Receipt format
One signed, hash chained line of JSON per step. The members, the signed bytes and the chain rule, as implemented in verdock 0.3.0.
Each receipt is one line of newline delimited JSON, following draft-sahu-agent-action-receipts-00.
Members#
| Member | Type | Signed |
|---|---|---|
step_id | string, required | yes |
action_id | string, required | yes |
params | any JSON value, required | yes |
success | boolean, required | yes |
ts_ms | integer milliseconds since the Unix epoch, required | yes |
actor | object with string members agent and user, optional | yes |
prev_hash | 64 lowercase hex. Absent on the first line, required after. | yes |
public_key | 64 lowercase hex (Ed25519, 32 bytes), required | no |
signature | 128 lowercase hex (Ed25519, 64 bytes), required | no |
Other members can be present. They are not signed, but the next line's prev_hash covers them because that digest is over the exact line bytes.
Signed bytes#
Compact JSON of the signed members in the fixed order step_id, action_id, params, success, ts_ms, actor (agent then user), prev_hash, omitting absent ones. Object keys inside params are sorted by Unicode code point at every depth. Arrays keep their order. Strings use the shortest RFC 8259 form with lowercase \u escapes. Numbers are integers within plus or minus 2^53 minus 1. A non integer number token anywhere in a line is rejected, so the Python, Node and browser verifiers always agree.
Chain#
prev_hash of line n is the SHA256 hex digest of the exact octets of line n minus 1, without its newline.
What goes in params#
| Key | Holds |
|---|---|
approval_evidence | The exact request, policy hash, required approver count, trusted key ids, decisions and decision times. See maker and checker. |
delegation | The full signed manifest chain from the root to the acting agent. See limits and manifests. |
| Committed fields | {"sha256": ...} in place of account ids, account numbers and emails. See selective disclosure. |
Verification#
verdock verify FILE --public-key HEX checks every line: members and types, hex lengths, the signature over the signed bytes, the chain, that the key is the one you trust, then approval evidence and delegation when present. Reasons are in failure reasons.
The annotated example is on the receipt format page.