Cryptography in Faraday: specifications, code and checks
Every cryptographic action in Faraday, 110 in all. The index, the actions and the list of libraries below are generated from Faraday's manifest, docs/crypto/actions.toml, at release 0.2.0 (SHA-256 e175b3ab42660df464731639eb087edbc5a6c0fe9d5103890dd3fffe0ae5254c), and none of them is written by hand. Faraday's own checks hold the manifest to the code: a cryptographic function the manifest does not cover, a change to one since its entry was last reviewed, or a change to the cryptographic code since the last passing cross-check fails Faraday's checks. The page is generated again each time the website is published for a new release.
Faraday's approach
Faraday follows published specifications: BIPs, SLIPs, RFCs and conventions other wallets already use. Where a specification has an established implementation, Faraday uses it as a library instead of writing its own. A library is code others wrote, published as a Rust crate and pinned to one version; Faraday's own code calls it, checks what goes in and comes out, refuses what it cannot verify, and does every step the library does not. Faraday writes code of its own only where no established implementation exists or none fits its rules for keys, and says why. Where no specification exists, Faraday writes its own, labelled "Own specification, not yet reviewed outside Faraday" until someone outside reviews it. Each action is checked against its specification's published test vectors where there are any, and its results are compared with a second implementation: code others wrote where it exists, otherwise a second version Faraday's authors wrote, which is not an outside check. Actions with no second implementation are marked not cross-checked.
Each row below is one action. Specification is what it follows. Code is the libraries it uses and the crate of Faraday's code that calls them. Cross-checked with is what its results are compared with. The full rule is on the Standards page.
Key to the terms
Specification
Published94A specification others published.
Own specification22A specification Faraday's authors wrote.
Code
Faraday's own code35Code Faraday's authors wrote rather than took from a library; the action says why.
Cross-checked with
Others' code76Compared with code others wrote.
Faraday's second version44Compared with a second implementation Faraday's authors wrote, in Python; not checked against an outside source.
Not cross-checked26Compared with no second implementation.
Grouped as in the app. A filter hides the actions that do not match it; with no filter, every action shows.
Status
Specification
Code
Cross-checked with
Not checked
Own calls
Keys
14 actions · 3 own specification · 3 with Faraday's own code · 10 cross-checked with others' code · 3 with Faraday's second version · 4 not cross-checked
Reads seed words typed, pasted or scanned, and checks their count and checksum.
Specification
BIP 39, Mnemonic code for generating deterministic keys, Deployed
Code
Library: unicode-normalization 0.1.25, by the unicode-rs developers.
Library: sha2 0.11.0, by the RustCrypto developers, through core/faraday-crypto.
Faraday's code: core/faraday-bip: The sentence is read in NFKD and split on Unicode whitespace; the first word not in the list is reported by position; a word typed by pinyin, zhuyin, kana or hangul is composed to the listed word.
Written by Faraday
BIP-39 entry and display: words typed by pinyin, zhuyin, kana or hangul, the last word's candidates, the explorer's view of the checksum (faraday-bip::bip39) · Faraday's own specification
How a person types and sees the words is Faraday's own.
BIP-39 mnemonics: entropy to words and back, the checksum, a word's place in its list (faraday-bip::bip39) · One exists but does not fit Faraday's rules for keys
The Rust BIP-39 library's word lookup takes a time that follows the secret words; Faraday's looks each word up in constant time and is tested against that library and the reference.
Does not fit: bip39 2.2.2 finds a word by a binary search or a scan that stops at it (find_word) and packs entropy with a branch on each bit (from_entropy_in), so the time it takes follows the secret words
Compared with others' code: python-mnemonic, by Trezor (SatoshiLabs), and bip39_slip39, by the btclib developers (a second reader: wordlists, entropy, indices, checksums and the seed in the ten languages).
Area bip39
Faraday's code faraday_bip::bip39
Compared with python-mnemonic (bip39/); bip39_slip39 (bip39-slip39/) answering every operation beside it.
Checked first: Its vendored files are hashed against references.sha256 before any run, and a published vector's answer is required of the reference as well as of Faraday; python-mnemonic's own to_hd_master_key is checked against the seed's master key, as a second BIP-32 master; its wheel is hashed too, and a published vector's answer is required of bip39_slip39 as well.
Vectors The ten wordlists; every vector of tools/vectors/bip39/vectors.json in Faraday's languages; the Japanese vectors with non-ASCII passphrases.
Random cases Entropy to words and back in every language and length; seeds under random ASCII passphrases; a changed word, an unknown word, a word too many or too few; every valid last word.
Differences Both read a BIP-39 sentence in NFKD, so composed words and the Japanese vectors as published parse on both sides (owner, 2026-10-23).
A passphrase typed in Faraday is printable ASCII, at most 256 bytes; python-mnemonic takes any text. Faraday's vector tests and start-up self-test give a non-ASCII passphrase as its NFKD bytes, and the area checks that a typed one, or one past 256 bytes, is still refused.
When it runs Before every release, with a new seed and about ten times the cases.
Last passing runSeed 5be11ec606a76d2767f225b8992c45fe · 30000 cases
A word is found by comparing it with every entry of its list in constant time (subtle), and the entropy's bits are written without a branch; the sentence is gathered by a masked scan, and its length follows the words, as BIP-39 requires; the code states no other timing.
The word buffer and the indices are Secret values, zeroized when dropped; the Mnemonic wipes its indices when dropped.
Limits
Word counts of 12, 15, 18, 21 and 24 only.
A word not in the chosen list is refused and its position reported.
A checksum that fails is refused.
Faraday's own calls
Word entry by readings and kana: typed readings find the listed words. Neutral.
no fuzz target: Takes entropy of a fixed length from the person's own source; no outside text is parsed
Cross-check
Compared with others' code: python-mnemonic, by Trezor (SatoshiLabs), and bip39_slip39, by the btclib developers (a second reader: wordlists, entropy, indices, checksums and the seed in the ten languages).
Area bip39
Faraday's code faraday_bip::bip39
Compared with python-mnemonic (bip39/); bip39_slip39 (bip39-slip39/) answering every operation beside it.
Checked first: Its vendored files are hashed against references.sha256 before any run, and a published vector's answer is required of the reference as well as of Faraday; python-mnemonic's own to_hd_master_key is checked against the seed's master key, as a second BIP-32 master; its wheel is hashed too, and a published vector's answer is required of bip39_slip39 as well.
Vectors The ten wordlists; every vector of tools/vectors/bip39/vectors.json in Faraday's languages; the Japanese vectors with non-ASCII passphrases.
Random cases Entropy to words and back in every language and length; seeds under random ASCII passphrases; a changed word, an unknown word, a word too many or too few; every valid last word.
Differences Both read a BIP-39 sentence in NFKD, so composed words and the Japanese vectors as published parse on both sides (owner, 2026-10-23).
A passphrase typed in Faraday is printable ASCII, at most 256 bytes; python-mnemonic takes any text. Faraday's vector tests and start-up self-test give a non-ASCII passphrase as its NFKD bytes, and the area checks that a typed one, or one past 256 bytes, is still refused.
When it runs Before every release, with a new seed and about ten times the cases.
Last passing runSeed 5be11ec606a76d2767f225b8992c45fe · 30000 cases
Makes the 64-byte seed from words and a passphrase by PBKDF2-HMAC-SHA512, 2048 rounds, and adds the key it gives to the session.
Specification
BIP 39, Mnemonic code for generating deterministic keys, Deployed
Code
Library: pbkdf2 0.13.0, by the RustCrypto developers, through core/faraday-crypto.
Library: sha2 0.11.0, by the RustCrypto developers, through core/faraday-crypto.
Faraday's code: core/faraday-bip: The passphrase is checked to printable ASCII before the derivation; the sentence and salt are built in Secret buffers; a key already held is refused as a duplicate.
Written by Faraday
The BIP-39 seed, PBKDF2-HMAC-SHA512 over the sentence through faraday-crypto (faraday-bip::bip39) · One exists but does not fit Faraday's rules for keys
The seed is derived with the RustCrypto PBKDF2 Faraday uses everywhere, into a buffer that is wiped.
Does not fit: bip39's to_seed returns the seed as a plain [u8; 64], and its own PBKDF2 leaves its HMAC state unwiped (bip39 2.2.2's src/pbkdf2.rs)
no fuzz target: Takes parsed words and a passphrase typed in a field; words-read fuzzes the text
Cross-check
Compared with others' code: python-mnemonic, by Trezor (SatoshiLabs), and bip39_slip39, by the btclib developers (a second reader: wordlists, entropy, indices, checksums and the seed in the ten languages).
Area bip39
Faraday's code faraday_bip::bip39
Compared with python-mnemonic (bip39/); bip39_slip39 (bip39-slip39/) answering every operation beside it.
Checked first: Its vendored files are hashed against references.sha256 before any run, and a published vector's answer is required of the reference as well as of Faraday; python-mnemonic's own to_hd_master_key is checked against the seed's master key, as a second BIP-32 master; its wheel is hashed too, and a published vector's answer is required of bip39_slip39 as well.
Vectors The ten wordlists; every vector of tools/vectors/bip39/vectors.json in Faraday's languages; the Japanese vectors with non-ASCII passphrases.
Random cases Entropy to words and back in every language and length; seeds under random ASCII passphrases; a changed word, an unknown word, a word too many or too few; every valid last word.
Differences Both read a BIP-39 sentence in NFKD, so composed words and the Japanese vectors as published parse on both sides (owner, 2026-10-23).
A passphrase typed in Faraday is printable ASCII, at most 256 bytes; python-mnemonic takes any text. Faraday's vector tests and start-up self-test give a non-ASCII passphrase as its NFKD bytes, and the area checks that a typed one, or one past 256 bytes, is still refused.
When it runs Before every release, with a new seed and about ten times the cases.
Last passing runSeed 5be11ec606a76d2767f225b8992c45fe · 30000 cases
A word is found by comparing it with every entry of its list in constant time (subtle), and the entropy's bits are written without a branch; the sentence is gathered by a masked scan, and its length follows the words, as BIP-39 requires; the code states no other timing.
The sentence, the salt and the seed are Secret values, zeroized when dropped; the key holds its words and passphrase in zeroizing buffers until it is removed.
Limits
A passphrase longer than 256 bytes, or with a byte outside 0x20 to 0x7E, is refused.
Nothing is added while a stick is attached.
Faraday's own calls
A passphrase is printable ASCII, at most 256 bytes. BIP 39 allows any NFKD text, so a wallet made elsewhere with another passphrase cannot be restored here; a letter outside the range typed into a passphrase field is refused. Conservative, F155.
Library: bitcoin 0.32.102, by the rust-bitcoin developers.
Library: secp256k1 0.29.1, by the rust-bitcoin developers (rust-secp256k1), over libsecp256k1, by Bitcoin Core's libsecp256k1 project (bitcoin-core/secp256k1).
Library: hmac 0.13.0, by the RustCrypto developers, through core/faraday-crypto.
Library: sha2 0.11.0, by the RustCrypto developers, through core/faraday-crypto.
Library: base16ct 1.0.0, by the RustCrypto developers, through core/faraday-crypto.
Faraday's code: core/faraday-bip: An extended private key typed or scanned is decoded by Faraday's own strict rules (78 bytes, version, zero parent and child number at depth 0, zero pad byte, scalar in 1..n) before bitcoin sees it; the key is kept on a pinned page; the fingerprint and a 32-byte identity (SHA-256 of the public key and chain code) are worked out once.
Compared with others' code: btclib-wallet's bip32, by the btclib developers, on btclib's own curve; and hdkeychain from btcd v0.27.0, by the btcd developers, on decred's secp256k1.
Compared, for one part, with Faraday's second version, written by Faraday's authors in Python; that part is not checked against an outside source: the three rules of a strict reader that hdkeychain does not make: which versions it takes (BIP-32's xprv and tprv, xpub and tpub, from btclib's network table; btclib reads SLIP-132's too and hdkeychain any version), a version of the other kind than the key's data, and a depth-0 key with a parent fingerprint or an index, in area_bip32.py and bip32_ref.py.
Compared with btclib-wallet's bip32 over btclib and ecc (btclib/), on btclib's own curve with libsecp256k1 turned off, through bip32_ref.py, and hdkeychain from btcd v0.27.0 (btcd/, Go, decred's secp256k1); the versions a strict reader takes (BIP-32's four, from btclib's network table), a version whose kind differs from the key's data, and a depth-0 key with a parent or an index are ours.
Checked first: The wheels and the vendored Go tree are hashed against references.sha256 before any run; check_driver runs btclib against BIP-32's vectors 1 to 5 and the invalid keys of vector 5 before anything else, and every vector is asked of hdkeychain too.
Vectors BIP-32's vectors 1 to 5 (tools/vectors/bip32/), python-mnemonic's master keys.
Random cases Seeds of 16 to 64 bytes on every network, random paths with every index, public derivation against private, keys broken one rule at a time and the master-key import, each judged by btclib and by hdkeychain.
Differences Hdkeychain reads a key of any version, a key whose version is a private one over a public key's data (or the reverse), and a depth-0 key with a parent fingerprint or an index. Faraday refuses all three, as btclib refuses the last; where one applies and btclib refuses, hdkeychain is not asked (uncovered in area_bip32.py), so Faraday's strict reader is not retired.
When it runs Before every release, with a new seed and about ten times the cases.
Last passing runSeed 5be11ec606a76d2767f225b8992c45fe · 4000 cases
The private key and chain code are overwritten when the key is dropped and where the decoded copy stood; the key lives on a pinned page; copies bitcoin makes inside derivation are outside Faraday's reach (stated in the module).
Limits
Only a depth-0 key is a master key; a key at another depth is refused.
An extended key text that breaks any of BIP 32 test vector 5's rules is refused.
Faraday's own calls
An extended private key is decoded by Faraday's own strict reader because bitcoin accepts seven of the sixteen serialisations vector 5 rejects. Conservative.
BIP 44, Multi-Account Hierarchy for Deterministic Wallets, Deployed
BIP 49, Derivation scheme for P2WPKH-nested-in-P2SH based accounts, Deployed
BIP 84, Derivation scheme for P2WPKH based accounts, Deployed
BIP 86, Key Derivation for Single Key P2TR Outputs, Deployed
Code
Library: bitcoin 0.32.102, by the rust-bitcoin developers.
Library: secp256k1 0.29.1, by the rust-bitcoin developers (rust-secp256k1), over libsecp256k1, by Bitcoin Core's libsecp256k1 project (bitcoin-core/secp256k1).
Faraday's code: core/faraday-bip: The account path is purpose'/coin'/account' with the purpose of the script type; an account or index of 2^31 or more is refused; the key text is [fingerprint/path]xpub with h for hardened. Explore reads a path typed with h or ' for hardened, of at most 10 levels, each index under 2^31, and takes the script type from a hardened purpose of 44, 49, 84 or 86; the account of an address path is the path without its chain and index, and none for the multisig purposes 45 and 48.
no fuzz target: Takes a parsed path and a held key; the extended key texts are fuzzed by master's xkey target
Cross-check
Compared with others' code: btclib-wallet's bip32, by the btclib developers, on btclib's own curve; and hdkeychain from btcd v0.27.0, by the btcd developers, on decred's secp256k1.
Compared with btclib-wallet's bip32 over btclib and ecc (btclib/), on btclib's own curve with libsecp256k1 turned off, through bip32_ref.py, and hdkeychain from btcd v0.27.0 (btcd/, Go, decred's secp256k1); the versions a strict reader takes (BIP-32's four, from btclib's network table), a version whose kind differs from the key's data, and a depth-0 key with a parent or an index are ours.
Checked first: The wheels and the vendored Go tree are hashed against references.sha256 before any run; check_driver runs btclib against BIP-32's vectors 1 to 5 and the invalid keys of vector 5 before anything else, and every vector is asked of hdkeychain too.
Vectors BIP-32's vectors 1 to 5 (tools/vectors/bip32/), python-mnemonic's master keys.
Random cases Seeds of 16 to 64 bytes on every network, random paths with every index, public derivation against private, keys broken one rule at a time and the master-key import, each judged by btclib and by hdkeychain.
Differences Hdkeychain reads a key of any version, a key whose version is a private one over a public key's data (or the reverse), and a depth-0 key with a parent fingerprint or an index. Faraday refuses all three, as btclib refuses the last; where one applies and btclib refuses, hdkeychain is not asked (uncovered in area_bip32.py), so Faraday's strict reader is not retired.
When it runs Before every release, with a new seed and about ten times the cases.
Last passing runSeed 5be11ec606a76d2767f225b8992c45fe · 4000 cases
The account is asked after the quorum, not on Kind. Neutral, F98.
Restore takes a seed for a wallet's key slot only when its whole extended public key at the slot's path matches the wallet's, not the four bytes of its fingerprint. Conservative, F155.
Holds a key in memory blinded and on pinned pages.
Specification
Own specification (no decision)
Code
Library: subtle 2.6.1, by the dalek-cryptography developers.
Library: secp256k1 0.29.1, by the rust-bitcoin developers (rust-secp256k1), over libsecp256k1, by Bitcoin Core's libsecp256k1 project (bitcoin-core/secp256k1).
Faraday's code: core/faraday-crypto: Each key's signing context is randomized from the session's randomness, again whenever it changes (a key a signing job holds is randomized as soon as the job's answer is applied or dropped), each key's blind drawn by HKDF-Expand under a count so no two are the same; pinned pages hold a long-lived secret apart from other data and are asked to stay out of swap; words, passphrases and seeds are values wiped on drop.
Written by Faraday
WipeOnFree, the allocator that wipes what it frees (faraday-crypto::wipe) · No established implementation exists
No wiping allocator comes from a publisher Faraday's dependency review trusts; this one is installed in no shipped program (F181).
An outside review recorded in a decision ends it; a reproduction from the specification by an outside party is asked for in docs/AUDIT-SUBMISSIONS.md §10.
not cross-checked: Nothing outside the program reads these values
Secret and Pinned comparison is constant time (subtle's ConstantTimeEq, documented in secret.rs and pinned.rs).
A Secret and a Pinned page are zeroized on drop. Not reached: a secret while it is live in a plain type, the stack and registers, memory other code allocates, a copy in freed heap until the process ends (the next lock on the device), and anything outside the process (none on the device; the computer's own on the desktop).
Limits
Pinning is a feature of the desktop app and of the stick and Pi images (faraday-crypto's pin-pages); a build without it holds the same value unpinned.
Faraday's own calls
A key's signing context is blinded from the session's randomness. Neutral.
Library: base16ct 1.0.0, by the RustCrypto developers, through core/faraday-crypto.
Faraday's code: faraday/faraday-keys: Answers only its own reason, and only for a key with no words; the codex32 secret is recovered from the strings held once their count reaches the set's threshold.
no fuzz target: Takes a held key and a reason; no outside input is parsed
Cross-check
Compared with others' code: python-codex32, by Ben Westgate, and rust-codex32, by Andrew Poelstra (which decides the threshold of 0 or 2 to 9 and a threshold of 0's share index).
Compared, for one part, with Faraday's second version, written by Faraday's authors in Python; that part is not checked against an outside source: two rules BIP 93 states that neither enforces (the seed's lengths, the order shares are handed out), written in area_codex32.py from the BIP's text.
Area codex32
Faraday's code faraday_bip::codex32
Compared with python-codex32 (codex32/); rust-codex32 at a pinned commit (rust-codex32/), a program outside the workspace: parsing, checksums, the threshold and a threshold of 0's share index, interpolate_at for a fresh set's shares; volvelle-website's checksum worksheet run as a program over every worksheet of 48 and 74 characters; the worksheet of 127 characters written in the area from python-codex32's polymod.
Checked first: Its vendored files are hashed against references.sha256 before any run (the Rust programs' sources included, built offline by run.sh with the toolchain on the PATH), and a published vector's answer is required of the reference as well as of Faraday; rust-codex32 and python-codex32 must give the same answer where both are asked; two rules BIP 93 states that neither enforces (the master seed's sizes, the order shares are handed out) are written in the area from the BIP's text, and the worksheet of 127 characters from BIP 93's polymod alone.
Vectors Every vector of tools/vectors/bip93/, the 55 invalid strings included; volvelle-website's worksheet cells (tools/vectors/codex32-volvelle/); the booklet's checksum, derivation, recovery, addition, translation and fusion tables (tools/vectors/codex32-booklet/); the Codex32QR profile's sets (tools/vectors/codex32qr/).
Random cases secrets, splits (the same randomness), recovery, derived shares, corrupted strings; fresh sets of every threshold up to 31 strings at 48, 74 and 127 characters, the checksum worksheets of their strings and of corrupted ones, checksums made on a sheet, translation and recovery symbols, translation worksheets.
Differences Codex32: Faraday recovers only from exactly k shares without the secret, and derives a share only from exactly k strings at an unused index; the reference also takes more strings or a used index.
The codex32 seed sizes, which the references leave to their caller, are written in the area from the BIP's own sentence. Volvelle's sheet works the checksum itself, so a string of 48 or 74 characters whose checksum is not the one the sheet works is judged by that alone (holds false), not by its rows.
When it runs Before every release, with a new seed and about ten times the cases.
Last passing runSeed 5be11ec606a76d2767f225b8992c45fe · 10000 cases
Faraday's code: faraday/faraday-keys: Answers only its own reason; the key is derived at the path and written in a fixed buffer. On Explore each eye makes what it shows once, at the press that opens it: the seed's forms, the root's and the account's extended private keys together, or an address's private key. The account is the path's account, or the path itself where it is in none. What is not on screen is dropped after every press and key on Explore, and by closing an eye, leaving Explore, the idle warning and a lock.
no fuzz target: Takes a held key, a path and a reason; no outside input is parsed
Cross-check
Compared with others' code: btclib-wallet's bip32, by the btclib developers, on btclib's own curve; and hdkeychain from btcd v0.27.0, by the btcd developers, on decred's secp256k1.
Compared with btclib-wallet's bip32 over btclib and ecc (btclib/), on btclib's own curve with libsecp256k1 turned off, through bip32_ref.py, and hdkeychain from btcd v0.27.0 (btcd/, Go, decred's secp256k1); the versions a strict reader takes (BIP-32's four, from btclib's network table), a version whose kind differs from the key's data, and a depth-0 key with a parent or an index are ours.
Checked first: The wheels and the vendored Go tree are hashed against references.sha256 before any run; check_driver runs btclib against BIP-32's vectors 1 to 5 and the invalid keys of vector 5 before anything else, and every vector is asked of hdkeychain too.
Vectors BIP-32's vectors 1 to 5 (tools/vectors/bip32/), python-mnemonic's master keys.
Random cases Seeds of 16 to 64 bytes on every network, random paths with every index, public derivation against private, keys broken one rule at a time and the master-key import, each judged by btclib and by hdkeychain.
Differences Hdkeychain reads a key of any version, a key whose version is a private one over a public key's data (or the reverse), and a depth-0 key with a parent fingerprint or an index. Faraday refuses all three, as btclib refuses the last; where one applies and btclib refuses, hdkeychain is not asked (uncovered in area_bip32.py), so Faraday's strict reader is not retired.
When it runs Before every release, with a new seed and about ten times the cases.
Last passing runSeed 5be11ec606a76d2767f225b8992c45fe · 4000 cases
Library: bitcoin 0.32.102, by the rust-bitcoin developers, through core/faraday-bip.
Faraday's code: faraday/faraday-keys: Answers only its own reason; the WIF is compressed and carries the store's network. On Explore's address list an address's key is asked at the account's path, its chain and its index.
Compared with btclib-wallet's bip32 over btclib and ecc (btclib/), on btclib's own curve with libsecp256k1 turned off, through bip32_ref.py, and hdkeychain from btcd v0.27.0 (btcd/, Go, decred's secp256k1); the versions a strict reader takes (BIP-32's four, from btclib's network table), a version whose kind differs from the key's data, and a depth-0 key with a parent or an index are ours.
Checked first: The wheels and the vendored Go tree are hashed against references.sha256 before any run; check_driver runs btclib against BIP-32's vectors 1 to 5 and the invalid keys of vector 5 before anything else, and every vector is asked of hdkeychain too.
Vectors BIP-32's vectors 1 to 5 (tools/vectors/bip32/), python-mnemonic's master keys.
Random cases Seeds of 16 to 64 bytes on every network, random paths with every index, public derivation against private, keys broken one rule at a time and the master-key import, each judged by btclib and by hdkeychain.
Differences Hdkeychain reads a key of any version, a key whose version is a private one over a public key's data (or the reverse), and a depth-0 key with a parent fingerprint or an index. Faraday refuses all three, as btclib refuses the last; where one applies and btclib refuses, hdkeychain is not asked (uncovered in area_bip32.py), so Faraday's strict reader is not retired.
When it runs Before every release, with a new seed and about ten times the cases.
Last passing runSeed 5be11ec606a76d2767f225b8992c45fe · 4000 cases
Writes a key's master seed as hex, its master extended private key, a SLIP-39 1 of 1, a SLIP-39 set of k of n or of groups, or a codex32 set, a key's words as Seed XOR parts, and a key's words as words, SeedQR, CompactSeedQR, hex entropy, word numbers or 4-letter starts, each read back through its standard's decoder to the key's wallet.
SeedQR, SeedQR and CompactSeedQR, Convention, vendored
Seed XOR, Seed XOR, Coldcard's split of a seed into parts, Convention, vendored
Code
Library: base16ct 1.0.0, by the RustCrypto developers, through core/faraday-crypto.
Faraday's code: faraday/faraday-keys: Each conversion is given only for Reveal::PaperForm, and only when its result, read back through the standard's own decoder (hex, the strict xprv importer, SLIP-39's share, every share of a set parsed before any recovery and then a first and a last qualifying subset each recovered, codex32's parse of every share and recover from the first k and the last k), gives the key's master fingerprint; otherwise nothing is returned. A key's words written in another form are read back to the same entropy on the same list, so the same words and the same fingerprint, with no PBKDF2 run; SeedQR forms take English 12 or 24 words, and 4-letter starts English. A key with words is refused for SLIP-39 and codex32; SLIP-39 holds 16 and 32 bytes only; Seed XOR is given for a key on the English list only, the list its parts are restored on. A codex32 set of k above 0 takes its identifier from the randomness passed in, never the one of the key's fingerprint nor of its own set, so two sets of one key are not one set; the secret alone keeps the fingerprint's. A SLIP-39 set is made with an empty passphrase, the extendable flag set and iteration exponent 1, its identifier and shares from the randomness passed in, and a shape the split refuses is refused.
Checked against
tools/vectors/bip39
Published, by Trezor (SatoshiLabs), python-mnemonic's vectors; bip32JP's Japanese vectors.
tools/vectors/bip32
Published, by BIP 32's authors (bitcoin/bips).
tools/vectors/slip39
Published, by Trezor (SatoshiLabs), python-shamir-mnemonic.
no fuzz target: Takes a held key and a reason; no outside input is parsed
Cross-check
not cross-checked: The core functions are judged in their own areas; these wrappers add the gate and the read-back, and are tested here against the published vectors, with no cross-check run of their own
SpecificationSLIP-0039PublishedCodeLibrary: subtle 2.6Faraday's code: faraday/faraday-keysCross-checked withpython-shamir-mnemonicOthers' codeFaraday's second version
Action
Holds the SLIP-39 shares a person types, and from them writes a share at a member index (adding a share or replacing a lost one) or a new set of the same encrypted master secret, each read back before it is returned.
Specification
SLIP-0039, Shamir's Secret-Sharing for Mnemonic Codes, Status not checked, vendored
Code
Library: subtle 2.6.1, by the dalek-cryptography developers.
Faraday's code: faraday/faraday-keys: The typed shares are held as a transient value, never a key, and each is checked against the others as it is typed (one set; no member typed twice; no more members than the group's threshold). A share at a member index is derived from one group's quorum and read back by swapping it in for one of the quorum, which must give back, word for word, the share displaced; where the whole set is typed the swapped set must also recover the same EMS and parameters. A new set is split from the EMS recovered from the whole set's quorum: with the extendable flag set it takes a new identifier and the old one is refused, with it clear the identifier stays; every share is parsed and every member of every group takes part in a qualifying subset that must recover the same EMS and parameters. No passphrase is taken and nothing is decrypted.
Checked against
tools/vectors/slip39
Published, by Trezor (SatoshiLabs), python-shamir-mnemonic.
Compared with others' code: python-shamir-mnemonic, by Trezor (SatoshiLabs), and bip39_slip39, by the btclib developers, for the core functions these wrappers call (shares read, recover_ems, split_ems, derive_member), judged in the slip39 area.
Compared, for one part, with Faraday's second version, written by Faraday's authors in Python; that part is not checked against an outside source: slip39::check_gathered, Faraday's own rule on the shares typed (one set, no member twice, no more members than the threshold), which no judge in tools/crosscheck runs, and the held set and the read-back, which are tested here against the published vectors.
Area slip39
Faraday's code faraday_bip::slip39
Compared with python-shamir-mnemonic (slip39/), its recover_ems, split_ems and _interpolate for a set's EMS, a new split of it and a member at an index; bip39_slip39 (bip39-slip39/) answering each SLIP-39 operation beside it (not the two codex32 operations); python-codex32 (codex32/) for the codex32 side of the conversions and btclib (bip32_ref.py) for the fingerprint; the refusals of a member at an index before the arithmetic are ours (derive_refused), and so are the lengths the fixed 1 of 1 refuses, which no second judge covers.
Checked first: Its vendored files are hashed against references.sha256 before any run, and a published vector's answer is required of the reference as well as of Faraday, and of bip39_slip39 too; all 45 of its own vectors are run.
Vectors All 45 of tools/vectors/slip39/, each again through its EMS and its decryption.
Random cases Splits fed the same random bytes, which must match word for word; recovery from qualifying and short subsets and a changed word; the passphrase cipher; a set's EMS from a quorum, refused from a short or changed set, split again on the same random bytes (some under a new identifier where extendable) and a member added or a lost one made again at an index, each recovering the first set's secret, and a member refused at an index given, past 15, from a short quorum and across two groups; random seeds of 16 and 32 bytes through the fixed 1 of 1 against both libraries under the fingerprint's first 15 bits, recovered through both, and the lengths it refuses, against Faraday's own rule; the seed written as codex32 by Faraday and read by python-codex32, and a SLIP-39 set with a passphrase recovered by Faraday and by python-shamir-mnemonic, written as codex32 by Faraday and by python-codex32, the second read by Faraday, the same bytes both ways, the identifier's 20 bits written and the fingerprint (btclib's) compared on both sides.
Differences SLIP-39: Faraday refuses a group threshold of 1 over several groups; python-shamir-mnemonic makes the shares. The area checks that this still holds, so a change either way is seen.
When it runs Before every release, with a new seed and about ten times the cases.
Last passing runSeed 5be11ec606a76d2767f225b8992c45fe · 21000 cases
Each share held is wiped as it drops, and each result is a Held value in a zeroizing buffer.
Limits
Another reason gets nothing.
Nothing is held in Practice or while a stick is attached, and no share or set is made while one is; the held set stays.
The fuzz target `seed_parts` reaches the core SLIP-39 functions these call, not the held set or these wrappers.
A result that does not read back as the same EMS and parameters is not returned.
Faraday's own calls
A SLIP-39 set's actions are in Convert a seed, not with the backup, since no plan or vault tracks a SLIP-39 set; nothing is remembered, and a share is refused where one more member than its group's threshold would be held. Conservative, F204.
Reads a single private key written as WIF, typed or scanned for a sweep, and works out the addresses it pays.
Specification
Own specification (F171)
Code
Library: secp256k1 0.29.1, by the rust-bitcoin developers (rust-secp256k1), over libsecp256k1, by Bitcoin Core's libsecp256k1 project (bitcoin-core/secp256k1).
Library: bitcoin 0.32.102, by the rust-bitcoin developers.
Library: hmac 0.13.0, by the RustCrypto developers, through core/faraday-crypto.
Library: sha2 0.11.0, by the RustCrypto developers, through core/faraday-crypto.
Faraday's code: core/faraday-bip: Reads base58check with the bitcoin crate and holds Bitcoin Core's DecodeSecret rules itself: a version of 0x80 or 0xef, 32 bytes of key then nothing or exactly 0x01, a scalar in 1..n; the key is held on a pinned page in a signing context blinded from the key and, in faraday-keys, again from the session's randomness. A key of the other network kind, or read while a stick is attached, is refused; the key pays P2PKH, and if compressed P2WPKH and P2SH-P2WPKH.
Checked against
tools/vectors/wif
Published, by Bitcoin Core's key_io_valid.json and key_io_invalid.json, by the Bitcoin Core developers.
Compared with others' code: Bitcoin Core v31.1, by the Bitcoin Core developers, which signs from descriptors of the same WIF what Faraday reads from it and shares libsecp256k1's curve maths with Faraday's; btclib, by the btclib developers, which decodes the WIF and works out its public key on its own curve.
Area sign
Faraday's code faraday_psbt::sign (every held key selected, deterministic Schnorr, both RFC 6979 nonce rules) and faraday_psbt::finalize
Compared with Bitcoin Core v31.1 on regtest (core_node.py): descriptorprocesspsbt signs from the held masters' keys, finalizepsbt finalizes and extracts, testmempoolaccept judges each finalized transaction over its funding on the node; BIP-340's reference (secp256k1lab) and Core's key.py for the deterministic nonces, over Core's script.py sighashes; python-ecdsa (the distribution's package) and btclib (btclib/, its own curve) as a second curve lineage, beside them: every ECDSA signature again under plain RFC 6979 or verified, every BIP-340 signature verified and made again; btclib-wallet's finalizer (psbt.finalize with its miniscript solver) finalizes every input Faraday finalizes again and gives the same scriptSig and witness; for each sweep, btclib reads the WIF (scalar, compression, public key) and signs and finalizes the sweep on its own curve, and python-ecdsa makes the first-nonce signature of each input again, byte for byte; python-bip380 (miniscript/) reads the leaves. Faraday's refusals and the inputs a wallet's rule leaves unsigned are ours, in area_sign.py.
Checked first: Core is the pinned release, hashed against its pin before every run; the vendored files are hashed against references.sha256; a published vector's answer is required of Core as well as of Faraday; every ECDSA and BIP-340 signature Core makes is checked to verify under the hash the area computes before that hash is used for Faraday's deterministic nonces.
Vectors BIP-174's signer, finalizer and extractor vectors; the Core-built spends of tools/vectors/psbt/ (2-of-3 sortedmulti, the Liana wallet down both paths, a taproot tree by a leaf and by the key path, BIP 387's taproot multisig), signed by every subset of their keys; the finalizer vectors there (or_b's smaller signature, the taproot leaves that tie by count, the taproot multisig and MuSig2 spends).
Random cases PSBTs of one to four inputs, each spending a funding output on the node: P2PKH, P2SH-P2WPKH, P2WPKH, multi/sortedmulti in P2SH, P2WSH and P2SH-P2WSH, P2TR key path, P2TR script path (pk, pkh, timelocked keys, or_d, multi_a) with the key path beside it, miniscript in P2WSH and P2SH-P2WSH; held and foreign keys, cosigners' signatures already on (Core's), every standard sighash type, timelocks met and not; Core's signatures (ECDSA byte for byte, BIP-340 by verification and the deterministic nonce), each final scriptSig and witness and the extracted transaction Core's, the cleared fields, and every finalized transaction accepted by Core's mempool; an origin that derives another key refused; sweeps: a WIF key's P2PKH, P2WPKH and P2SH-P2WPKH outputs (P2PKH alone for an uncompressed key) spent beside another key's, signed by Core from the WIF and by faraday_psbt::sweep::sign, byte for byte, finalized and accepted by the mempool.
Differences PSBT signing: Faraday refuses to sign a SegWit v0 input with no previous transaction in a transaction of more than one input; Core signs it, and BIP-174's own signer vector is such a PSBT. The refusal is ours, checked and counted. Faraday holds a finalized input to the same rule and refuses the PSBT when such an input is final, except a taproot one, whose final witness is the coordinator's.
PSBT signing, wallets: Faraday signs an input spent from a script of several keys (a multi of two or more, a miniscript naming two or more, a taproot script path whose carried leaves name two or more with its internal key, or are not its whole tree) only for a registered wallet that holds one of its keys and whose script it is; Core signs any. The area refuses, by a rule of its own, where no wallet the request registers holds a held key and gives the input, and counts it only where Faraday's refusal is that the wallet is not registered. A miniscript or a taproot tree of one key is signed only through such a wallet, and is otherwise left unsigned while the rest is signed (F141); the area takes Core's signatures off it. Half the corpus's multi, miniscript and taproot-tree inputs come with their wallet registered, so their signatures are still compared. A registered tree's every leaf has its wait met, since Faraday refuses a path that can never be valid, which the area does not work out.
PSBT signing: Faraday refuses a PSBT any input of which asks for a NONE or SINGLE sighash, and one that none of the held keys can sign: dangers no hold accepts (F136). Core signs the first and answers the second with nothing signed. The area expects both refusals by a rule of its own, counting a held key as taking part as Faraday's inspection does (a miniscript or a taproot tree only through a wallet in use), checks that Faraday's refusal names the danger, and counts them.
Taproot pkh leaves: Faraday signs a taproot leaf that checks its key by hash but does not finalize it: miniscript 12's finalizer looks the key up among the ECDSA origins and panics, and would push 33 bytes where the leaf hashed 32. Core finalizes such a leaf; the area takes the signatures under it off before Core finalizes, and counts each input Core would otherwise have finalized another way.
btclib's finalizer writes no taproot leaf that is neither a single key nor multi_a, and refuses to choose among leaves a PSBT signs: an input of another leaf is judged by Core alone (counted as a known difference), and btclib is given only the signatures of the leaf Faraday spent. It writes a plain multisig from the smallest m signatures on hand where Core and Faraday write the first m signers': btclib is given only the signatures Faraday's input carries, so it judges the script written from them and Core judges which were chosen.
When it runs Before every release, with a new seed and about ten times the cases.
Last passing runSeed 5be11ec606a76d2767f225b8992c45fe · 1580 cases
libsecp256k1 documents its key multiplication as constant time; the base58 decode is not stated to be.
The decoded buffer is zeroized before the reader returns, but base58ck's own scratch and result vectors are freed unwiped, until the next lock (ESTABLISHED §4.8); the key is held on a pinned page and erased when it is dropped, at Done, a lock or leaving the Sweep sheet.
Limits
A key is swept and never kept: no vault record, no key slot, no backup.
A WIF of the other network kind is refused.
Faraday's own calls
A WIF key is never loaded as a key or kept: it lives for one sweep. Conservative, F171.
Lends a key's words or passphrase as text for a named reason, and shows them on screen or for copying by hand.
Specification
Own specification (F70)
Code
Faraday's code: faraday/faraday-keys: A key's words and passphrase leave as text only through a Reveal reason from a closed list; the text is lent while a guard lives and the guard cannot be cloned or printed.
Tells whether two keys, or a key and a copy of its words, have the same words, by a SHA-256 of their entropy, and orders the copy check's questions.
Specification
BIP 39, Mnemonic code for generating deterministic keys, Deployed
Code
Library: sha2 0.11.0, by the RustCrypto developers, through core/faraday-crypto.
Library: unicode-normalization 0.1.25, by the unicode-rs developers, through core/faraday-bip.
Faraday's code: faraday/faraday-keys: The id is all 32 bytes of the SHA-256 of the words' entropy, worked out the first time it is asked and kept beside the key, so two seeds never pass for one; the same words with and without a passphrase share it. What is kept of a secret's fingerprint is keyed by SHA-256 of a tag and the secret, so the secret itself is kept nowhere. The copy check's questions are ordered by a small shuffle (xorshift64*) seeded from 8 bytes of the session's generator, which the words do not enter.
Derives a BIP 48 cosigner account and its extended public key, and lends the account key to sign a BSMS key record.
Specification
BIP 48, Multi-Script Hierarchy for Multi-Sig Wallets, Deployed
BIP 67, Deterministic Pay-to-script-hash multi-signature addresses through public key sorting, Complete
Code
Library: bitcoin 0.32.102, by the rust-bitcoin developers.
Faraday's code: core/faraday-bip: The account path is m/48'/coin'/account'/script' with script 1' or 2'; the account node's private key is lent to one closure and erased when it returns.
Compared with btclib-wallet's bip32 over btclib and ecc (btclib/), on btclib's own curve with libsecp256k1 turned off, through bip32_ref.py, and hdkeychain from btcd v0.27.0 (btcd/, Go, decred's secp256k1); the versions a strict reader takes (BIP-32's four, from btclib's network table), a version whose kind differs from the key's data, and a depth-0 key with a parent or an index are ours.
Checked first: The wheels and the vendored Go tree are hashed against references.sha256 before any run; check_driver runs btclib against BIP-32's vectors 1 to 5 and the invalid keys of vector 5 before anything else, and every vector is asked of hdkeychain too.
Vectors BIP-32's vectors 1 to 5 (tools/vectors/bip32/), python-mnemonic's master keys.
Random cases Seeds of 16 to 64 bytes on every network, random paths with every index, public derivation against private, keys broken one rule at a time and the master-key import, each judged by btclib and by hdkeychain.
Differences Hdkeychain reads a key of any version, a key whose version is a private one over a public key's data (or the reverse), and a depth-0 key with a parent fingerprint or an index. Faraday refuses all three, as btclib refuses the last; where one applies and btclib refuses, hdkeychain is not asked (uncovered in area_bip32.py), so Faraday's strict reader is not retired.
When it runs Before every release, with a new seed and about ten times the cases.
Last passing runSeed 5be11ec606a76d2767f225b8992c45fe · 4000 cases
Derives the script and the address of a wallet at a chain and an index, and looks for an address among a wallet's first addresses.
Specification
BIP 44, Multi-Account Hierarchy for Deterministic Wallets, Deployed
BIP 49, Derivation scheme for P2WPKH-nested-in-P2SH based accounts, Deployed
BIP 84, Derivation scheme for P2WPKH based accounts, Deployed
BIP 86, Key Derivation for Single Key P2TR Outputs, Deployed
BIP 341, Taproot: SegWit version 1 spending rules, Deployed
BIP 173, Base32 address format for native v0-16 witness outputs, Deployed
BIP 350, Bech32m Format for v1+ Witness Addresses, Deployed
Code
Library: bitcoin 0.32.102, by the rust-bitcoin developers.
Library: secp256k1 0.29.1, by the rust-bitcoin developers (rust-secp256k1), over libsecp256k1, by Bitcoin Core's libsecp256k1 project (bitcoin-core/secp256k1).
Library: miniscript 12.3.7, by the rust-bitcoin developers (rust-miniscript).
Faraday's code: core/faraday-bip: The script is derived from the keys of the policy on a verification-only context; an index of 2^31 or more is refused; the search takes the receive and change address at each index in turn, nearest first. Explore's address list and search derive from the account's extended public key as a single-key wallet and keep up to 10,000 addresses of each chain from index 0; a search looks 100, 1,000 or 10,000 indices deep, and a wallet keeps the scripts it has derived, a lookup after the first.
Checked against
tools/vectors/addresses
Published, by the authors of BIP 173, BIP 350, BIP 380, BIP 49, BIP 84 and BIP 86 (bitcoin/bips).
Compared with others' code: Bitcoin Core v31.1 itself (deriveaddresses) and its functional-test framework, by Bitcoin Core's contributors; btclib-wallet's bip32 and slip132, by the btclib developers, on btclib's own curve, for the account keys, and its descriptors (parse, script_pub_key, checksum) for each account descriptor's kind, text, script at an index and checksum; BIP 380's own checksum code, as the BIP prints it; python-mnemonic, by Trezor (SatoshiLabs), for the seeds.
Area addr
Faraday's code faraday_bip::address::parse, bitcoin's Address::from_script, faraday_bip::account (account xpub, SLIP-132, descriptor, addresses), faraday_bip::descriptor's checksum, faraday_bip::policy::WalletPolicy::from_descriptor (an account descriptor's kind, text and script at an index)
Compared with Bitcoin Core's functional-test framework (core/): segwit_addr.py, Base58Check, descriptors.py; BIP 380's own checksum code as the BIP prints it (bip380/); btclib-wallet's bip32 and slip132 (btclib/, on btclib's own curve) for accounts' keys, and its descriptors (descriptors) for each account descriptor's kind, text, script at an index and checksum, and as a third checksum judge; Bitcoin Core v31.1's bitcoind on regtest for every account's address (deriveaddresses) and for reading Faraday's regtest descriptors (getdescriptorinfo).
Checked first: Its vendored files are hashed against references.sha256 before any run, and a published vector's answer is required of the reference as well as of Faraday; every descriptor checksum is also asked of BIP 380's own code, as the BIP prints it, and of btclib's; Core's release tarball is checked against its pinned SHA-256 (tools/reference/core/release.pin) before every run, and the node's version is asked.
Vectors BIP-350's and BIP-173's addresses, BIP-380's checksum cases, BIP-49's, 84's and 86's accounts (tools/vectors/addresses/).
Random cases Scripts of every address kind on every network, written and read back, then changed; accounts of every type at random indices, their descriptors read and changed; random descriptors' checksums.
Differences A descriptor with a second # in its body: Faraday and btclib refuse it, as Bitcoin Core's parser does, where BIP 380's code and Core's framework check the last nine characters; its checksum is asked of btclib only. btclib reads descriptors Faraday takes for no account (pk, combo, multi, addr, raw) and other chains than <0;1>; the area asks it for the four account descriptors with both chains only.
When it runs Before every release, with a new seed and about ten times the cases.
Last passing runSeed 5be11ec606a76d2767f225b8992c45fe · 40000 cases
Library: bitcoin 0.32.102, by the rust-bitcoin developers.
Library: miniscript 12.3.7, by the rust-bitcoin developers (rust-miniscript).
Library: base16ct 1.0.0, by the RustCrypto developers, through core/faraday-crypto.
Faraday's code: core/faraday-bip: A wallet policy (BIP 388) and a descriptor are one wallet, written with h for hardened and the multipath /<0;1>/* form; a descriptor with a checksum that does not match is refused; the checksum is BIP 380's, worked out by miniscript; a tr() wallet states who can spend by the key path.
Checked against
tools/vectors/addresses
Published, by the authors of BIP 173, BIP 350, BIP 380, BIP 49, BIP 84 and BIP 86 (bitcoin/bips).
tools/vectors/bip387
Published, by BIP 387's authors (bitcoin/bips).
tools/vectors/miniscript
Published, by Bitcoin Core's miniscript_tests.cpp, v31.1, by the Bitcoin Core developers.
Compared with others' code: Bitcoin Core v31.1 itself (deriveaddresses) and its functional-test framework, by Bitcoin Core's contributors; python-bip380, by Antoine Poinsot, for Core's vectors that state no script; btclib-wallet's bip32, by the btclib developers, for the cosigners' keys, and its descriptors and miniscript, by the btclib developers, on btclib's own curve, for each descriptor's kind, text and script at an index, Core's vectors' types, sanity and scripts, and the satisfaction of each way a wallet's coins move under its lock times.
Area miniscript
Faraday's code faraday_bip::policy::WalletPolicy (a wallet's descriptor and the script it pays at an index, its kind, text and spend paths), faraday_bip::policy::parse_script_descriptor, a witness script read back as faraday_psbt reads one, faraday_bip::recovery::RecoveryPolicy (a recovery wallet built from its parts and read back)
Compared with Bitcoin Core v31.1's bitcoind on regtest (deriveaddresses) for random wallets, their cosigners' keys from btclib (btclib/, on btclib's own curve); btclib-wallet's descriptors and miniscript (btclib/) for each descriptor's kind, text and script, Core's vectors' types and scripts, and the satisfaction of each way a wallet's coins move under its lock times; Antoine Poinsot's python-bip380 (miniscript/) for Core's vectors that state no script.
Checked first: Its vendored files are hashed against references.sha256 before any run, and a published vector's answer is required of the reference as well as of Faraday; btclib reads Core's 97 miniscripts, in both contexts, before any random wallet (valid exactly when Core says, its properties, sane, script); Core's release tarball is checked against its pinned SHA-256 (tools/reference/core/release.pin) before every run, and the node's version is asked.
The witness bytes of a satisfaction (btclib assembles one and area sign compares Faraday's finalizer); a wallet with more than 64 ways to spend, for which Faraday states none; hash locks and locks in seconds, which the corpus does not generate; and a wallet btclib cannot read (none yet).
Vectors Bitcoin Core's miniscript unit tests, 97 miniscripts in P2WSH and Tapscript (tools/vectors/miniscript/).
Random cases Wallets of the Liana, Nunchuk, Sparrow and recovery shapes in wsh() and sh(wsh()), multi/sortedmulti in sh(), wsh(), sh(wsh()), tr() with trees of one to six leaves or a lone sortedmulti_a, over random accounts on every network, at random indices of both chains; the same made not sane, refused; recovery wallets of both forms with one to three recovery paths, and the ways each wallet's coins move spent at their lock times.
Differences Miniscript: Faraday reads sortedmulti_a only as a tr()'s one leaf; BIP 387 allows it deeper in a tree, and Core reads it there. Two of Bitcoin Core's sane miniscripts are refused, as miniscript refuses them: or_b(0,a:0), which has no satisfaction, and a d: used as a unit under Tapscript. Each is checked and counted; btclib is not asked the deeper sortedmulti_a. btclib says nothing of "needs a signature" for a malleable miniscript (BIP 379 does not), so that property is compared where Core calls the miniscript non-malleable.
When it runs Before every release, with a new seed and about ten times the cases.
Last passing runSeed 5be11ec606a76d2767f225b8992c45fe · 2500 cases
BIP 341, Taproot: SegWit version 1 spending rules, Deployed
BIP 342, Validation of Taproot Scripts, Deployed
Code
Library: bitcoin 0.32.102, by the rust-bitcoin developers.
Library: miniscript 12.3.7, by the rust-bitcoin developers (rust-miniscript).
Faraday's code: core/faraday-bip: sortedmulti_a is read here because miniscript has no such fragment: the descriptor is read as its multi_a twin and the script rebuilt at every index with the x-only keys sorted.
Compared with others' code: btclib's check_output_pubkey, by the btclib developers, on btclib's own curve; ParseControlBlock and VerifyTaprootLeafCommitment of btcd v0.27.0, by the btcd developers; and Bitcoin Core's functional-test framework, v31.1, by Bitcoin Core's contributors, for the trees.
Compared, for one part, with Faraday's second version, written by Faraday's authors in Python; that part is not checked against an outside source: the rule that a leaf version is not 0x50, which neither btclib nor btcd makes, written in area_taproot.py.
Area taproot
Faraday's code bitcoin's TaprootBuilder and TaprootSpendInfo (as faraday_bip::tapmulti and miniscript's tr() build trees), ScriptBuf::new_p2tr as faraday_psbt::sign checks a key path, Address::p2tr_tweaked, ControlBlock decoding and verify_taproot_commitment
Compared with Core's taproot_construct, key.py's tweak and segwit_addr.py for the trees; btclib's check_output_pubkey (btclib/, on its own curve) and btcd v0.27.0's txscript.ParseControlBlock and VerifyTaprootLeafCommitment (btcd/, Go) for the control blocks; the rule that a leaf version is not 0x50 is ours.
Checked first: Its vendored files, the btclib wheels and the vendored Go tree are hashed against references.sha256 before any run, and a published vector's answer is required of the reference as well as of Faraday; each of BIP-341's wallet vectors is checked against the reference first.
Vectors BIP-341's scriptPubKey wallet vectors, all seven (tools/vectors/sighash/).
Random cases Trees of 0 to 12 leaves in random shapes with random scripts and leaf versions over random internal keys: leaf hashes, Merkle root, tweak, output key and parity, script, address, control blocks; each control block checked, then changed eleven ways, each judged by btclib and by btcd; internal keys that are no point, odd leaf versions and 0x50 refused.
Differences Btclib and btcd hash a leaf of version 0x50 like any other, where BIP-341's text and Faraday refuse it (the annex tag): a control block of that version is judged by the area alone, and neither is asked.
When it runs Before every release, with a new seed and about ten times the cases.
Last passing runSeed 5be11ec606a76d2767f225b8992c45fe · 4400 cases
SpecificationBIP 388 · RFC 8259PublishedCodeLibrary: bitcoin 0.32Library: serde_json 1.0Library: base16ct 1.0 (through core/faraday-crypto)Faraday's code: core/faraday-bipFaraday's own codeCross-checked withBitcoin Core v31.1 (deriveaddressesOthers' codeFaraday's second version
Action
Reads another wallet's export (Coldcard JSON and multisig configuration files, Specter DIY's addwallet command) as a wallet and checks the first address it states; writes a native SegWit single-key wallet as Coldcard's file for Wasabi, and any wallet but a MuSig2 or silent payments one as Specter DIY's addwallet command.
Specification
BIP 388, Wallet Policies for Descriptor Wallets, Complete
RFC 8259, The JavaScript Object Notation (JSON) Data Interchange Format, Status not checked
Code
Library: bitcoin 0.32.102, by the rust-bitcoin developers.
Library: serde_json 1.0.151, by David Tolnay.
Library: base16ct 1.0.0, by the RustCrypto developers, through core/faraday-crypto.
Faraday's code: core/faraday-bip: JSON is read by serde_json, behind Faraday's refusal of a key named twice and of a nesting deeper than 32 (and of a text over 1 MiB); a Coldcard export's stated first address is derived and compared; a multisig file with more than fifteen cosigners is refused at the sixteenth. An account key alone becomes a wallet of the kind its path's purpose names (44 legacy, 49 nested SegWit, 84 native SegWit, 86 taproot), and a purpose of 45, 48 or 87 is a cosigner's key and no wallet on its own; a key of a test network is taken as testnet unless the session is already on a test network; the file for Wasabi is written only for a native SegWit single-key wallet whose key has an origin at exactly 84h/0h/0h or 84h/1h/0h. Specter DIY's addwallet command is read with its name before the last `&`, its descriptor's checksum checked where it has one (Specter DIY drops it unread), and keys none of which carries a derivation as the two chains; a single-key or multisig wallet is written without its keys' derivations and with no checksum, as Sparrow writes it, any other with them.
Written by Faraday
The JSON visitor that refuses a key named twice and counts depth (faraday-bip::json) · Only the part used is written
serde_json reads the text; Faraday refuses a key named twice and a nesting deeper than 32.
Published, by the wallets' own test suites: Coldcard's firmware, Caravan, Liana, Sparrow and BlueWallet (the commit, licence and SHA-256 of each file are in the folder's README and the interop vectors' README).
Compared with others' code: Bitcoin Core v31.1 (deriveaddresses, and BIP-380's checksum in its descriptors.py), by the Bitcoin Core developers, for every wallet's addresses and checksums; btclib-wallet's BIP-32 and btclib's SLIP-132 versions, by the btclib developers, for the keys; and 93 real files from the wallets' own test suites (Sparrow, BlueWallet, Coldcard, Caravan, Liana), read in the same area.
Compared, for one part, with Faraday's second version, written by Faraday's authors in Python; that part is not checked against an outside source: the files the area writes and what each format's fields mean, and the formats no test suite publishes a file for (Nunchuk's, Specter DIY's and Keystone's beyond Sparrow's copies) (Coldcard's export and multisig file, Caravan's, Electrum's, Cobo's, Keystone's, Wasabi's, Specter Desktop's, Specter DIY's addwallet, Core's listdescriptors), written in area_import.py from each format's documentation, which account of a Coldcard export and which pair of a listdescriptors is the wallet, and F155's SLIP-132 refusals.
Area import
Faraday's code faraday_intake::wallet::read_wallet (the wallet a file or text is: descriptors, faraday_bip::coldcard, faraday_bip::multisig_config, Caravan's, Electrum's, Cobo's, Keystone's and Wasabi's files, Specter DIY's addwallet, faraday_bip::bsms::DescriptorRecord), and faraday_bip::bsms::SignerRecord read and verified and faraday_bip::bsms::signer_record over the BIP-48 or BIP-87 account node's key
Compared with Bitcoin Core v31.1's bitcoind on regtest, offline (deriveaddresses), and its descriptors.py (BIP-380's checksum) and address.py, for each wallet's receive and change scripts and every checksum; btclib-wallet 2026.10.29's BIP-32 (btclib's own curve) for every key, btclib 2026.10.24's SLIP-132 versions and addresses, and its bms for every key record's signature, made, verified and written byte for byte; CPython's json for the value of every JSON file read and for a key named twice and a nesting past 32 refused (those two rules are the reader's own, written beside it); the files are written in the area from each format's documentation, and the meaning of their fields is the area's.
Checked first: Core's release tarball against its pinned SHA-256 before every run; btclib's wheels against the hashes btclib-wallet's lock file names (references.sha256), with libsecp256k1 off; BIP 129's own records and the real files of Sparrow, BlueWallet (Nunchuk's, Coldcard's and Unchained's among them), Coldcard, Caravan and Liana, judged in the prelude.
The wallet's name a file carries; Electrum's encrypted files and BSMS's encrypted records, which Faraday refuses by name; a silent payments record; the kind of a refusal.
Vectors BIP 129's key and descriptor records (tools/vectors/bip129/), and 93 real files from the wallets' own test suites, 62 of them a wallet and 31 refused by both sides (faraday/faraday-core/tests/vectors/interop/: Sparrow's and BlueWallet's; tools/vectors/wallet-files/: Coldcard's firmware tests, Caravan's and Liana's): BSMS records, Coldcard setup files and exports, Caravan, Electrum, Cobo, Keystone, Jade, Specter Desktop and Specter DIY files, descriptors and a Core listdescriptors.
Random cases single-key wallets (P2PKH, P2SH-P2WPKH, P2WPKH, P2TR), sortedmulti in P2WSH, P2SH-P2WSH and P2SH of one to fifteen keys, a miniscript in P2WSH, a taproot tree and a taproot sortedmulti_a, on mainnet and testnet keys, each as a descriptor (multipath with and without checksum, receive and change lines, labelled, receive alone, Core's listdescriptors, Specter Desktop's file, Specter DIY's addwallet with and without its keys' derivations) or as the files that state its kind (Coldcard's export and multisig file, Caravan's, Electrum's, Cobo's, Wasabi's, a key alone, a BSMS descriptor record), in BIP-32's or SLIP-132's spelling; damaged by a wrong checksum, a wrong first address, a SLIP-132 version of another script or another paths line; key records signed by btclib in each header form, with or without damage, and Faraday's own record of random seeds.
Differences Still ours, expected from Faraday's rule: a SLIP-132 version that names another script than the file's (F155), a BSMS paths line other than /0/*,/1/* or No path restrictions, which Faraday reads as the two chains (F64), a BSMS descriptor that is not a template, a key record whose description is over eighty characters or whose token is not BIP 129's; and which account of a Coldcard export, which pair of a listdescriptors, and what each field of every format means, the area's reading of each format's documentation; a checksum in Specter DIY's addwallet, which Specter DIY drops unread and Faraday checks, is refused when Core's code calls it wrong; and the reading of each format's documentation.
Real files both sides refuse, each by a named rule: a Caravan file or an Electrum multisig file whose keys lack a path or a fingerprint, a Caravan quorum that is not the keys listed, a multisig setup file with no policy, a key missing or no format line (Coldcard's own P2SH setup files omit Format, which Faraday refuses), a BSMS record with a paths line other than /0/*,/1/*, a derivation other than /** or <0;1>, a missing line, a first address that is not Core's or not an address, a Coldcard cosigner key file, an Unchained key file and a Coldcard stored setting (a key, not a wallet), and a UR text (area ur). Left out and named: a silent payments record (area sp) and a PSBT or transaction file (areas psbt, tx).
Formats with no published file in a test suite: Nunchuk's own files (only BlueWallet's copies of them), Specter DIY's beyond the one Sparrow keeps, Keystone's beyond Sparrow's, and Core's listdescriptors beyond the one in the interop vectors, whose source is not recorded; Electrum's published test wallets carry a seed and are not taken. Those formats stay the area's own reading (Faraday's second version), as above.
A key record's signature in any of BIP-137's header forms is accepted when it recovers the record's key: btclib is asked with the address that form names (Faraday reads no address from the record).
When it runs Before every release, with a new seed and about ten times the cases.
Last passing runSeed 5be11ec606a76d2767f225b8992c45fe · 4500 cases
Only public keys and public text are read, except that an Electrum file is read to find whether it holds a secret.
An Electrum file's keystore is checked for a private key or seed without its values being kept; the file's own bytes are the caller's.
Limits
A file whose stated first address is not its wallet's is refused.
A key in a SLIP-132 version that disagrees with the script is refused.
A receive and a change descriptor are one wallet only when they are the same but for /0/* and /1/*, each with its checksum, if any, holding; otherwise the file is refused.
A file for Wasabi is written only for a native SegWit single-key wallet at 84h/0h/0h (mainnet) or 84h/1h/0h (test networks).
Faraday's own calls
A SLIP-132 version is checked against the script and the path around the key. Conservative, F155.
A Caravan file whose startingAddressIndex is not 0, and an Electrum multisig keystore with no fingerprint, are refused. Conservative, F155.
BIP 137, Signatures of Messages using Private Keys, Deployed
Code
Library: bitcoin 0.32.102, by the rust-bitcoin developers.
Library: secp256k1 0.29.1, by the rust-bitcoin developers (rust-secp256k1), over libsecp256k1, by Bitcoin Core's libsecp256k1 project (bitcoin-core/secp256k1).
Library: base64ct 1.8.3, by the RustCrypto developers.
Library: base16ct 1.0.0, by the RustCrypto developers, through core/faraday-crypto.
Faraday's code: core/faraday-bip: The signature is the legacy compact recoverable signature every signer writes: the public key is recovered from it and compared with the record's; a descriptor record's first address is derived and compared; a record signed with a secret that is not the account's is refused rather than written.
no fuzz target: Takes a record text; the descriptor it carries is the policy parser, which the policy target fuzzes
Cross-check
Compared with others' code: btclib's bms and btclib-wallet's BIP-32, by the btclib developers, for every key record's signature, made, verified and written; Bitcoin Core v31.1 (deriveaddresses), by the Bitcoin Core developers, for a descriptor record's addresses.
Compared, for one part, with Faraday's second version, written by Faraday's authors in Python; that part is not checked against an outside source: BIP 129's record lines read in area_import.py, and the rules no outside code has: the paths line (/0/*,/1/* or No path restrictions, read as the two chains, F64), a descriptor that is not a template, a description over eighty characters, a token not BIP 129's, and the header forms a signature is accepted in.
Area import
Faraday's code faraday_intake::wallet::read_wallet (the wallet a file or text is: descriptors, faraday_bip::coldcard, faraday_bip::multisig_config, Caravan's, Electrum's, Cobo's, Keystone's and Wasabi's files, Specter DIY's addwallet, faraday_bip::bsms::DescriptorRecord), and faraday_bip::bsms::SignerRecord read and verified and faraday_bip::bsms::signer_record over the BIP-48 or BIP-87 account node's key
Compared with Bitcoin Core v31.1's bitcoind on regtest, offline (deriveaddresses), and its descriptors.py (BIP-380's checksum) and address.py, for each wallet's receive and change scripts and every checksum; btclib-wallet 2026.10.29's BIP-32 (btclib's own curve) for every key, btclib 2026.10.24's SLIP-132 versions and addresses, and its bms for every key record's signature, made, verified and written byte for byte; CPython's json for the value of every JSON file read and for a key named twice and a nesting past 32 refused (those two rules are the reader's own, written beside it); the files are written in the area from each format's documentation, and the meaning of their fields is the area's.
Checked first: Core's release tarball against its pinned SHA-256 before every run; btclib's wheels against the hashes btclib-wallet's lock file names (references.sha256), with libsecp256k1 off; BIP 129's own records and the real files of Sparrow, BlueWallet (Nunchuk's, Coldcard's and Unchained's among them), Coldcard, Caravan and Liana, judged in the prelude.
The wallet's name a file carries; Electrum's encrypted files and BSMS's encrypted records, which Faraday refuses by name; a silent payments record; the kind of a refusal.
Vectors BIP 129's key and descriptor records (tools/vectors/bip129/), and 93 real files from the wallets' own test suites, 62 of them a wallet and 31 refused by both sides (faraday/faraday-core/tests/vectors/interop/: Sparrow's and BlueWallet's; tools/vectors/wallet-files/: Coldcard's firmware tests, Caravan's and Liana's): BSMS records, Coldcard setup files and exports, Caravan, Electrum, Cobo, Keystone, Jade, Specter Desktop and Specter DIY files, descriptors and a Core listdescriptors.
Random cases single-key wallets (P2PKH, P2SH-P2WPKH, P2WPKH, P2TR), sortedmulti in P2WSH, P2SH-P2WSH and P2SH of one to fifteen keys, a miniscript in P2WSH, a taproot tree and a taproot sortedmulti_a, on mainnet and testnet keys, each as a descriptor (multipath with and without checksum, receive and change lines, labelled, receive alone, Core's listdescriptors, Specter Desktop's file, Specter DIY's addwallet with and without its keys' derivations) or as the files that state its kind (Coldcard's export and multisig file, Caravan's, Electrum's, Cobo's, Wasabi's, a key alone, a BSMS descriptor record), in BIP-32's or SLIP-132's spelling; damaged by a wrong checksum, a wrong first address, a SLIP-132 version of another script or another paths line; key records signed by btclib in each header form, with or without damage, and Faraday's own record of random seeds.
Differences Still ours, expected from Faraday's rule: a SLIP-132 version that names another script than the file's (F155), a BSMS paths line other than /0/*,/1/* or No path restrictions, which Faraday reads as the two chains (F64), a BSMS descriptor that is not a template, a key record whose description is over eighty characters or whose token is not BIP 129's; and which account of a Coldcard export, which pair of a listdescriptors, and what each field of every format means, the area's reading of each format's documentation; a checksum in Specter DIY's addwallet, which Specter DIY drops unread and Faraday checks, is refused when Core's code calls it wrong; and the reading of each format's documentation.
Real files both sides refuse, each by a named rule: a Caravan file or an Electrum multisig file whose keys lack a path or a fingerprint, a Caravan quorum that is not the keys listed, a multisig setup file with no policy, a key missing or no format line (Coldcard's own P2SH setup files omit Format, which Faraday refuses), a BSMS record with a paths line other than /0/*,/1/*, a derivation other than /** or <0;1>, a missing line, a first address that is not Core's or not an address, a Coldcard cosigner key file, an Unchained key file and a Coldcard stored setting (a key, not a wallet), and a UR text (area ur). Left out and named: a silent payments record (area sp) and a PSBT or transaction file (areas psbt, tx).
Formats with no published file in a test suite: Nunchuk's own files (only BlueWallet's copies of them), Specter DIY's beyond the one Sparrow keeps, Keystone's beyond Sparrow's, and Core's listdescriptors beyond the one in the interop vectors, whose source is not recorded; Electrum's published test wallets carry a seed and are not taken. Those formats stay the area's own reading (Faraday's second version), as above.
A key record's signature in any of BIP-137's header forms is accepted when it recovers the record's key: btclib is asked with the address that form names (Faraday reads no address from the record).
When it runs Before every release, with a new seed and about ten times the cases.
Last passing runSeed 5be11ec606a76d2767f225b8992c45fe · 4500 cases
SpecificationBIP 379PublishedCodeLibrary: miniscript 12.3Library: base16ct 1.0 (through core/faraday-crypto)Faraday's code: core/faraday-bipCross-checked withBitcoin Core v31.1 itself (getdescriptorinfoOthers' codeFaraday's second version
Action
Compiles a spending policy to a miniscript descriptor and lists the ways it can be spent.
Specification
BIP 379, Miniscript, Draft
Code
Library: miniscript 12.3.7, by the rust-bitcoin developers (rust-miniscript).
Library: base16ct 1.0.0, by the RustCrypto developers, through core/faraday-crypto.
Faraday's code: core/faraday-bip: The policy is compiled by rust-miniscript for SegWit or Taproot; Faraday reads the result back as a wallet and lists its spend paths.
no fuzz target: Takes a policy typed in a field; the descriptor it makes is the policy parser's
Cross-check
Compared with others' code: Bitcoin Core v31.1 itself (getdescriptorinfo, deriveaddresses) and its functional-test framework, by Bitcoin Core's contributors; python-bip380, by Antoine Poinsot, for the miniscript's validity, sanity and script; btclib-wallet's descriptors and miniscript, by the btclib developers, on btclib's own curve, for the descriptor's kind, checksum, script at an index and the miniscript's script.
Compared, for one part, with Faraday's second version, written by Faraday's authors in Python; that part is not checked against an outside source: the lift of a miniscript to a boolean formula over its keys and waits, written in area_compile.py from the fragments' meanings (rust-miniscript's own lift is not used), and the rules by which a policy is refused (a threshold of 0 or above its parts, a lock of 0, a key twice, nothing typed), which no outside compiler states.
Area compile
Faraday's code faraday_bip::compile::compile (a concrete policy to a wsh() or tr() descriptor, the keys it names, the ways it can be spent and the script it pays at an index), over rust-miniscript's policy compiler
Compared with Bitcoin Core v31.1's bitcoind on regtest (getdescriptorinfo and deriveaddresses), with its descriptors.py (BIP-380's checksum); btclib-wallet's descriptors and miniscript (btclib/, on btclib's own curve) for the kind, checksum, script at an index and keys; Antoine Poinsot's python-bip380 (miniscript/) for the miniscript's validity, sanity and script, and its fragments for the lift to a formula, which is ours (lift, in area_compile.py).
Checked first: Its vendored files are hashed against references.sha256 before any run; Core's release tarball is checked against its pinned SHA-256 (tools/reference/core/release.pin) before every run, and the node's version is asked; the self-test makes Faraday's descriptor wrong and the lift wrong, and each is caught.
The script itself: no other compiler makes rust-miniscript's choice, so only that it is valid, sane and means the policy is judged; hash locks, locks in seconds and the time flag of older, which the corpus does not generate; a policy that names a key by a fingerprint token of a loaded key; policies of more than six keys.
Vectors none: no compiler states a script for a policy (rust-miniscript, sipa's and the Go and Python ones choose differently), so the answers are judged by what the descriptor is and means.
Random cases Policies of and, or (with weights), thresh, pk, after and older of one to six keys, each key written as an account key with its origin, compiled for wsh() and for tr() (a key beside the rest, which the compiler takes as the internal key), on mainnet and testnet keys, read at random indices of both chains; refusals: a threshold of 0 or above its parts, a lock of 0, a key twice, nothing typed.
Differences A single key as a tr() policy: rust-miniscript's compile_tr takes the key as the internal key, is left with no leaf and refuses it (Empty Miniscript compilation); Faraday refuses it too, in its own words, and the area counts the refusal. python-bip380 writes a v: over a multi_a, at any depth, as OP_NUMEQUAL OP_VERIFY where BIP 379 and Core write OP_NUMEQUALVERIFY, so such a leaf must equal btclib's script but for that (counted); the output key, which commits to the leaf, is Core's and btclib's. python-bip380 types and_b's e as f_X s_X f_Y s_Y where BIP 379 has e_X e_Y s_X s_Y, so it calls thresh(1,X,a:and_b(pk(A),s:pk(B))) malleable where BIP 379, Core and btclib call it sane. Its thresh leaves the first part out of e, s and m, so it never calls a thresh expressive and calls an or_c over one malleable, where the same three call it sane. Its 0 is not s where BIP 379's is, so l:X and u:X lose X's s. Such a miniscript is asked of python-bip380 again with those three rules as BIP 379's, must be sane then and is counted; any other reason python-bip380 gives stops the area. Its thresh of 1 never sets its lock fields, so reading one inside a thresh of 2 or more raises a TypeError, where BIP 379, Core and btclib read it. Such a miniscript is read again with those fields set from its parts, as Core keeps them, and is counted; any other error stops the area.
When it runs Before every release, with a new seed and about ten times the cases.
Last passing runSeed 5be11ec606a76d2767f225b8992c45fe · 3000 cases
Aggregates MuSig2 public keys (BIP 327), publishes the aggregate as an extended public key (BIP 328) and reads the musig() expression of a wallet (BIP 390).
Specification
BIP 327, MuSig2 for BIP340-compatible Multi-Signatures, Deployed
BIP 328, Derivation Scheme for MuSig2 Aggregate Keys, Complete
BIP 341, Taproot: SegWit version 1 spending rules, Deployed
Code
Library: secp256k1 0.29.1, by the rust-bitcoin developers (rust-secp256k1), over libsecp256k1, by Bitcoin Core's libsecp256k1 project (bitcoin-core/secp256k1).
Library: bitcoin 0.32.102, by the rust-bitcoin developers.
Library: sha2 0.11.0, by the RustCrypto developers, through core/faraday-crypto.
Library: base16ct 1.0.0, by the RustCrypto developers, through core/faraday-crypto.
Faraday's code: core/faraday-bip: Written here over libsecp256k1's point and scalar operations; keys inside a musig() are sorted after derivation and before aggregation as BIP 390 requires, while key_agg itself sorts nothing.
Written by Faraday
BIP-327 MuSig2, with BIP-328 and BIP-390 (faraday-bip::musig) · No established implementation exists
libsecp256k1's MuSig2 is in rust-secp256k1 0.32 and later; bitcoin 0.32, which Faraday uses, is on 0.29, and no miniscript release builds on bitcoin 0.33 yet.
Compared with others' code: BIP-327's reference.py, by the BIP's authors, and btclib's MuSig2 (ecc.ecc.musig2), by the btclib developers, on its own curve, for key aggregation, tweaks and the aggregate signature; Bitcoin Core v31.1's musig() descriptors through deriveaddresses, by the Bitcoin Core developers, Core's musig module is libsecp256k1's, as Faraday's point operations are, so it judges BIP-390's descriptors and addresses, not the curve maths.
Area musig
Faraday's code faraday_bip::musig
Compared with BIP-327's reference.py (bip327/); btclib's MuSig2 (btclib/, its own curve) in full, answering every operation beside it and verifying the aggregate signature as BIP-340; btclib-wallet's BIP-373 roles over the Core round trip's PSBTs; Bitcoin Core v31.1 (deriveaddresses) for musig() descriptors.
Checked first: Its vendored files are hashed against references.sha256 before any run, and a published vector's answer is required of the reference as well as of Faraday.
Vectors All eight files of tools/vectors/bip327/; the valid and invalid descriptors of tools/vectors/bip390/ (Core).
Random cases Sessions of 1 to 3 signers: key sort and aggregation, tweaks, nonces, partial signatures, their verification (and a tampered one), aggregation checked as BIP-340, deterministic signing; tr(musig(…)) wallets of 2 to 4 keys, as xpubs on both chains or as plain keys, whose scripts Core pays too.
Differences None known.
When it runs Before every release, with a new seed and about ten times the cases.
Last passing runSeed 5be11ec606a76d2767f225b8992c45fe · 320 cases
Only public keys are used; nothing here holds a secret.
Nothing secret is held.
Limits
A nested musig() or one with fewer than two participants is refused.
Key path only: script-path spends are refused; no WIF participant, no tap tree.
Faraday's own calls
Script-path spends of a musig() wallet are refused; only the key path is built. Conservative, F155.
A musig() wallet two of whose keys have one master fingerprint is refused at registration: the MuSig2 check matches one participant to each master fingerprint, so a second account of one seed never signs. Conservative.
Writes and reads an extended public key in its SLIP-132 spelling, and takes a version only where it agrees with the script and the path around the key.
Specification
SLIP-0132, Registered HD version bytes for BIP-0032, Status not checked
Library: bitcoin 0.32.102, by the rust-bitcoin developers.
Faraday's code: core/faraday-bip: All ten public versions are read; a key whose version disagrees with the script or the purpose in its path is a mismatch, never converted silently; every key read as text goes through the strict decoder.
Compared with others' code: btclib-wallet's slip132 and bip32, by the btclib developers.
Area addr
Faraday's code faraday_bip::address::parse, bitcoin's Address::from_script, faraday_bip::account (account xpub, SLIP-132, descriptor, addresses), faraday_bip::descriptor's checksum, faraday_bip::policy::WalletPolicy::from_descriptor (an account descriptor's kind, text and script at an index)
Compared with Bitcoin Core's functional-test framework (core/): segwit_addr.py, Base58Check, descriptors.py; BIP 380's own checksum code as the BIP prints it (bip380/); btclib-wallet's bip32 and slip132 (btclib/, on btclib's own curve) for accounts' keys, and its descriptors (descriptors) for each account descriptor's kind, text, script at an index and checksum, and as a third checksum judge; Bitcoin Core v31.1's bitcoind on regtest for every account's address (deriveaddresses) and for reading Faraday's regtest descriptors (getdescriptorinfo).
Checked first: Its vendored files are hashed against references.sha256 before any run, and a published vector's answer is required of the reference as well as of Faraday; every descriptor checksum is also asked of BIP 380's own code, as the BIP prints it, and of btclib's; Core's release tarball is checked against its pinned SHA-256 (tools/reference/core/release.pin) before every run, and the node's version is asked.
Vectors BIP-350's and BIP-173's addresses, BIP-380's checksum cases, BIP-49's, 84's and 86's accounts (tools/vectors/addresses/).
Random cases Scripts of every address kind on every network, written and read back, then changed; accounts of every type at random indices, their descriptors read and changed; random descriptors' checksums.
Differences A descriptor with a second # in its body: Faraday and btclib refuse it, as Bitcoin Core's parser does, where BIP 380's code and Core's framework check the last nine characters; its checksum is asked of btclib only. btclib reads descriptors Faraday takes for no account (pk, combo, multi, addr, raw) and other chains than <0;1>; the area asks it for the four account descriptors with both chains only.
When it runs Before every release, with a new seed and about ten times the cases.
Last passing runSeed 5be11ec606a76d2767f225b8992c45fe · 40000 cases
Reads an address typed or scanned, and says whether the text so far can still become an address on a network.
Specification
BIP 173, Base32 address format for native v0-16 witness outputs, Deployed
BIP 350, Bech32m Format for v1+ Witness Addresses, Deployed
Base58Check, Base58Check encoding, as Bitcoin Core writes it, Convention
Code
Library: bitcoin 0.32.102, by the rust-bitcoin developers.
Faraday's code: core/faraday-bip: An address of another network is told apart from an invalid one, and a silent payment address is told apart from both. A scanned address is told apart as one of a loaded wallet's first 100 receive or change addresses, one of another network, or text of at least 26 characters with an address's prefix that does not parse.
Checked against
tools/vectors/addresses
Published, by the authors of BIP 173, BIP 350, BIP 380, BIP 49, BIP 84 and BIP 86 (bitcoin/bips).
Compared with others' code: Bitcoin Core's functional-test framework, v31.1, by Bitcoin Core's contributors.
Area addr
Faraday's code faraday_bip::address::parse, bitcoin's Address::from_script, faraday_bip::account (account xpub, SLIP-132, descriptor, addresses), faraday_bip::descriptor's checksum, faraday_bip::policy::WalletPolicy::from_descriptor (an account descriptor's kind, text and script at an index)
Compared with Bitcoin Core's functional-test framework (core/): segwit_addr.py, Base58Check, descriptors.py; BIP 380's own checksum code as the BIP prints it (bip380/); btclib-wallet's bip32 and slip132 (btclib/, on btclib's own curve) for accounts' keys, and its descriptors (descriptors) for each account descriptor's kind, text, script at an index and checksum, and as a third checksum judge; Bitcoin Core v31.1's bitcoind on regtest for every account's address (deriveaddresses) and for reading Faraday's regtest descriptors (getdescriptorinfo).
Checked first: Its vendored files are hashed against references.sha256 before any run, and a published vector's answer is required of the reference as well as of Faraday; every descriptor checksum is also asked of BIP 380's own code, as the BIP prints it, and of btclib's; Core's release tarball is checked against its pinned SHA-256 (tools/reference/core/release.pin) before every run, and the node's version is asked.
Vectors BIP-350's and BIP-173's addresses, BIP-380's checksum cases, BIP-49's, 84's and 86's accounts (tools/vectors/addresses/).
Random cases Scripts of every address kind on every network, written and read back, then changed; accounts of every type at random indices, their descriptors read and changed; random descriptors' checksums.
Differences A descriptor with a second # in its body: Faraday and btclib refuse it, as Bitcoin Core's parser does, where BIP 380's code and Core's framework check the last nine characters; its checksum is asked of btclib only. btclib reads descriptors Faraday takes for no account (pk, combo, multi, addr, raw) and other chains than <0;1>; the area asks it for the four account descriptors with both chains only.
When it runs Before every release, with a new seed and about ten times the cases.
Last passing runSeed 5be11ec606a76d2767f225b8992c45fe · 40000 cases
12 actions · 9 own specification · 2 with Faraday's own code · 2 cross-checked with others' code · 10 with Faraday's second version · 2 not cross-checked
ActionSpecificationCodeCross-checked with
Turn dice into entropy
SpecificationDice hashing of Coldcard and SeedSignerPublishedCodeLibrary: sha2 0.11 (through core/faraday-crypto)Faraday's code: core/faraday-entropyFaraday's own codeCross-checked withColdcard's rolls.py and rolls12.py (public domain)Others' codeFaraday's second version
Action
Turns dice rolls into entropy by one of three published procedures, and cautions about runs, sequences and skew.
Specification
Dice hashing of Coldcard and SeedSigner, Coldcard rolls.py, SeedSigner, EntropyLab, Keystone and BitBox dice procedures, Convention
Code
Library: sha2 0.11.0, by the RustCrypto developers, through core/faraday-crypto.
Faraday's code: core/faraday-entropy: Hashed rolls are SHA-256 of the rolls as ASCII digits, truncated to the strength; the second procedure writes every 6 as 0 first; the third names every word from five rolls of 1 to 4 and a sixth read as a coin, and the checksum replaces the last word's low bits.
Written by Faraday
Dice, coin, card, hex and camera entropy accumulation and packing, and the mix of sources (faraday-entropy) · Faraday's own specification
Faraday's own procedures over SHA-256; the card, camera and mix procedures are labelled as not yet reviewed outside Faraday.
no fuzz target: Takes single key presses from a pad, one die face at a time; no text is parsed
Cross-check
Compared with others' code: Coldcard's rolls.py and rolls12.py (public domain), run for the hashed procedure and every rolls commitment; SeedSigner's mnemonic_generation.py (MIT) over embit's BIP-39, run for the hashed procedure at 50 and 99 rolls and for direct selection's entropy, read back from its completed words, at every length.
Compared, for one part, with Faraday's second version, written by Faraday's authors in Python; that part is not checked against an outside source: EntropyLab's six-as-zero and direct word selection (JavaScript, which needs Node, written out in area_entropy.py from tools/reference/dice/README.md; the wordlist indices from faces are Faraday's rule, SeedSigner has no dice selection), the cut of Coldcard's digest to 20, 24 and 28 bytes, and the roll counts and refused faces.
Area entropy
Faraday's code faraday_entropy: dice under the three procedures, coins, hex, cards, camera frames, the device's answer, a mix
Compared with The procedures written out in area_entropy.py over hashlib, from tools/reference/entropy/README.md and the dice sources quoted in tools/reference/dice/README.md, except that the hashed dice procedure and every rolls commitment are Coldcard's own rolls.py and rolls12.py (tools/reference/coldcard-rolls/, run, public domain) and hex digits become bytes through CPython's bytes.fromhex; SeedSigner's mnemonic_generation.py (tools/reference/seedsigner/) over embit's BIP-39 (tools/reference/embit/) reads the hashed procedure at 50 and 99 rolls and direct selection's last word back.
Checked first: The hashed dice procedure is Coldcard's own scripts run, their files hashed against references.sha256 before any run; SeedSigner's and embit's files are hashed the same way and their functions run; the rest is written in the area over hashlib from the statements of tools/reference/entropy/README.md and tools/reference/dice/README.md, and the published dice answers are required of them as well as of Faraday.
Vectors Coldcard's rolls.py digest, EntropyLab's six-as-zero and direct word selection (tools/vectors/entropy/).
Random cases Runs of every source at every strength, short of the count, at it and past it, with faces, cards, frames and characters the pads refuse and every source past its limit; mixes of one to six sources given by their inputs.
Differences SeedSigner's generate_mnemonic_from_dice cuts to 16 bytes only at exactly 50 rolls and takes every other count as 32 bytes, and its calculate_checksum completes 12 and 24 words only: SeedSigner judges the hashed procedure at 50 and 99 rolls and direct selection's last word at 12 and 24 words (at 15, 18 and 21 embit's checksum through generate_mnemonic_from_bytes), compared as the entropy embit reads back from those words, the checksum itself being area bip39's; it has no six-as-zero, no cut to 20, 24 or 28 bytes, and its dice take no direct selection, which stay the area's own.
When it runs Before every release, with a new seed and about ten times the cases.
Last passing runSeed 5be11ec606a76d2767f225b8992c45fe · 30000 cases
SpecificationOwn specificationCodeLibrary: sha2 0.11 (through core/faraday-crypto)Library: base16ct 1.0 (through core/faraday-crypto)Faraday's code: core/faraday-entropyCross-checked withCPython's bytes.fromhexOthers' codeFaraday's second version
Action
Packs coin flips into entropy most significant bit first, and takes hexadecimal digits as they are.
Specification
Own specification (no decision)
Code
Library: sha2 0.11.0, by the RustCrypto developers, through core/faraday-crypto.
Library: base16ct 1.0.0, by the RustCrypto developers, through core/faraday-crypto.
Faraday's code: core/faraday-entropy: Each flip is one bit, packed most significant bit first without hashing; hex is two digits a byte, 32 to 64 digits, taken as they are; the commitment is a separate SHA-256 of what went in.
Checked against
tools/vectors/entropy
Computed by Coldcard's rolls.py and EntropyLab, run as tools/reference/dice/README.md records.
no fuzz target: Takes single flips and digits from a pad; no outside text is parsed beyond hex digits
Cross-check
Compared with others' code: CPython's bytes.fromhex, by the CPython developers, for hex digits read as bytes, against base16ct in Faraday.
Compared, for one part, with Faraday's second version, written by Faraday's authors in Python; that part is not checked against an outside source: the packing of flips, the commitments, and which characters and how many digits hex takes, written out in area_entropy.py.
Area entropy
Faraday's code faraday_entropy: dice under the three procedures, coins, hex, cards, camera frames, the device's answer, a mix
Compared with The procedures written out in area_entropy.py over hashlib, from tools/reference/entropy/README.md and the dice sources quoted in tools/reference/dice/README.md, except that the hashed dice procedure and every rolls commitment are Coldcard's own rolls.py and rolls12.py (tools/reference/coldcard-rolls/, run, public domain) and hex digits become bytes through CPython's bytes.fromhex; SeedSigner's mnemonic_generation.py (tools/reference/seedsigner/) over embit's BIP-39 (tools/reference/embit/) reads the hashed procedure at 50 and 99 rolls and direct selection's last word back.
Checked first: The hashed dice procedure is Coldcard's own scripts run, their files hashed against references.sha256 before any run; SeedSigner's and embit's files are hashed the same way and their functions run; the rest is written in the area over hashlib from the statements of tools/reference/entropy/README.md and tools/reference/dice/README.md, and the published dice answers are required of them as well as of Faraday.
Vectors Coldcard's rolls.py digest, EntropyLab's six-as-zero and direct word selection (tools/vectors/entropy/).
Random cases Runs of every source at every strength, short of the count, at it and past it, with faces, cards, frames and characters the pads refuse and every source past its limit; mixes of one to six sources given by their inputs.
Differences SeedSigner's generate_mnemonic_from_dice cuts to 16 bytes only at exactly 50 rolls and takes every other count as 32 bytes, and its calculate_checksum completes 12 and 24 words only: SeedSigner judges the hashed procedure at 50 and 99 rolls and direct selection's last word at 12 and 24 words (at 15, 18 and 21 embit's checksum through generate_mnemonic_from_bytes), compared as the entropy embit reads back from those words, the checksum itself being area bip39's; it has no six-as-zero, no cut to 20, 24 or 28 bytes, and its dice take no direct selection, which stay the area's own.
When it runs Before every release, with a new seed and about ten times the cases.
Last passing runSeed 5be11ec606a76d2767f225b8992c45fe · 30000 cases
SpecificationOwn specificationCodeLibrary: sha2 0.11 (through core/faraday-crypto)Faraday's code: core/faraday-entropyCross-checked withFaraday's second version
Action
Turns playing-card draws into entropy as SHA-256 of the draws' indices, one byte each.
Specification
Own specification (F158)
Code
Library: sha2 0.11.0, by the RustCrypto developers, through core/faraday-crypto.
Faraday's code: core/faraday-entropy: A deck tracker refuses a card already out, so each draw is worth log2 of the cards left; 25, 31, 39, 50 and 58 draws are asked for, the last more than one deck holds.
Checked against
tools/vectors/cards
Faraday's own known answers.
tools/vectors/entropy
Computed by Coldcard's rolls.py and EntropyLab, run as tools/reference/dice/README.md records.
An outside review recorded in a decision ends it; a reproduction from the specification by an outside party is asked for in docs/AUDIT-SUBMISSIONS.md §10.
Compared with Faraday's second version, written by Faraday's authors in Python from the specification. Not checked against an outside source.
What it covers: the card procedure, written out in area_entropy.py.
Area entropy
Faraday's code faraday_entropy: dice under the three procedures, coins, hex, cards, camera frames, the device's answer, a mix
Compared with The procedures written out in area_entropy.py over hashlib, from tools/reference/entropy/README.md and the dice sources quoted in tools/reference/dice/README.md, except that the hashed dice procedure and every rolls commitment are Coldcard's own rolls.py and rolls12.py (tools/reference/coldcard-rolls/, run, public domain) and hex digits become bytes through CPython's bytes.fromhex; SeedSigner's mnemonic_generation.py (tools/reference/seedsigner/) over embit's BIP-39 (tools/reference/embit/) reads the hashed procedure at 50 and 99 rolls and direct selection's last word back.
Checked first: The hashed dice procedure is Coldcard's own scripts run, their files hashed against references.sha256 before any run; SeedSigner's and embit's files are hashed the same way and their functions run; the rest is written in the area over hashlib from the statements of tools/reference/entropy/README.md and tools/reference/dice/README.md, and the published dice answers are required of them as well as of Faraday.
Vectors Coldcard's rolls.py digest, EntropyLab's six-as-zero and direct word selection (tools/vectors/entropy/).
Random cases Runs of every source at every strength, short of the count, at it and past it, with faces, cards, frames and characters the pads refuse and every source past its limit; mixes of one to six sources given by their inputs.
Differences SeedSigner's generate_mnemonic_from_dice cuts to 16 bytes only at exactly 50 rolls and takes every other count as 32 bytes, and its calculate_checksum completes 12 and 24 words only: SeedSigner judges the hashed procedure at 50 and 99 rolls and direct selection's last word at 12 and 24 words (at 15, 18 and 21 embit's checksum through generate_mnemonic_from_bytes), compared as the entropy embit reads back from those words, the checksum itself being area bip39's; it has no six-as-zero, no cut to 20, 24 or 28 bytes, and its dice take no direct selection, which stay the area's own.
When it runs Before every release, with a new seed and about ten times the cases.
Last passing runSeed 5be11ec606a76d2767f225b8992c45fe · 30000 cases
The accumulator is a fixed buffer erased when it is dropped; the entropy it makes is a RawEntropy that is wiped when dropped.
Limits
A card already out of its deck is refused.
At most two decks (104 cards) are held.
Five cards in a row in the deck's own order, up or down, are cautioned, not refused.
Faraday's own calls
The procedure is Faraday's own: a card is the index suit × 13 + rank, and the entropy is SHA-256 of those one-byte indices; no other wallet's card mode is claimed to match, and the bits counted assume a well-shuffled deck. Novel, F158.
SpecificationOwn specificationCodeLibrary: sha2 0.11 (through core/faraday-crypto)Faraday's code: core/faraday-entropyCross-checked withFaraday's second version
Action
Commits to camera frames as SHA-256 over the frames' SHA-256 digests, for a mix or the session's randomness, never a key alone.
Specification
Own specification (F158)
Code
Library: sha2 0.11.0, by the RustCrypto developers, through core/faraday-crypto.
Faraday's code: core/faraday-entropy: A frame is taken only if it has at least 32 distinct luma values and its SHA-256 is not one already taken; three frames are asked for per 128 bits, rounded up, as a guard against a still scene rather than an entropy calculation.
Checked against
tools/vectors/camera
Faraday's own known answers.
tools/vectors/entropy
Computed by Coldcard's rolls.py and EntropyLab, run as tools/reference/dice/README.md records.
An outside review recorded in a decision ends it; a reproduction from the specification by an outside party is asked for in docs/AUDIT-SUBMISSIONS.md §10.
Compared with Faraday's second version, written by Faraday's authors in Python from the specification. Not checked against an outside source.
What it covers: the frames' commitment, written out in area_entropy.py.
Area entropy
Faraday's code faraday_entropy: dice under the three procedures, coins, hex, cards, camera frames, the device's answer, a mix
Compared with The procedures written out in area_entropy.py over hashlib, from tools/reference/entropy/README.md and the dice sources quoted in tools/reference/dice/README.md, except that the hashed dice procedure and every rolls commitment are Coldcard's own rolls.py and rolls12.py (tools/reference/coldcard-rolls/, run, public domain) and hex digits become bytes through CPython's bytes.fromhex; SeedSigner's mnemonic_generation.py (tools/reference/seedsigner/) over embit's BIP-39 (tools/reference/embit/) reads the hashed procedure at 50 and 99 rolls and direct selection's last word back.
Checked first: The hashed dice procedure is Coldcard's own scripts run, their files hashed against references.sha256 before any run; SeedSigner's and embit's files are hashed the same way and their functions run; the rest is written in the area over hashlib from the statements of tools/reference/entropy/README.md and tools/reference/dice/README.md, and the published dice answers are required of them as well as of Faraday.
Vectors Coldcard's rolls.py digest, EntropyLab's six-as-zero and direct word selection (tools/vectors/entropy/).
Random cases Runs of every source at every strength, short of the count, at it and past it, with faces, cards, frames and characters the pads refuse and every source past its limit; mixes of one to six sources given by their inputs.
Differences SeedSigner's generate_mnemonic_from_dice cuts to 16 bytes only at exactly 50 rolls and takes every other count as 32 bytes, and its calculate_checksum completes 12 and 24 words only: SeedSigner judges the hashed procedure at 50 and 99 rolls and direct selection's last word at 12 and 24 words (at 15, 18 and 21 embit's checksum through generate_mnemonic_from_bytes), compared as the entropy embit reads back from those words, the checksum itself being area bip39's; it has no six-as-zero, no cut to 20, 24 or 28 bytes, and its dice take no direct selection, which stay the area's own.
When it runs Before every release, with a new seed and about ten times the cases.
Last passing runSeed 5be11ec606a76d2767f225b8992c45fe · 30000 cases
The accumulator is a fixed buffer erased when it is dropped; the entropy it makes is a RawEntropy that is wiped when dropped.
Limits
A frame of fewer than 32 distinct values is refused.
A frame whose SHA-256 was already taken is refused.
At most 8 frames are held.
Never a key's only source: a mix's member, or added to the session's randomness.
Faraday's own calls
The procedure is Faraday's own, and three frames per 128 bits is a heuristic; the frames only add to a mix or to the system's randomness, never make a key alone. Novel, F158.
SpecificationOwn specificationCodeLibrary: sha2 0.11 (through core/faraday-crypto)Faraday's code: core/faraday-entropyCross-checked withFaraday's second version
Action
Records pointer moves and key presses with time and a running count, and commits them in batches of SHA-256 for the session's randomness.
Specification
Own specification (F86)
Code
Library: sha2 0.11.0, by the RustCrypto developers, through core/faraday-crypto.
Faraday's code: core/faraday-entropy: Each event is a 17-byte record of its kind, a running count, the time and its position or key code; a batch of at most 64 is committed as SHA-256 of the domain and its records and then wiped, and the count goes on across batches.
An outside review recorded in a decision ends it; a reproduction from the specification by an outside party is asked for in docs/AUDIT-SUBMISSIONS.md §10.
Compared with Faraday's second version, written by Faraday's authors in Python from the specification. Not checked against an outside source.
What it covers: docs/OWN-RANDOMNESS.md §2.1 and §2.3, written out in area_own.py.
Area own-randomness
Faraday's code faraday_core's fresh.rs (Own, the session seed and pool) through the testkit's fresh and seed_draw, with faraday_entropy's dice, coin, camera and pointer-and-keys commitments
Compared with docs/OWN-RANDOMNESS.md §2.1 and §2.3 written out in area_own.py over hashlib.
Checked first: The second implementation is written in the area from docs/OWN-RANDOMNESS.md §2.3 over hashlib, and the known answers of faraday/faraday-core/tests/all/own_randomness.rs are required of it as well as of Faraday.
Vectors The known answers of faraday/faraday-core/tests/all/own_randomness.rs: nothing added, dice before and after the system's answers, dice then coins, a batch of pointer moves and keys, a lock.
Random cases Random sessions of system answers, dice, coins, camera frames (some refused, some empty) and pointer moves and keys (none to several batches), locks, seed draws, fresh bytes and counts, in any order.
Differences None known.
When it runs Before every release, with a new seed and about ten times the cases.
Last passing runSeed 5be11ec606a76d2767f225b8992c45fe · 4000 cases
SpecificationOwn specificationCodeLibrary: sha2 0.11 (through core/faraday-crypto)Faraday's code: core/faraday-entropyCross-checked withFaraday's second version
Action
Combines two to five sources, dice or this device among them, by hashing their commitments in the order taken.
Specification
Own specification (F158)
Code
Library: sha2 0.11.0, by the RustCrypto developers, through core/faraday-crypto.
Faraday's code: core/faraday-entropy: The entropy is SHA-256 over the sources' 32-byte commitments, concatenated in the order taken and truncated to the strength; the same commitments in the same order always give the same key, so they can be written down before the words appear.
Checked against
tools/vectors/entropy
Computed by Coldcard's rolls.py and EntropyLab, run as tools/reference/dice/README.md records.
An outside review recorded in a decision ends it; a reproduction from the specification by an outside party is asked for in docs/AUDIT-SUBMISSIONS.md §10.
Compared with Faraday's second version, written by Faraday's authors in Python from the specification. Not checked against an outside source.
What it covers: the mix of commitments, written out in area_entropy.py.
Area entropy
Faraday's code faraday_entropy: dice under the three procedures, coins, hex, cards, camera frames, the device's answer, a mix
Compared with The procedures written out in area_entropy.py over hashlib, from tools/reference/entropy/README.md and the dice sources quoted in tools/reference/dice/README.md, except that the hashed dice procedure and every rolls commitment are Coldcard's own rolls.py and rolls12.py (tools/reference/coldcard-rolls/, run, public domain) and hex digits become bytes through CPython's bytes.fromhex; SeedSigner's mnemonic_generation.py (tools/reference/seedsigner/) over embit's BIP-39 (tools/reference/embit/) reads the hashed procedure at 50 and 99 rolls and direct selection's last word back.
Checked first: The hashed dice procedure is Coldcard's own scripts run, their files hashed against references.sha256 before any run; SeedSigner's and embit's files are hashed the same way and their functions run; the rest is written in the area over hashlib from the statements of tools/reference/entropy/README.md and tools/reference/dice/README.md, and the published dice answers are required of them as well as of Faraday.
Vectors Coldcard's rolls.py digest, EntropyLab's six-as-zero and direct word selection (tools/vectors/entropy/).
Random cases Runs of every source at every strength, short of the count, at it and past it, with faces, cards, frames and characters the pads refuse and every source past its limit; mixes of one to six sources given by their inputs.
Differences SeedSigner's generate_mnemonic_from_dice cuts to 16 bytes only at exactly 50 rolls and takes every other count as 32 bytes, and its calculate_checksum completes 12 and 24 words only: SeedSigner judges the hashed procedure at 50 and 99 rolls and direct selection's last word at 12 and 24 words (at 15, 18 and 21 embit's checksum through generate_mnemonic_from_bytes), compared as the entropy embit reads back from those words, the checksum itself being area bip39's; it has no six-as-zero, no cut to 20, 24 or 28 bytes, and its dice take no direct selection, which stay the area's own.
When it runs Before every release, with a new seed and about ten times the cases.
Last passing runSeed 5be11ec606a76d2767f225b8992c45fe · 30000 cases
The accumulator is a fixed buffer erased when it is dropped; the entropy it makes is a RawEntropy that is wiped when dropped.
Limits
Fewer than two sources make no entropy; at most five are held.
A mix without dice or this device among its sources makes no key.
Faraday's own calls
The specification is Faraday's own: SHA-256 over the concatenated commitments. With dice or this device among the sources, each at its full count, it only adds to that member's strength. Novel, F158.
SpecificationOwn specificationCodeLibrary: sha2 0.11 (through core/faraday-crypto)Faraday's code: core/faraday-entropyCross-checked withFaraday's second version
Action
Hashes the 32 bytes the shell answered the entropy request with into a key's entropy.
Specification
Own specification (no decision)
Code
Library: sha2 0.11.0, by the RustCrypto developers, through core/faraday-crypto.
Faraday's code: core/faraday-entropy: The entropy is SHA-256 of the 32 bytes, truncated to the strength, so the key is not the shell's bytes themselves; the source trusts the device. Where the person added randomness of their own, the hash is over a label, the 32 bytes and the accumulator of what was added, so someone who lacks either part cannot predict the key.
Checked against
tools/vectors/entropy
Computed by Coldcard's rolls.py and EntropyLab, run as tools/reference/dice/README.md records.
no fuzz target: Takes one 32-byte answer from the shell
Cross-check
Compared with Faraday's second version, written by Faraday's authors in Python from the specification. Not checked against an outside source.
What it covers: the hash of the shell's answer, written out in area_entropy.py; with what the person added, as area_own.py writes it.
Area entropy
Faraday's code faraday_entropy: dice under the three procedures, coins, hex, cards, camera frames, the device's answer, a mix
Compared with The procedures written out in area_entropy.py over hashlib, from tools/reference/entropy/README.md and the dice sources quoted in tools/reference/dice/README.md, except that the hashed dice procedure and every rolls commitment are Coldcard's own rolls.py and rolls12.py (tools/reference/coldcard-rolls/, run, public domain) and hex digits become bytes through CPython's bytes.fromhex; SeedSigner's mnemonic_generation.py (tools/reference/seedsigner/) over embit's BIP-39 (tools/reference/embit/) reads the hashed procedure at 50 and 99 rolls and direct selection's last word back.
Checked first: The hashed dice procedure is Coldcard's own scripts run, their files hashed against references.sha256 before any run; SeedSigner's and embit's files are hashed the same way and their functions run; the rest is written in the area over hashlib from the statements of tools/reference/entropy/README.md and tools/reference/dice/README.md, and the published dice answers are required of them as well as of Faraday.
Vectors Coldcard's rolls.py digest, EntropyLab's six-as-zero and direct word selection (tools/vectors/entropy/).
Random cases Runs of every source at every strength, short of the count, at it and past it, with faces, cards, frames and characters the pads refuse and every source past its limit; mixes of one to six sources given by their inputs.
Differences SeedSigner's generate_mnemonic_from_dice cuts to 16 bytes only at exactly 50 rolls and takes every other count as 32 bytes, and its calculate_checksum completes 12 and 24 words only: SeedSigner judges the hashed procedure at 50 and 99 rolls and direct selection's last word at 12 and 24 words (at 15, 18 and 21 embit's checksum through generate_mnemonic_from_bytes), compared as the entropy embit reads back from those words, the checksum itself being area bip39's; it has no six-as-zero, no cut to 20, 24 or 28 bytes, and its dice take no direct selection, which stay the area's own.
When it runs Before every release, with a new seed and about ten times the cases.
Last passing runSeed 5be11ec606a76d2767f225b8992c45fe · 30000 cases
SpecificationOwn specificationCodeLibrary: getrandom 0.3 and 0.4Faraday's code: faraday/shells/windowCross-checked withNot cross-checked
Action
Reads 32 bytes from the system's generator for the desktop app and the Starter, and names the source.
Specification
Own specification (F102, F86)
Code
Library: getrandom 0.3.4 and 0.4.3, by the Rand Project developers.
Faraday's code: faraday/shells/window: The bytes come from getrandom(2), ProcessPrng, getentropy(2) or crypto.getRandomValues according to the platform; when the system gives none, nothing is answered.
SpecificationOwn specificationCodeLibrary: bitcoin_hashes 0.14Faraday's code: faraday/faraday-coreFaraday's own codeCross-checked withFaraday's second version
Action
Keeps the session's seed and pool from the shell's answers, mixes a person's own randomness in, never in place of the system's, and draws the seed of a MuSig2 round.
Specification
Own specification (F234, F86)
Code
Library: bitcoin_hashes 0.14.101, by the rust-bitcoin developers.
Faraday's code: faraday/faraday-core: The seed is the shell's first answer, hashed with the person's accumulator when there is one and again at each batch added (SHA-256 of a label, the base and the accumulator); the accumulator chains each batch's commitment; a fresh answer is SHA-256 of a label, what it is for, the answer and the accumulator; a signing round's seed is SHA-256 of a label, the session's seed and a count of rounds; nothing is made before the system has answered.
Written by Faraday
The session's random generator: its seed and pool, and the mixing of a person's own randomness (faraday-core::fresh) · Faraday's own specification
Faraday's own procedure over SHA-256, labelled as not yet reviewed outside Faraday.
An outside review recorded in a decision ends it; a reproduction from the specification by an outside party is asked for in docs/AUDIT-SUBMISSIONS.md §10.
Compared with Faraday's second version, written by Faraday's authors in Python from the specification. Not checked against an outside source.
What it covers: docs/OWN-RANDOMNESS.md §2.1 and §2.3, written out in area_own.py.
Area own-randomness
Faraday's code faraday_core's fresh.rs (Own, the session seed and pool) through the testkit's fresh and seed_draw, with faraday_entropy's dice, coin, camera and pointer-and-keys commitments
Compared with docs/OWN-RANDOMNESS.md §2.1 and §2.3 written out in area_own.py over hashlib.
Checked first: The second implementation is written in the area from docs/OWN-RANDOMNESS.md §2.3 over hashlib, and the known answers of faraday/faraday-core/tests/all/own_randomness.rs are required of it as well as of Faraday.
Vectors The known answers of faraday/faraday-core/tests/all/own_randomness.rs: nothing added, dice before and after the system's answers, dice then coins, a batch of pointer moves and keys, a lock.
Random cases Random sessions of system answers, dice, coins, camera frames (some refused, some empty) and pointer moves and keys (none to several batches), locks, seed draws, fresh bytes and counts, in any order.
Differences None known.
When it runs Before every release, with a new seed and about ten times the cases.
Last passing runSeed 5be11ec606a76d2767f225b8992c45fe · 4000 cases
Faraday's code: core/faraday-entropy: Each die gives one bit by comparing its second value with its first, a die with equal values is rolled twice again, and the five bits walk the booklet's tree to a character; dice of 2 to 20 faces are read by the same comparison.
Compared with Faraday's second version, written by Faraday's authors in Python from the specification. Not checked against an outside source.
What it covers: the booklet's dice worksheet, written out in area_roller.py from docs/CODEX32.md §5.5.
Area roller
Faraday's code Faraday Demo's dice rollers (faraday_core's fresh/roller/, through the testkit)
Compared with docs/CODEX32.md §5.6's "The values" and §5.5's worksheet written out in area_roller.py.
Checked first: The second implementation is written in the area from docs/CODEX32.md §5.5 and §5.6 and the booklet's worksheet, and the known answers, the byte distribution and every byte as a face of every die are required of it as well as of Faraday.
Vectors Every byte value as an answer: each face from 42 bytes, the four above 251 skipped; every byte as a face of every die of 2 to 20 faces (faraday_entropy::uniform_face); the booklet's 32 paths on six- and twenty-faced dice and its order with an equal pair (roller.sheet).
Random cases Random answers (some mostly skipped bytes) under clicks of every size into entries of random room, with resets; the five dice of random faces (2 to 20) under clicks of every reach into codex32 shares of random count and length, answers running out part way; rolls of random dice entered by hand, equal pairs among them.
Differences None known.
When it runs Before every release, with a new seed and about ten times the cases.
Last passing runSeed 5be11ec606a76d2767f225b8992c45fe · 30000 cases
SpecificationOwn specificationCodeFaraday's code: faraday/faraday-coreCross-checked withFaraday's second version
Action
Rolls simulated dice for Faraday Demo from the session's randomness, one value per byte with no bias.
Specification
Own specification (F96)
Code
Faraday's code: faraday/faraday-core: Each value is one byte of a 32-byte fresh answer taken from the last to the first; a byte among the 256 mod faces highest is skipped so no face is likelier; a new answer is asked for when one is used up.
An outside review recorded in a decision ends it; a reproduction from the specification by an outside party is asked for in docs/AUDIT-SUBMISSIONS.md §10.
Compared with Faraday's second version, written by Faraday's authors in Python from the specification. Not checked against an outside source.
What it covers: Faraday Demo's roller, written out in area_roller.py from docs/CODEX32.md §5.6.
Area roller
Faraday's code Faraday Demo's dice rollers (faraday_core's fresh/roller/, through the testkit)
Compared with docs/CODEX32.md §5.6's "The values" and §5.5's worksheet written out in area_roller.py.
Checked first: The second implementation is written in the area from docs/CODEX32.md §5.5 and §5.6 and the booklet's worksheet, and the known answers, the byte distribution and every byte as a face of every die are required of it as well as of Faraday.
Vectors Every byte value as an answer: each face from 42 bytes, the four above 251 skipped; every byte as a face of every die of 2 to 20 faces (faraday_entropy::uniform_face); the booklet's 32 paths on six- and twenty-faced dice and its order with an equal pair (roller.sheet).
Random cases Random answers (some mostly skipped bytes) under clicks of every size into entries of random room, with resets; the five dice of random faces (2 to 20) under clicks of every reach into codex32 shares of random count and length, answers running out part way; rolls of random dice entered by hand, equal pairs among them.
Differences None known.
When it runs Before every release, with a new seed and about ten times the cases.
Last passing runSeed 5be11ec606a76d2767f225b8992c45fe · 30000 cases
SpecificationEFF word listsPublishedCodeFaraday's code: core/faraday-bipCross-checked withNot cross-checked
Action
Chooses Diceware words for a passphrase from dice rolls, from the three EFF lists checked by digest.
Specification
EFF word lists, EFF long and short Diceware word lists, Convention, vendored
Code
Faraday's code: core/faraday-bip: The lists are modules written by tools/diceware/gen.py from the committed EFF files and built in; a roll is the index written in base six with one added to each digit; a test checks each list and its SHA-256 against the committed file.
13 actions · 6 with Faraday's own code · 12 cross-checked with others' code · 9 with Faraday's second version · 1 not cross-checked
ActionSpecificationCodeCross-checked with
Make a SeedQR
SpecificationSeedQR · BIP 39PublishedCodeLibrary: sha2 0.11 (through core/faraday-crypto)Library: unicode-normalization 0.1 (through core/faraday-bip)Faraday's code: core/faraday-codecFaraday's own codeCross-checked withSeedSigner's encoders and DecodeQROthers' codeFaraday's second version
Action
Makes a SeedQR or CompactSeedQR picture from a key's words.
Specification
SeedQR, SeedQR and CompactSeedQR, Convention, vendored
BIP 39, Mnemonic code for generating deterministic keys, Deployed
Code
Library: sha2 0.11.0, by the RustCrypto developers, through core/faraday-crypto.
Library: unicode-normalization 0.1.25, by the unicode-rs developers, through core/faraday-bip.
Faraday's code: core/faraday-codec: The word indices as four decimal digits each in numeric mode, or the entropy bytes in byte mode, at error-correction level L; the matrix and the digit buffer are wiped; the code is the smallest version that holds the payload. The app writes the picture as an eight-bit greyscale PNG with the key's fingerprint as its title, and wipes the pixels drawn once the file is made; the blank sheet's grid is the SeedQR of an all-zero seed of the same length, so its fixed squares are every seed's.
Written by Faraday
SeedQR (faraday-codec::seedqr) · No established implementation exists
Compared with others' code: SeedSigner's encoders and DecodeQR, by the SeedSigner developers, over embit's BIP-39 code, by Stepan Snigirev, and Project Nayuki's qrcodegen.py, by Nayuki, and segno, by Lars Heuer, and the pictures decoded by zbar, by the zbar developers, and zxing-cpp, by the zxing-cpp developers.
Compared, for one part, with Faraday's second version, written by Faraday's authors in Python; that part is not checked against an outside source: the CompactSeedQR of 15, 18 and 21 words, which SeedSigner does not define (the entropy itself).
Area seedqr
Faraday's code faraday_codec::seedqr (SeedQR, CompactSeedQR), faraday_codec::qr, the encoder that draws them, and faraday_codec::qr::codex32qr with the picture faraday_core::picture writes of it
Compared with SeedSigner's own encoders and DecodeQR (seedsigner/, unchanged, with embit's BIP-39 code in embit/); Project Nayuki's qrcodegen.py (qrcodegen/), module for module; segno 1.6 (python3-segno), an encoder of another lineage, at Faraday's mask and at its own; Pillow and CPython's zlib, which read every PNG Faraday writes; zbar (zbarimg) and zxing-cpp, which decode the QR code in every picture and return its payload as bytes (qr_decode.py).
Checked first: Its vendored files are hashed against references.sha256 before any run, and a published vector's answer is required of the reference as well as of Faraday; SeedSigner's reader is looser than Faraday (it takes 49 digits, a sign inside a group, 20 to 28 bytes, and does not check the checksum of digits), so Faraday's own rule, the lengths and the digits, stands in front of it in area_seedqr.py and the checksum is embit's; SeedSigner runs in English for every language, the indices being the same; the profile's own pictures are read from their pixels and must be Faraday's code module for module; segno is asked for Faraday's version, level and mode and its mask forced, and its mask is read back from it, its padding quirk being modelled in Nayuki's code; rqrr reads Faraday's and segno's codes; the self-test makes each decoder's answer wrong (a payload's last byte changed) and must catch it.
An empty payload, which segno refuses.
Vectors SeedSigner's nine test SeedQRs (tools/vectors/seedqr/); every string and picture of the Codex32QR profile (tools/vectors/codex32qr/), each decoded by zbar and zxing-cpp.
Random cases Keys of every length and language, both codes and the words read back; digits and bytes malformed; payloads in each mode at each level and version limit; 48-character codex32 strings in either case as Codex32QR codes and the pictures written of them read back and decoded by zbar and zxing-cpp, other lengths refused; the pictures of a key's SeedQR and CompactSeedQR decoded by both and read by Faraday to the key's words; greyscale pictures and QR pictures of random size and scale read by Pillow and zlib.
Differences SeedQR digits: SeedSigner reads a string with 1 to 3 digits more than 48 or 96 (it drops the tail) and one with a sign or a space inside a group of four (int() takes them); Faraday refuses both (5 cases, each checked on both sides and counted). SeedSigner takes no CompactSeedQR of 20, 24 or 28 bytes either, and strips checksum bits for 12 and 24 words only; the corpus keeps Faraday's 15, 18 and 21 word compact form on the entropy itself.
Codex32QR: Faraday picks the mask Nayuki's encoder picks; the profile's encoder chose another for 6 of its 22 pictures. For those the area swaps the mask of Faraday's code for the picture's with qrcodegen.py's masking, requires the picture, and counts it.
Segno 1.6 writes a zero codeword where the pad codewords begin when the data, terminator included, ends on a codeword boundary with room left (its write_padding_bits adds 8 zero bits where none are due; ISO/IEC 18004 7.4.10 adds none): its code is Nayuki's with that codeword changed, which rqrr reads, counted as a known difference, the padding; Faraday's is the standard's.
Segno picks a mask by its own penalty rule, and for some payloads another than Nayuki's and Faraday's; the area requires that code to be Faraday's under the mask segno reports (Nayuki's masking swapped to it) and rqrr to read it, and counts each as a known difference, the mask choice, which a reader ignores.
When it runs Before every release, with a new seed and about ten times the cases.
Last passing runSeed 5be11ec606a76d2767f225b8992c45fe · 8000 cases
Compared with others' code: SeedSigner's encoders and DecodeQR, by the SeedSigner developers, over embit's BIP-39 code, by Stepan Snigirev, and Project Nayuki's qrcodegen.py, by Nayuki, and the pictures decoded by zbar, by the zbar developers, and zxing-cpp, by the zxing-cpp developers.
Compared, for one part, with Faraday's second version, written by Faraday's authors in Python; that part is not checked against an outside source: Faraday's rule written in area_seedqr.py in front of SeedSigner's reader (exactly 48 or 96 digits, 16 or 32 bytes), and the CompactSeedQR of 15, 18 and 21 words, which SeedSigner does not define.
Area seedqr
Faraday's code faraday_codec::seedqr (SeedQR, CompactSeedQR), faraday_codec::qr, the encoder that draws them, and faraday_codec::qr::codex32qr with the picture faraday_core::picture writes of it
Compared with SeedSigner's own encoders and DecodeQR (seedsigner/, unchanged, with embit's BIP-39 code in embit/); Project Nayuki's qrcodegen.py (qrcodegen/), module for module; segno 1.6 (python3-segno), an encoder of another lineage, at Faraday's mask and at its own; Pillow and CPython's zlib, which read every PNG Faraday writes; zbar (zbarimg) and zxing-cpp, which decode the QR code in every picture and return its payload as bytes (qr_decode.py).
Checked first: Its vendored files are hashed against references.sha256 before any run, and a published vector's answer is required of the reference as well as of Faraday; SeedSigner's reader is looser than Faraday (it takes 49 digits, a sign inside a group, 20 to 28 bytes, and does not check the checksum of digits), so Faraday's own rule, the lengths and the digits, stands in front of it in area_seedqr.py and the checksum is embit's; SeedSigner runs in English for every language, the indices being the same; the profile's own pictures are read from their pixels and must be Faraday's code module for module; segno is asked for Faraday's version, level and mode and its mask forced, and its mask is read back from it, its padding quirk being modelled in Nayuki's code; rqrr reads Faraday's and segno's codes; the self-test makes each decoder's answer wrong (a payload's last byte changed) and must catch it.
An empty payload, which segno refuses.
Vectors SeedSigner's nine test SeedQRs (tools/vectors/seedqr/); every string and picture of the Codex32QR profile (tools/vectors/codex32qr/), each decoded by zbar and zxing-cpp.
Random cases Keys of every length and language, both codes and the words read back; digits and bytes malformed; payloads in each mode at each level and version limit; 48-character codex32 strings in either case as Codex32QR codes and the pictures written of them read back and decoded by zbar and zxing-cpp, other lengths refused; the pictures of a key's SeedQR and CompactSeedQR decoded by both and read by Faraday to the key's words; greyscale pictures and QR pictures of random size and scale read by Pillow and zlib.
Differences SeedQR digits: SeedSigner reads a string with 1 to 3 digits more than 48 or 96 (it drops the tail) and one with a sign or a space inside a group of four (int() takes them); Faraday refuses both (5 cases, each checked on both sides and counted). SeedSigner takes no CompactSeedQR of 20, 24 or 28 bytes either, and strips checksum bits for 12 and 24 words only; the corpus keeps Faraday's 15, 18 and 21 word compact form on the entropy itself.
Codex32QR: Faraday picks the mask Nayuki's encoder picks; the profile's encoder chose another for 6 of its 22 pictures. For those the area swaps the mask of Faraday's code for the picture's with qrcodegen.py's masking, requires the picture, and counts it.
Segno 1.6 writes a zero codeword where the pad codewords begin when the data, terminator included, ends on a codeword boundary with room left (its write_padding_bits adds 8 zero bits where none are due; ISO/IEC 18004 7.4.10 adds none): its code is Nayuki's with that codeword changed, which rqrr reads, counted as a known difference, the padding; Faraday's is the standard's.
Segno picks a mask by its own penalty rule, and for some payloads another than Nayuki's and Faraday's; the area requires that code to be Faraday's under the mask segno reports (Nayuki's masking swapped to it) and rqrr to read it, and counts each as a known difference, the mask choice, which a reader ignores.
When it runs Before every release, with a new seed and about ten times the cases.
Last passing runSeed 5be11ec606a76d2767f225b8992c45fe · 8000 cases
Faraday's code: core/faraday-bip: The BCH checksum and the Lagrange interpolation over GF(32) are written here, with no codex32 crate; the string, its payload and the seed live in fixed arrays wiped on drop. Recovery takes exactly k shares; a further share is derived only from exactly k strings at an index not in use.
Written by Faraday
BIP 93 codex32 (faraday-bip::codex32) · One exists but does not fit Faraday's rules for keys
The reference library keeps the seed in text that is never wiped and needs a full operating system.
Does not fit: codex32 0.1.0 holds the seed in a String that is Clone and Debug and never wiped, which tools/lint-secrets.sh refuses, and needs std, which faraday-bip does not have
Compared with others' code: python-codex32, by Ben Westgate, and rust-codex32, by Andrew Poelstra (which decides the threshold of 0 or 2 to 9 and a threshold of 0's share index).
Compared, for one part, with Faraday's second version, written by Faraday's authors in Python; that part is not checked against an outside source: two rules BIP 93 states that neither enforces (the seed's lengths, the order shares are handed out), written in area_codex32.py from the BIP's text.
Area codex32
Faraday's code faraday_bip::codex32
Compared with python-codex32 (codex32/); rust-codex32 at a pinned commit (rust-codex32/), a program outside the workspace: parsing, checksums, the threshold and a threshold of 0's share index, interpolate_at for a fresh set's shares; volvelle-website's checksum worksheet run as a program over every worksheet of 48 and 74 characters; the worksheet of 127 characters written in the area from python-codex32's polymod.
Checked first: Its vendored files are hashed against references.sha256 before any run (the Rust programs' sources included, built offline by run.sh with the toolchain on the PATH), and a published vector's answer is required of the reference as well as of Faraday; rust-codex32 and python-codex32 must give the same answer where both are asked; two rules BIP 93 states that neither enforces (the master seed's sizes, the order shares are handed out) are written in the area from the BIP's text, and the worksheet of 127 characters from BIP 93's polymod alone.
Vectors Every vector of tools/vectors/bip93/, the 55 invalid strings included; volvelle-website's worksheet cells (tools/vectors/codex32-volvelle/); the booklet's checksum, derivation, recovery, addition, translation and fusion tables (tools/vectors/codex32-booklet/); the Codex32QR profile's sets (tools/vectors/codex32qr/).
Random cases secrets, splits (the same randomness), recovery, derived shares, corrupted strings; fresh sets of every threshold up to 31 strings at 48, 74 and 127 characters, the checksum worksheets of their strings and of corrupted ones, checksums made on a sheet, translation and recovery symbols, translation worksheets.
Differences Codex32: Faraday recovers only from exactly k shares without the secret, and derives a share only from exactly k strings at an unused index; the reference also takes more strings or a used index.
The codex32 seed sizes, which the references leave to their caller, are written in the area from the BIP's own sentence. Volvelle's sheet works the checksum itself, so a string of 48 or 74 characters whose checksum is not the one the sheet works is judged by that alone (holds false), not by its rows.
When it runs Before every release, with a new seed and about ten times the cases.
Last passing runSeed 5be11ec606a76d2767f225b8992c45fe · 10000 cases
GF(32) multiplication, the checksum's residue and the alphabet's lookup are written without a branch or a table index on a symbol's value, as the code documents; the code states no other timing.
The string, its payload and the seed are fixed arrays wiped on drop; a codex32 share record's string is a secret. A fresh set's share list is reserved at its full count before the first share is pushed, so no share is left in a block freed by a reallocation.
Limits
Seeds of 128, 160, 192, 224, 256 or 512 bits.
A threshold of 2 to 9, or 0 for the secret alone, and at most 31 strings.
A string that does not hold together, or whose checksum fails, is refused with the reason named.
A key of words is never split into codex32 strings.
Faraday's own calls
Recovery is from exactly k shares only. Conservative, F90.
The set's identifier is the first 20 bits of the master fingerprint, which puts 20 bits of it on every share. Neutral.
SpecificationBIP 93PublishedCodeFaraday's code: core/faraday-bipCross-checked withvolvelle-website's checksum worksheetOthers' codeFaraday's second version
Action
Fills the codex32 booklet's worksheets one character at a time and makes a fresh set or derived shares from them.
Faraday's code: core/faraday-bip: The checksum and translation worksheets are the booklet's tables as numbers, so every cell is shown as it is worked; a fresh set takes the person's characters as the data of the k initial shares and interpolates the secret and the other shares; faraday-keys lends a work set's rows and strings only as a paper form.
Checked against
tools/vectors/bip93
Published, by BIP 93's authors (bitcoin/bips).
tools/vectors/codex32-booklet
Published, by the codex32 booklet, by Blockstream (SSS32).
tools/vectors/codex32-volvelle
Computed by volvelle-website's checksum worksheet (apoelstra/volvelle-website), run as the folder's harness runs it.
no fuzz target: The characters are typed one at a time into worksheets that refuse a symbol outside the alphabet and a length that is not codex32's
Cross-check
Compared with others' code: volvelle-website's checksum worksheet, by Andrew Poelstra (the worksheets of 48 and 74 characters), and rust-codex32, by Andrew Poelstra (a fresh set's derived shares), beside python-codex32, by Ben Westgate.
Compared, for one part, with Faraday's second version, written by Faraday's authors in Python; that part is not checked against an outside source: the worksheet of 127 characters, which volvelle does not lay out, written in area_codex32.py from python-codex32's polymod.
Area codex32
Faraday's code faraday_bip::codex32
Compared with python-codex32 (codex32/); rust-codex32 at a pinned commit (rust-codex32/), a program outside the workspace: parsing, checksums, the threshold and a threshold of 0's share index, interpolate_at for a fresh set's shares; volvelle-website's checksum worksheet run as a program over every worksheet of 48 and 74 characters; the worksheet of 127 characters written in the area from python-codex32's polymod.
Checked first: Its vendored files are hashed against references.sha256 before any run (the Rust programs' sources included, built offline by run.sh with the toolchain on the PATH), and a published vector's answer is required of the reference as well as of Faraday; rust-codex32 and python-codex32 must give the same answer where both are asked; two rules BIP 93 states that neither enforces (the master seed's sizes, the order shares are handed out) are written in the area from the BIP's text, and the worksheet of 127 characters from BIP 93's polymod alone.
Vectors Every vector of tools/vectors/bip93/, the 55 invalid strings included; volvelle-website's worksheet cells (tools/vectors/codex32-volvelle/); the booklet's checksum, derivation, recovery, addition, translation and fusion tables (tools/vectors/codex32-booklet/); the Codex32QR profile's sets (tools/vectors/codex32qr/).
Random cases secrets, splits (the same randomness), recovery, derived shares, corrupted strings; fresh sets of every threshold up to 31 strings at 48, 74 and 127 characters, the checksum worksheets of their strings and of corrupted ones, checksums made on a sheet, translation and recovery symbols, translation worksheets.
Differences Codex32: Faraday recovers only from exactly k shares without the secret, and derives a share only from exactly k strings at an unused index; the reference also takes more strings or a used index.
The codex32 seed sizes, which the references leave to their caller, are written in the area from the BIP's own sentence. Volvelle's sheet works the checksum itself, so a string of 48 or 74 characters whose checksum is not the one the sheet works is judged by that alone (holds false), not by its rows.
When it runs Before every release, with a new seed and about ten times the cases.
Last passing runSeed 5be11ec606a76d2767f225b8992c45fe · 10000 cases
GF(32) multiplication, the checksum's residue and the alphabet's lookup are written without a branch or a table index on a symbol's value, as the code documents; the code states no other timing.
The work set's rows and strings are lent only for a paper form; the strings and the seed are wiped on drop.
Limits
A worksheet refuses a length that is not codex32's and a symbol outside the bech32 alphabet.
A scheme takes any threshold up to 9 and up to 31 strings.
The set is not made before every character is in.
Faraday's own calls
A further share is derived only from exactly k strings at an index not in use. Conservative, F90.
Faraday's code: core/faraday-bip: BIP 93 specifies no procedure; the decoder is written here after python-codex32's: up to 4 substituted boxes, up to 8 unreadable boxes, any mix with twice the substitutions plus the unreadable boxes at most 8, or one run of 9 to 13 unreadable boxes (15 on the long checksum); the proposal is parsed again before anything takes it.
Checked against
tools/vectors/codex32-correction
Published, by python-codex32's frozen correction corpus, by Ben Westgate.
Compared with others' code: python-codex32, by Ben Westgate (its correction.py).
Compared, for one part, with Faraday's second version, written by Faraday's authors in Python; that part is not checked against an outside source: the bound BIP 93 states (substitutions and unreadable boxes, one run up to the checksum's length) and a held string's fixed header, written in area_codex32_correct.py from the BIP's sentence.
Area codex32-correct
Faraday's code faraday_bip::codex32::correct
Compared with python-codex32's decoder, correction.py at a later commit (codex32/correction/), asked with BIP 93's bound.
Checked first: Its vendored files are hashed against references.sha256 before any run, and a published vector's answer is required of the reference as well as of Faraday; it is asked with the bound BIP 93 states, written in the area from that sentence and nothing else.
Random cases Random strings of every length with substitutions and unreadable boxes up to and past the bound, runs of unreadable boxes around the checksum's length, a held string's header fixed, upper case, ms1 damaged.
Differences Codex32 correction: python-codex32 reads a character outside the bech32 alphabet as unreadable, and fills more than 8 unreadable boxes that are not one run when its equations allow; Faraday refuses both (docs/CODEX32.md §8.4). The corpus damages strings with bech32 characters and ? only.
When it runs Before every release, with a new seed and about ten times the cases.
Last passing runSeed 5be11ec606a76d2767f225b8992c45fe · 100000 cases
GF(32) multiplication, the checksum's residue and the alphabet's lookup are written without a branch or a table index on a symbol's value, as the code documents; the code states no other timing.
The strings are fixed arrays wiped on drop.
Limits
ms1 and, where a string of the set is in, the threshold and identifier boxes are never changed.
Insertions, deletions and swapped boxes are not searched for.
A character outside the bech32 alphabet other than ? is refused, not read as unreadable.
More than 8 unreadable boxes that are not one run are refused.
Faraday's own calls
Correction is opt-in, off whenever the form opens, proposes only where the correction is unique, and is never applied: the person types the changed boxes again. Conservative, F94.
A character outside the bech32 alphabet is not read as an erasure, and more than 8 erasures not in one run are refused; BIP 93 makes the first optional, and python-codex32 accepts both. Conservative, F155.
Faraday's code: core/faraday-codec: One upper-case string in alphanumeric mode at level L, version 3, with the standard quiet zone, following the profile's pictures module for module.
Checked against
tools/vectors/codex32qr
Published, by the Codex32QR profile, in FractalEncrypt's SeedSigner fork.
no fuzz target: The encoder takes a string that Codex32::parse has already accepted; seed_parts fuzzes that reading
Cross-check
Compared with others' code: Project Nayuki's qrcodegen.py, by Nayuki, and segno, by Lars Heuer, and the pictures decoded by zbar, by the zbar developers, and zxing-cpp, by the zxing-cpp developers.
Area seedqr
Faraday's code faraday_codec::seedqr (SeedQR, CompactSeedQR), faraday_codec::qr, the encoder that draws them, and faraday_codec::qr::codex32qr with the picture faraday_core::picture writes of it
Compared with SeedSigner's own encoders and DecodeQR (seedsigner/, unchanged, with embit's BIP-39 code in embit/); Project Nayuki's qrcodegen.py (qrcodegen/), module for module; segno 1.6 (python3-segno), an encoder of another lineage, at Faraday's mask and at its own; Pillow and CPython's zlib, which read every PNG Faraday writes; zbar (zbarimg) and zxing-cpp, which decode the QR code in every picture and return its payload as bytes (qr_decode.py).
Checked first: Its vendored files are hashed against references.sha256 before any run, and a published vector's answer is required of the reference as well as of Faraday; SeedSigner's reader is looser than Faraday (it takes 49 digits, a sign inside a group, 20 to 28 bytes, and does not check the checksum of digits), so Faraday's own rule, the lengths and the digits, stands in front of it in area_seedqr.py and the checksum is embit's; SeedSigner runs in English for every language, the indices being the same; the profile's own pictures are read from their pixels and must be Faraday's code module for module; segno is asked for Faraday's version, level and mode and its mask forced, and its mask is read back from it, its padding quirk being modelled in Nayuki's code; rqrr reads Faraday's and segno's codes; the self-test makes each decoder's answer wrong (a payload's last byte changed) and must catch it.
An empty payload, which segno refuses.
Vectors SeedSigner's nine test SeedQRs (tools/vectors/seedqr/); every string and picture of the Codex32QR profile (tools/vectors/codex32qr/), each decoded by zbar and zxing-cpp.
Random cases Keys of every length and language, both codes and the words read back; digits and bytes malformed; payloads in each mode at each level and version limit; 48-character codex32 strings in either case as Codex32QR codes and the pictures written of them read back and decoded by zbar and zxing-cpp, other lengths refused; the pictures of a key's SeedQR and CompactSeedQR decoded by both and read by Faraday to the key's words; greyscale pictures and QR pictures of random size and scale read by Pillow and zlib.
Differences SeedQR digits: SeedSigner reads a string with 1 to 3 digits more than 48 or 96 (it drops the tail) and one with a sign or a space inside a group of four (int() takes them); Faraday refuses both (5 cases, each checked on both sides and counted). SeedSigner takes no CompactSeedQR of 20, 24 or 28 bytes either, and strips checksum bits for 12 and 24 words only; the corpus keeps Faraday's 15, 18 and 21 word compact form on the entropy itself.
Codex32QR: Faraday picks the mask Nayuki's encoder picks; the profile's encoder chose another for 6 of its 22 pictures. For those the area swaps the mask of Faraday's code for the picture's with qrcodegen.py's masking, requires the picture, and counts it.
Segno 1.6 writes a zero codeword where the pad codewords begin when the data, terminator included, ends on a codeword boundary with room left (its write_padding_bits adds 8 zero bits where none are due; ISO/IEC 18004 7.4.10 adds none): its code is Nayuki's with that codeword changed, which rqrr reads, counted as a known difference, the padding; Faraday's is the standard's.
Segno picks a mask by its own penalty rule, and for some payloads another than Nayuki's and Faraday's; the area requires that code to be Faraday's under the mask segno reports (Nayuki's masking swapped to it) and rqrr to read it, and counts each as a known difference, the mask choice, which a reader ignores.
When it runs Before every release, with a new seed and about ten times the cases.
Last passing runSeed 5be11ec606a76d2767f225b8992c45fe · 8000 cases
The matrix wipes on drop; the caller asks faraday-keys for the string.
Limits
A string of any length but 48 characters is refused; no profile is made up for the 74 and 127 character forms.
Faraday's own calls
No code is drawn for a 74 or 127 character string, and none is read but as plain text, until the profile's author publishes a profile for them. Conservative, F95.
SpecificationKEFPublishedCodeLibrary: aes 0.9Library: cbc 0.2Library: ctr 0.104 moreFaraday's code: faraday/faraday-kefFaraday's own codeCross-checked withKrux's kef.pyOthers' codeFaraday's second version
Action
Writes and reads a Krux encrypted code (KEF): a passphrase and a count of PBKDF2-HMAC-SHA-256 rounds over an id give an AES-256 key, and one of twelve versions (ECB, CBC, CTR or GCM, with or without compression) seals the bytes with the format's own check.
Specification
KEF, KEF, Krux's encrypted code, Convention
Code
Library: aes 0.9.3, by the RustCrypto developers.
Library: cbc 0.2.1, by the RustCrypto developers.
Library: ctr 0.10.1, by the RustCrypto developers.
Library: aes-gcm 0.11.1, by the RustCrypto developers.
Library: miniz_oxide 0.8.9 and 0.9.1, by the miniz_oxide developers, a port of Rich Geldreich's miniz.
Library: sha2 0.11.0, by the RustCrypto developers.
Library: hmac 0.13.0, by the RustCrypto developers, through core/faraday-crypto.
Faraday's code: faraday/faraday-kef: Only the part used is written: the twelve versions of Krux's table, their padding and their checks, the tolerant reading of Krux's own inconsistencies, and the refusal of what Krux refuses to write (a hidden check ending in 0x00). A compressed code inflates under a limit. The PBKDF2 loop can stop and counts; it is one 32-byte block, checked against the library's PBKDF2 and RFC 7914's vectors.
Written by Faraday
KEF: the envelope, the version table, padding, the two SHA-256 checks and base43 (faraday-codec::kef, faraday-kef), and PBKDF2's loop over HMAC-SHA-256 for one block, with a cancel check (faraday-crypto::hash) · Only the part used is written
No library reads or writes this format. The pbkdf2 crate is one call that cannot stop, and a count of 100 million rounds must be stoppable.
Published, by Krux's test data (tests/test_kef.py and tests/test_encryption.py of selfcustody/krux; the commit, licence and SHA-256 of each file are in the folder's README).
Compared with others' code: Krux's kef.py, by the Krux developers, vendored unchanged and run under CPython, for all twelve versions, written and read.
Compared, for one part, with Faraday's second version, written by Faraday's authors in Python; that part is not checked against an outside source: Faraday's refusals listed as known differences in area_kef.py (an empty plaintext, an id of 253 bytes, a text that inflates past the limit, a passphrase or count Krux's field does not offer, suggestions over 1,024 bytes), and krux's three shims (ucryptolib, uhashlib_hw and deflate at wbits -10, over hashlib, PyCA and zlib).
Compared with krux's kef.py (krux/, unchanged), by the krux developers, on three small shims for the firmware's AES, SHA-256 and PBKDF2, and deflate modules (PyCA cryptography's AES, hashlib, zlib at wbits -10).
Checked first: The vendored files are hashed against references.sha256 before any run; krux's own vectors (tools/vectors/kef/) are required of the reference as well as of Faraday; every plaintext Faraday seals is opened by krux's decrypt, and every plaintext krux seals by Faraday, to the plaintext that went in.
The text forms and the classifier (krux's kef.py holds neither), the Reveal variant and the worker; whether Faraday notes that the check passed only after putting NULs back; a key entered as hex that Faraday writes under (it refuses a passphrase that is not printable ASCII), so keys of raw bytes are compared only when Faraday opens.
Vectors krux's test data for versions 5, 15 and 20 (tools/vectors/kef/): a CTR code under key, a GCM code under test key at 100,000 rounds, and the version 5 code opened by abc and by a wrong passphrase that passes its 3-byte check.
Random cases Each of the twelve versions sealed by Faraday and by krux, byte for byte for the ten that do not compress and opened by the other for all twelve, over entropy of 16 and 32 bytes, short and long text, text up to 1,024 bytes, text ending in NUL, text whose hidden check ends in 0x00, repeated blocks, ids of 0, 8, 252 and random lengths, every edge of the count, and wrong IV lengths; codes under a passphrase at 10,000 to 30,000 rounds, one of 200 characters with an id of 252 bytes, and keys of raw bytes (to 200 bytes) krux seals and Faraday opens; codes from a writer that skipped the NUL rules, with 1 to 8 NULs at the end; envelopes cut or changed; the suggested versions for each mode at every length to 1,024.
Differences KEF: Faraday refuses an empty plaintext, a compressed version over 1,024 bytes, an id of 253 bytes or more when reading (krux's unwrap does not check it), a count over 550,000 and a passphrase that is not printable ASCII when it works out the key, and a stream that inflates to over 102,400 bytes; krux does none of these. Each is asked of krux and counted. Faraday does not suggest a compressed version over 1,024 bytes.
KEF: a stream that inflates to exactly 102,400 bytes is read by Faraday and refused by krux's firmware (its read is capped at the limit and raises when it is asked for more before the stream has ended); one of 102,401 bytes or more is refused by both. A stream whose matches reach back more than 1,024 bytes is read by Faraday (any window to 32 KiB) and refused by krux's 1,024-byte window; Faraday writes none.
KEF: Faraday's unwrap refuses at once a payload that holds nothing but the IV, the exposed check and the hidden check; krux's unwrap takes it apart and its decryption then fails. Both end in a code that does not open.
KEF: version 7 (ECB with deflate) is refused for a repeated block by the side whose compressor makes a stream with one; the stream of the other has none, and that side's code is opened by both.
KEF: the compressed versions are not equal byte for byte, as Faraday's deflate and zlib's write different streams. Each opens the other's; krux's decryption inflates under zlib at wbits -10.
When it runs Before every release, with a new seed and about ten times the cases.
Last passing runSeed 5be11ec606a76d2767f225b8992c45fe · 8200 cases
The GCM tag is compared in constant time by aes-gcm; the check bytes of the other versions are compared as Krux does; AES and PBKDF2 state nothing more.
The key, the passphrase bytes and the opened plaintext are Zeroizing values wiped on drop.
Limits
A written passphrase is printable ASCII of at most 200 characters; a read one is tried as typed, in NFC and in NFD.
A code that inflates past 100 KiB does not open.
A count over 550,000 is not written; PBKDF2 runs in steps of 5,000 rounds and stops when told.
Faraday's own calls
What Krux refuses to write is refused here, and a refusal names a version that works. Conservative, F219.
SpecificationSQLite file formatPublishedCodeFaraday's code: faraday/faraday-sqliteCross-checked withSQLite itselfOthers' codeFaraday's second version
Action
Reads a SQLite database file and never writes one: the header, the schema, the one table of two blob columns (key and value) of a Bitcoin Core wallet and its pages, with every file that is not whole refused. It is not cryptography.
Specification
SQLite file format, The SQLite database file format, Convention
Code
Faraday's code: faraday/faraday-sqlite: Only the part Bitcoin Core writes is read: the 100-byte header, table b-tree interior and leaf pages, overflow pages, varints and the record format, in the rollback-journal form. The write-ahead-log form, a header field SQLite does not allow, a page reached twice, a cell or overflow past its page or the file, a record whose header disagrees with its body, a column that is not a blob, a table other than the wanted one holding records and a tree deeper than 20 are refused.
Compared with others' code: SQLite itself, by the SQLite developers, through CPython's sqlite3, which makes each database and returns its rows.
Compared, for one part, with Faraday's second version, written by Faraday's authors in Python; that part is not checked against an outside source: Faraday's refusals asked of Faraday alone in area_sqlite.py (the write-ahead-log form, auto-vacuum and UTF-16 databases, which SQLite reads).
Compared with SQLite itself, through CPython's sqlite3 module (the version is printed at the start of the area), by the SQLite developers.
Checked first: The rows SQLite returns for the bytes are the answer, with the table names of sqlite_schema; the databases are made by SQLite, and the cases that SQLite reads and Faraday refuses are asked of Faraday alone.
none; index pages are not read by Faraday and the rows are SQLite's answer.
Vectors none; the reader's tests read databases SQLite made (faraday/faraday-sqlite/tests/).
Random cases Random one-table databases at each page size from 512 to 65,536, with blobs from empty to several pages (overflow chains of every length), several transactions with rows deleted between them, and a second table in some; the same with one byte changed.
Differences SQLite reads the write-ahead-log form, auto-vacuum databases and UTF-16 databases, and a database with a table of any shape; Faraday reads the rollback-journal form with UTF-8 text and a table of two blob columns only, and refuses the rest. Each is asked of Faraday and counted.
SQLite parses the CREATE statements of the schema and refuses a database whose text is not valid SQL; Faraday reads a table's name and root page from its schema row and does not parse the statement. A changed byte in the schema page that SQLite refuses as a malformed schema, and Faraday reads, is not a mismatch.
When it runs Before every release, with a new seed and about ten times the cases.
Last passing runSeed 5be11ec606a76d2767f225b8992c45fe · 8000 cases
The reader holds no secrets: it reads the bytes it is given and keeps none.
Limits
A file over 1 GiB, a page size outside 512 to 65,536, a tree deeper than 20 and a database in the write-ahead-log, auto-vacuum or UTF-16 form are refused.
Only the table b-tree is read: an index's pages are not, and not checked against the others.
Faraday's own calls
Whatever the reader does not follow is refused, and a page reached twice is refused. Conservative, F229.
SpecificationSLIP-0039PublishedCodeLibrary: hmac 0.13 (through core/faraday-crypto)Library: sha2 0.11 (through core/faraday-crypto)Faraday's code: core/faraday-bipFaraday's own codeCross-checked withpython-shamir-mnemonicOthers' codeFaraday's second version
Action
Splits a master secret into SLIP-39 shares and recovers it from them, with the passphrase's Feistel encryption.
Specification
SLIP-0039, Shamir's Secret-Sharing for Mnemonic Codes, Status not checked, vendored
Code
Library: hmac 0.13.0, by the RustCrypto developers, through core/faraday-crypto.
Library: sha2 0.11.0, by the RustCrypto developers, through core/faraday-crypto.
Faraday's code: core/faraday-bip: Written here over faraday-crypto's HMAC-SHA256 and PBKDF2-HMAC-SHA256: the RS1024 checksum, Shamir over GF(256), the digest share and the Feistel cipher. The recovered master secret is the BIP 32 seed, not BIP 39 entropy. New key's split takes the shares' identifier and the split's randomness from the session's randomness, each 32 bytes from an answer of the system's of its own; the identifier is 15 bits of the first two bytes.
Written by Faraday
SLIP-39 Shamir backup (faraday-bip::slip39) · No established implementation exists
No maintained Rust implementation of SLIP-39 exists.
Compared with others' code: python-shamir-mnemonic, by Trezor (SatoshiLabs), and bip39_slip39, by the btclib developers (shares read and combined, secrets split under the same random bytes, the passphrase cipher, recover_ems, split_ems and _interpolate).
Compared, for one part, with Faraday's second version, written by Faraday's authors in Python; that part is not checked against an outside source: Faraday's refusals of a new member in derive_refused (area_slip39.py), written in front of the references, which have no function for them: shares of more than one group, an index outside 0 to 15, a group of threshold 1, a count other than the threshold, a repeated index, an index among the shares given; the refused lengths of the fixed 1 of 1; the identifier rules one_of_one_identifier and codex32_identifier, which the libraries take as a parameter.
Area slip39
Faraday's code faraday_bip::slip39
Compared with python-shamir-mnemonic (slip39/), its recover_ems, split_ems and _interpolate for a set's EMS, a new split of it and a member at an index; bip39_slip39 (bip39-slip39/) answering each SLIP-39 operation beside it (not the two codex32 operations); python-codex32 (codex32/) for the codex32 side of the conversions and btclib (bip32_ref.py) for the fingerprint; the refusals of a member at an index before the arithmetic are ours (derive_refused), and so are the lengths the fixed 1 of 1 refuses, which no second judge covers.
Checked first: Its vendored files are hashed against references.sha256 before any run, and a published vector's answer is required of the reference as well as of Faraday, and of bip39_slip39 too; all 45 of its own vectors are run.
Vectors All 45 of tools/vectors/slip39/, each again through its EMS and its decryption.
Random cases Splits fed the same random bytes, which must match word for word; recovery from qualifying and short subsets and a changed word; the passphrase cipher; a set's EMS from a quorum, refused from a short or changed set, split again on the same random bytes (some under a new identifier where extendable) and a member added or a lost one made again at an index, each recovering the first set's secret, and a member refused at an index given, past 15, from a short quorum and across two groups; random seeds of 16 and 32 bytes through the fixed 1 of 1 against both libraries under the fingerprint's first 15 bits, recovered through both, and the lengths it refuses, against Faraday's own rule; the seed written as codex32 by Faraday and read by python-codex32, and a SLIP-39 set with a passphrase recovered by Faraday and by python-shamir-mnemonic, written as codex32 by Faraday and by python-codex32, the second read by Faraday, the same bytes both ways, the identifier's 20 bits written and the fingerprint (btclib's) compared on both sides.
Differences SLIP-39: Faraday refuses a group threshold of 1 over several groups; python-shamir-mnemonic makes the shares. The area checks that this still holds, so a change either way is seen.
When it runs Before every release, with a new seed and about ten times the cases.
Last passing runSeed 5be11ec606a76d2767f225b8992c45fe · 21000 cases
The GF(256) arithmetic of the shares and the RS1024 checksum are written without a table indexed by a share's bytes or a branch on them, as the code documents; a word is found by comparing its first four letters with every entry of the list in constant time (subtle), the rest of the word with the entry found, masked; the digest is compared in constant time (subtle's ConstantTimeEq); the code states no other timing.
The master secret is a Secret; the share values and points wipe on drop.
Limits
Secrets of 16 to 32 bytes of even length.
An iteration exponent above 5 is refused before any PBKDF2 round.
A group threshold of 1 over several groups is refused when splitting.
A wrong passphrase opens a different wallet: the passphrase is not a check.
Faraday's own calls
Shares with an iteration exponent above 5 are refused; a split writes exponent 1 with the extendable flag set. Conservative, F90.
A split with a group threshold of 1 over several groups is refused. Conservative, F90.
Secrets above 256 bits are refused. Conservative, F155.
The split's randomness is taken from the session's randomness, an answer for every 32 bytes; SLIP-0039 does not say where a split's randomness comes from. Neutral, F154.
SpecificationSeed XOR · BIP 39PublishedCodeLibrary: sha2 0.11 (through core/faraday-crypto)Library: unicode-normalization 0.1 (through core/faraday-bip)Faraday's code: core/faraday-entropyFaraday's own codeCross-checked withColdcard's xor and xor_splitOthers' codeFaraday's second version
Action
Splits a seed into Seed XOR parts, each a BIP 39 mnemonic, and combines parts into the seed.
Specification
Seed XOR, Seed XOR, Coldcard's split of a seed into parts, Convention, vendored
BIP 39, Mnemonic code for generating deterministic keys, Deployed
Code
Library: sha2 0.11.0, by the RustCrypto developers, through core/faraday-crypto.
Library: unicode-normalization 0.1.25, by the unicode-rs developers, through core/faraday-bip.
Faraday's code: core/faraday-entropy: The bitwise XOR of the parts' entropy; the random parts are taken in turn, the seed's length each, from 32 fresh bytes for each random part; every part is a valid mnemonic of the same word count.
Written by Faraday
Seed XOR (faraday-entropy::xor) · Only the part used is written
Faraday writes only the few lines the standard needs, over standard XOR.
Published, by Coldcard's docs/seed-xor.md, by Coinkite. Faraday's own known answers: the two-part and three-part files, made from the definition of Seed XOR.
no fuzz target: The parts are BIP 39 mnemonics read by the BIP 39 reader before they combine; bip39_words fuzzes that
Cross-check
Compared with others' code: Coldcard's xor and xor_split, by Coinkite, over python-mnemonic, by Trezor (SatoshiLabs).
Compared, for one part, with Faraday's second version, written by Faraday's authors in Python; that part is not checked against an outside source: the count of parts (2 to 4) and the five BIP-39 lengths, Faraday's rule written in area_xor.py in front of Coldcard's xor, which asserts only equal lengths.
Area xor
Faraday's code faraday_entropy::SeedXor with faraday_bip::bip39
Compared with Coldcard's own xor and xor_split (coldcard/, unchanged) with python-mnemonic (bip39/) for the words.
Checked first: Its vendored files are hashed against references.sha256 before any run, and a published vector's answer is required of the reference as well as of Faraday; the count of parts (2 to 4) and the five BIP-39 lengths are Faraday's rule, written in the area in front of Coldcard's xor, which asserts only equal lengths.
Vectors Coldcard's two examples (tools/vectors/xor/coldcard.json) and this tree's two.
Random cases Splits and combines in all ten languages and five lengths, with refusals; parts made by Coldcard's xor_split read back to their seed.
Differences None known.
When it runs Before every release, with a new seed and about ten times the cases.
Last passing runSeed 5be11ec606a76d2767f225b8992c45fe · 40000 cases
Makes the file a backup stick holds for a key: its words or passphrase as one line, its SeedQR as a labelled picture, a codex32 string as one line or as a Codex32QR picture.
Specification
BIP 39, Mnemonic code for generating deterministic keys, Deployed
SeedQR, SeedQR and CompactSeedQR, Convention, vendored
Faraday's code: faraday/faraday-core: Each secret is lent by faraday-keys for the reason BackupStick, which names the part (words, passphrase, SeedQR or codex32), and written into a zeroizing buffer; the words and the passphrase are one line each; the SeedQR is made by the SeedQR encoder and drawn as a labelled picture.
Written by Faraday
FAT16 and FAT32, read and written (faraday-fat) · No established implementation exists
No FAT library comes from a publisher Faraday's dependency review trusts.
no fuzz target: Takes a held key and a form; no outside input is parsed
Cross-check
Compared with others' code: zbar, by the zbar developers, and zxing-cpp, by the zxing-cpp developers, which decode each picture this writes and whose payload is compared with the key's words.
Area seedqr
Faraday's code faraday_codec::seedqr (SeedQR, CompactSeedQR), faraday_codec::qr, the encoder that draws them, and faraday_codec::qr::codex32qr with the picture faraday_core::picture writes of it
Compared with SeedSigner's own encoders and DecodeQR (seedsigner/, unchanged, with embit's BIP-39 code in embit/); Project Nayuki's qrcodegen.py (qrcodegen/), module for module; segno 1.6 (python3-segno), an encoder of another lineage, at Faraday's mask and at its own; Pillow and CPython's zlib, which read every PNG Faraday writes; zbar (zbarimg) and zxing-cpp, which decode the QR code in every picture and return its payload as bytes (qr_decode.py).
Checked first: Its vendored files are hashed against references.sha256 before any run, and a published vector's answer is required of the reference as well as of Faraday; SeedSigner's reader is looser than Faraday (it takes 49 digits, a sign inside a group, 20 to 28 bytes, and does not check the checksum of digits), so Faraday's own rule, the lengths and the digits, stands in front of it in area_seedqr.py and the checksum is embit's; SeedSigner runs in English for every language, the indices being the same; the profile's own pictures are read from their pixels and must be Faraday's code module for module; segno is asked for Faraday's version, level and mode and its mask forced, and its mask is read back from it, its padding quirk being modelled in Nayuki's code; rqrr reads Faraday's and segno's codes; the self-test makes each decoder's answer wrong (a payload's last byte changed) and must catch it.
An empty payload, which segno refuses.
Vectors SeedSigner's nine test SeedQRs (tools/vectors/seedqr/); every string and picture of the Codex32QR profile (tools/vectors/codex32qr/), each decoded by zbar and zxing-cpp.
Random cases Keys of every length and language, both codes and the words read back; digits and bytes malformed; payloads in each mode at each level and version limit; 48-character codex32 strings in either case as Codex32QR codes and the pictures written of them read back and decoded by zbar and zxing-cpp, other lengths refused; the pictures of a key's SeedQR and CompactSeedQR decoded by both and read by Faraday to the key's words; greyscale pictures and QR pictures of random size and scale read by Pillow and zlib.
Differences SeedQR digits: SeedSigner reads a string with 1 to 3 digits more than 48 or 96 (it drops the tail) and one with a sign or a space inside a group of four (int() takes them); Faraday refuses both (5 cases, each checked on both sides and counted). SeedSigner takes no CompactSeedQR of 20, 24 or 28 bytes either, and strips checksum bits for 12 and 24 words only; the corpus keeps Faraday's 15, 18 and 21 word compact form on the entropy itself.
Codex32QR: Faraday picks the mask Nayuki's encoder picks; the profile's encoder chose another for 6 of its 22 pictures. For those the area swaps the mask of Faraday's code for the picture's with qrcodegen.py's masking, requires the picture, and counts it.
Segno 1.6 writes a zero codeword where the pad codewords begin when the data, terminator included, ends on a codeword boundary with room left (its write_padding_bits adds 8 zero bits where none are due; ISO/IEC 18004 7.4.10 adds none): its code is Nayuki's with that codeword changed, which rqrr reads, counted as a known difference, the padding; Faraday's is the standard's.
Segno picks a mask by its own penalty rule, and for some payloads another than Nayuki's and Faraday's; the area requires that code to be Faraday's under the mask segno reports (Nayuki's masking swapped to it) and rqrr to read it, and counts each as a known difference, the mask choice, which a reader ignores.
When it runs Before every release, with a new seed and about ten times the cases.
Last passing runSeed 5be11ec606a76d2767f225b8992c45fe · 8000 cases
Makes a key's words file and its SeedQR picture, standard or compact, for the secret sheet to save to the Outbox unprotected.
Specification
BIP 39, Mnemonic code for generating deterministic keys, Deployed
SeedQR, SeedQR and CompactSeedQR, Convention, vendored
Code
Faraday's code: faraday/faraday-core: The words are lent by faraday-keys for the reason OutboxFile and written as one line, as Add a key and other signers read them; a SeedQR picture is added for English words only, and only where the plan copies the seed as a SeedQR, titled with the key's fingerprint; the sheet's warning differs for a wallet that needs more than one key, and says how many more keys whoever holds the file needs.
no fuzz target: Takes a held key and a form; no outside input is parsed
Cross-check
Compared with others' code: zbar, by the zbar developers, and zxing-cpp, by the zxing-cpp developers, which decode the picture this writes and whose payload is compared with the key's words.
Area seedqr
Faraday's code faraday_codec::seedqr (SeedQR, CompactSeedQR), faraday_codec::qr, the encoder that draws them, and faraday_codec::qr::codex32qr with the picture faraday_core::picture writes of it
Compared with SeedSigner's own encoders and DecodeQR (seedsigner/, unchanged, with embit's BIP-39 code in embit/); Project Nayuki's qrcodegen.py (qrcodegen/), module for module; segno 1.6 (python3-segno), an encoder of another lineage, at Faraday's mask and at its own; Pillow and CPython's zlib, which read every PNG Faraday writes; zbar (zbarimg) and zxing-cpp, which decode the QR code in every picture and return its payload as bytes (qr_decode.py).
Checked first: Its vendored files are hashed against references.sha256 before any run, and a published vector's answer is required of the reference as well as of Faraday; SeedSigner's reader is looser than Faraday (it takes 49 digits, a sign inside a group, 20 to 28 bytes, and does not check the checksum of digits), so Faraday's own rule, the lengths and the digits, stands in front of it in area_seedqr.py and the checksum is embit's; SeedSigner runs in English for every language, the indices being the same; the profile's own pictures are read from their pixels and must be Faraday's code module for module; segno is asked for Faraday's version, level and mode and its mask forced, and its mask is read back from it, its padding quirk being modelled in Nayuki's code; rqrr reads Faraday's and segno's codes; the self-test makes each decoder's answer wrong (a payload's last byte changed) and must catch it.
An empty payload, which segno refuses.
Vectors SeedSigner's nine test SeedQRs (tools/vectors/seedqr/); every string and picture of the Codex32QR profile (tools/vectors/codex32qr/), each decoded by zbar and zxing-cpp.
Random cases Keys of every length and language, both codes and the words read back; digits and bytes malformed; payloads in each mode at each level and version limit; 48-character codex32 strings in either case as Codex32QR codes and the pictures written of them read back and decoded by zbar and zxing-cpp, other lengths refused; the pictures of a key's SeedQR and CompactSeedQR decoded by both and read by Faraday to the key's words; greyscale pictures and QR pictures of random size and scale read by Pillow and zlib.
Differences SeedQR digits: SeedSigner reads a string with 1 to 3 digits more than 48 or 96 (it drops the tail) and one with a sign or a space inside a group of four (int() takes them); Faraday refuses both (5 cases, each checked on both sides and counted). SeedSigner takes no CompactSeedQR of 20, 24 or 28 bytes either, and strips checksum bits for 12 and 24 words only; the corpus keeps Faraday's 15, 18 and 21 word compact form on the entropy itself.
Codex32QR: Faraday picks the mask Nayuki's encoder picks; the profile's encoder chose another for 6 of its 22 pictures. For those the area swaps the mask of Faraday's code for the picture's with qrcodegen.py's masking, requires the picture, and counts it.
Segno 1.6 writes a zero codeword where the pad codewords begin when the data, terminator included, ends on a codeword boundary with room left (its write_padding_bits adds 8 zero bits where none are due; ISO/IEC 18004 7.4.10 adds none): its code is Nayuki's with that codeword changed, which rqrr reads, counted as a known difference, the padding; Faraday's is the standard's.
Segno picks a mask by its own penalty rule, and for some payloads another than Nayuki's and Faraday's; the area requires that code to be Faraday's under the mask segno reports (Nayuki's masking swapped to it) and rqrr to read it, and counts each as a known difference, the mask choice, which a reader ignores.
When it runs Before every release, with a new seed and about ten times the cases.
Last passing runSeed 5be11ec606a76d2767f225b8992c45fe · 8000 cases
Library: bitcoin 0.32.102, by the rust-bitcoin developers.
Library: sha2 0.11.0, by the RustCrypto developers, through core/faraday-crypto.
Library: unicode-normalization 0.1.25, by the unicode-rs developers, through core/faraday-bip.
Faraday's code: faraday/faraday-core: A words file is read in whichever BIP 39 word list it is in, checksum included; SLIP-39 shares and codex32 strings are gathered from their files and the codex32 seed is recovered from them. The fingerprint is that of the master key, with the passphrase a passphrase file or the person brings, and is kept by a memo keyed by SHA-256 of a tag and the secret, so the secret is kept nowhere. Pasted text is refused when it is words of any list, checksum or not, a SeedQR's 48 or 96 digits, an extended private key, a WIF key, a codex32 string or a SLIP-39 share; a scanner that loads a seed refuses only a private key.
no fuzz target: No fuzz target reads a file as a seed; the readers it calls (words, codex32 and SLIP-39 strings) have their own
Cross-check
not cross-checked: The key a seed makes is checked by the bip39, bip32, codex32 and slip39 areas; the recognising of files and pasted text has no second implementation
11 actions · 4 with Faraday's own code · 11 cross-checked with others' code · 4 with Faraday's second version
ActionSpecificationCodeCross-checked with
Hash and authenticate bytes
SpecificationFIPS 180-4 · RFC 2104 · RFC 4231 · 2 morePublishedCodeLibrary: sha2 0.11Library: hmac 0.13Library: pbkdf2 0.13Faraday's code: core/faraday-cryptoCross-checked withPython's hmac and hashlib.pbkdf2_hmac (OpenSSL) for HMAC and PBKDF2Others' code
Action
Hashes and authenticates bytes with SHA-256, HMAC-SHA256 and HMAC-SHA512, and stretches a password with PBKDF2.
Specification
FIPS 180-4, Secure Hash Standard, Status not checked
RFC 2104, HMAC: Keyed-Hashing for Message Authentication, Status not checked
RFC 4231, Identifiers and Test Vectors for HMAC-SHA-224, HMAC-SHA-256, HMAC-SHA-384, and HMAC-SHA-512, Status not checked
RFC 8018, PKCS #5: Password-Based Cryptography Specification Version 2.1, Status not checked
RFC 7914, The scrypt Password-Based Key Derivation Function, Status not checked
Code
Library: sha2 0.11.0, by the RustCrypto developers.
Library: hmac 0.13.0, by the RustCrypto developers.
Library: pbkdf2 0.13.0, by the RustCrypto developers.
Faraday's code: core/faraday-crypto: Thin wrappers, the one entry point the rest of the core uses, so the choice of crate is confined here; any HMAC key length is accepted; the whole-file SHA-256 and the key-stretching calls count themselves on the compute token. The bip39 area reaches SHA-256 and PBKDF2-HMAC-SHA512 only; HMAC-SHA256 and PBKDF2-HMAC-SHA256 are checked by their RFCs' cases here.
no fuzz target: Takes bytes from callers that parse their own input
Cross-check
Compared with others' code: Python's hmac and hashlib.pbkdf2_hmac (OpenSSL) for HMAC and PBKDF2, each over SHA-256 and SHA-512, in area hash.
Area hash
Faraday's code faraday_bip::hashes and faraday_codec::encodings (read, the writers and from_hex), faraday_core::file_menu::sha256, and faraday_crypto::hkdf_sha256 and hkdf_sha256_expand, hmac_sha256, hmac_sha512, pbkdf2_hmac_sha256, pbkdf2_hmac_sha512 and scrypt
Compared with Bitcoin Core v31.1's functional-test framework (core/): ripemd160.py, address.py and segwit_addr.py, with hashlib for SHA-256 and bytes.fromhex for hex; PyCA cryptography's HKDF and HKDFExpand (OpenSSL) for the one HKDF; hmac, hashlib.pbkdf2_hmac and hashlib.scrypt (OpenSSL) for HMAC, PBKDF2 and scrypt.
Checked first: Its vendored files are hashed against references.sha256 before any run, and a published vector's answer is required of the reference as well as of Faraday; the order read tries the spellings in, the trimming of the text, hex as an even number of hex digits, plain Base58 (which Core's framework does not read; the area's own few lines) and which prefixes make a segwit address are Faraday's rules, written in the area in front of the reference.
The file hash is file_menu::sha256 over a whole byte slice (it reads in no buffer, so no read size is probed); the Files screen's reading of a file from a stick is the files areas'.
Vectors FIPS 180-4's SHA-256 examples, RIPEMD-160 of abc, BIP-173's key and its HASH160, Bitcoin Core's first key_io_valid.json address, BIP-173's and BIP-350's bech32 strings and their valid and invalid segwit addresses (tools/vectors/addresses).
Random cases Random bytes of every length from 0 to 130 and to 300 hashed (SHA-256, SHA-256d, HASH160) and as a file, files of 4 KiB, 64 KiB and 1 MiB with a byte more and less; random bytes written and read as Base58Check, Base58, bech32 and bech32m, Core's writing read by Faraday, segwit addresses of every version Core's framework writes, and texts changed, cut or made of random characters read by both.
Differences bech32 groups: a string that is not a segwit address of bc, tb or bcrt is read as bytes, all its data groups together, and the bits that do not fill a byte are dropped. BIP-173 has a padding rule only for a segwit address, so Core's convertbits, which applies it to any data, refuses some of these strings, and the area reads them as Faraday does.
bech32 length: Core's decoder refuses more than 90 characters (BIP-173); Faraday accepts any length the checksum covers. The area reads longer strings the same way.
When it runs Before every release, with a new seed and about ten times the cases.
Last passing runSeed 5be11ec606a76d2767f225b8992c45fe · 30000 cases
Hashes bytes with SHA-256, SHA-256d and HASH160, and reads and writes Base58Check, bech32 and bech32m text.
Specification
FIPS 180-4, Secure Hash Standard, Status not checked
BIP 173, Base32 address format for native v0-16 witness outputs, Deployed
BIP 350, Bech32m Format for v1+ Witness Addresses, Deployed
BIP 380, Output Script Descriptors General Operation, Deployed
Base58Check, Base58Check encoding, as Bitcoin Core writes it, Convention
Code
Library: bitcoin 0.32.102, by the rust-bitcoin developers.
Library: sha2 0.11.0, by the RustCrypto developers, through core/faraday-crypto.
Library: base16ct 1.0.0, by the RustCrypto developers, through core/faraday-crypto.
Faraday's code: core/faraday-bip: The calculator shows the three hashes of any bytes, says which of Base58, Base58Check, bech32, bech32m or hex a text is, reads a segwit address as its witness version and program, and writes the same bytes in the other spellings.
Checked against
tools/vectors/addresses
Published, by the authors of BIP 173, BIP 350, BIP 380, BIP 49, BIP 84 and BIP 86 (bitcoin/bips).
Compared with others' code: Bitcoin Core v31.1's functional-test framework, by Bitcoin Core's contributors (ripemd160.py for HASH160, address.py for Base58Check, segwit_addr.py for bech32 and bech32m), and Python's hashlib (SHA-256 and SHA-256d) and bytes.fromhex (hex).
Compared, for one part, with Faraday's second version, written by Faraday's authors in Python; that part is not checked against an outside source: plain Base58 with no checksum, which the framework does not read, the order the spellings are tried in, the trimming of the text, hex as an even number of hex digits only, and which prefixes make a segwit address, in area_hash.py; bech32 text that is not a segwit address is read as all its data groups at any length by Faraday and by the area alike, a stated difference.
Area hash
Faraday's code faraday_bip::hashes and faraday_codec::encodings (read, the writers and from_hex), faraday_core::file_menu::sha256, and faraday_crypto::hkdf_sha256 and hkdf_sha256_expand, hmac_sha256, hmac_sha512, pbkdf2_hmac_sha256, pbkdf2_hmac_sha512 and scrypt
Compared with Bitcoin Core v31.1's functional-test framework (core/): ripemd160.py, address.py and segwit_addr.py, with hashlib for SHA-256 and bytes.fromhex for hex; PyCA cryptography's HKDF and HKDFExpand (OpenSSL) for the one HKDF; hmac, hashlib.pbkdf2_hmac and hashlib.scrypt (OpenSSL) for HMAC, PBKDF2 and scrypt.
Checked first: Its vendored files are hashed against references.sha256 before any run, and a published vector's answer is required of the reference as well as of Faraday; the order read tries the spellings in, the trimming of the text, hex as an even number of hex digits, plain Base58 (which Core's framework does not read; the area's own few lines) and which prefixes make a segwit address are Faraday's rules, written in the area in front of the reference.
The file hash is file_menu::sha256 over a whole byte slice (it reads in no buffer, so no read size is probed); the Files screen's reading of a file from a stick is the files areas'.
Vectors FIPS 180-4's SHA-256 examples, RIPEMD-160 of abc, BIP-173's key and its HASH160, Bitcoin Core's first key_io_valid.json address, BIP-173's and BIP-350's bech32 strings and their valid and invalid segwit addresses (tools/vectors/addresses).
Random cases Random bytes of every length from 0 to 130 and to 300 hashed (SHA-256, SHA-256d, HASH160) and as a file, files of 4 KiB, 64 KiB and 1 MiB with a byte more and less; random bytes written and read as Base58Check, Base58, bech32 and bech32m, Core's writing read by Faraday, segwit addresses of every version Core's framework writes, and texts changed, cut or made of random characters read by both.
Differences bech32 groups: a string that is not a segwit address of bc, tb or bcrt is read as bytes, all its data groups together, and the bits that do not fill a byte are dropped. BIP-173 has a padding rule only for a segwit address, so Core's convertbits, which applies it to any data, refuses some of these strings, and the area reads them as Faraday does.
bech32 length: Core's decoder refuses more than 90 characters (BIP-173); Faraday accepts any length the checksum covers. The area reads longer strings the same way.
When it runs Before every release, with a new seed and about ten times the cases.
Last passing runSeed 5be11ec606a76d2767f225b8992c45fe · 30000 cases
Derives a BIP 85 child (words, a WIF, an extended private key, hex or a password) from a held key.
Specification
BIP 85, Deterministic Entropy From BIP32 Keychains, Deployed, vendored
RFC 4648, The Base16, Base32, and Base64 Data Encodings, Status not checked
RFC 1924, A Compact Representation of IPv6 Addresses (base 85 alphabet), Status not checked
Code
Library: bitcoin 0.32.102, by the rust-bitcoin developers.
Library: base64ct 1.8.3, by the RustCrypto developers.
Library: hmac 0.13.0, by the RustCrypto developers, through core/faraday-crypto.
Library: sha2 0.11.0, by the RustCrypto developers, through core/faraday-crypto.
Library: base16ct 1.0.0, by the RustCrypto developers, through core/faraday-crypto.
Faraday's code: core/faraday-bip: The path is m/83696968'/app'/params'/index', fully hardened; the derived private key is run through HMAC-SHA512 with the BIP's key; the passwords' base64 (RFC 4648) is the base64ct crate's and their base85 (RFC 1924's alphabet) is written here; every value is a fixed-size buffer that zeroizes on drop and nothing here allocates.
no fuzz target: Takes a held key, an application and numbers chosen on a pad; no text is parsed
Cross-check
Compared with others' code: btclib-wallet's bip85, by the btclib developers, on btclib's own curve and run as written over bip39_slip39, by the btclib developers; ethankosakovsky/bip85, by Ethan Kosakovsky, over python-mnemonic, by Trezor (SatoshiLabs), and btclib through a pycoin shim.
Area bip85
Faraday's code faraday_bip::bip85
Compared with btclib-wallet's bip85 (btclib/, on btclib's own curve) run as written over bip39_slip39 (bip39-slip39/); and ethankosakovsky/bip85 over python-mnemonic and a pycoin shim whose every call is btclib's (bip85/, bip39/).
Checked first: Their vendored files and wheels are hashed against references.sha256 before any run, and a published vector's answer is required of each reference as well as of Faraday.
The BIP's reference is not asked the passwords, which it does not have, nor hex bytes of a length outside the BIP's range, which it does not refuse: btclib alone answers those.
Vectors Every application vector of tools/vectors/bip85/.
Random cases Random master keys, indices, languages, word counts and lengths, with refusals.
Differences None known.
When it runs Before every release, with a new seed and about ten times the cases.
Last passing runSeed 5be11ec606a76d2767f225b8992c45fe · 30000 cases
The password's base64 is the base64ct crate's, which documents its encoding as constant time with respect to the data; its base85 is shown (§4.10).
The derived private key and the 64 bytes are zeroized before the function returns, and every value returned is a buffer that zeroizes on drop. The copies bitcoin makes inside derivation are freed unwiped, until the next lock (ESTABLISHED §4.8).
Limits
Applications 2', 32', 39', 128169', 707764' and 707785' only; no DICE, RSA or Nostr 128002'.
Hex is 16 to 64 bytes, a base64 password 20 to 86 characters, a base85 password 10 to 80.
An index of 2^31 or more is refused.
Faraday's own calls
Nostr keys by application 128002' are not built. Neutral, F27.
Library: bitcoin 0.32.102, by the rust-bitcoin developers.
Library: secp256k1 0.29.1, by the rust-bitcoin developers (rust-secp256k1), over libsecp256k1, by Bitcoin Core's libsecp256k1 project (bitcoin-core/secp256k1).
Faraday's code: core/faraday-bip: Nothing is random: the counter is written in EntropyLab's alphabet and odometer order, width by width, so a find here is the same find there; one passphrase candidate costs one PBKDF2, one account candidate one hardened derivation.
no fuzz target: Takes a prefix typed on a pad and a held key; no outside text is parsed
Cross-check
Compared with others' code: python-mnemonic, by Trezor (SatoshiLabs), Bitcoin Core v31.1 (deriveaddresses), by the Bitcoin Core developers, and btclib, by the btclib developers, which derives each candidate's child keys on its own curve (Core judges the script and the address text only, and shares libsecp256k1's curve maths with Faraday's).
Compared, for one part, with Faraday's second version, written by Faraday's authors in Python; that part is not checked against an outside source: EntropyLab's counter, the prefix rules, the expected work and the search loop, written out in area_vanity.py from a quotation.
Area vanity
Faraday's code faraday_bip::vanity (the counter, prefixes and their expected work, the search on both dials, for the four script types and a silent payment code)
Compared with EntropyLab's counter as tools/reference/vanity/README.md quotes it, written out in area_vanity.py over python-mnemonic, each candidate's child key derived by btclib on its own curve, and its address by Bitcoin Core v31.1 for the script and address text only (deriveaddresses on regtest, from the bare key) and Core's framework, as the addr area writes it; a silent payment code by the BIP-352 reference's own bech32m from btclib's keys at BIP-352's paths.
Checked first: The search is written in the area from the README's quotation of EntropyLab's counter, and EntropyLab's two finds are required of it as well as of Faraday.
Vectors EntropyLab's two finds.
Random cases Counters at every width's edges; prefixes of every kind on every network, valid and not; searches of random keys on both dials from random starting counters, with budgets ending before a match and after.
Differences Each candidate's child key is derived by btclib on its own curve, not by Bitcoin Core, which shares libsecp256k1's curve maths with Faraday; Core is given the bare key and judges the script and the address text only.
When it runs Before every release, with a new seed and about ten times the cases.
Last passing runSeed 5be11ec606a76d2767f225b8992c45fe · 2000 cases
Reads an LND aezeed: 24 words, checksum, scrypt key and AEZ decipher, giving the entropy, version and birthday; a scanner tells one apart by its version and checksum alone.
Specification
LND aezeed, LND cipher seed (aezeed) with AEZ v5, Convention
RFC 7914, The scrypt Password-Based Key Derivation Function, Status not checked
Code
Library: aes 0.9.3, by the RustCrypto developers.
Library: blake2 0.11.0, by the RustCrypto developers, through core/faraday-crypto.
Faraday's code: core/faraday-bip: AEZ v5 is written here, over the aes crate's AES round; the words are 24 x 11 bits with a CRC-32C checked before scrypt (N 32768, r 8, p 1) runs; reading only: an aezeed is never made, and never loaded as a key.
Written by Faraday
AEZ v5 and aezeed, with aezeed's CRC-32C (faraday-bip::aez, faraday-bip::aezeed) · No established implementation exists
No maintained Rust implementation of AEZ exists; Faraday's follows the Go code LND uses and is tested against LND's vectors. Its AES round is the aes crate's and its BLAKE2b the blake2 crate's.
Published, by LND's aezeed test package, by Lightning Labs; the node keys computed with LND's and ldk-node's code, as tools/reference/aezeed/README.md records.
Compared with others' code: Lightning Labs (LND), Yawning Angel (AEZ): compared with the processor's AES round on both sides and again with the aes crate's software round against Yawning Angel's AEZ built without assembly.
Area lightning
Faraday's code faraday_bip::aezeed (ldk-node's and LND's node keys, the aezeed read), faraday_codec::bolt11::decode (a BOLT #11 invoice read), faraday_codec::bolt12::decode (a BOLT #12 offer read), faraday_keys::hsm_secret (Core Lightning's node key from its hsm_secret, plain encrypted or the mnemonic form, and from BIP-39 words)
Compared with LND's own code, vendored in Go (tools/reference/lnd/: its aezeed package over Yawning Angel's aez, and the node key over btcd's hdkeychain), one process answering the run's requests (the aezeed also asked of a second build of each side, Faraday's with the aes crate's software round and LND's without assembly); ldk-node's derivation as tools/reference/aezeed/README.md quotes it, written out in area_lightning.py over btclib's BIP-32 (btclib/, on btclib's own curve); for invoices, the bolt11 package by lnbits (2.2.0, tools/reference/bolt11/: its wheels over the bech32, base58 and bitstring packages, with a stand-in for its libsecp256k1 binding coincurve written over btclib's curve), and invoices written in bolt11_enc.py from BOLT #11 and signed with btclib; for offers, Core Lightning's own offer decoder, devtools/bolt12-cli built from its source release by its own configure and make (tools/reference/bolt12/), and offers written in bolt12_enc.py from BOLT #12; Core Lightning's code (tools/reference/cln/: ccan's HKDF-SHA256 compiled as it is, and its common/hsm_secret.c functions written out over the system libsodium, the BIP-39 words and seed of the mnemonic form from python-mnemonic), one process answering the run's requests.
Checked first: LND's code reads the aezeed (wordlist, version, CRC-32C, scrypt, AEZ) and derives the node key, and its published answers (tools/vectors/aezeed/) are required of it as well as of Faraday; the Go program is built offline from the vendored tree (GOFLAGS=-mod=vendor, GOTOOLCHAIN=local) and its version is written into the stamp; the area stops when the program is missing; the software-round pass runs only on programs soft.py has checked to be soft (the tags noasm and purego; no AES-NI instruction in Faraday's command) and the command says it was built soft; ldk-node's derivation is written in the area from the sources the README quotes, and ldk's published answers are required of it as well as of Faraday; the bolt11 package's wheels and its stand-in are hashed against references.sha256 before any run, and each of BOLT #11's 31 published examples is required to be read by Faraday as the BOLT says (a valid one read, an invalid one refused), the package reading the valid ones to the same fields; Core Lightning's HKDF is its compiled code, its salt, limits and calls are those of hsm_secret.c, libsodium itself seals and opens the file, and Core Lightning's two published node ids for words are required of it as well as of Faraday; the area stops when the program is missing and the stamp records libsodium's version; Core Lightning's release archive is hashed against tools/reference/bolt12/release.pin by the fetch and again by every build, the area stops when bolt12-cli is missing, and each of the BOLT #12 vectors is required to be read by Faraday as the vector says (a valid one read, an invalid one refused) and read by Core Lightning's decoder to the same fields where Faraday reads it.
ldk-node's node key is compared with a derivation written here, not with ldk's code (Rust, not vendored): only ldk's five published answers are outside it; LND's key path numbers are written in the Go program from keychain/derivation.go, as LND derives through btcwallet, which is not vendored; the bolt11 package is not asked the fields it does not read (fields BOLT #11 does not define, a fallback of a witness version above 16, a second or later fallback), which are compared with the writer's own list; its signature check runs on btclib's curve, not libsecp256k1's, and refuses a high-S signature as libsecp256k1 does; hsm_secret.c itself is not compiled (it needs tal and libwally): its functions are written out in main.c, and for the mnemonic form libwally's two answers, whether the words validate and their BIP-39 seed, are python-mnemonic's, which takes 12 to 24 words and normalises the words and passphrase (NFKD) where libwally takes 27 and 30 words too and normalises nothing, so the area judges only English 12 to 24-word ASCII cases and Faraday refuses 27 and 30 words (F228); a NUL in the mnemonic form's words is not compared (Core Lightning reads the text up to it, Faraday refuses the file); the words' derivation (lightning-hsmtool generatehsm) is BIP-39's seed, whose first 32 bytes are taken by both sides here; Core Lightning's bolt12-cli reads one Bech32 string, so the area takes out a + between two Bech32 characters and the white space after it, and a lightning: prefix, before asking it, and a text with a NUL byte cannot be given to it (Faraday refuses it); its output is read as text (a short channel id as BxTxO/direction, chain hashes reversed).
Vectors LND's five cipher seeds, LND's two node keys, ldk's five node ids (tools/vectors/aezeed/); BOLT #11's 31 examples, valid and invalid (tools/vectors/lightning-bolt11/); BOLT #12's 53 offer vectors and 12 format strings, valid and invalid (tools/vectors/lightning-bolt12/).
Random cases Random BIP-39 seeds and entropies on every network; every aezeed case again with the aes crate's software round against LND's AEZ without assembly; random words, a wrong version with a right checksum, published seeds under a changed passphrase, a changed enciphered byte or salt with the checksum put right, a changed word, each refused by LND's code; 150 invoices written with every kind of field (amounts in every multiplier, description or its hash, payee key, expiry, final cltv, fallbacks of every version, route hints, features, metadata, fields BOLT #11 does not define) and signed, read by Faraday and by the package field by field, then each with one Bech32 character changed, with one letter in upper case, and with two of these spoiled: a repeated p or x, a wrong-length p, s, h or n, no p, no s, both or neither of d and h, an unknown required feature, a leading zero value in a longer x, c or 9, a leading zero or a fraction of a millisatoshi in the amount, a bad multiplier, an unknown network, a high-S signature, a field cut short, a text over 1023 characters, a description that is not UTF-8; for Core Lightning, random plain and encrypted hsm_secrets under random passphrases (opened by Faraday and by libsodium, node ids compared), a secret sealed by libsodium and opened by Faraday and by Core Lightning's functions, a changed byte, a wrong passphrase and a wrong length each refused by both, random mnemonic-form files with and without a passphrase (node ids compared; a wrong passphrase, a passphrase the file does not have and broken words each refused by both), and random BIP-39 words with a passphrase; 250 rounds of BOLT #12 offers, each an offer written with every kind of field (chains, metadata, a currency or an amount in millisatoshis, description, features, expiry, blinded paths, issuer, quantity, issuer id, unknown odd fields; + joins, upper case and a lightning: prefix) read by Faraday and by Core Lightning's decoder field by field and by the writer's own record, then one with a Bech32 character changed, one in mixed case, and three of thirty-eight spoils: types out of order or repeated, a field cut short or longer than the stream, a BigSize, truncated integer or feature field not minimal, a type outside the offer's ranges or an unknown even one, a text that is not BOLT #1's, an amount without a description, of zero, or a currency without an amount, no issuer id and no path, a path of no hops or a bad point, chains empty or of a wrong length, padding of more than four bits, a bad +, a wrong prefix, characters outside Bech32, and F232's stricter cases (a text over 4,296 characters, a non-zero padding bit, a chain twice or none known, a currency not in ISO 4217, an amount above 21 million bitcoin, an expiry past the year 9999, a first node byte that is no key, an unassigned character).
Differences BOLT #11 invoices: the package skips a p, h, s or n field of the wrong length, reads the first of a repeated p or s, and accepts both or neither of a description and its hash, mixed case, an amount finer than a millisatoshi and a leading zero value in x, c or 9, all of which BOLT #11 makes a refusal or says "should" of and Faraday refuses; it also accepts what BOLT #11 leaves open, which Faraday is stricter on: a repeated x, c, m, 9, d, h or n, a text over 1023 characters, an amount with a leading zero, and a required feature bit Faraday does not know; the area counts each refusal as known, naming its reason.
BOLT #11 route hints: the package reads a hop's fees and delta as signed integers (a fee above 2^31 reads negative); the area reads them modulo 2^32 and 2^16 before comparing, and keeps a hint to three hops, as the package drops the last hop of a hint of a multiple of five.
BOLT #11 fallbacks: the package reads only the first fallback address and writes the others in bech32 for every witness version, no bech32m; the area compares Faraday's whole list of fallbacks with the writer's f fields of versions 0 to 18, in order, and its fields of an unknown version by the writer's list.
BOLT #11 features: the package keeps one state per feature, so a feature with both its required and its supported bit set reads as supported only; the writer sets one bit of each pair.
BOLT #12 offers: Core Lightning's bolt12-cli passes the decoder no feature set, so it reads an offer with an even feature bit that Faraday refuses (BOLT #9 defines no offer feature); it also reads feature bytes with a leading zero byte, which BOLT #9 makes not minimal, and a description, issuer or currency holding a character of Unicode's Cc, Cf, Co, Zl or Zp categories, which BOLT #1 refuses and Faraday refuses; and it refuses what Faraday reads when the currency is missing from its ISO 4217 table (the list of 2018) or an amount in bitcoin has a first chain Faraday does not know (it names the unit by the first chain alone), which Faraday reads as BOLT #12 says; the area counts each as known, naming the reason, and every other difference fails the run.
BOLT #12 offers, F232's stricter cases: Faraday refuses what Core Lightning reads (a text over 4,296 characters, a non-zero padding bit, whitespace after a + that is not a space, tab or line break, a chain twice, no known chain, a currency not in the ISO 4217 list Faraday holds, an amount over 21 million bitcoin, an expiry past the year 9999, a first node that is no key, an unassigned character); the area requires Faraday's refusal and counts it as known.
When it runs Before every release, with a new seed and about ten times the cases.
Last passing runSeed 5be11ec606a76d2767f225b8992c45fe · 14060 cases
AEZ's AES round is the aes crate's, which documents every backend as designed to run in constant time; the rest of AEZ is XOR, shifts and loops of fixed length, and the words are packed without a branch on their bits; the code states no other timing.
The deciphered entropy is held in a Secret that zeroizes on drop; the word bytes and the inner seed buffer are zeroized after use.
Limits
Version 0 only; a seed of another version or a failed checksum is refused before scrypt.
Reading only.
Faraday's own calls
aezeed and AEZ are written here; the cross-check asks LND's own Go aezeed package, over Yawning Angel's AEZ, the same words and passphrases and requires the same answers or refusals, once with the processor's AES round on both sides and once with the aes crate's software round against AEZ built without assembly. Neutral.
SpecificationCore Lightning hsm_secret · BIP 39PublishedCodeLibrary: argon2 0.6Library: chacha20 0.10Library: poly1305 0.91 moreFaraday's code: faraday/faraday-keysFaraday's own codeCross-checked withBlockstream and the Core Lightning developers (ccan's HKDF-SHA256Others' code
Action
Reads Core Lightning's hsm_secret, the plain 32 bytes, the 73 bytes encrypted under a passphrase, or the mnemonic form (a passphrase hash, then English BIP-39 words), or BIP-39 words as lightning-hsmtool generatehsm makes it, and gives the node key hsmd derives.
Specification
Core Lightning hsm_secret, Core Lightning's hsm_secret, plain or encrypted, and its node key, Convention
BIP 39, Mnemonic code for generating deterministic keys, Deployed
Code
Library: argon2 0.6.0, by the RustCrypto developers.
Library: chacha20 0.10.2, by the RustCrypto developers.
Library: poly1305 0.9.1, by the RustCrypto developers.
Library: hmac 0.13.0, by the RustCrypto developers, through core/faraday-crypto.
Faraday's code: faraday/faraday-keys: A 73-byte file is a 24-byte header and 49 bytes of ciphertext; the key is Argon2id of the passphrase with Core Lightning's salt and libsodium's moderate limits, and libsodium's secretstream pulls one message of it; the node key is HKDF-SHA256 of the 32 bytes with info nodeid and a 4-byte salt counting from 0, retried while it is not a valid key. The mnemonic form is a 32-byte hash (zero without a passphrase, else the SHA-256 of the 64-byte BIP-39 seed) and English words in single-space form, the node key from the first 32 bytes of the seed; the words come from faraday-bip's BIP-39. Reading only; a file shorter than 32 bytes or longer than the mnemonic form can be is refused.
Written by Faraday
libsodium's crypto_secretstream_xchacha20poly1305 pull of one message (faraday-keys::hsm_secret) · No established implementation exists
No maintained Rust crate offers libsodium's secretstream; Faraday's is HChaCha20, ChaCha20 and Poly1305 of RustCrypto's crates, and is tested against a file libsodium sealed and against libsodium itself.
no fuzz target: The mnemonic form's text is read by the BIP-39 words parser, which has its own fuzz target (bip39_words); the rest is a length check and bytes of a fixed length
Cross-check
Compared with others' code: Blockstream and the Core Lightning developers (ccan's HKDF-SHA256, the salt, limits and calls of common/hsm_secret.c written out in tools/reference/cln/main.c), the libsodium developers (Argon2id and the secretstream), python-mnemonic, by Trezor (SatoshiLabs) (the mnemonic form's BIP-39 words and seed).
Area lightning
Faraday's code faraday_bip::aezeed (ldk-node's and LND's node keys, the aezeed read), faraday_codec::bolt11::decode (a BOLT #11 invoice read), faraday_codec::bolt12::decode (a BOLT #12 offer read), faraday_keys::hsm_secret (Core Lightning's node key from its hsm_secret, plain encrypted or the mnemonic form, and from BIP-39 words)
Compared with LND's own code, vendored in Go (tools/reference/lnd/: its aezeed package over Yawning Angel's aez, and the node key over btcd's hdkeychain), one process answering the run's requests (the aezeed also asked of a second build of each side, Faraday's with the aes crate's software round and LND's without assembly); ldk-node's derivation as tools/reference/aezeed/README.md quotes it, written out in area_lightning.py over btclib's BIP-32 (btclib/, on btclib's own curve); for invoices, the bolt11 package by lnbits (2.2.0, tools/reference/bolt11/: its wheels over the bech32, base58 and bitstring packages, with a stand-in for its libsecp256k1 binding coincurve written over btclib's curve), and invoices written in bolt11_enc.py from BOLT #11 and signed with btclib; for offers, Core Lightning's own offer decoder, devtools/bolt12-cli built from its source release by its own configure and make (tools/reference/bolt12/), and offers written in bolt12_enc.py from BOLT #12; Core Lightning's code (tools/reference/cln/: ccan's HKDF-SHA256 compiled as it is, and its common/hsm_secret.c functions written out over the system libsodium, the BIP-39 words and seed of the mnemonic form from python-mnemonic), one process answering the run's requests.
Checked first: LND's code reads the aezeed (wordlist, version, CRC-32C, scrypt, AEZ) and derives the node key, and its published answers (tools/vectors/aezeed/) are required of it as well as of Faraday; the Go program is built offline from the vendored tree (GOFLAGS=-mod=vendor, GOTOOLCHAIN=local) and its version is written into the stamp; the area stops when the program is missing; the software-round pass runs only on programs soft.py has checked to be soft (the tags noasm and purego; no AES-NI instruction in Faraday's command) and the command says it was built soft; ldk-node's derivation is written in the area from the sources the README quotes, and ldk's published answers are required of it as well as of Faraday; the bolt11 package's wheels and its stand-in are hashed against references.sha256 before any run, and each of BOLT #11's 31 published examples is required to be read by Faraday as the BOLT says (a valid one read, an invalid one refused), the package reading the valid ones to the same fields; Core Lightning's HKDF is its compiled code, its salt, limits and calls are those of hsm_secret.c, libsodium itself seals and opens the file, and Core Lightning's two published node ids for words are required of it as well as of Faraday; the area stops when the program is missing and the stamp records libsodium's version; Core Lightning's release archive is hashed against tools/reference/bolt12/release.pin by the fetch and again by every build, the area stops when bolt12-cli is missing, and each of the BOLT #12 vectors is required to be read by Faraday as the vector says (a valid one read, an invalid one refused) and read by Core Lightning's decoder to the same fields where Faraday reads it.
ldk-node's node key is compared with a derivation written here, not with ldk's code (Rust, not vendored): only ldk's five published answers are outside it; LND's key path numbers are written in the Go program from keychain/derivation.go, as LND derives through btcwallet, which is not vendored; the bolt11 package is not asked the fields it does not read (fields BOLT #11 does not define, a fallback of a witness version above 16, a second or later fallback), which are compared with the writer's own list; its signature check runs on btclib's curve, not libsecp256k1's, and refuses a high-S signature as libsecp256k1 does; hsm_secret.c itself is not compiled (it needs tal and libwally): its functions are written out in main.c, and for the mnemonic form libwally's two answers, whether the words validate and their BIP-39 seed, are python-mnemonic's, which takes 12 to 24 words and normalises the words and passphrase (NFKD) where libwally takes 27 and 30 words too and normalises nothing, so the area judges only English 12 to 24-word ASCII cases and Faraday refuses 27 and 30 words (F228); a NUL in the mnemonic form's words is not compared (Core Lightning reads the text up to it, Faraday refuses the file); the words' derivation (lightning-hsmtool generatehsm) is BIP-39's seed, whose first 32 bytes are taken by both sides here; Core Lightning's bolt12-cli reads one Bech32 string, so the area takes out a + between two Bech32 characters and the white space after it, and a lightning: prefix, before asking it, and a text with a NUL byte cannot be given to it (Faraday refuses it); its output is read as text (a short channel id as BxTxO/direction, chain hashes reversed).
Vectors LND's five cipher seeds, LND's two node keys, ldk's five node ids (tools/vectors/aezeed/); BOLT #11's 31 examples, valid and invalid (tools/vectors/lightning-bolt11/); BOLT #12's 53 offer vectors and 12 format strings, valid and invalid (tools/vectors/lightning-bolt12/).
Random cases Random BIP-39 seeds and entropies on every network; every aezeed case again with the aes crate's software round against LND's AEZ without assembly; random words, a wrong version with a right checksum, published seeds under a changed passphrase, a changed enciphered byte or salt with the checksum put right, a changed word, each refused by LND's code; 150 invoices written with every kind of field (amounts in every multiplier, description or its hash, payee key, expiry, final cltv, fallbacks of every version, route hints, features, metadata, fields BOLT #11 does not define) and signed, read by Faraday and by the package field by field, then each with one Bech32 character changed, with one letter in upper case, and with two of these spoiled: a repeated p or x, a wrong-length p, s, h or n, no p, no s, both or neither of d and h, an unknown required feature, a leading zero value in a longer x, c or 9, a leading zero or a fraction of a millisatoshi in the amount, a bad multiplier, an unknown network, a high-S signature, a field cut short, a text over 1023 characters, a description that is not UTF-8; for Core Lightning, random plain and encrypted hsm_secrets under random passphrases (opened by Faraday and by libsodium, node ids compared), a secret sealed by libsodium and opened by Faraday and by Core Lightning's functions, a changed byte, a wrong passphrase and a wrong length each refused by both, random mnemonic-form files with and without a passphrase (node ids compared; a wrong passphrase, a passphrase the file does not have and broken words each refused by both), and random BIP-39 words with a passphrase; 250 rounds of BOLT #12 offers, each an offer written with every kind of field (chains, metadata, a currency or an amount in millisatoshis, description, features, expiry, blinded paths, issuer, quantity, issuer id, unknown odd fields; + joins, upper case and a lightning: prefix) read by Faraday and by Core Lightning's decoder field by field and by the writer's own record, then one with a Bech32 character changed, one in mixed case, and three of thirty-eight spoils: types out of order or repeated, a field cut short or longer than the stream, a BigSize, truncated integer or feature field not minimal, a type outside the offer's ranges or an unknown even one, a text that is not BOLT #1's, an amount without a description, of zero, or a currency without an amount, no issuer id and no path, a path of no hops or a bad point, chains empty or of a wrong length, padding of more than four bits, a bad +, a wrong prefix, characters outside Bech32, and F232's stricter cases (a text over 4,296 characters, a non-zero padding bit, a chain twice or none known, a currency not in ISO 4217, an amount above 21 million bitcoin, an expiry past the year 9999, a first node byte that is no key, an unassigned character).
Differences BOLT #11 invoices: the package skips a p, h, s or n field of the wrong length, reads the first of a repeated p or s, and accepts both or neither of a description and its hash, mixed case, an amount finer than a millisatoshi and a leading zero value in x, c or 9, all of which BOLT #11 makes a refusal or says "should" of and Faraday refuses; it also accepts what BOLT #11 leaves open, which Faraday is stricter on: a repeated x, c, m, 9, d, h or n, a text over 1023 characters, an amount with a leading zero, and a required feature bit Faraday does not know; the area counts each refusal as known, naming its reason.
BOLT #11 route hints: the package reads a hop's fees and delta as signed integers (a fee above 2^31 reads negative); the area reads them modulo 2^32 and 2^16 before comparing, and keeps a hint to three hops, as the package drops the last hop of a hint of a multiple of five.
BOLT #11 fallbacks: the package reads only the first fallback address and writes the others in bech32 for every witness version, no bech32m; the area compares Faraday's whole list of fallbacks with the writer's f fields of versions 0 to 18, in order, and its fields of an unknown version by the writer's list.
BOLT #11 features: the package keeps one state per feature, so a feature with both its required and its supported bit set reads as supported only; the writer sets one bit of each pair.
BOLT #12 offers: Core Lightning's bolt12-cli passes the decoder no feature set, so it reads an offer with an even feature bit that Faraday refuses (BOLT #9 defines no offer feature); it also reads feature bytes with a leading zero byte, which BOLT #9 makes not minimal, and a description, issuer or currency holding a character of Unicode's Cc, Cf, Co, Zl or Zp categories, which BOLT #1 refuses and Faraday refuses; and it refuses what Faraday reads when the currency is missing from its ISO 4217 table (the list of 2018) or an amount in bitcoin has a first chain Faraday does not know (it names the unit by the first chain alone), which Faraday reads as BOLT #12 says; the area counts each as known, naming the reason, and every other difference fails the run.
BOLT #12 offers, F232's stricter cases: Faraday refuses what Core Lightning reads (a text over 4,296 characters, a non-zero padding bit, whitespace after a + that is not a space, tab or line break, a chain twice, no known chain, a currency not in the ISO 4217 list Faraday holds, an amount over 21 million bitcoin, an expiry past the year 9999, a first node that is no key, an unassigned character); the area requires Faraday's refusal and counts it as known.
When it runs Before every release, with a new seed and about ten times the cases.
Last passing runSeed 5be11ec606a76d2767f225b8992c45fe · 14060 cases
Poly1305's tag is compared in constant time (subtle); the rest is not stated.
The passphrase, the Argon2id key, the secret and the node key are held in zeroizing buffers; the node key leaves only as hex for a reason that names it.
Limits
Reading only: an hsm_secret is never made and never loaded as a key.
A file shorter than 32 bytes, or longer than the mnemonic form can be, is refused. In the mnemonic form the words are English only, in single-space form with no NUL, newline or other whitespace; Core Lightning's text reading is stricter in no case and looser in some, which Faraday refuses.
BIP 39, Mnemonic code for generating deterministic keys, Deployed
Code
Library: bitcoin 0.32.102, by the rust-bitcoin developers.
Library: secp256k1 0.29.1, by the rust-bitcoin developers (rust-secp256k1), over libsecp256k1, by Bitcoin Core's libsecp256k1 project (bitcoin-core/secp256k1).
Library: base16ct 1.0.0, by the RustCrypto developers, through core/faraday-crypto.
Faraday's code: core/faraday-bip: LND's key is m/1017'/coin'/6'/0/0 of the aezeed's entropy taken as the BIP-32 seed; ldk-node's is m/0' of a second master key made from the first master's private key.
Checked against
tools/vectors/aezeed
Published, by LND's aezeed test package, by Lightning Labs; the node keys computed with LND's and ldk-node's code, as tools/reference/aezeed/README.md records.
Compared with others' code: LND's node key by btcd's hdkeychain in LND's vendored tree, by Lightning Labs and the btcd developers, for LND; btclib-wallet's bip32, by the btclib developers, and python-mnemonic, by Trezor (SatoshiLabs), for each step of ldk-node's key.
Compared, for one part, with Faraday's second version, written by Faraday's authors in Python; that part is not checked against an outside source: ldk-node's node key, composed in area_lightning.py from the sources tools/reference/aezeed/README.md quotes (each step btclib's), and LND's key-path numbers (1017', coin, 6', 0, 0), written in tools/reference/lnd/main.go from keychain/derivation.go.
Area lightning
Faraday's code faraday_bip::aezeed (ldk-node's and LND's node keys, the aezeed read), faraday_codec::bolt11::decode (a BOLT #11 invoice read), faraday_codec::bolt12::decode (a BOLT #12 offer read), faraday_keys::hsm_secret (Core Lightning's node key from its hsm_secret, plain encrypted or the mnemonic form, and from BIP-39 words)
Compared with LND's own code, vendored in Go (tools/reference/lnd/: its aezeed package over Yawning Angel's aez, and the node key over btcd's hdkeychain), one process answering the run's requests (the aezeed also asked of a second build of each side, Faraday's with the aes crate's software round and LND's without assembly); ldk-node's derivation as tools/reference/aezeed/README.md quotes it, written out in area_lightning.py over btclib's BIP-32 (btclib/, on btclib's own curve); for invoices, the bolt11 package by lnbits (2.2.0, tools/reference/bolt11/: its wheels over the bech32, base58 and bitstring packages, with a stand-in for its libsecp256k1 binding coincurve written over btclib's curve), and invoices written in bolt11_enc.py from BOLT #11 and signed with btclib; for offers, Core Lightning's own offer decoder, devtools/bolt12-cli built from its source release by its own configure and make (tools/reference/bolt12/), and offers written in bolt12_enc.py from BOLT #12; Core Lightning's code (tools/reference/cln/: ccan's HKDF-SHA256 compiled as it is, and its common/hsm_secret.c functions written out over the system libsodium, the BIP-39 words and seed of the mnemonic form from python-mnemonic), one process answering the run's requests.
Checked first: LND's code reads the aezeed (wordlist, version, CRC-32C, scrypt, AEZ) and derives the node key, and its published answers (tools/vectors/aezeed/) are required of it as well as of Faraday; the Go program is built offline from the vendored tree (GOFLAGS=-mod=vendor, GOTOOLCHAIN=local) and its version is written into the stamp; the area stops when the program is missing; the software-round pass runs only on programs soft.py has checked to be soft (the tags noasm and purego; no AES-NI instruction in Faraday's command) and the command says it was built soft; ldk-node's derivation is written in the area from the sources the README quotes, and ldk's published answers are required of it as well as of Faraday; the bolt11 package's wheels and its stand-in are hashed against references.sha256 before any run, and each of BOLT #11's 31 published examples is required to be read by Faraday as the BOLT says (a valid one read, an invalid one refused), the package reading the valid ones to the same fields; Core Lightning's HKDF is its compiled code, its salt, limits and calls are those of hsm_secret.c, libsodium itself seals and opens the file, and Core Lightning's two published node ids for words are required of it as well as of Faraday; the area stops when the program is missing and the stamp records libsodium's version; Core Lightning's release archive is hashed against tools/reference/bolt12/release.pin by the fetch and again by every build, the area stops when bolt12-cli is missing, and each of the BOLT #12 vectors is required to be read by Faraday as the vector says (a valid one read, an invalid one refused) and read by Core Lightning's decoder to the same fields where Faraday reads it.
ldk-node's node key is compared with a derivation written here, not with ldk's code (Rust, not vendored): only ldk's five published answers are outside it; LND's key path numbers are written in the Go program from keychain/derivation.go, as LND derives through btcwallet, which is not vendored; the bolt11 package is not asked the fields it does not read (fields BOLT #11 does not define, a fallback of a witness version above 16, a second or later fallback), which are compared with the writer's own list; its signature check runs on btclib's curve, not libsecp256k1's, and refuses a high-S signature as libsecp256k1 does; hsm_secret.c itself is not compiled (it needs tal and libwally): its functions are written out in main.c, and for the mnemonic form libwally's two answers, whether the words validate and their BIP-39 seed, are python-mnemonic's, which takes 12 to 24 words and normalises the words and passphrase (NFKD) where libwally takes 27 and 30 words too and normalises nothing, so the area judges only English 12 to 24-word ASCII cases and Faraday refuses 27 and 30 words (F228); a NUL in the mnemonic form's words is not compared (Core Lightning reads the text up to it, Faraday refuses the file); the words' derivation (lightning-hsmtool generatehsm) is BIP-39's seed, whose first 32 bytes are taken by both sides here; Core Lightning's bolt12-cli reads one Bech32 string, so the area takes out a + between two Bech32 characters and the white space after it, and a lightning: prefix, before asking it, and a text with a NUL byte cannot be given to it (Faraday refuses it); its output is read as text (a short channel id as BxTxO/direction, chain hashes reversed).
Vectors LND's five cipher seeds, LND's two node keys, ldk's five node ids (tools/vectors/aezeed/); BOLT #11's 31 examples, valid and invalid (tools/vectors/lightning-bolt11/); BOLT #12's 53 offer vectors and 12 format strings, valid and invalid (tools/vectors/lightning-bolt12/).
Random cases Random BIP-39 seeds and entropies on every network; every aezeed case again with the aes crate's software round against LND's AEZ without assembly; random words, a wrong version with a right checksum, published seeds under a changed passphrase, a changed enciphered byte or salt with the checksum put right, a changed word, each refused by LND's code; 150 invoices written with every kind of field (amounts in every multiplier, description or its hash, payee key, expiry, final cltv, fallbacks of every version, route hints, features, metadata, fields BOLT #11 does not define) and signed, read by Faraday and by the package field by field, then each with one Bech32 character changed, with one letter in upper case, and with two of these spoiled: a repeated p or x, a wrong-length p, s, h or n, no p, no s, both or neither of d and h, an unknown required feature, a leading zero value in a longer x, c or 9, a leading zero or a fraction of a millisatoshi in the amount, a bad multiplier, an unknown network, a high-S signature, a field cut short, a text over 1023 characters, a description that is not UTF-8; for Core Lightning, random plain and encrypted hsm_secrets under random passphrases (opened by Faraday and by libsodium, node ids compared), a secret sealed by libsodium and opened by Faraday and by Core Lightning's functions, a changed byte, a wrong passphrase and a wrong length each refused by both, random mnemonic-form files with and without a passphrase (node ids compared; a wrong passphrase, a passphrase the file does not have and broken words each refused by both), and random BIP-39 words with a passphrase; 250 rounds of BOLT #12 offers, each an offer written with every kind of field (chains, metadata, a currency or an amount in millisatoshis, description, features, expiry, blinded paths, issuer, quantity, issuer id, unknown odd fields; + joins, upper case and a lightning: prefix) read by Faraday and by Core Lightning's decoder field by field and by the writer's own record, then one with a Bech32 character changed, one in mixed case, and three of thirty-eight spoils: types out of order or repeated, a field cut short or longer than the stream, a BigSize, truncated integer or feature field not minimal, a type outside the offer's ranges or an unknown even one, a text that is not BOLT #1's, an amount without a description, of zero, or a currency without an amount, no issuer id and no path, a path of no hops or a bad point, chains empty or of a wrong length, padding of more than four bits, a bad +, a wrong prefix, characters outside Bech32, and F232's stricter cases (a text over 4,296 characters, a non-zero padding bit, a chain twice or none known, a currency not in ISO 4217, an amount above 21 million bitcoin, an expiry past the year 9999, a first node byte that is no key, an unassigned character).
Differences BOLT #11 invoices: the package skips a p, h, s or n field of the wrong length, reads the first of a repeated p or s, and accepts both or neither of a description and its hash, mixed case, an amount finer than a millisatoshi and a leading zero value in x, c or 9, all of which BOLT #11 makes a refusal or says "should" of and Faraday refuses; it also accepts what BOLT #11 leaves open, which Faraday is stricter on: a repeated x, c, m, 9, d, h or n, a text over 1023 characters, an amount with a leading zero, and a required feature bit Faraday does not know; the area counts each refusal as known, naming its reason.
BOLT #11 route hints: the package reads a hop's fees and delta as signed integers (a fee above 2^31 reads negative); the area reads them modulo 2^32 and 2^16 before comparing, and keeps a hint to three hops, as the package drops the last hop of a hint of a multiple of five.
BOLT #11 fallbacks: the package reads only the first fallback address and writes the others in bech32 for every witness version, no bech32m; the area compares Faraday's whole list of fallbacks with the writer's f fields of versions 0 to 18, in order, and its fields of an unknown version by the writer's list.
BOLT #11 features: the package keeps one state per feature, so a feature with both its required and its supported bit set reads as supported only; the writer sets one bit of each pair.
BOLT #12 offers: Core Lightning's bolt12-cli passes the decoder no feature set, so it reads an offer with an even feature bit that Faraday refuses (BOLT #9 defines no offer feature); it also reads feature bytes with a leading zero byte, which BOLT #9 makes not minimal, and a description, issuer or currency holding a character of Unicode's Cc, Cf, Co, Zl or Zp categories, which BOLT #1 refuses and Faraday refuses; and it refuses what Faraday reads when the currency is missing from its ISO 4217 table (the list of 2018) or an amount in bitcoin has a first chain Faraday does not know (it names the unit by the first chain alone), which Faraday reads as BOLT #12 says; the area counts each as known, naming the reason, and every other difference fails the run.
BOLT #12 offers, F232's stricter cases: Faraday refuses what Core Lightning reads (a text over 4,296 characters, a non-zero padding bit, whitespace after a + that is not a space, tab or line break, a chain twice, no known chain, a currency not in the ISO 4217 list Faraday holds, an amount over 21 million bitcoin, an expiry past the year 9999, a first node that is no key, an unassigned character); the area requires Faraday's refusal and counts it as known.
When it runs Before every release, with a new seed and about ten times the cases.
Last passing runSeed 5be11ec606a76d2767f225b8992c45fe · 14060 cases
Reads a BOLT #11 invoice: Bech32, the amount, the timestamp and the tagged fields, and checks the signature against the `n` field or recovers the payee's key from it.
Specification
BOLT 11, BOLT #11: Invoice Protocol for Lightning Payments, Deployed
Code
Library: bitcoin 0.32.102, by the rust-bitcoin developers.
Faraday's code: core/faraday-codec: The invoice's fields are read here, over the bitcoin crate's Bech32 and secp256k1; reading only, nothing is paid, signed or stored, and every refusal is a named reason.
Checked against
tools/vectors/lightning-bolt11
Published, by BOLT #11's authors (lightning/bolts): the examples of bolt11/invoice-test.json, valid and invalid.
Compared with others' code: the bolt11 package (lnbits), over the bech32 and bitstring packages, with a stand-in for its libsecp256k1 binding over btclib; Faraday's stricter refusals are stated differences of the area.
Area lightning
Faraday's code faraday_bip::aezeed (ldk-node's and LND's node keys, the aezeed read), faraday_codec::bolt11::decode (a BOLT #11 invoice read), faraday_codec::bolt12::decode (a BOLT #12 offer read), faraday_keys::hsm_secret (Core Lightning's node key from its hsm_secret, plain encrypted or the mnemonic form, and from BIP-39 words)
Compared with LND's own code, vendored in Go (tools/reference/lnd/: its aezeed package over Yawning Angel's aez, and the node key over btcd's hdkeychain), one process answering the run's requests (the aezeed also asked of a second build of each side, Faraday's with the aes crate's software round and LND's without assembly); ldk-node's derivation as tools/reference/aezeed/README.md quotes it, written out in area_lightning.py over btclib's BIP-32 (btclib/, on btclib's own curve); for invoices, the bolt11 package by lnbits (2.2.0, tools/reference/bolt11/: its wheels over the bech32, base58 and bitstring packages, with a stand-in for its libsecp256k1 binding coincurve written over btclib's curve), and invoices written in bolt11_enc.py from BOLT #11 and signed with btclib; for offers, Core Lightning's own offer decoder, devtools/bolt12-cli built from its source release by its own configure and make (tools/reference/bolt12/), and offers written in bolt12_enc.py from BOLT #12; Core Lightning's code (tools/reference/cln/: ccan's HKDF-SHA256 compiled as it is, and its common/hsm_secret.c functions written out over the system libsodium, the BIP-39 words and seed of the mnemonic form from python-mnemonic), one process answering the run's requests.
Checked first: LND's code reads the aezeed (wordlist, version, CRC-32C, scrypt, AEZ) and derives the node key, and its published answers (tools/vectors/aezeed/) are required of it as well as of Faraday; the Go program is built offline from the vendored tree (GOFLAGS=-mod=vendor, GOTOOLCHAIN=local) and its version is written into the stamp; the area stops when the program is missing; the software-round pass runs only on programs soft.py has checked to be soft (the tags noasm and purego; no AES-NI instruction in Faraday's command) and the command says it was built soft; ldk-node's derivation is written in the area from the sources the README quotes, and ldk's published answers are required of it as well as of Faraday; the bolt11 package's wheels and its stand-in are hashed against references.sha256 before any run, and each of BOLT #11's 31 published examples is required to be read by Faraday as the BOLT says (a valid one read, an invalid one refused), the package reading the valid ones to the same fields; Core Lightning's HKDF is its compiled code, its salt, limits and calls are those of hsm_secret.c, libsodium itself seals and opens the file, and Core Lightning's two published node ids for words are required of it as well as of Faraday; the area stops when the program is missing and the stamp records libsodium's version; Core Lightning's release archive is hashed against tools/reference/bolt12/release.pin by the fetch and again by every build, the area stops when bolt12-cli is missing, and each of the BOLT #12 vectors is required to be read by Faraday as the vector says (a valid one read, an invalid one refused) and read by Core Lightning's decoder to the same fields where Faraday reads it.
ldk-node's node key is compared with a derivation written here, not with ldk's code (Rust, not vendored): only ldk's five published answers are outside it; LND's key path numbers are written in the Go program from keychain/derivation.go, as LND derives through btcwallet, which is not vendored; the bolt11 package is not asked the fields it does not read (fields BOLT #11 does not define, a fallback of a witness version above 16, a second or later fallback), which are compared with the writer's own list; its signature check runs on btclib's curve, not libsecp256k1's, and refuses a high-S signature as libsecp256k1 does; hsm_secret.c itself is not compiled (it needs tal and libwally): its functions are written out in main.c, and for the mnemonic form libwally's two answers, whether the words validate and their BIP-39 seed, are python-mnemonic's, which takes 12 to 24 words and normalises the words and passphrase (NFKD) where libwally takes 27 and 30 words too and normalises nothing, so the area judges only English 12 to 24-word ASCII cases and Faraday refuses 27 and 30 words (F228); a NUL in the mnemonic form's words is not compared (Core Lightning reads the text up to it, Faraday refuses the file); the words' derivation (lightning-hsmtool generatehsm) is BIP-39's seed, whose first 32 bytes are taken by both sides here; Core Lightning's bolt12-cli reads one Bech32 string, so the area takes out a + between two Bech32 characters and the white space after it, and a lightning: prefix, before asking it, and a text with a NUL byte cannot be given to it (Faraday refuses it); its output is read as text (a short channel id as BxTxO/direction, chain hashes reversed).
Vectors LND's five cipher seeds, LND's two node keys, ldk's five node ids (tools/vectors/aezeed/); BOLT #11's 31 examples, valid and invalid (tools/vectors/lightning-bolt11/); BOLT #12's 53 offer vectors and 12 format strings, valid and invalid (tools/vectors/lightning-bolt12/).
Random cases Random BIP-39 seeds and entropies on every network; every aezeed case again with the aes crate's software round against LND's AEZ without assembly; random words, a wrong version with a right checksum, published seeds under a changed passphrase, a changed enciphered byte or salt with the checksum put right, a changed word, each refused by LND's code; 150 invoices written with every kind of field (amounts in every multiplier, description or its hash, payee key, expiry, final cltv, fallbacks of every version, route hints, features, metadata, fields BOLT #11 does not define) and signed, read by Faraday and by the package field by field, then each with one Bech32 character changed, with one letter in upper case, and with two of these spoiled: a repeated p or x, a wrong-length p, s, h or n, no p, no s, both or neither of d and h, an unknown required feature, a leading zero value in a longer x, c or 9, a leading zero or a fraction of a millisatoshi in the amount, a bad multiplier, an unknown network, a high-S signature, a field cut short, a text over 1023 characters, a description that is not UTF-8; for Core Lightning, random plain and encrypted hsm_secrets under random passphrases (opened by Faraday and by libsodium, node ids compared), a secret sealed by libsodium and opened by Faraday and by Core Lightning's functions, a changed byte, a wrong passphrase and a wrong length each refused by both, random mnemonic-form files with and without a passphrase (node ids compared; a wrong passphrase, a passphrase the file does not have and broken words each refused by both), and random BIP-39 words with a passphrase; 250 rounds of BOLT #12 offers, each an offer written with every kind of field (chains, metadata, a currency or an amount in millisatoshis, description, features, expiry, blinded paths, issuer, quantity, issuer id, unknown odd fields; + joins, upper case and a lightning: prefix) read by Faraday and by Core Lightning's decoder field by field and by the writer's own record, then one with a Bech32 character changed, one in mixed case, and three of thirty-eight spoils: types out of order or repeated, a field cut short or longer than the stream, a BigSize, truncated integer or feature field not minimal, a type outside the offer's ranges or an unknown even one, a text that is not BOLT #1's, an amount without a description, of zero, or a currency without an amount, no issuer id and no path, a path of no hops or a bad point, chains empty or of a wrong length, padding of more than four bits, a bad +, a wrong prefix, characters outside Bech32, and F232's stricter cases (a text over 4,296 characters, a non-zero padding bit, a chain twice or none known, a currency not in ISO 4217, an amount above 21 million bitcoin, an expiry past the year 9999, a first node byte that is no key, an unassigned character).
Differences BOLT #11 invoices: the package skips a p, h, s or n field of the wrong length, reads the first of a repeated p or s, and accepts both or neither of a description and its hash, mixed case, an amount finer than a millisatoshi and a leading zero value in x, c or 9, all of which BOLT #11 makes a refusal or says "should" of and Faraday refuses; it also accepts what BOLT #11 leaves open, which Faraday is stricter on: a repeated x, c, m, 9, d, h or n, a text over 1023 characters, an amount with a leading zero, and a required feature bit Faraday does not know; the area counts each refusal as known, naming its reason.
BOLT #11 route hints: the package reads a hop's fees and delta as signed integers (a fee above 2^31 reads negative); the area reads them modulo 2^32 and 2^16 before comparing, and keeps a hint to three hops, as the package drops the last hop of a hint of a multiple of five.
BOLT #11 fallbacks: the package reads only the first fallback address and writes the others in bech32 for every witness version, no bech32m; the area compares Faraday's whole list of fallbacks with the writer's f fields of versions 0 to 18, in order, and its fields of an unknown version by the writer's list.
BOLT #11 features: the package keeps one state per feature, so a feature with both its required and its supported bit set reads as supported only; the writer sets one bit of each pair.
BOLT #12 offers: Core Lightning's bolt12-cli passes the decoder no feature set, so it reads an offer with an even feature bit that Faraday refuses (BOLT #9 defines no offer feature); it also reads feature bytes with a leading zero byte, which BOLT #9 makes not minimal, and a description, issuer or currency holding a character of Unicode's Cc, Cf, Co, Zl or Zp categories, which BOLT #1 refuses and Faraday refuses; and it refuses what Faraday reads when the currency is missing from its ISO 4217 table (the list of 2018) or an amount in bitcoin has a first chain Faraday does not know (it names the unit by the first chain alone), which Faraday reads as BOLT #12 says; the area counts each as known, naming the reason, and every other difference fails the run.
BOLT #12 offers, F232's stricter cases: Faraday refuses what Core Lightning reads (a text over 4,296 characters, a non-zero padding bit, whitespace after a + that is not a space, tab or line break, a chain twice, no known chain, a currency not in the ISO 4217 list Faraday holds, an amount over 21 million bitcoin, an expiry past the year 9999, a first node that is no key, an unassigned character); the area requires Faraday's refusal and counts it as known.
When it runs Before every release, with a new seed and about ten times the cases.
Last passing runSeed 5be11ec606a76d2767f225b8992c45fe · 14060 cases
Reading only: no invoice is written, paid or stored.
A text over 1023 characters, mixed case or a checksum that fails is refused.
Fields of a tag BOLT #11 does not define, and a fallback address of an unknown version, are listed and not used.
Faraday's own calls
BOLT #11 makes mixed case, an amount finer than a millisatoshi and a `c`, `x` or `9` field that begins with a zero value (the minimal form of zero is an empty field) a refusal, and Faraday refuses them. Where BOLT #11 leaves a case open, Faraday refuses the invoice: an amount with a leading zero, a repeated `x`, `c`, `m`, `9`, `d`, `h` or `n`, a malformed fallback of a version it defines, an empty route hint or a hop key that is not a curve point, an `n` key that is not on the curve, a non-zero padding bit, and a text over 1023 characters (what the Bech32 checksum guarantees). Conservative.
Reads an OpenTimestamps proof and follows every path of its operations from the file's hash to its attestations, and says for each Bitcoin one whether it reaches the merkle root of a block header the person gives, whose hash meets its own target.
Library: sha1 0.11.0, by the RustCrypto developers.
Library: ripemd 0.2.0, by the RustCrypto developers.
Library: sha3 0.11.0, by the RustCrypto developers.
Library: sha2 0.11.0, by the RustCrypto developers, through core/faraday-crypto.
Faraday's code: faraday/faraday-ots: The proof's reader and the walk of its operations are written here; the hashes are the RustCrypto crates and SHA-256 is faraday-crypto's. A Bitcoin path is counted only when every hash on it is SHA-256, and the header's own proof of work is checked before it is used.
Written by Faraday
OpenTimestamps proof reader and walk (faraday-ots) · No established implementation exists
No Rust implementation of the OpenTimestamps proof format is established; Faraday's follows python-opentimestamps and is tested against that project's example proofs.
Published, by the OpenTimestamps client's example proofs (opentimestamps/opentimestamps-client), with the headers of the blocks they name from a public block explorer, each checked against its recorded hash.
Compared with others' code: python-opentimestamps, by the OpenTimestamps developers (the reference client's own reader and verifier of proofs).
Area ots
Faraday's code faraday_ots (Proof::parse, Proof::verify, Header::parse), asked through the three requests ots.read, ots.verify and ots.header
Compared with python-opentimestamps' core modules, vendored unchanged in tools/reference/opentimestamps/, by the OpenTimestamps developers, on three small shims for what it imports and the repository does not vendor (Keccak-256, RIPEMD-160 over Bitcoin Core's pure-Python hash, and four names of python-bitcoinlib that only its printing routine uses); block headers are read by the area's own transcription of Bitcoin Core's SetCompact and proof-of-work test.
Checked first: The vendored files are hashed against references.sha256 before any run; the client's example proofs (tools/vectors/opentimestamps/) are read by both and the four that reach a block through SHA-256 and RIPEMD-160 alone are required to be committed by both; the shims' hashes are checked against known values before the corpus; each limit is built either side of its edge and both must agree.
The reference's printing of a tree and its stream readers; the order of a node's entries (the walk is compared as a set of paths); whether a header is in the chain; calendars, which neither side asks.
Vectors The OpenTimestamps client's example proofs (all 22, three of them invalid) and the headers of the six blocks they name, each proof walked against each header.
Random cases Proofs built through the reference's classes with every operation, the file hashed with SHA-256, SHA-1 or RIPEMD-160, side branches ending in pending, Bitcoin, Litecoin, Ethereum and unknown attestations, and chains to 255 operations, walked against a header that commits to the main path and one that does not; merkle trees of up to 40 leaves; proofs with a byte changed, inserted, deleted, cut or added to; every limit either side of its edge; headers over every kind of target and lengths other than 80.
Differences OTS: a Bitcoin path through SHA-1 or Keccak-256, or a file taken with SHA-1, is counted by the reference when it reaches the header's merkle root; Faraday names the first such hash and does not count it. Each is asked of the reference and counted.
OTS: an Ethereum attestation is verified by the reference against a block's transactions root; Faraday lists it by height and does not check it. A Litecoin one is listed by both (the reference raises when asked to verify it).
OTS: an attestation repeated at one node is collapsed by the reference and listed twice by Faraday.
OTS: Faraday refuses a proof over 64 KiB, a tree of more than 16,384 entries and a tree whose operations make more than 16 MiB of values; the reference reads each (a tree of 17 appends of one byte to a value of 4,095 bytes, each followed by 250 reversals, makes 17.5 MiB in 8.6 KB; 65 chains of 252 reversals behind distinct appends make over 16,384 entries in 17 KB).
When it runs Before every release, with a new seed and about ten times the cases.
Last passing runSeed 5be11ec606a76d2767f225b8992c45fe · 5800 cases
Reading only: no timestamp is made, upgraded or looked up; a pending attestation is listed with its calendar and not followed.
The header given is checked against its own target and not against the chain: a match says the file is committed to by that header.
An operation's argument or result over 4,096 bytes, a tree deeper than 256 levels, a height over 32 bits, a proof over 64 KiB, a tree of over 16,384 entries, over 16 MiB of values made by the operations in all, a header target above its network's limit and a proof with bytes after its tree are refused.
Faraday's own calls
A Bitcoin path counts only when the file's hash and every hash on it are SHA-256 or RIPEMD-160: a path through SHA-1 or Keccak-256 is named and not counted, where python-opentimestamps counts it. Where the reference leaves a case open, Faraday refuses: an Ethereum attestation whose payload is not one height, a block height over 32 bits, a number over 64 bits, a proof over 64 KiB, a tree of over 16,384 entries or whose operations make over 16 MiB of values in all, and a header whose target is above its network's proof-of-work limit (the reference reads these without a limit). Conservative, F230.
SpecificationBOLT 12PublishedCodeLibrary: bitcoin 0.32Faraday's code: core/faraday-codecCross-checked withCore Lightning's bolt12-cliOthers' codeFaraday's second version
Action
Reads a BOLT #12 offer: Bech32 without a checksum, its `+` joins, and the TLV fields (chains, amount and currency, description, issuer, expiry, quantity, features, blinded paths, issuer id and the odd fields it does not know).
Specification
BOLT 12, BOLT #12: Negotiation Protocol for Lightning Payments, Deployed
Code
Library: bitcoin 0.32.102, by the rust-bitcoin developers.
Faraday's code: core/faraday-codec: The offer's fields are read here, over the bitcoin crate's secp256k1 for the points; reading only, an offer carries no signature and nothing is hashed, requested, paid or stored, and every refusal is a named reason.
Checked against
tools/vectors/lightning-bolt12
Published, by BOLT #12's authors (lightning/bolts): the offers of bolt12/offers-test.json and the strings of bolt12/format-string-test.json, valid and invalid, at the commit tools/vectors/lightning-bolt12/README.md names.
Compared with others' code: Core Lightning's bolt12-cli, by the Core Lightning developers (Blockstream), built from its v26.06.10 source release.
Compared, for one part, with Faraday's second version, written by Faraday's authors in Python; that part is not checked against an outside source: the offers the area reads, written in bolt12_enc.py from BOLT #12, and the stricter refusals of F232 and what Core Lightning's command does not check (a feature set, minimal feature bytes, BOLT #1's refused characters, its 2018 currency table), which are stated differences of the area.
Area lightning
Faraday's code faraday_bip::aezeed (ldk-node's and LND's node keys, the aezeed read), faraday_codec::bolt11::decode (a BOLT #11 invoice read), faraday_codec::bolt12::decode (a BOLT #12 offer read), faraday_keys::hsm_secret (Core Lightning's node key from its hsm_secret, plain encrypted or the mnemonic form, and from BIP-39 words)
Compared with LND's own code, vendored in Go (tools/reference/lnd/: its aezeed package over Yawning Angel's aez, and the node key over btcd's hdkeychain), one process answering the run's requests (the aezeed also asked of a second build of each side, Faraday's with the aes crate's software round and LND's without assembly); ldk-node's derivation as tools/reference/aezeed/README.md quotes it, written out in area_lightning.py over btclib's BIP-32 (btclib/, on btclib's own curve); for invoices, the bolt11 package by lnbits (2.2.0, tools/reference/bolt11/: its wheels over the bech32, base58 and bitstring packages, with a stand-in for its libsecp256k1 binding coincurve written over btclib's curve), and invoices written in bolt11_enc.py from BOLT #11 and signed with btclib; for offers, Core Lightning's own offer decoder, devtools/bolt12-cli built from its source release by its own configure and make (tools/reference/bolt12/), and offers written in bolt12_enc.py from BOLT #12; Core Lightning's code (tools/reference/cln/: ccan's HKDF-SHA256 compiled as it is, and its common/hsm_secret.c functions written out over the system libsodium, the BIP-39 words and seed of the mnemonic form from python-mnemonic), one process answering the run's requests.
Checked first: LND's code reads the aezeed (wordlist, version, CRC-32C, scrypt, AEZ) and derives the node key, and its published answers (tools/vectors/aezeed/) are required of it as well as of Faraday; the Go program is built offline from the vendored tree (GOFLAGS=-mod=vendor, GOTOOLCHAIN=local) and its version is written into the stamp; the area stops when the program is missing; the software-round pass runs only on programs soft.py has checked to be soft (the tags noasm and purego; no AES-NI instruction in Faraday's command) and the command says it was built soft; ldk-node's derivation is written in the area from the sources the README quotes, and ldk's published answers are required of it as well as of Faraday; the bolt11 package's wheels and its stand-in are hashed against references.sha256 before any run, and each of BOLT #11's 31 published examples is required to be read by Faraday as the BOLT says (a valid one read, an invalid one refused), the package reading the valid ones to the same fields; Core Lightning's HKDF is its compiled code, its salt, limits and calls are those of hsm_secret.c, libsodium itself seals and opens the file, and Core Lightning's two published node ids for words are required of it as well as of Faraday; the area stops when the program is missing and the stamp records libsodium's version; Core Lightning's release archive is hashed against tools/reference/bolt12/release.pin by the fetch and again by every build, the area stops when bolt12-cli is missing, and each of the BOLT #12 vectors is required to be read by Faraday as the vector says (a valid one read, an invalid one refused) and read by Core Lightning's decoder to the same fields where Faraday reads it.
ldk-node's node key is compared with a derivation written here, not with ldk's code (Rust, not vendored): only ldk's five published answers are outside it; LND's key path numbers are written in the Go program from keychain/derivation.go, as LND derives through btcwallet, which is not vendored; the bolt11 package is not asked the fields it does not read (fields BOLT #11 does not define, a fallback of a witness version above 16, a second or later fallback), which are compared with the writer's own list; its signature check runs on btclib's curve, not libsecp256k1's, and refuses a high-S signature as libsecp256k1 does; hsm_secret.c itself is not compiled (it needs tal and libwally): its functions are written out in main.c, and for the mnemonic form libwally's two answers, whether the words validate and their BIP-39 seed, are python-mnemonic's, which takes 12 to 24 words and normalises the words and passphrase (NFKD) where libwally takes 27 and 30 words too and normalises nothing, so the area judges only English 12 to 24-word ASCII cases and Faraday refuses 27 and 30 words (F228); a NUL in the mnemonic form's words is not compared (Core Lightning reads the text up to it, Faraday refuses the file); the words' derivation (lightning-hsmtool generatehsm) is BIP-39's seed, whose first 32 bytes are taken by both sides here; Core Lightning's bolt12-cli reads one Bech32 string, so the area takes out a + between two Bech32 characters and the white space after it, and a lightning: prefix, before asking it, and a text with a NUL byte cannot be given to it (Faraday refuses it); its output is read as text (a short channel id as BxTxO/direction, chain hashes reversed).
Vectors LND's five cipher seeds, LND's two node keys, ldk's five node ids (tools/vectors/aezeed/); BOLT #11's 31 examples, valid and invalid (tools/vectors/lightning-bolt11/); BOLT #12's 53 offer vectors and 12 format strings, valid and invalid (tools/vectors/lightning-bolt12/).
Random cases Random BIP-39 seeds and entropies on every network; every aezeed case again with the aes crate's software round against LND's AEZ without assembly; random words, a wrong version with a right checksum, published seeds under a changed passphrase, a changed enciphered byte or salt with the checksum put right, a changed word, each refused by LND's code; 150 invoices written with every kind of field (amounts in every multiplier, description or its hash, payee key, expiry, final cltv, fallbacks of every version, route hints, features, metadata, fields BOLT #11 does not define) and signed, read by Faraday and by the package field by field, then each with one Bech32 character changed, with one letter in upper case, and with two of these spoiled: a repeated p or x, a wrong-length p, s, h or n, no p, no s, both or neither of d and h, an unknown required feature, a leading zero value in a longer x, c or 9, a leading zero or a fraction of a millisatoshi in the amount, a bad multiplier, an unknown network, a high-S signature, a field cut short, a text over 1023 characters, a description that is not UTF-8; for Core Lightning, random plain and encrypted hsm_secrets under random passphrases (opened by Faraday and by libsodium, node ids compared), a secret sealed by libsodium and opened by Faraday and by Core Lightning's functions, a changed byte, a wrong passphrase and a wrong length each refused by both, random mnemonic-form files with and without a passphrase (node ids compared; a wrong passphrase, a passphrase the file does not have and broken words each refused by both), and random BIP-39 words with a passphrase; 250 rounds of BOLT #12 offers, each an offer written with every kind of field (chains, metadata, a currency or an amount in millisatoshis, description, features, expiry, blinded paths, issuer, quantity, issuer id, unknown odd fields; + joins, upper case and a lightning: prefix) read by Faraday and by Core Lightning's decoder field by field and by the writer's own record, then one with a Bech32 character changed, one in mixed case, and three of thirty-eight spoils: types out of order or repeated, a field cut short or longer than the stream, a BigSize, truncated integer or feature field not minimal, a type outside the offer's ranges or an unknown even one, a text that is not BOLT #1's, an amount without a description, of zero, or a currency without an amount, no issuer id and no path, a path of no hops or a bad point, chains empty or of a wrong length, padding of more than four bits, a bad +, a wrong prefix, characters outside Bech32, and F232's stricter cases (a text over 4,296 characters, a non-zero padding bit, a chain twice or none known, a currency not in ISO 4217, an amount above 21 million bitcoin, an expiry past the year 9999, a first node byte that is no key, an unassigned character).
Differences BOLT #11 invoices: the package skips a p, h, s or n field of the wrong length, reads the first of a repeated p or s, and accepts both or neither of a description and its hash, mixed case, an amount finer than a millisatoshi and a leading zero value in x, c or 9, all of which BOLT #11 makes a refusal or says "should" of and Faraday refuses; it also accepts what BOLT #11 leaves open, which Faraday is stricter on: a repeated x, c, m, 9, d, h or n, a text over 1023 characters, an amount with a leading zero, and a required feature bit Faraday does not know; the area counts each refusal as known, naming its reason.
BOLT #11 route hints: the package reads a hop's fees and delta as signed integers (a fee above 2^31 reads negative); the area reads them modulo 2^32 and 2^16 before comparing, and keeps a hint to three hops, as the package drops the last hop of a hint of a multiple of five.
BOLT #11 fallbacks: the package reads only the first fallback address and writes the others in bech32 for every witness version, no bech32m; the area compares Faraday's whole list of fallbacks with the writer's f fields of versions 0 to 18, in order, and its fields of an unknown version by the writer's list.
BOLT #11 features: the package keeps one state per feature, so a feature with both its required and its supported bit set reads as supported only; the writer sets one bit of each pair.
BOLT #12 offers: Core Lightning's bolt12-cli passes the decoder no feature set, so it reads an offer with an even feature bit that Faraday refuses (BOLT #9 defines no offer feature); it also reads feature bytes with a leading zero byte, which BOLT #9 makes not minimal, and a description, issuer or currency holding a character of Unicode's Cc, Cf, Co, Zl or Zp categories, which BOLT #1 refuses and Faraday refuses; and it refuses what Faraday reads when the currency is missing from its ISO 4217 table (the list of 2018) or an amount in bitcoin has a first chain Faraday does not know (it names the unit by the first chain alone), which Faraday reads as BOLT #12 says; the area counts each as known, naming the reason, and every other difference fails the run.
BOLT #12 offers, F232's stricter cases: Faraday refuses what Core Lightning reads (a text over 4,296 characters, a non-zero padding bit, whitespace after a + that is not a space, tab or line break, a chain twice, no known chain, a currency not in the ISO 4217 list Faraday holds, an amount over 21 million bitcoin, an expiry past the year 9999, a first node that is no key, an unassigned character); the area requires Faraday's refusal and counts it as known.
When it runs Before every release, with a new seed and about ten times the cases.
Last passing runSeed 5be11ec606a76d2767f225b8992c45fe · 14060 cases
Reading only: no offer is written, requested, paid or stored.
A text over 4,296 characters, mixed case, an invoice request or a field outside the offer's ranges is refused.
An expiry is shown and not judged against the clock; odd fields BOLT #12 does not define are listed and not used.
Faraday's own calls
BOLT #12 and BOLT #1 make mixed case, a misplaced `+`, a malformed TLV stream, a type outside the offer's ranges, an unknown even type, an unknown required feature, text that is not BOLT #1's UTF-8, an amount of zero or without a description, a currency without an amount, an offer naming neither an issuer id nor a path, a path of no hops, a point that is not a curve point, empty chains and more than four bits of padding a refusal, and Faraday refuses them. Where BOLT #12 leaves a case open, Faraday refuses the offer: a text over 4,296 characters (what a QR code holds in capital letters), a non-zero padding bit, whitespace after a `+` other than spaces, tabs and line breaks, a chain named twice, chains naming no Bitcoin network Faraday knows, a currency that is not in its ISO 4217 list, an amount over 21 million bitcoin, an expiry past the year 9999, an offer_paths that holds no path, and a character of Unicode's Cn category. Conservative, F232.
Derives a silent payments address, labels and scan key (BIP 352, 392) and finds the payments a transaction makes to them; reads and writes BIP 392's sp() descriptor.
BIP 321, URI Scheme for Bitcoin Payments, Complete, vendored
BIP 353, DNS Payment Instructions, Complete, vendored
Code
Library: bitcoin 0.32.102, by the rust-bitcoin developers.
Library: secp256k1 0.29.1, by the rust-bitcoin developers (rust-secp256k1), over libsecp256k1, by Bitcoin Core's libsecp256k1 project (bitcoin-core/secp256k1).
Library: sha2 0.11.0, by the RustCrypto developers, through core/faraday-crypto.
Library: base16ct 1.0.0, by the RustCrypto developers, through core/faraday-crypto.
Faraday's code: core/faraday-bip: The scan and spend keys are taken at BIP 352's paths; a transaction's eligible inputs give the input hash and shared secret, and every output it pays to the wallet is found with the label it was paid to, up to K_max; the scan private key leaves only as BIP 392's spscan1q text, or the sp() descriptor over it with its key origin, for a named reason. An sp() descriptor, or its key alone after its origin, is read as a silent payments record: the scan key is read for its public key, in constant time, and wiped; an origin that is missing or not BIP 352's path on the key's network is refused, as are sp(KEY,KEY), spspend and a key with a derivation; a text that holds a scan key is a wallet file in Files, and one that holds a spend key a secret no scanner files. The app's check of a transaction takes its previous transactions one at a time and gives the previous outputs, in input order, once every one is known.
Written by Faraday
BIP-352 silent payments (faraday-bip::silent) · No established implementation exists
libsecp256k1's silent payments module is not yet in its Rust bindings.
Compared with others' code: BIP-352's reference.py, by the BIP's authors, over secp256k1lab, and btclib-wallet's silent_payments.py, by the btclib developers, on btclib's own curve: addresses, labels, input keys and hash, the sender's outputs and the receiver's scan; for BIP 392's spscan key, which has no published code or vectors, that reference's bech32m and curve and btclib's.
Area sp
Faraday's code faraday_bip::silent
Compared with BIP-352's reference.py (bip352/); btclib-wallet's silent_payments.py (btclib/, its own curve) answering every operation beside it.
Checked first: Its vendored files are hashed against references.sha256 before any run, and a published vector's answer is required of the reference as well as of Faraday.
Vectors Every case of tools/vectors/bip352/, both sides, each answered by btclib-wallet too.
Random cases Inputs of every kind BIP-352 reads, receivers with labels, a sender's outputs and what each receiver finds among them and decoys.
Differences BIP-352: Faraday's sender arithmetic is test-only and has no K_max, so the vector that exceeds it is checked on the receiving side only.
BIP-352's skip of a transaction spending SegWit version 2 or above, which the reference and btclib-wallet leave to their caller, is written in the area from the BIP's own sentence.
BIP-392 publishes no reference code or vectors: its spscan expression is written and read with the BIP-352 reference's bech32m and curve, as BIP-392 states the payload, and the sp() around it is read in the area from the BIP's text. Faraday's own, expected from its rule: an sp() with no key origin, which BIP-392 allows, is refused, as is an origin other than BIP-352's path.
When it runs Before every release, with a new seed and about ten times the cases.
Last passing runSeed 5be11ec606a76d2767f225b8992c45fe · 1000 cases
A label tweak times G is libsecp256k1's ecmult_gen through a secret key, in a randomized context; the output tweak is treated as public and multiplied by ecmult, as libsecp256k1's own silent payments module does.
The scan key and the texts that carry it are written in fixed buffers that zeroize on drop. SecretKey is Copy, so every add_tweak, mul_tweak and negate copies the key and only the last copy is erased; the earlier copies are left in memory, later work under the security scope (ESTABLISHED §4.1).
Limits
Scanning stops at K_max, 2323 outputs for one scan key.
A script type the protocol does not list, a taproot input under H, an uncompressed key and a scriptSig holding no key matching its hash are skipped.
The wallet record keeps public values only.
Faraday's own calls
The faraday-silent 1 record holds the kind, the network, the key's origin, the label count and the address. Neutral.
Reads a version 0 PSBT from bytes or base64 and writes it back as it was read.
Specification
BIP 174, Partially Signed Bitcoin Transaction Format, Deployed
Code
Library: bitcoin 0.32.102, by the rust-bitcoin developers.
Library: miniscript 12.3.7, by the rust-bitcoin developers (rust-miniscript), through core/faraday-bip.
Library: sha2 0.11.0, by the RustCrypto developers, through core/faraday-crypto.
Library: base64ct 1.8.3, by the RustCrypto developers, through core/faraday-bip.
Faraday's code: core/faraday-psbt: Refuses a version other than 0, version 2 fields inside a version 0 file, a 65-byte taproot signature whose sighash byte is 0 (BIP 341) and a key origin of more than 16 steps; a field not changed since it was read is written back exactly as read. The app tells a file is a PSBT by reading it once as bytes, else as base64 text, when it comes in.
Written by Faraday
PSBT inspection, signing orchestration and verification logic (faraday-psbt) · Faraday's own specification
What Faraday checks before it signs is Faraday's own rule; the PSBT format itself is rust-bitcoin's.
Published, by BIP 174's and RFC 6979's authors; the spends and finalized answers Bitcoin Core v31.1 made on regtest. Faraday's own known answers: the wallet policies, the warning PSBTs and the PSBTs this tree signed.
tools/vectors/psbt-bips
Published, by the authors of BIP 174, BIP 370 and BIP 371 (bitcoin/bips).
Compared with others' code: Bitcoin Core v31.1 (decodepsbt, and combinepsbt as its writer), by Bitcoin Core's contributors; HWI's psbt.py, by Ava Chow and HWI's contributors, for the version 2 fields BIP-370 refuses in version 0; btclib-wallet's Psbt.parse, by the btclib developers, which also refuses a 65-byte taproot signature whose sighash byte is 0 (BIP-341).
Compared with Bitcoin Core v31.1's bitcoind on regtest for version 0 (decodepsbt, combinepsbt of one PSBT as its writer, the test framework's taproot_tree_helper); HWI's psbt.py (hwi/) for version 2 and the version 2 fields refused in version 0, its version 0 form read by Core; btclib-wallet's Psbt (btclib/, on btclib's own curve) for both versions: parse, lock_time, tx, to_v0 and to_v2, which also decides the refusals of a taproot signature whose sighash byte is 0, of bytes after the last map and of a stream that ends inside a map.
Checked first: Core's release tarball is checked against its pinned SHA-256 (tools/reference/core/release.pin) before every run, and the node's version is asked; HWI's vendored files and btclib's wheels are hashed against references.sha256 before any run; a published vector's answer is required of the side that decides.
Whether a PSBT_GLOBAL_VERSION of 0 is written: Core reads a version 0 PSBT alike with it or without it, and Faraday writes it back as read.
Vectors Every PSBT of BIP-174's, 370's and 371's test vectors (tools/vectors/psbt-bips/), with BIP-370's locktimes, read by btclib too.
Random cases Random version 0 and 2 PSBTs with every field Faraday reads, taproot trees among them, in random order, read field for field as Core reads them and written back byte for byte as read and as Core writes them, then broken one rule at a time; each version 0 PSBT made version 2 as HWI's convert_to_v2 and btclib's to_v2 make it, and back to its own bytes; BIP-370's locktime, transaction and version 0 form under every mix of required locktimes, also btclib's lock_time, tx and to_v0; one version 0 PSBT in eight carries fields btclib refuses and btclib is not asked of it.
Differences Version 0 made version 2: HWI's convert_to_v2 leaves out the PSBT_OUT_SCRIPT of an output whose script is empty, which BIP-370 requires; Faraday and btclib write it, and the rest of the PSBT must be the same.
Bitcoin Core reads a version 0 PSBT with a version 2 field as valid, the field as unknown; Faraday refuses it, as BIP-370 does, and so do HWI, which decides it, and btclib.
A taproot signature of 65 bytes whose sighash byte is 0, which neither Core nor HWI refuses, and bytes after a version 2 PSBT's last map or a stream that ends inside one, which HWI reads: Faraday refuses each, as BIP-341 and BIP-174 do, and so does btclib, which decides them (the stream ending inside a map checked, as the specification marked it not checked).
PSBT version 2 (faraday_psbt::v2): a BIP-370 key with key data is an unknown key; BIP-174's and BIP-371's fields inside are checked only when the PSBT is bridged to version 0, except a taproot signature whose sighash byte is 0, refused on reading. HWI checks them on reading; the area requires HWI and btclib to read the PSBT without those pairs, to Faraday's locktime and transaction. Where HWI reads a value shorter than its length says and makes a version 0 PSBT of it, which Faraday does not, Core must refuse the version 0 PSBT of the PSBT's own pairs, and btclib refuses the PSBT.
Btclib reads some PSBTs that Core and Faraday refuse (a key with key data on a field that takes none, for one): btclib is not asked to refuse what Core refuses, only what Core and HWI read and Faraday refuses.
Btclib refuses what the BIPs allow: an ECDSA signature that is not strict DER with a low S and an r that is a point's x, a sighash type of the seven it defines, a BIP-375 field in a version 0 global map, a previous transaction and a witness UTXO that disagree. About one version 0 PSBT in eight carries such a field, and btclib is not asked of it or of what is made from it. Pairs btclib does not write back as read (an empty final witness) and what it writes in their place are left out of the conversions it is compared on, and leaf hashes are compared sorted, as it writes them.
When it runs Before every release, with a new seed and about ten times the cases.
Last passing runSeed 5be11ec606a76d2767f225b8992c45fe · 15000 cases
SpecificationBIP 370PublishedCodeLibrary: bitcoin 0.32Faraday's code: core/faraday-psbtFaraday's own codeCross-checked withHWI's psbt.py (readingOthers' codeFaraday's second version
Action
Reads a version 2 PSBT as its key-value maps, checks BIP 370's shape and converts it to version 0 and back.
Specification
BIP 370, PSBT Version 2, Deployed
Code
Library: bitcoin 0.32.102, by the rust-bitcoin developers.
Faraday's code: core/faraday-psbt: bitcoin reads version 0 only, so the maps are read here. Every pair is kept as read and written back with what was set; a version 2 PSBT becomes version 0 once every output has a script, and only the signing fields (partial signatures, final scripts, taproot and MuSig2 signatures and nonces) are taken back from it. A version 0 PSBT becomes version 2 and back to its own bytes. The app reads a version 2 file wherever it reads a PSBT, signs its version 0 form and writes the version 2 PSBT that came in with the signatures added; where they do not go back into it, nothing is written or shown, never the version 0 form.
Written by Faraday
The PSBT version 2 reader (faraday-psbt::v2) · No established implementation exists
rust-bitcoin reads only version 0 PSBTs; its version 2 crate is pre-release.
Compared with others' code: HWI's psbt.py (reading, compute_lock_time, get_unsigned_tx, convert_to_v0, convert_to_v2), by Ava Chow and HWI's contributors, with both version 0 forms read by Bitcoin Core v31.1; btclib-wallet's Psbt (parse, lock_time, tx, to_v0, to_v2), by the btclib developers, which also refuses bytes after the last map, a stream that ends inside a map and a 65-byte taproot signature whose sighash byte is 0.
Compared, for one part, with Faraday's second version, written by Faraday's authors in Python; that part is not checked against an outside source: the choice of the pairs Faraday leaves to the bridge to version 0, and the version 0 PSBT of a PSBT's own pairs that Core judges where HWI repairs a short value, written in area_psbt.py.
Compared with Bitcoin Core v31.1's bitcoind on regtest for version 0 (decodepsbt, combinepsbt of one PSBT as its writer, the test framework's taproot_tree_helper); HWI's psbt.py (hwi/) for version 2 and the version 2 fields refused in version 0, its version 0 form read by Core; btclib-wallet's Psbt (btclib/, on btclib's own curve) for both versions: parse, lock_time, tx, to_v0 and to_v2, which also decides the refusals of a taproot signature whose sighash byte is 0, of bytes after the last map and of a stream that ends inside a map.
Checked first: Core's release tarball is checked against its pinned SHA-256 (tools/reference/core/release.pin) before every run, and the node's version is asked; HWI's vendored files and btclib's wheels are hashed against references.sha256 before any run; a published vector's answer is required of the side that decides.
Whether a PSBT_GLOBAL_VERSION of 0 is written: Core reads a version 0 PSBT alike with it or without it, and Faraday writes it back as read.
Vectors Every PSBT of BIP-174's, 370's and 371's test vectors (tools/vectors/psbt-bips/), with BIP-370's locktimes, read by btclib too.
Random cases Random version 0 and 2 PSBTs with every field Faraday reads, taproot trees among them, in random order, read field for field as Core reads them and written back byte for byte as read and as Core writes them, then broken one rule at a time; each version 0 PSBT made version 2 as HWI's convert_to_v2 and btclib's to_v2 make it, and back to its own bytes; BIP-370's locktime, transaction and version 0 form under every mix of required locktimes, also btclib's lock_time, tx and to_v0; one version 0 PSBT in eight carries fields btclib refuses and btclib is not asked of it.
Differences Version 0 made version 2: HWI's convert_to_v2 leaves out the PSBT_OUT_SCRIPT of an output whose script is empty, which BIP-370 requires; Faraday and btclib write it, and the rest of the PSBT must be the same.
Bitcoin Core reads a version 0 PSBT with a version 2 field as valid, the field as unknown; Faraday refuses it, as BIP-370 does, and so do HWI, which decides it, and btclib.
A taproot signature of 65 bytes whose sighash byte is 0, which neither Core nor HWI refuses, and bytes after a version 2 PSBT's last map or a stream that ends inside one, which HWI reads: Faraday refuses each, as BIP-341 and BIP-174 do, and so does btclib, which decides them (the stream ending inside a map checked, as the specification marked it not checked).
PSBT version 2 (faraday_psbt::v2): a BIP-370 key with key data is an unknown key; BIP-174's and BIP-371's fields inside are checked only when the PSBT is bridged to version 0, except a taproot signature whose sighash byte is 0, refused on reading. HWI checks them on reading; the area requires HWI and btclib to read the PSBT without those pairs, to Faraday's locktime and transaction. Where HWI reads a value shorter than its length says and makes a version 0 PSBT of it, which Faraday does not, Core must refuse the version 0 PSBT of the PSBT's own pairs, and btclib refuses the PSBT.
Btclib reads some PSBTs that Core and Faraday refuse (a key with key data on a field that takes none, for one): btclib is not asked to refuse what Core refuses, only what Core and HWI read and Faraday refuses.
Btclib refuses what the BIPs allow: an ECDSA signature that is not strict DER with a low S and an r that is a point's x, a sighash type of the seven it defines, a BIP-375 field in a version 0 global map, a previous transaction and a witness UTXO that disagree. About one version 0 PSBT in eight carries such a field, and btclib is not asked of it or of what is made from it. Pairs btclib does not write back as read (an empty final witness) and what it writes in their place are left out of the conversions it is compared on, and leaf hashes are compared sorted, as it writes them.
When it runs Before every release, with a new seed and about ten times the cases.
Last passing runSeed 5be11ec606a76d2767f225b8992c45fe · 15000 cases
Reads what a PSBT spends and pays: amounts, fee, verified change, warnings, and the wallet it defines for registering.
Specification
BIP 174, Partially Signed Bitcoin Transaction Format, Deployed
BIP 173, Base32 address format for native v0-16 witness outputs, Deployed
BIP 350, Bech32m Format for v1+ Witness Addresses, Deployed
Code
Library: bitcoin 0.32.102, by the rust-bitcoin developers.
Library: miniscript 12.3.7, by the rust-bitcoin developers (rust-miniscript).
Library: sha2 0.11.0, by the RustCrypto developers, through core/faraday-crypto.
Library: base16ct 1.0.0, by the RustCrypto developers, through core/faraday-crypto.
Faraday's code: core/faraday-psbt: Change is verified only when the output's script is the address a loaded key's account, or a registered wallet, derives at the stated path; a claim on a loaded key that derives another script is a block. Warnings are ranked Info, Caution, Danger and Blocked. A wallet is offered for registering only when the PSBT's global xpubs give every script of its inputs and outputs. A PSBT's network is read from its global xpubs, else from the coin type of a BIP 44, 49, 84, 86 or 48 key path, else it is the session's. The signed-amount memory keeps the SHA-256 of the unsigned transaction and the amount each input states, and only when every input states one. Another device's signatures are merged only into a PSBT of the same transaction that asks the same sighashes, and are refused when one is invalid. The register sheet's hold registers a wallet only once its descriptor gives the spend's scripts and one of its keys is a loaded key's own at its path. An output over 21,000,000 BTC, outputs whose total is over it, or an amount an input states or their total over it, is a block, as Bitcoin Core's CheckTransaction and CheckTxInputs refuse them (`transaction::money_total`).
Checked against
tools/vectors/psbt
Published, by BIP 174's and RFC 6979's authors; the spends and finalized answers Bitcoin Core v31.1 made on regtest. Faraday's own known answers: the wallet policies, the warning PSBTs and the PSBTs this tree signed.
Compared with others' code: btclib-wallet's descriptor wallet (update_psbt_output, index_of), by the btclib developers, on btclib's own curve; Bitcoin Core v31.1 (decodepsbt, analyzepsbt, deriveaddresses, and a watch-only descriptor wallet's getaddressinfo and walletprocesspsbt), by the Bitcoin Core developers.
Compared, for one part, with Faraday's second version, written by Faraday's authors in Python; that part is not checked against an outside source: the rule that a script of several keys, a miniscript or a taproot tree is change only for a registered wallet, which outputs claim a held key, and the account keys a registered wallet names, derived in the area.
Area psbt-review
Faraday's code faraday_psbt::inspect (amounts in and out, the fee, verified change and the spoofed-change and missing-UTXO warnings), over faraday_psbt::Psbt and the keys and registered wallets the Sign screen holds
Compared with Bitcoin Core v31.1's bitcoind on regtest, offline: decodepsbt and analyzepsbt for amounts and fee, deriveaddresses from tprv descriptors for the addresses the PSBTs pay, createpsbt, createrawtransaction and descriptorprocesspsbt to make the PSBTs; btclib's descriptor wallet (update_psbt_output and index_of, btclib/, its own curve) for which outputs are change; a watch-only descriptor wallet on the same node (getaddressinfo, walletprocesspsbt) for where each change claim's script is; the area adds each input's UTXO fields, splices a spoofed output, derives the account keys a registered wallet names (checked by Core deriving the same addresses from them), and keeps the rule that a script of several keys is change only for a registered wallet.
Checked first: Core's release tarball is checked against its pinned SHA-256 (tools/reference/core/release.pin) before every run, and the node's version is asked; every PSBT is one Core made and read, and every change decision is btclib's whole-script comparison at the chain and index the output states, which Core's own wallet must find at the same place.
Faraday's other warnings (high fee, dust, address reuse, sighash, network, locktime) and thresholds, which are Faraday's own rules; the estimated virtual size and fee rate (Core's estimate needs signing data the PSBT does not carry).
Vectors none: Core's decoding and btclib's change decision are the references, over each wallet shape with change, spoofed change, a foreign claim and missing UTXO data in the prelude.
Random cases PSBTs of one to three inputs and one to four outputs over single-key accounts (P2PKH, P2SH-P2WPKH, P2WPKH, P2TR) and registered wallets (sortedmulti in P2WSH, a miniscript in P2WSH, a taproot tree, a taproot sortedmulti_a) or the same wallets unregistered: witness UTXOs, previous transactions and no UTXO data, fees from nothing to a third of the inputs, payments, change on either chain, another wallet's change, and spoofed change over the wallet's own script at another index, another wallet's and a stranger's; one key held, two, or none of the wallet's.
Differences Change of a script of several keys, a miniscript or a taproot tree: Faraday verifies it only for a registered wallet that holds a loaded key, and counts it as paid to others otherwise, which btclib's descriptor wallet has no notion of. The area expects the same refusal, and does not compare the spoof warning for an unregistered wallet (Faraday's reading of such a claim depends on the account path it states).
When it runs Before every release, with a new seed and about ten times the cases.
Last passing runSeed 5be11ec606a76d2767f225b8992c45fe · 2000 cases
Only public account keys are derived from a master key; the review compares public data. The library does not state the derivation's timing.
The review keeps public keys only; the derived private keys are dropped inside the master key's account_xpub.
Limits
Supported input scripts: p2pkh, p2sh-p2wpkh, p2wpkh, p2tr key path, and multi or sortedmulti in p2sh, p2wsh and p2sh-p2wsh, with miniscript and taproot trees through a registered wallet.
Multisig change is verified only by re-deriving it from a registered wallet.
A SegWit v0 input with no previous transaction in a transaction of several inputs is blocked.
Only a high fee and an absurd fee rate can be held past; every other danger and every block has no way past.
Another device's PSBT for another transaction, one that asks another sighash of an input and one with a signature that does not verify are refused, never merged.
An amount or a total over 21,000,000 BTC, in the outputs or the amounts the inputs state, blocks signing.
Faraday's own calls
Change under an unloaded key, or at a path under no loaded account, counts as a payment to others. Conservative, F136.
A script of several keys is signed only for a registered wallet that holds a loaded key. Conservative, F135.
A miniscript or a taproot tree of one key is signed only through its registered wallet. Conservative, F141.
A SegWit v0 input with only a witness UTXO in a transaction of several inputs is refused, which BIP 174 allows. Conservative, F155.
The signed-amount memory refuses one transaction stated again with other amounts. Conservative, F155.
Reads each input's sighash type and signs SIGHASH_ALL and SIGHASH_DEFAULT, and ALL with ANYONECANPAY after a caution.
Specification
BIP 143, Transaction Signature Verification for Version 0 Witness Program, Deployed
BIP 341, Taproot: SegWit version 1 spending rules, Deployed
BIP 342, Validation of Taproot Scripts, Deployed
Code
Library: bitcoin 0.32.102, by the rust-bitcoin developers.
Faraday's code: core/faraday-psbt: Names the sighash kind of every input; ALL|ANYONECANPAY is a caution, NONE, a non-standard value and SINGLE with an output are dangers with no way past, SINGLE with no output of its index is blocked. The tx area checks the signature hashes bitcoin computes for each type; the naming and ranking of a sighash is not cross-checked.
Checked against
tools/vectors/sighash
Published, by Bitcoin Core's sighash.json, v31.1, by the Bitcoin Core developers; BIP 143's and BIP 341's authors.
Compared with others' code: btclib's sig_hash (legacy, segwit_v0 and taproot), by the btclib developers; and Bitcoin Core's functional-test framework, v31.1, by Bitcoin Core's contributors.
Area tx
Faraday's code faraday_psbt::transaction::read_raw, faraday_core::decode::decode's txid, wtxid and output addresses, bitcoin's SighashCache as faraday_psbt::sign calls it
Compared with btclib's Tx.parse and sig_hash (btclib/); Bitcoin Core v31.1's decoderawtransaction on regtest (core_node.py) for the transactions; Core's messages.py and script.py (core/) for the signature hashes; the refusal of a transaction with no inputs is ours.
Checked first: Its vendored files and the btclib wheels are hashed against references.sha256 before any run, and a published vector's answer is required of the reference as well as of Faraday; each published signature hash is checked against the framework first.
Random cases Random transactions with and without witnesses (txid, wtxid, weight, bytes) read by btclib and Core's decoderawtransaction, cut or lengthened, and shown by Faraday's Decode view (txid, wtxid, each output's address, none where Core gives none) against Core's; every input hashed as legacy, BIP-143 P2WPKH and P2WSH, BIP-341 key and script path under every hash type, by btclib and the framework.
Differences Decode refuses a transaction whose outputs total over 21,000,000 BTC, as Core does not in decoderawtransaction; the corpus asks Decode only of transactions within that total.
Legacy sighash: bitcoin hashes the script code as given, Core and btclib remove every OP_CODESEPARATOR first. Faraday's legacy spends (P2PKH, P2SH multisig) have none.
Core's decoderawtransaction reads bytes whose marker 00 01 it takes as a count of no inputs and one output, a legacy transaction of no inputs; Faraday refuses a transaction with no inputs, and the area counts a case where btclib reads inputs of such bytes as this difference.
BIP-341's refusals (SIGHASH_SINGLE without an output, a hash type it does not list) are btclib's: the framework hashes those anyway and is not asked.
When it runs Before every release, with a new seed and about ten times the cases.
Last passing runSeed 5be11ec606a76d2767f225b8992c45fe · 30000 cases
SpecificationBIP 143 · BIP 174 · RFC 6979PublishedCodeLibrary: secp256k1 0.29Library: bitcoin 0.32Faraday's code: core/faraday-psbtCross-checked withBitcoin Core v31.1Others' codeFaraday's second version
Action
Signs a transaction input with ECDSA, from the key the PSBT's origin names, and checks the key against the script.
Specification
BIP 143, Transaction Signature Verification for Version 0 Witness Program, Deployed
BIP 174, Partially Signed Bitcoin Transaction Format, Deployed
RFC 6979, Deterministic Usage of the Digital Signature Algorithm (DSA) and Elliptic Curve Digital Signature Algorithm (ECDSA), Informational
Code
Library: secp256k1 0.29.1, by the rust-bitcoin developers (rust-secp256k1), over libsecp256k1, by Bitcoin Core's libsecp256k1 project (bitcoin-core/secp256k1).
Library: bitcoin 0.32.102, by the rust-bitcoin developers.
Faraday's code: core/faraday-psbt: Derives the key at the origin's path from the matching master key and refuses unless it is the key named and the script holds it; grinds for a low r by default; signs twice and refuses unless the bytes match; verifies the signature before writing it. faraday-keys lends the master keys and passes the default nonce and aux_rand choices.
Checked against
tools/vectors/psbt
Published, by BIP 174's and RFC 6979's authors; the spends and finalized answers Bitcoin Core v31.1 made on regtest. Faraday's own known answers: the wallet policies, the warning PSBTs and the PSBTs this tree signed.
no fuzz target: No target runs sign: it needs a master key and a PSBT that inspect accepts; psbt_parse fuzzes the PSBT it reads
Cross-check
Compared with others' code: Bitcoin Core v31.1, by the Bitcoin Core developers (descriptorprocesspsbt signs, testmempoolaccept judges the spend), with Core's key.py and script.py for the first RFC 6979 nonce; python-ecdsa, by Brian Warner and Hubert Kario (no Bitcoin code), which makes that nonce's signature again byte for byte and verifies the low-R ones; Core shares libsecp256k1's curve maths with Faraday's.
Compared, for one part, with Faraday's second version, written by Faraday's authors in Python; that part is not checked against an outside source: Faraday's refusals (F136, F141) and the inputs a wallet's rule leaves unsigned, the script code of the hash the first RFC 6979 nonce is checked under, in area_sign.py; the keys of those checks are btclib's.
Area sign
Faraday's code faraday_psbt::sign (every held key selected, deterministic Schnorr, both RFC 6979 nonce rules) and faraday_psbt::finalize
Compared with Bitcoin Core v31.1 on regtest (core_node.py): descriptorprocesspsbt signs from the held masters' keys, finalizepsbt finalizes and extracts, testmempoolaccept judges each finalized transaction over its funding on the node; BIP-340's reference (secp256k1lab) and Core's key.py for the deterministic nonces, over Core's script.py sighashes; python-ecdsa (the distribution's package) and btclib (btclib/, its own curve) as a second curve lineage, beside them: every ECDSA signature again under plain RFC 6979 or verified, every BIP-340 signature verified and made again; btclib-wallet's finalizer (psbt.finalize with its miniscript solver) finalizes every input Faraday finalizes again and gives the same scriptSig and witness; for each sweep, btclib reads the WIF (scalar, compression, public key) and signs and finalizes the sweep on its own curve, and python-ecdsa makes the first-nonce signature of each input again, byte for byte; python-bip380 (miniscript/) reads the leaves. Faraday's refusals and the inputs a wallet's rule leaves unsigned are ours, in area_sign.py.
Checked first: Core is the pinned release, hashed against its pin before every run; the vendored files are hashed against references.sha256; a published vector's answer is required of Core as well as of Faraday; every ECDSA and BIP-340 signature Core makes is checked to verify under the hash the area computes before that hash is used for Faraday's deterministic nonces.
Vectors BIP-174's signer, finalizer and extractor vectors; the Core-built spends of tools/vectors/psbt/ (2-of-3 sortedmulti, the Liana wallet down both paths, a taproot tree by a leaf and by the key path, BIP 387's taproot multisig), signed by every subset of their keys; the finalizer vectors there (or_b's smaller signature, the taproot leaves that tie by count, the taproot multisig and MuSig2 spends).
Random cases PSBTs of one to four inputs, each spending a funding output on the node: P2PKH, P2SH-P2WPKH, P2WPKH, multi/sortedmulti in P2SH, P2WSH and P2SH-P2WSH, P2TR key path, P2TR script path (pk, pkh, timelocked keys, or_d, multi_a) with the key path beside it, miniscript in P2WSH and P2SH-P2WSH; held and foreign keys, cosigners' signatures already on (Core's), every standard sighash type, timelocks met and not; Core's signatures (ECDSA byte for byte, BIP-340 by verification and the deterministic nonce), each final scriptSig and witness and the extracted transaction Core's, the cleared fields, and every finalized transaction accepted by Core's mempool; an origin that derives another key refused; sweeps: a WIF key's P2PKH, P2WPKH and P2SH-P2WPKH outputs (P2PKH alone for an uncompressed key) spent beside another key's, signed by Core from the WIF and by faraday_psbt::sweep::sign, byte for byte, finalized and accepted by the mempool.
Differences PSBT signing: Faraday refuses to sign a SegWit v0 input with no previous transaction in a transaction of more than one input; Core signs it, and BIP-174's own signer vector is such a PSBT. The refusal is ours, checked and counted. Faraday holds a finalized input to the same rule and refuses the PSBT when such an input is final, except a taproot one, whose final witness is the coordinator's.
PSBT signing, wallets: Faraday signs an input spent from a script of several keys (a multi of two or more, a miniscript naming two or more, a taproot script path whose carried leaves name two or more with its internal key, or are not its whole tree) only for a registered wallet that holds one of its keys and whose script it is; Core signs any. The area refuses, by a rule of its own, where no wallet the request registers holds a held key and gives the input, and counts it only where Faraday's refusal is that the wallet is not registered. A miniscript or a taproot tree of one key is signed only through such a wallet, and is otherwise left unsigned while the rest is signed (F141); the area takes Core's signatures off it. Half the corpus's multi, miniscript and taproot-tree inputs come with their wallet registered, so their signatures are still compared. A registered tree's every leaf has its wait met, since Faraday refuses a path that can never be valid, which the area does not work out.
PSBT signing: Faraday refuses a PSBT any input of which asks for a NONE or SINGLE sighash, and one that none of the held keys can sign: dangers no hold accepts (F136). Core signs the first and answers the second with nothing signed. The area expects both refusals by a rule of its own, counting a held key as taking part as Faraday's inspection does (a miniscript or a taproot tree only through a wallet in use), checks that Faraday's refusal names the danger, and counts them.
Taproot pkh leaves: Faraday signs a taproot leaf that checks its key by hash but does not finalize it: miniscript 12's finalizer looks the key up among the ECDSA origins and panics, and would push 33 bytes where the leaf hashed 32. Core finalizes such a leaf; the area takes the signatures under it off before Core finalizes, and counts each input Core would otherwise have finalized another way.
btclib's finalizer writes no taproot leaf that is neither a single key nor multi_a, and refuses to choose among leaves a PSBT signs: an input of another leaf is judged by Core alone (counted as a known difference), and btclib is given only the signatures of the leaf Faraday spent. It writes a plain multisig from the smallest m signatures on hand where Core and Faraday write the first m signers': btclib is given only the signatures Faraday's input carries, so it judges the script written from them and Core judges which were chosen.
When it runs Before every release, with a new seed and about ten times the cases.
Last passing runSeed 5be11ec606a76d2767f225b8992c45fe · 1580 cases
libsecp256k1 documents its signing as constant time; the low-R grind repeats the signing until r is small, so the number of signings varies, which the library does not address.
The derived key lives in the signing function's frame and is wiped when it is dropped; no secret leaves faraday-keys.
Limits
ALL is signed, and ALL with ANYONECANPAY after a caution; NONE, SINGLE and non-standard sighashes are refused.
A SegWit v0 input with no previous transaction, in a transaction of several inputs, is refused.
A key comes from the PSBT's origin only; a multisig key with no origin is refused.
The app signs with the low-R nonce; the first RFC 6979 nonce is the library's other choice and is not offered in the app.
Faraday's own calls
A key comes from the PSBT's origin only, under the master key's fingerprint; a key whose derived public key differs from the one named, or that the script does not hold, is refused, and an origin under an account's fingerprint matches no key. Conservative, F155.
A script of several keys is signed only for a registered wallet that holds a loaded key. Conservative, F135.
Only a high fee and an absurd fee rate can be held past; every other danger refuses. Conservative, F136.
Each signature is made twice and compared, and verified before it is written. Neutral.
Signs the inputs of a PSBT that spend a WIF key's own outputs, after a review that names each output's loaded wallet.
Specification
BIP 143, Transaction Signature Verification for Version 0 Witness Program, Deployed
BIP 174, Partially Signed Bitcoin Transaction Format, Deployed
RFC 6979, Deterministic Usage of the Digital Signature Algorithm (DSA) and Elliptic Curve Digital Signature Algorithm (ECDSA), Informational
Code
Library: secp256k1 0.29.1, by the rust-bitcoin developers (rust-secp256k1), over libsecp256k1, by Bitcoin Core's libsecp256k1 project (bitcoin-core/secp256k1).
Library: bitcoin 0.32.102, by the rust-bitcoin developers.
Faraday's code: core/faraday-psbt: An input is the key's when the output it spends pays one of the key's scripts, not by a key origin; the PSBT is inspected and a block, or a danger that is not holdable, refuses it, but for no loaded master key taking part; every input of the key is checked before the first is signed; each signature is made twice with the low-R nonce, compared and verified before it is written. The review searches each loaded wallet's first hundred addresses on each chain for every output and flags the others.
Checked against
tools/vectors/sighash
Published, by Bitcoin Core's sighash.json, v31.1, by the Bitcoin Core developers; BIP 143's and BIP 341's authors.
no fuzz target: No target runs sign: it needs a key and a PSBT that inspect accepts; psbt_parse fuzzes the PSBT and xkey the WIF it reads
Cross-check
Compared with others' code: Bitcoin Core v31.1, by the Bitcoin Core developers, which signs the same sweep from pkh(), wpkh() and sh(wpkh()) descriptors of the WIF (descriptorprocesspsbt), finalizes it and judges it (testmempoolaccept); BIP-143's published P2SH-P2WPKH example signs to its transaction; Core shares libsecp256k1's curve maths with Faraday's, so python-ecdsa, by Brian Warner and Hubert Kario, signs each sweep again under the first RFC 6979 nonce byte for byte, and btclib, by the btclib developers, signs and finalizes each on its own curve.
Area sign
Faraday's code faraday_psbt::sign (every held key selected, deterministic Schnorr, both RFC 6979 nonce rules) and faraday_psbt::finalize
Compared with Bitcoin Core v31.1 on regtest (core_node.py): descriptorprocesspsbt signs from the held masters' keys, finalizepsbt finalizes and extracts, testmempoolaccept judges each finalized transaction over its funding on the node; BIP-340's reference (secp256k1lab) and Core's key.py for the deterministic nonces, over Core's script.py sighashes; python-ecdsa (the distribution's package) and btclib (btclib/, its own curve) as a second curve lineage, beside them: every ECDSA signature again under plain RFC 6979 or verified, every BIP-340 signature verified and made again; btclib-wallet's finalizer (psbt.finalize with its miniscript solver) finalizes every input Faraday finalizes again and gives the same scriptSig and witness; for each sweep, btclib reads the WIF (scalar, compression, public key) and signs and finalizes the sweep on its own curve, and python-ecdsa makes the first-nonce signature of each input again, byte for byte; python-bip380 (miniscript/) reads the leaves. Faraday's refusals and the inputs a wallet's rule leaves unsigned are ours, in area_sign.py.
Checked first: Core is the pinned release, hashed against its pin before every run; the vendored files are hashed against references.sha256; a published vector's answer is required of Core as well as of Faraday; every ECDSA and BIP-340 signature Core makes is checked to verify under the hash the area computes before that hash is used for Faraday's deterministic nonces.
Vectors BIP-174's signer, finalizer and extractor vectors; the Core-built spends of tools/vectors/psbt/ (2-of-3 sortedmulti, the Liana wallet down both paths, a taproot tree by a leaf and by the key path, BIP 387's taproot multisig), signed by every subset of their keys; the finalizer vectors there (or_b's smaller signature, the taproot leaves that tie by count, the taproot multisig and MuSig2 spends).
Random cases PSBTs of one to four inputs, each spending a funding output on the node: P2PKH, P2SH-P2WPKH, P2WPKH, multi/sortedmulti in P2SH, P2WSH and P2SH-P2WSH, P2TR key path, P2TR script path (pk, pkh, timelocked keys, or_d, multi_a) with the key path beside it, miniscript in P2WSH and P2SH-P2WSH; held and foreign keys, cosigners' signatures already on (Core's), every standard sighash type, timelocks met and not; Core's signatures (ECDSA byte for byte, BIP-340 by verification and the deterministic nonce), each final scriptSig and witness and the extracted transaction Core's, the cleared fields, and every finalized transaction accepted by Core's mempool; an origin that derives another key refused; sweeps: a WIF key's P2PKH, P2WPKH and P2SH-P2WPKH outputs (P2PKH alone for an uncompressed key) spent beside another key's, signed by Core from the WIF and by faraday_psbt::sweep::sign, byte for byte, finalized and accepted by the mempool.
Differences PSBT signing: Faraday refuses to sign a SegWit v0 input with no previous transaction in a transaction of more than one input; Core signs it, and BIP-174's own signer vector is such a PSBT. The refusal is ours, checked and counted. Faraday holds a finalized input to the same rule and refuses the PSBT when such an input is final, except a taproot one, whose final witness is the coordinator's.
PSBT signing, wallets: Faraday signs an input spent from a script of several keys (a multi of two or more, a miniscript naming two or more, a taproot script path whose carried leaves name two or more with its internal key, or are not its whole tree) only for a registered wallet that holds one of its keys and whose script it is; Core signs any. The area refuses, by a rule of its own, where no wallet the request registers holds a held key and gives the input, and counts it only where Faraday's refusal is that the wallet is not registered. A miniscript or a taproot tree of one key is signed only through such a wallet, and is otherwise left unsigned while the rest is signed (F141); the area takes Core's signatures off it. Half the corpus's multi, miniscript and taproot-tree inputs come with their wallet registered, so their signatures are still compared. A registered tree's every leaf has its wait met, since Faraday refuses a path that can never be valid, which the area does not work out.
PSBT signing: Faraday refuses a PSBT any input of which asks for a NONE or SINGLE sighash, and one that none of the held keys can sign: dangers no hold accepts (F136). Core signs the first and answers the second with nothing signed. The area expects both refusals by a rule of its own, counting a held key as taking part as Faraday's inspection does (a miniscript or a taproot tree only through a wallet in use), checks that Faraday's refusal names the danger, and counts them.
Taproot pkh leaves: Faraday signs a taproot leaf that checks its key by hash but does not finalize it: miniscript 12's finalizer looks the key up among the ECDSA origins and panics, and would push 33 bytes where the leaf hashed 32. Core finalizes such a leaf; the area takes the signatures under it off before Core finalizes, and counts each input Core would otherwise have finalized another way.
btclib's finalizer writes no taproot leaf that is neither a single key nor multi_a, and refuses to choose among leaves a PSBT signs: an input of another leaf is judged by Core alone (counted as a known difference), and btclib is given only the signatures of the leaf Faraday spent. It writes a plain multisig from the smallest m signatures on hand where Core and Faraday write the first m signers': btclib is given only the signatures Faraday's input carries, so it judges the script written from them and Core judges which were chosen.
When it runs Before every release, with a new seed and about ten times the cases.
Last passing runSeed 5be11ec606a76d2767f225b8992c45fe · 1580 cases
libsecp256k1 documents its signing as constant time; the low-R grind repeats the signing until r is small, so the number of signings varies, which the library does not address.
The key never leaves faraday-keys; it is erased when the sweep ends.
Limits
P2PKH, P2WPKH and P2SH-P2WPKH outputs of the key are signed; a legacy input needs its previous transaction.
An output to no loaded wallet's address is flagged, and the hold signs past it.
Faraday's own calls
An output to no loaded wallet's first hundred addresses on either chain is flagged on the review, and the hold signs past it. Neutral, F171.
Each signature is made twice and compared, and verified before it is written. Neutral.
Signs a taproot input with BIP 340, by the key path or under a tap leaf's hash.
Specification
BIP 340, Schnorr Signatures for secp256k1, Deployed
BIP 341, Taproot: SegWit version 1 spending rules, Deployed
BIP 342, Validation of Taproot Scripts, Deployed
Code
Library: secp256k1 0.29.1, by the rust-bitcoin developers (rust-secp256k1), over libsecp256k1, by Bitcoin Core's libsecp256k1 project (bitcoin-core/secp256k1).
Library: bitcoin 0.32.102, by the rust-bitcoin developers.
Library: hmac 0.13.0, by the RustCrypto developers, through core/faraday-crypto.
Library: sha2 0.11.0, by the RustCrypto developers, through core/faraday-crypto.
Faraday's code: core/faraday-psbt: Signs the key path with the BIP 341 tweaked key and a leaf with the leaf's own key under its leaf hash; each signature is made twice, compared and verified; aux_rand is zero by default, and fresh bytes a caller passes are expanded for each input with HKDF-Expand (RFC 5869, faraday-crypto), which the app does not use; a miniscript or a tree is signed only through a registered wallet.
Checked against
tools/vectors/psbt
Published, by BIP 174's and RFC 6979's authors; the spends and finalized answers Bitcoin Core v31.1 made on regtest. Faraday's own known answers: the wallet policies, the warning PSBTs and the PSBTs this tree signed.
no fuzz target: No target runs sign: it needs a master key and a PSBT that inspect accepts; psbt_parse fuzzes the PSBT it reads
Cross-check
Compared with others' code: Bitcoin Core v31.1, by the Bitcoin Core developers (descriptorprocesspsbt signs, testmempoolaccept judges the spend), with BIP-340's reference (secp256k1lab) and Core's script.py for the zero-randomness nonce; btclib, by the btclib developers, on its own curve, which verifies each signature and makes it again byte for byte; Core shares libsecp256k1's curve maths with Faraday's.
Compared, for one part, with Faraday's second version, written by Faraday's authors in Python; that part is not checked against an outside source: Faraday's refusals (F136, F141) and the inputs a wallet's rule leaves unsigned, in area_sign.py; the keys of the zero-randomness check are btclib's.
Area sign
Faraday's code faraday_psbt::sign (every held key selected, deterministic Schnorr, both RFC 6979 nonce rules) and faraday_psbt::finalize
Compared with Bitcoin Core v31.1 on regtest (core_node.py): descriptorprocesspsbt signs from the held masters' keys, finalizepsbt finalizes and extracts, testmempoolaccept judges each finalized transaction over its funding on the node; BIP-340's reference (secp256k1lab) and Core's key.py for the deterministic nonces, over Core's script.py sighashes; python-ecdsa (the distribution's package) and btclib (btclib/, its own curve) as a second curve lineage, beside them: every ECDSA signature again under plain RFC 6979 or verified, every BIP-340 signature verified and made again; btclib-wallet's finalizer (psbt.finalize with its miniscript solver) finalizes every input Faraday finalizes again and gives the same scriptSig and witness; for each sweep, btclib reads the WIF (scalar, compression, public key) and signs and finalizes the sweep on its own curve, and python-ecdsa makes the first-nonce signature of each input again, byte for byte; python-bip380 (miniscript/) reads the leaves. Faraday's refusals and the inputs a wallet's rule leaves unsigned are ours, in area_sign.py.
Checked first: Core is the pinned release, hashed against its pin before every run; the vendored files are hashed against references.sha256; a published vector's answer is required of Core as well as of Faraday; every ECDSA and BIP-340 signature Core makes is checked to verify under the hash the area computes before that hash is used for Faraday's deterministic nonces.
Vectors BIP-174's signer, finalizer and extractor vectors; the Core-built spends of tools/vectors/psbt/ (2-of-3 sortedmulti, the Liana wallet down both paths, a taproot tree by a leaf and by the key path, BIP 387's taproot multisig), signed by every subset of their keys; the finalizer vectors there (or_b's smaller signature, the taproot leaves that tie by count, the taproot multisig and MuSig2 spends).
Random cases PSBTs of one to four inputs, each spending a funding output on the node: P2PKH, P2SH-P2WPKH, P2WPKH, multi/sortedmulti in P2SH, P2WSH and P2SH-P2WSH, P2TR key path, P2TR script path (pk, pkh, timelocked keys, or_d, multi_a) with the key path beside it, miniscript in P2WSH and P2SH-P2WSH; held and foreign keys, cosigners' signatures already on (Core's), every standard sighash type, timelocks met and not; Core's signatures (ECDSA byte for byte, BIP-340 by verification and the deterministic nonce), each final scriptSig and witness and the extracted transaction Core's, the cleared fields, and every finalized transaction accepted by Core's mempool; an origin that derives another key refused; sweeps: a WIF key's P2PKH, P2WPKH and P2SH-P2WPKH outputs (P2PKH alone for an uncompressed key) spent beside another key's, signed by Core from the WIF and by faraday_psbt::sweep::sign, byte for byte, finalized and accepted by the mempool.
Differences PSBT signing: Faraday refuses to sign a SegWit v0 input with no previous transaction in a transaction of more than one input; Core signs it, and BIP-174's own signer vector is such a PSBT. The refusal is ours, checked and counted. Faraday holds a finalized input to the same rule and refuses the PSBT when such an input is final, except a taproot one, whose final witness is the coordinator's.
PSBT signing, wallets: Faraday signs an input spent from a script of several keys (a multi of two or more, a miniscript naming two or more, a taproot script path whose carried leaves name two or more with its internal key, or are not its whole tree) only for a registered wallet that holds one of its keys and whose script it is; Core signs any. The area refuses, by a rule of its own, where no wallet the request registers holds a held key and gives the input, and counts it only where Faraday's refusal is that the wallet is not registered. A miniscript or a taproot tree of one key is signed only through such a wallet, and is otherwise left unsigned while the rest is signed (F141); the area takes Core's signatures off it. Half the corpus's multi, miniscript and taproot-tree inputs come with their wallet registered, so their signatures are still compared. A registered tree's every leaf has its wait met, since Faraday refuses a path that can never be valid, which the area does not work out.
PSBT signing: Faraday refuses a PSBT any input of which asks for a NONE or SINGLE sighash, and one that none of the held keys can sign: dangers no hold accepts (F136). Core signs the first and answers the second with nothing signed. The area expects both refusals by a rule of its own, counting a held key as taking part as Faraday's inspection does (a miniscript or a taproot tree only through a wallet in use), checks that Faraday's refusal names the danger, and counts them.
Taproot pkh leaves: Faraday signs a taproot leaf that checks its key by hash but does not finalize it: miniscript 12's finalizer looks the key up among the ECDSA origins and panics, and would push 33 bytes where the leaf hashed 32. Core finalizes such a leaf; the area takes the signatures under it off before Core finalizes, and counts each input Core would otherwise have finalized another way.
btclib's finalizer writes no taproot leaf that is neither a single key nor multi_a, and refuses to choose among leaves a PSBT signs: an input of another leaf is judged by Core alone (counted as a known difference), and btclib is given only the signatures of the leaf Faraday spent. It writes a plain multisig from the smallest m signatures on hand where Core and Faraday write the first m signers': btclib is given only the signatures Faraday's input carries, so it judges the script written from them and Core judges which were chosen.
When it runs Before every release, with a new seed and about ten times the cases.
Last passing runSeed 5be11ec606a76d2767f225b8992c45fe · 1580 cases
libsecp256k1 documents its signing as constant time.
bitcoin forces two copies of the key for Schnorr, the untweaked and the tweaked keypair; both are overwritten with secp256k1's non_secure_erase before the function returns, which the library calls best effort.
Limits
SIGHASH_DEFAULT and ALL are signed, and ALL with ANYONECANPAY after a caution; NONE, SINGLE and undefined types are refused.
A taproot input that no key of this device can sign is left unsigned.
A leaf is signed only when the leaf's script checks a signature against the key, read through the miniscript.
Faraday's own calls
aux_rand is zero, so a signature can be made again byte for byte; BIP 340 recommends fresh randomness against fault attacks. The library offers fresh aux_rand, and the app does not use it. Neutral, F156.
A miniscript or a taproot tree of one key is signed only through its registered wallet. Conservative, F141.
Signs as one MuSig2 participant: draws a nonce, signs with it or signs last, and aggregates the partial signatures.
Specification
BIP 327, MuSig2 for BIP340-compatible Multi-Signatures, Deployed
BIP 373, MuSig2 PSBT Fields, Complete
BIP 341, Taproot: SegWit version 1 spending rules, Deployed
Code
Library: secp256k1 0.29.1, by the rust-bitcoin developers (rust-secp256k1), over libsecp256k1, by Bitcoin Core's libsecp256k1 project (bitcoin-core/secp256k1).
Library: bitcoin 0.32.102, by the rust-bitcoin developers.
Library: hmac 0.13.0, by the RustCrypto developers, through core/faraday-crypto.
Library: sha2 0.11.0, by the RustCrypto developers, through core/faraday-crypto.
Library: base16ct 1.0.0, by the RustCrypto developers, through core/faraday-crypto.
Faraday's code: core/faraday-psbt: BIP 327's signing side is written here over libsecp256k1's point and secret-key operations (faraday-bip); the signing orchestration over BIP 373's PSBT fields is faraday-psbt's; a secret nonce is consumed by the signature it makes and held in memory for one transaction only; the wallet must be registered.
Checked against
tools/vectors/bip327
Published, by BIP 327's authors (bitcoin/bips).
tools/vectors/psbt
Published, by BIP 174's and RFC 6979's authors; the spends and finalized answers Bitcoin Core v31.1 made on regtest. Faraday's own known answers: the wallet policies, the warning PSBTs and the PSBTs this tree signed.
no fuzz target: No target runs the MuSig2 rounds; psbt_parse fuzzes the PSBT that carries their fields through inspect
Cross-check
Compared with others' code: BIP-327's reference.py, by the BIP's authors, and btclib's MuSig2 (ecc.ecc.musig2) and btclib-wallet's BIP-373 roles (Updater, Signer, Finalizer), by the btclib developers, on btclib's own curve: nonces, signing, verification and aggregation, and the Core round trip's PSBTs read, verified, signed last and finalized again; the Core 31.1 round trip stays as a judge of BIP-373 and the descriptor and shares libsecp256k1's scalar code with Faraday's.
Area musig
Faraday's code faraday_bip::musig
Compared with BIP-327's reference.py (bip327/); btclib's MuSig2 (btclib/, its own curve) in full, answering every operation beside it and verifying the aggregate signature as BIP-340; btclib-wallet's BIP-373 roles over the Core round trip's PSBTs; Bitcoin Core v31.1 (deriveaddresses) for musig() descriptors.
Checked first: Its vendored files are hashed against references.sha256 before any run, and a published vector's answer is required of the reference as well as of Faraday.
Vectors All eight files of tools/vectors/bip327/; the valid and invalid descriptors of tools/vectors/bip390/ (Core).
Random cases Sessions of 1 to 3 signers: key sort and aggregation, tweaks, nonces, partial signatures, their verification (and a tampered one), aggregation checked as BIP-340, deterministic signing; tr(musig(…)) wallets of 2 to 4 keys, as xpubs on both chains or as plain keys, whose scripts Core pays too.
Differences None known.
When it runs Before every release, with a new seed and about ten times the cases.
Last passing runSeed 5be11ec606a76d2767f225b8992c45fe · 320 cases
Every operation on a secret scalar is libsecp256k1's (SecretKey add, multiply and negate, and a nonce's public key). libsecp256k1's header says its code is written and tested to be constant time whatever the secret values; it states nothing of these functions by name. A hash is reduced to a scalar without a branch; the code documents no other timing.
A SecNonce is wiped on drop and consumed by the signature it makes; the session wipes its nonces when another transaction opens a session, and holds none once each has signed. SecretKey is Copy, so every add_tweak, mul_tweak and negate copies the key and only the last copy is erased; the earlier copies are left in memory, later work under the security scope (ESTABLISHED §4.1).
Limits
Key path only; a nonce or partial signature keyed by a tapleaf hash is a script-path spend and is refused.
The wallet must be registered; a participant set no registered wallet has is blocked.
Rounds across a lock, with the secret nonce kept in a vault, are not offered (F234).
Faraday's own calls
Each nonce's rand' is RFC 5869 HKDF-Expand of the session's seed, with the draw counter, the input's index and the participant's key as info: a fresh value per call, and a refusal when the counter would wrap. Neutral.
no decision
The secret nonce is held in memory for its one session and never serialised. Conservative, F234.
Checks every signature a PSBT or a finished transaction carries, finds a nonce used twice, recomputes this device's signatures and compares two PSBTs.
Specification
RFC 6979, Deterministic Usage of the Digital Signature Algorithm (DSA) and Elliptic Curve Digital Signature Algorithm (ECDSA), Informational
BIP 143, Transaction Signature Verification for Version 0 Witness Program, Deployed
BIP 341, Taproot: SegWit version 1 spending rules, Deployed
BIP 174, Partially Signed Bitcoin Transaction Format, Deployed
BIP 373, MuSig2 PSBT Fields, Complete
Code
Library: secp256k1 0.29.1, by the rust-bitcoin developers (rust-secp256k1), over libsecp256k1, by Bitcoin Core's libsecp256k1 project (bitcoin-core/secp256k1).
Library: bitcoin 0.32.102, by the rust-bitcoin developers.
Library: base16ct 1.0.0, by the RustCrypto developers, through core/faraday-crypto.
Faraday's code: core/faraday-psbt: Each signature is checked against the key it is under and the sighash the input's fields give, including the ones inside a finalized witness; one r or one R in more than one place is reported, under one key or several, and so is a point of a MuSig2 public nonce; a signature under a key this device holds is recomputed to say which nonce rule produced it.
Checked against
tools/vectors/psbt
Published, by BIP 174's and RFC 6979's authors; the spends and finalized answers Bitcoin Core v31.1 made on regtest. Faraday's own known answers: the wallet policies, the warning PSBTs and the PSBTs this tree signed.
Compared with others' code: python-ecdsa, by Brian Warner and Hubert Kario, and btclib, by the btclib developers, on btclib's own curve, verify every signature (ECDSA, and BIP-340 over python-ecdsa's points and btclib's ssa); the signature hashes are btclib's (sig_hash.py); btclib's script engine runs every complete input; Bitcoin Core v31.1 itself (finalizepsbt, testmempoolaccept), by Bitcoin Core's contributors, judges the complete inputs and the transaction, and shares libsecp256k1 with Faraday.
Compared, for one part, with Faraday's second version, written by Faraday's authors in Python; that part is not checked against an outside source: the report of a reused nonce, written in area_sign_check.py from Faraday's own rule, failing closed (signatures that verify with one r or R, differing in key or in message), which no outside library reports.
Area sign-check
Faraday's code faraday_psbt::verify::verify_signatures (every signature of a PSBT, in a partial field or a final scriptSig or witness, checked against its signature hash) and faraday_psbt::verify::repeated_nonces (one r or R under one key in more than one place)
Compared with python-ecdsa (the distribution's package, its own curve) and btclib (btclib/, libsecp256k1 off) verify every signature over btclib's signature hashes (sig_hash.py); btclib's script engine (verify_input, standardness rules on) runs every complete input and, under consensus's rules alone, every final input of the table (CONSENSUS); Bitcoin Core v31.1's finalizepsbt and testmempoolaccept judge the complete inputs and the transaction, and are named as sharing libsecp256k1 with Faraday; the reuse of a nonce is ours (reused, in area_sign_check.py).
Checked first: Its vendored files and the btclib wheels are hashed against references.sha256 before any run; Core's release tarball is checked against its pinned SHA-256 (tools/reference/core/release.pin) before every run, and the node's version is asked; the self-test makes Faraday's verdict wrong and its report of a nonce wrong, and each is caught.
A PSBT with no previous output for an input (Faraday leaves the signature unchecked); signatures under a pkh leaf or a script that names no key; MuSig2 partial signatures (area musig); the order of the signatures within a reuse report.
Vectors none: BIP-340's and ECDSA's published vectors are in the areas that sign (sign, msg); the signatures here are made for the PSBT in the case, with verdicts given by two verifiers.
Random cases Transactions of one to three inputs of legacy P2PKH, P2WPKH, P2WSH multisig (1 of 2 to 3 of 3), taproot key path and taproot script path, each with its signatures partial (in the PSBT's fields) or complete (in a final scriptSig or witness), good, under the wrong key, over the wrong sighash type, with a high S, or malformed, with every sighash type; nonces reused on purpose across inputs that share a key (ECDSA with k and -k too, Schnorr), one nonce under two keys, and one key under fresh nonces; and, for the verdict on a final input, a table of about ninety rows, each in every wrapping its script allows: and_v, thresh, pk, pkh, an or_d recovery path with older, 2 of 2 over [A,A], 2 of 3 over [A,A,B] and [A,B,A], the dummy empty and not, junk, repeated, swapped and extra signatures, 2 of 17 and 17 of 20, uncompressed keys, bare P2PK and multisig, P2PKH and P2WPKH true and forged, a hash time lock on both branches and three false spends of it, a redeem script of 500 and of 517 bytes, a high S and sighash bytes no standard defines, with keys drawn for each case; and about thirty taproot rows, run under TAPROOT: a key path and a script path on a Tap miniscript leaf, true and forged, an annex signed and not, SIGHASH_SINGLE with no output of its index, a control block that does not commit to the output key, a 65-byte element ending 0x00, and the leaves not run (another leaf version, a hash lock, OP_CODESEPARATOR, OP_DROP).
Differences A partial signature that is not a strict DER signature with a defined sighash byte (or a taproot signature of 64 bytes, or 65 with a sighash byte that is defined and not 0x00): Bitcoin Core reads the PSBT and leaves the input unfinalized, Faraday refuses the PSBT or does not call the signature valid. Counted.
A final input whose script Faraday does not run (a hash time lock, which is no miniscript: a wrong preimage, the key of the other branch, a sequence below the lock, and its true spends; a P2SH puzzle; a segwit pk of an uncompressed key, which Faraday's segwit reading refuses, though a segwit multisig of such keys is read by hand and answers ok; a bare P2PK of a key off the curve; a taproot leaf of a version other than 0xc0, a taproot hash lock, a taproot leaf with OP_CODESEPARATOR or OP_DROP): Faraday answers unjudged, whatever the engine decides. Such a script reads not sound in the nonce check and is not refused, and only these rows may answer so: a miniscript or a multisig answering unjudged fails the area. Counted.
A legacy (bare or P2SH) multisig with a junk element below the dummy: consensus leaves it on the stack and accepts, Faraday refuses it. No wallet writes one, and the refusal stays. Counted.
What no wallet writes and no node relays, which consensus accepts: a P2SH redeem script or signature pushed by PUSHDATA1 where a direct push fits; a P2SH or_i selector 01 01 (a push of one byte, not OP_1); a P2WSH or_i selector [2] (not [1] or empty); an or_d dissatisfied by a wrong DER signature, not an empty element; an element left below a P2SH pk. Faraday's reading of the final fields refuses each, and the refusal stays. Counted.
A final input with a high S, or with a sighash byte no standard defines (0x00, 0x04, 0x05, 0x84), in a signature the script engine accepts under consensus's rules: Faraday refuses it (a mismatch, or an invalid signature) and consensus takes it. Faraday keeps to the standard here on purpose: a node relays neither, so a transaction carrying one does not reach a miner. Counted.
When it runs Before every release, with a new seed and about ten times the cases.
Last passing runSeed 5be11ec606a76d2767f225b8992c45fe · 7000 cases
Private keys are used only to recompute this device's signatures; what comes back is a verdict. The library does not state the recomputation's timing.
The keypairs made to recompute a signature are overwritten with secp256k1's non_secure_erase, which the library calls best effort.
Limits
A signature with no previous output to check against is not checked.
A signature under a sighash type that was not asked for is flagged.
A signature of another device is not recomputed.
A finalized taproot signature of 65 bytes with hash type 0x00 is reported invalid, key path and script path alike (BIP 341): it is a danger card, and the PSBT is not refused.
Faraday's own calls
The nonce check is run on signatures a device writes, comparing them with the RFC 6979 or BIP 340 nonce rule. Neutral.
Compares two PSBTs side by side and says whether a replacement only raises the fee of an original: the same inputs, the same payments, a higher fee.
Specification
BIP 174, Partially Signed Bitcoin Transaction Format, Deployed
BIP 125, Opt-in Full Replace-by-Fee Signaling, Deployed
Code
Library: bitcoin 0.32.102, by the rust-bitcoin developers.
Faraday's code: core/faraday-psbt: Two PSBTs are read and set side by side; the fee of each is worked out from the amounts of its inputs and outputs, and a replacement is judged to only raise the fee when it spends the same inputs, pays the same outputs and its lock times and sequences allow it; any other case is Cannot tell.
Checked against
tools/vectors/psbt
Published, by BIP 174's and RFC 6979's authors; the spends and finalized answers Bitcoin Core v31.1 made on regtest. Faraday's own known answers: the wallet policies, the warning PSBTs and the PSBTs this tree signed.
no fuzz target: No target runs the comparison; psbt_parse fuzzes the PSBTs it reads
Cross-check
not cross-checked: No cross-check area runs it: the expected results are Bitcoin Core's psbtbumpfee pair (tools/vectors/psbt, bump-core-*), in the tests
SpecificationBIP 174PublishedCodeLibrary: bitcoin 0.32Library: miniscript 12.3Faraday's code: core/faraday-psbtFaraday's own codeCross-checked withBitcoin Core v31.1Others' codeFaraday's second version
Action
Builds the final scriptSig and witness from the partial signatures and extracts the transaction.
Specification
BIP 174, Partially Signed Bitcoin Transaction Format, Deployed
Code
Library: bitcoin 0.32.102, by the rust-bitcoin developers.
Library: miniscript 12.3.7, by the rust-bitcoin developers (rust-miniscript).
Faraday's code: core/faraday-psbt: every input goes through miniscript's finalizer with its interpreter check (pkh, wpkh, sh-wpkh, multisig under sh, wsh and sh-wsh, a miniscript, a tree); among satisfactions of a wsh miniscript the smaller by real signature size is chosen, as Bitcoin Core's finalizepsbt chooses it, a multi() inside it keeping its k smallest signatures, and a plain multisig keeps the first m signers' under any wrapper as Core does, each checked by the interpreter again; the signing fields are cleared as BIP 174 requires. The app keeps the finished transaction and writes it as hex.
Written by Faraday
The choice among a script's satisfactions by real signature size (faraday-psbt::finalize) · Faraday's own specification
For a miniscript Faraday picks the smallest witness as Bitcoin Core's finalizepsbt does; a plain multisig carries the first m signers' signatures, as Core writes them; miniscript builds and checks each witness.
Published, by BIP 174's and RFC 6979's authors; the spends and finalized answers Bitcoin Core v31.1 made on regtest. Faraday's own known answers: the wallet policies, the warning PSBTs and the PSBTs this tree signed.
Compared with others' code: Bitcoin Core v31.1, by the Bitcoin Core developers (finalizepsbt finalizes and extracts, testmempoolaccept judges the transaction over its funding on the node).
Compared, for one part, with Faraday's second version, written by Faraday's authors in Python; that part is not checked against an outside source: the signatures under a taproot pkh leaf taken off before Core finalizes, as Faraday leaves such a leaf to the coordinator, and the fields BIP-174 keeps on a finalized input, in area_sign.py.
Area sign
Faraday's code faraday_psbt::sign (every held key selected, deterministic Schnorr, both RFC 6979 nonce rules) and faraday_psbt::finalize
Compared with Bitcoin Core v31.1 on regtest (core_node.py): descriptorprocesspsbt signs from the held masters' keys, finalizepsbt finalizes and extracts, testmempoolaccept judges each finalized transaction over its funding on the node; BIP-340's reference (secp256k1lab) and Core's key.py for the deterministic nonces, over Core's script.py sighashes; python-ecdsa (the distribution's package) and btclib (btclib/, its own curve) as a second curve lineage, beside them: every ECDSA signature again under plain RFC 6979 or verified, every BIP-340 signature verified and made again; btclib-wallet's finalizer (psbt.finalize with its miniscript solver) finalizes every input Faraday finalizes again and gives the same scriptSig and witness; for each sweep, btclib reads the WIF (scalar, compression, public key) and signs and finalizes the sweep on its own curve, and python-ecdsa makes the first-nonce signature of each input again, byte for byte; python-bip380 (miniscript/) reads the leaves. Faraday's refusals and the inputs a wallet's rule leaves unsigned are ours, in area_sign.py.
Checked first: Core is the pinned release, hashed against its pin before every run; the vendored files are hashed against references.sha256; a published vector's answer is required of Core as well as of Faraday; every ECDSA and BIP-340 signature Core makes is checked to verify under the hash the area computes before that hash is used for Faraday's deterministic nonces.
Vectors BIP-174's signer, finalizer and extractor vectors; the Core-built spends of tools/vectors/psbt/ (2-of-3 sortedmulti, the Liana wallet down both paths, a taproot tree by a leaf and by the key path, BIP 387's taproot multisig), signed by every subset of their keys; the finalizer vectors there (or_b's smaller signature, the taproot leaves that tie by count, the taproot multisig and MuSig2 spends).
Random cases PSBTs of one to four inputs, each spending a funding output on the node: P2PKH, P2SH-P2WPKH, P2WPKH, multi/sortedmulti in P2SH, P2WSH and P2SH-P2WSH, P2TR key path, P2TR script path (pk, pkh, timelocked keys, or_d, multi_a) with the key path beside it, miniscript in P2WSH and P2SH-P2WSH; held and foreign keys, cosigners' signatures already on (Core's), every standard sighash type, timelocks met and not; Core's signatures (ECDSA byte for byte, BIP-340 by verification and the deterministic nonce), each final scriptSig and witness and the extracted transaction Core's, the cleared fields, and every finalized transaction accepted by Core's mempool; an origin that derives another key refused; sweeps: a WIF key's P2PKH, P2WPKH and P2SH-P2WPKH outputs (P2PKH alone for an uncompressed key) spent beside another key's, signed by Core from the WIF and by faraday_psbt::sweep::sign, byte for byte, finalized and accepted by the mempool.
Differences PSBT signing: Faraday refuses to sign a SegWit v0 input with no previous transaction in a transaction of more than one input; Core signs it, and BIP-174's own signer vector is such a PSBT. The refusal is ours, checked and counted. Faraday holds a finalized input to the same rule and refuses the PSBT when such an input is final, except a taproot one, whose final witness is the coordinator's.
PSBT signing, wallets: Faraday signs an input spent from a script of several keys (a multi of two or more, a miniscript naming two or more, a taproot script path whose carried leaves name two or more with its internal key, or are not its whole tree) only for a registered wallet that holds one of its keys and whose script it is; Core signs any. The area refuses, by a rule of its own, where no wallet the request registers holds a held key and gives the input, and counts it only where Faraday's refusal is that the wallet is not registered. A miniscript or a taproot tree of one key is signed only through such a wallet, and is otherwise left unsigned while the rest is signed (F141); the area takes Core's signatures off it. Half the corpus's multi, miniscript and taproot-tree inputs come with their wallet registered, so their signatures are still compared. A registered tree's every leaf has its wait met, since Faraday refuses a path that can never be valid, which the area does not work out.
PSBT signing: Faraday refuses a PSBT any input of which asks for a NONE or SINGLE sighash, and one that none of the held keys can sign: dangers no hold accepts (F136). Core signs the first and answers the second with nothing signed. The area expects both refusals by a rule of its own, counting a held key as taking part as Faraday's inspection does (a miniscript or a taproot tree only through a wallet in use), checks that Faraday's refusal names the danger, and counts them.
Taproot pkh leaves: Faraday signs a taproot leaf that checks its key by hash but does not finalize it: miniscript 12's finalizer looks the key up among the ECDSA origins and panics, and would push 33 bytes where the leaf hashed 32. Core finalizes such a leaf; the area takes the signatures under it off before Core finalizes, and counts each input Core would otherwise have finalized another way.
btclib's finalizer writes no taproot leaf that is neither a single key nor multi_a, and refuses to choose among leaves a PSBT signs: an input of another leaf is judged by Core alone (counted as a known difference), and btclib is given only the signatures of the leaf Faraday spent. It writes a plain multisig from the smallest m signatures on hand where Core and Faraday write the first m signers': btclib is given only the signatures Faraday's input carries, so it judges the script written from them and Core judges which were chosen.
When it runs Before every release, with a new seed and about ten times the cases.
Last passing runSeed 5be11ec606a76d2767f225b8992c45fe · 1580 cases
An input that has too few signatures stays partial and the transaction is not extracted.
A timelock the transaction does not meet stops the input in miniscript's interpreter check.
A final input whose funding transaction lacks the spent output is refused.
A taproot leaf holding pkh() is signed but left for the coordinator to finalize.
Faraday's own calls
Of several satisfactions of a wsh miniscript, the one with the smaller real signature size is chosen; where two weigh the same, the one Bitcoin Core keeps: an or's first branch, a multi()'s keys named first, a thresh()'s branches named last, a taproot spend's leaf whose script sorts first by its bytes. Neutral, F161.
Signs a message with the key at a path, in BIP 137's compact form or as BIP 322 simple.
Specification
BIP 137, Signatures of Messages using Private Keys, Deployed
BIP 322, Generic Signed Message Format, Complete
RFC 6979, Deterministic Usage of the Digital Signature Algorithm (DSA) and Elliptic Curve Digital Signature Algorithm (ECDSA), Informational
BIP 340, Schnorr Signatures for secp256k1, Deployed
Code
Library: secp256k1 0.29.1, by the rust-bitcoin developers (rust-secp256k1), over libsecp256k1, by Bitcoin Core's libsecp256k1 project (bitcoin-core/secp256k1).
Library: bitcoin 0.32.102, by the rust-bitcoin developers.
Library: hmac 0.13.0, by the RustCrypto developers, through core/faraday-crypto.
Library: sha2 0.11.0, by the RustCrypto developers, through core/faraday-crypto.
Faraday's code: core/faraday-psbt: The address is derived from the key that signs, so the address in the result is the one the signature verifies against; BIP 137 low-R is ground here, libsecp256k1 having no low-R recoverable signer; the key's own blinded curve context is used. In the app the key is the one behind an address of a loaded single-key wallet's receive chain, and a wallet of several keys is refused.
Written by Faraday
BIP-322 "simple" message signatures (faraday-psbt::message) · No established implementation exists
no fuzz target: No fuzz target signs: the signer takes the person's own text and key; message_verify fuzzes the reading of a signed message
Cross-check
Compared with others' code: Bitcoin Core v31.1 (signmessagewithprivkey, verifymessage, signrawtransactionwithkey); btclib's bms and btclib-wallet's bip322, by the btclib developers, on btclib's own curve; btcd's bip322 (pull request 2521), by Oliver Gugger and the btcd developers; python-ecdsa, by Brian Warner and Hubert Kario, for the first-nonce ECDSA signature of BIP-137; Core shares libsecp256k1's curve maths with Faraday's.
Compared with Bitcoin Core v31.1 and btclib for BIP-137, btclib-wallet and btcd for BIP-322: Core's signmessagewithprivkey, verifymessage and signrawtransactionwithkey (the low-R P2WPKH witness); btclib's bms and btclib-wallet's bip322 (btclib/, btclib's own curve); python-ecdsa (the distribution's package) for the first-nonce ECDSA signature of BIP-137; btcd's bip322 from pull request 2521 (btcd-bip322/, Go).
Checked first: The wheels and the Go tree are hashed against references.sha256 before any run, Core's release against its pin; BIP-322's basic and generated vectors and btcd's negative vectors are required of both BIP-322 references, each in the state the vector names, and Trezor's and Electrum's BIP-137 signatures of btclib.
A taproot signature's bytes (BIP-340's auxiliary randomness is the signer's: Faraday's is verified by both BIP-322 references, and btcd's by Faraday); the kind of a refusal (Malformed, Invalid, Unsupported…), Faraday's own words, checked by its tests; Core's reading of a BIP-137 header outside 27 to 42.
Vectors BIP-322's basic and generated vectors (hashes, txids, simple, full and proof-of-funds signatures, errors) and btcd's negative vectors; Trezor's and Electrum's BIP-137 signatures (tools/vectors/message/), Trezor's made again from its keys.
Random cases Random keys, address forms, networks and messages: virtual txids; signatures made byte for byte under both nonce rules and checked by every reference, then checked against a changed message, another address, a changed byte and a moved header; btcd's own simple signatures checked by Faraday.
Differences BIP-137: Faraday reads the address form from the address rather than the header's range and tries a P2PKH address in both key encodings (faraday_psbt::message), as Electrum and Sparrow do; btclib holds the ranges (with Electrum's for SegWit) and Core reads the key encoding from the header. Counted where btclib accepts the signature with the header the address's form names, or Core with the other key encoding.
BIP-322: Faraday refuses the full form and proof of funds, which both references make and accept (for P2PKH and P2SH-P2WPKH addresses they sign in the full form); counted where both accept and Faraday refuses the format.
BIP-322: Faraday checks simple signatures for P2WPKH and P2TR addresses only; a P2WSH script both references accept is refused as an unsupported address, and counted.
Between the references: btclib's interpreter holds witness v0 scripts alone to MINIMALIF, so it accepts btcd's two negative vectors of a legacy P2SH script, in the full form, whose OP_IF takes a non-minimal true; btcd must call them invalid and Faraday, which reads no full form, refuse them, and each is counted.
When it runs Before every release, with a new seed and about ten times the cases.
Last passing runSeed 5be11ec606a76d2767f225b8992c45fe · 6000 cases
libsecp256k1 documents its signing as constant time; the BIP 137 low-R grind repeats the signing until r is small.
The secret key is borrowed for the moment it signs; the two Schnorr copies bitcoin forces for a taproot address are overwritten with secp256k1's non_secure_erase before the function returns, which the library calls best effort.
Limits
BIP 322 simple only: no full form, no proof of funds.
A nested SegWit address has no BIP 322 simple form and is signed as BIP 137 only.
A taproot address is signed as BIP 322 only.
Faraday's own calls
The app signs with the low-R nonce and zero aux_rand for a taproot address. Neutral, F156.
Checks a signed message against an address, as BIP 137 or BIP 322 simple.
Specification
BIP 137, Signatures of Messages using Private Keys, Deployed
BIP 322, Generic Signed Message Format, Complete
Code
Library: secp256k1 0.29.1, by the rust-bitcoin developers (rust-secp256k1), over libsecp256k1, by Bitcoin Core's libsecp256k1 project (bitcoin-core/secp256k1).
Library: bitcoin 0.32.102, by the rust-bitcoin developers.
Faraday's code: core/faraday-psbt: Reads the recovery id from the BIP 137 header and asks the address itself which form to rebuild, as Electrum and Sparrow do; a P2PKH address is tried in both key encodings. The app requires the address to be on the session's network and looks for it among each loaded wallet's first 100 addresses on both chains.
Checked against
tools/vectors/message
Published, by BIP 322's authors (bitcoin/bips); btcd's BIP-322 (pull request 2521); Trezor's and Electrum's test suites, for BIP 137.
Compared with others' code: Bitcoin Core v31.1 (signmessagewithprivkey, verifymessage, signrawtransactionwithkey); btclib's bms and btclib-wallet's bip322, by the btclib developers, on btclib's own curve; btcd's bip322 (pull request 2521), by Oliver Gugger and the btcd developers; python-ecdsa, by Brian Warner and Hubert Kario, for the first-nonce ECDSA signature of BIP-137; Core shares libsecp256k1's curve maths with Faraday's.
Compared with Bitcoin Core v31.1 and btclib for BIP-137, btclib-wallet and btcd for BIP-322: Core's signmessagewithprivkey, verifymessage and signrawtransactionwithkey (the low-R P2WPKH witness); btclib's bms and btclib-wallet's bip322 (btclib/, btclib's own curve); python-ecdsa (the distribution's package) for the first-nonce ECDSA signature of BIP-137; btcd's bip322 from pull request 2521 (btcd-bip322/, Go).
Checked first: The wheels and the Go tree are hashed against references.sha256 before any run, Core's release against its pin; BIP-322's basic and generated vectors and btcd's negative vectors are required of both BIP-322 references, each in the state the vector names, and Trezor's and Electrum's BIP-137 signatures of btclib.
A taproot signature's bytes (BIP-340's auxiliary randomness is the signer's: Faraday's is verified by both BIP-322 references, and btcd's by Faraday); the kind of a refusal (Malformed, Invalid, Unsupported…), Faraday's own words, checked by its tests; Core's reading of a BIP-137 header outside 27 to 42.
Vectors BIP-322's basic and generated vectors (hashes, txids, simple, full and proof-of-funds signatures, errors) and btcd's negative vectors; Trezor's and Electrum's BIP-137 signatures (tools/vectors/message/), Trezor's made again from its keys.
Random cases Random keys, address forms, networks and messages: virtual txids; signatures made byte for byte under both nonce rules and checked by every reference, then checked against a changed message, another address, a changed byte and a moved header; btcd's own simple signatures checked by Faraday.
Differences BIP-137: Faraday reads the address form from the address rather than the header's range and tries a P2PKH address in both key encodings (faraday_psbt::message), as Electrum and Sparrow do; btclib holds the ranges (with Electrum's for SegWit) and Core reads the key encoding from the header. Counted where btclib accepts the signature with the header the address's form names, or Core with the other key encoding.
BIP-322: Faraday refuses the full form and proof of funds, which both references make and accept (for P2PKH and P2SH-P2WPKH addresses they sign in the full form); counted where both accept and Faraday refuses the format.
BIP-322: Faraday checks simple signatures for P2WPKH and P2TR addresses only; a P2WSH script both references accept is refused as an unsupported address, and counted.
Between the references: btclib's interpreter holds witness v0 scripts alone to MINIMALIF, so it accepts btcd's two negative vectors of a legacy P2SH script, in the full form, whose OP_IF takes a non-minimal true; btcd must call them invalid and Faraday, which reads no full form, refuse them, and each is counted.
When it runs Before every release, with a new seed and about ten times the cases.
Last passing runSeed 5be11ec606a76d2767f225b8992c45fe · 6000 cases
A signature belongs to the one address it was made for.
BIP 322 simple only.
A taproot signature of 65 bytes with hash type 0x00 is refused as malformed (BIP 341).
Faraday's own calls
The address form is read from the address, not from the BIP 137 header's range, and a P2PKH address is tried in both key encodings; more lenient than BIP 137. Neutral.
Library: bitcoin 0.32.102, by the rust-bitcoin developers.
Library: base16ct 1.0.0, by the RustCrypto developers, through core/faraday-crypto.
Faraday's code: core/faraday-psbt: A raw transaction is read from hex or bytes by rust-bitcoin, and one it reads to no inputs is refused, as Bitcoin Core refuses those bytes (the segwit flag with no witness); a previous transaction is accepted for an input only when its txid is the one spent. The Decode screen takes the amounts its inputs spend from the spend's PSBT and the Inbox's PSBTs whose unsigned transaction is exactly the one decoded, and uses an input's amount only when no two of them state different ones. An output is named by its script kind (P2WPKH, P2WSH, P2TR, P2SH, P2PKH or OP_RETURN) and marked when it pays to a loaded wallet's first 100 addresses on either chain. A text is taken as a transaction in hex only when it has an even number of at least 120 hex digits that read as a transaction. Decode refuses a transaction with an output over 21,000,000 BTC or outputs whose total is over it, as Bitcoin Core's CheckTransaction does (bad-txns-vout-toolarge, bad-txns-txouttotal-toolarge), and one whose inputs' stated amounts, or their total, are over it, as its CheckTxInputs does (bad-txns-inputvalues-outofrange), so no total or fee it shows overflows.
Compared with others' code: btclib's Tx.parse, by the btclib developers; and Bitcoin Core v31.1's decoderawtransaction, by Bitcoin Core's contributors.
Compared, for one part, with Faraday's second version, written by Faraday's authors in Python; that part is not checked against an outside source: the refusal of a transaction with no inputs, which neither judge makes (Core's decoderawtransaction reads bytes that begin with the marker 00 01 as a legacy transaction of no inputs), written in area_tx.py.
Area tx
Faraday's code faraday_psbt::transaction::read_raw, faraday_core::decode::decode's txid, wtxid and output addresses, bitcoin's SighashCache as faraday_psbt::sign calls it
Compared with btclib's Tx.parse and sig_hash (btclib/); Bitcoin Core v31.1's decoderawtransaction on regtest (core_node.py) for the transactions; Core's messages.py and script.py (core/) for the signature hashes; the refusal of a transaction with no inputs is ours.
Checked first: Its vendored files and the btclib wheels are hashed against references.sha256 before any run, and a published vector's answer is required of the reference as well as of Faraday; each published signature hash is checked against the framework first.
Random cases Random transactions with and without witnesses (txid, wtxid, weight, bytes) read by btclib and Core's decoderawtransaction, cut or lengthened, and shown by Faraday's Decode view (txid, wtxid, each output's address, none where Core gives none) against Core's; every input hashed as legacy, BIP-143 P2WPKH and P2WSH, BIP-341 key and script path under every hash type, by btclib and the framework.
Differences Decode refuses a transaction whose outputs total over 21,000,000 BTC, as Core does not in decoderawtransaction; the corpus asks Decode only of transactions within that total.
Legacy sighash: bitcoin hashes the script code as given, Core and btclib remove every OP_CODESEPARATOR first. Faraday's legacy spends (P2PKH, P2SH multisig) have none.
Core's decoderawtransaction reads bytes whose marker 00 01 it takes as a count of no inputs and one output, a legacy transaction of no inputs; Faraday refuses a transaction with no inputs, and the area counts a case where btclib reads inputs of such bytes as this difference.
BIP-341's refusals (SIGHASH_SINGLE without an output, a hash type it does not list) are btclib's: the framework hashes those anyway and is not asked.
When it runs Before every release, with a new seed and about ten times the cases.
Last passing runSeed 5be11ec606a76d2767f225b8992c45fe · 30000 cases
5 actions · 1 own specification · 3 with Faraday's own code · 4 cross-checked with others' code · 1 with Faraday's second version · 1 not cross-checked
Encodes a payload as a QR code, ISO/IEC 18004 model 2, and reads QR codes from a camera frame or a PNG.
Specification
ISO/IEC 18004, QR Code bar code symbology specification, Status not checked
Code
Library: rqrr 0.11.0, by WanzenBug (rust-qr-reader), as copied into third_party/rqrr with the changes third_party/rqrr/PATCHES.md lists.
Library: bitcoin 0.32.102, by the rust-bitcoin developers, through core/faraday-bip.
Faraday's code: core/faraday-codec: The encoder is a port of Project Nayuki's qrcodegen, rewritten for no_std and secret payloads: the module grid and every buffer holding payload bits wipe on drop, and the error-correction level is never raised; the PNG writer is here; reading is rqrr's.
Written by Faraday
The QR encoder, a port of Nayuki's qrcodegen, with its GF(256) and Reed-Solomon (faraday-codec::qr) · No established implementation exists
No QR encoder comes from a publisher Faraday's dependency review trusts; Faraday's port of Nayuki's code wipes a SeedQR's buffers.
Compared with others' code: Project Nayuki's qrcodegen.py, by Nayuki, and segno, by Lars Heuer, and the pictures decoded by zbar, by the zbar developers, and zxing-cpp, by the zxing-cpp developers.
Area seedqr
Faraday's code faraday_codec::seedqr (SeedQR, CompactSeedQR), faraday_codec::qr, the encoder that draws them, and faraday_codec::qr::codex32qr with the picture faraday_core::picture writes of it
Compared with SeedSigner's own encoders and DecodeQR (seedsigner/, unchanged, with embit's BIP-39 code in embit/); Project Nayuki's qrcodegen.py (qrcodegen/), module for module; segno 1.6 (python3-segno), an encoder of another lineage, at Faraday's mask and at its own; Pillow and CPython's zlib, which read every PNG Faraday writes; zbar (zbarimg) and zxing-cpp, which decode the QR code in every picture and return its payload as bytes (qr_decode.py).
Checked first: Its vendored files are hashed against references.sha256 before any run, and a published vector's answer is required of the reference as well as of Faraday; SeedSigner's reader is looser than Faraday (it takes 49 digits, a sign inside a group, 20 to 28 bytes, and does not check the checksum of digits), so Faraday's own rule, the lengths and the digits, stands in front of it in area_seedqr.py and the checksum is embit's; SeedSigner runs in English for every language, the indices being the same; the profile's own pictures are read from their pixels and must be Faraday's code module for module; segno is asked for Faraday's version, level and mode and its mask forced, and its mask is read back from it, its padding quirk being modelled in Nayuki's code; rqrr reads Faraday's and segno's codes; the self-test makes each decoder's answer wrong (a payload's last byte changed) and must catch it.
An empty payload, which segno refuses.
Vectors SeedSigner's nine test SeedQRs (tools/vectors/seedqr/); every string and picture of the Codex32QR profile (tools/vectors/codex32qr/), each decoded by zbar and zxing-cpp.
Random cases Keys of every length and language, both codes and the words read back; digits and bytes malformed; payloads in each mode at each level and version limit; 48-character codex32 strings in either case as Codex32QR codes and the pictures written of them read back and decoded by zbar and zxing-cpp, other lengths refused; the pictures of a key's SeedQR and CompactSeedQR decoded by both and read by Faraday to the key's words; greyscale pictures and QR pictures of random size and scale read by Pillow and zlib.
Differences SeedQR digits: SeedSigner reads a string with 1 to 3 digits more than 48 or 96 (it drops the tail) and one with a sign or a space inside a group of four (int() takes them); Faraday refuses both (5 cases, each checked on both sides and counted). SeedSigner takes no CompactSeedQR of 20, 24 or 28 bytes either, and strips checksum bits for 12 and 24 words only; the corpus keeps Faraday's 15, 18 and 21 word compact form on the entropy itself.
Codex32QR: Faraday picks the mask Nayuki's encoder picks; the profile's encoder chose another for 6 of its 22 pictures. For those the area swaps the mask of Faraday's code for the picture's with qrcodegen.py's masking, requires the picture, and counts it.
Segno 1.6 writes a zero codeword where the pad codewords begin when the data, terminator included, ends on a codeword boundary with room left (its write_padding_bits adds 8 zero bits where none are due; ISO/IEC 18004 7.4.10 adds none): its code is Nayuki's with that codeword changed, which rqrr reads, counted as a known difference, the padding; Faraday's is the standard's.
Segno picks a mask by its own penalty rule, and for some payloads another than Nayuki's and Faraday's; the area requires that code to be Faraday's under the mask segno reports (Nayuki's masking swapped to it) and rqrr to read it, and counts each as a known difference, the mask choice, which a reader ignores.
When it runs Before every release, with a new seed and about ten times the cases.
Last passing runSeed 5be11ec606a76d2767f225b8992c45fe · 8000 cases
The module grid, the bit stream and the data and error-correction codewords wipe on drop; a decoded payload is a zeroizing buffer. The caller asks faraday-keys for any secret it encodes.
Limits
One segment per code; the caller picks numeric, alphanumeric or byte mode.
The error-correction level is never raised above the one asked for.
A frame whose byte count is not width times height yields nothing; a code whose error correction fails is skipped.
Faraday's own calls
The error-correction level is never boosted, so a SeedQR comes out at the level its specification names. Neutral.
Writes and reads UR codes: bytewords with CRC-32, fountain-coded parts and the CBOR around them.
Specification
BCR-2020-005, Uniform Resources (UR), the animated-QR transport, Convention, vendored
BCR-2020-006, The crypto-psbt UR type, Convention, vendored
BCR-2020-012, Bytewords, Convention, vendored
BCR-2020-007, UR Type Definition for Hierarchical Deterministic (HD) Keys, Convention
BCR-2020-010, UR Type Definition for Bitcoin Output Descriptors, Convention
BCR-2020-015, UR Type Definition for BIP44 Accounts, Convention
Code
Library: bitcoin 0.32.102, by the rust-bitcoin developers, through core/faraday-bip.
Library: sha2 0.11.0, by the RustCrypto developers, through core/faraday-crypto.
Faraday's code: core/faraday-codec: The whole transport is written here: bytewords in the minimal style with their CRC-32, the xoshiro generator that picks a part's fragments, the fountain parts with their CBOR and the ur: text; SHA-256 and CRC-32 come from faraday-crypto. A decoder reduces a mix by any buffered mix whose fragments are a subset of its own. The registry's crypto-hdkey, crypto-account and crypto-output are read as key lines or a descriptor, and a crypto-account is written for one key as SeedSigner shows it.
Written by Faraday
BC-UR, with its CBOR (faraday-codec::ur, faraday-codec::cbor) · No established implementation exists
No library for this format comes from a publisher Faraday's dependency review trusts.
CRC-32 (faraday-crypto::crc32) · No established implementation exists
The CRC-32 crate in the tree, crc32fast 1.5.1, is not covered by an outside review at that version; Faraday's is a branch-free loop checked against the published check values.
Compared with others' code: foundation-ur-py, by Foundation Devices, and CPython's zlib.crc32 and cbor2, by the cbor2 developers, which judge the one CRC-32 and the one CBOR (the parts' and payloads' CBOR and the registry's types).
Area ur
Faraday's code faraday_codec::ur (single-part URs, the animation's parts, the decoder), faraday_crypto::crc32, faraday_codec::cbor and faraday_qr::registry
Compared with Foundation Devices' foundation-ur-py (ur/), URKit ported; CPython's zlib.crc32; cbor2.
Checked first: Its vendored files are hashed against references.sha256 before any run, and a published vector's answer is required of the reference as well as of Faraday; foundation-ur-py is itself a port of URKit checked against URKit's own tests, whose vectors the area also runs.
Vectors URKit's single-part and multipart encoder vectors (tools/vectors/ur/).
Random cases Messages as crypto-psbt and bytes at random fragment lengths, parts byte for byte; sets with fragments dropped, mixes added, shuffled, repeated and upper case, put together by both; URs of other types written, read, changed and cut; CRC-32 of random messages and of the parts; the parts and single-part payloads read by cbor2; registry types built with cbor2 and read; random and mutated CBOR through Faraday's reader beside cbor2.
Differences UR: Faraday has no minimum fragment length, writes a one-fragment message as a part like any other, and refuses to animate an empty message; foundation-ur-py checks a UR type one character's way ('a' <= type <= 'z'). The area asks the reference with a minimum of 1, makes parts with its fountain encoder, and keeps its types to letters, digits and - not starting with z. Faraday's decoder reduces mixes by each other whichever arrived first, and so sometimes finishes a set URKit's does not; the area then checks the message is the one sent and counts the set.
CBOR: Faraday's reader refuses indefinite lengths, floats, simple values other than false, true and null, nesting beyond 16 levels, a key given twice and a stray break, which cbor2 reads; cbor2 reads tags below 300 or from 1000 on as types of its own. The area counts each such input as a known difference, and any other difference is a failure.
When it runs Before every release, with a new seed and about ten times the cases.
Last passing runSeed 5be11ec606a76d2767f225b8992c45fe · 24000 cases
SpecificationBBQr · Specter pNofMPublishedCodeLibrary: base16ct 1.0 (through core/faraday-crypto)Faraday's code: faraday/faraday-qrFaraday's own codeCross-checked withCoinkite's BBQr libraryOthers' codeFaraday's second version
Action
Splits a file into BBQr or numbered pNofM parts for QR codes and puts received parts together.
Specification
BBQr, BBQr, a file split across QR codes, Convention
Specter pNofM, Numbered text parts, pNofM, Convention
Code
Library: base16ct 1.0.0, by the RustCrypto developers, through core/faraday-crypto.
Faraday's code: faraday/faraday-qr: BBQr is written in base32 only and read in base32, hex and raw DEFLATE (miniz_oxide, decompressed within a bound); the numbered parts are Specter's and SeedSigner's pNofM; every limit fails closed. The assembler keeps a transfer part-way through across scans; a part of another transfer starts that one afresh, and any other refusal leaves the transfer as it was.
Written by Faraday
BBQr (faraday-qr::bbqr) · No established implementation exists
No library for this format comes from a publisher Faraday's dependency review trusts.
Compared with others' code: Coinkite's BBQr library, by Coinkite, for BBQr; krux's qr.py and bbqr.py, by the krux developers, for writing and reading numbered parts; SeedSigner's SpecterWalletQrDecoder, by the SeedSigner developers, for the numbered parts.
Compared, for one part, with Faraday's second version, written by Faraday's authors in Python; that part is not checked against an outside source: Faraday's refusals written in area_bbqr.py in front of SeedSigner's decoder (a part number of 0 or past the count, a repeat with other text, a header in upper case or missing, a count over 1,000), the one-table pyqrcode shim checked against qrcodegen.py, and krux's three shims (QR, base32, deflate).
Area bbqr
Faraday's code faraday_qr::bbqr, faraday_qr::specter (numbered text parts)
Compared with Coinkite's BBQr library (bbqr/, with a one-table pyqrcode shim checked against qrcodegen.py); krux's qr.py and bbqr.py (krux/, unchanged, with three small shims for the firmware's QR, base32 and deflate modules); SeedSigner's own SpecterWalletQrDecoder (seedsigner/, unchanged).
Checked first: check_capacities and check_krux_capacities run first, the pyqrcode shim's table of version capacities and krux's two tables against qrcodegen.py's; the vendored files are hashed against references.sha256 before any run, and a published vector's answer is required of the reference as well as of Faraday; where Faraday refuses what SeedSigner's decoder files or misfiles (a part number of 0 or past the count, a repeat with other text, a header in upper case or missing, a count over 1,000) the refusal is written in the area, in front of the decoder.
krux's writing of file types Faraday does not write (C, X, B, R, S, E are refused by both and compared as refusals); a set over 1,295 parts, which krux cannot number; the old cases of Faraday's writing at 1, 5, 7 and 40 bytes a part, gone because writing is now sized by QR version, the size krux chooses.
Vectors Coinkite's BBQr test files (tools/vectors/bbqr/): the 26 parts of a phone's scan, which read as a U file with the text Coinkite's test expects, and its ten PSBTs and transactions, each split in every encoding and read back to the file's bytes.
Random cases Files of every type and size written by krux (at the sizes of QR versions 1 to 20) and split by Coinkite in each encoding, read in any order, with repeats, a part missing, another transfer's part, a conflicting repeat and a part past the count, against Coinkite and krux; what Faraday writes, part for part krux's own writing at the same size, read back by join_qrs and by krux; numbered parts written by krux, written again by Faraday, read in any order against SeedSigner's decoder and krux and refused when malformed.
Differences BBQr: Faraday reads the file types P, T, U and J and frames of at most 4,096 characters; Coinkite's library reads every type BBQr defines and a version 40 part of 4,296 characters. Both refusals are checked and counted, and the corpus splits at version 39 at most. Faraday also refuses a set whose parts are not one length but the last, which Coinkite never writes.
Numbered parts: SeedSigner matches P and OF in upper case; Faraday does not (checked and counted). Faraday also refuses a part number of 0 or past the count, a count over 1,000, a repeat with other text and a part with no header, which SeedSigner's decoder files, fails on or takes whole; those refusals are written in the area, in front of the decoder.
Krux (checked and counted): reads the file types P, T, J and U only, decodes J and U as UTF-8 in 2 and Z only, stops at 160 KiB of characters (Coinkite's signed.txn is over it, in H), and can write a last part longer than the others, which Faraday refuses; its deflate reads a 1,024-byte window on a device, which the shim reads and writes. A set with an empty last part is read by Coinkite and krux and refused by Faraday, which refuses any part with no data.
When it runs Before every release, with a new seed and about ten times the cases.
Last passing runSeed 5be11ec606a76d2767f225b8992c45fe · 15000 cases
Puts a file in the faraday-file-v1 envelope with its SHA-256 and checks one received, saving a file received once.
Specification
Own specification (no decision)
Code
Library: bitcoin 0.32.102, by the rust-bitcoin developers.
Library: base16ct 1.0.0, by the RustCrypto developers, through core/faraday-crypto.
Faraday's code: faraday/faraday-qr: The envelope is canonical JSON with sorted keys and no spaces; unpack reads the fields, puts the file in an envelope again and refuses unless the bytes are identical; the SHA-256 of the file is written in the envelope and checked when one is read. A scanned text is taken as an envelope only when it looks like one and unpack accepts it.
A secret received is returned for the hold that saves it, in a Zeroizing buffer; the buffer that joins name, extension and data is zeroized after hashing.
Limits
A file of no bytes or over 256 KiB is refused.
A kind other than file, public-key or signing-subkey is refused.
A name is 1 to 128 letters, digits, dots, hyphens or underscores.
An envelope over BBQr's 360 KiB is refused.
Faraday's own calls
The SHA-256 shows that the file arrived whole, not who sent it. Neutral.
no decision
An envelope is refused unless it is exactly what pack would write for its file. Conservative.
Computes the SHA-256 of a whole file to show and keep.
Specification
FIPS 180-4, Secure Hash Standard, Status not checked
Code
Library: sha2 0.11.0, by the RustCrypto developers.
Library: base16ct 1.0.0, by the RustCrypto developers.
Faraday's code: core/faraday-crypto: sha2's SHA-256 over every byte, counted as file-hash work through the compute token. A file in the Inbox is hashed when it comes in and the sum is kept on it, a lookup after; the Files menu and the GPG signing page hash through the same function.
no fuzz target: Takes any bytes and parses nothing
Cross-check
Compared with others' code: Python's hashlib (SHA-256), over random files of every length around the 64-byte blocks and of 4 KiB, 64 KiB and 1 MiB with a byte more and less.
Area hash
Faraday's code faraday_bip::hashes and faraday_codec::encodings (read, the writers and from_hex), faraday_core::file_menu::sha256, and faraday_crypto::hkdf_sha256 and hkdf_sha256_expand, hmac_sha256, hmac_sha512, pbkdf2_hmac_sha256, pbkdf2_hmac_sha512 and scrypt
Compared with Bitcoin Core v31.1's functional-test framework (core/): ripemd160.py, address.py and segwit_addr.py, with hashlib for SHA-256 and bytes.fromhex for hex; PyCA cryptography's HKDF and HKDFExpand (OpenSSL) for the one HKDF; hmac, hashlib.pbkdf2_hmac and hashlib.scrypt (OpenSSL) for HMAC, PBKDF2 and scrypt.
Checked first: Its vendored files are hashed against references.sha256 before any run, and a published vector's answer is required of the reference as well as of Faraday; the order read tries the spellings in, the trimming of the text, hex as an even number of hex digits, plain Base58 (which Core's framework does not read; the area's own few lines) and which prefixes make a segwit address are Faraday's rules, written in the area in front of the reference.
The file hash is file_menu::sha256 over a whole byte slice (it reads in no buffer, so no read size is probed); the Files screen's reading of a file from a stick is the files areas'.
Vectors FIPS 180-4's SHA-256 examples, RIPEMD-160 of abc, BIP-173's key and its HASH160, Bitcoin Core's first key_io_valid.json address, BIP-173's and BIP-350's bech32 strings and their valid and invalid segwit addresses (tools/vectors/addresses).
Random cases Random bytes of every length from 0 to 130 and to 300 hashed (SHA-256, SHA-256d, HASH160) and as a file, files of 4 KiB, 64 KiB and 1 MiB with a byte more and less; random bytes written and read as Base58Check, Base58, bech32 and bech32m, Core's writing read by Faraday, segwit addresses of every version Core's framework writes, and texts changed, cut or made of random characters read by both.
Differences bech32 groups: a string that is not a segwit address of bc, tb or bcrt is read as bytes, all its data groups together, and the bits that do not fill a byte are dropped. BIP-173 has a padding rule only for a segwit address, so Core's convertbits, which applies it to any data, refuses some of these strings, and the area reads them as Faraday does.
bech32 length: Core's decoder refuses more than 90 characters (BIP-173); Faraday accepts any length the checksum covers. The area reads longer strings the same way.
When it runs Before every release, with a new seed and about ten times the cases.
Last passing runSeed 5be11ec606a76d2767f225b8992c45fe · 30000 cases
11 actions · 7 own specification · 2 with Faraday's own code · 8 cross-checked with others' code · 5 with Faraday's second version · 3 not cross-checked
A vault has two layers. The lock is the passphrase, Argon2id, ChaCha20 and HMAC. It is what keeps secrets safe. All of it is published, and each algorithm comes from an established library.
The plumbing is the code that lays the file out, reads it back and decides which field holds what. Most of what is Faraday's own is here. A bug in the plumbing usually means a file that does not open. The exception is in writing, under Security.
The file
A vault is one KDBX 4 file, the database format KeePass writes, under one passphrase. Faraday writes it in one shape and reads the shapes a KeePass app saves within limits.
The file holds a plaintext of a whole number of 32 KiB steps, from one step to 128 MiB, framed in blocks and wrapped in a header. A vault is as small as its contents allow, and no size is chosen.
The file's name ends in .kdbx. There is one passphrase and no slots: a file does not hide how many passphrases exist, because there is one.
The keys
The passphrase is put in Unicode Normalization Form C (UAX #15), and its UTF-8 bytes are hashed with SHA-256 twice to make KDBX 4's composite key. Then "é" typed as one character (U+00E9) and as "e" with a combining accent (U+0065 U+0301) open the same vault.
Argon2id version 1.3 (RFC 9106) stretches the composite key under the header's salt, memory, passes and lanes to 32 bytes; SHA-256 and SHA-512 over that and the header make the encryption key and the HMAC base, and each block has its own HMAC key.
Create a vault offers five memory steps, from 64 MiB to 1 GiB, each at 3 passes and 4 lanes. The lanes do not change the work a guess costs.
Sealing and opening
The body is the database's XML, padded to the file's size with line feeds and encrypted with ChaCha20, in blocks of 1 048 576 bytes each with its own HMAC-SHA-256 over its length and bytes. The header carries its own SHA-256 and HMAC-SHA-256.
The reader checks the version, the header's fields, the cost against its limits and the file's length before any memory is asked for, then derives the keys once. Every block's HMAC is checked before its bytes are used; a missing or extra block, a changed byte and a cut file are refused.
A seal writes the file again with a fresh salt, fresh IVs and a fresh inner key, all from one answer the caller draws, and a seal count one more than the last with the time.
A file a KeePass app saved with another cipher or KDF the reader takes, or other settings, opens, and its next seal writes it in Faraday's shape; only a format mark other than the one this build writes or a Meta that reads ambiguously holds a vault read only.
What it promises
Without the passphrase, the file shows its header, which states the cost and the salt, and a length that is a whole number of 32 KiB steps. Nothing in the body can be read or changed without the passphrase: the header's and every block's HMAC fail first.
What it does not promise
Offline guessing. Anyone with the file has its salt and cost and can try passphrases on their own computers. Each guess costs one Argon2id at the vault's cost.
Rollback. An older copy of a vault still opens. Someone who can write to the stick can put an older copy back; they cannot read or change anything in it. The seal count is how an older copy is told from a newer one.
A vault's size and its seal count are in the clear or can be read by whoever opens it; the cost and salt are in the header.
Independent review. Faraday's reader and writer are its own and have been read by pykeepass, keepassxc-cli and keepass-rs, in the vault cross-check area, over the files they write and the files those programs write.
Availability. A changed byte anywhere in the file fails its HMAC and the vault does not open; a backup is how a damaged vault is recovered.
What is Faraday's own, and why
The format and the algorithms are published. These pieces are not. For each: what it does, what could replace it, and why it is not taken.
KDBX reader and writer. Reads and writes the file vault: the header, the block stream, the cipher steps and the XML. Could be replaced by the keepass crate (keepass-rs). It drops the XML elements it does not model, which would disturb what a KeePass app wrote into the file, and it draws a save's randomness itself, with no way to pass the session's in. No audit of it is one Faraday's dependency checks trust. It is used in the tests as an outside reader and writer, never in what ships.
Faraday's names inside the vault. Decides which KeePass field holds a seed's words, a wallet or a GPG key, and keeps Faraday's settings in custom data under names that start with faraday. Could be replaced by nothing, since no standard puts a Bitcoin seed in KeePass. Unavoidable. An item the reader does not expect is named Unreadable and never used.
Padding after the XML. Keeps each file at one of its sizes, by adding line feeds after the XML's closing tag. Could be replaced by nothing, since KDBX has no padding of its own. It uses what XML already allows after its last tag, so a KeePass app reads the padded file as any other. A KeePass app that saves the file drops the padding.
OpenPGP code for the QR vault. Writes and reads the three packets a QR vault is made of. Could be replaced by rPGP (pgp) or Sequoia. Each brings every algorithm OpenPGP has had, with all the libraries those need, for a message that uses AES and OCB alone. rPGP has been audited by outside reviewers, but none of those audits is one Faraday's dependency checks trust, so each library it brings would be Faraday's own to vet.
HKDF (RFC 5869). Turns one key into others; in the vault only the QR vault uses it. Could be replaced by the hkdf crate. It leaves the intermediate key and each output block in freed memory unwiped; Faraday's own wipes them.
QR vault contents. The short TOML inside the code, padded to one length, holding one seed, share, passphrase or note. Could be replaced by nothing, since no standard exists for an encrypted seed QR that other tools read. Unavoidable. The cross-check reads the contents with an outside TOML parser.
Security
What protects secrets is all published. Someone with the file faces Argon2id at the vault's memory step, then the cipher. None of that is Faraday's design.
The main risk is parsing. The device reads files from outside, and a bug in a reader could crash it, hang it, or make it accept or refuse a file wrongly. The guards: a file's memory, passes and lanes are checked against limits before any memory is asked for; every block's HMAC is checked before its bytes are used; anything unexpected is refused, never guessed at; the XML reader refuses a DOCTYPE and an entity it does not know; each reader has a fuzz target; and pykeepass, keepassxc-cli and keepass-rs read what Faraday writes, and Faraday reads what they write.
The QR vault's reader checks the Argon2 cost against the same limits right after the key packet, before the data packet is read, and refuses every packet it does not use.
The one subtle risk is in writing. If Faraday's code reused a value it should draw fresh, a nonce for example, the file would still open everywhere, so the cross-check would not notice, but the encryption would be weaker. A library carries the same risk in its own code. The guard: every seal draws its bytes from one call for the session's randomness, and the specification counts every byte that call returns.
The library trade. A large audited library is more code that Faraday did not write and more to vet, looked at by others. A small piece of Faraday's own is less code and nothing extra to vet, looked at by Faraday, its tests and three outside programs. For one file format the small piece is taken, and keepass-rs would also give up two requirements of the file vault: that what a KeePass app wrote is kept, and that the session's randomness is the only source.
Key commitment. Every HMAC in a file vault is keyed from the key its passphrase makes, so no second passphrase opens the file to other contents.
OCB does not commit to its key. A QR vault someone else made could be built to open to two contents under two passphrases. Faraday makes every QR vault under one passphrase.
Later work. Faraday does not yet wipe every copy of a key left in freed memory, and Argon2id's later passes read memory at places the passphrase decides, which a program on the same computer could time. The device is offline and powered off after use, so both wait.
Opening it elsewhere
This shows the file is standard, and is not the way to use a vault. The cross-check opens a file vault with pykeepass, keepassxc-cli and keepass-rs, and Faraday opens what they write.
A QR vault is read by Sequoia's sq and by rPGP in the cross-check. GnuPG cannot read a QR vault: it follows LibrePGP, not RFC 9580.
Unlocking a vault on a computer that is online shows its seed on that computer. It is a last resort, for when Faraday is gone and the seed is needed back. Move the funds to a new seed afterwards and treat the old seed as exposed. The way to open a vault is Faraday on the offline device.
A passphrase of words drawn by dice from a list carries log2 of the list's length in bits for every word. Faraday has the three lists the EFF publishes (EFF word lists):
Words
EFF large list: 7 776 words, 12.9 bits a word
EFF short list 1: 1 296 words, 10.3 bits a word
EFF short list 2: 1 296 words, 10.3 bits a word
4
51.7
41.4
41.4
5
64.6
51.7
51.7
6
77.5
62.0
62.0
7
90.5
72.4
72.4
8
103.4
82.7
82.7
9
116.3
93.1
93.1
10
129.2
103.4
103.4
The bits hold when every word is drawn by fair dice or by the computer's randomness, and not when a person chooses a word.
What Argon2id adds
Each guess costs one Argon2id at the vault's memory and passes, on the guesser's own hardware. Faraday states that work as log2(memory in KiB × passes) bits, which Create a vault shows beside each cost. The memory of the vaults Faraday makes ranges over a factor of 16, which is 4 bits; one more word from the large list is 12.9. The figure counts work, not how much more memory costs a guesser than time, and it gives no time per guess.
Other passphrases
A person may use any passphrase. Its strength is then theirs to ensure: Faraday does not measure a typed passphrase. A short passphrase, or one used anywhere else, is not protected by any cost.
Where to learn more
The EFF's page on dice-generated passphrases, eff.org/dice.
Makes a vault file: an empty KDBX 4 database with a root group of the given UUID and name, stamped as the first seal, written at the smallest size, 32 KiB of contents, under one passphrase with Argon2id, ChaCha20 and an HMAC per block; the file's salt, IVs and inner key come from one 140-byte answer the caller draws.
Specification
Own specification
KeePass KDBX 4, The KeePass database format, version 4, Convention
RFC 9106, Argon2 Memory-Hard Function for Password Hashing and Proof-of-Work Applications, Informational
RFC 8439, ChaCha20 and Poly1305 for IETF Protocols, Status not checked
RFC 2104, HMAC: Keyed-Hashing for Message Authentication, Status not checked
UAX #15, Unicode Standard Annex #15: Unicode Normalization Forms, Complete
Code
Library: chacha20 0.10.2, by the RustCrypto developers.
Library: hmac 0.13.0, by the RustCrypto developers.
Library: sha2 0.11.0, by the RustCrypto developers.
Library: unicode-normalization 0.1.25, by the unicode-rs developers.
Library: argon2 0.6.0, by the RustCrypto developers, through core/faraday-crypto.
Faraday's code: faraday/faraday-vault: The passphrase is put in NFC; the container is `kdbx::seal` (the `vault-kdbx` action); a size that is not one of the four is refused before any work; a cost whose memory cannot be allocated is an error that names the MiB needed.
Checked against
tools/vectors/vault
Faraday's own known answers.
tools/vectors/vault-primitives
Published, by the Argon2id answer of tools/vectors/kdf (argon2-cffi and OpenSSL agree on it).
tools/vectors/kdf
Published, by RFC 7914 §12, for scrypt; the Argon2id answer computed by argon2-cffi and PyCA cryptography, which agree.
An outside review recorded in a decision ends it; a reproduction from the specification by an outside party is asked for in docs/AUDIT-SUBMISSIONS.md §10.
not cross-checked: The `vault` cross-check area judges the Argon2id step (argon2-cffi and PyCA) and the NFC step (Python's `unicodedata`) a vault is made with. The KDBX file `file::create` makes, and the one an export makes (`file::create_holding`), is read by pykeepass, `keepassxc-cli` and keepass-rs in that area, and its changes by them too
Not stated by the argon2, hmac or chacha20 crates.
The Argon2id output, the encryption key, the HMAC base and every block key are Secret values wiped on drop; the Argon2id memory is overwritten before it is released; the passphrase's NFC form is wiped on drop (the normaliser's own buffer of combining marks is not).
Limits
One passphrase, non-empty; no slots, no second passphrase.
File sizes 64 KiB, 256 KiB, 1 MiB and 4 MiB only.
A vault is made at any cost the reader accepts: memory 8 MiB to 1 GiB, 1 to 100 passes, 1 to 64 lanes.
A cost whose memory cannot be allocated is an error that names the MiB needed.
A passphrase is put in Unicode NFC, and Argon2id takes that form's UTF-8 bytes.
Faraday's own calls
The file vault is one KDBX 4 file with one passphrase, padded to a multiple of 32 KiB, so a file's length says how much it holds to within 32 KiB and, between two copies, that it grew or shrank (F206). Conservative, F206.
Every passphrase is put in Unicode NFC before Argon2id, and nothing else is done to it: compatibility characters, case and spaces are kept as typed. Neutral, F159.
Opens a vault file with its passphrase: checks the header and the cost before any memory is asked for, derives the keys once with Argon2id, checks the header's and every block's HMAC, decrypts and inflates the body and reads its items; a wrong passphrase and a damaged file are told apart only where KDBX 4 allows.
Specification
Own specification
KeePass KDBX 4, The KeePass database format, version 4, Convention
RFC 9106, Argon2 Memory-Hard Function for Password Hashing and Proof-of-Work Applications, Informational
RFC 8439, ChaCha20 and Poly1305 for IETF Protocols, Status not checked
RFC 2104, HMAC: Keyed-Hashing for Message Authentication, Status not checked
UAX #15, Unicode Standard Annex #15: Unicode Normalization Forms, Complete
Code
Library: chacha20 0.10.2, by the RustCrypto developers.
Library: hmac 0.13.0, by the RustCrypto developers.
Library: sha2 0.11.0, by the RustCrypto developers.
Library: unicode-normalization 0.1.25, by the unicode-rs developers.
Library: argon2 0.6.0, by the RustCrypto developers, through core/faraday-crypto.
Faraday's code: faraday/faraday-vault: The passphrase is put in NFC; the container is `kdbx::open` (the `vault-kdbx` action); a file longer than the largest vault takes, or whose cost or version is outside the limits, is refused before any work; a file of another length opens with no size stated, and its next seal takes the smallest size that holds the contents; a file a KeePass app saved with a cipher and a KDF the reader takes is opened and its next seal writes it in Faraday's one shape; only a `faraday.format` other than the one this build writes, or a Meta or custom data that cannot be told apart from what was read, holds a vault read only.
Checked against
tools/vectors/vault
Faraday's own known answers.
tools/vectors/vault-primitives
Published, by the Argon2id answer of tools/vectors/kdf (argon2-cffi and OpenSSL agree on it).
tools/vectors/kdf
Published, by RFC 7914 §12, for scrypt; the Argon2id answer computed by argon2-cffi and PyCA cryptography, which agree.
An outside review recorded in a decision ends it; a reproduction from the specification by an outside party is asked for in docs/AUDIT-SUBMISSIONS.md §10.
Compared with others' code: argon2-cffi (the Argon2 designers' reference code), for Argon2id, and Python's unicodedata, for the NFC form.
Compared, for one part, with Faraday's second version, written by Faraday's authors in Python; that part is not checked against an outside source: the payload layouts of docs/VAULT.md §7, written in area_vault.py from that document; the KDBX file itself is read by pykeepass, keepassxc-cli and keepass-rs in the area (an outside reader each).
Area vault
Faraday's code faraday_vault's file (file::create, open and seal, the document model and the items of §7), its payload layouts and a passphrase's NFC form with the Unicode version it is made under, file::create_holding (an export), and faraday_crypto::argon2id
Compared with Pykeepass and keepassxc-cli (the distribution's packages) for the vault file, both ways, and keepass-rs for the file format only; docs/VAULT.md §7 written out in area_vault.py, over argon2-cffi and PyCA cryptography's Argon2id (OpenSSL's) (the distribution's packages) and Python's unicodedata, for the payloads.
Checked first: check_primitives runs before anything else: argon2-cffi and PyCA (44 or later over OpenSSL 3.2 or later, or the area stops) against tools/vectors/kdf/'s known answer; pykeepass and keepassxc-cli are the distribution's packages and the area stops and names a missing one, so a run without it fails; their versions are written into the stamp; the area stops where Python's Unicode is newer than unicode-normalization's.
keepass-rs does not count for the primitives and takes no part in the NFD or wrong-passphrase cases of files it did not read; the QR vault and OpenPGP are other areas.
Vectors The Argon2id known answer (tools/vectors/vault-primitives/); the export vector of tools/vectors/backup/, read with a byte changed refused, and with each bit of the version field and bit 44 of the Argon2 iterations changed refused; every file of tools/vectors/vault/, read by Faraday and by both outside readers.
Random cases Argon2id at small random costs and the costs it refuses; payloads made, read and malformed; passphrases in NFC, by case and at random; vaults Faraday writes at small costs with items of every kind of §7 and seals once more, read by pykeepass (every group, entry, field, protected mark and custom data item) and keepassxc-cli (listing and every field), under the passphrase, its NFD form, a wrong one and a changed byte; exports (file::create_holding) of one to eight entries whose Title, Notes and Password hold control characters, read the same way; files pykeepass makes at random (ciphers, KDFs, compression, tags, icons, custom properties, attachments, history, custom data) and keepassxc-cli makes (groups, entries, notes, attachments), opened in Faraday and sealed once more with nothing of the other program's lost; keepass-rs (format only, not counted for the primitives) reads the vaults Faraday writes and seals, with a wrong passphrase, the NFD form and a changed byte refused, and writes files (AES-256 or ChaCha20, Argon2d or Argon2id, compression or not, groups, entries, tags, icons, properties, attachments, custom data) that Faraday opens and seals once more.
Differences Pykeepass strips the characters XML 1.0 cannot hold from a protected value after decrypting it; Faraday keeps a Password's characters as they are put in (and leaves them out of a Title or Notes when it writes). The export loop expects pykeepass's reading of a Password and Faraday's own as put in, and counts the passwords that differ.
Pykeepass opens a file whose major version is neither 3 nor 4 without reading past it, deriving a key or checking a hash; KeePass refuses such a file, and the area counts a file as opened only when pykeepass read a KDBX 4 body (readers.open_kdbx). It also runs the key derivation the header states before it checks the header's SHA-256, so a changed bit in the Argon2 iterations (2^44 passes) holds it for good; KeePass and keepassxc-cli refuse at once, and the area asks pykeepass first with a key given and nothing decrypted.
The vault's passphrase is put in NFC (§3); KeePass apps do not. A vault under an NFC passphrase opens in Faraday under its NFD form and in neither outside reader. The area counts the NFD tries and expects exactly that.
Faraday's reader is stricter than the outside readers' in what it takes of a file (§4, §7.1): a block stream that ends before its empty last block (keepassxc-cli reads it), an XML document with an element after the root (keepassxc-cli), a protected value not canonical Base64, nesting past 64, another root element, a DOCTYPE and another encoding (pykeepass reads these). WIDER names each and the reader that opens it; the area expects exactly that set and counts those opens as known differences.
keepass-rs writes files Faraday refuses (§4): Twofish, AES-KDF and a Salsa20 inner stream (keepass_rs.REFUSED). The area makes one of each, expects Faraday to refuse it and counts the refusals as known differences.
KeePassXC 2.7.10 (and its development branch, November 2026) fails a save of a ChaCha20 file whose plaintext is a multiple of 1024 bytes, "Writing the database failed: Cannot process 0 length data.", and writes nothing: SymmetricCipherStream encrypts each full block of 1024 bytes as it fills and then the empty rest, which SymmetricCipher::process refuses (AES-256's last block is padded). Each save puts a random value of 128 to 1022 hex digits in the file (KPXC_RANDOM_SLUG), so it is chance, compressed or not, about one save in 450 at most. readers.Kpxc makes a command that writes again, once, from the file in a new shell, only on exactly that message and for a ChaCha20 file left byte for byte as it was; the save made again is judged as any other, a second such failure in a row fails the run, and each is counted as a known difference. The prelude shows the condition (kpxc_zero_length): on a file whose plaintext but for the random value is known (its ciphertext's length less the value pykeepass reads), 1500 saves that cannot reach a multiple of 1024 bytes do not fail, of saves that can, one must fail within 20,000, and the same file under AES-256 does not fail; when KeePassXC no longer fails, the run fails and the handling is to go.
keepass-rs decodes a custom data item's value as Base64 when it can, and the program encodes the bytes again (keepass-rs/src/main.rs). A value that is valid Base64 but not canonical (padding or trailing bits the encoder would not write) comes back as another text, so keepass-rs's reading of such a value differs from the file's and from pykeepass's. The area compares custom data as they are, so such a value is a known difference of keepass-rs, not a disagreement about the format.
When it runs Before every release, with a new seed and about ten times the cases.
Last passing runSeed 5be11ec606a76d2767f225b8992c45fe · 26310 cases
The header's and every block's HMAC are compared in constant time (`verify_slice`); Argon2, SHA-2 and ChaCha20 state nothing more.
The keys are Secret values wiped on drop; the decrypted and inflated body are Zeroizing buffers; the passphrase's NFC form is wiped on drop.
Limits
Refuses a file longer than the largest vault takes, and one whose version, cipher, KDF or cost is not one the reader takes, before any derivation; a file of another length is not refused.
Refuses a file in which any block's HMAC or the header's does not verify.
A wrong passphrase and a file that needs a key file as well give the same refusal.
KDBX 3.1, AES-KDF, Twofish and an empty passphrase are named and refused.
Faraday's own calls
A file a KeePass app saved with other settings is opened and changed like any vault, and its next seal writes it in Faraday's one shape; it is held read only only for a `faraday.format` other than the one this build writes or a Meta that reads ambiguously (F190). Conservative, F190.
SpecificationRFC 9580 · RFC 7253 · RFC 9106 · 1 morePublishedCodeFaraday's code: faraday/faraday-keysCross-checked withSequoia's sq and rPGPOthers' codeFaraday's second version
Action
Seals a typed note, a loaded key's words, or a seed, codex32 share, BIP-39 passphrase or note of an open file vault, as a QR vault under a typed passphrase and a memory step, and reads the seal back before the code is given.
Specification
RFC 9580, OpenPGP, Proposed Standard
RFC 7253, The OCB Authenticated-Encryption Algorithm, Informational
RFC 9106, Argon2 Memory-Hard Function for Password Hashing and Proof-of-Work Applications, Informational
RFC 5869, HMAC-based Extract-and-Expand Key Derivation Function (HKDF), Informational
Code
Faraday's code: faraday/faraday-keys: Writes the contents (`faraday-vault::contents`) and seals them as the message of the action above with 95 random bytes the device drew; a key's words are lent for the seal and not kept; a vault item is read once, when the job is made, checked to fit and left in the vault.
Compared with others' code: Sequoia's sq and rPGP, as for the OpenPGP message the code is.
Compared, for one part, with Faraday's second version, written by Faraday's authors in Python; that part is not checked against an outside source: none beyond the message's own.
Area qrvault
Faraday's code faraday_vault::qr (the QR vault sealed and opened, with faraday_pgp::message)
Compared with Sequoia's sq, the distribution's package, over Nettle (judges the primitives except Argon2, which it shares with the app's lineage); rPGP (tools/crosscheck/rpgp/, a program outside the workspace, on RustCrypto like the app: judges the format only); PyCA cryptography's Argon2id, HKDF-SHA-256 and AES-256-OCB (OpenSSL's), which judge the primitives, under the OpenPGP framing written in the area from RFC 9580 and docs/VAULT.md §1.2 (Faraday's second version, not another program's); the QR TOML qr_toml written in the area from §2.1, each opened item also read by CPython's tomllib.
Checked first: Sq is the distribution's package, built over Nettle (the run stops otherwise, judges.py), its version written into the stamp; rPGP is built from the crates.io release tools/crosscheck/rpgp/Cargo.lock names; PyCA must be 44 or later over OpenSSL 3.2 or later or the area stops, and its Argon2id, HKDF-SHA-256 and AES-OCB are checked against the repository's Argon2id known answer, RFC 5869 test case 1 and RFC 7253's first vector first; sq and rPGP open the repository's vault vectors, and so does the PyCA judge, which reads strictly and refuses anything but a QR vault.
OpenPGP.js, which docs/VAULT.md §10 names, is not run; sq does not seal a QR vault (below); rPGP judges the format only. §1.2's wider reading, which only Faraday's reader is held to, is not compared with a judge: any literal date, padding packets after the SEIPD packet and the literal data, and every length form RFC 9580 allows; of the chunk size octets only 0 (rPGP seals several chunks, Faraday opens them) and 10 are run.
Vectors The seven vaults of tools/vectors/vault/qr/ opened by sq, rPGP and the PyCA judge to the item each holds and by Faraday; the four refused messages refused by Faraday and by the PyCA judge; the PyCA judge refuses a vector with a byte changed in each field.
Random cases An item of every kind of §2.1 (12 and 24 words, a codex32 share, a passphrase, a note with markup, control characters and several scripts, the empty vault) sealed by Faraday and opened by sq, rPGP, the PyCA judge and Faraday, and sealed by rPGP and by the PyCA judge (memory 2^13 to 2^16 KiB) and opened by Faraday, each opened item read by tomllib; each memory step of §3 (2^16 to 2^20 KiB) sealed by Faraday at scale 1, each message equal byte for byte to the PyCA judge's seal of the same random bytes; items at the size limits (a note of 216 and 217 bytes, a passphrase of 193 and 194, a 24-word seed of the longest words); a passphrase in NFD or NFC either way; a wrong passphrase; a 15-word seed and a document of two keys sealed by rPGP, refused by Faraday; the messages sq writes, refused by Faraday and the PyCA judge; two items sealed by rPGP in chunks of 64 bytes (chunk size octet 0), opened by Faraday.
Differences QR vault: sq 1.3.1 writes a SKESK v4 and a SEIPD v1 for a password under either --profile, never the SKESK v6 and SEIPD v2 of RFC 9580, so sq cannot seal a QR vault; rPGP and the PyCA judge seal the other direction, and the area asserts that Faraday and the PyCA judge refuse what sq writes. The PyCA judge's framing is the area's own Python; OpenPGP.js is not run.
When it runs Before every release, with a new seed and about ten times the cases.
Last passing runSeed 5be11ec606a76d2767f225b8992c45fe · 450 cases
The typed note and passphrases are wiped when the code is made; the random bytes and the key's or vault item's words copied into the job are wiped on drop, not lent.
Limits
A note holds the room the contents leave; a key of other than 12 or 24 English words is not offered; a vault item over the same room is refused with the reason, and a note with the characters to take off.
The memory step is one of the steps the message allows; a computer without the room for it refuses.
Faraday's own calls
A passphrase is typed twice and is not measured; the code is only as strong as it. Neutral, F190.
SpecificationRFC 9580 · RFC 7253 · RFC 9106 · 1 morePublishedCodeFaraday's code: faraday/faraday-keysCross-checked withSequoia's sq and rPGPOthers' codeFaraday's second version
Action
Opens a scanned QR vault code, or a chosen .pgp file, under a typed passphrase, and holds the one item it holds for the QR vault tool to say what it is and, behind an eye, to show a note or a passphrase; then offers what that item takes: a seed's words to the seed sheet, a share to the codex32 form, a passphrase added to the loaded key whose words make the key it names (with the offer worked out from fingerprints alone), and a note saved in the open file vault.
Specification
RFC 9580, OpenPGP, Proposed Standard
RFC 7253, The OCB Authenticated-Encryption Algorithm, Informational
RFC 9106, Argon2 Memory-Hard Function for Password Hashing and Proof-of-Work Applications, Informational
RFC 5869, HMAC-based Extract-and-Expand Key Derivation Function (HKDF), Informational
Code
Faraday's code: faraday/faraday-keys: Reads the message of the action above with the typed passphrase after its stated Argon2 cost is checked against the limits (the app also checks the cost against the memory this computer has free before it starts the job, and names a code it cannot open at once), and reads the contents (`faraday-vault::contents`) into one held item that leaves `faraday-keys` only through the `Reveal::QrVault` reveals. The offers lend the held words or share once to the seed sheet or the codex32 form; `qr_passphrase_offer` makes the BIP-39 seed and BIP-32 master fingerprint of each loaded key with the held passphrase and returns only fingerprints, and `qr_add_passphrase` adds the key it finds; `qr_save_note` writes the note as a note record of the open vault.
Compared with others' code: Sequoia's sq and rPGP, as for the OpenPGP message the code is.
Compared, for one part, with Faraday's second version, written by Faraday's authors in Python; that part is not checked against an outside source: none beyond the message's own.
Area qrvault
Faraday's code faraday_vault::qr (the QR vault sealed and opened, with faraday_pgp::message)
Compared with Sequoia's sq, the distribution's package, over Nettle (judges the primitives except Argon2, which it shares with the app's lineage); rPGP (tools/crosscheck/rpgp/, a program outside the workspace, on RustCrypto like the app: judges the format only); PyCA cryptography's Argon2id, HKDF-SHA-256 and AES-256-OCB (OpenSSL's), which judge the primitives, under the OpenPGP framing written in the area from RFC 9580 and docs/VAULT.md §1.2 (Faraday's second version, not another program's); the QR TOML qr_toml written in the area from §2.1, each opened item also read by CPython's tomllib.
Checked first: Sq is the distribution's package, built over Nettle (the run stops otherwise, judges.py), its version written into the stamp; rPGP is built from the crates.io release tools/crosscheck/rpgp/Cargo.lock names; PyCA must be 44 or later over OpenSSL 3.2 or later or the area stops, and its Argon2id, HKDF-SHA-256 and AES-OCB are checked against the repository's Argon2id known answer, RFC 5869 test case 1 and RFC 7253's first vector first; sq and rPGP open the repository's vault vectors, and so does the PyCA judge, which reads strictly and refuses anything but a QR vault.
OpenPGP.js, which docs/VAULT.md §10 names, is not run; sq does not seal a QR vault (below); rPGP judges the format only. §1.2's wider reading, which only Faraday's reader is held to, is not compared with a judge: any literal date, padding packets after the SEIPD packet and the literal data, and every length form RFC 9580 allows; of the chunk size octets only 0 (rPGP seals several chunks, Faraday opens them) and 10 are run.
Vectors The seven vaults of tools/vectors/vault/qr/ opened by sq, rPGP and the PyCA judge to the item each holds and by Faraday; the four refused messages refused by Faraday and by the PyCA judge; the PyCA judge refuses a vector with a byte changed in each field.
Random cases An item of every kind of §2.1 (12 and 24 words, a codex32 share, a passphrase, a note with markup, control characters and several scripts, the empty vault) sealed by Faraday and opened by sq, rPGP, the PyCA judge and Faraday, and sealed by rPGP and by the PyCA judge (memory 2^13 to 2^16 KiB) and opened by Faraday, each opened item read by tomllib; each memory step of §3 (2^16 to 2^20 KiB) sealed by Faraday at scale 1, each message equal byte for byte to the PyCA judge's seal of the same random bytes; items at the size limits (a note of 216 and 217 bytes, a passphrase of 193 and 194, a 24-word seed of the longest words); a passphrase in NFD or NFC either way; a wrong passphrase; a 15-word seed and a document of two keys sealed by rPGP, refused by Faraday; the messages sq writes, refused by Faraday and the PyCA judge; two items sealed by rPGP in chunks of 64 bytes (chunk size octet 0), opened by Faraday.
Differences QR vault: sq 1.3.1 writes a SKESK v4 and a SEIPD v1 for a password under either --profile, never the SKESK v6 and SEIPD v2 of RFC 9580, so sq cannot seal a QR vault; rPGP and the PyCA judge seal the other direction, and the area asserts that Faraday and the PyCA judge refuse what sq writes. The PyCA judge's framing is the area's own Python; OpenPGP.js is not run.
When it runs Before every release, with a new seed and about ten times the cases.
Last passing runSeed 5be11ec606a76d2767f225b8992c45fe · 450 cases
The typed passphrase is wiped when the open ends, stops or fails; words or a share lent to an offer are wiped as the seed sheet or the form takes them; the item held is wiped on the next open, on leaving the tool, at the idle warning and at a lock.
Limits
A message Faraday does not open, or a stated cost outside the limits, is named before any memory is taken.
A wrong passphrase is told from a changed message and may be tried again.
No key loads with a stick plugged in; the card says so. A key already loaded is not added twice; a vault that is read-only, full or not open takes no note.
Writes and reads the KDBX 4 container a file vault is: Argon2id (or, read only, Argon2d) over the SHA-256 of the passphrase's SHA-256, SHA-256 and SHA-512 key steps, ChaCha20 (or, read only, AES-256-CBC) over the body, HMAC-SHA-256 over the header and over every block of the stream, gzip read, and the inner stream's ChaCha20 over protected values. The store's functions listed here make the seal's job: the writes a seal makes from the records changed (a change the seal cannot write refuses it, never dropped), the UUIDs new entries and groups take from the bytes the seal draws (one fresh answer expanded by SHA-256 over a domain string, the answer and a counter: the UUIDs need to differ, not to be secret), and the check that the changes fit the file's size.
Specification
Own specification
KeePass KDBX 4, The KeePass database format, version 4, Convention
RFC 9106, Argon2 Memory-Hard Function for Password Hashing and Proof-of-Work Applications, Informational
RFC 8439, ChaCha20 and Poly1305 for IETF Protocols, Status not checked
RFC 2104, HMAC: Keyed-Hashing for Message Authentication, Status not checked
FIPS 197, Advanced Encryption Standard (AES), Status not checked
RFC 1952, GZIP file format specification version 4.3, Status not checked
Code
Library: chacha20 0.10.2, by the RustCrypto developers.
Library: aes 0.9.3, by the RustCrypto developers.
Library: cbc 0.2.1, by the RustCrypto developers.
Library: base64ct 1.8.3, by the RustCrypto developers.
Library: hmac 0.13.0, by the RustCrypto developers.
Library: quick-xml 0.41.0, by the quick-xml developers.
Library: miniz_oxide 0.8.9 and 0.9.1, by the miniz_oxide developers, a port of Rich Geldreich's miniz.
Library: sha2 0.11.0, by the RustCrypto developers.
Library: argon2 0.6.0, by the RustCrypto developers, through core/faraday-crypto.
Faraday's code: faraday/faraday-vault: The container only, not the meaning of entries: signatures and version (4.0 and 4.1), the header fields (an unknown one refused), the KDF parameters' VariantDictionary with the cost checked against the vault's limits before any memory is asked for, the header's SHA-256 and HMAC, the HMAC block stream (every block's HMAC checked before its bytes are used, a missing or extra block refused), the cipher, gzip read into a buffer sized from its stated length and bounded by the largest vault, and the inner header with its attachments carried. KDBX 3.1, AES-KDF, Twofish, Salsa20 as the inner stream and an empty passphrase are named and refused; a key file or a challenge-response key is not recorded in a KDBX 4 header, so such a file cannot be told from a wrong passphrase (owner, 2026-11-02) and the wrong-passphrase message for a KeePass file says that a file which also needs one cannot be opened here. An Argon2 version missing from the parameters is a damaged file, as KeePass and KeePassXC take it. A file is written as Faraday writes one: 4.0, ChaCha20, Argon2id, no compression, 1 MiB blocks, the plaintext padded with line feeds to the size asked for; the master seed, IV, Argon2 salt and inner stream key are the 140 bytes the caller passes. The XML document (`kdbx::xml`) is read over quick-xml's tokenizer and refused, naming what was found, for a document not well formed, a DOCTYPE, an entity other than XML's five and character references, an XML declaration anywhere but the start, anything after the root other than XML whitespace, comments and processing instructions, nesting past 64, markup inside a text element the model reads, a Meta or Root missing or repeated, and a protected value that is not canonical Base64 (base64ct) of text; a comment or processing instruction is carried, and skipped in text the model reads; an entry or group with two UUIDs or a UUID of other than 16 bytes, a field with two values and the like is marked ambiguous and left as read, not refused; every protected value, those in carried bytes, history and the recycle bin included, is decrypted in document order and, on writing, the ones written are encrypted in document order under the new key from their plaintexts; what the model does not read is carried as the bytes read, and history and the recycle bin (the bin dropped while RecycleBinEnabled is True or absent) are dropped and counted.
Written by Faraday
The KDBX 4 container a file vault is: header, VariantDictionary, HMAC block stream, inner header and gzip framing (faraday-vault::kdbx) · Only the part used is written
Faraday writes only the part of KeePass's format the vault uses, over argon2, chacha20, aes and cbc, hmac, sha2 and miniz_oxide; keepass-rs, which no review Faraday trusts covers, drops the XML elements it does not read and draws a save's randomness itself.
Computed by pykeepass 4.1.1 (the distribution's 4.1.1.post1), run by tools/vectors/kdbx/make.py (both ciphers, both Argon2 types, with and without gzip, a header marked 4.1, and a file with a 1.2 MiB attachment, more than one block of the stream); KeePassXC 2.7.12's own KDBX 3.1 file.
An outside review recorded in a decision ends it; a reproduction from the specification by an outside party is asked for in docs/AUDIT-SUBMISSIONS.md §10.
not cross-checked: Opened from pykeepass's files in both ciphers and both KDFs (read here) and the export's vector written again byte for byte; the file is read by pykeepass, `keepassxc-cli` and keepass-rs, and written by them and read here, in the `vault` cross-check area
The header's and every block's HMAC are compared in constant time (`verify_slice`); Argon2, SHA-2, ChaCha20 and AES-CBC state nothing more.
The composite key, the Argon2 output, the encryption key, the HMAC base and every block key are Secret values wiped on drop; the decrypted body, the inflated body, the document and the attachments are Zeroizing buffers, decrypted and unpadded in place; the Argon2 memory is overwritten before release. Not wiped: the SHA-256 and SHA-512 hashers' state, the ChaCha20 and AES-CBC cipher states and the AES key schedule, the inflater's own state, and the NFC normaliser's buffer of combining marks. The passphrase's first SHA-256 is a Zeroizing value; a seal works out the plaintext length before the buffer is grown, so a refusal as too small leaves no copy.
Limits
Version 4.0 and 4.1 only; KDBX 3.1 and older are named and not opened.
Argon2 version 1.3 with 8 MiB to 1 GiB of memory, 1 to 100 passes and 1 to 64 lanes, no secret key and no associated data; a cost outside is refused before any memory is asked for.
A plaintext of at most 4 MiB; a file too long to hold one is refused before any work, and a gzip body that states more is refused as soon as it is read.
The composite key is the passphrase alone; a key file or a challenge-response key cannot be told from a wrong passphrase (KDBX 4 records neither).
The passphrase arrives in Unicode NFC; the container puts it there.
Faraday's own calls
Only the part of KDBX used is written (F178, F190): the file is written in one shape, and a KeePass app's other choices are read. Conservative, F190.
SpecificationKeePass KDBX 4 · RFC 8439 · RFC 2104PublishedOwn specificationCodeLibrary: chacha20 0.10Library: hmac 0.13Library: sha2 0.111 moreFaraday's code: faraday/faraday-vaultCross-checked withargon2-cffi (the Argon2 designers' reference code)Others' codeFaraday's second version
Action
Writes an open vault back: applies the changes to its document, stamps the seal count and time, and seals the file at the size the changes fit, with a fresh salt, IVs and inner key from the bytes the caller draws.
Specification
Own specification
KeePass KDBX 4, The KeePass database format, version 4, Convention
RFC 8439, ChaCha20 and Poly1305 for IETF Protocols, Status not checked
RFC 2104, HMAC: Keyed-Hashing for Message Authentication, Status not checked
Code
Library: chacha20 0.10.2, by the RustCrypto developers.
Library: hmac 0.13.0, by the RustCrypto developers.
Library: sha2 0.11.0, by the RustCrypto developers.
Library: argon2 0.6.0, by the RustCrypto developers, through core/faraday-crypto.
Faraday's code: faraday/faraday-vault: The container is `kdbx::seal` (the `vault-kdbx` action); the seal count is one more than the last and the time is the caller's; a change the file cannot write refuses the seal and is never dropped; history and the recycle bin are dropped and counted; a vault under a cost below the first step takes the first step.
An outside review recorded in a decision ends it; a reproduction from the specification by an outside party is asked for in docs/AUDIT-SUBMISSIONS.md §10.
Compared with others' code: argon2-cffi (the Argon2 designers' reference code), for Argon2id, and Python's unicodedata, for the NFC form.
Compared, for one part, with Faraday's second version, written by Faraday's authors in Python; that part is not checked against an outside source: the payload layouts of docs/VAULT.md §7, written in area_vault.py from that document; the KDBX file itself is read by pykeepass, keepassxc-cli and keepass-rs in the area (an outside reader each).
Area vault
Faraday's code faraday_vault's file (file::create, open and seal, the document model and the items of §7), its payload layouts and a passphrase's NFC form with the Unicode version it is made under, file::create_holding (an export), and faraday_crypto::argon2id
Compared with Pykeepass and keepassxc-cli (the distribution's packages) for the vault file, both ways, and keepass-rs for the file format only; docs/VAULT.md §7 written out in area_vault.py, over argon2-cffi and PyCA cryptography's Argon2id (OpenSSL's) (the distribution's packages) and Python's unicodedata, for the payloads.
Checked first: check_primitives runs before anything else: argon2-cffi and PyCA (44 or later over OpenSSL 3.2 or later, or the area stops) against tools/vectors/kdf/'s known answer; pykeepass and keepassxc-cli are the distribution's packages and the area stops and names a missing one, so a run without it fails; their versions are written into the stamp; the area stops where Python's Unicode is newer than unicode-normalization's.
keepass-rs does not count for the primitives and takes no part in the NFD or wrong-passphrase cases of files it did not read; the QR vault and OpenPGP are other areas.
Vectors The Argon2id known answer (tools/vectors/vault-primitives/); the export vector of tools/vectors/backup/, read with a byte changed refused, and with each bit of the version field and bit 44 of the Argon2 iterations changed refused; every file of tools/vectors/vault/, read by Faraday and by both outside readers.
Random cases Argon2id at small random costs and the costs it refuses; payloads made, read and malformed; passphrases in NFC, by case and at random; vaults Faraday writes at small costs with items of every kind of §7 and seals once more, read by pykeepass (every group, entry, field, protected mark and custom data item) and keepassxc-cli (listing and every field), under the passphrase, its NFD form, a wrong one and a changed byte; exports (file::create_holding) of one to eight entries whose Title, Notes and Password hold control characters, read the same way; files pykeepass makes at random (ciphers, KDFs, compression, tags, icons, custom properties, attachments, history, custom data) and keepassxc-cli makes (groups, entries, notes, attachments), opened in Faraday and sealed once more with nothing of the other program's lost; keepass-rs (format only, not counted for the primitives) reads the vaults Faraday writes and seals, with a wrong passphrase, the NFD form and a changed byte refused, and writes files (AES-256 or ChaCha20, Argon2d or Argon2id, compression or not, groups, entries, tags, icons, properties, attachments, custom data) that Faraday opens and seals once more.
Differences Pykeepass strips the characters XML 1.0 cannot hold from a protected value after decrypting it; Faraday keeps a Password's characters as they are put in (and leaves them out of a Title or Notes when it writes). The export loop expects pykeepass's reading of a Password and Faraday's own as put in, and counts the passwords that differ.
Pykeepass opens a file whose major version is neither 3 nor 4 without reading past it, deriving a key or checking a hash; KeePass refuses such a file, and the area counts a file as opened only when pykeepass read a KDBX 4 body (readers.open_kdbx). It also runs the key derivation the header states before it checks the header's SHA-256, so a changed bit in the Argon2 iterations (2^44 passes) holds it for good; KeePass and keepassxc-cli refuse at once, and the area asks pykeepass first with a key given and nothing decrypted.
The vault's passphrase is put in NFC (§3); KeePass apps do not. A vault under an NFC passphrase opens in Faraday under its NFD form and in neither outside reader. The area counts the NFD tries and expects exactly that.
Faraday's reader is stricter than the outside readers' in what it takes of a file (§4, §7.1): a block stream that ends before its empty last block (keepassxc-cli reads it), an XML document with an element after the root (keepassxc-cli), a protected value not canonical Base64, nesting past 64, another root element, a DOCTYPE and another encoding (pykeepass reads these). WIDER names each and the reader that opens it; the area expects exactly that set and counts those opens as known differences.
keepass-rs writes files Faraday refuses (§4): Twofish, AES-KDF and a Salsa20 inner stream (keepass_rs.REFUSED). The area makes one of each, expects Faraday to refuse it and counts the refusals as known differences.
KeePassXC 2.7.10 (and its development branch, November 2026) fails a save of a ChaCha20 file whose plaintext is a multiple of 1024 bytes, "Writing the database failed: Cannot process 0 length data.", and writes nothing: SymmetricCipherStream encrypts each full block of 1024 bytes as it fills and then the empty rest, which SymmetricCipher::process refuses (AES-256's last block is padded). Each save puts a random value of 128 to 1022 hex digits in the file (KPXC_RANDOM_SLUG), so it is chance, compressed or not, about one save in 450 at most. readers.Kpxc makes a command that writes again, once, from the file in a new shell, only on exactly that message and for a ChaCha20 file left byte for byte as it was; the save made again is judged as any other, a second such failure in a row fails the run, and each is counted as a known difference. The prelude shows the condition (kpxc_zero_length): on a file whose plaintext but for the random value is known (its ciphertext's length less the value pykeepass reads), 1500 saves that cannot reach a multiple of 1024 bytes do not fail, of saves that can, one must fail within 20,000, and the same file under AES-256 does not fail; when KeePassXC no longer fails, the run fails and the handling is to go.
keepass-rs decodes a custom data item's value as Base64 when it can, and the program encodes the bytes again (keepass-rs/src/main.rs). A value that is valid Base64 but not canonical (padding or trailing bits the encoder would not write) comes back as another text, so keepass-rs's reading of such a value differs from the file's and from pykeepass's. The area compares custom data as they are, so such a value is a known difference of keepass-rs, not a disagreement about the format.
When it runs Before every release, with a new seed and about ten times the cases.
Last passing runSeed 5be11ec606a76d2767f225b8992c45fe · 26310 cases
Not stated by the argon2, hmac or chacha20 crates.
The plaintext is a Zeroizing buffer, sized before it is grown so a refusal as too small leaves no copy; the keys are Secret values wiped on drop.
Limits
Refuses changes that do not fit the largest size, and names the bytes over and the next size.
Refuses a change the file cannot write, and keeps the vault open with its changes.
A vault held read only (a `faraday.format` other than the one this build writes, or a Meta or custom data that reads ambiguously) refuses every change and every seal (`Error::ReadOnly`); a KeePass app's other settings do not hold it read only.
Nothing is sealed before the session's answer has arrived.
Faraday's own calls
Each seal counts itself and stamps the sealing computer's clock in the file's custom data, so an older copy can be told from a newer one (F159). Neutral, F159.
Puts a secret of an open vault's record in the clear for the one reason named: a key's words or passphrase, a kept passphrase, an entry's password, TOTP secret or notes, a note's text.
Specification
Own specification (F70)
Code
Library: sha2 0.11.0, by the RustCrypto developers, through core/faraday-crypto.
Faraday's code: faraday/faraday-keys: Returns a borrowed text for one named part of one record, or an empty text where the record has no such part; a key's words are parsed again from the record each time and handed back as a value that wipes on drop.
SpecificationOwn specificationCodeFaraday's code: faraday/faraday-keysCross-checked withargon2-cffi (the Argon2 designers' reference code)Others' codeFaraday's second version
Action
Adds, changes, copies and makes public the records of an open vault, holding every secret field in a value that wipes on drop.
Specification
Own specification (F97)
Code
Faraday's code: faraday/faraday-keys: Records are typed fields (`docs/VAULT.md` §7); a copy between vaults is the same record bytes; a codex32 set's facts are written without any of its strings. No cryptographic primitive runs here; the functions are found because they hold secret fields and reach functions that do.
An outside review recorded in a decision ends it; a reproduction from the specification by an outside party is asked for in docs/AUDIT-SUBMISSIONS.md §10.
Compared with others' code: argon2-cffi (the Argon2 designers' reference code), for Argon2id, and Python's unicodedata, for the NFC form.
Compared, for one part, with Faraday's second version, written by Faraday's authors in Python; that part is not checked against an outside source: the payload layouts of docs/VAULT.md §7, written in area_vault.py from that document; the KDBX file itself is read by pykeepass, keepassxc-cli and keepass-rs in the area (an outside reader each).
Area vault
Faraday's code faraday_vault's file (file::create, open and seal, the document model and the items of §7), its payload layouts and a passphrase's NFC form with the Unicode version it is made under, file::create_holding (an export), and faraday_crypto::argon2id
Compared with Pykeepass and keepassxc-cli (the distribution's packages) for the vault file, both ways, and keepass-rs for the file format only; docs/VAULT.md §7 written out in area_vault.py, over argon2-cffi and PyCA cryptography's Argon2id (OpenSSL's) (the distribution's packages) and Python's unicodedata, for the payloads.
Checked first: check_primitives runs before anything else: argon2-cffi and PyCA (44 or later over OpenSSL 3.2 or later, or the area stops) against tools/vectors/kdf/'s known answer; pykeepass and keepassxc-cli are the distribution's packages and the area stops and names a missing one, so a run without it fails; their versions are written into the stamp; the area stops where Python's Unicode is newer than unicode-normalization's.
keepass-rs does not count for the primitives and takes no part in the NFD or wrong-passphrase cases of files it did not read; the QR vault and OpenPGP are other areas.
Vectors The Argon2id known answer (tools/vectors/vault-primitives/); the export vector of tools/vectors/backup/, read with a byte changed refused, and with each bit of the version field and bit 44 of the Argon2 iterations changed refused; every file of tools/vectors/vault/, read by Faraday and by both outside readers.
Random cases Argon2id at small random costs and the costs it refuses; payloads made, read and malformed; passphrases in NFC, by case and at random; vaults Faraday writes at small costs with items of every kind of §7 and seals once more, read by pykeepass (every group, entry, field, protected mark and custom data item) and keepassxc-cli (listing and every field), under the passphrase, its NFD form, a wrong one and a changed byte; exports (file::create_holding) of one to eight entries whose Title, Notes and Password hold control characters, read the same way; files pykeepass makes at random (ciphers, KDFs, compression, tags, icons, custom properties, attachments, history, custom data) and keepassxc-cli makes (groups, entries, notes, attachments), opened in Faraday and sealed once more with nothing of the other program's lost; keepass-rs (format only, not counted for the primitives) reads the vaults Faraday writes and seals, with a wrong passphrase, the NFD form and a changed byte refused, and writes files (AES-256 or ChaCha20, Argon2d or Argon2id, compression or not, groups, entries, tags, icons, properties, attachments, custom data) that Faraday opens and seals once more.
Differences Pykeepass strips the characters XML 1.0 cannot hold from a protected value after decrypting it; Faraday keeps a Password's characters as they are put in (and leaves them out of a Title or Notes when it writes). The export loop expects pykeepass's reading of a Password and Faraday's own as put in, and counts the passwords that differ.
Pykeepass opens a file whose major version is neither 3 nor 4 without reading past it, deriving a key or checking a hash; KeePass refuses such a file, and the area counts a file as opened only when pykeepass read a KDBX 4 body (readers.open_kdbx). It also runs the key derivation the header states before it checks the header's SHA-256, so a changed bit in the Argon2 iterations (2^44 passes) holds it for good; KeePass and keepassxc-cli refuse at once, and the area asks pykeepass first with a key given and nothing decrypted.
The vault's passphrase is put in NFC (§3); KeePass apps do not. A vault under an NFC passphrase opens in Faraday under its NFD form and in neither outside reader. The area counts the NFD tries and expects exactly that.
Faraday's reader is stricter than the outside readers' in what it takes of a file (§4, §7.1): a block stream that ends before its empty last block (keepassxc-cli reads it), an XML document with an element after the root (keepassxc-cli), a protected value not canonical Base64, nesting past 64, another root element, a DOCTYPE and another encoding (pykeepass reads these). WIDER names each and the reader that opens it; the area expects exactly that set and counts those opens as known differences.
keepass-rs writes files Faraday refuses (§4): Twofish, AES-KDF and a Salsa20 inner stream (keepass_rs.REFUSED). The area makes one of each, expects Faraday to refuse it and counts the refusals as known differences.
KeePassXC 2.7.10 (and its development branch, November 2026) fails a save of a ChaCha20 file whose plaintext is a multiple of 1024 bytes, "Writing the database failed: Cannot process 0 length data.", and writes nothing: SymmetricCipherStream encrypts each full block of 1024 bytes as it fills and then the empty rest, which SymmetricCipher::process refuses (AES-256's last block is padded). Each save puts a random value of 128 to 1022 hex digits in the file (KPXC_RANDOM_SLUG), so it is chance, compressed or not, about one save in 450 at most. readers.Kpxc makes a command that writes again, once, from the file in a new shell, only on exactly that message and for a ChaCha20 file left byte for byte as it was; the save made again is judged as any other, a second such failure in a row fails the run, and each is counted as a known difference. The prelude shows the condition (kpxc_zero_length): on a file whose plaintext but for the random value is known (its ciphertext's length less the value pykeepass reads), 1500 saves that cannot reach a multiple of 1024 bytes do not fail, of saves that can, one must fail within 20,000, and the same file under AES-256 does not fail; when KeePassXC no longer fails, the run fails and the handling is to go.
keepass-rs decodes a custom data item's value as Base64 when it can, and the program encodes the bytes again (keepass-rs/src/main.rs). A value that is valid Base64 but not canonical (padding or trailing bits the encoder would not write) comes back as another text, so keepass-rs's reading of such a value differs from the file's and from pykeepass's. The area compares custom data as they are, so such a value is a known difference of keepass-rs, not a disagreement about the format.
When it runs Before every release, with a new seed and about ten times the cases.
Last passing runSeed 5be11ec606a76d2767f225b8992c45fe · 26310 cases
Not applicable: no secret-dependent comparison is made.
A copied-out record is a Held value wiped on drop; a record removed or replaced is wiped; every record of a vault is wiped when it closes.
Limits
A record's size counts against the file; a vault whose records no longer fit the largest size cannot be sealed.
A codex32 set's record holds the threshold, identifier, length and each string's state, and no string.
Faraday's own calls
Faraday's own record layouts (`docs/VAULT.md` §7); the payload layouts are read by a second implementation Faraday's authors wrote from that document (`area_vault.py`) and the items by pykeepass, `keepassxc-cli` and keepass-rs. Novel, F97.
Loads a key kept in an open vault into the session: its words (BIP 39) and passphrase to the seed and the master key's fingerprint (BIP 32), or its master seed, or its codex32 set.
Specification
BIP 39, Mnemonic code for generating deterministic keys, Deployed
Library: sha2 0.11.0, by the RustCrypto developers, through core/faraday-crypto.
Library: unicode-normalization 0.1.25, by the unicode-rs developers, through core/faraday-bip.
Faraday's code: faraday/faraday-keys: Reads a record's words or seed from the open vault and hands them to the session's key functions; the vault record only decides which key is loaded and with which passphrase. A key loaded from a master seed, as a codex32 or SLIP-39 key is, is known to a vault by the id of a key record made of its seed.
Checked against
tools/vectors/bip39
Published, by Trezor (SatoshiLabs), python-mnemonic's vectors; bip32JP's Japanese vectors.
Compared with others' code: python-mnemonic, by Trezor (SatoshiLabs), and bip39_slip39, by the btclib developers (a second reader: wordlists, entropy, indices, checksums and the seed in the ten languages).
Area bip39
Faraday's code faraday_bip::bip39
Compared with python-mnemonic (bip39/); bip39_slip39 (bip39-slip39/) answering every operation beside it.
Checked first: Its vendored files are hashed against references.sha256 before any run, and a published vector's answer is required of the reference as well as of Faraday; python-mnemonic's own to_hd_master_key is checked against the seed's master key, as a second BIP-32 master; its wheel is hashed too, and a published vector's answer is required of bip39_slip39 as well.
Vectors The ten wordlists; every vector of tools/vectors/bip39/vectors.json in Faraday's languages; the Japanese vectors with non-ASCII passphrases.
Random cases Entropy to words and back in every language and length; seeds under random ASCII passphrases; a changed word, an unknown word, a word too many or too few; every valid last word.
Differences Both read a BIP-39 sentence in NFKD, so composed words and the Japanese vectors as published parse on both sides (owner, 2026-10-23).
A passphrase typed in Faraday is printable ASCII, at most 256 bytes; python-mnemonic takes any text. Faraday's vector tests and start-up self-test give a non-ASCII passphrase as its NFKD bytes, and the area checks that a typed one, or one past 256 bytes, is still refused.
When it runs Before every release, with a new seed and about ten times the cases.
Last passing runSeed 5be11ec606a76d2767f225b8992c45fe · 30000 cases
Writes a KeePass database of one entry under a passphrase, as a one-entry vault: the same KDBX 4.0 file the vault is (Argon2id, SHA-256 and SHA-512 key steps, ChaCha20 over the body, HMAC-SHA-256 block authentication), sealed at the smallest size that holds it.
Specification
Own specification
KeePass KDBX 4, The KeePass database format, version 4, Convention
RFC 9106, Argon2 Memory-Hard Function for Password Hashing and Proof-of-Work Applications, Informational
RFC 8439, ChaCha20 and Poly1305 for IETF Protocols, Status not checked
Code
Library: chacha20 0.10.2, by the RustCrypto developers.
Library: hmac 0.13.0, by the RustCrypto developers.
Library: sha2 0.11.0, by the RustCrypto developers.
Library: base64ct 1.8.3, by the RustCrypto developers.
Library: argon2 0.6.0, by the RustCrypto developers, through core/faraday-crypto.
Faraday's code: faraday/faraday-vault: A KeePass export is a vault of one entry (`docs/VAULT.md` section 8): the vault's own container and document model, one group and one entry holding the secret, sealed by the vault's `kdbx::seal` at the smallest of the vault sizes that holds it, under the passphrase put in NFC. The vault id, the seal's salt, seed, IV and inner key, and the entry's UUIDs are three draws of the session's randomness, each with its label (`vault id`, `vault seal`, `vault entries`), and nothing is made until the system has answered.
Checked against
tools/vectors/backup
Faraday's own known answers.
tools/vectors/kdf
Published, by RFC 7914 §12, for scrypt; the Argon2id answer computed by argon2-cffi and PyCA cryptography, which agree.
An outside review recorded in a decision ends it; a reproduction from the specification by an outside party is asked for in docs/AUDIT-SUBMISSIONS.md §10.
Compared with others' code: pykeepass, by the libkeepass project, and KeePassXC's keepassxc-cli (the distribution's packages), and argon2-cffi and PyCA's cryptography over OpenSSL for the Argon2id.
Area vault
Faraday's code faraday_vault's file (file::create, open and seal, the document model and the items of §7), its payload layouts and a passphrase's NFC form with the Unicode version it is made under, file::create_holding (an export), and faraday_crypto::argon2id
Compared with Pykeepass and keepassxc-cli (the distribution's packages) for the vault file, both ways, and keepass-rs for the file format only; docs/VAULT.md §7 written out in area_vault.py, over argon2-cffi and PyCA cryptography's Argon2id (OpenSSL's) (the distribution's packages) and Python's unicodedata, for the payloads.
Checked first: check_primitives runs before anything else: argon2-cffi and PyCA (44 or later over OpenSSL 3.2 or later, or the area stops) against tools/vectors/kdf/'s known answer; pykeepass and keepassxc-cli are the distribution's packages and the area stops and names a missing one, so a run without it fails; their versions are written into the stamp; the area stops where Python's Unicode is newer than unicode-normalization's.
keepass-rs does not count for the primitives and takes no part in the NFD or wrong-passphrase cases of files it did not read; the QR vault and OpenPGP are other areas.
Vectors The Argon2id known answer (tools/vectors/vault-primitives/); the export vector of tools/vectors/backup/, read with a byte changed refused, and with each bit of the version field and bit 44 of the Argon2 iterations changed refused; every file of tools/vectors/vault/, read by Faraday and by both outside readers.
Random cases Argon2id at small random costs and the costs it refuses; payloads made, read and malformed; passphrases in NFC, by case and at random; vaults Faraday writes at small costs with items of every kind of §7 and seals once more, read by pykeepass (every group, entry, field, protected mark and custom data item) and keepassxc-cli (listing and every field), under the passphrase, its NFD form, a wrong one and a changed byte; exports (file::create_holding) of one to eight entries whose Title, Notes and Password hold control characters, read the same way; files pykeepass makes at random (ciphers, KDFs, compression, tags, icons, custom properties, attachments, history, custom data) and keepassxc-cli makes (groups, entries, notes, attachments), opened in Faraday and sealed once more with nothing of the other program's lost; keepass-rs (format only, not counted for the primitives) reads the vaults Faraday writes and seals, with a wrong passphrase, the NFD form and a changed byte refused, and writes files (AES-256 or ChaCha20, Argon2d or Argon2id, compression or not, groups, entries, tags, icons, properties, attachments, custom data) that Faraday opens and seals once more.
Differences Pykeepass strips the characters XML 1.0 cannot hold from a protected value after decrypting it; Faraday keeps a Password's characters as they are put in (and leaves them out of a Title or Notes when it writes). The export loop expects pykeepass's reading of a Password and Faraday's own as put in, and counts the passwords that differ.
Pykeepass opens a file whose major version is neither 3 nor 4 without reading past it, deriving a key or checking a hash; KeePass refuses such a file, and the area counts a file as opened only when pykeepass read a KDBX 4 body (readers.open_kdbx). It also runs the key derivation the header states before it checks the header's SHA-256, so a changed bit in the Argon2 iterations (2^44 passes) holds it for good; KeePass and keepassxc-cli refuse at once, and the area asks pykeepass first with a key given and nothing decrypted.
The vault's passphrase is put in NFC (§3); KeePass apps do not. A vault under an NFC passphrase opens in Faraday under its NFD form and in neither outside reader. The area counts the NFD tries and expects exactly that.
Faraday's reader is stricter than the outside readers' in what it takes of a file (§4, §7.1): a block stream that ends before its empty last block (keepassxc-cli reads it), an XML document with an element after the root (keepassxc-cli), a protected value not canonical Base64, nesting past 64, another root element, a DOCTYPE and another encoding (pykeepass reads these). WIDER names each and the reader that opens it; the area expects exactly that set and counts those opens as known differences.
keepass-rs writes files Faraday refuses (§4): Twofish, AES-KDF and a Salsa20 inner stream (keepass_rs.REFUSED). The area makes one of each, expects Faraday to refuse it and counts the refusals as known differences.
KeePassXC 2.7.10 (and its development branch, November 2026) fails a save of a ChaCha20 file whose plaintext is a multiple of 1024 bytes, "Writing the database failed: Cannot process 0 length data.", and writes nothing: SymmetricCipherStream encrypts each full block of 1024 bytes as it fills and then the empty rest, which SymmetricCipher::process refuses (AES-256's last block is padded). Each save puts a random value of 128 to 1022 hex digits in the file (KPXC_RANDOM_SLUG), so it is chance, compressed or not, about one save in 450 at most. readers.Kpxc makes a command that writes again, once, from the file in a new shell, only on exactly that message and for a ChaCha20 file left byte for byte as it was; the save made again is judged as any other, a second such failure in a row fails the run, and each is counted as a known difference. The prelude shows the condition (kpxc_zero_length): on a file whose plaintext but for the random value is known (its ciphertext's length less the value pykeepass reads), 1500 saves that cannot reach a multiple of 1024 bytes do not fail, of saves that can, one must fail within 20,000, and the same file under AES-256 does not fail; when KeePassXC no longer fails, the run fails and the handling is to go.
keepass-rs decodes a custom data item's value as Base64 when it can, and the program encodes the bytes again (keepass-rs/src/main.rs). A value that is valid Base64 but not canonical (padding or trailing bits the encoder would not write) comes back as another text, so keepass-rs's reading of such a value differs from the file's and from pykeepass's. The area compares custom data as they are, so such a value is a known difference of keepass-rs, not a disagreement about the format.
When it runs Before every release, with a new seed and about ten times the cases.
Last passing runSeed 5be11ec606a76d2767f225b8992c45fe · 26310 cases
The header's and every block's HMAC are compared in constant time (`verify_slice`); Argon2, SHA-2 and ChaCha20 state nothing more.
The Argon2id output, the composite key, the encryption key and the HMAC base are Secret values wiped on drop; the document is built in a zeroizing buffer and encrypted in place; the Argon2id memory is overwritten before release.
Limits
One entry, as large as the largest vault size (4 MiB of plain text) holds with the document around it; a larger one is refused as not fitting and no file is made. The entry comes from an open vault, whose file is no larger. KDBX states no limit of its own.
The file is a vault of the smallest size that holds it.
The export is as safe as its passphrase.
Faraday's own calls
Nostr entries are never exported (F27). Neutral, F27.
The file's seed, IV, salt, inner key and UUIDs are taken from the session's randomness, an answer for every 32 bytes. Neutral, F154.
RFC 4226, HOTP: An HMAC-Based One-Time Password Algorithm, Informational
otpauth Key URI Format, Key URI Format of Google Authenticator, Convention
Code
Library: hmac 0.13.0, by the RustCrypto developers.
Library: sha1 0.11.0, by the RustCrypto developers.
Library: sha2 0.11.0, by the RustCrypto developers.
Library: base16ct 1.0.0, by the RustCrypto developers, through core/faraday-crypto.
Faraday's code: faraday/faraday-vault: Reads an otpauth://totp URI or a bare Base32 key, and from an entry's fields KeePass 2's TimeOtp-* fields and older KeePassXC's TOTP Seed and TOTP Settings (docs/TOTP.md section 4.1); SHA1 by default as RFC 6238 does, SHA256 and SHA512 on request; the clock is the person's, checked or set by hand (docs/TOTP.md §1).
Written by Faraday
TOTP code derivation (faraday-vault::totp) · Only the part used is written
Faraday writes only the few lines RFC 6238 needs, over standard HMAC.
Compared with others' code: pyotp, by the pyotp developers, which judges the code, the seconds left, the period and the reading of an otpauth URI's key, digits, period and hash; Faraday's stricter and wider readings of a URI are stated differences of the area.
Area totp
Faraday's code faraday_vault::totp (parse, Totp::code, left and period)
Compared with Pyotp 2.9 (python3-pyotp): TOTP.at and generate_otp for the code, parse_uri for a URI's key, digits, period and hash.
Checked first: RFC 6238 Appendix B's codes are required of pyotp as well as of Faraday, and each pinned URI's answer from each side is stated in the area.
from_fields (KeePass 2's TimeOtp-* fields and KeePassXC's TOTP Seed and TOTP Settings) and normalise (what the entry form writes into field 6), which no pyotp reader covers: the crate's tests hold them; grouped, the display grouping of a code.
Vectors RFC 6238 Appendix B: the codes of the SHA-1, SHA-256 and SHA-512 seeds at its six times, 8 digits.
Random cases Random keys of 1 to 300 bytes in otpauth://totp/ URIs and, from 10 bytes, as bare keys, digits 6 to 8, periods 1 to 3600 (and past it), the three hashes, times from 0 to 2^64 - 1 with the edges of each period, the code, the seconds left and the period; the URIs written in other spellings and damaged (a character changed, added, removed, a cut, a pair dropped or doubled), read by both; the pinned URIs.
Differences Where Faraday reads and pyotp refuses: a scheme, type or algorithm in other than lower (upper for the algorithm) case; a parameter name pyotp does not know, a counter on a TOTP, a label issuer that the issuer parameter does not repeat; Base32 with spaces or hyphens (a bare key) or = in the wrong place, or a length that Base32 cannot have. The area asks both about the URI with that difference taken out and requires the same answer, and Faraday's answer to the original to be that answer.
Where Faraday refuses and pyotp reads: a period over 3600 seconds (Faraday's rule), a parameter of the key URI format written twice or in a case other than lower or with a percent-escape in its name (pyotp keeps the last, or reads the decoded name), a parameter name with a tab or line break in it (pyotp strips them), a pair with no = or no value, a type with no / before its ?, a value written percent-encoded (Faraday reads it as it is), a fragment after the last value, a bare key of fewer than 16 characters, and encoder=steam, which pyotp reads as a Steam code of five characters and Faraday refuses, making no such code. The area asks both about the URI with a period, repeated parameter, name, pair or type difference taken out and requires the same answer; the percent escapes, the fragment, the short key and Steam's code are pinned one URI at a time.
Where both read and the keys differ: an escaped & or = in a value, such as an issuer's a%26secret%3DB. pyotp unquotes the whole URI first and reads a second secret from it; Faraday reads the value as written, one issuer and the key before it, which is the reading the URI's writer meant. Pinned one URI at a time, where the pin judges the kind and not the key.
HOTP: pyotp reads otpauth://hotp/ as a HOTP; Faraday refuses it, naming it HOTP (NotTotp::Hotp) and reading no code.
Times: pyotp works from a datetime, which ends in year 9999; past it the area asks generate_otp for the counter, time // period.
When it runs Before every release, with a new seed and about ten times the cases.
Last passing runSeed 5be11ec606a76d2767f225b8992c45fe · 33000 cases
The decoded secret is held in a zeroizing buffer; the HMAC output is a plain buffer dropped at the end of the call, and hmac's key block is freed unwiped, until the next lock (ESTABLISHED §4.8, §6.7).
Limits
TOTP only: an otpauth://hotp URI is told apart and not computed.
Digits 6 to 8, period 1 to 3600 seconds; a parameter outside that is unreadable.
A bare Base32 key is read as SHA1, 6 digits, 30 seconds; a short key is refused.
No code is shown while the clock is not checked or set.
Faraday's own calls
A manual clock with a fixed-offset time zone, since a device with no network has no other time (F7). Neutral, F7.
A parameter of the otpauth key URI written twice, in a case other than lower, or with a percent-escape in its name, or a parameter name with a space or control character in it, is refused; pyotp keeps the last of a repeated parameter and reads a decoded name. Conservative.
Makes an OpenPGP v4 key from two fresh Ed25519 seeds, a certifying primary key and a signing subkey, with its public certificate and a kept revocation certificate.
Specification
RFC 4880, OpenPGP Message Format, obsoleted by RFC 9580, Proposed Standard
RFC 9580, OpenPGP, Proposed Standard
RFC 8032, Edwards-Curve Digital Signature Algorithm (EdDSA), Informational
Code
Library: ed25519-dalek 3.0.0, by the dalek-cryptography developers.
Library: sha1 0.11.0, by the RustCrypto developers.
Library: sha2 0.11.0, by the RustCrypto developers.
Library: base64ct 1.8.3, by the RustCrypto developers.
Faraday's code: faraday/faraday-pgp: The armoured secret key a KDBX vault's GPG entry holds is the key's own packets (`Key::secret_key`) in ASCII armour, and it is read back only when writing the key it names gives the same bytes. Version-4 packets for one key shape: EdDSALegacy Ed25519 for the primary (certify) and the subkey (sign), SHA-1 fingerprints, self-signatures over SHA-512, the subkey's back signature, and a revocation certificate kept in the vault record as GnuPG 2.1 and later keep one; every signature is deterministic.
Written by Faraday
OpenPGP v4 packets for one key shape, the armour's CRC-24, and the paperkey format (faraday-pgp) · Only the part used is written
Faraday writes only the packets of its one key shape, over Ed25519 from dalek and SHA-1/SHA-2 from RustCrypto, each judged by GnuPG and paperkey; the armour's base64 is the base64ct crate's.
not cross-checked: Judged by real gnupg and paperkey in faraday/faraday-pgp/tests/gnupg.rs, not by an F79 area; those tests fail where the tools are missing
Signs data with the GPG key's signing subkey: an Ed25519 detached signature over the SHA-512 of the data, armoured.
Specification
RFC 4880, OpenPGP Message Format, obsoleted by RFC 9580, Proposed Standard
RFC 9580, OpenPGP, Proposed Standard
RFC 8032, Edwards-Curve Digital Signature Algorithm (EdDSA), Informational
Code
Library: ed25519-dalek 3.0.0, by the dalek-cryptography developers.
Library: sha2 0.11.0, by the RustCrypto developers.
Library: base64ct 1.8.3, by the RustCrypto developers.
Faraday's code: faraday/faraday-pgp: A version-4 binary signature (type 0x00) by the signing subkey; the digest is signed, not the data, as OpenPGP's EdDSA does; output is `{file}.asc`.
Makes a revocation certificate for the GPG key and writes it as the `.rev` file GnuPG writes.
Specification
RFC 4880, OpenPGP Message Format, obsoleted by RFC 9580, Proposed Standard
RFC 9580, OpenPGP, Proposed Standard
Code
Library: ed25519-dalek 3.0.0, by the dalek-cryptography developers.
Library: sha1 0.11.0, by the RustCrypto developers.
Library: sha2 0.11.0, by the RustCrypto developers.
Library: base64ct 1.8.3, by the RustCrypto developers.
Faraday's code: faraday/faraday-pgp: A key-revocation signature (type 0x20) by the primary key over SHA-512 with GnuPG's reason codes; the file is laid out as `openpgp-revocs.d/<FPR>.rev` with a colon before the first dashes so `gpg --import` refuses it until the colon is removed.
Writes the GPG key's secret parts in paperkey's text form, for a person to copy onto paper.
Specification
paperkey, paperkey's text and raw forms of an OpenPGP secret key, Convention
Code
Library: ed25519-dalek 3.0.0, by the dalek-cryptography developers.
Library: sha1 0.11.0, by the RustCrypto developers.
Library: sha2 0.11.0, by the RustCrypto developers.
Library: base16ct 1.0.0, by the RustCrypto developers.
Faraday's code: faraday/faraday-pgp: The secret MPIs of the primary and the subkey, each behind its 20-byte fingerprint, in lines with a CRC-24, computed only to be shown and wiped after; the unprotected transferable secret key the tests give to paperkey and Faraday does not put in the Outbox.
Checked against
tools/vectors/paperkey
Computed by paperkey 1.6 and GnuPG 2.4.8, run by the folder's make.sh.
The armour's and paperkey's CRC-24 runs without a branch on the data; the code states no other timing.
The paperkey text, the secret key packets and the seeds are Zeroizing values wiped on drop; the paperkey is computed only while it is held to show. Copies other crates make while encoding are freed unwiped, until the next lock (ESTABLISHED §4.8).
Limits
Faraday's key shape only: a key of another algorithm, with no subkey or protected by a passphrase is not written.
Faraday's own calls
The paperkey is computed only while it is held to show, and wiped after. Conservative, F32.
Restores a GPG key from its paperkey lines, typed or scanned as paperkey's text or raw form, and its public certificate: checks every line's CRC, rebuilds the key from the seeds, and makes every signature of the certificate again to compare.
Specification
paperkey, paperkey's text and raw forms of an OpenPGP secret key, Convention
RFC 4880, OpenPGP Message Format, obsoleted by RFC 9580, Proposed Standard
RFC 9580, OpenPGP, Proposed Standard
RFC 8032, Edwards-Curve Digital Signature Algorithm (EdDSA), Informational
Code
Library: ed25519-dalek 3.0.0, by the dalek-cryptography developers.
Library: sha1 0.11.0, by the RustCrypto developers.
Library: sha2 0.11.0, by the RustCrypto developers.
Library: base64ct 1.8.3, by the RustCrypto developers.
Library: base16ct 1.0.0, by the RustCrypto developers.
Faraday's code: faraday/faraday-pgp: The key is rebuilt only if the seeds make the public key and every self-signature of the certificate comes out again byte for byte; a certificate merged or renewed by GnuPG restores from its newest self-signature, and a revoked one restores marked revoked.
Checked against
tools/vectors/paperkey
Computed by paperkey 1.6 and GnuPG 2.4.8, run by the folder's make.sh.
The typed lines, a scanned code's lines and the restored seeds are wiped when the restore is wiped or dropped; a code refused keeps nothing.
Limits
Refuses a paperkey protected by a passphrase, one of another algorithm, one for another key or subkey, and one whose secret does not make the public key.
A certification by another key is set aside and counted, not restored.
The public key is read from Files, a scanned one filed there first; a paperkey's code is taken whole or not at all, every line checked as typed, the raw form by its whole CRC.
Faraday's own calls
A restore that cannot reproduce the certificate's own signatures is refused rather than accepted on the public key alone. Conservative, F155.
Checks a detached OpenPGP signature over data against a certificate: the signing subkey's binding and back signature, the key's life, and the Ed25519 signature over a SHA-256 or SHA-512 digest.
Specification
RFC 4880, OpenPGP Message Format, obsoleted by RFC 9580, Proposed Standard
RFC 9580, OpenPGP, Proposed Standard
RFC 8032, Edwards-Curve Digital Signature Algorithm (EdDSA), Informational
Code
Library: ed25519-dalek 3.0.0, by the dalek-cryptography developers.
Library: sha1 0.11.0, by the RustCrypto developers.
Library: sha2 0.11.0, by the RustCrypto developers.
Library: base64ct 1.8.3, by the RustCrypto developers.
Faraday's code: faraday/faraday-pgp: Takes one armoured block of one version-4 binary signature and refuses everything it does not honour; checks the certificate too, with strict Ed25519 verification of the signature and of the subkey's binding and back signature.
Checked against
tools/vectors/release-sums
Computed by GnuPG 2.4.9, run by the folder's make.sh; faraday-0.1.7/ holds Faraday 0.1.7's published sums.
Not applicable: only public keys and signatures are handled.
Nothing secret is held.
Limits
Refuses text-mode signatures, versions 5 and 6, a hashed signature expiry, a creation time outside the hashed area and a critical subpacket it does not understand.
Refuses a certificate that carries a revocation, and a signature made before the subkey or after either key's expiry.
Armour without its checksum, or with anything after it, is refused.
Faraday's own calls
Anything not honoured is refused rather than read, so the release check of F134 cannot be satisfied by a signature of another shape. Conservative, F134.
Makes an owner's Secure Boot keys, PK, KEK and db as RSA-2048 with self-signed certificates, and the enrolment files: signature lists, PKCS #7 signed updates and certificates.
Specification
Own specification
UEFI Specification, Unified Extensible Firmware Interface Specification: Secure Boot, signature lists and authenticated variables, Status not checked
RFC 5280, Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile, Proposed Standard
RFC 5652, Cryptographic Message Syntax (CMS), Internet Standard
RFC 8017, PKCS #1: RSA Cryptography Specifications Version 2.2, Informational
Code
Library: rsa 0.10.0-rc.18, by the RustCrypto developers.
Library: sha2 0.11.0, by the RustCrypto developers.
Library: chacha20 0.10.2, by the RustCrypto developers.
Library: rand_core 0.10.1, by the Rand Project developers.
Library: x509-cert 0.3.0, by the RustCrypto developers.
Library: der 0.8.2, by the RustCrypto developers.
Faraday's code: faraday/faraday-sb: The RSA key generator draws from the chacha20 crate's `ChaCha20Rng`, seeded with a fresh 32-byte draw (a system answer, with the person's own randomness hashed in when they added some), with a stream for the key, one for the GUID and serials and one that blinds the signing; the certificates are `x509-cert`'s builder signing through `rsa`'s `pkcs1v15::SigningKey`, and the CMS SignedData and Authenticode structures are `der` types; the `rsa` crate is a release candidate and pinned.
Written by Faraday
CMS SignedData, Authenticode's image hash and signature, EFI signature lists and .auth files (faraday-sb) · No established implementation exists
No library writes Authenticode signatures or EFI signature lists; the CMS crate for the DER version Faraday uses is a release candidate.
An outside review recorded in a decision ends it; a reproduction from the specification by an outside party is asked for in docs/AUDIT-SUBMISSIONS.md §10.
not cross-checked: Judged by openssl in faraday/faraday-sb/tests/judged.rs, which fails where openssl is missing; not by an F79 area
Signs a boot program with the db key, as an Authenticode SHA-256 signature, only when it is the file a release's checked sums name.
Specification
Authenticode, Windows Authenticode Portable Executable Signature Format, Status not checked
UEFI Specification, Unified Extensible Firmware Interface Specification: Secure Boot, signature lists and authenticated variables, Status not checked
RFC 5652, Cryptographic Message Syntax (CMS), Internet Standard
RFC 8017, PKCS #1: RSA Cryptography Specifications Version 2.2, Informational
Code
Library: rsa 0.10.0-rc.18, by the RustCrypto developers.
Library: sha2 0.11.0, by the RustCrypto developers.
Library: x509-cert 0.3.0, by the RustCrypto developers.
Library: der 0.8.2, by the RustCrypto developers.
Faraday's code: faraday/faraday-sb: Signs only the image whose SHA-256 the checked release names (F134); the release is checked from its SHA256SUMS and their OpenPGP signature. The signer of any image exists only under a build feature that no shipped binary turns on.
Checked against
tools/vectors/release-sums
Computed by GnuPG 2.4.9, run by the folder's make.sh; faraday-0.1.7/ holds Faraday 0.1.7's published sums.
The db key is the vault record's, held by the open vault and wiped when it closes; the blinding stream is a ChaCha20 keystream of fresh bytes from the system.
Limits
Signs only a release's own boot program, and not an older release's: the release must be at least as new as the running Faraday.
Refuses a file the sums do not list exactly once, sums whose first line does not name the release, and a text-mode signature.
The signature is appended as one certificate table at the image's end.
Faraday's own calls
A boot program is signed only when it is a release's own. Conservative, F134.
Checks an image's Authenticode signature against a db certificate: the image hash, the SHA-256 digest in the signed data and the RSA signature.
Specification
Authenticode, Windows Authenticode Portable Executable Signature Format, Status not checked
RFC 5652, Cryptographic Message Syntax (CMS), Internet Standard
RFC 8017, PKCS #1: RSA Cryptography Specifications Version 2.2, Informational
Code
Library: rsa 0.10.0-rc.18, by the RustCrypto developers.
Library: sha2 0.11.0, by the RustCrypto developers.
Library: x509-cert 0.3.0, by the RustCrypto developers.
Library: der 0.8.2, by the RustCrypto developers.
Faraday's code: faraday/faraday-sb: Says whether the signature is valid, signed by another key, or not readable; it says nothing of whether a computer trusts the key, which its db decides.
not cross-checked: Judged by images signed by sbsign and osslsigncode and by sbverify (faraday/faraday-sb/tests/judged.rs), not by an F79 area; sbverify fails the test where it is missing
Runs eight fixed-vector checks at start-up and from Settings: BIP 39 words and seed in English and Japanese, BIP 32 derivation, a BIP 84 address, an ECDSA and a BIP 340 signature, scrypt and Argon2id.
Specification
BIP 39, Mnemonic code for generating deterministic keys, Deployed
BIP 84, Derivation scheme for P2WPKH based accounts, Deployed
BIP 340, Schnorr Signatures for secp256k1, Deployed
RFC 6979, Deterministic Usage of the Digital Signature Algorithm (DSA) and Elliptic Curve Digital Signature Algorithm (ECDSA), Informational
RFC 7914, The scrypt Password-Based Key Derivation Function, Status not checked
RFC 9106, Argon2 Memory-Hard Function for Password Hashing and Proof-of-Work Applications, Informational
Code
Library: argon2 0.6.0, by the RustCrypto developers, through core/faraday-crypto.
Library: bitcoin 0.32.102, by the rust-bitcoin developers, through core/faraday-bip.
Library: hmac 0.13.0, by the RustCrypto developers, through core/faraday-crypto.
Library: sha2 0.11.0, by the RustCrypto developers, through core/faraday-crypto.
Library: unicode-normalization 0.1.25, by the unicode-rs developers, through core/faraday-bip.
Library: base16ct 1.0.0, by the RustCrypto developers, through core/faraday-crypto.
Faraday's code: core/faraday-selftest: Each check calls the function the product itself calls (the Argon2id check calls `faraday_crypto::argon2id`, which wraps the `faraday_crypto::argon2` the vault calls) and compares with an expected value copied from a vector file; a failure names the check and blocks the app but Exit.
Checked against
tools/vectors/bip39
Published, by Trezor (SatoshiLabs), python-mnemonic's vectors; bip32JP's Japanese vectors.
tools/vectors/psbt
Published, by BIP 174's and RFC 6979's authors; the spends and finalized answers Bitcoin Core v31.1 made on regtest. Faraday's own known answers: the wallet policies, the warning PSBTs and the PSBTs this tree signed.
tools/vectors/kdf
Published, by RFC 7914 §12, for scrypt; the Argon2id answer computed by argon2-cffi and PyCA cryptography, which agree.
not cross-checked: It checks the app's own functions against fixed published answers; the functions it calls are cross-checked in the bip39, bip32, addr, sign, lightning and vault areas
SpecificationFIPS 180-4PublishedCodeLibrary: sha2 0.11Library: lzma-rust2 0.22Library: getrandom 0.3 and 0.4Faraday's code: faraday/faraday-payloadFaraday's own codeCross-checked withNot cross-checked
Action
Writes an image to a stick and checks it: the SHA-256 of the found image file against the release's image list before any write, of the decompressed bytes against the list as they are written, and of what was read back from the stick, with the stick's own IDs and name taken back out, against the list after; keep data takes a stick as the same build only when its boot partition's SHA-256 is the release's boot partition sum (F244).
Specification
FIPS 180-4, Secure Hash Standard, Status not checked
Code
Library: sha2 0.11.0, by the RustCrypto developers.
Library: lzma-rust2 0.22.0, by hasenbanck (lzma-rust2), a port of the Tukaani project's XZ for Java.
Library: getrandom 0.3.4 and 0.4.3, by the Rand Project developers.
Faraday's code: faraday/faraday-payload: The image file is read whole and its SHA-256 compared before anything is written, then read again and decompressed into the writer; success means the writer received exactly the list's size with the list's SHA-256; a developer's image is hashed when confirmed and refused if it changed after; a Pi card is read back and compared with the stream as written, and the SHA-256 of what was read, with the card's own IDs put back where they went (docs/STICK-IDENTITY.md §4.3), must be the list's. A stick is made for its size, not copied (docs/STICK-IDENTITY.md §4.2): only the image's boot partition reaches it, byte for byte with the release's serial; its protective MBR, GPT (new disk and partition GUIDs from getrandom, the data partition to the last usable sector, every CRC-32 worked out again) and its data partition's FAT32 (faraday-fat's formatter, a new serial from getrandom) are written as regions and every region and the boot partition are read back and compared byte for byte; the GUIDs and serials are identities, not secrets. A stick made or keep data from a found image with no boot file signed first checks that the SHA-256 of the image's boot partition is the list's and writes nothing otherwise. Clearing the whole stick first writes zeros over every sector and reads none back. A name given the data partition (docs/STICK-IDENTITY.md §6) is faraday-fat's label write run over the sectors captured, each byte it changed a patch put back the same way.
Written by Faraday
The FAT32 formatter for the Starter's data partition (faraday-fat::format) · No established implementation exists
No FAT library comes from a publisher Faraday's dependency review trusts; the partition it makes is checked by dosfstools' fsck.fat, against what mkfs.fat makes.
no fuzz target: The image_list target fuzzes the image list's reading; no target runs the xz decoder or the hash
Cross-check
not cross-checked: The sums are compared with `sha256sum`'s in the tests, and the tests judge the decoder with `xz` and 7-Zip (`7zz` or `7z`) over good and damaged streams, the tables written with `sfdisk --verify` and `sgdisk -v`, the `diskutil` answers with Python's `plistlib` and the GUIDs with Python's `uuid` and the CRC-32 fields of the GPT headers and partition arrays with `zlib.crc32`; each is skipped without its tool in `just` and fails in `just crosscheck`. No F79 area runs the decoder
Checks a boot file the person signed against the release's own: its Authenticode image hash, its one signature at the file's end, and the signature on the file built.
Specification
Authenticode, Windows Authenticode Portable Executable Signature Format, Status not checked
RFC 8017, PKCS #1: RSA Cryptography Specifications Version 2.2, Informational
Code
Library: rsa 0.10.0-rc.18, by the RustCrypto developers.
Library: sha2 0.11.0, by the RustCrypto developers.
Faraday's code: faraday/faraday-sb: Only the signature is taken from the person's file: the file written is the release's own bytes with that file's checksum, certificate-table entry and certificate table, so every byte the signature does not cover is the release's; which key signed it is not judged, a computer's db decides that.
not cross-checked: Judged by images signed by sbsign and osslsigncode and by sbverify (faraday/faraday-sb/tests/judged.rs), not by an F79 area; sbverify fails the test where it is missing
SpecificationOwn specificationCodeFaraday's code: faraday/faraday-starterFaraday's own codeCross-checked withNot cross-checked
Action
Reads a BitLocker recovery key, eight groups of six digits, for the system drive, holds it until the notes sheet is made and wipes it.
Specification
Own specification (F49)
Code
Faraday's code: faraday/faraday-starter: A key is taken only as eight groups of six digits joined by hyphens, for a drive that is a letter and a colon; it is held in a zeroizing string, printed on the sheet after the other rows with its drive, four groups to a line, and the rows' copies of its text are zeroized once the PDF is made; Debug prints none of it.
Written by Faraday
The PDF writer (faraday-core::pdf, faraday-starter::sheets) · No established implementation exists
No PDF library comes from a publisher Faraday's dependency review trusts.
Not applicable: the key is read and printed, not used in a computation.
The key is a zeroizing string wiped when dropped, once the sheet is made; the rows' copies of its text are zeroized after the PDF is written, and the PDF is the caller's to wipe.
Limits
A key that is not eight groups of six digits, or a drive that is not a letter and a colon, is not taken.
The key is on the sheet only when the person ticked Include the BitLocker recovery key.
The sheet carries nothing else of BitLocker and no QR code of the key.
Faraday's own calls
The sheet carries the key only when it is ticked, and holds it only until the sheet is made. Conservative, F49.
Builds a timelocked recovery wallet from its parts and reads the parts back out of one.
Specification
BIP 379, Miniscript, Draft
BIP 382, Output Script Descriptors: wsh, Deployed
BIP 386, Output Script Descriptors: tr, Deployed
Code
Library: miniscript 12.3.7, by the rust-bitcoin developers (rust-miniscript).
Library: bitcoin 0.32.102, by the rust-bitcoin developers.
Library: base16ct 1.0.0, by the RustCrypto developers, through core/faraday-crypto.
Faraday's code: core/faraday-bip: A primary spending path and recovery paths behind relative delays, as Liana writes them; a taproot form puts one primary key on the key path; a wallet no one could recover is refused. The miniscript area builds wallets of these shapes with RecoveryPolicy in both forms and reads them back, and compares their scripts, kinds and ways to spend with Bitcoin Core and btclib.
Checked against
tools/vectors/miniscript
Published, by Bitcoin Core's miniscript_tests.cpp, v31.1, by the Bitcoin Core developers.
Compared with others' code: Bitcoin Core v31.1 itself (deriveaddresses) and its functional-test framework, by Bitcoin Core's contributors; python-bip380, by Antoine Poinsot, for Core's vectors that state no script; btclib-wallet's bip32, by the btclib developers, for the cosigners' keys, and its descriptors and miniscript, by the btclib developers, on btclib's own curve, for each descriptor's kind, text and script at an index, Core's vectors' types, sanity and scripts, and the satisfaction of each way a wallet's coins move under its lock times (and, for recovery wallets, each built from its parts).
Area miniscript
Faraday's code faraday_bip::policy::WalletPolicy (a wallet's descriptor and the script it pays at an index, its kind, text and spend paths), faraday_bip::policy::parse_script_descriptor, a witness script read back as faraday_psbt reads one, faraday_bip::recovery::RecoveryPolicy (a recovery wallet built from its parts and read back)
Compared with Bitcoin Core v31.1's bitcoind on regtest (deriveaddresses) for random wallets, their cosigners' keys from btclib (btclib/, on btclib's own curve); btclib-wallet's descriptors and miniscript (btclib/) for each descriptor's kind, text and script, Core's vectors' types and scripts, and the satisfaction of each way a wallet's coins move under its lock times; Antoine Poinsot's python-bip380 (miniscript/) for Core's vectors that state no script.
Checked first: Its vendored files are hashed against references.sha256 before any run, and a published vector's answer is required of the reference as well as of Faraday; btclib reads Core's 97 miniscripts, in both contexts, before any random wallet (valid exactly when Core says, its properties, sane, script); Core's release tarball is checked against its pinned SHA-256 (tools/reference/core/release.pin) before every run, and the node's version is asked.
The witness bytes of a satisfaction (btclib assembles one and area sign compares Faraday's finalizer); a wallet with more than 64 ways to spend, for which Faraday states none; hash locks and locks in seconds, which the corpus does not generate; and a wallet btclib cannot read (none yet).
Vectors Bitcoin Core's miniscript unit tests, 97 miniscripts in P2WSH and Tapscript (tools/vectors/miniscript/).
Random cases Wallets of the Liana, Nunchuk, Sparrow and recovery shapes in wsh() and sh(wsh()), multi/sortedmulti in sh(), wsh(), sh(wsh()), tr() with trees of one to six leaves or a lone sortedmulti_a, over random accounts on every network, at random indices of both chains; the same made not sane, refused; recovery wallets of both forms with one to three recovery paths, and the ways each wallet's coins move spent at their lock times.
Differences Miniscript: Faraday reads sortedmulti_a only as a tr()'s one leaf; BIP 387 allows it deeper in a tree, and Core reads it there. Two of Bitcoin Core's sane miniscripts are refused, as miniscript refuses them: or_b(0,a:0), which has no satisfaction, and a d: used as a unit under Tapscript. Each is checked and counted; btclib is not asked the deeper sortedmulti_a. btclib says nothing of "needs a signature" for a malleable miniscript (BIP 379 does not), so that property is compared where Core calls the miniscript non-malleable.
When it runs Before every release, with a new seed and about ten times the cases.
Last passing runSeed 5be11ec606a76d2767f225b8992c45fe · 2500 cases
SpecificationRFC 5869 · RFC 2104 · FIPS 180-4PublishedCodeLibrary: hmac 0.13Faraday's code: core/faraday-cryptoCross-checked withPyCA cryptography's HKDF and HKDFExpand (OpenSSL)Others' code
Action
Derives keys with HKDF over SHA-256, extracting under a salt and expanding, or expanding alone.
Specification
RFC 5869, HMAC-based Extract-and-Expand Key Derivation Function (HKDF), Informational
RFC 2104, HMAC: Keyed-Hashing for Message Authentication, Status not checked
FIPS 180-4, Secure Hash Standard, Status not checked
Code
Library: hmac 0.13.0, by the RustCrypto developers.
Faraday's code: core/faraday-crypto: HKDF (RFC 5869) is written here over `hmac`: `hkdf_sha256` extracts under the salt into a pseudorandom key held in a wiped `Secret` and expands, for the QR vault's message, and `hkdf_sha256_expand` (§2.3) expands alone, for the blinding of the session's keys and Schnorr signing's per-input auxiliary randomness. Both are checked against RFC 5869's test cases 1 to 3 and, in area `hash`, against PyCA's `HKDF` and `HKDFExpand`.
no fuzz target: Takes bytes from callers that parse their own input
Cross-check
Compared with others' code: PyCA cryptography's HKDF and HKDFExpand (OpenSSL).
Area hash
Faraday's code faraday_bip::hashes and faraday_codec::encodings (read, the writers and from_hex), faraday_core::file_menu::sha256, and faraday_crypto::hkdf_sha256 and hkdf_sha256_expand, hmac_sha256, hmac_sha512, pbkdf2_hmac_sha256, pbkdf2_hmac_sha512 and scrypt
Compared with Bitcoin Core v31.1's functional-test framework (core/): ripemd160.py, address.py and segwit_addr.py, with hashlib for SHA-256 and bytes.fromhex for hex; PyCA cryptography's HKDF and HKDFExpand (OpenSSL) for the one HKDF; hmac, hashlib.pbkdf2_hmac and hashlib.scrypt (OpenSSL) for HMAC, PBKDF2 and scrypt.
Checked first: Its vendored files are hashed against references.sha256 before any run, and a published vector's answer is required of the reference as well as of Faraday; the order read tries the spellings in, the trimming of the text, hex as an even number of hex digits, plain Base58 (which Core's framework does not read; the area's own few lines) and which prefixes make a segwit address are Faraday's rules, written in the area in front of the reference.
The file hash is file_menu::sha256 over a whole byte slice (it reads in no buffer, so no read size is probed); the Files screen's reading of a file from a stick is the files areas'.
Vectors FIPS 180-4's SHA-256 examples, RIPEMD-160 of abc, BIP-173's key and its HASH160, Bitcoin Core's first key_io_valid.json address, BIP-173's and BIP-350's bech32 strings and their valid and invalid segwit addresses (tools/vectors/addresses).
Random cases Random bytes of every length from 0 to 130 and to 300 hashed (SHA-256, SHA-256d, HASH160) and as a file, files of 4 KiB, 64 KiB and 1 MiB with a byte more and less; random bytes written and read as Base58Check, Base58, bech32 and bech32m, Core's writing read by Faraday, segwit addresses of every version Core's framework writes, and texts changed, cut or made of random characters read by both.
Differences bech32 groups: a string that is not a segwit address of bc, tb or bcrt is read as bytes, all its data groups together, and the bits that do not fill a byte are dropped. BIP-173 has a padding rule only for a segwit address, so Core's convertbits, which applies it to any data, refuses some of these strings, and the area reads them as Faraday does.
bech32 length: Core's decoder refuses more than 90 characters (BIP-173); Faraday accepts any length the checksum covers. The area reads longer strings the same way.
When it runs Before every release, with a new seed and about ten times the cases.
Last passing runSeed 5be11ec606a76d2767f225b8992c45fe · 30000 cases
SpecificationRFC 7914PublishedCodeFaraday's code: core/faraday-cryptoFaraday's own codeCross-checked withPython's hashlib.scrypt (OpenSSL) in area hashOthers' code
Action
Stretches a password with scrypt, written in this crate, for LND's aezeed.
Specification
RFC 7914, The scrypt Password-Based Key Derivation Function, Status not checked
Code
Faraday's code: core/faraday-crypto: Written here, with one caller (the aezeed reader), because it is small enough that a crate would cost more than it saves.
Written by Faraday
scrypt (faraday-crypto::scrypt) · One exists but does not fit Faraday's rules for keys
The Rust scrypt library leaves its passphrase-derived working memory unwiped; Faraday's wipes it.
Does not fit: scrypt 0.12.0 frees its passphrase-derived working buffers (b, v, t) without wiping them
no fuzz target: Takes cost parameters fixed by the one caller; aezeed fuzzes the words
Cross-check
Compared with others' code: Python's hashlib.scrypt (OpenSSL) in area hash, and LND's aezeed package, by Lightning Labs, over golang.org/x/crypto's scrypt, vendored in tools/reference/lnd/, in area lightning.
Area hash
Faraday's code faraday_bip::hashes and faraday_codec::encodings (read, the writers and from_hex), faraday_core::file_menu::sha256, and faraday_crypto::hkdf_sha256 and hkdf_sha256_expand, hmac_sha256, hmac_sha512, pbkdf2_hmac_sha256, pbkdf2_hmac_sha512 and scrypt
Compared with Bitcoin Core v31.1's functional-test framework (core/): ripemd160.py, address.py and segwit_addr.py, with hashlib for SHA-256 and bytes.fromhex for hex; PyCA cryptography's HKDF and HKDFExpand (OpenSSL) for the one HKDF; hmac, hashlib.pbkdf2_hmac and hashlib.scrypt (OpenSSL) for HMAC, PBKDF2 and scrypt.
Checked first: Its vendored files are hashed against references.sha256 before any run, and a published vector's answer is required of the reference as well as of Faraday; the order read tries the spellings in, the trimming of the text, hex as an even number of hex digits, plain Base58 (which Core's framework does not read; the area's own few lines) and which prefixes make a segwit address are Faraday's rules, written in the area in front of the reference.
The file hash is file_menu::sha256 over a whole byte slice (it reads in no buffer, so no read size is probed); the Files screen's reading of a file from a stick is the files areas'.
Vectors FIPS 180-4's SHA-256 examples, RIPEMD-160 of abc, BIP-173's key and its HASH160, Bitcoin Core's first key_io_valid.json address, BIP-173's and BIP-350's bech32 strings and their valid and invalid segwit addresses (tools/vectors/addresses).
Random cases Random bytes of every length from 0 to 130 and to 300 hashed (SHA-256, SHA-256d, HASH160) and as a file, files of 4 KiB, 64 KiB and 1 MiB with a byte more and less; random bytes written and read as Base58Check, Base58, bech32 and bech32m, Core's writing read by Faraday, segwit addresses of every version Core's framework writes, and texts changed, cut or made of random characters read by both.
Differences bech32 groups: a string that is not a segwit address of bc, tb or bcrt is read as bytes, all its data groups together, and the bits that do not fill a byte are dropped. BIP-173 has a padding rule only for a segwit address, so Core's convertbits, which applies it to any data, refuses some of these strings, and the area reads them as Faraday does.
bech32 length: Core's decoder refuses more than 90 characters (BIP-173); Faraday accepts any length the checksum covers. The area reads longer strings the same way.
When it runs Before every release, with a new seed and about ten times the cases.
Last passing runSeed 5be11ec606a76d2767f225b8992c45fe · 30000 cases
SpecificationBitcoin Core wallet.datPublishedCodeLibrary: aes 0.9Library: cbc 0.2Library: sha2 0.11 (through core/faraday-crypto)Faraday's code: faraday/faraday-keysFaraday's own codeCross-checked withBitcoin Core (the pinned release's bitcoind on regtest)Others' code
Action
Checks each private key of a Bitcoin Core descriptor wallet against the public key its record names, and in an encrypted wallet opens the master key from the passphrase and each key with it; says pass or fail for each and gives nothing back.
Specification
Bitcoin Core wallet.dat, Bitcoin Core's descriptor wallet records and their encrypted keys, Convention
Code
Library: aes 0.9.3, by the RustCrypto developers.
Library: cbc 0.2.1, by the RustCrypto developers.
Library: sha2 0.11.0, by the RustCrypto developers, through core/faraday-crypto.
Faraday's code: faraday/faraday-keys: The master key is SHA-512 of the passphrase and the record's 8-byte salt, hashed again for the rounds less one (at most 10,000,000); its first 32 bytes are the AES-256 key and the next 16 the IV that open the 48-byte mkey under CBC with PKCS#7 padding. Each walletdescriptorckey is opened under AES-256-CBC with the double SHA-256 of its public key as the IV. A key must give the public key its record names (33 bytes, or 65 for an uncompressed key with its 279-byte DER), and in the clear match the stored hash of the public key and the DER. One mkey record is tried; a wallet with more is not whole. Where the keys are checked, each account key Core cached for a descriptor's key at a hardened step (a walletdescriptorlhcache record of 74 bytes) is derived again from the checked master key along the hardened path, one derivation for each account key, and must equal the cached bytes in constant time; a cached key whose depth, child number or parent fingerprint disagrees with its path, or is not a point on the curve, fails its record, and so does a cached key no master key was compared with, whatever the wallet's flags say.
Written by Faraday
Bitcoin Core's key from a passphrase and the opening of its encrypted keys (faraday-keys::core_wallet) · No established implementation exists
No maintained Rust crate offers Bitcoin Core's BytesToKeySHA512AES and DecryptSecret; Faraday's is SHA-512 rounds over faraday-crypto and RustCrypto's aes and cbc, tested against wallets Bitcoin Core made.
Computed by Bitcoin Core (the pinned bitcoind on regtest), run by tools/vectors/core-wallet/gen.py: plain, encrypted (passphrase faraday), watch-only, blank, labelled, imported descriptor and imported uncompressed key wallets, a multisig and a miniscript wallet of keys with further hardened steps, and a wallet Core's migratewallet made of a legacy wallet (its combo() descriptors, which Faraday lists and does not take), with Core's listdescriptors and getwalletinfo.
no fuzz target: The records are fuzzed through core_wallet_records, which reaches these functions
Cross-check
Compared with others' code: Bitcoin Core (the pinned release's bitcoind on regtest), which makes each wallet and says what it holds (listdescriptors, getwalletinfo, walletpassphrase) and loads or refuses each changed file (loadwallet).
Area core_wallet
Faraday's code faraday_core_wallet::read_file (a wallet.dat read whole through faraday_sqlite, the records read and checked, the private keys checked in faraday-keys)
Compared with Bitcoin Core v31.1's bitcoind on regtest, offline: it makes each wallet (createwallet, encryptwallet, importdescriptors, getnewaddress with labels, generatetoaddress), says what it holds (listdescriptors and listdescriptors true, getwalletinfo), opens the passphrase (walletpassphrase) and loads or refuses a changed file (loadwallet).
Checked first: Core's release tarball is checked against its pinned SHA-256 (tools/reference/core/release.pin) before every run and the node's version is asked; every wallet.dat is one Core wrote and every answer is one Core gave of the same wallet.
Labels and the block locator (counted by Faraday; Core's address book is asked only for a purpose record Faraday refuses), the records Faraday counts and does not read, and the transactions themselves.
Vectors The three wallet.dat files Core made (tools/vectors/core-wallet/), plain, encrypted and migrated from a legacy wallet by migratewallet (made with the older release of tools/reference/core/legacy.pin), with what Core said of them.
Random cases Fresh wallets of eight shapes (plain, encrypted, watch-only, blank, with labels, with an imported descriptor, with an imported uncompressed key, with imported multisig and miniscript descriptors of keys with an origin and further hardened steps, a bare master key with hardened steps, and a hash before a key), with and without a transaction, each read with the right passphrase, a wrong one and none; and the same files with a byte flipped in a record, a record dropped or pages cut off.
Differences Faraday gives each descriptor as Core lists it (the account key from the walletdescriptorlhcache records, the master key's fingerprint and the hardened path as the origin, checksum included), and the area compares that whole text, with Core's listdescriptors without private keys, for every shape.
Faraday checks what Core does not look at when it loads a wallet: a private key's stored hash and public key, a descriptor's id and checksum, and flags and records Core's loader ignores. A changed file Core loads and Faraday does not call whole is counted, and must name a record and fault of the listed set; nothing is asked of Core there beyond that it loads, except where Core's own reading must show the condition: a purpose record Faraday cannot read (Core lists the address's purpose as unknown), a block locator that does not read as one (Core shows it read no locator from the record), a descriptor's range or next index out of order (Core lists it so, loaded with -keypool=1), and a header text encoding other than the three the file format names (SQLite reads it as UTF-8).
Core reads each transaction record as it loads and refuses a wallet one of which does not read; Faraday counts them. Core derives every index of a descriptor's range, and tops it up to its next index, as it loads; it refuses a descriptor that is not ranged whose stored range spans more than one index (the same script twice), and Faraday refuses it too; Faraday also refuses a range of 1,000,000 indexes or more and a next index of 1,000,000 or more (Core's limit on the size of a range). Past 2^16 the area does not wait for Core's answer (past 2^19 it takes minutes), and Faraday, which derives nothing as it reads, reads such a file whole up to that limit; it is counted where Core did not answer. Each is asked of Core in the prelude.
Core runs SQLite's integrity check when it loads a wallet and refuses a file in which a record's key was changed (the unique index beside the table still holds the old key), and refuses one whose walletdescriptorcache record was dropped; Faraday reads the table only, so it reads such a file whole when the changed key is still a record it accepts. Core also refuses a wallet whose block locator ends in another chain's genesis block, as it attaches the wallet to its node's chain; Faraday reads no chain and does not read the locator's hashes. Each is asked of Core in the prelude.
Faraday refuses a wallet of another network than its mode and a file with a journal, log or lock beside it, which Core opens (and recovers); the area reads regtest wallets with nothing beside them, so neither arises.
When it runs Before every release, with a new seed and about ten times the cases.
Last passing runSeed 5be11ec606a76d2767f225b8992c45fe · 380 cases
Adds this signer's ECDH shares and BIP 374 proofs to a silent payments PSBT, and sets the output scripts the shares give.
Specification
BIP 374, Discrete Log Equality Proofs, Draft
BIP 375, Sending Silent Payments with PSBTs, Draft
BIP 352, Silent Payments, Complete, vendored
Code
Library: secp256k1 0.29.1, by the rust-bitcoin developers (rust-secp256k1), over libsecp256k1, by Bitcoin Core's libsecp256k1 project (bitcoin-core/secp256k1).
Library: bitcoin 0.32.102, by the rust-bitcoin developers.
Library: sha2 0.11.0, by the RustCrypto developers, through core/faraday-crypto.
Faraday's code: core/faraday-psbt: BIP 374's proofs are written here (faraday-bip); each share a·B_scan carries a proof that it came from the input's key, every private multiplication going through secp256k1's ecdh; the scripts are set once every eligible input has a share, and signable gives the version 0 PSBT that sign signs.
Written by Faraday
BIP-374 DLEQ proofs and BIP-375's sending fields (faraday-bip::dleq, faraday-psbt::silent) · No established implementation exists
No Rust library implements BIP-374 proofs or BIP-375's PSBT fields.
no fuzz target: Not reachable from the app: no outside input reaches it
Cross-check
Compared with others' code: BIP-374/375 authors (bitcoin/bips), and btclib's dleq.py (BIP-374) and btclib-wallet's BIP-375 roles (Signer, Extractor), by the btclib developers, on btclib's own curve: proofs, shares, output scripts and the verdict on a PSBT; btclib-wallet counts a taproot input's NUMS claim only against a proof, so a PSBT with an unproved claim is judged by the validator alone.
Compared with BIP-374's reference.py (bip374/) and BIP-375's validator and test_runner.py (bip375/), over secp256k1lab; btclib's dleq.py and btclib-wallet's BIP-375 roles (btclib/, its own curve) answering beside them.
Checked first: Its vendored files are hashed against references.sha256 before any run, the validator is required to give each of BIP-375's 43 vectors its published verdict and the reference to give each of BIP-374's rows its published answer.
Vectors Both CSV files of tools/vectors/bip374/ and tools/vectors/bip375/bip375_test_vectors.json, each judged by btclib too.
Random cases Proofs made and verified, damaged or not, under two generators; version 2 PSBTs of one to four inputs of every kind BIP-375 reads and some it does not, one to three silent payment outputs, shares added by one signer or two, a global share, and each finished PSBT damaged in one of eighteen ways, judged by the BIP's validator.
Differences BIP-375: Faraday takes a key a PSBT states for a P2PKH, P2SH-P2WPKH or P2WPKH input only where the input's script commits to it (F89); the validator takes the first key stated, so a PSBT it accepts with an unbound key is refused by Faraday.
BIP-375: Faraday accepts the scripts of a scan key's outputs numbered in sorted order of their spend keys, as the BIP's text says, and in output order, as its vectors do; the validator accepts output order only.
BIP-375: Faraday refuses an input whose redeem script is not the one its P2SH script hashes, and one whose previous transaction is not the one spent; the validator reads both fields without checking them.
BIP-375: btclib-wallet takes a taproot input's NUMS internal key as a reason to skip the input only against a proof (a merkle root or a control block that tweaks the NUMS point to the output key), and counts the input otherwise; Faraday and the validator skip on the claim. A PSBT with an unproved claim is not asked of btclib-wallet; the run prints how many PSBTs it judged and how many it was not asked. A proved claim only in a control block, with no internal key set, is not detected: btclib-wallet would skip the input, Faraday would count it, and the run would stop on it. The corpus also makes inputs whose claim is proved, which all three skip.
When it runs Before every release, with a new seed and about ten times the cases.
Last passing runSeed 5be11ec606a76d2767f225b8992c45fe · 800 cases
The output tweak is treated as public and multiplied by ecmult, as libsecp256k1's own silent payments module does.
The secret's bytes and the hashes they pass through are zeroized before return; each private key used is erased before its input is done. The nonce is a SecretScalar, erased when it is dropped, but musig.rs's `match (self.0, other.0)`, `self.0.map` and `self.0.and_then` leave copies of it. SecretKey is Copy, so every add_tweak, mul_tweak and negate copies the key and only the last copy is erased; the earlier copies are left in memory, later work under the security scope (ESTABLISHED §4.1).
Limits
Built in core and not reachable from the app: the device does not send.
An eligible input whose public key the PSBT does not state, a P2SH input with no redeem script and a previous transaction that is not the one spent stop the check.
A SegWit version above 1 and a sighash other than ALL are refused.
Faraday's own calls
A key a PSBT states for an input counts only where the input's script commits to it, which is stricter than BIP 375's reference validator. Conservative, F89.
Spends of SegWit above v1 and sighashes other than ALL are refused. Conservative.
Reads the TOML a vault holds into its items: the keys of a QR vault (a seed's words, a codex32 share, a passphrase, a note, or nothing), and the three TOML values a file vault keeps in its custom data (a backup plan, a seed's codex32 facts, its BIP-85 facts). What the Spec does not name is refused: a syntax refusal names the line and every other the key; a value read is written again to the same fields. A file vault's KDBX document is mapped to the records the app reads and back (`kdbx::items`): each Faraday item by its `faraday.kind` in its published text form (BIP-39 words of a list or a seed in hex, a BIP-388 policy or a descriptor, PEM keys and certificates, an armored GPG key, a codex32 string), a person's entry by its six fields, and the database's format, seal count, plans and signed amounts; an item that does not read is named Unreadable, never made a record, and written back as read.
Specification
TOML v1.0.0, TOML, Tom's Obvious Minimal Language, version 1.0.0, Status not checked
Code
Library: toml_parser 1.1.3+spec-1.1.0, by the toml-rs developers.
Library: pem-rfc7468 1.0.0, by the RustCrypto developers.
Library: base16ct 1.0.0, by the RustCrypto developers, through core/faraday-crypto.
Faraday's code: faraday/faraday-vault: The parser alone reads TOML v1.0.0 tokens; the tree, the duplicate rules, the key and size limits of docs/VAULT.md sections 2.1 and 7 and the values' meaning are Faraday's own (`contents.rs`, `contents/tree.rs`). Whatever is outside those rules is refused by name. The KDBX mapping (`kdbx/items/`) is Faraday's own over the document model, faraday-bip's BIP-39, wallet policy, descriptor and codex32 readers, the TOTP reader and pem-rfc7468: the field names, the kinds, the labels of related secrets (several shares of one threshold, identifier, index and key) and the Unreadable items of docs/VAULT.md section 7.
Written by Faraday
The TOML tree inside a vault: duplicates, limits and the names of docs/VAULT.md (faraday-vault::contents) · Only the part used is written
toml_parser reads the tokens; Faraday builds the tree and refuses what VAULT.md does not name, as the JSON visitor does over serde_json.
Published, by toml-test (toml-lang/toml-test), the TOML v1.0.0 cases for tables, inline tables, arrays, keys and strings, which the vault's TOML reader is held to.
not cross-checked: The TOML syntax is checked against toml-test's published cases for TOML v1.0.0, made by the TOML authors' test suite; the vault's own rules (its keys, limits and values) are Faraday's and are not checked against an outside source. The action is not cross-checked as one, since the KDBX vault's items have no such judge; area qrvault compares the QR form's writer byte for byte and its reader by item, tomllib reading the canonical form the area writes
The reader branches on secret text (a seed's words, a passphrase, a note) while it parses, and so does the KDBX mapping over an item's fields; constant-time parsing is later work (docs/SECURITY-MODEL.md, the security scope).
The text read and the values made from it are held in wiping types (docs/KEYS.md); what toml_parser and the word-list parser keep is not wiped (docs/deps/toml_parser.md). The KDBX mapping's words, seed hex and PEM keys are made in wiping buffers (`kdbx/items/forms.rs`); a GPG key's armored text is held in a wiping string.
Limits
A QR vault is exactly 226 bytes; a plan over 1 MiB, an inline table over its size, a key part of more than 128 bytes, a key path of more than 8 parts and a key outside docs/VAULT.md sections 2.1 and 7 are refused.
A QR vault holds one item, a note of at most QR_NOTE_MAX bytes and a passphrase of at most QR_PASSPHRASE_MAX; more is refused as too long, naming the key.
Faraday's own calls
Nothing about Faraday's items refuses a KDBX file: an item that does not read is named Unreadable, by its title, UUID, field and fault, is never made a record and is written back as read; a faraday.format other than 1 makes the vault read-only (owner, 2026-11-03; docs/VAULT.md section 7). Conservative, F194.
Whatever the Spec's TOML does not name is refused, so a value that adds a key is not read (F190 point 3, docs/VAULT.md section 7). Conservative, F194.
A QR vault's contents are the item's keys at the top of a TOML document, padded to 226 bytes with line feeds (F190 point 5, docs/VAULT.md section 2.1). Neutral, F194.
SpecificationRFC 9580 · RFC 7253 · RFC 9106 · 1 morePublishedCodeLibrary: aes 0.9Library: ocb3 0.2Library: argon2 0.6 (through core/faraday-crypto)Faraday's code: faraday/faraday-pgpFaraday's own codeCross-checked withSequoia's sqOthers' codeFaraday's second version
Action
Writes and reads an RFC 9580 message under a passphrase: Argon2id (the Argon2 S2K, 3 passes, 4 lanes) over the passphrase gives a key, HKDF-SHA-256 makes the key that AES-256-OCB wraps the session key with in a version 6 symmetric-key encrypted session key packet, and a version 2 data packet holds one literal data packet in AES-256-OCB chunks under a key HKDF-SHA-256 makes from the session key and a 32-byte salt, with a final tag over the plaintext's length.
Specification
RFC 9580, OpenPGP, Proposed Standard
RFC 7253, The OCB Authenticated-Encryption Algorithm, Informational
RFC 9106, Argon2 Memory-Hard Function for Password Hashing and Proof-of-Work Applications, Informational
RFC 5869, HMAC-based Extract-and-Expand Key Derivation Function (HKDF), Informational
Code
Library: aes 0.9.3, by the RustCrypto developers.
Library: ocb3 0.2.0, by the RustCrypto developers.
Library: argon2 0.6.0, by the RustCrypto developers, through core/faraday-crypto.
Faraday's code: faraday/faraday-pgp: Only the part used is written: the version 6 symmetric-key packet with the Argon2 S2K and the version 2 data packet, both AES-256 and OCB, and the one literal data packet, in any length form RFC 9580 allows. The Argon2 cost is checked against the limits right after the key packet, before the data packet is read or any Argon2 memory is taken, padding packets are ignored, every tag is checked before plaintext is returned, and every other packet, version, algorithm or trailing byte is named and not opened. HKDF-SHA-256 is Faraday's own (`faraday-crypto`); Argon2id, AES and OCB are the RustCrypto crates.
Written by Faraday
HKDF-SHA256, one copy (faraday-crypto::hash) · One exists but does not fit Faraday's rules for keys
The Rust HKDF library leaves the pseudorandom key and its output blocks unwiped; Faraday's holds both in buffers it wipes.
Does not fit: hkdf 0.13.0 returns the pseudorandom key and leaves each output block T(i) in plain arrays it does not wipe
The QR vault's OpenPGP message: the version 6 symmetric-key packet with the Argon2 S2K, the version 2 data packet and the literal data packet (faraday-pgp::message) · Only the part used is written
Faraday writes only the three packets a QR vault uses, over argon2, aes and ocb3 and Faraday's HKDF; rPGP, which no review Faraday trusts covers, brings every OpenPGP algorithm.
Published, by RFC 9580 Appendix A (A.10, the version 6 symmetric-key session key and the version 2 data packet with AES-128 and OCB; A.12.3, the Argon2 S2K with AES-256), made by the RFC's authors.
Compared with others' code: Sequoia's sq, by the Sequoia PGP developers (judges the primitives except Argon2, which it shares with the app's lineage, and opens Faraday's messages), rPGP, by the rPGP developers (judges the format only, on the app's lineage: opens Faraday's messages and seals the ones Faraday opens), and PyCA cryptography over OpenSSL (judges Argon2id, HKDF-SHA-256 and AES-256-OCB).
Compared, for one part, with Faraday's second version, written by Faraday's authors in Python; that part is not checked against an outside source: the OpenPGP framing around PyCA's primitives, read and written strictly in area_qrvault.py from RFC 9580 and docs/VAULT.md §1.2, and the QR TOML (qr_toml) from §2.1, read beside by CPython's tomllib; Faraday's second version of the framing, not another program's.
Area qrvault
Faraday's code faraday_vault::qr (the QR vault sealed and opened, with faraday_pgp::message)
Compared with Sequoia's sq, the distribution's package, over Nettle (judges the primitives except Argon2, which it shares with the app's lineage); rPGP (tools/crosscheck/rpgp/, a program outside the workspace, on RustCrypto like the app: judges the format only); PyCA cryptography's Argon2id, HKDF-SHA-256 and AES-256-OCB (OpenSSL's), which judge the primitives, under the OpenPGP framing written in the area from RFC 9580 and docs/VAULT.md §1.2 (Faraday's second version, not another program's); the QR TOML qr_toml written in the area from §2.1, each opened item also read by CPython's tomllib.
Checked first: Sq is the distribution's package, built over Nettle (the run stops otherwise, judges.py), its version written into the stamp; rPGP is built from the crates.io release tools/crosscheck/rpgp/Cargo.lock names; PyCA must be 44 or later over OpenSSL 3.2 or later or the area stops, and its Argon2id, HKDF-SHA-256 and AES-OCB are checked against the repository's Argon2id known answer, RFC 5869 test case 1 and RFC 7253's first vector first; sq and rPGP open the repository's vault vectors, and so does the PyCA judge, which reads strictly and refuses anything but a QR vault.
OpenPGP.js, which docs/VAULT.md §10 names, is not run; sq does not seal a QR vault (below); rPGP judges the format only. §1.2's wider reading, which only Faraday's reader is held to, is not compared with a judge: any literal date, padding packets after the SEIPD packet and the literal data, and every length form RFC 9580 allows; of the chunk size octets only 0 (rPGP seals several chunks, Faraday opens them) and 10 are run.
Vectors The seven vaults of tools/vectors/vault/qr/ opened by sq, rPGP and the PyCA judge to the item each holds and by Faraday; the four refused messages refused by Faraday and by the PyCA judge; the PyCA judge refuses a vector with a byte changed in each field.
Random cases An item of every kind of §2.1 (12 and 24 words, a codex32 share, a passphrase, a note with markup, control characters and several scripts, the empty vault) sealed by Faraday and opened by sq, rPGP, the PyCA judge and Faraday, and sealed by rPGP and by the PyCA judge (memory 2^13 to 2^16 KiB) and opened by Faraday, each opened item read by tomllib; each memory step of §3 (2^16 to 2^20 KiB) sealed by Faraday at scale 1, each message equal byte for byte to the PyCA judge's seal of the same random bytes; items at the size limits (a note of 216 and 217 bytes, a passphrase of 193 and 194, a 24-word seed of the longest words); a passphrase in NFD or NFC either way; a wrong passphrase; a 15-word seed and a document of two keys sealed by rPGP, refused by Faraday; the messages sq writes, refused by Faraday and the PyCA judge; two items sealed by rPGP in chunks of 64 bytes (chunk size octet 0), opened by Faraday.
Differences QR vault: sq 1.3.1 writes a SKESK v4 and a SEIPD v1 for a password under either --profile, never the SKESK v6 and SEIPD v2 of RFC 9580, so sq cannot seal a QR vault; rPGP and the PyCA judge seal the other direction, and the area asserts that Faraday and the PyCA judge refuse what sq writes. The PyCA judge's framing is the area's own Python; OpenPGP.js is not run.
When it runs Before every release, with a new seed and about ten times the cases.
Last passing runSeed 5be11ec606a76d2767f225b8992c45fe · 450 cases
The tags are compared in constant time by the ocb3 crate; Argon2id, HKDF and AES state nothing more.
The Argon2 output, the wrapping key, the session key, the message key and the opened plaintext are Zeroizing values wiped on drop; the Argon2 memory is overwritten after the run.
Limits
A SKESK v4, a SEIPD v1, a public-key encrypted session key, a second SKESK, compressed data, a signature and trailing data but padding are named "An OpenPGP message Faraday does not open".
Argon2 memory 8 MiB to 1 GiB, passes 1 to 100 and lanes 1 to 64; outside them the message is refused right after the key packet, before the data packet is read or any memory is taken; a QR vault is written at 64 MiB to 1 GiB.
A wrong passphrase is told from a changed message: the session key's tag fails for the first, a data tag for the second.
The passphrase arrives in Unicode NFC; the caller puts it there.
Faraday's own calls
Only AES-256 with OCB and the Argon2 S2K are read: another cipher, AEAD mode or S2K is refused, as are armor and every packet but the three (F178, F190). Conservative, F190.
The 43 pieces of code Faraday's authors wrote rather than took from a library, in four lists by reason, each with the action that uses it and the decision that accepts it.
Faraday's own specification
The format or procedure is Faraday's, so nothing outside can implement it. 5 pieces.
Piece
Action
Note
Decision
BIP-39 entry and display: words typed by pinyin, zhuyin, kana or hangul, the last word's candidates, the explorer's view of the checksum (faraday-bip::bip39)
For a miniscript Faraday picks the smallest witness as Bitcoin Core's finalizepsbt does; a plain multisig carries the first m signers' signatures, as Core writes them; miniscript builds and checks each witness.
libsecp256k1's MuSig2 is in rust-secp256k1 0.32 and later; bitcoin 0.32, which Faraday uses, is on 0.29, and no miniscript release builds on bitcoin 0.33 yet.
No maintained Rust implementation of AEZ exists; Faraday's follows the Go code LND uses and is tested against LND's vectors. Its AES round is the aes crate's and its BLAKE2b the blake2 crate's.
No maintained Rust crate offers libsodium's secretstream; Faraday's is HChaCha20, ChaCha20 and Poly1305 of RustCrypto's crates, and is tested against a file libsodium sealed and against libsodium itself.
No maintained Rust crate offers Bitcoin Core's BytesToKeySHA512AES and DecryptSecret; Faraday's is SHA-512 rounds over faraday-crypto and RustCrypto's aes and cbc, tested against wallets Bitcoin Core made.
No Rust implementation of the OpenTimestamps proof format is established; Faraday's follows python-opentimestamps and is tested against that project's example proofs.
No QR encoder comes from a publisher Faraday's dependency review trusts; Faraday's port of Nayuki's code wipes a SeedQR's buffers. Carries a format; it computes nothing on a key.
The CRC-32 crate in the tree, crc32fast 1.5.1, is not covered by an outside review at that version; Faraday's is a branch-free loop checked against the published check values. Carries a format; it computes nothing on a key.
No FAT library comes from a publisher Faraday's dependency review trusts; the partition it makes is checked by dosfstools' fsck.fat, against what mkfs.fat makes. Carries a format; it computes nothing on a key.
The Rust BIP-39 library's word lookup takes a time that follows the secret words; Faraday's looks each word up in constant time and is tested against that library and the reference. Does not fit: bip39 2.2.2 finds a word by a binary search or a scan that stops at it (find_word) and packs entropy with a branch on each bit (from_entropy_in), so the time it takes follows the secret words
The seed is derived with the RustCrypto PBKDF2 Faraday uses everywhere, into a buffer that is wiped. Does not fit: bip39's to_seed returns the seed as a plain [u8; 64], and its own PBKDF2 leaves its HMAC state unwiped (bip39 2.2.2's src/pbkdf2.rs)
Faraday writes a SeedQR's picture in buffers it wipes; its Adler-32 is the adler2 crate's. Does not fit: png 0.18.1 needs std, which faraday-codec does not have, and does not wipe a picture's rows Carries a format; it computes nothing on a key.
The reference library keeps the seed in text that is never wiped and needs a full operating system. Does not fit: codex32 0.1.0 holds the seed in a String that is Clone and Debug and never wiped, which tools/lint-secrets.sh refuses, and needs std, which faraday-bip does not have
The Rust scrypt library leaves its passphrase-derived working memory unwiped; Faraday's wipes it. Does not fit: scrypt 0.12.0 frees its passphrase-derived working buffers (b, v, t) without wiping them
The Rust HKDF library leaves the pseudorandom key and its output blocks unwiped; Faraday's holds both in buffers it wipes. Does not fit: hkdf 0.13.0 returns the pseudorandom key and leaves each output block T(i) in plain arrays it does not wipe
KEF: the envelope, the version table, padding, the two SHA-256 checks and base43 (faraday-codec::kef, faraday-kef), and PBKDF2's loop over HMAC-SHA-256 for one block, with a cancel check (faraday-crypto::hash)
The QR vault's OpenPGP message: the version 6 symmetric-key packet with the Argon2 S2K, the version 2 data packet and the literal data packet (faraday-pgp::message)
Faraday writes only the three packets a QR vault uses, over argon2, aes and ocb3 and Faraday's HKDF; rPGP, which no review Faraday trusts covers, brings every OpenPGP algorithm.
Faraday writes only the part of KeePass's format the vault uses, over argon2, chacha20, aes and cbc, hmac, sha2 and miniz_oxide; keepass-rs, which no review Faraday trusts covers, drops the XML elements it does not read and draws a save's randomness itself.
Faraday writes only the packets of its one key shape, over Ed25519 from dalek and SHA-1/SHA-2 from RustCrypto, each judged by GnuPG and paperkey; the armour's base64 is the base64ct crate's.
The 3 libraries the actions use that are not established, each with the reason it is used and the decision that accepts it.
Library
Reason
Decision
lzma-rust2
The Starter's xz decoder. No established pure-Rust streaming xz decoder exists, and the Starter's design (docs/STARTER.md) rules out the C library liblzma; what it writes is checked against the signed manifest's SHA-256 and size.
The camera's QR decoder, vendored and patched against panics on hostile frames (third_party/rqrr/PATCHES.md): the only maintained pure-Rust QR decoder. What it reads is untrusted input that Faraday's parsers check. The same panic is reported upstream as rqrr's issue 54.
The tokenizer under the XML of a KDBX vault file. It does no cryptography and has no outside review; its default features are off and it is already in the dependency graph. Which references are refused, the nesting cap and everything else the reader does are Faraday's own.