bip-138: specify BIP388 wallet policy backup content

2026-10-19 19:29:18 +00:00 · 2026-06-18 04:38:58 -04:00
parent 9e2a585a9a
commit 810b4df73e
3 changed files with 161 additions and 1 deletions
--- a/bip-0138.md
+++ b/bip-0138.md
@@ -404,6 +404,54 @@ the ranged derivation indexes covered by the descriptor set.
 lower bound for when the descriptor set may have received funds. Importing
 wallets MAY use this value as a scanning hint.

+#### BIP388 Wallet Policy Backup Content
+
+When `CONTENT` is `TYPE = 0x01` with `DATA = 0x0184` (BIP388), `PLAINTEXT` is a
+UTF-8 JSON wallet policy backup document. A BIP388 wallet policy is a descriptor
+template plus a vector of key information items, as defined in BIP388.
+
+Test vectors are in
+[`bip388.json`](./bip-0138/test_vectors/bip388.json).
+
+The document is one of two forms:
+
+- A single policy, a JSON object `{ "keys": [...], "policy": "<template>" }`.
+- Multiple policies, a JSON object `{ "version": 1, "policy_sets": [...] }`.
+
+Parsers select the form by structure: an object with a `policy_sets` field is the
+multiple form, an object with a `policy` field is the single form.
+
+##### Policy Fields
+
+`keys` is a required array of BIP388 key information items, each a serialized
+extended public key with optional key origin (`[fingerprint/path]xpub`). It MUST
+contain at least one key. Keys MUST NOT contain private key material.
+
+`policy` is a required non-empty string containing a BIP388 wallet descriptor
+template, with `@i` key placeholders referring to `keys`.
+
+##### Policy Set Fields
+
+A policy set has the same `keys` and `policy` fields as the single form, plus the
+optional metadata fields:
+
+If optional boolean `archived` is `true`, importing wallets SHOULD NOT use the
+policy for new address generation.
+
+`range` is an optional two-element array `[start, end]`, inclusive, describing the
+ranged derivation indexes covered by the policy.
+
+`birth_time` is an optional integer Unix timestamp in seconds, indicating a lower
+bound for when the policy may have received funds. Importing wallets MAY use this
+value as a scanning hint.
+
+##### Multiple Policies Document
+
+The multiple form is a JSON object with the following fields:
+
+- `version`: integer. This specification defines version `1`.
+- `policy_sets`: array of policy set objects.
+
 #### Encrypted Payload

 `ENCRYPTED_PAYLOAD` follows this format:
@@ -459,10 +507,13 @@ contains test vectors for generation of encryption secret.
 [chacha20poly1305_encryption.json](./bip-0138/test_vectors/chacha20poly1305_encryption.json)
 contains test vectors for ciphertexts generated using CHACHA20-POLY1305.
 [encrypted_backup.json](./bip-0138/test_vectors/encrypted_backup.json)
-contains test vectors for generation of complete encrypted backup.  
+contains test vectors for generation of complete encrypted backups, including
+BIP380 and BIP388 content.  
 [bip380_descriptor_backup.txt](./bip-0138/test_vectors/bip380_descriptor_backup.txt)
 and [bip380_descriptor_backup.json](./bip-0138/test_vectors/bip380_descriptor_backup.json)
 contain test vectors for BIP380 descriptor backup documents.  
+[bip388.json](./bip-0138/test_vectors/bip388.json)
+contains test vectors for BIP388 wallet policy backup documents.  

 ## Acknowledgements

