About Proofs

A proof is a cryptographic signature appended to a ledger record. Proofs are the mechanism for changing a record's status, managing its labels, recording authorization decisions, and storing application-specific data. Every record maintains a list of proofs in meta.proofs.

Adding a proof

To add a proof, send a POST request to the record's /proofs endpoint:

POST /v2/{resource}/{id}/proofs

The proof must be signed against the record's current hash. This ensures the signer has seen the latest version of the record before approving a change. The signature is verified by the server — if it doesn't match the current hash, the proof is rejected.

What proofs can change

Each proof can include custom fields that request changes to the record:

• custom.status — request a status transition (e.g., pending → active)
• custom.labels — add or remove labels (supports $push, $pull, $pullAll)
• custom.moment — timestamp of when the proof was signed

The record's data fields are not modified by proofs — only metadata like status and labels.

Custom fields and audit trail

Beyond status and label changes, proofs can carry arbitrary custom fields in the custom object. This makes proofs a signed, append-only audit trail for recording application-specific events, decisions, or external references.

For example, a proof might record a compliance review decision, an external transaction ID, or a processing note — all cryptographically signed by the acting signer. Since proofs are never modified or removed, they provide a tamper-evident history of all actions taken on a record.

Quorum and incremental signing

Policies can require multiple signers to approve a status transition. This is called a quorum. When a quorum is defined:

1. The first signer adds a proof requesting a status change
2. The proof is accepted and stored in meta.proofs, but the status does not change yet
3. Additional signers add their proofs for the same status
4. When the required quorum is met, the status transitions

This allows each signer to review and approve independently. There is no error when quorum is not yet met — the proof is simply stored until enough signatures are collected.

When proofs are rejected

A proof is rejected entirely (not stored) when:

• Invalid signature — the proof was not signed against the record's current hash
• No permission — the signer does not have access to add proofs to this record
• Invalid status transition — a status policy does not allow the requested status value
• Invalid labels — a label policy does not allow the requested labels

When a proof is rejected, the record is not modified and an error is returned.

Response

On success, the endpoint returns the updated record with the new proof appended to meta.proofs. If the proof triggered a status or label change, the updated values are reflected in meta.status and meta.labels.

Related

• About Statuses — how statuses work and how to manage them
• Status Policies — define valid statuses and quorum requirements
• Labels — how labels work on records
• Keys and Signatures — cryptographic key pairs and signing