Repository navigation
draft integration - #80
Draft
yuval-block wants to merge 104 commits into
Draft
yuval-block wants to merge 104 commits into
yuval-block wants to merge 104 commits into
Conversation
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>
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 indented entry at the start of a part has no entry to nest under, and an entry indented more than one level deeper than the entry above has no parent at the level between, so both are rejected, as are indents that are not a multiple of two spaces. Tabs and other indented lines are still unexpected lines. OKF v0.2 shows 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>
Co-authored-by: bc1cindy <bc1cindy@proton.me> Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The notebook package re-executes the notebook. Execution is deterministic and records no timing metadata, so re-rendering the notebook amounts to copying the build output over it, and a notebook that is already up to date comes back byte-identical. Only editing or executing the notebook needs the scientific python stack, so it stays out of the default shell and the site build. The notebook devshell has the same dependencies as the derivation, plus jupyterlab, whose checkpoint directories are ignored. Every dependency is packaged in nixpkgs, so no uv2nix layer is required. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The saved plots came from Colab, whose environment is not recorded anywhere. Re-executing with the notebook derivation reproduces the same data (the denominations table is unchanged), and the result is a fixed point: building again from the re-rendered notebook leaves it byte-identical. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The last chart counted n^k ordered selections, which overstates the number of size k combinations with replacement from n denominations, (n+k-1 choose k), by orders of magnitude: 30,840,979,456 versus 55,525,372 for k=6. With the correct count the combinations stay below the number of distinct integers in the range for every k. The density axis was scaled by an invisible scatter of the densities, which only lined up with the count axis while the combinations curve set the top of the plot. Derive its limits from the count axis instead. The output is rendered by the notebook derivation. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Split the long conditional sentences, say what Hamming weight 1 means for the denominations in use, and state what the notebook measures before the asymptotic claim about the size of the denomination set. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
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>
--- - [x] Define wallet-state domain and transitions - [x] Define expectation and brackets - [x] Define piecewise-linear sign-change evaluation - [x] Reconcile multiparty monotonicity with wallet-state domain Co-authored-by: GPT-5.6 Sol <noreply@openai.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>
Apply the fixes from the PR 15 review that were made on the cost-function-review branch (56f24f01, 139a1679, 93f82c18), which still edits the old cost_function.md path: - Cindy's typo list, and a few more of the same kind - RBF double spends the transaction's spent outputs, not its own outputs (oakagent's comment) - The objective cost is the negated change in balance, so it is positive when a transition pays a fee and reduces the balance Lines that were rewritten in "Clarify abstract cost function" keep that wording. The unresolved diff at the end of that commit is left as it is, with the same fixes applied to both of its sides. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Verbatim notes on how the decision tree is built, to be distributed where they belong in the repository. things like the actions going into broadcasting ownership proofs, making co-spend proposals, broadcasting unilateral co-spend proposals (e.g. a single coin with surplus and density certificate requirement vs. picking specific values and choosing payoffs for them) describe how the tree is built bottom up: 1. partition the queue of intents in the wallet state heuristically 2. each partition is an outcome, batches to execute 3. for each outcome, generate coin selections iteratively batch by batch possibly shuffling. these can be optimizing or fully randomized, interactive incoming payments could be treated as pseudo-inputs. ensures the outcome has a positive surplus and can be executed 4. for each surplus, decompose it by brute force enuemration of radix possibilities 5. for coins on the order book "select" them to extend outcomes this generates a bunch of independent, complete, balanced outcomes that each involve disjoint batches (though typically there will be one greedy batch, or one small batch for a unilateral fallback if it becomes urgent) the shared coins of these are then used to guide the decision tree, as is individual coins' luck at the current time or the next time (beacon values don't need to be the current block tip they can be delayed by some block depth) each path down the decision tree is a plan, by building the trees bottom up by scheduling actions that are least comittal first and leaving the ones shared by most outcomes to be the roots, all actions including announcements, co-spend proposals etc can be planned, and new alternatives can be added to this or an entire tree recalculated and potentially ORed with the current one from any arbitrary state however because this object is potentially large and costly to generate and evaluate we want to generate most of it up front as co-spend proposals, coalition formation proposals and auxiliary inputs of comitted transactions are learned the decision tree can be updated expectations about the durations of certain steps can be annotated along the path, which allows the time dependence of the leaves to be taken into account ensuring to schedule actions to take place early enough interanlizing expectaitons about the children into their parents gives a way to evaluate the parents' piecewise linear curve, and solve for the time at which the next child it is expected to have positive utility and at that point take this branch (unless new information comes in and invalidates the decision) --- - [x] Describe the bottom-up construction in the decision tree structure section of cost_function_abstract.md - done in “Describe how the decision tree is built” - [x] List the actions (ownership proofs, co-spend proposals, unilateral co-spend proposals) - done in “Describe how the decision tree is built” 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>
The decision tree section only had a FIXME saying the tree is built
bottom up. Describe the construction from the notes recorded in the
parent commit:
- the actions, including announcements and negotiation, not just
transaction construction
- outcomes generated first: partition the intents, select coins batch by
batch, decompose each surplus into radix denominations, extend with
coins from the order book
- the tree arranged over these outcomes, least committal actions first,
guided by shared coins and luck under the beacon
- updating the tree as proposals and auxiliary inputs are learned
- durations along each path, and solving the parent's piecewise linear
curve for the time to take the next branch
---
- [x] List the actions
- [x] Describe the bottom-up construction
- [ ] Settle the term for a proposal naming a single coin ("unilateral
co-spend proposal" in the notes, "single-UTXO proposal" in the
subset sum ambiguity chapter)
- [ ] Check "surplus" here (what is left after funding a batch) against
the surplus of a co-spend proposal in coalition_formation.md
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>
cspell rejects "feerates", "locktimes", "backout" and "Parameterizing" in docs/cost_function_abstract.md. The first three are Bitcoin and Lightning vocabulary, so they go in the shared dictionary. "Parameterizing" is only used in this chapter's heading, so it is allowed inline, as cost_function_subset_sum_ambiguity.md does for its own words. 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.
Finish resolving the conflict. The end of the document was still the diff part of a jj conflict: lines prefixed with "+", "-" or a space, followed by the conflict's closing marker. Keep the "-" side, the original wording of the end of "Use in multiparty protocols", and drop the "+" side: - "Piecewise-linear payoff curves and sign changes", whose math wasn't reviewed. Solving for intercepts is described in words in a later commit. - the rewrite of the last two paragraphs, whose point that partial transactions are information within a wallet state is already made in "Wallet states and actions". Monotonicity is rewritten in a later commit. Both are still in this commit's parent if they're wanted. Also empty the lines that contained only a space. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
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.
Compare the channel output with a unilaterally controlled output The lightning channel funding output is an output, so the comparison is with a unilaterally controlled output, not an input. From a593abdf on cost-function-review. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
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.
Weigh the waste metric against the other terms Consolidation at low feerates is what the waste metric favors, but the waste metric is just one term, included in every automated transaction. Whether coins are actually spent together also depends on other terms, such as privacy liabilities, which the abstract cost function leaves to concrete writeups. From 9500ed84 on cost-function-review. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
cost_function_randomized_selection.md adapts the randomization gist (#22) as three cost function terms: the per input and pairwise preferences, and the provenance term, which multiplies the funding transaction's liquidity and cost by the Sybil resistance index computed from joint sums. Covers the terms in the decision tree and after confirmation. sybil_resistance_index.md: the proofs of the joint sums bound, from the estimator in tx-graph-estimators (joint_spans.lcb), and the scan over candidate block hashes. The simulation, Rust timings and caps are from its rust-joint-spans bookmark. It replaces the chapters' review stubs. 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>
The Privacy liability terms chapter points to the metrics in its opening, and the Tactics chapter follows the Mixed strategy chapter. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Two additions to the overview: a paragraph pointing at the channel interfaces, and one relating per-peer trust assumptions to asymmetric distributed trust and Flexible BFT. Kept apart from the overview itself (PR 51) so it can be reviewed on its own. Co-authored-by: GPT-6.1 Sol <noreply@openai.com> Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
List the messages peers exchange: peer introduction, gossip, sets, public gossip, negotiation, session initialization, transaction construction, interactive payments and blocks. For each, say who sends it, to whom, in which setting, what it carries and what its channel must provide. The content comes from the peer messages draft (onwloqro) and the concurrent PSBT and coalition formation drafts. The draft's transport survey is left out: specs state channel properties, and choosing a transport belongs to another layer. It replaces the chapter's review stub. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
State what interactive payments need from peer to peer messaging: reaching the counterparty's device, inviting it into a collaborative transaction, and messaging it during the critical section for payment confirmations. Payment confirmations follow the payment graph and refer to the block DAG's committed message sets. Contact, identity and device management is left to applications. 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>
Ownership proof gossip, online key enrollment, its flood protection and precedence ordering, the gossip rules for listen advertisements, and the flood protection for partially accepted proposals are transport rules for the peer to world broadcast domain. Move them here from coalition formation unchanged, apart from a link from the listen advertisement rules back to coalition formation. The removal from coalition formation is a separate commit on the coalition formation branch. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Give the protocol an abstract syntax for messages: send, receive and bidirectional channels. Name the three kinds of messaging the protocol needs: peer to peer authenticated messages, and peer to group and peer to world anonymous messages, which are broadcast. Define connection and message unlinkability, and build broadcast by gossip from peer to peer channels that are sender anonymous and message unlinkable. SDK implementation choices (Rust traits, adapters, builders) are left to the SDK. It replaces the chapter's review stub. Links to other chapters resolve against their stubs until those land. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The radix footnote linked the notebook on Colab, which is becoming a chapter of the book. It names that chapter until both are merged. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: Armin Sabouri <me@arminsabouri.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Start from push gossip, then motivate pulling with the block structure: a peer holding a Merkle root wants the leaves it commits to. Honest peers send only hashes whose preimages they have validated, and answer a pull with the preimage, like getdata in Bitcoin. That is enough for the naive reconciliation of BEC. The same mechanism exchanges roots of unordered sets: the mempool-like set of a group, and the order book of the world. Range reconciliation and rateless streams are optimizations of this one mechanism. It replaces the chapter's review stub. Co-authored-by: GPT-6 Astra <noreply@openai.com> Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The DAG doesn't order messages; its message sets are sets, committed to by sparse Merkle trees. The ordered/unordered distinction is between a list and a set, as for a block's parents if they are committed to in an arbitrary order. Whether a set is in the block DAG determines its consistency guarantees instead, so rename the unordered sets section to sets outside the block DAG. Drop the relation to asynchronous data dissemination, which is for large messages; ours are generally small. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Record the best candidate found so far for proving that outputs are covered by inputs: input slots committed with their destinations, anonymous registration rate-limited by a tag per slot, and output proofs against the registered leaves, in jellyfish TurboPlonk on BN254 with a universal setup. The figures come from the jf-register proof of concept. Evaluation continues; the code will be rewritten for Fungi and this document finalized when validity proofs are needed. It replaces the chapter's review stub. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A stalled phase of the optimistic track turns into a recovery coalition formation proposal. Deadlines exist only on this track. Recovery track blocks have a reduced threshold t < n and commit unambiguously to what they are missing; a block that contradicts itself is invalid and its author treated as unresponsive, but an equivocating one still exposes the author's key. Counterparty stalls are specified as option A (blame the payer only), with option B (blame the pair) described and left open. Also covers the dishonest majority case, privacy, cost and a worked example. It replaces the chapter's review stub. Links to other chapters resolve against their stubs until those land. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The block structure both tracks of transaction construction share: its objects, optional block extensions, nonce commitments and compact equivocation evidence, genesis, causal order and block properties, and frontiers. It was a section of the transaction construction chapter, and is now its first sub-chapter. It replaces the chapter's review stub. Links to other chapters resolve against their stubs until those land. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A parent chapter for transaction construction in the abstract: content versus state synchronization, the phases, the two tracks, and what the validity proofs enforce, without how they work. The block DAG both tracks share is its first sub-chapter, followed by the optimistic and recovery tracks. The validity proofs chapter follows the protocol messages. It replaces the chapter's review stub. Links to other chapters resolve against their stubs until those land. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Phases close by unanimous acknowledgement, with no deadlines: each phase closes with an echo and a closing acknowledgement, the input set is stable before outputs, and the outputs phase closes on balance. The chapter goes through the phases one by one, including the censorship exception for a validator's own anonymous contributions. It also covers sharded state and synchronization scope, the dissemination interface, optional attested validation and acknowledgement relay, and block publication after quiescence. It replaces the chapter's review stub. Links to other chapters resolve against their stubs until those land. Co-authored-by: GPT-6 Astra <noreply@openai.com> Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Merge each protocol chapter's bookmark, and the overview with its transport edits, over the book structure and its review stubs. Each chapter replaces only its own stub, so the merge has no conflicts. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Ownership proof gossip, online key enrollment, its flood protection and precedence ordering, the gossip rules for listen advertisements, and the flood protection for partially accepted proposals now live in the channels chapter, under peer to world broadcast. Keep the section headings, so existing anchors still resolve, and point each one there. The channels chapter isn't on this branch, so these links only resolve where both are merged. 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>
range-diff for force push 1ee57d1562 → 8e41ba243d
|
oakagent
reviewed
Oct 26, 2026
oakagent
left a comment
oakagent
left a comment
There was a problem hiding this comment.
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
oakagent
reviewed
Oct 26, 2026
|
|
||
| - 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; |
There was a problem hiding this comment.
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
| - 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. |
There was a problem hiding this comment.
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
oakagent
reviewed
Oct 26, 2026
| additional-css = ["theme/diagrams.css"] | ||
| git-repository-url = "https://github.com/fungi-protocol/docs" | ||
| site-url = "/docs/" | ||
| site-url = "/docs-draft/" |
There was a problem hiding this comment.
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
| | [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 | |
There was a problem hiding this comment.
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
| """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", []) |
There was a problem hiding this comment.
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
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
mainly for @oakagent to pick apart, individual PRs for the various pieces will come separately