Bitcoin PIR

Quickstart

Add Bitcoin PIR to a wallet in under ten minutes. We'll use the DPF backend — the two-server, stateless flow with the lowest round-trip cost — and the TypeScript / WASM SDK. The same flow works in any browser wallet, in a desktop wallet that ships a Node runtime, or in any JS environment with a WebSocket.

Free while the servers have room

The reference servers serve DPF, HarmonyPIR and OnionPIR free on a best-effort lane (OnionPIR one lookup at a time, within an hourly budget): paid lookups go first, and when the free lane is full a server answers free capacity busy instead. A credit provider added after the sealed channel (step 5) pays for priority then.

By the end you'll have:

  1. The WASM SDK loaded in your app.
  2. A connected WasmDpfClient.
  3. The list of UTXOs for a real on-chain script hash, with a server-side Merkle proof verified locally.

1. Install

npm install pir-sdk-wasm

The package is the wasm-pack output of the pir-sdk-wasm crate. It ships a small JS loader, a .wasm binary, and the TypeScript .d.ts. Bundle works with Webpack, Vite, esbuild, Next.js, and any other tool that understands ES modules.

Not on npm yet?

While the package is finalizing distribution, you can build it locally from the main repo with wasm-pack build --target web --out-dir pkg inside crates/sdk/wasm/, and npm link it. See crates/sdk/wasm/README.md for the canonical build path.

2. Initialize the WASM module

WASM modules need an explicit init() call once per page or worker. The wrapper exported as the module's default re-exports every typed class:

import init, { WasmDpfClient } from 'pir-sdk-wasm';
 
// Loads the .wasm and runs the panic-hook + tracing setup.
await init();

You only need to call init() once. Subsequent imports are no-ops.

3. Connect to the live servers

The reference deployment runs two servers — the hint server and the query server. Both URLs go to the WasmDpfClient constructor in order:

const client = new WasmDpfClient(
  'wss://weikeng1.bitcoinpir.org',                      // hint server
  'wss://bitcoin-pir-weikeng-laptop.chenweikeng.com',   // query server
);
 
await client.connect();

connect() opens both WebSockets, runs the protocol handshake, and resolves once both are ready. It throws on a malformed URL, a CORS rejection, or a server refusal.

WebSocket only

The endpoints reject plain HTTP — wss:// only. See Live endpoints for the wire contract.

4. Run a query

The SDK takes a packed Uint8Array of script hashes: 20 bytes each, back to back. (Script hashes are the same HASH160(scriptPubKey) that Electrum uses. The SDK doesn't impose a particular wallet stack — derive the hashes however you already do.)

// Example: a single script hash. In a real wallet this would be
// every address derived from your xpub (or, for a watch-only setup,
// every address the user pasted in).
const scriptHash = new Uint8Array([
  0x86, 0xee, 0x42, 0x29, 0x80, 0x4e, 0x21, 0x42,
  0x8e, 0x32, 0x6f, 0x9d, 0xd2, 0xb2, 0x07, 0x90,
  0xbc, 0xcb, 0xe9, 0x6a,
]);
 
// Pack N script hashes into one Uint8Array (20*N bytes).
const packed = scriptHash;
 
// `null`: `sync()` always runs a full sync (the newest snapshot plus
// any deltas up to the tip).
const sync = await client.sync(packed, null);
 
for (let i = 0; i < sync.resultCount; i++) {
  const result = sync.getResult(i);
  if (!result) {
    console.log(`${i}: not found (verified absent)`);
    continue;
  }
  // SOUNDNESS: `merkleVerified === false` means a per-bucket proof
  // failed and the server's response cannot be trusted. Skip the slot
  // (and surface the failure to the user); never display the entries.
  if (!result.merkleVerified) {
    console.warn(`${i}: Merkle FAILED — refusing to display untrusted UTXOs`);
    continue;
  }
  console.log(
    `${i}: ${result.entryCount} UTXO(s), ` +
    `balance ${result.totalBalance} sat`,
  );
  for (let j = 0; j < result.entryCount; j++) {
    console.log('  ', result.getEntry(j));
  }
}
 
console.log('synced at height', sync.syncedHeight);

That's the full flow. Three things to call out:

  • result === undefined (null in JSON) means the script hash is verified absent — the server proved your address isn't in the UTXO set. This is not an error.
  • result.merkleVerified === false means the per-bucket Merkle proof failed. The data is untrusted; treat the slot as if it returned nothing, log it, and surface a wallet-side warning.
  • sync.syncedHeight tells you the block height the result reflects. Persist it and pass it as the second argument on the next call to fetch only the delta.

5. Verify privacy (optional but recommended)

If you want to confirm the live servers are what they claim to be — running the operator-published binary, under the operator's signed identity — call attest() and follow the attestation walkthrough. Neither live server has a TEE (both report sevStatus: noSevHost), so there is no SEV-SNP report or MEASUREMENT to check:

import { PIR1_PIN, PIR2_MACBOOK_PIN, pinAcceptsBinary } from './attest-pin';
 
const attest0 = await client.attest(0); // 0 = hint server
const attest1 = await client.attest(1); // 1 = query server
 
// 1. Compare each server's binary hash to your build-time pin (or the
//    pin's transition build while the operator switches builds).
if (!pinAcceptsBinary(PIR1_PIN, attest0.binarySha256Hex)
    || !pinAcceptsBinary(PIR2_MACBOOK_PIN, attest1.binarySha256Hex)) {
  throw new Error('Server is running a different binary than expected');
}
 
// 2. Upgrade to the encrypted channel so cloudflared (or any other
//    TLS-terminating intermediary) sees only ciphertext.
await client.upgradeToSecureChannel(
  attest0.serverStaticPub,
  attest1.serverStaticPub,
);
 
// 3. Without a TEE, the operator-signed identity is what ties each
//    channel key to the operator: require it before the first query
//    (`announce()` + `gateOperatorIdentity`, see the walkthrough).

The wire to upgradeToSecureChannel is AEAD-sealed end-to-end with ChaCha20-Poly1305 — see Attestation for the full picture.

6. Disconnect cleanly

await client.disconnect();

After this client.isConnected === false. Call connect() again before the next query.

Where to go next

  • Switching backends. DPF is the right default for most wallets. For long-lived sessions where the same wallet does many queries, consider HarmonyPIR — the offline hint phase amortises beautifully. For deployments where you control only one server, use OnionPIR.
  • Inspect the wire. Open the wire explorer and run the same query — every frame is decoded and the four privacy invariants are checked live.
  • Persist sync state. The WasmSyncResult.syncedHeight is the only state you need to round-trip across sessions; the SDK itself is stateless on the DPF path.
  • Handle errors. See Troubleshooting for the common failure modes and what they mean.