Bitcoin PIR

Live endpoints

The Bitcoin PIR reference deployment runs two PIR servers — pir1 and pir2 — with deliberately different roles, plus a Direct ORAM host inside an AMD SEV-SNP enclave. Wallets connect to the servers of the backend they use; the SDK handles the routing.

The two roles

EndpointShort nameRoleHardwareSEV-SNPCredits
wss://weikeng1.bitcoinpir.orgpir1Hint server (+ DPF server 0, OnionPIR)Hetzner i7-8700NoDPF and HarmonyPIR hints free while it has room (hints up to an hourly budget); OnionPIR free one lookup at a time, up to an hourly budget
wss://bitcoin-pir-weikeng-laptop.chenweikeng.compir2Query server (+ DPF server 1)MacBook (macOS arm64)NoDPF and HarmonyPIR queries free while it has room
wss://weikeng2.bitcoinpir.orgORAM hostDirect ORAM onlyVPSBG cloud VPS, AMD EPYC 7713P (Milan)Yes (Tier 3 UKI)Direct ORAM free while it has room

Each server publishes what it charges per backend (Payments): DPF-PIR and HarmonyPIR (hints on pir1, queries on pir2) are free while the servers have room, while OnionPIR needs a credit provider.

pir2 has no TEE; Direct ORAM has its own TEE host

Until 2026-10-02 pir2 was a VPSBG AMD SEV-SNP host (Tier 3 UKI) at wss://weikeng2.bitcoinpir.org, which also served Direct ORAM. That host was retired; a MacBook without a TEE now serves the pir2 roles under the server id pir2-macbook-v1. Since 2026-10-03 wss://weikeng2.bitcoinpir.org is a new VPSBG SEV-SNP host (AMD Milan, server id pir2-oram-v1) that serves Direct ORAM only.

The hint/query split is intentional. The hint server runs on commodity hardware because the hint blob alone reveals nothing about which addresses are queried. Neither PIR server has hardware attestation today: each is checked by its binary pin plus its operator-signed identity. The ORAM host is attested by AMD SEV-SNP as well (see Attestation).

                  ┌───────────────────────────┐
                  │ pir1 (Hetzner, no SEV)    │
                  │   - HarmonyPIR hint srv   │
                  │   - DPF server 0          │
                  │   - OnionPIR (single srv) │
                  └─────────────┬─────────────┘
                                │
                                │  hint pool + DPF + OnionPIR
                                │  per-query traffic
                                │
┌──────────┐                    │
│  Wallet  │────────────────────┤
└──────────┘                    │
                                │  DPF + HarmonyPIR per-query
                                │  traffic
                                │
                  ┌─────────────▼─────────────┐
                  │ pir2 (MacBook, no TEE)    │
                  │   - DPF server 1          │
                  │   - HarmonyPIR query srv  │
                  │   (no OnionPIR — runs     │
                  │    on pir1 only; Direct   │
                  │    ORAM: weikeng2 TEE)    │
                  └───────────────────────────┘

WebSocket-only

All three endpoints are WebSocket-only. A plain HTTP GET / returns 502 by design — there is no HTTP fallback, no JSON-RPC layer, no SSE.

Health-checking from the outside requires a real WebSocket handshake (Upgrade: websocket, etc.) followed by a REQ_PING (0x00) frame. A normal curl or wget will not work.

curl will not work

Probing these endpoints with plain HTTP returns 502. The endpoint is healthy if it returns 502 to HTTP and accepts a WebSocket upgrade. Use a WS-aware probe like wscat if you need to test from the command line.

Per-backend routing

Each backend uses the two endpoints differently:

DPF

Connect to both servers. Server 0 = pir1, server 1 = pir2.

new WasmDpfClient(
  'wss://weikeng1.bitcoinpir.org',                      // server 0 (Hetzner)
  'wss://bitcoin-pir-weikeng-laptop.chenweikeng.com',   // server 1 (MacBook)
);

Order matters cryptographically only in that the two share-keys are labelled "server 0" and "server 1"; either ordering is correct as long as the wallet is consistent.

HarmonyPIR

Connect to both, but the role is asymmetric:

new WasmHarmonyClient(
  'wss://weikeng1.bitcoinpir.org',                      // hint server
  'wss://bitcoin-pir-weikeng-laptop.chenweikeng.com',   // query server
);

The hint server (pir1) only sees REQ_HARMONY_HINTS traffic. The query server (pir2) sees per-query frames.

OnionPIR

OnionPIR is single-server. Connect to whichever server hosts OnionPIR. In the current reference deployment that's pir1 — pir2 runs --serve-queries only and does not serve OnionPIR. Check attest-pin.ts for the canonical config.

Direct ORAM

Direct ORAM is single-server too and runs inside an SEV-SNP guest: the server process sees the script hash, the host does not. Since 2026-10-03 it runs on its own VPSBG host (wss://weikeng2.bitcoinpir.org, AMD Milan, server id pir2-oram-v1), free while the guest has room. ORAM_PROVIDER carries its endpoint and pins; it is null only while Direct ORAM is paused, and clients then stop with ORAM_PAUSED_MESSAGE. Use the production request shape — every lookup is one fixed-budget ORAM access with 25 padded slots:

import {
  OramPirClientAdapter, ORAM_PROVIDER, ORAM_PAUSED_MESSAGE, PRODUCTION_ORAM_BATCH_PLANNER,
} from 'bitcoin-pir-web';
 
if (!ORAM_PROVIDER) throw new Error(ORAM_PAUSED_MESSAGE);  // null only while paused
 
new OramPirClientAdapter({
  serverUrl: ORAM_PROVIDER.endpoint,
  batchPlanner: PRODUCTION_ORAM_BATCH_PLANNER,
  // …pins: see the playground's ORAM snippet
});

Reading from the right server

For DPF and HarmonyPIR, the SDK enforces the role. You can't ask pir1 for a per-query response — it's the hint server and rejects unknown variants.

For OnionPIR, the wallet picks the endpoint manually.

Server info / catalog

Both servers respond to:

REQ_GET_INFO      (0x01)  → RESP_INFO        (database parameters)
REQ_GET_DB_CATALOG (0x02) → RESP_DB_CATALOG  (full per-DB catalog)
REQ_PING          (0x00)  → RESP_PONG        (health check)
REQ_ATTEST        (admin) → REPORT bytes     (see Attestation)

The SDK fetches the catalog automatically as part of connect() / sync(). For manual inspection use:

const catalog = await client.fetchCatalog();
console.log(catalog.toJson());

The catalog lists every database the server hosts — typically the full UTXO snapshot at some height, plus a chain of delta databases covering blocks since.

TLS termination

Both endpoints are fronted by cloudflared running on the host. TLS is terminated at the tunnel; the WebSocket is then forwarded to the local unified_server binary on a loopback port.

This means:

  • The CA-issued TLS certificate on the public URL is what your browser sees. Use it for the standard browser-level authentication.
  • For binding to the binary (not just the TLS cert), use the attestation flow — upgradeToSecureChannel wraps the WebSocket in an AEAD layer keyed to the attested server static key.

Running your own

If you're deploying the reference servers yourself, see:

  • pir-sdk-server — the publishable server wrapper.
  • The unified_server binary built by nix build .#unified-server is the production binary.
  • The flake.nix tier3-uki derivation is the UKI build (for SEV-SNP deployments).
  • Operator runbook lives in docs/PHASE3_ROADMAP.md.

Where to go next

  • Attestation — pinning the running binary and checking the operator-signed identity of each server.
  • Wire format — the WebSocket frame layout both endpoints speak.
  • Troubleshooting — connection issues.