Repository navigation
O. Contract Upgrade Proposal Guide
This guide explains how to prepare and submit a Contract Upgrade proposal through Diamond UI and follow it through to execution. The proposal identifies a target contract and an encoded contract call; its description explains the intended change, while the address and calldata define the executable action.
On this page
- Overview and Requirements
- Preparing the Contract Call
- Submitting the Proposal
- Voting, Finalization, and Execution
- Calldata Reference and Tools
Contract Upgrade proposals use High Majority approval. The voting thresholds, proposal phases, fees, and execution rules are described in DAO Governance.
Before creating a proposal, prepare the target contract address, the relevant contract ABI, the function to call, and its arguments. Confirm that the proposed action is supported by the target contract and its governance permissions. Creating a proposal does not require ownership of a validator pool.
Use Diamond UI Mainnet for mainnet proposals. The separate Diamond UI Testnet is available for testing. Contract addresses and configuration must correspond to the selected network. Keep enough DMD in the submitting wallet for the applicable proposal fee and transaction gas fees.
Outstanding proposals from previous voting phases must be finalized before new proposals can be submitted. Any participant can finalize a proposal; finalization and execution are separate operations.
- Identify the target contract. Determine the address that the approved proposal will call. Depending on the upgrade mechanism, this may be an administrative contract or proxy rather than the new implementation address itself.
-
Select the exact function and arguments. Use the ABI and documentation for the intended target. Function names and argument types vary between contracts; a function such as
upgrade(address)is not a universal DMD upgrade method. - Encode the calldata. Use an ABI-aware tool to encode the selected function and its arguments as a hexadecimal string.
- Verify the encoded call. Decode the calldata with the same ABI and check that the function and every argument match the intended action. Confirm the target address separately: the calldata does not identify the contract to which it will be sent.
- Review the expected effect. Test or simulate the intended call in an appropriate environment, accounting for execution through the DAO and the target's access permissions. Successful encoding alone does not establish that the call is authorized or will execute successfully.
The proposal description should explain the purpose, affected contracts, expected outcome, and supporting technical material. Reviewers must be able to compare that explanation with the actual target and calldata. See Proposal Types.
- Open DAO in Diamond UI Mainnet and connect the submitting wallet to the intended network.
- During the proposal phase, select Create Proposal, then choose Contract Upgrade.
- Complete the proposal fields:
| Field | What to Provide |
|---|---|
| Title | A concise name for the proposed change. |
| Description | The intended action, rationale, expected effect, and relevant technical references. |
| Discussion URL | An optional link to the discussion or supporting review. |
| Contract Address | The target address that the approved proposal will call. |
| Contract Calldata | The verified, ABI-encoded function call and arguments. |
- Review the network, target address, calldata, description, and applicable proposal fee. Ensure that the executable action matches the description.
- Submit the proposal and confirm the transaction request in your wallet. Network gas fees are separate from the proposal fee.
- After the transaction is processed, open the proposal and verify the recorded details. Share its link and supporting material for review before voting.
Submission records the proposal; it does not execute the contract call. The proposal proceeds through the following stages:
| Stage | What Happens |
|---|---|
| Voting | Eligible validator pool owners vote during the voting phase. Contract Upgrade proposals must meet the High Majority requirements. |
| Finalization | After voting ends, any participant can finalize the proposal to record the result and settle the proposal fee. An accepted proposal still requires execution. |
| Execution | The proposer initiates execution of an accepted, finalized Contract Upgrade proposal within the permitted window. The target call must also satisfy its execution conditions. |
Under the mainnet schedule described in Proposal Lifecycle and Fees, the execution window covers the following proposal and voting phases, totaling 28 days. An accepted proposal cannot be executed after its window expires.
After execution, check the transaction result and the affected contract state to confirm that the intended change took effect. For the general interface workflow, see the DAO Proposal and Voting Guide.
For a standard ABI-encoded function call, calldata consists of a 4-byte function selector followed by the encoded arguments. The selector is derived from the first four bytes of the Keccak-256 hash of the canonical function signature. This signature includes the function name and parameter types, without argument names or spaces; for example, upgrade(address).
In standard ABI encoding, an address is a 20-byte value encoded in a 32-byte word. Dynamic arguments such as strings and byte arrays use offsets, lengths, and padding. Use an ABI encoder rather than manually concatenating these values. The Solidity ABI Specification provides the complete encoding rules.
ABI-aware libraries such as Ethers.js and Web3.js, and development environments such as Remix and Hardhat, can support call preparation and testing. Use the API and documentation for the installed tool version. A graphical interface can simplify data entry, but the target address, ABI, function, arguments, and execution permissions still require technical review.
