## Canonical Bridge Upgrade Checklist

This article outlines the **steps required** for the canonical bridge upgrade.

### Components:

**1. Smart Contract**

1. **Discussion Phase:**
1. Does the design **involve** only a single chain or both chains?
2. What are the affected components (including non-core contracts) after the upgrade?
3. If the event signature **is changed**, update the indexer, bridge validators, and bridge UI.
4. Is new contract needed?
2. **Development Phase:**
1. AMB -> [tokenbridge-contracts/master](https://github.com/gnosischain/tokenbridge-contracts/tree/master)
2. xDAI bridge -> [tokenbridge-contracts/xdaibridge](https://github.com/gnosischain/tokenbridge-contracts/tree/xdaibridge)
3. Omnibridge -> [omnibridge](https://github.com/gnosischain/omnibridge)
4. Framework:
* **Truffle:** **Deprecated**; only remains for original **code**.
* **Hardhat:** **Only** for Hashi-related components.
* **Foundry:** **Used** by all latest **development** (includ**ing** sDAI, USDS migration).
3. **Testing Phase:**
1. **Unit test:** **All** individual functions that are modified or added.
2. **Fork test:** **Ideal** for simulating a single-chain environment.
3. **Fuzzing test:** **Ideal** for checking edge cases.
4. **End-to-End test:** Critical for simulating the cross-chain environment. Can abstract away the bridge validator logic by creating a simple script at this phase.
5. **Testnet:** Deploy to Sepolia and Gnosis Chiado Chain for testnet testing. Alternatively, use Tenderly VirtualTestNet for xDAI bridge testing.
4. **Audit Phase:**
1. Defining audit scope:
1. Initial audit phase:
1. Smart contracts involved.
2. Latest GitHub commit.
3. Auditing timeline and cost.
2. Upgrade procedure validation:
1. Bytecode of the deployed contract matches the bytecode of the audited contract.
2. Parameters in the upgrade transaction match the expected upgrade procedure, including state changes, events, and balance changes.
3. Safe transaction metadata is correct, including Safe transaction hash, domain hash, and message hash. (Tool: [SafeUtils](https://safeutils.openzeppelin.com/)).
2. **Hosting** of audit report:
1. The audit report is uploaded by the auditor in public repository. [Example](https://github.com/OmegaAudits/audits/blob/main/202510-Gnosis-Bridge-USDS-Upgrade.pdf)
2. **Should** be available in [Gnosis Docs](https://docs.gnosischain.com/bridges/audits) and [relevant repository on Gnosis Chain](https://github.com/gnosischain/tokenbridge-contracts/tree/xdaibridge/docs).
3. Repository management:
1. Create a new PR.
2. Review and merge to the relevant branch.

---

**2. Bridge Validators**

1. **Code change process (if required):**
1. Development phase:
1. Repository: [tokenbridge/oracle](https://github.com/gnosischain/tokenbridge/tree/master/oracle)
2. Framework:
1. Node.js
2. Testing phase:
1. Unit test
2. Fork test
3. End-to-End test
3. Publish **a** new image to **Docker Hub**: [gnosischain/tokenbridge-oracles](https://hub.docker.com/r/gnosischain/tokenbridge-oracle/tags)
2. **Coordination with bridge validators:**
1. Publish an [instruction article](https://github.com/gnosischain/tokenbridge/blob/master/oracle/USDS_migration.md) for running **the** new **Docker** image with bridge validators.
2. Provide a testing environment for bridge validators if needed.
3. Verify and make sure all bridge validators are running the correct version before the upgrade.
4. Confirm availability with bridge validator in case there is downtime during the upgrade.

---

**3. Bridge Event Indexer**

1. if event signature is modified:
1. Modify indexer code.
2. Testing phase.
3. Release phase.

---

**4. Bridge UI**

1. **Defining scope:**
1. Which bridges and logic are modified?
2. How does the user flow change?
3. Does the indexer logic change?
2. **Development phase**
3. **Testing phase:**
1. Test changes on the dev branch.
4. **Release phase:**
1. **Branch flow:** develop -> staging -> production
2. Create a new release.
3. Deploy to production by DevOps.

---

**5. Communication Phase**

1. **Target audience:**
1. General users
2. 3rd-party applications
2. **Target channels:** Discord, X, Official Docs, Telegram, Farcaster, Slack, Gnosis Forum.
3. Create a draft article and coordinate with the communications/marketing team for the release date.
4. Nodify 3rd party bridges if event signature or entry point contract change.
5. Provide technical details on github for developers and users, includes integration guideline, contract workflow, deployed contract address. [Example](https://github.com/gnosischain/tokenbridge-contracts/blob/xdaibridge/USDSMigration.md)

---

**6. Bridge Governance**

1. **Create a governance proposal:**
1. Provide a clear explanation of the purpose of the bridge governance proposal, and relevant details for validation (i.e., technical documentation, audit report, transaction simulation).
2. Execute the governance proposal when the threshold of signatures is reached.
3. Update in Gnosis Chain Docs [governance decision](https://docs.gnosischain.com/bridges/management/decisions).