feat(ledger): trade-ledger foundation — schema + no-op access layer

[0xfandom]

Heads-up for reviewers — this PR does NOT close #95.
It ships only the foundation slice of the trade-ledger work: schema + no-op access layer. The Postgres-backed writes, engine / executor wiring, scheduled rollup, and CI integration-test container all land in separate follow-up PRs (links in Out of scope below). #95 stays open until those land.

Why split: the full issue touches Rust + Go + infra + CI + docs (~25-40 files) and has merge-conflict surface with in-flight PRs (#93 shadow, #98 obs, #114 polling). Foundation-only keeps this PR mergeable today with zero behaviour change when DATABASE_URL is unset.

Summary

• Adds postgres:17 compose service (healthcheck + named volume).
• Adds migrations/0001_trade_ledger.sql — 5 tables: arbs, bundles, inclusion_results, pool_registry, pnl_daily. U256 → NUMERIC(78,0), variable-shape path data → JSONB, all timestamps TIMESTAMPTZ. Indexes per the issue spec.
• Adds scripts/db_migrate.sh — sqlx-cli wrapper, loads .env, applies migrations.
• Adds Ledger trait + NoopLedger default in Rust (crates/common/src/db.rs) with NewArb / NewPool / InclusionUpdate payloads.
• Adds Ledger interface + NoopLedger default in Go (internal/db/ledger.go) with NewBundle / NewInclusion / PnLDailyDelta payloads.
• .env.example documents DATABASE_URL + POSTGRES_USER/PASSWORD/DB (commented out so unset behaviour stays the default).

Backward compatibility: binaries still build and run identically to current main. NoopLedger discards every write and logs once at startup so operators can grep for ledger disabled.

Files Changed

File	Purpose
migrations/0001_trade_ledger.sql	Initial schema (5 tables + indexes)
scripts/db_migrate.sh	sqlx-cli migrate wrapper
crates/common/src/db.rs	Rust Ledger trait + NoopLedger
crates/common/src/lib.rs	Export db module
crates/common/Cargo.toml	Promote serde_json + tracing to runtime deps
internal/db/ledger.go	Go Ledger interface + NoopLedger
internal/db/ledger_test.go	Go ledger smoke test
deploy/docker/docker-compose.yml	postgres:17 service + postgres-data volume
.env.example	DATABASE_URL + POSTGRES_* lines

Acceptance Criteria (issue scope satisfied by this PR)

• docker compose up postgres brings up Postgres 17 with healthcheck (compose config validated; reviewer to do live up)
• scripts/db_migrate.sh is in place; applies 0001_trade_ledger.sql idempotently against any reachable Postgres
• With DATABASE_URL unset: both binaries boot and run identically to today (no writes, no errors)
• cargo build --workspace, cargo clippy --workspace --all-targets -- -D warnings, cargo test -p aether-common clean
• go build ./..., go test ./... -race -count=1, go vet ./... clean
• Deferred to follow-up PRs: rows actually written by live / shadow / replay; row counts matching Prometheus counters; CI integration-tests job against a real Postgres service container

Test plan

• cargo build --workspace — green
• cargo clippy --workspace --all-targets -- -D warnings — clean
• cargo test -p aether-common --release — 40 pass incl new NoopLedger tests
• go build ./... — green
• go test ./... -count=1 — green incl new ledger smoke test
• go vet ./... — clean
• docker compose -f deploy/docker/docker-compose.yml config — postgres service + postgres-data volume registered correctly
• Reviewer manual: docker compose up postgres -d + DATABASE_URL=postgres://aether:aether@localhost:5432/aether ./scripts/db_migrate.sh applies the migration

Out of scope — tracked under #95, will land in follow-ups

• Rust PgLedger — sqlx::PgPool impl of Ledger; engine wiring (insert_arb on every ARB PUBLISHED, insert_pool on auto-registered pools); workspace sqlx + uuid deps.
• Go PgLedger — pgxpool impl; executor wiring (InsertBundle on bundle build, InsertInclusion on GetBundleStats resolve).
• pnl_daily rollup — scheduled job, once per UTC day.
• CI — postgres:17 service container in the Rust integration-test job, schema-applied + round-trip test.
• Redis state cache — separate hot-path concern, different access pattern.
• mev-inspect-py importer + Grafana dashboards backed by this schema — downstream of wiring.

Refs #95

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
aether	Ready	Preview, Comment	May 4, 2026 1:41pm
aether-63xv	Ready	Preview, Comment	May 4, 2026 1:41pm

[Pablosinyores]

Review — feat(ledger): trade-ledger foundation

Foundation slice is well-scoped and the "zero behaviour change when DATABASE_URL unset" promise holds in code. Verified locally: cargo build -p aether-common, cargo test -p aether-common --lib db:: (2/2), go build ./internal/db/..., go test ./internal/db/..., go vet ./internal/db/..., docker compose config, bash -n scripts/db_migrate.sh — all clean. Schema↔payload mapping walked column-by-column on both sides.

Hot-path latency impact verified zero: NoopLedger is empty-body vtable dispatch, no alloc, no atomic. OnceLock/sync.Once only fires in the constructor.

Blocking (CRITICAL)

1. internal/db/ledger.go:40 — Error string is not nullable

SQL inclusion_results.error TEXT is nullable. Go zero-value "" will write an empty string instead of NULL, so WHERE error IS NULL returns zero rows for successful inclusions. Rust counterpart at crates/common/src/db.rs:70 correctly uses Option<String>.

-    Error         string
+    Error         *string

2. internal/db/ledger.go:39 — LandedTxHash []byte has no length contract

Schema is semantically a 32-byte tx hash; Rust counterpart at crates/common/src/db.rs:69 is Option<B256> (exactly 32 bytes). The unbounded []byte lets a caller silently write 0/20/64 bytes — Rust readers would then panic or get garbage. Suggest *[32]byte (nullable) or at minimum a documented length contract.

Should Fix Before Merge (WARNING)

• go.mod:29 — github.com/google/uuid is marked // indirect but is now imported directly in internal/db/ledger.go:16. Any go mod tidy will rewrite go.mod/go.sum. Run go mod tidy and commit the result.
• crates/common/src/db.rs:117-136 — uuid_compat::Uuid has no documented byte-order contract. google/uuid is RFC 4122; if the future uuid::Uuid swap uses a different layout, the FK correlation arbs.arb_id ↔ bundles.arb_id breaks silently. Add // TODO: replace with uuid::Uuid (RFC 4122 byte order) before PgLedger impl ships on the struct so the swap is gated on the byte-layout match.
• crates/common/src/db.rs:52 — NewPool.protocol: String is stringly-typed; ProtocolType enum already exists at crates/common/src/types.rs:7. Casing drift in the DB will silently break WHERE protocol = ... filters. Bind through the enum's Display impl.
• deploy/docker/docker-compose.yml:177 — postgres service starts unconditionally on every docker compose up, consuming port 5432 and ~50MB RAM even when no binary is wired to it. The reth service at line 199 uses profiles: [node] for the same reason. Add profiles: [ledger] (or similar) to preserve the "no surprise" contract for current operators.
• Clock-authority inconsistency — internal/db/ledger.go:25 (SubmittedAt) and :41 (ResolvedAt) are client-set time.Times that override the SQL DEFAULT now(), while arbs.ts has no Rust field and is DB-authoritative. If the Go executor's clock drifts vs Postgres, submitted_at/resolved_at aren't safely comparable with arbs.ts. Either document this as intentional (Go clock = "when Go acted", DB clock = "when row was written") or unify.

Nice to Have (SUGGESTION)

• migrations/0001_trade_ledger.sql:62 — inclusion_results_bundle_id_idx is redundant with the composite PK (bundle_id, builder) (line 59); the PK B-tree already serves any leading-column query. Drop it.
• internal/db/ledger.go:57-59 — interface methods take structs by value. NewBundle.SignedTxHex is a ~500B string. NoopLedger is fine (compiler elides), but the future PgLedger is forced to copy on every call. Pointer receivers cost nothing now and avoid a future interface-breaking change.
• crates/common/src/db.rs:81 — trait methods are infallible by design. This boxes the future PgLedger into log-and-drop, which works for fire-and-forget but rules out caller-side retry/metric emission. Consider -> Result<(), LedgerError> with an extension trait that auto-logs-and-drops for hot-path callers.

What's Good

• Single coherent commit, conventional format, clean message.
• 9 files, no drive-by edits, scope matches the PR body.
• NUMERIC(78,0) correctly sized for U256 (2^256 has 78 digits). BYTEA/TIMESTAMPTZ choices are correct.
• OnceLock<()> / sync.Once startup-warn is symmetric across both binaries with identical log message, so operators can grep ledger disabled on either side.
• Trait object safety is explicitly tested (db.rs:151).
• No existing code imports aether_common::db or internal/db outside the new files — runtime behaviour vs main is genuinely unchanged.

Verdict

REQUEST CHANGES — gated on the two CRITICAL items above. Once those land, the WARNINGs are cheap fixes that lock the schema/trait into a shape that won't fight the PgLedger follow-up.

[Pablosinyores]

Re-review — all prior findings addressed

Verified locally on e4fc873: cargo build -p aether-common, cargo test -p aether-common --lib db:: (2/2), cargo clippy -p aether-common --all-targets -- -D warnings, go build ./internal/db/..., go test ./internal/db/..., go vet ./internal/db/... — all clean. CI green (rust 2m55s, go 29s, solidity 17s, toolchain 4s). mergeStateStatus: CLEAN.

Blocking findings — both resolved

internal/db/ledger.go:48-49 — LandedTxHash *[32]byte and Error *string now match the Rust counterpart's nullability + length contract. The struct doc explicitly calls out the bugs the previous shapes would have caused ("" instead of NULL; arbitrary-length tx hashes), which closes the loop nicely for a future reader.

Non-blocking findings — all resolved

• go.mod:7-12 — github.com/google/uuid and the four go.opentelemetry.io/otel packages promoted to the direct require block. go mod tidy is now a no-op for contributors.
• crates/common/src/db.rs:124-137 — uuid_compat::Uuid byte-order contract documented as RFC 4122 network byte order, with explicit notes on Postgres binary wire format compatibility, uuid::Uuid::as_bytes/from_bytes round-trip, and the gotcha around from_bytes_le / Windows GUIDs. The future uuid::Uuid swap is now a typed contract, not an implicit assumption.
• crates/common/src/db.rs:59 — NewPool.protocol is now ProtocolType, not String. Stringly-typed casing drift in the DB is no longer possible. crates/common/src/types.rs also derives Default mapping to ProtocolType::UniswapV2 = 1 so the Default derive on NewPool keeps working — the rationale is in the doc comment, which I think is the right safe sentinel.
• deploy/docker/docker-compose.yml — postgres service is now gated behind profiles: [ledger]. Verified: docker compose config --services returns 9 services (no postgres); docker compose --profile ledger config --services returns 10 (postgres added). The "no surprise" contract for current operators is intact.
• migrations/0001_trade_ledger.sql:11-22 — clock-authority policy is now an explicit comment in the schema header: event-time columns (arbs.ts, bundles.submitted_at, inclusion_results.resolved_at) are CLIENT-SET, persistence-boundary columns (pool_registry.first_seen/last_seen, pnl_daily.updated_at) are DB-SET. The reasoning (event-vs-row time skew under load) is captured. Future wiring PRs have a clear contract.

One minor follow-up (non-blocking, just for tracking)

The new clock-authority policy says arbs.ts is CLIENT-SET, but NewArb at crates/common/src/db.rs:30-48 still has no ts field. The wiring follow-up that ships PgLedger will need to add pub ts: chrono::DateTime<Utc> (or equivalent) to NewArb and have callers populate it at arb-creation time. Same applies to NewBundle.SubmittedAt and NewInclusion.ResolvedAt on the Go side, which already have client-set fields — those are good. Just calling out the asymmetry so it doesn't slip when PgLedger lands.

Quality of the fixes is high — author didn't just patch the field types but also added doc comments explaining the bugs the original shapes would have caused, which makes the intent durable.

Verdict: APPROVE