XFuel

Theta-Hybrid AI DePIN Hub — live inference on EdgeCloud GPUs, ZK-verified settlements, agent-first API, and cross-chain yield across Theta, Bittensor, Akash, Solana, and beyond.

Live: xfuel.app (Theta Mainnet Beta)

Docs Status Audit Status Build License ZK-VM DePIN Tests

Table of Contents

• What is XFUEL?
• Whitepaper
• Key Features
  • Revenue Model
• Quick Start
  • For Users
  • For Developers
  • For Agents (M2M)
• How It Works
• Architecture
• Core Layer
• Circuits
• Deployment Status
• Roadmap
• AI DePIN Overview
• Governance (veXF)
• Verifier Patches
• CosmWasm Prover
• EVM Prover (Phase 2)
• Solana Prover (Phase 3)
• Security
• Research Integration & Attribution
• Tech Stack
• Repo Structure
• Development Setup
• Testing
• Deployment
• Ecosystem Expansion (Phase 6)
• Contributing
• Community & Support
• License
• Quick Links

What is XFUEL?

XFuel Protocol is a Theta-hybrid AI DePIN hub — a modular, ZK-secured Core Layer that pumps intelligence, compute, liquidity, and value across AI ecosystems. Built with Theta EdgeCloud as the primary GPU backbone, XFuel routes real AI inference (LLM, image gen, STT, voice cloning, RAG, video, object detection) through live EdgeCloud APIs, generates SP1 zkVM proofs on the same GPU hardware, and settles everything on-chain with cryptographic guarantees.

The Core Layer verifies proofs, routes intents, splits fees, and governs parameters. All domain-specific logic — which AI model to run, which GPU tier to select, how to price a lease — lives in circuits (independent modules). The result is an agent-first, intent-driven system where any user, developer, or autonomous agent can access verifiable AI compute in under 10 seconds.

In practical terms, XFuel lets you:

• Run AI inference via 15 one-click preset hooks with smart GPU selection (RTX 4090 / A100 / H100 SXM) — real EdgeCloud execution, ZK-proven results
• Route workloads to the cheapest DePIN provider across Theta EdgeCloud, Akash, Bittensor, Render, and more
• Settle cross-chain AI tasks with SP1 zkVM Groth16 proofs — sub-200ms proving on EdgeCloud GPUs, <270K gas on-chain
• Build agents that interact via structured API (/theta-ai/agent-intent) with webhook callbacks — no polling, no UI needed
• Earn from a unified revenue model: 30/30/25/15 split (see Revenue Model)
• Monitor everything via a live dashboard with failure prediction, gas profiles, and ROI calculator
• Govern circuit priorities, fee parameters, and treasury via vote-escrowed veXF

Whitepaper

XFuel Protocol — Whitepaper v2.4 AI Pumping Station: Modular ZK-Secured DePIN Hub — Hybrid Theta-Centric Architecture

Read the complete technical whitepaper: WHITEPAPER.md

Highlights:

• Theta-hybrid Core Layer — ZKVerifierSP1, CoreRevenueSplitter (with GET), veXFGovernance
• Live inference pipeline — 15 presets, smart GPU selector, EdgeCloud execution, agent webhooks, monitoring dashboard
• SP1 zkVM v6.0.2 — Binary serialization, batch=10 recursive rollup (11.6x speedup), sub-200ms per proof on EdgeCloud
• Tri-prover architecture — EVM (Solidity) + CosmWasm (Rust) + Solana SVM (Rust) — all <270K gas equivalent
• 16+ modular circuits — AI compute, DePIN infrastructure, yield, robotics, data, energy, wireless, and more
• Revenue innovation — Growth & Expansion Treasury (GET), Fee-to-Stake routing
• Cross-chain — Theta (primary), Bittensor, Osmosis, Akash, Solana, Filecoin, NEAR, Aptos, Sui
• Phase 1 research integration — zkGPT (LLM ZK proofs; eprint 2025/1184, security-Anonymous/zkgpt) and Fair Exchange / PAS (atomic A2A payment↔result; eprint 2026/395). Mock prover: node services/zkgpt-prover/mock-server.cjs; smoke test: npm run test:zkgpt-mock. Full attribution: docs/REFERENCES-AND-ATTRIBUTION.md.

Key Features

Revenue Model

Every fee-generating interaction — AI inference, bridge transfers, A2A relay, data attestations — flows through CoreRevenueSplitter. All fees are distributed via a clean four-way split:

GET Sub-Breakdown:

Fee rates by stream:

Steady-state volume target: 60% AI tasks, 25% data & communications, 15% financial settlements. Governance (veXF) can adjust fee BPS ranges and split ratios via proposal — see Governance.

