Glossary
Quick reference for every term used across the docs.
Attestation
A signed statement linking a Bitcoin address to zero or more handles. The full JSON envelope includes the canonical message, signature, signing scheme, and metadata. See AttestationEnvelope in the SDK.
Attestation ID
SHA-256(canonical_message) encoded as 64 lowercase hex characters. Content-addressed, deterministic, URL-safe. Two different messages produce different IDs.
BIP-322
Bitcoin Improvement Proposal 322 — a generic message signing scheme that works with every Bitcoin address type (P2WPKH, P2TR, P2PKH, P2SH, etc). Preferred over the legacy signmessage scheme because it supports SegWit and Taproot.
Bond
A declared commitment of sats, expressed via the bond: extension inside a signed canonical message. Verifiers fail with bond_insufficient when the confirmed balance drops below the declared bond, and use the declared value (not the confirmed balance) as sats_bonded for scoring.
Canonical message
The exact UTF-8 text a Bitcoin wallet signs. Seven core lines, LF endings, one trailing LF, optional lexicographically-sorted extensions. Strict by design — see The canonical message.
Challenge (signed-challenge auth)
A short-lived message with header orangecheck-auth and an explicit expires_at. The user signs it with BIP-322 to prove address control in real time. Distinct from an attestation so a signed challenge can never be confused with one.
days_unspent
Integer number of days since the earliest confirmation time among the bonded UTXOs (or, if bond: is present, computed via oldest-first greedy selection). Recomputed from live chain state at verification time.
Discovery relay
A Nostr relay that the verifier queries to find an attestation by address, ID, or bound identity. The default set ships with the SDK; you can override.
Gate
A server-side policy that either passes or rejects a request based on an OrangeCheck proof. The @orangecheck/gate package ships drop-in gates for common Node frameworks.
Handle
A user-facing identifier on some external system — nostr:npub1…, github:alice, dns:example.com, twitter:@alice, etc. Bound inside the signed message as a self-asserted claim.
Identity binding
A protocol:identifier pair bound inside the identities: field of a canonical message. Self-asserted — must be verified out-of-band if ownership matters.
Kind 30078
The Nostr event kind OrangeCheck uses for publishing. Parameterised replaceable per NIP-78 (application-specific data). The d tag contains the attestation ID; replacement semantics keep the newest per (pubkey, kind, d) triple.
Legacy signmessage
The pre-SegWit Bitcoin message signing scheme. Only works for P2PKH (1…) addresses. Accepted by verifiers but BIP-322 is preferred.
Nonce (canonical message)
16 random bytes encoded as 32 lowercase hex characters. Prevents replay — a signature for one nonce cannot be re-used for another.
Nonce (signed-challenge auth)
Same 16-byte hex, but issued by the challenge-issuing server and stashed against the session. The verify step requires expectedNonce to match — this is what defeats replay of stolen challenges.
Reference score (score_v0)
score_v0 = round(ln(1 + sats_bonded) * (1 + days_unspent / 30), 2)
One and only one registered algorithm. Advisory — RPs should gate on raw metrics (min_sats, min_days), not scores.
Relying Party (RP)
The app that consumes a proof and makes a decision. "RP" is a conventional term from federated-identity standards; in OrangeCheck an RP is whatever is gating access.
Score
A number produced by a scoring algorithm from raw metrics. Advisory only. The protocol registers score_v0; additional algorithms are RP-specific and should not be registered.
sats_bonded
Sum of confirmed, unspent UTXO values at the address — or, if bond: is present, exactly the declared value (surplus ignored). Integer, satoshis. Recomputed from chain state at verify time.
Scheme
The signature scheme used: "bip322" or "legacy". Encoded in the attestation envelope and in the Nostr event's scheme tag.
Subject
In the context of /api/check / /api/discover, the thing you're querying about — an address, attestation ID, or bound identity. Every endpoint accepts exactly one subject per request.
Tier
A UI convenience for rendering proofs. Four tiers: bronze (10k × 30d), silver (100k × 90d), gold (1M × 180d), platinum (10M × 365d). Thresholds are a suggestion, not protocol — a platform's "Gold" doesn't necessarily mean another platform's.
UTXO
Unspent Transaction Output. The atomic unit of Bitcoin balance. An address's confirmed UTXOs are what sats_bonded sums over.
Verifier
Any app or server that checks a signature and recomputes metrics. The hosted verifier at ochk.io/api/* is one; the SDK's verify() is another; your own server is a third.