You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
We stood up the design-doc system in #1229 and wrote the first active designs (on-disk format, devcontainer, the mdBook site itself) in #2090. But a bunch of Firewood's core still isn't written down anywhere as a proper design — it only lives in the code and in people's heads.
This issue is the running list of designs we still want to backfill. These aren't proposals for new work — they document things that already exist, written after the fact as active designs (totally fine, the workflow explicitly allows it). The point is to get the "how does this actually work" knowledge out of the code and into the book.
The designs/README.md links here instead of keeping the list inline, so this is the one place to check off items as they land.
The list
Revision management — how RevisionManager creates and expires revisions, what's kept in memory vs. on disk, the max_revisions default (128) and eviction, and how the persist worker fits in. On-disk format doc (0003) touches this but there's no dedicated design.
Hashing model — the default SHA-256 (merkledb-compatible) path vs. the ethhash feature (Keccak-256), how account nodes at specific depths get RLP-encoded values, and why the account-trie hash ends up as the real root. Nothing documents this today.
Proposals & commits — what a proposal is (a batch on top of a base root), the commit pipeline, and what happens when you commit against a revision that's moved on underneath you (conflict/rebase semantics).
State sync & reconstruction — range proofs, change proofs, the Reconstructed view, and how RootStore rebuilds state during sync. This folds in the "archival mode" story; the storage-layer half already lives in 0003.
Go FFI layer — how the ffi/ crate exposes a C-compatible API, the cargo build → go tool cgo flow, memory ownership across the Rust/Go boundary (who frees what, borrowed vs. copied), the #[repr(C, usize)] tagged-enum alignment rule, and how it all gets packaged and published as firewood-go-ethhash.
Not on the list (on purpose)
Free lists & the future-delete log (FDL) — already covered in 0003, so no separate design needed.
How to grab one
Run just new-design <slug> to scaffold a doc from the template, write it up as status: active, and open a PR. See docs/src/designs/README.md for the workflow. Check the box here when it merges. Add more items if you spot a subsystem that deserves its own design.
We stood up the design-doc system in #1229 and wrote the first
activedesigns (on-disk format, devcontainer, the mdBook site itself) in #2090. But a bunch of Firewood's core still isn't written down anywhere as a proper design — it only lives in the code and in people's heads.This issue is the running list of designs we still want to backfill. These aren't proposals for new work — they document things that already exist, written after the fact as
activedesigns (totally fine, the workflow explicitly allows it). The point is to get the "how does this actually work" knowledge out of the code and into the book.The
designs/README.mdlinks here instead of keeping the list inline, so this is the one place to check off items as they land.The list
RevisionManagercreates and expires revisions, what's kept in memory vs. on disk, themax_revisionsdefault (128) and eviction, and how the persist worker fits in. On-disk format doc (0003) touches this but there's no dedicated design.ethhashfeature (Keccak-256), how account nodes at specific depths get RLP-encoded values, and why the account-trie hash ends up as the real root. Nothing documents this today.Reconstructedview, and howRootStorerebuilds state during sync. This folds in the "archival mode" story; the storage-layer half already lives in 0003.ffi/crate exposes a C-compatible API, thecargo build→go tool cgoflow, memory ownership across the Rust/Go boundary (who frees what, borrowed vs. copied), the#[repr(C, usize)]tagged-enum alignment rule, and how it all gets packaged and published asfirewood-go-ethhash.Not on the list (on purpose)
How to grab one
Run
just new-design <slug>to scaffold a doc from the template, write it up asstatus: active, and open a PR. Seedocs/src/designs/README.mdfor the workflow. Check the box here when it merges. Add more items if you spot a subsystem that deserves its own design.