> ## Documentation Index
> Fetch the complete documentation index at: https://docs.polygon.technology/llms.txt
> Use this file to discover all available pages before exploring further.
# CDK Besu
> Run a Hyperledger Besu chain with QBFT consensus, connected to Agglayer through pessimistic proofs, using the public cdk-besu runbook.
CDK Besu runs a [Hyperledger Besu](https://github.com/hyperledger/besu) chain with QBFT consensus (Besu's Byzantine fault tolerant proof-of-authority consensus) and connects it to Agglayer. It is the Besu-based alternative to the OP Stack execution clients, op-geth and op-reth, and fits chains where a known set of validators operates a private ledger.
The step-by-step deployment procedure is maintained in the public [`0xPolygon/cdk-besu`](https://github.com/0xPolygon/cdk-besu) runbook. This page explains what the runbook deploys, how it differs from CDK op-reth, and which runbook chapter covers each step.
## Scope
The `cdk-besu` runbook covers one deployment path: sovereign mode, secured by pessimistic proofs, with the `AggchainECDSAMultisig` consensus contract. It targets devnets, testnets, and production networks that settle on Sepolia or Ethereum mainnet, and includes an optional configuration for a chain operated jointly by a consortium.
The runbook creates a new chain with the Agglayer bridge and Global Exit Root (GER) contracts in its genesis. Connecting an existing chain with its own history follows the Agglayer Outpost path, which the runbook does not cover.
## Security model
The pessimistic proof protects the shared bridge. It proves that the chain cannot withdraw more than it deposited, which caps the damage a faulty or compromised chain can do to the rest of the Agglayer network.
The pessimistic proof does not prove the chain's internal state transitions, and a CDK Besu chain posts no transaction data to L1. The chain's state lives on the operator's validators. For a private ledger this is the intended design; confirm it matches your requirements before you deploy.
## Architecture
A CDK Besu chain combines Besu nodes with the same Agglayer components used by other CDK chains:
| Component | Role |
| - | - |
| Besu validators | Propose and finalize blocks with QBFT. |
| Besu RPC node | Serves JSON-RPC to users, aggkit, and the bridge service so the validators stay off the public network. |
| [aggkit](https://github.com/agglayer/aggkit) (aggoracle) | Writes GERs to the L2. |
| [aggkit](https://github.com/agglayer/aggkit) (aggsender) | Builds certificates and submits them to the Agglayer node. |
| aggkit (aggsender validators) | Optional. Approve certificates in a consortium before the aggsender submits them. |
| [zkevm-bridge-service](https://github.com/0xPolygon/zkevm-bridge-service) | Indexes bridge events on L1 and L2 and submits claims on L2. |
| Agglayer node | Requests the pessimistic proof, generated with SP1 on the Succinct Prover Network, and settles the certificate on L1. |
```mermaid theme={null}
flowchart LR
User((User))
L1[L1]
SPN[Succinct Prover Network]
subgraph BESU[Besu]
besurpc[Besu RPC node]
besuval[Besu validators, QBFT]
end
subgraph STACK[Agglayer components]
aggkit[aggkit]
aggval[aggsender validators, optional]
bridge[bridge service]
agglayer[Agglayer node]
end
User -->|1. Submit transaction| besurpc
besurpc -->|2. Propose and finalize block| besuval
aggkit -->|3. Set GER| besurpc
aggkit -->|4. Collect certificate signatures| aggval
aggkit -->|5. Submit certificate| agglayer
agglayer -->|6. Request pessimistic proof| SPN
agglayer -->|7. Submit settlement transaction| L1
bridge -.->|Read bridge events| L1
bridge -.->|Read bridge events| besurpc
```
aggkit and the bridge service also read GER and bridge events from L1 and the Besu RPC node continuously. Step 4 applies only to the consortium configuration.
## How CDK Besu differs from CDK op-reth
| Area | CDK op-reth | CDK Besu |
| - | - | - |
| Execution and consensus | `op-reth` plus `op-node` | One Besu node per validator, QBFT consensus |
| L1 data posting | `op-batcher` | None |
| Consensus contracts | `AggchainECDSAMultisig` (pessimistic proof), `AggchainFEP` (FEP) | `AggchainECDSAMultisig` (pessimistic proof) only |
| L2 contract deployment | `op-deployer` | None; the sovereign bridge and GER contracts are predeployed in the Besu genesis |
| Block finality tags | `safe` and `finalized` advance through `op-node` | Not served; aggkit tracks `latest` |
| Minimum aggkit version | Per the `cdk-op-reth` version table | 0.9 |
| Consortium configuration | Not covered | Covered in the runbook |
## Before you deploy
These Besu-specific requirements affect planning. The runbook explains each one in detail.
* **Use aggkit 0.9 or later.** Earlier versions recompute L2 block hashes in a way that never matches a QBFT block hash, so aggkit never builds a certificate.
* **Track the `latest` block.** QBFT finalizes each block when it is produced, and Besu returns error `-39001` for the `safe` and `finalized` tags. Set every aggkit block finality setting to `LatestBlock`.
* **Size the validator set for fault tolerance.** QBFT tolerates `f` faulty validators with at least `3f + 1` validators. A single validator works for devnets, but one failure halts the chain; use four or more validators for testnet and mainnet.
* **Run a separate RPC node.** aggkit, the bridge service, and users connect to the RPC node. Add their hostnames to the node's `--host-allowlist`.
* **Register the aggsender as the first signer.** During rollup initialization, the first entry in the `AggchainECDSAMultisig` signer list must be the aggsender address, or the aggsender refuses to send certificates.
* **Apply account permissioning on every node.** If you enable a Besu account allowlist, add the aggoracle and ClaimTxManager addresses before starting aggkit and the bridge service, and apply the same allowlist on every validator and RPC node.
The runbook pins the tested versions of Besu, `agglayer-contracts`, aggkit, and `zkevm-bridge-service` in its [Prerequisites](https://github.com/0xPolygon/cdk-besu/blob/main/00-prerequisites.md) chapter. Keep your deployment in step with those versions.
## Consortium configuration
When several organizations operate one chain, the runbook uses two independent controls so that no single member can produce blocks or settle a certificate alone:
* **Shared block production.** Each member runs its own QBFT validator and keeps its own validator key. Membership changes go through a QBFT validator vote.
* **Shared certificate approval.** `AggchainECDSAMultisig` requires M of N registered signers to approve each certificate. One member runs the proposing aggsender, and each other member runs an aggsender validator that checks the certificate against its own view of the chain.
See [Consortium Configuration](https://github.com/0xPolygon/cdk-besu/blob/main/07-consortium-configuration.md) for the key handling, signer configuration, permissioning, and operational agreements members need before launch.
## Runbook chapters
| Chapter | What it covers |
| - | - |
| [Prerequisites](https://github.com/0xPolygon/cdk-besu/blob/main/00-prerequisites.md) | Supported L1s, host tooling, component versions, secrets handling, and wallet accounts to fund. |
| [Rollup creation](https://github.com/0xPolygon/cdk-besu/blob/main/01-rollup-creation.md) | Starting the Agglayer chain integration process to receive the `combined.json` deployment artifact. |
| [Genesis generation](https://github.com/0xPolygon/cdk-besu/blob/main/02-genesis.md) | Generating the sovereign bridge and GER predeploys with `createSovereignGenesis`. |
| [Besu network deployment](https://github.com/0xPolygon/cdk-besu/blob/main/03-besu-network.md) | Building the QBFT genesis, starting the validators and RPC node, and configuring permissioning. |
| [Rollup initialization](https://github.com/0xPolygon/cdk-besu/blob/main/04-rollup-initialization.md) | Initializing the rollup on L1 with the `AggchainECDSAMultisig` parameters. |
| [Polygon stack deployment](https://github.com/0xPolygon/cdk-besu/blob/main/05-polygon-stack.md) | Configuring and running aggkit and the zkEVM Bridge Service against Besu. |
| [Verification and operations](https://github.com/0xPolygon/cdk-besu/blob/main/06-verification-and-operations.md) | Confirming the chain settles on Agglayer, then monitoring, validator set changes, upgrades, and key rotation. |
| [Consortium configuration](https://github.com/0xPolygon/cdk-besu/blob/main/07-consortium-configuration.md) | Sharing block production and certificate approval across several organizations. Consortium chains only. |
## Resources
The canonical step-by-step deployment guide for CDK Besu chains.
The end-to-end sequence from intake to a live chain on Agglayer.
Agglayer endpoints and L1 contract addresses for Bali, Cardona, and Mainnet.
Upstream reference for QBFT genesis options and validator management.