Skip to content

[WIP] draft of complete docs - #80

Draft
yuval-block wants to merge 112 commits into
mainfrom
draft
Draft

yuval-block wants to merge 112 commits into
mainfrom
draft

Conversation

@yuval-block

@yuval-block yuval-block commented Oct 26, 2026 •

Copy link
Copy Markdown
Collaborator

mainly for @oakagent to pick apart, individual PRs for the various pieces will come separately, but feedback welcome

this branch is also pushed to main on docs-draft repo and rendered here: https://fungi-protocol.github.io/docs-draft/

@github-actions

Copy link
Copy Markdown
range-diff for force push 1ee57d1562 → 8e41ba243d October 26, 2026 05:06 UTC: 1 modified, 99 unchanged

reproduce: git range-diff 116e871..1ee57d1 116e871..8e41ba2

  1:  e8823d9851 =   1:  e8823d9851 Concurrent PSBT spec
  2:  eaeb02395e =   2:  eaeb02395e Render math before mdbook-graphviz re-serializes the markdown
  3:  45d04a7c65 =   3:  45d04a7c65 [WIP] Nest indented index entries as sub-chapters
  4:  e5cca8913e =   4:  e5cca8913e Arrange the index into the parts proposed in #19
  5:  f71ae6bd74 =   5:  f71ae6bd74 Radix coinjoin denominations notebook
  6:  cd8717c6e3 =   6:  cd8717c6e3 add a notebook derivation and a devshell for editing the notebook
  7:  074f2043e6 =   7:  074f2043e6 re-render notebook outputs with the notebook derivation
  8:  c694d0f6b8 =   8:  c694d0f6b8 count combinations with replacement as multisets
  9:  8e5f763477 =   9:  8e5f763477 clarify the notebook introduction
 10:  3ab0a79a2e =  10:  3ab0a79a2e count combinations of up to k denominations, as the sumsets do
 11:  9c9b6c7189 =  11:  9c9b6c7189 skip the median, not the 25th percentile, among the quantile dots
 12:  08ef6aaccc =  12:  08ef6aaccc clarify the sub-transaction counting argument
 13:  34c8624554 =  13:  34c8624554 explain why sums are cut off above a multiple of max_denom
 14:  adef92720d =  14:  adef92720d explain subset sum density as an invariant of the mapping
 15:  92be6a91e9 =  15:  92be6a91e9 Abstract cost function
 16:  b45805e9b2 =  16:  b45805e9b2 render jupyter notebook chapters as mdbook pages: hide code, paginate tables
 17:  f7f60c5d6c =  17:  f7f60c5d6c [WIP] ████████████████████ Clarify abstract cost function
 18:  4c0c04bdde =  18:  4c0c04bdde assemble notebook chapters from docs/
 19:  c9657fb600 =  19:  c9657fb600 fixup! Abstract cost function
 20:  46bd912aab =  20:  46bd912aab style plots: theme-neutral, colorblind-safe, re-rendered outputs
 21:  d8cc781d87 =  21:  d8cc781d87 [WIP] ████████████████████ Record decision tree construction notes
 22:  fb7eaf4a88 =  22:  fb7eaf4a88 point links to notebook chapters at their rendered pages
 23:  d2188cce83 =  23:  d2188cce83 [WIP] ████████████████░░░░ Describe how the decision tree is built
 24:  12882cc08a =  24:  12882cc08a Skip separators and part titles when walking the book's chapters
 25:  f251904ed0 =  25:  f251904ed0 [WIP] Add the cost function's words to the spelling dictionary
 26:  3090962f8b =  26:  3090962f8b nb-table: print every row of paginated tables
 27:  3db8bc429b =  27:  3db8bc429b fixup! [WIP] ████████████████████ Clarify abstract cost function
 28:  7eb96cdf62 =  28:  7eb96cdf62 keep bar value labels black over the bar fills
 29:  f1e0775403 =  29:  f1e0775403 fixup! Abstract cost function
 30:  3bbaca1af3 =  30:  3bbaca1af3 outline density series to read on dark pages
 31:  dfeb856e29 =  31:  dfeb856e29 fixup! Abstract cost function
 32:  72b2b36caf =  32:  72b2b36caf restore the density plot's legend frame
 33:  d2fd00eccb =  33:  d2fd00eccb fixup! Abstract cost function
 34:  f08d2541b1 =  34:  f08d2541b1 stop claiming six outputs close every gap above dust
 35:  ba2dc096f8 =  35:  ba2dc096f8 fixup! Abstract cost function
 36:  332eb9a07a =  36:  332eb9a07a Keep the powers below the dust threshold until they are multiplied
 37:  1dc15c0962 =  37:  1dc15c0962 [WIP] Order inputs before outputs within a batch
 38:  ce1e6b3aa5 =  38:  ce1e6b3aa5 Say that the gap plot's k=6 quantiles start at 2, not 1
 39:  1a8d01c6d1 =  39:  1a8d01c6d1 [WIP] Model time dependence as piecewise linear offsets
 40:  8b3cd62799 =  40:  8b3cd62799 Bound the terms of a sum above the cutoff by its size alone
 41:  64b6dd7261 =  41:  64b6dd7261 [WIP] Say what each end of the bracket means
 42:  60483321e7 =  42:  60483321e7 Say that a k:1 exchange changes the weight, not the fee
 43:  7cb54eb1ca =  43:  7cb54eb1ca [WIP] Distinguish the pure and mixed strategies
 44:  4e0549d28c =  44:  4e0549d28c Qualify the density argument by the denominations that remain
 45:  dca8177394 =  45:  dca8177394 [WIP] Describe commitment in multiparty protocols
 46:  3d0b9d7731 =  46:  3d0b9d7731 Define the on-chain privacy problems being addressed
 47:  f466a31550 =  47:  f466a31550 Show the denomination generating code in the book
 48:  c0d0ac8041 =  48:  c0d0ac8041 [WIP] Rewrite the global privacy budget
 49:  69cc0361bf =  49:  69cc0361bf Edits to Collaborative Transaction Privacy (#30)
 50:  c9cc193580 =  50:  c9cc193580 Coalition formation
 51:  4f8b8cc681 =  51:  4f8b8cc681 Show the sumset and gap computation code in the book
 52:  d98dc69986 =  52:  d98dc69986 Fix typos and a broken anchor in the concurrent PSBT spec
 53:  26f0b2c05c =  53:  26f0b2c05c [WIP] ████████████████░░░░ Penalize co-spend proposals that leak a counterfactual path
 54:  5cb76884a7 =  54:  5cb76884a7 Revise and clarify following editorial pass
 55:  1d16c3d371 =  55:  1d16c3d371 [WIP] ████████████████░░░░ Add input value constraints to proposal conditions
 56:  0b760af3e8 =  56:  0b760af3e8 Show the analysis parameters in the book
 57:  ae28f03f0e =  57:  ae28f03f0e Move the concurrent PSBT spec into the book
 58:  50ab0fc9c6 =  58:  50ab0fc9c6 fixup! [WIP] ████████████████░░░░ Describe how the decision tree is built
 59:  59ce690b06 =  59:  59ce690b06 fixup! [WIP] Say what each end of the bracket means
 60:  ada41525c2 =  60:  ada41525c2 [WIP] ████████████████████ Describe the greedy decision loop
 61:  a3a6ae2197 =  61:  a3a6ae2197 [WIP] ████████████████████ Give the decision loop its own heading
 62:  d8c739a4c5 =  62:  d8c739a4c5 [WIP] ██████████████████░░ Move tree construction to the strategy chapter
 63:  480d87164c =  63:  480d87164c [WIP] ████████████████░░░░ Rename the chapter to Optimization framework
 64:  424d28b5e5 =  64:  424d28b5e5 [WIP] ████████████████████ Introduce the strategy as generating and evaluating decisions
 65:  2e3c4c14eb =  65:  2e3c4c14eb [WIP] ████████████████░░░░ Move the mixed strategy into its own chapter
 66:  1241a68935 =  66:  1241a68935 [WIP] Add the Pure Strategy Evaluation chapter
 67:  66962a56d1 =  67:  66962a56d1 [WIP] ████████████████░░░░ Mark agent-generated text with 🤖
 68:  746b8a2055 =  68:  746b8a2055 [WIP] Add the Tactics chapter
 69:  9db08a16d9 =  69:  9db08a16d9 [WIP] Call the greedy loop a decision loop run as a greedy search
 70:  d144f76af6 =  70:  d144f76af6 [WIP] Add the Privacy liability terms chapter
 71:  3746f2e362 =  71:  3746f2e362 Add an overview
 72:  564eafe255 =  72:  564eafe255 [WIP] Specify peer and broadcast channels
 73:  0f938de8c3 =  73:  0f938de8c3 [WIP] Move the cost function's structure into its own chapter
 74:  8ae2f824a6 =  74:  8ae2f824a6 [WIP] Describe what each privacy liability term is for
 75:  8080f864df =  75:  8080f864df Link the optimization framework chapter by its new file name
 76:  12dfe894df =  76:  12dfe894df [WIP] Compare candidate transports for the channels
 77:  59bd9579e0 =  77:  59bd9579e0 Move the problem definition into the mdbook
 78:  380b9bd4f6 =  78:  380b9bd4f6 [WIP] Link the Tactics and Privacy liability terms chapters
 79:  ae24c1a125 =  79:  ae24c1a125 [WIP] Outline max flow based counterfactual path estimation
 80:  4a94f1c4a8 =  80:  4a94f1c4a8 [WIP] Outline the consolidation penalty
 81:  f410526ff3 =  81:  f410526ff3 [WIP] Outline subset sum density, subset sum ambiguity and the sibling output penalty
 82:  89dfa42770 =  82:  89dfa42770 [WIP] Add the randomized selection and Sybil resistance chapters
 83:  3e10b5d2e9 =  83:  3e10b5d2e9 [WIP] Add the Bottom-up construction chapter
 84:  bc18c81547 =  84:  bc18c81547 [WIP] Group the privacy metrics after the privacy liability terms
 85:  686efeeae4 =  85:  686efeeae4 [WIP] Point the overview at the channel interfaces and asymmetric trust
 86:  d483a2ee8f =  86:  d483a2ee8f [WIP] Specify the protocol messages
 87:  89a6e005e9 =  87:  89a6e005e9 [WIP] Specify contacts and payment messaging
 88:  31f505ed43 =  88:  31f505ed43 [WIP] Move the BIP 322 gossip rules into peer to world broadcast
 89:  dd81be7d24 =  89:  dd81be7d24 [WIP] Specify the abstract transport interfaces
 90:  330989bc4b =  90:  330989bc4b Refer to the Radix CoinJoin Denominations chapter
 91:  915c548aaf =  91:  915c548aaf README do-over
 93:  c7a5c9ca5a =  92:  c7a5c9ca5a [WIP] Specify peer set reconciliation
 94:  b1b1e23160 =  93:  b1b1e23160 [WIP] Distinguish lists from sets, not DAG from non-DAG
 95:  8183885159 =  94:  8183885159 [WIP] Specify the allocation registration validity proofs
 96:  786eefe3ec =  95:  786eefe3ec [WIP] Specify the recovery track
 97:  eae73a6fa0 =  96:  eae73a6fa0 [WIP] Specify the block DAG
 98:  2b8c84d848 =  97:  2b8c84d848 [WIP] Introduce transaction construction
 99:  950eca6f64 =  98:  950eca6f64 [WIP] Specify the optimistic track
 92:  044726af51 !  99:  e6b5b0b793 [WIP] Move the BIP 322 gossip rules to peer to world broadcast
100:  1ee57d1562 = 100:  8e41ba243d [WIP] Serve the draft from /docs-draft/
92: 044726af51 ! 99: e6b5b0b793 [WIP] Move the BIP 322 gossip rules to peer to world broadcast
@@ docs/coalition_formation.md: Finally, PQ privacy must of course also assume that
  ### Transaction construction protocol
  
 -A transaction construction protocol can provide liveness, although in this setting, relying on KVACs would require one of the peers to serve as the coordinator, and it would be trusted. With modification, this coordinator could prove all transcript messages it accepted are valid, but may still arbitrarily censor certain operations, causing a UTXO to be unfairly blamed for failing to sign.
-+🤖 The accepted coalition formation proposal specifies the initial inputs, their online keys, the negotiated adjustments and the parameters for [transaction construction](transaction-construction.md). It is the genesis of the construction instance. The initial state can be proven valid with respect to each UTXO's adjustment sum commitments, which enforces that the agreed imputation is in effect.
++🤖 The accepted coalition formation proposal specifies the initial inputs, their online keys, the negotiated adjustments and the parameters for [transaction construction](transaction-construction.md). It is the genesis of the construction instance. The initial state can be proven valid with respect to each UTXO's adjustment sum commitments, which enforces that the agreed imputation is in effect. When construction stalls, the [recovery track](recovery-track.md) turns the stall into a new coalition formation proposal among the responsive subset.
  
 -Technically the coalition formation proposal can implement a coordination fee mechanism — for example, by making all adjustments slightly negative, apart from that of the coordinator (which may or may not be the aggregator). This provides the coordinator with an incentive to coordinate honestly on average. Unfortunately, this does little for any targeted censorship risk, so long as the payoff from censorship (of e.g. a specific TxOut) dominates over the expected loss of revenue from sabotaging a single attempt at transaction construction. It's likely that the majority of the revenue is still recoverable in a subsequent blame round, as the other participants have no indication that censorship has occurred.
 +🤖 Any participant can act as an aggregator. Assembling a proposal gives that participant no additional privileges during transaction construction.

@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/channels.md

  • l.47 - "UTXOs that provides" → "UTXOs that provide"
  • l.49 - "encoded of the cost function" → "encoded in the cost function"
  • l.69 - "gossipped" → "gossiped"
  • l.69 - "is just be a hash" → "is just a hash"

docs/coalition_formation.md

  • l.76 - "the honest subset peers" → "the honest subset of peers"

oak · automated

Comment thread docs/recovery-track.md

- each started successor costs the adversary at least one coin, apart from option A's counterparty exception;
- a late pass starts nothing, so it creates no new attempt;
- a participant accepts at most one successor per stalled phase;

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Recovery accepts conflict with one-successor rule

The acceptance section says a participant may accept competing successors of the same stalled phase, but this privacy bullet says it accepts at most one. The two rules cannot both be implemented, and the privacy and boundary-split analysis depends on which one holds.

oak · automated · 8e41ba2

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

the privacy bullet is wrong, although directionally correct - participants should not accept an unbounded number of proposals, but there is no requirement for recovery coalition formation proposals to be linearized or synchronized in any way

the problem with accepting all proposals is that this necessarily reveals some information:

  • when a participant is active
  • what their preferences may be (e.g. consider probing with co-spend proposals until a feerate threshold is discovered, and then knowing that feerate, differentiating with respect to the other elements of the co-spend proposals to ellicit information about preferences with respect to various UTXOs, constraints, etc)

a participant should add some noise to their preferences and limit how much they negotiate, which applies to recovery sessions especially since DoS amplifies privacy leaks, c.f. https://dl.acm.org/doi/10.1145/1315245.1315258 (loosely related)

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

something i meant to add to the coalition formation chapter is a few worked examples. noting here since it's relevant to this point too:

a trivial co-spend proposal is one involving just a single UTXO and surplus, no fee adjustment. this does not benefit from any fee fuzzing, but minimally reveals preferences through the transaction constraints. this is also suitable for light clients who do not wish to interact with the order book directly, delegating order matching to the aggregator. notably, relaxing the requirement that the aggregator own an input makes possible aggregation by some generic service, cc @zealsham, but the cryptography would preclude earning any fees (essentially coordinator fees) without also contributing an input, so i'm leaning towards just requiring an input. other semi-centralized special cases of coordination responsibilities are discussed in the DAG sections.

then for demonstrating privacy optimization concretely, a few more co-spend proposals make sense:

  • a sub-coalition of several "lucky" market makers collectively bargaining for a larger fee payoff, by posting a negative surplus
  • a radix coinjoin equivalence class of UTXOs, and nominal input value constraints for radix coinjoin guarantees
  • heterogenous / complementary values and sumset density certificates
  • two mutually trusting parties who wish to make an interactive payment selecting some coins to their dissimilar inputs as cover, without revealing each others' specific inputs among the decoy set selected by each party, and without either party revealing to the world their identity or relationship within the union of their decoy sets

Comment thread docs/protocol-messages.md
- the Merkle set commitment of its parent blocks;
- the Merkle set commitment of the gossiped transaction construction messages it includes;
- its parent block by the same node;
- the nonce point R its successor will be signed with.

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Block format drops recovery nonce commitment

This block format lists a single nonce point, while the block DAG requires separate optimistic and recovery nonce points and selects the point by track. A block built from this description cannot satisfy the track-specific signing rule, and the two descriptions disagree on the data needed to detect equivocation.

oak · automated · 8e41ba2

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

the block DAG specification is correct, we need one R point per track

@bc1cindy
bc1cindy requested a review from oakagent October 26, 2026 17:03
Comment thread book.toml
additional-css = ["theme/diagrams.css"]
git-repository-url = "https://github.com/fungi-protocol/docs"
site-url = "/docs/"
site-url = "/docs-draft/"

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Not-found page base points to a path the Pages workflow does not deploy

On merge, the Pages workflow publishes the site at /docs/ (as docs/README.md documents), but site-url makes mdbook write <base href="/docs-draft/"> into the 404 page, so its CSS and JS resolve under a path the workflow does not deploy.

oak · automated · 8e41ba2

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

this is an artifact of me pushing that to the other repo, this modification shouldn't be merged in this repo but is correct over there

Comment thread docs/protocol-messages.md
| [Session initialization](#session-initialization) | Start a construction session | all |
| [Transaction construction](#transaction-construction) | Build the transaction | all |
| [Interactive payments](#interactive-payments) | Grant funds and confirm payments | honest, semi-honest |
| [Blocks](#blocks) | Synchronize state and signal phase changes | semi-honest, Byzantine |

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Docs disagree on blocks in the honest setting

The blocks row restricts blocks to the semi-honest and Byzantine settings, but transaction-construction says both tracks use the block DAG and the optimistic track is sufficient in the honest setting. Implementers cannot tell whether the honest setting uses blocks.

oak · automated · 8e41ba2

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

strictly speaking naive gossip with no consistency guarantees is still safe to use, and with deterministic ordering also ensure convergence on transcript with high probability the larger the transaction. there is no safety requirement for synchronization.

synchronization can, however, reduce the number of times the spending keys are accessed to the minimum, so this is desirable in both of these settings as a UX consideration, and to allow more efficient communications.

as a separate consideration, the honest and semi-honest threat model do not differ in this either, in both we assume liveness is not being attacked, and the question is about how non-byzantine fault tolerance, i.e. the communication model being assumed (timeout behavior, etc). this too is primarily a UX consideration.

for MVP the recovery track can be omitted and async communication model & optimistic track can be assumed, semi-honest & honest threat models only. this is arguably not the the most minimal minimally viable thing, but i see no benefit to not going directly to that for the coordination layer, choosing when to sign without a synchronization mechanism without one would be hacky and fragile (waiting for quiesence)

Comment thread contrib/book.py Outdated
"""A notebook's frontmatter, as a markdown page would have it, if a
raw cell holding nothing else opens it, and the notebook without it."""
nb = json.loads(text)
cells = nb.get("cells", [])

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Non-object notebook JSON crashes check with AttributeError

A notebook file containing [] makes nb.get raise AttributeError, which check does not wrap, so the build fails with a traceback that omits the filename.

oak · automated · 8e41ba2

@bc1cindy
bc1cindy requested a review from oakagent October 27, 2026 15:20

@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 8e41ba2 again: nothing to add to the earlier comments.

oak · automated

mdbook-graphviz re-serializes every chapter, escaping characters such
as `[`, `_` and `\` along the way. It and mdbook-katex were both only
ordered after `links`, and mdbook happened to run graphviz first, so
katex saw the escaped source: a formula like `$t \in [a, b]$` reached
it as `$t \\in \[a, b\]$`, failed to parse, and was left in the page
as raw TeX.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@oakagent oakagent mentioned this pull request Nov 9, 2026
nothingmuch and others added 2 commits November 10, 2026 01:31
An index entry indented two spaces more than the entry above it becomes a
sub-chapter of that entry in SUMMARY.md, which mdbook numbers and shows as
nested in the sidebar. The contents page copies the index, so it nests the same
way.

Note that this is idiosyncratic with respect to OKF v0.2, which specifies only
flat index entries. The more OKF native way to nest is a sub-directory with its
own index.md, such as docs/tactics/index.md, listed by the root index as one
entry. Indented entries keep the files where they are; moving to sub-indexes is
a possible follow-up.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Move the cost function framework stub to optimization_framework.md, and group
the index into the parts proposed in #19.

This adds stubs for all chapters in the draft so that there are valid targets
for cross-reference links, allowing each chapter's PR to be independently
opened and pass checks without needing to add links in a second PR.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@yuval-block

Copy link
Copy Markdown
Collaborator Author

cc @xstoicunicornx this can be thought of as a sort of tracking issue for all of the spec chapters, as i slowly finalize things i plan to open PRs, happy to already open draft PRs for some of the less sloppy chapters if they seem like they could use more focused review

currently finding oakagent's feedback useful here, and using it to save some notes for additional improvements, i think i will do a few more LLM passes before converting to meat slop, most of this is dry spec so not as important as README, overview, problem definition and abstract cost function chapters which are more conceptual so i was more ready to accept LLM output expanding my outlines etc, but i'm still a bit wary of opening PRs for most of this

@github-actions

Copy link
Copy Markdown
range-diff for force push 8e41ba243d → dbe0d25372 November 10, 2026 01:21 UTC: 31 modified, 66 unchanged, 3 dropped, 10 added

reproduce: git range-diff 116e871..8e41ba2 cbb5404..dbe0d25

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

  1:  e8823d9851 =   1:  e8823d9851 Concurrent PSBT spec
  2:  eaeb02395e =   2:  2fe2e8f9f4 Render math before mdbook-graphviz re-serializes the markdown
  3:  45d04a7c65 !   3:  8dd55aaff4 [WIP] Nest indented index entries as sub-chapters
  4:  e5cca8913e !   4:  01217000e0 Arrange the index into the parts proposed in #19
  5:  f71ae6bd74 =   5:  3c2976fa71 Radix coinjoin denominations notebook
  6:  cd8717c6e3 =   6:  18e6a34368 add a notebook derivation and a devshell for editing the notebook
  7:  074f2043e6 =   7:  3e6af68406 re-render notebook outputs with the notebook derivation
  8:  c694d0f6b8 =   8:  1d5c95986d count combinations with replacement as multisets
  9:  8e5f763477 =   9:  4e31859369 clarify the notebook introduction
 10:  3ab0a79a2e =  10:  1e48ab2a74 count combinations of up to k denominations, as the sumsets do
 11:  9c9b6c7189 =  11:  b92dd12461 skip the median, not the 25th percentile, among the quantile dots
 12:  08ef6aaccc =  12:  71f872f3db clarify the sub-transaction counting argument
 13:  34c8624554 =  13:  d0f701b2d3 explain why sums are cut off above a multiple of max_denom
 14:  adef92720d =  14:  e2e04bc2cb explain subset sum density as an invariant of the mapping
 16:  b45805e9b2 =  15:  f083d06355 render jupyter notebook chapters as mdbook pages: hide code, paginate tables
 18:  4c0c04bdde !  16:  7b97cf6a78 assemble notebook chapters from docs/
 20:  46bd912aab =  17:  96d6a3d029 style plots: theme-neutral, colorblind-safe, re-rendered outputs
 22:  fb7eaf4a88 =  18:  21839237c6 point links to notebook chapters at their rendered pages
 24:  12882cc08a =  19:  fda57dffdb Skip separators and part titles when walking the book's chapters
 26:  3090962f8b =  20:  21c056bdf5 nb-table: print every row of paginated tables
 28:  7eb96cdf62 =  21:  6ff83f0b7a keep bar value labels black over the bar fills
 30:  3bbaca1af3 =  22:  207f2f8a9e outline density series to read on dark pages
 32:  72b2b36caf =  23:  f7dfe4e094 restore the density plot's legend frame
 46:  3d0b9d7731 =  24:  3bccc89af9 Define the on-chain privacy problems being addressed
 34:  f08d2541b1 =  25:  40e42443d9 stop claiming six outputs close every gap above dust
 49:  69cc0361bf =  26:  3703714fb2 Edits to Collaborative Transaction Privacy (#30)
 36:  332eb9a07a =  27:  52769f7f5a Keep the powers below the dust threshold until they are multiplied
 54:  5cb76884a7 =  28:  1e6321cb44 Revise and clarify following editorial pass
 38:  ce1e6b3aa5 =  29:  e582b564df Say that the gap plot's k=6 quantiles start at 2, not 1
 72:  564eafe255 =  30:  8971acf3e5 [WIP] Specify peer and broadcast channels
 77:  59bd9579e0 !  31:  46c4dd630c Move the problem definition into the mdbook
 40:  8b3cd62799 =  32:  6580268846 Bound the terms of a sum above the cutoff by its size alone
 76:  12dfe894df =  33:  a6c7251338 [WIP] Compare candidate transports for the channels
 90:  330989bc4b =  34:  934939d950 Refer to the Radix CoinJoin Denominations chapter
 66:  1241a68935 =  35:  512c0ed394 [WIP] Add the Pure Strategy Evaluation chapter
 42:  60483321e7 =  36:  7385b65b40 Say that a k:1 exchange changes the weight, not the fee
 80:  4a94f1c4a8 =  37:  ea80b60e13 [WIP] Outline the consolidation penalty
 83:  3e10b5d2e9 =  38:  befaec25b0 [WIP] Add the Bottom-up construction chapter
 86:  d483a2ee8f !  39:  43a5439f09 [WIP] Specify the protocol messages
 87:  89a6e005e9 =  40:  22be9dc41c [WIP] Specify contacts and payment messaging
 88:  31f505ed43 !  41:  95aca97bcb [WIP] Move the BIP 322 gossip rules into peer to world broadcast
  -:  ---------- >  42:  2c11278670 Cite Gavenda et al. in the sub-transaction mapping section
 91:  915c548aaf =  43:  390ea1246f README do-over
 15:  92be6a91e9 !  44:  e72354730d Abstract cost function
 17:  f7f60c5d6c !  45:  80985c2621 [WIP] ████████████████████ Clarify abstract cost function
 19:  c9657fb600 !  46:  c9e91e42b9 fixup! Abstract cost function
 21:  d8cc781d87 =  47:  cc18450cdc [WIP] ████████████████████ Record decision tree construction notes
 23:  d2188cce83 =  48:  ad3f201e4a [WIP] ████████████████░░░░ Describe how the decision tree is built
 25:  f251904ed0 <   -:  ---------- [WIP] Add the cost function's words to the spelling dictionary
 27:  3db8bc429b =  49:  ad8a00313b fixup! [WIP] ████████████████████ Clarify abstract cost function
 29:  f1e0775403 =  50:  806e78a4f8 fixup! Abstract cost function
 31:  dfeb856e29 =  51:  ea828dd167 fixup! Abstract cost function
 33:  d2fd00eccb =  52:  4029c1f384 fixup! Abstract cost function
 35:  ba2dc096f8 !  53:  30a31f15ef fixup! Abstract cost function
 37:  1dc15c0962 =  54:  edb7c0f229 [WIP] Order inputs before outputs within a batch
 39:  1a8d01c6d1 =  55:  5fb552f0ec [WIP] Model time dependence as piecewise linear offsets
 41:  64b6dd7261 =  56:  63f9548074 [WIP] Say what each end of the bracket means
 43:  7cb54eb1ca !  57:  0c02c686d6 [WIP] Distinguish the pure and mixed strategies
 45:  dca8177394 =  58:  b033c44353 [WIP] Describe commitment in multiparty protocols
 48:  c0d0ac8041 =  59:  c8862c7061 [WIP] Rewrite the global privacy budget
 53:  26f0b2c05c =  60:  c16aaf5547 [WIP] ████████████████░░░░ Penalize co-spend proposals that leak a counterfactual path
 58:  50ab0fc9c6 =  61:  d10c6c06de fixup! [WIP] ████████████████░░░░ Describe how the decision tree is built
 59:  59ce690b06 =  62:  8c9b0d82fb fixup! [WIP] Say what each end of the bracket means
 60:  ada41525c2 =  63:  3d7329bf6d [WIP] ████████████████████ Describe the greedy decision loop
 61:  a3a6ae2197 =  64:  a31cfc82f6 [WIP] ████████████████████ Give the decision loop its own heading
 50:  c9cc193580 !  65:  96a1cdb35e Coalition formation
 68:  746b8a2055 !  66:  5104bedc29 [WIP] Add the Tactics chapter
 44:  4e0549d28c =  67:  9698ef7eb4 Qualify the density argument by the denominations that remain
 62:  d8c739a4c5 =  68:  14f70a784b [WIP] ██████████████████░░ Move tree construction to the strategy chapter
 55:  1d16c3d371 =  69:  47d02eeffd [WIP] ████████████████░░░░ Add input value constraints to proposal conditions
 70:  d144f76af6 =  70:  bd50030469 [WIP] Add the Privacy liability terms chapter
 47:  f466a31550 =  71:  b18bfa10de Show the denomination generating code in the book
 63:  480d87164c =  72:  bd2a789516 [WIP] ████████████████░░░░ Rename the chapter to Optimization framework
  -:  ---------- >  73:  c35c9ecb4b [WIP] Replace coalition formation text superseded by the protocol chapters
 74:  8ae2f824a6 !  74:  d91137c1c2 [WIP] Describe what each privacy liability term is for
 92:  c7a5c9ca5a !  75:  8cb7169d4a [WIP] Specify peer set reconciliation
 51:  4f8b8cc681 =  76:  2277e026fe Show the sumset and gap computation code in the book
 52:  d98dc69986 =  77:  09c0e6a269 Fix typos and a broken anchor in the concurrent PSBT spec
 64:  424d28b5e5 =  78:  82655b3841 [WIP] ████████████████████ Introduce the strategy as generating and evaluating decisions
  -:  ---------- >  79:  cdbbae24c4 [WIP] Move the coalition formation games text from the overview
 95:  786eefe3ec !  80:  478fb1df65 [WIP] Specify the recovery track
 96:  eae73a6fa0 !  81:  a6d9e142a5 [WIP] Specify the block DAG
 97:  2b8c84d848 !  82:  2485849480 [WIP] Introduce transaction construction
 89:  dd81be7d24 !  83:  c1ae9df1ed [WIP] Specify the abstract transport interfaces
 79:  ae24c1a125 !  84:  934f3c5723 [WIP] Outline max flow based counterfactual path estimation
 81:  f410526ff3 !  85:  a71722105e [WIP] Outline subset sum density, subset sum ambiguity and the sibling output penalty
 82:  89dfa42770 !  86:  cc90552b7a [WIP] Add the randomized selection and Sybil resistance chapters
 84:  bc18c81547 !  87:  4e5eec71e2 [WIP] Group the privacy metrics after the privacy liability terms
 93:  b1b1e23160 !  88:  dda51210ea [WIP] Distinguish lists from sets, not DAG from non-DAG
 94:  8183885159 !  89:  f7080c72c8 [WIP] Specify the allocation registration validity proofs
 98:  950eca6f64 !  90:  90917b642b [WIP] Specify the optimistic track
 56:  0b760af3e8 =  91:  a0948d4228 Show the analysis parameters in the book
 57:  ae28f03f0e !  92:  c7b1c9d7e2 Move the concurrent PSBT spec into the book
 65:  2e3c4c14eb =  93:  e3e7a4a3f4 [WIP] ████████████████░░░░ Move the mixed strategy into its own chapter
 67:  66962a56d1 =  94:  0979865daa [WIP] ████████████████░░░░ Mark agent-generated text with 🤖
 69:  9db08a16d9 =  95:  e075273c68 [WIP] Call the greedy loop a decision loop run as a greedy search
 73:  0f938de8c3 !  96:  8b59e00bfc [WIP] Move the cost function's structure into its own chapter
 78:  380b9bd4f6 !  97:  bae6dfd3ed [WIP] Link the Tactics and Privacy liability terms chapters
 71:  3746f2e362 !  98:  6a66aa533b Add an overview
 75:  8080f864df <   -:  ---------- Link the optimization framework chapter by its new file name
 85:  686efeeae4 <   -:  ---------- [WIP] Point the overview at the channel interfaces and asymmetric trust
  -:  ---------- >  99:  16cb126130 First round edits of Overview
  -:  ---------- > 100:  baa4bc3c84 First round edits of Overview
  -:  ---------- > 101:  a19176263d First round edits of Overview
  -:  ---------- > 102:  b4e9e2b6d5 First round edits of Overview
  -:  ---------- > 103:  4131b8c13a First round edits of Overview
  -:  ---------- > 104:  f53bb94928 First round edits of Overview
  -:  ---------- > 105:  405921f46c [WIP] Point the overview at the channel interfaces and asymmetric trust
 99:  e6b5b0b793 ! 106:  0f0e4e3754 [WIP] Move the BIP 322 gossip rules to peer to world broadcast
100:  8e41ba243d = 107:  dbe0d25372 [WIP] Serve the draft from /docs-draft/
3: 45d04a7c65 ! 3: 8dd55aaff4 [WIP] Nest indented index entries as sub-chapters
@@ Metadata
 Author: Yuval Kogman <nothingmuch@woobling.org>
 
  ## Commit message ##
-    [WIP] Nest indented index entries as sub-chapters
+    Nest indented index entries as sub-chapters
 
-    An index entry indented two spaces more than the entry above it becomes
-    a sub-chapter of that entry in SUMMARY.md, which mdbook numbers and
-    shows as nested in the sidebar. The contents page copies the index, so
-    it nests the same way.
+    An index entry indented two spaces more than the entry above it becomes a
+    sub-chapter of that entry in SUMMARY.md, which mdbook numbers and shows as
+    nested in the sidebar. The contents page copies the index, so it nests the same
+    way.
 
… (truncated)
4: e5cca8913e ! 4: 01217000e0 Arrange the index into the parts proposed in #19
@@ Metadata
  ## Commit message ##
     Arrange the index into the parts proposed in #19
 
-    Move the cost function framework stub to optimization_framework.md,
-    and group the index into the parts proposed in #19.
+    Move the cost function framework stub to optimization_framework.md, and group
+    the index into the parts proposed in #19.
 
-    Add review stubs for the protocol chapters, with their final index
-    entries. Each stub carries the headings other chapters link to, so
-    each chapter's pull request can replace its stub without touching the
-    index, and links between chapters resolve whichever lands first. The
-    concurrent PSBT stub gains the heading the overview links to.
-
-    Groth, from Groth16, is a name, not a misspelling of growth.
+    This adds stubs for all chapters in the draft so that there are valid targets
+    for cross-reference links, allowing each chapter's PR to be independently
+    opened and pass checks without needing to add links in a second PR.
 
     Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
 
@@ docs/block-dag.md (new)
 +
… (truncated)
18: 4c0c04bdde ! 16: 7b97cf6a78 assemble notebook chapters from docs/
@@ docs/Denominations_and_gap_size_distributions.ipynb
 
  ## docs/index.md ##
 @@ docs/index.md: okf_version: "0.2"
- # Privacy Optimization Strategy
+ * [🤖 Mixed strategy](mixed_strategy.md) - How to compose a mixed strategy from the cost of pure strategies: randomization, time dependence, internalization and the decision loop.
+ * [Tactics](tactics.md) - Generating the decision tree bottom up, with coin selection and change decomposition, and when to re-evaluate it.
+   * [Bottom-up construction](bottom_up_construction.md) - Building the decision tree from the leaves: partitions of the intent queue, coin selection, change construction, order book coins, action sequences, and bracketing.
… (truncated)
77: 59bd9579e0 ! 31: 46c4dd630c Move the problem definition into the mdbook
@@ docs/collaborative_txn_privacy.md
 +[^scam-exchanges]: Unsurprisingly, the most aggressive compliance posturing has historically often come from businesses that later collapsed, namely FTX, whose executives were convicted of fraud, and BlockFi, which settled SEC charges that included materially false statements before going under in FTX's wake.
 +
 +[^proximity]: Not exactly the same, since both temporal patterns and the number of hops make a difference. This can be addressed by ensuring the length of the actual path taken is consistent with the distribution of lengths of the counterfactual paths.
-
- ## docs/index.md ##
-@@
- okf_version: "0.2"
- ---
- 
--* [Collaborative transaction privacy](collaborative_txn_privacy.md) - Under review in #7.
-+# Problem Statement
-+
-+* [Collaborative transaction privacy](collaborative_txn_privacy.md) - Challenges for privacy in multiparty transaction settings, from PayJoin to CoinJoin.
- 
- # Protocol Suite
- 
86: d483a2ee8f ! 39: 43a5439f09 [WIP] Specify the protocol messages
@@ docs/protocol-messages.md
 +| pull | object hash | requests an announced object |
 +| push | object | solicited: answers a pull |
 +
-+🤖 Small messages are pushed eagerly to neighbors. A block is pushed as just its header, expecting the receiver to already know its Merkle tree.
++Small messages are pushed eagerly to neighbors. A block is pushed as just its header, expecting the receiver to already know its Merkle tree.
 +
-+🤖 After an anonymous submission enters the broadcast domain, peers disseminate it by gossip or set reconciliation. Anonymous submission does not replace dissemination.
++After an anonymous submission enters the broadcast domain, peers disseminate it by gossip or set reconciliation. Anonymous submission does not replace dissemination.
 +
 +### Unsolicited push
 +
@@ docs/protocol-messages.md
… (truncated)
88: 31f505ed43 ! 41: 95aca97bcb [WIP] Move the BIP 322 gossip rules into peer to world broadcast
@@ docs/channels.md: These travel over neighbor channels. The minimal set suffices
  
  The semi-honest and Byzantine settings add **unsolicited push**, used for anonymous broadcast. A peer that receives a new unsolicited message pushes it to one randomly selected neighbor, and announces it to its other neighbors. This is a candidate policy, not an established anonymity guarantee.
  
-+🤖 Anonymous submission introduces a message into the broadcast domain. Once received, the message is disseminated by gossip or set reconciliation. The submission mechanism and the subsequent dissemination serve different purposes.
++Anonymous submission introduces a message into the broadcast domain. Once received, the message is disseminated by gossip or set reconciliation. The submission mechanism and the subsequent dissemination serve different purposes.
 +
  ## Anonymous submission
15: 92be6a91e9 ! 44: e72354730d Abstract cost function
@@ docs/optimization_framework.md
 @@
  ---
 -type: Stub
+-title: Optimization framework for Bitcoin wallets
 +type: concept
- title: Cost function framework for Bitcoin wallets
++title: Cost function framework for Bitcoin wallets
  status: draft
 -stale_after: 2027-04-15T00:00:00Z
 +stale_after: 2026-10-31T00:00:00Z
  ---
  
- # Cost function framework for Bitcoin wallets
+-# Optimization framework for Bitcoin wallets
++# Cost function framework for Bitcoin wallets
  
 -This chapter is under review in [#15](https://github.com/fungi-protocol/docs/pull/15). Its draft is on [the pull request's branch](https://github.com/fungi-protocol/docs/blob/cost-function-abstract/cost_function.md).
 +This document describes how score the outcomes of transacting on Bitcoin, in particular privacy outcomes. This is the basis for automating various decisions delegated by the user to the wallet.
-+
+ 
+-Other chapters link to these sections:
 +## Coin selection with objective costs
-+
+ 
… (truncated)
17: f7f60c5d6c ! 45: 80985c2621 [WIP] ████████████████████ Clarify abstract cost function
@@ docs/optimization_framework.md: Sometimes it's possible to closely approximate t
  
  ### Future cost of spending (Bitcoin Core's waste metric)
  
+@@ docs/optimization_framework.md: On-chain privacy techniques in Bitcoin come in two flavors: overt, or covert. Ov
+ 
+ Both overt and covert techniques carry censorship risk. For overt techniques this is inherent, as the use of the technique is self-evident, and exchanges that may regard this as a compliance risk (which incidentally is more often the case for fraudulent exchanges) are more likely to reject or even confiscate deposits that are linkable to such techniques. For covert techniques, although the technique itself doesn't flag a deposit, it may result in counterfactual linking of the deposit funds to coins that are deemed tainted.
+ 
+-<!-- cspell:words Parameterizing -->
++<!-- cspell:words Parameterizing optzn -->
+ 
+ ## Parameterizing the cost function according to user preferences
+ 
 @@ docs/optimization_framework.md: As described in abstract terms above, a per intent deadline or confirmation targ
  
  The privacy sensitivity of a transaction determines whether the preferred behavior is to execute a payment even if privacy is sacrificed as the deadline approaches, or whether it's better to miss the deadline or even forego the transaction entirely if the payment cannot be made privately. This can be modeled as divergence towards negative or positive infinity after the deadline elapses.
19: c9657fb600 ! 46: c9e91e42b9 fixup! Abstract cost function
@@ docs/optimization_framework.md: On the other hand it may be the case that two pa
  
  Both overt and covert techniques carry censorship risk. For overt techniques this is inherent, as the use of the technique is self-evident, and exchanges that may regard this as a compliance risk (which incidentally is more often the case for fraudulent exchanges) are more likely to reject or even confiscate deposits that are linkable to such techniques. For covert techniques, although the technique itself doesn't flag a deposit, it may result in counterfactual linking of the deposit funds to coins that are deemed tainted.
  
+@@ docs/optimization_framework.md: Both overt and covert techniques carry censorship risk. For overt techniques thi
+ 
  ## Parameterizing the cost function according to user preferences
  
… (truncated)
35: ba2dc096f8 ! 53: 30a31f15ef fixup! Abstract cost function
@@ docs/optimization_framework.md: Let's momentarily ignore both the severity of th
 -Both overt and covert techniques carry censorship risk. For overt techniques this is inherent, as the use of the technique is self-evident, and exchanges that may regard this as a compliance risk (which incidentally is more often the case for fraudulent exchanges) are more likely to reject or even confiscate deposits that are linkable to such techniques. For covert techniques, although the technique itself doesn't flag a deposit, it may result in counterfactual linking of the deposit funds to coins that are deemed tainted.
 +Both overt and covert techniques carry censorship risk. For overt techniques this is inherent, as the use of the technique is self-evident, and exchanges that may regard this as a compliance risk (which incidentally is more often the case for fraudulent exchanges) are more likely to reject or even confiscate deposits that are linkable to such techniques. For covert techniques, although the technique itself doesn't flag a deposit, it may result in [counterfactual linking](collaborative_txn_privacy.md) of the deposit funds to coins that are deemed tainted.
  
- <!-- cspell:words Parameterizing -->
+ <!-- cspell:words Parameterizing optzn -->
43: 7cb54eb1ca ! 57: 0c02c686d6 [WIP] Distinguish the pure and mixed strategies
@@ docs/optimization_framework.md: This document describes how to score the outcome
  ## Preliminaries
  
 -TODO
--
++Automating the decisions delegated to a wallet is an optimization problem, and every optimization problem has a cost function.
+ 
 -- this is an optimization problem, every optzn problem has a cost function
 -- this actual cost function is a mixed strategy, we model it explicitly as a decision tree and we randomize
 -- the thing we call "the" cost function is a pure strategy, it evaluates specific contingencies
@@ docs/optimization_framework.md: This document describes how to score the outcome
 -    - privacy liabilities
 -    - payoffs from completing goals (e.g. making a payment)
 -  - every term is a piecewise linear function of time, terms evaluated and summed at a point in time
-+Automating the decisions delegated to a wallet is an optimization problem, and every optimization problem has a cost function.
… (truncated)
50: c9cc193580 ! 65: 96a1cdb35e Coalition formation
@@ docs/coalition_formation.md
 @@
  ---
 -type: Stub
--title: Market-based coalition formation for collaborative transaction construction
 +type: concept
-+title: Market-based coalition formation
+ title: Market-based coalition formation
  status: draft
 -stale_after: 2027-04-15T00:00:00Z
 +stale_after: 2027-01-23T00:00:00Z
  ---
  
--# Market-based coalition formation for collaborative transaction construction
… (truncated)
68: 746b8a2055 ! 66: 5104bedc29 [WIP] Add the Tactics chapter
@@ docs/tactics.md
  
 -This chapter is under review. Its draft is on [its branch](https://github.com/fungi-protocol/docs/blob/cost-function-concrete/docs/tactics.md).
 +🤖 A procedure for constructing the decision tree that the [cost function](optimization_framework.md) evaluates, using the terms in the [Privacy liability terms](cost_function_concrete.md) chapter. The input is the current wallet state. The output is a tree whose edges are actions and whose nodes are successor wallet states.
-+
+ 
+-Other chapters link to this section:
 +## 🤖 Inputs and output {#inputs-and-output}
 +
 +The wallet state contains the spendable UTXO set, inflight transactions, current protocol observations and beliefs, policy parameters, and an ordered queue $Q=(q_1,\ldots,q_n)$ of pending actions. An entry may be a PSBT fragment, a lone `TxOut` for an intended payment, or an arbitrary transaction fragment. This procedure calls every such entry an *intent* without assuming that it already defines a complete transaction.
@@ docs/tactics.md
… (truncated)
74: 8ae2f824a6 ! 74: d91137c1c2 [WIP] Describe what each privacy liability term is for
@@ docs/cost_function_concrete.md: status: draft
 +Randomization also promotes a robustly connected transaction graph, which the [counterfactual paths](cost_function_counterfactual_paths.md) term measures. See the [Randomized selection](cost_function_randomized_selection.md) chapter for the terms, and the [Order book size estimation](sybil_resistance_index.md) chapter for the lower bound on the number of candidates.
  
 -Both are summed over the transaction's inputs, through a monotone scaling function. They bias co-spending through market choices. See the [Randomized selection and Sybil resistance](cost_function_randomized_selection.md) chapter.
-+## 🤖 Sybil resistance
++## Sybil resistance
  
 -### 🤖 Sybil resistance {#sybil-resistance}
 +The Sybil resistance term evaluates the cost of an adversary supplying the coins in a coin's history and the candidates from which they were selected. Observed resource requirements and estimates derived from selection bias are assessed against the user's threat model. The liability is zero when the attack cost is judged prohibitive under that model; otherwise, it represents a subjective loss scaled by the user's privacy budget. See the [Sybil resistance](cost_function_sybil_resistance.md) chapter.
92: c7a5c9ca5a ! 75: 8cb7169d4a [WIP] Specify peer set reconciliation
@@ Commit message
     Co-authored-by: GPT-6 Astra <noreply@openai.com>
     Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
 
- ## docs/index.md ##
-@@ docs/index.md: okf_version: "0.2"
-   * [Block DAG](block-dag.md) - The validator blocks both tracks share, with their objects, nonce commitments and equivocation evidence, genesis, causal order and frontiers.
-   * [🤖 Optimistic track: blocks and phase states](optimistic-track.md) - Unanimity and phase closure on the optimistic track, phase by phase.
-   * [Recovery track](recovery-track.md) - How a stalled phase of the optimistic track turns into a recovery coalition formation proposal. Draft.
--* [🤖 Peer set reconciliation](set-reconciliation.md) - Pulling what a Merkle root commits to, naive reconciliation, unordered sets, and range and rateless reconciliation as optimizations.
-+* [🤖 Peer set reconciliation](set-reconciliation.md) - Requesting hash preimages, naive reconciliation, unordered sets, and range and rateless reconciliation as optimizations.
… (truncated)
95: 786eefe3ec ! 80: 478fb1df65 [WIP] Specify the recovery track
@@ docs/recovery-track.md
  
 -## Open questions
 +Under asynchrony and in the presence of (Byzantine) faults, due to the unanimity requirement the best consistency guarantee that can be made for the optimistic track is eventual consistency. No liveness guarantee is possible in the presence of faults for a particular run of the transaction construction protocol.
-+
+ 
… (truncated)
96: eae73a6fa0 ! 81: a6d9e142a5 [WIP] Specify the block DAG
@@ Commit message
 
     Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
 
+ ## .typos.toml ##
+@@
++[default.extend-identifiers]
++# Author of Asymmetric Distributed Trust.
++Cachin = "Cachin"
++
+ [default.extend-words]
+ # Groth16, the proof system named after Jens Groth.
+ Groth = "Groth"
+
  ## docs/block-dag.md ##
 @@
  ---
@@ docs/block-dag.md
  ---
  
 -# 🤖 Block DAG
-+<!-- cspell:words Alpos antichain Cachin consed Ehud Heidi Kleppmann Kogias Kokoris Malkhi Nayak Spiegelman Tackmann Zanolini Idit Keidar mathcal mathrm Naor Oded operatorname Ouri permissioned Pieter Poupko Wuille -->
++<!-- cspell:words Alpos antichain Cachin consed Ehud Heidi Kleppmann Kogias Kokoris Malkhi Nayak Spiegelman Tackmann Zanolini Idit Keidar mathcal mathrm Naor Oded operatorname Ouri permissioned Pieter Poupko Wuille Kogman Merklized Samourai unlinkable -->
  
 -This chapter is under review. Its draft is on [its branch](https://github.com/fungi-protocol/docs/blob/block-dag/docs/block-dag.md).
 +# Block DAG
  
--Other chapters link to this section:
+-Other chapters link to these sections:
 +🤖 Both tracks use the block DAG defined here.
 +
 +## Synchronizing protocol state
@@ docs/block-dag.md
 +
 +## 🤖 Optional attested validation and acknowledgement relay {#optional-attested-validation-and-acknowledgement-relay}
 +
… (truncated)
97: 2b8c84d848 ! 82: 2485849480 [WIP] Introduce transaction construction
@@ cspell/bitcoin-privacy.txt: taptree
  UTXO
  xpub
 +vbyte
++vbytes
 
  ## docs/transaction-construction.md ##
 @@
@@ docs/transaction-construction.md
 -This chapter is under review. Its draft is on [its branch](https://github.com/fungi-protocol/docs/blob/transaction-construction/docs/transaction-construction.md).
 +🤖 Transaction construction starts from an accepted coalition formation proposal and ends with a signed transaction. This chapter describes it in the abstract. Its sub-chapters define the [block DAG](block-dag.md) that the tracks share, and describe each track.
  
… (truncated)
89: dd81be7d24 ! 83: c1ae9df1ed [WIP] Specify the abstract transport interfaces
@@ docs/transport-interfaces.md
 +The protocol should make progress even if a channel delivers only one message at a time. In the asynchronous and partially synchronous models, the network adversary can already impose this.
  
  ## Kinds of messaging
-+
+ 
 +With some well-defined way to transmit messages from one peer to another, we can start to reason about how synchronization between peers can happen by using interactivity. Communication serves two purposes: peers exchange payment details directly with their counterparties, and send transaction contributions to the group as a whole.
 +
… (truncated)
79: ae24c1a125 ! 84: 934f3c5723 [WIP] Outline max flow based counterfactual path estimation
@@ docs/cost_function_counterfactual_paths.md
 @@
  ---
 -type: Stub
--title: Max flow based counterfactual path estimation
 +type: concept
-+title: Counterfactual paths
+ title: Counterfactual paths
  status: draft
 -stale_after: 2027-04-23T00:00:00Z
 +stale_after: 2026-11-05T00:00:00Z
  ---
  
--# 🤖 Max flow based counterfactual path estimation
-+# 🤖 Counterfactual paths
+ # 🤖 Counterfactual paths
… (truncated)
81: f410526ff3 ! 85: a71722105e [WIP] Outline subset sum density, subset sum ambiguity and the sibling output penalty
@@ docs/cost_function_subset_sum_ambiguity.md
 @@
  ---
 -type: Stub
--title: Own inputs or outputs subset sum ambiguity
 +type: concept
-+title: Subset sum ambiguity
+ title: Subset sum ambiguity
  status: draft
 -stale_after: 2027-04-23T00:00:00Z
 +stale_after: 2026-11-05T00:00:00Z
  ---
  
--# 🤖 Own inputs or outputs subset sum ambiguity
-+# 🤖 Subset sum ambiguity
+ # 🤖 Subset sum ambiguity
  
 -This chapter is under review. Its draft is on [its branch](https://github.com/fungi-protocol/docs/blob/subset-sum-ambiguity/docs/cost_function_subset_sum_ambiguity.md).
 +<!-- cspell:words sumsets binom quotienting -->
@@ docs/cost_function_subset_sum_ambiguity.md
 +- Is $\varepsilon$ absolute, or relative to the target? Does it include adjustments?
 +- After the fact, is a sum covered if either $\Sigma_{\le d}(X)$ or $\Sigma_{\le d}(Y)$ covers it, or are the two fractions separate?
… (truncated)
82: 89dfa42770 ! 86: cc90552b7a [WIP] Add the randomized selection and Sybil resistance chapters
@@ docs/cost_function_randomized_selection.md
 @@
  ---
 -type: Stub
--title: Randomized selection and Sybil resistance
 +type: concept
-+title: Randomized selection
+ title: Randomized selection
  status: draft
 -stale_after: 2027-04-23T00:00:00Z
 +stale_after: 2026-11-06T00:00:00Z
  ---
  
--# Randomized selection and Sybil resistance
-+# Randomized selection
-+
+ # Randomized selection
+ 
+-This chapter is under review. Its draft is on [its branch](https://github.com/fungi-protocol/docs/blob/randomized-selection/docs/cost_function_randomized_selection.md).
 +<!-- cspell:words msats rivalrous -->
-+
+ 
… (truncated)
84: bc18c81547 ! 87: 4e5eec71e2 [WIP] Group the privacy metrics after the privacy liability terms
@@ docs/cost_function_concrete.md: stale_after: 2026-11-06T00:00:00Z
  ## Randomized selection
  
 
- ## docs/index.md ##
-@@ docs/index.md: okf_version: "0.2"
- # Privacy Optimization Strategy
- 
- * [Optimization framework for Bitcoin wallets](optimization_framework.md) - Under review in #15.
--* [🤖 Pure Strategy Evaluation](pure_strategy_evaluation.md) - How the cost of a pure strategy is evaluated: the structure of the cost function, and its privacy liability terms.
-+* [🤖 Pure Strategy Evaluation](pure_strategy_evaluation.md) - How the cost of a pure strategy is evaluated: the structure of the cost function, its privacy liability terms, and the privacy metrics they take as input.
-   * [🤖 Cost function structure](cost_function_structure.md) - The structure shared by the family of cost functions that evaluate pure strategies: time dependence, linear combination of terms and bracketing.
-   * [🤖 Privacy liability terms](cost_function_concrete.md) - What each privacy liability term of the cost function is for: the risk it prices, what it encourages, and how it relates to the others.
-     * [Randomized selection and Sybil resistance](cost_function_randomized_selection.md) - Selection preferences that randomize which coins are co-spent, a Sybil resistance index measuring their effect, and a provenance term valuing coins by it.
… (truncated)
93: b1b1e23160 ! 88: dda51210ea [WIP] Distinguish lists from sets, not DAG from non-DAG
@@ docs/set-reconciliation.md
 -[Epidemic gossip](channels.md#dissemination-methods) disseminates data by pushing it: a peer that learns of a new message passes it on to its neighbors, and they pass it on in turn. Every peer eventually receives every message. Until then, a peer waits for messages to be pushed to it.
 +[Epidemic gossip](channels.md#dissemination-methods) disseminates data by pushing it: a peer that learns of a new message passes it on to its neighbors, and they pass it on in turn. Every peer eventually receives every message, assuming the required connectivity and delivery. A peer can also request missing messages by hash or reconcile its set with another peer's set, as described below.
  
- 🤖 Small messages are pushed eagerly to neighbors. A block is pushed as just its header, expecting the receiver to already know its Merkle tree.
+ Small messages are pushed eagerly to neighbors. A block is pushed as just its header, expecting the receiver to already know its Merkle tree.
  
 @@ docs/set-reconciliation.md: Reconciliation uses [peer to peer channels](transport-interfaces.md), independen
94: 8183885159 ! 89: f7080c72c8 [WIP] Specify the allocation registration validity proofs
@@ Commit message
 
     Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
 
+ ## cspell/bitcoin-privacy.txt ##
+@@ cspell/bitcoin-privacy.txt: taptree
+ unlinkability
+ UTXO
+ xpub
++vbyte
++vbytes
+
  ## docs/validity-proofs.md ##
 @@
  ---
@@ docs/validity-proofs.md
  stale_after: 2027-04-17T00:00:00Z
  ---
  
-+<!-- cspell:words arkworks blindings Bowe Camenisch Campanelli Goodell Holmgaard Kamp dedup Gabizon Groth Hohenberger Kohlweiss Lysyanskaya mathit mathrm mathsf Meyerovich Miers Noether RTAG ungated unlinkable -->
++<!-- cspell:words arkworks Falbesoner josibake Somsen blindings Bowe Camenisch Campanelli Goodell Holmgaard Kamp dedup Gabizon Groth Hohenberger Kohlweiss Lysyanskaya mathit mathrm mathsf Meyerovich Miers Noether RTAG ungated unlinkable -->
 +
  # 🤖 Validity proofs by allocation registration
  
 -This chapter is under review. Its draft is on [its branch](https://github.com/fungi-protocol/docs/blob/validity-proofs/docs/validity-proofs.md).
-+> 🤖 **Status: selected (2026-10-25).** Allocation registration was chosen
++> **Status: selected (2026-10-25).** Allocation registration was chosen
 +> because the payee doesn't learn the paying input, at the cost of a separate
… (truncated)
98: 950eca6f64 ! 90: 90917b642b [WIP] Specify the optimistic track
@@ Commit message
     Co-authored-by: GPT-6 Astra <noreply@openai.com>
     Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
 
+ ## cspell/bitcoin-privacy.txt ##
+@@ cspell/bitcoin-privacy.txt: taptree
+ unlinkability
+ UTXO
+ xpub
++vbyte
++vbytes
+
  ## docs/optimistic-track.md ##
… (truncated)
57: ae28f03f0e ! 92: c7b1c9d7e2 Move the concurrent PSBT spec into the book
@@ docs/psbt-concurrent.md: stale_after: 2027-04-15T00:00:00Z
 -This chapter is under review in [#16](https://github.com/fungi-protocol/docs/pull/16). Its draft is on [the pull request's branch](https://github.com/fungi-protocol/docs/blob/concurrent-psbt/psbt-concurrent.md).
 +## Abstract
  
--Other chapters link to this section:
+-Other chapters link to these sections:
 +New fields and rules for combining PSBTs in a distributed setting. This provides an alternative to the BIP 370 constructor role that is less sensitive to order of operations and therefore more amenable to concurrency, which reduces the coordination required for collaborative transaction construction.
 +
 +## Motivation
… (truncated)
73: 0f938de8c3 ! 96: 8b59e00bfc [WIP] Move the cost function's structure into its own chapter
@@ docs/cost_function_structure.md
  # 🤖 Cost function structure
  
 -This chapter is under review. Its draft is on [its branch](https://github.com/fungi-protocol/docs/blob/cost-function-abstract-rework/docs/cost_function_structure.md).
+-
+-Other chapters link to these sections:
 +The evaluation of pure strategies is a family of cost functions, sharing the structure set out in the [Optimization framework](optimization_framework.md#preliminaries) chapter: a linear combination of terms, each labelled as privacy related or not, and each a piecewise linear function of time. This chapter describes that structure: how terms depend on time, how they are combined into a single amount in satoshis, and how incomplete information is handled by bracketing. The chapters that follow define the concrete terms.
-+
-+## Time dependence
-+
+ 
+ ## Time dependence
+ 
 +Every term of the cost function and every intent in the queue may depend on time, and how it does may depend on what is being evaluated. This time dependence is modeled as piecewise linear offsets to values computed independently of time, so the cost function returns a family of piecewise linear functions of time, one per term. Evaluating them at a given time is just a matter of indexing them and taking a sum, but treating them explicitly as piecewise linear functions makes it possible to solve for intercepts.
 +
-+## Linear combination
-+
+ ## Linear combination
+ 
… (truncated)
78: 380b9bd4f6 ! 97: bae6dfd3ed [WIP] Link the Tactics and Privacy liability terms chapters
@@ Commit message
 
     Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
 
- ## docs/index.md ##
-@@ docs/index.md: okf_version: "0.2"
- * [Abstract transport interfaces](transport-interfaces.md) - Send, receive and bidirectional channels, the kinds of messaging the protocol needs, and broadcast built from peer to peer channels.
- * [🤖 Peer and broadcast channels](channels.md) - Broadcast to a group or to the world, built by gossip over peer to peer channels.
- * [Contacts and payment messaging](contacts.md) - What interactive payments need from peer to peer messaging between payer and payee.
--* [Market-based coalition formation](coalition_formation.md) - Under review in #18.
-+* [Market-based coalition formation](coalition_formation.md) - Bilateral negotiation and aggregation of co-spend proposals into a unanimously accepted coalition formation proposal.
… (truncated)
71: 3746f2e362 ! 98: 6a66aa533b Add an overview
@@ docs/overview.md
 +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.
  
… (truncated)
99: e6b5b0b793 ! 106: 0f0e4e3754 [WIP] Move the BIP 322 gossip rules to peer to world broadcast
@@ Commit message
     Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
 
  ## docs/coalition_formation.md ##
-@@ docs/coalition_formation.md: The primary purpose of this protocol is to construct an [imputation](https://en.
- 
- ### Hedonic games and games with transferable utility
- 
-+Coalition formation games, in game theory, typically refer to the cooperative game theory setting, where agreements are binding and can be enforced by some kind of mechanism. While Bitcoin can provide such a construct, analogously to the function of the court system, the current consensus rules require some kind of contract to be anchored in a confirmed transaction, i.e. binding agreements require creating new transactions and waiting for them to confirm.[^coinswap] In order to build transactions without having already built transactions, we must therefore assume the non-cooperative setting. Coalition formation in the non-cooperative setting can only rely on incentives.
-+
… (truncated)

A 🤖 covers everything under it, so a mark inside a marked chapter,
section or list item is redundant, and suggests that only the inner part
is LLM output. contrib/robot_marks.py reads each page as a tree of
sections, paragraphs and list items. check lists the redundant marks,
and the chapters whose title and index entry disagree, and the
robot-marks flake check runs it on docs/. fix removes the redundant
marks. merge marks a chapter, section or list item in place of its
children once they are all covered. relegate moves a mark onto the
children, for when part of a marked scope is rewritten.

The property tests generate pages from a tree of blocks, and check that
the pages are read as that tree, that fix keeps what is covered, that
fix and merge give the same marks in either order, and that merge undoes
relegate. Hypothesis comes from nixpkgs.

The stub titles of five chapters were marked where their index entries
are not; their chapters are not marked.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@bc1cindy
bc1cindy requested a review from oakagent November 10, 2026 03:00
Comment thread contrib/jupyter_nb.py
target = posixpath.normpath(posixpath.join(here, m.group(2) + ".ipynb"))
return m.group(1) + m.group(2) + ".md" if target in notebooks else m.group(0)

chapter["content"] = NOTEBOOK_LINK.sub(fix, chapter.get("content", ""))

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Link rewrite corrupts code blocks

link_notebooks applies the .ipynb regex to the whole chapter, so a notebook link shown in a fenced code block is rewritten from .ipynb to .md, changing verbatim code.

oak · automated · dbe0d25

Comment thread docs/psbt-concurrent.md

This can provides additional integrity to a collaborative transaction construction protocol, since [`SIGHASH_ALL`](#divergence-and-sighash-flags) signatures must agree on the ordering.

In applications where this is desirable, the *Creator* should only set `PSBT_GLOBAL_SORT_DETERMINISTIC` to `0x01`, and leave `PSBT_GLOBAL_SORT_SEED` unset. Each replica will locally provide a value for `PSBT_GLOBAL_SORT_SEED` just in time, as a commitment to protocol transcript (e.g. the root hash of a Merkle set of protocol messages).

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 requirement contradicts flag

Line 153 tells the Creator to set PSBT_GLOBAL_SORT_DETERMINISTIC to 0x01 and leave PSBT_GLOBAL_SORT_SEED unset, but line 139 requires the seed whenever that flag is 0x01.

oak · automated · dbe0d25

nothingmuch and others added 11 commits November 10, 2026 19:10
Improve the introduction, define sub-transaction balance, clarify wallet
fingerprint distributions, social graph partitioning and related payments in
CoinJoins, and fix typos.

Use "topological" rather than "structural" for features of the graph shape, to
avoid confusion with features related to transaction structure.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Build broadcast to a group or to the world by gossip over peer to peer
channels: broadcast domains, neighbor and submission channels, the
announce, pull and push messages, anonymous submission,
synchronization of the session's message set, dissemination methods and
topology.

Developed from the peer-messages notes (onwloqro, 1f68a962).

Links to the optimistic track and set reconciliation chapters resolve
once those follow in this series.

It replaces the chapter's review stub. Links to other chapters
resolve against their stubs until those land.

Co-authored-by: GPT-6.1 Sol <noreply@openai.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
It introduces the two chapters that evaluate a pure strategy: the
structure of the cost function, and its privacy liability terms. It
replaces the chapter's review stub.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The chapter replaces its stub in docs/, with frontmatter, and leaves
In Review for the top level of the index, before its first part, like
the introduction. The README links to it by its docs/ path, which
book.py rewrites for the book.

Co-authored-by: bc1cindy <bc1cindy@proton.me>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Add a table of candidate transports: the BIP 77 mailbox, a specialized
OHTTP pubsub service, nostr with gift wrapping, Tor and Nym. It compares
delivery, broadcast domain, sender anonymity and topology, and states
that the specification relies only on the channel properties.

Name the gossip topologies after the literature, as described in
Weaver's dissertation: the random phone call model, one random neighbor
per round, and the LOCAL model, all neighbors per round with bounded
degree. Transports that are connectionless end to end match the former;
connection oriented ones scale well only in the latter.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Builds the decision tree from the leaves: partitions of the pending
action queue, coin selection within each, change construction, order
book coins, action sequences, and bracketing. It replaces the
chapter's review stub.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: bc1cindy <bc1cindy@proton.me>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: Armin Sabouri <me@arminsabouri.com>
nothingmuch and others added 25 commits November 10, 2026 19:10
The sumsets draw k values from the denominations and 0, so they hold the
sums of every combination of size at most k. Count those combinations
the same way, (n+k choose k) less the empty combination, which makes the
two curves agree at k=1.

The counted combinations are not limited by their sum, so title the
chart by the denominations they are drawn from and attach the range to
the distinct sums and integers instead.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The quantile levels are i/20, so the median is i == 10. Skipping i == 5
dropped the first quartile and drew dots under the median markers.
Name the number of quantile levels and derive the median's index and
the legend's percentile step from it, so they cannot disagree again.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Say which property permutations of equal values preserve and why
permutations within a sub-transaction yield no new mappings, name the
fee rates whose variance makes k:1 exchanges asymmetric, and use m for multiplicity so that k only
ever means combination size.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Describe why dense instances leave sub-transaction mappings
underdetermined without suggesting a brute force enumeration: density
survives setting any one sub-transaction aside, so it holds for the
rest of the transaction too. Open the Radix CoinJoin section by
drawing that conclusion explicitly.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The book is assembled from docs/ by contrib/book.py, which only took
markdown pages as chapters. Take Jupyter notebooks too. A notebook's
frontmatter is a raw cell that opens it, holding what a markdown page's
frontmatter would. It is checked, and dropped from the notebook the book
is given, as a markdown page's is. Jupyter's autosaves under
.ipynb_checkpoints/ are neither chapters nor copied.

List the radix CoinJoin notebook in the index, under a new Drafts part,
in place of the SUMMARY.md entry it had before the book was assembled
from docs/.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
mdbook rewrites links to `.md` chapters into links to their `.html`
pages, and into in-page anchors on the print page, but leaves links to
`.ipynb` chapters as they are, so they lead to the raw notebook, which
isn't part of the built site.

After rendering the notebooks, the preprocessor points every relative
link that resolves to a notebook chapter at the chapter's `.md` path,
so mdbook rewrites it like any other chapter link. Links to other
`.ipynb` files, and absolute ones, are left alone.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
mdbook lists separators as the bare string "Separator" and part titles
as {"PartTitle": ...}, and the jupyter preprocessor called .get on every
item, so a book with a separator stopped the build. It now only
descends into chapters.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
mdbook loads additional-js on print.html as well, so the printed book
kept only the first page of each table and showed dead page buttons.

Showing every row widens the table past the page, because the later
rows hold the longest values, so print also tightens font and padding.
The global text colour is a mid grey chosen to read on the page, but
these labels sit on the bars, where grey has almost no contrast. They
go back to black, as they were before the plot style was added.
With a transparent figure the darkest plasma fills sit directly on the
page, and on the dark themes they nearly vanish into it. A grey outline
per series keeps each silhouette visible on either theme.
The plot style turns legend frames off and makes their labels grey.
Over the dust band of this plot that left the labels unreadable on
dark pages, so this legend gets back its white frame and black labels.
With the notebook's own parameters the k=6 sumset still has gaps larger
than the dust threshold, including below max_denom, so describe how
coverage varies across the range instead.

Suggested-by: bc1cindy <bc1cindy@proton.me>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
powers() dropped every power below min_denom before multiples() scaled
them, so the multiples of those powers that do reach min_denom were
missing: 2 × 3^5 = 486 and 5 × 10^2 = 500. multiples() already keeps
only the values in the denomination range, so powers() now starts at
the zeroth power.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The quantiles of the k=6 sumset start with several that are entirely
gaps of size 1, but the plot omits gaps of size 1 (min_diff = 2), so
its quantiles plateau at 2 and then at 3. The text described the
sumset as if it were the plot.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A sum above c times max_denom does not need c copies of the largest
denomination: 100000000 + 86093442 + 20000000 exceeds the cutoff at
c = 2 with one. Since no term exceeds max_denom, it needs more than c
terms, which is what leaves it fewer free terms.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The paragraph defines the implied fee rate as the nominal input sum
minus the output sum, over the weight. A k:1 exchange keeps the nominal
sums, so the difference it makes is to the weight, and therefore to the
implied fee rate.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A sub-transaction that uses every copy of a denomination leaves the
remaining coins without it, and they may no longer be dense. The
argument holds when the multiplicities are high enough that no single
sub-transaction does that.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Tag the parameter cells and the cells that build the binary, ternary and
decimal sets and their union with show-input, so the rendered chapter
gives the code that generates the denominations. The plotting, sumset
and gap cells stay hidden.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Tag the cells that compute the sumsets, the gaps and the relative gaps
with show-input. The plotting cells stay hidden.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The gap code shown in the chapter filters by min_diff and
min_diff_ratio, so tag the cell that sets them with show-input.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The draft is published from its own repository,
fungi-protocol/docs-draft, so that nothing has to be merged into main
for it to go live. Its Pages site is served from /docs-draft/, not
/docs/. Point the 404 page's base and the link check at that path.

The Pages workflow is unchanged: it deploys on a push to that
repository's main, which is this commit.

This commit belongs on draft only. It never goes to main.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@github-actions

Copy link
Copy Markdown
range-diff for force push dbe0d25372 → f2806d95f0 November 10, 2026 22:29 UTC: 13 modified, 94 unchanged, 1 added

reproduce: git range-diff cbb5404..dbe0d25 cbb5404..f2806d9

  1:  e8823d9851 =   1:  e8823d9851 Concurrent PSBT spec
  2:  2fe2e8f9f4 =   2:  2fe2e8f9f4 Render math before mdbook-graphviz re-serializes the markdown
  3:  8dd55aaff4 =   3:  8dd55aaff4 Nest indented index entries as sub-chapters
  4:  01217000e0 !   4:  2fc9478220 Arrange the index into the parts proposed in #19
  -:  ---------- >   5:  0e2cf050dc Check for redundant 🤖 marks, and move them up or down a level
 24:  3bccc89af9 !   6:  a32eb7a192 Define the on-chain privacy problems being addressed
 26:  3703714fb2 =   7:  4914ce7c2f Edits to Collaborative Transaction Privacy (#30)
 28:  1e6321cb44 =   8:  d3f8ddd526 Revise and clarify following editorial pass
 30:  8971acf3e5 =   9:  806b091863 [WIP] Specify peer and broadcast channels
 35:  512c0ed394 =  10:  3bd6942ccb [WIP] Add the Pure Strategy Evaluation chapter
 31:  46c4dd630c =  11:  6b2b5ec066 Move the problem definition into the mdbook
 33:  a6c7251338 =  12:  e436c7e9b0 [WIP] Compare candidate transports for the channels
 38:  befaec25b0 =  13:  7495d31418 [WIP] Add the Bottom-up construction chapter
  5:  3c2976fa71 =  14:  44eb9fc537 Radix coinjoin denominations notebook
 43:  390ea1246f =  15:  d06490455c README do-over
 44:  e72354730d =  16:  ed36e7343b Abstract cost function
 45:  80985c2621 =  17:  8bc90e5471 [WIP] ████████████████████ Clarify abstract cost function
 46:  c9e91e42b9 =  18:  a1b42076e2 fixup! Abstract cost function
 47:  cc18450cdc =  19:  3dc08de944 [WIP] ████████████████████ Record decision tree construction notes
 48:  ad3f201e4a =  20:  b4232a77df [WIP] ████████████████░░░░ Describe how the decision tree is built
 49:  ad8a00313b =  21:  6245e2e57f fixup! [WIP] ████████████████████ Clarify abstract cost function
 50:  806e78a4f8 =  22:  0b38c93626 fixup! Abstract cost function
 51:  ea828dd167 =  23:  c5b36e8fc5 fixup! Abstract cost function
 52:  4029c1f384 =  24:  fa2163b232 fixup! Abstract cost function
 53:  30a31f15ef =  25:  ca9aa5a0a3 fixup! Abstract cost function
 54:  edb7c0f229 =  26:  8951f31175 [WIP] Order inputs before outputs within a batch
 55:  5fb552f0ec =  27:  031c5258cd [WIP] Model time dependence as piecewise linear offsets
 56:  63f9548074 =  28:  7f83e280a6 [WIP] Say what each end of the bracket means
 57:  0c02c686d6 =  29:  2c7b07e4fc [WIP] Distinguish the pure and mixed strategies
 58:  b033c44353 =  30:  762baeb074 [WIP] Describe commitment in multiparty protocols
 59:  c8862c7061 =  31:  57b151edb9 [WIP] Rewrite the global privacy budget
 60:  c16aaf5547 =  32:  b37c1e2aa4 [WIP] ████████████████░░░░ Penalize co-spend proposals that leak a counterfactual path
 61:  d10c6c06de =  33:  43fc75bbb2 fixup! [WIP] ████████████████░░░░ Describe how the decision tree is built
 62:  8c9b0d82fb =  34:  60911023b3 fixup! [WIP] Say what each end of the bracket means
 63:  3d7329bf6d =  35:  df00c8ceb1 [WIP] ████████████████████ Describe the greedy decision loop
 64:  a31cfc82f6 =  36:  de99d8e884 [WIP] ████████████████████ Give the decision loop its own heading
 68:  14f70a784b =  37:  81d71429ef [WIP] ██████████████████░░ Move tree construction to the strategy chapter
 72:  bd2a789516 =  38:  68f91dcef7 [WIP] ████████████████░░░░ Rename the chapter to Optimization framework
 78:  82655b3841 =  39:  5ef94da4f9 [WIP] ████████████████████ Introduce the strategy as generating and evaluating decisions
 65:  96a1cdb35e =  40:  39af227008 Coalition formation
 93:  e3e7a4a3f4 =  41:  3588019cd2 [WIP] ████████████████░░░░ Move the mixed strategy into its own chapter
 69:  47d02eeffd =  42:  673acd41b5 [WIP] ████████████████░░░░ Add input value constraints to proposal conditions
 94:  0979865daa =  43:  3a256fc142 [WIP] ████████████████░░░░ Mark agent-generated text with 🤖
 66:  5104bedc29 =  44:  da19c8833e [WIP] Add the Tactics chapter
 73:  c35c9ecb4b =  45:  bfdbe9443a [WIP] Replace coalition formation text superseded by the protocol chapters
 95:  e075273c68 =  46:  a33c480a64 [WIP] Call the greedy loop a decision loop run as a greedy search
 70:  bd50030469 =  47:  fb6cefa357 [WIP] Add the Privacy liability terms chapter
 79:  cdbbae24c4 =  48:  b4c800617e [WIP] Move the coalition formation games text from the overview
 96:  8b59e00bfc =  49:  e399dbd13b [WIP] Move the cost function's structure into its own chapter
 74:  d91137c1c2 =  50:  be997bf4b4 [WIP] Describe what each privacy liability term is for
 75:  8cb7169d4a =  51:  ef6fc2ee0b [WIP] Specify peer set reconciliation
 34:  934939d950 =  52:  a7795bdebe Refer to the Radix CoinJoin Denominations chapter
 99:  16cb126130 =  53:  fd03d67a24 First round edits of Overview
 97:  bae6dfd3ed =  54:  b8605902f3 [WIP] Link the Tactics and Privacy liability terms chapters
 84:  934f3c5723 =  55:  f46d6d0e2e [WIP] Outline max flow based counterfactual path estimation
 37:  ea80b60e13 =  56:  6ca1fb32e4 [WIP] Outline the consolidation penalty
 85:  a71722105e =  57:  8e3f6d6393 [WIP] Outline subset sum density, subset sum ambiguity and the sibling output penalty
 86:  cc90552b7a =  58:  012811c806 [WIP] Add the randomized selection and Sybil resistance chapters
 87:  4e5eec71e2 =  59:  b88f260731 [WIP] Group the privacy metrics after the privacy liability terms
 88:  dda51210ea =  60:  00645b51d4 [WIP] Distinguish lists from sets, not DAG from non-DAG
 39:  43a5439f09 =  61:  5f724e0564 [WIP] Specify the protocol messages
 89:  f7080c72c8 =  62:  1b4f8d4ae9 [WIP] Specify the allocation registration validity proofs
 90:  90917b642b =  63:  38b2f64c74 [WIP] Specify the optimistic track
 41:  95aca97bcb =  64:  87a4be3005 [WIP] Move the BIP 322 gossip rules into peer to world broadcast
 42:  2c11278670 =  65:  e6c6624fb9 Cite Gavenda et al. in the sub-transaction mapping section
106:  0f0e4e3754 =  66:  cee91ea5d3 [WIP] Move the BIP 322 gossip rules to peer to world broadcast
 98:  6a66aa533b !  67:  ba1124ae5f Add an overview
104:  f53bb94928 !  68:  b104bd3e2d First round edits of Overview
 77:  09c0e6a269 =  69:  fb3db213e1 Fix typos and a broken anchor in the concurrent PSBT spec
105:  405921f46c =  70:  26d6afb634 [WIP] Point the overview at the channel interfaces and asymmetric trust
 92:  c7b1c9d7e2 =  71:  20cb1c4ee8 Move the concurrent PSBT spec into the book
 81:  a6d9e142a5 !  72:  4629dff77c [WIP] Specify the block DAG
 82:  2485849480 !  73:  f7b422e9a1 [WIP] Introduce transaction construction
101:  a19176263d =  74:  39d7bfd8b4 First round edits of Overview
102:  b4e9e2b6d5 =  75:  c92783b68a First round edits of Overview
 80:  478fb1df65 !  76:  fd7103ff35 [WIP] Specify the recovery track
 83:  c1ae9df1ed !  77:  96abee7009 [WIP] Specify the abstract transport interfaces
100:  baa4bc3c84 =  78:  fae28be992 First round edits of Overview
 40:  22be9dc41c !  79:  98f99554c7 [WIP] Specify contacts and payment messaging
103:  4131b8c13a =  80:  190ffcbf2d First round edits of Overview
  6:  18e6a34368 !  81:  8fcfb38142 add a notebook derivation and a devshell for editing the notebook
  7:  3e6af68406 =  82:  dc53ca5fe3 re-render notebook outputs with the notebook derivation
  8:  1d5c95986d =  83:  5f149f2267 count combinations with replacement as multisets
  9:  4e31859369 =  84:  7a9136d67e clarify the notebook introduction
 10:  1e48ab2a74 =  85:  7433a91a97 count combinations of up to k denominations, as the sumsets do
 11:  b92dd12461 =  86:  45c9c6ac45 skip the median, not the 25th percentile, among the quantile dots
 12:  71f872f3db =  87:  a910b4b480 clarify the sub-transaction counting argument
 13:  d0f701b2d3 =  88:  46fcaea412 explain why sums are cut off above a multiple of max_denom
 14:  e2e04bc2cb =  89:  9d4f58c1b5 explain subset sum density as an invariant of the mapping
 15:  f083d06355 =  90:  2b37b92b19 render jupyter notebook chapters as mdbook pages: hide code, paginate tables
 16:  7b97cf6a78 !  91:  b1c2bfb928 assemble notebook chapters from docs/
 17:  96d6a3d029 =  92:  cc4f78c82f style plots: theme-neutral, colorblind-safe, re-rendered outputs
 18:  21839237c6 =  93:  144998930c point links to notebook chapters at their rendered pages
 19:  fda57dffdb !  94:  3efd9584e5 Skip separators and part titles when walking the book's chapters
 20:  21c056bdf5 =  95:  1f6e961dc8 nb-table: print every row of paginated tables
 21:  6ff83f0b7a =  96:  e2cbe3af80 keep bar value labels black over the bar fills
 22:  207f2f8a9e =  97:  4b270f8457 outline density series to read on dark pages
 23:  f7dfe4e094 =  98:  67053a4e34 restore the density plot's legend frame
 25:  40e42443d9 =  99:  81d59e8bac stop claiming six outputs close every gap above dust
 27:  52769f7f5a = 100:  164b73b671 Keep the powers below the dust threshold until they are multiplied
 29:  e582b564df = 101:  ecfa43d86a Say that the gap plot's k=6 quantiles start at 2, not 1
 32:  6580268846 = 102:  82d0b2ccde Bound the terms of a sum above the cutoff by its size alone
 36:  7385b65b40 = 103:  b2fe5d1321 Say that a k:1 exchange changes the weight, not the fee
 67:  9698ef7eb4 = 104:  a57f68148c Qualify the density argument by the denominations that remain
 71:  b18bfa10de = 105:  f79f96847c Show the denomination generating code in the book
 76:  2277e026fe = 106:  e9316202e9 Show the sumset and gap computation code in the book
 91:  a0948d4228 = 107:  04ddc82085 Show the analysis parameters in the book
107:  dbe0d25372 ! 108:  f2806d95f0 [WIP] Serve the draft from /docs-draft/
4: 01217000e0 ! 4: 2fc9478220 Arrange the index into the parts proposed in #19
@@ docs/index.md
 +
 +# Protocol Suite
 +
-+* [Overview](overview.md) - Collaborative transaction construction, privacy, fault tolerance and coalition formation.
++* [Overview](overview.md) - Collaborative transaction construction, privacy, fault tolerance, and coalition formation.
 +* [Abstract transport interfaces](transport-interfaces.md) - Send, receive and bidirectional channels, the kinds of messaging the protocol needs, and broadcast built from peer to peer channels.
 +* [🤖 Peer and broadcast channels](channels.md) - Broadcast to a group or to the world, built by gossip over peer to peer channels.
 +* [Contacts and payment messaging](contacts.md) - What interactive payments need from peer to peer messaging between payer and payee.
24: 3bccc89af9 ! 6: a32eb7a192 Define the on-chain privacy problems being addressed
@@ cspell/tooling.txt
 +ambs
 +atmd
  cacheprovider
+ capsys
  DejaVu
- devshell
+@@ cspell/tooling.txt: devshell
  DNSSEC
  dontInstall
  dylanowen
98: 6a66aa533b ! 67: ba1124ae5f Add an overview
@@ docs/overview.md
 +
 +## 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 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.
++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 to 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.
 +
104: f53bb94928 ! 68: b104bd3e2d First round edits of Overview
@@ docs/overview.md: As a result, liveness is inherently brittle. Consistency is a
  
  ## 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 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.
-+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 be 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 to 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 be merged according to 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.
 +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.
81: a6d9e142a5 ! 72: 4629dff77c [WIP] Specify the block DAG
@@ docs/block-dag.md
  stale_after: 2027-04-23T00:00:00Z
  ---
  
--# 🤖 Block DAG
 +<!-- cspell:words Alpos antichain Cachin consed Ehud Heidi Kleppmann Kogias Kokoris Malkhi Nayak Spiegelman Tackmann Zanolini Idit Keidar mathcal mathrm Naor Oded operatorname Ouri permissioned Pieter Poupko Wuille Kogman Merklized Samourai unlinkable -->
++
+ # Block DAG
  
 -This chapter is under review. Its draft is on [its branch](https://github.com/fungi-protocol/docs/blob/block-dag/docs/block-dag.md).
-+# Block DAG
- 
--Other chapters link to these sections:
 +🤖 Both tracks use the block DAG defined here.
 +
 +## Synchronizing protocol state
@@ docs/block-dag.md
 +3. The next TEE-backed block references the preceding TEE-backed block and the other validators' acknowledgements, relaying them and supplying the evidence for the next acknowledgements.
 +
 +The validator relays acknowledgements rather than signing on behalf of their authors. Support still counts the distinct validators whose acknowledgements are represented. Peers can independently validate the same DAG, and multiple validators may provide attestations; the profile does not create a privileged protocol leader.
-+
+ 
+-Other chapters link to these sections:
 +The attestation can certify validation and satisfaction of the applicable agreement predicate. It does not authorize a change to that predicate: unanimous phases still require all required acknowledgements, and transaction signing still requires the input owners. Private allocation information and spending keys are not supplied to the TEE. Peers retain local checks needed to bind their own contributions, proofs and signatures to the intended instance and privacy context. The optional trust assumption reduces validation work and can support stronger liveness under the selected recovery policy.
  
  ## Nonce commitments and compact equivocation evidence
82: 2485849480 ! 73: f7b422e9a1 [WIP] Introduce transaction construction
@@ docs/transaction-construction.md
  stale_after: 2027-04-23T00:00:00Z
  ---
  
--# 🤖 Transaction construction
-+# Transaction construction
+ # Transaction construction
  
 -This chapter is under review. Its draft is on [its branch](https://github.com/fungi-protocol/docs/blob/transaction-construction/docs/transaction-construction.md).
 +🤖 Transaction construction starts from an accepted coalition formation proposal and ends with a signed transaction. This chapter describes it in the abstract. Its sub-chapters define the [block DAG](block-dag.md) that the tracks share, and describe each track.
80: 478fb1df65 ! 76: fd7103ff35 [WIP] Specify the recovery track
@@ docs/recovery-track.md
  stale_after: 2026-11-06T00:00:00Z
  ---
  
--# 🤖 Recovery track
 +<!-- cspell:words Dwork Lynch Stockmeyer APSA APSA's Baudet Brugeres CRBB Chondros Christos Croman Danezis Deligios Diamantopoulos Dolev Duan Ehud Eurocrypt Falbesoner Garay Guerraoui Haibin Haifeng Idit Ittai josibake Keidar Kelkar Kichidis Klasovita Kuznetsov Languille Mahimna Maneas mathit Maxence Mema Minghang Naor Nikos Oded Ouri Patsonakis permissioned Pieter Poupko Rachid Reiter Roussopoulos Ruomu Sisi Skoumios Somsen Sonnino Stathis Tasos texttt Tonkikh Vassilis Wonseok Wuille Yuval Zarfaoui Zhuolun Zikas antichain counterpropose mathcal mathrm operatorname paxpay precommitted semilattice -->
++
+ # Recovery track
  
 -This chapter is under review. Its draft is on [its branch](https://github.com/fungi-protocol/docs/blob/recovery-track/docs/recovery-track.md).
-+# Recovery track
++🤖 A stalled phase can produce recovery observations in validator blocks, each signed by its validator and committing to what that validator is missing. Any participant can turn those observations into a recovery coalition formation proposal that anyone can check. The intended synchrony properties are exclusion of a faulty party without excluding an honest one, apart from the [counterparty-stall exception](#counterparty-stalls). Claims below that depend on identifying missing first- or second-round acknowledgements remain unresolved under the two-round finalization rule.
++
++🤖 This chapter describes the recovery track ($t \lt n$). The block structure and the per-track nonce commitments are described in the [block DAG](block-dag.md) chapter. The closing of each phase is described in the [optimistic track](optimistic-track.md#phase-closure) chapter ($t = n$). Dissemination and set reconciliation are out of scope here.
  
 -Other chapters link to these sections:
-+🤖 A stalled phase can produce recovery observations in validator blocks, each signed by its validator and committing to what that validator is missing. Any participant can turn those observations into a recovery coalition formation proposal that anyone can check. The intended synchrony properties are exclusion of a faulty party without excluding an honest one, apart from the [counterparty-stall exception](#counterparty-stalls). Claims below that depend on identifying missing first- or second-round acknowledgements remain unresolved under the two-round finalization rule.
++🤖 Several names in this chapter and in [phase closure](optimistic-track.md#phase-closure) are placeholders, chosen only so the rules can be stated: *per-input message*, *quorum mode*, *own-view mode*, *deny list*, *late pass*, *coin binding*, *evidence-only proposal*, *boundary split* and *light participant*. A light participant is one that does not see the DAG.
  
 -## Recovery overlay
-+🤖 This chapter describes the recovery track ($t \lt n$). The block structure and the per-track nonce commitments are described in the [block DAG](block-dag.md) chapter. The closing of each phase is described in the [optimistic track](optimistic-track.md#phase-closure) chapter ($t = n$). Dissemination and set reconciliation are out of scope here.
++## Fault tolerance via branched execution
  
 -## Evidence that excludes at once
-+🤖 Several names in this chapter and in [phase closure](optimistic-track.md#phase-closure) are placeholders, chosen only so the rules can be stated: *per-input message*, *quorum mode*, *own-view mode*, *deny list*, *late pass*, *coin binding*, *evidence-only proposal*, *boundary split* and *light participant*. A light participant is one that does not see the DAG.
++Somewhat surprisingly, the optimistic track and the recovery track can both proceed more or less independently.
  
 -## Recovery track blocks
-+## Fault tolerance via branched execution
++Under asynchrony and in the presence of (Byzantine) faults, due to the unanimity requirement the best consistency guarantee that can be made for the optimistic track is eventual consistency. No liveness guarantee is possible in the presence of faults for a particular run of the transaction construction protocol.
  
 -## Recovery proposal
-+Somewhat surprisingly, the optimistic track and the recovery track can both proceed more or less independently.
++Recall that when multiple transactions attempt to spend some of the same coins, it is up to miners to determine which one (if any) will be confirmed in a block. Miners are assumed to follow their incentives, maximizing fee revenues. Even if transaction replacement wasn't useful or desirable, there is no mechanism that can enforce that unspent outputs are exclusively bound to one transaction construction session over another without *global* consensus.
  
 -## Open questions
-+Under asynchrony and in the presence of (Byzantine) faults, due to the unanimity requirement the best consistency guarantee that can be made for the optimistic track is eventual consistency. No liveness guarantee is possible in the presence of faults for a particular run of the transaction construction protocol.
++As we have seen, the success path always reaches termination, and can only reach it by observing unanimous agreement, and when that is possible progress requires only eventual consistency. Validity proofs reduce Byzantine faults to omission faults, so recovering liveness in the presence of failure requires partial synchrony assumptions at the very least.
  
 -## Fault tolerance via branched execution
-+Recall that when multiple transactions attempt to spend some of the same coins, it is up to miners to determine which one (if any) will be confirmed in a block. Miners are assumed to follow their incentives, maximizing fee revenues. Even if transaction replacement wasn't useful or desirable, there is no mechanism that can enforce that unspent outputs are exclusively bound to one transaction construction session over another without *global* consensus.
-+
-+As we have seen, the success path always reaches termination, and can only reach it by observing unanimous agreement, and when that is possible progress requires only eventual consistency. Validity proofs reduce Byzantine faults to omission faults, so recovering liveness in the presence of failure requires partial synchrony assumptions at the very least.
-+
 +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. 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.
83: c1ae9df1ed ! 77: 96abee7009 [WIP] Specify the abstract transport interfaces
@@ docs/transport-interfaces.md
  stale_after: 2027-04-22T00:00:00Z
  ---
  
--# 🤖 Abstract transport interfaces
 +<!-- cspell:words unlinkable -->
++
+ # Abstract transport interfaces
  
 -This chapter is under review. Its draft is on [its branch](https://github.com/fungi-protocol/docs/blob/transport-interfaces/docs/transport-interfaces.md).
-+# Abstract transport interfaces
- 
--Other chapters link to these sections:
 +🤖 These interfaces give the protocol an abstract syntax for messages. Every part of the protocol is described in terms of messages: who sends them, who receives them, and what a message reveals about its sender. How a message travels is up to the transport.
 +
 +🤖 Delivering messages is the transport's job. Its non-malicious delivery faults and delays constrain the timing model the layers above can assume. Agreeing on what was delivered belongs to those layers. Protocol timeouts need not match transport timeouts; see the [communication models](recovery-track.md#fault-tolerance-under-different-communication-models). Wire encodings are out of scope.
 +
 +## 🤖 Channels {#channels}
-+
+ 
+-Other chapters link to these sections:
 +* A **send channel** accepts messages, one per send.
 +* A **receive channel** yields messages, one at a time.
 +* A **bidirectional channel** is both. Its two directions may carry different message types.
40: 22be9dc41c ! 79: 98f99554c7 [WIP] Specify contacts and payment messaging
@@ docs/contacts.md
  stale_after: 2027-04-15T00:00:00Z
  ---
  
--# 🤖 Contacts and payment messaging
-+# Contacts and payment messaging
+ # Contacts and payment messaging
  
 -This chapter is under review. Its draft is on [its branch](https://github.com/fungi-protocol/docs/blob/contacts/docs/contacts.md).
 +🤖 Interactive payments need the payer and the payee to message each other. This chapter states what the protocol requires of that messaging. How an application manages contacts, identities and devices, and how it obtains a suitable channel, is up to the application. The protocol only uses the channel it is given, so it need not implement an identity system.
6: 18e6a34368 ! 81: 8fcfb38142 add a notebook derivation and a devshell for editing the notebook
@@ .gitignore
 @@
  book/
  result
+ .hypothesis/
 +.ipynb_checkpoints/
 
  ## cspell/tooling.txt ##
16: 7b97cf6a78 ! 91: b1c2bfb928 assemble notebook chapters from docs/
@@ contrib/book.py: def strip_frontmatter(text):
 +    """A notebook's frontmatter, as a markdown page would have it, if a
 +    raw cell holding nothing else opens it, and the notebook without it."""
 +    nb = json.loads(text)
-+    cells = nb.get("cells", [])
++    cells = nb.get("cells", []) if isinstance(nb, dict) else None
++    if not isinstance(cells, list) or not all(isinstance(c, dict) for c in cells):
++        raise ValueError("not a Jupyter notebook")
 +    if cells and cells[0].get("cell_type") == "raw":
 +        head = "".join(cells[0].get("source", []))
 +        if FRONTMATTER.fullmatch(head):
@@ contrib/test_book.py: def test_check_rejects_a_page_without_a_type_status_or_sta
 +    with pytest.raises(ValueError, match="three.ipynb: Expecting value"):
 +        book.check("three.ipynb", "# Three\n")
 +
++
++@pytest.mark.parametrize("text", ["[]\n", '{"cells": {}}\n', '{"cells": [[]]}\n'])
++def test_check_rejects_json_that_is_not_a_notebook(text):
++    with pytest.raises(ValueError, match="three.ipynb: not a Jupyter notebook"):
++        book.check("three.ipynb", text)
++
 +
  def test_assembly_skips_reserved_files_at_any_level(tmp_path):
      root, out = tmp_path / "root", tmp_path / "root" / "src"
19: fda57dffdb ! 94: 3efd9584e5 Skip separators and part titles when walking the book's chapters
@@ contrib/test_jupyter_nb.py (new)
 +    out = json.loads(capsys.readouterr().out)["items"]
 +    assert out[0]["Chapter"]["content"] == "# Nb\n"
 +    assert out[2]["Chapter"]["content"] == "[a](../nb.md#x) [b](other.ipynb)\n\n[c]: ../nb.md\n"
-
- ## cspell/tooling.txt ##
-@@
- # Repository tools, identifiers, and upstream authors
- cacheprovider
-+capsys
- DejaVu
- devshell
- DNSSEC
107: dbe0d25372 ! 108: f2806d95f0 [WIP] Serve the draft from /docs-draft/
@@ book.toml: before = ["graphviz"]
 
  ## nix/site.nix ##
 @@
-             '';
+         '';
          # lychee loads CA certificates to build its HTTP client even with --offline.
          links = pkgs.runCommand "links" { nativeBuildInputs = [ pkgs.lychee pkgs.cacert ]; } ''
 -          # The site is served from /docs/, so a link from the root leaves it.

before it left."""
for op in ops:
page = parse(text, indexed)
op(page)
from hypothesis import given, settings
from hypothesis import strategies as st

import robot_marks
@nothingmuch nothingmuch changed the title draft integration [WIP] draft of complete docs Nov 11, 2026
"\n",
"Although this preserves the nominal sum of the sub-transaction, its weight, and therefore its implied fee rate, will differ. A high variance in the implied fee rates of sub-transactions is less likely, so unlike 1:1 exchanges, k:1 exchanges are not perfectly symmetric. Here a sub-transaction's implied fee rate is the nominal sum of its inputs minus that of its outputs, divided by the weight of the sub-transaction. Users who attempt to recover every last sat are more susceptible to such analysis.\n",
"\n",
"A partition of the inputs and outputs is only a valid sub-transaction mapping if each part's outputs balance its inputs. When the coins form a dense subset sum instance, almost any group of inputs can be balanced by many groups of outputs, and vice versa. With multiplicities high enough that no single sub-transaction uses every copy of a denomination, the remaining coins stay dense after any one sub-transaction is set aside, so the same holds for the rest of the transaction. Every input and output therefore appears in many distinct sub-transactions across all non-derived mappings.\n",

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Density claim fails after a sub-transaction consumes copies

The condition only ensures a sub-transaction leaves at least one copy of each denomination it uses, not that the remaining multiset stays dense. With six 1s, two 3s, and two 9s, a balanced sub-transaction can consume three 1s and one 3, satisfying the condition yet leaving 7 unrepresentable, so the 'many groups' claim does not follow.

oak · automated · f2806d9

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.

two strategies i have considered for this:

  • when computing the sumsets, compute explicit combinations. similar machinery is needed for coin selection, etc. this ensures distinct combinations, not reusing the same values. the output value selection subset sum density cost function term specifies this behavior to a limited degree, because it provides strict lower bounds.
  • and when that is intractable, shuffle the elements and construct a tree of sumsets with some fanout factor TBD, where each intermediate node in the tree is associated with the sumset generated by the values labeling the leaves of the tree. per Bringmann et al, stop when just before sumset by convolution transitions to the dense regime, and characterize the overall redundant density approximately the scale at which density emerges from disjoint subsets. i think Sasamoto et al has some theoretical insights into when the transition is normally expected.

this notebook is not trying to define cost function terms, those are done more carefully, this is more to give intuition about why the particular strategy of using these denominations has been proposed

"outputs": [
{
"data": {
"image/png": "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

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Density threshold does not bound every approximation gap

The plotted density is count / bin_width in sats, so a density at or above the dust inverse threshold only gives about one sum per dust-wide interval on average; it does not mean every value is approximable with error below dust. The notebook itself says some gaps still exceed the dust threshold even at the largest combination size shown.

oak · automated · f2806d9

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.

not sure which plot this is specifically but this is why absolute gaps are also plotted

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 comment is on the "Density of distinct sums" markdown at line 1387, above the density plot, not on the absolute gap histogram. It is about the sentence that density ≥ dust⁻¹ means every value can be approximated within dust; the notebook itself says some gaps still exceed the dust threshold even with six outputs (line 53).

oak · automated

Comment thread contrib/book.py
if not isinstance(cells, list) or not all(isinstance(c, dict) for c in cells):
raise ValueError("not a Jupyter notebook")
if cells and cells[0].get("cell_type") == "raw":
head = "".join(cells[0].get("source", []))

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Null raw-cell source crashes notebook check

A raw cell with source: null raises TypeError at book.py:55, which check does not catch, so the build aborts with a traceback instead of a ValueError.

oak · automated · f2806d9

"\n",
"In base 2, a value with multiplicity 2 within a single sub-transaction is exchangeable with the next denomination up from some other sub-transaction. Base 3 and 10 have somewhat more complex arithmetic relationships which imply yet more permutations of subsets of coins.\n",
"\n",
"If an arbitrary output value (i.e. with large Hamming weight) can be constructed -- or more generally than in Maurer et al, approximated -- by summing together $k$ distinct denominations, and each of which has multiplicity $m$ in the outputs of the sub-transaction mapping as a whole, then the number of equivalent mappings is $k \\times m!$. This counts permutations over sets of subsets of outputs, specifically when a subset of size $k$ is exchanged with a subset of size $1$.\n",

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Formula gives 6 where the case has 8 choices

For k=3 and m=2, choosing one copy of each denomination from two copies each gives 8 subsets, while k × m! gives 6, so the stated formula does not match this case.

oak · automated · f2806d9

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.

yes, this is supposed to be a (trivial) lower bound, it is a factor of the actual bound (because like instances of the symmetric group can be quotiented out of the sub-transaction model)

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.

5 participants