SatoFinder Help

SatoFinder ships two front-ends over the same wallet rules. Both derive identical addresses from the same mnemonic, and both apply the same ordinal/token protection described below. Pick whichever suits you:

• Classic (index.html) — the default. Password-locked vault, auto-lock, per-address sweep previews. Pins @smartledger/bsv@7.1.0.
• Alternate UI (satofinder-modern.html) — a panelled dashboard layout. Auto-locks like Classic, but has no password vault; one consolidated recovery transaction instead of per-address sweeps. Pins @smartledger/bsv@7.1.0.

They are not the same security model, and the differences are not cosmetic — see Alternate UI before you use it with real funds.

• Your mnemonic is encrypted with a password you choose, using PBKDF2-SHA256 (310,000 iter) → AES-GCM, and stored in localStorage only.
• The encrypted blob is the only source of truth on this device — there is no password recovery. If you forget the password, you must wipe the vault and re-import the mnemonic.
• The app loads the BSV library from jsDelivr, pinned with SHA-384 Subresource Integrity — @smartledger/bsv@7.1.0 on both pages. A compromised CDN cannot ship modified code: the browser refuses to run a bundle whose bytes don't match the pinned hash.
• Strict Content-Security-Policy blocks all inline scripts except the one hashed into the policy, and only allows network calls to a fixed allowlist (api.whatsonchain.com, api.bitails.io and ordinals.gorillapool.io in Classic; api.whatsonchain.com and ordinals.gorillapool.io in the Alternate UI).
• The wallet auto-locks after 10 minutes of inactivity, and when the tab is hidden. Private key / mnemonic are cleared from memory. Classic locks the instant the tab is hidden; the Alternate UI waits 60 seconds first (see Alternate UI).
• Keys are hidden by default. Click "Show private keys" to reveal — they will be visible until you toggle back or lock the wallet.

On first visit you get three choices:

• Create new wallet: pick 12-word or 24-word entropy, write down the mnemonic, confirm by re-typing the last word, set a password (and optionally a BIP39 passphrase).
• Import mnemonic: paste an existing 12/24-word BIP39 phrase, optionally provide a BIP39 passphrase, set a password.
• Unlock (only if a vault already exists on this device).

Write your mnemonic on paper. Do not screenshot or email it.

BIP39 defines an optional passphrase that is fed into the seed derivation alongside the mnemonic. The same 12 or 24 words combined with a different passphrase produce a completely different wallet (different addresses, different keys). This is also known as the "25th word" or "BIP39 hidden wallet".

• If you're importing from a wallet (Trezor, Ledger, Electrum, Sparrow, etc.) that uses a passphrase, you must enter the same passphrase here — otherwise SatoFinder will derive a different address set and show no coins even though your funds are safe on chain.
• If you're creating a new wallet you can leave it blank for the standard BIP39 default. Setting one adds a second secret you must back up alongside the mnemonic.
• The passphrase is not the same thing as your SatoFinder unlock password. Both are stored encrypted in the same vault blob; both are required to derive your keys.
• There is no passphrase recovery. If you set one and forget it, your funds are unreachable — the mnemonic alone is not enough.

SatoFinder supports both BIP32 (m/0'/external'/index') and BIP44 (m/44'/coin'/account'/change/index) paths.

The Wallet preset dropdown picks the right coin / account index for popular BSV wallets (Atomic, Exodus, Keevo, MoneyButton, RelayX, SimplyCash, Twetch). Editing any path field marks the preset as "custom".

Enter the recipient address and amount (in satoshis). Click Build transaction. The app fetches UTXOs from WhatsOnChain, builds and signs the transaction using a two-pass fee calculation (no under-fee bugs), and shows you the full transaction (destination, amount, fee, change, raw hex) before you confirm.

Show raw transaction hex expands a panel with the signed hex, a Copy hex button, and a link that opens WhatsOnChain's broadcast page in a new tab. Paste the hex into WoC's Decode tab to independently verify inputs, outputs and fee before coming back here to confirm.

Nothing leaves your browser until you click Confirm & broadcast.

Fee rate. The default is 100 sat/KB, and the Fee rate field in the Send panel lets you change it — the value applies to Send and to recovery sweeps, persists across reloads, and is shown on the confirm screen so you can see the rate that actually built the transaction. It exists so a change in what miners accept doesn't need a new release: if your transactions stop confirming, raise it. Values are clamped to whole numbers between 1 and 100,000 sat/KB — anything else falls back to the default and says so, since a zero fee builds a transaction no miner will relay.

SatoFinder queries GorillaPool's 1Sat overlay (ordinals.gorillapool.io) on every Send and Sweep to identify UTXOs at your address that carry an inscription (1Sat ordinal / NFT), a BSV-20 token, or a lock script. These UTXOs are automatically excluded from the spendable set — otherwise a sweep or send would burn the NFT or destroy the token by paying it as fee or change.

The Send confirm and Sweep preview panels show a small "🛡 N ordinal/token UTXOs excluded" line whenever protection is in effect. The Alternate UI shows the same line on its Send and Recovery panels.

If the indexer is unreachable when you try to build a transaction, the build is blocked. Silently spending without protection could permanently destroy your ordinals or tokens. Retry when the indexer is back, or use a different network path. (We do not offer a "spend anyway" override in this release.)

The Tokens & ordinals panel is an informational read-only view of what's at your current derived address — useful before you change paths or sweep. Click Load tokens & ordinals to refresh it. Sending or transferring ordinals/tokens is not supported in this release; this is a recovery-focused tool.

