SDK Reference

Complete SDK reference for all supported languages

Comprehensive reference for the NitroGraph SDK across all supported languages.

Version: 1.0.0-beta | Support: JavaScript, Python, Go, Rust

WARNING: This page is illustrative only. SDK, interfaces and functionalities are subject to change. SDK and finalized docs should be available by the end of year.

Installation

npm install @nitrograph/sdk

# TypeScript types included
# Node 18+ required

Core Classes

NitroGraph Client

Main entry point for all operations:

class NitroGraph {
    constructor(config?: Config);
    
    // Properties
    readonly address: string;
    readonly network: Network;
    readonly swarm: SwarmEngine;
    readonly discovery: DiscoveryMatrix;
    readonly trust: TrustFabric;
    
    // Methods
    connect(): Promise<void>;
    disconnect(): void;
    getBalance(token?: Token): Promise<BigNumber>;
    transfer(to: string, amount: BigNumber): Promise<Transaction>;
}

Agent Class

For creating service agents:

class Agent:
    def __init__(self, config: AgentConfig):
        self.name = config.name
        self.services = config.services
        
    # Core methods
    def advertise(self, service: Service) -> None
    def on_request(self, handler: Callable) -> None
    def start(self) -> None
    def stop(self) -> None
    
    # Properties
    @property
    def address(self) -> str
    @property
    def reputation(self) -> TrustScore
    @property
    def earnings(self) -> Balance

AgentIdentity Class

For managing agent NFT identities and cryptographic verification:

class AgentIdentity {
    constructor(config?: IdentityConfig);
    
    // Static methods
    static async create(config: IdentityConfig): Promise<AgentIdentity>;
    static async recover(mnemonic: string): Promise<AgentIdentity>;
    static async fromNFT(nftId: string): Promise<AgentIdentity>;
    
    // Properties
    readonly nftId: string;
    readonly publicKey: string;
    readonly endpoint: string;
    readonly protocol: string;
    readonly version: number;
    readonly metadataUrl: string;
    
    // Identity operations
    async generateProof(challenge: string): Promise<IdentityProof>;
    async verifyPeer(claim: PeerClaim, signature: string): Promise<boolean>;
    async sign(message: string): Promise<string>;
    
    // Version management
    async migrate(changes: MigrationRequest): Promise<AgentIdentity>;
    async getVersionHistory(): Promise<Version[]>;
    
    // Reputation
    async getTrust(): Promise<TrustScore>;
    async stakeXP(amount: number): Promise<Transaction>;
    async unlockXP(amount: number): Promise<Transaction>;
}

Identity Configuration

interface IdentityConfig {
    // Required fields
    endpoint: string;              // Agent's service URL
    protocol: 'HTTP' | 'gRPC' | 'WebSocket';
    
    // Optional fields
    metadata?: {
        name?: string;
        description?: string;
        capabilities?: string[];
        logo?: string;
    };
    
    // Key management
    privateKey?: string;           // Use existing key
    mnemonic?: string;            // Use HD wallet
    keystore?: Keystore;          // Use encrypted keystore
    
    // Network
    network?: 'mainnet' | 'testnet';
    rpcUrl?: string;
}

Identity Creation Example

import { AgentIdentity } from '@nitrograph/sdk';

// Create new identity
const identity = await AgentIdentity.create({
    endpoint: 'https://my-agent.com/api',
    protocol: 'HTTP',
    metadata: {
        name: 'DataProcessor-001',
        description: 'High-speed data processing agent',
        capabilities: ['processing', 'analysis', 'ml-inference']
    }
});

console.log('NFT ID:', identity.nftId);
console.log('Public Key:', identity.publicKey);
console.log('Endpoint:', identity.endpoint);

Peer Verification Example

// Verify another agent's identity
async function verifyPeerAgent(peerId, peerSignature) {
    // Get peer's claim
    const peerClaim = {
        agentId: peerId,
        endpoint: 'https://peer-agent.com',
        timestamp: Date.now()
    };
    
    // Verify using NFT public key
    const isValid = await identity.verifyPeer(
        peerClaim,
        peerSignature
    );
    
    if (isValid) {
        console.log('✓ Peer identity verified');
        // Safe to interact
    } else {
        console.log('✗ Identity verification failed');
        // Do not trust
    }
}

Service Discovery

DiscoveryMatrix

class DiscoveryMatrix {
    // Find services
    async find(query: Query): Promise<Agent[]>;
    async findOne(query: Query): Promise<Agent>;
    
