API Reference

RPC URL: https://rpc.nex-t1.ai
Chain ID: 2370
Currency: NZT
Block Explorer: https://explorer.nex-t1.ai

RPC URL: https://testnet-rpc.nex-t1.ai
Chain ID: 2371
Currency: NZT
Block Explorer: https://testnet.nex-t1.ai

RPC URL: http://localhost:8545
Chain ID: 1337

// Example: Only agent owner or delegate can update metadata
modifier onlyOwnerOrDelegate(uint256 agentId, bytes32 permission) {
    require(_isAuthorized(agentId, permission, msg.sender));
    _;
}

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1638360000

error AgentNotRegistered(uint256 agentId);
error NotAgentOwner(uint256 agentId, address expectedOwner, address actualCaller);
error ZeroAmount();
error AmountTooLarge(uint256 requested, uint256 available);
error InsufficientStake();

{
  "error": {
    "code": "AGENT_NOT_REGISTERED",
    "message": "Agent ID 12345 is not registered",
    "details": {
      "agentId": 12345
    }
  }
}

// Secure key management example
import { config } from 'dotenv';
import { SecretsManager } from '@aws-sdk/client-secrets-manager';

// Load from environment (development)
config();
const devKey = process.env.AI_AGENT_PRIVATE_KEY;

// Load from secrets manager (production)
const secretsManager = new SecretsManager({ region: 'us-east-1' });
const secret = await secretsManager.getSecretValue({
  SecretId: 'nexis/ai-agent/prod-key'
});
const prodKey = JSON.parse(secret.SecretString).privateKey;

// Use appropriate key based on environment
const agentKey = process.env.NODE_ENV === 'production' ? prodKey : devKey;
const wallet = new ethers.Wallet(agentKey, provider);

// ❌ Bad: Multiple sequential calls (high latency)
const agent1 = await agents.getAgent(1);
const agent2 = await agents.getAgent(2);
const agent3 = await agents.getAgent(3);

// ✅ Good: Batch read calls with multicall
import { Contract } from 'ethers';

const multicall = new Contract(multicallAddress, multicallABI, provider);

const calls = [
  { target: agentsAddress, callData: agents.interface.encodeFunctionData('getAgent', [1]) },
  { target: agentsAddress, callData: agents.interface.encodeFunctionData('getAgent', [2]) },
  { target: agentsAddress, callData: agents.interface.encodeFunctionData('getAgent', [3]) }
];

const results = await multicall.aggregate(calls);

// ✅ Better: Use list queries when available
const agentList = await agents.listAgents(0, 100); // Get 100 agents in one call

class RateLimitedAPI {
  constructor(provider, retryConfig = {}) {
    this.provider = provider;
    this.maxRetries = retryConfig.maxRetries || 3;
    this.baseDelay = retryConfig.baseDelay || 1000;
  }

  async callWithRetry(fn, ...args) {
    for (let attempt = 0; attempt < this.maxRetries; attempt++) {
      try {
        return await fn(...args);
      } catch (error) {
        // Check if rate limit error
        if (error.code === -32005 || error.message?.includes('rate limit')) {
          const delay = this.baseDelay * Math.pow(2, attempt);
          console.warn(`Rate limited, retrying in ${delay}ms...`);
          await new Promise(resolve => setTimeout(resolve, delay));
        } else {
          throw error; // Re-throw non-rate-limit errors
        }
      }
    }

    throw new Error('Max retries exceeded for rate limited request');
  }
}

// Usage
const api = new RateLimitedAPI(provider);

const balance = await api.callWithRetry(
  () => provider.getBalance(address)
);

// AI agent processing multiple inferences
class BatchInferenceProcessor {
  constructor(agents, wallet) {
    this.agents = agents;
    this.wallet = wallet;
    this.pendingInferences = [];
    this.batchSize = 10;
    this.batchTimeout = 30000; // 30 seconds
  }

  async recordInference(agentId, inputHash, outputHash, modelHash, taskId, proofURI) {
    this.pendingInferences.push({
      agentId, inputHash, outputHash, modelHash, taskId, proofURI
    });

    if (this.pendingInferences.length >= this.batchSize) {
      await this.processBatch();
    }
  }

  async processBatch() {
    if (this.pendingInferences.length === 0) return;

    const batch = this.pendingInferences.splice(0, this.batchSize);

    console.log(`Processing batch of ${batch.length} inferences...`);

    // Submit all inferences in parallel
    const txPromises = batch.map(inference =>
      this.agents.recordInference(
        inference.agentId,
        inference.inputHash,
        inference.outputHash,
        inference.modelHash,
        inference.taskId,
        inference.proofURI
      )
    );

    const txs = await Promise.all(txPromises);

    // Wait for all confirmations in parallel
    await Promise.all(txs.map(tx => tx.wait()));

    console.log(`Batch processed: ${batch.length} inferences recorded`);
  }

