Zero Network Documentation

Technical reference for the Zero micropayment blockchain -- purpose-built for AI agents, machines, and the protocols that connect them.

Every transaction on Zero costs a flat 0.01 Z ($0.0001 USD). The token is backed 1:1 by stablecoins locked in auditable bridge vault contracts. There is no speculative float, no inflationary emission schedule, no governance token. Zero exists to move money -- small amounts, very fast, between machines.

The network is implemented in Rust from scratch (not a fork), using a block-lattice account model inspired by Nano, with a leaderless DAG-based asynchronous BFT consensus layer inspired by Mysticeti and Lachesis. The result is a system that achieves deterministic finality in milliseconds, stores only the latest state (not unbounded history), and fits a complete transaction into 136 bytes.

Why Zero Exists

Existing payment rails fail the machine economy in several ways:

• Credit cards have minimum charges, require human identity, and take days to settle.
• Ethereum and L2s are too expensive for sub-cent payments. Even at $0.001 per transaction, the gas cost exceeds the payment amount for a 1-cent API call.
• Solana and fast L1s have variable fees and are optimized for DeFi, not for deterministic micropayment workloads.
• Lightning Network requires channel management and online receivers -- impractical for ephemeral AI agents.
• Stablecoins on L2s still require bridging, nonce management, and fee estimation that adds complexity for automated systems.

Zero solves this by being radically simple. One token, one fee, one purpose. A 136-byte transaction, a 48-byte account. No smart contracts, no virtual machine, no ERC-20 token standards. Just value transfer, as fast as the network can gossip it.

Design Principles

1. Machine-first. The protocol is designed for agents and programs, not human wallet UIs. SDK ergonomics prioritize programmatic access.
2. Deterministic cost. Every transaction costs exactly 0.01 Z. No gas auctions, no priority fees, no MEV.
3. Stable value. 1 Z = 1 penny. The token is a unit of account, not a speculative asset.
4. Minimal state. Account state is 48 bytes. Transaction records are pruned via ring buffer. Validator storage is bounded forever.
5. No smart contracts. Zero does one thing: transfer value. This constraint enables extreme optimization.
6. Stablecoin-backed. Every Z in circulation has a corresponding cent of USDC or USDT locked in an on-chain vault.

The Z Token

Z is the sole token on the Zero network. It is a value-transfer token with no governance utility, no staking reward emission, and no speculative mechanics.

Bridge Flow

Z tokens are minted and burned through the bridge vault system. There is no other way to create or destroy Z.

Minting (Deposit)

1. User deposits USDC or USDT to the vault contract on a supported chain (Base or Arbitrum).
2. Trinity Validators observe and attest to the deposit (2/3+ threshold).
3. Once attested, the equivalent Z is minted to the user's Zero account.
4. Conversion: 1 USDC = 100 Z.

Burning (Withdrawal)

1. User initiates a BridgeOut transaction on Zero, specifying destination chain, token (USDC/USDT), and destination address.
2. The Z is burned on the Zero network, plus a 0.5 Z bridge fee to cover EVM gas costs.
3. Trinity Validators sign an EIP-712 release digest (2-of-3 ECDSA threshold).
4. Once threshold is met, the vault contract releases the equivalent stablecoin to the destination address.

Stablecoin Backing

The fundamental invariant of the Zero network:

This invariant is enforced at the protocol level. Z cannot be minted without a corresponding stablecoin deposit, and stablecoins cannot be released without a corresponding Z burn. Validators enforce this invariant as part of consensus -- any block that violates it is rejected.

Supported backing assets:

• USDC (Circle) -- primary backing asset on Base, also accepted on Arbitrum
• USDT (Tether) -- primary backing asset on Arbitrum

The vault contracts are controlled by a ZeroTimelock contract (24-hour delay, 14-day grace period) that holds the sole admin role. All privileged operations -- guardian rotation, parameter changes, emergency pause -- go through the timelock with 2-of-3 guardian threshold. The deployer has renounced all direct admin access.

Block-Lattice Account Model

