System Architecture
Layer Diagram
┌─────────────────────────────────────────────────────────────────────┐
│ External Integrations │
│ LLM agents · AI frameworks · Application backends │
└─────────────────────────┬───────────────────────────────────────────┘
│ HTTP / Go SDK
┌─────────────────────────▼───────────────────────────────────────────┐
│ Go SDK (golang-sdk) │
│ Wallet management · Transaction submission · Domain test runners │
│ Identity lifecycle · Council orchestration · Polling / receipts │
└─────────────────────────┬───────────────────────────────────────────┘
│ HTTP (REST)
┌─────────────────────────▼───────────────────────────────────────────┐
│ Node Webserver │
│ Auth middleware · Rate limiting · Route dispatch │
│ /chains · /wallets · /entities · /contracts · /credentials │
└──────┬──────────────────────┬──────────────────────────────────────┘
│ │
▼ ▼
┌─────────────┐ ┌──────────────────────────────────────────────────┐
│ Blockchain │ │ Consensus Layer │
│ (per chain)│ │ BFT voting · Proposal/vote buffers │
│ │◄───│ Member cache · Quorum agreement │
│ Processors │ │ Block finalization │
│ (60+ TX │ └──────────────────────────────────────────────────┘
│ types) │
└──────┬──────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ Core Domain Types │
│ Wallet · Entity · Transaction · Block · Capability · Contract │
└──────┬──────────────────────┬──────────────────────────────────────┘
│ │
▼ ▼
┌─────────────┐ ┌──────────────────────────────────────────────────┐
│ Storage │ │ Execution Subsystems │
│ BadgerDB │ │ ULVM (wazero WASM) · Crypto · Proofs · Identity │
│ + sidecar │ │ Credentials · Network (libp2p QUIC+GossipSub) │
└─────────────┘ └──────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ Helix STARK Sidecar (per node) │
│ Plonky3 prover · Checkpoint generation · Recursive proof folding │
│ Independent auditor · Cross-algorithm anchoring │
└─────────────────────────────────────────────────────────────────────┘
Nodes and Councils
A council is the set of validator nodes that reach BFT consensus on a chain. In a production deployment the Helix runbook describes a 9-node council, each node hosting:
- Principal chain (
secp256k1): the primary consensus chain. - Member chain A (
secp256k1): secondary member activity chain. - Member chain B (
mldsa87): post-quantum member chain.
Each chain has independent BFT consensus. A checkpoint requires quorum agreement from the council before it is written.
Node Ports (Default Local)
| Service | Ports |
|---|---|
| Node webserver (HTTP API) | 8080–8088 |
| Node admin | 8200–8208 |
| Node p2p (libp2p) | 9080–9088 |
| Helix sidecar (per node) | 8100–8108 |
| Independent auditor | 8120 |
| DHT relay | 4001 |
Chains and Key Types
A chain is identified by a blockchain ID (a hex hash). At chain creation time, the key algorithm is fixed. All wallets on that chain must use that algorithm. For the full algorithm reference see Wallet Key Types.
Wallet keys are derived from BIP39 mnemonics with entropy. A wallet's private key never leaves the SDK; only the public key and signed transactions touch the network.
Transaction Lifecycle
1. CONSTRUCT
SDK builds transaction payload (type, fields, sender address)
2. SIGN
SDK signs payload with sender's private key (.ukey file)
3. SUBMIT
HTTP POST to any node endpoint → pending pool
4. GOSSIP
Node broadcasts transaction to peers via GossipSub (libp2p)
5. VALIDATE
During block proposal: authorization checks (ancestry, capabilities,
blacklists) run against current state
6. EXECUTE
Block processor executes transaction: updates wallets, entities,
contract state, token balances
7. COMMIT
Block finalized, state committed to BadgerDB + sidecar files
8. CONFIRM
SDK polls any node (including a different node from submission)
for transaction receipt, cross-node consistency confirmed
Authorization Checks (Run at Steps 5 and 6)
- Sender's entity ancestry chain must be fully enabled.
- Target entity's governing chain honors blacklists.
- Value-transfer recipients may self-blacklist.
- Capability-restricted wallets are checked against held capabilities.
- Capability expiry is evaluated at execution time (block height comparison).
Storage Architecture
ULedgerNET uses a hybrid storage model:
- BadgerDB stores a single-byte sentinel key per record (fast key existence checks).
- Sidecar files store the full serialized records on disk.
- Read path: bounded in-memory cache → BadgerDB sentinel → sidecar file read.
This keeps BadgerDB compact while preserving auditability of the full record set in flat files.
Credential registry is node-local; it is not replicated across nodes. Each node issues and tracks its own verifiable credentials independently.
Helix STARK Proof Pipeline
Blocks finalized by BFT consensus
│
▼
Helix sidecar (per node) collects block headers + member data
│
▼
Plonky3 prover generates STARK proof for epoch batch
│
▼
Recursive proof folding: each epoch proof folds into the prior chain
│
▼
Checkpoint written to principal chain (cross-algorithm anchored:
secp256k1 + ML-DSA-87 signatures on the same checkpoint)
│
▼
Independent auditor verifies checkpoint without access to any node
The result is a constant-size proof that covers an arbitrarily long chain history. An auditor does not need to replay the entire chain; only the checkpoint proofs and the public keys of the council members are required.
Go SDK as Integration Layer
The Go SDK (github.com/ULedgerInc/golang-sdk) is the primary integration interface. It provides:
- Wallet generation and registration: create and on-board wallets from BIP39 entropy.
- Transaction submission and polling: submit any transaction type, poll for receipt, verify cross-node consistency.
- Domain test runners: assertive end-to-end harnesses for token, contract, walletops, data, and council domains.
- Identity lifecycle: create DIDs, issue verifiable credentials, configure recovery.
- Council orchestration: full proposal lifecycle: member add, agent authorize, create proposal, issue work tokens, submit votes, finalize.
The SDK reads wallet keys from .ukey files, uses a JSON config for node endpoints and chain parameters, and writes timestamped JSON reports for every run.
Network Layer
Node-to-node communication uses libp2p with:
- Transport: QUIC (primary) + TCP (fallback)
- Security: Noise protocol handshake
- Discovery: DHT (Kademlia) via a bootstrap relay node
- Messaging: GossipSub for transaction propagation and block announcements
Nodes authenticate each other via their keypairs. The DHT relay on port 4001 serves as the bootstrap point for new nodes joining the council.