Skip to content
On this page

Specification

Normative source

SPEC.md is the authoritative rules. The full normative set — seven documents plus the required-pass conformance vectors — is laid out below.

oc-pledge-protocol/SPEC.md (opens in a new tab)

The normative spec is one repo, seven documents and a set of conformance vectors:

DocumentWhat it covers
SPEC.md (opens in a new tab)Normative rules — canonical message, envelopes, state machine, errors
PROTOCOL.md (opens in a new tab)Flow diagrams, discovery patterns, relay semantics
NIP_ORANGECHECK_PLEDGE.md (opens in a new tab)Nostr kind-30078 d-tag namespaces + discovery filters
REGISTRY.md (opens in a new tab)Resolution mechanisms, extension policy, change process
WHY.md (opens in a new tab)Design rationale + the rejected-design log
SECURITY.md (opens in a new tab)Threat model, verifier obligations, mitigations
LIFECYCLE.md (opens in a new tab)After publishing: what a swearer may do, and what a verifier must do
/test-vectors/ (opens in a new tab)Conformance vectors — required-pass for any impl
/examples/ (opens in a new tab)Three runnable example envelopes

License: MIT, for the spec, the examples and the test vectors.

Conformance vectorsLink to this section

The vectors, by group:

GroupVectorsCoverage
Resolution mechanismsv01–v07One happy-path vector per mechanism (chain_state … vote_resolves)
Agent delegationv08, v33Pledge signed by an agent under pledge:create delegation scope; an agent address equal to the swearer is rejected
Edge casesv09–v10resolves_at == expires_at, same-block resolve
Outcome envelope shapesv11–v16One per mechanism — deterministic and resolver-signed
Abandonmentv17Abandonment envelope, classification = broken
Bond verificationv18–v20, v29–v30Valid, invalid, and spent-mid-pledge; days_unspent is the age of the coins covering min_sats
Bilateral consistencyv21–v22, v51–v54A swearer's counter-claim agreeing with or contradicting the counterparty's outcome, alone, after a zero-length window, or at expires_at
Disputesv47–v50The resolver's own contradiction after and inside its window; a dispute timing out at expires_at with no dispute mechanism, and staying disputed with one
State-machine transitionsv23–v27, v31–v32, v39All 5 transition classes from §2.4 of the brief; an outcome dated after now, a signed outcome after expires_at, an abandonment whose reason holds a line break
Malformed-input rejectionv28, v41–v45Empty nonce — implementation MUST reject before computing canonical; a line feed in evidence.result, the string "null" for a null field, non-ASCII digits in a time
Field tolerancev34–v38, v40Abandonment reasons and outcome evidence a verifier MUST NOT refuse (long, empty, line breaks); a lone surrogate's canonical bytes
Delegation scope checkv4631 pledge:create scope cases
Address spellingv55–v58A bech32 address with a capital is rejected in swearer.address, agent_address and counterparty, and in an outcome's resolved_by

Every vector is a (inputs, expected_outputs) JSON tuple. Implementations ship a harness that runs all vectors and reports pass/fail. CI must run the harness; a new implementation joins the family by passing all vectors byte-identically.

The TypeScript and Python SDKs are required to produce byte-identical canonical messages, ids, and signatures. Same discipline orangecheck and @orangecheck/sdk already follow.

Versioning policyLink to this section

The canonical message header oc-pledge/v1 commits incompatible changes to explicit version bumps. Adding a new resolution mechanism is a MINOR version (existing pledges still verify); changing field order or serialization is MAJOR (existing pledges may need re-canonicalization in clients).

v1.0.0 was released in 2026-05. SPEC.md is marked Draft until implementations conform to the changes listed under Unreleased in the CHANGELOG (opens in a new tab). Future MINOR bumps add fields without breaking existing verifiers; future MAJOR bumps require coordinated upgrade across the family.

See alsoLink to this section