Zero uses a block-lattice architecture, where each account maintains its own chain of transactions. This design, inspired by Nano, enables several key properties:

• Parallelism. Transactions on different accounts are independent and can be processed concurrently without coordination.
• Minimal contention. There is no global transaction ordering bottleneck. Each account's nonce provides local ordering.
• Compact state. Only the latest account state (balance, nonce, head hash) needs to be stored -- not the full history.

Each account is identified by an Ed25519 public key (32 bytes). The account's "chain" is a sequence of transfers, each linked to the previous by the head hash (a BLAKE3 digest of the previous transfer).

Transaction Format

Every Zero transaction is exactly 136 bytes on the wire. No variable-length fields, no optional extensions, no metadata. This fixed size enables aggressive optimization in serialization and networking.

struct ZeroTransfer {
    from:      [32 bytes]  // Ed25519 public key
    to:        [32 bytes]  // Ed25519 public key
    amount:    [4 bytes]   // u32, penny units
    nonce:     [4 bytes]   // u32, monotonic counter
    signature: [64 bytes]  // Ed25519 full signature
}

Account State

Each account on Zero is represented by exactly 48 bytes of state:

struct Account {
    balance:  [4 bytes]   // u32
    nonce:    [4 bytes]   // u32
    head:     [32 bytes]  // BLAKE3 hash
    flags:    [8 bytes]   // reserved
}

With 48 bytes per account, one billion accounts require approximately 48 GB of state. Combined with the transaction ring buffer, total validator storage remains bounded at 50-110 GB regardless of network age.

Consensus: Leaderless DAG aBFT

Zero uses a leaderless DAG-based asynchronous Byzantine Fault Tolerant consensus protocol, drawing from the designs of Mysticeti and Lachesis.

Key Properties

• Leaderless. No single validator is responsible for block production. All validators propose transaction batches concurrently.
• DAG structure. Validator proposals form a directed acyclic graph, where each proposal references multiple previous proposals.
• Asynchronous BFT. Consensus is reached without timing assumptions. The protocol is safe under arbitrary network delays and tolerates up to 1/3 Byzantine validators.
• Deterministic finality. Once a transaction is included in a committed DAG vertex, it is final. No probabilistic confirmation, no chain reorganizations.

Throughput

Storage & Pruning

Zero uses a ring buffer for transaction storage. Instead of growing unboundedly like traditional blockchains, the transfer log overwrites the oldest entries once the buffer is full.

Why This Works

Zero is a payment network, not a smart contract platform. The only state that matters is each account's current balance, nonce, and head hash (48 bytes). Historical transactions are useful for auditing and debugging, but they are not required for consensus or state validation.

Storage Budget

Vault Architecture

The vault system is Zero's bridge to the broader crypto ecosystem. It consists of smart contracts deployed on supported chains that hold stablecoins (USDC, USDT) as backing for Z tokens.

Design Goals

• Minimal attack surface. Vault contracts are pure escrow controlled by a timelocked admin (ZeroTimelock). All privileged operations require 2-of-3 guardian approval and a 24-hour delay.
• Validator-attested. Deposits and withdrawals require 2/3+ validator attestations, using the same consensus mechanism that secures the Zero network itself.
• Multi-chain. Vaults are deployed on multiple chains to meet users where they are.

Contract Security

• AccessControl (OpenZeppelin): Role-based permissions for all privileged operations.
• EIP-712 typed signatures: Human-readable signing payloads for Trinity Validator approvals.
• Asymmetric pause: Any 1 Trinity Validator can pause all bridge operations; only the admin role can unpause.
• Tiered circuit breaker: ≤20% TVL per 24h requires 2-of-3 Trinity approval. 20-50% TVL requires 3-of-3 Trinity approval. >50% TVL is blocked entirely.
• Timelocked guardian rotation: 48-hour delay for any guardian change, observable on-chain.
• ReentrancyGuard: Applied to all fund-moving functions.
• Replay prevention: Unique bridgeId per operation prevents replay attacks.

Invariant Enforcement

The core safety property is checked at every consensus round:

