Quickstart

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

// 1. Enable once at startup. The API key resolves your project.
ProofLedger.enable({
  apiKey: process.env.PROOFLEDGER_API_KEY,
  baseUrl: "https://www.proofledger.dev",
  agentName: "support-agent",
  owner: "customer-success",
  framework: "custom",        // langchain | crewai | openai-agents | claude-code | custom
  model: "gpt-4.1",
  version: "1.0.0",
  policyMode: "monitor",      // switch to "enforce" when you're ready to gate actions
});

// 2. Register the agent's identity. Generates an Ed25519 keypair —
//    the private key stays in this process and signs every event.
await ProofLedger.registerAgent();

// 3. Start a workflow and log what the agent does.
const workflowId = "wf_refund_" + Date.now();

await ProofLedger.logWorkflowStep({
  workflowId,
  workflowName: "Customer refund request",
  eventType: "task_received",
  action: "Received refund request for order ORD-123",
});

await ProofLedger.logToolCall({
  workflowId,
  toolName: "refund_lookup",
  inputSummary: "orderId=ORD-123",
  outputSummary: "eligible=true, amount=$49",
});

// 4. Check policy BEFORE a risky action (no event logged, no trust change).
const policy = await ProofLedger.evaluatePolicy({
  toolName: "issue_refund",
  sensitiveAction: true,
});

if (policy.decision === "allow") {
  await ProofLedger.logDecision({
    workflowId,
    action: "Refund approved under policy",
    outputSummary: "$49 refunded to customer",
  });
}

// 5. Record which model actually executed (provenance — the agent keeps its
//    identity and trust even when this changes).
await ProofLedger.recordModelExecution({
  provider: "openai", modelName: "gpt-4.1",
  inputTokens: 812, outputTokens: 214,
  estimatedCostUsd: 0.012, latencyMs: 2100,
});

// 6. Record the verified outcome. verificationMethod is REQUIRED —
//    agents never silently self-declare success.
await ProofLedger.recordOutcome({
  taskType: "refund-request",
  status: "success",
  verificationMethod: "deterministic",   // refund confirmed via payments API
  businessValueEstimate: 49,
});

// 7. Finish the workflow and flush before exit.
await ProofLedger.logWorkflowStep({
  workflowId,
  action: "Refund issued",
  status: "completed",
});
await ProofLedger.flush();

// 8. Live trust score, any time.
const trust = await ProofLedger.getTrustScore();
console.log(trust); // { trustScore: 100, trustLevel: "trusted", status: "active" }