Skip to content

Concurrent psbt rewrite - #78

Draft
arminsabouri wants to merge 11 commits into
mainfrom
concurrent-psbt-rewrite
Draft

arminsabouri wants to merge 11 commits into
mainfrom
concurrent-psbt-rewrite

Conversation

@arminsabouri

@arminsabouri arminsabouri commented Oct 23, 2026 •

Copy link
Copy Markdown
Collaborator

I left both commits so we can see what changed. This ended up being mostly a rewrite of the wording of this BIP to be less jargony and dense. I found the writing to be hard to parse even tho the ideas are quite simple. So no new ideas being presented just a restructing of what was there.

For example, I reconciled all of the background related text into a background subsection.
THere are still many todos and cleanups. But more to rewrite and the flow of ideas can be improved.
i.e:

  • what the current issues are with the combiner and joinpsbt
  • The new fields
  • Strict combining rules for unordered psbts
  • Rules for sorting the pbst
  • thing to be careful about and edge cases
  • reference etc...

Any language specific to collaborative tx construction is treated as outside the scope.
Anything that was removed is in scratch section.

@arminsabouri
arminsabouri force-pushed the concurrent-psbt-rewrite branch from 01cd573 to 1b45dc3 Compare October 23, 2026 19:04
@github-actions

Copy link
Copy Markdown
range-diff for force push 01cd573ddd → 1b45dc344a October 23, 2026 19:04 UTC: 1 modified, 1 unchanged

reproduce: git range-diff b9e78fd..01cd573 b9e78fd..1b45dc3

1:  e8823d9851 = 1:  e8823d9851 Concurrent PSBT spec
2:  01cd573ddd ! 2:  1b45dc344a WIP - cpsbt rewrite
2: 01cd573ddd ! 2: 1b45dc344a WIP - cpsbt rewrite
@@ psbt-concurrent.md: New fields and rules for combining PSBTs in a distributed se
  
 -## Specification
 +Bitcoin Core additionally implements a `joinpsbts` RPC command which does allow merging unique 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.
++`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.
  
 -    creator -> constructor<modifiable, unordered> -> constructor<modifiable> (bip 370) -> updater -> signer -> combiner -> finalizer -> extractor
-+// TODO:
++`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.
  
 -TODO discuss scrubbing after signer and before combiner
 +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$.
@@ psbt-concurrent.md: The new field types for distributed PSBT construction are as
 -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.
-+    creator -> constructor<modifiable, unordered> -> constructor<modifiable> (bip 370) -> updater -> signer -> combiner -> finalizer -> extractor
- 
--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.
 +Example collaborative protocol (*N* wallets). **Creator** and **Constructor** share an empty PSBT with every wallet. Each wallet *i* runs the same pipeline below in parallel. **Combiner**, **Finalizer**, and **Extractor** fan in once all wallets have signed.
 +
 +```mermaid
@@ psbt-concurrent.md: The new field types for distributed PSBT construction are as
 +    COMB --> 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.
+-
 -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).
-+TODO discuss scrubbing after signer and before combiner
- 
+-
 -### 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.
 +#### Strict Combiner
  
--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.
 +BIP 174 lets a Combiner resolve a key that has two different values by picking either one. That is safe when every copy 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 silently change what the transaction spends or pays, and the result depends on the order in which copies were combined.
  
--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.
 +A strict Combiner therefore MUST fail when the same key has conflicting values, whenever bit 0 or bit 1 of `PSBT_GLOBAL_TX_MODIFIABLE` is set. With this rule, the transaction effects of combining a set of PSBTs don't 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.
  
--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.
 +##### Combining unique PSBTs
  
--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
 +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.
  
--#### `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.
 +Inputs or outputs with identical unique IDs are merged by combining their key-value pairs with the stricter, idempotent combination defined above. 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.
  
--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.
 +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.
  
--`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.
 +##### Unique identifiers for inputs
  
--`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$.
 +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.
  
--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
 +##### Unique identifiers for outputs
  
--#### 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.
 +Outputs are identified by a new `PSBT_OUT_UNIQUE_ID` field, which must be universally unique (e.g. 16 bytes of randomness).
  
@@ psbt-concurrent.md: The new field types for distributed PSBT construction are as
 -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.
--
++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.
+ 
 -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.
--
++Unordered PSBTs MUST be shuffled prior to reserialization. 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.
@@ psbt-concurrent.md: The new field types for distributed PSBT construction are as
 -#### 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).
-+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.
- 
+-
 -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.
-+Unordered PSBTs MUST be shuffled prior to reserialization. If all inputs and outputs have [sort keys](#ordering-inputs-and-outputs), the key based ordering may be used instead of shuffling.
- 
+-
 -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.
 +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.
  
@@ psbt-concurrent.md: The new field types for distributed PSBT construction are as
  
  - 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
-+- TODO: 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.
  
@@ psbt-concurrent.md: For consistent ordering we define `PSBT_IN_SORT_KEY` and `PS
 +If `PSBT_GLOBAL_SORT_DETERMINISTIC` is set to `0x00`, explicit sort keys are required to be set and used to sort the 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:
  
 -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).
-+A missing `PSBT_IN_SORT_KEY` is derived as:
-+
 +- `H(PSBT_GLOBAL_SORT_SEED || PSBT_IN_PREVIOUS_TXID || PSBT_IN_OUTPUT_INDEX)` for the inputs
 +- `PSBT_OUT_SORT_KEY` as `H(PSBT_GLOBAL_SORT_SEED || PSBT_OUT_UNIQUE_ID)` for the outputs
 +
@@ psbt-concurrent.md: For consistent ordering we define `PSBT_IN_SORT_KEY` and `PS
 -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..
 +This can provides additional integrity to a collaborative transaction construction protocol, since [`SIGHASH_ALL`](#divergence-and-sighash-flags) signatures must agree on the ordering.
  
- TODO global sort seed || hash of fee contributions or expect application to commit to that in transcript if appropriate?
+-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.
+-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
  
 -### Unique identification of unordered PSBTs
-+### Unique identification
-+
 +A canonical ID MAY be needed to if replicas are attempting to tell if they are holding the same PSBT.
 +For unordered transactions (i.e `PSBT_GLOBAL_TX_UNORDERED` is set), 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).
  
@@ psbt-concurrent.md: TODO: domain separation from PSBT v2, it doesn't make sense
 -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.
 +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.
  
--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 reccomended, 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.
 +That at least makes the txid malleable, so it cannot be used with any protocol that needs pre-signed descendant transactions.
  
--While this would allow limited interoperability among clients, that is not reccomended, 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).
 +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.
  
--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.
@@ scratch (new)
 +
 +- discuss liveness. safety WRT transaction effects is nice but we also want to
 +  minimize irrecoverable failures. discuss both generally and in CRDT section.
++
++
++
++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.
+ \ No newline at end of file

Comment thread psbt-concurrent.md Resolved
Comment thread psbt-concurrent.md Resolved
Comment thread psbt-concurrent.md Resolved
Comment thread psbt-concurrent.md Resolved
Comment thread psbt-concurrent.md Resolved

@oakagent oakagent left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Typos in what this pull request adds:

psbt-concurrent.md

  • l.15 - "integrate information add by either" → "integrate information added by either"
  • l.15 - "intended for for PSBTs" → "intended for PSBTs"
  • l.120 - "the transaction in unordered" → "the transaction is unordered"
  • l.128 - "Ordering inputs and ouputs" → "Ordering inputs and outputs"
  • l.151 - "inidivudal sort seed" → "individual sort seed"
  • l.151 - "determinsitic key" → "deterministic key"
  • l.153 - "to enure consistent" → "to ensure consistent"
  • l.162 - "This can provides" → "This can provide"
  • l.167 - "needed to if replicas" → "needed if replicas"
  • l.170 - "its the same" → "it's the same"
  • l.170 - "same prodcedure" → "same procedure"

oak · automated

@yuval-block yuval-block left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

first review pass, approach ACK, i might have some more comments where i'll be a stickler for particular phrasing but on the whole this looks like a big improvement, thanks!

Comment thread psbt-concurrent.md Resolved
Comment thread psbt-concurrent.md Resolved
Comment thread psbt-concurrent.md Resolved
Comment thread psbt-concurrent.md Resolved
Comment thread psbt-concurrent.md Outdated
#### Strict Combiner

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.
BIP 174 lets a Combiner resolve a key that has two different values by picking either one. That is safe when every copy 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 silently change what the transaction spends or pays, and the result depends on the order in which copies were combined.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"within the scope of bip 174" is a bit more subtle than "shares the same unsigned transaction" because equivocated values may have safety implications... bip 174 stipulates that this could only produce an invalid or valid transaction which is correct in its scope, but for security to carry through more generally may mean more than just "on any equivocation the transaction isn't valid", in particular where some notion of secret sharing is in effect that could potentially lead to subtle bugs like key cancellation, leaking secrets through nonces etc, which is why the strict combiner is a safer baseline (in addition to being a useful definition for our general merging procedure)

Comment thread psbt-concurrent.md Resolved
Comment thread psbt-concurrent.md Resolved
Comment thread psbt-concurrent.md Resolved
@bc1cindy

Copy link
Copy Markdown
Member
Captura de Tela 2026-10-27 às 16 33 44 Captura de Tela 2026-10-27 às 16 34 22 Captura de Tela 2026-10-27 às 16 36 02 Captura de Tela 2026-10-27 às 16 36 43 Captura de Tela 2026-10-27 às 16 37 18 Captura de Tela 2026-10-27 às 16 37 49

Comment thread psbt-concurrent.md Outdated
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.
If `PSBT_GLOBAL_SORT_SEED` is set, any explicit `PSBT_IN_SORT_KEY` or `PSBT_OUT_SORT_KEY` is ignored and replaced by the deterministic key defined above.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sort-seed rule contradicts explicit-key fallback

Line 151 says any explicit PSBT_IN_SORT_KEY/PSBT_OUT_SORT_KEY is ignored whenever PSBT_GLOBAL_SORT_SEED is set, but line 40 says the seed derives keys only when explicit keys are absent and line 141 derives only omitted keys. With both present, the table keeps explicit keys while line 151 discards them, so replicas can order differently and produce divergent unsigned transactions.

oak · automated · 626af58

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

the reason for allowing mixed stuff is so that explicit positions can still be specified for some of the elements

for example if trading ordinals or whatever, with same sized inputs and outputs, these can be specified to have sort keys low numerical values that are in correspondence, while leaving the non shitcoin inputs & outputs without a sort key and allowing those to be derived

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The mixed case you describe is exactly what line 151 still contradicts: it says that when PSBT_GLOBAL_SORT_SEED is set, any explicit PSBT_IN_SORT_KEY or PSBT_OUT_SORT_KEY is ignored and replaced by the derived key. That would discard the low explicit keys you want for the ordinal inputs and outputs, while line 141 only derives the omitted ones. To support the intent, line 151 needs to honor explicit keys and derive only the missing ones.

oak · automated

Comment thread scratch Resolved
Comment thread psbt-concurrent.md Resolved
@xstoicunicornx xstoicunicornx mentioned this pull request Nov 9, 2026
10 tasks
@arminsabouri
arminsabouri force-pushed the concurrent-psbt-rewrite branch from 626af58 to 5c3da4e Compare November 9, 2026 18:37
@github-actions

github-actions Bot commented Nov 9, 2026

Copy link
Copy Markdown
range-diff for force push 626af58c21 → 5c3da4ee66 November 9, 2026 18:38 UTC: 1 modified, 1 unchanged, 1 dropped

reproduce: git range-diff b9e78fd..626af58 cbb5404..5c3da4e

1:  e8823d9851 = 1:  d096f2c23f Concurrent PSBT spec
2:  1b45dc344a ! 2:  5c3da4ee66 WIP - cpsbt rewrite
3:  626af58c21 < -:  ---------- fixup! WIP - cpsbt rewrite
2: 1b45dc344a ! 2: 5c3da4ee66 WIP - cpsbt rewrite
@@ psbt-concurrent.md: New fields and rules for combining PSBTs in a distributed se
  ## 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 only need to agree on which inputs it spends and which outputs it creates. They don't need to agree on the order in which those inputs and outputs were added. This document defines an order insensitive merging procedure which generalizes the *Combiner* role (defined in BIP 174) to non-identical PSBTs which may still overlap in some of their data. A consistent ordering procedure is also defined for producing a consistent PSBT which can subsequently be manipulated using the normal BIP 174 roles.
