Field guide / Reference

A field guide to what a Bitcoin app is made of.

Read this in the order a request travels: from what you see, down through the layers that decide what the app can do, and out to the network. You can read straight through or jump to the part that matters for your project.

Keys and where they live

A Bitcoin key is a secret number. Whoever holds it can authorize spending from the addresses it controls, so an app has to answer one question before anything else: where does the secret live, and who can read it?

Three answers cover most designs. The key can be generated and kept on the device the app runs on. It can sit on a separate signing device that the app talks to through a defined step. Or the app can hold no key at all and work only with public information.

Each answer moves risk somewhere else. On-device keys are simple, and they depend on that device staying safe. A separate signer adds a step and a second device to lose or misconfigure, but it keeps secrets out of the app's code paths. A watch-only design shrinks what a compromise can do, and it cannot spend.

Signing is a separate act

A transaction is valid only when it carries signatures that satisfy the conditions on the outputs it spends. A careful app treats building and signing as two steps. Building assembles inputs, outputs and a fee. Signing proves ownership. Keeping them apart lets you review what will move before any secret is touched.

Ask whether the app shows every output, the destination and the fee before it asks for a signature. If it cannot show you what it is about to sign, its review screen is decoration.

Chain data is a claim you check

An app needs balances, histories and fee conditions. It can get them from a full node it runs, from a light client that verifies less on its own, or from files a person imports. The source matters, because it decides whose version of the chain the app repeats back to you.

A full node checks the rules itself. A light client trusts peers for part of the picture, which is cheaper and leaves a dependency. File import makes review possible but rules out live use. None of these is a moral choice. Each is a decision about what you are willing to take on trust.

Backups are a tested process

Recovery material is only useful if it works on the day you need it. Write it down offline, keep copies in separate physical places, and test a restore before you rely on it. An app with a backup flow should make that test part of setup, not a link buried in settings.

Be wary of any design that asks you to type recovery material into a web page or an app you have not reviewed. Recovery material belongs only in a process you control.

Network requests reveal more than you think

Every request an app makes tells a server something: the address you connect from, the times you connect, and what you ask for. Over time those details can be linked. Push notifications, remote fee lookups and data feeds each leak timing or intent in their own way.

Good designs make network traffic explicit, batch it where they can, and let you route it through a proxy you choose. When an app fetches outside data, ask what it fetches, from whom, and how often.

What to check yourself

  • Whether the signing screen shows the full transaction before a signature is requested.
  • Whether recovery material is ever displayed outside of setup.
  • Which hosts the app contacts, and whether you can see or change that list.
  • Whether the source is available to a reviewer you trust, and whether the released build matches it.

For a line-by-line version of these questions, use the review checklist.

Words we use

Watch-only
An app or wallet that can see public data and prepare transactions without holding any signing key.
Signer
The component that holds keys and produces signatures, either on the same device or on a separate one.
Full node
Software that downloads and checks every block against the rules, rather than trusting others to do so.
Light client
Software that verifies less itself and relies on peers for parts of the chain history.
Satoshi
The smallest unit of bitcoin. One satoshi is one hundred millionth of one bitcoin.

Not financial, legal, or medical advice

This guide explains architecture and vocabulary. It does not recommend a wallet, an exchange, a custody arrangement, or any amount to hold. For an app that holds funds, a qualified reviewer should read the code and the signing path.

Nettlewick publishes plain-language notes on Bitcoin software at btcapps.me. Write to hello@btcapps.me.

Nothing on this site is financial, legal, or medical advice.