Quickstart
Three things to do — in order, once. After this, sending and receiving are one click.
1. Register your deviceLink to this section
Visit /app (opens in a new tab) in a browser, enter your Bitcoin address, pick your wallet (UniSat, Xverse, Leather, OKX, Phantom — or paste a signature from any signmessage-capable wallet), and sign the binding statement. The browser stores a 32-byte X25519 secret in IndexedDB and publishes a public kind-30078 event to nostr-core's five Nostr relays. The browser is set up once two of them serve the record back; until then the page says "Not set up yet", and Try again sends the same record (when a record counts).
You never do this step again for this address in this browser.
2. Send a messageLink to this section
On /app (opens in a new tab), click New and paste the recipient's
Bitcoin address. The thread opens. Type a message or attach files and press
send. The app looks up the recipient on Nostr (4 of the 5 relays must
answer), verifies the BIP-322 binding on their device record, seals the
envelope, publishes a gift-wrap so the recipient's inbox auto-delivers, and
exposes a share URL / .lock / QR on the resulting bubble so you can also hand
the envelope off out-of-band any time.
Every sent message is a sealed vault by definition — same crypto, same identity binding, same envelope structure. The URL encodes the full envelope in its fragment, so nothing touches a server.
https://lock.ochk.io/unlock#eyJhbGci…
Share the URL through any channel: Signal, email, paper QR code, carrier pigeon.
3. Receive a messageLink to this section
Open the share URL. The app:
- Recomputes the envelope id and verifies the sender's BIP-322 signature.
- Looks up your local device key by
device_id. - Derives
shared = X25519(device_sk, eph_pk)from the recipient entry. - Unwraps the content key under
HKDF(shared, salt=nonce_ct). - Decrypts the payload with AES-256-GCM.
Total on-screen time: < 3 seconds.
4. Hand off an envelopeLink to this section
Every message bubble, sent or received, exposes three affordances: Link, .lock, QR. Same envelope, three ways to deliver it out-of-band if the Nostr auto-delivery isn't convenient (counterpart isn't on Lock yet, in-person hand-off, air-gapped recipient). See chat transport for the full delivery model and security implications for the trust model.
Using the SDKLink to this section
If you want to embed OC Lock in another app — Node, a browser extension, a Nostr
client — the three packages are published from the
oc-packages (opens in a new tab) monorepo.
npm install @orangecheck/lock-core @orangecheck/lock-crypto @orangecheck/lock-deviceSeal:
import { seal } from '@orangecheck/lock-core/seal';
import { utf8Encode } from '@orangecheck/lock-crypto';
declare function walletSignBIP322(message: string): Promise<string>; // your wallet's BIP-322 signer
const envelope = await seal({
payload: utf8Encode('hi bob'),
sender: {
address: 'bc1qalice…',
signMessage: async (msg) => walletSignBIP322(msg),
},
recipients: [{ address: 'bc1qbob…', device_id: '…', device_pk: '…' }],
});
Unseal:
import type { LockEnvelope } from '@orangecheck/lock-core';
import { unseal } from '@orangecheck/lock-core/seal';
declare const envelope: LockEnvelope; // as the sender sent it
declare const localDeviceSecret: Uint8Array; // this device's device_sk
declare function myVerifier(
message: string,
signatureB64: string,
address: string
): Promise<boolean>;
const result = await unseal({
envelope,
device: { device_id: '…', secretKey: localDeviceSecret },
verifyBip322: async (msg, sig, addr) => myVerifier(msg, sig, addr),
});
const plaintext = new TextDecoder().decode(result.payload);
Device-key lifecycle:
import {
buildBindingStatement,
deriveNostrKey,
finalizeDeviceEvent,
generateDeviceKey,
} from '@orangecheck/lock-device';
declare const btcAddress: string; // the address the device binds to
declare const wallet: { signBIP322(message: string): Promise<string> }; // your wallet
const kp = generateDeviceKey();
// nostr_pk makes this the v3 statement publishers must emit: it signs the one
// Nostr key that may publish the record, the key finalizeDeviceEvent signs with.
const statement = buildBindingStatement({
address: btcAddress,
device_pk: kp.device_pk,
nostr_pk: deriveNostrKey(kp.device_sk).nostrPk,
device_id: kp.device_id,
created_at: kp.created_at,
});
const signature = await wallet.signBIP322(statement);
const event = finalizeDeviceEvent({
deviceSk: kp.device_sk,
address: btcAddress,
device_id: kp.device_id,
device_pk: kp.device_pk,
bindingStatement: statement,
bindingSigBase64: signature,
});
// publish `event` to Nostr relays of your choice
Layered with orangecheckLink to this section
Need a sybil filter on your inbox? Gate unseal on an orangecheck check:
import type { LockEnvelope, UnsealInput } from '@orangecheck/lock-core';
import { unseal } from '@orangecheck/lock-core/seal';
import { check } from '@orangecheck/sdk';
// as in Unseal above
declare const envelope: LockEnvelope, device: UnsealInput['device'];
declare const verifyBip322: UnsealInput['verifyBip322'];
const ok = await check({
addr: envelope.from.address,
minSats: 100_000,
minDays: 30,
});
if (!ok.ok) throw new Error('stake too low');
const out = await unseal({ envelope, device, verifyBip322 });
NextLink to this section
- Protocol walkthrough — narrative version, flow diagrams.
- Specification — normative rules, canonicalization, error codes.
- FAQ — common questions.