agora/docs/agora-requirements-06-exchange-and-contracts.org

#+TITLE: Agora Requirements - 06: Exchange
#+author: Amero Garcia
#+created: [2026-03-16 Mon 14:28]
#+DATE: 2026-03-15
#+ID: agora-requirements-06-exchange
#+STARTUP: content

* Exchange

** Concept

The Exchange layer provides the economic substrate of Agora: value transfer via the Lightning Network, multi-currency support, and payment primitives. Built on top of Content Objects (see [[file:agora-requirements-04-the-primitive.org][The Primitive]]) and Social relationships (see [[file:agora-requirements-05-social.org][Social]]).

** Lightning Native

** Base Currency

Lightning Network (Bitcoin L2) is the default payment rail:
- *Minimum:* 1 satoshi
- *Maximum:* Channel capacity limited
- *Speed:* Near-instant for settled payments
- *Cost:* Fraction of a cent per transaction

** Payment Types

**** One-shot Payment
- Single payment for content or service
- Invoice generated, payment fulfilled, preimage reveals

**** Streaming Payment
- Continuous micropayments (per-second, per-action)
- Used for subscriptions, metered services
- Automatic via HTLC stream

**** Hodl Invoice
- Escrow with hash-locked release
- Payment committed but conditional on secret

**** Keysend
- Spontaneous payment without invoice
- Used for tips, donations

** Lightning Node Architecture

The specification currently lacks explicit guidance on how end users run Lightning nodes. Below are the three architectural options under consideration:

**** Option 1: Embedded LDK Node (Self-Sovereign)
- Each user's client (desktop/mobile) runs an embedded Lightning node using LDK (Lightning Dev Kit)
- User has full custody of keys; channels are mobile-friendly (LSP-managed)
- PDS handles the always-online requirement since user devices aren't
- Aligns with Agora's "sovereign" philosophy but requires technical sophistication

**** Option 2: LSP (Lightning Service Provider) Model
- User connects to an LSP that provides inbound liquidity and accepts payments on their behalf
- User still has signing keys locally; LSP manages channels and uptime
- User can switch LSPs without losing funds (Lightning hygiene)
- Most realistic for mobile users; PDS providers may bundle LSP services

**** Option 3: Custodial Bridge (On-ramp)
- PDS offers built-in custodial Lightning wallet for users who don't want self-custody
- Users can withdraw to self-custody later (exit guarantee)
- Default for new users, opt-in for sovereignty
- Trade-off: convenience vs. full sovereignty

**** Key Distinction: Custody vs. Hosting
Non-custodial means *you* control the private keys, not where the software runs. Even if the Lightning node runs on hosted PDS infrastructure, it can still be *your* node with *your* keys:
- Your PDS gets encrypted data (content)
- Your Lightning node gets encrypted state (channel backups)
- Both are encrypted to *your* keys
- The PDS provider cannot sign transactions or spend your funds

**** GAP: Decision Required
The specification has not yet decided between:
- Requiring all users to run embedded nodes (sovereign, high technical barrier)
- Defaulting to LSP connections (practical, retains key custody)
- Offering custodial as default with opt-out (maximum adoption, sovereignty trade-off)

*Next Step:* Evaluate technical feasibility of LSP integration with PDS providers and document recommended architecture for V1.0.

** Multi-Currency Support

** Supported Currencies

- *Lightning (default):* For micro-payments (<$1)
- *On-chain Bitcoin:* For settlements, channel opens
- *Stablecoins (RGB):* USDT/USDC on Bitcoin L2

** Currency Routing
- Client specifies desired currency
- PDS may support conversion
- Exchange rates oracle-attested

** Concept

The Agora protocol must support multiple currencies beyond Lightning-native satoshis to facilitate broader economic participation and provide stability options. While Lightning remains the primary rail for micro-payments, other assets will be integrated for larger transactions and specific use cases.

** Supported Currencies

**** Lightning Network (L2 Bitcoin)
- *Role:* Primary for all micro-payments (typically <$10).
- *Mechanism:* BOLT-compatible invoices, streaming payments, Keysend.

**** On-chain Bitcoin
- *Role:* For large settlements, channel opens/closes, long-term value storage.
- *Mechanism:* Standard Bitcoin transactions, multi-sig escrow.

