CoCo Blockchain

Overview

CoCo is a Substrate-based blockchain protocol purpose-built for real businesses. It creates a programmable economic layer where merchants can issue tokens, track inventory, manage digital rights, and accept payments — all without understanding blockchain. The system hides behind familiar tools: a barcode scanner, a dashboard, a POS terminal.

Any organization can issue custom programmable tokens — loyalty points, employee compensation, asset-backed credits, or micro-finance instruments — that can be exchanged across a unified ecosystem with near-zero fees (0% internal, 0.25% external vs. 2-5% card networks). The protocol extends this with a Product Rights Management (PRM) system: physical products are tokenized as NFTs carrying DRM flags that enable pay-as-you-go, lease-to-own, subscriptions, and microtransaction-based feature unlocks.

Barcode scanning, real-time inventory analysis, and POS integration provide the physical-world bridge. The goal is not to build a crypto platform — it's to build a better payment and inventory system that happens to run on a blockchain.

Three-Layer Architecture

Key Differentiators (v0.6)

Fee Comparison: Retail Payment ($20 purchase)

Fee Comparison: B2B / Supplier Payment ($1,000 invoice)

0.25% border fee is still 10-24x cheaper than any card processor. Internal ecosystem movement is 0%. The only thing cheaper is cash — and cash doesn't give you inventory analytics, DRM enforcement, automated supplier ordering, or yield-bearing savings.

Architecture

System Diagram

┌─────────────────────────────────────────────────────────────────────┐
│                      CoCo Blockchain (Substrate)                    │
│                                                                     │
│  ┌────────────────────────────────────────────────────────────┐    │
│  │                    Runtime (FRAME) — 3 Layers              │    │
│  │                                                             │    │
│  │  LAYER 1: ECONOMIC ✦ BRIDGE                               │    │
│  │  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────┐ │    │
│  │  │pallet-   │ │pallet-   │ │pallet-   │ │pallet-       │ │    │
│  │  │assets    │ │kyc       │ │rewards   │ │bridge 🆕     │ │    │
│  │  └──────────┘ └──────────┘ └──────────┘ └──────────────┘ │    │
│  │                                                             │    │
│  │  LAYER 2: PRODUCT RIGHTS MANAGEMENT                        │    │
│  │  ┌──────────────────┐ ┌────────────┐ ┌──────────────────┐ │    │
│  │  │pallet-product-nft│ │pallet-drm  │ │pallet-           │ │    │
│  │  │★ (digital twins) │ │(enforce)   │ │microfinance      │ │    │
│  │  └──────────────────┘ └────────────┘ └──────────────────┘ │    │
│  │                                                             │    │
│  │  LAYER 3: PHYSICAL BRIDGE ✦ REALTIME INVENTORY           │    │
│  │  ┌──────────┐ ┌──────────┐ ┌──────────┐                   │    │
│  │  │barcode   │ │inventory │ │POS       │                   │    │
│  │  │scanner   │ │analysis  │ │terminal  │                   │    │
│  │  └──────────┘ └──────────┘ └──────────┘                   │    │
│  │                                                             │    │
│  │  System: ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────┐ │    │
│  │          │balances  │ │timestamp │ │sudo      │ │grandpa│ │    │
│  │          └──────────┘ └──────────┘ └──────────┘ └──────┘ │    │
│  └────────────────────────────────────────────────────────────┘    │
│  Consensus: Aura (6s blocks) + Grandpa (fast finality)              │
└────────────────────────────────────────────────────────────────────┘
                          ↕
┌─────────────────────────┼──────────────────────────┐
│                         │                          │
│              ┌──────────▼──────────┐              │
│              │   Node.js Server    │              │
│              │  (REST API + WS)    │              │
│              └──────────┬──────────┘              │
│                         │                          │
│  ┌─────────────────┐  ┌───────────────────────┐  │
│  │ Web Apps        │  │   Mobile Apps         │  │
│  │ /login          │  │   Android Scanner     │  │
│  │ /admin          │  │   (Kotlin + ML Kit)   │  │
│  │ /dashboard      │  └───────────────────────┘  │
│  │ /marketplace    │                              │
│  │ /onboarding      │                              │
│  └─────────────────┘                              │
└──────────────────────────────────────────────────┘

Directory Structure

