TES - Trusted Encryption Service

A NestJS-based trusted encryption service for the Zeroledger ecosystem, providing encryption/decryption capabilities, blockchain event indexing, and paymaster services.

Features

• Challenge Authentication: Wallet-based authentication system
• Encryption Service: Secure data encryption and decryption with wallet-based authentication
• Paymaster Service: Gas fee sponsorship and transaction execution
• User Metadata Management: User data storage and retrieval
• Sync Service: Service for fast commitments synchronization
• Blockchain Indexer: Real-time event indexing from EVM-compatible blockchains with pub-sub model
• Points Service: Track and update points for users based on onchain activity
• Swagger API Documentation: Interactive API documentation at /api endpoint

Technologies

• NestJS with TypeScript and SWC
• MongoDB with Mongoose for data persistence
• Viem for EVM blockchain interactions
• Jest for unit and e2e testing
• Docker & Docker Compose for development & production
• Swagger for API documentation
• Zod for runtime type validation
• Linters, code formatter, pre-commit and pre-push hooks
• Custom GitHub Actions and quality gate workflow for CI/CD
• Flexible environment configuration with encryption via dotenvx

Requirements

• Git
  • You'll know you've done it right if you can run git --version
• Node.js v20.11.0+
• Docker

API Documentation

Interactive API documentation is available at /api endpoint when the service is running.

Main Endpoints

• Encryption: /encryption - Data encryption and decryption services
• Indexer: /indexer - Blockchain event indexing and retrieval
• Paymaster: /paymaster - Gas fee sponsorship and transaction execution
• Challenge: /challenge - Authentication challenge generation
• User Metadata: /userMetadata - User data management
• Health: /health - Service health check

Installation

npm install

Configuration

Environment Setup

The service requires configuration via environment files in the conf/ directory. All environment variables are documented with comments and mock values in the example files.

Local Development

1. Create and modify .env file in conf folder:

   cp conf/.example.env conf/.env

2. Update the configuration values in conf/.env:

   • PORT: Service port (default: 3000)
   • DB_URI: MongoDB connection string
   • ENCRYPTION_PK: Encryption private key
   • PAYMASTER_PK: Paymaster private key
   • NETWORK: EVM network name (e.g., "baseSepolia")
   • START_BLOCK: Block number to start indexing from
   • VAULT_CONTRACT: Vault contract address
   • FORWARDER_CONTRACT: Forwarder contract address
   • WS_RPC: WebSocket RPC endpoint
   • RPC: HTTP RPC endpoint
   • ORIGIN: Allowed CORS origin
   • CMC_API_KEY: CoinMarketCap API key for gas estimation

Production Environment

1. Create production secrets file:

   cp conf/.example.env conf/.prod.secrets.env

2. Update production values in conf/.prod.secrets.env

3. Encrypt production secrets:

   npm run env:encrypt

   Note: The generated .prod.secrets.env file can be publicly shared after encryption.

4. Keep the generated .env.keys file secure and do not commit it to the repository.

Authentication

The service uses wallet-based authentication:

1. Client requests a challenge number from GET /challenge endpoint
2. Client signs the challenge with their wallet
3. Client includes the auth jwt in subsequent authenticated requests via cookies & csrf header

Running

Local Development

# Development mode with hot reload
npm run dev

Docker Development

# Development mode with Docker (includes MongoDB)
npm run up.dev

Production

# Build the application
npm run build

# Start the application
npm start

Testing

# Run e2e tests
npm run test.e2e

# Run unit tests
npm test

# Run linting
npm run lint

# Type checking
npm run typecheck

Development Scripts

• npm run dev - Start development server with hot reload
• npm run up.dev - Start with Docker Compose (includes MongoDB)
• npm run build - Build for production
• npm start - Start production server
• npm test - Run unit tests
• npm run test.e2e - Run end-to-end tests
• npm run lint - Run ESLint with auto-fix
• npm run typecheck - Run TypeScript type checking
• npm run clean - Clean build artifacts and databases
• npm run env:encrypt - Encrypt production environment variables

Project Structure

src/
├── app.module.ts              # Main application module
├── main.ts                    # Application bootstrap
├── challenge/                 # Authentication challenge system
├── core/                      # Core functionality
├── encryption/                # Encryption/decryption services
├── health/                    # Health check endpoints
├── indexer/                   # Blockchain event indexing
├── paymaster/                 # Gas fee sponsorship
├── points/                    # Points tracker
├── sync/                      # Commitments fast sync service
└── userMetadata/              # User metadata management

Contributing

Contributions are always welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass
6. Submit a pull request

License

See LICENSE file for details.

Support

• Open an issue for bug reports
• Check the API documentation when the service is running