feat: range reduction breaks paired claims / unclaims

[joanestebanr]

Summary

This PR adds two independent safety features:

Fix: #343 Detect broken import/unclaim pairs after range reduction

When the proposer reduces the end_block of a certificate (range reduction), it is possible that an imported_bridge_exit falls within the new range while its matching unclaim does not. This would cause the import to appear as valid in the proof even though it was intentionally cancelled.

A new validate_no_broken_pairs check is added in aggchain-proof-service that, whenever the proposer returns a different end_block than the one originally requested, verifies that no (imported_bridge_exit, unclaim) pair is split by the new boundary. Pairs are matched by global_index in chronological order (k-th import ↔ k-th unclaim). If a broken pair is found, proof generation is aborted with a descriptive error.

Fix: #346 full error chain returned to gRPC clients

Previously, gRPC error responses only included the top-level error message (error.to_string()), silently dropping all nested cause messages. A new format_error_chain helper walks the full source() chain and concatenates all messages, so clients now receive the complete error description.

Chore: IGNORE_VKEY_MISMATCH environment variable to be able to develop/debug locally

Adds an opt-in escape hatch for development/testing environments: when IGNORE_VKEY_MISMATCH is set, vkey hash and range vkey commitment mismatches between the on-chain op-succinct config and the local ELF are logged as warnings instead of returning an error, allowing the server to continue running. The mismatch is still clearly surfaced in the logs. This flag should never be set in production.

Chore: scrtipt automates the setup needed to run the aggkit-prover locally against a live Kurtosis enclave (a local multi-service test environment).

Changes

• aggchain-proof-service/src/validation.rs — new module with validate_no_broken_pairs and unit tests
• aggchain-proof-service/src/service.rs — calls the validation after receiving a proposer response with a reduced end block
• aggchain-proof-service/src/error.rs — new BrokenImportUnclaimPair error variant
• aggchain-proof-builder/src/lib.rs — IGNORE_VKEY_MISMATCH support for aggregation vkey hash and range vkey commitment checks
• aggkit-prover/src/rpc.rs — format_error_chain helper; full error chain now returned to gRPC clients
• proposer-client/src/rpc/mod.rs — minor error wrapping fix
• scripts/generate_config_based_kurtosis_to_run_locally.sh — new helper script for local Kurtosis-based testing

Fixes #343, #346

[CLAassistant]

All committers have signed the CLA.

[Copilot]

Pull request overview

Adds a safety validation to detect when a proposer-reduced end_block would cause an import/unclaim pair to be split (and therefore incorrectly treated as a valid claim), plus a helper script to generate a locally-runnable config from a Kurtosis enclave.

Changes:

• Add validate_no_broken_pairs to detect broken (imported_bridge_exit, unclaim) pairs under range reduction, with unit tests.
• Wire the validation into AggchainProofService and introduce a dedicated error variant.
• Add a script to download the Kurtosis config artifact and rewrite internal endpoints/paths for local execution.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
scripts/generate_config_based_kurtosis_to_run_locally.sh	Downloads config/genesis from Kurtosis and rewrites endpoints/paths for local runs.
crates/aggchain-proof-service/src/validation.rs	Implements broken-pair detection logic with a comprehensive test suite.
crates/aggchain-proof-service/src/service.rs	Calls the new validation when the proposer returns a different end_block.
crates/aggchain-proof-service/src/lib.rs	Registers the new validation module.
crates/aggchain-proof-service/src/error.rs	Adds an error variant for broken import/unclaim pairs.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 0545b620d6

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[Copilot]

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated 5 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[hadjiszs]

Thanks! Here is a first pass of review

[hadjiszs]

I asked claude to try to make this function more readable

it suggested something like below (not tested nor properly reviewed), wdyt? Happy to review another version if you find better 👌
but basically trying to have dedicated structs if possible, and splitting this function into "build pairs into well-suited data structures" followed by "check the pairs"

#[derive(Debug)]
struct ImportUnclaimPair {
    global_index: U256,
    import_block: u64,
    unclaim_block: u64,
}

pub(crate) fn validate_no_broken_pairs(
    imports: &[ImportedBridgeExitWithBlockNumber],
    unclaims: &[UnclaimWithBlockNumber],
    new_end_block: u64,
) -> Result<(), Error> {
    for ImportUnclaimPair {
        global_index,
        import_block,
        unclaim_block,
    } in pair_imports_with_unclaims(imports, unclaims)
    {
        if import_block <= new_end_block && unclaim_block > new_end_block {
            return Err(Error::BrokenImportUnclaimPair {
                global_index,
                import_block,
                unclaim_block,
                new_end_block,
            });
        }
    }
    Ok(())
}

/// Pairs the k-th import event for each `global_index` with the k-th unclaim
/// for the same `global_index`, both in (block_number, log_index) order.
/// Excess events on either side are dropped — they correspond to imports
/// not yet cancelled, or unclaims targeting imports outside this witness.
fn pair_imports_with_unclaims(
    imports: &[ImportedBridgeExitWithBlockNumber],
    unclaims: &[UnclaimWithBlockNumber],
) -> Vec<ImportUnclaimPair> {
    #[derive(Default)]
    struct EventLists {
        imports: Vec<(u64, u64)>,
        unclaims: Vec<(u64, u64)>,
    }

    let mut by_gi: HashMap<U256, EventLists> = HashMap::new();

    for ev in imports {
        by_gi
            .entry(ev.global_index.into())
            .or_default()
            .imports
            .push((ev.block_number, ev.log_index));
    }

    for ev in unclaims {
        by_gi
            .entry(ev.global_index)
            .or_default()
            .unclaims
            .push((ev.block_number, ev.log_index));
    }

    by_gi
        .into_iter()
        .flat_map(|(global_index, mut events)| {
            events.imports.sort_unstable();
            events.unclaims.sort_unstable();

            events
                .imports
                .into_iter()
                .zip(events.unclaims)
                .map(move |((import_block, _), (unclaim_block, _))| ImportUnclaimPair {
                    global_index,
                    import_block,
                    unclaim_block,
                })
        })
        .collect()
}

[joanestebanr]

Thanks! Good suggestion — I went ahead and applied essentially this exact refactor in refactor(validation): split pairing from broken-pair check.

The current version now has:

• a dedicated ImportUnclaimPair struct,
• validate_no_broken_pairs reduced to just iterating the pairs and checking the broken-pair condition,
• the pairing logic extracted into pair_imports_with_unclaims (with the EventLists helper).

Only differences vs. your snippet are cosmetic: full-word variable names (imported_bridge_exits, events_by_global_index) to match the repo style, and slightly reworded doc comments. Let me know if you'd like anything else tweaked 👌

[hadjiszs]

lgtm 👍

nit: we may get some issues if aggsender submits some unclaim that are prior to the last_proven_block, due to the order in which we sort and filter, but I guess aggsender already enforce that when generating its request, so I'm fine not bothering too much there

[hadjiszs]

nit: otherwise IGNORE_VKEY_MISMATCH=false would enable it

Suggested change

	let ignore_mismatch = std::env::var("IGNORE_VKEY_MISMATCH").is_ok();
	let ignore_mismatch = prover_utils::from_env_or_default("IGNORE_VKEY_MISMATCH", false);