Crypto that works for real businesses.
Near-zero fees. Real-time inventory. No complexity.
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.
| Capability | CoCo | Traditional |
|---|---|---|
| Payment Fees (retail) | 0.25% | Visa/MC 2-5% |
| B2B / Supplier Payment | 0% internal | 2-3% card or $25 wire |
| Settlement Time | 6 seconds | 1-3 business days |
| Chargebacks | None | Costly & frequent |
| Programmable Tokens | Custom sub-tokens + sub-token AMM | Siloed loyalty programs |
| DRM Enforcement | On-chain lock/unlock/repossess | No enforcement mechanism |
| Micro-finance | PAYG, lease-to-own, subscriptions, rentals | Credit cards (2-3% fees) |
| Supply Chain + Inventory | Real-time, on-chain, auto-reorder from suppliers | Siloed, no cross-org data |
| Inter-Ecosystem Trade | 0% between any CoCo tokens | Visa/Mastercard 2-3% |
| Merchant Complexity | Scan barcode → done | Terminal contract, PCI audit, chargeback risk |
| Processor | Fee on $20 | Settlement |
|---|---|---|
| ★ CoCo | $0.05 | 6 seconds |
| Visa / Mastercard | $0.50 – $0.90 | 1-2 days |
| MercadoPago QR | $0.30 – $0.40 | Next day |
| MercadoPago Card | $0.80 – $1.00 | Next day |
| PayPal | $1.19 | Instant (holds apply) |
| Stripe | $0.88 | 1-2 days |
| Method | Fee on $1,000 | Settlement |
|---|---|---|
| ★ CoCo (internal) | $0.00 | 6 seconds |
| ★ CoCo (border crossing) | $2.50 | 6 seconds |
| Wire Transfer | $25 – $50 flat | 1-3 days |
| Corporate Credit Card | $20 – $30 (2-3%) | 1-2 days |
| Paper Check | $5 – $10 + float | 5-10 days |
| ACH / SEPA | ~$0.50 | 2-3 days |
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.
┌─────────────────────────────────────────────────────────────────────┐
│ CoCo Blockchain (Substrate) │
│ │
│ ┌────────────────────────────────────────────────────────────┐ │
│ │ Runtime (FRAME) — 18 Pallets │ │
│ │ │ │
│ │ ECONOMIC LAYER │ │
│ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────┐ │ │
│ │ │pallet- │ │pallet- │ │pallet- │ │pallet- │ │ │
│ │ │assets │ │kyc │ │rewards │ │bridge (TRON) │ │ │
│ │ └──────────┘ └──────────┘ └──────────┘ └──────────────┘ │ │
│ │ ┌──────────┐ ┌──────────┐ │ │
│ │ │pallet- │ │pallet- │ │ │
│ │ │swap │ │oracle │ │ │
│ │ └──────────┘ └──────────┘ │ │
│ │ │ │
│ │ PRODUCT RIGHTS LAYER │ │
│ │ ┌──────────────────┐ ┌──────────────────┐ ┌────────────┐ │ │
│ │ │pallet-product-nft│ │pallet- │ │pallet- │ │ │
│ │ │★ (digital twins) │ │microfinance │ │rental │ │ │
│ │ └──────────────────┘ └──────────────────┘ └────────────┘ │ │
│ │ ┌──────────────┐ ┌──────────┐ ┌──────────┐ │ │
│ │ │pallet- │ │pallet- │ │pallet- │ │ │
│ │ │supply-chain │ │loyalty │ │dispute │ │ │
│ │ └──────────────┘ └──────────┘ └──────────┘ │ │
│ │ │ │
│ │ GOVERNANCE ✦ PRIVACY LAYER │ │
│ │ ┌──────────┐ ┌────────────────┐ │ │
│ │ │pallet- │ │pallet- │ │ │
│ │ │voting │ │shielded-coin │ │ │
│ │ │(+union) │ │(stealth addr) │ │ │
│ │ └──────────┘ └────────────────┘ │ │
│ │ │ │
│ │ System: ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────┐ │ │
│ │ │balances │ │timestamp │ │sudo │ │grandpa│ │ │
│ │ └──────────┘ └──────────┘ └──────────┘ └──────┘ │ │
│ └────────────────────────────────────────────────────────────┘ │
│ Consensus: Aura (6s blocks) + Grandpa (fast finality) │
└────────────────────────────────────────────────────────────────────┘
↕
┌─────────────────────────┼──────────────────────────┐
│ │ │
│ ┌──────────▼──────────┐ │
│ │ API Servers │ │
│ │ barcode/Server │ │
│ │ website/server.js │ │
│ └──────────┬──────────┘ │
│ │ │
│ ┌─────────────────┐ ┌───────────────────────┐ │
│ │ Web Apps │ │ Mobile Apps │ │
│ │ /wallet │ │ Android Scanner │ │
│ │ /explorer │ │ Android Wallet │ │
│ │ /dashboard │ └───────────────────────┘ │
│ │ /union-now │ │
│ │ /voting │ │
│ └─────────────────┘ │
└──────────────────────────────────────────────────┘
The core pallet managing the full lifecycle of physical products as digital twins (NFTs). 17 extrinsics (0-16) + 8 DRM extrinsics (17-24), 14 storage maps, 26 events, 43 error codes.
| # | Extrinsic | Call Index | Access | Description |
|---|---|---|---|---|
| 0 | register_company | 0 | KYC user | Register a brand/company |
| 1 | deactivate_company | 1 | Owner | Deactivate own company |
| 2 | activate_company | 2 | Owner | Reactivate company |
| 3 | mint_product | 3 | Company | Mint 1 product with GTIN+serial |
| 4 | batch_mint_products | 4 | Company | Mint up to 1000 units |
| 5 | transfer | 5 | Owner | Transfer custody + location |
| 6 | sell_to_consumer | 6 | Owner | Retail sale + warranty |
| 7 | authenticate_product | 7 | Mfr | Mark authentic on-chain |
| 8 | recall_product | 8 | Mfr | Recall product, block sale |
| 9 | resolve_recall | 9 | Mfr | Close recall, EndOfLife |
| 10 | register_product | 10 | Owner | Add to consumer portfolio |
| 11 | submit_warranty_claim | 11 | Owner | File a warranty claim |
| 12 | resolve_warranty_claim | 12 | Mfr | Approve/deny claim |
| 13 | list_for_sale | 13 | Owner | List on marketplace |
| 14 | buy_listing | 14 | Any | Purchase listed product |
| 15 | cancel_listing | 15 | Seller | Remove listing |
| 16 | set_fee_config | 16 | Root | Set fee rates & treasury collector |
| # | Extrinsic | Call Index | Access | Description |
|---|---|---|---|---|
| 17 | set_drm_config | 17 | Manufacturer | Enable DRM on a product, set enforcement type |
| 18 | lock_product | 18 | Financing Entity | Lock product (missed payment, default) |
| 19 | unlock_product | 19 | Financing Entity | Restore product access on payment |
| 20 | unlock_feature | 20 | Any | Microtransaction: unlock single feature for N blocks |
| 21 | lock_feature | 21 | Financing Entity | Lock a specific feature |
| 22 | repossess_product | 22 | Manufacturer | Transfer ownership back on final default |
| 23 | burn_drm | 23 | Owner | Permanently remove DRM (full ownership achieved) |
| 24 | emergency_drm_override | 24 | Emergency Auth | Temporary unlock for safety/medical emergencies |
| 25 | provide_drm_consent | 25 | Consumer | Consumer consent at sale for DRM |
| 26 | revoke_drm_consent | 26 | Consumer | Consumer revokes DRM consent |
| 27 | set_emergency_authority | 27 | Root | Designate emergency override accounts |
| 28 | consumer_break_glass_override | 28 | Consumer | 1-time consumer emergency unlock |
| 29 | expire_feature | 29 | Any | Time-based feature expiry check |
Unlocked → Licensed → FeatureLocked → FullyLocked → Repossessed → Burned
↑ | | | |
└──────────┴────────────┴───────────────┴─────────────┘
(payment restores access)
| Model | Example | DRM Flow |
|---|---|---|
| Pay-as-you-go | Heated seats: $0.50/24h | FeatureLocked → unlock_feature(payment) → Timed unlock → Locked on expiry |
| Lease-to-own | Smartphone: $30/mo × 24 | Licensed → Each payment → ownership% → Full payment → Burned |
| Subscription | Premium audio: $10/mo | Licensed → Missed payment → FeatureLocked → Payment → Unlocked |
| Micro-loan | $200 loan on $500 phone | FullyLocked → Repayment → Unlocked → Default → Repossessed |
| Name | Key | Value | Query |
|---|---|---|---|
| Companies | AccountId | CompanyInfo | Option |
| CompanyCount | — | u32 | Value |
| NextProductId | — | u128 | Value |
| Products | u128 | ProductNFT | Option |
| ProductLookup | (GTIN, Serial) | u128 | — |
| Authentications | u128 | AuthenticationRecord | Option |
| RecalledProducts | u128 | RecallInfo | Option |
| ConsumerPortfolio | AccountId | BoundedVec<u128> | Value |
| WarrantyClaimCount | — | u32 | Value |
| WarrantyClaims | (u128, u32) | WarrantyClaim | Option |
| MarketListings | u128 | MarketListing | Option |
| FeeConfig | — | FeeConfiguration | Value |
| ProductDRM 🆕 | u128 | DRMStatus | Option |
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
}
Manages KYC provider network and user address approvals. Used as a gate for company registration and staking.
| Extrinsic | Access | Description |
|---|---|---|
| add_kyc_provider | Root | Register a KYC provider |
| remove_kyc_provider | Root | Remove a KYC provider |
| activate_provider | Root | Reactivate suspended provider |
| deactivate_provider | Root | Suspend a provider |
| approve_address | Provider | KYC-approve a user |
| revoke_approval | Provider | Revoke KYC approval |
is_kyc_approved(address) — Check if address is KYC'd and activeget_kyc_approval(address) — Get approval details (expiry, provider)is_kyc_provider(account) — Check if account is a KYC providerget_all_approved_addresses() — List all active KYC addressesApartment lease agreements with DRM-enforced access control. An apartment is a ProductNFT with DRM — on-time payment unlocks the door, late payment locks it. Security deposits held in escrow, released on completion or dispute.
| # | Extrinsic | Access | Description |
|---|---|---|---|
| 0 | create_agreement | Landlord | Set terms: rent, deposit, grace period, late fee |
| 1 | accept_agreement | Tenant | Pay deposit + first month → status Active |
| 2 | pay_rent | Tenant | Monthly payment. Restores DRM unlock if late. |
| 3 | trigger_late | Anyone | After grace period. Locks DRM on property. |
| 4 | serve_notice | Landlord | Start eviction process. |
| 5 | vacate | Tenant/Landlord | End tenancy. Status → Terminated. |
| 6 | release_deposit | Tenant/Landlord | Release security deposit. |
Pending → Active → Late → EvictionProcess → Terminated → Completed
↑ ↓ (pay rent) ↓
└─────────┘ release_deposit
Cross-chain bridge for TRON USDC/USDT interoperability. Wrapped tokens on CoCo backed 1:1 by locked tokens on TRON. Relayer-based verification with replay protection.
| # | Extrinsic | Access | Description |
|---|---|---|---|
| 0 | register_asset | Root | Register bridged token (USDC/USDT) |
| 1 | deactivate_asset | Root | Stop new deposits |
| 2 | deposit | Relayer | Complete deposit (mint wrapped tokens) |
| 3 | withdraw | Any | Initiate withdrawal (burn wrapped tokens) |
| 4 | complete_withdrawal | Relayer | Confirm unlock on source chain |
| 5 | add_relayer | Root | Authorize relayer |
| 6 | remove_relayer | Root | Remove relayer |
| 7 | set_paused | Root | Emergency stop |
TRON → CoCo: User locks USDC/USDT on TRON
→ Relayer detects event
→ Calls bridge.deposit() on CoCo
→ Wrapped tokens minted to recipient
CoCo → TRON: User calls bridge.withdraw() on CoCo
→ Wrapped tokens burned
→ Relayer detects WithdrawalInitiated event
→ Calls unlock_tokens() on TRON contract
→ User receives native tokens on TRON
| Asset | TRON Address | CoCo ID | Decimals |
|---|---|---|---|
| USDC | TEkxiTehnzSmC2eVxARldVjSr9SkoN4ZzR | 0 | 6 |
| USDT | TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t | 1 | 6 |
scripts/bridge-relayer.jsTreasury-managed yield distribution to KYC-approved stakers. Implements the CoCo-K staking model where real-world asset yield (USDC from T-bills) is distributed proportionally.
| Extrinsic | Access | Description |
|---|---|---|
| set_treasury_manager | Root | Appoint treasury manager |
| remove_treasury_manager | Root | Remove treasury manager |
| activate_manager | Root | Reactivate manager |
| deactivate_manager | Root | Suspend manager |
| distribute_rewards | Manager | Distribute yield to KYC stakers |
| claim_rewards | Staker | Claim pending rewards |
| stake | KYC user | Stake CoCo-K tokens |
| unstake | Staker | Unstake tokens |
| set_distribution_schedule | Root | Configure interval/minimum |
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
On-chain voting with sub-coin vote tokens. Each election creates a vote token sub-coin via pallet-assets. Tokens minted to shareholders or citizens; casting a ballot burns 1 token. 9 extrinsics, 89 tests, FREE creation.
| # | Name | Access | Description |
|---|---|---|---|
| 0 | create_election | Signed | FREE — creates sub-coin + election. Supports auto_populate flag for group asset elections. |
| 1 | mint_vote_tokens | Sudo | Batch-mint vote tokens to recipients (max 100/batch) |
| 2 | buy_vote_tokens | Signed | Purchase vote tokens with COCO if token_price > 0 |
| 3 | cast_vote | Signed | Burn 1 token → record ballot (one per address) |
| 4 | close_election | Signed | Close after end_block passes |
| 5 | finalize_election | Sudo | Burn remaining supply, publish final tally |
| 6 | cancel_election | Sudo | Cancel active election, burn all tokens |
| 7 | register_candidate 🆕 | Signed | Self-nominate as candidate for a group asset election (requires ≥1 of the group asset) |
| 8 | withdraw_candidacy 🆕 | Signed | Remove self from candidate list |
| Type | Weight | Use Case |
|---|---|---|
| Democratic | 1 person = 1 vote | National elections, union votes, community referendums |
| Shareholder | Weighted by shares | Board elections, merger votes, dividend proposals |
| Referendum | 1 person = 1 vote | Yes/No proposals, constitutional amendments |
| Open | 1 person = 1 vote | General purpose, multi-option polls |
POST /api/voting/distribute-shares
Body: { electionId: 0, shareAssetId: 2000, seed: "//Alice" }
→ Auto-mints vote tokens proportional to share coin holdings
| Parameter | Value |
|---|---|
| VoteSessionPrice | 0 (FREE creation) |
| MaxOptions | 20 per election |
| MaxNameLen | 100 bytes |
| MaxOptionLen | 200 bytes |
| MaxMintPerBatch | 100 recipients |
| MaxCandidates | 20 per group asset |
Any asset holder (≥1 balance) can participate in group elections — perfect for unions, HOAs, DAOs, and national elections.
create_election — auto-fills ballot from GroupCandidatesPOST /api/voting/distribute-shares queries all share coin holders from the chain and auto-mints proportional vote tokens.
The voting pallet also powers the union system — worker organizations with on-chain membership, dues, and governance. Unions have their own sub-coin (asset_id = union_id + 2000), member registry, and treasury.
| # | Extrinsic | Access | Description |
|---|---|---|---|
| 9 | register_union | KYC user | Register union, creates sub-coin (asset_id = union_id + 2000) |
| 10 | join_union | Signed | Join union, mints 1 union coin |
| 11 | leave_union | Member | Leave union, burns 1 union coin |
| 12 | pay_dues | Member | COCO → union treasury |
| 13 | appoint_delegate | President | Designate union delegate |
| 14 | set_union_leadership | Root | Set elected officers |
| 15 | dissolve_union | Root | Emergency dissolve union |
| 16 | create_fast_union_usa | KYC user | One-click USA fast union: KYC + deposit + sub-coin + charter election |
| 17 | set_union_charter | President | Store ratified charter hash + URI on-chain |
17 Country Templates: US, GB, CA, FR, DE, ES, IT, SE, NO, JP, CL, MX, ZA, AU, AR, BR, UY. Each with legal metadata: min_workers, recognition_process, union_density, protection_rating.
Constant-product AMM (x*y=k) for sub-token trading. CoCo-K hub pools enable any sub-token to trade against the CoCo-K stable asset. Auto-registration creates hub pools on first swap. LP staking with fee rewards.
| # | Extrinsic | Access | Description |
|---|---|---|---|
| 0 | create_pool | Signed | Create a new swap pool (token_a, token_b) |
| 1 | add_liquidity | Signed | Add liquidity to pool, receive LP shares |
| 2 | remove_liquidity | Signed | Remove liquidity, burn LP shares |
| 3 | swap_exact_input | Signed | Swap exact input amount for minimum output |
| 4 | swap_exact_output | Signed | Swap for exact output amount with maximum input |
| 5 | set_pool_fee | Root | Set fee tier for a pool (default 0.25%) |
| Parameter | Value |
|---|---|
| Default fee | 0.25% |
| Minimum liquidity | 100 COCO-K |
| Hub asset | CoCo-K (stable asset, asset_id 0) |
Provides on-chain EUR/USD exchange rates for multi-currency checkout. Authorized oracles submit signed rate data with timestamps. Rates expire after a configurable period.
| # | Extrinsic | Access | Description |
|---|---|---|---|
| 0 | set_rate | Oracle | Submit EUR/USD rate with timestamp |
| 1 | add_oracle | Root | Authorize a new oracle provider |
| 2 | remove_oracle | Root | Remove an oracle provider |
get_rate() — Current EUR/USD rate (None if expired)convert(amount_eur) — Convert EUR amount to USDC at current ratePurchase order automation between companies. Create orders, mark shipped, mark delivered with auto-payment. Payment intents for supplier invoices.
| # | Extrinsic | Access | Description |
|---|---|---|---|
| 0 | create_order | Company | Create purchase order with items, total, supplier |
| 1 | mark_shipped | Supplier | Mark order as shipped with tracking |
| 2 | mark_delivered | Buyer | Confirm delivery — auto-pays supplier |
| 3 | cancel_order | Buyer | Cancel order before shipment |
| 4 | create_payment_intent | Buyer | Create payment intent for supplier invoice |
| 5 | complete_payment | Buyer | Complete payment on delivery |
| 6 | fail_payment | Buyer | Mark payment as failed |
Cross-merchant loyalty program system. Merchants create programs, users earn points on purchases, redeem for brand tokens. Referral system with 50 COCO payouts.
| # | Extrinsic | Access | Description |
|---|---|---|---|
| 0 | create_program | Merchant | Create loyalty program with earn rate and redemption options |
| 1 | earn_points | Signed | Earn points on purchase (merchant-signed) |
| 2 | redeem_points | Consumer | Redeem points for brand tokens or discounts |
| 3 | create_referral | Merchant | Generate referral code (50 COCO payout on signup) |
| 4 | submit_referral | New user | Submit referral code at registration |
| 5 | process_referral_payout | Merchant | Release 50 COCO referral bonus |
Time-locked escrow for transactions with mediator-based dispute resolution. Includes refund receipt system with VAT breakdown and CSV settlement reports.
| # | Extrinsic | Access | Description |
|---|---|---|---|
| 0 | create_escrow | Signed | Lock funds in time-bound escrow |
| 1 | flag_dispute | Buyer/Seller | Flag a dispute on an escrow |
| 2 | release_escrow | Mediator/Both | Release funds to agreed party |
| 3 | resolve_by_mediator | Mediator | Mediator resolves with split judgment |
| 4 | refund_after_timeout | Buyer | Auto-refund after escrow timeout |
| 5 | register_mediator | KYC user | Register as mediator with 10 COCO stake |
| 6 | slash_mediator | Root | Slash mediator stake for misconduct |
| 7 | issue_refund_receipt | Merchant | Issue tax-compliant refund receipt with VAT |
| 8 | claim_refund | Consumer | Claim refund against receipt |
Privacy-preserving stealth address system. Users register stealth meta-addresses and receive private payments. Sender generates one-time stealth addresses using Diffie-Hellman key exchange. Only the recipient can detect and claim outputs. Mixer removed May 2026 for regulatory compliance.
| # | Extrinsic | Access | Description |
|---|---|---|---|
| 0 | register_stealth_address | Signed | Register stealth meta-address (spending key + view key) |
| 1 | transfer_stealth | Signed | Send private payment to recipient's stealth address |
| 2 | claim_stealth_output | Recipient | Detect and claim incoming stealth payment |
| Name | Key | Value |
|---|---|---|
| StealthMetaAddresses | AccountId | StealthMetaAddress |
| StealthOutputs | u64 | StealthOutput |
| StealthOutputCounter | — | u64 |
| PalletBalance | — | Balance |
The Node.js server at barcode/Server/ provides REST API endpoints for both the POS system and blockchain operations.
| Method | Endpoint | Description |
|---|---|---|
| POST | /api/auth/login | Username + password → JWT token |
| POST | /api/auth/register | Create new user (admin required) |
| GET | /api/auth/me | Get current user from token |
| POST | /api/auth/change-password | Change password |
| POST | /api/auth/logout | Logout (stateless, logs event) |
| GET | /api/items | List inventory items |
| POST | /api/items | Add inventory item |
| GET | /api/transactions | List POS transactions |
| Endpoint | Blockchain Call | Key Parameters |
|---|---|---|
| /kyc | kyc.approveAddress | address |
| /register | productNft.registerCompany | name, seed |
| /asset | assets.create + setMetadata | assetId, name, symbol, seed |
| /mint | productNft.mintProduct | gtin, serialNumber, batchId, name, category, seed |
| /mint-batch | productNft.batchMintProducts | gtin, batchId, name, category, quantity, seed |
| /transfer | productNft.transfer | productId, toAddress, newStatus, lat, lng, desc, action, seed |
| /sale | productNft.sellToConsumer | productId, consumerAddress, price, warrantyDuration, lat, lng, desc, seed |
| /authenticate | productNft.authenticateProduct | productId, seed |
| /recall | productNft.recallProduct | productId, reason, action, seed |
| /resolve-recall | productNft.resolveRecall | productId, seed |
| /register-product | productNft.registerProduct | productId, seed |
| /warranty-claim | productNft.submitWarrantyClaim | productId, description, seed |
| /resolve-claim | productNft.resolveWarrantyClaim | productId, claimIndex, resolution, seed |
| /list-for-sale | productNft.listForSale | productId, price, royaltyPercent, seed |
| /buy-listing | productNft.buyListing | productId, lat, lng, desc, seed |
| /cancel-listing | productNft.cancelListing | productId, seed |
| /set-drm 🆕 | productNft.setDrmConfig | productId, enforcementType, paymentTokenId, seed |
| /lock 🆕 | productNft.lockProduct | productId, reason, seed |
| /unlock 🆕 | productNft.unlockProduct | productId, seed |
| /unlock-feature 🆕 | productNft.unlockFeature | productId, featureId, durationBlocks, seed |
| /lock-feature 🆕 | productNft.lockFeature | productId, featureId, seed |
| /repossess 🆕 | productNft.repossessProduct | productId, seed |
| /burn-drm 🆕 | productNft.burnDrm | productId, seed |
| /emergency-override 🆕 | productNft.emergencyDrmOverride | productId, seed |
| Endpoint | Blockchain Call | Access |
|---|---|---|
| /api/bridge/register-asset | bridge.registerAsset | Root |
| /api/bridge/deactivate-asset | bridge.deactivateAsset | Root |
| /api/bridge/deposit | bridge.deposit | Relayer |
| /api/bridge/withdraw | bridge.withdraw | Any |
| /api/bridge/complete-withdrawal | bridge.completeWithdrawal | Relayer |
| /api/bridge/add-relayer | bridge.addRelayer | Root |
| /api/bridge/remove-relayer | bridge.removeRelayer | Root |
| /api/bridge/set-paused | bridge.setPaused | Root |
| Endpoint | Blockchain Call | Description |
|---|---|---|
| /api/swap/create-pool | swap.createPool | Create new AMM pool |
| /api/swap/add-liquidity | swap.addLiquidity | Add liquidity, get LP shares |
| /api/swap/remove-liquidity | swap.removeLiquidity | Remove liquidity, burn LP shares |
| /api/swap/swap-exact-input | swap.swapExactInput | Swap exact input for min output |
| /api/swap/swap-exact-output | swap.swapExactOutput | Swap for exact output with max input |
| /api/swap/pools | query | List all swap pools |
| /api/swap/pool/:id | query | Get pool details and reserves |
| Endpoint | Blockchain Call | Description |
|---|---|---|
| /api/oracle/set-rate | oracle.setRate | Submit EUR/USD rate (oracle only) |
| /api/oracle/get-rate | query | Get current EUR/USD rate |
| /api/oracle/convert | oracle.convert | Convert EUR amount to USDC |
| Endpoint | Blockchain Call | Description |
|---|---|---|
| /api/supply-chain/create-order | supplyChain.createOrder | Create purchase order |
| /api/supply-chain/mark-shipped | supplyChain.markShipped | Mark order shipped |
| /api/supply-chain/mark-delivered | supplyChain.markDelivered | Confirm delivery, auto-pay |
| /api/supply-chain/payment-intent | supplyChain.createPaymentIntent | Create supplier payment intent |
| /api/supply-chain/get-order/:id | query | Get order details |
| Endpoint | Blockchain Call | Description |
|---|---|---|
| /api/loyalty/create-program | loyalty.createProgram | Create loyalty program |
| /api/loyalty/earn | loyalty.earnPoints | Earn points on purchase |
| /api/loyalty/redeem | loyalty.redeemPoints | Redeem points for rewards |
| /api/loyalty/create-referral | loyalty.createReferral | Generate referral code |
| Endpoint | Blockchain Call | Description |
|---|---|---|
| /api/dispute/create-escrow | dispute.createEscrow | Lock funds in escrow |
| /api/dispute/flag | dispute.flagDispute | Flag a dispute |
| /api/dispute/resolve | dispute.resolveByMediator | Mediator resolves dispute |
| /api/dispute/release | dispute.releaseEscrow | Release escrowed funds |
| /api/dispute/refund-receipt | dispute.issueRefundReceipt | Issue VAT-compliant refund receipt |
| /api/dispute/claim-refund | dispute.claimRefund | Claim refund against receipt |
| /api/dispute/receipt | server | Generate QR receipt with VAT breakdown |
| /api/dispute/report/:address | server | Daily CSV settlement report |
| Endpoint | Blockchain Call | Description |
|---|---|---|
| /api/rental/create | rental.createAgreement | Create lease agreement |
| /api/rental/accept | rental.acceptAgreement | Accept and pay deposit |
| /api/rental/pay-rent | rental.payRent | Pay monthly rent |
| /api/rental/trigger-late | rental.triggerLate | Trigger late payment, lock DRM |
| /api/rental/serve-notice | rental.serveNotice | Start eviction process |
| /api/rental/vacate | rental.vacate | End tenancy |
| /api/rental/release-deposit | rental.releaseDeposit | Release security deposit |
| Endpoint | Description |
|---|---|
| /api/pos/scan | Scan barcode, resolve via DNS or chain |
| /api/pos/checkout | One-click checkout with CoCo-K payment |
| /api/pos/offline-queue | Queue offline transactions |
| /api/pos/offline-sync | Sync queued transactions to chain |
| /api/pos/savings | Calculate savings vs Visa/MC |
| /api/pos/receipt | Generate POS receipt with TVA |
| Endpoint | Description |
|---|---|
| /api/checkout/checkout | Multi-currency checkout via oracle + swap |
| /api/checkout/round-up | Round up to nearest unit for savings |
| /api/checkout/b2b-settle | B2B invoice auto-settlement |
| /api/checkout/savings-report | Savings report vs traditional payments |
| Endpoint | Description |
|---|---|
| /api/union/templates | Get 17 country legal templates |
| /api/union/create-fast | Create USA fast union |
| /api/union/join | Join union, mint 1 union coin |
| /api/union/leave | Leave union, burn 1 union coin |
| /api/union/pay-dues | Pay COCO dues to union treasury |
| /api/union/states | Get 50 states + DC union data |
| /api/union/:id/status | Get union stats and recognition status |
| /api/union/:id/recognition | Get NLRB petition and demand letter |
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.
| Route | File | Description |
|---|---|---|
| / | index.html | Home — hero, features, fee comparison |
| /wallet | wallet.html | Web wallet — BIP39, send, receive, portfolio |
| /explorer | explorer.html | Block explorer — stats, blocks, extrinsics, accounts |
| /dashboard | dashboard.html | Merchant dashboard — stats, coins, KYC, activity |
| /create-coin | create-coin.html | One-click sub-coin creation wizard |
| /login | login.html | Sign in / Sign up with Google OAuth |
| /kyc | kyc.html | KYC document upload (ID + selfie) |
| /admin-kyc | admin-kyc.html | Admin KYC review queue |
| /union-now | union-now.html | Unionize hub with 50-state guide |
| /union-coin | union-coin.html | Privacy-shielded worker organizing |
| /voting | vote/elections.html | On-chain voting guide |
| /privacy | privacy-page.html | Stealth addresses and privacy features |
| /launch-guide | launch-guide.html | Launch and deployment guide |
| /docs | README.html | Full documentation (this page) |
// 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
Full-featured web wallet with BIP39 mnemonic generation, send/receive, portfolio view, and transaction history.
Chain explorer with real-time stats, block details, extrinsics, account balances, and search.
Login/Register page with JWT-based authentication, Google OAuth, TOTP 2FA, and KYC document upload.
Full-featured admin panel for companies to manage their CoCo operations.
Features:
Product inventory with search/filter · Single & batch minting · Supply chain transfers · Retail sales · Recall management · Warranty claim resolution · Product authentication · Company settings
Worker organizing hub with 50-state guide, geolocation, NLRB contacts, and privacy-shielded union formation.
On-chain voting guide covering democratic, shareholder, referendum, and union elections with sub-coin vote tokens.
Stealth address documentation with Diffie-Hellman key exchange privacy and legal compliance notices.
Guide for integrating the Android barcode scanner app with the CoCo blockchain (wallet management, on-chain queries, transaction signing).
Command-line tool for common operations: build, run node, test, check, start server, reset chain data, generate spec, build Docker.
./coco-substrate/scripts/admin.sh build ./coco-substrate/scripts/admin.sh run ./coco-substrate/scripts/admin.sh test nft
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.
coco://product/{chain_id}/{product_id}?gtin={gtin}&serial={serial}&sig={signature}
coco://product/0/0x00000000000000000000000000000001?gtin=00012345678905&serial=LV-2024-001234
| Type | Use | Signature |
|---|---|---|
| Static QR | Printed on packaging, permanent | No (lookup only) |
| Dynamic QR | App-generated at POS/transfer | ECDSA signature from owner |
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
UPC-A, UPC-E, EAN-13, EAN-8, Code 128, Code 39, Code 93, QR, Data Matrix, PDF417, Aztec, ITF, Codabar
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)
beta_instructions.md. This section covers building, configuring, and running the CoCo node.
| Component | Development | Testnet Validator |
|---|---|---|
| CPU | 2 vCPU | 4 vCPU |
| RAM | 4 GB | 8 GB |
| Storage | 20 GB | 100 GB SSD |
| OS | Linux / macOS / WSL2 | Ubuntu 22.04+ |
# Rust toolchain (must be 1.88.0 — pinned in rust-toolchain.toml) 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 20+ (for server/relayer) curl -fsSL https://deb.nodesource.com/setup_20.x | bash - apt install nodejs # core2 patch (yanked from crates.io — must apply locally) # See /tmp/core2-patch/core2-0.4.0/ # Verify rustc --version # ≥ 1.88 node --version # ≥ 20
cd coco-substrate # Release build (recommended — 30-60 min) ./scripts/build.sh # Or manually (use scripts/build.sh which applies core2 patch): cargo build --release -p coco-substrate # Binary at: ./target/release/coco-node (73MB) ./target/release/coco-node --version
# Quick start ./scripts/run-dev.sh # Or manual (MUST use --pool-type single-state for polkadot-stable2603-1): ./target/release/coco-node --dev \ --base-path /tmp/coco-dev \ --rpc-port 9933 \ --unsafe-rpc-external \ --pool-type single-state \ --no-prometheus # RPC: http://127.0.0.1:9933 | WS: ws://127.0.0.1:9944 # Connect: https://polkadot.js.org/apps → Development → Local Node
# 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 (MUST use --pool-type single-state) ./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 \ --pool-type single-state # Ports: 30333 (P2P), 9933 (RPC), 9944 (WS), 9615 (metrics) # See beta_instructions.md for multi-validator testnet setup
# Auth server (MariaDB + JWT + Google OAuth) cd website npm install cp .env.example .env # Edit DB creds, JWT secret, Google OAuth keys npm start # http://localhost:4000 # POS + blockchain proxy server cd barcode/Server npm install cp .env.example .env # Edit SUBSTRATE_URL npm start # http://localhost:3000
# 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 # Standalone multi-coin wallet app (wallet-app/) # BTC, ETH, SOL, USDC, USDT + COCO with BIP44 HD derivation # Build: cd wallet-app && ./gradlew assembleDebug # APK: 13MB, package com.companycoin.wallet # Features: biometric auth, portfolio, AES-256-GCM key storage # Barcode POS Android wallet # Build: cd barcode && ./gradlew assembleDebug # APK: app/build/outputs/apk/debug/app-debug.apk
# Environment
export COCO_WS_URL=ws://127.0.0.1:9944
export COCO_RELAYER_SEED=//RelayerRelayer
# Start relayer (TRON only)
node scripts/bridge-relayer.js --tron
# Register bridged assets (as root)
curl -X POST http://localhost:3000/api/bridge/register-asset \
-H "Content-Type: application/json" \
-d '{
"sourceChain":"TRON",
"sourceTokenAddress":"TEkxiTehnzSmC2eVxARldVjSr9SkoN4ZzR",
"name":"USD Coin","symbol":"USDC","decimals":6,
"seed":"//Alice"
}'
CoCo uses MariaDB for user accounts with free TOTP two-factor authentication — no SMS costs, no API fees. Users scan a QR code with Google Authenticator or Authy:
| Method | Endpoint | Description |
|---|---|---|
| POST | /api/auth/register | Create account (email + password) |
| POST | /api/auth/login | Sign in — returns partial token if 2FA enabled |
| POST | /api/auth/login-totp | Complete 2FA login with authenticator code |
| POST | /api/auth/totp/setup | Generate secret + QR code + 8 backup codes |
| POST | /api/auth/totp/enable | Verify setup code → enable 2FA |
| GET | /api/auth/me | Get current user profile + KYC status |
CoCo validators earn from every transaction. No PoW hardware. No 32 ETH stake. Just run a node and earn.
| Transaction | Fee | To Validators | To Treasury |
|---|---|---|---|
| POS settlement (retail) | 0.25% | 80% | 20% |
| Sub-token swap (CoCo-K hub) | 0.25% | 70% | 30% |
| Sub-token swap (peer-to-peer) | 0% | — | — |
| Product minting | 0.1% | 50% | 50% |
| COCO native transfers | Gas only | 100% | 0% |
| Governance (coin create, KYC) | Gas only | 100% | 0% |
| Daily Network Volume | Per-Validator/Day (10 nodes) | Annual |
|---|---|---|
| $100,000 | $200 | $73,000 |
| $1,000,000 | $2,000 | $730,000 |
| $10,000,000 (Visa-scale) | $20,000 | $7,300,000 |
Any merchant can run a validator. Hardware cost: ~$100/month VPS. Actively profitable at $300+ daily network volume. Merchants earn fees FROM their own transactions — the network pays THEM to participate.
A database handles one company's data. CoCo handles what no database can: trust between companies. When manufacturer, distributor, retailer, and consumer each run their own systems, reconciliations take days — if they happen at all. Chargebacks, disputes, and counterfeit goods thrive in the gaps between databases. CoCo eliminates those gaps with one shared, immutable truth that every party trusts because no single party controls it.
Manufacturer, distributor, retailer, and consumer never share a database. Each has their own systems. Reconciliations take days. CoCo eliminates reconciliation — one shared truth trusted by all.
A QR code can be copied from a fake Gucci bag. An on-chain authenticity record signed by the manufacturer cannot be forged. Scan to verify cryptographically — impossible with any database.
Supplier delivers → QR scan at receiving dock → inventory auto-updates → payment auto-settles at 0% internal fee. No invoice. No wire. No 3-day wait. No database can settle across company boundaries in 6 seconds.
French tax authorities require 10-year inventory audits. A database can be modified. A blockchain cannot. CoCo gives you append-only records with cryptographic proof — not a database you can edit and call "audited."
Merchants run their own node and earn fees from their own transactions. No SaaS subscription. No platform lock-in. A database is a cost center. CoCo is a profit center that pays you to participate.
A customer scanning a QR code on their phone sees the full product history — origin, manufacturer, recalls, authenticity. A private database cannot share this across companies. CoCo makes it public, verifiable, and free.
CoCo is not a database replacement — it's a database upgrade. Your internal records stay in Postgres, SQLite, or whatever you use. CoCo adds the layer that databases were never built for: trust between parties that don't trust each other. Ownership. Authenticity. Custody. Settlement. A database can store facts. CoCo stores provable facts.
CoCo offers two POS versions for different needs:
Standalone, zero dependencies. Works on any browser — including old Android phones. Cash, card, and bank transfer payments. Offline-first with localStorage.
Perfect for: Brazilian kiosks, French butchers, any merchant with just a phone.
Chain-connected via API bridge. Accept CoCo-K payments. Wallet balance display. Mining validator integration. Settle on-chain at 0.25% fee. Earn fees by running the miner.
Perfect for: Merchants who want to earn from their own transactions.
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
./scripts/run-dev.sh # Or: ./target/release/coco-node --dev --base-path /tmp/coco-dev \ # --rpc-port 9933 --unsafe-rpc-external \ # --pool-type single-state --no-prometheus # RPC: http://127.0.0.1:9933 | WS: ws://127.0.0.1:9944 # Connect: https://polkadot.js.org/apps → Development → Local Node
# Product NFT pallet (45 tests) cargo test -p pallet-product-nft # All pallets: cargo test -p pallet-voting # 66 tests (union + elections) cargo test -p pallet-bridge # 31 tests cargo test -p pallet-rental # 25 tests cargo test -p pallet-loyalty # 23 tests cargo test -p pallet-dispute # 21 tests cargo test -p pallet-oracle # 20 tests cargo test -p pallet-shielded-coin # 20 tests cargo test -p pallet-supply-chain # 19 tests cargo test -p pallet-swap # 21 tests cargo test -p pallet-micro-finance # 16 tests cargo test -p pallet-kyc # 14 tests cargo test -p pallet-rewards # ~15 tests
# Auth server (MariaDB) cd website npm install cp .env.example .env # Edit DB, JWT, OAuth config npm start # http://localhost:4000 # POS + blockchain proxy cd barcode/Server npm install cp .env.example .env # Edit SUBSTRATE_URL if needed npm start # http://localhost:3000
cd barcode ./gradlew assembleDebug # APK: app/build/outputs/apk/debug/app-debug.apk
target/release/coco-node.
SDK upgraded to polkadot-stable2603-1 with Rust 1.88.0.
The company onboarding process is a 6-step flow documented in ONBOARDING.md and implemented in the website at /onboarding.html.
| Step | Blockchain Action | Who |
|---|---|---|
| 1. KYC Approval | kyc.approveAddress | Provider (Alice in demo) |
| 2. Register Company | productNft.registerCompany | KYC-approved user |
| 3. Create Asset | assets.create + setMetadata | Company |
| 4. Mint Products | productNft.mintProduct / batchMintProducts | Company |
| 5. Supply Chain Transfer | productNft.transfer | Current owner |
| 6. Retail Sale | productNft.sellToConsumer | Retailer |
| Action | Blockchain Call | When |
|---|---|---|
| Register product | productNft.registerProduct | After purchase |
| Authenticate product | productNft.authenticateProduct | Manufacturer only |
| Submit warranty claim | productNft.submitWarrantyClaim | Within warranty period |
| List for resale | productNft.listForSale | Owner wants to sell |
| Buy from marketplace | productNft.buyListing | Any user |
| Cancel listing | productNft.cancelListing | Original seller |
| Parameter | Value | Notes |
|---|---|---|
| Block Time | 6 seconds | Aura slot duration |
| Finality | ~12-18 seconds | Grandpa 2/3+ confirmation |
| Native Token | COCO | 12 decimal places |
| Total Supply | 1,000,000,000 | Pre-mined at genesis |
| Existential Deposit | 500 plancks | Minimum balance |
| Max Validators | 32 | Aura authorities |
| Max KYC Providers | 100 | Configurable |
| Max Stakers | 100,000 | CoCo-K stakers |
set_fee_config (sudo). Default rates shown below.
| Transaction | Fee | Recipient | Status |
|---|---|---|---|
| Supply chain transfer | 0% | Free | Live |
| Product minting | 0.1% (configurable) | Treasury | Live |
| Retail sale | 0.25% (configurable) | Treasury | Live |
| P2P resale | 0.25% (configurable) | Treasury | Live |
| COCO transfer | Network fee | Validators | Live |
| Sub-token swap (same brand) | 0% | Free | Planned |
| Sub-token to COCO | 0.25% | Treasury | Planned |
// 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.
| Name | Role | Address | COCO |
|---|---|---|---|
| Alice | Sudo / Validator | 5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY | 1,152.9 |
| Bob | Validator / KYC Provider | 5FHneW46xGXgs5mUiveU4sbTyGBzmstUspZC92UhjJM694ty | 1,152.9 |
| Charlie | User / Staker | 5FLSigC9HGRKVhB9FiEo4Y3koPsNmBmLJbpXg2mp1hXcS59Y | 1,152.9 |
| Dave | User | 5DAAnrj7VHTznn2AWBemMuyBwZWs6FNFjdyVXUeYum3PTXFy | 1,152.9 |
| Eve | User | 5HGjWAe3PDDVWTJNQ3dvkRJEiPDpMC8Dcpg4KoUF3ipqCDRa | 1,152.9 |
| Ferdie | User | 5CiPPseXPECbkjWCa6MnjNokrgYjMqmKndv2rSnekmSK2DjL | 1,152.9 |
Done New Pending Planned
/dashboard/marketplacescripts/admin.sh with 9 commandsdocs/SCANNER_INTEGRATION.md| Metric | Target |
|---|---|
| Brands onboarded | 50 |
| Products tokenized | 500M |
| Active consumers | 10M |
| Resale volume | $100M |
| Microtransaction volume | $10M |
| DRM-enabled products | 100K |
| Network revenue | $90M |