See docs/Growth-Expansion-Treasury.md for GET mechanics.

Quick Start

For Users

1. Visit xfuel.app — the live beta UI with bridge, dashboard, governance, circuits, staking, and monitoring.
2. Run AI inference — Select a preset (e.g., QUICK_LLAMA), choose a GPU tier, confirm wallet, and get ZK-verified results in seconds.
3. Bridge TFUEL — Select a target (e.g., Osmosis AI yield pool), click "Show Deposit Address", and send TFUEL from any Theta wallet. The ZK proof pipeline handles the rest (~11-12 seconds).

Beta notice: Pre-audit beta for traction validation. Start with small amounts. Full CertiK audit planned for Q2 2026. See Security.

For Developers

# 1. Clone and install
git clone https://github.com/XFuel-Lab/xfuel-protocol.git
cd xfuel-protocol
npm install

# 2. Compile contracts
npx hardhat compile

# 3. Run the full test suite (755+ tests)
npx hardhat test

# 4. Start the bridge + dashboard UI (Vite + React)
npm run dev

# 5. Start the Core Layer AI listener + agent API
cd core-layer && npm install && node ai-listener.js

# 6. Open the monitoring dashboard
npx serve dashboard -l 3000

Local simulation (no TFUEL needed):

npx hardhat run activation/public-activation.cjs
# Deploys 16 circuits + Core Layer + BelieverRound to Hardhat local network

Windows note: Hardhat and Node.js run natively on PowerShell. For CosmWasm/Rust builds, WSL 2 or Git Bash is recommended.

For Agents (M2M)

Submit AI inference intents directly via the agent API — no UI required:

# Submit an inference intent with GPU tier selection
curl -X POST http://localhost:3002/theta-ai/agent-intent \
  -H "Content-Type: application/json" \
  -d '{
    "preset": "QUICK_LLAMA",
    "gpuTier": "rtx4090",
    "prompt": "Explain ZK proofs in one sentence",
    "callbackUrl": "https://my-agent.example.com/webhook"
  }'

# List available presets and GPU pricing
curl http://localhost:3002/theta-ai/presets

# Check webhook delivery status
curl http://localhost:3002/theta-ai/webhook-status/<taskId>

Agents receive webhook callbacks with full output, ZK proof data, and settlement tx hash. See docs/M2M_API.md for the complete API reference.

How It Works

Live Inference + Settlement Flow

User / Agent submits intent (UI, preset hook, or POST /theta-ai/agent-intent)
  │
  ├─ On-chain: submitIntent(serviceId, inputHash) or submitPresetIntent(presetId)
  │     └─ TFUEL payment + 0.5% fee → CoreRevenueSplitter (30/30/25/15 split)
  │
  ▼
CoreListener (ai-listener.js) detects InferenceIntentSubmitted event
  │
  ├─ Smart GPU Selector: RTX 4090 (1x) → A100 (2.5x) → H100 SXM (5x)
  ├─ Routes to Theta EdgeCloud API (primary) or RapidAPI (fallback)
  │
  ▼
EdgeCloud executes inference (LLM, image gen, STT, voice clone, RAG, video, detection)
  │
  ├─ completeIntent(intentId, outputHash, modelHash, latencyMs)
  ├─ SP1 proof generated on EdgeCloud GPU (sub-200ms, batch=10 recursive rollup)
  │
  ▼
settleIntent(intentId, proof, publicValues, nullifier)
  │
  ├─ ZK-verified on-chain → ProofVerified event → FULFILLED
  └─ Webhook callback + Monitoring update + ROI calc refresh

Bridge Flow (TFUEL ↔ Cosmos DeFi)

Forward (~11-12s): User sends TFUEL to VaultFactory vault → SP1 proof generated → CosmWasm ZKVerifier validates → ibcTFUEL minted 1:1 → IBC routing to yield pool.

Reverse (~12-15s): User calls burn_for_unwrap() → 0.5% fee to FeeCollector → Backend detects burn → SP1 proof → VaultFactory releases TFUEL.

No wallet extensions needed — send via QR code or paste address from any Theta wallet.

Architecture

