[yuval-block]

This includes a high level description of the various components of the
protocol suite, focusing on the transaction construction.

Unlike the strawman ladder it replaced (previously described as an
overview, and now somewhat out of date at any rate) it is scoped to only
discuss actual things not strawman constructions which only benefit
exposition, to avoid confusion about what is actually being implemented.

Closes #21

[arminsabouri]

This walks a thin line between describing the solutions and the techincal "how" (as well as what the problems). My comments are mostly regarding continuitity / flow of ideas.

[arminsabouri]

nit: We either need a leading sentence that connects this section with the one before or just remove it or condense it into 2 sentences into the last section. e.g the interactive tx construction protocols may operate in these communication models blah blah it matters bc X.

[arminsabouri]

Edit: now that I see how the rest of the document builds these terms, I think its approriate to define them here. But a connector sentence would still cause less "whip lash" .

[arminsabouri]

Same comment about a connector sentence for this as well.

[arminsabouri]

just noticed this. Have not read the rest of this

[arminsabouri]

This reads well! I need to re-read the cordial miners / consitency section again. There is a lot of information packed in there that I am mainly not familiar with. But I think it gets the why across which is the important bit for this document.

[yuval-block]

about the links, we can:

• remove them, add later (risks forgetting)
• wait until the destinations are merged (leaves this PR open needlessly)
• merge with broken links, risks leaving them broken if there are typos etc

i'm leaning towards the latter, and after we're done with the backlog we can add a nix flake check that ensures there are no broken links... wdyt @bc1cindy ?

[github-actions]

range-diff for force push f9a0ded9d9 → 36dbec85c3 October 14, 2026 16:42 UTC: 1 modified, 1 added

^{reproduce: git range-diff 8ac4434..f9a0ded 8ac4434..36dbec8}

-:  ---------- > 1:  304120b2d0 Generate SUMMARY.md from an OKF index.md
1:  f9a0ded9d9 ! 2:  36dbec85c3 [WIP] Overview

1: f9a0ded9d9 ! 2: 36dbec85c3 [WIP] Overview

@@ Metadata
 Author: Yuval Kogman <nothingmuch@woobling.org>
 
  ## Commit message ##
-    [WIP] Overview
+    Add an overview
+
+    This includes a high level description of the various components of the
+    protocol suite, focusing on the transaction construction.
+
+    Unlike the strawman ladder it replaced (previously described as an
+    overview, and now somewhat out of date at any rate) it is scoped to only
+    discuss actual things not strawman constructions which only benefit
+    exposition, to avoid confusion about what is actually being implemented.
 
     Closes #21
 
- ## overview.md (new) ##
+ ## .typos.toml (new) ##
+@@
++[default.extend-identifiers]
++# Author of The Byzantine Generals Problem.
++Pease = "Pease"
+
+ ## docs/index.md ##
+@@
+ okf_version: "0.2"
+ ---
+ 
++# Protocol Suite
++
++* [Overview](overview.md) - Collaborative transaction construction, privacy, fault tolerance and coalition formation.
++
+ # BIP Drafts
+ 
+ * [PSBT Scrubber](bip-drafts/scrubber.md) - Which PSBT fields can be shared with trusted and untrusted parties such that privacy is preserved.
+
+ ## docs/overview.md (new) ##
 @@
 +# Fungi protocol overview
 +
@@ overview.md (new)
 +
 +## Consistency, safety and liveness
 +
-+Consistency has to do not just with peers synchronizing their states, but also detecting when they have been successfully synchronized. Two properties of distributed systems related to this are safety and liveness.[^safety-liveness]
++Consistency has to do not just with peers synchronizing their states, but also detecting when they have been successfully synchronized. Two properties of distributed systems related to this are safety and liveness: safety excludes unacceptable outcomes; liveness concerns whether the protocol eventually completes.[^safety-liveness]
 +
 +Because transactions are subject to the safety guarantees of the Bitcoin protocol, collaborative transaction construction can more or less take it for granted. In all transaction construction variants the consistency requirement is agreeing on the exact unsigned transaction. We assume `SIGHASH_ALL`, which means that a signature by an input only authorizes that exact transaction, with its full list of inputs and outputs. In order to combine the signatures and obtain a fully valid transaction, all of the signatures must be made against the same transaction data.
 +
@@ overview.md (new)
 +
 +What such a majority can provide, therefore, is a mechanism for agreeing on which inputs belong to peers that have failed to complete the protocol. Depending on the communication model, some kind of timeout or recovery condition will be reached, and any inputs for which signatures have not yet been provided can be defined as out of compliance with the protocol. A new transaction construction session can then be attempted, excluding those inputs.
 +
-+Under synchrony or partial synchrony (specifically the eventual synchrony variant), if a sufficient threshold of peers can all agree it has been too long, then they can initiate such a recovery session. A threshold of peers agreeing implies a majority of honest peers agreeing. Note that agreement by a majority of honest participants requires a supermajority threshold: given $n = 3f+1$ where at most $f$ are faulty, a quorum of $2f+1$ peers will have at least $f+1$ honest peers in it agreeing.
++Under synchrony or partial synchrony (specifically the eventual synchrony variant), if a sufficient threshold of peers can all agree it has been too long, then they can initiate such a recovery session. A threshold of peers agreeing implies a majority of honest peers agreeing. Note that agreement by a majority of honest participants requires a supermajority threshold. A quorum is a set of peers meeting the required agreement threshold. Given $n = 3f+1$ where at most $f$ are faulty, a quorum of $2f+1$ peers will have at least $f+1$ honest peers in it agreeing.
 +
-+So long as the notion of "too long" is well defined (consistent with the communication model) and agreed by a quorum, if there are $f$ inputs owned by misbehaving peers honest parties should be able to successfully complete a run of the protocol after $O(f)$ attempts by simply excluding those inputsn as it becomes apparent that they are unresponsive.
++So long as the notion of "too long" is well defined (consistent with the communication model) and agreed by a quorum, if there are $f$ inputs owned by misbehaving peers honest parties should be able to successfully complete a run of the protocol after $O(f)$ attemptsby simply excluding those inputs as it becomes apparent that they are unresponsive.
 +
 +## Synchronization protocol
 +
@@ overview.md (new)
 +
 +### Byzantine eventual consistency
 +
