feat(besu): add IBFT 2.0 and QBFT light clients

.env.example

@@ -1,4 +1,6 @@
-# Which type of ethereum testnet to run locally (anvil|pos)
+# Which type of ethereum testnet to run locally (anvil|pos|besu-qbft|none)
+# Validated Besu mode for e2e: ETH_TESTNET_TYPE=besu-qbft, ETH_LC_ON_COSMOS=attestor-native,
+# COSMOS_LC_ON_ETH=sp1, SP1_PROVER=mock
 ETH_TESTNET_TYPE="anvil"
 # Preset for Ethereum PoS network configuration (minimal|mainnet)
 ETHEREUM_POS_NETWORK_PRESET="minimal"

.github/workflows/abigen.yaml

@@ -9,15 +9,21 @@ on:
   pull_request:
     paths:
       - 'ibc-solidity/abi/**'
+      - 'ibc-solidity/solidity.just'
       - 'packages/go-abigen/**'
+      - 'e2e/interchaintestv8/types/erc20/**'
       - '**.sol'
       - 'ibc-solidity/bun.lock'
   push:
     branches:
       - main
     paths:
       - 'ibc-solidity/abi/**'
+      - 'ibc-solidity/solidity.just'
       - 'packages/go-abigen/**'
+      - 'e2e/interchaintestv8/types/erc20/**'
+      - '**.sol'
+      - 'ibc-solidity/bun.lock'
 
 jobs:
   check:
@@ -38,16 +44,18 @@ jobs:
       - name: Install abigen
         run: go install github.com/ethereum/go-ethereum/cmd/abigen@be4dc0c4be2fe316dbdd0a73e48421f64978232f # v1.17.2
 
-      - name: Run abigen
+      - name: Generate contract artifacts
         run: just solidity::generate-abi
 
-      - name: Check for diffs in go-abigen
+      - name: Check generated contract artifacts
         run: |
-          if ! git diff --quiet HEAD -- packages/go-abigen; then
-            echo "Git diff found in the selected directory. Failing the job."
+          if [ -n "$(git status --short --untracked-files=all -- ibc-solidity/abi packages/go-abigen e2e/interchaintestv8/types/erc20)" ]; then
+            echo "Generated contract artifacts are stale."
+            git status --short --untracked-files=all -- ibc-solidity/abi packages/go-abigen e2e/interchaintestv8/types/erc20
+            git diff --stat -- ibc-solidity/abi packages/go-abigen e2e/interchaintestv8/types/erc20
             exit 1
           else
-            echo "No changes detected in the selected directory."
+            echo "Generated contract artifacts are current."
           fi
 
   golangci:

.github/workflows/e2e-attestor.yml

@@ -104,7 +104,6 @@ jobs:
       fail-fast: false
       matrix: ${{ fromJson(needs.generate-matrix-eth-to-eth.outputs.matrix) }}
     name: attestor-native/${{ matrix.entrypoint }}/${{ matrix.test }}
-
     runs-on: depot-ubuntu-24.04-4
     permissions:
       contents: read
@@ -121,6 +120,52 @@ jobs:
           cd e2e/interchaintestv8
           go test -v -mod=readonly . -run "^${{ matrix.entrypoint }}$/${{ matrix.test }}$" -timeout 60m
 
