Handoff at a glance

Version
r8.1a
Licence
CC-BY-4.0
Formats
HTML · Handoff v0 specification

A one-page summary of the Handoff v0 specification, revision r8.1a. The full text is the reference.

A Handoff record is the record of one piece of work between two parties: a provider and a counterparty.

Each event names its record, its position and the hash of the event before it, so the events form a hash chain.

Each event is signed by the log server's key, and by the writing party's own Ed25519 key where the specification requires it.

Events are appended to one Merkle log (RFC 9162). The log operator signs at most one tree head per UTC date; each head also commits every record's latest event in a tip tree, and anyone can mirror the heads.

An export carries one record plus the heads and proofs needed to check it offline. A verifier answers ACCEPT, REJECT, DETECT or ERROR.

ACCEPT means the export checks out, not that the delivery was accepted or paid, or that any party was vetted. A signature shows which key signed, not which person.

Handoff moves no money, is not a marketplace or escrow, does not verify identity, and has no AI model in the record path.

#Events

Rows of the transition table in section 5.3, one per event type.

State beforeEvent (actor)Result
noneCOMMIT (P or C)PROPOSED, pending COMMIT
PROPOSEDCONFIRM (other role)AGREED
AGREED, REJECTEDDELIVER (P), current terms, no pending AMENDDELIVERED
DELIVEREDACCEPT / REJECT (C), ref = latest DELIVERACCEPTED / REJECTED
AGREED, DELIVERED, REJECTEDAMEND (P or C), new termssame, pending AMEND
ACCEPTEDREVERSE (P or C), ref = the ACCEPTACCEPTED, pending REVERSE
DELIVERED, REJECTED, ACCEPTED, REVERSED; WITHDRAWN only if ≥ 1 DELIVERDISPUTE (P or C)same, disputed + 1
PROPOSED, AGREED, DELIVERED, REJECTED (never after an ACCEPT)WITHDRAW (P or C)WITHDRAWN
anyERASE (W)same, erased ∪ {role}

#Results

From section 11.1.

ResultExitMeaning
ACCEPT0VERIFIED: the export is internally valid; no authenticated conflict, freshness, completeness or anchoring failure was found against the supplied signed heads; consistency is claimed only with linked heads (§9.3)
REJECT1the export is internally invalid or incomplete (including a missing or failing proof)
DETECT2internally valid, but an authenticated conflict, a freshness failure, a completeness failure or an anchoring failure (the class of each detect finding says which)
ERROR3usage, I/O, local cap, key-history or witness-input problem (WITNESS_UNPROVEN); no verdict on the export

#Command line

Command line defined in section 13

handoff verify RECORD.json
    [--known-heads FILE]        §9.1
    [--mirror DIR]              §9.2
    [--require-anchored]        DETECT if any anchoring head is not in --mirror; without --mirror: ERROR (exit 3)
    [--update-known-heads FILE] append the export's verified heads (only on ACCEPT; never silent)
    [--keys FILE]               key history (§7); default = keys.json in --mirror
    [--json]                    {"result": "ACCEPT|REJECT|DETECT|ERROR", "findings": [...], "time_bounds": [...]}
Exit code: 0 ACCEPT, 1 REJECT, 2 DETECT, 3 ERROR (usage, I/O, local cap, key history, unproven mirror).

#In the specification

Back to the documents