-+
-+## Background
-+
-+### BIP 174 Combiner
-+
-+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.
-+
-+### BIP 370 Constructor
++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, since consensus requires a specific order. They don't need to agree on the order in which those inputs and outputs were added. This document defines a strict *Combiner*, an order-insensitive merging procedure which restricts the *Combiner* role (defined in BIP 174) by failing on conflicting values, and extends it to non-identical PSBTs which may still overlap in some of their data. A consistent ordering procedure is also defined for producing a consistent PSBT which can subsequently be manipulated using the normal BIP 174 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.
+-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.
-+### `joinpsbts` vs. the Combiner role
++### BIP 174 Combiner
  
 -## Specification
-+Bitcoin Core additionally implements a `joinpsbts` RPC command which does allow merging unique PSBTs, so long as their spent output sets are disjoint.
++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 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.
++
++### `joinpsbts`
  
 -TODO diagram for the combined state machine, indicate when downconversion (to v2 or v0) can happen
-+`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.
++Bitcoin Core implements a [`joinpsbts`](https://bitcoincore.org/en/doc/30.0.0/rpc/rawtransactions/joinpsbts/) RPC command which does allow merging PSBTs, so long as their spent output sets are disjoint.
  
 -    creator -> constructor<modifiable, unordered> -> constructor<modifiable> (bip 370) -> updater -> signer -> combiner -> finalizer -> extractor
++`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.
  
 -TODO discuss scrubbing after signer and before combiner
-+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$.
++`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.
 +
 +## Specification
  
  The new field types for distributed PSBT construction are as follows:
  
 @@ psbt-concurrent.md: The new field types for distributed PSBT construction are as follows:
- | 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. |
+ 
+ | 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 a value `0x03` to indicate inputs and outputs are unordered. |
  | Sort Seed | `PSBT_GLOBAL_SORT_SEED = TBD` | None | No key data | `<bytes globalseed>` | 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. |
+-| 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` | `<bytes input unique id>` | `PSBT_IN_UNIQUE_ID`  of an input removed from the logical input set. | None | No value data. |
 -| Removed Output | `PSBT_GLOBAL_REMOVED_OUTPUT = TBD` | `<bytes output unique id>` | `PSBT_OUT_UNIQUE_ID` removed from the logical output set. | None | No value data. |
++| 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. |
  
  ### New per-input types
  
+ | Name | `keytype` | `keydata` | `keydata` Description | `valuedata` | `valuedata` Description |
+ | --- | --- | --- | --- | --- | --- |
+ | Input Sort Key | `PSBT_IN_SORT_KEY = TBD` | None | No key data | `<bytes sort key>` | Arbitrary lexicographically comparable value used to order inputs. |
+-| Input Unique ID | `PSBT_IN_UNIQUE_ID = TBD` | None | No key data | `<bytes unique id>` | Optional unique suffix for outpoint identity, used for input removal extensions. |
+ 
+ ### New per-output types
+ 
 @@ psbt-concurrent.md: The new field types for distributed PSBT construction are as follows:
  | Output Unique ID | `PSBT_OUT_UNIQUE_ID = TBD` | None | No key data | `<bytes unique id>` | Universally unique identifier for output map identity under unordered output semantics. |
  | Output Sort Key | `PSBT_OUT_SORT_KEY = TBD` | None | No key data | `<bytes sort key>` | 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.
 +Example collaborative protocol (*N* wallets). **Creator** and **Constructor** share an empty PSBT with every wallet. Each wallet *i* runs the same pipeline below in parallel. **Combiner**, **Finalizer**, and **Extractor** fan in once all wallets have signed.
-+
+ 
+-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.
 +```mermaid
-+flowchart TB
++flowchart LR
 +    subgraph init ["Creator / Constructor"]
 +        EMPTY[empty PSBT]
 +    end
 +    EMPTY -->|Distribute to wallets| Pop
-+
+ 
+-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.
 +    subgraph Wi ["Wallet i (i = 1..N)"]
-+        direction TB
-+        Pop[PSBT populate with Wallet i's inputs and outputs]
++        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 -->|cleared PSBT_GLOBAL_TX_UNORDERED bit| Clear[Sorted inputs and outputs]
 +        subgraph us ["Updater / Signer"]
@@ psbt-concurrent.md: The new field types for distributed PSBT construction are as
 +        end
 +        Clear -->|Downcast to BIP 370| SIG
 +    end
-+
+ 
+-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.
 +    subgraph combine ["Combiner"]
 +        COMB[N signed PSBTs]
 +    end
-+
+ 
+-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 finish ["Finalizer / Extractor"]
 +        SIGNED[signed tx]
 +    end
-+
+ 
+-### Combiner role and transaction effects
 +    SIG --> COMB
 +    COMB --> 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.
--
--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.
-+#### Strict Combiner
++### Strict Combiner
  
 -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.
-+BIP 174 lets a Combiner resolve a key that has two different values by picking either one. That is safe when every copy 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 silently change what the transaction spends or pays, and the result depends on the order in which copies were combined.
++BIP 174 lets a 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.
  
 -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.
-+A strict Combiner therefore MUST fail when the same key has conflicting values, whenever bit 0 or bit 1 of `PSBT_GLOBAL_TX_MODIFIABLE` is set. With this rule, the transaction effects of combining a set of PSBTs don't 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.
++A strict Combiner therefore MUST fail when the same key has conflicting values, whenever bit 0 or bit 1 of `PSBT_GLOBAL_TX_MODIFIABLE` is set. 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.
  
 -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.
-+##### Combining unique PSBTs
++#### Combining PSBTs
  
 -#### `joinpsbts` vs. the Combiner role
 +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.
  
 -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.
-+Inputs or outputs with identical unique IDs are merged by combining their key-value pairs with the stricter, idempotent combination defined above. 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.
++Inputs or outputs with identical unique IDs are merged by combining their key-value pairs with the stricter, idempotent combination defined above. 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.
  
 -`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.