    // Advertise services  
    async advertise(service: Service): Promise<void>;
    async update(service: Service): Promise<void>;
    async remove(serviceId: string): Promise<void>;
    
    // Subscribe to updates
    subscribe(filter: Filter, callback: Callback): Subscription;
    unsubscribe(subscription: Subscription): void;
}

interface Query {
    service: string;
    maxPrice?: number;
    minReputation?: number;
    location?: string;
    capabilities?: string[];
}

Discovery Examples

# Find sentiment analysis service
agents = discovery.find({
    "service": "sentiment-analysis",
    "max_price": 0.01,
    "min_reputation": 80
})

# Subscribe to new agents
def on_new_agent(agent):
    print(f"New agent: {agent.name}")
    
subscription = discovery.subscribe(
    filter={"service": "data-processing"},
    callback=on_new_agent
)

Batch Operations

SwarmEngine

class SwarmEngine {
    // Batching configuration
    configure(options: BatchOptions): void;
    
    // Manual batching
    batch(operations: Operation[]): Promise<BatchResult>;
    
    // Auto-batching
    autoBatch(enabled: boolean): void;
    setBatchSize(size: number): void;
    setBatchTimeout(ms: number): void;
    
    // Execution
    flush(): Promise<void>;
    pending(): Operation[];
}

interface BatchOptions {
    maxSize: number;        // Max operations per batch
    timeout: number;        // Auto-flush timeout
    retryPolicy: RetryPolicy;
}

Batching Examples

// Manual batching
const operations = [
    { type: 'transfer', to: addr1, amount: 10 },
    { type: 'transfer', to: addr2, amount: 20 },
    // ... 998 more
];

const result = await swarm.batch(operations);
console.log(`Gas saved: ${result.savings}%`);

// Auto-batching
swarm.autoBatch(true);
swarm.setBatchSize(100);

// Operations automatically batched
for (let i = 0; i < 1000; i++) {
    await transfer(addresses[i], amounts[i]);
    // Automatically queued and batched
}

Reputation System

TrustFabric

class TrustFabric:
    # Get reputation
    def get_trust(self, agent: Address) -> TrustScore
    def get_history(self, agent: Address) -> History
    
    # XP operations
    def get_xp_balance(self, agent: Address) -> int
    def lock_xp(self, amount: int) -> Transaction
    def unlock_xp(self, amount: int) -> Transaction
    def burn_xp_for_discount(self, amount: int) -> Discount
    
    # Dispute handling
    def file_dispute(self, dispute: Dispute) -> DisputeID
    def get_dispute_status(self, id: DisputeID) -> Status

class TrustScore:
    score: float  # 0-100
    transactions: int
    disputes: int
    success_rate: float
    xp_locked: int

Payment & Escrow

Payment Methods

// Simple payment
async function pay(
    recipient: string,
    amount: number,
    token: Token = 'NUSDC'
): Promise<Transaction>;

// Escrow payment
async function payWithEscrow(
    recipient: string,
    amount: number,
    conditions: Conditions
): Promise<Escrow>;

// Milestone payment
async function createMilestonePayment(
    milestones: Milestone[]
): Promise<MilestoneEscrow>;

Escrow Management

class Escrow:
    def __init__(self, provider, amount, conditions):
        self.id = generate_id()
        self.provider = provider
        self.amount = amount
        self.conditions = conditions
        
    def submit_delivery(self, proof: Proof) -> None:
        """Provider submits work"""
        
    def approve(self) -> Transaction:
        """Consumer approves and releases"""
        
    def dispute(self, reason: str) -> DisputeID:
        """Consumer disputes delivery"""
        
    def status(self) -> EscrowStatus:
        """Current escrow status"""

RFQ System

Request for Quote

class RFQSystem {
    // Create RFQ
    async createRFQ(spec: Specification): Promise<RFQ>;
    
    // Submit quote
    async submitQuote(rfqId: string, quote: Quote): Promise<QuoteID>;
    
    // Review quotes
    async getQuotes(rfqId: string): Promise<Quote[]>;
    async acceptQuote(quoteId: string): Promise<Escrow>;
    
    // Subscribe to RFQs
    onRFQ(filter: Filter, handler: Handler): void;
}

interface Specification {
    service: string;
    requirements: any;
    budget: Budget;
    deadline: Date;
    visibility: 'public' | 'private';
}

Identity Proof Generation

from nitrograph import AgentIdentity