--- a/bip-0138/test_vectors/bip388.json
+++ b/bip-0138/test_vectors/bip388.json
@@ -0,0 +1,92 @@
+[
+  {
+    "description": "single pkh policy",
+    "valid": true,
+    "document": {
+      "keys": [
+        "[d34db33f/44'/0'/0']xpub6ERApfZwUNrhLCkDtcHTcxd75RbzS1ed54G1LkBUHQVHQKqhMkhgbmJbZRkrgZw4koxb5JaHWkY4ALHY2grBGRjaDMzQLcgJvLJuZZvRcEL"
+      ],
+      "policy": "pkh(@0/**)"
+    }
+  },
+  {
+    "description": "multiple policy sets with metadata",
+    "valid": true,
+    "document": {
+      "version": 1,
+      "policy_sets": [
+        {
+          "keys": [
+            "[6738736c/48'/0'/0'/2']xpub6FC1fXFP1GXLX5TKtcjHGT4q89SDRehkQLtbKJ2PzWcvbBHtyDsJPLtpLtkGqYNYZdVVAjRQ5kug9CsapegmmeRutpP7PW4u4wVF9JfkDhw",
+            "[b2b1f0cf/48'/0'/0'/2']xpub6EWhjpPa6FqrcaPBuGBZRJVjzGJ1ZsMygRF26RwN932Vfkn1gyCiTbECVitBjRCkexEvetLdiqzTcYimmzYxyR1BZ79KNevgt61PDcukmC7"
+          ],
+          "policy": "wsh(sortedmulti(2,@0/**,@1/**))",
+          "archived": true,
+          "range": [
+            0,
+            999
+          ],
+          "birth_time": 1710000000
+        },
+        {
+          "keys": [
+            "[d34db33f/44'/0'/0']xpub6ERApfZwUNrhLCkDtcHTcxd75RbzS1ed54G1LkBUHQVHQKqhMkhgbmJbZRkrgZw4koxb5JaHWkY4ALHY2grBGRjaDMzQLcgJvLJuZZvRcEL"
+          ],
+          "policy": "pkh(@0/**)"
+        }
+      ]
+    }
+  },
+  {
+    "description": "version not one",
+    "valid": false,
+    "document": {
+      "version": 2,
+      "policy_sets": [
+        {
+          "keys": [
+            "[d34db33f/44'/0'/0']xpub6ERApfZwUNrhLCkDtcHTcxd75RbzS1ed54G1LkBUHQVHQKqhMkhgbmJbZRkrgZw4koxb5JaHWkY4ALHY2grBGRjaDMzQLcgJvLJuZZvRcEL"
+          ],
+          "policy": "pkh(@0/**)"
+        }
+      ]
+    }
+  },
+  {
+    "description": "missing policy",
+    "valid": false,
+    "document": {
+      "keys": [
+        "[d34db33f/44'/0'/0']xpub6ERApfZwUNrhLCkDtcHTcxd75RbzS1ed54G1LkBUHQVHQKqhMkhgbmJbZRkrgZw4koxb5JaHWkY4ALHY2grBGRjaDMzQLcgJvLJuZZvRcEL"
+      ]
+    }
+  },
+  {
+    "description": "empty policy",
+    "valid": false,
+    "document": {
+      "keys": [
+        "[d34db33f/44'/0'/0']xpub6ERApfZwUNrhLCkDtcHTcxd75RbzS1ed54G1LkBUHQVHQKqhMkhgbmJbZRkrgZw4koxb5JaHWkY4ALHY2grBGRjaDMzQLcgJvLJuZZvRcEL"
+      ],
+      "policy": ""
+    }
+  },
+  {
+    "description": "empty keys",
+    "valid": false,
+    "document": {
+      "keys": [],
+      "policy": "pkh(@0/**)"
+    }
+  },
+  {
+    "description": "single literal pubkey in keys",
+    "valid": false,
+    "document": {
+      "keys": [
+        "0279be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798"
+      ],
+      "policy": "pkh(@0/**)"
+    }
+  }
+]
--- a/bip-0138/test_vectors/encrypted_backup.json
+++ b/bip-0138/test_vectors/encrypted_backup.json
@@ -63,5 +63,22 @@
    "nonce": "000102030405060708090a0b",
    "expected": "424950313338010001c14d5bfeb7f9709e996c6696959107d4c57d367d2aee207d5361f116e3c4708b01000102030405060708090a0b2988e0747028c10af011cba311ebabb3a094366a96ad747cd8e3edfc1474b356c2393e13ee9c5cd0aae5",
    "expected_base64": "QklQMTM4AQABwU1b/rf5cJ6ZbGaWlZEH1MV9Nn0q7iB9U2HxFuPEcIsBAAECAwQFBgcICQoLKYjgdHAowQrwEcujEeurs6CUNmqWrXR82OPt/BR0s1bCOT4T7pxc0Krl"
