Bitcoin PIR

Payments (credits)

Lookups a server charges for are paid in credits. A wallet buys Cashu ecash over Lightning and spends it one frame at a time; the servers never learn who bought it, and nothing links a lookup to a purchase. The design and the rate card live in docs/CREDITS.md in the main repo; this page is the wallet-side view.

Who charges

Every server decides, per backend, whether its lookups are free, paid, or best-effort — free while the server has room, with paid lookups served first — and publishes that in its GET_INFO_JSON answer ("credits": { "access": { "dpf": { "mode": "best-effort", … }, … } }). The SDK reads each server's own policy, so one wallet works against free, paid and mixed servers, including ones other operators run.

ServerServesAccess
pir1 — wss://weikeng1.bitcoinpir.orgDPF server 0, HarmonyPIR hints, OnionPIRDPF and HarmonyPIR hints best-effort (free hint work capped per hour); OnionPIR best-effort, one lookup at a time within an hourly budget
pir2 — wss://bitcoin-pir-weikeng-laptop.chenweikeng.com (MacBook, no TEE)DPF server 1, HarmonyPIR queriesDPF and HarmonyPIR queries best-effort; the server itself runs best-effort and may be offline
ORAM host — wss://weikeng2.bitcoinpir.org (VPSBG, AMD SEV-SNP)Direct ORAMDirect ORAM best-effort

So every backend is free while the servers have room (OnionPIR one lookup at a time within an hourly budget); credits buy priority when a free lane is busy.

A best-effort frame goes out unpaid. When the server's free lane is full, or a lane with an hourly budget has used it up, the server answers free capacity busy: …; the SDK then pays for the frame and sends it again if the wallet has credits, and reports the busy answer otherwise. Whether a lookup is served free, queued or refused depends only on the server's load and the connection's balance, never on what is looked up.

Try it without paying

The playground runs every backend for free while the servers have room. When a free lane is busy it shows exactly where a lookup stops without credits.

Price

1 credit10 sat
Top-upany amount of sat: through the mint's Lightning invoice, or over x402 from the issuer (10 to 20,000 sat per purchase)

Rate card for one single-address lookup, when both servers of a backend charge for it (docs/CREDITS.md): DPF ≈ 2, HarmonyPIR ≈ 5 (fresh hint set), OnionPIR ≈ 10, Direct ORAM ≈ 1 credits. Servers meter real work in gas (1 credit = 72,000 gas; a fixed 20 gas per frame plus 1,000 gas per MB of response), so a batch costs less per address than a single lookup.

How it works

  1. Buy. Either rail ends with ecash only the wallet can spend. The wallet asks the Cashu mint (https://mint.bitcoinpir.org) for a Lightning invoice, pays it, and mints into its own blinded outputs; or it buys over x402 from the issuer (https://issuer.bitcoinpir.org, POST /v2/x402/ecash): it sends its blinded outputs, pays the invoice bound to that request, and the issuer swaps its own ecash into those outputs at the mint and returns the blind signatures. The wallet unblinds the signatures itself.
  2. Spend. After the sealed channel is up, the client presents ecash on each connection that needs it (REQ_CREDIT_PRESENT, opcode 0x12, kind 1, only accepted inside the encrypted channel): a cashuB… token worth at least the credits the round needs.
  3. Settle. The server forwards the token to the issuer (/v2/redeem), which swaps it at the mint (the mint refuses spent proofs) and credits the connection with gas (7,200 gas per sat). The server then serves metered frames until the balance runs out; the client tops up transparently, and any overpay stays as connection gas.

What each party sees: buying from the mint, the mint sees the Lightning payment and the buyer's network address; over x402, the issuer does. Both see only blinded outputs. On a lookup, a server sees the connection and the token, the issuer which server redeemed it and when, and the mint the proofs being swapped. A proof is unlinkable to its purchase (blind signatures; the wallet keeps no DLEQ blinding data), and PIR hides the query contents from everyone regardless.

In the SDK

Every client takes a credit provider: a function that returns a presentation worth at least credits credits, or null when the wallet is empty.

type CreditProvider = (credits: number) =>
  { kind: number; payload: Uint8Array; credits: number } | null;

WASM clients (DPF, HarmonyPIR, Direct ORAM)

Call enableCredits after the sealed channel (presentations are bearer material). It reads the server's policy for the client's backend and funds that connection's paid frames from the provider — or, on a best-effort server, only the frames its busy free lane refuses:

await client.upgradeToSecureChannel(att0.serverStaticPub, att1.serverStaticPub);
 
// 'not-enabled' | 'not-required' | 'required' | 'best-effort'
const s0 = await client.enableCredits(0, wallet.present.bind(wallet)); // pir1
const s1 = await client.enableCredits(1, wallet.present.bind(wallet)); // pir2

WasmOramClient.enableCredits(provider) takes no server index (one server). With an empty provider, a backend a server charges for stops at the first metered frame with credits required: this frame needs N more credit(s) and the wallet has none, and a best-effort backend whose free lane is full returns the server's free capacity busy: ….

TypeScript adapters and the OnionPIR client

OnionPirWebClient, OramPirClientAdapter and the DPF / HarmonyPIR adapters in bitcoin-pir-web take the provider as a config field and report what each server decided:

new OramPirClientAdapter({
  ...config,
  creditProvider: wallet.present.bind(wallet),
  onCredits: (status) => console.log('credits', status.state),
});

A wallet

bitcoin-pir-web ships the browser wallet the reference site uses:

import {
  IssuerClient, CashuStore, openCashuWallet, topUpFromMint, topUpX402,
  PRODUCTION_ISSUER_URL,
} from 'bitcoin-pir-web';
 
const issuer = new IssuerClient(PRODUCTION_ISSUER_URL);
const store = new CashuStore();                  // localStorage
const wallet = await openCashuWallet(store);     // loads cashu-ts
// wallet.present is the credit provider.
 
// Top up 1,000 sat through the mint's Lightning invoice: shows the invoice
// through `onInvoice`, waits for payment, mints into the wallet's own
// blinded outputs and stores the proofs.
await topUpFromMint(issuer, store, 1000, { onInvoice: (bolt11) => showInvoice(bolt11) });
 
// Or over x402 from the issuer (pays through WebLN when the browser has it).
await topUpX402(issuer, store, 1000, { onInvoice: (bolt11) => showInvoice(bolt11) });

Both top-ups are resumable: the wallet stores its blinded outputs before minting, so if the page closes after payment, calling the same function again finishes it. Presented proofs move to "in flight" and are checked with the mint after two minutes (wallet.reconcile()); unspent ones come back. The ecash lives only where the store keeps it — clear that storage and the unspent ecash is gone, by design.

Browser origin

The issuer answers cross-origin requests only from origins it lists, so a wallet served from another origin needs to be added on the issuer (cors_origins) before it can top up in the browser.

Rust

pir_sdk_client::credit_transport has the same shape: implement CreditProvider (present(&self, credits) -> PirResult<Option<Presentation>>) and call the client's enable_credits(server_index, provider) after the secure-channel upgrade; it returns the server's CreditStatus for that backend (NotEnabled, NotRequired, Required or BestEffort).