modules/applications-economy/hyper-p2p-credit-ledger/docs/architecture.md

Architecture: hyper-p2p-credit-ledger

Category: applications-economy · Protocol: credit-ledger/v1

Role

Eventually-consistent balance sheet: peers converge on latest gossiped balance per account. Suitable for soft credits and demo economies — not a Byzantine-fault-tolerant ledger without additional consensus.

flowchart LR
  App[Wallet / market] --> CL[HyperP2PCreditLedger]
  CL --> Acct[_accounts Map]
  CL --> Gossip[gossipSend ledger-entry]

Wire messages

type	direction	fields	behavior
ledger-entry	gossip	accountId, kind, balance, at, optional delta, reason, peer	Create on open; else overwrite balance

Sequence

sequenceDiagram
  participant A as Peer A
  participant L as CreditLedger
  participant B as Peer B
  A->>L: transfer(alice, bob, 10)
  L->>L: debit + credit locally
  L-->>B: ledger-entry (bob balance)
  B->>B: apply balance snapshot

State model

Key	Value
_accounts	accountId → { id, balance, updatedAt }
_stats	credit/debit counters, gossip in/out

Merge rule: last gossip wins per account (by arrival order, not Lamport clock). Transfers are two entries; receivers may briefly see intermediate states.

Composition

• hyper-p2p-auction-gossip — pay winner via debit/credit
• hyper-p2p-marketplace-listing — price in listing metadata
• hyper-p2p-decentralized-oracle — FX or reserve rates