+  e2e-besu-qbft:
+    needs: build-e2e-programs
+    name: besu-qbft/ics20-roundtrip
+    env:
+      ETH_TESTNET_TYPE: besu-qbft
+      ETH_LC_ON_COSMOS: attestor-native
+      COSMOS_LC_ON_ETH: sp1
+      SP1_PROVER: mock
+      E2E_PROOF_TYPE: groth16
+    runs-on: depot-ubuntu-24.04-4
+    permissions:
+      contents: read
+      packages: read
+    steps:
+      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5.1.0
+      - name: Set up E2E environment
+        uses: ./.github/actions/e2e-setup
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+      - name: Run test
+        run: |
+          cd e2e/interchaintestv8
+          go test -v -mod=readonly . -run '^TestWithIbcEurekaTestSuite$/^Test_ICS20TransferERC20TokenfromEthereumToCosmosAndBack$' -timeout 60m
+
+  e2e-besu-to-besu:
+    needs: build-e2e-programs
+    name: besu-to-besu
+    runs-on: depot-ubuntu-24.04-4
+    permissions:
+      contents: read
+      packages: read
+    steps:
+      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5.1.0
+      - name: Set up E2E environment
+        uses: ./.github/actions/e2e-setup
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+      - name: Run Go package tests
+        run: |
+          cd e2e/interchaintestv8
+          go test ./e2esuite
+      - name: Run Besu to Besu test suite
+        run: |
+          cd e2e/interchaintestv8
+          go test -v -mod=readonly . -run '^TestWithBesuToBesuTestSuite$' -timeout 60m
+
   e2e-multi-attestor-native:
     needs: build-e2e-programs
     strategy:

AGENTS.md

@@ -0,0 +1,23 @@
+# AGENTS.md
+
+This repo combines Solidity/Foundry contracts, a Rust workspace, Solana Anchor programs, and Go-based end-to-end tooling for IBC Eureka.
+
+Look here first:
+- `README.md`
+- `justfile`
+- `ibc-solidity/foundry.toml`
+- `Cargo.toml`
+- `ibc-solidity/contracts/README.md`
+
+Use the smallest relevant validation from the repo root:
+- Solidity: `just solidity::lint-solidity` and `just solidity::test-foundry`
+- Rust workspace, relayer, operator, and shared packages: `just lint-rust` and `just test-cargo`
+- Broad cross-stack changes: `just lint`
+- Solana or e2e changes: use the subtree-specific commands in `ibc-solana/AGENTS.md` or `e2e/interchaintestv8/AGENTS.md`
+
+Hard constraints:
+- Do not hand-edit generated outputs in `packages/go-abigen/`, most of `packages/go-anchor/`, `e2e/interchaintestv8/solana/go-anchor/`, or protobuf outputs under `e2e/interchaintestv8/types/`; regenerate with `just solidity::generate-abi`, `just solana::generate-solana-types`, or `just generate-buf`.
+- `packages/go-anchor/ics07_tendermint_patches/` is the hand-maintained exception inside `packages/go-anchor/`; preserve it across regeneration.
+- If Solidity interfaces, ABI-exposed structs, or contract types change, run `just solidity::generate-abi` before validating Go or e2e code.
+- If Solana program interfaces or IDLs change, run `just solana::generate-solana-types`.
+- If `.proto` files change, run `just generate-buf`.

Cargo.toml

