chore: trim the Midnight comments down to what is worth reading - #54
Merged
Conversation
Most of the Midnight comments were doing too much: module headers that ran 20-30 lines, doc comments restating the signature below them, and match arms narrated line by line where every sibling arm is bare. Cut them back to the non-obvious facts and deleted the rest outright. What went: - Doc comments that only echoed the item name. `toolkit.rs` alone had about a hundred of these, the same "Operation discriminator" / "Indexer GraphQL endpoint" block repeated across six near-identical request structs. Nothing in that module is reachable outside the crate, so none of it was required. - Design essays in the crate and module headers. The Rust siblings open with one line, so these do too, keeping only what is not visible from the code: the feature gate, the off-chain merkle tree, the trailing-zero trim. - Comments restating the assertion underneath them. A line reading "a shared prefix does not match" above an assert that a shared prefix does not match is not telling anyone anything. - Cross-chain trivia. Whether a choice matches EVM, Aleo, or Sealevel is interesting while writing the code and useless while reading it, so it stays only where it grounds a whole design. - Every #N issue reference in code and docs. - Narration of the Midnight arms in chains.rs, cursors/mod.rs, and chain.rs. One was also stale, still describing an on-chain merkle tree that was removed. - Tool and version detail that dates fast (compact-js, wallet-sdk, node and midnight-js versions) where the behaviour is the point, not the version. - The devnet integration test that was only an unimplemented!() and a four-step plan in a comment. - The stale "under construction" note in the midnight-sdk README and the "verified separately" note on PARTIAL_SUCCESS, which has since been confirmed safe. Also renamed one test to say what it asserts and dropped an unused mut. No behaviour change: cargo test -p hyperlane-midnight is 84 green, clippy reports no missing docs, tsc and oxlint clean across the touched packages.
ctoyan
force-pushed
the
chore/humanize-midnight-comments
branch
from
August 25, 2026 20:41
75a5f81 to
6b38022
Compare
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.
Comment-only pass over the Midnight work, in two rounds: the first rewrote the
overlong comments, the second deleted the ones that should not have existed at
all. Net ~900 lines of comment removed.
What went
toolkit.rsalone had about ahundred: the same
/// Operation discriminator//// Indexer GraphQL endpoint (HTTP)block repeated across six near-identical request structs.Nothing in that module is reachable outside the crate, so none of it was
required by
missing_docs— confirmed by clippy after removal.(
hyperlane-cosmos,hyperlane-aleo,hyperlane-sealevel) all open with asingle line, so these do too, keeping only what is not visible from the code:
the feature gate, the off-chain merkle tree, the
Bytes<N>trailing-zerotrim.
merkle_tree_hook.rswent 36 header lines to 10,metadata_tests.rs31 to 12,
state_decode.rs22 to 7.prefix does not match" sitting above an assert that a shared prefix does not
match tells nobody anything.
interesting while writing the code and useless while reading it. It stays
only where it grounds a whole design (the off-chain merkle tree).
#Nissue reference, including two in runtime strings: atodo!()message and an error message a user could actually see.
chains.rs,cursors/mod.rsand
chain.rseach had a comment describing the line below it, where everysurrounding arm has none. One was also stale — it still described reading
count/current_rootfrom an on-chain merkle tree that was removed. Thestate_decode.rsheader was stale too: it listed field positions ([0, 8],[0, 9]) that contradicted the actual constants directly below it.where the behaviour is the point. The reason the chunked deploy is hand-built
at the ledger level is still there; the exact version that forced it is not.
construction", and the
PARTIAL_SUCCESSnote no longer says segmentattribution is still being verified — that was confirmed safe.
core-config.yamltrimmed from a 14-line preamble to 5, matching theother example configs.
Three changes that are not comments
Flagging these since everything else is comment-only:
announce_and_read_back_on_devnetinvalidator_announce.rs. It was#[ignore]plusunimplemented!()and a four-step plan in a comment — itnever ran and never asserted anything. Say the word if you'd rather keep the
placeholder.
tx_status_filter_is_the_single_decision_pointtotx_status_filter_excludes_only_failures, so the name says what it asserts.mutinmailbox.rs.Verification
cargo test -p hyperlane-midnight— 84 passed, 3 ignoredcargo clippy -p hyperlane-midnight --all-targets— nomissing_docs, no newwarnings (one pre-existing
is_multiple_ofsuggestion, untouched by this PR)cargo check -p hyperlane-base -p relayer -p lander -p validator --features midnight— cleancargo fmt --all --check— cleantsc --noEmiton sdk and cli; builds green for midnight-sdk, provider-sdk,deploy-sdk
oxlintclean on every touched TS fileand the first round: the only non-comment changes are the three above.