CoCoX Documentation

Contents

Overview & Architecture

CoCoX is a distributed on-chain research platform. Anyone can mint structured data tables (Data Coins) and executable R research contracts (Analysis Coins) that run natively on-chain via offchain workers. No external R dependency — all statistical functions are pure Rust.

SCRAPERS (standalone Node.js)         WEB UI (cocox/*.html)
  FRED BLS Census IMF World           Data Wallet | Coin IDE | Data Explorer
  Canada Asia DeFi                        │
     │                                    │
     ▼ mint_data_coin                     ▼ /api/cocox-v2/*
┌────────────────────────────────────────────────────────────┐
│                   SUBSTRATE CHAIN (pallet-analysis)         │
│                                                            │
│  ┌─ DATA COINS ───────────────────────────────────────┐   │
│  │  Columns(coin, col, chunk) → Vec<DataValue>         │   │
│  │  Per-column, 1024 rows/chunk                        │   │
│  │  ReadOnly | AppendOnly | Derived(sql_expr)          │   │
│  └────────────────────────────────────────────────────┘   │
│                                                            │
│  ┌─ ANALYSIS COINS ───────────────────────────────────┐   │
│  │  r_script + steps: Vec<ComputeStep>                 │   │
│  │  state: Pending → Solving → Solved → Verified       │   │
│  │  StepResults(coin, step) → bytes                    │   │
│  └─────────────┬──────────────────────────────────────┘   │
│                │                                          │
│  ┌─ OFFCHAIN WORKER (per block) ──────────────────────┐   │
│  │  DataFetch step  → sql::execute_query()             │   │
│  │  NativeFn step   → native_r::execute_native()       │   │
│  │  submit_step(signed) → StepResults storage           │   │
│  └────────────────────────────────────────────────────┘   │
│                                                            │
│  ┌─ NATIVE R ─────────────────────────────────────────┐   │
│  │  lm | glm | t.test | cor.test | chisq.test          │   │
│  │  benford | arima | garch | pca | johansen | var     │   │
│  │  sharpe | beta | maxdrawdown | sortino | calmar     │   │
│  │  summary | predict                                   │   │
│  └────────────────────────────────────────────────────┘   │
└────────────────────────────────────────────────────────────┘

Data Coins

Data Coins are on-chain structured tables with per-column chunked storage. Each coin has a declared schema, a provenance source, and a read/write mode. They are public — any Analysis Coin can reference any Data Coin.

Data Types

Coin Modes

Metadata Fields

Chunked Column Storage

Each column is stored in chunks of 1024 values. A Data Coin with 1M rows per column = 1000 chunks, ~8 MB per Float column. Scales from 300 rows (FRED quarterly) to millions. Configurable via MaxChunks constant (default 10,000 = 10M rows).

Extrinsics

Data Coin Reference — Find, Query & Use

How Coins Are Minted

Automated scrapers run every 30 minutes against public economic APIs. Each observation is appended to an on-chain Data Coin:

1. FRED scraper fetches latest GDP, CPI, UNRATE etc. from api.stlouisfed.org
2. EU scraper fetches ECB rates, Eurostat GDP, World Bank indicators
3. Asia scraper fetches RBI (India), ABS (Australia), PBoC (China), etc.
   ↓
ensureCoin("GDP"): scan chain for source=FredSeries("GDP") → cache coinId
appendRows(coinId, [[Int:timestamp, Float:value]]) → appended to chain
   ↓
If coin doesn't exist yet, mintDataCoin creates it with metadata:
  category=GDP | frequency=Quarterly | geography=US | source=FredSeries("GDP")

Current On-Chain Coins

Data coins are active on-chain. Full list at Data Explorer.

How the Ecosystem Works

Data Coins live on-chain and can be referenced by any Analysis Coin, SQL query, or R script running within the platform. They don't need to be downloaded or exported — you work with them directly inside the Coin IDE.

  Scrapers pull economic data every 30 min
       ↓
  Data Coins store it on-chain (columnar, 1024 rows/chunk)
       ↓
  Analysis Coins reference Data Coins by ID or alias
       ↓
  R scripts run inside the chain (native Rust, no external R)
       ↓
  Results stored as Analysis Coin step outputs

Finding & Referencing Coins

Every coin has a numeric ID and a source name. In the Data Explorer, browse the catalog to find coins. In the Coin IDE, reference them by ID with an alias:

# In the Coin IDE, declare inputs like:
#   Coin #33 → alias "gdp"
#   Coin #35 → alias "unemp"
#   Coin #45 → alias "rates"
#   Coin #44 → alias "housing"

# Quick lookup in the explorer:
#   Open /cocox/data-explorer.html?coin=33
#   Browse full catalog at /cocox/data-explorer.html
#   Reference snippets shown in the Coin view tab

Query Syntax — SQL & R Side by Side

Both SQL and R run natively on-chain. Use whichever fits your analysis.

-- Last 10 GDP rows
SELECT * FROM coin[33]
ORDER BY date DESC LIMIT 10

-- Unemployment over 5%
SELECT date, value
FROM coin[35] WHERE value > 5

-- GDP + Unemployment joined
SELECT a.date,
  a.value AS gdp,
  b.value AS unemp
FROM coin[33] a
JOIN coin[35] b
  ON a.date = b.date

-- Average 10-year yield
SELECT AVG(value)
FROM coin[45]

# Alias: coin #33 → "gdp"

# Linear model
lm(gdp$value ~ unemp$value)

# Summary
summary(unemp)

# T-test
t.test(gdp$value, mu = 20000)

# Correlation
cor.test(gdp$value, unemp$value)

# Benford's law
benford(rates$value)

# ARIMA forecast
arima(housing$value, c(1,1,1))

# Beta between assets
beta(rates$value, sp500$value)

Real Analysis Workflows

# In Coin IDE: set coins #33→"gdp", #35→"unemp"
model <- lm(gdp$value ~ unemp$value, data = merge(gdp, unemp, by = "date"))
summary(model)
# Output: R², coefficients, p-values — stored as Analysis Coin step result

# In Coin IDE: set coin #45→"rates"
result <- benford(rates$value)
# Output: χ², p-value. p < 0.05 suggests abnormal digit distribution.

# In Coin IDE: set coin #44→"housing"
fit <- arima(housing$value, order = c(1,1,1))
# Output: coefficients, AIC, BIC, fitted values.

-- In the coin creator, set mode = Derived with this SQL:
SELECT a.date, a.value / b.value AS real_gdp
FROM coin[33] a
JOIN coin[36] b ON a.date = b.date
-- This creates a new coin that updates automatically

Coin ID Reference for Common Series

Analysis Coins

Analysis Coins are executable R research contracts. Each coin contains an R script, input Data Coin references, and a directed acyclic graph of computation steps that execute against on-chain data.

Lifecycle

1. MINT: User submits R script + parsed steps → AnalysisCoins(id) storage
2. SOLVING: OCW picks up steps with dependencies met → dispatches execution
3. REMINT: Each step result advances coin state — coin persists, state updates
4. SOLVED: All steps complete → coin.state = Solved
5. VERIFIED: Challenge window passes (2 blocks for testnet)

Step Types

DAG Validation at Mint

The step graph must be a valid DAG: no cycles, no self-references, dependencies precede dependents. Rejected at mint time if invalid. Steps must have ascending step_id with dependencies pointing to lower IDs.

Step Input Types

Extrinsics

SQL Engine

Native Rust SQL parser. No external libraries. Deterministic at a given block height — same query at same block always produces the same result. Columnar storage access: reads Columns(coin_id, col_idx, chunk_idx) storage maps directly.

Syntax

SELECT col1, col2, AGG(col3) FROM coin[N] [AS alias]
  [JOIN coin[M] ON a.col_i = b.col_j]
  [WHERE col OP value [AND|OR ...]]
  [GROUP BY col]
  [ORDER BY col ASC|DESC]
  [LIMIT n]

Aggregation Functions

SUM(col) AVG(col) COUNT(col) COUNT(*) MAX(col) MIN(col)

WHERE Operators

= == != <> < > <= >= LIKE

Native R Library

All statistical functions are pure Rust — zero external R dependency. Compiled into the pallet binary. Deterministic: same input bytes always produce the same output bytes. 20 functions across 6 categories.

Regression

Statistical Tests

Time Series

Risk Metrics

Multivariate

Utility

Data Sources & Scrapers

9 standalone Node.js scripts that fetch data and mint it as Data Coins on the chain. All run independently — no server integration needed.

Scraper Catalog

OCW Execution

Offchain workers run on each validator node. They dispatch Analysis Coin steps every block.

dispatch_analysis_steps(block_number):
  For each AnalysisCoin in Pending or Solving:
    For each step with dependencies met:
      if DataFetch(query):
        → parse "coin[N]" from SQL
        → read Columns(N, col, chunk) across all chunks
        → zip columns into rows → encode as typed binary
        → submit_step(signed) → StepResults storage
      if NativeFunction(fn):
        → read input data from StepResults or Data Coins
        → execute pure Rust function via native_r::execute_native()
        → submit_step(signed) → StepResults storage
      If all steps now solved:
        → coin.state = Solved

Determinism Guarantees

• All inputs read from on-chain storage at the current block height
• Native functions are pure Rust — no I/O, no randomness, no external processes
• Same input bytes → same output bytes every time
• GLM IRLS runs to fixed 25 iterations (no early convergence)
• PCA uses deterministic power iteration (no randomized SVD)
• ARIMA uses zero-initialized residuals (no random seed)
• GARCH runs fixed 100 MLE iterations (deterministic gradient descent)

API Reference

V2 Endpoints /api/cocox-v2/

V1 Endpoints /api/cocox/

V2 Curl Examples

# List all Data Coins
curl https://cocoio.cc/api/cocox-v2/coins/list
# → {"success":true,"data":{"coins":[{"coinId":0,"name":"x","rows":10}],"total":3}}

# Get coin detail
curl https://cocoio.cc/api/cocox-v2/coins/0
# → {"success":true,"data":{"coinId":0,"schema":[{"name":"x","dataType":"Float(0)"}],"rows":10}}

# Get paginated rows
curl "https://cocoio.cc/api/cocox-v2/coins/0/rows?from=0&to=5"

# Run SQL query
curl -X POST https://cocoio.cc/api/cocox-v2/coins/0/query \
  -H "Content-Type: application/json" \
  -d '{"query":"SELECT x, y FROM coin[0] WHERE x > 5 ORDER BY y DESC"}'

# View wallet
curl https://cocoio.cc/api/cocox-v2/wallet/5GrwvaEF5zXb...

# Parse R script
curl -X POST https://cocoio.cc/api/cocox-v2/parse-r \
  -H "Content-Type: application/json" \
  -d '{"script":"model <- lm(y ~ x, data = d)","refs":[{"coinId":0,"alias":"d"}]}'

Web UI

Tutorial: Running R Analytics on CoCoX

This tutorial walks through the full workflow: get data → explore it → create an analysis coin → submit steps → read and interpret results.

Prerequisites

cd coco-substrate && cargo build --release
./target/release/coco-node --dev --base-path=/tmp/coco-dev \
  --rpc-port=9933 --unsafe-rpc-external --pool-type single-state \
  --enable-offchain-indexing true --no-prometheus

1. Get Data

export FRED_API_KEY=your_key
cd scripts
node fred-scraper.js preview   # View data, no writes
node fred-scraper.js update    # Mint Data Coins on chain

2. Explore Data

Go to Data Explorer, enter Coin ID 0. Browse rows, run SQL, see chart.

curl https://cocoio.cc/api/cocox-v2/coins/0
curl "https://cocoio.cc/api/cocox-v2/coins/0/rows?from=0&to=20"

3. Create an Analysis Coin

Go to Coin IDE → Analysis Coin tab. Write:

model <- lm(y ~ x, data = mydata)
summary(model)

Add input coin (ID 0, alias "mydata"). Click "Parse & Preview Steps" to see the DAG. Click "Mint".

4. Submit Step Results & Read Output

Submit step results via the test script or Coin IDE. Then check your wallet:

curl https://cocoio.cc/api/cocox-v2/wallet/5GrwvaEF5zXb...
# → { "analysisCoins": [{ "coinId": 0, "state": "Solved", "steps": 2, "solved": 2 }] }

The LM result bytes encode: coefficients, SE, t-stats, p-values, R², F-statistic, and residuals. See the function catalog above for exact byte layouts.

5. Interpret Results

6 Worked Examples

# R: model <- lm(y ~ x1 + x2, data = mydata)
# Input: y column + 1+ x columns
# Output: coefs, SE, t, p, R², F, residuals
# Use: Predicting GDP from unemployment + inflation

# R: result <- t.test(returns, mu = 0)
# Input: 1 numeric column, Output: mean, t, df, p, SE
# Use: Testing if average returns differ from zero

# R: result <- benford(amounts)
# Input: 1 numeric column, Output: χ², p, obs/exp counts per digit
# Use: Forensic accounting — p < 0.05 suggests manipulation

# R: result <- cor.test(x, y, method = "pearson")
# Input: 2 numeric columns, Output: r, t, df, p
# Use: Checking if two assets move together

# R: model <- glm(recession ~ spread + unemployment, data = macro)
# Input: 0/1 outcome + predictors, Output: logit coefs, deviance
# Use: Predicting binary events like recession probability

# R: fit <- garch(returns)
# Input: time series (≥30 obs), Output: ω, α, β, AIC, BIC, fitted vol
# Use: Modeling volatility clustering. Backbone of risk management

Deployment

Deploy package at DEPLOY_PACKAGE/ contains everything needed to run a CoCo node with scrapers.

# Quick deploy
unzip DEPLOY_PACKAGE.zip -d /opt/coco
cd /opt/coco
cp systemd/*.service /etc/systemd/system/
cp .env.template .env   # Fill in API keys
systemctl daemon-reload
systemctl enable coco-node coco-scraper-scheduler
systemctl start coco-node
sleep 30
systemctl start coco-scraper-scheduler

# Health check
curl localhost:9933 -d '{"method":"system_health"}'
node scripts/fred-scraper.js preview

Required keys listed in NEED_KEYS. Free API keys from FRED, BLS, Census, IMF.

Troubleshooting