docs: ADR bundle (0001-0008) — engine and CoW architectural decisions#12
docs: ADR bundle (0001-0008) — engine and CoW architectural decisions#12brunota20 wants to merge 5 commits into
Conversation
| ## Decision | ||
|
|
||
| Two pieces: | ||
|
|
||
| **1. Manifest schema gains `[[subscription.template]]`**, a topic-only log subscription whose address set is populated at runtime: | ||
|
|
||
| ```toml | ||
| [[subscription.template]] | ||
| chain_id = 1 | ||
| name = "uniswap_v3_pool" | ||
| event_topics = [ | ||
| "0xc42079f94a6350d7e6235f29174924f928cc2ac818eb64fed8004e115fbcca67", # Swap | ||
| "0x7a53080ba414158be7ec69b987b5fb7d07dee101fe85488f0853ae16239d0bde", # Mint | ||
| ] | ||
| ``` |
There was a problem hiding this comment.
This is interesting. I'm not so sure on this. I'm pretty sure from my understanding that eth_getLogs is capable of being queried by topic without an address for the log to originate from. The question is whether or not this JSON-RPC method is supported by RPCs (i.e. is it a general case that public / free RPCs generally gate on requiring the address as well as the topics?).
There was a problem hiding this comment.
Good question. Combined with an internal complexity flag (the schema and host-function surface adds engine state that no M2 deliverable consumes), ADR-0008 has been deferred entirely (status: deferred, target 0.3). The reference design (Envio HyperIndex-style register-address + topic-only [[subscription.template]]) is preserved as historical context but does not land in 0.2. Topic-only eth_getLogs is explicitly listed as the simplest alternative for the eventual 0.3 conversation; the question of "do public RPCs gate on address" is the right one to validate at that point against a concrete consumer module.
2 participants
Captures the eight architectural decisions Bleu has made (engine-side) or proposed (CoW host helpers, upstream policy, forward-looking factory pattern) across the M1 → M2 work. All eight carry status
proposedpending upstream sign-off; landing them here makes the decisions reviewable independently from the implementing draft PRs (#8, #9, #10).These ADRs went through internal Bleu review in bleu/nullis-shepherd#1 before opening here.
ADRs are ordered for reading (foundations → CoW infra → CoW helpers → cross-cutting), not chronologically.
Scope
engine.tomlseparate from modulenexum.tomllocal-storevia length-prefixed keycowprotocolto the head of upstream PR #5cow-apihost backend via cachedOrderBookApiper chainshepherd:cow@0.2.0cow-rsfirst, adopt in engine secondAlso adds
data/(enginestate_dirdefault) andskills-lock.json(local skill lockfile) to.gitignoreso the engine's runtime state does not pollute the working tree.Format
ADRs follow the
grill-with-docsformat: short title, 1-2 paragraph Context, Decision, Considered options (rejected alternatives worth remembering), and Consequences. Frontmatter carriesstatus: proposedand animplemented-in: <PR>pointer where applicable.Points to weigh on review
docs/04-state-store.md— the linked doc specifies one redb file per module; we propose a single shared file with a[len:u8][module][key]prefix. Rationale in the ADR. This is the one place Bleu deliberately deviates from the published design and needs explicit sign-off.cowprotocolprimitives. EthFlow is positioned as the Rust externalization of the ethflow indexer currently insidecowprotocol/services/crates/autopilot/src/database/onchain_order_events/ethflow_events.rs.composable::poll_and_build_orderwith richPollOutcome,eth_flow::decode_placement,OrderPostErrorrich variants +retry_hint,OrderBookApi::with_base_url,wasm32feature-gate) land as additional commits oncowdao-grants/cow-rsPR #5 and are consumed via the patched dependency in ADR-0004.Next
Once feedback comes in, statuses flip to
accepted(orsuperseded) in a follow-up commit. The most likely point of pushback is ADR-0003 (single redb file vs per-module file); the rest of the surface is either gap-filling or implementation choice over interfaces the upstream spec already defines.