Skip to main content

Wallet-level QR (bittool-signer-wallet v2)

ur:bytescanonical CBORanimatedversion 2identity signature

The wallet-level QR code exports every account of one BitTool Signer wallet in a single scan: four Bitcoin accounts (one per single-signature address type), the EVM and TRON accounts, and the three Solana preset addresses. In the app it is Pair › Wallet Level.

Version 2 keeps everything version 1 defined and adds a wallet-identity signature: a Bitcoin message signature, made from the wallet's own seed, over one fixed public sentence. It shows that whoever produced the code holds the private key behind the public keys it exports. The receiving wallet verifies it on the device, offline, before it creates a watch-only wallet, and then registers it as the wallet's identity.

Produced byBitTool Signer 1.1.0 or later (iOS and Android). It produces only v2.
Accepted byBitTool Wallet 1.1.0 or later. It accepts only v2.
Changed from v1version is 2; two new fields, khSig and khEpoch; the identity check is mandatory
UnchangedAccounts, paths, canonical CBOR, the ur:bytes transport, and every coin-level export

Encoding​

pairing object (text keys, see below)
→ canonical CBOR (RFC 8949 §4.2.1) "inner", 1666 bytes for the test wallet
→ CBOR byte string containing those bytes "outer"
→ UR type "bytes" (BCR-2020-006)
→ multi-part UR, 400-byte fragments, upper-case 5 frames for the test wallet

Exactly as in v1:

  1. Two CBOR layers. The UR body is a CBOR byte string; the pairing map is inside it.
  2. Text keys. The map keys are the JSON field names as CBOR text strings.
  3. Canonical encoding. Definite lengths, shortest integer forms, and map keys sorted by the bytes of their encoding (for text keys: shorter keys first, then bytewise). The new keys sort with the rest: khSig (5 characters) comes before khEpoch (7), both after mode and before network.
  4. Always animated. The fragment size is 400 bytes, capped at half the payload, so there are always at least two frames. BitTool Signer refuses payloads above 4,096 bytes. Collect all frames (in any order) before decoding.

The pairing object​

Envelope​

FieldTypeValue
protocoltext"bittool-signer-wallet"
versionuint2. Refuse every other version, v1 included.
modetext"full". BitTool Signer only produces full.
networktext"mainnet"
masterFingerprinttextBIP32 master key fingerprint, 8 lower-case hex digits
khSigtextNew. The wallet-identity signature: base64 of 65 bytes, see below
khEpochuintNew. The epoch the signature is for. 1 today; the field allows a later rotation without a format change.
accountsarray7 entries, as in v1. Look them up by chain and script/profile, never by position.

Accounts​

chainFieldsNotes
btc (×4)accountPath, script, xpub, derive: {receive: "0/*", change: "1/*"}One per script: p2wpkh (m/84'/0'/0'), p2tr (m/86'/0'/0'), p2sh-p2wpkh (m/49'/0'/0'), p2pkh (m/44'/0'/0'). The p2pkh account is also the identity account.
evmaccountPath m/44'/60'/0', xpub, derive: "0/*"One account for all EVM networks
tronaccountPath m/44'/195'/0', xpub, derive: "0/*"
solprofile: "bip44-solana", accounts: [{index, profile, path, address}]Three entries: standard m/44'/501'/0'/0', trust m/44'/501'/0', legacy m/44'/501'

Every xpub uses the standard mainnet version bytes 0x0488B21E; the script field, not a ypub/zpub prefix, says which addresses to derive. Multisig (BIP48) cosigner keys are not included; use the coin-level cosigner export for those.

The identity signature​

Identity keym/44'/0'/0'/0/1000000000: the non-hardened child 1000000000 of the BIP44 receive branch
MessageOwnbitAuth:v2:epoch=<khEpoch>: ASCII, no spaces, the epoch in decimal. This exact text is fixed by the wallet backend; nothing else is ever signed.
DigestSHA256(SHA256(0x18 ‖ "Bitcoin Signed Message:\n" ‖ varint(len) ‖ message))
SignatureECDSA secp256k1, RFC 6979 deterministic k, low S. Base64 of 65 bytes: header ‖ R (32) ‖ S (32)
Header27 + recovery id + 4 (the + 4 marks a compressed key), so 31 or 32 in practice. Accept 27…42.
Verifying addressThe P2PKH (1…) address of the identity key
kh2Lower-case hex of SHA-256(R ‖ S). It is the wallet's identity value; it is not in the payload, the receiver computes it.