-+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.
++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.
  
 -`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.
-+##### Unique identifiers for inputs
++#### Unique identifiers for inputs
  
 -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$.
-+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.
  
 -#### Strict Combiner
-+##### Unique identifiers for outputs
++#### Unique identifiers for outputs
  
 -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.
-+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).
  
 -Exceptions to this are detailed in the next sections, preserving idempotence, commutativity and associativity.
-+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, but that if two different distributed constructors 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.
  
 -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.
-+// TODO: if we merge two output how do we decide which id identifies the new one with the usmmer value?
-+Outputs with an identical `PSBT_OUT_SCRIPT` MAY 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, during or after sorting, using BIP 370 construction rules. Unique IDs are no longer required once sorted, because outputs are then identified by position. See the next section on ordering.
  
  ### 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.
-+Reordering a transaction's inputs or outputs does not change which coins it spends or which payments it creates. Treating them as unordered sets, rather than ordered lists, is what lets us combine 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.
- 
+-
+-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.
-+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.
- 
+-
 -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.
-+Unordered PSBTs MUST be shuffled prior to reserialization. If all inputs and outputs have [sort keys](#ordering-inputs-and-outputs), the key based ordering may be used instead of shuffling.
++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.
  
 -[fn:Join is implicitly defined on equivalence class of all permutations of inputs/outputs, but the PSBT contents is a random representative.
--
++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 is unordered.[^1]
+ 
 -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.
--
++Unordered PSBTs MUST be shuffled prior to reserialization.[^2] If all inputs and outputs have [sort keys](#ordering-inputs-and-outputs), the key-based ordering MAY be used instead of shuffling.
+ 
 -#### Combining PSBTs with different identities
--
++### Ordering inputs and outputs
+ 
 -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.
@@ psbt-concurrent.md: The new field types for distributed PSBT construction are as
 -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.
--
++- 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)
+ 
 -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.
-+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.
++Clearing the `PSBT_GLOBAL_TX_UNORDERED` field indicates 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.
  
- ### Ordering inputs and ouputs
+-### Ordering inputs and ouputs
++// TODO: how can this be a MAY (it feels like it should be a MUST)
++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. Sort keys MUST always be unique.
  
- - 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)
+-- 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
++There are two ways of setting the sort keys:
  
- 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 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.
++#### Individual sort keys
  
-@@ psbt-concurrent.md: For consistent ordering we define `PSBT_IN_SORT_KEY` and `PSBT_OUT_SORT_KEY` fie
+-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.
++// TODO: and sort key must not be set? and you have both PSBT_GLOBAL_SORT_DETERMINISTIC and SORT_SEED?
++If `PSBT_GLOBAL_SORT_DETERMINISTIC` is set to `0x00`, explicit sort keys are required to be set and used to sort the inputs and outputs prior to clearing the `PSBT_GLOBAL_TX_UNORDERED` field, thus fixing the transaction order.
  
- 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 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.
++#### Generated from global sort seed
  
 -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: and sort key must not be set? and you have both PSBT_GLOBAL_SORT_DETERMINISTIC and SORT_SEED?
-+If `PSBT_GLOBAL_SORT_DETERMINISTIC` is set to `0x00`, explicit sort keys are required to be set and used to sort the 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:
++If the global field `PSBT_GLOBAL_SORT_DETERMINISTIC` is set to `0x01`, then input and output sort keys MUST NOT be set. `PSBT_GLOBAL_SORT_SEED` MAY be left unset until the sorting, but MUST be set at the time of sorting and contain at least 128 bits of randomness.
  
 -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).
-+- `H(PSBT_GLOBAL_SORT_SEED || PSBT_IN_PREVIOUS_TXID || PSBT_IN_OUTPUT_INDEX)` for the inputs
-+- `PSBT_OUT_SORT_KEY` as `H(PSBT_GLOBAL_SORT_SEED || PSBT_OUT_UNIQUE_ID)` for the outputs
-+
-+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 `PSBT_IN_SORT_KEY` or `PSBT_OUT_SORT_KEY` is omitted, the global `PSBT_GLOBAL_SORT_SEED` field MUST be set, and `PSBT_GLOBAL_SORT_DETERMINISTIC` MUST be either omitted or set to `0x01`. The sort keys are derived deterministically. If `PSBT_GLOBAL_SORT_SEED` is set, any explicit `PSBT_IN_SORT_KEY` or `PSBT_OUT_SORT_KEY` is ignored and replaced by the deterministic key defined below.
  
- If any sort key is missing, ordering can only proceed after `PSBT_GLOBAL_SORT_SEED` is set.
-+If `PSBT_GLOBAL_SORT_SEED` is set and an individual field-level sort seed is set. The inidivudal sort seed will be ignored and replaced by the determinsitic key defined above.
+-If any sort key is missing, ordering can only proceed after `PSBT_GLOBAL_SORT_SEED` is set.
++Sort keys are derived as:
  
- A *Creator* creating an unordered transaction SHOULD set `PSBT_GLOBAL_SORT_DETERMINISTIC` to enure consistent ordering rules are enforced.
+-A *Creator* creating an unordered transaction SHOULD set `PSBT_GLOBAL_SORT_DETERMINISTIC` to enure consistent ordering rules are enforced.
++- `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)`
  
 -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$.
-+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 or something similar.
++where `H_s` is a BIP 341-style tagged hash, with the tag being `ConcurrentPSBTDeterministicOrdering`.
  
 -This can provides additional integrity to a collaborative transaction construction protocol, since [`SIGHASH_ALL`](#divergence-and-sighash-flags) signatures must agree on the ordering.
-+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.
++#### Creator Responsibility // TODO: better header
  
 -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).
-+// TODO move to footer.
-+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$.
++A *Creator* intending to enforce consistent ordering via `PSBT_GLOBAL_SORT_SEED` SHOULD set `PSBT_GLOBAL_SORT_DETERMINISTIC`.
  
 -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..
-+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 the protocol transcript or something similar.
  
 -TODO global sort seed || hash of fee contributions or expect application to commit to that in transcript if appropriate?
++If that is not the case, the *Creator* SHOULD initialize `PSBT_GLOBAL_SORT_SEED` with sufficient randomness, thereby ensuring some order can always be determined, or set `PSBT_GLOBAL_SORT_DETERMINISTIC` to `0x00` to indicate explicit sort keys are required.[^3]
  
 -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
  
 -### Unique identification of unordered PSBTs
-+A canonical ID MAY be needed to if replicas are attempting to tell if they are holding the same PSBT.
-+For unordered transactions (i.e `PSBT_GLOBAL_TX_UNORDERED` is set), 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).
++A canonical ID may be needed if replicas are attempting to tell if they are holding the same PSBT.
++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).
  
 -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).
-+In the case the PSBT is ordered, its the same prodcedure just no sorting.
++If the PSBT is ordered, the same procedure applies, without sorting.
  
  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.
  
-@@ psbt-concurrent.md: TODO: domain separation from PSBT v2, it doesn't make sense to treat an ordered
- 
- Signers MUST sign only using `SIGHASH_ALL`.
+ ### 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.
@@ psbt-concurrent.md: TODO: domain separation from PSBT v2, it doesn't make sense
 -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 inadvertantly authorized, the full output list should always be comitted 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).
--
++Signers MUST sign only using `SIGHASH_ALL`.[^4]
+ 
 -### Confirmation of successful payment prior to signing
--
++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.
+ 
 -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.
--
++That at least makes the transaction id malleable, so it cannot be used with any protocol that needs pre-signed descendant transactions.
+ 
 -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 comitting 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.
@@ psbt-concurrent.md: TODO: domain separation from PSBT v2, it doesn't make sense
 -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.
-+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.
- 
+-
 -While this would allow limited interoperability among clients, that is not reccomended, 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.
-+That at least makes the txid malleable, so it cannot be used with any protocol that needs pre-signed descendant transactions.
- 
+-
 -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).
-+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.
- 
+-
 -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-concurrent.md: TODO: domain separation from PSBT v2, it doesn't make sense
 -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.
-+Rationale: No known use cases for these flags in true multiparty transactions (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).
++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
  
-@@ psbt-concurrent.md: In order to ensure the least upper bound of any two inputs under consideration n
+-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.
+ 
+-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.
++In order to ensure the least upper bound of any two inputs under consideration can not only be defined but also corresponds 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.
  
@@ psbt-concurrent.md: In order to ensure the least upper bound of any two inputs u
 -  - 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)
--
++## Backwards Compatibility
+ 
 -inputs before outputs?
 -only rely on payment ACKs
--
- ## Rationale
++This proposal does not specify a new PSBT version. It is compatible with both BIP 174 and BIP 370.
++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 (`PSBT_IN_PREVIOUS_TXID` and `PSBT_IN_OUTPUT_INDEX`) and output (`PSBT_OUT_AMOUNT` and `PSBT_OUT_SCRIPT`) maps.
  
-+TODO global sort seed || hash of fee contributions or expect application to commit to that in transcript if appropriate?
-+
- ## Backwards Compatibility
+-## Rationale
++Existing software will not be able to parse new fields. New PSBT clients may encode and decode the new fields in proprietary fields.
+ 
+-## Backwards Compatibility
++While `PSBT_GLOBAL_TX_UNORDERED` is set, PSBTs MUST only be combined by a strict Combiner, not the BIP 174 Combiner. Once `PSBT_GLOBAL_TX_UNORDERED` is cleared the PSBT may be "downcast" to BIP 370 or BIP 174 at the caller's choosing. None of the new fields need to be set.
  
  ## Reference Implementation
--
+ 
 ----
--
++// TODO
+ 
 -# TODO
--
++## Test Vectors
+ 
 -- new PSBT version?
 -  - con: new PSBT version
 -    pro: deserializing unordered txns in psbtv2 will error instead of
 -    potentially leaking unshuffled input/output order
--
++// TODO
+ 
 -- Move inline rationales to their own section
--
++[^1]: Since there is no known use case that requires inputs or outputs 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.
+ 
 -- 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.
--
++[^2]: 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.
+ 
 ----
--
++[^3]: 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 provide additional integrity to a collaborative transaction construction protocol, since [`SIGHASH_ALL`](#divergence-and-sighash-flags) signatures must agree on the ordering.
+ 
 -- discuss liveness. safety WRT transaction effects is nice but we also want to
 -  minimize irrecoverable failures. discuss both generally and in CRDT section.
++[^4]: There are no known use cases for these flags in true multiparty transactions (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).
 
  ## scratch (new) ##
 @@
@@ scratch (new)
 +
 +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 comitting 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.
++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 recevier 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 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.
 +
@@ scratch (new)
 +
 +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 reccomended, 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.
++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).
 +
@@ scratch (new)
 +
 +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 partcipants can be restricted via some external mechanism.
++assumes the number of participants can be restricted via some external mechanism.
 +
 +==== no version of any document needs this information
 +
@@ scratch (new)
 +- discuss liveness. safety WRT transaction effects is nice but we also want to
 +  minimize irrecoverable failures. discuss both generally and in CRDT section.
 +
++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.
 +
++## Rationale
 +
 +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.
- \ No newline at end of file

@xstoicunicornx xstoicunicornx mentioned this pull request Nov 9, 2026
11 tasks
@xstoicunicornx xstoicunicornx linked an issue Nov 9, 2026 that may be closed by this pull request
11 tasks

@oakagent oakagent left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This PR builds on work that is not on main yet (d096f2c ('Concurrent PSBT spec') from #80 (draft)). Setting its base to draft, or waiting for that work to land, keeps the diff to this PR's own commits.

oak · automated · 5c3da4e

Comment thread psbt-concurrent.md Resolved
Comment thread scratch Resolved
Comment thread psbt-concurrent.md Resolved
@arminsabouri
arminsabouri force-pushed the concurrent-psbt-rewrite branch from 5c3da4e to 7217c06 Compare November 9, 2026 21:02
@github-actions

github-actions Bot commented Nov 9, 2026

Copy link
Copy Markdown
range-diff for force push 5c3da4ee66 → 7217c065df November 9, 2026 21:03 UTC: 1 modified, 1 unchanged

reproduce: git range-diff cbb5404..5c3da4e cbb5404..7217c06

1:  d096f2c23f = 1:  d096f2c23f Concurrent PSBT spec
2:  5c3da4ee66 ! 2:  7217c065df WIP - cpsbt rewrite
2: 5c3da4ee66 ! 2: 7217c065df WIP - cpsbt rewrite
@@ Metadata
  ## Commit message ##
     WIP - cpsbt rewrite
 
+ ## cspell/bitcoin-privacy.txt ##
+@@ cspell/bitcoin-privacy.txt: taptree
+ unlinkability
+ UTXO
+ xpub
++ANYONECANPAY
++globalseed
++joinpsbts
++keydata
++Kickstarter
++nlocktime
++reserialization
++unrepresentable
++valuedata
+
  ## psbt-concurrent.md ##
-@@ psbt-concurrent.md: New fields and rules for combining PSBTs in a distributed setting. This provides
+@@
+ 
+ ## 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.
++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 the 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.
-+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, since consensus requires a specific order. They don't need to agree on the order in which those inputs and outputs were added. This document defines a strict *Combiner*, an order-insensitive merging procedure which restricts the *Combiner* role (defined in BIP 174) by failing on conflicting values, and extends it to non-identical PSBTs which may still overlap in some of their data. A consistent ordering procedure is also defined for producing a consistent PSBT which can subsequently be manipulated using the normal BIP 174 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, since consensus requires a specific order. They don't need to agree on the order in which those inputs and outputs were added. This document defines a strict *Combiner*, an order-insensitive merging procedure which restricts the *Combiner* role (defined in BIP 174) by failing on conflicting values, and extends it to non-identical PSBTs which may still overlap in some of their data. An ordering procedure is also defined for producing a consistent PSBT which can subsequently be manipulated using the normal BIP 174 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.
 +## Background
@@ psbt-concurrent.md: New fields and rules for combining PSBTs in a distributed se
 +### 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 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
 +
@@ psbt-concurrent.md: The new field types for distributed PSBT construction are as
  | 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 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 | `<bytes globalseed>` | 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` | `<bytes input unique id>` | `PSBT_IN_UNIQUE_ID`  of an input removed from the logical input set. | None | No value data. |
@@ psbt-concurrent.md: The new field types for distributed PSBT construction are as
 +Outputs are identified by a new `PSBT_OUT_UNIQUE_ID` field, which MUST be universally unique (e.g. 16 bytes of randomness).
  
 -Exceptions to this are detailed in the next sections, preserving idempotence, commutativity and associativity.
-+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_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.
++This ensures that repeated addition of the same output is idempotent, and 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.
  
 -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.
 +Outputs with an identical `PSBT_OUT_SCRIPT` MAY be merged deterministically by adding their amounts, during or after sorting, using BIP 370 construction rules. Unique IDs are no longer required once sorted, because outputs are then identified by position. See the next section on ordering.
@@ psbt-concurrent.md: The new field types for distributed PSBT construction are as
 -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.
-+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.
- 
+-
 -[fn:Join is implicitly defined on equivalence class of all permutations of inputs/outputs, but the PSBT contents is a random representative.
-+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 is unordered.[^1]
++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.
  
 -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.
-+Unordered PSBTs MUST be shuffled prior to reserialization.[^2] If all inputs and outputs have [sort keys](#ordering-inputs-and-outputs), the key-based ordering MAY be used instead of shuffling.
++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 is unordered.[^1]
  
 -#### Combining PSBTs with different identities
-+### Ordering inputs and outputs
++Unordered PSBTs MUST be shuffled prior to reserialization.[^2] If all inputs and outputs have [sort keys](#ordering-inputs-and-outputs), the key-based ordering MAY be used instead of shuffling.
  
 -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.
 -
@@ psbt-concurrent.md: The new field types for distributed PSBT construction are as
 -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.
-+- 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)
- 
+-
 -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.
-+Clearing the `PSBT_GLOBAL_TX_UNORDERED` field indicates 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.
- 
+-
 -### Ordering inputs and ouputs
-+// TODO: how can this be a MAY (it feels like it should be a MUST)
-+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. Sort keys MUST always be unique.
++### 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)
+ - 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
-+There are two ways of setting the sort keys:
- 
+-
 -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.
-+#### Individual sort keys
  
 -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.
-+// TODO: and sort key must not be set? and you have both PSBT_GLOBAL_SORT_DETERMINISTIC and SORT_SEED?
-+If `PSBT_GLOBAL_SORT_DETERMINISTIC` is set to `0x00`, explicit sort keys are required to be set and used to sort the inputs and outputs prior to clearing the `PSBT_GLOBAL_TX_UNORDERED` field, thus fixing the transaction order.
++Clearing the `PSBT_GLOBAL_TX_UNORDERED` field indicates 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.
  
 -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.
-+#### Generated from global sort seed
++// TODO: how can this be a MAY (it feels like it should be a MUST)
++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 `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 the global field `PSBT_GLOBAL_SORT_DETERMINISTIC` is set to `0x01`, then input and output sort keys MUST NOT be set. `PSBT_GLOBAL_SORT_SEED` MAY be left unset until the sorting, but MUST be set at the time of sorting and contain at least 128 bits of randomness.
++There are two ways of setting the sort keys:
  
 -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 `PSBT_IN_SORT_KEY` or `PSBT_OUT_SORT_KEY` is omitted, the global `PSBT_GLOBAL_SORT_SEED` field MUST be set, and `PSBT_GLOBAL_SORT_DETERMINISTIC` MUST be either omitted or set to `0x01`. The sort keys are derived deterministically. If `PSBT_GLOBAL_SORT_SEED` is set, any explicit `PSBT_IN_SORT_KEY` or `PSBT_OUT_SORT_KEY` is ignored and replaced by the deterministic key defined below.
++#### Individual sort keys
  
 -If any sort key is missing, ordering can only proceed after `PSBT_GLOBAL_SORT_SEED` is set.
-+Sort keys are derived as:
++If `PSBT_GLOBAL_SORT_DETERMINISTIC` is set to `0x00`, explicit sort keys are required to be set and used to sort the inputs and outputs prior to clearing the `PSBT_GLOBAL_TX_UNORDERED` field, thus fixing the transaction order.
  
 -A *Creator* creating an unordered transaction SHOULD set `PSBT_GLOBAL_SORT_DETERMINISTIC` to enure consistent ordering rules are enforced.
-+- `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)`
++#### Generated from global sort seed
  
 -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$.
-+where `H_s` is a BIP 341-style tagged hash, with the tag being `ConcurrentPSBTDeterministicOrdering`.
++If the global field `PSBT_GLOBAL_SORT_DETERMINISTIC` is set to `0x01`, then input and output sort keys MUST NOT be set. `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.[^3]
  
 -This can provides additional integrity to a collaborative transaction construction protocol, since [`SIGHASH_ALL`](#divergence-and-sighash-flags) signatures must agree on the ordering.
-+#### Creator Responsibility // TODO: better header
++If any `PSBT_IN_SORT_KEY` or `PSBT_OUT_SORT_KEY` is omitted, the global `PSBT_GLOBAL_SORT_SEED` field MUST be set, and `PSBT_GLOBAL_SORT_DETERMINISTIC` MUST be either omitted or set to `0x01`. The sort keys are derived deterministically. If `PSBT_GLOBAL_SORT_SEED` is set, any explicit `PSBT_IN_SORT_KEY` or `PSBT_OUT_SORT_KEY` is ignored and replaced by the deterministic key defined below.
  
 -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).
-+A *Creator* intending to enforce consistent ordering via `PSBT_GLOBAL_SORT_SEED` SHOULD set `PSBT_GLOBAL_SORT_DETERMINISTIC`.
++Sort keys are derived as:
  
 -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..
-+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 the protocol transcript or something similar.
++- `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)`
  
 -TODO global sort seed || hash of fee contributions or expect application to commit to that in transcript if appropriate?
-+If that is not the case, the *Creator* SHOULD initialize `PSBT_GLOBAL_SORT_SEED` with sufficient randomness, thereby ensuring some order can always be determined, or set `PSBT_GLOBAL_SORT_DETERMINISTIC` to `0x00` to indicate explicit sort keys are required.[^3]
++where `H_s` is a BIP 341-style tagged hash, with the tag being `ConcurrentPSBTDeterministicOrdering`.[^4]
  
 -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
  
 -### Unique identification of unordered PSBTs
 +A canonical ID may be needed if replicas are attempting to tell if they are holding the same PSBT.
-+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).
++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).
  
 -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).
 +If the PSBT is ordered, the same procedure applies, without sorting.
  
