# sourcenetwork/orbis-rs architecture

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

- Interactive diagram: https://gitdiagram.com/sourcenetwork/orbis-rs
- Repository: https://github.com/sourcenetwork/orbis-rs

## Overview

1. This is a Rust workspace centered on a threshold-cryptography system. The top-level split is between reusable libraries under `crates/` and runnable binaries under `bin/`: `orbis-node` is the ring participant, and `cli-tool` is the operator/client entrypoint.

2. The runtime architecture has three main planes:
   - a **gRPC control plane** exposed by each node,
   - a **peer-to-peer MPC plane** between nodes for DKG/PRE/signing messages,
   - a **chain-backed metadata/policy plane** used for bulletin-board state and authorization decisions.
   The README’s deployment diagram matches this: clients talk to nodes via gRPC, nodes talk to each other via QUIC/iROH, and nodes also consult SourceHub-based chain services.

3. `bin/orbis-node` is the core subsystem. It bundles the node’s gRPC services, MPC coordinators, protocol handlers, and storage. Its module layout shows the major feature areas directly: `dkg`, `pre`, `sign`, `store_secret`, `info`, `pss`, plus shared `helpers`, `runtime`, `metrics`, and `ring_state`.

4. Each cryptographic protocol is versioned and isolated behind its own `v0` subtree, with a consistent internal shape:
   - `service` for the external gRPC-facing API,
   - `protocol_handler` for inbound message routing,
   - `coordinator` for the state machine and peer orchestration,
   - `messages` / `response_state` / `error` for protocol data and state.
   This makes the protocol boundary explicit: transport and request handling stay separate from the cryptographic ceremony logic.

5. The DKG implementation is the most elaborate coordinator subsystem. Under `bin/orbis-node/src/dkg/v0/`, it is further broken into state-machine phases, message handlers, peer/ring bookkeeping, reshare logic, refresh health checks, and ring storage. That indicates DKG is not just a one-shot request; it manages long-lived ceremony state, member selection, and ring lifecycle changes.

6. PRE and signing follow the same distributed pattern but with different internal choreography:
   - `pre/v0` has initiator, verification, handlers, network, and response state, reflecting a request/response workflow for re-encryption.
   - `sign/v0` has nonce and signing rounds plus verification, indicating an interactive threshold-signing flow.
   These modules rely on peer messaging between ring nodes rather than only local computation.

7. `crates/crypto` is the cryptographic engine layer. It defines the protocol traits for DKG, threshold re-encryption, polynomial commitments, and generic crypto serialization/deserialization. The crate supports multiple curve families via features, with BLS12-381 as the default and decaf377 as an alternate implementation. This is a key architectural boundary: the node protocol code depends on abstract traits, not on one hard-coded curve.

8. `crates/network` is the transport abstraction for node-to-node communication. It wraps QUIC-based Iroh networking behind traits like `Network`, `Connection`, `ProtocolHandler`, and `Router`. The node’s MPC coordinators depend on this layer for peer discovery, routing, and incoming protocol dispatch, which keeps transport concerns separate from protocol logic.

9. `crates/local-storage` is the persistence boundary for node secrets. It provides an encrypted key-value interface with interchangeable backends: `redb` for persistent storage and `memory` for tests. The README notes AES-256-GCM plus Argon2-derived keys, so this crate is responsible for protecting stored private material rather than exposing raw secrets to the rest of the system.

10. `crates/authn`, `crates/authz`, `crates/bulletin`, and `crates/common` form the chain-integrated support layer. `authn` handles JWT / did:key verification, `authz` performs policy checks, `bulletin` writes or reads bulletin-board state, and `common` contains the shared SourceHub blockchain client, config, signer, and test harnesses. Both `authz` and `bulletin` depend on `common`, which is the shared chain-access boundary.

11. `crates/proto` defines the gRPC surface for the whole system. Its generated types cover DKG, PRE, info, sign, store-secret, and unsafe-testing services. This crate is the contract layer between `cli-tool` / external callers and the node’s service implementations.

12. The repo is intentionally backend-swappable via Cargo features. The major choice points are crypto curve, network backend, local storage backend, authz backend, and bulletin backend. That means architecture diagrams should show abstract subsystems with replaceable implementations, not a single fixed technology stack.

