@chaoschain/sdk

v0.1.3

Published

3 months ago

TypeScript SDK for building verifiable AI agents on ChaosChain

0High
0Medium
0Low

sumeetc

chaoschain ai agents blockchain erc-8004 x402 eip-3009 payments crypto

ChaosChain TypeScript SDK

Production-ready TypeScript/JavaScript SDK for building verifiable AI agents with on-chain identity

The ChaosChain TypeScript SDK enables developers to build autonomous AI agents with:

ERC-8004 v1.0 ✅ 100% compliant - on-chain identity, validation and reputation
x402 payments using Coinbase's HTTP 402 protocol
Pluggable storage - IPFS, Pinata, Irys, 0G Storage
Type-safe - Full TypeScript support with exported types
Tree-shakeable - Optimized bundle size (< 100KB)

Zero setup required - all ERC-8004 v1.0 contracts are pre-deployed on 5 networks!

Quick Start

Installation

Basic Installation

# Core SDK with ERC-8004 + x402 + Local IPFS
npm install @chaoschain/sdk ethers@^6.9.0

With Optional Storage Providers

# Pinata (cloud IPFS)
npm install @chaoschain/sdk @pinata/sdk

# Irys (Arweave permanent storage)
npm install @chaoschain/sdk @irys/sdk

Basic Usage

import { ChaosChainSDK, NetworkConfig, AgentRole } from '@chaoschain/sdk';

// Initialize SDK
const sdk = new ChaosChainSDK({
  agentName: 'MyAgent',
  agentDomain: 'myagent.example.com',
  agentRole: AgentRole.SERVER,
  network: NetworkConfig.BASE_SEPOLIA,
  privateKey: process.env.PRIVATE_KEY,
  enablePayments: true,
  enableStorage: true
});

// 1. Register on-chain identity (ERC-8004)
const { agentId, txHash } = await sdk.registerIdentity();
console.log(`✅ Agent #${agentId} registered on-chain`);

// 2. Execute x402 payment
const payment = await sdk.executeX402Payment({
  toAgent: '0x20E7B2A2c8969725b88Dd3EF3a11Bc3353C83F70',
  amount: '1.5',
  currency: 'USDC'
});
console.log(`💰 Payment sent: ${payment.txHash}`);

// 3. Store evidence on IPFS
const cid = await sdk.storeEvidence({
  agentId: agentId.toString(),
  timestamp: Date.now(),
  result: 'analysis complete'
});
console.log(`📦 Evidence stored: ipfs://${cid}`);

// 4. Give feedback to another agent
const feedbackTx = await sdk.giveFeedback({
  agentId: 123n,
  rating: 95,
  feedbackUri: `ipfs://${cid}`
});
console.log(`⭐ Feedback submitted: ${feedbackTx}`);

Core Features

ERC-8004 v1.0 On-Chain Identity ✅

The SDK implements the full ERC-8004 v1.0 standard with pre-deployed contracts.

// Register agent identity
const { agentId, txHash } = await sdk.registerIdentity();

// Update agent metadata
await sdk.updateAgentMetadata(agentId, {
  name: 'MyAgent',
  description: 'AI analysis service',
  capabilities: ['market_analysis', 'sentiment'],
  supportedTrust: ['reputation', 'validation', 'tee-attestation']
});

// Give feedback (Reputation Registry)
await sdk.giveFeedback({
  agentId: otherAgentId,
  rating: 95,
  feedbackUri: 'ipfs://Qm...',
  feedbackData: {
    score: 95,
    context: 'excellent_service'
  }
});

// Request validation (Validation Registry)
await sdk.requestValidation({
  validatorAgentId: validatorId,
  requestUri: 'ipfs://Qm...',
  requestHash: 'proof_hash_here'
});

Pre-deployed addresses:

Hedera Testnet

IdentityRegistry: 0x4c74ebd72921d537159ed2053f46c12a7d8e5923
ReputationRegistry: 0xc565edcba77e3abeade40bfd6cf6bf583b3293e0
ValidationRegistry: 0x18df085d85c586e9241e0cd121ca422f571c2da6

0G Galileo Testnet

IdentityRegistry: 0x80043ed9cf33a3472768dcd53175bb44e03a1e4a
ReputationRegistry: 0x80045d7b72c47bf5ff73737b780cb1a5ba8ee202
ValidationRegistry: 0x80041728e0aadf1d1427f9be18d52b7f3afefafb

x402 Crypto Payments

Native integration with Coinbase's x402 HTTP 402 protocol:

// Execute payment
const payment = await sdk.executeX402Payment({
  toAgent: '0x20E7B2A2c8969725b88Dd3EF3a11Bc3353C83F70',
  amount: '10.0',
  currency: 'USDC',
  serviceType: 'ai_analysis'
});

// Create payment requirements (HTTP 402)
const requirements = sdk.createX402PaymentRequirements(
  '5.0',
  'USDC',
  'Premium AI Analysis'
);

