Composition with the family
OC Pledge is designed to compose with every other primitive. The patterns below show how.
Gate on pledge history — ocGate plus pledge-coreLink to this section
@orangecheck/gate checks stake: minSats and minDays. It has no pledge
option, and it refuses options it does not read (gate 0.3.1 and later). To admit
only people with a record of kept pledges, put a check of your own after the
gate. Your site reads the subject's pledges and their outcomes from its relays;
pledge-core verifies each one and says what state it is in.
import type {
AbandonmentEnvelope,
OutcomeEnvelope,
PledgeEnvelope,
} from '@orangecheck/pledge-core';
import { verifySignature } from '@orangecheck/bip322';
import { ocGate } from '@orangecheck/gate';
import {
classifyState,
pledgeCanonicalInputFromEnvelope,
verifyAbandonment,
verifyOutcome,
verifyPledge,
} from '@orangecheck/pledge-core';
import express from 'express';
// Yours: the signed-in person's address, and their pledges with any outcome
// and abandonment, read from your relays.
declare function addressOf(req: object): string | undefined;
declare function pledgesOf(address: string): Promise<
{
pledge: PledgeEnvelope;
outcome: OutcomeEnvelope | null;
abandonment: AbandonmentEnvelope | null;
}[]
>;
const verifyBip322 = async (msg: string, sig: string, address: string) =>
verifySignature(address, msg, sig);
/** Kept and broken counts, from envelopes that verify. Anything else counts as neither. */
async function pledgeRecord(address: string) {
const now = new Date().toISOString().replace(/\.\d+Z$/, 'Z'); // whole seconds
let kept = 0;
let broken = 0;
for (const { pledge, outcome, abandonment } of await pledgesOf(address)) {
if (pledge.swearer.address !== address) continue;
if (!(await verifyPledge({ envelope: pledge, verifyBip322 })).ok)
continue;
const canonical = pledgeCanonicalInputFromEnvelope(pledge);
const o =
outcome &&
(
await verifyOutcome({
envelope: outcome,
pledge: canonical,
verifyBip322,
})
).ok
? outcome
: null;
const a =
abandonment &&
(
await verifyAbandonment({
envelope: abandonment,
pledge: canonical,
verifyBip322,
})
).ok
? abandonment
: null;
const state = classifyState({
pledge,
outcome: o,
abandonment: a,
now,
});
if (state === 'kept') kept++;
if (state === 'broken') broken++;
}
return { kept, broken };
}
const app = express();
app.post(
'/post',
ocGate({ minSats: 100_000, minDays: 30, address: { from: addressOf } }),
async (req, res, next) => {
const address = addressOf(req);
const record = address ? await pledgeRecord(address) : null;
// At least five kept pledges and none broken.
if (!record || record.kept < 5 || record.broken > 0) {
res.status(403).json({ error: 'pledge_history' });
return;
}
next();
}
);
The policy is yours: a relay might want ten kept pledges and nothing broken in the last year, a forum a different bar per tier. Count from envelopes that verify, and treat a read your relays could not complete as a refusal, not as an empty record: an outcome or abandonment is absent only when four of the five relays answered in full and none was cut off (SPEC §11 item 15).
Stamp as resolution — stamp_publishedLink to this section
The canonical way to pledge "I will publish X by time T":
import type { Bip322Signer, CreatePledgeInput } from '@orangecheck/pledge-core';
import { createPledge } from '@orangecheck/pledge-core';
declare const swearer: Bip322Signer; // the swearer's wallet signer
declare const contentHash: string; // 64 hex: sha256 of what will be published
// expires_at, bond, counterparty and dispute, as in the quickstart
declare const terms: Pick<
CreatePledgeInput,
'expires_at' | 'bond' | 'counterparty' | 'dispute'
>;
const pledge = await createPledge({
...terms,
swearer: swearer.address,
proposition: 'I will publish my Q3 results by 2026-08-01.',
resolution: {
mechanism: 'stamp_published',
query: `stamp(content_hash=sha256:${contentHash}, signer=${swearer.address})`,
},
resolves_at: { time: '2026-08-01T00:00:00Z' },
swearerSigner: swearer,
});
At resolution, the verifier looks up the stamp via the Stamp NIP's kind-30083
directory. If a valid stamp with the declared content_hash exists and was
signed by the swearer, the pledge resolves kept. No resolver signature
required — fully deterministic.
Vote as dispute resolution — vote_resolvesLink to this section
Pledge's dispute.mechanism can invoke an OC Vote with a pre-specified voter
set and threshold:
dispute: {
mechanism: 'vote_resolves',
params: 'poll_id=84ad…;option=kept;threshold=0.66',
},
The OC Vote poll uses standard weight modes and a
deterministic tally; the dispute resolves kept if the
poll crosses the threshold for the kept option, broken otherwise.
Agent-delegated pledgesLink to this section
A principal can delegate pledge:create scope to an agent under
OC Agent. The agent signs the pledge, and the principal stays the
swearer in the canonical message. The envelope names the delegation in
via_delegation and the agent in agent_address; a verifier resolves that
delegation and checks its scope (SPEC §7.3).
import type { SignerRef } from '@orangecheck/agent-signer';
import type { CreatePledgeTerms } from '@orangecheck/pledge-core';
import { createDelegation } from '@orangecheck/agent-signer';
import { createPledge } from '@orangecheck/pledge-core';
declare const principal: SignerRef; // the principal's wallet
declare const agent: SignerRef; // the agent's own key
// proposition, resolution, bond and the rest, as in the quickstart
declare const terms: Omit<CreatePledgeTerms, 'swearer'>;
// Principal mints a delegation:
const delegation = await createDelegation({
principal,
agentAddress: agent.address,
scopes: ['pledge:create(max_bond_sats<=10000000)'],
ttlMs: 365 * 24 * 3600 * 1000,
});
// Agent later swears a pledge under that delegation and signs it with its own
// key. The swearer stays the principal, named by address; the principal signs
// nothing here (pledge-core 3.3.0 and later).
const pledge = await createPledge({
...terms,
swearer: principal.address,
viaDelegation: { delegation_id: delegation.id, agent_signer: agent },
});
The pledge counts against the principal's history, not the agent's.
Scope-grammar extensions for pledge:create are coordinated with the
OC Agent spec.
A verifier checks the delegation as of the time it verifies: unexpired then, and
not revoked. The agent writes the pledge's sworn_at, so that time does not
decide whether the delegation was in force, and once the delegation expires or
is revoked the pledge stops counting. A history can still show it as of its
sworn_at with verifyPledgeAsOfSwornAt, which says that time is unanchored.
Lock for private counterparty negotiationLink to this section
A bilateral pledge often has confidential negotiation before the public swearing. Counterparties can use OC Lock to seal envelopes addressed to each other's Bitcoin addresses, hash out terms privately, then publish the agreed pledge envelope to Nostr. Pure usage pattern — no protocol-level coupling.
What does NOT composeLink to this section
- No automatic payouts. OC Pledge can be used in a prediction-market shape
(two parties swear opposite propositions,
counterparty_signsresolution), but the protocol does not route value. Settlement is out-of-band — Lightning, on-chain, or off-rail. - No pledge chains in v1.0. "This pledge's resolution triggers that pledge's resolution" is interesting and deferred to post-v1 once we observe what real-world demand exists.
- No cross-protocol aggregated reputation. Same discipline orangecheck
applies to
score_v0— the protocol ships raw metrics; aggregation is the platform's call.