# ValidatorConfig V2 ## Abstract TIP-1017 defines ValidatorConfig V2, a new precompile for managing consensus participants. V2 improves lifecycle tracking so validator sets can be reconstructed for any epoch, and adds stricter input validation. It is designed to safely support permissionless validator rotation, and additionally allows separation of fee custody from day-to-day validator operations. ## Necessary background information In Tempo, validator information is stored on-chain. This includes which nodes make up the current committee, which nodes are intended to join or leave the committee, and their network information (ingress, egress). Each validator is uniquely identified by its ed25519 public key used for signing all consensus p2p messages. For consensus itself, Tempo employs bls12381 threshold cryptography, where each validator is assigned a private key share corresponding to a section of the network public key. The network key itself is undergoing a re-sharing Distributed Key Generation process every epoch, where each epoch runs for a fixed number of blocks. The outcome of the DKG process is written to last block of an epoch. The DKG outcome contains the validators that made up the committee in epoch `E-1` (called dealers), the validators that will make up the committee in `E` (called players during `E-1`), and the validators that will participate as players in the DKG process during epoch `E` to become committee members in `E+1`. To determine the next players, validators read the contract state at the end of the epoch and select all entries marked as active. The DKG outcome hence determines who the committee members *are*, and the contract states who the committee members *should be*. ## Motivation The original ValidatorConfig precompile (frequently referred to V1 from here on), was too permissive. It allowed addresses to arbitrarily change the values of their entry in the contract, potentially breaking consensus. This and other issues were: 1. **Key ownership verification**: V1 does not verify that the caller controls the private key corresponding to the public key being registered. A malicious validator could hence grief another validator by using their public key, breaking the consensus requirement that all keys be unique. 2. **Validator re-registration**: V1 allows deleted validators to be re-added with different parameters, complicating historical queries. 3. **Historical state dependency**: Because V1 contained a warmup epoch for new validators, and because these were not written to the DKG outcome, to sync a node always needed to keep up to twice the epoch length of blocks around, requiring bloated snapshots and preventing aggressive pruning. Tempo solved problems 1 and 2 by assigning validators entries anonymous addresses. Thus, only the contract owner could change or deactivate entries. ### How V2 solves these problems: * ed25519 signature verification proves key ownership at registration time * fields `addedAtHeight` and `deactivatedAtHeight` are controlled by the contract and cannot be mutated by the owner and allow historical state reconstruction. * Public keys remain reserved forever (even after deactivation) * Addresses are unique among current validators but can be reassigned via `transferValidatorOwnership` # Specification ## Precompile Address ```solidity address constant VALIDATOR_CONFIG_V2_ADDRESS = 0xCCCCCCCC00000000000000000000000000000001; ``` ## Interface ```solidity // SPDX-License-Identifier: MIT pragma solidity ^0.8.13; /// @title IValidatorConfigV2 - Validator Config V2 Precompile Interface /// @notice Interface for managing consensus validators with append-only, deactivate-once semantics interface IValidatorConfigV2 { /// @notice Caller is not authorized. error Unauthorized(); /// @notice Active validator address already exists. error AddressAlreadyHasValidator(); /// @notice Public key already exists. error PublicKeyAlreadyExists(); /// @notice Validator was not found. error ValidatorNotFound(); /// @notice Validator is already deactivated. error ValidatorAlreadyDeactivated(); /// @notice Public key is invalid. error InvalidPublicKey(); /// @notice Validator address is invalid. error InvalidValidatorAddress(); /// @notice Ed25519 signature verification failed. error InvalidSignature(); /// @notice Contract is not initialized. error NotInitialized(); /// @notice Contract is already initialized. error AlreadyInitialized(); /// @notice Migration is not complete. error MigrationNotComplete(); /// @notice V1 has no validators to migrate. error EmptyV1ValidatorSet(); /// @notice Migration index is out of order. error InvalidMigrationIndex(); /// @notice Address is not in valid `IP:port` format. /// @param input Invalid input. /// @param backtrace Additional error context. error NotIpPort(string input, string backtrace); /// @notice Address is not a valid IP address. /// @param input Invalid input. /// @param backtrace Additional error context. error NotIp(string input, string backtrace); /// @notice Ingress IP is already in use by an active validator. /// @param ingress Conflicting ingress address. error IngressAlreadyExists(string ingress); /// @notice Validator information /// @param publicKey Ed25519 communication public key. /// @param validatorAddress Validator address. /// @param ingress Inbound address in `:` format. /// @param egress Outbound address in `` format. /// @param index Immutable validators-array position. /// @param addedAtHeight Block height when entry was added. /// @param deactivatedAtHeight Block height when entry was deactivated (`0` if active). /// @param feeRecipient The fee recipient the node will set when proposing blocks as a leader. struct Validator { bytes32 publicKey; address validatorAddress; string ingress; string egress; uint64 index; uint64 addedAtHeight; uint64 deactivatedAtHeight; address feeRecipient; } /// @notice Get active validators. /// @return validators Active validators (`deactivatedAtHeight == 0`). function getActiveValidators() external view returns (Validator[] memory validators); /// @notice Get contract owner. /// @return Owner address. function owner() external view returns (address); /// @notice Get total validators, including deactivated entries. /// @return count Validator count. function validatorCount() external view returns (uint64); /// @notice Get validator by array index. /// @param index Validators-array index. /// @return validator Validator at `index`. function validatorByIndex(uint64 index) external view returns (Validator memory); /// @notice Get validator by address. /// @param validatorAddress Validator address. /// @return validator Validator for `validatorAddress`. function validatorByAddress(address validatorAddress) external view returns (Validator memory); /// @notice Get validator by public key. /// @param publicKey Ed25519 public key. /// @return validator Validator for `publicKey`. function validatorByPublicKey(bytes32 publicKey) external view returns (Validator memory); /// @notice Get next epoch configured for a fresh DKG ceremony. /// @return epoch Epoch number, or `0` if none is scheduled. function getNextFullDkgCeremony() external view returns (uint64); /// @notice Add a new validator (owner only) /// @dev Requires Ed25519 signature over a unique digest generated from inputs. /// @param validatorAddress New validator address. /// @param publicKey Validator Ed25519 communication public key. /// @param ingress Inbound address `:`. /// @param egress Outbound address ``. /// @param feeRecipient The fee recipient the validator sets when proposing. /// @param signature Ed25519 signature proving key ownership. function addValidator( address validatorAddress, bytes32 publicKey, string calldata ingress, string calldata egress, address feeRecipient, bytes calldata signature ) external returns (uint64); /// @notice Deactivate a validator (owner or validator only). /// @dev Sets `deactivatedAtHeight` to current block height. /// @param idx Validator index. function deactivateValidator(uint64 idx) external; /// @notice Rotate a validator to a new identity (owner or validator only). /// @dev Preserves index stability by appending a copy of the existing entry and updating the entry in-place. /// @param idx Validator index to rotate. /// @param publicKey New Ed25519 communication public key. /// @param ingress New inbound address `:`. Must be different from the rotated-out validator (changing port is enough). /// @param egress New outbound address ``. /// @param signature Ed25519 signature proving new key ownership. function rotateValidator( uint64 idx, bytes32 publicKey, string calldata ingress, string calldata egress, bytes calldata signature ) external; /// @notice Update validator IP addresses (owner or validator only). /// @param idx Validator index. /// @param ingress New inbound address `:`. /// @param egress New outbound address ``. function setIpAddresses( uint64 idx, string calldata ingress, string calldata egress ) external; /// @notice Update validator fee recipient (owner or validator only). /// @param idx Validator index. /// @param feeRecipient New fee recipient. function setFeeRecipient( uint64 idx, address feeRecipient ) external; /// @notice Transfer validator entry to a new address (owner or validator only). /// @dev Reverts if `newAddress` conflicts with an active validator. /// @param idx Validator index. /// @param newAddress New validator address. function transferValidatorOwnership(uint64 idx, address newAddress) external; /// @notice Transfer contract ownership (owner only). /// @param newOwner New owner address. function transferOwnership(address newOwner) external; /// @notice Set next fresh DKG ceremony epoch (owner only). /// @param epoch Epoch where ceremony runs (`epoch + 1` uses new polynomial). function setNextFullDkgCeremony(uint64 epoch) external; /// @notice Migrate one validator by V1 index (owner only). /// @param idx V1 validator index. function migrateValidator(uint64 idx) external; /// @notice Initialize V2 and enable reads (owner only). /// @dev Requires all V1 indices to be processed. function initializeIfMigrated() external; /// @notice Check initialization state. /// @return initialized True if initialized. function isInitialized() external view returns (bool); /// @notice Get initialization block height. /// @return height Initialization height (`0` if not initialized). function getInitializedAtHeight() external view returns (uint64); } ``` ## Overview * Migration incrementally reads and copies validator entries from V1 into V2. * During migration, the consensus layer continues reading V1 until `initializeIfMigrated()` completes. * Validator history are append-only, and deactivation is one-way. * Historical validator sets are reconstructed from `addedAtHeight` and `deactivatedAtHeight`. * Validator `index` is stable for the lifetime of an entry. * Writes for post-migration operations are gated by `isInitialized()`. ## State Model V2 stores validators in one append-only array, with lookup indexes by address and public key. * `addedAtHeight`: block height where the entry becomes visible to CL epoch filtering. * `deactivatedAtHeight`: `0` means active; non-zero marks irreversible deactivation. * `index`: immutable array position assigned at creation. * `initialized`: one-way migration flag toggled by `initializeIfMigrated()`. ### Fee Recipient Separation Each validator entry includes a `feeRecipient` that can differ from the validator's control address. This enables operators to route protocol fees to a dedicated treasury wallet, while retaining a separate validator or treasury-ops multisig for operational calls. This separation reduces blast radius during key compromise: operational key exposure does not cause historically collected fees held by the custody wallet to be lost. ## Operation Semantics ### Lifecycle Operations * `addValidator`: appends a new active entry after validation and signature verification. * `deactivateValidator`: marks an existing active entry as deactivated at current block height. * `rotateValidator`: to keep `index` stable, this updates the active entry in place and appends the entry to be deactivated. Active validator count is unchanged. ### Network And Ownership Operations * `setIpAddresses`: updates ingress and egress for an active validator, enforcing address format and ingress uniqueness among active entries. * `setFeeRecipient`: updates the destination address that receives network fees from block proposing. * `transferValidatorOwnership`: rebinds a validator entry to a new address provided the address is not used by another active entry. ### Migration And Phase-Gating Operations * `migrateValidator`: copies one V1 entry into V2 in descending index order. * `initializeIfMigrated`: switches V2 to initialized state after all V1 indices have been processed. * Mutators are phase-gated: migration mutators are blocked after init, and post-init mutators are blocked before init. ### Input Validation And Safety Checks ValidatorConfig V2 enforces the following checks: 1. Validator ed25519 public keys must be unique across all validators (active and inactive). 2. Validator addresses must be unique across active validators. 3. `ingress` must be a valid `IP:port`, and unique across active validators. 4. `egress` must be a valid IP. 5. `addValidator` and `rotateValidator` require a signature from the Ed25519 key being installed. ### Ed25519 Signature Verification When adding or rotating a validator, the caller must provide an Ed25519 signature proving ownership of the public key. **Namespace:** `addValidator` uses `b"TEMPO_VALIDATOR_CONFIG_V2_ADD_VALIDATOR"` and `rotateValidator` uses `b"TEMPO_VALIDATOR_CONFIG_V2_ROTATE_VALIDATOR"`. **Messages:** ``` addValidatorMessage = keccak256( bytes8(chainId) // uint64: Prevents cross-chain replay || contractAddress // address: Prevents cross-contract replay || validatorAddress // address: Binds to specific validator address || uint8(ingress.length) // uint8: Length of ingress || ingress // string: Binds network configuration || uint8(egress.length) // uint8: Length of egress || egress // string: Binds network configuration || feeRecipient // address: Binds fee recipients when proposing. ) rotateValidatorMessage = keccak256( bytes8(chainId) // uint64: Prevents cross-chain replay || contractAddress // address: Prevents cross-contract replay || validatorAddress // address: Binds to specific validator address || uint8(ingress.length) // uint8: Length of ingress || ingress // string: Binds network configuration || uint8(egress.length) // uint8: Length of egress || egress // string: Binds network configuration ) ``` The Ed25519 signature is computed over the operation-specific message with the namespace parameter (see commonware's [signing scheme](https://github.com/commonwarexyz/monorepo/blob/abb883b4a8b42b362d4003b510bd644361eb3953/cryptography/src/ed25519/scheme.rs#L38-L40) and [union format](https://github.com/commonwarexyz/monorepo/blob/abb883b4a8b42b362d4003b510bd644361eb3953/utils/src/lib.rs#L166-L174)). ## Compatibility And Upgrade Behavior ### Changes From V1 1. V2 preserves append-only history with irreversible deactivation instead of mutable active/inactive toggling. 2. V2 enforces stronger input checks in the precompile, including signature-backed key ownership. 3. V2 keeps validator index stable across lifecycle operations. ### Consensus Layer Read Behavior The Consensus Layer checks `v2.isInitialized()` to determine which contract to read: * **`initialized == false`**: CL reads from V1. * **`initialized == true`**: CL reads from V2. This read switch is implemented in CL logic. V2 does not proxy reads to V1. ## Consensus Layer Integration **IP address changes**: `setIpAddresses` is expected to take effect in CL peer configuration on the next finalized block. **Validator addition and deactivation**: there is no warmup or cooldown in V2. Added validators are added to the DKG player set on the next epoch; deactivated validators leave on the next epoch. (both in the case of successful DKG rounds; on failure DKG still falls back to its previous state, which might include validators that are marked inactive as per the contract). **Fee recipients**: Fee recipients are included now to be used in the future in a not yet determined hardfork. ### DKG Player Selection The consensus layer determines DKG players for epoch `E+1` by reading state at `boundary(E) - 1` and filtering: ``` players(E+1) = validators.filter(v => v.addedAtHeight < boundary(E) && (v.deactivatedAtHeight == 0 || v.deactivatedAtHeight >= boundary(E)) ) ``` This enables node recovery and late joining without historical account state. ## Migration from V1 On networks that start directly with V2 (no V1 state), `initializeIfMigrated` can be called immediately when the V1 validator count is zero. Because `SSTORE` cost is high under TIP-1000, migration is done one validator at a time to reduce out-of-gas risk on large sets. ### Full Migration Steps 1. At fork activation, the V2 precompile goes live. However, CL continues reading from the V1 precompile. 2. The owner calls `migrateValidator(n-1)` with `n` being the validator count in the V1 precompile. 3. On the first migration call, V2 copies owner from V1 if unset and snapshots the V1 validator count, then continues in descending index order. The snapshotted count is used for all subsequent index validation to prevent V1 mutations from breaking migration ordering. 4. After all indices are processed, owner calls `initializeIfMigrated()`, which flips `initialized` and activates CL reads from V2. ### Migration Edge Cases 1. **Validator goes offline during migration**: admin deactivates the validator in V1. If that index has already been migrated the admin will also deactivates it in V2. 2. **Invalid V1 entry encountered**: the index is still marked as processed (migrated, overwritten, or skipped by implementation rules) so global completion is not blocked. 3. **Zero validators in V1**: The migration flow requires at least 1 validator to be in the V1 precompile. 4. **Validator count overflow**: We use uint8s to cache the number of V1 validators and the number of skipped V1 validators. V1 currently has 14 validators, so a limit of 255 is sufficient. ### Permitted Calls During Migration | Contract | Caller | Allowed calls | | --- | --- | --- | | V2 (pre-init) | owner | `deactivateValidator`, `migrateValidator`, `initializeIfMigrated` | | V2 (pre-init) | validator | `deactivateValidator` (theoretically; in Tempo these addresses are unowned) | | V2 (post-init) | any | `migrateValidator` and `initializeIfMigrated` are blocked | | V1 (during migration window) | owner and validators | all V1 calls remain available (subject to V1 authorization and key ownership assumptions) | # Security ## Considerations * **Migration timing**: migration and `initializeIfMigrated()` should complete before an epoch boundary to avoid DKG disruption. * **Pre-migration validation**: admins should run a validation script against V1 state to detect entries that would fail V2 checks. * **State parity before init**: admins should verify V1/V2 state consistency before finalizing with `initializeIfMigrated()`. * **Signature domain separation**: signatures for `addValidator` and `rotateValidator` are bound to chain ID, precompile address, namespace, validator address, and endpoint payload. ## Race And Griefing Risks * Stable `index` values prevent races between concurrent state-changing calls. * Append-only history and permissionless rotation require query paths that remain safe as history grows. ## Testing Requirements Unit tests should cover all control-flow branches in added functions, including initialization gating, migration completion checks, and index-based query behavior under large validator sets. ## Invariants ### Identity and Uniqueness 1. **Unique active addresses**: No two active validators share the same `validatorAddress`. Deactivated addresses may be reused. 2. **Unique public keys**: No two validators (including deactivated) share the same `publicKey`. 3. **Ingress uniqueness across active validators**: In `getActiveValidators()`, no two validators share the same ingress `:`. 4. **Valid public keys**: All validators must have valid ed25519 `publicKey`s. ### Lifecycle and Storage Behavior 1. **Append-only validator array**: `validatorsArray` length can only increase. 2. **Entry index immutability**: Once a validator entry is created at index `i`, that entry can never move to another index. A previously deactivated operator may later be re-added as a new entry at a different index. 3. **Deactivate-once**: `deactivatedAtHeight` can only transition from 0 to a non-zero value, never back. 4. **Add increases exactly one entry**: A successful `addValidator` call increases `getActiveValidators().length` by exactly one. 5. **Rotation preserves active cardinality**: A successful `rotateValidator` call does not change `getActiveValidators().length`. 6. **Deactivation decrements active cardinality by one**: A successful `deactivateValidator` call decreases `getActiveValidators().length` by exactly one. ### Query Correctness 1. **Full-set reconstruction by index**: Reading `validatorByIndex(i)` for all `i` in `0..validatorCount()-1` must reconstruct exactly the ordered validator set. 2. **Validator activity consistency**: Filtering the reconstructed validator set by `deactivatedAtHeight == 0` must produce exactly `getActiveValidators()` (same members, order not important). 3. **Address round-trip for active entries**: For any `i` where `validatorByIndex(i).deactivatedAtHeight == 0`, `validatorByAddress(validatorByIndex(i).validatorAddress).index == i`. 4. **Public-key round-trip for all entries**: For any `i < validatorCount()`, `validatorByPublicKey(validatorByIndex(i).publicKey).index == i`. 5. **Index round-trip for all entries**: For any `i < validatorCount()`, `validatorByIndex(i).index == i`. ### Migration and Initialization 1. **Initialization phase gating**: Before initialization, post-init mutators are blocked; after initialization, migration mutators are blocked. 2. **Initialized once**: The `initialized` flag can only transition from `false` to `true`, never back. 3. **Migration completion gate**: Each V1 index must be processed exactly once (migrated or skipped), and `initializeIfMigrated()` stays blocked until all indices are processed. 4. **Skipped-index counter monotonicity**: `migrationSkippedCount` is monotonically non-decreasing and may only change during `migrateValidator`. 5. **DKG continuity at initialization**: On successful `initializeIfMigrated`, `getNextFullDkgCeremony()` in V2 equals the value read from V1 at that moment. 6. **Owner bootstrap during migration**: If V2 owner is unset on first migration call, owner is copied from V1 exactly once and then used for all migration authorization checks.