If you've used multiple addresses under the same mnemonic, click Scan first 50 addresses to find UTXOs across the first 50 receive and 50 change addresses under your current preset. Bitails serves the multi-address lookup.

The Send recovered coins to field at the top of the panel sets where the sweep transactions go:

• Defaults to your current derived address (whatever the path panel above shows).
• Edit it to send to any other BSV address you control — for example, a hardware-wallet address, an exchange deposit address, or a different account in this wallet.
• Use current resets the field to the active derived address.

Each found address has its own Preview button. Click it to build (but NOT broadcast) the sweep transaction; an inline review block shows the destination, amount, fee, and raw hex. You can copy the hex and inspect it on WhatsOnChain's decode tab before clicking Confirm & broadcast. Only one preview is open at a time; Cancel discards it without broadcasting.

When there are 2 or more matches, a Sweep all button at the top broadcasts a sweep for each pending address in sequence — this path bypasses the per-row preview since the destination is already set explicitly at the top of the panel. Per-address results display next to each row; one failure does not block the rest.

The Export mnemonic panel re-asks for your password before revealing the mnemonic (so a casual onlooker can't read it). You can also download an encrypted backup file (satofinder-vault-…json) — useless without your password, safe to email or archive.

The Alternate UI (satofinder-modern.html) is a second front-end with a panelled dashboard layout — sidebar navigation, live balance, and separate Wallet / Send / Recover / Tokens / History / Backup / Settings panels. It is not a relaxed or "lite" build: it enforces the same ordinal/token protection, the same hard-block when the indexer is unreachable, the same auto-lock, the same CSP inline-script hash pinning, and the same SHA-384 SRI pinning as Classic.

What is the same:

• Derivation. Identical BIP32/BIP44 paths, identical wallet presets, identical addresses from the same mnemonic.
• BIP39 passphrase. Same "25th word" behaviour described above, on the Wallet panel.
• 12/24-word generation. Choose the length under New phrase length. The page re-counts the words it was handed and refuses the phrase if it doesn't match what you asked for.
• Ordinal/token protection. Every Send and every Recovery build queries the 1Sat overlay first and excludes protected UTXOs. Indexer down = build blocked, no override.
• Auto-lock after 10 minutes of inactivity. Same timeout as Classic; keys are wiped from memory and from the page, not merely hidden.

What is different — read this before using it with real funds:

• No vault. Classic makes you set a password up front and keeps your mnemonic encrypted behind it, so locking always costs only a password to undo. In the Alternate UI an encrypted backup is an explicit, optional action on the Backup panel — so if you never save one, auto-lock wipes the wallet and you must re-import your phrase. The Wallet panel warns you about this for as long as no backup exists. Save one and the lock screen offers a password box instead.
• Auto-lock waits 60 seconds on tab-hide, where Classic locks instantly. This is deliberate: the Alternate UI's explorer links open in a new tab, which hides this one, and an instant lock would wipe the wallet the moment you clicked through to inspect the transaction you were about to broadcast. Coming back within 60 seconds cancels the lock. The 10-minute inactivity timer is identical to Classic's, and Lock now on the Wallet panel locks immediately.
• Recovery is one consolidated transaction, not per-address sweeps. Scan for UTXOs walks the receive and change chains, then Build consolidated transaction produces a single signed transaction spending every found UTXO into one destination. Classic instead previews and broadcasts one sweep per funded address.
• A scan that fails, stops. Address lookups are rate-limited and retried with backoff; if one still fails, the whole scan aborts with an error rather than reporting a "complete" scan that quietly omits an address. A recovery tool that under-reports your coins is worse than one that tells you it failed.
• WhatsOnChain only for address scanning — there is no Bitails multi-address lookup, so a large scan is slower (roughly one address every 350ms, staying inside WoC's rate limit). Watch the progress in the status line.
• Settings panel. The API base, explorer base and fee rate (satoshis/KB, default 100, shared by Send and Recovery) are editable and persist in localStorage. Both URLs must be HTTPS, and the API base must be on the CSP connect-src allowlist above — point it elsewhere and the browser blocks the request.

Both pages link to each other in the footer, and both are covered by ./build.sh, which re-pins each page's inline-script CSP hash and verifies its SRI hashes against the live CDN.

SatoFinder no longer installs a service worker, and does not cache itself. Every visit loads the current code.

Earlier versions did cache the app and served it cache-first, refreshing only when the worker file itself changed. That file went untouched from v2.0.0 through v2.4.0, so anyone who had visited before kept running the v2.0.0 app — and never received the BIP39 passphrase support, the 24-word entropy fix, or the ordinal/token spend protection that stops a Send from burning an NFT. It failed silently; there was nothing to notice.

It also bought nothing. This wallet needs the network for balances, UTXOs, history and broadcast, and a Send is blocked unless the ordinal indexer can confirm your UTXOs are safe to spend — so an offline SatoFinder can derive an address and little else. The bundle's integrity comes from SHA-384 SRI, not from the cache.

If you used SatoFinder before v2.5.0: your browser will pick up a replacement worker that clears the old caches, unregisters itself, and reloads the page onto the live version. If you want to force it now, hard-reload (Ctrl/Cmd+Shift+R) or clear site data for this origin.

Want it offline anyway? Save the page. It is a single self-contained file — open the saved copy on an air-gapped machine to derive keys.

SatoFinder is provided as-is, free, with no warranty. The author is not responsible for any loss of funds. Always verify the raw transaction hex before broadcasting if you are moving significant value, and test with small amounts first.