Foundational principles for designing and interacting with upgradeable derivatives contracts, focusing on security, governance, and user protection.
LABS
Guides
Upgradeable Smart Contracts in Derivatives Systems
Chainscore © 2025
core_concepts
Core Concepts for Upgradeable Derivatives
01
Proxy Patterns
Proxy patterns separate a contract's logic from its storage. The proxy contract holds the state and delegates function calls to a separate logic contract.
- Transparent Proxy: Uses an admin to manage upgrades, preventing function selector clashes.
- UUPS (EIP-1822): Upgrade logic is built into the implementation contract itself, reducing gas costs.
- This matters because it allows for fixing bugs and adding features without migrating user positions or liquidity.
02
Storage Layout Preservation
Storage layout refers to how variables are stored in contract memory slots. When upgrading, new variables must be appended to avoid corrupting existing data.
- Appending new variables after existing ones prevents storage collisions.
- Using structured storage libraries like
StorageSlotcan help manage layout. - This is critical for user safety; a corrupted layout can permanently lock funds or break contract logic.
03
Initialization and Constructors
Initializer functions replace constructors in upgradeable contracts, as constructors are not called when a proxy delegates to a new logic contract.
- An
initializefunction, protected by an initializer modifier, sets up initial state. - It must be called only once to prevent re-initialization attacks.
- For derivatives, this securely sets parameters like oracle addresses, fee rates, and asset whitelists.
04
Timelocks and Governance
Timelocks enforce a mandatory delay between a governance vote approving an upgrade and its execution.
- This delay gives users time to review code changes or exit positions if they disagree.
- Multi-signature wallets or DAOs typically hold the upgrade authority.
- For derivatives, this protects users from sudden, potentially malicious changes to pricing models or liquidation logic.
05
State Variable Gaps
Storage gaps are reserved, unused storage variables in base contracts that allow for future expansion without breaking inheritance chains.
- A common pattern is declaring a
uint256[50] __gapin a base contract. - This provides flexibility for child contracts to add new variables in subsequent upgrades.
- It's essential for complex derivatives systems where multiple facets (trading, lending, oracles) may need upgrades.
06
User Opt-Out Mechanisms
Opt-out mechanisms allow users to withdraw or settle their positions before an upgrade takes effect, preserving their right to exit.
- Contracts may implement a grace period where certain functions are paused, allowing only withdrawals.
- This is a critical trust-minimizing feature for perpetual futures or options vaults.
- It ensures users are not forced into a new, unaudited version of the protocol against their will.
Upgrade Pattern Implementations
Core Upgrade Architectures
Modern upgradeable smart contracts rely on a few foundational patterns that separate logic from state. The proxy pattern is the most common, where a lightweight proxy contract delegates all function calls to a separate logic contract. This allows the logic to be swapped without migrating user data. The Diamond Standard (EIP-2535) is a more advanced, modular approach, enabling a single proxy to delegate to multiple logic contracts (facets) for better upgrade granularity and reduced contract size limits. Transparent proxies and UUPS (EIP-1822) are two primary implementation standards that define the delegation mechanism and upgrade authorization.
Key Distinctions
- Transparent Proxy: Upgrade logic is managed in the proxy contract itself. Prevents clashes between admin and user calls but is slightly more gas-intensive.
- UUPS (Universal Upgradeable Proxy Standard): Upgrade logic is embedded in the implementation contract. This makes implementations slightly more complex but can reduce gas costs for users.
- Diamond Standard: Enables a proxy to map function selectors to multiple logic addresses, solving the 24KB contract size limit and allowing for selective, modular upgrades.
Implementing an Upgrade for a Derivatives Contract
Process for securely upgrading the logic of a live derivatives protocol using a proxy pattern.
1
Audit and Finalize the New Contract Logic
Prepare the upgraded contract version for deployment.
Detailed Instructions
Before deployment, the new contract logic must be rigorously vetted. This involves a comprehensive security audit by a reputable third-party firm to identify vulnerabilities in the upgrade's new features or modifications to existing logic, such as changes to margin calculations or liquidation mechanisms. Developers should write extensive unit and integration tests, ideally achieving 95%+ coverage, to ensure the new logic behaves as intended and does not break existing functionality. Finally, the contract bytecode should be verified on a block explorer like Etherscan for transparency.
- Sub-step 1: Deploy the new
DerivativesV2implementation contract to a testnet (e.g., Sepolia). - Sub-step 2: Run the full test suite against the new implementation address in a forked mainnet environment.
- Sub-step 3: Obtain and review the formal audit report, addressing all critical and high-severity findings.
solidity// Example: New function signature in DerivativesV2 function calculateFundingRateV2(address _market) public view override returns (int256) { // New, optimized logic for funding rate calculation }
Tip: Use
slitherormythrilfor automated static analysis as part of your internal review process.
2
Deploy and Initialize the New Implementation
Deploy the final logic contract and run its initializer.
Detailed Instructions
Deploy the audited contract to the mainnet. Because you are using a Transparent Proxy or UUPS pattern, this new contract is a standalone logic contract with no stored data. After deployment, you must call any initialization function required by the new logic. This is distinct from the proxy's initializer and sets up any new variables introduced in the upgrade. Crucially, you must verify that this function can only be called once to prevent re-initialization attacks. Record the new implementation address (e.g., 0x742d35Cc6634C0532925a3b844Bc9e...) for the next step.
- Sub-step 1: Deploy the
DerivativesV2contract using a secure, reproducible script (e.g., Foundry'sforge script). - Sub-step 2: Call the
initializeV2()function (or similar) with necessary parameters like new fee rates or guardian addresses. - Sub-step 3: Confirm the transaction succeeded and the contract's new state variables are set correctly.
solidity// Example deployment script snippet (Foundry) DerivativesV2 newImpl = new DerivativesV2(); newImpl.initializeV2(0.003e18, timelockAddress); // 0.3% new fee
Tip: Use a multisig or DAO treasury for the deployer account to enhance security.
3
Propose the Upgrade via Governance
Submit a formal proposal to change the proxy's pointer to the new logic.
Detailed Instructions
In a decentralized protocol, upgrading the proxy is a privileged operation typically governed by a token vote. You must create a proposal that calls the upgradeTo(address) function on the proxy admin contract (for Transparent Proxies) or on the proxy itself (for UUPS). The proposal should clearly specify the new implementation address, a link to the verified source code, audit reports, and a detailed description of changes impacting users (e.g., "Funding rate calculation updated to improve long-tail asset support"). A timelock is often used to delay execution, giving users time to react.
- Sub-step 1: Encode the calldata for the upgrade transaction (e.g.,
proxyAdmin.upgrade(proxyAddress, newImplAddress)). - Sub-step 2: Submit the proposal to the governance forum (e.g., Commonwealth) for community discussion.
- Sub-step 3: After feedback, create the formal on-chain proposal via Snapshot or the governor contract.
solidity// Example calldata for a Transparent Proxy upgrade bytes memory data = abi.encodeWithSignature("upgrade(address,address)", proxyAddress, newImplAddress); // This data is the payload of the governance proposal.
Tip: Ensure the proposal specifies a sufficiently long voting period and timelock delay (e.g., 3-7 days).
4
Execute the Upgrade and Verify Storage
Finalize the upgrade and confirm the system operates correctly.
Detailed Instructions
After the governance vote passes and the timelock delay expires, the upgrade transaction is executed. This changes the implementation slot in the proxy's storage to point to the new contract address. Immediately after execution, you must perform critical verifications. First, confirm the proxy's implementation() returns the new address. Next, run a series of read-only calls to ensure all existing user data (like positions and balances) is preserved and accessible through the new interface. Finally, execute a low-risk write transaction (e.g., a simulated trade) on a test account to confirm the new logic is active and functional.
- Sub-step 1: Execute the queued timelock transaction to perform the
upgradeTocall. - Sub-step 2: Call
proxy.implementation()and verify it matches the newDerivativesV2address. - Sub-step 3: Use a script to read key storage variables (e.g., total open interest) from before and after the upgrade to confirm integrity.
bash# Example: Cast call to verify implementation cast call <PROXY_ADDRESS> "implementation()(address)" # Should return 0x742d35Cc6634C0532925a3b844Bc9e...
Tip: Have a prepared emergency pause mechanism or rollback plan in case critical issues are discovered post-upgrade.
Upgrade Pattern Comparison for DeFi
Comparison of common upgrade patterns for derivatives protocol smart contracts.
| Feature | Proxy Pattern | Diamond Pattern | Data Separation |
|---|---|---|---|
Upgrade Gas Cost (avg) | ~45k gas | ~80k gas | ~25k gas |
Initial Deployment Cost | High | Very High | Medium |
Implementation Logic Limit | Single contract | Multiple facets | Single contract |
Storage Collision Risk | High | Managed via slots | None (separate) |
Admin Function Overhead | Centralized proxy admin | Diamond loupe/cut | Migration manager |
Time to Execute Upgrade | Single transaction | Multiple facet cuts | Data migration required |
Suitability for Complex Derivatives | Low | High | Medium |
Audit Complexity | Standard | High (facet interactions) | Medium (data flows) |
risk_management
Risk Management and Security
Critical considerations for securing upgradeable derivatives protocols, focusing on governance, access control, and vulnerability mitigation.
01
Timelock-Enforced Upgrades
Timelocks introduce a mandatory delay between a governance vote approving an upgrade and its execution. This creates a security-critical window for users and developers to review code changes, exit positions, or initiate a governance veto. For derivatives, this prevents sudden, unexpected changes to core pricing or liquidation logic that could be exploited.
02
Proxy Storage Collisions
A storage collision occurs when a new implementation contract's variable layout overwrites data from the previous version. In a derivatives vault, this could corrupt user balance mappings or oracle price data. Meticulous use of unstructured storage patterns or inherited storage gaps is required to ensure upgrade safety.
03
Governance Attack Vectors
Governance attacks target the upgrade mechanism itself, such as token whale manipulation or flash loan voting power attacks. A malicious upgrade could drain all collateral. Mitigations include multi-sig guardians for critical functions, progressive decentralization, and lower quorum requirements for security-related proposals versus feature changes.
04
Function Selector Clashing
Selector clashing happens when a function signature in the new implementation matches a different function in the old one, causing unintended behavior. In a complex derivatives system, this could mistakenly route a liquidate() call to a withdraw() function. Thorough testing and tools like slither-check-upgradeability are essential.
05
Implementation Contract Immutability
While the proxy is upgradeable, each deployed implementation contract should be immutable and thoroughly audited. Once an implementation is in use, any bug fix requires deploying a new contract and upgrading the proxy to point to it. This ensures a clean, verifiable history of all live logic versions.
06
Emergency Pause & Rollback
An emergency pause mechanism allows guardians to freeze system operations if a vulnerability is detected post-upgrade. A prepared rollback capability, storing the previous implementation address, enables a swift revert to a known-safe state. This is crucial for derivatives to prevent loss amplification during a crisis.
Governance and Upgrade Control
Understanding Upgrade Control
Governance is the system that decides when and how a smart contract can be upgraded. In derivatives protocols like Synthetix or dYdX, this is critical because the contracts manage user funds and complex financial logic. A bad upgrade could lead to fund loss or system failure.
Key Points
- Proposal Process: Changes start as formal proposals, often requiring a deposit. Community members discuss and vote on them.
- Voting Power: Voting weight is usually tied to a governance token (e.g., SNX for Synthetix). The more tokens you stake, the greater your influence.
- Timelocks: A successful vote does not enact the change immediately. A timelock period (e.g., 2-3 days) gives users time to react or exit if they disagree with the upgrade.
- Proxy Pattern: Most upgradeable systems use a proxy contract. The proxy holds the user's funds and logic, but points to a separate "implementation" contract that can be swapped via governance.
Example
When Synthetix governance votes to add a new synthetic asset, token holders vote. If the vote passes, a timelock begins. After the delay, a privileged function is called to update the proxy's target address to the new, audited contract version, enabling the new feature.
Frequently Asked Questions
The primary risks involve upgrade governance and storage collisions. A malicious or compromised governance contract can push a harmful upgrade, draining funds. Storage collisions occur when new variable declarations in an upgraded contract unintentionally overwrite existing data slots, corrupting state. For example, adding a new uint256 variable in the wrong position could overwrite a critical oracle price feed. Robust time-locks and multi-signature schemes on the proxy admin are essential to mitigate governance risk, while meticulous storage layout planning prevents collisions.