@proofledger/sdk

The universal trust, audit, observability & replay layer for AI agents.

ProofLedger records what your AI agents do — prompts, model calls, tool calls, outputs, errors — as a tamper-evident SHA-256 hash chain, so you can prove later that the audit trail wasn't altered. Framework-agnostic: works under or beside LangGraph, CrewAI, the OpenAI Agents SDK, AutoGen, or a custom stack.

npm install @proofledger/sdk

Quick start

import { ProofLedger } from "@proofledger/sdk";

ProofLedger.enable({
  apiKey: process.env.PROOFLEDGER_API_KEY,
  baseUrl: "https://your-proofledger.app",
  projectId: "proj_...",
});

// One-shot tracking
await ProofLedger.track({
  agentId: "support-agent",
  userId: "user_123",
  input: "User prompt here",
  output: "Agent response here",
  model: "gpt-4.1",
  provider: "openai",
});

// Wrap a unit of work as a fully-traced run
await ProofLedger.withRun(
  { agentId: "research-agent", model: "claude-4-opus", provider: "anthropic" },
  async (run) => {
    await run.recordToolCall({ toolName: "web_search", input: { q: "ai" }, output: { hits: 3 } });
    return await myAgent.run("Research this topic");
  }
);

// Verify the tamper-evident chain
const result = await ProofLedger.verifyRun(runId); // { valid, issues, eventCount }

Local-first: with no apiKey, the SDK runs in local mode and writes a real audit log to ./.proofledger/events.jsonl — so you can develop with zero setup.

API

enable · track · startRun · endRun · recordEvent · recordToolCall · withRun · verifyRun, plus the primitives createPayloadHash, createEventHash, and verifyEventChain.

Hash chain

Each run is its own chain. For every event:

payloadHash  = sha256(canonicalJSON(payload))
previousHash = the prior event's eventHash   (genesis for the first)
eventHash    = sha256(canonicalJSON({ eventId, eventType, timestamp, payloadHash, previousHash }))

The canonical encoding is byte-for-byte compatible with the proofledger Python SDK, so chains captured from either language verify identically.

License

MIT