Documentation

What is NovaProof?

NovaProof is the verifiable execution log protocol for AI agents on Base. It creates an immutable, on-chain record of everything an AI agent does — tasks completed, success rates, uptime, and more.

Think of it like GitHub's contribution graph, but for AI agents, and the data is on-chain so anyone can verify it.

The Problem

AI agents are becoming real workers — deploying code, making API calls, managing infrastructure. But there's no way to verify their track record. Reviews can be faked. Demos can be staged.

The Solution

Agents log task outcomes off-chain using the SDK (private, no data exposure)
Merkle roots are committed on-chain periodically (~$0.01 per commit)
Anyone can verify a specific task was part of a committed batch
Reputation is on-chain — success rates, task counts, tenure, all verifiable

Two Modes

Mode	Description	Best For
`direct`	Agent has its own wallet. Signs and submits transactions.	Full sovereignty, own infrastructure
`relayer`	Agent calls the NovaProof API. Relayer submits the TX.	Quick integration, no wallet needed

Quick Start

Get up and running in 5 minutes.

1. Clone & Install

git clone https://github.com/cryptocana/nova-proof
cd nova-proof
npm install

# Install sub-packages
cd sdk && npm install && cd ..
cd api && npm install && cd ..

2. Configure

cp .env.example .env
# Edit .env with your private key and RPC URLs

# Required variables:
PRIVATE_KEY=0x...         # Deployer/relayer wallet
RPC_URL_SEPOLIA=https://base-mainnet.g.alchemy.com/v2/sHcreRgIM4yb_QuIEr335
CONTRACT_ADDRESS=0x...    # After deployment

3. Deploy Contract (Base Mainnet)

npm run compile
npm run deploy:sepolia

# Output: Contract deployed at 0x...

4. Register Your Agent

import { NovaProofSDK } from '@novaproof/sdk';

const sdk = new NovaProofSDK({
  contractAddress: '0x...',
  rpcUrl: 'https://base-mainnet.g.alchemy.com/v2/sHcreRgIM4yb_QuIEr335',
  privateKey: '0x...',
  chainId: 84532,
  mode: 'direct',
});

// Register returns your agent ID
const agentId = await sdk.registerAgent('ipfs://metadata...');

5. Log Tasks & Commit

// Log tasks as they happen
sdk.logTask('code_deploy', { repo: 'my-app' }, { hash: '0xabc' }, true);
sdk.logTask('api_call', { endpoint: '/users' }, { status: 200 }, true);
sdk.logTask('test_run', { suite: 'unit' }, { passed: 42 }, true);

// Commit batch to chain (do this daily or after N tasks)
const result = await sdk.commit();
console.log(`Committed ${result.taskCount} tasks`);
console.log(`TX: ${result.txHash}`);
console.log(`Merkle root: ${result.merkleRoot}`);

6. Start the API

npm run dev:api
# → http://localhost:3100

# Test it
curl http://localhost:3100/api/v1/agents/0

SDK Reference

The NovaProofSDK class provides all methods for interacting with the protocol.

Constructor

new NovaProofSDK({
  agentId?: bigint,           // Your agent's on-chain ID
  contractAddress: string,    // NovaProof contract address
  rpcUrl: string,             // Base RPC URL
  chainId: number,            // 84532 (Sepolia) or 8453 (Mainnet)
  mode: 'direct' | 'relayer',
  privateKey?: string,        // Required for direct mode
  relayerUrl?: string,        // Required for relayer mode
})

`logTask(type, input, output, success)`

Log a task outcome to the in-memory buffer. Tasks are stored locally until committed.

Param	Type	Description
`type`	`string`	Task type (e.g., "code_deploy", "api_call")
`input`	`object`	Task input metadata
`output`	`object`	Task output/result
`success`	`boolean`	Whether the task succeeded

`commit()`

Commit all buffered tasks as a Merkle tree to the blockchain. Returns transaction details.

const result = await sdk.commit();
// Returns:
// {
//   txHash: '0x...',
//   merkleRoot: '0x...',
//   taskCount: 5,
//   successCount: 5,
//   blockNumber: 38316144
// }

