Detailed Instructions

Begin by examining the official upgrade proposal and the associated code diff on GitHub. The primary risk is the introduction of new smart contract vulnerabilities or unintended interactions. Focus on changes to core logic, such as modifications to state variables, access control functions, or external calls. For a lending protocol upgrade, scrutinize changes to the interest rate model or liquidation logic. Use tools like Slither or Mythril for a preliminary static analysis of the new contract bytecode. Cross-reference the diff with the audit scope; any code outside the audited modules represents a higher risk.

• Sub-step 1: Clone the repository and check out the commit hashes for the pre- and post-upgrade versions.
• Sub-step 2: Run git diff <old_commit> <new_commit> -- contracts/ to isolate Solidity changes.
• Sub-step 3: Manually review high-risk diff sections, such as new delegatecall or low-level call operations.

solidityCopy
// Example: Check for new state variable layout which could cause storage collisions.
// Old contract storage slot 0:
uint256 public totalSupply;
// New contract storage slot 0:
address public newAdmin; // HIGH RISK: Storage collision risk if upgrade is not handled correctly.

Tip: Pay special attention to proxy upgrade patterns (Transparent vs. UUPS). A poorly implemented upgradeTo function is a critical failure point.

Detailed Instructions

Assess the credibility and depth of the security audits. A single audit is insufficient for a major upgrade. Look for audits from multiple reputable firms (e.g., Trail of Bits, OpenZeppelin, ConsenSys Diligence). The key metric is audit coverage, which should explicitly include the new and modified code paths. Check if the audit reports detail the severity of findings (Critical, High, Medium) and confirm that all Critical/High issues are resolved and verified. Furthermore, examine the protocol's public bug bounty program. A live bounty on Immunefi or HackerOne with a significant prize pool (e.g., $1M+ for Critical vulnerabilities) is a strong positive signal. Verify that the scope of the bounty explicitly covers the new upgrade contracts.

• Sub-step 1: Locate all audit reports linked in the governance forum or protocol documentation.
• Sub-step 2: Compare the commit hash in the audit report to the final upgrade code to ensure they match.
• Sub-step 3: Search the bug bounty platform for the project and note the maximum bounty amount and scope.

bashCopy
# Example command to verify a contract address is in the bug bounty scope on Immunefi
curl -s 'https://immunefi.com/api/project/[PROJECT_NAME]/' | jq '.scopes.in_scope[] | select(.type=="contract")'

Tip: Be wary of audits that are marked as "preliminary" or that have a large number of unresolved Medium-severity issues, as they indicate rushed due diligence.

Detailed Instructions

Use forked mainnet environments (e.g., via Foundry or Tenderly) to simulate the upgrade's impact under stress conditions. This step assesses economic risk. For a DEX upgrade changing fee structures or AMM curves, simulate large trades to check for unexpected slippage or LP impermanent loss. For a lending protocol, test new liquidation parameters (e.g., a lowered liquidation threshold) against historical price volatility to estimate potential bad debt. Parameterize your simulations using historical data from Dune Analytics or The Graph. The goal is to identify if the new parameters could trigger cascading liquidations or render certain positions unprofitable in common market conditions.

• Sub-step 1: Fork mainnet at the block before the upgrade using Foundry: anvil --fork-url $RPC_URL --fork-block-number 19238201.
• Sub-step 2: Deploy the new implementation contract to the fork and upgrade the proxy.
• Sub-step 3: Write a test script that replicates a 30% price drop for a major collateral asset and triggers the liquidation engine.

solidityCopy
// Foundry test example to simulate a price drop and check liquidation
function testLiquidationPostUpgrade() public {
    vm.roll(forkBlock + 100);
    // Set oracle price to 70% of original
    oracle.setPrice(collateralAsset, (oraclePrice * 70) / 100);
    // Attempt to liquidate a user position
    (bool success, ) = address(liquidationModule).call(calldata);
    assertTrue(success, "Liquidation failed under stress");
}

Tip: Compare the gas cost of key user actions (e.g., supply, swap, withdraw) before and after the upgrade. A significant increase can lead to network congestion failures.

Detailed Instructions

Scrutinize the governance process that approved the upgrade. A high voter turnout and a significant majority (e.g., > 70% for) from diverse delegates reduces the risk of a contentious hard fork. Check if the upgrade includes a timelock (minimum 48-72 hours), which allows for a last-minute cancel if issues are discovered. The most critical factor is the existence and clarity of a rollback plan. For proxy-based upgrades, this is typically a simple re-pointing to the old implementation. For immutable contracts or complex migrations, the plan must be explicit and tested. Verify if the protocol has a designated emergency multisig or pause guardian with the authority to halt the system, and review its signer composition for decentralization and security.

• Sub-step 1: Review the final governance proposal snapshot. Note the total voting power and the For/Against split.
• Sub-step 2: Inspect the timelock contract (e.g., 0x0...Timelock) for the scheduled upgrade transaction and its eta (execution timestamp).
• Sub-step 3: Locate the official rollback procedure in the project's documentation or emergency response GitHub repo.

bashCopy
# Example: Check a timelock queue for a pending upgrade transaction
cast call 0x0...Timelock "getTransactionId(address,uint256,bytes,bytes32,uint256)" \
    $target 0 $calldata $predecessor $timestamp

Tip: A lack of a tested rollback procedure or an overly centralized emergency multisig (e.g., 2/3 signers from the same company) significantly increases the risk of permanent fund loss.

Detailed Instructions