flowchart TB
    subgraph Users["Users / Agents / Protocols"]
        U1["👤 End User\n(xfuel.app)"]
        U2["🤖 Autonomous Agent\n(/theta-ai/agent-intent)"]
        U3["🔗 External Protocol\n(xfuel-sdk)"]
    end

    subgraph CoreLayer["🔷 CORE LAYER — Theta Mainnet (chain 361)"]
        direction TB
        ZK["ZKVerifierSP1\nGroth16/PLONK · <270K gas\nNullifiers · Circuit registry"]
        RS["CoreRevenueSplitter\n30% BBB · 30% GET · 25% Stakers · 15% Treasury\nFee-to-Stake routing"]
        GOV["veXFGovernance\nCurve-style lock · ZK nullifiers\nOn-chain execution hooks"]
        HOOKS["SP1ProofHooks\nNullifier compute · Fee commitments\nCross-chain payload encoding"]
        LISTENER["CoreListener (ai-listener.js)\nEvent polling · Intent routing\nWebhook dispatch · Proof submission"]
        ZK <-->|"verified nullifiers"| RS
        RS <-->|"governance params"| GOV
        HOOKS -.->|"used by all circuits"| ZK
        LISTENER -->|"submits proofs"| ZK
        LISTENER -->|"collects fees"| RS
    end

    subgraph Circuits["⚡ CIRCUITS — Pluggable Modules"]
        CI["ThetaInferenceCircuit\nEdgeCloud · TDROP payments\nGPU tier selection"]
        TAO["TAOCircuit\nBittensor dTAO staking\nSubnet routing via EVM 964"]
        BRG["BridgeCircuit\nHyperlane cross-chain\nISM-secured relay"]
        A2A["A2ACircuit\nAgent-to-agent messaging\nEscrow · ZK verified"]
        MORE["+ 17 more circuits\nAkash · Yield · ZKML\nSolana · DataHubs…"]
    end

    subgraph Provers["🔐 ZK PROVING"]
        SP1["SP1 zkVM v6.0.2\nRISC-V → STARK → Groth16\n~9s proof · <270K gas verify"]
        EDGE["Theta EdgeCloud\nH100 SXM · A100 · RTX 4090\nCUDA SP1 proving"]
        SP1 <-->|"CUDA acceleration"| EDGE
    end

    subgraph Chains["🌐 SETTLEMENT CHAINS"]
        TH["Theta Mainnet\nchain 361"]
        BT["Bittensor EVM\nchain 964"]
        COS["Cosmos IBC\nOsmosis · Persistence"]
        SOL["Solana\n(Phase 3)"]
    end

    Users --> LISTENER
    Circuits --> LISTENER
    Circuits <-->|"proofBytes + publicValues"| SP1
    LISTENER <-->|"EdgeCloud inference API"| EDGE
    CoreLayer -->|"verified settlements"| TH
    BRG -->|"Hyperlane dispatch"| BT
    TAO -->|"dTAO precompile 0x805"| BT
    BRG -->|"IBC relay"| COS
    BRG -.->|"Phase 3"| SOL

Core Components

Event-Driven Circuit Interface

Circuits interact with the Core Layer exclusively through events — zero shared state, independent upgradability, and live on the XFuel shared subchain:

Core emits:   TaskRouted, ProofVerified, FeeDistributed, ProposalExecuted
Circuits emit: IntentSubmitted, TaskCompleted, SettlementRequested

Supported Chains

Additional chains via circuits: Filecoin, NEAR, Aptos (Move), Sui (Move).

Core Layer

The Core Layer lives in core-layer/ and is designed for independent circuits to plug in via events. See docs/Technical-Specifications.md for full multi-prover gas benchmarks.

# Install and compile
cd core-layer && npm install
npx hardhat compile

# Run Solidity tests
npx hardhat test core-layer/test/ZKVerifierSP1.test.cjs
npx hardhat test core-layer/test/SP1ProofHooks.test.cjs

# Run JS listener tests (85 multi-prover tests)
cd core-layer && node --test test/ai-listener.test.js

# Build CosmWasm contracts
cd core-layer/wasm/zk-verifier && cargo build --release --target wasm32-unknown-unknown
cd ../revenue-splitter && cargo build --release --target wasm32-unknown-unknown

# Build Solana prover
cd solana-prover && cargo build-sbf && cargo test

Integrating a Custom Circuit

import { CoreListener, AI_INTENT_TYPES, ChainType, ProverType } from './ai-listener.js';

const listener = new CoreListener({
  chains: {
    theta_mainnet: {
      type: ChainType.EVM,
      prover: ProverType.EVM_GROTH16,
      name: 'Theta Mainnet',
      chainId: 361,
      rpc: 'https://eth-rpc-api.thetatoken.org/rpc',
      gasTarget: 270000,
    },
    solana_devnet: {
      type: ChainType.SVM,
      prover: ProverType.SOLANA_ALT_BN128,
      name: 'Solana Devnet',
      rpc: 'https://api.devnet.solana.com',
      gasTarget: 220000,
      programId: 'YOUR_PROGRAM_ID',
    },
  },
});