- 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.
+-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.
++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
  
@@ psbt-concurrent.md: The new field types for distributed PSBT construction are as
 -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 inadvertantly authorized, the full output list should always be comitted 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).
-+Signers MUST sign only using `SIGHASH_ALL`.[^4]
++Signers MUST sign only using `SIGHASH_ALL`.[^5]
  
 -### Confirmation of successful payment prior to signing
 +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.
  
 -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.
-+That at least makes the transaction id malleable, so it cannot be used with any protocol that needs pre-signed descendant transactions.
++That at least makes the transaction ID malleable, so it cannot be used with any protocol that needs pre-signed descendant transactions.
  
 -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 comitting 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.
 -
@@ psbt-concurrent.md: The new field types for distributed PSBT construction are as
  #### 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.
 +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.
+-#### Size Limits
 +In order to ensure the least upper bound of any two inputs under consideration can not only be defined but also corresponds 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
--
++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.
+ 
 -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 partcipants can be restricted via some external mechanism.
@@ psbt-concurrent.md: The new field types for distributed PSBT construction are as
 -inputs before outputs?
 -only rely on payment ACKs
 +This proposal does not specify a new PSBT version. It is compatible with both BIP 174 and BIP 370.
-+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 (`PSBT_IN_PREVIOUS_TXID` and `PSBT_IN_OUTPUT_INDEX`) and output (`PSBT_OUT_AMOUNT` and `PSBT_OUT_SCRIPT`) maps.
++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 (`PSBT_IN_PREVIOUS_TXID` and `PSBT_IN_OUTPUT_INDEX`). However outputs MUST NOT be generated from output maps (`PSBT_OUT_AMOUNT` and `PSBT_OUT_SCRIPT`).
  
 -## Rationale
 +Existing software will not be able to parse new fields. New PSBT clients may encode and decode the new fields in proprietary fields.
  
 -## Backwards Compatibility
-+While `PSBT_GLOBAL_TX_UNORDERED` is set, PSBTs MUST only be combined by a strict Combiner, not the BIP 174 Combiner. Once `PSBT_GLOBAL_TX_UNORDERED` is cleared the PSBT may be "downcast" to BIP 370 or BIP 174 at the caller's choosing. None of the new fields need to be set.
++While `PSBT_GLOBAL_TX_UNORDERED` is set, PSBTs MUST only be combined by a strict Combiner, not the BIP 174 Combiner. Once `PSBT_GLOBAL_TX_UNORDERED` is cleared, the PSBT may be "downcast" to BIP 370 or BIP 174 at the caller's discretion. None of the new fields need to be set.
  
  ## Reference Implementation
  
 ----
 +// TODO
++
++## Test Vectors
  
 -# TODO
-+## Test Vectors
++// TODO
  
 -- new PSBT version?
 -  - con: new PSBT version
 -    pro: deserializing unordered txns in psbtv2 will error instead of
 -    potentially leaking unshuffled input/output order
-+// TODO
++[^1]: Since there is no known use case that requires inputs or outputs 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.
  
 -- Move inline rationales to their own section
-+[^1]: Since there is no known use case that requires inputs or outputs 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.
++[^2]: 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.
  
 -- 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.
-+[^2]: 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.
++[^3]: 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 provide additional integrity to a collaborative transaction construction protocol, since [`SIGHASH_ALL`](#divergence-and-sighash-flags) signatures must agree on the ordering.
  
 ----
-+[^3]: 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 provide additional integrity to a collaborative transaction construction protocol, since [`SIGHASH_ALL`](#divergence-and-sighash-flags) signatures must agree on the ordering.
++[^4]: **Why is `PSBT_GLOBAL_SORT_DETERMINISTIC` needed in addition to `PSBT_GLOBAL_SORT_SEED`?** A *Creator* intending to enforce consistent ordering via `PSBT_GLOBAL_SORT_SEED`, but without a sort seed yet, SHOULD set `PSBT_GLOBAL_SORT_DETERMINISTIC`. In applications where the sort seed is provided later, 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 the protocol transcript or something similar. If that is not the case, the *Creator* SHOULD initialize `PSBT_GLOBAL_SORT_SEED` with sufficient randomness, thereby ensuring some order can always be determined, or set `PSBT_GLOBAL_SORT_DETERMINISTIC` to `0x00` to indicate explicit sort keys are required.
  
 -- discuss liveness. safety WRT transaction effects is nice but we also want to
 -  minimize irrecoverable failures. discuss both generally and in CRDT section.
-+[^4]: There are no known use cases for these flags in true multiparty transactions (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).
++[^5]: There are no known use cases for these flags in true multiparty transactions (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).
 
  ## scratch (new) ##
 @@

@arminsabouri
arminsabouri force-pushed the concurrent-psbt-rewrite branch from 7217c06 to 483db15 Compare November 9, 2026 21:25
@github-actions

github-actions Bot commented Nov 9, 2026

Copy link
Copy Markdown
range-diff for force push 7217c065df → 483db158b2 November 9, 2026 21:25 UTC: 1 modified, 1 unchanged

reproduce: git range-diff cbb5404..7217c06 cbb5404..483db15

1:  d096f2c23f = 1:  d096f2c23f Concurrent PSBT spec
2:  7217c065df ! 2:  483db158b2 WIP - cpsbt rewrite
2: 7217c065df ! 2: 483db158b2 WIP - cpsbt rewrite
@@ psbt-concurrent.md
  ## 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, since consensus requires a specific order. They don't need to agree on the order in which those inputs and outputs were added. This document defines a strict *Combiner*, an order-insensitive merging procedure which restricts the *Combiner* role (defined in BIP 174) by failing on conflicting values, and extends it to non-identical PSBTs which may still overlap in some of their data. An ordering procedure is also defined for producing a consistent PSBT which can subsequently be manipulated using the normal BIP 174 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, since consensus requires a specific order. They don't need to agree on the order in which those inputs and outputs were added. This document defines a strict *Combiner*, an order-insensitive merging procedure which restricts the *Combiner* role (defined in BIP 174) by failing on conflicting values, and extends it to non-identical PSBTs which may still overlap in some of their data. An ordering procedure is also defined for producing a consistent PSBT which can subsequently be manipulated using the normal BIP 174 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.
 +## Background
@@ psbt-concurrent.md: The new field types for distributed PSBT construction are as
  | Output Sort Key | `PSBT_OUT_SORT_KEY = TBD` | None | No key data | `<bytes sort key>` | 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.
 +Example collaborative protocol (*N* wallets). **Creator** and **Constructor** share an empty PSBT with every wallet. Each wallet *i* runs the same pipeline below in parallel. **Combiner**, **Finalizer**, and **Extractor** fan in once all wallets have signed.
  
--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.
+-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.
 +```mermaid
 +flowchart LR
 +    subgraph init ["Creator / Constructor"]
@@ psbt-concurrent.md: The new field types for distributed PSBT construction are as
 +    end
 +    EMPTY -->|Distribute to wallets| Pop
  
--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.
+-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.
 +    subgraph Wi ["Wallet i (i = 1..N)"]
 +        direction LR
 +        Pop[PSBT populated with Wallet i's inputs and outputs]
@@ psbt-concurrent.md: The new field types for distributed PSBT construction are as
 +        Clear -->|Downcast to BIP 370| SIG
 +    end
  
--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.
+-#### `joinpsbts` vs. the Combiner role
 +    subgraph combine ["Combiner"]
 +        COMB[N signed PSBTs]
 +    end
  
--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).
+-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.
 +    subgraph finish ["Finalizer / Extractor"]
 +        SIGNED[signed tx]
 +    end
  
--### Combiner role and transaction effects
+-`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
 +    SIG --> COMB
 +    COMB --> SIGNED
 +```
  
--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.
+-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
 +### Strict Combiner
  
--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.
+-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.
 +BIP 174 lets a 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.
  
--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.
+-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.
 +A strict Combiner therefore MUST fail when the same key has conflicting values, whenever bit 0 or bit 1 of `PSBT_GLOBAL_TX_MODIFIABLE` is set. 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.
  
--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.
+-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.
 +#### Combining PSBTs
  
--#### `joinpsbts` vs. the Combiner role
+-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.
 +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.
  
--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.
+-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.
 +Inputs or outputs with identical unique IDs are merged by combining their key-value pairs with the stricter, idempotent combination defined above. 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.
  
--`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.
-+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.
- 
--`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.
-+#### Unique identifiers for inputs
- 
--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$.
-+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.
- 
--#### Strict Combiner
-+#### Unique identifiers for outputs
- 
--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.
-+Outputs are identified by a new `PSBT_OUT_UNIQUE_ID` field, which MUST be universally unique (e.g. 16 bytes of randomness).
- 
--Exceptions to this are detailed in the next sections, preserving idempotence, commutativity and associativity.
-+This ensures that repeated addition of the same output is idempotent, and 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.
- 
--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.
-+Outputs with an identical `PSBT_OUT_SCRIPT` MAY be merged deterministically by adding their amounts, during or after sorting, using BIP 370 construction rules. Unique IDs are no longer required once sorted, because outputs are then identified by position. See the next section on ordering.
- 
- ### 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.
-+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.
- 
+-
 -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.
-+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 is unordered.[^1]
- 
+-
 -#### Combining PSBTs with different identities
-+Unordered PSBTs MUST be shuffled prior to reserialization.[^2] If all inputs and outputs have [sort keys](#ordering-inputs-and-outputs), the key-based ordering MAY be used instead of shuffling.
- 
+-
 -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
--
++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
--
++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.
--
++Outputs are identified by a new `PSBT_OUT_UNIQUE_ID` field, which MUST be universally unique (e.g. 16 bytes of randomness).
+ 
 -### Ordering inputs and ouputs
-+### Ordering inputs and outputs
++This ensures that repeated addition of the same output is idempotent, and 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.
  
- - 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)
+-- 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.
++Outputs with an identical `PSBT_OUT_SCRIPT` MAY be merged deterministically by adding their amounts, during or after sorting, using BIP 370 construction rules. Unique IDs are no longer required once sorted, because outputs are then identified by position. See the next section on ordering.
  
+-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.
-+Clearing the `PSBT_GLOBAL_TX_UNORDERED` field indicates 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.
- 
+-
 -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.
-+// TODO: how can this be a MAY (it feels like it should be a MUST)
-+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 `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.
-+There are two ways of setting the sort keys:
- 
+-
 -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).
-+#### Individual sort keys
- 
+-
 -If any sort key is missing, ordering can only proceed after `PSBT_GLOBAL_SORT_SEED` is set.
-+If `PSBT_GLOBAL_SORT_DETERMINISTIC` is set to `0x00`, explicit sort keys are required to be set and used to sort the inputs and outputs prior to clearing the `PSBT_GLOBAL_TX_UNORDERED` field, thus fixing the transaction order.
- 
+-
 -A *Creator* creating an unordered transaction SHOULD set `PSBT_GLOBAL_SORT_DETERMINISTIC` to enure consistent ordering rules are enforced.
-+#### Generated from global sort seed
- 
+-
 -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 the global field `PSBT_GLOBAL_SORT_DETERMINISTIC` is set to `0x01`, then input and output sort keys MUST NOT be set. `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.[^3]
- 
+-
 -This can provides additional integrity to a collaborative transaction construction protocol, since [`SIGHASH_ALL`](#divergence-and-sighash-flags) signatures must agree on the ordering.
-+If any `PSBT_IN_SORT_KEY` or `PSBT_OUT_SORT_KEY` is omitted, the global `PSBT_GLOBAL_SORT_SEED` field MUST be set, and `PSBT_GLOBAL_SORT_DETERMINISTIC` MUST be either omitted or set to `0x01`. The sort keys are derived deterministically. If `PSBT_GLOBAL_SORT_SEED` is set, any explicit `PSBT_IN_SORT_KEY` or `PSBT_OUT_SORT_KEY` is ignored and replaced by the deterministic key defined below.
- 
+-
 -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).
-+Sort keys are derived as:
- 
+-
 -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..
-+- `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)`
- 
+-
 -TODO global sort seed || hash of fee contributions or expect application to commit to that in transcript if appropriate?
-+where `H_s` is a BIP 341-style tagged hash, with the tag being `ConcurrentPSBTDeterministicOrdering`.[^4]
- 
+-
 -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
- 
+-
 -### Unique identification of unordered PSBTs
-+A canonical ID may be needed if replicas are attempting to tell if they are holding the same PSBT.
-+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).
- 
+-
 -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).
-+If the PSBT is ordered, the same procedure applies, without sorting.
- 
+-
 -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.
-+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
- 
+-
+-### 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.
@@ psbt-concurrent.md: The new field types for distributed PSBT construction are as
 -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 inadvertantly authorized, the full output list should always be comitted to using `SIGHASH_ALL`.
--
++### Unordered input and output sets
+ 
 -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).
-+Signers MUST sign only using `SIGHASH_ALL`.[^5]
++// TODO: what are we trying to convey in this opening? We can safely strictly combine inputs and outputs while they are unordered. However, once an order is established, this is no longer safe?
  
 -### Confirmation of successful payment prior to signing
-+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.
++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.
  
 -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.
-+That at least makes the transaction ID malleable, so it cannot be used with any protocol that needs pre-signed descendant transactions.
++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 is unordered.[^1]
  
 -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 comitting 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.
--
++Unordered PSBTs MUST be shuffled prior to reserialization.[^2] If all inputs and outputs have [sort keys](#ordering-inputs-and-outputs), the key-based ordering MAY be used instead of shuffling.
+ 
 -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.
--
++### Ordering inputs and outputs
+ 
 -Every recevier 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.
--
++Clearing the `PSBT_GLOBAL_TX_UNORDERED` field indicates 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.
+ 
 -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.
--
++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 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.
--
++`PSBT_GLOBAL_TX_UNORDERED` SHOULD NOT be cleared until all `PSBT_IN_SORT_KEY` and `PSBT_OUT_SORT_KEY` fields are set and the inputs and outputs have been sorted.
+ 
 -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.
--
++There are two ways of setting the sort keys:
+ 
 -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.
--
++#### Individual sort keys
+ 
 -TODO sender/receiver examples, including an example with a receiver that contributes no inputs, only outputs
--
++If `PSBT_GLOBAL_SORT_DETERMINISTIC` is set to `0x00`, explicit sort keys are required to be set and used to sort the inputs and outputs prior to clearing the `PSBT_GLOBAL_TX_UNORDERED` field, thus fixing the transaction order.
+ 
 -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.
--
++#### Generated from global sort seed
+ 
 -### Input or output removal (optional)
--
++If the global field `PSBT_GLOBAL_SORT_DETERMINISTIC` is set to `0x01`, then input and output sort keys MUST NOT be set. `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.[^3]
+ 
 -As in BIP 174, the combination of several PSBTs must contain all the key-value pairs from each of the input PSBTs.