Why under BIP44. BitTool Wallet registers the BIP44 receive-branch xpub (m/44'/0'/0'/0) with its backend, for a hot wallet and for a watch-only wallet paired from BitTool Signer alike, so the same seed is recognised as one wallet. The backend derives the identity key as child 1000000000 of that xpub, so the identity key lives under BIP44 even though the default receive addresses are BIP84. The payload's p2pkh account (m/44'/0'/0') is where a receiver derives it from: 0/1000000000.

Because k is deterministic, the same wallet and epoch always give the same bytes: reinstalling either app re-derives exactly the same identity.

What the signature is not. It is not a transaction and authorizes nothing. It covers a sentence with no amounts, addresses or recipients, and BitTool Signer's engine has no way to sign any other text with that key: the operation takes an epoch and nothing else.

When BitTool Signer asks for the password. A wallet created or imported on 1.1.0 signs its identity at that moment, while the seed is already unlocked, and stores the signature beside its authenticated public index, so the pairing page opens without a password. A wallet saved by an earlier version shows a password field once, the first time its wallet-level code is opened; after that it behaves the same. Coin-level exports never need the password.

Test vectors​

From the public test phrase abandon … about, no passphrase. Point your scanner at the animation, or use the frames below.

Wallet-level pairing QR v2 (test wallet)5 frames · 1,666-byte payload · loops like the app
UR:BYTES/1-5/LPADAHCFAMLPCYENRFFRBBHKADGLHKAMLFPDIEJNJLIEIHIEIYKPJZJZIHJEISGUINIOKSHDGAFYIDJSEHGMGDKNGWJNJSEHJSEOEMGEJPIAHDIAGDFWHSESKOHFIMJPJOFLDYFWDNESDLJZJYGEHDGYIMIYHGJZFYFLJLGDDLIOKTFDFYGTIHFLFGFDECHDIEGSENESEOKTJTISIDIHFPJKFWIEIYGMIMEMKSEMDYJKESEEGSJNEEFSIOJEISFEJOJLIAISADIOJTIHJYKTJLJPJEIOJNHSINJTJTIHJYIOKOIHJPJKINJLJTAOISHSIAIAJLKPJTJYJKLTONIEKSJOKPIDKSJLKSJOKPIDENFXHSJYHGIEINHTINJLIEJNGOIHGHFYJOETGSGHECJLJPETJTJNIDGRGLIAKPKKKOKNEMHGKKJEJKHFFGJEGRFWEEGMFDKTFXFYEOHDKKKPKOGDFEIDKOJSFPGYHKEOJPFPGDJKISHGIAGTGSJLGDEYIYGTFGGTGRFDGDGEEEHTIHHTHDHKHFGOISGSKOEHHFGTJPIMGDFXEMGDHGENHFIHIAISHSINJTIAIDJYIAIYIEIHJPINKOIHOEIYIAISHSJTIOIHIAEHDLDRIOJPIHIAIHINKOIHIADYDLDRIYJKIAJPINJOJYIYJOEYKTJOJEISJEHSIAIAJLKPOXPDLPLN
1 / 5
Pairing object (JSON view of the inner CBOR)
{
"protocol": "bittool-signer-wallet",
"version": 2,
"mode": "full",
"network": "mainnet",
"masterFingerprint": "73c5da0a",
"khEpoch": 1,
"khSig": "IDbq1RPzOmq1q37JrcXcPBa9vVjrpG0B+9/ltJXQjfWlDGoP/gwHDMeGFH5XdL693wnhbeAsBdfRj7x70s94Lm4=",
"accounts": [
{
"chain": "btc",
"accountPath": "m/84'/0'/0'",
"script": "p2wpkh",
"xpub": "xpub6CatWdiZiodmUeTDp8LT5or8nmbKNcuyvz7WyksVFkKB4RHwCD3XyuvPEbvqAQY3rAPshWcMLoP2fMFMKHPJ4ZeZXYVUhLv1VMrjPC7PW6V",
"derive": {
"receive": "0/*",
"change": "1/*"
}
},
{
"chain": "btc",
"accountPath": "m/86'/0'/0'",
"script": "p2tr",
"xpub": "xpub6BgBgsespWvERF3LHQu6CnqdvfEvtMcQjYrcRzx53QJjSxarj2afYWcLteoGVky7D3UKDP9QyrLprQ3VCECoY49yfdDEHGCtMMj92pReUsQ",
"derive": {
"receive": "0/*",
"change": "1/*"
}
},
{
"chain": "btc",
"accountPath": "m/49'/0'/0'",
"script": "p2sh-p2wpkh",
"xpub": "xpub6C6nQwHaWbSrzs5tZ1q7m5R9cPK9eYpNMFesiXsYrgc1P8bvLLAet9JfHjYXKjToD8cBRswJXXbbFpXgwsswVPAZzKMa1jUp2kVkGVUaJa7",
"derive": {
"receive": "0/*",
"change": "1/*"
}
},
{
"chain": "btc",
"accountPath": "m/44'/0'/0'",
"script": "p2pkh",
"xpub": "xpub6BosfCnifzxcFwrSzQiqu2DBVTshkCXacvNsWGYJVVhhawA7d4R5WSWGFNbi8Aw6ZRc1brxMyWMzG3DSSSSoekkudhUd9yLb6qx39T9nMdj",
"derive": {
"receive": "0/*",
"change": "1/*"
}
},
{
"chain": "evm",
"accountPath": "m/44'/60'/0'",
"xpub": "xpub6DCoCpSuQZB2jawqnGMEPS63ePKWkwWPH4TU45Q7LPXWuNd8TMtVxRrgjtEshuqpK3mdhaWHPFsBngh5GFZaM6si3yZdUsT8ddYM3PwnATt",
"derive": "0/*"
},
{
"chain": "tron",
"accountPath": "m/44'/195'/0'",
"xpub": "xpub6D1AabNHCupeiLM65ZR9UStMhJ1vCpyV4XbZdyhMZBiJXALQtmn9p42VTQckoHVn8WNqS7dqnJokZHAHcHGoaQgmv8D45oNUKx6DZMNZBCd",
"derive": "0/*"
},
{
"chain": "sol",
"profile": "bip44-solana",
"accounts": [
{
"index": 0,
"profile": "standard",
"path": "m/44'/501'/0'/0'",
"address": "HAgk14JpMQLgt6rVgv7cBQFJWFto5Dqxi472uT3DKpqk"
},
{
"index": 1,
"profile": "trust",
"path": "m/44'/501'/0'",
"address": "GjJyeC1r2RgkuoCWMyPYkCWSGSGLcz266EaAkLA27AhL"
},
{
"index": 2,
"profile": "legacy",
"path": "m/44'/501'",
"address": "D2PPQSYFe83nDzk96FqGumVU8JA7J8vj2Rhjc2oXzEi5"
}
]
}
]
}
QR frames (ur:bytes, 5 parts)
frames
UR:BYTES/1-5/LPADAHCFAMLPCYENRFFRBBHKADGLHKAMLFPDIEJNJLIEIHIEIYKPJZJZIHJEISGUINIOKSHDGAFYIDJSEHGMGDKNGWJNJSEHJSEOEMGEJPIAHDIAGDFWHSESKOHFIMJPJOFLDYFWDNESDLJZJYGEHDGYIMIYHGJZFYFLJLGDDLIOKTFDFYGTIHFLFGFDECHDIEGSENESEOKTJTISIDIHFPJKFWIEIYGMIMEMKSEMDYJKESEEGSJNEEFSIOJEISFEJOJLIAISADIOJTIHJYKTJLJPJEIOJNHSINJTJTIHJYIOKOIHJPJKINJLJTAOISHSIAIAJLKPJTJYJKLTONIEKSJOKPIDKSJLKSJOKPIDENFXHSJYHGIEINHTINJLIEJNGOIHGHFYJOETGSGHECJLJPETJTJNIDGRGLIAKPKKKOKNEMHGKKJEJKHFFGJEGRFWEEGMFDKTFXFYEOHDKKKPKOGDFEIDKOJSFPGYHKEOJPFPGDJKISHGIAGTGSJLGDEYIYGTFGGTGRFDGDGEEEHTIHHTHDHKHFGOISGSKOEHHFGTJPIMGDFXEMGDHGENHFIHIAISHSINJTIAIDJYIAIYIEIHJPINKOIHOEIYIAISHSJTIOIHIAEHDLDRIOJPIHIAIHINKOIHIADYDLDRIYJKIAJPINJOJYIYJOEYKTJOJEISJEHSIAIAJLKPOXPDLPLN
UR:BYTES/2-5/LPAOAHCFAMLPCYENRFFRBBHKADGLJTJYGDHSJYISJEJNDLETEEDIDLDYDIDLDYDIONIEKSJOKPIDKSJLKSJOKPIDENFWIOFWIOJKIHJKJOHGKOFEGMFGEOGSFDGYKPENFXJTJSIEKOIYFEKOJYGTIAGYIMHKJPIAGMKNKSECEOGYGEIMGUKSHSJPIMEYHSIYHKHGIAGSJYIHJLFLHFJEKKEMFYEOGOGRFYGDESGYKKJPGSJOJPGYEOHFFXFEFXJLHKEEESKKIYIEFYFEFDFLFXJYGTGTIMESEYJOGMIHGOJKGYIHIAISHSINJTIAIDJYIAIYIEIHJPINKOIHOEIYIAISHSJTIOIHIAEHDLDRIOJPIHIAIHINKOIHIADYDLDRIYJKIAJPINJOJYIEJOEYJYJPJEHSIAIAJLKPJTJYGDHSJYISJEJNDLETENDIDLDYDIDLDYDIONIEKSJOKPIDKSJLKSJOKPIDENFXENJTGYKTFDHSHGIDGUJPKNJKECJYHTEHJSEMJNECGMESIAGDGRESIHHKJOGLGTFGIHJKINHDJKHKJPIOIAEHGDETIDKOGSGSFPIHJYESGEIYFDIMHKHDGRIMGHJLFYETIAFWGMJKKTGEHDHDIDIDFGJOHDIOKTJKJKKTHFGDFPHTKNGRGTHSEHIMGOJOEYJEHFJEFLHFGOHSGEHSEMIHMSIABBAM
UR:BYTES/3-5/LPAXAHCFAMLPCYENRFFRBBHKADGLIAISHSINJTIAIDJYIAIYIEIHJPINKOIHOEIYIAISHSJTIOIHIAEHDLDRIOJPIHIAIHINKOIHIADYDLDRIYJKIAJPINJOJYJEJOEYJKISDPJOEYKTJOJEISJEHSIAIAJLKPJTJYGDHSJYISJEJNDLEEESDIDLDYDIDLDYDIONIEKSJOKPIDKSJLKSJOKPIDENFWJLJKIYFXJTINIYKNKSIAFGKTJPGUKNGYINJSKPEYFYFWHFGHJKISJEFXHDHSIAKOGLJKHGFLHKGEHFHFISISHSKTFPEMIEEEGMECHGGUHGFLFGGLIDINETFPKTENHTGMIAEHIDJPKSGTKKHGGTKNFLEOFYGUGUGUGUJLIHJEJEKPIEISGOIEESKKGSIDENJSKSEOESGHESJTGTIEIMIHIAISHSINJTIAIDJYIAIYIEIHJPINKOIHOEIYIAISHSJTIOIHIAEHDLDRIOJPIHIAIHINKOIHIADYDLDRIYJKIAJPINJOJYIHJOEYJOJEISJEHSIAIAJLKPJTJYGDHSJYISJEJNDLEEEEDIDLDYDIDLDYDIOXIEKSJOKPIDKSJLKSJOKPIDENFYFXJLFXJOGUKPGYHTFWEYIMHSKTJSJTFLGTFEGDGUENEOIHGDGRHGJEKTHGGDFDEEGHGOEEECGYEMGSGDDTPFJTJK
UR:BYTES/4-5/LPAAAHCFAMLPCYENRFFRBBHKADGLHDHGKPGLIEETGHGTJYHFKSGMJPIOIMJYFEJKISKPJSJOGREOJNIEISHSHGFDGDFGJKFWJTIOISECFLFGHTHSGTENJKINEOKKHTIEGOJKGHETIEIEHKGTEOGDKTJTFPGHJYIHIAISHSINJTIAIHKOJNIYIEIHJPINKOIHIADYDLDRJEHSIAIAJLKPJTJYGDHSJYISJZJNDLEEEEDIDLENDYDIDLDYDIOXIEKSJOKPIDKSJLKSJOKPIDENFYEHFPHSIDGLFDFXKPJOIHINGSGTENECHTGMESGOGUJYGTISGEEHKOFXJOKKHFEEHDIDHTIEKKISGTHTFWINGEHDFPGSGYJYJNJTESJOEEEYHFGHGYIAJEJLFDHFJTETHGGLJSGUEMIEJSJTGEJLJEHTFDFPFDIAFDFLJLHSGYIOJNKOETFYEEECJLGLGOGRKSENFYHTGTGLHTFWFXIEIHIAISHSINJTIEJYJPJLJTIYIEIHJPINKOIHIADYDLDRJEHSIAIAJLKPJTJYGDHSJYISJNJNDLEEEEDIDLEHESECDIDLDYDIOTIHIAISHSINJTIAJKJLJZIOJOJPJLIYINJZIHJZIDINJOEEEEDPJKJLJZHSJTHSISHSIAIAJLKPJTJYJKLSOXIEJOHSJYISJOJNDLEEEEDIDLECRNIECEQZ
UR:BYTES/5-5/LPAHAHCFAMLPCYENRFFRBBHKADGLDYEHDIDLDYDIDLDYDIIHINJTIEIHKSAEIOHSIEIEJPIHJKJKKSDWFDFPIOJEEHEEGEJOGTGYGSIOJYENJPHFIOKOEMIAFWGYFGGEHGFGJYJLECFYJSKSINEEEMEYKPGHEOFYGRJOJSJEIOJOJPJLIYINJZIHISJKJYHSJTIEHSJPIEOXIEJOHSJYISJNJNDLEEEEDIDLECDYEHDIDLDYDIIHINJTIEIHKSADIOHSIEIEJPIHJKJKKSDWFLIMGEKKIHFXEHJPEYGMIOJEKPJLFXHGGTKKGDHKJEFXHGGUFLGUFLGSIAKNEYENENFEHSFPJEGSFPEYEMFPISGSIOJOJPJLIYINJZIHIHJYJPKPJKJYOXIEJOHSJYISIMJNDLEEEEDIDLECDYEHDIIHINJTIEIHKSAOIOHSIEIEJPIHJKJKKSDWFYEYGDGDGYGUHKFGIHETEOJTFYKNJEESENFGJSFLKPJNHFGOETGEFPEMGEETKOIMEYGMISIMIAEYJLHDKNFEINECIOJOJPJLIYINJZIHIYJZIHIOHSIAKKISJOJPJLJYJLIAJLJZKPIDINJYJYJLJLJZDPJKINIOJTIHJPDPKTHSJZJZIHJYJSJNHSJKJYIHJPFGINJTIOIHJPJOJPINJTJYISEMEOIAECIEHSDYHSAEFHSGBEJL
Inner canonical CBOR (hex) and its SHA-256
inner CBOR, 1666 bytes
a8646d6f64656466756c6c656b685369677858494462713152507a4f6d71317133374a726358635042613976566a72704730422b392f6c744a58516a66576c44476f502f677748444d654746483558644c363933776e6862654173426466526a377837307339344c6d343d676b6845706f636801676e6574776f726b676d61696e6e65746776657273696f6e02686163636f756e747387a56478707562786f78707562364361745764695a696f646d5565544470384c54356f72386e6d624b4e637579767a3757796b7356466b4b423452487743443358797576504562767141515933724150736857634d4c6f5032664d464d4b48504a345a655a58595655684c7631564d726a5043375057365665636861696e6362746366646572697665a2666368616e676563312f2a677265636569766563302f2a6673637269707466703277706b686b6163636f756e74506174686b6d2f3834272f30272f3027a56478707562786f787075623642674267736573705776455246334c48517536436e716476664576744d63516a597263527a783533514a6a537861726a3261665957634c74656f47566b79374433554b4450395179724c70725133564345436f5934397966644445484743744d4d6a393270526555735165636861696e6362746366646572697665a2666368616e676563312f2a677265636569766563302f2a6673637269707464703274726b6163636f756e74506174686b6d2f3836272f30272f3027a56478707562786f787075623643366e51774861576253727a7335745a3171376d35523963504b396559704e4d4665736958735972676331503862764c4c416574394a66486a59584b6a546f443863425273774a5858626246705867777373775650415a7a4b4d61316a5570326b566b475655614a613765636861696e6362746366646572697665a2666368616e676563312f2a677265636569766563302f2a667363726970746b703273682d703277706b686b6163636f756e74506174686b6d2f3439272f30272f3027a56478707562786f7870756236426f7366436e69667a7863467772537a51697175324442565473686b43586163764e735747594a56566868617741376434523557535747464e6269384177365a5263316272784d79574d7a473344535353536f656b6b756468556439794c62367178333954396e4d646a65636861696e6362746366646572697665a2666368616e676563312f2a677265636569766563302f2a66736372697074657032706b686b6163636f756e74506174686b6d2f3434272f30272f3027a46478707562786f787075623644436f43705375515a42326a6177716e474d455053363365504b576b77575048345455343551374c505857754e6438544d7456785272676a744573687571704b336d6468615748504673426e67683547465a614d36736933795a64557354386464594d3350776e41547465636861696e6365766d6664657269766563302f2a6b6163636f756e74506174686c6d2f3434272f3630272f3027a46478707562786f787075623644314161624e4843757065694c4d36355a52395553744d684a3176437079563458625a6479684d5a42694a58414c51746d6e39703432565451636b6f48566e38574e71533764716e4a6f6b5a4841486348476f6151676d76384434356f4e554b7836445a4d4e5a42436465636861696e6474726f6e6664657269766563302f2a6b6163636f756e74506174686d6d2f3434272f313935272f3027a365636861696e63736f6c6770726f66696c656c62697034342d736f6c616e61686163636f756e747383a46470617468706d2f3434272f353031272f30272f302765696e646578006761646472657373782c4841676b31344a704d514c6774367256677637634251464a5746746f3544717869343732755433444b70716b6770726f66696c65687374616e64617264a464706174686d6d2f3434272f353031272f302765696e646578016761646472657373782c476a4a79654331723252676b756f43574d7950596b4357534753474c637a3236364561416b4c41323741684c6770726f66696c65657472757374a464706174686a6d2f3434272f3530312765696e646578026761646472657373782c44325050515359466538336e447a6b3936467147756d5655384a41374a38766a3252686a63326f587a4569356770726f66696c65666c65676163796870726f746f636f6c75626974746f6f6c2d7369676e65722d77616c6c6574716d617374657246696e6765727072696e74683733633564613061
SHA-256(inner)
cc911414877a3b544b90f6c8ac794c76197015b60c00002d12577608473894ef

Identity​

Identity pathm/44'/0'/0'/0/1000000000
Identity public key02a61d47c2a0326f197d2d42bfc27b4171f7870e6b3d7ad37f3f210c3d602bab1c
Identity address1N8ju3BdMHttCNBJ4d8v3eCrpzdLk1m9Vo
Registered xpub (m/44'/0'/0'/0)xpub6ELHKXNimKbxMCytPh7EdC2QXx46T9qLDJWGnTraz1H9kMMFdcduoU69wh9cxP12wDxqAAfbaESWGYt5rREsX1J8iR2TEunvzvddduAPYcY
EpochMessagekhSigkh2
1OwnbitAuth:v2:epoch=1IDbq1RPzOmq1q37JrcXcPBa9vVjrpG0B+9/ltJXQjfWlDGoP/gwHDMeGFH5XdL693wnhbeAsBdfRj7x70s94Lm4=4fb494ddc6dac144c283c3a24f92156937c855a1b2e3997981ef510465d948fc
2OwnbitAuth:v2:epoch=2HyJlRiut4wBA9pcd0q6BFqC1ghMJUhpRd82P3pUS+LNLBY0MOquhqW11cNTf1QGYSHUJ3b8N930O+SvrVOIdYqE=af8fde9ee528be6f31de021820fa7490b1584b0b753b29e12443927135ec5292

Every BitTool implementation (Signer for iOS and Android, Wallet for iOS and Android) reproduces these bytes exactly. Downloads: wallet-pairing-v2.json (payload, CBOR, frames, addresses, identity) and kh2_bittool_vectors.json (the identity signatures, also published in the BitTool Signer repositories).

The first address of each account, which BitTool Signer shows under the QR code:

AccountPathAddress
Bitcoin P2WPKHm/84'/0'/0'/0/0bc1qcr8te4kr609gcawutmrza0j4xv80jy8z306fyu
Bitcoin P2TRm/86'/0'/0'/0/0bc1p5cyxnuxmeuwuvkwfem96lqzszd02n6xdcjrs20cac6yqjjwudpxqkedrcr
Bitcoin P2SH-P2WPKHm/49'/0'/0'/0/037VucYSaXLCAsxYyAPfbSi9eh4iEcbShgf
Bitcoin P2PKHm/44'/0'/0'/0/01LqBGSKuX5yYUonjxT5qGfpUsXKYYWeabA
EVMm/44'/60'/0'/0/00x9858EfFD232B4033E47d90003D41EC34EcaEda94
TRONm/44'/195'/0'/0/0TUEZSdKsoDHQMeZwihtdoBiN46zxhGWYdH
Solana standardm/44'/501'/0'/0'HAgk14JpMQLgt6rVgv7cBQFJWFto5Dqxi472uT3DKpqk
Solana trustm/44'/501'/0'GjJyeC1r2RgkuoCWMyPYkCWSGSGLcz266EaAkLA27AhL
Solana legacym/44'/501'D2PPQSYFe83nDzk96FqGumVU8JA7J8vj2Rhjc2oXzEi5

Decoding it​

This decoder uses @ngraveio/bc-ur for the UR layer and cborg in strict mode for CBOR. It refuses every version other than 2:

examples/wallet-pairing.mjs
import { URDecoder } from '@ngraveio/bc-ur';
import { decode } from 'cborg';

export function decodeWalletPairing(frames) {
const decoder = new URDecoder();
for (const frame of frames) decoder.receivePart(frame); // any order; repeats are ignored
if (!decoder.isComplete()) throw new Error(`Keep scanning: ${Math.round(decoder.estimatedPercentComplete() * 100)}%`);
if (!decoder.isSuccess()) throw new Error(decoder.resultError());

const ur = decoder.resultUR();
if (ur.type !== 'bytes') throw new Error('Not a BitTool Signer wallet QR');
const strict = { strict: true, rejectDuplicateMapKeys: true };
const inner = decode(ur.cbor, strict); // layer 1: a CBOR byte string
if (!(inner instanceof Uint8Array)) throw new Error('ur:bytes must hold a byte string');
const pairing = decode(inner, strict); // layer 2: the text-keyed map

if (pairing.protocol !== 'bittool-signer-wallet') throw new Error('Unknown protocol');
if (pairing.version !== 2) throw new Error('Unsupported version: update BitTool Signer to 1.1.0 or later and scan again');
if (pairing.mode !== 'full' && pairing.mode !== 'simple') throw new Error('Unsupported mode');
if (pairing.network !== 'mainnet') throw new Error('Unsupported network');
if (!/^[0-9a-f]{8}$/.test(pairing.masterFingerprint)) throw new Error('Bad fingerprint');
return pairing;
}

Then verify the identity signature against the payload's own p2pkh account. The function checks that the key recovered from the signature is the derived identity key and runs an explicit low-S ECDSA verification, which rejects a malleated or re-headered signature:

examples/wallet-pairing.mjs
import { HDKey } from '@scure/bip32';
import { secp256k1 } from '@noble/curves/secp256k1.js';
import { sha256 } from '@noble/hashes/sha2.js';
import { base64 } from '@scure/base';
import { p2pkh } from '@scure/btc-signer';

const AUTH_INDEX = 1000000000;
const hex = (bytes) => Buffer.from(bytes).toString('hex');

// Bitcoin signed-message digest; the identity sentence is far shorter than 253 bytes,
// so its length is a one-byte varint.
function messageDigest(text) {
const prefix = new TextEncoder().encode('\x18Bitcoin Signed Message:\n');
const message = new TextEncoder().encode(text);
return sha256(sha256(Uint8Array.from([...prefix, message.length, ...message])));
}

export function verifyWalletIdentity(pairing) {
const { khSig, khEpoch } = pairing;
if (!Number.isInteger(khEpoch) || khEpoch < 1) throw new Error('Missing or bad khEpoch');
const sig = typeof khSig === 'string' ? base64.decode(khSig) : new Uint8Array();
if (sig.length !== 65 || sig[0] < 27 || sig[0] > 42) throw new Error('Missing or bad khSig');

const identity = pairing.accounts.filter((a) => a.chain === 'btc' && a.script === 'p2pkh' && a.accountPath === "m/44'/0'/0'");
if (identity.length !== 1) throw new Error('No p2pkh identity account');
const key = HDKey.fromExtendedKey(identity[0].xpub).deriveChild(0).deriveChild(AUTH_INDEX).publicKey;

const digest = messageDigest(`OwnbitAuth:v2:epoch=${khEpoch}`);
const rs = sig.subarray(1);
const recovered = secp256k1.Signature.fromBytes(rs, 'compact') // throws unless 0 < R, S < n
.addRecoveryBit((sig[0] - 27) & 3).recoverPublicKey(digest).toBytes(true);
if (hex(recovered) !== hex(key)) throw new Error('khSig was not made by this wallet');
if (!secp256k1.verify(rs, digest, key, { prehash: false, lowS: true, format: 'compact' })) throw new Error('khSig does not verify');

return { address: p2pkh(key).address, kh2: hex(sha256(rs)) };
}

And derive the first addresses to show the user:

examples/wallet-pairing.mjs
import { HDKey } from '@scure/bip32';
import { keccak_256 } from '@noble/hashes/sha3.js';
import { sha256 } from '@noble/hashes/sha2.js';
import { secp256k1 } from '@noble/curves/secp256k1.js';
import { base58check } from '@scure/base';
import { p2wpkh, p2tr, p2sh, p2pkh } from '@scure/btc-signer';
import { getAddress } from 'ethers';

const child = (xpub, branch, index) => HDKey.fromExtendedKey(xpub).deriveChild(branch).deriveChild(index);

export function firstAddresses(pairing) {
const out = {};
for (const account of pairing.accounts) {
if (account.chain === 'btc') {
const pub = child(account.xpub, 0, 0).publicKey; // receive branch 0, index 0
out[`btc:${account.script}`] = {
p2wpkh: () => p2wpkh(pub).address,
p2tr: () => p2tr(pub.subarray(1)).address, // BIP86: untweaked x-only key
'p2sh-p2wpkh': () => p2sh(p2wpkh(pub)).address,
p2pkh: () => p2pkh(pub).address,
}[account.script]();
} else if (account.chain === 'evm' || account.chain === 'tron') {
const point = secp256k1.Point.fromBytes(child(account.xpub, 0, 0).publicKey);
const hash = keccak_256(point.toBytes(false).subarray(1)).subarray(-20);
out[account.chain] = account.chain === 'evm'
? getAddress('0x' + Buffer.from(hash).toString('hex'))
: base58check(sha256).encode(Uint8Array.from([0x41, ...hash]));
} else if (account.chain === 'sol') {
for (const sol of account.accounts) out[`sol:${sol.profile}`] = sol.address;
}
}
return out;
}

All three functions are run against the vectors above by examples/test.mjs in the docs repository, including the refusal of the v1 test code, of a wrong epoch and of a missing signature.

Receiver rules​

A receiver must:

  1. Require protocol == "bittool-signer-wallet" and integer version == 2. Refuse every other version, v1 included, and never read another version as v2. For a v1 code, tell the user: Update BitTool Signer to 1.1.0 or later, then open the wallet QR code again.
  2. Require mode == "full" (the draft also defines simple), network == "mainnet" and a valid 8-hex-digit masterFingerprint.
  3. Require khEpoch to be an integer ≥ 1, and khSig to decode to exactly 65 bytes with a header in 27…42 and 0 < R, S < n. Missing or malformed: refuse.
  4. Verify khSig on the device before creating anything: take the btc account with script == "p2pkh" and accountPath == "m/44'/0'/0'" (missing: refuse), derive 0/1000000000 from its xpub, and verify the Bitcoin message signature of OwnbitAuth:v2:epoch=<khEpoch> against that key's P2PKH address. Does not verify: refuse the code.
  5. Only then register the signature as the wallet's identity with your backend.

And, as in v1, a robust receiver should:

  • Find accounts by key, not by position, and reject a payload with a missing or duplicated known account.
  • Ignore unknown fields. Check the bytes exactly as received; do not strip unknown fields and re-encode before a canonical-encoding check.
  • Validate every xpub: Base58Check, version 0x0488B21E, depth 3, a hardened child index, a valid compressed secp256k1 key. Reject xprv, tpub and ypub/zpub.
  • Check the paths against the table above, rather than silently rewriting an unknown path to a default.
  • Validate Solana keys: Base58 decodes to exactly 32 bytes, a valid Ed25519 point, no duplicates.
  • Treat it as untrusted input: bound the frame count and sizes, reject duplicate CBOR keys and trailing bytes.

Security notes​

  • The payload holds only extended public keys, addresses and one signature over a fixed public sentence. The pairing builder reads the signer's authenticated public index; the signature is made from the seed once and stored beside that index under the same protection.
  • khSig and kh2 identify a wallet. Do not log them, upload them to analytics or include them in crash reports, and handle the whole payload like any xpub: anyone who scans it can see every address of these accounts and their history.
  • The signature proves who built the code. It does not authenticate the receiving wallet, so still show the first addresses after importing and ask the user to compare them in full.