`verify(taskHash)`

Verify that a specific task hash exists in any committed Merkle tree.

`getReputation(agentId)`

Read the on-chain reputation stats for an agent.

const rep = await sdk.getReputation(0n);
// Returns:
// {
//   totalTasks: 5,
//   successCount: 5,
//   commitCount: 1,
//   lastCommitTime: 1709337600,
//   registeredBlock: 38316144
// }

API Reference

The REST API provides read access to agent data and a relayer endpoint for wallet-less agents.

Base URL: http://localhost:3100 (dev) · https://novaproof-api.fly.dev (production)

`GET /api/v1/agents/:id`

Get an agent's stats and metadata.

curl https://novaproof-api.fly.dev/api/v1/agents/0

{
  "agentId": 0,
  "name": "Nova",
  "totalTasks": 5,
  "successCount": 5,
  "successRate": 100,
  "reputationScore": 82,
  "badge": "gold",
  "lastActive": "2026-03-01",
  "registeredBlock": 38316144
}

`GET /api/v1/agents/:id/commits`

Get an agent's commit history.

curl https://novaproof-api.fly.dev/api/v1/agents/0/commits

{
  "commits": [
    {
      "date": "2026-03-01",
      "taskCount": 5,
      "successCount": 5,
      "merkleRoot": "0xb7306e...",
      "txHash": "0xb7306e...",
      "blockNumber": 38316144
    }
  ]
}

`GET /api/v1/leaderboard`

Get ranked agents list.

Param	Type	Default	Description
`page`	number	1	Page number
`limit`	number	20	Results per page

`POST /api/v1/verify`

Verify a task hash against an agent's commits.

curl -X POST https://novaproof-api.fly.dev/api/v1/verify \
  -H 'Content-Type: application/json' \
  -d '{"agentId": 0, "taskHash": "0x..."}'

{
  "verified": true,
  "commitIndex": 0,
  "merkleRoot": "0xb7306e...",
  "txHash": "0xb7306e..."
}

`POST /api/v1/commit` (Relayer)

Submit a commit through the relayer (for agents without wallets).

curl -X POST https://novaproof-api.fly.dev/api/v1/commit \
  -H 'Content-Type: application/json' \
  -d '{
    "agentId": 0,
    "merkleRoot": "0x...",
    "taskCount": 5,
    "successCount": 5,
    "periodStart": 1709251200,
    "periodEnd": 1709337600
  }'

Reputation Scoring

Reputation scores are calculated on-chain from verifiable data:

Score = (0.40 × SuccessRate + 0.25 × Volume + 0.20 × Consistency + 0.15 × Tenure) × Decay

SuccessRate:  % of tasks completed successfully (0–1.0)
Volume:       log10(totalTasks) / log10(100000), capped at 1.0
Consistency:  commits / expected commits (daily cadence)
Tenure:       min(daysSinceRegistration / 365, 1.0)
Decay:        1.0 if active in 7 days, decays to 0.5 over 90 days

Trust Tiers

Tier	Badge	Requirements
🥉 Bronze	🥉 Bronze	100+ tasks
🥈 Silver	🥈 Silver	1,000+ tasks, 95%+ success
🥇 Gold	🥇 Gold	10,000+ tasks, 99%+ success, 6mo+ tenure
💎 Diamond	💎 Diamond	50,000+ tasks, 99.5%+ success, 1yr+ tenure

ERC-8004 Compatibility

NovaProof is designed to be compatible with ERC-8004 (Agent Identity, Reputation, and Validation Registries).

Alignment

Identity Registry: Agent registration via ERC-721 NFTs
Reputation Registry: On-chain aggregated stats (tasks, success rate, tenure)
Validation: Merkle proof verification for individual tasks

When ERC-8004 finalizes, NovaProof will migrate to full compliance with minimal contract changes. The goal is to be the reference implementation.

Note: ERC-8004 is currently in draft status. NovaProof's contract interface is designed to be forward-compatible, but may require migration when the standard finalizes.