--
++If any `PSBT_IN_SORT_KEY` or `PSBT_OUT_SORT_KEY` is omitted, the global `PSBT_GLOBAL_SORT_SEED` field MUST be set, and `PSBT_GLOBAL_SORT_DETERMINISTIC` MUST be either omitted or set to `0x01`. The sort keys are derived deterministically. If `PSBT_GLOBAL_SORT_SEED` is set, any explicit `PSBT_IN_SORT_KEY` or `PSBT_OUT_SORT_KEY` is ignored and replaced by the deterministic key defined below.
+ 
 -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.
--
++Sort keys are derived as:
+ 
 -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.
--
++- `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)`
+ 
 -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.
--
++where `H_s` is a BIP 341-style tagged hash, with the tag being `ConcurrentPSBTDeterministicOrdering`.[^4]
+ 
 -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.
--
++### Unique identification
+ 
 -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.
--
++A canonical ID may be needed if replicas are attempting to tell if they are holding the same PSBT.
++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).
+ 
 -While this would allow limited interoperability among clients, that is not reccomended, 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.
--
++If the PSBT is ordered, the same procedure applies, without sorting.
+ 
 -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).
--
++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.
+ 
 -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`.[^5]
+ 
 -### 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.
--
--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.
 +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.
  
--#### Size Limits
+-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.
 +In order to ensure the least upper bound of any two inputs under consideration can not only be defined but also corresponds to a valid transaction, the *Creator* role can restrict the domain of spendable inputs before inputs are added.
  
--advisory fields: `MAX_WEIGHT_PER_PARTICIPANT`, `MAX_TRANSACTION_WEIGHT` (default 400000?) - determines max number of participants while also signalling size limit is enforced
+-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.
 +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 partcipants can be restricted via some external mechanism.
 -
 -#### Termination
--
++## Backwards Compatibility
+ 
 -knowing when to proceed to signing
--
++This proposal does not specify a new PSBT version. It is compatible with both BIP 174 and BIP 370.
+ 
 -- global fee contribution
 -  - `PSBT_GLOBAL_EXPLICIT_FEE_CONTRIBUTION`
 -  - keydata = 16 byte uuid
@@ psbt-concurrent.md: The new field types for distributed PSBT construction are as
 -  - 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)
-+## Backwards Compatibility
++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`).
  
 -inputs before outputs?
 -only rely on payment ACKs
-+This proposal does not specify a new PSBT version. It is compatible with both BIP 174 and BIP 370.
-+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 (`PSBT_IN_PREVIOUS_TXID` and `PSBT_IN_OUTPUT_INDEX`). However outputs MUST NOT be generated from output maps (`PSBT_OUT_AMOUNT` and `PSBT_OUT_SCRIPT`).
++Existing software will not be able to parse new fields. New PSBT clients may encode and decode the new fields as proprietary fields.
  
 -## Rationale
-+Existing software will not be able to parse new fields. New PSBT clients may encode and decode the new fields in proprietary fields.
++While `PSBT_GLOBAL_TX_UNORDERED` is set, PSBTs MUST only be combined by a strict Combiner, not the BIP 174 Combiner. Once `PSBT_GLOBAL_TX_UNORDERED` is cleared, the PSBT may be "downcast" to BIP 370 or BIP 174 at the caller's discretion. None of the new fields need to be retained.
  
 -## Backwards Compatibility
-+While `PSBT_GLOBAL_TX_UNORDERED` is set, PSBTs MUST only be combined by a strict Combiner, not the BIP 174 Combiner. Once `PSBT_GLOBAL_TX_UNORDERED` is cleared, the PSBT may be "downcast" to BIP 370 or BIP 174 at the caller's discretion. None of the new fields need to be set.
++Clients implementing the rules specified in this proposal on a BIP 174 PSBT should be careful to order and perform the strict combination on unsigned transaction components as well as the PSBT input and output maps. In general, we recommend that clients use BIP 370 with the rules discussed in this proposal.
  
  ## Reference Implementation

Comment thread psbt-concurrent.md Resolved
Comment thread psbt-concurrent.md Resolved
Comment thread psbt-concurrent.md Resolved
@bc1cindy
bc1cindy requested a review from oakagent November 10, 2026 03:01
Comment thread psbt-concurrent.md Resolved
@arminsabouri
arminsabouri force-pushed the concurrent-psbt-rewrite branch from 483db15 to 37dbb5c Compare November 10, 2026 15:20
@github-actions

Copy link
Copy Markdown
range-diff for force push 483db158b2 → 37dbb5c989 November 10, 2026 15:20 UTC: 2 modified

reproduce: git range-diff cbb5404..483db15 cbb5404..37dbb5c

Some interdiffs were truncated to fit; the full range-diff is in the job summary.

1:  d096f2c23f ! 1:  5e02e9086c Concurrent PSBT spec
2:  483db158b2 ! 2:  37dbb5c989 WIP - cpsbt rewrite
1: d096f2c23f ! 1: 5e02e9086c Concurrent PSBT spec
@@ Metadata
  ## Commit message ##
     Concurrent PSBT spec
 
+ ## cspell/bitcoin-privacy.txt ##
+@@ cspell/bitcoin-privacy.txt: taptree
+ unlinkability
+ UTXO
+ xpub
++ANYONECANPAY
++CRDT
++globalseed
++joinpsbts
++keydata
++Kickstarter
++nlocktime
++psbtv
++reserialization
++standardness
++txns
++unioned
++unrepresentable
++unshuffled
++valuedata
+
  ## psbt-concurrent.md (new) ##
 @@
 +# Concurrent PSBT Construction
@@ psbt-concurrent.md (new)
 +
 +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 ouputs
++### 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
@@ psbt-concurrent.md (new)
 +
 +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 enure consistent ordering rules are enforced.
++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$.
 +
@@ psbt-concurrent.md (new)
 +
 +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 inadvertantly authorized, the full output list should always be comitted to using `SIGHASH_ALL`.
++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).
 +
@@ psbt-concurrent.md (new)
 +
 +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 comitting 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.
++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 recevier 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 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.
 +
@@ psbt-concurrent.md (new)
 +
 +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 reccomended, 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.
++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).
 +
@@ psbt-concurrent.md (new)
 +
 +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 partcipants can be restricted via some external mechanism.
++assumes the number of participants can be restricted via some external mechanism.
 +
 +#### Termination
 +
2: 483db158b2 ! 2: 37dbb5c989 WIP - cpsbt rewrite
@@ Commit message
     WIP - cpsbt rewrite
 
  ## cspell/bitcoin-privacy.txt ##
-@@ cspell/bitcoin-privacy.txt: taptree
- unlinkability
+@@ cspell/bitcoin-privacy.txt: unlinkability
  UTXO
  xpub
-+ANYONECANPAY
-+globalseed
-+joinpsbts
-+keydata
-+Kickstarter
-+nlocktime
-+reserialization
-+unrepresentable
-+valuedata
+ ANYONECANPAY
+-CRDT
+ globalseed
+ joinpsbts
+ keydata
+ Kickstarter
+ nlocktime
+-psbtv
+ reserialization
+-standardness
+-txns
+-unioned
+ unrepresentable
+-unshuffled
+ valuedata
 
  ## psbt-concurrent.md ##
 @@
@@ psbt-concurrent.md
  ## 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, since consensus requires a specific order. They don't need to agree on the order in which those inputs and outputs were added. This document defines a strict *Combiner*, an order-insensitive merging procedure which restricts the *Combiner* role (defined in BIP 174) by failing on conflicting values, and extends it to non-identical PSBTs which may still overlap in some of their data. An ordering procedure is also defined for producing a consistent PSBT which can subsequently be manipulated using the normal BIP 174 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. This document defines a strict *Combiner*, an order-insensitive merging procedure which restricts the *Combiner* role (defined in BIP 174) by failing on conflicting values, and extends it to non-identical PSBTs which may still overlap in some of their data. An ordering procedure is also defined for producing a consistent PSBT which can subsequently be manipulated using the normal BIP 174 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.
 +## Background
