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.
The normative spec is one repo, seven documents and a set of conformance vectors:
| Document | What it covers |
|---|---|
SPEC. (opens in a new tab) | Normative rules — canonical message, envelopes, state machine, errors |
PROTOCOL. (opens in a new tab) | Flow diagrams, discovery patterns, relay semantics |
NIP_ (opens in a new tab) | Nostr kind-30078 d-tag namespaces + discovery filters |
REGISTRY. (opens in a new tab) | Resolution mechanisms, extension policy, change process |
WHY. (opens in a new tab) | Design rationale + the rejected-design log |
SECURITY. (opens in a new tab) | Threat model, verifier obligations, mitigations |
LIFECYCLE. (opens in a new tab) | After publishing: what a swearer may do, and what a verifier must do |
/ (opens in a new tab) | Conformance vectors — required-pass for any impl |
/ (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:
| Group | Vectors | Coverage |
|---|---|---|
| Resolution mechanisms | v01–v07 | One happy-path vector per mechanism (chain_ … vote_) |
| Agent delegation | v08, v33 | Pledge signed by an agent under pledge: delegation scope; an agent address equal to the swearer is rejected |
| Edge cases | v09–v10 | resolves_, same-block resolve |
| Outcome envelope shapes | v11–v16 | One per mechanism — deterministic and resolver-signed |
| Abandonment | v17 | Abandonment envelope, classification = broken |
| Bond verification | v18–v20, v29–v30 | Valid, invalid, and spent-mid-pledge; days_ is the age of the coins covering min_ |
| Bilateral consistency | v21–v22, v51–v54 | A swearer's counter-claim agreeing with or contradicting the counterparty's outcome, alone, after a zero-length window, or at expires_ |
| Disputes | v47–v50 | The resolver's own contradiction after and inside its window; a dispute timing out at expires_ with no dispute mechanism, and staying disputed with one |
| State-machine transitions | v23–v27, v31–v32, v39 | All 5 transition classes from §2.4 of the brief; an outcome dated after now, a signed outcome after expires_, an abandonment whose reason holds a line break |
| Malformed-input rejection | v28, v41–v45 | Empty nonce — implementation MUST reject before computing canonical; a line feed in evidence., the string "null" for a null field, non-ASCII digits in a time |
| Field tolerance | v34–v38, v40 | Abandonment reasons and outcome evidence a verifier MUST NOT refuse (long, empty, line breaks); a lone surrogate's canonical bytes |
| Delegation scope check | v46 | 31 pledge: scope cases |
| Address spelling | v55–v58 | A bech32 address with a capital is rejected in swearer., agent_ and counterparty, and in an outcome's resolved_ |
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
- How it works — narrative companion to SPEC §3–§5
- Resolution grammar — narrative companion to SPEC §3.4 and REGISTRY §6
- State machine — narrative companion to SPEC §4
- Security posture — narrative companion to SECURITY.md