-+The simplest of these is Byzantine Eventual Consistency by Martin Kleppmann and Heidi Howard.[^bec] In this model, messages, or transaction fragments as in our case, are committed to a Merklized causal log. For example, if Alice is adding an output, the output itself would be the payload of her message, and the envelope would contain references to Alice's last message, as well as the messages of other peers, referenced by hash.
++The simplest of these is Byzantine Eventual Consistency by Martin Kleppmann and Heidi Howard.[^bec] In this model, messages, or transaction fragments as in our case, are committed to a [Merklized](https://en.wikipedia.org/wiki/Merkle_tree) causal log. For example, if Alice is adding an output, the output itself would be the payload of her message, and the envelope would contain references to Alice's last message, as well as the messages of other peers, referenced by hash.
 +
 +In the naive version of their protocol (they describe a more optimized version), whenever a message is received, if the receiving peer does not know what a hash in its references commits to, it will request the preimage from the peer which sent this message, and after a finite number of such recursive queries and round trips it will eventually reach a message it has already seen. Signatures on the messages authenticate their authorship, allowing messages to be relayed via intermediate peers, and for any equivocations to be detectable. If the payloads are subject to validity constraints and merging independently accepting updates preserves these constraints, as Kleppmann and Howard show, this is sufficient for *Byzantine* eventual consistency: loosely speaking, even in the presence of Byzantine nodes, honest peers will eventually converge on the same set of messages.
 +
-+For privacy-preserving transaction construction, the payload should be a list of transaction fragments delivered anonymously to the peer which constructs the message. In BEC, these messages form an unstructured DAG, with each honest peer's messages forming a linked list which also links into the linked lists of other peers. The depths of these lists are not synchronized or bounded.
++For privacy-preserving transaction construction, the payload should be a list of transaction fragments delivered anonymously to the peer which constructs the message. In BEC, these messages form an unstructured directed acyclic graph (DAG), with each honest peer's messages forming a linked list which also links into the linked lists of other peers. The depths of these lists are not synchronized or bounded.
 +
 +Because in our setting they collect several state-related messages submitted by other participants, we'll call these messages blocks, in line with conventions in similar protocols.
 +
@@ overview.md (new)
 +
 +By waiting to reconcile the set of fragments with neighboring peers before building a block, peers can adhere to the cordiality while minimizing the number of blocks sent overall, which is more appropriate for the goal of coming to consensus over a finite sequence of sets with minimal end-to-end latency, as opposed to maximizing throughput and minimizing confirmation latency, which is the more typical design goal for DAG consensus algorithms.
 +
-+Note that these restrictions on the structure still consist of a special case of Kleppmann and Howard's hash-consed DAG; every block DAG structure is also a valid Byzantine eventual consistency causal log structure. Because of the validity proofs on transaction fragments, and the concurrent PSBT semantics we do not need an ordering but only a set union.
++Note that these restrictions on the structure still consist of a special case of Kleppmann and Howard's [hash-consed](https://en.wikipedia.org/wiki/Hash_consing) DAG; every block DAG structure is also a valid Byzantine eventual consistency causal log structure. Because of the validity proofs on transaction fragments, and the concurrent PSBT semantics we do not need an ordering but only a set union.
 +
 +Whether or not eventual consistency will suffice for synchronizing a set union depends on the communication model. When it is not sufficient, the blocks which do arrive and their parent blocks can be used to coordinate failure recovery, identifying responsive peers. In any case we do not need to ensure the stronger notion of safety that cordial miners and other such protocols provide, because of the unanimity requirement, and the consensus machinery is only needed for coordinating failure recovery.
 +
@@ overview.md (new)
 +
 +All participants can submit their transactions to a designated validator, with all other validators' blocks simply acknowledging the designated validator's blocks. 
 +
-+In principle, it is possible to decouple the validator role from the participant role and setting $n = 1$, where blocks form a linked list. This instantiates a version of the protocol based on a trusted coordinator. Note that "trust" here is meant only with regard to liveness, not to privacy. If a coordinator is trusted with privacy, which is the norm  for such services, validity proofs and anonymous broadcast are little more than privacy theater. A centralized protocol where the server simply does not keep a permanent record would be strictly better because users would be informed and computational and bandwidth resources would not be pointlessly wasted, degrading reliabiliy (which itself a privacy concern).
++In principle, it is possible to decouple the validator role from the participant role and setting $n = 1$, where blocks form a linked list. This instantiates a version of the protocol based on a trusted coordinator. Note that "trust" here is meant only with regard to liveness, not to privacy. If a coordinator is trusted with privacy, which is the norm for such services,[^trusted-coordinators] validity proofs and anonymous broadcast are little more than privacy theater. A centralized protocol where the server simply does not keep a permanent record would be strictly better because users would be informed and computational and bandwidth resources would not be pointlessly wasted, degrading reliabiliy (which itself a privacy concern).
 +
-+Note that this does not actually require $n = 1$ to shift the communication and coordination complexity onto a more powerful node; clients who choose to follow a particular attested state can still submit ACKs to it, and simply echo the parent block set commitments of the attested blocks when ACKing the same height with minimal communication complexity. Therefore there is no need to actually decouple those roles, it is sufficient to just shift the workload to one validator, unless such a validator is not itself a participant in the transaction.
++Note that this does not actually require $n = 1$ to shift the communication and coordination complexity onto a more powerful node; clients who choose to follow a particular attested state can still submit acknowledgements to it, and simply echo the parent block set commitments of the attested blocks when acknowledging the same height with minimal communication complexity. Therefore there is no need to actually decouple those roles, it is sufficient to just shift the workload to one validator, unless such a validator is not itself a participant in the transaction.
 +
-+A trusted execution environment can realize this trust model concretely, and would then be able to provide an attested view of the protocol state to clients.
++A trusted execution environment (TEE) can shift this trust assumption from the service operator to the hardware vendor and its attestation infrastructure. Attestation provides verifiable evidence that designated validation code executed in the claimed protected environment. Clients can therefore accept its validation of the protocol state without trusting the operator to execute that code faithfully, instead trusting the vendor’s hardware isolation and attestation guarantees. This additional trust assumption can improve liveness and consistency under weaker quorum assumptions, while reducing clients’ validation work. It does not relax the requirement for unanimous transaction signing; private allocations and spending authority remain with the participants.
 +
 +This has two primary advantages. The first is that bandwidth or compute restricted devices can participate asymmetrically in dissemination, validation, etc. If the trust assumption fails, that is still only a liveness violation, and doesn't compromise on safety or privacy. Presumably such clients are too constrained for scalable Byzantine fault tolerance. On the other hand, if the TEE assumption holds, liveness can tolerate a dishonest majority allowing successful termination after $O(f)$ attempts even if $f = n - 2$ (note that $f = n - 1$ holds trivially, that's just falling back to a unilateral transaction).
 +
@@ overview.md (new)
 +
 +When preferences over the coalition structure are in play (the cost function), in so-called hedonic games, it is often very hard (also in an algorithmic sense) to find stable coalition structures, as the preferences of the participants may conflict. In their most general form, such game descriptions are enormous as the preferences are defined over a large combinatorial object but even when many assumptions are made, like constraining the kinds of preferences the participants may have, it is still generally hard to find stable equilibria.[^hedonic] Complicating matters further, sharing the preferences would itself be a privacy leak, so we would prefer to limit that as much as possible, and certainly we cannot assume a mechanism that optimizes outcomes by just being able to read these preferneces.
 +