@@ psbt-concurrent.md
 +
 +### BIP 370 Constructor
 +
-+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.
++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, 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.
 +
 +### `joinpsbts`
  
@@ psbt-concurrent.md: The new field types for distributed PSBT construction are as
 -| 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` | `<bytes input unique id>` | `PSBT_IN_UNIQUE_ID`  of an input removed from the logical input set. | None | No value data. |
 -| Removed Output | `PSBT_GLOBAL_REMOVED_OUTPUT = TBD` | `<bytes output unique id>` | `PSBT_OUT_UNIQUE_ID` removed from the logical output set. | None | No value data. |
-+| 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. |
++| 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. If absent, explicit sort keys are used where present and the rest are derived. |
  
  ### New per-input types
  
@@ psbt-concurrent.md: The new field types for distributed PSBT construction are as
  | Output Sort Key | `PSBT_OUT_SORT_KEY = TBD` | None | No key data | `<bytes sort key>` | 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.
 +Example collaborative protocol (*N* wallets). **Creator** and **Constructor** share an empty PSBT with every wallet. Each wallet *i* runs the same pipeline below in parallel. **Combiner**, **Finalizer**, and **Extractor** fan in once all wallets have 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.
+-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.
 +```mermaid
 +flowchart LR
 +    subgraph init ["Creator / Constructor"]
@@ psbt-concurrent.md: The new field types for distributed PSBT construction are as
 +    end
 +    EMPTY -->|Distribute to wallets| Pop
  