Any proposed state transition that would violate this invariant is rejected by honest validators.

Deposit Flow (Mint Z)

Step 1: Deposit stablecoins

The user sends USDC or USDT to the vault contract on a supported chain. The deposit transaction includes a memo field containing the user's Zero public key (the account that will receive the minted Z).

Step 2: Validator observation

Zero validators monitor all supported chains for vault deposits. Each validator independently verifies the deposit transaction on the source chain.

Step 3: Attestation

Once a validator confirms the deposit, it broadcasts an attestation to the Zero network. When 2/3+ of validators (by stake weight) have attested to the same deposit, the mint is authorized.

Step 4: Mint

The consensus layer mints the equivalent Z to the specified account. For 1 USDC deposited, 100 Z is minted.

Withdrawal Flow (Burn Z)

Step 1: Initiate BridgeOut

The user sends a BridgeOut transaction on Zero, specifying:

• Destination chain (Base or Arbitrum)
• Token type (USDC or USDT)
• Destination address on the target chain
• Amount of Z to burn

Step 2: Burn

The Z is burned on the Zero network, reducing total supply.

Step 3: Attestation

Validators attest to the burn. When 2/3+ have attested, the release is authorized.

Step 4: Release

The vault contract on the destination chain releases the equivalent stablecoin to the specified address. For 100 Z burned, 1 USDC is released.

Attestation Layer

The attestation layer is the trust bridge between Zero and external chains. It uses the same validator set and consensus mechanism as the main Zero network.

Threshold

Both deposits (mints) and withdrawals (burns) require attestation from 2/3+ of validators by stake weight. This threshold matches the BFT assumption of the main consensus protocol -- if 2/3+ of stake is honest, the bridge is secure.

Validator Responsibilities

• Run full nodes on all supported chains (or use trusted RPC endpoints with verification).
• Monitor vault contracts for deposit events.
• Verify transactions on source chains before attesting.
• Sign attestations using their Zero validator key.

Trinity Validators

Bridge operations (mint/burn) are controlled by three trusted parties called Trinity Validators, separate from the consensus validator set. All vault contract operations require a 2-of-3 multisig from the Trinity Validators.

• Organizational separation: Each Trinity Validator is a different organization in a different legal jurisdiction.
• Hardware-only signing: All Trinity Validator keys are held in HSMs or hardware wallets. No software key storage.
• No delegation without expiry: Signing authority cannot be delegated without an on-chain expiry enforced at the contract level.
• Asymmetric pause: Any single Trinity Validator can pause bridge operations; only the admin role can unpause.
• Timelocked rotation: Guardian rotation requires a 48-hour delay, observable on-chain before it takes effect.

Supported Chains

Python SDK

Install the Python SDK:

pip install zero-network

Basic Usage

from zero import Wallet

# Load wallet from ZERO_PRIVATE_KEY env var
w = Wallet.from_env()

# Send 10 Z ($0.10) to a recipient
tx = w.send("zr_recipient", 10)
print(tx.hash)  # Transaction hash

# Check balance
bal = w.balance()
print(bal)  # 489.89 Z

# Get account info
acct = w.account()
print(acct.nonce)   # 1042
print(acct.head)    # BLAKE3 hash of last transfer

Transaction History

# Get last 10 transfers
history = w.history(limit=10)
for tx in history:
    print(f"{tx.direction} {tx.amount} Z -> {tx.counterparty}")

Bridge Operations

# Deposit: after sending USDC to vault on Base
mint = w.bridge_in(
    source_chain="base",
    token="usdc",
    tx_hash="0xabc123..."
)
print(mint.status)  # "pending" -> "confirmed"

# Withdraw: burn Z and release USDC
release = w.bridge_out(
    dest_chain="arbitrum",
    token="usdc",
    dest_address="0xdef456...",
    amount=500  # 500 Z = 5 USDC
)

JavaScript SDK

Install the JavaScript SDK:

npm install @zero-network/sdk

Basic Usage

import { Wallet } from '@zero-network/sdk';

