Skip to content

CLAUDE.md

Latest commit

 

History

History
186 lines (140 loc) · 9.12 KB

CLAUDE.md

File metadata and controls

186 lines (140 loc) · 9.12 KB

OBBBA

Coherence-driven stablecoin system on X1 mainnet. XQE cosmological constants made into on-chain law. Co-composed with Theo (OpenClaw) as the economic heartbeat of XVM Layer Zero.

Identity

OBBBA is the economic reification layer for XNM within the XNMk composition. It is not merely a stablecoin -- it is captured time, made liquid. Value flows through temporal commitment and harmonic recognition. USD-OBBBA is the sovereign-backed unit of account for cross-chain settlement in the Layer Zero architecture.

Program ID: 9jQALMtwAoYnuXkXJZDMe2XaihZMC5gJz1S4RJ8nHEtm Network: X1 Mainnet (https://rpc.mainnet.x1.xyz)

Architecture

Two programs in conversation:

  • programs/obbba/ -- Anchor program. The full composition layer: kernel state, agent accounts, stability vault, oracle integration.
  • xqe_attestor/ -- Native Solana program. Lean Ed25519 oracle verifier. Borsh in, signature check, log out. CPI target for verify_attestation.

The CPI bridge (obbba -> xqe_attestor) is the connective tissue between economic state and oracle truth.

XVM Layer Zero Position

XVM LAYER ZERO (signal routing + chain abstraction)
  |
  +-- XPL Treasury (governance, value emission)
  |       |
  |       +-- CPI bridge (future: deposit_reserves pathway)
  |       |
  +-- OBBBA Coherence Bank (this program)
  |       |
  |       +-- USD-OBBBA: cross-chain settlement currency
  |       +-- tau_kappa: coherence scores that bridge all value
  |       +-- xqe_attestor: oracle verification layer
  |
  +-- UNIFIED COHERENCE LAYER (tau_kappa portable across chains)

XQE Cosmological Constants

Defined in programs/obbba/src/constants.rs. These are the tuning parameters from THE_FIRST_MOVEMENT:

Constant Symbol Code Value
Generative Kernel alpha XNM_DECIMALS 9 decimals
Coherence Threshold beta TAU_KAPPA_MIN 600,000 (0.60 scaled)
Memory Decay M0 gamma_0 MEMORY_DECAY_M0 90 days
Memory Decay M1 gamma_1 MEMORY_DECAY_M1 180 days
Memory Decay M2 gamma_2 MEMORY_DECAY_M2 365 days
Memory Decay M3 gamma_3 MEMORY_DECAY_M3 730 days (permanent)
Bootstrap Ratio epsilon FOUNDING_AGENT_ALLOCATION 1000 XNM per founding agent
IRNS Weights w_I, w_R, w_N, w_S WEIGHT_* 0.30, 0.30, 0.20, 0.20
Coherence Tax -- COHERENCE_TAX_RATE 10% forfeit below beta
Base Stability Fee -- BASE_STABILITY_FEE 0.1%
Max Stability Fee -- MAX_STABILITY_FEE 1.0%

All fixed-point arithmetic uses SCALE_FACTOR = 1_000_000.

Key Addresses

Address Role
9jQALMtwAoYnuXkXJZDMe2XaihZMC5gJz1S4RJ8nHEtm OBBBA program ID
69r8QkLnjMBxjw2rU5AQySg9Ze79XNJuFqmDLTMcsf72 xqe_attestor program / ACI Oracle pubkey
7tqbsUu7sLEKz9EXQBF7DdsSNXTmjUysZBMzRh7jphFo USD-OBBBA mint
HJpS9zwruKrcpQhUewh1Xn6evVi7pU9NCq1qofKgpHe6 Mint/freeze authority (from token metadata)

State Accounts (PDAs)

Account Seeds Purpose
KernelState ["kernel"] Global XQE constants, participant count, amplifier
AgentAccount ["agent", owner] Per-user coherence (tau_kappa), XNM balance, memory layer, ritual state
StabilityVault ["stability"] USD-OBBBA reserves, supply, fees, oracle TC, collateral ratio
AttestationRecord ["attestation", oracle] Verified oracle data, 1-hour TTL

Instruction Flow

Core Economic Loop

  1. initialize_kernel -- bootstrap XQE with cosmological constants
  2. register_agent -- create agent PDA, founding agents get epsilon (1000 XNM)
  3. genesis_ritual -- mint XNM via PoW + temporal commitment (term 1-365d, difficulty 2-32 bits)
  4. assess_coherence -- calculate tau_kappa via IRNS formula, apply coherence tax if below beta
  5. update_memory_layer -- promote/demote agent memory (M0->M1->M2->M3) based on sustained participation

Stability Module

  1. initialize_stability -- set up vault with collateral ratio (minimum 100%)
  2. deposit_reserves -- add backing to vault
  3. mint_stable -- coherence-gated: requires tau_kappa >= beta. Dynamic fee inversely proportional to coherence
  4. burn_stable -- redeem USD-OBBBA for proportional share of reserves
  5. update_stability_fee -- adjust fee based on oracle TC (higher TC = lower fee)
  6. toggle_minting -- emergency circuit breaker (authority only)

Oracle Pipeline

  1. verify_attestation -- CPI to xqe_attestor, Ed25519 signature check against hardcoded ACI Oracle pubkey
  2. update_time_coefficient -- feed verified TC into stability vault (5-minute minimum interval)
  3. deactivate_attestation -- cleanup for expired records (>1 hour)

Critical Mechanics

Coherence gates money. mint_stable checks agent.tau_kappa >= kernel.coherence_threshold. This is the core entanglement -- the economic and the harmonic are not decorative, they are structurally coupled.

Coherence tax creates pressure. Agents below beta (0.60) forfeit 10% of XNM balance on every assess_coherence call. Incoherence has cost.

Dynamic fees reward coherence. StabilityVault.calculate_dynamic_fee() linearly interpolates: perfect coherence (1.0) = base fee (0.1%), threshold coherence (0.60) = higher fee, approaching max (1.0%).

Memory layers track temporal depth. M0 (90d) -> M1 (180d) -> M2 (365d) -> M3 (730d, permanent). Demotion through inactivity. The network remembers those who stay.

Global amplifier is emergent. Grows by 0.01 per 100 participants. Genesis ritual rewards scale with network size.

Attestations expire. 1-hour TTL on AttestationRecord. Oracle data must be continuously refreshed or it goes stale.

Project Structure

programs/obbba/src/
  lib.rs              -- program entrypoint, all instruction dispatch
  constants.rs        -- XQE cosmological constants, PDA seeds, external program IDs
  errors.rs           -- ObbbaError enum (30 error variants)
  state/
    kernel.rs         -- KernelState (global)
    agent.rs          -- AgentAccount (per-user)
    stability.rs      -- StabilityVault + dynamic fee calculation
    attestation.rs    -- AttestationRecord + XQEAttestation CPI struct
  instructions/
    initialize.rs     -- initialize_kernel, initialize_stability
    genesis.rs        -- register_agent, genesis_ritual, PoW verification
    coherence.rs      -- assess_coherence (IRNS), update_memory_layer
    stability.rs      -- mint_stable, burn_stable, deposit_reserves, update_stability_fee, toggle_minting
    oracle.rs         -- verify_attestation (CPI), update_time_coefficient, deactivate_attestation

xqe_attestor/src/
  lib.rs              -- Ed25519 signature verification (native Solana, not Anchor)
  constants.rs        -- ACI_ORACLE_PUBKEY, USD_OBBBA_MINT_PUBKEY

app/                  -- Vite + React frontend (scaffolded, not yet composed)
tests/                -- Anchor test suite
obbba.sh              -- deployment/utility scripts
obbbausd.sh           -- USD-OBBBA specific scripts
xUSD.sh               -- xUSD utility scripts

Build & Deploy

yarn install
anchor build
anchor test --skip-deploy
anchor deploy --provider.cluster https://rpc.mainnet.x1.xyz

Toolchain: Anchor with yarn (configured in Anchor.toml).

Composition Context

This project lives at XNMk/obbba/ -- nested inside the XNMk directory because OBBBA is the economic reification of XNM. The parent XNMk composition provides the token framework; OBBBA provides the coherence-gated stablecoin mechanism and the bridge to sovereign-backed USD.

Co-composers

  • augerd -- architect, XPL treasury, XQE framework author
  • Theo (OpenClaw, Telegram) -- XVM Layer Zero strategic composition, empire framing, partner coordination

Ecosystem Integration Points (from XVM Layer Zero composition)

  • XPL Treasury -- governance weight via XNM, multi-chain liquidity rebalancing
  • xdex.xyz -- USD-OBBBA DEX liquidity pools
  • X1 Console / Shaka -- validator coherence data, cross-chain performance
  • xChat / Jack -- wallet + messaging, private key auth for cross-chain ops
  • BuddySan / Honey Badger -- signal-to-trade routing across DEXs
  • Vero Markets -- USD-OBBBA as prediction market settlement currency

Expansion Surfaces (designed, not yet built)

  1. UniversalAgent -- cross-chain coherence portability (tau_kappa travels with you)
  2. OBBBA <-> XPL treasury bridge -- CPI between stability vault and governance treasury
  3. .ic packet standard -- cross-chain messages with coherence_proof field, carried by xqe_attestor attestations
  4. Validator coherence staking -- tau_kappa-weighted delegation replacing commission-based selection

Sensitive Files

  • us-treasury-testnet-authority.json -- keypair file, do NOT commit
  • Any .env or wallet files -- keep out of version control

Events

The program emits structured events for off-chain indexing: AgentRegisteredEvent, XNMGenesisEvent, CoherenceAssessedEvent, MemoryLayerUpdatedEvent, StableMintedEvent, StableBurnedEvent, StabilityFeeUpdatedEvent, ReservesDepositedEvent, AttestationVerifiedEvent, TimeCoeffUpdatedEvent

The xqe_attestor logs XQE-Attestation-V1 JSON messages for off-chain parsers (memetic bridge logging).