From 1d60dfe0ccb59524800ccbf5cb6d0d5c47ab9d60 Mon Sep 17 00:00:00 2001 From: josh crites Date: Fri, 17 Apr 2026 13:44:43 +0000 Subject: [PATCH 1/3] cherry-pick: fix(docs): restore operator changelog v4.md and add v4.2 to sidebar (with conflicts) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Cherry-pick of #22609 (merge commit cbb09bcc85) onto v4-next. Applied with -m 1 -Xno-renames. Conflicts + git rename-detection misfires to resolve in next commit: - version-v2.1.11-ignition/reference/changelog/v4.md: conflict (git mapped the v4.2.0/reference/changelog/v4.md patch here because version-v4.2.0/ does not exist on v4-next) - version-v2.1.11-ignition-sidebars.json: auto-merged from version-v4.2.0-sidebars.json — not a real target - version-v4.1.2/operators/reference/changelog/index.md: auto-merged from v4.2.0 — v4.2 does not yet have a versioned folder here - version-v4.1.2/operators/reference/changelog/v4.md: auto-merged link fix from v4.2.0 — v4.1.2 already points at the correct path Legitimate portions: docs-operate/reference/changelog/v4.md restore, docs-operate/operators/reference/changelog/index.md v4.2 entry, sidebars-operate.js v4.2 entry. --- .../operators/reference/changelog/index.md | 13 + docs/docs-operate/reference/changelog/v4.md | 324 ++++++++++++++--- .../reference/changelog/v4.md | 329 ++++++++++++++++-- .../operators/reference/changelog/index.md | 13 + .../operators/reference/changelog/v4.md | 2 +- .../version-v2.1.11-ignition-sidebars.json | 1 + docs/sidebars-operate.js | 1 + 7 files changed, 605 insertions(+), 78 deletions(-) diff --git a/docs/docs-operate/operators/reference/changelog/index.md b/docs/docs-operate/operators/reference/changelog/index.md index 8ac918dbd583..0cf9b04f4ecd 100644 --- a/docs/docs-operate/operators/reference/changelog/index.md +++ b/docs/docs-operate/operators/reference/changelog/index.md @@ -11,6 +11,19 @@ This changelog documents all configuration changes, new features, and breaking c ## Version history +### [v4.2.0](./v4.2.md) + +New features and configuration options for node operators. + +**Key changes:** +- Blob retrieval improvements with unified retry loop + +**Migration difficulty**: Low + +[View full changelog →](./v4.2.md) + +--- + ### [v4.x (Upgrade from Ignition)](./v4.md) Major upgrade from Ignition (v2.x) to Alpha (v4.x) with significant architectural changes. diff --git a/docs/docs-operate/reference/changelog/v4.md b/docs/docs-operate/reference/changelog/v4.md index adba87dd0bcc..a7f3b5a9179e 100644 --- a/docs/docs-operate/reference/changelog/v4.md +++ b/docs/docs-operate/reference/changelog/v4.md @@ -1,85 +1,325 @@ --- -title: v4.0.0 (from v3.0.0) -description: TODO +title: v4.x (Upgrade from Ignition) +description: Breaking changes and migration guide for upgrading from Ignition (v2.x) to Alpha (v4.x). --- ## Overview -**Migration difficulty**: TODO +**Migration difficulty**: High ## Breaking changes -### StakingAssetHandler refactored to simple token faucet +### Node.js upgraded to v24 -The `StakingAssetHandler` L1 contract has been significantly simplified. It no longer handles validator registration directly - instead it functions as a simple STK token faucet with ZKPassport sybil resistance. +Node.js minimum version changed from v22 to v24.12.0. -**v3.0.0:** -```solidity -// Single call registered validator -stakingAssetHandler.addValidator(attester, merkleProof, zkPassportParams, publicKeyG1, publicKeyG2, signature); +### Bot fee padding configuration renamed + +The bot configuration for fee padding has been renamed from "base fee" to "min fee". + +**v3.x:** + +```bash +--bot.baseFeePadding ($BOT_BASE_FEE_PADDING) +``` + +**v4.0.0:** + +```bash +--bot.minFeePadding ($BOT_MIN_FEE_PADDING) +``` + +**Migration**: Update your configuration to use the new flag name and environment variable. + +### L2Tips API restructured with checkpoint information + +The `getL2Tips()` RPC endpoint now returns a restructured response with additional checkpoint tracking. + +**v3.x response:** + +```json +{ + "latest": { "number": 100, "hash": "0x..." }, + "proven": { "number": 98, "hash": "0x..." }, + "finalized": { "number": 95, "hash": "0x..." } +} +``` + +**v4.0.0 response:** + +```json +{ + "proposed": { "number": 100, "hash": "0x..." }, + "checkpointed": { + "block": { "number": 99, "hash": "0x..." }, + "checkpoint": { "number": 10, "hash": "0x..." } + }, + "proven": { + "block": { "number": 98, "hash": "0x..." }, + "checkpoint": { "number": 9, "hash": "0x..." } + }, + "finalized": { + "block": { "number": 95, "hash": "0x..." }, + "checkpoint": { "number": 8, "hash": "0x..." } + } +} +``` + +**Migration**: + +- Replace `tips.latest` with `tips.proposed` +- For `checkpointed`, `proven`, and `finalized` tips, access block info via `.block` (e.g., `tips.proven.block.number`) + +### Block gas limits reworked + +The byte-based block size limit has been removed and replaced with field-based blob limits and automatic gas budget computation from L1 rollup limits. + +**Removed:** + +```bash +--maxBlockSizeInBytes ($SEQ_MAX_BLOCK_SIZE_IN_BYTES) +``` + +**Changed to optional (now auto-computed from L1 if not set):** + +```bash +--maxL2BlockGas ($SEQ_MAX_L2_BLOCK_GAS) +--maxDABlockGas ($SEQ_MAX_DA_BLOCK_GAS) ``` +**New (proposer):** + +```bash +--perBlockAllocationMultiplier ($SEQ_PER_BLOCK_ALLOCATION_MULTIPLIER) +--maxTxsPerCheckpoint ($SEQ_MAX_TX_PER_CHECKPOINT) +``` + +**New (validator):** + +```bash +--validateMaxL2BlockGas ($VALIDATOR_MAX_L2_BLOCK_GAS) +--validateMaxDABlockGas ($VALIDATOR_MAX_DA_BLOCK_GAS) +--validateMaxTxsPerBlock ($VALIDATOR_MAX_TX_PER_BLOCK) +--validateMaxTxsPerCheckpoint ($VALIDATOR_MAX_TX_PER_CHECKPOINT) +``` + +**Migration**: Remove `SEQ_MAX_BLOCK_SIZE_IN_BYTES` from your configuration. Per-block L2 and DA gas budgets are now derived automatically as `(checkpointLimit / maxBlocks) * multiplier`, where the multiplier defaults to 2. You can still override `SEQ_MAX_L2_BLOCK_GAS` and `SEQ_MAX_DA_BLOCK_GAS` explicitly, but they will be capped at the checkpoint-level limits. Validators can now set independent per-block and per-checkpoint limits via the `VALIDATOR_` env vars; when not set, only checkpoint-level protocol limits are enforced. + +### Setup phase allow list requires function selectors + +The transaction setup phase allow list now enforces function selectors, restricting which specific functions can run during setup on whitelisted contracts. Previously, any public function on a whitelisted contract or class was permitted. + +The semantics of the environment variable `TX_PUBLIC_SETUP_ALLOWLIST` have changed: + +**v3.x:** + +```bash +--txPublicSetupAllowList ($TX_PUBLIC_SETUP_ALLOWLIST) +``` + +The variable fully **replaced** the hardcoded defaults. Format allowed entries without selectors: `I:address`, `C:classId`. + **v4.0.0:** -```solidity -// Step 1: Claim STK tokens from faucet -stakingAssetHandler.claim(zkPassportParams); -// Step 2: Approve rollup to spend tokens -stakingAsset.approve(rollupAddress, amount); +```bash +--txPublicSetupAllowListExtend ($TX_PUBLIC_SETUP_ALLOWLIST) +``` + +The variable now **extends** the hardcoded defaults (which are always present). Selectors are now mandatory. An optional flags segment can be appended for additional validation: + +``` +I:address:selector[:flags] +C:classId:selector[:flags] +``` + +Where `flags` is a `+`-separated list of: +- `os` — `onlySelf`: only allow calls where msg_sender == contract address +- `rn` — `rejectNullMsgSender`: reject calls with a null msg_sender +- `cl=N` — `calldataLength`: enforce exact calldata length of N fields + +Example: `C:0xabc:0x1234:os+cl=4` + +**Migration**: If you were using `TX_PUBLIC_SETUP_ALLOWLIST`, ensure all entries include function selectors. Note the variable now adds to defaults rather than replacing them. If you were not setting this variable, no action is needed — the hardcoded defaults now include the correct selectors automatically. + +### Token removed from default setup allowlist + +Token class-based entries (`_increase_public_balance` and `transfer_in_public`) have been removed from the default public setup allowlist. FPC-based fee payments using custom tokens no longer work out of the box. + +This change was made because Token class IDs change with aztec-nr releases, making the allowlist impossible to keep up to date with new library releases. In addition, `transfer_in_public` requires complex additional logic to be built into the node to prevent mass transaction invalidation attacks. **FPC-based fee payment with custom tokens won't work on mainnet alpha**. + +**Migration**: Node operators who need FPC support must manually add Token entries via `TX_PUBLIC_SETUP_ALLOWLIST`. Example: -// Step 3: Deposit into rollup (user chooses their own withdrawer) -rollup.deposit(attester, withdrawer, publicKeyG1, publicKeyG2, signature, moveWithLatestRollup); +```bash +TX_PUBLIC_SETUP_ALLOWLIST="C:::os+cl=3,C:::cl=5" +``` + +Replace `` with the deployed Token contract class ID and ``/`` with the respective function selectors. Keep in mind that this will only work on local network setups, since even if you as an operator add these entries, other nodes will not have them and will not pick up these transactions. + +### Sequencer environment variable renames + +Several sequencer environment variables have been renamed: + +| Old variable | New variable | +|---|---| +| `SEQ_TX_POLLING_INTERVAL_MS` | `SEQ_POLLING_INTERVAL_MS` | +| `SEQ_MAX_L1_TX_INCLUSION_TIME_INTO_SLOT` | `SEQ_L1_PUBLISHING_TIME_ALLOWANCE_IN_SLOT` | +| `SEQ_MAX_TX_PER_BLOCK` | `SEQ_MAX_TX_PER_CHECKPOINT` | +| `SEQ_MAX_BLOCK_SIZE_IN_BYTES` | Removed (see [Block gas limits reworked](#block-gas-limits-reworked)) | + +**Migration**: Search your configuration for the old variable names and replace them. The node will not recognize the old names. + +### Double signing slashing + +New slashable offenses have been introduced for duplicate proposals and duplicate attestations. Penalty amounts are currently set to 0, but the detection infrastructure is active. + +If you run redundant sequencer nodes, you **must** enable high-availability signing with PostgreSQL to prevent accidental double signing: + +```bash +VALIDATOR_HA_SIGNING_ENABLED=true +VALIDATOR_HA_DATABASE_URL=postgresql://:@:/ +VALIDATOR_HA_NODE_ID= +``` + +Run the database migration before starting your nodes: + +```bash +aztec migrate-ha-db up --database-url ``` -**Removed functions:** -- `addValidator()` - replaced by `claim()` + direct rollup deposit -- `reenterExitedValidator()` -- `setValidatorsToFlush()`, `setMintInterval()`, `setDepositsPerMint()`, `setWithdrawer()` -- `setSkipMerkleCheck()`, `setDepositMerkleRoot()` +**Migration**: If you run a single node, no action is required. If you run redundant nodes for high availability, configure HA signing immediately. See the [High Availability Sequencers](../../operators/setup/high-availability.md) guide for details. + +### Blob-only data publication + +Transaction data is now published entirely via EIP-4844 blobs. The calldata fallback has been removed. + +Your consensus client (e.g., Lighthouse, Prysm) must run as a **supernode** or **semi-supernode** to make blobs available for retrieval. Standard pruning configurations will not retain blobs long enough. -**New functions:** -- `claim(ProofVerificationParams)` - claim STK tokens with ZKPassport proof -- `setFaucetAmount(uint256)` - owner sets claim amount -- `resetNullifier(bytes32)` - owner can reset a nullifier +You should also configure blob file stores for redundancy: -**CLI changes:** ```bash -# v3.0.0 -aztec add-l1-validator --merkle-proof +BLOB_FILE_STORE_URLS= +BLOB_FILE_STORE_UPLOAD_URL= +BLOB_ARCHIVE_API_URL= +``` + +**Migration**: Ensure your consensus client is configured as a supernode. If you previously relied on calldata for data availability, switch to blob-based retrieval. See the [Blob Storage](../../operators/setup/blob_storage) guide for configuration details. + +### Withdrawal delay increase + +The governance execution delay has increased from 7 days to 30 days. This extends the time required for staker withdrawals from approximately 15 days to approximately 38 days. -# v4.0.0 -aztec add-l1-validator --withdrawer-address
+**Migration**: No configuration changes needed. Be aware that withdrawal processing will take longer after the upgrade. + +### Prover architecture change + +The prover now runs as a node subsystem rather than a separate standalone process. Start it alongside your node using the `--prover-node` flag: + +```bash +aztec start --node --prover-node ``` -**Migration**: Users must now call `claim()` to get STK tokens, then deposit into the rollup themselves. The `--merkle-proof` CLI flag is removed; add `--withdrawer-address` instead. +**Migration**: If you were running the prover as a separate process, update your deployment to run it as part of the node with `--prover-node`. ## Removed features ## New features -### P2P clock tolerance for slot validation +### Initial ETH per fee asset configuration + +A new environment variable `AZTEC_INITIAL_ETH_PER_FEE_ASSET` has been added to configure the initial exchange rate between ETH and the fee asset (AZTEC) at contract deployment. This value uses 1e12 precision. + +**Default**: `10000000` (0.00001 ETH per AZTEC) + +**Configuration:** -Added a 500ms tolerance window for P2P messages from the previous slot, following Ethereum's `MAXIMUM_GOSSIP_CLOCK_DISPARITY` approach. This prevents peers from being penalized for valid messages that arrive slightly after the slot boundary due to network latency. +```bash +--initialEthPerFeeAsset ($AZTEC_INITIAL_ETH_PER_FEE_ASSET) +``` + +This replaces the previous hardcoded default and allows network operators to set the starting price point for the fee asset. + +### `reloadKeystore` admin RPC endpoint + +Node operators can now update validator attester keys, coinbase, and fee recipient without restarting the node by calling the new `reloadKeystore` admin RPC endpoint. + +What is updated on reload: + +- Validator attester keys (add, remove, or replace) +- Coinbase and fee recipient per validator +- Publisher-to-validator mapping + +What is NOT updated (requires restart): -The tolerance is hardcoded at 500ms (matching Ethereum's current value) and can be made configurable via environment variables in the future if needed. +- L1 publisher signers +- Prover keys +- HA signer connections -**Impact**: Improved network stability with no action required from node operators. +New validators must use a publisher key already initialized at startup. Reload is rejected with a clear error if validation fails. -### Transaction collection config renamed +### Admin API key authentication -The environment variable for selecting the missing transactions collector implementation has been renamed: +The admin JSON-RPC endpoint now supports auto-generated API key authentication. + +**Behavior:** + +- A cryptographically secure API key is auto-generated at first startup and displayed once via stdout +- Only the SHA-256 hash is persisted to `/admin/api_key_hash` +- The key is reused across restarts when `--data-directory` is set +- Supports both `x-api-key` and `Authorization: Bearer ` headers +- Health check endpoint (`GET /status`) is excluded from auth (for k8s probes) + +**Configuration:** -**v3.0.0:** ```bash ---tx-collection-proposal-tx-collector-type ($TX_COLLECTION_PROPOSAL_TX_COLLECTOR_TYPE) +--admin-api-key-hash ($AZTEC_ADMIN_API_KEY_HASH) # Use a pre-generated SHA-256 key hash +--disable-admin-api-key ($AZTEC_DISABLE_ADMIN_API_KEY) # Disable auth entirely +--reset-admin-api-key ($AZTEC_RESET_ADMIN_API_KEY) # Force key regeneration ``` -**v4.0.0:** +**Helm charts**: Admin API key auth is disabled by default (`disableAdminApiKey: true`). Set to `false` in production values to enable. + +**Migration**: No action required — auth is opt-out. To enable, ensure `--disable-admin-api-key` is not set and note the key printed at startup. + +### Transaction pool error codes for RPC callers + +Transaction submission via RPC now returns structured rejection codes when a transaction is rejected by the mempool: + +- `LOW_PRIORITY_FEE` — tx priority fee is too low +- `INSUFFICIENT_FEE_PAYER_BALANCE` — fee payer doesn't have enough balance +- `NULLIFIER_CONFLICT` — conflicting nullifier already in pool + +**Impact**: Improved developer experience — callers can now programmatically handle specific rejection reasons. + +### RPC transaction replacement price bump + +Transactions submitted via RPC that clash on nullifiers with existing pool transactions must now pay at least X% more in priority fee to replace them. The same bump applies when the pool is full and the incoming tx needs to evict the lowest-priority tx. P2P gossip behavior is unchanged. + +**Configuration:** + ```bash ---tx-collection-missing-txs-collector-type ($TX_COLLECTION_MISSING_TXS_COLLECTOR_TYPE) +P2P_RPC_PRICE_BUMP_PERCENTAGE=10 # default: 10 (percent) ``` -**Migration**: Update your configuration to use the new environment variable name. The default value (`new`) remains unchanged. +Set to `0` to disable the percentage-based bump (still requires strictly higher fee). + +### Validator-specific block limits + +Validators can now enforce per-block and per-checkpoint limits independently from the sequencer (proposer) limits. This allows operators to accept proposals that exceed their own proposer settings, or to reject proposals that are too large even if the proposer's limits allow them. + +**Configuration:** + +```bash +VALIDATOR_MAX_L2_BLOCK_GAS= # Max L2 gas per block for validation +VALIDATOR_MAX_DA_BLOCK_GAS= # Max DA gas per block for validation +VALIDATOR_MAX_TX_PER_BLOCK= # Max txs per block for validation +VALIDATOR_MAX_TX_PER_CHECKPOINT= # Max txs per checkpoint for validation +``` + +When not set, no per-block limit is enforced for that dimension — only checkpoint-level protocol limits apply. These do not fall back to the `SEQ_` values. + +### Setup allow list extendable via network config + +The setup phase allow list can now be extended via the network configuration JSON (`txPublicSetupAllowListExtend` field). This allows network operators to distribute additional allowed setup functions to all nodes without requiring code changes. The local environment variable takes precedence over the network-json value. ## Changed defaults diff --git a/docs/network_versioned_docs/version-v2.1.11-ignition/reference/changelog/v4.md b/docs/network_versioned_docs/version-v2.1.11-ignition/reference/changelog/v4.md index 6f4abb6a79ae..4ae76c5a5906 100644 --- a/docs/network_versioned_docs/version-v2.1.11-ignition/reference/changelog/v4.md +++ b/docs/network_versioned_docs/version-v2.1.11-ignition/reference/changelog/v4.md @@ -1,70 +1,329 @@ --- -title: v4.0.0 (from v3.0.0) -description: TODO +title: v4.x (Upgrade from Ignition) +description: Breaking changes and migration guide for upgrading from Ignition (v2.x) to Alpha (v4.x). --- ## Overview -**Migration difficulty**: TODO +**Migration difficulty**: High ## Breaking changes -### StakingAssetHandler refactored to simple token faucet +### Node.js upgraded to v24 -The `StakingAssetHandler` L1 contract has been significantly simplified. It no longer handles validator registration directly - instead it functions as a simple STK token faucet with ZKPassport sybil resistance. +Node.js minimum version changed from v22 to v24.12.0. -**v3.0.0:** -```solidity -// Single call registered validator -stakingAssetHandler.addValidator(attester, merkleProof, zkPassportParams, publicKeyG1, publicKeyG2, signature); +### Bot fee padding configuration renamed + +The bot configuration for fee padding has been renamed from "base fee" to "min fee". + +**v3.x:** + +```bash +--bot.baseFeePadding ($BOT_BASE_FEE_PADDING) +``` + +**v4.0.0:** + +```bash +--bot.minFeePadding ($BOT_MIN_FEE_PADDING) +``` + +**Migration**: Update your configuration to use the new flag name and environment variable. + +### L2Tips API restructured with checkpoint information + +The `getL2Tips()` RPC endpoint now returns a restructured response with additional checkpoint tracking. + +**v3.x response:** + +```json +{ + "latest": { "number": 100, "hash": "0x..." }, + "proven": { "number": 98, "hash": "0x..." }, + "finalized": { "number": 95, "hash": "0x..." } +} +``` + +**v4.0.0 response:** + +```json +{ + "proposed": { "number": 100, "hash": "0x..." }, + "checkpointed": { + "block": { "number": 99, "hash": "0x..." }, + "checkpoint": { "number": 10, "hash": "0x..." } + }, + "proven": { + "block": { "number": 98, "hash": "0x..." }, + "checkpoint": { "number": 9, "hash": "0x..." } + }, + "finalized": { + "block": { "number": 95, "hash": "0x..." }, + "checkpoint": { "number": 8, "hash": "0x..." } + } +} +``` + +**Migration**: + +- Replace `tips.latest` with `tips.proposed` +- For `checkpointed`, `proven`, and `finalized` tips, access block info via `.block` (e.g., `tips.proven.block.number`) + +### Block gas limits reworked + +The byte-based block size limit has been removed and replaced with field-based blob limits and automatic gas budget computation from L1 rollup limits. + +**Removed:** + +```bash +--maxBlockSizeInBytes ($SEQ_MAX_BLOCK_SIZE_IN_BYTES) +``` + +**Changed to optional (now auto-computed from L1 if not set):** + +```bash +--maxL2BlockGas ($SEQ_MAX_L2_BLOCK_GAS) +--maxDABlockGas ($SEQ_MAX_DA_BLOCK_GAS) +``` + +**New (proposer):** + +```bash +--perBlockAllocationMultiplier ($SEQ_PER_BLOCK_ALLOCATION_MULTIPLIER) +--maxTxsPerCheckpoint ($SEQ_MAX_TX_PER_CHECKPOINT) +``` + +**New (validator):** + +```bash +--validateMaxL2BlockGas ($VALIDATOR_MAX_L2_BLOCK_GAS) +--validateMaxDABlockGas ($VALIDATOR_MAX_DA_BLOCK_GAS) +--validateMaxTxsPerBlock ($VALIDATOR_MAX_TX_PER_BLOCK) +--validateMaxTxsPerCheckpoint ($VALIDATOR_MAX_TX_PER_CHECKPOINT) +``` + +**Migration**: Remove `SEQ_MAX_BLOCK_SIZE_IN_BYTES` from your configuration. Per-block L2 and DA gas budgets are now derived automatically as `(checkpointLimit / maxBlocks) * multiplier`, where the multiplier defaults to 2. You can still override `SEQ_MAX_L2_BLOCK_GAS` and `SEQ_MAX_DA_BLOCK_GAS` explicitly, but they will be capped at the checkpoint-level limits. Validators can now set independent per-block and per-checkpoint limits via the `VALIDATOR_` env vars; when not set, only checkpoint-level protocol limits are enforced. + +### Setup phase allow list requires function selectors + +The transaction setup phase allow list now enforces function selectors, restricting which specific functions can run during setup on whitelisted contracts. Previously, any public function on a whitelisted contract or class was permitted. + +The semantics of the environment variable `TX_PUBLIC_SETUP_ALLOWLIST` have changed: + +**v3.x:** + +```bash +--txPublicSetupAllowList ($TX_PUBLIC_SETUP_ALLOWLIST) ``` +The variable fully **replaced** the hardcoded defaults. Format allowed entries without selectors: `I:address`, `C:classId`. + **v4.0.0:** -```solidity -// Step 1: Claim STK tokens from faucet -stakingAssetHandler.claim(zkPassportParams); -// Step 2: Approve rollup to spend tokens -stakingAsset.approve(rollupAddress, amount); +```bash +--txPublicSetupAllowListExtend ($TX_PUBLIC_SETUP_ALLOWLIST) +``` + +The variable now **extends** the hardcoded defaults (which are always present). Selectors are now mandatory. An optional flags segment can be appended for additional validation: + +``` +I:address:selector[:flags] +C:classId:selector[:flags] +``` + +Where `flags` is a `+`-separated list of: +- `os` — `onlySelf`: only allow calls where msg_sender == contract address +- `rn` — `rejectNullMsgSender`: reject calls with a null msg_sender +- `cl=N` — `calldataLength`: enforce exact calldata length of N fields + +Example: `C:0xabc:0x1234:os+cl=4` + +**Migration**: If you were using `TX_PUBLIC_SETUP_ALLOWLIST`, ensure all entries include function selectors. Note the variable now adds to defaults rather than replacing them. If you were not setting this variable, no action is needed — the hardcoded defaults now include the correct selectors automatically. + +### Token removed from default setup allowlist + +Token class-based entries (`_increase_public_balance` and `transfer_in_public`) have been removed from the default public setup allowlist. FPC-based fee payments using custom tokens no longer work out of the box. + +This change was made because Token class IDs change with aztec-nr releases, making the allowlist impossible to keep up to date with new library releases. In addition, `transfer_in_public` requires complex additional logic to be built into the node to prevent mass transaction invalidation attacks. **FPC-based fee payment with custom tokens won't work on mainnet alpha**. + +**Migration**: Node operators who need FPC support must manually add Token entries via `TX_PUBLIC_SETUP_ALLOWLIST`. Example: + +```bash +TX_PUBLIC_SETUP_ALLOWLIST="C:::os+cl=3,C:::cl=5" +``` + +Replace `` with the deployed Token contract class ID and ``/`` with the respective function selectors. Keep in mind that this will only work on local network setups, since even if you as an operator add these entries, other nodes will not have them and will not pick up these transactions. -// Step 3: Deposit into rollup (user chooses their own withdrawer) -rollup.deposit(attester, withdrawer, publicKeyG1, publicKeyG2, signature, moveWithLatestRollup); +### Sequencer environment variable renames + +Several sequencer environment variables have been renamed: + +| Old variable | New variable | +|---|---| +| `SEQ_TX_POLLING_INTERVAL_MS` | `SEQ_POLLING_INTERVAL_MS` | +| `SEQ_MAX_L1_TX_INCLUSION_TIME_INTO_SLOT` | `SEQ_L1_PUBLISHING_TIME_ALLOWANCE_IN_SLOT` | +| `SEQ_MAX_TX_PER_BLOCK` | `SEQ_MAX_TX_PER_CHECKPOINT` | +| `SEQ_MAX_BLOCK_SIZE_IN_BYTES` | Removed (see [Block gas limits reworked](#block-gas-limits-reworked)) | + +**Migration**: Search your configuration for the old variable names and replace them. The node will not recognize the old names. + +### Double signing slashing + +New slashable offenses have been introduced for duplicate proposals and duplicate attestations. Penalty amounts are currently set to 0, but the detection infrastructure is active. + +If you run redundant sequencer nodes, you **must** enable high-availability signing with PostgreSQL to prevent accidental double signing: + +```bash +VALIDATOR_HA_SIGNING_ENABLED=true +VALIDATOR_HA_DATABASE_URL=postgresql://:@:/ +VALIDATOR_HA_NODE_ID= ``` -**Removed functions:** -- `addValidator()` - replaced by `claim()` + direct rollup deposit -- `reenterExitedValidator()` -- `setValidatorsToFlush()`, `setMintInterval()`, `setDepositsPerMint()`, `setWithdrawer()` -- `setSkipMerkleCheck()`, `setDepositMerkleRoot()` +Run the database migration before starting your nodes: -**New functions:** -- `claim(ProofVerificationParams)` - claim STK tokens with ZKPassport proof -- `setFaucetAmount(uint256)` - owner sets claim amount -- `resetNullifier(bytes32)` - owner can reset a nullifier +```bash +aztec migrate-ha-db up --database-url +``` + +**Migration**: If you run a single node, no action is required. If you run redundant nodes for high availability, configure HA signing immediately. See the [High Availability Sequencers](../../operators/setup/high-availability.md) guide for details. + +### Blob-only data publication + +Transaction data is now published entirely via EIP-4844 blobs. The calldata fallback has been removed. + +Your consensus client (e.g., Lighthouse, Prysm) must run as a **supernode** or **semi-supernode** to make blobs available for retrieval. Standard pruning configurations will not retain blobs long enough. + +You should also configure blob file stores for redundancy: -**CLI changes:** ```bash -# v3.0.0 -aztec add-l1-validator --merkle-proof +BLOB_FILE_STORE_URLS= +BLOB_FILE_STORE_UPLOAD_URL= +BLOB_ARCHIVE_API_URL= +``` -# v4.0.0 -aztec add-l1-validator --withdrawer-address
+**Migration**: Ensure your consensus client is configured as a supernode. If you previously relied on calldata for data availability, switch to blob-based retrieval. See the [Blob Storage](../../operators/setup/blob_storage) guide for configuration details. + +### Withdrawal delay increase + +The governance execution delay has increased from 7 days to 30 days. This extends the time required for staker withdrawals from approximately 15 days to approximately 38 days. + +**Migration**: No configuration changes needed. Be aware that withdrawal processing will take longer after the upgrade. + +### Prover architecture change + +The prover now runs as a node subsystem rather than a separate standalone process. Start it alongside your node using the `--prover-node` flag: + +```bash +aztec start --node --prover-node ``` -**Migration**: Users must now call `claim()` to get STK tokens, then deposit into the rollup themselves. The `--merkle-proof` CLI flag is removed; add `--withdrawer-address` instead. +**Migration**: If you were running the prover as a separate process, update your deployment to run it as part of the node with `--prover-node`. ## Removed features ## New features -### P2P clock tolerance for slot validation +### Initial ETH per fee asset configuration + +A new environment variable `AZTEC_INITIAL_ETH_PER_FEE_ASSET` has been added to configure the initial exchange rate between ETH and the fee asset (AZTEC) at contract deployment. This value uses 1e12 precision. + +**Default**: `10000000` (0.00001 ETH per AZTEC) + +**Configuration:** + +<<<<<<< HEAD:docs/network_versioned_docs/version-v2.1.11-ignition/reference/changelog/v4.md +======= +```bash +--initialEthPerFeeAsset ($AZTEC_INITIAL_ETH_PER_FEE_ASSET) +``` + +This replaces the previous hardcoded default and allows network operators to set the starting price point for the fee asset. + +### `reloadKeystore` admin RPC endpoint + +Node operators can now update validator attester keys, coinbase, and fee recipient without restarting the node by calling the new `reloadKeystore` admin RPC endpoint. + +What is updated on reload: + +- Validator attester keys (add, remove, or replace) +- Coinbase and fee recipient per validator +- Publisher-to-validator mapping + +What is NOT updated (requires restart): + +- L1 publisher signers +- Prover keys +- HA signer connections + +New validators must use a publisher key already initialized at startup. Reload is rejected with a clear error if validation fails. + +### Admin API key authentication + +The admin JSON-RPC endpoint now supports auto-generated API key authentication. + +**Behavior:** + +- A cryptographically secure API key is auto-generated at first startup and displayed once via stdout +- Only the SHA-256 hash is persisted to `/admin/api_key_hash` +- The key is reused across restarts when `--data-directory` is set +- Supports both `x-api-key` and `Authorization: Bearer ` headers +- Health check endpoint (`GET /status`) is excluded from auth (for k8s probes) + +**Configuration:** + +```bash +--admin-api-key-hash ($AZTEC_ADMIN_API_KEY_HASH) # Use a pre-generated SHA-256 key hash +--disable-admin-api-key ($AZTEC_DISABLE_ADMIN_API_KEY) # Disable auth entirely +--reset-admin-api-key ($AZTEC_RESET_ADMIN_API_KEY) # Force key regeneration +``` + +**Helm charts**: Admin API key auth is disabled by default (`disableAdminApiKey: true`). Set to `false` in production values to enable. + +**Migration**: No action required — auth is opt-out. To enable, ensure `--disable-admin-api-key` is not set and note the key printed at startup. + +### Transaction pool error codes for RPC callers + +Transaction submission via RPC now returns structured rejection codes when a transaction is rejected by the mempool: + +- `LOW_PRIORITY_FEE` — tx priority fee is too low +- `INSUFFICIENT_FEE_PAYER_BALANCE` — fee payer doesn't have enough balance +- `NULLIFIER_CONFLICT` — conflicting nullifier already in pool + +**Impact**: Improved developer experience — callers can now programmatically handle specific rejection reasons. + +### RPC transaction replacement price bump + +Transactions submitted via RPC that clash on nullifiers with existing pool transactions must now pay at least X% more in priority fee to replace them. The same bump applies when the pool is full and the incoming tx needs to evict the lowest-priority tx. P2P gossip behavior is unchanged. + +**Configuration:** + +```bash +P2P_RPC_PRICE_BUMP_PERCENTAGE=10 # default: 10 (percent) +``` + +Set to `0` to disable the percentage-based bump (still requires strictly higher fee). + +### Validator-specific block limits + +Validators can now enforce per-block and per-checkpoint limits independently from the sequencer (proposer) limits. This allows operators to accept proposals that exceed their own proposer settings, or to reject proposals that are too large even if the proposer's limits allow them. + +**Configuration:** + +```bash +VALIDATOR_MAX_L2_BLOCK_GAS= # Max L2 gas per block for validation +VALIDATOR_MAX_DA_BLOCK_GAS= # Max DA gas per block for validation +VALIDATOR_MAX_TX_PER_BLOCK= # Max txs per block for validation +VALIDATOR_MAX_TX_PER_CHECKPOINT= # Max txs per checkpoint for validation +``` -Added a 500ms tolerance window for P2P messages from the previous slot, following Ethereum's `MAXIMUM_GOSSIP_CLOCK_DISPARITY` approach. This prevents peers from being penalized for valid messages that arrive slightly after the slot boundary due to network latency. +When not set, no per-block limit is enforced for that dimension — only checkpoint-level protocol limits apply. These do not fall back to the `SEQ_` values. -The tolerance is hardcoded at 500ms (matching Ethereum's current value) and can be made configurable via environment variables in the future if needed. +### Setup allow list extendable via network config -**Impact**: Improved network stability with no action required from node operators. +The setup phase allow list can now be extended via the network configuration JSON (`txPublicSetupAllowListExtend` field). This allows network operators to distribute additional allowed setup functions to all nodes without requiring code changes. The local environment variable takes precedence over the network-json value. +>>>>>>> cbb09bcc85 (fix(docs): restore operator changelog v4.md and add v4.2 to sidebar (#22609)):docs/network_versioned_docs/version-v4.2.0/reference/changelog/v4.md ## Changed defaults ## Troubleshooting diff --git a/docs/network_versioned_docs/version-v4.1.2/operators/reference/changelog/index.md b/docs/network_versioned_docs/version-v4.1.2/operators/reference/changelog/index.md index 8ac918dbd583..0cf9b04f4ecd 100644 --- a/docs/network_versioned_docs/version-v4.1.2/operators/reference/changelog/index.md +++ b/docs/network_versioned_docs/version-v4.1.2/operators/reference/changelog/index.md @@ -11,6 +11,19 @@ This changelog documents all configuration changes, new features, and breaking c ## Version history +### [v4.2.0](./v4.2.md) + +New features and configuration options for node operators. + +**Key changes:** +- Blob retrieval improvements with unified retry loop + +**Migration difficulty**: Low + +[View full changelog →](./v4.2.md) + +--- + ### [v4.x (Upgrade from Ignition)](./v4.md) Major upgrade from Ignition (v2.x) to Alpha (v4.x) with significant architectural changes. diff --git a/docs/network_versioned_docs/version-v4.1.2/operators/reference/changelog/v4.md b/docs/network_versioned_docs/version-v4.1.2/operators/reference/changelog/v4.md index 26a67ed75c82..a12bee3d00b6 100644 --- a/docs/network_versioned_docs/version-v4.1.2/operators/reference/changelog/v4.md +++ b/docs/network_versioned_docs/version-v4.1.2/operators/reference/changelog/v4.md @@ -186,7 +186,7 @@ Run the database migration before starting your nodes: aztec migrate-ha-db up --database-url ``` -**Migration**: If you run a single node, no action is required. If you run redundant nodes for high availability, configure HA signing immediately. See the [High Availability Sequencers](../../setup/high_availability_sequencers) guide for details. +**Migration**: If you run a single node, no action is required. If you run redundant nodes for high availability, configure HA signing immediately. See the [High Availability Sequencers](../../setup/high-availability.md) guide for details. ### Blob-only data publication diff --git a/docs/network_versioned_sidebars/version-v2.1.11-ignition-sidebars.json b/docs/network_versioned_sidebars/version-v2.1.11-ignition-sidebars.json index df4c27e906ef..2d978cb055b4 100644 --- a/docs/network_versioned_sidebars/version-v2.1.11-ignition-sidebars.json +++ b/docs/network_versioned_sidebars/version-v2.1.11-ignition-sidebars.json @@ -136,6 +136,7 @@ "id": "operators/reference/changelog/changelog" }, "items": [ + "operators/reference/changelog/v4.2", "operators/reference/changelog/v4", "operators/reference/changelog/v2.0.2" ] diff --git a/docs/sidebars-operate.js b/docs/sidebars-operate.js index 514874bcaf71..bb94c7ee3a74 100644 --- a/docs/sidebars-operate.js +++ b/docs/sidebars-operate.js @@ -145,6 +145,7 @@ const sidebars = { id: "operators/reference/changelog/changelog", }, items: [ + "operators/reference/changelog/v4.2", "operators/reference/changelog/v4", "operators/reference/changelog/v2.0.2", ], From fc36658b8779930e5fd0fdcba7373385c09691ff Mon Sep 17 00:00:00 2001 From: AztecBot Date: Fri, 17 Apr 2026 14:31:33 +0000 Subject: [PATCH 2/3] fix: resolve cherry-pick conflicts Restore version-v2.1.11-ignition/reference/changelog/v4.md to its pre-cherry-pick state. Git rename-detected version-v4.2.0/reference/ changelog/v4.md onto this path (version-v4.2.0 does not exist on v4-next), producing a conflict plus unwanted auto-merges. The v2.1.11-ignition snapshot must remain unchanged. --- .../reference/changelog/v4.md | 329 ++---------------- 1 file changed, 35 insertions(+), 294 deletions(-) diff --git a/docs/network_versioned_docs/version-v2.1.11-ignition/reference/changelog/v4.md b/docs/network_versioned_docs/version-v2.1.11-ignition/reference/changelog/v4.md index 4ae76c5a5906..6f4abb6a79ae 100644 --- a/docs/network_versioned_docs/version-v2.1.11-ignition/reference/changelog/v4.md +++ b/docs/network_versioned_docs/version-v2.1.11-ignition/reference/changelog/v4.md @@ -1,329 +1,70 @@ --- -title: v4.x (Upgrade from Ignition) -description: Breaking changes and migration guide for upgrading from Ignition (v2.x) to Alpha (v4.x). +title: v4.0.0 (from v3.0.0) +description: TODO --- ## Overview -**Migration difficulty**: High +**Migration difficulty**: TODO ## Breaking changes -### Node.js upgraded to v24 +### StakingAssetHandler refactored to simple token faucet -Node.js minimum version changed from v22 to v24.12.0. +The `StakingAssetHandler` L1 contract has been significantly simplified. It no longer handles validator registration directly - instead it functions as a simple STK token faucet with ZKPassport sybil resistance. -### Bot fee padding configuration renamed - -The bot configuration for fee padding has been renamed from "base fee" to "min fee". - -**v3.x:** - -```bash ---bot.baseFeePadding ($BOT_BASE_FEE_PADDING) -``` - -**v4.0.0:** - -```bash ---bot.minFeePadding ($BOT_MIN_FEE_PADDING) -``` - -**Migration**: Update your configuration to use the new flag name and environment variable. - -### L2Tips API restructured with checkpoint information - -The `getL2Tips()` RPC endpoint now returns a restructured response with additional checkpoint tracking. - -**v3.x response:** - -```json -{ - "latest": { "number": 100, "hash": "0x..." }, - "proven": { "number": 98, "hash": "0x..." }, - "finalized": { "number": 95, "hash": "0x..." } -} -``` - -**v4.0.0 response:** - -```json -{ - "proposed": { "number": 100, "hash": "0x..." }, - "checkpointed": { - "block": { "number": 99, "hash": "0x..." }, - "checkpoint": { "number": 10, "hash": "0x..." } - }, - "proven": { - "block": { "number": 98, "hash": "0x..." }, - "checkpoint": { "number": 9, "hash": "0x..." } - }, - "finalized": { - "block": { "number": 95, "hash": "0x..." }, - "checkpoint": { "number": 8, "hash": "0x..." } - } -} -``` - -**Migration**: - -- Replace `tips.latest` with `tips.proposed` -- For `checkpointed`, `proven`, and `finalized` tips, access block info via `.block` (e.g., `tips.proven.block.number`) - -### Block gas limits reworked - -The byte-based block size limit has been removed and replaced with field-based blob limits and automatic gas budget computation from L1 rollup limits. - -**Removed:** - -```bash ---maxBlockSizeInBytes ($SEQ_MAX_BLOCK_SIZE_IN_BYTES) -``` - -**Changed to optional (now auto-computed from L1 if not set):** - -```bash ---maxL2BlockGas ($SEQ_MAX_L2_BLOCK_GAS) ---maxDABlockGas ($SEQ_MAX_DA_BLOCK_GAS) -``` - -**New (proposer):** - -```bash ---perBlockAllocationMultiplier ($SEQ_PER_BLOCK_ALLOCATION_MULTIPLIER) ---maxTxsPerCheckpoint ($SEQ_MAX_TX_PER_CHECKPOINT) -``` - -**New (validator):** - -```bash ---validateMaxL2BlockGas ($VALIDATOR_MAX_L2_BLOCK_GAS) ---validateMaxDABlockGas ($VALIDATOR_MAX_DA_BLOCK_GAS) ---validateMaxTxsPerBlock ($VALIDATOR_MAX_TX_PER_BLOCK) ---validateMaxTxsPerCheckpoint ($VALIDATOR_MAX_TX_PER_CHECKPOINT) -``` - -**Migration**: Remove `SEQ_MAX_BLOCK_SIZE_IN_BYTES` from your configuration. Per-block L2 and DA gas budgets are now derived automatically as `(checkpointLimit / maxBlocks) * multiplier`, where the multiplier defaults to 2. You can still override `SEQ_MAX_L2_BLOCK_GAS` and `SEQ_MAX_DA_BLOCK_GAS` explicitly, but they will be capped at the checkpoint-level limits. Validators can now set independent per-block and per-checkpoint limits via the `VALIDATOR_` env vars; when not set, only checkpoint-level protocol limits are enforced. - -### Setup phase allow list requires function selectors - -The transaction setup phase allow list now enforces function selectors, restricting which specific functions can run during setup on whitelisted contracts. Previously, any public function on a whitelisted contract or class was permitted. - -The semantics of the environment variable `TX_PUBLIC_SETUP_ALLOWLIST` have changed: - -**v3.x:** - -```bash ---txPublicSetupAllowList ($TX_PUBLIC_SETUP_ALLOWLIST) +**v3.0.0:** +```solidity +// Single call registered validator +stakingAssetHandler.addValidator(attester, merkleProof, zkPassportParams, publicKeyG1, publicKeyG2, signature); ``` -The variable fully **replaced** the hardcoded defaults. Format allowed entries without selectors: `I:address`, `C:classId`. - **v4.0.0:** +```solidity +// Step 1: Claim STK tokens from faucet +stakingAssetHandler.claim(zkPassportParams); -```bash ---txPublicSetupAllowListExtend ($TX_PUBLIC_SETUP_ALLOWLIST) -``` - -The variable now **extends** the hardcoded defaults (which are always present). Selectors are now mandatory. An optional flags segment can be appended for additional validation: - -``` -I:address:selector[:flags] -C:classId:selector[:flags] -``` - -Where `flags` is a `+`-separated list of: -- `os` — `onlySelf`: only allow calls where msg_sender == contract address -- `rn` — `rejectNullMsgSender`: reject calls with a null msg_sender -- `cl=N` — `calldataLength`: enforce exact calldata length of N fields - -Example: `C:0xabc:0x1234:os+cl=4` - -**Migration**: If you were using `TX_PUBLIC_SETUP_ALLOWLIST`, ensure all entries include function selectors. Note the variable now adds to defaults rather than replacing them. If you were not setting this variable, no action is needed — the hardcoded defaults now include the correct selectors automatically. - -### Token removed from default setup allowlist - -Token class-based entries (`_increase_public_balance` and `transfer_in_public`) have been removed from the default public setup allowlist. FPC-based fee payments using custom tokens no longer work out of the box. - -This change was made because Token class IDs change with aztec-nr releases, making the allowlist impossible to keep up to date with new library releases. In addition, `transfer_in_public` requires complex additional logic to be built into the node to prevent mass transaction invalidation attacks. **FPC-based fee payment with custom tokens won't work on mainnet alpha**. - -**Migration**: Node operators who need FPC support must manually add Token entries via `TX_PUBLIC_SETUP_ALLOWLIST`. Example: - -```bash -TX_PUBLIC_SETUP_ALLOWLIST="C:::os+cl=3,C:::cl=5" -``` - -Replace `` with the deployed Token contract class ID and ``/`` with the respective function selectors. Keep in mind that this will only work on local network setups, since even if you as an operator add these entries, other nodes will not have them and will not pick up these transactions. +// Step 2: Approve rollup to spend tokens +stakingAsset.approve(rollupAddress, amount); -### Sequencer environment variable renames - -Several sequencer environment variables have been renamed: - -| Old variable | New variable | -|---|---| -| `SEQ_TX_POLLING_INTERVAL_MS` | `SEQ_POLLING_INTERVAL_MS` | -| `SEQ_MAX_L1_TX_INCLUSION_TIME_INTO_SLOT` | `SEQ_L1_PUBLISHING_TIME_ALLOWANCE_IN_SLOT` | -| `SEQ_MAX_TX_PER_BLOCK` | `SEQ_MAX_TX_PER_CHECKPOINT` | -| `SEQ_MAX_BLOCK_SIZE_IN_BYTES` | Removed (see [Block gas limits reworked](#block-gas-limits-reworked)) | - -**Migration**: Search your configuration for the old variable names and replace them. The node will not recognize the old names. - -### Double signing slashing - -New slashable offenses have been introduced for duplicate proposals and duplicate attestations. Penalty amounts are currently set to 0, but the detection infrastructure is active. - -If you run redundant sequencer nodes, you **must** enable high-availability signing with PostgreSQL to prevent accidental double signing: - -```bash -VALIDATOR_HA_SIGNING_ENABLED=true -VALIDATOR_HA_DATABASE_URL=postgresql://:@:/ -VALIDATOR_HA_NODE_ID= +// Step 3: Deposit into rollup (user chooses their own withdrawer) +rollup.deposit(attester, withdrawer, publicKeyG1, publicKeyG2, signature, moveWithLatestRollup); ``` -Run the database migration before starting your nodes: +**Removed functions:** +- `addValidator()` - replaced by `claim()` + direct rollup deposit +- `reenterExitedValidator()` +- `setValidatorsToFlush()`, `setMintInterval()`, `setDepositsPerMint()`, `setWithdrawer()` +- `setSkipMerkleCheck()`, `setDepositMerkleRoot()` -```bash -aztec migrate-ha-db up --database-url -``` - -**Migration**: If you run a single node, no action is required. If you run redundant nodes for high availability, configure HA signing immediately. See the [High Availability Sequencers](../../operators/setup/high-availability.md) guide for details. - -### Blob-only data publication - -Transaction data is now published entirely via EIP-4844 blobs. The calldata fallback has been removed. - -Your consensus client (e.g., Lighthouse, Prysm) must run as a **supernode** or **semi-supernode** to make blobs available for retrieval. Standard pruning configurations will not retain blobs long enough. - -You should also configure blob file stores for redundancy: +**New functions:** +- `claim(ProofVerificationParams)` - claim STK tokens with ZKPassport proof +- `setFaucetAmount(uint256)` - owner sets claim amount +- `resetNullifier(bytes32)` - owner can reset a nullifier +**CLI changes:** ```bash -BLOB_FILE_STORE_URLS= -BLOB_FILE_STORE_UPLOAD_URL= -BLOB_ARCHIVE_API_URL= -``` +# v3.0.0 +aztec add-l1-validator --merkle-proof -**Migration**: Ensure your consensus client is configured as a supernode. If you previously relied on calldata for data availability, switch to blob-based retrieval. See the [Blob Storage](../../operators/setup/blob_storage) guide for configuration details. - -### Withdrawal delay increase - -The governance execution delay has increased from 7 days to 30 days. This extends the time required for staker withdrawals from approximately 15 days to approximately 38 days. - -**Migration**: No configuration changes needed. Be aware that withdrawal processing will take longer after the upgrade. - -### Prover architecture change - -The prover now runs as a node subsystem rather than a separate standalone process. Start it alongside your node using the `--prover-node` flag: - -```bash -aztec start --node --prover-node +# v4.0.0 +aztec add-l1-validator --withdrawer-address
``` -**Migration**: If you were running the prover as a separate process, update your deployment to run it as part of the node with `--prover-node`. +**Migration**: Users must now call `claim()` to get STK tokens, then deposit into the rollup themselves. The `--merkle-proof` CLI flag is removed; add `--withdrawer-address` instead. ## Removed features ## New features -### Initial ETH per fee asset configuration - -A new environment variable `AZTEC_INITIAL_ETH_PER_FEE_ASSET` has been added to configure the initial exchange rate between ETH and the fee asset (AZTEC) at contract deployment. This value uses 1e12 precision. - -**Default**: `10000000` (0.00001 ETH per AZTEC) - -**Configuration:** - -<<<<<<< HEAD:docs/network_versioned_docs/version-v2.1.11-ignition/reference/changelog/v4.md -======= -```bash ---initialEthPerFeeAsset ($AZTEC_INITIAL_ETH_PER_FEE_ASSET) -``` - -This replaces the previous hardcoded default and allows network operators to set the starting price point for the fee asset. - -### `reloadKeystore` admin RPC endpoint - -Node operators can now update validator attester keys, coinbase, and fee recipient without restarting the node by calling the new `reloadKeystore` admin RPC endpoint. - -What is updated on reload: - -- Validator attester keys (add, remove, or replace) -- Coinbase and fee recipient per validator -- Publisher-to-validator mapping - -What is NOT updated (requires restart): - -- L1 publisher signers -- Prover keys -- HA signer connections - -New validators must use a publisher key already initialized at startup. Reload is rejected with a clear error if validation fails. - -### Admin API key authentication - -The admin JSON-RPC endpoint now supports auto-generated API key authentication. - -**Behavior:** - -- A cryptographically secure API key is auto-generated at first startup and displayed once via stdout -- Only the SHA-256 hash is persisted to `/admin/api_key_hash` -- The key is reused across restarts when `--data-directory` is set -- Supports both `x-api-key` and `Authorization: Bearer ` headers -- Health check endpoint (`GET /status`) is excluded from auth (for k8s probes) - -**Configuration:** - -```bash ---admin-api-key-hash ($AZTEC_ADMIN_API_KEY_HASH) # Use a pre-generated SHA-256 key hash ---disable-admin-api-key ($AZTEC_DISABLE_ADMIN_API_KEY) # Disable auth entirely ---reset-admin-api-key ($AZTEC_RESET_ADMIN_API_KEY) # Force key regeneration -``` - -**Helm charts**: Admin API key auth is disabled by default (`disableAdminApiKey: true`). Set to `false` in production values to enable. - -**Migration**: No action required — auth is opt-out. To enable, ensure `--disable-admin-api-key` is not set and note the key printed at startup. - -### Transaction pool error codes for RPC callers - -Transaction submission via RPC now returns structured rejection codes when a transaction is rejected by the mempool: - -- `LOW_PRIORITY_FEE` — tx priority fee is too low -- `INSUFFICIENT_FEE_PAYER_BALANCE` — fee payer doesn't have enough balance -- `NULLIFIER_CONFLICT` — conflicting nullifier already in pool - -**Impact**: Improved developer experience — callers can now programmatically handle specific rejection reasons. - -### RPC transaction replacement price bump - -Transactions submitted via RPC that clash on nullifiers with existing pool transactions must now pay at least X% more in priority fee to replace them. The same bump applies when the pool is full and the incoming tx needs to evict the lowest-priority tx. P2P gossip behavior is unchanged. - -**Configuration:** - -```bash -P2P_RPC_PRICE_BUMP_PERCENTAGE=10 # default: 10 (percent) -``` - -Set to `0` to disable the percentage-based bump (still requires strictly higher fee). - -### Validator-specific block limits - -Validators can now enforce per-block and per-checkpoint limits independently from the sequencer (proposer) limits. This allows operators to accept proposals that exceed their own proposer settings, or to reject proposals that are too large even if the proposer's limits allow them. - -**Configuration:** - -```bash -VALIDATOR_MAX_L2_BLOCK_GAS= # Max L2 gas per block for validation -VALIDATOR_MAX_DA_BLOCK_GAS= # Max DA gas per block for validation -VALIDATOR_MAX_TX_PER_BLOCK= # Max txs per block for validation -VALIDATOR_MAX_TX_PER_CHECKPOINT= # Max txs per checkpoint for validation -``` +### P2P clock tolerance for slot validation -When not set, no per-block limit is enforced for that dimension — only checkpoint-level protocol limits apply. These do not fall back to the `SEQ_` values. +Added a 500ms tolerance window for P2P messages from the previous slot, following Ethereum's `MAXIMUM_GOSSIP_CLOCK_DISPARITY` approach. This prevents peers from being penalized for valid messages that arrive slightly after the slot boundary due to network latency. -### Setup allow list extendable via network config +The tolerance is hardcoded at 500ms (matching Ethereum's current value) and can be made configurable via environment variables in the future if needed. -The setup phase allow list can now be extended via the network configuration JSON (`txPublicSetupAllowListExtend` field). This allows network operators to distribute additional allowed setup functions to all nodes without requiring code changes. The local environment variable takes precedence over the network-json value. +**Impact**: Improved network stability with no action required from node operators. ->>>>>>> cbb09bcc85 (fix(docs): restore operator changelog v4.md and add v4.2 to sidebar (#22609)):docs/network_versioned_docs/version-v4.2.0/reference/changelog/v4.md ## Changed defaults ## Troubleshooting From 54eb65091d64a20c4d0f24d9f74a117f6ee61511 Mon Sep 17 00:00:00 2001 From: AztecBot Date: Fri, 17 Apr 2026 14:32:40 +0000 Subject: [PATCH 3/3] fix: adapt backport for v4-next (no v4.2.0 version yet) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adapt cherry-pick result for v4-next, which does not yet contain the v4.2.0 versioned snapshot nor the operator v4.2.md source file. - Revert misdirected rename targets in v4.1.2/operators/changelog/index.md and v2.1.11-ignition-sidebars.json (v4.2 entries point to files that do not exist on this branch). - Drop the v4.2 entries from docs-operate/operators/reference/changelog/ index.md and sidebars-operate.js for the same reason — including them would break the Docusaurus build. They should be added back when v4.2 infrastructure (#22581 / #22612) is backported. Kept: - docs-operate/reference/changelog/v4.md content restore (core fix) - v4.1.2/operators/reference/changelog/v4.md HA-guide link fix (the target file is high-availability.md on v4-next too, so the underscore link was already broken here). --- .../operators/reference/changelog/index.md | 13 ------------- .../operators/reference/changelog/index.md | 13 ------------- .../version-v2.1.11-ignition-sidebars.json | 1 - docs/sidebars-operate.js | 1 - 4 files changed, 28 deletions(-) diff --git a/docs/docs-operate/operators/reference/changelog/index.md b/docs/docs-operate/operators/reference/changelog/index.md index 0cf9b04f4ecd..8ac918dbd583 100644 --- a/docs/docs-operate/operators/reference/changelog/index.md +++ b/docs/docs-operate/operators/reference/changelog/index.md @@ -11,19 +11,6 @@ This changelog documents all configuration changes, new features, and breaking c ## Version history -### [v4.2.0](./v4.2.md) - -New features and configuration options for node operators. - -**Key changes:** -- Blob retrieval improvements with unified retry loop - -**Migration difficulty**: Low - -[View full changelog →](./v4.2.md) - ---- - ### [v4.x (Upgrade from Ignition)](./v4.md) Major upgrade from Ignition (v2.x) to Alpha (v4.x) with significant architectural changes. diff --git a/docs/network_versioned_docs/version-v4.1.2/operators/reference/changelog/index.md b/docs/network_versioned_docs/version-v4.1.2/operators/reference/changelog/index.md index 0cf9b04f4ecd..8ac918dbd583 100644 --- a/docs/network_versioned_docs/version-v4.1.2/operators/reference/changelog/index.md +++ b/docs/network_versioned_docs/version-v4.1.2/operators/reference/changelog/index.md @@ -11,19 +11,6 @@ This changelog documents all configuration changes, new features, and breaking c ## Version history -### [v4.2.0](./v4.2.md) - -New features and configuration options for node operators. - -**Key changes:** -- Blob retrieval improvements with unified retry loop - -**Migration difficulty**: Low - -[View full changelog →](./v4.2.md) - ---- - ### [v4.x (Upgrade from Ignition)](./v4.md) Major upgrade from Ignition (v2.x) to Alpha (v4.x) with significant architectural changes. diff --git a/docs/network_versioned_sidebars/version-v2.1.11-ignition-sidebars.json b/docs/network_versioned_sidebars/version-v2.1.11-ignition-sidebars.json index 2d978cb055b4..df4c27e906ef 100644 --- a/docs/network_versioned_sidebars/version-v2.1.11-ignition-sidebars.json +++ b/docs/network_versioned_sidebars/version-v2.1.11-ignition-sidebars.json @@ -136,7 +136,6 @@ "id": "operators/reference/changelog/changelog" }, "items": [ - "operators/reference/changelog/v4.2", "operators/reference/changelog/v4", "operators/reference/changelog/v2.0.2" ] diff --git a/docs/sidebars-operate.js b/docs/sidebars-operate.js index bb94c7ee3a74..514874bcaf71 100644 --- a/docs/sidebars-operate.js +++ b/docs/sidebars-operate.js @@ -145,7 +145,6 @@ const sidebars = { id: "operators/reference/changelog/changelog", }, items: [ - "operators/reference/changelog/v4.2", "operators/reference/changelog/v4", "operators/reference/changelog/v2.0.2", ],