**** Stablecoins
- *Role:* For price stability, high-volume transactions, fiat-pegged value.
- *Mechanism:* RGB protocol on Bitcoin (future), wrapped assets on compatible L2s, or direct integration with atomic swaps.

** Currency Routing & Conversion

**** Client-Side Preference
- Users specify preferred payment currencies for sending and receiving.
- Clients automatically attempt conversion if sender's and receiver's preferred currencies differ.

**** PDS/Relay Support
- PDS nodes MAY offer automated currency conversion services (e.g., satoshis to stablecoins).
- Fees for conversion MUST be transparent and competitive.
- Conversion services MUST be auditable (using attestations).

**** Exchange Rate Verification (Oracle)
- The system MUST use a decentralized oracle network to attest to current exchange rates.
- Exchange rate attestations are signed Content Objects.
- Clients verify oracle signatures and rate validity before conversion.

** Integration with Contracts

- Contracts (e.g., Sale, Service) MUST specify accepted currencies.
- Prices in contracts MUST be expressed in a base unit (e.g., satoshis) with optional equivalent in other currencies.
- Exchange rates for contract execution MUST be based on oracle attestations at time of execution.

** Economic Primitives

** Invoice
- BOLT-11 compliant
- Amount, memo, expiry
- Static (LNURL) or dynamic

** Payment
- Preimage proof of settlement
- Content-addressed for audit trail
- Refundable if escrowed

** Account
- DID-linked balance tracking
- Multi-currency support
- Reconciliation with on-chain

** Fee Structure

** Relay Fees
- Per-message routing (configurable)
- Subscription-based access
- Priority delivery premium

** PDS Fees
- Storage: per-GB per month
- Bandwidth: per-request or per-GB
- Compute: for AI, indexing

** Marketplace Fees
- Owner-defined (0-30%)
- Universal Open Market: minimal (relay costs)

** Exchange Primitives

** Escrow

Hold funds until conditions met:
- 2-of-3 multisig (buyer, seller, arbitrator)
- HTLC hash-time-locked contracts
- Smart contract on compatible L2

** Subscription

Ongoing economic relationship:
- Streaming Lightning payments
- Permissioned content access
- Automatic key provision

** Bounty

Payment for task completion:
- Escrowed funds
- Completion attestation
- Oracle verification option

** Sovereign Contract & Arbitration Layer (SCAL)

To enable Personas to execute binding agreements with decentralized dispute resolution, Agora implements SCAL. A contract in this system is not a static PDF; it is an executable cryptographic object.

*** 1. The Ricardian Contract Module
Agora contracts follow the Ricardian model, ensuring they are both human-readable and machine-executable.
- *Natural Language (The Markdown):* The human-readable terms of the agreement (e.g., "Person A delivers 100 bricks to Person B by Friday").
- *Machine Logic (The JSON-LD):* The executable parameters embedded in the Note's metadata (e.g., `due_date: 2026-01-16`, `price_sats: 50000`, `arbitrator_did: did:key:xyz`).
- *The Merkle Link:* Both parts are hashed together into a single Content Identifier (CID). If a single comma is changed in the text, the hash changes, breaking the digital contract. This ensures the "Code" and the "Law" remain identical.

*** 2. Payment & Escrow: The "HODL Invoice"
For service delivery and physical goods, Agora relies on Lightning HODL Invoices as a trustless escrow, removing the need for a custodial middleman.
- *Commitment:* The Buyer "pays" the invoice. The funds leave their Lightning wallet but remain cryptographically locked in the network routing nodes.
- *The Proof:* The Seller observes the network state, sees the funds are "Locked," and confidently delivers the goods or services.
- *Settlement:* Once the Buyer confirms receipt, they release the cryptographic Preimage (the key). The money instantly settles to the Seller.
- *Dispute:* If a problem arises, the funds stay locked. An agreed-upon Arbitrator intervenes, eventually providing the key to either the Buyer (triggering a Refund) or the Seller (forcing a Payout).
- *Timeout Logic:* Contracts MUST include a `CLTV-expiry` (CheckLockTimeVerify). If the arbitrator does not rule within a predefined window (e.g., 30 days), the funds are automatically returned to the Buyer to prevent "Forever-Locks."