// Load wallet from ZERO_PRIVATE_KEY env var
const w = Wallet.fromEnv();

// Send 10 Z ($0.10)
const tx = await w.send('zr_recipient', 10);
console.log(tx.hash);

// Check balance
const bal = await w.balance();
console.log(`Balance: ${bal} Z`);

// Get transaction history
const history = await w.history({ limit: 10 });
history.forEach(tx => console.log(tx));

Bridge Operations

// Deposit: track a USDC deposit
const mint = await w.bridgeIn({
  sourceChain: 'base',
  token: 'usdc',
  txHash: '0xabc123...'
});

// Withdraw: burn Z and release USDC
const release = await w.bridgeOut({
  destChain: 'base',
  token: 'usdc',
  destAddress: '0xdef456...',
  amount: 1000  // 1000 Z = 10 USDC
});

Rust SDK

Add the Rust SDK to your Cargo.toml:

[dependencies]
zero-network = "0.1"

Basic Usage

use zero_sdk::{Wallet, Result};

fn main() -> Result<()> {
    // Load from ZERO_PRIVATE_KEY env var
    let w = Wallet::from_env()?;

    // Send 10 Z
    let tx = w.send("zr_recipient", 10)?;
    println!("tx: {}", tx.hash);

    // Check balance
    let bal = w.balance()?;
    println!("balance: {} Z", bal);

    Ok(())
}

Environment Pattern

All Zero SDKs follow a consistent environment-first pattern. The wallet private key is loaded from the ZERO_PRIVATE_KEY environment variable by default.

# Set the private key
export ZERO_PRIVATE_KEY="your_ed25519_private_key_hex"

# Optional: set a custom RPC endpoint
export ZERO_RPC_URL="https://rpc.zzero.net"

This pattern is designed for machine environments -- containers, serverless functions, CI/CD pipelines, and AI agent runtimes. No config files, no interactive prompts, no key management UIs. Just an environment variable.

Chat Wallet

AI agents running in chat contexts (LLM tool-use, MCP servers, chat assistants) can use a chat wallet -- a lightweight wallet that lives in the agent's runtime and makes payments on behalf of the user.

from zero import ChatWallet

# Agent creates a chat wallet for a session
wallet = ChatWallet.create()
print(wallet.address)  # zr_a1b2c3...

# User funds it (small amount for the session)
# wallet receives 5 Z ($0.05) -- enough for ~500 API calls

# Agent pays for tool calls automatically
result = await wallet.pay_and_call(
    tool_address="zr_search_provider",
    amount=1,  # 0.01 Z per call (+ 0.01 Z fee = 0.02 Z total)
    endpoint="https://api.example.com/search",
    params={"q": "machine learning papers"}
)

x402 Protocol

x402 is a machine-native payment protocol inspired by HTTP 402 (Payment Required). It enables APIs to charge per-request without subscriptions, API keys, or billing infrastructure.

How It Works

1. Client makes a request to a paid API endpoint.
2. Server responds with HTTP 402 and a payment header containing the price (in Z) and the server's Zero address.
3. Client makes a Zero payment for the requested amount.
4. Client retries the request with the transaction hash in a payment header.
5. Server verifies the payment and serves the response.

// Step 1: Client request
GET /api/search?q=zero+network HTTP/1.1

// Step 2: Server responds with payment details
HTTP/1.1 402 Payment Required
X-Zero-Amount: 10
X-Zero-Address: zr_merchant_abc123
X-Zero-Network: zero

// Step 4: Client retries with payment
GET /api/search?q=zero+network HTTP/1.1
X-Zero-Payment: tx_hash_abc123

// Step 5: Server verifies and responds
HTTP/1.1 200 OK
{ "results": [...] }

Server Middleware

The @paywall decorator turns any API endpoint into a paid endpoint with one line of code:

from fastapi import FastAPI
from zero.x402 import paywall

app = FastAPI()

@app.get("/api/search")
@paywall(amount=10, address="zr_merchant")
async def search(q: str):
    return do_search(q)

The middleware handles:

