How AGLedger Works
Three services. Notarize signs and chains what happened — one API call, terminal at create, the default path. The Gate adds an explicit accept-or-reject from a principal when work crosses a delegation boundary. Notify pushes each record event out to the systems and people around the work. All three sit on the same Server, share the same chain, and compose with the same architectural building blocks: delegation chains, federation, Settlement Signals, predicate schemas, and integrations.
Notarize · Gate · Notify · Delegation · Federation · Settlement Signals · Schemas · Integrations
Last updated: 2026-05-27 · API v0.26.1
Service 1 · the default path
Notarize — sign and chain at the moment of writing
An agent calls POST /v1/records with a structured statement of what it did or is doing — the action, the inputs, any trace IDs and join keys you want carried inside the signed envelope. AGLedger validates the payload against the contract type schema, signs it Ed25519, hash-chains it to the previous entry, and writes it to the vault. The record terminates at RECORDED in the same call. One Signed Statement, one chain position, one network round-trip.
The chain is durable memory. When a new agent picks up where the old one left off — after a context reset, a session expiry, a handoff, a tool swap — it reads the chain to recover what was signed for. Not a summary of a conversation that no longer exists. The byte-stable record of what happened.
Every record is verifiable offline against published public keys at /.well-known/agledger-vault-keys.json. The vault rejects UPDATE and DELETE; partition-level TRUNCATE is blocked by trigger. Tampering is mathematically detectable.
POST /v1/records → chain position N, signed, RECORDED
GET /v1/records/{id}/audit-export → Signed Statement, verifiable offline
GET /.well-known/agledger-vault-keys.json → public keys for offline verify
Service 2 — the delegation boundary
Gate — principal renders accept or reject
When work crosses a delegation boundary — between agents, between departments, between companies — the principal needs a place to render accept or reject on the performer's delivery. AGLedger holds the signed contract, the signed completion, the signed verdict, and the structured dispute path. We are the interface, not the judge. The principal renders the judgment; the chain records it.
The principal can be a human in a dashboard, an automated agent rendering accept or reject against its own logic, or the rules engine evaluating numeric criteria with tolerance bands. AGLedger does not distinguish among them — the verdict is signed either way. The rules engine is a convenience layer for deterministic checks; the principal remains the real judge.
1. Principal creates the record
Structured statement of what is being assigned, by when, under what criteria, with which tolerance bands.
POST /v1/records2. Performer accepts and activates
Counter-proposals are supported on the same flow if terms need to change before work begins.
POST /v1/records/{id}/accept3. Performer submits a completion
Structured evidence matching the contract type's completion schema, signed by the performer.
POST /v1/records/{id}/completions4. Principal renders the verdict
The record terminates at FULFILLED on accept or FAILED on reject. A Settlement Signal fires.
POST /v1/records/{id}/verdictDisputes are first-class. A three-tier path covers automated re-adjudication on rules-mode verdicts, a structured evidence window for both parties, and a final arbitration tier that terminates at PENDING_ARBITRATION rather than fabricating a verdict. The notary remembers; the contractually agreed arbiter judges.
Service 3 · keeping everyone in the loop
Notify — signed event delivery the receiver can verify
Register an endpoint with POST /v1/webhooks and AGLedger pushes every business-meaningful record event to the systems and people you already run — an approval queue, a dashboard, an ERP, a payment platform. Human-in-the-loop by delivery, not by polling. The subscription is durable: at-least-once delivery with a stable idempotency key, retry with backoff, a circuit breaker, and a seven-day dead-letter queue.
Every delivery is signed so the receiver can verify origin, not just integrity. HMAC by default; Ed25519 (RFC 9421) for the non-repudiable path that Settlement Signals ride — verifiable against the same published keys that sign the chain, with no shared secret.
POST /v1/webhooks → register a subscription with an event filter
POST /v1/webhooks/{id}/ping → send a test event before you wire it up
GET /v1/webhooks/{id}/deliveries → per-attempt delivery log
Building blocks
Building blocks that compose with all three
Notarize and the Gate are the two paths a record can take; Notify carries the events out. Everything below composes on top: turn on what the work calls for, leave the rest off. Configuration is per-record, per-contract, or per-Server.
Delegation chains
Real work doesn't stay with one agent. When work is handed off, each step creates its own signed record parented to the one above it via parent_record_id. The original principal can trace the full tree from the root record to every leaf, with every signature along the way. Default delegation depth is 5; configurable up to 10. Cross-Server delegation chains complete naturally — each Server holds its own slice and chains link by signature reference.
Federation
Peer-to-peer signed-message transport between sovereign Servers. Each organization runs its own Server, signs its own records, and verifies inbound bytes against the peer's published public key. No central coordinator, no peering handshake, no bearer tokens. The chain crosses the boundary; the data doesn't — criteria values, completion evidence, and audit entries stay local to the originating Server. Sharing is per-record (with share), per-contract, or globally configurable.
Settlement Signals
When a Gate verdict terminates, AGLedger emits a Settlement Signal — SETTLE on FULFILLED, HOLD on FAILED, RELEASE on dispute Tier 1 auto-overturn — to the payment, ERP, or ticketing system that actually moves value. AGLedger does not move money; it produces the signed verdict that authorizes the systems that do. USPTO 19/565,072.
Predicate schemas
You define the record schema, the completion schema, and the deterministic field mappings. AGLedger ships with no built-in contract types. Contract types are content-addressed by RFC 8785 manifest digest, and seven first-class in-toto predicate kinds are served as JSON Schema at GET /predicates/{kind}/v1.
Integrations
AGLedger fits underneath the platforms you already run. OpenTelemetry, Langfuse, Arize, Datadog and other trace IDs ride inside the signed envelope under metadata.traces. OCSF audit exports drop into your SIEM. Native REST is the primary path; TypeScript SDK, Python SDK, CLI, and MCP server cover the rest. Signed event delivery is its own service — see Notify, above.
On the chain
What gets written to the chain
Every state transition produces a Signed Statement — a tagged COSE_Sign1 envelope (RFC 9052, tag 18) over an in-toto v1 Statement payload, deterministically CBOR-encoded per RFC 8949 §4.2.1, Ed25519-signed, and hash-chained. The database enforces immutability: UPDATE and DELETE are revoked on the vault tables, and partition-level TRUNCATE is blocked by trigger. Privileged-DBA tampering of the visible payload jsonb is caught at verify time as chainIntegrityReason: 'payload_drift'.
Public verification keys at /.well-known/agledger-vault-keys.json — verify the chain offline, no account needed.
Composition
Common combinations
The services and building blocks compose freely. These are the combinations that actually appear in customer deployments.
| Shape | When it fits |
|---|---|
| Notarize | Single-agent work, most of the time. One signed record, terminal at create. |
| Notarize + Delegation | Multi-agent or multi-service workflows inside one organization. Each handoff signs its step. |
| Gate | A delegated decision where the principal must explicitly accept or reject before the work is treated as done — refund eligibility, payout authorization, goods acceptance. |
| Gate + Settlement Signals | Commercial single-org work where the verdict authorizes a downstream payment, ERP, or ticketing system. |
| Notarize + Federation | Cross-department or cross-company notarization where both sides need the same byte-stable record without a verdict. |
| Gate + Delegation + Federation + Settlement Signals | Agent-to-agent commercial work across organizations. Each side renders its own verdict on its own Server; signals close the loop into downstream systems. |
Where it runs
Self-hosted, one role, your keys
AGLedger runs on your infrastructure. PostgreSQL 17+ (18 recommended for native UUIDv7), Node 24 LTS, Kubernetes 1.27+ for the Enterprise shape. Every install is the same binary — one role: Server. A Server with federation off and gating off is the same install as one with both on; only configuration changes.
No phone-home, no telemetry call, no kill switch. If the license lapses, the software keeps running. Security patches are free regardless of support status. Air-gap capable. Docker Compose for the Developer Edition; Helm chart on EKS/ALB/ACM (or your equivalent) for Enterprise.
Related capabilities
The Gate in depth — how principals render verdicts and what makes the verdict itself a signed object.
How accountability crosses an organizational boundary while the underlying business data stays on each side.
The terminal-state signal — SETTLE, HOLD, RELEASE — that authorizes downstream payment or contract systems.
Webhook delivery, trace correlation, SIEM export, and the SDKs and MCP server that wire AGLedger into existing stacks.
Customer-defined contract types and predicate kinds — the structural input verifiers evaluate against.
Single Server role, Compose or Helm, customer-owned database — the operational shape of every install.
The cryptographic architecture that underwrites every record, verdict, and federation message.
The 194-route HTTP surface every SDK, MCP tool, and federation peer talks to.
The flagship explainer — how a transparency service, an Article 12 logging surface, and federation compose into the substrate AI agents need for accountable cross-org work.
Next steps