VERDOCK

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.

On this page

Each receipt is one line of newline delimited JSON, following draft-sahu-agent-action-receipts-00.

Members#

MemberTypeSigned
step_idstring, requiredyes
action_idstring, requiredyes
paramsany JSON value, requiredyes
successboolean, requiredyes
ts_msinteger milliseconds since the Unix epoch, requiredyes
actorobject with string members agent and user, optionalyes
prev_hash64 lowercase hex. Absent on the first line, required after.yes
public_key64 lowercase hex (Ed25519, 32 bytes), requiredno
signature128 lowercase hex (Ed25519, 64 bytes), requiredno

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#

KeyHolds
approval_evidenceThe exact request, policy hash, required approver count, trusted key ids, decisions and decision times. See maker and checker.
delegationThe 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.