hardening(tier-2): polish, ergonomics & full-surface docs before v0.1.0 - #29
Merged
KaiCode2 merged 9 commits intoJul 7, 2026
Merged
Conversation
Part 1 of the Tier 2 polish PR (missing_docs sweep follows as its own commit). - Configurable quote sender: `SimConfig.from` (default `Address::ZERO`) + a new public `quote_via_call_from(cache, from, target, calldata)`; `quote_via_call` now delegates to it with ZERO (unchanged behavior). Every adapter's `simulate_swap` threads `config.from` so a caller can quote against a target that gates on `msg.sender`. facade_typing gains a sender-threading test. - New `docs/protocol-support-matrix.md`: a per-protocol v0.1 capability matrix (cold-start, offline-after-cold-start, exact-write vs resync, factory discovery, known limitations), linked from the README's protocol table. - README: note that the published crate excludes `tests/`, so `cargo test` on a crates.io download runs only inline unit tests (clone for the full suite). - docs/benchmarks.md: a point-in-time / reproduce note on the results (medians are one host/run; `cargo bench` emits full Criterion stats + HTML reports). Full gate green: tests (all/default/no-default), clippy -D warnings, fmt, doc. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…_docs)] Part 2 of the Tier 2 polish PR. Enable `#![warn(missing_docs)]` at the crate root (CI's `-D warnings` promotes it to an error), and document every previously-undocumented public item so the surface stays fully documented as it grows — ~300 items across types, factory, bytecode, registry, cache, traits, storage, reactive, driver, the adapter structs, and the module declarations. Docs only; no behavior change. Verified: missing_docs = 0 under all-features / no-default / experimental; clippy -D warnings (all-features + no-default + isolation), doc -D warnings, fmt, and tests all green. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…onal code seed CurveColdStartPlanner now skips discovery when CurveMetadata.discovered_slots is already known (a prior discovery, a trace, or a registry): no pool-account/bytecode fetch and no cold-cache get_dy slot-faulting, just a single verify round over the known slots. This makes a known-read-set single-pool cold_start as cheap as the bundled cold_start_many storage-program path Uniswap V2/V3 use. The discover->verify path is unchanged when discovered_slots is empty. Adds optional CurveMetadata.code_seed (+ with_code_seed builder + CurveAdapter::code_seeds): a caller-supplied Vyper runtime, verified once against on-chain EXTCODEHASH (mismatch -> purged -> lazy fetch), removing the one lazy code fetch a Curve pool otherwise pays on its first simulate_swap. Additive, non-breaking. Tests: verify-only skips-discovery + unfetchable-slot repair (cold_start_adoption), code_seeds unit test (curve), positive Curve one-shot classification (bootstrap_many). Adds examples/curve_cold_start_phases.rs and updates docs (curve-adapter, README, benchmarks). 216 tests pass; clippy/doc/all-features clean. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Uniswap V3 `Mint`/`Burn` previously always emitted a tick-range resync (an RPC round trip). They now event-source the affected state directly wherever it is already warm, matching the exact-write posture of the V2/Solidly `Sync` path, and resync ONLY for ticks outside the warmed window. The event carries the exact liquidity delta and the boundary ticks; the current tick comes from cached `slot0`. For each warm boundary tick the adapter read-modify-writes the packed `Tick.Info` word 0 — `liquidityGross` (low 128) and `liquidityNet` (high 128, opposite signs for the lower vs upper tick) — and toggles the `tickBitmap` bit on an init/clear (Uniswap `flipTick` is an XOR); the in-range global `liquidity` slot is adjusted by `±amount`. Those are exactly the slots a `QuoterV2` swap reads; `feeGrowthOutside`/`positions` are accounting-only (they do not affect `amountOut`) and are intentionally not maintained. A cold boundary tick (word 0 not cached) cannot be read-modify-written, so its info + bitmap slots fall back to a `VerifySlots` resync — the hybrid write-where-warm / resync-cold policy. No-layout pools still degrade to a conservative whole-storage invalidation. Correctness rests on the reactive runtime applying each input's updates before the next input's decode (verified in `ingest_batch_direct`), so read-modify-write sees prior events in the batch. Bitmap flips for both ticks in a shared word are accumulated into one combined write (two full-slot writes from the same pre-event view would not compose). Tests: 9 inline unit tests (packing round-trip incl. negative net, all four mint/burn sign combos, init/clear detection, overflow rejection, bit-position vs Uniswap `position`); reactive integration tests for warm direct writes, out-of-range liquidity, burn-to-zero bitmap clear (shared word), and cold-tick resync fallback; Pancake/Slipstream layout coverage retained. `RepairAction:: V3TickRange` is retained as a reserved variant. Full gate green (tests all/default/no-default, clippy -D warnings ×2, doc, fmt, missing_docs=0). Follow-up: an env-gated RPC parity test (apply a real Mint/Burn, compare event-sourced slots to eth_getStorageAt ground truth at the post-event block) — deferred pending an archive endpoint to author it against. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Ports the Curve verify-only fast path to BalancerV2ColdStartPlanner: when BalancerV2Metadata.balance_slots is already known (a prior discovery or a trace), skip the getPoolTokens discovery -- no vault-account fetch, no cold-cache faulting -- and warm exactly those slots in a single verify round, matching the bundled cold_start_many storage-program path. Config-supplied tokens are preserved (no getPoolTokens decode repopulates them). The discover->verify path is unchanged when balance_slots is empty. Adds balancer_cold_start_verify_only_skips_discovery. 217 tests pass; clippy/all-features/doc clean. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Adds tests/v3_liquidity_rpc.rs (env-gated, #[ignore]): for a real add- and remove-liquidity transaction, fetch the exact per-tx storage diff via trace_replayTransaction(stateDiff), warm the pre-tx state, apply the event through the adapter, and assert the event-sourced writes reproduce the on-chain post-tx values for every slot the adapter maintains — each boundary tick's packed Tick.Info word 0 (liquidityGross/liquidityNet, incl. a negative net in two's complement) and the in-range global liquidity. Verified live against a mainnet archive+trace endpoint: a JIT add + remove of the same liquidity on the USDC/WETH 0.05% pool — BOTH the Mint and the Burn reproduce the on-chain per-tx storage exactly (tickLower/tickUpper word0 + global liquidity). This is the RPC parity check deferred in the feature commit; it now exists and passes. serde_json added as a dev-dependency (parses the trace stateDiff JSON). Full gate green: clippy -D warnings (all-features + no-default), offline tests, fmt, doc, missing_docs=0. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
feat(uniswap-v3): event-source Mint/Burn liquidity (no RPC where warm)
perf(cold-start): verify-only fast path for Curve + Balancer (+ optional Curve code seed)
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
1 participant
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.
Tier 2 — polish, ergonomics & full-surface docs (pre-v0.1.0 hardening)
Third and final stacked hardening PR. Stacked on #28 (base =
hardening/tier-1-docs-robustness); review only the Tier 2 diff here. Retarget tomainonce #27 and #28 merge.Two commits:
1 — ergonomics + user-facing docs (
d0a7225)SimConfig.from(defaultAddress::ZERO) +with_from, and a new publicquote_via_call_from(cache, from, target, calldata).quote_via_calldelegates to it with ZERO (behavior unchanged for existing callers). All five adapters'simulate_swapthreadconfig.from, so a caller can quote against a target that gates onmsg.sender. Newfacade_typingtest asserts the sender threading.docs/protocol-support-matrix.md— a per-protocol v0.1 capability table (cold-start, offline-after-cold-start, exact-write vs resync, factory discovery, known limitations), linked from the README's protocol table.tests/, socargo teston a crates.io download runs only inline unit tests.docs/benchmarks.mdgains a point-in-time / how-to-regenerate note (medians are one host/run;cargo benchemits full Criterion stats + HTML).2 — full-surface documentation (
edd8e84)Enable
#![warn(missing_docs)]at the crate root (CI's-D warningspromotes it to an error) and document every previously-undocumented public item — ~300 items acrosstypes,factory,bytecode,registry,cache,traits,storage,reactive,driver, the adapter structs, and the module declarations. Docs only, no behavior change.missing_docs = 0under all-features / no-default / experimental, so the surface stays fully documented as it grows.Scope note
This tier implements the remaining checklist items (P1
missing_docs+ configurablefrom; all P2 items). The two speculative items in the original plan — extra decode-hardening and a cohesion sweep — were dropped: the Tier 0 adversarial review confirmed the adapter decode paths are sound (no overflow/OOM) and the five adapters already handle the trait uniformly, so there was no defect to fix.Verification
Full CI-parity gate green:
cargo test(all-features / default / no-default, 27 binaries),clippy -D warnings(all-features + no-default + per-protocol isolation),doc -D warnings,fmt --check,experimental-protocols×2,missing_docs = 0.A skeptical review agent audited the diff before this PR.
🤖 Generated with Claude Code