@@ -20,6 +20,7 @@ members = [
     "packages/proof-api/modules/eth-to-cosmos-compat",
     "packages/proof-api/modules/cosmos-to-eth",
     "packages/proof-api/modules/eth-to-eth",
+    "packages/proof-api/modules/besu-to-eth",
     "packages/proof-api/modules/cosmos-to-cosmos",
     "packages/proof-api/modules/solana-to-cosmos",
     "packages/proof-api/modules/cosmos-to-solana",
@@ -60,6 +61,7 @@ proof-api-eth-to-cosmos        = { path = "packages/proof-api/modules/eth-to-cos
 proof-api-eth-to-cosmos-compat = { path = "packages/proof-api/modules/eth-to-cosmos-compat", default-features = false }
 proof-api-cosmos-to-eth        = { path = "packages/proof-api/modules/cosmos-to-eth", default-features = false }
 proof-api-eth-to-eth           = { path = "packages/proof-api/modules/eth-to-eth", default-features = false }
+proof-api-besu-to-eth          = { path = "packages/proof-api/modules/besu-to-eth", default-features = false }
 proof-api-cosmos-to-cosmos     = { path = "packages/proof-api/modules/cosmos-to-cosmos", default-features = false }
 proof-api-solana-to-cosmos     = { path = "packages/proof-api/modules/solana-to-cosmos", default-features = false }
 proof-api-cosmos-to-solana     = { path = "packages/proof-api/modules/cosmos-to-solana", default-features = false }

README.md

@@ -80,6 +80,8 @@ This project is structured with the following directories:
 | `ICS26Router.sol` | IBC router handles sequencing, replay protection, and timeout checks. Passes proofs to light clients for verification, and resolves `portId` for app callbacks. Provable IBC storage is stored in this contract.  | ✅ |
 | `ICS20Transfer.sol` | IBC transfer application to send and receive tokens to/from another IBC transfer implementation. | ✅ |
 | `SP1ICS07Tendermint.sol` | Tendermint light client powered by SP1. The entry point for SP1 proofs. | ✅ |
+| `BesuIBFT2LightClient.sol` | Besu IBFT 2.0 light client for header-validator mode with weak-subjectivity updates and EVM proof verification, following the YUI + prover sealing-header verification model. | ✅ |
+| `BesuQBFTLightClient.sol` | Besu QBFT light client for header-validator mode with weak-subjectivity updates and EVM proof verification, following the YUI + prover sealing-header verification model. | ✅ |
 | `ICS27GMP.sol` | IBC General Message Passing via Interchain Accounts. | ✅ |
 | `AttestationLightClient.sol` | The multisig contract implementing IBC Light Client specs. | ✅ |
 | `utils/IFTBaseUpgradeable.sol` | Interchain Fungible Token standard. Mint and burn alternative to ICS-20. | ⏳ |
@@ -316,6 +318,7 @@ Note: These gas benchmarks are with Groth16.
 IBC is a peer-to-peer, light-client-based interoperability protocol. This repository contains the following light clients:
 
 - **SP1 Tendermint Light Client** – Verifies the consensus state of a Cosmos SDK chain powered by SP1 and `tendermint-rs`. (Solidity)
+- **Besu IBFT 2.0 / QBFT Light Clients** – Verify Besu BFT headers in header-validator mode, track the counterparty `ICS26Router` account storage root, and verify EVM account/storage proofs for Eureka commitments. (Solidity)
 - [**Ethereum Light Client**](./ibc-solidity/programs/cw-ics08-wasm-eth/README.md) – Verifies the consensus state of the Ethereum chain. (CosmWasm)
 - **Attestation Light Client** – A multisig that can be used if the counterparty chain does not have a light client protocol. (Solidity and Solana)
 - **Solana Tendermint Light Client** - Verifies the consensus state of a Cosmos SDK chain powered by `tendermint-rs`. (Solana)

e2e/interchaintestv8/AGENTS.md

@@ -0,0 +1,21 @@
+# AGENTS.md
+
+This subtree contains the Go end-to-end test suites that drive local Ethereum, Cosmos, and Solana environments through interchaintest.
+
+Look here first:
+- `e2e/interchaintestv8/README.md`
+- `e2e/interchaintestv8/go.mod`
+- the relevant suite entrypoint (`ibc_eureka_test.go`, `relayer_test.go`, `sp1_ics07_test.go`, `solana_test.go`, etc.)
+
+Use the smallest relevant validation from the repo root:
+- Single targeted test: `just test-e2e TestWithSuite/Test_Name`
+- Common wrappers: `just test-e2e-eureka`, `just test-e2e-relayer`, `just test-e2e-cosmos-relayer`, `just test-e2e-sp1-ics07`
+- Solana e2e wrappers: `just test-e2e-solana`, `just test-e2e-solana-gmp`, `just test-e2e-solana-ift`, `just test-e2e-solana-upgrade`, `just test-e2e-solana-attestation`
+- Go lint for this subtree lives in `just lint-go`; see `justfile` for the other suite wrappers
+
+Local constraints:
+- Prefer the smallest targeted test; full e2e runs are slow and environment-dependent.
+- Local runs expect `.env` set up from `.env.example`; `just test-e2e` installs the relayer, and `just test-e2e-sp1-ics07` also installs the operator.
+- If contract interfaces or ABI-exposed types change, run `just generate-abi` before e2e validation.
+- If Solana IDLs change, run `just generate-solana-types`; if `.proto` files change, run `just generate-buf`.
+- Do not hand-edit generated code under `e2e/interchaintestv8/types/` or `e2e/interchaintestv8/solana/go-anchor/`.

e2e/interchaintestv8/README.md

@@ -8,6 +8,8 @@ These end to end tests are designed to run in the CI, but you can also run them
 
 ### Prerequisites
 
+Besu tests additionally require Docker Compose v2 (`docker compose`).
+
 In the repo root:
 
 ```
@@ -29,3 +31,65 @@ just test-e2e TestWithIbcEurekaTestSuite/Test_Deploy
 # Alternatively:
 just test-e2e-eureka Test_Deploy
 ```
+
+## Besu QBFT mode
+
+Set `ETH_TESTNET_TYPE=besu-qbft` to start a real 4-validator Besu QBFT network.
+
+### Supported in this mode
+
+This pass supports the following Besu configuration:
+
+- `ETH_TESTNET_TYPE=besu-qbft`
+- `ETH_LC_ON_COSMOS=attestor-native`
+- `COSMOS_LC_ON_ETH=sp1`
+- `SP1_PROVER=mock`
+
+Validated coverage in this mode:
+
+- Besu chain bring-up and contract deployment
+- Dockerized Ethereum attestors reading Besu RPC
+- relayer startup and client creation
+- full Ethereum ↔ Cosmos ICS20 transfer roundtrip
+
+### Not supported
+
+- `ETH_LC_ON_COSMOS=full`
+- beacon-chain-based Ethereum verification on Cosmos
+
+### Focused local test commands
+
+From the repo root, run:
+
+```shell
+# Full ICS20 roundtrip in the supported Besu mode
+ETH_TESTNET_TYPE=besu-qbft \
+ETH_LC_ON_COSMOS=attestor-native \
+COSMOS_LC_ON_ETH=sp1 \
+SP1_PROVER=mock \
+just test-e2e TestWithIbcEurekaTestSuite/Test_ICS20TransferERC20TokenfromEthereumToCosmosAndBack
+```
+
+## Focused Besu ↔ Besu e2e
+
+This focused suite starts two independent Besu QBFT networks, deploys Eureka contracts on both, starts the Rust relayer with `besu_to_eth` in both directions, deploys and registers Besu light clients on both chains, and verifies a one-way A → B ICS20 transfer plus the B → A acknowledgement relay using real Besu proofs.
+
+### Focused local test commands
+
+From the repo root, run:
+
+```shell
+# Dual-Besu deploy / client-registration path
+just test-e2e TestWithBesuToBesuTestSuite/Test_Deploy
+
+# One-way Besu A -> Besu B ICS20 transfer with acknowledgement relay back to A
+just test-e2e TestWithBesuToBesuTestSuite/Test_ICS20TransferERC20FromChainAToChainB
+
+# Regenerate the QBFT light-client fixture used by test/besu-bft/*
+GENERATE_BESU_LIGHT_CLIENT_FIXTURES=true \
+just test-e2e TestWithBesuToBesuTestSuite/Test_ICS20TransferERC20FromChainAToChainB
+```
+
+When `GENERATE_BESU_LIGHT_CLIENT_FIXTURES=true` is set, the focused Besu↔Besu transfer test writes:
+
+- `ibc-solidity/test/besu-bft/fixtures/qbft.json`

e2e/interchaintestv8/attestor/setup.go

@@ -203,6 +203,7 @@ func SetupAttestors(ctx context.Context, t *testing.T, params SetupParams) Setup
 // chainType should be ChainTypeEvm for PoW chains or ChainTypeCosmos for PoS chains.
 func SetupEthAttestors(ctx context.Context, t *testing.T, client *dockerclient.Client, networkID, ethRPC, ics26Address string, chainType ChainType) SetupResult {
 	t.Helper()
+	require.NotEmpty(t, ethRPC, "Ethereum attestors require a Docker-reachable Ethereum RPC URL")
 	return SetupAttestors(ctx, t, SetupParams{
 		NumAttestors:         testvalues.NumAttestors,
 		KeystorePathTemplate: testvalues.AttestorKeystorePathTemplate,