After the upgrade executes, real-time monitoring is essential. Set up alerts for key on-chain metrics that deviate from baseline. Use a service like DefiLlama, Tenderly Alerts, or custom OpenZeppelin Defender Sentinels. Critical metrics include: total value locked (TVL) outflow, unusual failure rates for common transactions, and the health of the protocol's reserves or backing ratio. Specifically, monitor for any unexpected pausing of core functions or activation of emergency modes. Watch governance forums and social media for user reports of failed transactions or lost funds. This phase confirms whether the risk assessment was accurate and determines if insurance coverage should be adjusted or claims may be imminent.

• Sub-step 1: Set up a Tenderly alert for TransactionReverted events on the upgraded contract addresses.
• Sub-step 2: Track the protocol's TVL on DefiLlama, alerting on a drop of >10% in the first hour post-upgrade.
• Sub-step 3: Monitor the contract's event logs for any Paused(address) or EmergencyModeActivated() events.

javascriptCopy
// Example Defender Sentinel to monitor for a critical function failure
// Condition: `withdraw` function calls that revert with a specific error.
module.exports = async function (txEvent) {
  const iface = new ethers.utils.Interface(ABI);
  const log = iface.parseLog(txEvent.receipt.logs[0]);
  if (log.name === 'WithdrawFailed' && log.args.errorCode === 'INSUFFICIENT_LIQUIDITY') {
    return true; // Trigger alert
  }
  return false;
};

Tip: Have a pre-prepared checklist of the first 10-20 transactions that should succeed post-upgrade (e.g., a small deposit and withdrawal) to perform an immediate functional test.

Detailed Instructions

First, you must verify that the protocol upgrade failure meets the specific coverage parameters defined in the insurance policy. This typically requires the upgrade to have been officially proposed, voted on, and executed, resulting in a functional failure or value loss.

• Sub-step 1: Review the policy's Coverage Scope Document to confirm the failed upgrade's contract addresses and failure modes are listed.
• Sub-step 2: Collect immutable evidence. This includes the failed upgrade proposal's on-chain transaction hash (e.g., 0x123...abc), the block number of execution, and the resulting error logs or revert messages.
• Sub-step 3: Document the quantifiable loss. Calculate the exact amount of assets locked, devalued, or lost due to the failure, referencing your wallet's pre- and post-upgrade state from a block explorer.

Tip: Use a service like Tenderly to replay the failed transaction and capture a precise trace of the error for your claim dossier.

Detailed Instructions

Claims are initiated on-chain to ensure immutability and transparency. You will call the submitClaim function on the insurance protocol's ClaimsManager contract.

• Sub-step 1: Locate the correct contract address for the active claims manager, which is often published on the protocol's documentation or governance forum.
• Sub-step 2: Prepare the function call with required parameters: your wallet address, the policy ID (uint256), the amount of loss (uint256), and the IPFS CID hash of your evidence dossier.
• Sub-step 3: Execute the transaction. Ensure you have sufficient ETH for gas, as this is a state-changing call. Monitor the transaction for success and save the resulting ClaimSubmitted event log.

solidityCopy
// Example interaction via ethers.js
const tx = await claimsManager.submitClaim(policyId, lossAmount, evidenceCID);
await tx.wait();

Tip: Submit the claim as soon as possible after the failure is confirmed, as there may be a time-bound claims window defined in the policy.

Detailed Instructions

After submission, your claim enters a public validation period (e.g., 7 days). During this time, the claim's details are open for scrutiny by policy underwriters or a designated claims assessor DAO.

• Sub-step 1: Monitor the claim's status on the protocol's dashboard or by querying the getClaimStatus(uint256 claimId) view function on the contract.
• Sub-step 2: Be prepared to provide additional context or proof if requested by assessors through the protocol's communication channels (e.g., a dedicated Discord channel or forum post linked to your claim ID).
• Sub-step 3: The validation logic may involve an on-chain vote by token-holding assessors. The voting contract address and proposal ID will be emitted in an event.

solidityCopy
// Querying claim status
(uint8 status, uint256 validationEnds) = claimsManager.getClaimStatus(myClaimId);
// status: 1=Pending, 2=UnderReview, 3=Approved, 4=Denied

Tip: Actively engage with assessors to clarify technical details; a well-documented claim with clear on-chain proof is more likely to be validated efficiently.

Detailed Instructions

Once the claim is approved, the payout process is typically automated but requires a final claimant action to trigger the transfer from the insurance pool.

• Sub-step 1: After the validation period ends with a successful vote, call the finalizeClaim(uint256 claimId) function on the ClaimsManager. This function checks the approved status and transfers the covered amount.
• Sub-step 2: The payout is usually sent in the native stablecoin of the policy (e.g., USDC) or the network's native gas token. Verify the received amount matches the approved claim amount minus any applicable deductible.
• Sub-step 3: Confirm the transaction and check your wallet balance. The contract should emit a ClaimPaid event containing the claim ID, recipient, and amount.

solidityCopy
// Finalizing an approved claim
function finalizeClaim(uint256 _claimId) external {
    require(claimStatus[_claimId] == Status.Approved, "Claim not approved");
    claimStatus[_claimId] = Status.Paid;
    uint256 payout = claimAmount[_claimId] - deductible;
    IERC20(payoutToken).transfer(claimant[_claimId], payout);
    emit ClaimPaid(_claimId, claimant[_claimId], payout);
}

Tip: There is often a time limit to finalize a claim after approval. If you do not call finalizeClaim, the payout may be forfeited back to the pool after a set period.