How concordium/concordium-rust-sdk works
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.