Skip to content

Backfill design docs for core subsystems #2139

Description

@demosdemon

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 buildgo 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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    area/docsDocumentationkind/tech-debtRefactors, cleanup, debt paydownpriority/P2Medium: should do, not urgent.status/readyTriaged and ready to be picked up.

    Type

    No type

    Fields

    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions