Ledger & provenance

Overview

Every AI settlement leaves a verifiable trail. When an intent is created, funded, updated with evidence, settled, refunded, or moved into dispute, Paybond records that step as tenant-scoped, signed evidence in an append-only provenance ledger.

The point is not "we keep logs." Application logs answer what your code wrote; they are mutable, internal, and hard for an outside reviewer to trust. The Ledger answers what actually happened in settlement in a form a reviewer can verify independently:

• Prove — a tamper-evident, append-only history of intent activity.
• Verify — cryptographically verifiable evidence packages an auditor can validate offline, without a live database session.
• Share — bounded, tenant-scoped export bundles you can hand to auditors, partners, or a dispute desk without exposing production systems.

The ledger also serves the platform internally: it is the replayable event stream downstream systems such as Signal consume, and the verifiable anchor behind audit exports, dispute packages, and compliance review.

Ledger does not move funds. Harbor and the configured payment rails move money; Ledger preserves the signed evidence trail those systems produce.

How Ledger works

Settlement events flow through authorization and payment rails into signed Ledger history, then into an evidence package a reviewer can verify offline.

flowchart LR
  Agent[AI agent] --> Intent
  Intent --> Auth[Authorization]
  Auth --> Settlement
  Settlement --> Ledger[(Signed ledger)]
  Ledger --> Package[Evidence package]
  Package --> Auditor

The provenance flow has five stages:

1. Capture — every payment event (authorization, payment, refund, dispute, reviewer action) becomes signed evidence.
2. Bind — each entry is tied to the authenticated organization; a write is rejected when the tenant in the signed envelope does not match the caller context.
3. Package — Gateway assembles manifests, receipts, verifier packs, and file hashes into a bounded export for one tenant and one window.
4. Verify — a reviewer validates the package independently by recomputing hashes and checking signatures and ledger continuity.
5. Share — only the required evidence leaves your environment; there is no public raw event firehose.

Within your stack the pieces line up as Agent → Harbor → Stripe (or other rail) → Ledger → Evidence export: agents authorize spend through Harbor, settle on the configured rail, and produce exportable evidence from the same signed history.

Why signed evidence, not database logs

Ledger records signed settlement events, packages them into standard export bundles, and lets auditors validate manifests, hashes, and checkpoints without trusting your dashboard or being granted database access.

Evidence packages

A Ledger-backed export is a bounded package for one tenant and one export window. Depending on the requested include set and disclosure tier, a bundle can contain:

1. manifest.json — signed by the Gateway audit-export key, listing file hashes and the Signal ledger checkpoint captured for the export.
2. proof/ledger_verifier_pack.json — the Harbor tenant ledger verifier pack (ledger tip, completed checkpoint history, witness freshness, and signing-key lineage).
3. proof/verifier_pack.json — the export verifier pack that binds the manifest, Signal checkpoint, ledger checkpoint witnesses, and key-transparency summaries.
4. Optional Signal provenance rows, score snapshots, signed portfolio artifacts, and reputation receipts.
5. Optional dispute case rows, provider settlement rows, guardrail policy/audit JSONL artifacts, and per-intent Harbor snapshots such as harbor/intents/{intent_id}.json.
6. VERIFICATION.txt — plain-language instructions for checking the package offline.

The bundle is what a customer hands to an auditor, partner reviewer, or dispute desk: intents and authorization decisions, payments/refunds/settlement outcomes, disputes and reviewer actions, signed receipts and file hashes, and manifests with verification instructions.

Redaction and disclosure tiers

Exports are tenant-scoped and window-bounded, and sensitive fields are reduced by a named redaction profile so reviewers can see which rules applied:

• standard (default, paybond_export_redaction_v1_standard) — reduces sensitive surface area such as Stripe webhook bodies, payout payloads, dispute subjects, and evidence-URI query strings.
• extended (paybond_export_redaction_v1_extended) — tenant_admin or audited support session only; includes internal dispute timeline rows, richer Stripe metadata, and full evidence URIs.

evidence_timeline and protocol (and agent_receipts) includes are opt-in and gated by role; they are not part of the default include set. Create and download bundles from Investigations → Compliance exports in the console (plan-gated).

Verification

Reviewers can validate a bundle offline with no live database session:

1. Unzip the bundle and open manifest.json; confirm kind is paybond.audit_export_manifest_v1 and tenant_realm_id matches the expected tenant.
2. Recompute SHA-256 for every file listed under artifacts and compare to the manifest.
3. Open proof/verifier_pack.json and confirm the tenant_realm_id, job_id, and Signal checkpoint match the manifest, that witness freshness is within the declared window, and that the export and Signal covering checkpoints line up with proof/ledger_verifier_pack.json.
4. Confirm canonical integrity: signed_payload_sha256_hex equals SHA-256 of the manifest core JSON (without the three trailing security fields); verify the Ed25519 signature with the published public key in the manifest.
5. Re-run append-only continuity over proof/ledger_verifier_pack.json for a database-free continuity proof. The repo ships paybond-ledger-verifier-pack --path proof/ledger_verifier_pack.json --json for this.
6. Verify any signed Signal, guardrail, protocol, or agent-receipt artifacts that are present.

The same steps are repeated inside each bundle in VERIFICATION.txt.

Gateway can also re-verify a stored bundle for you: POST /v1/compliance/audit-exports/{job_id}/verify re-reads the persisted ZIP, checks the manifest signature and every artifact digest, and returns status = verified only when the ZIP, manifest, artifact set, witnesses, freshness windows, key-transparency metadata, and signed Signal artifacts all match. It fails closed with a concrete failure_code otherwise, and remains tenant-scoped so callers never learn another tenant's bundle presence.

Export API

Customer-facing review does not use a public raw event stream. It uses Gateway audit exports and Gateway compliance ledger verification routes:

Tenant scope is derived from the authenticated credential; unauthenticated organization identifiers in the request body are treated only as hints. See the Gateway API — compliance exports and ledger verification for auth rules and the OpenAPI-backed reference.

Retention

Export bundles are retained per job. The retention_hours parameter on create defaults to 168 hours (7 days) and is capped at 720 hours (30 days); after that window the stored ZIP is removed. Callers can revoke a bundle early with DELETE /v1/compliance/audit-exports/{job_id}.

Retention applies to the generated export artifact, not to the ledger itself: the append-only provenance history is durable and is re-packaged on demand for a new export window. Every download is recorded in paybond_audit_export_access_log.

Event format

Each persisted ledger row contains:

Ledger signing bodies (format_version = 2) and evidence bindings (EvidenceSignV1.version = 2) use bincode 2 standard encoding. Rows signed under the previous format_version = 1 encoding remain verifiable only when the verifier supports the legacy wire format.

