# analog-labs/chain-connectors architecture

> Architecture diagram of the GitHub repository analog-labs/chain-connectors, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/analog-labs/chain-connectors
- Repository: https://github.com/analog-labs/chain-connectors

## Overview

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`](https://github.com/analog-labs/chain-connectors/tree/master/rosetta-types) (Rosetta types), [`chains/ethereum/server`](https://github.com/analog-labs/chain-connectors/tree/master/chains/ethereum/server) (Eth server), [`rosetta-server`](https://github.com/analog-labs/chain-connectors/tree/master/rosetta-server) (Server infra), [`rosetta-client`](https://github.com/analog-labs/chain-connectors/tree/master/rosetta-client) (Client SDK)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_shared["Shared crates"]
  node_rosetta_types["Rosetta types<br/>protocol model"]
  node_rosetta_core["Rosetta core<br/>traits + contracts"]
  node_rosetta_client["Client SDK<br/>consumer client"]
  node_rosetta_crypto["Crypto<br/>keys + addresses"]
  node_rosetta_utils["Utilities<br/>support library"]
end

subgraph group_infra["Runtime infra"]
  node_rosetta_server["Server infra<br/>transport layer"]
end

subgraph group_chains["Chain adapters"]
  node_ethereum_backend["Eth backend<br/>rpc glue"]
  node_ethereum_types["Eth types<br/>chain models"]
  node_ethereum_server["Eth server<br/>Rosetta adapter"]
  node_ethereum_streams["Stream pipeline<br/>ingest flow"]
  node_ethereum_tx["Eth tx<br/>tx helpers"]
  node_ethereum_config["Eth config<br/>chain config"]
  node_polkadot_server["Polkadot server<br/>Rosetta adapter"]
  node_polkadot_tx["Polkadot tx<br/>tx helpers"]
  node_polkadot_config["Polkadot config<br/>chain config"]
  node_astar_server["Astar server<br/>Rosetta adapter"]
  node_astar_config["Astar config<br/>chain config"]
end

subgraph group_testing["Testing"]
  node_chain_testing["Chain testing<br/>integration crates"]
  node_rosetta_docker["Docker tests<br/>test harness"]
end

node_rosetta_core -->|"defines"| node_rosetta_types
node_rosetta_client -->|"uses"| node_rosetta_types
node_rosetta_client -->|"signs with"| node_rosetta_crypto
node_rosetta_client -->|"depends on"| node_rosetta_core
node_rosetta_server -->|"uses"| node_rosetta_utils
node_rosetta_server -->|"depends on"| node_rosetta_core
node_ethereum_server -->|"uses"| node_rosetta_server
node_ethereum_server -->|"calls"| node_ethereum_backend
node_ethereum_server -->|"normalizes"| node_ethereum_types
node_ethereum_server -->|"maps to"| node_rosetta_types
node_ethereum_streams -->|"part of"| node_ethereum_server
node_ethereum_tx -->|"builds"| node_rosetta_types
node_ethereum_tx -->|"uses"| node_rosetta_crypto
node_ethereum_config -->|"configures"| node_ethereum_server
node_polkadot_server -->|"uses"| node_rosetta_server
node_polkadot_server -->|"maps to"| node_rosetta_types
node_polkadot_server -->|"reads"| node_polkadot_config
node_polkadot_tx -->|"builds"| node_rosetta_types
node_astar_server -->|"uses"| node_rosetta_server
node_astar_server -->|"maps to"| node_rosetta_types
node_astar_server -->|"reads"| node_astar_config
node_chain_testing -->|"uses"| node_rosetta_docker
node_chain_testing -->|"drives"| node_rosetta_client

click node_rosetta_types "https://github.com/analog-labs/chain-connectors/tree/master/rosetta-types"
click node_rosetta_core "https://github.com/analog-labs/chain-connectors/tree/master/rosetta-core"
click node_rosetta_client "https://github.com/analog-labs/chain-connectors/tree/master/rosetta-client"
click node_rosetta_crypto "https://github.com/analog-labs/chain-connectors/tree/master/rosetta-crypto"
click node_rosetta_utils "https://github.com/analog-labs/chain-connectors/tree/master/rosetta-utils"
click node_rosetta_server "https://github.com/analog-labs/chain-connectors/tree/master/rosetta-server"
click node_ethereum_backend "https://github.com/analog-labs/chain-connectors/tree/master/chains/ethereum/backend"
click node_ethereum_types "https://github.com/analog-labs/chain-connectors/tree/master/chains/ethereum/types"
click node_ethereum_server "https://github.com/analog-labs/chain-connectors/tree/master/chains/ethereum/server"
click node_ethereum_streams "https://github.com/analog-labs/chain-connectors/tree/master/chains/ethereum/server/src"
click node_ethereum_tx "https://github.com/analog-labs/chain-connectors/tree/master/chains/ethereum/tx"
click node_ethereum_config "https://github.com/analog-labs/chain-connectors/tree/master/chains/ethereum/config"
click node_polkadot_server "https://github.com/analog-labs/chain-connectors/tree/master/chains/polkadot/server"
click node_polkadot_tx "https://github.com/analog-labs/chain-connectors/tree/master/chains/polkadot/tx"
click node_polkadot_config "https://github.com/analog-labs/chain-connectors/tree/master/chains/polkadot/config"
click node_astar_server "https://github.com/analog-labs/chain-connectors/tree/master/chains/astar/server"
click node_astar_config "https://github.com/analog-labs/chain-connectors/tree/master/chains/astar/config"
click node_chain_testing "https://github.com/analog-labs/chain-connectors/tree/master/chains/rosetta-chain-testing"
click node_rosetta_docker "https://github.com/analog-labs/chain-connectors/tree/master/rosetta-docker"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_rosetta_types,node_rosetta_core,node_rosetta_client,node_rosetta_crypto,node_rosetta_utils toneBlue
class node_rosetta_server toneAmber
class node_ethereum_backend,node_ethereum_types,node_ethereum_server,node_ethereum_streams,node_ethereum_tx,node_ethereum_config,node_polkadot_server,node_polkadot_tx,node_polkadot_config,node_astar_server,node_astar_config toneMint
class node_chain_testing,node_rosetta_docker toneRose
```