/home/nate/gemini/coco/
├── coco-substrate/          ★ Primary — Substrate blockchain
│   ├── node/                Node binary (CLI, RPC, chain spec)
│   ├── runtime/             All pallets configured
│   ├── pallets/             11 custom pallets + pallet-contracts
│   │   ├── product-nft/     ★ Core — product NFT + DRM (v0.5)
│   │   ├── kyc/             KYC provider network
│   │   ├── rewards/         Yield distribution + staking
│   │   └── ... (7 more)
│   ├── contracts/           Example ink! smart contracts (PAYG, Lease, Escrow)
│   ├── scripts/             Build & run utilities
│   └── docs/                Technical documentation
├── barcode/                 Scanner app + POS server
│   ├── app/                 Android app (Kotlin)
│   └── Server/              Node.js backend (Express, SQLite)
└── website/                 Public website and documentation

Pallet Reference

ProductNFT {
    product_id: u128,
    gtin: BoundedString,         // GTIN-14 (GS1 standard)
    serial_number: BoundedString, // Unit-level serial
    batch_id: BoundedString,
    name: BoundedString,
    category: ProductCategory,
    manufacturer: AccountId,
    manufactured_at: BlockNumber,
    current_owner: AccountId,
    status: ProductStatus,       // InProduction → ... → Sold/EndOfLife
    custody_chain: BoundedVec<CustodyRecord>,
    sale_price: Option<Balance>,
    warranty: Option<WarrantyInfo>,
    drm: Option<DRMStatus>,     // 🆕 v0.5: DRM config, state, features
}

DRMStatus {                     // 🆕 v0.5
    drm_config: DRMConfig { drm_enabled, enforcement_type, ... },
    drm_state: DRMState,        // Unlocked | Licensed | FeatureLocked | FullyLocked | Repossessed | Burned
    features: BoundedVec<FeatureLock>,
    enforcement_history: BoundedVec<EnforcementRecord>,
}

ProductStatus enum:
  InProduction | InTransit | AtDistributor | InStore |
  Sold | ListedForResale | Recalled | ReportedStolen | EndOfLife

RecallInfo {
    recalled_by: AccountId,
    recalled_at: BlockNumber,
    reason: BoundedString,
    action: RecallAction,  // Return | Dispose | Replace | Refund
    is_resolved: bool,
    resolved_at: Option<BlockNumber>,
}

MarketListing {
    seller: AccountId,
    price: Balance,
    listed_at: BlockNumber,
    royalty_percent: Option<u8>,  // Brand royalty on resale
}

Unlocked → Licensed → FeatureLocked → FullyLocked → Repossessed → Burned
   ↑          |            |               |             |
   └──────────┴────────────┴───────────────┴─────────────┘
                    (payment restores access)

ProductNFT {
    ...
    drm: Option<DRMStatus>,  // NEW: DRM config, state, features
}

Pending → Active → Late → EvictionProcess → Terminated → Completed
            ↑         ↓ (pay rent)               ↓
            └─────────┘                    release_deposit

Solana → CoCo: User locks tokens on Solana
               → Relayer detects event
               → Calls bridge.deposit() on CoCo
               → Wrapped tokens minted to recipient

CoCo → Solana: User calls bridge.withdraw() on CoCo
               → Wrapped tokens burned
               → Relayer detects WithdrawalInitiated event
               → Calls unlock_tokens() on Solana program
               → User receives native tokens on Solana

Off-Chain Treasury (T-bills)
    ↓ Interest earned
Convert to USDC
    ↓ Bridge to CoCo chain
Treasury Manager calls distribute_rewards()
    ↓ Proportional to stake
KYC-Approved Stakers → Pending Rewards
    ↓ claim_rewards()
Withdrawn to staker's wallet

# Install ink! toolchain
cargo install cargo-contract

# Build a contract
cd coco-substrate/contracts/payg
cargo contract build

# Upload via Polkadot.js → Developer → Contracts
# Instantiate with constructor args
# Call via extrinsic or UI

API Reference

The Node.js server at barcode/Server/ provides REST API endpoints for both the POS system and blockchain operations.

Auth & POS Endpoints

Blockchain Onboarding Endpoints

Bridge Endpoints 🆕

Note: "seed" is the private key seed phrase for signing transactions. In production, this would use a wallet connection (Polkadot.js extension, mobile wallet) rather than raw seed input.

Web App Routes

Substrate Service (substrate.js)