+  },
+  {
+    "description": "Two keys, BIP388 wallet policy content (multisig)",
+    "version": 1,
+    "encryption": 1,
+    "content": "010184",
+    "keys": [
+      "02ee3887104834ec2970bb793abc7fd37661e2c44c49fb48c10745ef7d7c85b17c",
+      "036f155ae2153b09bb4e1383756723c0879e80d0f32767c7e4875d5de2fb9a400d"
+    ],
+    "derivation_paths": [
+      "m/48'/0'/0'/2'"
+    ],
+    "plaintext": "{\"keys\":[\"[6738736c/48'/0'/0'/2']xpub6FC1fXFP1GXLX5TKtcjHGT4q89SDRehkQLtbKJ2PzWcvbBHtyDsJPLtpLtkGqYNYZdVVAjRQ5kug9CsapegmmeRutpP7PW4u4wVF9JfkDhw\",\"[b2b1f0cf/48'/0'/0'/2']xpub6EWhjpPa6FqrcaPBuGBZRJVjzGJ1ZsMygRF26RwN932Vfkn1gyCiTbECVitBjRCkexEvetLdiqzTcYimmzYxyR1BZ79KNevgt61PDcukmC7\"],\"policy\":\"wsh(sortedmulti(2,@0/**,@1/**))\"}",
+    "nonce": "000000000000000000000388",
+    "expected": "424950313338010104800000308000000080000000800000020263f5769bbb36d77fc5d3251700590c087013ca44284850e88f379f2519190f97e5b4cabf8bdb9a04a92fc3e104dd2d8a2cb8e5ea886e143236dd4b04619e796d01000000000000000000000388fd5d011def7dae872431f1fa0df78989f7e5087cd0cb112a69bc211d3346b1031c5d1e8702197712ac46597e05d80421fda7e60d09f3ba2178bd770c904bf840d3d779565fbd0668a989934483820c4c828f32ffe5fc1ce55bbfe287a6d4eb4461e4da1b6a6f22cc0932773c84f07d879b1ed8035831e2a358101be023ea2efb7c70411f757c42715f4e5f7eff416a456a5dadf1b980480e22a7b66726ebc84afe04acdfbf47c6b41c2bb39c5a069a93dba0de4ea9bc192f938f968c9fa2afc26025dd577461b73bad0870e97d7519945ced9d73500c7ece85696d98f223350cd6a337cb74feeeea8d5144ee94553dc54a46e43f67fa48f11c7746e006aac4478fa0c484f041be451548152a1f11f632a9d966de62e3cd80ed9885117e5901042974c80d3f95a13c1cfe2157f2bfb80bea7b3bc0a71127d8daa6a75d3cc517ef934dd9af4b504600c5ce223ba9538c9bc0472aa3832571b1486e2f51b40a5351",
+    "expected_base64": "QklQMTM4AQEEgAAAMIAAAACAAAAAgAAAAgJj9XabuzbXf8XTJRcAWQwIcBPKRChIUOiPN58lGRkPl+W0yr+L25oEqS/D4QTdLYosuOXqiG4UMjbdSwRhnnltAQAAAAAAAAAAAAADiP1dAR3vfa6HJDHx+g33iYn35Qh80MsRKmm8IR0zRrEDHF0ehwIZdxKsRll+BdgEIf2n5g0J87oheL13DJBL+EDT13lWX70GaKmJk0SDggxMgo8y/+X8HOVbv+KHptTrRGHk2htqbyLMCTJ3PITwfYebHtgDWDHio1gQG+Aj6i77fHBBH3V8QnFfTl9+/0FqRWpdrfG5gEgOIqe2ZybryEr+BKzfv0fGtBwrs5xaBpqT26DeTqm8GS+Tj5aMn6KvwmAl3Vd0Ybc7rQhw6X11GZRc7Z1zUAx+zoVpbZjyIzUM1qM3y3T+7uqNUUTulFU9xUpG5D9n+kjxHHdG4AaqxEePoMSE8EG+RRVIFSofEfYyqdlm3mLjzYDtmIURflkBBCl0yA0/laE8HP4hV/K/uAvqezvApxEn2Nqmp108xRfvk03Zr0tQRgDFziI7qVOMm8BHKqODJXGxSG4vUbQKU1E="
  }
 ]