How to Track Upgrade Adoption

A successful smart contract upgrade is not complete when the code is deployed; it's complete when a critical mass of network participants adopts it. Tracking this adoption involves monitoring on-chain data to answer key questions: What percentage of total value or activity has migrated? Are major node operators or applications using the new contract? Are there unexpected forks or versions persisting? This data is essential for developers to gauge rollout success, for security teams to identify lingering risks on deprecated code, and for the community to verify the network's consensus state.

The primary method for tracking adoption is analyzing transaction data and contract calls. You need to monitor interactions with both the old and new contract addresses. Key metrics include: - Total Value Locked (TVL) migrated, often the most critical metric for DeFi protocols. - Transaction volume and count flowing through each version. - Unique user addresses interacting with the new contract. - Integration signals from major front-ends, wallets (like MetaMask), oracles (like Chainlink), and bridges. Tools like Dune Analytics, The Graph, and custom indexers are used to query and visualize this data across blocks.

For upgrades involving consensus clients or node software (e.g., Ethereum execution or consensus client updates), tracking shifts from on-chain contracts to network participation. Here, you monitor metrics like: - Node client distribution using networks like Ethernodes or client diversity dashboards. - Block production attribution to identify which client versions are successfully proposing and attesting to blocks. - Fork choice metrics to ensure the network is finalizing on the intended chain. A slow or stalled adoption curve for critical consensus upgrades can indicate coordination problems or technical hurdles for node operators.

Beyond raw metrics, qualitative and ecosystem tracking is vital. Monitor community channels (Discord, governance forums) for operator feedback on upgrade issues. Check if major infrastructure providers like Infura, Alchemy, or Blockdaemon have enabled support. Verify that block explorers (Etherscan), data indexes, and cross-chain messaging protocols (LayerZero, Wormhole) have updated their configurations to recognize the new contract addresses. This ecosystem-wide lens helps identify single points of failure or integration gaps that could fragment user experience.

Setting up effective tracking requires defining clear success benchmarks before the upgrade goes live. Determine your adoption thresholds: Is 75% of TVL migrated sufficient? Is 95% of block production from the new client required for network stability? Use dashboards to track progress against these goals in real-time. Publicly sharing these dashboards, as teams like Uniswap or Aave do during upgrades, builds transparency and trust, allowing the entire community to independently verify the upgrade's health and progression.

To track upgrade adoption, you must first understand the proxy pattern, the architectural standard for upgradeable smart contracts. Most major protocols, including OpenZeppelin's TransparentUpgradeableProxy and UUPS (EIP-1822), use a proxy contract that delegates calls to a separate logic contract. The proxy holds the state, while the logic contract holds the code. An upgrade involves deploying a new logic contract and updating the proxy's pointer. Your tracking tools will monitor the Upgraded event emitted by the proxy when this pointer changes.

You will need access to blockchain data. For comprehensive analysis, use a node provider like Alchemy, Infura, or QuickNode for reliable RPC access. To query historical events and contract states efficiently, you should use a blockchain indexing service. The Graph Protocol allows you to create subgraphs for custom event tracking, while platforms like Dune Analytics and Flipside Crypto provide SQL-based querying of decoded on-chain data, which is ideal for aggregating upgrade events across many contracts.

Familiarity with the EIP-1967 storage slot is crucial for direct verification. This standard defines specific storage slots where proxies store the address of the logic contract. You can read this slot directly using eth_getStorageAt via an RPC call. For a transparent proxy, the logic address is at slot 0x360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc. This allows you to programmatically verify the current implementation of any EIP-1967 compliant contract, serving as a ground truth check against indexed event data.

Set up a development environment with the necessary libraries. For JavaScript/TypeScript, install ethers.js v6 or viem for interacting with the blockchain. Use the OpenZeppelin Upgrades Plugins for Hardhat or Foundry to understand the upgrade process programmatically. For Python, web3.py is the standard. You'll use these to write scripts that fetch events, query storage slots, and calculate metrics like the percentage of wallets interacting with the new logic contract post-upgrade.

Finally, identify the specific contracts and events you need to monitor. You will require the proxy contract address and the ABI (Application Binary Interface), specifically the event signatures for upgrades. Common events include Upgraded(address indexed implementation) from OpenZeppelin's proxies. For a real-world example, to track Uniswap's governance upgrades, you would monitor the GovernorBravoDelegate proxy for ProposalCreated and ProposalExecuted events that signal a successful upgrade execution.

Tracking upgrade adoption is a critical operational task for developers, node operators, and governance participants. It involves monitoring the network to determine what percentage of nodes have successfully migrated to a new protocol version or activated a specific fork. This data is essential for assessing network health, coordinating hard forks, and ensuring security. Key metrics include the block height at which an upgrade activates, the validator set participation rate, and the total value secured (TVS) on the new chain. Tools like block explorers, node APIs, and dedicated dashboards provide this visibility.