listener.registerCircuit('my-circuit', {
  onIntent: async (intent, ctx) => {
    // ctx.prover — which backend verified this proof
    // ctx.gasEquivalent — { cost, unit, meetsTarget }
    // ctx.getRoute(ChainType.EVM) — cross-chain routing info
    // ctx.generateProof(req) — SP1 proof generation
  },
  onProofReady: async (proof) => { /* settlement confirmed */ },
});

await listener.start();

Multi-Prover Gas Targets

All provers meet the <270K gas equivalent target for single Groth16 verification:

Cross-Chain Proof Routing

Both live mode (with SP1 Verifier Gateway) and mock mode (gateway = address(0)) are supported for development.

Circuits

XFuel ships 16+ modular circuits — each fully isolated with its own state, events, pause mechanism, and off-chain handler. All fees route through CoreRevenueSplitter (see Revenue Model).

Priority Circuits (v1.6.1)

Expansion Circuits

The Core Layer's modular architecture imposes no upper limit on circuit count. See docs/CIRCUITS.md and docs/Circuit-Design-and-Expansion.md for full specifications.

Deployment Status

As of March 2026.

Current Phase: Phase 6 Complete — Ecosystem Expansion + Theta Testnet Full Deployment

Live Contract Addresses

Theta Mainnet (Chain ID: 361):

VaultFactory:       0xB0a26600074dADC69186632a1B8dFd7c3146Ce56
RevenueSplitter:    0x1C4CEbbb4Cfa7fdb546424F21CF706c48C478EE6

Theta Testnet (Chain ID: 365) — 23 contracts:

Addresses saved to deploy/manifests/testnet-<timestamp>.json. Key entries: CoreRevenueSplitter, ZKVerifierSP1, TAOCircuit, A2ACircuit, ThetaGPUCircuit, ZKMLCircuit, and 13 more.

Cosmos (Osmosis primary):

ZKVerifier:         Awaiting governance whitelist
ibcTFUEL (CW20):    Awaiting governance whitelist
FeeCollector:       Awaiting governance whitelist

Roadmap

Phases 1–6 are complete. The roadmap below reflects where the protocol is heading, not where it's been. For the full build history, see docs/Circuit-Design-and-Expansion.md and CHANGELOG.md.

✅ Foundation Complete (Q1 2026)

All six build phases are shipped:

• Core Layer — ZKVerifierSP1, CoreRevenueSplitter, veXFGovernance, SP1ProofHooks (755+ tests)
• 16 Circuits — deployed across Theta, Bittensor EVM, Cosmos, Solana, Akash, Render
• Theta Subchain — privatenet validated → testnet live (chain 365001), mainnet-ready (361001)
• AI Listener — multi-prover event orchestrator, 6-tier DePIN router, EdgeCloud attestation
• ZK Settlement — SP1 Groth16/PLONK proof pipeline, SP1-CC composed calls, Hyperlane relay
• Agent Economy — A2ACircuit swarms, x402 micropayments, privacy-preserving data markets

⏳ Now: Audit & Grant Sprint (Q2 2026)

🔜 Near-Term: Agent Capture (Q2–Q3 2026)

Positioning: XFuel is becoming the ZK settlement layer for AI compute across all DePIN networks. The agent economy narrative is heating up in 2026 — our goal is to own the infrastructure layer that agents trust.

🗓 Medium-Term: Ecosystem Expansion (Q3–Q4 2026)

🔭 Long-Term Vision (2027+)

• Additional subchains per circuit when volume warrants (currently single shared XFuel subchain)
• TPULSE subchain integration (Track 7 — health AI + cross-subchain)
• LavitaCircuit — health AI × biomedical DePIN
• EdgeCloud Distributed Training (Track 2.5) — ZK-proven model training jobs
• Cross-DePIN reputation ledger — verifiable GPU track records across Theta, Akash, Render, Bittensor

XFuel as AI DePIN Hub: How It Works

XFuel is the ZK settlement and orchestration layer for AI compute across decentralized networks. The core insight: AI agents and DePIN GPU providers need trustless, verifiable proof that compute actually happened — on the right hardware, producing the right output — before funds settle. XFuel provides that proof layer.

The Flow (How an Agent Uses XFuel)

1. INTENT SUBMISSION
   Agent (or circuit) → submitIntent(taskType, model, input_hash)
   └── Fee deposited → CoreRevenueSplitter (circuit-attributed)

2. COMPUTE ROUTING (6-tier DePIN priority router)
   Tier 1: Theta EdgeCloud       ← primary (GPU-native, CUDA persistent)
   Tier 2: RapidAPI              ← inference fallback
   Tier 3: MCP (local)           ← low-latency local inference
   Tier 4: Akash Network         ← decentralized GPU marketplace (Cosmos)
   Tier 5: Render Network        ← GPU marketplace (image/LLM workloads)
   Tier 6: AWS Bedrock           ← centralized last resort

