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.
| Server | Serves | Access |
|---|---|---|
pir1 — wss://weikeng1.bitcoinpir.org | DPF server 0, HarmonyPIR hints, OnionPIR | DPF 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 queries | DPF 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 ORAM | Direct 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.
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 credit | 10 sat |
| Top-up | any 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
- 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. - Spend. After the sealed channel is up, the client presents ecash
on each connection that needs it (
REQ_CREDIT_PRESENT, opcode0x12, kind 1, only accepted inside the encrypted channel): acashuB…token worth at least the credits the round needs. - 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)); // pir2WasmOramClient.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.
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).