-+Fortunately, some of these difficulties of hedonic games can be bypassed with the introduction of a transferrable utility, and assigning the coalition itself a payoff, which can be redistributed. In our use case this payoff originates from any blockspace savings from net settlement, and the privacy benefits from collaboration. This surplus is not observable, it is the sum of subjective payoffs depending on individual participants' preferences (which in turn depend on their circumstances, privacy threat model, etc). While this does not guarantee stability, if a stable coalition structure exists, a transferrable utility can make the process of finding one much easier by iterated bilateral negotiation. However much these benefits are worth it to participants, if this surplus exists, then it can be voluntarily redistributed as sats among the participants (i.e. via a fee mechanism) aligning incentives for collaborative transaction construction, so that all coalition members stand to gain from participating.
++Fortunately, some of these difficulties of hedonic games can be bypassed with the introduction of a transferable utility, and assigning the coalition itself a payoff, which can be redistributed. In our use case this payoff originates from any blockspace savings from net settlement, and the privacy benefits from collaboration. This surplus is not observable, it is the sum of subjective payoffs depending on individual participants' preferences (which in turn depend on their circumstances, privacy threat model, etc). While this does not guarantee stability, if a stable coalition structure exists, a transferable utility can make the process of finding one much easier by iterated bilateral negotiation. However much these benefits are worth it to participants, if this surplus exists, then it can be voluntarily redistributed as sats among the participants (i.e. via a fee mechanism) aligning incentives for collaborative transaction construction, so that all coalition members stand to gain from participating.
 +
 +This is exactly the mechanism that the coalition formation protocol attempts to build: co-spend proposals are anonymous and confidential proposals, each of which is a bundle of bilateral agreements between the proposer and the owner of the other UTXOs listed in the proposal. The distinguishing feature of co-spend proposals is that they can be aggregated together, which generalizes a JoinMarket-like fee mechanism: it allows multiple "takers" to pay a single "maker" as a kind of group buy, as well as multiple independent "makers", all in the same transaction. This generality means that the distinction between taker and maker is removed; any participant can play both roles in a single transaction, depending on the co-spend proposals it makes or accepts.
 +
