Sentra Protocol SDK

TypeScript SDK for interacting with the sentra AI Agent Payment Protocol.

Installation

npm install @actualte/sentra ethers

Quick Start

import { SentraClient, ethers } from '@actualte/sentra';

// Initialize client
const provider = new ethers.JsonRpcProvider('https://base-mainnet.g.alchemy.com/v2/YOUR_KEY');
const signer = new ethers.Wallet('YOUR_PRIVATE_KEY', provider);

const client = new SentraClient({
  provider,
  signer,
  contracts: {
    identityRegistry: '0x...',
    budgetController: '0x...',
    serviceEscrow: '0x...'
  }
});

// Register an agent
const tx = await client.registerAgent(
  agentAddress,
  'did:sentra:agent:001',
  publicKeyX,
  publicKeyY
);
await tx.wait();

// Set budget policy
await client.setBudgetPolicy(
  agentAddress,
  ethers.parseEther('10'), // 10 ETH daily limit
  ethers.parseEther('1'),  // 1 ETH per transaction
  60 // 60 seconds between transactions
);

// Authorize payment
await client.authorizePayment(
  agentAddress,
  ethers.parseEther('0.5')
);

// Create escrow
const commitmentHash = ethers.keccak256(ethers.toUtf8Bytes('service-data'));
const timeout = Math.floor(Date.now() / 1000) + 3600; // 1 hour

await client.createEscrow(
  serviceProviderAddress,
  'did:sentra:service:001',
  commitmentHash,
  timeout,
  ethers.parseEther('0.5')
);

API Reference

Agent Management

registerAgent(address, did, publicKeyX, publicKeyY)

Register a new AI agent with W3C DID.

await client.registerAgent(
  '0xAgentAddress',
  'did:sentra:agent:12345',
  publicKeyX,
  publicKeyY
);

getAgent(address)

Get agent details by address.

const agent = await client.getAgent('0xAgentAddress');
console.log(agent.did); // did:sentra:agent:12345
console.log(agent.reputationScore); // 500n

verifyAgent(address)

Check if agent is eligible for payments.

const isValid = await client.verifyAgent('0xAgentAddress');

Budget Management

setBudgetPolicy(address, dailyLimit, perTxLimit, minTime)

Set spending limits for an agent.

await client.setBudgetPolicy(
  agentAddress,
  ethers.parseEther('100'), // Daily limit
  ethers.parseEther('10'),  // Per-tx limit
  120 // 2 minutes between transactions
);

getBudgetPolicy(address)

Get current budget policy.

const policy = await client.getBudgetPolicy(agentAddress);
console.log(policy.dailyLimit); // 100000000000000000000n
console.log(policy.dailySpent); // 50000000000000000000n

authorizePayment(address, amount, currency?)

Authorize a payment for an agent.

await client.authorizePayment(
  agentAddress,
  ethers.parseEther('5'),
  ethers.ZeroAddress // Native token
);

Service Escrow

createEscrow(provider, serviceDid, hash, timeout, amount)

Create escrow for service delivery.

await client.createEscrow(
  '0xProviderAddress',
  'did:sentra:service:ai-compute',
  commitmentHash,
  Date.now() / 1000 + 3600, // 1 hour
  ethers.parseEther('2')
);

getEscrow(escrowId)

Get escrow details.

const escrow = await client.getEscrow(0);
console.log(escrow.amount); // 2000000000000000000n
console.log(escrow.fulfilled); // false

submitDeliveryProof(escrowId, proof)

Submit ZK proof and release payment.

await client.submitDeliveryProof(0, proofBytes);

refundEscrow(escrowId)

Refund escrow after timeout.

await client.refundEscrow(0);

Event Listeners

Listen for on-chain events:

// Agent registration
client.onAgentRegistered((agentId, did, owner) => {
  console.log(`Agent ${did} registered with ID ${agentId}`);
});

// Payment authorization
client.onPaymentAuthorized((agentId, agent, amount, currency) => {
  console.log(`Payment of ${amount} authorized for agent ${agent}`);
});

// Escrow creation
client.onEscrowCreated((escrowId, agent, provider, amount) => {
  console.log(`Escrow ${escrowId} created for ${amount}`);
});

// Payment release
client.onPaymentReleased((escrowId, agent, amount) => {
  console.log(`Payment ${amount} released from escrow ${escrowId}`);
});

Multi-Network Support

The SDK works on all supported networks:

// Base Mainnet
const baseProvider = new ethers.JsonRpcProvider('https://mainnet.base.org');

// Polygon
const polygonProvider = new ethers.JsonRpcProvider('https://polygon-rpc.com');

// Avalanche
const avaxProvider = new ethers.JsonRpcProvider('https://api.avax.network/ext/bc/C/rpc');

// Ethereum
const ethProvider = new ethers.JsonRpcProvider('https://eth.llamarpc.com');

Error Handling

try {
  await client.authorizePayment(agentAddress, ethers.parseEther('100'));
} catch (error) {
  if (error.message.includes('Exceeds daily limit')) {
    console.error('Daily budget exceeded');
  } else if (error.message.includes('Agent not registered')) {
    console.error('Agent must be registered first');
  }
}

TypeScript Types

All methods are fully typed:

import type { Agent, BudgetPolicy, Escrow } from '@actualte/sentra';

const agent: Agent = await client.getAgent(address);
const policy: BudgetPolicy = await client.getBudgetPolicy(address);
const escrow: Escrow = await client.getEscrow(0);

License

MIT