Technical specification for a dual-layer monetary system: UBX (elastic transactional layer, COP-reference band) and KNEX (fixed-supply reserve + settlement layer). Built on a Nano-inspired block-lattice DAG with Proof-of-Bandwidth (PoB) consensus and Open Representative Voting (ORV) finality.
Bootstrap: Assets are currently issued on Stellar for distribution + liquidity rails. Target: Migration to a native L1 DAG where UBX and KNEX are first-class protocol assets.
UBX is the elastic, bearer-like circulation unit for everyday payments. Merchants price goods in UBX using a COP reference (~1 UBX ≈ 1,000 COP, ±20% tolerance). KNEX is the fixed-supply (100,000,000) reserve asset for settlement, validator bonding, and long-term value accumulation. Neither token works alone: UBX provides velocity, KNEX provides scarcity. Economic gravity flows directionally from UBX (circulation) to KNEX (accumulation).
Phase 1 (Current): Both UBX and KNEX are issued on Stellar. DEX trading provides liquidity. Wallets use Stellar SDK. Settlement is 3-5 seconds. Phase 2 (Target): Native block-lattice DAG with Proof-of-Bandwidth consensus, sub-second finality, feeless UBX transactions, and full validator economics. Migration via balance snapshot and 1:1 address mapping.
UBX does not require centralized exchanges to function. Stellar DEX is used as a bootstrap liquidity layer (on/off ramps, early market depth, and conversion rails) while the “true” price discovery model is merchant-driven: goods and services priced directly in UBX using a COP reference band. Over time, as UBX velocity and merchant density grow, reliance on speculative venues decreases and stability emerges from real economic usage.
Traditional blockchains serialize all transactions into sequential blocks, creating bottlenecks. A DAG allows parallel transaction processing — each account maintains its own chain, enabling unlimited horizontal scaling. For a dual-token system processing both UBX micropayments and KNEX settlement, this parallelism is essential.
BLOCKCHAIN (Sequential) DAG / BLOCK-LATTICE (Parallel)
───────────────────── ────────────────────────────────
┌───┐ ┌───┐ ┌───┐ Account A: ●──●──●──●──●
│ 1 │──▶│ 2 │──▶│ 3 │ Account B: ●──●──●──●──●
└───┘ └───┘ └───┘ Account C: ●──●──●
▼ Account D: ●──●──●──●
All txns wait ↑ ↑ ↑
for blocks Independent chains
Parallel processing
SYSTEM ARCHITECTURE (Current → Target)
═══════════════════════════════════════
┌──────────────────────────────────────────────────┐
│ APPLICATION LAYER │
│ KnexPay PWA │ NFC SmartBills │ KnexKeys │
│ (merchant) (NTAG 424 DNA) (keygen) │
└───────────────────────┬──────────────────────────┘
│
┌───────────────────────┼──────────────────────────┐
│ DISTRIBUTION LAYER │
│ ┌─────────────┐ │ ┌─────────────────┐ │
│ │ Stellar │ ◄──┤───► │ Native L1 DAG │ │
│ │ (Phase 1) │ │ │ (Phase 2) │ │
│ │ 3-5s finality│ │ │ <1s finality │ │
│ └─────────────┘ │ └─────────────────┘ │
└──────────────────────┼───────────────────────────┘
│
┌───────────────────────┼──────────────────────────┐
│ TOKEN LAYER │
│ UBX (elastic, COP-reference band, merchant payments) │
│ KNEX (fixed 100M, settlement, validator bonds) │
└──────────────────────────────────────────────────┘
The KNEX/UBX system implements a dual-layer monetary design. Each layer serves a distinct economic function. Neither token works in isolation — UBX provides velocity, KNEX provides scarcity. Value flows directionally from the circulation layer to the reserve layer over time.
UBX is the primary user-facing currency for everyday payments. It is designed to behave like digital cash for Colombia: fast, fee-less, bearer-like, and anchored by real commerce.
| Property | Value | Notes |
|---|---|---|
| Role | Elastic circulation currency | Daily payments, merchant settlement, payroll, NFC SmartBills |
| Supply Model | Elastic / policy-driven | No permanent hard cap. Supply expands/contracts via distribution throttling + treasury ops + conversion gravity. |
| Initial Authorized Distribution Program | 10,000,000,000 UBX | “Program ceiling” for early bootstrapping releases. Future authorization requires governance + health metrics. |
| COP Reference | 1 UBX ≈ 1,000 COP | Informational reference only — not a peg or guarantee |
| Tolerance Band | ±20% (ε = 0.20) | 800 ≤ PUBX ≤ 1,200 COP operational band |
| Distribution Model | φ-decay × stability multiplier | Smooth release curve; automatically throttled by price deviation |
| DEX Liquidity | Bootstrap-only rails | Stellar DEX provides early liquidity rails; long-term anchoring comes from merchant pricing + payroll demand |
| Supply Control | Treasury ops + throttling + conversion sink | No per-transaction burns required |
| Design Goal | Circulation, not accumulation | UBX is designed to move; surplus is structurally converted into KNEX |
UBX functions as a digital bearer instrument. Possession equals ownership. No KYC required for peer-to-peer transfers. NFC SmartBills (NTAG 424 DNA) enable physical-to-digital value transfer without internet connectivity at point of sale. The combination of feeless transfers, COP-denominated pricing, and bearer-like portability makes UBX function like digital cash for the Colombian economy.
| Property | Value | Notes |
|---|---|---|
| Role | Fixed-supply reserve asset | Settlement, validator bonding, long-term accumulation |
| Maximum Supply | 100,000,000 KNEX | Absolute hard cap — no inflation possible |
| Deflation | Staking locks + conversion absorption | Validator bonds and UBX→KNEX conversion continuously remove KNEX from active circulation |
| Settlement Finality | Irreversible, on-chain | KNEX transactions represent final settlement |
| Category | Amount | % | Purpose |
|---|---|---|---|
| Network Release Reserve | 90,000,000 | 90% | Validator incentives and long-term network security via PoB |
| Treasury | 7,000,000 | 7% | Ecosystem development, liquidity support, infrastructure |
| Team | 3,000,000 | 3% | Development, operations, long-term maintenance |
| Total (HARD CAP) | 100,000,000 | 100% | Absolute maximum — no additional minting possible |
This distribution prioritizes long-term network operation over insider ownership. 90% is aligned with infrastructure participation. Team and Treasury tokens are subject to time-locked vesting schedules. All reserve accounts are publicly visible on-chain with verifiable balances. No rebase. No post-distribution minting authority.
KNEX is not freely tradable on external markets. Liquidity is utility-driven and ecosystem-based, ensuring that KNEX value derives from protocol participation — not speculation.
| Path | Mechanism | Who |
|---|---|---|
| 1. UBX → KNEX Conversion | Protocol conversion module. UBX is absorbed, KNEX is released at the current epoch rate (K = U / Ee) |
Any UBX holder |
| 2. Validator Rewards | Released from the 90M Network Reserve via PoB. Proportional to Bandwidth Score, subject to 3% cap and geographic multiplier | Active validators |
| 3. Treasury Operations | Ecosystem grants, liquidity seeding, and strategic allocations governed by treasury policy | Treasury (7M pool) |
No dependency on centralized exchange listings. KNEX does not derive value from speculative trading volume. Its worth comes from: (1) validator bond requirements, (2) slashing collateral at risk, (3) conversion gravity absorbing UBX surplus, and (4) governance weight. When demand for KNEX exceeds release rate, scarcity emerges naturally from protocol utility — not artificial restriction.
KNEX market access opens in three phases, each gated by concrete ecosystem health metrics. Premature opening risks speculation bubbles; permanent restriction risks thin liquidity. Graduated liberation balances both.
| Phase | Timeline | Access Level | Trigger Conditions |
|---|---|---|---|
| 1. Bootstrap | Years 0–2 | Protocol conversion + validator rewards + treasury ops + authorized Stellar DEX pools only | Default — active from genesis |
| 2. Maturation | Years 2–4 | Open authorized DEX pools with controlled depth. Community-governed liquidity pools (protocol approval required). No CEX. | Validators >100 AND Merchants >2,000 AND V >3 |
| 3. Liberation | Years 4+ | Remove pool authorization requirement. DEX aggregator integration. CEX becomes protocol-neutral (not endorsed, not blocked). | KNEX price stability >1 year AND Merchants >10,000 AND V ≥4 |
Each phase requires meeting ALL listed trigger conditions before progressing. Regression is possible: if metrics drop below thresholds for >90 consecutive days, the protocol reverts to the previous phase. Governance can override timelines but not trigger conditions.
New UBX distribution follows a time-decay schedule based on the golden ratio. Early epochs distribute more UBX, creating adoption incentives while limiting long-term inflationary pressure.
// Golden ratio decay applied to UBX distribution const φ = 1.6180339887 // Golden ratio // Distribution rate per epoch: Re = R0 / φe // Where: // R0 = base distribution rate // e = epoch number (fixed time intervals) // Re = distribution rate at epoch e // Conversion factor per epoch (UBX per KNEX): Ee = E0 / φe // UBX → KNEX conversion: K = U / Ee // Inverse: U = K · Ee
φ-DECAY RELEASE CURVE
═══════════════════════
Distribution
Rate (R)
│
R₀ │●
│ ╲
│ ╲
R₁ │ ●
│ ╲
│ ╲
R₂ │ ●
│ ╲
R₃ │ ●
│ ╲
R₄ │ ●───●───●───●──▸ (asymptotic)
│
└────────────────────────────▸
e₀ e₁ e₂ e₃ e₄ e₅ Epoch
Each epoch: Re = R0 / φe
Early participants receive higher distribution rates.
Release rate decreases predictably, never reaches zero.
Traditional halving models create sharp supply shocks every N years. φ-decay provides smooth, continuous reduction following the golden ratio — a curve found in natural growth patterns. This eliminates supply cliff events while still rewarding early network participation.
Canonical v5.1 requirement: UBX distribution is implemented as φ-decay multiplied by a stability multiplier (price-band throttling). Any earlier prototypes that used halving-based schedules are deprecated and must be treated as non-canonical.
UBX and KNEX use different release curves, each optimized for its economic role:
RUBX(e) = (R0 / φe) × M(P)RKNEX(t) = 4,500,000/year × NAIdampingAll 100,000,000 KNEX are created at genesis. The 90,000,000 KNEX Network Emission Reserve is locked and released over a 20-year program to fund validators and infrastructure participants via Proof-of-Bandwidth.
This is a release schedule, not inflation. Total supply is fixed from genesis and can never exceed 100,000,000 KNEX.
// All KNEX created at genesis. Reserve is RELEASED, not minted. // Invariant: Released_total ≤ 90,000,000 KNEX // Invariant: Total_supply ≤ 100,000,000 KNEX // Primary release: linear over 20 years Rbase = 90,000,000 / 20 = 4,500,000 KNEX/year // Epoch duration: 1 hour (8,760 epochs/year) // Per-epoch base release: floor(4,500,000 / 8,760) = 513 KNEX // Annual truncation remainder: 4,500,000 − (513 × 8,760) = 6,120 KNEX // Distributed in the final epoch of each year. // NAI counter-cyclical damping (see §04 PoB): Reffective = Rbase × NAIdamping // NAI damping range: 0.25× to 3.0× // Low activity → damping >1 → higher rewards (retain validators) // High activity → damping <1 → lower rewards (prevent overshoot) // NAI adjusts TIMING only, never total supply. // End of program (year 20): // No further issuance occurs. // Undistributed reserve (if any) handled by governance only. // No new minting authority exists.
At every epoch:
released_total ≤ 90,000,000 KNEX (hard cap on reserve release)total_supply ≤ 100,000,000 KNEX (hard cap on total supply)NAI adjusts timing, never total supply.
If the projected reserve depletion date would fall earlier than the canonical narrative horizon, the protocol automatically caps reward acceleration:
NAI_damping is capped at 1.0× until the horizon recovers.This prevents sustained bear-market acceleration from draining the reserve early and breaking the 20-year distribution narrative.
lib.rs) uses MAX_SUPPLY = 100,000,000 with linear release from the 90M Network Release Reserve + NAI counter-cyclical damping + horizon protection. The release.rs module handles schedule computation, horizon_safe_damping(), and validator reward distribution. See the DLT repository for current implementation status.
Proof-of-Bandwidth validators share 4,500,000 KNEX per year released from the Network Emission Reserve, distributed proportionally to bandwidth score. All KNEX was created at genesis — this is a release schedule, not inflation.
Validator rewards are funded from the 90M reserve during the primary program. After the program completes (or governance finalizes any remaining undistributed reserve), validator income transitions to protocol-level revenue sources (e.g., settlement service charges, streaming settlement rails, and other governed network services). No new KNEX minting is permitted.
UBX uses a target range model rather than a fixed peg. The protocol does not guarantee redemption at a fixed COP value. Instead, stability emerges from real economic demand, merchant acceptance, controlled distribution (φ-decay), and structural conversion toward KNEX.
// Target range (not a peg) Ptarget = 1,000 COP ε = 0.20 // 20% acceptable deviation // Tolerance formula: Ptarget(1 − ε) ≤ PUBX ≤ Ptarget(1 + ε) // With ε = 20%: 800 ≤ PUBX ≤ 1,200 COP // Deviation metric: ε = (Pmarket − Ptarget) / Ptarget |ε| < δ // Must stay within acceptable range
The system does not guarantee a fixed peg. Instead, it maintains a managed floating band using automated and treasury-driven mechanisms. Three coordinated levers keep UBX within the operational band.
// Volume-Weighted Average Price from multiple sources PUBX = Σ(Pricei × Volumei) / Σ(Volumei) // Price sources: // 1. Stellar DEX trades (UBX/COP, UBX/USDC pairs) // 2. Merchant pricing data (UBX/COP posted prices) // 3. Payroll conversion rates // 4. Treasury operations // This produces a real-time VWAP that reflects // actual economic activity, not speculative order flow.
| Parameter | Value |
|---|---|
| Ptarget | 1,000 COP |
| Lower Band | 0.8 × Ptarget = 800 COP |
| Upper Band | 1.2 × Ptarget = 1,200 COP |
| Tolerance (ε) | ±20% |
The Treasury maintains continuous liquidity on Stellar DEX with daily intervention limits to prevent reserve depletion.
// When UBX is BELOW the lower band: if PUBX < Lower { // Treasury places buy orders (UBX ← reserve assets) // Removes UBX from circulation → upward price pressure treasury.buy_ubx(amount); } // When UBX is ABOVE the upper band: if PUBX > Upper { // Treasury sells UBX from reserves // Increases circulating supply → downward price pressure treasury.sell_ubx(amount); } // Daily intervention limit (prevents reserve depletion): Maxdaily = α × TreasuryUBX // Where α = 0.5% to 2% (policy parameter) // At α=1%, a 100M UBX treasury can deploy 1M/day max
UBX distribution rate adjusts automatically based on price deviation from target. This creates supply elasticity without manual intervention. Tokens are released from the distribution pool, not minted.
// Price deviation from target: D = (PUBX − Ptarget) / Ptarget // Distribution multiplier: M = 1 + β × D // Where β ≈ 2 (policy sensitivity parameter) // Behavior: // Price LOW (D < 0) → M < 1 → distribution DECREASES // Price HIGH (D > 0) → M > 1 → distribution INCREASES // Floor and ceiling (prevents extreme swings): 0.5 ≤ M ≤ 1.5 // Example: UBX at 900 COP (D = -0.10) // M = 1 + 2(-0.10) = 0.80 → distribution cut 20% // Example: UBX at 1,100 COP (D = +0.10) // M = 1 + 2(+0.10) = 1.20 → distribution up 20%
When UBX is weak, the conversion mechanism absorbs excess supply. Users convert UBX into KNEX — UBX is locked, KNEX released from reserve pool. This is the economic gravity engine.
// UBX → KNEX conversion KNEXout = (UBXin × PUBX) / PKNEX // Effect: excess UBX flows into scarce KNEX // → UBX circulating supply decreases // → KNEX demand increases // → Both layers stabilize
Merchants display dual pricing: COP price and UBX equivalent. This creates a real-economy feedback loop that anchors UBX to tangible goods and services.
// Merchants display both COP and UBX prices UBXprice = COPprice / PUBX // Example: Coffee = 5,000 COP // At P_UBX = 1,000 COP → 5.0 UBX // At P_UBX = 900 COP → 5.6 UBX (merchant adjusts) // At P_UBX = 1,100 COP → 4.5 UBX // This creates price feedback: // UBX drops → merchants adjust → demand increases → price stabilizes
Employer payroll creates predictable, recurring baseline demand for UBX independent of speculative activity.
// Employee receives partial salary in UBX SalaryCOP = total COP salary r = UBX allocation (3% to 30%) UBXissued = (SalaryCOP × r) / PUBX // Example: 3,000,000 COP salary, r = 10% // UBX_issued = (3,000,000 × 0.10) / 1,000 = 300 UBX // At 1,000 employees: 300,000 UBX/month recurring demand // This is non-speculative, productivity-backed demand
| Condition | Action |
|---|---|
| Price within band (800-1,200 COP) | No intervention |
| Price near lower band (~800-850 COP) | Reduce distribution (Lever 2) |
| Price below band (<800 COP) | Treasury buys + conversion encouraged (Levers 1+3) |
| Price near upper band (~1,150-1,200 COP) | Increase distribution (Lever 2) |
| Price above band (>1,200 COP) | Treasury sells UBX from reserves (Lever 1) |
Over time, the system stabilizes through five reinforcing mechanisms: (1) continuous payroll demand, (2) merchant pricing anchors, (3) treasury market depth on DEX, (4) UBX→KNEX gravity conversion, and (5) controlled distribution elasticity. This avoids hard pegs, algorithmic death spirals, and purely speculative price discovery. Stellar DEX is a bootstrap market mechanism, not the economic source of truth.
The system creates a one-directional economic flow from high-velocity circulation (UBX) toward low-velocity reserves (KNEX). This structural dynamic is the engine that sustains both layers.
ECONOMIC GRAVITY: DIRECTIONAL VALUE FLOW
═════════════════════════════════════════
┌─────────────────────────────────────────────────────┐
│ REAL ECONOMY │
│ Merchants ● Payroll ● Services ● Retail │
└──────────────────────┬──────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────┐
│ UBX CIRCULATION │
│ High velocity ● Bearer-like ● ~1,000 COP │
│ Daily payments, NFC SmartBills, P2P transfers │
└──────────────────────┬──────────────────────────────┘
│
Operational Surplus
│
▼
┌─────────────────────────────────────────────────────┐
│ DEX CONVERSION │
│ Merchant treasury converts excess UBX → KNEX │
│ K = U / Ee (conversion rate decays with φ) │
└──────────────────────┬──────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────┐
│ KNEX ACCUMULATION │
│ Low velocity ● Fixed supply ● Settlement │
│ Validator bonds, reserves, deflation via locks │
└─────────────────────────────────────────────────────┘
Flow direction: UBX circulation → surplus → DEX → KNEX
Value flows from high-velocity to low-velocity over time.
// Merchant conversion variables P = UBX revenue received by merchant O = UBX retained for operations S = surplus converted to KNEX // Surplus calculation: S = P − O // KNEX acquired: Kacquired = S / Ee // Aggregate economic gravity: // As more merchants convert surplus → KNEX: // - UBX circulating supply stabilizes // - KNEX liquid supply decreases // - d(KNEX_accumulated)/dt > 0 → increasing scarcity
The dual-layer system must be continuously monitored against quantitative thresholds. These metrics determine whether the economic engine is functioning as designed.
| Metric | Formula | Healthy | Critical |
|---|---|---|---|
| Monetary Velocity (V) | V = T / M | V ≥ 2 (2-4x/month target) | V < 2 → stagnation |
| Conversion Flow (C) | C = Σ(UBX→KNEX) per period | C > 0 (positive flow) | C → 0 → gravity collapse |
| DEX Buy Liquidity (L) | Lbuy = total buy-side depth | Lbuy ≥ 3 × Voldaily | Lbuy < Voldaily → thin market |
| COP Deviation (ε) | ε = (Pmarket − Ptarget) / Ptarget | |ε| ≤ 0.20 | |ε| > 0.30 → anchor breach |
| Ecosystem Stability Index | ESI = f(V, C, L, ε) | ESI > 3 | ESI < 1 → overdistribution |
// Monetary velocity (UBX must circulate, not accumulate) V = T / M // T = total UBX transaction volume in period // M = UBX in active circulation // V ≥ 2 → healthy system (UBX is being used) // V < 2 → WARNING: velocity collapse risk // KNEX accumulation rate (must be positive for gravity) d(KNEXaccumulated) / dt > 0 // If accumulation rate is positive: // → liquid KNEX supply decreases // → relative economic value increases // → economic gravity is functioning // Equilibrium condition D ≥ RUBX // Demand ≥ Distribution → price stability RUBX > D // Distribution > Demand → downward pressure
The single greatest threat to this system is a liquidity death spiral. If UBX→KNEX conversion (C) approaches zero AND UBX velocity (V) drops below 2 simultaneously, the following cascade occurs:
The following mechanisms are designed to detect and halt the death spiral before it reaches critical cascade.
| Trigger | Condition | Response |
|---|---|---|
| Velocity Alert | V < 2 for > 7 days | Increase UBX distribution incentives, merchant onboarding push |
| Conversion Halt | C = 0 for > 14 days | Treasury provides bridge liquidity on DEX buy side |
| Anchor Breach | |ε| > 0.30 | Treasury intervention: sell KNEX reserves for UBX buy pressure |
| Liquidity Crisis | Lbuy < Voldaily | Emergency treasury injection into DEX order book |
Failure is not theoretical. These are the concrete failure modes that the protocol team must monitor and defend against:
| Asset | Supply Behavior | Role |
|---|---|---|
| UBX | Elastic / expanding | Circulation and liquidity |
| KNEX | Fixed / scarce (100M cap) | Reserve and settlement |
| Conversion | Directional (UBX → KNEX) | Economic gravity engine |
| Distribution | φ-Decay by epochs | Bootstrapping with natural decay |
The complementary dynamics — elastic circulation against fixed reserves — create a self-reinforcing monetary system where increased economic activity in UBX structurally benefits KNEX holders through conversion gravity.
Inspired by Nano's block-lattice architecture. Each account has its own chain (account-chain) in the DAG. Transactions only touch the sender and receiver chains.
pub struct Block { // Block identification hash: [u8; 32], // Blake2b hash of block previous: [u8; 32], // Previous block in account-chain // Account info account: [u8; 32], // Account public key representative: [u8; 32], // Voting representative balance: u128, // Account balance after block // Dual-token support (L1) token_type: TokenType, // UBX | KNEX — first-class on L1 // Block type specific block_type: BlockType, // Send | Receive | Change | Bandwidth | StreamOpen | StreamSettle | StreamClose link: [u8; 32], // Destination, source block hash, or stream session ID // Proof-of-Bandwidth (KnexCoin specific) bandwidth_proof: Option<BandwidthProof>, // Streaming payment data (optional — only for StreamOpen/Settle/Close) stream_data: Option<StreamData>, // Signature & anti-spam signature: [u8; 64], // Ed25519 signature work: u64, // Client-side anti-spam PoW (Nano model, NOT a fee) } pub enum TokenType { UBX, // Elastic transactional layer (~1,000 COP) KNEX, // Fixed-supply reserve layer (100M cap) } // Stream block types for off-chain payment channels // StreamOpen: Locks funds, creates session (sender's chain) // StreamSettle: Batch settlement of off-chain vouchers (receiver's chain) // StreamClose: Final settlement + reclaim remaining (sender's chain)
On the native L1 DAG, both UBX and KNEX are first-class token types. Each block explicitly declares its token type. An account can hold balances in both tokens simultaneously (separate balance fields or separate account-chains per token type). During the Stellar phase, this distinction is handled by Stellar asset codes; on L1, it becomes a native protocol field.
The work: u64 field is a lightweight client-side computation (Nano model) that prevents network spam. It is not a transaction fee — no value is transferred to validators or burned. "Feeless" means zero value transfer for transaction processing. The PoW is computed by the sending wallet before broadcast and verified by nodes on receipt. Difficulty adjusts based on account activity frequency.
BLOCK-LATTICE STRUCTURE (UBX Example)
══════════════════════════════════════
Alice's Chain Bob's Chain Carol's Chain
──────────── ─────────── ─────────────
│ │ │
┌────┴────┐ │ │
│ GENESIS │ │ │
│ 1000 UBX│ │ │
└────┬────┘ │ │
│ ┌────┴────┐ │
│ │ GENESIS │ │
│ │ 500 UBX │ │
│ └────┬────┘ │
┌────┴────┐ │ │
│ SEND │────────────────┼──────────────┐ │
│ -100 UBX│ │ │ │
│ 900 UBX │ │ ▼ │
└────┬────┘ │ ┌────┴────┐ │
│ │ │ RECEIVE │ │
│ │ │ +100 UBX│ │
│ │ │ 100 UBX │ │
│ │ └────┬────┘ │
│ ┌────┴────┐ │ │
│ │ SEND │─────────┼───────┼──▶ Pending
│ │ -50 UBX │ │ │
│ │ 450 UBX │ │ │
│ └────┬────┘ │ │
▼ ▼ ▼ ▼
Same structure applies to KNEX blocks (token_type = KNEX).
Each account can maintain parallel chains for each token type.
Bandwidth is difficult to prove trustlessly. Unlike PoW (verifiable computation) or PoS (verifiable stake), bandwidth proofs can be spoofed, colocated, or gamed. Our solution uses multiple verification vectors.
pub struct BandwidthProof { // Challenge data challenge_hash: [u8; 32], // Hash of random challenge data challenge_size: u64, // Size of data transferred (bytes) timestamp_start: u64, // Challenge initiated (ms) timestamp_end: u64, // Challenge completed (ms) // Verification challenger_nodes: Vec<[u8; 32]>, // Nodes that issued challenge attestations: Vec<Attestation>, // Peer confirmations // Computed metrics measured_bandwidth: u64, // Calculated Mbps latency_avg: u32, // Average latency (ms) // VDF commitment (prevents pre-computation) vdf_output: [u8; 32], vdf_proof: [u8; 64], } pub struct Attestation { attester: [u8; 32], // Attesting node pubkey observed_bandwidth: u64, // Their measurement confidence: u8, // 0-100 confidence score signature: [u8; 64], }
Validators earn a Bandwidth Score (BS) that determines their voting weight and rewards eligibility. All component metrics are normalized to [0, 1] before weighting to prevent any single factor from dominating.
// Bandwidth Score (BS) — all components normalized to [0, 1] // Step 1: Normalize each metric BW_norm = min(BW_measured / BW_cap, 1.0) // Cap: 10 Gbps Lat_norm = max(1.0 − (Latency / Lat_max), 0.0) // Max: 500ms Up_norm = Uptime / 100.0 // Already 0-100% Rep_norm = min(AttestScore / Rep_cap, 1.0) // Cap: max rep // Step 2: Weighted sum BS = (BW_norm × 0.40) + // 40% throughput (Lat_norm × 0.25) + // 25% latency (Up_norm × 0.20) + // 20% uptime (rolling 30 days) (Rep_norm × 0.15) // 15% peer reputation // Result: BS ∈ [0.0, 1.0] // Weights tunable via governance after Phase 3 // Caps prevent diminishing-return gaming: BW_cap = 10_000 // 10 Gbps — beyond this, no extra weight Lat_max = 500 // 500ms — above this, latency score = 0 Rep_cap = 1000 // Maximum peer attestation score
Challenge-response proofs require unbiased challenger selection. A Verifiable Random Function (VRF) ensures challengers are unpredictable and cannot be bribed or colocated in advance.
The full VDF commitment system (shown in the BandwidthProof struct) is deferred for v1. Initial implementation uses challenge-response with VRF-selected challengers only. VDF integration is planned for v2 when hardware-accelerated VDF libraries mature. The struct retains the VDF fields as reserved/optional.
| Parameter | v1 (Launch) | Target (Maturity) |
|---|---|---|
| Minimum challenger regions | 3 | 5 |
| Proof window | 60 seconds | 30 seconds |
| Challenge data size | 1-10 MB random | 1-50 MB adaptive |
| Minimum validators | 21 | 100+ |
| Geographic diversity | 3 countries min | 5+ regions, 10+ countries |
Bandwidth proofs are validated against anomaly thresholds to detect spoofing, proxy attacks, and colocation.
| Anomaly | Detection | Threshold | Action |
|---|---|---|---|
| Latency inconsistency | Triangulation mismatch > 2σ | > 2× standard deviation from expected RTT | Flag proof, require re-challenge |
| Bandwidth spike | Sudden >5× increase vs rolling average | 500% of 7-day rolling mean | Cap at rolling average, investigate |
| Attestation collusion | Same attesters repeatedly paired | > 3 consecutive pairings | Rotate challengers, flag both parties |
| Geographic impossibility | Claimed location vs latency mismatch | Latency < speed-of-light minimum for distance | Reject proof, slash reputation |
v1 uses threshold-based detection. ML-based anomaly detection (neural network models for bandwidth pattern analysis) is deferred to v2.
// Reputation decays toward baseline without fresh evidence Rept = Rept-1 × λ + evidence // Where: // λ = decay factor (0.95 — 5% decay per period) // evidence = new attestation score from latest proof window // Rept = reputation at time t // A validator that stops proving bandwidth sees reputation // decay exponentially toward zero. No free riding on past proofs. // Minimum reputation threshold for consensus participation: Repmin = 100 // Below this → excluded from voting
Proof-of-Bandwidth validators share 4,500,000 KNEX per year from the 90M Network Release Reserve (20-year program). Rewards are distributed proportionally to Bandwidth Score:
// Annual release from Network Reserve (not minted — unlocked) Rannual = 4,500,000 KNEX // Reward for validator i in period p: Rewardi = Rperiod × (BSi / ΣBSall) // Where: // Rperiod = KNEX released in this period (daily/weekly) // BSi = Bandwidth Score of validator i // ΣBSall = Sum of all active validator scores // Anti-centralization: max 3% of period rewards per validator // MaxRewardi = Rperiod × 0.03 // Geographic diversity multiplier: // GeoMuli = 1.0 + γ × (1 − RegionDensityi) // γ = 0.15 (diversity bonus coefficient) // RegionDensity = validators_in_region / total_validators // Validators in underrepresented regions earn up to 15% bonus // Validators in overrepresented regions receive no penalty (floor = 1.0) // Final reward with anti-centralization + geographic diversity: // Rewardi = min(MaxRewardi, Rperiod × (BSi × GeoMuli) / Σ(BSj × GeoMulj)) // Example: 100 validators, equal BS // Rewardi = 4,500,000 / 100 = 45,000 KNEX/year each // Validator in rare region (5% density): GeoMul = 1.0 + 0.15 × 0.95 ≈ 1.14 // Validator in common region (30% density): GeoMul = 1.0 + 0.15 × 0.70 ≈ 1.11
Three mechanisms prevent reward concentration and geographic monoculture:
γ = 0.15). This incentivizes geographic spread without penalizing existing operators.The NAI adjusts validator rewards based on real network activity, preventing reward gaming during low-activity periods and providing higher incentives when the network is under-utilized. This is a counter-cyclical mechanism: rewards increase when activity drops (incentivizing validators to stay) and decrease when activity spikes (preventing inflationary overshoot).
| Input | Weight | Source |
|---|---|---|
| Transaction Volume | 40% | Total UBX + KNEX transaction volume in RAW |
| Active Accounts | 20% | Unique accounts with ≥1 transaction in the epoch |
| Active Validators | 10% | Validators that submitted PoB proofs in the epoch |
| DEX Volume | 30% | Volume between D-prefix DEX accounts (Stellar bootstrap + L1 pools) |
// NAI computes a damping multiplier applied to base validator rewards // Range: 0.25× (high activity) to 3.0× (low activity) NAIdamping = clamp(target_activity / current_activity, 0.25, 3.0) // Where: // target_activity = rolling average of NAI score over 90-day window // current_activity = NAI score for current epoch (1 hour) // Effective validator reward: Rewardeffective = Rewardbase × NAIdamping // Counter-cyclical behavior: // Network busy → damping < 1.0 → rewards decrease (prevent overshoot) // Network quiet → damping > 1.0 → rewards increase (retain validators) // Network dead → damping = 3.0 → maximum incentive to bootstrap // NAI bootstrap: first 7 days (168 epochs) use damping = 1.0 // Rolling window: 90 days (2,160 epochs) for target calculation // Parameters tunable only via governance process
Any account whose Base62-encoded address starts with D is flagged as a DEX account. Transactions between two D-accounts count as DEX volume in the NAI calculation. This allows the protocol to measure on-chain DEX activity without requiring a separate oracle. On L1, D-prefix accounts host authorized liquidity pools; on Stellar, they map to the existing order book infrastructure.
Adapted from Nano's ORV consensus. Voting weight is determined primarily by Bandwidth Score. Stake functions as a bond threshold with ramp-up, not a weight multiplier.
The previous model (sqrt(Stake) × BS) still gave whales disproportionate power: 100× more stake = 10× more base weight before bandwidth. The new formula uses a bond threshold with linear ramp-up — below 10,000 KNEX you get proportional eligibility, at or above 10,000 KNEX you are fully eligible, but additional KNEX gives zero extra weight. Beyond the threshold, only bandwidth determines weight. A validator with 10,000 KNEX and excellent infrastructure has identical weight to one with 1,000,000 KNEX and the same infrastructure. Capital cannot buy consensus influence — only real infrastructure contribution matters.
// NEW: Bandwidth-primary, stake is bond threshold with ramp-up VotingWeight = BandwidthScore × min(1, Stake / MIN_STAKE) // Where: // BandwidthScore = BS ∈ [0.0, 1.0] (from Section 04) // Stake = KNEX bonded by validator // MIN_STAKE = 10,000 KNEX // The min(1, Stake/MIN_STAKE) term: // Stake < 10,000 → factor = Stake/10,000 (partial, ramping) // Stake ≥ 10,000 → factor = 1.0 (fully eligible) // Stake = 1,000,000 → factor = 1.0 (no extra weight) // RESULT: Only bandwidth determines consensus influence.
const MIN_STAKE: u128 = 10_000 * KNEX_RAW; // 10,000 KNEX in raw units fn calculate_voting_weight(validator: &Validator) -> f64 { // Bond threshold with ramp-up: 0.0 to 1.0 let stake_factor = (validator.staked_amount as f64 / MIN_STAKE as f64) .min(1.0); // Bandwidth score is the real weight (0.0 to 1.0) let bandwidth_score = validator.bandwidth_score; // Weight = bandwidth × eligibility bandwidth_score * stake_factor } // Examples: // Validator A: 10,000 KNEX, BS=0.85 → 0.85 × 1.0 = 0.85 // Validator B: 1,000,000 KNEX, BS=0.85 → 0.85 × 1.0 = 0.85 // ↳ 100× more KNEX gives ZERO extra weight // Validator C: 10,000 KNEX, BS=0.40 → 0.40 × 1.0 = 0.40 // ↳ Less infrastructure = less influence (as intended) // Validator D: 5,000 KNEX, BS=0.90 → 0.90 × 0.5 = 0.45 // ↳ Below min stake = reduced eligibility
CONSENSUS FLOW (ORV + PoB)
══════════════════════════
1. BROADCAST 2. VOTE 3. CONFIRM
─────────── ────── ─────────
┌─────────┐ ┌───────────────┐ ┌──────────┐
│ User │ │ Representatives│ │ Quorum │
│ creates │─────▶│ receive & vote │─────▶│ reached │
│ block │ │(bandwidth-wtd)│ │ (67%) │
└─────────┘ └───────────────┘ └──────────┘
│ │ │
│ ┌───────┴───────┐ │
│ │ │ │
│ ┌───┴───┐ ┌───┴───┐ │
│ │Rep A │ │Rep B │ │
│ │BS:0.85│ │BS:0.72│ │
│ │Vote:✓ │ │Vote:✓ │ ▼
│ └───────┘ └───────┘ ┌─────────┐
│ │CONFIRMED│
│ ┌───────┐ ┌───────┐ │ <1 sec │
│ │Rep C │ │Rep D │ └─────────┘
│ │BS:0.60│ │BS:0.91│
│ │Vote:✓ │ │Vote:✗ │
│ └───────┘ └───────┘
│
Weight = BandwidthScore × min(1, Stake / MIN_STAKE)
Quorum = 67% of total online voting weight
| Parameter | Value | Notes |
|---|---|---|
| Quorum threshold | 67% (2/3 + 1) | Of total online voting weight |
| Minimum stake | 10,000 KNEX | Bond threshold with linear ramp-up |
| Delegation | Supported | Users delegate to representatives via Change blocks |
| Confirmation target | <1 second (L1) | 3-5 seconds during Stellar phase |
| Fork resolution | Heaviest-weight branch | Branch with most bandwidth-weighted votes wins |
| Slashing | KNEX bond at risk | Double-voting or provably malicious behavior |
In this design, KNEX stake serves three purposes: (1) Sybil resistance — creating a validator costs 10,000 KNEX, making mass-creation expensive; (2) Slashing collateral — malicious validators lose their bond; (3) Alignment — validators have economic skin in the game. What stake does not do: determine voting power, earn proportional rewards, or create governance influence. Infrastructure contribution is the only path to consensus weight.
Both UBX and KNEX use the same asynchronous two-phase transaction model. The token_type field in each block determines which layer the transaction operates on.
The primary transaction flow. UBX payments between merchants, consumers, and payroll systems. Feeless, sub-second, NFC-compatible.
| Step | Action | Time (L1) | Time (Stellar) | State |
|---|---|---|---|---|
| 1 | Customer taps NFC SmartBill or opens wallet | ~0ms | ~0ms | Intent created |
| 2 | UBX SEND block created (token_type: UBX) | ~0ms | N/A (Stellar tx) | Block signed locally |
| 3 | Block broadcast / Stellar submit | ~50ms | ~500ms | Propagating |
| 4 | ORV quorum (67%) / Stellar consensus | ~200-500ms | ~3-5s | SEND confirmed |
| 5 | Merchant RECEIVE block created | ~0ms | Automatic | Balance credited |
| 6 | RECEIVE confirmed | ~200-500ms | Included in step 4 | Payment complete |
Full UBX transaction confirmation with zero fees. On L1: sub-second via ORV with bandwidth-weighted voting. During Stellar phase: 3-5 seconds via Stellar consensus. Both paths are suitable for point-of-sale use. NFC SmartBills (NTAG 424 DNA) enable tap-to-pay at physical locations.
The secondary flow. Merchants converting UBX surplus to KNEX via DEX, validator bond deposits, and high-value settlement transfers.
| Step | Action | Time | State |
|---|---|---|---|
| 1 | Merchant identifies UBX surplus (P − O = S) | Business logic | Surplus calculated |
| 2 | UBX sell order placed on DEX (UBX/KNEX pair) | ~1-3s | Order submitted |
| 3 | DEX matches order (K = S / Ee) | ~3-5s (Stellar) | Conversion executed |
| 4 | KNEX credited to merchant wallet | ~3-5s (Stellar) | Settlement complete |
| 5 | KNEX optionally locked in treasury/staking | Varies | Long-term reserve |
DUAL-TOKEN TRANSACTION FLOWS
════════════════════════════
FLOW 1: UBX DAILY PAYMENT (feeless, sub-second)
─────────────────────────────────────────────────
Consumer Merchant
┌──────────┐ ┌──────────┐
│ Wallet │── UBX SEND ────────▶│ Wallet │
│ (NFC/ │ token: UBX │ (POS / │
│ App) │ fee: 0 │ App) │
└──────────┘ └──────────┘
│ ORV │
└──── <1s confirmation ───────────┘
FLOW 2: KNEX SETTLEMENT (DEX conversion)
─────────────────────────────────────────
Merchant DEX Reserve
┌──────────┐ ┌────────────┐ ┌──────────┐
│ UBX │── Sell ▶│ UBX/KNEX │── Buy ─▶│ KNEX │
│ Surplus │ │ Order Book│ │ Treasury│
└──────────┘ └────────────┘ └──────────┘
│ │ │
└──── Economic Gravity (directional) ────────┘
| Network | Confirmation | Fees | Finality |
|---|---|---|---|
| KnexCoin L1 (UBX) | <1 second | Zero | Immediate (ORV quorum) |
| KnexCoin Stellar (UBX) | 3-5 seconds | ~0.00001 XLM | Immediate (SCP) |
| Nano | <1 second | Zero | Immediate (ORV) |
| Solana | ~400ms | ~$0.00025 | Probabilistic |
| Ethereum | ~12 seconds | $0.50-50+ | ~15 minutes |
| Bitcoin | ~10 minutes | $1-50+ | ~60 minutes |
UBX supports continuous, per-second payment streams via off-chain signed vouchers with periodic on-chain settlement. This enables payroll drip, bandwidth metering, service billing, and micro-commerce without chain spam.
| Token | Streamable? | Use Cases | Rationale |
|---|---|---|---|
| UBX | ✓ Yes | Payroll drip, service metering, bandwidth payments, micro-commerce | High-velocity layer designed for continuous flow |
| KNEX (retail) | ✗ No | — | Low velocity reserve asset; should not be continuously spent by retail users |
| KNEX (protocol) | ✓ Yes | Validator rewards, treasury vesting, protocol distributions | Controlled release from reserves needs continuous scheduling |
struct StreamSession { session_id: Hash, // Unique channel ID (Blake2b of params) sender: PublicKey, // Payer receiver: PublicKey, // Payee token_type: TokenType, // UBX (retail) or KNEX (protocol-only) rate_raw_per_second: u128, // Continuous payment rate in RAW max_total_raw: u128, // Spending cap for this session settled_raw: u128, // Cumulative on-chain settlements expiration: u64, // Unix timestamp auto-close created_at: u64, // Session start time } // Precision: 1.0000000 = 10,000,000 RAW (7 decimal places) // Example: Payroll stream of 400 UBX/month // rate = (400 × 10,000,000) / (30 × 86,400) = 1,543 RAW/second // max_total = 400 × 10,000,000 = 4,000,000,000 RAW // Rounding: all RAW calculations truncate toward zero (floor division) // No fractional RAW exists. Remainder stays with sender on StreamClose // Min settlement amount: 1,000 RAW (0.0001000 tokens) — prevents dust // Min settle interval: 60 seconds per session (anti-spam)
// Sender signs cumulative vouchers off-chain struct Voucher { session_id: Hash, cumulative_amount: u128, // Total owed (grows over time) sequence: u64, // Monotonically increasing signature: Signature, // Sender signs (cumulative, not delta) } // Receiver holds the LATEST voucher as proof of payment // Only the most recent voucher matters (cumulative design) // Settlement triggers (any one triggers on-chain block): // 1. Time interval: every N minutes (default 5 min) // 2. Amount threshold: unsettled exceeds X RAW // 3. Session close: final settlement on expiry or manual close // 4. Dispute: receiver submits voucher if sender goes offline // Dispute resolution: // If sender goes offline, receiver submits latest voucher // to create a StreamSettle block (unilateral close) // Sender's locked funds up to voucher.cumulative_amount // are transferred. Remainder returns to sender after grace period. // Grace period: 24 hours from session expiration // After grace: receiver can claim, sender can reclaim unclaimed // On-chain footprint: ONE StreamSettle block per settlement // NOT one block per micro-payment — anti-spam by design
| Parameter | Value | Purpose |
|---|---|---|
| Min settlement interval | 60 seconds per session | Prevents rapid-fire on-chain blocks |
| Max concurrent sessions | 100 per account | Prevents account-level spam |
| Voucher expiry | Session expiration + 24h grace | Receiver can always claim owed funds |
| KNEX streaming guard | Protocol-only (validator/treasury) | Retail KNEX streams are rejected at validation |
rate = monthly_salary / (30 × 86,400). Settles hourly on-chain. Employee can spend accrued UBX in real-time
STREAMING PAYMENT FLOW
═══════════════════════
Sender Receiver
┌──────────────┐ ┌──────────────┐
│ StreamOpen │── on-chain ──▶ │ Session │
│ (lock funds) │ │ Registered │
└──────┬───────┘ └──────┬───────┘
│ │
│ ┌─────────────────────────┐ │
│ │ OFF-CHAIN VOUCHERS │ │
├─▶│ v1: 1,543 RAW │──┤
├─▶│ v2: 3,086 RAW │──┤
├─▶│ v3: 4,629 RAW ... │──┤
│ └─────────────────────────┘ │
│ │
┌──────┴───────┐ ┌──────┴───────┐
│ │ │ StreamSettle │
│ │◀── on-chain ──│ (batch claim)│
└──────┬───────┘ └──────┬───────┘
│ │
┌──────┴───────┐ ┌──────┴───────┐
│ StreamClose │── on-chain ──▶ │ Final Settle │
│ (reclaim │ │ (claim │
│ remainder) │ │ remaining) │
└──────────────┘ └──────────────┘
UBX launches as a local payment rail in Colombia before expanding regionally. Price stability, merchant density, and payroll integration are achieved in a single market first — proving the economic model with real transaction volume before geographic expansion.
| Phase | Name | Merchants | Users | Volume (USD/mo) | Target |
|---|---|---|---|---|---|
| 1 | Pilot Local | 50–100 | 1,000–5,000 | $50K–$200K | Single city (Cali), prove unit economics |
| 2 | Service Sector | 500–2,000 | 10,000–50,000 | $500K–$2M | 3–5 cities (Bogotá, Medellín, Cali, Barranquilla) |
| 3 | Enterprise Integration | 2,000+ | 50,000–300,000 | $2M–$10M | Payroll API, corporate treasury, SME onboarding |
| 4 | Regional Network | 5,000+ | 300,000–1,000,000 | $10M+ | National merchant directory, inter-city payment corridors |
| 5 | International Settlement | 10,000+ | 1,000,000+ | $50M+ | Remittance corridors, LATAM expansion, KNEX as settlement layer |
ADOPTION FLYWHEEL
═══════════════════
┌──────────────┐ ┌──────────────┐
│ Merchant │────────▶│ Consumer │
│ Accepts │ │ Pays UBX │
│ UBX │ │ │
└──────┬───────┘ └──────┬───────┘
│ │
▼ ▼
┌──────────────┐ ┌──────────────┐
│ Payroll │◀────────│ Velocity │
│ Integration │ │ Increases │
│ (COP→UBX) │ │ (V ≥ 2) │
└──────┬───────┘ └──────┬───────┘
│ │
▼ ▼
┌──────────────┐ ┌──────────────┐
│ Surplus │────────▶│ KNEX │
│ UBX Flow │ │ Conversion │
│ │ │ Gravity │
└──────────────┘ └──────────────┘
Merchants accept UBX → Consumers spend UBX → Velocity rises →
Payroll creates recurring demand → Surplus flows to KNEX →
More merchants attracted by network density → Flywheel accelerates
KnexCoin deploys NFC-enabled physical cards and SmartBills for frictionless in-store payments without requiring advanced smartphones.
| Feature | Specification | Purpose |
|---|---|---|
| Chip | NXP NTAG 424 DNA | Cryptographic authentication hardware |
| Authentication | SUN (Signature Universal Naming) | Dynamic signature per tap — prevents cloning |
| Anti-Cloning | Dynamic counter + CMAC verification | Each tap generates a unique response |
| Wallet Binding | Card ↔ Wallet address link | Physical card triggers wallet-level transactions |
| Form Factor | Card / SmartBill / sticker | Multiple deployment formats for merchant needs |
NFC deployment begins in Phase 1 with pilot merchants. Regional-scale card distribution starts in Phase 2. Each card is provisioned via the KnexCard system at nfc.serial.cash/auth/.
Employers integrate via the Payroll API, allowing employees to receive a configurable percentage of their salary in UBX. This creates recurring, predictable demand that anchors UBX velocity.
// Company → Payroll API → Split payout // Employee configures UBX percentage (r = 3% to 30%) UBXpayout = (SalaryCOP × r) / PUBX COPpayout = SalaryCOP × (1 - r) // Example: 4,000,000 COP salary, r = 10%, P_UBX = 1,000 COP // UBX payout = (4,000,000 × 0.10) / 1,000 = 400 UBX // COP payout = 4,000,000 × 0.90 = 3,600,000 COP (to bank) // Payroll creates: // - Recurring UBX demand (buy pressure at each pay cycle) // - Velocity floor (employees spend UBX at merchants) // - Natural COP anchor reinforcement
UBX percentage is fully employee-configurable with no minimum mandate. Integration with existing accounting systems (SAP, Siigo) planned for Phase 3. Corporate treasury can also hold KNEX as a reserve asset. Streaming mode: Payroll can use the streaming payment channel (see §06) for per-second UBX drip — employees accrue UBX in real time and can spend it before the pay period ends.
Colombia receives $9B+ in annual remittances, primarily from the United States. UBX/KNEX provides a settlement rail with sub-5-second finality and less than 0.1% transaction cost.
| Corridor | Volume Estimate | Infrastructure |
|---|---|---|
| Colombia ↔ USA | $9B+/year (primary) | Stellar + local on-ramps |
| Colombia ↔ Spain | Remittances + commerce | Stellar + EU partners |
| LATAM Regional | Bilateral trade | Regional node networks |
| Colombia ↔ Asia | Imports | Stellar cross-border settlement |
| Route | Monthly Volume | Use Case |
|---|---|---|
| Bogotá ↔ Medellín | $1M–$5M | Inter-city commerce |
| Bogotá ↔ Cali | $500K–$3M | Supply chain payments |
| Venezuela Border | $200K–$1M | Remittances + commerce |
| Ecuador Border | $100K–$500K | Bilateral trade |
| Metric | Target | Why It Matters |
|---|---|---|
| WAU (Weekly Active Users) | >500 | Minimum network activity for meaningful data |
| UBX Velocity (V) | 2–4× rotations/month | Below 2 = stagnation risk, above 4 = healthy commerce |
| 3-Month Retention | >50% | Users must stay for flywheel to work |
| UBX→KNEX Conversion | >20% of merchants | Proves KNEX gravity is active |
| NPS (Merchant) | >40 | Merchant satisfaction drives word-of-mouth |
| Settlement Time | <3 seconds | Must match or beat card network UX |
| Year | Milestone | Users | Key Deliverable |
|---|---|---|---|
| 2026 | Launch & Validation | 1K–5K | Mainnet activation, pilot in Cali, 20–50 merchants |
| 2027 | Local Expansion | 20K–50K | Multiple urban zones, NFC card deployment at regional scale |
| 2028 | Enterprise Integration | 100K–300K | SME integration, payroll API live, KNEX corporate treasury |
| 2029 | National Network | 1M+ | Multiple major cities, national merchant directory |
| 2030 | International Expansion | 3M+ | Remittance corridors, 3+ LATAM countries, KNEX settlement layer |
Minimum 6 months of stable Colombian operation required before international expansion. Each market requires a local partner for regulatory compliance.
Security spans both token layers: UBX supply integrity (distribution accuracy, conversion rate manipulation, COP anchor defense), KNEX lockup enforcement (validator bonds, slashing execution, reserve accounting), and conversion manipulation prevention (rate oracle attacks, front-running, sandwich attacks on the conversion module).
All slashing penalties are denominated in KNEX from the validator’s bonded collateral. This ensures economic consequences are tied to the settlement layer, not the transactional layer.
| Violation | Penalty | Detection | Recovery |
|---|---|---|---|
| Double voting | 100% of bond (10,000 KNEX) | Cryptographic proof (conflicting signatures) | None — permanent ban from validator set |
| Bandwidth spoofing | 100% of bond | PoB cross-validation, latency triangulation | None |
| Attestation collusion | 75% of bond (7,500 KNEX) | Statistical analysis, repeated pairing detection | Re-bond after cooldown (90 days) |
| Attestation fraud | 50% of bond (5,000 KNEX) | Challenge-response verification failure | Re-bond after cooldown (30 days) |
| Extended downtime | 5% of bond per week | Missing PoB proofs for >48 hours | Resume proofs to stop penalty |
| Stale proofs | Reputation decay (no KNEX slash) | Proof age exceeds freshness window | Submit fresh PoB proofs |
Slashed KNEX is burned (removed from circulating supply), not redistributed. This makes slashing deflationary, reinforcing KNEX scarcity. The Stellar bootstrap phase uses reputation-based penalties only; full KNEX slashing activates on L1 mainnet.
Full security hardening details — including cryptographic primitives, network security, consensus safety, economic security, quantum resistance, and formal verification — are specified in the comprehensive security section below (see implementation phases and detailed protocol review).
| Layer | Domain | Key Measures |
|---|---|---|
| 1 | Cryptographic | Ed25519 signatures, Blake2b hashing, deterministic key derivation |
| 2 | Network | Peer authentication, encrypted transport (Noise protocol), eclipse resistance |
| 3 | Consensus | ORV quorum (67%), bandwidth-weighted voting, fork resolution |
| 4 | Economic | KNEX bond slashing, PoB spoofing detection, conversion rate integrity |
| 5 | Quantum | FALCON-512 post-quantum migration path, hybrid signature scheme |
| 6 | Operational | Rate limiting, DoS mitigation, client-side PoW anti-spam |
Each phase includes difficulty rating, time estimate, AI prompts for development, and test commands for validation.
Build the block-lattice data structure, account-chain management, and basic transaction processing without consensus.
Create a Rust implementation for a Nano-inspired block-lattice DAG cryptocurrency called KnexCoin. Requirements: 1. Define a Block struct with fields: hash ([u8; 32]), previous ([u8; 32]), account ([u8; 32]), representative ([u8; 32]), balance (u128), block_type (enum: Send, Receive, Change, Bandwidth), link ([u8; 32]), bandwidth_proof (Option), signature ([u8; 64]), work (u64) 2. Implement Blake2b-256 for block hashing 3. Implement Ed25519 for signatures using ed25519-dalek crate 4. Create serialization/deserialization using bincode 5. Add validation methods for each block type 6. Include proof-of-work validation (anti-spam, minimal difficulty) The block should be compatible with a block-lattice structure where each account has its own chain. Send blocks create pending receivables, Receive blocks claim them. Output complete, production-ready Rust code with proper error handling and documentation.
Create a RocksDB-based storage layer for KnexCoin's block-lattice DAG. Requirements: 1. AccountChainDB struct wrapping RocksDB with column families: - accounts: account_pubkey -> AccountInfo (head block hash, balance, representative) - blocks: block_hash -> Block (serialized) - pending: (destination_account, source_block_hash) -> amount - representatives: rep_pubkey -> total_weight 2. Implement CRUD operations: - put_block(block) - validate and store block, update account head - get_block(hash) -> Option- get_account_chain(account) -> Vec (traverse from head) - get_pending(account) -> Vec - update_representative(account, new_rep) 3. Atomic operations using RocksDB WriteBatch for consistency 4. Implement proper error types with thiserror 5. Add LRU cache for hot accounts (100k entries) Use rocksdb crate. Include comprehensive unit tests.
Create a CLI wallet for KnexCoin using Rust and the clap crate. Commands needed: 1. knex wallet create - Generate new Ed25519 keypair, display mnemonic (BIP39) 2. knex wallet import- Restore from mnemonic 3. knex wallet balance [account] - Show balance and pending 4. knex send - Create and sign send block 5. knex receive [block_hash] - Create receive block for pending 6. knex change-rep - Create change block 7. knex history [account] - Show transaction history Requirements: - Secure key storage (encrypted with password, use argon2) - BIP39 mnemonic support (24 words) - Offline signing capability - Human-readable account addresses (knex1... bech32 format) - JSON output option for scripting Use clap v4 with derive macros. Include colored output using colored crate.
# Setup Rust development environment
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
rustup default stable
rustup component add clippy rustfmt llvm-tools-preview
# Install testing tools
cargo install cargo-tarpaulin # Code coverage
cargo install cargo-nextest # Faster test runner
cargo install cargo-watch # Auto-run tests
# Create project structure
mkdir knexcoin && cd knexcoin
cargo new node --lib
cargo new wallet
# Add dependencies to node/Cargo.toml
cat >> node/Cargo.toml << 'EOF'
[dependencies]
tokio = { version = "1", features = ["full"] }
rocksdb = "0.21"
ed25519-dalek = "2"
blake2 = "0.10"
serde = { version = "1", features = ["derive"] }
bincode = "1"
thiserror = "1"
lru = "0.12"
hex = "0.4"
rand = "0.8"
[dev-dependencies]
criterion = "0.5"
tempfile = "3"
proptest = "1"
EOF
# Run all unit tests cargo test --workspace # Run with verbose output cargo test --workspace -- --nocapture # Run specific block module tests cargo test -p knex-node block::tests # Test block creation cargo test test_create_genesis_block cargo test test_create_send_block cargo test test_create_receive_block cargo test test_create_change_block cargo test test_block_type_enum # Test block serialization cargo test test_block_serialize_deserialize cargo test test_block_bincode_roundtrip cargo test test_block_json_roundtrip # Test block validation cargo test test_block_hash_verification cargo test test_block_signature_verification cargo test test_block_balance_validation cargo test test_block_previous_link_validation cargo test test_reject_invalid_block_type cargo test test_reject_tampered_block
# Blake2b hashing tests cargo test test_blake2b_hash_correctness cargo test test_blake2b_test_vectors # RFC 7693 test vectors cargo test test_blake2b_empty_input cargo test test_blake2b_deterministic cargo test test_hash_different_inputs_differ # Ed25519 signature tests cargo test test_ed25519_keypair_generation cargo test test_ed25519_sign_verify cargo test test_ed25519_invalid_signature_fails cargo test test_ed25519_wrong_key_fails cargo test test_ed25519_test_vectors # RFC 8032 test vectors cargo test test_signature_malleability_protection # BIP39 mnemonic tests cargo test test_mnemonic_generation_24_words cargo test test_mnemonic_to_seed cargo test test_mnemonic_restore_keypair cargo test test_invalid_mnemonic_rejected cargo test test_mnemonic_checksum_validation
# Database CRUD tests cargo test test_db_put_block cargo test test_db_get_block cargo test test_db_get_nonexistent_block cargo test test_db_delete_block cargo test test_db_update_block # Account chain tests cargo test test_account_chain_traversal cargo test test_account_head_update cargo test test_account_balance_tracking cargo test test_account_representative_change cargo test test_multiple_accounts_isolation # Pending receivables tests cargo test test_add_pending_receivable cargo test test_get_pending_receivables cargo test test_claim_pending_receivable cargo test test_pending_removed_after_receive cargo test test_multiple_pending_same_account # RocksDB specific tests cargo test test_rocksdb_column_families cargo test test_rocksdb_write_batch_atomicity cargo test test_rocksdb_persistence_after_restart cargo test test_rocksdb_concurrent_access
# Full transaction flow integration test cargo test --test integration_tests test_full_send_receive_flow # Manual integration testing steps: # 1. Create two test wallets ./knex wallet create --output wallet_a.json ./knex wallet create --output wallet_b.json # 2. Fund wallet A with genesis block (testnet) ./knex genesis create --account $(cat wallet_a.json | jq -r .address) --amount 1000000 # 3. Send from A to B ./knex send --wallet wallet_a.json --to $(cat wallet_b.json | jq -r .address) --amount 100 # 4. Verify pending on B ./knex pending --wallet wallet_b.json # 5. Receive on B ./knex receive --wallet wallet_b.json # 6. Verify balances ./knex balance --wallet wallet_a.json # Should be 999900 ./knex balance --wallet wallet_b.json # Should be 100 # 7. Verify chain integrity ./knex verify-chain --account $(cat wallet_a.json | jq -r .address) ./knex verify-chain --account $(cat wallet_b.json | jq -r .address)
# Edge case tests cargo test test_send_entire_balance cargo test test_send_zero_amount_rejected cargo test test_send_negative_amount_rejected cargo test test_send_more_than_balance_rejected cargo test test_receive_already_claimed_rejected cargo test test_double_spend_rejected cargo test test_fork_detection cargo test test_orphan_block_handling cargo test test_max_balance_u128 cargo test test_very_long_account_chain # Property-based testing (proptest) cargo test test_proptest_block_roundtrip cargo test test_proptest_signature_validity cargo test test_proptest_balance_never_negative # Stress tests (run with --release) cargo test --release test_stress_1000_transactions -- --ignored cargo test --release test_stress_concurrent_sends -- --ignored cargo test --release test_stress_rapid_blocks -- --ignored
# Run all benchmarks cargo bench # Individual benchmarks cargo bench bench_block_creation cargo bench bench_block_hashing cargo bench bench_signature_creation cargo bench bench_signature_verification cargo bench bench_block_serialization cargo bench bench_db_write cargo bench bench_db_read cargo bench bench_chain_traversal # Expected targets: # - Block hashing: < 1μs # - Signature creation: < 100μs # - Signature verification: < 200μs # - DB write: < 1ms # - DB read: < 100μs # - Block serialization: < 10μs
# Check for common mistakes cargo clippy --all-targets --all-features -- -D warnings # Format code cargo fmt --all --check # Generate coverage report (target: >90%) cargo tarpaulin --out Html --output-dir coverage/ open coverage/tarpaulin-report.html # Run all checks before commit cargo fmt --all cargo clippy --all-targets --all-features cargo test --workspace cargo tarpaulin --fail-under 90
PHASE 1 COMPLETION CHECKLIST: BLOCK STRUCTURE: [ ] Block struct compiles and serializes correctly [ ] All block types implemented (Send, Receive, Change, Bandwidth) [ ] Block validation rejects invalid blocks [ ] Genesis block creation works CRYPTOGRAPHY: [ ] Blake2b hash matches RFC 7693 test vectors [ ] Ed25519 signatures match RFC 8032 test vectors [ ] BIP39 mnemonic generation and recovery works [ ] Keypair derivation is deterministic DATABASE: [ ] RocksDB stores and retrieves blocks correctly [ ] Account head updates atomically on new block [ ] Pending receivables tracked correctly [ ] Column families properly isolated [ ] Data persists after restart TRANSACTIONS: [ ] Send block decrements balance correctly [ ] Receive block increments balance correctly [ ] Previous block hash links correctly [ ] Double-spend prevention works [ ] Balance underflow prevented CLI WALLET: [ ] Creates valid Ed25519 keypairs [ ] Mnemonic backup/restore works [ ] Send command creates valid blocks [ ] Receive command claims pending [ ] Balance display accurate QUALITY: [ ] All unit tests pass [ ] All integration tests pass [ ] Code coverage >90% [ ] No clippy warnings [ ] Code formatted with rustfmt [ ] Documentation complete for public APIs [ ] Benchmarks meet performance targets
Implement node discovery, block propagation, and peer communication using libp2p.
Create a P2P networking layer for KnexCoin using libp2p in Rust.
Requirements:
1. NetworkService struct with:
- Kademlia DHT for peer discovery
- GossipSub for block/vote propagation
- Request-Response for direct queries
- Identify protocol for peer info exchange
2. Message types (use protobuf or serde):
- BlockAnnounce { block: Block }
- VoteMessage { block_hash, voter, signature }
- BlockRequest { hash } / BlockResponse { block }
- AccountInfoRequest / AccountInfoResponse
- PeerListRequest / PeerListResponse
3. Peer management:
- Bootstrap from seed nodes
- Maintain 8-50 active connections
- Peer scoring based on behavior (good blocks, response time)
- Ban misbehaving peers (invalid blocks, spam)
4. NAT traversal using AutoNAT and relay protocols
5. Encryption using Noise protocol (XX handshake pattern)
Use libp2p 0.53+. Include connection limits, rate limiting, and backpressure handling.
Implement a GossipSub-based block propagation system for KnexCoin. Requirements: 1. Topics: - /knex/blocks/1.0.0 - New block announcements - /knex/votes/1.0.0 - Consensus votes - /knex/confirmations/1.0.0 - Block confirmations 2. Message validation: - Reject messages > 1MB - Verify block signatures before forwarding - Deduplicate by message ID (hash) - Rate limit per peer (max 100 msg/sec) 3. Propagation optimization: - Priority queue for votes (consensus-critical) - Batch small blocks for efficiency - Lazy push for large blocks (announce hash first) 4. Metrics: - Messages sent/received per topic - Propagation latency percentiles - Peer message rates Include flood prevention, eclipse attack resistance, and peer diversity requirements (min 3 different /24 subnets).
# Add libp2p dependencies
cat >> node/Cargo.toml << 'EOF'
libp2p = { version = "0.53", features = [
"tokio", "tcp", "noise", "yamux", "gossipsub",
"kad", "identify", "autonat", "relay", "dcutr"
]}
prost = "0.12"
prost-build = "0.12"
tracing = "0.1"
tracing-subscriber = "0.3"
[dev-dependencies]
tokio-test = "0.4"
mockall = "0.11"
EOF
# Create protobuf definitions
mkdir -p node/proto
cat > node/proto/messages.proto << 'EOF'
syntax = "proto3";
package knex;
message BlockAnnounce {
bytes block_data = 1;
}
message VoteMessage {
bytes block_hash = 1;
bytes voter_pubkey = 2;
bytes signature = 3;
uint64 timestamp = 4;
}
EOF
# Install network testing tools
cargo install libp2p-lookup
sudo apt install iperf3 tcpdump # Linux
brew install iperf3 tcpdump # macOS
# Network service initialization cargo test test_network_service_creation cargo test test_network_service_start_stop cargo test test_peer_id_generation cargo test test_keypair_persistence # Transport layer tests cargo test test_tcp_transport_connect cargo test test_noise_handshake cargo test test_yamux_multiplexing cargo test test_connection_limits # Identify protocol tests cargo test test_identify_exchange cargo test test_protocol_negotiation cargo test test_agent_version_reporting
# Kademlia DHT tests cargo test test_kademlia_bootstrap cargo test test_kademlia_peer_discovery cargo test test_kademlia_routing_table cargo test test_kademlia_closest_peers cargo test test_kademlia_provider_records # Bootstrap tests cargo test test_bootstrap_from_seed_nodes cargo test test_bootstrap_with_invalid_seed cargo test test_bootstrap_timeout_handling cargo test test_bootstrap_multiple_seeds # Peer management tests cargo test test_peer_add_remove cargo test test_peer_connection_state cargo test test_maintain_peer_count cargo test test_peer_eviction_policy cargo test test_max_connections_enforced
# GossipSub subscription tests cargo test test_gossipsub_subscribe_blocks cargo test test_gossipsub_subscribe_votes cargo test test_gossipsub_unsubscribe cargo test test_gossipsub_topic_validation # Message propagation tests cargo test test_gossipsub_publish_block cargo test test_gossipsub_publish_vote cargo test test_gossipsub_receive_message cargo test test_gossipsub_message_deduplication cargo test test_gossipsub_message_validation # GossipSub scoring tests cargo test test_peer_scoring_valid_messages cargo test test_peer_scoring_invalid_messages cargo test test_peer_scoring_spam_detection cargo test test_peer_ban_threshold
# Message serialization tests cargo test test_block_announce_serialize cargo test test_vote_message_serialize cargo test test_protobuf_roundtrip cargo test test_invalid_protobuf_rejected # Message validation tests cargo test test_validate_block_signature_before_gossip cargo test test_reject_oversized_message cargo test test_reject_malformed_message cargo test test_message_rate_limiting # Request-response tests cargo test test_block_request_response cargo test test_account_info_request_response cargo test test_peer_list_request_response cargo test test_request_timeout_handling
# Start local test network (3 nodes) ./target/release/knexd --port 26656 --data-dir ./node1 --seed & PID1=$! sleep 2 ./target/release/knexd --port 26657 --data-dir ./node2 --bootstrap /ip4/127.0.0.1/tcp/26656 & PID2=$! ./target/release/knexd --port 26658 --data-dir ./node3 --bootstrap /ip4/127.0.0.1/tcp/26656 & PID3=$! sleep 5 # Verify peer discovery curl -s localhost:26656/api/peers | jq '.peers | length' # Should be 2 curl -s localhost:26657/api/peers | jq '.peers | length' # Should be 2 curl -s localhost:26658/api/peers | jq '.peers | length' # Should be 2 # Test block propagation curl -X POST localhost:26656/api/test/create_block sleep 1 curl -s localhost:26657/api/blocks/latest | jq # Should have new block curl -s localhost:26658/api/blocks/latest | jq # Should have new block # Cleanup kill $PID1 $PID2 $PID3
# Automated integration tests cargo test --test network_integration test_3_node_block_propagation cargo test --test network_integration test_5_node_block_propagation cargo test --test network_integration test_10_node_block_propagation # Vote propagation tests cargo test --test network_integration test_vote_reaches_all_nodes cargo test --test network_integration test_vote_aggregation # Partition tests cargo test --test network_integration test_network_partition_recovery cargo test --test network_integration test_node_rejoin_after_disconnect # Measure propagation latency cargo test --test network_integration test_measure_propagation_latency -- --nocapture # Target: <500ms for 10-node network
# Eclipse attack resistance cargo test test_eclipse_attack_detection cargo test test_peer_diversity_enforcement cargo test test_min_unique_subnets_requirement # Sybil attack resistance cargo test test_connection_limit_per_ip cargo test test_rate_limit_new_connections cargo test test_peer_reputation_scoring # DDoS protection cargo test test_message_rate_limiting cargo test test_connection_rate_limiting cargo test test_backpressure_handling # Flood prevention cargo test test_gossipsub_flood_protection cargo test test_duplicate_message_filtering cargo test test_invalid_message_ban
# AutoNAT tests cargo test test_autonat_detection cargo test test_nat_type_discovery # Relay tests (requires external setup) cargo test test_relay_reservation cargo test test_relay_connection cargo test test_dcutr_hole_punch # Test NAT traversal manually: # 1. Start relay node with public IP ./knexd --relay-mode --external-ip YOUR_PUBLIC_IP --port 26656 # 2. Start node behind NAT ./knexd --bootstrap /ip4/YOUR_PUBLIC_IP/tcp/26656 --enable-relay # 3. Verify connectivity curl localhost:26657/api/nat_status # Should show "relayed" or "public"
# Run network benchmarks cargo bench --bench network_benchmarks # Individual benchmarks cargo bench bench_message_serialization cargo bench bench_message_validation cargo bench bench_peer_discovery_time cargo bench bench_propagation_latency_10_nodes cargo bench bench_propagation_latency_50_nodes cargo bench bench_max_message_throughput # Expected targets: # - Message serialization: < 10μs # - Message validation: < 100μs # - Peer discovery: < 5s for 10 peers # - Propagation (10 nodes): < 200ms # - Propagation (50 nodes): < 500ms # - Throughput: > 10,000 msgs/sec
# Network stress tests (run with --release) cargo test --release test_stress_100_concurrent_connections -- --ignored cargo test --release test_stress_1000_messages_per_second -- --ignored cargo test --release test_stress_rapid_connect_disconnect -- --ignored cargo test --release test_stress_large_messages -- --ignored # Long-running stability test cargo test --release test_24_hour_stability -- --ignored # Memory leak detection cargo test --release test_memory_usage_over_time -- --ignored # Use valgrind for detailed memory analysis valgrind --leak-check=full ./target/release/knexd --test-mode
PHASE 2 COMPLETION CHECKLIST: LIBP2P CORE: [ ] Network service starts and stops cleanly [ ] Peer ID generated and persisted [ ] TCP transport with Noise encryption works [ ] Yamux multiplexing works [ ] Connection limits enforced PEER DISCOVERY: [ ] Kademlia DHT bootstraps from seed nodes [ ] Peers discovered within 5 seconds [ ] Routing table maintained correctly [ ] Peer count stays within limits (8-50) GOSSIPSUB: [ ] Block topic subscription works [ ] Vote topic subscription works [ ] Messages propagate to all subscribers [ ] Message deduplication works [ ] Peer scoring rejects bad actors MESSAGE HANDLING: [ ] Protobuf serialization works [ ] Invalid messages rejected [ ] Rate limiting enforced [ ] Request-response protocol works SECURITY: [ ] Eclipse attack detection works [ ] Sybil attack mitigation works [ ] DDoS protection effective [ ] Peer reputation system functional NAT TRAVERSAL: [ ] AutoNAT detects NAT type [ ] Relay connections work [ ] Hole punching works (when possible) PERFORMANCE: [ ] Propagation < 500ms for 10 nodes [ ] Throughput > 10,000 msgs/sec [ ] Memory usage stable over time [ ] No connection leaks QUALITY: [ ] All unit tests pass [ ] All integration tests pass [ ] Stress tests pass [ ] Code coverage > 85% [ ] No clippy warnings
Implement Open Representative Voting. For phased delivery, early testnets may use simplified weighting for stability testing. However, the canonical v5.1 protocol weight rule is PoB-first: VotingWeight = BandwidthScore × min(1, Stake / MIN_STAKE). Stake is eligibility + slashing collateral only; it is not a power multiplier beyond the bond threshold.