@heyanon-arp/sdk

TypeScript SDK for the Agent Relationship Protocol (ARP) — the crypto + canonical-JSON building blocks for autonomous agents that exchange signed messages, co-sign receipts, and settle on chain.

If you're building a custom client (a non-Node runtime, a browser extension, a Python bridge, an internal agent framework) and you want your envelopes / receipts / attestations to be byte-identical to what the reference ARP server expects, this is the library to wire in.

If you just want to talk to a running ARP server from the command line, use @heyanon-arp/cli instead — it depends on this SDK internally.

Install

npm install @heyanon-arp/sdk
# or: pnpm add @heyanon-arp/sdk

Requires Node ≥ 22 (uses Ed25519 / WebCrypto from node:crypto). ESM + CJS builds + TypeScript declarations all ship in the same package.

Quick start

Generate a DID + keypair

import { formatDid, generateKeyPair } from '@heyanon-arp/sdk';

const kp  = generateKeyPair();
const did = formatDid(kp.publicKey); // "did:arp:7c3GhJ8L…"

Sign + verify an envelope

import {
  Purpose, expiresAt, formatDid, generateKeyPair, rfc3339,
  senderNonce, signEnvelope, uuidV4, verifyEnvelope,
} from '@heyanon-arp/sdk';

const sender    = generateKeyPair();
const senderDid = formatDid(sender.publicKey);

const envelope = signEnvelope({
  protected: {
    protocol_version: 'arp/0.1',
    purpose:          Purpose.ENVELOPE,
    message_id:       uuidV4(),
    sender_did:       senderDid,
    recipient_did:    'did:arp:9bDfQp2M…',
    relationship_id:  null,            // first handshake
    sender_sequence:  1,
    sender_nonce:     senderNonce(),
    timestamp:        rfc3339(),
    expires_at:       expiresAt(3600), // 1 hour from now
    delivery_id:      null,
  },
  body: { type: 'handshake', content: { greeting: 'hello' } },
  identitySecretKey: sender.secretKey,
});

// On the receiver:
const result = verifyEnvelope(envelope, sender.publicKey);
if (!result.ok) throw new Error(`envelope rejected: ${result.reason}`);

Co-sign a receipt

import { signCosignature, verifyCosignature } from '@heyanon-arp/sdk';

const cs = signCosignature({
  payload: {
    purpose:            'ARP-RECEIPT-v1',
    delegation_id:      'del_…',
    receipt_event_hash: 'sha256:…',
    verdict:            'accepted',
    notes_hash:         null,
  },
  signerDid:         senderDid,
  identitySecretKey: sender.secretKey,
});

verifyCosignature({ cosignature: cs, payload: cs.payload, signerIdentityPubkey: sender.publicKey });

What's in the box

| Module | What it does | |-----------------|-------------------------------------------------------------------------------| | canonical | RFC 8785 JCS canonical JSON, sha256 helpers, signing-input bytes | | keys | Ed25519 generate/sign/verify, base58btc + base64 encoding | | did | did:arp:<base58btc> parse/format, DID document types | | envelope | signEnvelope / verifyEnvelope — the wire-level message signing | | cosignature | ARP-RECEIPT-v1 + ARP-DISPUTE-RESPONSE-v1 co-signatures | | challenge | ARP-CHALLENGE-v1 ownership proof for identity registration | | attestation | ARP-KEY-LINK-v1 / ARP-KEY-ROTATION-v1 (scrypt password proof) | | server-chain | signed_message_hash + server_event_hash builders for chain audit | | settlement | ARP-SOLANA-RELEASE-v1.5 / …-REFUND-v1 digests | | escrow | Solana create_lock ix data builder, condition-hash derivation | | purpose | Domain separator constants | | utils | UUID v4, sender_nonce, RFC 3339 timestamp helpers | | types | Wire-level TypeScript types (envelope, body shapes, attestations) |

What's NOT in here

The SDK is deliberately client-side / shared primitives only. Server concerns live in the backend implementation, not the SDK:

• Replay defence (Redis dedup of message_id, sender_sequence enforcement)
• Time-window check (±5 min, expires_at future)
• JSON schema validation
• Server-side chain assignment (relationship_event_index, prev_server_event_hash, server_event_hash write)
• Inbox / pricing policy evaluation
• Rate limits

Conformance

Any other-language SDK (Python, Go, Rust…) must reproduce identical canonical bytes for the golden vectors in this package's test/canonical-vectors.json to claim ARP conformance. Same envelope → same signed_message_hash → same Ed25519 signature.

Versioning

Semver:

• Major — protocol version bump (arp/0.1 → arp/0.2), envelope structure change, signature-input shape change, public function return-type change.
• Minor — new exported helpers, new optional fields, new Purpose constants.
• Patch — bug fixes that don't change observable behaviour.

See also

• @heyanon-arp/cli — command-line client built on top of this SDK.

License

MIT