  // Start periodic batch processing
  startAutoProcessing() {
    setInterval(() => this.processBatch(), this.batchTimeout);
  }
}

// Usage
const processor = new BatchInferenceProcessor(agents, wallet);
processor.startAutoProcessing();

// Record inferences as they happen
await processor.recordInference(...inference1);
await processor.recordInference(...inference2);
// Automatically batched and submitted

// Efficiently monitor multiple agents for events
class AgentEventMonitor {
  constructor(agents, agentIds) {
    this.agents = agents;
    this.agentIds = agentIds;
    this.listeners = new Map();
  }

  async monitorInferences() {
    // Single filter for all agents
    const filter = this.agents.filters.InferenceRecorded(this.agentIds);

    // Batch event processing
    let eventBuffer = [];
    const flushInterval = 5000; // 5 seconds

    this.agents.on(filter, (...args) => {
      eventBuffer.push(args);
    });

    // Process events in batches
    setInterval(() => {
      if (eventBuffer.length > 0) {
        console.log(`Processing ${eventBuffer.length} inference events...`);
        this.processEventBatch(eventBuffer);
        eventBuffer = [];
      }
    }, flushInterval);
  }

  async processEventBatch(events) {
    // Bulk process events
    const inferences = events.map(event => ({
      agentId: event[0],
      inferenceId: event[1],
      timestamp: Date.now()
    }));

    // Bulk insert to database, update analytics, etc.
    await this.bulkUpdateDatabase(inferences);
  }
}

import { ethers } from 'ethers';

class RealtimeAIMonitor {
  constructor(wsUrl, contracts) {
    this.wsProvider = new ethers.WebSocketProvider(wsUrl);
    this.contracts = {
      agents: new ethers.Contract(
        contracts.agents,
        agentsABI,
        this.wsProvider
      ),
      tasks: new ethers.Contract(
        contracts.tasks,
        tasksABI,
        this.wsProvider
      ),
      subscriptions: new ethers.Contract(
        contracts.subscriptions,
        subscriptionsABI,
        this.wsProvider
      )
    };

    this.setupReconnection();
  }

  setupReconnection() {
    this.wsProvider.on('error', (error) => {
      console.error('WebSocket error:', error);
      this.reconnect();
    });

    this.wsProvider.on('close', () => {
      console.warn('WebSocket closed, reconnecting...');
      this.reconnect();
    });
  }

  async reconnect() {
    await new Promise(resolve => setTimeout(resolve, 5000));
    this.wsProvider = new ethers.WebSocketProvider(this.wsUrl);
    this.setupSubscriptions();
  }

  setupSubscriptions() {
    // Monitor new agent registrations
    this.contracts.agents.on('AgentRegistered', (owner, agentId, metadata) => {
      console.log('New agent registered:', { owner, agentId });
      this.onNewAgent({ owner, agentId, metadata });
    });

    // Monitor AI inferences
    this.contracts.agents.on('InferenceRecorded', (
      agentId, inferenceId, inputHash, outputHash, modelHash, taskId
    ) => {
      console.log('New inference:', { agentId, inferenceId });
      this.onNewInference({ agentId, inferenceId, taskId });
    });

    // Monitor task lifecycle
    this.contracts.tasks.on('TaskCreated', (taskId, creator, asset, reward) => {
      console.log('New task:', { taskId, creator, reward });
      this.onNewTask({ taskId, creator, reward });
    });

    this.contracts.tasks.on('TaskCompleted', (taskId, agentId, recipient, reward) => {
      console.log('Task completed:', { taskId, agentId, reward });
      this.onTaskCompleted({ taskId, agentId, reward });
    });

    // Monitor subscriptions
    this.contracts.subscriptions.on('SubscriptionCreated', (
      subId, subscriber, agentId, asset, amountPerEpoch
    ) => {
      console.log('New subscription:', { subId, subscriber, agentId });
      this.onNewSubscription({ subId, subscriber, agentId, amountPerEpoch });
    });

    // Monitor payment streams
    this.contracts.subscriptions.on('StreamCreated', (
      streamId, payer, agentId, asset, totalAmount
    ) => {
      console.log('New stream:', { streamId, payer, agentId });
      this.onNewStream({ streamId, payer, agentId, totalAmount });
    });
  }