// The Polkadot.js API client handles:
getApi()           — Connect to ws://127.0.0.1:9944
sendTransaction()  — Sign + submit + wait for inclusion + decode errors
getAlice()         — Get dev sudo key for KYC approval

Web Applications

./coco-substrate/scripts/admin.sh build
./coco-substrate/scripts/admin.sh run
./coco-substrate/scripts/admin.sh test nft

QR Code Standard

Every product on CoCo has a scannable QR code linking its physical form to its on-chain digital twin. The standard is defined in docs/QR_CODE_STANDARD.md.

URI Scheme

coco://product/{chain_id}/{product_id}?gtin={gtin}&serial={serial}&sig={signature}

Example

coco://product/0/0x00000000000000000000000000000001?gtin=00012345678905&serial=LV-2024-001234

Types

GS1 Digital Link Compatibility

GS1 Digital Link:  https://id.gs1.org/01/00012345678905/21/LV-2024-001234
CoCo Equivalent:   coco://product/0/0x01?gtin=00012345678905&serial=LV-2024-001234

Supported Barcode Formats (Scanner App)

UPC-A, UPC-E, EAN-13, EAN-8, Code 128, Code 39, Code 93, QR, Data Matrix, PDF417, Aztec, ITF, Codabar

Resolution Flow

User scans QR code → App extracts product_id from URI
  → Queries chain: Products(product_id)
  → Displays: authenticity, status, custody chain, warranty
  → If for sale: show purchase option
  → If owned by user: show manage options (list, claim warranty)

Installation / Runtime Guide

System Requirements

Prerequisites

# Rust toolchain
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
rustup target add wasm32-unknown-unknown

# System dependencies (Ubuntu)
apt install build-essential pkg-config libssl-dev clang

# Node.js 18+ (for server/relayer)
curl -fsSL https://deb.nodesource.com/setup_18.x | bash -
apt install nodejs

# Verify
rustc --version          # ≥ 1.77
node --version           # ≥ 18

Build from Source

cd coco-substrate

# Release build (recommended — 30-60 min)
./scripts/build.sh

# Or manually:
cargo build --release -p coco-substrate

# Binary at: ./target/release/coco-node
./target/release/coco-node --version

Development Chain (Single Node)

# Quick start
./scripts/run-dev.sh

# Or manual:
./target/release/coco-node --dev --tmp

# Connect: ws://127.0.0.1:9944
# Connect: https://polkadot.js.org/apps → Development → Local Node

Validator Setup (Testnet)

# 1. Generate chain spec
./target/release/coco-node build-spec --chain local --raw > testnet-spec.json

# 2. Generate validator keys
./target/release/coco-node key generate --scheme sr25519 --output-type json > aura-key.json
./target/release/coco-node key generate --scheme ed25519 --output-type json > grandpa-key.json

# 3. Insert keys
./target/release/coco-node key insert \
  --base-path /opt/coco/data/validator \
  --chain testnet-spec.json \
  --scheme sr25519 --key-type aura --suri "<seed>"

./target/release/coco-node key insert \
  --base-path /opt/coco/data/validator \
  --chain testnet-spec.json \
  --scheme ed25519 --key-type gran --suri "<seed>"

# 4. Start validator
./target/release/coco-node \
  --chain testnet-spec.json \
  --base-path /opt/coco/data/validator \
  --name "My Validator" --validator \
  --rpc-methods Safe --rpc-external --ws-external \
  --prometheus-external

# Ports: 30333 (P2P), 9933 (RPC), 9944 (WS), 9615 (metrics)
# See beta_instructions.md for multi-validator testnet setup

Server + Website

# Start Node.js server (POS + blockchain proxy)
cd barcode/Server
npm install
cp .env.example .env    # Edit SUBSTRATE_URL
npm start               # http://localhost:3000

# Web apps:
#   /admin      — POS dashboard
#   /dashboard  — Company inventory
#   /marketplace — P2P product listings
#   /onboarding — Company setup wizard
#   /login      — Authentication

Wallets

# Linux CLI wallet
cd barcode/linux-wallet
npm install
./wallet.js new           # Create wallet
./wallet.js balance       # Check balances
./wallet.js send <addr> <amt>  # Send COCO

# Android wallet
# Build: cd barcode && ./gradlew assembleDebug
# APK: app/build/outputs/apk/debug/app-debug.apk

Running the Bridge Relayer

# Environment
export COCO_WS_URL=ws://127.0.0.1:9944
export COCO_RELAYER_SEED=//RelayerRelayer

