Skip to content

How it works

This page follows one transaction from start to finish. New words link to the glossary.

How a transaction is signedSparrow Wallet on your computer shows the unsigned transaction as an animated QR code. The ESP32-CAM scans it and passes it over a one-way wire to the ESP32 DevKit. The DevKit works out the amounts, fee and change itself and shows them on the touchscreen. If you approve, it signs and shows the signed transaction as a QR code, which Sparrow scans and broadcasts.The signing device. No Wi-Fi, Bluetooth or USB data usedSparrow Walleton your computer(watch-only)ESP32-CAMscans the QR codeESP32 DevKitchecks, then signsTouchscreenyou approve or rejectanimated QRone-waywirereviewsigned QR1234How a transaction is signedSparrow Wallet on your computer shows the unsigned transaction as an animated QR code. The ESP32-CAM scans it and passes it over a one-way wire to the ESP32 DevKit. The DevKit works out the amounts, fee and change itself and shows them on the touchscreen. If you approve, it signs and shows the signed transaction as a QR code, which Sparrow scans and broadcasts.Sparrow Walleton your computer (watch-only)animated QR1The signing device:no Wi-Fi, Bluetooth or USB data usedESP32-CAMscans the QR codeone-way wire2ESP32 DevKitchecks, then signsreview3Touchscreenyou approve or rejectsigned QR4Sparrow Walletscans it and broadcasts

Two halves: a watch-only wallet and a signer

Section titled “Two halves: a watch-only wallet and a signer”

The work is split between two programs that never connect to each other.

  • On your computer, Sparrow Wallet is a watch-only wallet. It knows your public keys, so it can show your balance, make addresses and build transactions. It can’t sign, because it never sees your seed.
  • The device is the signer. It holds the seed in memory while you use it, checks each transaction, and signs only if you approve.

To set this up, the device shows its account’s public key as a QR code (an output descriptor holding a tpub). Sparrow scans it with the computer’s webcam and creates the watch-only wallet. From then on, both sides agree on the same addresses, and you can check any of them on the device’s own screen.

When you send coins, Sparrow builds an unsigned transaction in the PSBT format (“Partially Signed Bitcoin Transaction”, BIP174). A PSBT holds the transaction plus extra data the signer needs: which coins are being spent, how much they’re worth, and which of your keys they belong to.

The signer must not simply trust that extra data. The computer could be infected with malware, and a PSBT is just data the computer wrote. Much of what follows is about how the device checks it.

A PSBT is usually too big for one QR code that a small camera can read, so Sparrow shows it as an animated QR in the UR format. Each frame begins UR:CRYPTO-PSBT/ and carries a small piece of the data.

UR uses “fountain codes”: the frames are mixed in a way that lets the scanner start at any frame, miss some, and still rebuild the whole PSBT once it has collected enough. A progress bar on the device shows how far it has got.

The ESP32-CAM is only a scanner. It reads each QR code and sends what it read to the ESP32 DevKit over one wire, from the camera board’s GPIO14 to the DevKit’s GPIO34.

  • Data only goes one way. There is no wire back from the DevKit to the camera board, and GPIO34 on the DevKit can only receive. The signer can’t be made to send anything to the camera.
  • Every frame is checked. Each one carries its length and a checksum (CRC-32). The DevKit treats every byte as hostile: it throws away anything malformed, too long or with a wrong checksum, and counts it. In a flood test with random data, it ran for minutes without crashing.
  • Its limit: the camera board still sees everything it scans, including a SeedQR if you use one, and its chip has a radio. The one-way wire stops data from flowing back; it doesn’t make the camera board itself trusted.

The device is stateless: it never saves your seed. Nothing secret is written to its flash memory.

  • Each session starts by loading the seed. You type the 12 or 24 words (BIP39) on the touchscreen, with autocomplete, or scan a SeedQR. An optional passphrase can be added.
  • The device shows the wallet’s fingerprint after loading. Compare it with the one you noted, to catch a typo in the words or the passphrase.
  • A new seed can be made on the device, from the chip’s hardware random number generator, optionally mixed with dice rolls you enter. The device then shows the words and quizzes you on a few of them, to make sure you wrote them down.
  • When you’re done, “Wipe & lock” clears the seed from memory and restarts the device. It also locks itself after 5 minutes without a touch.

The device’s own screen is the only display it trusts. It recalculates everything from the PSBT, and ignores labels or “this is change” claims that the computer might add.

  • Every input must be yours. Each coin being spent must carry the key path of your wallet, and the device re-creates the key itself to confirm it. If any input isn’t yours, it refuses the whole transaction.
  • Amounts are verified. With more than one input, the device needs a copy of the earlier transaction that created each coin. It checks that copy against the coin’s ID and reads the amount from it. Without these copies, a known attack (CVE-2020-14199) can trick a signer into paying a much larger fee than it shows, so the device refuses.
  • With one input, the copy is optional. For a single input, a lie about the amount can only produce a signature the network rejects, so the device accepts the transaction. It notes on the summary that the fee wasn’t independently verified.
  • Change must prove it’s yours. An output counts as change only if its key path is on your wallet’s change branch and the device re-creates exactly the same address. Anything else is shown as a payment to someone else.
  • The fee is worked out on the device: the inputs minus the outputs. You get an extra warning screen if the fee is over 1% of the amount sent or over 50,000 sats, or if the fee rate is over 500 sat/vB.
  • Unusual signing modes and address types are refused. The device only signs with SIGHASH_ALL and only spends native SegWit coins (BIP84). It refuses Taproot and data-only (OP_RETURN) outputs, which it can’t show correctly yet.

Then you review it on the touchscreen: one screen for each recipient, with the full address split into groups of 4 characters and the amount, followed by a summary of the total sent, change, fee and fee rate. Reject is the default. Approving takes a deliberate tap and a second confirmation.

The device doesn’t give the scanned PSBT to its Bitcoin library. The library has known weaknesses with hostile data, and the scanned PSBT was written by the computer.

Instead, the device reads the PSBT with its own strict parser and checks it as above. It then builds a new, minimal PSBT holding only the values it has verified, and that rebuilt copy is what the library signs. So the signature can only cover what you saw on the screen. Before showing the result, the device also checks that every signature is valid.

The device shows the signed PSBT as an animated QR code, with a button to change its density if the webcam struggles. Sparrow scans it, checks it, and broadcasts it to the signet network. The device then wipes the transaction from memory, and the seed stays loaded until you choose “Wipe & lock” or the timeout runs out.

What the prototype protects against, and what it doesn’t, is on the next page: Security and limits.