Boostrap app structure

[lucasbalieiro]

closes #1

this PR bootstraps the app and establishes the initial structure that future compliance scenarios will follow.

I know this is a larger-than-usual PR because it lays down the initial infrastructure. At this stage, I'm mainly looking for feedback on the overall architecture and project structure, so there's no need to spend too much time reviewing implementation details.

The goal is to establish a framework that makes adding new scenarios straightforward, without requiring changes to the execution framework. The SetupConnection scenario included in this PR serves as the reference implementation for future scenarios.

Currently, the application can connect to SV2 endpoints (Pools and Job Declarator Servers), execute protocol compliance scenarios, and report pass/fail results. Scenarios can be run against a single endpoint or against multiple deployments defined in a TOML configuration file.

What's included

• A library plus a CLI (src/bin/sv2_compliance.rs) for running compliance scenarios against individual endpoints or batches of deployments.

• A generic scenario framework (src/scenario.rs) built around AppType and Scenario.

• The first compliance scenario (src/setup_connection/), organized as the template for future scenarios.

• TOML-based batch execution (src/config.rs and src/runner.rs).

• GitHub Actions CI running:

  • cargo test --all-targets
  • cargo clippy --all-targets -- -D warnings
  • cargo fmt --all -- --check (nightly)

Adding new scenarios

Adding a new scenario should only require:

1. Creating src/<scenario>/ with a run(endpoint, app_type) entrypoint.
2. Registering it in src/bin/sv2_compliance.rs with Scenario::new(...).

Once registered, it automatically works with both single-endpoint and TOML-based batch execution, and can be filtered with --scenario.

[plebhash]

I'm still exploring things at a very superficial level... just manually trying to run and see what happens

I launched a local SRI Pool and ran:

cargo run -- --endpoint 0.0.0.0:3333 --app-type pool
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.22s
     Running `target/debug/sv2-compliance --endpoint '0.0.0.0:3333' --app-type pool`
Running 1 scenario(s) against 1 target(s)

  ── 0.0.0.0:3333 ──
     testing Pool endpoint at 0.0.0.0:3333
    ── SetupConnection ──
       Happy-path and error-case SetupConnection handshakes
      ✓ SetupConnection (MiningProtocol) (version=2)
      ✓ SetupConnection (TemplateDistributionProtocol) expects rejection
      ✓ SetupConnection (JobDeclarationProtocol) expects rejection


✓ 3/3 tests passed across 1 target(s)

all good

---

but then I killed SRI Pool and tried to run again:

cargo run -- --endpoint 0.0.0.0:3333 --app-type pool
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.27s
     Running `target/debug/sv2-compliance --endpoint '0.0.0.0:3333' --app-type pool`
Running 1 scenario(s) against 1 target(s)

  ── 0.0.0.0:3333 ──
     testing Pool endpoint at 0.0.0.0:3333
    ── SetupConnection ──
       Happy-path and error-case SetupConnection handshakes

thread 'main' panicked at /home/plebhash/.cargo/registry/src/index.crates.io-1949cf8c6b5b557f/integration_tests_sv2-0.4.0/lib/sniffer.rs:190:17:
timeout while waiting for message SetupConnection to go upstream
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace
^C^C^C^C^C

a few observations:

• it took a really long time for the panic (probably ~60s which IIRC is default timeout for integration_tests_sv2::Sniffer)
• process is frozen, I cannot kill it with Ctrl+C

[plebhash]

@lucasbalieiro I spent a few hours for the past few days trying to create a mental model of where this is going

overall it seems to be in an interesting direction

I had a few things I was going to point out on the code diff, but then I decided to ask Kimi K3 (IMHO the best frontier-model available today) to address #1 and see how much it would differ from the direction we're going here

for many pre-requisites, it ended up taking an approach that's very similar to what we have here... which is a solid indicator that there's not too much ambiguity in the design space, and we were already going in the right direction here

but for some other things, it took a different approach... I took time to review those divergences and I feel they're worth consideration (especially encapsulation)

so I'm creating #3 as an alternative to this so we can compare trade-offs

[lucasbalieiro]

closing this in favor #3