# Start relayer
node scripts/bridge-relayer.js

# Register bridged assets (as root)
curl -X POST http://localhost:3000/api/bridge/register-asset \
  -H "Content-Type: application/json" \
  -d '{
    "sourceChain":"Solana",
    "sourceTokenAddress":"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
    "name":"USD Coin","symbol":"USDC","decimals":6,
    "seed":"//Alice"
  }'

Build & Test Guide

Build Blockchain

cd coco-substrate

# Quick build (recommended)
./scripts/build.sh

# Or manually:
cargo build --release -p coco-substrate-runtime
cargo build --release -p coco-substrate

# Binary: ./target/release/coco-node

Run Dev Chain

./scripts/run-dev.sh
# or: ./target/release/coco-node --dev

# RPC: ws://127.0.0.1:9944 | http://127.0.0.1:9933
# Connect: https://polkadot.js.org/apps → Development → Local Node

Run Tests

# Product NFT pallet (36 tests)
cargo test -p pallet-product-nft

# All pallets
cargo test -p pallet-kyc
cargo test -p pallet-rewards

Run Server + Onboarding Website

cd barcode/Server
npm install
cp .env.example .env         # Edit SUBSTRATE_URL if needed
npm start                    # http://localhost:3000

# Open: http://localhost:3000/onboarding.html

Build Android App

cd barcode
./gradlew assembleDebug
# APK: app/build/outputs/apk/debug/app-debug.apk

Onboarding Flow

The company onboarding process is a 6-step flow documented in ONBOARDING.md and implemented in the website at /onboarding.html.

Step Details

Extended Consumer Flow

Tokenomics & Network Parameters

Network Parameters

Fee Model

How It Works

// Fee configuration (stored on-chain):
struct FeeConfiguration {
    fee_collector: AccountId,    // Treasury address
    sale_fee_rate: Permill,      // 0.25% default
    resale_fee_rate: Permill,    // 0.25% default
    mint_fee_rate: Permill,      // 0.1% default
}

// Example: Retail sale of 1000 COCO product
// Sale price: 1000 COCO
// Fee (0.25%): 2.5 COCO → transferred to TreasuryAccount
// Seller receives: 997.5 COCO (net)

Fees are automatically deducted during sell_to_consumer and buy_listing extrinsics via the charge_fee helper. The treasury account is set to Alice in dev mode and should be changed to a multi-sig treasury for production.

Dev Accounts

Roadmap & Status

Legend

Done New Pending Planned

Phase 1 — Foundation Complete

• ✓ Substrate node (Aura + Grandpa consensus)
• ✓ COCO native token (1B supply, 12 decimals)
• ✓ pallet-kyc (provider network, address approval, expiry)
• ✓ pallet-rewards (treasury managers, staking, yield distribution)
• ✓ pallet-assets integration (company sub-tokens)
• ✓ Docker, scripts, chain specs, documentation

Phase 2 — Product Features Complete

• ✓ pallet-product-nft: company registration, minting, transfer, sale
• ✓ Authentication: manufacturer verifies product authenticity on-chain
• ✓ Recall Management: flag products, block transfers/sales, track resolution
• ✓ Warranty Claims: submit + resolve claims with full history
• ✓ Consumer Registration: post-purchase activation, product portfolio
• ✓ P2P Resale: marketplace listings, buying, cancellations, royalties
• ✓ QR Code Standard: coco:// URI scheme with GS1 compatibility
• ✓ 40 Unit + Integration Tests: all extrinsics + full lifecycle flows
• ✓ Server API routes for all 16 extrinsics
• ✓ Fee Routing: 0.25% sale/resale fee, configurable rates, treasury account
• ✓ Company Dashboard: web app at /dashboard
• ✓ P2P Marketplace: web app at /marketplace
• ✓ Admin Script: scripts/admin.sh with 9 commands
• ✓ Scanner Integration Guide: docs/SCANNER_INTEGRATION.md
• ✓ Comprehensive documentation site

Phase 3a — DRM & Enforcement Complete

