feat: update raiko caller for v3 batch/realtime API changes

[smartprogrammer93]

Summary

• Adapts the raiko proof caller to the updated /v3/proof/batch/realtime endpoint (NethermindEth/raiko#56)
• Adds l2_block_hashes to RaikoProofRequest and Proposal, accumulated from engine API responses as each L2 block is preconfirmed — used as part of the raiko cache key so reorgs don't serve stale proofs
• Implements proper two-phase submit/poll flow: first request sends full sources+blobs to trigger proving, subsequent polls send empty sources+blobs
• Handles new "proof not found" error (cache expiry) by re-submitting the full request with sources+blobs

Test plan

• Verify proof request JSON includes l2_block_hashes field with correct hex-encoded hashes
• Verify polling requests send empty sources and blobs arrays
• Verify "proof not found" error triggers re-submission with full payload
• End-to-end test with raiko instance running the updated endpoint

🤖 Generated with Claude Code

[smartprogrammer93]

@claude review

[claude]

Claude finished @smartprogrammer93's task in 2m 18s —— View job

---

Code Review

• Gather context and read changed files
• Review realtime/src/raiko/mod.rs
• Review realtime/src/node/proposal_manager/proposal.rs
• Review realtime/src/node/proposal_manager/batch_builder.rs
• Review realtime/src/node/proposal_manager/async_submitter.rs
• Post findings

---

Overall the change is well-structured and the two-phase submit/poll flow is clearly explained in code comments. A few things to flag:

Issues

1. Fragile string match for "proof not found" (raiko/mod.rs:188)

if msg.contains("proof not found") {

This is case-sensitive. If raiko ever sends "Proof not found" or "proof_not_found" the branch silently falls through to the hard error. Suggest at minimum .to_lowercase().contains(...). Better yet, if the raiko v3 API has a stable error code field, use that instead.

Fix this →

2. "Proof not found" re-submissions consume the retry budget (raiko/mod.rs:149-195)

Each time "proof not found" fires, it burns one slot from max_retries. If the raiko cache expires several times before the proof is ready, the loop can exhaust retries before ever receiving a successful response. The final error message "proof not ready after N attempts" would then be misleading (the proof was never ready because we kept re-submitting rather than polling).

Consider maintaining a separate counter for full-request re-submissions, or logging a warning when a re-submission eats into a low retry budget.

3. l2_block_hashes is Option<Vec<String>> but always Some (raiko/mod.rs:27, async_submitter.rs:179)

At the construction site the field is always Some(l2_block_hashes). The Option wrapper exists only to allow skip_serializing_if, but Vec::is_empty achieves the same effect without the wrapping Option. Using a plain Vec<String> with #[serde(skip_serializing_if = "Vec::is_empty")] removes a layer of indirection and makes the poll-request clone cleaner.

Fix this →

Non-issues (investigated and OK)

remove_last_l2_block does not touch l2_block_hashes — safe. Block hashes are pushed in set_proposal_checkpoint, which is only reached on engine API success. remove_last_l2_block is only called on engine API failure (mod.rs:424), before any hash is pushed for that block. The two lists stay in sync.

poll_request is constructed unconditionally — the struct is cheap to build (just clones) and this is in an already-async proof path, so no real concern.

use_full_request = false is set before response parsing — the state is correctly reset to true in the "proof not found" branch before continue, so the state machine is correct. The placement is slightly unintuitive but not wrong.

Nit

checkpoint.blockHash is accessed without _ prefix even though Checkpoint fields appear to use PascalCase from the ABI binding (blockHash, blockNumber, etc.). Worth double-checking whether clippy is happy with this on the CI run.

---

[smartprogrammer93]

@claude review

[claude]

Claude finished @smartprogrammer93's task in 1m 45s —— View job

---

Code Review

• Read changed files
• Review realtime/src/raiko/mod.rs
• Review realtime/src/node/proposal_manager/proposal.rs
• Review realtime/src/node/proposal_manager/batch_builder.rs
• Review realtime/src/node/proposal_manager/async_submitter.rs
• Post findings

---

The two-phase submit/poll flow is well-structured and the code comments clearly explain the intent. Commit 54ba9a2 resolved the case-sensitivity concern from the previous review pass. Two issues remain open:

Issues

1. Fragile string match for "proof not found" — Fixed in 54ba9a2 ✅

The .to_lowercase() fix is in place at raiko/mod.rs:188.

---

2. "Proof not found" re-submissions burn the retry budget (raiko/mod.rs:149-195)

Each cache-expiry event consumes one slot from max_retries. If the Redis TTL fires several times before the proof completes, the loop will exhaust retries and return "proof not ready after N attempts" — a misleading message when the real problem is repeated re-submissions.

Minimal mitigation: log a warning when a re-submission happens with fewer than (say) 3 retries left:

if attempt + 1 >= self.max_retries.saturating_sub(3) {
    warn!("Raiko: proof not found re-submission with low retry budget remaining");
}

Or track re-submission count separately so the error message can distinguish "never polled successfully" from "kept re-submitting".

Fix this →

---

3. l2_block_hashes is Option<Vec<String>> but is always Some (raiko/mod.rs:27, async_submitter.rs:179)

The Option wrapper exists only for skip_serializing_if = "Option::is_none", but a plain Vec<String> with #[serde(skip_serializing_if = "Vec::is_empty")] achieves the same result without the indirection. The Some(...) wrap and the Option::is_none guard add noise to every read site.

// current
#[serde(skip_serializing_if = "Option::is_none")]
pub l2_block_hashes: Option<Vec<String>>,
// ...
l2_block_hashes: Some(l2_block_hashes),

// suggested
#[serde(skip_serializing_if = "Vec::is_empty")]
pub l2_block_hashes: Vec<String>,
// ...
l2_block_hashes,

Fix this →

Non-issues (verified)

remove_last_l2_block vs l2_block_hashes sync — safe. set_proposal_checkpoint (which pushes a hash) is called only on successful engine API response. remove_last_l2_block is called only on engine API failure, before any hash for that block is pushed. The two vecs stay in sync.

Manual field-by-field poll_request construction — intentional. sources and blobs are zeroed out, so a plain .clone() wouldn't work. The explicit construction is the right approach here.

use_full_request = false placement — the flag is reset to true inside the "proof not found" branch before continue, so the state machine is correct despite the flag being cleared unconditionally before response parsing.

[mikhailUshakoff]

We also need to check the cancel_token; otherwise, if we receive a cancel signal, we won’t be able to shut down Catalyst before handling proof retrieval.
I've created issue #935