DeBros/orama
4
0
Fork 0
mirror of https://github.com/DeBrosOfficial/orama.git synced 2026-05-01 05:04:13 +00:00
Code Issues Packages Projects Releases Wiki Activity

Changes

Browse Source
This commit is contained in:
anonpenguin23 2026-03-28 14:58:25 +02:00
parent f3f4a84762
commit b9b6e19bb8
8 changed files with 0 additions and 2095 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

71
whitepaper/APPENDIX_A_EMISSION_CURVE.md
View File

@ -1,71 +0,0 @@
# Appendix A: Emission Curve & Halving Schedule
## Parameters
- **Total supply:** 210,000,000 $ORAMA (hard cap)
- **Block time:** 6 seconds
- **Blocks per day:** 14,400
- **Blocks per year:** 5,256,000
- **Block reward split:** 80% to block proposer, 20% to bonding curve inventory (capped at 21M total to curve)
- **Halving interval:** Every 2 years (~10,512,000 blocks)
## Detailed Emission Table
| Era | Years | Block Reward | Blocks in Era | Era Emission | To Miners (80%) | To Curve (20%) | Cumulative Supply | % of Total |
|-----|-------|-------------|---------------|-------------|-----------------|----------------|-------------------|-----------|
| 1 | 1–2 | 100 $ORAMA | 10,512,000 | 105,120,000 | 84,096,000 | 21,024,000 | 105,120,000 | 50.03% |
| 2 | 3–4 | 50 $ORAMA | 10,512,000 | 52,560,000 | 42,048,000 | 10,512,000 | 157,680,000 | 75.04% |
| 3 | 5–6 | 25 $ORAMA | 10,512,000 | 26,280,000 | 21,024,000 | 5,256,000 | 183,960,000 | 87.52% |
| 4 | 7–8 | 12.5 $ORAMA | 10,512,000 | 13,140,000 | 10,512,000 | 2,628,000 | 197,100,000 | 93.76% |
| 5 | 9–10 | 6.25 $ORAMA | 10,512,000 | 6,570,000 | 5,256,000 | 1,314,000 | 203,670,000 | 96.88% |
| 6 | 11–12 | 3.125 $ORAMA | 10,512,000 | 3,285,000 | 2,628,000 | 657,000 | 206,955,000 | 98.44% |
| 7 | 13–14 | 1.5625 $ORAMA | 10,512,000 | 1,642,500 | 1,314,000 | 328,500 | 208,597,500 | 99.22% |
| 8 | 15–16 | 0.78125 $ORAMA | 10,512,000 | 821,250 | 657,000 | 164,250 | 209,418,750 | 99.61% |
| 9 | 17–18 | 0.390625 $ORAMA | 10,512,000 | 410,625 | 328,500 | 82,125 | 209,829,375 | 99.81% |
| 10 | 19–20 | 0.195313 $ORAMA | 10,512,000 | 205,313 | 164,250 | 41,063 | 210,034,688 | 99.90% |
*Emission continues halving indefinitely. When the remaining emittable supply is less than the block reward, the block reward equals the remaining supply — ensuring the 210,000,000 hard cap is never exceeded.*
## Cumulative Supply Over Time
```
Year 1: 52,560,000 $ORAMA (25.0%)
Year 2: 105,120,000 $ORAMA (50.0%) ← First halving
Year 4: 157,680,000 $ORAMA (75.0%) ← Second halving
Year 6: 183,960,000 $ORAMA (87.5%)
Year 8: 197,100,000 $ORAMA (93.8%)
Year 10: 203,670,000 $ORAMA (96.9%)
Year 20: ~210,000,000 $ORAMA (99.9%)
```
## Daily Emission by Era
| Era | Daily Total Emission | Daily to Miners | Daily to Curve |
|-----|---------------------|----------------|----------------|
| 1 | 1,440,000 $ORAMA | 1,152,000 | 288,000 |
| 2 | 720,000 $ORAMA | 576,000 | 144,000 |
| 3 | 360,000 $ORAMA | 288,000 | 72,000 |
| 4 | 180,000 $ORAMA | 144,000 | 36,000 |
| 5 | 90,000 $ORAMA | 72,000 | 18,000 |
## Per-Node Earnings Estimates (Era 1)
Assumes equal Effective Power across all nodes (simplified):
| Total Nodes | Daily per Node | Monthly per Node |
|-------------|---------------|-----------------|
| 300 | 3,840 $ORAMA | 115,200 $ORAMA |
| 500 | 2,304 $ORAMA | 69,120 $ORAMA |
| 1,000 | 1,152 $ORAMA | 34,560 $ORAMA |
| 5,000 | 230 $ORAMA | 6,912 $ORAMA |
| 10,000 | 115 $ORAMA | 3,456 $ORAMA |
*Actual earnings vary by Effective Power (stake × contribution × infrastructure multiplier).*
## Key Properties
1. **50% emitted in first 2 years** — rewards early risk-takers who secure the network when it's most vulnerable.
2. **75% emitted by year 4** — strong incentive to join early.
3. **96.9% emitted by year 10** — after a decade, the network runs primarily on transaction fee revenue.
4. **Never reaches 210M exactly** — the halving creates an asymptotic approach, just like Bitcoin's 21 million.
5. **Predictable at every block** — anyone can calculate the exact circulating supply at any block height with simple arithmetic.

58
whitepaper/APPENDIX_B_HARDWARE_SPECS.md
View File

@ -1,58 +0,0 @@
# Appendix B: Orama One Hardware Specs
## Design Principles
Orama One is designed so that anyone, anywhere, can afford to run a node. The hardware requirements are intentionally modest — the protocol is optimized for accessibility, not raw performance. Scaling is achieved through more nodes, not bigger nodes.
## Orama One — Standard Node
**Form factor:** 3D-printed compact enclosure, fanless, suitable for home use.
**Open-source:** Enclosure design files, bill of materials, and assembly guide will be published so anyone can build their own.
### Minimum Specifications
| Component | Specification | Purpose |
|-----------|--------------|---------|
| **CPU** | 4+ cores, 2.0+ GHz (ARM or x86) | Block validation, WASM execution, consensus |
| **RAM** | 8 GB | Distributed cache, state management |
| **Storage** | 256 GB NVMe SSD | Blockchain state, IPFS storage, SQL database |
| **Network** | 1 Gbps Ethernet | Encrypted mesh, block propagation, data serving |
| **TPM** | TPM 2.0 module | Infrastructure attestation for OramaOS multiplier |
| **Power** | Low power draw (target: under 25W) | Continuous operation at minimal energy cost |
### Recommended Specifications
| Component | Specification |
|-----------|--------------|
| **CPU** | 6+ cores, 2.4+ GHz |
| **RAM** | 16 GB |
| **Storage** | 512 GB NVMe SSD |
| **Network** | 2.5 Gbps Ethernet |
## Cloud Node — Minimum Specs
For operators who prefer cloud hosting over physical hardware.
| Component | Specification |
|-----------|--------------|
| **vCPUs** | 2+ cores |
| **RAM** | 4 GB |
| **Storage** | 80 GB SSD |
| **Bandwidth** | 1 TB/month |
| **OS** | OramaOS image |
Cloud nodes receive the OramaOS multiplier (1.5×) the same as any other node running OramaOS. The multiplier is based on the operating system, not the hardware.
## Compute Provider Node — Additional Specs
For operators who want to participate in the AI Marketplace (optional).
| Component | Specification | Purpose |
|-----------|--------------|---------|
| **Accelerator** | High-performance GPU or AI accelerator | AI model inference |
| **Accelerator memory** | 24 GB+ | Model loading |
| **RAM** | 32 GB+ | Data preprocessing |
| **Storage** | 1 TB+ NVMe SSD | Model storage |
| **Network** | High-throughput connection recommended | API serving |
Compute provider nodes must also meet standard node specs. Compute capacity is registered separately on the AI Marketplace. Compute providers earn standard block rewards from their base node plus marketplace revenue from AI API calls.

91
whitepaper/APPENDIX_C_BONDING_CURVE.md
View File

@ -1,91 +0,0 @@
# Appendix C: Bonding Curve Price Table & BTC Reserve Projections
## Curve Formula
$$
\text{Price (BTC)} = k \times \sqrt{n}
$$
Where:
- `k = 0.0000000006 BTC` (genesis constant)
- `n` = total number of $ORAMA tokens sold from the curve
## Total Cost Formula
The cumulative BTC required to purchase the first N tokens from the curve:
$$
\text{Total BTC} = k \times \frac{2}{3} \times n^{3/2}
$$
## Detailed Price Table
| Tokens Sold (n) | Price per $ORAMA (BTC) | Price (USD at $100K BTC) | Cumulative BTC Spent | Cumulative USD Spent |
|---|---|---|---|---|
| 1 | 0.0000000006 | $0.00006 | 0.0000000004 | $0.00004 |
| 100 | 0.000000006 | $0.0006 | 0.0000004 | $0.04 |
| 1,000 | 0.000000019 | $0.0019 | 0.000012 | $1.27 |
| 10,000 | 0.00000006 | $0.006 | 0.0004 | $40 |
| 50,000 | 0.000000134 | $0.0134 | 0.00447 | $447 |
| 100,000 | 0.00000019 | $0.019 | 0.0127 | $1,265 |
| 500,000 | 0.000000424 | $0.0424 | 0.141 | $14,142 |
| 1,000,000 | 0.0000006 | $0.06 | 0.4 | $40,000 |
| 2,000,000 | 0.000000849 | $0.0849 | 1.131 | $113,137 |
| 5,000,000 | 0.00000134 | $0.134 | 4.47 | $447,214 |
| 10,000,000 | 0.0000019 | $0.19 | 12.65 | $1,264,911 |
| 15,000,000 | 0.00000232 | $0.232 | 23.24 | $2,323,790 |
| 21,000,000 | 0.00000275 | $0.275 | 38.49 | $3,849,002 |
## BTC Protocol Reserve Accumulation
As tokens are purchased from the curve, BTC accumulates in the protocol reserve:
| Milestone | BTC in Reserve | USD Value | What This Backs |
|---|---|---|---|
| First 100K tokens sold | 0.013 BTC | $1,265 | Minimal — early days |
| First 1M tokens sold | 0.4 BTC | $40K | Small but growing reserve |
| First 5M tokens sold | 4.47 BTC | $447K | Meaningful bridge backing |
| First 10M tokens sold | 12.65 BTC | $1.27M | Substantial reserve |
| Full curve (21M sold) | **38.49 BTC** | **$3.85M** | Full reserve capacity |
## Curve Inventory Supply
The curve's sell-side inventory comes from 20% of block rewards, **capped at 21,000,000 $ORAMA total**. Once the curve has accumulated 21M tokens (whether sold or unsold), the 20% share redirects to the block proposer.
| Era | Daily Curve Inventory Added | Monthly | Era Total (2 years) |
|---|---|---|---|
| 1 (Years 1–2) | 288,000 $ORAMA | 8,640,000 | 21,024,000 |
| 2 (Years 3–4)* | 144,000 $ORAMA | 4,320,000 | 10,512,000 |
*The 21M cap will likely be reached during Era 1. Once reached, no further tokens flow to the curve regardless of era.*
## Curve vs Order Book Interaction
The curve and the order book coexist. The real market price is determined by organic supply and demand on the order book:
**Scenario: Curve price > Order book price (typical early on)**
- Miners sell on the order book at prices below the curve
- Buyers purchase from the order book (cheaper)
- The curve sits unused, accumulating inventory
- This is normal — miners have surplus tokens and need to sell
**Scenario: Order book price > Curve price (as demand grows)**
- Order book is more expensive than the curve
- Buyers purchase from the curve instead
- BTC flows into the protocol reserve
- The curve provides a price ceiling in this scenario
**Scenario: After sunset**
- Curve stops receiving new inventory
- All trading happens on the order book
- The curve may still have leftover inventory available at its last price point
- Pure free market
## Sunset Conditions
The curve's 20% share of block rewards drops to 0% when:
1. Average daily order book volume exceeds the governance-defined threshold
2. This threshold is maintained for 30 consecutive days
3. The change is automatic — no vote required
After sunset, the 20% that previously went to the curve flows directly to block proposers (miners receive 100% of block rewards).

98
whitepaper/APPENDIX_D_PLONK_SETUP.md
View File

