# fystack/mpcium architecture

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

- Interactive diagram: https://gitdiagram.com/fystack/mpcium
- Repository: https://github.com/fystack/mpcium

## Overview

Mpcium is a distributed MPC wallet engine: clients request wallet generation, signing, or resharing; node processes authenticate and route those events into threshold sessions, which coordinate peers and return results. The graph also shows node identity, persistence, HD derivation, service discovery, health checks, and backup capabilities. Relationships reflect sampled source references and README statements; some subsystems are documented but their internal wiring was not sampled.

Main entry points: [`cmd/mpcium/main.go`](https://github.com/fystack/mpcium/blob/master/cmd/mpcium/main.go) (Node process), [`pkg/client/client.go`](https://github.com/fystack/mpcium/blob/master/pkg/client/client.go) (MPC client), [`pkg/mpc/session.go`](https://github.com/fystack/mpcium/blob/master/pkg/mpc/session.go) (Threshold sessions), [`pkg/kvstore/badger.go`](https://github.com/fystack/mpcium/blob/master/pkg/kvstore/badger.go) (Encrypted key store)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_product["Requests and operations"]
  node_client["MPC client<br/>[client.go]"]
  node_client_signer["Client signers"]
  node_keygen_events["Keygen events<br/>[keygen.go]"]
  node_sign_events["Signing events<br/>[sign.go]"]
  node_reshare_events["Reshare events<br/>[reshare.go]"]
end

subgraph group_coordination["Node coordination"]
  node_event_router["Event consumer<br/>[event_consumer.go]"]
  node_keygen_handler["Keygen handler<br/>[keygen_consumer.go]"]
  node_sign_handler["Signing handler<br/>[sign_consumer.go]"]
  node_messaging["NATS messaging"]
  node_peer_messaging["Peer messaging"]
end

subgraph group_crypto["MPC and identity"]
  node_mpc_node["MPC node<br/>[node.go]"]
  node_mpc_sessions["Threshold sessions<br/>[session.go]"]
  node_ecdsa_sign["ECDSA signing"]
  node_eddsa_sign["EdDSA signing"]
  node_identity["Identity and auth<br/>[identity.go]"]
  node_child_keys["HD derivation"]
end

subgraph group_state["State and key material"]
  node_kvstore[("Encrypted key store<br/>[badger.go]")]
  node_keyinfo[("Wallet metadata<br/>[keyinfo.go]")]
  node_backup["Encrypted backups<br/>[badger_backup.go]"]
end

subgraph group_operations["Node operations"]
  node_node_app["Node process<br/>[main.go]"]
  node_consul["Consul discovery<br/>[consul.go]"]
  node_health["Health checks<br/>[server.go]"]
  node_cli["Node setup CLI<br/>[main.go]"]
end

node_user(("Wallet client"))
node_nats_service["NATS service"]
node_peer_nodes(("MPC peers"))
node_consul_service["Consul service"]

node_user -->|"requests operations"| node_client
node_client -->|"signs requests"| node_client_signer
node_client -->|"publishes requests"| node_messaging
node_client -->|"builds"| node_keygen_events
node_client -->|"builds"| node_sign_events
node_client -.->|"builds"| node_reshare_events
node_node_app -->|"starts"| node_event_router
node_node_app -->|"creates"| node_mpc_node
node_node_app -->|"connects"| node_messaging
node_node_app -->|"opens"| node_kvstore
node_node_app -->|"loads"| node_identity
node_node_app -->|"configures"| node_consul
node_node_app -->|"starts"| node_health
node_messaging -->|"delivers events"| node_event_router
node_event_router -->|"verifies senders"| node_identity
node_event_router -->|"dispatches keygen"| node_keygen_handler
node_event_router -->|"dispatches signing"| node_sign_handler
node_keygen_handler -->|"creates sessions"| node_mpc_node
node_sign_handler -->|"creates sessions"| node_mpc_node
node_mpc_node -.->|"runs sessions"| node_mpc_sessions
node_mpc_sessions -->|"coordinates peers"| node_peer_messaging
node_mpc_sessions -->|"signs messages"| node_identity
node_mpc_sessions -->|"loads shares"| node_kvstore
node_ecdsa_sign -->|"reads metadata"| node_keyinfo
node_ecdsa_sign -->|"loads shares"| node_kvstore
node_ecdsa_sign -.->|"derives child key"| node_child_keys
node_eddsa_sign -->|"reads metadata"| node_keyinfo
node_eddsa_sign -->|"loads shares"| node_kvstore
node_mpc_sessions -->|"exchanges shares"| node_peer_nodes
node_mpc_sessions -->|"publishes results"| node_messaging
node_keygen_handler -.->|"stores shares"| node_kvstore
node_kvstore -.->|"backs up data"| node_backup
node_consul -->|"registers nodes"| node_consul_service
node_health -->|"checks status"| node_consul_service
node_health -->|"checks readiness"| node_peer_nodes
node_cli -.->|"generates identity"| node_identity
node_nats_service -->|"relays messages"| node_peer_nodes

click node_client "https://github.com/fystack/mpcium/blob/master/pkg/client/client.go"
click node_client_signer "https://github.com/fystack/mpcium/tree/master/pkg/client"
click node_keygen_events "https://github.com/fystack/mpcium/blob/master/pkg/event/keygen.go"
click node_sign_events "https://github.com/fystack/mpcium/blob/master/pkg/event/sign.go"
click node_reshare_events "https://github.com/fystack/mpcium/blob/master/pkg/event/reshare.go"
click node_node_app "https://github.com/fystack/mpcium/blob/master/cmd/mpcium/main.go"
click node_event_router "https://github.com/fystack/mpcium/blob/master/pkg/eventconsumer/event_consumer.go"
click node_keygen_handler "https://github.com/fystack/mpcium/blob/master/pkg/eventconsumer/keygen_consumer.go"
click node_sign_handler "https://github.com/fystack/mpcium/blob/master/pkg/eventconsumer/sign_consumer.go"
click node_mpc_node "https://github.com/fystack/mpcium/blob/master/pkg/mpc/node.go"
click node_mpc_sessions "https://github.com/fystack/mpcium/blob/master/pkg/mpc/session.go"
click node_ecdsa_sign "https://github.com/fystack/mpcium/blob/master/pkg/mpc/ecdsa_signing_session.go"
click node_eddsa_sign "https://github.com/fystack/mpcium/blob/master/pkg/mpc/eddsa_signing_session.go"
click node_identity "https://github.com/fystack/mpcium/blob/master/pkg/identity/identity.go"
click node_messaging "https://github.com/fystack/mpcium/blob/master/pkg/messaging/jetstream_broker.go"
click node_peer_messaging "https://github.com/fystack/mpcium/tree/master/pkg/messaging"
click node_kvstore "https://github.com/fystack/mpcium/blob/master/pkg/kvstore/badger.go"
click node_keyinfo "https://github.com/fystack/mpcium/blob/master/pkg/keyinfo/keyinfo.go"
click node_child_keys "https://github.com/fystack/mpcium/blob/master/pkg/ckdutil/child_derivation.go"
click node_backup "https://github.com/fystack/mpcium/blob/master/pkg/kvstore/badger_backup.go"
click node_consul "https://github.com/fystack/mpcium/blob/master/pkg/infra/consul.go"
click node_health "https://github.com/fystack/mpcium/blob/master/pkg/healthcheck/server.go"
click node_cli "https://github.com/fystack/mpcium/blob/master/cmd/mpcium-cli/main.go"

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_client,node_client_signer,node_keygen_events,node_sign_events,node_reshare_events,node_user toneBlue
class node_event_router,node_keygen_handler,node_sign_handler,node_messaging,node_peer_messaging toneAmber
class node_mpc_node,node_mpc_sessions,node_ecdsa_sign,node_eddsa_sign,node_identity,node_child_keys toneMint
class node_kvstore,node_keyinfo,node_backup toneRose
class node_node_app,node_consul,node_health,node_cli,node_nats_service,node_peer_nodes,node_consul_service toneIndigo
```

## Components

### Requests and operations

- [MPC client](https://github.com/fystack/mpcium/blob/master/pkg/client/client.go): `pkg/client/client.go`
- [Client signers](https://github.com/fystack/mpcium/tree/master/pkg/client): `pkg/client`
- [Keygen events](https://github.com/fystack/mpcium/blob/master/pkg/event/keygen.go): `pkg/event/keygen.go`
- [Signing events](https://github.com/fystack/mpcium/blob/master/pkg/event/sign.go): `pkg/event/sign.go`
- [Reshare events](https://github.com/fystack/mpcium/blob/master/pkg/event/reshare.go): `pkg/event/reshare.go`

### Node coordination

- [Event consumer](https://github.com/fystack/mpcium/blob/master/pkg/eventconsumer/event_consumer.go): `pkg/eventconsumer/event_consumer.go`
- [Keygen handler](https://github.com/fystack/mpcium/blob/master/pkg/eventconsumer/keygen_consumer.go): `pkg/eventconsumer/keygen_consumer.go`
- [Signing handler](https://github.com/fystack/mpcium/blob/master/pkg/eventconsumer/sign_consumer.go): `pkg/eventconsumer/sign_consumer.go`
- [NATS messaging](https://github.com/fystack/mpcium/blob/master/pkg/messaging/jetstream_broker.go): `pkg/messaging/jetstream_broker.go`
- [Peer messaging](https://github.com/fystack/mpcium/tree/master/pkg/messaging): `pkg/messaging`

### MPC and identity

- [MPC node](https://github.com/fystack/mpcium/blob/master/pkg/mpc/node.go): `pkg/mpc/node.go`
- [Threshold sessions](https://github.com/fystack/mpcium/blob/master/pkg/mpc/session.go): `pkg/mpc/session.go`
- [ECDSA signing](https://github.com/fystack/mpcium/blob/master/pkg/mpc/ecdsa_signing_session.go): `pkg/mpc/ecdsa_signing_session.go`
- [EdDSA signing](https://github.com/fystack/mpcium/blob/master/pkg/mpc/eddsa_signing_session.go): `pkg/mpc/eddsa_signing_session.go`
- [Identity and auth](https://github.com/fystack/mpcium/blob/master/pkg/identity/identity.go): `pkg/identity/identity.go`
- [HD derivation](https://github.com/fystack/mpcium/blob/master/pkg/ckdutil/child_derivation.go): `pkg/ckdutil/child_derivation.go`

### State and key material

- [Encrypted key store](https://github.com/fystack/mpcium/blob/master/pkg/kvstore/badger.go): `pkg/kvstore/badger.go`
- [Wallet metadata](https://github.com/fystack/mpcium/blob/master/pkg/keyinfo/keyinfo.go): `pkg/keyinfo/keyinfo.go`
- [Encrypted backups](https://github.com/fystack/mpcium/blob/master/pkg/kvstore/badger_backup.go): `pkg/kvstore/badger_backup.go`

### Node operations

- [Node process](https://github.com/fystack/mpcium/blob/master/cmd/mpcium/main.go): `cmd/mpcium/main.go`
- [Consul discovery](https://github.com/fystack/mpcium/blob/master/pkg/infra/consul.go): `pkg/infra/consul.go`
- [Health checks](https://github.com/fystack/mpcium/blob/master/pkg/healthcheck/server.go): `pkg/healthcheck/server.go`
- [Node setup CLI](https://github.com/fystack/mpcium/blob/master/cmd/mpcium-cli/main.go): `cmd/mpcium-cli/main.go`

### Other components

- **Wallet client**
- **NATS service**
- **MPC peers**
- **Consul service**

## Connections

- Wallet client → MPC client: requests operations
- MPC client → Client signers: signs requests
- MPC client → NATS messaging: publishes requests (evidence: `pkg/client/client.go`)
- MPC client → Keygen events: builds (evidence: `pkg/client/client.go`)
- MPC client → Signing events: builds (evidence: `pkg/client/client.go`)
- MPC client → Reshare events: builds
- Node process → Event consumer: starts (evidence: `cmd/mpcium/main.go`)
- Node process → MPC node: creates (evidence: `cmd/mpcium/main.go`)
- Node process → NATS messaging: connects (evidence: `cmd/mpcium/main.go`)
- Node process → Encrypted key store: opens (evidence: `cmd/mpcium/main.go`)
- Node process → Identity and auth: loads (evidence: `cmd/mpcium/main.go`)
- Node process → Consul discovery: configures (evidence: `cmd/mpcium/main.go`)
- Node process → Health checks: starts (evidence: `cmd/mpcium/main.go`)
- NATS messaging → Event consumer: delivers events
- Event consumer → Identity and auth: verifies senders
- Event consumer → Keygen handler: dispatches keygen (evidence: `pkg/eventconsumer/event_consumer.go`)
- Event consumer → Signing handler: dispatches signing (evidence: `pkg/eventconsumer/event_consumer.go`)
- Keygen handler → MPC node: creates sessions (evidence: `pkg/eventconsumer/keygen_consumer.go`)
- Signing handler → MPC node: creates sessions
- MPC node → Threshold sessions: runs sessions
- Threshold sessions → Peer messaging: coordinates peers (evidence: `pkg/mpc/session.go`)
- Threshold sessions → Identity and auth: signs messages (evidence: `pkg/mpc/session.go`)
- Threshold sessions → Encrypted key store: loads shares (evidence: `pkg/mpc/session.go`)
- ECDSA signing → Wallet metadata: reads metadata (evidence: `pkg/mpc/ecdsa_signing_session.go`)
- ECDSA signing → Encrypted key store: loads shares (evidence: `pkg/mpc/ecdsa_signing_session.go`)
- ECDSA signing → HD derivation: derives child key
- EdDSA signing → Wallet metadata: reads metadata (evidence: `pkg/mpc/eddsa_signing_session.go`)
- EdDSA signing → Encrypted key store: loads shares (evidence: `pkg/mpc/eddsa_signing_session.go`)
- Threshold sessions → MPC peers: exchanges shares
- Threshold sessions → NATS messaging: publishes results
- Keygen handler → Encrypted key store: stores shares
- Encrypted key store → Encrypted backups: backs up data
- Consul discovery → Consul service: registers nodes
- Health checks → Consul service: checks status (evidence: `pkg/healthcheck/server.go`)
- Health checks → MPC peers: checks readiness (evidence: `pkg/healthcheck/server.go`)
- Node setup CLI → Identity and auth: generates identity
- NATS service → MPC peers: relays messages