The primary method for tracking is querying the network's consensus layer. For Ethereum clients like Geth or Erigon, you can check the node's version via the web3_clientVersion RPC call and compare it against a target. More importantly, monitor for the activation of specific fork blocks or epochs. For example, tracking the Dencun upgrade involved watching for EIP-4844 blob transactions on mainnet after epoch 269568. You can script this using the eth_getBlockByNumber method to inspect block headers for new fields like blobGasUsed and excessBlobGas.

For a broader network view, aggregate data from public endpoints is necessary. Services like Etherscan, Beaconcha.in, and Dune Analytics compile node version statistics and fork participation. You can also build custom dashboards by polling multiple nodes or using subgraphs for on-chain activity. A practical approach is to track the proportion of blocks produced using post-upgrade rules. If an upgrade introduces a new transaction type (like EIP-4844 blobs), monitoring the count of those transactions per block gives a direct signal of adoption by applications and users.

When tracking upgrades for smart contracts, the process differs. Adoption is measured by contract call volume and value locked migrating to new contract addresses. For a DeFi protocol upgrade, you would track the TVL in the new pool factory versus the old one. Use event logs: after a proxy contract is upgraded via upgradeTo(address), monitor for Upgraded(address) events. Then, trace all subsequent calls to the new implementation address. Tools like Tenderly or OpenZeppelin Defender can automate this monitoring and alert on specific function calls post-upgrade.

Long-term tracking involves analyzing economic indicators and governance signals. Observe staking derivatives (like stETH), governance token votes, and fee market changes post-upgrade. A successful upgrade should see stable validator participation, increased network usage if scalability improved, and no significant chain splits. Always cross-reference data from multiple independent sources to avoid relying on a single point of failure. Establishing these tracking practices is fundamental for managing risk and verifying the success of any network evolution.

Every Ethereum Virtual Machine (EVM) compatible node, including those on Layer 2s and other chains, exposes a standard set of JSON-RPC methods. The two most critical for upgrade tracking are web3_clientVersion and eth_protocolVersion. A call to web3_clientVersion returns a string identifying the specific client software (e.g., Geth, Erigon, Nethermind) and its exact version number. This is the primary signal for determining if a node has upgraded to a new hard-fork compatible release. The eth_protocolVersion method returns the Ethereum protocol version number, which typically increments with network upgrades.

To implement tracking, you need to build or use a crawler that connects to a list of node endpoints. For Ethereum mainnet, you can source node IPs from the public peer-to-peer (DHT) network or use services like Ethernodes. The crawler should periodically (e.g., every 4-6 hours) call web3_clientVersion on each node and record the response. It's crucial to handle timeouts and connection errors gracefully, as not all discovered nodes will be publicly accessible. The resulting dataset allows you to calculate the percentage of nodes running the new, old, or other client versions.

Analyzing the data requires understanding client naming conventions. A Geth response might look like Geth/v1.13.12-stable/linux-amd64/go1.21.5. The segment after the /v is the version. You would filter for versions equal to or greater than the minimum required for the upgrade (e.g., Geth v1.13.12 for the Dencun upgrade). You can then track adoption over time: (Upgraded Nodes / Total Reachable Nodes) * 100. This gives a concrete, node-based adoption metric, which is more reliable than proxy metrics like hash rate for Proof-of-Stake networks.

There are important limitations and considerations with this method. First, your sample must be representative. If you only crawl nodes from a single hosting provider or geographic region, your data will be skewed. Second, you cannot directly query the nodes of major centralized infrastructure providers like Infura or Alchemy, which power a significant portion of application traffic. Their adoption status must be tracked via public announcements or status pages. Finally, this method measures node operator adoption, which is a leading indicator but not the final word; the upgrade only activates at a specific block height, regardless of node readiness.

For practical implementation, here is a simple Python example using the web3.py library to check a single node's version:

pythonCopy
from web3 import Web3
w3 = Web3(Web3.HTTPProvider('https://mainnet.infura.io/v3/YOUR_KEY'))
try:
    client_version = w3.client_version
    print(f"Client Version: {client_version}")
except Exception as e:
    print(f"Error: {e}")

While this queries a hosted endpoint, the same client_version property is available when connecting to any standard JSON-RPC node. For bulk crawling, you would iterate this call over a list of node URLs using an asynchronous HTTP client.

To track upgrade adoption, you need to identify a specific, immutable on-chain signal that distinguishes upgraded nodes from legacy ones. This is often a new transaction type, a modified smart contract function call, or a distinct event log emitted by the upgraded protocol. For example, after Ethereum's EIP-1559 upgrade, you could track the new maxPriorityFeePerGas and maxFeePerGas fields in transactions, which replaced the old gasPrice. On a rollup like Optimism, adoption of a new fault proof system might be signaled by transactions calling a new precompile address.

Once you've identified the signal, use the block explorer's API to query historical data. Most explorers like Etherscan, Arbiscan, or Subscan offer public APIs. You would write a script to fetch blocks or transactions over a time range and filter for those containing the upgrade signal. Calculate the adoption rate as (Blocks with Signal / Total Blocks) * 100 over a given period. For a more nuanced view, track the signal's appearance in transaction volume or total value locked (TVL) in upgraded contracts, not just block count.