13. Observability and test infrastructure are first-class parts of the architecture. The node exports metrics, and the repository includes Docker Compose setups for multi-node integration testing plus Prometheus/Grafana dashboards. The presence of `unsafe_testing` and extensive protocol-specific tests also suggests a strong separation between production protocol paths and test-only control surfaces.

14. At a high level, the main data flow is: a client requests an operation through gRPC, the node validates and routes it, the protocol coordinator exchanges MPC messages with peers over Iroh/QUIC, secrets or metadata are persisted through encrypted local storage and/or bulletin-board interactions, and the resulting public outputs or aggregated signatures are returned through the service layer.

Main entry points: [`bin/orbis-node`](https://github.com/sourcenetwork/orbis-rs/tree/develop/bin/orbis-node) (Orbis node), [`bin/orbis-node/src/dkg`](https://github.com/sourcenetwork/orbis-rs/tree/develop/bin/orbis-node/src/dkg) (DKG), [`crates/bulletin`](https://github.com/sourcenetwork/orbis-rs/tree/develop/crates/bulletin) (Bulletin), [`bin/orbis-node/src/pre`](https://github.com/sourcenetwork/orbis-rs/tree/develop/bin/orbis-node/src/pre) (PRE)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_binaries["Binaries"]
  node_cli_tool["CLI tool<br/>operator client"]
end

subgraph group_node["Node runtime"]
  node_orbis_node["Orbis node<br/>runtime binary"]
  node_node_runtime["Runtime<br/>app core<br/>[runtime.rs]"]
  node_node_helpers["Helpers<br/>node glue"]
end

subgraph group_protocols["Protocol subsystems"]
  node_dkg{{"DKG<br/>threshold ceremony"}}
  node_pre{{"PRE<br/>threshold reencryption"}}
  node_sign{{"Signing"}}
  node_store_secret["Store secret<br/>secret service"]
  node_info["Info<br/>status service"]
  node_unsafe_testing["Unsafe testing<br/>test service"]
end

subgraph group_shared["Shared crates"]
  node_crypto{{"Crypto<br/>protocol engine"}}
  node_network[("Network<br/>p2p transport")]
  node_local_storage[("Local storage<br/>encrypted KV")]
  node_proto["Proto<br/>grpc contract"]
  node_authn["AuthN<br/>jwt/did:key"]
  node_authz["AuthZ<br/>policy engine"]
  node_bulletin["Bulletin"]
  node_common["Common<br/>chain client"]
end

subgraph group_infra["Infra"]
  node_node_metrics(("Metrics<br/>telemetry<br/>[metrics.rs]"))
end

node_cli_tool -->|"calls"| node_proto
node_cli_tool -->|"invokes"| node_orbis_node
node_orbis_node -->|"boots"| node_node_runtime
node_orbis_node -->|"uses"| node_node_helpers
node_orbis_node -->|"exports"| node_node_metrics
node_orbis_node -->|"hosts"| node_dkg
node_orbis_node -->|"hosts"| node_pre
node_orbis_node -->|"hosts"| node_sign
node_orbis_node -->|"hosts"| node_store_secret
node_orbis_node -->|"hosts"| node_info
node_orbis_node -->|"hosts"| node_unsafe_testing
node_dkg -->|"depends on"| node_crypto
node_pre -->|"depends on"| node_crypto
node_sign -->|"depends on"| node_crypto
node_dkg -->|"peers via"| node_network
node_pre -->|"peers via"| node_network
node_sign -->|"peers via"| node_network
node_store_secret -->|"persists to"| node_local_storage
node_orbis_node -->|"implements"| node_proto
node_orbis_node -->|"validates"| node_authn
node_orbis_node -->|"authorizes"| node_authz
node_orbis_node -->|"reads/writes"| node_bulletin
node_authz -->|"uses"| node_common
node_bulletin -->|"uses"| node_common
node_dkg -->|"updates"| node_bulletin
node_dkg -->|"stores"| node_local_storage
node_pre -->|"consults"| node_bulletin
node_sign -->|"consults"| node_bulletin

click node_cli_tool "https://github.com/sourcenetwork/orbis-rs/tree/develop/bin/cli-tool"
click node_orbis_node "https://github.com/sourcenetwork/orbis-rs/tree/develop/bin/orbis-node"
click node_node_runtime "https://github.com/sourcenetwork/orbis-rs/blob/develop/bin/orbis-node/src/runtime.rs"
click node_node_helpers "https://github.com/sourcenetwork/orbis-rs/tree/develop/bin/orbis-node/src/helpers"
click node_node_metrics "https://github.com/sourcenetwork/orbis-rs/blob/develop/bin/orbis-node/src/metrics.rs"
click node_dkg "https://github.com/sourcenetwork/orbis-rs/tree/develop/bin/orbis-node/src/dkg"
click node_pre "https://github.com/sourcenetwork/orbis-rs/tree/develop/bin/orbis-node/src/pre"
click node_sign "https://github.com/sourcenetwork/orbis-rs/tree/develop/bin/orbis-node/src/sign"
click node_store_secret "https://github.com/sourcenetwork/orbis-rs/tree/develop/bin/orbis-node/src/store_secret"
click node_info "https://github.com/sourcenetwork/orbis-rs/tree/develop/bin/orbis-node/src/info"
click node_unsafe_testing "https://github.com/sourcenetwork/orbis-rs/tree/develop/bin/orbis-node/src/unsafe_testing"
click node_crypto "https://github.com/sourcenetwork/orbis-rs/tree/develop/crates/crypto"
click node_network "https://github.com/sourcenetwork/orbis-rs/tree/develop/crates/network"
click node_local_storage "https://github.com/sourcenetwork/orbis-rs/tree/develop/crates/local-storage"
click node_proto "https://github.com/sourcenetwork/orbis-rs/tree/develop/crates/proto"
click node_authn "https://github.com/sourcenetwork/orbis-rs/tree/develop/crates/authn"
click node_authz "https://github.com/sourcenetwork/orbis-rs/tree/develop/crates/authz"
click node_bulletin "https://github.com/sourcenetwork/orbis-rs/tree/develop/crates/bulletin"
click node_common "https://github.com/sourcenetwork/orbis-rs/tree/develop/crates/common"

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_cli_tool toneBlue
class node_orbis_node,node_node_runtime,node_node_helpers toneAmber
class node_dkg,node_pre,node_sign,node_store_secret,node_info,node_unsafe_testing toneMint
class node_crypto,node_network,node_local_storage,node_proto,node_authn,node_authz,node_bulletin,node_common toneRose
class node_node_metrics toneIndigo
```

## Components

### Binaries

Runnable entrypoints

- [CLI tool](https://github.com/sourcenetwork/orbis-rs/tree/develop/bin/cli-tool): operator client · Operator and client entrypoint · `bin/cli-tool`

### Node runtime

Core orbis-node application

- [Orbis node](https://github.com/sourcenetwork/orbis-rs/tree/develop/bin/orbis-node): runtime binary · Ring participant and service host · `bin/orbis-node`
- [Runtime](https://github.com/sourcenetwork/orbis-rs/blob/develop/bin/orbis-node/src/runtime.rs): app core · Launch, app state, and execution wiring · `bin/orbis-node/src/runtime.rs`
- [Helpers](https://github.com/sourcenetwork/orbis-rs/tree/develop/bin/orbis-node/src/helpers): node glue · Auth, routing, identity, and protocol utilities · `bin/orbis-node/src/helpers`

### Protocol subsystems

Versioned MPC and control services

- [DKG](https://github.com/sourcenetwork/orbis-rs/tree/develop/bin/orbis-node/src/dkg): threshold ceremony · Distributed key generation and resharing · `bin/orbis-node/src/dkg`
- [PRE](https://github.com/sourcenetwork/orbis-rs/tree/develop/bin/orbis-node/src/pre): threshold reencryption · Distributed proxy re-encryption workflow · `bin/orbis-node/src/pre`
- [Signing](https://github.com/sourcenetwork/orbis-rs/tree/develop/bin/orbis-node/src/sign): threshold signing · Interactive threshold signature flow · `bin/orbis-node/src/sign`
- [Store secret](https://github.com/sourcenetwork/orbis-rs/tree/develop/bin/orbis-node/src/store_secret): secret service · Secret persistence service · `bin/orbis-node/src/store_secret`
- [Info](https://github.com/sourcenetwork/orbis-rs/tree/develop/bin/orbis-node/src/info): status service · Node and ring information service · `bin/orbis-node/src/info`
- [Unsafe testing](https://github.com/sourcenetwork/orbis-rs/tree/develop/bin/orbis-node/src/unsafe_testing): test service · Non-production control surface · `bin/orbis-node/src/unsafe_testing`

### Shared crates

Reusable libraries and integration boundaries

- [Crypto](https://github.com/sourcenetwork/orbis-rs/tree/develop/crates/crypto): protocol engine · Curve-backed threshold crypto traits and implementations · `crates/crypto`
- [Network](https://github.com/sourcenetwork/orbis-rs/tree/develop/crates/network): p2p transport · QUIC/Iroh abstraction for peer messaging · `crates/network`
- [Local storage](https://github.com/sourcenetwork/orbis-rs/tree/develop/crates/local-storage): encrypted KV · Encrypted persistence for node secrets · `crates/local-storage`
- [Proto](https://github.com/sourcenetwork/orbis-rs/tree/develop/crates/proto): grpc contract · Generated gRPC service definitions · `crates/proto`
- [AuthN](https://github.com/sourcenetwork/orbis-rs/tree/develop/crates/authn): jwt/did:key · Authentication verification layer · `crates/authn`
- [AuthZ](https://github.com/sourcenetwork/orbis-rs/tree/develop/crates/authz): policy engine · Authorization policy checks · `crates/authz`
- [Bulletin](https://github.com/sourcenetwork/orbis-rs/tree/develop/crates/bulletin): bulletin-board · Chain-backed bulletin state access · `crates/bulletin`
- [Common](https://github.com/sourcenetwork/orbis-rs/tree/develop/crates/common): chain client · Shared SourceHub blockchain client and config · `crates/common`

### Infra

Observability and deployment support

- [Metrics](https://github.com/sourcenetwork/orbis-rs/blob/develop/bin/orbis-node/src/metrics.rs): telemetry · Node observability exports · `bin/orbis-node/src/metrics.rs`

## Connections

- CLI tool → Proto: calls · Client talks through the gRPC contract
- CLI tool → Orbis node: invokes · Operator drives node operations
- Orbis node → Runtime: boots · Main binary wires runtime state and services
- Orbis node → Helpers: uses · Shared node glue for routing and auth
- Orbis node → Metrics: exports · Publishes operational metrics
- Orbis node → DKG: hosts · Runs DKG control and coordinator logic
- Orbis node → PRE: hosts · Runs PRE control and coordinator logic
- Orbis node → Signing: hosts · Runs signing control and coordinator logic
- Orbis node → Store secret: hosts · Exposes secret storage service
- Orbis node → Info: hosts · Exposes node information service
- Orbis node → Unsafe testing: hosts · Exposes test-only control surface
- DKG → Crypto: depends on · Protocol logic is trait-backed by crypto engine
- PRE → Crypto: depends on · Re-encryption workflow uses crypto abstractions
- Signing → Crypto: depends on · Signing rounds use crypto abstractions
- DKG → Network: peers via · MPC messages flow over p2p transport
- PRE → Network: peers via · Distributed PRE exchange uses p2p transport
- Signing → Network: peers via · Interactive signing uses p2p transport
- Store secret → Local storage: persists to · Secrets are written through encrypted storage
- Orbis node → Proto: implements · Node services implement gRPC contracts
- Orbis node → AuthN: validates · Node checks caller identity and JWTs
- Orbis node → AuthZ: authorizes · Node consults policy decisions
- Orbis node → Bulletin: reads/writes · Node accesses bulletin-board state
- AuthZ → Common: uses · Policy layer relies on shared chain client
- Bulletin → Common: uses · Bulletin layer relies on shared chain client
- DKG → Bulletin: updates · Reshare and lifecycle steps touch bulletin state
- DKG → Local storage: stores · Ring and secret material persist locally
- PRE → Bulletin: consults · PRE decisions can depend on bulletin metadata
- Signing → Bulletin: consults · Signing can depend on bulletin metadata