From 9e2a585a9ad2bc01d1114725f822953e1ae1ed81 Mon Sep 17 00:00:00 2001
From: pythcoiner <pythcoiner@proton.me>
Date: Thu, 18 Jun 2026 03:44:25 -0400
Subject: [PATCH] bip-138: specify BIP380 descriptor backup content

---
 bip-0138.md                                   | 56 +++++++++++++++++++
 .../bip380_descriptor_backup.json             | 33 +++++++++++
 .../test_vectors/bip380_descriptor_backup.txt |  2 +
 3 files changed, 91 insertions(+)
 create mode 100644 bip-0138/test_vectors/bip380_descriptor_backup.json
 create mode 100644 bip-0138/test_vectors/bip380_descriptor_backup.txt

diff --git a/bip-0138.md b/bip-0138.md
index b88356b5..fc2d2872 100644
--- a/bip-0138.md
+++ b/bip-0138.md
@@ -351,6 +351,59 @@ payload.[^type-upgrade]
     define a new content type at or above `0x80` that older parsers reject rather
     than misread, while types below `0x80` stay backward compatible.
 
+#### BIP380 Descriptor Backup Content
+
+When `CONTENT` is `TYPE = 0x01` with `DATA = 0x017c` (BIP380), `PLAINTEXT`
+is UTF-8 encoded BIP380 descriptor backup content. It is either:
+
+- A text descriptor backup document.
+- A JSON descriptor backup document, if the first character is `{`.
+
+Test vectors are in
+[`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).
+
+Descriptor strings MUST NOT contain private key material and SHOULD include a
+checksum.
+
+##### Text Descriptor Backup Documents
+
+A text descriptor backup document contains one BIP380 output script descriptor
+per line. Empty lines and lines starting with `#` MUST be ignored. Each
+descriptor MUST use BIP389 multipath key expressions, where `/<0;1>` means
+receive and change, respectively.
+
+##### JSON Descriptor Backup Documents
+
+The descriptor backup document is a JSON object with the following fields:
+
+- `version`: integer. This specification defines version `1`.
+- `descriptor_sets`: array of descriptor set objects.
+
+Each descriptor set describes BIP380 output script descriptors belonging to one
+logical account or script family.
+
+##### Descriptor Set Fields
+
+`descriptor` is a required string containing a BIP380 output script descriptor.
+
+For BIP389 multipath descriptors, `/<0;1>` means receive and change,
+respectively. The `change_descriptor` field MUST NOT be used.
+
+For descriptors without BIP389 multipath key expressions, `descriptor` is the
+receive descriptor and `change_descriptor` is the change descriptor.
+
+If optional boolean `archived` is `true`, importing wallets SHOULD NOT use the
+descriptor set for new address generation.
+
+`range` is an optional two-element array `[start, end]`, inclusive, describing
+the ranged derivation indexes covered by the descriptor set.
+
+`birth_time` is an optional integer Unix timestamp in seconds, indicating a
+lower bound for when the descriptor set may have received funds. Importing
+wallets MAY use this value as a scanning hint.
+
 #### Encrypted Payload
 
 `ENCRYPTED_PAYLOAD` follows this format:
@@ -407,6 +460,9 @@ contains test vectors for generation of encryption secret.
 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.  
+[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.  
 
 ## Acknowledgements
 
diff --git a/bip-0138/test_vectors/bip380_descriptor_backup.json b/bip-0138/test_vectors/bip380_descriptor_backup.json
new file mode 100644
index 00000000..719d0e11
--- /dev/null
+++ b/bip-0138/test_vectors/bip380_descriptor_backup.json
@@ -0,0 +1,33 @@
+[
+  {
+    "description": "Descriptor with change descriptor",
+    "valid": true,
+    "document": {
+      "version": 1,
+      "descriptor_sets": [
+        {
+          "archived": false,
+          "birth_time": 1710000000,
+          "range": [0, 999],
+          "descriptor": "wpkh([d34db33f/84h/1h/0h]tpubDC5FSnBiZDMmhiuCmWAYsLwgLYrrT9rAqvTySfuCCrgsWz8wxMXUS9Tb9iVMvcRbvFcAHGkMD5Kx8koh4GquNGNTfohfk7pgjhaPCdXpoba/0/*)",
+          "change_descriptor": "wpkh([d34db33f/84h/1h/0h]tpubDC5FSnBiZDMmhiuCmWAYsLwgLYrrT9rAqvTySfuCCrgsWz8wxMXUS9Tb9iVMvcRbvFcAHGkMD5Kx8koh4GquNGNTfohfk7pgjhaPCdXpoba/1/*)"
+        }
+      ]
+    }
+  },
+  {
+    "description": "BIP389 multipath descriptor",
+    "valid": true,
+    "document": {
+      "version": 1,
+      "descriptor_sets": [
+        {
+          "archived": false,
+          "birth_time": 1710000000,
+          "range": [0, 999],
+          "descriptor": "wpkh([d34db33f/84h/1h/0h]tpubDC5FSnBiZDMmhiuCmWAYsLwgLYrrT9rAqvTySfuCCrgsWz8wxMXUS9Tb9iVMvcRbvFcAHGkMD5Kx8koh4GquNGNTfohfk7pgjhaPCdXpoba/<0;1>/*)"
+        }
+      ]
+    }
+  }
+]
diff --git a/bip-0138/test_vectors/bip380_descriptor_backup.txt b/bip-0138/test_vectors/bip380_descriptor_backup.txt
new file mode 100644
index 00000000..4ce5adaa
--- /dev/null
+++ b/bip-0138/test_vectors/bip380_descriptor_backup.txt
@@ -0,0 +1,2 @@
+# BIP380 descriptor backup text vector
+wpkh([d34db33f/84h/1h/0h]tpubDC5FSnBiZDMmhiuCmWAYsLwgLYrrT9rAqvTySfuCCrgsWz8wxMXUS9Tb9iVMvcRbvFcAHGkMD5Kx8koh4GquNGNTfohfk7pgjhaPCdXpoba/<0;1>/*)