• Returning 402 with payment details when no payment is provided
• Verifying the Zero transaction hash against the expected amount and address
• Rejecting replayed transaction hashes (each tx can only be used once)
• Passing the request through to the handler once payment is verified

Express.js Middleware

import { paywall } from '@zero-network/x402';

app.get('/api/search',
  paywall({ amount: 10, address: 'zr_merchant' }),
  async (req, res) => {
    const results = await doSearch(req.query.q);
    res.json({ results });
  }
);

Client Auto-Pay

The SDK provides an auto-pay HTTP client that handles the 402 flow automatically:

from zero.x402 import AutoPayClient
from zero import Wallet

w = Wallet.from_env()
client = AutoPayClient(wallet=w)

# This will automatically:
# 1. GET the endpoint
# 2. Receive 402 with payment details
# 3. Pay the requested amount
# 4. Retry with the tx hash
# 5. Return the final response
result = await client.get("https://api.example.com/search?q=hello")
print(result.json())

import { AutoPayClient, Wallet } from '@zero-network/sdk';

const w = Wallet.fromEnv();
const client = new AutoPayClient({ wallet: w });

// Automatic 402 handling
const result = await client.get('https://api.example.com/search?q=hello');
console.log(result.data);

MCP Server Payments

Zero integrates natively with the Model Context Protocol (MCP) -- the standard for connecting AI models to external tools and data sources. MCP tool servers can charge per-invocation using Zero.

Server Implementation

from mcp.server import Server
from zero import Wallet

server = Server("search-provider")
wallet = Wallet.from_env()

@server.tool("web_search")
async def web_search(query: str, zero_payment: str = None):
    # No payment provided -- return payment request
    if not zero_payment:
        return {
            "error": "payment_required",
            "network": "zero",
            "address": wallet.address,
            "amount": 10
        }

    # Verify the payment
    verified = await wallet.verify_payment(
        tx_hash=zero_payment,
        min_amount=10
    )
    if not verified:
        return {"error": "payment_invalid"}

    # Payment verified -- serve the request
    return {"results": await do_search(query)}

Payment Flow

1. AI agent invokes the web_search tool without a payment.
2. Server returns a payment_required response with the price and address.
3. Agent's wallet sends the requested amount to the server's address.
4. Agent retries the tool call with the zero_payment transaction hash.
5. Server verifies the payment on-chain and serves the result.

This creates a machine-to-machine economy where AI agents can autonomously discover, pay for, and consume tools without human intervention.

MCP Client

The Zero-aware MCP client handles payment negotiation automatically:

from mcp.client import Client
from zero.mcp import ZeroPaymentHandler
from zero import Wallet

wallet = Wallet.from_env()
handler = ZeroPaymentHandler(wallet=wallet)

client = Client(
    server_url="https://mcp.example.com",
    payment_handler=handler
)

# The client will automatically handle payment_required
# responses, pay, and retry -- transparent to the caller
result = await client.call_tool("web_search", {
    "query": "latest AI research papers"
})
print(result)

For Providers: Accept Zero Payments

If you run a website, API, or MCP server, you can charge users and AI agents per request using Zero. No API keys to issue, no subscription management, no billing infrastructure. Agents and users pay per-use with Z tokens and get instant access.

Website Paywall

Gate any webpage or content behind a Zero micropayment. When a user or agent requests the page, return HTTP 402 with payment details. After payment, serve the content.

Express.js Middleware

const { ZeroPaywall } = require('@zero-network/sdk');

const paywall = new ZeroPaywall({
  address: process.env.ZERO_ADDRESS,
});

// Gate a route: 0.05 Z to read an article
app.get('/article/:id', paywall.gate(5), async (req, res) => {
  // Only reached after payment verified
  const article = await getArticle(req.params.id);
  res.json(article);
});

// Gate a download: 0.10 Z for a PDF
app.get('/report/:id', paywall.gate(10), async (req, res) => {
  res.sendFile(reportPath);
});

What the Agent Sees

GET /article/42 HTTP/1.1

HTTP/1.1 402 Payment Required
Content-Type: application/json