3. ATTESTATION (on-chain proof of compute provenance)
   EdgeCloud node → attestEdgeCloudNode(nodeId, gpuFingerprint, petaflopsUsed)
   └── EdgeCloudAttestation stored on-chain with ProviderTag

4. ZK PROOF GENERATION
   SP1 Prover (CUDA) → groth16 proof of AITaskPublicValues
   └── Inputs: taskId, outputHash, feeBps, sender, chainId, blockHeight

5. ON-CHAIN SETTLEMENT
   ZKVerifierSP1.verifyProof(programVKey, publicValues, proofBytes)
   └── Nullifier stored (replay protection)
   └── Fee distributed: BBB 30% / GET 30% / Stakers 25% / Treasury 15%

6. CROSS-CHAIN RELAY (optional)
   Hyperlane.dispatch(destDomain, recipient, proofPayload)
   └── Bittensor EVM (964): dTAO stake-gated verification via precompile 0x0805
   └── Cosmos/IBC: ai-verifier CosmWasm (pending governance whitelist)

Why Theta First

Theta is uniquely positioned as the GPU-native backbone:

• EdgeCloud provides real CUDA GPU compute with on-demand + dedicated serving
• Subchain gives XFuel <2s finality at near-zero gas costs (tsub365001 testnet, tsub361001 mainnet)
• TDROP is the designated AI-to-AI incentive token — callers paying in TDROP receive 20% fee discount
• EdgeStore provides decentralized proof artifact storage (ZK proofs, model output attestations)
• Video API enables AI-generated media with on-chain DRM and provenance via VideoProvenance events

Theta as GPU Export Layer for Other Networks

The strategic insight beyond Theta-native value: Theta EdgeCloud can serve as the GPU compute backend for other DePIN networks. A Bittensor subnet or Akash deployment can route their GPU workloads through Theta EdgeCloud, get ZK-attested proof of delivery via XFuel, and settle payments cross-chain via Hyperlane. XFuel becomes the settlement and attestation bridge between DePIN networks — not just a Theta-native protocol.

Bittensor Subnet → TAOCircuit.submitTask()
   └── Routes to Theta EdgeCloud via DePIN router
   └── SP1 proof generated on EdgeCloud CUDA
   └── Proof relayed back via Hyperlane (Bittensor 945 → Theta 365)
   └── dTAO stake verified via precompile 0x0805
   └── Settlement on Bittensor, fee distribution on Theta

Agent-to-Agent (A2A) Economy

XFuel's A2ACircuit.sol enables autonomous agents to discover, bid, and settle work between each other:

formSwarm(objectiveHash) → joinSwarm(swarmId) → settleSwarmAgent(proof) → dissolveSwarm()

• Up to 18 agents per swarm (Almanak Monte Carlo lifecycle)
• ZK-verified micro-settlements at <50K gas per AgentSettled event
• x402-style payment channels: openChannel → claimChannel (repeatable) → closeChannel
• Sybil resistance via stake-weighted agent registration
• Reputation-priority routing: higher-reputation agents get first access to tasks

SP1 Circuit Message Types

COMPUTE_BID        → Agent requests GPU resources with ZK-verified escrow
COMPUTE_RESULT     → Provider attests job completion with output hash
INFERENCE_REQUEST  → Route ML inference to optimal DePIN provider
CAPABILITY_QUERY   → Discover peer agent capabilities across chains
DATA_ATTESTATION   → Certify dataset provenance on-chain
SETTLEMENT         → Settle cross-chain payments with nullifier protection

For Developers / Agents: Quick Integration

# Submit an AI task via M2M API
curl -X POST http://localhost:3002/task-request \
  -H "X-API-Key: $XFUEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message_type": "inference_request",
    "chain_id": "theta",
    "amount": "1000000",
    "sender": "0xYourAgentAddress",
    "model_id": "llama-3-70b",
    "input_hash": "0xabc..."
  }'

# Poll settlement status
curl http://localhost:3002/task-status/$TASK_ID

Full M2M API reference: docs/M2M_API.md

DePIN Synergy Incentives

Circuits that route through multiple DePIN tiers receive boost multipliers:

DEFAULT_CHAINS in ai-listener.js includes aptos_mainnet and sui_mainnet with Move VM type, gas targets, and ZK adapter configs.

Governance (veXF)

XFuel governance follows the Curve-style vote-escrowed model for progressive decentralization.

Lock XF tokens → receive veXF → vote on protocol parameters.

Power decays linearly to zero at lock expiry.

Governance Scope

# Create and simulate proposals
node governance/proposal-script.cjs --list
node governance/proposal-script.cjs --create allocation
node governance/proposal-script.cjs --simulate