## Components

### Shared crates

Canonical Rosetta protocol, contracts, client SDK, crypto, and utilities.

- [Rosetta types](https://github.com/analog-labs/chain-connectors/tree/master/rosetta-types): protocol model · Canonical Rosetta request/response and domain structs used across the workspace. · `rosetta-types`
- [Rosetta core](https://github.com/analog-labs/chain-connectors/tree/master/rosetta-core): traits + contracts · Shared traits, node URI handling, and cross-crate abstractions for chain plug-ins. · `rosetta-core`
- [Client SDK](https://github.com/analog-labs/chain-connectors/tree/master/rosetta-client): consumer client · Rosetta client, wallet, mnemonic, transaction building, and signing support. · `rosetta-client`
- [Crypto](https://github.com/analog-labs/chain-connectors/tree/master/rosetta-crypto): keys + addresses · BIP32/BIP44 derivation and address encoders such as EIP-55, SS58, and Bech32. · `rosetta-crypto`
- [Utilities](https://github.com/analog-labs/chain-connectors/tree/master/rosetta-utils): support library · 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](https://github.com/analog-labs/chain-connectors/tree/master/rosetta-server): transport layer · 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](https://github.com/analog-labs/chain-connectors/tree/master/chains/ethereum/backend): rpc glue · Low-level Ethereum JSON-RPC helpers and block-range coordination. · `chains/ethereum/backend`
- [Eth types](https://github.com/analog-labs/chain-connectors/tree/master/chains/ethereum/types): chain models · Ethereum block, transaction, receipt, log, proof, fee history, and RPC data models. · `chains/ethereum/types`
- [Eth server](https://github.com/analog-labs/chain-connectors/tree/master/chains/ethereum/server): Rosetta adapter · Ethereum Rosetta server logic that turns upstream data into Rosetta-facing responses. · `chains/ethereum/server`
- [Stream pipeline](https://github.com/analog-labs/chain-connectors/tree/master/chains/ethereum/server/src): ingest flow · Block, head, finalized-block, log, and event streaming plus shared stream state. · `chains/ethereum/server/src`
- [Eth tx](https://github.com/analog-labs/chain-connectors/tree/master/chains/ethereum/tx): tx helpers · Ethereum transaction-related helpers and construction support. · `chains/ethereum/tx`
- [Eth config](https://github.com/analog-labs/chain-connectors/tree/master/chains/ethereum/config): chain config · Ethereum chain configuration and typed config data. · `chains/ethereum/config`
- [Polkadot server](https://github.com/analog-labs/chain-connectors/tree/master/chains/polkadot/server): Rosetta adapter · Polkadot/Westend server implementation with chain-specific call handling and variants. · `chains/polkadot/server`
- [Polkadot tx](https://github.com/analog-labs/chain-connectors/tree/master/chains/polkadot/tx): tx helpers · Polkadot transaction helpers and construction logic. · `chains/polkadot/tx`
- [Polkadot config](https://github.com/analog-labs/chain-connectors/tree/master/chains/polkadot/config): chain config · Polkadot and Westend network resources and configuration data. · `chains/polkadot/config`
- [Astar server](https://github.com/analog-labs/chain-connectors/tree/master/chains/astar/server): Rosetta adapter · Astar Rosetta server backed by chain-specific configuration and runtime behavior. · `chains/astar/server`
- [Astar config](https://github.com/analog-labs/chain-connectors/tree/master/chains/astar/config): chain config · Astar network configuration and embedded resources. · `chains/astar/config`

### Testing

Integration and Docker-based test harnesses.

- [Chain testing](https://github.com/analog-labs/chain-connectors/tree/master/chains/rosetta-chain-testing): integration crates · Workspace crates for node-backed integration testing across multiple chains. · `chains/rosetta-chain-testing`
- [Docker tests](https://github.com/analog-labs/chain-connectors/tree/master/rosetta-docker): test harness · Reusable Docker-oriented test infrastructure and local dependency setup. · `rosetta-docker`

## Connections

- 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.