{
  "x-402-version": 1,
  "x-402-network": "zero",
  "x-402-amount": 5,
  "x-402-address": "zr_pub...",
  "x-402-description": "Pay 0.05 Z to read this article"
}

The agent's SDK auto-pays, attaches the receipt in an X-Zero-Receipt header, and retries. The middleware verifies and serves content. The entire flow takes <1 second.

API Paywall

Charge per API call with a single decorator. No API keys to manage, no rate limit tiers, no billing dashboard. Every call pays.

Python (FastAPI)

from zero_sdk import x402_gate
from fastapi import FastAPI

app = FastAPI()

@app.get("/api/sentiment")
@x402_gate(amount=1)  # 0.01 Z per call
async def sentiment(text: str):
    return analyze_sentiment(text)

@app.get("/api/translate")
@x402_gate(amount=3)  # 0.03 Z per call
async def translate(text: str, target_lang: str):
    return do_translate(text, target_lang)

@app.get("/api/ocr")
@x402_gate(amount=5)  # 0.05 Z per call
async def ocr(image_url: str):
    return extract_text(image_url)

Revenue Example

No minimum volume. No setup cost. Deploy, set your price, and start earning from the first request.

MCP Provider

Build an MCP tool server that charges AI agents per tool invocation. Prices are advertised in the tool schema so agents know the cost before calling.

Server with Per-Tool Pricing

from mcp.server import Server
from zero import Wallet

server = Server("my-tools")
wallet = Wallet.from_env()

# Each tool declares its price in the decorator
@server.tool("web_search", zero_price=2)  # 0.02 Z
async def search(query: str):
    return await search_web(query)

@server.tool("run_code", zero_price=10)  # 0.10 Z
async def run_code(code: str, language: str):
    return await sandbox_exec(code, language)

@server.tool("image_gen", zero_price=25)  # 0.25 Z
async def generate_image(prompt: str):
    return await gen_image(prompt)

How Agents Discover Prices

When an agent calls tools/list, prices are included in the tool metadata:

{
  "tools": [
    {
      "name": "web_search",
      "description": "Search the web",
      "zero_price": 2,
      "zero_address": "zr_pub..."
    },
    {
      "name": "run_code",
      "description": "Execute code in sandbox",
      "zero_price": 10,
      "zero_address": "zr_pub..."
    }
  ]
}

The agent compares the price against its spending limits. If acceptable, it pays automatically and receives the tool result. No human approval needed for within-budget calls.

Provider Use Cases

Zero enables new business models that weren't viable before penny-scale settlement existed.

Agent Discovery Flow

When an AI agent encounters a Zero-gated resource, the payment is automatic and transparent.

HTTP (x402) Flow

1. Request: Agent sends a normal HTTP request to the endpoint.
2. 402 Response: Server returns HTTP 402 with x-402-amount, x-402-address, and x-402-network: "zero".
3. Budget Check: Agent SDK checks the requested amount against its per-call and per-hour spending limits.
4. Payment: If within budget, SDK sends a Zero transfer to the provided address.
5. Retry: SDK retries the original request with X-Zero-Receipt: <tx_hash> header.
6. Content: Server verifies receipt on-chain (<500ms) and serves the response.

MCP Flow

1. List Tools: Agent calls tools/list and sees zero_price in each tool's metadata.
2. Call Tool: Agent invokes the tool. If no payment is attached, the server returns payment_required.
3. Auto-Pay: The Zero MCP client handler detects the payment request, sends Z, and retries with the tx hash.
4. Result: Server verifies payment and returns the tool result.

Agent Configuration

from zero import Wallet
from zero.spending import SpendingPolicy

wallet = Wallet.from_env()

# Configure spending limits for autonomous operation
policy = SpendingPolicy(
    max_per_call=25,       # 0.25 Z max per single payment
    max_per_minute=100,    # 1.00 Z max per minute
    max_per_hour=1000,     # 10.00 Z max per hour
    max_per_day=10000,     # 100.00 Z ($1.00) max per day
)