--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 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.
 +    subgraph Wi ["Wallet i (i = 1..N)"]
 +        direction LR
 +        Pop[PSBT populated with Wallet i's inputs and outputs]
@@ psbt-concurrent.md: The new field types for distributed PSBT construction are as
 +        Clear -->|Downcast to BIP 370| SIG
 +    end
  
--#### `joinpsbts` vs. the Combiner role
+-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.
 +    subgraph combine ["Combiner"]
 +        COMB[N signed PSBTs]
 +    end
  
--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.
+-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 finish ["Finalizer / Extractor"]
 +        SIGNED[signed tx]
 +    end
  
--`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
+-### Combiner role and transaction effects
 +    SIG --> COMB
 +    COMB --> SIGNED
 +```
  
--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
+-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.
 +### Strict Combiner
  
--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.
+-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.
 +BIP 174 lets a 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.
  
--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.
+-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.
 +A strict Combiner therefore MUST fail when the same key has conflicting values, whenever bit 0 or bit 1 of `PSBT_GLOBAL_TX_MODIFIABLE` is set. 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.
  
--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.
+-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.
 +#### Combining PSBTs
  
--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.
+-#### `joinpsbts` vs. the Combiner role
 +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.
  
--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.
+-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.
 +Inputs or outputs with identical unique IDs are merged by combining their key-value pairs with the stricter, idempotent combination defined above. 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.
  
--[fn:Join is implicitly defined on equivalence class of all permutations of inputs/outputs, but the PSBT contents is a random representative.
+-`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.
++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.
+ 
+-`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.
++#### Unique identifiers for inputs
+ 
+-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$.
++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.
+ 
+-#### Strict Combiner
++#### Unique identifiers for outputs
+ 
+-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.
++Outputs are identified by a new `PSBT_OUT_UNIQUE_ID` field, which MUST be universally unique (e.g. 16 bytes of randomness).
+ 
+-Exceptions to this are detailed in the next sections, preserving idempotence, commutativity and associativity.
++This ensures that repeated addition of the same output is idempotent, and 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.
+ 
+-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.
++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` from which to derive its sort key. 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.
+ 
+ ### 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.
 -
--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.
+-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.
++// TODO: what are we trying to convey in this opening? We can safely strictly combine inputs and outputs while they are unordered. However, once an order is established, this is no longer safe?
+ 
+-[fn:Join is implicitly defined on equivalence class of all permutations of inputs/outputs, but the PSBT contents is a random representative.
++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.
+ 
+-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.
++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 is unordered.[^1]
+ 
 -#### 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.
@@ psbt-concurrent.md: The new field types for distributed PSBT construction are as
 -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.
-+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
- 
+-
+-#### 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.
- 
- #### Unique identifiers for outputs
- 
+-
+-#### 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.
-+Outputs are identified by a new `PSBT_OUT_UNIQUE_ID` field, which MUST be universally unique (e.g. 16 bytes of randomness).
++Unordered PSBTs MUST be shuffled prior to reserialization.[^2] If all inputs and outputs have [sort keys](#ordering-inputs-and-outputs), the key-based ordering MAY be used instead of shuffling.
  
--### Ordering inputs and ouputs
-+This ensures that repeated addition of the same output is idempotent, and 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.
+ ### 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
-+Outputs with an identical `PSBT_OUT_SCRIPT` MAY be merged deterministically by adding their amounts, during or after sorting, using BIP 370 construction rules. Unique IDs are no longer required once sorted, because outputs are then identified by position. See the next section on ordering.
++Clearing the `PSBT_GLOBAL_TX_UNORDERED` field indicates 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.
  
 -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, which MAY include up to 32 bytes of arbitrary data, used as a sort key for lexicographical sorting. Sort keys MUST always be unique.
+ 
 -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.
--
++`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 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.
--
++There are three ways of setting the sort keys, selected by `PSBT_GLOBAL_SORT_DETERMINISTIC`:[^3]
+ 
 -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.
--
++#### Individual sort keys
+ 
 -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 `PSBT_GLOBAL_SORT_DETERMINISTIC` 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.
+ 
 -If any sort key is missing, ordering can only proceed after `PSBT_GLOBAL_SORT_SEED` is set.
--
… (truncated)

Comment thread psbt-concurrent.md Resolved
Comment thread psbt-concurrent.md Resolved
Comment thread psbt-concurrent.md Resolved
Comment thread psbt-concurrent.md Resolved
Comment thread psbt-concurrent.md Resolved
@arminsabouri
arminsabouri force-pushed the concurrent-psbt-rewrite branch from 12e3a9f to f7b37fa Compare November 11, 2026 01:50
@github-actions

Copy link
Copy Markdown
range-diff for force push 12e3a9fbc4 → f7b37fa451 November 11, 2026 01:50 UTC: 1 modified, 1 unchanged, 4 dropped

reproduce: git range-diff cbb5404..12e3a9f cbb5404..f7b37fa

1:  5e02e9086c = 1:  5e02e9086c Concurrent PSBT spec
2:  37dbb5c989 ! 2:  f7b37fa451 WIP - cpsbt rewrite
3:  a06c857df4 < -:  ---------- fixup! WIP - cpsbt rewrite
4:  d255ec8e63 < -:  ---------- fixup! fixup! WIP - cpsbt rewrite
5:  920381dd7e < -:  ---------- fixup! fixup! fixup! WIP - cpsbt rewrite
6:  12e3a9fbc4 < -:  ---------- fixup! fixup! fixup! fixup! WIP - cpsbt rewrite
2: 37dbb5c989 ! 2: f7b37fa451 WIP - cpsbt rewrite
@@ psbt-concurrent.md
 +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, 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.
 +
 +### `joinpsbts`
++
++Bitcoin Core implements a [`joinpsbts`](https://bitcoincore.org/en/doc/30.0.0/rpc/rawtransactions/joinpsbts/) RPC command which does allow 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
-+Bitcoin Core implements a [`joinpsbts`](https://bitcoincore.org/en/doc/30.0.0/rpc/rawtransactions/joinpsbts/) RPC command which does allow merging PSBTs, so long as their spent output sets are disjoint.
++`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<modifiable, unordered> -> constructor<modifiable> (bip 370) -> updater -> signer -> combiner -> finalizer -> extractor
-+`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.
  
 -TODO discuss scrubbing after signer and before combiner
-+`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.
-+
 +## Specification
  
  The new field types for distributed PSBT construction are as follows:
@@ psbt-concurrent.md: The new field types for distributed PSBT construction are as
  | Output Sort Key | `PSBT_OUT_SORT_KEY = TBD` | None | No key data | `<bytes sort key>` | 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.
 +Example collaborative protocol (*N* wallets). **Creator** and **Constructor** share an empty PSBT with every wallet. Each wallet *i* runs the same pipeline below in parallel. **Combiner**, **Finalizer**, and **Extractor** fan in once all wallets have signed.
  
--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.
+-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).
 +```mermaid
 +flowchart LR
 +    subgraph init ["Creator / Constructor"]
@@ psbt-concurrent.md: The new field types for distributed PSBT construction are as
 +    end
 +    EMPTY -->|Distribute to wallets| Pop
  
--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.
+-### Combiner role and transaction effects
 +    subgraph Wi ["Wallet i (i = 1..N)"]
 +        direction LR
 +        Pop[PSBT populated with Wallet i's inputs and outputs]
@@ psbt-concurrent.md: The new field types for distributed PSBT construction are as
 +        Clear -->|Downcast to BIP 370| SIG
 +    end
  
--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.
+-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 combine ["Combiner"]
 +        COMB[N signed PSBTs]
 +    end
  
--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).
+-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.
 +    subgraph finish ["Finalizer / Extractor"]
 +        SIGNED[signed tx]
 +    end
  
--### Combiner role and transaction effects
+-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.
 +    SIG --> COMB
 +    COMB --> SIGNED
 +```
  
--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.
-+### Strict Combiner
- 
--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.
-+BIP 174 lets a 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.
- 
--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.
-+A strict Combiner therefore MUST fail when the same key has conflicting values, whenever bit 0 or bit 1 of `PSBT_GLOBAL_TX_MODIFIABLE` is set. 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.
- 
 -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.
-+#### Combining PSBTs
++### Strict Combiner
  
 -#### `joinpsbts` vs. the Combiner role
-+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.
- 
+-
 -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.
-+Inputs or outputs with identical unique IDs are merged by combining their key-value pairs with the stricter, idempotent combination defined above. 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.
- 
+-
 -`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.
-+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.
++BIP 174 lets a 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` 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.
-+#### Unique identifiers for inputs
++A strict Combiner therefore MUST fail when the same key has conflicting values, whenever bit 0 or bit 1 of `PSBT_GLOBAL_TX_MODIFIABLE` is set. 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.
  
 -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$.
-+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.
++#### Combining PSBTs
  
 -#### Strict Combiner
-+#### Unique identifiers for outputs
++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.
  
 -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.
-+Outputs are identified by a new `PSBT_OUT_UNIQUE_ID` field, which MUST be universally unique (e.g. 16 bytes of randomness).
++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.[^1]
  
 -Exceptions to this are detailed in the next sections, preserving idempotence, commutativity and associativity.
-+This ensures that repeated addition of the same output is idempotent, and 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.
++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.
  
 -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.
-+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` from which to derive its sort key. 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.
++Inputs or outputs with identical unique IDs are merged by combining their key-value pairs with the stricter, idempotent combination defined above. 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.
  
- ### Unordered input and output sets
+-### Unordered input and output sets
++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.
  
 -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.
 -
@@ psbt-concurrent.md: The new field types for distributed PSBT construction are as
 -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.
-+// TODO: what are we trying to convey in this opening? We can safely strictly combine inputs and outputs while they are unordered. However, once an order is established, this is no longer safe?
- 
+-
 -[fn:Join is implicitly defined on equivalence class of all permutations of inputs/outputs, but the PSBT contents is a random representative.
-+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.
- 
+-
 -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.
-+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 is unordered.[^1]
- 
+-
 -#### 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.
@@ psbt-concurrent.md: The new field types for distributed PSBT construction are as
 -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
--
++Unordered PSBTs MUST be shuffled prior to reserialization.[^2] 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.
--
--#### Unique identifiers for outputs
--
++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).
--
++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.
-+Unordered PSBTs MUST be shuffled prior to reserialization.[^2] If all inputs and outputs have [sort keys](#ordering-inputs-and-outputs), the key-based ordering MAY be used instead of shuffling.
++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` from which to derive its sort key. 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
  
@@ psbt-concurrent.md: The new field types for distributed PSBT construction are as
 +`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 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.
-+There are three ways of setting the sort keys, selected by `PSBT_GLOBAL_SORT_DETERMINISTIC`:[^3]
++There are two ways of setting the sort keys, selected by `PSBT_GLOBAL_SORT_DETERMINISTIC`:[^3]
  
 -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.
 +#### Individual sort keys
@@ psbt-concurrent.md: The new field types for distributed PSBT construction are as
 +If the global field `PSBT_GLOBAL_SORT_DETERMINISTIC` is set to `0x01`, then input and output sort keys MUST NOT be set. `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.[^4] Every sort key is derived as defined below.
  
 -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$.
-+#### Explicit and derived sort keys
++If `PSBT_GLOBAL_SORT_DETERMINISTIC` is omitted, either explicit sort keys MUST be set or `PSBT_GLOBAL_SORT_SEED` MUST be set at the time of sorting.[^5]
  
 -This can provides additional integrity to a collaborative transaction construction protocol, since [`SIGHASH_ALL`](#divergence-and-sighash-flags) signatures must agree on the ordering.
-+If `PSBT_GLOBAL_SORT_DETERMINISTIC` is omitted, explicit sort keys MAY be set on some inputs and outputs to fix their relative order (e.g. to pair inputs and outputs in an atomic trade, or for compatibility with Lightning interactive transaction construction). Explicit keys are kept, and only omitted keys are derived as defined below. If any sort key is omitted, `PSBT_GLOBAL_SORT_SEED` MUST be set at the time of sorting. Explicit and derived keys are sorted together.[^5]
++// TODO; what to do when modifiable is not set and we have to sort?
  
 -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).
 +Sort keys are derived as:
@@ psbt-concurrent.md: The new field types for distributed PSBT construction are as
 +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.
-+In order to ensure the least upper bound of any two inputs under consideration can not only be 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 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.
  
 -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.
 +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
 +## Backwards Compatibility
  
+-advisory fields: `MAX_WEIGHT_PER_PARTICIPANT`, `MAX_TRANSACTION_WEIGHT` (default 400000?) - determines max number of participants while also signalling size limit is enforced
++// TODO: modifiable flag should be unset when converting to psbtv2
+ 
 -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.
-+// TODO: PSBT version 3 that builds on v2?
++// TODO: rewrite this section as this wraps v2 psbts. with rationale. And downcasting define procedure.
  
 -assumes the number of participants can be restricted via some external mechanism.
-+This proposal does not specify a new PSBT version. It is compatible with both BIP 174 and BIP 370.
++This document does not define a new PSBT version. It extends BIP 370.
  
 -#### Termination
-+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`).
++Existing software cannot parse the new fields. New clients MAY encode and decode them as proprietary fields.
  
 -knowing when to proceed to signing
-+Existing software will not be able to parse new fields. New PSBT clients may encode and decode the new fields as proprietary fields.
++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.
  
 -- global fee contribution
 -  - `PSBT_GLOBAL_EXPLICIT_FEE_CONTRIBUTION`
@@ psbt-concurrent.md: The new field types for distributed PSBT construction are as
 -  - 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)
-+While `PSBT_GLOBAL_TX_UNORDERED` is set, PSBTs MUST only be combined by a strict Combiner, not the BIP 174 Combiner. Once `PSBT_GLOBAL_TX_UNORDERED` is cleared, the PSBT may be "downcast" to BIP 370 or BIP 174 at the caller's discretion. None of the new fields need to 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 caller MAY downcast to BIP 370 or BIP 174. The new fields need not be retained. `PSBT_GLOBAL_TX_MODIFIABLE` does not restrict reordering of input or output maps, and MAY stay set after `PSBT_GLOBAL_TX_UNORDERED` is cleared.
  
 -inputs before outputs?
 -only rely on payment ACKs
-+Clients implementing the rules specified in this proposal on a BIP 174 PSBT should be careful to order and perform the strict combination on unsigned transaction components as well as the PSBT input and output maps. In general, we recommend that clients use BIP 370 with the rules discussed in this proposal.
++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`).
  
 -## Rationale
 +## Reference Implementation
@@ psbt-concurrent.md: The new field types for distributed PSBT construction are as
 +// TODO
  
 -# TODO
-+[^1]: Since there is no known use case that requires inputs or outputs 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.
++[^1]: 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.
  
 -- new PSBT version?
 -  - con: new PSBT version
 -    pro: deserializing unordered txns in psbtv2 will error instead of
 -    potentially leaking unshuffled input/output order
-+[^2]: 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.
++[^2]: 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.
  
 -- Move inline rationales to their own section
-+[^3]: **Why is `PSBT_GLOBAL_SORT_DETERMINISTIC` needed in addition to `PSBT_GLOBAL_SORT_SEED`?** A *Creator* intending to enforce consistent ordering via `PSBT_GLOBAL_SORT_SEED`, but without a sort seed yet, SHOULD set `PSBT_GLOBAL_SORT_DETERMINISTIC`. In applications where the sort seed is provided later, 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 the protocol transcript or something similar. If that is not the case, the *Creator* SHOULD initialize `PSBT_GLOBAL_SORT_SEED` with sufficient randomness, thereby ensuring some order can always be determined, or set `PSBT_GLOBAL_SORT_DETERMINISTIC` to `0x00` to indicate explicit sort keys are required.
++[^3]: Why is `PSBT_GLOBAL_SORT_DETERMINISTIC` 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_DETERMINISTIC`. If the seed is supplied later, the *Creator* SHOULD set `PSBT_GLOBAL_SORT_DETERMINISTIC` 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_DETERMINISTIC` to `0x00` to require explicit sort keys.
  
 -- 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.
-+[^4]: 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 provide additional integrity to a collaborative transaction construction protocol, since [`SIGHASH_ALL`](#divergence-and-sighash-flags) signatures must agree on the ordering.
++[^4]: On a sufficiently large transaction, the ordering (and therefore the per-input signatures) commits cryptographically to `PSBT_GLOBAL_SORT_SEED`. The entropy of an ordering of $n$ elements is $\log_2(n!)$. $\log_2(35!) > 128$, $\log_2(25!) > 80$, and $\log_2(15!) > 40$. [`SIGHASH_ALL`](#divergence-and-sighash-flags) signatures must agree on that ordering, so the commitment binds a collaborative construction protocol.
  
 ----
-+[^5]: Derived sort keys are not necessarily written into the PSBT. They are derived, used to sort, and discarded.
++[^5]: Derived sort keys need not be written into the PSBT. Derive them, sort, and discard them.
  
 -- discuss liveness. safety WRT transaction effects is nice but we also want to
 -  minimize irrecoverable failures. discuss both generally and in CRDT section.
-+[^6]: There are no known use cases for these flags in true multiparty transactions (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).
++[^6]: 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.
 
  ## scratch (new) ##
 @@

Comment thread psbt-concurrent.md Resolved
Comment thread psbt-concurrent.md Resolved
@arminsabouri arminsabouri changed the title WIP - Concurrent psbt rewrite Concurrent psbt rewrite Nov 11, 2026
@arminsabouri
arminsabouri marked this pull request as ready for review November 11, 2026 14:25
Comment thread psbt-concurrent.md
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.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

i think this can be spun off too

BIP 370 has this as an input field (PSBT_IN_REQUIRED_TIME_LOCKTIME vs PSBT_IN_REQUIRED_HEIGHT_LOCKTIME) but if no inputs are present, then that is ambiguous.

this is more like some of the other considerations like malleability, or ensuring no size overflow... in general we can't ensure a join semi lattice whose join will always be consensus valid, without carving out the sub-lattice over which join can be shown to be total, not just because of mutually exclusive locktimes

Comment thread psbt-concurrent.md Resolved
@arminsabouri
arminsabouri marked this pull request as draft November 14, 2026 03:02
Comment thread psbt-concurrent.md Resolved
Comment thread psbt-concurrent.md Outdated
Comment on lines +107 to +109
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.

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.[^7]

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

stoic's rewrite is good, but please split into two paragraphs, i think these cases are different enough that they shouldn't be in the same paragraph.

"when there is a distinct unique identifier" is, apart from sounding redundant in a confusing way (distinct unique), not accurate or at least not well defined.

the correct rule is that if either or both sides are not modifiable, then the union of the identifiers has to be equal to the unmodifiable identifier set (which for both unmodifiable, $A \subseteq B \wedge B \subseteq A \iff A = B$. see fungi-protocol/concurrent-psbt#109 for implementation of this rule.

Comment thread psbt-concurrent.md Outdated
Comment on lines +107 to +109
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.

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.[^7]

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

also please "corresponding PSBT_GLOBAL_TX_MODIFIABLE flag is not set", because there are two relevant flags in there, and they are independent

Comment thread psbt-concurrent.md Resolved
@arminsabouri
arminsabouri force-pushed the concurrent-psbt-rewrite branch from d439466 to 5395d95 Compare November 14, 2026 03:40
@github-actions

Copy link
Copy Markdown
range-diff for force push d439466885 → 5395d955ce November 14, 2026 03:40 UTC: 1 modified, 1 unchanged

reproduce: git range-diff cbb5404..d439466 cbb5404..5395d95

1:  5e02e9086c = 1:  5e02e9086c Concurrent PSBT spec
2:  d439466885 ! 2:  5395d955ce Rewrite concurrent PSBT BIP draft
2: d439466885 ! 2: 5395d955ce Rewrite concurrent PSBT BIP draft
@@ psbt-concurrent.md
 -| 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` | `<bytes input unique id>` | `PSBT_IN_UNIQUE_ID`  of an input removed from the logical input set. | None | No value data. |
 -| Removed Output | `PSBT_GLOBAL_REMOVED_OUTPUT = TBD` | `<bytes output unique id>` | `PSBT_OUT_UNIQUE_ID` removed from the logical output set. | None | No value data. |
-+| Deterministic Sort Flag | `PSBT_GLOBAL_SORT_DETERMINISTIC = TBD` | None | No key data | `<8-bit uint>` | A value of `0x01` indicates some sort keys MUST be deterministically derived. A value of `0x00` indicates explicit sort keys are required and `PSBT_GLOBAL_SORT_SEED` is disallowed. If absent, at the time of sorting either every input and output has an explicit sort key, or `PSBT_GLOBAL_SORT_SEED` is set and all sort keys are derived. |
++| Deterministic Sort Flag | `PSBT_GLOBAL_SORT_DETERMINISTIC = 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
  
@@ psbt-concurrent.md
 +| Output Sort Key | `PSBT_OUT_SORT_KEY = TBD` | None | No key data | `<bytes sort key>` | 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**, **Finalizer**, and **Extractor** fan in once all wallets have signed.
++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
@@ psbt-concurrent.md
 +        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 -->|cleared PSBT_GLOBAL_TX_UNORDERED field| Clear[Sorted 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
@@ psbt-concurrent.md
 +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.[^1]
++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.
@@ psbt-concurrent.md
 +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.[^7]
++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
 -
@@ psbt-concurrent.md
 -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.[^2] If all inputs and outputs have [sort keys](#ordering-inputs-and-outputs), the key-based ordering MAY be used instead of shuffling.
++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
  
@@ psbt-concurrent.md
 +// 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).
-+There are three ways of setting the sort keys. At the time of sorting, `PSBT_GLOBAL_SORT_DETERMINISTIC` and the presence of explicit sort keys determine whether `PSBT_GLOBAL_SORT_SEED` MUST be set and/or whether sort keys are derived.[^3][^5]
++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_DETERMINISTIC` 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_DETERMINISTIC` omitted or `=0x00` | `PSBT_GLOBAL_SORT_DETERMINISTIC=0x01` |
-+| --- | --- | --- |
-+| none | `PSBT_GLOBAL_SORT_SEED` MUST NOT be set. Use explicit sort keys. | `PSBT_GLOBAL_SORT_SEED` MUST be set. Derive every sort key. |
-+| some but not all | `PSBT_GLOBAL_SORT_SEED` MUST NOT be set. Use explicit sort keys. | `PSBT_GLOBAL_SORT_SEED` MUST be set. Derive the missing sort keys. |
-+| every input and output | `PSBT_GLOBAL_SORT_SEED` MUST NOT be set. Use the explicit keys. | No sort keys are derived. Use the explicit keys. |
++| Explicit sort keys | `PSBT_GLOBAL_SORT_DETERMINISTIC=0x00` | `PSBT_GLOBAL_SORT_DETERMINISTIC` omitted | `PSBT_GLOBAL_SORT_DETERMINISTIC=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
@@ psbt-concurrent.md
 +#### 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_DETERMINISTIC` is set to `0x01` and input and output sort keys are not set, then 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 the global field `PSBT_GLOBAL_SORT_DETERMINISTIC` 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_DETERMINISTIC` 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.
@@ psbt-concurrent.md
 +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.
-+#### Hybrid
++#### Mixed
  
 -### Divergence and SIGHASH flags
-+If `PSBT_GLOBAL_SORT_DETERMINISTIC` is set to `0x01` and some subset of inputs and outputs have explicit sort keys but not all, then the `PSBT_GLOBAL_SORT_SEED` MUST be set at the time of sorting and is used to derive the missing sort keys.[^8]
++If `PSBT_GLOBAL_SORT_DETERMINISTIC` is set to `0x01` and some subset of inputs and outputs have explicit sort keys but not all, 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
@@ psbt-concurrent.md
 +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`.[^9] 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.
++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.
@@ psbt-concurrent.md
 +### 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`.[^6]
++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.
@@ psbt-concurrent.md
 +// TODO: add link to test vectors
  
 -## Reference Implementation
-+[^1]: 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.
++[^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.
  
 ----
-+[^2]: 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.
++[^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
-+[^3]: Why is `PSBT_GLOBAL_SORT_DETERMINISTIC` 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_DETERMINISTIC`. If the seed is supplied later, the *Creator* SHOULD set `PSBT_GLOBAL_SORT_DETERMINISTIC` 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_DETERMINISTIC` to `0x00` to require explicit sort keys.
++[^sort-deterministic]: Why is `PSBT_GLOBAL_SORT_DETERMINISTIC` 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_DETERMINISTIC`. If the seed is supplied later, the *Creator* SHOULD set `PSBT_GLOBAL_SORT_DETERMINISTIC` 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_DETERMINISTIC` 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
-+[^5]: Derived sort keys need not be written into the PSBT. Derive them, sort, and discard them.
++[^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
-+[^6]: 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.
++[^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.
-+[^7]: `PSBT_GLOBAL_TX_MODIFIABLE` does not restrict reordering of input or output maps, and MAY stay set after `PSBT_GLOBAL_TX_UNORDERED` is cleared.
++[^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.
  
 ----
-+[^8]: Hybrid 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`.
++[^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.
-+[^9]: 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.
++[^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.

@arminsabouri
arminsabouri force-pushed the concurrent-psbt-rewrite branch from 5395d95 to 7e14aaa Compare November 14, 2026 03:42
@github-actions

Copy link
Copy Markdown
range-diff for force push 5395d955ce → 7e14aaa12d November 14, 2026 03:42 UTC: 1 modified, 1 unchanged

reproduce: git range-diff cbb5404..5395d95 cbb5404..7e14aaa

1:  5e02e9086c = 1:  5e02e9086c Concurrent PSBT spec
2:  5395d955ce ! 2:  7e14aaa12d Rewrite concurrent PSBT BIP draft
2: 5395d955ce ! 2: 7e14aaa12d Rewrite concurrent PSBT BIP draft
@@ psbt-concurrent.md
 +#### Mixed
  
 -### Divergence and SIGHASH flags
-+If `PSBT_GLOBAL_SORT_DETERMINISTIC` is set to `0x01` and some subset of inputs and outputs have explicit sort keys but not all, 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_DETERMINISTIC` 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

Comment thread psbt-concurrent.md Outdated

#### 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).

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this should probably be restricted to up to 32 bytes

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

and non empty, h/t @bc1cindy

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
@arminsabouri
arminsabouri force-pushed the concurrent-psbt-rewrite branch from 7e14aaa to 673171e Compare November 14, 2026 04:21
@github-actions

Copy link
Copy Markdown
range-diff for force push 7e14aaa12d → 673171e5a5 November 14, 2026 04:21 UTC: 1 modified, 1 unchanged

reproduce: git range-diff cbb5404..7e14aaa cbb5404..673171e

1:  5e02e9086c = 1:  5e02e9086c Concurrent PSBT spec
2:  7e14aaa12d ! 2:  673171e5a5 Rewrite concurrent PSBT BIP draft
2: 7e14aaa12d ! 2: 673171e5a5 Rewrite concurrent PSBT BIP draft
@@ psbt-concurrent.md
 -| 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` | `<bytes input unique id>` | `PSBT_IN_UNIQUE_ID`  of an input removed from the logical input set. | None | No value data. |
 -| Removed Output | `PSBT_GLOBAL_REMOVED_OUTPUT = TBD` | `<bytes output unique id>` | `PSBT_OUT_UNIQUE_ID` removed from the logical output set. | None | No value data. |
-+| Deterministic Sort Flag | `PSBT_GLOBAL_SORT_DETERMINISTIC = 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. |
++| 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
  
@@ psbt-concurrent.md
 +// 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_DETERMINISTIC` field. If any keys must be derived then `PSBT_GLOBAL_SORT_SEED` MUST be set. [^sort-deterministic][^derived-sort-keys]
++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_DETERMINISTIC=0x00` | `PSBT_GLOBAL_SORT_DETERMINISTIC` omitted | `PSBT_GLOBAL_SORT_DETERMINISTIC=0x01` |
++| 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 |
@@ psbt-concurrent.md
 +#### 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_DETERMINISTIC` 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.
++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_DETERMINISTIC` 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 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_DETERMINISTIC` 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.
++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
@@ psbt-concurrent.md
 +#### Mixed
  
 -### Divergence and SIGHASH flags
-+If `PSBT_GLOBAL_SORT_DETERMINISTIC` 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 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
@@ psbt-concurrent.md
 +[^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_DETERMINISTIC` 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_DETERMINISTIC`. If the seed is supplied later, the *Creator* SHOULD set `PSBT_GLOBAL_SORT_DETERMINISTIC` 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_DETERMINISTIC` to `0x00` to require explicit sort keys.
++[^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

Comment thread psbt-concurrent.md Resolved
Comment thread psbt-concurrent.md

### Canonical Identifier

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.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Canonical ID ignores sequence-only differences

The canonical ID is the BIP 370 unique ID of the sorted transaction with the double SHA256 replaced by a BIP 340-style tagged hash, and BIP 370 sets PSBT_IN_SEQUENCE to 0 when constructing that ID, so PSBTs differing only in sequence get the same canonical ID even though their final transactions differ.
A matching ID therefore does not show that replicas hold the same data.

oak · automated · 673171e

@nothingmuch nothingmuch Nov 14, 2026 •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this attempts to generalize BIP 370 unique IDs, which the more i think about the more i am unsure about.

this notion of "the same" is already reasonably defined and allows comparing whether the consensus level effects of the resulting transactions, if signed, valid etc, would be equivalent (up to outpoints of newly created UTXOs).

domain separation categorically rules out a BIP 370 and unordered PSBT being "the same" even if they are equivalent in their effects, since they are hashed differently. on the one hand this seems safer, because mixing these types of PSBTs without being clear about their correspondence and doing explicit conversion seems like a footgun, they are obviously not interchangeable as states, even if they can be mapped (even losslessly, e.g. assign sequential explicit sort keys to parsed inputs, so that the unordered psbt is truly equivalent to the ordered one, and it still doesn't seem to make sense to treat the two states as comparable since they are manipulated differently).

the more useful tracking of whether an unordered PSBT is "the same" as in part of the same shared mutable monotone state, is probably best achieved by a UUID which the sort seed would be able to achieve, but no such field is defined if derived=0x00, and in fungi we want to set the sort seed late (but this is a bit of a weak argument because it doesn't actually matter because we won't be serializing and joining arbitrary PSBTs in a way that relies on idempotence in the setting where the sort seed is set late)

so despite the argument being weak, i think maybe we should allow and recommend use of an additional proprietary UUID field, that can unambiguously check whether two PSBTs are intended to be mergeable, with the prorpietary field doing domain separation, and the value distinguishing particular shared session IDs. this differs from when they are de-facto mergeable, i.e. anywhere try_join succeeds.

then instead of being about unique IDs we can just give a table for the notions of equivalence, i.e. equivalent consensus effects, equivalent states, and related shared mutable state snapshots, all of which are useful. equivalent consensus effects is how i had it specified before the output uid comment, i.e. sort and bip 370 unique id, equivalent states is how i suggested to patch that up by additionally binding to the ordered sequence of output uids, equivalent session ID is just comparing a single field (which signals protocol and instance ID separately, so a single shared state instance can be shared between multiple protocols)

then to bikeshed it a bit, we can specify that deterministic sort seeding can be done as H(uuid | sort_seed) and rename "sort seed" to "additional entropy", and we can require this uuid field instead of the sort seed when derived key order is used, and the additional entropy can be always optional so punted to a spinoff that describes the security implications of the lehmer code thereby eliminating the footnotes here

this uuid field should be 16-32 bytes, recommended at least 128 bits of entropy for covert tranactions.

for strong covert privacy either this identifier or the additional entropy should contribute randomness to reach the desired security level wrt guessing the seed, assuming covert transactions are intended (so semi-honest, net-settlement). this is to resist fingerprinting as a wallet which sorts this way.

uuid7 has 74 bits of randomness, but since 2^6 = 64ms is on the scale that human caused variance could contribute sufficient entropy, this arguably reaches 80 bit security level? for an observer watching the mempool, the uncertainty about the time of initiation should be on the order of seconds, not ms. so 80 bit security as a requirement seems fair to set good defaults, and arguably uuid7 meets that requirement, and allowed, but 16 random bytes is reccomended?

overt coinjoin doesn't need to resist the fingerprinting of having been deterministically shuffled so the commitment property of the additional entropy is more useful. the seed should be unguessable, but the adversary can likely infer by the structure which protocol was used so this entropy can't protect from fingerprinting regardless.

Comment thread psbt-concurrent.md Resolved
Comment thread psbt-concurrent.md Resolved
@yuval-block

yuval-block commented Nov 14, 2026 •

Copy link
Copy Markdown
Collaborator

requiring unique sort keys in addition to unique IDs is kind of annoying as an invariant, it requires maintaining an alternate lookup structure or linear scan for duplicates on every mutation or join

so here's a strange reframing of the sorting rules that cannot fail:

  • global sort seed always allowed
  • explicit keys always assumed
  • derived sort keys always assumed
  • the sorting procedure compares explicit then derived sort keys
  • setting derived = 0x00 means the explicit keys must be non-empty
  • setting derived = 0x01 means the explicit keys must not be set (so only derived keys matter)
  • mixed mode, where derived is unset, means no constraint on explicit keys, missing and empty explicit keys are treated as the same

this way derived keys are always produced for symmetry breaking, and are (up to hash collision) guaranteed unique by hashing the unique identifiers

i think that's substantially simpler, and works basically the same, except that it eliminates an invariant check and error condition

and in mixed or explicit mode subsets of coins can be safely assigned the same sort key, allowing only subgroups to be shuffled separately from each other, not providing enough entropy in the sort keys is neither a safety nor fingerprinting concern with the mandatory uuid suggestion posted previously [edit: previously had below, tbh as much as i talk a lot of shit about github, this PR overview change is working for me, i have to admit]

@oakagent oakagent left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Typos in what this pull request adds:

psbt-concurrent.md

  • l.15 - "roles to divergent copies" → "roles into divergent copies"

oakagent · automated

@oakagent oakagent left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed the 6 newest of 7 commits; the rest of the pull request will be reviewed in the next cycles.

Comment thread psbt-concurrent.md Resolved

@oakagent oakagent left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed 4b8375b again: nothing to add to the earlier comments.

oakagent · automated

@oakagent oakagent left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed the pull request in full: the 6 newest of 11 commits, then the rest of its changes.

Comment thread psbt-concurrent.md

// 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]

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Strict Combiner rejects permitted additions

The condition is inverted: BIP 370 sets PSBT_GLOBAL_TX_MODIFIABLE to permit adding inputs or outputs, so this rule fails legitimate additions, including the wallet-join example on line 53, while not rejecting additions when the flag is clear. It also contradicts the union rule on line 88.

oakagent · automated · 4b8375b

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Concurrent PSBT Rewrite

6 participants