Concept & philosophy
Bitcoin Tools is built around three principles: self-custody, local-first, and source transparency.
1. Non-negotiable self-custody
No private key, no seed and no wallet password ever passes through Bitcoin Tools. Bitcoin Tools builds an unsigned PSBT; the “Sign” button only hands that PSBT to your wallet (Xverse), which asks for your explicit approval. Once you approve, Bitcoin Tools receives the finalized transaction and your browser broadcasts it directly to mempool.space (Blockstream.info as fallback). The guarantee is therefore precise: Bitcoin Tools cannot produce a spendable transaction without your wallet signature approval — but once signed, broadcast can proceed automatically.
2. Local-first: your IndexedDB is the source of truth
Wallet scans, UTXO enrichments, selections and preferences are persisted in your browser across several specialized local stores, most of them IndexedDB databases. This enables:
- instant navigation between tools without re-fetching,
- offline analysis (PSBT Inspector),
- local persistence of your results: they are stored on your device and are not uploaded as a whole.
Local persistence is not the same thing as total isolation. To fetch UTXOs, enrichments or transaction statuses — and for the optional AI analysis — Bitcoin addresses, outpoints, transaction IDs and decoded transaction data are transmitted to the required data providers and proxies. That traffic is temporary network processing; what is stored durably stays on your device.
Main local stores (non-exhaustive)
| Cache | Content | TTL |
|---|---|---|
scanCache | Full wallet scan result (ordinals + payment UTXOs + rare sat groups) | 7 days |
ordinalsEnrichmentCache | Ordiscan enrichment per txid:vout (sat-ranges, inscriptions, runes, satributes) | ~permanent |
addressUtxosCache | Raw mempool.space UTXOs per address + network fingerprint | invalidated on fingerprint change |
psbtCache | PSBT enrichment indexed by SHA-256 hash of the payload | ~permanent |
addressEnrichmentCache | Address-level Ordiscan enrichment (inscriptions, BRC-20 balances) | 120 s (anti-burst) |
paymentRiskScans | Risk scan result for the payment address | 7 days |
This table lists the principal stores; it is deliberately not an exhaustive inventory of every internal cache. Note that the detailed transaction history displayed by Bitcoin Tools is not kept in IndexedDB: it lives in localStorage, keyed by network and address.
3. What touches the server (and what doesn't)
What stays local
- Your private keys and seed (always inside Xverse).
- All wallet scans, enrichments and UTXO selections.
- PSBTs being built.
- The full functional transaction history shown by Bitcoin Tools (pending and confirmed), stored in your browser's localStorage and keyed by network and address.
Reading and refreshing these items still requires network calls: addresses, outpoints and transaction IDs are sent to the data providers described below in order to obtain UTXOs, enrichments and confirmation statuses.
What goes through the server
- Ordiscan calls: your personal key (BYOK) is encrypted server-side using AES-256-GCM; it is decrypted in memory only for the duration of a call and is never returned to the client.
- mempool.space proxy: keyless relay used for read/query traffic (fee rates, prices, chain tip, address and UTXO lookups) with a light server cache. Signed-transaction broadcast does not use this proxy: your browser posts the finalized transaction directly to mempool.space, with Blockstream.info as fallback.
- Non-PII analytics: on login, your Supabase
userId, country/region (Cloudflare headers) and a SHA-256 hash of your IP are recorded. The raw IP is never stored. - Operational usage telemetry: when a transaction is broadcast, the app's analytics implementation may record a server-side record of the operation (identifiers and summary figures such as the txid, the tool used, the fee and the number of inputs). This is telemetry, not the detailed history you see in the interface, which remains local.
- Optional AI audit in the PSBT Inspector (explicit button): sends the decoded JSON payload to a Supabase function, never your key or personal information.
4. Demo mode
Demo mode loads a wallet snapshot (UTXOs, runes, inscriptions, BRC-20) pre-captured by an administrator. All tools behave as if you were connected, with one exception:
Live BRC-20 and pending-tx polling are also disabled in demo to avoid consuming your Ordiscan key.
5. BYOK: Bring Your Own Key (Ordiscan)
Ordiscan is our primary source for sat-ranges, inscriptions, BRC-20 balances and rune metadata. A free key gives you 1,000 requests per month — plenty for normal personal use.
You can store up to 5 keys. When one hits its quota, the next is used automatically. See Prerequisites for the setup procedure.
6. Wallet roles and ORD / PAY / CHANGE badges
Across History, transaction details and every builder preview, inputs and outputs carry a small badge that describes the address family of the script, derived by decoding the script for the active network — not by comparing strings to your connected addresses.
- ORD (orange) — Taproot (P2TR) script, the family used by the Ordinals wallet.
- PAY (blue) — validated payment family: Native SegWit, or a supported validated Nested SegWit form.
- CHANGE (blue) — the output that returns the remainder of the transaction to your Payment wallet. It replaces the PAY badge on that output; inputs are never labelled CHANGE.