From 5e02e9086cabb4352f39cbeb884f9148eeed0fcf Mon Sep 17 00:00:00 2001 From: Yuval Kogman Date: Tue, 4 Aug 2026 16:08:51 +0200 Subject: [PATCH 01/11] Concurrent PSBT spec --- cspell/bitcoin-privacy.txt | 15 ++ psbt-concurrent.md | 276 +++++++++++++++++++++++++++++++++++++ 2 files changed, 291 insertions(+) create mode 100644 psbt-concurrent.md diff --git a/cspell/bitcoin-privacy.txt b/cspell/bitcoin-privacy.txt index 16c9b72..2bc87e3 100644 --- a/cspell/bitcoin-privacy.txt +++ b/cspell/bitcoin-privacy.txt @@ -28,3 +28,18 @@ taptree unlinkability UTXO xpub +ANYONECANPAY +CRDT +globalseed +joinpsbts +keydata +Kickstarter +nlocktime +psbtv +reserialization +standardness +txns +unioned +unrepresentable +unshuffled +valuedata diff --git a/psbt-concurrent.md b/psbt-concurrent.md new file mode 100644 index 0000000..5c63c85 --- /dev/null +++ b/psbt-concurrent.md @@ -0,0 +1,276 @@ +# Concurrent PSBT Construction + +## Abstract + +New fields and rules for combining PSBTs in a distributed setting. This provides an alternative to the BIP 370 constructor role that is less sensitive to order of operations and therefore more amenable to concurrency, which reduces the coordination required for collaborative transaction construction. + +## Motivation + +BIP 174 defines *Combiner* functionality. Its purpose is to integrate information add by either the *Updater* or *Signer* roles to divergent copies of a PSBT. According to the specification the combiner is intended for for PSBTs whose underlying unsigned transactions are identical, i.e. it is restricted to the *Updater* and *Signer* roles. + +BIP 370 introduced a *Constructor* role, which allows signalling that the inputs or outputs of a PSBT are modifiable. Arbitrary mutation of the inputs and outputs is then allowed, but this assumes such state updates are done sequentially. The combiner role is mostly unchanged in BIP 370, and is restricted to only allow combining fields of PSBTs which spend and create the same outputs, and in the same order. This facilitates aggregating signatures from multiple parties in any order, but has limited usefulness during the construction of the PSBT. + +In a distributed system it is easier to deliver messages without guaranteeing the order of delivery is consistent across nodes. Agreement on the set of outputs to spend and a set of outputs to create is sufficient for constructing a transaction, it isn't necessary to agree on the order in which they were added. This document defines an order insensitive merging procedure which generalizes the *Combiner* role to non-identical modifiable PSBTs which may still overlap in some of their data. To terminate concurrent transaction construction, a consistent ordering procedure is also defined for producing a a consistent PSBT which can subsequently be manipulated using the normal BIP 174 roles. + +## Specification + +TODO diagram for the combined state machine, indicate when downconversion (to v2 or v0) can happen + + creator -> constructor -> constructor (bip 370) -> updater -> signer -> combiner -> finalizer -> extractor + +TODO discuss scrubbing after signer and before combiner + +The new field types for distributed PSBT construction are as follows: + +### New global types + +| Name | `keytype` | `keydata` | `keydata` Description | `valuedata` | `valuedata` Description | +| --- | --- | --- | --- | --- | --- | +| Transaction Unordered Flag | `PSBT_GLOBAL_TX_UNORDERED = TBD` | None | No key data | `<8-bit uint>` | If present, must be set to a value `0x03` to indicate inputs and outputs are unordered. | +| Sort Seed | `PSBT_GLOBAL_SORT_SEED = TBD` | None | No key data | `` | Random seed used to derive deterministic sort keys when explicit per-map sort keys are absent. | +| Deterministic Sort Flag | `PSBT_GLOBAL_SORT_DETERMINISTIC = TBD` | None | No key data | `<8-bit uint>` | A value of `0x01` indicates sort keys must be deterministically derived and explicit `PSBT_IN_SORT_KEY` / `PSBT_OUT_SORT_KEY` fields are disallowed. A value of `0x00` indicates sort keys are required and `PSBT_GLOBAL_SORT_SEED` is disallowed. | +| Removed Input | `PSBT_GLOBAL_REMOVED_INPUT = TBD` | `` | `PSBT_IN_UNIQUE_ID` of an input removed from the logical input set. | None | No value data. | +| Removed Output | `PSBT_GLOBAL_REMOVED_OUTPUT = TBD` | `` | `PSBT_OUT_UNIQUE_ID` removed from the logical output set. | None | No value data. | + +### New per-input types + +| Name | `keytype` | `keydata` | `keydata` Description | `valuedata` | `valuedata` Description | +| --- | --- | --- | --- | --- | --- | +| Input Sort Key | `PSBT_IN_SORT_KEY = TBD` | None | No key data | `` | Arbitrary lexicographically comparable value used to order inputs. | +| Input Unique ID | `PSBT_IN_UNIQUE_ID = TBD` | None | No key data | `` | Optional unique suffix for outpoint identity, used for input removal extensions. | + +### New per-output types + +| Name | `keytype` | `keydata` | `keydata` Description | `valuedata` | `valuedata` Description | +| --- | --- | --- | --- | --- | --- | +| Output Unique ID | `PSBT_OUT_UNIQUE_ID = TBD` | None | No key data | `` | Universally unique identifier for output map identity under unordered output semantics. | +| Output Sort Key | `PSBT_OUT_SORT_KEY = TBD` | None | No key data | `` | Arbitrary lexicographically comparable value used to order outputs when transitioning from unordered to ordered mode. | + +### PSBT identity and transaction effects + +The BIP 174 *Combiner* role specifies how to merge diverging copies of the same PSBT. PSBTs are considered "the same", by identifying them based on the unsigned transaction. Two PSBTs with the same unsigned transaction but potentially different key value pairs are considered two versions of the same PSBT. + +BIP 370 introduces the notion of a [unique ID](https://github.com/bitcoin/bips/blob/master/bip-0370.mediawiki#user-content-Unique_Identification) which is computed as a hash that commits to UTXOs being spent and the new outputs being created, thereby ensuring PSBTs with the same ID have the same structure, but abstracting away some details of the transaction, thereby introducing a notion of equivalence that is a bit more general. + +The effects of a transaction on the distribution of money are determined by its effects the UTXO set: which outputs does it spend and create. However, with regards to money changing hands, we would like to treat equivalent outputs as interchangeable by disregarding the specific outpoints by which specific coins are identified. + +Both notions of identity ensure that PSBTs with the same ID have the same effects, but it is not true that PSBTs with the same effects will have the same ID, since depends on the specific order of the inputs and outputs, among other things. By abstracting over these details we obtain a more general notion of PSBT identity than in BIP 370. The details of how to compute this ID are [provided below](#unique-identifiers). + +### Combiner role and transaction effects + +The BIP 174 *Combiner* role requires that the PSBTs have the same identity. In order to relax this constraint and allow the *Combiner* role to be used in conjunction with (a more general notion of) the *Constructor* role, the *Combiner* role has to be made more conservative in other regards. + +BIP 174 specifies that fields with duplicate keys and more than one distinct value may be combined by [picking one of the values arbitrarily](https://github.com/bitcoin/bips/blob/master/bip-0174.mediawiki#handling-duplicated-keys). This is safe within the scope of BIP 174 because any inconsistency will only affect the validity of a transaction. In other words, when choosing one value over another for a duplicate field, although signing may fail to produce a valid signature, no money will be lost because if the IDs are the same, the the effects are identical. + +This notion of safety can be extend beyond just combining signing related data, so that effects of a transaction formed by combining PSBTs do not depend in any way on the order in which the PSBTs were combined, nor even on combination being done sequentially. Note that this does not require that the effects of the constituent PSBT be identical, only that all of them are combined at some point. More formally, in order to be safe, combining should be monotone in the transaction effects. + +Unfortunately choosing between conflicting values arbitrarily does not preserve this notion of safety when merging PSBTs where the inputs or outputs of one PSBT don't correspond to the inputs or outputs which occupy the same positions in the second PSBT. For example, if the first inputs of two PSBTs spend different coins, and one PSBT takes precedence, the input in the other transaction will be omitted. If the `PSBT_IN_PREVIOUS_TXID` field of one PSBT overrides the other but this precedence is reversed for `PSBT_IN_OUTPUT_INDEX`, the one remaining input will be corrupted. + +#### `joinpsbts` vs. the Combiner role + +Bitcoin Core additionally implements a `joinpsbts` RPC command which does allow merging PSBTs with different identities, so long as their spent output sets are disjoint. + +`joinpsbts` is not idempotent with respect to inputs (writing it as $+$, idempotence would mean that $A + A = A$). Attempting to join a PSBT more than once fails closed: if $B$ contains an input, and $A + B$ is defined, then $(A + B) + B$ will fail, because a transaction cannot spend the same coin twice. + +`joinpsbts` is also not idempotent with respect to the outputs, but unfortunately also does not fail closed, potentially leading to overspending: if $B$ contains just an output, then $B + B$ will contain two copies of that output. + +Although not strictly associative or commutative, due to use of shuffling, in regards to transaction effects it does hold that $(A + B) + C = A + (B + C)$ and that $A + B = B + A$. + +#### Strict Combiner + +In order for combination being deterministic, idempotent and commutative and associative in regards to transaction effects, when either bits 0 or 1 of `PSBT_GLOBAL_TX_MODIFIABLE` are set, indicating the transaction is modifiable, instead of choosing arbitrarily the strict *Combiner* MUST fail whenever duplicate fields have conflicting (unequal) values. + +Exceptions to this are detailed in the next sections, preserving idempotence, commutativity and associativity. + +This establishes a more conservative foundation for ensuring that the effects of a transaction formed by combining a set of PSBTs will always be the same regardless how these PSBTs were combined to obtain a complete transaction. + +### Unordered input and output sets + +Since transaction effects are invariant under permutations of the inputs or outputs, treating the inputs and outputs as unordered sets as opposed to order lists allows safe combining to be defined for PSBTs that are not identical. + +To represent this we define a global field `PSBT_GLOBAL_TX_UNORDERED`, indicating whether the order of inputs and outputs should be ignored. The value is an unsigned 8 bit integer and if present must be set to `0x03`, indicating the transaction in unordered. + +Rationale: Since there is no known use case that requires input or output to be marked unordered or ordered separately from each other, that is omitted from the spec. The value `0x03` simplifies forward compatibility with any specification that might amend this by allowing either bit to be set independently, so long as it overlaps with this specification when both are set. + +If set, the `Has SIGHASH_SINGLE` flag of `PSBT_GLOBAL_TX_MODIFIABLE` must not be set. `SIGHASH_SINGLE` inputs [MUST not be used](#divergence-and-sighash-flags) in unordered transactions. + +Unordered PSBTs MUST be shuffled prior to reserialization. This is easily accomplished by storing them in randomized hashmaps, keyed by their unique identifiers as defined below. If all inputs and outputs have [sort keys](#ordering-inputs-and-outputs), the key based ordering may be used instead of shuffling. + +[fn:Join is implicitly defined on equivalence class of all permutations of inputs/outputs, but the PSBT contents is a random representative. + +Rationale: Not shuffling presents a privacy hazard, leaking information about the sequence of actions leading to a transaction's construction. When a transaction is unordered, shuffling by definition doesn't change its meaning, but ensures the incidental order can't accidentally be relied upon. + +#### Combining PSBTs with different identities + +When `PSBT_GLOBAL_TX_UNORDERED` is set, the input or output maps are no longer distinguished by their index, but instead by a unique identifier defined for each input or output. + +Inputs or outputs with identical unique IDs (those which are present in both PSBTs) are merged by combining their key-value pairs with the stricter, idempotent combination defined above. + +These sets of combined inputs and outputs are then unioned with any inputs or outputs from that have distinct unique identifiers (i.e. are only present in one of the PSBTs, and therefore aren't combined with a counterparts). Distinct identifiers are only allowed if the corresponding `PSBT_GLOBAL_TX_MODIFIABLE` flag is set, because such combinations represent additions of inputs or outputs. If this is not the case but a distinct input or output is present, then combining must fail. + +#### Unique identifiers for inputs + +Inputs are identified by their outpoint, i.e. the tuple of their `PSBT_IN_PREVIOUS_TXID` and `PSBT_IN_OUTPUT_INDEX`, both of which must be set. + +#### Unique identifiers for outputs + +Outputs are identified by a new `PSBT_OUT_UNIQUE_ID` field, which must be universally unique (e.g. 16 bytes of randomness). + +This ensures that repeated addition of the same output is idempotent, but that if two different distributed constructors both attempt to add an identical output (same `PSBT_OUT_VALUE` and `PSBT_OUT_SCRIPT`), that will still result in two copies of the output as intended. This is important because a transaction with only a single copy will appear correct but end up losing the value of all missing copies to mining fees. + +Outputs with an identical `PSBT_OUT_SCRIPT` can be merged, and their values summed together after `PSBT_GLOBAL_TX_UNORDERED` is cleared and an order is determined, using BIP 370 construction rules. See the next section on ordering. + +### Ordering inputs and outputs + +- TODO: unique ID can be derived by sorting even if sort key is empty, but txn finalization must not be unless all sort keys are provided explicitly (regardless of DETERMINISTIC) +- add section for unique ID derivation a la BIP 370 + +Clearing the `PSBT_GLOBAL_TX_UNORDERED` field indicates the order of the inputs and outputs. Due to the shuffling requirement, the given order will in general not be consistent across replicas if this is done without determining an order, resulting in diverging unsigned transactions. + +For consistent ordering we define `PSBT_IN_SORT_KEY` and `PSBT_OUT_SORT_KEY` fields for inputs and outputs respectively, that may include up to 32 bytes of arbitrary data, used as a sort key for lexicographical sorting. + +If the global field `PSBT_GLOBAL_SORT_DETERMINISTIC` is set (unsigned 8 bit integer) to `0x01`, then sort keys MUST NOT be set, and `PSBT_GLOBAL_SORT_SEED` MUST be set and contain at least 128 bits of randomness. + +If `PSBT_GLOBAL_SORT_DETERMINISTIC` is set to `0x00`, explicit sort keys are required to be set and used prior to clearing the `PSBT_GLOBAL_TX_UNORDERED` field and fixing the transaction order. + +If any `PSBT_IN_SORT_KEY` and `PSBT_OUT_SORT_KEY` are omitted, the global `PSBT_GLOBAL_SORT_SEED` field is set, and `PSBT_GLOBAL_SORT_DETERMINISTIC` is either omitted or set to `0x01`, the sort keys are derived deterministically. A missing `PSBT_IN_SORT_KEY` is derived as `H(PSBT_GLOBAL_SORT_SEED || PSBT_IN_PREVIOUS_TXID || PSBT_IN_OUTPUT_INDEX)` and `PSBT_OUT_SORT_KEY` as `H(PSBT_GLOBAL_SORT_SEED || PSBT_OUT_UNIQUE_ID)`, where `H_s` is a BIP 341 style tagged hash, with the tag preimage being `BIP ???? deterministic ordering` (TODO pick a real domain separator). + +If any sort key is missing, ordering can only proceed after `PSBT_GLOBAL_SORT_SEED` is set. + +A *Creator* creating an unordered transaction SHOULD set `PSBT_GLOBAL_SORT_DETERMINISTIC` to ensure consistent ordering rules are enforced. + +For sufficiently large transactions the ordering itself (and therefore the per input signatures) is a cryptographically binding commitment to the `PSBT_GLOBAL_SORT_SEED` value. This is because the entropy of the ordering of $n$ elements is $log_2(n!)$. For reference, $\log_2(35!) > 128$, $\log_2(25!) > 80$, and $\log_2(15!) > 40$. + +This can provides additional integrity to a collaborative transaction construction protocol, since [`SIGHASH_ALL`](#divergence-and-sighash-flags) signatures must agree on the ordering. + +In applications where this is desirable, the *Creator* should only set `PSBT_GLOBAL_SORT_DETERMINISTIC` to `0x01`, and leave `PSBT_GLOBAL_SORT_SEED` unset. Each replica will locally provide a value for `PSBT_GLOBAL_SORT_SEED` just in time, as a commitment to protocol transcript (e.g. the root hash of a Merkle set of protocol messages). + +If that is not the case, the *Creator* should initialize `PSBT_GLOBAL_SORT_SEED` with sufficient randomness thereby ensure some order can always be determined, or set `PSBT_GLOBAL_SORT_DETERMINISTIC` to `0x00` to indicate explicit sort keys are required.. + +TODO global sort seed || hash of fee contributions or expect application to commit to that in transcript if appropriate? + +TODO: Rationale for allowing explicit sort key: lightning interactive-tx `serial_id` field. should always use odd parity form, encoded in network order so that lexicographical sorting works the same as the interactive-tx sorting rule. + +### Unique identification of unordered PSBTs + +In order to derive unique IDs as in BIP 370 for unordered transactions, the `PSBT_GLOBAL_SORT_SEED` and `PSBT_IN_SORT_KEY` and `PSBT_OUT_SORT_KEY` fields are cleared, and then the ordering procedure of the previous section is used without the restriction of a non-empty `PSBT_GLOBAL_SORT_SEED` (sorting with an empty seed). + +TODO: domain separation from PSBT v2, it doesn't make sense to treat an ordered BIP 370 PSBT as the same PSBT even if it agrees on its content when it doesn't agree that the order is meaningless. how to do this? hashing output unique IDs of outputs is insufficient for domain separation of input only partially constructed PSBTs, but maybe that's OK. + +### Divergence and SIGHASH flags + +Signers MUST sign only using `SIGHASH_ALL`. + +If `SIGHASH_ANYONECANPAY` or `SIGHASH_NONE` is used by a signer, the signature is valid for an (ill defined) equivalence class of transactions, with non-equivalent transaction effects. + +At minimum any such signature could lead to txid malleability, and so is not composable with any protocol that requires pre-signed descendant transactions. + +Furthermore, members of this equivalence class of transactions may differ substantially in their effects, potentially leading to loss of funds, not only due to byzantine faults but even omission faults. To ensure undesired transactions are not inadvertently authorized, the full output list should always be committed to using `SIGHASH_ALL`. + +Rationale: No known use cases for such flags in true multiparty transactions (i.e. three or more parties). If necessary, a carve out can be specified in a separate document (e.g. for kickstarter-style crowdfunding with `SIGHASH_ANYONECANPAY|SIGHASH_ALL` signing). + +### Confirmation of successful payment prior to signing + +Parties which neither send nor receive payments within a transaction can safely sign so long as all of their intended outputs are covered by the input signature. This may require signing more than once if some messages are delayed, but TODO see also termination via explicit fee contributions. + +If there is any net transfer between the parties, it is insufficient for a sender (any party that makes an outgoing payment to another party within the transaction regardless of their net send/receive balance) to rely only on the signature committing to the outputs they added, because some of their funds will be used by other parties and their actions need to have been registered as well. + +Before signing, every sender must wait until it has positive confirmation of the PSBT's unique ID (which commits to the full output set) from every one of its receivers, and that in every case the confirmed ID matches the one they derive locally. + +Every receiver whose net balance is non-negative (they may be a sender too but they receive at least as much as they send) can confirm the unique PSBT ID to their respective senders output set contains all of their added outputs. + +Every receiver whose balance is net negative (they send more than they receive) must wait for confirmation from all receivers for whom it is a sender before it confirms the unique ID to the senders for whom it is a receiver. + +If there is a cyclic payment graph, for example Alice pays Bob, Bob pays Carol, and Carol pays Alice, net positive receivers can safely initiate confirmations, breaking the circular dependency, because senders will sign will only occur after all receivers have confirmed and if all net positive receivers have confirmed then all funds are accounted for. At least one such node must exist in every cyclic payment structure, since the sum of the payments along a cycle will be 0. + +If there is any mismatch in the confirmations, either the receiver or the sender has not yet received the full message set. If a receiver learns of an additional input or output after previously confirming, they must confirm the new unique ID which incorporates this additional data. If a sender learns of an additional input or output, they can derive a new unique ID, and stop waiting if this matches all of their receivers' confirmations. + +Such a confirmation mechanism does not require an agreement or consensus mechanism, only eventual consistency. If messages are guaranteed to be delivered eventually then every receiver will eventually confirm a consistent least upper bound. + +TODO sender/receiver examples, including an example with a receiver that contributes no inputs, only outputs + +TODO net-sender, net-receiver, explain in terms of breaking cyclic graph to a tree with net-receivers at the leaves, propagate confirmation up the chain. + +### Input or output removal (optional) + +As in BIP 174, the combination of several PSBTs must contain all the key-value pairs from each of the input PSBTs. + +If support for removal of inputs and outputs is needed, two global fields `PSBT_GLOBAL_REMOVED_INPUT` and `PSBT_GLOBAL_REMOVED_OUTPUT` can be used to represent a [two phase set](https://en.wikipedia.org/wiki/Conflict-free_replicated_data_type#2P-Set_(Two-Phase_Set)) by specifying the inputs or outputs to be removed in the keydata. Inputs or outputs whose unique IDs are specified must be pruned from the input or output. + +Because inputs are identified by outpoint, an input spending the same coin as an input whose outpoint is in the set of removed inputs can't normally be added. Therefore we introduce an optional `PSBT_IN_UNIQUE_ID` field, whose value (if provided) is appended to the outpoint. + +Support for removal is entirely optional. Implementations may explicitly fail when combining with a PSBT that sets either `PSBT_GLOBAL_REMOVED_INPUT` or `PSBT_GLOBAL_REMOVED_OUTPUT`, but completely ignoring these fields is fail safe. + +Assuming [`SIGHASH_ALL` is used](#divergence-and-sighash-flags), it's sufficient to simply rely on the signature hashing. If an output was removed, a peer which does not implement removal it will diverge from those that do, and therefore produce a signature that will not be valid for the transaction supporting peers will produce and subsequently sign, and vice versa, ensuring that neither transaction is valid. + +This optionality extends the `PSBT_IN_UNIQUE_ID` field, a removal and re-insertion with incompatible data will either cause combination to fail due to a mismatch or succeed by ignoring the removal and treating the insertion as idempotent, but otherwise diverge. + +While this would allow limited interoperability among clients, that is not recommended, and is described as an argument for the safety of omitting any removal related functionality. Implementations which omit removal functionality SHOULD fail or at least warn if combining a PSBT that signals removal. + +TODO: while combine is monotone of data / PSBT fields including removals, it is no longer monotone in transaction effects. This does not present a safety issue if [only `SIGHASH_ALL` is used](#divergence-and-sighash-flags). + +Rationale for optionality: not implementing is safe, couldn't find usage of `tx_remove_{input,output}`, non-monotonic state makes termination / limits trickier. + +TODO for interactive-tx, set `PSBT_IN_UNIQUE_ID` to odd parity `serial_id`. this makes it possible to support `tx_remove_{input,output}` operations. + +### PSBT CRDT (optional) + +In some circumstances a conflict free replicated data type (CRDT) can be defined as a subtype of (unordered) PSBTs. In a CRDT, in addition to being idempotent, commutative and associative, combination is additionally [guaranteed to succeed](https://en.wikipedia.org/wiki/Semilattice). + +Success here means producing a useful output, which ideally would guarantee a transaction that would be valid if fully signed, which also conforms to standardness policy. This can only be guaranteed under assumptions that must be realized by some additional protocol, beyond the scope of this document. + +#### Mutually exclusive inputs + +Two `OP_CLTV` encumbered coins, one with a height based and one with a time based `nLocktime` constraint will impose mutually exclusive validity requirements on their spending transactions, and therefore cannot be spent together in the same transaction. + +In order to ensure the least upper bound of any two inputs under consideration not only can be defined, but will correspond to a valid transaction, the *Creator* role can restrict the domain of spendable inputs before inputs are added. + +TODO `PSBT_GLOBAL_{REQUIRED,MAXIMUM}_{HEIGHT,TIME}_LOCKTIME` height and time separately or just integer range? separately is consistent with other PSBT specs. a single nlocktime interval field with two unsigned integers, required and max-required would make many invalid states unrepresentable, but is more fiddly and unfamiliar. + +#### Size Limits + +advisory fields: `MAX_WEIGHT_PER_PARTICIPANT`, `MAX_TRANSACTION_WEIGHT` (default 400000?) - determines max number of participants while also signalling size limit is enforced + +if every participant effectively restricts the domain by respecting the limit the least upper bound is guaranteed not to exceed the limit making the join valid. + +assumes the number of participants can be restricted via some external mechanism. + +#### Termination + +knowing when to proceed to signing + +- global fee contribution + - `PSBT_GLOBAL_EXPLICIT_FEE_CONTRIBUTION` + - keydata = 16 byte uuid + - value = u64 amount of funds explicitly contributed as fees + - needs `PSBT_IN_NON_WITNESS_UTXO` or `PSBT_IN_WITNESS_UTXO` for nominal value + - effective values/costs would a specific feerate and input size estimation, + instead all such fee contributions should also be added (but can be + computed deterministically in case this is known) + +inputs before outputs? +only rely on payment ACKs + +## Rationale + +## Backwards Compatibility + +## Reference Implementation + +--- + +# TODO + +- new PSBT version? + - con: new PSBT version + pro: deserializing unordered txns in psbtv2 will error instead of + potentially leaking unshuffled input/output order + +- Move inline rationales to their own section + +- BIP 174 describes how to aggregate signatures via combiner. example includes a manual coinjoin flow, joining of PSBTs not defined in the spec. technically this involves two different PSBTs. discuss what happens when not sequential, as well as conceptual issues. + +--- + +- discuss liveness. safety WRT transaction effects is nice but we also want to + minimize irrecoverable failures. discuss both generally and in CRDT section. From 673171e5a53f697d459f06f494321965c7c9bf87 Mon Sep 17 00:00:00 2001 From: Armin Sabouri Date: Fri, 23 Oct 2026 14:52:23 -0400 Subject: [PATCH 02/11] Rewrite concurrent PSBT BIP draft Reduce scope to just strict combining and sorting. Drop the open design notes and optional extensions, and specify ordering and identity precisely. - Rewrite abstract and motivation. Move the BIP 174 Combiner, BIP 370 Constructor and joinpsbts discussion into a new Background section - Add a note that field values are TBD and that field names serve as proprietary types for now - Replace the text state machine with a mermaid flowchart of an N-wallet protocol - Condense the strict Combiner and unordered combining rules - Drop input and output removal (PSBT_GLOBAL_REMOVED_INPUT, PSBT_GLOBAL_REMOVED_OUTPUT, PSBT_IN_UNIQUE_ID) - Drop the PSBT identity, payment confirmation, CRDT, size limit and termination sections, the sort seed commitment discussion, the SIGHASH_SINGLE modifiable flag rule and all inline TODO lists - Allow merging outputs with the same script only after sorting. The merged output takes the position of the first output it replaces - Rename PSBT_OUT_VALUE to PSBT_OUT_AMOUNT to match BIP 370 - Require unique sort keys and forbid clearing PSBT_GLOBAL_TX_UNORDERED before sorting - Specify explicit, derived and hybrid sort key modes with a table covering every PSBT_GLOBAL_SORT_DETERMINISTIC value. The sort seed may stay unset until sorting - Derive sort keys with a BIP 340 tagged hash, tag ConcurrentPSBTDeterministicOrdering - Add a Canonical Identifier section that uses the tag ConcurrentPSBTUnorderedState to keep unordered IDs distinct from BIP 370 IDs - Shorten the SIGHASH_ALL rationale - Add Backwards Compatibility, Open Question, Reference Implementation and Test Vectors sections - Move inline rationales to footnotes - Use RFC 2119 keywords consistently and fix spelling and grammar - Remove cspell words the draft no longer uses --- cspell/bitcoin-privacy.txt | 6 - psbt-concurrent.md | 289 ++++++++++++++++--------------------- 2 files changed, 122 insertions(+), 173 deletions(-) diff --git a/cspell/bitcoin-privacy.txt b/cspell/bitcoin-privacy.txt index 2bc87e3..6cea9e4 100644 --- a/cspell/bitcoin-privacy.txt +++ b/cspell/bitcoin-privacy.txt @@ -29,17 +29,11 @@ unlinkability UTXO xpub ANYONECANPAY -CRDT globalseed joinpsbts keydata Kickstarter nlocktime -psbtv reserialization -standardness -txns -unioned unrepresentable -unshuffled valuedata diff --git a/psbt-concurrent.md b/psbt-concurrent.md index 5c63c85..9318478 100644 --- a/psbt-concurrent.md +++ b/psbt-concurrent.md @@ -2,275 +2,230 @@ ## Abstract -New fields and rules for combining PSBTs in a distributed setting. This provides an alternative to the BIP 370 constructor role that is less sensitive to order of operations and therefore more amenable to concurrency, which reduces the coordination required for collaborative transaction construction. +This document extends BIP 370 with new PSBT fields and rules for constructing transactions concurrently, so participants no longer need to agree on the order in which inputs and outputs are added. Inputs and outputs are treated as unordered sets instead of ordered lists, and a strict *Combiner* restricts the BIP 174 *Combiner* by failing on conflicting values while extending it to non-identical PSBTs that may overlap. An ordering procedure then produces a consistent PSBT that can be handled by the normal BIP 174 roles. ## Motivation -BIP 174 defines *Combiner* functionality. Its purpose is to integrate information add by either the *Updater* or *Signer* roles to divergent copies of a PSBT. According to the specification the combiner is intended for for PSBTs whose underlying unsigned transactions are identical, i.e. it is restricted to the *Updater* and *Signer* roles. +In a distributed system, it is easier to deliver messages without guaranteeing the order of delivery is consistent across nodes. To build a transaction, participants need to agree on which inputs it spends, which outputs it creates, and how those inputs and outputs are ordered. They don't need to agree on the order in which those inputs and outputs were added. -BIP 370 introduced a *Constructor* role, which allows signalling that the inputs or outputs of a PSBT are modifiable. Arbitrary mutation of the inputs and outputs is then allowed, but this assumes such state updates are done sequentially. The combiner role is mostly unchanged in BIP 370, and is restricted to only allow combining fields of PSBTs which spend and create the same outputs, and in the same order. This facilitates aggregating signatures from multiple parties in any order, but has limited usefulness during the construction of the PSBT. +## Background -In a distributed system it is easier to deliver messages without guaranteeing the order of delivery is consistent across nodes. Agreement on the set of outputs to spend and a set of outputs to create is sufficient for constructing a transaction, it isn't necessary to agree on the order in which they were added. This document defines an order insensitive merging procedure which generalizes the *Combiner* role to non-identical modifiable PSBTs which may still overlap in some of their data. To terminate concurrent transaction construction, a consistent ordering procedure is also defined for producing a a consistent PSBT which can subsequently be manipulated using the normal BIP 174 roles. +### BIP 174 Combiner -## Specification +BIP 174 defines *Combiner* functionality. Its purpose is to integrate information added by either the *Updater* or *Signer* roles to divergent copies of a PSBT. According to the specification, the Combiner is intended for PSBTs whose underlying unsigned transactions are identical. + +### BIP 370 Constructor + +BIP 370 introduced a *Constructor* role, which allows signaling that the inputs or outputs of a PSBT are modifiable. Arbitrary mutation of the inputs and outputs is then allowed, but this assumes such state updates are done sequentially. The Combiner role is mostly unchanged in BIP 370, and is restricted to only allow combining fields of PSBTs which spend and create the same outputs in the same order. This facilitates aggregating signatures from multiple parties in any order, but has limited usefulness during the construction of the PSBT. + +### `joinpsbts` + +Bitcoin Core implements a [`joinpsbts`](https://bitcoincore.org/en/doc/30.0.0/rpc/rawtransactions/joinpsbts/) RPC command that allows merging PSBTs, so long as their spent output sets are disjoint. + +`joinpsbts` is not idempotent with respect to inputs (writing it as $+$, idempotence would mean that $A + A = A$). Attempting to join a PSBT more than once fails closed: if $B$ contains an input, and $A + B$ is defined, then $(A + B) + B$ will fail, because a transaction cannot spend the same coin twice. -TODO diagram for the combined state machine, indicate when downconversion (to v2 or v0) can happen +`joinpsbts` is also not idempotent with respect to the outputs, potentially leading to overspending: if $B$ contains just an output, then $B + B$ will contain two copies of that output. - creator -> constructor -> constructor (bip 370) -> updater -> signer -> combiner -> finalizer -> extractor +`joinpsbts` is not strictly associative or commutative, because it shuffles. $(A + B) + C$ can serialize differently from $A + (B + C)$, and $A + B$ from $B + A$. The same coins are spent and the same payments created either way. However, in a concurrent setting, replicas will have diverging copies of the PSBT. -TODO discuss scrubbing after signer and before combiner +## Specification The new field types for distributed PSBT construction are as follows: ### New global types +> [!NOTE] +> Field values are currently TBD, and as implemented, the name (e.g. `PSBT_GLOBAL_TX_UNORDERED`) is used as the proprietary field type. + | Name | `keytype` | `keydata` | `keydata` Description | `valuedata` | `valuedata` Description | | --- | --- | --- | --- | --- | --- | -| Transaction Unordered Flag | `PSBT_GLOBAL_TX_UNORDERED = TBD` | None | No key data | `<8-bit uint>` | If present, must be set to a value `0x03` to indicate inputs and outputs are unordered. | +| Transaction Unordered Flag | `PSBT_GLOBAL_TX_UNORDERED = TBD` | None | No key data | `<8-bit uint>` | If present, MUST be set to `0x03` to indicate inputs and outputs are unordered. | | Sort Seed | `PSBT_GLOBAL_SORT_SEED = TBD` | None | No key data | `` | Random seed used to derive deterministic sort keys when explicit per-map sort keys are absent. | -| Deterministic Sort Flag | `PSBT_GLOBAL_SORT_DETERMINISTIC = TBD` | None | No key data | `<8-bit uint>` | A value of `0x01` indicates sort keys must be deterministically derived and explicit `PSBT_IN_SORT_KEY` / `PSBT_OUT_SORT_KEY` fields are disallowed. A value of `0x00` indicates sort keys are required and `PSBT_GLOBAL_SORT_SEED` is disallowed. | -| Removed Input | `PSBT_GLOBAL_REMOVED_INPUT = TBD` | `` | `PSBT_IN_UNIQUE_ID` of an input removed from the logical input set. | None | No value data. | -| Removed Output | `PSBT_GLOBAL_REMOVED_OUTPUT = TBD` | `` | `PSBT_OUT_UNIQUE_ID` removed from the logical output set. | None | No value data. | +| Deterministic Sort Flag | `PSBT_GLOBAL_SORT_KEY_DERIVATION = TBD` | None | No key data | `<8-bit uint>` | A value of `0x01` indicates all sort keys MUST be deterministically derived. A value of `0x00` indicates only explicit sort keys are allowed and `PSBT_GLOBAL_SORT_SEED` is disallowed. If absent, missing explicit sort keys are derived. At the time of sorting either every input and output must have an explicit sort key, or `PSBT_GLOBAL_SORT_SEED` MUST be set and sort key derivation allowed or required. | ### New per-input types | Name | `keytype` | `keydata` | `keydata` Description | `valuedata` | `valuedata` Description | | --- | --- | --- | --- | --- | --- | | Input Sort Key | `PSBT_IN_SORT_KEY = TBD` | None | No key data | `` | Arbitrary lexicographically comparable value used to order inputs. | -| Input Unique ID | `PSBT_IN_UNIQUE_ID = TBD` | None | No key data | `` | Optional unique suffix for outpoint identity, used for input removal extensions. | ### New per-output types | Name | `keytype` | `keydata` | `keydata` Description | `valuedata` | `valuedata` Description | | --- | --- | --- | --- | --- | --- | | Output Unique ID | `PSBT_OUT_UNIQUE_ID = TBD` | None | No key data | `` | Universally unique identifier for output map identity under unordered output semantics. | -| Output Sort Key | `PSBT_OUT_SORT_KEY = TBD` | None | No key data | `` | Arbitrary lexicographically comparable value used to order outputs when transitioning from unordered to ordered mode. | - -### PSBT identity and transaction effects - -The BIP 174 *Combiner* role specifies how to merge diverging copies of the same PSBT. PSBTs are considered "the same", by identifying them based on the unsigned transaction. Two PSBTs with the same unsigned transaction but potentially different key value pairs are considered two versions of the same PSBT. +| Output Sort Key | `PSBT_OUT_SORT_KEY = TBD` | None | No key data | `` | Arbitrary lexicographically comparable value used to order outputs. | -BIP 370 introduces the notion of a [unique ID](https://github.com/bitcoin/bips/blob/master/bip-0370.mediawiki#user-content-Unique_Identification) which is computed as a hash that commits to UTXOs being spent and the new outputs being created, thereby ensuring PSBTs with the same ID have the same structure, but abstracting away some details of the transaction, thereby introducing a notion of equivalence that is a bit more general. +Example collaborative protocol (*N* wallets). Creator and Constructor set `PSBT_GLOBAL_SORT_SEED` and share that PSBT with every wallet. Each wallet *i* runs the same pipeline below in parallel. Combiner once all wallets have signed. -The effects of a transaction on the distribution of money are determined by its effects the UTXO set: which outputs does it spend and create. However, with regards to money changing hands, we would like to treat equivalent outputs as interchangeable by disregarding the specific outpoints by which specific coins are identified. +```mermaid +flowchart LR + subgraph init ["Creator / Constructor"] + EMPTY[empty PSBT] + SEED[PSBT with PSBT_GLOBAL_SORT_SEED set] + EMPTY -->|set PSBT_GLOBAL_SORT_SEED| SEED + end + SEED -->|Distribute to wallets| Pop -Both notions of identity ensure that PSBTs with the same ID have the same effects, but it is not true that PSBTs with the same effects will have the same ID, since depends on the specific order of the inputs and outputs, among other things. By abstracting over these details we obtain a more general notion of PSBT identity than in BIP 370. The details of how to compute this ID are [provided below](#unique-identifiers). + subgraph Wi ["Wallet i (i = 1..N)"] + direction LR + Pop[PSBT populated with Wallet i's inputs and outputs] + Pop -->|Send and join received PSBTs from other wallets| Join[PSBT populated with all wallets' inputs and outputs] + Join -->|sort, then clear PSBT_GLOBAL_TX_UNORDERED field| Clear[Sorted inputs and outputs] + subgraph us ["Updater / Signer"] + SIG[Wallet i's signed PSBT] + end + Clear --> SIG + end -### Combiner role and transaction effects + subgraph combine ["Combiner"] + COMB[N signed PSBTs] + end -The BIP 174 *Combiner* role requires that the PSBTs have the same identity. In order to relax this constraint and allow the *Combiner* role to be used in conjunction with (a more general notion of) the *Constructor* role, the *Combiner* role has to be made more conservative in other regards. + subgraph finish ["Finalizer / Extractor"] + SIGNED[signed tx] + end -BIP 174 specifies that fields with duplicate keys and more than one distinct value may be combined by [picking one of the values arbitrarily](https://github.com/bitcoin/bips/blob/master/bip-0174.mediawiki#handling-duplicated-keys). This is safe within the scope of BIP 174 because any inconsistency will only affect the validity of a transaction. In other words, when choosing one value over another for a duplicate field, although signing may fail to produce a valid signature, no money will be lost because if the IDs are the same, the the effects are identical. + SIG --> COMB + COMB --> SIGNED +``` -This notion of safety can be extend beyond just combining signing related data, so that effects of a transaction formed by combining PSBTs do not depend in any way on the order in which the PSBTs were combined, nor even on combination being done sequentially. Note that this does not require that the effects of the constituent PSBT be identical, only that all of them are combined at some point. More formally, in order to be safe, combining should be monotone in the transaction effects. +### Strict Combiner -Unfortunately choosing between conflicting values arbitrarily does not preserve this notion of safety when merging PSBTs where the inputs or outputs of one PSBT don't correspond to the inputs or outputs which occupy the same positions in the second PSBT. For example, if the first inputs of two PSBTs spend different coins, and one PSBT takes precedence, the input in the other transaction will be omitted. If the `PSBT_IN_PREVIOUS_TXID` field of one PSBT overrides the other but this precedence is reversed for `PSBT_IN_OUTPUT_INDEX`, the one remaining input will be corrupted. +BIP 174 lets a [Combiner](https://github.com/bitcoin/bips/blob/master/bip-0174.mediawiki#user-content-Combiner) resolve a key that has two different values by picking either one. That is safe when every PSBT shares the same unsigned transaction, because the worst outcome is an invalid signature. Once inputs and outputs can differ between copies, picking one value can change what the transaction spends or pays, and the result depends on the order in which copies were combined. -#### `joinpsbts` vs. the Combiner role - -Bitcoin Core additionally implements a `joinpsbts` RPC command which does allow merging PSBTs with different identities, so long as their spent output sets are disjoint. - -`joinpsbts` is not idempotent with respect to inputs (writing it as $+$, idempotence would mean that $A + A = A$). Attempting to join a PSBT more than once fails closed: if $B$ contains an input, and $A + B$ is defined, then $(A + B) + B$ will fail, because a transaction cannot spend the same coin twice. +A strict Combiner therefore MUST fail when the same key has conflicting values. With this rule, the transaction effects of combining a set of PSBTs do not depend on the order or grouping of the combinations, or on whether a PSBT is combined more than once. The following sections define exceptions that keep these properties. -`joinpsbts` is also not idempotent with respect to the outputs, but unfortunately also does not fail closed, potentially leading to overspending: if $B$ contains just an output, then $B + B$ will contain two copies of that output. +#### Combining PSBTs -Although not strictly associative or commutative, due to use of shuffling, in regards to transaction effects it does hold that $(A + B) + C = A + (B + C)$ and that $A + B = B + A$. +Reordering a transaction's inputs or outputs does not change which coins it spends or which payments it creates. Treating them as unordered sets is what lets us combine PSBTs that are not identical. -#### Strict Combiner +To represent this, we define a global field `PSBT_GLOBAL_TX_UNORDERED`, indicating whether the order of inputs and outputs should be ignored. When present, it MUST be set to `0x03`, indicating the transaction is unordered.[^tx-unordered] -In order for combination being deterministic, idempotent and commutative and associative in regards to transaction effects, when either bits 0 or 1 of `PSBT_GLOBAL_TX_MODIFIABLE` are set, indicating the transaction is modifiable, instead of choosing arbitrarily the strict *Combiner* MUST fail whenever duplicate fields have conflicting (unequal) values. +When `PSBT_GLOBAL_TX_UNORDERED` is set, the input or output maps are not distinguished by their index, but instead by a unique identifier defined for each input or output. -Exceptions to this are detailed in the next sections, preserving idempotence, commutativity and associativity. +Inputs or outputs with identical unique IDs are merged by combining their key-value pairs with the stricter, idempotent combination [defined above](#strict-combiner). After merging the inputs and outputs that appear in both PSBTs, the strict Combiner additionally keeps the ones that appear in only one of them. -This establishes a more conservative foundation for ensuring that the effects of a transaction formed by combining a set of PSBTs will always be the same regardless how these PSBTs were combined to obtain a complete transaction. +Distinct identifiers are only allowed if the corresponding BIP 370 `PSBT_GLOBAL_TX_MODIFIABLE` flag is set, because such combinations represent additions of inputs or outputs. If this is not the case but a distinct input or output is present, then combining MUST fail.[^tx-modifiable] -### Unordered input and output sets - -Since transaction effects are invariant under permutations of the inputs or outputs, treating the inputs and outputs as unordered sets as opposed to order lists allows safe combining to be defined for PSBTs that are not identical. - -To represent this we define a global field `PSBT_GLOBAL_TX_UNORDERED`, indicating whether the order of inputs and outputs should be ignored. The value is an unsigned 8 bit integer and if present must be set to `0x03`, indicating the transaction in unordered. - -Rationale: Since there is no known use case that requires input or output to be marked unordered or ordered separately from each other, that is omitted from the spec. The value `0x03` simplifies forward compatibility with any specification that might amend this by allowing either bit to be set independently, so long as it overlaps with this specification when both are set. - -If set, the `Has SIGHASH_SINGLE` flag of `PSBT_GLOBAL_TX_MODIFIABLE` must not be set. `SIGHASH_SINGLE` inputs [MUST not be used](#divergence-and-sighash-flags) in unordered transactions. - -Unordered PSBTs MUST be shuffled prior to reserialization. This is easily accomplished by storing them in randomized hashmaps, keyed by their unique identifiers as defined below. If all inputs and outputs have [sort keys](#ordering-inputs-and-outputs), the key based ordering may be used instead of shuffling. - -[fn:Join is implicitly defined on equivalence class of all permutations of inputs/outputs, but the PSBT contents is a random representative. - -Rationale: Not shuffling presents a privacy hazard, leaking information about the sequence of actions leading to a transaction's construction. When a transaction is unordered, shuffling by definition doesn't change its meaning, but ensures the incidental order can't accidentally be relied upon. - -#### Combining PSBTs with different identities - -When `PSBT_GLOBAL_TX_UNORDERED` is set, the input or output maps are no longer distinguished by their index, but instead by a unique identifier defined for each input or output. - -Inputs or outputs with identical unique IDs (those which are present in both PSBTs) are merged by combining their key-value pairs with the stricter, idempotent combination defined above. - -These sets of combined inputs and outputs are then unioned with any inputs or outputs from that have distinct unique identifiers (i.e. are only present in one of the PSBTs, and therefore aren't combined with a counterparts). Distinct identifiers are only allowed if the corresponding `PSBT_GLOBAL_TX_MODIFIABLE` flag is set, because such combinations represent additions of inputs or outputs. If this is not the case but a distinct input or output is present, then combining must fail. +Unordered PSBTs MUST be shuffled prior to reserialization.[^shuffle] If all inputs and outputs have [sort keys](#ordering-inputs-and-outputs), the key-based ordering MAY be used instead of shuffling. #### Unique identifiers for inputs -Inputs are identified by their outpoint, i.e. the tuple of their `PSBT_IN_PREVIOUS_TXID` and `PSBT_IN_OUTPUT_INDEX`, both of which must be set. +Inputs are identified by their outpoint, i.e. the tuple of their `PSBT_IN_PREVIOUS_TXID` and `PSBT_IN_OUTPUT_INDEX`, both of which MUST be set according to BIP 370. #### Unique identifiers for outputs -Outputs are identified by a new `PSBT_OUT_UNIQUE_ID` field, which must be universally unique (e.g. 16 bytes of randomness). +Outputs are identified by a new `PSBT_OUT_UNIQUE_ID` field, which MUST be universally unique (e.g. 16 bytes of randomness). -This ensures that repeated addition of the same output is idempotent, but that if two different distributed constructors both attempt to add an identical output (same `PSBT_OUT_VALUE` and `PSBT_OUT_SCRIPT`), that will still result in two copies of the output as intended. This is important because a transaction with only a single copy will appear correct but end up losing the value of all missing copies to mining fees. +This ensures that repeated addition of the same output is idempotent, and that if two replicas both attempt to add an identical output (same `PSBT_OUT_AMOUNT` and `PSBT_OUT_SCRIPT`), it will still result in two copies of the output as intended. This is important because a transaction with only a single copy will appear correct but end up losing the value of all missing copies to mining fees. -Outputs with an identical `PSBT_OUT_SCRIPT` can be merged, and their values summed together after `PSBT_GLOBAL_TX_UNORDERED` is cleared and an order is determined, using BIP 370 construction rules. See the next section on ordering. +Outputs with an identical `PSBT_OUT_SCRIPT` MAY be merged deterministically by adding their amounts after sorting, using BIP 370 construction rules. Merging during sorting is not allowed, because a merged output has no `PSBT_OUT_UNIQUE_ID`. The merged output takes the position of the first of the outputs it replaces. Unique IDs are no longer required once sorted, because outputs are then identified by position. See the next section on ordering. ### Ordering inputs and outputs -- TODO: unique ID can be derived by sorting even if sort key is empty, but txn finalization must not be unless all sort keys are provided explicitly (regardless of DETERMINISTIC) -- add section for unique ID derivation a la BIP 370 - -Clearing the `PSBT_GLOBAL_TX_UNORDERED` field indicates the order of the inputs and outputs. Due to the shuffling requirement, the given order will in general not be consistent across replicas if this is done without determining an order, resulting in diverging unsigned transactions. +Clearing the `PSBT_GLOBAL_TX_UNORDERED` field fixes the order of the inputs and outputs. Due to the shuffling requirement and the unpredictability of a concurrent setting, the given order will in general not be consistent across replicas, resulting in diverging unsigned transactions. -For consistent ordering we define `PSBT_IN_SORT_KEY` and `PSBT_OUT_SORT_KEY` fields for inputs and outputs respectively, that may include up to 32 bytes of arbitrary data, used as a sort key for lexicographical sorting. +For consistent ordering, we define `PSBT_IN_SORT_KEY` and `PSBT_OUT_SORT_KEY` fields for inputs and outputs respectively, which MAY include up to 32 bytes of arbitrary data, used as a sort key for lexicographical sorting. Sort keys MUST always be unique. -If the global field `PSBT_GLOBAL_SORT_DETERMINISTIC` is set (unsigned 8 bit integer) to `0x01`, then sort keys MUST NOT be set, and `PSBT_GLOBAL_SORT_SEED` MUST be set and contain at least 128 bits of randomness. +`PSBT_GLOBAL_TX_UNORDERED` SHOULD NOT be cleared until every input and output has a sort key, explicit or derived, and the inputs and outputs have been sorted. -If `PSBT_GLOBAL_SORT_DETERMINISTIC` is set to `0x00`, explicit sort keys are required to be set and used prior to clearing the `PSBT_GLOBAL_TX_UNORDERED` field and fixing the transaction order. +// TODO: warning that applications should be careful about how sort keys are selected as it may be a fingerprint -If any `PSBT_IN_SORT_KEY` and `PSBT_OUT_SORT_KEY` are omitted, the global `PSBT_GLOBAL_SORT_SEED` field is set, and `PSBT_GLOBAL_SORT_DETERMINISTIC` is either omitted or set to `0x01`, the sort keys are derived deterministically. A missing `PSBT_IN_SORT_KEY` is derived as `H(PSBT_GLOBAL_SORT_SEED || PSBT_IN_PREVIOUS_TXID || PSBT_IN_OUTPUT_INDEX)` and `PSBT_OUT_SORT_KEY` as `H(PSBT_GLOBAL_SORT_SEED || PSBT_OUT_UNIQUE_ID)`, where `H_s` is a BIP 341 style tagged hash, with the tag preimage being `BIP ???? deterministic ordering` (TODO pick a real domain separator). +At sorting time, every input and output must have a sort key defined. There are three possibilities: all keys must be explicitly provided, some keys may be derived, or all keys must be derived, as determined by the `PSBT_GLOBAL_SORT_KEY_DERIVATION` field. If any keys must be derived then `PSBT_GLOBAL_SORT_SEED` MUST be set. [^sort-deterministic][^derived-sort-keys] -If any sort key is missing, ordering can only proceed after `PSBT_GLOBAL_SORT_SEED` is set. +| Explicit sort keys | `PSBT_GLOBAL_SORT_KEY_DERIVATION=0x00` | `PSBT_GLOBAL_SORT_KEY_DERIVATION` omitted | `PSBT_GLOBAL_SORT_KEY_DERIVATION=0x01` | +| --- | --- | --- | --- | +| none | INVALID | `PSBT_GLOBAL_SORT_SEED` MUST be set. Derive every sort key. | `PSBT_GLOBAL_SORT_SEED` MUST be set. Derive every sort key. | +| some but not all | INVALID | `PSBT_GLOBAL_SORT_SEED` MUST be set. Derive missing sort key. | INVALID | +| every input and output | `PSBT_GLOBAL_SORT_SEED` MUST NOT be set. Use the explicit keys. | No sort keys are derived. Use the explicit sort keys. | INVALID | -A *Creator* creating an unordered transaction SHOULD set `PSBT_GLOBAL_SORT_DETERMINISTIC` to ensure consistent ordering rules are enforced. +#### Explicit sort keys -For sufficiently large transactions the ordering itself (and therefore the per input signatures) is a cryptographically binding commitment to the `PSBT_GLOBAL_SORT_SEED` value. This is because the entropy of the ordering of $n$ elements is $log_2(n!)$. For reference, $\log_2(35!) > 128$, $\log_2(25!) > 80$, and $\log_2(15!) > 40$. +If `PSBT_GLOBAL_SORT_KEY_DERIVATION` is set to `0x00`, every input and output MUST have an explicit sort key, and `PSBT_GLOBAL_SORT_SEED` MUST NOT be set. The explicit keys are used to sort the inputs and outputs prior to clearing the `PSBT_GLOBAL_TX_UNORDERED` field, thus fixing the transaction order. -This can provides additional integrity to a collaborative transaction construction protocol, since [`SIGHASH_ALL`](#divergence-and-sighash-flags) signatures must agree on the ordering. +#### Derived sort keys generated from global sort seed -In applications where this is desirable, the *Creator* should only set `PSBT_GLOBAL_SORT_DETERMINISTIC` to `0x01`, and leave `PSBT_GLOBAL_SORT_SEED` unset. Each replica will locally provide a value for `PSBT_GLOBAL_SORT_SEED` just in time, as a commitment to protocol transcript (e.g. the root hash of a Merkle set of protocol messages). +If the global field `PSBT_GLOBAL_SORT_KEY_DERIVATION` is set to `0x01`, input and output sort keys MUST NOT be set and every sort key is derived (as [defined below](#derivation-rules)) using the `PSBT_GLOBAL_SORT_SEED`. `PSBT_GLOBAL_SORT_SEED` MAY be left unset until sorting, but MUST be set at the time of sorting and contain at least 128 bits of randomness. -If that is not the case, the *Creator* should initialize `PSBT_GLOBAL_SORT_SEED` with sufficient randomness thereby ensure some order can always be determined, or set `PSBT_GLOBAL_SORT_DETERMINISTIC` to `0x00` to indicate explicit sort keys are required.. +If `PSBT_GLOBAL_SORT_KEY_DERIVATION` is omitted, then at the time of sorting either every input and output MUST have an explicit sort key and `PSBT_GLOBAL_SORT_SEED` MUST NOT be set, or `PSBT_GLOBAL_SORT_SEED` MUST be set and explicit sort keys MUST NOT be set. -TODO global sort seed || hash of fee contributions or expect application to commit to that in transcript if appropriate? +##### Derivation rules -TODO: Rationale for allowing explicit sort key: lightning interactive-tx `serial_id` field. should always use odd parity form, encoded in network order so that lexicographical sorting works the same as the interactive-tx sorting rule. +Sort keys are derived as: -### Unique identification of unordered PSBTs +- `PSBT_IN_SORT_KEY` as `H_s(PSBT_GLOBAL_SORT_SEED || PSBT_IN_PREVIOUS_TXID || PSBT_IN_OUTPUT_INDEX)` +- `PSBT_OUT_SORT_KEY` as `H_s(PSBT_GLOBAL_SORT_SEED || PSBT_OUT_UNIQUE_ID)` -In order to derive unique IDs as in BIP 370 for unordered transactions, the `PSBT_GLOBAL_SORT_SEED` and `PSBT_IN_SORT_KEY` and `PSBT_OUT_SORT_KEY` fields are cleared, and then the ordering procedure of the previous section is used without the restriction of a non-empty `PSBT_GLOBAL_SORT_SEED` (sorting with an empty seed). +where `H_s` is a BIP 340-style tagged hash, with the tag being `ConcurrentPSBTDeterministicOrdering`. -TODO: domain separation from PSBT v2, it doesn't make sense to treat an ordered BIP 370 PSBT as the same PSBT even if it agrees on its content when it doesn't agree that the order is meaningless. how to do this? hashing output unique IDs of outputs is insufficient for domain separation of input only partially constructed PSBTs, but maybe that's OK. +#### Mixed -### Divergence and SIGHASH flags +If `PSBT_GLOBAL_SORT_KEY_DERIVATION` is absent and some subset of inputs and outputs are missing explicit sort keys, then the `PSBT_GLOBAL_SORT_SEED` MUST be set at the time of sorting and is used to derive the missing sort keys.[^mixed-mode] -Signers MUST sign only using `SIGHASH_ALL`. +### Canonical Identifier -If `SIGHASH_ANYONECANPAY` or `SIGHASH_NONE` is used by a signer, the signature is valid for an (ill defined) equivalence class of transactions, with non-equivalent transaction effects. +A canonical ID identifies equivalent PSBT states, letting replicas check whether their copies agree. For unordered PSBTs, the ID ignores the order of inputs and outputs, but any other difference in the unsigned transaction changes it. -At minimum any such signature could lead to txid malleability, and so is not composable with any protocol that requires pre-signed descendant transactions. +For unordered transactions (i.e. `PSBT_GLOBAL_TX_UNORDERED` is set), the `PSBT_GLOBAL_SORT_SEED`, `PSBT_IN_SORT_KEY`, and `PSBT_OUT_SORT_KEY` fields are cleared, and then the ordering procedure of the previous section is used without the restriction of a non-empty `PSBT_GLOBAL_SORT_SEED` (sorting with an empty seed). -Furthermore, members of this equivalence class of transactions may differ substantially in their effects, potentially leading to loss of funds, not only due to byzantine faults but even omission faults. To ensure undesired transactions are not inadvertently authorized, the full output list should always be committed to using `SIGHASH_ALL`. +The ID MUST then be computed as the BIP 370 unique ID of the sorted transaction, with the double SHA256 replaced by a BIP 340-style tagged hash with the tag `ConcurrentPSBTUnorderedState`.[^canonical-id] This keeps the ID of an unordered PSBT distinct from the ID of an ordered PSBT with the same contents, even when it has no outputs. -Rationale: No known use cases for such flags in true multiparty transactions (i.e. three or more parties). If necessary, a carve out can be specified in a separate document (e.g. for kickstarter-style crowdfunding with `SIGHASH_ANYONECANPAY|SIGHASH_ALL` signing). +If the PSBT is ordered, the BIP 370 unique ID is used unchanged, without sorting. -### Confirmation of successful payment prior to signing - -Parties which neither send nor receive payments within a transaction can safely sign so long as all of their intended outputs are covered by the input signature. This may require signing more than once if some messages are delayed, but TODO see also termination via explicit fee contributions. - -If there is any net transfer between the parties, it is insufficient for a sender (any party that makes an outgoing payment to another party within the transaction regardless of their net send/receive balance) to rely only on the signature committing to the outputs they added, because some of their funds will be used by other parties and their actions need to have been registered as well. - -Before signing, every sender must wait until it has positive confirmation of the PSBT's unique ID (which commits to the full output set) from every one of its receivers, and that in every case the confirmed ID matches the one they derive locally. - -Every receiver whose net balance is non-negative (they may be a sender too but they receive at least as much as they send) can confirm the unique PSBT ID to their respective senders output set contains all of their added outputs. - -Every receiver whose balance is net negative (they send more than they receive) must wait for confirmation from all receivers for whom it is a sender before it confirms the unique ID to the senders for whom it is a receiver. - -If there is a cyclic payment graph, for example Alice pays Bob, Bob pays Carol, and Carol pays Alice, net positive receivers can safely initiate confirmations, breaking the circular dependency, because senders will sign will only occur after all receivers have confirmed and if all net positive receivers have confirmed then all funds are accounted for. At least one such node must exist in every cyclic payment structure, since the sum of the payments along a cycle will be 0. - -If there is any mismatch in the confirmations, either the receiver or the sender has not yet received the full message set. If a receiver learns of an additional input or output after previously confirming, they must confirm the new unique ID which incorporates this additional data. If a sender learns of an additional input or output, they can derive a new unique ID, and stop waiting if this matches all of their receivers' confirmations. - -Such a confirmation mechanism does not require an agreement or consensus mechanism, only eventual consistency. If messages are guaranteed to be delivered eventually then every receiver will eventually confirm a consistent least upper bound. - -TODO sender/receiver examples, including an example with a receiver that contributes no inputs, only outputs - -TODO net-sender, net-receiver, explain in terms of breaking cyclic graph to a tree with net-receivers at the leaves, propagate confirmation up the chain. - -### Input or output removal (optional) - -As in BIP 174, the combination of several PSBTs must contain all the key-value pairs from each of the input PSBTs. - -If support for removal of inputs and outputs is needed, two global fields `PSBT_GLOBAL_REMOVED_INPUT` and `PSBT_GLOBAL_REMOVED_OUTPUT` can be used to represent a [two phase set](https://en.wikipedia.org/wiki/Conflict-free_replicated_data_type#2P-Set_(Two-Phase_Set)) by specifying the inputs or outputs to be removed in the keydata. Inputs or outputs whose unique IDs are specified must be pruned from the input or output. - -Because inputs are identified by outpoint, an input spending the same coin as an input whose outpoint is in the set of removed inputs can't normally be added. Therefore we introduce an optional `PSBT_IN_UNIQUE_ID` field, whose value (if provided) is appended to the outpoint. - -Support for removal is entirely optional. Implementations may explicitly fail when combining with a PSBT that sets either `PSBT_GLOBAL_REMOVED_INPUT` or `PSBT_GLOBAL_REMOVED_OUTPUT`, but completely ignoring these fields is fail safe. - -Assuming [`SIGHASH_ALL` is used](#divergence-and-sighash-flags), it's sufficient to simply rely on the signature hashing. If an output was removed, a peer which does not implement removal it will diverge from those that do, and therefore produce a signature that will not be valid for the transaction supporting peers will produce and subsequently sign, and vice versa, ensuring that neither transaction is valid. - -This optionality extends the `PSBT_IN_UNIQUE_ID` field, a removal and re-insertion with incompatible data will either cause combination to fail due to a mismatch or succeed by ignoring the removal and treating the insertion as idempotent, but otherwise diverge. - -While this would allow limited interoperability among clients, that is not recommended, and is described as an argument for the safety of omitting any removal related functionality. Implementations which omit removal functionality SHOULD fail or at least warn if combining a PSBT that signals removal. - -TODO: while combine is monotone of data / PSBT fields including removals, it is no longer monotone in transaction effects. This does not present a safety issue if [only `SIGHASH_ALL` is used](#divergence-and-sighash-flags). - -Rationale for optionality: not implementing is safe, couldn't find usage of `tx_remove_{input,output}`, non-monotonic state makes termination / limits trickier. +### Divergence and SIGHASH flags -TODO for interactive-tx, set `PSBT_IN_UNIQUE_ID` to odd parity `serial_id`. this makes it possible to support `tx_remove_{input,output}` operations. +Signers MUST sign only using `SIGHASH_ALL`.[^sighash-all] -### PSBT CRDT (optional) +If a signer uses `SIGHASH_ANYONECANPAY` or `SIGHASH_NONE`, the signature stays valid for a family of transactions that do not have the same effects. -In some circumstances a conflict free replicated data type (CRDT) can be defined as a subtype of (unordered) PSBTs. In a CRDT, in addition to being idempotent, commutative and associative, combination is additionally [guaranteed to succeed](https://en.wikipedia.org/wiki/Semilattice). +That at least makes the transaction ID malleable, so it cannot be used with any protocol that needs pre-signed descendant transactions. -Success here means producing a useful output, which ideally would guarantee a transaction that would be valid if fully signed, which also conforms to standardness policy. This can only be guaranteed under assumptions that must be realized by some additional protocol, beyond the scope of this document. +Those transactions can also differ enough in what they spend or pay that funds can be lost, not only because someone is cheating, but even because a contribution was left out. `SIGHASH_ALL` commits to the full output list, so a signature cannot authorize a transaction the signer did not intend. #### Mutually exclusive inputs -Two `OP_CLTV` encumbered coins, one with a height based and one with a time based `nLocktime` constraint will impose mutually exclusive validity requirements on their spending transactions, and therefore cannot be spent together in the same transaction. +Two `OP_CLTV`-encumbered coins, one with a height-based and one with a time-based `nLockTime` constraint, will impose mutually exclusive validity requirements on their spending transactions, and therefore cannot be spent together in the same transaction. + +// TODO: IIRC BIP 370 specifies the constraints so maybe reference that +In order to ensure the least upper bound of any two inputs under consideration is not only defined but also corresponds to a valid transaction, the *Creator* role can restrict the domain of spendable inputs before inputs are added. -In order to ensure the least upper bound of any two inputs under consideration not only can be defined, but will correspond to a valid transaction, the *Creator* role can restrict the domain of spendable inputs before inputs are added. +## Backwards Compatibility -TODO `PSBT_GLOBAL_{REQUIRED,MAXIMUM}_{HEIGHT,TIME}_LOCKTIME` height and time separately or just integer range? separately is consistent with other PSBT specs. a single nlocktime interval field with two unsigned integers, required and max-required would make many invalid states unrepresentable, but is more fiddly and unfamiliar. +This document does not define a new PSBT version. It extends BIP 370. -#### Size Limits +Existing software can parse and preserve the new fields as [BIP 174 requires](https://github.com/bitcoin/bips/blob/master/bip-0174.mediawiki#extensibility), but cannot interpret them. Clients that do not implement the new rules from this specification therefore cannot take part in unordered construction, and MUST NOT be used to combine PSBTs while `PSBT_GLOBAL_TX_UNORDERED` is set. -advisory fields: `MAX_WEIGHT_PER_PARTICIPANT`, `MAX_TRANSACTION_WEIGHT` (default 400000?) - determines max number of participants while also signalling size limit is enforced +Clients convert to BIP 174 by carrying the new fields as proprietary fields, then following the BIP 370 conversion. Convert a BIP 174 PSBT to BIP 370 before sorting or applying the strict Combiner. -if every participant effectively restricts the domain by respecting the limit the least upper bound is guaranteed not to exceed the limit making the join valid. +While `PSBT_GLOBAL_TX_UNORDERED` is set, PSBTs MUST be combined only by a strict Combiner, not the BIP 174 Combiner. Once `PSBT_GLOBAL_TX_UNORDERED` is cleared, the caller MAY convert to BIP 370 or BIP 174. The new fields need not be retained. -assumes the number of participants can be restricted via some external mechanism. +For BIP 174, input unique IDs may be extracted from the unsigned transaction in the global map. For BIP 370, they may be extracted from the input map (`PSBT_IN_PREVIOUS_TXID` and `PSBT_IN_OUTPUT_INDEX`). However, output unique IDs MUST NOT be derived from the output maps (`PSBT_OUT_AMOUNT` and `PSBT_OUT_SCRIPT`). -#### Termination +## Open Question -knowing when to proceed to signing +- Should we just define a version 3 instead of an extension? The benefits are safety and simplicity. The major downsides are adoption and bikeshedding over details. -- global fee contribution - - `PSBT_GLOBAL_EXPLICIT_FEE_CONTRIBUTION` - - keydata = 16 byte uuid - - value = u64 amount of funds explicitly contributed as fees - - needs `PSBT_IN_NON_WITNESS_UTXO` or `PSBT_IN_WITNESS_UTXO` for nominal value - - effective values/costs would a specific feerate and input size estimation, - instead all such fee contributions should also be added (but can be - computed deterministically in case this is known) +## Reference Implementation -inputs before outputs? -only rely on payment ACKs +Rust implementation: -## Rationale +## Test Vectors -## Backwards Compatibility +// TODO: add link to test vectors -## Reference Implementation +[^tx-unordered]: This specification does not mark inputs and outputs unordered independently. No known use case requires that. `0x03` sets both bits, so a later specification can allow either bit independently and still overlap this one when both are set. ---- +[^shuffle]: Skipping the shuffle leaks the sequence of actions that built the transaction. An unordered transaction has the same meaning after a shuffle, and the shuffle prevents later steps from relying on the incidental order. -# TODO +[^sort-deterministic]: Why is `PSBT_GLOBAL_SORT_KEY_DERIVATION` needed in addition to `PSBT_GLOBAL_SORT_SEED`? A *Creator* that will enforce consistent ordering with `PSBT_GLOBAL_SORT_SEED`, but does not have a seed yet, SHOULD set `PSBT_GLOBAL_SORT_KEY_DERIVATION`. If the seed is supplied later, the *Creator* SHOULD set `PSBT_GLOBAL_SORT_KEY_DERIVATION` to `0x01` and leave `PSBT_GLOBAL_SORT_SEED` unset. Each replica then supplies `PSBT_GLOBAL_SORT_SEED` locally at sort time, as a commitment to the protocol transcript or something similar. Otherwise the *Creator* SHOULD initialize `PSBT_GLOBAL_SORT_SEED` with sufficient randomness so that some order can always be determined, or set `PSBT_GLOBAL_SORT_KEY_DERIVATION` to `0x00` to require explicit sort keys. -- new PSBT version? - - con: new PSBT version - pro: deserializing unordered txns in psbtv2 will error instead of - potentially leaking unshuffled input/output order +[^derived-sort-keys]: Derived sort keys need not be written into the PSBT. Derive them, sort, and discard them. -- Move inline rationales to their own section +[^sighash-all]: No known use case needs these flags in a multiparty transaction of three or more parties. Specify a carve-out in a separate document if one appears, for example Kickstarter-style crowdfunding with `SIGHASH_ANYONECANPAY|SIGHASH_ALL` signing. -- BIP 174 describes how to aggregate signatures via combiner. example includes a manual coinjoin flow, joining of PSBTs not defined in the spec. technically this involves two different PSBTs. discuss what happens when not sequential, as well as conceptual issues. +[^tx-modifiable]: `PSBT_GLOBAL_TX_MODIFIABLE` does not restrict reordering of input or output maps, and MAY stay set after `PSBT_GLOBAL_TX_UNORDERED` is cleared. ---- +[^mixed-mode]: Mixed mode allows clients to fix the relative order of some of their own inputs and outputs with explicit sort keys while the PSBT is merged with other parties' contributions, whose keys are derived from `PSBT_GLOBAL_SORT_SEED`. -- discuss liveness. safety WRT transaction effects is nice but we also want to - minimize irrecoverable failures. discuss both generally and in CRDT section. +[^canonical-id]: Replicas compare canonical IDs to check that they hold the same data. A plain transaction ID also commits to the order of inputs and outputs, but the canonical ID sorts with an empty seed, so its order might not be the final order. The tag marks the ID as order-independent, so a matching ID does not signal agreement on order. From 67a1b2861c771ca4d3547f5e8a5ec0b3001b273f Mon Sep 17 00:00:00 2001 From: Armin Sabouri Date: Mon, 16 Nov 2026 11:43:03 -0500 Subject: [PATCH 03/11] fixup: rewrite joinpsbt section --- psbt-concurrent.md | 8 +------- 1 file changed, 1 insertion(+), 7 deletions(-) diff --git a/psbt-concurrent.md b/psbt-concurrent.md index 9318478..0b6b823 100644 --- a/psbt-concurrent.md +++ b/psbt-concurrent.md @@ -20,13 +20,7 @@ BIP 370 introduced a *Constructor* role, which allows signaling that the inputs ### `joinpsbts` -Bitcoin Core implements a [`joinpsbts`](https://bitcoincore.org/en/doc/30.0.0/rpc/rawtransactions/joinpsbts/) RPC command that allows merging PSBTs, so long as their spent output sets are disjoint. - -`joinpsbts` is not idempotent with respect to inputs (writing it as $+$, idempotence would mean that $A + A = A$). Attempting to join a PSBT more than once fails closed: if $B$ contains an input, and $A + B$ is defined, then $(A + B) + B$ will fail, because a transaction cannot spend the same coin twice. - -`joinpsbts` is also not idempotent with respect to the outputs, potentially leading to overspending: if $B$ contains just an output, then $B + B$ will contain two copies of that output. - -`joinpsbts` is not strictly associative or commutative, because it shuffles. $(A + B) + C$ can serialize differently from $A + (B + C)$, and $A + B$ from $B + A$. The same coins are spent and the same payments created either way. However, in a concurrent setting, replicas will have diverging copies of the PSBT. +Bitcoin Core implements a [`joinpsbts`](https://bitcoincore.org/en/doc/32.0.0/rpc/rawtransactions/joinpsbts/) RPC command that allows merging PSBTs, so long as their input sets are disjoint. For example, if PSBT A spends coin x and B spends y they can be joined however not with PSBT C which spends x as well. In other words, `joinpsbts` is not idompotents with respect to the inputs nor the outputs -- which can lead to over spending. For example, joining a PSBT with distinct inputs but the same outputs will create two identical outputs. Lastly, `joinpsbt` is not associative or commutative because it shuffles. In the concurrent setting this will lead to replicas having divering copies. ## Specification From bcc78e005150938a76268600c7b0213a8745c1dc Mon Sep 17 00:00:00 2001 From: Armin Sabouri Date: Mon, 16 Nov 2026 12:31:34 -0500 Subject: [PATCH 04/11] fixup: rewrite strict combiner rules --- psbt-concurrent.md | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/psbt-concurrent.md b/psbt-concurrent.md index 0b6b823..822637d 100644 --- a/psbt-concurrent.md +++ b/psbt-concurrent.md @@ -99,8 +99,11 @@ To represent this, we define a global field `PSBT_GLOBAL_TX_UNORDERED`, indicati When `PSBT_GLOBAL_TX_UNORDERED` is set, the input or output maps are not distinguished by their index, but instead by a unique identifier defined for each input or output. Inputs or outputs with identical unique IDs are merged by combining their key-value pairs with the stricter, idempotent combination [defined above](#strict-combiner). After merging the inputs and outputs that appear in both PSBTs, the strict Combiner additionally keeps the ones that appear in only one of them. +The Strict combiner, MUST update `PSBT_GLOBAL_INPUT_COUNT` and/or `PSBT_GLOBAL_OUTPUT_COUNT` if combining introduces new inputs and/or outputs. -Distinct identifiers are only allowed if the corresponding BIP 370 `PSBT_GLOBAL_TX_MODIFIABLE` flag is set, because such combinations represent additions of inputs or outputs. If this is not the case but a distinct input or output is present, then combining MUST fail.[^tx-modifiable] +// TODO: provide some examples here + +The strict Combiner MUST fail combining for either the inputs or outputs if the corresponding BIP 370 `PSBT_GLOBAL_TX_MODIFIABLE` flag is set and the combinations represent additions of inputs or outputs. [^tx-modifiable] Unordered PSBTs MUST be shuffled prior to reserialization.[^shuffle] If all inputs and outputs have [sort keys](#ordering-inputs-and-outputs), the key-based ordering MAY be used instead of shuffling. @@ -110,11 +113,11 @@ Inputs are identified by their outpoint, i.e. the tuple of their `PSBT_IN_PREVIO #### Unique identifiers for outputs -Outputs are identified by a new `PSBT_OUT_UNIQUE_ID` field, which MUST be universally unique (e.g. 16 bytes of randomness). +Outputs are identified by a new `PSBT_OUT_UNIQUE_ID` field, which MUST be 16 bytes of uniform randomness. This ensures that repeated addition of the same output is idempotent, and that if two replicas both attempt to add an identical output (same `PSBT_OUT_AMOUNT` and `PSBT_OUT_SCRIPT`), it will still result in two copies of the output as intended. This is important because a transaction with only a single copy will appear correct but end up losing the value of all missing copies to mining fees. -Outputs with an identical `PSBT_OUT_SCRIPT` MAY be merged deterministically by adding their amounts after sorting, using BIP 370 construction rules. Merging during sorting is not allowed, because a merged output has no `PSBT_OUT_UNIQUE_ID`. The merged output takes the position of the first of the outputs it replaces. Unique IDs are no longer required once sorted, because outputs are then identified by position. See the next section on ordering. +Outputs with an identical `PSBT_OUT_SCRIPT` MAY be merged deterministically by adding their amounts after sorting. Merging during sorting is NOT allowed, because a merged output has no `PSBT_OUT_UNIQUE_ID`. The merged output takes the position of the first of the outputs it replaces and the `PSBT_GLOBAL_OUTPUT_COUNT` must be decremented by the number of outputs merged. Unique IDs are no longer required once sorted, because outputs are then identified by position. See the next section on ordering. ### Ordering inputs and outputs @@ -192,7 +195,7 @@ Existing software can parse and preserve the new fields as [BIP 174 requires](ht Clients convert to BIP 174 by carrying the new fields as proprietary fields, then following the BIP 370 conversion. Convert a BIP 174 PSBT to BIP 370 before sorting or applying the strict Combiner. -While `PSBT_GLOBAL_TX_UNORDERED` is set, PSBTs MUST be combined only by a strict Combiner, not the BIP 174 Combiner. Once `PSBT_GLOBAL_TX_UNORDERED` is cleared, the caller MAY convert to BIP 370 or BIP 174. The new fields need not be retained. +While `PSBT_GLOBAL_TX_UNORDERED` is set, PSBTs MUST be combined only by a strict Combiner, not the BIP 174 Combiner. Once `PSBT_GLOBAL_TX_UNORDERED` is cleared the PSBT is semantically the same as a BIP 370 or BIP 174. The new fields need not be retained. For BIP 174, input unique IDs may be extracted from the unsigned transaction in the global map. For BIP 370, they may be extracted from the input map (`PSBT_IN_PREVIOUS_TXID` and `PSBT_IN_OUTPUT_INDEX`). However, output unique IDs MUST NOT be derived from the output maps (`PSBT_OUT_AMOUNT` and `PSBT_OUT_SCRIPT`). From 3a7d9aacc89a9f0252bfcf275b8971cc6e97360f Mon Sep 17 00:00:00 2001 From: Armin Sabouri Date: Mon, 16 Nov 2026 12:43:15 -0500 Subject: [PATCH 05/11] fixup: rewrite diagram --- psbt-concurrent.md | 23 +++++------------------ 1 file changed, 5 insertions(+), 18 deletions(-) diff --git a/psbt-concurrent.md b/psbt-concurrent.md index 822637d..a31fb92 100644 --- a/psbt-concurrent.md +++ b/psbt-concurrent.md @@ -50,38 +50,25 @@ The new field types for distributed PSBT construction are as follows: | Output Unique ID | `PSBT_OUT_UNIQUE_ID = TBD` | None | No key data | `` | Universally unique identifier for output map identity under unordered output semantics. | | Output Sort Key | `PSBT_OUT_SORT_KEY = TBD` | None | No key data | `` | Arbitrary lexicographically comparable value used to order outputs. | -Example collaborative protocol (*N* wallets). Creator and Constructor set `PSBT_GLOBAL_SORT_SEED` and share that PSBT with every wallet. Each wallet *i* runs the same pipeline below in parallel. Combiner once all wallets have signed. +Example collaborative protocol (*N* wallets).Each wallet i adds its own inputs and outputs, then joins the PSBTs it receives from the other wallets. Once every wallet's inputs and outputs are present, it clears PSBT_GLOBAL_TX_UNORDERED and PSBT_GLOBAL_TX_MODIFIABLE, sorts the inputs and outputs, and signs. The signed PSBT goes to the Combiner. ```mermaid flowchart LR - subgraph init ["Creator / Constructor"] - EMPTY[empty PSBT] - SEED[PSBT with PSBT_GLOBAL_SORT_SEED set] - EMPTY -->|set PSBT_GLOBAL_SORT_SEED| SEED - end - SEED -->|Distribute to wallets| Pop + CC[Creator / Constructor] -->|sets PSBT_GLOBAL_SORT_SEED| Pop - subgraph Wi ["Wallet i (i = 1..N)"] + subgraph Wi ["Wallet i"] direction LR Pop[PSBT populated with Wallet i's inputs and outputs] Pop -->|Send and join received PSBTs from other wallets| Join[PSBT populated with all wallets' inputs and outputs] - Join -->|sort, then clear PSBT_GLOBAL_TX_UNORDERED field| Clear[Sorted inputs and outputs] + Join -->|cleared PSBT_GLOBAL_TX_UNORDERED and PSBT_GLOBAL_TX_MODIFIABLE| Clear[Sorted inputs and outputs] subgraph us ["Updater / Signer"] SIG[Wallet i's signed PSBT] end Clear --> SIG end - subgraph combine ["Combiner"] - COMB[N signed PSBTs] - end - - subgraph finish ["Finalizer / Extractor"] - SIGNED[signed tx] - end + SIG --> OUT[Combiner] - SIG --> COMB - COMB --> SIGNED ``` ### Strict Combiner From 179bfc39124a97d2796303c9d37168a6d5566efa Mon Sep 17 00:00:00 2001 From: Armin Sabouri Date: Mon, 16 Nov 2026 12:50:33 -0500 Subject: [PATCH 06/11] Fixup: rationale for when conflicts are ok --- psbt-concurrent.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/psbt-concurrent.md b/psbt-concurrent.md index a31fb92..f940d32 100644 --- a/psbt-concurrent.md +++ b/psbt-concurrent.md @@ -73,7 +73,7 @@ flowchart LR ### Strict Combiner -BIP 174 lets a [Combiner](https://github.com/bitcoin/bips/blob/master/bip-0174.mediawiki#user-content-Combiner) resolve a key that has two different values by picking either one. That is safe when every PSBT shares the same unsigned transaction, because the worst outcome is an invalid signature. Once inputs and outputs can differ between copies, picking one value can change what the transaction spends or pays, and the result depends on the order in which copies were combined. +BIP 174 lets a [Combiner](https://github.com/bitcoin/bips/blob/master/bip-0174.mediawiki#user-content-Combiner) resolve a key that has two different values by picking either one. That is safe when every PSBT shares the same unsigned transaction, because the worst outcome is an invalid signature. Once inputs and outputs can differ between copies, picking one value can change what the transaction spends or pays, and the result depends on the order in which copies were combined.[^conflict-ok] A strict Combiner therefore MUST fail when the same key has conflicting values. With this rule, the transaction effects of combining a set of PSBTs do not depend on the order or grouping of the combinations, or on whether a PSBT is combined more than once. The following sections define exceptions that keep these properties. @@ -213,3 +213,5 @@ Rust implementation: [^mixed-mode]: Mixed mode allows clients to fix the relative order of some of their own inputs and outputs with explicit sort keys while the PSBT is merged with other parties' contributions, whose keys are derived from `PSBT_GLOBAL_SORT_SEED`. [^canonical-id]: Replicas compare canonical IDs to check that they hold the same data. A plain transaction ID also commits to the order of inputs and outputs, but the canonical ID sorts with an empty seed, so its order might not be the final order. The tag marks the ID as order-independent, so a matching ID does not signal agreement on order. + +[^conflict-ok]: Are there certain keys where it would be acceptable to have conflicting values? Yes (e.g tapleaf BIP 32 sources TODO: get key type), however the PSBTs format forbids multiple enteries. Custom join procedures should require BIP extensions and outside the scope of this BIP. From f412fc6a52f077b0be8f0e959cfc5b5ed106ff01 Mon Sep 17 00:00:00 2001 From: Armin Sabouri Date: Mon, 16 Nov 2026 12:52:30 -0500 Subject: [PATCH 07/11] Fixup: fix typos and spelling --- psbt-concurrent.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/psbt-concurrent.md b/psbt-concurrent.md index f940d32..1360eb1 100644 --- a/psbt-concurrent.md +++ b/psbt-concurrent.md @@ -20,7 +20,7 @@ BIP 370 introduced a *Constructor* role, which allows signaling that the inputs ### `joinpsbts` -Bitcoin Core implements a [`joinpsbts`](https://bitcoincore.org/en/doc/32.0.0/rpc/rawtransactions/joinpsbts/) RPC command that allows merging PSBTs, so long as their input sets are disjoint. For example, if PSBT A spends coin x and B spends y they can be joined however not with PSBT C which spends x as well. In other words, `joinpsbts` is not idompotents with respect to the inputs nor the outputs -- which can lead to over spending. For example, joining a PSBT with distinct inputs but the same outputs will create two identical outputs. Lastly, `joinpsbt` is not associative or commutative because it shuffles. In the concurrent setting this will lead to replicas having divering copies. +Bitcoin Core implements a [`joinpsbts`](https://bitcoincore.org/en/doc/32.0.0/rpc/rawtransactions/joinpsbts/) RPC command that allows merging PSBTs, so long as their input sets are disjoint. For example, if PSBT A spends coin x and B spends y they can be joined however not with PSBT C which spends x as well. In other words, `joinpsbts` is not idempotent with respect to the inputs nor the outputs -- which can lead to over spending. For example, joining a PSBT with distinct inputs but the same outputs will create two identical outputs. Lastly, `joinpsbts` is not associative or commutative because it shuffles. In the concurrent setting this will lead to replicas having diverging copies. ## Specification @@ -214,4 +214,4 @@ Rust implementation: [^canonical-id]: Replicas compare canonical IDs to check that they hold the same data. A plain transaction ID also commits to the order of inputs and outputs, but the canonical ID sorts with an empty seed, so its order might not be the final order. The tag marks the ID as order-independent, so a matching ID does not signal agreement on order. -[^conflict-ok]: Are there certain keys where it would be acceptable to have conflicting values? Yes (e.g tapleaf BIP 32 sources TODO: get key type), however the PSBTs format forbids multiple enteries. Custom join procedures should require BIP extensions and outside the scope of this BIP. +[^conflict-ok]: Are there certain keys where it would be acceptable to have conflicting values? Yes (e.g tapleaf BIP 32 sources TODO: get key type), however the PSBTs format forbids multiple entries. Custom join procedures should require BIP extensions and outside the scope of this BIP. From f80d4e8e7201c857d416f497128c5c8d1aa569cc Mon Sep 17 00:00:00 2001 From: Armin Sabouri Date: Mon, 16 Nov 2026 13:52:24 -0500 Subject: [PATCH 08/11] Fixup: correct output count on merge Merging k outputs removes k-1 maps, so decrementing by k broke the BIP 370 count invariant. --- psbt-concurrent.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/psbt-concurrent.md b/psbt-concurrent.md index 1360eb1..a1fe01d 100644 --- a/psbt-concurrent.md +++ b/psbt-concurrent.md @@ -104,7 +104,7 @@ Outputs are identified by a new `PSBT_OUT_UNIQUE_ID` field, which MUST be 16 byt This ensures that repeated addition of the same output is idempotent, and that if two replicas both attempt to add an identical output (same `PSBT_OUT_AMOUNT` and `PSBT_OUT_SCRIPT`), it will still result in two copies of the output as intended. This is important because a transaction with only a single copy will appear correct but end up losing the value of all missing copies to mining fees. -Outputs with an identical `PSBT_OUT_SCRIPT` MAY be merged deterministically by adding their amounts after sorting. Merging during sorting is NOT allowed, because a merged output has no `PSBT_OUT_UNIQUE_ID`. The merged output takes the position of the first of the outputs it replaces and the `PSBT_GLOBAL_OUTPUT_COUNT` must be decremented by the number of outputs merged. Unique IDs are no longer required once sorted, because outputs are then identified by position. See the next section on ordering. +Outputs with an identical `PSBT_OUT_SCRIPT` MAY be merged deterministically by adding their amounts after sorting. Merging during sorting is NOT allowed, because a merged output has no `PSBT_OUT_UNIQUE_ID`. The merged output takes the position of the first of the outputs it replaces and the `PSBT_GLOBAL_OUTPUT_COUNT` must be decremented by one less than the number of outputs merged. Unique IDs are no longer required once sorted, because outputs are then identified by position. See the next section on ordering. ### Ordering inputs and outputs From 5764c912cbfec2c553eef3659246a1b2b865d834 Mon Sep 17 00:00:00 2001 From: Armin Sabouri Date: Mon, 16 Nov 2026 13:53:18 -0500 Subject: [PATCH 09/11] fixup: add tapleaf allowed words --- cspell/bitcoin-privacy.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/cspell/bitcoin-privacy.txt b/cspell/bitcoin-privacy.txt index 6cea9e4..7b34ed1 100644 --- a/cspell/bitcoin-privacy.txt +++ b/cspell/bitcoin-privacy.txt @@ -24,6 +24,7 @@ RIPEMD scriptSig scriptWitness sighash +tapleaf taptree unlinkability UTXO From e5046b08bd7d97d9dfc17f8bc2e84d78a0aee08a Mon Sep 17 00:00:00 2001 From: Armin Sabouri Date: Mon, 16 Nov 2026 14:19:09 -0500 Subject: [PATCH 10/11] fixup: drop redundant ordered ID sentence --- psbt-concurrent.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/psbt-concurrent.md b/psbt-concurrent.md index a1fe01d..239fd00 100644 --- a/psbt-concurrent.md +++ b/psbt-concurrent.md @@ -155,8 +155,6 @@ For unordered transactions (i.e. `PSBT_GLOBAL_TX_UNORDERED` is set), the `PSBT_G The ID MUST then be computed as the BIP 370 unique ID of the sorted transaction, with the double SHA256 replaced by a BIP 340-style tagged hash with the tag `ConcurrentPSBTUnorderedState`.[^canonical-id] This keeps the ID of an unordered PSBT distinct from the ID of an ordered PSBT with the same contents, even when it has no outputs. -If the PSBT is ordered, the BIP 370 unique ID is used unchanged, without sorting. - ### Divergence and SIGHASH flags Signers MUST sign only using `SIGHASH_ALL`.[^sighash-all] From 4b8375b92490e2804df7bacad393ac70d024b1fa Mon Sep 17 00:00:00 2001 From: Armin Sabouri Date: Mon, 16 Nov 2026 14:23:43 -0500 Subject: [PATCH 11/11] fixup: align omitted derivation flag with mixed mode --- psbt-concurrent.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/psbt-concurrent.md b/psbt-concurrent.md index 239fd00..f8bbdee 100644 --- a/psbt-concurrent.md +++ b/psbt-concurrent.md @@ -132,8 +132,6 @@ If `PSBT_GLOBAL_SORT_KEY_DERIVATION` is set to `0x00`, every input and output MU If the global field `PSBT_GLOBAL_SORT_KEY_DERIVATION` is set to `0x01`, input and output sort keys MUST NOT be set and every sort key is derived (as [defined below](#derivation-rules)) using the `PSBT_GLOBAL_SORT_SEED`. `PSBT_GLOBAL_SORT_SEED` MAY be left unset until sorting, but MUST be set at the time of sorting and contain at least 128 bits of randomness. -If `PSBT_GLOBAL_SORT_KEY_DERIVATION` is omitted, then at the time of sorting either every input and output MUST have an explicit sort key and `PSBT_GLOBAL_SORT_SEED` MUST NOT be set, or `PSBT_GLOBAL_SORT_SEED` MUST be set and explicit sort keys MUST NOT be set. - ##### Derivation rules Sort keys are derived as: @@ -145,7 +143,7 @@ where `H_s` is a BIP 340-style tagged hash, with the tag being `ConcurrentPSBTDe #### Mixed -If `PSBT_GLOBAL_SORT_KEY_DERIVATION` is absent and some subset of inputs and outputs are missing explicit sort keys, then the `PSBT_GLOBAL_SORT_SEED` MUST be set at the time of sorting and is used to derive the missing sort keys.[^mixed-mode] +If `PSBT_GLOBAL_SORT_KEY_DERIVATION` is omitted, explicit sort keys are used where present and every missing sort key is derived.[^mixed-mode] If any input or output is missing an explicit sort key, `PSBT_GLOBAL_SORT_SEED` MUST be set at the time of sorting. If every input and output has an explicit sort key, no sort keys are derived. ### Canonical Identifier