*** 3. Proof-of-Delivery (Oracles)
To automate the release of HODL invoices without manual buyer intervention, SCAL supports cryptographic Proof-of-Delivery.
- *Physical Goods:* Support for "Scanning a QR code" upon physical delivery, which automatically signs the release transaction and broadcasts the Preimage.
- *Digital Goods:* Support for Zero-Knowledge Proofs (ZKP). The payment is released automatically once the client cryptographically verifies that the received file hash matches the contracted payload.

*** 4. Multi-Level Arbitration & The Ricardian Evidence Vault
To address disputes without a central state, contracts reference a tiered system of human judgment (The "Circles" Model). As detailed in the [[file:agora-requirements-10-governance-and-assets.org][Governance]] specifications, this involves escalating from Local Elders to specialized Guilds, and finally to Global Juries.
- *Web of Trust (WoT) Level 1:* Arbitrators at Level 1 are selected based on Transitive Trust (e.g., the system finds a mutual connection trusted by both parties within 3 degrees of separation).
- *Ricardian Evidence Vault:* During a dispute, parties upload encrypted "Evidence Blobs" to their PDS. Using Zero-Knowledge Proofs (ZKPs) or Shared Keys, they grant the current level of arbitrators temporary read-access to the evidence without making it public.
- *Real-Time Adjudication:* If live hearings are required, the system MUST support VoIP/WebRTC signaling conducted over an authenticated DIDComm v2 channel, utilizing "blind" Community TURN servers if direct P2P fails.
- *Audit Trail:* Every ruling, appeal, and evidence hash is permanently stored in the Key Event Log (KEL) for that specific contract, creating a verifiable record of the "trial."

*** 5. Enforcement: Social vs. Financial
In weak rule-of-law environments, the system relies on two "sticks" to ensure contract compliance without physical police forces:
- *Financial Collateral:* High-risk contracts can require both parties to lock "Safety Deposits" in a 2-of-3 multisig before the contract begins. If a party defects, they forfeit their deposit.
- *Reputation Slashing (Social Enforcement):* If a Persona loses an arbitration and refuses to comply, their DID is cryptographically "Flagged" across the public network. Because DIDs are persistent and tied to social graphs, they cannot simply delete their account to escape the penalty. Their "Trust Score" drops to zero, effectively cutting them off from future trade, employment, or community participation.

** Integration with Content Objects

Economic actions are specialized Notes containing structured `contract` metadata:

- *Invoice:* Contract offer Note containing payment terms (`price_satoshis`, `bolt11`).
- *Payment:* Contract fulfillment Note (`Take`) containing cryptographic proof (`preimage`).
- *Escrow:* Contract state Note referencing a multi-signature threshold or conditional logic.
- *Subscription:* Ongoing contract Note with streaming parameters or recurring billing cycles.

Transactions reference the Content Objects they interact with:
- Payment Note `reply_to` the Invoice Note being fulfilled.
- Subscription Note `references` the Feed CID it provides access to.
- Bounty Note (Contract) `references` the Task description.

** Content Monetization & Seeder Rewards

To monetize high-bandwidth content (like video or software) in a decentralized, permissionless network, Agora utilizes a combination of Split-State Encryption, the LSAT protocol, and granular Lightning network routing. This ensures creators get paid without relying on centralized DRM or hosting providers.

*** 1. The Encrypted Swarm (Blind CDN)
If you want to charge for a video, you cannot send the raw file into the P2P swarm. If you did, the first "seeder" would simply share the unencrypted version for free.
- *The Locked Box:* The creator encrypts the video with a unique Symmetric Key.
- *The Split Structure:* The Note's `contract` field is Public (listing the price, title, and terms), but the `payload` field is a CID pointing to the encrypted video chunks.
- *Blind Replication:* Followers and network participants host and seed this encrypted `payload`. They act as a "Blind CDN" (Content Delivery Network)—hosting a file they cannot see.

*** 2. The LSAT Protocol (The Smart Ticket)
To automate the purchase and unlocking of this content, Agora uses LSATs (Lightning Service Authentication Tokens).
- *The 402 Challenge:* When a viewer clicks "Play," their client attempts to fetch the payload. The PDS responds with an HTTP 402 (Payment Required) error, containing a Lightning Invoice (generated based on the `contract` terms) and a "Macaroon" (a digital ticket).
- *The Unlock:* Once the user pays the invoice (e.g., 100 sats), they receive a cryptographic Preimage (proof of payment). They send this Preimage back to the PDS.
- *The Result:* The PDS validates the proof and releases the Decryption Key. The video decodes instantly on the client's device. The data may have been downloaded from a friend's PDS (the swarm), but the permission to view it was purchased securely from the creator.

