This BIP defines a compact encryption scheme for output script descriptors (BIP-0380),\nwallet policies (BIP-0388), and other wallet metadata.\nThe payload must not contain any private key material.
\nUsers can store encrypted backups on untrusted media or cloud services without leaking\naddresses, script structures, or cosigner counts. The encryption key derives from the\nlexicographically-sorted public keys in the descriptor, allowing any keyholder to decrypt\nwithout additional secrets.
\nThough designed for descriptors and policies, the scheme works equally well for labels\nand backup metadata.
\nThis BIP is licensed under the BSD 2-Clause License.
Redistribution and use in source and binary forms, with or without modification, are\npermitted provided that the above copyright notice and this permission notice appear\nin all copies.
Losing the wallet descriptor (or wallet policy) is almost as catastrophic as\nlosing the seed itself. The seed lets you sign, but the descriptor maps you to your coins.\nFor multisig or miniscript wallets, keys alone are insufficient: without the descriptor, you\ncan't reconstruct the script.
\nMultisig setups can be designed to retain access to coins even if one of the\nseeds is lost, for example a 3-of-3 MuSig2 keypath with a script path that lets\n2-of-3 recover. But when one seed is lost, its public key may also be lost,\nrendering the coins inaccessible. This risk is not intuitive.
\nOffline storage of descriptors has two practical obstacles:
\nDescriptors are hard to store offline.
Descriptors can be much longer than a 12/24-word seed. Paper and steel backups\nbecome impractical or error-prone, while USB sticks and other offline digital\nstorage solutions degrade over time and are unlikely to survive flood or fire.
Online redundancy carries privacy risk.
Phones and cloud storage solve the length problem but expose your wallet\nstructure. Plaintext descriptors leak your pubkeys and script details.\nCloud storage is often unencrypted, and even cloud encryption could be compromised,\ndepending on (often opaque) implementation details. Its security also reduces to\nthat of the weakest device with cloud access. Each copy increases the attack surface.
This BIP therefore proposes an encrypted, compact backup format that:
\nSee the original Delving post\nfor more background.
\nThis proposal targets output script descriptors (BIP-0380) and policies (BIP-0388), but the\nscheme also works for labels (BIP-0329) and other wallet metadata like\nwallet backup metadata (BIP-0139).
\nPrivate key material MUST be removed before encrypting any payload.\nThis is because the use of public key material for decryption makes the\nscheme unsuitable for storing private key material.
\nNote: in the following sections, the operator ⊕ refers to the bitwise XOR operation.
\nwhere tagged_hash(tag, m) = sha256(sha256(tag) | sha256(tag) | m) is the tagged\nhash construction from BIP340.
\nBecause $s$ and $s_i$ use distinct domain-separation tags, $s \\neq s_i$ and\ntherefore $c_i$ is never the all-zero string.
\nThe Descriptor key requirements exclude\nkeys exposed by literal or bare-xpub expressions in the backed-up scripts.\nImplementations MUST exclude the key with x coordinate\n50929b74c1a04954b78b4b6035e97a5e078a5a0f28ec96d547bfee9ace803ac0 (the BIP341 NUMS\npoint). Applications MAY exclude any further key they know to be public.
Applications that exclude keys beyond the NUMS point SHOULD document which keys they\nexclude, so that users know which keys cannot open the backup. A cosigner holding an\nexcluded key will simply fail to decrypt, while the cosigners holding the keys that\nremain in ${p_1, \\dots, p_n}$ can still decrypt the backup.
\nNote: A key is publicly known when a third party can learn it without the wallet\nowner disclosing it. There is no registry of such keys. In practice they come from two\nsources: the blockchain, and well-known constants.
\nWarning: An xpub can be known to a third party without ever appearing on chain.\nSome single-signature wallets, such as the Ledger and Trezor desktop apps, send the\nBIP44/49/84/86 account xpub to a server, the server then derive every key from\nthat xpub. For a single-signature descriptor this leaks little the server does not\nalready know, but reusing such an xpub as a key of a multisig descriptor lets that\nserver decrypt every backup of the multisig. Users SHOULD build a multisig from\naccounts whose xpub was never sent to such a server, such as BIP48 or BIP87 accounts.
\nOutside musig(), only key expressions of the extended-public-key type with a\ntrailing derivation step or wildcard contribute to ${p_1, \\dots, p_n}$. Without\nthat derivation, the xpub's root pubkey, used to seed $s$, would also be\nthe on-chain pubkey of every spend, so observing one spend would let\nanyone recompute $s$ and decrypt the backup.[^trailing-derivation] The\nrule generalizes to any network prefix (xpub/tpub/Vpub/...).
[^trailing-derivation]: Why require trailing derivation?\n Any trailing derivation step, or the implicit child derivation forced by\n a wildcard, breaks the identity between the xpub root pubkey and the\n on-chain pubkey. Fixed-derivation expressions like xpub.../0/5 are\n allowed because the on-chain key (xpub/0/5) already differs from the\n encryption seed (the xpub root). Outside musig(), literal pubkeys and\n bare xpubs are disallowed for the same reason: the literal value is exactly\n what goes on-chain, so $s$ would become recoverable from a single observed spend.
Allowed forms (origin information [...] is optional and orthogonal):
| Form | \nExample | \n
|---|---|
<xpub>/<path> (fixed derivation, no wildcard) | \nxpub.../0/5 | \n
<xpub>/* (wildcard only) | \nxpub.../* | \n
<xpub>/<path>/* (fixed derivation followed by a wildcard) | \nxpub.../0/* | \n
<xpub>/<a;b;...> (multipath, no wildcard) | \nxpub.../<0;1> | \n
<xpub>/<a;b;...>/* (multipath followed by a wildcard) | \nxpub.../<0;1>/* | \n
<xpub> (only as a musig() participant) | \nxpub... | \n
Within a BIP390 musig() expression, participant xpubs\nare allowed with or without trailing derivation: the aggregate on-chain key\ndoes not reveal the individual participant keys. For encryption, use each\nparticipant's xpub root rather than the aggregate key. Literal public-key\nparticipants remain excluded.
A candidate root MUST be excluded if its x-coordinate matches a literal key\nor a bare xpub root used outside musig() in any descriptor or resolved\npolicy in the payload. For example,\nwsh(or_i(pk(X/0/*),pk(X))) exposes the root of xpub X on spending, so that\nroot must be excluded even though X/0/* is otherwise eligible.
Implementations:
\nmusig(),\n...) from ${p_1, \\dots, p_n}$.For each allowed expression, take the root extended public key (ignoring\norigin information, the trailing derivation path, the wildcard, and any\nmultipath specifiers) and extract its x-coordinate. The result is the\n32-byte x-only public key $p_i$.[^x-only]
\n[^x-only]: Why x-only keys?\n X-only public keys are 32 bytes, a natural size for cryptographic operations.\n This format is also used in BIP340 (Schnorr signatures) and BIP341 (Taproot).
\nThe format uses CHACHA20_POLY1305 (RFC 8439) as the encryption algorithm,\nwith a 96-bit random nonce and a 128-bit authentication tag to provide confidentiality\nand integrity.[^chacha-default]
\n[^chacha-default]: Why CHACHA20-POLY1305 ?\n ChaCha20-Poly1305 is already used in Bitcoin Core (e.g., BIP324) and is widely\n available in cryptographic libraries. It performs well in software without\n hardware acceleration, making it suitable for hardware wallets and embedded devices.
\nThe additional authenticated data ($aad$) is empty.
\nThe $nonce$ MUST NOT be all zero. If the random source yields an all-zero nonce,\nthe encoder MUST generate a new one.
\nIn order to decrypt the payload of a backup, the owner of a certain public key p\ncomputes:
\nindividual_secret_i generate reconstructed_secret_i =\nindividual_secret_i ⊕ sireconstructed_secret_i process $payload$ =\ndecrypt($ciphertext$, $secret$, $nonce$, $aad$)Decryption will succeed if and only if p was one of the keys in the\ndescriptor/wallet policy.
\nThe encrypted backup must be encoded as follows:
\nMAGIC VERSION DERIVATION_PATHS INDIVIDUAL_SECRETS ENCRYPTION\nENCRYPTED_PAYLOAD
MAGIC: 6 bytes which are ASCII/UTF-8 representation of BIP138.
VERSION: 1 byte unsigned integer representing the format version. The current\nspecification defines version 0x01.
Derivation paths are optional; they can be useful to simplify the recovery process\nif one has used a non-common derivation path to derive his key.[^derivation-optional]
\nAll implementations that can fetch xpubs from a signing device SHOULD try the following\ncommon paths automatically:
\nm/44h/<coin>h/{0..9}hm/49h/<coin>h/{0..9}hm/84h/<coin>h/{0..9}hm/86h/<coin>h/{0..9}hm/87h/<coin>h/{0..9}hm/48h/<coin>h/{0..9}h/1hm/48h/<coin>h/{0..9}h/2h<coin> is the BIP44 coin type of the network being recovered: 0 for mainnet\nand 1 for test networks. {0..9}h covers accounts 0 through 9.
Some signing devices can fail or require confirmation when fetching xpubs for\nsome of these paths. This list is not exhaustive: an implementation MAY treat a\npath as allowed to fail for any device it supports, in particular\nm/87h/<coin>h/{0..9}h, which is widely under-supported. Implementations SHOULD\nat least classify these:[^common-derivation-paths]
m/44h/<coin>h/{0..9}h, m/87h/<coin>h/{0..9}hm/87h/<coin>h/{0..9}hIf fetching an xpub for one of these common paths fails or times out and\ndecryption fails, implementations SHOULD warn the user.
\n[^derivation-optional]: Why are derivation paths optional?\n When standard derivation paths are used, they are easily discoverable, making\n them straightforward to brute-force. Omitting them enhances privacy by reducing\n the information shared publicly about the descriptor scheme.
\n[^common-derivation-paths]: Why this restricted list?\n The list covers common account paths for the network being recovered, accounts 0\n through 9. Some signing devices reject or display some of these paths before\n exporting an xpub, so implementations should treat the listed paths for that\n device as optional rather than aborting recovery.
\nDERIVATION_PATH follows this format:
COUNTCHILD_COUNT CHILD ... CHILD...CHILD_COUNT CHILD ... CHILD
COUNT: 1-byte unsigned integer (0–255) indicating how many derivation paths are\nincluded.CHILD_COUNT: 1-byte unsigned integer (1–255) indicating how many children are in\nthe current path.CHILD: 4-byte big-endian unsigned integer representing a child index per BIP-32.
The derivation-path vector SHOULD be encoded in lexicographic order. This avoids\nleaking information through implementation-specific ordering. The vector SHOULD NOT\ncontain duplicates. Implementations SHOULD deduplicate paths during encoding or\nparsing.
\nAt least one individual secret must be supplied.[^no-fingerprints]
\n[^no-fingerprints]: Why no fingerprints in plaintext encoding?\n Including fingerprints would leak direct information about the descriptor\n participants, which compromises privacy.
\nThe INDIVIDUAL_SECRETS section follows this format:
COUNTINDIVIDUAL_SECRETINDIVIDUAL_SECRET
COUNT: 1-byte unsigned integer (1–255) indicating how many secrets are included.INDIVIDUAL_SECRET: 32-byte serialization of the derived individual secret.
The individual secrets vector SHOULD be encoded in lexicographic order. This avoids\nleaking information through implementation-specific ordering. The vector SHOULD NOT\ncontain duplicates. Implementations SHOULD deduplicate secrets during encoding or\nparsing.
\nEncoders SHOULD append random decoy INDIVIDUAL_SECRET entries to hide the exact\nnumber of real decryption keys. The total count SHOULD be rounded up to the\nsmallest bucket greater than or equal to the real count, starting at 5 and doubling\nfor each following bucket: 5, 10, 20, and so on. The bucket sequence saturates at\nthe 255 COUNT limit: when the smallest fitting bucket would exceed 255, encoders\nSHOULD pad to 255 instead. Decoders do not distinguish real\nentries from decoys; they try each entry until one decrypts the payload.
ENCRYPTION: 1-byte unsigned integer identifying the encryption algorithm.
| Value | \nDefinition | \n
|---|---|
| 0x00 | \nReserved | \n
| 0x01 | \nCHACHA20_POLY1305 | \n
CHACHA20_POLY1305 (per RFC 8439) supports plaintext up to 2^38 - 64 bytes.\nImplementations MAY impose stricter limits based on platform constraints\n(e.g., limiting to 2^32 - 1 bytes on 32-bit architectures).
\nImplementations MUST reject empty payloads (i.e. zero content items).
\nCIPHERTEXT is the encrypted data resulting from encryption of PAYLOAD with algorithm\ndefined in ENCRYPTION where PAYLOAD is encoded following this format:
CONTENT_TYPE CONTENT_LENGTH CONTENT (CONTENT_TYPE CONTENT_LENGTH CONTENT ...) (PADDING)
CONTENT_LENGTH: variable-length integer representing the length of CONTENT in bytes.\nIt MUST be present.
CONTENT: the CONTENT_LENGTH bytes of payload data.
PADDING: OPTIONAL bytes after the final CONTENT, up to the end of the decrypted\nPAYLOAD. Parsers MUST consume exactly CONTENT_LENGTH bytes of each CONTENT. The padding\nbytes are reserved for size padding (see Padding) and/or vendor-specific data, the same\nway trailing bytes after CIPHERTEXT are reserved and ignored.
Backups that are updated over time can leak information through their size even when the\ncontents are encrypted. A wallet that uploads a new backup after every received transaction\ncan reveal activity to the storage provider through changing payload sizes. This is relevant\nfor mutable payloads such as BIP-329 or BIP-0139.[^padding-privacy]
\nPadding is OPTIONAL and is an encoder concern only: decoders ignore the PADDING bytes and\nMUST NOT validate any bucket. Because the padding sits inside CIPHERTEXT, the\nENCRYPTED_PAYLOAD LENGTH reveals only the padded size, not the real PAYLOAD size.
Encoders that pad SHOULD zero-fill PAYLOAD up to the smallest bucket S_n that fits it,\nwith S_0 = 10240 (10 KiB) and S_n = floor(S_0 * (5 / 4)^n). Payloads of 10 KiB or less\nare padded to 10 KiB. This keeps padding overhead under 25% above the smallest fitting bucket\nwhile coarsening the observable size. Padding is RECOMMENDED for mutable payloads and\nunnecessary for static ones such as BIP-380 descriptors and BIP-388 wallet policies.
[^padding-privacy]: Why pad inside the ciphertext?\n Padding the encrypted payload, rather than appending bytes after the backup, hides the\n real payload size from anyone who parses the backup, not just from someone who measures\n the file size. The size field a parser sees is the padded ENCRYPTED_PAYLOAD LENGTH.
All variable-length integers are encoded as\ncompact size.
\nCONTENT_TYPE is a variable length field defining the type of the CONTENT that follows\nit. It follows this format:
TYPE (TYPE_LENGTH) TYPE_PARAMS
A PAYLOAD carries one or more CONTENT_TYPE CONTENT_LENGTH CONTENT items, each CONTENT_TYPE\ndescribing the CONTENT immediately following it. The sequence ends at the first\nTYPE byte equal to 0x00, or at the end of the PAYLOAD, whichever comes first; all\nremaining bytes are PADDING. A PAYLOAD MUST contain at least one item (see\nPayload Size Limits).
TYPE: 1-byte unsigned integer identifying how to interpret TYPE_PARAMS.
| Value | \nDefinition | \n
|---|---|
| 0x00 | \nEnd of content items; padding follows | \n
| 0x01 | \nBIP Number (big-endian uint16) | \n
| 0x02 | \nVendor-Specific Opaque Tag | \n
| 0x03 | \nString | \n
TYPE_LENGTH: variable-length integer representing the length of TYPE_PARAMS in bytes.
For all TYPE values except 0x00 and 0x01, TYPE_LENGTH MUST be present.[^length-required]
[^length-required]: Why is TYPE_LENGTH mandatory?\n TYPE_LENGTH is what lets a parser skip a content type it does not implement and still\n read the items that follow; without it, the parser cannot know where TYPE_PARAMS ends.\n A string note placed before a descriptor, for example, must not stop an\n implementation that only handles descriptors from recovering that descriptor. A\n type whose TYPE_PARAMS is always empty still carries a zero TYPE_LENGTH for this reason.\n 0x01 is exempt because every implementation handles it, so it is never skipped\n blindly. 0x00 is a terminator rather than a content item.
TYPE_PARAMS: variable-length field whose encoding depends on TYPE.
For TYPE values defined above:
TYPE_LENGTH MUST be omitted and TYPE_PARAMS is a 2-byte big-endian unsigned integer\nrepresenting the BIP number that defines it.TYPE_PARAMS MUST be TYPE_LENGTH bytes of opaque, vendor-specific data.TYPE_PARAMS MUST be empty, and the following CONTENT is the string itself,\nwhich MUST be valid UTF-8.For all TYPE values except 0x00 and 0x01, parsers MUST reject CONTENT_TYPE if TYPE_LENGTH exceeds\nthe remaining payload bytes.
For an unknown TYPE less than 0x80, parsers MUST consume its TYPE_LENGTH bytes of\nTYPE_PARAMS, treat the content type as unknown, consume the following payload\nCONTENT_LENGTH and CONTENT, and continue with the next item.
For an unknown TYPE greater than or equal to 0x80, parsers MUST reject the\npayload.[^type-upgrade]
[^type-upgrade]: Why the 0x80 threshold?\n The TYPE >= 0x80 rule keeps the encoding upgradeable. A future version can\n define a new content type at or above 0x80 that older parsers reject rather\n than misread, while types below 0x80 stay backward compatible.
When CONTENT_TYPE is TYPE = 0x01 with TYPE_PARAMS = 0x017c (BIP380), CONTENT is a\nUTF-8 BIP380 descriptor backup. It is either a single bare descriptor string, or\na JSON descriptor backup document (for several descriptors) when the first\ncharacter is {.
Test vectors are in\nbip380_descriptor_backup.json.
Descriptor strings MUST NOT contain private key material and SHOULD include a\nchecksum.
\nThe descriptor backup document is a JSON object with the following fields:
\nversion: integer. This specification defines version 1.descriptor_sets: array of descriptor set objects.Each descriptor set describes BIP380 output script descriptors belonging to one\nlogical account or script family.
\ndescriptor is a required string containing a BIP380 output script descriptor.
For BIP389 multipath descriptors, /<0;1> means receive and change,\nrespectively. The change_descriptor field MUST NOT be used.
For descriptors without BIP389 multipath key expressions, descriptor is the\nreceive descriptor. The optional change_descriptor string can be omitted for a\nreceive-only set.
If optional boolean archived is true, importing wallets SHOULD NOT use the\ndescriptor set for new address generation.
range is an optional two-element array [start, end], inclusive, describing\nthe BIP32 non-hardened child indexes covered by the\ndescriptor set, with start <= end.
birth_time is an optional integer Unix timestamp in seconds, indicating a\nlower bound for when the descriptor set may have received funds. Importing\nwallets MAY use this value as a scanning hint.\nIf 0 or omitted, no lower bound is known. Importers SHOULD scan from the wallet\nbirthday if known, otherwise from genesis.
When CONTENT_TYPE is TYPE = 0x01 with TYPE_PARAMS = 0x0184 (BIP388), CONTENT is a\nUTF-8 JSON wallet policy backup document. A BIP388 wallet policy is a descriptor\ntemplate plus a vector of key information items, as defined in BIP388.
Test vectors are in\nbip388.json.
The document is one of two forms:
\n{ "keys": [...], "policy": "<template>" }.{ "version": 1, "policy_sets": [...] }.Parsers select the form by structure: an object with a policy_sets field is the\nmultiple form, an object with a policy field is the single form.
keys is a required array of BIP388 key information items, each a serialized\nextended public key with optional key origin ([fingerprint/path]xpub). It MUST\ncontain at least one key. Keys MUST NOT contain private key material.
policy is a required non-empty string containing a BIP388 wallet descriptor\ntemplate, with @i key placeholders referring to keys.
A policy set has the same keys and policy fields as the single form, plus the\noptional metadata fields:
If optional boolean archived is true, importing wallets SHOULD NOT use the\npolicy for new address generation.
range is an optional two-element array [start, end], inclusive, describing\nthe BIP32 non-hardened child indexes covered by the\npolicy, with start <= end.
birth_time is an optional integer Unix timestamp in seconds, indicating a lower\nbound for when the policy may have received funds. Importing wallets MAY use this\nvalue as a scanning hint.\nIf 0 or omitted, no lower bound is known. Importers SHOULD scan from the wallet\nbirthday if known, otherwise from genesis.
The multiple form is a JSON object with the following fields:
\nversion: integer. This specification defines version 1.policy_sets: array of policy set objects.ENCRYPTED_PAYLOAD follows this format:
NONCE LENGTH CIPHERTEXT
NONCE: 12-byte (96-bit) nonce. Parsers MUST reject a backup whose NONCE is all zero.\nLENGTH: variable-length integer representing ciphertext length.\nCIPHERTEXT: variable-length ciphertext.
Note: CIPHERTEXT is followed by the end of the ENCRYPTED_PAYLOAD section.
Compliant parsers MUST stop reading after consuming LENGTH bytes of ciphertext;\nadditional trailing bytes are reserved for vendor-specific extensions and MUST\nbe ignored.
Implementations SHOULD encode and decode the backup using Base64 (RFC 4648).[^psbt-base64]
\n[^psbt-base64]: Why Base64?\n PSBT (BIP174) is commonly exchanged as a Base64 string, so wallet software\n likely already supports this representation.
\nBackups saved to a file SHOULD use the .bip138 file extension for the raw binary\nencoding and the .txt extension for the Base64 text representation, so that the\nextension tells implementations which encoding to expect.
See footnotes throughout the specification for design rationale.
\nThe version field enables possible future enhancements:
\nrecipient_keys.json contains\ntest vectors for recipient selection. descriptors lists the payload's descriptor\nstrings; expected_keys lists the sorted, deduplicated x-only recipient roots\nbefore application-specific exclusions. null requires refusing to encode.
content_type.json contains test\nvectors for content types serialisations.
payload.json contains test vectors for payload parsing.\npayload and each item's content are hexadecimal bytes; type is the numeric\ntype byte, and items lists the content items before the terminator.
derivation_path.json contains\ntest vectors for derivation paths serialisations.
individual_secrets.json\ncontains test vectors for individual secrets serialization.
encryption_secret.json\ncontains test vectors for generation of encryption secret.
chacha20poly1305_encryption.json\ncontains test vectors for ciphertexts generated using CHACHA20-POLY1305.\nencrypted_backup.json\ncontains test vectors for generation of complete encrypted backups, including\nBIP380 and BIP388 content, a multi-content payload, and an all-zero-nonce backup\nthat parsers MUST reject.
bip380_descriptor_backup.json\ncontains test vectors for BIP380 descriptor backup documents.
bip388.json\ncontains test vectors for BIP388 wallet policy backup documents.
This BIP defines a new format and changes no existing one. Liana wallet uses an early\nversion of this BIP, which is not compatible: its magic is BEB rather than BIP138.
This BIP builds on the backup scheme proposed by @bigspider on\nDelving Bitcoin,\nwho also suggested the payload padding design.
\nThanks to @Sjors for extensive reviews, many design contributions to the payload\nencoding, and a proof-of-concept implementation on top of Bitcoin Core. Thanks\nalso to @murchandamus, @jonatack, @craigraw, @jp1ac4, and @torkelrogstad for\ntheir reviews and suggestions.
\n0x00 ends payload parsing and add test vectors.