Harbor exposes protected, tenant-authenticated /ledger/v1/* routes for Signal ingestion, Gateway proof workflows, and operator automation. Those routes can read the current tenant tip (GET /ledger/v1/tip), fetch paginated history (GET /ledger/v1/events), retrieve the active verifying key (GET /ledger/v1/authority), inspect the latest Merkle checkpoint (GET /ledger/v1/merkle/latest), run continuity checks (GET /ledger/v1/verify), export a tenant verifier pack (GET /ledger/v1/verifier-pack), and verify a submitted verifier pack (POST /ledger/v1/verifier-pack/verify). These are trusted upstream routes; customer-facing review uses the Gateway compliance surface above rather than a public raw event stream.

Tenant scoping and access

Cross-tenant access is treated as a severity-zero defect. Every append is tenant-bound: Paybond rejects a ledger write unless the tenant in the signed envelope matches the authenticated caller context, and the tenant id remains part of the signed event so every downstream read filters by tenant. Reads, writes, exports, and verifier packs are limited to the authenticated organization, tenant mismatches are rejected before the request reaches the underlying record, and export access is logged.

Replay and downstream processing

Signal consumes ledger events from a checkpoint using short-lived tenant JWTs on the protected Harbor ledger routes, then applies them idempotently to tenant-scoped storage. This makes routine restarts safe and prevents double-counting during normal recovery.

If an operator needs a full rebuild of a tenant's Signal state, Paybond uses an explicit recovery path rather than allowing replay by mistake. See Operational surfaces for the controlled rebuild flow.

Examples

Export and verify walkthrough (TypeScript)

Tenant scope comes from the service-account API key — never pass a tenant id.

import { Paybond } from "@paybond/kit";

const paybond = await Paybond.open({ apiKey: process.env.PAYBOND_API_KEY! });

// 1. Create a tenant-scoped export job (POST /v1/compliance/audit-exports).
const { job } = await paybond.audit.exports.create({
  filter: {
    time_start: "2026-05-01T00:00:00Z",
    time_end: "2026-05-07T23:59:59Z",
  },
  disclosureTier: "standard",
});

// 2. Fetch status and mint a short-lived download token when the bundle is ready.
const { job: ready } = await paybond.audit.exports.get(job.id, {
  issueDownload: true,
});
console.log(ready.status, ready.download_token);

// 3. Verify a downloaded bundle offline — no database session required.
const result = await paybond.audit.exports.verify("./audit-export.zip");
console.log(result.verified, result.tenant_realm_id, result.job_id);
import { Paybond } from "@paybond/kit";

const paybond = await Paybond.open({ apiKey: process.env.PAYBOND_API_KEY! });

// 1. Create a tenant-scoped export job (POST /v1/compliance/audit-exports).
const { job } = await paybond.audit.exports.create({
  filter: {
    time_start: "2026-05-01T00:00:00Z",
    time_end: "2026-05-07T23:59:59Z",
  },
  disclosureTier: "standard",
});

// 2. Fetch status and mint a short-lived download token when the bundle is ready.
const { job: ready } = await paybond.audit.exports.get(job.id, {
  issueDownload: true,
});
console.log(ready.status, ready.download_token);

// 3. Verify a downloaded bundle offline — no database session required.
const result = await paybond.audit.exports.verify("./audit-export.zip");
console.log(result.verified, result.tenant_realm_id, result.job_id);

Export and verify walkthrough (Python)

import os
from paybond_kit import Paybond

paybond = await Paybond.open(api_key=os.environ["PAYBOND_API_KEY"])

# 1. Create a tenant-scoped export job.
created = await paybond.audit.exports.create(
    filter={
        "time_start": "2026-05-01T00:00:00Z",
        "time_end": "2026-05-07T23:59:59Z",
    },
    disclosure_tier="standard",
)

# 2. Fetch status and mint a short-lived download token when ready.
ready = await paybond.audit.exports.get(created.job.id, issue_download=True)
print(ready.job.status, ready.job.download_token)

# 3. Verify a downloaded bundle offline.
result = await paybond.audit.exports.verify("./audit-export.zip")
print(result["verified"], result["tenant_realm_id"], result["job_id"])
import os
from paybond_kit import Paybond

paybond = await Paybond.open(api_key=os.environ["PAYBOND_API_KEY"])

# 1. Create a tenant-scoped export job.
created = await paybond.audit.exports.create(
    filter={
        "time_start": "2026-05-01T00:00:00Z",
        "time_end": "2026-05-07T23:59:59Z",
    },
    disclosure_tier="standard",
)

# 2. Fetch status and mint a short-lived download token when ready.
ready = await paybond.audit.exports.get(created.job.id, issue_download=True)
print(ready.job.status, ready.job.download_token)

# 3. Verify a downloaded bundle offline.
result = await paybond.audit.exports.verify("./audit-export.zip")
print(result["verified"], result["tenant_realm_id"], result["job_id"])

Verify a bundle from the CLI

Job creation is SDK-only, but listing, fetching, deleting, and offline verification are available from the CLI:

paybond audit exports list
paybond audit exports get <job_id>
paybond audit exports verify ./audit-export.zip
paybond audit exports list
paybond audit exports get <job_id>
paybond audit exports verify ./audit-export.zip

SDKs

Kit wraps the Gateway compliance surface as paybond.audit.exports (PaybondAuditExports) in both the TypeScript (@paybond/kit) and Python (paybond-kit) SDKs.

The Python surface mirrors these with snake_case keyword arguments (disclosure_tier, retention_hours, issue_download) and exposes create, list, get, delete, and verify. list and get are also available as readonly MCP tools (paybond_list_audit_exports, paybond_get_audit_export); local bundle verification is SDK/CLI only. See the TypeScript SDK reference and Python SDK reference.

Signing keys and rotation

• Harbor signs ledger events with a dedicated ledger key.
• Signal receipts and portfolio artifacts use separate signing keys.
• Audit export manifests use their own dedicated signing key.

Rotation is additive: new keys come online for fresh signatures while older keys remain available to verify historical records until their retirement window closes.

Backup and DR

• Back up the ledger store and Harbor intent store together so provenance and settlement references stay consistent.
• Validate the ledger tip before resuming normal traffic after a restore or recovery event.

FAQ

What is Paybond Ledger?

Ledger is Paybond's append-only signed history for settlement activity—intents, authorizations, payments, refunds, disputes, and reviewer actions. It does not move funds; Harbor and payment rails do. Ledger preserves the evidence trail those systems produce.

Why not use database logs?

Database logs are mutable, internal, and hard for outside reviewers to verify. Ledger records signed settlement events, packages them into standard export bundles, and lets auditors validate manifests, hashes, and checkpoints without trusting your dashboard or granting database access.

Can auditors verify evidence offline?

Yes. Audit export ZIPs include a signed manifest, artifact digests, proof material, and plain-language verification instructions. Reviewers can recompute hashes, check signatures, and validate ledger continuity with Kit or the paybond-ledger-verifier-pack tool—no live database session required.

What information is included in an export?

Exports are tenant-scoped and window-bounded. Depending on plan and disclosure tier, bundles can include intent and settlement records, dispute material, Signal receipts, guardrail history, manifest signatures, file hashes, and verifier results. Sensitive fields are reduced through standard or extended redaction profiles.

Can I redact sensitive data?

Yes. The default standard tier reduces sensitive surface area (Stripe webhook bodies, payout payloads, dispute subjects, evidence-URI query strings). The extended tier is limited to tenant_admin or an audited support session. The applied profile is named in the manifest so reviewers can see which rules were used.

Does Ledger store payment funds?

No. Ledger stores signed evidence about settlement, not money. Harbor and the configured payment rails (for example Stripe) move funds; Ledger records the authorization, payment, refund, and dispute events they produce.

How long is evidence retained?

Export bundles are retained per job (retention_hours defaults to 7 days, maximum 30 days) and can be revoked early. The append-only ledger history itself is durable and is re-packaged on demand for new export windows.

Can I integrate with existing payment systems?

Yes. Agents authorize spend through Harbor and settle on a configured rail; the same signed history feeds exportable evidence. Ledger records the outcome regardless of which supported rail moved the money.

Is the Ledger a blockchain?

No. The Ledger is an append-only signed event log optimized for provenance and verification within Paybond's settlement model. The goal is tamper-evident history and attributable events, not public consensus.

How does the Ledger relate to Harbor and Signal?

Harbor records the agreement, evidence, and release/refund outcome. Ledger preserves the signed history behind those records. Signal uses that history to build receipts and standing views.

How do you handle corrections?

Corrections are expressed as new events that clarify or supersede prior facts. The history remains append-only so reviewers can see what changed and why.

Is it multi-tenant?

Yes. Reads, writes, exports, and verifier packs are limited to the authenticated organization. Tenant mismatches are rejected before the request reaches the underlying record, and export access is logged.

Is there a public raw ledger event stream?

No. Raw event pages are protected Harbor routes for trusted ingestion and automation. Public review happens through Gateway audit exports, tenant verifier packs, and verification routes, not a paginated event stream.

Is Ledger a legal audit opinion?

No. Ledger provides signed records and verification material. Customers, auditors, payment providers, and legal teams still decide how those records satisfy their own review or compliance obligations.

Related

• Intent lifecycle
• Signal scoring
• Operational surfaces
• Agent receipt standard
• Gateway API — compliance exports