• ✓ DRM types & storage: DRMStatus, DRMState, FeatureLock, EnforcementRecord
• ✓ DRM extrinsics: set_drm_config, lock/unlock product, lock/unlock feature, repossess, burn, emergency override, expire_feature, consent flow
• ✓ Consumer DRM Consent: provide/revoke + sell_to_consumer enforcement + 4 tests
• ✓ Emergency Override: authority role, break-glass, max limits + 3 tests
• ✓ Micro-Finance pallet: PAYG, lease-to-own, subscriptions, micro-loans, batch settlement
• ✓ DRM Oracle Specification: docs/DRM_ORACLE_SPEC.md
• ✓ 63 tests across product-nft (47) + micro-finance (16)
• ☐ Automotive feature unlock pilot (partnership-dependent)

Phase 3e — Rental Contracts Complete

• ✓ pallet-rental: 7 extrinsics, full lease lifecycle
• ✓ 13 unit tests: state transitions, access control, deposit escrow
• ✓ DRM integration: pay → unlock, late → lock, vacate → release
• ✓ Server API: 7 endpoints at /api/rental
• ☐ Smart contract integration for custom lease terms

Phase 3c — Solana/USDC/USDT Bridge Complete

• ✓ pallet-bridge: 8 extrinsics, asset registry, deposit/withdraw/complete flows
• ✓ 12 unit tests: all extrinsics, replay protection, relayers, pause
• ✓ Solana Program Spec: docs/SOLANA_BRIDGE_SPEC.md
• ✓ Off-Chain Relayer: scripts/bridge-relayer.js
• ✓ Server API: 7 bridge endpoints at /api/bridge
• ☐ Deploy Solana program to devnet/mainnet (requires Solana dev)
• ☐ Run relayer 24/7 in production

Phase 4 — Merchant Tools & Ecosystem Complete

• ✓ Barcode Scanner Wallet — Android app with on-device SR25519 keygen, BIP39 mnemonics, biometric auth, scan-to-redeem in <5s
• ✓ Realtime Inventory Analysis — Dashboard with stock alerts, sales velocity, ABC classification, auto-reorder, expiry tracking + markdown engine
• ✓ Merchant-Friendly POS — One-click checkout via barcode scan, offline queue, receipt with TVA, virtual card terminal
• ✓ Zero-Crypto UX — Email+PIN registration, gas station accounts, delegated signing, no seed phrases for merchants
• ✓ Sub-Token AMM (Swap) — pallet-swap with CoCo-K hub pools, constant product x*y=k, auto-registration, LP staking, 7 server routes
• ✓ EUR/USD Oracle — pallet-oracle with rate setting, expiry, conversion endpoint
• ✓ Multi-Currency Checkout — oracle rates + swap pools + round-up savings + B2B settlement
• ✓ Supply Chain Automation — pallet-supply-chain: purchase orders, shipping, delivery auto-pay, payment intents
• ✓ Cross-Merchant Loyalty — pallet-loyalty: earn/redeem points, referral codes with 50 COCO payouts
• ✓ Dispute Resolution — pallet-dispute: time-locked escrow, mediator network (10 COCO stake), refund receipts, CSV reports
• ✓ Tax-Compliant Receipts — QR receipts with French TVA (5.5%/10%/20%), merchant VAT number, daily CSV settlement
• ✓ Expiry + Markdown Engine — Auto-suggest discounts (20% at 2 days, 40% at 1 day, 60% on expiry day), one-click apply, margin analysis
• ✓ Website Auth + KYC — MariaDB-backed Express server, Google OAuth, document upload, admin review queue, sub-coin creation wizard

Phase 5 — Smart Contracts Complete

• ✓ pallet-contracts — Wasm smart contract support integrated into runtime (16th pallet)
• ✓ CoCo Chain Extension — 5 functions exposing KYC, product NFT queries, and DRM status to ink! contracts
• ✓ PAYG Contract — Pay-as-you-go ink! contract with KYC-gated access checks
• ✓ Lease-to-Own Contract — Installment payment contract with ownership transfer
• ✓ Escrow Contract — Time-locked escrow with mediator resolution and staking
• ☐ Deploy contracts to testnet for integration testing

Phase 6 — Infrastructure & Scale Remaining

• ☐ Benchmarking + weight calculation for all extrinsics
• ☐ Load testing (100K products/hour target)
• ☐ Professional security audit ($75K budget)
• ☐ Public testnet deployment (4+ validators)
• ☐ Governance: pallet-collective, pallet-treasury, pallet-staking
• ☐ Developer SDK (JavaScript, Python)
• ☐ Mobile wallet SDK (iOS + Android)
• ☐ Mainnet deployment

Year 1 Targets (v0.5)