# concordium/concordium-rust-sdk architecture

> Architecture diagram of the GitHub repository concordium/concordium-rust-sdk, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/concordium/concordium-rust-sdk
- Repository: https://github.com/concordium/concordium-rust-sdk

## Overview

##### Project type and purpose
- This is a Rust SDK library (concordium-rust-sdk) whose purpose is to provide a type-safe, ergonomic API for constructing, signing, and sending transactions to a Concordium blockchain node, as well as querying chain and node state.
- It supports both the legacy V1 gRPC API (via `endpoints`) and the newer, more efficient V2 API (via the `v2` module). It also includes a small code-generation tool (`proto-generate`) that updates the embedded protobuf definitions.

##### File structure
- Top-level directories:
- `src/` – main library code
- `examples/` – runnable example programs demonstrating SDK usage
- `proto-generate/` – a separate binary crate for regenerating the gRPC bindings
- `src/` layout:
- Core modules: `client` (`contract_client.rs`), `endpoints.rs`, `indexer.rs`, `internal.rs`, `signatures.rs`, `web3id.rs`
- API split: `v2/` subdirectory (with generated protobuf code under `v2/generated`), and the V1 API surfaced under `endpoints` and `internal`
- Smart contract helpers under `smart_contracts/` and CIS standards under `cis0.rs`, `cis2/`, `cis3.rs`, `cis4.rs`
- Data models under `types/` (block certificates, transactions, queries, network, smart contracts)
- Configs and meta-files: `Cargo.toml`, `rustfmt.toml`, GitHub workflows in `.github/workflows`, `.gitmodules` for submodules, `CHANGELOG.md`, `LICENSE`.

##### README for additional insights
- Confirms the split between V1 and V2 APIs, deprecation timeline for V1, and focuses on the `Client` abstraction in V2.
- Notes that protobuf schema updates are handled by the `proto-generate` crate and committed directly into the repo.
- Examples use Tokio for async execution and show typical patterns: build transaction → sign → send_block_item.

##### Main components
a. SDK Library (crate)
- Core Library Modules (client, endpoints, indexer, internal, signatures, web3id)
- Data Models (`types`)
- Smart Contract Helpers (`smart_contracts`, `cis*`)
- Versioned API layers: V1 (`endpoints`) and V2 (`v2/*`)
- Code-gen tool: `proto-generate` binary (runs at dev time, outputs protobuf code under `v2/generated`)
b. External Systems
- Concordium Node gRPC API V1
- Concordium Node gRPC API V2
- User Application (any Rust app that depends on this SDK)
c. Example Programs
- Drive usage of SDK; show typical flows (e.g., `v2_send_transfer.rs`)
d. Build and CI
- Cargo build → compiles SDK + examples
- GitHub Actions workflow (`build-and-test.yaml`)

##### Relationships and data flows
- Developer invokes `proto-generate` → regenerates `.rs` in `v2/generated`.
- At compile time:
- SDK crate compiles and embeds generated protobuf code.
- Examples link against SDK crate.
- At runtime:
- User App or Example → instantiate `v2::Client` → sends gRPC/HTTP calls to Concordium Node V2 endpoint.
- For legacy uses: calls into `endpoints` module → gRPC V1.
- Data flows back as typed Rust structs (in `types/`).
- Signing modules (`signatures.rs`) handle cryptographic signing before send.
- Indexer component (`indexer.rs`) may query specialized endpoints (e.g., to list transactions, balances).

##### Architectural patterns and design principles
- Layered architecture:
- Transport layer (gRPC clients)
- API abstraction (Client)
- Domain models (types)
- Utility modules (signatures, internal helpers)
- Examples as thin clients
- Separation of concerns: code generation is isolated in a separate crate, runtime code does not depend on `prost` or `tonic` directly.
- Feature flags (if any) can toggle between V1 and V2 support.
- Async execution model with Tokio.

## Diagram (Mermaid)

