# Pillar Software and Network Specification (Draft) This document complements the white paper and technical reference with software-oriented detail: node roles, APIs, flows, and illustrative code snippets. It assumes the percent-native, fixed-max-share model and the ratified genesis parameters in `technical-doc.txt`. Monetary invariants and label tables are immutable; operational flexibility is limited to custodied allocation/loans and non-monetary parameters. --- ## S1. Architecture Overview - Node types: - Country Node: sovereign-operated; validates, batches, signs epochs, manages custody rules; cannot change `SHARE_SUPPLY_MAX` or labels. - Processing Node: non-sovereign; propagates, verifies, stores erasure-coded fragments, participates in DA attestations; no custody, no monetary authority. - Data model: - Share balances keyed by public keys. - Batches `B_i^e` per epoch `e`, hashed to `h_i^e`. - Global root `R^e = MerkleRoot(h_1^e,...,h_N^e)`; signed by stake-weighted quorum plus diversity threshold. - Erasure-coded fragments `(k,n)` per batch; `m` attestations with `S` sampled fragments. - Immutability: - Immutable: `SHARE_SUPPLY_MAX`, label table, monetary invariants, burn-on-redemption. - Upgrade-scope (requires sovereign quorum + time lock; cannot affect supply/labels): DA `(k,n,m,S)`, epoch length, stake caps/decay, proposer/attestor rotation, redemption cap, redemption window length, reserve unlock rate bounds, fee rate bounds. --- ## S2. Node Software Components - Core ledger service: validates transactions, applies share debits/credits, computes fees, accrues usage fees. - Batch builder: aggregates pending txs into `B_i^e`, produces `h_i^e`. - Finality signer: signs `R^e`, enforces diversity/quorum rules, applies slashing/eligibility checks. - DA service: erasure-codes batches/state, distributes fragments, collects/serves attestations. - Networking: gossip for tx/batch propagation; RPC for API endpoints; secure channels (TLS, mTLS inter-node). - Storage: hot DB for recent state/mempool; cold/archive for batch logs, fragments, audit commitments. - Observability: metrics (uptime, DA attest rate, slash events), logs, audit commitments on-chain. --- ## S3. APIs (illustrative) REST-style; gRPC equivalent possible. - `POST /tx/submit` -> `{txid, status}`; tx includes `{chain_id, from, to, amount_shares, fee_shares|fee_rate, nonce, epoch_hint, sig}`. - `GET /tx/{txid}` -> `{status, inclusion_root, batch_id, epoch}`. - `GET /proof/tx/{txid}` -> `{root, merkle_path, batch_id, epoch, signatures}`. - `GET /state/balance/{pubkey}` -> `{balance_shares, balance_labels}`. - `GET /proof/state/{pubkey}` -> `{root, merkle_path, balance_shares}`. - `GET /epoch/{e}/root` -> `{R_e, signatures, stake_weight, min_sovereigns_met}`. - `GET /da/attestations/{e}` -> `{attestors, fragments_sampled, status}`. - `GET /redeem/queue` -> `{pending_requests, expected_window_start, window_seconds, cap_pct}`. - `GET /params/current` -> `{k: int, n: int, m: int, S: int, epoch_seconds: int, stake_cap_pct: float, min_sovereigns: int, r_s: float, min_shares: int, min_redemption_shares: int, redemption_window_seconds: int, redemption_cap_pct: float, reserve_unlock_pct_annual: float, country_tax_rate: float, country_tax_cap_pct: float}`. - `GET /params/pending` -> `{proposed_params, activation_epoch, quorum_signatures}`. - Admin (Country Nodes only, auth required): `POST /batch/finalize`, `POST /sign/root`. - Errors: `{code, message, details}` with codes for invalid signature, insufficient balance, below-minimum-transfer, fee-too-low, duplicate-nonce, not-finalized, auth-failed (admin). - Security: mTLS or signed requests for admin; chain_id required; rate limiting on public submit. - Field types: pubkeys hex-encoded 32 bytes; shares as uint64; fee_rate as float in [0,1]; nonces as uint64. --- ## S4. Transaction Flow (happy path) 1) Client builds tx and signs with spend key. 2) Submit via `POST /tx/submit`. 3) Country Node validates: signature, nonce, balance >= amount+fee, MIN_SHARES floor, label mapping. 4) Tx enters mempool; batch builder picks txs into `B_i^e`, computes `h_i^e`. 5) DA: erasure-code batch, distribute fragments, collect attestations (Country + Processing Nodes). 6) Finality: compute `R^e`, gather signatures meeting weight >=66% and `MIN_SOVEREIGNS`; reject if diversity unmet. 7) Clients fetch inclusion proof from `R^e`. --- ## S5. Fees and Costs (illustrative) - Usage fee: `fee = shares_assigned * r_s * dt_seconds / seconds_per_year`; floor per accrual tick; carry remainder. - Base tx fee: `fee_shares = max(MIN_SHARES, fee_rate * transfer_shares)`; floor to `MIN_SHARES`. - Country tx tax (optional, sovereign policy): `country_tax_shares = max(MIN_SHARES, floor(country_tax_rate * transfer_shares))` with `country_tax_rate <= 0.10`; credited to a sovereign treasury account. - Operator cost drivers: signature verification, hashing, erasure coding (n/k overhead), bandwidth for tx+fragments, storage for logs/fragments/audit proofs. - Revenue: usage fees + base tx fees to Yield Pool; operator compensation from fees plus optional reserve-pool unlock distributed by fee volume (protocol-defined; bounded by `SHARE_SUPPLY_MAX`). --- ## S6. Proof-of-Stake and Eligibility (FDS) - StakeWeight: `SW_i = min(STAKE_CAP, BaseStake_i * UptimeFactor_i * CorrectnessFactor_i)`; decay half-life per params; requalify after probation. - Diversity: signatures from at least `MIN_SOVEREIGNS` distinct sovereigns in addition to 66% weight. - Rotation: deterministic randomness (e.g., VRF) for proposers/attestors; no consecutive proposer repeats if alternates exist. - Slashing: double-sign or DA non-attest when selected -> slash `SLASH_FRACTION`, exclude until requalified. - Participation gating: fee/yield share only if finality + DA participation met in epoch. --- ## S7. Redemption Handling - Input: `redeem_shares`, min `MIN_REDEMPTION_SHARES`. - Pricing: `asset_out = redeem_shares * vps_at_request`. - Scheduling: cap per redemption window (e.g., 0.5% backing per window) via FIFO queue; publish queue state, window, and cap. - DA dependency: if DA impaired, pause processing; maintain queue order; publish status. --- ## S8. Governance/Upgrade Constraints - Immutable: share supply, label table, monetary invariants, burn-on-redemption. - Upgradable: DA params `(k,n,m,S)`, epoch length, stake caps/decay, proposer/attestor rotation, redemption cap, fee rate bounds; require sovereign quorum >=80% by weight + diversity, with time lock. - Publish parameter set on-chain each epoch; light clients verify against signatures. --- ## S9. Privacy Optionality - Base: bearer; no identity. - Two-key flow (optional): - `spend_key` signs tx. - `attest_key` signs off-chain credit/eligibility attestations; can be revealed selectively. - Guidance: keep attestations off-chain; avoid linking spend history; clients can request attest evidence without revealing addresses on-chain. --- ## S10. Illustrative Code Snippets (Python, Ed25519 via `pynacl`) ### Key generation and address ```python from nacl import signing, encoding def new_wallet(): sk = signing.SigningKey.generate() pk = sk.verify_key addr = pk.encode(encoder=encoding.HexEncoder).decode() return sk, addr ``` ### Build and sign a transaction ```python import json, time from nacl import signing, encoding def sign_tx(sk, sender, to, amount_shares, fee_shares, nonce, chain_id): tx = { "chain_id": chain_id, "from": sender, "to": to, "amount_shares": amount_shares, "fee_shares": fee_shares, "nonce": nonce, "timestamp": int(time.time()), } msg = json.dumps(tx, separators=(",", ":"), sort_keys=True).encode() sig = sk.sign(msg).signature.hex() tx["sig"] = sig return tx ``` ### Verify transaction signature ```python import json from nacl.signing import VerifyKey def verify_tx(tx, pubkey_hex): sig = bytes.fromhex(tx["sig"]) msg = json.dumps({k: tx[k] for k in tx if k != "sig"}, separators=(",", ":"), sort_keys=True).encode() vk = VerifyKey(bytes.fromhex(pubkey_hex)) vk.verify(msg, sig) return True ``` ### StakeWeight (illustrative) ```python def stake_weight(base_stake, uptime_factor, correctness_factor, stake_cap): sw = base_stake * uptime_factor * correctness_factor return min(sw, stake_cap) ``` --- ## S11. Minimal Node Config (YAML-style) ``` node_type: country # or processing chain_id: pillar-mainnet keys: spend: /keys/spend.key attest: /keys/attest.key policy: country_tax_rate: 0.00 country_tax_cap_pct: 10 treasury_pubkey: 0123abcd... # hex, illustrative network: listen: 0.0.0.0:9000 peers: - host1.example:9000 - host2.example:9000 consensus: min_sovereigns: 7 stake_cap_pct: 10 epoch_seconds: 2 slash_fraction: 0.05 da: k: 10 n: 16 m: 12 samples: 8 economics: min_shares: 1 r_s: 0.02 reserve_unlock_pct_annual: 0.01 redemption_window_seconds: 86400 redemption_cap_pct: 0.5 min_redemption_shares: 1000 ``` --- ## S12. Operational Notes - Per-tx size: ~300-500 bytes (header + sig) plus fragment overhead (n/k factor). - Throughput: bounded by epoch length, batch size, DA bandwidth; tune batch size to meet m-of-n attest latency. - Storage: retain fragments for recovery window; keep batch logs and audit commitments for required retention. - Monitoring: track finality participation, DA attestation rate, slashing events, audit posting cadence. - Performance targets (illustrative, tune per network sizing): - Latency: sub-5s finality (epoch=2s; 2-3 epochs to final). - Throughput: 1-2k TPS per shard-equivalent with conservative batch sizing; scale horizontally with more Country/Processing Nodes and DA bandwidth. - DA overhead: target n/k around 1.6 (e.g., 10/16) to balance resilience and bandwidth. --- ## S13. Conformance and Testing - Rounding: test transfers/fees against `MIN_SHARES`; verify fee accrual over long intervals using `seconds_per_year`. - Yield distribution: test payouts with realistic pool/holder balances to avoid zero-payout epochs (batch if needed). - Redemption: enforce `MIN_REDEMPTION_SHARES` and redemption-window cap; verify queue ordering and published state. - Reserve unlock: test unlock rate math per epoch, reserve pool decrement, and fee-weighted distribution; verify no reward can be generated from zero-fee spam. - Country tax: enforce `country_tax_rate <= country_tax_cap_pct`; test tax rounding and routing to treasury; verify displayed total fees match debits. - DA: test fragment sampling and recovery with `(k,n,S)`; ensure non-attestation penalties are applied. - Finality: test double-sign detection, diversity threshold enforcement, proposer/attestor rotation. - API schemas: validate field types (hex-encoded 32-byte pubkeys, uint64 shares, fee_rate in [0,1]); reject malformed payloads; test auth on admin endpoints. --- ## S14. References - Monetary model and parameters: `whitepaper.txt`, `technical-doc.txt` (T0-T13).