// Calculate costs with fees
const costs = sdk.calculateTotalCost('10.0', 'USDC');
console.log(`Amount: ${costs.amount}, Fee: ${costs.fee}, Total: ${costs.total}`);

Features:

✅ Direct USDC transfers (Base, Ethereum, Linea)
✅ Automatic 2.5% protocol fee to ChaosChain
✅ ETH and USDC support
✅ Payment receipts and verification

Pluggable Storage Providers

Choose your storage backend:

import { 
  ChaosChainSDK, 
  IPFSLocalStorage, 
  PinataStorage 
} from '@chaoschain/sdk';

// Local IPFS (default)
const sdk = new ChaosChainSDK({
  agentName: 'MyAgent',
  network: 'base-sepolia',
  privateKey: process.env.PRIVATE_KEY
  // Uses LocalIPFS by default
});

// Or use Pinata
const sdk = new ChaosChainSDK({
  agentName: 'MyAgent',
  network: 'base-sepolia',
  privateKey: process.env.PRIVATE_KEY,
  storageProvider: new PinataStorage({
    jwt: process.env.PINATA_JWT,
    gatewayUrl: 'https://gateway.pinata.cloud'
  })
});

// Upload data
const result = await sdk.storage.upload({ data: 'evidence' });
console.log(`Uploaded to: ${result.uri}`);

// Download data
const data = await sdk.storage.download(result.cid);

Storage Options:

| Provider | Cost | Setup | Best For | |----------|------|-------|----------| | Local IPFS | 🆓 Free | ipfs daemon | Development | | Pinata | 💰 Paid | API keys | Production | | Irys | 💰 Paid | Wallet key | Permanent storage |

Supported Networks

ERC-8004 v1.0 contracts are pre-deployed on 5 networks:

| Network | Chain ID | Status | Features | |---------|----------|--------|----------| | Ethereum Sepolia | 11155111 | ✅ Active | ERC-8004 + x402 USDC | | Base Sepolia | 84532 | ✅ Active | ERC-8004 + x402 USDC | | Linea Sepolia | 59141 | ✅ Active | ERC-8004 + x402 USDC | | Hedera Testnet | 296 | ✅ Active | ERC-8004 | | 0G Testnet | 16600 | ✅ Active | ERC-8004 + Storage + Compute |

Simply change the network parameter - no other configuration needed!

API Reference

ChaosChainSDK

Main SDK class with all functionality.

Constructor Options

interface ChaosChainSDKConfig {
  agentName: string;              // Your agent's name
  agentDomain: string;            // Your agent's domain
  agentRole: AgentRole | string;  // 'server', 'client', 'validator', 'both'
  network: NetworkConfig | string; // Network to use
  privateKey?: string;            // Wallet private key
  mnemonic?: string;              // Or HD wallet mnemonic
  rpcUrl?: string;                // Custom RPC URL (optional)
  enablePayments?: boolean;       // Enable x402 payments (default: true)
  enableStorage?: boolean;        // Enable storage (default: true)
  storageProvider?: StorageProvider; // Custom storage provider
  computeProvider?: ComputeProvider; // Custom compute provider
  walletFile?: string;            // Load wallet from file
}

Key Methods

| Category | Method | Description | |----------|--------|-------------| | Identity | registerIdentity() | Register agent on-chain | | | getAgentMetadata(agentId) | Get agent metadata | | | updateAgentMetadata(agentId, metadata) | Update metadata | | Reputation | giveFeedback(params) | Submit feedback | | | getAgentStats(agentId) | Get reputation stats | | | revokeFeedback(feedbackId) | Revoke feedback | | Validation | requestValidation(params) | Request validation | | | respondToValidation(requestId, approved, uri) | Respond to validation | | | getValidationStats(agentId) | Get validation stats | | Payments | executeX402Payment(params) | Execute payment | | | getUSDCBalance() | Get USDC balance | | | getETHBalance() | Get ETH balance | | Storage | storage.upload(data) | Upload to storage | | | storage.download(cid) | Download from storage | | | storeEvidence(data) | Store evidence (convenience) | | Wallet | getAddress() | Get wallet address | | | getBalance() | Get native balance | | | signMessage(message) | Sign message |

Examples

Complete Agent Workflow

import { ChaosChainSDK, NetworkConfig, AgentRole } from '@chaoschain/sdk';