@@ overview.md (new)
 +
 +[^dag-rider]: I. Keidar, E. Kokoris-Kogias, O. Naor and A. Spiegelman, [*All You Need is DAG*](https://arxiv.org/abs/2102.08325) (2021). DAG-Rider separates construction of a communication DAG from local ordering of its proposals.
 +
++[^trusted-coordinators]: Y. Kogman, [*Reiterating centralized coinjoin (Wasabi & Samourai) deanonymization attacks*](https://groups.google.com/g/bitcoindev/c/CbfbEGozG7c/m/w2B-RRdUCQAJ)
++
 +[^coinswap]: For example [CoinSwap](https://openswap.live/) is such a protocol which relies on atomic swap contracts, designed with privacy in mind.
 +
 +[^hedonic]: D. Peters and E. Elkind, [*Simple Causes of Complexity in Hedonic Games*](https://arxiv.org/abs/1507.03474) (2015). Shows how modest expressiveness in preferences can make deciding the existence of stable outcomes computationally hard.

[github-actions]

range-diff for force push 36dbec85c3 → c3a0f8d3da October 14, 2026 16:48 UTC: 1 modified, 1 unchanged

^{reproduce: git range-diff 8ac4434..36dbec8 8ac4434..c3a0f8d}

1:  304120b2d0 = 1:  304120b2d0 Generate SUMMARY.md from an OKF index.md
2:  36dbec85c3 ! 2:  c3a0f8d3da Add an overview

2: 36dbec85c3 ! 2: c3a0f8d3da Add an overview

@@ docs/overview.md (new)
 +
 +Fungi is a suite of protocols for collaborative Bitcoin transactions. Its goal is to support interactive payments and net settlement with counterparties, as well as decentralized, market-based CoinJoins with untrusted parties.
 +
-+While the protocols themselves support arbitrary transaction structures, obtaining privacy outcomes is a matter of participants acting in their own self-interest and cooperating with others to achieve the desired results. The [problem definition](https://github.com/fungi-protocol/docs/blob/problem-definition/collaborative_txn_privacy.md) <!-- FIXME relative link to file not http --> describes conditions for a transaction graph to preserve privacy on chain. The repository also discusses the definition of a [cost function](./cost_function_abstract.md) for optimizing for this outcome. That said, the protocols for collaborative transactions summarized in this document are agnostic to the details of such a cost function.
++While the protocols themselves support arbitrary transaction structures, obtaining privacy outcomes is a matter of participants acting in their own self-interest and cooperating with others to achieve the desired results. The [problem definition](../collaborative_txn_privacy.md) describes conditions for a transaction graph to preserve privacy on chain. The repository also discusses the definition of a [cost function](./cost_function_abstract.md) for optimizing for this outcome. That said, the protocols for collaborative transactions summarized in this document are agnostic to the details of such a cost function.
 +
 +Depending on whether peers must be considered adversarial, and the underlying transport mechanisms, different variations of transaction construction are defined. These are the honest, semi-honest (also known as honest-but-curious) and Byzantine settings.
 +
 +In the honest setting, we assume peers can be trusted to follow the protocol and never leak any information apart from the final transaction (deliberately or otherwise). In the semi-honest setting we no longer trust peers with privacy; privacy-preserving transports are used to hide the attribution of different transaction fragments. Finally, in the Byzantine setting we must tolerate arbitrarily malicious behavior from peers.
 +
-+Finally, the [coalition formation](https://github.com/fungi-protocol/docs/blob/coalition-formation/coalition_formation.md) <!-- FIXME relative link to file not http --> protocol provides a market-based mechanism to allow mutually distrusting strangers to anonymously start transaction construction together. Randomizing peer selection is a requirement for CoinJoin graphs with the desired privacy properties. Net settlement, while beneficial for privacy, does not obscure the community structure that is inherent in real-world economic networks.
++Finally, the [coalition formation](../coalition_formation.md) protocol provides a market-based mechanism to allow mutually distrusting strangers to anonymously start transaction construction together. Randomizing peer selection is a requirement for CoinJoin graphs with the desired privacy properties. Net settlement, while beneficial for privacy, does not obscure the community structure that is inherent in real-world economic networks.
 +
 +## Concurrent PSBTs
 +
@@ docs/overview.md (new)
 +
 +While BIP 174 has been used in several collaborative transaction protocols, as specified it can only represent a fully formed unsigned transaction. [BIP 370](https://bips.dev/370/) extends the format to explicitly allow the input and output lists to be modifiable. The fact that these lists are ordered presents a challenge for concurrent transaction construction.
 +
-+The first component of the Fungi protocol suite is the proposed [Concurrent PSBT specification](https://github.com/fungi-protocol/docs/blob/concurrent-psbt/psbt-concurrent.md) <!-- FIXME relative link to file not http -->. It treats these collections as unordered sets rather than lists, allowing fragments to be combined regardless of arrival order, not just when collecting signatures but also when authoring the transaction. A consistent ordering is established before signing.
++The first component of the Fungi protocol suite is the proposed [Concurrent PSBT specification](../psbt-concurrent.md). It treats these collections as unordered sets rather than lists, allowing fragments to be combined regardless of arrival order, not just when collecting signatures but also when authoring the transaction. A consistent ordering is established before signing.
 +
 +In the "sneakernet" setting participants can pass around a single PSBT file, editing it in turn before handing it to the next party, but with concurrent PSBTs they can also concurrently modify different copies and merge them as well. And anything in between. Because divergent copies can be merged into one coherent transaction, the details of communication don't need to be specified; it could be a shared directory on a server, or one or more USB sticks, perhaps files shared over email, or some combination of the above.
 +
@@ docs/overview.md (new)
 +
 +A motivating use case for interactive transaction construction, one of several, is more efficient and private on-chain payments. Several parties can batch arbitrarily many payments into one transaction. Each participant's inputs and outputs express only the net difference. Individual payment amounts need not appear on chain.
 +
-+Net settlement adds safety considerations. Before signing, a participant must know that its funds reach the intended destinations. It can check outputs returning funds to itself directly; for a payment, it needs the payee to confirm that the transaction satisfies their agreement. Within each payment cycle at least one party will receive as much as it sends or more, and can therefore safely initiate confirmation. See the [concurrent PSBT specification](https://github.com/fungi-protocol/docs/blob/concurrent-psbt/psbt-concurrent.md#confirmation-of-successful-payment-prior-to-signing) <!-- FIXME relative link to file not http --> for additional details. <!-- TODO will be split off into a separate BIP see #16 -->
++Net settlement adds safety considerations. Before signing, a participant must know that its funds reach the intended destinations. It can check outputs returning funds to itself directly; for a payment, it needs the payee to confirm that the transaction satisfies their agreement. Within each payment cycle at least one party will receive as much as it sends or more, and can therefore safely initiate confirmation. See the [concurrent PSBT specification](../psbt-concurrent.md#confirmation-of-successful-payment-prior-to-signing) for additional details.
 +
 +## The semi-honest setting: adding privacy-preserving communication
 +
@@ docs/overview.md (new)
 +
 +Payment communication has different requirements, which also must be provided by the underlying transport. A sender must authenticate its receiver and obtain confirmation that the proposed transaction satisfies their agreement. However, this authentication can rely on a one-time code or pseudonym. The receiver doesn't need to authenticate the sender in order to be paid securely. Both counterparties know their payment amount, but need not disclose that relationship to the group or identify their transaction inputs and outputs to one another.
 +
-+The privacy objective is to avoid revealing anything more than what is inherent in the transaction data to the world, and the minimal payment details to counterparties. Anonymous communication is a necessary but insufficient requirement for this; it does not prevent inference from amounts or transaction structure, nor from the wider transaction graph. The on-chain limitations described in the [problem definition](https://github.com/fungi-protocol/docs/blob/problem-definition/collaborative_txn_privacy.md) <!-- FIXME rel link --> still apply.
++The privacy objective is to avoid revealing anything more than what is inherent in the transaction data to the world, and the minimal payment details to counterparties. Anonymous communication is a necessary but insufficient requirement for this; it does not prevent inference from amounts or transaction structure, nor from the wider transaction graph. The on-chain limitations described in the [problem definition](../collaborative_txn_privacy.md) still apply.
 +
 +This setting is inherently more brittle, because when disruptive messages are shared anonymously not only is it unclear how to recover, in general it isn't possible to tell apart the disruptive messages from the honest ones.
 +

[bc1cindy]

about the links, we can:

• remove them, add later (risks forgetting)
• wait until the destinations are merged (leaves this PR open needlessly)
• merge with broken links, risks leaving them broken if there are typos etc

i'm leaning towards the latter, and after we're done with the backlog we can add a nix flake check that ensures there are no broken links... wdyt @bc1cindy ?

agreed, merge with broken links and #54 tracks adding the check once the backlog lands

non-blocking, but since the chapters move into docs/ per #50, the ../ links should be ./, otherwise they stay broken even after the destinations land:

- L5: ../collaborative_txn_privacy.md → ./collaborative_txn_privacy.md
- L11: ../coalition_formation.md → ./coalition_formation.md
- L19: ../psbt-concurrent.md → ./psbt-concurrent.md
- L71: ../psbt-concurrent.md#confirmation-... → ./psbt-concurrent.md#confirmation-...
- L83: ../collaborative_txn_privacy.md → ./collaborative_txn_privacy.md

[bc1cindy]

• L59: were not delivered.. → were not delivered.
• L129: attemptsby → attempts by
• L139: merging independently accepting updates → merging independently accepted updates
• L171: reliabiliy → reliability
• L171: (which itself a privacy concern) → (which is itself a privacy concern)
• L189: preferneces → preferences
• L193: the owner of the other UTXOs → the owners of the other UTXOs
• L195: peers which proposing → peers proposing

[oakagent]

This PR builds on work that is not on main yet (304120b ('Generate SUMMARY.md from an OKF index.md') from #50 (okf-index)). Setting its base to okf-index, or waiting for that work to land, keeps the diff to this PR's own commits.

[github-actions]

range-diff for force push c278fa2252 → e341018a9c October 19, 2026 19:51 UTC: 1 unchanged, 1 dropped

^{reproduce: git range-diff 32edbfe..c278fa2 344b072..e341018}

1:  d20289ee35 < -:  ---------- Generate SUMMARY.md from an OKF index.md
2:  c278fa2252 = 1:  e341018a9c Add an overview

[github-actions]

range-diff for force push e341018a9c → fd3cc4b9ad October 19, 2026 19:57 UTC: 1 modified

^{reproduce: git range-diff 344b072..e341018 344b072..fd3cc4b}

1:  e341018a9c ! 1:  fd3cc4b9ad Add an overview

1: e341018a9c ! 1: fd3cc4b9ad Add an overview

@@ docs/overview.md (new)
 +
 +## Interactive transaction construction in the honest setting
 +
-+All of the protocols described here, starting with this one, assume interactivity. The PSBT concurrency spec describes how to merge states without specifying how peers communicate, whereas the protocols perscribe specific messages to be exchanged between peers. Some of these messages correspond to unordered PSBT fragments, and can merged according the concurrent PSBT specification.
++All of the protocols described here, starting with this one, assume interactivity. The PSBT concurrency spec describes how to merge states without specifying how peers communicate, whereas the protocols prescribe specific messages to be exchanged between peers. Some of these messages correspond to unordered PSBT fragments, and can merged according the concurrent PSBT specification.
 +
 +An *honest* participant is one that complies with the protocol. Faulty peers may deviate from the protocol, by being unresponsive or potentially with arbitrary, possibly malicious behavior. In the honest setting we assume that the only kind of fault is being unresponsive. Not only that, peers are additionally expected to keep confidential all of the information pertaining to the protocol's execution.
 +
@@ docs/overview.md (new)
 +
 +On the optimistic path, no proofs are needed if every participant can verify that all of its funds are are accounted for in its outputs and fees contributions, and no overspending has occurred, and everyone acknowledges that exact state. Overspending triggers proving so that contentious outputs and fee contributions can be validated. An anonymous, oversized fee contribution permits any participant to abort the optimistic path and force validity proofs to be required.
 +
-+Only valid transactions have consequences for the owners of the inputs, because invalid transaction cannot actually spend any coins, even if fully signed. The sense in which the fragments themselves must be valid according to the proofs is that when combined they would result in a valid transaction if it were fully signed. Taken together with the incentive compatibility assumption, the lack of obstruction removes any reason for honest participants to withhold their signatures: by following the protocol their funds will be sent to the destination they intended, and since this applies to all participants, this removes any valid reason for honest participants to withold their input signatures.
++Only valid transactions have consequences for the owners of the inputs, because invalid transaction cannot actually spend any coins, even if fully signed. The sense in which the fragments themselves must be valid according to the proofs is that when combined they would result in a valid transaction if it were fully signed. Taken together with the incentive compatibility assumption, the lack of obstruction removes any reason for honest participants to withhold their signatures: by following the protocol their funds will be sent to the destination they intended, and since this applies to all participants, this removes any valid reason for honest participants to withhold their input signatures.
 +
 +A widely circulated misconception is that validity proofs in such protocols, due to the use of zero knowledge somehow themselves are a source of privacy. This is false. All they can do is enforce validity, and if done correctly, they can enforce this without requiring privacy to be destroyed.
 +
@@ docs/overview.md (new)
 +
 +If a majority of the honest users can agree on a set of inputs and outputs, but one of the honest participants not in this majority still hasn't submitted all of their outputs, then it would rightfully withhold its signatures even if it does come back online. When assuming the asynchronous communication model, this can delay termination indefinitely, and achieving a majority is not sufficient for termination.
 +
-+Contributing signatures to a transaction that may become valid when fully signed is both an honest signal and a signal of honesty. In the signalling-theory sense, it is not costless, since the transaction may have consequences such as mining fees if the other parties also sign. Contributing signatures *also* signals honesty in the sense defined above: validity proofs make it safe for honest participants to sign regardless of the actions of other users, so they have no reason to withhold their signatures. A which deviates or defects from transaction construction can veto the transaction but at the cost of witholding a signature on at least one of their inputs.
++Contributing signatures to a transaction that may become valid when fully signed is both an honest signal and a signal of honesty. In the signalling-theory sense, it is not costless, since the transaction may have consequences such as mining fees if the other parties also sign. Contributing signatures *also* signals honesty in the sense defined above: validity proofs make it safe for honest participants to sign regardless of the actions of other users, so they have no reason to withhold their signatures. A which deviates or defects from transaction construction can veto the transaction but at the cost of withholding a signature on at least one of their inputs.
 +
 +In lieu of agreement about a transaction, agreement on the available evidence can still support liveness by allowing recovery from a fault. This boils down identifying inputs for which signatures have not yet been received. A missing signature may still eventually arrive, completing the transaction, but to avoid waiting indefinitely, participants can negotiate another transaction construction attempt while continuing to listen for progress in the original one.
 +
@@ docs/overview.md (new)
 +
 +So long as the notion of "too long" is well defined (consistent with the communication model) and agreed to by such a quorum, whenever there are up to $f$ inputs owned by faulty peers honest parties should be able to successfully complete a run of the protocol after $O(f)$ attempts by simply excluding those inputs as it becomes apparent that they are disruptive or unresponsive. Even in the worst case this process ensures at least one input can always be excluded.
 +
-+If there are more than $f$ faults recovery is still possible but coordinating recovery attempts by identifying the subset of inputs elligible to participate in recovery requires additional assumptions.
++If there are more than $f$ faults recovery is still possible but coordinating recovery attempts by identifying the subset of inputs eligible to participate in recovery requires additional assumptions.
 +
-+Note that synchronization has consequences for privacy as well, when operating outside of the design parameters. A majority of malicious validators, for example, could disrupt gossip and inclusion of certain messages in order to deanonymize them. In this scenario, the participant which unsuccessfully attempted to anonymously broadcast that message but failed can choose to include it, which would potentially implicate it as the author, or defect from validation in order to avoid acknowledging a state which does not include the message. However, in such a circumstance it would be better to allow outputs to be omitted and to withold signing with one of the inputs in order to reveal as little as possible.
++Note that synchronization has consequences for privacy as well, when operating outside of the design parameters. A majority of malicious validators, for example, could disrupt gossip and inclusion of certain messages in order to deanonymize them. In this scenario, the participant which unsuccessfully attempted to anonymously broadcast that message but failed can choose to include it, which would potentially implicate it as the author, or defect from validation in order to avoid acknowledging a state which does not include the message. However, in such a circumstance it would be better to allow outputs to be omitted and to withhold signing with one of the inputs in order to reveal as little as possible.
 +
 +## Synchronizing protocol state
 +
@@ docs/overview.md (new)
 +
 +In principle, it is possible to decouple the validator role from the participant role, with one validator serving many transaction participants. That validator's blocks form a linked list. This instantiates a version of the protocol based on a trusted coordinator. Note that "trust" here is meant only with regard to liveness, not to privacy. If a coordinator is trusted with privacy, which is the norm for such services,[^trusted-coordinators] validity proofs and anonymous broadcast are little more than privacy theater. A centralized protocol where the server simply does not keep a permanent record would be strictly better because users would be informed and computational and bandwidth resources would not be pointlessly wasted, degrading reliability (which is itself a privacy concern).
 +
-+Note that centralizing the bulk of this communication and coordination work on one node does not require decoupling the validator and participant roles, nor does it confer any special priviliges to this de-facto leader; on the DAG model participants which only acknowledge the blocks of a single peer, can make those acknwoledgement in the form of blocks that echo the content bearing blocks with minimal communication complexity. No protocol modifications so long as this validator is still a participant in the transaction, and only the introduction of a validator that is not a participant would require these roles to be decoupled.
++Note that centralizing the bulk of this communication and coordination work on one node does not require decoupling the validator and participant roles, nor does it confer any special privileges to this de-facto leader; on the DAG model participants which only acknowledge the blocks of a single peer, can make those acknwoledgement in the form of blocks that echo the content bearing blocks with minimal communication complexity. No protocol modifications so long as this validator is still a participant in the transaction, and only the introduction of a validator that is not a participant would require these roles to be decoupled.
 +
-+Going futher, a trusted execution environment (TEE) can shift trust assumptions from a participant to the the hardware vendor on which the participant is running the protocol. Such a participant can produce attestations about exactly what code is being exceuted in the TEE enclave, which the other participants can verify. Clients could therefore accept its validation of the protocol state without trusting the operator to execute that code faithfully, instead trusting the vendor’s hardware isolation and attestation guarantees.
++Going further, a trusted execution environment (TEE) can shift trust assumptions from a participant to the the hardware vendor on which the participant is running the protocol. Such a participant can produce attestations about exactly what code is being executed in the TEE enclave, which the other participants can verify. Clients could therefore accept its validation of the protocol state without trusting the operator to execute that code faithfully, instead trusting the vendor’s hardware isolation and attestation guarantees.
 +
 +The reason such an additional trust assumption may be desired in some circumstances is that it improve liveness and consistency under weaker quorum assumptions, while reducing clients’ validation work further. This does not relax the requirement for unanimous transaction signing, nor is the TEE trusted with protecting privacy; private allocations and spending authority remain with the participants and their messages must remain unlinkable. This provides an alternative path to linveness when clients are too constrained for scalable Byzantine fault tolerance, or when the conditions for Byzantine fault tolerance don't hold (for example a dishonest majority of validators).
 +

[github-actions]

range-diff for force push fd3cc4b9ad → dc99513d04 October 19, 2026 21:43 UTC: 1 unchanged

^{reproduce: git range-diff 344b072..fd3cc4b b3e699e..dc99513}

1:  fd3cc4b9ad = 1:  dc99513d04 Add an overview

[xstoicunicornx]

Overall its ACK from me.

Highlighted the remaining feedback that I think was missed.

The one thing I feel strongly about is that the 3 settings have the same heading pattern (leading with the setting name) and should be grouped together to make it intuitive to the reader that these are the 3 different settings in which fungi operates under.

[xstoicunicornx]

I think old title of "The semi-honest setting: adding privacy-preserving communication" was better. Transaction construction is kinda a given for entire fungi protocol, and "adding privacy-preserving communication" does a good job highlighting the the main difference between honest and semi-honest setting.

If you'd rather not use the old title it should at least match format of "Byzantine fault tolerant transaction construction" (ie Semi-honest setting transaction construction).

[xstoicunicornx]

I still think my version reads better:

Suggested change

	A widely circulated misconception is that validity proofs in such protocols, due to the use of zero knowledge somehow themselves are a source of privacy. This is false. All they can do is enforce validity, and if done correctly, they can enforce this without requiring privacy to be destroyed.
	While validity proofs restore the possibility of completion without sacrificing privacy, they do not contribute to privacy themselves. All they do is enforce validity, and if done correctly, they can enforce validity without destroying privacy.

[yuval-block]

i'll concede that it reads better but I do think this needs to address the fact that this is responding to a misconception

the rift is that anyone who understands how validity proofs actually work should know this already, and yet in bitcoin privacy discussions the incorrect statement is often repeated and seldom questioned

[xstoicunicornx]

"Honest setting transaction construction" is more consistent with BFT heading. I think putting the "transaction construction" in the front buries the lede (especially since thats the redundant-ish part that all settings relate too).

[yuval-block]

"byzantine setting transaction construction" would be but that sounds a bit weird to me

i think i'm kind of aesthetically averse to mechanical repetition of sentence structure, i can't make a strong argument other than so far the way i wrote it sounds the best to me when i say it out loud (same re other heading)

[xstoicunicornx]

No I would leave BFT heading as is... "setting" word is honestly unnecessary for for honest/semi-honest. I was saying change only honest/semi-honest headings. BFT heading is the one that I think reads well.

[yuval-block]

No I would leave BFT heading as is... "setting" word is honestly unnecessary for for honest/semi-honest.

Hmm, "(semi-)honest transaction construction" seems a bit vague to me, i think it "the honest setting" makes it clear that it's a specific setting described in that section, no?

[xstoicunicornx]

Yes, my main point is that I think that "transaction construction" should be in latter half of heading for all 3 settings.

[yuval-block]

hmm that sounds a bit forced to me. "semi-honest setting" is a noun phrase, "byzantine fault tolerant" is an adjective phrase... noun phrases can be forced into becoming adjectives phrases, but for my brain it's much easier to parse these as prepositions via in, kinda gives crash blossom vibes

[xstoicunicornx]

Where are these equations pulled from?

[yuval-block]

https://www.cs.huji.ac.il/~dolev/pubs/the-byz-generals-combined.pdf but with the more modern conventions of labeling the number of faulty nodes $f$

[xstoicunicornx]

The cordiality requirement is that for $n = 3f + 1$ validators, every block at height $h$ will have $t = n - f$ parent blocks with height $h - 1$.

I guess I don't understand how height and parent blocks tie together? They seem to not have a relationship in the given equations?

[yuval-block]

in cordial miners each of $n$ validators produces a sequence of blocks. each block of height which must have $t$ parent blocks at height $h-1$ (and can have more older parents but i'm ignoring that).

the two quantities aren't related by any equation but the constraint is related in that if a block with height $h$ has $t$ parents but some of them are not of height $h-1$ then it is not a valid block in that model

this condition ensures that every block witnesses an honest majority of blocks from the previous generation which is required for their tau function that defines what the consensus state is, and it also ensures that no honest validator can run ahead of the honest majority

[bc1cindy]

ACK dc99513

[xstoicunicornx]

For all the references/context you provided for my dumb questions I would just say that it would probably be good to have that context in the document itself imo.

[yuval-block]

For all the references/context you provided for my dumb questions I would just say that it would probably be good to have that context in the document itself imo.

The LSP paper that introduces byzantine generals problem is in the footnotes.

Based on other feedback, maybe it's best to move the communication models and fault tolerance to the DAG spec stuff (#67) but the unanimity requirement is so fundamental to coinjoins i wanted to address it in the overview... Still unsure about this

[oakagent]

Typos in what this pull request adds:

docs/overview.md

• l.107 - "even if if signatures" → "even if signatures"
• l.119 - "are are accounted" → "are accounted"
• l.121 - "invalid transaction cannot" → "an invalid transaction cannot"
• l.193 - "acknwoledgement" → "acknowledgement"
• l.195 - "to the the hardware" → "to the hardware"
• l.197 - "it improve liveness" → "it improves liveness"
• l.197 - "linveness" → "liveness"

_{oak · automated}

[github-actions]

range-diff for force push dc99513d04 → f22253b13c October 21, 2026 22:04 UTC: 1 modified

^{reproduce: git range-diff b3e699e..dc99513 5e034ba..f22253b}

1:  dc99513d04 ! 1:  f22253b13c Add an overview

1: dc99513d04 ! 1: f22253b13c Add an overview

@@ docs/overview.md (new)
 +
 +These protocols are designed to allow interactive payments with net settlement. While net settlement on its own is beneficial for privacy in some ways, it does not adequately obscure the community structure that is inherent in real-world economic networks. Randomizing peer selection is one of the requirements for building CoinJoin graphs with the desired privacy enhancing properties.
 +
-+The last component needed is therefore the [coalition formation](./coalition_formation.md) protocol. It provides a market-based mechanism to allow mutually distrusting strangers to anonymously start an instance of the Byzantine fault tolerant (BFT) transaction construction protocol.
++In order to randomize peer selection, the last component needed is the [coalition formation](./coalition_formation.md) protocol. It provides a market-based mechanism to allow mutually distrusting strangers to anonymously start an instance of the Byzantine fault tolerant (BFT) transaction construction protocol.
 +
 +## PSBT concurrency
 +
@@ docs/overview.md (new)
 +
 +Participation is voluntary, and no party can be compelled to sign. The protocol therefore operates in the non-cooperative game-theoretic setting: any agreement to transact or sign cannot be binding, and must be self-enforcing through incentives in order to have any bearing. We therefore additionally define an honest participant as one which intends to complete the protocol and sign, regardless of which permitted actions the other honest participants choose to take. The agreed conditions must preserve that incentive throughout construction; the coalition formation protocol, discussed at the end of this overview, provides a mechanism for negotiating those conditions and aligning incentives for cooperation. For now we will simply assume that the honest users' incentives are already aligned when transaction construction commences.
 +
-+Under the rules of the semi-honest setting a malicious participant might attempt to overspend, causing the combined transaction to be invalid even if if signatures are given for all inputs. A malicious peer might also equivocate: give conflicting accounts of its actions to different peers. Or it might simply withhold a signature, causing delays. In the Byzantine setting the honest peers must be resilient to such disruption. This means ensuring flood protection and fairness.
++Under the rules of the semi-honest setting a malicious participant might attempt to overspend, causing the combined transaction to be invalid even if signatures are given for all inputs. A malicious peer might also equivocate: give conflicting accounts of its actions to different peers. Or it might simply withhold a signature, causing delays. In the Byzantine setting the honest peers must be resilient to such disruption. This means ensuring flood protection and fairness.
 +
 +### Optimistic transaction construction
 +
@@ docs/overview.md (new)
 +
 +The purpose of validity proofs is to restore the possibility of completion by preventing the same funds from being claimed more than once.The proofs establish that outputs and fee contributions are covered by input funds, including any funds that originate from payments between participants. They must accomplish this *without* sacrificing privacy, which is why they must be zero-knowledge proofs. They do not replace each participant's final approval, nor can they compel any participant into providing the remaining proofs or signatures. They ensure that honest, responsive participants can successfully add all of their intended inputs and outputs to the shared state without obstruction.
 +
-+On the optimistic path, no proofs are needed if every participant can verify that all of its funds are are accounted for in its outputs and fees contributions, and no overspending has occurred, and everyone acknowledges that exact state. Overspending triggers proving so that contentious outputs and fee contributions can be validated. An anonymous, oversized fee contribution permits any participant to abort the optimistic path and force validity proofs to be required.
++On the optimistic path, no proofs are needed if every participant can verify that all of its funds are accounted for in its outputs and fees contributions, and no overspending has occurred, and everyone acknowledges that exact state. Overspending triggers proving so that contentious outputs and fee contributions can be validated. An anonymous, oversized fee contribution permits any participant to abort the optimistic path and force validity proofs to be required.
 +
-+Only valid transactions have consequences for the owners of the inputs, because invalid transaction cannot actually spend any coins, even if fully signed. The sense in which the fragments themselves must be valid according to the proofs is that when combined they would result in a valid transaction if it were fully signed. Taken together with the incentive compatibility assumption, the lack of obstruction removes any reason for honest participants to withhold their signatures: by following the protocol their funds will be sent to the destination they intended, and since this applies to all participants, this removes any valid reason for honest participants to withhold their input signatures.
++Only valid transactions have consequences for the owners of the inputs, because an invalid transaction cannot actually spend any coins, even if fully signed. The sense in which the fragments themselves must be valid according to the proofs is that when combined they would result in a valid transaction if it were fully signed. Taken together with the incentive compatibility assumption, the lack of obstruction removes any reason for honest participants to withhold their signatures: by following the protocol their funds will be sent to the destination they intended, and since this applies to all participants, this removes any valid reason for honest participants to withhold their input signatures.
 +
 +A widely circulated misconception is that validity proofs in such protocols, due to the use of zero knowledge somehow themselves are a source of privacy. This is false. All they can do is enforce validity, and if done correctly, they can enforce this without requiring privacy to be destroyed.
 +
@@ docs/overview.md (new)
 +
 +Since input exclusivity is neither desirable nor enforceable, we can embrace its absence and reframe liveness in a simpler way by treating all failure recovery as branching off another instance of the protocol with a subset of the participants precisely when that subset of the participants can agree among themselves that a failure condition has been detected. Such agreement inherently requires synchrony or partial synchrony, and so explains why this is needed for fault tolerance. In this case the blocks at some height $h$ with $t < n$ parent blocks will be produced as part of the recovery synchronization protocol on top of which a new transaction construction session will commence. If messages are delivered allowing a block at height $h$ to be produced with $t = n$ messages, the asynchronous base protocol can resume progress resulting in the diverging protocol states at height $h$. This special case has the same structure as all-to-all broadcast.
 +
-+Since recovery is just permissioned coalition formation, any participant may act as an aggregator and make a coalition formation proposal based on its local view; the proposed participants must all accept before it starts. Membership changes can alter anonymity or payment terms, so participants may renegotiate or decline.
++Since recovery is just permissioned coalition formation, any participant may act as an aggregator and make a coalition formation proposal based on its local view; the proposed participants must all accept before it starts. Membership changes can alter anonymity or payment terms, so participants may renegotiate or decline. Recovery also has a privacy cost: excluding an input links it to the outputs that drop out with it, even if its owner was merely unresponsive.
 +
 +The reason this framing is simpler is that recovery attempts do not need to terminate the run of the protocol that they are trying to recover. In the case that both branches eventually succeed, Bitcoin itself will adjudicate the conflicting transactions. We can treat failure recovery as a (more) synchronous layer building on a fundamentally asynchronous optimistic base protocol with BEC semantics.
 +
@@ docs/overview.md (new)
 +
 +In principle, it is possible to decouple the validator role from the participant role, with one validator serving many transaction participants. That validator's blocks form a linked list. This instantiates a version of the protocol based on a trusted coordinator. Note that "trust" here is meant only with regard to liveness, not to privacy. If a coordinator is trusted with privacy, which is the norm for such services,[^trusted-coordinators] validity proofs and anonymous broadcast are little more than privacy theater. A centralized protocol where the server simply does not keep a permanent record would be strictly better because users would be informed and computational and bandwidth resources would not be pointlessly wasted, degrading reliability (which is itself a privacy concern).
 +
-+Note that centralizing the bulk of this communication and coordination work on one node does not require decoupling the validator and participant roles, nor does it confer any special privileges to this de-facto leader; on the DAG model participants which only acknowledge the blocks of a single peer, can make those acknwoledgement in the form of blocks that echo the content bearing blocks with minimal communication complexity. No protocol modifications so long as this validator is still a participant in the transaction, and only the introduction of a validator that is not a participant would require these roles to be decoupled.
++Note that centralizing the bulk of this communication and coordination work on one node does not require decoupling the validator and participant roles, nor does it confer any special privileges to this de-facto leader; on the DAG model participants which only acknowledge the blocks of a single peer, can make those acknowledgement in the form of blocks that echo the content bearing blocks with minimal communication complexity. No protocol modifications so long as this validator is still a participant in the transaction, and only the introduction of a validator that is not a participant would require these roles to be decoupled.
 +
-+Going further, a trusted execution environment (TEE) can shift trust assumptions from a participant to the the hardware vendor on which the participant is running the protocol. Such a participant can produce attestations about exactly what code is being executed in the TEE enclave, which the other participants can verify. Clients could therefore accept its validation of the protocol state without trusting the operator to execute that code faithfully, instead trusting the vendor’s hardware isolation and attestation guarantees.
++Going further, a trusted execution environment (TEE) can shift trust assumptions from a participant to the hardware vendor on which the participant is running the protocol. Such a participant can produce attestations about exactly what code is being executed in the TEE enclave, which the other participants can verify. Clients could therefore accept its validation of the protocol state without trusting the operator to execute that code faithfully, instead trusting the vendor’s hardware isolation and attestation guarantees.
 +
-+The reason such an additional trust assumption may be desired in some circumstances is that it improve liveness and consistency under weaker quorum assumptions, while reducing clients’ validation work further. This does not relax the requirement for unanimous transaction signing, nor is the TEE trusted with protecting privacy; private allocations and spending authority remain with the participants and their messages must remain unlinkable. This provides an alternative path to linveness when clients are too constrained for scalable Byzantine fault tolerance, or when the conditions for Byzantine fault tolerance don't hold (for example a dishonest majority of validators).
++The reason such an additional trust assumption may be desired in some circumstances is that it improves liveness and consistency under weaker quorum assumptions, while reducing clients’ validation work further. This does not relax the requirement for unanimous transaction signing, nor is the TEE trusted with protecting privacy; private allocations and spending authority remain with the participants and their messages must remain unlinkable. This provides an alternative path to liveness when clients are too constrained for scalable Byzantine fault tolerance, or when the conditions for Byzantine fault tolerance don't hold (for example a dishonest majority of validators).
 +
 +In other words, using essentially the same unmodified block DAG structure we can accommodate multiple communication models and trust assumptions, to accommodate a variety of client capabilities and circumstances.
 +

[github-actions]

range-diff for force push f22253b13c → 6bc209f822 October 21, 2026 22:15 UTC: 1 modified

^{reproduce: git range-diff 5e034ba..f22253b 5e034ba..6bc209f}

1:  f22253b13c ! 1:  6bc209f822 Add an overview

1: f22253b13c ! 1: 6bc209f822 Add an overview

@@ .typos.toml (new)
 +# Author of The Byzantine Generals Problem.
 +Pease = "Pease"
 
+ ## cspell.json ##
+@@
+     "fonts",
+     "python",
+     "networking-terms",
++    "author-names",
+     "bitcoin-privacy",
+     "repo-tooling"
+   ],
+   "dictionaryDefinitions": [
++    {
++      "name": "author-names",
++      "path": "./cspell/author-names.txt"
++    },
+     {
+       "name": "bitcoin-privacy",
+       "path": "./cspell/bitcoin-privacy.txt"
+
+ ## cspell/author-names.txt (new) ##
+@@
++# Author names
++Alpern
++Dwork
++Elkind
++Keidar
++Kleppmann
++Kogias
++Kogman
++Kokoris
++Naor
++Paverd
++Poupko
++Stockmeyer
+
+ ## cspell/bitcoin-privacy.txt ##
+@@
+ # Bitcoin and privacy vocabulary
++Blocklace
+ blockspace
+ CoinJoin
++CoinSwap
+ deanonymization
+ deanonymize
+ CLTV
+@@ cspell/bitcoin-privacy.txt: HTLCs
+ keytype
+ locktime
+ Merkle
++Merklized
+ MuSig
+ Payjoin
++permissioned
+ permissionless
+ preimages
+ PSBT
+ PSBTs
+ pubkeys
+ RIPEMD
++Samourai
+ scriptSig
+ scriptWitness
+ sighash
++sneakernet
+ taptree
+ unlinkability
++unlinkable
+ UTXO
+ xpub
+
  ## docs/index.md ##
 @@
  okf_version: "0.2"

[github-actions]

range-diff for force push 6bc209f822 → e442a6cc15 October 21, 2026 22:15 UTC: 1 modified

^{reproduce: git range-diff 5e034ba..6bc209f 5e034ba..e442a6c}

1:  6bc209f822 ! 1:  e442a6cc15 Add an overview

1: 6bc209f822 ! 1: e442a6cc15 Add an overview

@@ docs/overview.md (new)
 +
 +### Validity proofs
 +
-+The purpose of validity proofs is to restore the possibility of completion by preventing the same funds from being claimed more than once.The proofs establish that outputs and fee contributions are covered by input funds, including any funds that originate from payments between participants. They must accomplish this *without* sacrificing privacy, which is why they must be zero-knowledge proofs. They do not replace each participant's final approval, nor can they compel any participant into providing the remaining proofs or signatures. They ensure that honest, responsive participants can successfully add all of their intended inputs and outputs to the shared state without obstruction.
++The purpose of validity proofs is to restore the possibility of completion by preventing the same funds from being claimed more than once. The proofs establish that outputs and fee contributions are covered by input funds, including any funds that originate from payments between participants. They must accomplish this *without* sacrificing privacy, which is why they must be zero-knowledge proofs. They do not replace each participant's final approval, nor can they compel any participant into providing the remaining proofs or signatures. They ensure that honest, responsive participants can successfully add all of their intended inputs and outputs to the shared state without obstruction.
 +
 +On the optimistic path, no proofs are needed if every participant can verify that all of its funds are accounted for in its outputs and fees contributions, and no overspending has occurred, and everyone acknowledges that exact state. Overspending triggers proving so that contentious outputs and fee contributions can be validated. An anonymous, oversized fee contribution permits any participant to abort the optimistic path and force validity proofs to be required.
 +

[oakagent]

@yuval-block e442a6c is clean; the ACK waits on two open points:

• docs/overview.md:156 afsheenb: "Might be worth adding a sentence or two about what Kleppman and Howard show (invariant confluence, iiuc?) so that the reader doesn't have to leave the doc to..." (not in the code yet)
• docs/overview.md:87 xstoicunicornx: "I think old title of "The semi-honest setting: adding privacy-preserving communication" was better. Transaction construction is kinda a given for entire fung..." (no reply yet)

_{oak · automated}

[bc1cindy]

ACK

[bc1cindy]

link check fails because this anchor only exists in #16, adding a ### Confirmation of successful payment prior to signing heading to the docs/psbt-concurrent.md stub should fix it until #16 lands