# BaseHub — full content
> BaseHub — reference for agents on Base. Full Markdown corpus, concatenated. 232 pages. See /llms.txt for the index.
Source: https://basehub.org
Index: https://basehub.org/llms.txt
---
# B20 Invariants and Conformance Tests
Source: https://basehub.org/api-reference/b20-invariants/
Description: The behavioral guarantees the B20 precompiles hold to, and the conformance scenarios that exercise each one.
import { Aside } from '@astrojs/starlight/components';
The [B20 precompile reference](/api-reference/b20-precompiles/) tells you what each call looks like on the wire. This page covers the other half: the properties the implementation promises to hold, whatever order you make those calls in, plus the scenarios used to check them.
Treat the list below as normative. An implementation that breaks any line here is wrong, not merely surprising. Read it alongside the [B20 Native Token Standard](/specifications/b20/) writeup for the reasoning behind each rule.
## Invariants
### Policy registry
1. No pairing of `policyId` and `account` can make `isAuthorized` revert.
2. A `BLOCKLIST` policy that was never created clears every account. The same query against an uncreated `ALLOWLIST` denies every account.
3. Once `renounceAdmin(policyId)` runs, every call that would alter that policy's membership reverts, permanently.
4. `ALWAYS_ALLOW`, at ID `0`, passes every account, and `ALWAYS_BLOCK` rejects every account. Both are fixed points — neither can be created, edited, nor renounced.
5. Policy IDs never repeat, and within a single `PolicyType` prefix they only climb.
### Roles
6. Neither `renounceRole` nor `revokeRole` will strip the final `DEFAULT_ADMIN_ROLE` holder. `renounceLastAdmin()` is the only exit.
7. After `renounceLastAdmin()` lands, `DEFAULT_ADMIN_ROLE` is unreachable — no address can ever hold it again.
8. Roles granted before the admin stepped down keep working after.
9. A custom role means nothing on its own. No B20 operation consults one.
### Transfer policies
10. Policy gating never applies to `approve`.
11. `TRANSFER_EXECUTOR_POLICY` is consulted on `transferFrom` only. A direct `transfer` never reaches it.
12. `MINT_RECEIVER_POLICY` holds at all times, factory `initCalls` included.
13. All three transfer-side scopes stand down while `initCalls` execute.
14. Every scope points at `ALWAYS_ALLOW` the moment a token is created.
### Supply
15. `totalSupply` cannot climb past the supply cap.
16. A cap cannot be lowered under the prevailing `totalSupply`.
17. Burning pulls `totalSupply` down, which opens headroom beneath the cap.
### Pause
18. Each `PausableFeature` stands alone. Pausing one leaves the others running.
19. Pause state never reaches `approve` or `permit`.
20. A pause survives factory `initCalls` rather than being bypassed by them.
### Memos
21. The `Memo` event sits at exactly `logIndex + 1` relative to the `Transfer` it annotates.
22. A memo method matches its plain counterpart in every respect but the extra event.
### Permit
23. `permit` accepts ECDSA signatures alone. An ERC-1271 contract signature always fails.
24. A single nonce step follows every `permit` that verifies — the owner's counter moves up by one, never more.
25. A permit signed ahead of `updateName` stops verifying once the name changes.
### Variants
26. An Asset fixes its decimals at creation and cannot revisit them. Anything outside 6 through 18 is rejected.
27. Every Stablecoin reports `6` decimals; the value is not configurable.
28. `OPERATOR_ROLE` exists on Asset tokens and nowhere else.
29. An announcement ID is spent once across the token's entire life.
30. A Stablecoin's currency code is immutable, and only `A`–`Z` characters are legal in it.
31. A multiplier update reaches every holder at the same moment.
32. `batchMint` runs `MINT_RECEIVER_POLICY` against each recipient on its own.
### Factory
33. Deployment is deterministic — identical inputs always land on an identical address.
34. Read position 10 of any B20 address and the variant byte there will name the variant actually deployed.
35. A `(deployer, variant, salt)` tuple has exactly one address it can ever produce.
36. Array order governs `initCalls` execution, and a single revert anywhere in the sequence rolls back the deployment entire.
## Conformance test cases
### Policy registry
| # | Scenario | Expected |
|---|----------|----------|
| 1 | Create a `BLOCKLIST` policy, query an account that is not on it | `isAuthorized` returns `true` |
| 2 | Add that account to the blocklist and query again | `isAuthorized` returns `false` |
| 3 | Take it back off the blocklist and query again | `isAuthorized` returns `true` |
| 4 | Create an `ALLOWLIST` policy, query an account that is not listed | `isAuthorized` returns `false` |
| 5 | Query a blocklist-prefixed ID that was never created | Returns `true` |
| 6 | Query an allowlist-prefixed ID that was never created | Returns `false` |
| 7 | Call `renounceAdmin`, then attempt `updateBlocklist` | Reverts |
| 8 | Call `finalizeUpdateAdmin` from an address that is not pending | Reverts |
### Roles
| # | Scenario | Expected |
|---|----------|----------|
| 9 | Grant `MINT_ROLE`, then call `mint` | Succeeds |
| 10 | Call `mint` with no `MINT_ROLE` held | Reverts |
| 11 | With a single admin left, call `revokeRole(DEFAULT_ADMIN_ROLE)` | Reverts with `LastAdminCannotRenounce` |
| 12 | Call `renounceLastAdmin()` | Succeeds — the token is left admin-less |
| 13 | A `MINT_ROLE` holder calls `mint` after `renounceLastAdmin` | Succeeds — non-admin roles survive |
| 14 | Deploy with `initialAdmin == address(0)`, then call `grantRole` | Reverts |
### Transfer policies
| # | Scenario | Expected |
|---|----------|----------|
| 15 | A blocklisted sender calls `transfer` | Reverts with `PolicyForbids` |
| 16 | That same blocklisted sender calls `approve` | Succeeds |
| 17 | `transferFrom` where the executor sits on the executor blocklist | Reverts |
| 18 | Direct `transfer` by a sender on the executor blocklist but not the sender blocklist | Succeeds |
| 19 | Transfer from a blocklisted sender during `initCalls` | Succeeds — the scope is relaxed |
| 20 | Mint to a receiver on the mint-receiver blocklist during `initCalls` | Reverts — this scope is never relaxed |
### Mint and supply cap
| # | Scenario | Expected |
|---|----------|----------|
| 21 | Mint an amount that would carry `totalSupply` over the cap | Reverts with `SupplyCapExceeded` |
| 22 | Mint exactly up to the cap | Succeeds |
| 23 | Call `updateSupplyCap` with a value under the current `totalSupply` | Reverts with `InvalidSupplyCap` |
| 24 | Burn some supply, then mint back up to the cap | Succeeds |
| 25 | Mint while `MINT` is paused | Reverts |
### Burn and seize
| # | Scenario | Expected |
|---|----------|----------|
| 26 | `burnBlocked` against a frozen account | Succeeds |
| 27 | `burnBlocked` against an account that is not frozen | Reverts |
| 28 | `burnBlocked` called by a `BURN_ROLE` holder lacking `BURN_BLOCKED_ROLE` | Reverts |
| 29 | Freeze an account, seize the full balance, re-mint to a recovery address | Succeeds |
| 30 | Burn while `BURN` is paused | Reverts |
### Pause
| # | Scenario | Expected |
|---|----------|----------|
| 31 | Pause `TRANSFER`, then call `transfer` | Reverts |
| 32 | Pause `TRANSFER`, then call `mint` | Succeeds |
| 33 | Pause `TRANSFER`, then call `approve` | Succeeds |
| 34 | A pauser calls `unpause` without holding `UNPAUSE_ROLE` | Reverts |
### Memos
| # | Scenario | Expected |
|---|----------|----------|
| 35 | Call `transferWithMemo` | Emits `Transfer`, then `Memo` at consecutive log indices |
| 36 | Call `transferFromWithMemo` | `Memo.caller` carries `msg.sender`, not `from` |
| 37 | Call plain `transfer` | No `Memo` event appears |
### Permit
| # | Scenario | Expected |
|---|----------|----------|
| 38 | Submit a permit with a sound signature, nonce, and deadline | Succeeds |
| 39 | Submit a permit whose deadline has passed | Reverts |
| 40 | Replay a permit signature that was already spent | Reverts |
| 41 | Sign a permit before `updateName`, submit it after | Reverts |
| 42 | Submit a contract wallet signature (ERC-1271) | Reverts |
| 43 | Submit a permit while `TRANSFER` is paused | Succeeds |
### Factory
| # | Scenario | Expected |
|---|----------|----------|
| 44 | Call `getB20Address`, then deploy with the same parameters | The two addresses match |
| 45 | Read byte 10 of a deployed Asset address | Returns `0x00` |
| 46 | Deploy the same `(deployer, variant, salt)` a second time | The second attempt reverts |
| 47 | Deploy a variant whose feature is not yet activated | Reverts |
| 48 | An `initCall` pauses `TRANSFER`, a later `initCall` transfers | The transfer reverts |
### Variants
| # | Scenario | Expected |
|---|----------|----------|
| 49 | Deploy an Asset with `decimals = 5` | Reverts |
| 50 | Set the multiplier to `2e18`, read `balanceOf` for a raw balance of 100 | Returns 200 |
| 51 | Reuse an announcement ID | Reverts with `DuplicateAnnouncementId` |
| 52 | Call `batchMint` where one recipient is off the allowlist | Reverts |
| 53 | Deploy a Stablecoin with `currency = "usd"` | Reverts — the code must be `A`–`Z` |
## Related pages
- [B20 Precompile Reference](/api-reference/b20-precompiles/) — selectors, `topic0` values, and revert codes.
- [B20 Native Token Standard](/specifications/b20/) — the behavioral writeup these invariants formalize.
- [Tokenized Stocks](/integration-guides/tokenized-stocks/) — one applied configuration of the standard.
---
# B20 Precompile Reference
Source: https://basehub.org/api-reference/b20-precompiles/
Description: Selector-level reference for the B20 token, Asset and Stablecoin variants, factory, policy registry, and activation registry precompiles.
import { Aside } from '@astrojs/starlight/components';
This page is the call-level companion to the [B20 Native Token Standard](/specifications/b20/) writeup. That page explains how the standard behaves; this one gives you the wire details — every function with its four-byte selector, every event with its `topic0`, and every revert with the selector you'll see come back.
## Precompile addresses
The same three addresses apply on every network that has B20 turned on.
| Surface | Address |
|---|---|
| B20Factory | `0xB20f000000000000000000000000000000000000` |
| ActivationRegistry | `0x8453000000000000000000000000000000000001` |
| PolicyRegistry | `0x8453000000000000000000000000000000000002` |
## IB20
The base token surface. Every B20 token exposes it, whichever variant it was created as.
### Role identifiers
| Function | Selector | What it returns |
|---|---|---|
| `DEFAULT_ADMIN_ROLE` | `0xa217fddf` | The top-level admin role, which is `bytes32(0)`. Holders can manage the role graph, policy slots, and the supply cap. |
| `MINT_ROLE` | `0xe9a9c850` | The role a caller needs for `mint` and `mintWithMemo`. |
| `BURN_ROLE` | `0xb930908f` | The role a caller needs for `burn` and `burnWithMemo`. |
| `BURN_BLOCKED_ROLE` | `0x32ad9be8` | The role behind the deprecated `burnBlocked` path, kept for older integrations. |
| `SEIZE_ROLE` | `0x3c7e9ba5` | The role a caller needs for `seizeWithMemo`. |
| `PAUSE_ROLE` | `0x389ed267` | The role a caller needs for `pause`. |
| `UNPAUSE_ROLE` | `0x309756fb` | The role a caller needs for `unpause`. |
| `METADATA_ROLE` | `0x38841782` | The role behind `updateName`, `updateSymbol`, and `updateContractURI`. |
### Policy scope identifiers
Each of these names one slot on the token. The slot holds a `uint64` policy ID, and the token consults it against the account listed below.
| Function | Selector | Account checked |
|---|---|---|
| `TRANSFER_SENDER_POLICY` | `0xd116fc21` | `from`, on every transfer — `transferFrom` included. |
| `TRANSFER_RECEIVER_POLICY` | `0x210f521b` | `to`, on every transfer. |
| `TRANSFER_EXECUTOR_POLICY` | `0x724e9c53` | `msg.sender` on `transferFrom`, but only where it differs from `from`. From Denim, `msg.sender` on every transfer path, `transfer` included ([details](/integration-guides/b20-issuer-operations/#limit-who-may-initiate-transfers)). |
| `MINT_RECEIVER_POLICY` | `0x6e5b013d` | `to`, on every mint. |
| `SEIZE_EXEMPT_POLICY` | `0xfeb346ec` | `from`, when `seizeWithMemo` runs. |
| `SEIZE_RECEIVER_POLICY` | `0xb31da27f` | `to`, when `seizeWithMemo` runs. |
### ERC-20 surface
| Function | Selector | Behavior |
|---|---|---|
| `name` | `0x06fdde03` | The token name. Fixed at creation, but `updateName` can change it later. |
| `symbol` | `0x95d89b41` | The token symbol. Fixed at creation, but `updateSymbol` can change it later. |
| `decimals` | `0x313ce567` | The decimal count. Each variant fixes this and it never moves. |
| `totalSupply` | `0x18160ddd` | How much of the token is in circulation right now. |
| `balanceOf` | `0x70a08231` | The balance held by `account`. |
| `allowance` | `0xdd62ed3e` | How much `spender` is still cleared to move on behalf of `owner`. |
| `transfer` | `0xa9059cbb` | Moves `amount` from the caller to `to`, emitting `Transfer`. |
| `transferFrom` | `0x23b872dd` | Moves `amount` from `from` to `to`, drawing on the caller's allowance. Emits `Transfer`. |
| `approve` | `0x095ea7b3` | Rewrites `spender`'s allowance to `amount`. Neither policies nor the pause state apply. Emits `Approval`. |
### Memo variants
Each of these does exactly what its plain counterpart does, then emits `Memo` in the log slot directly after the primary event.
| Function | Selector | Wraps |
|---|---|---|
| `transferWithMemo` | `0x95777d59` | `transfer` |
| `transferFromWithMemo` | `0x929c2539` | `transferFrom` |
| `mintWithMemo` | `0xe44f0b12` | `mint` |
| `burnWithMemo` | `0x38f23b0b` | `burn` |
### Supply operations
| Function | Selector | Behavior |
|---|---|---|
| `mint` | `0x40c10f19` | Issues `amount` to `to` and emits `Transfer(address(0), to, amount)`. |
| `burn` | `0x42966c68` | Destroys `amount` out of the caller's own balance. No policy applies. |
| `burnBlocked` | `0xec0cf3dc` | Deprecated. Destroys `amount` belonging to a `from` that `TRANSFER_SENDER_POLICY` currently denies. |
| `seizeWithMemo` | `0xf916d81b` | Takes `amount` from `from` and reassigns it to `to` in one privileged step. |
| `supplyCap` | `0x8f770ad0` | The ceiling `mint` enforces. It tops out at `type(uint128).max`, which doubles as the no-cap sentinel. |
| `updateSupplyCap` | `0xe5a97f07` | Moves the cap up or down. It can never sit below the supply already outstanding. |
### Access control
| Function | Selector | Behavior |
|---|---|---|
| `hasRole` | `0x91d14854` | Whether `account` belongs to `role`. The graph accepts user-defined roles, though the token itself enforces none of them. |
| `getRoleAdmin` | `0x248a9ca3` | Which role can hand out or take away `role`. Falls back to `DEFAULT_ADMIN_ROLE` where nothing was set. |
| `grantRole` | `0x2f2ff15d` | Adds `account` to `role` and emits `RoleGranted`. |
| `revokeRole` | `0xd547741f` | Drops `account` from `role` and emits `RoleRevoked`. |
| `setRoleAdmin` | `0x1e4e0091` | Reassigns which role administers `role`. Emits `RoleAdminChanged`. |
| `renounceRole` | `0x36568abe` | Lets the caller give up a role they hold. Emits `RoleRevoked`. |
| `renounceLastAdmin` | `0x6f79e3d7` | The one route to a permanently admin-less token. It strips `DEFAULT_ADMIN_ROLE` from the last holder for good. |
### Pause
| Function | Selector | Behavior |
|---|---|---|
| `pausedFeatures` | `0xde9997e3` | The set of `PausableFeature` values paused on this token. Don't rely on the ordering. |
| `isPaused` | `0x165c44bc` | Whether one specific `feature` is paused. Constant time. |
| `pause` | `0x9f98bd2d` | Pauses everything in `features`. It adds to the existing set, so repeats are harmless. |
| `unpause` | `0xb61b2ebc` | Clears the pause on everything in `features`, leaving anything unlisted alone. Repeats are harmless. |
### Policy slots
| Function | Selector | Behavior |
|---|---|---|
| `policyId` | `0xdb3de624` | The policy currently wired into `policyScope`. An unset slot reads back as `0`, the always-allow built-in. |
| `updatePolicy` | `0xadf9c4ea` | Points `policyScope` at a different policy ID. The next gated call already sees it. |
### ERC-2612 permit and metadata
| Function | Selector | Behavior |
|---|---|---|
| `nonces` | `0x7ecebe00` | The permit nonce for `owner`, which climbs by one after each `permit` that lands. |
| `permit` | `0xd505accf` | The EIP-2612 signed approval. It recovers `owner` from `(v, r, s)` by ECDSA, so only EOA signatures work. |
| `DOMAIN_SEPARATOR` | `0x3644e515` | The token's live EIP-712 domain separator, recomputed per call. |
| `eip712Domain` | `0x84b0196e` | ERC-5267 introspection over that domain. |
| `contractURI` | `0xe8a3d485` | Where the token's contract-level metadata lives offchain, per ERC-7572. |
| `updateContractURI` | `0x7e5b1e24` | Repoints `contractURI`. Per ERC-7572 the resulting event carries no arguments. |
| `updateName` | `0x84da92a7` | Rewrites `name`. Emits `NameUpdated`, then `EIP712DomainChanged`, because the separator rotates with it. |
| `updateSymbol` | `0x537f5312` | Rewrites `symbol` and emits `SymbolUpdated`. |
## IB20Asset
Extra surface carried only by tokens created as the `ASSET` variant.
| Function | Selector | Behavior |
|---|---|---|
| `OPERATOR_ROLE` | `0xf5b541a6` | The role behind `announce` and the multiplier operations. |
| `WAD_PRECISION` | `0x664808a8` | The fixed-point scale the multiplier uses, equal to `1e18`. |
| `MAX_UI_MULTIPLIER` | `0x785c0cf0` | The largest multiplier the setters will take. |
| `multiplier` | `0x1b3ed722` | The multiplier in force, at `WAD_PRECISION`. Stored balances stay raw underneath it. |
| `uiMultiplier` | `0xa60bf13d` | The ERC-8056 UI multiplier as it stands now. |
| `newUIMultiplier` | `0xdc767007` | The UI multiplier waiting to take over, if one is scheduled. |
| `effectiveAt` | `0x97a4064f` | When that pending multiplier is due to apply. |
| `updateUIMultiplier` | `0x628e600f` | Queues a UI-multiplier change for the `effectiveAt` timestamp. |
| `cancelUIMultiplierUpdate` | `0x2c97a0f0` | Drops the one pending change and returns the token to having none queued. |
| `updateMultiplier` | `0x5ffe6146` | The emergency override. It sets the multiplier on the spot rather than scheduling it. |
| `toScaledBalance` | `0x04f04c99` | Scales a raw balance up: `rawBalance * multiplier / WAD_PRECISION`. |
| `toRawBalance` | `0x0ca06c44` | Scales a scaled balance back down to its raw form. |
| `scaledBalanceOf` | `0x1da24f3e` | Shorthand for `toUIAmount(balanceOf(account))`. |
| `balanceOfUI` | `0x437a9958` | An account's balance with the UI adjustment already applied. |
| `totalSupplyUI` | `0x9bea6429` | Total supply with the UI adjustment already applied. |
| `toUIAmount` | `0x3248d4ff` | Converts a raw amount into its UI form. |
| `fromUIAmount` | `0x65cd9b3c` | Converts a UI amount back into its raw form. |
| `announce` | `0x595135dd` | Publishes an announcement that affects holders and fires off each bundled call atomically. |
| `isAnnouncementIdUsed` | `0xc0da474e` | Whether `announce` has already spent `id`. IDs never come back around. |
| `batchMint` | `0x68573107` | Issues `amounts[i]` to `recipients[i]` across the arrays. It's all or nothing — one bad element reverts the lot. |
| `extraMetadata` | `0x4ddf9da0` | Reads a named metadata entry, giving back an empty string where none is set. |
| `updateExtraMetadata` | `0xb2851ef5` | Writes a metadata entry, or clears it when you pass an empty `value`. |
## IB20Stablecoin
Tokens created as the `STABLECOIN` variant add one call.
| Function | Selector | Behavior |
|---|---|---|
| `currency` | `0xe5a6b10f` | The currency code the stablecoin says it tracks, such as `"USD"`, `"EUR"`, or `"JPY"`. |
## IB20Factory
Every B20 token comes into existence through this one precompile.
| Function | Selector | Behavior |
|---|---|---|
| `createB20` | `0x62975e6a` | Deploys a token of the requested `variant` at the address derived deterministically for it. |
| `getB20Address` | `0x8c30260f` | Tells you which address `createB20` would pick for `(variant, sender, salt)`. It never reverts. |
| `isB20` | `0xfa19b927` | Whether this factory made `token`, read straight off the address prefix. It never reverts. |
| `isB20Initialized` | `0x6a45ba98` | Whether `createB20` finished at `token`. It flips once and stays there. |
## IPolicyRegistry
The singleton registry holding every policy, keyed by `uint64 policyId`.
| Function | Selector | Behavior |
|---|---|---|
| `createPolicy` | `0xca5d55f6` | Opens an empty simple policy. Anyone can call it. |
| `createPolicyWithAccounts` | `0xa2d3044f` | Opens a simple policy with `accounts` already in it. Anyone can call it. |
| `createCompositePolicy` | `0x6fdd1491` | Opens a composite that joins existing simple policies under a logic rule. |
| `updateAllowlist` | `0x3388fb5b` | Sets each of `accounts` to `allowed` on an ALLOWLIST policy, in one batch. |
| `updateBlocklist` | `0x5c4e51b8` | Sets each of `accounts` to `blocked` on a BLOCKLIST policy, in one batch. |
| `updateComposite` | `0xbfe142c0` | Swaps a composite's children out wholesale for `childPolicyIds`. |
| `stageUpdateAdmin` | `0x1d7ae695` | Nominates a replacement admin for `policyId`. The sitting admin keeps control until the handover completes. |
| `finalizeUpdateAdmin` | `0x33031a9c` | Closes out the two-step handover. The caller becomes admin and the pending slot empties. |
| `renounceAdmin` | `0xefdb7fa3` | Gives up the policy permanently, which freezes its membership and children from then on. |
| `isAuthorized` | `0x55a1179e` | Whether `account` clears `policyId`. It never reverts. A malformed ID gives `false`, and a well-formed ID that was never created behaves as an empty set. |
| `policyExists` | `0x330f5637` | Whether `policyId` is a built-in sentinel or an ID that was actually handed out. It never reverts. |
| `policyAdmin` | `0x09dd0a47` | The sitting admin for `policyId`, or the zero address for built-ins. |
| `pendingPolicyAdmin` | `0x017548b7` | The nominated admin for `policyId`, or the zero address when nothing is staged. |
| `compositePolicyChildIds` | `0x7c40df74` | The children a composite `policyId` is built from. |
| `MIN_COMPOSITE_CHILD_POLICIES` | `0xb3ae29f7` | The fewest children a composite can reference, inclusive. It never reverts. |
| `MAX_COMPOSITE_CHILD_POLICIES` | `0x54309870` | The most children a composite can reference, inclusive. It never reverts. |
Every ID shape gets an answer, and none of them revert:
| Policy ID | `isAuthorized` result |
|---|---|
| Malformed (top byte outside `PolicyType`) | `false` |
| Well-formed, never created, `ALLOWLIST` or `UNION` | `false`, because an empty set lets nobody through |
| Well-formed, never created, `BLOCKLIST` or `INTERSECT` | `true`, because an empty set stops nobody |
| Inverted, base exists (from Denim) | The opposite of the base result |
| Inverted, base never created or malformed (from Denim) | `false` |
The token guards its own slots: `updatePolicy` reverts with `PolicyNotFound` when `policyExists` is false, so a B20 scope can never point at a missing ID. The empty-set rows matter for your own contracts and off-chain checks that call `isAuthorized` directly and store IDs without that guard. An unknown `BLOCKLIST` or `INTERSECT` ID there quietly lets everyone through.
## IActivationRegistry
The gate that decides which features are live on the chain.
| Function | Selector | Behavior |
|---|---|---|
| `isActivated` | `0xba87af80` | Whether `feature` is on right now. It never reverts. |
| `checkActivated` | `0xde5bfd9b` | The asserting form — it reverts with `FeatureNotActivated(feature)` when the feature is off. |
| `admin` | `0xf851a440` | The only address cleared to call `activate` and `deactivate`. |
| `activate` | `0x59db6e85` | Switches `feature` on and emits `FeatureActivated`. |
| `deactivate` | `0x22eee84c` | Switches `feature` off and emits `FeatureDeactivated`. |
## Events
Look these up by `topic0` when you're decoding logs.
| Event | Interface | Topic0 |
|---|---|---|
| `Transfer` | `IB20` | `0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef` |
| `Approval` | `IB20` | `0x8c5be1e5ebec7d5bd14f71427d1e84f3dd0314c0f7b2291e5b200ac8c7c3b925` |
| `Memo` | `IB20` | `0x6989f5818dcfd11f8cd53b27c94cec33dae1589735f03e639cba54553a1825e8` |
| `Seized` | `IB20` | `0xa9aec5d8b86e2fa2fd6ac3af62f2622e3dfdab1967d4cbbb56a5df7d74cb887c` |
| `BurnedBlocked` | `IB20` | `0x0b552e96653fd6842da37c477005d3b5c08a8c7d3631b1f43787b2dc9a1006a3` |
| `RoleGranted` | `IB20` | `0x2f8788117e7eff1d82e926ec794901d17c78024a50270940304540a733656f0d` |
| `RoleRevoked` | `IB20` | `0xf6391f5c32d9c69d2a47ea670b442974b53935d1edc7fd64eb21e047a839171b` |
| `RoleAdminChanged` | `IB20` | `0xbd79b86ffe0ab8e8776151514217cd7cacd52c909f66475c3af44e129f0b00ff` |
| `LastAdminRenounced` | `IB20` | `0xe8d3a9872e7ca325571ff1e4c51ddd69090a0345240cc605ccde365ec867cc67` |
| `Paused` | `IB20` | `0x43e072977b8112813d7c2aa0b63d3c121c1fe3e714e6d2eacb5735fe4027e976` |
| `Unpaused` | `IB20` | `0xdc6281474ea3dea2a856e225c7ba3edf427de9164495817c4d49a595e683fed4` |
| `PolicyUpdated` | `IB20` | `0x8b4790f7ff717fc8f60f07ae099e47ef318dc04b37ae98056b50a22b79056626` |
| `SupplyCapUpdated` | `IB20` | `0x6d14f44808ce024f263432bc38d019a9951fbe674e9898b54844dbc8dc09c23a` |
| `ContractURIUpdated` | `IB20` | `0xa5d4097edda6d87cb9329af83fb3712ef77eeb13738ffe43cc35a4ce305ad962` |
| `NameUpdated` | `IB20` | `0x74321da206c1b9fa34367f7ece59ca49371dcd13820b9a5c3767ae1ecceed51a` |
| `SymbolUpdated` | `IB20` | `0x64e8b5c6dcea43dd79766bb3b8af7c45968d12b68c960cf2da23856f34d598d4` |
| `EIP712DomainChanged` | `IB20` | `0x0a6387c9ea3628b88a633bb4f3b151770f70085117a15f9bf3787cda53f13d31` |
| `UIMultiplierUpdated` | `IB20Asset` | `0x2205df4534432b2f60654a3fdb48737ffdaf3e9edb1a498bd985bc026b15b055` |
| `MultiplierUpdated` | `IB20Asset` | `0x4dbe4840d7465bd162f67814cea0b519567a2e0e578bcde61e7f4ced361e5a3d` |
| `UIMultiplierUpdateCancelled` | `IB20Asset` | `0x883856335ba5f60c18b9817c4505d3c7d3f6223dcf39516b30c508c46a5e1cad` |
| `ExtraMetadataUpdated` | `IB20Asset` | `0xd7bb345be29e78d635203d40fe0567e7ef19d5cd5cc5fcd25f768b8063e82aa1` |
| `Announcement` | `IB20Asset` | `0xccebf8218a62875909564adef86a6f4df81503cb617221e793357d62f8e813f7` |
| `EndAnnouncement` | `IB20Asset` | `0x96d64dafe2c790596430196b982ad1da3221cb3b0f4e6e2df77f2e4f71a90037` |
| `B20Created` | `IB20Factory` | `0xfd9bf2730513a1709722ff379a0844dfd8f997d600693c2bcc659e188bbdba0d` |
| `PolicyCreated` | `IPolicyRegistry` | `0xdc870ce85be577234b8548f42b93f84bbff6d0c1f38ee725c809c49932a13885` |
| `PolicyAdminStaged` | `IPolicyRegistry` | `0xdbf3b34a4c956c56ca05cd4b8f9293a4347ad61994445a4b89817d4a19561136` |
| `PolicyAdminUpdated` | `IPolicyRegistry` | `0x98925cfb1bc09c5b43dd0dd56d3d95aa04fb3300927580cc588c3f5dd58c15e1` |
| `AllowlistUpdated` | `IPolicyRegistry` | `0x18c46532f90187ba11e436e21da087b684801d7f0787f2043f26f079c91e9ef0` |
| `BlocklistUpdated` | `IPolicyRegistry` | `0x2ff63c102b1b9fd7f5d39f83039c5d6aaf50a414a4f2def2704e41be2628f1e3` |
| `CompositePolicyUpdated` | `IPolicyRegistry` | `0x4ff6adaab31b0df87aa7b8b7320c52b8b3b5eede3bf28a6baaaa8b8b7e1d6363` |
| `FeatureActivated` | `IActivationRegistry` | `0x8c7a0ecdbb8d96e867e43ec1aef80027976ee493c18bef399fa799ed19752451` |
| `FeatureDeactivated` | `IActivationRegistry` | `0x15bf65a782c3258c63268ba9d7aed710cf9f9315d3687d9a4632ccdad7926c84` |
## Errors
Reverse lookup for revert selectors. A few names appear more than once — `NonPayable` and `Unauthorized` are shared across surfaces, and `Unauthorized` does not even carry the same selector everywhere, so read the interface column.
### IB20
| Error | Selector | Cause |
|---|---|---|
| `NonPayable` | `0x6fb1b0e9` | ETH rode along with a call to a nonpayable token selector. |
| `AccessControlUnauthorizedAccount` | `0xe2517d3f` | `account` is missing `neededRole`. |
| `AccessControlBadConfirmation` | `0x6697b232` | `renounceRole` got a `callerConfirmation` that wasn't `msg.sender`. |
| `Unauthorized` | `0x82b42900` | A positional authorization check failed — one that doesn't reduce to a missing role. |
| `ContractPaused` | `0xf9df5ac9` | The `PausableFeature` this operation falls under is paused. |
| `InsufficientAllowance` | `0x192b9e4e` | The `transferFrom` asked for more than `spender` is allowed to move. |
| `InsufficientBalance` | `0xdb42144d` | The transfer or burn asked for more than `sender` holds. |
| `InvalidSender` | `0x4c14f64c` | The source address on the transfer is not valid, typically `address(0)`. |
| `InvalidReceiver` | `0x9cfea583` | The destination address on the transfer is not valid — `address(0)`, or from Denim the address of the token being credited. |
| `InvalidApprover` | `0x8bc146c4` | The `owner` on the approval is not valid, typically `address(0)`. |
| `InvalidSpender` | `0x4e15efda` | The `spender` on the approval is not valid, typically `address(0)`. |
| `InvalidAmount` | `0x2c5211c6` | An amount came through as zero where a nonzero one is required. ERC-20 amount arguments are exempt. |
| `EmptyFeatureSet` | `0x4861ff45` | An empty array reached a function that needs at least one entry. |
| `InvalidSupplyCap` | `0x0a3780ce` | The proposed cap sits outside the permitted band — under current supply, or over the maximum. |
| `SupplyCapExceeded` | `0x4b344b11` | The mint would carry `totalSupply` past the cap. |
| `PolicyForbids` | `0xa43fec12` | One of the policy slots turned the operation down. |
| `PolicyNotFound` | `0xcccad523` | The policy ID given isn't in the registry. |
| `UnsupportedPolicyType` | `0xcdd98a4a` | This token, or this variant of it, has no such `policyScope`. |
| `AccountNotSeizable` | `0x91dbbc8d` | `seizeWithMemo` targeted a `from` that `SEIZE_EXEMPT_POLICY` still authorizes. |
| `AccountNotBlocked` | `0x64a5cb46` | The deprecated `burnBlocked` targeted a `from` that is still authorized. |
| `ExpiredSignature` | `0xbd2a913c` | The `permit` arrived with a `deadline` already behind `block.timestamp`. |
| `InvalidSigner` | `0x7ba5ffb5` | ECDSA recovery on the `permit` produced a `signer` that isn't the `owner` claimed. |
| `LastAdminCannotRenounce` | `0x361513e7` | The sole remaining admin tried to leave via `renounceRole(DEFAULT_ADMIN_ROLE, ...)`. |
| `NotSoleAdmin` | `0x2a98e73b` | `renounceLastAdmin()` was called while other accounts still hold `DEFAULT_ADMIN_ROLE`. |
### IB20Asset
| Error | Selector | Cause |
|---|---|---|
| `AnnouncementIdAlreadyUsed` | `0xd10b3c9e` | The `id` handed to `announce` was already spent. |
| `AnnouncementInProgress` | `0x5c5f0829` | A call dispatched from inside `announce` tried to call `announce` again. |
| `InternalCallMalformed` | `0x4e2f143e` | A call dispatched by `announce` came in under four bytes. |
| `InternalCallFailed` | `0xb288a127` | A call dispatched by `announce` reverted normally, and its reason is wrapped here. |
| `InvalidMetadataKey` | `0x86ea3abb` | `updateExtraMetadata` got an empty `key`. |
| `InvalidMultiplier` | `0x6f12f3dc` | A multiplier setter was handed a value it won't accept. |
| `EffectiveAtInPast` | `0x14119cf6` | The `effectiveAt` on `updateUIMultiplier` isn't in the future. |
| `EffectiveAtTooFar` | `0x1ce214fa` | The `effectiveAt` on `updateUIMultiplier` overran `type(uint64).max`. |
| `UIMultiplierUpdateExists` | `0x4481a68e` | `updateUIMultiplier` was called while another update is still pending. |
| `UIMultiplierUpdateDoesNotExist` | `0xa7d6a5ca` | `cancelUIMultiplierUpdate` found nothing pending to cancel. |
| `LengthMismatch` | `0xab8b67c6` | A batched call got parallel arrays of unequal length. |
| `EmptyBatch` | `0xc2e5347d` | A batched call got empty arrays. |
### IB20Factory
| Error | Selector | Cause |
|---|---|---|
| `NonPayable` | `0x6fb1b0e9` | ETH rode along with a call to a nonpayable factory selector. |
| `TokenAlreadyExists` | `0x15ef3a57` | Something already occupies the deterministic address this creation derives. |
| `InvalidVariant` | `0xf10e8e43` | The `variant` given isn't a recognized `B20Variant`. |
| `UnsupportedVersion` | `0xc0d8b4e0` | The leading `version` byte in `params` matches no known encoding for that variant. |
| `MissingRequiredField` | `0x4a43ae87` | A required string argument came through empty. |
| `InvalidCurrency` | `0x997c1de8` | The stablecoin `currency` had content, but carried a byte outside `A`-`Z`. |
| `InvalidDecimals` | `0xca950391` | The asset `decimals` fell outside the permitted inclusive range. |
| `InitCallFailed` | `0x4eae0860` | One of the `initCalls` reverted, and the factory passes the underlying reason back up. |
### IPolicyRegistry
| Error | Selector | Cause |
|---|---|---|
| `NonPayable` | `0x6fb1b0e9` | ETH rode along with a call to a nonpayable registry selector. |
| `Unauthorized` | `0x82b42900` | The caller isn't the admin the operation demands. |
| `PolicyNotFound` | `0x720caa4f` | The policy ID referenced doesn't exist. |
| `IncompatiblePolicyType` | `0xf1011ef5` | The operation doesn't fit this policy's type. |
| `ZeroAddress` | `0xd92e233d` | An address argument that has to be set came through as the zero address. |
| `BatchSizeTooLarge` | `0x083e2f67` | A membership batch ran past the registry's limit. |
| `NoPendingAdmin` | `0xb4539afa` | `finalizeUpdateAdmin` ran with nobody staged. |
| `ChildPoliciesOutsideOfRange` | `0x697ec868` | A composite's child count fell outside the permitted range. |
| `InvalidChildPolicy` | `0x46508ef6` | A composite's children must be existing simple policies. Composites can't nest. |
### IActivationRegistry
| Error | Selector | Cause |
|---|---|---|
| `Unauthorized` | `0x8e4a23d6` | The caller isn't the activation admin. |
| `AlreadyActivated` | `0x866b0041` | The feature is already on. |
| `FeatureNotActivated` | `0xb9b2a425` | The feature is off. |
| `DelegateCallNotAllowed` | `0x0d89438e` | The precompile was reached through `DELEGATECALL` or `CALLCODE`. |
| `StaticCallNotAllowed` | `0xbeaba5b7` | A state-changing entry point was reached from inside a `STATICCALL` frame. |
## Constants
### Roles
| Role | Solidity constant |
|---|---|
| Default admin | `bytes32(0)` |
| Mint | `keccak256("MINT_ROLE")` |
| Burn | `keccak256("BURN_ROLE")` |
| Deprecated blocked burn | `keccak256("BURN_BLOCKED_ROLE")` |
| Seize | `keccak256("SEIZE_ROLE")` |
| Pause | `keccak256("PAUSE_ROLE")` |
| Unpause | `keccak256("UNPAUSE_ROLE")` |
| Metadata | `keccak256("METADATA_ROLE")` |
| Asset operator | `keccak256("OPERATOR_ROLE")` |
### Policy scopes
| Scope | Solidity constant |
|---|---|
| Transfer sender | `keccak256("TRANSFER_SENDER_POLICY")` |
| Transfer receiver | `keccak256("TRANSFER_RECEIVER_POLICY")` |
| Transfer executor | `keccak256("TRANSFER_EXECUTOR_POLICY")` |
| Mint receiver | `keccak256("MINT_RECEIVER_POLICY")` |
| Seize exempt | `keccak256("SEIZE_EXEMPT_POLICY")` |
| Seize receiver | `keccak256("SEIZE_RECEIVER_POLICY")` |
### Policy IDs
Two counters are reserved for the built-ins; anything you create starts at `2`.
| Name | Value |
|---|---|
| `ALWAYS_ALLOW` | `0` |
| `ALWAYS_BLOCK` | `(uint64(uint8(IPolicyRegistry.PolicyType.ALLOWLIST)) << 56) \| 1` |
Custom IDs pack a type byte over a counter:
```text
[8-bit PolicyType][56-bit counter]
```
| PolicyType | Byte |
|---|---|
| `BLOCKLIST` | `0x00` |
| `ALLOWLIST` | `0x01` |
| `UNION` | `0x02` |
| `INTERSECT` | `0x03` |
### Variant bytes
The variant is encoded into the address, so you can read it off the prefix.
| Variant | Byte | Address shape |
|---|---|---|
| `ASSET` | `0x00` | `0xB200...` |
| `STABLECOIN` | `0x01` | `0xB201...` |
### Supply and decimals
| Constant | Value |
|---|---|
| Minimum Asset decimals | `6` |
| Maximum Asset decimals | `18` |
| Maximum supply cap, and the no-cap sentinel | `type(uint128).max` |
| Bitmask with every feature paused | `15` — `TRANSFER`, `MINT`, `BURN`, `SEIZE` together |
## Availability by hardfork
Every selector on this page is final, but not all of them are dialable today. [Beryl](/specifications/beryl-overview/) shipped the standard. [Cobalt](/specifications/cobalt-overview/) added a second group, and both are live on Mainnet and Sepolia. A third group waits for Denim and takes effect only when that fork activates.
Cobalt adds no breaking change. Every Beryl function, event topic, and error keeps the exact four-byte selector or `topic0` it has now, and keeps its behaviour.
### Live since Beryl
| Network | B20 live since |
|---|---|
| Base Mainnet | 2026-06-25 |
| Base Sepolia | 2026-06-18 |
Beryl carried the roles model, the policy registry with its six per-token scopes, memos, granular pausing, supply caps, `permit`, the factory, and both the Asset and Stablecoin variants.
### Live since Cobalt
| Network | Cobalt live since |
|---|---|
| Base Mainnet | 2026-09-30 |
| Base Sepolia | 2026-09-23 |
Three groups came with this fork. On 2026-10-01, a Mainnet B20 Asset token reverted the Cobalt getters at a pre-fork block and answered them at the head.
**The seize surface on `IB20`.** `seizeWithMemo` (`0xf916d81b`), the `SEIZE_ROLE`, `SEIZE_EXEMPT_POLICY` and `SEIZE_RECEIVER_POLICY` getters, the `Seized` event, the `AccountNotSeizable` error, and the `SEIZE` pause ordinal (`3`, bit `8`) all land together. It is defined on the shared `IB20` surface, so Asset and Stablecoin expose it identically.
**The ERC-8056 multiplier surface on `IB20Asset`.** `uiMultiplier`, `toUIAmount`, `fromUIAmount`, `balanceOfUI` and `totalSupplyUI` become the canonical names, and the scheduled setter `updateUIMultiplier` joins `newUIMultiplier`, `effectiveAt`, `cancelUIMultiplierUpdate`, `MAX_UI_MULTIPLIER` and `supportsInterface`. The older `multiplier`, `toScaledBalance`, `toRawBalance` and `scaledBalanceOf` are kept as aliases returning the same values.
**Composite policies on `IPolicyRegistry`.** `createCompositePolicy`, `updateComposite`, `compositePolicyChildIds`, the two bound getters, the `CompositePolicyUpdated` event, and the `ChildPoliciesOutsideOfRange` and `InvalidChildPolicy` errors. The `PolicyType` enum gains `UNION = 2` and `INTERSECT = 3` by appending, so the existing values and the packed-ID top-byte encoding do not move.
### Arriving with Denim
Three changes are already in the node source, gated behind [Denim](/specifications/denim-overview/) rather than Cobalt. Denim has a target month but no activation timestamp yet. Upstream published a changelog entry for each on 2026-09-29 and labels the first two breaking for integrations that depend on the old behaviour; inverted policy IDs are purely additive.
**A token can no longer be credited to itself.** `transfer`, `transferFrom`, `mint`, `batchMint` (checked per element) and `seizeWithMemo`, plus their memo variants, all reject a `to` equal to the address of the token being credited, reverting `InvalidReceiver`. Asset and Stablecoin enforce it identically. The zero address was already refused; this extends the same treatment to the token's own address, which previously accepted the credit and stranded the balance where nothing could move it.
The rule is narrower than it first sounds, and the distinction is the part worth getting right:
- Only the token *being credited* is refused. Sending B20 token A to the address of a different B20 token B is still a valid transfer. An earlier revision of this change rejected every B20-prefixed recipient; it was narrowed before landing, so do not build on the broader reading.
- On `transferFrom` the recipient is validated before the allowance is touched, so a call that trips this rule leaves the allowance unspent rather than consuming it on a revert.
- Only `to` is checked. A seize whose `from` is the token address still works, which is how an issuer recovers tokens that were sent there before Denim. The error keeps its selector, `InvalidReceiver(address)` (`0x9cfea583`); it simply fires in one more case.
- For seizure, this closes a disguised-burn path: because seize leaves `totalSupply` alone, seizing into the token address used to remove a balance from circulation without recording it as a burn.
**The executor policy covers every transfer.** Asset and Stablecoin both move to logic version 3 at Denim. Before it, `TRANSFER_EXECUTOR_POLICY` runs only on `transferFrom` where the caller is not `from`. From Denim it runs first on `transfer`, `transferFrom`, and the memo variants, so a holder who is not on a restrictive executor allowlist can no longer move their own balance. When the caller is `from` and both the executor and sender scopes hold the same policy ID, the sender check is skipped as redundant. Storage is append-only, so existing tokens switch in place with no migration. Upstream's issuer guide documents this behaviour without the Denim gate. See [B20 Issuer Operations](/integration-guides/b20-issuer-operations/#limit-who-may-initiate-transfers).
**Inverted policy IDs.** Denim moves the policy registry to its third version, which treats bit 63 of a policy ID as a NOT flag. Setting it gives you the complement of an existing policy without building a second member set: bind the inverted ID to a token scope, or hand it to a composite as a child to express "A AND NOT X". It works on all four types. Membership stays on the base policy, so editing the base changes the inverse too. The one new selector is `invertedPolicyId(uint64 policyId) external pure returns (uint64)`, which flips the bit either way. You can also set it by hand.
On an inverted ID, `isAuthorized` returns the negation of the base, except when the base is unknown or malformed: then it returns `false`. The registry clears bit 63 before it checks the type byte, so an inverted ID counts as malformed only when its base does. That fail-closed rule stops a mistyped inverted ID from turning into allow-everyone. `policyExists` and `policyAdmin` ignore bit 63 and answer for the base, because an inverted ID has no record of its own.
## What changes for integrators at Cobalt
Nothing you call today stops working, so none of this is a forced migration. The timing has tightened, though: Sepolia activates on September 23, 2026 and Mainnet a week later, so each item below is now a path worth moving to on a schedule rather than eventually.
### Seizure replaces `burnBlocked`
`burnBlocked` and `BURN_BLOCKED_ROLE` are deprecated but untouched — same selector, same events, same behaviour, still callable. `seizeWithMemo(from, to, amount, memo)` becomes the canonical route for administrative balance removal.
The two are not interchangeable, and swapping the selector alone will not reproduce the old outcome:
- **Seize is a transfer, not a burn.** It moves `amount` from `from` to `to` and leaves `totalSupply` alone. To get the old result, seize into a treasury address you control and then call `burn`. Do not seize into the token's own address: that reverts `InvalidReceiver` from Denim onward, and before Denim it strands the balance instead of burning it.
- **They read different policies.** `seizeWithMemo` consults `SEIZE_EXEMPT_POLICY`; `burnBlocked` consults `TRANSFER_SENDER_POLICY`. A token can define a seizable set that has nothing to do with its transfer-blocked set. Under both, "eligible" means *not* authorized by the relevant policy.
- **They sit in different role and pause domains.** `SEIZE_ROLE` and `BURN_BLOCKED_ROLE` are separate grants, and `SEIZE` (ordinal 3) and `BURN` (ordinal 2) are separate pause bits. Pausing one leaves the other running.
The scope was renamed at Cobalt. It was `SEIZE_HOLDER_POLICY` with selector `0xb279d311`, and it is now `SEIZE_EXEMPT_POLICY` with selector `0xfeb346ec`. Both the selector and the `keccak256` scope constant change, so any code holding either value hardcoded needs updating. Behaviour did not move with the name — the inverted check is the same one it always was.
Attach a `BLOCKLIST` to this scope. Accounts on the blocklist read as unauthorized and are therefore seizable; everyone else stays exempt. An `ALLOWLIST` or the `ALWAYS_BLOCK` sentinel inverts that and makes every holder seizable, which is almost never what an issuer wants here. The scope is also independent of `TRANSFER_SENDER_POLICY`: blocking an account from transferring does not make it seizable.
When more than one guard would fail, the holder gate reports first, then the destination gate, then the balance: `AccountNotSeizable` before `PolicyForbids(SEIZE_RECEIVER_POLICY, ...)` before `InsufficientBalance`.
### Multiplier changes get scheduled
`updateUIMultiplier(newMultiplier, effectiveAt)` is the path meant for corporate actions such as splits and reinvested dividends. Only one pending update exists at a time.
1. **Schedule** with `updateUIMultiplier`. It needs `OPERATOR_ROLE`, and `effectiveAt` must be strictly in the future.
2. **Observe** while it waits: `newUIMultiplier()` gives the target, `effectiveAt()` gives the flip time, and `uiMultiplier()` / `multiplier()` still report the value in force.
3. **Let it mature.** Once `block.timestamp >= effectiveAt` the reads flip on their own. No event marks the moment.
4. **Or drop it** with `cancelUIMultiplierUpdate()`, which emits `UIMultiplierUpdateCancelled`.
To reorder overlapping actions, cancel and reschedule in a single announcement rather than as two calls: `announce([cancelUIMultiplierUpdate(), updateUIMultiplier(...)], ...)`.
The instant `updateMultiplier(uint256)` stays, downgraded to an emergency failsafe. It applies immediately, clears any live pending update, and is meant for reversing a scheduling mistake — usually paired with a pause — rather than for routine use.
### Composite policies join existing ones
A composite authorizes by combining 2 to 4 existing simple policies under `UNION` (OR) or `INTERSECT` (AND). Build one with `createCompositePolicy(admin, policyType, childPolicyIds)`; change it with `updateComposite(policyId, childPolicyIds)`, which replaces the child set **in full** — there is no partial update and no way to clear the list.
The problem this solves is duplication. A B20 token stores one policy ID per scope, so combining a shared KYC allowlist with a token-specific one previously meant copying both member lists into a third, flattened policy and running infrastructure to keep that copy in step with its sources. Every such copy has a window in which it is wrong: an account added upstream cannot transact until the copy catches up, and an account removed upstream keeps its access until then. A composite stores references instead of members, so there is no copy to drift.
Evaluation is live and shallow. `isAuthorized` calls each child's own `isAuthorized` at read time rather than working from a set captured at creation, `UNION` short-circuits on the first child that authorizes, and `INTERSECT` short-circuits on the first that does not. Recursion never passes depth 1, because write-time validation rejects any child that is itself a composite or a built-in sentinel with `InvalidChildPolicy`. Nesting is impossible by construction.
The registry stores the child list exactly as given. It does not sort it and does not reject duplicates, so ordering is yours to choose. That choice cannot change the answer, since both gates are order-independent, but it does change what you pay: each child actually evaluated costs a membership read, and short-circuiting stops the walk early. Put the child most likely to decide the outcome first — the broadest allowlist under `UNION`, the narrowest under `INTERSECT`.
Two adjacent behaviours are easy to guess wrong:
- **A renounced child keeps working.** `renounceAdmin` on a child policy only clears its admin and freezes its membership; the policy still exists and still answers `isAuthorized`, so the parent composite evaluates it exactly as before.
- **`compositePolicyChildIds` never reverts.** Handed a simple policy or an ID that was never created, it returns an empty array rather than an error, so an empty result does not distinguish "not a composite" from "does not exist".
Two existing behaviours shift. `createPolicy` and `createPolicyWithAccounts` gain a revert path that was previously unreachable: passing `UNION` or `INTERSECT` to a simple constructor now reverts `IncompatiblePolicyType`, checked right after `ZeroAddress`. And the registry now carries two independent size limits — keep `ChildPoliciesOutsideOfRange`, which guards the `[2, 4]` child count, separate from `BatchSizeTooLarge`, which guards the 64-account membership batch. They are different errors on different call paths, and one tells you nothing about the other.
## Selector stability
Everything on this page is fixed. B20 method and event signatures sit on the chain's consensus surface, so a selector that ships never changes meaning and never gets withdrawn. The standard only grows by addition: a later release can introduce new calls, but it will not rewrite the behaviour behind one you already integrated against.
That gives you one practical guarantee. Code compiled against the selectors here keeps working across upgrades, and you only revisit it when you want something new.
Two names are the exception, and they are already marked throughout this page. `burnBlocked` and `BURN_BLOCKED_ROLE` are deprecated. They still resolve, because nothing is removed, and seizure flows now use [`seizeWithMemo`](#ib20), which has been live on every public network since Cobalt.
---
# debug_traceBlockByHash
Source: https://basehub.org/api-reference/debug/debug_traceblockbyhash/
Description: Replays every transaction in a block identified by hash and returns an EVM execution trace for each one.
Replays all transactions in a block identified by its hash and returns an execution trace for each.
Debug methods replay every transaction in the block and are computationally expensive. Availability varies by node provider.
## Parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `blockHash` | string | Yes | The 32-byte block hash. |
| `traceOptions` | object | No | Optional trace configuration. Accepts the same fields as [`debug_traceTransaction`](/api-reference/debug/debug_traceTransaction/). |
## Returns
`result` is an array of trace result objects, one per transaction in the block.
| Field | Type | Description |
| --- | --- | --- |
| `txHash` | string | The transaction hash. |
| `result` | object | The execution trace for this transaction. Same format as [`debug_traceTransaction`](/api-reference/debug/debug_traceTransaction/). |
## Example
### Request
```json
{
"jsonrpc": "2.0",
"method": "debug_traceBlockByHash",
"params": [
"0x3a4e8c5d7f2b1a6e9d0c4f8b3e7a2d5c8f1b4e7a0d3c6f9b2e5a8d1c4f7b0e3",
{ "tracer": "callTracer" }
],
"id": 1
}
```
### Response
```json
{
"jsonrpc": "2.0",
"id": 1,
"result": [
{
"txHash": "0xb903239f8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568238",
"result": {
"type": "CALL",
"from": "0xd3cda913deb6f4967b2ef66ae97de114a83bcc01",
"to": "0x4200000000000000000000000000000000000006",
"value": "0x2c68af0bb14000",
"gas": "0x5208",
"gasUsed": "0x5208",
"input": "0x",
"output": "0x",
"calls": []
}
}
]
}
```
---
# debug_traceBlockByNumber
Source: https://basehub.org/api-reference/debug/debug_traceblockbynumber/
Description: Returns EVM execution traces for every transaction in a block identified by its block number or block tag.
Returns the EVM execution traces for all transactions in a block identified by its number.
Debug methods replay every transaction in the block and are computationally expensive. Availability varies by node provider.
## Parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `block` | string | Yes | A block number in hex, or one of `"latest"`, `"earliest"`, `"safe"`, `"finalized"`. |
| `tracerConfig` | object | No | Optional tracer configuration. See [`debug_traceTransaction`](/api-reference/debug/debug_traceTransaction/) for available options. |
## Returns
| Field | Type | Description |
| --- | --- | --- |
| `result` | array | Array of trace objects, one per transaction in the block. |
## Example
### Request
```json
{
"jsonrpc": "2.0",
"method": "debug_traceBlockByNumber",
"params": ["latest", {"tracer": "callTracer"}],
"id": 1
}
```
### Response
```json
{
"jsonrpc": "2.0",
"id": 1,
"result": [
{
"result": {
"type": "CALL",
"gasUsed": "0xab3f"
}
}
]
}
```
---
# debug_traceTransaction
Source: https://basehub.org/api-reference/debug/debug_tracetransaction/
Description: Replays a transaction and returns its full EVM execution trace, with opcode-level gas, stack, memory, and storage detail.
Replays a transaction and returns its complete EVM execution trace, including every opcode executed, gas consumed at each step, stack contents, and storage changes.
Debug methods replay transactions and are computationally expensive. Availability and rate limits vary by node provider — avoid calling them in hot paths.
## Parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `transactionHash` | string | Yes | The 32-byte transaction hash to trace. |
| `traceOptions` | object | No | Optional tracing configuration. |
The `traceOptions` object accepts:
| Field | Type | Description |
| --- | --- | --- |
| `tracer` | string | Built-in tracer name. `"callTracer"` returns a call tree. `"prestateTracer"` returns the pre-execution account state. Omit to use the default struct log tracer. |
| `tracerConfig` | object | Options for the selected tracer. For `"callTracer"`, `\{ "onlyTopCall": true \}` skips internal calls. |
| `disableStorage` | boolean | If `true`, omits storage capture from struct logs. Reduces response size. Defaults to `false`. |
| `disableMemory` | boolean | If `true`, omits memory capture from struct logs. Reduces response size. Defaults to `false`. |
| `disableStack` | boolean | If `true`, omits stack capture from struct logs. Defaults to `false`. |
| `timeout` | string | Execution timeout as a Go duration string (for example, `"10s"`, `"30s"`). Defaults to `"5s"`. |
## Returns
`result` is the execution trace. The shape depends on the `tracer` option.
### Default struct log trace
| Field | Type | Description |
| --- | --- | --- |
| `gas` | number | Total gas provided for the transaction. |
| `failed` | boolean | Whether the transaction failed (reverted). |
| `returnValue` | string | Hex-encoded return value from the execution. |
| `structLogs` | array | Array of struct log entries, one per EVM opcode executed. |
Each entry in `structLogs` contains:
| Field | Type | Description |
| --- | --- | --- |
| `pc` | number | Program counter position. |
| `op` | string | EVM opcode name (for example, `"PUSH1"`, `"SLOAD"`). |
| `gas` | number | Remaining gas at this step. |
| `gasCost` | number | Gas cost of this opcode. |
| `depth` | number | Call depth (1 = top-level call). |
| `stack` | array | EVM stack values at this step. |
| `memory` | array | EVM memory contents as 32-byte chunks. |
| `storage` | object | Contract storage changes at this step (slot to value). |
### callTracer result
| Field | Type | Description |
| --- | --- | --- |
| `type` | string | Call type: `"CALL"`, `"STATICCALL"`, `"DELEGATECALL"`, or `"CREATE"`. |
| `from` | string | Sender address. |
| `to` | string | Recipient address. |
| `value` | string | ETH value sent with the call. |
| `gas` | string | Gas provided for the call. |
| `gasUsed` | string | Gas actually consumed. |
| `input` | string | Call data sent. |
| `output` | string | Return data from the call. |
| `error` | string | Error message if the call reverted. Optional. |
| `calls` | array | Array of nested call objects for internal calls. |
## Example
### Request (default struct log)
```json
{
"jsonrpc": "2.0",
"method": "debug_traceTransaction",
"params": [
"0xb903239f8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568238",
{}
],
"id": 1
}
```
### Request (callTracer)
```json
{
"jsonrpc": "2.0",
"method": "debug_traceTransaction",
"params": [
"0xb903239f8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568238",
{ "tracer": "callTracer" }
],
"id": 1
}
```
### Response (default)
```json
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"gas": 21000,
"failed": false,
"returnValue": "",
"structLogs": [
{
"pc": 0,
"op": "PUSH1",
"gas": 21000,
"gasCost": 3,
"depth": 1,
"stack": [],
"memory": [],
"storage": {}
}
]
}
}
```
### Response (callTracer)
```json
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"type": "CALL",
"from": "0xd3cda913deb6f4967b2ef66ae97de114a83bcc01",
"to": "0x4200000000000000000000000000000000000006",
"value": "0x2c68af0bb14000",
"gas": "0x5208",
"gasUsed": "0x5208",
"input": "0x",
"output": "0x",
"calls": []
}
}
```
---
# eth_blockNumber
Source: https://basehub.org/api-reference/eth/eth_blocknumber/
Description: Returns the latest block number on Base — the most recent block the node has imported, encoded as a hexadecimal string.
Returns the number of the most recently mined block.
## Parameters
None.
## Returns
| Field | Type | Description |
| --- | --- | --- |
| `result` | string | The current block number as a hexadecimal string. |
## Example
### Request
```json
{
"jsonrpc": "2.0",
"method": "eth_blockNumber",
"params": [],
"id": 1
}
```
### Response
```json
{
"jsonrpc": "2.0",
"id": 1,
"result": "0x158a0e9"
}
```
---
# eth_call
Source: https://basehub.org/api-reference/eth/eth_call/
Description: Executes a read-only message call against Base state without broadcasting a transaction; pair with pending on Flashblocks for pre-confirmed reads.
import { Aside, Tabs, TabItem } from '@astrojs/starlight/components';
Runs a message call immediately against node state without broadcasting a transaction or consuming on-chain gas. Use it to read contract state or simulate calls.
## Parameters
### `transaction` (object, required)
The transaction call object.
| Field | Type | Description |
| --- | --- | --- |
| `from` | string | Address the call is sent from. Optional; defaults to the zero address. |
| `to` | string | Address the call is directed to. Required. |
| `gas` | string | Gas provided for the call as a hexadecimal integer. Defaults to a high limit if omitted. |
| `gasPrice` | string | Gas price in wei as a hexadecimal integer. For legacy transactions. Optional. |
| `maxFeePerGas` | string | EIP-1559 maximum total fee per gas. Optional. |
| `maxPriorityFeePerGas` | string | EIP-1559 maximum priority fee per gas. Optional. |
| `value` | string | Value transferred in wei as a hexadecimal integer. Optional. |
| `data` | string | ABI-encoded call data: the 4-byte function selector followed by encoded arguments. Optional. |
### `block` (string, required)
Block number in hex, or `"latest"`, `"pending"`, `"safe"`, `"finalized"`, `"earliest"`. Pass `"pending"` to call against pre-confirmed state.
## Returns
| Field | Type | Description |
| --- | --- | --- |
| `result` | string | The return value of the call as a hex-encoded byte array. |
## Error codes
| Code | Message | Description |
| --- | --- | --- |
| `-32000` | execution reverted | The call reverted. The `data` field in the error object contains the ABI-encoded revert reason when available. |
## Example
### Request
```bash
curl https://mainnet.base.org \
-X POST \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"method": "eth_call",
"params": [
{
"to": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
"data": "0x70a082310000000000000000000000004200000000000000000000000000000000000006"
},
"latest"
],
"id": 1
}'
```
```bash
curl https://mainnet.base.org \
-X POST \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"method": "eth_call",
"params": [
{
"to": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
"data": "0x70a082310000000000000000000000004200000000000000000000000000000000000006"
},
"pending"
],
"id": 1
}'
```
### Response
```json
{
"jsonrpc": "2.0",
"id": 1,
"result": "0x0000000000000000000000000000000000000000000000000000000005f5e100"
}
```
---
# eth_chainId
Source: https://basehub.org/api-reference/eth/eth_chainid/
Description: Returns the EIP-695 chain ID for the connected Base network — 0x2105 for Mainnet and 0x14a34 for Sepolia.
Returns the chain ID of the current network, per [EIP-695](https://eips.ethereum.org/EIPS/eip-695).
## Parameters
None.
## Returns
| Field | Type | Description |
| --- | --- | --- |
| `result` | string | The chain ID as a hexadecimal string. `"0x2105"` (8453) for Base Mainnet and `"0x14a34"` (84532) for Base Sepolia. |
## Example
### Request
```json
{
"jsonrpc": "2.0",
"method": "eth_chainId",
"params": [],
"id": 1
}
```
### Response
Base Mainnet:
```json
{
"jsonrpc": "2.0",
"id": 1,
"result": "0x2105"
}
```
Base Sepolia:
```json
{
"jsonrpc": "2.0",
"id": 1,
"result": "0x14a34"
}
```
---
# eth_estimateGas
Source: https://basehub.org/api-reference/eth/eth_estimategas/
Description: Estimates the gas required to execute a transaction on Base; use pending on Flashblocks to estimate against pre-confirmed state.
import { Aside, Tabs, TabItem } from '@astrojs/starlight/components';
Returns an estimate of how much gas a transaction would require. The reported value may exceed what the transaction actually consumes when executed.
## Parameters
### `transaction` (object, required)
The transaction object to estimate gas for.
| Field | Type | Description |
| --- | --- | --- |
| `from` | string | Address the transaction is sent from. Optional. |
| `to` | string | Address the transaction is sent to. Optional for contract deployments. |
| `gas` | string | Gas limit. Optional; a high default is used if omitted. |
| `gasPrice` | string | Gas price in wei for legacy transactions. Optional. |
| `maxFeePerGas` | string | EIP-1559 maximum total fee per gas. Optional. |
| `maxPriorityFeePerGas` | string | EIP-1559 maximum priority fee per gas. Optional. |
| `value` | string | Value to transfer in wei. Optional. |
| `data` | string | ABI-encoded call data. Optional. |
### `block` (string, optional)
Block to estimate against. Defaults to `"latest"`. Pass `"pending"` to estimate against pre-confirmed state.
## Returns
| Field | Type | Description |
| --- | --- | --- |
| `result` | string | The estimated gas amount as a hexadecimal integer. |
## Error codes
| Code | Message | Description |
| --- | --- | --- |
| `-32000` | execution reverted | The transaction would revert. The error `data` field may contain a revert reason. |
## Example
### Request
```bash
curl https://mainnet.base.org \
-X POST \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"method": "eth_estimateGas",
"params": [{
"from": "0xd3CdA913deB6f4967b2Ef66ae97DE114a83bcc01",
"to": "0x4200000000000000000000000000000000000006",
"value": "0x2c68af0bb14000"
}],
"id": 1
}'
```
```bash
curl https://mainnet.base.org \
-X POST \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"method": "eth_estimateGas",
"params": [{
"from": "0xd3CdA913deB6f4967b2Ef66ae97DE114a83bcc01",
"to": "0x4200000000000000000000000000000000000006",
"value": "0x2c68af0bb14000"
}, "pending"],
"id": 1
}'
```
### Response
```json
{
"jsonrpc": "2.0",
"id": 1,
"result": "0x5208"
}
```
---
# eth_feeHistory
Source: https://basehub.org/api-reference/eth/eth_feehistory/
Description: Returns historical base fees, gas-used ratios, and priority-fee percentile rewards across a range of Base blocks for fee estimation.
Returns historical gas data for a contiguous range of blocks, including per-block base fees and the distribution of priority fees. Useful for building EIP-1559 fee-estimation strategies.
## Parameters
| Position | Name | Type | Description |
| --- | --- | --- | --- |
| 1 | `blockCount` | string \| number | Number of blocks to return. Decimal or hexadecimal integer. The maximum is typically 1024. Required. |
| 2 | `newestBlock` | string | The highest block to include, as a block number in hex or a block tag (`"latest"`, `"pending"`, etc.). Required. |
| 3 | `rewardPercentiles` | array | Array of percentile values (0–100) to sample from each block's priority fees. For example, `[25, 50, 75]` returns the 25th, 50th, and 75th percentile priority fees. Required. |
## Returns
`result` (object):
| Field | Type | Description |
| --- | --- | --- |
| `oldestBlock` | string | The oldest block number in the result set (hex). |
| `baseFeePerGas` | array | Base fees per gas for each block, with one extra trailing entry for the next pending block, so the length is `blockCount + 1`. |
| `gasUsedRatio` | array | Gas-used to gas-limit ratios for each block (0.0 to 1.0); length is `blockCount`. |
| `baseFeePerBlobGas` | array | Base fees per blob gas for each block plus one extra entry for the next pending block (EIP-4844), giving a length of `blockCount + 1`. Currently always `"0x1"` on Base. |
| `blobGasUsedRatio` | array | Blob-gas-used ratios for each block (0.0 to 1.0), used to derive the next blob base fee (EIP-4844); length is `blockCount`. |
| `reward` | array | Two-dimensional array of priority-fee percentiles per block, matching the requested percentile values. |
## Example
### Request
```json
{
"jsonrpc": "2.0",
"method": "eth_feeHistory",
"params": ["0xa", "latest", [25, 50, 75]],
"id": 1
}
```
### Response
```json
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"oldestBlock": "0x158a0e0",
"baseFeePerGas": ["0xf5", "0xf7", "0xfa", "0xfc", "0xf8", "0xf5", "0xf2", "0xf0", "0xef", "0xf1", "0xf3"],
"gasUsedRatio": [0.45, 0.62, 0.38, 0.71, 0.55, 0.49, 0.43, 0.37, 0.52, 0.64],
"baseFeePerBlobGas": ["0x1", "0x1", "0x1", "0x1", "0x1", "0x1", "0x1", "0x1", "0x1", "0x1", "0x1"],
"blobGasUsedRatio": [0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
"reward": [
["0x1", "0x1", "0x2"],
["0x1", "0x1", "0x1"]
]
}
}
```
---
# eth_gasPrice
Source: https://basehub.org/api-reference/eth/eth_gasprice/
Description: Returns the current gas price on Base in wei as a hexadecimal string; for EIP-1559 fee estimation use eth_maxPriorityFeePerGas and eth_feeHistory.
Returns the current gas price in wei. For EIP-1559 transactions, prefer [`eth_maxPriorityFeePerGas`](/api-reference/eth/eth_maxpriorityfeepergas/) and [`eth_feeHistory`](/api-reference/eth/eth_feehistory/) instead.
## Parameters
None.
## Returns
| Field | Type | Description |
| --- | --- | --- |
| `result` | string | The current gas price in wei as a hexadecimal string. |
## Example
### Request
```json
{
"jsonrpc": "2.0",
"method": "eth_gasPrice",
"params": [],
"id": 1
}
```
### Response
```json
{
"jsonrpc": "2.0",
"id": 1,
"result": "0x5b8d80"
}
```
---
# eth_getBalance
Source: https://basehub.org/api-reference/eth/eth_getbalance/
Description: Returns the ETH balance of an account at a given block on Base; use pending on Flashblocks for ~200ms pre-confirmed balances.
import { Aside, Tabs, TabItem } from '@astrojs/starlight/components';
Returns the ETH balance of an address at a given block.
## Parameters
| Position | Name | Type | Description |
| --- | --- | --- | --- |
| 1 | `address` | string | The 20-byte address to query. Required. |
| 2 | `block` | string | Block number in hex, or `"latest"`, `"pending"`, `"safe"`, `"finalized"`, `"earliest"`. Pass `"pending"` for the pre-confirmed balance. Required. |
## Returns
| Field | Type | Description |
| --- | --- | --- |
| `result` | string | The balance in wei as a hexadecimal string. |
## Example
### Request
```bash
curl https://mainnet.base.org \
-X POST \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"method": "eth_getBalance",
"params": ["0x742d35Cc6634C0532925a3b8D4C9dD0b4f3BaEa", "latest"],
"id": 1
}'
```
```bash
curl https://mainnet.base.org \
-X POST \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"method": "eth_getBalance",
"params": ["0x742d35Cc6634C0532925a3b8D4C9dD0b4f3BaEa", "pending"],
"id": 1
}'
```
### Response
```json
{
"jsonrpc": "2.0",
"id": 1,
"result": "0x1a055690d9db80000"
}
```
---
# eth_getBlockByHash
Source: https://basehub.org/api-reference/eth/eth_getblockbyhash/
Description: Returns block information for a given 32-byte block hash on Base, with full transaction objects or just transaction hashes.
Returns information about a block identified by its hash.
## Parameters
| Position | Name | Type | Description |
| --- | --- | --- | --- |
| 1 | `blockHash` | string | The 32-byte block hash. Required. |
| 2 | `fullTransactions` | boolean | When `true`, returns full transaction objects; when `false`, returns only transaction hashes. Required. |
## Returns
| Field | Type | Description |
| --- | --- | --- |
| `result` | object \| null | A block object, or `null` if no block was found. See [`eth_getBlockByNumber`](/api-reference/eth/eth_getblockbynumber/) for the full field list. |
## Example
### Request
```json
{
"jsonrpc": "2.0",
"method": "eth_getBlockByHash",
"params": ["0x5c330e55a190f82ea486b61e5b12e27dfb4fb3cecfc5746886ef38ca1281bce8", false],
"id": 1
}
```
### Response
```json
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"number": "0x158a0e9",
"hash": "0x5c330e55a190f82ea486b61e5b12e27dfb4fb3cecfc5746886ef38ca1281bce8",
"parentHash": "0x9edc29b8b0a1e31d28616e40c16132ad0d58faa8bb952595b557526bdb9a960a",
"timestamp": "0x67bf8332",
"gasLimit": "0x3938700",
"gasUsed": "0xab3f",
"transactions": ["0x7ef8f8a0..."]
}
}
```
---
# eth_getBlockByNumber
Source: https://basehub.org/api-reference/eth/eth_getblockbynumber/
Description: Returns block data by number on Base; the pending tag returns the live pre-confirmed block updated every ~200ms.
import { Aside, Tabs, TabItem } from '@astrojs/starlight/components';
Returns information about a block identified by its number.
## Parameters
| Position | Name | Type | Description |
| --- | --- | --- | --- |
| 1 | `block` | string | Block number in hex, or `"latest"`, `"pending"`, `"safe"`, `"finalized"`, `"earliest"`. Pass `"pending"` to get the in-progress block. Required. |
| 2 | `fullTransactions` | boolean | When `true`, returns full transaction objects; when `false`, returns only transaction hashes. Required. |
## Returns
`result` (object or `null` if no block was found):
| Field | Type | Description |
| --- | --- | --- |
| `number` | string | Block number in hex. `null` when pending. |
| `hash` | string | Block hash. `null` when pending. |
| `parentHash` | string | Hash of the parent block. |
| `nonce` | string | PoW nonce. Always `"0x0000000000000000"` on Base (PoS). |
| `sha3Uncles` | string | Hash of the uncles list. Always empty on Base. |
| `logsBloom` | string | Bloom filter for the block's logs. |
| `transactionsRoot` | string | Root of the transaction trie. |
| `stateRoot` | string | Root of the final state trie. |
| `receiptsRoot` | string | Root of the receipts trie. |
| `miner` | string | Address of the fee recipient (coinbase). |
| `difficulty` | string | Always `"0x0"` on Base (PoS). |
| `totalDifficulty` | string | Always `"0x0"` on Base (PoS). |
| `mixHash` | string | Present on every block; repurposed for PoS consensus (bytes32 hex). |
| `extraData` | string | Arbitrary data field set by the sequencer. |
| `size` | string | Block size in bytes (hex). |
| `gasLimit` | string | Maximum gas allowed in this block (hex). |
| `gasUsed` | string | Total gas used in this block (hex). |
| `timestamp` | string | Unix timestamp (hex). |
| `transactions` | array | Array of transaction hashes or full transaction objects. |
| `uncles` | array | Always `[]` on Base. |
| `withdrawals` | array | Always `[]` on Base. |
| `withdrawalsRoot` | string | Merkle root of the withdrawals list (EIP-4895, bytes32 hex). |
| `baseFeePerGas` | string | EIP-1559 base fee per gas (hex). |
| `blobGasUsed` | string | Total blob gas used (EIP-4844, hex). |
| `excessBlobGas` | string | Excess blob gas for blob fee calculation (EIP-4844, hex). |
| `parentBeaconBlockRoot` | string | Parent beacon block root (EIP-4788). |
| `requestsHash` | string | Hash of requests (EIP-7685). |
## Flashblock-specific response fields
When you query `"pending"`, the response is a live snapshot of the block being built. A few fields behave differently:
| Field | Standard `latest` | Flashblocks `pending` |
| --- | --- | --- |
| `number` | Sealed block number | Current block number (being built) |
| `hash` | Final block hash | Hash of the partial block at this Flashblock index |
| `gasUsed` | Final gas used | Cumulative gas used up to this Flashblock |
| `transactions` | All sealed transactions | Transactions pre-confirmed so far |
| `blobGasUsed` | Final blob gas used | Propagated from cumulative Flashblock state |
## Example
### Request
```bash
curl https://mainnet.base.org \
-X POST \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"method": "eth_getBlockByNumber",
"params": ["latest", false],
"id": 1
}'
```
```bash
curl https://mainnet.base.org \
-X POST \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"method": "eth_getBlockByNumber",
"params": ["pending", false],
"id": 1
}'
```
### Response
```json
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"number": "0x158a0e9",
"hash": "0x5c330e55a190f82ea486b61e5b12e27dfb4fb3cecfc5746886ef38ca1281bce8",
"parentHash": "0x9edc29b8b0a1e31d28616e40c16132ad0d58faa8bb952595b557526bdb9a960a",
"timestamp": "0x67bf8332",
"gasLimit": "0x3938700",
"gasUsed": "0xab3f",
"baseFeePerGas": "0xfa",
"transactions": ["0x7ef8f8a0..."],
"withdrawals": [],
"miner": "0x4200000000000000000000000000000000000011"
}
}
```
---
# eth_getBlockReceipts
Source: https://basehub.org/api-reference/eth/eth_getblockreceipts/
Description: Returns every transaction receipt for a block on Base in one call; pair with pending on Flashblocks for pre-confirmed receipts.
import { Aside, Tabs, TabItem } from '@astrojs/starlight/components';
Returns every transaction receipt for a given block in a single call.
## Parameters
| Position | Name | Type | Description |
| --- | --- | --- | --- |
| 1 | `block` | string | Block number in hex, or `"latest"`, `"pending"`, `"safe"`, `"finalized"`, `"earliest"`. Required. |
## Returns
| Field | Type | Description |
| --- | --- | --- |
| `result` | array | Array of receipt objects, one per transaction in the block. See [`eth_getTransactionReceipt`](/api-reference/eth/eth_gettransactionreceipt/) for the receipt object shape. |
## Example
### Request
```bash
curl https://mainnet.base.org \
-X POST -H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","method":"eth_getBlockReceipts","params":["latest"],"id":1}'
```
```bash
curl https://mainnet.base.org \
-X POST -H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","method":"eth_getBlockReceipts","params":["pending"],"id":1}'
```
### Response
```json
{
"jsonrpc": "2.0",
"id": 1,
"result": [
{
"transactionHash": "0xabc123...",
"blockNumber": "0x158a0e9",
"status": "0x1",
"gasUsed": "0x5208",
"type": "0x2"
}
]
}
```
---
# eth_getBlockTransactionCountByHash
Source: https://basehub.org/api-reference/eth/eth_getblocktransactioncountbyhash/
Description: Returns the number of transactions included in the Base block matching the supplied 32-byte block hash.
Returns the number of transactions in a block matching the given block hash.
## Parameters
| Position | Name | Type | Description |
| --- | --- | --- | --- |
| 1 | `blockHash` | string | The 32-byte block hash. Required. |
## Returns
| Field | Type | Description |
| --- | --- | --- |
| `result` | string | The number of transactions in the block as a hexadecimal integer. `null` if no block was found. |
## Example
### Request
```json
{
"jsonrpc": "2.0",
"method": "eth_getBlockTransactionCountByHash",
"params": ["0x5c330e55a190f82ea486b61e5b12e27dfb4fb3cecfc5746886ef38ca1281bce8"],
"id": 1
}
```
### Response
```json
{
"jsonrpc": "2.0",
"id": 1,
"result": "0x1f"
}
```
---
# eth_getBlockTransactionCountByNumber
Source: https://basehub.org/api-reference/eth/eth_getblocktransactioncountbynumber/
Description: Returns the transaction count for a Base block by number; the pending tag counts pre-confirmed transactions in the live Flashblock.
import { Aside } from '@astrojs/starlight/components';
Returns the number of transactions in a block matching the given block number.
## Parameters
| Position | Name | Type | Description |
| --- | --- | --- | --- |
| 1 | `block` | string | Block number in hex, or `"latest"`, `"pending"`, `"safe"`, `"finalized"`, `"earliest"`. Required. |
## Returns
| Field | Type | Description |
| --- | --- | --- |
| `result` | string | The number of transactions in the block as a hexadecimal integer. |
## Example
### Request
```json
{
"jsonrpc": "2.0",
"method": "eth_getBlockTransactionCountByNumber",
"params": ["latest"],
"id": 1
}
```
### Response
```json
{
"jsonrpc": "2.0",
"id": 1,
"result": "0x1f"
}
```
---
# eth_getCode
Source: https://basehub.org/api-reference/eth/eth_getcode/
Description: Returns the deployed bytecode at an address on Base; use pending on Flashblocks to detect newly deployed contracts before block finalization.
import { Aside, Tabs, TabItem } from '@astrojs/starlight/components';
Returns the compiled bytecode at a given address. Returns `"0x"` for externally owned accounts (EOAs).
## Parameters
| Position | Name | Type | Description |
| --- | --- | --- | --- |
| 1 | `address` | string | The 20-byte address to query. Required. |
| 2 | `block` | string | Block number in hex, or `"latest"`, `"pending"`, `"safe"`, `"finalized"`, `"earliest"`. Required. |
## Returns
| Field | Type | Description |
| --- | --- | --- |
| `result` | string | The bytecode at the address as a hex string. `"0x"` if there is no code. |
## Example
### Request
```bash
curl https://mainnet.base.org \
-X POST \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"method": "eth_getCode",
"params": ["0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "latest"],
"id": 1
}'
```
```bash
curl https://mainnet.base.org \
-X POST \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"method": "eth_getCode",
"params": ["0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "pending"],
"id": 1
}'
```
### Response
```json
{
"jsonrpc": "2.0",
"id": 1,
"result": "0x608060405234801561001057600080fd5b50..."
}
```
---
# eth_getLogs
Source: https://basehub.org/api-reference/eth/eth_getlogs/
Description: Returns event logs on Base matching a filter object; pair with pending on Flashblocks to query logs from pre-confirmed transactions.
import { Aside, Tabs, TabItem } from '@astrojs/starlight/components';
Returns an array of all logs matching a filter object. The primary tool for indexing on-chain events.
## Parameters
### `filter` (object, required)
Filter options. At least one criterion should be provided.
| Field | Type | Description |
| --- | --- | --- |
| `fromBlock` | string | Start of the block range. Block number in hex or a block tag. Pass `"pending"` to include pre-confirmed logs. Defaults to `"latest"`. |
| `toBlock` | string | End of the block range. Block number in hex or a block tag. Defaults to `"latest"`. |
| `address` | string \| array | A contract address or array of addresses to filter by. Optional. |
| `topics` | array | Array of 32-byte topic filters. Each position can be `null` (match any), a single topic hex string, or an array of hex strings (match any in the array). Position 0 is typically the `keccak256` hash of the event signature. Optional. |
| `blockHash` | string | Restricts logs to the block with this hash. When supplied, `fromBlock` and `toBlock` are ignored. Optional. |
## Returns
`result` (array of log objects):
| Field | Type | Description |
| --- | --- | --- |
| `address` | string | 20-byte address of the contract that emitted the log. |
| `topics` | array | Array of 0–4 indexed 32-byte topics. Topic 0 is typically the event signature hash. |
| `data` | string | ABI-encoded non-indexed event parameters. |
| `blockNumber` | string | Block number in which this log was emitted (hex). |
| `blockTimestamp` | string | Unix timestamp (hex) of the block that contains this log. An OP Stack extension to the standard Ethereum log schema. |
| `transactionHash` | string | 32-byte hash of the transaction that emitted this log. |
| `transactionIndex` | string | Index of the transaction in the block (hex). |
| `blockHash` | string | 32-byte hash of the block. |
| `logIndex` | string | The log's index position within the block (hex). |
| `removed` | boolean | `true` if the log was removed due to a chain reorganization. |
## Example
### Request
```bash
curl https://mainnet.base.org \
-X POST \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"method": "eth_getLogs",
"params": [{
"fromBlock": "0x12ced00",
"toBlock": "0x12ced28",
"address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
"topics": ["0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"]
}],
"id": 1
}'
```
```bash
curl https://mainnet.base.org \
-X POST \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"method": "eth_getLogs",
"params": [{
"fromBlock": "pending",
"toBlock": "pending",
"address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
"topics": ["0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"]
}],
"id": 1
}'
```
### Response
```json
{
"jsonrpc": "2.0",
"id": 1,
"result": [
{
"address": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
"topics": [
"0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
"0x000000000000000000000000d3cda913deb6f4967b2ef66ae97de114a83bcc01",
"0x0000000000000000000000004200000000000000000000000000000000000006"
],
"data": "0x0000000000000000000000000000000000000000000000000000000005f5e100",
"blockNumber": "0x12ced28",
"blockTimestamp": "0x6a1092f7",
"transactionHash": "0xb903239f8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568238",
"transactionIndex": "0x0",
"blockHash": "0x3a4e8c5d7f2b1a6e9d0c4f8b3e7a2d5c8f1b4e7a0d3c6f9b2e5a8d1c4f7b0e3",
"logIndex": "0x0",
"removed": false
}
]
}
```
---
# eth_getStorageAt
Source: https://basehub.org/api-reference/eth/eth_getstorageat/
Description: Returns the 32-byte value stored at a contract storage slot on Base; use pending on Flashblocks for pre-confirmed storage reads.
import { Aside, Tabs, TabItem } from '@astrojs/starlight/components';
Returns the value held at a storage position for a given contract address.
## Parameters
| Position | Name | Type | Description |
| --- | --- | --- | --- |
| 1 | `address` | string | The 20-byte address that owns the storage. Required. |
| 2 | `position` | string | The storage slot position as a hexadecimal integer. Required. |
| 3 | `block` | string | Block number in hex, or `"latest"`, `"pending"`, `"safe"`, `"finalized"`, `"earliest"`. Required. |
## Returns
| Field | Type | Description |
| --- | --- | --- |
| `result` | string | The value at the storage position as a 32-byte hex string. |
## Example
### Request
```bash
curl https://mainnet.base.org \
-X POST \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"method": "eth_getStorageAt",
"params": ["0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "0x0", "latest"],
"id": 1
}'
```
```bash
curl https://mainnet.base.org \
-X POST \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"method": "eth_getStorageAt",
"params": ["0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "0x0", "pending"],
"id": 1
}'
```
### Response
```json
{
"jsonrpc": "2.0",
"id": 1,
"result": "0x0000000000000000000000000000000000000000000000000000000000000001"
}
```
---
# eth_getTransactionByBlockHashAndIndex
Source: https://basehub.org/api-reference/eth/eth_gettransactionbyblockhashandindex/
Description: Returns transaction data on Base by combining a 32-byte block hash with the transaction's zero-based index inside that block.
Returns information about a transaction identified by a block hash and the transaction's index position within that block.
## Parameters
| Position | Name | Type | Description |
| --- | --- | --- | --- |
| 1 | `blockHash` | string | The 32-byte block hash. Required. |
| 2 | `index` | string | The transaction index position as a hexadecimal integer. Required. |
## Returns
| Field | Type | Description |
| --- | --- | --- |
| `result` | object \| null | A transaction object, or `null` if not found. See [`eth_getTransactionByHash`](/api-reference/eth/eth_gettransactionbyhash/) for the full field list. |
## Example
### Request
```json
{
"jsonrpc": "2.0",
"method": "eth_getTransactionByBlockHashAndIndex",
"params": ["0x5c330e55a190f82ea486b61e5b12e27dfb4fb3cecfc5746886ef38ca1281bce8", "0x0"],
"id": 1
}
```
### Response
The example below is a type `0x7e` deposit transaction at index `0x0`, which carries the OP Stack deposit fields (`sourceHash`, `mint`, `depositReceiptVersion`). See [`eth_getTransactionByHash`](/api-reference/eth/eth_gettransactionbyhash/) for the full field list.
```json
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"blockHash": "0x491bca01d4bc076d60833dbd973fe031a74e7ae31866bf70d077619e09edb6ff",
"blockNumber": "0x2c31b0b",
"depositReceiptVersion": "0x1",
"from": "0xdeaddeaddeaddeaddeaddeaddeaddeaddead0001",
"gas": "0xf4240",
"gasPrice": "0x0",
"hash": "0x03c8f106f18ad94190e763e21b584c5825b2f4c61f1274c0e8abe65b4476cd51",
"input": "0x3db6be2b...",
"mint": "0x0",
"nonce": "0x2c31b0e",
"r": "0x0",
"s": "0x0",
"sourceHash": "0xe40ffb1b9f98a24b21e90e3a3cfe49de1eed195618e943da4d029881d3b3e055",
"to": "0x4200000000000000000000000000000000000015",
"transactionIndex": "0x0",
"type": "0x7e",
"v": "0x0",
"value": "0x0",
"yParity": "0x0"
}
}
```
---
# eth_getTransactionByBlockNumberAndIndex
Source: https://basehub.org/api-reference/eth/eth_gettransactionbyblocknumberandindex/
Description: Returns transaction data on Base by pairing a block number or tag with the transaction's zero-based index inside that block.
Returns information about a transaction identified by a block number and the transaction's index position within that block.
## Parameters
| Position | Name | Type | Description |
| --- | --- | --- | --- |
| 1 | `block` | string | Block number in hex, or `"latest"`, `"pending"`, `"safe"`, `"finalized"`, `"earliest"`. Required. |
| 2 | `index` | string | The transaction index position as a hexadecimal integer. Required. |
## Returns
| Field | Type | Description |
| --- | --- | --- |
| `result` | object \| null | A transaction object, or `null` if not found. See [`eth_getTransactionByHash`](/api-reference/eth/eth_gettransactionbyhash/) for the full field list. |
## Example
### Request
```json
{
"jsonrpc": "2.0",
"method": "eth_getTransactionByBlockNumberAndIndex",
"params": ["latest", "0x0"],
"id": 1
}
```
### Response
The example below is a type `0x7e` deposit transaction at index `0x0`, which carries the OP Stack deposit fields (`sourceHash`, `mint`, `depositReceiptVersion`). See [`eth_getTransactionByHash`](/api-reference/eth/eth_gettransactionbyhash/) for the full field list.
```json
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"blockHash": "0x491bca01d4bc076d60833dbd973fe031a74e7ae31866bf70d077619e09edb6ff",
"blockNumber": "0x2c31b0b",
"depositReceiptVersion": "0x1",
"from": "0xdeaddeaddeaddeaddeaddeaddeaddeaddead0001",
"gas": "0xf4240",
"gasPrice": "0x0",
"hash": "0x03c8f106f18ad94190e763e21b584c5825b2f4c61f1274c0e8abe65b4476cd51",
"input": "0x3db6be2b...",
"mint": "0x0",
"nonce": "0x2c31b0e",
"r": "0x0",
"s": "0x0",
"sourceHash": "0xe40ffb1b9f98a24b21e90e3a3cfe49de1eed195618e943da4d029881d3b3e055",
"to": "0x4200000000000000000000000000000000000015",
"transactionIndex": "0x0",
"type": "0x7e",
"v": "0x0",
"value": "0x0",
"yParity": "0x0"
}
}
```
---
# eth_getTransactionByHash
Source: https://basehub.org/api-reference/eth/eth_gettransactionbyhash/
Description: Returns full transaction data for a 32-byte transaction hash on Base, or null when the node has not seen the transaction.
Returns information about a transaction given its hash. Returns `null` for unknown transactions.
## Parameters
| Position | Name | Type | Description |
| --- | --- | --- | --- |
| 1 | `transactionHash` | string | The 32-byte transaction hash. Required. |
## Returns
`result` (object, or `null` if the transaction was not found):
| Field | Type | Description |
| --- | --- | --- |
| `hash` | string | 32-byte transaction hash. |
| `nonce` | string | Number of transactions sent by the sender prior to this one (hex). |
| `blockHash` | string | 32-byte hash of the block containing this transaction. `null` if pending. |
| `blockNumber` | string | Block number (hex). `null` if pending. |
| `transactionIndex` | string | Index position in the block (hex). `null` if pending. |
| `from` | string | 20-byte sender address. |
| `to` | string | 20-byte recipient address. `null` for contract deployments. |
| `value` | string | ETH value transferred in wei (hex). |
| `gas` | string | Gas provided by the sender (hex). |
| `gasPrice` | string | Gas price in wei. For EIP-1559 transactions, this is the effective gas price paid (hex). |
| `maxFeePerGas` | string | EIP-1559 maximum total fee per gas (hex). Present for type `0x2` transactions only; absent on type `0x7e`. |
| `maxPriorityFeePerGas` | string | EIP-1559 maximum priority fee per gas (hex). Present for type `0x2` transactions only; absent on type `0x7e`. |
| `input` | string | ABI-encoded call data. `"0x"` for plain ETH transfers. |
| `type` | string | Transaction type: `"0x0"` Legacy, `"0x1"` Access List, `"0x2"` EIP-1559, `"0x7e"` Deposit (L1→L2). |
| `chainId` | string | Chain ID the transaction is valid for. `"0x2105"` for Base Mainnet, `"0x14a34"` for Base Sepolia. Not present on type `0x7e`. |
| `accessList` | array | List of addresses and storage keys pre-declared by the transaction (EIP-2930). Present for type `0x1` and `0x2` transactions. |
| `v` | string | ECDSA recovery ID (hex). |
| `r` | string | 32-byte ECDSA signature component r (hex). Always `"0x0"` for type `0x7e`. |
| `s` | string | 32-byte ECDSA signature component s (hex). Always `"0x0"` for type `0x7e`. |
| `yParity` | string | Signature parity (hex). Always `"0x0"` for type `0x7e` deposits. |
| `sourceHash` | string | Identifies the deposit source (32-byte hex). Present on type `0x7e` only. |
| `mint` | string | ETH minted on L2 as part of the deposit (hex), usually `"0x0"`. Present on type `0x7e` only. |
| `depositReceiptVersion` | string | Version of the deposit receipt format (hex). Present on type `0x7e` only. |
Base carries the Ethereum-standard transaction types — `0x0` legacy, `0x1` EIP-2930, `0x2` EIP-1559 — plus the OP Stack deposit type `0x7e`. Deposits are injected by the sequencer at the top of each block: they omit the fee and signature fields a normal transaction carries (`maxFeePerGas`, `accessList`, `chainId`) and instead expose `sourceHash`, `mint`, `depositReceiptVersion`, and a zeroed `yParity`.
## Example
### Request
```json
{
"jsonrpc": "2.0",
"method": "eth_getTransactionByHash",
"params": ["0xb903239f8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568238"],
"id": 1
}
```
### Response
```json
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"hash": "0xb903239f8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568238",
"nonce": "0x1b",
"blockHash": "0x3a4e8c5d7f2b1a6e9d0c4f8b3e7a2d5c8f1b4e7a0d3c6f9b2e5a8d1c4f7b0e3",
"blockNumber": "0x12ced28",
"transactionIndex": "0x0",
"from": "0xd3CdA913deB6f4967b2Ef66ae97DE114a83bcc01",
"to": "0x4200000000000000000000000000000000000006",
"value": "0x2c68af0bb14000",
"gas": "0x5208",
"gasPrice": "0x3b9aca00",
"maxFeePerGas": "0x77359400",
"maxPriorityFeePerGas": "0x3b9aca00",
"input": "0x",
"type": "0x2",
"chainId": "0x2105",
"accessList": [],
"v": "0x1",
"r": "0x1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b",
"s": "0x2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c"
}
}
```
When the node has not seen the transaction:
```json
{
"jsonrpc": "2.0",
"id": 1,
"result": null
}
```
---
# eth_getTransactionCount
Source: https://basehub.org/api-reference/eth/eth_gettransactioncount/
Description: Returns the transaction count (nonce) for an address. Use the pending tag to include pre-confirmed transactions.
Returns the number of transactions sent from an address. The value is the account nonce — pass it as `nonce` when constructing the next transaction.
Querying with `"pending"` against `https://mainnet.base.org` returns the nonce inclusive of every pre-confirmed transaction and refreshes every ~200ms. This eliminates nonce gaps when an agent submits transactions at high frequency.
## Parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `address` | string | Yes | The 20-byte address to query. |
| `block` | string | Yes | A block number in hex, or one of `"latest"`, `"pending"`, `"safe"`, `"finalized"`, `"earliest"`. Use `"pending"` to include all pre-confirmed transactions in the count. |
## Returns
| Field | Type | Description |
| --- | --- | --- |
| `result` | string | The transaction count (nonce) as a hexadecimal string. |
## Example
### Request (standard, latest confirmed)
```bash
curl https://mainnet.base.org \
-X POST \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"method": "eth_getTransactionCount",
"params": ["0x742d35Cc6634C0532925a3b8D4C9dD0b4f3BaEa", "latest"],
"id": 1
}'
```
### Request (Flashblocks pending nonce, ~200ms)
```bash
curl https://mainnet.base.org \
-X POST \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"method": "eth_getTransactionCount",
"params": ["0x742d35Cc6634C0532925a3b8D4C9dD0b4f3BaEa", "pending"],
"id": 1
}'
```
### Response
```json
{
"jsonrpc": "2.0",
"id": 1,
"result": "0x4d2"
}
```
---
# eth_getTransactionReceipt
Source: https://basehub.org/api-reference/eth/eth_gettransactionreceipt/
Description: Returns the receipt for a mined transaction by hash, or null when the transaction is still pending or has not been included in a block.
Returns the receipt for a transaction identified by its hash. Returns `null` while the transaction is still pending or has not yet been mined.
Receipts are only emitted once a transaction is included in a block. To track a transaction beforehand, call [`base_transactionStatus`](/api-reference/flashblocks/base_transactionStatus/) to confirm it has reached the mempool, or subscribe to [`newFlashblockTransactions`](/api-reference/flashblocks/newFlashblockTransactions/) to detect its pre-confirmation inside a Flashblock.
## Parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `transactionHash` | string | Yes | The 32-byte transaction hash. |
## Returns
`result` is the receipt object, or `null` if the transaction has not been mined.
| Field | Type | Description |
| --- | --- | --- |
| `transactionHash` | string | 32-byte transaction hash. |
| `transactionIndex` | string | Position of the transaction in the block (hex). |
| `blockHash` | string | 32-byte hash of the block containing this transaction. |
| `blockNumber` | string | Block number (hex). |
| `from` | string | 20-byte sender address. |
| `to` | string | 20-byte recipient address. `null` for contract deployments. |
| `cumulativeGasUsed` | string | Total gas used in the block up to and including this transaction (hex). |
| `effectiveGasPrice` | string | Actual gas price paid per unit of gas for this transaction (hex). |
| `gasUsed` | string | Gas used by this specific transaction (hex). |
| `contractAddress` | string \| null | Address of the deployed contract, or `null` if the transaction was not a deployment. |
| `logs` | array | Array of log objects emitted by this transaction. |
| `logsBloom` | string | 256-byte bloom filter for the logs in this receipt. |
| `type` | string | Transaction type: `"0x0"` Legacy, `"0x1"` Access List, `"0x2"` EIP-1559, `"0x7e"` Deposit (L1→L2). |
| `status` | string | `"0x1"` for success, `"0x0"` for failure (revert). |
| `blobGasUsed` | string | Blob gas consumed by this transaction (EIP-4844). `null` for non-blob transactions. |
| `blobGasPrice` | string | Blob gas price at the time of this transaction (EIP-4844). `null` for non-blob transactions. |
| `l1Fee` | string | Total L1 data fee paid for this transaction (hex). OP Stack L2 field. |
| `l1GasUsed` | string | L1 gas attributed to this transaction's L1 data portion (hex). OP Stack L2 field. |
| `l1GasPrice` | string | L1 gas price at the time of inclusion (hex). OP Stack L2 field. |
| `l1BlobBaseFee` | string | L1 blob base fee at the time of inclusion (hex). OP Stack L2 field. |
| `l1BlobBaseFeeScalar` | string | Scalar applied to the blob base fee when computing the L1 fee (hex). OP Stack L2 field. |
| `l1BaseFeeScalar` | string | Scalar applied to the L1 base fee when computing the L1 fee (hex). OP Stack L2 field. |
| `daFootprintGasScalar` | string | Base-specific data-availability footprint scalar (hex). |
| `depositNonce` | string | Nonce of the deposit transaction (hex). Present on type `0x7e` transactions only. |
| `depositReceiptVersion` | string | Deposit receipt format version (hex). Present on type `0x7e` transactions only. |
## Error codes
| Code | Message | Description |
| --- | --- | --- |
| `-32000` | transaction indexing is in progress | The node is still indexing transactions. Retry once the node finishes syncing. |
## Pre-confirmed receipt data
Earlier client versions surfaced abbreviated receipts inside the `metadata.receipts` map of the Flashblocks infrastructure stream. That field was removed in client version v0.8.0 — `metadata` now carries only `block_number`. To obtain receipt data before a block seals, poll this method with the `"pending"` tag, or subscribe to [`newFlashblockTransactions`](/api-reference/flashblocks/newFlashblockTransactions/) with `full: true` for a real-time stream of pre-confirmed transactions that includes their logs.
## Example
### Request
```json
{
"jsonrpc": "2.0",
"method": "eth_getTransactionReceipt",
"params": ["0xb903239f8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568238"],
"id": 1
}
```
### Response
```json
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"transactionHash": "0xb903239f8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568238",
"transactionIndex": "0x0",
"blockHash": "0x3a4e8c5d7f2b1a6e9d0c4f8b3e7a2d5c8f1b4e7a0d3c6f9b2e5a8d1c4f7b0e3",
"blockNumber": "0x12ced28",
"from": "0xd3CdA913deB6f4967b2Ef66ae97DE114a83bcc01",
"to": "0x4200000000000000000000000000000000000006",
"cumulativeGasUsed": "0x5208",
"effectiveGasPrice": "0x3b9aca00",
"gasUsed": "0x5208",
"contractAddress": null,
"logs": [],
"logsBloom": "0x00000000000000000000000000000000...",
"status": "0x1",
"type": "0x2"
}
}
```
### Response (not found)
```json
{
"jsonrpc": "2.0",
"id": 1,
"result": null
}
```
---
# eth_maxPriorityFeePerGas
Source: https://basehub.org/api-reference/eth/eth_maxpriorityfeepergas/
Description: Returns the suggested EIP-1559 priority fee (tip) per gas to pay the sequencer on top of the base fee.
Returns a suggested value for `maxPriorityFeePerGas` to use in an EIP-1559 transaction. The value is the tip paid to the sequencer on top of the base fee.
## Parameters
None.
## Returns
| Field | Type | Description |
| --- | --- | --- |
| `result` | string | The suggested priority fee per gas in wei as a hexadecimal string. |
## Example
### Request
```json
{
"jsonrpc": "2.0",
"method": "eth_maxPriorityFeePerGas",
"params": [],
"id": 1
}
```
### Response
```json
{
"jsonrpc": "2.0",
"id": 1,
"result": "0xf4240"
}
```
---
# eth_sendRawTransaction
Source: https://basehub.org/api-reference/eth/eth_sendrawtransaction/
Description: Submits a pre-signed RLP-encoded transaction to the network. Submit to a Flashblocks preconf endpoint for ~200ms pre-confirmation.
Submits a pre-signed, RLP-encoded transaction to the network and returns the resulting transaction hash.
Submit to `https://mainnet.base.org` to have the transaction considered for the next Flashblock (~200ms). After submission, call [`base_transactionStatus`](/api-reference/flashblocks/base_transactionStatus/) to confirm receipt in the mempool, then subscribe to [`newFlashblockTransactions`](/api-reference/flashblocks/newFlashblockTransactions/) to detect pre-confirmation.
## Parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | string | Yes | The signed transaction as an RLP-encoded hex string. Typically produced by a wallet library such as viem, ethers.js, or web3.js. |
## Returns
| Field | Type | Description |
| --- | --- | --- |
| `result` | string | The 32-byte transaction hash, returned when the transaction is accepted into the mempool. |
## Error codes
| Code | Message | Description |
| --- | --- | --- |
| `-32000` | nonce too low | The transaction nonce is below the current account nonce. |
| `-32000` | insufficient funds for gas * price + value | The sender's balance cannot cover the gas cost plus the value transferred. |
| `-32000` | already known | An identical transaction is already in the mempool. |
| `-32000` | replacement transaction underpriced | A replacement transaction must increase the gas price by at least 10%. |
## Example
### Request (standard)
```bash
curl https://mainnet.base.org \
-X POST -H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","method":"eth_sendRawTransaction","params":["0x02f86b82210501843b9aca008477359400825208944200000000000000000000000000000000000006872c68af0bb1400080c001a0..."],"id":1}'
```
### Request (Flashblocks preconf submission)
```bash
curl https://mainnet.base.org \
-X POST -H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","method":"eth_sendRawTransaction","params":["0x02f86b82210501843b9aca008477359400825208944200000000000000000000000000000000000006872c68af0bb1400080c001a0..."],"id":1}'
```
### Response
```json
{
"jsonrpc": "2.0",
"id": 1,
"result": "0xb903239f8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568238"
}
```
---
# eth_subscribe
Source: https://basehub.org/api-reference/eth/eth_subscribe/
Description: Opens a real-time WebSocket subscription for new blocks, logs, and pending transactions over a node-provider WebSocket endpoint.
Opens a real-time event subscription over a WebSocket connection. Returns a subscription ID; events arrive as `eth_subscription` notifications without the client needing to poll.
The public Base endpoints (`mainnet.base.org`, `sepolia.base.org`) are HTTP only — WebSocket connections are not served there. For `eth_subscribe` and the Flashblocks streams, connect through a node provider such as Alchemy or QuickNode that offers WebSocket support for Base. On a Flashblocks-aware endpoint, `newHeads` fires every ~200ms (once per Flashblock) rather than every ~2 seconds, and three additional subscription types become available: [`newFlashblockTransactions`](/api-reference/flashblocks/newFlashblockTransactions/), [`pendingLogs`](/api-reference/flashblocks/pendingLogs/), and [`newFlashblocks`](/api-reference/flashblocks/newFlashblocks/).
## Parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `subscriptionType` | string | Yes | The event type to subscribe to. |
| `filterOptions` | object | No | Optional filter object. Only applicable for the `"logs"` subscription type. |
The `filterOptions` object accepts:
| Field | Type | Description |
| --- | --- | --- |
| `address` | string \| array | A contract address or array of addresses to filter by. Optional. |
| `topics` | array | Array of topic filters in the same format as `eth_getLogs`. Optional. |
## Subscription types
| Type | Description | Notification payload |
| --- | --- | --- |
| `newHeads` | Fires for each new block appended to the chain | Full block header object — same shape as [`eth_getBlockByNumber`](/api-reference/eth/eth_getblockbynumber/) with `hydrated: false` |
| `logs` | Fires for each new log matching the filter criteria | Log object |
| `newPendingTransactions` | Fires for each new transaction hash added to the mempool | Transaction hash string |
## Returns
| Field | Type | Description |
| --- | --- | --- |
| `result` | string | A hex-encoded subscription ID. Every event notification from this subscription includes the same ID under `params.subscription`. |
Event notifications arrive as unsolicited JSON-RPC messages:
```json
{
"jsonrpc": "2.0",
"method": "eth_subscription",
"params": {
"subscription": "0x1887ec8b9589ccad00000000000532da",
"result": { ... }
}
}
```
## Example
### Subscribe to newHeads
```json
{"jsonrpc": "2.0", "method": "eth_subscribe", "params": ["newHeads"], "id": 1}
```
### Subscribe to logs (with filter)
```json
{
"jsonrpc": "2.0",
"id": 1,
"method": "eth_subscribe",
"params": [
"logs",
{
"address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
"topics": ["0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"]
}
]
}
```
### Subscription ID response
```json
{"jsonrpc": "2.0", "id": 1, "result": "0x1887ec8b9589ccad00000000000532da"}
```
### newHeads event
```json
{
"jsonrpc": "2.0",
"method": "eth_subscription",
"params": {
"subscription": "0x1887ec8b9589ccad00000000000532da",
"result": {
"number": "0x12ced29",
"hash": "0x4b5e8c5d7f2b1a6e9d0c4f8b3e7a2d5c8f1b4e7a0d3c6f9b2e5a8d1c4f7b0e4",
"parentHash": "0x3a4e8c5d7f2b1a6e9d0c4f8b3e7a2d5c8f1b4e7a0d3c6f9b2e5a8d1c4f7b0e3",
"gasLimit": "0x1c9c380",
"gasUsed": "0xa410",
"timestamp": "0x6783a5d2",
"baseFeePerGas": "0x3b9aca00"
}
}
}
```
### logs event
```json
{
"jsonrpc": "2.0",
"method": "eth_subscription",
"params": {
"subscription": "0x2a7bc8d4e3f5a6b1c2d3e4f5a6b7c8d9",
"result": {
"address": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
"topics": [
"0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
"0x000000000000000000000000d3cda913deb6f4967b2ef66ae97de114a83bcc01",
"0x0000000000000000000000004200000000000000000000000000000000000006"
],
"data": "0x0000000000000000000000000000000000000000000000000000000005f5e100",
"blockNumber": "0x12ced29",
"transactionHash": "0xc903239f...",
"blockHash": "0x4b5e8c5d...",
"logIndex": "0x0",
"removed": false
}
}
}
```
---
# eth_syncing
Source: https://basehub.org/api-reference/eth/eth_syncing/
Description: Returns the sync status of the node. Returns false when the node is fully synced, otherwise an object describing sync progress.
Returns the sync status of the node. Returns `false` when the node is fully synced.
## Parameters
None.
## Returns
`result` is `false` if the node is fully synced. Otherwise it is a sync status object with the following fields:
| Field | Type | Description |
| --- | --- | --- |
| `startingBlock` | string | Block at which the sync started (hex). |
| `currentBlock` | string | Current block being processed (hex). |
| `highestBlock` | string | Estimated highest block (hex). |
## Example
### Request
```json
{
"jsonrpc": "2.0",
"method": "eth_syncing",
"params": [],
"id": 1
}
```
### Response (synced)
```json
{
"jsonrpc": "2.0",
"id": 1,
"result": false
}
```
---
# eth_unsubscribe
Source: https://basehub.org/api-reference/eth/eth_unsubscribe/
Description: Cancels an active WebSocket subscription created with eth_subscribe and invalidates the subscription ID.
Cancels a subscription created with [`eth_subscribe`](/api-reference/eth/eth_subscribe/). The subscription ID is no longer valid after this call.
## Parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `subscriptionId` | string | Yes | The subscription ID returned by `eth_subscribe`. |
## Returns
| Field | Type | Description |
| --- | --- | --- |
| `result` | boolean | `true` if the subscription was successfully cancelled, `false` if the subscription ID was not found. |
## Example
### Request
```json
{
"jsonrpc": "2.0",
"id": 1,
"method": "eth_unsubscribe",
"params": ["0x1887ec8b9589ccad00000000000532da"]
}
```
### Response (success)
```json
{
"jsonrpc": "2.0",
"id": 1,
"result": true
}
```
### Response (not found)
```json
{
"jsonrpc": "2.0",
"id": 1,
"result": false
}
```
---
# net_version
Source: https://basehub.org/api-reference/eth/net_version/
Description: Returns the current network ID as a decimal string. Base Mainnet is 8453 and Base Sepolia is 84532.
Returns the current network ID as a decimal string.
## Parameters
None.
## Returns
| Field | Type | Description |
| --- | --- | --- |
| `result` | string | The network ID as a decimal string. `"8453"` for Base Mainnet, `"84532"` for Base Sepolia. |
## Example
### Request
```json
{
"jsonrpc": "2.0",
"method": "net_version",
"params": [],
"id": 1
}
```
### Response (Base Mainnet)
```json
{
"jsonrpc": "2.0",
"id": 1,
"result": "8453"
}
```
---
# web3_clientVersion
Source: https://basehub.org/api-reference/eth/web3_clientversion/
Description: Returns the version string identifying the underlying node client software running the JSON-RPC endpoint.
import { Aside } from '@astrojs/starlight/components';
Returns the version string of the node client software.
## Parameters
None.
## Returns
| Field | Type | Description |
| --- | --- | --- |
| `result` | string | The client version string, formatted as `/-//base/`. Treat it as opaque — the format shifts with node software updates, so avoid parsing it. |
## Example
### Request
```json
{
"jsonrpc": "2.0",
"method": "web3_clientVersion",
"params": [],
"id": 1
}
```
### Response
```json
{
"jsonrpc": "2.0",
"id": 1,
"result": "reth/v1.11.3-2ac58a2/x86_64-unknown-linux-gnu/base/v0.9.0"
}
```
---
# base_transactionStatus
Source: https://basehub.org/api-reference/flashblocks/base_transactionstatus/
Description: Reports whether a transaction hash is present in the node mempool, useful for confirming submission before pre-confirmation lands.
Reports whether a specific transaction is present in the node mempool. Use it to confirm that a submitted transaction has been received before it appears in a Flashblock.
A Base pre-confirmation method served on the standard public endpoints (`https://mainnet.base.org` / `https://sepolia.base.org`), which are all Flashblocks-enabled.
Requires [base/base](https://github.com/base/base) minimum client version v0.3.0.
## Parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `transactionHash` | string | Yes | The 32-byte transaction hash to query. |
## Returns
`result` is the transaction status object:
| Field | Type | Description |
| --- | --- | --- |
| `status` | string | `"Known"` if the transaction is present in the mempool. `"Unknown"` if the node has not seen it. |
## Example
### Request
```bash
curl https://mainnet.base.org \
-X POST -H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","method":"base_transactionStatus","params":["0xabc123..."],"id":1}'
```
### Response (Known)
```json
{"jsonrpc": "2.0", "id": 1, "result": {"status": "Known"}}
```
### Response (Unknown)
```json
{"jsonrpc": "2.0", "id": 1, "result": {"status": "Unknown"}}
```
---
# eth_simulateV1
Source: https://basehub.org/api-reference/flashblocks/eth_simulatev1/
Description: Simulates one or more transaction bundles against the current pre-confirmed Flashblock state, with state overrides and optional transfer tracing.
Simulates one or more transaction bundles against the current pre-confirmed Flashblock state. Supports state overrides, multi-block simulation, and optional transfer tracing.
A Base pre-confirmation method served on the standard public endpoints (`https://mainnet.base.org` / `https://sepolia.base.org`), which are all Flashblocks-enabled.
## Parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `simulationPayload` | object | Yes | The simulation configuration. |
| `blockParameter` | string | Yes | Use `"pending"` to simulate against the current Flashblock state. |
The `simulationPayload` object accepts:
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `blockStateCalls` | array | Yes | Array of block state call objects. Each object represents one simulated block. |
| `traceTransfers` | boolean | No | If `true`, ETH transfer events are included as logs in the result. Defaults to `false`. |
| `validation` | boolean | No | If `true`, transaction validation (nonce, balance) is enforced. Defaults to `false`. |
Each entry in `blockStateCalls` accepts:
| Field | Type | Description |
| --- | --- | --- |
| `calls` | array | Array of transaction call objects to simulate within this block. |
| `stateOverrides` | object | Per-address state overrides applied before simulation (for example, balance, nonce, code, storage). Optional. |
| `blockOverrides` | object | Block-level overrides (for example, `number`, `timestamp`). Optional. |
## Returns
`result` is an array of simulated block results, one per entry in `blockStateCalls`. Each result is a full block object that embeds a `calls` array alongside the standard block fields:
| Field | Type | Description |
| --- | --- | --- |
| `number` | string | Simulated block number (hex). |
| `hash` | string | Simulated block hash. |
| `parentHash` | string | Parent block hash. |
| `timestamp` | string | Block timestamp (hex). |
| `gasLimit` | string | Gas limit (hex). |
| `gasUsed` | string | Total gas used by the simulated calls (hex). |
| `baseFeePerGas` | string | Base fee per gas (hex). |
| `stateRoot` | string | Always `"0x000...000"`, because simulation never commits state to the trie. |
| `calls` | array | Array of individual call results. |
Each entry in `calls` has:
| Field | Type | Description |
| --- | --- | --- |
| `status` | string | `"0x1"` for success, `"0x0"` for failure. |
| `gasUsed` | string | Gas used as a hexadecimal integer. |
| `returnData` | string | Hex-encoded return data. |
| `logs` | array | Logs emitted (including ETH transfer logs if `traceTransfers` is `true`). |
| `error` | string | Revert reason if the call failed. Optional. |
## Example
### Request
```bash
curl https://sepolia.base.org \
-X POST \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"method": "eth_simulateV1",
"params": [
{
"blockStateCalls": [
{
"calls": [{"to": "0x...", "data": "0x..."}],
"stateOverrides": {}
}
],
"traceTransfers": true,
"validation": true
},
"pending"
],
"id": 1
}'
```
### Response
```json
{
"jsonrpc": "2.0",
"id": 1,
"result": [
{
"baseFeePerGas": "0x0",
"blobGasUsed": "0x39d0",
"calls": [
{
"gasUsed": "0x5208",
"logs": [],
"returnData": "0x",
"status": "0x1"
}
],
"difficulty": "0x0",
"excessBlobGas": "0x0",
"extraData": "0x01000000640000000500000000004c4b40",
"gasLimit": "0x17d78400",
"gasUsed": "0x5208",
"hash": "0x2f2f692821995e39653f63164b2d5d0e0bba66c86c2a199fd3009c0b9906c7b0",
"logsBloom": "0x000...000",
"miner": "0x4200000000000000000000000000000000000011",
"mixHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
"nonce": "0x0000000000000000",
"number": "0x2c31c49",
"parentBeaconBlockRoot": "0x64e625f8bc74f78539f962aa09d522c63576ff6ad57170c668882d99e669ef52",
"parentHash": "0x9653660afa4fca3976a21d42ebf849c337e9840993f050fee3affc673a573bf8",
"receiptsRoot": "0xf78dfb743fbd92ade140711c8bbc542b5e307f0ab7984eff35d751969fe57efa",
"requestsHash": "0xe3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
"sha3Uncles": "0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347",
"size": "0x2a6",
"stateRoot": "0x0000000000000000000000000000000000000000000000000000000000000000",
"timestamp": "0x6a10957f",
"transactions": [
"0xa401668a06b038c488c1abc013676dfe63fc645d182ece34d8b3f40f45689279"
],
"transactionsRoot": "0x0b1328c457d7a8108ea9f2559142890491b680fdb691720b3d0c857c3d11002c",
"uncles": [],
"withdrawals": [],
"withdrawalsRoot": "0x0000000000000000000000000000000000000000000000000000000000000000"
}
]
}
```
---
# newFlashblocks
Source: https://basehub.org/api-reference/flashblocks/newflashblocks/
Description: Subscribe to the full Flashblock payload stream and receive each pre-confirmed block delta as the sequencer builds it, every ~200ms.
Subscribe via `eth_subscribe` to receive full block state updates as each Flashblock is built. Each message contains the accumulated pre-confirmed state for the block in progress.
This subscription needs a WebSocket-enabled endpoint. The public Base endpoints (`mainnet.base.org`, `sepolia.base.org`) are HTTP only, so connect through a node provider such as Alchemy or QuickNode that offers WebSocket support for Base.
Requires [base/base](https://github.com/base/base) minimum client version v0.3.1.
Each subscription emits one Flashblock object per WebSocket message, with events arriving roughly every 200ms. If your handler does heavy work per event, throttle or debounce it to avoid blocking.
## Parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `subscriptionType` | string | Yes | Must be `"newFlashblocks"`. |
## Returns
| Field | Type | Description |
| --- | --- | --- |
| `result` | string | Hex-encoded subscription ID. Each event notification delivers a Flashblock object — not a standard block object. The payload contains `payload_id`, `index`, `diff`, and (on index 0) `base`. See the [infrastructure stream schema](/api-reference/flashblocks/overview/#flashblock-object) for the full structure. |
## Example
### Subscribe
```json
{"jsonrpc": "2.0", "id": 1, "method": "eth_subscribe", "params": ["newFlashblocks"]}
```
### Subscription ID response
```json
{"jsonrpc": "2.0", "id": 1, "result": "0x3b8cd9e5f4a7b2c1d0e3f4a5b6c7d8e9"}
```
### JavaScript
```javascript
import WebSocket from 'ws';
// Use a WebSocket-enabled node provider endpoint
const ws = new WebSocket('wss://your-provider-endpoint');
ws.on('open', () => {
ws.send(JSON.stringify({
jsonrpc: '2.0',
method: 'eth_subscribe',
params: ['newFlashblocks'],
id: 1
}));
});
ws.on('message', (data) => {
const msg = JSON.parse(data.toString());
if (msg.method === 'eth_subscription') {
// Fires every ~200ms with the latest Flashblock state
console.log('Flashblock update:', msg.params.result);
}
});
```
---
# newFlashblockTransactions
Source: https://basehub.org/api-reference/flashblocks/newflashblocktransactions/
Description: Subscribe to receive each transaction the sequencer pre-confirms into a Flashblock, optionally with full transaction and log data.
Subscribe via `eth_subscribe` to receive each transaction as it is pre-confirmed into a Flashblock. Pass `true` as the second parameter to receive full transaction and log data.
This subscription needs a WebSocket-enabled endpoint. The public Base endpoints (`mainnet.base.org`, `sepolia.base.org`) are HTTP only, so connect through a node provider such as Alchemy or QuickNode that offers WebSocket support for Base.
Requires [base/base](https://github.com/base/base) minimum client version v0.8.0. When `full` is `true`, each notification carries the transaction object with its receipt fields (including logs) embedded directly rather than in a nested receipt.
Each subscription emits one item per WebSocket message, with events arriving roughly every 200ms. If your handler does heavy work per event, throttle or debounce it to avoid blocking.
## Parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `subscriptionType` | string | Yes | Must be `"newFlashblockTransactions"`. |
| `full` | boolean | No | If `true`, each notification includes the full transaction object and associated logs. Defaults to `false` (minimal data only). |
## Returns
| Field | Type | Description |
| --- | --- | --- |
| `result` | string | Hex-encoded subscription ID. |
## Example
### Subscribe
```json
{"jsonrpc": "2.0", "id": 1, "method": "eth_subscribe", "params": ["newFlashblockTransactions"]}
```
### Subscribe (full data)
```json
{"jsonrpc": "2.0", "id": 1, "method": "eth_subscribe", "params": ["newFlashblockTransactions", true]}
```
### Subscription ID response
```json
{"jsonrpc": "2.0", "id": 1, "result": "0x1887ec8b9589ccad00000000000532da"}
```
## Notifications
Every update arrives as a standard `eth_subscription` message. What lands in `params.result` depends on the `full` flag.
With **`full: false`**, `result` is just the transaction hash:
```json
{
"jsonrpc": "2.0",
"method": "eth_subscription",
"params": {
"subscription": "0x1887ec8b9589ccad00000000000532da",
"result": "0xe26de91f9037e903eefe70b28f613019253da603e67e0dbfe2f656dce5444311"
}
}
```
With **`full: true`**, `result` is a transaction object that folds its receipt fields in directly (no nested receipt object). The schema below was verified live against `base/v0.9.0`:
| Field | Type | Description |
| --- | --- | --- |
| `type` | string | Transaction type: `0x0` Legacy, `0x2` EIP-1559, `0x7e` Deposit. |
| `chainId` | string | Chain ID (hex). |
| `nonce` | string | Sender nonce (hex). |
| `gas` | string | Gas limit (hex). |
| `maxFeePerGas` | string | EIP-1559 max fee per gas (hex). |
| `maxPriorityFeePerGas` | string | EIP-1559 max priority fee per gas (hex). |
| `to` | string | Recipient address. |
| `value` | string | ETH value transferred (hex). |
| `accessList` | array | EIP-2930 access list. |
| `input` | string | Transaction input data (hex). |
| `r` | string | Signature `r` component. |
| `s` | string | Signature `s` component. |
| `yParity` | string | Signature parity (hex). |
| `v` | string | Signature `v` value (hex). |
| `hash` | string | Transaction hash. |
| `blockHash` | null | Always `null` — the transaction is pre-confirmed, not yet in a finalized block. |
| `blockNumber` | string | Block number (hex) of the in-progress Flashblock. |
| `transactionIndex` | string | Index within the block (hex). |
| `from` | string | Sender address. |
| `gasPrice` | string | Effective gas price (hex). |
| `gasUsed` | string | Gas used by this transaction (hex). Changed from an integer to a hex string in v0.8.0. |
| `status` | string | `0x1` for success, `0x0` for failure. |
| `cumulativeGasUsed` | string | Total gas used in the block up to and including this transaction (hex). |
| `contractAddress` | string \| null | Address of the created contract, or `null`. |
| `logsBloom` | string | Bloom filter of logs (hex). |
| `logs` | array | Array of log objects emitted by this transaction. |
**Heads up:** `gasUsed` is delivered as a hex string (for example `"0x26132"`), not a number. This changed in v0.8.0, so update any parser that still expects an integer.
```json
{
"jsonrpc": "2.0",
"method": "eth_subscription",
"params": {
"subscription": "0x1887ec8b9589ccad00000000000532da",
"result": {
"type": "0x2",
"chainId": "0x2105",
"nonce": "0x34ed",
"gas": "0x7a1200",
"maxFeePerGas": "0x257ab3c",
"maxPriorityFeePerGas": "0x419c7c",
"to": "0x6211a3742cf9d3b6677ecc7fd9dd102ab101d8e2",
"value": "0x0",
"accessList": [],
"input": "0x...",
"r": "0xa7cd30d21c30d4d60d27073c8bbc3ef5778527cf98eae0433e9d1f18c929dd5d",
"s": "0x08c75921e6bb75e19112300f80998f88a2b0f1adc52df2c3597b171d8c8de68d",
"yParity": "0x1",
"v": "0x1",
"hash": "0x6a010a5ce041ff0ee5a926db65d1ef512836cae822d5f2d58b63981bfa40aa7f",
"blockHash": null,
"blockNumber": "0x2c679a1",
"transactionIndex": "0x83",
"from": "0x2ad149d3d3099532d7c25c47cce37db6c4677b3a",
"gasPrice": "0x8de7bc",
"gasUsed": "0x26132",
"status": "0x1",
"cumulativeGasUsed": "0x16cb406",
"contractAddress": null,
"logsBloom": "0x00...00",
"logs": []
}
}
}
```
---
# Flashblocks API overview
Source: https://basehub.org/api-reference/flashblocks/overview/
Description: Flashblocks-specific RPC methods, WebSocket subscriptions, and the infrastructure stream schema for Base pre-confirmations.
import { Aside } from '@astrojs/starlight/components';
Every public Base endpoint (`mainnet.base.org` / `sepolia.base.org`) is Flashblocks-enabled, serving the full set of standard Ethereum JSON-RPC methods plus a set of pre-confirmation-specific additions. Together they let you read state, simulate transactions, and stream events against sequencer-ordered data up to ~1.8 seconds before a block seals.
Every [standard Ethereum JSON-RPC method](/api-reference/rpc-overview/) accepts the `"pending"` block tag to resolve against pre-confirmed state instead of the transaction pool. See the [RPC overview](/api-reference/rpc-overview/) for endpoint URLs.
## HTTP methods
| Method | Description |
| --- | --- |
| [`eth_simulateV1`](/api-reference/flashblocks/eth_simulateV1/) | Simulate transaction bundles against pre-confirmed state. |
| [`base_transactionStatus`](/api-reference/flashblocks/base_transactionStatus/) | Check whether a transaction has been received by the node mempool. |
## WebSocket subscriptions
Over a WebSocket connection, `eth_subscribe` with `newHeads` emits a new event approximately every 200ms per Flashblock instead of every 2 seconds, and three additional subscription types become available. Note that the public Base endpoints are HTTP only — WebSocket subscriptions require a WebSocket-enabled node provider such as Alchemy or QuickNode.
| Subscription | Description |
| --- | --- |
| [`newFlashblockTransactions`](/api-reference/flashblocks/newFlashblockTransactions/) | Stream individual transactions as they are pre-confirmed (~200ms each). |
| [`pendingLogs`](/api-reference/flashblocks/pendingLogs/) | Stream filtered event logs from pre-confirmed transactions. |
| [`newFlashblocks`](/api-reference/flashblocks/newFlashblocks/) | Stream full Flashblock payload objects from the sequencer. |
## Infrastructure stream
The raw Flashblocks infrastructure stream is the upstream WebSocket feed consumed by Flashblocks-aware RPC nodes. It emits a new message approximately every 200ms as the sequencer pre-confirms transactions.
Applications should not connect directly to the infrastructure stream — these endpoints are reserved for node operators. App developers should use the [WebSocket subscription methods](#websocket-subscriptions) above through a Flashblocks-aware RPC provider.
| Network | Raw stream URL |
| --- | --- |
| Mainnet | `wss://mainnet.flashblocks.base.org/ws` |
| Sepolia | `wss://sepolia.flashblocks.base.org/ws` |
### Flashblock object
The root structure of each infrastructure stream message.
| Field | Type | Description |
| --- | --- | --- |
| `payload_id` | string | Unique identifier for the block being built. Remains consistent across all Flashblocks within a single full block. |
| `index` | number | Flashblock index within the current block. Starts at 0 (system transactions only). User transactions begin at index 1. Typically reaches 9–10 per block, but may exceed 10 during sequencer timing drift. |
| `base` | Base Object | Block header properties. **Only present when `index` is `0`.** See [Base object](#base-object). |
| `diff` | Diff Object | Incremental block state changes for this Flashblock. Present in every message. See [Diff object](#diff-object). |
| `metadata` | Metadata Object | Supplemental data. **Unstable — fields may change without notice.** See [Metadata object](#metadata-object). |
### Base object
Contains full block header properties. Only present in the `index: 0` message (the first Flashblock of each full block).
| Field | Type | Description |
| --- | --- | --- |
| `parent_hash` | string | Hash of the parent block. |
| `fee_recipient` | string | Address receiving transaction fees (coinbase). |
| `block_number` | string | Block number in hex. |
| `gas_limit` | string | Maximum gas allowed in this block (hex). |
| `timestamp` | string | Unix timestamp of block creation (hex). |
| `base_fee_per_gas` | string | EIP-1559 base fee per gas (hex). |
| `prev_randao` | string | Previous RANDAO value used for on-chain randomness. |
| `extra_data` | string | Arbitrary data field set by the sequencer. |
| `parent_beacon_block_root` | string | Root of the parent beacon block (EIP-4788). |
### Diff object
Contains the incremental block state changes for this specific Flashblock. Present in every message.
| Field | Type | Description |
| --- | --- | --- |
| `state_root` | string | Merkle root of the state trie after applying this Flashblock's transactions. |
| `block_hash` | string | Hash of the partial block at this Flashblock index. Changes with each Flashblock as more transactions are pre-confirmed. |
| `gas_used` | string | Cumulative gas used up to and including this Flashblock (hex). |
| `blob_gas_used` | string | Cumulative blob gas used (EIP-4844, hex). |
| `transactions` | string[] | Array of RLP-encoded transactions included in this Flashblock. |
| `withdrawals` | array | Validator withdrawals (always empty on Base L2). |
| `receipts_root` | string | Merkle root of transaction receipts. |
| `logs_bloom` | string | Bloom filter for logs in this Flashblock. |
| `withdrawals_root` | string | Merkle root of withdrawals. |
### Metadata object
The `metadata` object is not stable. Fields may be added, modified, or removed without prior notice. Do not build production dependencies on it — use the [`diff`](#diff-object) object or query finalized block data via standard RPC instead.
As of client version v0.8.0, `new_account_balances` and `receipts` are no longer carried in `metadata`; `block_number` is the only field that remains.
| Field | Type | Description |
| --- | --- | --- |
| `block_number` | number | Block number as a decimal integer. |
### Receipt object
`metadata.receipts` was dropped in v0.8.0; this schema is retained only as a reference for older node versions. On v0.8.0 and later, poll [`eth_getTransactionReceipt`](/api-reference/eth/eth_gettransactionreceipt/) for receipt data, or subscribe to [`newFlashblockTransactions`](/api-reference/flashblocks/newFlashblockTransactions/) with `full: true` for a live stream of pre-confirmed transaction data including logs. Check the `type` field to determine the transaction type.
| Field | Type | Description |
| --- | --- | --- |
| `type` | string | Transaction type: `0x0` Legacy, `0x1` Access List, `0x2` EIP-1559, `0x7e` Deposit (L1→L2). |
| `status` | string | Transaction status: `0x1` for success, `0x0` for failure. |
| `cumulativeGasUsed` | string | Total gas used in the block up to and including this transaction (hex). |
| `logs` | Log[] | Array of event logs emitted by the transaction. See [Log object](#log-object). |
| `logsBloom` | string | Bloom filter for the logs in this receipt. |
| `transactionIndex` | string | Index of the transaction within the block (hex). |
### Log object
| Field | Type | Description |
| --- | --- | --- |
| `address` | string | Contract address that emitted the event. |
| `topics` | string[] | Array of indexed event parameters. Topic 0 is typically the event signature hash. |
| `data` | string | ABI-encoded non-indexed event parameters. |
| `blockHash` | string | Hash of the block containing this log. |
| `blockNumber` | string | Block number in hex. |
| `blockTimestamp` | string | Unix timestamp of the block as a hex string. OP Stack extension to the standard Ethereum log schema. |
| `transactionHash` | string | Hash of the transaction that emitted this log. |
| `transactionIndex` | string | Index of the transaction in the block (hex). |
| `logIndex` | string | Log's index position within the block (hex). |
| `removed` | boolean | `true` if the log was removed due to a chain reorg. |
### Complete examples
Index 0 — includes the `base` object (block header):
```json
{
"payload_id": "0x03997352d799c31a",
"index": 0,
"base": {
"parent_hash": "0x9edc29b8b0a1e31d28616e40c16132ad0d58faa8bb952595b557526bdb9a960a",
"fee_recipient": "0x4200000000000000000000000000000000000011",
"block_number": "0x158a0e9",
"gas_limit": "0x3938700",
"timestamp": "0x67bf8332",
"base_fee_per_gas": "0xfa",
"parent_beacon_block_root": "0x15b9e7c8ac4cbe92dafc849ed30a23e91624bbe5cbe199c0ccea3f7de7fc6d49"
},
"diff": {
"state_root": "0x208fd63edc0681161105f27d03daf9f8c726d8c94e584a3c0696c98291c24333",
"block_hash": "0x5c330e55a190f82ea486b61e5b12e27dfb4fb3cecfc5746886ef38ca1281bce8",
"gas_used": "0xab3f",
"transactions": ["0x7ef8f8a0b4afc0b7ce10e150801bbaf08ac33fecb0f38311793abccb022120d321c6d276..."],
"withdrawals": []
},
"metadata": {
"block_number": 22585577
}
}
```
Index 1–N (diff only) — no `base` object:
```json
{
"payload_id": "0x03997352d799c31a",
"index": 4,
"diff": {
"state_root": "0x7a8f45038665072f382730e689f4a1561835c9987fca8942fa95872fb9367eaa",
"block_hash": "0x9b32f7a14cbd1efc8c2c5cad5eb718ec9e0c5da92c3ba7080f8d4c49d660c332",
"gas_used": "0x1234f",
"transactions": ["0x02f90133...", "0x02f90196..."],
"withdrawals": []
},
"metadata": {
"block_number": 22585577
}
}
```
---
# pendingLogs
Source: https://basehub.org/api-reference/flashblocks/pendinglogs/
Description: Subscribe to logs from pre-confirmed transactions matching an optional address and topics filter, with sub-block latency over a WebSocket connection.
Subscribe via `eth_subscribe` to receive logs from pre-confirmed transactions matching an optional filter. Useful for monitoring contract events with sub-block latency.
This subscription needs a WebSocket-enabled endpoint. The public Base endpoints (`mainnet.base.org`, `sepolia.base.org`) are HTTP only, so connect through a node provider such as Alchemy or QuickNode that offers WebSocket support for Base.
Requires [base/base](https://github.com/base/base) minimum client version v0.3.1.
Each subscription emits one item per WebSocket message, with events arriving roughly every 200ms. If your handler does heavy work per event, throttle or debounce it to avoid blocking.
## Parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `subscriptionType` | string | Yes | Must be `"pendingLogs"`. |
| `filterOptions` | object | No | Optional log filter. |
The `filterOptions` object accepts:
| Field | Type | Description |
| --- | --- | --- |
| `address` | string \| array | A single contract address or array of addresses to filter by. |
| `topics` | array | Array of topic filters in the same format as `eth_getLogs`. |
## Returns
| Field | Type | Description |
| --- | --- | --- |
| `result` | string | Hex-encoded subscription ID. |
## Example
### Subscribe (with filter)
```json
{
"jsonrpc": "2.0",
"id": 1,
"method": "eth_subscribe",
"params": [
"pendingLogs",
{
"address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
"topics": ["0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"]
}
]
}
```
### Subscription ID response
```json
{"jsonrpc": "2.0", "id": 1, "result": "0x2a7bc8d4e3f5a6b1c2d3e4f5a6b7c8d9"}
```
---
# Rollup node RPC
Source: https://basehub.org/api-reference/rollup-node-rpc/
Description: Reference for the Base rollup node's optimism_outputAtBlock method, which returns the L2 output root and sync metadata for a given block, along with the supporting BlockID, L1BlockRef, L2BlockRef, and SyncStatus structures.
Beyond the execution-layer JSON-RPC namespaces, the Base rollup node exposes its own RPC surface. The method documented here, `optimism_outputAtBlock`, is the one most integrators reach for: it hands back the 32-byte [L2 output root](/specifications/proofs-overview/) for a chosen block, which is the value bridges and proof systems anchor against.
## `optimism_outputAtBlock`
Given an L2 block number, this method returns that block's output root together with the metadata needed to reason about it.
### Parameters
| Name | Type | Description |
| :--- | :--- | :--- |
| `blockNumber` | `QUANTITY`, 64 bits | L2 integer block number |
### Returns
| Name | Type | Description |
| :--- | :--- | :--- |
| `version` | `DATA`, 32 Bytes | Output root version number, beginning with `0` |
| `outputRoot` | `DATA`, 32 Bytes | The output root |
| `blockRef` | `Object` | Instance of [`L2BlockRef`](#l2blockref) |
| `withdrawalStorageRoot` | `DATA`, 32 Bytes | Storage root of the `L2ToL1MessagePasser` contract |
| `stateRoot` | `DATA`, 32 Bytes | The state root |
| `syncStatus` | `Object` | Instance of [`SyncStatus`](#syncstatus) |
The input and output types follow the [engine API specification][engine-structures].
## Structures
The object types referenced by the rollup node API are listed below. They extend the structures defined in the [engine API specs][engine-structures].
### BlockID
- `hash`: `DATA`, 32 Bytes
- `number`: `QUANTITY`, 64 Bits
### L1BlockRef
- `hash`: `DATA`, 32 Bytes
- `number`: `QUANTITY`, 64 Bits
- `parentHash`: `DATA`, 32 Bytes
- `timestamp`: `QUANTITY`, 64 Bits
### L2BlockRef
- `hash`: `DATA`, 32 Bytes
- `number`: `QUANTITY`, 64 Bits
- `parentHash`: `DATA`, 32 Bytes
- `timestamp`: `QUANTITY`, 64 Bits
- `l1origin`: `BlockID`
- `sequenceNumber`: `QUANTITY`, 64 Bits - distance to first block of epoch
### SyncStatus
A point-in-time snapshot of the rollup driver's view of both chains.
- `current_l1`: `Object` - instance of [`L1BlockRef`](#l1blockref).
- `current_l1_finalized`: `Object` - instance of [`L1BlockRef`](#l1blockref).
- `head_l1`: `Object` - instance of [`L1BlockRef`](#l1blockref).
- `safe_l1`: `Object` - instance of [`L1BlockRef`](#l1blockref).
- `finalized_l1`: `Object` - instance of [`L1BlockRef`](#l1blockref).
- `unsafe_l2`: `Object` - instance of [`L2BlockRef`](#l2blockref).
- `safe_l2`: `Object` - instance of [`L2BlockRef`](#l2blockref).
- `finalized_l2`: `Object` - instance of [`L2BlockRef`](#l2blockref).
- `pending_safe_l2`: `Object` - instance of [`L2BlockRef`](#l2blockref).
- `queued_unsafe_l2`: `Object` - instance of [`L2BlockRef`](#l2blockref).
[engine-structures]: https://github.com/ethereum/execution-apis/blob/main/src/engine/paris.md#structures
---
# RPC overview
Source: https://basehub.org/api-reference/rpc-overview/
Description: Full reference for the JSON-RPC and Flashblocks methods exposed by Base nodes across the eth, net, web3, debug, txpool, and base namespaces.
import { Tabs, TabItem, Aside } from '@astrojs/starlight/components';
Base exposes a single, fully EVM-compatible JSON-RPC API. There is now one public endpoint per network rather than separate standard and pre-confirmation URLs — every endpoint is Flashblocks-enabled, so the `pending` block tag resolves against pre-confirmed state with no change of host.
## Networks
| Network | Chain ID | Type | Archive |
| :--- | :--- | :--- | :--- |
| Mainnet | `8453` | Production | Yes |
| Sepolia | `84532` | Testnet | Yes |
## Endpoints
| | HTTP |
| :--- | :--- |
| RPC | `https://mainnet.base.org` |
| | HTTP |
| :--- | :--- |
| RPC | `https://sepolia.base.org` |
## Flashblocks
Every public Base endpoint is Flashblocks-enabled, so all standard `eth_` methods behave identically and the `pending` block tag resolves against the **pre-confirmed block currently being built**, refreshed every ~200ms with new batches of sequencer-ordered transactions.
Methods such as `eth_getBalance`, `eth_getStorageAt`, and `eth_call` execute against real sequencer state up to 1.8 seconds before a block seals, with sub-second latency.
## Namespaces
Base nodes implement the standard Ethereum namespaces plus a small set of Base-specific methods.
- **`eth`** — core Ethereum protocol methods for accounts, blocks, transactions, gas, and logs. The `pending` tag resolves against pre-confirmed state.
- **`net`** — network identification (`net_version`).
- **`web3`** — client identification (`web3_clientVersion`).
- **`debug`** — replay and tracing utilities for deep transaction inspection. Computationally expensive; availability depends on the node provider.
- **`txpool`** — inspection of the local mempool.
- **`base`** — Base-specific helpers, including pre-confirmation status checks (`base_transactionStatus`).
- **Flashblocks** — pre-confirmation methods (`eth_simulateV1`) and WebSocket streams (`newFlashblockTransactions`, `pendingLogs`, `newFlashblocks`). The streaming subscriptions need a WebSocket-enabled node provider.
- **`optimism`** — rollup-node methods served by the consensus client rather than the execution layer, including `optimism_outputAtBlock` for retrieving an L2 output root.
## Method index
### Ethereum JSON-RPC API
Methods marked with a check mark support the `"pending"` block tag, which resolves against the pre-confirmed Flashblock in progress.
| Method | Description | Flashblocks `pending` |
| :--- | :--- | :--- |
| [eth_blockNumber](/api-reference/eth/eth_blocknumber/) | Current block number | — |
| [eth_getBalance](/api-reference/eth/eth_getbalance/) | Account ETH balance | yes |
| [eth_getTransactionCount](/api-reference/eth/eth_gettransactioncount/) | Account nonce / tx count | yes |
| [eth_getCode](/api-reference/eth/eth_getcode/) | Deployed contract bytecode | yes |
| [eth_getStorageAt](/api-reference/eth/eth_getstorageat/) | Contract storage slot value | yes |
| [eth_call](/api-reference/eth/eth_call/) | Execute read-only call | yes |
| [eth_getBlockByNumber](/api-reference/eth/eth_getblockbynumber/) | Block data by number | yes |
| [eth_getBlockByHash](/api-reference/eth/eth_getblockbyhash/) | Block data by hash | — |
| [eth_getBlockReceipts](/api-reference/eth/eth_getblockreceipts/) | All receipts for a block | yes |
| [eth_getBlockTransactionCountByNumber](/api-reference/eth/eth_getblocktransactioncountbynumber/) | Tx count by block number | yes |
| [eth_getBlockTransactionCountByHash](/api-reference/eth/eth_getblocktransactioncountbyhash/) | Tx count by block hash | — |
| [eth_getTransactionByHash](/api-reference/eth/eth_gettransactionbyhash/) | Transaction data by hash | — |
| [eth_getTransactionByBlockHashAndIndex](/api-reference/eth/eth_gettransactionbyblockhashandindex/) | Tx by block hash and index | — |
| [eth_getTransactionByBlockNumberAndIndex](/api-reference/eth/eth_gettransactionbyblocknumberandindex/) | Tx by block number and index | — |
| [eth_getTransactionReceipt](/api-reference/eth/eth_gettransactionreceipt/) | Receipt for a mined tx | — |
| [eth_sendRawTransaction](/api-reference/eth/eth_sendrawtransaction/) | Submit signed transaction | — |
| [eth_gasPrice](/api-reference/eth/eth_gasprice/) | Current gas price | — |
| [eth_maxPriorityFeePerGas](/api-reference/eth/eth_maxpriorityfeepergas/) | Max priority fee estimate | — |
| [eth_feeHistory](/api-reference/eth/eth_feehistory/) | Historical base fee and rewards | — |
| [eth_estimateGas](/api-reference/eth/eth_estimategas/) | Estimate gas for a tx | yes |
| [eth_getLogs](/api-reference/eth/eth_getlogs/) | Query event logs by filter | yes |
| [eth_chainId](/api-reference/eth/eth_chainid/) | Network chain ID | — |
| [eth_syncing](/api-reference/eth/eth_syncing/) | Node sync status | — |
| [net_version](/api-reference/eth/net_version/) | Network version ID | — |
| [web3_clientVersion](/api-reference/eth/web3_clientversion/) | Client version string | — |
| [eth_subscribe](/api-reference/eth/eth_subscribe/) | Subscribe to events (WSS) | yes |
| [eth_unsubscribe](/api-reference/eth/eth_unsubscribe/) | Cancel a subscription (WSS) | — |
### Flashblocks API
Pre-confirmation methods that deliver sub-second transaction signals on Base. They let you read state, simulate bundles, and stream events up to ~1.8 seconds ahead of block sealing. The streaming methods require a WebSocket-enabled node provider.
| Method | Description |
| --- | --- |
| [eth_simulateV1](/api-reference/flashblocks/eth_simulatev1/) | Simulate transaction bundles against pre-confirmed state |
| [base_transactionStatus](/api-reference/flashblocks/base_transactionstatus/) | Check whether a transaction has been received by the mempool |
| [newFlashblockTransactions](/api-reference/flashblocks/newflashblocktransactions/) | Subscribe to individual pre-confirmed transactions |
| [pendingLogs](/api-reference/flashblocks/pendinglogs/) | Subscribe to filtered logs from pre-confirmed transactions |
| [newFlashblocks](/api-reference/flashblocks/newflashblocks/) | Subscribe to the full Flashblock payload stream |
### Debug API
Development and debugging utilities for transaction replay and block inspection. Debug methods replay execution and are computationally expensive — availability and rate limits vary by node provider.
| Method | Description |
| --- | --- |
| [debug_traceTransaction](/api-reference/debug/debug_tracetransaction/) | Full EVM execution trace for a transaction |
| [debug_traceBlockByHash](/api-reference/debug/debug_traceblockbyhash/) | EVM traces for every transaction in a block by hash |
| [debug_traceBlockByNumber](/api-reference/debug/debug_traceblockbynumber/) | EVM traces for every transaction in a block by number |
### Rollup node RPC
Methods exposed by the rollup (consensus) node rather than the execution client.
| Method | Description |
| --- | --- |
| [optimism_outputAtBlock](/api-reference/rollup-node-rpc/) | Output root and sync metadata for an L2 block |
## Request and response format
All requests are HTTP `POST` with `Content-Type: application/json`.
| Field | Type | Description |
| :--- | :--- | :--- |
| `jsonrpc` | string | Always `"2.0"` |
| `method` | string | The RPC method name |
| `params` | array | Method parameters in order |
| `id` | number \| string | Identifier echoed back in the response |
**Request:**
```json
{
"jsonrpc": "2.0",
"method": "eth_getBalance",
"params": ["0x742d35Cc6634C0532925a3b8D4C9dD0b4f3BaEa", "pending"],
"id": 1
}
```
**Success response:**
```json
{
"jsonrpc": "2.0",
"id": 1,
"result": "0x1a055690d9db80000"
}
```
**Error response:**
```json
{
"jsonrpc": "2.0",
"id": 1,
"error": {
"code": -32602,
"message": "Invalid params"
}
}
```
## Error codes
| Code | Name | Description |
| --- | --- | --- |
| `-32700` | Parse error | Invalid JSON |
| `-32600` | Invalid request | Not a valid JSON-RPC 2.0 object |
| `-32601` | Method not found | Method does not exist or is unavailable |
| `-32602` | Invalid params | Invalid method parameters |
| `-32603` | Internal error | Internal JSON-RPC error |
| `-32000` | Server error | Node-specific error (see message) |
## Block parameters
| Value | Resolves to |
| --- | --- |
| `"latest"` | Most recently sealed block |
| `"pending"` | **Current Flashblock in progress (~200ms resolution)** |
| `"safe"` | Latest safe block |
| `"finalized"` | Latest finalized block |
| `"earliest"` | Genesis block |
| `"0x"` | Specific block by number |
---
# Tokenized Stocks API
Source: https://basehub.org/api-reference/tokenized-stocks-api/
Description: Reference for the public, read-only Coinbase Tokenized Stocks API — token records, protocol contract addresses, normalized supplies, metadata, icons, prospectuses, corporate actions, and Chainlink NAV values on Base.
import { Aside } from '@astrojs/starlight/components';
Coinbase runs a small HTTP API that hands back reference data for its [tokenized stocks on Base](/integration-guides/tokenized-stocks/). It is public and read-only, and it needs no API key. One request gets you what would otherwise take several onchain reads per token: the contract address, supply, current multiplier, pause state, and the latest Chainlink reference value.
```text
https://api.coinbase.com/v1/tokenized-stocks
```
## Endpoints
| Method | Path | Returns |
|--------|------|---------|
| `GET` | `/` | Every tokenized-stock record the API currently exposes. |
| `GET` | `/chains` | The tokenized-stocks protocol contracts, per supported chain. |
| `GET` | `/total-supply/{contract_address}` | One token's total supply, normalized by its decimals. |
| `GET` | `/metadata/{ticker}` | A `contractURI`-style metadata document for one token. |
| `GET` | `/images/{symbol}` | A `302` redirect to the token's icon. |
| `GET` | `/prospectus/{ticker}` | A `302` redirect to the token's approved prospectus PDF. |
| `GET` | `/prospectuses` | Tickers that currently have a cached prospectus, with ISINs where known. |
| `GET` | `/corporate-actions/{id}` | One announced or applied corporate action. |
The full schema lives upstream in `openapi/tokenized-equities.json`.
## List tokenized stocks
```bash
curl https://api.coinbase.com/v1/tokenized-stocks
```
The response is a `tokens` array and, when more records exist, a `next_page_token`. Each entry is a `v1TokenizedEquityToken`:
| Field | Type | Meaning |
|-------|------|---------|
| `contract_address` | string | The ERC-20 (B20) token contract on Base. |
| `symbol` | string | Ticker symbol of the token. |
| `name` | string | Name of the underlying equity. |
| `decimals` | integer | Token decimals. |
| `icon_url` | string | Icon for the underlying equity. |
| `total_supply` | double | Supply in token units, already divided by `decimals`. |
| `isin` | string | ISIN of the underlying equity. |
| `multiplier` | double | Current token-to-share scaling factor. `1.0` means no adjustment. |
| `paused_features` | integer[] | Feature flags currently paused on the token contract. |
| `nav_price` | double | Latest Chainlink NAV/reference value, adjusted for the feed's decimals. |
| `nav_price_updated_at` | date-time | When `nav_price` last changed onchain (the feed's `updatedAt`). |
| `description` | string | Long-form description of the tokenized stock. |
| `first_mint_date` | date-time | UTC block time of the token's first positive mint. This is not the deploy time, and later mints or burns never move it. |
Not every field appears on every record. The API drops scalar fields that hold their default value, empty arrays, and timestamps that were never set. `first_mint_date` is also missing when a token has never been minted or when its first mint has not been resolved yet. On 2026-10-17 the full list had 174 records. 116 of them had no `total_supply` key (zero supply), and only 58 carried `first_mint_date`. Write your parser so a missing key means "default or unknown", and never read a missing `nav_price` as a usable price.
### Paging through the list
The list is paged, so one call can miss records. If a response has `next_page_token`, send it back as the `page_token` query parameter to get the next page. Stop when a response has no `next_page_token`. Leave every other query parameter the same from one page to the next. Records come back sorted by contract address.
`page_size` sets the page length. Omitting it, or sending `0`, gives `100`. Anything above `500` is quietly cut to `500`. A negative or malformed `page_size`, or a malformed `page_token`, fails with HTTP `400`.
```bash
curl "https://api.coinbase.com/v1/tokenized-stocks?page_token="
```
This is not a corner case. On 2026-10-14 a call with no parameters returned 100 records and a `next_page_token`. Walking every page returned 145 records (174 by 2026-10-17). Code that reads only the first response misses about a third of the tokens and gets no error. Upstream added pagination to its docs on 2026-10-13.
## List protocol contract addresses
```bash
curl https://api.coinbase.com/v1/tokenized-stocks/chains
```
Returns a `chains` array of `v1ChainContractAddresses` entries, each with `chain_id`, `chain`, `policy_registry_address`, `token_supply_manager_address`, and `token_factory_address`. On 2026-09-25 it listed one chain, Base (`8453`):
| Field | Value |
|-------|-------|
| `policy_registry_address` | `0x8453000000000000000000000000000000000002` |
| `token_supply_manager_address` | `0xD1Ca4dAcdf3231011D175351f1f02D15C7c5664C` |
| `token_factory_address` | `0x4bA3E29E254F25E94E61C4c9d67b37027331534D` |
The policy registry is the B20 [PolicyRegistry precompile](/api-reference/b20-precompiles/), not a separate deployment. Treat the live response as authoritative over this table.
## Get token total supply
The example below uses the AAPLc contract. For any other token, take its address from the list endpoint above.
```bash
curl https://api.coinbase.com/v1/tokenized-stocks/total-supply/0xb200000000000000000000C2e324d24d7eEcd1fb
```
The body is a bare JSON number, such as `7459.11648989` for AAPLc on 2026-10-17. There is no wrapping object and no `total_supply` key, so a parser that looks for one gets nothing. The value is already divided by the token's decimals; do not divide it again.
A badly formed address gets HTTP `400` with service code `3`. A well-formed address that is not a supported tokenized stock gets HTTP `404` with service code `5`.
## Get token metadata
Pass the token symbol with its suffix, for example `TSLAc`. Case does not matter.
```bash
curl https://api.coinbase.com/v1/tokenized-stocks/metadata/TSLAc
```
The document has `contract_address`, `name`, `symbol`, `description`, `image`, and `prospectus_url`. Both URLs point back at this API and redirect to whatever asset is current, so they stay stable. A `prospectus_url` is always present, but that does not mean a PDF is cached right now. Check the cached prospectus list below before you rely on it.
## Get token icon
Pass the symbol with its suffix. Case does not matter, and the `.png` ending is optional.
```bash
curl -L https://api.coinbase.com/v1/tokenized-stocks/images/TSLAc.png --output TSLAc.png
```
A hit returns HTTP `302` with the real image location in the `Location` header; `-L` tells curl to follow it. There is no JSON body. An unknown symbol gets `404`, and missing token data gets `503`, both as plain text.
## Get token prospectus
Pass the ticker with its suffix. Case does not matter, the `.pdf` ending is optional, and dotted share classes such as `BRK.Bc` work.
```bash
curl -L https://api.coinbase.com/v1/tokenized-stocks/prospectus/TSLAc.pdf --output TSLAc.pdf
```
A hit returns HTTP `302` to the approved prospectus PDF; on 2026-10-17 the TSLAc redirect pointed at a file on `adgm.com`. A malformed ticker gets `400`, and a ticker with no prospectus available gets `404`. Both errors are plain text, not JSON.
## List cached prospectuses
```bash
curl https://api.coinbase.com/v1/tokenized-stocks/prospectuses
```
The body holds a `prospectuses` array in alphabetical order of the upper-cased ticker. Each item has a `ticker` and, if known, the underlying equity's `isin`. The tickers come back fully upper-cased (`AAPLC`, not `AAPLc`), which is fine because the prospectus endpoint ignores case. No PDF links are included; feed the ticker to the prospectus endpoint instead.
The cache fills in the background. Until its first good refresh it can be empty, and then the `prospectuses` key can be absent altogether. This list tells you which prospectuses are on hand. It is not a list of tradable tokens. On 2026-10-17 it held 177 entries.
## Get a corporate action
```bash
curl https://api.coinbase.com/v1/tokenized-stocks/corporate-actions/e82812a6-0b24-41c4-8ed1-322d1b466d33
```
That ID is a GOOGLc cash dividend. Get the ID from the UUID at the end of the `uri` in the token's onchain `Announcement` event. Do not use the event's `id` argument; it can be a plain number or carry a suffix like `:pre` or `-1`. The GOOGLc example shows why: its announcement history has one entry with ID `2097` and a second whose ID is the UUID. Announcements that have no addressable URI cannot be fetched here.
The body is the action itself, not wrapped in a `corporate_action` key. It carries the token, a description, the status, the first announcement time, and the onchain announcements in time order. Announcement `block_number` values are decimal strings.
- `CORPORATE_ACTION_STATUS_ANNOUNCED`: published, but the token's multiplier has not changed yet.
- `CORPORATE_ACTION_STATUS_APPLIED`: the multiplier change is in effect. Only in this state are `applied_at`, `multiplier_before`, and `multiplier_after` filled in.
The multiplier values are already converted out of their 18-decimal fixed-point form. A malformed UUID gets `400`. An unknown action, or one on a test or non-live token, gets `404`. Stale or unavailable action data gets `503`.
## Errors
The JSON endpoints report failures as an object with `code` and `message`. `code` is a service error code, not the HTTP status:
```json
{"code": 3, "message": "page_token is invalid"}
```
| HTTP status | `code` | When |
|-------------|--------|------|
| `400` | `3` | Bad input: malformed page token, negative page size, invalid contract address, or malformed corporate action UUID. |
| `404` | `5` | The token, ticker, or corporate action is unsupported or does not exist. |
| `503` | `14` | Data the request needs is temporarily unavailable. |
The icon and prospectus endpoints are the exception. They answer success with a `302` and send their errors as plain text.
## Reading the numbers correctly
The field names look familiar from the onchain interface, but several of them carry different units here. Most integration mistakes with this API come from mixing the two.
- **`total_supply` counts tokens, not shares.** To get the share count, multiply it by `multiplier`.
- **`multiplier` is already scaled down.** Onchain the multiplier is WAD-scaled (18 decimals). The API divides that out, so a token with no adjustment reports `1`, not `1e18`. Do not apply the WAD division a second time.
- **`multiplier` moves.** Dividends and splits change it, so read the current value each time you convert units to shares. Never cache it as a constant.
- **`nav_price` is a reference value, not a quote.** It is the total-return figure from the token's Chainlink feed. It is not a bid, an ask, or a fill price.
- **`nav_price` goes stale without warning.** Chainlink publishes a new round only on a price deviation or a heartbeat, and the feeds stop outside market hours. So `nav_price_updated_at` can trail the clock by minutes or by many hours. Apply the same staleness bound you would apply to `updatedAt` from `latestRoundData()`.
Two response details surfaced when this page was checked against the live API on 2026-09-25:
- `paused_features` is left out entirely when nothing is paused, rather than sent as an empty array. Treat a missing key as "no pauses". Upstream now documents this as the general rule for all default-valued fields.
- The list held exactly the ten launched tokens (AAPLc through TSLAc). COINc, CRCLc, and INTCc, which are registered onchain but have zero supply, were not in it. That is no longer true: by 2026-10-17 the list included zero-supply tokens such as RKTc, with `total_supply` simply omitted.
## Related pages
- [Tokenized Stocks](/integration-guides/tokenized-stocks/) — multipliers, policies, price feeds, and deployed addresses
- [B20 Precompile Reference](/api-reference/b20-precompiles/) — the onchain interface these records describe
- [B20 Native Token Standard](/specifications/b20/)
---
# Validity Transactions
Source: https://basehub.org/api-reference/validity-transactions/
Description: Reference for base_sendRawTransactionValidity — submitting a signed transaction with predicates over chain state, so Base holds it back until every condition matches.
import { Aside } from '@astrojs/starlight/components';
A validity transaction is an ordinary signed transaction handed to Base together with a list of conditions on chain state. Base keeps it out of a block until every condition matches, then lets it compete for inclusion on the usual fee rules. The pattern suits conditional swaps, conditional withdrawals, and anything else that should only fire once the chain reaches a particular state.
The method accepts legacy, EIP-2930, and EIP-1559 transactions. EIP-1559 is the recommended type.
## How it works
Submit two things: a signed raw transaction, and an object carrying a non-empty `validity` array. Base checks the predicates against the state as it stands just before the transaction would run, not against the state at submission time. A transaction whose predicates do not all match stays pending rather than failing.
That waiting behaviour is the useful part. An earlier transaction can move the storage value a pending transaction is watching, and the pending transaction then becomes eligible — possibly within the same Flashblock. No keeper has to watch the chain and race to submit.
Eligibility is not a reservation. A matching predicate set earns a place in the ordinary competition for block space, nothing more.
## `base_sendRawTransactionValidity`
### Parameters
| Position | Value |
| --- | --- |
| 1 | A signed, serialized transaction (legacy, EIP-2930, or EIP-1559) |
| 2 | An object containing a non-empty `validity` array |
The second parameter takes `validity` and nothing else. An unrecognised key fails the whole request, so a misspelled field name surfaces as a rejection rather than as a silently ignored setting. From `v1.5.0-rc.7` the object also accepts an optional `validity_signature`, covered under [Signed predicates](#signed-predicates).
Every submission also needs a `block_number` upper bound. The example below pairs the condition it actually cares about with that mandatory bound:
```json
{
"jsonrpc": "2.0",
"id": 1,
"method": "base_sendRawTransactionValidity",
"params": [
"0x",
{
"validity": [
{
"type": "storage",
"params": {
"address": "0x8ba1f109551bD432803012645Ac136ddd64DBA72",
"slot": "0x8",
"mask": "0xff",
"op": "=",
"value": "0x2a"
}
},
{
"type": "block_number",
"params": {
"op": "<=",
"value": "0x1e8493"
}
}
]
}
]
}
```
The `block_number` value here is only a placeholder. Right before you sign, call `eth_blockNumber`, add `10` to the result, and send that as a `0x`-prefixed hex string. A bound that close stays inside the 60-second expiry window described under [Fees, ordering, and lifecycle](#fees-ordering-and-lifecycle). An old value copied from an example fails the check that rejects a bound behind the block being built.
### Limits
| Limit | Value |
| --- | --- |
| Predicates per submission | 1 to 64 |
| Lifetime window | 60 seconds by default |
| Unknown top-level fields | Rejected |
The predicate ceiling is a wire limit rather than a policy an operator can raise. Decoding stops at the 65th entry, so an oversized batch is refused before the node allocates room for it. An operator can lower the ceiling with `--validity-max-predicates` (builders use `--builder.validity-max-predicates`), but a value above 64 is refused at startup instead of being quietly clamped.
An empty `validity` array is also rejected. A submission with no conditions carries nothing to enforce, so it is not accepted as a plain private transaction.
### Returns
A 32-byte transaction hash, as a `0x`-prefixed string.
### Errors
Failures come back as JSON-RPC errors. Handle at least three cases: the method being unavailable on the endpoint, invalid parameters, and a missing transaction hash in the response. Do not pattern-match on codes or message text yet, because neither is stable.
## Predicate types
| Type | Parameters |
| --- | --- |
| `balance` | `address`, `op`, `value` |
| `nonce` | `address`, `op`, `value` |
| `storage` | `address`, `slot`, `op`, `value`, optional `mask` |
| `block_number` | `op`, `value` |
| `flashblock_index` | `op`, `value` |
Operators are `<`, `<=`, `=`, `!=`, `>`, and `>=`. Every value is a `0x`-prefixed hexadecimal string.
For a storage predicate Base compares `(storage[address][slot] & mask)` against `value`. Leave `mask` out to compare the whole storage word; it defaults to all ones.
A balance predicate reads the native ETH balance of `address`, in wei, and compares it with `value`. An address with no account reads as zero. It takes no `slot` and no `mask`.
A nonce predicate works the same way, but on the account's protocol nonce (#5637). That is the ordinary transaction count of `address`, not an EIP-8130 channel nonce. An address with no account reads as zero, and an account deleted during the block also reads as zero. Like `balance`, it takes no `slot` and no `mask`. Use it to make one transaction wait until another account has sent a given number of transactions, or to stop waiting once it has sent too many.
A nonce condition that has been passed does not evict the transaction. Suppose you write `=`, `<`, or `<=` and the nonce then moves above your value. Nonces only go up, so the condition can never match again, but the node still parks the transaction and does not drop it. Only your mandatory `block_number` bound ends its life. Keep that bound tight when you rely on a nonce ceiling.
Use `block_number` to pin a target block and `flashblock_index` to pin a position inside it. Both conditions need their own predicate — one entry cannot express both. The request sample in the Cobalt launch post folds both into a single object with repeated `type` and `params` keys, and it is not valid JSON as printed. Give each predicate its own entry in the `validity` array, as the examples on this page do.
A usable `flashblock_index` runs from `1` to `10` inclusive, which is `0x1` to `0xa` in hex. Index `0` is the fallback block. It holds only the sequencer's own transactions, so no pooled transaction can ever match there. The node refuses at ingress any `flashblock_index` predicate whose largest reachable value is below `1`, for example `<= 0x0` or `< 0x1`, because such a transaction would wait forever.
## Signed predicates
The relayer problem above now has an opt-in fix (#5645). A sender can sign the predicate list itself, so nobody else can bolt different conditions onto the transaction. The motivating attack is a sandwich: someone holding your raw transaction adds a storage check that keeps it waiting until their own trade has moved a pool's reserves. Your calldata is untouched, and the damage stays inside your onchain slippage limit, which is why it is easy to miss.
To sign, pass `validity_signature` next to `validity` in the second parameter. It is an Alloy signature object with `r`, `s`, and `yParity` as hex quantities. Produce it with `eth_signTypedData_v4`, not `personal_sign`, over this EIP-712 data:
- **Domain:** `{ name: "Base Transaction Validity", version: "1", chainId }`, with the transaction's own chain ID and no verifying contract.
- **Types:**
```text
ValidityPredicate(uint8 kind,uint8 operator,address account,uint256 slot,uint256 mask,uint256 value)
ValidityAuthorization(bytes32 transactionHash,ValidityPredicate[] validity)
```
`transactionHash` is the hash of the full signed EIP-2718 envelope. `kind` is balance = 0, storage = 1, block number = 2, flashblock index = 3, nonce = 4. `operator` is `<` = 0, `<=` = 1, `=` = 2, `!=` = 3, `>` = 4, `>=` = 5. Fields a predicate does not use are zero, and a storage predicate with no mask signs `U256::MAX`. Before signing, sort the predicates by their EIP-712 struct hashes in ascending byte order and keep any duplicates. Reordering your list then gives the same digest, while any added, dropped, or edited predicate gives a different one.
Only a secp256k1 key at the sender address can sign. Contract wallets and EIP-8130 actors without that key cannot use this, and neither can deposits or unprotected legacy transactions, which have no chain-bound domain. The node also refuses high-s signatures.
Node operators control enforcement with `--validity-signature-mode off|verify-if-present|required`, on forwarding ingress nodes and on builders:
| Mode | Unsigned predicates | Supplied signatures |
| --- | --- | --- |
| `off` (default) | Accepted | Kept and forwarded, never checked |
| `verify-if-present` | Accepted | Checked at raw ingress |
| `required` | Rejected for any non-empty batch | Checked at raw ingress |
The intended rollout is `verify-if-present` across every ingress node and builder first, then wallets move to signing, then the fleet flips to `required`. The `txpool.validity_signature.accepted{site,signature}` and `txpool.validity_signature.rejected{site,reason}` metrics show how far that migration has got.
This first appeared in `v1.5.0-rc.7` and ships in the final `v1.5.0`. `v1.4.2` does not have it, and rejects `validity_signature` as an unknown key. The flag defaults to `off`, so until Base announces otherwise, assume the public sequencer does not enforce signatures.
## Safety
Three further limits are worth internalising before writing one:
- **Storage predicates read raw slots.** They cannot call a view function or evaluate anything computed. You need the target contract's storage layout, and that layout is an implementation detail the contract author can change under an upgrade.
- **Only the state at execution counts.** The check runs against the state right before your transaction would execute. A condition true when you submit can be false by then, and the reverse. Treat the predicate as a filter, not a guarantee.
- **A zero-valued slot proves nothing.** An uninitialized contract, a proxy before initialization, and a CREATE2 address that has not been deployed yet all read as zero. None of them is safe to call on that basis.
Do not use a transaction's position as a randomness source.
## Fees, ordering, and lifecycle
Fees follow the normal rules for the transaction type. For EIP-1559 set `maxFeePerGas` and `maxPriorityFeePerGas` on the signed transaction as usual.
A transaction that never becomes eligible costs nothing onchain. One that is included pays normal execution fees, and it pays them even if it reverts.
**Expiry is mandatory, and it is bounded on both sides.** Every submission has to carry a `block_number` predicate with an upper bound, written with `<`, `<=`, or `=`. Leave it out and the node refuses the transaction outright. Pair it with `flashblock_index` to tighten the bound to a position within the block.
Only an upper bound counts. A `>`, `>=`, or `!=` comparison on `block_number` does not establish expiry, and neither does a `balance`, `nonce`, `storage`, or `flashblock_index` predicate. State conditions can recover after failing, and the flashblock index restarts every block, so none of them puts a ceiling on how long a transaction can wait. When several `block_number` predicates carry upper bounds, the tightest one decides the lifetime.
Two further checks apply once a canonical head exists. A bound already behind the block being built is rejected, because every block it still permits has been sealed. A bound past the node's configured window is rejected as well. That window is 60 seconds of wall-clock time by default, which the node converts into a block count using the current full-block cadence: roughly 30 blocks on two-second blocks, and roughly 300 once Denim's 200ms cadence is active. Operators set it with `--validity-max-expiry-secs`.
A bound equal to the block currently being built is fine. The transaction can still land in a later Flashblock of that same block.
Once the block named by the bound is committed, the node drops the transaction from its pool, because no later block can include it. Before #5333 the node kept it for one more block. During that block the node still forwarded it and still counted it against admission capacity. The fix is not in `v1.4.2`. It first ships in `v1.5.0-rc.1`.
A `flashblock_index` upper bound now expires sooner too (#5477). The node drops the transaction as soon as the last Flashblock it allows is published, instead of waiting for the whole block to seal. This frees the nonce at once. An unbumped replacement with the same nonce can land in a later Flashblock of the same block, which an expired entry used to block. A failed publication does not trigger the drop. This change also first ships in `v1.5.0-rc.1`.
**Replacement** works the way it does for ordinary transactions: sign again with the same sender and nonce. If the node answers with an underpriced-replacement error, raise the fee fields, re-sign, and retry.
## Worked example
Build the predicate list first. This one waits for a storage slot to reach a value, and bounds the result to a block and a Flashblock position:
```ts
import type { Address, Hex } from 'viem';
const validity = [
{
type: 'storage',
params: {
address: '0x8ba1f109551bD432803012645Ac136ddd64DBA72' as Address,
slot: '0x8' as Hex,
op: '=',
value: '0x2a' as Hex,
},
},
{
type: 'block_number',
params: { op: '<=', value: '0x11a6a1' as Hex },
},
{
type: 'flashblock_index',
params: { op: '<=', value: '0x2' as Hex },
},
] as const;
```
Sign an EIP-1559 transaction against the sender's next nonce. The signed payload becomes the first RPC parameter:
```ts
import { createPublicClient, http, type Chain } from 'viem';
import { privateKeyToAccount } from 'viem/accounts';
const client = createPublicClient({ chain, transport: http(rpcUrl) });
const account = privateKeyToAccount(privateKey);
const fees = await client.estimateFeesPerGas();
const nonce = await client.getTransactionCount({
address: account.address,
blockTag: 'latest',
});
const rawTransaction = await account.signTransaction({
chainId: (chain as Chain).id,
type: 'eip1559',
nonce,
to: '0x...' as Address,
data: '0x...' as Hex,
value: 0n,
gas: 100_000n,
maxFeePerGas: fees.maxFeePerGas,
maxPriorityFeePerGas: fees.maxPriorityFeePerGas,
});
```
Then submit both parameters. Viem has no client method for this yet, so call the endpoint directly:
```ts
const response = await fetch(rpcUrl, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
jsonrpc: '2.0',
id: 1,
method: 'base_sendRawTransactionValidity',
params: [rawTransaction, { validity }],
}),
});
const body = await response.json();
if (body.error) throw new Error(body.error.message);
const hash = body.result;
```
## When a transaction does not land
Start by separating "not accepted" from "accepted but not included". A returned hash means the submission was accepted, so anything after that is an inclusion question.
**The method is unavailable.** The endpoint does not serve `base_sendRawTransactionValidity`. Today that means Vibenet or, on Base Sepolia, `https://sepolia-sequencer.base.org`; the regular `sepolia.base.org` endpoint returns `Method not found`.
**Submission fails.** Check that the first parameter really is a signed legacy, EIP-2930, or EIP-1559 transaction, and that the second parameter carries a non-empty `validity` array and no other key (apart from `validity_signature` on `v1.5.0-rc.7` and later). Then check each predicate's type, operator, and that every value is `0x`-prefixed hex.
Four rejections come from the expiry and batch rules rather than from malformed input. Each arrives as an invalid-parameters error naming the predicate's position in the array:
| Message | Cause |
| --- | --- |
| `validity transactions require a block-number predicate with an upper bound` | No `block_number` predicate uses `<`, `<=`, or `=` |
| `block-number predicate at index N already expired` | The bound sits behind the block being built |
| `block-number predicate at index N expires too far in the future` | The bound is past the node's lifetime window |
| `too many validity predicates` | The batch is over the 64-entry ceiling |
The first is the one to check first when a request that previously worked starts failing. A bounded lifetime is required on every submission, so a predicate set that only describes state conditions is no longer sufficient on its own.
**It stays pending.** Four ordinary explanations: a predicate is still false, other transactions are outbidding it, a replacement superseded it, or its `block_number` or `flashblock_index` bound has passed.
**It expired.** Sign and submit a fresh transaction with later bounds. An expired one does not revive.
**Replacement is underpriced.** Raise the fee fields and retry with the same sender and nonce.
When escalating, record the network, RPC provider, transaction hash, predicate type, submission time, and the full JSON-RPC error. Never paste private keys, authentication data, or complete signed transactions into a public channel.
---
# Crate Dependency Graph
Source: https://basehub.org/architecture/crate-graph/
Description: Visual map of workspace dependencies across the 8 crate groups in base/base.
The `base/base` workspace organizes 8 top-level crate groups into a directed acyclic dependency graph. This page traces how the groups connect, which crates are foundational, and where the integration boundaries sit.
## High-level dependency flow
The dependency graph flows downward: higher-level groups depend on lower-level ones, but not the reverse.
```
┌─────────────────────────────────────────────────────┐
│ infra │
│ based, basectl, roxy, websocket-proxy, ... │
└───────────┬──────────┬──────────┬───────────────────┘
│ │ │
v v v
┌──────────────┐ ┌──────────┐ ┌──────────┐
│ builder │ │ client │ │consensus │
│ core, pub, │ │ node,cli,│ │ protocol,│
│ metering │ │ engine, │ │ rpc,kona │
│ │ │ flash │ │ │
└──────┬───────┘ └────┬─────┘ └────┬─────┘
│ │ │
│ ┌────┘ │
│ v │
│ ┌──────────┐ │
└───►│execution │◄──────────┘
└────┬─────┘
│
v
┌──────────┐ ┌──────────┐
│ shared │◄────│ proof │
└────┬─────┘ └──────────┘
│
v
┌──────────┐
│ alloy │
└──────────┘
```
**Key observations:**
- **`alloy`** and **`shared`** sit at the bottom of the graph. They have no internal workspace dependencies and are consumed by everything above them.
- **`execution`** depends on `shared` and `alloy` for types, and is consumed by both `client` and `builder`.
- **`client`** is the main integration point -- it pulls in execution, consensus, and shared.
- **`infra`** binaries sit at the top, assembling components from multiple groups.
- **`proof`** is relatively isolated. It depends on `shared` for types but has its own Kona-derived execution and derivation logic (designed to run inside a fault proof VM).
## Detailed crate-level dependencies
### Alloy crates
```
alloy/
└── (external: alloy-rs ecosystem)
No internal workspace dependencies.
Consumed by: shared, client, consensus, builder, execution
```
The alloy crates define Ethereum and Optimism wire types using the [Alloy](https://github.com/alloy-rs/alloy) framework. They are leaf dependencies with no intra-workspace imports.
### Shared crates
```
shared/
├── base-primitives ← foundational types (blocks, txs, receipts)
├── base-bundles ← depends on: base-primitives
├── base-jwt ← standalone (JWT auth tokens)
├── base-cli-utils ← standalone (CLI helpers)
├── base-engine-ext ← depends on: base-primitives
├── base-access-lists ← depends on: base-primitives
├── base-reth-rpc-types ← depends on: base-primitives
└── base-txpool-rpc ← depends on: base-primitives, base-reth-rpc-types
```
[`base-primitives`](https://github.com/base/base/tree/main/crates/shared/primitives) is the single most depended-upon crate. It defines `BaseTxEnvelope`, `BaseBlock`, chain IDs, and fee calculation types. Almost every other workspace crate imports it directly or transitively.
### Execution crates
```
execution/
└── (execution crates)
depends on: base-primitives, alloy types
consumed by: client, builder
```
The execution group provides Base's EVM configuration. It depends on `base-primitives` for block and transaction types and on alloy types for encoding. The `client` and `builder` groups both consume execution crates to run EVM state transitions.
### Consensus crates
```
consensus/
├── base-protocol ← depends on: base-primitives
├── base-consensus-rpc ← depends on: base-protocol, base-primitives
│
└── kona-* (vendored)
├── kona-node-service ← top-level; depends on most kona-* below
├── kona-engine ← depends on: kona-derive, kona-providers-alloy
├── kona-derive ← depends on: kona-sources, kona-genesis, kona-hardforks
├── kona-gossip ← depends on: kona-disc, kona-peers
├── kona-sources ← depends on: kona-providers-alloy
├── kona-providers-alloy ← depends on: kona-genesis
├── kona-genesis ← depends on: kona-registry
├── kona-registry ← depends on: kona-hardforks
├── kona-hardforks ← leaf
├── kona-disc ← leaf (peer discovery)
├── kona-peers ← leaf (peer management)
├── kona-cli ← leaf (CLI utils)
└── kona-macros ← leaf (proc macros)
```
The Kona crates form their own internal dependency tree. `kona-node-service` is the top-level entry point, and `kona-derive` is the core derivation pipeline. The Base-native consensus crates (`base-protocol`, `base-consensus-rpc`) integrate with the Kona stack and provide Base-specific protocol constants.
### Builder crates
```
builder/
├── base-builder-core ← depends on: base-primitives, base-bundles,
│ execution crates, base-engine-ext
├── base-builder-publish ← depends on: base-builder-core, base-primitives
└── base-builder-metering ← depends on: base-builder-core
```
The builder's dependency chain:
```
base-builder-metering ──► base-builder-core ──► base-primitives
│ │
base-builder-publish ───────────┘ v
alloy types
│
v
execution crates
```
`base-builder-core` contains the block building loop and depends on execution crates for EVM access and on `base-primitives` for block/transaction types. `base-builder-publish` handles the output side -- streaming flashblocks and submitting sealed blocks.
### Client crates
```
client/
├── base-client-node ← depends on: base-client-cli, base-client-engine,
│ base-flashblocks, base-metering, base-txpool-tracing,
│ execution crates, consensus crates, shared crates
├── base-client-cli ← depends on: base-cli-utils
├── base-client-engine ← depends on: base-primitives, base-engine-ext
├── base-flashblocks ← depends on: base-primitives
├── base-metering ← depends on: base-primitives, base-reth-rpc-types
└── base-txpool-tracing ← depends on: base-primitives
```
`base-client-node` is the integration hub. It is where Reth's `NodeBuilder` is configured with all Base-specific components. Its dependency list is the longest in the workspace because it wires together execution, consensus, flashblocks, metering, and the transaction pool.
### Proof crates
```
proof/
├── kona-proof ← depends on: kona-driver, kona-mpt
├── kona-driver ← depends on: kona-executor, kona-preimage
├── kona-executor ← depends on: kona-mpt, kona-preimage
├── kona-mpt ← leaf (Merkle Patricia Trie)
├── kona-preimage ← leaf (preimage oracle interface)
├── kona-std-fpvm ← leaf (FPVM runtime)
└── kona-std-fpvm-proc ← leaf (proc macros for FPVM)
```
The proof group is intentionally isolated from the rest of the workspace. It must be compilable to FPVM targets (MIPS/RISC-V), so it avoids pulling in networking, RPC, or OS-specific dependencies. It re-implements derivation and execution logic using `kona-preimage` to read data from the host environment.
### Infra crates
```
infra/
├── based ← depends on: client, builder, consensus, shared
├── basectl-cli ← depends on: shared (base-cli-utils, base-primitives)
├── ingress-rpc-lib ← retired 2026-09-21 (was: shared — base-jwt, base-primitives)
├── websocket-proxy ← depends on: shared (base-primitives)
├── mempool-rebroadcaster ← depends on: shared (base-primitives, base-txpool-rpc)
├── audit-archiver-lib ← depends on: shared (base-primitives)
└── system-tests ← depends on: client, shared, infra binaries
```
Infra crates are consumers. They import from the lower layers but are not imported by any other workspace crate (except `system-tests`, which depends on infra binaries for integration testing).
## Dependency rules
The workspace follows these conventions:
1. **No circular dependencies.** The crate graph is a DAG.
2. **Shared and alloy are leaf layers.** They never depend on higher-level groups.
3. **Proof is sandboxed.** Proof crates do not depend on client, builder, or infra crates, keeping them FPVM-compilable.
4. **External Reth dependencies flow through execution and client.** Other groups do not directly import `reth-*` crates; they go through the abstractions in execution or shared.
5. **Kona crates are vendored, not patched.** The consensus and proof groups contain full copies of Kona crates (not Git patches), allowing Base-specific modifications while preserving the ability to pull upstream changes.
## Workspace Cargo.toml structure
All inter-crate dependencies are declared as workspace dependencies in the root [`Cargo.toml`](https://github.com/base/base/blob/main/Cargo.toml). Individual crate `Cargo.toml` files reference these with `workspace = true`:
```toml
# Root Cargo.toml (excerpt)
[workspace.dependencies]
base-primitives = { path = "crates/shared/primitives" }
base-builder-core = { path = "crates/builder/core" }
base-client-node = { path = "crates/shared/node" }
# ... etc.
```
This centralized dependency management ensures version consistency and makes it straightforward to audit the full dependency graph.
---
# Engineering Blog Index
Source: https://basehub.org/architecture/engineering-blog/
Description: Running paraphrased index of architecture-relevant posts from the Base engineering blog.
A running index of paraphrased entries from the [Base engineering blog](https://blog.base.dev/) that touch on `base/base` architecture — proof systems, builder internals, decentralization milestones, and protocol upgrades. Entries are paraphrased summaries; follow the linked post for full detail.
## 2026
### Introducing Base Cobalt — 30 September 2026
Posted the day Cobalt reached Mainnet, the launch note boils the fork down to two user-facing changes. Validity transactions let a trader sign once and hand Base a set of conditions, such as a pool price floor plus a block-number deadline; the transaction sits unseen until every condition holds, and lapses if the deadline passes first. On the B20 side, issuers gain composite policies that combine existing allowlists and blocklists with AND or OR logic, scheduled multiplier changes for corporate actions (aligned with ERC-8056, display-only, raw balances untouched), and `seizeWithMemo` for moving a frozen balance in one recorded transfer. The post tells indexers to pick up the new ABI and names 200ms blocks, protocol-level smart accounts, and part of Glamsterdam as the next items. Its request sample merges two predicates into one object and does not parse as printed; see the local [Validity Transactions](/api-reference/validity-transactions/) reference for working shapes, the [Cobalt hardfork overview](/specifications/cobalt-overview/) for scope, or read the original at [blog.base.dev/cobalt](https://blog.base.dev/cobalt).
### B20: The Standard Behind Tokenized Stocks on Base — 27 August 2026
Base sets out the reasoning behind B20, the native token standard built so real-world assets such as tokenized equities can live onchain without a bespoke contract for each one. A dynamic multiplier lets one token track corporate actions — splits, dividends — by rescaling every holder's balance rather than reissuing anything, and compliance controls sit inside the standard as modular policy slots instead of being written into each issuer's own code. See the local [B20 native token standard](/specifications/b20/) writeup and the [tokenized stocks integration guide](/integration-guides/tokenized-stocks/), or read the original at [blog.base.dev/b20-tokenized-stocks-on-base](https://blog.base.dev/b20-tokenized-stocks-on-base).
### Making AWS Nitro Validation Feasible Onchain — 11 August 2026
Two Fusaka changes — a higher price on large `MODEXP` calls (EIP-7883) and a 16.7M gas ceiling per transaction (EIP-7825) — drove one P-384 signature check to roughly 50.6M gas and left the original `base/nitro-validator` library unable to run at all. Base rebuilt it around checked hints: each costly modular inverse now arrives in calldata from offchain, and the contract confirms it with a single multiplication before use, so a bad hint reverts instead of skewing the result. A full cold attestation now fits in five transactions well under the cap, and Base plans to use the approach for the canonical bridge's proof system in place of ZK proofs for onchain Nitro verification. See the local [onchain Nitro attestation validation](/architecture/nitro-validator/) deep-dive, or read the original at [blog.base.dev/making-aws-nitro-validation-feasible-onchain](https://blog.base.dev/making-aws-nitro-validation-feasible-onchain).
### Native Account Abstraction — 17 July 2026
Base, working with Optimism, Coinbase, and WalletConnect, is bringing account abstraction into the protocol itself via EIP-8130, replacing the above-the-EVM ERC-4337 model that made smart accounts expensive and slow. Co-designing the transaction type with the chain cuts per-transaction cost to users by more than 2x — a USDC transfer drops from 125,000 to 46,000 gas — while adding native batching, sponsorship, session keys, sub-accounts, and cross-chain portability. The post put it on Base in the Cobalt upgrade in September 2026, with a new ephemeral devnet (Base Vibenet) for early testing; that plan has since changed, and EIP-8130 now sits behind a gate no public network sets. See the local [Native Account Abstraction](/architecture/native-account-abstraction/) deep-dive, or read the original at [blog.base.dev/native-account-abstraction](https://blog.base.dev/native-account-abstraction).
### Postmortem: June 25th Block Production Outage — 27 June 2026
Base published a detailed postmortem for the two mainnet block production halts on June 25 and 26, 2026 (116 minutes and 20 minutes). Both traced to the same sequencer bug: a failed transaction left the EVM journal state dirty, so a following valid transaction was charged the wrong gas and produced a block no other node would accept, stopping the chain. The patch ([PR #3806](https://github.com/base/base/pull/3806)) restored correct journal handling, and a separate engine-reset race in the sequencers ([PR #3805](https://github.com/base/base/pull/3805/changes)) explains the second-day recurrence. See the local [June 2026 block production outage](/architecture/june-2026-block-production-outage/) deep-dive for the full timeline, or read the original at [blog.base.dev/postmortem-june-25th-block-production-outage](https://blog.base.dev/postmortem-june-25th-block-production-outage).
### Introducing Base Beryl — 18 June 2026
Beryl, Base's second network upgrade, is live on testnet and reaches mainnet on June 25, 2026. It turns Base into a first-class issuance platform through the B20 native token standard, tightens capital efficiency by shortening the withdrawal delay, and raises throughput with Reth V2. The post frames Beryl as the next step after Azul, which laid down the Base Stack and the multiproof system. See the local [Beryl hardfork overview](/specifications/beryl-overview/) for the paraphrased spec, or read the original at [blog.base.dev/introducing-base-beryl](https://blog.base.dev/introducing-base-beryl).
### Multiproofs on Base — 21 May 2026
Base has shipped its multiproof system on mainnet, pairing TEE and ZK provers so the chain can detect and respond to bugs onchain — the technical bar required to reach Stage 2 decentralization in Vitalik Buterin's framework. The new system also speeds up withdrawals by removing the long optimistic challenge window and lowers the bond capital honest defenders previously needed to keep posted. Read the full post at [blog.base.dev/multiproofs-on-base](https://blog.base.dev/multiproofs-on-base).
---
# Execution Pipeline
Source: https://basehub.org/architecture/execution-pipeline/
Description: Transaction flow from RPC receipt through the transaction pool, payload building, EVM execution, state trie update, and block production.
A transaction enters the Base node through the RPC layer, lands in the pool, gets selected by the builder, executes against the EVM, and lands in a sealed block committed to the state trie. Each stage below names the crate that owns it.
## Pipeline overview
```
User/Wallet
│
▼
┌──────────────────┐
│ 1. RPC Ingress │ ingress-rpc-lib, base-reth-rpc-types
└────────┬─────────┘
▼
┌──────────────────┐
│ 2. Transaction │ base-txpool-rpc, base-txpool-tracing,
│ Pool │ base-access-lists, base-bundles
└────────┬─────────┘
▼
┌──────────────────┐
│ 3. Payload │ base-builder-core, base-engine-ext
│ Building │
└────────┬─────────┘
▼
┌──────────────────┐
│ 4. EVM │ execution crates (EvmConfig),
│ Execution │ base-primitives
└────────┬─────────┘
▼
┌──────────────────┐
│ 5. State Trie │ Reth's state database,
│ Update │ kona-mpt (for proofs)
└────────┬─────────┘
▼
┌──────────────────┐
│ 6. Block │ base-builder-publish,
│ Sealing │ base-client-engine
└──────────────────┘
```
## Stage 1: RPC ingress
Transactions enter the system through JSON-RPC endpoints. The Base node exposes the standard Ethereum JSON-RPC API (`eth_sendRawTransaction`) plus Base-specific extensions.
**Relevant crates:**
- In production deployments a proxy sits in front of the node, handling rate limiting, authentication (via `base-jwt`), and request routing before forwarding validated requests to the node's internal RPC server. The crate that did this, [`ingress-rpc-lib`](https://github.com/base/base/tree/v1.4.0/crates/infra/ingress-rpc), was removed on 2026-09-21 and the link points at `v1.4.0`, the last release containing it. The stage itself is unchanged; only the component that fills it moved out of this repository.
- [`base-reth-rpc-types`](https://github.com/base/base/tree/main/crates/shared/rpc-types) -- defines the request and response types for Base-specific RPC methods.
When the node receives `eth_sendRawTransaction`, it:
1. Decodes the RLP-encoded transaction bytes into a `BaseTxEnvelope` (defined in `base-primitives`).
2. Validates the signature, chain ID, and basic transaction fields.
3. Submits the transaction to the transaction pool.
For bundle submissions (used by MEV searchers), the `base-bundles` crate defines the `BaseBundle` type, which groups multiple transactions with ordering constraints and tip payments.
## Stage 2: Transaction pool
The transaction pool holds pending transactions that are valid but not yet included in a block. Base uses Reth's built-in transaction pool with custom extensions.
**Relevant crates:**
- [`base-txpool-rpc`](https://github.com/base/base/tree/main/crates/shared/txpool-rpc) -- RPC methods for querying pool state (`txpool_content`, `txpool_status`, and Base-specific methods).
- [`base-txpool-tracing`](https://github.com/base/base/tree/main/crates/client/txpool-tracing) -- emits tracing events for transaction lifecycle (received, promoted, dropped, included). Useful for debugging and monitoring.
- [`base-access-lists`](https://github.com/base/base/tree/main/crates/shared/access-lists) -- access list generation. When a transaction declares storage slots it will touch, the pool can pre-validate these and the execution engine can optimize state loading.
- [`base-bundles`](https://github.com/base/base/tree/main/crates/shared/bundles) -- bundle handling logic. Bundles are stored separately from individual transactions and are evaluated atomically during payload building.
The pool maintains several sub-pools:
- **Pending** -- transactions ready for immediate inclusion (correct nonce, sufficient balance).
- **Queued** -- transactions with future nonces, waiting for gaps to fill.
- **Basefee** -- transactions whose `maxFeePerGas` is below the current base fee. They become pending when the base fee drops.
Transactions are sorted by **effective tip** (the priority fee the builder would receive). The builder pulls from the pending pool in tip-descending order.
## Stage 3: Payload building
Payload building is the process of selecting transactions from the pool and assembling them into a candidate block. In Base, this happens in the builder, which operates on a configurable interval.
**Relevant crates:**
- [`base-builder-core`](https://github.com/base/base/tree/main/crates/builder/core) -- the main building loop. It:
1. Receives a `PayloadAttributes` message from the consensus layer (via `engine_forkchoiceUpdated`). This message includes the parent block hash, timestamp, and any **deposit transactions** from L1.
2. Pulls pending transactions from the pool, sorted by effective tip.
3. Applies each transaction against the current state to check validity and compute gas used.
4. Respects the block gas limit and any per-transaction gas limits.
5. Optionally includes bundles, evaluating them atomically (all-or-nothing).
- [`base-engine-ext`](https://github.com/base/base/tree/main/crates/shared/engine-ext) -- Engine API extensions that carry additional payload attributes specific to Base (e.g., Flashblocks configuration, builder identity).
### Deposit transactions
Every L2 block begins with **deposit transactions** -- L1-to-L2 messages derived from L1 by the consensus layer. These are mandatory and always placed at the top of the block, before any user transactions. The builder does not select them from the pool; they are injected by the engine.
The ordering within a block is:
```
┌──────────────────────────────────────┐
│ Deposit transactions (from L1) │ ← mandatory, first
├──────────────────────────────────────┤
│ User transactions (from pool) │ ← sorted by effective tip
├──────────────────────────────────────┤
│ Bundle transactions (if any) │ ← evaluated atomically
└──────────────────────────────────────┘
```
### Flashblocks sub-intervals
In Flashblocks mode, the builder does not wait for the full 2-second block time. Instead, it produces partial payloads (**flashblocks**) every 200 milliseconds. Each flashblock contains whatever transactions have been processed since the last interval. See [Flashblocks Pipeline](/architecture/flashblocks-pipeline/) for details.
## Stage 4: EVM execution
Each transaction is executed against the Ethereum Virtual Machine. Base uses Reth's EVM with an Optimism-specific configuration.
**Relevant crates:**
- Execution crates in [`crates/execution/`](https://github.com/base/base/tree/main/crates/execution) -- provide the `EvmConfig` implementation that configures:
- **L1 data fee** -- Optimism charges an additional fee based on the transaction's L1 data cost (the cost of posting the transaction data to L1). This is calculated using the L1 base fee and blob base fee, which are read from the L1 attributes deposit transaction at the start of each block.
- **Custom precompiles** -- Base may add precompiles beyond the standard Ethereum set.
- **System transactions** -- the L1 attributes deposit transaction updates on-chain variables (`l1BaseFee`, `l1BlobBaseFee`, `sequenceNumber`, etc.) by calling the `L1Block` system contract.
- [`base-primitives`](https://github.com/base/base/tree/main/crates/shared/primitives) -- defines the transaction envelope types that the EVM processes, including Optimism deposit transactions (`TxDeposit`).
The EVM execution loop for each transaction:
1. **Load sender state** -- retrieve the sender's nonce and balance from the state trie.
2. **Validate** -- check nonce matches, balance covers `gasLimit * gasPrice + value`, and the transaction is well-formed.
3. **Deduct upfront cost** -- subtract the maximum possible gas cost from the sender's balance.
4. **Execute** -- run the EVM bytecode. For contract creations, deploy the code. For calls, execute the target contract.
5. **Apply state changes** -- write modified storage slots, created/destroyed accounts, and balance transfers to the state.
6. **Calculate gas refund** -- refund unused gas to the sender (up to the refund cap).
7. **Pay fees** -- transfer the priority fee to the builder's fee recipient. The base fee is burned. The L1 data fee is sent to the L1 fee vault.
8. **Emit receipt** -- produce a transaction receipt with status, gas used, and logs.
## Stage 5: State trie update
After all transactions in the payload are executed, the resulting state changes are committed to the state trie.
Base uses Reth's state storage, which maintains:
- **Account trie** -- maps addresses to account state (nonce, balance, storage root, code hash).
- **Storage tries** -- per-account Merkle Patricia Tries mapping storage slots to values.
- **State root** -- the root hash of the account trie, included in the block header.
The state root is a cryptographic commitment to the entire world state after the block's execution. It is used by:
- **Consensus** -- the consensus layer verifies that the state root in a proposed block matches the result of re-executing all transactions.
- **Fault proofs** -- the proof system (`kona-mpt`) uses Merkle Patricia Trie proofs to verify individual state transitions without re-executing the entire block.
For fault proof purposes, [`kona-mpt`](https://github.com/base/base/tree/main/crates/proof/mpt) provides a standalone MPT implementation that can verify inclusion/exclusion proofs against a known state root inside the FPVM.
## Stage 6: Block sealing
Once all transactions are executed and the state root is computed, the block is sealed.
**Relevant crates:**
- [`base-builder-publish`](https://github.com/base/base/tree/main/crates/builder/publish) -- the builder packages the sealed payload (transactions, receipts, state root, block header) and publishes it.
- [`base-client-engine`](https://github.com/base/base/tree/main/crates/client/engine) -- the node's engine handler receives the sealed payload via `engine_newPayload` and:
1. Validates the payload (re-executes transactions and checks the state root).
2. Stores the block in the database.
3. Updates the chain tip via `engine_forkchoiceUpdated`.
The sealed block header contains:
| Field | Source |
|---|---|
| `parentHash` | Previous block's hash |
| `stateRoot` | Computed from stage 5 |
| `transactionsRoot` | Merkle root of the transaction list |
| `receiptsRoot` | Merkle root of the receipt list |
| `logsBloom` | Bloom filter over all logs |
| `gasUsed` | Total gas consumed by all transactions |
| `timestamp` | From the `PayloadAttributes` |
| `baseFeePerGas` | Calculated from parent block's gas usage via EIP-1559 |
| `extraData` | Builder-specific metadata |
## End-to-end latency
In normal operation (non-Flashblocks mode), the full pipeline from transaction receipt to block sealing takes up to 2 seconds (the L2 block time). In Flashblocks mode, the first confirmation comes within 200 milliseconds because the builder streams partial results as they are produced.
| Mode | First confirmation | Final block |
|---|---|---|
| Standard | ~2 seconds | 2 seconds |
| Flashblocks | ~200 milliseconds | 2 seconds |
The Flashblocks pipeline does not change the final block structure -- it only provides earlier visibility into which transactions will be included. The sealed block at the end of the 2-second interval is identical regardless of whether Flashblocks streaming was active.
---
# Flashblocks Pipeline
Source: https://basehub.org/architecture/flashblocks-pipeline/
Description: How the builder produces flashblocks at 200ms sub-block intervals, streams them over WebSockets, and reconciles state at block boundaries.
Flashblocks are partial block updates the builder emits every 200 milliseconds within a 2-second L2 block. They deliver sub-second inclusion confirmation without altering the sealed block or the consensus protocol.
The sections below cover how the builder produces flashblocks, how they stream to consumers, and how state reconciles when the block seals.
## Motivation
Standard L2 blocks on Base are produced every 2 seconds. For latency-sensitive applications (trading, gaming, real-time UIs), 2 seconds is too slow for a responsive experience. Flashblocks reduce the effective confirmation time to approximately 200 milliseconds by streaming the builder's work-in-progress.
A flashblock is not a new consensus primitive. It is an **application-layer optimization**: the builder shares its intermediate results before the block is finalized. Consumers who trust the sequencer can act on flashblocks immediately; consumers who require consensus finality wait for the sealed block as usual.
## Architecture
The Flashblocks pipeline involves three crate groups:
```
┌──────────────────────────────────────────────────────────────┐
│ Builder │
│ │
│ ┌───────────────────┐ ┌───────────────────┐ │
│ │ base-builder-core │───►│base-builder-publish│──► Engine API │
│ │ │ │ │ │
│ │ tx selection, │ │ flashblock framing│ │
│ │ EVM execution, │ │ WebSocket publish │ │
│ │ 200ms timer │ │ sealed block emit │ │
│ └───────────────────┘ └────────┬──────────┘ │
│ │ │
│ ┌───────────────────┐ │ │
│ │base-builder-meter.│ │ │
│ │ │ │ │
│ │ build time, tx │ │ │
│ │ count, revenue │ │ │
│ └───────────────────┘ │ │
└────────────────────────────────────┼──────────────────────────┘
│
▼
┌───────────────────┐
│ websocket-proxy │ (infra)
│ │
│ fan-out to │
│ subscribers │
└────────┬──────────┘
│
┌──────────────┼──────────────┐
▼ ▼ ▼
Client A Client B Client C
```
```
┌──────────────────────────────────────────────────────────────┐
│ Client Node │
│ │
│ ┌───────────────────┐ ┌───────────────────┐ │
│ │ base-flashblocks │◄───│ base-client-engine│ │
│ │ │ │ │ │
│ │ flashblock state │ │ engine API handler│ │
│ │ tracking, sub │ │ payload validation│ │
│ │ management │ │ │ │
│ └───────────────────┘ └───────────────────┘ │
└──────────────────────────────────────────────────────────────┘
```
## The build loop
The core building loop in [`base-builder-core`](https://github.com/base/base/tree/main/crates/builder/core) operates on a timer-driven cycle within each 2-second block interval.
### Step 1: Receive payload attributes
The consensus layer sends `engine_forkchoiceUpdated` with `PayloadAttributes` to begin a new block. The attributes include:
- **Parent block hash** -- the block to build on top of.
- **Timestamp** -- the L2 timestamp for the new block.
- **Deposit transactions** -- mandatory L1-to-L2 messages that must appear at the start of the block.
- **Fee recipient** -- the address that receives priority fees.
- **Flashblocks configuration** -- whether flashblocks are enabled and the sub-interval duration (default: 200ms).
### Step 2: Initialize the build context
The builder sets up:
- A mutable state overlay on top of the parent block's state.
- A running transaction list (starts with the deposit transactions).
- A cumulative gas counter.
- A 200ms interval timer.
- A flashblock sequence counter (starting at 0).
### Step 3: Execute transactions in sub-intervals
The builder enters a loop that repeats every 200 milliseconds until the block time expires:
```
for each 200ms interval:
1. Pull pending transactions from the pool (sorted by effective tip)
2. Execute each transaction against the state overlay:
- If the transaction succeeds: append to the running tx list,
update cumulative gas, record the receipt
- If the transaction fails (reverts, out-of-gas, nonce mismatch):
skip it and try the next
3. Compute the intermediate state root
4. Emit a flashblock containing:
- The transactions processed in this interval
- The receipts for those transactions
- The cumulative gas used so far
- The intermediate state root
- The flashblock index (0, 1, 2, ...)
- The block number and parent hash
5. Increment the flashblock sequence counter
```
A typical 2-second block produces up to **10 flashblocks** (2000ms / 200ms). In practice, the number may be fewer if the builder finishes processing all pending transactions before the block time expires.
### Step 4: Seal the block
When the block timer expires, the builder:
1. Stops accepting new transactions.
2. Computes the final state root.
3. Assembles the complete block header (with all transactions from all flashblocks).
4. Sends the sealed payload to the node via `engine_newPayload`.
The sealed block is identical to what would have been produced without Flashblocks. The only difference is that consumers received incremental updates during construction.
## Publishing: `base-builder-publish`
The [`base-builder-publish`](https://github.com/base/base/tree/main/crates/builder/publish) crate handles the output side of the pipeline. It is responsible for two output channels:
### Engine API output
The sealed block payload is sent to the node's Engine API (`engine_newPayload`), followed by a `engine_forkchoiceUpdated` call to update the canonical chain tip. This is the standard Reth/OP Stack block import path.
### WebSocket streaming output
Flashblocks are streamed in real time over a WebSocket connection. Each flashblock is serialized as a JSON object and pushed to connected subscribers.
The publish crate:
1. Maintains a set of WebSocket connections (via the `websocket-proxy` infra binary, which handles fan-out).
2. Serializes each flashblock into the `flashblocks_v0` JSON-RPC notification format.
3. Sends the notification to the proxy, which distributes it to all subscribers.
4. At the end of the block, sends a final `flashblocks_v0` notification with `sealed: true`, signaling that the block is complete.
### Flashblock message format
Each flashblock notification contains:
```json
{
"jsonrpc": "2.0",
"method": "flashblocks_v0",
"params": {
"index": 3,
"blockNumber": "0x1a2b3c",
"parentHash": "0xabc...def",
"timestamp": "0x67890",
"transactions": ["0x...rlp1", "0x...rlp2"],
"receipts": [{ ... }, { ... }],
"stateRoot": "0x...",
"gasUsed": "0x...",
"sealed": false
}
}
```
When `sealed` is `true`, the message represents the final state of the block. Consumers can treat a `sealed: true` flashblock as equivalent to a full block notification.
## WebSocket proxy: fan-out and backpressure
The [`websocket-proxy`](https://github.com/base/base/tree/main/crates/infra/websocket-proxy) binary sits between the builder and external consumers. It exists because the builder should focus on building blocks, not managing thousands of WebSocket connections.
The proxy:
- Accepts incoming WebSocket connections from clients.
- Subscribes to the builder's flashblock stream (a single connection).
- Fans out each flashblock notification to all connected clients.
- Applies backpressure: if a client cannot keep up, the proxy drops messages for that client rather than blocking the builder.
- Handles connection lifecycle (ping/pong, reconnection, graceful shutdown).
This separation ensures that a slow or misbehaving consumer cannot affect block building performance.
## Client-side: `base-flashblocks`
On the node side, the [`base-flashblocks`](https://github.com/base/base/tree/main/crates/client/flashblocks) crate manages flashblock state within the running node.
Its responsibilities:
- **Tracking in-progress flashblocks** -- maintains a buffer of flashblocks for the current block interval, updating as new ones arrive from the builder.
- **Subscription management** -- the node exposes its own `flashblocks_subscribe` RPC method for local consumers. The `base-flashblocks` crate manages these subscriptions and forwards flashblock notifications.
- **State reconciliation** -- when the sealed block arrives via `engine_newPayload`, the crate reconciles the flashblock state with the final block. Any speculative state derived from flashblocks is replaced by the canonical block state.
## State reconciliation
Flashblocks introduce a concept of **speculative state**: consumers act on transactions that are included in a flashblock but not yet in a sealed block. In the normal case, the sealed block contains exactly the union of all flashblock transactions, so speculative state matches final state perfectly.
However, there are edge cases:
### Reorgs within a block interval
If the builder receives a new `forkchoiceUpdated` that changes the parent block during construction (e.g., due to an L1 reorg affecting deposit transactions), the builder:
1. Discards the in-progress block.
2. Sends a `flashblocks_v0` notification with `"reorg": true` to signal that previous flashblocks for this block number are invalid.
3. Starts building a new block from the updated parent.
Consumers must handle reorg notifications by discarding any speculative state derived from the invalidated flashblocks.
### Builder restarts
If the builder process restarts mid-block, flashblock numbering resets. The `websocket-proxy` detects the upstream disconnection and sends a disconnect notification to subscribers. When the builder reconnects, it starts a fresh block interval.
## Metering: `base-builder-metering`
The [`base-builder-metering`](https://github.com/base/base/tree/main/crates/builder/metering) crate collects performance metrics from the build loop:
| Metric | Description |
|---|---|
| `builder_flashblock_build_time_ms` | Time to produce each flashblock |
| `builder_flashblock_tx_count` | Number of transactions per flashblock |
| `builder_block_total_gas` | Total gas used in the sealed block |
| `builder_block_tx_count` | Total transactions in the sealed block |
| `builder_block_revenue_wei` | Total priority fees earned by the builder |
| `builder_block_build_time_ms` | Wall-clock time for the full 2-second build cycle |
| `builder_flashblock_count` | Number of flashblocks produced per block |
These metrics are exported via Prometheus and are critical for monitoring builder performance in production. A drop in `flashblock_tx_count` or a spike in `flashblock_build_time_ms` can indicate EVM execution bottlenecks or transaction pool issues.
## Timeline of a single block
The following timeline illustrates a typical 2-second block with Flashblocks:
```
Time (ms) Event
───────── ─────
0 forkchoiceUpdated received; builder starts block N
0-10 Deposit transactions executed
10-200 User transactions executed from pool
200 Flashblock 0 emitted (deposits + first batch of user txs)
200-400 More user transactions executed
400 Flashblock 1 emitted
400-600 More user transactions executed
600 Flashblock 2 emitted
... (continues every 200ms)
1800-2000 Final batch of user transactions executed
2000 Flashblock 9 emitted (final interval)
2000 Block sealed; engine_newPayload sent
2000+ forkchoiceUpdated confirms block N as canonical
```
In this example, a user whose transaction was included in Flashblock 0 received confirmation at t=200ms -- a 10x improvement over the 2-second block time.
## Integration with the execution pipeline
Flashblocks do not change the execution pipeline described in [Execution Pipeline](/architecture/execution-pipeline/). The EVM execution, state trie updates, and block sealing steps are identical. Flashblocks simply add **observation points** at 200ms intervals, allowing external consumers to see progress before the block is complete.
The key invariant is: **the set of transactions in the sealed block is exactly the union of all flashblock transaction sets for that block**. There are no transactions that appear in a flashblock but not in the sealed block (barring the reorg case described above), and no transactions that appear in the sealed block but not in any flashblock.
---
# June 2026 Block Production Outage
Source: https://basehub.org/architecture/june-2026-block-production-outage/
Description: Postmortem of the two June 2026 Base mainnet block production halts caused by stale EVM journal state in the sequencer, plus the mitigation and follow-up work.
import { Aside } from '@astrojs/starlight/components';
Base mainnet halted block production twice in late June 2026. The first halt began at 11:47am EDT on June 25 and ran for 116 minutes; the second began at 11:28am EDT on June 26 and lasted 20 minutes. Both share a single root cause, so this page treats them together. Chain integrity was preserved and user funds were never at risk — sequencing resumed safely once the underlying bug was patched.
## Root cause
The defect lived in the sequencer's block-building path: after a transaction failed validation, the EVM journal — the record of accounts and storage slots touched during execution — was not reset. When an invalid transaction arrived at the builder, it failed during execution as designed, but the dirty journal state survived instead of being rolled back.
The next valid transaction then executed against that leftover state before the journal was cleared. Because the journal no longer reflected reality, the gas charged to the valid transaction was wrong, and the block it landed in carried an invalid state transition. No other node would accept a block produced from that corrupted state, so the chain stopped advancing.
## Impact
For the duration of each outage, two effects were visible across the network:
- **Block production stopped.** No new L2 blocks were sealed. Both sequencer and validator nodes were stuck behind the invalid block and could not move forward until sequencing was restored.
- **Transactions could not be included.** Pending transactions piled up in the mempool, which eventually exceeded its storage capacity and began rejecting new submissions. Calls to `eth_sendRawTransaction` returned errors throughout the incident.
## Mitigation
The fix patched the sequencers so the journal state is correctly updated during execution. It shipped as [base/base PR #3806](https://github.com/base/base/pull/3806).
Recovery took longer than the patch alone would suggest, because of an unrelated infrastructure condition. The sequencers in the active/passive cluster sync at the consensus layer rather than via execution sync like validator nodes do, and the engine reset path carried a race condition that stopped the sequencers from catching back up to the chain tip after a restart. That second bug — visible in [base/base PR #3805](https://github.com/base/base/pull/3805/changes) — affected only the sequencers and is why the chain halted again the following day.
## Incident timeline
### Phase 1 — the chain halt
| Time | Event | What happened |
|------|-------|---------------|
| 11:47:13 AM ET (15:47:13 UTC) | Journal left dirty | An invalid transaction fails while block 47806543 is being built, but the error path never clears the in-memory journal, so it stays dirty. |
| 11:47:13 AM ET (15:47:13 UTC) | Execution on bad state | In that same ~2-second window, the next valid transaction runs against the dirty journal and computes a wrong receipts root. The bad block is then sealed and broadcast by the sequencer. |
| 11:47:13 AM ET (15:47:13 UTC) | Validators reject, chain halts | Validators re-execute the block. Because they skip the excluded invalid transaction, they derive a different receipts root from a clean journal, reject the block, and the chain stops at block 47806542. |
### Phase 2 — response and triage
| Time | Milestone | Action |
|------|-----------|--------|
| 11:49:00 AM ET (15:49:00 UTC) | T + 2 minutes | Monitors detect the production stall and fire an automated alert. |
| 11:52:00 AM ET (15:52:00 UTC) | T + 5 minutes | An engineering war room opens; within three minutes of the alert the bad block hash is identified. |
| 11:53:00 AM ET (15:53:00 UTC) | T + 6 minutes | The public status page is updated. |
### Phase 3 — mitigation and recovery
| Time | Status | Steps |
|------|--------|-------|
| 12:24 PM ET (16:24 UTC) | Investigating | Teams work multiple parallel tracks to isolate the cause. |
| 12:55 PM ET (16:55 UTC) | Root cause found | The cause is confirmed and the invalid block pinpointed; fix implementation and testing begin. |
| 1:20 PM ET (17:20 UTC) | Internal nodes recover | The EVM journal patch reaches internal sequencers and core nodes, which achieve preliminary recovery. |
| 1:51 PM ET (17:51 UTC) | Blocks resume | New blocks start sealing again; downstream ecosystem operators are told to restart stalled nodes. Total outage ~116 minutes. |
| 1:58 PM ET (17:58 UTC) | Network stable | Ecosystem-wide syncing is verified and the network holds stable under active monitoring. |
The June 26 halt shared the same root cause, started at 11:28am EDT, and was resolved in roughly 20 minutes.
## Follow-up work
Base outlined several reliability investments coming out of the incident:
- Stronger protocol fuzz testing and load-testing harnesses, aimed at surfacing adversarial transaction patterns that can trigger bugs like the journal-state defect, alongside broader operational and monitoring improvements.
- Graceful recovery support in `base-consensus`, since this incident required validator nodes to be restarted before they could resume syncing. The goal is faster, lower-effort recovery across the ecosystem in similar situations.
Node operators and integrators can subscribe to updates at [status.base.org](https://status.base.org) to stay informed about future events.
---
# Multiproofs on Base
Source: https://basehub.org/architecture/multiproofs/
Description: How Base's multiproof system combines TEE and ZK provers to enable fast finality, satisfy Stage 2 decentralization requirements, and strengthen the proof system's security posture.
The multiproof system on Base mainnet pairs a TEE prover with a ZK prover to validate state transitions, shortening withdrawal finality to at most one day when both proofs agree, and giving the chain the onchain bug-detection capability required for Stage 2 decentralization. ZK proofs can override TEE proofs, and contradictions across provers raise a soundness alert that disables the affected prover automatically.
## Why move beyond optimistic proofs
Base reached Stage 1 in October 2024 with permissionless fault proofs and again in April 2025 with the Security Council that approves upgrades. The fault dispute protocol behind those milestones works, but is interactive (a dispute can span dozens of transactions), demands a smart contract that emulates a virtual machine, and requires defenders to lock up hundreds of ETH in bonds in the worst case. Those costs make optimistic systems an awkward foundation for the next stage of decentralization.
Validity systems flip the model: every block in a proposal is proved correct upfront and verified onchain in a single transaction, eliminating the multi-round dispute game and the bond requirements. Two flavors lead the field:
- **ZK provers** use cryptography to attest that the chain advanced correctly. Real-time proving is expensive today, and the offchain machinery is hard to implement soundly, but the trust model is the cleanest available.
- **TEE provers** lean on hardware attestation. They are fast and cheap to verify, but introduce trust in the hardware vendor (Intel, AWS) and remain susceptible to side-channel attacks on physical TEEs.
## The multiproof design
Following Vitalik's L2 finalization roadmap, Base finalizes a proposal as soon as either a TEE or ZK proof is present. When both are present and agree, the proposal finalizes quickly — within a day at most. A ZK proof can overrule a TEE proof, and any contradiction between proofs (for example, two ZK proofs disagreeing on the same block) triggers a soundness alert that pauses the implicated prover.
That layout buys three things at once:
- **Faster withdrawals** when both provers are active, improving liquidity efficiency across bridges.
- **Permissionless decentralization**, because ZK proposing remains open and the permissionless path always overrides the permissioned one.
- **Stage 2 readiness**, since prover bugs become detectable onchain rather than relying on offchain coordination.
Base treats TEE proofs as the near-term workhorse while confidence in the ZK stack matures. The current ZK prover is SP1, chosen for performance, audit coverage, and ongoing formal verification work.
## Defense in depth: intermediary roots and soundness alerts
To keep defender requirements low, the proof system embeds **intermediary roots** — subclaims published every few blocks within a proposal. Contradicting a single subclaim is enough to invalidate the whole proposal and surface a soundness alert. A defender no longer needs to disprove an entire proposal to flag a faulty prover; one disagreeing block is sufficient.
Soundness alerts are the system's circuit breaker. When two proofs disagree on the same block, the implicated prover is disabled automatically until reviewed, preserving the assurance that any finalized proposal was vouched for by at least one honest prover.
## Where this goes next
The endpoint is full ZK proving with near-instant withdrawals. Reaching that state depends on two parallel tracks:
- **Improving ZK security and efficiency**, including chain-side changes that make real-time proving tractable and ongoing evaluation of competing ZKVMs.
- **Shortening finality**, from the current one-day window down toward a few minutes as confidence in ZK provers grows.
The multiproof launch on mainnet is the architectural step that satisfies Stage 2's technical requirement for onchain bug detection while leaving room for the chain to keep tightening finality as the underlying proving technology matures.
---
# Native Account Abstraction
Source: https://basehub.org/architecture/native-account-abstraction/
Description: How Base brings account abstraction into the protocol itself via EIP-8130, cutting per-transaction cost over the ERC-4337 smart-account model while keeping accounts portable across EVM chains.
import { Aside } from '@astrojs/starlight/components';
Native Account Abstraction folds the capabilities of smart accounts directly into the chain through **EIP-8130**, rather than layering them on top of the EVM the way **ERC-4337** did. Base is building it alongside Optimism, Coinbase, and WalletConnect, with the rest of the OP Stack to follow. Because the transaction type is co-designed with the protocol instead of bolted on, Base reports it can more than halve the per-transaction cost users paid under ERC-4337 without giving up any of the chain's scaling targets.
## Why move account abstraction into the protocol
Smart accounts have carried much of the UX progress in crypto over the past few years — gas abstraction, batched actions, and flexible key management all became possible. But the ERC-4337 design that delivered them sits above the EVM, and that placement carries a tax: higher gas, added latency, and more moving parts. Native AA removes that overhead by making these behaviors first-class properties of a chain-level transaction type.
Co-designing **EIP-8130** with the surrounding protocol let Base keep the transaction opinionated and easy to optimize. The savings show up directly in gas and calldata:
| Transaction type | ERC-4337 | Native AA |
| --- | --- | --- |
| USDC Transfer | 125,000 gas / 1,090 bytes | 46,000 gas (-63.2%) / 180 bytes (-83.4%) |
| USDC Transfer (Passkey, Sponsored) | 173,000 gas / 1,940 bytes | 68,700 gas (-60.3%) / 890 bytes (-56.1%) |
## What becomes native to the chain
With EIP-8130, the following capabilities are provided by the chain itself rather than by contract-level machinery:
- **Batch calls** — bundle several actions into one transaction.
- **Sponsorship** — an application can cover its users' gas, or let them pay in a token of their choice.
- **Portability** — the same account travels to any chain, including ones that have not yet adopted Native AA.
- **Quantum readiness** — support for key rotation and multiple authentication schemes leaves room to move to post-quantum authentication.
- **High throughput** — parallel nonces and generous sender limits allow a high degree of concurrency.
- **Session keys** — an application can act for you within bounded, revocable permissions.
- **Sub-accounts** — a fully isolated account you own that an application can operate.
- **Metadata** — attach memos and attribution to transactions.
A key point of the design is that adopting Native AA on Base does not tie an account to Base — accounts remain usable on other EVM chains regardless of whether those chains support the feature yet.
## How EIP-8130 works
Every 8130 transaction identifies the account it is sent from, demonstrates that whoever submitted it is permitted to act on that account's behalf, and bundles a group of calls to execute together. The whole model reduces to five pieces:
- **Account.** Addresses are deterministic — a client derives them locally with `CREATE2`, so an account address exists before any code is deployed and its creation can ride along inside the first transaction it sends. Each account is a thin proxy that routes its calls into a shared implementation contract; `DefaultAccount` is the minimal version and also backs EOAs upgraded through EIP-7702. A variant tuned for high transaction rates locks up outbound ETH mid-execution in return for looser mempool rate-limit ceilings.
- **Signer and actor.** A *signer* is what generates the authorization attached to a transaction; the *actor* is the onchain identity that authorization maps back to, as recorded in the `AccountConfiguration` system contract. One account can authorize many actors and revoke any of them independently.
- **Scope and policy.** Every actor carries scope flags — `SCOPE_NONCE`, `SCOPE_POLICY` — that bound what it can do, and it can bind to an onchain policy setting per-token spend limits and allowed contracts/functions. This is the native session-key model: give an app an actor scoped to precisely the permissions it should have, and pull that grant back whenever you want.
- **Authenticators.** Signature checking is pluggable. An authenticator is any contract satisfying:
```solidity
interface IAuthenticator {
function authenticate(bytes32 hash, bytes calldata data) external view returns (bool);
}
```
The reference set covers secp256k1 (ordinary EVM keys), P-256, and WebAuthn, which is what puts passkey validation at the protocol level instead of behind a wrapper contract.
Base's own node is narrower than the design for now. Since late September 2026 (#5232), its txpool admits only the native k1 authenticator on the transaction path, for the sender and the payer alike, and the payload must be exactly `r || s || v` (65 bytes). A sender or payer that names P-256, WebAuthn, or the delegate authenticator is turned away at admission, so passkey-signed 8130 transactions do not currently reach a block through the Base node. Treat this as the state of an unscheduled feature, not a final scope.
- **Payer.** A transaction may name a payer to cover gas for the sender. The draft [ERC-8168](https://eip.tools/eip/8168) standardizes how apps discover and request that sponsorship.
## What an 8130 transaction carries
A transaction under this model always does three things: it names the account it acts for, it shows that the submitter is cleared to act for that account, and it carries the calls to run. Four fields do that work.
| Field | Purpose |
| --- | --- |
| `sender` | The account the transaction acts for. |
| `accountChanges` | Configuration applied before execution — creating the account included. |
| `calls` | The batch to run atomically. |
| `payer` | Optional. The account that covers gas instead of the sender. |
The set of account changes has shrunk in the node. Code delegation is `0x01` (`ACCOUNT_CHANGE_TYPE_DELEGATION`), and it is the only entry type in EIP-8430. `0x00` is reserved and never decodes. As of October 2026, account creation is `0x02` (`ACCOUNT_CHANGE_TYPE_CREATE`) and the signed config batch is `0x03` (`ACCOUNT_CHANGE_TYPE_CONFIG`). Source comments assign both to a Keystore integration that is valid only once Zenith is active. The byte values moved more than once in 2026, so encoders built against an older order decode as the wrong change type. Rebuild any 8130 tooling against the current node.
Delegation is now opt-in only. Before late September 2026 (#5255), the node pointed a sender with no code at `DEFAULT_ACCOUNT` on its own during execution and charged an `auto_delegation_cost` of 4,600 gas for it. That path is gone: a code-less sender is delegated only when the transaction carries an explicit `0x01` delegation entry, and the intrinsic gas formula no longer has an auto-delegation term. Delegation updates also stop adding a `DelegationApplied` log to the receipt, so the protocol-injected logs are now only `ActorAuthorized`, `ActorRevoked`, and `AccountCreated`. An indexer that watched for `DelegationApplied` must read delegation from the transaction's `accountChanges` instead.
Receipts need care here. Rather than collapsing to one status, an 8130 receipt reports a result for each phase, which means a transaction can come back successful at the top level while a phase inside it reverted. Check every phase before you treat a send as done. In the reference client `allPhasesSucceeded` does exactly that.
## Trying it on vibenet
EIP-8130 is experimental and, for now, only runs on the vibenet devnet (chain ID `84538453`, RPC `https://rpc.vibes.base.org`, faucet `POST https://api.vibes.base.org/api/vibenet/faucet/drip`). Client-side support currently ships in an experimental fork of viem:
```bash
bun add "viem@github:chunter-cb/viem#feat/eip-8130"
```
The `viem/experimental/eip8130` helpers let a single transaction create an account, fund it from the vibenet faucet, and send an atomic batch of calls — an 8130 receipt reports per-phase results, so a successful send still has to be checked phase by phase. The reference contracts (`AccountConfiguration`, the account implementations, and the authenticators, with Foundry tests) live at [github.com/base/eip-8130](https://github.com/base/eip-8130).
## What changes for each audience
- **Users.** A standard EOA gains access to new behaviors such as gas sponsorship and batching. In the current node that takes an explicit delegation entry, not an automatic upgrade (see above). An existing ERC-4337 smart account takes a one-time upgrade to move onto the cheaper, faster-to-include path.
- **Application developers.** Existing integrations keep working unchanged — for example, `wallet_sendCalls` continues to function against Native AA — while new capabilities like memos (for attribution), session keys, and sub-accounts become available.
- **Wallets.** No changes are required to keep working as they do today. Adding Native AA support opens new revenue paths through subscriptions and **ERC-8168** payer services.
- **Node operators.** Nothing to do yet. The transaction type now waits for [Everest](/specifications/everest-overview/), which has no date. When Everest is scheduled, upstream will publish the release that carries it. The RPC changes are listed in [Base Transactions](/specifications/base-transactions/#receipts-and-rpc).
## Testing ahead of activation
To let developers exercise EIP-8130 before it goes live, Base is introducing **Base Vibenet**, an ephemeral devnet for trying out chain-level features prior to their activation. Native AA is meant to run on any EVM chain, and Base is inviting chains, wallets, and applications to integrate it. See the original announcement at [blog.base.dev/native-account-abstraction](https://blog.base.dev/native-account-abstraction).
---
# Onchain Nitro Attestation Validation
Source: https://basehub.org/architecture/nitro-validator/
Description: How the redesigned base/nitro-validator library uses checked P-384 inverse hints to bring AWS Nitro Enclave attestation verification back under the post-Fusaka gas cap.
Ethereum's **Fusaka** upgrade priced the original `base/nitro-validator` library out of existence: **EIP-7883** raised the cost of large `MODEXP` calls and **EIP-7825** put a hard 16.7M gas ceiling on every transaction, which together pushed a single P-384 signature check past what one transaction can spend. The rebuilt library gets the work back under the cap by moving the expensive part — modular inversion — offchain, and passing the results in as calldata **hints** that the contract verifies before it uses them. The result is cheaper than the pre-Fusaka library was, and it adds no trust in whoever generated the hints.
## Why attestations belong onchain
A Trusted Execution Environment such as AWS Nitro isolates the code it runs and signs a statement covering what ran and where, tied to whatever the application cares about — an enclave public key, a nonce, or the output itself. That statement only becomes a guarantee once a contract checks it. The alternative is trusting an operator's claim about which code they ran; verification replaces the claim with a cryptographic link between the output and one particular enclave image.
Several patterns follow from that:
- **External verification** — admit state commitments, proofs, or claims from a verifier you have approved offchain.
- **Custom execution engines** — put specialized logic outside the EVM, then establish onchain that approved enclave code produced the answer.
- **Private compute** — keep scoring, matching, auctions, or policy checks sealed inside the enclave, surfacing nothing but a signed result.
- **Oracle and risk pipelines** — take updates from a data-processing environment whose measurements you can check.
- **Enclave-backed signers** — release authority to a key only once the Nitro attestation behind it verifies.
- **Bridges, settlement, and keepers** — require a signature from approved enclave code before a privileged action proceeds.
The obstacle is the curve. Nitro attestations are signed on **P-384**, which neither Base nor Ethereum L1 exposes as a precompile, so every verification pays for the elliptic-curve arithmetic in EVM bytecode.
## What Fusaka changed
Onchain Nitro verification was expensive but workable beforehand. One P-384 signature check ran about **7.9M gas**, and a full cold attestation — five signature checks plus CBOR/COSE parsing, X.509 handling, and certificate caching — landed near **53M gas** spread over several transactions.
Two Fusaka changes broke that budget:
- **EIP-7883** raised the price of large `MODEXP` calls.
- **EIP-7825** imposed a 16.7M gas ceiling per transaction.
Afterward a single unhinted P-384 verification cost roughly **50.6M gas**, which overruns the per-transaction cap on its own before anything else runs. Five of them for a full attestation comes to about **267M gas**. The library could no longer execute at all, so the fix was to change the unit of work rather than shave percentages off it.
## Where the gas goes: ~570 huge exponentiations
ECDSA verification without a precompile means doing elliptic-curve arithmetic in the contract. The verifier rebuilds a point on the curve and checks its x-coordinate against the signature. This implementation works in affine coordinates, so point addition and doubling compute slopes by finite-field division — and division needs a modular inverse:
```
a / b mod m = a · b⁻¹ mod m
```
The inverse itself comes from Fermat's Little Theorem, which means exponentiating to a 384-bit exponent:
```
b⁻¹ = b^(m − 2) mod m
```
For P-384 the modulus `m` is either the field prime `p` or the group order `n`. Both are roughly 384-bit primes on the order of 10¹¹⁵, and one signature check performs that exponentiation about **570 times**. That is the entire cost.
Inversion is asymmetric in a way the design exploits. Computing an inverse is expensive; checking a claimed one is not. Given a candidate `inv`, a single multiplication settles it:
```
b · inv == 1 mod m
```
## Checked hints
Each inverse is computed offchain and supplied in calldata. At every division the verifier pulls the next 48-byte hint and validates it before it touches the arithmetic:
```
need a / b mod m
→ read next hint inv
→ require b · inv == 1 mod m
→ use a · inv mod m
```
Nothing about a hint is taken on faith. A wrong hint reverts, a truncated stream reverts, and a stream carrying extra unused hints reverts as well. A caller can burn their own gas on a bad submission, but cannot push the verifier into accepting a signature it would otherwise turn down.
Primality is what makes the substitution exact. The two P-384 moduli in play — group order `n` and field prime `p` — are both prime, which means no nonzero element of the field has more than one inverse. A hint that clears `b · inv == 1 mod m` is thus necessarily identical to what `b^(m − 2)` would have yielded. The route to the inverse changes; the set of signatures that verify does not.
Three contracts split the work:
- **`P384Verifier`** owns the hint checks and the ECDSA-P-384 arithmetic. An external call separates it from the rest, which keeps both other contracts under the **EIP-170** size limit.
- **`CertManager`** measures X.509 certificates against a pinned AWS Nitro root, sends every non-root signature to `P384Verifier`, retains metadata for certificates it has already cleared, and honors revocation.
- **`NitroValidator`** reads the COSE/CBOR attestation document, runs its certificate bundle through `CertManager`, and settles the attestation signature against whichever leaf key is cached.
Reverting is the deliberate behavior of the unhinted entrypoints. Everything in production goes through `verifyCACertWithHints`, `verifyClientCertWithHints`, and `validateAttestationWithHints`, so the gas profile stays explicit and nothing can drift back onto the path nobody can afford.
## Cold and warm paths
Every attestation carries a leaf certificate plus the bundle behind it. Because `CertManager` pins the root CA, the root alone needs no onchain work. The cold path handles the remainder, verifying and caching one signature at a time:
- Regional CA
- Zonal CA
- Issuer / instance CA
- Leaf certificate
- COSE attestation document signature
Five P-384 checks, one per transaction. After the leaf and its chain are cached, any later attestation under that same leaf follows the warm path instead: one transaction verifies the document signature and reconfirms that the cached chain is intact — nothing missing, expired, misordered, or revoked.
## Measured gas
Five transactions cover the whole cold sequence on Base, and none of them comes close to the 16,777,216 gas cap:
| tx | Action | Hint bytes | Gas used |
| --- | --- | --- | --- |
| 1 | cache regional CA | 27,456 | 6,825,140 |
| 2 | cache zonal CA | 27,408 | 7,053,669 |
| 3 | cache issuer / instance CA | 27,408 | 6,813,103 |
| 4 | cache leaf cert | 27,504 | 6,825,004 |
| 5 | validate attestation document | 27,312 | 13,775,541 |
Each inverse takes 48 bytes. How many a verification needs varies with the signature data — somewhere between 569 and 573 — which lands every hint stream near 27 KB. Calldata is already priced into the receipt figures above.
## Security model
Hints are public proposals, not trusted witnesses — that is the property the whole design rests on. Because the contract validates each inverse before use, a wrong one cannot bend the elliptic-curve arithmetic in any direction; it can only revert. Exact hint consumption is enforced too, so a caller can neither drop a required inverse nor smuggle unused data through the stream.
The hint mechanism itself is trustless. Whether the attestation means anything still depends on trusting AWS Nitro hardware, which this design does not attempt to remove.
Policy stays with the application. What `NitroValidator` settles is narrow — the attestation traces back to a valid Nitro certificate chain — and it returns the parsed fields for the caller to judge. Which public keys, timestamps, nonces, module IDs, and PCRs are acceptable is a decision the consuming contract keeps.
## Using it
The implementation is open source in [`base/nitro-validator`](https://github.com/base/nitro-validator), and ships with:
- the hinted `P384Verifier`, `CertManager`, and `NitroValidator`;
- a reference hint generator in Node.js, with no dependencies;
- Foundry coverage for revocation, expired certificates, malformed hints, parser edge cases, valid attestations, and equivalence between offchain and onchain hint streams; and
- a Base Sepolia demo exercising the warm path as well as the cold one.
Cantina audited the library independently. The bundled JavaScript is there as a reference, not as something to depend on in your backend — calldata is the whole interface, so porting the generator to your existing stack is straightforward.
## Where this goes
After Fusaka, Base verified Nitro attestations through zero-knowledge proofs, the only practical route at the time. The hinted P-384 approach removes that dependency: no new precompile, no ZK proving service. That plan has now shipped. The [Cobalt](/specifications/cobalt-overview/) upgrade moves TEE signer registration for the proof system onto these hinted contracts, and the [registrar](/specifications/registrar/) now computes the hints itself instead of ordering a ZK proof.
Nothing here is specific to Base. The same sequence works for any EVM application on a post-Fusaka chain that needs to place trust in a Nitro enclave: walk the AWS certificate chain, check the attestation signature, read off the measurements that come back, and hold them against whatever policy you have defined.
For how Base uses Nitro Enclaves inside the proof system itself, see the [TEE prover](/specifications/tee-prover/) specification and the [multiproof](/architecture/multiproofs/) design.
---
# Architecture Overview
Source: https://basehub.org/architecture/overview/
Description: How the 8 crate groups in base/base fit together — from Reth integration to Flashblocks production.
`base/base` is a Rust workspace that implements the Base L2 node on top of [Reth](https://github.com/paradigmxyz/reth) v1.11.0. It layers Optimism rollup semantics, a Flashblocks-aware block builder, and a [Kona](https://github.com/op-rs/kona)-derived fault proof pipeline onto the Reth execution client.
The workspace is organized into **8 top-level crate groups**, each in its own subdirectory under `crates/`. These groups map to the major subsystems of an L2 node: receiving transactions, building blocks, executing the EVM, reaching consensus with L1, generating fault proofs, and operating the infrastructure that ties it all together.
## System diagram
At the highest level, the system looks like this:
```
L1 (Ethereum)
|
┌───────────────┼───────────────┐
v v v
┌─────────┐ ┌───────────┐ ┌───────────┐
│consensus│ │ proof │ │ builder │
│ (kona) │ │ (kona) │ │(flashblocks│
└────┬────┘ └───────────┘ │ + core) │
│ └─────┬─────┘
v v
┌─────────┐ ┌───────────┐
│ client │◄─────────────────►│ execution │
│(node + │ │ (EVM + │
│ engine) │ │ payload) │
└────┬────┘ └───────────┘
│
v
┌─────────┐ ┌───────────┐ ┌───────────┐
│ shared │ │ alloy │ │ infra │
│(prims, │ │ (types + │ │(binaries +│
│ utils) │ │ codecs) │ │ tooling) │
└─────────┘ └───────────┘ └───────────┘
```
## Crate groups
### 1. Client — the node core
**Path:** [`crates/client/`](https://github.com/base/base/tree/main/crates/client)
The client group contains the node implementation itself. It is the entry point for the `base-reth-node` binary and assembles all the other subsystems into a running process.
| Crate | Purpose |
|---|---|
| `base-client-node` | Node configuration, component wiring, Reth `NodeBuilder` integration |
| `base-client-cli` | CLI argument parsing and subcommand definitions |
| `base-client-engine` | Engine API handler — receives payloads from the consensus layer and drives execution |
| `base-flashblocks` | Flashblocks state management, WebSocket streaming, sub-block interval logic |
| `base-metering` | Gas metering extensions and RPC metering endpoints |
| `base-txpool-tracing` | Transaction pool event tracing and diagnostics |
The client group depends on nearly every other group. It pulls primitives from **shared**, types from **alloy**, EVM logic from **execution**, and consensus derivation from **consensus**.
### 2. Execution — EVM and payload construction
**Path:** [`crates/execution/`](https://github.com/base/base/tree/main/crates/execution)
This group wraps Reth's EVM execution with Base-specific customizations. It is responsible for:
- Configuring the `EvmConfig` with Optimism-specific precompiles and fee logic
- Building execution payloads (the block body that the engine seals)
- Applying L1-to-L2 deposit transactions that arrive via the derivation pipeline
Reth's modular `EvmConfig` trait allows Base to inject its own gas pricing rules (L1 data fee), custom precompiles, and Optimism system transaction handling without forking the core EVM loop.
### 3. Consensus — L1 derivation
**Path:** [`crates/consensus/`](https://github.com/base/base/tree/main/crates/consensus)
Consensus is split into two sub-groups:
**Base-native crates:**
| Crate | Purpose |
|---|---|
| `base-protocol` | Protocol constants, chain config, fork schedule |
| `base-consensus-rpc` | RPC interface for consensus queries |
**Kona-derived crates** (forked/vendored from the [Kona](https://github.com/op-rs/kona) project):
| Crate | Purpose |
|---|---|
| `kona-node-service` | Top-level consensus node service |
| `kona-engine` | Engine driver — sends `engine_forkchoiceUpdated` / `engine_newPayload` calls |
| `kona-derive` | L1 derivation pipeline — reads batches from L1, produces L2 payload attributes |
| `kona-gossip` | P2P gossip protocol for unsafe block propagation |
| `kona-sources` | Data source adapters (L1 RPC, blobs, DA) |
| `kona-providers-alloy` | Alloy-based provider implementations for L1/L2 data |
| `kona-genesis` | Genesis state and rollup config loading |
| `kona-registry` | Chain registry (rollup configs for known chains) |
| `kona-hardforks` | Hardfork activation logic |
| `kona-disc` | Peer discovery |
| `kona-peers` | Peer management and scoring |
| `kona-cli` | CLI utilities for consensus binaries |
| `kona-macros` | Procedural macros used across kona crates |
The derivation pipeline reads L1 blocks, extracts batch data (from calldata or EIP-4844 blobs), and derives the sequence of L2 blocks that the execution layer must process. This is the mechanism by which Base inherits Ethereum's security.
### 4. Builder — block construction and Flashblocks
**Path:** [`crates/builder/`](https://github.com/base/base/tree/main/crates/builder)
The builder group implements Base's custom block builder, which goes beyond standard Reth payload building by producing **Flashblocks** -- partial block updates streamed every 200 milliseconds.
| Crate | Purpose |
|---|---|
| `base-builder-core` | Core block building loop, transaction ordering, Flashblock interval timer |
| `base-builder-publish` | Publishing built blocks/flashblocks to consumers (WebSocket, engine) |
| `base-builder-metering` | Builder-specific metrics (build times, transaction counts, revenue) |
The builder runs as a separate binary (`builder`) and communicates with the node via the Engine API. See [Flashblocks Pipeline](/architecture/flashblocks-pipeline/) for a detailed walkthrough.
### 5. Proof — fault proof generation
**Path:** [`crates/proof/`](https://github.com/base/base/tree/main/crates/proof)
The proof group contains the machinery for generating fault proofs that can be verified on L1. These crates are also derived from Kona and target execution inside a fault proof virtual machine (FPVM).
| Crate | Purpose |
|---|---|
| `kona-proof` | Top-level proof orchestration |
| `kona-driver` | Drives the derivation + execution pipeline inside the FPVM |
| `kona-executor` | EVM executor adapted for the proof environment |
| `kona-mpt` | Merkle Patricia Trie operations for state proof verification |
| `kona-preimage` | Preimage oracle client — requests data from the host during proof execution |
| `kona-std-fpvm` | Standard FPVM runtime (syscall interface, memory management) |
| `kona-std-fpvm-proc` | Procedural macros for FPVM entry points |
In a fault proof, the entire derivation-then-execution pipeline runs deterministically inside a sandboxed VM. The `kona-driver` crate replays the same logic as the consensus layer's derivation pipeline, but reads data through a preimage oracle rather than from the network.
### 6. Shared — common types and utilities
**Path:** [`crates/shared/`](https://github.com/base/base/tree/main/crates/shared)
Shared crates provide types, utilities, and abstractions used across multiple other groups.
| Crate | Purpose |
|---|---|
| `base-primitives` | Core types: `BaseTxEnvelope`, `BaseBlock`, chain IDs, fee types |
| `base-bundles` | Bundle types for MEV/searcher bundle submission |
| `base-jwt` | JWT authentication for Engine API and inter-service communication |
| `base-cli-utils` | Common CLI argument types and parsing helpers |
| `base-engine-ext` | Engine API extensions (additional methods beyond the standard spec) |
| `base-access-lists` | Access list generation and optimization |
| `base-reth-rpc-types` | Custom RPC type definitions |
| `base-txpool-rpc` | Transaction pool RPC method types |
`base-primitives` is the most widely depended-upon crate in the workspace. It defines the canonical transaction, block, and receipt types that every other group imports.
### 7. Alloy — type system and codecs
**Path:** [`crates/alloy/`](https://github.com/base/base/tree/main/crates/alloy)
The alloy group provides Ethereum/Optimism type definitions and encoding/decoding logic built on the [Alloy](https://github.com/alloy-rs/alloy) library ecosystem. These crates define the wire format for transactions, receipts, and other protocol objects, ensuring compatibility with the broader Ethereum tooling ecosystem.
### 8. Infra — binaries and operational tooling
**Path:** [`crates/infra/`](https://github.com/base/base/tree/main/crates/infra)
The infra group contains the supporting binaries and tooling that run alongside the core node.
| Crate/Binary | Purpose |
|---|---|
| `based` | Sequencer orchestrator daemon |
| `basectl-cli` | Operator CLI tool for node management and diagnostics |
| `ingress-rpc-lib` | RPC ingress proxy — retired 2026-09-21, last shipped in `v1.4.0` |
| `websocket-proxy` | WebSocket proxy for Flashblocks streaming |
| `mempool-rebroadcaster` | Rebroadcasts mempool transactions to peers |
| `audit-archiver-lib` | Archives audit logs for compliance and debugging |
| `system-tests` | End-to-end integration test harness |
## Reth integration
Base does not fork Reth. Instead, it uses Reth as a library dependency and extends it through Reth's plugin architecture:
1. **`NodeBuilder`** — the client group uses Reth's `NodeBuilder` to assemble a node with custom components (EVM config, transaction pool, payload builder).
2. **`EvmConfig`** — the execution group provides an Optimism-aware EVM configuration that plugs into Reth's execution pipeline.
3. **`PayloadBuilder`** — the builder group implements a custom payload builder that produces Flashblocks.
4. **`EngineApi`** — the client engine crate extends the standard Engine API with additional methods for Flashblocks and metering.
This library-based integration means Base automatically picks up upstream Reth improvements (perf optimizations, new EVM opcodes, database improvements) by updating the Reth dependency version.
## Optimism component usage
Base is an OP Stack chain, and the codebase relies on several Optimism-specific components:
- **`reth-optimism-*` crates** — Reth ships first-party Optimism support. Base uses these for deposit transaction handling, L1 fee calculation, and the Optimism-specific Engine API extensions (`op-engine-api`).
- **Kona** — the consensus and proof groups are built on Kona, the Rust implementation of the OP Stack's derivation pipeline and fault proof program. Base vendors these crates to apply Base-specific patches (e.g., Flashblocks-aware derivation).
- **Alloy Optimism types** — the alloy group extends Alloy's Optimism type definitions with Base-specific transaction types and receipt fields.
## Build toolchain
The workspace uses:
- **Rust edition 2024** with a minimum supported Rust version of **1.88**
- **MIT license** for all crates
- **Just** as the task runner (see `justfile` at the repo root)
- **Docker** for containerized builds and deployments
---
# Protocol Overview
Source: https://basehub.org/architecture/protocol-overview/
Description: A tour of the Base rollup protocol — the network participants, the consensus, execution, bridging, batcher, and proof components, and the deposit, transaction, and withdrawal flows that connect L1 and L2.
Base is an Ethereum rollup: L2 transaction data is published to Ethereum so anyone can reconstruct the chain, and proofs let any participant challenge an invalid state transition. This page walks through the protocol-level pieces and the user flows that tie L1 and L2 together. For the codebase-level view of how these subsystems map to Rust crates, see [Architecture Overview](/architecture/overview/).
## Design Goals
Four principles shape the protocol specification. They account for a number of choices that would otherwise look arbitrary.
- **Opinionated** — Where several designs would each work, the spec picks one and commits to it. Simplicity here is a product of refusing to keep options open.
- **Maximally Simple** — Scope stays limited to what Base itself needs, which strips a great deal of generality out of the stack. The target is a spec and a codebase that one developer can hold in their head.
- **Fast Cycles** — Risk gets spread across many small upgrades rather than concentrated into a few large ones. The plan is six tightly scoped hard forks a year on a regular cadence, with releases landing fortnightly.
- **Ethereum Aligned** — Base treats Ethereum's success as its own. High-impact changes ship here ahead of L1, and the production data that comes back feeds into Ethereum's own roadmap.
## Lineage
Base Chain takes its EVM semantics from Ethereum, along with Ethereum's rules for transactions and its security model anchored on L1. The chain was first built on the [OP Stack](https://specs.optimism.io). From the Jovian Hardfork onward it follows this specification instead.
## Network Participants
Three kinds of actors interact with Base: users, sequencers, and validators.
```mermaid
graph TD
EthereumL1(Ethereum L1)
subgraph "L2 Participants"
Users(Users)
Sequencers(Sequencers)
Validators(Validators)
end
Validators -.->|fetch transaction batches| EthereumL1
Validators -.->|fetch deposit data| EthereumL1
Validators -->|submit/validate/challenge output proposals| EthereumL1
Validators -.->|fetch realtime P2P updates| Sequencers
Users -->|submit deposits/withdrawals| EthereumL1
Users -->|submit transactions| Sequencers
Users -->|query data| Validators
Sequencers -->|submit transaction batches| EthereumL1
Sequencers -.->|fetch deposit data| EthereumL1
classDef l1Contracts stroke:#bbf,stroke-width:2px;
classDef l2Components stroke:#333,stroke-width:2px;
classDef systemUser stroke:#f9a,stroke-width:2px;
class EthereumL1 l1Contracts;
class Users,Sequencers,Validators l2Components;
```
### Users
Users are the broad set of participants who send transactions — either through the sequencer or by calling contracts directly on Ethereum — and who read transaction data back from the interfaces that validators expose.
### Sequencers
The sequencer is Base's block producer. The network runs a single active sequencer today, and it:
- Accepts transactions directly from Users.
- Observes "deposit" transactions generated on Ethereum.
- Consolidates both transaction streams into ordered L2 blocks.
- Submits information to L1 that is sufficient to fully reproduce those L2 blocks.
- Provides real-time access to pending L2 blocks that have not yet been confirmed on L1.
- Produces Flashblocks every 200ms, committing to the ordering of transactions within the block as it is being built.
Although it is central to how the chain runs, the sequencer is not a trusted party. Its job is to improve the experience — ordering transactions far faster and more cheaply than would be possible if every user submitted directly to L1 — not to be relied upon for correctness.
### Validators
Validators run the L2 state transition function for themselves, independently of the sequencer. By doing so they keep the network honest and serve chain data back to users. In general they:
- Sync rollup data from L1 and the Sequencer.
- Use rollup data to execute the L2 state transition function.
- Serve rollup data and computed L2 state information to Users.
A validator can additionally take on the Proposer and/or Challenger role, which means it will:
- Submit assertions about the state of the L2 to a smart contract on L1.
- Validate assertions made by other participants.
- Dispute invalid assertions made by other participants.
## High-Level System Diagram
The diagram below traces how the main components talk to each other across L1 and L2.
```mermaid
graph LR
subgraph "Ethereum L1"
OptimismPortal(OptimismPortal)
BatchInbox(Batch Inbox Address)
DisputeGameFactory(DisputeGameFactory)
end
subgraph "L2 Node"
RollupNode(Consensus)
ExecutionEngine(Execution Engine)
end
Batcher(Batcher)
Proposers(Proposers)
Challengers(Challengers)
Users(Users)
Users -->|deposits / withdrawals| OptimismPortal
Users -->|transactions| ExecutionEngine
Batcher -->|post transaction batches| BatchInbox
Batcher -.->|fetch batch data| RollupNode
RollupNode -.->|fetch batches| BatchInbox
RollupNode -.->|fetch deposit events| OptimismPortal
RollupNode -->|Engine API| ExecutionEngine
Proposers -->|submit output proposals| DisputeGameFactory
Proposers -.->|fetch outputs| RollupNode
Challengers -->|verify / challenge games| DisputeGameFactory
OptimismPortal -.->|query state proposals| DisputeGameFactory
classDef l1Contracts stroke:#bbf,stroke-width:2px;
classDef l2Components stroke:#333,stroke-width:2px;
classDef systemUser stroke:#f9a,stroke-width:2px;
class OptimismPortal,BatchInbox,DisputeGameFactory l1Contracts;
class RollupNode,ExecutionEngine l2Components;
class Batcher,Proposers,Challengers,Users systemUser;
```
## Protocol Components
### Consensus
The consensus layer derives the canonical L2 chain from L1 data. It pulls transaction batches out of the Batch Inbox and deposit events out of `OptimismPortal`, assembles payload attributes from them, and drives the execution engine through the Engine API. Newly built but still-unconfirmed blocks are gossiped to peers over a dedicated P2P network, so validators see them with low latency well before the corresponding batches reach L1.
```mermaid
graph LR
L1(Ethereum L1)
subgraph "Rollup Node"
BatchDecoding(Batch Decoding)
Derivation(Derivation Pipeline)
end
EngineAPI(Engine API)
EE(Execution Engine)
L2(L2 Blocks)
L1 -->|batches + deposit events| BatchDecoding
BatchDecoding --> Derivation
Derivation -->|payload attributes| EngineAPI
EngineAPI --> EE
EE --> L2
classDef l1 stroke:#bbf,stroke-width:2px;
classDef l2 stroke:#333,stroke-width:2px;
class L1 l1;
class EE,L2 l2;
```
### Execution
Execution runs on a Reth-based engine that speaks the standard Ethereum JSON-RPC API and processes the blocks consensus hands it. Predeploys (system contracts living at fixed L2 addresses), precompiles, and preinstalls extend the EVM with the rollup-specific behavior it needs — fee distribution, L1 block attribute injection, and cross-domain messaging among them.
### Bridging
Deposits move from the `OptimismPortal` contract on L1 into L2 as special deposit transactions placed at the top of each L2 block. Withdrawals run the other way: a user starts a withdrawal transaction on L2, a proposer files an output root with `DisputeGameFactory`, and once the challenge period elapses the user proves and finalizes the withdrawal back on L1 through `OptimismPortal`.
```mermaid
graph LR
subgraph "Deposit Path"
User1(User)
OP1(OptimismPortal)
DepTx(Deposit Transaction on L2)
end
subgraph "Withdrawal Path"
User2(User)
WdTx(Withdrawal Tx on L2)
DGF(DisputeGameFactory)
OP2(OptimismPortal)
end
User1 -->|depositTransaction| OP1
OP1 -->|TransactionDeposited event| DepTx
User2 -->|initiates withdrawal| WdTx
WdTx -->|output root proposed| DGF
User2 -->|prove + finalize| OP2
OP2 -.->|verify game| DGF
classDef l1 stroke:#bbf,stroke-width:2px;
classDef systemUser stroke:#f9a,stroke-width:2px;
class OP1,OP2,DGF l1;
class User1,User2 systemUser;
```
### Batcher
The batcher is a sequencer-operated service that compresses L2 transaction data into channel frames and posts them — as calldata or blobs — to the Batch Inbox Address on L1. This is the data availability layer: with it, any validator can rebuild the full L2 chain from L1 alone.
```mermaid
graph LR
Sequencer(Sequencer)
Batcher(Batcher)
BatchInbox(Batch Inbox Address)
RollupNode(Rollup Node)
Sequencer -->|L2 blocks| Batcher
Batcher -->|compressed channel frames| BatchInbox
BatchInbox -.->|fetch batches| RollupNode
classDef l1 stroke:#bbf,stroke-width:2px;
classDef l2 stroke:#333,stroke-width:2px;
classDef systemUser stroke:#f9a,stroke-width:2px;
class BatchInbox l1;
class RollupNode l2;
class Batcher,Sequencer systemUser;
```
### Proofs
Output proposals and the proofs behind them are what make the L2 state verifiable. A proposer opens a checkpoint game through `DisputeGameFactory`, the onchain verifier contracts check the proof material, and challengers can dispute any claim they believe is wrong. A withdrawal can only be finalized through `OptimismPortal` after the game backing it resolves in the proposer's favor. The current proof topology is the Azul multiproof design — see [Azul Proof System](/specifications/azul-proofs/) for the dispute-game and finality details.
```mermaid
graph LR
Proposer(Proposer)
DGF(DisputeGameFactory)
Game(AggregateVerifier game)
Challengers(Challengers)
OP(OptimismPortal)
Proposer -->|submit checkpoint proof| DGF
DGF -->|create game| Game
Challengers -->|challenge invalid claims| Game
Game -->|resolved result| OP
classDef l1 stroke:#bbf,stroke-width:2px;
classDef systemUser stroke:#f9a,stroke-width:2px;
class DGF,Game,OP l1;
class Proposer,Challengers systemUser;
```
## Core User Flows
### Depositing ETH to Base
Most users arrive on L2 by bridging ETH over from L1; once they hold ETH for fees, they begin transacting on Base. The flow below shows that first hop and the components it touches.
```mermaid
graph TD
subgraph "Ethereum L1"
OptimismPortal(OptimismPortal)
BatchInbox(Batch Inbox Address)
end
Sequencer(Sequencer)
Users(Users)
%% Interactions
Users -->|1. submit deposit| OptimismPortal
Sequencer -.->|2. fetch deposit events| OptimismPortal
Sequencer -->|3. generate deposit block| Sequencer
Users -->|4. send transactions| Sequencer
Sequencer -->|5. submit transaction batches| BatchInbox
classDef l1Contracts stroke:#bbf,stroke-width:2px;
classDef l2Components stroke:#333,stroke-width:2px;
classDef systemUser stroke:#f9a,stroke-width:2px;
class OptimismPortal,BatchInbox l1Contracts;
class Sequencer l2Components;
class Users systemUser;
```
### Sending Transactions on Base
Transacting on Base is identical to transacting on Ethereum: a user signs a transaction and submits it via `eth_sendRawTransaction` to any node's JSON-RPC endpoint. The sequencer takes it from the mempool, slots it into an L2 block, and eventually posts the containing batch to L1.
### Withdrawing from Base
Moving ETH or ERC-20 tokens from Base back to Ethereum starts as an ordinary L2 transaction but finishes with transactions on L1. A withdrawal has to reference a valid proof game that asserts the L2 state at a particular point, and only completes once that game has finalized.
```mermaid
graph LR
subgraph "Ethereum L1"
BatchInbox(Batch Inbox Address)
DisputeGameFactory(DisputeGameFactory)
ProofGame(AggregateVerifier game)
OptimismPortal(OptimismPortal)
ExternalContracts(External Contracts)
end
Sequencer(Sequencer)
Proposers(Proposers)
Users(Users)
%% Interactions
Users -->|1. send withdrawal initialization txn| Sequencer
Sequencer -->|2. submit transaction batch| BatchInbox
Proposers -->|3. submit output proposal| DisputeGameFactory
DisputeGameFactory -->|4. generate game| ProofGame
Users -->|5. submit withdrawal proof| OptimismPortal
Users -->|6. wait for finalization| ProofGame
Users -->|7. submit withdrawal finalization| OptimismPortal
OptimismPortal -->|8. check game validity| ProofGame
OptimismPortal -->|9. execute withdrawal transaction| ExternalContracts
%% Styling
classDef l1Contracts stroke:#bbf,stroke-width:2px;
classDef l2Components stroke:#333,stroke-width:2px;
classDef systemUser stroke:#f9a,stroke-width:2px;
class BatchInbox,DisputeGameFactory,ProofGame,OptimismPortal l1Contracts;
class Sequencer l2Components;
class Users,Proposers systemUser;
```
---
# audit-archiver
Source: https://basehub.org/binaries/audit-archiver/
Description: Kafka-to-S3 audit log archival service with configurable worker pools.
import { LinkCard } from '@astrojs/starlight/components';
`audit-archiver` archives audit log messages to S3-compatible storage for long-term retention, debugging, and compliance. Its Kafka producer used to be `ingress-rpc`, which was removed from `base/base` on 2026-09-21; the archiver itself stayed, and it still ingests transaction events over HTTP from Vector.
## Package
- **Crate name:** `audit-archiver`
- **Source:** [`bin/audit-archiver`](https://github.com/base/base/tree/main/bin/audit-archiver)
- **Library:** [`crates/infra/audit`](https://github.com/base/base/tree/main/crates/infra/audit) (`audit-archiver-lib`)
## Architecture
The archiver runs a configurable pool of workers that consume messages from Kafka topics and write them in batches to S3:
```
Kafka topics → audit-archiver (worker pool) → S3 bucket
```
The service supports a `noop-archive` mode for testing where messages are consumed and logged but not written to S3.
## Features
| Feature | Description |
|---------|-------------|
| **Worker pool** | Configurable pool of up to 80 concurrent workers |
| **S3 archival** | Writes audit logs to S3-compatible object storage |
| **Noop mode** | `noop-archive` mode for testing without S3 writes |
| **Metrics** | Exposes Prometheus metrics on port 9002 |
| **Batch processing** | Groups messages into batches for efficient writes |
## Ports
| Port | Protocol | Purpose |
|------|----------|---------|
| 9002 | HTTP | Prometheus metrics |
## Key Dependencies
- `audit-archiver-lib` — Core archival logic
- `rdkafka` — Kafka consumer
- `aws-sdk-s3` — S3 client
- `tokio` — Async runtime
## Build
```bash
cargo build --bin audit-archiver --release
```
## Usage
```bash
./target/release/audit-archiver [OPTIONS]
```
## Source
---
# base-reth-node
Source: https://basehub.org/binaries/base-reth-node/
Description: The main Base Reth Node binary — a Reth-based Ethereum execution client for the Base L2 network.
import { LinkCard } from '@astrojs/starlight/components';
`base-reth-node` runs the Base L2 execution client. It extends the standard Reth OP node with five extensions covering Flashblocks streaming, transaction pool RPC, resource metering, and proofs history retention.
## Package
- **Crate name:** `base-reth-node`
- **Source:** [`bin/node`](https://github.com/base/base/tree/main/bin/node)
- **Dockerfile:** `etc/docker/Dockerfile.client`
## Extensions
The node binary installs five extensions on top of the standard Reth OP node:
| Extension | Crate | Purpose |
|-----------|-------|---------|
| `TxPoolRpcExtension` | `base-txpool-rpc` | Exposes custom transaction pool RPC methods |
| `TxPoolExtension` | `base-txpool-tracing` | Adds transaction pool tracing and diagnostics |
| `MeteringExtension` | `base-metering` | Resource metering RPC for gas accounting |
| `FlashblocksExtension` | `base-flashblocks` | Flashblocks streaming provider over WebSocket |
| `ProofsHistoryExtension` | `base-proofs-history` | Retains trie proofs for the fault proof window |
These extensions are registered via Reth's `NodeComponents` system. Each one hooks into the node lifecycle to provide additional RPC methods or background services.
## Key Dependencies
- `reth-optimism-node` — Base Reth node builder
- `reth-optimism-cli` — CLI framework with jemalloc and OTel
- `base-flashblocks` — Flashblocks RPC provider
- `base-metering` — Resource metering RPC
- `base-txpool-rpc` — Transaction pool RPC extensions
- `base-txpool-tracing` — Transaction pool tracing
- `base-proofs-history` — Proofs history extension
- `base-cli-utils` — CLI utilities (logging, metrics)
## Build
```bash
# Build just this binary
just build node
# Or using cargo directly
cargo build --bin base-reth-node
# Release build
cargo build --release --bin base-reth-node
```
`just build node` is a debug build — it wraps the plain `cargo build --bin base-reth-node` above. Pass `--release` when you want the optimized binary. That covers local use. The published binary archives are compiled with `maxperf` instead, a heavier variant of `release` that Base applies only to release artifacts.
## Usage
```bash
./target/release/base-reth-node node \
--chain base \
--datadir /data/base \
--http \
--http.api eth,net,web3,debug,txpool \
--ws \
--ws.api eth,net,web3
```
View all available options:
```bash
./target/release/base-reth-node --help
```
## Docker
```bash
# Build the image
docker build -t base-reth-node -f etc/docker/Dockerfile.client .
# Run
docker run -it --rm \
-v /data/base:/data \
-p 8545:8545 \
-p 8546:8546 \
base-reth-node node --chain base --datadir /data
```
## Source
---
# basectl
Source: https://basehub.org/binaries/basectl/
Description: TUI management utility for configuring and inspecting Base nodes across different network targets.
import { LinkCard } from '@astrojs/starlight/components';
`basectl` is the operator TUI for configuring and inspecting Base nodes across multiple network targets. The interface is built with [`ratatui`](https://github.com/ratatui/ratatui).
## Package
- **Crate name:** `basectl`
- **Source:** [`bin/basectl`](https://github.com/base/base/tree/main/bin/basectl)
- **Library:** [`crates/infra/basectl`](https://github.com/base/base/tree/main/crates/infra/basectl) (`basectl-cli`)
## Architecture
`basectl` is split into two crates:
- **`basectl`** (binary) — The CLI entry point that parses arguments and launches the TUI
- **`basectl-cli`** (library) — The core logic for configuration management, subcommands, and the TUI renderer
The TUI is built with [`ratatui`](https://github.com/ratatui/ratatui), providing an interactive terminal interface for node management.
## Subcommands
| Subcommand | Purpose |
|------------|---------|
| `config` | Generate or inspect node configuration for a target network |
| `flashblocks` | Inspect and manage flashblocks streaming state |
| `da` | Data availability layer inspection and diagnostics |
| `command-center` | Interactive TUI dashboard for monitoring and managing the node |
## Configuration Targets
| Config | Network |
|--------|---------|
| `mainnet` | Base Mainnet |
| `sepolia` | Base Sepolia Testnet |
| `devnet` | Local Development Network |
| `` | Custom configuration file path |
## Key Dependencies
- `basectl-cli` — Configuration logic library
- `ratatui` — TUI framework
- `clap` — CLI argument parsing
- `anyhow` — Error handling
- `tokio` — Async runtime
## Usage
```bash
# Via cargo
cargo run -p basectl --release -- -c
# Via Just (preferred)
just basectl mainnet
just basectl sepolia
just basectl devnet
```
## Source
---
# based
Source: https://basehub.org/binaries/based/
Description: Block-building sidecar service with health checks and StatsD metrics.
import { LinkCard } from '@astrojs/starlight/components';
`based` runs as a sidecar to the block builder, exposing HTTP health check endpoints and forwarding metrics over StatsD to Datadog or compatible backends.
## Package
- **Crate name:** `based-bin`
- **Binary name:** `based`
- **Source:** [`bin/based`](https://github.com/base/base/tree/main/bin/based)
- **Library:** [`crates/infra/based`](https://github.com/base/base/tree/main/crates/infra/based) (`based`)
## Architecture
`based` runs as a sidecar alongside the block builder. It:
1. Exposes HTTP health check endpoints for load balancer integration
2. Reports block-building metrics via StatsD to Datadog or compatible backends
3. Reads configuration from environment variables for deployment flexibility
## Key Dependencies
- `based` — Core daemon library
- `clap` — CLI argument parsing
- `tracing` / `tracing-subscriber` — Structured logging
- `tokio` — Async runtime
- `cadence` — StatsD metrics client (for Datadog integration)
## Environment Variables
| Variable | Purpose |
|----------|---------|
| `STATSD_HOST` | StatsD server hostname |
| `STATSD_PORT` | StatsD server port |
| `STATSD_PREFIX` | Metric name prefix |
| `CODEFLOW_*` | Codeflow environment integration variables |
## Build
```bash
cargo build --bin based --release
```
## Usage
```bash
./target/release/based [OPTIONS]
```
## Source
---
# builder
Source: https://basehub.org/binaries/builder/
Description: The Base block builder binary for flashblock production and block building.
import { LinkCard } from '@astrojs/starlight/components';
`base-builder` produces flashblocks every 200 milliseconds and assembles the sealed canonical blocks for Base. It orchestrates the build pipeline through `FlashblocksServiceBuilder`.
## Package
- **Crate name:** `base-builder-bin`
- **Binary name:** `base-builder`
- **Source:** [`bin/builder`](https://github.com/base/base/tree/main/bin/builder)
- **Dockerfile:** `etc/docker/Dockerfile.builder`
## Architecture
The builder binary bootstraps using `FlashblocksServiceBuilder`, which wires together:
1. **Block building** — Assembles transactions from the pool into execution payloads
2. **Flashblock production** — Produces 200ms sub-block preconfirmations streamed to subscribers
3. **Metering** — Tracks gas usage and resource consumption via `MeteringStoreExtension`
4. **Transaction pool RPC** — Exposes custom pool methods via `TxPoolRpcExtension`
The builder uses jemalloc as its global allocator for improved memory allocation performance.
## Key Extensions
| Extension | Purpose |
|-----------|---------|
| `FlashblocksServiceBuilder` | Orchestrates the full flashblocks pipeline |
| `MeteringStoreExtension` | Resource metering data store |
| `TxPoolRpcExtension` | Transaction pool RPC methods |
## Key Dependencies
- `base-cli-utils` — CLI utilities (logging, metrics)
- `base-builder-core` — Core block building logic
- `base-builder-metering` — Resource metering
- `base-builder-publish` — Block publishing and streaming
- `reth-optimism-node` — Reth node builder
- `jemalloc` — Memory allocator
## Build
```bash
# Build the builder binary
cargo build --bin base-builder --release
```
## Docker
```bash
# Build the image
docker build -t base-builder -f etc/docker/Dockerfile.builder .
# Run
docker run -it --rm base-builder [OPTIONS]
```
## Usage
```bash
./target/release/base-builder [OPTIONS]
```
## Source
---
# consensus
Source: https://basehub.org/binaries/consensus/
Description: The Base consensus node binary implementing the OP Stack consensus protocol via Kona.
import { Aside, LinkCard } from '@astrojs/starlight/components';
`base-consensus` runs the Base consensus layer, implementing the OP Stack consensus protocol on top of the [Kona](https://github.com/op-rs/kona) derivation framework.
## Package
- **Crate name:** `base-consensus`
- **Source:** [`bin/consensus`](https://github.com/base/base/tree/main/bin/consensus)
## Architecture
The consensus binary:
1. **L1 derivation** — Connects to L1 Ethereum to read rollup data and derives L2 blocks from L1 batches using the derivation pipeline
2. **P2P networking** — Manages peer-to-peer networking for block gossip and state sync
3. **Engine API** — Communicates with the execution layer (base-reth-node) via the Engine API to deliver derived payloads
4. **Kona integration** — Uses `kona-node-service` for the core consensus loop and `kona-genesis` for chain configuration
## Key Dependencies
- `base-cli-utils` — CLI utilities (logging, metrics)
- `base-client-cli` — Client CLI extensions
- `kona-genesis` — Genesis configuration
- `kona-cli` — Consensus CLI framework
- `kona-node-service` — Node service orchestration
## Build
```bash
cargo build --bin base-consensus --release
```
## Usage
```bash
./target/release/base-consensus [OPTIONS]
```
The consensus node must be configured with:
- An L1 Ethereum RPC endpoint for reading rollup data
- An Engine API endpoint for communicating with the execution layer
- A P2P configuration for block gossip
### Serving execution methods from the consensus port
By default the consensus RPC answers only its own methods. A call such as `eth_getBlockByNumber` fails with method not found, so a client that needs both layers has to hold two URLs. #5506 adds an opt-in fix: `--rpc.execution-forwarding-endpoint ` (env `BASE_NODE_RPC_EXECUTION_FORWARDING_ENDPOINT`). Point it at the execution client's plain, unauthenticated HTTP RPC. There is no default. It works on `base-consensus node`, `base-consensus follow`, `base rpc`, `base follow`, and `base sequencer`.
With the flag set, any method the consensus server does not serve goes to that endpoint unchanged, and its result or error comes back as is. The match is on the exact method name. A method the consensus server serves itself is never forwarded, even if the execution client has one of the same name. Each entry in a batch is routed on its own. Notifications are not forwarded. Forwarded calls share `--rpc.max-concurrent` and `--rpc.timeout` with the server's own requests. If the execution client returns no valid response, or a response over 10 MB, the caller gets a bare `-32603` internal error, and the real cause goes only to the log.
## Source
---
# ingress-rpc
Source: https://basehub.org/binaries/ingress-rpc/
Description: JSON-RPC ingress proxy with Kafka audit trail for transaction and bundle submission.
import { LinkCard } from '@astrojs/starlight/components';
`ingress-rpc` fronts the node, accepting JSON-RPC requests and routing each one to the right backend. Every request is mirrored to Kafka for audit and replay.
## Package
- **Crate name:** `ingress-rpc`
- **Source:** [`bin/ingress-rpc`](https://github.com/base/base/tree/main/bin/ingress-rpc)
- **Library:** [`crates/infra/ingress-rpc`](https://github.com/base/base/tree/main/crates/infra/ingress-rpc) (`ingress-rpc-lib`)
## Architecture
The ingress RPC proxy handles three categories of traffic:
1. **Transaction submission** — `eth_sendRawTransaction` calls forwarded to the transaction pool
2. **Bundle submission** — `eth_sendBundle` and related methods forwarded to the builder
3. **Mempool/simulation/raw TX forwarding** — Read and simulation requests forwarded to the appropriate backend
All requests are logged to Kafka for audit and replay purposes. The proxy uses `jsonrpsee` for its JSON-RPC server implementation.
## Request Flow
```
Client → ingress-rpc → Kafka (audit log)
→ Backend (node/builder/mempool)
→ Client (response)
```
## Key Dependencies
- `ingress-rpc-lib` — Core proxy logic
- `clap` — CLI argument parsing
- `tokio` — Async runtime
- `rdkafka` — Kafka client for audit logging
- `jsonrpsee` — JSON-RPC server
- `dotenvy` — Environment variable loading
## Build
```bash
cargo build --bin ingress-rpc --release
```
## Usage
```bash
./target/release/ingress-rpc [OPTIONS]
```
## Source
---
# mempool-rebroadcaster
Source: https://basehub.org/binaries/mempool-rebroadcaster/
Description: Bidirectional Geth-Reth mempool transaction rebroadcasting service.
import { LinkCard } from '@astrojs/starlight/components';
`mempool-rebroadcaster` bridges the Geth and Reth transaction pools, forwarding pending transactions in both directions so the two clients stay in sync.
## Package
- **Crate name:** `mempool-rebroadcaster-bin`
- **Binary name:** `mempool-rebroadcaster`
- **Source:** [`bin/mempool-rebroadcaster`](https://github.com/base/base/tree/main/bin/mempool-rebroadcaster)
- **Library:** [`crates/infra/mempool-rebroadcaster`](https://github.com/base/base/tree/main/crates/infra/mempool-rebroadcaster)
## Architecture
The rebroadcaster connects to both a Geth node and a Reth node, monitoring each transaction pool and forwarding new transactions to the other:
```
Geth txpool ←→ mempool-rebroadcaster ←→ Reth txpool
```
This ensures that during the migration from Geth to Reth, or in hybrid deployments where both clients are running, transactions submitted to either node are visible to both. The service periodically polls both pools and rebroadcasts any transactions that are missing from the other.
## Key Dependencies
- `mempool-rebroadcaster` — Core rebroadcasting logic
- `clap` — CLI argument parsing
- `dotenvy` — Environment variable loading
- `tracing` / `tracing-subscriber` — Structured logging
- `tokio` — Async runtime
## Build
```bash
cargo build --bin mempool-rebroadcaster --release
```
## Usage
```bash
./target/release/mempool-rebroadcaster [OPTIONS]
```
## Source
---
# websocket-proxy
Source: https://basehub.org/binaries/websocket-proxy/
Description: Fan-out WebSocket proxy with Brotli compression, API key authentication, and rate limiting.
import { LinkCard } from '@astrojs/starlight/components';
`websocket-proxy` fans out flashblock streams from one or more upstream builders to connected clients. It handles Brotli compression, API key authentication, and per-IP rate limiting.
## Package
- **Crate name:** `websocket-proxy-bin`
- **Binary name:** `websocket-proxy`
- **Source:** [`bin/websocket-proxy`](https://github.com/base/base/tree/main/bin/websocket-proxy)
- **Library:** [`crates/infra/websocket-proxy`](https://github.com/base/base/tree/main/crates/infra/websocket-proxy)
- **Dockerfile:** `etc/docker/Dockerfile.websocket-proxy`
## Architecture
The proxy operates as a fan-out service:
```
Upstream 1 ─┐
Upstream 2 ─┤→ websocket-proxy ─→ Client A
Upstream N ─┘ ─→ Client B
─→ Client N
```
It connects to one or more upstream WebSocket URIs (e.g., builder nodes producing flashblocks) and fans out the messages to all connected downstream clients. This enables horizontal scaling of flashblock delivery.
## Features
| Feature | Description |
|---------|-------------|
| **Fan-out** | Multiplexes messages from upstream sources to all connected clients |
| **Brotli compression** | Compresses WebSocket frames for bandwidth-efficient delivery |
| **API key auth** | Authenticates clients via API keys before allowing connections |
| **Per-IP rate limiting** | Prevents abuse by limiting connection rates per source IP |
| **Metrics** | Exposes Prometheus metrics on port 9000 |
| **Multiple upstreams** | Connects to multiple upstream URIs for redundancy |
## Ports
| Port | Protocol | Purpose |
|------|----------|---------|
| 8545 | WebSocket | Client-facing flashblock stream |
| 9000 | HTTP | Prometheus metrics |
## Key Dependencies
- `websocket-proxy` — Core proxy logic
- `brotli` — Brotli compression
- `futures` — Async stream utilities
- `hostname` — Hostname resolution
- `tokio` — Async runtime
## Docker
```bash
# Build the image
docker build -t websocket-proxy -f etc/docker/Dockerfile.websocket-proxy .
# Run
docker run -it --rm \
-p 8545:8545 \
-p 9000:9000 \
websocket-proxy [OPTIONS]
```
## Build
```bash
cargo build --bin websocket-proxy --release
```
## Usage
```bash
./target/release/websocket-proxy [OPTIONS]
```
## Source
---
# Contributing
Source: https://basehub.org/contributing/
Description: Issues and pull requests are off. Reach out on X.
Issues and pull requests on this repository are intentionally turned off — contributions aren't accepted through GitHub.
If you've spotted a bug, want to suggest content, or have feedback, tag [@wbnns on X](https://x.com/wbnns).
## Running it locally
```bash
npm install
npm run dev # http://localhost:4321 with HMR
npm run build # production build into dist/
npx astro check # type check
```
Node 20+ required.
## License
The site and the [`@wbnns/base-mcp`](https://www.npmjs.com/package/@wbnns/base-mcp) package are MIT-licensed (see [`LICENSE`](https://github.com/wbnns/basehub/blob/main/LICENSE)) — fork and adapt freely.
---
# alloy/consensus
Source: https://basehub.org/crates/alloy/consensus/
Description: Base alloy consensus types — transactions, receipts with Base-specific fields.
import { LinkCard } from '@astrojs/starlight/components';
## Overview
The `base-alloy-consensus` crate defines Base consensus types, including custom transaction and receipt types. It extends the standard Alloy consensus types for the OP Stack L2 environment.
## Key Dependencies
- `alloy-consensus` — Upstream consensus types
- `op-alloy-consensus` — OP Stack consensus types
## Source
---
# alloy/evm
Source: https://basehub.org/crates/alloy/evm/
Description: EVM implementation with Base hardfork awareness.
import { LinkCard } from '@astrojs/starlight/components';
## Overview
The `base-alloy-evm` crate implements the EVM with Base hardfork awareness. It builds on `op-revm` to customize execution for the Base L2 chain.
## Key Dependencies
- `op-revm` — OP Stack REVM extensions
- `revm` — Rust EVM implementation
- `base-alloy-hardforks` — Base hardfork definitions
## Source
---
# alloy/hardforks
Source: https://basehub.org/crates/alloy/hardforks/
Description: Named bindings for Base-specific hardforks.
import { LinkCard } from '@astrojs/starlight/components';
## Overview
The `base-alloy-hardforks` crate defines named bindings for Base hardforks. Other crates use these bindings to gate hardfork-aware behavior.
## Source
---
# alloy/network
Source: https://basehub.org/crates/alloy/network/
Description: Base blockchain RPC behavior abstraction at the network layer.
import { LinkCard } from '@astrojs/starlight/components';
## Overview
The `base-alloy-network` crate defines how the Base chain implements Alloy's network traits. It abstracts RPC behavior at the network layer.
## Source
---
# alloy
Source: https://basehub.org/crates/alloy/overview/
Description: Alloy type extensions for Base — consensus types, EVM customizations, RPC types, and network definitions.
The `alloy` crate group extends [Alloy](https://github.com/alloy-rs/alloy), the standard Rust toolkit for Ethereum types and RPC, with Base-specific consensus types, RPC types, EVM behavior, and hardfork definitions.
## Sub-crates
| Crate | Package Name | Purpose |
|-------|-------------|---------|
| [consensus](/crates/alloy/consensus/) | `base-alloy-consensus` | Base-specific consensus types |
| [evm](/crates/alloy/evm/) | `base-alloy-evm` | EVM customizations for Base |
| [hardforks](/crates/alloy/hardforks/) | `base-alloy-hardforks` | Base hardfork definitions |
| [network](/crates/alloy/network/) | `base-alloy-network` | Network type definitions |
| [provider](/crates/alloy/provider/) | `base-alloy-provider` | Alloy provider extensions |
| [rpc-jsonrpsee](/crates/alloy/rpc-jsonrpsee/) | `base-alloy-rpc-jsonrpsee` | JSON-RPC server traits (jsonrpsee) |
| [rpc-types-engine](/crates/alloy/rpc-types-engine/) | `base-alloy-rpc-types-engine` | Engine API RPC types |
| [rpc-types](/crates/alloy/rpc-types/) | `base-alloy-rpc-types` | General RPC type extensions |
## Role in the Architecture
The alloy crates sit at the foundation of the dependency graph. They define the types that flow through every other layer — from how blocks and transactions are represented in consensus, to the RPC types returned to users, to the EVM execution context.
These crates extend the upstream Alloy types with Base-specific fields and behaviors needed for the OP Stack L2 environment.
## Source
[`crates/alloy/`](https://github.com/base/base/tree/main/crates/alloy)
---
# alloy/provider
Source: https://basehub.org/crates/alloy/provider/
Description: Interface with a Base blockchain via the Engine API provider.
import { LinkCard } from '@astrojs/starlight/components';
## Overview
The `base-alloy-provider` crate exposes an Alloy provider for the Base chain, including Engine API extensions used by the consensus layer.
## Source
---
# alloy/rpc-jsonrpsee
Source: https://basehub.org/crates/alloy/rpc-jsonrpsee/
Description: Base RPC client using the jsonrpsee framework.
import { LinkCard } from '@astrojs/starlight/components';
## Overview
The `base-alloy-rpc-jsonrpsee` crate implements the Base RPC client on top of the [jsonrpsee](https://github.com/paritytech/jsonrpsee) framework.
## Source
---
# alloy/rpc-types
Source: https://basehub.org/crates/alloy/rpc-types/
Description: Base RPC types for blocks and transactions.
import { LinkCard } from '@astrojs/starlight/components';
## Overview
The `base-alloy-rpc-types` crate defines Base-specific RPC types for blocks and transactions. It extends the standard Ethereum JSON-RPC types.
## Source
---
# alloy/rpc-types-engine
Source: https://basehub.org/crates/alloy/rpc-types-engine/
Description: Base RPC types for the engine namespace — SSZ, snappy, and sha2 hashing.
import { LinkCard } from '@astrojs/starlight/components';
## Overview
The `base-alloy-rpc-types-engine` crate defines RPC types for the `engine` namespace, with SSZ serialization, snappy compression, and sha2 hashing support.
## Source
---
# builder/core
Source: https://basehub.org/crates/builder/core/
Description: Core block builder for the OP Stack — the main builder logic for sequencing and flashblock production.
import { LinkCard } from '@astrojs/starlight/components';
## Overview
The `base-builder-core` crate drives block building for the OP Stack. It handles sequencing, flashblock production at ~200ms intervals, and canonical block assembly.
This is the largest crate in the builder group, with dependencies on reth, alloy, revm, and the shared primitives. It integrates transaction bundling, gas metering, caching (via moka), and secp256k1 signing.
## Key Dependencies
- `base-bundles` — Transaction bundle types
- `base-client-node` — Node harness
- `base-primitives` — Core types
- `base-access-lists` — FAL implementation
- `reth-*` / `reth-optimism-*` — Reth execution crates
- `alloy-*` / `op-alloy-*` — Alloy types
- `revm` / `op-revm` — EVM execution
## Source
---
# builder/metering
Source: https://basehub.org/crates/builder/metering/
Description: Resource metering backend for the OP Stack block builder.
import { LinkCard } from '@astrojs/starlight/components';
## Overview
The `base-builder-metering` crate is the resource metering backend for the block builder. It tracks gas usage and resource consumption during block construction.
## Source
---
# builder
Source: https://basehub.org/crates/builder/overview/
Description: Block building, flashblock production, metering, and block publishing for Base.
The `builder` crate group produces blocks and flashblocks. It assembles flashblocks at 200ms intervals and publishes them to streaming clients.
## Sub-crates
| Crate | Package Name | Purpose |
|-------|-------------|---------|
| [core](/crates/builder/core/) | `base-builder-core` | Core block building logic and flashblock production |
| [metering](/crates/builder/metering/) | `base-builder-metering` | Resource metering for block building |
| [publish](/crates/builder/publish/) | `base-builder-publish` | Block/flashblock publishing and distribution |
## Role in the Architecture
The builder sits between the execution layer and the consensus layer. It:
1. Receives transactions from the transaction pool
2. Builds execution payloads using the EVM
3. Produces flashblocks at ~200ms intervals during the 2-second block time
4. Publishes flashblocks via WebSocket for real-time streaming
5. Finalizes the canonical block at the end of each slot
The `base-builder-core` crate contains the main building logic, `base-builder-metering` handles gas and resource accounting, and `base-builder-publish` handles distribution of produced blocks.
## Source
[`crates/builder/`](https://github.com/base/base/tree/main/crates/builder)
---
# builder/publish
Source: https://basehub.org/crates/builder/publish/
Description: WebSocket broadcast publisher for flashblock distribution.
import { LinkCard } from '@astrojs/starlight/components';
## Overview
The `base-builder-publish` crate is the WebSocket broadcast publisher for the OP Stack block builder. It streams produced flashblocks and canonical blocks to connected clients.
## Source
---
# client/cli
Source: https://basehub.org/crates/client/cli/
Description: CLI argument types for Base node consensus clients.
import { LinkCard } from '@astrojs/starlight/components';
## Overview
The `base-client-cli` crate defines the CLI argument types for Base node consensus clients. It integrates Kona and Alloy for chain configuration and argument parsing.
## Source
---
# client/engine
Source: https://basehub.org/crates/client/engine/
Description: Engine validator for the Base Node — handles Engine API, trie computation, and flashblocks.
import { LinkCard } from '@astrojs/starlight/components';
## Overview
The `base-client-engine` crate implements the engine validator for the Base Node. It handles Engine API communication, trie root computation, and flashblocks integration between the execution and consensus layers.
## Source
---
# client/flashblocks
Source: https://basehub.org/crates/client/flashblocks/
Description: Flashblocks state management — WebSocket streaming, pending state, EVM re-execution.
import { LinkCard } from '@astrojs/starlight/components';
## Overview
The `base-flashblocks` crate manages the core flashblocks state. It handles:
- WebSocket streaming of flashblock updates from the builder
- Pending state cache for preconfirmed transactions
- EVM re-execution for state queries against the pending block
- The `pending` tag support for standard Ethereum JSON-RPC methods
This is the crate that powers the [Flashblocks RPC](/specifications/flashblocks/).
## Source
---
# client/flashblocks-node
Source: https://basehub.org/crates/client/flashblocks-node/
Description: Flashblocks node extension — integrates flashblocks into the node lifecycle.
import { LinkCard } from '@astrojs/starlight/components';
## Overview
The `base-flashblocks-node` crate wires flashblocks into the Reth node lifecycle. It registers the flashblocks RPC, WebSocket streaming, and pending state management.
## Source
---
# client/metering
Source: https://basehub.org/crates/client/metering/
Description: Metering RPC for the Base node — resource and gas metering per block.
import { LinkCard } from '@astrojs/starlight/components';
## Overview
The `base-metering` crate exposes metering RPC endpoints for the Base node. It tracks gas usage and resource consumption per block.
## Source
---
# client
Source: https://basehub.org/crates/client/overview/
Description: Node client — CLI, engine, flashblocks integration, metering, proofs, and transaction pool tracing.
The `client` crate group assembles the full Base Reth Node. It supplies the CLI, Engine API integration, flashblocks support, metering RPC, proof extensions, and transaction pool tracing.
## Sub-crates
| Crate | Package Name | Purpose |
|-------|-------------|---------|
| [cli](/crates/client/cli/) | `base-client-cli` | CLI argument parsing and node configuration |
| [engine](/crates/client/engine/) | `base-client-engine` | Engine API client for consensus-execution communication |
| [flashblocks-node](/crates/client/flashblocks-node/) | `base-flashblocks-node` | Flashblocks-enabled node assembly |
| [flashblocks](/crates/client/flashblocks/) | `base-flashblocks` | Flashblocks RPC provider and pending state cache |
| [metering](/crates/client/metering/) | `base-metering` | Metering RPC endpoints for resource tracking |
| [proofs](/crates/client/proofs/) | `base-proofs-extension` | Proof generation extensions |
| [txpool-tracing](/crates/client/txpool-tracing/) | `base-txpool-tracing` | Transaction pool tracing and diagnostics |
## Role in the Architecture
The client crate group is the primary interface for node operators. It:
1. Parses CLI arguments and configures the node (`cli`)
2. Manages the Engine API connection between execution and consensus (`engine`)
3. Assembles the flashblocks-enabled node with all components (`flashblocks-node`)
4. Provides the Flashblocks RPC for querying preconfirmed state (`flashblocks`)
5. Exposes metering endpoints for gas and resource tracking (`metering`)
6. Supports proof generation for the fault proof system (`proofs`)
7. Adds tracing to the transaction pool for debugging (`txpool-tracing`)
The `base-reth-node` binary (in `bin/node`) depends primarily on this crate group.
## Source
[`crates/client/`](https://github.com/base/base/tree/main/crates/client)
---
# client/proofs
Source: https://basehub.org/crates/client/proofs/
Description: Proofs extension for the Base node — fault proof data via Execution Extensions.
import { LinkCard } from '@astrojs/starlight/components';
## Overview
The `base-proofs-extension` crate is the proofs extension for the Base node. It uses Reth's Execution Extensions (ExEx) framework to generate and serve fault proof data.
## Source
---
# client/txpool-tracing
Source: https://basehub.org/crates/client/txpool-tracing/
Description: Transaction tracing extensions — LRU caching, metrics, and streaming.
import { LinkCard } from '@astrojs/starlight/components';
## Overview
The `base-txpool-tracing` crate adds transaction tracing extensions to the Base node. It supplies LRU caching, metrics collection, and streaming support for transaction pool diagnostics.
## Source
---
# consensus/cli
Source: https://basehub.org/crates/consensus/cli/
Description: Shared CLI utilities for Kona crates — tracing, metrics, and clap argument parsing.
import { LinkCard } from '@astrojs/starlight/components';
## Overview
The `kona-cli` crate provides shared CLI utilities for Kona consensus crates, including tracing, metrics, and clap argument parsing.
## Source
---
# consensus/derive
Source: https://basehub.org/crates/consensus/derive/
Description: A `no_std` derivation pipeline implementation for the OP Stack. Derives L2 blocks from L1 data.
import { LinkCard } from '@astrojs/starlight/components';
## Overview
The `kona-derive` crate implements the OP Stack derivation pipeline. It derives L2 blocks from L1 data and runs in `no_std` environments.
## Source
---
# consensus/disc
Source: https://basehub.org/crates/consensus/disc/
Description: Discovery service for the OP Stack using discv5 and libp2p.
import { LinkCard } from '@astrojs/starlight/components';
## Overview
The `kona-disc` crate runs the peer discovery service for the OP Stack consensus layer. It uses discv5 and libp2p to find peers on the network.
## Source
---
# consensus/engine
Source: https://basehub.org/crates/consensus/engine/
Description: OP Stack engine client implementation — makes Engine API calls to the execution layer.
import { LinkCard } from '@astrojs/starlight/components';
## Overview
The `kona-engine` crate implements the OP Stack engine client. It makes Engine API calls from the consensus layer to the execution layer.
## Source
---
# consensus/genesis
Source: https://basehub.org/crates/consensus/genesis/
Description: Optimism genesis types including rollup config, system config, and hardfork definitions.
import { LinkCard } from '@astrojs/starlight/components';
## Overview
The `kona-genesis` crate defines Optimism genesis types, including the rollup config, system config, and hardfork definitions.
## Source
---
# consensus/gossip
Source: https://basehub.org/crates/consensus/gossip/
Description: Gossip protocol implementation for the OP Stack using libp2p gossipsub.
import { LinkCard } from '@astrojs/starlight/components';
## Overview
The `kona-gossip` crate implements the OP Stack gossip protocol on top of libp2p gossipsub.
## Source
---
# consensus/hardforks
Source: https://basehub.org/crates/consensus/hardforks/
Description: Consensus hardfork type definitions for the OP Stack.
import { LinkCard } from '@astrojs/starlight/components';
## Overview
The `kona-hardforks` crate defines the consensus hardfork types for the OP Stack.
## Source
---
# consensus/macros
Source: https://basehub.org/crates/consensus/macros/
Description: Utility procedural macros for kona crates.
import { LinkCard } from '@astrojs/starlight/components';
## Overview
The `kona-macros` crate supplies utility procedural macros used across the Kona consensus crates.
## Source
---
# consensus
Source: https://basehub.org/crates/consensus/overview/
Description: OP Stack consensus implementation — derivation pipeline, gossip networking, P2P discovery, and sequencing.
The `consensus` crate group implements the OP Stack consensus protocol for Base. The crates derive from the [Kona](https://github.com/op-rs/kona) project and handle L1 derivation, P2P networking, gossip, and block sequencing.
## Sub-crates
| Crate | Package Name | Purpose |
|-------|-------------|---------|
| [cli](/crates/consensus/cli/) | `kona-cli` | Consensus node CLI |
| [derive](/crates/consensus/derive/) | `kona-derive` | L1 derivation pipeline |
| [disc](/crates/consensus/disc/) | `kona-disc` | Peer discovery |
| [engine](/crates/consensus/engine/) | `kona-engine` | Consensus engine driver |
| [genesis](/crates/consensus/genesis/) | `kona-genesis` | Genesis state and chain configuration |
| [gossip](/crates/consensus/gossip/) | `kona-gossip` | Gossip protocol implementation |
| [hardforks](/crates/consensus/hardforks/) | `kona-hardforks` | OP Stack hardfork definitions |
| [macros](/crates/consensus/macros/) | `kona-macros` | Procedural macros for consensus code |
| [peers](/crates/consensus/peers/) | `kona-peers` | Peer management |
| [protocol](/crates/consensus/protocol/) | `base-protocol` | Base-specific protocol extensions |
| [providers-alloy](/crates/consensus/providers-alloy/) | `kona-providers-alloy` | Alloy-based data providers for L1/L2 |
| [registry](/crates/consensus/registry/) | `kona-registry` | Chain and rollup configuration registry |
| [rpc](/crates/consensus/rpc/) | `base-consensus-rpc` | Consensus RPC endpoints |
| [service](/crates/consensus/service/) | `kona-node-service` | Consensus node service orchestration |
| [sources](/crates/consensus/sources/) | `kona-sources` | Data source abstractions for derivation |
## Role in the Architecture
The consensus layer runs independently from the execution layer, communicating via the Engine API. It:
1. Connects to L1 Ethereum to read rollup data (`sources`, `providers-alloy`)
2. Derives L2 blocks from L1 data using the derivation pipeline (`derive`)
3. Manages P2P networking for block gossip (`gossip`, `disc`, `peers`)
4. Drives the consensus engine that feeds payloads to the execution layer (`engine`)
5. Handles chain configuration and hardfork activation (`genesis`, `hardforks`, `registry`)
The `base-consensus` binary (in `bin/consensus`) runs this layer.
## Source
[`crates/consensus/`](https://github.com/base/base/tree/main/crates/consensus)
---
# consensus/peers
Source: https://basehub.org/crates/consensus/peers/
Description: Network peers library for the OP Stack — peer management, discv5, and libp2p integration.
import { LinkCard } from '@astrojs/starlight/components';
## Overview
The `kona-peers` crate manages network peers for the OP Stack consensus layer. It integrates discv5 and libp2p for peer tracking and connection lifecycle.
## Source
---
# consensus/protocol
Source: https://basehub.org/crates/consensus/protocol/
Description: Base-specific protocol types — batches, channels, frames, and compression (brotli, zlib).
import { LinkCard } from '@astrojs/starlight/components';
## Overview
The `base-protocol` crate defines Base-specific protocol types: batches, channels, frames, and compression via brotli and zlib.
## Source
---
# consensus/providers-alloy
Source: https://basehub.org/crates/consensus/providers-alloy/
Description: Alloy-backed data providers for L1/L2 data including beacon, execution, and blob fetching with c-kzg.
import { LinkCard } from '@astrojs/starlight/components';
## Overview
The `kona-providers-alloy` crate supplies Alloy-backed data providers for L1 and L2 data, covering beacon, execution, and blob fetching with c-kzg.
## Source
---
# consensus/registry
Source: https://basehub.org/crates/consensus/registry/
Description: Registry of superchain configurations — chain configs loaded from TOML.
import { LinkCard } from '@astrojs/starlight/components';
## Overview
The `kona-registry` crate holds the registry of superchain configurations, loaded from TOML.
## Source
---
# consensus/rpc
Source: https://basehub.org/crates/consensus/rpc/
Description: RPC types and client for Base consensus using jsonrpsee.
import { LinkCard } from '@astrojs/starlight/components';
## Overview
The `base-consensus-rpc` crate defines the RPC types and client for the Base consensus layer, built on jsonrpsee.
## Source
---
# consensus/service
Source: https://basehub.org/crates/consensus/service/
Description: OP Stack consensus node service — orchestrates derivation, gossip, discovery, and engine communication.
import { LinkCard } from '@astrojs/starlight/components';
## Overview
The `kona-node-service` crate orchestrates the OP Stack consensus node. It coordinates derivation, gossip, discovery, and engine communication.
## Source
---
# consensus/sources
Source: https://basehub.org/crates/consensus/sources/
Description: Data source types and utilities for the consensus node including remote signer and transport abstractions.
import { LinkCard } from '@astrojs/starlight/components';
## Overview
The `kona-sources` crate defines data source types and utilities for the consensus node, including remote signer and transport abstractions.
## Source
---
# execution/chainspec
Source: https://basehub.org/crates/execution/chainspec/
Description: Defines OP chain parameters, genesis state, and hardfork activation for the Base execution layer.
import { LinkCard } from '@astrojs/starlight/components';
## Overview
The `execution/chainspec` sub-crate (`reth-optimism-chainspec`) is part of the [execution crate group](/crates/execution/overview/).
It defines the OP chain spec, including genesis state, gas parameters, and hardfork activation rules consumed by the EVM and consensus layers.
## Source
---
# execution/cli
Source: https://basehub.org/crates/execution/cli/
Description: Command-line entry point for the OP execution node with jemalloc, OpenTelemetry, and asm-keccak.
import { LinkCard } from '@astrojs/starlight/components';
## Overview
The `execution/cli` sub-crate (`reth-optimism-cli`) is part of the [execution crate group](/crates/execution/overview/).
It exposes the command-line interface for the OP execution node and wires in jemalloc, OpenTelemetry tracing, and the asm-keccak backend.
## Source
---
# execution/consensus
Source: https://basehub.org/crates/execution/consensus/
Description: Validates OP blocks and verifies trie roots inside the execution layer.
import { LinkCard } from '@astrojs/starlight/components';
## Overview
The `execution/consensus` sub-crate (`reth-optimism-consensus`) is part of the [execution crate group](/crates/execution/overview/).
It validates OP block headers and bodies and verifies state, transaction, and receipt trie roots before blocks enter the chain.
## Source
---
# execution/evm
Source: https://basehub.org/crates/execution/evm/
Description: OP EVM block executor and state transition logic for the Base execution environment.
import { LinkCard } from '@astrojs/starlight/components';
## Overview
The `execution/evm` sub-crate (`reth-optimism-evm`) is part of the [execution crate group](/crates/execution/overview/).
It runs the OP-flavored EVM, executing blocks and applying state transitions for the Base execution environment.
## Source
---
# execution/exex
Source: https://basehub.org/crates/execution/exex/
Description: Execution Extensions for OP-Reth, including the proofs ExEx that emits trie updates.
import { LinkCard } from '@astrojs/starlight/components';
## Overview
The `execution/exex` sub-crate (`reth-optimism-exex`) is part of the [execution crate group](/crates/execution/overview/).
It hosts Execution Extensions for OP-Reth, including the proofs ExEx that streams trie updates alongside committed blocks.
## Source
---
# execution/hardforks
Source: https://basehub.org/crates/execution/hardforks/
Description: Defines Optimism hardforks and activation rules used throughout op-reth.
import { LinkCard } from '@astrojs/starlight/components';
## Overview
The `execution/hardforks` sub-crate (`reth-optimism-forks`) is part of the [execution crate group](/crates/execution/overview/).
It enumerates Optimism hardforks and their activation rules, supplying the fork schedule consumed across op-reth.
## Source
---
# execution/node
Source: https://basehub.org/crates/execution/node/
Description: Assembles the OP execution node from EVM, RPC, payload, pool, and storage components.
import { LinkCard } from '@astrojs/starlight/components';
## Overview
The `execution/node` sub-crate (`reth-optimism-node`) is part of the [execution crate group](/crates/execution/overview/).
It assembles the OP execution node, wiring the EVM, RPC, payload builder, transaction pool, and storage into a runnable binary.
## Source
---
# execution
Source: https://basehub.org/crates/execution/overview/
Description: Execution layer crates covering the EVM, chain spec, payload building, storage, transaction pool, and state.
The `execution` crate group runs the Base node's execution layer. It spans EVM execution, state storage, transaction pool, and payload construction.
## Sub-crates
| Crate | Package Name | Purpose |
|-------|-------------|---------|
| [chainspec](/crates/execution/chainspec/) | `reth-optimism-chainspec` | EVM chain spec for Optimism |
| [cli](/crates/execution/cli/) | `reth-optimism-cli` | Execution layer CLI (jemalloc, OTel) |
| [consensus](/crates/execution/consensus/) | `reth-optimism-consensus` | Block validation and trie roots |
| [evm](/crates/execution/evm/) | `reth-optimism-evm` | Block executor and state transitions |
| [exex](/crates/execution/exex/) | `reth-optimism-exex` | Execution Extensions — proofs with trie updates |
| [hardforks](/crates/execution/hardforks/) | `reth-optimism-forks` | Optimism hardfork definitions |
| [node](/crates/execution/node/) | `reth-optimism-node` | Node builder — assembles all components |
| [payload](/crates/execution/payload/) | `reth-optimism-payload-builder` | Payload construction from pending transactions |
| [primitives](/crates/execution/primitives/) | `reth-optimism-primitives` | Custom transaction and receipt types |
| [reth](/crates/execution/reth/) | `reth-op` | Meta-crate re-exporting all OP reth components |
| [rpc](/crates/execution/rpc/) | `reth-optimism-rpc` | eth\_, debug\_, op\_ RPC namespaces |
| [storage](/crates/execution/storage/) | `reth-optimism-storage` | Database codec implementations |
| [trie](/crates/execution/trie/) | `reth-optimism-trie` | Trie storage for fault proof window |
| [txpool](/crates/execution/txpool/) | `reth-optimism-txpool` | Transaction pool with L1 cost calculation |
## Role in the Architecture
The execution crate group is the heart of the node. It:
1. Defines the Base chain specification including gas limits, hardforks, and genesis (`chainspec`, `hardforks`)
2. Configures and runs the EVM for transaction execution (`evm`)
3. Builds execution payloads from pending transactions (`payload`)
4. Manages the transaction pool for pending transactions (`txpool`)
5. Handles state storage and the Merkle Patricia Trie (`storage`, `trie`)
6. Provides RPC endpoints for querying execution state (`rpc`)
7. Integrates with Reth's execution pipeline (`reth`, `node`)
8. Supports Execution Extensions for custom indexing (`exex`)
Built on top of [Reth](https://github.com/paradigmxyz/reth) v1.11.0, these crates customize Reth's execution engine for the Base L2 environment.
## Source
[`crates/execution/`](https://github.com/base/base/tree/main/crates/execution)
---
# execution/payload
Source: https://basehub.org/crates/execution/payload/
Description: Builds OP execution payloads from pending transactions for the engine API.
import { LinkCard } from '@astrojs/starlight/components';
## Overview
The `execution/payload` sub-crate (`reth-optimism-payload-builder`) is part of the [execution crate group](/crates/execution/overview/).
It builds OP execution payloads from the pending transaction set, returning blocks ready for the engine API to commit.
## Source
---
# execution/primitives
Source: https://basehub.org/crates/execution/primitives/
Description: OP-specific transaction, receipt, and block primitive types shared across the execution layer.
import { LinkCard } from '@astrojs/starlight/components';
## Overview
The `execution/primitives` sub-crate (`reth-optimism-primitives`) is part of the [execution crate group](/crates/execution/overview/).
It defines the OP transaction, receipt, and block primitive types reused across the EVM, RPC, payload, and storage crates.
## Source
---
# execution/reth
Source: https://basehub.org/crates/execution/reth/
Description: Meta-crate that re-exports all OP reth components behind feature gates.
import { LinkCard } from '@astrojs/starlight/components';
## Overview
The `execution/reth` sub-crate (`reth-op`) is part of the [execution crate group](/crates/execution/overview/).
It re-exports the full OP reth surface behind `full`, `node`, `evm`, and `rpc` feature gates so downstream crates pull in only what they need.
## Source
---
# execution/rpc
Source: https://basehub.org/crates/execution/rpc/
Description: Implements the eth_, debug_, and op_ JSON-RPC namespaces for the OP execution layer.
import { LinkCard } from '@astrojs/starlight/components';
## Overview
The `execution/rpc` sub-crate (`reth-optimism-rpc`) is part of the [execution crate group](/crates/execution/overview/).
It implements the `eth_`, `debug_`, and `op_` JSON-RPC namespaces that clients use to query state, trace execution, and read OP-specific data.
## Source
---
# execution/storage
Source: https://basehub.org/crates/execution/storage/
Description: Database codecs for OP storage types used by the execution layer.
import { LinkCard } from '@astrojs/starlight/components';
## Overview
The `execution/storage` sub-crate (`reth-optimism-storage`) is part of the [execution crate group](/crates/execution/overview/).
It implements database codecs for OP-specific storage types so the execution layer can persist and read them through Reth's database stack.
## Source
---
# execution/trie
Source: https://basehub.org/crates/execution/trie/
Description: Stores trie nodes so the node can serve proofs across the fault proof window.
import { LinkCard } from '@astrojs/starlight/components';
## Overview
The `execution/trie` sub-crate (`reth-optimism-trie`) is part of the [execution crate group](/crates/execution/overview/).
It persists Merkle Patricia Trie nodes so the node can serve state and storage proofs throughout the fault proof window.
## Source
---
# execution/txpool
Source: https://basehub.org/crates/execution/txpool/
Description: OP-Reth transaction pool with gas estimation and L1 data cost accounting.
import { LinkCard } from '@astrojs/starlight/components';
## Overview
The `execution/txpool` sub-crate (`reth-optimism-txpool`) is part of the [execution crate group](/crates/execution/overview/).
It manages the OP-Reth transaction pool, applying gas estimation and L1 data fee accounting to pending transactions before they enter blocks.
## Source
---
# infra/audit
Source: https://basehub.org/crates/infra/audit/
Description: Consumes transaction events from Kafka and archives them to S3 for audit retention.
import { LinkCard } from '@astrojs/starlight/components';
## Overview
The `infra/audit` sub-crate (`audit-archiver-lib`) is part of the [infra crate group](/crates/infra/overview/).
It consumes transaction events from Kafka and archives them to S3, producing the audit trail used for operational review.
## Source
---
# infra/basectl
Source: https://basehub.org/crates/infra/basectl/
Description: Ratatui-based terminal UI for interacting with Base, with WebSocket, clipboard, and contract support.
import { LinkCard } from '@astrojs/starlight/components';
## Overview
The `infra/basectl` sub-crate (`basectl-cli`) is part of the [infra crate group](/crates/infra/overview/).
It ships a ratatui terminal UI for interacting with Base nodes, including WebSocket subscriptions, clipboard helpers, and contract calls.
## Source
---
# infra/based
Source: https://basehub.org/crates/infra/based/
Description: Shared library for block header fetching and StatsD metrics emission via cadence.
import { LinkCard } from '@astrojs/starlight/components';
## Overview
The `infra/based` sub-crate (`based`) is part of the [infra crate group](/crates/infra/overview/).
It provides shared building blocks for fetching block headers and emitting StatsD metrics through cadence across the infra binaries.
## Source
---
# infra/ingress-rpc
Source: https://basehub.org/crates/infra/ingress-rpc/
Description: Retired ingress JSON-RPC service, removed from base/base on 2026-09-21. Kept here for readers working with older tags or archived audit rows.
import { LinkCard } from '@astrojs/starlight/components';
:::caution[Retired crate]
`ingress-rpc` was deleted from `base/base` on 2026-09-21. Both `crates/infra/ingress-rpc` and `bin/ingress-rpc` are gone, and the crate is no longer a workspace member. This page stays up because the last tag that contains it, `v1.4.0`, is still the current stable release, and because archived audit records still reference the service.
:::
## Overview
The `infra/ingress-rpc` sub-crate (`ingress-rpc-lib`) was part of the [infra crate group](/crates/infra/overview/).
It ran an ingress JSON-RPC server that forwarded incoming transactions to the builder and wrote each one to Kafka for the audit trail.
## What replaced it
There is no drop-in successor crate. The removal took out the whole forwarding hop rather than reassigning it:
- The proxy layer is now the entry point. `proxyd` no longer forwards to an ingress service, and the devnet observability stack was renamed from `ingress` to `tx-observability` in the same change. See [Transaction Event Journal](/specifications/transaction-events/#local-devnet-verification).
- `roxy`, under `crates/infra/roxy`, is the in-house Rust reverse proxy meant to displace the `proxyd` fork. It is not a replacement for this crate, and its own README still describes it as scaffolding with no proxying implemented, so do not plan around it yet.
The transaction-event vocabulary kept its `ingress-rpc` producer value and its `INGRESS_*` event types on purpose, so that rows written before the removal still parse. Read those values; never emit them.
## Source
The crate no longer exists on `main`. This link points at `v1.4.0`, the last release that carries it.
---
# infra/mempool-rebroadcaster
Source: https://basehub.org/crates/infra/mempool-rebroadcaster/
Description: Rebroadcasts mempool transactions to multiple upstream providers to ensure propagation.
import { LinkCard } from '@astrojs/starlight/components';
## Overview
The `infra/mempool-rebroadcaster` sub-crate (`mempool-rebroadcaster`) is part of the [infra crate group](/crates/infra/overview/).
It rebroadcasts pending mempool transactions to multiple upstream providers so they propagate even when individual peers drop them.
## Source
---
# infra
Source: https://basehub.org/crates/infra/overview/
Description: Operational tooling for Base — basectl, ingress RPC, WebSocket proxy, mempool rebroadcaster, and tests.
The `infra` crate group runs the operational services around the Base node. It powers the auxiliary binaries that sit beside the main client.
## Sub-crates
| Crate | Package Name | Purpose |
|-------|-------------|---------|
| [audit](/crates/infra/audit/) | `audit-archiver-lib` | Audit log archival |
| [basectl](/crates/infra/basectl/) | `basectl-cli` | Node management utility |
| [based](/crates/infra/based/) | `based` | Base daemon service |
| [ingress-rpc](/crates/infra/ingress-rpc/) | `ingress-rpc-lib` | RPC ingress proxy (Kafka-based) — **retired 2026-09-21** |
| [mempool-rebroadcaster](/crates/infra/mempool-rebroadcaster/) | `mempool-rebroadcaster` | Transaction rebroadcasting service |
| [system-tests](/crates/infra/system-tests/) | `system-tests` | End-to-end system test framework |
| [websocket-proxy](/crates/infra/websocket-proxy/) | `websocket-proxy` | WebSocket proxy for flashblock streaming |
## Role in the Architecture
The infra crates provide the operational tooling around the core node:
- **basectl** — A management utility for configuring and inspecting Base nodes. Supports mainnet, sepolia, and devnet configurations.
- **based** — The Base daemon that orchestrates node services.
- **ingress-rpc** — An RPC proxy that routed incoming JSON-RPC requests, using Kafka for message queuing. Removed from the workspace on 2026-09-21; the proxy layer is the entry point now, and no crate took the forwarding hop over.
- **websocket-proxy** — Proxies WebSocket connections for flashblock streaming with Brotli compression.
- **mempool-rebroadcaster** — Rebroadcasts transactions from the mempool to ensure propagation.
- **audit** — Archives audit logs for operational monitoring.
- **system-tests** — Integration and end-to-end tests using Docker Compose.
## Source
[`crates/infra/`](https://github.com/base/base/tree/main/crates/infra)
---
# infra/system-tests
Source: https://basehub.org/crates/infra/system-tests/
Description: End-to-end test harness exercising the Base stack against Kafka, S3, and multiple providers.
import { LinkCard } from '@astrojs/starlight/components';
## Overview
The `infra/system-tests` sub-crate (`system-tests`) is part of the [infra crate group](/crates/infra/overview/).
It runs end-to-end tests against the full Base stack, standing up Kafka, S3, and multiple provider configurations to validate behavior.
## Source
---
# infra/websocket-proxy
Source: https://basehub.org/crates/infra/websocket-proxy/
Description: WebSocket proxy built on axum with Brotli compression and exponential backoff reconnects.
import { LinkCard } from '@astrojs/starlight/components';
## Overview
The `infra/websocket-proxy` sub-crate (`websocket-proxy`) is part of the [infra crate group](/crates/infra/overview/).
It runs an axum-based WebSocket proxy that fans out flashblock streams with Brotli compression and exponential backoff on reconnects.
## Source
---
# Crate Reference
Source: https://basehub.org/crates/overview/
Description: The 8 top-level crate groups that make up the base/base Cargo workspace.
The `base/base` Cargo workspace splits into 8 top-level crate groups. Each group owns a domain of the Base Reth Node and contains its own set of sub-crates.
## Workspace Structure
| Crate Group | Sub-crates | Purpose |
|-------------|-----------|---------|
| [alloy](/crates/alloy/overview/) | 8 | Alloy type extensions for Base (consensus types, RPC types, EVM, hardforks) |
| [builder](/crates/builder/overview/) | 3 | Block building, flashblock production, and metering |
| [client](/crates/client/overview/) | 7 | Node client — CLI, engine, flashblocks integration, metering, RPC |
| [consensus](/crates/consensus/overview/) | 15 | OP Stack consensus — derivation, gossip, P2P, sequencing (Kona-based) |
| [execution](/crates/execution/overview/) | 14 | Execution layer — EVM, chainspec, payload building, storage, txpool |
| [infra](/crates/infra/overview/) | 7 | Infrastructure tooling — basectl, ingress RPC, WebSocket proxy |
| [proof](/crates/proof/overview/) | 7 | Fault proof system — FPVM, preimage oracle, proof driver (Kona-based) |
| [shared](/crates/shared/overview/) | 9 | Shared utilities — primitives, access lists, JWT, bundles, CLI utils |
## Naming Conventions
Crate names in `Cargo.toml` follow these patterns:
- **`base-*`** — Core Base crates (e.g., `base-primitives`, `base-flashblocks`, `base-builder-core`)
- **`kona-*`** — Consensus and proof crates derived from the Kona project (e.g., `kona-derive`, `kona-proof`)
- **Infrastructure** — Named after their binary or function (e.g., `based`, `basectl-cli`, `ingress-rpc-lib`)
## Dependency Flow
At a high level, dependencies flow in this direction:
```
shared, alloy (foundation types)
↓
execution (EVM, state, txpool)
↓
client (node assembly, CLI, RPC)
↓
builder (block building, flashblocks)
consensus (independent OP Stack consensus)
proof (independent fault proof system)
infra (infrastructure binaries, depends on various crates)
```
The `shared` and `alloy` crates provide foundational types used throughout the workspace. The `execution` crates build on these to implement the EVM and state management. The `client` crates assemble the full node, and the `builder` crates handle block production.
The `consensus` and `proof` crate groups are relatively independent — they implement the OP Stack consensus protocol and fault proof system respectively, with their own internal dependency chains.
## Source Code
All crates live under [`crates/`](https://github.com/base/base/tree/main/crates) in the repository.
---
# proof/driver
Source: https://basehub.org/crates/proof/driver/
Description: no_std driver that sequences derivation and execution steps inside the fault proof program.
import { LinkCard } from '@astrojs/starlight/components';
## Overview
The `proof/driver` sub-crate (`kona-driver`) is part of the [proof crate group](/crates/proof/overview/).
It drives the `no_std` derivation pipeline, sequencing derive and execute steps so the fault proof program can advance the L2 chain step by step.
## Source
---
# proof/executor
Source: https://basehub.org/crates/proof/executor/
Description: no_std stateless OP Stack block builder that runs the EVM inside the FPVM.
import { LinkCard } from '@astrojs/starlight/components';
## Overview
The `proof/executor` sub-crate (`kona-executor`) is part of the [proof crate group](/crates/proof/overview/).
It builds OP Stack blocks statelessly inside the FPVM, executing the EVM against witness data supplied through the preimage oracle.
## Source
---
# proof/mpt
Source: https://basehub.org/crates/proof/mpt/
Description: Merkle Patricia Trie utilities for traversal, lookup, and proof verification inside the FPVM.
import { LinkCard } from '@astrojs/starlight/components';
## Overview
The `proof/mpt` sub-crate (`kona-mpt`) is part of the [proof crate group](/crates/proof/overview/).
It implements Merkle Patricia Trie traversal, lookup, and proof verification used by the fault proof program to read state.
## Source
---
# proof
Source: https://basehub.org/crates/proof/overview/
Description: Fault proof crates covering the FPVM runtime, preimage oracle, driver, executor, and MPT verification.
The `proof` crate group implements Base's fault proof stack. The crates derive from [Kona](https://github.com/op-rs/kona) and cover proof generation, verification, and the Fault Proof Virtual Machine (FPVM) interface.
## Sub-crates
| Crate | Package Name | Purpose |
|-------|-------------|---------|
| [driver](/crates/proof/driver/) | `kona-driver` | Proof generation driver |
| [executor](/crates/proof/executor/) | `kona-executor` | Stateless block executor for proofs |
| [mpt](/crates/proof/mpt/) | `kona-mpt` | Merkle Patricia Trie for proofs |
| [preimage](/crates/proof/preimage/) | `kona-preimage` | Preimage oracle interface |
| [proof](/crates/proof/proof/) | `kona-proof` | Core proof logic |
| [std-fpvm](/crates/proof/std-fpvm/) | `kona-std-fpvm` | Standard FPVM runtime |
| [std-fpvm-proc](/crates/proof/std-fpvm-proc/) | `kona-std-fpvm-proc` | Procedural macros for FPVM |
## Role in the Architecture
The proof system enables trustless verification of L2 state transitions on L1. It:
1. Re-executes L2 blocks in a deterministic environment (`executor`)
2. Uses the Merkle Patricia Trie for state proof verification (`mpt`)
3. Interfaces with the preimage oracle for reading L1/L2 data (`preimage`)
4. Runs inside the Fault Proof Virtual Machine (`std-fpvm`)
5. Coordinates the proof generation process (`driver`, `proof`)
These crates compile to targets that run inside the FPVM (e.g., MIPS or RISC-V) for on-chain dispute resolution.
## Source
[`crates/proof/`](https://github.com/base/base/tree/main/crates/proof)
---
# proof/preimage
Source: https://basehub.org/crates/proof/preimage/
Description: Rust bindings and types for the PreimageOracle ABI used by fault proof programs.
import { LinkCard } from '@astrojs/starlight/components';
## Overview
The `proof/preimage` sub-crate (`kona-preimage`) is part of the [proof crate group](/crates/proof/overview/).
It provides Rust bindings and typed wrappers over the PreimageOracle ABI, the channel through which fault proof programs read host data.
## Source
---
# proof/proof
Source: https://basehub.org/crates/proof/proof/
Description: OP Stack Proof SDK with KZG via ark-bls12-381, preimage oracle integration, and the full proof pipeline.
import { LinkCard } from '@astrojs/starlight/components';
## Overview
The `proof/proof` sub-crate (`kona-proof`) is part of the [proof crate group](/crates/proof/overview/).
It is the OP Stack Proof SDK, wiring KZG verification via `ark-bls12-381`, the preimage oracle, and the end-to-end proof pipeline.
## Source
---
# proof/std-fpvm
Source: https://basehub.org/crates/proof/std-fpvm/
Description: Platform APIs and a buddy allocator for programs targeting Fault Proof VM kernels.
import { LinkCard } from '@astrojs/starlight/components';
## Overview
The `proof/std-fpvm` sub-crate (`kona-std-fpvm`) is part of the [proof crate group](/crates/proof/overview/).
It exposes platform-specific APIs for Fault Proof VM kernels and ships a buddy allocator that proof programs use as their global allocator.
## Source
---
# proof/std-fpvm-proc
Source: https://basehub.org/crates/proof/std-fpvm-proc/
Description: Procedural macros that emit the entry point for kona-std-fpvm proof programs.
import { LinkCard } from '@astrojs/starlight/components';
## Overview
The `proof/std-fpvm-proc` sub-crate (`kona-std-fpvm-proc`) is part of the [proof crate group](/crates/proof/overview/).
It supplies procedural macros that generate the entry point and runtime glue for programs targeting `kona-std-fpvm`.
## Source
---
# shared/access-lists
Source: https://basehub.org/crates/shared/access-lists/
Description: Implements Flashblock-level Access Lists (FAL), the EIP-7928 adaptation used by Base.
import { LinkCard } from '@astrojs/starlight/components';
## Overview
The `shared/access-lists` sub-crate (`base-access-lists`) is part of the [shared crate group](/crates/shared/overview/).
It implements Flashblock-level Access Lists (FAL), Base's adaptation of EIP-7928 for the OP Stack.
## Source
---
# shared/bundles
Source: https://basehub.org/crates/shared/bundles/
Description: Defines transaction bundle types with UUID IDs, signing, and gas estimation for ordering.
import { LinkCard } from '@astrojs/starlight/components';
## Overview
The `shared/bundles` sub-crate (`base-bundles`) is part of the [shared crate group](/crates/shared/overview/).
It defines transaction bundle types, including UUID identification, signing, and gas estimation that other crates use to order bundles.
## Source
---
# shared/cli-utils
Source: https://basehub.org/crates/shared/cli-utils/
Description: Shared CLI helpers for tracing, Prometheus export, clap parsing, and Kona registry lookups.
import { LinkCard } from '@astrojs/starlight/components';
## Overview
The `shared/cli-utils` sub-crate (`base-cli-utils`) is part of the [shared crate group](/crates/shared/overview/).
It provides shared CLI helpers across the workspace: tracing setup, Prometheus metric export, clap argument helpers, and Kona registry chain lookup.
## Source
---
# shared/engine-ext
Source: https://basehub.org/crates/shared/engine-ext/
Description: In-process engine client that talks directly to Reth's execution layer without going over RPC.
import { LinkCard } from '@astrojs/starlight/components';
## Overview
The `shared/engine-ext` sub-crate (`base-engine-ext`) is part of the [shared crate group](/crates/shared/overview/).
It exposes an in-process engine client so consensus components can drive Reth's execution layer directly without round-tripping through JSON-RPC.
## Source
---
# shared/jwt
Source: https://basehub.org/crates/shared/jwt/
Description: Loads and validates JWT secrets that authenticate Engine API traffic between node components.
import { LinkCard } from '@astrojs/starlight/components';
## Overview
The `shared/jwt` sub-crate (`base-jwt`) is part of the [shared crate group](/crates/shared/overview/).
It loads and validates the JWT secrets that authenticate Engine API traffic between the consensus and execution components.
## Source
---
# shared/node
Source: https://basehub.org/crates/shared/node/
Description: Core node harness with the types and traits used to build Base node runner extensions.
import { LinkCard } from '@astrojs/starlight/components';
## Overview
The `shared/node` sub-crate (`base-client-node`) is part of the [shared crate group](/crates/shared/overview/).
It defines the core node harness, including the primitive types and traits that Base node runner extensions implement.
## Source
---
# shared
Source: https://basehub.org/crates/shared/overview/
Description: Foundational crates for primitives, access lists, JWT auth, bundles, CLI utilities, and RPC types.
The `shared` crate group holds the foundational types and utilities used across the workspace. It defines primitives, access lists, JWT auth, and RPC extensions consumed by every other crate group.
## Sub-crates
| Crate | Package Name | Purpose |
|-------|-------------|---------|
| [access-lists](/crates/shared/access-lists/) | `base-access-lists` | Flashblock-level Access Lists (FAL) implementation |
| [bundles](/crates/shared/bundles/) | `base-bundles` | Transaction bundle types |
| [cli-utils](/crates/shared/cli-utils/) | `base-cli-utils` | CLI utilities (logging, metrics, clap helpers) |
| [engine-ext](/crates/shared/engine-ext/) | `base-engine-ext` | Engine API extensions |
| [jwt](/crates/shared/jwt/) | `base-jwt` | JWT authentication for Engine API |
| [node](/crates/shared/node/) | `base-client-node` | Shared node configuration |
| [primitives](/crates/shared/primitives/) | `base-primitives` | Core primitive types (includes Solidity contracts for tests) |
| [reth-rpc-types](/crates/shared/reth-rpc-types/) | `base-reth-rpc-types` | Reth-compatible RPC type definitions |
| [txpool-rpc](/crates/shared/txpool-rpc/) | `base-txpool-rpc` | Transaction pool RPC extensions |
## Role in the Architecture
The shared crates form the foundation layer that all other crate groups depend on:
- **primitives** — Defines the core types (transactions, blocks, receipts) used everywhere. Includes Solidity contracts compiled with Foundry for testing.
- **access-lists** — Implements the [FAL specification](/specifications/access-lists/) for flashblock-level access lists, adapting EIP-7928 for the OP Stack.
- **cli-utils** — Provides standardized CLI setup including clap argument parsing, tracing/logging configuration, and Prometheus metrics exporting.
- **jwt** — Handles JWT-based authentication for the Engine API connection between execution and consensus layers.
- **engine-ext** — Extends the Engine API with Base-specific payload attributes.
- **txpool-rpc** — Adds custom RPC methods for interacting with the transaction pool.
- **bundles** — Defines transaction bundle types for MEV and priority ordering.
- **reth-rpc-types** — Bridges Base types to Reth's RPC type system.
## Source
[`crates/shared/`](https://github.com/base/base/tree/main/crates/shared)
---
# shared/primitives
Source: https://basehub.org/crates/shared/primitives/
Description: Shared primitive types, Brotli helpers, bundle types, and Solidity bindings used across Base.
import { LinkCard } from '@astrojs/starlight/components';
## Overview
The `shared/primitives` sub-crate (`base-primitives`) is part of the [shared crate group](/crates/shared/overview/).
It defines the workspace-wide primitive types and ships Brotli helpers, bundle types, and Solidity contract bindings used by tests and runtime code.
## Source
---
# shared/reth-rpc-types
Source: https://basehub.org/crates/shared/reth-rpc-types/
Description: Re-exports Reth RPC types so external consumers of the Base RPC interface get a stable surface.
import { LinkCard } from '@astrojs/starlight/components';
## Overview
The `shared/reth-rpc-types` sub-crate (`base-reth-rpc-types`) is part of the [shared crate group](/crates/shared/overview/).
It re-exports the Reth RPC types so external consumers of the Base RPC interface depend on one stable surface.
## Source
---
# shared/txpool-rpc
Source: https://basehub.org/crates/shared/txpool-rpc/
Description: Adds Base-specific RPC methods for inspecting and interacting with the transaction pool.
import { LinkCard } from '@astrojs/starlight/components';
## Overview
The `shared/txpool-rpc` sub-crate (`base-txpool-rpc`) is part of the [shared crate group](/crates/shared/overview/).
It extends the JSON-RPC surface with Base-specific methods for inspecting and interacting with the transaction pool.
## Source
---
# App Integration
Source: https://basehub.org/flashblocks/app-integration/
Description: Integrate Flashblocks for 200ms confirmations using the pending RPC tag with Wagmi, Viem, Ethers, and Flashblocks-aware node providers.
import { Aside, Tabs, TabItem } from '@astrojs/starlight/components';
Choose the integration that matches your app's needs and connect through a Flashblocks-aware RPC endpoint.
| Use case | Recommended approach | Documentation |
|----------|----------------------|---------------|
| **Apps needing instant UX** | Flashblocks-aware RPC with the `pending` tag. | [API Reference](/api-reference/flashblocks/flashblocks-api-overview/) |
| **Infrastructure providers** | Host Flashblocks-aware RPC nodes. | [Enable Flashblocks](/node-operations/run-a-base-node/#enable-flashblocks) |
| **Standard apps** | Continue using regular RPCs. | [JSON-RPC API Reference](/api-reference/rpc-overview/) |
## RPC endpoints
For HTTP and WebSocket endpoint URLs, see the [Flashblocks API reference](/api-reference/flashblocks/flashblocks-api-overview/). Public endpoints are rate-limited; for production, route through a Flashblocks-enabled provider such as Alchemy, QuickNode, or dRPC.
## Performance characteristics
| Metric | Value |
|--------|-------|
| Flashblock build time (P50) | ~10ms |
| Preconfirmation latency | ~200ms |
| Full block time | 2 seconds |
| Flashblocks per block | 10 |
| Reorg rate | < 0.1% |
## Gas and transaction sizing
The gas budget is **cumulative**, not per-Flashblock. Each Flashblock unlocks an additional 1/10 of the total block gas:
| Flashblock | Cumulative gas available |
|------------|--------------------------|
| 1 | 1/10 of block limit (~40M gas) |
| 2 | 2/10 of block limit (~80M gas) |
| 3 | 3/10 of block limit (~120M gas) |
| ... | ... |
| 10 | Full block limit (~400M gas) |
**Implications for large transactions:**
- In practice, gas size is rarely the limiting factor. Base's **per-transaction gas maximum** of 16,777,216 gas (~16.7M) is already below Flashblock 1's ~40M budget, so any valid transaction qualifies for the first Flashblock on size alone.
- Inclusion timing is governed primarily by priority fee relative to others competing in the same 200ms window, not by transaction size.
## Reliability and fallback
Base targets a **< 0.1% Flashblock reorg rate** — the share of preconfirmations that were streamed but missed inclusion in the final block. This is rare, but apps should plan for it.
If Flashblocks become unavailable, the sequencer keeps running and confirmation falls back to standard 2-second blocks. Apps should handle both modes.
## Library examples
A Flashblocks-aware RPC endpoint is required to use Flashblocks with these libraries.
### [Wagmi](https://wagmi.sh)
To use Flashblocks with Wagmi, set the `basePreconf` chain in the Wagmi config (see `config.ts`).
```tsx
import { useSendTransaction, useWaitForTransactionReceipt } from "wagmi";
function SendTransaction() {
const { data: hash, sendTransaction } = useSendTransaction();
const { data: receipt } = useWaitForTransactionReceipt({ hash });
return (
{hash &&
Hash: {hash}
}
{receipt &&
Included on block number: {receipt.blockNumber}
}
)
}
```
```tsx
import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
import { WagmiProvider, useAccount } from 'wagmi'
import { config } from './config'
import { Example } from './Example'
const queryClient = new QueryClient()
function App() {
return (
)
}
```
```tsx
import { createConfig, http } from "wagmi";
import { baseSepoliaPreconf } from "wagmi/chains";
import { baseAccount } from "wagmi/connectors";
export const config = createConfig({
chains: [baseSepoliaPreconf],
connectors: [baseAccount()],
transports: {
[baseSepoliaPreconf.id]: http(),
},
});
```
### [Viem](https://viem.sh)
```ts
import { createWalletClient, http, parseEther, publicActions } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { baseSepoliaPreconf } from "viem/chains";
// Create client with the Flashblocks-aware chain.
const account = privateKeyToAccount(`0x${process.env.PRIVATE_KEY}`);
const client = createWalletClient({
account,
chain: baseSepoliaPreconf,
transport: http(),
})
.extend(publicActions);
const submissionTime = new Date();
console.log(`Submitting transaction at: ${submissionTime.toISOString()}`);
// Send transaction.
const hash = await client.sendTransaction({
to: "0x...",
value: parseEther('0.0001'),
});
console.log(`Transaction hash: ${hash}`);
// Wait for transaction to be included.
const receipt = await client.waitForTransactionReceipt({ hash });
const confirmTime = new Date();
console.log(`Transaction included at: ${confirmTime.toISOString()}`);
console.log(`Time difference: ${confirmTime - submissionTime}ms`);
```
### [Ethers](https://github.com/ethers-io/ethers.js)
```jsx
const providerA = new ethers.JsonRpcProvider(
"https://sepolia.base.org"
);
const wallet = new ethers.Wallet(process.env.PRIVATE_KEY, providerA);
try {
// Create a simple transaction (sending 0.001 ETH to a random address)
const tx = {
to: "",
value: ethers.parseEther("0.0000001"),
};
// Submit transaction
const submissionTime = new Date();
const transaction = await wallet.sendTransaction(tx);
console.log(`Submitting transaction at: ${submissionTime.toISOString()}`);
console.log(`Transaction hash: ${transaction.hash}`);
await transaction.wait(0); // Make sure to set the confirmation count to 0
console.log("Transaction confirmed");
const confirmationTime = new Date();
console.log(`Transaction confirmed at: ${confirmationTime.toISOString()}`);
console.log(`Time difference: ${confirmationTime - submissionTime}ms`);
}
```
Confirmation times against this endpoint should be substantially lower than the standard RPC.
## Support
For feedback, support, or questions about Flashblocks, reach the team in the `#developer-chat` channel on the [Base Discord](https://base.org/discord).
---
# Flashblocks Architecture
Source: https://basehub.org/flashblocks/architecture/
Description: Sequencer topology and infrastructure components — rollup-boost, base-builder, websocket-proxy, and base — that power Flashblocks on Base.
The Flashblocks pipeline layers four new components — rollup-boost, base-builder, websocket-proxy, and base — onto Base's existing high-availability sequencer.
## Before Flashblocks
Base operates a high-availability sequencer with five sequencer instances:
| Component | Role |
|-----------|------|
| **base-consensus** | Consensus layer (CL) — took over from op-node after Azul. |
| **base-reth-node** | Execution layer (EL) — took over from op-geth after Azul. |
| **op-conductor** | High availability controller using Raft consensus for leader election. |
One sequencer instance is the **leader** and produces blocks, propagating them over P2P. The other four follow and sync the chain. Leadership transfers when the current leader stops producing blocks.
## With Flashblocks
Flashblocks add several new infrastructure components:
| Component | Purpose | What it unlocks |
|-----------|---------|-----------------|
| **rollup-boost** | CL↔EL Engine API proxy. | Streams Flashblocks to the EL without modifying the CL. Provides a stable seam for future block-building changes such as multi-builder. |
| **base-builder** | Out-of-protocol builder running at 200ms cadence. | Produces sub-second Flashblocks decoupled from the EL and enables pluggable builder mechanisms. |
| **websocket-proxy** | Fan-out for the Flashblocks stream. | Lets many consumers read the stream without overwhelming the builder. |
| **[base](https://github.com/base/base)** | RPC surface that exposes preconfirmations. | Turns streamed Flashblocks into familiar RPC methods so apps and wallets can consume preconfirmed state. |
Flashbots builds and maintains [rollup-boost](https://github.com/flashbots/rollup-boost); Base maintains [base-builder](https://github.com/base/base/tree/main/crates/builder), the websocket-proxy, and the [base](https://github.com/base/base) component.
---
## Further reading
- [Flashblocks Overview](/flashblocks/overview/) — key concepts and transaction lifecycle.
- [Enable Flashblocks](/node-operations/run-a-base-node/#enable-flashblocks) — run your own Flashblocks-aware RPC node.
- [API Reference](/api-reference/flashblocks/flashblocks-api-overview/) — RPC methods, WebSocket subscriptions, and infrastructure stream schema.
- [Flashblocks deep dive](https://blog.base.dev/flashblocks-deep-dive) — engineering blog post with implementation details.
---
# Flashblocks FAQ
Source: https://basehub.org/flashblocks/faq/
Description: Answers to common questions about Flashblocks block building, WebSocket data, RPC behavior, and node setup on Base.
import { Aside } from '@astrojs/starlight/components';
Common questions about Flashblocks block building, WebSocket access, RPC behavior, and node setup.
## Block building
### Are Flashblocks optional?
Every block on Base is built by the Flashblocks builder, so **Flashblocks are always live**. Apps that prefer not to consume preconfirmations can keep using standard RPCs without any Flashblocks integration.
### Is transaction inclusion different for Flashblocks vs. 2-second blocks?
Not in any meaningful way — both order transactions by fee. The difference is timing: Flashblocks arrive every 200ms instead of every 2 seconds.
See [Block Building](/network/block-building/#flashblocks) for details.
### Can the sequencer stop publishing Flashblocks?
The sequencer will not stop publishing Flashblocks unless an extreme situation makes them unsafe to operate. If that happens, preconfirmations are disabled network-wide and confirmation falls back to standard 2-second blocks. The sequencer continues operating normally.
### Why is my transaction having trouble getting included?
Inclusion timing is driven mainly by priority fee, not transaction size. The builder allocates gas cumulatively — Flashblock `j` may use up to `j/10` of the total block gas limit — so in principle a very large transaction has a harder time landing in the first Flashblock. In practice this rarely bites: Base's [per-transaction gas maximum](/network/block-building/#per-transaction-gas-maximum) of 16,777,216 gas (~16.7M) is already below Flashblock 1's ~40M budget, so any valid transaction fits in the first Flashblock on size alone. When a transaction is slow to include, the usual cause is a low priority fee relative to others competing in the same 200ms window.
See [Block Building](/network/block-building/) for the gas budget breakdown and throughput limits.
### How do I make sure my transaction lands in the first Flashblock?
There is no way to guarantee inclusion in a specific Flashblock, just as there is no way to guarantee a specific block. Since the per-transaction gas maximum (~16.7M) sits below Flashblock 1's ~40M capacity, gas size is not the limiting factor — every valid transaction is eligible for the first Flashblock. To improve the odds of fast inclusion, set a higher priority fee.
### Why do transactions sometimes appear out of fee order?
The Flashblock builder uses a **dynamic mempool** that keeps accepting new transactions while it builds. The design favors **low inclusion latency** over strict fee ordering.
**What that means in practice:**
- Transactions are ordered by fee *at the moment they are selected* for inclusion.
- A high-fee transaction that arrives after a lower-fee transaction has already been committed to the current Flashblock will appear after it (or in the next Flashblock).
- This is expected — the builder does not "reorder" already-committed transactions.
**Why this trade-off?**
A "snapshot" mempool that froze the txpool at the start of each block would guarantee strict fee ordering but at the cost of higher inclusion latency. The dynamic approach gets transactions into blocks faster, occasionally at the expense of breaking strict priority gas auction (PGA) ordering.
**For traders and bots:** if strict fee-based ordering is essential to your strategy, arrival timing matters as much as fee amount within any 200ms Flashblock window.
### How frequently do Flashblock reorgs happen?
Base targets a Flashblock reorg rate of < 0.1%. Reorgs are rare, but applications handling critical operations should still implement fallback logic.
Live metrics are at [base.org/stats](https://base.org/stats).
### What does it mean when a Flashblock is reorged?
A reorg means a Flashblock was streamed as a preconfirmation but did not make it into the final block. Architectural improvements in rollup-boost prevent tail-Flashblock reorgs, so this is uncommon — but apps should still handle the case.
---
## WebSocket
### Can I connect directly to the Flashblocks WebSocket stream?
**No.** The raw Flashblocks WebSocket (`wss://mainnet.flashblocks.base.org/ws`) is reserved for infrastructure-to-node data syncing. Applications should not connect to it directly.
Instead, query your RPC node or node provider (QuickNode, Alchemy, Infura, dRPC, etc.) for Flashblocks data via:
- **RPC API** — standard JSON-RPC methods with the `pending` tag.
- **WebSocket subscriptions** — `eth_subscribe` through your node provider's WebSocket endpoint.
See [App Integration](/flashblocks/app-integration/) for implementation details.
### Why are there 11 Flashblock indices (0-10)?
Index 0 carries only system transactions and uses no gas budget. Indexes 1-10 are the actual Flashblocks that pull pending transactions from the txpool.
### Why are there sometimes fewer than 10 Flashblocks?
Expected behavior. When the previous block takes longer to build, the system compensates by allocating less time to the next block, which leaves room for fewer Flashblocks.
### Can the Flashblock index exceed 10? Is that a bug?
**Not a bug.** Indices of 10, 11, or higher show up in normal operation.
The standard math — 2-second block time divided by 200ms per Flashblock — yields exactly 10 Flashblocks (indices 0-9). In practice, the transition from one full L2 block to the next is not always perfectly aligned with the 200ms timer. Two situations create extra indices:
1. **Sequencer delay.** If sealing the full block takes slightly longer than 2000ms, the Flashblock stream keeps emitting incremental updates for the current block to keep the stream live.
2. **Timing drift.** If the internal 200ms clock drifts or starts early relative to the L2 block's canonical start time, an extra update can fit inside the 2-second window.
**What this means for your implementation:**
- Do not hardcode `9` or `10` as the final index — the last Flashblock for a given block is not predictable by index alone.
- Track `payloadId` instead. The most reliable signal that a block has finished is when `payloadId` changes, or when the full block confirms via standard RPC. All Flashblocks sharing the same `payloadId` belong to the same block, no matter how high the index goes.
- Once the sequencer advances to the next block, `payloadId` resets and `index` returns to `0`.
### What encoding format is the transaction data in?
Transaction data in the [`diff.transactions`](/api-reference/flashblocks/flashblocks-api-overview/#diff-object) array is Recursive Length Prefix (RLP) encoded.
### Why am I getting rate limited on the WebSocket?
Whatever socket you are connected to belongs to somebody, and it enforces their limits. Base publishes no free WebSocket RPC on Mainnet or Sepolia, so every `wss://` endpoint that works for Flashblocks is either your own node or a provider's, and each sets its own ceiling on connections and messages. There is no shared public allowance to be throttled against. For production use:
1. Run your own [Flashblocks-aware RPC node](/node-operations/run-a-base-node/#enable-flashblocks), where the limits are yours to set.
2. Use a third-party node provider with Flashblocks support, and size the plan to your subscription count.
---
## RPC
### Why am I getting rate limited using `mainnet.base.org`?
The public endpoint applies explicit rate limits. For production traffic:
- Use a third-party node provider with Flashblocks support (Alchemy, Infura, QuickNode, dRPC).
- Run your own [Flashblocks-aware RPC node](/node-operations/run-a-base-node/#enable-flashblocks).
### Why does `eth_call "pending"` report a block number several blocks behind tip?
This is expected. Flashblocks-aware nodes retain up to 5 historical blocks of Flashblocks state to avoid race conditions. When `eth_call "pending"` runs, it executes on top of that historical base, so the block number visible in the call context (such as `block.number`) may show as N-5.
When `eth_call "pending"` executes, the entire block context — `block.number`, `block.timestamp`, `block.basefee`, and the rest — corresponds to that historical base block (potentially N-5), not the current chain tip. **The call result is correct** in that all received Flashblocks state has been applied on top, but contracts that depend on block context properties should be aware that those values may be several blocks behind.
For nodes in regions where P2P latency is comparable to WebSocket stream latency, lowering `MAX_PENDING_BLOCKS_DEPTH` reduces this gap. The setting controls how many historical blocks of Flashblocks state the node retains; a lower value keeps the block context closer to tip at the cost of less tolerance for P2P latency spikes.
### What RPC methods support Flashblocks?
The following methods are Flashblocks-enabled:
| Method | Usage |
|--------|-------|
| `eth_getBlockByNumber` | Use the `pending` tag. |
| `eth_getBalance` | Use the `pending` tag. |
| `eth_getTransactionReceipt` | Returns preconfirmed receipts. |
| `eth_getTransactionByHash` | Use the `pending` tag. |
| `eth_getTransactionCount` | Use the `pending` tag. |
| `eth_call` | Use the `pending` tag. |
| `eth_simulateV1` | Use the `pending` tag. |
| `eth_estimateGas` | Use the `pending` tag. |
| `eth_getLogs` | Use `pending` for `toBlock`. |
| `eth_subscribe` | Stream Flashblock data in real time. |
| `base_transactionStatus` | Check if a transaction is in the mempool (Beta). |
See the [Flashblocks API reference](/api-reference/flashblocks/flashblocks-api-overview/) for full method details and examples.
---
## Node setup
### How do I set up a Flashblocks-aware RPC node?
Use the Reth binary from the [base/base repository](https://github.com/base/base). Full instructions are in [Enable Flashblocks](/node-operations/run-a-base-node/#enable-flashblocks).
---
# Migrate to 200ms Blocks
Source: https://basehub.org/flashblocks/migrate-to-200ms-blocks/
Description: Move a Flashblocks integration onto canonical 200ms blocks ahead of the Denim upgrade, with a replacement for every subscription and pending-tag RPC call.
import { Aside } from '@astrojs/starlight/components';
Read this page if your application consumes Flashblocks. The [Denim](/specifications/denim-200ms-blocks/) upgrade swaps Flashblocks for canonical 200ms blocks. Once it activates, Flashblocks subscriptions and the pending state behind them stop being available.
## Where to start
Take an inventory before Denim lands. Two things belong on that list: every Flashblocks subscription your application opens, and every RPC request it makes with the `"pending"` block tag. Work through the table below and pair each one with its replacement.
Flashblocks integrations are not the only thing Denim touches. If you also own contracts, check them for durations expressed as block counts: `block.number` advances ten times faster afterwards, so timelocks, cooldowns, vesting schedules, and governance windows written that way shrink to a tenth of their intended length. [Block-number contract logic](/specifications/denim-200ms-blocks/#block-number-contract-logic) has the pattern table.
## Replacements by integration
| Flashblocks integration | Update for Denim |
| --- | --- |
| `eth_subscribe("newFlashblocks")` | Use `eth_subscribe("newHeads")`. |
| `eth_subscribe("pendingLogs")` | Use `eth_subscribe("logs")`. |
| `eth_subscribe("newFlashblockTransactions")` | Use `eth_subscribe("newHeads")`, then fetch transactions for each canonical block. |
| `eth_getBlockByNumber("pending", ...)` | Use normal RPC calls to read the latest canonical blocks. |
| `eth_getBalance(..., "pending")` | Use normal RPC calls to read the latest canonical state. |
| `eth_getTransactionCount(..., "pending", ...)` | Use normal RPC calls to read the latest canonical state. |
| `eth_call(..., "pending")` | Use normal RPC calls to read the latest canonical state. |
| `eth_estimateGas(..., "pending")` | Use normal RPC calls to read the latest canonical state. |
| `eth_simulateV1(..., "pending")` | Use normal RPC calls to read the latest canonical state. |
| `eth_getLogs` with a range ending at `"pending"` | Use normal RPC calls to query logs from canonical blocks. |
| `eth_getBlockTransactionCountByNumber("pending")` | Use normal RPC calls to read the latest canonical block. |
| A bridge or proof flow that reads historical block hashes or beacon roots | Re-check what it assumes about reach. The number of values kept does not change, but each one covers a tenth as much elapsed time. |
The practical difference is one of timing rather than shape. A preconfirmation used to arrive ahead of the block that contained it. A 200ms canonical block arrives at the same cadence but already settled, so the read you make after migrating is a read of committed state.
## How far back history reaches
The last row of that table is the one most likely to be missed, because nothing about it looks like a Flashblocks integration and nothing in the affected code has to change to break.
Onchain history is retained by count, not by duration. The EIP-2935 ring buffer holds `8191` entries, and `BLOCKHASH` reaches back `256` blocks. Neither figure moves at Denim. What moves is how much time those fixed counts represent, and since blocks arrive ten times more often, each window contracts by the same factor:
| Window | Before Denim | After Denim |
|---|---|---|
| `BLOCKHASH`, 256 blocks | about 8.5 minutes | about 51 seconds |
| EIP-2935 history buffer, 8191 blocks | about 4.5 hours | about 27 minutes |
Audit any flow that fetches a historical block hash or beacon root and ask how long it takes end to end, including the parts you do not control: a user signing, an operator batching, a relay waiting on L1 confirmation. A step that took twenty minutes was well inside a four-and-a-half-hour buffer and sits outside a twenty-seven-minute one. Where a flow cannot be made faster, capture the hash or root at the time of use and carry it through, rather than looking it up again once the work completes.
## Try it on Vibenet
Point your migrated integration at [Vibenet](/introduction/connecting-to-base/) and exercise it there. For the protocol design behind the change, along with the RPC behaviour it produces, see [Denim 200ms Native Blocks](/specifications/denim-200ms-blocks/).
---
# Flashblocks Overview
Source: https://basehub.org/flashblocks/overview/
Description: Flashblocks deliver 200ms preconfirmed sub-blocks on Base, streaming state updates 10x faster than the standard 2-second block cadence.
import { Aside } from '@astrojs/starlight/components';
Flashblocks are 200ms preconfirmed sub-blocks streamed by the Base sequencer, giving applications fee-ordered state updates ten times per standard 2-second block.
## What are Flashblocks
Flashblocks add **200ms** incremental state updates to Base, cutting perceived latency for end users.
The mechanism, built with [Flashbots](https://www.flashbots.net/), streams sub-blocks inside the regular 2-second block interval. Apps see preconfirmations from the sequencer well before the full block is gossiped to the network.
### Key concepts
| Term | Definition |
|------|------------|
| **Flashblock** | A 200ms sub-block carrying part of the full block's transactions. |
| **Preconfirmation** | An ultra-fast signal that a transaction will be included, before the full block is sealed. |
| **Full Block** | A sequence of 10 Flashblocks combined into the complete 2-second block. |
Each block contains **10 Flashblocks** (indexes 1-10), arriving every 200ms. Index 0 exists but only carries system transactions. See [Gas and transaction sizing](/flashblocks/app-integration/#gas--transaction-sizing) for how the gas budget evolves across the window.
## Architecture
For details on the sequencer system and the Flashblocks infrastructure components (rollup-boost, base-builder, websocket-proxy, and base), see the [Architecture](/flashblocks/architecture/) page.
## Transaction lifecycle
When a transaction is sent to Base, this is the path it takes:
### 1. Submission
```
User → DNS (mainnet.base.org) → Load Balancer → Proxyd → Mempool
```
The transaction lands in the private mempool and is added to the txpool as pending.
### 2. Distribution
The mempool keeps P2P connections open with execution layers (base-reth-node, base-builder), keeping all pending transactions in sync for block building.
### 3. Block building
In each 200ms loop, base-builder selects transactions using:
1. **Transaction fee** — transactions are ordered fee-first (highest first).
2. **Gas limit and remaining capacity** — Flashblock `j` may use up to `j/10` of the total block gas limit.
### 4. Block building algorithm
For each 2-second block, the builder runs:
```
FOR each flashblock j FROM 0 TO 10:
1. Wait until next 200ms window
2. Calculate available gas: (j / 10) × total_block_gas_limit
3. Sort pending transactions by fee (descending)
4. Select top transactions that fit within available gas
5. Execute transactions and update state
6. Stream flashblock to websocket-proxy
```
### 5. Preconfirmation delivery
Once a transaction is included in a Flashblock, the builder streams it to the websocket-proxy. RPC nodes subscribe to that stream, so a Flashblocks-aware RPC method (such as `eth_getTransactionReceipt`) can return preconfirmed data straight from the node's cache.
## Further reading
- [FAQ](/flashblocks/faq/) — common questions about Flashblocks.
- [Block Building](/network/block-building/) — detailed block ordering configuration.
- [Flashblocks deep dive](https://blog.base.dev/flashblocks-deep-dive) — engineering blog post with implementation details.
---
# Block Production Review
Source: https://basehub.org/getting-started/block-production-review/
Description: The halt and stall scenarios reviewers must check when a base/base pull request touches builder, execution, precompile, payload, or flashblocks publishing paths.
`base/base` keeps a dedicated review guide for changes that can stop the chain. It drives automated reviews of block-production-sensitive pull requests, and it is worth reading before you open one. A change counts as block-production-sensitive when it touches the builder, execution, precompiles, payload assembly, state root, transaction selection, metering, payload or data transport, or flashblocks publishing.
The scenarios below are the patterns already known to be dangerous — not a closed list. Analogous changes deserve the same scrutiny even when no rule names the exact code path. What reviewers are looking for is any change that can halt block production, stall payload finalization, block validator re-execution, or shut valid transactions out indefinitely.
An unmitigated change of that kind earns an inline **Critical** finding. A useful finding names five things: the triggering input, state, or config; the affected code path; the error or panic that propagates; the resulting halt or stall mode; and the mitigation or test that is missing.
## The payload and data boundary gate
Where a pull request adds, replaces, or alters any path that pushes block-production data over an I/O boundary, it has to answer the size questions below before it can be called safe. That holds even when the change is presented as a latency optimization, an encoding swap, a fallback path, or a way around an earlier size cap.
Read "data" broadly here: commit messages, responses and requests, state updates, receipts and transactions, frames, batches, flashblocks, payloads, and whole blocks all qualify. So does the full range of boundaries they travel over — external services and conductor payload commits, batcher/blob/calldata frames, database writes, HTTP handlers, gossip and RPC messages, websocket publishers, and channels that never leave the process.
Five questions have to be answered per boundary the change touches:
1. What is the ceiling at every hop downstream? Implicit ones count — whatever the queue, database, raft/consensus layer, HTTP server, RPC server, proxy, framework, or service body silently imposes.
2. What does that ceiling measure? Raw, JSON-expanded, framed, uncompressed, compressed, encoded, and serialized bytes are all different numbers.
3. At what point does the producer apply it? The check has to land early enough that no payload gets built, committed, published, or endlessly retried after passing local validation.
4. How does the code behave right at the ceiling, and one byte over? That covers retry, finalization, fallback, and whatever the operator ends up seeing.
5. What proves it? At-limit and over-limit payloads need tests or documented evidence on the real production boundary. Skipped, manual, and e2e-only tests fall short on their own — pair them with an explanation of the production limit and of why narrower coverage cannot be written.
A **Critical** finding is warranted whenever such a change leaves the downstream ceiling unidentified, applies no bound at or ahead of the production boundary, drops the sole boundary test, or arrives with neither at-limit nor over-limit coverage. Be strictest where a transport or encoding was swapped in precisely to sidestep an older cap — the replacement has a ceiling of its own, and treating it as unbounded is how a cap gets quietly traded for a stall.
## Critical scenarios
### Precompile fatal execution semantics
**Triggers.** Changes to BLS, BN254, P256, MODEXP, or Base precompiles that turn malformed, oversized, or otherwise user-controlled input from ordinary EVM halt/revert behavior into fatal `Err`, panic, or process exit behavior. Blurring `Error` against `Halt` semantics after an upstream SDK change counts too.
**Surfaces.** `crates/common/precompiles`, `crates/common/evm/src/precompiles`, precompile provider and adapter code, Reth SDK integration.
**Symptoms.** `PrecompileError::Fatal`, a non-invalid EVM error, a panic, or validator re-execution failure.
**Halt mode.** The sequencer can fail to build any block containing the transaction, and validators can wedge re-executing a block that already contains it.
**Rule.** Any semantic change to a precompile failure mode is critical unless it comes with explicit builder and validator impact analysis.
**Mitigation.** Boundary tests at max and max+1 input sizes; tests asserting exactly which behavior is fatal and which halts or reverts; block-building or re-execution coverage for user-triggerable failure inputs.
### Fatal EVM transaction execution in the builder
**Triggers.** `evm.transact` returning a non-invalid-tx error for transaction input sourced from attributes, the txpool, bundles, precompiles, or database-backed execution.
**Surfaces.** `execute_sequencer_transactions`, `execute_best_transactions`, EVM config, transaction environment conversion.
**Symptoms.** `PayloadBuilderError::EvmExecutionError`, `PayloadBuilderError::evm`, or a panic ahead of the receipt and state update.
**Halt mode.** The builder abandons the payload or flashblock attempt instead of producing a valid payload or fallback.
**Rule.** It is critical when user-controlled transaction input can produce fatal EVM errors in production builder paths.
**Mitigation.** Tests showing invalid user input gets skipped, halted, reverted, or rejected as that path requires; fatal error propagation tested only where consensus actually demands it.
### Strict derived attributes and the `no_tx_pool=true` path
**Triggers.** Derived payload attributes carrying invalid transactions, blob transactions, unrecoverable transactions, deposit account load failures, or pre-execution failures.
**Surfaces.** `execute_pre_steps`, `execute_sequencer_transactions`, payload attributes, deposit nonce loading, blob transaction checks.
**Symptoms.** `BlobTransactionRejected`, `TransactionEcRecoverFailed`, `AccountLoadFailed`, `EvmExecutionError`.
**Halt mode.** The EL rejects the derived payload. A wrong change here either halts sync and building or drifts away from proof-executor behavior.
**Rule.** Never silently skip consensus-derived invalid input unless proof-executor parity is explicitly preserved. Divergence is critical.
**Mitigation.** Tests covering `no_tx_pool=true` and `no_tx_pool=false` against the same invalid input, plus a proof-executor parity explanation for any change in strictness.
### State, provider, and finalization failures
**Triggers.** A missing parent block, a failed `state_by_block_hash`, a failed state root or trie update, a failed Isthmus withdrawals root, a missing parent beacon block root, invalid fork extra-data derivation, or inconsistent block number context.
**Surfaces.** Payload job creation, `build_payload`, `build_block`, `finalize_payload`, state provider and trie APIs.
**Symptoms.** `MissingParentBlock`, a provider error, a state-root error, `PayloadBuilderError::Other`, or invalid fields on a finalized payload.
**Halt mode.** No valid payload finalizes, and repeated failures stop block production until the underlying state, config, or fork problem is resolved.
**Rule.** Changes that widen these failures, drop context, retry incorrectly, or let an invalid payload finalize are critical.
**Mitigation.** Tests for parent, state-root, and fork-boundary errors wherever practical; error context identifying the block number, hash, and failing component; no silent fallback to an invalid state root.
### Flashblock loop, deadline, and publish failures
**Triggers.** Flashblock build errors, websocket serialization failures, a closed payload handler channel, cancellation and deadline races, or a late FCU or clock skew that yields zero flashblocks. Reordering publish against finalize belongs here as well.
**Surfaces.** `build_next_flashblock`, `finalize_payload`, `payload_tx`, the websocket publisher, the publish guard, and job deadline and cancellation code.
**Symptoms.** A flashblock build returning `Err`, `failed to publish flashblock`, a closed channel, a missing finalized payload, or a missed cancellation.
**Halt mode.** Flashblocks stop, payload finalization gets skipped or delayed, or external consumers are left with stale or missing updates.
**Rule.** It is critical when a change can stop building or publishing without finalizing a valid payload or falling back cleanly.
**Mitigation.** Cancellation race tests or explicit reasoning; tests for closed-channel and serialization behavior when that behavior changes; evidence that the final payload survives a failure on the publish path.
### Payload and data size limits across I/O boundaries
**Triggers.** Block, payload, flashblock, batch, frame, transaction, request, response, or commit data crossing an internal or external boundary that carries an explicit or implicit maximum. Serialized, compressed, uncompressed, encoded, JSON/RPC, websocket, channel, database, gossip, batcher/blob/calldata, conductor payload-commit, and external-service payloads can all outgrow the downstream limit when the code lacks preflight bounds, backpressure, chunking, or deterministic rejection before production.
**Surfaces.** Payload and flashblock serialization and publishing, `payload_tx`, conductor and payload commit APIs, gossip and RPC request bodies, batch/channel/frame encoding, `max_uncompressed_block_size`, DA limits, txpool forwarding, storage and DB writes.
**Symptoms.** Oversized message rejection, a closed connection or channel, a serialization or send failure, a downstream commit failure, retries that never progress, `BlockUncompressedSizeExceeded`.
**Halt mode.** The builder produces a payload that is locally valid but rejected downstream, fails to commit or publish it, or keeps building payloads too large to move through the production path at all.
**Rule.** Introducing a new I/O boundary, changing payload shape, swapping one transport or encoding for another, or increasing the possible serialized, encoded, or uncompressed size all have to satisfy the boundary gate above. Missing downstream max-size analysis, missing enforcement, removed boundary tests, or absent at-limit and over-limit tests are each critical.
**Mitigation.** At-limit and over-limit tests for serialized, encoded, and uncompressed sizes; commit and publish boundary tests; tests proving oversized data is rejected before it can stall production; regression coverage for fallback and finalization behavior.
### Resource starvation and transaction pool exclusion
**Triggers.** Metering data pending for every fresh transaction, DA/gas/uncompressed/state-root-gas/execution-time limits rejecting most candidates, a permanent rejection cache poisoning valid transactions, or `mark_invalid` and `mark_rejected` changes that exclude valid nonce chains.
**Surfaces.** `TxnExecutionError`, `ResourceLimits::is_tx_over_limits`, metering wait logic, `NextBestFlashblocksTxs`, the rejection cache, txpool pruning.
**Symptoms.** `MeteringDataPending`, `TransactionDASizeExceeded`, `BlockDASizeExceeded`, `DAFootprintLimitExceeded`, `TransactionGasLimitExceeded`, `BlockUncompressedSizeExceeded`, `ExecutionMeteringLimitExceeded`, or empty flashblocks despite valid transactions waiting.
**Halt mode.** The builder turns out empty or underfilled flashblocks and blocks repeatedly, or valid transactions never get included.
**Rule.** Changes that starve inclusion, permanently reject valid transactions, or convert a transient resource limit into a block-production stall are critical.
**Mitigation.** Tests separating transient from permanent rejection; metering-disabled behavior; nonce-chain behavior after a transaction is skipped; cache TTL and capacity behavior whenever either changes.
### Production panics and unchecked assumptions
**Triggers.** A new `unwrap`, `expect`, index, division, overflow, or `panic!` reachable from user input, chain data, database state, fork config, payload attributes, or runtime config.
**Surfaces.** Precompiles, transaction execution, payload assembly, state-root and fork activation, flashblocks publishing, job timing.
**Symptoms.** A panic, a crashed task, process exit, or a finalized payload that never appears.
**Halt mode.** The sequencer stops producing blocks, or validators stop progressing.
**Rule.** Any panic in a block-production-sensitive path that user or chain data can trigger is critical.
**Mitigation.** Replace it with a typed error, or demonstrate the invariant is enforced at construction. Add a regression test for the edge case that triggers it.
## Review checklist
When a pull request touches a block-production-sensitive path:
1. Establish whether the code can execute during building, finalization, publishing, or re-execution of a block.
2. Follow each error conversion, cancellation, timeout, channel send, `panic!`, `expect`, `unwrap`, `map_err`, and `?` the branch adds or alters.
3. Ask what sits upstream of each one: client and network behavior, runtime config, fork config, provider or DB state, chain data, payload attributes, or a transaction a user submitted.
4. Where a new or altered boundary carries this data, run the gate above and require both the downstream ceiling analysis and coverage on either side of it.
5. Satisfy yourself that one of three things holds — a valid payload comes out, it is rejected on purpose without breaking consensus or proof parity, or the failure degrades something other than finalization.
6. Request tests aimed at the boundary inputs, and separate ones per mode when txpool-driven building and derived attributes diverge.
Absent enough context to demonstrate that a path cannot halt or stall production, ask for the analysis or the tests in a **Critical** finding rather than assuming the best.
For the test tiers and CI stages these requirements plug into, see [Testing](/getting-started/testing/). The [June 2026 block production outage](/architecture/june-2026-block-production-outage/) is a worked example of what this guide exists to prevent.
---
# Building from Source
Source: https://basehub.org/getting-started/building/
Description: Clone the base/base repository and compile binaries with Just recipes or Cargo.
Building `base/base` from source means cloning the repository and compiling one or more workspace targets with Just or Cargo. Install all [prerequisites](/getting-started/prerequisites/) before continuing.
## Clone the Repository
```bash
git clone https://github.com/base/base.git
cd base
```
## How the Build Recipes Are Organised
Build work sits in a Just module rather than in top-level recipes. You reach it by naming the module first, then the recipe:
```bash
just build release
```
Running `just build` on its own prints the recipe list instead of compiling anything. That is the module default. To see what is available:
```bash
just build
```
## Standard Release Build
This is the usual command. It produces an optimized binary for every binary target in the workspace:
```bash
just build release
```
It wraps `cargo build --workspace --release`, and the results land in `target/release/`.
`release` is the profile you want for day-to-day work, and it is what `docker-bake.hcl` falls back to when nothing sets `PROFILE`. The workspace also keeps `maxperf`, which inherits `release` and then switches to fat LTO with a single codegen unit. Base reserves it for the artifacts it publishes, so reaching for it locally mostly buys you a much longer compile. Every profile is listed under [build profiles](/node-operations/configuration/#build-profiles).
## Building Individual Targets
To compile only the node binary:
```bash
just build node
```
Be aware that this recipe is a debug build — it maps to `cargo build --bin base-reth-node` with no profile flag. For an optimized single binary, call Cargo yourself:
```bash
cargo build --release --bin base-reth-node
```
That writes to `target/release/base-reth-node`.
## Building Solidity Test Contracts
Some crates need compiled Solidity contracts before their tests will run. Build them with:
```bash
just build contracts
```
The recipe changes into `crates/utilities/test-utils/contracts`, pulls dependencies with `forge soldeer install`, and runs `forge build`. [Foundry](/getting-started/prerequisites/#foundry) must be installed first.
## Debug Build (All Targets)
For an unoptimized build of every target in the workspace, including tests and benches:
```bash
just build all-targets
```
This one depends on `contracts` and `elfs`, so both are built for you first. Compilation is much quicker than a release build and the binaries are correspondingly slower. Reach for it while iterating.
## CI-Profile Builds
Two recipes mirror what continuous integration does. Both use the `ci` profile, which is tuned for fast GitHub Actions runs and small `target` directories:
```bash
# Every target in the workspace
just build ci
# Only the crates affected by your branch
just build affected-ci
```
`affected-ci` compares against `main` by default. Pass another ref to compare against it instead — `just build affected-ci origin/develop`. When nothing is affected it reports so and exits without building.
## SP1 ELF Builds
Proving work needs its SP1 ELFs compiled:
```bash
just build elfs
```
This delegates to `just succinct build-elfs`.
## Build Artifacts
| Command | Profile | Output |
|---|---|---|
| `just build release` | release | `target/release/*` |
| `just build node` | debug | `target/debug/base-reth-node` |
| `just build all-targets` | debug | `target/debug/*` |
| `just build ci` | ci | `target/ci/*` |
| `just build affected-ci` | ci | `target/ci/*` (affected crates only) |
| `just build contracts` | N/A (Foundry) | Solidity artifacts in `crates/utilities/test-utils/contracts/out/` |
| `just build elfs` | N/A (SP1) | Compiled SP1 ELFs |
## Troubleshooting
**Linker errors mentioning `clang` or `llvm`** -- Install `libclang-dev` (Debian/Ubuntu) or make sure Xcode Command Line Tools are installed (macOS).
**Out of memory during linking** -- Release builds use link-time optimization, which can consume a lot of RAM. Close other memory-heavy applications or add swap space. You can also reduce parallelism:
```bash
CARGO_BUILD_JOBS=2 just build release
```
**Stale Solidity artifacts** -- If contract tests fail after pulling new changes, re-run `just build contracts` to recompile.
**`just build` did nothing** -- That prints the module's recipe list. Name a recipe after it, such as `just build release`.
Once the build completes, continue to [Running the Node](/getting-started/running/) or [Docker Builds](/getting-started/docker/).
---
# Development Workflow
Source: https://basehub.org/getting-started/development/
Description: Run the check, test, fix, and CI Just recipes used day-to-day on base/base.
The `base/base` repository drives day-to-day development through [Just](https://github.com/casey/just) recipes for checking, testing, formatting, and CI parity. The recipes below cover the commands you will run most often.
## Quick Reference
| Command | What it does |
|---|---|
| `just check` | Lists the individual `check::*` static-check recipes |
| `just check::all` | Runs the full static-check suite (format, clippy, udeps, deny) |
| `just test` | Runs the test suite via cargo-nextest |
| `just fix` | Auto-fixes formatting, clippy, and zepter issues |
| `just ci` | Full local gate (fix, checks, tests, lychee, zepter, no-std checks) |
| `just pr` | Same as `just ci`, but with tests scoped to affected crates |
## Running Tests
The project uses [cargo-nextest](https://nexte.st/) as its test runner. Install it if you have not already:
```bash
cargo install cargo-nextest
```
Run the full test suite:
```bash
just test
```
This executes `cargo nextest` with all features enabled. The devnet tests are excluded by default since they require a running Docker Compose stack.
To run tests for a specific crate:
```bash
cargo nextest run -p base-execution-evm
```
To run a single test by name:
```bash
cargo nextest run -p base-execution-evm -- test_name
```
### Building Test Contracts
Some tests depend on compiled Solidity contracts. If you see test failures related to missing contract artifacts, build them first:
```bash
just build contracts
```
See [Building from Source](/getting-started/building/#building-solidity-test-contracts) for details.
## Checking Code Quality
The static checks live in a `check` module, so each one is addressed as `check::`. Running the module on its own lists what is available:
```bash
just check
```
To run the whole static-check suite at once:
```bash
just check::all
```
That expands to these four, in order:
1. **`check::format`** -- Verifies that all Rust source files match `rustfmt` style.
2. **`check::clippy`** -- Runs Clippy with the project's configured lints.
3. **`check::udeps`** -- Detects unused dependencies in `Cargo.toml` files.
4. **`check::deny`** -- Checks dependencies for known vulnerabilities and license issues via `cargo-deny`.
Note that the test suite is *not* part of `check::all` -- it is a separate step, run on its own or as part of `just ci`. Two further checks, `check::no-std` and `check::no-std-proof`, sit outside `check::all` as well and are invoked directly by the CI recipes.
If any step fails, the pipeline stops. Fix the issue and re-run.
## Auto-Fixing Issues
Most formatting and lint issues can be fixed automatically:
```bash
just fix
```
This runs three fixers in sequence:
1. **`format-fix`** -- Applies `rustfmt` to all source files.
2. **`clippy-fix`** -- Applies Clippy's suggested fixes.
3. **`zepter-fix`** -- Fixes feature propagation issues detected by [zepter](https://github.com/nicknisi/zepter).
Run `just fix` before committing to avoid CI failures.
## Full CI Pipeline
To run the same gate the merge queue will ultimately enforce:
```bash
just ci
```
This encompasses:
1. `fix` -- auto-fix everything fixable
2. `check::all` -- the static-check quality gate
3. `test` -- the full workspace test suite
4. `lychee` -- checks for broken links in documentation
5. `zepter` -- validates Cargo feature propagation
6. `check::no-std` and `check::no-std-proof` -- ensure `no_std` compatibility for the crates that require it, including the bare-metal proof crates
For faster iteration there is `just pr`, which runs the same checks but swaps the full test suite for `test-affected`, limiting tests to the crates your branch changes relative to `main`:
```bash
just pr
```
Use `just pr` while iterating and `just ci` before requesting review. See [Testing](/getting-started/testing/) for the tiers those tests are drawn from and how each CI stage differs.
## Formatting
Check formatting without modifying files:
```bash
just check::format
```
Auto-format all files:
```bash
just format-fix
```
The project uses the standard `rustfmt` configuration. If your editor supports format-on-save with `rustfmt`, enable it for a smoother workflow.
## Clippy
Run Clippy to catch common mistakes and non-idiomatic patterns:
```bash
just check::clippy
```
Apply Clippy's suggestions automatically:
```bash
just clippy-fix
```
## Recommended Editor Setup
For the best development experience, configure your editor with:
- **rust-analyzer** -- Provides inline type hints, go-to-definition, and real-time diagnostics.
- **Format on save** -- Set your editor to run `rustfmt` whenever you save a `.rs` file.
- **Clippy as the check command** -- Configure rust-analyzer to use `clippy` instead of `cargo check` for richer diagnostics:
```json
{
"rust-analyzer.check.command": "clippy"
}
```
## Next Steps
- [Testing](/getting-started/testing/) -- the four testing tiers and what each CI stage runs.
- [Local Devnet](/getting-started/devnet/) -- run a full local network for integration testing.
- [Contributing](/contributing/) -- guidelines for submitting pull requests.
---
# Local Devnet
Source: https://basehub.org/getting-started/devnet/
Description: Run Base locally from base/base, either as a throwaway Docker network that crosses every hardfork in its first blocks, or as a snapshot dev chain that continues real Mainnet state.
The `base/base` repository ships a Docker devnet that brings up the whole Base stack locally: an L1 made of Reth and Lighthouse, a Base sequencer, two RPC nodes, and a batcher. A shadow batcher and shadow validator run alongside it so the Rust batcher gets exercised too. It is the place to try contracts, apps, and node or hardfork changes when you do not want a public network involved.
There is also a [snapshot dev chain](#snapshot-dev-chain-base-dev) that picks up from real Base Mainnet or Sepolia state instead of a fresh genesis. The table further down helps you choose.
If you only need to build against new Base features and have no interest in running infrastructure, the hosted Vibenet is the lighter option.
:::caution
Treat the devnet as disposable. `just devnet up`, `just devnet up-single`, and `just devnet down` all wipe the chain data in `.devnet/`. The stack also binds its ports on every interface, so keep it on an isolated development machine.
:::
## Prerequisites
You need the following before the first start:
- [Docker](/getting-started/prerequisites/#docker-optional) with Compose v2 and Buildx. The first build compiles the Rust services, so give Docker plenty of memory.
- [`just`](https://github.com/casey/just) `1.51.0` or newer.
- [Foundry](https://getfoundry.sh), for `cast`.
- [`jq`](https://jqlang.org), which `just devnet status` and `just devnet checks` rely on.
- A clone of `base/base` with the other [prerequisites](/getting-started/prerequisites/) in place.
### Pre-Pulling Images
To shorten the first start, build the setup image and pull the L1 images ahead of time:
```bash
just devnet pull-images
```
## Starting the Devnet
The devnet commands live in a `just` module, so each one is written `just devnet `. Running `just devnet` on its own only prints the list.
Run this from the root of the repo:
```bash
just devnet up-single
```
It shuts down any devnet that is already running, clears the old data, builds fresh images, and starts a stack with one sequencer. Expect the first run to take several minutes while the Rust services compile.
| Command | Starts |
| --- | --- |
| `just devnet up-single` | One sequencer. The quickest choice for most testing. |
| `just devnet up` | A 3-node high-availability sequencer cluster with conductor. |
Confirm that blocks are being produced:
```bash
just devnet status
```
## Stopping the Devnet
```bash
just devnet down
```
This removes the containers and deletes everything under `.devnet/`, so the next start is clean.
## Sending a Test Transaction
The standard Foundry/Anvil test accounts are funded at genesis. Their addresses and keys are in `etc/docker/devnet-env`. This sends a little ETH through the sequencer:
```bash
source etc/docker/devnet-env
cast send "$ANVIL_ACCOUNT_2_ADDR" --value 0.001ether \
--private-key "$ANVIL_ACCOUNT_1_KEY" \
--rpc-url http://127.0.0.1:7545
```
A receipt showing `status 1` means the sequencer took the transaction into a block. For a canned set of L1 and L2 checks, run `just devnet checks` instead.
:::danger
These test keys are public knowledge. Do not use them on Mainnet or Sepolia.
:::
## Endpoints
| Service | URL | Chain ID |
| --- | --- | --- |
| L2 sequencer (builder) RPC | `http://127.0.0.1:7545` | `84538453` |
| L2 RPC node | `http://127.0.0.1:8545` | `84538453` |
| L2 RPC node (`base-rpc`) | `http://127.0.0.1:8645` | `84538453` |
| L1 RPC | `http://127.0.0.1:4545` | `1337` |
| Grafana | `http://localhost:3000/d/devnet-overview` | |
All ports come from `etc/docker/devnet-env`. With `just devnet up`, port `7545` is only one of three sequencers that conductor manages. If leadership moves, a transaction sent there can sit pending. Send through the RPC node on `8545` instead, because it forwards to whichever sequencer currently leads.
## Hardfork Activation
A fresh devnet crosses every scheduled upgrade almost at once. Azul activates at L2 block 20, Beryl at 21, Cobalt at 22, and Denim at 25. Blocks come every 2 seconds until Denim, and then the sequencer drops to 200ms blocks.
Two optional modes add the unscheduled forks:
| Command | Also activates |
| --- | --- |
| `just devnet up-single everest` | Everest ([Base Transactions](/specifications/base-transactions/), type `0x79`) at block 100 |
| `just devnet up-single zenith` | Everest and Zenith at block 100 |
:::caution
The canonical batcher in the devnet (`op-batcher`) does not understand Base Transactions (EIP-8430, type `0x79`; the node code still calls them EIP-8130). As soon as one lands in a block, that batcher stops moving forward and the canonical safe head stalls. The shadow `base-batcher` handles the type, so the shadow validator keeps deriving past those blocks.
:::
Each activation reads from an `L2_BASE__BLOCK` variable, such as `L2_BASE_DENIM_BLOCK`. Set it before `up` or `up-single` to move that fork. An empty value leaves the fork unscheduled.
## Common Commands
| Command | Does |
| --- | --- |
| `just devnet status` | Prints block numbers and sync status |
| `just devnet accounts` | Lists funded test accounts with balances and nonces |
| `just devnet smoke` | Sends test transactions to L1 and L2 |
| `just devnet checks` | Runs `status` and then `smoke` |
| `just devnet logs [containers]` | Streams logs, for all containers or the ones you name |
| `just devnet ps` | Shows container status |
| `just devnet flashblocks` | Streams Flashblocks from the builder until Denim (block 25 by default). Nothing arrives after Denim. Needs Go; the first run installs the client and can exit silently, so run it a second time. |
| `just devnet profiling` | Restarts the devnet with Pyroscope and optimized profiling builds |
| `just devnet tests` | Runs the system tests against the devnet |
| `just devnet down` | Stops the devnet and deletes its data |
The devnet README in `etc/docker/README.md` and the recipes in `etc/docker/Justfile` are the full reference. They also cover the Anvil + Nitro proving variant and upgrade-signal testing.
### Load Testing
The load generator is a separate module that targets the devnet by default:
```bash
just load-test-continuous
```
### Proving
No prover runs inside the devnet. To prove against it, start the separate [standalone proving](/node-operations/standalone-proving/) stack. ZK proving against a local devnet only works with Beryl and Cobalt turned off.
## Snapshot Dev Chain (`base dev`)
:::note
`base dev` is on `main` only. No release ships it yet. The final `v1.5.0` (2026-10-14) does not include it, so build from a `main` checkout.
:::
There is a second, lighter way to get a local chain. `base dev` takes a copy of a real snapshot and keeps producing blocks on top of it, with no L1 behind it. One process holds both an embedded execution node and a standalone sequencer, talking over Engine IPC. Contracts, balances, and storage start out exactly as they were on the network at the snapshot head.
### Picking Between the Two
| | Docker devnet | Snapshot dev chain |
| --- | --- | --- |
| Starting state | A fresh genesis | Base Mainnet or Sepolia at the snapshot head |
| Good for | Sequencing, derivation, batching, fork activation, HA failover | Real deployed contracts and liquidity, acting as any account, 200ms blocks |
| Out of reach | Mainnet contracts and state | L1 derivation, bridges, safe and finalized heads, proofs |
| Needs | Docker | A native Rust build and at least 1.5 TB of free disk; no Docker |
| First start | Several minutes of image builds | About an hour of download, then a one-time index rebuild |
Pick the Docker devnet when the test touches node behavior or L1. Pick `base dev` when you want your app to meet the same contracts it will see on Mainnet.
### Requirements
On top of `just`, Foundry, and `jq`, the recipes compile `base` with Cargo, so you need:
- The Rust toolchain pinned in `rust-toolchain.toml` (through [rustup](https://rustup.rs)), Go, a C/C++ compiler, libclang, OpenSSL development headers, `pkg-config`, CMake, and `protoc`.
- At least 1.5 TB free, ideally on fast NVMe. A Base Mainnet download in October 2026 came to about 830 GiB and unpacked to about 1.4 TB. Upstream has only tested the flow on Linux.
### Download and Run
```bash
just devnet snapshot download --dir "$HOME/data/my-devnet"
just devnet snapshot run --dir "$HOME/data/my-devnet"
```
`download` only fetches data and writes a node config into the directory. It does not start anything. Add `--print-plan-json` to list the exact archives and sizes first. If the transfer breaks off, run the same command again and verified archives are reused. Add `--manifest-url ` to stay on one specific snapshot across a resume.
The download keeps 1,339,200 blocks of transactions, receipts, and state history, which covers about 31 days of 2-second blocks. The `--full` preset keeps 13,392,000 blocks instead. That is 31 days only once blocks are 200ms, and about 310 days today, so a Mainnet `--full` pull is about 1.9 TB and unpacks to about 3.7 TB.
`run` builds `base`, prints the endpoints and the snapshot head, and stays in the foreground. The snapshot ships without the transaction and history indexes, so the first `run` rebuilds them. RPC calls work within seconds, but no new blocks appear until the rebuild ends. Upstream measured about 22 minutes for a Mainnet snapshot. Later starts begin sequencing almost at once.
What else to expect:
- It never creates, downloads, or resets data on its own. `run` only continues a datadir that already exists.
- Peers and discovery are off. HTTP RPC listens on `http://127.0.0.1:8545` and WS on `ws://127.0.0.1:8546`, with the `eth_*`, `debug_*`, and `trace_*` methods. `--http.port` and `--ws.port` move them.
- The chain ID stays the snapshot's own: `8453` for Mainnet, `84532` for Sepolia.
- If the snapshot head is from before Denim, Denim activates on the next block. The schedule and starting head are written to `base-dev.json` in the datadir and reused after a restart.
- Ctrl+C stops it, and the same command resumes it. Downtime does not create catch-up blocks.
For Sepolia, select the chain on both steps. Note that `download` refuses the `BASE_CHAIN` variable and takes its own `--chain` flag:
```bash
env -u BASE_CHAIN just devnet snapshot download --chain sepolia --dir "$HOME/data/sepolia-devnet"
BASE_CHAIN=sepolia just devnet snapshot run --dir "$HOME/data/sepolia-devnet"
```
:::danger
Use a throwaway copy. Never point `base dev` at a live node's datadir or at your only Mainnet copy. Once development blocks exist, the data has left Mainnet for good, and deleting `base-dev.json` does not reverse it. Only a clean backup does. For the same reason, never run `download` again into a directory that has already made dev blocks.
:::
### Block Timing
Blocks come every 200ms, but header timestamps only count whole seconds, so roughly five blocks in a row share one timestamp. Code that counts blocks sees time run ten times faster than on a 2-second chain. Code that reads `block.timestamp` sees normal time. A busy disk or CPU can make blocks late.
### `dev_impersonateTransaction`
`base dev` adds one RPC method that runs a call as any account without its key. It is handy for funding accounts, moving tokens out of real holders, or calling owner-only functions:
```text
dev_impersonateTransaction({from, to?, input?, value?, gas, mint?}) -> txHash
```
- `from` and `gas` are required. `input` defaults to empty, and `value` and `mint` default to zero. `mint` wei is credited to `from` before the call runs. Leave out `to` to deploy a contract from `input`.
- The request becomes a deposit transaction. Signature, nonce, and fee checks are skipped, and no fee is paid. Checks that live inside contracts, such as `ecrecover`, EIP-1271, or `permit`, still run. Use signed transactions when you want to test admission or fees.
- The receipt has type `0x7e`, an `effectiveGasPrice` of zero, and `from` set to the impersonated account. Each request bumps that account's nonce.
- The returned hash only means the request is queued. It normally lands in the next block, about 200ms later. Poll `eth_getTransactionReceipt` rather than sending again, because a repeat is a second transaction. A reverting call still lands, with status `0`, and any minted ETH stays. Queued requests live in memory and vanish if the process stops.
A quick way to fund a fresh key with 1 ETH:
```bash
RPC=http://127.0.0.1:8545
DEV_KEY=$(cast wallet new --json | jq -er '(if type == "array" then . else .data end)[0].private_key')
ACCOUNT=$(cast wallet address --private-key "$DEV_KEY")
cast rpc --rpc-url "$RPC" dev_impersonateTransaction \
"{\"from\":\"$ACCOUNT\",\"to\":\"$ACCOUNT\",\"gas\":\"0x5208\",\"mint\":\"0xde0b6b3a7640000\"}"
```
| Error code | Meaning |
| --- | --- |
| `-32602` | Bad request: `from` or `gas` missing, gas under the intrinsic cost or above the block gas limit minus 2,000,000, calldata over 131,072 bytes, or init code over 49,152 bytes |
| `-32000` | Try again later: sequencing has not started (for example during the first-run rebuild), or 256 requests are already waiting |
:::caution
The receipt's `contractAddress` is wrong for a contract deployed this way. It shows the address for nonce zero. The code actually lands at the address derived from the sender's nonce before the request. Read that nonce with `cast nonce` first, then get the address with `cast compute-address --nonce `.
:::
:::caution
Because impersonation can act as any account, keep the dev RPC endpoints private. The chain also keeps its real chain ID, so anything you sign here is valid on that network too. Act as real accounts through impersonation, and sign only with throwaway keys.
:::
## Troubleshooting
**Containers fail to start.** Check that Docker is running and that your user belongs to the `docker` group. `docker compose version` confirms the Compose plugin is present.
**Port conflicts.** Stop whatever else holds the port, or change the value in `etc/docker/devnet-env`.
**Stale state.** If behavior looks wrong after a code change, run `just devnet up-single` again. It always clears data before it starts.
**Slow first start.** The first run pulls images and compiles the Rust services. Running `just devnet pull-images` beforehand saves part of that wait.
**Transactions pending in HA mode.** After a leader change, send through `8545` rather than `7545`.
---
# Docker Builds
Source: https://basehub.org/getting-started/docker/
Description: Build and run base/base from the Dockerfiles under etc/docker without installing Rust on the host.
Docker builds compile `base/base` reproducibly without a host Rust toolchain. The repository ships several Dockerfiles under `etc/docker/` for the client, builder, devnet, and websocket proxy.
## Available Dockerfiles
| File | Purpose |
|---|---|
| `etc/docker/Dockerfile.client` | Production client image containing `base-reth-node` |
| `etc/docker/Dockerfile.builder` | Builder image used as a base for multi-stage builds |
| `etc/docker/Dockerfile.devnet` | Devnet-specific image for local development networks |
| `etc/docker/Dockerfile.websocket-proxy` | Standalone websocket proxy image |
## Building the Client Image
From the repository root, build the production client image:
```bash
docker build -t base-reth-node -f etc/docker/Dockerfile.client .
```
This performs a multi-stage build: it compiles the Rust binary inside a builder container and copies the resulting binary into a minimal runtime image. The build context is the repository root, so all workspace crates are available to the compiler.
Depending on your hardware, the first build may take 15-30 minutes. Subsequent builds benefit from Docker layer caching.
## Running the Container
Start the node with default settings:
```bash
docker run -it --rm base-reth-node
```
Pass CLI options after the image name, exactly as you would with the bare binary:
```bash
docker run -it --rm base-reth-node --help
```
### Persisting Data
By default, a container's filesystem is ephemeral. To persist chain data across restarts, mount a host directory to the node's data directory:
```bash
docker run -it --rm \
-v /path/to/data:/data \
base-reth-node \
--datadir /data
```
### Exposing Ports
The node exposes several network ports. Map them to the host as needed:
```bash
docker run -it --rm \
-v /path/to/data:/data \
-p 8545:8545 \
-p 8546:8546 \
-p 30303:30303 \
-p 30303:30303/udp \
base-reth-node \
--datadir /data \
--http \
--http.addr 0.0.0.0 \
--ws \
--ws.addr 0.0.0.0
```
| Port | Protocol | Service |
|---|---|---|
| 8545 | TCP | HTTP JSON-RPC |
| 8546 | TCP | WebSocket JSON-RPC |
| 30303 | TCP + UDP | P2P discovery and communication |
### Running in the Background
Use `-d` instead of `-it` to run detached:
```bash
docker run -d --name base-node \
-v /path/to/data:/data \
-p 8545:8545 \
base-reth-node \
--datadir /data \
--http --http.addr 0.0.0.0
# View logs
docker logs -f base-node
# Stop
docker stop base-node
```
## Building Other Images
Build the websocket proxy image:
```bash
docker build -t base-websocket-proxy -f etc/docker/Dockerfile.websocket-proxy .
```
Build the devnet image (typically used by the docker-compose devnet stack rather than run directly):
```bash
docker build -t base-devnet -f etc/docker/Dockerfile.devnet .
```
## Tips
- **Layer caching**: The Dockerfiles are structured so that dependency fetching is cached separately from source compilation. If you only change Rust source files, the dependency layers are reused.
- **BuildKit**: Enable BuildKit for faster builds: `DOCKER_BUILDKIT=1 docker build ...`
- **Cross-compilation**: If you need an `amd64` image on an ARM host (or vice versa), use `docker buildx build --platform linux/amd64 ...`.
For running a full local devnet with Docker Compose, see [Local Devnet](/getting-started/devnet/). For production Docker deployments, see [Node Operations: Docker](/node-operations/docker/).
---
# Prerequisites
Source: https://basehub.org/getting-started/prerequisites/
Description: Install Rust, Just, Foundry, build essentials, and optionally Docker before working on base/base.
Building or developing on `base/base` requires Rust, Just, Foundry, a C/C++ toolchain, and optionally Docker. Instructions below target Linux (Debian/Ubuntu); macOS users can substitute `brew install` where applicable.
## Rust
The project requires **Rust 1.88 or later**. The recommended way to install and manage Rust toolchains is through [rustup](https://rustup.rs/):
```bash
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
```
Follow the on-screen prompts and then reload your shell:
```bash
source "$HOME/.cargo/env"
```
Verify the installed version:
```bash
rustc --version
# rustc 1.88.0 (or later)
```
If you already have Rust installed, make sure it is up to date:
```bash
rustup update
```
## Just
[Just](https://github.com/casey/just) is a command runner used throughout the project for build, test, and devnet workflows. Install it with one of:
```bash
# Using cargo (works everywhere Rust is installed)
cargo install just
# Debian/Ubuntu
sudo apt install just
# macOS (Homebrew)
brew install just
```
Confirm the installation:
```bash
just --version
```
## Foundry
[Foundry](https://book.getfoundry.sh/) is required for compiling the Solidity test contracts used by several crates. Install via the official installer:
```bash
curl -L https://foundry.paradigm.xyz | bash
```
Then run:
```bash
foundryup
```
This gives you `forge`, `cast`, `anvil`, and `chisel`. Verify with:
```bash
forge --version
```
## Build Essentials
A standard C/C++ toolchain and a few system libraries are needed to compile native dependencies:
```bash
# Debian / Ubuntu
sudo apt update
sudo apt install -y git libclang-dev pkg-config curl build-essential
```
```bash
# macOS (Xcode Command Line Tools provide clang and related headers)
xcode-select --install
brew install pkg-config
```
## Docker (Optional)
Docker is only required if you plan to build container images or run the local devnet. Install Docker Engine by following the [official instructions](https://docs.docker.com/engine/install/) for your platform, or on Ubuntu:
```bash
sudo apt install -y docker.io
sudo systemctl enable --now docker
sudo usermod -aG docker "$USER"
```
Log out and back in for the group change to take effect, then verify:
```bash
docker --version
docker compose version
```
The devnet uses Docker Compose (the `docker compose` plugin, not the legacy `docker-compose` binary).
## Quick Check
Once everything is installed, you can run a quick sanity check from the repository root:
```bash
rustc --version && cargo --version && just --version && forge --version && git --version
```
All five commands should succeed and print version information. With these prerequisites in place, proceed to [Building from Source](/getting-started/building/).
---
# Running the Node
Source: https://basehub.org/getting-started/running/
Description: Start the base-reth-node binary, configure RPC and metrics, and shut down cleanly.
The `base-reth-node` binary starts the Base L2 execution client once you have a [source build](/getting-started/building/) or [Docker image](/getting-started/docker/). For production guidance, see [Node Operations](/node-operations/deployment/).
## Starting the Node
Run the binary directly from the build output directory:
```bash
./target/release/base-reth-node
```
That path assumes a release build. `just build node` is a debug build instead, so its binary sits elsewhere:
```bash
./target/debug/base-reth-node
```
The node will begin syncing from the network. On the first run it creates a data directory (by default `~/.local/share/reth/` on Linux, `~/Library/Application Support/reth/` on macOS) and starts downloading blocks.
## CLI Help
View all available options and subcommands:
```bash
./target/release/base-reth-node --help
```
This prints the full help text including every flag, option, and subcommand. It is the definitive reference for the CLI and is always in sync with the version you built.
## Common Options
### Data Directory
Override the default data directory:
```bash
./target/release/base-reth-node --datadir /mnt/ssd/base-node
```
### HTTP JSON-RPC
Enable the HTTP JSON-RPC server:
```bash
./target/release/base-reth-node \
--http \
--http.addr 127.0.0.1 \
--http.port 8545
```
By default the server only listens on localhost. Set `--http.addr 0.0.0.0` to accept connections from other machines (make sure your firewall is configured appropriately).
### WebSocket JSON-RPC
Enable the WebSocket server alongside (or instead of) HTTP:
```bash
./target/release/base-reth-node \
--ws \
--ws.addr 127.0.0.1 \
--ws.port 8546
```
### Logging
Control log verbosity with the `-v` flag (can be repeated) or the `RUST_LOG` environment variable:
```bash
# Increase verbosity
./target/release/base-reth-node -vvv
# Fine-grained control via RUST_LOG
RUST_LOG=info,reth=debug ./target/release/base-reth-node
```
### Metrics
Enable the Prometheus metrics endpoint:
```bash
./target/release/base-reth-node \
--metrics 127.0.0.1:9001
```
Point your Prometheus instance at `http://:9001/metrics` to scrape node metrics.
## Example: Full Node with RPC
A typical invocation that enables both HTTP and WebSocket RPC, metrics, and stores data on a dedicated volume:
```bash
./target/release/base-reth-node \
--datadir /data/base-node \
--http \
--http.addr 0.0.0.0 \
--http.port 8545 \
--ws \
--ws.addr 0.0.0.0 \
--ws.port 8546 \
--metrics 0.0.0.0:9001 \
-vv
```
## Enabling Flashblocks
A synced node can serve ~200ms pre-confirmations to your applications once it is subscribed to the Flashblocks stream. Point the node at the Flashblocks WebSocket feed with `RETH_FB_WEBSOCKET_URL` when you launch it:
```bash
RETH_FB_WEBSOCKET_URL="wss://mainnet.flashblocks.base.org/ws" ./target/release/base-reth-node
```
| Network | URL |
|---------|-----|
| Mainnet | `wss://mainnet.flashblocks.base.org/ws` |
| Sepolia | `wss://sepolia.flashblocks.base.org/ws` |
These WebSocket URLs are part of the node infrastructure and are not meant for direct use by applications — your own RPC endpoint is what apps should query for Flashblocks data. The binary tails this stream, caches the pre-confirmation data, and replies from that cache when a Flashblocks-aware RPC method is called. The full message schema is documented in the [Flashblocks API Overview](/api-reference/flashblocks/overview/).
To confirm it is working, request a `pending` block:
```bash
curl -X POST \
--data '{"jsonrpc":"2.0","method":"eth_getBlockByNumber","params":["pending", false],"id":1}' \
http://localhost:8545
```
A working setup returns data from the most recent Flashblock; if the stream is briefly unavailable the node falls back to the latest finalized block.
## Historical Proofs RPCs
Serving `eth_getProof`, `debug_executionWitness`, and `debug_executePayload` at scale requires the historical proofs execution extension (ExEx), which maintains a dedicated database of the state those methods need. That database can grow by hundreds of gigabytes and wants a host with strong I/O, so enable it only if you actually need these endpoints — most operators do not.
The official execution entrypoint needs two environment variables to turn the ExEx on. It checks both, and if the storage path is empty it quietly starts the node without the ExEx:
```bash
RETH_HISTORICAL_PROOFS=true
RETH_HISTORICAL_PROOFS_STORAGE_PATH=
```
With both set, the entrypoint runs the idempotent `proofs init` step and then starts the node with `--proofs-history --proofs-history.storage-path=`. The first start backfills existing state into that proofs database, which takes roughly 24-48 hours on mainnet. You can skip it entirely by [restoring a proofs snapshot](/node-operations/snapshots/#proofs-snapshots).
The earliest block these RPCs can answer for is whichever block the ExEx first ran from. When the ExEx is active the `--rpc.eth-proof-window` flag has no effect.
Retention is set by `--proofs-history.window` (alias `--proofs.window`), counted in blocks rather than days. Because it is a block count, the time it covers depends on block time:
| Build | Default window | At 2s blocks | At 200ms blocks |
| --- | --- | --- | --- |
| `v1.4.2` and earlier | `1296000` | 30 days | 3 days |
| `v1.5.0` and later (#5362) | `6480000` | 150 days | 15 days |
The new default is sized for [200ms blocks under Denim](/specifications/denim-200ms-blocks/). Until Denim activates, a node on the new default keeps five times as much history as before, so plan disk for that or set the window yourself. The same change lowers the minimum from just over 12 hours of 2s blocks to a single block.
The entrypoint has no variable of its own for the window, and the `RETH_PROOFS_HISTORY_WINDOW` variable that some guides mention is not read by it. To set the flag through the official image, append it to `RETH_PRUNING_ARGS`, which the entrypoint passes through to the node unchanged.
The ExEx is fastest when it stays within 1024 blocks of the chain tip, so performance suffers while syncing up to head, and on an initial Base Mainnet sync it can fall behind far enough that it never catches up unaided. To prevent that, run `base-consensus` in follow mode so it tracks within 512 blocks of the proofs ExEx:
```bash
BASE_NODE_SOURCE_L2_RPC=
BASE_NODE_PROOFS=true
```
When the ExEx reports state-root and execution durations of 0, it is keeping up correctly — it is not re-executing blocks, only persisting data from already-executed ones.
## Stopping the Node
Send `SIGINT` (Ctrl+C) or `SIGTERM` to gracefully shut down the node. It will flush pending state to disk before exiting. Avoid sending `SIGKILL` unless absolutely necessary, as it can leave the database in an inconsistent state requiring a repair on next startup.
## Next Steps
- [Development Workflow](/getting-started/development/) -- learn the day-to-day check, test, and fix commands.
- [Local Devnet](/getting-started/devnet/) -- spin up a full local network for integration testing.
- [Configuration](/node-operations/configuration/) -- detailed configuration reference for production deployments.
---
# Testing
Source: https://basehub.org/getting-started/testing/
Description: The four tiers of tests in base/base — unit, action, system, and fuzz — and the CI stages that run them.
Tests in `base/base` are organized into four tiers. Each step up the ladder puts more of the production system under test and costs proportionally more time to run. Knowing which tier a change belongs in is most of the work: reach for the fastest one that actually covers the behavior you changed.
For the day-to-day `just` recipes themselves, see [Development Workflow](/getting-started/development/).
## Before Opening a Pull Request
One command covers the full local gate:
```bash
just ci
```
It applies the auto-fixers first, then runs every static check and the complete unit test suite:
```
fix → check::all (format, clippy, udeps, deny) → test → lychee → zepter → check::no-std → check::no-std-proof
```
When you have only touched a handful of crates, there is a narrower variant that scopes clippy and the test run to the crates your branch actually affects, relative to `main`:
```bash
just pr
```
Both need Docker, [`just`](https://github.com/casey/just), and Foundry (`forge`) available on your machine — see [Prerequisites](/getting-started/prerequisites/).
## The Four Tiers
| Tier | Speed | Scope | Location |
|---|---|---|---|
| Unit | milliseconds | One function or type on its own | Colocated `#[cfg(test)] mod tests` blocks |
| Action | milliseconds | Real protocol logic — batching, derivation — against in-memory actors | `actions/harness` (`base-action-harness`) |
| System | minutes | The whole L1 + L2 stack under Docker/testcontainers | `etc/systems` (`base-system-tests`) |
| Fuzz | hours (nightly) | Randomized transaction streams hunting sync-parity regressions | `base-system-tests`, nightly only |
### Unit Tests
Unit tests sit in the same file as the code under test, in a `#[cfg(test)] mod tests { ... }` block placed at the end. Run the whole workspace suite with:
```bash
just test
```
Behind that recipe is `cargo nextest run --workspace --all-features --exclude base-system-tests --no-fail-fast`, preceded by a build of the test contracts and SP1 ELFs. Excluding `base-system-tests` leaves no gap. That crate carries two kinds of test — the Docker-backed integration cases and plain unit tests sitting alongside them — and [System Tests](#system-tests) below picks up both.
To limit the run to crates your branch touches:
```bash
just test-affected
```
### Action Tests
Action tests are the middle tier: an integration framework that models the L1 block producer, batcher, sequencer, and verifier as lightweight in-memory actors, drives them through a scripted list of actions, and asserts on the chain state that results. Nothing real is spun up — no nodes, no sockets, no containers — but batch encoding, channel compression, and derivation all go through the same production types they would in a live network. That combination is the point: protocol-boundary bugs that slip past unit tests get caught in milliseconds instead of minutes.
```bash
just actions test
```
Or invoke the harness crate directly:
```bash
cargo nextest run -p base-action-harness
```
The [`actions/README.md`](https://github.com/base/base/blob/main/actions/README.md) in the repository documents the actor architecture and how to add a scenario.
### System Tests
System tests bring up an isolated L1 + L2 stack with [testcontainers](https://testcontainers.com/) and drive the node end to end against real components — Reth for L1, Lighthouse, and real Base sequencer and validator processes. It is the slowest and most complete tier:
```bash
just devnet tests
```
That recipe builds the test contracts, then runs `cargo nextest run -p base-system-tests`. Docker is required.
Their cost keeps them off pull requests altogether. The merge queue runs them instead, as the required `ci / System Tests` check — and that requirement is what does the real work. A failing run blocks the merge outright, so nothing lands on `main` without clearing it.
### Fuzz Tests
A scheduled nightly job throws randomized transaction streams at the node to shake out sync-parity regressions, spreading the work over 4 parallel shards. Every shard draws its own random seed and logs it, so any failure can be replayed deterministically:
```bash
cargo nextest run -P ci -p base-system-tests --cargo-profile ci --no-capture -E 'test(fuzz_sync_parity)'
```
Neither pull requests nor the merge queue trigger it. It fires on the daily schedule at 07:00 UTC, or through a manual `workflow_dispatch` when you want to replay a particular seed.
## Static Checks
Alongside the tests, `just ci` and `just pr` run a set of static checks:
| Check | Command | Purpose |
|---|---|---|
| Format | `cargo +nightly fmt --all -- --check` | Enforces `rustfmt.toml` (2024 edition style) |
| Clippy | `cargo clippy --workspace --all-features --all-targets -- -D warnings` | Lints, warnings denied |
| Unused deps | `cargo +nightly udeps --locked --workspace --all-features --all-targets` | Flags unused `Cargo.toml` dependencies |
| Dependency bans/licenses | `cargo deny check bans --hide-inclusion-graph` | Enforces `deny.toml` — allowed licenses, banned crates, source restrictions |
| `no_std` | `etc/scripts/ci/check-no-std.sh` | Confirms `no_std` crates still build without `std` |
| `no_std` (proof) | `etc/scripts/ci/check-no-std-proof.sh` | The same, for the bare-metal FPVM proof crates |
| Feature flags | `zepter format features && zepter` | Validates Cargo feature propagation across the workspace |
| Links | `lychee --config ./lychee.toml .` | Looks for dead links repository-wide |
The docs index check is the newest of these. The manifest at `etc/docs-index.toml` holds one summary per doc, plus a digest of the doc as it was when someone last reviewed that summary. Edit a doc and the check fails until its sThe docs index check that used to sit in this list is gone (#5646). Its generated files, `llms.txt`, `llms-full.txt`, and the `etc/docs-index.toml` manifest, changed in almost every pull request that edited a Markdown file, and the resulting merge conflicts kept leaving `main` red. Upstream deleted the index, its script, and the CI step. Agents now locate docs by searching the tree, since each doc lives beside the code it covers, and the repository map moved into `CLAUDE.md`.hat is possible.
## CI Stages
Which checks run depends on where a change sits in its lifecycle:
| Stage | Trigger | Workflow | Scope |
|---|---|---|---|
| Pull request | `pull_request` | `ci-pr.yml` → `ci-core.yml` | Build/clippy/test, **affected crates only** vs. the base branch |
| Pull request | `pull_request` | `no-std.yml`, `zepter.yml`, `lychee.yml`, `action-tests.yml`, `base-std-fork-tests.yml` | Full workspace — these are already fast |
| Merge queue | `merge_group` | `ci-merge-queue.yml` → `ci-core.yml` | **Full** workspace build/clippy/test, plus **system tests** |
| Push to `main` | `push` | `ci-main-cache.yml` | Warms the shared Rust build cache |
| Nightly | `schedule` (07:00 UTC) | `fuzz-nightly.yml` | Sharded sync-parity fuzzing |
| Nightly | `schedule` (13:00 UTC) | `udeps-report.yml` | Unused-dependency report; opens a GitHub issue on findings |
| Release | manual / push to `releases/v*` | See [Release Process](/node-operations/release-process/) | Release builds, RC tags, Docker images |
Pull requests scope to affected crates through `etc/scripts/local/affected-crates.py`, which is exactly why the two local recipes differ: `just pr` mirrors what PR CI will do, while `just ci` mirrors the broader bar the merge queue eventually enforces. Holding system tests back to the queue is what keeps that PR stage quick, and making them a required check is what keeps the trade-off safe — the queue refuses to merge when they fail.
One naming trap worth knowing: `action-tests.yml` is not a workflow that tests GitHub Actions, despite how it reads. It drives the [action-test](#action-tests) tier covered earlier on this page, via `just actions::lint-ci` and `just actions::test-ci`, and does so for both pull requests and merge-queue runs. Its verdict is binding as well: action tests are a required status check too.
## Conventions
- Any behavioral change should come with tests that cover it.
- Pick the cheapest tier that genuinely exercises what you changed. Logic that stands on its own belongs in a unit test; anything crossing a protocol boundary — batching, derivation, channel encoding — belongs in an action test; reserve system tests for the cases that truly need a live L1/L2 stack.
- Keep unit tests next to the implementation, in a trailing `#[cfg(test)] mod tests { ... }` block.
- Run `just pr` while iterating for quick feedback, and `just ci` before you ask for review, so nothing surprises you at the merge queue.
## Command Reference
| Command | Runs |
|---|---|
| `just ci` | The full local gate — fix, all checks, full test suite |
| `just pr` | Affected-crates-only variant of `just ci` |
| `just fix` | Auto-fixes formatting, clippy, and zepter issues |
| `just test` | Unit tests across the whole workspace |
| `just test-affected` | Unit tests for affected crates only |
| `just actions test` | Action tests (`base-action-harness`) |
| `just devnet tests` | System tests (`base-system-tests`, needs Docker) |
| `just check` | Lists every `check::*` static-check recipe |
| `just lychee` | Link check |
| `just zepter` | Feature-flag validation |
## Next Steps
- [Development Workflow](/getting-started/development/) — the everyday check, test, and fix recipes.
- [Local Devnet](/getting-started/devnet/) — bring up a full local network for integration work.
---
# Accept Payments
Source: https://basehub.org/integration-guides/accept-payments/
Description: The onchain payment lifecycle on Base — direct USDC and B20 checkout, the Commerce Payments Protocol for charge, authorize, capture, void, and refund, x402 for APIs and agents, payouts, and reconciliation.
import { Aside } from '@astrojs/starlight/components';
Taking money on Base is an ERC-20 problem with a handful of extra primitives layered on top. The token moves, a `Transfer` event lands, and your backend decides whether that constitutes payment. Everything else on this page — escrow, collectors, HTTP negotiation, channels — exists to control *when* that transfer happens and *who* triggers it.
Two rails carry almost all of it:
| Rail | Best for | Integration |
|---|---|---|
| Direct USDC | Wallet-agnostic ERC-20 checkout | viem |
| B20 with memo | Issuer tokens and onchain reconciliation | viem or Solidity |
USDC lives at `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913` on Base mainnet and `0x036CbD53842c5426634e7929541eC2318f3dCF7c` on Base Sepolia. [B20](/specifications/b20/) adds issuer policy controls and an order memo written onchain beside the transfer.
## Settle now, or approve now and settle later
The first decision is whether the wallet interaction and the token movement happen together.
**A plain transfer** is the floor. The sender calls `transfer` on USDC, pays the gas, and the recipient holds the funds once it confirms. There is no escrow behind it, no authorization to revoke, and no protocol refund path, so check the network and the recipient before anyone signs. Treat it as paid only after the receipt succeeds and its `Transfer` event matches the sender, recipient, and amount you expected.
**B20 with a memo** keeps the one-prompt shape but writes an order reference onchain. The payer calls `transferWithMemo`, or a checkout contract pulls a pre-approved amount with `transferFromWithMemo` and refuses order IDs it has already seen:
```solidity
function pay(bytes32 orderId, uint256 amount) external {
if (paid[orderId]) revert OrderAlreadyPaid(orderId);
paid[orderId] = true;
bool transferred = token.transferFromWithMemo(msg.sender, merchant, amount, orderId);
require(transferred, "B20 transfer failed");
}
```
That Solidity path has two prerequisites people miss: the payer has to approve the checkout contract, and any `TRANSFER_EXECUTOR_POLICY` on the token has to authorize it as well. Verifying the amount before you ship remains your job either way.
**Anything with terms attached** — a charge you may refund, a hold you capture after shipping, a recurring bill — now goes through the [Commerce Payments Protocol](https://github.com/base/commerce-payments). The rest of this page covers it.
## The Commerce Payments Protocol
The protocol puts one contract, `AuthCaptureEscrow`, between payer and merchant. It keeps per-payment accounting onchain, so the questions a merchant ledger used to answer on its own — how much is still capturable, how much can still be refunded — become contract state you can read.
| v1.1.0 contract | Address |
|---|---|
| `AuthCaptureEscrow` | `0xf96815976523E00e65Be8f34cA5e64b4f41EB19c` |
| `ERC3009PaymentCollector` | `0x8612dfdc421f80336cd14E8EF9cb1E765dB5ab88` |
| `Permit2PaymentCollector` | `0xD69831Aed5bfe262067ec4c751f4F830EcdD446e` |
| `PreApprovalPaymentCollector` | `0xF1F9C408C787B2bC6CAEB91e5BbEc434a5c8d2Ea` |
| `SpendPermissionPaymentCollector` | `0xB508c1C0a13849693DC175307667653C5977a408` |
| `OperatorRefundCollector` | `0x7a03443724d14798c4AB4622F1DAAcA761Fea486` |
These are CREATE2 deployments, so each address is identical on Base and Base Sepolia. The escrow holds bytecode at that address on both chains.
### Payment terms
Every payment starts from a `PaymentInfo` struct that never changes once used. Every later operation takes the whole struct and rehashes it, so store it exactly as submitted:
| Field | Role |
|---|---|
| `operator` | The only account that may submit charge, authorize, capture, void, and refund |
| `payer` | Where funds come from, and where refunds and returned holds go |
| `receiver` | Where captured value goes, minus fees |
| `token` | The ERC-20 being moved |
| `maxAmount` | Ceiling on what this payment can collect |
| `preApprovalExpiry` | Last moment the payer's approval can be used to collect |
| `authorizationExpiry` | Last moment a hold can be captured; the payer can reclaim from here on |
| `refundExpiry` | Last moment a refund can be issued |
| `minFeeBps`, `maxFeeBps` | Bounds each fee is checked against |
| `feeReceiver` | Where fees go |
| `salt` | Makes the hash unique |
The three expiries must satisfy `preApprovalExpiry <= authorizationExpiry <= refundExpiry`; otherwise the escrow reverts with `InvalidExpiries`. A payment can be collected exactly once. Draw a fresh random `salt` for every checkout attempt, and that includes the retry after a void or a reclaim.
### How the payer approves
The escrow never pulls tokens itself. A collector contract does it, and you choose which one per payment:
| Collector | Use when |
|---|---|
| ERC-3009 | The token supports native transfer authorizations, as USDC does |
| Permit2 | You need general ERC-20 coverage and the payer has approved Permit2 |
| Pre-approval | A standard allowance plus a pre-approval scoped to this payment |
| Spend permission | A wallet has granted a spend permission for repeat billing |
B20 tokens and other ERC-20s can go through Permit2 or the pre-approval collector, but only when their transfer policies admit every party involved: the collector, the operator's token store, the receiver, and the fee receiver.
## Charge immediately
`charge` collects, pays out, and records the result in one transaction. The operator submits it with the terms, an amount, the collector, the collector's data, and a fee:
```typescript
const simulation = await publicClient.simulateContract({
account,
address: AUTH_CAPTURE_ESCROW,
abi: authCaptureEscrowAbi,
functionName: "charge",
args: [
payment.paymentInfo,
payment.paymentInfo.maxAmount,
ERC3009_PAYMENT_COLLECTOR,
payment.collectorData,
0n,
zeroAddress,
],
});
```
The receiver gets `amount - feeAmount`, the fee receiver gets the fee, and `refundableAmount` rises by the full gross amount. Look for `PaymentCharged`, match its `paymentInfoHash` to the order, and claim it once before you fulfil. Keep `maxFeeBps` tight, and pin `feeReceiver` in the terms unless your operator genuinely needs to swap out a recipient that has been denylisted.
## Authorize and capture
Use this path when fulfilment comes after checkout. It differs from the old signature-only hold in one decisive way: a successful `authorize` pulls the tokens into the operator's escrow token store *right away*. The payer spending the balance afterwards cannot break a later capture.
```typescript
const simulation = await publicClient.simulateContract({
account,
address: AUTH_CAPTURE_ESCROW,
abi: authCaptureEscrowAbi,
functionName: "authorize",
args: [
payment.paymentInfo,
payment.paymentInfo.maxAmount,
ERC3009_PAYMENT_COLLECTOR,
payment.collectorData,
],
});
```
Once `PaymentAuthorized` is emitted, the state reads:
| State field | Value |
|---|---|
| `hasCollectedPayment` | `true`, forever |
| `capturableAmount` | Everything held in escrow |
| `refundableAmount` | `0`, until something is captured |
Record `paymentInfoHash`, the full terms, the collector, the authorization transaction hash, and `PaymentAuthorized.amount` against the order.
To settle, read `paymentState(paymentInfoHash)` and call `capture` with an amount that is nonzero and no more than `capturableAmount`:
```typescript
const simulation = await publicClient.simulateContract({
account,
address: AUTH_CAPTURE_ESCROW,
abi: authCaptureEscrowAbi,
functionName: "capture",
args: [payment.paymentInfo, amount, 0n, zeroAddress],
});
```
The fee argument is an absolute `feeAmount` in raw token units, not basis points. The escrow checks it against `minFeeBps` and `maxFeeBps` from the terms. Each capture moves its gross amount out of `capturableAmount` and into `refundableAmount`. Confirm `PaymentCaptured(paymentInfoHash, amount, feeAmount, feeReceiver)` and the matching transfers before you mark that piece of the order settled.
### Capture a partial amount
There is no separate function. Call `capture` again for each increment — a split shipment, or a final bill that came in lower. Successful captures can sum to at most `PaymentAuthorized.amount`, and fee bounds are checked on every one individually. Capture 64 from a 100 USDC hold, and 36 stays capturable while 64 becomes refundable. From there you can capture again or void the rest.
Re-read `capturableAmount` and `refundableAmount` after each capture, before any other worker moves the order forward.
### Void or reclaim what is left
| Path | Caller | Available |
|---|---|---|
| `void(paymentInfo)` | Operator | Whenever a capturable balance remains |
| `reclaim(paymentInfo)` | Payer | At or after `authorizationExpiry` |
`void` hands back the *entire* `capturableAmount`. Nothing voids part of a hold, so capture the fulfilled amount first and void afterwards. Both paths zero `capturableAmount` and leave any `refundableAmount` from earlier captures alone. Match `PaymentVoided` or `PaymentReclaimed` against the capturable balance just before it fired.
## Verify before you fulfil
A wallet prompt that returned cleanly is not a payment, and neither is a transaction hash the client hands you. Decode confirmed `AuthCaptureEscrow` events on the backend, match their `paymentInfoHash` to the order, claim each one exactly once in durable storage, and only then reserve inventory, issue credentials, or return a paid resource.
`PaymentAuthorized` and `PaymentCharged` carry the complete `PaymentInfo`. Every later lifecycle event carries only the hash, so join those to the terms you stored at order creation.
The check should pass only for the first confirmed event with the right chain, escrow address, payment hash, operation, amount, and fee. Outside the protocol, bind orders like this:
| Rail | Bind the order with |
|---|---|
| Direct USDC | Stored transaction hash and expected checkout fields |
| Commerce Payments | `paymentInfoHash` from the escrow event |
| B20 | Adjacent `Memo` event containing the order reference |
For B20 the memo is emitted directly after its `Transfer`, so the join is `logIndex + 1` — an ordering guarantee, not a search.
Pick a confirmation depth against the value at stake and how hard fulfilment is to undo. The [transaction finality](/specifications/transactions/) stages describe what each depth actually buys you.
## Refunds
Protocol refunds run up to `refundExpiry` and always go to `paymentInfo.payer`; there is no argument for a different destination. The escrow enforces the ceiling: every charge or capture adds its gross amount to `refundableAmount`, fees do not reduce it, and every refund subtracts what it returned.
What the escrow does not supply is the money. Captured funds already left for the receiver, so the refund has to be funded fresh. The `OperatorRefundCollector` draws from `paymentInfo.operator`, which means the operator approves that collector for the refund amount first:
```typescript
await walletClient.writeContract({
address: payment.paymentInfo.token,
abi: refundApprovalAbi,
functionName: "approve",
args: [OPERATOR_REFUND_COLLECTOR, refundAmount],
});
// then
const refund = await publicClient.simulateContract({
account,
address: AUTH_CAPTURE_ESCROW,
abi: authCaptureEscrowAbi,
functionName: "refund",
args: [payment.paymentInfo, refundAmount, OPERATOR_REFUND_COLLECTOR, "0x"],
});
```
Confirm `PaymentRefunded(paymentInfoHash, amount, tokenCollector)`, the transfer to the stored payer, and the lowered `refundableAmount` before closing the return.
Outside the protocol nothing tracks this for you. Refund the address the chain says paid you, taken from the verified `Transfer` log, and reserve before you broadcast: atomically create the pending refund and decrement your own refundable balance so concurrent requests cannot overshoot. B20 can carry the original order ID into the refund via `transferWithMemo`.
## Payouts and splits
Both use a purpose-built contract that pulls each amount straight from the sender to its recipient. Nothing pools in the contract between transactions, which keeps the contract from becoming a balance worth attacking.
A payout batch is a list of recipients and amounts under one `batchId`, replay-guarded and length-bounded:
```solidity
function sendPayouts(bytes32 batchId, address[] calldata recipients, uint256[] calldata amounts) external {
if (processed[batchId]) revert BatchAlreadyProcessed(batchId);
if (recipients.length == 0 || recipients.length != amounts.length) revert InvalidArrayLengths();
if (recipients.length > MAX_RECIPIENTS) revert TooManyRecipients();
processed[batchId] = true;
for (uint256 i; i < recipients.length; ++i) {
require(token.transferFrom(msg.sender, recipients[i], amounts[i]), "transfer failed");
emit PayoutSent(batchId, msg.sender, recipients[i], amounts[i]);
}
}
```
Size batches from measured gas and respect `MAX_RECIPIENTS`. One failing token transfer reverts the whole batch.
A split is the same shape with proportions instead of amounts. Shares are basis points, they must total `10_000`, and integer division leaves a remainder that goes to one nominated recipient — so the legs sum to the input exactly and no dust is stranded. Every leg emits `PayoutSent` under a shared `splitId`, which gives both USDC and B20 an order reference without depending on token-level memo support.
Who gets the rounding remainder is a commercial question. Settle it in your terms, not implicitly in the loop.
## Paying for APIs with x402
x402 moves the negotiation into HTTP. An unpaid request gets `402 Payment Required` carrying the scheme, network, token, price, and recipient. The client signs what was advertised and retries with a `PAYMENT-SIGNATURE` header. Seller middleware verifies before your handler runs, and a facilitator settles. On Base USDC, the thing being carried through that handshake is an EIP-3009 authorization.
Three schemes cover three billing shapes:
- **`exact`** — the price is known before the work. A fixed-price route.
- **`upto`** — you advertise a ceiling, then set the real charge after the handler succeeds. This is the agentic twin of the capped permit checkout above. Apply the settlement override only once you have computed successful usage, and keep it at or below the advertised maximum.
- **`batch-settlement`** — for many small requests where per-request settlement would cost more than the requests. Each call advances a cumulative voucher; the channel manager claims, settles, or refunds the latest state later. Onchain transactions happen only at those points.
```typescript
app.use(paymentMiddleware({
"GET /metered": {
accepts: [{ scheme: "upto", price: "$0.10", network, payTo }],
description: "Usage-priced inference",
mimeType: "application/json",
},
}, resourceServer));
app.get("/metered", (_request, response) => {
setSettlementOverrides(response, { amount: "$0.04" });
response.json({ tokens: 812, result: "Generated response" });
});
```
Treat the facilitator's response and your own fulfilment record as two separate facts. A retried paid request must not deliver a one-time resource twice.
### The buyer side
An agent wraps its HTTP client so it can read a 402, pick a scheme it supports, sign, and retry. The important part is that policy runs *before* any signature exists — network, asset, per-request cap, and a session-cumulative cap:
```typescript
client.onBeforePaymentCreation(async ({ selectedRequirements }) => {
if (selectedRequirements.network !== "eip155:84532") return { abort: true, reason: "Wrong network" };
if (selectedRequirements.asset.toLowerCase() !== baseSepoliaUsdc.toLowerCase()) return { abort: true, reason: "Wrong asset" };
const amount = BigInt(selectedRequirements.amount);
if (amount > 100_000n || authorizedThisSession + amount > 1_000_000n) {
return { abort: true, reason: "Spend limit exceeded" };
}
authorizedThisSession += amount;
});
```
The wrapper automates negotiation, not trust. Whatever the service returns is untrusted input: validate the schema and the content, and never let anything in the response steer wallet policy.
## Charge on a schedule
Recurring billing runs through the `SpendPermissionPaymentCollector`. It rebuilds a spend permission out of the payment terms: the payer is the account, the collector is the spender, the token and allowance come from `PaymentInfo`, and `preApprovalExpiry` is where the permission ends. Pass the permission signature, plus an optional MagicSpend withdrawal request, as `collectorData`.
Each billing period is its own protocol payment with a fresh `PaymentInfo` and a fresh `salt`, because a payment collects only once. Key each one durably — `subscriptionId:periodStart` works — before you submit `charge`. The resulting `PaymentCharged` gives that period its own `refundableAmount`. Keep the billing key, `paymentInfoHash`, charge transaction, amount, and permission usage together in one durable workflow.
Some outcomes at a billing point are ordinary states, not errors:
- **Revoked or expired permission** — stop retrying and ask for a new one.
- **Insufficient balance** — notify the buyer and retry on your billing policy.
- **Period allowance exhausted** — wait for `nextPeriodStart`, or collect a new permission.
## Watching and reconciling
A WebSocket subscription gives you low-latency wakeups. It is not the source of truth. `eth_getLogs` across an overlapping window is, because it survives disconnects and reorgs — so use the subscription only to trigger a backfill, and let the backfill decide what is real.
For protocol payments, watch the v1.1.0 escrow for `PaymentAuthorized`, `PaymentCharged`, `PaymentCaptured`, `PaymentVoided`, `PaymentReclaimed`, and `PaymentRefunded`. All six index `paymentInfoHash`, which becomes the key of your ledger.
Make the overlap replacement one database transaction: delete the previously indexed rows in the window, insert the canonical logs returned now, rebuild the payment state they touch, and advance the cursor only if every write succeeds. Key rows on `(blockHash, transactionHash, logIndex)` so retries stay idempotent.
The ledger arithmetic per charge or capture is:
```text
merchant net = gross amount - fee amount
refundable balance += gross amount
```
A refund lowers the refundable balance by its gross amount. A void or reclaim lowers only the capturable balance and never unwinds an earlier capture. Two identities should hold for every payment:
- Authorized amount = captures + voided or reclaimed amount + current `capturableAmount`.
- Total charged and captured = refunds + current `refundableAmount`.
For reporting, run accounting over a finalized range only. If you also surface recent activity, label it provisional and replace it after a reorg.
One reconciliation trap worth naming: an outgoing `Transfer` from the merchant address is ambiguous on its face. It could be a refund, a payout leg, a split leg, or a treasury movement. Join it to your refund ledger, to `PaymentRefunded`, or to the `PayoutSent` reference — direction alone does not classify it. On the incoming side, B20 memos join back through `(transactionHash, logIndex - 1)`, the mirror of the adjacency rule used during verification. Direct USDC has no memo, so those rows join on the transaction hash or a contract event you emitted yourself.
---
# B20 Issuer Operations
Source: https://basehub.org/integration-guides/b20-issuer-operations/
Description: Day-two controls for a live B20 token — seizing and recovering a blocked balance, cancelling units, limiting who may initiate transfers, announcing holder-impacting changes, and scheduling multiplier updates.
import { Aside } from '@astrojs/starlight/components';
[Launching a B20 token](/integration-guides/launch-a-b20-token/) gets a balance onchain. This page covers what an issuer does after that: taking a balance back under a legal hold, cancelling units, deciding who may move tokens, and telling holders about changes before they land. The call-level reference is in [B20 precompiles](/api-reference/b20-precompiles/). The rules behind each check are in the [B20 specification](/specifications/b20/).
Each control below is tied to a fork. Beryl and Cobalt controls are live on Mainnet and Sepolia. Denim controls are not live yet.
| Control | Available from | Variants |
|---|---|---|
| `seizeWithMemo` | Cobalt (live: Sepolia September 23, Mainnet September 30, 2026) | Asset and Stablecoin |
| Executor policy on every transfer path | Denim (Sepolia October 21, 2026; Mainnet pinned in source for November 5, 2026) | Asset and Stablecoin |
| `announce` | Beryl | Asset only |
| Scheduled multiplier (`updateUIMultiplier`) | Cobalt | Asset only |
## Seize a blocked balance
Upstream's issuer guides now route every "take it back" case through `seizeWithMemo`: a lost key, a court order, a sanctions hold, or a holder who is no longer eligible. The call moves tokens from the holder to a safekeeping account in one transaction. It does not burn or mint, so `totalSupply` stays the same. The memo carries your case reference, and the token emits a dedicated `Seized` event that auditors can follow.
The older route, `burnBlocked` followed by a fresh `mint`, is deprecated. It makes supply dip and recover, emits no `Seized` event, and leaves reconciliation with two unrelated transactions. Since Cobalt reached Mainnet on September 30, 2026, there is no network where it is still the only option.
### Three gates
A seize runs only if all three of these pass:
| Gate | Passes when | If unset |
|---|---|---|
| `SEIZE_ROLE` | The caller holds the role. | No one can seize. |
| `SEIZE_EXEMPT_POLICY` | The holder (`from`) is **not** authorized under the attached policy. | Everyone is authorized, so no one is seizable. |
| `SEIZE_RECEIVER_POLICY` | The destination (`to`) is authorized. | Any destination works. |
`SEIZE` must also not be paused. Pausing `TRANSFER`, `MINT`, or `BURN` does not stop a seize.
On this scope, a `false` from `isAuthorized` exposes the holder. `isAuthorized` gives `false` for a malformed ID, and from Denim also for an inverted ID whose base is unknown or malformed. The token itself rejects a missing ID in `updatePolicy` with `PolicyNotFound`. If your tooling computes or stores IDs before it attaches them, still check `policyExists` first, so a typo fails at the call and not on a holder.
### Freezing does not make an account seizable
Seize reads its own scope and ignores the transfer scopes. Two common setups leave an account frozen but still out of reach:
- **Stablecoin blocklist.** A blocklist bound to `TRANSFER_SENDER_POLICY` stops the holder's outgoing transfers. To make the same account seizable, also bind that blocklist to `SEIZE_EXEMPT_POLICY`. One list then both freezes and exposes the account.
- **Asset allowlist.** Taking a holder off an eligibility allowlist freezes their transfers. It does not make them seizable. You need a separate blocklist on `SEIZE_EXEMPT_POLICY` with that holder on it.
### The call
Grant the role once, attach the blocklist, then seize to your treasury:
```solidity
token.grantRole(token.SEIZE_ROLE(), seizer);
token.updatePolicy(B20Constants.SEIZE_EXEMPT_POLICY, blocklistId);
token.seizeWithMemo(blocked, treasury, 50e6, bytes32("legal-hold-2026-118"));
```
Events fire in this order: `Transfer(from, to, amount)`, `Memo(caller, memo)`, then `Seized(caller, from, to, amount)`. After that the treasury holds an ordinary balance. You can `transfer` it to the holder's new address, keep it while the case is open, or cancel it (next section).
To restrict where seized funds can go, put the treasury on an allowlist and bind it to `SEIZE_RECEIVER_POLICY`.
`to` cannot be zero, the token's own address, or the same as `from`. Seizing *from* the token's own address is allowed, which is how you recover tokens someone sent to the contract by mistake.
### Errors, in check order
| Error | Meaning |
|---|---|
| `ContractPaused(SEIZE)` | Seize is paused. |
| `AccessControlUnauthorizedAccount(caller, SEIZE_ROLE)` | The caller lacks the role. |
| `InvalidReceiver(to)` | `to` is zero, the token, or `from`. |
| `InvalidSender(from)` | `from` is zero. |
| `AccountNotSeizable(from)` | `from` is still authorized under `SEIZE_EXEMPT_POLICY`: the slot is unset, or the holder is not on the blocklist. |
| `PolicyForbids(SEIZE_RECEIVER_POLICY, policyId)` | `to` fails the receiver policy. |
| `InsufficientBalance(from, balance, amount)` | `from` holds less than `amount`. |
## Cancel units
For an Asset whose units must be destroyed, seize first, then burn from the treasury with `burnWithMemo`. `burnWithMemo` burns the caller's own balance, so either seize to the burning account or transfer to it first. The burner needs `BURN_ROLE`, and `BURN` must not be paused.
```solidity
IB20(token).seizeWithMemo(holder, address(this), 100e6, bytes32("cancel-2026-07"));
IB20(token).burnWithMemo(100e6, bytes32("cancel-2026-07"));
```
`totalSupply` stays level after the seize and drops after the burn. Reuse the same memo on both calls so reconciliation can link them to one case. To disclose the cancellation, wrap the burn in `announce` (see below).
## Limit who may initiate transfers
Some issuers want every transfer to go through a designated account, such as a transfer agent, even when both sides are eligible holders. `TRANSFER_EXECUTOR_POLICY` checks the initiator (`msg.sender`), separately from the sender and receiver scopes.
From Denim, the rules are:
- The executor check runs first on `transfer`, `transferFrom`, and their memo variants.
- A holder calling `transfer`, or `transferFrom` on their own balance, must be on the executor allowlist. Otherwise the call reverts `PolicyForbids(TRANSFER_EXECUTOR_POLICY, policyId)` before any balance check.
- When the caller is `from` and the executor and sender scopes point at the same policy, the node skips the now-redundant sender check.
- An allowance is still required for `transferFrom`. The allowance limits how much a caller may spend. The executor policy decides whether the caller may start a transfer at all. A transfer agent needs both.
Setup is two calls: create an allowlist seeded with the agent, then bind it.
```solidity
id = StdPrecompiles.POLICY_REGISTRY.createPolicyWithAccounts(
admin, IPolicyRegistry.PolicyType.ALLOWLIST, initiators
);
IB20(token).updatePolicy(B20Constants.TRANSFER_EXECUTOR_POLICY, id);
```
Creating the policy has no effect until `updatePolicy` binds it. Add every intended initiator before you bind, including the issuer's own accounts. Anyone left off loses the ability to start transfers. Batches cap at 64 accounts, and only the policy admin can change membership.
## Announce a change to holders
`announce(internalCalls, id, description, uri)` wraps a holder-impacting change in an onchain disclosure. It is Asset-only and needs `OPERATOR_ROLE`. The wrapped calls keep their own role checks and run with the operator as `msg.sender`, so the operator also needs `MINT_ROLE` for `batchMint` or `mintWithMemo` and `BURN_ROLE` for `burnWithMemo`.
The sequence is: emit `Announcement(caller, id, description, uri)`, run every inner call atomically, emit `EndAnnouncement(id)`. Each inner entry is raw calldata against this same asset, at least 4 bytes long. It is not a target and calldata pair. If any inner call fails, the whole transaction reverts and `id` stays unused. A successful call burns `id` for the life of the asset.
Typical uses:
- **Extra units** (a stock dividend paid in shares): wrap `batchMint`. The events are `Announcement`, one `Transfer` per recipient, then `EndAnnouncement`.
- **Split or reverse split**: wrap `updateUIMultiplier`.
- **Replacing a pending multiplier**: wrap `cancelUIMultiplierUpdate` and a new `updateUIMultiplier` in the same announcement.
- **Treasury burn**: wrap `burnWithMemo`.
- **Notice only**: pass an empty `internalCalls` array.
**For indexers:** match `Announcement` to `EndAnnouncement` by `id`, not just by position. Everything between the two logs belongs to the announcement. A state change outside any bracket was made directly. A direct `updateUIMultiplier` still works, so flag it as undisclosed rather than assume every change was announced.
## Schedule a multiplier update
The multiplier changes what holders *see*, not what they hold. Raw `balanceOf`, `totalSupply`, and transfer amounts never move, so DeFi that reads raw units keeps working. Only the UI views apply it: `balanceOfUI(account)` equals `balanceOf(account) * uiMultiplier() / 1e18`.
An asset holds at most **one** pending update:
1. `updateUIMultiplier(newMultiplier, effectiveAt)` records it. `effectiveAt` must be later than the current block time, and `newMultiplier` must be above zero and at most `MAX_UI_MULTIPLIER`. A 2-for-1 split is `2e18`.
2. While pending, `uiMultiplier()` still returns the old value, `newUIMultiplier()` returns the scheduled one, and a second schedule reverts `UIMultiplierUpdateExists`.
3. At `effectiveAt` the new value takes over. Nothing is written and no event fires at that moment. `UIMultiplierUpdated` fired earlier, when the schedule was recorded.
4. After it matures, `effectiveAt()` keeps the old timestamp. **Test for a pending update with `effectiveAt() > block.timestamp`, never with `effectiveAt() == 0`.**
`cancelUIMultiplierUpdate()` drops a pending update before it matures. After maturity it reverts `UIMultiplierUpdateDoesNotExist`.
The deprecated `updateMultiplier(newMultiplier)` applies a value at once and clears anything pending. Keep it for fixing a mistake you cannot wait out. It emits `UIMultiplierUpdateCancelled` only if an update was still live, then `MultiplierUpdated`, then `UIMultiplierUpdated` with the current block time as `effectiveAtTimestamp`, not the old scheduled time.
The setters are not pause-gated. Pausing `TRANSFER` around a split is possible, but it freezes every holder and needs the pause roles, so upstream advises against it for routine updates.
---
# Base Verify
Source: https://basehub.org/integration-guides/base-verify/
Description: Sybil resistance and eligibility gating from verified X, Coinbase, Instagram, and TikTok accounts — the backend token API and the onchain SignerRegistry flow, with what each one reveals.
import { Aside } from '@astrojs/starlight/components';
A wallet says nothing about the person behind it. One person can split across a hundred wallets, and a valuable user can arrive with an empty one. Base Verify closes both gaps. A user proves they control a verified account on X, Coinbase, Instagram, or TikTok, and your app gets two things back: a stable key that is the same for that account whichever wallet it uses (Sybil resistance), and a yes or no on traits you care about, such as follower count or an active Coinbase One membership (eligibility). Your app never sees the user's credentials or account name.
It answers a different question from [Builder Codes](/integration-guides/builder-codes/). Builder Codes say which app produced a transaction. Base Verify says whether the person behind a wallet qualifies, and whether they have already been counted.
## Two integrations
| | Backend (verify social accounts) | Onchain (verify users onchain) |
|---|---|---|
| Who enforces | Your backend | Your contract |
| Endpoint | `POST /v1/base_verify_token` | `POST /v1/onchain_verifications` |
| Auth | Secret API key plus a SIWE signature | SIWE signature only, no key |
| You get back | `token`, `action`, `wallet` | `identityHash`, `expiration`, `signature` |
| Backend at claim time | Required | Not required |
| Networks | Any app | **Base Sepolia only** |
Both start the same way: the user signs a [SIWE](https://eips.ethereum.org/EIPS/eip-4361) message, which proves they control the wallet and states what is being checked. Access to the backend API is by request through the Base Verify interest form.
If the user has not verified the needed provider yet, send them to Base Verify to complete OAuth, then check again:
```text
https://verify.base.dev?redirect_uri={your_app_url}&providers={provider}
```
`providers` takes `x`, `coinbase`, `instagram`, or `tiktok`.
## Backend flow
Your frontend has the user sign a SIWE message. Your backend forwards the message and signature to Base Verify with the secret key:
```bash
curl -X POST https://verify.base.dev/v1/base_verify_token \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_SECRET_KEY" \
-d '{
"signature": "0x1234...",
"message": "verify.base.dev wants you to sign in..."
}'
```
The SIWE `resources` list carries the provider, any trait requirements, and an action:
```typescript
resources: [
'urn:verify:provider:x',
'urn:verify:provider:x:verified:eq:true',
'urn:verify:action:claim_airdrop'
]
```
Trait requirements use the form `urn:verify:provider:{provider}:{trait_name}:{operation}:{value}`.
### The token is the dedupe key
A `200` returns `{ "token", "action", "wallet" }`. The token is what makes Sybil resistance work. Store it, and refuse any second claim that arrives with a token you have already seen.
- It follows the provider account, not the wallet. The same X account on a second wallet returns the same token.
- It differs per provider, per app, and per action. Your tokens cannot be matched against another app's.
- It does not rotate and does not change when traits change, such as a rising follower count.
**Actions** let one app run several independent claims. The same account gets one token for `claim_airdrop` and a different one for `join_allowlist`. Pick descriptive names like `enter_weekly_raffle`, and do not rename an action after launch: a new name issues new tokens to every user, and your duplicate check stops working.
### Responses
| Status | Meaning | What to do |
|---|---|---|
| `200` | Verified and meets every trait. | Store the token and grant access. |
| `404` `verification_not_found` | This wallet has never verified the provider. | Redirect to Base Verify. Do not retry. |
| `400` `verification_traits_not_satisfied` | Verified, but a trait falls short. | Tell the user. Do not redirect or retry. |
| `401` `unauthorized` | Bad or missing secret key. | Fix the `Authorization` header. |
Keep the secret key on the server only. Never put it in frontend code or in a browser-exposed variable such as `NEXT_PUBLIC_*`, and rotate it at once if it leaks. Cache results for a session at most, and clear the cache when the wallet disconnects.
## Onchain flow
Here your contract does the checking, so no backend has to be up at claim time. Base Verify signs a short-lived [EIP-712](https://eips.ethereum.org/EIPS/eip-712) verification. The contract checks it and records the identity in the same transaction as the claim, mint, deposit, or vote.
| Item | Value |
|---|---|
| `SignerRegistry` (Base Sepolia) | `0x4f15593fbF7e3491d15080e1610E7AF8deBA1a02` |
| API base URL | `https://verify.base.dev/v1` |
| Consumer base contract | `BaseVerifyConsumer.sol` |
The steps are:
1. Your contract extends `BaseVerifyConsumer` and declares its policy: one `provider` and one or more `conditions`.
2. The user signs a SIWE message whose `statement` is exactly `Claim eligibility for a Base Verify onchain benefit.`, whose `chainId` is `84532`, and whose `Resources` include `eip155::`.
3. Your app posts `{ "message", "signature" }` to `POST /v1/onchain_verifications`. Smart-wallet signatures (ERC-1271 and ERC-6492) work.
4. Base Verify reads your contract's policy through `eth_call`, checks the user's stored credential against it, and signs only if it passes. The conditions come from your contract, not from the user, so a user cannot drop one.
5. The user submits `identityHash`, `expiration`, and `signature` to your contract.
6. Your contract calls `registry.verifyVerification(...)`, then rejects any `identityHash` it has already stored.
### The contracts
`SignerRegistry` is stateless. It checks that a trusted signer produced the verification, that it has not expired, and that it matches the calling contract's live policy. It does not dedupe, which is your contract's job.
```solidity
function verifyVerification(
address user,
bytes32 identityHash,
uint40 expiration,
bytes calldata signature
) external view;
// Reverts VerificationExpired(expiration) when block.timestamp > expiration.
// Reverts InvalidSignature() when the signature cannot be recovered.
// Reverts NotSigner(signer) when the recovered signer is not on the allowlist.
```
The registry rebuilds `policyHash` from the calling contract's policy, so a verification for one contract fails at any other. `BaseVerifyConsumer` supplies the policy getters and an `_verify` helper that passes `msg.sender` as the user, so only the wallet that signed can spend the verification and a mempool watcher cannot front-run it.
```solidity
abstract contract BaseVerifyConsumer {
struct Condition {
string name; // e.g. "followers"
string op; // eq | gt | gte | lt | lte | in
string value; // e.g. "1000"
}
function provider() external view virtual returns (string memory);
function conditions() external view virtual returns (Condition[] memory);
function cutoffBlock() external view virtual returns (uint256);
function _verify(bytes32 identityHash, uint40 expiration, bytes calldata signature) internal view;
}
```
Your policy must be immutable. `cutoffBlock()` is the exception: it is outside `policyHash`, so you can raise it to force users to re-authenticate without breaking verifications already in flight. Return `0` for no cutoff.
`identityHash` is one-way and scoped to your contract. The same person gets the same hash from every wallet, which is what blocks duplicates. A different contract gets an unrelated hash, so no one can link the same person across apps.
### Policy options
All conditions on a policy must pass (AND).
| Provider | Condition | Type | Operators |
|---|---|---|---|
| `x` | `followers` | int | `eq` `gt` `gte` `lt` `lte` |
| `x` | `verified` | bool | `eq` |
| `x` | `verified_type` | string | `eq` |
| `coinbase` | `coinbase_one_active` | bool | `eq` |
| `coinbase` | `coinbase_one_billed` | bool | `eq` |
| `instagram` | `followers_count` | int | `eq` `gt` `gte` `lt` `lte` |
| `instagram` | `username` | string | `eq` |
| `tiktok` | `follower_count` | int | `eq` `gt` `gte` `lt` `lte` |
| `tiktok` | `following_count`, `likes_count`, `video_count` | int | `eq` `gt` `gte` `lt` `lte` |
### Errors
Do not send the transaction unless the API returned `200`.
| Response | Meaning |
|---|---|
| `404` `contract_not_found` | The contract is not on this chain or has no policy. |
| `404` `verification_not_found` | No credential for the contract's provider. Redirect to Base Verify. |
| `404` `needs_reauth` | The credential predates the contract's cutoff block. Redirect to re-authenticate. |
| `400` `conditions_not_satisfied` | Verified, but the policy is not met. Do not retry. |
| `400` `invalid_policy` | The contract's provider, condition, and operator combination is unsupported. |
| `400` `invalid_argument` | The SIWE message is malformed, expired, has the wrong statement, or names the wrong chain. |
## What a claim makes public
Neither flow hands your app a username, handle, trait value, or OAuth token. The onchain flow still leaves a public trail, and it is permanent once mined.
- **Onchain:** the claiming wallet, the `identityHash`, and the expiring signature, plus anything your contract stores or emits. Your `provider` and `conditions` are public view functions.
- **Never onchain:** the account itself, trait values, OAuth tokens, and `policyHash`, which the registry computes in memory.
Because the policy is public, a claim reveals that the wallet met it. Every wallet in a Coinbase One-gated contract's claim log is known to have held an active membership at claim time. Anyone can see that, but not which Coinbase account it was. A narrow policy such as `followers gte 10000` reveals more than `verified eq true`.
---
# Builder Codes
Source: https://basehub.org/integration-guides/builder-codes/
Description: Attribute onchain activity to an app, wallet, or agent with ERC-8021 calldata suffixes — client setup for Wagmi and Viem, the wallet-side capability, and the agent registration API.
import { Aside } from '@astrojs/starlight/components';
A Builder Code ties onchain activity back to whoever built the thing that caused it. Codes live as an ERC-721 collection, one NFT per code, each holding a short identifier such as `abc123`. The onchain metadata carries a payout address — where rewards would go if the program pays out. Name, site, and similar details sit offchain.
Register a project on [Base Dashboard](https://dashboard.base.org/) to get a code. Base Dashboard is the new name for base.dev, and `base.dev` now redirects there. The code sits under **Settings** → **Project Settings** → **Builder Code**. Switch the format to **Encoded String** there to copy the whole ERC-8021 suffix. It is the same hex that `Attribution.toDataSuffix` returns.
## The mechanism, in one paragraph
Attribution rides on the tail of the calldata. Your code is encoded as an [ERC-8021](https://eip.tools/eip/8021) suffix and appended after the real arguments; indexers strip it back off later, offchain. Nothing onchain reads it, so contracts run exactly as before. Three consequences follow, and they are the reason this design was picked:
- Any deployed contract already works with ERC-8021. There is nothing to upgrade and nothing to redeploy.
- Execution is unaffected, because the trailing bytes are never decoded by the callee.
- The cost is 16 gas per non-zero byte, which is negligible against any real transaction.
EOAs and smart contract wallets both work. Attribution links a transaction to an application — it does not surface wallet information that was not already public onchain.
## For app developers
An app registered on [Base Dashboard](https://dashboard.base.org/) gets attribution inside the Base App for free — the Base App appends your code to transactions its users make through your app or its browser. That credits the activity to your project and counts toward any future rewards.
Everything outside the Base App is on you. If users reach your app on the web or through another client, wire up `dataSuffix` yourself to capture that traffic.
Registration hands you a Builder Code — a random string along the lines of `bc_b7k3p9da`. How you attach it depends on the library. A Viem wallet client takes it once and applies it to everything it sends. Wagmi does not, so there you pass it with each write.
### Wagmi
Both examples need viem `2.45.0` or newer.
```bash
npm i ox wagmi viem
```
Build the suffix once in its own module so every call site can import it:
```typescript
// attribution.ts
import { Attribution } from "ox/erc8021";
// Get your Builder Code from Base Dashboard > Settings > Project Settings > Builder Code
export const DATA_SUFFIX = Attribution.toDataSuffix({
codes: ["YOUR-BUILDER-CODE"],
});
```
Then hand it to every write. `useSendTransaction` and `useWriteContract` take `dataSuffix` directly and add it to the calldata before the wallet signs:
```tsx
// SendButton.tsx
import { useSendTransaction } from "wagmi";
import { parseEther } from "viem";
import { DATA_SUFFIX } from "./attribution";
function SendButton() {
const { sendTransaction } = useSendTransaction();
return (
);
}
```
```tsx
// MintButton.tsx
import { useWriteContract } from "wagmi";
import { abi } from "./abi";
import { DATA_SUFFIX } from "./attribution";
function MintButton() {
const { writeContract } = useWriteContract();
return (
);
}
```
`useSendCalls` works differently. The suffix goes in the `dataSuffix` capability, and the wallet does the appending, so the connected wallet has to [support that capability](#for-wallet-developers):
```tsx
// SendCallsButton.tsx
import { useSendCalls } from "wagmi";
import { parseEther } from "viem";
import { DATA_SUFFIX } from "./attribution";
function SendCallsButton() {
const { sendCalls } = useSendCalls();
return (
);
}
```
Send one test transaction and inspect its input data, as in [Confirming attribution works](#confirming-attribution-works), before you trust the setup.
### Viem
```bash
npm i ox viem
```
The wallet client takes the same option:
```typescript
// client.ts
import { createWalletClient, http } from "viem";
import { base } from "viem/chains";
import { Attribution } from "ox/erc8021";
// Get your Builder Code from Base Dashboard > Settings > Project Settings > Builder Code
const DATA_SUFFIX = Attribution.toDataSuffix({
codes: ["YOUR-BUILDER-CODE"],
});
export const walletClient = createWalletClient({
chain: base,
transport: http(),
dataSuffix: DATA_SUFFIX,
});
```
`sendTransaction` and `writeContract` on this client add the suffix for you. `sendCalls` passes it on to the wallet as the `dataSuffix` capability instead:
```typescript
// send-transaction.ts
import { parseEther } from "viem";
import { walletClient } from "./client";
const hash = await walletClient.sendTransaction({
to: "0x70997970c51812dc3a010c7d01b50e0d17dc79c8",
value: parseEther("0.01"),
});
```
### Managed wallet providers
- **CDP Wallets** — [Coinbase Developer Platform](https://docs.cdp.coinbase.com/wallets/non-custodial-wallets/overview) smart accounts accept `dataSuffix` on user operations, across the React hooks (`useSendUserOperation`), Node, and Python SDKs. Generate the suffix with `Attribution.toDataSuffix` from `ox/erc8021`; setup notes are under [Builder Codes](https://docs.cdp.coinbase.com/wallets/using-wallets/smart-accounts#builder-codes) in their docs.
- **Privy** — ships a `dataSuffix` plugin that covers plain EOA transactions and ERC-4337 user operations alike. See the [Privy integration guide](https://docs.privy.io/recipes/evm/base-builder-codes).
- **Turnkey** — infrastructure for programmatic wallets, also supported.
## For wallet developers
A wallet enables attribution by honoring the `dataSuffix` capability: accept it, then append the bytes before signing.
Accept a `dataSuffix` object inside the `capabilities` object of `wallet_sendCalls`:
```typescript
type DataSuffixCapability = {
value: `0x${string}`; // hex-encoded bytes provided by the app
optional?: boolean; // whether the capability is optional
}
```
Where the bytes land depends on the transaction type. For an EOA, extend `tx.data`:
```typescript
// Minimal example for EOA
function applySuffixToEOA(tx, capabilities) {
const suffix = capabilities.dataSuffix?.value
if (!suffix) return tx
return {
...tx,
// Append suffix bytes (remove 0x prefix from suffix if tx.data has it)
data: tx.data + suffix.slice(2)
}
}
```
For ERC-4337 the target is `userOp.callData`, **not** the outer transaction calldata:
```typescript
// Minimal example for ERC-4337
function applySuffixToUserOp(userOp, capabilities) {
const suffix = capabilities.dataSuffix?.value
if (!suffix) return userOp
return {
...userOp,
// Append suffix bytes to the UserOp callData
callData: userOp.callData + suffix.slice(2)
}
}
```
A wallet can claim attribution of its own at the same time. ERC-8021 carries multiple codes natively, so prepend your suffix ahead of the app's and both parties are credited:
```typescript
finalSuffix = walletSuffix + appSuffix
```
Apps need to do nothing for this — the wallet handles it alone.
## For agent developers
Agents transact on their own schedule, with no human pressing a button per transaction. Without a code that activity is anonymous; with one it rolls up under your identity in the Base registry, where anyone can measure it from chain data, and making the agent eligible for discovery surfaces such as the App Leaderboard.
The mechanics are the ones described above — an ERC-8021 suffix, ignored by contracts, recovered by indexers, 16 gas per non-zero byte.
### Registration API
```http
POST /v1/agents/builder-codes
```
No authentication required.
| Field | Type | Required | Description |
|---|---|---|---|
| `walletAddress` | string | Yes | Your agent's EVM wallet address (`0x...`) |
```bash
curl -X POST https://api.base.dev/v1/agents/builder-codes \
-H "Content-Type: application/json" \
-d '{
"walletAddress": ""
}'
```
```json
{
"builderCode": "bc_a1b2c3d4",
"walletAddress": "0x..."
}
```
The endpoint is idempotent on wallet address: one address always maps to the same code, and calling again returns the code you already have. That makes it safe to run on every deploy rather than gating it behind a first-run check.
### Doing it from a coding agent
Working in Claude Code, Cursor, or Codex? The Base skills package handles the whole path:
```bash
npx skills add base/base-skills
```
Then ask for a builder code registration. The skill validates the wallet, calls the API, writes the result to `src/constants/builderCode.ts`, installs `ox`, and threads the ERC-8021 `dataSuffix` into whichever client you use — viem, ethers.js, or a managed service.
## Confirming attribution works
Two independent checks:
1. **A block explorer** — pull up the transaction on Basescan or Etherscan, open the input data field, and confirm the last 16 bytes are the repeating `8021` pattern. Decode the suffix to see your code.
2. **The validation tool** — paste a transaction or UserOperation hash into [Builder Code Validation](https://builder-code-checker.vercel.app/), pick the transaction type, and press **Check Attribution**.
Upstream used to list the base.dev dashboard as a third check. It removed that step on 2026-10-01, so rely on the onchain data instead.
## Measuring your own users
Base Dashboard reports a narrow set of numbers from your code's activity: spot trading volume, borrow TVL, and lending TVL. It does not report users, retention, funnels, or the raw ETH and USDC your attributed transactions move. For those you join two data sets yourself. One is what your app sees in the browser. The other is the attributed transactions onchain. The connected wallet address, in lowercase, is the join key. The transaction hash links each submit to its result.
| Metric | What to count | Where it comes from |
| --- | --- | --- |
| Daily, weekly, and monthly active users | Distinct addresses that connected, or that sent a successful attributed transaction | The `eth_requestAccounts` result; the sender and status of each transaction |
| D1, D7, and D30 retention | Each address's first-seen date, and whether it returned later | Block timestamp of the address's first successful attributed transaction |
| Conversion funnel | Open, connect, submit, success, joined on address and hash | Page load, `eth_requestAccounts`, the hash or call bundle ID from submit, the receipt |
| Attributed onchain activity | Transactions whose ERC-8021 suffix holds your code | Transaction `input`, or each UserOperation's `callData` |
| ETH and USDC volume | What the user moved out in each attributed transaction | The transaction's `value`, plus `Transfer` logs in its receipt |
Capture the browser side at each step:
- **Open.** Read the acquisition source from URL parameters such as `utm_source` or `ref`, and from `document.referrer`. Do it on the first load, because client-side navigation discards them.
- **Connect.** A resolved `eth_requestAccounts` call. Error code `4001` means the user said no.
- **Submit.** `eth_sendTransaction` returns a transaction hash. `wallet_sendCalls` ([EIP-5792](https://eips.ethereum.org/EIPS/eip-5792)) returns a call bundle ID instead, and `wallet_getCallsStatus` turns it into hashes. Store the hash with the in-app action it stands for (mint, swap, deposit). Error code `4001` here means the user refused to sign.
- **Success.** Comes from the chain, not the app.
The suffix is parsed from the end backwards. First comes the 16-byte marker `0x80218021802180218021802180218021`, then a 1-byte schema ID, then a 1-byte length, then the codes as comma-separated ASCII. So `bc_b7k3p9da` becomes `0x62635f62376b33703964610b0080218021802180218021802180218021`. Compare decoded codes, not raw bytes.
Upstream's helper takes a recorded hash and returns one row per user action, for either account type:
```typescript
import { createPublicClient, decodeFunctionData, http, isAddressEqual, parseEventLogs, type Hash } from "viem";
import { base } from "viem/chains";
import { entryPoint06Abi, entryPoint06Address, entryPoint07Abi, entryPoint07Address } from "viem/account-abstraction";
import { Attribution } from "ox/erc8021";
const client = createPublicClient({ chain: base, transport: http() });
const BUILDER_CODE = "YOUR-BUILDER-CODE";
export async function getAttributedActivity(hash: Hash) {
const [tx, receipt] = await Promise.all([
client.getTransaction({ hash }),
client.getTransactionReceipt({ hash }),
]);
const block = await client.getBlock({ blockNumber: receipt.blockNumber });
const common = {
transactionHash: hash,
blockNumber: receipt.blockNumber,
timestamp: Number(block.timestamp),
};
// ERC-4337: the outer transaction is sent by a bundler to the EntryPoint.
// The user is each UserOperation's sender, and the suffix sits in its callData.
const entryPoint =
tx.to && isAddressEqual(tx.to, entryPoint07Address) ? { abi: entryPoint07Abi } :
tx.to && isAddressEqual(tx.to, entryPoint06Address) ? { abi: entryPoint06Abi } :
undefined;
if (entryPoint) {
const { args } = decodeFunctionData({ abi: entryPoint.abi, data: tx.input });
const ops = (args?.[0] ?? []) as readonly { sender: `0x${string}`; callData: `0x${string}` }[];
const events = parseEventLogs({ abi: entryPoint.abi, eventName: "UserOperationEvent", logs: receipt.logs });
return ops.map((op) => {
const event = events.find((e) => isAddressEqual(e.args.sender, op.sender));
return {
...common,
sender: op.sender.toLowerCase(),
success: event?.args.success ?? false,
attributed: Attribution.fromData(op.callData)?.codes?.includes(BUILDER_CODE) ?? false,
};
});
}
// EOA transaction: the user is tx.from and the suffix is at the end of tx.input.
return [{
...common,
sender: tx.from.toLowerCase(),
success: receipt.status === "success",
attributed: Attribution.fromData(tx.input)?.codes?.includes(BUILDER_CODE) ?? false,
}];
}
```
To backfill, or to catch transactions sent from outside your UI, scan Base blocks (or your contracts' logs via `eth_getLogs`) for calldata that ends in the marker, and decode each hit the same way.
For volume, reuse the transaction and receipt you already fetched. Where the value shows up depends on the account type:
- **ETH from an EOA** is the transaction's `value`.
- **ETH from a smart account** moves in an internal call, so it is in neither the outer `value` nor any log. You need a call trace for it (`debug_traceTransaction` with the `callTracer`), from a node or provider that offers one. The public `mainnet.base.org` endpoint stopped serving `debug_` on 2026-10-08.
- **USDC and other ERC-20 tokens** are `Transfer` logs from the token contract. Keep only transfers whose sender is your user. That filter also splits a bundle into its separate UserOperations, because each has its own `sender`.
```typescript
// get-attributed-volume.ts
import { erc20Abi, isAddressEqual, parseEventLogs, type Address, type Transaction, type TransactionReceipt } from "viem";
// USDC on Base
const USDC = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913";
// Pass the transaction and receipt fetched in step 3, and the sender of each row where success and attributed are true
export function getAttributedVolume(tx: Transaction, receipt: TransactionReceipt, sender: Address) {
const usdcTransfers = parseEventLogs({ abi: erc20Abi, eventName: "Transfer", logs: receipt.logs })
.filter((log) => isAddressEqual(log.address, USDC) && isAddressEqual(log.args.from, sender));
return {
// Native ETH sent directly by an EOA. Smart account ETH transfers need a call trace.
ethWei: isAddressEqual(tx.from, sender) ? tx.value : 0n,
// USDC uses 6 decimals: format with formatUnits(usdc, 6)
usdc: usdcTransfers.reduce((sum, log) => sum + log.args.value, 0n),
};
}
```
Call it for each row from `getAttributedActivity` where `success` and `attributed` are both true. ("Step 3" in the upstream comment is that helper.) Roll the totals up by day, week, or month. For a single currency figure, price each amount at its block timestamp with whatever price source you trust.
With both sides joined:
1. **Active users.** Count distinct addresses per UTC day, week, or month. Keep connected users and transacting users apart (a transacting user has a row where `success` and `attributed` are both true). The gap between the two is your activation rate.
2. **Retention.** Put each address in a cohort by the week of its first successful attributed transaction. Then measure what share of each cohort transacts again after 1, 7, and 30 days.
3. **Funnel.** Count addresses at each stage, split by acquisition source. A drop between submit and success has three causes: a refused signature (`4001`), a revert (`success` is false), or a missing code (`attributed` is false). The last one usually means a client was set up without `dataSuffix`.
## Wallet support today
Every EOA wallet supports `dataSuffix` as a matter of course. Smart wallets that implement ERC-5792 can carry it through the `DataSuffixCapability`:
```javascript
await wallet.sendCalls({
calls: [
// your transaction calls
],
capabilities: {
dataSuffix: {
value: "0x07626173656170700080218021802180218021802180218021",
optional: true
}
}
});
```
Privy and Turnkey both cover the embedded wallet case.
## Not the same thing as user verification
Builder Codes and [Base Verify](/integration-guides/base-verify/) get reached for interchangeably and answer different questions. A Builder Code says which app, wallet, or agent produced a transaction. It says nothing about who the user is or whether they qualify for anything. Base Verify goes the other way: it lets a user prove control of a supported account so your app can evaluate approved traits, with a backend flow for app-controlled experiences and an onchain flow for policy a contract has to enforce itself. It carries no attribution.
If you need both — attributing activity *and* gating who can perform it — they are two integrations, not one.
## Related resources
- [ERC-8021 proposal](https://eip.tools/eip/8021) — the specification itself.
- [Builder Code Validation tool](https://builder-code-checker.vercel.app/) — check a hash for attribution.
- [Base Dashboard](https://dashboard.base.org/) — registration, project settings, and your code.
---
# Connecting to Base
Source: https://basehub.org/integration-guides/connecting/
Description: Connect to Base mainnet or Sepolia using public endpoints, your own node, or a third-party provider.
import CodeColumns from '../../../components/CodeColumns.astro';
Connect to Base mainnet or the Sepolia testnet using public RPC endpoints, your own node, or a third-party provider.
## Network parameters
### Base Mainnet
| Parameter | Value |
|-----------|-------|
| Network name | Base |
| Chain ID | `8453` (`0x2105`) |
| Currency | ETH |
| Block time | 2 seconds |
| Flashblock interval | 200ms |
| L1 settlement | Ethereum Mainnet |
| Explorer | [basescan.org](https://basescan.org) |
### Base Sepolia (testnet)
| Parameter | Value |
|-----------|-------|
| Network name | Base Sepolia |
| Chain ID | `84532` (`0x14a34`) |
| Currency | ETH (testnet) |
| Block time | 2 seconds |
| L1 settlement | Ethereum Sepolia |
| Explorer | [sepolia.basescan.org](https://sepolia.basescan.org) |
## Public RPC endpoints
Base provides public RPC endpoints for general use. They serve HTTP only:
| Network | HTTP Endpoint | WebSocket |
|---------|---------------|-----------|
| Mainnet | `https://mainnet.base.org` | none |
| Sepolia | `https://sepolia.base.org` | none |
:::caution[There is no free public WebSocket on Mainnet or Sepolia]
Base does not run a public WebSocket RPC endpoint on either network. A `wss://` handshake against `mainnet.base.org` or `sepolia.base.org` is refused with `405 Method Not Allowed`, while the same host answers HTTP JSON-RPC normally. Anything that needs `eth_subscribe`, `newHeads`, or log streaming has to come from your own node or a WebSocket-capable provider.
Base Vibenet is the exception. It publishes an open WebSocket at `wss://rpc.vibes.base.org/ws`, which makes it the cheapest place to prototype subscription code.
:::
### Transaction submission endpoints
Base also publishes a separate host on each network for sending transactions straight to the sequencer:
| Network | Transaction submission |
|---------|------------------------|
| Mainnet | `https://mainnet-sequencer.base.org` |
| Sepolia | `https://sepolia-sequencer.base.org` |
Point only transaction sends at these hosts, and keep every other call on the regular RPC endpoint. They are not general-purpose RPC: a probe on 2026-09-30 showed both hosts answering `eth_chainId` with `rpc method is not allowed`. Since Cobalt, both hosts also serve `base_sendRawTransactionValidity`; see [Validity Transactions](/api-reference/validity-transactions/).
:::note
Public endpoints are rate-limited and intended for development and light usage. For production, run your own node or use a third-party provider.
From **October 8, 2026 at 12:00 UTC**, `https://mainnet.base.org` no longer serves the `debug`, `trace`, or `txpool` namespaces, and basic reads get a lower rate limit. Use a [node provider](/node-operations/node-providers/) for those namespaces or for higher throughput.
:::
## Connecting with common tools
### curl
A raw JSON-RPC `POST` request returns the latest block number as a hex string.
This is the lowest-common-denominator way to talk to Base — useful for sanity-checking that an endpoint is alive.
viem ships chain definitions for both Base networks. `createPublicClient` selects the right RPC defaults automatically.
```typescript
import { createPublicClient, http } from "viem";
import { base, baseSepolia } from "viem/chains";
const client = createPublicClient({
chain: base,
transport: http(),
});
const blockNumber = await client.getBlockNumber();
console.log("Current block:", blockNumber);
const testnetClient = createPublicClient({
chain: baseSepolia,
transport: http(),
});
```
### MetaMask / wallet configuration
To add Base to a wallet manually:
| Field | Mainnet | Sepolia |
|-------|---------|---------|
| Network Name | Base | Base Sepolia |
| RPC URL | `https://mainnet.base.org` | `https://sepolia.base.org` |
| Chain ID | `8453` | `84532` |
| Currency Symbol | ETH | ETH |
| Block Explorer URL | `https://basescan.org` | `https://sepolia.basescan.org` |
## Running your own node
For production, running your own Base node gives full control over rate limits, latency, and data availability.
### Quick start
The fastest path is the pre-built Docker image:
```bash
docker pull ghcr.io/base/base-reth-node:latest
docker run -d \
--name base-node \
-p 8545:8545 \
-p 8546:8546 \
-p 30303:30303 \
-v base-data:/data \
ghcr.io/base/base-reth-node:latest \
--http \
--http.addr 0.0.0.0 \
--http.port 8545 \
--http.api eth,net,web3,txpool \
--ws \
--ws.addr 0.0.0.0 \
--ws.port 8546
```
For full instructions:
- [Building from source](/getting-started/building/) — compile the node binary.
- [Running the node](/getting-started/running/) — configuration and startup.
- [Docker](/getting-started/docker/) — containerized deployment.
- [Node deployment](/node-operations/deployment/) — production deployment guide.
### Node sync modes
| Mode | Description | Disk usage | Sync time |
|------|-------------|------------|-----------|
| Full | Executes all transactions from genesis. | High | Days |
| Snap | Downloads state snapshots, then follows chain tip. | Moderate | Hours |
## JSON-RPC interface
Base nodes expose the standard Ethereum JSON-RPC interface. The following namespaces are available:
### Standard namespaces
| Namespace | Description |
|-----------|-------------|
| `eth` | Core Ethereum methods — blocks, transactions, state queries, gas estimation. |
| `net` | Network information — peer count, version, listening status. |
| `web3` | Utility methods — client version, SHA3. |
| `txpool` | Transaction pool inspection (see [Transaction Pool](/integration-guides/txpool/)). |
| `debug` | Debug methods — trace transactions, get raw block data (enable with `--http.api debug`). |
### Base-specific namespaces
| Namespace | Description |
|-----------|-------------|
| `base` | Base-specific methods including metering (see [Metering RPC](/integration-guides/metering-rpc/)). |
### Commonly used methods
| Method | Description |
|--------|-------------|
| `eth_blockNumber` | Returns the latest block number. |
| `eth_getBlockByNumber` | Returns block data by number or tag. |
| `eth_getBlockByHash` | Returns block data by hash. |
| `eth_getTransactionByHash` | Returns a transaction by hash. |
| `eth_getTransactionReceipt` | Returns a transaction receipt. |
| `eth_getBalance` | Returns account balance. |
| `eth_getTransactionCount` | Returns account nonce. |
| `eth_call` | Executes a call without creating a transaction. |
| `eth_estimateGas` | Estimates gas for a transaction. |
| `eth_sendRawTransaction` | Submits a signed transaction. |
| `eth_getCode` | Returns contract bytecode. |
| `eth_getStorageAt` | Returns storage value at a given position. |
| `eth_getLogs` | Returns logs matching a filter. |
| `eth_chainId` | Returns the chain ID. |
### Flashblocks support
The `"pending"` block tag is supported across applicable methods when flashblocks are enabled. See [Flashblocks RPC](/integration-guides/flashblocks-rpc/) for details on querying preconfirmed state.
## Troubleshooting
### Common issues
| Issue | Cause | Solution |
|-------|-------|----------|
| `429 Too Many Requests` | Rate limit exceeded on public endpoint. | Reduce request frequency or run your own node. |
| Connection refused on port 8545 | Node HTTP RPC not enabled. | Start the node with `--http` and `--http.addr 0.0.0.0`. |
| Empty response for `eth_getLogs` | Block range too large. | Reduce the `fromBlock`/`toBlock` range (max ~2000 blocks per query). |
| Wrong chain ID | Connected to wrong network. | Verify the RPC URL matches the intended network. |
| `nonce too low` | Transaction nonce already used. | Use `"pending"` tag with `eth_getTransactionCount` for the latest nonce. |
## Further reading
- [Flashblocks RPC](/integration-guides/flashblocks-rpc/) — query preconfirmed state with the `"pending"` tag.
- [Transaction Pool](/integration-guides/txpool/) — inspect and manage the txpool.
- [Metering RPC](/integration-guides/metering-rpc/) — resource metering API.
- [Node configuration](/node-operations/configuration/) — detailed node configuration options.
- [Monitoring](/node-operations/monitoring/) — observability and metrics.
---
# DeFi Integrations
Source: https://basehub.org/integration-guides/defi-integrations/
Description: Adding swaps, lending, borrowing, and vault-based earn to an app on Base — the 0x AllowanceHolder flow, approval hazards, and what a safe position UI has to show before a user signs.
import { Aside } from '@astrojs/starlight/components';
Trading, lending, borrowing, and earn products on Base are built on third-party protocols rather than anything the chain provides. Your app's job is to prepare and simulate a call, show the user what it will do, and let them sign it from their own wallet. The position lives with the protocol, not with you.
## Swaps through an aggregator
The 0x Swap API searches liquidity across exchanges and market makers and hands back a transaction the wallet can simulate, sign, and submit. The AllowanceHolder flow runs in four steps:
1. Ask for an indicative `/price` while the user is still editing the trade.
2. Ask for a firm `/quote` once they are ready to review and sign.
3. If the quote reports `issues.allowance`, approve the returned `spender` — for the sell amount only.
4. Take a fresh quote, simulate its `transaction`, submit, and wait for confirmation.
Requests carry `chainId` `8453` for Base mainnet and an API key that belongs on your server, never in the client. The quote's own diagnostics are worth reading before you prompt anyone: `liquidityAvailable` tells you whether a route exists at all, and `issues.balance` catches an underfunded taker before the wallet does.
Refreshing the quote after approval is not optional bookkeeping. Prices move between the quote and the signature, and `minBuyAmount` is what protects the user from the difference. Keep the quote request on your backend, return the reviewed transaction fields to the frontend, and submit from the connected wallet.
## Supplying to a money market
Lending is a supply call against a market the protocol defines. Your app prepares and simulates it; the user signs. What you owe them is an accurate picture of the terms at signing time.
## Borrowing against collateral
Borrowing adds a liquidation surface, which makes the display requirement stricter rather than merely advisable. Show collateral value, outstanding debt, the liquidation parameters, and position health — both as they stand and as they would stand after the action.
Health is not static between render and signature. Collateral prices move, oracles update, and interest accrues, so re-fetch immediately before the user signs rather than trusting a value fetched when the screen was drawn. If an action would leave the position unsafe, say so plainly before it is signed, not after.
## Vault-based earn
An earn product is the one-deposit case: the user deposits once and receives vault shares, and the vault handles allocation across its underlying markets. Morpho's vaults follow the ERC-4626 shape, so share accounting and redemption previews use the interface you already know.
The abstraction is the selling point and also the thing to be careful about. Because the user sees one balance rather than a set of positions, your interface carries the whole burden of showing current redeemable value and the risk behind it. Shares are not a stable unit of account — quote value by converting through the vault, never by treating one share as one token.
---
# Flashblocks RPC
Source: https://basehub.org/integration-guides/flashblocks-rpc/
Description: Read preconfirmed Base state and stream sub-block updates over JSON-RPC and WebSocket.
import CodeColumns from '../../../components/CodeColumns.astro';
Flashblocks are sub-block preconfirmations produced every 200ms on Base. Read preconfirmed balances, nonces, receipts, and block data through standard JSON-RPC, or stream every flashblock as it lands.
## Overview
A single Base block (produced every 2 seconds) is divided into ten **flashblocks** streamed at 200ms intervals. Each flashblock is a delta containing new transactions and the resulting state changes. The Flashblocks RPC exposes this preconfirmed state through the standard Ethereum JSON-RPC interface by supporting the `"pending"` block tag.
```
Block N (2s)
├── Flashblock 0 (0ms)
├── Flashblock 1 (200ms)
├── Flashblock 2 (400ms)
├── Flashblock 3 (600ms)
├── Flashblock 4 (800ms)
├── Flashblock 5 (1000ms)
├── Flashblock 6 (1200ms)
├── Flashblock 7 (1400ms)
├── Flashblock 8 (1600ms)
└── Flashblock 9 (1800ms)
Block N+1 (2s)
└── ...
```
## Querying preconfirmed state
Pass `"pending"` to any supported JSON-RPC method to read the latest preconfirmed state. The same call against `"latest"` returns the last sealed block.
### Check an account balance
`eth_getBalance` with the `"pending"` tag returns the balance reflecting every transaction included in the most recent flashblock — usually within 200ms of the user's submission.
The hex `result` is the balance in wei.
After submitting a transaction, poll `eth_getTransactionReceipt` immediately — no need to wait for the next sealed block.
A preconfirmed receipt is identifiable by its zero `blockHash`. Once the parent block seals, the same receipt comes back with a real block hash.
`eth_getBlockByNumber` with `"pending"` returns the in-progress block including every transaction landed in flashblocks so far.
Pass `true` as the second parameter for full transaction objects, `false` for hashes only.
```bash
curl -X POST https://your-base-rpc-endpoint \
-H "Content-Type: application/json" \
-d '{
"method": "eth_getBlockByNumber",
"params": ["pending", true],
"id": 1,
"jsonrpc": "2.0"
}'
```
### Get the pending nonce
`eth_getTransactionCount` against `"pending"` returns a nonce that already accounts for transactions sitting in flashblocks.
This avoids nonce collisions when an account submits many transactions in rapid succession.
Pass `"pending"` as the block tag to any read method to get preconfirmed values.
For receipts, poll `getTransactionReceipt` on a 200ms interval — that matches the flashblock cadence.
```javascript
import { JsonRpcProvider } from "ethers";
const provider = new JsonRpcProvider("https://your-base-rpc-endpoint");
const balance = await provider.getBalance("0xYourAddress", "pending");
const nonce = await provider.getTransactionCount("0xYourAddress", "pending");
async function waitForFlashblockReceipt(txHash, intervalMs = 200) {
while (true) {
const receipt = await provider.getTransactionReceipt(txHash);
if (receipt) return receipt;
await new Promise((r) => setTimeout(r, intervalMs));
}
}
```
### viem
viem accepts `blockTag: "pending"` on every read method. Receipts return as soon as the transaction is included in a flashblock.
```typescript
import { createPublicClient, http } from "viem";
import { base } from "viem/chains";
const client = createPublicClient({
chain: base,
transport: http("https://your-base-rpc-endpoint"),
});
const balance = await client.getBalance({
address: "0xYourAddress",
blockTag: "pending",
});
const nonce = await client.getTransactionCount({
address: "0xYourAddress",
blockTag: "pending",
});
const receipt = await client.getTransactionReceipt({
hash: "0xYourTxHash",
});
```
## WebSocket streaming
For real-time updates, connect to the WebSocket endpoint and subscribe to `flashblocks_v1`. Each flashblock arrives as it is produced — five times per second.
### Subscribing
Open a WebSocket, send an `eth_subscribe` request with the `flashblocks_v1` topic, and handle each `eth_subscription` message as it arrives.
`flashblock.diff` carries the new transactions and state changes since the previous flashblock; `flashblock.index` runs from 0 to 9 within each parent block.
```javascript
import WebSocket from "ws";
const ws = new WebSocket("wss://your-base-ws-endpoint");
ws.on("open", () => {
ws.send(
JSON.stringify({
jsonrpc: "2.0",
id: 1,
method: "eth_subscribe",
params: ["flashblocks_v1"],
})
);
});
ws.on("message", (data) => {
const msg = JSON.parse(data);
if (msg.method === "eth_subscription") {
const flashblock = msg.params.result;
console.log("Index:", flashblock.index);
console.log("Txs:", flashblock.diff.transactions?.length ?? 0);
}
});
```
### Flashblock payload structure
Each streamed flashblock contains:
| Field | Description |
|-------|-------------|
| `payload_id` | Identifier for the parent payload (block being built). |
| `index` | Flashblock index within the current block (0, 1, 2, ...). |
| `base` | Present only on index 0. Contains the base execution payload. |
| `diff` | Delta of transactions, receipts, and state changes since the previous flashblock. |
| `metadata` | Additional metadata, including the flashblock access list if enabled. |
## Error handling and fallback
### Automatic fallback
When the `"pending"` tag is used but no preconfirmed data is available — for example, during sequencer downtime or between blocks — the RPC falls back to the `"latest"` confirmed state. That means:
- Applications do not need special error handling for missing flashblock state.
- Results are always consistent: either preconfirmed or latest confirmed.
- The caller cannot distinguish a "pending equals latest" response from a fallback, so applications should not assume the data is fresher than the latest block.
### Error responses
Standard JSON-RPC error codes apply:
| Scenario | Behavior |
|----------|----------|
| Invalid method parameters | Standard JSON-RPC error response with error code and message. |
| Transaction not found | `null` result (not an error). |
| Block not found | `null` result (not an error). |
| Flashblocks disabled | Falls back to standard RPC behavior. No error is returned. |
### Detecting preconfirmed vs. finalized
A preconfirmed receipt can be identified by its `blockHash`:
- **Preconfirmed** — `blockHash` is the zero hash.
- **Finalized** — `blockHash` is a real block hash.
```javascript
function isPreconfirmed(receipt) {
return (
receipt.blockHash ===
"0x0000000000000000000000000000000000000000000000000000000000000000"
);
}
```
## Further reading
- [Flashblocks specification](/specifications/flashblocks/) — full RPC method reference with parameter and return type details.
- [Access lists specification](/specifications/access-lists/) — the FAL spec that accompanies flashblocks.
- [Flashblocks pipeline](/architecture/flashblocks-pipeline/) — how flashblocks are produced and streamed internally.
---
# Launch a B20 Token
Source: https://basehub.org/integration-guides/launch-a-b20-token/
Description: End-to-end workflow for creating a B20 Asset or Stablecoin token — Base's Foundry build, the Activation Registry check, a B20FactoryLib create script, minting, and onchain verification.
import { Aside, Tabs, TabItem } from '@astrojs/starlight/components';
A B20 token needs no contract of your own. The [B20 standard](/specifications/b20/) lives in the chain as a precompile, so access control, pause switches, cap enforcement, policy gates, memo fields, and ERC-2612 `permit` are all already there before you write a line of Solidity. One call to the factory hands back a configured token. Nothing to deploy, nothing to audit, nothing to maintain.
This guide takes an Asset token from nothing to a verified onchain balance. The reference material sits elsewhere: [the specification](/specifications/b20/) for behaviour, [the precompile reference](/api-reference/b20-precompiles/) for selectors and ABIs.
## Pick a variant first
The singleton **B20 Factory** builds both variants, and the choice is fixed at creation:
- **Asset** — decimals are yours to set anywhere in `[6, 18]`. It also gains batched issuance, announcements published onchain, and a rebase multiplier. Reach for it with long-tail tokens, real-world assets, and equities.
- **Stablecoin** — decimals are pinned at 6, and the token carries an immutable ISO currency code instead. This is the variant for fiat-backed tokens.
Past that split the two behave identically. Both get the same roles, caps, policies, pause controls, memos, and `permit`.
The steps below use `ASSET`. A stablecoin swaps two lines, shown at the end of the create step.
## Install Base's Foundry build
Stock Foundry cannot do this work. B20 precompiles sit at fixed addresses that hold no bytecode, so `forge` refuses the call with `call to non-contract address`. Base ships `base-forge`, `base-cast`, and [`base-anvil`](https://github.com/base/base-anvil), which register those addresses into the EVM. They install beside your existing Foundry rather than over it.
Pin the Beryl-compatible release:
```bash
curl -L https://raw.githubusercontent.com/base/base-anvil/HEAD/foundryup/install | bash
base-foundryup --install v1.1.1
```
## Confirm the feature is switched on
Each variant is gated separately by the Activation Registry. Deploy against a network where the gate is closed and the call reverts with `FeatureNotActivated`. Check before you spend gas — query the variant you plan to use and read `true` back:
```bash
REG=0x8453000000000000000000000000000000000001 # Activation Registry precompile
RPC=https://mainnet.base.org # replace with your target network (e.g. https://sepolia.base.org, https://rpc.vibes.base.org)
base-cast call $REG "isActivated(bytes32)(bool)" $(base-cast keccak "base.b20_asset") --rpc-url $RPC
base-cast call $REG "isActivated(bytes32)(bool)" $(base-cast keccak "base.b20_stablecoin") --rpc-url $RPC
```
## Set up the project
```bash
base-forge init b20-quickstart && cd b20-quickstart
base-forge install base/base-std@v1.0.0 --no-git
```
That pulls in [Base Standard Library v1.0.0](https://github.com/base/base-std/tree/v1.0.0), which is where the shipped Beryl interfaces live, along with the constants and the helpers that encode calls for you.
Then add the remappings to `foundry.toml`, under `[profile.default]`. The `base = true` flag is what puts the precompiles inside the build's EVM, which is what lets the deploy script simulate its own factory call locally:
```toml
base = true
remappings = [
"base-std/=lib/base-std/src/",
"base-std-test/=lib/base-std/test/",
]
```
Any Solidity in `>=0.8.20 <0.9.0` compiles the interfaces.
## Choose a network
Create a `.env` **inside `b20-quickstart`** for the network you picked. [Connecting to Base](/introduction/connecting-to-base/) has the full network table.
| Setting | Value |
|---|---|
| RPC URL | `https://mainnet.base.org` |
| Chain ID | `8453` |
| Explorer | [basescan.org](https://basescan.org) |
```bash
export RPC_URL="https://mainnet.base.org"
export PRIVATE_KEY="0x..."
export ACCOUNT_ADDRESS="0x..."
export CHAIN_ID="8453"
```
| Setting | Value |
|---|---|
| RPC URL | `https://sepolia.base.org` |
| Chain ID | `84532` |
| Faucet | [CDP Faucet](https://portal.cdp.coinbase.com/products/faucet) |
| Explorer | [sepolia.basescan.org](https://sepolia.basescan.org) |
```bash
export RPC_URL="https://sepolia.base.org"
export PRIVATE_KEY="0x..."
export ACCOUNT_ADDRESS="0x..."
export CHAIN_ID="84532"
```
| Setting | Value |
|---|---|
| RPC URL | `https://rpc.vibes.base.org/` |
| Chain ID | `84538453` |
| Faucet | [chain.base.org/vibenet/faucet](https://chain.base.org/vibenet/faucet) |
| Explorer | [chain.base.org/vibenet/explorer](https://chain.base.org/vibenet/explorer) |
```bash
export RPC_URL="https://rpc.vibes.base.org/"
export PRIVATE_KEY="0x..."
export ACCOUNT_ADDRESS="0x..."
export CHAIN_ID="84538453"
```
Run a Base node in another terminal:
```bash
base-anvil
```
Anvil's first pre-funded account is enough:
```bash
export RPC_URL="http://127.0.0.1:8545"
export PRIVATE_KEY="0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80"
export ACCOUNT_ADDRESS="0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266"
export CHAIN_ID="31337"
```
`base-cast wallet new` prints a fresh address and key if you need one. Check the account holds gas before continuing — it signs both the create and the mint, and the supply lands there:
```bash
source .env
base-cast balance $ACCOUNT_ADDRESS --rpc-url $RPC_URL
```
Against local anvil that prints `10000000000000000000000`, its default 10,000 ETH. Anywhere else, any non-zero number will do.
## Create the token
The factory exposes one entry point, `createB20(variant, salt, params, initCalls)`, and its four arguments are the whole configuration surface:
- `variant` — `ASSET` or `STABLECOIN`.
- `salt` — entropy you choose, which determines the token's deterministic address.
- `params` — name, symbol, first admin, and decimals, ABI-encoded.
- `initCalls` — configuration applied in the same transaction as creation.
Encode both `params` and `initCalls` with `B20FactoryLib`. Write `script/CreateToken.s.sol`:
```solidity
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;
import {Script, console} from "forge-std/Script.sol";
import {B20Constants} from "base-std/lib/B20Constants.sol";
import {B20FactoryLib} from "base-std/lib/B20FactoryLib.sol";
import {IB20Factory} from "base-std/interfaces/IB20Factory.sol";
import {StdPrecompiles} from "base-std/StdPrecompiles.sol";
contract CreateToken is Script {
function run() external returns (address token) {
// For the quickstart, one account is admin + minter.
address account = vm.envAddress("ACCOUNT_ADDRESS");
bytes32 salt = keccak256("my-first-b20");
// Name, symbol, initial DEFAULT_ADMIN_ROLE holder, decimals (6-18).
bytes memory params = B20FactoryLib.encodeAssetCreateParams("My Token", "MYT", account, 18);
// Configuration applied atomically at creation.
bytes[] memory initCalls = new bytes[](2);
initCalls[0] = B20FactoryLib.encodeGrantRole(B20Constants.MINT_ROLE, account);
initCalls[1] = B20FactoryLib.encodeUpdateSupplyCap(1_000_000e18);
vm.startBroadcast();
token = StdPrecompiles.B20_FACTORY.createB20(IB20Factory.B20Variant.ASSET, salt, params, initCalls);
vm.stopBroadcast();
console.log("B20 token created at:", token);
}
}
```
Two constraints worth knowing before you run it. Asset decimals are locked in at creation and have to land in `[6, 18]`. The supply cap is optional — pass `type(uint128).max` to mean no cap, which is also the ceiling the cap can never exceed.
Broadcast it:
```bash
source .env
base-forge script script/CreateToken.s.sol --rpc-url $RPC_URL --private-key $PRIVATE_KEY --broadcast
```
The factory answers from `0xB20f000000000000000000000000000000000000`, the same address on every network, and the tokens it mints all begin `0xB200...`. The script logs the one it made:
```text
== Logs ==
B20 token created at: 0xB200...
```
A `TokenAlreadyExists` revert means `keccak256("my-first-b20")` has already been used by your account on that network. Change the salt, or restart `base-anvil` for a clean slate.
Pull the address out of the broadcast artifact so nothing needs copying by hand. Appending it to `.env` keeps it around for later steps and later shells:
```bash
TOKEN_ADDRESS=$(jq -er '.returns.token.value' \
broadcast/CreateToken.s.sol/$CHAIN_ID/run-latest.json) \
&& echo "export TOKEN_ADDRESS=$TOKEN_ADDRESS" >> .env \
&& source .env \
&& echo "TOKEN_ADDRESS=$TOKEN_ADDRESS"
```
The artifact path carries the chain ID, which is where the `CHAIN_ID` you exported earns its place.
### Making a stablecoin instead
Change the variant and the params encoder. The ISO currency code is uppercase `A`–`Z` and immutable, and it takes the place of the decimals argument:
```solidity
bytes memory params = B20FactoryLib.encodeStablecoinCreateParams("My USD", "MUSD", account, "USD");
token = StdPrecompiles.B20_FACTORY.createB20(IB20Factory.B20Variant.STABLECOIN, salt, params, initCalls);
```
Roles, caps, minting, and verification are unchanged.
## Mint and verify
`initCalls` already granted `MINT_ROLE` to your account, so this works straight away:
```bash
base-cast send $TOKEN_ADDRESS "mint(address,uint256)" $ACCOUNT_ADDRESS 1000000000000000000000 \
--rpc-url $RPC_URL --private-key $PRIVATE_KEY
```
A receipt with `status 1 (success)` means it landed. Read the balance back:
```bash
base-cast call $TOKEN_ADDRESS "balanceOf(address)(uint256)" $ACCOUNT_ADDRESS --rpc-url $RPC_URL
# 1000000000000000000000 [1e21]
```
Search `$TOKEN_ADDRESS` in the explorer and the token is there.
## Calling the token from an app
For application code rather than operational commands, upstream's examples run on `viem@2.55.11`. Nothing about the client is B20-specific — a B20 token answers the ERC-20 surface natively, so an ordinary viem client reads and writes it:
```bash
mkdir b20-viem && cd b20-viem
npm init -y
npm install viem@2.55.11
```
```typescript
import { createPublicClient, createWalletClient, http } from 'viem';
import { privateKeyToAccount } from 'viem/accounts';
import { baseSepolia } from 'viem/chains';
if (!process.env.PRIVATE_KEY) throw new Error('Set PRIVATE_KEY');
export const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`);
export const publicClient = createPublicClient({
chain: baseSepolia,
transport: http(process.env.RPC_URL ?? 'https://sepolia.base.org'),
});
export const walletClient = createWalletClient({
account,
chain: baseSepolia,
transport: http(process.env.RPC_URL ?? 'https://sepolia.base.org'),
});
```
Scripts that create policies need `jq` as well, to lift `PolicyCreated` out of a transaction receipt.
## Where to go next
You now have a token with an admin, a minter, a supply cap, and real supply — none of it written by you.
- Gate transfers or mints behind PolicyRegistry policies, narrow the pause surface, or hand roles around. [The B20 specification](/specifications/b20/) covers all three.
- [Tokenized Stocks](/integration-guides/tokenized-stocks/) shows the same primitives configured for a real-world underlying.
- [B20 precompiles](/api-reference/b20-precompiles/) lists every selector, event `topic0`, and revert.
- [B20 invariants](/api-reference/b20-invariants/) states what the chain guarantees regardless of configuration.
---
# Metering RPC
Source: https://basehub.org/integration-guides/metering-rpc/
Description: Simulate transactions to return gas estimates, resource breakdowns, and builder metering metadata.
The Metering API simulates a transaction against current state and returns gas estimates, per-resource consumption, and the metering metadata the builder uses to price and prioritize inclusion.
## What Metering Provides
Traditional gas estimation (`eth_estimateGas`) returns a single number. The Metering API goes further by simulating transactions against the current state and reporting:
- **Gas consumption** -- total gas used, broken down by execution phase.
- **Resource usage** -- compute, storage reads, storage writes, and memory allocation.
- **Metering metadata** -- information used by the block builder to price and prioritize transactions.
This is particularly useful for:
- Block builders that need to meter transactions for optimal block packing.
- Applications that want to display detailed cost breakdowns to users.
- MEV searchers estimating transaction costs against live state.
## Relevant Crates
The metering system is implemented across two crates in the `base/base` workspace:
| Crate | Description |
|-------|-------------|
| `base-metering` | Core metering logic -- simulates transactions and computes resource consumption metrics. |
| `base-builder-metering` | Builder-specific metering integration -- connects metering to the block building pipeline. |
These crates live under [`crates/builder/`](https://github.com/base/base/tree/main/crates/builder) in the repository.
## RPC Endpoints
### `base_estimateMeteredGas`
Simulates a transaction and returns a detailed metering report.
#### Parameters
| Name | Type | Description |
|------|------|-------------|
| `transaction` | `Object` | Transaction call object (`from`, `to`, `data`, `value`, `gas`, etc.). |
| `blockNumber` | `String` | Block tag or number. Use `"latest"` or `"pending"` for current state. |
#### Returns
`Object` -- Metering result containing gas estimates and resource breakdown.
#### Example
```bash
curl -X POST https://your-base-rpc-endpoint \
-H "Content-Type: application/json" \
-d '{
"method": "base_estimateMeteredGas",
"params": [
{
"from": "0xSenderAddress",
"to": "0xContractAddress",
"data": "0xCalldata"
},
"latest"
],
"id": 1,
"jsonrpc": "2.0"
}'
```
```json
{
"id": 1,
"jsonrpc": "2.0",
"result": {
"gasUsed": "0x1a4c0",
"gasLimit": "0x1e848",
"computeUnits": "0x3200",
"storageReads": "0x5",
"storageWrites": "0x2",
"success": true
}
}
```
### `base_getMeteringConfig`
Returns the current metering configuration parameters used by the builder.
#### Parameters
None.
#### Returns
`Object` -- Metering configuration including resource weights and limits.
#### Example
```bash
curl -X POST https://your-base-rpc-endpoint \
-H "Content-Type: application/json" \
-d '{
"method": "base_getMeteringConfig",
"params": [],
"id": 1,
"jsonrpc": "2.0"
}'
```
```json
{
"id": 1,
"jsonrpc": "2.0",
"result": {
"computeWeight": 1,
"storageReadWeight": 2,
"storageWriteWeight": 5,
"maxComputeUnitsPerBlock": "0x989680",
"maxStorageReadsPerBlock": "0x493e0",
"maxStorageWritesPerBlock": "0x186a0"
}
}
```
## Usage with ethers.js
```javascript
import { JsonRpcProvider } from "ethers";
const provider = new JsonRpcProvider("https://your-base-rpc-endpoint");
// Estimate metered gas for a transaction
async function estimateMeteredGas(tx) {
const result = await provider.send("base_estimateMeteredGas", [
{
from: tx.from,
to: tx.to,
data: tx.data,
value: tx.value ?? "0x0",
},
"latest",
]);
console.log("Gas used:", parseInt(result.gasUsed, 16));
console.log("Compute units:", parseInt(result.computeUnits, 16));
console.log("Storage reads:", parseInt(result.storageReads, 16));
console.log("Storage writes:", parseInt(result.storageWrites, 16));
console.log("Success:", result.success);
return result;
}
```
## Usage with viem
```typescript
import { createPublicClient, http } from "viem";
import { base } from "viem/chains";
const client = createPublicClient({
chain: base,
transport: http("https://your-base-rpc-endpoint"),
});
// Estimate metered gas
const result = await client.request({
method: "base_estimateMeteredGas" as any,
params: [
{
from: "0xSenderAddress",
to: "0xContractAddress",
data: "0xCalldata",
},
"latest",
],
});
```
## How Metering Works
The metering pipeline operates as follows:
1. **Transaction submission** -- a transaction (or call object) is submitted to the metering RPC.
2. **State simulation** -- the transaction is executed against the current (or specified) state using the EVM, with metering instrumentation enabled.
3. **Resource accounting** -- during simulation, the metering engine tracks compute cycles, storage operations, and memory usage.
4. **Result assembly** -- the raw resource counts are combined with the current metering configuration (weights) to produce the final metering report.
5. **Builder integration** -- when used by the block builder, metering results feed into transaction ordering and block packing decisions.
```
Transaction
│
▼
┌──────────────────┐
│ EVM Simulation │
│ (base-metering) │
└────────┬─────────┘
│
▼
┌──────────────────────────┐
│ Resource Accounting │
│ compute, storage, memory │
└────────┬─────────────────┘
│
▼
┌──────────────────────────────┐
│ Metering Report │
│ gas, compute units, storage │
└──────────────────────────────┘
```
## Error Handling
| Scenario | Behavior |
|----------|----------|
| Transaction reverts during simulation | `success: false` in the result; gas and resource fields still populated. |
| Invalid transaction parameters | Standard JSON-RPC error response. |
| State unavailable for requested block | JSON-RPC error with appropriate code. |
## Further Reading
- [Crate Reference](/crates/overview/) -- overview of all crate groups, including the builder crates.
- [Execution Pipeline](/architecture/execution-pipeline/) -- how the EVM and state management work.
---
# Private Transactions (Base Ledgers)
Source: https://basehub.org/integration-guides/private-transactions/
Description: Base Ledgers keeps balances, transfers, and counterparties off the public chain while funds still settle on Base through one Portal contract. What each step exposes, and what stays hidden.
import { Aside } from '@astrojs/starlight/components';
A Base ledger is a private accounting layer that sits beside Base and settles through it. Money enters and leaves through a single `Portal` contract on Base. Everything that happens between those two calls stays off public block explorers: who holds what, who paid whom, and how much.
The operator of a ledger owns the parts a public chain cannot provide. They run the KYC and compliance gate. They hold the funds in a contract they control, so custody stays with them. They also choose the logic that processes transactions inside the ledger, and the rule the `Portal` uses to release a withdrawal.
Upstream has published the model and the privacy boundaries, but no contract address, ABI, or SDK yet. This page covers what is public so far.
## Where it fits
The use cases upstream names share one trait: the payment itself is routine, but the counterparty list or amounts are commercially sensitive.
- **B2B payments.** Pay suppliers without publishing who your suppliers are.
- **Payroll and payouts.** Pay staff and contractors onchain without exposing each person's pay.
- **Treasury.** Shift balances between your own accounts, custodians, and counterparties out of public view.
- **Cross-border remittance.** Run KYC-gated corridors where neither party nor the amount is visible.
## The three steps
Funds follow the same path every time: in through the `Portal`, around inside the ledger, and back out through the `Portal`. Each step reveals a different set of fields, so the privacy you get depends on which step an observer is watching.
| Field | Deposit | Transfer inside the ledger | Withdraw |
|---|---|---|---|
| Asset | Public | Hidden | Public |
| Amount | Public | Hidden | Public |
| Sender | Public | Hidden | Hidden |
| Recipient | Hidden | Hidden | Public |
### Deposit
A deposit is a call to the `Portal` on Base, so it settles in the open. Anyone can see the asset, the amount, and the address that sent it. The recipient is the exception. It is encrypted onchain, so a series of deposits into one ledger account cannot be tied together or traced to that account.
The operator can also put a gate on deposits, such as requiring an attestation or a permission before a given address can fund the ledger.
### Transfer inside the ledger
After funds are inside, accounts can send to each other, swap, and earn yield with nothing written to Base. Sender, recipient, amount, and even the fact that activity happened stay inside the ledger. Only deposits and withdrawals touch the chain.
The ledger does not dictate the offchain system behind it. The operator keeps their own books and writes their own transaction logic.
### Withdraw
A withdrawal is the mirror of a deposit. The `Portal` releases funds on Base, so the asset, the amount, and the receiving address are public. The ledger account the money came from is not revealed. Because deposits hide the recipient and withdrawals hide the sender, an observer cannot pair a deposit with the withdrawal that later drained it.
The operator decides how strict the `Portal` is before it pays out. The range runs from a simple signature check to full state-transition proofs, which is the main trust decision a ledger operator makes.
`withdraw()` is a normal Base contract call. You can bundle it with other Base actions in one atomic transaction, such as withdraw-and-swap, and the whole bundle either lands or reverts together. Deposits compose the same way, for example deposit-and-act.
---
# Tokenized Stocks
Source: https://basehub.org/integration-guides/tokenized-stocks/
Description: Integrating tokenized equities on Base — B20 multipliers, transfer policies, corporate actions, Chainlink price feeds, and the deployed token addresses.
import { Aside } from '@astrojs/starlight/components';
Tokenized equities on Base are not a bespoke contract family. They are ordinary [B20](/specifications/b20/) tokens — Base's native token standard — configured for a real-world underlying. B20 itself takes no position on what backs a token, so equities are one application of it among several. Product-level questions about the Coinbase offering are answered at [coinbase.com/tokenize](https://coinbase.com/tokenize), not here; this page covers what an integrator has to handle onchain.
## Listing and discovery
From a wallet or indexer's point of view these behave like any ERC-20. Name, symbol, and icon come from the places you already look, and the standard ERC-20 call and event surface works natively. Two details are specific to B20:
- Read metadata onchain through [`name`](/api-reference/b20-precompiles/), `symbol`, `decimals`, and `contractURI` — the last being [ERC-7572](https://eips.ethereum.org/EIPS/eip-7572) collection metadata. Logos are also carried in the canonical token list and by the usual market-data aggregators.
- Watch the `B20Created` event to pick up new tokens as they appear.
- Or skip the onchain reads: the public [Tokenized Stocks API](/api-reference/tokenized-stocks-api/) returns each token's address, symbol, name, decimals, icon URL, and ISIN in one request, with no key needed.
## What the equity case adds over ERC-20
### Multipliers
Corporate actions on the underlying share change how much equity one token redeems for. Dividends and splits are the common cases, and both have to reach the holder onchain. B20 handles this with a [multiplier](/specifications/b20/#multiplier): a single value that restates the redemption ratio, so every holder's position tracks the corporate action without any balance moving.
Say a dividend lands. The multiplier moves to `1.02`, and one token now redeems for 1.02 shares. Cash dividends, for the present, get converted into shares of the underlying and expressed the same way, rather than reaching the token holder as cash.
Three calls manage it:
| Call | When to use it |
|------|----------------|
| `updateUIMultiplier` | The normal path. Schedules a change for a future timestamp under [ERC-8056](https://eips.ethereum.org/EIPS/eip-8056), so the market gets advance onchain notice. Use it for routine corporate actions. |
| `updateMultiplier` | Deprecated, and kept only as an emergency failsafe. Applies at once and discards any scheduled change that was pending. |
| `cancelUIMultiplierUpdate` | Withdraws a pending scheduled update. |
For the arithmetic, the contract exposes helpers rather than making you replicate it. From Cobalt these follow ERC-8056 naming. `raw` is the token-unit balance; `ui` is the redeemable share quantity.
| Function | Result |
|----------|--------|
| `uiMultiplier()` | Current effective multiplier (WAD) |
| `balanceOfUI(account)` | Raw balance × multiplier |
| `totalSupplyUI()` | Raw total supply × multiplier |
| `toUIAmount(raw)` | Raw amount converted to UI amount |
| `fromUIAmount(ui)` | UI amount converted to raw |
The Beryl names still work. `multiplier()` and `scaledBalanceOf(account)` stay canonical, with `uiMultiplier()` and `balanceOfUI(account)` as aliases returning identical values. `toScaledBalance` and `toRawBalance` remain callable but are deprecated in favour of `toUIAmount` and `fromUIAmount`.
### Policies
Where an asset carries regulatory obligations, the issuer can attach [policies](/specifications/b20/#policy-registry) — allowlists and blocklists that decide, per transfer, whether it proceeds or reverts. To check an account ahead of time, call `isAuthorized(policyID, account)`. It always returns an answer, even for an ID that was never created, so confirm `policyExists(policyId)` before you trust the result.
### Pauses
B20 allows individual functions inside a contract to be paused. Triggering one is unlikely, but an integrator that wants a truthful answer to "can this move right now" has to watch pause state rather than assume it.
### Announcements
Sensitive operations are bracketed by onchain disclosure events. `announce` emits `Announcement (id, description, uri)`, the operation runs, then `EndAnnouncement` closes the window. Indexing this pair is how you catch corporate actions at the moment they execute. Two properties are worth knowing:
- The announcement can be bundled atomically with the change it describes — the multiplier update for a split, say — so the onchain record stays coherent.
- Descriptions are deliberately human-readable onchain, which is what makes them usable for public reporting.
### Extra metadata
Issuers can attach arbitrary key/value pairs onchain through `extraMetadata(key)`. Securities identifiers such as ISIN and CUSIP are the obvious use.
### Name and symbol
Both are editable after deployment, through `updateName` and `updateSymbol`. When the underlying instrument gets renamed or reticker'd, the issuer follows it onchain rather than migrating holders to a fresh token. This is the mutability the caution above is about — index on the address.
### Memos
`transferWithMemo` and `transferFromWithMemo` carry a `bytes32` reference alongside a single transfer, surfaced as a `Memo` event. It gives you somewhere to hang an offchain reference for reconciliation and reporting.
### Supply cap
Total supply can be bounded by an optional cap, which limits the damage from an operational mistake or a compromised role holder over-minting.
## Compliance
Secondary trading is permissionless — holding and trading require no gating. KYC applies at the edges instead, on the mint and redeem flows, which only Authorized Participants (APs) can perform.
- Policies can reject specific addresses onchain, sanctioned ones being the clear case, and a blocked transfer reverts. See [Policies](#policies) above.
- Creating and destroying the underlying shares runs through its own gated flow, open to APs alone.
## Price feeds
Whichever source you use, the price resolves from one relationship — the underlying's market price, restated by the token's multiplier:
```text
Token Price = Underlying Equity Market Price × Multiplier
```
Multipliers are read per token and are WAD-scaled, meaning fixed-point with 18 decimals. Divide the onchain value by that scale to recover the real factor; `WAD_PRECISION()` returns the scale, which is `1e18`.
### Onchain
At launch, Chainlink covers the onchain side. Every tokenized equity gets its own feed. It runs 24/5, carries the last close through weekends and holidays, and halts during corporate actions. Each one presents the usual Chainlink V3 aggregator interface, so you read it off the proxy with `latestRoundData()`, no differently from a crypto feed.
One difference from a standard market-rate feed matters: Coinbase feeds publish **Total Return Values** rather than bare equity prices, so the figure already accounts for corporate actions. Chainlink applies the same treatment to other tokenized-equity issuers, [Ondo and Robinhood](https://docs.chain.link/data-feeds/tokenized-equity-feeds/providers) among them. The underlying price comes from Chainlink's traditional equity feeds — the token's own DEX price is not an input to the oracle.
Two inputs come from Coinbase's onchain oracle registry: the multiplier, and a pause flag. That registry is one contract, distinct from the tokens themselves, and a single call returns both:
- **`paused = false`** — the feed publishes the underlying price multiplied by the multiplier.
- **`paused = true`** — the feed stops publishing and holds its last good value.
The [Tokenized Stocks API](/api-reference/tokenized-stocks-api/) exposes the same feed value as `nav_price`, next to `nav_price_updated_at` and the current `multiplier`. It inherits every limit above: it is a reference value, not a tradeable price, and `nav_price_updated_at` needs the same staleness bound as `updatedAt`.
During a corporate action the pieces move separately:
- Minting and redemption halt offchain. Onchain the token stays unpaused, so transfers continue.
- The registry pause flag is set, the feed freezes, and its price goes stale.
- No price discontinuity appears, because the feed is total-return: multiplier and underlying price move opposite each other and cancel. A 10:1 split cuts the price by roughly ten and lifts the multiplier by roughly ten.
- Resumption waits on Coinbase confirming both halves, the new price and the new multiplier. If only one has landed, the feed holds its pre-pause value instead of publishing something half-applied. That is a deliberate fail-safe.
Read each of the following through `latestRoundData()` on the proxy address given. Each returns 8 decimals across US equity hours of 24/5, republishing on a 0.5% move or the 24-hour heartbeat. Because the values are total-return, the pause and staleness rules above apply to every one of them.
| Feed | Address |
|------|---------|
| Coinbase AAPL | `0x787f13dEa48Db0897CbCDD985de77809D837F988` |
| Coinbase AMZN | `0x06A8E4b3aBB3B7543d8396FB2B763d22820cB295` |
| Coinbase GOOGL | `0x5bF49E0ffA937CE2FfF033c739aD7C634c4D34F2` |
| Coinbase META | `0x6526aE6797A76123638b863AeE4dD27Ba4E4b27D` |
| Coinbase MSFT | `0xeB10A6c9aa7E537aEd766C08c35Dae35B321b18c` |
| Coinbase MSTR | `0xB3cE282CD188b35DA0E38D8Bc7d58e33173D202a` |
| Coinbase NVDA | `0x04689a41629776563E6822F76f2e57D148d28513` |
| Coinbase SNDK | `0x388b0dC46C0Fb05A74BeE0994fa5b02c6Fcca2eA` |
| Coinbase SPCX | `0x6A634B235903C4ad6376892180d6fF8612e3Fa68` |
| Coinbase TSLA | `0xFaf869185383a24F8cb00e27BdA6b63B9905DCb4` |
### Offchain
Aggregators such as CoinGecko, CoinMarketCap, and RWA are the offchain route. Each one follows the live market price on whichever DEXs carry the token, which means coverage runs 24/7 while the secondary market stays active. Two patterns are common:
- Read the token's market price straight from a provider that already tracks the B20.
- Read the underlying reference price and apply the multiplier calculation yourself.
### Historical data
For OHLC and time series, either use a market-data provider or walk Chainlink's round history by `roundId`.
## Deployed addresses
The tables here are a snapshot, and the token list changes as stocks launch or are pulled. Upstream stopped printing the table on 2026-10-07. It now sends readers to the [Base assets page](https://www.base.org/assets) for the current token addresses. Treat that page as the source of truth. For a live copy in code, the [Tokenized Stocks API](/api-reference/tokenized-stocks-api/) serves the token contracts from its list endpoint and the protocol contracts, including the Onchain Registry, from `/chains`.
| Ticker | Contract address |
|--------|------------------|
| Onchain Registry | `0x3f3E8cf41cdd3b1D118c16471aB0113DfDDd5CaD` |
| AAPLc | `0xb200000000000000000000C2e324d24d7eEcd1fb` |
| AMZNc | `0xb200000000000000000000d9192b6B456483C2E8` |
| GOOGLc | `0xb2000000000000000000002D0BA3164cc74f58B7` |
| METAc | `0xb2000000000000000000008bC8786B856E61707C` |
| MSFTc | `0xB200000000000000000000Ab99cFa739E253872B` |
| MSTRc | `0xb2000000000000000000004884b426556b92883d` |
| NVDAc | `0xb20000000000000000000078ee7ce2fE4908108C` |
| SNDKc | `0xb200000000000000000000397293Cb8cda9a10c5` |
| SPCXc | `0xb2000000000000000000007b9fcbd005511aCBd5` |
| TSLAc | `0xb2000000000000000000001e800a7f5189430cD0` |
## Related pages
- [Tokenized Stocks API](/api-reference/tokenized-stocks-api/) — token records, supplies, multipliers, and NAV values over HTTP
- [B20 Native Token Standard](/specifications/b20/) — how the standard behaves
- [Launch a B20 Token](/integration-guides/launch-a-b20-token/) — creating and minting one end to end
- [B20 Precompile Reference](/api-reference/b20-precompiles/) — selectors, `topic0` values, and revert codes
- [Base Standard Library](https://github.com/base/base-std/tree/main) — the interface definitions
---
# Transaction Pool
Source: https://basehub.org/integration-guides/txpool/
Description: Inspect and monitor the Base txpool through RPC extensions and tracing instrumentation.
The Base transaction pool holds pending transactions until the builder includes them in a block. The `base/base` repository ships RPC extensions and tracing instrumentation for inspecting pool contents and monitoring transaction lifecycle events.
## Relevant Crates
| Crate | Description |
|-------|-------------|
| `base-txpool-rpc` | Txpool RPC namespace extensions -- provides JSON-RPC methods for querying pool contents. |
| `base-txpool-tracing` | Tracing instrumentation for txpool operations -- emits structured logs and metrics for transaction lifecycle events. |
These crates live under [`crates/execution/`](https://github.com/base/base/tree/main/crates/execution) in the repository.
## How Transactions Flow Through the Pool
```
User / Application
│
▼
┌─────────────────┐
│ JSON-RPC │ eth_sendRawTransaction
│ (proxy layer) │
└────────┬────────┘
│
▼
┌─────────────────┐
│ Validation │ Nonce check, balance check, gas price check
│ │
└────────┬────────┘
│
▼
┌─────────────────┐
│ Transaction │ Pending pool (ready to include)
│ Pool │ Queued pool (future nonce gap)
└────────┬────────┘
│
▼
┌─────────────────┐
│ Block Builder │ Selects transactions for next block/flashblock
│ │
└─────────────────┘
```
1. **Ingress** -- transactions arrive via `eth_sendRawTransaction` through the proxy layer in front of the node. This used to be the `ingress-rpc` service, which was retired on 2026-09-21; the stage is the same, and nothing about the pool behaviour below depends on which component fronts it.
2. **Validation** -- each transaction is validated: signature verification, nonce ordering, sufficient balance for gas and value, gas price meets the minimum.
3. **Pool insertion** -- valid transactions enter the pool. Transactions with the next expected nonce go into the **pending** sub-pool (ready for inclusion). Transactions with a future nonce go into the **queued** sub-pool (waiting for the gap to be filled).
4. **Promotion** -- when a pending transaction is included in a block or flashblock, queued transactions from the same sender may be promoted to pending if the nonce gap is closed.
5. **Selection** -- the block builder pulls transactions from the pending pool, ordered by effective gas price, for inclusion in the next flashblock delta.
## RPC Methods
The `base-txpool-rpc` crate extends the standard txpool namespace with the following methods.
### `txpool_status`
Returns the number of transactions in each sub-pool.
```bash
curl -X POST https://your-base-rpc-endpoint \
-H "Content-Type: application/json" \
-d '{
"method": "txpool_status",
"params": [],
"id": 1,
"jsonrpc": "2.0"
}'
```
```json
{
"id": 1,
"jsonrpc": "2.0",
"result": {
"pending": "0x12",
"queued": "0x3"
}
}
```
### `txpool_content`
Returns all transactions in the pool, grouped by sender address and nonce.
```bash
curl -X POST https://your-base-rpc-endpoint \
-H "Content-Type: application/json" \
-d '{
"method": "txpool_content",
"params": [],
"id": 1,
"jsonrpc": "2.0"
}'
```
```json
{
"id": 1,
"jsonrpc": "2.0",
"result": {
"pending": {
"0xSenderAddress": {
"0": { "hash": "0x...", "gasPrice": "0x...", "nonce": "0x0", "..." : "..." },
"1": { "hash": "0x...", "gasPrice": "0x...", "nonce": "0x1", "..." : "..." }
}
},
"queued": {
"0xAnotherSender": {
"5": { "hash": "0x...", "gasPrice": "0x...", "nonce": "0x5", "..." : "..." }
}
}
}
}
```
### `txpool_inspect`
Returns a text summary of all transactions in the pool (lighter-weight than `txpool_content`).
```bash
curl -X POST https://your-base-rpc-endpoint \
-H "Content-Type: application/json" \
-d '{
"method": "txpool_inspect",
"params": [],
"id": 1,
"jsonrpc": "2.0"
}'
```
```json
{
"id": 1,
"jsonrpc": "2.0",
"result": {
"pending": {
"0xSenderAddress": {
"0": "0xRecipient: 0 wei + 21000 gas x 1000000000 wei"
}
},
"queued": {}
}
}
```
### `txpool_contentFrom`
Returns transactions from a specific sender address.
```bash
curl -X POST https://your-base-rpc-endpoint \
-H "Content-Type: application/json" \
-d '{
"method": "txpool_contentFrom",
"params": ["0xSenderAddress"],
"id": 1,
"jsonrpc": "2.0"
}'
```
```json
{
"id": 1,
"jsonrpc": "2.0",
"result": {
"pending": {
"0": { "hash": "0x...", "nonce": "0x0", "..." : "..." }
},
"queued": {}
}
}
```
## Tracing and Observability
The `base-txpool-tracing` crate instruments the transaction pool with structured tracing events. When enabled, it emits events for:
| Event | Description |
|-------|-------------|
| `txpool.insert` | A transaction was inserted into the pool. Includes sender, nonce, hash, gas price. |
| `txpool.promote` | A queued transaction was promoted to pending (nonce gap filled). |
| `txpool.discard` | A transaction was removed from the pool (replaced, expired, or invalidated). |
| `txpool.replace` | A transaction was replaced by a new one with the same nonce and higher gas price. |
| `txpool.evict` | A transaction was evicted due to pool size limits. |
These events can be consumed by any `tracing` subscriber -- written to stdout, sent to a logging backend, or exported as OpenTelemetry spans.
### Enabling Tracing
Tracing is configured via the node's logging configuration. For example, to enable debug-level txpool tracing:
```bash
RUST_LOG=base_txpool_tracing=debug base-reth-node \
--http \
--http.api eth,txpool
```
## Practical Tips
- **Nonce management** -- use `eth_getTransactionCount` with the `"pending"` tag (see [Flashblocks RPC](/integration-guides/flashblocks-rpc/)) to get the latest nonce including flashblock-preconfirmed transactions. This avoids nonce collisions when submitting transactions rapidly.
- **Gas price monitoring** -- query `txpool_status` periodically to gauge pool congestion. A high pending count relative to block throughput suggests rising base fees.
- **Transaction replacement** -- to speed up or cancel a pending transaction, submit a new transaction with the same nonce and a higher gas price (typically at least 10% higher to be accepted by the pool).
- **Pool limits** -- the pool has configurable size limits. When full, the lowest-priced transactions are evicted first. Monitor `txpool.evict` tracing events to detect when your transactions might be at risk.
## Further Reading
- [Crate Reference](/crates/overview/) -- overview of all crate groups, including the execution crates.
- [Flashblocks RPC](/integration-guides/flashblocks-rpc/) -- using the `"pending"` tag for preconfirmed nonces and balances.
- [Connecting to Base](/integration-guides/connecting/) -- network endpoints and chain parameters.
---
# Base-Solana Bridge
Source: https://basehub.org/introduction/base-solana-bridge/
Description: Bridge tokens and arbitrary messages between Base and Solana with the official Base-Solana bridge contracts and programs.
import { Aside, Card, CardGrid } from '@astrojs/starlight/components';
The Base-Solana bridge moves tokens and arbitrary messages in both directions between Base and Solana, with optional contract-call execution at the destination.
The bridge supports:
- **Token transfers** between Base and Solana
- **Arbitrary cross-chain messages**
- **Combined flows** that pair a transfer with a destination contract call
- **Wrapped token deployments** on either chain
This page covers the bridge architecture, production contract addresses, and reference implementation patterns.
## How it works
### On Base
The Base bridge contract locks or burns outgoing tokens and mints or unlocks incoming tokens. It also assembles outgoing messages into Merkle trees. Validators sign the Merkle root every ~300 finalized blocks and relay it to Solana, where users prove their message exists in the tree to complete the transfer.
**Key smart contracts:**
- [**Bridge Contract**](https://github.com/base/bridge/blob/main/base/src/Bridge.sol) — handles outgoing transfers
- [**CrossChainERC20**](https://github.com/base/bridge/blob/main/base/src/CrossChainERC20.sol) — mintable/burnable tokens for cross-chain transfers
- [**BridgeValidator**](https://github.com/base/bridge/blob/main/base/src/BridgeValidator.sol) — verifies messages with oracle signatures
- [**Twin Contract**](https://github.com/base/bridge/blob/main/base/src/Twin.sol) — your personal smart contract on Base for executing calls forwarded from Solana
### On Solana
The Solana bridge program manages token transfers by locking or burning the asset and emitting events. For messages, validators forward those events to Base, where execution runs through your Twin contract.
**Key programs (Solana Mainnet-Beta):**
- [**Bridge Program**](https://github.com/base/bridge/blob/main/solana/programs/bridge) — handles outgoing transfers and message commitments
- [**Base Relayer Program**](https://github.com/base/bridge/blob/main/solana/programs/base_relayer) — optional relayer that can prepay gas on Base
The full repository lives at [github.com/base/bridge](https://github.com/base/bridge).
## Bridging flows
Push-based flow with an optional relayer for instant execution on Base. See [Solana to Base](#solana-to-base).
Proof-based burn-and-unlock flow with full custody. See [Base to Solana](#base-to-solana).
Production terminal UI for bridging plus contract calls. See [Terminally Onchain example](#terminally-onchain-example).
## Solana to Base
**Flow:** Lock SOL/SPL → (optional) pay for relay → validators approve → mint and execute on Base.
The Solana to Base direction uses a pull-based model with three steps:
1. **Initiate the bridge on Solana.** Lock your SOL or native SPL token in a Solana vault.
2. **Wait for validator pre-approval.** Validators verify and approve the bridge message.
3. **Execute on Base.** The approved message runs on Base to mint SOL and execute any attached calls.
Reference scripts for auto-relay, token wrapping, and CLI utilities live in the `scripts/` directory of the official repository: [Solana to Base CLI scripts](https://github.com/base/bridge/tree/main/scripts/src/commands/sol/bridge).
### Auto-relay example
This sample bridges SOL with auto-relay enabled.
```typescript solToBaseWithAutoRelay/index.ts expandable
// Configure
const TO = "0x8c1a617bdb47342f9c17ac8750e0b070c372c721"; // Base address
const AMOUNT = 0.001; // SOL amount
// Bridge SOL with auto-relay
const ixs = [
getBridgeSolInstruction({
payer,
from: payer,
solVault: solVaultAddress,
bridge: bridgeAccountAddress,
outgoingMessage,
to: toBytes(TO),
remoteToken: toBytes("0xC5b9112382f3c87AFE8e1A28fa52452aF81085AD"), // SOL on Base
amount: BigInt(AMOUNT * 10**9),
}),
await buildPayForRelayIx(RELAYER_PROGRAM_ID, outgoingMessage, payer)
];
await buildAndSendTransaction(SOLANA_RPC_URL, ixs, payer);
```
Full handler: [Solana to Base relay script](https://github.com/base/bridge/blob/main/scripts/src/commands/sol/bridge/solana-to-base/bridge-sol.handler.ts).
### Wrap custom SPL tokens
The example above bridges native SOL. To bridge custom SPL tokens, deploy wrapped ERC20 representations on Base via `CrossChainERC20Factory`.
Reference: [token wrapping example](https://github.com/base/bridge/blob/main/scripts/src/commands/sol/bridge/solana-to-base/wrap-token.handler.ts).
```typescript wrapSolTokenOnBase/index.ts expandable
// Deploy wrapped token on Base
const mintBytes32 = getBase58Codec().encode(SOLANA_SPL_MINT_ADDRESS).toHex();
await client.writeContract({
address: "0x58207331CBF8Af87BB6453b610E6579D9878e4EA", // Factory
abi: TokenFactory,
functionName: "deploy",
args: [`0x${mintBytes32}`, "Token Name", "SYMBOL", 9],
});
```
## Base to Solana
**Flow:** Burn ERC20 SOL on Base → wait for finalization → generate Merkle proof → execute on Solana.
The return path burns the wrapped token on Base, waits for the message to become provable, then submits the proof on Solana to release the native asset. This route preserves full custody and requires a prover.
Reference: [Base to Solana example](https://github.com/base/bridge/blob/main/scripts/src/internal/sol/base.ts).
```typescript bridgeSolFromBaseToSolana/index.ts expandable
// Step 1: Burn SOL on Base
const transfer = {
localToken: "0xC5b9112382f3c87AFE8e1A28fa52452aF81085AD", // SOL (on Base)
remoteToken: pubkeyToBytes32(SOL_ADDRESS),
to: pubkeyToBytes32(solanaAddress),
remoteAmount: BigInt(AMOUNT * 10**9),
};
const txHash = await client.writeContract({
address: "0xB2068ECCDb908902C76E3f965c1712a9cF64171E", // Bridge
abi: Bridge,
functionName: "bridgeToken",
args: [transfer, []],
});
// Step 2: Wait for finalization
const isProvable = await isBridgeMessageProvable(txHash);
// Step 3: Generate proof
const { event, rawProof } = await generateProof(txHash, baseBlockNumber);
// Step 4: Execute on Solana
const proveIx = getProveMessageInstruction({
nonce: event.message.nonce,
sender: toBytes(event.message.sender),
data: toBytes(event.message.data),
proof: rawProof.map(e => toBytes(e)),
messageHash: toBytes(event.messageHash),
});
const relayIx = getRelayMessageInstruction({ message: messagePda });
await buildAndSendTransaction(SOLANA_RPC_URL, [proveIx, relayIx], payer);
```
## Utilities
The repository ships utilities for converting between Solana and Base address formats, loading the Solana CLI keypair for signing, and building/sending Solana transactions: [scripts/src/commands](https://github.com/base/bridge/tree/main/scripts/src/commands).
### Address conversion
Convert a Solana pubkey to bytes32 for Base contracts:
```typescript example.ts
// Convert Solana pubkey to bytes32 for Base contracts
import { pubkeyToBytes32 } from "./utils/pubkeyToBytes32";
const bytes32Address = pubkeyToBytes32(solanaAddress);
```
### Keypair management
Load the Solana CLI keypair for signing:
```typescript example.ts
import { getSolanaCliConfigKeypairSigner } from "./utils/keypair";
const payer = await getSolanaCliConfigKeypairSigner();
```
### Transaction building
Build and submit a Solana transaction:
```typescript example.ts
import { buildAndSendTransaction } from "./utils/buildAndSendTransaction";
const signature = await buildAndSendTransaction(SOLANA_RPC_URL, ixs, payer);
```
## Terminally Onchain example
Repository: [github.com/base/sol2base](https://github.com/base/sol2base).
[Terminally Onchain](https://terminallyonchain.com/) is a production Next.js app that exposes the bridge through a command terminal UI. Users connect a Solana wallet and run commands that bridge value and call a contract on Base:
```bash
bridge 0.0001 sol 0xYourTwin --call-contract 0x311935Cd80B76769bF2ecC9D8Ab7635b2139cf82 \
--call-selector "transfer(address,uint256)" \
--call-args 0x0000000000000000000000000000000000000000 100000000000000
```
The workflow:
1. **Parse command.** The terminal parser resolves the asset, destination, and optional Base call (selector, args, value).
2. **Stage bridge.** `queueBridge` validates SPL overrides, ABI-encodes the Base call via `encodeFunctionData`, and stages relay overrides.
3. **Execute.** `solanaBridge.bridge()` resolves the destination (ENS or Basename), confirms balances, and calls `realBridgeImplementation` to sign and submit the Solana transaction.
4. **Relay and call.** When relay gas is prepaid, the Base Relayer immediately runs the attached call from the user's Twin contract once ERC20 SOL is minted.
Key implementation references:
- `src/lib/bridge.ts` — asset resolution (including mint addresses), environment-aware RPC connections, and call attachment
- `src/lib/realBridgeImplementation.ts` — builds Solana transactions with `PayForRelay` plus `bridge_sol`/`bridge_spl` instructions, using per-environment PDAs and gas-fee receivers
- `src/components/MainContent.tsx` — terminal UI with command staging, log viewer, and ABI encoding for arbitrary Base calls
- `src/components/WalletConnection.tsx` — fetches the deterministic Twin address on Base Mainnet/Sepolia for the connected Solana wallet
### Run the terminal locally
```bash Terminal
git clone https://github.com/base/sol2base.git
cd sol2base
npm install --legacy-peer-deps
# Configure env (RPC URLs, relayer addresses, CDP API keys, etc.)
cp env.template .env.local
npm run dev # defaults to http://localhost:3000
```
## Contract addresses
### Base Mainnet
```json
{
"Bridge": "0x3eff766C76a1be2Ce1aCF2B69c78bCae257D5188",
"BridgeValidator": "0xAF24c1c24Ff3BF1e6D882518120fC25442d6794B",
"CrossChainERC20Factory": "0xDD56781d0509650f8C2981231B6C917f2d5d7dF2",
"SOL": "0x311935Cd80B76769bF2ecC9D8Ab7635b2139cf82"
}
```
### Solana Mainnet
```json
{
"BridgeProgram": "HNCne2FkVaNghhjKXapxJzPaBvAKDG1Ge3gqhZyfVWLM",
"BaseRelayerProgram": "g1et5VenhfJHJwsdJsDbxWZuotD5H4iELNG61kS4fb9"
}
```
### Base Sepolia
```json
{
"Bridge": "0x01824a90d32A69022DdAEcC6C5C14Ed08dB4EB9B",
"BridgeValidator": "0xa80C07DF38fB1A5b3E6a4f4FAAB71E7a056a4EC7",
"CrossChainERC20Factory": "0x488EB7F7cb2568e31595D48cb26F63963Cc7565D",
"SOL": "0xCace0c896714DaF7098FFD8CC54aFCFe0338b4BC",
"FLYWHEEL_ADDRESS": "0x00000F14AD09382841DB481403D1775ADeE1179F",
"BRIDGE_CAMPAIGN_ADDRESS": "0xE2AD1C34382410C30d826B019A0B3700F5c4e6c9"
}
```
### Solana Devnet
```json
{
"BridgeProgram": "7c6mteAcTXaQ1MFBCrnuzoZVTTAEfZwa6wgy4bqX3KXC",
"BaseRelayerProgram": "56MBBEYAtQAdjT4e1NzHD8XaoyRSTvfgbSVVcEcHj51H",
"GasFeeReceiver": "AFs1LCbodhvwpgX3u3URLsud6R1XMSaMiQ5LtXw4GKYT"
}
```
## Resources
Source code, contracts, programs, and scripts: [github.com/base/bridge](https://github.com/base/bridge).
Inspect Solana mainnet-beta transactions at [explorer.solana.com](https://explorer.solana.com/).
Inspect Base Mainnet transactions at [basescan.org](https://basescan.org/).
Get help from the Base community at [base.org/discord](https://base.org/discord).
---
# Connecting to Base
Source: https://basehub.org/introduction/connecting-to-base/
Description: Network parameters, RPC endpoints, and wallet setup for connecting to Base Mainnet and Base Sepolia testnet.
import { Aside } from '@astrojs/starlight/components';
Connect to Base Mainnet or the Sepolia testnet using the public RPC endpoints, then configure any EVM-compatible wallet to use the network.
## Base Mainnet
| Name | Value |
| :--- | :--- |
| Network Name | Base Mainnet |
| Description | The public mainnet for Base. |
| RPC Endpoint | [https://mainnet.base.org](https://mainnet.base.org) — Flashblocks-enabled; rate limited, not for production. |
| Transaction Submission | `https://mainnet-sequencer.base.org` — send transactions only; use the RPC endpoint for everything else. |
| Chain ID | 8453 |
| Currency Symbol | ETH |
| Block Explorer | [https://base.blockscout.com/](https://base.blockscout.com/) |
## Base Testnet (Sepolia)
| Name | Value |
| :--- | :--- |
| Network Name | Base Sepolia |
| Description | The public testnet for Base. |
| RPC Endpoint | [https://sepolia.base.org](https://sepolia.base.org) — Flashblocks-enabled; rate limited, not for production. |
| Transaction Submission | `https://sepolia-sequencer.base.org` — send transactions only; use the RPC endpoint for everything else. |
| Chain ID | 84532 |
| Currency Symbol | ETH |
| Block Explorer | [https://sepolia-explorer.base.org](https://sepolia-explorer.base.org) |
## Base Vibenet (preview)
Vibenet is Base's experimental preview network. Chain-level features land here first, ahead of any rollout to Sepolia or Mainnet, so it is the place to try upcoming capabilities before they stabilize. At the moment it carries [B20 tokens](/specifications/b20/) — an ERC-20 superset that adds roles, supply caps, pausing, and policy gating, with `permit` provided as a native precompile. Treat Vibenet as a sandbox for cutting-edge work only; it is not meant for production deployments or anything user-facing. Vibenet's landing page, faucet, and explorer now all sit under [chain.base.org/vibenet](https://chain.base.org/vibenet); the older `vibes.base.org` subdomains have been retired apart from the RPC endpoint.
| Name | Value |
| :--- | :--- |
| Network Name | Base Vibenet |
| Description | Base's experimental preview network. |
| RPC Endpoint | [https://rpc.vibes.base.org](https://rpc.vibes.base.org) |
| WebSocket Endpoint | `wss://rpc.vibes.base.org/ws` |
| Chain ID | 84538453 |
| Currency Symbol | ETH |
| Faucet | [https://chain.base.org/vibenet/faucet](https://chain.base.org/vibenet/faucet) |
| Block Explorer | [https://chain.base.org/vibenet/explorer](https://chain.base.org/vibenet/explorer) |
### Streaming from Vibenet
Vibenet is the one Base network with an open WebSocket, at `wss://rpc.vibes.base.org/ws`. It accepts `eth_subscribe`, so subscription code can be written and tested here without a provider account:
- `newHeads` fires once per block and tracks chain progress.
- `logs` carries contract events, narrowed by address and indexed topics.
```javascript
import WebSocket from "ws";
const ws = new WebSocket("wss://rpc.vibes.base.org/ws");
ws.on("open", () => {
ws.send(JSON.stringify({
jsonrpc: "2.0",
id: 1,
method: "eth_subscribe",
params: ["newHeads"],
}));
});
ws.on("message", (data) => {
const msg = JSON.parse(data.toString());
if (msg.method === "eth_subscription") {
console.log("new head:", msg.params.result.number);
}
});
```
Vibenet runs [200ms blocks](/specifications/denim-200ms-blocks/), which changes what polling can do. A loop on a 250ms to 1s timer will step over whole blocks rather than merely lag behind them, so the socket has to be the primary feed and polling drops back to reconciliation work: balances, fee estimates, health checks. Hold a small number of long-lived connections and share each one across subscriptions and ordinary calls rather than opening a socket per subscription. Keep an HTTPS path ready for when the socket drops.
Do not carry this endpoint into code destined for Sepolia or Mainnet. Neither offers an equivalent, so the transport has to change when the network does.
## Using Base with your wallet
### Coinbase Wallet
The [Coinbase Wallet](https://chrome.google.com/webstore/detail/coinbase-wallet-extension/hnfanknocfeofbddgcijnmhnfnkdnaad?hl=en) browser extension supports Base out of the box.
To switch to Base in Coinbase Wallet:
1. Open the Coinbase Wallet extension and sign in.
2. Connect to an app from within the wallet.
3. Click the network icon in the top right to open the network menu.
4. Choose **Base**.
The active network now points at Base.
### Other wallets
Base works as a custom network in any EVM-compatible wallet, including [MetaMask](https://chrome.google.com/webstore/detail/metamask/nkbihfbeogaeaoehlefnkodbefgpgknn).
#### MetaMask
To add Base as a custom network in MetaMask:
1. Open the MetaMask extension.
2. Click the network dropdown at the top of the extension.
3. Click **Add network**.
4. Click **Add a network manually**.
5. Enter the Base mainnet values:
| Name | Value |
| :--- | :--- |
| Network Name | Base Mainnet |
| Description | The public mainnet for Base. |
| RPC Endpoint | [https://mainnet.base.org](https://mainnet.base.org) |
| Chain ID | 8453 |
| Currency Symbol | ETH |
| Block Explorer | [https://base.blockscout.com/](https://base.blockscout.com/) |
6. Click **Save**.
Base now appears in the network dropdown.
## Testnet
#### Coinbase Wallet supports Base Sepolia by default
To use Base Sepolia in Coinbase Wallet:
1. Open the Coinbase Wallet extension and sign in.
2. Connect to an app.
3. Click the network icon at the top right.
4. Click **More networks**.
5. Open the **Testnets** tab.
6. Choose **Base Sepolia**.
The active network is now the Base testnet.
#### Other wallets
Base Sepolia can also be added as a custom network in any EVM-compatible wallet such as [MetaMask](https://chrome.google.com/webstore/detail/metamask/nkbihfbeogaeaoehlefnkodbefgpgknn).
#### MetaMask
To add Base Sepolia in MetaMask:
1. Open the MetaMask extension.
2. Click the network dropdown.
3. Click **Add network**.
4. Click **Add a network manually**.
5. Enter the Base Sepolia values:
| Name | Value |
| :--- | :--- |
| Network Name | Base Sepolia |
| RPC Endpoint | [https://sepolia.base.org](https://sepolia.base.org) |
| Chain ID | 84532 |
| Currency Symbol | ETH |
| Block Explorer | [https://sepolia-explorer.base.org](https://sepolia-explorer.base.org) |
6. Click **Save**.
Base Sepolia is now selectable from the network dropdown.
---
# Deploy on Base
Source: https://basehub.org/introduction/deploy-on-base/
Description: Set up Base's Foundry build, configure RPC and key management, and deploy a smart contract to Base Sepolia in a single workflow.
import { Aside } from '@astrojs/starlight/components';
Set up a Foundry project, point it at Base, and deploy a contract to Base Sepolia in a single end-to-end workflow.
Base is EVM-equivalent, so Solidity and Vyper contracts carry over from Ethereum unchanged — same bytecode, same ABIs, same tooling. The one place that equivalence stops is the precompiles.
## What you build
By the end of this guide you will have:
- A development environment running Base's Foundry build
- A smart contract deployed to Base Sepolia
- A connection pattern your frontend can reuse against your contracts
## Set up your development environment
1. Create a project directory.
```bash
mkdir my-base-project && cd my-base-project
```
2. Install Base's Foundry build, used throughout this guide.
```bash
curl -L https://raw.githubusercontent.com/base/base-anvil/HEAD/foundryup/install | bash
base-foundryup
```
This lands `base-forge`, `base-cast`, `base-anvil`, and the `base-chisel` REPL next to whatever Foundry you already have. To target a specific Base release, pin it with `base-foundryup --install `; releases are named for the Base chain release they support. Nothing is overwritten, and the two toolchains coexist.
3. Initialize a Solidity project.
```bash
base-forge init
```
The project is ready. The starter contract sits at `src/Counter.sol` — this guide uses that contract as the deployment target.
## Configure the toolchain for Base
Deploying to Base requires two pieces:
1. An RPC connection to the network
2. A funded private key for signing the deployment transaction
### 1. Set up your RPC connection
1. Create a `.env` file at the project root.
2. Add the Base RPC URLs.
```bash
BASE_RPC_URL="https://mainnet.base.org"
BASE_SEPOLIA_RPC_URL="https://sepolia.base.org"
```
3. Load the variables into your shell.
```bash
source .env
```
### 2. Secure your private key
1. Import your private key into the encrypted keystore.
```bash
base-cast wallet import deployer --interactive
```
2. Paste the key when prompted and set a password.
The encrypted key is stored at `~/.foundry/keystores`, which is excluded from git.
## Deploy your contract
With the environment configured, deploy to Base Sepolia.
1. (Optional) Run a dry run first to confirm the deployment is well-formed.
```bash
base-forge create ./src/Counter.sol:Counter --rpc-url $BASE_SEPOLIA_RPC_URL --account deployer
```
This simulates the deploy without broadcasting. You will see the transaction details and ABI; nothing is written onchain.
2. Add `--broadcast` to actually deploy.
```bash
base-forge create ./src/Counter.sol:Counter --rpc-url $BASE_SEPOLIA_RPC_URL --account deployer --broadcast
```
The contract argument follows the format `:`.
3. A successful deploy prints output similar to:
```
Deployer: 0x...
Deployed to: 0x... <-- YOUR CONTRACT ADDRESS
Transaction hash: 0x...
```
4. Save the deployed address into `.env`.
```bash
COUNTER_CONTRACT_ADDRESS="0x..."
```
Replace `0x...` with the address from the output.
5. Reload the variables.
```bash
source .env
```
### Verify your deployment
To confirm the contract is live:
1. Look up the transaction hash on [Sepolia Basescan](https://sepolia.basescan.org/).
2. Read the contract directly with `base-cast`:
```bash
base-cast call $COUNTER_CONTRACT_ADDRESS "number()(uint256)" --rpc-url $BASE_SEPOLIA_RPC_URL
```
The call returns the initial value of the Counter's `number` storage slot, which is `0`.
The contract is now live on Base Sepolia.
## Next steps
- Launch a token on Base's native standard, built in at the precompile level — see [B20](/specifications/b20/) and the [B20 precompile reference](/api-reference/b20-precompiles/).
- Wire a frontend to your contracts using [wagmi](https://wagmi.sh) or [viem](https://viem.sh).
- Drive deployments from scripts with the [Foundry scripting guide](https://www.getfoundry.sh/forge/scripting).
---
# Why Base
Source: https://basehub.org/introduction/why-base/
Description: Base delivers sub-cent, sub-second transactions on a global, permissionless platform with developer tooling, grants, and built-in distribution.
Base is an Ethereum L2 designed for sub-second, sub-cent transactions on a permissionless platform with first-class developer tooling and built-in distribution.
## At a glance
- **Open and inexpensive.** Base is a globally accessible network offering 1-second confirmations and transactions that cost less than a cent.
- **First-class tooling.** Builders ship onchain experiences across AI, social, media, and entertainment with a mature developer stack.
- **Funding for builders.** Base has issued grants to over 1,000 builders, with more on the way.
- **Distribution channels.** Apps reach users through official Base distribution surfaces.
## A platform for new applications
Base is a global onchain economy of people, builders, and businesses building the next iteration of the open internet. The chain is engineered so developers can:
- Concentrate on real user problems
- Ship apps that scale globally by default
- Onboard new users in a single click
- Take payments from anyone, anywhere
It is fast, inexpensive, and permissionless — anyone can build on or use applications running on Base.
The network has emerged as a hub for new use cases across media, entertainment, social, and AI. [Clanker](https://www.clanker.world), an autonomous AI agent operating on Base, generated more than $13 million in revenue in its first three months. Base is structured so developers retain more of the upside their products create.
Conventional app distribution often forces developers to give up 30% of revenue to marketplaces. Those marketplaces can also drive practices that work against users — selling personal data, demanding identity disclosures, or denying access at will. A user in Nairobi, for example, may be locked out of many U.S.-based fintech services entirely.
Onchain finance changes that math. Apps such as [Moonwell](https://moonwell.fi) make financial services available directly from a phone, anywhere in the world. A user in Nairobi gets the same access as a user in the United States, opening up opportunities that did not previously exist.
## Developer tooling
Developers pick Base for:
- An always-on, internet-speed payment rail with global reach
- Per-transaction costs that are typically below a cent
- A deep developer toolchain
Apps on Base ship in hours instead of days or weeks, thanks to a broad set of tools — many of them open source. Two builders working from a garage can again credibly create a major business.
Tools that make this practical:
- **Base Account.** Onboard users quickly and securely without seed phrases.
- **Coinbase Developer Platform.** Specialized services for onchain builders, including free node software, sponsored transactions, and tooling to refine your app.
- **Basenames.** More than human-readable addresses — Basenames are the front door to a builder's onchain profile.
- **Verifications.** Power tailored experiences for users with verified credentials.
---
# Contract Addresses
Source: https://basehub.org/network/base-contracts/
Description: Canonical L1 and L2 contract and admin addresses for Base Mainnet and Base Sepolia, with explorer links and notes on unused OP Stack contracts.
The tables below list the canonical contract and admin addresses for Base Mainnet and Base Sepolia, with links to the corresponding block explorer.
## L2 contract addresses
### Base Mainnet
| Name | Address |
| :---------------------------- | :-------------------------------------------------------------------------------------------------------------------- |
| WETH9 | [0x4200000000000000000000000000000000000006](https://basescan.org/address/0x4200000000000000000000000000000000000006) |
| L2CrossDomainMessenger | [0x4200000000000000000000000000000000000007](https://basescan.org/address/0x4200000000000000000000000000000000000007) |
| L2StandardBridge | [0x4200000000000000000000000000000000000010](https://basescan.org/address/0x4200000000000000000000000000000000000010) |
| SequencerFeeVault | [0x4200000000000000000000000000000000000011](https://basescan.org/address/0x4200000000000000000000000000000000000011) |
| OptimismMintableERC20Factory | [0xF10122D428B4bc8A9d050D06a2037259b4c4B83B](https://basescan.org/address/0xF10122D428B4bc8A9d050D06a2037259b4c4B83B) |
| GasPriceOracle | [0x420000000000000000000000000000000000000F](https://basescan.org/address/0x420000000000000000000000000000000000000F) |
| L1Block | [0x4200000000000000000000000000000000000015](https://basescan.org/address/0x4200000000000000000000000000000000000015) |
| L2ToL1MessagePasser | [0x4200000000000000000000000000000000000016](https://basescan.org/address/0x4200000000000000000000000000000000000016) |
| L2ERC721Bridge | [0x4200000000000000000000000000000000000014](https://basescan.org/address/0x4200000000000000000000000000000000000014) |
| OptimismMintableERC721Factory | [0x4200000000000000000000000000000000000017](https://basescan.org/address/0x4200000000000000000000000000000000000017) |
| ProxyAdmin | [0x4200000000000000000000000000000000000018](https://basescan.org/address/0x4200000000000000000000000000000000000018) |
| BaseFeeVault | [0x4200000000000000000000000000000000000019](https://basescan.org/address/0x4200000000000000000000000000000000000019) |
| L1FeeVault | [0x420000000000000000000000000000000000001a](https://basescan.org/address/0x420000000000000000000000000000000000001a) |
| EAS | [0x4200000000000000000000000000000000000021](https://basescan.org/address/0x4200000000000000000000000000000000000021) |
| EASSchemaRegistry | [0x4200000000000000000000000000000000000020](https://basescan.org/address/0x4200000000000000000000000000000000000020) |
| LegacyERC20ETH | [0xDeadDeAddeAddEAddeadDEaDDEAdDeaDDeAD0000](https://basescan.org/address/0xDeadDeAddeAddEAddeadDEaDDEAdDeaDDeAD0000) |
### Base Sepolia
| Name | Address |
| :---------------------------- | :---------------------------------------------------------------------------------------------------------------------------- |
| WETH9 | [0x4200000000000000000000000000000000000006](https://sepolia.basescan.org/address/0x4200000000000000000000000000000000000006) |
| L2CrossDomainMessenger | [0x4200000000000000000000000000000000000007](https://sepolia.basescan.org/address/0x4200000000000000000000000000000000000007) |
| L2StandardBridge | [0x4200000000000000000000000000000000000010](https://sepolia.basescan.org/address/0x4200000000000000000000000000000000000010) |
| SequencerFeeVault | [0x4200000000000000000000000000000000000011](https://sepolia.basescan.org/address/0x4200000000000000000000000000000000000011) |
| OptimismMintableERC20Factory | [0x4200000000000000000000000000000000000012](https://sepolia.basescan.org/address/0x4200000000000000000000000000000000000012) |
| GasPriceOracle | [0x420000000000000000000000000000000000000F](https://sepolia.basescan.org/address/0x420000000000000000000000000000000000000F) |
| L1Block | [0x4200000000000000000000000000000000000015](https://sepolia.basescan.org/address/0x4200000000000000000000000000000000000015) |
| L2ToL1MessagePasser | [0x4200000000000000000000000000000000000016](https://sepolia.basescan.org/address/0x4200000000000000000000000000000000000016) |
| L2ERC721Bridge | [0x4200000000000000000000000000000000000014](https://sepolia.basescan.org/address/0x4200000000000000000000000000000000000014) |
| OptimismMintableERC721Factory | [0x4200000000000000000000000000000000000017](https://sepolia.basescan.org/address/0x4200000000000000000000000000000000000017) |
| ProxyAdmin | [0x4200000000000000000000000000000000000018](https://sepolia.basescan.org/address/0x4200000000000000000000000000000000000018) |
| BaseFeeVault | [0x4200000000000000000000000000000000000019](https://sepolia.basescan.org/address/0x4200000000000000000000000000000000000019) |
| L1FeeVault | [0x420000000000000000000000000000000000001a](https://sepolia.basescan.org/address/0x420000000000000000000000000000000000001a) |
| EAS | [0x4200000000000000000000000000000000000021](https://sepolia.basescan.org/address/0x4200000000000000000000000000000000000021) |
| EASSchemaRegistry | [0x4200000000000000000000000000000000000020](https://sepolia.basescan.org/address/0x4200000000000000000000000000000000000020) |
| LegacyERC20ETH | [0xDeadDeAddeAddEAddeadDEaDDEAdDeaDDeAD0000](https://sepolia.basescan.org/address/0xDeadDeAddeAddEAddeadDEaDDEAdDeaDDeAD0000) |
Most L2 predeploys share the same address on Base Mainnet and Base Sepolia. The exceptions are network-specific contracts such as `OptimismMintableERC20Factory`, whose per-network address appears in the relevant table above.
## L1 contract addresses
### Ethereum Mainnet
Mainnet's proof contracts were swapped ahead of the Cobalt activation at `1790791200` (September 30, 2026, 18:00 UTC). The `AggregateVerifier` row now points at a new deployment, and a factory query on 2026-09-30 confirmed that game type `621` already resolves to it. Nitro attestation is handled by `NitroValidator`, which works with `CertManager` and `P384Verifier`; together they take the place of the retired `NitroEnclaveVerifier`. Anything that pinned the old Mainnet `AggregateVerifier` or `NitroEnclaveVerifier` address needs updating.
| Name | Address |
| :--------------------------- | :-------------------------------------------------------------------------------------------------------------------- |
| AddressManager | [0x8EfB6B5c4767B09Dc9AA6Af4eAA89F749522BaE2](https://etherscan.io/address/0x8EfB6B5c4767B09Dc9AA6Af4eAA89F749522BaE2) |
| AggregateVerifier | [0xeF9eCeA15265321753047EBF7D54C858D53cB94f](https://etherscan.io/address/0xeF9eCeA15265321753047EBF7D54C858D53cB94f) |
| AnchorStateRegistryProxy | [0x909f6cf47ed12f010A796527f562bFc26C7F4E72](https://etherscan.io/address/0x909f6cf47ed12f010A796527f562bFc26C7F4E72) |
| CertManager | [0x7227d8C477CD0A9EC1446A19b1FCf940Ba3Fba17](https://etherscan.io/address/0x7227d8C477CD0A9EC1446A19b1FCf940Ba3Fba17) |
| DelayedWETHProxy | [0xd0D07924AdD740a87e41Ca8A0d4CBBf6b074EF71](https://etherscan.io/address/0xd0D07924AdD740a87e41Ca8A0d4CBBf6b074EF71) |
| DisputeGameFactoryProxy | [0x43edB88C4B80fDD2AdFF2412A7BebF9dF42cB40e](https://etherscan.io/address/0x43edB88C4B80fDD2AdFF2412A7BebF9dF42cB40e) |
| L1CrossDomainMessenger | [0x866E82a600A1414e583f7F13623F1aC5d58b0Afa](https://etherscan.io/address/0x866E82a600A1414e583f7F13623F1aC5d58b0Afa) |
| L1ERC721Bridge | [0x608d94945A64503E642E6370Ec598e519a2C1E53](https://etherscan.io/address/0x608d94945A64503E642E6370Ec598e519a2C1E53) |
| L1StandardBridge | [0x3154Cf16ccdb4C6d922629664174b904d80F2C35](https://etherscan.io/address/0x3154Cf16ccdb4C6d922629664174b904d80F2C35) |
| NitroValidator | [0x47C1ab20fac92c789d9e5708D06641c79b03C460](https://etherscan.io/address/0x47C1ab20fac92c789d9e5708D06641c79b03C460) |
| OptimismMintableERC20Factory | [0x05cc379EBD9B30BbA19C6fA282AB29218EC61D84](https://etherscan.io/address/0x05cc379EBD9B30BbA19C6fA282AB29218EC61D84) |
| OptimismPortal | [0x49048044D57e1C92A77f79988d21Fa8fAF74E97e](https://etherscan.io/address/0x49048044D57e1C92A77f79988d21Fa8fAF74E97e) |
| P384Verifier | [0xe0aa6868e14300355001130C6DC29f2f4467D86c](https://etherscan.io/address/0xe0aa6868e14300355001130C6DC29f2f4467D86c) |
| ProtocolVersionsProxy | [0x7480Afc8D99a5c645c247dB5A1e4a4f440e6e095](https://etherscan.io/address/0x7480Afc8D99a5c645c247dB5A1e4a4f440e6e095) |
| ProxyAdmin | [0x0475cBCAebd9CE8AfA5025828d5b98DFb67E059E](https://etherscan.io/address/0x0475cBCAebd9CE8AfA5025828d5b98DFb67E059E) |
| RiscZeroSetVerifier | [0x5005aBa3DFf7C940fcc1e48DccCAD611a80eEB85](https://etherscan.io/address/0x5005aBa3DFf7C940fcc1e48DccCAD611a80eEB85) |
| RiscZeroVerifierRouter | [0x8EaB2D97Dfce405A1692a21b3ff3A172d593D319](https://etherscan.io/address/0x8EaB2D97Dfce405A1692a21b3ff3A172d593D319) |
| SystemConfig | [0x73a79Fab69143498Ed3712e519A88a918e1f4072](https://etherscan.io/address/0x73a79Fab69143498Ed3712e519A88a918e1f4072) |
| SystemDictator | [0x1fE3fdd1F0193Dd657C0a9AAC37314D6B479E557](https://etherscan.io/address/0x1fE3fdd1F0193Dd657C0a9AAC37314D6B479E557) |
| TEEProverRegistryProxy | [0x1af2A7E537DE2eE795DE5B8BfbB1Ad0DD513A5aA](https://etherscan.io/address/0x1af2A7E537DE2eE795DE5B8BfbB1Ad0DD513A5aA) |
| TEEVerifier | [0x1FbA0C57b07Af804A9717e51dec9CC27FBC12228](https://etherscan.io/address/0x1FbA0C57b07Af804A9717e51dec9CC27FBC12228) |
| ZkVerifier | [0xB88D95bDf6972508942d184866890c1834219B75](https://etherscan.io/address/0xB88D95bDf6972508942d184866890c1834219B75) |
#### Unused OP Stack addresses
The [OP Stack SDK](https://stack.optimism.io/docs/build/sdk/#unneeded-contract-addresses) requires the following addresses to be set even though Base does not use them. Pass the zero address for each:
- `StateCommitmentChain`
- `CanonicalTransactionChain`
- `BondManager`
### Ethereum Sepolia
The Sepolia proof contracts moved with the Cobalt upgrade on 2026-09-23. `AggregateVerifier (Multiproof)` and `ZkVerifier` now point at new deployments. The Nitro attestation path is listed as `NitroValidator`, with `CertManager` and `P384Verifier` beside it, in place of the old `NitroEnclaveVerifier` row. If you pinned any of the old Sepolia addresses, update them. The Mainnet `AggregateVerifier` and Nitro rows changed later, ahead of the Mainnet activation; see the note above that table.
| Name | Address |
| :----------------------------- | :---------------------------------------------------------------------------------------------------------------------------- |
| AddressManager | [0x709c2B8ef4A9feFc629A8a2C1AF424Dc5BD6ad1B](https://sepolia.etherscan.io/address/0x709c2B8ef4A9feFc629A8a2C1AF424Dc5BD6ad1B) |
| AggregateVerifier (Multiproof) | [0xd702aaE6221f36Dfe7e8EBC4315D64344A9dB4CB](https://sepolia.etherscan.io/address/0xd702aaE6221f36Dfe7e8EBC4315D64344A9dB4CB) |
| AnchorStateRegistryProxy | [0x2fF5cC82dBf333Ea30D8ee462178ab1707315355](https://sepolia.etherscan.io/address/0x2fF5cC82dBf333Ea30D8ee462178ab1707315355) |
| CertManager | [0x50521128e3eB8708F05129D7B7283737D55a1936](https://sepolia.etherscan.io/address/0x50521128e3eB8708F05129D7B7283737D55a1936) |
| DelayedWETHProxy (FDG) | [0xd3683e4947A7769603Ab6418eC02f000CE3cF30b](https://sepolia.etherscan.io/address/0xd3683e4947A7769603Ab6418eC02f000CE3cF30b) |
| DelayedWETHProxy (Multiproof) | [0xD6e2d9D4f1f8865AC983eE848983fb1979429914](https://sepolia.etherscan.io/address/0xD6e2d9D4f1f8865AC983eE848983fb1979429914) |
| DelayedWETHProxy (PDG) | [0x32cE910d9C6c8F78dc6779c1499aB05F281A054e](https://sepolia.etherscan.io/address/0x32cE910d9C6c8F78dc6779c1499aB05F281A054e) |
| DisputeGameFactoryProxy | [0xd6E6dBf4F7EA0ac412fD8b65ED297e64BB7a06E1](https://sepolia.etherscan.io/address/0xd6E6dBf4F7EA0ac412fD8b65ED297e64BB7a06E1) |
| FaultDisputeGame | [0x6dDBa09bc4cCB0D6Ca9Fc5350580f74165707499](https://sepolia.etherscan.io/address/0x6dDBa09bc4cCB0D6Ca9Fc5350580f74165707499) |
| FaultDisputeGame (Kona) | [0x6dDBa09bc4cCB0D6Ca9Fc5350580f74165707499](https://sepolia.etherscan.io/address/0x6dDBa09bc4cCB0D6Ca9Fc5350580f74165707499) |
| L1CrossDomainMessenger | [0xC34855F4De64F1840e5686e64278da901e261f20](https://sepolia.etherscan.io/address/0xC34855F4De64F1840e5686e64278da901e261f20) |
| L1ERC721Bridge | [0x21eFD066e581FA55Ef105170Cc04d74386a09190](https://sepolia.etherscan.io/address/0x21eFD066e581FA55Ef105170Cc04d74386a09190) |
| L1StandardBridge | [0xfd0Bf71F60660E2f608ed56e1659C450eB113120](https://sepolia.etherscan.io/address/0xfd0Bf71F60660E2f608ed56e1659C450eB113120) |
| MIPS | [0x6463dEE3828677F6270d83d45408044fc5eDB908](https://sepolia.etherscan.io/address/0x6463dEE3828677F6270d83d45408044fc5eDB908) |
| NitroValidator | [0x16970101Ea32243cC80a2e0C91427e8bDA70F689](https://sepolia.etherscan.io/address/0x16970101Ea32243cC80a2e0C91427e8bDA70F689) |
| OptimismMintableERC20Factory | [0xb1efB9650aD6d0CC1ed3Ac4a0B7f1D5732696D37](https://sepolia.etherscan.io/address/0xb1efB9650aD6d0CC1ed3Ac4a0B7f1D5732696D37) |
| OptimismPortal | [0x49f53e41452C74589E85cA1677426Ba426459e85](https://sepolia.etherscan.io/address/0x49f53e41452C74589E85cA1677426Ba426459e85) |
| P384Verifier | [0xa8320712fF181D74e719Ff7E6E1012bbe4687b26](https://sepolia.etherscan.io/address/0xa8320712fF181D74e719Ff7E6E1012bbe4687b26) |
| PermissionedDisputeGame | [0x58bf355C5d4EdFc723eF89d99582ECCfd143266A](https://sepolia.etherscan.io/address/0x58bf355C5d4EdFc723eF89d99582ECCfd143266A) |
| PreimageOracle | [0x1fb8cdFc6831fc866Ed9C51aF8817Da5c287aDD3](https://sepolia.etherscan.io/address/0x1fb8cdFc6831fc866Ed9C51aF8817Da5c287aDD3) |
| ProtocolVersionsProxy | [0x15B721B12CF3b0C4400c8a2935A0Ae391c2eF65b](https://sepolia.etherscan.io/address/0x15B721B12CF3b0C4400c8a2935A0Ae391c2eF65b) |
| ProxyAdmin | [0x0389E59Aa0a41E4A413Ae70f0008e76CAA34b1F3](https://sepolia.etherscan.io/address/0x0389E59Aa0a41E4A413Ae70f0008e76CAA34b1F3) |
| RiscZeroSetVerifier | [0xcb9D14347b1e816831ECeE46EC199144F360B55c](https://sepolia.etherscan.io/address/0xcb9D14347b1e816831ECeE46EC199144F360B55c) |
| RiscZeroVerifierRouter | [0x925d8331ddc0a1F0d96E68CF073DFE1d92b69187](https://sepolia.etherscan.io/address/0x925d8331ddc0a1F0d96E68CF073DFE1d92b69187) |
| SystemConfig | [0xf272670eb55e895584501d564AfEB048bEd26194](https://sepolia.etherscan.io/address/0xf272670eb55e895584501d564AfEB048bEd26194) |
| TEEProverRegistryProxy | [0xf0d7E15673fBA052e83d7f2b26BB6071E86b972e](https://sepolia.etherscan.io/address/0xf0d7E15673fBA052e83d7f2b26BB6071E86b972e) |
| TEEVerifier | [0x92F6dD3501E51B8b20C77b959becaaebeB210e17](https://sepolia.etherscan.io/address/0x92F6dD3501E51B8b20C77b959becaaebeB210e17) |
| ZkVerifier | [0xa738E13d97A3f10b307C2CD190edd3E227A72D68](https://sepolia.etherscan.io/address/0xa738E13d97A3f10b307C2CD190edd3E227A72D68) |
## Base admin addresses
### Base Mainnet
| Admin Role | Address | Type of Key |
| :--------------------- | :-------------------------------------------------------------------------------------------------------------------- | :----------------------------------- |
| Base Security Council | [0x20AcF55A3DCfe07fC4cecaCFa1628F788EC8A4Dd](https://etherscan.io/address/0x20AcF55A3DCfe07fC4cecaCFa1628F788EC8A4Dd) | Gnosis Safe |
| Batch Sender | [0x5050f69a9786f081509234f1a7f4684b5e5b76c9](https://etherscan.io/address/0x5050f69a9786f081509234f1a7f4684b5e5b76c9) | EOA managed by Coinbase Technologies |
| Batch Inbox | [0xff00000000000000000000000000000000008453](https://etherscan.io/address/0xff00000000000000000000000000000000008453) | EOA (with no known private key) |
| CB Multisig | [0x9855054731540A48b28990B63DcF4f33d8AE46A1](https://etherscan.io/address/0x9855054731540A48b28990B63DcF4f33d8AE46A1) | Gnosis Safe |
| Output Proposer | [0xc1366Fabe614d42D367A1ecE61821238A1d31cF5](https://etherscan.io/address/0xc1366Fabe614d42D367A1ecE61821238A1d31cF5) | EOA managed by Coinbase Technologies |
| Proxy Admin Owner (L1) | [0x7bB41C3008B3f03FE483B28b8DB90e19Cf07595c](https://etherscan.io/address/0x7bB41C3008B3f03FE483B28b8DB90e19Cf07595c) | Gnosis Safe |
| Challenger | [0x819501cdA743a606A93dbEF254FE0D263Ce7d102](https://etherscan.io/address/0x819501cdA743a606A93dbEF254FE0D263Ce7d102) | EOA managed by Coinbase Technologies |
| SystemConfig owner | [0x14536667Cd30e52C0b458BaACcB9faDA7046E056](https://etherscan.io/address/0x14536667Cd30e52C0b458BaACcB9faDA7046E056) | Gnosis Safe |
| Guardian | [0x7bB41C3008B3f03FE483B28b8DB90e19Cf07595c](https://etherscan.io/address/0x7bB41C3008B3f03FE483B28b8DB90e19Cf07595c) | Gnosis Safe |
| Incident Multisig | [0x14536667Cd30e52C0b458BaACcB9faDA7046E056](https://etherscan.io/address/0x14536667Cd30e52C0b458BaACcB9faDA7046E056) | Gnosis Safe |
| Registrar | [0xd87488Dbb5b6F47cc6c15Dd95Bb60c83D3031b04](https://etherscan.io/address/0xd87488Dbb5b6F47cc6c15Dd95Bb60c83D3031b04) | EOA managed by Coinbase Technologies |
### Base Sepolia
| Admin Role | Address | Type of Key |
| :--------------------- | :---------------------------------------------------------------------------------------------------------------------------- | :----------------------------------- |
| Base Security Council | [0x6AF0674791925f767060Dd52f7fB20984E8639d8](https://sepolia.etherscan.io/address/0x6AF0674791925f767060Dd52f7fB20984E8639d8) | Gnosis Safe |
| Batch Sender | [0x6CDEbe940BC0F26850285cacA097C11c33103E47](https://sepolia.etherscan.io/address/0x6CDEbe940BC0F26850285cacA097C11c33103E47) | EOA managed by Coinbase Technologies |
| Batch Inbox | [0xff00000000000000000000000000000000084532](https://sepolia.etherscan.io/address/0xff00000000000000000000000000000000084532) | EOA (with no known private key) |
| CB Multisig | [0x646132A1667ca7aD00d36616AFBA1A28116C770A](https://sepolia.etherscan.io/address/0x646132A1667ca7aD00d36616AFBA1A28116C770A) | Gnosis Safe |
| Output Proposer | [0xdb84125f2f4229c81c579f41bc129c71b174eb58](https://sepolia.etherscan.io/address/0xdb84125f2f4229c81c579f41bc129c71b174eb58) | EOA managed by Coinbase Technologies |
| Proxy Admin Owner (L1) | [0x0fe884546476dDd290eC46318785046ef68a0BA9](https://sepolia.etherscan.io/address/0x0fe884546476dDd290eC46318785046ef68a0BA9) | Gnosis Safe |
| Challenger | [0xadc09b63a3ac57a2ce86d946617a18df9db029a1](https://sepolia.etherscan.io/address/0xadc09b63a3ac57a2ce86d946617a18df9db029a1) | EOA managed by Coinbase Technologies |
| SystemConfig owner | [0x646132A1667ca7aD00d36616AFBA1A28116C770A](https://sepolia.etherscan.io/address/0x646132A1667ca7aD00d36616AFBA1A28116C770A) | Gnosis Safe |
| Guardian | [0x0fe884546476dDd290eC46318785046ef68a0BA9](https://sepolia.etherscan.io/address/0x0fe884546476dDd290eC46318785046ef68a0BA9) | Gnosis Safe |
| Incident Multisig | [0x646132A1667ca7aD00d36616AFBA1A28116C770A](https://sepolia.etherscan.io/address/0x646132A1667ca7aD00d36616AFBA1A28116C770A) | Gnosis Safe |
---
# Block Building
Source: https://basehub.org/network/block-building/
Description: How Base orders transactions inside blocks, including Flashblocks 200ms preconfirmations and the per-transaction gas cap enforced by the mempool.
import { Aside } from '@astrojs/starlight/components';
Base block ordering is independent of the user-facing experience: the sequencer can build sub-block updates without exposing them, and the underlying ordering rules continue to apply.
## Current configuration
| Network | Active configuration | Upcoming |
|--------------|---------------------------------------------------------------------------------------|----------|
| Base Mainnet | [Flashblocks](#flashblocks) and [per-transaction gas maximum](#per-transaction-gas-maximum) | |
| Base Sepolia | [Flashblocks](#flashblocks) and [per-transaction gas maximum](#per-transaction-gas-maximum) | |
The [configuration changelog](/network/configuration-changelog/) records every change to block building parameters and other network-level settings.
## Flashblocks
Blocks are produced by [base-builder](https://github.com/base/base/tree/main/crates/builder), with a fresh priority fee auction running every **200ms**. The auction shortens effective block times from 2 seconds to 200 milliseconds via preconfirmations.
Three properties distinguish Flashblocks from vanilla ordering:
1. **Timing** — The builder emits one Flashblock every 200ms, sealing a slice of the eventual block. Once a Flashblock is broadcast, its ordering is final; later transactions with higher priority fees cannot displace transactions already committed to an earlier Flashblock.
2. **Gas allocation** — Each Flashblock has a progressively larger gas budget. Flashblock 1 may consume up to one tenth of the block gas limit, Flashblock 2 up to two tenths, and so on through Flashblock 10, which may use the full limit.
| Flashblock | Available gas |
|------------|---------------|
| 1 | ~40M gas (1/10) |
| 2 | ~80M gas (2/10) |
| 3 | ~120M gas (3/10) |
| ... | ... |
| 10 | ~400M gas (full) |
3. **Dynamic mempool** — The builder keeps accepting new transactions while a Flashblock is being assembled. This minimizes inclusion latency, but transactions are ordered by fee *at the moment of selection*, not against every transaction that arrived during the 200ms window. A high-fee transaction that arrives late may appear after a lower-fee transaction that was already committed.
## Per-transaction gas maximum
Since the [Azul hardfork](/specifications/azul-overview/), Base applies a protocol-level ceiling of **16,777,216 gas (2^24)** to any single transaction, as specified by [EIP-7825](https://eips.ethereum.org/EIPS/eip-7825). A transaction that declares a gas limit above this figure is **rejected during block validation**, and `eth_sendTransaction` or `eth_sendRawTransaction` returns a JSON-RPC error — for instance, `exceeds maximum per-transaction gas limit`.
Operators running bundlers for smart contract wallets need to size each bundle so that it stays within this limit.
## Vanilla ordering
Under the legacy configuration, [op-geth](https://github.com/ethereum-optimism/op-geth) builds a block every 2 seconds and orders transactions inside the block by priority fee. See the [reference implementation](https://github.com/ethereum-optimism/op-geth/blob/optimism/miner/worker.go#L627).
## Source code
The software that applies these ordering rules is public, from base-builder to the transaction pool. [Reliability and Liveness](/security/reliability-and-liveness/#open-source-sequencer-components) lists each component and links to its repository.
---
# Bridges
Source: https://basehub.org/network/bridges/
Description: Routes for moving assets between Base and Ethereum, other EVM chains, Solana, or Bitcoin (standard bridge, fast bridges, aggregators, and cross-chain messaging protocols), plus Base-Solana bridge addresses.
import { Aside, Card, CardGrid } from '@astrojs/starlight/components';
Base supports asset transfers from Ethereum, Solana, and Bitcoin through a network of third-party bridge providers. The Base-operated bridge at bridge.base.org is no longer available; the providers below cover the same asset flows.
For frequently asked questions, jump to the [FAQ](#faq).
## Picking a route
Where your assets sit now decides which of the options below applies.
| Coming from | Route | Typical assets |
|---|---|---|
| A Coinbase account | Withdraw straight to Base — no bridge | ETH, USDC, cbBTC |
| Ethereum (L1) | [Superbridge](https://superbridge.app/?fromChainId=1&toChainId=8453) or [Brid.gg](https://www.brid.gg/?fromChainId=1&toChainId=8453), or a [fast bridge](#fast-bridges) | ETH, ERC-20s |
| Another EVM chain | A [fast bridge](#fast-bridges) or a [bridge aggregator](#bridge-aggregators) | ETH, stablecoins, ERC-20s |
| Solana | [Base-Solana bridge](/introduction/base-solana-bridge/) | SOL, SPL tokens |
| Bitcoin | [Garden](https://app.garden.finance/?output-chain=base&output-asset=cbBTC) | BTC to cbBTC |
Fast bridges and aggregators are run by third parties, and each one carries its own trust assumptions. [Bridge types compared](#bridge-types-compared) sets them side by side with the standard bridge.
## Bridge types compared
Every route into or out of Base falls into one of three groups. What separates them is how long a move takes and whose honesty you rely on for the funds to arrive.
| Bridge type | Withdrawal to Ethereum | Who you rely on |
|---|---|---|
| [Standard bridge](#ethereum-and-base) | The 5-day [finalization window](/network/bridging-and-withdrawals/), cut to 1 day when a TEE proof and a ZK proof both back the proposal | Base's proofs, checked on Ethereum |
| [Fast bridge](#fast-bridges) | Usually seconds to minutes | The provider |
| [Messaging protocol](#cross-chain-messaging-protocols) | Depends on the protocol and how it is configured | The protocol and the token's own settings |
Only standard-bridge withdrawals from Base back to Ethereum sit through the finalization window. Standard-bridge deposits from Ethereum into Base do not wait for it. [Bridging and Withdrawals](/network/bridging-and-withdrawals/) explains why the window exists.
## Ethereum and Base
### Superbridge
Superbridge moves ETH and other supported assets between Ethereum mainnet (L1) and Base.
Supported networks:
- [Base Mainnet](https://superbridge.app/base)
- [Base Sepolia (Testnet)](https://superbridge.app/base-sepolia)
### Brid.gg
Brid.gg also bridges ETH and supported assets between Ethereum mainnet (L1) and Base.
Supported networks:
- [Base Mainnet](https://brid.gg/base)
- [Base Sepolia (Testnet)](https://testnet.brid.gg/base-sepolia)
A standard-bridge withdrawal from Base to Ethereum still has to clear the finalization window shown in [Bridge types compared](#bridge-types-compared). Superbridge can also send a transfer through a third-party bridge, so confirm which route it picked before you sign.
### Programmatic bridging from Ethereum
The [sample code repository](https://github.com/base-org/guides/tree/main/bridge/native) demonstrates how to bridge ETH and ERC-20s from Ethereum to Base.
### Token issuers
If you have an ERC-20 deployed on Ethereum and want to make it bridgeable to Base, follow the [bridge-an-L1-token guide](https://docs.base.org/base-chain/quickstart/bridge-token). It walks through deploying via the standard bridge contracts and adding your token to the Superchain token list.
If the goal is one token that lives on Base and on other chains at once, look at a [cross-chain messaging protocol](#cross-chain-messaging-protocols) instead.
## Fast bridges
A fast bridge moves assets in either direction between Base, Ethereum, and other chains, usually within seconds to minutes. The provider pays you from liquidity it already holds on the destination chain, then squares up afterwards through its own settlement process.
| Provider | Model | Links |
|---|---|---|
| Across | Intent-based; competing relayers fill each transfer | [App](https://app.across.to/bridge), [Docs](https://docs.across.to) |
| Relay | Bridging and swaps, filled by solvers | [App](https://relay.link), [Docs](https://docs.relay.link) |
| Stargate | Liquidity pools on top of LayerZero | [App](https://stargate.finance/bridge), [Docs](https://stargateprotocol.gitbook.io/stargate/v2-user-docs) |
## Bridge aggregators
An aggregator pulls quotes from many bridges and chooses one for you. That is useful when the chain you hold assets on has no direct route to Base. Your security is whatever the chosen bridge provides, so look at which bridge the aggregator picked before you confirm.
Bridge and swap aggregator built on LI.FI. [jumper.exchange](https://jumper.exchange)
Bridge and swap aggregator built on Socket. [bungee.exchange](https://www.bungee.exchange)
## Cross-chain messaging protocols
A token issuer can use a cross-chain messaging protocol to run a single token across Base and other chains. Both protocols below support Base Mainnet.
| Protocol | Token standard | Base reference |
|---|---|---|
| Chainlink CCIP | Cross-Chain Token (CCT) | [Base on CCIP](https://docs.chain.link/ccip/directory/mainnet/chain/ethereum-mainnet-base-1) |
| LayerZero V2 | Omnichain Fungible Token (OFT) | [OFT quickstart](https://docs.layerzero.network/v2/developers/evm/oft/quickstart) |
LayerZero identifies Base Mainnet as endpoint ID `30184`. The full list is on its [deployed contracts](https://docs.layerzero.network/v2/deployments/deployed-contracts) page.
The protocol's own network secures a token issued this way. Base's standard bridge plays no part. Pick the protocol, and its security settings, before the token launches.
## Solana and Base
The Base-Solana bridge supports two-way token transfers and arbitrary message passing between Base and Solana.
Capabilities include:
- Transferring SOL and SPL tokens to and from Base
- Sending arbitrary cross-chain messages
- Deploying wrapped tokens on either side
- Optional auto-relay for instant settlement
[Complete bridge guide with code samples and contract addresses](/introduction/base-solana-bridge/)
[Production terminal UI for bridging and contract calls](https://terminallyonchain.com/)
### Contract addresses
| Network | Contract | Address |
|---------|----------|---------|
| Base Mainnet | Bridge | `0x3eff766C76a1be2Ce1aCF2B69c78bCae257D5188` |
| Base Mainnet | SOL Token | `0x311935Cd80B76769bF2ecC9D8Ab7635b2139cf82` |
| Solana Mainnet | Bridge Program | `HNCne2FkVaNghhjKXapxJzPaBvAKDG1Ge3gqhZyfVWLM` |
## Bitcoin to Base
### Garden
Garden is a fast, non-custodial bridge that moves BTC and supported assets from Ethereum, Solana, and other chains directly to Base.
Supported networks:
- [Base Mainnet](https://app.garden.finance/?output-chain=base&output-asset=cbBTC)
- [Base Sepolia (Testnet)](https://testnet.garden.finance/?output-chain=base_sepolia&output-asset=USDT)
## Disclaimer
Coinbase Technologies, Inc. links to these independent providers for convenience and accepts no responsibility for their operations. Any interaction with a listed provider is solely between you and that provider.
## FAQ
**Can I still use the bridge on bridge.base.org?**
No. The bridge at bridge.base.org has been deprecated.
**I used bridge.base.org previously — how do I find my deposit or withdrawal?**
Look up your transaction on one of the Superchain Bridges listed above.
**Why was the bridge on bridge.base.org deprecated?**
Base is committed to decentralization and the Superchain. Handing bridging off to community-operated providers strengthens censorship resistance and reduces single points of control.
**Who runs the Superchain Bridges (Garden.finance, Superbridge.app, Brid.gg)?**
Superchain Bridges are operated by independent third parties, not by Coinbase Technologies, Inc. ("Coinbase"). Coinbase does not control or operate them and assumes no responsibility for their performance. Each provider may require you to accept its terms of service and privacy policy — review them before using a bridge. Listing a bridge here is not an endorsement.
**How does the Base-Solana bridge work?**
A validator set verifies cross-chain messages. Bridging from Solana to Base locks the source tokens on Solana and mints wrapped tokens on Base. Bridging from Base to Solana burns the wrapped tokens on Base and releases the originals on Solana. The [full bridge documentation](/introduction/base-solana-bridge/) covers the implementation.
**Where can I get help if I have a question or problem?**
The [Base Discord](https://base.org/discord) is staffed around the clock. Open a ticket in the `#general-support` channel for assistance.
---
# Bridging and Withdrawals
Source: https://basehub.org/network/bridging-and-withdrawals/
Description: How deposits into Base and standard withdrawals back to Ethereum work, why withdrawals take days (5, or 1 with two proofs), and the faster bridge options available.
import { Aside } from '@astrojs/starlight/components';
Bridging is the movement of assets or messages across chains. Moving value into Base is a deposit; moving it out is a withdrawal.
The two directions have very different timing because each leans on a different part of the rollup protocol. A deposit originates on another chain and lands as a transaction on Base. A standard withdrawal originates on Base, then has to be proven on Ethereum and can only be finalized once its finalization window has closed.
## Deposits to Base
A deposit is kicked off somewhere other than Base and surfaces as a Base transaction. When the source is Ethereum, the L1 transaction logs data, and Base nodes read that data to construct the corresponding L2 deposit transaction.
These deposit transactions are baked into the protocol rather than submitted like ordinary user transactions. They skip the usual signature, nonce, and fee fields, since authorization comes from the L1 deposit event and the L2 gas was already paid on L1.
From a user's point of view it is simple: confirm and process the transaction on the source chain, and the asset or message arrives on Base shortly after. The [deposits specification](https://docs.base.org/base-chain/specs/protocol/bridging/deposits) covers the protocol mechanics.
## Standard withdrawals
A standard withdrawal is a single cross-domain action that opens on Base and closes on Ethereum. Through it you can move ETH, bridge supported ERC-20 tokens, or pass a message from Base to a contract on L1.
It proceeds in three stages:
1. **Initiate on Base** — submitting the withdrawal on Base writes its message into the `L2ToL1MessagePasser` contract.
2. **Prove on Ethereum** — after Base has published the state that contains it, anyone may hand the `OptimismPortal` contract a proof that the message is present on Base.
3. **Finalize on Ethereum** — when the finalization window closes, anyone can finalize on Ethereum, which hands over the assets or delivers the message to its destination.
Whoever proves or finalizes does not have to be whoever started the withdrawal, so wallets, bridge front-ends, and other services can shepherd users through the steps.
## Why standard withdrawals take days
Withdrawals are backed by Base's proof system. Every withdrawal proof is anchored to an output root that commits to Base state, and the finalization window exists so that participants can challenge a bad output root before anything resting on it is allowed to finalize.
The window used to be a flat 7 days. [Beryl](/specifications/beryl-overview/) cut the single-proof dispute game to **5 days**, and the dual-proof fast path, where a TEE proof and a ZK proof agree on one proposal, stays at **1 day**. Almost all of a withdrawal's end-to-end time is this window. Getting the relevant Base state proposed on Ethereum usually adds just 20 to 60 minutes, on top of the prove and finalize transactions themselves.
Absent a successful challenge, the withdrawal finalizes when the window expires. Should an output root prove invalid, the chain itself is unaffected — Base does not reorg — but any withdrawal anchored to that root is blocked and has to be re-proven against a sound one.
The [Transaction Finality](/network/transaction-finality/#finality-for-withdrawals) page explains how this differs from finality for everyday Base transactions.
## Faster withdrawal options
A number of bridge providers advertise withdrawals quicker than the native protocol allows. They leave the underlying finalization window untouched; what they do instead is advance users their funds on the far chain — backed by liquidity, relayers, or market makers — ahead of the standard withdrawal actually settling.
The convenience comes with trade-offs: each provider layers on its own trust assumptions and charges its own fees. Vet a provider's terms, asset support, pricing, liquidity, and security design before depending on it. The [Bridges](/network/bridges/#fast-bridges) page lists the fast-bridge providers, and its [bridge types comparison](/network/bridges/#bridge-types-compared) shows how they differ from the standard bridge.
## Standard bridge contracts
Cross-domain ETH and ERC-20 transfers run through the standard bridges, which wrap the cross-domain messenger contracts in a uniform deposit-and-withdrawal interface.
On the L2 side, the `L2StandardBridge` is a predeploy at `0x4200000000000000000000000000000000000010`.
Contract-level detail lives in the [standard bridges specification](https://docs.base.org/base-chain/specs/protocol/bridging/bridges) and the [withdrawals specification](https://docs.base.org/base-chain/specs/protocol/bridging/withdrawals).
---
# Configuration Changelog
Source: https://basehub.org/network/configuration-changelog/
Description: A dated log of block-building, fee, and other network parameter changes for Base Mainnet and Base Sepolia.
The tables below track network parameter changes — block building, fees, and other operational settings — for Base Mainnet and Base Sepolia.
## Base Mainnet
| Date | Change | Documentation |
|------|--------|---------------|
| May 28, 2026 | Azul: Reduced per-transaction gas maximum to 16,777,216 (2^24) via EIP-7825 | [Per-Transaction Gas Maximum](/network/block-building/#per-transaction-gas-maximum) |
| February 19, 2026 | Increased Minimum Base Fee to 5,000,000 wei | [Minimum Base Fee](/network/network-fees/#minimum-base-fee) |
| February 4, 2026 | Increased EIP-1559 Denominator to 125 | [EIP-1559 Fee Parameters](/network/network-fees/#eip-1559-fee-parameters) |
| February 2, 2026 | Increased Minimum Base Fee to 2,000,000 wei | [Minimum Base Fee](/network/network-fees/#minimum-base-fee) |
| January 22, 2026 | Increased Minimum Base Fee to 1,000,000 wei | [Minimum Base Fee](/network/network-fees/#minimum-base-fee) |
| December 18, 2025 | Increased Minimum Base Fee to 500,000 wei | [Minimum Base Fee](/network/network-fees/#minimum-base-fee) |
| December 4, 2025 | Enabled Minimum Base Fee (200,000 wei) | [Minimum Base Fee](/network/network-fees/#minimum-base-fee) |
| September 17, 2025 | Enabled Per-Transaction Gas Maximum | [Per-Transaction Gas Maximum](/network/block-building/#per-transaction-gas-maximum) |
| September 11, 2025 | Ended testing Per-Transaction Gas Maximum | [Per-Transaction Gas Maximum](/network/block-building/#per-transaction-gas-maximum) |
| September 10, 2025 | Started testing Per-Transaction Gas Maximum | [Per-Transaction Gas Maximum](/network/block-building/#per-transaction-gas-maximum) |
| July 7, 2025 | Enabled Flashblocks | [Flashblocks](/network/block-building/#flashblocks) |
| May 15, 2025 | Ended testing Flashblocks | [Flashblocks](/network/block-building/#flashblocks) |
| May 15, 2025 | Started testing Flashblocks | [Flashblocks](/network/block-building/#flashblocks) |
## Base Sepolia
| Date | Change | Documentation |
|------|--------|---------------|
| April 20, 2026 | Azul: Reduced per-transaction gas maximum to 16,777,216 (2^24) via EIP-7825 | [Per-Transaction Gas Maximum](/network/block-building/#per-transaction-gas-maximum) |
| February 19, 2026 | Increased Minimum Base Fee to 5,000,000 wei | [Minimum Base Fee](/network/network-fees/#minimum-base-fee) |
| February 10, 2026 | Increased EIP-1559 Denominator to 125 | [EIP-1559 Fee Parameters](/network/network-fees/#eip-1559-fee-parameters) |
| February 10, 2026 | Increased Minimum Base Fee to 2,000,000 wei | [Minimum Base Fee](/network/network-fees/#minimum-base-fee) |
| November 20, 2025 | Enabled Minimum Base Fee (200,000 wei) | [Minimum Base Fee](/network/network-fees/#minimum-base-fee) |
| September 3, 2025 | Enabled Per-Transaction Gas Maximum | [Per-Transaction Gas Maximum](/network/block-building/#per-transaction-gas-maximum) |
| February 25, 2025 | Enabled Flashblocks | [Flashblocks](/network/block-building/#flashblocks) |
---
# Differences Between Ethereum and Base
Source: https://basehub.org/network/diffs-ethereum-base/
Description: Short reference to the protocol-level differences developers encounter when moving apps from Ethereum to Base.
Base targets full compatibility with Ethereum, so most apps port over without modification. A small set of behavioral differences are worth knowing before you ship.
The notable differences are:
- [Flashblocks](/flashblocks/app-integration/)
- [Minimum base fee](/network/network-fees/#minimum-base-fee)
- [Bridging](https://docs.optimism.io/stack/differences#bridging)
- [Opcodes](https://docs.optimism.io/stack/differences#opcodes)
- [Address aliasing](https://docs.optimism.io/stack/differences#address-aliasing)
- [Transaction costs](https://docs.optimism.io/stack/differences#transaction-fees)
- [Chain finality](https://docs.optimism.io/stack/differences#chain-finality)
---
# Ecosystem Contracts
Source: https://basehub.org/network/ecosystem-contracts/
Description: Deployed addresses for Multicall3, Uniswap v2, and Uniswap v3 on Base Mainnet and Base Sepolia, with block explorer links.
import { Aside } from '@astrojs/starlight/components';
The tables below list deployment addresses for widely used onchain apps on Base.
## Base Mainnet
### Multicall3
| Contract | Address |
| :--------- | :-------------------------------------------------------------------------------------------------------------------- |
| Multicall3 | [0xcA11bde05977b3631167028862bE2a173976CA11](https://basescan.org/address/0xcA11bde05977b3631167028862bE2a173976CA11) |
### Uniswap v3
| Contract | Address |
| :----------------------------------- | :-------------------------------------------------------------------------------------------------------------------- |
| `Permit2` | [0x000000000022D473030F116dDEE9F6B43aC78BA3](https://basescan.org/address/0x000000000022D473030F116dDEE9F6B43aC78BA3) |
| `universal router` | [0x198EF79F1F515F02dFE9e3115eD9fC07183f02fC](https://basescan.org/address/0x198EF79F1F515F02dFE9e3115eD9fC07183f02fC) |
| `v3CoreFactory` | [0x33128a8fC17869897dcE68Ed026d694621f6FDfD](https://basescan.org/address/0x33128a8fC17869897dcE68Ed026d694621f6FDfD) |
| `multicall` | [0x091e99cb1C49331a94dD62755D168E941AbD0693](https://basescan.org/address/0x091e99cb1C49331a94dD62755D168E941AbD0693) |
| `proxyAdmin` | [0x3334d83e224aF5ef9C2E7DDA7c7C98Efd9621fA9](https://basescan.org/address/0x3334d83e224aF5ef9C2E7DDA7c7C98Efd9621fA9) |
| `tickLens` | [0x0CdeE061c75D43c82520eD998C23ac2991c9ac6d](https://basescan.org/address/0x0CdeE061c75D43c82520eD998C23ac2991c9ac6d) |
| `nftDescriptor` | [0xF9d1077fd35670d4ACbD27af82652a8d84577d9F](https://basescan.org/address/0xF9d1077fd35670d4ACbD27af82652a8d84577d9F) |
| `nonfungibleTokenPositionDescriptor` | [0x4f225937EDc33EFD6109c4ceF7b560B2D6401009](https://basescan.org/address/0x4f225937EDc33EFD6109c4ceF7b560B2D6401009) |
| `descriptorProxy` | [0x4615C383F85D0a2BbED973d83ccecf5CB7121463](https://basescan.org/address/0x4615C383F85D0a2BbED973d83ccecf5CB7121463) |
| `nonfungibleTokenPositionManager` | [0x03a520b32C04BF3bEEf7BEb72E919cf822Ed34f1](https://basescan.org/address/0x03a520b32C04BF3bEEf7BEb72E919cf822Ed34f1) |
| `v3Migrator` | [0x23cF10b1ee3AdfCA73B0eF17C07F7577e7ACd2d7](https://basescan.org/address/0x23cF10b1ee3AdfCA73B0eF17C07F7577e7ACd2d7) |
| `v3Staker` | [0x42bE4D6527829FeFA1493e1fb9F3676d2425C3C1](https://basescan.org/address/0x42bE4D6527829FeFA1493e1fb9F3676d2425C3C1) |
| `quoterV2` | [0x3d4e44Eb1374240CE5F1B871ab261CD16335B76a](https://basescan.org/address/0x3d4e44Eb1374240CE5F1B871ab261CD16335B76a) |
| `swapRouter` | [0x2626664c2603336E57B271c5C0b26F421741e481](https://basescan.org/address/0x2626664c2603336E57B271c5C0b26F421741e481) |
### Uniswap v2
| Contract | Address |
| :-------- | :-------------------------------------------------------------------------------------------------------------------- |
| `Factory` | [0x8909Dc15e40173Ff4699343b6eB8132c65e18eC6](https://basescan.org/address/0x8909Dc15e40173Ff4699343b6eB8132c65e18eC6) |
| `Router` | [0x4752ba5dbc23f44d87826276bf6fd6b1c372ad24](https://basescan.org/address/0x4752ba5dbc23f44d87826276bf6fd6b1c372ad24) |
## Base Sepolia
### Multicall3
| Contract | Address |
| :--------- | :---------------------------------------------------------------------------------------------------------------------------- |
| Multicall3 | [0xcA11bde05977b3631167028862bE2a173976CA11](https://sepolia.basescan.org/address/0xcA11bde05977b3631167028862bE2a173976CA11) |
### Uniswap v3
| Contract | Address |
| :----------------------------------- | :---------------------------------------------------------------------------------------------------------------------------- |
| `Permit2` | [0x000000000022d473030f116ddee9f6b43ac78ba3](https://sepolia.basescan.org/address/0x000000000022d473030f116ddee9f6b43ac78ba3) |
| `universal router` | [0x050E797f3625EC8785265e1d9BDd4799b97528A1](https://sepolia.basescan.org/address/0x050E797f3625EC8785265e1d9BDd4799b97528A1) |
| `v3CoreFactory` | [0x4752ba5DBc23f44D87826276BF6Fd6b1C372aD24](https://sepolia.basescan.org/address/0x4752ba5DBc23f44D87826276BF6Fd6b1C372aD24) |
| `multicall` | [0xd867e273eAbD6c853fCd0Ca0bFB6a3aE6491d2C1](https://sepolia.basescan.org/address/0xd867e273eAbD6c853fCd0Ca0bFB6a3aE6491d2C1) |
| `proxyAdmin` | [0xD7303474Baca835743B54D73799688990f24a79D](https://sepolia.basescan.org/address/0xD7303474Baca835743B54D73799688990f24a79D) |
| `tickLens` | [0xedf6066a2b290C185783862C7F4776A2C8077AD1](https://sepolia.basescan.org/address/0xedf6066a2b290C185783862C7F4776A2C8077AD1) |
| `nftDescriptor` | [0x4e0caFF1Df1cCd7CF782FDdeD77f020699B57f1a](https://sepolia.basescan.org/address/0x4e0caFF1Df1cCd7CF782FDdeD77f020699B57f1a) |
| `nonfungibleTokenPositionDescriptor` | [0xd7c6e867591608D32Fe476d0DbDc95d0cf584c8F](https://sepolia.basescan.org/address/0xd7c6e867591608D32Fe476d0DbDc95d0cf584c8F) |
| `nonfungibleTokenPositionManager` | [0x27F971cb582BF9E50F397e4d29a5C7A34f11faA2](https://sepolia.basescan.org/address/0x27F971cb582BF9E50F397e4d29a5C7A34f11faA2) |
| `v3Migrator` | [0xCbf8b7f80800bd4888Fbc7bf1713B80FE4E23E10](https://sepolia.basescan.org/address/0xCbf8b7f80800bd4888Fbc7bf1713B80FE4E23E10) |
| `v3Staker` | [0x62725F55f50bdE240aCa3e740D47298CAc8d57D5](https://sepolia.basescan.org/address/0x62725F55f50bdE240aCa3e740D47298CAc8d57D5) |
| `quoterV2` | [0xC5290058841028F1614F3A6F0F5816cAd0df5E27](https://sepolia.basescan.org/address/0xC5290058841028F1614F3A6F0F5816cAd0df5E27) |
| `swapRouter` | [0x94cC0AaC535CCDB3C01d6787D6413C739ae12bc4](https://sepolia.basescan.org/address/0x94cC0AaC535CCDB3C01d6787D6413C739ae12bc4) |
#### Testnet interfaces
### Uniswap v2
| Contract | Address |
| :-------- | :---------------------------------------------------------------------------------------------------------------------------- |
| `Factory` | [0x7Ae58f10f7849cA6F5fB71b7f45CB416c9204b1e](https://sepolia.basescan.org/address/0x7Ae58f10f7849cA6F5fB71b7f45CB416c9204b1e) |
| `Router` | [0x1689E7B1F10000AE47eBfE339a4f69dECd19F602](https://sepolia.basescan.org/address/0x1689E7B1F10000AE47eBfE339a4f69dECd19F602) |
---
# Network Incident History
Source: https://basehub.org/network/incident-history/
Description: Paraphrased log of Base mainnet and Sepolia incidents and scheduled network events.
A running log of substantive incidents and scheduled upgrades affecting Base Mainnet and Base Sepolia. Procedural status pings are omitted. Entries are newest first.
## 2026
### 2026-10-21 — Sepolia Denim upgrade (scheduled)
Base Sepolia is set to activate the Denim hardfork on Wednesday, October 21st at 18:00 UTC (Unix timestamp `1792605600`), inside a maintenance window that runs until 20:00 UTC. The notice went up on October 19 at 13:52 UTC, and the testnet is expected to keep running through the upgrade. Sepolia node operators need [`v1.5.0`](https://github.com/base/base/releases/tag/v1.5.0) of `github.com/base/base` or a later release. The notice also calls out a startup trap: `v1.5.0` no longer knows `--enable-experimental-validity-transactions`, so a `base-reth-node` launched with that flag will not start until the flag is removed (the builder twin, `--builder.enable-experimental-validity-transactions`, is gone too). See the [Denim overview](/specifications/denim-overview/) for what the fork changes.
### 2026-10-09 — Mainnet output proposals stalled (resolved)
The status page opened an incident at 13:48 UTC on Friday, October 9th: new output proposals for Base Mainnet had stopped, which holds up withdrawals already in flight. Proposals were flowing again by 14:21 UTC, and the incident closed at 19:15 UTC. Block production and deposits were not part of it.
The onchain record shows a much longer gap than the status timeline suggests. On the Mainnet `DisputeGameFactoryProxy` (`0x43edB88C4B80fDD2AdFF2412A7BebF9dF42cB40e`), game `23770` was created on October 8 at 14:46 UTC, and the next one, game `23771`, not until October 9 at 14:08 UTC. Before that, a new game (type `621`) landed about every 20 minutes. So no proposals went up for roughly 23 hours, most of it before the incident was posted. After the restart the proposer moved slowly at first, then filed a burst of more than 80 games between about 18:28 and 19:37 UTC to catch up, and returned to its usual 20-minute pace.
A withdrawal can only be proven against a proposal that covers its L2 block. Withdrawals started during the gap therefore waited up to about a day longer than usual before the proof step was possible. Once proven, the normal [finalization delay](/network/bridging-and-withdrawals/#standard-withdrawals) still applies on top.
### 2026-10-08 — mainnet.base.org loses debug, trace, and txpool (completed)
From Thursday, October 8th at 12:00 UTC, the free public endpoint `https://mainnet.base.org` stops answering the `debug`, `trace`, and `txpool` namespaces. Reads that remain get a tighter rate limit. The endpoint stays free and best-effort for basic reads. The notice went up on October 1 and gives a window that ends October 9 at 12:00 UTC. Any app that calls those namespaces on the public host, or needs more throughput than the new limit allows, must move to a dedicated [node provider](/node-operations/node-providers/).
The status page closed the work on October 8 at 19:42 UTC, well inside the window. A probe of the public host on October 9 confirmed the cut: `txpool_status` came back as an unsupported method (`-32604`), a `debug_` call was refused by the request filter (`-32611`), and `eth_blockNumber` still answered normally.
### 2026-10-05 — V1 node snapshots retired (completed)
From Monday, October 5th at 12:00 UTC, Base stopped publishing V1 node database snapshots and stopped serving the ones already out there. The notice went up on September 29 with a 24-hour window ending October 6 at 12:00 UTC. The status page marked the work complete on October 6 at 14:00 UTC, two hours past that window. Operators who still restore from V1 need to move to the V2 snapshots at chain.base.org/snapshots; see [Snapshots](/node-operations/snapshots/) for the restore steps.
### 2026-09-30 — Mainnet Cobalt upgrade (completed)
The window opened on schedule at 18:00 UTC and closed as complete at 20:00 UTC. No incident was raised against it.
Base Mainnet was scheduled to activate the Cobalt hardfork on Wednesday, September 30th at 18:00 UTC (Unix timestamp `1790791200`), with a maintenance window running until 20:00 UTC. The notice went up on September 23 at 23:00 UTC, a few hours after the Sepolia window closed. Mainnet operators must run [`v1.4.2`](https://github.com/base/base/releases/tag/v1.4.2) of `github.com/base/base` or a later release. That is a higher floor than the compiled-in timestamp alone implies: `v1.4.1` already carries the Mainnet value, but `v1.4.2` adds a backport (#5260) that registers the validity transaction RPC ahead of Cobalt and switches it on from the live upgrade schedule. Details are in the [Cobalt Upgrade Overview](/specifications/cobalt-overview/#required-software).
### 2026-09-23 — Sepolia Cobalt upgrade (completed)
The maintenance window opened on time at 18:00 UTC and was marked complete at 20:00 UTC, with no incident reported against it.
Base Sepolia is scheduled to activate the Cobalt hardfork on Wednesday, September 23rd at 18:00 UTC (Unix timestamp `1790186400`), with a maintenance window held open until 20:00 UTC. Operators of Sepolia nodes must be running the [`v1.4.0`](https://github.com/base/base/releases/tag/v1.4.0) release of `github.com/base/base` or later; earlier builds have no Cobalt timestamp compiled in and will not follow the fork. That floor applies to Sepolia only. The Mainnet activation timestamp was not added to the source until 2026-09-21, after `v1.4.0` was tagged, so Mainnet operators need a later build for their own September 30 window. The notice also restates where node software now comes from: `github.com/base/base` publishes the public node that used to ship from `base/node`. Scope and migration notes are in the [Cobalt Upgrade Overview](/specifications/cobalt-overview/#required-software).
### 2026-07-28 — Mainnet safe head fell behind
At 13:10 UTC on Tuesday, July 28th, the safe head on Base Mainnet was reported as lagging. Unsafe block production was unaffected — the delay was confined to the batching of L2 data down to Ethereum L1, so chain progress at the tip continued as normal. The safe head was advancing again by 15:13 UTC, when the incident was closed.
### 2026-07-21 — Mainnet Flashblocks websocket capacity reduced
On Tuesday, July 21st, the Flashblocks websocket stream on Base Mainnet ran at reduced capacity for roughly fifty minutes, spanning 19:50 to 20:42 UTC. Subscribers were likely to see messages arrive late over that window, and fresh connection attempts could come back rate limited. The event was marked resolved once stream capacity recovered.
### 2026-06-25 — Mainnet chain stall
Beginning at 16:03 UTC on Thursday, June 25th, Base Mainnet block production turned unhealthy. The team traced it to a consensus fault: an invalid block had been sequenced, which kept new blocks from being built past block `47806542`. Sequencing of fresh blocks was restored by around 17:51 UTC, though ecosystem node operators had to restart their Base nodes to resume syncing. Healthy block building was confirmed shortly after, and the Beryl hardfork still activated on schedule at 18:00 UTC. By 19:22 UTC the network was stable with recovery verified across the ecosystem; any nodes still stuck at block `47806542` recover on restart. The root cause was identified and a fix put under verification, with a full post-mortem and root-cause analysis promised to the ecosystem.
### 2026-06-25 — Mainnet Beryl upgrade (scheduled)
Base Mainnet is scheduled to activate the Beryl hardfork on Thursday, June 25th at 18:00 UTC (Unix timestamp `1782410400`). Operators of Mainnet nodes must move to the `1.1.1` release or later of `github.com/base/base`, with matching preconfigured binaries published as the [`v1.1.1`](https://github.com/base/node/releases/tag/v1.1.1) release of `github.com/base/node`. Migration steps are documented in the [Beryl Upgrade Overview](/specifications/beryl-overview#required-software).
### 2026-06-18 — Sepolia Beryl upgrade (scheduled)
Base Sepolia is scheduled to activate the Beryl hardfork on Thursday, June 18th at 18:00 UTC (`1781805600`). Operators of Sepolia nodes need to move to the `v1.1.0` release or later of `github.com/base/base`, with matching preconfigured builds shipped as the `v1.1.0` release of `github.com/base/node`. The migration details live in the [Beryl Upgrade Overview](/specifications/beryl-overview).
### 2026-06-12 — Mainnet p2p peering instability
On Friday, June 12th at 21:28 UTC, the team began investigating peering problems on Base Mainnet where newly started nodes were having trouble finding peers. As a temporary measure, affected operators were pointed at a short list of `--trusted-peers` enode entries to add to their Reth node and restart while a fix was developed.
### 2026-06-02 — Mainnet Flashblocks broadcasting degraded
On Tuesday, June 2nd at 22:32 UTC, the team began investigating periodic instability in Flashblocks broadcasting on Base Mainnet. Pre-confirmation delivery was affected, but transaction inclusion in sealed blocks was reported as unaffected throughout.
### 2026-05-29 — Mainnet withdrawal delay (TEE enclave)
On Friday, May 29th at 15:55 UTC, Base Mainnet withdrawals began running late after a TEE enclave fault stopped output proposals from being posted. The issue was identified and a fix was reported in progress; withdrawals resume once proposals catch back up.
### 2026-05-28 — Mainnet Azul upgrade (scheduled)
Base Mainnet activates the Azul hardfork on Thursday, May 28th at 18:00 UTC. Node operators must run version `0.9.0` or later of `github.com/base/base`, with corresponding preconfigured binaries published as the `v0.16.0` release of `github.com/base/node`. From this upgrade onward, `base-consensus` and `base-reth-node` are the only supported clients — `op-node` and `op-geth` will not follow the new chain. Pending withdrawals will be invalidated by the upgrade; users with in-flight withdrawals will need to submit a second proof transaction afterward to complete them. Migration steps are documented in [Base v1 upgrade](/node-operations/base-v1-upgrade).
---
# Network Faucets
Source: https://basehub.org/network/network-faucets/
Description: Testnet ETH faucets for Base Sepolia from Coinbase Developer Platform, Alchemy, QuickNode, Chainstack, and other providers.
import { Aside } from '@astrojs/starlight/components';
Multiple providers dispense free Base Sepolia testnet ETH (and a few support mainnet drips for contract deployment). Supported assets, claim limits, and authentication requirements vary by provider.
## Coinbase Developer Platform
The [Coinbase Developer Platform Faucet](https://portal.cdp.coinbase.com/products/faucet) hands out up to 0.1 testnet ETH per 24 hours on Base Sepolia, and also drips USDC, EURC, and cbBTC.
## thirdweb
The [thirdweb Faucet](https://thirdweb.com/base-sepolia-testnet) provides free Base Sepolia ETH with a single claim per 24 hours.
## Alchemy
The [Alchemy Faucet](https://basefaucet.com/) requires a free Alchemy account and dispenses Base Sepolia testnet ETH.
## Bware Labs
The [Bware Labs Faucet](https://bwarelabs.com/faucets) requires no registration and dispenses Base Sepolia ETH.
## Chainstack
The [Chainstack Faucet](https://faucet.chainstack.com/) drips Base ETH against your Chainstack platform API key.
## ethfaucet.com
[ethfaucet.com](https://ethfaucet.com/networks/base) provides free Base Sepolia testnet ETH and small mainnet drips for contract deployment. The faucet is operated by [BringID](https://www.bringid.org/).
## QuickNode
The [QuickNode Faucet](https://faucet.quicknode.com/drip) is a multi-chain faucet that dispenses Base Sepolia testnet ETH.
## LearnWeb3
The [LearnWeb3 Faucet](https://learnweb3.io/faucets/base_sepolia) is a multi-chain faucet that dispenses Base Sepolia testnet ETH.
## Ethereum Ecosystem
The [Base Sepolia Faucet](https://www.ethereum-ecosystem.com/faucets/base-sepolia) is operated by [Ethereum Ecosystem](https://www.ethereum-ecosystem.com) and requires no login.
---
# Network Fees
Source: https://basehub.org/network/network-fees/
Description: How Base fees are split between L2 execution and L1 data, plus the minimum base fee, EIP-1559 parameters, and the GasPriceOracle.
Every Base transaction pays an L2 execution fee plus an L1 security fee — the cost of posting transaction data back to Ethereum. The L1 component is typically the larger of the two.
## How fees work
The L1 fee fluctuates with Ethereum gas conditions. If your transaction timing is flexible, submitting during quieter L1 windows (such as weekends) can reduce overall cost.
The L2 fee responds to demand on Base itself, using the same EIP-1559 mechanism Ethereum uses. For background, see Coinbase's [EIP-1559 explainer](https://help.coinbase.com/en/coinbase/getting-started/crypto-education/eip-1559).
For lower-level details on fee composition, refer to the [OP Stack fee documentation](https://docs.optimism.io/stack/transactions/fees).
## Minimum base fee
The [Jovian upgrade](https://docs.optimism.io/notices/upgrade-17) introduced a minimum base fee — a floor that prevents the L2 base fee from collapsing during quiet periods.
Base Mainnet's minimum base fee is currently 5,000,000 wei (0.005 gwei). The value may be adjusted over time as data accumulates. As a reference point, a 0.005 gwei base fee costs about $0.002 for a 200,000-gas transaction at an ETH price of $2,000.
### Benefits
- **Faster inclusion.** Without a floor, low-activity periods drove the base fee toward zero, and demand spikes could then take a long time to clear the resulting backlog. With a floor, transactions clear faster and most users do not need to manually bump priority fees.
- **More predictable fees.** Base fees sit at or near the minimum during normal operation and rise above it during congestion — a surge-pricing pattern.
- **Spam mitigation.** Very low fees make spam transactions cheap. The floor prices out that activity while keeping legitimate use affordable.
### Current configuration
| Network | Minimum base fee |
|--------------|------------------|
| Base Mainnet | 5,000,000 wei (0.005 gwei) |
| Base Sepolia | 5,000,000 wei (0.005 gwei) |
The [configuration changelog](/network/configuration-changelog/) tracks every change to the minimum base fee and other parameters.
## EIP-1559 fee parameters
Base uses the OP Stack implementation of EIP-1559 to adjust the L2 base fee in response to demand. Two parameters drive the dynamics.
### Elasticity multiplier
The **elasticity multiplier** sets the maximum block gas relative to the target. With elasticity 6, a block can hold up to 6× the target gas, absorbing short demand spikes.
### Base fee change denominator
The **base fee change denominator** controls how aggressively the base fee moves between blocks. Larger denominators yield smoother changes; with a denominator of 125, the fee adjusts more gradually than under lower values.
### Maximum rate of change
Per-block change is capped at:
**Max increase per block = (Elasticity − 1) / Denominator**
With the current parameters (Elasticity = 6, Denominator = 125):
- Maximum increase per block: (6 − 1) / 125 = **4%**
- Minimum time to double the base fee: 18 blocks × 2 seconds = **36 seconds**
The smoothed adjustment limits fee volatility during traffic spikes while still letting the network track sustained demand.
### Current configuration
| Network | Elasticity | Denominator | Max change per block |
|--------------|------------|-------------|----------------------|
| Base Mainnet | 6 | 125 | 4% |
| Base Sepolia | 6 | 125 | 4% |
## Querying the L1 fee
The **GasPriceOracle** predeploy at `0x420000000000000000000000000000000000000F` (see [Contract Addresses](/network/base-contracts/)) lets callers estimate the L1 component before signing.
| Method | Returns |
| ------ | ------- |
| `getL1Fee(bytes)` | Exact L1 fee for a fully serialized (RLP-encoded) transaction |
| `getL1FeeUpperBound(uint256 txSize)` | Upper-bound L1 fee estimated from approximate transaction byte length |
| `l1BaseFee()` | Current Ethereum L1 base fee as observed by Base |
| `blobBaseFee()` | Current EIP-4844 blob base fee |
| `baseFeeScalar()` | Scalar applied to the L1 base fee component |
| `blobBaseFeeScalar()` | Scalar applied to the blob base fee component |
Use `getL1FeeUpperBound` for a quick estimate before the transaction is fully built. Use `getL1Fee` with the complete serialized transaction for an exact pre-sign value.
---
# Throughput and Limits
Source: https://basehub.org/network/throughput-and-limits/
Description: Gas limits, Flashblock performance figures, fee parameters, data availability throttling, and endpoint limits that shape practical throughput on Base.
import { Aside } from '@astrojs/starlight/components';
Several things bound throughput on Base simultaneously: how much gas a block allows, how much data the chain can publish for availability, the parameters of the fee market, and the limits imposed at the RPC endpoint. No single transactions-per-second number describes every workload, since transactions differ widely in the gas and data they each consume.
Base has sustained several bursts above 5,000 TPS, and capacity keeps growing as the chain scales. The [Introducing Base Azul](https://blog.base.dev/introducing-base-azul) post has more background.
## Current limits
| Limit | Value |
|-------|-------|
| Full block gas budget | ~400M gas |
| First Flashblock gas budget | ~40M gas |
| Per-transaction gas maximum | 16,777,216 gas (2^24) |
| Deposit transaction limit | Maximum gas includable in an L1 block (20,000,000 gas) |
While a block is being assembled, the full gas budget is divided across its Flashblocks: Flashblock 1 can use one tenth of the limit, Flashblock 2 two tenths, and so on up to Flashblock 10, which has the full budget. See [Block Building](/network/block-building/#flashblocks) for how this shapes transaction ordering.
## Flashblock performance
Flashblocks emit incremental block updates roughly every 200ms, so apps receive sub-second preconfirmations inside the standard 2-second block.
| Metric | Value |
|--------|-------|
| Flashblock build time (P50) | ~10ms |
| Preconfirmation latency | ~200ms |
| Full block time | 2 seconds |
| Flashblocks per block | 10 |
| Reorg rate | < 0.1% |
For how reorgs are handled — and other recurring questions — see the [Flashblocks FAQ](/flashblocks/faq/).
## Per-transaction gas maximum
Since the [Azul hardfork](/specifications/azul-overview/), any single transaction is held to a protocol-level ceiling of **16,777,216 gas (2^24)**, as set out in [EIP-7825](https://eips.ethereum.org/EIPS/eip-7825). A transaction that declares a gas limit above this value is **rejected during block validation**, and `eth_sendTransaction` or `eth_sendRawTransaction` returns a JSON-RPC error such as `exceeds maximum per-transaction gas limit`.
Operators running bundlers for smart contract wallets need to size each bundle to stay under this cap.
## Fee parameters
Fees feed back into real-world throughput: as load climbs toward the ceiling, the fee a transaction offers governs whether it makes it into a block.
| Parameter | Current value |
|-----------|---------------|
| Minimum base fee | 5,000,000 wei (0.005 gwei) |
| EIP-1559 elasticity | 6 |
| EIP-1559 denominator | 125 |
| Maximum L2 base fee change per block | 4% |
For how Base fees are structured — the L2 execution fee and the L1 security fee — see [Network Fees](/network/network-fees/).
## Data availability throughput
Base posts its transaction data to Ethereum for data availability. When DA bandwidth is constrained, the sequencer can throttle L2 throughput while the batcher catches up.
While DA throttling is active, even transactions paying a high priority fee may be delayed, and no RPC endpoint estimates priority fees with throttling in mind. The [troubleshooting guide](/network/troubleshooting-transactions/) covers what this means for transaction submission.
## Endpoint limits
Public endpoints carry rate limits and are not built for production traffic. A hosted RPC provider may layer on further constraints — caps on requests per second or compute units, restricted method sets, limits on archive data, or ceilings on WebSocket subscriptions.
None of that alters the protocol's own capacity, but any of it can turn into the practical ceiling for an app, wallet, indexer, or monitoring system. For production traffic, route through a node provider or [run your own Base node](/getting-started/running/).
---
# Transaction Finality
Source: https://basehub.org/network/transaction-finality/
Description: The four finality stages for Base L2 transactions and the withdrawal finalization window (5 days, or 1 day with two proofs) that applies only to withdrawals back to Ethereum.
import { Aside } from '@astrojs/starlight/components';
Finality is the point at which a Base transaction becomes irreversible. The behavior differs for transactions that update L2 state versus transactions that withdraw funds from Base L2 to Ethereum L1.
## Finality for Base L2 transactions
This section covers every Base transaction except withdrawals back to Ethereum.
Finality is layered: each successive stage strengthens the security guarantee.
### Flashblock inclusion: ~200ms
After about 200 milliseconds, the Base sequencer includes the transaction in a preconfirmation block (a Flashblock).
Reorg probability is below 0.001%. Flashblocks reorg less than 0.001% of the time; the [public stats page](https://base.org/stats) records the reorg history.
### L2 block inclusion: ~2s
After roughly 2 seconds, the sequencer has packaged the transaction into a sealed L2 block and propagated it to validator nodes.
Reorg probability is effectively 0%. Only one Base L2 block has ever reorged, accounting for 0.0000003% of transactions. The data is visible on [Blockscout](https://base.blockscout.com/blocks?tab=reorgs).
### L1 batch inclusion: ~2m
After about 2 minutes, a Base batch containing the transaction has been posted to Ethereum.
Reorg probability is effectively 0%. No L2 blocks that have been batched to Ethereum L1 have ever reorged. **An Ethereum L1 reorg does not force a Base L2 reorg.** The sequencer and validator nodes maintain a configurable lag from the L1 tip, so typical L1 reorgs have no impact. If a deeper L1 reorg occurs, Base can resubmit batch data without altering the sequenced L2 blocks.
### L1 batch finality: ~20m
The Ethereum batch carrying the transaction is older than 2 epochs (64 L1 blocks).
Reorg probability is effectively 0%. L2 blocks past L1 batch finality enjoy the same protection as Ethereum-finalized blocks and are practically impossible to reverse.
## Finality for withdrawals
**A withdrawal from Base to Ethereum is released to the L1 recipient only after its finalization window closes.** That window is what lets Base's proof system give bridged funds strong security guarantees.
Since [Beryl](/specifications/beryl-overview/) activated, the window is **5 days** for a dispute game backed by a single proof. When a TEE proof and a ZK proof both support the same proposal, the dual-proof fast path cuts it to **1 day**. The window dominates the end-to-end time: the wait for the relevant Base state to be proposed on Ethereum typically adds only 20 to 60 minutes, plus however long the prove and finalize transactions take. Third-party bridges that pay out sooner do it with their own liquidity; they leave this window untouched.
### What happens during the finalization window
The funds leave the Base account as soon as the withdrawal is initiated. A proposer then posts a checkpoint claim on Ethereum through an `AggregateVerifier` game, backed by a TEE or ZK proof. An independent challenger can contest an invalid claim by supplying a ZK proof. The window exists so that others have time to check the claim, and it is shorter when TEE and ZK proofs agree. The [Azul proof system](/specifications/azul-proofs/) page walks through the full flow.
If a claim turns out to be invalid, withdrawals proven against it cannot finalize and have to be proven again against a valid claim. Contesting a claim never reorgs the Base chain.
## FAQ
**If Ethereum reorgs, will Base reorg?**
Almost never. Base resubmits batch data to Ethereum transparently while the L2 chain continues forward.
**How long do deposit transactions take to finalize?**
Deposits are initiated on Ethereum and are typically picked up by the Base sequencer within 3 minutes.
**If a challenger wins a dispute game, will the L2 chain reorg?**
No. The challenged output proposal is marked invalid, and any actions that depended on its output root must use a valid replacement. In practice, withdrawals proven against the invalid proposal must be re-proven against a different one.
---
# Troubleshooting Transactions
Source: https://basehub.org/network/troubleshooting-transactions/
Description: Diagnose pending, rejected, failed, or slow Base transactions, with fixes for fee, nonce, gas, and Flashblocks issues.
import { Aside } from '@astrojs/starlight/components';
This guide walks through the common reasons Base transactions stall, fail, or revert, and explains how to fix each one.
## Pending transactions
If a transaction is sitting in the mempool longer than expected, work through the following.
### `maxFeePerGas` too low
If your `maxFeePerGas` is below the current base fee, the transaction stays pending until the base fee drops below your value.
**Fix:** `maxFeePerGas` must cover both the base fee and the priority fee. Because the base fee can move between blocks, set `maxFeePerGas` high enough to remain valid even if the base fee climbs while the transaction is queued. A common formula:
```
maxFeePerGas = baseFee * 2 + maxPriorityFeePerGas
```
This pattern (used by [ethers.js](https://github.com/ethers-io/ethers.js/blob/98c49d091eb84a9146dfba8476f18e4c3e3d1d31/src.ts/providers/abstract-provider.ts#L945-L950)) provides headroom for the base fee to double before the transaction becomes uneconomical. You only pay the actual base fee at inclusion, not the maximum.
### Priority fee too low
When the network is busy, transactions compete for inclusion via priority fees. Submitting a low priority fee against active demand delays inclusion.
**Fix:** Most users wait for congestion to ease. For time-sensitive transactions, query `eth_maxPriorityFeePerGas` for an estimate that should outbid recent transactions.
### Nonce gap
A pending transaction at nonce N blocks every transaction at nonce N+1 or higher, regardless of fees.
**Fix:** Wait for the pending transaction, or replace it by submitting a new transaction with the same nonce and a fee bump of at least 10% on both `maxPriorityFeePerGas` and `maxFeePerGas`.
### Nonce too low
Submitting a transaction with a nonce that has already been used results in a rejection.
**Fix:** Query the next available nonce with `eth_getTransactionCount` and the `pending` tag.
## Rejected transactions
### Gas limit exceeds the maximum
Base enforces a [per-transaction gas maximum](/network/block-building/#per-transaction-gas-maximum) of **16,777,216 gas (2^24)**. Any transaction declaring a higher limit is rejected during block validation.
**Error:** `exceeds maximum per-transaction gas limit`
**Fix:** Reduce the gas limit to 16,777,216 (2^24) or lower. If the transaction genuinely needs more gas, split it into multiple transactions.
## Included but failed transactions
### Out of gas
The transaction exhausted its gas during execution.
**Fix:** Increase the gas limit. Estimate with `eth_estimateGas` and add a safety margin (for example, 20%) to absorb variability.
### Reverted by contract
Contract logic triggered a revert.
**Fix:** Inspect the transaction on [Basescan](https://basescan.org) to find the revert reason. Common causes include failed `require` checks, arithmetic errors, and invalid state transitions.
## Slow confirmations
### Confirmation tiers
Base produces an L2 block every 2 seconds, while [Flashblocks](/flashblocks/app-integration/) emit preconfirmations every 200ms.
| Confirmation level | Time | Description |
|--------------------|------|-------------|
| Flashblock preconfirmation | ~200ms | Transaction included in a preconfirmation |
| L2 block inclusion | ~2s | Transaction included in a sealed L2 block |
| L1 batch inclusion | ~2m | Transaction posted to Ethereum |
| L1 finality | ~20m | Ethereum batch is finalized |
See [Transaction Finality](/network/transaction-finality/) for the full breakdown.
### Use a Flashblocks-aware endpoint
For the fastest possible confirmation, point your client at the Flashblocks RPC endpoint:
| Network | Flashblocks RPC |
|---------|-----------------|
| Mainnet | `https://mainnet.base.org` |
| Sepolia | `https://sepolia.base.org` |
These endpoints return receipts as soon as the transaction lands in a Flashblock instead of waiting for the full L2 block.
## Debugging tools
- **[Basescan](https://basescan.org)** — Inspect status, logs, and revert reasons
- **[Tenderly](https://tenderly.co)** — Simulate and debug transactions
- **`eth_call`** — Test contract calls without submitting a transaction
- **`eth_estimateGas`** — Estimate gas usage before submitting
## Getting help
If you are still stuck, ask in the `#developer-chat` channel on the [Base Discord](https://base.org/discord).
---
# Azul Node Upgrade Guide
Source: https://basehub.org/node-operations/azul-node-upgrade/
Description: Migrate a Base node to base-reth-node and base-consensus for the Azul hardfork, including the op-node to base-consensus environment variable mapping.
import { Aside } from '@astrojs/starlight/components';
Azul is only supported by `base-reth-node` (execution) and `base-consensus` (consensus). **Nodes still running `op-node`, `op-geth`, `op-reth`, `nethermind`, or `kona` cannot follow the upgrade and have to be migrated.**
Azul went live on mainnet at **May 28, 2026 18:00 UTC** (`1779991200`). The [Azul overview](/specifications/azul-overview/) carries the full activation-timestamp table.
## Required software
| Layer | Software | Mainnet | Testnet |
|-------|----------|---------|---------|
| Execution (EL) | `base-reth-node` | [v0.9.0+](https://github.com/base/base/releases/tag/v0.9.0) | [v0.7.0+](https://github.com/base/base/releases/tag/v0.7.0) |
| Consensus (CL) | `base-consensus` | [v0.9.0+](https://github.com/base/base/releases/tag/v0.9.0) | [v0.7.0+](https://github.com/base/base/releases/tag/v0.7.0) |
## Migrating the execution layer
### Coming from OP Reth
Operators already on OP Reth through the compose setup only need to update — the latest version switches the binary to `base-reth-node` automatically, and your current `./reth-data` directory carries over with no re-sync or snapshot restore required.
1. Stop your node:
```bash
docker compose down
```
2. Move to [base/base](https://github.com/base/base), which now publishes the operator node, and update it:
```bash
# Coming from a base/node clone? Clone base/base next to it and bring your env file across:
git clone https://github.com/base/base.git
cp ../node/.env.mainnet ./base/.env.mainnet # or .env.sepolia
# Already tracking base/base:
git pull origin main
```
3. Start your node:
```bash
docker compose up
```
4. Confirm the client version: `web3_clientVersion` should now carry `base` in the string (for example `reth/v1.11.3-.../base/v0.9.0`).
### Coming from another client
`op-geth` and `nethermind` are no longer supported, so you will have to start over on `base-reth-node`.
1. Stop your node:
```bash
docker compose down
```
2. Clone [base/base](https://github.com/base/base), or update an existing clone:
```bash
git clone https://github.com/base/base.git
# or, where it is already cloned:
git pull origin main
```
3. Delete the old data directory (for example `./geth-data` or `./nethermind-data`).
4. Adjust `.env.mainnet` or `.env.sepolia` to your preferences.
5. Bootstrap from a [Reth snapshot](/node-operations/snapshots/) so you can skip a full sync.
6. Start your node:
```bash
docker compose up
```
## Migrating the consensus layer
Swap `op-node` for `base-consensus` by updating environment variables.
1. Set `USE_BASE_CONSENSUS=true` in your `.env` file.
2. Add the new `BASE_NODE_*` environment variables (mapping below).
3. Restart your node:
```bash
docker compose up
```
4. Verify:
- Tail the consensus logs: `docker compose logs -f node`
- Confirm sync status: `optimism_syncStatus` still responds
### Environment variable mapping
The `.env.mainnet` and `.env.sepolia` templates in [base/base](https://github.com/base/base) already populate most of these. If you build from [base/base](https://github.com/base/base), translate your `op-node` variables with the table below. Nearly all of them are optional. `base-consensus node --help` prints the complete set.
| `op-node` | `base-consensus` |
|-----------|-------------------|
| `OP_NODE_NETWORK` | `BASE_NODE_NETWORK` |
| `OP_NODE_ROLLUP_CONFIG` | `BASE_NODE_ROLLUP_CONFIG` |
| — | `BASE_NODE_LOG_VERBOSITY` |
| — | `BASE_NODE_LOG_FORMAT` |
| `OP_NODE_L1_ETH_RPC` | `BASE_NODE_L1_ETH_RPC` |
| `OP_NODE_L1_BEACON` | `BASE_NODE_L1_BEACON` |
| `OP_NODE_L1_TRUST_RPC` | `BASE_NODE_L1_TRUST_RPC` |
| `OP_NODE_L2_ENGINE_RPC` | `BASE_NODE_L2_ENGINE_RPC` |
| `OP_NODE_L2_ENGINE_AUTH` | `BASE_NODE_L2_ENGINE_AUTH` |
| — | `BASE_NODE_L2_ENGINE_AUTH_ENCODED` |
| `OP_NODE_P2P_BOOTNODES` | `BASE_NODE_P2P_BOOTNODES` |
| `OP_NODE_P2P_LISTEN_IP` | `BASE_NODE_P2P_LISTEN_IP` |
| `OP_NODE_P2P_LISTEN_TCP_PORT` | `BASE_NODE_P2P_LISTEN_TCP_PORT` |
| `OP_NODE_P2P_LISTEN_UDP_PORT` | `BASE_NODE_P2P_LISTEN_UDP_PORT` |
| `OP_NODE_P2P_ADVERTISE_IP` | `BASE_NODE_P2P_ADVERTISE_IP` |
| `OP_NODE_P2P_ADVERTISE_TCP` | `BASE_NODE_P2P_ADVERTISE_TCP_PORT` |
| `OP_NODE_P2P_ADVERTISE_UDP` | `BASE_NODE_P2P_ADVERTISE_UDP_PORT` |
| `OP_NODE_P2P_PRIV_PATH` | `BASE_NODE_P2P_PRIV_PATH` |
| `OP_NODE_P2P_PEER_SCORING` | `BASE_NODE_P2P_SCORING` |
| `OP_NODE_P2P_PEER_BANNING` | `BASE_NODE_P2P_BAN_PEERS` |
| `OP_NODE_P2P_PEER_BANNING_THRESHOLD` | `BASE_NODE_P2P_BAN_THRESHOLD` |
| `OP_NODE_P2P_PEER_BANNING_DURATION` | `BASE_NODE_P2P_BAN_DURATION` |
| `OP_NODE_METRICS_ENABLED` | `BASE_NODE_METRICS_ENABLED` |
| `OP_NODE_METRICS_ADDR` | `BASE_NODE_METRICS_ADDR` |
| `OP_NODE_METRICS_PORT` | `BASE_NODE_METRICS_PORT` |
| `OP_NODE_RPC_ADDR` | `BASE_NODE_RPC_ADDR` |
| `OP_NODE_RPC_PORT` | `BASE_NODE_RPC_PORT` |
| `OP_NODE_RPC_ENABLE_ADMIN` | `BASE_NODE_RPC_ENABLE_ADMIN` |
| `OP_NODE_RPC_ADMIN_STATE` | `BASE_NODE_RPC_ADMIN_STATE` |
| `OP_NODE_SAFEDB_PATH` | `BASE_NODE_SAFEDB_PATH` |
| `OP_NODE_SYNCMODE` | — |
| `OP_NODE_VERIFIER_L1_CONFS` | — |
| `OP_NODE_L2_ENGINE_KIND` | — |
| `OP_NODE_L1_RPC_KIND` | — |
| `OP_NODE_L1_BEACON_FETCH_ALL_SIDECARS` | — |
| `OP_NODE_L1_BEACON_FALLBACKS` | — |
| `OP_NODE_ROLLUP_LOAD_PROTOCOL_VERSIONS` | — |
| `OP_NODE_P2P_STATIC` | — |
| `OP_NODE_P2P_DISABLE` | — |
| `OP_NODE_P2P_NAT` | — |
## FAQ
- **Do I have to re-sync?** No, not if you are already on OP Reth — the existing data directory is compatible.
- **What if I run `op-geth` or `nethermind`?** Move to `base-reth-node` and bootstrap from a [Reth snapshot](/node-operations/snapshots/).
- **Do the OP namespace RPCs still work?** Yes — every existing RPC remains supported.
---
# Base Azul Upgrade
Source: https://basehub.org/node-operations/base-v1-upgrade/
Description: Migrate Base nodes to base-reth-node and base-consensus ahead of the Azul network upgrade, with environment variable mappings and timelines.
import { Aside } from '@astrojs/starlight/components';
The Base Azul upgrade activates Osaka features on Base alongside the TEE/ZK proof systems and requires every node operator to migrate to Base-native clients.
The full scope is documented in the [Azul specification](https://specs.base.org/upgrades/azul/overview).
## Activation timeline
| Network | Date | Timestamp |
|---------|------|-----------|
| Mainnet | May 28, 2026 18:00 UTC | `1779991200` |
| Sepolia | April 20, 2026 18:00 UTC | `1776708000` |
## Required software
| Layer | Software | Mainnet | Testnet |
|-------|----------|---------|---------|
| Execution (EL) | `base-reth-node` | [v0.9.0+](https://github.com/base/base/releases/tag/v0.9.0) | [v0.7.0+](https://github.com/base/base/releases/tag/v0.7.0) |
| Consensus (CL) | `base-consensus` | [v0.9.0+](https://github.com/base/base/releases/tag/v0.9.0) | [v0.7.0+](https://github.com/base/base/releases/tag/v0.7.0) |
## Migrating the execution layer
### From OP Reth
If you already run OP Reth through the compose setup, updating to the latest release switches you to `base-reth-node` automatically. Your existing `./reth-data` directory is fully compatible — no resync or snapshot restore required.
1. Stop the node:
```bash
docker compose down
```
2. Pull the latest [base/base](https://github.com/base/base), which now publishes the operator node:
```bash
git pull origin main
```
3. Start the node:
```bash
docker compose up
```
4. Confirm the client version with `web3_clientVersion` — the response should include `base` (for example, `reth/v1.11.3-.../base/v0.9.0`).
### From other clients
`op-geth` and `nethermind` are no longer supported. You must restart from a clean `base-reth-node` setup.
1. Stop the node:
```bash
docker compose down
```
2. Pull the latest [base/base](https://github.com/base/base), which now publishes the operator node:
```bash
git pull origin main
```
3. Remove the existing client data directory (for example, `./geth-data` or `./nethermind-data`).
4. Edit `.env.mainnet` or `.env.sepolia` to match your preferences.
5. Bootstrap from a [Reth snapshot](/node-operations/snapshots/) to skip a full sync.
6. Start the node:
```bash
docker compose up
```
## Migrating the consensus layer
Replace `op-node` with `base-consensus` by updating your environment variables.
1. Set `USE_BASE_CONSENSUS=true` in your `.env` file.
2. Update `.env` with the new `BASE_NODE_*` variables (see the mapping below).
3. Restart:
```bash
docker compose up
```
4. Verify:
- Tail consensus logs: `docker compose logs -f node`
- Confirm sync status: `optimism_syncStatus` continues to work
### Environment variable mapping
The `.env.mainnet` and `.env.sepolia` templates in [base/base](https://github.com/base/base) already populate most variables. If you build from [base/base](https://github.com/base/base), translate `op-node` variables with the table below. Nearly all of them are optional. `base-consensus node --help` prints the complete set.
| `op-node` | `base-consensus` |
|-----------|-------------------|
| `OP_NODE_NETWORK` | `BASE_NODE_NETWORK` |
| `OP_NODE_ROLLUP_CONFIG` | `BASE_NODE_ROLLUP_CONFIG` |
| — | `BASE_NODE_LOG_VERBOSITY` |
| — | `BASE_NODE_LOG_FORMAT` |
| `OP_NODE_L1_ETH_RPC` | `BASE_NODE_L1_ETH_RPC` |
| `OP_NODE_L1_BEACON` | `BASE_NODE_L1_BEACON` |
| `OP_NODE_L1_TRUST_RPC` | `BASE_NODE_L1_TRUST_RPC` |
| `OP_NODE_L2_ENGINE_RPC` | `BASE_NODE_L2_ENGINE_RPC` |
| `OP_NODE_L2_ENGINE_AUTH` | `BASE_NODE_L2_ENGINE_AUTH` |
| — | `BASE_NODE_L2_ENGINE_AUTH_ENCODED` |
| `OP_NODE_P2P_BOOTNODES` | `BASE_NODE_P2P_BOOTNODES` |
| `OP_NODE_P2P_LISTEN_IP` | `BASE_NODE_P2P_LISTEN_IP` |
| `OP_NODE_P2P_LISTEN_TCP_PORT` | `BASE_NODE_P2P_LISTEN_TCP_PORT` |
| `OP_NODE_P2P_LISTEN_UDP_PORT` | `BASE_NODE_P2P_LISTEN_UDP_PORT` |
| `OP_NODE_P2P_ADVERTISE_IP` | `BASE_NODE_P2P_ADVERTISE_IP` |
| `OP_NODE_P2P_ADVERTISE_TCP` | `BASE_NODE_P2P_ADVERTISE_TCP_PORT` |
| `OP_NODE_P2P_ADVERTISE_UDP` | `BASE_NODE_P2P_ADVERTISE_UDP_PORT` |
| `OP_NODE_P2P_PRIV_PATH` | `BASE_NODE_P2P_PRIV_PATH` |
| `OP_NODE_P2P_PEER_SCORING` | `BASE_NODE_P2P_SCORING` |
| `OP_NODE_P2P_PEER_BANNING` | `BASE_NODE_P2P_BAN_PEERS` |
| `OP_NODE_P2P_PEER_BANNING_THRESHOLD` | `BASE_NODE_P2P_BAN_THRESHOLD` |
| `OP_NODE_P2P_PEER_BANNING_DURATION` | `BASE_NODE_P2P_BAN_DURATION` |
| `OP_NODE_METRICS_ENABLED` | `BASE_NODE_METRICS_ENABLED` |
| `OP_NODE_METRICS_ADDR` | `BASE_NODE_METRICS_ADDR` |
| `OP_NODE_METRICS_PORT` | `BASE_NODE_METRICS_PORT` |
| `OP_NODE_RPC_ADDR` | `BASE_NODE_RPC_ADDR` |
| `OP_NODE_RPC_PORT` | `BASE_NODE_RPC_PORT` |
| `OP_NODE_RPC_ENABLE_ADMIN` | `BASE_NODE_RPC_ENABLE_ADMIN` |
| `OP_NODE_RPC_ADMIN_STATE` | `BASE_NODE_RPC_ADMIN_STATE` |
| `OP_NODE_SAFEDB_PATH` | `BASE_NODE_SAFEDB_PATH` |
| `OP_NODE_SYNCMODE` | — |
| `OP_NODE_VERIFIER_L1_CONFS` | — |
| `OP_NODE_L2_ENGINE_KIND` | — |
| `OP_NODE_L1_RPC_KIND` | — |
| `OP_NODE_L1_BEACON_FETCH_ALL_SIDECARS` | — |
| `OP_NODE_L1_BEACON_FALLBACKS` | — |
| `OP_NODE_ROLLUP_LOAD_PROTOCOL_VERSIONS` | — |
| `OP_NODE_P2P_STATIC` | — |
| `OP_NODE_P2P_DISABLE` | — |
| `OP_NODE_P2P_NAT` | — |
## FAQ
- **Do I need to resync?** No, if you already run OP Reth — existing data is compatible.
- **What if I'm on `op-geth` or `nethermind`?** Switch to `base-reth-node` and bootstrap from a [Reth snapshot](/node-operations/snapshots/).
- **Do OP namespace RPCs still work?** Yes, all existing RPCs remain supported.
---
# basectl
Source: https://basehub.org/node-operations/basectl/
Description: Configure and inspect Base nodes across mainnet, sepolia, devnet, and custom configs.
`basectl` configures and inspects Base nodes across mainnet, Sepolia, devnet, and custom config targets. It ships with the workspace and runs via `cargo` or the `just basectl` recipe.
## Usage
```bash
# Build and run with a configuration target
cargo run -p basectl --release -- -c
```
Supported configurations:
| Config | Network |
|--------|---------|
| `mainnet` | Base Mainnet |
| `sepolia` | Base Sepolia Testnet |
| `devnet` | Local Development Network |
| `` | Custom configuration file |
## Examples
```bash
# Mainnet configuration
just basectl mainnet
# Sepolia testnet
just basectl sepolia
# Local devnet
just basectl devnet
```
## Architecture
`basectl` is split into two crates:
- **`basectl-cli`** ([`crates/infra/basectl`](https://github.com/base/base/tree/main/crates/infra/basectl)) — The library with configuration logic
- **`basectl`** ([`bin/basectl`](https://github.com/base/base/tree/main/bin/basectl)) — The binary entry point
The binary depends on `basectl-cli`, `clap` for argument parsing, `anyhow` for error handling, and `tokio` for async runtime.
---
# Configuration Reference
Source: https://basehub.org/node-operations/configuration/
Description: CLI flags, environment variables, and Cargo build profiles for base-reth-node.
## CLI Options
The Base Reth Node inherits Reth's comprehensive CLI. View all options:
```bash
./target/release/base-reth-node --help
```
Key option categories:
- **Network** — Chain selection, bootnodes, P2P port
- **RPC** — HTTP/WS endpoints, CORS, API namespaces
- **Database** — Data directory, state pruning
- **Metrics** — Prometheus endpoint
- **Engine API** — JWT secret, engine API endpoint
- **Logging** — Log level, log format
## Environment Variables
Configuration can also be set via environment variables. The devnet uses `etc/docker/devnet-env` for its environment.
## Build Profiles
The workspace defines several Cargo build profiles:
| Profile | Use Case | Key Settings |
|---------|---------|-------------|
| `dev` | Development | `debug = "line-tables-only"` |
| `release` | Production | `opt-level = 3`, `lto = "thin"`, `codegen-units = 16`, `strip = "symbols"`, `panic = "unwind"` |
| `maxperf` | Published release artifacts | Inherits `release`, then `lto = "fat"`, `codegen-units = 1` |
| `release-symbols` | Production build you need to profile | Inherits `release`, then `debug = "line-tables-only"`, `strip = "none"` |
| `bench` | Callgrind-driven benchmarks | Inherits `release`, then `debug = true`, `strip = false` |
| `profiling` | Performance analysis | Inherits `release`, then `lto = false`, `debug = "line-tables-only"`, `strip = "none"` |
| `ci` | CI builds | Inherits `dev`, then `debug = false`, `incremental = false` |
Two profiles share the production role, and which one you get depends on who is building. `release` is the default everywhere you build yourself: `docker-bake.hcl` declares `PROFILE` with a default of `release`, so a local `--build` and an ordinary Cargo build both land there. `maxperf` is reserved for what Base actually publishes. The release workflow compiles the native binary archives with it and passes `PROFILE: maxperf` when it bakes the image pushed to `ghcr.io/base/node`. It inherits everything from `release` and then trades build time for speed, using fat LTO across the whole graph and a single codegen unit. So a binary you build locally is not bit-identical to the published one, even at the same tag.
Two of these exist because `release` strips symbols. `release-symbols` restores them without changing any codegen setting, so a profiled binary matches what you ship. `bench` goes further and keeps full debug info, which iai-callgrind needs to find the function it measures; without symbols every counter reads zero.
Dependencies drop their debug info in `dev` builds through a `[profile.dev.package."*"]` override. Workspace crates keep theirs. This mostly targets the C and C++ build scripts behind rocksdb, mdbx, and jemalloc, which otherwise dominate the size of `target`.
## basectl
The [`basectl`](/node-operations/basectl/) utility provides configuration management for different network targets:
```bash
# Mainnet configuration
cargo run -p basectl --release -- -c mainnet
# Sepolia testnet
cargo run -p basectl --release -- -c sepolia
# Local devnet
cargo run -p basectl --release -- -c devnet
```
---
# Deployment
Source: https://basehub.org/node-operations/deployment/
Description: Run base-reth-node in production via the official Docker image or a custom source build.
import { Aside } from '@astrojs/starlight/components';
## Production Images
Production runs are best served by the published Docker image, which is built from [base/base](https://github.com/base/base):
```bash
docker pull ghcr.io/base/node-reth:latest
```
This image bundles both vanilla Reth and Base Reth and can be toggled with the `NODE_TYPE` environment variable:
```bash
# Run Base Reth
docker run ghcr.io/base/node-reth -e NODE_TYPE=base
# Run vanilla Reth
docker run ghcr.io/base/node-reth -e NODE_TYPE=vanilla
```
## Pinning a Release with `NODE_TAG`
The root `docker-compose.yml` in `base/base` pulls `ghcr.io/base/node:latest` unless you say otherwise. To run one specific published release without compiling anything, name its tag:
```bash
NODE_TAG=v1.3.0 docker compose up
```
A pinned tag bypasses the source build completely, so the node starts once the pull finishes. Leave `--build` off when you pin. Passing it triggers a local compile that takes precedence over the tag you asked for.
Note that `v1.3.0` is the earliest release published to `ghcr.io/base/node` out of `base/base`. Tags older than that were never pushed to this image path, so they are not reachable by pin.
### Compose Variables
A handful of variables let you retune the compose file from your shell or a `.env` file, so you never have to edit the file itself:
| Variable | Default | Purpose |
|----------|---------|---------|
| `NODE_TAG` | `latest` | Tag pulled from `ghcr.io/base/node`. Give it a release tag such as `v1.3.0` to pin. |
| `NETWORK_ENV` | `.env.mainnet` | Env file loaded by the `execution` and `node` services. Use `.env.sepolia` for testnet. |
| `HOST_DATA_DIR` | `./reth-data` | Host directory bind-mounted to `/data` in the execution container. Repoint it at an external volume if you need to. |
| `PROFILE` | `release` | Cargo profile applied when you pass `--build`. It matches the profile behind the published image. |
Running `docker compose up --build` compiles whatever is in your `base/base` checkout through the `base` target of `etc/docker/Dockerfile.rust-services`. That is the same target the published `ghcr.io/base/node` image comes from, so a local build and a pinned image lay out their binaries identically.
## Building from Source for Deployment
If you need a custom build:
```bash
# Standard release build
just build release
```
A local `--build` compiles with `release`, which sets `opt-level = 3`, `lto = "thin"`, `codegen-units = 16`, and strips symbols. Note that this is not the profile behind the image you pull. Base bakes its published images with `maxperf`, which adds fat LTO and one codegen unit on top of `release`. Expect a locally built node to behave the same and to benchmark a little slower.
If you need to profile a deployed binary, build the `release-symbols` variant instead. It keeps `release` codegen untouched and only restores the symbol table:
```bash
cargo build --profile release-symbols --package base-reth-node --bin base-reth-node
```
A `release` build leaves the binary at `target/release/base-reth-node`. See [Configuration](/node-operations/configuration/#build-profiles) for the full profile table.
## Hardware Requirements
Base Reth Node requires:
- **CPU:** Multi-core processor (4+ cores recommended)
- **Memory:** 16 GB+ RAM
- **Storage:** NVMe SSD with sufficient space for chain state
- **Network:** Stable, high-bandwidth connection
## Configuration
See the [Configuration Reference](/node-operations/configuration/) for all available options, or run:
```bash
./target/release/base-reth-node --help
```
---
# Docker Operations
Source: https://basehub.org/node-operations/docker/
Description: Build and run base-reth-node, the builder, and the websocket proxy with Docker.
## Dockerfiles
The repository provides several Dockerfiles in [`etc/docker/`](https://github.com/base/base/tree/main/etc/docker):
| Dockerfile | Purpose |
|-----------|---------|
| `Dockerfile.client` | Main Base Reth Node client |
| `Dockerfile.builder` | Block builder service |
| `Dockerfile.devnet` | Local development network setup |
| `Dockerfile.websocket-proxy` | WebSocket proxy for flashblock streaming |
## Building Images
### Client Node
```bash
docker build -t base-reth-node -f etc/docker/Dockerfile.client .
```
### Builder
```bash
docker build -t base-builder -f etc/docker/Dockerfile.builder .
```
### WebSocket Proxy
```bash
docker build -t websocket-proxy -f etc/docker/Dockerfile.websocket-proxy .
```
## Running Containers
```bash
docker run -it --rm \
-p 8545:8545 \
-p 8546:8546 \
-p 30303:30303 \
-p 30303:30303/udp \
-p 9222:9222 \
-p 9222:9222/udp \
-v /path/to/data:/data \
base-reth-node [OPTIONS]
```
Common flags:
- `-p 8545:8545` — HTTP JSON-RPC
- `-p 8546:8546` — WebSocket JSON-RPC
- `-p 30303:30303` (TCP/UDP) — discv4 P2P discovery and RLPx
- `-p 9222:9222` (TCP/UDP) — Reth discv5 peer discovery
- `-v /path/to/data:/data` — Persistent data volume
### Bootnode egress
In addition to the ingress ports above, the node needs outbound access to the Base bootnodes for initial peer discovery. Operators running behind strict egress filtering must allow outgoing traffic to ports `30301` (TCP/UDP) and `9200` (UDP); without these, the node cannot bootstrap into the peer set.
If egress is controlled with network ACLs rather than a stateful firewall (for example AWS security groups), open the ephemeral port range **32768–60999** (TCP/UDP) for outbound traffic as well. Stateful firewalls recognize and admit return packets on their own; ACLs do not, so omitting this range causes responses from peers to be dropped without warning.
## Docker Compose
The repository includes a Docker Compose configuration for running a local devnet:
```bash
docker compose --env-file etc/docker/devnet-env \
-f etc/docker/docker-compose.yml up -d --build
```
See [Local Devnet](/getting-started/devnet/) for the full devnet setup guide.
## Production Images
For production use, the official images are published at:
```
ghcr.io/base/node-reth
```
Release tags and the accompanying configuration live in the [base/base repository](https://github.com/base/base).
---
# Monitoring
Source: https://basehub.org/node-operations/monitoring/
Description: Prometheus metrics, devnet status commands, log streaming, and profiling for base-reth-node.
## Prometheus Metrics
The Base Reth Node exports Prometheus-compatible metrics. The `base-cli-utils` crate sets up a metrics HTTP listener using `metrics-exporter-prometheus`.
Key metric categories:
- **Process metrics** — CPU, memory, file descriptors (via `metrics-process`)
- **RPC metrics** — Request counts, latencies, error rates
- **Transaction pool** — Pool size, pending/queued counts
- **Sync progress** — Block height, peer count
- **Flashblocks** — Flashblock production rate, latency
## Devnet Monitoring
The devnet includes built-in monitoring commands:
```bash
# Check block numbers and sync status across all nodes
just devnet status
# View funded test accounts with balances and nonces
just devnet accounts
# Run smoke tests (send test transactions to L1 and L2)
just devnet smoke
# Full check suite
just devnet checks
```
## Log Streaming
Stream logs from devnet containers:
```bash
# All containers
just devnet logs
# Specific containers
just devnet logs base-builder base-client
```
## Profiling
For performance profiling, build with the `profiling` profile:
```bash
just devnet profiling
```
This starts the devnet with Pyroscope integration and optimized builds that retain frame pointers for accurate profiling.
The profiling profile settings:
- Inherits from `release`
- LTO disabled for faster builds
- Debug info: line tables only
- Frame pointers forced on
- Symbols not stripped
---
# Node Providers
Source: https://basehub.org/node-operations/node-providers/
Description: Hosted RPC providers for Base Mainnet and Base Sepolia, including Coinbase Developer Platform, Alchemy, QuickNode, and others.
import { Aside } from '@astrojs/starlight/components';
A range of providers offer hosted RPC endpoints for Base Mainnet and Base Sepolia. Capabilities, networks, and pricing tiers vary — links below point to each provider's documentation and pricing pages.
## Coinbase Developer Platform (CDP)
[CDP](https://portal.cdp.coinbase.com/) exposes an RPC endpoint that runs on the same node infrastructure powering Coinbase's retail exchange. The free tier is rate-limited and ready for early development.
Supported networks:
- Base Mainnet
- Base Sepolia (Testnet)
## 1RPC
[1RPC](https://1rpc.io/) is an on-chain attested, privacy-preserving RPC that minimizes metadata exposure when interacting with chains. Free and [paid plans](https://www.1rpc.io/#pricing) are available.
Supported networks:
- Base Mainnet
## Alchemy
[Alchemy](https://dashboard.alchemy.com/?utm_source=chain_partner&utm_medium=referral&utm_campaign=base) provides a developer platform with SDKs, [JSON-RPC APIs](https://docs.alchemy.com/reference/base-api-quickstart), and hosted Base mainnet and testnet nodes on a free tier.
Supported networks:
- Base Mainnet
- Base Sepolia (Testnet)
## All That Node
[All That Node](https://www.allthatnode.com/base.dsrv) is a multi-chain development platform with free and [paid plans](https://www.allthatnode.com/pricing.dsrv).
Supported networks:
- Base Mainnet
- Base Sepolia (Testnet)
## Ankr
[Ankr](https://www.ankr.com/rpc/base/) offers private and public Base RPC endpoints backed by a globally distributed node network. Free and [paid plans](https://www.ankr.com/rpc/pricing/) are available.
Supported networks:
- Base Mainnet
- Base Sepolia (Testnet)
## Blast
[Blast](https://blastapi.io/public-api/base) provides decentralized blockchain APIs via partnerships with third-party node providers. Users can [generate dedicated Base RPC endpoints](https://blastapi.io/login).
Supported networks:
- Base Mainnet
- Base Sepolia (Testnet)
## Blockdaemon
[Blockdaemon](https://www.blockdaemon.com/protocols/base/) hosts Base nodes with a free tier via the Ubiquity Data API Suite. Usage above the free tier incurs additional charges.
Supported networks:
- Base Mainnet
- Base Sepolia (Testnet)
## BlockPI
[BlockPI](https://blockpi.io/) provides Base RPC access with [free and paid plans](https://docs.blockpi.io/pricing/pricing-and-rate-limit).
Supported networks:
- Base Mainnet
- Base Sepolia (Testnet)
## Chainstack
[Chainstack](https://chainstack.com/build-better-with-base/) provisions elastic Base RPC nodes with personal, geographically diverse endpoints, plus archive nodes for full history queries. See the [free and paid plans](https://chainstack.com/pricing/).
Supported networks:
- Base Mainnet
- Base Sepolia (Testnet)
## dRPC NodeCloud
[dRPC NodeCloud](https://drpc.org/nodecloud-multichain-rpc-management) offers Base Mainnet and Base Sepolia endpoints alongside 180+ networks, with smart routing, analytics, key management, and front-end protection. Backed by 40 providers across 9 geoclusters. Free tier with flat-rate pricing from $10.
Supported networks:
- Base Mainnet
- Base Sepolia (Testnet)
## GetBlock
[GetBlock](https://getblock.io/nodes/base/) is a Blockchain-as-a-Service platform offering instant API access to full Base nodes with free, pay-per-use, and unlimited tiers.
Supported networks:
- Base Mainnet
- Base Sepolia (Testnet)
## NodeReal
[NodeReal](https://nodereal.io/) supplies Base node API access for blockchain infrastructure use cases.
Supported networks:
- Base Mainnet
## Nodies DLB
[Nodies DLB](https://nodies.app) operates high-performance RPC for Base and other OP Stack chains, with public free endpoints, pay-as-you-go, and enterprise plans.
Supported networks:
- Base Mainnet
- Base Testnet (available on request)
## NOWNodes
[NOWNodes](https://nownodes.io/nodes/basechain-base) provides shared and dedicated Base RPC access without rate limits.
Supported networks:
- Base Mainnet
## OnFinality
[OnFinality](https://onfinality.io) offers high-performance archive access to Base Mainnet and Base Sepolia. The free tier carries generous limits, and Trace and Debug APIs are available on [paid plans](https://onfinality.io/pricing).
Supported networks:
- Base Mainnet
- Base Sepolia (Testnet)
## QuickNode
[QuickNode](https://www.quicknode.com/chains/base) supports Base with Flashblocks and archive data, plus trace/debug capabilities for transaction analysis. Streams and Webhooks cover event-driven and data-streaming workloads, and the Marketplace includes add-ons such as the [Aerodrome Swap API](https://marketplace.quicknode.com/add-on/aerodrome-swap-api). See the [QuickNode Base docs](https://www.quicknode.com/docs/base) for setup.
Supported networks:
- Base Mainnet
- Base Sepolia (Testnet)
## RockX
[RockX](https://access.rockx.com) operates a global node network with developer tooling. The free [Base RPC](https://access.rockx.com/product/base-blockchain-api-for-web3-builders) tier provides institutional-grade access.
Supported networks:
- Base Mainnet
## Stackup
[Stackup](https://www.stackup.sh/) is an ERC-4337 infrastructure platform offering hosted Base nodes plus [account abstraction tooling](https://docs.stackup.sh/docs) such as bundlers and paymasters.
Supported networks:
- Base Mainnet
- Base Sepolia (Testnet)
## SubQuery
[SubQuery](https://subquery.network/rpc) is a decentralized RPC network with public free endpoints and Flex Plans for higher access.
Supported networks:
- Base Mainnet
## Tenderly Web3 Gateway
[Tenderly Web3 Gateway](https://tenderly.co/web3-gateway) is a hosted node solution with developer tooling spanning the full lifecycle — develop, test, deploy, and monitor on Base. [Free and paid plans](https://tenderly.co/pricing) are available.
Supported networks:
- Base Mainnet
- Base Sepolia (Testnet)
## Unifra
[Unifra](https://www.unifra.io) provides Web3 developer tooling, APIs, and Base node infrastructure.
Supported networks:
- Base Mainnet
## Validation Cloud
[Validation Cloud](https://app.validationcloud.io/) offers low-latency Base RPC with 50 million compute units available on the free tier (no credit card required) and a scale tier without rate limits.
Supported networks:
- Base Mainnet
---
# Performance Tuning
Source: https://basehub.org/node-operations/performance-tuning/
Description: Hardware, storage, and client recommendations for high-performance Base nodes, including production configurations and sync guidance.
import { Aside } from '@astrojs/starlight/components';
This guide covers the hardware, storage, and client choices that yield the best Base node performance.
## Hardware
A performant Base node needs adequate hardware. Recommended minimums:
1. A modern multi-core CPU with strong single-core performance.
2. At least 32 GB of RAM (64 GB preferred).
3. A locally attached NVMe SSD. RAID 0 layouts can boost throughput.
4. Sufficient capacity, sized as:
```
(2 × [current chain size] + [snapshot size] + 20% buffer)
```
The formula reserves room for chain growth and snapshot restoration. See [Base Stats](https://base.org/stats) for the current chain size and [Base Snapshots](https://snapshots.base.org) for snapshot size.
### Production hardware
Base production nodes use the following hardware:
- **Reth archive node**
- Instance: AWS `i7i.12xlarge` or larger
- Storage: RAID 0 across all local NVMe drives (`/dev/nvme*`)
- Filesystem: ext4
## Initial sync
Restore from a recent [snapshot](/node-operations/snapshots/) to dramatically shorten initial sync.
## Client software
The [base/base](https://github.com/base/base) repository carries the current stable client configurations and run instructions.
Reth is currently the most performant Base client, and ongoing optimization work is concentrated there. Background on the move to Reth: [Scaling Base with Reth](https://blog.base.dev/scaling-base-with-reth).
---
# Release Process
Source: https://basehub.org/node-operations/release-process/
Description: How base/base releases are produced — Start Release, automatic RC tagging and dispatched candidate builds, and Publish Release for the final tag.
Shipping a `base/base` release means driving two workflows by hand and letting the rest fire on their own. You start a release, let release candidates accumulate on the branch until one looks right, then publish that version as the final tag.
The version number lives in `Cargo.toml` on the release branch, and almost every guard rail in the pipeline keys off it. A branch whose `Cargo.toml` still reads `0.0.0` has not been initialised yet, and the automation declines to build from it.
## Step by step
### 1. Start a release
Go to `Actions → Start Release → Run workflow` and pick a bump type — `major` for breaking changes, `minor` for a feature release, `patch` for fixes.
You do not supply a version. The workflow derives the next one from the most recent final tag and cuts a `releases/vX.Y.Z` branch for it. Where that branch is cut from depends on the bump: a `patch` branches off the newest matching `releases/vX.Y.*` branch, while `major` and `minor` branch off `main`.
Creating the branch sets off **Release Version Sync**, which raises a PR writing the new version into `Cargo.toml`.
### 2. Merge the version sync PR
Nothing else can proceed until that PR lands. While `Cargo.toml` reads `0.0.0`, RC builds keep declining to run. Review it and merge it into the release branch.
### 3. Collect release candidates
From here the branch builds itself. **Create RC** runs on every push to it and:
- Backs out quietly when `Cargo.toml` is still `0.0.0`, which means step 2 has not finished.
- Works out the next number in the RC series and tags it — `v0.6.0-rc.1`, then `v0.6.0-rc.2`, and so on — against the commit that triggered the run.
- Hands that tag to **Build RC** as a separate dispatch, then reports success without waiting to see what the build does.
**Build RC** is what actually produces the artifacts, delegating to `Build Release` for multi-arch Docker images and native binaries. The compatibility `node` image and each of the single-binary images all receive the RC tag and nothing else; `latest` stays where it is until a final release. Because each candidate builds inside its own run, a fresh merge no longer cancels or queues behind the artifacts of the candidate before it — runner capacity permitting, the two build side by side.
That split is worth internalising before you read a green checkmark. A passing **Create RC** tells you a tag was allocated and a build was requested, and nothing more. Artifact success lives in the **Build RC** run, so that is the one to open when you want to know whether a candidate is installable.
Need another candidate? Push another commit. Fixes and backports both re-trigger the workflow, so there is no separate command for cutting an RC.
### 4. Publish the final release
When a candidate holds up, run `Actions → Publish Release → Run workflow` and type the bare version — `0.6.0`, with no `v` and no `releases/` in front of it.
Before doing anything, the workflow confirms the release branch is really there and that `Cargo.toml` has moved off `0.0.0`. Then it:
- Tags the release branch `vX.Y.Z`.
- Builds seven images under `PROFILE=maxperf`, each for both amd64 and arm64: the compatibility `node` image plus the single-binary `base`, `base-reth-node`, `base-consensus`, `base-builder`, `basectl`, and `base-snapshotter` images.
- Gives every one of them the same four tags: `vX.Y.Z`, `X.Y`, `X`, and `latest`.
- Drafts a GitHub release, writes its changelog automatically, and attaches the binaries.
The draft is the last manual gate. Read it over on GitHub and publish it yourself.
### Which image to pull
Every image lands under the `ghcr.io/base/` namespace, and the names are easy to confuse. The one to watch is `base`.
| Image | Bake target | What it holds |
|-------|-------------|---------------|
| `ghcr.io/base/node` | `base` | The compatibility image: `base`, `base-reth-node`, `base-consensus`, and `snapshotter`, plus `supervisord`, which is the default command and runs the execution and consensus entrypoints together. The root `docker-compose.yml` pulls this one. |
| `ghcr.io/base/base` | `unified` | Only the `base` binary, with `ENTRYPOINT ["./base"]`. |
| `ghcr.io/base/base-reth-node` | `execution` | Only `base-reth-node`. |
| `ghcr.io/base/base-consensus` | `consensus` | Only `base-consensus`. |
| `ghcr.io/base/base-builder` | `builder` | Only `base-builder`. |
| `ghcr.io/base/basectl` | `basectl` | Only `basectl`. |
| `ghcr.io/base/base-snapshotter` | `snapshotter` | Only `snapshotter`. |
The bake target called `base` publishes as `node`, while the image called `base` comes from a different target. So `ghcr.io/base/base` is not a renamed `ghcr.io/base/node`. Swap one for the other and the container starts a lone `./base` binary, with no `supervisord` and none of the entrypoint scripts the operator default relies on.
The split arrived after `v1.4.1-rc.11` was cut, so no tag published so far carries the single-binary images. Until a release built from it ships, `ghcr.io/base/node` is still the only image path you can pull.
Each image is published on its own, so one failure does not stop the rest. If neither architecture builds for an image, the workflow skips that image with a warning. If only one builds, it publishes that one with a warning. A final release can therefore exist on one image path but not another, or exist as amd64 only. Before you pin a tag on arm64 hardware, check that the manifest actually lists your platform:
```bash
docker buildx imagetools inspect ghcr.io/base/node:vX.Y.Z
```
## Why RC builds sometimes do nothing
**Create RC** is wired to every push on any `releases/v*` branch, including pushes that arrive before the version sync PR merges. Those are harmless. Rather than failing the run, the workflow spots the `0.0.0` version and exits with a notice.
RC numbering needs no bookkeeping either. `N` in `vX.Y.Z-rc.N` is derived from the tags already present.
Only the tagging and dispatch half is serialised per release branch, and it is serialised deliberately rather than throttled. The tagging job runs under [`queue: max`](https://docs.github.com/en/actions/how-tos/write-workflows/choose-when-workflows-run/control-workflow-concurrency#example-queueing-multiple-pending-runs), which lets as many as 100 runs sit in line instead of displacing one another. Setting `cancel-in-progress: false` on its own does not achieve that — pending runs still get replaced. Two caveats come with the queue. GitHub releases waiting jobs in the order they began waiting, which is not guaranteed to be commit order, though each run still tags the commit that started it. And once the line is full, further runs are cancelled outright.
The dispatch is explicit for a reason that is easy to trip over when editing these workflows. A tag pushed under `GITHUB_TOKEN` [will not set off another workflow](https://docs.github.com/en/actions/how-tos/write-workflows/choose-when-workflows-run/trigger-a-workflow#triggering-a-workflow-from-a-workflow), so **Create RC** cannot simply push the tag and expect a build to notice. It calls the build directly instead, which is why it carries `actions: write`. The permissions needed to publish artifacts are not granted there; they stay with **Build RC**.
## Retrying a candidate build
Which half failed decides what you rerun.
If the tag was created but the dispatch did not go through, rerun **Create RC**. It recognises the tag it already made at that commit and reuses it rather than burning the next number in the series.
If the tag is fine and the artifacts failed, rerun the **Build RC** run itself, or start one against the existing tag:
```sh
gh workflow run build-rc.yml --ref v1.4.0-rc.1
```
**Build RC** only accepts an RC tag as its ref. Pointing it at a release branch or a final tag will not work. Note also that dispatching a tag that is already building starts a second build rather than replacing the first, so check before you fire one off.
## Rolling out the workflow change
Landing this split across branches has an ordering requirement that is easy to get backwards. GitHub will only dispatch a workflow that exists on the default branch, so **Build RC** has to merge to the default branch first. Only then do you backport the workflow and release-script changes to each release branch still in service.
Both halves matter because dispatch happens at the RC tag. The commit under that tag has to contain `build-rc.yml` and the reusable build workflow too, otherwise there is nothing there to run. Tags cut before the split therefore cannot be dispatched this way at all; recover those by rerunning the build jobs they originally had.
Two things this rollout does not do. Updating the default branch alone leaves push-triggered workflows on existing release branches exactly as they were. And runs already queued or in flight keep the configuration they started with, so the change will not retroactively rescue cancelled runs or free the concurrency locks they are holding.
There is one trap in older runs specifically. Before touching a legacy **Create RC** run, look at which ref it checks out. Earlier definitions checked out the release branch rather than the triggering commit, and since the branch keeps moving, a rerun can tag a newer commit than the one you were trying to recover.
## Workflow reference
| Workflow | Trigger | What it does | Output |
|----------|---------|--------------|--------|
| **Start Release** | Manual — bump type | Cuts the release branch from the computed next version | `releases/vX.Y.Z` branch |
| **Release Version Sync** | Automatic — branch creation | Raises the PR that writes the version into `Cargo.toml` | PR targeting the release branch |
| **Create RC** | Automatic — push to `releases/v*` | Tags the next candidate and requests its build | RC tag + a dispatched build |
| **Build RC** | Dispatched by Create RC at the RC tag | Checks the ref is an RC tag, then builds on its own schedule | Docker images + binaries |
| **Build Release** | Called by Build RC and Publish Release | Shared build step behind both paths | Docker images + binaries |
| **Publish Release** | Manual — version number | Cuts the final tag and assembles the release | Final tag + Docker images + draft GitHub release |
`Build Release` is the only entry here you never invoke directly. Both the candidate path and the publish path delegate their image and binary builds to it, so a final release and the candidate it came from are produced by the same build steps.
Both paths build with `maxperf`, not the `release` default. `Build Release` compiles every native binary archive under it and passes it through to the image bake, so candidates and final releases are optimized identically. It layers fat LTO and a single codegen unit over `release`, which is why these builds take considerably longer than one you run yourself. See [build profiles](/node-operations/configuration/#build-profiles) for the full settings.
---
# Releases
Source: https://basehub.org/node-operations/releases/
Description: Versioning, the pinned Reth tag, production image registry, and the GitHub Actions release flow.
import { Aside } from '@astrojs/starlight/components';
## Versioning
The workspace version is `0.0.0` (development). All crates share the workspace version defined in the root `Cargo.toml`:
```toml
[workspace.package]
version = "0.0.0"
edition = "2024"
rust-version = "1.88"
```
## Reth Version
Base Reth Node tracks a specific Reth release. The current pinned version:
```
reth v1.11.0
```
This is specified in the workspace dependencies as a git dependency with a tag:
```toml
reth-db = { git = "https://github.com/paradigmxyz/reth", tag = "v1.11.0" }
```
## Production Docker Images
Production images are published at:
```
ghcr.io/base/node-reth
```
These come out of [base/base](https://github.com/base/base) and carry both vanilla Reth and Base Reth, which you pick between with `NODE_TYPE`.
## Release Process
Release branches follow the `releases/v` naming convention. The process uses GitHub Actions workflows:
1. **Release candidates** are created via the "Create Release" workflow with `rc` type. RC versions are auto-numbered (e.g., `v1.0.0-rc.1`, `v1.0.0-rc.2`).
2. **Final releases** are created with `final` type, which tags Docker images as `v1.0.0`, `1.0`, `1`, and `latest`.
### Workflows
| Workflow | Trigger | Purpose |
|----------|---------|---------|
| Release Version Sync | Automatic | Updates `Cargo.toml` versions on release branches |
| Create Release | Manual | Creates RC or final release tags |
| Release | Tag push | Builds Docker images, creates GitHub release |
## Default Build Targets
The workspace defines default members that are built by `cargo build`:
- `bin/based`
- `bin/node` (produces `base-reth-node`)
- `bin/basectl`
- `bin/builder`
- `bin/consensus`
- `bin/ingress-rpc`
- `bin/audit-archiver`
- `bin/mempool-rebroadcaster`
---
# Snapshot Benchmarking
Source: https://basehub.org/node-operations/snapshot-benchmarking/
Description: Run repeatable base-bench performance measurements on an L1-free snapshot devnet, publish the artifacts, and compare 2-second against 200ms block cadences.
import { Aside } from '@astrojs/starlight/components';
`base-bench snapshot` measures node performance against a prepared Base datadir, with no L1 in the loop. It exists for local performance investigation: you restore a snapshot, drive a workload at it, and publish the artifacts somewhere they can be compared.
It is not the tool for testing an application against real chain state. For that, use the `base dev` snapshot chain described in [Local Devnet](/getting-started/devnet/#snapshot-dev-chain-base-dev).
The important property is repeatability. Two runs are only worth comparing if everything except the variable under test held still, and most of this guide is about the discipline that requires.
## Before you start
You need an optimised `base-bench` binary. A debug build will not give you a meaningful number at 400M gas — it measures the build profile, not the node.
You also need a fully prepared Base datadir snapshot to restore from. Materialise a writable pair for one run using whatever snapshot and restore mechanism your environment provides, then point the paths at it:
```sh
RUN=blake2f-2s-run-1
BUILDER_DATADIR=/path/to/restored/${RUN}-builder
CLIENT_DATADIR=/path/to/restored/${RUN}-client
test -f "$BUILDER_DATADIR/db/mdbx.dat"
test -f "$CLIENT_DATADIR/db/mdbx.dat"
```
## Run one benchmark
Build the harness out of `base/base` and run it:
```sh
cargo build --release -p base-system-tests --bin base-bench
export BASE_BENCH_CLIENT_VERSION="base/$(git rev-parse --short HEAD)"
target/release/base-bench snapshot \
--chain sepolia \
--builder-datadir "$BUILDER_DATADIR" \
--client-datadir "$CLIENT_DATADIR" \
--load-test-config /path/to/blake2f-2s.yaml \
--benchmark-run snapshot-throughput \
--scenario blake2f-2s-run-1 \
--run-id blake2f-2s- \
--output-dir results/blake2f-2s-run-1
```
`--chain` picks the network rules used to continue the snapshot. It takes the built-in Base aliases, including `mainnet` (the default) and `sepolia`, or a path to a Base genesis JSON file.
A JSON chain whose L2 chain ID matches a built-in Base network gets that network's rollup configuration automatically, so `--rollup-config` is optional. A chain ID outside that set does not, and you have to supply it:
```sh
target/release/base-bench snapshot \
--chain /path/to/genesis.json \
--rollup-config /path/to/rollup.json \
--builder-datadir "$BUILDER_DATADIR" \
--client-datadir "$CLIENT_DATADIR" \
--load-test-config /path/to/load-test.yaml \
--benchmark-run custom-throughput \
--scenario custom-run-1 \
--output-dir results/custom-run-1
```
One invocation starts the builder and validator, funds a throwaway load-test account, runs the workload, checks that both roles agree on canonical blocks across the measured window, writes the result artifacts, and then exits the process outright, skipping node and database cleanup.
That last part is deliberate rather than a rough edge. Tearing down cleanly costs time and buys nothing here, because the run assumes its snapshot datadirs are disposable writable clones you discard afterwards. Point the command at a datadir you intend to keep and the abrupt exit becomes a real hazard, since the databases are left however the process abandoned them. If you need the previous bounded graceful teardown, pass a nonzero `--shutdown-timeout-seconds`, for example `10`.
The local sequencer picks its block gas limit from the cadence. A 2-second workload gets 10 Ggas per block; a 200ms workload gets 1 Ggas. Those two numbers are chosen to be the same thing said twice: both leave theoretical block capacity at 5 Ggas/s, so a cadence comparison is not quietly also a capacity comparison. Pass `--block-gas-limit ` to override the cadence default for one run.
Each `--output-dir` comes out self-contained, ready to hand to `base/benchmark`:
```text
/
benchmark-result.json
load-test-result.json
metadata.json
metrics-sequencer.json
metrics-validator.json
```
## Aggregate selected runs
Result directories are immutable inputs. To build a report index without disturbing them, pass the report root plus the direct-child run directories you want included:
```sh
target/release/base-bench aggregate \
--output-dir /absolute/path/to/results \
--versioned-pages \
/absolute/path/to/results/run-a \
/absolute/path/to/results/run-b
```
This writes `results/metadata.json` atomically. For each unique set of report tags — which includes the scenario and the block-time tag — it keeps the entry with the latest `createdAt`. Distinct scenarios, cadences, and client versions all survive that rule; a repeat of an identical tag set does not, because the newer run replaces the older one.
`--versioned-pages` then splits the report into pages. It rewrites `BenchmarkRun` so each client version gets its own page, and adds a `{cohort}--latest` alias page on top:
- The latest page holds, for each scenario, block-time, and transaction-payload combination, the newest run from the past seven days.
- Pages get distinct names, so the visualizer dropdown can tell them apart.
- The latest page is timestamped 1ms after the newest run it selected. That makes the visualizer's Latest option land on it.
Source metadata and scenario labels are left alone either way. `id` stays the unique raw artifact identifier, and `BenchmarkRun` stays the report cohort key.
## Choose comparable runs
Five flags and one environment variable look similar and do different jobs. Using them interchangeably is the fastest way to produce a comparison that means nothing.
| Field | Purpose | Comparison rule |
|---|---|---|
| `--benchmark-run` | Report cohort | Use the same value for every candidate in one comparison, such as `snapshot-throughput`. |
| `--scenario` | User-visible experiment/repetition label | Use a descriptive value for each selected run, such as `blake2f-2s-run-1` or `blake2f-200ms-run-1`. |
| `--run-id` | Immutable artifact identifier | Keep it unique. It does not group runs. |
| `--output-dir` | Complete local artifact directory | Keep it unique. Never allow two runs to write to the same directory. |
| `BASE_BENCH_CLIENT_VERSION` | Binary/build label | Keep it equal for cadence comparisons; deliberately vary it only for client-version comparisons. |
| `--block-gas-limit` | Produced-block gas ceiling | Leave it unset for cadence comparisons, so both sides keep the matched 5 Ggas/s capacity. Set it only when the ceiling itself is the variable. |
### A fair 2-second against 200ms comparison
1. Restore both roles from the same immutable snapshot for every repetition.
2. Use the same release binary, host, load parameters, seed, and funding policy.
3. Configure the 2-second YAML with 30 measured blocks.
4. Configure the 200-millisecond YAML with 300 measured blocks.
5. Give both cases the same `--benchmark-run`; use distinct scenarios and artifact IDs.
6. Alternate cadence order across repetitions (`2s`, `200ms`, then `200ms`, `2s`) to reduce thermal and cache-order bias.
Both YAMLs should drive one fixed Blake2f precompile payload at 50,000 rounds, with sender count, in-flight limits, batching, funding, and seed held identical. The differing block counts are deliberate: 30 blocks at 2 seconds and 300 at 200ms both cover a 60-second window, so the two cases measure the same span of time.
Keep maximum-throughput tuning separate from fixed-offered-load comparisons; they answer different questions. Record whether each run used a warm or cold page cache, too. Restoring both datadirs from the same snapshot does not by itself put the page cache in the same state.
Snapshot roles persist every block, which is what leaves the disposable datadirs inspectable afterwards.
## Compare in base/benchmark
Collect the finished output directories under one parent:
```text
results/
blake2f-2s-run-1/
blake2f-200ms-run-1/
```
From the paired `base/benchmark` repository, serve that directory and start the frontend in API mode:
```sh
make build-server
./bin/report-server --local-dir /absolute/path/to/results --port 8080
cd report
yarn install
VITE_DATA_SOURCE=api \
VITE_API_BASE_URL=http://127.0.0.1:8080/ \
VITE_ALLOWED_HOSTS=localhost \
yarn dev --host 127.0.0.1 --port 3000
```
Open `http://127.0.0.1:3000/#/run-comparison/snapshot-throughput`. Filter `Transaction Payload=blake2f`, pick the `Scenario` values and the node role you want, then set **Show Line Per** to **Block Time Milliseconds**. That draws the 2-second and 200-millisecond series together while keeping their scenarios distinct.
The x-axis lines up because the metric files record `BlockNumber` in two-second-equivalent units. At 200ms, block 1 is `0.1` and block 10 is `1.0`, so a 6,000-block run ends at `600.0` — directly comparable with a 600-block run at 2 seconds.
The report server can also synthesise extra comparison rows from the source runs. Those are views, not executions: cite the original run IDs when you refer to raw artifacts.
## Cleanup
Once the harness exits, keep the result directory and reset only the disposable datadirs through your environment's snapshot lifecycle.
If a run was interrupted, look for leftover `base-bench` or `base-devnet` processes before you remove its datadirs. Never remove or modify the immutable source snapshot.
---
# Snapshots
Source: https://basehub.org/node-operations/snapshots/
Description: Restore Base nodes from official Reth and proofs snapshots for Base Mainnet and Base Sepolia to skip the initial sync window.
import { Aside } from '@astrojs/starlight/components';
Restoring from a snapshot drastically reduces initial Base node sync time. Snapshots are refreshed regularly.
Whether you're planning to run a Base node or already operate one, seeding from a snapshot lets you skip most of the initial sync. Work through the steps below carefully.
## Restoring from a snapshot
These steps assume you're working from the cloned `node` directory — the one that holds `docker-compose.yml`.
Whichever binary you use, the download resolves through `https://chain.base.org`, from which the CLI derives its own manifest path. Per-chain archives then come from `mainnet-v2-snapshots.base.org`, `sepolia-v2-snapshots.base.org`, and `zeronet-v2-snapshots.base.org`, picked by your `--chain` value.
1. **Prepare the data directory.**
- **Before launching Docker for the first time**, create the host directory that will be mapped into the container. The path must match the `volumes` entry in `docker-compose.yml`:
```bash
mkdir ./reth-data
```
- If a previous run left an existing data directory, **stop the node first** (`docker compose down`), wipe the contents (for example, `rm -rf ./reth-data/*`), then continue.
2. **Choose the chain.** Select the network with the `--chain` flag. Base parsers accept two naming surfaces, and either one resolves the same chain:
| Network | Namespaced name | Operator selector | Chain ID |
|--------------|-----------------|-------------------|----------|
| Base Mainnet | `base` | `mainnet` | 8453 |
| Base Sepolia | `base-sepolia` | `sepolia` | 84532 |
| Base Zeronet | `base-zeronet` | `zeronet` | 763360 |
The namespaced column keeps its `base-` prefix so these values cannot be confused with the Ethereum L1 chain names that share the same ecosystem. The selector column is the short form the unified `base` binary exposes. Read `mainnet` carefully: within Base tooling it resolves to Base Mainnet, never to Ethereum Mainnet. The two sets are kept deliberately separate, so a parser that only understood one of them used to reject the other. Every Base entry point now resolves both, which means a `--chain` value you learned from one command carries over to the rest. `base_sepolia` with an underscore also still works as a legacy alias, and `dev` selects the local devnet.
3. **Download the snapshot.** V2 snapshots are no longer a single archive — they're broken into many small, segmented files. The CLI advertises just one `archive` snapshot because it holds every file; `full` and `minimal` simply pull progressively smaller subsets of it. Pick the configuration that fits your node from the table below.
| Config | Flag | What you get | Use when |
|-------------|-------------|--------------|----------|
| **Minimal** | `--minimal` | The leanest bootable set: current state and headers, carrying only the history that's strictly required. | Best when you want the quickest, lightest download and have no need for historical data. |
| **Full** | `--full` | Everything a default full node prunes down to — state, headers, and a capped span of recent transactions, receipts, and history. | Best for running an ordinary full node without holding the entire archive. |
| **Archive** | `--archive` | The complete dataset — every transaction, receipt, and account/storage record, with nothing pruned. | Best when you need the full history, such as for archive queries or indexing. |
These three presets are just the ready-made defaults published at [chain.base.org/snapshots](https://chain.base.org/snapshots). If none of them matches your retention needs, you can still supply custom pruning flags through the [`RETH_PRUNING_ARGS` variable](https://github.com/base/base/blob/main/.env.mainnet#L34) in `.env.mainnet` (or `.env.sepolia`) — but to do so you must pull the archival snapshot first and then apply your own pruning arguments on top of it.
```bash
# Minimal node on Base Mainnet
base-reth-node download --minimal --datadir ./reth-data --chain base --resumable
# Full node on Base Sepolia
base-reth-node download --full --datadir ./reth-data --chain base-sepolia --resumable
```
For archival nodes only, you can alternatively run `base-reth-node db migrate-v2` — but expect it to take **much** longer than a download, and note that `--resumable` is not supported by `migrate-v2`.
4. **(Optional) Tune download concurrency.**
The `--download-concurrency` flag governs how many HTTP downloads the snapshot job runs at once. Its default of `8` is a solid baseline for most machines.
On high-end hardware you can raise it to speed things up. A reasonable rule of thumb is **2× the number of physical CPU cores**:
```bash
# Example: a 16 physical-core machine
base-reth-node download --full --datadir ./reth-data --chain base --download-concurrency 32
```
5. **Start the node.** With the snapshot data in place, return to the root of your Base node folder and bring it up:
```bash
cd ..
docker compose up --build
```
The node should pick up syncing from the last block recorded in the snapshot.
6. **Verify.** Tail the logs (`docker compose logs -f `) or use the [sync monitoring](/getting-started/running/) command to confirm the node starts at the snapshot's block height.
## Proofs snapshots
If you run the [historical proofs ExEx](/getting-started/running/), proof database snapshots are available so you can skip the 24-48 hour backfill.
Because proofs snapshots are still packaged as archives, grab `aria2c` first — it's a resumable downloader that gracefully recovers from the periodic connection drops Cloudflare imposes on long transfers. If it isn't already installed:
```bash
# macOS
brew install aria2
# Ubuntu / Debian
sudo apt-get install aria2
```
| Network | Download command |
| ------- | ---------------- |
| Testnet | `aria2c -c -x 16 -s 16 "https://sepolia-reth-proofs-snapshots.base.org/$(curl -s https://sepolia-reth-proofs-snapshots.base.org/latest)"` |
| Mainnet | `aria2c -c -x 16 -s 16 "https://mainnet-reth-proofs-snapshots.base.org/$(curl -s https://mainnet-reth-proofs-snapshots.base.org/latest)"` |
With the download complete, unpack the archive — swap `snapshot-filename` for the file you actually pulled:
```bash
tar -xzvf
# For .tar.zst
tar -I zstd -xvf
```
Extraction typically produces a `reth/` directory. Move its contents into the data directory you created back in **Prepare the data directory**:
```bash
mv ./reth/* ./reth-data/
rm -rf ./reth # remove the now-empty extracted folder
```
The chain data subdirectories (`chaindata`, `nodes`, `segments`, etc.) must sit directly under `./reth-data`, not in a nested folder. Once that's confirmed, you can delete the downloaded archive (`.tar.gz`) to reclaim disk space, then pick back up from **Start the node** above.
## FAQ
**What actually separates a Full node from a Minimal one?**
In Reth, "full" is not a separate node type — it is just a pruned node configured with a specific preset. Reth's `--full` preset keeps the most recent **10,064 blocks**, which is roughly 1.4 days on Ethereum but only about 5-6 hours on Base because of the faster block cadence.
For a tier-by-tier breakdown of exactly what each one holds on disk, Reth's own [storage documentation](https://reth.rs/run/storage/minimal) is the reference to work from.
**I was already running a pruned node on v1 storage. How do I bring that setup over to v2?**
It comes down to how far back your pruning distance reached. If it extended past 10,064 blocks, the Full snapshot cannot carry you — that window is all it holds, and everything older is simply absent. Pull the Archive snapshot instead, then layer your pruning arguments on top of it.
**I'm seeing "Archive extracted, but output verification failed." What went wrong?**
Almost always this means a fresh snapshot was published while your download was in flight. Stop the `download` command and start it again — it's idempotent, so it won't re-pull files already on disk and will only fetch the delta.
---
# Standalone Proving
Source: https://basehub.org/node-operations/standalone-proving/
Description: Run the Base prover stack outside the devnet and buy ZK proofs for a live network using your own RPC endpoints and a funded Succinct requester key.
import { Aside } from '@astrojs/starlight/components';
A devnet is not a prerequisite for proving. The standalone stack aims the prover trio at whichever live network you care about — Base Sepolia, Base Mainnet — drawing on RPC endpoints you supply and a [Succinct Prover Network](https://docs.succinct.xyz/docs/protocol/spn/architecture) requester key you have funded yourself. Real proof requests against live dispute games follow from there. For what the service does underneath this workflow, see [ZK Prover](/specifications/zk-prover/).
## The stack
Three containers make up the stack, and `just prover up|down|logs ` manages them. Every network label gets a local control plane of its own, along with its own stored jobs, so two labels never share state.
Docker Engine must be at **28.3.3** or newer. Below that version a port bound to `127.0.0.1` can still reach the local network — and loopback binding is precisely the mechanism holding the unauthenticated requester RPC to your host. Startup reads the daemon version for that reason, and it also refuses any pre-existing Docker network whose options would let traffic route straight through.
| Container | Role |
|-----------|------|
| `prover-service-postgres` | Keeps sessions on disk, under `.zk-prover//` |
| `base-prover-service` | The coordinator exposing JSON-RPC; this is what [`basectl`](/node-operations/basectl/) connects to |
| `base-prover-zk-host` | Worker process — it derives witnesses, then files the proof requests |
## ZK backends
Every backend is reachable from `basectl proofs propose` through `--zk-backend`. Finalization is narrower: `basectl proofs finalize` will take `network` or `cluster` and nothing else. A dry run returns nothing that could go on chain, which rules it out there.
| Backend | What it does | Cost | Needs |
|---------|--------------|------|-------|
| `dry-run` | Replays the range locally in the SP1 executor, then prints cycle statistics. Nothing provable comes out of it. | Free | Four RPC endpoints |
| `cluster` | Hands the work to an SP1 GPU cluster that you stand up yourself. | Whatever your own hardware costs | A cluster endpoint, and an S3 bucket for artifacts |
| `network` (default) | Purchases the finished proof through the Succinct Prover Network marketplace. | Billed in PROVE | Four RPC endpoints, and a requester key holding a balance |
Of the three, this stack handles `network` and `dry-run`. Give it all four RPC endpoints and `dry-run` becomes available on its own; add the requester key and `network` unlocks too. Measure first, buy second — that is what `dry-run` is for.
## Game ranges
Two forms of argument work with `basectl proofs finalize `: the proxy address of a dispute game, or the L1 transaction that spawned that game through `DisputeGameFactory.createWithInitData`. Either way, the game itself supplies the parameters. Basectl reads the output roots, the L1 head, the checkpoint interval, and the committed block range straight out of it, and it will not let an operator name a range by hand.
## Requester key
Give proving a key of its own. Do not point it at anything already in personal or operational use. Only `network`, the paid path, genuinely requires one — dry runs never touch it. The format is a bare hex private key, which the worker reads from `NETWORK_PRIVATE_KEY`. Requesters backed by a KMS fall outside this guide.
The [Succinct Prover Network quickstart](https://docs.succinct.xyz/docs/sp1/prover-network/quickstart) covers the setup:
1. Create the key — `cast wallet new` does it.
2. Obtain PROVE on Ethereum mainnet.
3. Move that PROVE onto the Succinct Network account belonging to the key, from the account page of the [Succinct explorer](https://explorer.succinct.xyz/).
That balance is what each request bills against.
## RPC requirements
Building a witness means replaying old state, which rules out any provider holding nothing but the current tip. All four endpoints have to fully serve every range you intend to prove — the claimed block, the pre-state block ahead of it, and the stretch of L1 those derive from. Prune history in front of your target range and witness generation simply fails.
- **L1 execution** (`L1_NODE_ADDRESS`) — the `finalized` block tag, access to old blocks, `debug_getRawHeader`, and `debug_getRawReceipts`.
- **L1 beacon** (`L1_BEACON_ADDRESS`) — spec and genesis endpoints, together with archived blob sidecars covering whichever L1 range holds the batch data.
- **L2 execution** (`L2_NODE_ADDRESS`) — `eth_getProof`, `debug_getRawBlock`, `debug_getRawHeader`, `debug_executePayload`, complete historical blocks, and `debug_dbGet` when preimages need a fallback.
- **Base consensus** (`BASE_CONSENSUS_ADDRESS`) — `optimism_outputAtBlock` and `optimism_rollupConfig`.
## Operator flow
1. **Put the endpoints in the environment.** Add the requester key as well, if proofs will be purchased:
```bash
export L1_NODE_ADDRESS=https://your-l1-node.example
export L1_BEACON_ADDRESS=https://your-l1-beacon.example
export L2_NODE_ADDRESS=https://your-base-node.example
export BASE_CONSENSUS_ADDRESS=https://your-base-consensus.example
export NETWORK_PRIVATE_KEY=0x...
```
Leave `NETWORK_PRIVATE_KEY` out and the stack still runs, limited to dry runs. It earns its place on the paid `network` path alone.
2. **Produce the reproducible SP1 ELFs**, unless they already exist. A worker sitting on stubs gets rejected outright by paid network proving:
```bash
just succinct build-elfs
```
3. **Bring the stack up against a network label.** Startup validates that label, confirms the four endpoints answer, inspects the ELFs, compiles both images, and launches all three containers:
```bash
just prover up sepolia
```
Reuse the same label on the basectl side, via `-c sepolia`. Keeping the two aligned is what makes the per-network local database and the session IDs refer to a single chain.
4. **Locate a live dispute game that still lacks a ZK proof:**
```bash
basectl -c sepolia proofs games --missing-zk
```
To look one over, run `basectl -c sepolia proofs games `. Either command wants `proofs.dispute_game_factory` set in config, or `--factory` supplied on the spot.
5. **Try a dry run against that game first.** It is optional, but it demonstrates that your RPC coverage reaches far enough, and it yields cycle statistics — without spending anything. Name the same L1 wallet you plan to submit with, so the rehearsal matches the real thing:
```bash
basectl -c sepolia proofs propose \
--prover-address \
--prover-rpc http://localhost:9000 \
--zk-backend dry-run
```
A session ID comes back; feed it to `basectl proofs status ` to watch progress. What a dry run leaves behind is execution data alone. No proof bytes sit in it, so none of it reaches the chain.
6. **Set the submitting wallet, then fire the single paid finalization command.** Settlement-layer ETH has to be sitting in that wallet to cover the closing L1 transaction. Do not confuse it with the requester key — SP1 gets paid from the PROVE deposited against that other key:
```bash
export BASECTL_SUBMITTER_PRIVATE_KEY=0x...
basectl -c sepolia proofs finalize \
--prover-rpc http://localhost:9000 \
--zk-backend network
```
Before committing, a prompt lists exactly what is about to happen: which L1 endpoint, which submitting wallet, which payment backend, which block range, which game. Finalize then orders the proof, holds for as long as 24 hours, and submits `verifyProposalProof` once the proof exists. Issue the identical command a second time and nothing gets bought twice — it picks the deterministic prover-service session back up. A session that failed earlier is treated more cautiously still: rather than quietly re-purchasing, finalize aborts. Add `--retry-failed` to say explicitly that a new paid request is wanted.
`just prover down sepolia` stops everything. What lives in `.zk-prover/sepolia/` is untouched by that, which is why proof results and sessions come back after a restart. For live logs, `just prover logs sepolia`.
Port `9000` is the RPC default. Override it through `PROVER_SERVICE_RPC_PORT`. Give that variable a bare number: whatever you supply lands in the host-port slot of a `127.0.0.1::9000` mapping.
## Requester RPC exposure
Two separate protections keep this port private. The publish itself is scoped to `127.0.0.1`, so none of your host's routable addresses answer on it. Docker adds a second layer independently, discarding packets aimed directly at the container. The Compose network then nails down the two options capable of undoing that second layer: gateway mode is fixed at `nat`, which stops a daemon defaulting to `routed` or `nat-unprotected` from taking effect, and `trusted_host_interfaces` is left empty, so no `default-network-opts` entry can nominate interfaces permitted to route straight to the container. Should an existing network already carry either option, `just prover up` refuses to reuse it.
Go through `just prover up`. Calling Compose yourself bypasses both the daemon version check and the network check.
**Nothing authenticates against this API.** Reaching it is the whole of the authorization check. A caller who gets through can order proofs on the paid `network` backend, billed against the PROVE you deposited, and can also reach `deleteProofRequest`, `deleteProofsByTeeSigner`, and `listProofs` — enough to enumerate or destroy proofs you already paid for. Nor is there a ceiling on aggregate spend: fresh session IDs let a caller keep queueing paid work indefinitely.
Driving the stack from a different host is reasonable, but do not solve it by republishing `9000` on a public interface. Terminate TLS in an authenticated reverse proxy of your own, sit it in front of the loopback port, and have it police both which callers get through and which `zk_backend` values they are allowed to name. Neither the worker RPC on `9001` nor Postgres gets published to the host in the first place, and neither should start.
## Splitting propose and submit
Three phases hide inside `proofs finalize` — it proposes, it polls, and it submits to L1. Split them apart when each has to live in its own process. The commands below work against the same game you turned up in step 4:
```bash
basectl -c sepolia proofs propose \
--prover-address \
--prover-rpc http://localhost:9000
```
Values such as the intermediate root interval, the L1 head, and the block range get taken from the game on L1 rather than passed in. Two stages then run through your stack: first a compressed proof of the range, after that an aggregation step shrinking it to a PLONK proof of roughly 870 bytes. Choose `network` and you pay Succinct for both. Because `--prover-address` is committed into the proof journal, verification succeeds for one wallet only — the one named there. Progress shows up through `basectl proofs status `, and the PLONK proof bytes end up stored on the finished session. Failed sessions behave as they do under `finalize`: left alone, until `--retry-failed` authorizes buying another proof.
Submission comes next, signed by whichever wallet you named in `--prover-address`:
```bash
export BASECTL_SUBMITTER_PRIVATE_KEY=0x... # key for
basectl -c sepolia proofs submit \
--prover-rpc http://localhost:9000
```
The proof gets collected from your prover service, `AggregateVerifier.verifyProposalProof(proof)` goes out to the game, and basectl blocks until that transaction is mined. Hold the wallet and the defaults steady from `propose` onward and no session ID is needed, since basectl computes the identical deterministic one each time. Anything overridden at propose time has to be repeated here — `--session-id`, `--zk-backend`, `--intermediate-root-interval`. Where the proof might not be finished yet, `--wait` polls until it is. One last safeguard fires immediately before the send: basectl re-reads the game, and if that game has closed or picked up a ZK proof in the meantime, it stops without burning gas.
## Sizing a range
Measure before money changes hands. `proofs propose --zk-backend dry-run` reports what a candidate game actually commits to, and the cycle count that comes back answers whether the SP1 range program can hold it. No Base-specific ceiling exists; what bounds a range is how much gas its blocks consumed. When the goal is just a paid smoke test, reach for the smallest eligible game on offer instead of inventing a range that nothing on chain commits to.
## Restarts and duplicate submissions
Acceptance by the network is the point at which the worker records that request's Succinct Network ID in Postgres. Restart the zk-host afterwards and any ID already on record goes back to polling — nothing gets filed a second time. That is what keeps duplicate payment rare.
## Relationship to the devnet
There is no prover inside the devnet. What `just devnet up` gives you is the chain stack and nothing else. Running the prover trio at all — pointed at a live network, or at a devnet on your machine — means using this standalone stack. For the devnet case, export the RPC endpoints the devnet publishes to the host, again written as `http://host.docker.internal:` rather than `localhost`, then run `just prover up devnet`.
Only chains whose activation registry admin address ships compiled into the binary can be proved. Three qualify: Base Mainnet, Sepolia, and Zeronet. Since the stock docker devnet carries another chain ID, witnesses cannot be generated against it — the exception being a devnet running with Beryl and Cobalt switched off.
## Troubleshooting
**`failed to run Succinct host`.** Go to the worker log on the zk-host, where the generation failure itself is recorded. What `basectl proofs status` surfaces afterwards can be a generic claim-expiry message from prover-service, which hides the real cause. Trust the worker log.
---
# Node Troubleshooting
Source: https://basehub.org/node-operations/troubleshooting/
Description: Diagnose setup, sync, performance, snapshot, and networking issues for Base nodes running the official Docker setup.
This guide covers the most common issues operators hit when running a Base node from the official [Docker setup](https://github.com/base/base), with steps to diagnose and resolve each one.
## General troubleshooting
Before chasing specific issues, work through these baseline checks.
1. **Inspect container logs.** Tail the relevant container with `docker compose logs -f `:
- L2 client (Reth): `docker compose logs -f execution`
- Rollup node: `docker compose logs -f node`. Look for errors, warnings, or repeated messages.
2. **Check container status.** Confirm the right containers are running with `docker compose ps`. Restart loops or exited containers warrant a log review.
3. **Watch resource usage.** CPU, RAM, disk I/O, and network usage are common bottlenecks. `htop`, `iostat`, and `iftop` are useful starting points.
4. **Verify RPC endpoints.** Use `curl` to confirm the L2 client's RPC is responding (see [running a Base node](/getting-started/running/)). Confirm L1 endpoints are correct and reachable from the node host.
5. **Check the L1 node.** Ensure the configured L1 execution and consensus clients are fully synced, healthy, and accessible. L1 issues block L2 sync.
## Common issues
### Setup and configuration
- **Issue:** The Docker command (`docker compose up ...`) fails.
- **Check:** Is Docker (and Docker Compose) installed and the daemon running?
- **Check:** Are you in the correct directory (the cloned `node` directory containing `docker-compose.yml`)?
- **Check:** Command syntax — typos in `NETWORK_ENV` or `CLIENT` are common.
- **Issue:** A container fails to start with `.env` or environment variable errors.
- **Check:** Did you set the L1 endpoints (`OP_NODE_L1_ETH_RPC`, `OP_NODE_L1_BEACON`) in the right `.env` file (`.env.mainnet` or `.env.sepolia`)?
- **Check:** Is `OP_NODE_L1_BEACON_ARCHIVER` set if your configuration or L1 node requires it?
- **Check:** Is `OP_NODE_L1_RPC_KIND` set correctly for your L1 provider?
- **Check:** (Reth) Are `RETH_CHAIN` and `RETH_SEQUENCER_HTTP` correctly configured in `.env`?
- **Issue:** JWT secret or auth errors between `op-node` and the L2 client.
- **Check:** Avoid hand-editing `OP_NODE_L2_ENGINE_AUTH` or the JWT file path (`$OP_NODE_L2_ENGINE_AUTH`) unless you know what you are doing — `docker-compose` handles this automatically.
- **Issue:** Permission errors against the data volume (`./reth-data`).
- **Check:** The user running `docker compose` must have write access to the cloned repo so Docker can write into `./reth-data`. Avoid `sudo`-running Docker commands; instead, add your user to the `docker` group.
### Syncing
- **Issue:** The node never starts syncing or block height stalls.
- **Check:** `op-node` logs for L1 endpoint or L2 client connection errors.
- **Check:** Execution client logs for Engine API issues on port `8551` or P2P errors.
- **Check:** L1 node health — is it accessible and fully synced?
- **Check:** System time. Run `ntp` or `chrony`; significant clock drift breaks P2P.
- **Issue:** Sync is unusually slow.
- **Check:** Hardware against the [performance tuning](/node-operations/performance-tuning/) recommendations, especially RAM and **NVMe SSD**. Disk I/O is usually the bottleneck.
- **Check:** L1 RPC responsiveness. A slow L1 node throttles L2 sync.
- **Check:** Network bandwidth and connection quality.
- **Check:** `op-node` and L2 client logs for performance warnings or errors.
- **Issue:** `optimism_syncStatus` (port `7545` on `op-node`) reports a large time delta or errors.
- **Action:** Inspect rollup node and L2 execution client logs around the time of the check to identify the cause (often L1 connectivity or L2 client problems).
- **Issue:** `Error: nonce has already been used` when sending transactions.
- **Cause:** The node is still catching up to the chain head.
- **Action:** Wait for full sync. Track progress via `optimism_syncStatus` or logs.
- **Tip:** [`basectl`](/node-operations/basectl/), the Base node operator CLI, surfaces richer node data and diagnostic checks than the raw RPC output.
### Performance
- **Issue:** High CPU, RAM, or disk I/O usage.
- **Check:** Hardware against the [performance tuning](/node-operations/performance-tuning/) recommendations, and upgrade if needed. Local NVMe SSDs are critical.
- **Check:** Client logs for specific bottlenecks or errors.
### Snapshot restoration
Refer to the [Snapshots](/node-operations/snapshots/) guide for the canonical procedure.
- **Issue:** `wget` fails or the snapshot download is corrupted.
- **Check:** Network connectivity.
- **Check:** Available disk space.
- **Action:** Retry the download and verify the URL.
- **Issue:** `tar` extraction fails.
- **Check:** Downloaded file integrity.
- **Check:** Available disk space — extraction needs much more than the download itself.
- **Check:** `tar` command syntax.
- **Issue:** The node fails to start after restoring a snapshot, with database errors or missing files.
- **Check:** Did you run `docker compose down` before touching the data directory?
- **Check:** Did you remove the contents of the old data directory (`./reth-data/*`) before extracting and moving the new data?
- **Check:** Is the chain data directly inside `./reth-data` rather than in a nested folder (for example, `./reth-data/reth/...`)? Verify the structure.
- **Issue:** Out of disk space during download or extraction.
- **Action:** Free space or attach a larger volume. Use the storage formula:
```
(2 * chain_size + snapshot_size + 20% buffer)
```
### Networking and connectivity
- **Issue:** RPC or WS connection refused (e.g., `curl localhost:8545` fails).
- **Check:** Is the L2 client container running (`docker compose ps`)?
- **Check:** Are you using the correct port (`8545` HTTP, `8546` WS by default)?
- **Check:** L2 client logs — did the RPC server fail to start?
- **Check:** Are `--http.addr` and `--ws.addr` set to `0.0.0.0` in the client config or entrypoint so external connections work within the Docker network?
- **Issue:** Low peer count, or the node cannot connect to any peers at all.
- **Check:** Ingress ports `30303` (TCP/UDP) and `9222` (TCP/UDP for Reth discv5) are reachable from the public internet through any host firewall and upstream network filtering.
- **Check:** Outbound traffic to ports `30301` (TCP/UDP) and `9200` (UDP) is permitted. These are the Base bootnode endpoints — if egress to them is blocked, the node has no entry point into peer discovery and will report zero peers even when ingress rules look correct.
- **Check:** Node logs for P2P errors.
- **Action:** Behind NAT, set `--nat=extip:` via `ADDITIONAL_ARGS` in `.env` (see [advanced configuration](/getting-started/running/)).
- **Issue:** Port conflicts in logs or `docker compose up` fails.
- **Check:** Other host services using the default ports (`8545`, `8546`, `8551`, `6060`, `7545`, `30303`):
```bash
sudo lsof -i -P -n | grep LISTEN
sudo netstat -tulpn | grep LISTEN
```
- **Action:** Stop the conflicting service or remap the Base container ports in `docker-compose.yml`, then update the related variables (`$RPC_PORT`, `$WS_PORT`, etc.) in `.env`.
## Getting more help
If you have worked through this guide and the issue persists:
- **Discord:** Join the [Base Discord](https://discord.gg/buildonbase) and post in `#node-operators` with details of your setup, the issue, and relevant logs.
- **GitHub:** Search the [base/base issue tracker](https://github.com/base/base/issues). File a fresh issue when the behaviour looks like a defect.
---
# Adding a New Network Upgrade
Source: https://basehub.org/node-operations/upgrades/
Description: Every code change required to land a new Base network upgrade — config, traits, RollupConfig methods, EVM spec resolution, and precompile routing.
import { Aside } from '@astrojs/starlight/components';
This guide walks through each code change needed to land a new network upgrade in [`base/base`](https://github.com/base/base). The work falls into two groups: edits required for every upgrade, and extra edits that apply only when the upgrade changes EVM execution rules.
The Azul upgrade is the running example. Substitute `Azul`, `azul`, and `BASE_AZUL` with the actual upgrade name. For broader context on the codebase, see the [architecture overview](/architecture/overview/).
## Architecture overview
Activation is wired through three layers:
1. **Config layer** — an optional per-upgrade activation timestamp lives in `UpgradeConfig`, which `RollupConfig` embeds; `RollupConfig` in turn surfaces the `is_X_active(timestamp)` helpers.
2. **Trait layer** — typed, generic activation checks come from the `BaseUpgrade` enum and the `BaseUpgrades` trait, shared alike by the consensus and execution layers.
3. **Execution layer** — an active upgrade is mapped to its EVM spec by `BaseSpecId`; `spec_by_timestamp_after_bedrock` and `RollupConfig::spec_id` decide which spec applies, and `BasePrecompiles` picks the matching precompile set.
## Part 1 — Required for every upgrade
### 1. Add the variant to the `BaseUpgrade` enum
**File:** [`crates/common/chains/src/upgrade.rs`](https://github.com/base/base/blob/main/crates/common/chains/src/upgrade.rs)
Within the `upgrade!` macro, add the new variant just after the current final entry:
```rust
upgrade!(
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
#[derive(Default)]
BaseUpgrade {
// ... existing variants ...
/// Jovian: Base network upgrade.
Jovian,
/// Azul: First Base-specific network upgrade.
Azul, // <-- add here
}
);
```
Then bump each chain config array method's length from `[(Self, ForkCondition); N]` to `N+1`, appending the new entry. Leave mainnet and sepolia on `ForkCondition::Never` until activation is scheduled; the generic devnet takes `ForkCondition::ZERO_TIMESTAMP`:
```rust
pub const fn mainnet() -> [(Self, ForkCondition); 10] {
[
// ... existing entries ...
(Self::Azul, ForkCondition::Never),
]
}
pub const fn devnet() -> [(Self, ForkCondition); 10] {
[
// ... existing entries ...
(Self::Azul, ForkCondition::ZERO_TIMESTAMP),
]
}
```
Finally, extend `check_base_upgrade_from_str` in the test module to cover the new upgrade variant.
### 2. Add the `BaseChainUpgrades` index arm
**File:** [`crates/common/chains/src/chain.rs`](https://github.com/base/base/blob/main/crates/common/chains/src/chain.rs)
Add `Azul` to the `use BaseUpgrade::{...}` import and add a match arm to `Index`:
```rust
use BaseUpgrade::{
Azul, Bedrock, Canyon, Ecotone, Fjord, Granite, Holocene, Isthmus, Jovian, Regolith,
};
impl Index for BaseChainUpgrades {
fn index(&self, hf: BaseUpgrade) -> &Self::Output {
match hf {
// ... existing arms ...
Jovian => &self.forks[Jovian.idx()].1,
Azul => &self.forks[Azul.idx()].1, // <-- add
}
}
}
```
### 3. Add the config field and nested struct
**File:** [`crates/common/genesis/src/chain/upgrade.rs`](https://github.com/base/base/blob/main/crates/common/genesis/src/chain/upgrade.rs)
For standard upgrades (a flat timestamp field), add the field directly to `UpgradeConfig`:
```rust
/// `azul_time` sets the activation time for the Base Azul network upgrade.
#[cfg_attr(feature = "serde", serde(skip_serializing_if = "Option::is_none"))]
pub azul_time: Option,
```
For namespaced upgrades that take the `{ "base": { "azul": } }` JSON shape, declare a sub-struct and embed it:
```rust
/// Upgrade configuration for Base-specific upgrades.
#[derive(Debug, Copy, Clone, Default, Hash, Eq, PartialEq)]
#[cfg_attr(feature = "arbitrary", derive(arbitrary::Arbitrary))]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
#[cfg_attr(feature = "serde", serde(deny_unknown_fields))]
pub struct BaseUpgradeConfig {
#[cfg_attr(feature = "serde", serde(skip_serializing_if = "Option::is_none"))]
pub azul: Option,
}
pub struct UpgradeConfig {
// ... existing fields ...
#[cfg_attr(feature = "serde", serde(skip_serializing_if = "Option::is_none"))]
pub base: Option,
}
```
Add the new entry to `UpgradeConfig::iter()` as well, and re-export any newly added public types from `crates/common/genesis/src/chain/mod.rs` and `crates/common/genesis/src/lib.rs`.
### 4. Add activation methods to `RollupConfig`
**File:** [`crates/common/genesis/src/rollup.rs`](https://github.com/base/base/blob/main/crates/common/genesis/src/rollup.rs)
Add `is_X_active` and `is_first_X_block` right after the previous upgrade's methods. The pattern you follow turns on whether the new upgrade is **standalone** or **cascading**.
**Standalone** (e.g. `pectra_blob_schedule`, `Azul`) — turned on in isolation, never inferred from a later upgrade being active. Reach for this pattern when the upgrade touches only protocol-level behavior and does not gate the upgrade that follows it:
```rust
/// Returns true if Base Azul is active at the given timestamp.
pub fn is_base_azul_active(&self, timestamp: u64) -> bool {
self.upgrades.base.as_ref().and_then(|b| b.azul).is_some_and(|t| timestamp >= t)
}
/// Returns true if the timestamp marks the first Base Azul block.
pub fn is_first_base_azul_block(&self, timestamp: u64) -> bool {
self.is_base_azul_active(timestamp)
&& !self.is_base_azul_active(timestamp.saturating_sub(self.block_time))
}
```
Leave the previous terminal upgrade's `is_X_active` method as-is — no cascade is added.
**Cascading** (e.g. `Canyon`, `Ecotone`, `Isthmus`) — whenever the new upgrade is active, the prior one counts as active too. Update the earlier terminal upgrade's method, then add the new method beside it:
```rust
/// Returns true if Jovian is active at the given timestamp.
pub fn is_jovian_active(&self, timestamp: u64) -> bool {
self.upgrades.jovian_time.is_some_and(|t| timestamp >= t)
|| self.is_next_active(timestamp) // <-- cascade to next fork
}
/// Returns true if Next is active at the given timestamp.
pub fn is_next_active(&self, timestamp: u64) -> bool {
self.upgrades.next_time.is_some_and(|t| timestamp >= t)
}
```
Add the new arm to `upgrade_activation` in `impl BaseUpgrades for RollupConfig` too. For a **standalone** upgrade, the prior arm retains `unwrap_or(ForkCondition::Never)`:
```rust
BaseUpgrade::Jovian => self
.upgrades
.jovian_time
.map(ForkCondition::Timestamp)
.unwrap_or(ForkCondition::Never), // standalone: no cascade
BaseUpgrade::Azul => self
.upgrades
.base
.as_ref()
.and_then(|b| b.azul)
.map(ForkCondition::Timestamp)
.unwrap_or(ForkCondition::Never),
_ => ForkCondition::Never, // required: BaseUpgrade is #[non_exhaustive]
```
For a **cascading** upgrade, swap the prior arm's `unwrap_or(ForkCondition::Never)` for `.unwrap_or_else(|| self.upgrade_activation(BaseUpgrade::Next))`.
### 5. Add the trait method
**File:** [`crates/common/chains/src/upgrades.rs`](https://github.com/base/base/blob/main/crates/common/chains/src/upgrades.rs)
```rust
/// Returns `true` if [`Azul`](BaseUpgrade::Azul) is active at given block timestamp.
fn is_azul_active_at_timestamp(&self, timestamp: u64) -> bool {
self.fork_condition(BaseUpgrade::Azul).active_at_timestamp(timestamp)
}
```
Note the accessor: the trait declares its own `fork_condition`, so the trait method calls that rather than `RollupConfig`'s inherent `upgrade_activation`. Step 4 above still uses `upgrade_activation`, which remains in place on `RollupConfig`.
### 6. Update timestamp constants and test fixtures
**Files:**
- [`crates/common/chains/src/upgrade.rs`](https://github.com/base/base/blob/main/crates/common/chains/src/upgrade.rs) (mainnet, sepolia, devnet constants)
- [`crates/common/chains/src/lib.rs`](https://github.com/base/base/blob/main/crates/common/chains/src/lib.rs)
- [`crates/common/chains/src/test_utils.rs`](https://github.com/base/base/blob/main/crates/common/chains/src/test_utils.rs)
Add named constants once an activation timestamp is confirmed:
```rust
// mainnet.rs
/// Base Azul mainnet activation timestamp.
pub const BASE_MAINNET_BASE_AZUL_TIMESTAMP: u64 = ;
// sepolia.rs
/// Base Azul sepolia activation timestamp.
pub const BASE_SEPOLIA_BASE_AZUL_TIMESTAMP: u64 = ;
```
Re-export them from `lib.rs` next to the existing timestamp constants.
Then update the `UpgradeConfig` literal in both registry fixture files:
```rust
upgrades: UpgradeConfig {
// ... existing fields ...
jovian_time: Some(BASE_MAINNET_JOVIAN_TIMESTAMP),
base: Some(BaseUpgradeConfig { azul: Some(BASE_MAINNET_BASE_AZUL_TIMESTAMP) }),
},
```
While the activation timestamp is still unconfirmed, keep `base: None` and hold the chain arrays at `ForkCondition::Never`.
### 7. Update the default rollup config
**File:** [`crates/common/chains/src/test_utils.rs`](https://github.com/base/base/blob/main/crates/common/chains/src/test_utils.rs)
The `default_rollup_config()` function activates every upgrade at genesis for dev use. Add the new upgrade:
```rust
upgrades: UpgradeConfig {
// ... existing fields ...
jovian_time: Some(0),
base: Some(BaseUpgradeConfig { azul: Some(0) }),
},
```
### 8. Verify the upgrade consistency tests
**File:** [`crates/common/chains/tests/upgrade_consistency.rs`](https://github.com/base/base/blob/main/crates/common/chains/tests/upgrade_consistency.rs)
The tests walk every entry in `BaseUpgrade::VARIANTS` and compare two sources of truth per network. On mainnet, the derived rollup config's `fork_condition(fork)` has to equal `ChainUpgrades::mainnet().fork_condition(fork)`; on Sepolia, the comparison is against `ChainUpgrades::sepolia().fork_condition(fork)`. The rollup configs under test are `BASE_MAINNET_ROLLUP_CONFIG` and `BASE_SEPOLIA_ROLLUP_CONFIG`, both exported from `base_common_chains::test_utils`.
There is no skip list anymore: every variant is checked. The two sides must report the same activation condition, and that includes both returning `ForkCondition::Never` while an upgrade is still unscheduled. Any mismatch fails the test.
## Part 2 — Required when the upgrade changes EVM execution
You can skip this part when the upgrade is purely protocol-level (batch decoding, derivation rules, system config) and adds no new EVM opcodes, precompile addresses, or gas-rule changes.
### 9. Add the `BaseSpecId` variant
**File:** [`crates/common/evm/src/spec.rs`](https://github.com/base/base/blob/main/crates/common/evm/src/spec.rs)
```rust
pub enum BaseSpecId {
// ... existing variants ...
JOVIAN,
AZUL, // <-- add
OSAKA,
}
```
Touch `BaseSpecId::into_eth_spec()` only if the new Base upgrade shifts the paired Ethereum EL upgrade. Because `BaseSpecId` wraps `BaseUpgrade`, the variant must be added to `BaseUpgrade` first:
```rust
BaseUpgrade::Isthmus | BaseUpgrade::Jovian => SpecId::PRAGUE,
BaseUpgrade::Azul | BaseUpgrade::Beryl => SpecId::OSAKA,
```
Add the new `BaseUpgrade` variant with its canonical string name:
```rust
/// Beryl upgrade.
Beryl,
```
`BaseSpecId` parsing and display delegate to `BaseUpgrade`.
### 10. Route precompiles
**File:** [`crates/common/precompiles/src/provider.rs`](https://github.com/base/base/blob/main/crates/common/precompiles/src/provider.rs)
When the upgrade brings new precompiles, define a new method on `BasePrecompiles`; when it reuses the prior set, just widen the existing arm in `new_with_spec`:
```rust
// Reuse previous precompile set
BaseUpgrade::Azul | BaseUpgrade::Beryl => Self::azul(),
// Or add a new set
BaseUpgrade::Beryl => Self::beryl(),
```
### 11. Update spec resolution
**File:** [`crates/common/chains/src/upgrade.rs`](https://github.com/base/base/blob/main/crates/common/chains/src/upgrade.rs)
Place the new upgrade as the leading check, since the newest active upgrade takes precedence:
```rust
pub fn from_timestamp(chain_spec: impl Upgrades, timestamp: u64) -> Self {
if chain_spec.is_beryl_active_at_timestamp(timestamp) {
Self::Beryl
} else if chain_spec.is_azul_active_at_timestamp(timestamp) {
Self::Azul
} else if chain_spec.is_jovian_active_at_timestamp(timestamp) {
Self::Jovian
} // ... remaining checks unchanged
}
```
### 12. Update the reth upgrade schedule builder
**File:** [`crates/common/chains/src/chain.rs`](https://github.com/base/base/blob/main/crates/common/chains/src/chain.rs)
Add the new upgrade to `to_chain_upgrades()`. Where it pairs with a new Ethereum upgrade (as Canyon does with Shanghai), push both entries; otherwise push only the Base upgrade entry:
```rust
// No paired Ethereum upgrade
forks.push((BaseUpgrade::Jovian.boxed(), self[BaseUpgrade::Jovian]));
forks.push((BaseUpgrade::Azul.boxed(), self[BaseUpgrade::Azul])); // <-- add
```
## Checklist
### Always required
- [ ] `BaseUpgrade` variant added in `upgrade.rs`; all four chain arrays updated
- [ ] `Index` arm added in `chain.rs`
- [ ] Config field (flat or nested struct) added to `UpgradeConfig` in `upgrade.rs`; `iter()` updated; new types re-exported
- [ ] `is_X_active` + `is_first_X_block` added to `RollupConfig`; `upgrade_activation` arm added; previous terminal upgrade cascades to new one (unless standalone)
- [ ] `is_X_active_at_timestamp` added to `BaseUpgrades` trait
- [ ] Timestamp constants added to chain config modules and re-exported from `lib.rs`
- [ ] Registry fixtures (`test_utils/mod.rs`) updated
- [ ] Default rollup config updated (`defaults.rs`)
- [ ] Upgrade consistency tests pass
### Required when EVM execution changes
- [ ] `BaseSpecId` variant added with `into_eth_spec` mapping and `#[strum(serialize = "...")]` attribute
- [ ] Precompile match arm updated (or new precompile set added)
- [ ] `spec_by_timestamp_after_bedrock` updated (`common/evm/src/spec.rs`)
- [ ] `RollupConfig::spec_id` updated (`common/genesis/src/rollup.rs`)
- [ ] `to_chain_upgrades` updated (`execution/chainspec/src/upgrades.rs`)
```
---
# Avoid Malicious Flags
Source: https://basehub.org/security/avoid-malicious-flags/
Description: Practical steps to keep your Base app from being flagged as malicious — verify contracts, request verification, and follow UX best practices.
Keep your app from being flagged as malicious by verifying contracts, requesting verification with trusted ecosystem sources, and following standard UX practices.
## 1. Verify and reduce the risk of your smart contract
- **Verify the contract source.** Publish verified source code for your contracts on [block explorers](/network/block-explorers/). For example, verification is available on [Etherscan](https://etherscan.io/verifyContract) and [Basescan](https://basescan.org/verifyContract) under "Verify Contract".
- **Limit user-fund exposure.** Design contracts to keep user funds out of unnecessary risk paths. Request only the minimum amount needed to complete each transaction.
## 2. Submit a verification request
After verifying your contract source, submit a [verification request](https://report.blockaid.io/). Verification helps ecosystem signal providers recognize your app as safe.
## 3. Follow app best practices
- **Accessibility across regions.** Avoid geo-blocking or other access restrictions that lock out specific regions or countries. If legal or compliance requirements force restrictions, note them in the verification request.
- **Consistent behavior.** Avoid sudden or unexplained UI changes that erode user trust in your app's reliability.
- **Transparent onchain interactions.** The onchain action should match the UI. A "Mint" button should clearly emit a mint transaction.
- **Standard sign-in methods.** Offer the standard wallet connection options — WalletConnect, Coinbase Wallet SDK, and the popular browser extension wallets.
- **Audit your contracts.** Have your contracts audited by a reputable firm, publish the report, and link to it from your app so users can find it. An audit signals that you have invested in securing the codebase.
Following these recommendations significantly reduces the chance of your app being flagged as malicious and helps maintain a secure, trustworthy environment for users.
---
**Still flagged?**
Coinbase Wallet may produce false positives. Confirm you have completed the actions above first. If your app remains flagged as suspicious or malicious, [report it to Blockaid](https://report.blockaid.io/mistake).
---
# Bug Bounty
Source: https://basehub.org/security/bug-bounty/
Description: Coinbase's million-dollar HackerOne bug bounty program covers Base, the Base bridge contracts, and Base infrastructure.
The Coinbase HackerOne bug bounty program covers the Base network, the Base bridge contracts, and Base infrastructure, with vulnerability reports triaged around the clock.
## Program coverage
In line with Base's strategy of being the safest way for users to access crypto, Coinbase extends its [best-in-industry](https://www.coinbase.com/blog/celebrating-10-years-of-our-bug-bounty-program) million-dollar [HackerOne bug bounty program](https://hackerone.com/coinbase?type=team) to:
- The Base network
- The Base bridge contracts
- Base infrastructure
Coinbase's program runs alongside Optimism's existing [Immunefi Bedrock bounty program](https://immunefi.com/bounty/optimism/), which covers the open-source [Bedrock](https://docs.optimism.io/stack/getting-started) OP Stack framework.
## Submitting a report
All potential vulnerabilities should be submitted via the [HackerOne platform](https://hackerone.com/coinbase). Reports are triaged by Coinbase engineers with relevant domain expertise, ensuring rapid SLAs and high-quality review.
For program scope, eligibility, and reward details, see the [security program policies](https://hackerone.com/coinbase?view_policy=true).
## Related
- [Reporting Vulnerabilities](/security/report-vulnerability/) — full procedure for submitting a vulnerability report.
- [Security Council for Base](/security/security-council/) — the multi-party group that signs off on Base contract upgrades.
---
# Reliability and Liveness
Source: https://basehub.org/security/reliability-and-liveness/
Description: Where Base reports outages and publishes postmortems and audits, how bug bounties are split, what you can do if the sequencer censors or halts, and which sequencer components are open source.
import { Aside } from '@astrojs/starlight/components';
This page collects the places to look when you need to judge how dependable Base is: live status, past incidents, audits, bounties, the escape hatch for censored transactions, and the source for the software that orders blocks.
## Status and incident history
Live component health for Base Mainnet and Base Sepolia sits on [status.base.org](https://status.base.org). Covered components include producing blocks, posting batches to L1, the Flashblocks stream, the mempool, deposits and withdrawals, and the public RPC endpoints.
- **Past incidents** are listed with timelines and resolutions at [status.base.org/history](https://status.base.org/history). BaseHub keeps a paraphrased running record in [Incident History](/network/incident-history/).
- **Alerts** are available by subscribing on [status.base.org](https://status.base.org).
- **Postmortems** for major incidents go out on the [Base Engineering Blog](https://blog.base.dev/). The [June 25th block production outage postmortem](https://blog.base.dev/postmortem-june-25th-block-production-outage) is one example, and the [Engineering Blog index](/architecture/engineering-blog/) lists the rest.
## Audits
Each third-party audit report lives in the repository whose code it reviewed. A report states its scope, the commit it looked at, what it found, and how each finding was closed out.
- **Smart contracts:** [base/contracts audits](https://github.com/base/contracts/tree/main/audits). These include the multiproof, proof, Cobalt, and dynamic upgrade contract reviews.
- **Node and precompiles:** [base/base audits](https://github.com/base/base/tree/main/audits). These include the B20 precompile and the dynamic upgrade node reviews. The folder is organised by upgrade (`azul`, `beryl`, `cobalt`).
- **Audit competitions:** [Immunefi reports](https://reports.immunefi.com/base), including the contest held for the Azul hardfork.
For the OP Stack pieces Base relied on up to and including OP Stack Upgrade 18, such as the bridge and the `OptimismPortal` contract, the reviews sit with Optimism in its [security reviews folder](https://github.com/ethereum-optimism/optimism/tree/develop/docs/security-reviews).
## Bug bounties
Two standing programs split the ground between them. HackerOne takes offchain components and infrastructure. Cantina takes deployed smart contracts. The Azul upgrade also had a one-off public audit competition on Immunefi. Scope, reward ceilings, and how to file are on [Report a Vulnerability](/security/report-vulnerability/) and [Bug Bounty](/security/bug-bounty/).
## Censorship resistance and sequencer liveness
Base has one active sequencer at a time. It runs as a high-availability cluster, and if the leader stops producing blocks, a follower takes over leadership. The [Flashblocks architecture](/flashblocks/architecture/) page shows the parts involved.
When the sequencer refuses your transaction, or stops altogether, you still have a route in. Send the transaction as a deposit through the `OptimismPortal` contract on Ethereum (see [Deposits to Base](/network/bridging-and-withdrawals/#deposits-to-base)). Two protocol rules make that route reliable:
- **The sequencer cannot skip deposits.** Each L1 block fixes the deposits that must appear in the first L2 block of its [sequencing epoch](/specifications/glossary/#sequencing-epoch). An L2 block that leaves them out breaks the derivation rules and is invalid.
- **The wait is bounded.** Should batches stop arriving on Ethereum, every node waits out one [sequencing window](/specifications/glossary/#sequencing-window), then fills in the absent L2 blocks itself, with the queued deposits inside them. Base sets that window to 3,600 L1 blocks, which is roughly 12 hours at 12 seconds per L1 block (see [Configuration](/specifications/configuration/#consensus-parameters)).
Halts and slow inclusion are announced on [status.base.org](https://status.base.org). If the sequencer has to stop streaming Flashblocks, preconfirmations switch off and confirmation falls back to whole blocks, which arrive every 2 seconds until [Denim](/specifications/denim-overview/) shortens them.
## Open-source sequencer components
All the software that orders and sequences Base transactions is published:
| Component | What it does | Source |
| --- | --- | --- |
| base-consensus | Consensus client run both by the sequencer and by independent node operators | [base/base](https://github.com/base/base/tree/main/crates/consensus) |
| base-reth-node | Execution layer client, transaction pool included | [base/base](https://github.com/base/base/tree/main/crates/execution) |
| base-builder | Block builder that arranges transactions into Flashblocks | [base/base](https://github.com/base/base/tree/main/crates/builder) |
| websocket-proxy | Fans the Flashblocks stream out to subscribers | [base/base](https://github.com/base/base/tree/main/bin/websocket-proxy) |
| rollup-boost | Flashbots-maintained proxy that sits on the Engine API between consensus and execution | [flashbots/rollup-boost](https://github.com/flashbots/rollup-boost) |
| op-conductor | High-availability controller that picks the sequencer leader | [ethereum-optimism/optimism](https://github.com/ethereum-optimism/optimism/tree/develop/op-conductor) |
[Block Building](/network/block-building/) covers the ordering rules these components carry out. You do not have to trust the sequencer's word for the result: node operators rebuild and check the canonical chain themselves from the batches and deposits posted to Ethereum.
## Planned upgrades
Upcoming network upgrades and their target months are tracked on upstream's [Upgrades](https://docs.base.org/upgrades/overview) page. BaseHub covers the current ones in the [Cobalt](/specifications/cobalt-overview/) and [Denim](/specifications/denim-overview/) overviews.
---
# Reporting Vulnerabilities
Source: https://basehub.org/security/report-vulnerability/
Description: How to report Base vulnerabilities — HackerOne for offchain services and infrastructure, Cantina for deployed smart contracts.
Base routes vulnerability reports through two separate platforms so that each report reaches reviewers with the right domain expertise. Offchain components and services flow through Coinbase's long-running HackerOne program, while findings in deployed smart contracts go to a dedicated Cantina program.
## Bug bounty programs
Consistent with Base's goal of being the safest way for users to access crypto, two complementary bounty programs cover the surface:
- The Coinbase [HackerOne bug bounty program](https://hackerone.com/coinbase?type=team) — a [best-in-industry](https://www.coinbase.com/blog/celebrating-10-years-of-our-bug-bounty-program) million-dollar program — has been extended to cover the Base network and Base infrastructure.
- A separate [Cantina bug bounty program](https://cantina.xyz/code/55316f42-3c5e-4746-9bd0-0f18dcbc344b), with a 5 million-dollar reward pool, covers every deployed smart contract used by Base and by Coinbase products and services.
## Where to submit a report
Pick the platform that matches what you found:
1. [**HackerOne**](https://hackerone.com/coinbase) — for offchain components and services. Submissions are triaged around the clock by Coinbase engineers with the relevant domain expertise. The program's full [security policies](https://hackerone.com/coinbase?view_policy=true) describe scope, eligibility, and reward details.
2. [**Cantina**](https://cantina.xyz/bounties/55316f42-3c5e-4746-9bd0-0f18dcbc344b) — for deployed smart contracts. The covered contracts are enumerated in the program's [Tier 0](https://cantina.xyz/code/55316f42-3c5e-4746-9bd0-0f18dcbc344b/overview?overviewTab=1&assetGroup=0) and [Tier 1](https://cantina.xyz/code/55316f42-3c5e-4746-9bd0-0f18dcbc344b/overview?overviewTab=1&assetGroup=1) scope guides.
For any other security-related question that does not fit either bounty program, reach the team at [security@coinbase.com](mailto:security@coinbase.com).
---
# Security Council for Base
Source: https://basehub.org/security/security-council/
Description: Composition, quorum rules, member criteria, and responsibilities of the Security Council that approves Base contract upgrades.
The Security Council for Base is the multi-party group of independent entities and individuals whose signatures are required to approve Base Chain contract upgrades.
## Purpose
Base's mission is to build a global onchain economy that increases innovation, creativity, and freedom. That mission is only possible on a decentralized platform. Base is therefore (1) built on Ethereum, the most secure and decentralized L1; (2) built in the [open](https://github.com/base/base); and (3) committed to a clear set of [Neutrality Principles](https://www.coinbase.com/blog/coinbases-neutrality-principles-for-base).
As part of the ongoing decentralization roadmap, Base launched [permissionless fault proofs](https://base.mirror.xyz/eOsedW4tm8MU5OhdGK107A9wsn-aU7MAb8f3edgX5Tk) in October 2024, [decentralized control of contract upgrades](https://base.mirror.xyz/tWDMlGp48fF0MeADcLQruUBq1Qxkou4O5x3ax8Rm3jA) via a Security Council in April 2025, and has now reached Stage 1 Decentralization.
Reaching **Stage 1** means Base offers stronger security guarantees and fewer trust assumptions. Builders gain infrastructure certainty (no surprise rule changes), and there is no single point of failure — anyone can participate in verifying and securing the network.
## Structure
**Composition and quorum**
Stage 1 Decentralization requires that the group approving Base Chain contract upgrades contain:
- at least 8 participants
- a ≥75% quorum
- a quorum-blocking group outside the main rollup operator (Base)
Upgrade authority sits behind a **2-of-2 multisig** — two separate parties that each have to sign off before a change can take effect:
- **CB Signers** — a 3-of-6 multisig run by Coinbase. The whole group resolves to one signature in the overall tally.
- **Security Council** — an 8-of-11 multisig whose members are the 11 independent entities and individuals listed below, drawn from a spread of geographic regions.
With the CB Signers collapsed to a single participant, the tally runs across 12 in total, 9 of which must approve any upgrade — the CB Signers plus a minimum of 8 council signatures. Neither party can move an upgrade on its own; both have to clear their own threshold first. This composition meets all of the requirements above.
**Member selection criteria**
- Representation across diverse geographic regions and international territories
- Strong alignment with [Base's mission and values](https://base.mirror.xyz/jjQnUq_UNTQOk7psnGBFOsShi7FlrRp8xevQUipG_Gk)
- Diverse organizations — each member represents a separate entity
- Proven track record in the Base and Ethereum ecosystem and good standing in upholding professional and ethical standards in the community
- Technical competency and good security practices — completed screening processes including background checks, with demonstrated ability to securely store and use sensitive key material
**Current roster**
This list stays current with membership. As of February 2026, the Security Council includes the following entities and individuals, based in the listed jurisdictions:
- [Entity] Aerodrome — signer based in Japan
- [Aerodrome](https://aerodrome.finance/) is a decentralized exchange on Base where users swap, earn rewards, and participate in the onchain economy.
- `0xa5959a39cA67b9fb473E4A3A898C611EEAc9CB73`
- [Entity] Moonwell — signer based in Brazil
- [Moonwell](https://moonwell.fi/) is a decentralized lending and borrowing platform built on Base.
- `0x21C7D1e6A81Daca071bA94839ab74C39A25f851F`
- [Entity] Blackbird — signer based in USA
- [Blackbird](https://www.blackbird.xyz/) is a loyalty and payments platform built specifically for the restaurant industry, powered by Base.
- `0xA5657B88A0130a626fcDd6aAA59522373438CdFE`
- [Entity] ChainSafe — signer based in Canada
- [ChainSafe](https://chainsafe.io/) is a blockchain R&D firm focused on decentralized infrastructure.
- `0x1C56A6d2A6Af643cea4E62e72B75B9bDe8d62e2B`
- [Entity] Talent Protocol — signer based in Portugal
- [Talent Protocol](https://app.talentprotocol.com/) brings professional reputation onchain to help Base builders showcase their skills and get the recognition they deserve.
- `0x5ff5C78ff194acc24C22DAaDdE4D639ebF18ACC6`
- [Entity] Moshicam — signer based in USA
- [Moshicam](https://moshi.cam/) is a community-based photo editing app built on Base.
- `0xa8ee754FD1d069fb4B5d652730A0ca5e07a3fb06`
- [Individual] Seneca — based in USA
- Seneca is the co-founder of [Rounds](https://rounds.wtf/), a social platform that has [powered](https://x.com/jessepollak/status/1781069700652523725) grant distribution to Base builders.
- `0x82C80F34C4b5c153dB76122a11AaD2F77C99E766`
- [Individual] Juan Suarez — based in USA
- Juan is an active member of the Base ecosystem and has advised a number of key Base projects. He is a former member of the Coinbase Legal Team.
- `0x99DB5BbA0db16e9aD05e3ff53310683CC3C971D2`
- [Individual] Toady Hawk — based in Canada
- [Toady Hawk](https://farcaster.xyz/toadyhawk.eth) is the founder of [Zero Rights Media](https://farcaster.xyz/zerorightsmedia), an open-source onchain media org on Base (producers of ZEROPOD), and [The Yellow Collective](https://farcaster.xyz/basedandyellow), an onchain culture club for artists and creators on Base.
- `0x0E8A99738a50D523871739c6d676554b0E34252f`
- [Individual] Roberto Bayardo — based in USA
- [Roberto Bayardo](https://farcaster.xyz/bayardo.eth) is an engineer at Commonware, building a framework for high-performance blockchains. He is a former core Base contributor.
- `0x18e982274f8C5B548D5aAc7aBef44D61504e1b3E`
- [Individual] Yele Bademosi — based in the UK
- [Yele Bademosi](https://x.com/YeleBademosi) is the co-founder of [Onboard](https://www.onboard.xyz/) and a longtime builder in the Base ecosystem, previously founding Bundle and investing in early-stage technology companies via Microtraction.
The individual representatives for each entity are not published, to protect personal privacy and improve security.
**Member terms**
The Security Council for Base operates on a staggered "cohort" model:
- Cohort 1 — current term lasts until October 2026
- Cohort 2 — current term lasts until January 2027
## Roles and responsibilities
**Review and approve changes**
- Members are notified of proposed upgrades and must verify, approve, and sign them.
- Members must verify, approve, and sign role changes (key rotations for lost devices, member rotations, and similar). Any key rotations are designed not to disrupt quorum or security.
**Maintain availability and lines of communication**
- Be reachable for scheduled signings, coordination calls, and emergencies.
- Coordinate with other members to resolve urgent issues.
**Preserve key security**
- Generate and store key material securely.
- Use the keys only for activities directly tied to the Security Council role (upgrades and ownership changes).
- Report any suspected loss of access or compromise immediately.
- Complete onchain safety and security training at the start of each term.
- Participate in periodic liveness checks by signing a message to confirm continued control of the key.
**Act in good faith**
- Avoid conflicts of interest and disclose any potential conflicts.
- Help remove or replace dysfunctional signers without compromising security.
## The future
The Security Council for Base is a meaningful step toward a more decentralized, resilient, and secure Base network. Distributing key responsibilities across trusted, independent participants — combined with permissionless fault proofs — reduces reliance on any single entity and strengthens guarantees for users, builders, and the broader ecosystem.
This is the start, not the end. As Base evolves, the Security Council's role will be progressively minimized, opening the path to even more trustless infrastructure beyond Stage 1 — Stage 2 — and broader community control.
The mission stays the same: build a global onchain economy that empowers innovation, creativity, and freedom on a foundation everyone can rely on.
Base is for everyone.
---
# Access Lists Specification
Source: https://basehub.org/specifications/access-lists/
Description: Flashblock-Level Access Lists (FAL) — adapting EIP-7928 for flashblock chains.
Flashblock-Level Access Lists (FAL) adapt [EIP-7928](https://eips.ethereum.org/EIPS/eip-7928) Block-Level Access Lists for chains that emit flashblocks, including Base. This specification defines their data structures, recording semantics, and validation rules.
:::note
The canonical source is [`docs/specs/access-lists.md`](https://github.com/base/base/blob/main/docs/specs/access-lists.md) in the base/base repository.
:::
## Abstract
FAL records every account and storage location accessed during flashblock execution, along with post-execution values. This enables parallel disk reads, parallel transaction validation, and state reconstruction without full re-execution.
## Motivation
Standard BAL (EIP-7928) targets L1 Ethereum where blocks are atomic units. Base produces **flashblocks** -- incremental sub-block deltas streamed at 200ms intervals. FAL adapts the access-list concept to this architecture by:
- Operating on incremental flashblock deltas rather than complete blocks.
- Handling OP Stack-specific transaction types (L1 attributes, L1-to-L2 deposits).
- Tracking three separate fee vaults instead of a single `COINBASE`.
- Omitting beacon chain features absent from the OP Stack (EIP-4895 withdrawals, EIP-4788 beacon root, EIP-7002/7251 validator operations).
## Key Differences from BAL
| Aspect | BAL (EIP-7928) | FAL |
|--------|----------------|-----|
| Unit of operation | Complete block | Flashblock delta (incremental) |
| Hash storage | Block header | Flashblock metadata |
| Fee recipient | Single `COINBASE` | Three OP Stack fee vaults |
| Transaction types | Standard + withdrawals | Standard + L1 attributes + L1-to-L2 deposits |
| Beacon chain features | Included | Omitted |
### OP Stack Fee Vaults
Instead of recording balance changes against `COINBASE`, FAL tracks three separate fee vault addresses:
| Vault | Address | Purpose |
|-------|---------|---------|
| Sequencer Fee Vault | `0x4200000000000000000000000000000000000011` | Priority fees |
| Base Fee Vault | `0x4200000000000000000000000000000000000019` | Base fees |
| L1 Fee Vault | `0x420000000000000000000000000000000000001a` | L1 data fees |
### L1 Attributes Transaction
The first transaction in each block (index 0) is the L1 attributes transaction. It updates the L1Block contract (`0x4200000000000000000000000000000000000015`) storage slots:
| Slot | Content |
|------|---------|
| 0 | L1 block number |
| 1 | L1 base fee |
| 2 | L1 timestamp |
| 3 | Batcher hash |
| 4 | Sequence number |
| 5 | Blob base fee |
| 6 | L1 block hash |
### L1-to-L2 User Deposits
L1-to-L2 deposits are treated as regular transactions with block access indices `1..n`. The FAL records sender and recipient addresses with their balance changes.
---
## Specification
### Data Structures
#### FlashblocksPayloadV1
```rust
pub struct FlashblocksPayloadV1 {
pub payload_id: PayloadId,
pub index: u64,
pub base: Option,
pub diff: ExecutionPayloadFlashblockDeltaV1,
pub metadata: Value, // Contains "flashblock_access_list"
}
```
#### FlashblockAccessList
```rust
pub struct FlashblockAccessList {
pub min_tx_index: u64, // Inclusive starting transaction index
pub max_tx_index: u64, // Exclusive ending transaction index
pub account_changes: Vec, // All account state changes
pub fal_hash: B256, // Keccak-256 of RLP-encoded changes
}
```
### RLP Data Structures
The following Python-style type aliases define the RLP encoding:
```python
Address = bytes # 20-byte Ethereum address
StorageKey = bytes # 32-byte storage slot key
StorageValue = bytes # 32-byte storage value
CodeData = bytes # Variable-length bytecode
BlockAccessIndex = uint16
Balance = uint256
Nonce = uint64
# Constants (OP Stack adapted)
MAX_TXS = 30_000
MAX_SLOTS = 300_000
MAX_ACCOUNTS = 300_000
MAX_CODE_SIZE = 24_576
MAX_CODE_CHANGES = 1
# Change structures
StorageChange = [BlockAccessIndex, StorageValue]
BalanceChange = [BlockAccessIndex, Balance]
NonceChange = [BlockAccessIndex, Nonce]
CodeChange = [BlockAccessIndex, CodeData]
SlotChanges = [StorageKey, List[StorageChange]]
AccountChanges = [
Address,
List[SlotChanges], # storage_changes
List[StorageKey], # storage_reads
List[BalanceChange], # balance_changes
List[NonceChange], # nonce_changes
List[CodeChange] # code_changes
]
FlashblockAccessList = List[AccountChanges]
```
### Scope and Inclusion Rules
The following must be included in the `FlashblockAccessList`:
- **Addresses with state changes** -- any account whose storage, balance, nonce, or code was modified.
- **Inspection targets** -- targets of `BALANCE`, `EXTCODESIZE`, `EXTCODECOPY`, `EXTCODEHASH`.
- **Call targets** -- targets of `CALL`, `CALLCODE`, `DELEGATECALL`, `STATICCALL`.
- **Creation targets** -- addresses produced by `CREATE` and `CREATE2`.
- **Transaction parties** -- senders and recipients of every transaction.
- **Fee vault addresses** -- all three OP Stack fee vaults listed above.
- **`SELFDESTRUCT` beneficiaries** -- addresses receiving self-destructed balances.
- **System contracts** -- L1Block contract (`0x4200...0015`) and EIP-2935 block hash contract.
- **L1-to-L2 deposit recipients** -- recipients of cross-chain deposits.
- **Precompiled contracts** -- when accessed during execution.
- **L1Block during L1 attributes execution** -- always included in the first flashblock.
Addresses without state changes must still appear with empty change lists.
### Ordering and Determinism
To ensure deterministic encoding:
- **Addresses** are sorted lexicographically (bytewise ascending).
- **Storage keys** are sorted lexicographically within each account.
- **Block access indices** are sorted in ascending order within each change list.
### BlockAccessIndex Assignment
| Index Value | Assigned To |
|-------------|-------------|
| `0` | Pre-execution system contracts and L1 attributes transaction (first flashblock only, where `min_tx_index = 0`). |
| `min_tx_index` ... `max_tx_index - 1` | Transactions within the flashblock, including L1-to-L2 deposits and regular transactions. |
| `n + 1` | Post-execution system contracts (final flashblock only). |
### Recording Semantics
#### Storage
**Writes** (recorded in `storage_changes`):
- Any value change where the post-execution value differs from the pre-execution value.
- Zeroing a slot (pre-execution value exists, post-execution value is zero).
**Reads** (recorded in `storage_reads`):
- `SLOAD` without a corresponding write.
- No-op writes where `SSTORE` is called but the post-execution value equals the pre-execution value.
#### Balance Changes
Post-transaction balances are recorded for:
- **Senders** -- after gas cost, transferred value, and L1 data fee are deducted (including gas refunds).
- **Recipients** -- only when transferred value is greater than zero.
- **Fee vaults** -- updated balance after each transaction.
- **`SELFDESTRUCT` / `SENDALL` beneficiaries** -- balance after receiving funds.
- **Deposit recipients** -- balance after the deposit is credited.
For zero-value transfers, the address is included but omitted from `balance_changes`.
#### Code Changes
Post-transaction runtime bytecode is recorded for:
- Contracts deployed via `CREATE` or `CREATE2`.
- Contracts modified via `SELFDESTRUCT` (if applicable).
- EIP-7702 delegation indicators.
#### Nonce Changes
Post-transaction nonces are recorded for:
- EOA senders (incremented by transaction execution).
- Successful `CREATE` performers (nonce incremented).
- Newly deployed contracts (nonce set to 1).
- EIP-7702 authorities (nonce incremented on successful delegation).
### OP Stack Edge Cases
- **Precompiles**: Include when accessed. Record a balance change if the precompile receives value.
- **`SENDALL`**: Record both sender (balance to zero) and beneficiary (balance increased).
- **`SELFDESTRUCT`**: Include without nonce/code changes. Record balance-to-zero if pre-transaction balance was positive. Include storage reads.
- **Gas refunds**: The final sender balance (after refunds) is the recorded value.
- **Exceptional halts (reverts/out-of-gas)**: Record the final nonce and balance of the sender and fee vaults. Include all accessed addresses even if execution was reverted.
- **EIP-7702**: The authority address must be included with nonce/code changes after a successful delegation operation, and with empty changes if the delegation fails.
### Empty State
When no state changes exist in a flashblock:
- `account_changes` is an empty list.
- `fal_hash` equals the Keccak-256 of an empty RLP list: `0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347`.
### Validation
The following pseudocode describes FAL validation:
```python
def validate_fal(flashblock, provided_fal):
# 1. Extract the FAL from flashblock metadata
fal = extract_fal(flashblock.metadata)
# 2. Verify the provided hash matches the encoded account_changes
encoded = rlp_encode(fal.account_changes)
expected_hash = keccak256(encoded)
assert fal.fal_hash == expected_hash, "FAL hash mismatch"
# 3. Execute the flashblock and collect actual accesses
actual_accesses = execute_flashblock(flashblock)
actual_encoded = rlp_encode(actual_accesses)
actual_hash = keccak256(actual_encoded)
# 4. Verify actual execution matches the provided FAL
assert actual_hash == fal.fal_hash, "Execution mismatch"
return True
```
---
## Performance
FAL enables the following optimizations:
- **Parallel disk reads** -- storage slots and account data can be prefetched across transactions.
- **Parallel transaction validation** -- independent transactions can be validated concurrently.
- **State reconstruction without execution** -- post-state can be derived from the access list alone.
- **Compact representation** -- expected size is approximately 40--50 KiB compressed on average, comparable to BAL.
## Source
Canonical specification: [docs/specs/access-lists.md](https://github.com/base/base/blob/main/docs/specs/access-lists.md)
---
# Azul Execution Engine
Source: https://basehub.org/specifications/azul-exec-engine/
Description: Execution-engine changes in the Azul hardfork — the EIP-7825 transaction gas cap, Osaka-era EVM and precompile updates, eth/69 networking, a slimmed Flashblocks payload, and the eth_config RPC method.
import { Aside } from '@astrojs/starlight/components';
Azul layers a batch of Osaka-era execution rules onto Base while keeping the chain in lockstep with L1 pricing and behavior. The changes fall into three buckets: EVM-level adjustments (a per-transaction gas cap, MODEXP limits, a new opcode, and precompile repricing), networking updates (the eth/69 wire protocol and a leaner Flashblocks message), and RPC additions (a fixed Engine API method set and the new `eth_config` endpoint).
## EVM Changes
### Transaction Gas Limit Cap
[EIP-7825](https://eips.ethereum.org/EIPS/eip-7825) sets a protocol-enforced ceiling of 16,777,216
(2^24) gas on any single transaction. Anything asking for more than that is turned away at validation
time. Base matches the L1 ceiling so the two layers stay equivalent.
### Upper-Bound MODEXP
[EIP-7823](https://eips.ethereum.org/EIPS/eip-7823) limits each MODEXP precompile input field to at
most 1024 bytes; calls that exceed that size are rejected.
### MODEXP Gas Cost Increase
[EIP-7883](https://eips.ethereum.org/EIPS/eip-7883) lifts the MODEXP precompile floor from 200 to 500
gas and triples the result of the general cost formula.
### CLZ Opcode
[EIP-7939](https://eips.ethereum.org/EIPS/eip-7939) adds the `CLZ` opcode, which counts the leading
zero bits in a 256-bit word and returns 256 when the input is zero.
### secp256r1 Precompile Gas Cost
[EIP-7951](https://eips.ethereum.org/EIPS/eip-7951) places the secp256r1 precompile at address `0x100`
with a gas cost of 3,450.
Base has shipped this functionality since Fjord, where the `p256Verify` precompile was added at the
same `0x100` address via [RIP-7212](https://github.com/ethereum/RIPs/blob/master/RIPS/rip-7212.md),
also priced at 3,450 gas. Starting with Azul the cost rises to 6,900 to match the L1 figure in
EIP-7951, keeping Base's precompile pricing strictly aligned with Ethereum.
## Networking Changes
### eth/69
[EIP-7642](https://eips.ethereum.org/EIPS/eip-7642) bumps the Ethereum wire protocol to version 69. It
strips legacy fields out of the `Status` message and streamlines the handshake.
### Discovery protocol now uses `basev0` protocol ID
The execution-layer discovery protocol now advertises `basev0` as its protocol ID. Scoping discovery
this way lets Base nodes locate one another faster, which matters most on smaller networks such as
Sepolia where peers are scarcer.
### Remove Account Balances & Receipts
Azul trims the `FlashblocksMetadata` payload sent over the Flashblocks WebSocket. The
`new_account_balances` and `receipts` fields are dropped. The `access_list` field stays in the schema
but is left unpopulated in Azul.
**Before:**
```json
{
"block_number": 43403718,
"new_account_balances": {
"0x4200000000000000000000000000000000000006": "0x35277a9715c6df1c99de"
},
"receipts": {
"0x1ef9be45b3f7d44de9d98767ddb7c0e330b21777b67a3c79d469be9ffab091dd": {
"cumulativeGasUsed": "0x177d7bd",
"logs": [],
"status": "0x1",
"type": "0x2"
}
},
"access_list": null
}
```
**After:**
```json
{
"block_number": 43403718,
"access_list": null
}
```
## RPC Changes
### Engine API Usage
From Azul activation onward, block production and import flow through a fixed set of Engine API
methods:
- `engine_forkchoiceUpdatedV3` to kick off block builds and synchronize forkchoice.
- `engine_getPayloadV5` to retrieve built payloads.
- `engine_newPayloadV4` to import payloads into the execution engine.
`engine_getPayloadV5` hands back a V5 envelope, but the execution payload inside it keeps its V4 shape.
Because of that, payloads are still inserted through `engine_newPayloadV4` — Base Azul clients never use
an `engine_newPayloadV5` path.
The flow operates under these Azul constraints:
- Blob-related Engine API inputs are pinned to empty values:
- `expectedBlobVersionedHashes` MUST be an empty array.
- `blobsBundle` in `engine_getPayloadV5` responses is expected to be empty.
- `executionRequests` in `engine_newPayloadV4` MUST be an empty array.
### eth_config RPC Method
[EIP-7910](https://eips.ethereum.org/EIPS/eip-7910) adds the `eth_config` JSON-RPC method, a way to
surface a chain's configuration — fork activation timestamps among other parameters. Base Azul answers
`eth_config` calls with the standard EIP-7910 response schema, subject to a few Base-specific details:
- `blobSchedule` always comes back with `current`, `next`, and `last` zeroed out. Since Base carries no
native blob transactions, it deliberately avoids reporting Ethereum's synthetic blob-schedule defaults.
- `precompiles` lists the active EVM precompile set for that fork — the standard Ethereum precompiles
plus any Base-specific additions.
- `systemContracts` only contains entries representable under EIP-7910. On Base that means:
- `BEACON_ROOTS_ADDRESS` appears once Ecotone is active.
- `HISTORY_STORAGE_ADDRESS` appears once Isthmus is active.
- `DEPOSIT_CONTRACT_ADDRESS`, `CONSOLIDATION_REQUEST_PREDEPLOY_ADDRESS`, and
`WITHDRAWAL_REQUEST_PREDEPLOY_ADDRESS` are omitted.
Base-specific predeploys and the other OP Stack system contracts are not serialized into `eth_config`
unless the EIP-7910 schema covers them.
---
# Azul Upgrade Overview
Source: https://basehub.org/specifications/azul-overview/
Description: Summary of the Azul hardfork — Osaka EVM features, a streamlined Flashblocks websocket format, and a multi-proof system for L2 checkpoints.
import { Aside } from '@astrojs/starlight/components';
Azul is the first Base-specific hardfork. It folds Osaka-era EVM changes onto the Base execution layer, trims the Flashblocks websocket payload, and turns on a multi-proof system that shortens withdrawal latency and lays the groundwork for stronger decentralization. It also drops support for non-Base clients.
## What Azul ships
- Osaka EVM support on Base.
- A simplified Flashblocks websocket message format.
- A multi-proof system that unlocks faster withdrawals and a credible path toward decentralization.
- Base-native clients (`base-reth-node` + `base-consensus`) as the only supported stack.
## Activation timestamps
| Network | Activation timestamp |
|---------|----------------------|
| `mainnet` | `1779991200` (2026-05-28 18:00:00 UTC) |
| `sepolia` | `1776708000` (2026-04-20 18:00:00 UTC) |
Both timestamps are now confirmed: Azul shipped to Sepolia first and activated on mainnet on 2026-05-28. Operators who have not yet moved to the Base-native stack should follow the [Azul node upgrade guide](/node-operations/azul-node-upgrade/) to stay on the chain.
## Required software
| Layer | Software | Mainnet | Sepolia |
|-------|----------|---------|---------|
| Execution (EL) | `base-reth-node` | [v0.9.0+](https://github.com/base/base/releases/tag/v0.9.0) | [v0.7.0+](https://github.com/base/base/releases/tag/v0.7.0) |
| Consensus (CL) | `base-consensus` | [v0.9.0+](https://github.com/base/base/releases/tag/v0.9.0) | [v0.7.0+](https://github.com/base/base/releases/tag/v0.7.0) |
| - | `base/node` | [v0.16.0+](https://github.com/base/node/releases/tag/v0.16.0) | [v0.15.0+](https://github.com/base/node/releases/tag/v0.15.0) |
## Execution layer changes
The [Azul execution engine](/specifications/azul-exec-engine/) page covers each of these in full; the list below links straight to the relevant section:
- [EIP-7823: Upper-Bound MODEXP](/specifications/azul-exec-engine/#upper-bound-modexp)
- [EIP-7825: Transaction Gas Limit Cap](/specifications/azul-exec-engine/#transaction-gas-limit-cap)
- [EIP-7883: MODEXP Gas Cost Increase](/specifications/azul-exec-engine/#modexp-gas-cost-increase)
- [EIP-7939: CLZ Opcode](/specifications/azul-exec-engine/#clz-opcode)
- [EIP-7951: secp256r1 Precompile](/specifications/azul-exec-engine/#secp256r1-precompile-gas-cost)
- [EIP-7642: eth/69](/specifications/azul-exec-engine/#eth69)
- [EIP-7910: eth_config RPC Method](/specifications/azul-exec-engine/#eth_config-rpc-method)
- [Remove Account Balances & Receipts](/specifications/azul-exec-engine/#remove-account-balances--receipts)
- [Discovery protocol now uses `basev0`](/specifications/azul-exec-engine/#discovery-protocol-now-uses-basev0-protocol-id)
## Proof system
Azul introduces the components that make multi-proof withdrawals possible. The [Azul proof system](/specifications/azul-proofs/) page covers the design in full — the `AggregateVerifier` dispute game, the TEE and ZK proof paths, and the finality windows. The individual roles are documented separately:
- [Azul proof system](/specifications/azul-proofs/) — AggregateVerifier, finality model, and why the proof system changed
- [Proposer](/specifications/proposer/)
- [Challenger](/specifications/challenger/)
- [TEE provers](/specifications/tee-prover/)
- [ZK provers](/specifications/zk-prover/)
- [Prover registrar](/specifications/registrar/)
- [Proof contracts](/specifications/contracts/)
---
# Azul Proof System
Source: https://basehub.org/specifications/azul-proofs/
Description: Specification of the Azul multi-proof design — the AggregateVerifier dispute game, TEE and ZK proof paths, and the finality windows that govern L2 checkpoint withdrawals.
import { Aside } from '@astrojs/starlight/components';
Azul moves Base from a single-proof checkpoint model to a multi-proof one. A checkpoint is a fixed interval of L2 blocks reduced to a single output root, and every proposal about that checkpoint is filed against `AggregateVerifier` — an L1 dispute game that can accept one or two independent proofs for the same claimed root before any withdrawal is allowed to depend on it.
The common case is driven by a TEE prover, which produces the first proof attached to a proposal. A permissionless ZK prover can subsequently reinforce the same proposal or dispute one that is wrong. `AggregateVerifier` hands each proof off to a dedicated verifier contract and combines the results, while a prover registrar keeps the onchain list of trusted TEE signer identities current.
## Why the proof system changed
The pre-Azul fault-proof system is optimistic and interactive: a proposal stands unless someone steps in to challenge it. Two constraints follow from that design:
- Every withdrawal carries the full challenge window, so finalization takes at least 7 days.
- Each invalid proposal has to be actively disputed. If challengers lack the funds to contest every bad game, an incorrect state can slip through to finality. Centralized guardrails patch that gap today, but they are not a durable answer for Stage 2 decentralization.
Azul swaps that model for a multi-proof design anchored on TEE and ZK provers. TEE proofs carry the common path, ZK proofs serve as a permissionless backstop, and the structure leaves room to layer in stronger proving systems later.
## Finality model
A proposal on Ethereum can settle along three paths depending on which proofs are present:
| Proofs present | Settlement path | Target window | What it means |
| -------------- | --------------- | ------------- | ---------------------------------------- |
| TEE only | Long window | 7 days | Common path, still overridable by ZK |
| ZK only | Long window | 7 days | Permissionless path without TEE reliance |
| TEE + ZK | Short window | 1 day | Faster finality when both systems agree |
The long window exists so independent provers have time to recheck a claim and dispute it. The short window opens only when both proof systems endorse the same proposal. A ZK prover may also overturn an invalid TEE-backed claim and collect the TEE prover's bond as a reward.
In Azul that delay is held inside `AggregateVerifier` itself. `OptimismPortal2` and `AnchorStateRegistry` no longer impose their own separate 3.5 day delay — leaving either legacy delay in place would shut off the fast path even when both proofs are already present.
## Security and decentralization
- The TEE path is permissioned and tuned for the common case.
- The ZK path is permissionless and can override an invalid TEE-backed claim.
- The proof layer stays modular, so it can move toward stronger TEE implementations, alternate ZK systems, or multi-ZK designs over time.
## New and changed onchain components
- `AggregateVerifier` — Azul's dispute-game contract for checkpoint proposals. A proposal starts with one proof; a second proof for the same claimed root can be appended later. The contract invokes the proof-specific verifier contracts and aggregates their verdicts to decide how the proposal resolves. The Azul finality delay also lives here.
- `TEEVerifier` and `ZKVerifier` — the proof-specific verifier contracts that `AggregateVerifier` calls. Their addresses are immutable on the `AggregateVerifier` implementation, giving each deployment an explicit, fixed verifier set.
- `DelayedWETH` — still escrows the proposal bond for each game, but Azul cuts its withdrawal delay to 1 day. That is enough because the only bonds at risk here are proposer bonds.
- `OptimismPortal2` — no longer applies the separate 3.5 day proof-maturity delay to these proposals; that timing now sits in `AggregateVerifier` so the 1 day path stays reachable.
- `AnchorStateRegistry` — like `OptimismPortal2`, it drops the 3.5 day finalization delay for proposals, which is what makes fast finality possible.
## Proof flow
1. The proposer picks the next canonical checkpoint range and requests a TEE proof.
2. The TEE prover re-executes that L2 block range inside an AWS Nitro Enclave and signs the resulting output root.
3. The proposer checks the result against canonical Base L2 state and submits a new `AggregateVerifier` game to L1.
4. A challenger independently recomputes the same checkpoint roots and, on finding an invalid claim, obtains the ZK proof needed to dispute it.
The result keeps the normal path simple, preserves a permissionless dispute path, and enables faster settlement whenever both proof systems are available.
## Proof roles
- **Proposer** — converts canonical L2 checkpoints into new `AggregateVerifier` games on L1. See [Proposer](/specifications/proposer).
- **Challenger** — recomputes in-progress games against canonical L2 state and disputes incorrect claims. Anyone can run one; the permissionless dispute path is a ZK proof challenge. Base operates a challenger as a security backstop, with access to a TEE nullification path for invalid TEE-backed proposals. See [Challenger](/specifications/challenger).
- **TEE provers** — AWS Nitro Enclave-backed services used in the common proposal path. The host collects witness data from RPCs, the enclave re-executes the requested L2 block range in isolation, and it signs the resulting checkpoint outputs with a key that never leaves the enclave. See [TEE Prover](/specifications/tee-prover).
- **ZK provers** — the permissionless proving backend, used when a dispute requires a ZK proof — particularly to challenge an invalid TEE-backed proposal or invalidate a bad ZK claim. The proposer does not depend on them to create new games today; a future integration could let new roots carry both proof paths from the start, unlocking faster finality across the board. See [ZK Prover](/specifications/zk-prover).
- **Prover registrar** — keeps the onchain `TEEProverRegistry` aligned with the live set of Nitro prover signers: it discovers active provers, attests their signer identities onchain, and prunes orphaned signers with safeguards against transient outages. See [Registrar](/specifications/registrar).
- `AggregateVerifier` and its verifier contracts confirm claims before any L1 withdrawal can rely on them. See [Proof Contracts](/specifications/contracts).
---
# B20 Native Token Standard
Source: https://basehub.org/specifications/b20/
Description: Base's native token standard, serving creators of long-tail tokens, stablecoin issuers, and issuers of real-world assets (RWAs) and equities.
import { Aside } from '@astrojs/starlight/components';
B20 is Base's in-house take on [ERC-20](https://eips.ethereum.org/EIPS/eip-20). Compliance tooling is baked in from the start: role-based access control, transfer policies, supply caps, memos, and a freeze-and-seize path. The complete interface definitions live in the [Base Standard Library](https://github.com/base/base-std) repository.
This page describes how the standard behaves. For the hands-on path — install the toolchain, call the factory, mint, and verify — see [Launch a B20 Token](/integration-guides/launch-a-b20-token/).
Two variants are available:
| Variant | Decimals | Additional Features |
|---------|----------|---------------------|
| **Asset** | 6–18 (configurable) | Rebase multiplier, onchain announcements, batched issuance |
| **Stablecoin** | 6 (fixed) | Self-declared fiat currency code |
## ERC-20 compatibility
Rather than living as EVM smart contracts, B20 tokens run as **Rust precompiles**, which makes them faster, cheaper, and closer to the chain itself. Every token is deployed through the singleton B20Factory precompile.
Beyond that base surface, B20 layers on methods ERC-20 lacks: memos, mint/burn, policy gating, granular pause, and ERC-2612 `permit`. The containment runs one way only — anything ERC-20 defines is present on B20, but the additions don't flow back. Full ABIs are published as [interface definitions](https://github.com/base/base-std/tree/main/src/interfaces) in the Base Standard Library.
## Roles model
B20's access control builds on OpenZeppelin `AccessControl`, adding a fixed role set plus one behavioral tweak to how the admin role is renounced.
| Role | Gates |
|------|-------|
| `DEFAULT_ADMIN_ROLE` | All admin operations: role grants, policy updates, supply-cap changes |
| `MINT_ROLE` | `mint`, `mintWithMemo` |
| `BURN_ROLE` | Caller-side burns: `burn`, `burnWithMemo` |
| `BURN_BLOCKED_ROLE` | The deprecated third-party burn path: `burnBlocked` |
| `SEIZE_ROLE` | `seizeWithMemo` |
| `PAUSE_ROLE` | `pause` |
| `UNPAUSE_ROLE` | `unpause` |
| `METADATA_ROLE` | `updateName`, `updateSymbol`, `updateContractURI` |
You can define your own roles through `setRoleAdmin` and `grantRole`, but they carry no behavior on their own — only the eight base-surface roles listed above are actually gated. One more, `OPERATOR_ROLE`, is introduced by the Asset variant (see [Variants](#variants)).
### Admin renunciation
The final holder of `DEFAULT_ADMIN_ROLE` can't be dropped through `renounceRole` or `revokeRole`; both revert with `LastAdminCannotRenounce`. The only way to make a token permanently admin-less is the purpose-built `renounceLastAdmin()`.
Tokens meant to be admin-less from day one are created with `initialAdmin == address(0)`, which skips granting the role and bypasses the `renounceLastAdmin` step altogether.
Once `renounceLastAdmin()` has run (or for tokens deployed with `initialAdmin == address(0)`):
- Anything gated by `DEFAULT_ADMIN_ROLE` is permanently uncallable.
- Roles already held by other addresses (`MINT_ROLE`, `BURN_ROLE`, and so on) keep working on their own.
- The admin can't be resurrected: `grantRole`, `revokeRole`, and `setRoleAdmin` all revert with `AccessControlUnauthorizedAccount`, even for a caller holding a custom role.
## Policy registry
The PolicyRegistry is one singleton precompile holding allowlists and blocklists. B20 tokens point at policies by `uint64` ID, and anyone can create a policy and name its admin.
### Policy types
| Type | Value | Default | Behavior |
|------|-------|---------|----------|
| `BLOCKLIST` | `0` | Authorized | All accounts authorized by default; explicitly listed accounts are denied. |
| `ALLOWLIST` | `1` | Denied | All accounts denied by default; explicitly listed accounts are authorized. |
| `UNION` | `2` | Denied | Authorized when any child policy authorizes. Added at Cobalt. |
| `INTERSECT` | `3` | Authorized | Authorized only when every child policy authorizes. Added at Cobalt. |
The first two are simple policies: they hold a membership set of their own. The last two are composites, added at [Cobalt](/specifications/cobalt-overview/); they hold no members and instead reference 2 to 4 simple policies, which are evaluated live on each check. A composite's children must be simple, so evaluation never exceeds depth 1. The enum is append-only, so the two new values do not disturb the packed-ID encoding below. Call-level detail is in the [B20 precompile reference](/api-reference/b20-precompiles/).
### Policy IDs
A policy ID is a `uint64`. Its top byte holds the `PolicyType`; the remaining 56 bits are a global counter that begins at `2`, since `0` and `1` are reserved. Composites draw from that same counter rather than a separate one, so a policy ID is unique across all four types.
Two reserved IDs work without being created first:
| Constant | ID | Behavior |
|----------|----|----------|
| `ALWAYS_ALLOW` | `0` | Authorizes every account unconditionally. Default scope value on new B20 tokens. |
| `ALWAYS_BLOCK` | `(uint64(ALLOWLIST) << 56) \| 1` | Denies every account unconditionally. |
`isAuthorized` won't revert when handed a policy ID that doesn't exist. It reads whatever the ID points at and applies empty-set behavior, which each type resolves differently:
| Type | Nonexistent ID resolves to |
|------|----------------------------|
| `BLOCKLIST` | Authorizes everyone (nobody is listed as denied) |
| `ALLOWLIST` | Denies everyone (nobody is listed as allowed) |
| `UNION` | Denies everyone (no child authorizes) |
| `INTERSECT` | **Authorizes everyone** (no child declines) |
A malformed ID — one whose type byte exceeds `INTERSECT` — is treated as unauthorized rather than reverting. From Denim, the registry drops the invert flag (bit 63) before it reads the type byte. An inverted ID returns the opposite of its base when the base exists, and `false` when the base is unknown or malformed. A B20 token rejects any ID that does not exist in `updatePolicy`, so this empty-set behavior reaches only callers that query the registry with IDs they never checked. Store an ID only after `policyExists` confirms it.
From [Denim](/specifications/denim-overview/), bit 63 gains a meaning of its own: it inverts the policy. An ID with that bit set authorizes exactly the accounts its base rejects, and it reads as `false` when the base does not exist. `invertedPolicyId(policyId)` toggles the bit. Until Denim activates, the same ID is simply malformed and denies everyone, so a slot bound to one changes behaviour at the fork. The [precompile reference](/api-reference/b20-precompiles/#arriving-with-denim) has the details.
### Admin model
Every policy has exactly one admin, and transfers happen in two steps: the sitting admin calls `stageUpdateAdmin(policyId, newAdmin)`, then the nominee calls `finalizeUpdateAdmin(policyId)`. Calling `renounceAdmin(policyId)` freezes the policy for good — its membership can never change again.
### Creating and managing policies
```solidity
// Create a policy (admin first, then type)
uint64 policyId = policyRegistry.createPolicy(adminAddress, PolicyType.BLOCKLIST);
// Or seed the initial member set in one call:
// uint64 policyId = policyRegistry.createPolicyWithAccounts(adminAddress, PolicyType.BLOCKLIST, accounts);
// Update membership (batched). The setter is type-specific; the bool sets membership state.
policyRegistry.updateBlocklist(policyId, true, accounts); // block these accounts
policyRegistry.updateBlocklist(policyId, false, accounts); // unblock these accounts
// For ALLOWLIST policies: policyRegistry.updateAllowlist(policyId, allowed, accounts)
```
### Read interface
| Method | Description |
|--------|-------------|
| `isAuthorized(policyId, account)` | Whether `account` is authorized under `policyId`. Never reverts. |
| `policyExists(policyId)` | Whether a policy with this ID has been created. |
| `policyAdmin(policyId)` | Current admin address. |
| `pendingPolicyAdmin(policyId)` | Pending admin during a two-step transfer. |
## Policy integration
B20 exposes a fixed set of policy scopes, each holding a `uint64` policy ID into the PolicyRegistry. Each gated operation triggers an `isAuthorized` check on the matching scope; an unauthorized account makes the call revert with `PolicyForbids`.
| Scope | Gates |
|-------|-------|
| `TRANSFER_SENDER_POLICY` | The `from` of `transfer` / `transferFrom` |
| `TRANSFER_RECEIVER_POLICY` | The `to` of `transfer` / `transferFrom` |
| `TRANSFER_EXECUTOR_POLICY` | The `msg.sender` of `transferFrom`, when distinct from `from` (not checked on `transfer`). From Denim it checks the initiator of every transfer, `transfer` included |
| `MINT_RECEIVER_POLICY` | The `to` of `mint` |
| `SEIZE_EXEMPT_POLICY` | The `from` of `seizeWithMemo`. Note the inversion — a holder is only seizable while this scope *denies* them |
| `SEIZE_RECEIVER_POLICY` | The `to` of `seizeWithMemo`, which must be authorized |
Note that neither `approve` nor `permit` is policy-gated — only real balance movement through `transfer` / `transferFrom` is checked.
Scopes are read with `policyId(scope)` and set with `updatePolicy(scope, policyId)`. `updatePolicy` is admin-gated and reverts on an unrecognized scope.
## Mint
Fresh supply comes from `mint` / `mintWithMemo`, both gated by `MINT_ROLE`. The recipient is checked against `MINT_RECEIVER_POLICY`, and the call reverts with `SupplyCapExceeded` if it would carry `totalSupply` past the cap.
## Burn
There are two ways to burn:
- **`burn` / `burnWithMemo`** — a holder destroys supply from their own balance, gated by `BURN_ROLE`.
- **`burnBlocked`** — destroys supply held by a third party, gated by `BURN_BLOCKED_ROLE`. That account first has to be denied under `TRANSFER_SENDER_POLICY`.
## Seize
`seizeWithMemo(from, to, amount, memo)` is the current path for regulated issuers who need to move balance out of an account under compulsion. Rather than destroying the supply the way `burnBlocked` did, it reassigns it: the balance leaves `from` and lands on `to` in a single privileged step, emitting `Transfer`, `Memo`, and `Seized`.
The call answers to `SEIZE_ROLE`, and it deliberately bypasses both allowance and the ordinary transfer policies. In their place it applies two checks of its own, and the first one runs backwards from what you'd expect:
- `from` must be **denied** by `SEIZE_EXEMPT_POLICY`. Authorization here marks an account as protected, so only accounts the policy turns away can be seized from.
- `to` must be **authorized** by `SEIZE_RECEIVER_POLICY`, which keeps seized balance flowing only to destinations the issuer has sanctioned.
Missing either check reverts — `AccountNotSeizable` for the holder, `PolicyForbids` for the destination.
## Supply cap
Capping supply is opt-in. The sentinel `type(uint128).max` signals no cap, which is what a token starts with; it doubles as the highest permitted cap, so `totalSupply` can never climb past it. `updateSupplyCap(newCap)` is admin-gated and emits `SupplyCapUpdated`, reverting with `InvalidSupplyCap` if `newCap` falls beneath the current `totalSupply` or rises above `type(uint128).max`.
## Memos
A memo is an optional `bytes32` tag carried alongside an operation for off-chain reference. Any operation carrying one emits `Memo(address indexed caller, bytes32 indexed memo)` immediately after its primary event, and indexers join the two on `(transactionHash, logIndex − 1)`.
The memo-capable entrypoints are `transferWithMemo`, `transferFromWithMemo`, `mintWithMemo`, `burnWithMemo`, and `seizeWithMemo`.
## Pause
Pausing is fine-grained: the `PausableFeature` enum splits the token surface into operations that pause independently — `TRANSFER`, `MINT`, `BURN`, and `SEIZE`. That enum only ever grows. By design, `pause(features)` and `unpause(features)` answer to different roles (`PAUSE_ROLE` and `UNPAUSE_ROLE`), so you can hand out emergency-stop authority without also handing out the ability to lift it.
Each feature covers every entrypoint in its family, and a pause outranks a role — a `MINT_ROLE` holder still cannot mint while `MINT` is paused. The attempted call reverts with `ContractPaused(feature)`.
| Feature | Ordinal | Operations it stops |
|---|---|---|
| `TRANSFER` | 0 | `transfer`, `transferFrom`, and their memo variants |
| `MINT` | 1 | `mint`, `mintWithMemo`, and `batchMint` |
| `BURN` | 2 | `burn`, `burnWithMemo`, and the deprecated `burnBlocked` |
| `SEIZE` | 3 | `seizeWithMemo` |
Re-pausing a feature that is already paused is a no-op and does not revert, which keeps an emergency runbook safe to run twice. Read the whole current set in one call with `pausedFeatures()`. As a bitmask, `B20Constants.ALL_FEATURES_PAUSED` is `15` (`0b1111`), every feature bit set.
No feature covers `approve`. A fully paused token still accepts new allowances, and those become spendable the moment `TRANSFER` is lifted.
## ERC-2612 permit / EIP-712
B20 supports ERC-2612 signed approvals over an EIP-712 domain of `(name, version, chainId, verifyingContract)`, with `version` pinned to `"1"`. A `updateName` call rolls the domain separator and fires `EIP712DomainChanged` (ERC-5267). Only ECDSA signatures count — ERC-1271 contract signatures are rejected.
## Contract URI (ERC-7572)
`contractURI()` hands back a string pointing at off-chain metadata in the ERC-7572 style. `updateContractURI(newUri)` is gated by `METADATA_ROLE`.
## Metadata updates
`METADATA_ROLE` controls:
- `updateName(newName)` — changes `name` and cycles the EIP-712 domain separator, emitting `NameUpdated` alongside `EIP712DomainChanged`.
- `updateSymbol(newSymbol)` — changes only `symbol`. Emits `SymbolUpdated`.
## Factory
Every B20 token is minted through the singleton B20Factory precompile via `createB20(variant, salt, params, initCalls)`. Within `base-std` the factory is reachable as `StdPrecompiles.B20_FACTORY`.
| Parameter | Description |
|-----------|-------------|
| `variant` | `ASSET` or `STABLECOIN` |
| `salt` | Caller-chosen entropy for address derivation |
| `params` | ABI-encoded, variant-specific creation struct (versioned by leading byte) |
| `initCalls` | Optional array of ABI-encoded calls dispatched post-creation; calls originating from the factory bypass role gates and transfer-side policy gates during this window |
If the chain has not yet switched on the feature backing the requested variant, `createB20` reverts with `IActivationRegistry.FeatureNotActivated`.
### Address derivation
A B20 address is deterministic and carries its variant inline:
```text
[10-byte B20 prefix][1-byte variant][9-byte keccak256(deployer, salt)]
```
Because the variant lives in the address, it's recoverable without an RPC call — read byte 10 (zero-indexed) to learn the token type. The factory also exposes `getB20Address(variant, deployer, salt)`, `isB20(addr)`, and `isB20Initialized(addr)`.
### initCalls semantics
`initCalls` run after creation. While this bootstrap window is open, anything the factory dispatches skips two enforcement layers at once: the token's role checks, plus the sender/receiver/executor transfer policies (`TRANSFER_SENDER_POLICY`, `TRANSFER_RECEIVER_POLICY`, `TRANSFER_EXECUTOR_POLICY`) — letting a deployer apply admin-gated setup (policies, role grants) and seed opening balances all inside the deploy transaction. That relaxation is deliberately partial:
- `MINT_RECEIVER_POLICY` is enforced even inside `initCalls`.
- Pause state is never bypassed.
- Token invariants (the supply cap and so on) are never bypassed.
## Variants
Each variant has a 1-byte identifier written directly into the token's address (see [Address derivation](#address-derivation)):
| Variant | Byte |
|---------|------|
| `ASSET` | `0x00` |
| `STABLECOIN` | `0x01` |
### Asset
The general-purpose variant, suitable for any kind of asset. Decimals are chosen between 6 and 18 at deployment and locked thereafter.
On top of everything in the base surface, the Asset variant layers on extra capabilities. The newly added `OPERATOR_ROLE` guards the multiplier and announcements, while batch mint stays under `MINT_ROLE` and extra metadata under `METADATA_ROLE`.
#### Multiplier
A WAD-precision rebase multiplier applied across all balance reads. Stored balances stay as-is; the multiplier only scales the value callers see.
| Method | Description |
|--------|-------------|
| `multiplier()` | Current WAD-precision multiplier |
| `scaledBalanceOf(account)` | Raw balance × multiplier |
| `toScaledBalance(raw)` | Convert raw amount to scaled |
| `toRawBalance(scaled)` | Convert scaled amount to raw |
| `updateUIMultiplier(newMultiplier, effectiveAt)` | Queue a change to take effect at a future timestamp ([ERC-8056](https://eips.ethereum.org/EIPS/eip-8056)). The preferred path. Gated by `OPERATOR_ROLE`. |
| `cancelUIMultiplierUpdate()` | Drop the pending scheduled change. Gated by `OPERATOR_ROLE`. |
| `updateMultiplier(newMultiplier)` | Set the multiplier immediately, discarding any pending scheduled change. Deprecated. Gated by `OPERATOR_ROLE`. |
Scheduling is what issuers should reach for day to day: it puts the change onchain ahead of time, so holders and integrators see a corporate action coming rather than discovering it after the fact. The instant call survives as an emergency failsafe and nothing more. Neither path carries a timelock of its own — the announcement events are notice, not enforced delay — so any waiting period is something the issuer imposes above the standard.
For a worked example of multipliers under real corporate actions, see [Tokenized Stocks](/integration-guides/tokenized-stocks/).
#### Announcements
A way to bracket sensitive operations (batch mints, multiplier changes) inside a publicly visible disclosure window, gated by `OPERATOR_ROLE`.
`announce(internalCalls, id, description, uri)` emits an `Announcement` event, runs `internalCalls`, then emits `EndAnnouncement`. The `id` has to be unique and is enforced forever, and any inner-call revert is wrapped in `InternalCallFailed`.
#### Batch mint
`batchMint(recipients, amounts)` mints to several recipients at once, gated by `MINT_ROLE`. It should be wrapped in `announce()` for transparency.
#### Extra metadata
An open-ended store of issuer-set on-chain metadata, addressed by key.
| Method | Description |
|--------|-------------|
| `extraMetadata(key)` | Read a value by key |
| `updateExtraMetadata(key, value)` | Write a value. Gated by `METADATA_ROLE`. Setting an empty value removes the entry. |
### Stablecoin
A fiat-backed carveout with locked decimals. The decimal count is fixed at `6` and isn't configurable.
It adds `currency()`, returning an ISO-style currency code (`"USD"`, `"EUR"`, and the like). That code is set once at creation through `B20StablecoinCreateParams.currency`, limited to the characters `A`-`Z`. It's self-declared and isn't checked against any outside registry.
## Precompile addresses
The supporting precompiles sit at the same fixed addresses on every network where B20 is live — Mainnet, Base Sepolia, Vibenet, and a local `base-anvil` instance alike.
| Precompile | Address |
|---|---|
| [B20Factory](#factory) | `0xB20f000000000000000000000000000000000000` |
| Activation Registry | `0x8453000000000000000000000000000000000001` |
| [Policy registry](#policy-registry) | `0x8453000000000000000000000000000000000002` |
## How B20 executes
None of this is Solidity. The factory, both registries, and every token are precompiles: native code inside the node, sitting at reserved addresses. On each `CALL`, `STATICCALL`, or related opcode, the EVM consults its precompile table before loading bytecode. If the target is registered, native code runs and no bytecode is ever read. It is the same table that holds `ecrecover` and `sha256`. B20 adds entries to it rather than routing around it.
The difference from those classic precompiles is state. B20 is the first stateful precompile on Base. Each one keeps storage and emits real logs, and it writes that storage into the ordinary account slots at its own address. There is no side database, so `eth_getStorageAt` on a token address returns exactly what a `transfer` wrote.
Without an interpreter in the path, the native code does its own gas metering. It charges calldata, `SLOAD`, `SSTORE`, and logs at the prices those opcodes would cost, and it fails the ways a contract fails: out of gas, revert, or a custom error. A revert unwinds state exactly like a contract revert.
The three singletons live in the node's static table. Tokens cannot, because they are created at runtime. The node recognises a token address by decoding its prefix and variant byte instead (see [Address derivation](#address-derivation)).
### Versions are frozen per fork
Changing B20 behaviour takes a hardfork. A fork can add a precompile, or ship a new logic version for an existing address. The address stays the same; what changes is which native implementation answers it after activation.
Old versions are never edited. Each fork maps to one frozen implementation, and the node resolves that mapping on every call. A Beryl block always runs Beryl logic, even on a node that also knows Cobalt, and that is what lets a node syncing from genesis reach the same state as one that has run all along. If no version resolves for the active fork, the call reverts. There is no fallback to whatever is newest.
Two practical consequences:
- **Before a precompile's first fork**, its address holds no bytecode and no table entry, so it behaves like an empty account. A raw call to it succeeds and returns no data, which a caller expecting a return value will fail to decode. Tooling that checks for code at the target rejects it outright.
- **Before a new selector's fork**, the precompile already exists but its active version does not know the selector, so the call reverts. `invertedPolicyId` before [Denim](/api-reference/b20-precompiles/#arriving-with-denim) is a live example.
## Roadmap
Running in Rust beyond the EVM gives the node unusually deep control over how B20 tokens behave. The following capabilities are slated for later upgrades.
### Frontier features
- **Pay transaction fees with B20** — cover gas with a custom asset alone, holding no ETH at all.
- **Virtual addresses** — mint one-off deposit addresses that funnel into a single shared account.
- **Indexed data** — pull balances, transfer history, and token metadata straight from Base Node RPCs in aggregated form, with no external indexer in the loop.
### Performance optimizations
- **Lower fees** — transfers roughly 50% cheaper than an ERC-20 contract.
- **Higher throughput** — about 2× the transfers per block versus an ERC-20 contract.
More tuning is planned specifically for trading and payment workloads.
---
# Base Transactions (EIP-8430)
Source: https://basehub.org/specifications/base-transactions/
Description: Reference for Base Transactions, the type 0x79 transaction from EIP-8430 that Everest adds. It covers batched call phases, gas sponsorship, token gas payments, parallel and nonce-free nonces, and code delegation.
import { Aside } from '@astrojs/starlight/components';
Base Transactions are a new [EIP-2718](https://eips.ethereum.org/EIPS/eip-2718) typed transaction, specified in [EIP-8430](https://github.com/ethereum/EIPs/pull/12385). They give an ordinary EOA, with its existing secp256k1 key, the features that used to need a smart account and a bundler. One transaction can:
- **Batch calls** into atomic phases, and each call can carry its own native value.
- **Use a sponsor** that pays gas, with no paymaster contract.
- **Pay for gas in a token** by paying back a sponsor inside the same transaction (see [Token gas payments](#token-gas-payments)).
- **Run in parallel** on separate nonce lanes, or with no nonce at all.
- **Set code delegation** in the style of [EIP-7702](https://eips.ethereum.org/EIPS/eip-7702).
Validation has a fixed cost. A node checks one secp256k1 signature for each role, and then the nonce, the balance, and the validity window. It never runs wallet code to decide if a transaction is valid. So there are no bundlers, no relays, and no second mempool.
EIP-8430 was split out of [EIP-8130](/architecture/native-account-abstraction/). It keeps the transaction type and drops the onchain actor and authenticator model. Upstream replaced its EIP-8130 spec page with this one on 2026-10-13.
## Transaction format
The type byte is `0x79`:
```text
0x79 || rlp([
chain_id,
sender, // empty = recover from sender_auth | 20-byte address
nonce_key, // uint256: nonce channel selector
nonce_sequence, // uint64: sequence number
valid_after, // uint64: Unix timestamp (ms or s); 0 = no lower bound
valid_before, // uint64: Unix timestamp (ms or s); 0 = no expiry
max_priority_fee_per_gas,
max_fee_per_gas,
gas_limit,
account_changes, // typed entries | empty
calls, // [[call, ...], ...] | empty
metadata, // opaque attribution/annotation bytes | empty
payer, // empty = self-pay | 0x00 = open | 20-byte payer address
sender_auth,
payer_auth
])
call = rlp([to, value, data])
```
| Field | What it does |
|---|---|
| `chain_id` | The [EIP-155](https://eips.ethereum.org/EIPS/eip-155) chain ID. |
| `sender` | Leave it empty and the node recovers the sender from `sender_auth`. Or give a 20-byte address. |
| `nonce_key` | Picks the nonce channel. `0` is the account nonce. `1` through `2^256 - 2` are parallel channels. `2^256 - 1` turns nonces off. See [Nonces](#nonces). |
| `nonce_sequence` | The sequence number the sender expects in that channel. It goes up when the transaction is included, even if execution fails. It must be `0` when nonces are off. |
| `valid_after` | The earliest time the transaction is valid. `0` sets no lower limit. |
| `valid_before` | The latest time the transaction is valid. `0` sets no expiry. You must set it when nonces are off. |
| `max_priority_fee_per_gas`, `max_fee_per_gas` | [EIP-1559](https://eips.ethereum.org/EIPS/eip-1559) fee limits. |
| `gas_limit` | Gas for the sender's intrinsic cost and for the calls. Payer authentication is paid for separately. |
| `account_changes` | Typed state changes that run before the calls. See [Code delegation](#code-delegation). |
| `calls` | The phases of calls, in order. See [Call phases](#call-phases). |
| `metadata` | Free-form bytes, for example builder or app attribution or a payment reference. Both signatures cover them and they cost payload gas, but validation and execution ignore them. |
| `payer` | Who pays for gas. See [Payers](#payers). |
| `sender_auth` | The sender's authorization. See [Authentication](#authentication). |
| `payer_auth` | The payer's authorization. Empty when the sender pays. |
The two time fields take seconds or milliseconds. A value below `100_000_000_000` counts as seconds, and the node multiplies it by 1,000. A larger value counts as milliseconds. Every window check compares the result with `block.timestamp * 1000`.
## Authentication
One rule covers both `sender_auth` and `payer_auth`:
- If the identity is **recovered**, the blob is a plain 65-byte ECDSA signature, `r || s || v`.
- If the identity is **named** by a 20-byte address, the blob is a 20-byte authenticator selector and then the signature.
| `sender` | `sender_auth` | Sender used |
|---|---|---|
| Empty | `r \|\| s \|\| v` (65 bytes) | The address recovered from the sender signature hash |
| 20-byte address | `address(1) \|\| r \|\| s \|\| v` | `sender`. The recovered address must match it. |
`address(1)` selects native secp256k1. It is the only selector the protocol accepts, and any other selector or blob length makes the transaction invalid. Passkeys (P-256 and WebAuthn) are not part of this type.
The sender and the payer sign separate hashes, so one signature can never stand in for the other. Both hashes cover every field up to and including `payer`, and leave out `sender_auth` and `payer_auth`:
```text
sender_hash = keccak256(0x79 || rlp([chain_id, sender, nonce_key, nonce_sequence,
valid_after, valid_before, max_priority_fee_per_gas, max_fee_per_gas, gas_limit,
account_changes, calls, metadata, payer]))
payer_hash = keccak256(0x7A || rlp([chain_id, resolved_sender, nonce_key, nonce_sequence,
valid_after, valid_before, max_priority_fee_per_gas, max_fee_per_gas, gas_limit,
account_changes, calls, metadata, payer]))
```
The payer hash always puts in the resolved sender address, even if `sender` is empty in the encoded transaction. A payer signature is therefore tied to one sender. Another account cannot copy the same transaction body and reuse it.
## Payers
| `payer` | `payer_auth` | Mode | Payer used |
|---|---|---|---|
| Empty | Empty | Self-pay | `sender` |
| `0x00` | `r \|\| s \|\| v` (65 bytes) | Open | The address recovered from the payer signature hash |
| `sender` | `address(1) \|\| r \|\| s \|\| v` | Explicit self-pay | `sender` |
| Any other address | `address(1) \|\| r \|\| s \|\| v` | Sponsored | `payer`. The recovered address must match it. |
**Sponsored** mode locks the transaction to one named payer. **Open** mode names no payer, and any key that agrees to pay can sign the payer hash. While an open transaction waits in the pool, a third party can add its own `payer_auth` and send it again as a replacement. That replacement must still meet the minimum fee bump, and the payer is the only thing it changes.
The most a payer can spend is `max_fee_per_gas * effective_gas_limit`. `payer_auth` is metered outside `gas_limit`, so a payer cannot use up the sender's call gas through its choice of authorization.
A contract can read the resolved payer from the Transaction Context precompile (see [Precompiles](#precompiles)). For example, a sponsor's payment contract in phase 0 can check that the sponsor really is the one paying.
### Token gas payments
To pay for gas in a token, the sender sets a sponsor as `payer`. The first phase of `calls` sends the token to that sponsor, and the user's own actions go in later phases. The sponsor pays the gas in ETH. Phase 0 commits even if a later phase reverts, so the sponsor gets its token in all cases.
## Nonces
| `nonce_key` | Mode | How it works |
|---|---|---|
| `0` | Standard | The account nonce, shared with every other transaction type. |
| `1` through `2^256 - 2` | Parallel | Separate sequential channels, kept by the Nonce Manager precompile. Each one is its own lane. |
| `2^256 - 1` | Nonce-free | No nonce is read or changed. `nonce_sequence` must be `0` and `valid_before` must be set. |
A nonce-free transaction gets its replay protection from a `replay_id`:
```text
replay_id = keccak256(0x7901 || rlp([chain_id, resolved_sender, valid_after, valid_before,
account_changes, calls, metadata, payer]))
```
The chain keeps each `replay_id` in a ring buffer of fixed size and refuses any `replay_id` that is still in it. An entry expires after its `valid_before`, so this state does not grow forever. The chain also limits how far ahead `valid_before` can be.
The node source sets that limit. The onchain window is 30,000 ms. The txpool uses a smaller limit, `NONCE_FREE_MAX_EXPIRY_WINDOW` of `20_000` ms, so it never accepts a transaction that the block check would later refuse. A nonce-free transaction must therefore expire within about 20 seconds of when you send it.
`replay_id` does not cover the fee fields, `gas_limit`, or either authorization blob. A fee bump or a new signature keeps the same identity. Do not deduplicate nonce-free transactions by transaction hash, because the hash changes when the fees change.
### Replacement in the mempool
- **Standard and parallel:** a pending transaction replaces another one with the same `(sender, nonce_key, nonce_sequence)`. On `nonce_key` `0`, a pending transaction of a different type with the same account nonce can also be replaced.
- **Nonce-free:** a pending transaction replaces another one from the same sender with the same `replay_id`. A block cannot hold two transactions with the same `(sender, replay_id)`.
A replacement must raise both `max_fee_per_gas` and `max_priority_fee_per_gas` by at least the node's minimum bump. A sponsored replacement also needs a new `payer_auth`, because the payer signs the fee fields and `gas_limit`.
## Call phases
`calls` is a list of **phases**, and each phase is a list of calls. The protocol sends every call directly from the sender. So `msg.sender` and `tx.origin` are both `sender`, and `call.value` goes from the sender to `call.to`.
Each phase is all-or-nothing. If one call in it reverts, the node throws away that whole phase and skips every phase after it. Phases that finished before it stay in place.
| Pattern | `calls` |
|---|---|
| One call | `[[call]]` |
| Atomic batch | `[[call_a, call_b, call_c]]` |
| Sponsor payment, then user actions | `[[sponsor_payment], [action_a, action_b]]` |
## Code delegation
`account_changes` is a list of typed entries that run before the calls. Delegation (`0x01`) is the only entry type:
```text
rlp([0x01, target]) // target: contract to delegate to, or address(0) to clear
```
This entry sets EIP-7702-style delegation for the sender. `sender_auth` already authorizes it, so it needs no extra signature, and it uses the same nonce as the calls that run the new code.
- A transaction can hold one delegation entry at most.
- The sender must authenticate with native secp256k1, recovered or named with `address(1)`.
- The sender's code must be empty or an existing delegation indicator (`0xef0100 || address`). Other bytecode is never overwritten.
- A non-zero `target` sets the code to `0xef0100 || target`. `address(0)` removes it.
A Base Transaction never delegates an account on its own.
The node still knows two more entry types, `0x02` (account creation) and `0x03` (signed config batch). Source comments assign them to a Keystore integration that is valid only under Zenith, a test-only gate that no public network sets. They are not part of EIP-8430 and not part of Everest.
## Gas and fees
```text
intrinsic_gas = AA_BASE_COST + tx_payload_cost + nonce_key_cost + value_transfer_cost
+ account_changes_cost + sender_auth_cost + payer_auth_cost
effective_gas_limit = gas_limit + payer_gas_reserve
```
| Part | Cost |
|---|---|
| `AA_BASE_COST` | 15,000 |
| `tx_payload_cost` | 16 gas for each non-zero byte and 4 for each zero byte of the encoded transaction, not counting `payer_auth` |
| `nonce_key_cost` | 0 for key `0`. 22,100 the first time a parallel key is used, then 5,000. 13,000 when nonces are off. |
| `value_transfer_cost` | 6,000 for each call with `value > 0` and `to != sender` |
| `account_changes_cost` | 4,600 for a delegation entry |
| `sender_auth_cost` | 5,100 |
| `payer_auth_cost` | 0 for self-pay. Otherwise 5,100, plus payload cost for the bytes of `payer_auth`. |
`gas_limit` pays for the sender's intrinsic gas and for the calls. The payer pays for its own authentication on top of `gas_limit`, up to `MAX_AUTHENTICATION_GAS` (100,000 in the node). An [EIP-7623](https://eips.ethereum.org/EIPS/eip-7623)-style calldata floor applies to the whole transaction, `payer_auth` included.
Fees use EIP-1559 rules over `effective_gas_limit`. Before execution, the node takes `effective_gas_limit * effective_gas_price` from the payer. After execution, the payer pays for the gas used and gets the rest back. Gas for payer authentication is not refunded.
The node source shows how these numbers add up. `sender_auth_cost` is 3,000 for the `ECRECOVER` work plus one cold storage read (2,100). The 13,000 nonce-free charge is a fixed sum of storage costs for the replay buffer. For the precharge, the node prices the `payer_auth` bytes at the EIP-7623 floor rate. At settlement it uses the normal calldata rate, unless the floor applies to the whole transaction.
## Receipts and RPC
The receipt has the same shape as an EIP-1559 receipt: `rlp([status, cumulative_gas_used, logs_bloom, logs])`. `status` is `1` only when every phase succeeded, or when `calls` is empty. Logs from phases that reverted are dropped.
| Method | What changes |
|---|---|
| `eth_getTransactionReceipt` | Adds `payer` (the resolved payer) and `phaseStatuses` (`0x01` or `0x00` for each phase). `gasUsed` includes payer authentication. |
| `eth_getTransactionCount` | Takes an optional `nonceKey`. With no key, or `0`, it returns the account nonce. Any other key reads the Nonce Manager. |
| `eth_estimateGas`, `eth_call` | Take `sender`, `nonceKey`, `accountChanges`, `calls`, `validAfter`, `validBefore`, `metadata`, `payer`, `senderAuth`, and `payerAuth`, and run the request as a Base Transaction. Signatures are not checked. Missing auth fields are priced as secp256k1 placeholders of the correct shape. |
## Precompiles
| Precompile | Address | Interface |
|---|---|---|
| Nonce Manager | `0x813000000000000000000000000000000000aa01` | `getNonce(address account, uint256 nonceKey) returns (uint64)`. Read-only. Key `0` gives the account nonce. |
| Transaction Context | `0x813000000000000000000000000000000000aa02` | `getTransactionPayer() returns (address)`. Gives the resolved payer for a Base Transaction, and `tx.origin` for every other type. |
## Related pages
- [Everest Upgrade Overview](/specifications/everest-overview/): the fork that carries this type
- [Native Account Abstraction](/architecture/native-account-abstraction/): the EIP-8130 design that EIP-8430 came from
- [EIP-8430 specification](https://github.com/ethereum/EIPs/pull/12385) and the [Ethereum Magicians thread](https://ethereum-magicians.org/t/eip-8430-aa-transaction-type-split-out-from-8130/29810)
---
# Beryl Upgrade Overview
Source: https://basehub.org/specifications/beryl-overview/
Description: Summary of the Beryl hardfork — the B20 native token standard, a shorter single-proof withdrawal window, and the Reth V2 node release.
import { Aside } from '@astrojs/starlight/components';
Beryl is the next Base hardfork after Azul. It folds together three unrelated changes: a chain-native token standard called [B20](/specifications/b20), a shorter wait before withdrawals finalize, and the [Reth V2](/specifications/reth-v2) node release that trims disk usage and accelerates state-root work.
## What Beryl ships
- **[B20](/specifications/b20)** — a native token standard built for issuers of stablecoins, real-world assets (RWAs), and long-tail tokens.
- **Faster withdrawals** — a single-proof proposal now finalizes after 5 days instead of the previous 7, returning bridge liquidity sooner.
- **[Reth V2](/specifications/reth-v2)** — as much as 50% less disk and a rebuilt state-root pipeline worth roughly +33% throughput.
## Activation timestamps
| Network | Timestamp | Date |
|---------|-----------|------|
| `mainnet` | `1782410400` | 2026-06-25 18:00:00 UTC |
| `sepolia` | `1781805600` | 2026-06-18 18:00:00 UTC |
## Required software
Builds for both networks are now published — the Mainnet versions have been confirmed ahead of its activation date.
| Layer | Software | Mainnet | Sepolia |
|-------|----------|---------|---------|
| Execution (EL) | `base-reth-node` | [v1.1.1+](https://github.com/base/base/releases/tag/v1.1.1) | [v1.1.0+](https://github.com/base/base/releases/tag/v1.1.0) |
| Consensus (CL) | `base-consensus` | [v1.1.1+](https://github.com/base/base/releases/tag/v1.1.1) | [v1.1.0+](https://github.com/base/base/releases/tag/v1.1.0) |
| - | `base/node` | [v1.1.1+](https://github.com/base/node/releases/tag/v1.1.1) | [v1.1.0+](https://github.com/base/node/releases/tag/v1.1.0) |
## B20: native token standard
B20 is Base's own token standard: tokens that keep ERC-20 compatibility but run as Rust precompiles instead of EVM contracts, aimed at stablecoin, RWA, and long-tail issuers. The full surface is documented in [B20 Native Token Standard](/specifications/b20), covering the [roles model](/specifications/b20#roles-model), [policy integration](/specifications/b20#policy-integration), the [factory](/specifications/b20#factory), the [policy registry](/specifications/b20#policy-registry), [mint and burn](/specifications/b20#mint), and the asset/stablecoin [variants](/specifications/b20#variants).
## Withdrawals
Beryl shortens how long a single-proof proposal sits in its dispute game before finalizing — that wait drops to 5 days, down from 7. The TEE + ZK dual-proof path that Azul introduced is untouched and still resolves in a single day.
Returning capital to fast-bridge liquidity providers sooner is the point: shorter lockups mean lower fees and steadier third-party bridging for the people using it.
## Reth V2
Reth V2 ships as a node-software update alongside Beryl — it needs no separate network upgrade. It targets the two ceilings on a high-throughput chain, disk footprint and state-root speed, through [Storage V2](/specifications/reth-v2#storage-v2) and a rewritten [state-root computation](/specifications/reth-v2#state-root-computation) path. Full details are in [Reth V2](/specifications/reth-v2).
## Native Account Abstraction (EIP-8130)
Account abstraction moves into the protocol itself, but it is not part of Beryl. It was slated for [Cobalt](/specifications/cobalt-overview/), the hardfork that comes next, until the node source moved it onto a separate activation gate in September 2026 — one that no public network sets. In October 2026 the transaction part came back as [Base Transactions](/specifications/base-transactions/) (EIP-8430), planned for the [Everest](/specifications/everest-overview/) fork, which has no date yet. Each account records — onchain — who is allowed to act for it and how its signatures are checked, so smart-account behavior no longer depends on bundlers, relays, or a separate mempool. That hands applications portable smart accounts out of the box, along with scoped, revocable session keys, atomic call batching, and gas sponsorship paid natively by the protocol. EIP-8130 is still experimental, and Base Transactions run only on devnets for now. The full mechanics — the account/actor/policy/authenticator model and a working vibenet example — are in [Native Account Abstraction](/architecture/native-account-abstraction).
---
# Challenger
Source: https://basehub.org/specifications/challenger/
Description: Offchain service that detects invalid AggregateVerifier games and submits dispute transactions on L1 to nullify them.
The challenger guards the proof system by independently checking in-progress `AggregateVerifier` games against canonical L2 state. When it finds a checkpoint root that does not match, it obtains the proof material the game contract demands and sends a dispute transaction on L1.
The ZK path of the challenger is permissionless — anyone with L1 and L2 RPC access, a ZK proving service, and an L1 transaction signer can run one. Base may additionally run a challenger that has access to a TEE proof endpoint so invalid TEE-backed games can be nullified on the faster TEE path before any ZK fallback.
## Responsibilities
A conforming challenger:
1. Scans recent `DisputeGameFactory` games.
2. Selects games that are still `IN_PROGRESS` and whose proof state may need action.
3. Recomputes the relevant checkpoint output roots from an L2 node.
4. Identifies the first invalid checkpoint, or determines whether a ZK challenge was aimed at a correct checkpoint.
5. Sources a TEE or ZK proof for the interval that must be proven.
6. Submits `nullify()` or `challenge()` to the game contract.
7. Tracks the bond lifecycle that follows, when bond claiming is configured.
The challenger never decides canonical L2 state by trusting the game. It rebuilds roots from L2 headers and account proofs and treats the game itself purely as an input to be verified.
## Game selection
The challenger reads the current `AnchorStateRegistry.anchorGame()`, locates that game's slot in the factory index, and scans every higher index. If the registry is still at the original anchor, or if the anchor game cannot be found in the factory, the scan starts at index `0`. Games seen `IN_PROGRESS` stay tracked until they resolve or are completely nullified, so live metrics describe the full post-anchor set. Each scan re-evaluates that whole range so games can shift categories as new proofs, challenges, or nullifications appear onchain. Individual game query failures are logged and retried on the next scan rather than aborting the run.
A game is only selected when `status() == IN_PROGRESS`. The challenger then reads:
- `teeProver()`
- `zkProver()`
- `counteredByIntermediateRootIndexPlusOne()`
- `rootClaim()`
- `l2SequenceNumber()`
- `startingBlockNumber()`
- `l1Head()`
- `INTERMEDIATE_BLOCK_INTERVAL()` from the game implementation for that game type
The `(teeProver, zkProver, countered index)` tuple selects the candidate category:
| TEE prover | ZK prover | Countered index | Category | Challenger action |
| ---------- | --------- | --------------- | ----------------------- | --------------------------------------------------------------------------------------------------------------------- |
| non-zero | zero | `0` | Invalid TEE proposal | Validate all checkpoint roots. If invalid, prefer TEE nullification and fall back to ZK `challenge()`. |
| non-zero | non-zero | `> 0` | Fraudulent ZK challenge | Validate only the challenged checkpoint. If the challenged root is correct, submit ZK `nullify()`. |
| zero | non-zero | `0` | Invalid ZK proposal | Validate all checkpoint roots. If invalid, submit ZK `nullify()`. |
| non-zero | non-zero | `0` | Invalid dual proposal | Validate all checkpoint roots. If invalid, nullify the TEE proof first, then rescan to handle the remaining ZK proof. |
Games with both prover addresses zeroed are already fully nullified and are skipped. TEE-only or ZK-only games with a non-zero countered index are anomalous states and are also skipped.
## Output root validation
For an unchallenged proposal, the challenger validates the submitted intermediate roots. The checkpoint block for index `i` is:
```text
startingBlockNumber + INTERMEDIATE_BLOCK_INTERVAL * (i + 1)
```
The number of submitted roots must equal:
```text
(l2SequenceNumber - startingBlockNumber) / INTERMEDIATE_BLOCK_INTERVAL
```
The interval must be non-zero, and the starting block must be lower than the proposed L2 sequence number. Arithmetic overflow or a checkpoint-count mismatch causes validation to fail for that scan tick.
For each checkpoint block, the challenger derives the expected output root as follows:
1. Fetch the L2 block header by block number.
2. Verify that the RPC-provided header hash matches the hash computed from the consensus header.
3. Fetch an `eth_getProof` account proof for `L2ToL1MessagePasser` at that block hash.
4. Verify the account proof against the header state root.
5. Build the output root from the L2 state root, the `L2ToL1MessagePasser` storage root, and the L2 block hash.
6. Compare the computed root to the root stored in the game.
Intermediate roots are validated concurrently, but results are consumed in checkpoint order. The first mismatch sets the `intermediateRootIndex` and `intermediateRootToProve` used by the dispute transaction. `intermediateRootToProve` is the locally computed correct root for the invalid checkpoint.
If the requested L2 block is not yet available, the challenger skips that game for the tick. The game stays eligible and is retried on the next scan.
## Fraudulent ZK challenge validation
When a TEE proposal has already been challenged by a ZK proof, the game stores a 1-based countered index. The challenger converts it to a 0-based checkpoint index and validates only that one checkpoint.
If the onchain root at the challenged index does not match the locally computed root, the ZK challenge was legitimate and the challenger does nothing. If the onchain root does match, the ZK challenge targeted a correct checkpoint and is fraudulent — the challenger then obtains a ZK proof for that checkpoint interval and submits `nullify()`.
The validation here is intentionally local to the challenged index. Earlier invalid roots do not legitimize a challenge against a later valid root.
## Proof sourcing
The challenger proves only the interval that contains the invalid checkpoint. The trusted anchor is the prior checkpoint root, or the game's `startingBlockNumber` state when the invalid checkpoint is index `0`.
A ZK proof request specifies:
- `start_block_number` — the start of the invalid checkpoint interval.
- `number_of_blocks_to_prove` — `INTERMEDIATE_BLOCK_INTERVAL`.
- `proof_type` — Groth16 SNARK.
- `session_id` — deterministic from `(game address, invalid checkpoint index)`.
- `prover_address` — the L1 address that will submit the transaction.
- `l1_head` — the L1 head hash stored in the game at creation.
The deterministic session ID makes proof requests idempotent across retries.
When a TEE proof source is configured and the game has a TEE prover, the challenger tries the TEE path first for invalid TEE proposals and invalid dual proposals. The TEE request uses the game's stored `l1Head`, its corresponding L1 block number, the locally computed agreed L2 output at the start of the interval, and the expected output root at the invalid checkpoint. The TEE result is only accepted if the enclave's output root equals the locally computed expected root; the challenger then encodes the TEE dispute proof bytes for `nullify()`.
If the TEE request fails or times out, the challenger falls back to ZK. If a TEE proof is obtained but the TEE `nullify()` transaction fails, the pending entry transitions to a ZK proof request rather than retrying the same TEE transaction indefinitely.
## Dispute transactions
The challenger submits one of two game calls:
| Intent | Contract call | Used when |
| --------- | ----------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| Nullify | `nullify(proofBytes, intermediateRootIndex, intermediateRootToProve)` | Removing an invalid TEE proof, removing an invalid ZK proof, or refuting a fraudulent ZK challenge. |
| Challenge | `challenge(proofBytes, intermediateRootIndex, intermediateRootToProve)` | Challenging an invalid TEE proposal with a ZK proof. |
TEE proofs always target `nullify()`. ZK proofs may target either `challenge()` or `nullify()` depending on the candidate category.
Before submitting or retrying a failed proof, the challenger re-reads the game status and prover slots. If the game has already resolved, has already been challenged, or the targeted prover slot has been zeroed, the pending proof is dropped. This prevents duplicate transactions when another actor has already handled the game.
## Pending proof lifecycle
Each pending proof is keyed by game address and tracks:
- proof kind: TEE or ZK
- invalid checkpoint index
- expected root for that checkpoint
- dispute intent
- retry count
- phase
The phase machine is:
```mermaid
flowchart TB
ZkStart([ZK job accepted]) --> AwaitingProof[AwaitingProof]
TeeStart([TEE proof ready]) --> ReadyToSubmit[ReadyToSubmit]
AwaitingProof -->|ZK success| ReadyToSubmit
AwaitingProof -->|ZK failed| NeedsRetry[NeedsRetry]
NeedsRetry -->|retry accepted| AwaitingProof
NeedsRetry -->|exhausted/no fallback| Dropped[Dropped]
ReadyToSubmit -->|submitted/stale| Dropped
ReadyToSubmit -->|ZK fallback| AwaitingProof
```
ZK proofs are polled from the proving service until the job succeeds, fails, or remains pending. Successful ZK receipts are prefixed with the ZK proof-type byte before submission. Failed proof jobs are retried up to three times. A TEE proof enters `ReadyToSubmit` immediately on arrival; if its transaction fails, the challenger requests the pre-built ZK fallback proof when one is available. If no fallback request exists, the entry is dropped; if the fallback `prove_block` call fails, the entry stays in `NeedsRetry` until the next tick. A proof that stays pending, a failed ZK transaction, or a failed `prove_block` retry leaves the proof in its current phase until the next tick. A pending proof produces no contract reads for that game on that tick.
## Bond claiming
Bond claiming is optional and gated on configuring claim addresses. When enabled, the challenger tracks games whose `bondRecipient()` or pre-resolution `zkProver()` matches one of those addresses, which lets a challenger pick up claimable games after a restart and discover games other actors have handled.
The bond lifecycle is:
1. `NeedsResolve` — wait for `gameOver()`, then call `resolve()`.
2. `NeedsUnlock` — submit the first `claimCredit()` to unlock the `DelayedWETH` credit.
3. `AwaitingDelay` — wait out the `DelayedWETH` delay.
4. `NeedsWithdraw` — submit the second `claimCredit()` to withdraw the credit.
After resolution the challenger re-reads `bondRecipient()` and drops tracking if the bond is no longer claimable by a configured address. For games that resolve as `DEFENDER_WINS`, it also tries a best-effort `AnchorStateRegistry.setAnchorState(game)` update. That registry call is permissionless and self-validating; premature or ineligible calls can revert and be retried.
## Service lifecycle
At startup the challenger:
1. Creates L1 and L2 RPC clients.
2. Creates the L1 transaction manager from the configured signer.
3. Creates `DisputeGameFactory` and `AggregateVerifier` clients.
4. Creates the ZK proof client and optional TEE proof client.
5. Starts the health server.
6. Starts the driver loop.
Each driver tick:
1. Polls pending proof sessions and submits any disputes that are ready.
2. Discovers claimable bonds and advances tracked bond claims.
3. Scans for in-progress candidate games.
4. Validates and starts proofs for new candidates.
The health endpoint reports ready only after the first successful driver step. Shutdown is driven by a cancellation token so the driver and the health server stop together.
## Operator inputs
A challenger needs:
- L1 RPC endpoint.
- L2 execution RPC endpoint.
- `DisputeGameFactory` address.
- `AnchorStateRegistry` address.
- ZK proof RPC endpoint.
- L1 transaction signer.
- Poll interval.
Optional inputs:
- TEE proof RPC endpoint and timeout, enabling TEE-first nullification for TEE-backed games.
- Bond claim addresses, bond discovery interval, and bond discovery lookback window, enabling automatic bond recovery and claiming.
- Metrics and health server settings.
## Safety requirements
A challenger implementation must preserve these safety properties:
- Do not dispute a game from the game's own claimed roots alone; recompute roots from L2 headers and verified `L2ToL1MessagePasser` account proofs.
- Use the game's stored L1 head when requesting dispute proofs so proof journals match the game context that the contract verifies.
- For fraudulent ZK challenges, validate the challenged checkpoint itself rather than the first invalid checkpoint in the entire proposal.
- Recheck game state before submitting a ready proof, because another challenger or prover may have already changed the game.
- Treat unavailable L2 blocks and transient RPC failures as retryable scan conditions, not as final validation results.
---
# Cobalt Upgrade Overview
Source: https://basehub.org/specifications/cobalt-overview/
Description: Summary of the Cobalt hardfork — B20 improvements, validity transactions, upgrade timestamps read from an onchain contract, and a new onchain path for registering TEE signers.
import { Aside } from '@astrojs/starlight/components';
Cobalt is the Base hardfork that follows [Beryl](/specifications/beryl-overview/). Its scope settled in mid-September 2026 after two rounds of reshuffling, and it is now live on both public networks: Sepolia since September 23, 2026 and Mainnet since September 30, 2026. It carries four things: a batch of B20 additions, conditional transactions that only become eligible when chain state matches, a first step toward lifting fork timestamps out of the node binary, and a new way to register TEE prover signers that verifies the Nitro attestation directly onchain.
## Status
| Network | Status | Date |
|---|---|---|
| Base Sepolia | Live | September 23, 2026 |
| Base Mainnet | Live | September 30, 2026 |
Upstream moved Cobalt off planning status on 2026-09-15 and named both dates. Both are now pinned in the node source rather than merely announced, and the status page has published scheduled-event notices for both networks. Sepolia activated on September 23 and the maintenance window closed cleanly at 20:00 UTC, so the scope on this page is no longer expected to move.
Mainnet followed one week later. Its window opened at 18:00 UTC on September 30 and the status page marked it complete at 20:00 UTC, again with no incident filed. Upstream switched both the fork page and the upgrades tracker to Live the same evening. A check against Mainnet on 2026-10-01 agrees: at a block from before `1790791200`, a B20 Asset token reverted calls to the Cobalt-only `uiMultiplier` and `SEIZE_EXEMPT_POLICY` getters, and at the current head both return values.
Both networks now have an exact activation moment compiled into the node. `cobalt_timestamp` for chain `84532` is `1790186400`, which is **September 23, 2026 at 18:00 UTC**. Chain `8453` is `1790791200`, which is **September 30, 2026 at 18:00 UTC**. The two sit exactly seven days apart, and the Mainnet value landed on 2026-09-21, six days after the dates were first announced.
This corrects guidance this page carried until 2026-09-16. Cobalt does ship the onchain upgrade registry, but that mechanism runs in metrics-only mode at this fork and does not replace the compiled-in schedule yet. Both networks still take their Cobalt activation from the timestamp built into the client, so a node release remains the thing to watch.
## What Cobalt ships
- **B20 improvements** — scheduled multiplier updates, a first-class seize operation that supersedes `burnBlocked`, and two new composite policy types. The call-level detail is in the [B20 precompile reference](/api-reference/b20-precompiles/).
- **Validity transactions** — a signed transaction paired with conditions on chain state, which Base holds back until every condition matches. See [Validity Transactions](/api-reference/validity-transactions/).
- **Dynamic upgrades** — an L1 contract holds the fork schedule, groundwork for activation that does not depend on shipping a binary with the timestamps compiled in. Cobalt itself still activates from the compiled-in schedule; the registry runs alongside it in metrics-only mode.
- **TEE registration migration** — new TEE prover signers are now admitted by checking their AWS Nitro attestation fully onchain, with checked P-384 hints doing the heavy curve math. This retires the RISC Zero proof and the Boundless marketplace from registration, so the registrar no longer relies on an outside proving service and signers register faster. Enclave key generation, PCR0 image selection, and proof verification stay as they were. Upstream relabelled this item on 2026-09-25; earlier wording described a move of all Base infrastructure into a TEE, which overstated it. See the [TEE Prover Registrar](/specifications/registrar/) and the [nitro-validator redesign](/architecture/nitro-validator/).
## What moved out of Cobalt
Two features carried the Cobalt label at some point and no longer do. Material written earlier says otherwise, so it is worth stating plainly:
| Feature | Now shipped by | Status |
|---|---|---|
| Canonical 200ms blocks, BaseTime, millisecond RPC timestamps | [Denim](/specifications/denim-overview/) | Sepolia scheduled for 2026-10-21 18:00 UTC; Mainnet pinned in source for 2026-11-05 18:00 UTC, not yet announced |
| Native account abstraction (EIP-8130) | [Everest](/specifications/everest-overview/), as Base Transactions (EIP-8430) | Planning, no date on any network |
The 200ms work was briefly filed under Cobalt in early September 2026 and has since moved back to Denim. The node source never followed it across: block-timing paths have gated on `is_denim_active_at_timestamp` throughout, so the reassignment restores agreement between the docs and the implementation.
Account abstraction took longer to settle. From September to mid-October 2026 it had no fork, and its runtime gate was `zenith`, a test-only gate that no canonical network sets. On 2026-10-13 upstream gave it a new home in a smaller form. The transaction type is now [Base Transactions](/specifications/base-transactions/) under EIP-8430, carried by [Everest](/specifications/everest-overview/), and the node gates it on `is_everest_active_at_timestamp`. The actor and authenticator parts of the original model stay behind `zenith`. Everest has no date yet. The background design is in [Native Account Abstraction](/architecture/native-account-abstraction/).
## Required software
Sepolia now has a named minimum: [`v1.4.0`](https://github.com/base/base/releases/tag/v1.4.0) of `github.com/base/base`, or anything later. Upstream published that requirement alongside the scheduled-event notice on 2026-09-16, and the tag went out the same evening. It is the first build whose compiled-in schedule contains the Sepolia activation, so it is the floor rather than a recommendation — an older node does not recognise the fork at all.
Mainnet has a published floor too: [`v1.4.2`](https://github.com/base/base/releases/tag/v1.4.2), named in the status-page notice of 2026-09-23 and released the same evening. `v1.4.0` does not qualify. It was tagged before chain `8453` received `1790791200`, so it ships Mainnet `cobalt_timestamp: None` and will not follow the fork on September 30.
`v1.4.1` is the trap. It went final on 2026-09-23, and its compiled schedule already contains the Mainnet timestamp (the value first appears at `v1.4.1-rc.9`). So a `v1.4.1` node does activate Cobalt on time. It is still below the floor. `v1.4.2` is `v1.4.1` plus three commits, and the one that matters is a backport (#5260) of two validity RPC changes:
- the node registers validity transaction ingress before Cobalt and turns it on from the live upgrade schedule, while keeping the experimental override
- a regular RPC node proxies validity submissions to the sequencer through `SequencerClient`, keeping predicates, sequencer headers, and upstream rejection behavior intact
Put simply, `v1.4.1` follows the fork, but its validity RPC is not tied to the live schedule and does not forward submissions to the sequencer. If your node takes public RPC traffic and still runs `v1.4.1`, callers of `base_sendRawTransactionValidity` hit that gap today.
One packaging note worth repeating, because the September 23 window is the first fork where it bites: the public node images and binaries now come from `github.com/base/base`. The retired `base/node` repository stopped receiving them at `v1.3.0`, so there is no `v1.4.0` or `v1.4.2` on the old path to pull. [Vibenet](/introduction/connecting-to-base/) still carries the Cobalt surface too, and upstream keeps its interactive validity transaction demos there.
## B20 improvements
Cobalt widens the B20 surface rather than changing it. Every Beryl selector, event topic, and error keeps its 4-byte identity, so existing integrations keep compiling and keep working.
The additions worth knowing about: multiplier updates that can be scheduled ahead of time instead of landing instantly, a `seizeWithMemo` call that reassigns a holder's balance in one admin step, and Union and Intersect policy types that compose existing policies. Paying transaction fees in a B20 token was on Cobalt's list until 2026-09-29, when upstream took it off the fork page; the node source has no fee-token path either, so it remains a [roadmap item](/specifications/b20/#roadmap) rather than a Cobalt feature.
## Validity transactions
A validity transaction is an ordinary signed transaction submitted alongside a list of predicates over chain state. Base holds it out of the block until every predicate matches, then lets it compete for inclusion on normal fee rules. This makes conditional swaps, conditional withdrawals, and similar state-dependent actions expressible without a keeper watching the chain and racing to submit.
The predicates read account balances, raw storage slots, block numbers, and Flashblock positions. Upstream pulled the balance predicate on 2026-10-01 and restored it on 2026-10-06, and no release ever rejected it. They are submitted out of band and never appear onchain. The [Validity Transactions reference](/api-reference/validity-transactions/) covers the request format, the predicate types, and the safety rules that go with reading storage directly.
## Dynamic upgrades
Every fork so far has needed a fresh node release carrying the activation timestamps in its source. That couples two things that do not have to be coupled: agreeing on when a fork happens, and shipping the code that implements it. An operator who misses the release risks dropping out of consensus for no reason other than a version number.
Cobalt separates them. An Ethereum contract stores the upgrade schedule, and both the execution and consensus clients run a poller that reads it over an L1 RPC endpoint, writes the result into the client's activation overrides, and applies it everywhere the schedule is consulted. A fork can then activate at its scheduled moment with no restart.
---
# Configuration
Source: https://basehub.org/specifications/configuration/
Description: Reference for Base Chain configuration parameters and the roles authorized to change them, grouped into consensus parameters, policy parameters, admin roles, and service roles.
Base configuration is organized into four groups, distinguished by how — and by whom — each value can be altered:
- **Consensus Parameters** — set at genesis, or only movable through privileged accounts or a protocol upgrade.
- **Policy Parameters** — adjustable within protocol-enforced bounds without breaking consensus.
- **Admin Roles** — accounts permitted to upgrade contracts, reassign role ownership, or alter protocol parameters. Usually held in cold/multisig wallets.
- **Service Roles** — accounts that drive everyday operations. Usually hot wallets.
## Consensus Parameters
| Parameter | Description | Administrator |
|-----------|-------------|---------------|
| Batch Inbox Address | L1 address where batcher transactions are posted | Static |
| Batcher Hash | Versioned hash of the authorized batcher sender(s) | [System Config Owner](#admin-roles) |
| Chain ID | Unique chain ID for transaction signature validation | Static |
| Proof Maturity Delay | How long a proven withdrawal waits before it can finalize. Set by the dispute game's finalization window: 5 days with one proof, 1 day with both TEE and ZK proofs (see [Transaction Finality](/network/transaction-finality/#finality-for-withdrawals)). | [L1 Proxy Admin](#admin-roles) |
| Respected Game Type | Game type `OptimismPortal` accepts for withdrawal finalization. Aggregate verifier (`621`). | [Guardian](#service-roles) |
| Bond Withdrawal Delay | Time before dispute game bonds can be withdrawn. 1 day. | Static |
| Fee Scalar | Markup on transactions relative to raw L1 data cost. Fee margin between 0%–50%. | [System Config Owner](#admin-roles) |
| Gas Limit | L2 block gas limit. ≤ 200,000,000 gas. | [System Config Owner](#admin-roles) |
| Genesis State | Initial chain state including all predeploy code and storage. Standard predeploys and preinstalls only. | Static |
| L2 Block Time | Interval at which L2 blocks are produced via derivation. 1 or 2 seconds. | [L1 Proxy Admin](#admin-roles) |
| Sequencing Window Size | Max batch submission gap before L1 fallback triggers. 3,600 L1 blocks (12 hours at 12s L1 block time). | Static |
| Start Block | L1 block where `SystemConfig` was first initialized | [L1 Proxy Admin](#admin-roles) |
| Superchain Target | `SuperchainConfig` and `ProtocolVersions` addresses for cross-L2 config. Mainnet or Sepolia. | Static |
| Governance Token | OP governance token. Disabled. | n/a |
| Operator Fee Params | Operator fee scalar and constant for fee calculation. Standard values are 0; non-zero for non-standard configurations such as op-succinct. | [System Config Owner](#admin-roles) |
| DA Footprint Gas Scalar | Scalar for DA footprint calculation | [System Config Owner](#admin-roles) |
| Minimum Base Fee | Minimum base fee on L2 | [System Config Owner](#admin-roles) |
## Policy Parameters
| Parameter | Description | Administrator |
|-----------|-------------|---------------|
| Data Availability Type | Whether the batcher posts data as blobs or calldata. Ethereum (Blobs or Calldata); Alt-DA not supported. | [Batch Submitter](#service-roles) |
| Batch Submission Frequency | Frequency of batcher transaction submissions to L1. ≤ 1,800 L1 blocks (6 hours at 12s L1 block time). | [Batch Submitter](#service-roles) |
| Output Frequency | Frequency of output root submissions to L1. ≤ 43,200 L2 blocks (24 hours at 2s L2 block time); must be non-zero. Deprecated once fault proofs are enabled. | [L1 Proxy Admin](#admin-roles) |
## Admin Roles
| Role | Description | Administers |
|------|-------------|-------------|
| L1 Proxy Admin | `ProxyAdmin` from the latest `op-contracts` release, authorized to upgrade L1 contracts | L1 contracts |
| L1 ProxyAdmin Owner | Authorized to update the L1 Proxy Admin. [0x5a0Aae59D09fccBdDb6C6CcEB07B7279367C3d2A](https://etherscan.io/address/0x5a0Aae59D09fccBdDb6C6CcEB07B7279367C3d2A) | L1 Proxy Admin |
| L2 Proxy Admin | `ProxyAdmin` at `0x4200000000000000000000000000000000000018`, authorized to upgrade L2 contracts | Predeploys |
| L2 ProxyAdmin Owner | Aliased L1 ProxyAdmin Owner; upgrades L2 contracts via `ProxyAdmin`. [0x6B1BAE59D09fCcbdDB6C6cceb07B7279367C4E3b](https://optimistic.etherscan.io/address/0x6B1BAE59D09fCcbdDB6C6cceb07B7279367C4E3b) | L2 Proxy Admin |
| System Config Owner | Authorized to change values in the `SystemConfig` contract | Batch Submitter, Sequencer P2P Signer, Fee Scalar, Gas Limit |
## Service Roles
| Role | Description | Administrator |
|------|-------------|-------------|
| Batch Submitter | Authenticates batches submitted to L1 | [System Config Owner](#admin-roles) |
| Challenger | Interacts with permissioned dispute games. [0x9BA6e03D8B90dE867373Db8cF1A58d2F7F006b3A](https://etherscan.io/address/0x9BA6e03D8B90dE867373Db8cF1A58d2F7F006b3A) | [L1 Proxy Admin](#admin-roles) |
| Guardian | Pauses L1 withdrawals, blacklists dispute games, sets respected game type in `OptimismPortal`. [0x09f7150D8c019BeF34450d6920f6B3608ceFdAf2](https://etherscan.io/address/0x09f7150D8c019BeF34450d6920f6B3608ceFdAf2) | [L1 Proxy Admin](#admin-roles) |
| Proposer | Creates permissioned dispute games on L1. | [L1 Proxy Admin](#admin-roles) |
| Sequencer P2P Signer | Signs unsafe/pre-submitted blocks at the P2P layer | [System Config Owner](#admin-roles) |
---
# Proof Contracts
Source: https://basehub.org/specifications/contracts/
Description: Onchain contracts that verify proof material, track game state, and release withdrawals for the Azul proof system.
import { Aside } from '@astrojs/starlight/components';
The proof contracts are what turn offchain proof material into onchain checkpoint games. A game asserts an L2 output root for a fixed block interval. The contracts verify the initial proof, accept an optional second proof, let invalid proof material be challenged or nullified, resolve the game after the applicable delay, advance the anchor state, and release the initialization bond.
The contracts in this spec:
- `AnchorStateRegistry`
- `DelayedWETH`
- `DisputeGameFactory`
- `AggregateVerifier`
- `ZKVerifier`
- `TEEVerifier`
- `TEEProverRegistry`
- `NitroValidator`
- `CertManager`
- `P384Verifier`
## Contract graph
```mermaid
flowchart TB
Factory[DisputeGameFactory] -->|clones| Game[AggregateVerifier game]
Game -->|validates parent and finality| ASR[AnchorStateRegistry]
Game -->|escrows and releases bond| WETH[DelayedWETH]
Game -->|TEE proofs| TEEVerifier[TEEVerifier]
Game -->|ZK proofs| ZKVerifier[ZKVerifier]
TEEVerifier -->|signer and proposer checks| Registry[TEEProverRegistry]
Registry -->|signed attestation and hints| Nitro[NitroValidator]
Registry -->|current TEE_IMAGE_HASH| Factory
ZKVerifier -->|SP1 proof| SP1[SP1 verifier gateway]
Nitro -->|cached certificate chain| Certs[CertManager]
Nitro -->|attestation signature| P384[P384Verifier]
Certs -->|certificate signatures| P384
```
`DisputeGameFactory`, `AnchorStateRegistry`, `DelayedWETH`, and `TEEProverRegistry` sit behind proxies. `AggregateVerifier` is deployed once as an implementation, and the factory clones it with immutable arguments. `TEEVerifier` and `ZKVerifier` are standalone proof verifiers that the game implementation points to. The registry points to a standalone `NitroValidator`, and that contract relies on `CertManager` and `P384Verifier` to check signer attestations.
## Data model
The contracts share the same dispute-game types:
| Type | Meaning |
| ------------ | ----------------------------------------------------------------------------------------- |
| `GameType` | A `uint32` identifier for a dispute game implementation. |
| `Claim` | A 32-byte root claim. In this proof system it is an L2 output root. |
| `Hash` | A 32-byte hash wrapper. |
| `Timestamp` | A `uint64` timestamp wrapper. |
| `Proposal` | `(root, l2SequenceNumber)`, where `l2SequenceNumber` is the L2 block number for the root. |
| `GameStatus` | `IN_PROGRESS`, `CHALLENGER_WINS`, or `DEFENDER_WINS`. |
| `ProofType` | `TEE` or `ZK` inside `AggregateVerifier`. |
The `AggregateVerifier` game has two block intervals:
```text
BLOCK_INTERVAL
INTERMEDIATE_BLOCK_INTERVAL
```
`BLOCK_INTERVAL` is the distance between a parent output root and a proposed output root. `INTERMEDIATE_BLOCK_INTERVAL` is the spacing between intermediate roots inside that range. Both must be non-zero, and `BLOCK_INTERVAL` must be divisible by `INTERMEDIATE_BLOCK_INTERVAL`.
The number of intermediate roots in every game is:
```text
BLOCK_INTERVAL / INTERMEDIATE_BLOCK_INTERVAL
```
The final intermediate root must equal the game's `rootClaim`.
## Game lifecycle
1. The factory owner configures a game type with an `AggregateVerifier` implementation and an initialization bond.
2. The registrar caches the Nitro certificates in `CertManager`, then registers each enclave signer through `TEEProverRegistry` with the attestation and its P-384 hints.
3. A proposer creates a game through `DisputeGameFactory.createWithInitData()`, paying the exact initialization bond and supplying an initial TEE or ZK proof.
4. The game validates its parent, L2 block number, intermediate roots, L1 origin, and proof journal. The bond is deposited into `DelayedWETH`.
5. A second proof can be submitted through `verifyProposalProof()`. If the proposal is invalid, challengers can call `challenge()` or `nullify()` with proof material for an intermediate root.
6. After the expected resolution time, anyone can call `resolve()`. The result is `DEFENDER_WINS` for a valid unchallenged game and `CHALLENGER_WINS` for a successful challenge or invalid parent.
7. After resolution and the registry finality delay, anyone can call `closeGame()` to make a best-effort anchor update.
8. The bond recipient calls `claimCredit()` twice: once to unlock the `DelayedWETH` credit, then again after the `DelayedWETH` delay to withdraw and receive ETH.
## DisputeGameFactory
`DisputeGameFactory` creates and indexes dispute-game clones. Each game has a unique identifier:
```text
keccak256(abi.encode(gameType, rootClaim, extraData))
```
The factory stores that UUID in `_disputeGames` and also appends a packed `GameId` to `_disputeGameList` for index-based discovery. Offchain services find games via `DisputeGameCreated`, `gameAtIndex()`, and `findLatestGames()`.
### Configuration
Only the factory owner can:
- set a game implementation with `setImplementation(gameType, impl)`
- set a game implementation plus opaque implementation args with `setImplementation(gameType, impl, args)`
- set the exact required creation bond with `setInitBond(gameType, initBond)`
Creation reverts when the implementation is unset, the paid value disagrees with `initBonds`, or a game with the same UUID already exists.
### Clone arguments
With no implementation args configured, the clone-with-immutable-args payload is:
| Bytes | Description |
| -------------- | ------------------------------------- |
| `[0, 20)` | Game creator address |
| `[20, 52)` | Root claim |
| `[52, 84)` | Parent L1 block hash at creation time |
| `[84, 84 + n)` | Opaque game `extraData` |
With implementation args configured, the payload is:
| Bytes | Description |
| ---------------------- | ------------------------------------- |
| `[0, 20)` | Game creator address |
| `[20, 52)` | Root claim |
| `[52, 84)` | Parent L1 block hash at creation time |
| `[84, 88)` | Game type |
| `[88, 88 + n)` | Opaque game `extraData` |
| `[88 + n, 88 + n + m)` | Opaque implementation args |
`AggregateVerifier` uses the standard layout. Its `extraData` is specified in the `AggregateVerifier` section below.
## AnchorStateRegistry
`AnchorStateRegistry` is the source of truth for whether a dispute game can be trusted by the proof system. It stores:
- the `SystemConfig`
- the `DisputeGameFactory`
- the starting anchor root
- the current anchor game, if one has been accepted
- the current respected game type
- a game blacklist
- a retirement timestamp
- a dispute-game finality delay
The initial retirement timestamp is set during first initialization. Games created at or before the retirement timestamp are retired.
### Game predicates
The registry exposes these predicates:
| Predicate | True when |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `isGameRegistered(game)` | The factory maps the game's `(gameType, rootClaim, extraData)` back to the same address, and the game points at this registry. |
| `isGameRespected(game)` | The game reports that its game type was respected when it was created. |
| `isGameBlacklisted(game)` | The guardian has blacklisted the game address. |
| `isGameRetired(game)` | `game.createdAt() <= retirementTimestamp`. |
| `isGameResolved(game)` | The game has a non-zero `resolvedAt` and ended with `DEFENDER_WINS` or `CHALLENGER_WINS`. |
| `isGameProper(game)` | The game is registered, not blacklisted, not retired, and the system is not paused. |
| `isGameFinalized(game)` | The game is resolved and more than `disputeGameFinalityDelaySeconds` have elapsed since `resolvedAt`. |
| `isGameClaimValid(game)` | The game is proper, respected, finalized, and resolved with `DEFENDER_WINS`. |
`isGameProper()` is not a statement about the correctness of the root claim. It only certifies that the game has not been invalidated by registry-level controls. Consumers that need claim validity must use `isGameClaimValid()`.
### Guardian controls
The `SystemConfig.guardian()` can:
- set the respected game type
- update the retirement timestamp to the current block timestamp
- blacklist individual games
These controls are the onchain safety valves for invalidating games before they can become valid claims.
### Anchor updates
`getAnchorRoot()` returns the starting anchor root until an anchor game has been accepted. After that, it returns the root claim and L2 block number of `anchorGame`.
`setAnchorState(game)` accepts a new anchor game only when:
- `isGameClaimValid(game)` is true
- the game's L2 sequence number is greater than the current anchor root's sequence number
The update is permissionless and self-validating.
## DelayedWETH
`DelayedWETH` is WETH with delayed withdrawals. It escrows game bonds and forces a two-step credit claim:
1. The game calls `unlock(subAccount, amount)` for the bond recipient.
2. After `delay()` seconds, the game calls `withdraw(subAccount, amount)` and sends ETH to the recipient.
Unlocks are keyed by:
```text
withdrawals[msg.sender][subAccount]
```
For proof games, `msg.sender` is the `AggregateVerifier` game contract and `subAccount` is the current `bondRecipient`.
Withdrawals revert while the system is paused. The proxy admin owner also holds emergency recovery powers:
- `recover(amount)` sends up to `amount` ETH from the contract to the owner.
- `hold(account)` or `hold(account, amount)` pulls WETH from an account into the owner address.
## AggregateVerifier
`AggregateVerifier` is the dispute-game implementation for checkpoint proofs. Every factory-created game is a clone with immutable game data. The implementation itself owns no per-game storage beyond the clone's storage.
### Constructor configuration
An implementation fixes these values for all clones of that game type:
| Value | Purpose |
| ----------------------------- | -------------------------------------------------------- |
| `GAME_TYPE` | The dispute-game type served by this implementation. |
| `ANCHOR_STATE_REGISTRY` | Parent validation, claim validity, and anchor updates. |
| `DISPUTE_GAME_FACTORY` | Read from the registry during construction. |
| `DELAYED_WETH` | Bond escrow. |
| `TEE_VERIFIER` | Verifier for TEE signatures. |
| `TEE_IMAGE_HASH` | Expected TEE image hash committed into TEE journals. |
| `ZK_VERIFIER` | Verifier for ZK proofs. |
| `ZK_RANGE_HASH` | Range-program hash committed into ZK journals. |
| `ZK_AGGREGATE_HASH` | Aggregate-program hash passed to the ZK verifier. |
| `CONFIG_HASH` | Rollup configuration hash committed into proof journals. |
| `L2_CHAIN_ID` | L2 chain the game argues about. |
| `BLOCK_INTERVAL` | Distance from parent block to proposed block. |
| `INTERMEDIATE_BLOCK_INTERVAL` | Distance between intermediate checkpoint roots. |
| `PROOF_THRESHOLD` | Number of proofs required to resolve, either `1` or `2`. |
`PROOF_THRESHOLD` governs resolution, not proof submission. The game can store one TEE proof, one ZK proof, or both.
### Game extra data
`AggregateVerifier.extraData()` is encoded as:
| Bytes | Description |
| ------------------- | ---------------------------------------------------------------------- |
| `[0, 32)` | Proposed L2 block number. |
| `[32, 52)` | Parent address. The first game uses the `AnchorStateRegistry` address. |
| `[52, 52 + 32 * n)` | Ordered intermediate output roots. |
where:
```text
n = BLOCK_INTERVAL / INTERMEDIATE_BLOCK_INTERVAL
```
The final intermediate output root must equal `rootClaim`.
### Initialization
`initializeWithInitData(proof)` runs exactly once. It checks the calldata size so unused bytes cannot fabricate multiple factory UUIDs for the same logical proposal.
During initialization the game:
1. Checks that the final intermediate root matches `rootClaim`.
2. Resolves the starting root. If `parentAddress` is the registry address, the starting root is `AnchorStateRegistry.getStartingAnchorRoot()`. Otherwise the parent must be a valid registered game.
3. Requires:
```text
l2SequenceNumber == startingL2SequenceNumber + BLOCK_INTERVAL
```
4. Records `createdAt`, `wasRespectedGameTypeWhenCreated`, and an initial `expectedResolution`.
5. Verifies the claimed L1 origin hash in the initialization proof against either `blockhash()` or EIP-2935 history.
6. Verifies the supplied TEE or ZK proof.
7. Records the initial prover, sets `bondRecipient` to `gameCreator`, and deposits the bond into `DelayedWETH`.
The initialization proof format is:
| Bytes | Description |
| ----------- | -------------------------------------- |
| `[0, 1)` | `ProofType`: `0` for TEE, `1` for ZK. |
| `[1, 33)` | L1 origin hash. |
| `[33, 65)` | L1 origin block number. |
| `[65, end)` | Proof bytes for the selected verifier. |
The L1 origin block must lie in the past. Native `blockhash()` is used for block ages up to 256 blocks. EIP-2935 history is used up to 8191 blocks. Older or unavailable L1 origin blocks revert.
### Additional proofs
`verifyProposalProof(proofBytes)` adds the missing proof type while a game is in progress and not over. It does not re-read a new L1 origin from calldata; instead it uses the `l1Head()` captured by the factory at clone creation.
The additional proof format is:
| Bytes | Description |
| ---------- | -------------------------------------- |
| `[0, 1)` | `ProofType`: `0` for TEE, `1` for ZK. |
| `[1, end)` | Proof bytes for the selected verifier. |
A game cannot store more than one proof of the same type.
### Proof journals
TEE and ZK proofs commit to the same transition shape:
```text
proposer
l1OriginHash
startingRoot
startingL2SequenceNumber
endingRoot
endingL2SequenceNumber
intermediateRoots
CONFIG_HASH
proof-system-specific hash
```
For TEE proofs the final field is `TEE_IMAGE_HASH` and the journal is checked by `TEEVerifier`. The game calls:
```text
TEE_VERIFIER.verify(proposer || signature, TEE_IMAGE_HASH, keccak256(journal))
```
For ZK proofs the final field is `ZK_RANGE_HASH` and the proof is checked by `ZKVerifier`. The game calls:
```text
ZK_VERIFIER.verify(proofBytes, ZK_AGGREGATE_HASH, keccak256(journal))
```
### Resolution delay
`expectedResolution` is derived from the number of currently accepted proofs:
| Proof count | Delay |
| ----------- | ------------------------------------------- |
| `0` | Never resolvable. |
| `1` | `SLOW_FINALIZATION_DELAY`, 5 days since Beryl. |
| `2` | `FAST_FINALIZATION_DELAY`, fixed at 1 day. |
Adding a proof can only push `expectedResolution` earlier. Nullifying a proof can push it later. A challenge with a ZK proof sets `expectedResolution` to 7 days from the challenge so the challenge can itself be nullified.
### Challenge
`challenge(proofBytes, intermediateRootIndex, intermediateRootToProve)` challenges a TEE-backed proposal with a ZK proof for one intermediate interval.
The call is accepted only when:
- the game is still `IN_PROGRESS`
- the game itself is valid according to the registry
- the parent has not resolved with `CHALLENGER_WINS`
- the game has a TEE proof
- the game does not already have a ZK proof
- the supplied proof type is ZK
- the challenged index is in range
- the supplied root differs from the currently proposed intermediate root
When the ZK proof verifies, the game records the ZK prover, increments `proofCount`, stores the 1-based countered intermediate index, and emits `Challenged`. On resolution the challenger receives the bond and the game status becomes `CHALLENGER_WINS`.
### Nullification
`nullify(proofBytes, intermediateRootIndex, intermediateRootToProve)` removes an already accepted proof by proving a contradictory intermediate root.
For an unchallenged game, the target root must differ from the proposed intermediate root. For a challenged game, only the challenged index can be nullified, only with a ZK proof, and the supplied root must equal the original proposed intermediate root.
After a successful nullification:
- the prover slot for that proof type is deleted
- `proofCount` decreases
- `expectedResolution` is recalculated
- the countered index is cleared if the ZK challenge was nullified
- the corresponding verifier contract is nullified
Verifier nullification is a global safety stop. Once `TEE_VERIFIER.nullify()` or `ZK_VERIFIER.nullify()` succeeds, future proof verification through that verifier reverts until the system is upgraded or reconfigured.
### Resolve, close, and bonds
`resolve()` is permissionless. The parent must be resolved unless the parent is the registry itself. If the parent resolved with `CHALLENGER_WINS`, or later became blacklisted or retired, the child also resolves with `CHALLENGER_WINS`. Otherwise the game must be over and must hold at least `PROOF_THRESHOLD` accepted proofs.
If the game was challenged, `resolve()` sets `CHALLENGER_WINS` and moves the bond recipient to the ZK prover. Otherwise it sets `DEFENDER_WINS`.
`closeGame()` is permissionless. It reverts while the registry is paused, requires the game to be resolved and finalized by the registry, and then attempts `AnchorStateRegistry.setAnchorState()`. The anchor update is best-effort: if the registry rejects the game because it is no longer the newest valid claim, `closeGame()` swallows that registry revert.
`claimCredit()` has two phases:
1. Unlock the bond in `DelayedWETH`.
2. After the `DelayedWETH` delay, withdraw WETH and send ETH to `bondRecipient`.
If accepted proofs have been nullified and `expectedResolution` is reset to the never-resolvable sentinel, `claimCredit()` is blocked until 14 days after `createdAt`. This stops a stuck game from locking the bond forever.
## ZKVerifier
`ZKVerifier` adapts the Succinct SP1 verifier gateway to the common `IVerifier` interface used by `AggregateVerifier`.
The call:
```text
verify(proofBytes, imageId, journal)
```
runs:
```text
SP1_VERIFIER.verifyProof(imageId, abi.encodePacked(journal), proofBytes)
```
and returns `true` if the SP1 gateway does not revert. `imageId` is the aggregate program verification key supplied by the game, and `journal` is the hash of the public inputs assembled by the game.
`ZKVerifier` inherits verifier nullification. Once a proper respected game nullifies the verifier, all future `verify()` calls revert.
## TEEVerifier
`TEEVerifier` verifies TEE proof signatures against the `TEEProverRegistry`.
The proof bytes passed to `TEEVerifier` are:
| Bytes | Description |
| ---------- | ------------------------ |
| `[0, 20)` | Proposer address. |
| `[20, 85)` | 65-byte ECDSA signature. |
The signature is recovered over the journal hash directly. It is not wrapped with the Ethereum signed-message prefix.
A TEE proof is valid only when:
- the proof is at least 85 bytes
- the signature recovers cleanly
- the proposer is allowlisted in `TEEProverRegistry`
- the recovered signer is registered in `TEEProverRegistry`
- the signer's registered image hash equals the `imageId` supplied by the calling game
The image-hash check stops an enclave registered for one image from producing accepted proofs for a game type or upgrade that expects another image.
`TEEVerifier` also inherits verifier nullification.
## TEEProverRegistry
`TEEProverRegistry` manages TEE signer registration and proposer allowlisting.
The registry holds:
- an owner
- a manager
- an immutable `NitroValidator` reference
- a `DisputeGameFactory`
- a configurable `gameType`
- registered signer state
- proposer allowlist state
The owner can set proposer addresses and change the `gameType`. The owner or manager can register and deregister signers.
### Expected image hash
The registry reads the expected TEE image hash from the current game implementation:
```text
DisputeGameFactory.gameImpls(gameType).TEE_IMAGE_HASH()
```
`setGameType()` checks that this call succeeds and returns a non-zero hash. `isValidSigner()` returns true only when the signer is registered and its stored image hash matches the current expected hash.
Registration does not compare PCR0 with the current `TEE_IMAGE_HASH`. Operators can therefore register the signers of the next image ahead of a game-type migration. Those signers stay unusable for proofs until the game implementation's `TEE_IMAGE_HASH` equals their stored image hash.
### Signer registration
Since [Cobalt](/specifications/cobalt-overview/), the call is `registerSigner(attestationTbs, signature, hints)` (selector `0xb39dc09d`). It hands the attestation to the validator:
```text
NITRO_VALIDATOR.validateAttestationWithHints(
attestationTbs,
signature,
hints
)
```
The certificate chain behind the attestation has to be verified and cached in `CertManager` beforehand. The validator authenticates the signed fields and returns pointers into the attestation. The registry then applies Base's own rules:
- The attestation timestamp arrives in milliseconds and is converted to seconds. It must be strictly earlier than `block.timestamp`, and less than `MAX_AGE` (3,600 seconds) old.
- PCR0 must sit at index zero, be exactly 48 bytes, and not be the all-zero debug-mode value.
- The public key must be exactly 65 bytes in uncompressed ANSI X9.62 form:
```text
0x04 || x || y
```
The registry derives the signer address as:
```text
address(uint160(uint256(keccak256(x || y))))
```
It takes the 48-byte PCR0 value from the attestation and stores:
```text
signerImageHash[signer] = keccak256(PCR0)
```
It then marks the signer as registered, adds it to an enumerable signer set, and emits `SignerRegistered`.
### Deregistration
`deregisterSigner(signer)` deletes the signer's registration and image hash, removes it from the enumerable set, and emits `SignerDeregistered`.
`getRegisteredSigners()` returns the current enumerable set. Ordering is not guaranteed.
## NitroValidator
`NitroValidator` checks AWS Nitro attestations. It holds immutable references to `CertManager` and `P384Verifier`.
```text
validateAttestationWithHints(
attestationTbs,
signature,
attestationSigHints
)
```
The call does four things:
1. It parses the signed COSE `Sig_structure` and checks the shape of the Nitro payload.
2. It walks the certificate chain again through `CertManager`. The path to the pinned AWS Nitro root must be complete, unexpired, and unrevoked.
3. It checks the 96-byte P-384 attestation signature over `SHA384(attestationTbs)`, using the leaf certificate's public key and the supplied inverse hints.
4. It returns `Ptrs`, which holds the timestamp and CBOR field pointers into `attestationTbs`.
The chain walk takes no certificate hints, so every certificate must already sit in the cache. `decodeAttestationTbs()` splits a raw `COSE_Sign1` document into its signed TBS bytes and its signature. Decoding on its own proves nothing about validity.
The validator does not apply Base policy. It does not check the freshness window, the signer key format, or which enclave image is allowed. The [registry](#signer-registration) checks the timestamp, public key, and PCR0. The registrar checks the nonce offchain. `TEEVerifier` checks the game's expected image when a proof is submitted.
The old unhinted `validateAttestation()` entry point is deprecated and always reverts.
## CertManager
`CertManager` pins the AWS Nitro root when it is deployed. It verifies CA and leaf certificates and caches them. Its two active verification calls are:
```text
verifyCACertWithHints(
cert, parentCertHash, signatureHints
)
verifyClientCertWithHints(
cert, parentCertHash, signatureHints
)
```
Anyone can call either one. A non-root certificate needs its parent in the cache first. On a cold check, the certificate signature goes through `P384Verifier`. When a cached certificate is reused, the contract checks its CA or leaf role, its expiry, the parent it was first bound to, and an unrevoked path to the root. The CA call returns the certificate's cache key. The leaf call returns `VerifiedCert` metadata.
A non-root cache key is `keccak256(TBSCertificate DER)`, which leaves out the outer signature. The root uses its pinned `keccak256(root DER)` key. `loadVerified()` only reads the cache. What it returns can be expired or revoked, so do not treat it as proof that a certificate is still usable.
Revocation uses a separate identity. `computeCertId()` gives the issuer and serial identity of a non-root certificate, and `isRevoked()` reports its status. The root uses its pinned hash. The contract checks revocation on cold verification, on cached reuse, and on the final attestation check. The [TEE Prover Registrar](/specifications/registrar/) page describes how the registrar computes these identifiers.
The old unhinted `verifyCACert()` and `verifyClientCert()` entry points are deprecated and always revert.
## P384Verifier
```text
verifyP384SignatureWithHints(
hash, signature, pubKey, inverseHints
)
```
`P384Verifier` checks P-384 ECDSA signatures for both certificates and attestations. Each hint is a 48-byte big-endian modular inverse. Before it uses a hint, the contract confirms `b * hint == 1 (mod m)`. A wrong, short, or extra hint makes the call revert. A hint can never make a bad signature pass.
The contract does not enforce low-S, so two different byte strings can be valid signatures for the same message. Never use signature bytes as a unique ID for a certificate or an attestation.
## NitroEnclaveVerifier (legacy)
`NitroEnclaveVerifier` is the ZK attestation verifier that the registry used before Cobalt. It accepted RISC Zero or SP1 proofs of an attestation, handled certificate caching and revocation itself, and supported per-route verifier overrides and route freezing. The current registry does not call it. Use `NitroValidator`, `CertManager`, and `P384Verifier` instead.
## Cross-contract safety properties
The proof contracts rely on these cross-contract properties:
- Factory uniqueness: a logical `(gameType, rootClaim, extraData)` can create at most one game.
- Parent validity: non-anchor games can only start from a registered, respected, non-retired, non-blacklisted parent that has not lost.
- Monotonic checkpoints: each child game must advance exactly `BLOCK_INTERVAL` L2 blocks from its starting root.
- Intermediate accountability: every proposal commits to all intermediate roots, so challengers can target the first invalid checkpoint interval.
- Verifier separation: TEE and ZK proofs use different verifier contracts and different journal domain separators (`TEE_IMAGE_HASH` versus `ZK_RANGE_HASH`).
- Fast finality requires diversity: a game with two accepted proof types can resolve after one day, while a game with one proof waits five days (seven before [Beryl](/specifications/beryl-overview/)).
- Registry finality is separate from game resolution: a game can resolve before the `AnchorStateRegistry` accepts it as a valid claim.
- Safety controls fail closed: pause, blacklist, retirement, and verifier nullification all prevent acceptance rather than expanding trust.
## Administrative surfaces
| Contract | Privileged role | Privileged actions |
| ---------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------- |
| `DisputeGameFactory` | Owner | Set game implementations, implementation args, and initialization bonds. |
| `AnchorStateRegistry` | Guardian from `SystemConfig` | Set respected game type, blacklist games, update retirement timestamp. |
| `DelayedWETH` | Proxy admin owner | Recover ETH and hold WETH from accounts. |
| `TEEProverRegistry` | Owner | Set proposers, update game type, transfer ownership or management. |
| `TEEProverRegistry` | Owner or manager | Register and deregister TEE signers. |
| `CertManager` | Owner | Transfer ownership, set the revoker, revoke the pinned root, and unrevoke certificate identities or the root. |
| `CertManager` | Revoker | Revoke non-root issuer and serial identities with `revokeCert()` or `revokeCerts()`. |
These surfaces are intentionally narrow but high impact. Operational changes here can affect which games are respected, which proofs verify, and which attestations can register new TEE signers.
---
# Denim 200ms Native Blocks
Source: https://basehub.org/specifications/denim-200ms-blocks/
Description: Specification for the Denim upgrade's canonical 200ms blocks, where every 200ms interval becomes a full Base block, BaseTime supplies the sub-second timestamp, and block-counted durations shrink tenfold.
import { Aside } from '@astrojs/starlight/components';
Denim changes how Base produces blocks. Instead of one canonical block every two seconds, the chain would seal five per second. Every 200ms interval would produce a block that is complete in its own right — separately numbered and hashed, with its own state root and receipts, its own forkchoice update, and its own path from unsafe to safe to finalized.
## What Denim changes
Today [Flashblocks](/flashblocks/overview/) publish incremental previews of pending state inside a single two-second block. Denim removes the need for that layer by making the 200ms interval a real block. Under the rollout Base stops emitting Flashblocks entirely, so anything reading a Flashblocks stream has to move over to canonical block and RPC feeds.
The Ethereum block header does not change. Its `timestamp` field stays Unix time in whole seconds, and a metadata deposit called BaseTime supplies the missing sub-second piece. Reading both together gives a block's millisecond timestamp.
## Network availability
| Network | Status | Activation timestamp | Required client versions |
| --- | --- | --- | --- |
| `vibenet` | Live for experimental testing | — | — |
| `sepolia` | Scheduled | `1792605600` (2026-10-21 18:00 UTC) | `v1.5.0` or later |
| `mainnet` | Pinned in node source, not yet announced | `1793901600` (2026-11-05 18:00 UTC) | `v1.5.1-rc.7` or later; no final release yet |
Vibenet carries 200ms blocks today, which makes it the place to exercise an integration ahead of time.
Sepolia moved from a planning month to a fixed moment on 2026-10-08, when base/base set `denim_timestamp: Some(1_792_605_600)` for chain `84532` (#5694). The release candidates split cleanly on this: the chain config in `v1.5.0-rc.3` and earlier ships `None`, while `rc.4` and every later candidate carry the timestamp. The final `v1.5.0` landed on 2026-10-14, built from the same commit as `rc.12`, so a stable release now follows Sepolia into Denim. It still ships `None` for Mainnet.
Mainnet followed on 2026-10-20. The November target, which slipped from October on 2026-10-01, became a fixed moment when base/base set `denim_timestamp: Some(1_793_901_600)` for chain `8453` (#6124): **November 5, 2026 at 18:00 UTC**. Only release candidates carry it so far. `v1.5.1-rc.6` and earlier ship `None`, `rc.7` is the first with the value, and the stable `v1.5.0` still ships `None`. Wait for the final release and for Base's announcement before you plan around the exact time.
The fork name is no longer in doubt. Upstream briefly filed 200ms blocks under Cobalt in early September 2026 and has since moved them back to Denim, which matches what the node has done throughout: every block-timing path gates on `is_denim_active_at_timestamp`, and the BaseTime helper lives under the same gate.
## Block-number contract logic
Audit anything that converts a block count into a duration before activation. The common patterns and what each does afterwards:
| Pattern | Effect after Denim |
| --- | --- |
| Timelocks, cooldowns, and exit delays written as `block.number - start >= N` | Elapse in one tenth of the intended wall-clock time. |
| Vesting, emission, or difficulty schedules counted in blocks | Complete or retarget ten times faster in wall-clock time. |
| Per-block rate limits or caps that reset whenever `block.number` moves | Reset five times per second rather than once every two seconds, lifting the effective per-second limit ten times. |
| Deadlines set as `expirationBlock = block.number + N` | Expire in one tenth of the intended wall-clock time. |
| Governance voting delay and voting period in blocks, including `ERC20Votes` on the default block-number `clock()` | Voting windows shrink ten times. Stored checkpoints stay correct. |
| Uniswap V3 style TWAP oracles | The averages stay correct, because the accumulators weight by seconds rather than by blocks. The catch is history depth: a fixed observation cardinality now spans roughly half the wall-clock window it used to, so a long `observe()` lookback starts reverting with `OLD` earlier than it did. |
Logic that measures time with `block.timestamp` is unaffected, which is the cheapest fix where a redeploy is possible.
Four ways to prepare, roughly in order of preference:
- Swap block-count durations for `block.timestamp` comparisons anywhere you can redeploy or upgrade.
- Where the block count is governance-tunable, queue a change that divides it by ten at activation.
- Where the count is immutable and cannot be changed, work out the blast radius now and plan a migration rather than discovering it on activation day.
- Exercise the new behaviour on [vibenet](/introduction/connecting-to-base/), which already seals 200ms blocks.
## Execution
### Full block timestamp
Because the header keeps whole seconds, a block's real time comes from combining the header with the BaseTime deposit that sits at `tx[1]`:
```
T_ms(b) = 1000 * b.header.timestamp + b.tx[1].timestamp_millis_part
```
Only five values of `timestamp_millis_part` are legal: `0`, `200`, `400`, `600`, and `800`. Any two consecutive activated blocks must be exactly 200ms apart:
```
T_ms(child) = T_ms(parent) + 200
```
Slots cannot be skipped, and the two halves of the timestamp must come from one scheduled slot rather than being assembled independently. When the sequencer actually begins building has no bearing on the timestamp the block carries — the schedule decides that, not the wall clock. Contracts see no difference here: EVM `block.timestamp` still reports the whole-second header value.
### The BaseTime metadata deposit
Every block after activation carries one BaseTime update at `tx[1]`. It follows the L1 information deposit at `tx[0]` and precedes all user transactions. Source-hash domain `3` binds the deposit to the block number it belongs to.
| Field | Value |
| --- | --- |
| Transaction type | Deposit (`0x7e`) |
| Source hash | Domain `3`, bound to the current block number |
| From | `0xDeaDDEaDDeAdDeAdDEAdDEaddeAddEAdDEAd0001` |
| To | `0x4200000000000000000000000000000000000030` |
| Mint | `0` |
| Value | `0` |
| Gas limit | `1,000,000` |
| System transaction | `false` |
| Calldata | `setTimestampMillisPart(uint16)` with selector `0x86bdf394` and a 32-byte ABI-encoded millisecond part |
The rule runs both ways. A block built before activation must carry neither this deposit nor the Engine millisecond field. Once activated, implementations check the transaction end to end: its position in the block, the value it writes, the shape of its calldata, its system flag and gas limit, the mint and value it declares, its recipient and sender, and its source hash.
### The BaseTime predeploy
Contracts that need the current millisecond part read it from a predeploy.
| Property | Value |
| --- | --- |
| Proxy | `0x4200000000000000000000000000000000000030` |
| Implementation | `0xc0D3C0d3C0d3C0D3c0d3C0d3c0D3C0d3c0d30030` |
| Storage | `uint16` millisecond part in slot `0` |
| Setter | `setTimestampMillisPart(uint16)` |
| Millisecond-part getter | `timestampMillisPart()` |
| Full-timestamp getter | `timestampMs()` |
Ordering is what makes the value trustworthy inside a block, and it also bounds where the value can be trusted. The deposit sits at `tx[1]`, immediately after the L1-info deposit and ahead of both user deposits and sequencer transactions. Everything from `tx[2]` onward therefore reads the current block's millisecond part.
`tx[0]` is the exception, and it is a real one. The L1-info deposit executes before BaseTime updates, so a `timestampMs()` read during `tx[0]` returns the current block's seconds combined with the *previous* block's stored millisecond part. For a run of consecutive 200ms blocks that value is 200ms behind inside the same second, and 800ms ahead at the second rollover — so it is not merely stale, it can read later than the block it belongs to. The L1-info execution path is specified not to depend on the current block's millisecond part for this reason. Treat `tx[0]` as having no trustworthy millisecond source.
A chain starting fresh gets the linked predeploy in genesis. On a chain that already exists, the reserved address holds the canonical proxy runtime under the Base ProxyAdmin, but with no implementation set — calls to it revert until Denim activates. Activation installs the canonical implementation and links the proxy before any transaction executes, and it leaves both the proxy admin and any implementation that governance already set in place.
### Engine payload attributes
The Engine API carries `BasePayloadAttributes`, which lays the standard `PayloadAttributes` fields out alongside the Base-specific ones.
At or after activation, `BasePayloadAttributes.timestampMillisPart` **MUST** be present and hold one of `0`, `200`, `400`, `600`, or `800`. Before activation it **MUST NOT** appear at all.
`BasePayloadAttributes.transactions[1]` **MUST** hold the BaseTime deposit. The protocol depositor **MUST** be its sender and the BaseTime predeploy its recipient, and the calldata **MUST** be a canonical encoding of `setTimestampMillisPart(uint16)` whose argument matches `timestampMillisPart`.
Two failure paths are specified separately. Payload attributes that arrive malformed on `forkchoiceUpdated` **MUST** draw a JSON-RPC `Invalid params` error (`-32602`). A payload whose BaseTime deposit is missing or wrong **MUST** instead be reported invalid during `newPayload` validation.
Payload IDs fold in `timestampMillisPart`, so two builds that differ only by millisecond part get distinct IDs. Omit the field and the legacy ID calculation applies unchanged. Every Engine timestamp field otherwise stays in seconds.
### Validation
The checks split across two moments, because headers carry no milliseconds.
On `forkchoiceUpdated` the execution client validates what it can without touching contract state: the millisecond part is absent before Denim, present and one of the five legal values after, and the whole-second timestamp is not behind the parent's.
The 200ms spacing can only be confirmed once the block has executed and the deposit is readable. At that point the client **MUST** confirm the full timestamp lands exactly 200ms past the parent's. A block that misses is invalid.
## Derivation
### Scheduled timestamps
After activation, derivation computes timestamps from the Denim schedule and the absolute L2 block number. It reads the millisecond part neither from batch data nor from the local clock, which is what keeps the result deterministic. Blocks walk the second in five steps:
`p (.000)` → `child (.200)` → `child (.400)` → `child (.600)` → `child (.800)` → `child (.000 in the next second)`
The pipeline takes that scheduled timestamp, splits it into the header's seconds and the BaseTime millisecond part, and rebuilds the deposit at `tx[1]`.
### Block lifecycle
Each selected 200ms slot gets a full build and execution pass. What comes out is a whole block, not a fragment of one: its own state root and hash, its own receipts, its own Engine payload and forkchoice update, and its own walk from unsafe to safe to finalized.
Two deposits lead the transaction list — L1 information first at `tx[0]`, BaseTime next at `tx[1]` — and user transactions, plus anything else that applies, follow them. By design the payload attribute, the deposit at `tx[1]`, and the value written into the predeploy all describe the same planned millisecond part.
## RPC
### Seconds stay put
Existing integrations keep working because `timestamp` stays in Unix seconds. So does everything around it: what the EVM reports as `block.timestamp`, what `eth_call` sees, the timestamps that decide transaction validity, and the ones the Engine API carries. The internal `timestampMillisPart` field is never surfaced over RPC at all.
For sub-second updates after the rollout, read canonical blocks and subscriptions such as `eth_subscribe("newHeads")`. Flashblocks streams stop.
### Block and header timestamps
An optional `timestampMs` gets added to the responses below, encoded as a JSON-RPC quantity holding the full Unix timestamp in milliseconds:
- `eth_getBlockByHash`
- `eth_getBlockByNumber`
- `eth_getHeaderByHash`
- `eth_getHeaderByNumber`
- `eth_subscribe("newHeads")`
A block at 42.200 seconds reports:
| Field | Value |
| --- | --- |
| `timestamp` | `0x2a` |
| `timestampMs` | `0xa4d8` |
Clients are expected to take `timestampMs` from authenticated BaseTime metadata instead of guessing it from the seconds field. Where a historical block body or its metadata has been pruned or is otherwise missing, the field is left out rather than approximated.
### Transaction timestamps
Mined transaction objects gain an optional `blockTimestampMs` from:
- `eth_getTransactionByHash`
- `eth_getTransactionByBlockHashAndIndex`
- `eth_getTransactionByBlockNumberAndIndex`
Full transaction objects nested inside block responses behave the same way. Pending transactions omit the field, since they have no canonical block to take a timestamp from.
### Log and receipt timestamps
Mined logs gain the same optional `blockTimestampMs` when returned by:
- `eth_getLogs`
- `eth_getFilterChanges`
- `eth_getFilterLogs`
- `eth_getTransactionReceipt`
- `eth_getBlockReceipts`
- `eth_subscribe("logs")`
- `eth_subscribe("transactionReceipts")`
Receipts place the field one level down, on each nested log, and never on the receipt object itself. Should a log be removed, it keeps the block timestamp and the provenance it was first given. When the originating block's authenticated metadata cannot be read, the field is dropped instead of estimated.
Pruned or unprovenanced transaction and log data behaves the same way. Keeping all of these optional is what lets pre-Denim history, and clients lacking the body data, still be represented.
### Tooling
Foundry can carry an unknown block-level `timestampMs` through its `AnyRpcBlock` and `OtherFields` paths while EVM execution keeps working in seconds. Plain Alloy `AnyRpcHeader` discards unknown fields, so anything that needs Denim timestamps should reach for `WithOtherFields` or a typed Base response instead. Anvil is not expected to attach BaseTime metadata to locally mined blocks in the first rollout.
## What this means for integrators
Applications reading Flashblocks preconfirmations are the ones with work to do, because that stream goes away rather than changing shape. The replacement is the canonical block feed, which after Denim arrives at the same 200ms cadence the Flashblocks stream did — with the difference that each update is a sealed block rather than a preview of a pending one.
Code that only reads `timestamp` needs no change. Code that needs millisecond resolution reads `timestampMs` on blocks and headers, or `blockTimestampMs` on transactions and logs, and must tolerate the field being absent for older or pruned data.
---
# Denim Upgrade Overview
Source: https://basehub.org/specifications/denim-overview/
Description: Summary of the Denim hardfork — canonical 200ms blocks, onchain millisecond time through the BaseTime predeploy, and millisecond-resolution RPC timestamps.
import { Aside } from '@astrojs/starlight/components';
Denim is the Base hardfork that follows [Cobalt](/specifications/cobalt-overview/). It is a single idea expressed three ways: Base seals blocks five times per second instead of once every two seconds, the chain gains a millisecond clock that contracts can read, and RPC responses learn to report time at that resolution.
## Status
| Network | Status | Target |
|---|---|---|
| Base Sepolia | Scheduled | October 21, 2026 at 18:00 UTC (`1792605600`) |
| Base Mainnet | Pinned in node source | November 5, 2026 at 18:00 UTC (`1793901600`) |
| vibenet | Live for experimental testing | Available to preview today |
## What Denim ships
- **200ms native blocks** — block production goes from one canonical block every two seconds to five per second, each a complete block with its own number, hash, state root, receipts, and forkchoice lifecycle. This retires [Flashblocks](/flashblocks/overview/). Full detail in [Denim 200ms Native Blocks](/specifications/denim-200ms-blocks/).
- **BaseTime** — a predeploy that carries the sub-second part of each block's timestamp, supplied by a metadata deposit. Contracts can read the current block's millisecond component while EVM `block.timestamp` stays whole-second.
- **Millisecond RPC timestamps** — blocks, headers, transactions, logs, and receipts gain optional `timestampMs` and `blockTimestampMs` fields derived from authenticated BaseTime metadata. The existing seconds-based `timestamp` field does not change.
- **Longer sequencer drift** — the maximum sequencer drift rises from `1800` seconds to `21600` (six hours), so the sequencer can keep building on an old L1 origin through a much longer L1 RPC outage before it must stop including user transactions. As with the Fjord value, the L1 origin's timestamp picks which limit applies, not the L2 block's (#5696).
- **B20 policy and receiver changes** — the node source also gates two B20 changes on Denim, and upstream added them to the fork page on 2026-09-29, flagging the receiver and executor changes as breaking. The policy registry gains inverted policy IDs (bit 63 as a NOT flag, plus `invertedPolicyId`). Tokens also refuse to credit their own address. Both are in [Arriving with Denim](/api-reference/b20-precompiles/#arriving-with-denim). A third change, B20 logic version 3, enforces `TRANSFER_EXECUTOR_POLICY` on every transfer path, including a holder's own `transfer`; see [B20 Issuer Operations](/integration-guides/b20-issuer-operations/#limit-who-may-initiate-transfers).
## Why the header does not change
The obvious way to seal blocks every 200ms would be to make the Ethereum header timestamp finer-grained. Denim does not do that. `block.header.timestamp` stays Unix time in whole seconds, and a BaseTime metadata deposit at `tx[1]` supplies the sub-second piece, restricted to `0`, `200`, `400`, `600`, or `800`. Reading both together gives the block's millisecond timestamp.
Keeping the header intact is what lets existing tooling stay standing. Contracts observe no change, because EVM `block.timestamp` still reports the whole-second header value. The cost is that anything wanting millisecond precision has to read the BaseTime deposit or the new optional RPC fields rather than the header alone.
## Flashblocks retirement
Flashblocks publish incremental previews of pending state inside a two-second block. Once the 200ms interval is a real block, that preview layer has nothing left to do, so Base stops producing Flashblocks as part of the Denim rollout.
## A note on naming
Denim briefly lost 200ms blocks to Cobalt in early September 2026, then got them back a week later. The node source stayed put across both moves: `is_denim_active_at_timestamp` has gated every block-timing path throughout, and the BaseTime helper sits under the same gate. Documentation written during that window may attribute 200ms blocks to Cobalt. The mechanics described here are unaffected by which name is attached.
---
# Everest Upgrade Overview
Source: https://basehub.org/specifications/everest-overview/
Description: Summary of the Everest hardfork, which adds Base Transactions (EIP-8430), a native transaction type for batching, gas sponsorship, token gas payments, and parallel nonces.
import { Aside } from '@astrojs/starlight/components';
Everest is the Base hardfork planned after [Denim](/specifications/denim-overview/). Upstream added it to the upgrades tracker on 2026-10-13. It has one feature: [Base Transactions](/specifications/base-transactions/), the new transaction type from EIP-8430.
## Status
| Network | Status | Target |
|---|---|---|
| Base Sepolia | Planning | No date |
| Base Mainnet | Planning | No date |
## What Everest ships
- **Base Transactions (EIP-8430)** - a typed transaction (`0x79`) that lets an ordinary EOA batch calls into atomic phases, have a sponsor pay its gas, pay that sponsor back in a token, and run parallel or nonce-free lanes. It can also set EIP-7702-style delegation. Nodes check one secp256k1 signature for each role and never run wallet code, so no bundler or relay is involved. The full format, gas table, and RPC changes are in [Base Transactions](/specifications/base-transactions/).
## Where native account abstraction went
For most of 2026, Base described this work as native account abstraction under EIP-8130. Cobalt was to carry it, then Denim, and from September it had no fork at all (see [What moved out of Cobalt](/specifications/cobalt-overview/#what-moved-out-of-cobalt)). Everest gives the transaction type a fork again, but in a smaller form.
EIP-8430 is the transaction part of EIP-8130, split out on its own. The onchain actor and authenticator model, with P-256 and WebAuthn passkeys, is not in it. In the node, the gate for this transaction type moved from `zenith` to `is_everest_active_at_timestamp`. The txpool and the RPC layer both check it, and the EVM sets up the Nonce Manager system account at the same fork. Account creation and signed config batches are still in the source as entry types `0x02` and `0x03`. Comments mark them as valid only under Zenith, which stays a test-only gate with no canonical schedule. The background is in [Native Account Abstraction](/architecture/native-account-abstraction/).
## Related pages
- [Base Transactions](/specifications/base-transactions/)
- [Denim Upgrade Overview](/specifications/denim-overview/)
- [Cobalt Upgrade Overview](/specifications/cobalt-overview/)
---
# Flashblocks Specification
Source: https://basehub.org/specifications/flashblocks/
Description: JSON-RPC methods, parameters, and return types exposed by the Flashblocks RPC provider.
The Flashblocks RPC provider extends standard Ethereum JSON-RPC methods to query preconfirmed flashblock state via the `pending` tag. The methods, parameters, and return types are specified below.
:::note
This document serves as a reference for the current implementation and may differ from the full Flashblocks specification in terms of scope and methods implemented. The canonical source is [`docs/specs/flashblocks.md`](https://github.com/base/base/blob/main/docs/specs/flashblocks.md) in the base/base repository.
:::
## Type Definitions
All types used in these RPC methods are identical to the standard OP Stack RPC types. No modifications have been made to the existing type definitions.
## Modified Ethereum JSON-RPC Methods
The following standard Ethereum JSON-RPC methods are enhanced to support the `pending` tag for querying preconfirmed state.
### `eth_getBlockByNumber`
Returns block information for the specified block number.
#### Parameters
| Name | Type | Description |
|------|------|-------------|
| `blockNumber` | `String` | Block number (hex) or tag. Use `"pending"` for preconfirmed state. |
| `fullTransactions` | `Boolean` | If `true`, returns full transaction objects; if `false`, returns transaction hashes. |
#### Returns
`Object` -- Block object, or `null` if the block does not exist.
#### Example
```json
// Request
{
"method": "eth_getBlockByNumber",
"params": ["pending", false],
"id": 1,
"jsonrpc": "2.0"
}
// Response
{
"id": 1,
"jsonrpc": "2.0",
"result": {
"hash": "0x0000000000000000000000000000000000000000000000000000000000000000",
"parentHash": "0x...",
"stateRoot": "0x...",
"transactionsRoot": "0x...",
"receiptsRoot": "0x...",
"number": "0x123",
"gasUsed": "0x5208",
"gasLimit": "0x1c9c380",
"timestamp": "0x...",
"extraData": "0x",
"mixHash": "0x...",
"nonce": "0x0",
"transactions": ["0x..."]
}
}
```
#### Response Fields
| Field | Description |
|-------|-------------|
| `hash` | Block hash calculated from the current flashblock header. |
| `parentHash` | Hash of the parent block. |
| `stateRoot` | Current state root from the latest flashblock. |
| `transactionsRoot` | Transactions trie root. |
| `receiptsRoot` | Receipts trie root. |
| `number` | Block number being built. |
| `gasUsed` | Cumulative gas used by all transactions. |
| `gasLimit` | Block gas limit. |
| `timestamp` | Block timestamp. |
| `extraData` | Extra data bytes. |
| `mixHash` | Mix hash value. |
| `nonce` | Block nonce value. |
| `transactions` | Array of transaction hashes or full transaction objects. |
---
### `eth_getTransactionReceipt`
Returns the receipt for a transaction. When the transaction exists only in the preconfirmed (flashblock) state, the receipt is still returned -- enabling callers to confirm inclusion before the block is finalized.
#### Parameters
| Name | Type | Description |
|------|------|-------------|
| `transactionHash` | `String` | Hash of the transaction. |
#### Returns
`Object` -- Transaction receipt, or `null` if the transaction is not found.
#### Example
```json
// Request
{
"method": "eth_getTransactionReceipt",
"params": ["0x..."],
"id": 1,
"jsonrpc": "2.0"
}
// Response
{
"id": 1,
"jsonrpc": "2.0",
"result": {
"transactionHash": "0x...",
"blockHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
"blockNumber": "0x123",
"transactionIndex": "0x0",
"from": "0x...",
"to": "0x...",
"gasUsed": "0x5208",
"cumulativeGasUsed": "0x5208",
"effectiveGasPrice": "0x...",
"status": "0x1",
"contractAddress": null,
"logs": [],
"logsBloom": "0x..."
}
}
```
#### Response Fields
| Field | Description |
|-------|-------------|
| `transactionHash` | Hash of the transaction. |
| `blockHash` | Zero hash (`0x000...000`) for preconfirmed transactions. |
| `blockNumber` | Block number containing the transaction. |
| `transactionIndex` | Index of the transaction in the block. |
| `from` | Sender address. |
| `to` | Recipient address. |
| `gasUsed` | Gas used by this transaction. |
| `cumulativeGasUsed` | Total gas used up to and including this transaction. |
| `effectiveGasPrice` | Effective gas price paid. |
| `status` | `0x1` for success, `0x0` for failure. |
| `contractAddress` | Address of created contract (for contract creation transactions), otherwise `null`. |
| `logs` | Array of log objects emitted by the transaction. |
| `logsBloom` | Bloom filter for the logs. |
---
### `eth_getBalance`
Returns the balance of an account.
#### Parameters
| Name | Type | Description |
|------|------|-------------|
| `address` | `String` | Address to query. |
| `blockNumber` | `String` | Block number (hex) or tag. Use `"pending"` for preconfirmed state. |
#### Returns
`String` -- Account balance in wei, hex-encoded.
#### Example
```json
// Request
{
"method": "eth_getBalance",
"params": ["0x...", "pending"],
"id": 1,
"jsonrpc": "2.0"
}
// Response
{
"id": 1,
"jsonrpc": "2.0",
"result": "0x1bc16d674ec80000"
}
```
---
### `eth_getTransactionCount`
Returns the number of transactions sent from an address (the account nonce).
#### Parameters
| Name | Type | Description |
|------|------|-------------|
| `address` | `String` | Address to query. |
| `blockNumber` | `String` | Block number (hex) or tag. Use `"pending"` for preconfirmed state. |
#### Returns
`String` -- Transaction count (nonce), hex-encoded.
#### Example
```json
// Request
{
"method": "eth_getTransactionCount",
"params": ["0x...", "pending"],
"id": 1,
"jsonrpc": "2.0"
}
// Response
{
"id": 1,
"jsonrpc": "2.0",
"result": "0x5"
}
```
---
## Behavior Notes
### Pending Tag Usage
- When `"pending"` is used as the block tag, the method queries preconfirmed state from the flashblocks cache.
- If no preconfirmed data is available, the method falls back to the latest confirmed state.
- For non-pending queries (e.g., `"latest"`, `"finalized"`, or a specific block number), the method behaves identically to standard Ethereum JSON-RPC.
### Error Handling
- Standard JSON-RPC error responses are returned for invalid requests.
- `null` is returned for non-existent transactions or blocks.
- When flashblocks are disabled or unavailable, the RPC falls back to standard behavior transparently.
## Source
Canonical specification: [docs/specs/flashblocks.md](https://github.com/base/base/blob/main/docs/specs/flashblocks.md)
---
# Glamsterdam EIP Port (Design)
Source: https://basehub.org/specifications/glamsterdam/
Description: Draft plan for which Ethereum Glamsterdam EIPs Base would adopt, which it would modify, and which it would leave out, including block-level access lists, SLOTNUM, and a 128 gas/byte calldata floor.
import { Aside } from '@astrojs/starlight/components';
Glamsterdam is Ethereum's next L1 upgrade (meta-EIP [7773](https://eips.ethereum.org/EIPS/eip-7773)). On 2026-10-16, base/base added a design document (#5759) that sorts each Glamsterdam EIP into one of three buckets for Base: take it unchanged, take it with Base-specific changes, or skip it. This page summarizes that plan.
## Open items
Upstream lists four decisions that are still pending:
- **Base Transactions (EIP-8430):** pricing for the new transaction type is not yet defined. See [Base Transactions](/specifications/base-transactions/).
- **State creation (EIP-8037):** Base has not picked its per-byte gas price for newly created state.
- **State access (EIP-8038):** the account and storage access and write prices for Base are undecided.
- **BAL bandwidth:** a comparison of payload sizes with and without block-level access lists, both raw and compressed, has not been done yet.
## EIPs Base would modify
| EIP | What it does on L1 | Base's planned change |
|---|---|---|
| [7928](https://eips.ethereum.org/EIPS/eip-7928) | Block-level access lists (BALs): each block records the state it read and wrote, which enables parallel execution and quicker state processing. | Ship the BAL inside gossiped Base blocks, leave it out of L1 batches, and rebuild it during CL sync. See [design](#block-level-access-lists-eip-7928). |
| [2780](https://eips.ethereum.org/EIPS/eip-2780) | Replaces the flat per-transaction overhead with charges tied to the resources a transaction uses. | Extend the model to Base Transactions (EIP-8430), covering batching, sponsorship, and nonce modes. |
| [7843](https://eips.ethereum.org/EIPS/eip-7843) | Adds the `SLOTNUM` opcode and a matching header field for the consensus slot. | Report the L2 block number as the slot instead of the beacon slot. See [design](#slot-number-eip-7843). |
| [7976](https://eips.ethereum.org/EIPS/eip-7976) | Lifts the calldata floor to 64 gas per byte. | Use 128 gas/byte instead. See [design](#calldata-floor-eip-7976). |
| [8037](https://eips.ethereum.org/EIPS/eip-8037) | Reprices new state and meters state creation apart from execution. | Same mechanism; Base's state-byte price is still to be chosen. |
| [8038](https://eips.ethereum.org/EIPS/eip-8038) | Updates gas for account and storage accesses and writes. | Same mechanism; Base-specific values are still to be chosen. |
| [7981](https://eips.ethereum.org/EIPS/eip-7981) | Charges access lists for the data they carry. | Price at 128 gas/byte to line up with the calldata floor. See [design](#access-list-pricing-eip-7981). |
## EIPs Base would take unchanged
| EIP | Effect |
|---|---|
| [7708](https://eips.ethereum.org/EIPS/eip-7708) | Native ETH transfers produce a protocol-level log. |
| [7778](https://eips.ethereum.org/EIPS/eip-7778) | Block capacity counts execution gas before refunds, while users still receive their refunds. |
| [7954](https://eips.ethereum.org/EIPS/eip-7954) | Deployed code may be up to 64 KiB and initcode up to 128 KiB. |
| [7997](https://eips.ethereum.org/EIPS/eip-7997) | The standard `CREATE2` factory must exist at a shared address across EVM chains. |
| [8024](https://eips.ethereum.org/EIPS/eip-8024) | New `SWAPN`, `DUPN`, and `EXCHANGE` instructions reach deeper into the stack. |
| [8246](https://eips.ethereum.org/EIPS/eip-8246) | When an eligible self-destructed account is cleared, its leftover ETH is kept rather than burned. |
| [7975](https://eips.ethereum.org/EIPS/eip-7975) | Networking: `eth/70` lets peers send long receipt lists in pieces. |
| [8159](https://eips.ethereum.org/EIPS/eip-8159) | Networking: `eth/71` adds request and response messages for BALs. |
| [8189](https://eips.ethereum.org/EIPS/eip-8189) | Networking: `snap/2` uses BALs to move forward and patch state during sync. |
## Design notes
### Block-level access lists (EIP-7928)
The two goals are fast validator sync, at the chain tip and for history, and keeping L1 blob usage low.
The planned data flow:
- **Sequencer:** builds each block and its BAL together. It gossips the payload and BAL as one unit, but posts only the transactions to L1.
- **Unsafe sync (P2P):** a validator receives the payload with its BAL, executes the block, and checks the BAL against the result.
- **Safe sync (CL):** a validator derives block inputs from L1. If they match a block it has already validated, it reuses that execution and promotes the block to safe. If there is no match, it treats the case as a reorg, replays the block, and rebuilds the BAL.
- **Historical sync (EL):** a validator pulls blocks, state, and BALs from other nodes over `eth/71` and `snap/2`, then catches up and verifies state.
Two deliberate departures from L1:
- **BAL travels inside the block.** On Base the BAL sits in the gossiped execution payload instead of a separate sidecar, so a validator never needs a second fetch. The cost is more peer bandwidth, which upstream accepts because validators are expected to run on data-center links.
- **No BALs in L1 blobs.** Batches carry transactions only. Any BAL can be rebuilt by execution, including deposits and system inputs that come from L1. The trade-off is slower CL sync during unusual recovery. In normal operation, history uses EL sync and CL reconciliation matches blocks that were already validated, so the replay cost rarely applies. Base avoids paying blob fees for a BAL on every block.
### Slot number (EIP-7843)
| Option | Upside | Downside | Fits |
|---|---|---|---|
| **L2 block number (recommended)** | Easy to validate; every Base block gets its own slot; leaves space for a later Base slot counter that also advances over skipped blocks. | Duplicates what `NUMBER` already returns. | Scheduling local execution or tracking recent state per L2 block. |
| **Beacon slot of the L1 origin** | Matches the OP precedent for L1 consensus data (as with EIP-4399 and EIP-4788). | Many L2 blocks share one slot, and it only moves when the L1 origin moves. | Lining up with Ethereum oracle reporting windows or beacon-proof slots. |
### Calldata floor (EIP-7976)
The floor formula is:
`charged gas = max(txn cost, base_tx_cost + bytes * constant)`
Upstream recommends **`constant = 128` gas/byte**, applied to zero and nonzero bytes alike. Compared with L1's 64, that halves the worst-case calldata size and growth, and in the sampled transactions nobody pays more.
The ranking used to pick the number, highest priority first:
1. Do not price out payments, swaps, and other everyday transactions.
2. Cap the worst-case size of incompressible blocks on the P2P network.
3. Keep yearly calldata growth manageable.
#### Effect on sample transactions
Receipt gas for five real Base Mainnet transactions under different floors. Bold cells are where the floor starts to bind.
| Constant (gas/byte) | USDC payment (68 B) | Aerodrome Router (324 B) | Slipstream (260 B) | Uniswap Router02 (228 B) | Universal Router (644 B) |
|---|---|---|---|---|---|
| 64 | 40,271 | 181,916 | 186,366 | 105,413 | 171,148 |
| **128** (recommended) | 40,271 | 181,916 | 186,366 | 105,413 | 171,148 |
| 256 | 40,271 | 181,916 | 186,366 | 105,413 | **185,864** |
| 512 | **49,816** | 181,916 | 186,366 | **137,736** | **350,728** |
| 1,024 | **84,632** | **346,776** | **281,240** | **254,472** | **680,456** |
At 128 none of the five samples changes. The first sample to pay more is the Universal Router swap at 256.
#### Block size and storage growth
Under today's pricing, worst-case calldata per block is large. At 400M gas per 2-second block, zero bytes at 10 gas allow 40 MB per block (105.12 TB a year); nonzero bytes at 40 gas allow 10 MB (26.28 TB a year). Denim's 40M gas per 200 ms block cuts the per-block figures by ten (4 MB and 1 MB) but leaves the yearly growth the same.
With a floor in place, at a 200M gas/s limit and 33.33M gas/s target:
| Floor | Max calldata/block | Yearly growth | Gas to fill 10 MiB |
|---|---|---|---|
| 64 gas | 625 kB | 16.43 TB | ~671M |
| **128 gas** | **312.5 kB** | **8.21 TB** | **~1.34B** |
| 256 gas | 156.25 kB | 4.11 TB | ~2.68B |
| 512 gas | 78.13 kB | 2.05 TB | ~5.37B |
At a 1G gas/s limit and 166.67M gas/s target, the 128 gas row becomes 1.56 MB per block and 41.06 TB a year.
### Access-list pricing (EIP-7981)
Access lists take block space just like calldata, so they get the same **128 gas/byte** rate. Otherwise they would be a cheaper side door for stuffing data into a block.
| Entry | Bytes | L1 surcharge (64 gas/byte) | Base surcharge (128 gas/byte) |
|---|---|---|---|
| Address | 20 | 1,280 gas | 2,560 gas |
| Storage key | 32 | 2,048 gas | 4,096 gas |
## EIPs Base would leave out
| EIP | Topic | Why it does not apply |
|---|---|---|
| [7688](https://eips.ethereum.org/EIPS/eip-7688) | Forward-compatible consensus data structures | Changes beacon-chain structures, not Base execution. |
| [7732](https://eips.ethereum.org/EIPS/eip-7732) | Enshrined proposer-builder separation | Base sequencing does not use Ethereum's proposer and builder roles. |
| [8045](https://eips.ethereum.org/EIPS/eip-8045) | Bar slashed validators from proposing | Base does not pick L2 block proposers from Ethereum validators. |
| [8061](https://eips.ethereum.org/EIPS/eip-8061) | Higher exit and consolidation churn | Staking queues sit outside the Base protocol. |
| [8282](https://eips.ethereum.org/EIPS/eip-8282) | Builder execution requests | Manages staked ePBS builders, which Base does not have. |
| [8070](https://eips.ethereum.org/EIPS/eip-8070) | `eth/72` sparse blobpool | Base posts blobs to L1 and runs no L2 blob pool. |
| [8136](https://eips.ethereum.org/EIPS/eip-8136) | Cell-level deltas for data column broadcast | PeerDAS networking on L1; Base gains only indirectly through L1 DA. |
| [7904](https://eips.ethereum.org/EIPS/eip-7904) | Compute gas cost analysis | Informational; no protocol change to adopt. |
| [8261](https://eips.ethereum.org/EIPS/eip-8261) | Gas limit schedule | Informational; Base sets its L2 gas limit on its own. |
## Related pages
- [Base Transactions](/specifications/base-transactions/)
- [Everest Upgrade Overview](/specifications/everest-overview/)
- [Denim Upgrade Overview](/specifications/denim-overview/)
- [Access Lists](/specifications/access-lists/)
- [Original design doc (base/base)](https://github.com/base/base/blob/main/docs/guides/GLAMSTERDAM.md)
---
# Glossary
Source: https://basehub.org/specifications/glossary/
Description: Definitions for the terms used throughout the Base Chain protocol specification — from L1/L2 basics to sequencing, deposits, withdrawals, batch submission, derivation, and the execution engine.
This page collects the vocabulary used across the Base Chain protocol specs. Terms are grouped by topic; many definitions cross-reference each other, so the same word may appear in more than one section.
## General terms
### Layer 1 (L1)
Shorthand for the Ethereum blockchain. It is the counterpart to [layer 2](#layer-2-l2), which here means Base.
### Layer 2 (L2)
Shorthand for Base Chain — the rollup described by this specification. It sits on top of [layer 1](#layer-1-l1), the Ethereum settlement layer.
### Block
A term that applies to both L1 and L2 blocks, which share the same overall shape.
A block bundles an ordered list of transactions together with header fields. Some of those fields are *inputs* — known before the block's transactions run — while others are *outputs* derived only after execution. The output fields include several [Merkle Patricia Trie](#merkle-patricia-trie) roots that commit to the post-execution L2 state and to the logs emitted while the block ran. The Ethereum yellow paper (section 4.3) documents the full set of header properties.
### EOA
Short for "Externally Owned Account." It denotes an address controlled directly by a user's key, in contrast to a contract address.
### Merkle Patricia Trie
A Merkle Patricia Trie (MPT) is a sparse, tree-shaped map from keys to values. Its root hash commits to everything stored in the tree, which means you can produce a Merkle proof for any key-value pair it contains and check that proof against the root.
### Chain re-organization
A re-organization — "re-org" for short — happens when the head of a chain switches, according to the [fork choice rule](#fork-choice-rule), to a block that is not a direct child of the previous head.
On L1 these arise from network conditions or attacks. On L2 they are downstream effects of L1 re-orgs, propagated through [L2 chain derivation](#l2-chain-derivation).
### Predeployed contract ("predeploy")
A contract written into the L2 genesis state, so it exists from the very first block of the chain. The full set lives in the predeploys specification.
### Preinstalled contract ("preinstall")
Like a predeploy, a preinstall is seeded into the L2 genesis state. Unlike predeploys, preinstalls do not carry the same security guarantees; they are general-purpose contracts included to improve L2 user experience. The full set lives in the preinstalls specification.
### Precompiled contract ("precompile")
A contract implemented natively inside the EVM that runs a particular operation faster than an equivalent bytecode (for example, Solidity) version would. Precompiles live at fixed addresses and are introduced or changed only through network upgrades. The full set lives in the precompiles specification.
### Receipt
A receipt is what a transaction emits as a record of its execution: a status code, the gas it consumed, its log entries, and a [bloom filter](https://en.wikipedia.org/wiki/Bloom_filter) over those entries. Log entries are the mechanism behind Solidity events.
Blocks do not embed receipts directly; instead each block stores a [Merkle Patricia Trie](#merkle-patricia-trie) root over the tree of every transaction receipt in that block. Receipts are defined in the yellow paper, section 4.3.1.
### Transaction type
[EIP-2718](https://eips.ethereum.org/EIPS/eip-2718) defines a scheme for distinguishing transaction types. Each type may carry a different payload and be processed under different rules by the protocol.
### Fork choice rule
The rule that picks which block counts as the head of a chain. On L1 the choice follows the proof-of-stake rules.
L2 has its own fork choice logic, and which block it selects depends on whether you are asking for the [safe](#safe-l2-head), [unsafe](#unsafe-l2-head), or [finalized](#finalized-l2-head) L2 head.
### Priority gas auction
Ethereum orders transactions by the price they pay for inclusion. A Priority Gas Auction (PGA) breaks out when several parties race to occupy the first slot in a block, each repeatedly bumping the gas price on their transaction. PGAs appear wherever being first carries value — being the earliest deposit, say, or landing a deposit before the guaranteed gas runs out. Because they generate a flood of transactions in a tiny time window, PGAs impose negative externalities on the network.
## Sequencing
A rollup transaction reaches the chain by one of two routes:
- As a [deposited transaction](#deposited-transaction), which the system itself enforces.
- As an ordinary transaction packed into a [sequencer batch](#sequencer-batch).
Routing transactions through a batch trims overhead and lets the sequencer pre-confirm them ahead of L1 posting the underlying data.
### Sequencer
The sequencer is either a [rollup node](#rollup-node) operating in sequencer mode, or the party running that node.
It is a privileged role: it takes L2 transactions from users, assembles them into L2 blocks, and forwards those blocks to a [data availability provider](#data-availability-provider) by way of a [batcher](#batcher). It also posts [output roots](#l2-output-root) to L1.
### Sequencing window
A sequencing window is the span of L1 blocks that a single [sequencing epoch](#sequencing-epoch) is derived from.
If a window opens at L1 block `N`, it holds the [batcher transactions](#batcher-transaction) for epoch `N` and spans blocks `[N, N + SWS)`, with `SWS` the sequencer window size. The default `sws` is 3600 epochs. The window's first block also fixes the [depositing transactions](#depositing-transaction) that decide which [deposits](#deposits) go into the epoch's first L2 block.
### Sequencing epoch
A sequencing epoch is the consecutive run of L2 blocks derived from one [sequencing window](#sequencing-window) of L1 blocks. Its epoch number equals the block number of the window's first L1 block. Epochs may vary in length within defined limits; the L2 chain derivation spec covers the constraints.
### L1 origin
The L1 origin of an L2 block is the L1 block tied to that block's [sequencing epoch](#sequencing-epoch).
## Deposits
Broadly, a deposit is an L2 transaction that the [rollup driver](#rollup-driver) derives from an L1 block.
Deposits are commonly — though not exclusively — used to bridge ETH and tokens onto L2, but the word should be read as "a transaction *deposited* to L2 from L1." Because these "transactions" surface at several layers, the term is ambiguous; the entries below pin down the variants. A *deposit* can mean:
- A [deposited transaction](#deposited-transaction) on L2 belonging to a deposit block.
- A [depositing call](#depositing-call) that triggers a deposited transaction to be derived.
- The log/event data produced by that depositing call, which the rollup driver reads in order to derive the deposited transaction.
The phrase *user deposit* is similar but deliberately leaves out [L1 attributes deposited transactions](#l1-attributes-deposited-transaction).
### Deposited transaction
An L2 transaction derived from L1 and placed into an L2 block. Two kinds exist:
- The [L1 attributes deposited transaction](#l1-attributes-deposited-transaction), which records the L1 block's attributes into the [L1 Attributes Predeployed Contract](#l1-attributes-predeployed-contract).
- [User-deposited transactions](#user-deposited-transaction), derived from an L1 call into the [deposit contract](#deposit-contract).
### L1 attributes deposited transaction
A [deposited transaction](#deposited-transaction) that writes the attributes of an L1 block — its number, timestamp, and so on — onto L2 by calling the [L1 Attributes Predeployed Contract](#l1-attributes-predeployed-contract). Other contracts can then read those attributes for the L1 block matching the current L2 block.
### User-deposited transaction
A [deposited transaction](#deposited-transaction) produced from an L1 [depositing call](#depositing-call) into the [deposit contract](#deposit-contract).
### Depositing call
An L1 call into the [deposit contract](#deposit-contract) that the [rollup driver](#rollup-driver) turns into a [user-deposited transaction](#user-deposited-transaction). The call supplies every field the resulting deposited transaction needs — destination, value, calldata, and the rest.
### Depositing transaction
An L1 transaction that issues one or more [depositing calls](#depositing-call).
### Depositor
The L1 account — contract or [EOA](#eoa) — that is the `msg.sender` of the [depositing call](#depositing-call). The depositor is explicitly **not** the originator (`tx.origin`) of the surrounding depositing transaction.
### Deposited transaction type
The [EIP-2718](#transaction-type) transaction type that defines the input fields and processing rules for a [deposited transaction](#deposited-transaction).
### Deposit contract
An [L1](#layer-1-l1) contract that [EOAs](#eoa) and contracts send [deposits](#deposits) to. It emits each deposit as a log record — a Solidity event — for [rollup nodes](#rollup-node) to consume.
One subtlety: deposits are not carried in calldata, because a deposit can originate from a contract. In that case the calldata is part of *internal* contract-to-contract execution and never lands in any of the [Merkle Patricia Trie](#merkle-patricia-trie) roots committed by the L1 block.
## Withdrawals
In general terms, a withdrawal is a transaction sent from L2 to L1 that can move data, value, or both.
As with deposits, the word spans multiple layers and is therefore imprecise. To keep the L1 and L2 halves distinct:
- A *withdrawal initiating transaction* is the L2 transaction sent to the withdrawals predeploy.
- A *withdrawal finalizing transaction* is the L1 transaction that finalizes and relays that withdrawal.
### Relayer
An L1 EOA that finalizes a withdrawal by submitting whatever data is needed to prove the withdrawal's inclusion on L2.
### Finalization period
The finalization period — also called the *withdrawal delay* — is the minimum number of seconds that must pass before a [withdrawal](#withdrawals) can be finalized. The delay exists to give [validators](#validator) enough time to mount a [fault proof](#fault-proof).
## Configuration
### Batch inbox
The **Batch Inbox** is the address that sequencer transaction batches are posted to. A sequencer publishes to it by naming it as the `to` address of a transaction whose batched L2 transactions ride in calldata or in blobdata.
### Batcher hash
The **Batcher Hash** marks which sender(s) the L2 clients of a given Base chain will accept transactions from at the [Batch Inbox](#batch-inbox).
Its first byte is a version tag. The V0 layout is a 32-byte hash structured as:
| 1 byte | 11 bytes | 20 bytes |
| -------------- | -------- | -------- |
| version (0x00) | empty | address |
Equivalently:
```solidity
bytes32(address(batcher))
```
Here `batcher` is the address that submits to the Batch Inbox. In short, the V0 hash names a *single* address whose batches the L2 clients will honor. Versioning the hash leaves room to later reinterpret it — for example as a commitment to an allowlist of accounts or some other batcher-identification scheme.
### Fee scalars
The **Fee Scalars** are the parameters that feed the L1 data fee charged on L2 transactions. They are also known as Gas Price Oracle (GPO) parameters.
#### Pre-Ecotone parameters
Prior to the Ecotone upgrade:
- **Scalar**: a multiplier over the L1 base fee, read as a big-endian `uint256`.
- **Overhead**: a fixed gas overhead, read as a big-endian `uint256`.
#### Post-Ecotone parameters
After Ecotone:
- **Scalar** packs extra scalar information using a versioned encoding.
- **Overhead** is disregarded and has no bearing on the L2 state-transition output.
#### Post-Ecotone scalar encoding
The Scalar is a big-endian `uint256` reinterpreted as `bytes32` and laid out as:
- Byte `0`: scalar-version byte.
- Bytes `[1, 32)`: contents depend on the scalar version:
- Scalar-version `0`:
- Bytes `[1, 28)`: padding, expected to be zero.
- Bytes `[28, 32)`: big-endian `uint32`, the L1-fee `baseFeeScalar`.
- Implies `blobBaseFeeScalar` is 0.
- If the padding region holds any non-zero byte, `baseFeeScalar` must be set to MaxUint32.
- Scalar-version `1`:
- Bytes `[1, 24)`: padding, must be zero.
- Bytes `[24, 28)`: big-endian `uint32`, the `blobBaseFeeScalar`.
- Bytes `[28, 32)`: big-endian `uint32`, the `baseFeeScalar`.
`baseFeeScalar` captures the user transaction's per-byte share of the total regular L1 EVM gas the batch-submitter's data transaction consumes; for blob transactions this is the L1 transaction's fixed intrinsic gas cost. `blobBaseFeeScalar` captures the user transaction's per-byte share of the blobdata that the batch-submitter's data transaction introduces.
### Unsafe block signer
The **Unsafe Block Signer** is an Ethereum address whose private key signs "unsafe" blocks before they go to L1. The signature lets P2P-network nodes treat those blocks as the canonical unsafe blocks, which guards the P2P layer against denial-of-service attacks.
So that the value can be read with a storage proof regardless of storage layout, it lives at a dedicated slot keyed by `keccak256("systemconfig.unsafeblocksigner")`. Unlike the other system-config values, this one is purely a blockchain-policy setting and is not a consensus-level parameter.
### L2 gas limit
The **L2 Gas Limit** caps the gas a single L2 block may spend, keeping blocks small enough to process and prove. A change takes full effect in the first L2 block whose L1 origin carried the change. The limit may not exceed the protocol's maximum gas limit, which keeps L2 blocks provable and processable by consensus and execution clients.
## Batch submission
### Data availability
Data availability is the assurance that some data stays *retrievable* over a reasonably long window. For Base, that data is the [sequencer batches](#sequencer-batch) that [validators](#validator) need in order to check the sequencer's work and validate the L2 chain.
The [finalization period](#finalization-period) is the lower bound on this window, since availability matters most then — that is when the data is required to run a [fault proof](#fault-proof). Note that "available" is **not** a promise of long-term storage.
### Data availability provider
A service that makes data available, in the sense described under [data availability](#data-availability). A good provider backs that availability with strong, *verifiable* guarantees. Today the supported providers are Ethereum calldata and blob data.
### Sequencer batch
A sequencer batch is a list of L2 transactions (submitted to a sequencer) tagged with a [epoch number](#sequencing-epoch) and an L2 block timestamp — which converts straight to a block number because the block time is fixed.
Batches are part of the [L2 derivation inputs](#l2-derivation-inputs). Each batch carries the inputs to build exactly **one** L2 block on top of existing L2 state — except for an epoch's first block, which additionally needs deposit information.
### Channel
A channel is a run of [sequencer batches](#sequencer-batch) for consecutive blocks, compressed together. Grouping batches improves the compression ratio and so lowers data-availability cost.
A channel can be cut into [frames](#channel-frame) for transmission inside [batcher transactions](#batcher-transaction), which matters when the channel is too big to fit in one transaction. Each channel is identified by its creation timestamp (UNIX time) plus a random value. From the [rollup node's](#rollup-node) perspective, a channel is *open* until its explicitly-marked final frame has been read, and closed thereafter.
### Channel frame
A channel frame is a slice of a [channel](#channel). A single [batcher transaction](#batcher-transaction) may carry one or several frames. Splitting a channel into frames is what allows oversized channels to be transmitted across multiple transactions.
### Batcher
The batcher is a standalone program tasked with publishing channels to a data-availability provider. It pulls channels from the rollup node and makes them available through [batcher transactions](#batcher-transaction).
### Batcher transaction
A batcher transaction is the transaction a [batcher](#batcher) sends to a data-availability provider to publish channels. Each one carries one or more complete frames, which may come from different channels, and a single channel's frames may be spread across several batcher transactions.
When posted to Ethereum calldata, the transaction's receiver must be the sequencer inbox address and it must be signed by a recognized batch submitter account. That account is recorded in the [System Configuration](#system-configuration).
### Batch submission frequency
As long as it stays within the [sequencing window](#sequencing-window), the batcher may post L2 blocks for data availability whenever it likes; the batcher software lets operators tune this policy dynamically. The rollup's safety and liveness guarantees are enforced through the sequencing window if data fails to arrive in time.
Posting in smaller, more frequent chunks shortens the delay before L2 block inputs are confirmed, lets verifiers establish safety sooner, and reduces the time to L1 finality (and thus to L2 input-finality). Posting in larger, less frequent chunks aggregates more L2 data per submission, spreading the fixed overhead of batch submission over more data and lowering cost — especially for lower-throughput chains that take a while to fill a data transaction (typically 128 KB of calldata or 800 KB of blobdata).
### Channel timeout
The channel timeout is a window, measured in L1 blocks, during which a channel's [frames](#channel-frame) may arrive on L1 inside [batcher transactions](#batcher-transaction).
A [channel's](#channel) frames are accepted over the time range `[channel_id.timestamp, channel_id.timestamp + CHANNEL_TIMEOUT]`; any L1 block whose timestamp lands in that range is eligible. (The `channel_id.timestamp` must be earlier than the L1 block timestamp of every L1 block carrying the channel's frames, or those frames are dropped.)
Channel timeouts serve two purposes: they stop old, never-closed channels from lingering indefinitely, and they bound how far back through L1 blocks a node must scan to decode [sequencer batches](#sequencer-batch) — which is especially useful during L1 re-orgs.
## L2 output root proposals
### Proposer
The proposer builds and submits output roots — commitments to L2 state — to the L2OutputOracle contract on the L1 settlement layer. It periodically asks the rollup node for the latest output root derived from the most recent finalized L1 block, then posts that root to the L2OutputOracle.
## L2 chain derivation
L2 chain derivation is the process of reading [L2 derivation inputs](#l2-derivation-inputs) from L1 and using them to reconstruct the L2 chain. The L2 chain derivation specification has the full details.
### L2 derivation inputs
The data found in L1 blocks that the [rollup node](#rollup-node) reads to assemble [payload attributes](#payload-attributes). These inputs are:
- L1 block attributes
- block number
- timestamp
- basefee
- blob base fee
- [deposits](#deposits) (carried as log data)
- [sequencer batches](#sequencer-batch) (carried as transaction data)
- [System configuration](#system-configuration) updates (carried as log data)
### System configuration
The set of dynamically adjustable rollup parameters held by the `SystemConfig` contract on L1 and read by the L2 [derivation](#l2-chain-derivation) process. Keeping them in a contract lets keys be rotated and external cost parameters be retuned without going through a hardfork. The Configuration reference has the full overview.
### Payload attributes
An object derived from the [L2 derivation inputs](#l2-derivation-inputs) on L1 and handed to the [execution engine](#execution-engine) to build L2 blocks. In effect it encodes [a block stripped of its output properties](#block). The object originates in the Ethereum Engine API spec and is extended by the Execution Engine specification.
### L2 genesis block
The first block of the L2 chain in its current version. Its state is made up of:
- State carried over from the previous version of the L2 chain — possibly altered by "state surgeries" (for instance, the Bedrock migration changed how native ETH balances were held in the storage trie).
- [Predeployed contracts](#predeployed-contract-predeploy).
The genesis block's timestamp must be a multiple of the [block time](#block-time) — an even number, since the block time is 2 seconds.
When the rollup moves to a new protocol version, it may perform a *squash fork*, which mints a fresh L2 genesis block numbered `X + 1`, where `X` is the last L2 block before the upgrade. This differs from a *re-genesis*, an older approach that reset L2 block numbers so the new genesis block was number 0; re-genesis will not be used again. Squash forks win out because they avoid reusing L2 block numbers, which would break many external tools.
### L2 chain inception
The L1 block number at which the output roots for the [genesis block](#l2-genesis-block) were first proposed to the output oracle contract. In the current implementation that is the L1 block where the output oracle was deployed or upgraded.
### Safe L2 block
An L2 block that a [rollup node](#rollup-node) can derive in full from L1. Which block qualifies can differ between nodes depending on each node's view of the L1 chain.
### Safe L2 head
The highest [safe L2 block](#safe-l2-block) a [rollup node](#rollup-node) is aware of.
### Unsafe L2 block
An L2 block a [rollup node](#rollup-node) knows about but has not derived from L1. In sequencer mode this is a block the sequencer produced itself; in validator mode it is a block pulled from the sequencer via [unsafe sync](#unsafe-sync).
### Unsafe L2 head
The highest [unsafe L2 block](#unsafe-l2-block) a [rollup node](#rollup-node) is aware of.
### Unsafe block consolidation
The process by which a [rollup node](#rollup-node) advances the [safe L2 head](#safe-l2-head) by one block, promoting the oldest [unsafe L2 block](#unsafe-l2-block) to be the new safe head. To do so the node checks that the [payload attributes](#payload-attributes) derived from L1 match that oldest unsafe block exactly.
### Finalized L2 head
The highest L2 block derivable from *finalized* L1 blocks — that is, L1 blocks older than two L1 epochs (64 L1 [time slots](#time-slot)).
## Other L2 chain concepts
### Address aliasing
When a contract sends a [deposit](#deposits) from L1 to L2, the address reported by `ORIGIN` and `CALLER` on L2 is an *aliased* variant of the originating contract's address rather than the address itself.
### Rollup node
The rollup node [derives the L2 chain](#l2-chain-derivation) from the L1 chain — from L1 [blocks](#block) and their associated [receipts](#receipt). It runs in either *validator* or *sequencer* mode.
In sequencer mode it takes L2 transactions from users, builds L2 blocks, and posts them to a [data availability provider](#data-availability-provider) through [batch submission](#batch-submission); derivation then doubles as a sanity check and a way to spot L1 [re-orgs](#chain-re-organization). In validator mode it derives the chain as usual but can also "run ahead" of L1 by fetching blocks straight from the sequencer, with derivation serving to verify the sequencer's behavior. A validator-mode node is sometimes called a *replica*.
### Rollup driver
The [rollup node](#rollup-node) component responsible for [deriving the L2 chain](#l2-chain-derivation) from the L1 chain and its [receipts](#receipt).
### L1 attributes predeployed contract
A [predeployed contract](#predeployed-contract-predeploy) on L2 for looking up the attributes of an L1 block by its number or hash.
### L2 output root
A 32-byte value committing to the current state of the L2 chain.
### L2 output oracle contract
An L1 contract that the [sequencer](#sequencer) posts [L2 output roots](#l2-output-root) to.
### Validator
An individual or organization running a [rollup node](#rollup-node) in validator mode. Doing so brings benefits much like running an Ethereum node — for example simulating L2 transactions locally without rate limits. It also lets the validator audit the [sequencer](#sequencer) by re-deriving [output roots](#l2-output-root) and comparing them to the submitted ones; on a mismatch the validator can run a [fault proof](#fault-proof).
### Fault proof
An on-chain, *interactive* proof that [validators](#validator) run to show that a [sequencer](#sequencer) submitted incorrect [output roots](#l2-output-root).
### Time slot
L2 produces a block every 2 seconds — this interval is the [block time](#block-time). A "time slot" occurs at every 2-second multiple after the [L2 genesis block's](#l2-genesis-block) timestamp.
On post-[merge](https://ethereum.org/en/eth2/merge/) L1, time slots come every 12 seconds, though an L1 block need not be produced for every slot, even under benign consensus hiccups.
### Block time
The L2 block time is 2 seconds, so there is an L2 block at each 2-second [time slot](#time-slot).
Post-merge, the L1 block time can be described as 12 seconds — its [time slot](#time-slot) length — but it is effectively variable because some slots are skipped. Pre-merge, L1 block time was variable too, averaging around 13 seconds.
### Unsafe sync
The process by which a [validator](#validator) learns of [unsafe L2 blocks](#unsafe-l2-block) directly from the [sequencer](#sequencer). These blocks still have to be confirmed against the L1 chain later, via [unsafe block consolidation](#unsafe-block-consolidation).
## Execution engine concepts
### Execution engine
The execution engine runs the transactions in a block and computes the resulting state root, receipts root, and block hash. Both post-[merge](https://ethereum.org/en/eth2/merge/) L1 and L2 have one.
On L1, the blocks it executes either come from synchronizing the L1 chain or are freshly minted from the L1 mempool at the consensus layer's request. On L2, blocks are always freshly minted at the [rollup node's](#rollup-node) request, from transactions [derived from L1 blocks](#l2-chain-derivation). Throughout these specifications, "execution engine" means the L2 execution engine unless stated otherwise.
---
# Isthmus L2 Execution Engine
Source: https://basehub.org/specifications/isthmus-exec-engine/
Description: Execution-engine changes introduced by the Isthmus upgrade — the L2ToL1MessagePasser storage root in the block header, deposit-request handling, BLS precompiles, and the new operator fee.
Isthmus reworks several execution-layer rules. The headline change is that the block header's `withdrawalsRoot` field now carries the storage root of the `L2ToL1MessagePasser` predeploy. The upgrade also adjusts deposit-request handling, adds BLS precompiles, and introduces a configurable operator fee.
## Timestamp Activation
Like every Base network upgrade, Isthmus turns on at a timestamp. The new L2 block execution rules take effect once `L2 Timestamp >= activation time`.
## `L2ToL1MessagePasser` Storage Root in Header
From Isthmus activation onward, the L2 block header's `withdrawalsRoot` field holds the 32-byte `L2ToL1MessagePasser` account storage root, taken from the world state identified by the header's `stateRoot`. That root is the same value `eth_getProof` returns for the account at the given block number.
### Header Validity Rules
Before Isthmus activates:
- the L2 block header's `withdrawalsRoot` field must be:
- `nil` if Canyon has not been activated.
- `keccak256(rlp(empty_string_code))` if Canyon has been activated.
- the L2 block header's `requestsHash` field must be omitted.
After Isthmus activates, an L2 block header is valid if and only if:
1. The `withdrawalsRoot` field
1. Is 32 bytes in length.
1. Matches the `L2ToL1MessagePasser` account storage root, as committed to in the `storageRoot` within the block header
1. The `requestsHash` field is equal to `sha256('') = 0xe3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855`, indicating no requests in the block.
### Header Withdrawals Root
| Byte offset | Description |
| ----------- | -------------------------------------------- |
| `[0, 32)` | `L2ToL1MessagePasser` account storage root |
#### Rationale
Generating L2 output roots for historical blocks otherwise requires an archive node, which pushes real cost onto the people who keep the system running. In a world secured by fault proofs that means a proposer needs an archive node to propose an output root at the safe head, and a user proving a withdrawal needs one to confirm that the output root they are proving against is genuinely valid and part of the safe chain. Committing the `L2ToL1MessagePasser` storage root directly into the `withdrawalsRoot` field removes that requirement, so both proposers and verifiers can do their work at lower operating cost.
#### Genesis Block
If Isthmus is active at the genesis block, the genesis header's `withdrawalsRoot` is set to the `L2ToL1MessagePasser` account storage root.
#### State Processing
While transactions are being validated, the header's `withdrawalsRoot` must not be exposed to the EVM or the application layer.
#### P2P
During sync the withdrawals list in the block body is expected to be empty (OP Stack does not use it), so its hash is the MPT root of an empty list. When the synced header chain is verified against the final synced header, the header timestamp decides whether Isthmus is active at that block. If it is, the header's `withdrawalsRoot` MPT hash may be any non-null value, since it is expected to hold the `L2ToL1MessagePasser` storage root.
#### Backwards Compatibility Considerations
From Canyon (which brings in Shanghai support) up until Isthmus activation, `withdrawalsRoot` is set to the MPT root of an empty withdrawals list — the same value as an empty storage root. Withdrawals are captured in the L2 state during this window but are not reflected in `withdrawalsRoot`, so even when a header carries a non-trivial MPT root in that field before Isthmus, it must not be relied on. Any output-root calculation has to avoid using the header `withdrawalsRoot` in this range.
There is always nonzero storage in the `L2ToL1MessagePasser`, because it is a proxied predeploy and stores an implementation address and owner address from genesis. As a result, from Isthmus the `withdrawalsRoot` is always non-nil and never equal to the MPT root of an empty list.
#### Forwards Compatibility Considerations
The `withdrawalsRoot` field is otherwise unused in Base's header consensus format and is not slated for any other use. Pointing it at the withdrawal account's storage root fits Base cleanly and reuses a field that already exists in the L1 header format.
#### Client Implementation Considerations
Execution clients keep historical account state in different ways. In a contrived case where Base produced no outbound withdrawal for a long stretch, a node might not retain the `L2ToL1MessagePasser` account storage root and would then be unable to stay in consensus. In practice most modern clients can reconstruct an account's storage root at a given block on demand even when they do not persist it directly.
##### Transaction Simulation
For RPC methods such as `eth_simulateV1` that simulate arbitrary transactions across one or more blocks, the header of a simulated block should carry an empty withdrawals root. The same applies whenever the real withdrawals-root value is not readily available.
## Deposit Requests
[EIP-6110] moves deposits to the execution layer and defines a new [EIP-7685] deposit request of type `DEPOSIT_REQUEST_TYPE`, which would otherwise show up in the [EIP-7685] requests list. Base ignores these: requests generation is modified to leave out [EIP-6110] deposit requests. Because the [EIP-6110] request type did not exist before Pectra on L1 and Isthmus on L2, no activation time is needed — these deposit-type requests can always be excluded.
[EIP-6110]: https://eips.ethereum.org/EIPS/eip-6110
[EIP-7685]: https://eips.ethereum.org/EIPS/eip-7685
## Block Body Withdrawals List
The withdrawals list in the block body is encoded as an empty RLP list.
## EVM Changes
### BLS Precompiles
As with the `bn256Pairing` precompile in the Granite hardfork, [EIP-2537](https://eips.ethereum.org/EIPS/eip-2537) adds a BLS precompile that short-circuits based on input size in the EVM.
The input-size limits for the BLS precompile contracts are:
- G1 multiple-scalar-multiply: `input_size <= 513760 bytes`
- G2 multiple-scalar-multiply: `input_size <= 488448 bytes`
- Pairing check: `input_size <= 235008 bytes`
The remaining BLS precompiles are fixed-size operations with a fixed gas cost.
## Block Sealing
On Base, `EIP-7685` is no-op'd and `requestsHash` is always set to `sha256('')`, as covered in the [header validity rules](#header-validity-rules). That also means [EIP-6110](https://eips.ethereum.org/EIPS/eip-6110), [EIP-7002](https://eips.ethereum.org/EIPS/eip-7002), and [EIP-7251](https://eips.ethereum.org/EIPS/eip-7251) are not enabled. After Isthmus activation, the Base execution layer must not run the post-block deposit-contract event filtering (EIP-6110) or the `EIP-7002` + `EIP-7251` system calls during block sealing.
Users remain free to deploy these contracts permissionlessly, but the Base execution layer gives them no special treatment, and the system calls L1 introduced in Pectra are not considered.
## Engine API Updates
### Update to `ExecutionPayload`
After Isthmus, `ExecutionPayload` carries an additional `withdrawalsRoot` field.
### `engine_newPayloadV4` API
From Isthmus onward, `engine_newPayloadV4` is used. The `executionRequests` parameter MUST be an empty array.
## Fees
Different OP Stack variants consume resources differently and need a more flexible pricing model. To allow more customizable fee structures, Isthmus adds a new term to the fee calculation — the `operatorFee` — parameterized by two scalars, the `operatorFeeScalar` and the `operatorFeeConstant`.
### Operator Fee
The operator fee is wired directly into the EVM, alongside the standard gas fee and Base's L1 data fee. It behaves like the EVM's existing fees, just with a different beneficiary account.
#### Fee Formula
```text
operatorFee = (gas * operatorFeeScalar / 10^6) + operatorFeeConstant
```
Where:
- `gas` is the amount of gas that the transaction used. When calculating the amount of gas that is bought at the beginning of the transaction, this should be the `gas_limit`. When determining how much gas should be refunded, based off of how much of the `gas_limit` the transaction used, this should be the `gas_used`.
- `operatorFeeScalar` is a `uint32` scalar set by the chain operator, scaled by `1e6`.
- `operatorFeeConstant` is a `uint64` scalar set by the chain operator.
The operator fee's maximum value fits in 77 bits, which follows from the maximum input parameters:
```text
operatorFee_max = (uint64_max * uint32_max / 10^6) + uint64_max ≈ 7.924660923989131 * 10^22
```
So implementations that compute it with `uint256` types do not need to check for overflow.
#### Deposit Operator Fees
Deposit transactions are never charged an operator fee: whatever the operator fee parameters are, it is **zero** for them. They also receive no operator-fee gas refund, since they never bought that gas in the first place.
#### EVM Fee Semantics
Like the EVM's other fees, the operator fee is charged following this pattern:
1. During pre-execution validation, the account must have enough ETH to cover the existing worst-case gas + L1 data fees _as well as_ the worst-case operator fee (for deposits, the worst-case fee is `0`). To compute this value, use the [fee formula](#fee-formula) with `gas` set to the `gas_limit` of the transaction, and add it to the existing worst-case transaction fee.
1. When buying gas prior to execution, charge the account the worst-case operator fee. To compute this value, use the [fee formula](#fee-formula) with `gas` set to the `gas_limit` of the transaction.
1. After execution, when issuing refunds, transactions that bought operator fee gas should be refunded the operator fee gas that was unused (i.e., the caller should only be charged the _effective_ operator fee.) The refund should be calculated as `opFeeRefund = opFeeWorstCase - opFeeActual`, where:
- `opFeeWorstCase` is as described in #1 + #2.
- `opFeeActual` is the amount of the operator fee that was actually used. This value is computed using the [fee formula](#fee-formula) with `gas` set to the `gas_limit - gas_used + refunded_gas`. `refunded_gas` is as described in [EIP-3529](https://eips.ethereum.org/EIPS/eip-3529).
1. After execution, when rewarding the fee beneficiaries, send the _spent operator fee_ to the operator fee vault. This value is exactly `opFeeActual` as described above.
Implementations must ensure ETH is neither minted nor destroyed as a result of the operator fee.
#### Transaction Pool Changes
Because this extra fee feeds into transaction validity, the transaction pool must reject any transaction whose balance cannot cover the worst-case cost — and that worst-case cost now includes the worst-case operator fee.
#### Configuring Operator Fee Parameters
`operatorFeeScalar` and `operatorFeeConstant` are loaded much like the `baseFeeScalar` and `blobBaseFeeScalar` used in the `L1Fee` calculation. They can be read in two interchangeable ways:
- read from the deposited L1 attributes (`operatorFeeScalar` and `operatorFeeConstant`) of the current L2 block
- read from the L1 Block Info contract (`0x4200000000000000000000000000000000000015`)
- using the respective solidity getter functions (`operatorFeeScalar`, `operatorFeeConstant`)
- using direct storage-reads:
- Operator fee scalar as big-endian `uint32` in slot `8` at offset `0`.
- Operator fee constant as big-endian `uint64` in slot `8` at offset `4`.
### Fee Vaults
The collected operator fees go to a new vault, the `OperatorFeeVault`. As with the existing vaults, this is a hardcoded address pointing at a pre-deployed proxy, backed by a `FeeVault`-based deployment that routes vault funds to L1 securely.
### Receipts
After Isthmus activation, two new fields — `operatorFeeScalar` and `operatorFeeConstant` — are added to transaction receipts whenever at least one of them is non-zero.
---
# Jovian L2 Execution Engine
Source: https://basehub.org/specifications/jovian-exec-engine/
Description: Execution-engine changes introduced by the Jovian upgrade — a configurable minimum base fee, the DA footprint block limit, the updated operator fee formula, and precompile input-size restrictions.
Jovian reworks several execution-layer rules. It adds a configurable minimum base fee, introduces a DA footprint block limit that ties data-availability usage into base fee dynamics, raises the ceiling on the operator fee, and tightens input-size limits on a handful of precompiles.
## Minimum Base Fee
Jovian adds a [configurable minimum base fee](https://github.com/ethereum-optimism/design-docs/blob/main/protocol/minimum-base-fee.md) whose purpose is to shorten priority-fee auctions on Base.
It is configured in `SystemConfig` (see [System Configuration](../../protocol/consensus/derivation#system-configuration)); the execution engine then enforces it, encoding the value into the block header's `extraData` and threading it through the `PayloadAttributesV3` parameters of the Engine API.
### Minimum Base Fee in Block Header
As with [Holocene's dynamic EIP-1559 parameters](../holocene/exec-engine#dynamic-eip-1559-parameters), Jovian packs fee parameters into each L2 block header's `extraData`. The layout grows by one `u64` field holding the minimum base fee in wei.
| Name | Type | Byte Offset |
| ------------------- | ------------------ | ----------- |
| `minBaseFee` | `u64 (big-endian)` | `[9, 17)` |
Constraints:
- `version` MUST be `1` (raised from Holocene's `0`).
- Nothing may appear past these 17 bytes.
`minBaseFee` is an absolute floor expressed in wei. When the base fee is computed, a result below `minBaseFee` MUST be clamped up to it:
```javascript
if (baseFee < minBaseFee) {
baseFee = minBaseFee
}
```
Note: `extraData` is capped at 32 bytes (matching the L1 beacon-chain `extraData` type), and future upgrades may extend it.
### Minimum Base Fee in `PayloadAttributesV3`
The Engine API [`PayloadAttributesV3`](../../protocol/execution/index#extended-payloadattributesv3) gains a new `minBaseFee` field. The existing `eip1559Params` stays at 8 bytes (the Holocene format).
```text
PayloadAttributesV3: {
timestamp: QUANTITY
prevRandao: DATA (32 bytes)
suggestedFeeRecipient: DATA (20 bytes)
withdrawals: array of WithdrawalV1
parentBeaconBlockRoot: DATA (32 bytes)
transactions: array of DATA
noTxPool: bool
gasLimit: QUANTITY or null
eip1559Params: DATA (8 bytes) or null
minBaseFee: QUANTITY or null
}
```
`minBaseFee` MUST be `null` before the Jovian fork and non-`null` after it.
### Rationale
As with [Holocene's dynamic EIP-1559 parameters](../holocene/exec-engine#rationale), keeping the minimum base fee in the block header means block sealing never has to reach into state. The function that derives the next block's base fee from its parent header stays pure while the parameter remains dynamically configurable — handled much like `gasLimit`, with the derivation pipeline feeding the relevant `SystemConfig` values to the block builder through `PayloadAttributesV3`.
## DA Footprint Block Limit
Jovian introduces a _DA footprint block limit_ that caps the total estimated compressed transaction data a block may carry. Each transaction now tracks a new resource — its DA footprint — alongside gas usage. The figure is scaled into the gas dimension so its block total can be bounded by the block gas limit, just like total gas usage.
A block's `daFootprint` is defined as:
```python
def daFootprint(block: Block) -> int:
daFootprint = 0
for tx in block.transactions:
if tx.type == DEPOSIT_TX_TYPE:
continue
daUsageEstimate = max(
minTransactionSize,
(intercept + fastlzCoef * tx.fastlzSize) // 1e6
)
daFootprint += daUsageEstimate * daFootprintGasScalar
return daFootprint
```
Here `intercept`, `minTransactionSize`, `fastlzCoef`, and `fastlzSize` come from the [Fjord specs](../fjord/exec-engine), `DEPOSIT_TX_TYPE` is `0x7E`, and `//` denotes integer floor division.
From Jovian onward, each block header's `blobGasUsed` property is set to that block's `daFootprint`. Pre-Jovian (since Ecotone) it was held at 0 because Base has no blob support; the field is now reused to carry the DA footprint.
Block building must guarantee — and header validation must check — that a block's `daFootprint` stays under the `gasLimit`, exactly as it does for `gasUsed`. This implies a block may hold at most `gasLimit/daFootprintGasScalar` total estimated DA usage bytes.
In addition, from Jovian the base fee update uses `gasMetered := max(gasUsed, blobGasUsed)` in place of the previous `gasUsed`. As a result, blocks with heavy DA usage can push the base fee up in following blocks.
### Scalar loading
`daFootprintGasScalar` loads in the same fashion as the `operatorFeeScalar` and `operatorFeeConstant` [introduced](../isthmus/exec-engine#operator-fee) in Isthmus. It can be read two interchangeable ways:
- from the current L2 block's deposited L1 attributes (`daFootprintGasScalar`), decoded per the [jovian schema](./l1-attributes)
- from the L1 Block Info contract (`0x4200000000000000000000000000000000000015`)
- through the Solidity getter `daFootprintGasScalar`
- by reading storage directly — a big-endian `uint16` in slot `8` at offset `12`.
Its default value is given in the [L1 Attributes](./l1-attributes) section.
### Receipts
Once Jovian is active, transaction receipts gain a new `daFootprintGasScalar` field carrying its block's DA footprint gas scalar. The receipt's `blobGasUsed` field is also set to the transaction's DA footprint.
### Rationale
Today's L1 fee mechanism prices DA usage from an estimate of each transaction's DA footprint, yet nothing at the protocol level reflects how limited DA throughput on L1 actually is. For example, on Ethereum L1 with Pectra enabled, blob throughput is roughly `~96 kB/s` (target `~64 kB/s`), yet the calldata floor gas price of `40` for calldata-heavy L2 transactions permits more incompressible data than Ethereum blob space could absorb on most Base chains. This is currently handled at the policy level by batcher-sequencer throttling, which artificially constricts block building — and can drag base fees down, costing chain operators and worsening the user experience (inclusion delays, priority-fee auctions). Imposing a hard cap on a block's DA footprint that simultaneously feeds into the base fee resolves these shortcomings of the policy-based approach.
## Operator Fee
### Fee Formula Update
Jovian revises the operator fee calculation so larger fees can be charged. From the Jovian activation onward, the operator fee MUST be derived as:
```text
operatorFee = (gas * operatorFeeScalar * 100) + operatorFeeConstant
```
In effect, the per-gas scalar applied becomes `100 * operatorFeeScalar`. Every other data type and the operator-fee semantics from the [Isthmus spec](../isthmus/exec-engine#operator-fee) carry over unchanged.
### Maximum value
Under the new formula the operator fee's maximum value occupies 103 bits:
```text
operatorFee_max = (uint64_max * uint32_max * 100) + uint64_max ≈ 7.924660923989131 * 10^30
```
Implementations that use `uint256` for intermediate arithmetic need no extra overflow checks.
## EVM Changes
### Precompile Input Size Restrictions
A few precompiles have revised input-size limits. The new caps are:
- `bn256Pairing`: 81,984 bytes (427 pairs)
- `BLS12-381 G1 MSM`: 288,960 bytes (1,806 pairs)
- `BLS12-381 G2 MSM`: 278,784 bytes (968 pairs)
- `BLS12-381 Pairing`: 156,672 bytes (408 pairs)
---
# P2P Networking Stack
Source: https://basehub.org/specifications/p2p/
Description: How Base nodes discover peers and gossip blocks across two independent P2P stacks — discv5 plus libp2p on the consensus layer and DevP2P plus RLPx on execution.
import { Aside } from '@astrojs/starlight/components';
Base nodes run two independent peer-to-peer networks — one for the consensus layer (CL) and one for the execution layer (EL) — and bridge them locally through the Engine API. This guide walks through both stacks, why they exist, and where the relevant code lives in [`base/base`](https://github.com/base/base).
## Why P2P matters
A blockchain is a network of computers that must coordinate without a central server. Peer-to-peer networking provides that coordination. Each node connects to a handful of peers, and those peers connect to others, forming a mesh — a web of overlapping links where every node can reach every other node by some path. When a node sees a new block or transaction, it relays it to its neighbors, and within seconds the entire network has converged. This propagation pattern is gossip.
P2P networking solves three problems:
1. **Discovery** — how a fresh node finds peers to connect to.
2. **Transport** — how two nodes establish a secure session and exchange data.
3. **Gossip** — how connected nodes broadcast new information efficiently without flooding the network.
## Why Ethereum has two P2P layers
Before The Merge in September 2022, Ethereum ran a single P2P network. Every node ran one execution client (such as Geth) that handled discovery, transaction gossip, block propagation, and proof-of-work consensus. The networking stack was DevP2P, a custom protocol suite designed for Ethereum starting in 2014.
The Merge introduced a second binary: the consensus client. Consensus clients follow the beacon chain — a separate chain coordinating proof-of-stake — and decide which blocks are canonical. The beacon chain was designed from scratch on libp2p rather than DevP2P because libp2p is more modular and better suited to the publish/subscribe patterns required for attestation and block gossip in proof-of-stake. Merging the stacks would have been a massive undertaking with little practical benefit, so Ethereum kept them separate and bridged them with a local API.
After The Merge, every Ethereum node runs two processes with two separate P2P networks. The execution layer continues to use DevP2P over RLPx (an encrypted transport described later) for transaction and historical block exchange. The consensus layer uses libp2p with gossipsub (a broadcast protocol described later) for beacon blocks and attestations. The two layers communicate locally through the Engine API — JSON-RPC over HTTP or WebSocket on localhost.
A rollup like Base inherits the same two-layer architecture but ships different payloads. Where Ethereum L1 gossips beacon blocks and attestations from hundreds of thousands of validators, Base's CL gossips L2 execution payloads — the new blocks produced by the sequencer (the single designated node that orders and produces L2 blocks).
The sequencer signs each block with its private key so other nodes can verify it came from the authorized producer rather than from an attacker. It then publishes the signed block to the CL gossip network, and every Base node picks it up from there.
This is a latency optimization, not a security mechanism. Rollup security comes entirely from L1: batch data posted to Ethereum L1 is the canonical source of truth, and the derivation pipeline (software that reconstructs L2 state from L1 batch data) can rebuild the entire L2 chain from L1 alone. P2P gossip lets nodes see new L2 blocks several minutes before the corresponding batch lands on L1, reducing user-visible latency. The EL still runs a DevP2P network for transaction pool gossip and historical sync, though in practice the sequencer often receives transactions directly rather than through EL gossip.
## How the CL and EL communicate: the Engine API
Before walking through each stack, it helps to know how they connect. The consensus and execution clients do not share a P2P network — they share a local RPC bridge called the Engine API: a JSON-RPC interface exposed by the execution client (typically on port 8551) and secured with JWT authentication, a shared-secret mechanism that proves the caller is authorized. Only the co-located consensus client can issue these calls.
The Engine API has three core methods. Think of it as a three-step exchange: "start building a block," "give me what you built," and "here's a block someone else built — check it."
`engine_forkchoiceUpdated` tells the execution client which block is the current head, the latest safe block, and the latest finalized block. When the consensus client also passes optional payload attributes (timestamp, fee recipient, and other parameters describing the block to build), the call additionally instructs the execution client to begin assembling a new block. `engine_getPayload` retrieves the block the execution client has been assembling from its mempool. `engine_newPayload` sends an execution payload received from gossip to the execution client for validation and execution. The execution client re-executes all transactions, verifies the state root (a cryptographic fingerprint of the entire blockchain state after executing the block's transactions), and responds with VALID, INVALID, or SYNCING (meaning the node has not caught up to the chain tip yet and cannot validate the block).
For block production on Base, the flow is: the sequencer's CL calls `engine_forkchoiceUpdated` with payload attributes to start building, waits, calls `engine_getPayload` to retrieve the built payload, signs it, and publishes it to the CL gossip network. For block validation, the flow is reversed: the CL receives a signed block from gossip, validates the signature, sends the execution payload to the EL via `engine_newPayload`, and uses the validity response to accept or reject the block.
This separation lets each layer evolve its networking independently. It also means implementations are swappable — any CL and EL that speak the Engine API can be paired.
## The consensus layer P2P stack
The Base consensus P2P stack lives under [`crates/consensus/`](https://github.com/base/base/tree/main/crates/consensus) and is composed of four crates that layer on top of one another: peers, disc, gossip, and the network actor in the service crate.
### Peers — the foundation
The [`base-consensus-peers`](https://github.com/base/base/tree/main/crates/consensus/peers) crate provides the fundamental types for identifying and managing peers on the consensus network.
The central concept is the ENR (Ethereum Node Record), defined in [EIP-778](https://eips.ethereum.org/EIPS/eip-778). An ENR is a compact, self-describing identity document a node uses to advertise itself. It is encoded with RLP (Recursive Length Prefix, Ethereum's standard binary serialization format) and contains a cryptographic signature, a monotonically increasing sequence number (so newer records always rank higher), and a sorted set of key-value pairs. Predefined keys include `id` (the identity scheme — currently "v4" for secp256k1, the elliptic curve Ethereum uses for public-key cryptography), `secp256k1` (the node's compressed 33-byte public key), `ip` (IPv4 address), and `tcp`/`udp` (port numbers). When a node's information changes (for example, its IP address rotates), it bumps the sequence number and re-signs the record; the signature ensures records cannot be tampered with. ENRs are deliberately small (300 bytes maximum) because they propagate frequently and may need to fit in constrained transports such as DNS TXT records.
Different layers of the Ethereum stack use ENR extension keys for chain-specific metadata. Ethereum L1's execution layer carries an `eth` key with fork ID information. The L1 consensus layer carries an `eth2` key with the fork digest and attestation subnet bitfield. On Base — and OP Stack chains in general — every ENR includes an `opstack` key encoding the L2 chain ID and a version number. This is how nodes on different chains (Base Mainnet versus Base Sepolia) tell each other apart during discovery. ENRs are typically displayed as a base64-encoded string prefixed with `enr:`.
The [`BaseEnr`](https://github.com/base/base/blob/main/crates/consensus/peers/src/enr.rs) struct handles this encoding:
```rust
/// The unique L2 network identifier
pub struct BaseEnr {
/// Chain ID
pub chain_id: u64,
/// The version. Always set to 0.
pub version: u64,
}
impl BaseEnr {
/// The ENR key literal string for the consensus layer.
pub const OP_CL_KEY: &str = "opstack";
/// Constructs a BaseEnr from a chain id.
pub const fn from_chain_id(chain_id: u64) -> Self {
Self { chain_id, version: 0 }
}
}
```
When a node discovers another node's ENR, [`EnrValidation`](https://github.com/base/base/blob/main/crates/consensus/peers/src/enr.rs) checks that the `opstack` key is present, decodes correctly, and that the chain ID matches. If a Base Mainnet node (chain ID 8453) sees an ENR for a different chain, it ignores it.
The peers crate also provides a [`BootStore`](https://github.com/base/base/blob/main/crates/consensus/peers/src/store.rs), a JSON file that persists discovered ENRs to disk so the node does not need to bootstrap discovery from scratch on every restart. The store caps at 2048 entries and prunes the oldest when full.
### Discovery — finding peers with discv5
The [`base-consensus-disc`](https://github.com/base/base/tree/main/crates/consensus/disc) crate implements peer discovery using discv5. Discv5 is a UDP-based protocol that maintains a distributed hash table (DHT) of node records. It succeeds discv4 (used by the EL) and was designed for the consensus layer's needs.
Discv5 is inspired by Kademlia, an academic DHT protocol from 2002. A DHT is a system where many computers collectively maintain a lookup directory without a central coordinator. The Kademlia insight is using XOR as a distance metric. Every node has a 256-bit ID derived from its public key; the "distance" between two nodes is the XOR of their IDs interpreted as a number. The metric is symmetric (distance A→B equals B→A) and unrelated to physical or network distance. Two nodes with similar IDs can sit on opposite sides of the planet. Think of comparing two phone numbers digit by digit: numbers sharing a long prefix are "close" in Kademlia space even if the people holding them live in different countries.
Each node maintains a routing table organized into 256 "k-buckets" — one per possible bit-length of XOR distance. Bucket 0 holds nodes whose IDs differ from the local ID only in the least significant bit; bucket 255 holds nodes that differ in the most significant bit. Each bucket holds up to k entries (typically k=16). Imagine sorting your contacts into folders by how their IDs differ from yours — most contacts end up in "close" folders and fewer in the "far" folders, which is the right shape for efficient lookups.
To discover new peers, a node performs an iterative lookup: it picks a target ID (often random, to populate its routing table), finds the closest nodes it already knows, and sends them FINDNODE requests. Unlike discv4, which asks for nodes "near" a specific ID, discv5 FINDNODE requests specify a logarithmic distance — a number from 0 to 256 representing the bit position where IDs first differ ("give me all nodes at XOR distance 2^n from you"). It is more efficient and harder to abuse. The node receives lists of nodes at that distance, queries those newly learned nodes, and gets progressively closer to the target with each round.
Fresh nodes bootstrap by connecting to a small set of well-known bootnodes whose addresses are hardcoded into the client. The bootnode responds to FINDNODE requests, giving the new node its first set of peers. From there the new node performs a few random lookups to fill its routing table and within minutes has a healthy set of diverse peers.
The [`Discv5Driver`](https://github.com/base/base/blob/main/crates/consensus/disc/src/driver.rs) orchestrates discovery. On startup it initializes the discv5 UDP service with exponential backoff retries (waiting progressively longer between attempts — for example 1s, 2s, 4s, 8s). Once that succeeds, it starts the event stream, retrying up to 10 times with 2-second delays if initialization fails. Then it bootstraps by loading the boot store from disk and adding hardcoded boot nodes. Each ENR is validated against the expected chain ID before being added to the routing table:
```rust
let validation = EnrValidation::validate(&enr, chain_id);
if validation.is_invalid() {
trace!(target: "discovery::bootstrap", enr = ?enr, validation = ?validation,
"Ignoring Invalid Bootnode ENR");
continue;
}
if let Err(e) = disc.add_enr(enr.clone()) {
debug!(target: "discovery::bootstrap", error = ?e, "Failed to add enr");
continue;
}
store.add_enr(enr);
```
After bootstrapping, the driver enters its main loop, doing several things concurrently via `tokio::select!` (a Rust macro that waits on multiple async operations and runs the code for whichever completes first). It runs periodic random node queries (every 5 seconds by default) to keep discovering peers. It listens for discv5 events such as `Discovered`, `SessionEstablished`, and `UnverifiableEnr`, and when it sees a valid ENR it forwards it through an `mpsc` (multi-producer, single-consumer) channel to the gossip layer so it can dial the peer. An `mpsc` channel is a thread-safe queue where multiple senders push to a single receiver — the primary way components communicate in async Rust. The driver also persists the current set of known ENRs to the boot store every 60 seconds.
The driver communicates with the rest of the system through a [`Discv5Handler`](https://github.com/base/base/blob/main/crates/consensus/disc/src/handler.rs), a thin wrapper around an `mpsc::Sender`. Callers elsewhere in the node use it to ask for the peer count, peer lists, routing table details, and the local ENR, and to tell discovery to ban particular addresses. This channel-based design avoids shared mutable state across async boundaries.
### Gossip — broadcasting blocks with libp2p and gossipsub
The [`base-consensus-gossip`](https://github.com/base/base/tree/main/crates/consensus/gossip) crate is where the action happens — this is the layer that actually receives and broadcasts L2 blocks across the network.
Gossipsub is a publish/subscribe protocol on libp2p that solves the problem of distributing messages efficiently in a decentralized network where no node can be trusted. The naive approach (floodsub) forwards every message to every peer — it works but consumes huge bandwidth because every node receives each message from multiple sources. Gossipsub instead builds a sparse "mesh" overlay per topic.
When a node subscribes to a topic, it announces the subscription to its peers. It then selects D peers (the "desired mesh degree") that are also subscribed to the topic and establishes mesh links by sending GRAFT control messages. Mesh links are symmetric: if A grafts B, B also considers A part of its mesh. When a message is published, it flows eagerly through these links — each receiving node forwards the message to all of its mesh peers for that topic (except the sender). The result is a connected overlay where messages propagate in O(log N) hops with bounded bandwidth per node.
The protocol layers reliability on top of the mesh. Every heartbeat interval, each node sends IHAVE control messages to a random subset of non-mesh peers, listing recently seen message IDs. If a peer has not seen one of those messages (perhaps a mesh path failed or was slow), it replies with IWANT and the original node sends the full message. This lazy repair ensures messages reach everyone within a few heartbeat rounds even if the mesh is partitioned or a peer drops out. PRUNE messages are the inverse of GRAFT: a node sends PRUNE to remove a peer from its mesh, either because the mesh is too large or the peer's score is poor. Pruned peers are not disconnected — they simply move from the eager-push mesh to the lazy-gossip pool.
Gossipsub v1.1, which Base uses, adds a peer scoring system. Each node evaluates its peers based on behavior (whether they deliver valid messages promptly, whether they spam duplicates) and preferentially keeps well-scored peers in the mesh while pruning poorly scored ones. A peer that repeatedly sends invalid messages accumulates a negative score, and once it crosses a configurable threshold it is pruned and eventually disconnected. v1.1 also added flood publishing (where the original publisher sends to all connected peers, not just mesh peers), though Base disables this by default to conserve bandwidth.
The gossipsub configuration in Base lives in [`gossip/src/config.rs`](https://github.com/base/base/blob/main/crates/consensus/gossip/src/config.rs):
```rust
pub const DEFAULT_MESH_D: usize = 8; // target peers in mesh
pub const DEFAULT_MESH_DLO: usize = 6; // minimum before mesh repair
pub const DEFAULT_MESH_DHI: usize = 12; // maximum before pruning
pub const DEFAULT_MESH_DLAZY: usize = 6; // peers for lazy gossip
pub const GOSSIP_HEARTBEAT: Duration = Duration::from_millis(500);
pub const MAX_GOSSIP_SIZE: usize = 10 * (1 << 20); // 10 MB
```
In practice, each node aims for 8 peers in its mesh per topic. If it falls below 6 it grafts new peers; above 12 it prunes some. Every 500ms the heartbeat fires and the protocol checks mesh health. The lazy gossip parameter means that for messages a node has seen but did not forward via the mesh, it still tells 6 additional peers via lightweight metadata so they can request them if needed.
Messages are compressed with Snappy (a fast compression algorithm prioritizing speed over ratio) before being sent, and each message ID is computed by SHA-256 hashing (a cryptographic hash function that produces a unique fixed-size fingerprint of arbitrary data) the decompressed content with a domain prefix (a few extra bytes prepended before hashing to distinguish valid from invalid encodings). This is how the network deduplicates messages.
The gossip topics are where Base's L2-specific design becomes visible. The [`BlockHandler`](https://github.com/base/base/blob/main/crates/consensus/gossip/src/handler.rs) manages four versioned topics, one per protocol version:
```rust
blocks_v1_topic: IdentTopic::new(format!("/optimism/{chain_id}/0/blocks")),
blocks_v2_topic: IdentTopic::new(format!("/optimism/{chain_id}/1/blocks")),
blocks_v3_topic: IdentTopic::new(format!("/optimism/{chain_id}/2/blocks")),
blocks_v4_topic: IdentTopic::new(format!("/optimism/{chain_id}/3/blocks")),
```
For Base Mainnet (chain ID 8453), these resolve to `/optimism/8453/0/blocks` through `/optimism/8453/3/blocks`. The version is selected based on the active hardfork (a protocol upgrade that changes network rules, activated at a specific timestamp) at the block's timestamp. V1 covers pre-Canyon blocks, V2 Canyon/Delta, V3 Ecotone, and V4 Isthmus. Each version uses a slightly different encoding for the execution payload envelope.
A node does not hold all four subscriptions forever. Topics retire as forks age out. `BlockHandler::MAX_BLOCK_AGE` is 60 seconds, and it does double duty: it caps how old a gossip block can be, and it sets the retirement grace period. Once a replacement fork has been active for longer than that window, no block on the older topic can still be inside the accepted age range, so the subscription serves no purpose and the driver drops it:
```rust
pub const MAX_BLOCK_AGE: u64 = 60;
```
`topics_at()` computes the live set by finding the topic that would carry a block from 60 seconds ago and discarding everything older. Two properties of that calculation are worth holding onto. It reads the **local** clock, never a timestamp a peer claims, so a peer cannot talk a node into reviving a dead topic. And it keeps future topics joined ahead of their activation, so the mesh for the next fork is already warm when the fork lands. `GossipDriver` re-evaluates the set every 5 seconds (`TOPIC_RETIREMENT_INTERVAL`) whether or not traffic is arriving, and skips topics that are already retired when it starts up.
Retirement binds in both directions, and cheaply. Inbound, the handler discards a message on a retired topic before it decompresses or SSZ-decodes anything, so a flood of obsolete-topic traffic costs almost nothing to refuse. Outbound, a retired topic cannot be encoded for publication — relevant because gossipsub will happily publish to a topic you are not subscribed to, and this closes that path. Only v1 through v3 are ever retired; v4 is the newest topic and always stays.
With the `metrics` feature on, the live set is observable. `base_node_block_topic_subscribed`, `base_node_block_topic_peers`, and `base_node_block_topic_mesh_peers` are each labelled by version, and `base_node_block_topic_blocked_total` counts refusals with an `inbound` or `outbound` direction label. The three gauges are sampled at startup and on every retirement check, including while the network is idle, and they publish explicit zeroes for retired topics rather than dropping the series. Watch `peers` against `subscribed`: `peers` counts neighbours still advertising a topic even after the local node has retired it, so the two diverging is the expected shape during a fork transition, not a fault.
The `BlockHandler` implements the [`Handler`](https://github.com/base/base/blob/main/crates/consensus/gossip/src/handler.rs) trait, with two methods: `handle()` for processing incoming messages and `topics()` for declaring which topics it cares about. When a gossip message arrives, the handler first checks the topic to choose the decoder, then decodes the payload, then validates it:
```rust
fn handle(&mut self, msg: Message) -> (MessageAcceptance, Option) {
let decoded = if msg.topic == self.blocks_v1_topic.hash() {
NetworkPayloadEnvelope::decode_v1(&msg.data)
} else if msg.topic == self.blocks_v2_topic.hash() {
NetworkPayloadEnvelope::decode_v2(&msg.data)
} else if msg.topic == self.blocks_v3_topic.hash() {
NetworkPayloadEnvelope::decode_v3(&msg.data)
} else if msg.topic == self.blocks_v4_topic.hash() {
NetworkPayloadEnvelope::decode_v4(&msg.data)
} else {
return (MessageAcceptance::Reject, None);
};
match decoded {
Ok(envelope) => match self.block_valid(&envelope) {
Ok(()) => (MessageAcceptance::Accept, Some(envelope)),
Err(err) => (err.into(), None),
},
Err(err) => (MessageAcceptance::Reject, None),
}
}
```
The `MessageAcceptance` result feeds back into gossipsub's peer scoring. `Accept` means the message was valid and the peer earns credit. `Reject` means the message was invalid and the peer's score takes a hit. `Ignore` is used for already-seen blocks and does not penalize the peer.
### Block validation — keeping gossip honest
Block validation in [`block_validity.rs`](https://github.com/base/base/blob/main/crates/consensus/gossip/src/block_validity.rs) is one of the most important pieces of the P2P stack because it determines what the node accepts. The checks run in sequence and the order matters.
First, the timestamp must fall within an acceptable window — no more than 5 seconds in the future or 60 seconds in the past. This rejects stale blocks and prevents replay attacks (where an attacker re-broadcasts old, legitimate messages to confuse the network).
Second, the block hash is recomputed from the payload and compared against the hash in the envelope. A mismatch indicates tampering.
Third, version-specific payload constraints are enforced. V3 (Ecotone) and later payloads must include a non-empty parent beacon block root and zero blob gas usage. V4 (Isthmus) payloads must include a withdrawals root. This step catches blocks that are structurally invalid for their version.
Fourth, the handler consults its seen-hashes tracking. It maintains a `BTreeMap` keyed by block height with a 1,000-entry cache. If more than 5 different blocks already exist for a given height (a sixth unique block is accepted but a seventh is rejected), the new block is rejected. If this exact block hash has been seen before, it is ignored without penalty. Multiple valid blocks at the same height can occur with a single sequencer when it produces a replacement block — for example, after a reorg (chain reorganization) triggered from L1.
Fifth, and most important for rollup security, the signature is verified. The sequencer signs each block with its private key, and every node knows the expected signer's address. The expected signer is read first, then the signature is recovered from the payload hash via ECDSA recovery (a property of elliptic curve signatures that lets you compute the signer's public key from just the signature and the signed message). If the recovered address does not match the expected signer, the block is rejected:
```rust
let msg = envelope.payload_hash.signature_message(self.rollup_config.l2_chain_id.id());
let block_signer = *self.signer_recv.borrow();
let Ok(msg_signer) = envelope.signature.recover_address_from_prehash(&msg) else {
return Err(BlockInvalidError::Signature);
};
if msg_signer != block_signer {
return Err(BlockInvalidError::Signer { expected: block_signer, received: msg_signer });
}
```
Only after the signature passes does the handler insert the block hash into the seen-hashes map, marking it as processed. This prevents spam without rejecting legitimate competing blocks.
### Connection gating — controlling who connects
The [`ConnectionGater`](https://github.com/base/base/blob/main/crates/consensus/gossip/src/gater.rs) is a rate-limiting layer that controls peer connections. It tracks dial attempts per peer address and enforces a configurable dial period (default: 1 hour). By default, redialing is disabled entirely — a peer can only be dialed once per period. The CLI overrides this to allow up to 500 redials per period via `--p2p.redial`. The gater also supports explicitly blocking peers by ID, IP address, or subnet, and protecting specific peers from disconnection regardless of score.
Without connection gating, a misbehaving or misconfigured node could repeatedly attempt to connect, wasting resources. The gater bounds connection attempts and lets known-bad actors be blocked at the connection level rather than just at the gossip level.
### The libp2p Behaviour — combining protocols
The [`Behaviour`](https://github.com/base/base/blob/main/crates/consensus/gossip/src/behaviour.rs) struct is a libp2p `NetworkBehaviour` that combines several sub-protocols into a single swarm (libp2p's term for the combination of transport, protocol behaviors, and connection management — essentially the "networking engine"):
```rust
#[derive(NetworkBehaviour)]
pub struct Behaviour {
pub connection_limits: libp2p::connection_limits::Behaviour,
pub ping: libp2p::ping::Behaviour,
pub gossipsub: libp2p::gossipsub::Behaviour,
pub identify: libp2p::identify::Behaviour,
}
```
Field order carries meaning here. libp2p calls each behaviour's connection hooks in declaration order, so `connection_limits` sits first: it turns away surplus connections before any other behaviour allocates a handler for them. Its caps default to 5 pending inbound, 16 pending outbound, 30 established in each direction and in total, and 1 established connection per peer. This is a different layer from the `ConnectionGater` above. The gater decides whether a given peer is allowed to connect at all. These limits bound how many connections exist, whoever they belong to.
`ping` sends periodic keepalive pings and measures round-trip times. `gossipsub` handles block gossip. `identify` exchanges capability information when peers first connect (Base advertises its agent version as `"base"`).
Notice what is absent. Base neither advertises nor implements `payload_by_number`, the legacy op-node request-response protocol. Earlier releases carried a `sync_req_resp` stub that answered every such request with "not found", purely so op-nodes would not penalize Base for the gap. That stub is gone, and a test now asserts no advertised protocol begins with `/opstack/req/payload_by_number/`. Nothing about block delivery regresses as a result: gossipsub moves consensus-layer blocks, the execution layer syncs over its own path, and follow mode fetches payloads over HTTP. Any tooling that reached for this protocol on a Base node was already getting "not found" and must use one of those three paths instead.
The `GossipDriver` ([`gossip/src/driver.rs`](https://github.com/base/base/blob/main/crates/consensus/gossip/src/driver.rs)) wraps the swarm and provides higher-level operations. Its `start()` method binds the swarm to a TCP address (default `0.0.0.0:9222`), waits for the `NewListenAddr` event confirming the listener is up, and returns. Its `publish()` method takes an execution payload envelope (the signed wrapper around a block's contents — transactions, state root, gas used, and so on), selects the appropriate topic based on the block's timestamp and active hardfork, encodes it with version-appropriate serialization, and publishes it to gossipsub. Its `dial()` method takes an ENR from discovery, validates the chain ID, extracts the TCP multiaddr (a self-describing network address format used by libp2p, e.g. `/ip4/192.168.1.1/tcp/9222`), checks the connection gate, and initiates the connection.
### Putting it together — the network actor
The [`NetworkActor`](https://github.com/base/base/blob/main/crates/consensus/service/src/actors/network/actor.rs) in the service crate ties everything together. It follows the actor pattern, a concurrency design where each component runs as an independent task that communicates with others exclusively through message channels, avoiding shared mutable state. The actor is the top-level component the consensus node's main loop interacts with. It is generic over a [`GossipTransport`](https://github.com/base/base/blob/main/crates/consensus/service/src/actors/network/transport.rs) trait, which lets the real networking stack be swapped out for an in-process test transport:
```rust
#[async_trait]
pub trait GossipTransport: Send + 'static {
type Error: std::fmt::Debug + Send + 'static;
async fn publish(&mut self, payload: BaseExecutionPayloadEnvelope) -> Result<(), Self::Error>;
async fn next_unsafe_block(&mut self) -> Option;
fn set_block_signer(&mut self, address: Address);
fn handle_p2p_rpc(&mut self, request: P2pRpcRequest);
}
```
The production implementation, [`NetworkHandler`](https://github.com/base/base/blob/main/crates/consensus/service/src/actors/network/handler.rs), composes the `GossipDriver` and `Discv5Handler`. It runs a `tokio::select!` loop that simultaneously handles several things: receiving ENRs from discovery and dialing them as new gossip peers, receiving blocks from gossip and forwarding them to the consensus engine, publishing blocks produced locally if the node is the sequencer, inspecting peer scores every 15 seconds and banning low-scoring peers (disconnecting them from gossip and banning their addresses in discovery), and handling administrative RPC requests.
The [`NetworkDriver`](https://github.com/base/base/blob/main/crates/consensus/service/src/actors/network/driver.rs) handles the startup sequence. It starts the gossip swarm first, gets back the actual listen address, optionally updates the local ENR with that address (so other nodes discover the correct port), and then starts discovery. Ordering matters because the ENR must contain the real TCP port that gossip is listening on.
The `NetworkActor` communicates with the rest of the consensus node through `mpsc` channels bundled in a [`NetworkInboundData`](https://github.com/base/base/blob/main/crates/consensus/service/src/actors/network/actor.rs) struct:
```rust
pub struct NetworkInboundData {
pub signer: mpsc::Sender,
pub p2p_rpc: mpsc::Sender,
pub admin_rpc: mpsc::Sender,
pub gossip_payload_tx: mpsc::Sender,
}
```
Other actors in the node (such as the sequencer or the admin RPC server) push data to the network actor through these senders. The `signer` channel updates the expected unsafe block signer address. The `gossip_payload_tx` channel lets the sequencer publish newly produced blocks. This message-passing architecture isolates all networking concerns in one actor without shared mutable state.
### CL startup flow from the command line
When you launch the Base consensus binary, P2P configuration comes from CLI flags defined in [`base-client-cli`](https://github.com/base/base/tree/main/crates/client/cli). Key flags include `--p2p.listen.tcp` (default 9222) and `--p2p.listen.udp` (default 9223) for local bind addresses, `--p2p.advertise.ip` for NAT (Network Address Translation) scenarios where the node sits behind a router and its public IP differs from its local IP, `--p2p.priv.path` for the node's secp256k1 private key, and the mesh parameters such as `--p2p.gossip.mesh.d` for the target mesh size.
The startup flow in the CLI's `exec()` function loads the rollup configuration, parses the P2P arguments into a `NetworkConfig`, constructs a `NetworkBuilder` with both the gossip and discovery builders, and passes it to the `RollupNodeBuilder` which starts the `NetworkActor`. From that point on, the node is live on the consensus P2P network.
## The execution layer P2P stack
The execution layer P2P stack is built on Reth, a high-performance Ethereum execution client written in Rust. The Base-specific customizations live under [`crates/execution/`](https://github.com/base/base/tree/main/crates/execution), and the node definition is in [`crates/execution/node/`](https://github.com/base/base/tree/main/crates/execution/node). For an architectural overview of how this fits the rest of the system, see the [architecture overview](/architecture/overview/).
### How Reth handles networking
Reth implements the standard Ethereum execution layer networking stack. At the transport level it uses DevP2P with RLPx, a cryptographic transport where peers handshake to establish an encrypted, authenticated session. The mechanics resemble HTTPS: both nodes exchange temporary keys and derive a shared secret, after which all communication is encrypted. (For the curious, the handshake uses ECIES — Elliptic Curve Integrated Encryption Scheme — with ephemeral key shares and Diffie-Hellman key agreement. The session is encrypted with AES-256 and authenticated with keccak256-based MACs. Understanding these details is not necessary to work with the codebase.) Once the encrypted channel is up, the two nodes exchange "Hello" messages negotiating which sub-protocols they both support.
On top of this transport, Reth speaks the `eth/68` wire protocol (version 68 of the Ethereum sub-protocol for exchanging chain data between execution clients). It handles block headers, block bodies, receipts, and transaction announcements. For transaction gossip specifically, eth/68 uses a two-phase announcement system: when a node receives a new transaction, it sends the full transaction to a small random fraction of its peers and sends lightweight hash announcements (with type and size metadata) to all other peers, who can then request the full transaction if they do not already have it. Reth also supports the `snap/1` protocol for snapshot-based state synchronization, letting new nodes download state much faster than replaying chain history.
For peer discovery, Reth supports both discv4 (the older UDP-based Kademlia protocol) and discv5 (the newer protocol also used by the consensus layer). Nodes can additionally be configured with static boot nodes and DNS-based discovery.
### The BaseNetworkBuilder
The [`BaseNetworkBuilder`](https://github.com/base/base/blob/main/crates/execution/node/src/node.rs) configures Reth's network for Base. Since transaction gossip became unconditional it carries a single knob:
```rust
pub struct BaseNetworkBuilder {
/// Disable discovery v4
pub disable_discovery_v4: bool,
}
```
Transaction pool gossip is no longer something a node decides for itself. Base sets `tx_gossip_disabled` unconditionally, so a node never broadcasts its pending transactions to DevP2P peers. The reasoning is structural rather than situational: in a rollup only the sequencer orders transactions, so relaying pending ones around the mesh achieves nothing that forwarding to the sequencer does not already do.
The `network_config` method assembles Reth's `NetworkConfig` by applying the discovery settings. The code below builds the configuration step by step: it sets the RLPx socket address, conditionally disables discv4, enables discv5 with boot nodes, and finally sets the transaction gossip flag:
```rust
let network_builder = ctx
.network_config_builder()?
.apply(|mut builder| {
let rlpx_socket = (args.addr, args.port).into();
if disable_discovery_v4 || args.discovery.disable_discovery {
builder = builder.disable_discv4_discovery();
}
if !args.discovery.disable_discovery {
builder = builder.discovery_v5(
args.discovery.discovery_v5_builder(
rlpx_socket,
ctx.config()
.network
.resolved_bootnodes()
.or_else(|| ctx.chain_spec().bootnodes())
.unwrap_or_default(),
),
);
}
builder
});
let mut network_config = ctx.build_network_config(network_builder);
network_config.tx_gossip_disabled = true;
```
Discv4 is disabled by default for Base (`--rollup.discovery.v4` defaults to false) while discv5 is enabled. Boot nodes resolve from CLI arguments first and fall back to the chain specification. Once the config is built, `build_network` creates a `NetworkManager`, starts it, and logs the local enode record (the DevP2P equivalent of an ENR — a URL-formatted node identifier such as `enode://@:`).
### Transaction pool and gossip
The Base transaction pool lives in [`crates/execution/txpool/`](https://github.com/base/base/tree/main/crates/execution/txpool). It extends Reth's standard transaction pool with rollup-specific validation and ordering.
The [`OpTransactionValidator`](https://github.com/base/base/blob/main/crates/execution/txpool/src/validator.rs) wraps Reth's `EthTransactionValidator` and adds L1 data gas fee checks. Every transaction on Base pays both an L2 execution gas cost and an L1 data fee (the cost of posting transaction data to Ethereum L1). The validator confirms the sender's balance covers both. It also rejects EIP-4844 blob transactions (a special transaction type used on L1 to carry large data blobs for rollups, which are not meaningful on the L2 itself).
The ordering strategy is configurable via `--rollup.txpool-ordering` and defined in [`ordering.rs`](https://github.com/base/base/blob/main/crates/execution/txpool/src/ordering.rs):
```rust
pub enum BaseOrdering {
CoinbaseTip(CoinbaseTipOrdering),
Timestamp(TimestampOrdering),
}
```
`CoinbaseTip` is the standard Ethereum priority-fee ordering — higher fees first. `Timestamp` is a rollup-specific FIFO ordering that prioritizes by arrival time regardless of fee, which can produce fairer sequencing.
### Transaction forwarding
A node that is not the sequencer cannot include transactions itself, so whatever lands in its mempool has to be relayed onward to the sequencer. The reader/forwarder pipeline that handles this now lives in a dedicated `tx-forwarding` crate, split out of `txpool`.
The [`DestinationReader`](https://github.com/base/base/blob/main/crates/execution/tx-forwarding/src/reader/task.rs) polls the transaction pool for pending transactions and queues them onto a bounded `tokio::mpsc` channel. The [`DestinationForwarder`](https://github.com/base/base/blob/main/crates/execution/tx-forwarding/src/forwarder/task.rs) drains that queue and relays each transaction to the configured builder endpoints through a custom JSON-RPC method (`base_insertValidatedTransaction`). A separate forwarder task is spawned for each builder URL, so several downstream builders can be fed at once. Both halves of the pipeline run in the background, scheduled on the node's task executor.
From `v1.5.0` (#5479; first in `rc.1`, not in `v1.4.2`), the reader no longer queues purely by arrival. It fills each builder's queue from two lanes. A fixed share of picks, 20% by default, goes to the oldest pending transaction. Every other pick goes to the highest tip-per-gas bid, ranked by the same `coinbase-tip` ordering the builder uses. The picks alternate, so at the default one transaction in five comes from the oldest-first lane.
This only matters when a destination falls behind. With no backlog, everything pending fits in the next batch and the lanes change nothing. During a burst, a late high bid now goes out in the next batch rather than waiting behind the queue. The oldest-first share keeps low bids moving, so they slow down but do not starve. In both lanes, only a sender's earliest unsent transaction is eligible, so each sender's transactions still go out in nonce order.
Order is fixed once a transaction enters the queue. The queue is now two batches deep by default (200 at the default batch size of 100), so the order is chosen close to the send. Under a deep backlog the reader reuses a pool snapshot for up to 10ms, so a new arrival can wait that long before it is considered. Two flags control this, and both need `--enable-tx-forwarding`:
| Flag | Default | Effect |
| --- | --- | --- |
| `--tx-forwarding-fifo-percent` | `20` | Share of picks taken oldest-first, from `0` to `100`. `100` gives pure arrival order |
| `--tx-forwarding-queue-capacity` | 2x the batch size | Per-builder queue depth. A deeper queue fixes the order earlier |
On `main` (#5816, not yet in any tag up to `v1.5.1-rc.6`), a forwarder can also hand a whole batch to the builder in a single call. Turn on `--tx-forwarding-batched-insert` and each batch made only of inserts goes out as one `base_insertValidatedTransactions` request instead of a JSON-RPC batch of single `base_insertValidatedTransaction` calls. The builder admits the batch together, validating it against one state provider, and returns one result per transaction in the same order. A batch holds at most `1024` transactions (`MAX_VALIDATED_INSERT_BATCH`); bigger batches, or ones that mix in requests with no batched form, fall back to single calls.
:::caution
The flag is off by default, and every builder the node forwards to must serve the plural method. Roll it out in order: first upgrade the builders and sequencers, then enable the flag on the mempool nodes. The singular `base_insertValidatedTransaction` remains the method used when the flag is off.
:::
### EL P2P configuration flags
The execution layer P2P is configured through Reth's standard network flags plus Base-specific rollup flags defined in [`args.rs`](https://github.com/base/base/blob/main/crates/execution/node/src/args.rs). Key flags:
Three rollup flags remain. `--rollup.sequencer` names the endpoint that forwarded transactions are sent to. `--rollup.discovery.v4` brings back discv4, which stays off unless you ask for it because discv5 is what Base runs. `--rollup.txpool-ordering` picks the pool's ordering strategy, either `coinbase-tip` or `timestamp`. Nothing here governs gossip any more — the `--rollup.disable-tx-pool-gossip` flag that used to pair with `--rollup.sequencer` has been withdrawn, along with the builder field behind it.
Standard Reth network flags still apply: `--network.addr` and `--network.port` control the RLPx bind address (default port 30303), `--network.discovery.disable-discovery` turns off all peer discovery, and `--network.discovery.bootnodes` provides custom boot node addresses.
## How the two stacks interact at runtime
When a Base node is running, the consensus and execution processes work in tandem but network independently. Block reception flows like this:
The sequencer produces a new L2 block and signs it. The signed block is published as a `NetworkPayloadEnvelope` to the CL gossip network on the appropriate versioned topic (for example, `/optimism/8453/3/blocks` for Isthmus). Every consensus node's `BlockHandler` receives the message, validates it (timestamp, hash, signature, deduplication), and if valid marks it `Accept` and passes it to the consensus engine. The engine sends the execution payload to the local execution client via `engine_newPayloadV*`. The execution client validates the block against the EVM, computes the new state root, and reports the result back.
Submission runs the other way. A transaction arrives at some EL node's RPC endpoint and stops there as far as the mesh is concerned, because pool gossip is off everywhere. Where the node knows a sequencer endpoint, the forwarder hands the transaction straight over by JSON-RPC. From that point it rejoins the path already described: the sequencer seals it into a block, and the block travels back out over CL gossip.
Discovery on each layer is independent. The CL uses discv5 on a UDP port (default 9223) to find other CL peers, validating ENRs by chain ID so it only connects to Base nodes. The EL uses discv5 (and optionally discv4) on its own UDP port to find other EL peers. The two discovery networks are entirely separate and serve different purposes.
## Key files
**Consensus layer peers and ENR management:**
- [`crates/consensus/peers/src/enr.rs`](https://github.com/base/base/blob/main/crates/consensus/peers/src/enr.rs) — BaseEnr encoding and validation
- [`crates/consensus/peers/src/store.rs`](https://github.com/base/base/blob/main/crates/consensus/peers/src/store.rs) — BootStore persistence
**Consensus layer discovery:**
- [`crates/consensus/disc/src/driver.rs`](https://github.com/base/base/blob/main/crates/consensus/disc/src/driver.rs) — Discv5Driver event loop and bootstrap
**Consensus layer gossip:**
- [`crates/consensus/gossip/src/config.rs`](https://github.com/base/base/blob/main/crates/consensus/gossip/src/config.rs) — Gossipsub constants and configuration
- [`crates/consensus/gossip/src/handler.rs`](https://github.com/base/base/blob/main/crates/consensus/gossip/src/handler.rs) — BlockHandler and topic management
- [`crates/consensus/gossip/src/block_validity.rs`](https://github.com/base/base/blob/main/crates/consensus/gossip/src/block_validity.rs) — Block validation rules
- [`crates/consensus/gossip/src/behaviour.rs`](https://github.com/base/base/blob/main/crates/consensus/gossip/src/behaviour.rs) — libp2p Behaviour composition
- [`crates/consensus/gossip/src/gater.rs`](https://github.com/base/base/blob/main/crates/consensus/gossip/src/gater.rs) — Connection rate limiting
- [`crates/consensus/gossip/src/driver.rs`](https://github.com/base/base/blob/main/crates/consensus/gossip/src/driver.rs) — GossipDriver swarm management
**Consensus layer orchestration:**
- [`crates/consensus/service/src/actors/network/actor.rs`](https://github.com/base/base/blob/main/crates/consensus/service/src/actors/network/actor.rs) — NetworkActor definition
- [`crates/consensus/service/src/actors/network/handler.rs`](https://github.com/base/base/blob/main/crates/consensus/service/src/actors/network/handler.rs) — Production NetworkHandler transport
- [`crates/consensus/service/src/actors/network/driver.rs`](https://github.com/base/base/blob/main/crates/consensus/service/src/actors/network/driver.rs) — Network startup sequence
- [`crates/consensus/service/src/actors/network/transport.rs`](https://github.com/base/base/blob/main/crates/consensus/service/src/actors/network/transport.rs) — GossipTransport trait
**Execution layer node and networking:**
- [`crates/execution/node/src/node.rs`](https://github.com/base/base/blob/main/crates/execution/node/src/node.rs) — BaseNetworkBuilder and network configuration
- [`crates/execution/node/src/args.rs`](https://github.com/base/base/blob/main/crates/execution/node/src/args.rs) — Rollup-specific CLI arguments
**Execution layer transaction pool:**
- [`crates/execution/txpool/src/validator.rs`](https://github.com/base/base/blob/main/crates/execution/txpool/src/validator.rs) — OpTransactionValidator with L1 data gas checks
- [`crates/execution/txpool/src/ordering.rs`](https://github.com/base/base/blob/main/crates/execution/txpool/src/ordering.rs) — BaseOrdering (fee-based vs FIFO)
- [`crates/execution/tx-forwarding/src/reader/`](https://github.com/base/base/tree/main/crates/execution/tx-forwarding/src/reader) — Transaction pool reader
- [`crates/execution/tx-forwarding/src/forwarder/`](https://github.com/base/base/tree/main/crates/execution/tx-forwarding/src/forwarder) — Transaction forwarder to sequencer
## Glossary
**Attestation** — A validator's vote that a particular block is valid.
**Beacon chain** — The chain introduced with Ethereum's proof-of-stake upgrade that coordinates consensus.
**Bootnode** — A well-known node whose address is hardcoded into client software, used to bootstrap new nodes into the network.
**CL (Consensus Layer)** — The part of an Ethereum node responsible for consensus (deciding which blocks are canonical).
**DevP2P** — The execution layer's P2P protocol suite, including RLPx transport and the eth wire protocol.
**DHT (Distributed Hash Table)** — A system where many computers collectively maintain a lookup directory without any central coordinator.
**Discv4 / Discv5** — Node Discovery Protocol versions 4 and 5. UDP-based protocols for finding peers.
**EL (Execution Layer)** — The part of an Ethereum node responsible for executing transactions and maintaining state.
**Engine API** — The JSON-RPC interface that the consensus and execution layers use to communicate locally.
**ENR (Ethereum Node Record)** — A signed, self-describing identity document that a node uses to advertise itself (IP, ports, public key, chain metadata).
**EVM (Ethereum Virtual Machine)** — The runtime environment that executes smart contract bytecode.
**Gossipsub** — A publish/subscribe protocol built on libp2p that uses a mesh overlay for efficient message distribution.
**GRAFT / PRUNE** — Gossipsub control messages for adding or removing a peer from the mesh.
**Hardfork** — A protocol upgrade that changes the rules of the network, activated at a specific timestamp.
**IHAVE / IWANT** — Gossipsub control messages for the lazy repair mechanism (advertising and requesting missed messages).
**k-bucket** — A fixed-size list of peers at a particular XOR distance in a Kademlia routing table.
**L1 (Layer 1)** — The base Ethereum chain.
**L2 (Layer 2)** — A chain that runs on top of L1 for scalability (e.g. Base).
**libp2p** — A modular networking framework used by the consensus layer, originally developed for IPFS.
**Mempool** — The pool of pending transactions waiting to be included in a block.
**mpsc** — Multi-producer, single-consumer channel. A thread-safe queue used for async communication in Rust.
**Multiaddr** — A self-describing network address format used by libp2p (e.g. `/ip4/192.168.1.1/tcp/9222`).
**NAT (Network Address Translation)** — When a node is behind a router and its public IP differs from its local IP.
**Reorg** — A chain reorganization where the network switches to a different sequence of blocks.
**RLP (Recursive Length Prefix)** — Ethereum's standard binary serialization format.
**RLPx** — The execution layer's encrypted TCP transport protocol.
**Rollup** — A type of blockchain that executes transactions on its own chain but posts data back to Ethereum for security.
**Sequencer** — The single designated node that orders and produces L2 blocks.
**Snappy** — A fast compression algorithm used for gossip message compression.
**State root** — A cryptographic fingerprint of the entire blockchain state after executing a block's transactions.
**Swarm** — libp2p's term for the combination of transport, protocol behaviors, and connection management.
**XOR distance** — The distance metric used in Kademlia, computed by XOR-ing two node IDs. Has nothing to do with geographic distance.
---
# Proof System Overview
Source: https://basehub.org/specifications/proofs-overview/
Description: Roles of the offchain services and onchain contracts that make Azul L2 checkpoint proposals verifiable from Ethereum.
The proof system is the collection of offchain services and onchain contracts that lets Ethereum verify Base's L2 checkpoint proposals. Every proposal asserts an output root for a fixed L2 block range; independent proof actors then recompute that claim, supply proof material, and dispute the game when the claim does not match canonical L2 state.
This section covers the components used by the Azul proof system. The legacy interactive fault-proof construction is documented separately.
## Component roles
- [Challenger](/specifications/challenger) — watches in-flight games, compares them to canonical L2 state, and disputes claims that disagree.
- [Proposer](/specifications/proposer) — turns a canonical L2 checkpoint range into a new dispute game on L1.
- [Registrar](/specifications/registrar) — keeps the onchain registry of accepted TEE signer identities in sync with the running prover fleet.
- [TEE Prover](/specifications/tee-prover) — produces Nitro Enclave–backed proofs for the common, low-latency proposal path.
- [ZK Prover](/specifications/zk-prover) — produces permissionless proofs that can be used for both proposing and disputing.
- [Proof Contracts](/specifications/contracts) — verify submitted proof material, track game state, and release withdrawals and bonds according to each game's outcome.
---
# Proposer
Source: https://basehub.org/specifications/proposer/
Description: Offchain service that turns canonical L2 checkpoint ranges into AggregateVerifier dispute games on L1.
The proposer is the offchain service that promotes a canonical L2 checkpoint range into an `AggregateVerifier` game on L1. Each cycle it reads the latest onchain parent state, picks the next checkpoint, asks a TEE prover for a proof over that range, revalidates the proof against canonical L2 state, and opens a new dispute game through `DisputeGameFactory`.
The production proposer is gated by the L1 signer it is configured with. Its output remains self-validating end to end: a game is uniquely keyed by game type, claimed output root, parent, L2 block number, and the ordered intermediate output roots, and the proof itself can be re-checked by the onchain verifier and by independent challengers.
## Responsibilities
A conforming proposer is expected to:
1. Load the active `AggregateVerifier` implementation and proposal parameters from L1.
2. Recover the latest onchain parent state from `AnchorStateRegistry` and `DisputeGameFactory`.
3. Pick the next checkpoint block that is at or before the configured safe head.
4. Build a `prover_prove` request covering that checkpoint range.
5. Accept only TEE proof results for proposal creation.
6. Re-check the aggregate output root and every intermediate root against canonical L2 state right before L1 submission.
7. Optionally pre-validate the TEE signer against `TEEProverRegistry`.
8. Submit `DisputeGameFactory.createWithInitData()` with the required bond.
9. Retry transient proof, RPC, and transaction failures without ever creating games out of order.
The proposer does not challenge games, resolve them, claim bonds, or decide withdrawal finality — those duties live with the challenger and the proof contracts.
## Startup Configuration
At startup the proposer connects to:
- an L1 execution RPC for contract reads and transaction submission
- an L2 execution RPC for agreed L2 block headers
- a rollup RPC for sync status and output roots
- a prover RPC that implements `prover_prove`
- `AnchorStateRegistry`
- `DisputeGameFactory`
- an optional `TEEProverRegistry`
The game implementation address comes from:
```text
DisputeGameFactory.gameImpls(gameType)
```
That address must be non-zero. From there the proposer reads:
```text
AggregateVerifier.BLOCK_INTERVAL()
AggregateVerifier.INTERMEDIATE_BLOCK_INTERVAL()
DisputeGameFactory.initBonds(gameType)
```
`BLOCK_INTERVAL` must be at least `2`, `INTERMEDIATE_BLOCK_INTERVAL` must be non-zero, and `BLOCK_INTERVAL % INTERMEDIATE_BLOCK_INTERVAL` must be `0`. The number of intermediate roots a proposal carries is:
```text
BLOCK_INTERVAL / INTERMEDIATE_BLOCK_INTERVAL
```
By default the proposer targets finalized L2 state. Operators may opt into safe-but-not-finalized proposals, in which case the rollup node's safe L2 head is used instead.
## Parent recovery
Before planning new work, the proposer walks forward from L1 to find the current tip of the proposal chain. Parent state is captured as:
```text
parentAddress
parentOutputRoot
parentL2BlockNumber
```
If no games have been created yet, the parent is the anchor root from `AnchorStateRegistry`:
```text
parentAddress = AnchorStateRegistry address
parentOutputRoot = AnchorStateRegistry.getAnchorRoot().root
parentL2BlockNumber = AnchorStateRegistry.getAnchorRoot().l2BlockNumber
```
Otherwise the proposer performs a deterministic forward walk from the anchor root (or from a cached recovered tip when the cache is still fresh). At each step it:
1. Computes:
```text
expectedBlock = parentL2BlockNumber + BLOCK_INTERVAL
```
2. Fetches the canonical output root for every intermediate checkpoint at:
```text
parentL2BlockNumber + INTERMEDIATE_BLOCK_INTERVAL * i
```
for `i` in `1..=BLOCK_INTERVAL / INTERMEDIATE_BLOCK_INTERVAL`.
3. Takes the final intermediate root as the canonical root claim for `expectedBlock`.
4. Builds `extraData` from `expectedBlock`, `parentAddress`, and the ordered intermediate roots.
5. Looks the expected game up:
```text
DisputeGameFactory.games(gameType, rootClaim, extraData)
```
6. If the lookup returns `address(0)`, walk stops and the current parent is the recovered tip.
7. Otherwise it advances the parent to the returned game proxy and repeats.
This recovery does not scan the factory for a "best" game. It uses each game's unique factory key, so only the canonical next game for the recovered parent can advance the parent chain. Any game that disagrees on root, parent, L2 block number, or intermediate roots has a different key and is invisible to recovery.
## Checkpoint selection
After recovery, the next proposal target is:
```text
targetBlock = parentL2BlockNumber + BLOCK_INTERVAL
```
The proposer must not request or submit a proof for `targetBlock` unless:
```text
targetBlock <= safeHead
```
where `safeHead` is either:
- `finalized_l2.number`, by default, or
- `safe_l2.number`, only when non-finalized proposals are explicitly enabled.
When parallel proving is on, multiple proof requests can be in flight for future checkpoints, but L1 submissions are still strictly sequential — at most one proposal transaction is pending at a time, and the next one waits until earlier checkpoint games are recovered or confirmed.
## Proof request
For a checkpoint range the proposer builds a `ProofRequest` with:
| Field | Value |
| ----------------------------- | ---------------------------------------------------------- |
| `l1_head` | Hash of the latest L1 block at request construction time |
| `l1_head_number` | Number of the latest L1 block at request construction time |
| `agreed_l2_head_hash` | L2 block hash at `parentL2BlockNumber` |
| `agreed_l2_output_root` | Parent output root recovered from L1 |
| `claimed_l2_output_root` | Rollup RPC output root at `targetBlock` |
| `claimed_l2_block_number` | `targetBlock` |
| `proposer` | L1 address that will submit the proposal transaction |
| `intermediate_block_interval` | `INTERMEDIATE_BLOCK_INTERVAL` |
| `image_hash` | Expected TEE image hash |
The prover RPC method is:
```text
prover_prove(ProofRequest) -> ProofResult
```
Only `ProofResult::Tee` is accepted by the proposer. ZK proof results are not valid input on this path.
## TEE proposal journal
The TEE prover returns:
- one aggregate proposal that covers the entire checkpoint range
- per-block proposals for each block inside that range
The aggregate proposal carries:
```text
outputRoot
signature
l1OriginHash
l1OriginNumber
l2BlockNumber
prevOutputRoot
configHash
```
The TEE signature is taken over:
```text
keccak256(journal)
```
where `journal` is packed as:
```text
proposer(20)
|| l1OriginHash(32)
|| prevOutputRoot(32)
|| startingL2Block(8)
|| outputRoot(32)
|| endingL2Block(8)
|| intermediateRoots(32 * N)
|| configHash(32)
|| teeImageHash(32)
```
For aggregate proposals:
```text
startingL2Block = parentL2BlockNumber
endingL2Block = targetBlock
prevOutputRoot = parentOutputRoot
outputRoot = claimed root at targetBlock
```
`intermediateRoots` are sampled every `INTERMEDIATE_BLOCK_INTERVAL` blocks and include the final target block root.
## Pre-submission validation
Right before sending to L1, the proposer re-validates the proof against canonical L2 state:
1. Fetch the rollup output root at `targetBlock`.
2. Require it to equal the aggregate proposal's `outputRoot`.
3. Extract the intermediate roots from the per-block proposals.
4. Fetch the canonical output root for every intermediate checkpoint.
5. Require every proposed intermediate root to equal its canonical counterpart.
If the aggregate root or any intermediate root no longer matches canonical state, the proposer drops the pending work and restarts recovery. This is the guard against stale proof results after L1 or L2 reorgs.
When a `TEEProverRegistry` is configured, the proposer should recover the TEE signer from the aggregate proposal signature and call:
```text
TEEProverRegistry.isValidSigner(signer)
```
A `false` return means the proof must not be submitted; discard it and request a new one. If the registry call itself fails for RPC or deployment reasons, the proposer may continue to submission and let the onchain verifier enforce signer validity.
## Game creation
The proposer creates the game with:
```solidity
DisputeGameFactory.createWithInitData{value: initBond}(
gameType,
rootClaim,
extraData,
initData
)
```
where:
```text
rootClaim = aggregateProposal.outputRoot
```
`extraData` is packed, not ABI-encoded:
```text
l2BlockNumber(32) || parentAddress(20) || intermediateRoots(32 * N)
```
`l2BlockNumber` is a 32-byte big-endian integer. `parentAddress` is the recovered parent game proxy, or the `AnchorStateRegistry` address for the first game after the anchor.
`initData` is the TEE proof bytes for `AggregateVerifier.initializeWithInitData()`:
```text
proofType(1) || l1OriginHash(32) || l1OriginNumber(32) || signature(65)
```
For TEE proofs:
```text
proofType = 0
```
The ECDSA `v` value must be normalized to `27` or `28` before submission. `initBond` is read from `DisputeGameFactory.initBonds(gameType)` at startup and is sent as the transaction value. The L1 transaction manager owns nonce management, fee bumping, signing, and resubmission.
## Duplicate games
A game's factory key is:
```text
gameType || rootClaim || extraData
```
If `createWithInitData()` reverts with `GameAlreadyExists`, the proposer treats the target as already submitted, refreshes recovery from L1, and continues from the new tip. This covers both the case where a prior transaction succeeded but the receipt was missed, and the case where another valid proposer beat us to the same game.
## Retry behavior
Transient failures are retried on later ticks:
| Failure | Required behavior |
| ------------------------------------- | ----------------------------------------------------------- |
| Recovery RPC or contract read failure | Skip the current tick and retry recovery on the next tick |
| Proof request failure | Retry the target on a later tick |
| Repeated proof failure | Reset pipeline state and recover from L1 |
| L1 submission failure | Keep the proved result and retry submission on a later tick |
| L1 submission timeout | Treat as a submission failure and retry after recovery |
| `GameAlreadyExists` | Treat as success, refresh recovery, and continue |
| Canonical root mismatch | Reset pipeline state and re-prove from recovered L1 state |
| Invalid TEE signer | Discard the proof and request a new one |
The current implementation retries a single proof target up to three times before resetting pipeline state, and bounds proposal submission with a ten-minute timeout.
## Admin interface
The proposer may expose an optional JSON-RPC admin interface. When enabled, it provides:
| Method | Result |
| ----------------------- | --------------------------------------- |
| `admin_startProposer` | Starts the proving pipeline |
| `admin_stopProposer` | Stops the proving pipeline |
| `admin_proposerRunning` | Returns whether the pipeline is running |
Starting a proposer that is already running, or stopping one that is already stopped, are both errors.
## Dry run mode
In dry run mode the proposer still performs recovery, checkpoint selection, proof sourcing, and pre-submission validation, but it does not send L1 transactions — it just logs the game that would have been created. Useful for validating prover and RPC behavior, but it does not advance the onchain proposal chain.
---
# TEE Prover Registrar
Source: https://basehub.org/specifications/registrar/
Description: Offchain service that discovers TEE prover enclaves, verifies their Nitro attestations onchain with P-384 hints, and maintains the onchain TEEProverRegistry of accepted signer identities.
import { Aside } from '@astrojs/starlight/components';
The registrar is an offchain service that keeps the onchain set of accepted TEE signer identities in sync with the actual running prover fleet. It locates live TEE prover instances, pulls each enclave's AWS Nitro attestation document, computes the P-384 inverse hints the onchain verifier needs to check it, and writes the resulting signer registration to [`TEEProverRegistry`](https://github.com/base/contracts/blob/main/src/L1/proofs/tee/TEEProverRegistry.sol) on L1. It also removes signers whose backing instances have disappeared and revokes certificates that AWS has marked as withdrawn.
The Base team operates a single registrar. The proof system trusts only signers that this registrar has admitted, which makes registrar correctness a prerequisite for accepting TEE proofs onchain. The output is still self-validating end-to-end. Every certificate signature, the attestation signature, the enclave PCR0 measurement, and the signer public key are re-checked onchain by `TEEProverRegistry` and its `NitroValidator` and `CertManager` before the signer is treated as valid. The hints only speed that check up. A wrong hint makes the check fail, it cannot make a bad attestation pass.
## Responsibilities
A conforming registrar performs the following work each cycle:
1. Discover the current set of TEE prover instances behind the production load balancer.
2. Fetch per-enclave signer public keys and Nitro attestation documents from each instance.
3. Check the attestation certificate chain against the onchain revocation set and, when enabled, against AWS-published CRLs.
4. Compute P-384 hints for every enclave that is not yet registered, and cache any certificate in the chain that `CertManager` has not verified yet.
5. Submit `TEEProverRegistry.registerSigner()` for newly attested signers.
6. Submit `TEEProverRegistry.deregisterSigner()` for onchain signers whose instances are no longer reachable.
7. Submit `CertManager.revokeCert()` for any certificate found to be revoked.
The registrar deliberately does not gate which PCR0 measurements are admitted. Registration is PCR0-agnostic so the next image's signers can be pre-registered ahead of a hardfork. Whether a proof produced by a given signer is actually accepted is decided onchain by [`TEEVerifier`](https://github.com/base/contracts/blob/main/src/L1/proofs/tee/TEEVerifier.sol), which compares against the active game implementation's current `TEE_IMAGE_HASH`.
The registrar also does not build proposals, generate proof material for proposals or disputes, or challenge invalid state transitions. Those duties live with the proposer, the TEE provers, and the challenger.
## Startup configuration
At startup, the registrar connects to:
- an L1 execution RPC for contract reads and transaction submission
- AWS APIs for ELBv2 target health and EC2 instance metadata
- a JSON-RPC endpoint on each discovered TEE prover instance
- `TEEProverRegistry`
- the `NitroValidator` that the registry reports through `NITRO_VALIDATOR()`, and the `CertManager` that validator points to
The operator supplies only the registry address. The registrar reads the validator and certificate manager addresses from the chain at startup and refuses to start if either is zero. Any onchain signer that is not present in its own instance set is treated as an orphan candidate, so a given `TEEProverRegistry` must be written by exactly one registrar.
## Driver loop
The service runs a single driver loop:
1. Discover the current instance set through AWS.
2. Probe `readyz` on every target that is not draining, and resolve signer keys and attestations concurrently, bounded by `max_concurrency`.
3. Start a registration task for each eligible signer, and cancel tasks whose signer is no longer eligible.
4. Read the onchain signer set and deregister orphans, but only when discovery was conclusive.
5. Sleep `poll_interval` seconds, or exit on cancellation.
`step()` runs once at startup before the first sleep. Cancellation is observed promptly between ticks and inside long-running transaction retries, so the service can shut down without leaving partial state behind.
## Instance discovery
Discovery is driven exclusively by AWS ALB target group polling — DNS, SRV, and Kubernetes discovery are not supported.
Each discovery cycle:
1. Calls `elasticloadbalancingv2.DescribeTargetHealth(target_group_arn)`.
2. Drops non-instance targets (IDs that do not start with `i-`).
3. Deduplicates instance IDs that appear on more than one port.
4. Calls `ec2.DescribeInstances(instance_ids)` to read each instance's private IP and launch time.
5. Builds JSON-RPC endpoint URLs shaped like `http://{private_ip}:{prover_port}` and pairs each one with its ALB-reported health state.
The registrar does not trust the ALB health state to decide who may register. The load balancer's `/healthz` check only passes once an instance is registered, so relying on it would block every new instance from ever bootstrapping. Instead, the registrar calls the prover's own `readyz` method on every target that is not `Draining`, right before it resolves that target. A target that answers becomes `Healthy`. A target that fails becomes `Unhealthy`. Only `Healthy` instances can start a new registration. A slow probe does not hold up the others, because each probe is paired with its own resolution.
When an instance drops out of discovery or turns unhealthy, the registrar keeps protecting the signers it last saw there for `instance_cache_ttl_cycles` cycles. If any instance is still unresolved, it skips the whole orphan pass for that tick.
An AWS API error or missing EC2 data aborts the tick and skips orphan cleanup. An empty target group is different: it counts as a conclusive answer.
## Per-instance processing
For each discovered instance, the registrar:
1. Calls `enclave_signerPublicKey` to fetch the per-enclave SEC1 public keys. A single instance can host multiple enclaves, and each enclave has its own signer key.
2. Derives the Ethereum signer address from each public key as the last 20 bytes of `keccak256(uncompressed_pubkey_xy)`.
3. Returns immediately when no signers were reported — that instance contributes nothing to the active set, and the call becomes a no-op.
4. Decides whether the instance is currently registerable. Only an instance whose `readyz` probe passed proceeds. A `Draining` instance still adds its known signer addresses to the active set, so a rotation does not deregister it at once, but it starts no new registrations.
5. Calls `enclave_signerAttestation` once with one nonce per signer. Each nonce is deterministic: `keccak256` over the domain string `base-proof-tee-registrar:attestation-nonce:v1`, the registry address, and the signer address. That binds each attestation to one signer and one registry, and the registrar rejects any plan whose nonce does not match.
6. Runs CRL checks once per batch when CRL checking is enabled. Each enclave signs with its own key, but AWS Nitro attestations are signed by the parent EC2 instance's Nitro Hypervisor, whose signing key is endorsed by a per-instance AWS-issued certificate chain. Every enclave on a given instance therefore lives under the same parent chain, so one CRL check per instance is sufficient.
7. Runs the registration pipeline for each signer address.
All reachable instances contribute to the active signer set, including `Draining` and `Unhealthy` ones. This prevents an instance that is rotating in or out from being deregistered prematurely.
## Registration plan and hints
For each signer that is not yet onchain, the registrar first turns the raw attestation into a registration plan. The planner parses the `COSE_Sign1` envelope strictly, keeping the raw protected header and payload so the signed bytes can be rebuilt exactly. The plan lists the certificate chain from the AWS root down to the leaf, with each certificate's hash, parent hash, and revocation ID.
Before any transaction, the plan must pass these checks:
- The signer in the plan equals the signer the instance reported.
- The nonce equals the deterministic nonce for that signer and registry.
- PCR0 is a 48-byte value and is not the debug-mode measurement.
- The chain starts at the pinned Nitro root, whose hash is `0x311d96fcd5c5e0ccf72ef548e2ea7d4c0cd53ad7c4cc49e67471aed41d61f185`.
- Every entry before the last is a CA certificate, the last is the leaf, and each parent hash links to the one before it.
- The attestation timestamp is not in the future and is younger than `max_attestation_age`.
The registrar then computes the P-384 hints. It walks the same affine point schedule the onchain verifier uses and records every modular inverse as a 48-byte big-endian value. There is one hint set per certificate signature, plus one for the attestation signature. This runs on a blocking thread, and a semaphore caps how many hint jobs run at once.
The default freshness window is 3300 seconds, kept under the onchain `MAX_AGE` of 3600 seconds so a plan that passes locally still lands before it ages out onchain.
### Certificate caching
`CertManager` stores every certificate it has already verified. Before registering, the registrar walks the chain and, for each certificate not yet cached, sends one caching transaction: `verifyCACertWithHints` for a CA and `verifyClientCertWithHints` for the leaf. A per-certificate lock stops two signers that share a chain from caching the same certificate twice. Once the leaf is cached, later attestations under that leaf take the short path. Cache writes need no permission, because the contract verifies every certificate and hint itself. After each caching transaction the registrar reads the cache again. If a transaction reports an error but the expected entry is now present and usable, it counts as a success. After a restart or a partial failure, the registrar resumes from the first certificate that is still missing.
Each signature check gets its own transaction, which keeps every transaction under the EIP-7825 per-transaction gas limit. For a typical Nitro chain with three non-root CAs, the count depends on what is already cached:
| Already cached | Transactions |
| --- | ---: |
| Nothing | 5: three CA writes, one leaf write, one registration |
| CA chain only | 2: one leaf write, one registration |
| CA chain and leaf | 1: registration only |
The final `registerSigner` call carries no certificate hints. `NitroValidator` accepts it only if the whole chain is already cached and usable. Because a cold registration takes several transactions, the registrar checks attestation freshness again before every certificate, revocation, and registration transaction. That way it stops before it sends material that has gone stale.
## Registration transactions
For each unregistered signer, the registrar:
1. Calls `TEEProverRegistry.isRegisteredSigner(signer)` and skips the signer if it returns true.
2. Builds the plan and hints, and caches any missing certificates, as described above.
3. ABI-encodes `registerSigner(attestationTbs, signature, hints)` (selector `0xb39dc09d`).
4. Submits the transaction through the L1 transaction manager.
5. Retries failed submissions according to the rules below.
6. Increments the registration counter on a successful receipt.
The transaction retry rules are:
| Failure | Required behavior |
| ----------------------------- | ------------------------------------------------------------------------------------------------------- |
| Retryable error | Sleep `tx_retry_delay`, then retry, up to `max_tx_retries` total attempts. |
| `ExecutionReverted` revert | Return the error. The next cycle fetches a fresh attestation and builds a new plan. |
| Insufficient funds, fee cap | Treat as non-retryable. Surface the error and stop attempting this signer for the current cycle. |
| Reverted receipt | Treat as a transaction failure even when submission succeeded. |
| Reported error after mining | Re-read `isRegisteredSigner(signer)`. If true, treat the attempt as success. |
The post-error reconciliation matters because fee-bumping and nonce races can surface errors even when the underlying transaction has already been mined. Without the recheck, the registrar would redo hinting and send another transaction for a signer that is already registered.
Transaction submission is cancellation-aware: both the active send and the inter-attempt sleep abort cleanly on shutdown, so the next process starts from a clean nonce state without committing a partial transaction.
## Orphan deregistration
After every instance has been processed, the registrar reconciles the onchain signer set against the active set:
1. Skip cleanup if discovery failed during this tick, or if cancellation was requested.
2. Skip cleanup if any instance is still unresolved.
3. Build the protected set: active signers, signers kept from the last-known cache, and signers with a registration task still pending.
4. Read the onchain set with `TEEProverRegistry.getRegisteredSigners()`.
5. Compute `orphans = onchain_signers - protected_signers`.
6. For each orphan, in order:
1. Recheck `isRegisteredSigner(signer)`. Skip if it returns false.
2. ABI-encode `deregisterSigner(signer)` and submit it through the transaction manager.
Deregistration clears the registered flag and the stored image hash. The unresolved-instance rule and the last-known-signer grace period replace the older majority-reachable guard, which is no longer in the source. Together they keep a short AWS or VPC outage from deregistering live signers. The per-orphan `isRegisteredSigner` recheck is a race guard: the set returned by `getRegisteredSigners()` is read once per cycle, and a different writer might have deregistered the signer between that read and this transaction. Skipping signers that are already gone avoids wasted gas on a no-op transaction.
The procedure assumes a single registrar per `TEEProverRegistry`. Two registrars sharing a registry would each treat the other's signers as orphans.
## Certificate revocation
Revocation now lives on `CertManager` and is keyed by a certificate's issuer and serial number rather than by its position in a chain. The registrar applies two layers, in order.
### Layer 1: onchain revocation pre-check
For the pinned root and every certificate in the plan, the registrar asks `CertManager` whether that ID is revoked. Any hit stops registration for that signer. This check runs even for signers that are already registered, so a revoked chain is noticed as early as possible.
### Layer 2: AWS CRL distribution points
This layer runs only when CRL checking is on. For certificates that pass Layer 1, the registrar:
1. Parses each CRL distribution point from the chain.
2. Accepts only URLs whose host ends in `.amazonaws.com` and contains the `nitro-enclave` keyword. Redirects are off and responses are capped at 10 MiB.
3. Fetches the CRL with a 30-second timeout.
4. Looks up the certificate's serial number.
5. Submits `CertManager.revokeCert(certId)` for any revoked certificate it finds.
6. Blocks registration for that signer.
A recorded revocation protects every later registration that shares the same chain, because Layer 1 catches it on the next pass without a network fetch.
A CRL fetch or parse failure fails open and is retried on a later cycle. A revocation confirmed onchain always fails closed.
Revocation and expiry only block new registrations. They do not remove signers that are already registered. If a certificate under an existing signer is revoked, deregister that signer yourself.
## Pending registration lifecycle
Each signer has at most one registration task in flight, keyed by its address. A task runs through these stages:
```mermaid
flowchart TB
Start([signer not registered]) --> Plan[Build and validate plan]
Plan --> Revoke{Revoked or on CRL?}
Revoke -->|yes| Stop([Skip signer])
Revoke -->|no| Hints[Compute P-384 hints]
Hints --> Cache[Cache missing certificates]
Cache --> Send[tx_manager.send registerSigner]
Send -->|Ok| Done([Registered])
Send -->|Retryable| Send
Send -->|Stale or reverted| Next([Retry next cycle])
```
A stale attestation, a reverted transaction, or a cancelled task all end the attempt. The next cycle starts again from a fresh attestation, so a signer cannot get stuck.
## Onchain interactions
The registrar issues the following contract calls. `TEEProverRegistry.isValidSigner()` is intentionally never called by the registrar — that predicate is enforced by `TEEVerifier` at proof-submission time and includes an image-hash match that the registrar itself cannot satisfy.
| Contract | Method | Caller path |
| -------------------------------------------------------------------------------------------------------------------------- | ------------------------------- | --------------------------------------------------- |
| [`TEEProverRegistry`](https://github.com/base/contracts/blob/main/src/L1/proofs/tee/TEEProverRegistry.sol) | `registerSigner(attestationTbs, signature, hints)` | Per-signer registration transaction. |
| `TEEProverRegistry` | `NITRO_VALIDATOR()` | Startup, to find the validator. |
| `NitroValidator` | `certManager()` | Startup, to find the certificate manager. |
| `CertManager` | `verifyCACertWithHints` / `verifyClientCertWithHints` | Caching a certificate that is not yet verified. |
| [`TEEProverRegistry`](https://github.com/base/contracts/blob/main/src/L1/proofs/tee/TEEProverRegistry.sol) | `deregisterSigner(signer)` | Per-orphan deregistration transaction. |
| [`TEEProverRegistry`](https://github.com/base/contracts/blob/main/src/L1/proofs/tee/TEEProverRegistry.sol) | `isRegisteredSigner(signer)` | Pre-check, post-error reconciliation, orphan race guard. |
| [`TEEProverRegistry`](https://github.com/base/contracts/blob/main/src/L1/proofs/tee/TEEProverRegistry.sol) | `getRegisteredSigners()` | Once per cycle for orphan computation. |
| `CertManager` | `revokeCert(certId)` | When an AWS CRL lists a certificate. |
| `CertManager` | revocation lookup by issuer and serial | Layer-1 onchain revocation pre-check. |
PCR0 enforcement happens onchain at proof submission, not at registration. The registrar registers any enclave whose Nitro attestation verifies, regardless of PCR0 value. That makes it possible to bring up the next image's fleet and pre-register its signers before a hardfork; those signers cannot produce accepted proposals until the active game implementation's `TEE_IMAGE_HASH` matches their registered image hash.
## Service lifecycle
At startup, the registrar:
1. Parses CLI configuration and validates it.
2. Initializes tracing and installs the `rustls` ring crypto provider.
3. Installs a signal handler that triggers a cancellation token.
4. Initializes Prometheus metrics, including L1 wallet balance monitoring.
5. Builds the L1 provider, transaction manager, AWS SDK clients, and discovery client.
6. Builds the registry client, then reads the `NitroValidator` and `CertManager` addresses from the chain.
7. Starts the health server and marks readiness.
8. Starts the driver loop.
The health endpoint reports ready as soon as wiring completes. Connectivity gating is intentionally omitted because the registrar is outbound-only.
Each driver tick:
1. Discovers instances and probes `readyz`.
2. Processes instances concurrently.
3. Computes orphans, but only when no instance is unresolved.
4. Submits deregistration transactions for any confirmed orphans.
Shutdown is driven by a cancellation token. The driver loop exits, in-flight per-instance futures are dropped, the readiness flag clears, the `up` metric is set to zero, and the health server is joined.
## Operator inputs
A registrar needs:
| Input | Env variable | Default |
|---|---|---|
| L1 RPC endpoint | `L1_RPC_URL` | none |
| `TEEProverRegistry` address | `TEE_PROVER_REGISTRY_ADDRESS` | none |
| ALB target group ARN | `TARGET_GROUP_ARN` | none |
| AWS region | `AWS_REGION` | none |
| Prover JSON-RPC port | `PROVER_PORT` | `8000` |
| Maximum attestation age | `MAX_ATTESTATION_AGE_SECS` | `3300` |
| Poll interval | `POLL_INTERVAL_SECS` | `30` |
| Prover JSON-RPC timeout | `PROVER_TIMEOUT_SECS` | `30` |
| Concurrent instances per cycle | `MAX_CONCURRENCY` | built-in default |
| Cycles to keep signers of an instance missing from discovery | `INSTANCE_CACHE_TTL_CYCLES` | built-in default |
| Transaction retries | `MAX_TX_RETRIES` | built-in default |
| First retry delay | `TX_RETRY_DELAY_SECS` | built-in default |
It also needs an L1 transaction signer (a local key, or a remote signer plus the expected address) and the transaction manager settings. Retry delays double on each attempt, up to 60 seconds.
Optional inputs are `CRL_NITRO_VERIFIER_ADDRESS` (turns CRL checks on, see the caution above), the health server bind address and port, logging, and Prometheus metrics settings. The Boundless, RISC Zero, and guest ELF inputs are gone.
## Safety requirements
Any registrar implementation must preserve these safety properties:
- Never deregister live signers because of a transient AWS or VPC outage. Skip the orphan pass while any instance is unresolved, and honour the last-known-signer grace period.
- Keep the known signers of `Draining` and recently unavailable instances in the active set, so rotations do not race deregistration.
- Recheck attestation freshness before each transaction in a multi-transaction cold registration.
- Request each attestation with the deterministic per-signer nonce and reject any plan whose nonce, signer, root, or chain links do not match.
- Reject debug-mode PCR0 values before any transaction.
- Reject attestations older than `max_attestation_age`, keeping every submission inside the onchain `MAX_AGE` window.
- Recheck `isRegisteredSigner` after a transaction error to absorb fee-bump and nonce-race false negatives.
- Recheck `isRegisteredSigner` for every orphan candidate immediately before submitting a deregistration, so a concurrent writer or an earlier in-flight transaction cannot cause a redundant deregistration.
- Run the onchain revocation pre-check before fetching network CRLs, so a certificate revoked once stays revoked.
- Restrict CRL fetches to allowlisted hosts and bound the response size to defeat SSRF and resource-exhaustion attacks.
- Treat unavailable AWS APIs, unreachable prover endpoints, and transient RPC errors as retryable conditions for the next tick — not as deregistration or failure signals.
---
# Reth V2
Source: https://basehub.org/specifications/reth-v2/
Description: The Reth V2 node release — up to 50% smaller on disk, with a rebuilt state-root pipeline that raises throughput and lowers per-block execution latency.
import { Aside } from '@astrojs/starlight/components';
Base's execution client is Reth, a high-performance Ethereum client. Its next major release, Reth V2, goes straight at the two things that bound a high-throughput chain: how much disk a node burns and how fast it can compute state roots.
## Storage V2
Storage V2 reworks the on-disk layout to bring node storage requirements down sharply:
| Node type | Disk reduction |
|-----------|----------------|
| Full | ~30% |
| Minimal | ~50% |
| Archive | ~23% |
That lifts a disk-growth ceiling that would otherwise cap how far Base can push block throughput.
## State root computation
Reth V2 rebuilds the state-root pipeline around three changes:
- **Warm sparse-trie caching across blocks** — skips recomputing subtrees that didn't change from one block to the next.
- **Parallel trie** — spreads state-root work across CPU cores at once.
- **Proof V2** — a reworked proof-generation path that trims per-proof overhead.
## Performance
Across Reth's published benchmarks, those changes add up to:
- **+33% throughput**
- **~25% lower average block-execution latency**
`base-reth-node` picks up these gains directly, adding headroom on the way toward 1 gigagas/s.
---
# TEE Prover
Source: https://basehub.org/specifications/tee-prover/
Description: Offchain service that re-executes L2 block ranges inside AWS Nitro Enclaves to produce signed proof material for AggregateVerifier games.
The TEE prover is the offchain service that produces signed proof material for `AggregateVerifier` games by re-deriving and re-executing an L2 block range inside an AWS Nitro Enclave. The same service powers both proposal creation and dispute nullification: callers (proposer or challenger) submit a block range, the host gathers witness data, the enclave re-executes the range, and a per-instance key that lives only inside the enclave signs the resulting journal.
Verification of the signature is self-contained onchain. `TEEVerifier` recovers the signer from each proposal and checks it against `TEEProverRegistry` for the active game implementation's `TEE_IMAGE_HASH`. A signer from a different enclave image, or one that has been deregistered, cannot satisfy verification. The Nitro hypervisor's per-instance attestation binds the signer's public key to a specific PCR0, which the [registrar](/specifications/registrar) certifies separately.
## Responsibilities
A conforming TEE prover stack:
1. Serve `prover_prove` for proposal and dispute ranges over JSON-RPC.
2. Collect witness data from canonical L1, L1 beacon, and L2 RPCs on the host.
3. Forward content-verified preimages to the enclave over vsock.
4. Re-derive and re-execute the L2 range inside the enclave and validate the claimed output root against the re-executed one before signing anything.
5. Sign per-block journals and an aggregate journal with a secp256k1 key generated inside the enclave.
6. Expose `enclave_signerPublicKey` and `enclave_signerAttestation` for the registrar.
7. Optionally gate every request on registry signer validity to fail closed against deregistered enclaves.
8. Support multi-enclave deployment on a single EC2 parent so different PCR0 images can run side-by-side across rotations.
The TEE prover never decides whether a proposal or dispute is correct. It re-executes the range, signs the result when the re-execution matches the claim, and returns. Callers still recheck game state before submitting onchain.
## Architecture
The service runs as two processes on a Nitro-capable EC2 parent:
- A **host** binary (`base-prover-nitro-host`) that terminates JSON-RPC, gathers witness data over HTTP, and proxies requests to one or more enclaves.
- An **enclave** binary (`base-prover-nitro-enclave`) packed into an EIF that holds the signing key, exposes a vsock listener, and runs the proof pipeline.
The two processes talk only over vsock. The enclave has no network interface; all external RPC connectivity sits on the host side.
```mermaid
flowchart LR
caller[Proposer / Challenger]
host[NitroProverServer\nbase-prover-nitro-host]
rpc[L1 EL / L1 beacon / L2 EL]
enclave[NitroEnclave\nbase-prover-nitro-enclave]
nsm[NSM\nPCR0 / RNG / attestation]
caller -- "prover_prove\nenclave_*" --> host
host -- "witness build" --> rpc
host -- "vsock\nlength-prefixed bincode" --> enclave
enclave --> nsm
```
Each vsock connection handles exactly one request before closing. The enclave keeps no per-request state between connections; the only persistent state inside is the signer key and the boot-time PCR0 measurement.
Vsock frames use a `u32` big-endian length prefix followed by a bincode payload, with a 5-minute read timeout. The transport caps write chunks at 28 KiB to dodge a Linux kernel `virtio_vsock` SKB corruption bug.
## JSON-RPC interface
The host serves two JSON-RPC namespaces on a single HTTP listener, plus an HTTP `GET /healthz` proxy that routes to the JSON-RPC `healthz` method.
| Method | Purpose |
| ---------------------------- | ------------------------------------------------------------------------ |
| `prover_prove` | Produce per-block and aggregate signed proposals for a block range. |
| `enclave_signerPublicKey` | Return the 65-byte uncompressed secp256k1 public key for each enclave. |
| `enclave_signerAttestation` | Return the COSE_Sign1 attestation document for each enclave. |
| `healthz` / `GET /healthz` | Liveness, plus optional onchain signer validity (latching) when enabled. |
The `enclave_*` calls are all-or-nothing across multiple enclaves: a transport failure or an error from any enclave fails the whole response. Callers register every signer together, so a partial response would be unusable.
### prover_prove request
`ProofRequest` fields:
| Field | Meaning |
| ------------------------------ | ------------------------------------------------------------------------------------------------------ |
| `l1_head` | L1 head block hash anchoring the derivation window. |
| `l1_head_number` | L1 head block number. |
| `agreed_l2_head_hash` | L2 block hash at the parent of the range. |
| `agreed_l2_output_root` | Output root at the parent. Used as the starting state. |
| `claimed_l2_output_root` | Claimed output root at the target. Trust-critical: the enclave only signs if re-execution matches it. |
| `claimed_l2_block_number` | Target L2 block number (ending block of the range). |
| `proposer` | L1 address that will submit the proof. Committed into the journal so onchain `msg.sender` must match. |
| `intermediate_block_interval` | Sampling stride for intermediate roots in the aggregate proposal. |
| `image_hash` | `keccak256(PCR0)` the caller expects. Currently informational; routing uses onchain signer validity. |
### prover_prove response
`ProofResult::Tee` carries:
| Field | Meaning |
| -------------------- | --------------------------------------------------------------------------------------------- |
| `aggregate_proposal` | One `Proposal` covering the full range with sampled intermediate roots. |
| `proposals` | Per-block `Proposal`s in order, each chaining `prev_output_root` to the previous block's root.|
Each `Proposal`:
| Field | Meaning |
| ------------------ | ---------------------------------------------------------------------------------- |
| `output_root` | Output root at this proposal's ending block. |
| `signature` | 65-byte secp256k1 ECDSA signature (`r || s || v`) over `keccak256(journal)`. |
| `l1_origin_hash` | L1 head hash used during derivation. |
| `l1_origin_number` | L1 head block number. |
| `l2_block_number` | Ending L2 block number for this proposal. |
| `prev_output_root` | Output root before this proposal's range. |
| `config_hash` | Per-chain config hash hardcoded into the enclave. |
A single-block range collapses the aggregate proposal into the lone per-block proposal. For multi-block ranges the aggregate carries its own signature over a journal whose `prev_output_root` is the request's `agreed_l2_output_root`, whose `intermediate_roots` are sampled at `intermediate_block_interval`, and whose `ending_l2_block` is the final block in the range.
### enclave_signerAttestation
The call is `enclave_signerAttestation(user_data, nonces)`. Both arguments are optional:
| Argument | Type |
| --- | --- |
| `user_data` | `Option>` |
| `nonces` | `Option>>` |
`nonces` is now a list with one entry per enclave, not a single shared value. The host puts the same `user_data` into every attestation and hands out the nonces in `enclave_signerPublicKey` order. If you pass `nonces`, the list length must equal the number of configured enclaves. If you leave it out, no enclave gets a nonce. The NSM hardware allows 512 bytes for `user_data` and 512 bytes per nonce. A wrong nonce count or an oversized value fails with JSON-RPC error `-32602` before anything crosses vsock.
The host returns one raw `COSE_Sign1` document per configured enclave, in that same order. The registrar sends each signer its own [deterministic challenge](/specifications/registrar/), which ties the attestation to one registry and one signer before it goes onchain.
## Proof pipeline
A single `prover_prove` request flows host → vsock → enclave → host:
1. **Host**: `ProverService::prove_block` constructs a `Host` from the prover config, then calls `Host::build_witness` to walk L1 EL, L1 beacon, and L2 EL and populate an `Oracle` with hash-keyed preimages.
2. **Host**: `NitroBackend::prove` flattens the oracle into `(PreimageKey, Vec)` pairs and `NitroTransport::prove` sends them over vsock as one `EnclaveRequest::Prove(...)` frame.
3. **Enclave**: `Oracle::new` content-verifies every `Keccak256`- or `Sha256`-keyed preimage so the stored value actually hashes to its key.
4. **Enclave**: `BootInfo::load` extracts the proposer, L1 head, agreed/claimed roots, intermediate-block interval, and chain ID from local preimages.
5. **Enclave**: `config_hash_for_chain` looks up a hardcoded per-chain config hash from `CONFIG_HASHES` (computed at first access from `ChainConfig::all()`). Unknown chain IDs return `UnsupportedChain` and refuse to prove.
6. **Enclave**: the proof prologue drives derivation and execution via `driver.execute_with_intermediates()`. The epilogue's `validate()` is the trust-critical gate — it confirms the re-executed final output root matches the request's `claimed_l2_output_root`. Signing only happens after this check passes.
7. **Enclave**: for each block result, build a `ProofJournal` with empty `intermediate_roots` and sign it; chain `prev_output_root` through the loop. Then build and sign the aggregate journal with sampled intermediate roots.
8. **Enclave**: return `EnclaveResponse::Prove(ProofResult::Tee { aggregate_proposal, proposals })`.
9. **Host**: return the result to the JSON-RPC caller, applying the configured proof request timeout (default 1740 s, ~29 minutes).
The proposer consumes both the aggregate and per-block proposals: per-block roots feed `proposeOutputRoots` and the aggregate signature satisfies `AggregateVerifier`. The challenger only uses the aggregate signature, repacking it for `nullify()` via `ProofEncoder::encode_dispute_proof_bytes`. The enclave neither knows nor cares which caller it is serving.
## Signed journal
Each signature is `secp256k1.sign(keccak256(journal))`, serialized as 65 bytes (`r || s || v`). The journal is packed (not ABI-encoded), `196 + 32·N` bytes where `N` is the number of intermediate roots:
```text
proposer(20) || l1OriginHash(32) || prevOutputRoot(32)
startingL2Block(8) || outputRoot(32) || endingL2Block(8)
intermediateRoots(32 × N) || configHash(32)
teeImageHash(32)
```
Per-block proposals have `N == 0` and `startingL2Block == endingL2Block - 1`. Aggregate proposals have `startingL2Block == firstBlock - 1`, `endingL2Block == lastBlock`, and `N == lastBlock / intermediate_block_interval`.
`teeImageHash` is `keccak256(PCR0)` taken at enclave boot. Embedding it into every journal means a signature recovered onchain transitively commits to the exact EIF measurement that produced it. In local mode (no NSM, development and test only), `teeImageHash` is zero.
The signature `v` byte is encoded as the secp256k1 recovery id (`0` or `1`); callers normalize it to whichever EIP-155 form they need before L1 submission.
## Multi-enclave routing
`--vsock-cid` accepts one or more CIDs, so a single host process can attach to multiple enclaves running on the same EC2 parent. Each CID is an independent vsock endpoint that can run a different EIF — a different PCR0, a different `tee_image_hash`, and a different registered signer.
`--tee-prover-registry-address` is required whenever more than one CID is configured. Without the registry there is no deterministic way to pick between enclaves, so multi-enclave deployments are fail-closed-only.
Per-request routing walks configured CIDs in order and picks the first enclave whose signer is currently valid in `TEEProverRegistry`:
1. Fetch the signer public key from the enclave (skip the transport if this fails).
2. Call `isValidSigner(signer)` on `TEEProverRegistry`.
3. If valid, route the request to this enclave. If not, log and continue.
4. If no enclave in the list has a valid signer, fail the request with `NoValidSigner`.
The common operational case is image rotation. Run the old and new EIFs side-by-side; both signers stay registered for the active game implementation's `TEE_IMAGE_HASH` during the overlap window; after the registry switches to the new image hash only the new enclave's signer is valid and every new request routes to it.
`enclave_*` calls fan out to every configured enclave so the registrar can register every signer in one cycle.
## Registration gating and health
Setting `--tee-prover-registry-address` enables two registry-backed behaviors on the host:
- `GET /healthz` only reports healthy after at least one enclave's signer has been confirmed valid onchain. The health flag latches: once an enclave has been seen valid, `/healthz` continues to report healthy even if the registry RPC later fails or the signer is deregistered. This keeps load balancers stable through short outages.
- Every `prover_prove` request consults `RegistrationChecker::select_valid_enclave` before forwarding. A deregistered enclave, or one whose key fetch fails, is skipped. If no enclave is valid the request is rejected with JSON-RPC error code `-32001`.
Without the registry flag, the host is permissive: `/healthz` reports healthy as long as the server is up, and `prover_prove` routes to the first configured enclave.
## Attestation
The signer key is generated inside the enclave at startup and never leaves the enclave process. The `Server::new_enclave` constructor:
1. Opens an NSM session (`nsm_init`).
2. Reads PCR0 (48-byte SHA-384). A wrong-length PCR0 aborts startup.
3. Computes `tee_image_hash = keccak256(PCR0)` and stores it for inclusion in every signed journal.
4. Generates a secp256k1 ECDSA key with `NsmRng`, which calls `nsm_process_request(Request::GetRandom)`.
5. Logs the signer address (no key material).
There is no startup or periodic attestation. Attestations are produced only when the registrar calls `enclave_signerAttestation`. Each call:
1. Opens a fresh NSM session.
2. Calls `nsm_process_request(Request::Attestation { public_key, user_data, nonce })`.
3. Returns the raw COSE_Sign1 bytes.
The attestation document embeds the 65-byte uncompressed public key, all populated PCRs, the AWS-issued certificate chain, the timestamp, and the supplied `user_data`/`nonce`, all signed by the per-instance Nitro hypervisor key. Only PCR0 is consumed by this system — it is the value bound into every signed journal via `teeImageHash = keccak256(PCR0)`. See the [registrar](/specifications/registrar) spec for how attestations are verified and submitted onchain.
## Service lifecycle
The host startup sequence (`ServerArgs::run`):
1. Parse CLI; initialize logging and metrics via `base_cli_utils`.
2. Resolve the `RollupConfig` and L1 chain config from `--l2-chain-id`. Fail on unknown chains.
3. Build one `NitroTransport::vsock(cid, 8000)` per `--vsock-cid`.
4. Construct `NitroProverServer::new_multi(prover_config, transports, timeout)` and, if `--tee-prover-registry-address` is set, wrap with `RegistrationHealthConfig`.
5. Build a jsonrpsee HTTP server with a `/healthz` proxy layer, merge `ProverApiServer`, `EnclaveApiServer`, and one of the healthz modules, and start the server.
6. Block on the server handle; exit on ctrl-C.
The enclave startup sequence (`NitroEnclave::new`):
1. `Server::new()` opens NSM, derives `tee_image_hash`, and generates the signer key.
2. Bind a `VsockListener` on `VMADDR_CID_ANY:8000`.
3. For each connection, spawn a handler that reads one framed `EnclaveRequest`, dispatches to `Server::prove`, `signer_public_key`, or `signer_attestation`, writes the response, and closes the connection.
Per-request flow on the host:
1. (Optional) `select_valid_enclave` chooses a registered enclave.
2. `tokio::time::timeout(proof_request_timeout, enclave.service.prove_block(request))`.
3. On timeout, return JSON-RPC `-32000` with the offending L2 block number.
4. On error from the enclave, return JSON-RPC `-32000` with the underlying error message.
Shutdown is driven by ctrl-C handled by `RuntimeManager`. The jsonrpsee server stops, in-flight requests drain, and the runtime exits. The enclave has no graceful shutdown path; process termination drops NSM file descriptors via `Drop`.
## Operator inputs
A TEE prover host needs:
- L1 execution RPC URL.
- L1 beacon RPC URL.
- L2 execution RPC URL.
- L2 chain ID (used to select the rollup config and per-chain config hash).
- JSON-RPC listen address.
- One or more vsock CIDs, each backed by a Nitro Enclave running the prover EIF.
- Proof request timeout (default 1740 seconds).
- Logging filter and Prometheus metrics settings.
Optional:
- `TEEProverRegistry` address. Required when more than one vsock CID is configured. Enables registration-gated health and per-request signer validation.
- Experimental witness endpoint flag for hosts that expose `debug_executePayload`.
The enclave needs no operator inputs beyond the EIF image and the vsock channel. PCR0 is read at boot from NSM; the signer key is generated from the hardware RNG.
## Safety requirements
A conforming TEE prover preserves these safety properties:
- Generate the signing key inside the enclave from the NSM hardware RNG and never serialize it out of the enclave process.
- Validate the re-executed final output root against the request's `claimed_l2_output_root` before any signing, and refuse to sign if the check fails.
- Embed `tee_image_hash = keccak256(PCR0)` in every signed journal so signatures bind to one EIF measurement.
- Content-verify every hash-keyed preimage as it enters the enclave so derivation cannot consume preimages whose values disagree with their keys.
- Refuse to prove for chain IDs not present in the hardcoded `CONFIG_HASHES` table.
- Cap `user_data` and `nonce` at the NSM 512-byte limit at the host RPC boundary so oversize attestation requests cannot reach the enclave.
- Serve at most one request per vsock connection and keep no mutable state between requests so a malformed request cannot influence a later one.
- When `--tee-prover-registry-address` is configured, fail closed on per-request signer validity and reject the request if no configured enclave's signer is currently valid onchain.
---
# Transaction Event Journal
Source: https://basehub.org/specifications/transaction-events/
Description: The transaction-event/v1 contract — a shared JSONL business-event journal for Base transaction observability.
The `transaction-event/v1` contract gives Base components a common way to record business-level transaction events. Each producer appends newline-delimited JSON to a dedicated journal file rather than mixing these records into ordinary application output. The usual stdout/stderr path (and its Kubernetes-to-Datadog pipeline) is reserved for logs and must not double as this journal.
A Vector agent follows those JSONL files and forwards each record to `audit-archiver`. Because the audit ingest endpoint is collector-facing, it reads exactly one event object per line and does not accept a wrapped JSON batch.
:::note
The canonical source is [`docs/transaction-events/README.md`](https://github.com/base/base/blob/main/docs/transaction-events/README.md) in the base/base repository.
:::
## Postgres Retention
`audit-archiver` keeps the events it receives in Postgres so operators can query them. That copy is working storage, not the durable archive. Since #5519 the store is `transaction_events_v2`. It is split first by retention class (`hot`, `warm`, `cold`) and then into one partition per UTC day, named `transaction_events_v2_{class}_YYYYMMDD`. Instead of deleting individual rows, a background worker drops a whole day partition once it is older than its class window. The window depends on what kind of event the row holds:
| Default window | Event types |
| --- | --- |
| 3 days | Proxy and builder-decision events, which dominate the journal by volume |
| 7 days | Ingress and forwarding events |
| 30 days | Failures, drops, inclusion, and flashblock events |
Two placements are worth spelling out. `TXPOOL_SEND_RAW_TRANSACTION_VALIDITY` ages out on the same schedule as `TXPOOL_SEND_RAW_TRANSACTION`, so both halves of the admission path leave Postgres together rather than one outliving the other. `BUILDER_DEFERRED` and `BUILDER_EXPIRED` sit with the rest of the per-attempt builder decisions on the shortest window. Builder decisions are still the bulk of the journal. Since #5623, though, a parked transaction no longer writes a fresh deferral on every flashblock, so the volume tracks real decisions more closely.
Because expiry removes whole partitions, it no longer leaves dead tuples or index bloat behind for autovacuum to clean up. A partition is only dropped one hour after it passes its window, so an insert that lands right at the edge cannot race the drop.
Ingest also checks each event's `event_time` before storing it. An event that is already older than its class window is refused, since its partition would be gone anyway. An event stamped one hour or more ahead of the server clock is refused too, because no partition exists for it yet (partitions are created three UTC days ahead). Refusing the single bad record keeps it from failing the rest of the insert batch.
:::caution
The partitioned schema replaces the older migrations `001`–`004`. When `audit-archiver` starts against a database that recorded those migrations, it drops the old `transaction_events` table and resets that migration history in one transaction. Every stored event is discarded. Postgres is the query window, not the archive, so export anything you still need before you upgrade.
:::
The v2 primary key is `(event_hour, retention_class, event_id)`, where `event_hour` is `event_time` cut down to the UTC hour. The old key started with `event_id`, a random hex string, so each insert hit a random page of the whole day's index. Once that index grew past the buffer cache, inserts slowed down. Putting the hour first keeps writes inside the current hour's slice of the key.
The dedupe window is narrower as a result. A re-sent `event_id` dedupes only when its `event_time` falls in the same UTC hour. A copy stamped in a different hour lands as a second row. Before v2 the window was the whole UTC day. `tx_hash` and `block_hash` are now stored only as `0x` plus 64 lowercase hex digits, and a `CHECK` constraint enforces it.
:::caution
Migration `004_drop_legacy_transaction_events.sql` (#5590) drops the old `transaction_events` tree, with its partitions, indexes, and helper functions. This is the second wipe in two weeks: the v2 tree starts empty, and the old rows are gone after `004` runs. Export anything you still need first. Roll out a build that includes #5589 to every instance before `004` runs. An older build reads the legacy tree and fails its readiness check once that tree is gone. The migration waits up to 60 seconds for its locks. If a stray session holds one, the migration fails, and you can just run it again.
:::
## Configuration Fields
Rust producers are expected to surface the following settings, either at the top level or behind a producer-specific prefix:
| Field | Type | Meaning |
| --- | --- | --- |
| `enabled` | boolean | Enables transaction event journal writes. |
| `file_path` | string | Dedicated JSONL file path tailed by Vector. |
| `queue_capacity` | integer | Upper bound on the in-process event queue. Under backpressure a producer discards events rather than stalling its transaction-serving path. |
| `max_file_bytes` | integer | Size ceiling for the live JSONL segment. Once it is crossed, the writer rolls over: the current file is renamed and a fresh segment takes its place. |
| `max_files` | integer | How many JSONL segments are kept on disk at any one time, counting the segment currently being written. |
| `required` | boolean | When true, startup fails if the writer cannot open the file. A failure to write at runtime stays non-fatal and is still surfaced for observability. |
| `producer` | string | One of the producer identities below. |
| `network` | string | Network label, for example `base-mainnet` or `base-sepolia`. |
Go and proxyd builds carry the identical field names in TOML:
```toml
[transaction_events]
enabled = true
file_path = "/var/log/base/transaction-events.jsonl"
queue_capacity = 16384
max_file_bytes = 134217728
max_files = 8
required = false
producer = "base-routing/proxyd"
network = "base-mainnet"
```
## Envelope
Every line is a single JSON object:
```json
{
"schema_version": "transaction-event/v1",
"event_id": "0x7d5c4f...",
"event_time": "2026-06-02T00:00:00.000000000Z",
"producer": "base-reth-node",
"event_type": "TXPOOL_PENDING",
"network": "base-mainnet",
"tx_hash": "0x1111111111111111111111111111111111111111111111111111111111111111",
"block_hash": null,
"block_number": null,
"payload_id": null,
"request_id": null,
"data": {
"pool": "pending"
}
}
```
These fields are mandatory:
- `schema_version`
- `event_id`
- `event_time`
- `producer`
- `event_type`
In normal operation at least one join key should be set — either `tx_hash`, the `block_hash`/`block_number` pair, or `payload_id`. The `request_id` field is not required but helps correlate records across proxies and ingress. Producers should avoid emitting journal records for aggregate operational states that cannot be attributed to one of those join keys: broadcast lag, for instance, stays in logs and metrics because the receiver only sees a skipped count, whereas `INGRESS_METERING_SEND_DROPPED` fires once per dropped transaction precisely because ingress still holds the original `tx_hash`.
Anything producer-specific goes inside `data`. Never journal raw transaction bytes, calldata, full request bodies, API keys, secrets, private keys, bearer tokens, authorization headers, raw forwarding headers, or raw client IP forwarding chains.
A collector sidecar may attach deployment-specific origin metadata under `data.observability_source` before handing events off to `audit-archiver`. The archiver persists that object alongside the rest of `data`, but the shared contract places no schema constraints on it.
On the Rust side, the `TransactionEvent::validate` helper rejects a mismatched schema version, an empty `event_id`, and a short, exact denylist of unsafe `data` keys — among them `raw_tx`, `calldata`, `request_body`, `authorization`, `api_key`, `headers`, and `x-forwarded-for`. Vector collector pipelines are expected to catch wider case and delimiter variants — such as `rawTransaction`, `requestBody`, `secret_key`, and `privateKey` — before anything is ingested.
## Local Devnet Verification
Journaling is split across two devnet layers. The core devnet — `just devnet up` or `just devnet up-single` — switches on durable node journals for `base-client` and `base-builder`, which write their JSONL under `.devnet/transaction-events/`. The tx-observability overlay then layers the collection side on top: a Vector shipper, a local Postgres, the `audit-archiver` ingest path, and the proxyd producer. That overlay never touches the node journal configuration — it only consumes what the core layer already emits.
```bash
just devnet tx-observability
just devnet tx-observability-smoke
```
To exercise proxyd transaction events before that code ships in the default proxyd image, point `BASE_ROUTING_CONTEXT` at a local `protocols/base-routing` checkout:
```bash
BASE_ROUTING_CONTEXT=/path/to/base-routing just devnet tx-observability
just devnet tx-observability-smoke
```
The smoke test pushes a single transaction through proxyd, waits for Vector to deliver the JSONL records from the proxyd, txpool-tracing, and builder producers, and then confirms `audit-archiver` can read the stored events back out of Postgres by transaction hash.
:::caution
This overlay was called `ingress` until 2026-09-21, when the `ingress-rpc` service was deleted from `base/base`. The recipe was renamed rather than aliased, so `just devnet ingress` no longer resolves — along with `tx-observability`, the working recipes are now `tx-observability-down` and `tx-observability-logs`. The compose file moved to `etc/docker/docker-compose.tx-observability.yml`.
:::
To keep an eye on the local shipper, alert on or inspect the `component_discarded_events_total` metric. Two transforms account for what it counts: `parse_transaction_events` sheds malformed JSONL lines, while `validate_transaction_events` discards already-parsed records whose `data` keys are flagged unsafe.
## Producer Values
- `base-reth-node`
- `base-builder`
- `base-routing/proxyd`
- `ingress-rpc` (retired; the value stays defined so archived events remain readable)
Nothing emits `ingress-rpc` any more. The service was removed on 2026-09-21, but its producer value and event types were deliberately left in the vocabulary, because `audit-archiver` rows written before that date still carry them and would otherwise fail to parse. Treat it as a value you may read and must never write.
## Txpool Tracing Example
When `--enable-transaction-event-journal` and `--transaction-event-journal-path` are supplied, `base-reth-node` txpool tracing can route its existing live LRU events into the durable journal:
```json
{"schema_version":"transaction-event/v1","event_id":"0x4d6d...","event_time":"2026-06-02T00:00:00Z","producer":"base-reth-node","event_type":"TXPOOL_PENDING","network":"base-mainnet","tx_hash":"0x1111111111111111111111111111111111111111111111111111111111111111","block_hash":null,"block_number":null,"payload_id":null,"request_id":null,"data":{"event_source":"txpool-tracing","txpool_event":"pending","event_index":0,"node_role":"mempool","pool":"pending"}}
```
## Event Vocabulary
Edge/proxy:
- `PROXY_RECEIVED`
- `PROXY_REJECTED`
- `PROXY_VALIDATION_ACCEPTED`
- `PROXY_VALIDATION_REJECTED`
- `PROXY_ROUTED_TO_BACKEND`
- `PROXY_BACKEND_SUCCESS`
- `PROXY_BACKEND_FAILURE`
- `PROXY_INGRESS_RPC_ATTEMPT` (retired)
- `PROXY_INGRESS_RPC_SUCCESS` (retired)
- `PROXY_INGRESS_RPC_FAILURE` (retired)
Ingress/audit (retired producer; the types are retained so historical events remain readable):
- `INGRESS_RECEIVED`
- `SIMULATION_STARTED`
- `SIMULATION_SUCCEEDED`
- `SIMULATION_FAILED`
- `INGRESS_METERING_SEND_ATTEMPT`
- `INGRESS_METERING_SEND_SUCCESS`
- `INGRESS_METERING_SEND_FAILURE`
- `INGRESS_METERING_SEND_DROPPED`
Mempool/node:
- `TXPOOL_PENDING`
- `TXPOOL_QUEUED`
- `TXPOOL_PENDING_TO_QUEUED`
- `TXPOOL_QUEUED_TO_PENDING`
- `TXPOOL_DROPPED`
- `TXPOOL_REPLACED`
- `TXPOOL_TRACKING_OVERFLOWED`
- `TXPOOL_SEND_RAW_TRANSACTION`
- `TXPOOL_SEND_RAW_TRANSACTION_VALIDITY`
Admission caveat: `TXPOOL_SEND_RAW_TRANSACTION` and `TXPOOL_SEND_RAW_TRANSACTION_VALIDITY` mark entry at the RPC boundary. Each distinct submit path emits its own event exactly once, written after the transaction is decoded but ahead of pool insertion or sequencer forwarding. That places both earlier in the lifecycle than `TXPOOL_PENDING` and `TXPOOL_QUEUED`, which instead report which subpool the transaction landed in. Only `TXPOOL_SEND_RAW_TRANSACTION_VALIDITY` carries `data.validity_predicates` — the serialized list of `balance`, `nonce`, `storage`, `block_number`, and `flashblock_index` entries. Public ingress accepts `balance` again since #5528, which reverted the short-lived rejection from #5463. Producers further down the chain are required not to echo it, and that rule binds `BUILDER_DEFERRED`, `BUILDER_EXPIRED`, `BUILDER_ACCEPTED`, and `BUILDER_INCLUDED` alike, so recover the predicates by joining on `tx_hash`. Treat a replacement as an admission in its own right: it arrives with a separate `tx_hash`, a separate predicate list, or both, and `TXPOOL_REPLACED.replacement_hash` is what ties the departing transaction to the one taking its place. Submissions made through `base_insertValidatedTransaction` are journaled as `TXPOOL_VALIDATED_INSERT_ACCEPTED` / `TXPOOL_VALIDATED_INSERT_REJECTED` instead.
Forwarding:
- `TXPOOL_BUILDER_CONSUMED` (retired)
- `TXPOOL_BUILDER_FORWARD_ATTEMPT`
- `TXPOOL_BUILDER_FORWARD_SUCCESS` (retired)
- `TXPOOL_BUILDER_FORWARD_FAILURE`
- `TXPOOL_BUILDER_FORWARD_DROPPED`
- `TXPOOL_VALIDATED_INSERT_ACCEPTED`
- `TXPOOL_VALIDATED_INSERT_REJECTED`
A mempool node sends every pending transaction to each configured builder. While the transaction stays pending, it sends it again every `--tx-forwarding-resend-after-ms` (default `4000`, about two blocks). The mempool node does not journal the hand-off to a builder. Every destination has its own pool reader and its own queue, so the node writes neither `TXPOOL_BUILDER_CONSUMED` nor `TXPOOL_BUILDER_FORWARD_SUCCESS`. The receiving builder records the outcome instead, as `TXPOOL_VALIDATED_INSERT_ACCEPTED` or `TXPOOL_VALIDATED_INSERT_REJECTED`, with its host in the event ID. Join on those builder events. On the mempool side, a send that fails shows up as `TXPOOL_BUILDER_FORWARD_FAILURE` or `TXPOOL_BUILDER_FORWARD_DROPPED`, and `TXPOOL_BUILDER_FORWARD_ATTEMPT` appears only on RPC retries (`data.attempt` >= 1). Three details are left out of the journal on purpose: when a transaction was queued for each builder, where it sat in the pool iterator, and how many times it was resent. The reader and forwarder metrics show them in aggregate.
:::caution
This model arrived in two steps, so the events you see depend on the node version. `v1.4.2` still writes `TXPOOL_BUILDER_FORWARD_SUCCESS`. #5521 retired that event and made `TXPOOL_BUILDER_CONSUMED` stand in for the first send. #5643 then retired `TXPOOL_BUILDER_CONSUMED` as well. Both changes first ship in `v1.5.0-rc.1`. A query that counts `TXPOOL_BUILDER_CONSUMED` to measure forwarding volume returns zero on `v1.5.0` nodes and gives no error. Move it to the builder's insert events before you upgrade. The event type stays defined so that older rows still decode.
:::
`TXPOOL_BUILDER_FORWARD_DROPPED` is reserved for transaction-scoped drops where the forwarding task still has the `tx_hash` in hand, such as a final RPC failure after the retries are exhausted. Broadcast lag is deliberately kept out of the journal and stays visible only through logs and metrics.
Builder:
- `BUILDER_ACCEPTED`
- `BUILDER_REJECTED`
- `BUILDER_DEFERRED`
- `BUILDER_EXPIRED`
- `BUILDER_INCLUDED`
- `BUILDER_PAYLOAD_FINALIZED`
- `BUILDER_FLASHBLOCK_STARTED`
- `BUILDER_FLASHBLOCK_PUBLISHED`
- `BUILDER_FLASHBLOCK_BUILD_STOPPED`
Builder caveat: `BUILDER_ACCEPTED`, `BUILDER_REJECTED`, `BUILDER_DEFERRED`, and `BUILDER_EXPIRED` fire once per payload-building attempt and, where relevant, carry `payload_id`, `block_number`, and `flashblock_index`. As a result, one transaction can generate several decision events across consecutive flashblocks. Since #5623 neither builder writes `BUILDER_CONSIDERED`. Every candidate already gets one of the decision events above, and that event carries the same budget and position fields. The native builder journals only candidates gated by validity predicates. If such a candidate passes its predicates but is then skipped (block limits, resource metering, coinbase tip, nonce, or EVM validation), it gets `BUILDER_REJECTED`. A parked transaction is parked again on each later flashblock and after each promote-and-repark. But both builders write `BUILDER_DEFERRED` only the first time they defer it within a block build, and again if its `defer_reason` changes. Its `flashblock_index` and `ordering_position` describe that deferral. The native builder tracks this per build attempt, so a pre-Denim rebuild of the same payload reports the deferral again. Re-indexing a transaction that is already parked, because whatever blocks it changed, writes no second `BUILDER_DEFERRED`. Where a deferral says "not yet," `BUILDER_EXPIRED` says "never" — it is the terminal discard the builder writes once a window has closed for good, as when a bundle's validity window or a position predicate has run out and no later attempt can satisfy it. Neither `BUILDER_ACCEPTED` nor `BUILDER_INCLUDED` changed shape, so pairing a deferral with the accept or inclusion that follows means joining on `tx_hash` inside the same `payload_id` and flashblock window. Running out of parking capacity is not a deferral at all — that path still reports `BUILDER_REJECTED` carrying `validity_predicate_not_satisfied`. `BUILDER_INCLUDED` is recorded once the builder finalizes the payload it can serve through `engine_getPayload`, and it sets `data.inclusion_signal = "builder_finalized_payload"`. Nonce and validation skips are recorded by the payload loop as `BUILDER_REJECTED` rather than fabricating replacement relationships. `BUILDER_PAYLOAD_FINALIZED` is written once for every built payload — even an empty one with no user transactions — and ties the `payload_id` to the builder's block hash and number; it includes `data.parent_hash`, `data.transaction_count`, `data.gas_used`, `data.gas_limit`, and `data.timestamp`. `BUILDER_FLASHBLOCK_STARTED`, `BUILDER_FLASHBLOCK_PUBLISHED`, and `BUILDER_FLASHBLOCK_BUILD_STOPPED` are scoped to a payload/flashblock and carry top-level `payload_id` and `block_number` plus `data.parent_hash`, `data.flashblock_index`, and `data.target_flashblock_count`. Published events additionally set top-level `block_hash` and `data.transaction_count`, `data.byte_size`, and `data.build_duration_ms`. Build-stopped events use `data.reason` to label control-flow stops, for example payload resolution winning the race before publish.
Canonicality caveat: builder events describe local payload construction, not canonical-chain or consensus-finality state. A builder event that carries `block_hash` means the builder computed or published that payload shape — it is not, on its own, evidence that the block became canonical. Tie records back to canonical history through canonical-state observers such as txpool tracing by matching `block_hash`, `block_number`, and transaction hashes.
## Event ID Guidance
Prefer deterministic `event_id` values whenever the source has stable inputs. Reasonable components to combine include:
- `producer`
- `event_type`
- source timestamp bucket or source sequence
- `tx_hash`
- `request_id`
- backend/node identifier when applicable
- attempt index when applicable
When a source genuinely cannot produce a deterministic ID, record the reason in the producer implementation and pack enough fields into `data` for `audit-archiver` to enforce uniqueness on the database side.
## proxyd Examples
Received raw transaction request:
```json
{
"schema_version": "transaction-event/v1",
"event_id": "0x1f3f...",
"event_time": "2026-06-02T00:00:00.000000000Z",
"producer": "base-routing/proxyd",
"event_type": "PROXY_RECEIVED",
"network": "base-mainnet",
"tx_hash": "0x2222222222222222222222222222222222222222222222222222222222222222",
"block_hash": null,
"block_number": null,
"payload_id": null,
"request_id": "req-abc",
"data": {
"rpc_method": "eth_sendRawTransaction"
}
}
```
Validation rejection:
```json
{
"schema_version": "transaction-event/v1",
"event_id": "0x2a4b...",
"event_time": "2026-06-02T00:00:00.000000000Z",
"producer": "base-routing/proxyd",
"event_type": "PROXY_VALIDATION_REJECTED",
"network": "base-mainnet",
"tx_hash": "0x2222222222222222222222222222222222222222222222222222222222222222",
"block_hash": null,
"block_number": null,
"payload_id": null,
"request_id": "req-abc",
"data": {
"rpc_method": "eth_sendRawTransaction",
"validation_service": "tx-validation",
"fail_open": false
}
}
```
Routed to node:
```json
{
"schema_version": "transaction-event/v1",
"event_id": "0x3b5c...",
"event_time": "2026-06-02T00:00:00.000000000Z",
"producer": "base-routing/proxyd",
"event_type": "PROXY_ROUTED_TO_BACKEND",
"network": "base-mainnet",
"tx_hash": "0x2222222222222222222222222222222222222222222222222222222222222222",
"block_hash": null,
"block_number": null,
"payload_id": null,
"request_id": "req-abc",
"data": {
"backend": "reth-mainnet-0",
"attempt_index": 0
}
}
```
## Mempool and Builder Examples
These three events trace one validity transaction from admission through to a builder-side discard.
The admission event is the one place the predicate list appears in full. Every park, expiry, accept, and inclusion that follows must be tied back to it through `tx_hash`:
```json
{
"schema_version": "transaction-event/v1",
"event_id": "0x4c6d...",
"event_time": "2026-06-02T00:00:00.000000000Z",
"producer": "base-reth-node",
"event_type": "TXPOOL_SEND_RAW_TRANSACTION_VALIDITY",
"network": "base-mainnet",
"tx_hash": "0x3333333333333333333333333333333333333333333333333333333333333333",
"block_hash": null,
"block_number": null,
"payload_id": null,
"request_id": null,
"data": {
"rpc_method": "base_sendRawTransactionValidity",
"validity_predicates": [
{
"type": "storage",
"params": {
"address": "0xabababababababababababababababababababab",
"slot": "0x1",
"mask": "0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff",
"op": "=",
"value": "0x1"
}
}
]
}
}
```
A recoverable predicate parks the transaction rather than dropping it, holding it for a later ordering position or a later flashblock. Note what is absent — the predicate list is not restated here:
```json
{
"schema_version": "transaction-event/v1",
"event_id": "0x5d7e...",
"event_time": "2026-06-02T00:00:00.200000000Z",
"producer": "base-builder",
"event_type": "BUILDER_DEFERRED",
"network": "base-mainnet",
"tx_hash": "0x3333333333333333333333333333333333333333333333333333333333333333",
"block_hash": null,
"block_number": 123,
"payload_id": "0x0102030405060708",
"request_id": null,
"data": {
"builder_mode": "flashblocks",
"flashblock_index": 2,
"ordering_position": 4,
"defer_reason": "validity_predicate_not_satisfied",
"defer_detail": "a validity predicate is not satisfied by the current build state"
}
}
```
Expiry is the builder's terminal discard, written once no later attempt can satisfy the predicate. Exhausting parking capacity is a different outcome and still surfaces as `BUILDER_REJECTED` with `validity_predicate_not_satisfied`:
```json
{
"schema_version": "transaction-event/v1",
"event_id": "0x6e8f...",
"event_time": "2026-06-02T00:00:00.400000000Z",
"producer": "base-builder",
"event_type": "BUILDER_EXPIRED",
"network": "base-mainnet",
"tx_hash": "0x4444444444444444444444444444444444444444444444444444444444444444",
"block_hash": null,
"block_number": 123,
"payload_id": "0x0102030405060708",
"request_id": null,
"data": {
"builder_mode": "flashblocks",
"flashblock_index": 0,
"ordering_position": 1,
"expire_reason": "validity_predicate_expired",
"expire_detail": "a validity predicate can no longer be satisfied at or after the current build position"
}
}
```
## TIPS S3/Postgres Parity Checklist
The journal feeds the audit-archiver/Postgres query path that backs the TIPS UI. Before an environment flips `TIPS_UI_QUERY_BACKEND=audit`, the Postgres route should return the same answers the existing S3-backed route does. Keep S3 serving traffic until the samples below match against audit-archiver, then cut over.
**Sample inputs.** Pick a representative set and reuse it across both backends:
- A recent block hash that includes at least one non-system transaction, plus that same block addressed by number.
- A transaction hash from that block carrying a `SIMULATION_SUCCEEDED` event.
- A bundle hash or bundle id drawn from that transaction's event data.
- A rejected transaction from the trailing 31 days, if one exists.
**Route comparisons.** Run each sample through both backends and check that they line up:
- On `GET /api/block/`, the two paths should agree on block hash, number, gas limits, the ordering of transactions, and the transaction hashes themselves.
- Addressing the block by number via `GET /api/block/` should land on that same canonical block.
- Per sampled non-system transaction, both backends should concur on whether simulation data is present; where it is, the bundle hash/id, state block number, total gas used, total execution time, and the per-transaction gas/time summaries should all match.
- `GET /api/txn/` should hand back a matching transaction hash along with at least one bundle id/hash join key.
- Events from `GET /api/bundle/` should arrive in event-time order, with the accepted simulation event for the sample among them.
- Where a rejected sample exists, `GET /api/rejected` should echo its transaction hash, block number, rejection reason, timestamp, and metering summary.
**Operational checks:**
- On `audit-archiver`, `TIPS_AUDIT_POSTGRES_URL` is configured, and the audit service port answers both JSON-RPC and transaction-event HTTP ingest — that same port is where Vector delivers NDJSON, at `/v1/transaction-events/batch`.
- On the UI side, `TIPS_UI_QUERY_BACKEND=audit` is set with `TIPS_UI_AUDIT_RPC_URL` aimed at the audit service.
- Writes to S3 keep flowing across the whole comparison window.
- Nothing in the rollout drops a Kafka, S3, or existing RPC persistence path.
---
# ZK Prover
Source: https://basehub.org/specifications/zk-prover/
Description: Offchain service that drives SP1 programs to produce permissionless proofs for AggregateVerifier proposals and disputes.
The ZK prover is an offchain service that takes block-range proof requests, drives SP1 programs to completion, and returns receipts a caller can hand to `AggregateVerifier`. The service persists request state across restarts, submits the underlying work to its configured SP1 backend, and exposes proof status and receipt retrieval over gRPC.
The ZK path is permissionless: any operator with canonical L1 and L2 RPC access, a working SP1 backend, and an L1 transaction signer can both request proofs and submit valid proof material onchain.
## Responsibilities
A conforming ZK prover stack:
1. Accept proving requests for L2 block ranges.
2. Generate witness input from canonical L1, L2, and beacon RPCs.
3. Prove the range program with SP1.
4. For Groth16 requests, aggregate the completed range proof into an onchain-verifiable SNARK.
5. Persist proof request and backend session state so work can recover across process restarts.
6. Expose proof status and receipt retrieval over gRPC.
7. Encode receipts in the format expected by challengers, proposers, and `ZKVerifier`.
The ZK prover never decides whether a game is valid. Proposers and challengers pick the range, recompute canonical roots themselves, and recheck game state before submitting proof material onchain.
## Proving service API
The proving service exposes:
```text
ProveBlock(ProveBlockRequest) -> ProveBlockResponse
GetProof(GetProofRequest) -> GetProofResponse
```
`ProveBlock` enqueues a proof request and returns a `session_id`. `GetProof` returns the current status and, once complete, the requested receipt bytes.
### ProveBlock request
`ProveBlockRequest` carries:
| Field | Meaning |
| --------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `start_block_number` | L2 block whose output root is the trusted starting state for the range. |
| `number_of_blocks_to_prove` | Number of L2 blocks to prove after `start_block_number`. |
| `sequence_window` | Optional L1 block lookahead used when deriving an L1 head for witness generation. |
| `proof_type` | `PROOF_TYPE_COMPRESSED` or `PROOF_TYPE_SNARK_GROTH16`. |
| `session_id` | Optional caller-supplied UUID used for idempotent requests. |
| `prover_address` | L1 address committed into the Groth16 journal so a proof cannot be replayed by another sender. Required for Groth16. |
| `l1_head` | Optional 32-byte hex L1 block hash used for witness generation. |
A caller that supplies the same `session_id` twice receives the existing session in response. Challengers exploit this by deriving the UUID deterministically from `(game address, invalid checkpoint index)` so retries across process restarts are safe.
Pass `l1_head` when the proof journal must match an L1 head already committed onchain — dispute proofs against an existing game, for example. With `l1_head` omitted, the service picks one from the L2 block's L1 origin plus the request or service sequence window, which is the right behavior for fresh proposals where the caller has not yet committed to an L1 head.
For `PROOF_TYPE_SNARK_GROTH16` the `prover_address` is mandatory: the aggregation program embeds it into the journal digest and `AggregateVerifier` re-checks the same digest, so a Groth16 receipt is bound to the L1 sender that requested it.
### Proof types
Two proof types are supported:
| Proof type | Backend sessions | Result |
| ----------------------------- | ---------------- | ---------------------------------------------------------------------- |
| `PROOF_TYPE_COMPRESSED` | `STARK` | A compressed SP1 range proof. |
| `PROOF_TYPE_SNARK_GROTH16` | `STARK`, `SNARK` | A range proof plus a Groth16 aggregation proof suitable for onchain use. |
A `PROOF_TYPE_SNARK_GROTH16` request runs in two stages: the range program is submitted as a compressed STARK session, and once that session lands the aggregation program is submitted as a Groth16 SNARK session.
## Request lifecycle
Each proof request starts in `CREATED` once the request and its outbox entry are durably stored. A worker claims the outbox task and the request moves to `PENDING` while it prepares and submits backend work. The state advances to `RUNNING` as soon as at least one backend session exists. The terminal states are `SUCCEEDED` — every session required by the proof type completed and the receipt bytes are stored — or `FAILED`, set when validation, witness generation, backend submission, backend execution, receipt download, or retry recovery gives up.
Backend sessions advance through `RUNNING`, `COMPLETED`, or `FAILED` independently of the proof request itself. A compressed request lands when its STARK session lands. A Groth16 request lands only after both STARK and SNARK sessions complete. Any failed session fails the parent request.
## Receipt retrieval
`GetProofRequest` carries:
| Field | Meaning |
| -------------- | ----------------------------------------------------------- |
| `session_id` | UUID returned by `ProveBlock`. |
| `receipt_type` | Optional receipt selector. Defaults to `RECEIPT_TYPE_STARK`. |
Receipt selectors:
| Receipt type | Response bytes |
| ----------------------------- | ----------------------------------------------------------------------------------------- |
| `RECEIPT_TYPE_STARK` | Serialized SP1 proof-with-public-values for the range proof. |
| `RECEIPT_TYPE_SNARK` | Serialized SP1 proof-with-public-values for the aggregation proof. |
| `RECEIPT_TYPE_ON_CHAIN_SNARK` | Onchain proof bytes extracted from the stored SNARK receipt for the SP1 Groth16 verifier. |
While a request is `CREATED`, `PENDING`, or `RUNNING`, `GetProof` returns empty receipt bytes. A failed request returns `STATUS_FAILED` and the stored error message. A success always carries non-empty bytes; if the stored request is `Succeeded` but the requested receipt kind is missing, `GetProof` returns gRPC `NOT_FOUND` rather than an empty success.
Wrapping returned receipt bytes in the `AggregateVerifier` proof format is the caller's job. For challenge, nullification, and additional-proof submission the caller prefixes the ZK proof-type byte. For game initialization the caller also adds the L1 origin fields required by `initializeWithInitData()`. See [Proof Contracts](/specifications/contracts) for the verifier-side framing.
## Backend modes
Three backend modes are available:
| Mode | Purpose |
| --------- | ----------------------------------------------------------------------- |
| `mock` | Produces fake receipts for local tests without witness generation. |
| `cluster` | Submits work to a self-hosted SP1 cluster with Redis or S3 artifacts. |
| `network` | Submits work to the SP1 Network with the configured fulfillment policy. |
The `cluster` and `network` backends share the same witness generation; only submission, polling, and artifact retrieval differ. The `mock` backend skips witness generation entirely.
## SP1 range program
The range program proves a Base L2 state transition over a contiguous block range. Its stdin contains:
```text
rkyv(DefaultWitnessData)
intermediateRootInterval
```
The program reconstructs the preimage oracle and beacon blob provider from the witness, runs the Ethereum DA witness executor, and commits a `BootInfoStruct`.
The committed boot info contains:
| Field | Meaning |
| -------------------------- | --------------------------------------------------------------- |
| `l2PreRoot` | Output root for the trusted starting L2 block. |
| `l2PreBlockNumber` | Starting L2 block number. |
| `l2PostRoot` | Output root after executing the requested range. |
| `l2BlockNumber` | Ending L2 block number. |
| `l1Head` | L1 block hash used for derivation data. |
| `rollupConfigHash` | Hash of the rollup configuration used during execution. |
| `intermediateRoots` | Ordered output roots sampled every intermediate-root interval. |
The final intermediate root must correspond to the ending L2 block for the range being proven.
## SP1 aggregation program
The aggregation program collapses completed range proofs into the journal digest used by onchain verification. Inputs:
```text
AggregationInputs (sp1_zkvm::io::read)
L1 headers (CBOR-encoded) (sp1_zkvm::io::read_vec)
compressed range proofs (SP1 proof-input channel)
```
The compressed range proofs travel over SP1's proof-input mechanism rather than plain stdin bytes, and the program verifies them internally with `sp1_lib::verify::verify_sp1_proof`.
`AggregationInputs` bundles the range boot infos, the latest L1 checkpoint head, the range-program verification key, and the prover address.
The aggregation program checks:
1. At least one range boot info is present.
2. Adjacent range boot infos are sequential:
```text
previous.l2PostRoot == next.l2PreRoot
previous.l2BlockNumber == next.l2PreBlockNumber
```
3. Every range uses the same `rollupConfigHash`.
4. Every compressed range proof verifies against the supplied range verification key.
5. The supplied L1 headers form a linked chain ending at `latest_l1_checkpoint_head`.
6. Every range `l1Head` appears in that header chain.
After verification, the program concatenates all intermediate roots and builds one aggregate output:
```text
proverAddress
l1Head
l2PreRoot
startingL2SequenceNumber
l2PostRoot
endingL2SequenceNumber
intermediateRoots
rollupConfigHash
imageHash
```
`imageHash` is the range-program verification key commitment. The aggregation program commits:
```text
keccak256(abi.encodePacked(AggregationOutputs))
```
That digest matches the journal hash `AggregateVerifier` assembles for ZK proof verification. In [Proof Contracts](/specifications/contracts) terminology, `imageHash` is `ZK_RANGE_HASH` and the aggregation verification key configured on `ZKVerifier` is `ZK_AGGREGATE_HASH`.
## ELF reproducibility
SP1 ELF binaries are built on demand rather than committed. The repository pins expected ELF SHA-256 hashes in `crates/proof/succinct/elf/manifest.toml`. Any code change touching either SP1 program must rebuild the ELFs and update `manifest.toml` in the same change.
The range verification key commitment (`ZK_RANGE_HASH`) and aggregation verification key hash (`ZK_AGGREGATE_HASH`) are onchain security parameters. Operators must deploy or configure verifier contracts with values derived from the same ELFs the proving service runs.
## Retry behavior
Transient conditions are retried without changing the logical proof request:
| Condition | Required behavior |
| -------------------------------------------------- | ------------------------------------------------------------------------------ |
| Outbox task already claimed | Skip the duplicate worker. |
| Stuck `PENDING` request without an active session | Reset to `CREATED` with a new outbox entry until the retry limit is exhausted. |
| Backend status polling error | Leave the request `RUNNING` and retry on a later poll. |
| Proof artifact unavailable after backend success | Leave the session `RUNNING` or retry download on a later poll. |
| Backend reports failed or unfulfillable work | Mark the session and proof request `FAILED`. |
| Groth16 stage-two submission fails after STARK | Mark the proof request `FAILED`. |
Callers should treat `FAILED` as terminal for the stored request. If the proof is still wanted, resubmit or retry the same logical request using its deterministic `session_id`.
## Service lifecycle
At startup, the proving service:
1. Connects to Postgres.
2. Optionally starts rate-limited local proxies for L1, L2, and beacon RPCs.
3. Loads rollup configuration from the rollup RPC.
4. Computes the range and aggregation proving and verifying keys.
5. Initializes the configured backend.
6. Starts the outbox processor.
7. Starts the status poller.
8. Starts the gRPC server and reflection service.
The outbox processor converts persisted requests into backend sessions. The status poller keeps running sessions in sync, downloads receipts, triggers Groth16 stage two when needed, and either retries or fails stuck requests.
## Operator inputs
A ZK prover service needs:
- L1 execution RPC endpoint.
- L1 beacon RPC endpoint.
- L2 execution RPC endpoint.
- Rollup RPC endpoint.
- Postgres connection settings.
- SP1 backend configuration.
- Artifact storage configuration for cluster mode.
- Poll intervals, stuck-request timeout, and retry limits.
- Metrics and logging configuration.
Network mode also needs an SP1 Network signer or KMS requester configuration. Cluster mode also needs an SP1 cluster endpoint and exactly one artifact storage backend.
## Onchain expectations
ZK proof bytes are submitted to `AggregateVerifier` with proof type `ZK`. The game assembles the expected journal from proposal or dispute context and calls `ZKVerifier.verify()` with the configured aggregation verification key.
A valid Groth16 receipt proves the aggregation program committed the expected journal digest. It does not substitute for caller-side state checks. Proposers and challengers must still recompute canonical roots and recheck game state before submitting proof material.
## Safety requirements
A conforming ZK prover preserves these safety properties:
- Use the caller-provided `l1_head` when present so dispute proofs match the game context stored onchain.
- Require `prover_address` for Groth16 proofs because the aggregation journal commits it.
- Keep request creation idempotent for deterministic `session_id` values.
- Never return onchain SNARK bytes unless the stored SNARK receipt deserializes successfully.
- Persist backend session metadata before relying on asynchronous backend completion.
- Pin ELF hashes so verification keys and onchain configuration cannot silently drift.
- Treat unavailable RPC data, backend polling failures, and artifact download failures as retryable service conditions, not proof validity results.
---
# Terms of Use
Source: https://basehub.org/terms/
Description: Terms of use for basehub.org, including the analytics and consent terms that apply to everyone who uses the site.
**Effective date:** August 24, 2026
These terms apply to [basehub.org](https://basehub.org) and every page, feed, and
endpoint served from it (the "Site"). By accessing or using the Site, you agree
to these terms. If you do not agree, do not use the Site.
## What BaseHub is
BaseHub is a compendium of open resources about Base, assembled into one site
and built for agents. It is an independent project. It is **not affiliated with,
sponsored by, or endorsed by Coinbase, Base, or any related entity**.
## No warranty and no advice
The Site is provided "as is" and "as available", without warranty of any kind.
Content can be incomplete, out of date, or wrong. Nothing here is financial,
investment, legal, tax, or security advice. Always verify contract addresses,
network parameters, and protocol behavior against primary sources before you act
on them. To the maximum extent the law allows, the maintainer is not liable for
any loss or damage that results from your use of the Site.
## Analytics and your consent
The Site uses **Google Analytics 4** (measurement ID `G-WJLM7HDSFM`), a service
provided by Google LLC. The Site does **not** show a cookie consent banner or a
consent management platform.
**By accessing or using the Site, you consent to all analytics collection,
storage, and processing described in this section.** That consent covers every
Google Analytics storage and processing purpose, and it is set to *granted* for
all of them by default. Specifically, you consent to:
- **`analytics_storage`** — cookies and device identifiers used for analytics.
- **`ad_storage`** — cookies and identifiers used for advertising purposes.
- **`ad_user_data`** — sending your data to Google for advertising purposes.
- **`ad_personalization`** — use of your data for personalized advertising.
- **`functionality_storage`** and **`personalization_storage`** — storage that
supports site function and personalization.
- **`security_storage`** — storage used for security and fraud prevention.
### What is collected
Google Analytics collects, at a minimum:
- Pages and endpoints you request, page titles, and referring URLs.
- Session activity — visit counts, session duration, engagement time, scrolls,
outbound link clicks, file downloads, and site searches.
- Approximate geographic location derived from your IP address.
- Device, browser, operating system, screen size, and language.
- A pseudonymous client identifier stored in first-party cookies (`_ga` and
`_ga_*`) and in similar browser storage, which persists across visits.
- Any additional signals Google enables for the property, including Google
Signals, cross-device and demographic reporting, and audience data derived
from your activity.
This data is transmitted to Google and processed on Google infrastructure,
including servers in the United States and other countries. Google may use it as
described in the [Google Privacy Policy](https://policies.google.com/privacy) and
[How Google uses information from sites that use our services](https://policies.google.com/technologies/partner-sites).
You consent to that transfer and processing.
### What is not collected
The Site has no accounts, no login, no comments, and no payment or contact
forms. It does not ask you for a name, an email address, or a wallet address,
and it does not sell your data.
### Your choices
If you do not want this collection, you must not use the Site. You can also:
- Block or delete cookies and site data for `basehub.org` in your browser.
- Install the
[Google Analytics opt-out browser add-on](https://tools.google.com/dlpage/gaoptout).
- Use a browser, extension, or network filter that blocks analytics requests.
- Adjust personalization at [Google Ad Settings](https://adssettings.google.com).
The Site does not respond to Do Not Track or Global Privacy Control signals.
## Acceptable use
You can read, copy, and quote Site content, including the raw Markdown, JSON,
and text endpoints, for any lawful purpose. Automated access is expected and
welcome — that is what the Site is built for. Do not use the Site to break the
law, to attack the Site or its hosting, or to interfere with anyone else's use of
it.
## Content and licensing
BaseHub source and content are published under the
[MIT License](https://github.com/wbnns/basehub/blob/main/LICENSE). Material
gathered from upstream sources stays subject to its own license and terms.
Trademarks and logos belong to their owners.
## External links
The Site links to third-party sites, tools, and providers. Those links are not
endorsements. The maintainer does not control third-party sites and is not
responsible for their content, terms, or privacy practices.
## Changes to these terms
These terms can change at any time. The effective date above shows the most
recent revision. Continued use of the Site after a change means you accept the
revised terms.
## Contact
Reach out to [@wbnns on X](https://x.com/wbnns).
---