Verifier Patches (Feb 2026)

The ZK verification layer received critical patches based on the v1.6 audit baseline. All patches are documented in docs/zk-patch-report.json.

Summary

Gas Baselines (Phase 2)

CosmWasm Prover

The xfuel-zk-verifier CosmWasm contract provides ZK proof verification for Cosmos/IBC chains, mirroring the EVM ZKVerifierSP1.sol functionality.

Architecture

• BN254 Groth16 pairing via arkworks (ark-bn254, ark-groth16) compiled to wasm32-unknown-unknown
• Circuit registry with per-circuit verification keys (CIRCUIT_VKEYS storage)
• Nullifier tracking prevents replay attacks across all verification calls
• Mock mode for testnet development; toggle via admin SetMockMode
• IBC-compatible events with ibc_source and total_verified attributes

Build

cd core-layer/wasm/zk-verifier
cargo build --release --target wasm32-unknown-unknown

# Production-optimized WASM (Docker required)
docker run --rm -v "$(pwd)":/code \
  --mount type=volume,source="$(basename "$(pwd)")_cache",target=/code/target \
  --mount type=volume,source=registry_cache,target=/usr/local/cargo/registry \
  cosmwasm/optimizer:0.16.0

Test Coverage (16 tests)

cd core-layer/wasm/zk-verifier && cargo test

EVM Prover (Phase 2)

The ZKVerifierSP1.sol contract was extended in Phase 2 with SP1-CC composed calls, Hyperlane cross-chain relay, and dTAO stake-gated verification for Bittensor EVM (Chain ID 964).

Architecture

ZKVerifierSP1 (Phase 2)
├── Core Verification (Phase 1)
│   ├── verifyProof — single SP1 proof verification
│   ├── verifyProofBatch — up to 20 proofs per tx
│   ├── Circuit Registry — register/remove program VKeys
│   ├── Nullifier Tracking — replay protection
│   └── Circuit Breaker — auto-pause at >5% failure rate
├── SP1-CC Composed Calls (Phase 2)
│   ├── verifyComposedCall — state-bound proof verification
│   └── Read → Compute → Verify model
├── Hyperlane Cross-Chain Relay (Phase 2)
│   ├── relayProofCrossChain — verify locally, dispatch to remote
│   └── Trusted remotes + domain allowlisting
└── dTAO Stake-Gated Verification (Phase 2)
    ├── verifyWithStakeCheck — precompile query before verify
    └── Bittensor Staking Precompile V2 (0x805)

Deployment (Bittensor EVM)

npx hardhat run deploy/bittensor-evm.cjs --network hardhat      # Local
npx hardhat run deploy/bittensor-evm.cjs --network bittensor-evm # Mainnet

Test Coverage (40 tests)

npx hardhat test core-layer/test/ZKVerifierSP1.test.cjs

Solana Prover (Phase 3)

The xfuel-solana-prover is a native Solana program (sBPF/ELF) that verifies SP1 Groth16 proofs on-chain using alt_bn128 precompile syscalls. Mirrors the EVM and CosmWasm architecture.

Build

cd solana-prover
cargo build-sbf       # Build the program
cargo test            # 35 unit tests

Deploy (Devnet)

cd solana-prover
chmod +x deploy/deploy-devnet.sh
./deploy/deploy-devnet.sh

Test Coverage (35 tests)

CU Benchmarks

Security

Cryptographic Security

• SP1 zkVM proofs — all settlements cryptographically verified; no trust assumptions
• Transparent setup — no trusted ceremony (SP1 uses FRI-based STARKs)
• Nonce-based replay protection — per-sender, per-chain monotonic nonces
• Nullifier tracking — on-chain mapping prevents proof reuse

Contract Security

• Role-based access control (ADMIN, OPERATOR, CIRCUIT_MANAGER) via OpenZeppelin
• Pausability and emergency circuit breakers (auto-pause at configurable failure threshold)
• Reentrancy guards on all external-calling functions
• Non-custodial architecture — users retain full key control

Multi-Prover Security

Edge Cases Handled

• Nonce desync — backend queries on-chain nonce; automatic retry with fresh nonce
• Backend downtime — event replay from Redis checkpoint (24h); PagerDuty alerting
• Bank-run scenario — 0.5% reverse fee + circuit breaker at >20% TVL/24h withdrawal

Audit Plan

Pre-Audit Notice: Beta launch for traction validation. Use at your own risk. Report vulnerabilities to [email protected].

Research Integration & Attribution

XFuel integrates third-party research with full credit to authors and sources. Formal citations, eprint links, and compliance notes are in docs/REFERENCES-AND-ATTRIBUTION.md.

