Refactor protocol flows around Instance and Graph state machines

.github/workflows/ci.yml

@@ -15,6 +15,7 @@ on:
 
 env:
   CARGO_TERM_COLOR: always
+  ZKM_TOOLCHAIN_VERSION: '20260917'
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
@@ -61,6 +62,7 @@ jobs:
           java -jar "$JAR" -config GraphLifecycleFixed.cfg GraphLifecycle.tla
           java -jar "$JAR" -config GraphLifecycleFineGrainedFixed.cfg GraphLifecycleFineGrainedFixed.tla
           java -jar "$JAR" -config InstancePresignedFixed.cfg InstancePresigned.tla
+          java -jar "$JAR" -config InstanceLifecycle.cfg InstanceLifecycle.tla
           java -jar "$JAR" -config Take2DisproveRace.cfg Take2DisproveRace.tla
           java -jar "$JAR" -config MultiActorRace.cfg MultiActorRace.tla
           java -jar "$JAR" -config InstanceBridgeOutRaceFixed.cfg InstanceBridgeOutRace.tla
@@ -141,10 +143,21 @@ jobs:
         timeout-minutes: 30
         with:
           profile: minimal
-          toolchain: nightly-2025-12-11
+          toolchain: nightly-2026-09-17
           override: true
           components: clippy
-      - run: curl --proto '=https' --tlsv1.2 -sSf https://raw.githubusercontent.com/ProjectZKM/toolchain/refs/heads/main/setup.sh | sh
+      - name: Install Ziren toolchain
+        run: |
+          set -euo pipefail
+          installer="$RUNNER_TEMP/zkmup"
+          curl --proto '=https' --tlsv1.2 -fsSL --retry 3 \
+            https://raw.githubusercontent.com/ProjectZKM/toolchain/582f7927cac0668883a86cbd02fbc18b500b1b6f/zkmup \
+            -o "$installer"
+          sh "$installer" install -v "$ZKM_TOOLCHAIN_VERSION"
+          SHELL=/bin/true sh "$installer" setup -v "$ZKM_TOOLCHAIN_VERSION"
+          source "$HOME/.zkm-toolchain/env"
+          rustc --version
+          cargo --version
       - name: Install Dependencies
         run: sudo apt update && sudo apt install protobuf-compiler
       - run: |
@@ -154,14 +167,20 @@ jobs:
     name: Cargo Test
     needs: tla-plus
     runs-on: ubuntu-latest
-    strategy:
-      matrix:
-        toolchain:
-          - nightly-2025-12-11
     steps:
       - uses: actions/checkout@v5
       - name: Install Ziren toolchain
-        run: curl --proto '=https' --tlsv1.2 -sSf https://raw.githubusercontent.com/ProjectZKM/toolchain/refs/heads/main/setup.sh | sh
+        run: |
+          set -euo pipefail
+          installer="$RUNNER_TEMP/zkmup"
+          curl --proto '=https' --tlsv1.2 -fsSL --retry 3 \
+            https://raw.githubusercontent.com/ProjectZKM/toolchain/582f7927cac0668883a86cbd02fbc18b500b1b6f/zkmup \
+            -o "$installer"
+          sh "$installer" install -v "$ZKM_TOOLCHAIN_VERSION"
+          SHELL=/bin/true sh "$installer" setup -v "$ZKM_TOOLCHAIN_VERSION"
+          source "$HOME/.zkm-toolchain/env"
+          rustc --version
+          cargo --version
       - name: Install Dependencies
         run: sudo apt update && sudo apt install protobuf-compiler
       - name: Launch the Regtest

.github/workflows/e2e_localnet.yml

