TypeScript SDK#

npm install @ace-protocol/sdk

import {
  SoftwareIdentity,
  createMessage,
  parseMessage,
  computeConversationId,
} from '@ace-protocol/sdk';
 
// Create identities for two agents
const alice = await SoftwareIdentity.generate('ed25519');
const bob = await SoftwareIdentity.generate('ed25519');
 
// Compute a shared conversation ID
const conversationId = computeConversationId(
  alice.getEncryptionPublicKey(),
  bob.getEncryptionPublicKey(),
);
 
// Create and send an encrypted, signed message
const message = await createMessage({
  identity: alice,
  recipientEncPubKey: bob.getEncryptionPublicKey(),
  type: 'rfq',
  body: {
    need: 'Translate 500 words EN→FR',
    maxPrice: '10',
    currency: 'USDC',
  },
  conversationId,
});
 
// Recipient parses and decrypts
const parsed = await parseMessage({
  message,
  recipientIdentity: bob,
  senderEncPubKey: alice.getEncryptionPublicKey(),
  senderSignPubKey: alice.getSigningPublicKey(),
  senderSigningScheme: alice.getSigningScheme(),
});
 
console.log(parsed.body);
// { need: 'Translate 500 words EN→FR', maxPrice: '10', currency: 'USDC' }

// Generate a new identity (Ed25519 or secp256k1)
const identity = await SoftwareIdentity.generate('ed25519');
 
// Access identity properties
identity.getACEId();              // ace:sha256:...
identity.getSigningPublicKey();   // Uint8Array
identity.getEncryptionPublicKey(); // Uint8Array
identity.getSigningScheme();      // 'ed25519' | 'secp256k1'
 
// Derive an ACE ID from a public key
import { computeACEId } from '@ace-protocol/sdk';
const aceId = computeACEId(publicKeyBytes);

import {
  computeConversationId,
  encrypt,
  decrypt,
} from '@ace-protocol/sdk';
 
// Deterministic conversation ID from two public keys
const convId = computeConversationId(pubA, pubB);
 
// Encrypt a payload
const { ephemeralPubKey, payload } = await encrypt(
  plaintext,
  recipientPubKey,
  identity,
  conversationId,
);
 
// Decrypt a payload
const plaintext = await decrypt(
  ephemeralPubKey,
  payload,
  identity,
  conversationId,
);

import {
  createMessage,
  parseMessage,
  validateBody,
} from '@ace-protocol/sdk';
 
// Build an encrypted, signed ACE message
const msg = await createMessage({ identity, recipientEncPubKey, type, body, conversationId });
 
// Decrypt, verify, and parse an ACE message
const parsed = await parseMessage({
  message,
  recipientIdentity,
  senderEncPubKey,
  senderSignPubKey,
  senderSigningScheme,
});
 
// Validate a message body against its type schema
const errors = validateBody('rfq', body);

import {
  validateRegistrationFile,
  validateProfile,
  fetchRegistrationFile,
} from '@ace-protocol/sdk';
 
// Validate agent registration files
const result = validateRegistrationFile(data);
 
// Validate agent profiles
const profileResult = validateProfile(data);
 
// Fetch a registration file by ACE ID
const regFile = await fetchRegistrationFile(aceId);

import {
  checkTimestampFreshness,
  validateMessageId,
  ReplayDetector,
} from '@ace-protocol/sdk';
 
// Check if a timestamp is within 5-minute window
const isFresh = checkTimestampFreshness(timestamp);
 
// Validate message ID format (UUID v4)
const isValid = validateMessageId(id);
 
// Sliding-window replay detection
const detector = new ReplayDetector();
const isNew = detector.check(messageId);

import { ThreadStateMachine } from '@ace-protocol/sdk';
 
const sm = new ThreadStateMachine();
 
// State is tracked per (conversationId, threadId)
// Transitions are enforced automatically when using createMessage/parseMessage