# Onchain Architecture - Upgradability (EVM)
Source: https://docs.chain.link/ccip/concepts/architecture/onchain/evm/upgradability
Last Updated: 2025-05-19

> For the complete documentation index, see [llms.txt](/llms.txt).

Chainlink Cross‐Chain Interoperability Protocol (CCIP) is designed to evolve in response to new emerging feature requests, security considerations, and the need to support additional blockchains over time. This requires a secure upgrade process that preserves CCIP's robust security while allowing for iterative improvements.

**Note**: The Router contract is intentionally immutable. It remains the primary user entry point on both source and destination blockchains—unmodifiable to preserve reliability, stability, and developer predictability over time.

## What Can Be Upgraded

Upgradability in CCIP primarily refers to two categories of changes:

1. **Onchain Configuration**
   - Many CCIP contracts expose public setter functions that can adjust operational parameters.
   - Since these parameters can be adjusted without requiring the redeployment of an entire contract, it offers a flexible way to help ensure CCIP's security and reliability over time.

2. **Redeploying Contracts and Redirecting References**
   - Once a smart contract is deployed, its code cannot be modified. If a new contract version (e.g., OnRamp, OffRamp, or Token Pool) is required, a new updated contract can be deployed, with all existing references updated to point to the new contract address.
   - For example, an OffRamp address might be updated in the Router or a local mapping so that new inbound messages go through the upgraded contract.
   - This approach ensures older versions remain stable while new versions can be phased in.

## Implementation Process

All onchain configuration changes must pass through a Role-Based Access Control Timelock (RBACTimelock) contract. This mechanism ensures that:

1. **Proposals**
   - All proposals originate from a ManyChainMultiSig (MCMS), which requires multiple independent signers to sign off.
   - Signers are selected from multiple high-quality Chainlink node operators with a proven, multi-year track record of securing billions in value within the Chainlink Network, as well as from Chainlink Labs.
   - Signers are also spread across multiple different geographic locations globally and may be rotated on a periodic basis to help mitigate potential risks as they arise, such as geographic concentration.
   - Two distinct paths exist for a proposal to succeed:
     - **Time-locked review:** Node operators securing CCIP can veto a proposal within a defined review period. If no veto occurs, the update proceeds.
     - **Explicit approval:** A quorum of independent signers (including node operators) actively endorse the proposal, allowing for urgent or time-sensitive fixes.

2. **Review and Veto Window**
   - During the timelock review period, CCIP node operators can inspect the onchain proposal (e.g., adjusting a rate limit) and reject it if it appears incorrect, preventing the proposal from being executed.

3. **Execution**
   - Once the timelock finishes (with no veto), the proposal transitions to an "executable" state.
   - Any party can call the timelock contract to finalize the proposal (e.g., via a [timelock-worker](https://github.com/smartcontractkit/timelock-worker) script).
   - The timelock then calls the target CCIP contracts with the specified changes.

4. **Public Verifiability**
   - Information about the MCMS, including the timelock configuration, signer set, and ongoing timelocked proposals are visible onchain.
   - For instance, the Ethereum mainnet MCMS can be viewed on [Etherscan](https://etherscan.io/address/0xE53289F32c8E690b7173aA33affE9B6B0CB0012F#readContract).
   - Anyone can track in-progress proposals, track any node operators vetos, and monitor the final execution status using onchain data.

## Additional Resources

- **[CCIP Owner Contracts - GitHub](https://github.com/smartcontractkit/ccip-owner-contracts)**: Further documentation and source code for the ManyChainMultiSig, timelock, and other related contracts.
- **[Etherscan: MCMS on Ethereum Mainnet](https://etherscan.io/address/0xE53289F32c8E690b7173aA33affE9B6B0CB0012F#readContract)**: Allows anyone to see the current configuration, pending proposals, and signer addresses on Ethereum.
- **[Timelock Worker Repo](https://github.com/smartcontractkit/timelock-worker)**: Demonstrates how to automate final execution for proposals that have cleared the timelock period.