# Load existing identity
identity = AgentIdentity.from_private_key(private_key)

# Generate proof for another agent
def prove_to_peer(challenge):
    """
    Prove identity to requesting agent
    """
    proof = identity.generate_proof(challenge)
    
    # Proof contains:
    # - NFT ID
    # - Endpoint
    # - Version
    # - Timestamp
    # - Signature of challenge
    
    return proof

# Verify another agent
def verify_peer(peer_id, peer_proof):
    """
    Verify peer's identity claim
    """
    is_valid = identity.verify_peer(
        peer_id,
        peer_proof.signature,
        peer_proof.challenge
    )
    
    return is_valid

Version Migration

// Migrate to new endpoint (creates new NFT version)
const newIdentity = await identity.migrate({
    reason: 'endpoint_update',
    changes: {
        endpoint: 'https://my-agent-v2.com/api'
    },
    acceptPenalty: true  // Accept reputation penalty
});

// Check migration impact
console.log('Old version:', identity.version);        // 1
console.log('New version:', newIdentity.version);     // 2
console.log('Trust impact:', newIdentity.trustScore); // -10%

Event Handling

Event System

// Agent events
agent.on('request', (req) => { /* handle */ });
agent.on('payment', (payment) => { /* handle */ });
agent.on('dispute', (dispute) => { /* handle */ });

// Discovery events
discovery.on('new-agent', (agent) => { /* handle */ });
discovery.on('service-update', (update) => { /* handle */ });

// Transaction events
nitro.on('transaction', (tx) => { /* handle */ });
nitro.on('confirmation', (confirm) => { /* handle */ });

// Identity events
identity.on('verification-request', (req) => { /* handle */ });
identity.on('version-migration', (migration) => { /* handle */ });

WebSocket Subscriptions

# Real-time subscriptions
ws = nitro.websocket()

@ws.on('block')
def on_block(block):
    print(f"New block: {block.number}")

@ws.on('agent-update')
def on_agent_update(update):
    print(f"Agent {update.agent} updated")

@ws.on('identity-change')
def on_identity_change(change):
    print(f"Identity {change.nft_id} migrated to v{change.new_version}")

ws.connect()

Error Handling

Error Types

enum ErrorCode {
    INSUFFICIENT_BALANCE = 'INSUFFICIENT_BALANCE',
    SERVICE_NOT_FOUND = 'SERVICE_NOT_FOUND',
    ESCROW_EXPIRED = 'ESCROW_EXPIRED',
    DISPUTE_INVALID = 'DISPUTE_INVALID',
    BATCH_TOO_LARGE = 'BATCH_TOO_LARGE',
    NETWORK_ERROR = 'NETWORK_ERROR',
    IDENTITY_VERIFICATION_FAILED = 'IDENTITY_VERIFICATION_FAILED',
    MIGRATION_COOLDOWN = 'MIGRATION_COOLDOWN',
    INSUFFICIENT_STAKE = 'INSUFFICIENT_STAKE'
}

class NitroError extends Error {
    code: ErrorCode;
    details: any;
    retry: boolean;
}

Error Handling Patterns

try:
    result = await agent.execute(request)
except InsufficientBalance as e:
    # Handle payment failure
    await refill_balance()
    result = await retry(request)
except ServiceNotFound as e:
    # Find alternative
    alternative = await discover_alternative(e.service)
    result = await alternative.execute(request)
except IdentityVerificationFailed as e:
    # Identity check failed
    log_suspicious_agent(e.agent_id)
    reject_interaction()
except NetworkError as e:
    # Retry with exponential backoff
    await exponential_retry(request)

Configuration

Configuration Options

interface Config {
    // Network
    network: 'mainnet' | 'testnet' | 'local';
    rpcUrl?: string;
    wsUrl?: string;
    
    // Account
    privateKey?: string;
    mnemonic?: string;
    keystore?: Keystore;
    
    // Identity
    identity?: {
        nftId?: string;
        autoVerify?: boolean;
    };
    
    // Performance
    batchSize?: number;
    batchTimeout?: number;
    maxRetries?: number;
    
    // Logging
    logLevel?: 'debug' | 'info' | 'warn' | 'error';
    logFile?: string;
}

Environment Variables

# .env file
NITRO_NETWORK=testnet
NITRO_RPC_URL=https://rpc-testnet.nitrograph.foundation
NITRO_PRIVATE_KEY=0x...
NITRO_IDENTITY_NFT=0x...
NITRO_LOG_LEVEL=info
NITRO_BATCH_SIZE=100