  // Implement handlers
  onNewAgent(data) { /* Handle new agent */ }
  onNewInference(data) { /* Handle new inference */ }
  onNewTask(data) { /* Handle new task */ }
  onTaskCompleted(data) { /* Handle completed task */ }
  onNewSubscription(data) { /* Handle new subscription */ }
  onNewStream(data) { /* Handle new stream */ }
}

// Usage
const monitor = new RealtimeAIMonitor('wss://testnet-ws.nex-t1.ai', {
  agents: '0x5FbDB2315678afecb367f032d93F642f64180aa3',
  tasks: '0xe7f1725E7734CE288F8367e1Bb143E90bb3F0512',
  subscriptions: '0xCf7Ed3AccA5a467e9e704C703E8D87F634fB0Fc9'
});

monitor.setupSubscriptions();

// Process blockchain events as streams
import { pipeline } from 'stream/promises';
import { Transform } from 'stream';

class EventStream extends Transform {
  constructor(contract, eventName) {
    super({ objectMode: true });
    this.contract = contract;
    this.eventName = eventName;

    this.contract.on(eventName, (...args) => {
      this.push({ eventName, args, timestamp: Date.now() });
    });
  }

  _transform(chunk, encoding, callback) {
    callback(null, chunk);
  }
}

class EventProcessor extends Transform {
  constructor() {
    super({ objectMode: true });
  }

  _transform(event, encoding, callback) {
    // Process event
    const processed = this.processEvent(event);
    callback(null, processed);
  }

  processEvent(event) {
    // Add custom processing logic
    return {
      ...event,
      processed: true,
      processedAt: Date.now()
    };
  }
}

// Usage
const eventStream = new EventStream(agents, 'InferenceRecorded');
const processor = new EventProcessor();

await pipeline(
  eventStream,
  processor,
  async function* (source) {
    for await (const event of source) {
      console.log('Processed event:', event);
      // Store in database, trigger webhooks, etc.
    }
  }
);

class AgentAPIError extends Error {
  constructor(message, code, details) {
    super(message);
    this.name = 'AgentAPIError';
    this.code = code;
    this.details = details;
  }
}

class AgentErrorHandler {
  static async handleTransaction(txFunction) {
    try {
      const tx = await txFunction();
      const receipt = await tx.wait();

      if (receipt.status === 0) {
        throw new AgentAPIError(
          'Transaction failed',
          'TX_FAILED',
          { txHash: receipt.hash }
        );
      }

      return receipt;
    } catch (error) {
      return this.categorizeError(error);
    }
  }

  static categorizeError(error) {
    // Network errors
    if (error.code === 'NETWORK_ERROR') {
      throw new AgentAPIError(
        'Network connection failed',
        'NETWORK_ERROR',
        { originalError: error.message }
      );
    }

    // Insufficient funds
    if (error.code === 'INSUFFICIENT_FUNDS') {
      throw new AgentAPIError(
        'Insufficient balance for transaction',
        'INSUFFICIENT_FUNDS',
        { required: error.info?.required, balance: error.info?.balance }
      );
    }

    // Contract revert
    if (error.code === 'CALL_EXCEPTION') {
      const reason = this.parseRevertReason(error);
      throw new AgentAPIError(
        `Contract reverted: ${reason}`,
        'CONTRACT_REVERT',
        { reason, data: error.data }
      );
    }

    // Rate limit
    if (error.code === -32005) {
      throw new AgentAPIError(
        'Rate limit exceeded',
        'RATE_LIMIT',
        { retryAfter: error.data?.reset }
      );
    }

    // Unknown error
    throw new AgentAPIError(
      'Unknown error occurred',
      'UNKNOWN_ERROR',
      { originalError: error }
    );
  }

  static parseRevertReason(error) {
    // Extract custom error or revert string
    if (error.data) {
      try {
        // Parse custom error selector
        const selector = error.data.slice(0, 10);
        // Map to human-readable message
        return this.errorMessages[selector] || 'Unknown revert reason';
      } catch {
        return error.reason || 'Transaction reverted';
      }
    }
    return error.reason || 'Transaction reverted';
  }

  static errorMessages = {
    '0x1234abcd': 'Agent not registered',
    '0x5678efgh': 'Insufficient stake',
    // Add more custom error mappings
  };
}

// Usage
try {
  const receipt = await AgentErrorHandler.handleTransaction(
    () => agents.recordInference(...)
  );
  console.log('Inference recorded successfully');
} catch (error) {
  if (error.code === 'INSUFFICIENT_FUNDS') {
    console.error('Need more funds:', error.details);
  } else if (error.code === 'CONTRACT_REVERT') {
    console.error('Contract error:', error.details.reason);
  } else {
    console.error('Unexpected error:', error);
  }
}