@@ -0,0 +1,70 @@
+name: Localnet e2e
+
+# The whole localnet e2e suite (localnet/README.md, localnet/e2e/README.md) on the self-hosted
+# bitvm2-node runner: build the mock-gc binaries, rebuild a private localnet, run all 13 cases.
+# ~2 h per run, so it is not a PR gate: same triggers as ci_time_consuming.yml.
+
+on:
+  push:
+    branches: ["main", "dev"]
+  workflow_dispatch:
+
+# One CI localnet per host: queue runs, never cancel one that is half way through.
+concurrency:
+  group: localnet-e2e
+  cancel-in-progress: false
+
+env:
+  CARGO_TERM_COLOR: always
+  # A localnet of its own next to any other on the host (ports PORT_BASE+0..999).
+  LOCALNET_DATA: /data/actions-runner-bitvm2-node/cache/localnet-e2e/data
+  PORT_BASE: "25000"
+  COMPOSE_PROJECT: bvci
+  # Dedicated target dir, kept between runs; only this workflow builds into it.
+  CARGO_TARGET_DIR: /data/actions-runner-bitvm2-node/cache/localnet-e2e/target
+
+jobs:
+  e2e:
+    name: Localnet e2e
+    runs-on: [self-hosted, bitvm2-node]
+    timeout-minutes: 210
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          submodules: recursive
+
+      - name: Build the mock-gc binaries
+        run: |
+          # results of earlier runs stay in the data dir: keep the last 10, never report a stale one
+          mkdir -p "$LOCALNET_DATA/results"
+          rm -f "$LOCALNET_DATA/results/latest"
+          find "$LOCALNET_DATA/results" -mindepth 1 -maxdepth 1 -type d | sort | head -n -10 | xargs -r rm -rf
+          localnet/build.sh
+
+      - name: Reset the localnet
+        run: make localnet-reset
+
+      - name: Run the e2e suite
+        run: make e2e
+
+      - name: Report
+        if: always()
+        run: |
+          run=$(readlink -f "$LOCALNET_DATA/results/latest" 2>/dev/null || true)
+          [ -d "$run" ] || run=""
+          echo "E2E_RESULTS=$run" >> "$GITHUB_ENV"
+          if [ -f "$run/report.md" ]; then cat "$run/report.md" >> "$GITHUB_STEP_SUMMARY"; else echo "no e2e report" >> "$GITHUB_STEP_SUMMARY"; fi
+
+      - name: Stop the localnet
+        if: always()
+        run: |
+          localnet/scripts/chaos.sh reset || true
+          localnet/scripts/down.sh infra
+
+      - name: Upload the results
+        if: always() && env.E2E_RESULTS != ''
+        uses: actions/upload-artifact@v4
+        with:
+          name: localnet-e2e-${{ github.run_id }}
+          path: ${{ env.E2E_RESULTS }}
+          retention-days: 14

.github/workflows/release.yml

@@ -80,7 +80,6 @@ jobs:
             "target/release/send-rbf"
             "target/release/pegin-request"
             "target/release/pegout"
-            "target/release/update-db"
           )
 
           if [ "${{ runner.os }}" = "Linux" ]; then

.gitignore

@@ -41,4 +41,13 @@ local_docs/
 local_scripts/
 scripts/testnet/
 scripts/devnet/
-*.DS_Store
+*.DS_Store
+# localnet state (default LOCALNET_DATA) and build artifacts of its tooling
+localnet/.local/
+localnet/subgraph/gateway/node_modules/
+localnet/subgraph/gateway/build/
+localnet/subgraph/gateway/generated/
+localnet/contracts-local/out/
+localnet/contracts-local/cache/
+localnet/contracts-local/broadcast/
+localnet/tools/__pycache__/

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "localnet/contracts"]
+	path = localnet/contracts
+	url = https://github.com/KSlashh/bitvm-L2-contracts.git

Cargo.toml

