Merge branch 'main' into deploy-gateway

.gitignore

@@ -35,3 +35,5 @@ go/
 gocache/
 go.work*
 control/target/
+web/packages/operations/.env.polkadot
+web/packages/operations/.env.rococo

README.md

@@ -40,7 +40,7 @@ Integration tests for our local testnet. See [smoketest/README.md](https://githu
 
 We use the Nix package manager to provide a reproducible and maintainable developer environment.
 
-After [installing nix](https://nixos.org/download.html) Nix, enable [flakes](https://nixos.wiki/wiki/Flakes):
+After [installing nix](https://nixos.org/download.html) Nix, enable [flakes](https://wiki.nixos.org/wiki/Flakes):
 
 ```sh
 mkdir -p ~/.config/nix

contracts/src/interfaces/extensions/IERC20Metadata.sol

@@ -0,0 +1,29 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2024 Snowfork <[email protected]>
+// OpenZeppelin Contracts v4.4.1 (token/ERC20/extensions/IERC20Metadata.sol)
+
+pragma solidity ^0.8.23;
+
+import "../IERC20.sol";
+
+/**
+ * @dev Interface for the optional metadata functions from the ERC20 standard.
+ *
+ * _Available since v4.1._
+ */
+interface IERC20Metadata is IERC20 {
+    /**
+     * @dev Returns the name of the token.
+     */
+    function name() external view returns (string memory);
+
+    /**
+     * @dev Returns the symbol of the token.
+     */
+    function symbol() external view returns (string memory);
+
+    /**
+     * @dev Returns the decimals places of the token.
+     */
+    function decimals() external view returns (uint8);
+}

control/chopsticks/polkadot-asset-hub.yml

@@ -0,0 +1,12 @@
+endpoint: wss://statemint-rpc.dwellir.com
+mock-signature-host: true
+block: ${env.POLKADOT_ASSET_HUB_BLOCK_NUMBER}
+db: ./assethub.sqlite
+
+import-storage:
+  System:
+    Account:
+      - - - 5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY
+        - providers: 1
+          data:
+            free: 1000000000000000

control/chopsticks/polkadot-bridge-hub.yml

@@ -0,0 +1,12 @@
+endpoint: wss://polkadot-bridge-hub-rpc.dwellir.com
+mock-signature-host: true
+block: ${env.POLKADOT_BRIDGEHUB_BLOCK_NUMBER}
+db: ./bridgehub.sqlite
+
+import-storage:
+  System:
+    Account:
+      - - - 5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY
+        - providers: 1
+          data:
+            free: 1000000000000000

control/chopsticks/polkadot.yml

@@ -0,0 +1,14 @@
+endpoint: wss://polkadot-rpc.dwellir.com
+mock-signature-host: true
+block: ${env.POLKADOT_BLOCK_NUMBER}
+db: ./polkadot.sqlite
+
+import-storage:
+  System:
+    Account:
+      - - - 5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY
+        - providers: 1
+          data:
+            free: "10000000000000000000"
+  ParasDisputes:
+    $removePrefix: ["disputes"] # those can makes block building super slow

docs/.gitbook/assets/polkadot-asset-hub (1).yml

@@ -0,0 +1,12 @@
+endpoint: wss://statemint-rpc.dwellir.com
+mock-signature-host: true
+block: ${env.POLKADOT_ASSET_HUB_BLOCK_NUMBER}
+db: ./assethub.sqlite
+
+import-storage:
+  System:
+    Account:
+      - - - 5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY
+        - providers: 1
+          data:
+            free: 1000000000000000

docs/.gitbook/assets/polkadot-asset-hub.yml

@@ -0,0 +1,12 @@
+endpoint: wss://statemint-rpc.dwellir.com
+mock-signature-host: true
+block: ${env.POLKADOT_ASSET_HUB_BLOCK_NUMBER}
+db: ./assethub.sqlite
+
+import-storage:
+  System:
+    Account:
+      - - - 5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY
+        - providers: 1
+          data:
+            free: 1000000000000000

docs/.gitbook/assets/polkadot-bridge-hub.yml

@@ -0,0 +1,12 @@
+endpoint: wss://polkadot-bridge-hub-rpc.dwellir.com
+mock-signature-host: true
+block: ${env.POLKADOT_BRIDGEHUB_BLOCK_NUMBER}
+db: ./bridgehub.sqlite
+
+import-storage:
+  System:
+    Account:
+      - - - 5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY
+        - providers: 1
+          data:
+            free: 1000000000000000

docs/SUMMARY.md

@@ -36,9 +36,5 @@
 
 ## Runbooks
 
-* [Updating Snowbridge Pallets, BridgeHub & AssetHub Runtimes](runbooks/updating-snowbridge-pallets-bridgehub-and-assethub-runtimes.md)
-* [Initialize Ethereum light client with Forced Checkpoint](runbooks/initialize-ethereum-light-client-with-forced-checkpoint.md)
-* [Initial Deployment of Gateway Contracts](runbooks/initial-deployment-of-gateway-contracts.md)
-* [Halt Bridge in Case of Emergency](runbooks/halt-bridge-in-case-of-emergency.md)
-* [Contract Upgrades](runbooks/contract-upgrades.md)
-* [Run Relayers](runbooks/run-relayers.md)
+* [Contributing to Snowbridge](runbooks/updating-snowbridge-pallets-bridgehub-and-assethub-runtimes.md)
+* [Governance Updates](runbooks/governance-updates.md)

docs/runbooks/governance-updates.md

@@ -0,0 +1,52 @@
+# Governance Updates
+
+Snowbridge has several governance APIs that can only be executed using a democratic process via Polkadot OpenGov.
+
+These APIs include:
+
+* Updating the Gateway contract on Ethereum
+* Updating pricing parameters for fee calculations
+
+These APIs are available on the `EthereumSystem` pallet on BridgeHub. We have also developed a [tool](https://github.com/Snowfork/snowbridge/tree/main/control) for generating calls to these APIs.
+
+## Steps for initiating a governance update
+
+As an example, we will show how to upgrade the Gateway contract on Ethereum.
+
+### **Generate the preimage**
+
+Deploy the new gateway contract, and then generate a preimage for calling `EthereumSystem.upgrade`
+
+```bash
+snowbridge-preimage --format binary upgrade PARAMS > preimage.bin
+
+```
+
+### Test the update in chopsticks
+
+The `snowbridge-preimage` tool will also generate a helper script `chopsticks-execute-upgrade.js` to execute the update in simulated chopsticks environment.
+
+1. Run chopsticks and fork Polkadot, AssetHub, and BridgeHub, using these [configs](https://github.com/Snowfork/snowbridge/tree/main/control/chopsticks)
+
+```
+chopsticks xcm -r polkadot.yml -p polkadot-asset-hub.yml -p polkadot-bridge-hub.yml
+```
+
+2. Once the chopsticks environment has been initialized, connect to BridgeHub in Polkadot-JS, and execute the contents of `chopsticks-execute-upgrade.js` in the Polkadot-JS Javascript console.
+
+A more [complicated](https://hackmd.io/@vgeddes/B1dsexNx0) testing scenario would involve having to upgrade BridgeHub with new code, and then calling a governance API.
+
+### OpenGov
+
+The next step involves submitting the proposal to the Whitelisted Caller track in OpenGov.
+
+This actually involves two referendums:
+
+* A referendum on the Collectives chain where the technical fellowship vote to whitelist the preimage.
+* A public referendum on Polkadot where the general public vote to execute the whitelisted preimage.
+
+We use the tool [opengov-cli](https://github.com/joepetrowski/opengov-cli) to generate the various calls required to setup these referendums.
+
+```
+opengov-cli submit-referendum --proposal preimage.hex --network polkadot --track whitelisted-caller --after 100 --output-len-limit 100 --output AppsUiLink
+```