How analog-labs/chain-connectors works
This repository is a Rust workspace that implements a Rosetta-based blockchain connector stack. The architecture is split into shared protocol crates, reusable client/server infrastructure, and chain-specific adapters under chains/.
1. Top-level shape
The workspace is not a single application; it is a set of libraries plus test/integration crates. The main runtime boundary is between the Rosetta layer and the upstream blockchain nodes it talks to over JSON-RPC and WebSocket.
2. Shared Rosetta protocol model
rosetta-types defines the request/response and domain structs used across the stack: blocks, transactions, operations, coins, identifiers, signatures, construction endpoints, and error types. This is the canonical wire/data model for Rosetta messages.
3. Shared traits and integration contracts
rosetta-core holds the common traits, node URI handling, and shared type definitions that let server and client implementations agree on behavior without depending on a specific chain. This is the main abstraction boundary for plugging in a chain implementation.
4. Generic Rosetta server layer
rosetta-server contains reusable server-side infrastructure. It includes WebSocket management, reconnect logic, retry strategies, and JSON-RPC client adapters. This crate is responsible for maintaining resilient connectivity to upstream nodes and feeding data into higher-level chain handlers.
5. Generic Rosetta client layer
rosetta-client is the consumer-side library for talking to a Rosetta server. It includes a client, wallet/mnemonic handling, transaction building, and signing support. This is the main entry point for SDK-style usage by applications or tests.
6. Cryptography and address handling
rosetta-crypto provides the key-management and encoding primitives used by the client stack: BIP32/BIP44 derivation plus address formats such as EIP-55, SS58, and Bech32. This crate sits on the signing/addressing path for supported chains.
7. Shared utilities
rosetta-utils contains cross-cutting helpers for futures, JSON-RPC integration, polling, circuit breaking, and serde conversions. It is supporting infrastructure used by both server and chain-specific code, especially where transport and serialization need consistent behavior.
8. Ethereum as the most fully split chain adapter
chains/ethereum is decomposed into:
- backend: low-level RPC/block-range helpers and JSON-RPC glue
- config: chain configuration and typed config data
- server: Rosetta server logic for Ethereum
- types: Ethereum-specific block, transaction, receipt, log, fee history, proof, and RPC models
- tx: transaction-related helpers
The Ethereum server is further split into stream-oriented components such as block streaming, finalized-block tracking, new-head handling, log/event filtering, shared stream state, and proof/state utilities. This suggests a pipeline from node data ingestion to Rosetta responses.
9. Polkadot adapter
chains/polkadot provides a chain-specific server and transaction module, plus config resources for Polkadot and Westend. The server has distinct call handling and per-chain implementations under src/chains/, showing that chain behavior is selected by network variant rather than a single generic implementation.
10. Astar adapter
chains/astar is split into config and server, with chain-specific resources under config/res. This follows the same pattern as Polkadot: a shared Rosetta-facing server backed by network-specific configuration and runtime behavior.
11. Other chain packages
chains/avalanche, chains/base, chains/binance, and chains/polygon are present as chain-specific crates or test harnesses. Their presence indicates the repo is organized around many chain integrations, but the depth of implementation varies by chain.
12. Testing and simulation
There are dedicated testing crates such as rosetta-docker, rosetta-chain-testing, chains/arbitrum/testing/rosetta-testing-arbitrum, and chain-specific server tests. rosetta-docker provides generic test infrastructure, while the scripts and Docker compose file support spinning up node dependencies for integration tests.
13. External dependencies and runtime boundaries
The primary external systems are blockchain nodes and local test nodes, accessed via JSON-RPC/WebSocket. The repo also depends on Docker for reproducible integration environments and uses CI plus linting/tooling (cargo, clippy, deny, dprint) to enforce workspace-wide correctness.
14. High-level data flow
Typical flow is: node RPC/WebSocket data enters the chain backend/server layers, gets normalized into chain-specific types, then mapped into Rosetta types and served through the generic server/client contract. In the opposite direction, construction and signing requests flow through rosetta-client, rosetta-crypto, and chain-specific transaction logic before being submitted to the node.
Main entry points: rosetta-types Rosetta types · server Eth server · rosetta-server Server infra · rosetta-client Client SDK
Components 19
Shared crates
Canonical Rosetta protocol, contracts, client SDK, crypto, and utilities.
- Rosetta types · Canonical Rosetta request/response and domain structs used across the workspace.
rosetta-types - Rosetta core · Shared traits, node URI handling, and cross-crate abstractions for chain plug-ins.
rosetta-core - Client SDK · Rosetta client, wallet, mnemonic, transaction building, and signing support.
rosetta-client - Crypto · BIP32/BIP44 derivation and address encoders such as EIP-55, SS58, and Bech32.
rosetta-crypto - Utilities · Cross-cutting helpers for futures, polling, circuit breaking, JSON-RPC, and serde.
rosetta-utils
Runtime infra
Reusable server-side connectivity and websocket handling.
- Server infra · Reusable websocket, reconnect, retry, and JSON-RPC client infrastructure for upstream nodes.
rosetta-server
Chain adapters
Chain-specific Rosetta adapters and major internal split points.
- Eth backend · Low-level Ethereum JSON-RPC helpers and block-range coordination.
chains/ethereum/backend - Eth types · Ethereum block, transaction, receipt, log, proof, fee history, and RPC data models.
chains/ethereum/types - Eth server · Ethereum Rosetta server logic that turns upstream data into Rosetta-facing responses.
chains/ethereum/server - Stream pipeline · Block, head, finalized-block, log, and event streaming plus shared stream state.
chains/ethereum/server/src - Eth tx · Ethereum transaction-related helpers and construction support.
chains/ethereum/tx - Eth config · Ethereum chain configuration and typed config data.
chains/ethereum/config - Polkadot server · Polkadot/Westend server implementation with chain-specific call handling and variants.
chains/polkadot/server - Polkadot tx · Polkadot transaction helpers and construction logic.
chains/polkadot/tx - Polkadot config · Polkadot and Westend network resources and configuration data.
chains/polkadot/config - Astar server · Astar Rosetta server backed by chain-specific configuration and runtime behavior.
chains/astar/server - Astar config · Astar network configuration and embedded resources.
chains/astar/config
Testing
Integration and Docker-based test harnesses.
- Chain testing · Workspace crates for node-backed integration testing across multiple chains.
chains/rosetta-chain-testing - Docker tests · Reusable Docker-oriented test infrastructure and local dependency setup.
rosetta-docker
Connections 23
- Rosetta core → Rosetta types: defines · Builds on the canonical Rosetta data model.
- Client SDK → Rosetta types: uses · Builds and interprets Rosetta messages.
- Client SDK → Crypto: signs with · Derives keys and encodes addresses for construction flows.
- Client SDK → Rosetta core: depends on · Relies on shared contracts and node URI handling.
- Server infra → Utilities: uses · Shares transport, serde, and polling helpers.
- Server infra → Rosetta core: depends on · Implements the shared chain/server contracts.
- Eth server → Server infra: uses · Builds on reusable websocket and reconnect infrastructure.
- Eth server → Eth backend: calls · Uses RPC glue and block-range helpers to ingest chain data.
- Eth server → Eth types: normalizes · Converts upstream Ethereum data into chain-specific models.
- Eth server → Rosetta types: maps to · Translates chain data into Rosetta protocol objects.
- Stream pipeline → Eth server: part of · Implements the main streaming and state pipeline inside the server.
- Eth tx → Rosetta types: builds · Supports transaction construction and Rosetta payload creation.
- Eth tx → Crypto: uses · Consumes signing and address primitives.
- Eth config → Eth server: configures · Supplies chain-specific parameters to Ethereum server behavior.
- Polkadot server → Server infra: uses · Depends on the generic upstream connectivity layer.
- Polkadot server → Rosetta types: maps to · Implements Rosetta behavior for Polkadot networks.
- Polkadot server → Polkadot config: reads · Selects network-specific configuration and resources.
- Polkadot tx → Rosetta types: builds · Creates Rosetta construction and transaction artifacts.
- Astar server → Server infra: uses · Depends on shared websocket and retry infrastructure.
- Astar server → Rosetta types: maps to · Serves Astar-specific Rosetta responses.
- Astar server → Astar config: reads · Uses embedded chain configuration and resources.
- Chain testing → Docker tests: uses · Runs integration scenarios against containerized node dependencies.
- Chain testing → Client SDK: drives · Exercises client-side construction and submission flows.