winnow

Winnow · Architecture

How Winnow works.

Your phone finds and checks payments, keeps your wallet history, and signs with the keys you control.

Clearnet connections use your device’s IP address; your own Tor or I2P gateways can carry peer connections instead. Peers can see which blocks you request. Read the privacy and trust limits.

1 · Find payments on your phone

Winnow checks public block filters against your wallet on the phone. A possible match triggers a block download to check for your payments.

Every block · always

filter · newestchecked
filter · newerchecked
filter · olderchecked
filter · olderchecked
filter · oldestchecked

the same public filter any compact-filter client can request

MATCHED HERE against your own scripts, on the device

On a hit only · rare

a whole block the one block that matched

only when a filter matches

Your addresses stay on the device during filter matching. Requested blocks can still reveal interests to peers. Discovery and trust.

2 · Watch for pending payments

While Receive is open, Winnow briefly listens for relayed transactions and checks them locally. This can show a payment before it confirms; the listening window ends when you leave.

block
block
block
RECEIVE SCREEN OPEN
your payment
relayed transactions · matched locally your payment, spotted on the device

This uses extra bandwidth and can miss unconfirmed payments. Block scanning finds confirmed payments later. Phone resource limits.

3 · Restore from saved history

A new wallet scans from its creation height. A restored wallet resumes from the history and scan position in its iCloud or manual backup.

New walletstart at creation height H
never scanned
scanning forward →
Imported walletsaved at height H · resume from there
saved history
verifying →

Automatic encrypted iCloud recovery includes this phone’s signing key, history, multisig accounts, the signer list and saved people. Simple mode shows its save status; Advanced can turn it off. For manual recovery, keep both recovery words and a backup file. Words alone do not restore past payments or multisig accounts. A phrase-free file restores watch-only access on a replacement device; manual JSON import needs a file containing the words to restore signing. Cloud recovery requires the same Apple Account with iCloud Keychain. Without iCloud, the wallet remains usable and offers a manual backup. Backup and recovery.

4 · Spend from a k-of-n account

A multisig account is a Taproot address with no usable key path, tr(NUMS, sortedmulti_a(k, …)). Any k of its n signers can approve a payment. Each signs the same script-path message on its own, in any order, with no rounds between them. The PSBT carries the signatures from one signer to the next.

Build the payment

Send builds an unsigned PSBT from the account’s coins. Copy it to the other signers however you like; a co-signer’s Winnow pastes it back. There is no coordinator server.

Each signer signs alone

This phone, a Ledger or a Bitcoin Core wallet signs the BIP341 script-path message for the leaf and adds its signature to the PSBT. A Ledger first shows the payment on its own screen.

Finalize

Once k signatures are in the PSBT, Finalize and broadcast writes the witness and relays the transaction to peers.

→

On chain

k signatures · the leaf script · its control block · P2TR script-path

The spend reveals the leaf and its k signatures, with an empty slot for each key that did not sign. Anyone can see it was a k-of-n spend and which keys signed.

Optional recovery leaf

Opens after a delay: once a coin has not moved for a chosen number of blocks (older(N)), fewer of the same signers, or a separate recovery key, can spend it. Until then the leaf refuses it.

Each signer keeps an independent key and backup; recovery words restore the wallet, not its accounts. CI’s recorded journeys build a 2-of-3 with two Bitcoin Core wallets, spend from it with two signatures and then on the recovery path, and spend a 2-of-2 with a simulated Ledger. A real Nano X co-signed a mainnet 2-of-2 with the Swift app (0.8.14); the Lean app’s CI uses a simulated Ledger. Signing and recovery limits.

5 · Compare peer responses

Winnow compares filter checkpoints from up to three peers to detect disagreement. It also limits concentration when choosing peers automatically.

peer A cfcheckpt 000000a3f8…e21c ✓ agrees
peer B cfcheckpt 000000a3f8…e21c ✓ agrees
peer C cfcheckpt 0000004b17…9d02 ✕ dropped

For checkpoints, a strict majority identifies a disagreeing peer. Without a majority, Winnow replaces the queried peers. Other filter checks have their own rules.

Several peers can share an operator and agree on false data. These checks do not make the phone a fully validating node. What Winnow verifies.

6 · How the app is built

Winnow is written in Lean 4: the wallet and the app’s model, update and view, compiled to C. Standard UIKit controls draw it, through an Objective-C shell that LeanNative prints from Lean at build time. No Swift is compiled.

Wallet · Lean/Winnow

Keys, transactions, PSBTs, descriptors, compact-filter sync, peers, the mempool window and the broadcaster. Bitcoin P2P runs over Lean’s own TCP, on libuv.

Curve · Lean/Secp

Winnow’s own secp256k1. Lean proofs tie its field and point arithmetic, public keys, tweaks, and BIP340 signing and verification to a specification curve, and the build fails if one rests on an unproved step. It is not constant-time.

App · LeanApp/WinnowApp

Model, update and view, Elm-style: update turns each event into a new model and commands, and view returns a tree of screens and controls.

↓ compiled by Lean to C, linked with Lean’s runtime

Shell · LeanNative

Objective-C on UIKit, held as Lean data and printed into the build directory on every build, never checked in. It draws the view tree with standard UIKit controls and sends events back.

Typed capabilities

What only iOS can do: Keychain, Face ID or passcode, HTTPS GET, Bluetooth LE for the Ledger, CloudKit, background tasks, clipboard and file paths. LeanNative’s Lean clients turn the main ones into typed requests and answers, and the app lists the ones it uses in its manifest.

Project · WinnowApp/Project.lean

The Xcode project is generated from this Lean manifest: bundle id, bundled guides and peer list, background task ids, iCloud container, usage texts. Generation refuses a capability without its usage text or entitlement.

CI checks every Debug, Release and device build for Swift, and a release checks the signed archive and IPA again. The proofs cover the curve arithmetic, not the Objective-C shell or iOS, which are trusted. Lean’s runtime libraries run on iOS retargeted from macOS builds, which Lean does not support officially. Source: winnow-lean (MIT) and LeanNative.