Skip to content
On this page

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.

Code
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:

  1. Recomputes the envelope id and verifies the sender's BIP-322 signature.
  2. Looks up your local device key by device_id.
  3. Derives shared = X25519(device_sk, eph_pk) from the recipient entry.
  4. Unwraps the content key under HKDF(shared, salt=nonce_ct).
  5. 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-device

Seal:

TypeScript
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:

TypeScript
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:

TypeScript
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:

TypeScript
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