Skip to content

First round edits of Overview - #84

Open
deutschbitte wants to merge 4 commits into
overviewfrom
natalye/overview-edits
Open

deutschbitte wants to merge 4 commits into
overviewfrom
natalye/overview-edits

Conversation

@deutschbitte

Copy link
Copy Markdown
Collaborator

Editing #51

nothingmuch and others added 3 commits October 22, 2026 00:15
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
Comment thread docs/overview.md Resolved
Comment thread docs/overview.md
Bitcoin transactions are public, and the published research on wallet clustering shows that privacy on-chain is harder to achieve than commonly claimed. Collaborative transactions, in which several parties build one transaction together, can break the links that clustering relies on, but only if the way the transaction is constructed and the way peers are chosen don't reveal those links again. The [problem definition](./collaborative_txn_privacy.md) sets out what an observer can infer and what a claim of privacy on-chain has to withstand.

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. These conditions are specified in terms of properties of the graph, both the transactions that form it and its overall structure. 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.
Fungi is a suite of protocols for building such transactions between peers who are mutually consenting but distrusting. Its goal is to support interactive payments and net settlement with counterparties, as well as decentralized, market-based CoinJoins with untrusted parties. The protocols aim for safety (no participant can take another's funds), liveness (misbehaving peers can be excluded so the others can try again), and unlinkability of protocol messages. This overview describes how they work. The rest of the repository specifies them in detail.

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Overview says repository specifies protocols in detail

The overview now says the rest of the repository specifies the protocols in detail, but the linked chapters are stubs and docs/index.md and the README say they are under review; is that sentence meant to describe the current repository or the intended one?

oak · automated · 3788d50

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 introduced wording is correct, it speaks in the present tense about the state that draft approximates more closely, and main does not currently have, but this is intentional, it will become accurate soon and technically is already true speaking of the repository as a whole

@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:

docs/overview.md

  • l.37 - "has to don't just with" → "has to do not just with"
  • l.47 - "merged according the" → "merged according to the"

oak · automated

@yuval-block
yuval-block added this pull request to stack #86 November 10, 2026 00:36
@yuval-block

Copy link
Copy Markdown
Collaborator

the first commit in this PR was split and rebased into #51 and my draft branch (for the moved paragraphs), so it is effectively merged. the 2nd commit can now be rebased retaining the new intro paragraphs, since that I think needs actual review

i omitted the one incorrect don't

yuval-block pushed a commit that referenced this pull request Nov 10, 2026
The edits from #84 to the paragraphs that moved
from the overview into docs/transport-interfaces.md.
yuval-block pushed a commit that referenced this pull request Nov 10, 2026
The edits from #84 to the paragraphs that moved
from the overview into docs/transaction-construction.md.
yuval-block pushed a commit that referenced this pull request Nov 10, 2026
The edits from #84 to the paragraphs that moved
from the overview into docs/block-dag.md.
yuval-block pushed a commit that referenced this pull request Nov 10, 2026
The edits from #84 to the paragraphs that moved
from the overview into docs/recovery-track.md.
yuval-block pushed a commit that referenced this pull request Nov 10, 2026
The edits from #84 to the paragraphs that moved
from the overview into docs/coalition_formation.md.
Comment thread docs/overview.md Resolved
Comment thread docs/overview.md

One of the motivating use cases for interactive transaction construction 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 both safety and liveness 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. This can add sequential dependencies between peers. Within each payment cycle, at least one party will receive as much as it sends or more, and can therefore safely initiate a cascade of confirmations. See the [concurrent PSBT specification](./psbt-concurrent.md#confirmation-of-successful-payment-prior-to-signing) for additional details.

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

PSBT section link has no matching anchor

docs/overview.md links to ./psbt-concurrent.md#confirmation-of-successful-payment-prior-to-signing, but that page's only heading slug is concurrent-psbt-construction, so the fragment does not resolve and the link does not reach the referenced section.

oak · automated · f3e622f

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 will need to be resolved after the split (see #83) since that will be covered by a different doc

yuval-block pushed a commit to fungi-protocol/docs-draft that referenced this pull request Nov 10, 2026
The edits from fungi-protocol/docs#84 to the paragraphs that moved
from the overview into docs/transport-interfaces.md.
yuval-block pushed a commit to fungi-protocol/docs-draft that referenced this pull request Nov 10, 2026
The edits from fungi-protocol/docs#84 to the paragraphs that moved
from the overview into docs/transaction-construction.md.
yuval-block pushed a commit to fungi-protocol/docs-draft that referenced this pull request Nov 10, 2026
The edits from fungi-protocol/docs#84 to the paragraphs that moved
from the overview into docs/block-dag.md.
yuval-block pushed a commit to fungi-protocol/docs-draft that referenced this pull request Nov 10, 2026
The edits from fungi-protocol/docs#84 to the paragraphs that moved
from the overview into docs/recovery-track.md.
yuval-block pushed a commit to fungi-protocol/docs-draft that referenced this pull request Nov 10, 2026
The edits from fungi-protocol/docs#84 to the paragraphs that moved
from the overview into docs/coalition_formation.md.
yuval-block pushed a commit that referenced this pull request Nov 10, 2026
The edits from #84 to the paragraphs that moved
from the overview into docs/transport-interfaces.md.
yuval-block pushed a commit that referenced this pull request Nov 10, 2026
The edits from #84 to the paragraphs that moved
from the overview into docs/transaction-construction.md.
yuval-block pushed a commit that referenced this pull request Nov 10, 2026
The edits from #84 to the paragraphs that moved
from the overview into docs/block-dag.md.
yuval-block pushed a commit that referenced this pull request Nov 10, 2026
The edits from #84 to the paragraphs that moved
from the overview into docs/recovery-track.md.
yuval-block pushed a commit that referenced this pull request Nov 10, 2026
The edits from #84 to the paragraphs that moved
from the overview into docs/coalition_formation.md.

@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:

docs/overview.md

  • l.47 - "according the" → "according to the"
  • l.119 - "into providing" → "to provide"
  • l.121 - "fees contributions" → "fee contributions"
  • l.195 - "confer any special privileges to" → "confer any special privileges on"

oakagent · automated

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.

4 participants