49 lines
1.5 KiB
Markdown
49 lines
1.5 KiB
Markdown
# 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.
|
|
|
|
```mermaid
|
|
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
|
|
|
|
```mermaid
|
|
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
|