Here's a simplified Python example using the Etherscan-like API to find transactions using EIP-1559 fields, which indicates a post-upgrade client:

pythonCopy
import requests
API_KEY = 'YOUR_API_KEY'
BASE_URL = 'https://api.etherscan.io/api'

params = {
    'module': 'account',
    'action': 'txlist',
    'address': '0x...',
    'startblock': 12965000, # Block where EIP-1559 went live
    'endblock': 99999999,
    'sort': 'asc',
    'apikey': API_KEY
}

response = requests.get(BASE_URL, params=params).json()
if response['status'] == '1':
    txs = response['result']
    # Filter for EIP-1559 txs (have maxFeePerGas and maxPriorityFeePerGas)
    upgraded_txs = [tx for tx in txs if 'maxFeePerGas' in tx and 'maxPriorityFeePerGas' in tx]
    adoption_rate = len(upgraded_txs) / len(txs) * 100
    print(f"EIP-1559 adoption in queried txs: {adoption_rate:.2f}%")

When analyzing the data, look for the adoption curve's inflection points. A sharp initial increase often indicates coordinated validator upgrades, while a slow, steady climb suggests gradual user and dApp migration. Be aware of confounding factors: some legacy infrastructure (like certain RPC providers) may wrap old-style transactions in new fields, inflating adoption metrics. Always cross-reference with alternative data sources, such as node client version data from networks like Ethernodes or community-run dashboards, to validate your findings.

This method's strength is its objectivity—it uses the immutable ledger as its source. However, its limitation is that it only measures visible on-chain activity. It cannot measure the readiness of nodes that are not currently proposing blocks or the adoption by read-only infrastructure. For a complete picture, combine block explorer analysis with Method 1: Querying Node APIs to understand the full network state.

Monitoring consensus participation involves querying the blockchain's state to see what percentage of the active validator set is running the new client version and participating in consensus under the new rules. Unlike social signals or node counts, this metric directly measures the economic security of the upgrade. A low participation rate indicates that a significant portion of the network's stake is not yet prepared, signaling a high risk for a chain split if the upgrade activates. Tools like block explorers, node RPC endpoints, and dedicated dashboards (e.g., Ethereum's Fork Monitor) aggregate this data.

To check participation, you typically query the eth/v1/beacon/states/{state_id}/validators endpoint on a beacon node (for Ethereum) or similar consensus-layer API. Filter the response for validators with the expected fork_version in their status. The calculation is: (Validators on New Fork / Total Active Validators) * 100. A safe threshold for activation is often 80-90% participation, as this represents supermajority consensus. For example, during Ethereum's Dencun upgrade, trackers monitored the 0x04000000 version in validator messages to gauge adoption.

This method requires access to a synced node. You can run a simple script using a library like ethers.js or web3.py to poll the consensus client. The key is to check the data.root or fork field in block proposals and attestations. A sudden drop in participation after the upgrade epoch is a critical alert, potentially indicating a widespread client issue. Continuous monitoring of this metric, especially in the hours before and after the upgrade trigger, is essential for node operators and protocol developers to assess network stability and make informed decisions about proceeding.

Effectively tracking upgrade adoption requires a multi-faceted approach. You should combine on-chain data analysis from block explorers like Etherscan or The Graph with off-chain community signals from forums and governance platforms. For critical protocol upgrades, consider setting up automated alerts using services like Tenderly or OpenZeppelin Defender to monitor for specific contract events or function calls. This proactive monitoring helps you assess network health, security posture, and user sentiment following a major change.

To deepen your analysis, explore the specific metrics that matter for your use case. For a DeFi protocol, track the migration rate of total value locked (TVL) from the old contract to the new one. For an NFT project, monitor the percentage of holders who have interacted with the migration contract. For a governance token, analyze voter turnout and proposal execution related to the upgrade. Tools like Dune Analytics and Nansen are invaluable for building these custom dashboards that visualize adoption trends over time.

The landscape of smart contract upgrade patterns is still evolving. Stay informed by following the development of new standards like EIP-2535 Diamonds (modular proxy system) and EIP-1967 (standard proxy storage slots). Reviewing post-mortems and security analyses from firms like Trail of Bits or ConsenSys Diligence after major upgrades provides critical insights into real-world implementation risks. Continuously refining your tracking methodology is key to understanding the complex dynamics of decentralized system evolution.

Your next practical steps should be to: 1) Choose a primary data source (e.g., Dune, Covalent, direct RPC) for your target chain, 2) Identify the key proxy or beacon contract addresses for protocols you follow, 3) Script a basic query to fetch the implementation address and compare it to a known upgrade log, and 4) Join developer communities for specific protocols (e.g., Discord, Governance forums) to get early signals on upgrade proposals and timelines. Start with one protocol and expand your monitoring suite from there.