```mermaid
flowchart TD
  subgraph "Code Generation (Compile-time)"
    proto_gen["proto-generate Tool"]:::compile
    v2_generated["v2/generated (protobuf)"]:::compile
    proto_gen -->|"generates protobuf code"| v2_generated
  end

  subgraph "Rust SDK Internals"
    subgraph "Versioned API Layers"
      subgraph "V2 API Layer"
        v2_mod["v2 mod"]:::runtime
        v2_conv["conversions"]:::runtime
        v2_dry["dry_run"]:::runtime
        v2_schema["proto_schema_version"]:::runtime
        v2_gen["generated bindings"]:::runtime
        v2_mod --> v2_conv
        v2_mod --> v2_dry
        v2_mod --> v2_schema
        v2_mod --> v2_gen
      end
      subgraph "V1 API (Legacy)"
        endpoints["endpoints"]:::runtime
        internal["internal"]:::runtime
      end
    end

    contract_client["Client Abstraction"]:::runtime
    indexer["Indexer Module"]:::runtime
    signatures["Signatures Module"]:::runtime
    web3id["Web3ID Integration"]:::runtime

    subgraph "Data Models"
      types["types"]:::runtime
    end

    subgraph "Smart Contract Helpers"
      cis0["CIS0"]:::runtime
      cis2["CIS2"]:::runtime
      cis3["CIS3"]:::runtime
      cis4["CIS4"]:::runtime
      smart_contracts_mod["smart_contracts mod"]:::runtime
      smart_contracts_mod --> cis0
      smart_contracts_mod --> cis2
      smart_contracts_mod --> cis3
      smart_contracts_mod --> cis4
    end

    contract_client -->|"uses V2 API"| v2_mod
    contract_client -->|"uses V1 API"| endpoints
    contract_client -->|"signs using"| signatures
    contract_client -->|"identity via"| web3id
    endpoints -->|"returns data as"| types
    v2_mod -->|"returns data as"| types
    indexer -->|"queries via"| internal
    indexer -->|"returns data as"| types
  end

  subgraph "Example Applications / User Apps"
    examples["Examples & User App"]:::examples
    examples -->|"calls Client"| contract_client
  end

  subgraph "Concordium Node APIs"
    nodeV1["Concordium Node API V1"]:::external
    nodeV2["Concordium Node API V2"]:::external
  end

  contract_client -->|"gRPC V1 calls"| nodeV1
  v2_mod -->|"gRPC V2 calls"| nodeV2

  classDef compile fill:#a8d0e6,stroke:#000;
  classDef runtime fill:#c3e2a8,stroke:#000;
  classDef external fill:#f7bea1,stroke:#000;
  classDef examples fill:#d3d3d3,stroke:#000;

  click proto_gen "https://github.com/concordium/concordium-rust-sdk/blob/main/proto-generate/src/main.rs"
  click v2_generated "https://github.com/concordium/concordium-rust-sdk/blob/main/src/v2/generated/concordium.v2.rs"
  click v2_mod "https://github.com/concordium/concordium-rust-sdk/blob/main/src/v2/mod.rs"
  click v2_conv "https://github.com/concordium/concordium-rust-sdk/blob/main/src/v2/conversions.rs"
  click v2_dry "https://github.com/concordium/concordium-rust-sdk/blob/main/src/v2/dry_run.rs"
  click v2_schema "https://github.com/concordium/concordium-rust-sdk/blob/main/src/v2/proto_schema_version.rs"
  click endpoints "https://github.com/concordium/concordium-rust-sdk/blob/main/src/endpoints.rs"
  click internal "https://github.com/concordium/concordium-rust-sdk/blob/main/src/internal.rs"
  click contract_client "https://github.com/concordium/concordium-rust-sdk/blob/main/src/contract_client.rs"
  click indexer "https://github.com/concordium/concordium-rust-sdk/blob/main/src/indexer.rs"
  click signatures "https://github.com/concordium/concordium-rust-sdk/blob/main/src/signatures.rs"
  click web3id "https://github.com/concordium/concordium-rust-sdk/blob/main/src/web3id.rs"
  click types "https://github.com/concordium/concordium-rust-sdk/tree/main/src/types/"
  click cis0 "https://github.com/concordium/concordium-rust-sdk/blob/main/src/cis0.rs"
  click cis2 "https://github.com/concordium/concordium-rust-sdk/blob/main/src/cis2/mod.rs"
  click cis3 "https://github.com/concordium/concordium-rust-sdk/blob/main/src/cis3.rs"
  click cis4 "https://github.com/concordium/concordium-rust-sdk/blob/main/src/cis4.rs"
  click smart_contracts_mod "https://github.com/concordium/concordium-rust-sdk/blob/main/src/smart_contracts/mod.rs"
  click examples "https://github.com/concordium/concordium-rust-sdk/tree/main/examples/"
```