wallet.set_policy(policy)
# Agent now operates autonomously within these bounds

Running a Validator

Zero validators process transactions, participate in consensus, attest to bridge events, and earn a share of transaction fees.

Quick Start

# Install the Zero validator
curl -sSf https://install.zzero.net | sh

# Generate a validator keypair
zero keygen --output validator-key.json

# Start the validator
zero validator start \
  --key validator-key.json \
  --rpc-port 8545 \
  --p2p-port 30300

The install script downloads the latest validator binary, verifies its signature, and sets up a systemd service for automatic restarts.

Hardware Requirements

Economics

Transaction fees are split three ways each epoch:

Revenue Projections

At the fee of 0.01 Z ($0.0001) per transaction:

Staking

Validators must stake Z tokens to participate in consensus. The stake serves as a sybil resistance mechanism and economic bond against misbehavior.

Staking Parameters

The validator set is capped at 1,024. If all slots are filled, a new validator must stake more than the lowest-staked current validator to enter the set.

Trust Scoring

Each validator maintains a trust score (range 0-1000) that tracks reliability:

• Below 100: Validator is ejected from the active set.
• Bottom 5%: The lowest-scoring 5% of validators are ejected each epoch.
• Equivocation: Signing conflicting state transitions results in immediate ejection and stake at risk.

# Stake tokens as a validator (min 10,000 Z)
zero stake deposit --amount 10000 --key validator-key.json

# Check stake status
zero stake status --key validator-key.json

# Initiate unstaking (begins 7-day unbonding period)
zero stake withdraw --amount 5000 --key validator-key.json

API Reference

The Zero API consists of 8 client-facing endpoints plus 2 gossip endpoints (PushEvent, PullEvents) for validator-to-validator communication. All client endpoints are available via gRPC. The API is intentionally minimal -- there are no pagination cursors, no filtering operators, no GraphQL. Just 8 functions that do everything you need.

Send

Submit a signed transfer to the network.

// Request
{
  "method": "Send",
  "params": {
    "from":      "zr_sender_pubkey",
    "to":        "zr_recipient_pubkey",
    "amount":    10,
    "nonce":     42,
    "signature": "hex_encoded_64_byte_sig"
  }
}

// Response
{
  "tx_hash": "blake3_hash_of_transfer",
  "status":  "confirmed"
}

GetTransfer

Look up a transfer by its transaction hash. Returns the full transfer details and confirmation status.

// Request
{
  "method": "GetTransfer",
  "params": {
    "tx_hash": "blake3_hash"
  }
}

// Response
{
  "from":      "zr_sender",
  "to":        "zr_recipient",
  "amount":    10,
  "nonce":     42,
  "status":    "confirmed",
  "timestamp": 1709827200
}

GetHistory

Get recent transfers for an account, ordered most recent first. Limited by the ring buffer retention window.

// Request
{
  "method": "GetHistory",
  "params": {
    "account": "zr_account",
    "limit":   10
  }
}

// Response
{
  "transfers": [
    {
      "tx_hash":   "blake3_hash",
      "from":      "zr_sender",
      "to":        "zr_recipient",
      "amount":    10,
      "timestamp": 1709827200
    }
  ]
}

GetBalance

Get the current balance for an account. Returns the balance in penny units.

// Request
{
  "method": "GetBalance",
  "params": {
    "account": "zr_account"
  }
}

// Response
{
  "balance": 48989  // 489.89 Z = $4.90
}

GetAccount

Get the full account state, including balance, nonce, and head hash.

// Request
{
  "method": "GetAccount",
  "params": {
    "account": "zr_account"
  }
}

// Response
{
  "balance": 48989,
  "nonce":   1042,
  "head":    "blake3_hash_of_latest_transfer",
  "flags":   0
}

BridgeIn

Initiate a deposit by referencing a stablecoin transaction on a supported chain. Validators will observe and attest to the deposit.

// Request
{
  "method": "BridgeIn",
  "params": {
    "source_chain": "base",
    "token":        "usdc",
    "tx_hash":      "0xabc123..."
  }
}

