Skip to content

Relayer Service

High-performance blockchain transaction relay system for the KYAN platform. The Relayer Service handles secure transaction routing, Safe account management, and protocol deposit/withdrawal operations.

Architecture

The Relayer Service is built on a service-oriented architecture with dependency injection:

├── RelayerService (main orchestrator)
├── SafeService (Safe account management)
├── TransactionService (blockchain operations)
├── ValidationService (input validation)
└── EngineService (ThirdWeb engine integration)

Core Components

  • Hono Framework: Fast, lightweight HTTP server with middleware composition
  • Zod Validation: Type-safe schema validation for all inputs
  • Viem: Ethereum interaction library for blockchain operations
  • Safe Protocol Kit: Multi-signature wallet operations
  • ThirdWeb Engine: Managed transaction infrastructure

API Endpoints

Health Check

GET /health

Returns service health status and dependency checks.

Protocol Operations

Deposit

POST /deposit
Content-Type: application/json

{
  "from": "0x...",
  "to": "0x...",
  "amount": "1000000",
  "pair": "ETH/USDC",
  "signature": "0x...",
  "nonce": 123
}

Withdrawal

POST /withdraw
Content-Type: application/json

{
  "from": "0x...",
  "to": "0x...",
  "amount": "1000000",
  "pair": "ETH/USDC",
  "signature": "0x...",
  "nonce": 124
}

Service Architecture

RelayerService

Primary orchestrator that processes cloud events and coordinates other services:

  • Event validation and routing
  • Safe account creation
  • Transaction execution coordination
  • Error handling and response formatting

SafeService

Manages Safe multi-signature accounts:

  • Safe account creation and deployment
  • Multi-signature transaction management
  • Account security validation

TransactionService

Handles blockchain transactions:

  • Transaction construction and validation
  • Gas estimation and optimization
  • Transaction execution and monitoring

ValidationService

Provides input validation:

  • Schema-based validation using Zod
  • Cloud event validation
  • Protocol message validation

EngineService

ThirdWeb Engine integration:

  • Managed transaction processing
  • Queue management
  • Webhook handling for transaction status

Environment Configuration

Network Configuration

CHAIN_ID=421614                    # Blockchain network ID
RELAYER_CHAIN_ID=421614           # Chain ID for relayer
PRIVATE_HTTPS_RPC_URL=https://...  # HTTP RPC endpoint
PRIVATE_WSS_RPC_URL=wss://...     # WebSocket RPC endpoint

Service Configuration

RELAYER_PORT=3100                 # Service port
SERVICE_NAME=relayer:core         # Service identifier
ENV=local                         # Environment (local/dev/staging/prod)
NODE_ENV=development              # Node environment

Security Configuration

RELAYER_ACCOUNT=0x...             # Relayer Ethereum address
RELAYER_PRIVATE_KEY=0x...         # Relayer private key (dev only)
RELAYER_SAFE_SALT=55              # Salt for Safe generation

ThirdWeb Integration

RELAYER_TW_ACCESS_TOKEN=...       # ThirdWeb access token
RELAYER_TW_CLIENT_ID=...          # ThirdWeb client ID
RELAYER_TW_ENGINE_URL=...         # ThirdWeb engine URL

Contract Addresses

CLEARING_HOUSE_PXY=0x...          # ClearingHouse proxy
EXCHANGE_INFO_PXY=0x...           # ExchangeInfo proxy

Feature Flags

ENGINE_ENABLED=false              # Enable ThirdWeb engine
BREAKER_ENABLED=false             # Enable circuit breaker
METRICS_ENABLED=false             # Enable metrics collection

Development

Prerequisites

  • Node.js ≥22.6.0
  • Yarn ≥4.0.0
  • Bun (optional, for enhanced performance)

Local Development

# Install dependencies
yarn install

# Start development server
nx serve relayer

# Start with hot reload
yarn dev

# Run tests
nx test relayer

# Run linting
nx lint relayer

# Build for production
nx build relayer

Testing

# Unit tests
nx test relayer

# Integration tests
vitest run --config apps/relayer/vitest.config.ts

# Test coverage
vitest run --coverage

# Test UI
vitest --ui

Docker Deployment

Build Image

docker build -t premia/relayer:latest -f apps/relayer/Dockerfile .

Run Container

docker run -p 3100:3100 \
  -e RELAYER_RPC_URL=https://your-rpc-endpoint \
  -e RELAYER_PORT=3100 \
  -e NODE_ENV=production \
  -e LOG_LEVEL=info \
  premia/relayer:latest

Health Check

The container includes automatic health checks via /health endpoint:

docker inspect --format='{{json .State.Health}}' <container_id>

Production Deployment

Google Cloud Run

The service is configured for Cloud Run deployment with:

  • Automatic scaling based on request volume
  • Environment variables managed via Terraform
  • Health checks and monitoring integration
  • Secure secrets management

Monitoring

  • Health Checks: Continuous service health monitoring
  • Metrics: Performance and usage metrics collection
  • Logging: Structured logging with configurable levels
  • Error Tracking: Comprehensive error handling and reporting

Error Handling

The service implements a comprehensive error handling system:

  • RelayerErrorV2: Structured error class with error codes
  • Validation Errors: Schema validation failures
  • Network Errors: Blockchain connectivity issues
  • Service Errors: Internal service failures

Error responses follow a consistent format:

{
  "success": false,
  "error": {
    "message": "Error description",
    "details": {...},
    "code": 400
  }
}

Security

Best Practices

  • Private keys stored securely (never in code)
  • Input validation on all endpoints
  • Rate limiting and circuit breakers
  • Secure environment variable management
  • Multi-signature wallet integration

Authentication

  • API key validation middleware
  • Request signing validation
  • Nonce-based replay protection

Performance

Optimizations

  • Connection pooling for RPC calls
  • Request/response caching
  • Batch transaction processing
  • Circuit breaker patterns for fault tolerance

Monitoring

  • Response time tracking
  • Error rate monitoring
  • Resource utilization metrics
  • Transaction queue monitoring

Contributing

  1. Follow the established service architecture patterns
  2. Add comprehensive tests for new functionality
  3. Update documentation for API changes
  4. Ensure proper error handling implementation
  5. Validate all environment configurations

Support

For issues and questions:

This documentation is generated from the service README. For the most up-to-date information, refer to the original README