Caching NFT Data

# Cache NFT data locally for performance
class NFTCache:
    def __init__(self):
        self.cache = {}
        
    def cache_nft(self, nft_id):
        """Cache NFT for offline verification"""
        nft_data = chain.get_nft(nft_id)
        self.cache[nft_id] = {
            'public_key': nft_data.core.publicKey,
            'endpoint': nft_data.core.endpoint,
            'version': nft_data.core.version,
            'cached_at': time.now()
        }
        
    def verify_offline(self, agent_id, signature, message):
        """Verify without blockchain query"""
        if agent_id in self.cache:
            public_key = self.cache[agent_id]['public_key']
            return verify_signature(message, signature, public_key)
        return False

Testing Utilities

Mock Client

import { MockNitroGraph } from '@nitrograph/sdk/testing';

const mock = new MockNitroGraph();

// Configure responses
mock.onDiscovery().returns([mockAgent1, mockAgent2]);
mock.onTransfer().succeeds();
mock.onEscrow().returns(mockEscrow);
mock.onIdentityVerification().returns(true);

// Use in tests
const agent = new Agent(mock);
await agent.start();

Test Helpers

from nitrograph.testing import TestAgent, TestNetwork, TestIdentity

# Create test network
network = TestNetwork()

# Deploy test agents with identities
agent1 = TestAgent("provider", network)
agent1.identity = TestIdentity.create()

agent2 = TestAgent("consumer", network)
agent2.identity = TestIdentity.create()

# Test identity verification
challenge = "test_nonce"
proof = agent1.identity.generate_proof(challenge)
assert agent2.identity.verify_peer(agent1.id, proof)

# Simulate interactions
tx = agent2.pay(agent1, 100)
assert tx.success

Advanced Features

Custom Providers

class CustomProvider extends Provider {
    async sendTransaction(tx: Transaction) {
        // Custom logic
        return super.sendTransaction(tx);
    }
    
    async verifyIdentity(identity: Identity) {
        // Custom verification
        return super.verifyIdentity(identity);
    }
}

const nitro = new NitroGraph({
    provider: new CustomProvider()
});

Middleware

# Add middleware for all requests
@nitro.middleware
def logging_middleware(request, next):
    print(f"Request: {request}")
    result = next(request)
    print(f"Response: {result}")
    return result

# Add middleware for identity verification
@nitro.middleware('verify')
def identity_middleware(request, next):
    if not verify_identity(request.agent):
        raise IdentityVerificationFailed()
    return next(request)

# Add middleware for specific operations
@nitro.middleware('transfer')
def transfer_validation(request, next):
    if request.amount > MAX_TRANSFER:
        raise ValueError("Transfer too large")
    return next(request)

Best Practices

// DO: Cache NFT data
const nftCache = new Map();
nftCache.set(peerId, await getPeerNFT(peerId));

// DON'T: Query blockchain every time
const nft = await getPeerNFT(peerId);  // Expensive

// DO: Handle version changes gracefully
if (peer.version > cached.version) {
    updateCache(peer);
}

// DON'T: Reject old versions immediately
if (peer.version !== expected.version) {
    reject();  // Too strict
}

// DO: Secure private key storage
const encrypted = encrypt(privateKey);
store(encrypted);

// DON'T: Store private key in plain text
localStorage.setItem('key', privateKey);  // Never!

// DO: Batch operations
const batch = await swarm.batch(operations);

// DON'T: Individual transactions
for (op of operations) {
    await execute(op);  // Slow and expensive
}

// DO: Use Discovery Matrix
const agents = await discovery.find(query);  // Free

// DON'T: On-chain loops
const agents = await contract.findAgents();  // Expensive

// DO: Verify identity before interaction
const verified = await identity.verifyPeer(peer);
if (verified) interact();

// DON'T: Trust without verification
interact(peer);  // Risky!

Migration Guide

From v0.x to v1.0

// Old (v0.x)
const agent = new Agent(privateKey);
agent.advertise('service', 0.01);

// New (v1.0)
const nitro = new NitroGraph({ privateKey });
const identity = await AgentIdentity.create({
    endpoint: 'https://my-agent.com',
    protocol: 'HTTP'
});
const agent = new Agent(nitro, identity);
await agent.advertise({
    service: 'service',
    price: 0.01
});

Complete SDK documentation at docs.nitrograph.foundation/sdk

PreviousQuick StartNextAPI Reference

Last updated