// Response
{
  "bridge_id":    "bridge_mint_001",
  "status":       "pending",
  "attestations": 0,
  "required":     67  // 2/3+ of 100 validators
}

BridgeOut

Initiate a withdrawal by burning Z and specifying a destination chain and address for stablecoin release. A bridge-out fee of 0.5 Z ($0.005) is charged to cover EVM gas costs. The fee is deducted from the sender in addition to the burn amount.

// Request
{
  "method": "BridgeOut",
  "params": {
    "dest_chain":   "arbitrum",
    "token":        "usdc",
    "dest_address": "0xdef456...",
    "amount":       500  // 500 Z = 5 USDC (+ 50 units fee = 550 total deducted)
  }
}

// Response
{
  "bridge_id": "bridge_burn_042",
  "status":    "pending",
  "z_burned": 500,
  "fee":      50
}

GetBridgeStatus

Check the status of a bridge operation (deposit or withdrawal).

// Request
{
  "method": "GetBridgeStatus",
  "params": {
    "bridge_id": "bridge_mint_001"
  }
}

// Response
{
  "bridge_id":    "bridge_mint_001",
  "type":         "mint",
  "status":       "confirmed",
  "attestations": 72,
  "required":     67,
  "amount_z":     100,  // 100 Z = 1 USDC
  "source_chain": "base",
  "source_tx":    "0xabc123..."
}

Fee Structure

Zero has the simplest fee structure in crypto:

There is no:

• Gas price or gas limit
• Priority fee or tip
• Congestion-based pricing
• Different fee tiers for different transaction types
• Fee market or auction mechanism

Every transaction costs exactly 0.01 Z. The fee is deducted from the sender's balance in addition to the transfer amount. Total debit: amount + 0.01 Z. The smallest possible transaction is 0.01 Z + 0.01 Z fee = 0.02 Z ($0.0002). Collected fees are distributed each epoch: 70% to validators (proportional to stake), 15% to bridge reserve (vault contract gas), and 15% to protocol reserve (emergency fund, development).

Limits

Security Model

Cryptographic Primitives

Consensus Security

• Byzantine fault tolerance: Tolerates up to 1/3 of validators (by stake) being malicious.
• Deterministic finality: No chain reorganizations. Once confirmed, a transaction cannot be reversed.
• Trust scoring: Validators maintain a trust score (0-1000). Equivocation results in immediate ejection; poor performance accumulates penalties. Bottom 5% ejected per epoch.
• Stake at risk: Validators that sign conflicting state transitions face ejection and stake at risk.

Bridge Security

• 2/3+ attestation threshold: Same security model as the main consensus.
• Trinity Validators: 2-of-3 multisig from independent organizations in separate jurisdictions controls all mint/burn operations.
• Hardware-only signing: Trinity Validator keys held in HSMs/hardware wallets.
• Tiered circuit breaker: ≤20% TVL = 2-of-3, 20-50% = 3-of-3, >50% = blocked.
• Asymmetric pause: Any 1 Trinity Validator can pause; only admin can unpause.
• Invariant enforcement: Total Z supply must always equal 100x total locked stablecoins.

Economic Security

• Max tx value: 25 Z ($0.25). The maximum gain from a successful attack on a single transaction is $0.25.
• No MEV. No smart contracts means no sandwich attacks, no front-running, no flashloan exploits.
• No governance attacks. There is no on-chain governance to capture.

Attack Mitigations

Roadmap

Crate Structure

The Zero chain is implemented as a Rust workspace with seven crates:

chain/crates/
├── zero-types/      # Transfer, Account, BlockRef, Event, params, config
├── zero-crypto/     # Ed25519, BLAKE3, keyfiles
├── zero-storage/    # AccountStore, ring buffer, executor, rate limiter, snapshots
├── zero-consensus/  # DAG, Committee, ValidatorState, TrustScorer, Node, event loop
├── zero-network/    # gRPC server (8 client + 2 gossip endpoints)
├── zero-node/       # Binary entry point
└── zero-bridge/     # Bridge attestation service for Trinity Validators