@ -1,98 +0,0 @@
# Appendix D: PLONK Trusted Setup Ceremony Specification
## Overview
Orama's privacy features (public/private transaction toggle) use PLONK-based zk-SNARKs. PLONK requires a one-time **universal trusted setup** that generates a Structured Reference String (SRS). This SRS is used by all provers and verifiers on the network.
The setup ceremony is performed once during testnet (Q1 2027) and the resulting SRS is embedded in the genesis block at mainnet launch.
## Why PLONK Over Groth16
| Property | Groth16 | PLONK |
|---|---|---|
| Trusted setup | Per-circuit (new ceremony for every change) | Universal (one ceremony, valid for all circuits) |
| Proof size | ~200 bytes | ~500 bytes |
| Verification time | ~3ms | ~5ms |
| Upgradeability | Requires new ceremony | Same SRS works for new circuits |
| Security assumption | 1-of-N honest participants | 1-of-N honest participants |
PLONK's universal setup means Orama can add new privacy features (new transaction types, private smart contract calls, private DEX orders) without ever running another ceremony.
## Ceremony Design
### Multi-Party Computation (MPC)
The setup uses a sequential MPC protocol where each participant:
1. Receives the output of the previous participant
2. Mixes in their own randomness (called "toxic waste")
3. Destroys their randomness
4. Passes the result to the next participant
**Security guarantee:** As long as **one** participant honestly destroys their randomness, the SRS is secure. An attacker would need to compromise every single participant — a practical impossibility with hundreds of participants.
### Participation Requirements
- **Minimum participants:** 200 (target: 500+)
- **Open to anyone:** Any person in the world can participate. No KYC, no approval needed.
- **Diverse hardware:** Participants should use different hardware, operating systems, and entropy sources to prevent correlated failures.
- **Verifiable:** Each participant's contribution is publicly verifiable on-chain after the ceremony.
### Ceremony Phases
**Phase 1: Powers of Tau (universal)**
Generates the universal SRS that works for any PLONK circuit up to a maximum size.
1. Coordinator publishes initial parameters
2. Each participant downloads current state (~1 GB)
3. Participant runs the contribution software (5–30 minutes depending on hardware)
4. Participant uploads their contribution
5. Contribution is verified automatically
6. Next participant begins
**Phase 2: Circuit-Specific Finalization**
Takes the universal SRS and finalizes it for Orama's specific circuits (private transfers, private contract calls).
### Entropy Sources
Participants are encouraged to use creative and unpredictable entropy sources:
- Hardware random number generators
- Atmospheric noise sensors
- Radioactive decay measurements
- Keystroke timing
- Any source that is physically impossible for an attacker to predict or reproduce
### Timeline
| Step | Date | Duration |
|---|---|---|
| Ceremony software published and audited | Q4 2026 | — |
| Public registration opens | Q1 2027 | 2 weeks |
| Phase 1: Powers of Tau | Q1 2027 | 4–6 weeks |
| Phase 2: Circuit finalization | Q2 2027 | 2 weeks |
| Final SRS published and verified | Q2 2027 | — |
| SRS embedded in testnet | Q2 2027 | — |
| SRS embedded in mainnet genesis block | Q4 2028 | — |
## Verification
After the ceremony:
1. The final SRS is published on IPFS (permanently available)
2. A hash of the SRS is committed to the Orama genesis block
3. Every participant can verify their contribution was included
4. Anyone can verify the mathematical validity of the final SRS
5. The verification software is open-source
## What If the Setup Is Compromised?
If all participants collude (practically impossible with 200+ independent participants), an attacker could:
- Create fake private transactions (forge proofs)
- This would NOT affect public transactions, the supply cap, or the BTC bridge
The scope of damage is limited to the privacy feature. In the extremely unlikely event of compromise, governance can vote to:
1. Disable private transactions temporarily
2. Run a new ceremony with more participants
3. Re-enable with the new SRS
This is a Tier 1 emergency action (24-hour response by DeBros Team NFT holders).

369
whitepaper/APPENDIX_E_SAMPLE_CONTRACT.md
View File

@ -1,369 +0,0 @@
# Appendix E: Sample WASM Contracts
## Example: Private BTC Transfer Contract (Rust)
This example shows a WASM smart contract written in Rust that accepts BTC deposits and allows private withdrawals using Orama's privacy toggle. This contract deploys into a namespace.
```rust
use orama_sdk::prelude::*;
/// A simple vault contract that accepts BTC deposits (public)
/// and allows private withdrawals to any address.
#[orama_contract]
pub struct PrivateVault {
/// Maps depositor address to their BTC balance (in satoshis)
balances: StorageMap<Address, u64>,
}
#[orama_contract]
impl PrivateVault {
/// Initialize the contract
#[init]
pub fn new() -> Self {
Self {
balances: StorageMap::new("balances"),
}
}
/// Deposit BTC into the vault (public transaction)
#[payable(BTC)]
pub fn deposit(&mut self, ctx: &Context) -> Result<()> {
let sender = ctx.caller();
let amount = ctx.btc_value(); // Amount of BTC sent with this call
let current = self.balances.get(&sender).unwrap_or(0);
self.balances.set(&sender, current + amount);
emit!(Deposit {
from: sender,
amount: amount,
});
Ok(())
}
/// Withdraw BTC privately — sender, receiver, and amount are shielded
#[private] // This annotation enables the zk-SNARK privacy toggle
pub fn withdraw(&mut self, ctx: &Context, to: Address, amount: u64) -> Result<()> {
let sender = ctx.caller();
let balance = self.balances.get(&sender).ok_or(Error::InsufficientBalance)?;
if balance < amount {
return Err(Error::InsufficientBalance);
}
self.balances.set(&sender, balance - amount);
// Transfer BTC to recipient — this transfer is private
ctx.transfer_btc(to, amount)?;
Ok(())
}
/// Check your own balance (public, read-only)
#[view]
pub fn balance_of(&self, address: Address) -> u64 {
self.balances.get(&address).unwrap_or(0)
}
}
```
## How It Works
1. **Deposit (public):** User calls `deposit()` and sends BTC. The deposit is visible on-chain — everyone can see who deposited and how much.
2. **Withdraw (private):** User calls `withdraw()` with the `#[private]` annotation. The Orama runtime automatically generates a PLONK zk-SNARK proof that:
- The caller has sufficient balance
- The withdrawal amount is valid
- The recipient address is valid
But the proof reveals **none** of these details to observers. The transaction appears on-chain but the sender, recipient, and amount are shielded.
3. **Gas:** The private withdrawal costs 4x the gas of a public withdrawal (covers ZK proof generation).
## Example: AI Angel Contract (Rust)
This example shows an Angel (AI agent) that monitors BTC bridge activity and automatically places buy orders.
```rust
use orama_sdk::prelude::*;
use orama_sdk::dex::OrderBook;
/// An Angel that watches bridge deposits and places DEX buy orders
#[orama_contract]
pub struct BridgeWatcherAngel {
/// The Angel's own $ORAMA balance for placing orders
wallet: TokenBalance,
/// Minimum bridge deposit size to trigger a buy (in satoshis)
min_trigger: u64,
/// Percentage of bridge amount to buy in $ORAMA
buy_percentage: u8,
}
#[orama_contract]
impl BridgeWatcherAngel {
#[init]
pub fn new(min_trigger: u64, buy_percentage: u8) -> Self {
Self {
wallet: TokenBalance::new(),
min_trigger,
buy_percentage,
}
}
/// Called automatically by the Angel runtime when a bridge deposit event occurs
#[on_event(BridgeDeposit)]
pub fn on_bridge_deposit(&mut self, ctx: &Context, event: BridgeDepositEvent) -> Result<()> {
if event.amount < self.min_trigger {
return Ok(()); // Ignore small deposits
}
let buy_amount = (event.amount as u128 * self.buy_percentage as u128 / 100) as u64;
// Place a market buy order on the native DEX
let order = OrderBook::market_order(
Pair::ORAMA_BTC,
Side::Buy,
buy_amount,
)?;
emit!(AngelAction {
action: "buy_triggered",
trigger_amount: event.amount,
order_id: order.id,
});
Ok(())
}
/// Owner can deposit $ORAMA for the Angel to use
#[payable(ORAMA)]
pub fn fund(&mut self, ctx: &Context) -> Result<()> {
self.wallet.add(ctx.orama_value());
Ok(())
}
/// Owner can withdraw unused funds
pub fn withdraw_funds(&mut self, ctx: &Context, amount: u64) -> Result<()> {
ctx.require_owner()?;
self.wallet.subtract(amount)?;
ctx.transfer_orama(ctx.caller(), amount)?;
Ok(())
}
}
```
## Example: Full-Stack App with SQL Database (Rust)
This example demonstrates Orama's unique namespace model — contracts have access to a real SQL database (RQLite), distributed cache (Olric), and IPFS storage. No external indexing infrastructure needed.
```rust
use orama_sdk::prelude::*;
use orama_sdk::namespace::{Database, Cache, Storage};
/// A full-stack marketplace contract deployed into a namespace.
/// The namespace provides dedicated SQL, cache, and storage.
#[orama_contract]
pub struct Marketplace {
db: Database,
cache: Cache,
storage: Storage,
}
#[orama_contract]
impl Marketplace {
#[init]
pub fn new(ctx: &Context) -> Result<Self> {
let db = Database::connect()?;
// Create tables — real SQL, powered by the namespace's RQLite cluster
db.execute("
CREATE TABLE IF NOT EXISTS listings (
id INTEGER PRIMARY KEY AUTOINCREMENT,
seller TEXT NOT NULL,
title TEXT NOT NULL,
description TEXT,
price_rays INTEGER NOT NULL,
image_cid TEXT,
status TEXT DEFAULT 'active',
created_at DATETIME DEFAULT CURRENT_TIMESTAMP
)
", &[])?;
db.execute("
CREATE TABLE IF NOT EXISTS purchases (
id INTEGER PRIMARY KEY AUTOINCREMENT,
listing_id INTEGER NOT NULL,
buyer TEXT NOT NULL,
price_rays INTEGER NOT NULL,
purchased_at DATETIME DEFAULT CURRENT_TIMESTAMP,
FOREIGN KEY (listing_id) REFERENCES listings(id)
)
", &[])?;
Ok(Self {
db: Database::connect()?,
cache: Cache::connect()?,
storage: Storage::connect()?,
})
}
/// List an item for sale — stores metadata in SQL, image in IPFS
pub fn create_listing(
&mut self,
ctx: &Context,
title: String,
description: String,
price_rays: u64,
image_bytes: Vec<u8>,
) -> Result<u64> {
let seller = ctx.caller();
// Store image in the namespace's IPFS storage
let image_cid = self.storage.put(&image_bytes)?;
// Insert listing into the namespace's SQL database
let listing_id = self.db.execute(
"INSERT INTO listings (seller, title, description, price_rays, image_cid) VALUES (?, ?, ?, ?, ?)",
&[&seller.to_string(), &title, &description, &price_rays.to_string(), &image_cid],
)?;
// Invalidate the cache so the next query gets fresh data
self.cache.delete("listings:active")?;
emit!(ListingCreated {
id: listing_id,
seller: seller,
title: title,
price_rays: price_rays,
});
Ok(listing_id)
}
/// Buy a listed item
#[payable(ORAMA)]
pub fn purchase(&mut self, ctx: &Context, listing_id: u64) -> Result<()> {
let buyer = ctx.caller();
let payment = ctx.orama_value();
// Query the listing from SQL
let row = self.db.query_one(
"SELECT seller, price_rays, status FROM listings WHERE id = ?",
&[&listing_id.to_string()],
)?;
let seller: Address = row.get("seller")?;
let price: u64 = row.get("price_rays")?;
let status: String = row.get("status")?;
if status != "active" {
return Err(Error::Custom("Listing is not active".into()));
}
if payment < price {
return Err(Error::InsufficientPayment);
}
// Transfer payment to seller
ctx.transfer_orama(seller, price)?;
// Update listing status in SQL
self.db.execute(
"UPDATE listings SET status = 'sold' WHERE id = ?",
&[&listing_id.to_string()],
)?;
// Record the purchase
self.db.execute(
"INSERT INTO purchases (listing_id, buyer, price_rays) VALUES (?, ?, ?)",
&[&listing_id.to_string(), &buyer.to_string(), &price.to_string()],
)?;
Ok(())
}
/// Get active listings — uses cache for performance
/// This data is also queryable via the namespace's RPC:
/// GET /v1/contracts/{address}/listings?status=active&sort=price_rays&order=asc
#[view]
pub fn get_active_listings(&self, limit: u32, offset: u32) -> Result<Vec<Listing>> {
// Check cache first
let cache_key = format!("listings:active:{}:{}", limit, offset);
if let Some(cached) = self.cache.get(&cache_key)? {
return Ok(cached);
}
// Cache miss — query SQL
let rows = self.db.query(
"SELECT id, seller, title, price_rays, image_cid, created_at
FROM listings WHERE status = 'active'
ORDER BY created_at DESC LIMIT ? OFFSET ?",
&[&limit.to_string(), &offset.to_string()],
)?;
let listings: Vec<Listing> = rows.iter().map(|r| Listing {
id: r.get("id").unwrap(),
seller: r.get("seller").unwrap(),
title: r.get("title").unwrap(),
price_rays: r.get("price_rays").unwrap(),
image_cid: r.get("image_cid").unwrap(),
}).collect();
// Cache for 60 seconds
self.cache.set(&cache_key, &listings, 60)?;
Ok(listings)
}
}
```
### What This Contract Gets (From the Namespace)
This contract deploys into a namespace and automatically receives:
| Primitive | What It Does | Ethereum Equivalent |
|---|---|---|
| `Database::connect()` | Real SQL database (RQLite with Raft consensus across 3+ nodes) | Nothing — need The Graph or custom indexer |
| `Cache::connect()` | Distributed cache (Olric with consistent hashing) | Nothing — need Redis or Memcached externally |
| `Storage::connect()` | IPFS storage (content-addressed, replicated) | Need Pinata/Infura IPFS externally |
| Namespace RPC | Rich query API with filtering, sorting, pagination | Need The Graph subgraph |
**The namespace IS the backend.** No external infrastructure needed.
## Compiling and Deploying
```bash
# Install the Orama SDK
cargo install orama-cli
# Create a new contract project
orama new my-contract
cd my-contract
# Build to WASM
orama build --release
# Deploy to a namespace on the Orama network
# This creates a namespace (or uses an existing one) with dedicated
# RQLite, Olric, IPFS, and Gateway infrastructure
orama deploy --namespace my-marketplace --network mainnet ./target/wasm/my_contract.wasm
# Call a contract function
orama call my-marketplace::Marketplace create_listing --title "Cool NFT" --price 1000000
orama call my-marketplace::Marketplace purchase --listing-id 1 --value 1000000rays
# Query via the namespace's RPC (no indexer needed)
curl https://my-marketplace.orama.network/v1/contracts/Marketplace/listings?status=active&sort=price_rays
```
## Supported Languages
While these examples are in Rust, any language that compiles to WebAssembly can be used:
- **Rust** (recommended — best tooling and performance)
- **Go** (via TinyGo)
- **TypeScript** (via AssemblyScript)
- **C/C++** (via Emscripten)
- **Python** (experimental)
The Orama SDK provides bindings for all supported languages, giving access to the full set of namespace primitives (SQL, KV cache, IPFS, BTC bridge, DEX, AI Marketplace). As new languages gain WebAssembly compilation support, they become available for Orama contract development automatically.