We do not claim ownership of the names “zkGPT” or “Interstellar”; they refer to the cited works. When referencing XFuel’s use of these results, please cite the original papers.

Tech Stack

Frontend

Smart Contracts

Backend

ZK Proof Stack

Repo Structure

xfuel-protocol/
├── apps/                       # End-user / operator applications
│   ├── web/                    # ✅ CANONICAL frontend — xfuel.app (Vite + React 19 + Wagmi)
│   │                           #    Deployed to Vercel via vercel.json. This is the live app.
│   └── m2m-dashboard/          # 🔧 INTERNAL — local dev tool for testing M2M API endpoints
├── packages/                   # Publishable / shared libraries
│   ├── sdk/                    # JavaScript SDK (xfuel-sdk on npm) + runnable examples/
│   ├── mcp/                    # First-party MCP server (xfuel-mcp on npm)
│   ├── agent-skills/           # Agent Skills (front door for agents)
│   └── circuit-runtime/        # 20+ modular circuit handlers (JS) + Hardhat tests
├── services/                   # Long-running backend services
│   ├── gateway/                # Agent-facing API gateway (routing / payments / proving / receipts)
│   ├── sp1-prover/             # SP1 Rust RISC-V prover (EdgeCloud CUDA / Succinct network)
│   └── zkgpt-prover/           # zkGPT prover (Phase 1 mock + wrapper)
├── contracts/                  # Solidity + CosmWasm contracts
│   ├── core/                   # ZKVerifierSP1, CoreRevenueSplitter, veXFGovernance, SP1ProofHooks
│   ├── circuits/               # Circuit contracts (Solidity, audit scope)
│   ├── cosmwasm/               # CosmWasm contracts (Cosmos): zk-verifier, sp1-verifier, revenue-splitter
│   ├── governance/  interfaces/  legacy/  mocks/  test-helpers/
├── core-layer/                 # Settlement orchestration hub
│   ├── ai-listener.js          # Multi-prover event poller + normalizer + router
│   ├── sp1-hooks/              # Rust SP1 proof utilities
│   └── test/                   # Multi-prover tests
├── believer/                   # BelieverRound / AngelRound vesting contracts
├── deploy/                     # Deployment scripts + manifests
│   ├── testnet.cjs             # Theta Testnet (resumable)
│   ├── full.cjs                # Mainnet (Core + circuits + governance)
│   └── manifests/              # Deployment address manifests
├── scripts/                    # Build / deploy / dev helpers (scripts/dev/ = local launchers)
├── test/                       # Integration, system, hardening tests
├── cypress/                    # E2E browser tests
├── docs/                       # Extended documentation
├── WHITEPAPER.md               # Canonical whitepaper (v2.4)
├── CONTRIBUTING.md             # Contribution guidelines
└── README.md                   # This file

Development Setup

Prerequisites

• Node.js 20+ and npm 10+
• Rust toolchain + wasm32-unknown-unknown target (for CosmWasm)
• Hardhat (installed via npm)

Windows users: Hardhat and Node.js work natively on PowerShell. For CosmWasm/Rust builds, WSL 2 or Git Bash is recommended.

Bridge UI (Vite + React)

npm install
npm run dev          # Dev server
npm run build        # Production build

Backend Services + Agent API

cd services/gateway
npm install
npm run dev                # Theta listener
npm run ai-listener        # AI intent monitoring
npm run m2m-server         # Agent API (port 3002) — 7 endpoints + webhooks
pm2 start ecosystem.config.cjs  # Production (PM2)

xfuel.app Website

cd apps/web
npm install
npm run dev      # http://localhost:3000
npm run build    # Production build for Vercel

Smart Contracts

npx hardhat compile
npx hardhat test

Monitoring Dashboard

npx serve dashboard -l 3000
# Live contract health, gas profiles, failure prediction, 10s auto-refresh

Environment Variables

Create .env.local in the project root:

DEPLOYER_PRIVATE_KEY=0x...
ADMIN_ADDRESS=0x...
BBB_ADDRESS=0x...           # Buyback-burn recipient
GET_ADDRESS=0x...           # Growth & Expansion Treasury
STAKER_ADDRESS=0x...        # veXF staker rewards
TREASURY_ADDRESS=0x...      # Ops treasury
SP1_GATEWAY_ADDRESS=0x...   # SP1 Verifier Gateway (0x0 for mock)
XF_TOKEN_ADDRESS=0x...      # XF token for veXFGovernance (optional)

Full setup guide: docs/guides/LOCAL_DEV_SETUP.md

Testing

XFuel Protocol has 755+ tests covering unit, integration, system, hardening, multi-prover, governance, and phase expansion scenarios.