*** 3. Incentivizing the Seeders (Paid Seeding)
One of Agora's most innovative features is "Seeder Micro-Rewards." If a follower provides the bandwidth that allows a creator's content to go viral, the network can programmatically share the revenue.
- *The Split Payment:* The Note's `contract` can define a Lightning routing split. When the 100 sats are paid via the LSAT, the network routes the funds accordingly:
  - *90 sats* go to the Creator.
  - *5 sats* go to the Indexing Relay.
  - *5 sats* go to the Seeder (the specific follower who provided the data bits).
- *The Economic Shift:* "Following" an NGO or an indie creator becomes a way to earn a tiny amount of Bitcoin while supporting their mission. The better the content you seed, the more "tips" your server collects for providing the bandwidth.

*** Physical Collateralization
In environments with weak state enforcement, Agora enables the use of physical assets as cryptographically-secured collateral via the PAL (Physical Asset Linking) protocol.

- *The Pledge:* A user links a Digital Twin token (representing a physical asset like a car or machine) to a Civil Contract Note.
- *The Lock:* The contract's logic "freezes" the Digital Twin token. While the user maintains physical possession of the asset, they are cryptographically barred from selling or transferring the digital title until the contract obligations (e.g., a loan repayment) are met.
- *Enforcement:* Severe defaults can trigger the "IoT Stick" (see [[file:agora-requirements-07-advanced-integration.org][Advanced Integration]]), where an IoT-enabled smart lock physically disables the asset based on an Arbitration (HDR) ruling.

** Advanced Exchange Features

** Cross-Chain Swaps

**** Atomic Swaps Architecture
Agora enables seamless value transfer between Bitcoin and other blockchains without relying on centralized exchanges.
- *HTLC Contracts:* Hash Time-Locked Contracts (HTLCs) are used to lock assets on both chains simultaneously.
- *Swap Personas:* Specialized Personas (Market Makers) provide liquidity and act as counterparties for atomic swaps, competing on fees and speed.
- *Protocol Integration:* A `CrossChainSwap` Content Object defines the terms (rate, chains, timelock). Once agreed, both parties publish the HTLCs on their respective chains. The revelation of the preimage on one chain allows claiming the funds on the other.

** Stablecoin Integration

**** RGB Protocol Specification
Stablecoins (e.g., USDT, USDC) are supported natively as Layer 2 assets on top of Bitcoin/Lightning using the RGB protocol.
- *Asset Issuance:* Stablecoin issuers maintain a Genesis Contract on Agora defining the asset's RGB schema and initial supply.
- *Client Support:* Agora clients MUST integrate an RGB node alongside their Lightning node to parse client-side validated state transitions.
- *Payment Routing:* RGB assets are routed over standard Lightning channels. Clients construct invoices that specifically request the RGB stablecoin asset ID instead of raw satoshis.
- *PDS Storage:* The client-side validation data (consignment) for RGB assets is stored as encrypted Content Objects in the user's PDS, ensuring the user maintains full custody of the asset's history.

** Subscription Management

**** Complex Recurring Billing Logic
Agora handles recurring payments natively without centralized payment processors.
- *Subscription Objects:* A `SubscriptionContract` defines the terms: amount, currency, billing cycle (e.g., monthly, weekly), and grace period.
- *Streaming vs. Discrete Billing:* 
  - For continuous services (e.g., Relay access), streaming payments (sats/second) are preferred.
  - For discrete access (e.g., monthly newsletter), the client software automatically generates a local cron job to pay the creator's static LNURL-pay endpoint at the start of each billing cycle.
- *Grace Periods & Revocation:* If a recurring payment fails (due to offline client or insufficient funds), the provider's PDS logs a `PaymentFailed` event. The subscriber is granted a predefined grace period (e.g., 3 days). If unresolved, the provider's PDS automatically revokes the decryption keys for the subscribed content.

** Related Documents

- [[file:agora-requirements-04-the-primitive.org][The Primitive]] - Content Object structure
- [[file:agora-requirements-05-social.org][Social]] - Connection types for economic relationships
- [[file:agora-requirements-02-identity.org][Identity]] - Contracts and attestations

** Gaps

- *None.* All identified gaps in the exchange layer have been resolved.