async function main() {
  // Initialize SDK
  const sdk = new ChaosChainSDK({
    agentName: 'AnalysisAgent',
    agentDomain: 'analysis.example.com',
    agentRole: AgentRole.SERVER,
    network: NetworkConfig.BASE_SEPOLIA,
    privateKey: process.env.PRIVATE_KEY,
    enablePayments: true,
    enableStorage: true
  });

  // 1. Register on-chain identity
  const { agentId, txHash } = await sdk.registerIdentity();
  console.log(`✅ Agent #${agentId} registered: ${txHash}`);

  // 2. Update metadata
  await sdk.updateAgentMetadata(agentId, {
    name: 'AnalysisAgent',
    description: 'AI market analysis service',
    capabilities: ['market_analysis', 'sentiment'],
    supportedTrust: ['reputation', 'validation']
  });

  // 3. Perform work and store evidence
  const evidence = {
    agentId: agentId.toString(),
    timestamp: Date.now(),
    analysis: { trend: 'bullish', confidence: 0.87 }
  };
  const cid = await sdk.storeEvidence(evidence);
  console.log(`📦 Evidence stored: ipfs://${cid}`);

  // 4. Receive payment
  const payment = await sdk.executeX402Payment({
    toAgent: sdk.getAddress(),
    amount: '15.0',
    currency: 'USDC',
    serviceType: 'analysis'
  });
  console.log(`💰 Payment received: ${payment.txHash}`);

  // 5. Client gives feedback
  await sdk.giveFeedback({
    agentId: agentId,
    rating: 95,
    feedbackUri: `ipfs://${cid}`
  });
  console.log(`⭐ Feedback submitted`);

  // 6. Check reputation
  const stats = await sdk.getAgentStats(agentId);
  console.log(`📊 Stats: ${stats.totalFeedback} feedbacks, avg rating: ${stats.averageRating}`);
}

main().catch(console.error);

Using Pinata Storage

import { ChaosChainSDK, PinataStorage, NetworkConfig } from '@chaoschain/sdk';

const sdk = new ChaosChainSDK({
  agentName: 'MyAgent',
  agentDomain: 'myagent.example.com',
  agentRole: 'server',
  network: NetworkConfig.BASE_SEPOLIA,
  privateKey: process.env.PRIVATE_KEY,
  storageProvider: new PinataStorage({
    jwt: process.env.PINATA_JWT,
    gatewayUrl: 'https://gateway.pinata.cloud'
  })
});

// Upload will now use Pinata
const result = await sdk.storage.upload({
  data: 'Important evidence',
  timestamp: Date.now()
});
console.log(`Stored on Pinata: ${result.uri}`);

Event Listening

// Listen for new agent registrations
sdk.onAgentRegistered((agentId, owner, uri) => {
  console.log(`New agent registered: #${agentId} by ${owner}`);
});

// Listen for feedback events
sdk.onFeedbackGiven((feedbackId, fromAgent, toAgent, rating) => {
  console.log(`Feedback #${feedbackId}: ${fromAgent} → ${toAgent} (${rating}/100)`);
});

// Listen for validation requests
sdk.onValidationRequested((requestId, requester, validator) => {
  console.log(`Validation requested: #${requestId} from ${requester}`);
});

Configuration

Environment Variables

# Network Configuration
PRIVATE_KEY=your_private_key_here
BASE_SEPOLIA_RPC_URL=https://sepolia.base.org
ETHEREUM_SEPOLIA_RPC_URL=https://rpc.sepolia.org

# Storage Providers
PINATA_JWT=your_pinata_jwt
PINATA_GATEWAY=https://gateway.pinata.cloud

# Optional: Custom RPC endpoints
LINEA_SEPOLIA_RPC_URL=https://rpc.sepolia.linea.build

TypeScript Configuration

The SDK is fully typed. Enable strict mode in your tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "esModuleInterop": true
  }
}

Build & Development

# Install dependencies
npm install

# Build the SDK
npm run build

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Lint code
npm run lint

# Format code
npm run format

# Type check
npm run typecheck

Bundle Size

The SDK is optimized for minimal bundle size:

Core SDK: ~80KB minified + gzipped
Tree-shakeable: Import only what you need
Zero dependencies in production (ethers, axios, dotenv, zod)

// Import only what you need
import { ChaosChainSDK, NetworkConfig } from '@chaoschain/sdk';

// Or import storage providers separately
import { PinataStorage } from '@chaoschain/sdk/providers/storage';

Testing

# Run all tests
npm test

# Run specific test file
npm test -- WalletManager.test.ts

# Run with coverage
npm run test:coverage

FAQ

Q: Do I need to deploy contracts?
A: No! All ERC-8004 v1.0 contracts are pre-deployed on 5 networks.

Q: What's the difference between Python and TypeScript SDK?
A: Both SDKs have feature parity. Use TypeScript for web/Node.js apps, Python for backend services.

Q: How do x402 payments work?
A: Real USDC/ETH transfers using Coinbase's HTTP 402 protocol. 2.5% fee goes to ChaosChain treasury.

Q: Which storage provider should I use?
A: Local IPFS for development, Pinata for production, Irys for permanent storage.

Q: Can I use this in the browser?
A: Yes! The SDK works in Node.js, browsers, React, Next.js, Vue, etc.

Contributing

We welcome contributions! Please see CONTRIBUTING.md.

License

MIT License - see LICENSE file.

Support

Issues: GitHub Issues
Discord: [ChaosChain Community]
Email: [email protected]

Build verifiable AI agents with on-chain identity and crypto payments. Start in minutes!