# Run everything (EVM)
npx hardhat compile && npx hardhat test

# Core Layer
npx hardhat test core-layer/test/ZKVerifierSP1.test.cjs
npx hardhat test core-layer/test/SP1ProofHooks.test.cjs

# Multi-Prover CoreListener (85 tests — EVM/Cosmos/Solana)
cd core-layer && node --test test/ai-listener.test.js

# Priority Circuits (69 tests)
npx hardhat test test/priority-circuits/PriorityCircuits.test.cjs

# Phase 4-6 suites
npx hardhat test test/phase4/ZKRollup.test.cjs
npx hardhat test test/phase5/AgentSwarms.test.cjs
npx hardhat test test/phase6/EcosystemExpansion.test.cjs

# Solana Prover (35 tests)
cd solana-prover && cargo test

# CosmWasm Verifier (16 tests)
cd core-layer/wasm/zk-verifier && cargo test

Test Matrix

Gas Benchmarks

Full testing guide: docs/TESTING.md

Deployment

Quick Deploy

# Local (Hardhat)
npx hardhat run deploy/deploy-full.cjs

# Theta Testnet (resumable — 23 contracts)
npx hardhat run deploy/testnet.cjs --network theta-testnet

# Theta Mainnet (production safety checks)
npx hardhat run deploy/mainnet.cjs --network theta-mainnet

# Phase 3+ Mainnet (Core + circuits + governance + Fee-to-Stake)
npx hardhat run deploy/full.cjs --network theta-mainnet

Deployment Scripts

Monitoring

# Live dashboard (failure prediction, gas profiles, RPC health)
npx serve dashboard -l 3000

# Fee analytics (Prometheus + Grafana)
cd services/gateway && node src/fee-analytics.js --format prometheus --watch --port 9100

# BelieverRound monitoring
node believer/monitoring-script.cjs --watch --webhook https://discord.com/api/webhooks/...

Full deployment guide: docs/DEPLOYMENT.md

Ecosystem Expansion (Phase 6)

Phase 6 delivers production-ready ecosystem infrastructure: partner integrations, oracle feeds, semantic caching, marketing automation, and the xfuel.app web application.

Partner Integrations

xfuel.app Website

Pages: Home, Bridge, Dashboard, Governance, Circuits, Staking, Treasury, Docs, Community, Grants, Monitoring, Theta AI

Stack: Vite + React 19 + TypeScript + Wagmi 2 + Vercel

$500M+ TVL Projections

Contributing

We welcome contributions from all backgrounds — Solidity veterans, Rust newcomers, or technical writers. XFuel Protocol is open-source and MIT-licensed.

Focus areas: Theta EdgeCloud integration, SP1 proof tuning, agent API extensions, CosmWasm optimization, frontend polish, documentation.

git clone https://github.com/YOUR_USERNAME/xfuel-protocol.git
git checkout -b feature/your-feature-name
npm install && npx hardhat compile && npx hardhat test
git commit -m "feat: add your feature"
git push origin feature/your-feature-name

Read CONTRIBUTING.md for full guidelines. Check GitHub Issues for open tasks.

Community & Support

Community Tools

# Discord bot (veXF simulator, circuit info, fee calc)
node community/bot.cjs

# AMA content generator
node community/ama-script.cjs --generate ama

# Campaign automation
node community/campaign-automation.cjs --campaign partner --partner almanak

License

MIT License — see LICENSE for details.

Quick Links

For Users:

• xfuel.app — Live beta (bridge, dashboard, AI inference, governance)
• WHITEPAPER.md — Full technical whitepaper (v2.4)
• believer-guide.md — BelieverRound vesting guide

For Developers:

• docs/M2M_API.md — Agent API reference (7 endpoints + webhooks)
• docs/CIRCUITS.md — Circuit specifications and handler code
• docs/Circuit-Design-and-Expansion.md — Full circuit history
• docs/Technical-Specifications.md — Multi-prover benchmarks
• docs/TESTING.md — Test suite guide and coverage matrix
• CONTRIBUTING.md — Contribution guidelines

For Operators:

• docs/DEPLOYMENT.md — Deployment guides (testnet + mainnet)
• services/sp1-prover/DEPLOY_ON_EDGECLOUD.md — Prover infrastructure
• docs/Growth-Expansion-Treasury.md — GET mechanics

For Governance:

• docs/governance/PERSISTENCE_WHITELIST_PROPOSAL.md — Governance template
• grant-templates/ — Grant application templates

Docs note: Some linked files may be works in progress. If missing, refer to the corresponding WHITEPAPER.md section or open an issue.

Built with ZK proofs and open-source conviction by the XFUEL team — pumping intelligence across AI ecosystems.