171
whitepaper/APPENDIX_F_MATH_PROOFS.md
View File

@ -1,171 +0,0 @@
# Appendix F: Effective Power & Slashing Math
## Effective Power Formula
$$
\text{EP}_i = S_i \times (1 + C_i) \times M_i
$$
Where for node $i$:
- $S_i$ = Staked $ORAMA (minimum 1,000 at mainnet)
- $C_i$ = Contribution Score (0.0 to 1.0, recalculated every epoch)
- $M_i$ = Infrastructure Multiplier (1.0 or 1.5)
## Contribution Score Calculation
The Contribution Score is a weighted average of four metrics, measured every epoch (1 hour = 600 blocks):
$$
C_i = 0.4 \times U_i + 0.3 \times B_i + 0.2 \times W_i + 0.1 \times R_i
$$
Where:
- $U_i$ = Uptime ratio (blocks produced / blocks expected), range [0, 1]
- $B_i$ = Bandwidth ratio (bytes served / network average), normalized to [0, 1]
- $W_i$ = Work ratio (compute + storage + SQL queries served / network average), normalized to [0, 1]
- $R_i$ = Reliability ratio (successful responses / total requests), range [0, 1]
### Normalization
Bandwidth and work metrics are normalized relative to the network average:
$$
B_i = \min\left(\frac{b_i}{\bar{b}}, 1.0\right)
$$
Where $b_i$ is node $i$'s bandwidth served and $\bar{b}$ is the network average. Capped at 1.0 to prevent nodes from gaming the score by self-generating traffic.
### Score Examples
| Scenario | Uptime | Bandwidth | Work | Reliability | Score |
|---|---|---|---|---|---|
| Perfect node | 1.0 | 1.0 | 1.0 | 1.0 | **1.0** |
| Good node (some downtime) | 0.95 | 0.8 | 0.7 | 0.98 | **0.85** |
| Average node | 0.9 | 0.5 | 0.5 | 0.95 | **0.71** |
| Poor node | 0.7 | 0.3 | 0.2 | 0.8 | **0.49** |
| Minimal node (just online) | 0.8 | 0.1 | 0.05 | 0.9 | **0.44** |
## Infrastructure Multiplier
| Configuration | Multiplier ($M_i$) |
|---|---|
| Any node without OramaOS | 1.0× |
| Any node running OramaOS | **1.5×** |
The multiplier is based solely on running OramaOS, verified via TPM attestation. Orama One ships pre-loaded with OramaOS and thus receives the 1.5× multiplier out of the box, but any hardware running OramaOS receives the same bonus.
## Block Reward Distribution
Each block reward ($R$ = 100 $ORAMA in Era 1) is distributed:
$$
\text{Miner share} = 0.8 \times R = 80 \text{ \$ORAMA}
$$
$$
\text{Curve share} = 0.2 \times R = 20 \text{ \$ORAMA}
$$
The block proposer is selected proportionally to Effective Power:
$$
P(\text{node } i \text{ proposes block}) = \frac{\text{EP}_i}{\sum_{j=1}^{N} \text{EP}_j}
$$
## Effective Power Comparison Examples
### Scenario 1: Whale vs Active Small Node Runner
| | Whale | Small Runner |
|---|---|---|
| Stake | 100,000 $ORAMA | 2,000 $ORAMA |
| Contribution Score | 0.3 (minimal work) | 0.9 (active node) |
| Infrastructure | No OramaOS (1.0×) | OramaOS (1.5×) |
| **Effective Power** | 100,000 × 1.3 × 1.0 = **130,000** | 2,000 × 1.9 × 1.5 = **5,700** |
| **Ratio** | 22.8× more power | — |
The whale has 50× more stake but only 22.8× more Effective Power. Contribution and OramaOS close the gap significantly.
### Scenario 2: Two Equal-Stake Nodes
| | Without OramaOS | With OramaOS |
|---|---|---|
| Stake | 5,000 $ORAMA | 5,000 $ORAMA |
| Contribution Score | 0.7 | 0.7 |
| Infrastructure | 1.0× | 1.5× |
| **Effective Power** | 5,000 × 1.7 × 1.0 = **8,500** | 5,000 × 1.7 × 1.5 = **12,750** |
| **Ratio** | — | **1.5× more power** |
Same stake, same contribution, but OramaOS earns 50% more block rewards.
### Scenario 3: Active Small Node vs Lazy Whale
| | Lazy Whale | Active Small Node |
|---|---|---|
| Stake | 500,000 $ORAMA | 1,000 $ORAMA |
| Contribution Score | 0.1 (barely online) | 1.0 (perfect) |
| Infrastructure | No OramaOS (1.0×) | OramaOS (1.5×) |
| **Effective Power** | 500,000 × 1.1 × 1.0 = **550,000** | 1,000 × 2.0 × 1.5 = **3,000** |
The whale still dominates in raw Effective Power — but they have 500× more stake and only 183× more power. The contribution score and OramaOS multiplier reduce the whale's advantage by 63%. The small node runner is earning proportionally more per token staked.
## Slashing Rules
### Slashing Schedule
| Offense | Slash Amount | Scope | Recovery |
|---|---|---|---|
| Double-signing / equivocation | **100%** of stake | Stake + contribution score reset to 0 | Permanent ban from validation |
| Downtime > 20% in epoch | **5–30%** progressive | Stake only | Can resume after restaking |
| Downtime 20–40% | 5% | Stake | — |
| Downtime 40–60% | 10% | Stake | — |
| Downtime 60–80% | 20% | Stake | — |
| Downtime > 80% | 30% | Stake | — |
| False hardware/OS attestation | **50%** of stake | Stake + permanent flag | Infrastructure Multiplier permanently revoked |
### Progressive Downtime Slashing Formula
$$
\text{Slash \%} = \begin{cases}
0\% & \text{if downtime} \leq 20\% \\
5\% + 25\% \times \frac{\text{downtime} - 0.2}{0.6} & \text{if } 20\% < \text{downtime} \leq 80\% \\
30\% & \text{if downtime} > 80\%
\end{cases}
$$
### Slashing Examples
**Example 1: Node goes offline for 45 minutes in an epoch (75% uptime, 25% downtime)**
$$
\text{Slash} = 5\% + 25\% \times \frac{0.25 - 0.2}{0.6} = 5\% + 2.08\% = 7.08\%
$$
On a 10,000 $ORAMA stake: 708 $ORAMA slashed.
**Example 2: Node has 50% downtime**
$$
\text{Slash} = 5\% + 25\% \times \frac{0.5 - 0.2}{0.6} = 5\% + 12.5\% = 17.5\%
$$
On a 10,000 $ORAMA stake: 1,750 $ORAMA slashed.
**Example 3: Double-signing**
100% slash. On a 10,000 $ORAMA stake: all 10,000 $ORAMA slashed. Contribution score reset to 0. Node is permanently banned from validation.
### Where Slashed Tokens Go
All slashed $ORAMA is **burned** (permanently removed from circulating supply). Slashing is deflationary — bad actors make the token more scarce for everyone else.
## Epoch Transition
At the end of each epoch (every 600 blocks / 1 hour):
1. Contribution scores are recalculated for all active validators
2. Infrastructure attestations are verified
3. Effective Power is updated for all validators
4. Slashing conditions are evaluated
5. Block proposer selection probabilities are updated for the next epoch
6. Bridge fees are distributed to validators and NFT holders

454
whitepaper/APPENDIX_G_TECHNICAL_ARCHITECTURE.md
View File

