[ZIP 248]: Change bundle identifiers to (bundleType, bundleVersion) tuples.

nuttycom · claude · nuttycom · commit 68f3ef9a35d3 · 2026-03-05T19:19:00.000-07:00
This makes the mutual exclusivity of bundle variants (e.g. Orchard vs
OrchardZSA) implicit in the map structure, and allows clients that do
not recognize a specific bundleVersion to still identify which pool
is affected.

Co-Authored-By: Claude Opus 4.6 &lt;noreply@anthropic.com&gt;
diff --git a/zips/zip-0226.rst b/zips/zip-0226.rst
@@ -371,14 +371,21 @@ The ZSA-related changes in v6 include:
 Changes to ZIP 248
 ``````````````````
 
-This ZIP proposes to register the OrchardZSA bundle type in the V6 transaction
-bundle type registry defined in ZIP 248 [#zip-0248]_:
-
-+------------+----------------------+--------------------+------------------+-------------+
-| BundleType | ``mValuePoolDeltas`` | ``mEffectBundles`` | ``mAuthBundles`` | Bundle kind |
-+============+======================+====================+==================+=============+
-| TBD        |✅                    |✅                  |✅                | OrchardZSA  |
-+------------+----------------------+--------------------+------------------+-------------+
+This ZIP proposes to register a new version of the Orchard bundle type
+(``bundleType`` 3) in the V6 transaction bundle type registry defined in
+ZIP 248 [#zip-0248]_:
+
++------------+---------------+----------------------+--------------------+------------------+-------------+
+| BundleType | BundleVersion | ``mValuePoolDeltas`` | ``mEffectBundles`` | ``mAuthBundles`` | Bundle kind |
++============+===============+======================+====================+==================+=============+
+| 3          | TBD           |✅                    |✅                  |✅                | OrchardZSA  |
++------------+---------------+----------------------+--------------------+------------------+-------------+
+
+Because this is a new version of the Orchard bundle type rather than a new
+bundle type, a transaction that includes an OrchardZSA bundle cannot also
+include an Orchard or Orchard-post-ZIP-231 bundle. This constraint is enforced
+by the ZIP 248 requirement that each bundle map is keyed by ``bundleType``
+alone.
 
 OrchardZSA Effecting Data
 '''''''''''''''''''''''''
@@ -543,9 +550,11 @@ The OrchardZSA bundle has value pool deltas (transfers move value in and out of
 the transparent transaction value pool), effecting data (the OrchardZSA actions
 and burn information), and authorizing data (the proofs and binding signature).
 
-A transaction MUST NOT contain both an Orchard bundle (type 3) and an OrchardZSA
-bundle. The OrchardZSA bundle replaces the Orchard bundle for transactions that
-transfer Custom Assets.
+Because OrchardZSA is registered as a new version of ``bundleType`` 3
+(Orchard), a transaction cannot contain both an Orchard bundle and an
+OrchardZSA bundle; this is enforced by the ZIP 248 constraint that each bundle
+map is keyed by ``bundleType`` alone. The OrchardZSA bundle version replaces
+the Orchard bundle version for transactions that transfer Custom Assets.
 
 Implications for Wallets
 ````````````````````````
diff --git a/zips/zip-0227.rst b/zips/zip-0227.rst
@@ -371,17 +371,17 @@ The issuance bundle is added within the transaction format as a new bundle.
 The encoding of the issuance bundle's effecting and authorizing data is
 defined in `Changes to ZIP 248`_ below.
 
-This ZIP proposes to register the ZSA Issuance bundle type in the V6
+This ZIP proposes to register a new bundle type for ZSA Issuance in the V6
 transaction bundle type registry defined in ZIP 248 [#zip-0248]_:
 
 Changes to ZIP 248
 ``````````````````
 
-+------------+----------------------+--------------------+------------------+--------------+
-| BundleType | ``mValuePoolDeltas`` | ``mEffectBundles`` | ``mAuthBundles`` | Bundle kind  |
-+============+======================+====================+==================+==============+
-| TBD        |✅                    |✅                  |✅                | ZSA Issuance |
-+------------+----------------------+--------------------+------------------+--------------+
++------------+---------------+----------------------+--------------------+------------------+--------------+
+| BundleType | BundleVersion | ``mValuePoolDeltas`` | ``mEffectBundles`` | ``mAuthBundles`` | Bundle kind  |
++============+===============+======================+====================+==================+==============+
+| TBD        | 0             |✅                    |✅                  |✅                | ZSA Issuance |
++------------+---------------+----------------------+--------------------+------------------+--------------+
 
 The ZSA Issuance bundle has value pool deltas (issuance adds value to the
 transparent transaction value pool for Custom Assets), effecting data (the
diff --git a/zips/zip-0231.md b/zips/zip-0231.md
@@ -145,28 +145,33 @@ to both Sapling and Orchard outputs.
 
 ## Changes to ZIP 248
 
-This ZIP proposes to register the following bundle types in the V6 transaction
-bundle type registry defined in ZIP 248 [^zip-0248]:
+This ZIP proposes to register a new bundle type for Memos and new versions of
+the Sapling and Orchard bundle types in the V6 transaction bundle type registry
+defined in ZIP 248 [^zip-0248]:
 
-| BundleType | `mValuePoolDeltas` | `mEffectBundles` | `mAuthBundles` | Bundle kind          |
-|------------|--------------------| -----------------|----------------|----------------------|
-| TBD        |❌                  |✅                |❌              | Memos                |
-| TBD        |✅                  |✅                |✅              | Sapling-post-ZIP 231 |
-| TBD        |✅                  |✅                |✅              | Orchard-post-ZIP 231 |
+| BundleType | BundleVersion | `mValuePoolDeltas` | `mEffectBundles` | `mAuthBundles` | Bundle kind          |
+|------------|---------------|--------------------|------------------|----------------|----------------------|
+| TBD        | 0             |❌                  |✅                |❌              | Memos                |
+| 2          | TBD           |✅                  |✅                |✅              | Sapling-post-ZIP 231 |
+| 3          | TBD           |✅                  |✅                |✅              | Orchard-post-ZIP 231 |
 
 The Memos bundle has no value pool deltas (memo data does not involve value
 transfers) and no authorizing data. The effecting data consists of the encoded
 memo bundle as defined in [Encoding in transactions].
 
+The Sapling-post-ZIP 231 and Orchard-post-ZIP 231 entries are new versions of
+the existing Sapling (``bundleType`` 2) and Orchard (``bundleType`` 3) bundle
+types respectively. Because ZIP 248 requires that each bundle map is keyed by
+``bundleType`` alone, a transaction that includes a Sapling-post-ZIP 231 bundle
+cannot also include a pre-ZIP 231 Sapling bundle, and similarly for Orchard.
+
 If this ZIP is activated in the same network upgrade as ZIP 248, the encoding
 of the Sapling and Orchard bundles described in this ZIP will be used for
-bundle types 2 and 3, respectively, and ZIP 248's definition of the Sapling and
-Orchard bundles must be updated accordingly. If this ZIP is activated in a
-network upgrade AFTER the network upgrade in which ZIP 248 is activated, the
-encodings it describes will be assigned distinct bundle identifiers. In this
-latter case, a transaction MUST NOT contain both a Sapling-pre-ZIP 231 bundle
-and a Sapling-post-ZIP 231 bundle, or both an Orchard-pre-ZIP 231 bundle and an
-Orchard-post-ZIP 231 bundle.
+bundle type 2 version 0 and bundle type 3 version 0, respectively, and
+ZIP 248's definition of the Sapling and Orchard bundles must be updated
+accordingly. If this ZIP is activated in a network upgrade AFTER the network
+upgrade in which ZIP 248 is activated, the encodings it describes will be
+assigned distinct bundle version identifiers for their respective bundle types.
 
 ## Sapling-post-ZIP 231 Bundle
 
diff --git a/zips/zip-0233.md b/zips/zip-0233.md
@@ -94,12 +94,12 @@ network.
 
 ## Changes to ZIP 248
 
-This ZIP proposes to register bundle type 5 ("ZIP 233 NSM field") in the V6
-transaction bundle type registry defined in ZIP 248 [^zip-0248].
+This ZIP proposes to register bundle type 5 version 0 ("ZIP 233 NSM field") in
+the V6 transaction bundle type registry defined in ZIP 248 [^zip-0248].
 
-| BundleType | `mValuePoolDeltas` | `mEffectBundles` | `mAuthBundles` |
-|------------|--------------------| -----------------|----------------|
-| 5          |✅                  |❌                |❌              |
+| BundleType | BundleVersion | `mValuePoolDeltas` | `mEffectBundles` | `mAuthBundles` |
+|------------|---------------|--------------------|------------------|----------------|
+| 5          | 0             |✅                  |❌                |❌              |
 
 The NSM bundle has no effecting data and no authorizing data. The amount to be
 removed from circulation is represented solely as an entry in `mValuePoolDeltas`
diff --git a/zips/zip-0248.rst b/zips/zip-0248.rst
diff --git a/zips/zip-2002.rst b/zips/zip-2002.rst