@@ -10,6 +10,7 @@ members = [
     "crates/cbft-rpc",
     "crates/bitvm-gc",
     "crates/store",
+    "crates/engine",
     "crates/node-macros",
     "crates/client",
     "crates/util",
@@ -118,6 +119,7 @@ soldering-host = { git = "https://github.com/GOATNetwork/bitvm-gc", features = [
 #garbled-snark-verifier = { path = "../bitvm-gc/garbled-snark-verifier"}
 #soldering-host = { path = "../bitvm-gc/babe-programs/soldering/host" }
 store = { path = "crates/store" }
+engine = { path = "crates/engine" }
 util = { path = "crates/util" }
 client = { path = "crates/client" }
 bitcoin-light-client-circuit = { path = "circuits/crates/bitcoin-light-client-circuit" }

Makefile

@@ -0,0 +1,27 @@
+# Repo-level shortcuts for the local mock testnet under localnet/ (see localnet/README.md).
+# Every target honours LOCALNET_DATA, PORT_BASE and COMPOSE_PROJECT from the environment, e.g.
+#   LOCALNET_DATA=/tmp/bv2 PORT_BASE=23000 COMPOSE_PROJECT=bvlocal2 make localnet-reset
+LOCALNET := localnet
+
+.PHONY: localnet-build localnet-up localnet-down localnet-reset localnet-status e2e-smoke e2e
+
+localnet-build:        ## build the mock-gc node + helper binaries into the repo target
+	$(LOCALNET)/build.sh
+
+localnet-up:           ## adopt / start an existing localnet (infra, miner, proof builder, 5 nodes)
+	$(LOCALNET)/scripts/up.sh
+
+localnet-down:         ## stop nodes + support processes (infra keeps running; `scripts/down.sh infra` stops it too)
+	$(LOCALNET)/scripts/down.sh
+
+localnet-reset:        ## DESTRUCTIVE: wipe $(LOCALNET_DATA) and rebuild chains, contracts, subgraph, nodes
+	$(LOCALNET)/scripts/reset.sh --yes
+
+localnet-status:
+	$(LOCALNET)/scripts/status.sh
+
+e2e-smoke:             ## peg-in, peg-out and challenge/take-2 happy paths (~20 min)
+	$(LOCALNET)/e2e/run.sh pegin_happy pegout_happy challenge_take2
+
+e2e:                   ## the whole suite (~110 min)
+	$(LOCALNET)/e2e/run.sh

README.md

@@ -9,6 +9,8 @@ GOAT Network's BitVM bridge implementation. See [GOAT BitVM Whitepaper](https://
 - `proof-builder-rpc/`: RPC server for offloading proof generation to a separate process
 - `crates/`: Shared Rust crates for common types and utilities
 - `deployment`: Deployment scripts and documentation
+- `scripts/ops/`: Read-only operator helpers for a running node (health triage, log queries, instance / graph traces)
+- `localnet/`: clone-and-run mock testnet (five `mock-gc` nodes on regtest + anvil + graph-node) and the on-demand e2e suite, see [localnet/README.md](localnet/README.md); `make localnet-reset`, `make e2e-smoke`
 
 
 ## Formal verification (TLA+)

crates/bitvm-gc/Cargo.toml

@@ -22,11 +22,17 @@ ark-bn254 = { workspace = true }
 ark-groth16 = { workspace = true }
 ark-serialize = { workspace = true }
 ark-ff = { workspace = true }
+ark-ec = { workspace = true }
 verifiable-circuit-babe = { workspace = true }
 garbled-snark-verifier = { workspace = true }
 soldering-host = { workspace = true }
 rayon = { workspace = true }
 
+# Only needed by the compile-time `mock-gc` feature, to wrap the mocked soldered
+# output in a structurally-real `ZKMProofWithPublicValues` so the node's payload
+# plumbing (compact/expand, SolderingProof::output) keeps working unchanged.
+zkm-sdk = { workspace = true, optional = true }
+
 serde-big-array = { workspace = true }
 serde_json = { workspace = true }
 bincode.workspace = true
@@ -46,3 +52,6 @@ tokio = { workspace = true, features = ["macros", "time"] }
 [features]
 default = []
 ci-tests = []
+# Replace the real BABE/GC/soldering machinery with deterministic, on-chain-valid
+# mocks. Localnet only. See node feature `mock-gc` which forwards to this one.
+mock-gc = ["dep:zkm-sdk"]