Add nonce endpoint

[GCdePaula]

Summary

Adds two public ingress reads so a wallet can prepare a signature without guessing: GET /nonce?sender= (the nonce to sign next) and GET /domain (the EIP-712 domain /tx verifies against). It also makes the user-nonce rule the nonce endpoint relies on an explicit application contract, and rejects the unreachable-in-practice u32::MAX nonce instead of panicking.

What changed

GET /nonce?sender=0x… → {"sender": "0xAbC…", "next_nonce": 7}

• next_nonce is one past the sender's latest user op in a valid batch, or 0. It is named next_nonce because nonce in /tx responses and the WS feed is the nonce an op consumed.
• The value is derived from user_ops rows the inclusion lane already writes in the FULL commit that authorizes each POST /tx ack. There is no new table and no new writer; a (sender, nonce) index keeps the lookup off a full-history scan.
• A read after a 200 sees the op, because the commit precedes the ack.
• Recovery lowers the value on its own: the valid_batches filter excludes invalidated rows, which are kept and whose nonces are reused on resubmit.
• The value counts soft-confirmed ops. It is a hint for one op in flight per sender; concurrent submits from one sender are unsupported.
• A never-seen sender gets 200 with 0. A lookup that finds no row is an answer, not a storage fault.

GET /domain → {"name", "version", "chainId", "verifyingContract"}

• Serves the exact domain /tx verifies against, keyed as eth_signTypedData_v4 expects.
• Clients pin their own domain and assert against this one, like checking eth_chainId. chainId stays a JSON number; the README explains why.

Also

• /fee and /nonce send Cache-Control: no-store. /fee is otherwise unchanged.
• There is no nonce or fee pre-filter on POST /tx. A stale op costs the lane an in-memory check and no transaction; a pre-filter would add a SQLite read to every honest submit and is easy to bypass. The api.rs module doc records the reasoning and when to revisit it.
• The user-nonce rule is now contract: accounts start at 0, validation requires an exact match, each included op advances the nonce by one, and nothing else changes it. It is stated in the application contract, the trait docs, the C header, and AGENTS.md.
• The shared validate_and_execute_user_op rejects nonce u32::MAX with InvalidReason::NonceExhausted, which the lane and the canonical scheduler both apply. The wallet used to panic in apply there. Reaching it takes 2³²−1 paid ops from one sender.
• Rust SDK: adds get_nonce and get_domain. GetFeeError is renamed to QueryError, shared by the three read routes.
• Performance notes are filed in-tree: a dated measurement record and a new "Known optimizations" section in docs/review/register.md.

Why this design

Asking the app for a nonce would mean querying the inclusion lane, which puts reads into the one bounded queue and onto the single app thread. Reading SQLite does not contend with the lane: WAL readers never block the writer. The lane already persists every included op's (sender, nonce), so the nonce is derived from facts that already exist.

We considered and rejected two replicated tables:

• Written by the API after each ack: it adds a second hot-path writer, loses updates when the process crashes or the client disconnects after the ack, and never rolls back when recovery lowers nonces.
• Written by the lane: it needs a recovery-time rewind, and recomputing that rewind is the same query.

Known limitation

After an operator rebuild (setup --recovery), a sender with no surviving op since the rebuild reads 0 even when its nonce in the rebuilt baseline is higher. A 422 bad-nonce rejection still names the expected nonce. This is documented in the README and the contract, and the rebuild-round-trip e2e test asserts it. Cockroach recovery is being redesigned as a separate tool; seeding baseline nonces belongs there (Track 6 note).

Performance

Measured on an M5 Max running macOS, with WAL + synchronous=FULL, 64-op chunks, 192k ops. Full method and limits are in docs/review/2026-09-25-sender-index-commit-cost.md.

• Write side: the sender index raises a chunk commit from 0.27 to 1.0 ms mean, and from 1.1 to 9 ms at p99, because checkpoints run inline. That is about 12 µs per op, against the 500 ms ack target.
• Why the index stays: any sender-keyed structure pays about the same once the sender population is large, and a derived index needs no recovery maintenance.
• Read side: about 2 µs per query plus about 0.2 ms to open a connection per request. After recovery, the lookup also walks the sender's invalidated rows above its nonce, about 0.11 µs each, bounded by that sender's own rolled-back volume.
• The alternatives and their revisit triggers are in the register.

Risk and compatibility

• Schema: rewrites baseline migration 0001 to add the index. There are no deployed databases, but existing data directories need a fresh setup to get it.
• Rejection semantics: adds NonceExhausted in the shared boundary, which changes canonical behavior only for an op at u32::MAX, which used to crash the machine.
• C ABI: appends APPLICATION_ENGINE_NONCE_EXHAUSTED = 3, carried like the max-fee reason. Engines never report it, and the host treats it as unsupported if one does. @edubart: this is additive only, but it touches the shared header.
• Contract: contiguous, exact-match, +1 per-sender nonces are now required of every engine; libdex should confirm it follows the rule.
• SDK: GetFeeError is renamed to QueryError.
• API: additive only. POST /tx and the /fee body are unchanged.