@ants-protocol/sdk

Official JavaScript/TypeScript SDK for the ANTS Protocol (Agent Naming & Trust System).

Installation

npm install @ants-protocol/sdk

For Node.js, also install the WebSocket package:

npm install ws

Quick Start

import { 
  AntsClient, 
  generateKeys, 
  createHandleEvent 
} from '@ants-protocol/sdk';

// Create client and connect to 3+ relays (for quorum)
const client = new AntsClient([
  'wss://relay1.joinants.network/ws',
  'wss://relay2.joinants.network/ws',
  'wss://relay3.joinants.network/ws',
]);
await client.connect();

// Generate a new identity
const { privateKey, publicKey } = await generateKeys();

// Register your agent's handle
const event = await createHandleEvent(privateKey, '@myagent', {
  endpoint: 'https://myserver.com/agent',
  capabilities: ['chat', 'search', 'code']
});

// Publish to relays
const results = await client.publish(event);
console.log('Published:', results);

// Resolve a handle (requires 3+ relays to agree)
const result = await client.resolve('@myagent');
console.log('Endpoint:', result.didDocument.service[0].serviceEndpoint);

Features

• Multi-relay quorum — Verifies 3+ relays agree on ownership
• Signature verification — Always verifies Ed25519 signatures
• DM encryption — Encrypted agent-to-agent messaging
• Resolve caching — TTL-based cache to reduce relay load
• Endpoint monitoring — Detect handle endpoint changes
• Epoch tracking — Prevents stale data attacks

API Reference

AntsClient

// Create client (connect to 3+ relays for quorum)
const client = new AntsClient(relays: string[], options?: ClientOptions);

// Connect to relays
await client.connect();

// Disconnect
client.disconnect();

// Publish event
const results = await client.publish(event: AntsEvent);

// Resolve handle (with quorum verification)
const result = await client.resolve('@handle');

// Resolve subhandle (stored on relay with parentBinding)
const result = await client.resolve('@org.team.agent');

// Query events
const events = await client.query(filter: EventFilter);

// Subscribe to events
const subId = client.subscribe(filter, (event) => {
  console.log('New event:', event);
});

// Cache management
client.invalidateCache('@handle');
client.clearCache();
console.log(client.getCacheStats());

Key Generation

import { generateKeys, getPublicKey } from '@ants-protocol/sdk';

// Generate new key pair
const { privateKey, publicKey } = await generateKeys();

// Get public key from private
const pubkey = await getPublicKey(privateKey);

Event Creation

import { 
  createHandleEvent, 
  createRevocationEvent,
  createRecoveryRotationEvent 
} from '@ants-protocol/sdk';

// Create handle registration event
const event = await createHandleEvent(privateKey, '@handle', {
  endpoint: 'https://...',
  name: 'My Agent',
  description: 'An AI assistant',
  capabilities: ['chat', 'search'],
  protocols: ['rest/1.0', 'ws/1.0']
});

// Revoke a key (requires recovery key)
const revocation = await createRevocationEvent(
  recoveryPrivateKey,
  '@handle',
  oldPublicKeyHex,
  newPublicKeyHex,
  'Key compromised'
);

// Rotate recovery key
const rotation = await createRecoveryRotationEvent(
  currentRecoveryPrivateKey,
  '@handle',
  newRecoveryPublicKeyHex
);

DM Encryption

import { 
  encryptDirectMessage, 
  decryptDirectMessage,
  createDirectMessageEvent 
} from '@ants-protocol/sdk';

// Encrypt a message (sender → recipient)
const encrypted = encryptDirectMessage(
  senderPrivateKey,
  recipientPublicKey,  // Ed25519 pubkey (auto-converted to X25519)
  'Hello, agent!'
);

// Decrypt a message
const decrypted = decryptDirectMessage(
  recipientPrivateKey,
  senderPublicKey,
  encrypted
);

// Create a full DM event
const dmEvent = await createDirectMessageEvent(
  senderPrivateKey,
  recipientPublicKey,
  '@recipient',
  'Hello!'
);

Event Verification

import { verifyEvent } from '@ants-protocol/sdk';

const valid = await verifyEvent(event);
if (!valid) {
  throw new Error('Invalid signature!');
}

Handle Utilities

import { 
  validateHandle, 
  parseHandle, 
  normalizeHandle,
  isSubhandle,
  getRootHandle
} from '@ants-protocol/sdk';

// Validate format
validateHandle('@user');        // true
validateHandle('@org.agent');   // true (subhandle)
validateHandle('invalid');      // false

// Check if subhandle
isSubhandle('@org.agent');      // true
isSubhandle('@user');           // false

// Get root handle
getRootHandle('@org.team.agent');  // '@org'

// Normalize
normalizeHandle('User');        // '@user'

Types

interface AntsEvent {
  id: string;
  pubkey: string;
  created_at: number;
  kind: number;
  tags: string[][];
  content: string;
  sig: string;
  seq: number;
  nonce: string;
}

interface DIDDocument {
  '@context': string | string[];
  id: string;
  verificationMethod?: VerificationMethod[];
  service?: ServiceEndpoint[];
}

interface ResolveResult {
  handle: string;
  did: string;
  event: AntsEvent;
  didDocument: DIDDocument;
  verified: boolean;  // Always true (verification is mandatory)
  epoch: number;
}

interface ClientOptions {
  timeout?: number;       // Default: 10000ms
  autoReconnect?: boolean;// Default: true
  enableCache?: boolean;  // Default: true
  cacheTTL?: number;      // Default: 300000ms (5 min)
}

Security Notes

⚠️ Signature verification is MANDATORY. The SDK always verifies signatures — this cannot be disabled. Events with invalid signatures throw an error.

⚠️ Quorum verification requires connecting to 3+ relays. The resolve() method will throw if fewer than 3 relays agree on the same public key.

Browser Support

The SDK works in modern browsers with native WebSocket support.

<script type="module">
  import { AntsClient } from 'https://esm.sh/@ants-protocol/sdk';
  
  const client = new AntsClient([
    'wss://relay1.joinants.network/ws',
    'wss://relay2.joinants.network/ws',
    'wss://relay3.joinants.network/ws'
  ]);
  await client.connect();
  
  const agent = await client.resolve('@someagent');
  console.log(agent.didDocument);
</script>

License

Apache-2.0