How openzeppelin/openzeppelin-relayer works
Main Components
• Clients: Represent external systems or SDKs that interact via HTTP APIs.
• API Layer: Shows the exposed endpoints, controllers, and middleware (located in src/api).
• Domain Layer: Captures core business logic including transaction relaying, nonce management, and policy enforcement (see src/domain, src/config, and src/bootstrap).
• Infrastructure: Consists of repositories (data storage and state management, distributed through Redis), job queue handlers (for asynchronous processing in src/jobs), signer services (both local and Vault-based implementations) and provider components (for connecting with blockchain nodes).
• Services Layer: Encompasses transaction services, notification (webhook) modules, metrics/monitoring integrations, and vault services.
• Configuration: Covers configuration files (in config/ and env files) and environment variables, which are used to drive the behavior of the system.
• External Systems: Includes blockchain networks (Solana, EVM), external caches or databases (Redis), external key managers (Vault), monitoring systems (Prometheus/Grafana), and notification endpoints.
Relationships & Interactions
• Clients send HTTP requests to the API endpoints.
• The API Layer (routes and controllers) processes requests and delegates responsibility to middleware, which then routes to the Domain Layer.
• The Domain Layer orchestrates the transaction relay logic and policy enforcement using the integrated relayer services.
• The Infrastructure interacts with the Domain, providing persistent storage, job queuing, and external signing capabilities.
• The Services layer handles critical functions like transaction signing (which may refer to both local signing and Vault integrations), fee estimation, and notifications via webhooks.
• Configuration components (config files/environment variables) feed critical parameters to each layer.
• Data flows include requests from clients going through the API, business logic in the Domain communicating with Infrastructure services, while also sending jobs to the queue and interacting with external systems like blockchains and metrics collectors.
Architectural Patterns & Design Principles
• Layered architecture: Separation between API, Domain, Infrastructure, and Services.
• Modularity: Each folder under src (controllers, domain, repositories, services, etc.) encapsulates a distinct concern.
• Extensibility: The project is designed to support multiple networks and signing strategies; each can be visualized as separate modules that inject dependencies into the core relayer workflow.
• Asynchronous Processing: The jobs subcomponent works with Redis (as indicated by the docker-compose and external Redis container) to manage asynchronous operations.
• Observability: A dedicated metrics component is integrated which is driven via Prometheus/Grafana.
Detailing the Architecture
• The "src/api" directory corresponds to API endpoints and controllers.
• The "src/domain" and "src/models" directories represent the core business logic and data types.
• The "src/repositories" and "src/jobs" directories form the persistence and asynchronous processing layers.
• The "src/services" directory covers various integrations (gas pricing, notification, signer interfaces) and should be visibly separated.
• The "config" and environment (".env") files are critical for configuration management.
• Minor components (like helper scripts from the "helpers" directory or the "docs" and "examples" directories) as annotations if they influence deployment or operational behavior—but keep the primary focus on runtime architecture.
Final Recommendations
• Every component has a label that reflects the folder path (e.g., “src/services/signer/evm”).
• Extensibility of modules (for adding new networks or signing mechanisms) by grouping related components together.