지갑 레벨 QR (bittool-signer-wallet v2)
아래는 영어 원문입니다. 한국어판은 추후 제공됩니다.
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 by | BitTool Signer 1.1.0 or later (iOS and Android). It produces only v2. |
| Accepted by | BitTool Wallet 1.1.0 or later. It accepts only v2. |
| Changed from v1 | version is 2; two new fields, khSig and khEpoch; the identity check is mandatory |
| Unchanged | Accounts, 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:
- Two CBOR layers. The UR body is a CBOR byte string; the pairing map is inside it.
- Text keys. The map keys are the JSON field names as CBOR text strings.
- 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 beforekhEpoch(7), both aftermodeand beforenetwork. - 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
| Field | Type | Value |
|---|---|---|
protocol | text | "bittool-signer-wallet" |
version | uint | 2. Refuse every other version, v1 included. |
mode | text | "full". BitTool Signer only produces full. |
network | text | "mainnet" |
masterFingerprint | text | BIP32 master key fingerprint, 8 lower-case hex digits |
khSig | text | New. The wallet-identity signature: base64 of 65 bytes, see below |
khEpoch | uint | New. The epoch the signature is for. 1 today; the field allows a later rotation without a format change. |
accounts | array | 7 entries, as in v1. Look them up by chain and script/profile, never by position. |
Accounts
chain | Fields | Notes |
|---|---|---|
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. |
evm | accountPath m/44'/60'/0', xpub, derive: "0/*" | One account for all EVM networks |
tron | accountPath m/44'/195'/0', xpub, derive: "0/*" | |
sol | profile: "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 key | m/44'/0'/0'/0/1000000000: the non-hardened child 1000000000 of the BIP44 receive branch |
| Message | OwnbitAuth:v2:epoch=<khEpoch>: ASCII, no spaces, the epoch in decimal. This exact text is fixed by the wallet backend; nothing else is ever signed. |
| Digest | SHA256(SHA256(0x18 ‖ "Bitcoin Signed Message:\n" ‖ varint(len) ‖ message)) |
| Signature | ECDSA secp256k1, RFC 6979 deterministic k, low S. Base64 of 65 bytes: header ‖ R (32) ‖ S (32) |
| Header | 27 + recovery id + 4 (the + 4 marks a compressed key), so 31 or 32 in practice. Accept 27…42. |
| Verifying address | The P2PKH (1…) address of the identity key |
kh2 | Lower-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.
{
"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)
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
a8646d6f64656466756c6c656b685369677858494462713152507a4f6d71317133374a726358635042613976566a72704730422b392f6c744a58516a66576c44476f502f677748444d654746483558644c363933776e6862654173426466526a377837307339344c6d343d676b6845706f636801676e6574776f726b676d61696e6e65746776657273696f6e02686163636f756e747387a56478707562786f78707562364361745764695a696f646d5565544470384c54356f72386e6d624b4e637579767a3757796b7356466b4b423452487743443358797576504562767141515933724150736857634d4c6f5032664d464d4b48504a345a655a58595655684c7631564d726a5043375057365665636861696e6362746366646572697665a2666368616e676563312f2a677265636569766563302f2a6673637269707466703277706b686b6163636f756e74506174686b6d2f3834272f30272f3027a56478707562786f787075623642674267736573705776455246334c48517536436e716476664576744d63516a597263527a783533514a6a537861726a3261665957634c74656f47566b79374433554b4450395179724c70725133564345436f5934397966644445484743744d4d6a393270526555735165636861696e6362746366646572697665a2666368616e676563312f2a677265636569766563302f2a6673637269707464703274726b6163636f756e74506174686b6d2f3836272f30272f3027a56478707562786f787075623643366e51774861576253727a7335745a3171376d35523963504b396559704e4d4665736958735972676331503862764c4c416574394a66486a59584b6a546f443863425273774a5858626246705867777373775650415a7a4b4d61316a5570326b566b475655614a613765636861696e6362746366646572697665a2666368616e676563312f2a677265636569766563302f2a667363726970746b703273682d703277706b686b6163636f756e74506174686b6d2f3439272f30272f3027a56478707562786f7870756236426f7366436e69667a7863467772537a51697175324442565473686b43586163764e735747594a56566868617741376434523557535747464e6269384177365a5263316272784d79574d7a473344535353536f656b6b756468556439794c62367178333954396e4d646a65636861696e6362746366646572697665a2666368616e676563312f2a677265636569766563302f2a66736372697074657032706b686b6163636f756e74506174686b6d2f3434272f30272f3027a46478707562786f787075623644436f43705375515a42326a6177716e474d455053363365504b576b77575048345455343551374c505857754e6438544d7456785272676a744573687571704b336d6468615748504673426e67683547465a614d36736933795a64557354386464594d3350776e41547465636861696e6365766d6664657269766563302f2a6b6163636f756e74506174686c6d2f3434272f3630272f3027a46478707562786f787075623644314161624e4843757065694c4d36355a52395553744d684a3176437079563458625a6479684d5a42694a58414c51746d6e39703432565451636b6f48566e38574e71533764716e4a6f6b5a4841486348476f6151676d76384434356f4e554b7836445a4d4e5a42436465636861696e6474726f6e6664657269766563302f2a6b6163636f756e74506174686d6d2f3434272f313935272f3027a365636861696e63736f6c6770726f66696c656c62697034342d736f6c616e61686163636f756e747383a46470617468706d2f3434272f353031272f30272f302765696e646578006761646472657373782c4841676b31344a704d514c6774367256677637634251464a5746746f3544717869343732755433444b70716b6770726f66696c65687374616e64617264a464706174686d6d2f3434272f353031272f302765696e646578016761646472657373782c476a4a79654331723252676b756f43574d7950596b4357534753474c637a3236364561416b4c41323741684c6770726f66696c65657472757374a464706174686a6d2f3434272f3530312765696e646578026761646472657373782c44325050515359466538336e447a6b3936467147756d5655384a41374a38766a3252686a63326f587a4569356770726f66696c65666c65676163796870726f746f636f6c75626974746f6f6c2d7369676e65722d77616c6c6574716d617374657246696e6765727072696e74683733633564613061
cc911414877a3b544b90f6c8ac794c76197015b60c00002d12577608473894ef
Identity
| Identity path | m/44'/0'/0'/0/1000000000 |
| Identity public key | 02a61d47c2a0326f197d2d42bfc27b4171f7870e6b3d7ad37f3f210c3d602bab1c |
| Identity address | 1N8ju3BdMHttCNBJ4d8v3eCrpzdLk1m9Vo |
Registered xpub (m/44'/0'/0'/0) | xpub6ELHKXNimKbxMCytPh7EdC2QXx46T9qLDJWGnTraz1H9kMMFdcduoU69wh9cxP12wDxqAAfbaESWGYt5rREsX1J8iR2TEunvzvddduAPYcY |
| Epoch | Message | khSig | kh2 |
|---|---|---|---|
| 1 | OwnbitAuth:v2:epoch=1 | IDbq1RPzOmq1q37JrcXcPBa9vVjrpG0B+9/ltJXQjfWlDGoP/gwHDMeGFH5XdL693wnhbeAsBdfRj7x70s94Lm4= | 4fb494ddc6dac144c283c3a24f92156937c855a1b2e3997981ef510465d948fc |
| 2 | OwnbitAuth:v2:epoch=2 | HyJlRiut4wBA9pcd0q6BFqC1ghMJUhpRd82P3pUS+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:
| Account | Path | Address |
|---|---|---|
| Bitcoin P2WPKH | m/84'/0'/0'/0/0 | bc1qcr8te4kr609gcawutmrza0j4xv80jy8z306fyu |
| Bitcoin P2TR | m/86'/0'/0'/0/0 | bc1p5cyxnuxmeuwuvkwfem96lqzszd02n6xdcjrs20cac6yqjjwudpxqkedrcr |
| Bitcoin P2SH-P2WPKH | m/49'/0'/0'/0/0 | 37VucYSaXLCAsxYyAPfbSi9eh4iEcbShgf |
| Bitcoin P2PKH | m/44'/0'/0'/0/0 | 1LqBGSKuX5yYUonjxT5qGfpUsXKYYWeabA |
| EVM | m/44'/60'/0'/0/0 | 0x9858EfFD232B4033E47d90003D41EC34EcaEda94 |
| TRON | m/44'/195'/0'/0/0 | TUEZSdKsoDHQMeZwihtdoBiN46zxhGWYdH |
| Solana standard | m/44'/501'/0'/0' | HAgk14JpMQLgt6rVgv7cBQFJWFto5Dqxi472uT3DKpqk |
| Solana trust | m/44'/501'/0' | GjJyeC1r2RgkuoCWMyPYkCWSGSGLcz266EaAkLA27AhL |
| Solana legacy | m/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:
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:
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:
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:
- Require
protocol == "bittool-signer-wallet"and integerversion == 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. - Require
mode == "full"(the draft also definessimple),network == "mainnet"and a valid 8-hex-digitmasterFingerprint. - Require
khEpochto be an integer ≥ 1, andkhSigto decode to exactly 65 bytes with a header in27…42and0 < R, S < n. Missing or malformed: refuse. - Verify
khSigon the device before creating anything: take thebtcaccount withscript == "p2pkh"andaccountPath == "m/44'/0'/0'"(missing: refuse), derive0/1000000000from its xpub, and verify the Bitcoin message signature ofOwnbitAuth:v2:epoch=<khEpoch>against that key's P2PKH address. Does not verify: refuse the code. - 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. Rejectxprv,tpubandypub/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.
khSigandkh2identify 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.