Repository navigation
sort by explicit key, then by a key derived from the tx UUID - #120
yuval-block wants to merge 5 commits into
Conversation
1b475f7 to
9f4dce9
Compare
range-diff for force push 1b475f7b35 → 9f4dce9c75
|
9f4dce9 to
921b57a
Compare
range-diff for force push 9f4dce9c75 → 921b57a46a
|
| /// - a derived sort key = [`SortKeyHash`] of the sort seed, then the input's | ||
| /// consensus-encoded outpoint or the output's unique ID. | ||
| /// | ||
| /// Derived keys of distinct inputs, or outputs, differ, so explicit keys may |
There was a problem hiding this comment.
Public sort-key docs still require distinct keys
The new rule orders entries with equal explicit keys by their derived keys and UnorderedPsbt::try_from_psbt accepts repeated keys, but the public PSBT_IN_SORT_KEY/PSBT_OUT_SORT_KEY docs still say the key must be distinct across all inputs/outputs.
sort key. Must be distinct across all inputs in a PSBT.
— fungi-protocol/concurrent-psbt@921b57a · crates/concurrent-psbt/src/psbt/input.rs#L119
sort key. Must be distinct across all outputs in a PSBT.
— fungi-protocol/concurrent-psbt@921b57a · crates/concurrent-psbt/src/psbt/output.rs#L258
oakagent · automated · 921b57a
| return Err(UuidError::Empty); | ||
| } | ||
| let uuid = match global.uuid.clone() { | ||
| Some(existing) => existing.try_join(uuid).map_err(UuidError::from_conflict)?, |
There was a problem hiding this comment.
Empty UUID cannot be set by try_set_uuid
The decoder admits an empty PSBT_GLOBAL_TX_UUID, and has_uuid/sort_seed treat it as absent, so the PSBT enters an unseeded mode; join_uuid treats the empty value as an existing UUID, so try_set_uuid returns UuidError::Conflict and the PSBT can neither be refined to a seeded mode nor sorted.
A parsed PSBT may lack one: it enters an unseeded
— fungi-protocol/concurrent-psbt@921b57a · crates/concurrent-psbt/src/roles/sorter/mod.rs#L95
mode and is refined by
try_set_uuid.— fungi-protocol/concurrent-psbt@921b57a · crates/concurrent-psbt/src/roles/sorter/mod.rs#L96
oakagent · automated · 921b57a
| /// together with the transaction's [`TxUuid`]. | ||
| /// | ||
| /// The UUID already makes derived keys unpredictable, so the seed may be | ||
| /// empty, or commit to extra information such as a protocol transcript. An |
There was a problem hiding this comment.
Spec requires 128-bit seed under 0x01 but commit accepts empty
The spec requires a PSBT_GLOBAL_SORT_SEED of at least 128 bits under derivation 0x01 (line 139), but this commit accepts an empty seed; is that intentional?
If the global field
PSBT_GLOBAL_SORT_DETERMINISTICis set (unsigned 8 bit integer) to0x01, then sort keys MUST NOT be set, andPSBT_GLOBAL_SORT_SEEDMUST be set and contain at least 128 bits of randomness.— fungi-protocol/docs@f2806d9 · docs/psbt-concurrent.md#L139
should only set
PSBT_GLOBAL_SORT_DETERMINISTICto0x01, and leavePSBT_GLOBAL_SORT_SEEDunset.— fungi-protocol/docs@f2806d9 · docs/psbt-concurrent.md#L153
oak · automated · 921b57a
There was a problem hiding this comment.
my suggestions upon which this commit is modeled say that the UUID is now mandatory, and the seed is now renamed "additional entropy", and always allowed, and always optional
921b57a to
2ecafcf
Compare
range-diff for force push 921b57a46a → 2ecafcff2c
|
| /// | ||
| /// # Ordering | ||
| /// | ||
| /// Every mode sorts by explicit sort key, a missing key counting as empty, |
There was a problem hiding this comment.
Explicit mode does not treat missing keys as empty
ExplicitKeysRequired sorts with explicit = true, so input_sort_key and output_sort_key return MissingInputSortKey or MissingOutputSortKey when a key is absent; the Sorter doc's "every mode sorts by explicit sort key, a missing key counting as empty" is false for this mode.
oakagent · automated · 2ecafcf
There was a problem hiding this comment.
these requirements are independent, sorting by empty sort keys makes sense in mixed mode
the restriction on the explicit keys themselves, required to be all empty or all non-empty changes the meaning of the sorting but can be checked independently as a precondition before using the same exact sorting procedure, ignoring explicit sort keys when those are specified to be forbidden is an optimization not a correctness issue
| pub struct UuidTag = hash_str("concurrent-psbt/uuid"); | ||
|
|
||
| /// A sort key derived via tagged hash: `H(seed || identifier)`. | ||
| /// The tagged hash of `PSBT_GLOBAL_TX_UUID`, empty if unset. |
There was a problem hiding this comment.
UuidHash doc says empty when unset, but sorting errors
sort_seed returns MissingUuid when PSBT_GLOBAL_TX_UUID is unset or empty, so the UuidHash doc's "empty if unset" is wrong: an unset UUID is an error, not an empty hash.
Returns [
SortError::MissingUuid] if the UUID is unset or empty.— fungi-protocol/concurrent-psbt@93007c2 · crates/concurrent-psbt/src/roles/sorter/key.rs#L51
The tagged hash of
PSBT_GLOBAL_SORT_SEED, empty if unset.— fungi-protocol/concurrent-psbt@93007c2 · crates/concurrent-psbt/src/roles/sorter/key.rs#L21
oakagent · automated · 2ecafcf
There was a problem hiding this comment.
my suggestion is to treat that is required for sorting
we could make sorting generate a random UUID if it's not already set which would not be consistent across replicas, this seems reasonable since deriving a consistent order at that point would require transmitting either the seed or the sort order to the other replicas prior to signing
| creator: v2::Creator::new(), | ||
| sort_key_derivation: None, | ||
| seed: None, | ||
| uuid: TxUuid::generate(), |
There was a problem hiding this comment.
Cloned Creator breaks fresh-UUID guarantee
Creator derives Clone, but TxUuid::generate() is called in new, so PSBTs built from clones carry the same UUID; the doc's "fresh one on every PSBT" is false.
oakagent · automated · 2ecafcf
There was a problem hiding this comment.
it doesn't really make sense to use Clone but regardless that is intentional, if a creator was generated, and multiple copies of "the same" PSBT are then allowed to diverge, they should always be mergeable and in that sense the UUID refers to the same shared mutable state
2ecafcf to
ae9b191
Compare
range-diff for force push 2ecafcff2c → ae9b191a62
|
ae9b191 to
62c63be
Compare
range-diff for force push ae9b191a62 → 62c63bea9a
|
range-diff for force push ae9b191a62 → 62c63bea9a
|
Code coverage overviewLanguages: Rust Rust / code-coverage/cargo-llvm-cov
View coverage of the 10 most impacted files.
ℹ️ Calculations represent line coverage. Results may change as calculations are updated. Updated |
62c63be to
23287ff
Compare
range-diff for force push 62c63bea9a → 23287ff1ed
|
23287ff to
918602e
Compare
range-diff for force push 23287ff1ed → 918602e8a1
|
range-diff for force push 23287ff1ed → 918602e8a1
|
918602e to
0c154de
Compare
range-diff for force push 918602e8a1 → 0c154de312
|
range-diff for force push 918602e8a1 → 0c154de312
|
0c154de to
bd4f1dc
Compare
range-diff for force push 0c154de312 → bd4f1dc8f3
|
bd4f1dc to
70a89f4
Compare
range-diff for force push bd4f1dc8f3 → 70a89f49f2
|
70a89f4 to
0934730
Compare
range-diff for force push 70a89f49f2 → 0934730995
|
DerivedOnly becomes ExplicitKeysForbidden and ExplicitOnly becomes ExplicitKeysRequired, with the Creator methods explicit_keys_forbidden and explicit_keys_required. SortKeyDerivation::Derived and Explicit become ExplicitKeysForbidden and ExplicitKeysRequired. The following commits derive a key for every input and output in every mode, to break ties between explicit keys, so "derived only" no longer tells the modes apart. What tells them apart is whether explicit keys are forbidden, required, or optional. A mechanical rename, with comments reflowed: no behaviour changes. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Add PSBT_GLOBAL_TX_UUID (subtype 0x13): opaque bytes identifying the transaction being constructed, with Global::uuid and Global::set_uuid. It joins as an idempotent value, so two PSBTs with different UUIDs describe different transactions and do not join. The Creator sets a fresh random 16-byte UUID on every PSBT. Sorting does not read it yet. The next commit derives sort keys from it. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
PSBT_GLOBAL_TX_UUID becomes the mandatory sort seed. Every sort mode orders inputs and outputs by explicit sort key, a missing key counting as empty, and then by derived key. With BIP-340 style tagged hashes under concurrent-psbt/: - h = UuidHash(uuid) and e = AuxSortSeedHash(PSBT_GLOBAL_SORT_SEED), the latter over the empty string if the seed is unset; - the sort seed is SortSeedHash(h || e); - the derived key is SortKeyHash(sort seed || outpoint or unique ID). Sorting fails with SortError::MissingUuid if the UUID is unset or empty. Full keys of distinct entries differ, so the sorter's DuplicateSortKey goes away, and so does MissingSortSeed. The UUID supplies the entropy, so the sort seed becomes auxiliary: any length, allowed in every mode. SortSeed::MIN_LEN, InvalidSortSeed, SortSeedTooShort, UnexpectedSortSeed and SortModeError::MissingSortSeed are removed. try_set_seed and set_seed keep the mode, since the auxiliary seed adds no guarantee. The Seeded typestate now tracks the UUID instead of the sort seed, and refines all three modes: - The Creator produces Seeded modes. A parsed PSBT enters an unseeded mode, and try_set_uuid on the Constructor or Sorter joins a non-empty UUID and refines it; an empty or different UUID is a UuidError. - try_from_psbt and try_from_unordered_psbt into a Seeded mode reject a missing or empty UUID with SortModeError::MissingUuid. - Seeded Mixed and ExplicitKeysForbidden sort infallibly (into_ordered_psbt), and Seeded ExplicitKeysRequired fails only on a missing explicit key. Only the unseeded modes can fail with SortError::MissingUuid. Explicit keys must still be distinct; the next commit lifts that. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Derived keys break ties between equal explicit keys, so a repeated explicit key no longer leaves the order undetermined. Remove the duplicate-key check: UnorderedPsbtError::DuplicateSortKey, and the linear scan it ran on every join. A key is now marked only under a derivation, so mark is never handed an unset field. It becomes a single Option::map, leaving no unreachable arm for coverage to miss. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Derivation 0x00 now requires every explicit key to be non-empty. An empty key is marked as a conflict, as a key under 0x01 already is, and reported as UnorderedPsbtError::EmptyInputSortKey or EmptyOutputSortKey. Without a derivation, an empty key is still allowed, and sorts with the missing ones. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
0934730 to
ed2bcaa
Compare
range-diff for force push 0934730995 → ed2bcaa7d8
|
ed2bcaa to
000109c
Compare
range-diff for force push ed2bcaa7d8 → 000109cd49
|
Implements the sort-rule reframe from fungi-protocol/docs#78: a required transaction UUID seeds the derived sort keys, so explicit keys no longer need to be unique.
Split into five commits for review. Each one passes the checks on its own:
DerivedOnly→ExplicitKeysForbidden,ExplicitOnly→ExplicitKeysRequired,SortKeyDerivation::Derived→ExplicitKeysForbidden,SortKeyDerivation::Explicit→ExplicitKeysRequired, and the Creator methodsexplicit_keys_forbidden/explicit_keys_required.concurrent-psbt/:h = UuidHash(uuid), ande = AuxSortSeedHash(PSBT_GLOBAL_SORT_SEED), over the empty string if the seed is unset;SortSeedHash(h || e);SortKeyHash(sort seed || outpoint or unique ID).SortError::MissingUuidif the UUID is unset or empty.try_set_seedandset_seedkeep the mode.Seedednow tracks the UUID for all three modes:Seededmodes;try_set_uuidon the Constructor or Sorter refines it (UuidErroron an empty or different UUID);Seededmode rejects a missing or empty UUID (SortModeError::MissingUuid);Seeded<Mixed>andSeeded<ExplicitKeysForbidden>sort infallibly.DuplicateSortKey, and the linear scan on every join.EmptyInputSortKey/EmptyOutputSortKey. Derivation 0x01 still forbids explicit keys.The spec table in docs#78 still describes the old rules.
🤖 Generated with Claude Code