Architecture

The core node is written in Go. It uses libp2p for peer-to-peer networking, BadgerDB for persistent storage, blake2b for proof-of-work, and ed25519 for signatures.

Package Map

core/
├── cmd/
│   └── xe/         Single binary — node daemon, wallet, send/receive, leases, ssh
├── core/           Domain logic — ledger, crypto, encoding, PoW, voting, quorum
├── store/          Pluggable storage — MemStore (testing), BadgerStore (production)
├── net/            libp2p networking — gossip, sync, DHT, marketplace, messaging
├── node/           Orchestration — ties all packages together into a running node
├── api/            HTTP REST API — handler, routes, CORS
├── statechain/     Deterministic state machine — DAO governance, KV store, sync
├── vm/             VM abstraction — manager interface, mock, credentials
├── perf/           Performance certificates — workload benchmark, price multiplier
├── web/            Embedded web UI — HTML + ES modules + CSS, served by xe node --ui
├── client/         Client-side helpers shared by CLI subcommands
├── directory/      P2P account directory — registration, verification, gossip
├── chat/           P2P messaging — envelope format, chat store
└── scripts/        Test and utility scripts — e2e, stress, genesis generation

Core Package Files

File	Purpose
`types.go`	Block, Vote, Conflict, Lease, PendingSend structs; BlockType constants
`ledger.go`	Ledger struct — validates/adds blocks, per-account locking, delegation tracking
`amount.go`	Per-asset decimal precision; micro-unit amount parsing and formatting
`crypto.go`	KeyPair, GenerateKeyPair, HashBlock (SHA-256), SignBlock, VerifyBlock (ed25519)
`encoding.go`	MarshalBlockCanonical (binary encoding), MarshalBlock, UnmarshalBlock; vote encoding
`pow.go`	blake2b PoW — ComputePoW, ComputePoWConcurrent, ComputePoWWithContext, ValidatePoW
`vote.go`	VoteManager — casts and validates votes for conflict resolution
`quorum.go`	QuorumManager — tallies votes, finalizes/rejects blocks at 67% weight
`finalization.go`	Two-phase finalization voting — the central consensus mechanism
`conflict.go`	Conflict detection — equivocation checks
`cascade_commit.go`	Conflict-promotion overlay — atomically commits a winning fork's cascade
`rollback.go`	Cascading cross-account rollback of rejected forks
`spendable.go`	Spendable-balance computation — settlement surfaces honor finalization
`genesis.go`	Embedded genesis — loads and validates the genesis allocation at startup
`mint.go`	Authorized XUSD mint validation — sys.minter accounts only
`memo.go`	On-chain memo size and validation rules
`multisig.go`	Multisig address derivation, keyset validation, threshold signatures
`reputation.go`	Deterministic per-account reputation from on-chain lease activity
`retryable.go`	Classifies errors that may resolve on retry (missing dependencies)
`attestation.go`	Timekeeper attestation validation for lease blocks
`store.go`	Store interface and optional interfaces

Block Validation Pipeline

AddBlock(b *Block)
  │
  ├── 1. Normalize hex fields (lowercase)
  ├── 2. VerifyBlock — recompute hash + check ed25519 signature
  ├── 3. ValidatePoW — blake2b(nonce || hash) >= difficulty
  ├── 4. Timestamp check — within ±1 hour of local time
  ├── 5. Duplicate check — block hash not already in store
  ├── 6. Conflict detection — check if Previous hash is shared
  │     ├── No conflict → continue on main chain
  │     └── Conflict → stage block, fire callback, return
  │
  ├── 7. Type-specific validation (per-account lock held)
  │     ├── send     → balance sufficient, frontier matches, amount > 0
  │     ├── receive  → pending send exists, destination matches
  │     ├── mint     → XUSD only, account in sys.minter, no source/destination/memo, amount > 0
  │     ├── burn     → XE only, no source/destination, amount > 0, balance sufficient
  │     ├── lease    → XUSD only, cost formula correct, balance sufficient
  │     ├── lease_accept → lease exists, stake = ceil(cost/5), attestations valid
  │     ├── lease_settle → lease expired, XE emission formula
  │     ├── lease_cancel → consumer only, source lease exists and is cancellable
  │     ├── lease_force_settle → consumer only, lease accepted but unsettled
  │     └── multisig_open/update → keyset valid; open derives the account address, update rotates the keyset
  │
  ├── 8. Update in-memory state (asset balances, delegation weights)
  └── 9. Write to store (atomic commit via AtomicBlockStore)

Startup Sequence

Open or create key pair (loads {dataDir}/node.key or generates new)
Open store (BadgerStore at {dataDir}/ledger)
Create libp2p host (TCP, noise encryption, yamux)
Setup pubsub (GossipSub)
Create gossip layers (block, vote, marketplace, directory, state chain)
Setup mDNS
Create ledger (wraps store with validation)
Wire voting (VoteManager + QuorumManager)
Setup frontier sync
Setup DHT (Kademlia)
Create messenger
Initialize state chain
Wire timekeeper config
Register gossip handlers
Dial bootstrap peers
Start background goroutines