sourcenetwork/orbis-rs

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.