@ -1,454 +0,0 @@
# Appendix G: Technical Architecture
This appendix covers the implementation-level technical decisions for the Orama blockchain. These choices are informed by the design principles in the main whitepaper and reflect the specific tradeoffs appropriate for Orama's unique two-layer architecture (global chain + namespaces).
## 1. Dual-State Account Model
Every address on Orama has a single account with two compartments:
```
Account {
Address [20]byte // Account identifier (secp256k1-derived, Ethereum-compatible)
Username string // Optional, immutable once claimed, 3-32 chars [a-z0-9_-]
Nonce uint64 // Replay protection
// Public compartment — visible to everyone
OramaBalance uint64 // Balance in rays (1 $ORAMA = 1,000,000 rays)
BTCBalance uint64 // Balance in satoshis
CodeHash [32]byte // Hash of contract WASM bytecode (zero for non-contracts)
StorageRoot [32]byte // Merkle root of contract KV storage
// Private compartment (Phase 2 — zero hashes at genesis)
CommitmentRoot [32]byte // Merkle root of hidden value commitments
NullifierRoot [32]byte // Merkle root of spent-tracking nullifiers
}
```
### Signatures & Addresses
- **Curve**: secp256k1 (same as Bitcoin and Ethereum)
- **Signature**: 65 bytes (r, s, v) — ECDSA
- **Address**: 20 bytes, derived from `Keccak256(public_key)[12:]` (Ethereum-compatible)
- **Display format**: `orama:` prefix for human readability (e.g., `orama:742d35Cc...`)
- **Compatibility**: Same keys and addresses work in RootWallet, Ethereum, and any hardware wallet
### Usernames
Orama accounts can optionally claim a **permanent, human-readable username** tied to their address. Usernames are a protocol-level feature, not a smart contract.
- **Optional**: Accounts can exist without a username. Claim anytime via a `ClaimUsername` transaction.
- **Immutable**: Once claimed, a username can never be changed, transferred, or sold.
- **Unique**: 1:1 mapping between username and address.
- **Format**: Lowercase alphanumeric, hyphens, underscores. 3-32 characters.
- **Free**: Only costs standard transaction gas.
- **Resolvable**: Send to `@alex` instead of `orama:742d35Cc...`. The chain resolves the lookup natively.
The SMT stores a reverse-lookup leaf at `hash(username)` → `address`, enabling O(1) resolution.
### Phase 1 (Testnet): Public Only
All transactions operate on the public compartment. `CommitmentRoot` and `NullifierRoot` are zero hashes. The account structure ships with these fields from genesis — no migration or fork is needed when privacy is activated.
### Phase 2 (Post-PLONK Ceremony): Privacy Activation
The private compartment activates. Funds can be moved between compartments:
- **Shield** (public → private): Deduct from `OramaBalance`, add a Pedersen commitment to the account's commitment tree.
- **Unshield** (private → public): Spend a commitment (publish its nullifier), add to `OramaBalance`. A PLONK proof verifies the commitment was valid.
- **Private transfer**: Spend a commitment in sender's account, create a new commitment in receiver's account. PLONK proof verifies validity without revealing sender, receiver, or amount.
### Why Not a Separate Shielded Pool?
Other chains (Ethereum + Tornado Cash, Aztec) bolt privacy onto an account model via an external "shielded pool" contract. This creates:
- UX friction (explicit deposit/withdraw from pool)
- A privacy leak at the boundary (observers see pool deposits/withdrawals)
- Two incompatible codepaths for wallets
Orama's dual-state model avoids this: privacy is native to each account. One account, two views, no external pool.
## 2. State Tree: Sparse Merkle Tree (SMT)
All state is organized in a Sparse Merkle Tree — a binary tree with 256 levels where most branches are empty (sparse). Each account lives at a leaf determined by `hash(address)`.
```
Global State SMT (root goes in block header)
│
├── leaf[hash(Alice)] → Account data (serialized)
├── leaf[hash(Bob)] → Account data
├── leaf[hash(Contract)] → Account data
│ └── StorageRoot → Contract Storage SMT
│ ├── key1 → value1
│ ├── key2 → value2
│ └── ...
└── (2^256 - N empty leaves, represented by known zero hashes)
```
### Properties
| Property | Value |
|---|---|
| Depth | 256 levels (fixed) |
| Leaf position | `SHA256(address)` |
| Proof size | 256 × 32 bytes = 8 KB (compressible to ~1-2 KB) |
| Non-existence proofs | Built-in (prove an account does NOT exist) |
| Algorithm complexity | ~500 lines of Go |
### Why SMT Over Alternatives
| Tree | Used By | Pros | Cons |
|---|---|---|---|
| Merkle Patricia Trie | Ethereum | Battle-tested 10+ years | Complex (~3000 lines), deep trees, Ethereum is migrating away from it |
| **Sparse Merkle Tree** | **Orama**, Celestia, Mina | Simple, fixed depth, non-existence proofs, predictable performance | Larger raw proofs (mitigated by compression) |
| Verkle Tree | Ethereum (future) | Tiny proofs (~150 bytes) | Requires elliptic curve math, not yet shipped in production, quantum-vulnerable |
SMT's built-in non-existence proofs are critical for the privacy layer — proving a nullifier hasn't been spent requires proving a key does NOT exist in the nullifier tree.
### Nested SMTs
The same algorithm is used at every level of the state:
1. **Global State SMT** — accounts indexed by `hash(address)`, root in block header
2. **Contract Storage SMT** — per-contract KV data, root in account's `StorageRoot`
3. **Commitment SMT** (Phase 2) — per-account hidden commitments, root in `CommitmentRoot`
4. **Nullifier SMT** (Phase 2) — per-account spent nullifiers, root in `NullifierRoot`
One data structure. One algorithm. Clean.
## 3. State Storage: BadgerDB
The underlying key-value store for all chain state is **BadgerDB** — a pure Go, high-performance, LSM-tree-based database.
### Why BadgerDB
| Requirement | BadgerDB |
|---|---|
| Pure Go (no CGO) | Yes — compiles cleanly on any platform including OramaOS |
| Concurrent reads | Lock-free MVCC reads |
| Batched writes | Transaction-based batch writes |
| Crash safety | Write-ahead log with checksums |
| Used in blockchain | IPFS, libp2p ecosystem (already in Orama's dependency tree) |
| Maintenance | Actively maintained by Dgraph team |
### Storage Layout
```
/var/lib/orama/chain/
├── blocks/ # Block storage (BadgerDB)
│ └── (block headers, transaction lists, receipts)
├── state/ # Current state (BadgerDB)
│ └── (SMT nodes, account data, contract storage)
└── index/ # Query indexes (optional, per-node)
└── (tx-by-address, blocks-by-height, etc.)
```
The `blocks/` and `state/` databases are consensus-critical — every node computes identical content. The `index/` database is per-node, non-consensus, and supports the rich query RPC layer.
## 4. Serialization: Borsh
All data that is hashed, stored, or transmitted over the wire uses **Borsh** (Binary Object Representation Serializer for Hashing) — a deterministic binary serialization format created specifically for blockchain use.
### Why Borsh
| Requirement | Borsh | Protobuf | RLP (Ethereum) |
|---|---|---|---|
| Deterministic | By design | No (maps unordered) | By design |
| Code generation | None (struct tags) | Required (.proto files) | None |
| Schema | Implicit from struct | External .proto | None |
| Created for | Blockchain hashing | RPC/APIs | Ethereum |
| Compact | Yes | Yes | Yes |
### Example
```go
type Block struct {
Height uint64 `borsh:"height"`
ParentHash [32]byte `borsh:"parent_hash"`
StateRoot [32]byte `borsh:"state_root"`
Timestamp uint64 `borsh:"timestamp"`
ProposerAddr [20]byte `borsh:"proposer"`
Transactions []Transaction `borsh:"transactions"`
QC QuorumCert `borsh:"qc"`
}
// Deterministic: same data always produces identical bytes
bytes := borsh.Serialize(block)
blockHash := sha256(bytes)
```
## 5. Consensus: HotStuff BFT
The global chain uses a pipelined BFT protocol based on HotStuff. See Section 4 of the main whitepaper for the full protocol description.
### Key Implementation Details
**Message types:**
| Message | Direction | Content |
|---|---|---|
| `Propose` | Leader → All | Block + QC for previous round |
| `Vote` | Validator → Next Leader | Signed block hash + validator ID |
| `NewView` | Validator → New Leader | Timeout certificate (on leader failure) |
**Quorum Certificate (QC):** An aggregation of 2/3+ votes (by Effective Power) for a specific block. The QC is the proof that consensus was reached.
**View change:** If the current leader fails to propose within the timeout (configurable, default 4 seconds), validators send a `NewView` message to the next leader in the rotation. The next leader can immediately propose, including the timeout certificate as justification. No rounds are wasted on view-change voting.
**Pipelining:** Votes for block N serve as the QC for block N-1, which finalizes block N-2. This means:
- Block produced: every 6 seconds
- Block finalized: 18 seconds later (3 blocks)
- No dead time between rounds
### P2P Transport
Consensus messages are Borsh-serialized and transported over LibP2P pubsub topics, running on top of the WireGuard encrypted mesh. All validator-to-validator communication is authenticated and encrypted at the network layer.
**Topics:**
| Topic | Content |
|---|---|
| `/orama/chain/1/blocks` | Block proposals from leaders |
| `/orama/chain/1/votes` | HotStuff votes from validators |
| `/orama/chain/1/txs` | New transactions (mempool gossip) |
| `/orama/chain/1/newview` | View-change messages (leader timeout) |
**Message envelope:**
```
Message {
Type: uint8 // Block, Vote, Transaction, NewView
Payload: []byte // Borsh-serialized content
Sender: [20]byte // Sender address
Signature: [65]byte // ECDSA signature over payload
}
```
## 6. Namespace Architecture
Namespaces are provisioned from the global node pool. They come in tiers based on trust requirements.
### Namespace Tiers
| Tier | Name | Purpose | Blockchain Interaction |
|---|---|---|---|
| 0 | Cloud | App deployment (what namespaces are today) | None |
| 1 | Secured | Smart contracts, tokens, NFTs, anything with value | State commitments to global chain, staked validators |
| 2 | Trustless (future) | High-value protocols needing maximum security | ZK validity proofs |
**Tier 0** is the default. Existing namespaces are Tier 0. No changes to current behavior. Developers deploy apps just like today — no blockchain knowledge needed.
**Tier 1** adds verifiable state on top of the same infrastructure. It's Tier 0 plus three additions: a StateDB (BadgerDB + SMT) for cryptographic state proofs, a TxLog for replay/verification, and staked validators who submit state commitments to the global chain every epoch.
### Tier 0 Cluster Composition (unchanged)
| Service | Nodes | Purpose |
|---|---|---|
| RQLite | 3+ | SQL database with Raft consensus |
| Olric | 3+ | Distributed KV cache |
| Gateway | 3+ | HTTP/WebSocket API, WASM VM, RPC |
| IPFS | Shared | Content-addressed storage |
| SFU + TURN | Optional | WebRTC voice/video |
### Tier 1 Cluster Composition (adds verifiable state)
| Service | Nodes | Purpose |
|---|---|---|
| RQLite | 3+ | SQL database — developer queries, powers the RPC |
| **StateDB** | **3+ (per node)** | **BadgerDB + SMT — verifiable state, produces Merkle root** |
| **TxLog** | **3+ (per node)** | **Append-only operation log for replay/verification** |
| Olric | 3+ | Distributed KV cache |
| Gateway | 3+ | HTTP/WebSocket API, WASM VM, RPC |
| IPFS | Shared | Content-addressed storage |
| SFU + TURN | Optional | WebRTC voice/video |
**How the three storage layers work together in Tier 1:**
- **RQLite** = the read layer. Developers query with SQL. The RPC serves data from it. Fast and flexible, but not cryptographically verifiable.
- **StateDB** = the proof layer. Stores the same data in a Sparse Merkle Tree (BadgerDB). Produces the state fingerprint (Merkle root) that gets committed to the global chain. Verifiable but not queryable with SQL.
- **TxLog** = the replay layer. Ordered list of every state-changing operation. If someone challenges the namespace, they replay the log, compute the expected state, and compare with the submitted fingerprint.
Contracts write to both RQLite and StateDB atomically. They always agree on the current state.
### State Commitment Flow
The commitment mechanism strengthens across phases:
**Testnet: Attested Commitment**
```
1. Namespace executes transactions against its local state
2. At each epoch boundary, the namespace computes a state root:
hash(rqlite_state || olric_state || contract_storage || metadata)
3. 2/3+ of the namespace's validators sign the state root
4. Submit StateCommitment transaction to the global chain:
{ namespace_id, epoch, state_root, validator_signatures }
5. Global chain records the commitment in the namespace registry
```
**Mainnet: Optimistic with Challenge Period**
```
1-4. Same as above
5. State root enters "pending" state for ~100 blocks (10 minutes)
6. During pending period, anyone can submit a fraud proof:
→ provide the transactions + correct state root
→ if challenge is valid, namespace validators are slashed, state root rejected
7. After challenge period with no valid challenge → state root finalized
```
**Future: ZK Validity Proofs**
```
1-2. Same as above
3. Namespace generates a zero-knowledge proof that state transitions are correct
4. Submit proof + new state root to global chain
5. Global chain verifies proof (~5ms) → immediately finalized
```
### Namespace Provisioning
Namespace clusters are provisioned dynamically from the global node pool. Each physical node can host multiple namespace instances (up to 20 per node, constrained by port allocation). The cluster manager handles:
- Node selection (balanced load distribution)
- Port allocation (dedicated port block per namespace)
- Service bootstrapping (RQLite → Olric → Gateway, in dependency order)
- DNS record creation (namespace subdomain)
- Health monitoring and recovery
This infrastructure already exists in the Orama Network codebase (`pkg/namespace/`).
## 7. Block Structure
```
Block {
// Header
Height: uint64
ParentHash: [32]byte
StateRoot: [32]byte // SMT root after executing all transactions
TransactionsRoot:[32]byte // Merkle root of transaction list
ReceiptsRoot: [32]byte // Merkle root of execution receipts
Timestamp: uint64 // Unix timestamp (seconds)
ProposerAddr: [20]byte // Block proposer address
EpochNumber: uint64 // Current epoch
QC: QuorumCert // Quorum Certificate from previous round
// Body
Transactions: []Transaction
}
Transaction {
Type: uint8 // Transfer, Stake, Unstake, DEXOrder, BridgeDeposit,
// BridgeWithdraw, NamespaceCommit, GovernanceVote, ...
From: [20]byte
To: [20]byte
Amount: uint64 // In rays or satoshis depending on asset
Asset: uint8 // 0 = $ORAMA, 1 = BTC
Nonce: uint64
GasLimit: uint64
GasTipCap: uint64 // Priority fee (EIP-1559)
GasFeeCap: uint64 // Max total fee (EIP-1559)
Data: []byte // Type-specific payload
Signature: [65]byte // ECDSA signature (secp256k1)
}
```
## 8. RPC API
Orama uses a **REST API** as its primary interface. No JSON-RPC.
### Global Chain Endpoints
```
GET /v1/accounts/{address_or_username}
GET /v1/accounts/{address_or_username}/balance
GET /v1/accounts/{address_or_username}/transactions?limit=20&sort=timestamp&order=desc
POST /v1/transactions/send
GET /v1/transactions/{hash}
GET /v1/blocks/{height_or_hash}
GET /v1/blocks/latest
GET /v1/dex/orderbook
GET /v1/dex/orders?owner=@alex
POST /v1/dex/orders
GET /v1/bridge/status
GET /v1/validators
GET /v1/chain/status
```
### Namespace Endpoints (served by namespace gateway)
```
GET /v1/namespace/{name}/contracts
GET /v1/namespace/{name}/contracts/{address}/state/{key}
POST /v1/namespace/{name}/contracts/{address}/call
GET /v1/namespace/{name}/query?sql=SELECT...
```
Usernames are resolvable in any endpoint: `@alex` is equivalent to `orama:742d35Cc...`.
All responses support filtering, sorting, and pagination via query parameters. This matches the existing Gateway pattern in `pkg/gateway/`.
## 9. WASM Contract Host Functions
These are the "system calls" available to WASM contracts running in a namespace.
### Database (RQLite)
```
orama.db.execute(query_ptr, query_len, params_ptr, params_len) → result_ptr
orama.db.query(query_ptr, query_len, params_ptr, params_len) → result_ptr
orama.db.query_one(query_ptr, query_len, params_ptr, params_len) → result_ptr
```
### Cache (Olric)
```
orama.cache.get(key_ptr, key_len) → result_ptr
orama.cache.set(key_ptr, key_len, val_ptr, val_len, ttl_seconds) → status
orama.cache.delete(key_ptr, key_len) → status
```
### Storage (IPFS)
```
orama.storage.put(data_ptr, data_len) → cid_ptr
orama.storage.get(cid_ptr, cid_len) → data_ptr
```
### Token Operations (global chain interaction)
```
orama.transfer_orama(to_ptr, amount) → status
orama.transfer_btc(to_ptr, amount) → status
orama.get_balance(address_ptr, asset) → amount
```
### Context (read-only)
```
orama.ctx.caller() → address_ptr
orama.ctx.block_height() → uint64
orama.ctx.block_timestamp() → uint64
orama.ctx.orama_value() → uint64
orama.ctx.btc_value() → uint64
```
### Events, Logging, Crypto
```
orama.emit(event_ptr, event_len) → status
orama.log.info(msg_ptr, msg_len)
orama.log.error(msg_ptr, msg_len)
orama.crypto.sha256(data_ptr, data_len, out_ptr)
orama.crypto.keccak256(data_ptr, data_len, out_ptr)
orama.crypto.verify_signature(msg_ptr, msg_len, sig_ptr, addr_ptr) → bool
```
**Design principles:**
- No filesystem, no raw network, no non-deterministic operations
- `block_timestamp` is the block's timestamp (deterministic), not system time
- No `random` — use `block_hash` as a deterministic seed if needed
- Contracts write SQL directly — no ORM or query builder in the host layer
- Events are indexed by the namespace gateway for rich RPC queries
## 10. Implementation Language
The entire blockchain layer is implemented in **Go**, consistent with the existing Orama Network codebase. Key dependencies:
| Dependency | Purpose | Status |
|---|---|---|
| BadgerDB | State and block storage | To be added |
| wazero | WASM contract execution | Already in project |
| LibP2P | P2P networking, gossip | Already in project |
| go-ethereum/crypto | secp256k1 signatures | Already in project |
| gnark (future) | PLONK zk-SNARKs | Phase 2 |
The blockchain packages will be added to the existing monorepo under `pkg/chain/`.

783
whitepaper/WHITEPAPER.md
View File

@ -1,783 +0,0 @@
# Orama Network: The Eternal Decentralized Computer and Financial System
**Whitepaper Version 4.0**
**Date:** March 2026
**Author:** DeBros
## 1. Abstract
Orama Network is a standalone Layer-1 blockchain designed to serve as humanity's eternal decentralized computer and financial system. It combines the security and scarcity of Bitcoin with the full power of a global, censorship-resistant cloud infrastructure — all in one protocol.
Built from first principles for a 1,000-year horizon, Orama delivers:
- **Native BTC compatibility** from genesis (deposit, use, and withdraw BTC with progressively trust-minimized security).
- **Namespace-based execution** — smart contracts deploy into isolated environments with dedicated SQL databases, caches, storage, and API gateways. No shared bottleneck. No external indexing infrastructure. The namespace IS the backend.
- **Pure WASM smart contracts** so developers can write in any language they want (Rust, Go, TypeScript, C++, and any language that compiles to WebAssembly).
- **Per-transaction public/private toggle** using PLONK zk-SNARKs for optional privacy, built natively into the dual-state account model.
- **HotStuff-based BFT consensus** with Hybrid PoS + Proof of Contribution + Proof of Infrastructure, giving real power to ordinary people running nodes with OramaOS.
- **210 million $ORAMA** hard-capped supply with zero pre-mine — 100% of tokens are earned through mining, just like Bitcoin.
Orama is not an upgrade to existing chains. It is the base layer that millions of people and billions of devices will rely on for compute, storage, payments, and data ownership for centuries to come.
## 2. Introduction & Problem Statement
Centralized cloud providers control the internet's infrastructure. They can censor, surveil, or shut down services at will. At the same time, Bitcoin remains the most secure digital money ever created, yet it lacks a native programmable computer.
Existing Layer-1 blockchains force developers into rigid languages, expensive gas models, or centralized validator sets. Most projects also suffer from unfair token launches, infinite inflation, or governance capture.
Orama solves both problems at once:
- It is the **decentralized world computer** — but unlike Ethereum's "one global computer" model where every validator executes every contract, Orama gives each application its own isolated execution environment (namespace) with dedicated databases, caches, storage, and APIs. No application can clog another. No external infrastructure needed.
- It is the **Bitcoin-grade financial system** — BTC-only economy, native BTC bridge, scarce $ORAMA token, and per-transaction privacy.
## 3. Orama Network Solution & High-Level Architecture
Orama is a single Layer-1 chain with a unique two-layer architecture that solves the biggest problem in blockchain: **shared resource contention**. On Ethereum, a viral game clogs the entire network. On Orama, every application gets its own isolated infrastructure.
### The Two Layers
1. **Global Chain** (Immutable Financial Core) — all nodes participate. Handles $ORAMA and BTC balances, the native DEX, the BTC bridge, staking, slashing, and the namespace registry. Designed to be unchangeable for 1,000 years.
2. **Namespaces** (Isolated Execution Environments) — smart contracts deploy into namespaces, not onto the global chain. Each namespace is a dedicated cluster of nodes with its own database, cache, storage, API gateway, and WASM execution engine. Namespaces periodically commit state roots to the global chain, providing cryptographic proof that their execution is correct.
```
┌──────────────────────────────────────────────────────────────┐
│ GLOBAL CHAIN (all nodes participate via HotStuff consensus) │
│ │
│ • $ORAMA / BTC balances • Namespace registry │
│ • Native DEX order book • State root commitments │
│ • BTC bridge • Staking & slashing │
│ • Block rewards & emission • Governance │
└─────────────┬──────────────────┬──────────────────┬──────────┘
│ │ │
┌────────▼───────┐ ┌───────▼────────┐ ┌──────▼─────────┐
│ Namespace A │ │ Namespace B │ │ Namespace C │
│ "GameFi App" │ │ "DeFi Proto" │ │ "NFT Market" │
│ │ │ │ │ │
│ Own DB │ │ Own DB │ │ Own DB │
│ Own cache │ │ Own cache │ │ Own cache │
│ Own gateway │ │ Own gateway │ │ Own gateway │
│ Own WASM VM │ │ Own WASM VM │ │ Own WASM VM │
│ Own IPFS │ │ Own IPFS │ │ Own IPFS │
└────────────────┘ └────────────────┘ └────────────────┘
```
### Why This Architecture
Every other Layer-1 blockchain uses a single global state machine — every validator executes every smart contract. This creates a fundamental bottleneck: all applications compete for the same block space, the same throughput, and the same compute. A popular NFT mint can make a DeFi protocol unusable.
Orama's namespace model eliminates this problem by design:
- **No shared bottleneck** — each namespace runs on its own cluster of nodes with dedicated resources. One namespace cannot affect another.
- **Real developer infrastructure** — contracts in a namespace have access to a real SQL database (RQLite with Raft consensus), a real distributed cache (Olric), real IPFS storage, and a dedicated API gateway with rich query capabilities. No external indexing infrastructure needed.
- **Natural scaling** — adding nodes to the network allows more namespaces to be provisioned. No sharding complexity, no rollup escape hatches.
- **The global chain stays lean** — consensus only processes financial transactions and state commitments, not contract execution. This means higher throughput for the operations that matter most.
### Namespace Trust Model
Namespaces commit cryptographic state roots to the global chain every epoch. The global chain does not re-execute namespace transactions — it verifies that the committed state is correct.
- **Testnet & Mainnet V1**: Namespace nodes are staked validators. If they commit an incorrect state root, they are slashed. The number of nodes per namespace scales with the value at stake (minimum 3, higher for high-value protocols).
- **Mainnet V2 (future)**: Optimistic fraud proofs — a challenge period during which anyone can prove a state root is incorrect, triggering slashing.
- **Long-term (future)**: ZK validity proofs — namespaces generate zero-knowledge proofs that their state transitions are correct. Trustless verification without re-execution.
All nodes run on real hardware with OramaOS, creating true "power to the people" instead of stake-weighted whales.
## 4. Consensus Mechanism
Orama uses a **HotStuff-based BFT consensus protocol** combined with a **Hybrid PoS + Proof of Contribution + Proof of Infrastructure** validator selection model. The consensus protocol determines how blocks are produced and agreed upon. The hybrid model determines who gets to participate and how rewards are distributed.
### Consensus Protocol: HotStuff BFT
The global chain uses a pipelined BFT (Byzantine Fault Tolerant) protocol based on HotStuff. Unlike classical BFT protocols (Tendermint/PBFT) that require O(n²) messages per block — where every validator talks to every other validator — HotStuff achieves O(n) message complexity through leader-driven voting. This scales cleanly to 300+ validators.
**How a block is produced (every 6 seconds):**
1. **Leader Selection** — a block proposer is selected deterministically, weighted by Effective Power. Every node computes the same leader independently.
2. **Propose** — the leader collects transactions from the mempool, executes them against the current state, computes the new state root, and broadcasts the block.
3. **Vote** — all validators verify the block (re-execute transactions, confirm the state root matches) and send a signed vote to the next leader.
4. **Aggregate** — the next leader collects votes. When 2/3+ of Effective Power has voted, a Quorum Certificate (QC) is formed.
5. **Finalize** — the QC is included in the next block, finalizing the block from 2 rounds ago.
This pipelined approach means a new block is proposed every 6 seconds, with finality achieved in 18 seconds (3 blocks). There is no dead time between rounds.
### Effective Power Formula
$$
\text{Effective Power} = \text{Staked \$ORAMA} \times (1 + \text{Contribution Score}) \times \text{Infrastructure Multiplier}
$$
- **Proof-of-Stake**: Classic staking for economic security.
- **Proof of Contribution**: Real work performed (measured on-chain every epoch).
- **Proof of Infrastructure**: Nodes running OramaOS receive a multiplier, rewarding operators who run the hardened, secure operating system.
### Infrastructure Multiplier
- Running official OramaOS = **1.5× multiplier**
- Running without OramaOS = **1.0× (no bonus)**
A node runner with modest stake but perfect uptime, real contribution, and OramaOS can earn significantly more than a whale who only stakes large amounts of $ORAMA with no real infrastructure.
### Contribution Score (weighted every 1-hour epoch)
- Uptime: 40%
- Bandwidth served: 30%
- Compute/storage/namespace queries served: 20%
- Low latency & reliability: 10%
**Block time**: 6 seconds (14,400 blocks per day)
**Block capacity**: 1,000 transactions per block
**Epoch length**: 1 hour (600 blocks per epoch)
**Finality**: 18 seconds (3 blocks via HotStuff pipeline)
**Epoch checkpoints**: Every epoch, an additional BFT checkpoint is signed by 2/3+ of Effective Power as an extra layer of irreversibility.
**Minimum stake to validate**: 1,000 $ORAMA (mainnet only — see bootstrap below)
**Slashing**:
- Double-signing or cheating → 100% slash
- Downtime > 20% → progressive slash (5–30%)
- False infrastructure attestation → 50% slash
OramaOS attestation uses TPM-based remote attestation — cryptographically verified on-chain.
### Why HotStuff Over Other Protocols
| Protocol | Message Complexity | Finality | Max Validators | Used By |
|---|---|---|---|---|
| PBFT / Tendermint | O(n²) | 1 block (~6s) | ~200 | Cosmos |
| **HotStuff (Orama)** | **O(n)** | **3 blocks (~18s)** | **1,000+** | **Orama, Aptos (variant)** |
| Nakamoto (PoW) | O(n) | ~60 min (6 blocks) | Unlimited | Bitcoin |
| DAG-based | O(n) | 1-2 rounds | 1,000+ | Sui |
HotStuff gives Orama the best balance: linear scaling for 300+ validators today with room to grow to 1,000+, near-instant finality, and a clean leader rotation mechanism that integrates naturally with the Effective Power model.
### Staking Bootstrap
During testnet, **no staking is required** to run a node. Any node operator can participate and earn $ORAMA block rewards with zero stake. Testnet tokens carry over to mainnet — there is no reset. The tokens earned during testnet are real $ORAMA on the real chain.
At mainnet launch, the 1,000 $ORAMA minimum stake activates. By then, every testnet node runner will have earned more than enough to stake.
For new node runners joining after mainnet: acquire BTC, bridge it onto Orama, purchase $ORAMA on the native order book or bonding curve, stake, and begin earning.
## 5. Network Primitives & Execution Environment
### Dual-State Account Model
Every address on Orama has a single account with two compartments:
```
Account {
address: 0xABC...
nonce: 42
// Public compartment — visible to everyone
public: {
orama_balance: 500,000,000 rays
btc_balance: 50,000 sats
code_hash: 0x... // for contract accounts
storage_root: 0x... // Merkle root of contract storage
}
// Private compartment (Phase 2 — activated post-PLONK ceremony)
private: {
commitment_root: 0x... // Merkle root of hidden value commitments
nullifier_root: 0x... // Merkle root of spent-tracking nullifiers
}
}
```
**Public transactions** operate on the public compartment — visible, fast, and cheap. **Private transactions** (Phase 2) operate on the private compartment using PLONK zk-SNARKs, with funds moved between compartments via explicit shield/unshield operations.
This dual-state design is unique to Orama. Unlike hybrid approaches that bolt a separate "shielded pool" onto an account model, Orama's privacy is native to each account — one account, two views, no external pool contract. See Section 6 for details.
### Smart Contract Execution: Namespace Model
**Execution VM**: Pure WebAssembly (WASM) from genesis. Developers can write smart contracts in **any language** that compiles to WebAssembly — Rust, Go, TypeScript, C++, and more. No EVM, no Solidity required.
Unlike other blockchains where every validator executes every contract on a single shared state machine, **Orama smart contracts deploy into namespaces** — isolated execution environments with dedicated infrastructure.
**What a namespace provides to a smart contract:**
| Primitive | Implementation | What It Gives Developers |
|---|---|---|
| **SQL Database** | RQLite (distributed SQL with Raft consensus) | Real SQL queries — SELECT, INSERT, UPDATE, DELETE with JOINs, indexes, and transactions |
| **Key-Value Cache** | Olric (distributed, consistent hashing) | Sub-millisecond reads, TTL-based expiry, perfect for hot data |
| **Object Storage** | IPFS (content-addressed, replicated) | Store files, images, metadata — addressed by content hash |
| **API Gateway** | Dedicated HTTP/WebSocket gateway | Rich query API with filtering, pagination, sorting — no external indexer needed |
| **WASM Runtime** | wazero (pure Go WebAssembly engine) | Sandboxed execution with host functions for all primitives |
| **WebRTC** | Pion SFU + TURN (optional) | Real-time voice, video, and data channels |
**This solves Ethereum's biggest developer pain point.** On Ethereum, deploying a contract is only the beginning — you then need The Graph for indexing, Alchemy for RPC, IPFS pinning services for storage, and a separate backend for anything that requires a database. On Orama, the namespace IS your backend. Deploy a contract and you immediately have a database, cache, storage, and a queryable API.
### How Contract Deployment Works
```
1. Developer writes a WASM contract (Rust, Go, TypeScript, etc.)
2. Developer deploys to a namespace (creates one or uses existing)
3. The namespace provisions a dedicated cluster:
- 3+ nodes with RQLite, Olric, IPFS access, Gateway, WASM VM
- Dedicated ports, DNS subdomain, isolated from other namespaces
4. The contract runs in the namespace's WASM engine
5. The namespace commits state roots to the global chain every epoch
6. The global chain records the commitment — it does not re-execute
```
### Rich Query RPC
Every namespace's API gateway serves powerful, filterable queries over contract data — eliminating the need for external indexing infrastructure:
```
GET /v1/contracts/{address}/state/users?sort=created_at&order=desc&limit=20
GET /v1/transactions?address=0xABC...&limit=50
GET /v1/nfts?owner=0xABC...&collection=0xDEF...
GET /v1/blocks/12345
```
The node indexes contract state changes locally and serves them through the RPC. No Graph. No subgraphs. No external infrastructure. One API call.
### Global Chain Primitives
The following primitives live on the global chain (not in namespaces) because they are part of the immutable financial core:
- **$ORAMA and BTC transfers** — direct balance changes on the global state
- **Native DEX order book** — the $ORAMA/BTC trading pair (see Section 9)
- **BTC bridge** — deposit and withdrawal of BTC (see Section 7)
- **Staking and slashing** — validator economics
- **Governance** — on-chain voting (see Section 12)
- **Namespace registry** — which namespaces exist, their owners, and their committed state roots
Gas for global chain transactions is paid in $ORAMA. Base fee is burned. All global primitives integrate seamlessly with the public/private toggle.
### AI Marketplace & Angels
Orama has a native **AI Marketplace** — a protocol-level primitive for hosting and consuming AI models and AI agents (called **Angels**).
**For compute providers:**
- Register compute capacity on the network and host AI models or Angels (autonomous AI agents).
- Get paid per API call in $ORAMA — pricing is set by the provider and visible to all callers.
- Compute providers do **not** receive extra block rewards. Their revenue comes entirely from marketplace demand.
**For developers and users:**
- Call any hosted AI model or Angel from WASM contracts or via RPC.
- Pay per use in $ORAMA — transparent pricing, competitive marketplace.
**For Angel builders:**
- Deploy autonomous AI agents that can interact with Orama's namespace primitives (SQL, storage, cache, BTC bridge, DEX).
- Angels can hold $ORAMA, execute transactions, manage data, and interact with other Angels.
- Revenue model: builders set per-request or subscription pricing in $ORAMA.
**Compute provider economics:**
- Compute providers run standard Orama nodes (earning normal block rewards) plus optional AI capacity.
- AI revenue is purely market-driven — if demand is high, providers earn well. If demand is low, they still earn normal mining rewards from their standard node.
- The protocol caps compute-provider nodes at **10% of total network nodes** to prevent disproportionate influence.
- A provider with expensive hardware earns the same block rewards as any other node — plus whatever the marketplace pays them. The market decides if the investment is worth it.
## 6. Privacy Model
Every transaction has a simple **public/private toggle**:
- **Public** (default): Fully transparent, lowest cost.
- **Private**: Uses PLONK-based zk-SNARKs to shield sender, receiver, and amount. Only the participants know the details.
### Why PLONK
Zero-knowledge proofs require a cryptographic setup. Older systems (Groth16) need a new trusted setup ceremony for every circuit change — if any participant in the ceremony is dishonest, the system can be compromised. PLONK uses a **universal trusted setup**: performed once at genesis with hundreds of public participants, and valid for all future circuit upgrades. As long as one participant was honest and destroyed their contribution, the system is secure forever.
This means Orama can upgrade its privacy features (new transaction types, improved circuits) without ever needing another ceremony.
### Privacy Mechanics
- Gas cost for private mode = **4×** public mode (covers ZK proving).
- Smart contracts can enforce "private-only" mode for sensitive applications.
- Private transactions hide sender, receiver, and amount — but the transaction's existence is still visible on-chain.
- No network-level onion routing — privacy is pure cryptography, not traffic obfuscation.
## 7. Native BTC Integration & Bridge
### BTC-Only Economy
Orama has exactly two assets: **BTC** and **$ORAMA**. No stablecoins. No wrapped altcoins. No fiat pegs. Nothing else.
To acquire $ORAMA, you must use BTC. This is a deliberate design choice:
- **Zero counterparty risk** beyond Bitcoin itself — no exposure to stablecoin depegs, altcoin crashes, or centralized token issuers.
- **No dependence on external exchanges** — Orama's economy is self-contained.
- **Hard money priced in hard money** — $ORAMA's value is always denominated in BTC, the most battle-tested digital asset in existence.
If someone wants to buy $ORAMA, they acquire BTC (anywhere in the world), bridge it onto Orama, and trade on the native order book. If they want to exit, they sell $ORAMA for BTC and bridge it back to Bitcoin mainnet.
### Trust-Minimized BTC Bridge
Orama has a **native BTC bridge built into the protocol from genesis**, designed to progressively increase its trust guarantees as the network matures.
- Deposit BTC → receive native BTC on Orama (1:1).
- Use BTC to buy $ORAMA, pay for services, or use in smart contracts.
- Withdraw back to Bitcoin mainnet.
The bridge is further backed by a **protocol reserve** — BTC accumulated from bonding curve sales (see Section 9). This reserve provides additional collateral beyond the 1:1 deposits, ensuring the bridge remains solvent even under extreme conditions.
### Bridge Phases
The bridge security model strengthens over time, from validator-secured to cryptographically verified:
**Testnet → Mainnet V1: Validator Threshold Bridge**
The top validators by Effective Power form a threshold signature group. Deposits are detected by validators watching the Bitcoin chain; withdrawals require a supermajority (e.g., 7-of-10) of the validator group to sign the Bitcoin transaction. Validators are staked — cheating means losing their entire stake. This model is proven, ships fast, and enables the full BTC economy (DEX, bonding curve, bridge fees) from day one.
**Mainnet V2: Light Client + Optimistic Fraud Proofs**
A Bitcoin SPV (Simple Payment Verification) light client is embedded in the Orama protocol. The chain verifies Bitcoin block headers and Merkle inclusion proofs natively — deposits are verified cryptographically with no human attestation required.
Withdrawals use an optimistic model: a withdrawal is posted and enters a challenge period (e.g., 24 hours). If any validator can prove the withdrawal is invalid, it is reverted and the submitter is slashed. Security assumption: **1-of-N honest** — as long as one honest watcher exists in the entire world, fraud cannot succeed.
**Long-term: Cryptographic Validity Proofs**
As BTC bridge research matures (BitVM, ZK validity proofs), the bridge upgrades to fully cryptographic verification. No challenge period — the proof IS the verification. This is the ultimate trust-minimized design.
**Each phase is a strict upgrade** — the bridge fee structure, user experience, and economic model remain identical. Only the trust model under the hood improves.
### Testing
The bridge code is environment-aware, connecting to different Bitcoin networks per Orama environment:
| Orama Environment | Bitcoin Network | BTC Source |
|---|---|---|
| Devnet | Bitcoin Regtest (local) | Mine instantly, unlimited test BTC |
| Testnet | Bitcoin Testnet4 (public) | Free from faucets, zero value |
| Mainnet | Bitcoin Mainnet | Real BTC |
The same bridge code runs across all environments — only the configuration changes.
### Bridge Fee
**Fee: 0.25%** of every bridge transaction (deposit or withdrawal).
| Share | Recipient | Mechanism |
|---|---|---|
| 50% | Validators | Paid directly in BTC, distributed by Effective Power |
| 50% | DeBros Team NFT holders | Auto-swapped to $ORAMA on the native order book, sent to holders' RootWallet |
The NFT holder share creates a perpetual buy engine for $ORAMA: every bridge transaction automatically purchases $ORAMA on the open market, creating constant buy pressure that grows with network usage.
Minimum bridge amount: 0.001 BTC. No maximum.
## 8. Tokenomics & Economic Model
**Token**: $ORAMA
**Total Supply**: **210,000,000** (hard cap forever).
### Zero Pre-mine. Zero Airdrop. 100% Mined.
Every single $ORAMA token is earned by running a node — no exceptions. There is no team allocation, no investor round, no foundation reserve, no airdrop, and no pre-mine. The creators earn tokens the same way as everyone else: by running nodes.
This is the only truly fair model. Nobody starts with an advantage. Nobody dumps on you.
### Block Reward Distribution
Each block reward is split:
- **80%** → directly to the block proposer (the node runner who produced the block, weighted by Effective Power)
- **20%** → into the protocol bonding curve inventory (see Section 9: Native DEX), capped at 21,000,000 $ORAMA total. Once the curve has accumulated 21M tokens, the 20% share redirects to the block proposer (miners receive 100%).
### Emission Schedule
$ORAMA uses a fixed block reward with a Bitcoin-style halving:
| Era | Years | Block Reward | Approx. Annual Emission | Cumulative Supply |
|-----|-------|-------------|------------------------|-------------------|
| 1 | 1–2 | 100 $ORAMA | ~52.5M | ~105M |
| 2 | 3–4 | 50 $ORAMA | ~26.25M | ~157.5M |
| 3 | 5–6 | 25 $ORAMA | ~13.1M | ~183.7M |
| 4 | 7–8 | 12.5 $ORAMA | ~6.6M | ~196.9M |
| 5 | 9–10 | 6.25 $ORAMA | ~3.3M | ~203.5M |
| 6+ | 11+ | Continues halving | Asymptotically approaches 210M | 210M cap |
50% of the total supply is emitted in the first 2 years — rewarding the earliest node runners who take the biggest risk. The halving creates predictable, decreasing issuance that anyone can verify at any block height. When the remaining emittable supply is less than the block reward, the block reward equals the remaining supply — ensuring the 210M cap is never exceeded.
### Transaction Fees
**Smallest unit:** 1 $ORAMA = **1,000,000 rays**. All fees are denominated in rays.
**Genesis fee schedule:**
| Operation | Cost | Layer |
|---|---|---|
| $ORAMA / BTC transfer | 1,000 rays (0.001 $ORAMA) | Global chain |
| DEX order book trade | 1,000 rays | Global chain |
| Namespace state commitment | 2,000 rays | Global chain |
| Private transaction (zk-SNARK) | 4× the public equivalent | Global chain |
| Namespace operations (SQL, KV, IPFS, WASM) | Paid via namespace billing in $ORAMA | Namespace |
**Congestion multiplier:** Fees adjust dynamically based on block fullness (EIP-1559 model). When blocks are at 50% capacity (~500 transactions), the multiplier is 1×. As blocks fill toward the 1,000 transaction limit, the multiplier rises (up to 10×). When blocks are under half full, it drops below 1×. This prevents spam during peak demand and keeps fees low during normal usage.
**Fee distribution:**
- **Base fee** → burned. The more the network is used, the more $ORAMA is permanently removed from supply.
- **Priority fee** → 100% to block proposer (weighted by Effective Power).
- **BTC bridge fee** (0.25%) → 50% to validators, 50% auto-swapped to $ORAMA for DeBros Team NFT holders (see Section 10).
**Governance-adjustable:** The fee schedule is a compute layer parameter, not part of the immutable financial core. Governance can vote to adjust fee amounts to ensure the network remains affordable as $ORAMA appreciates in value. The community has a strong incentive to keep fees low — expensive fees drive users away, hurting the network and the token.
As usage grows and emissions shrink, $ORAMA becomes increasingly deflationary — a self-reinforcing flywheel for centuries.
## 9. Native DEX & Liquidity
Orama does not rely on external exchanges. The chain has its own **protocol-native exchange** built into the global chain as a first-class primitive.
### The Bootstrap Problem
At genesis, supply is near zero. Node runners are earning $ORAMA for the first time. Buyers who bridge BTC onto Orama need a way to purchase $ORAMA. The protocol solves this with two mechanisms that work together:
### Protocol Bonding Curve
The protocol itself acts as the first market maker — not a person, not a DAO, but pure math.
20% of every block reward flows into the bonding curve's sell-side inventory (capped at 21,000,000 $ORAMA total). Anyone can buy $ORAMA from the curve by sending BTC (bridged onto Orama). The price follows a square root function:
$$
\text{Price} = k \times \sqrt{\text{total\_sold\_from\_curve}}
$$
Where `k = 0.0000000006 BTC` — calibrated at genesis so the curve starts cheap (rewarding early risk-takers) and rises aggressively as demand grows.
**Curve price schedule:**
| Tokens Sold from Curve | Price per $ORAMA | Cumulative BTC Spent |
|---|---|---|
| 10,000 | 0.00000006 BTC | 0.0004 BTC |
| 100,000 | 0.00000019 BTC | 0.013 BTC |
| 1,000,000 | 0.0000006 BTC | 0.4 BTC |
| 5,000,000 | 0.00000134 BTC | 4.5 BTC |
| 10,000,000 | 0.0000019 BTC | 12.7 BTC |
| 21,000,000 (max) | 0.00000275 BTC | ~38.5 BTC |
Total BTC to fill the entire curve: **~38.5 BTC**. This BTC flows into the protocol reserve, directly backing the BTC bridge.
**Properties:**
- Always available — the curve always has a price and always has inventory (as long as blocks are being produced and the 21M cap hasn't been reached).
- Cheap early, expensive later — the first tokens cost fractions of a cent, rewarding those who take the earliest risk.
- The curve is a **guaranteed liquidity backstop** — when the order book is thin, buyers can always purchase from the curve. The free market (order book) determines the real price.
- Self-reinforcing: more people buy $ORAMA → more BTC in the protocol reserve → stronger bridge → more confidence → more demand.
**Sunset mechanism:** When the native order book achieves sufficient organic liquidity (average daily volume exceeds a governance-defined threshold for 30 consecutive days), the curve's share of block rewards drops to 0%. All rewards flow directly to node runners. The curve keeps its remaining inventory and stays available, but stops being refilled. The free market takes over entirely.
### Protocol-Native Order Book
The primary trading venue is a **native order book** — a chain primitive, not a smart contract.
Any holder of $ORAMA can place sell orders. Any holder of BTC (bridged onto Orama) can place buy orders. The protocol matches orders when prices cross. No intermediary. No privileged LP class. Pure price discovery. One pair: **$ORAMA/BTC**.
**Standard interface (callable from WASM contracts and external RPC):**
- `place_order(pair, side, amount, price)` — place a limit order
- `market_order(pair, side, amount)` — execute at best available price
- `cancel_order(order_id)` — cancel an open order
- `get_orderbook(pair)` → current bids and asks
- `quote(pair, side, amount)` → expected fill price and size
**Third-party integration:** Any wallet, aggregator, or exchange in the world can integrate by calling these functions over Orama's RPC. No permission required. No listing fees. No gatekeepers.
### Why an Order Book, Not an AMM
| | AMM | Order Book |
|---|---|---|
| Bootstrap | Needs liquidity providers with both assets — chicken-and-egg | Just needs sellers and buyers — works from block 1 |
| Fairness | LPs earn special yield (creates a privileged class) | No special roles — everyone is a trader |
| Capital efficiency | Liquidity spread across entire price curve | Concentrated at actual price levels |
| Philosophy | Complex, opaque | Simple, transparent, free |
### Permissionless WASM DEX Contracts
The protocol-native order book handles the core pair: **$ORAMA/BTC**. For tokens created on Orama via WASM contracts deployed in namespaces, anyone can deploy AMMs or order books as WASM smart contracts. Custom tokens trade against $ORAMA — creating a clear asset hierarchy:
```
BTC (bridged from Bitcoin mainnet)
↕ protocol-native order book
$ORAMA (gas token, earned through mining)
↕ permissionless WASM DEX contracts
Custom tokens (created on Orama)
```
The protocol defines a standard swap interface that all DEX contracts can implement, enabling aggregation and composability across the ecosystem.
## 10. DeBros NFT Collections
### DeBros Team NFTs (100) — The Founding Collection
**100 DeBros Team NFTs** — the founding collection of the Orama Network. These NFTs were originally minted on Solana and will be migrated to Orama at mainnet launch via snapshot.
**Supply:** 100 (fixed forever — no more will ever be minted).
**Revenue:** 50% of all BTC bridge fees, auto-swapped to $ORAMA and distributed to holders every epoch.
**Governance:** 40% of total voting power (5 votes per NFT). See Section 12.
**Tradeable:** Yes, freely on Orama's native marketplace. Anyone can buy one and receive their share of bridge revenue and governance power.
### DeBros NFTs (700) — The Community Collection
**700 DeBros NFTs** — the broader community collection. Migrated from Solana to Orama at mainnet via snapshot, alongside the Team collection.
**Supply:** 700 (fixed forever).
**Governance:** 35% of total voting power (1 vote per NFT). See Section 12.
**Tradeable:** Yes, freely on Orama's native marketplace.
These NFTs represent the wider community that supported the network in its earliest days. They carry significant governance weight — together with the Team NFTs, NFT holders control 75% of all voting power.
### Migration from Solana
At mainnet launch, a snapshot of all DeBros NFT holders (both collections) on Solana will be taken. Equivalent NFTs are minted natively on Orama and linked to holders' RootWallet addresses. The Solana originals remain as historical artifacts — the Orama versions are the ones connected to revenue and governance.
### Why These Exist
These NFTs honor the community that believed in and built the Orama Network before the blockchain existed. They took the earliest risk. The bridge fee share and governance power are their reward — not a privilege granted in secret, but open, transparent, and tradeable instruments that anyone can participate in by purchasing an NFT on the open market.
### Revenue Flywheel
```
More bridge usage → more BTC fees collected
→ more $ORAMA auto-bought on order book → buy pressure on $ORAMA
→ NFT holders receive more $ORAMA → NFTs become more valuable
→ more attention on Orama → more users → more bridge usage
```
## 11. Token Standards & Scaling
### OTS-1: Orama Token Standard (Fungible Tokens)
Fungible tokens are WASM contracts deployed in namespaces that implement the **OTS-1** interface. Designed from scratch to fix ERC-20's known problems:
- **No unlimited approvals** — the operator model requires an explicit spending limit. No "approve MAX_UINT" footgun that leads to wallet drains.
- **Memo field on transfers** — attach context (invoice ID, payment reason) to any transfer.
- **Explicit revoke** — `revoke_operator()` is a first-class operation, not `approve(addr, 0)`.
- **Global token registry** — tokens register on the global chain so wallets and explorers discover them. Symbol uniqueness is enforced (no impersonation).
- **Queryable** — token balances, transfer history, and holder lists are queryable via the namespace RPC. No external indexer needed.
$ORAMA and BTC are global chain native assets — they are not OTS-1 contracts.
### ONS-1: Orama NFT Standard (Non-Fungible Tokens)
NFTs are WASM contracts deployed in namespaces that implement the **ONS-1** interface. Designed from scratch to fix ERC-721's known problems:
- **On-chain metadata** — stored in the namespace's database and IPFS. No external URLs that can break. Queryable by attribute via SQL.
- **Batch operations** — `batch_transfer` and `batch_mint` are part of the standard. Moving 50 NFTs = 1 transaction.
- **Built-in royalties** — `royalty_info()` is mandatory, not optional. Enforced by marketplaces.
- **Enumerable by default** — `tokens_of(owner)` is part of the standard. List someone's NFTs without an indexer.
- **Two-level operators** — collection-wide approval OR per-token approval.
- **Global NFT registry** — collections register on the global chain for discovery.
**DeBros NFTs** (100 Team + 700 Community) are a special case — they live on the global chain (not in a namespace) because they carry governance power and bridge revenue rights. They are minted once at mainnet genesis from the Solana snapshot.
### Scaling
Orama's namespace architecture provides natural horizontal scaling — each namespace is an isolated execution environment with dedicated resources. Adding nodes to the network allows more namespaces to be provisioned. No sharding, no rollup escape hatches. For extreme-scale use cases, namespaces can optionally implement optimistic or zk-rollup patterns internally, with finality settling on the global chain.
## 12. Governance
Orama governance is fully on-chain — no off-chain snapshots, no forum polls, no "the foundation decided." Every proposal, every vote, and every result is recorded on-chain and verifiable by anyone.
### Voting Power Distribution
Total voting power is split by category, not by individual token math. NFT holders always control 75% of governance — no whale can ever outweigh them.
| Group | Voting Power | Per Unit | Total Units |
|---|---|---|---|
| DeBros Team NFTs (100) | **40%** | 5 votes per NFT | 500 votes within pool |
| DeBros NFTs (700) | **35%** | 1 vote per NFT | 700 votes within pool |
| $ORAMA token holders | **25%** | Quadratic: √(tokens held) | Proportional within pool |
Within each group, voting power is distributed proportionally. A whale who buys all circulating $ORAMA still only controls 25% of total governance — they can never override NFT holders.
### Testnet Governance
During testnet (before NFT migration), governance operates through the DeBros team directly. This is the only period where governance is not fully on-chain. At mainnet launch, when NFTs are migrated and the governance contracts are live, all decision-making transitions to the on-chain system permanently.
### Three Tiers of Decisions
Not all decisions need the same process. Governance is split by urgency and impact:
#### Tier 1: Emergency Actions (24 hours)
*Security patches, active exploit response, critical network fixes.*
**Who decides:** DeBros Team NFT holders only (40% pool).
**Threshold:** 60% of Team NFT votes cast within 24 hours.
**Safeguard:** All Tier 1 actions are logged on-chain and can be reversed by a Tier 2 vote within 7 days. The Team can act fast, but the community can override them.
Emergency is strictly defined: security vulnerabilities, active exploits, and network-critical bugs. The Team cannot use Tier 1 for non-emergency changes.
#### Tier 2: Protocol Upgrades (3 days)
*Fee schedule changes, new primitives, compute layer upgrades, merging significant core changes.*
**Who decides:** All three groups vote.
**Threshold:** 66% approval over a 3-day voting period.
#### Tier 3: Constitutional Changes (14 days)
*Changes to governance structure, bridge fee percentages, bonding curve parameters.*
**Who decides:** All three groups vote.
**Threshold:** 90% approval over a 14-day voting period.
**Truly immutable (no tier can change these):**
- 210 million $ORAMA supply cap
- Emission schedule and halving
- BTC-only economy
- 100% mining distribution (zero pre-mine)
- BTC bridge core security model
### How Voting Works
```
1. Any wallet with voting power submits a proposal (with tier classification)
2. Proposal enters voting period (24h / 3 days / 14 days)
3. Holders vote from their RootWallet
4. Votes are weighted by group allocation (40% / 35% / 25%)
5. If threshold is met, change executes automatically on-chain
6. All votes and results are permanently recorded
```
### Why This Model
Most blockchains have governance captured by whales or controlled by a handful of insiders pretending to be decentralized. Orama's model ensures:
- **No whale capture** — token holders are capped at 25% voting power regardless of holdings.
- **Fast emergency response** — Team NFT holders can act within hours, not days.
- **Community check** — 700 DeBros NFT holders can block the Team (35% vs 40% — Team can't pass Tier 2 alone).
- **Public voice** — token holders have meaningful input but can never overpower the community that built the network.
- **Open participation** — all NFTs are freely tradeable. Anyone can buy voting power on the open market.
## 13. Security Model & Attack Resistance
### Consensus Attacks
- **51% attack**: Requires controlling a majority of Effective Power — which means real uptime, real contribution, and real stake. An attacker can't just buy tokens; they need physical infrastructure and months of contribution history. This makes attacks orders of magnitude more expensive than pure PoS chains.
- **Nothing-at-stake**: Prevented by double-slashing — validators who sign conflicting blocks lose both their stake and their accumulated contribution score. The contribution score takes months to build, making it a meaningful deterrent.
- **Long-range attacks**: HotStuff BFT finalizes every block within 3 rounds (18 seconds). Additionally, epoch-level checkpoints are signed by 2/3+ of Effective Power every hour. Reorganizing beyond a finalized block is impossible.
- **Sybil attacks**: OramaOS attestation is verified via TPM — an attacker can't fake infrastructure multipliers without the real hardware and software.
- **Leader failure**: HotStuff's view-change mechanism handles unresponsive leaders cleanly — if the selected proposer fails to produce a block within the timeout, the next leader takes over without stalling the chain.
### BTC Bridge Security
The bridge security model strengthens across phases (see Section 7):
- **Phase 1 (testnet)**: Validator threshold signatures — staked validators sign bridge operations. Cheating means losing their entire stake.
- **Phase 2 (mainnet)**: Bitcoin SPV light client verifies deposits cryptographically. Withdrawals use optimistic fraud proofs with a challenge period (1-of-N honest assumption).
- **Phase 3 (future)**: Full cryptographic validity proofs — trustless verification with no challenge period.
- **Protocol reserve**: BTC accumulated from bonding curve sales provides additional collateral beyond 1:1 deposits.
- **Bridge halt**: If anomalous withdrawal patterns are detected (e.g., more than 10% of bridged BTC withdrawn in a single epoch), the bridge automatically pauses and requires a Tier 1 governance vote to resume.
### Namespace Security
- **Isolation**: Each namespace runs on a dedicated cluster with its own database, cache, and gateway. A compromised or malicious contract in one namespace cannot affect any other namespace or the global chain.
- **State commitments**: Namespaces commit state roots to the global chain. Invalid state roots result in slashing of the namespace's validator nodes.
- **Staked validators**: Namespace nodes are staked — the economic cost of attacking a namespace is proportional to the stake at risk.
- **Scaling trust**: High-value namespaces can require more validator nodes (e.g., 5 or 10 instead of the default 3), increasing the cost of collusion.
### DEX & Order Book Security
- **Front-running prevention**: Order book transactions within the same block are processed in a randomized order (using the block hash as a deterministic seed), not by gas price. This eliminates MEV (Miner Extractable Value) — block proposers cannot reorder transactions to front-run traders.
- **Price manipulation**: The bonding curve provides a reference price that cannot be manipulated by wash trading on the order book.
### Network Security
- **Encrypted mesh**: All inter-node communication is encrypted via WireGuard VPN tunnel. Internal services (database, cache, gateways) are never exposed on public IPs.
- **OramaOS hardening**: No SSH, read-only rootfs, service sandboxing — the attack surface per node is minimal (see Section 14).
- **Forged attestation**: Nodes submitting fake infrastructure proofs are slashed 50% and permanently flagged.
### Code Security
- All critical protocol components are open-source.
- Formal verification applied to consensus, bridge, and token contract logic where possible.
- Bug bounty program from testnet launch.
## 14. OramaOS & Orama One
### OramaOS — The Hardened Node Operating System
OramaOS is a custom minimal operating system purpose-built for Orama nodes. Running OramaOS provides the **1.5× Infrastructure Multiplier**.
**Security architecture:**
- **No remote shell access** — operators cannot access the filesystem. There is zero attack surface for remote exploitation.
- **Read-only root filesystem** — the OS cannot be tampered with, even by the node operator.
- **Full-disk encryption** with Shamir secret sharing for key distribution across the network.
- **Atomic updates** with automatic rollback if a new version fails. Every update is cryptographically signed and verified before applying.
- **Single root process** (orama-agent) — manages boot, encrypted mesh connectivity, and all service lifecycle. No other process runs as root.
- **Process isolation** — each service is sandboxed and isolated from every other.
**Runs anywhere:** OramaOS can be installed on any modest cloud server or on dedicated hardware. The same image runs on a cloud instance and on Orama One.
Most blockchain nodes run on stock operating systems with full remote access and services running as root. OramaOS is hardened like a hardware wallet operating system — because the node IS a financial system.
### Orama One — The People's Hardware Node
Orama One is a purpose-built, 3D-printed hardware node designed for the Orama Network. It ships pre-loaded with OramaOS.
**Design philosophy:** Anyone should be able to own and run a node. Not a mining rig. Not a server rack. A quiet, low-power device that sits on your desk and earns $ORAMA.
**Key features:**
- Pre-loaded with OramaOS — plug in power, connect to internet, it joins the network automatically.
- Open-source hardware — the enclosure design and bill of materials will be published so anyone can build their own.
- Low power consumption — designed to run continuously without significant energy costs.
- Compact and silent — suitable for home use.
Minimum hardware specifications are published in [Appendix B](APPENDIX_B_HARDWARE_SPECS.md).
### Infrastructure Attestation
The network must verify that a node is genuinely running OramaOS — not faking the multiplier. Attestation uses **TPM-based remote attestation**:
1. The node's TPM chip generates a cryptographic measurement of the boot chain and running software.
2. This measurement is submitted on-chain every epoch.
3. The protocol verifies the measurement against known-good OramaOS signatures.
4. Nodes that fail attestation lose their Infrastructure Multiplier immediately.
5. Nodes that submit forged attestations are slashed 50%.
This is cryptographic proof, not trust — the network doesn't take the node's word for it.
## 15. Genesis, Bootstrap & Launch Mechanics
### 300-Node Genesis Requirement
Orama does not launch mainnet until a minimum of **300 independent nodes** are running and verified. This is a hard requirement — no shortcuts, no exceptions. Most L1 blockchains launch with a handful of validators controlled by insiders. Orama launches with 300 real nodes operated by real people on real hardware, making it one of the most decentralized networks from block one.
### Timeline
- **Testnet**: Existing Orama network nodes upgrade and begin earning $ORAMA block rewards immediately. No staking required. New node operators join during testnet to reach the 300-node threshold. Testnet tokens are real — they carry over to mainnet.
- **Mainnet**: Full production launch with BTC bridge and native DEX live. Staking activated (1,000 $ORAMA minimum). DeBros NFT migration from Solana. On-chain governance begins. Every token in existence was earned through mining — no snapshots, no discretion, no privilege.
## 16. Roadmap & Implementation Plan
| Phase | Milestones |
|---|---|
| **Testnet** | Network launch, no staking required, node runners begin earning $ORAMA, PLONK trusted setup ceremony, bug bounty program |
| **Testnet Expansion** | AI Marketplace beta, Angels framework, compute provider registration, Orama One pre-orders |
| **Testnet Maturity** | 300-node threshold target, DeBros NFT migration preparation, bonding curve live on testnet, native order book testing |
| **Mainnet** | Full production launch, BTC bridge live, native DEX live, staking activated, DeBros NFT bridge revenue begins, on-chain governance live |
| **Post-Launch** | L2 rollup support, AI Marketplace expansion, post-quantum signature upgrade, Orama One general availability |
| **Long-Term** | Governance-driven improvements, bonding curve sunset when organic liquidity is sufficient, financial core remains immutable forever |
## 17. Risks, Mitigations & Eternal Safeguards
| Risk | Severity | Mitigation |
|---|---|---|
| **51% attack** | High | Proof of Infrastructure requires real uptime + contribution, not just stake. TPM attestation prevents fake nodes. |
| **BTC bridge exploit** | Critical | Phased security model: validator threshold signatures (testnet) → Bitcoin light-client + optimistic fraud proofs (mainnet) → cryptographic validity proofs (future). Automatic bridge halt on anomalous withdrawals. Protocol reserve as additional collateral. |
| **Governance capture** | High | NFT holders control 75% of voting power. Quadratic voting for token holders prevents whale dominance. Immutable financial core cannot be changed by any vote. |
| **Quantum computing** | Medium | Post-quantum signature upgrade on roadmap. PLONK proof system can be upgraded to quantum-resistant circuits via universal setup. |
| **Regulatory risk** | Medium | Fully decentralized, no single legal entity. OramaOS nodes have no remote access — even the operator can't be compelled to modify the software. |
| **AI Marketplace abuse** | Medium | Compute nodes capped at 10% of network. Marketplace is purely opt-in. Malicious models can be flagged via governance. |
| **Bonding curve manipulation** | Low | Curve price is mathematical (√n) — cannot be manipulated. Order book has randomized transaction ordering to prevent front-running. |
| **Namespace isolation failure** | Medium | Each namespace runs on a dedicated cluster with separate database, cache, and gateway. State roots are committed to the global chain and verified. Namespace validators are staked — incorrect state roots trigger slashing. |
The protocol is designed to outlive any single person, company, or government.
## 18. Conclusion & Call to Build
Orama Network is not another blockchain experiment. It is the base layer for the next thousand years of human digital life — a true decentralized computer that anyone with modest hardware can help secure, and a financial system as scarce and sovereign as Bitcoin.
We invite every node runner, developer, and user to join at mainnet launch. No tokens to buy beforehand. No presale to miss. Just run a node, earn $ORAMA, and be part of the only blockchain where everyone starts equal. The code is open-source. The rules are set in stone. The power belongs to the people.
**rootwallet.io** will be the official wallet from day one.
Together we build the eternal system.
— DeBros
---
- [Appendix A: Emission Curve & Halving Schedule](APPENDIX_A_EMISSION_CURVE.md)
- [Appendix B: Orama One Hardware Specs](APPENDIX_B_HARDWARE_SPECS.md)
- [Appendix C: Bonding Curve Price Table & BTC Reserve Projections](APPENDIX_C_BONDING_CURVE.md)
- [Appendix D: PLONK Trusted Setup Ceremony Specification](APPENDIX_D_PLONK_SETUP.md)
- [Appendix E: Sample WASM Contract](APPENDIX_E_SAMPLE_CONTRACT.md)
- [Appendix F: Effective Power & Slashing Math](APPENDIX_F_MATH_PROOFS.md)
- [Appendix G: Technical Architecture](APPENDIX_G_TECHNICAL_ARCHITECTURE.md)