gnosischain
diff --git a/‎docs/bridges/About Token Bridges/amb-bridge.md
Lines changed: 23 additions & 12 deletions b/‎docs/bridges/About Token Bridges/amb-bridge.md
Lines changed: 23 additions & 12 deletions
diff --git a/‎docs/bridges/About Token Bridges/hashi-integration.md
Lines changed: 29 additions & 0 deletions b/‎docs/bridges/About Token Bridges/hashi-integration.md
Lines changed: 29 additions & 0 deletions
diff --git a/‎docs/bridges/About Token Bridges/omnibridge.md
Lines changed: 23 additions & 14 deletions b/‎docs/bridges/About Token Bridges/omnibridge.md
Lines changed: 23 additions & 14 deletions
diff --git a/‎docs/bridges/About Token Bridges/usds-xdaibridge-migration.md
Lines changed: 157 additions & 0 deletions b/‎docs/bridges/About Token Bridges/usds-xdaibridge-migration.md
Lines changed: 157 additions & 0 deletions
@@ -80,9 +80,9 @@ Due to the light client finality requirements (at least 23mins on Ethereum), the
 
 ### Terminology
 
-- **Home (Native) Network**: Of the two networks being bridged between, the home or native network is the one with fast and inexpensive operations. All bridge operations to collect validator confirmations are performed on this side of the bridge. It is the Gnosis Chain in this case.
-- **Foreign Network**: Can be any EVM chain, generally it refers to Ethereum.
-- **Originating Contract**: An arbitrary contract where the message originates, typically this is where the user interacts and requests for a function to be invoked on another network.
+- **Home (Native) Network**: Gnosis Chain.
+- **Foreign Network**: Ethereum.
+- **Originating Contract**: An arbitrary contract where the message originates, typically this is where the user interacts and requests for a function to be invoked on another network. For example, Omnibridge is the originating contract that use AMB contract as data messaging layer.
 
 ### Call a cross-chain method via AMB:
 
@@ -100,21 +100,32 @@ function requireToPassMessage (address _contract,
 
 ![](/img/bridges/diagrams/amb-bridge-contract-flow.png)
 
-#### Foreign Network to Home Network
+#### Ethereum to Gnosis Chain
 
 1. User calls `foo()` on the originating contract
-2. Originating contract calls [`requireToPassMessage()`](https://etherscan.io/address/0x4C36d2919e407f0Cc2Ee3c993ccF8ac26d9CE64e#writeProxyContract#F10) on Foreign Bridge contract, and encodes `foo()`, target address, and gas limit used on the other chain for executing a message.
-3. `UserRequestForAffirmation` event is emitted, and listening validators relay the message to the Home side where signatures are collected
-4. [`executeAffirmation()`](https://gnosisscan.io/address/0x75Df5AF045d91108662D8080fD1FEFAd6aA0bb59#writeProxyContract#F15) is called on the Home Bridge contract by a validator once enough signatures are collected.
-5. Home bridge contract decodes the message and calls `foo()` on the target contract.
+2. Originating contract calls [`requireToPassMessage()`](https://etherscan.io/address/0x4C36d2919e407f0Cc2Ee3c993ccF8ac26d9CE64e#writeProxyContract#F10) on [Foreign AMB contract](https://etherscan.io/address/0x4C36d2919e407f0Cc2Ee3c993ccF8ac26d9CE64e#writeProxyContract), and encodes `foo()`, target address, and gas limit used on the other chain for executing a message.
+3. `UserRequestForAffirmation(bytes32 indexed messageId, bytes encodedData)` event is emitted from [Foreign AMB contract](https://etherscan.io/address/0x4C36d2919e407f0Cc2Ee3c993ccF8ac26d9CE64e#writeProxyContract), and listening bridge validators relay the message to the Home side where signatures are collected by calling Home AMB `executeAffirmation(bytes message)`, where `message` parameter is the `encodedData` from `UserRequestForAffirmation` event. Hashi acts as an additional bridge valdiator who validates transactions but no actually calling `executeAffirmation` on Home AMB. For more details about how Hashi works in this case, check out [here](./hashi-integration.md)
+4. Once enough signatures has been collected by bridge valdiators, the transaction will emit `CollectedSignatures (address authorityResponsibleForRelay, bytes32 messageHash, uint256 NumberOfCollectedSignatures)` and calls `foo()` on the target contract.
 
-#### Home Network to Foreign Network
+#### Gnosis Chain to Ethereum
 
 1. User calls `foo()` on an originating contract
 2. Originating contract calls [`requireToPassMessage()`](https://gnosisscan.io/address/0x75Df5AF045d91108662D8080fD1FEFAd6aA0bb59#writeProxyContract#F14) on Home Bridge contract, and encodes `foo()`, target address, and gas limit used on the other chain for executing a message.
-3. Signatures are collected from validators by calling [`submitSignatures()`](https://gnosisscan.io/address/0x75Df5AF045d91108662D8080fD1FEFAd6aA0bb59#writeProxyContract#F5), and once enough are collected `CollectedSignatures()` event is emitted.
-4. Message is relayed to the Foreign Bridge contract, and [`executeSignatures()`](https://etherscan.io/address/0x4C36d2919e407f0Cc2Ee3c993ccF8ac26d9CE64e#writeProxyContract#F3) is called
-5. Foreign bridge contract decodes the message and calls `foo()` on target contract
+3. Signatures are collected from validators by calling [`submitSignatures()`](https://gnosisscan.io/address/0x75Df5AF045d91108662D8080fD1FEFAd6aA0bb59#writeProxyContract#F5), and once enough are collected `CollectedSignatures()` event is emitted. Hashi acts as an additional bridge valdiator who validates transactions but no actually calling `executeAffirmation` on Home AMB. For more details about how Hashi works in this case, check out [here](./hashi-integration.md)
+4. Anyone can execute the call by calling [`executeSignatures(bytes message, bytes signatures)`](https://etherscan.io/address/0x4C36d2919e407f0Cc2Ee3c993ccF8ac26d9CE64e#writeProxyContract#F3) on Foreign AMB. To fetch the calldata for `executeSignatures` function, please follow the [guideline below](#how-to-call-executesignatures-on-foreign-amb-ethereum).
+5. Foreign AMB contract decodes the message and calls `foo()` on target contract
+
+
+### How to call executeSignatures on Foreign AMB (Ethereum)
+
+When the transaction is initiated from Home Network (Gnosis Chain), one has to claim the transaction on Ethereum explicitly. Here is how you can fetch the calldata required to call Foreign AMB to claim the transaction.
+
+1. Find the originating transaction on Gnosis Chain that interact with the Home AMB, and look for `UserRequestForSignature(bytes32 indexed messageId, bytes encodedData)`. [Example](https://gnosisscan.io/tx/0x946d5a926b4e6c55b51eae53b6fea118d7d4fd5ebfa44d6256ef4ce7b4d927be#eventlog)
+   ![](../../../static/img/bridges/amb-userrequestforsignature.png)
+2. Go to [AMB Helper contract](https://gnosisscan.io/address/0x7d94ece17e81355326e3359115D4B02411825EdD#readContract) on Gnosis Chain, paste the `encodedData` from `UserReqeustForSignature` into `getSignatures(bytes _message)` (the message starts with 0x0005). Fetch the return value from `getSignatures`.
+   ![](../../../static/img/bridges/amb-getsignatures.png)
+3. On Foreign AMB, call `executeSigantures(bytes _data, bytes _signatures)`, where `_data` is the `encodedData` from `UserRequestForSignature` and `_signatures` is from the return value of `getSignatures` method. Please make sure that the caller account has enough ETH for the gas fee.
+
 
 ### How to check if AMB is down (not relaying message)
 
 
@@ -82,6 +82,35 @@ For Omnibridge / AMB:
 3. If Hashi is enabled & mandatory, off chain executor calls Ethereum’s Yaru.executeMessages(), which check if the hash is agreed upon adapters and set isApprovedByHashi(messageId) to true eventually.
 4. User claims token by calling Ethereum’s ForeignxDAIBridge.executeSignatures(). DAI is transfer to the receiver eventually.
 
+# Hashi Manager contract
+
+Hashi Manager contract is the contract that controls the Hashi oracle and relevant information.
+
+<Tabs>
+<TabItem value="amb" label="AMB">
+
+| Contract                      | Address                                                                                                                |
+| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| Hashi Manager on Ethereum     | [0x93f6eE78451AaCc1Db1db49a12aBfCc4662B9Cc9](https://etherscan.io/address/0x93f6eE78451AaCc1Db1db49a12aBfCc4662B9Cc9)  |
+| Hashi Manager on Gnosis Chain | [0x74CACae9801bA4Fe0027Ed6F58d53797CCa7296E](https://gnosisscan.io/address/0x74CACae9801bA4Fe0027Ed6F58d53797CCa7296E) |
+
+</TabItem>
+
+<TabItem value="xdai" label="xDai">
+
+| Contract                      | Address                                                                                                                |
+| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| Hashi Manager on Ethereum     | [0x9acCFAD714A1e670CD1f6dc666FE892d1d5547BD ](https://etherscan.io/address/0x9acCFAD714A1e670CD1f6dc666FE892d1d5547BD) |
+| Hashi Manager on Gnosis Chain | [0x60Aa15198a3AdfC86FF15B941549A6447B2dDB49](https://gnosisscan.io/address/0x60Aa15198a3AdfC86FF15B941549A6447B2dDB49) |
+
+</TabItem>
+</Tabs>
+
+1. Set the oracle sets (reporter address from source chain, adapter address on target chain) for certain route (i.e. Ethereum -> Gnosis Chain, Gnosis Chain -> Ethereum).
+2. Set the target address: the bridge contract on the target chain.
+3. Set exepected adapter hash: the adapter address on the same chain.
+4. Set Yaho, Yaru: For message relaying and executing logic. Check out how it works [here](https://crosschain-alliance.gitbook.io/hashi/getting-started/how-hashi-works)
+
 ## Reference
 
 1. AMB contracts: https://github.com/crosschain-alliance/tokenbridge-contracts/tree/feat/hashi-integration-amb
 
@@ -133,6 +133,13 @@ Daily Limit is reset according to the following logic: the smart contract stores
 </details>
 ```
 
+
+### Terminology
+
+- **Home (Native) Network**: Gnosis Chain.
+- **Foreign Network**: Ethereum.
+- **Mediator Contract**: Omnibridge contract, built on top of AMB.
+
 ### Bridge Validators
 
 - See [Bridge Validator](../management/validators#amb--omnibridge)
@@ -143,18 +150,20 @@ Daily Limit is reset according to the following logic: the smart contract stores
 
 ## How it works
 
+The Omnibridge is built on top of the [Arbitrary Message Bridge](./amb-bridge.md).
+
 ### Ethereum -> Gnosis
 
 ![](/img/bridges/diagrams/token-bridge-01.png)
 
 1. User `approve` Omnibridge as token spender.
-2. User call `relayTokens()` on Mediator contract.
-3. Mediator calls `requireToPassMessage()` on the Bridge.
-4. `UserRequestForAffirmation` event is emitted for validators to validate the message.
-5. Message is relayed to the mediator contract when consensus is met by calling `executeAffirmation()`.
-6. ABM calls mediator on Gnosis chain:
-   - token does not exist: the mediator deploys a new token registry and mints the relayed amount.
-   - token exists: the relayed amount is minted in the token address.
+2. User call `relayTokens()` on [Foreign Omnibridge contract](https://etherscan.io/address/0x88ad09518695c6c3712AC10a214bE5109a655671#writeProxyContract).
+3. Omnibridge contract calls Foreign AMB `requireToPassMessage()`.
+4. `UserRequestForAffirmation` event is emitted from Foreign AMB and `TokensBridgingInitiated(address indexed token, address indexed sender, uint256 value, bytes32 indexed messageId)` event is emitted from Foreign Omnibridge.
+5. Message is relayed to the Omnibridge contract when bridge validator threshold is met by calling [Home AMB](https://gnosisscan.io/address/0x75Df5AF045d91108662D8080fD1FEFAd6aA0bb59#writeProxyContract)`executeAffirmation()` on Gnosis Chain.
+6. AMB calls [Omnibridge on Gnosis chain](https://gnosisscan.io/address/0xf6A78083ca3e2a662D6dd1703c939c8aCE2e268d#writeProxyContract):
+   - token does not exist: the Omnibridge deploys a new token registry and mints the relayed amount.
+   - token exists: the relayed Omnibridge is minted in the token address.
 
 ---
 
@@ -164,15 +173,15 @@ Daily Limit is reset according to the following logic: the smart contract stores
 
 1. User calls `transferAndCall` on ERC-677 token contract to send tokens to Omnibridge contract
 2. `OnTokenTransfer` is called
-3. Mediator contract burns tokens and calls bridge contract's `requireToPassMessage()` function.
+3. Home Omnibridge contract burns tokens and calls bridge contract's `requireToPassMessage()` function.
 4. `UseRequestForSignature` event is emitted for validators to validate the message.
 5. Validators listen to the event: call `submitSignature` on Gnosis chain.
-6. `CollectedSignatures` event is emitted when consensus is met.
-7. User calls AMB (Ethereum side) `executeSignatures()`
-8. ABM calls `handleBridgedTokens()` on Mediator.
-9. Mediator contract unlocks the tokens
 
-The Omnibridge is built on top of the [Arbitrary Message Bridge](./amb-bridge.md).
+6. `CollectedSignatures` event is emitted when enough bridge validator's signature is collected.
+7. User calls AMB `executeSignatures()` on Ethereum. To fetch the calldata for the function, please check [guideline here](./amb-bridge.md#how-to-call-executesignatures-on-foreign-amb-ethereum)
+8. AMB calls `handleBridgedTokens()` on Foreign Omnibridge contract.
+9. Foreign Omnibridge contract unlocks the tokens.
+
 
 ## Exceptions and Special Cases
 
@@ -231,7 +240,7 @@ A partial token list of inflationary tokens is included below:
 
 Additional References:
 
-- [GIP-31: Hardfork that removed `transferAfterCall` from Bridged Token methods](https://forum.gnosis.io/t/gip-31-should-gnosis-chain-perform-a-hardfork-to-upgrade-the-token-contract-vulnerable-to-the-reentrancy-attack/413) (also see [writeup](https://hackmd.io/@koal/SJiDiO0bc))
+- [GIP-31: Hardfork that removed `transferAfterCall` from Bridged Token methods](https://forum.gnosis.io/t/gip-31-should-gnosis-chain-perform-a-hardfork-to-upgrade-the-token-contract-vulnerable-to-the-reentrancy-attack/4134) (also see [writeup](https://hackmd.io/@koal/SJiDiO0bc))
 
 ### Canonical Token Registries
 
 
@@ -0,0 +1,157 @@
+---
+title: xDai Bridge - USDS migration
+sidebar_position: 5
+description: Replacing DAI to USDS as collateral on Foreign xDAI bridge
+keywords: [xdai bridge, bridge, dai, ethereum, gnosis bridge]
+---
+
+# USDS migration on xDai Bridge
+
+:::danger
+
+The bridge migration has not yet taken place.  
+Please prepare for the upcoming upgrade by switching the entry point contract from xDAI Foreign Bridge to Bridge Router contract.
+:::
+
+## 1. General Overview
+
+- **What changed?**
+
+  - The [xDAI bridge on Ethereum](https://etherscan.io/address/0x4aa42145Aa6Ebf72e164C9bBC74fbD3788045016) no longer accepts DAI as collateral. It now uses [USDS](https://etherscan.io/address/0xdC035D45d973E3EC169d2276DDab16f1e407384F).
+  - On Gnosis Chain, users still receive xDAI as usual.
+
+- **Why it matters?**
+
+  - Any application sending or claiming DAI must adapt to the new USDS flows.
+  - To send or claim tokens, you interact with the **BridgeRouter** contract, which directs transactions to the right bridge logic.
+
+- **When will it happen?**
+  - **The exact date for the migration is to be determined** and will be anounced in our comms channel (X, Discord, Telegram, Gnosis Docs).
+  - Before the migration happen, third party applications are given **1 month**(June 8, 2025) to adapt to the changes by switching the entry point contract to Bridge Router.
+
+---
+
+## 2. Key Contracts & Addresses
+
+| Contract                 | Chain    | Address                                                                                                                 |
+| ------------------------ | -------- | ----------------------------------------------------------------------------------------------------------------------- |
+| **BridgeRouter (Proxy)** | Ethereum | [`0x9a873656c19Efecbfb4f9FAb5B7acdeAb466a0B0`](https://etherscan.io/address/0x9a873656c19Efecbfb4f9FAb5B7acdeAb466a0B0) |
+| BridgeRouter Impl.       | Ethereum | [`0x691c025Efa7ea1c87DF256F2Da9208E5345D40b1`](https://etherscan.io/address/0x691c025Efa7ea1c87DF256F2Da9208E5345D40b1) |
+
+---
+
+## 3. Technical Details
+
+:::info
+Please refer to [here](https://github.com/gnosischain/tokenbridge-contracts/blob/feat/xdai-usds-migration/USDSMigration.md) for details regarding the contracts, workflow pre & post migration.
+:::
+
+**How it works after the migration**
+
+**Relay tokens**
+![](../../../static/img/bridges/xdaibridge/bridge-router-relay-token.svg)
+
+**Claim tokens**
+![](../../../static/img/bridges/xdaibridge/bridge-router-claim-token.svg)
+
+**Scenarios**
+
+1. `BridgeRouter.relayTokens(address token, address recipient, uint256 amount)`  
+   -> When token is DAI / USDS from Ethereum, receive xDAI on GC.  
+   -> When token is other tokens from Ethereum, receive the bridged version token on GC.
+2. `BridgeRouter.executeSignatures(bytes memory message, bytes memory signatures)`  
+   -> claim DAI on Ethereum
+3. `BridgeRouter.executeSignaturesUSDS(bytes memory message, bytes memory signatures)`  
+   -> claim USDS on Ethereum
+4. `BridgeRouter.safeExecuteSignaturesWithAutoGasLimit(bytes memory message, bytes memory signatures)`  
+   -> claim token from Omnibridge
+5. `xDAIForeignBridge.relayTokens(address recipient, uint256 amount)`  
+   -> relay USDS from Ethereum, receive xDAI on GC
+6. `xDAIForeignBridge.executeSignatures(bytes memory message, bytes memory signatures)`  
+   -> claim DAI on Ethereum
+7. `xDAIForeignBridge.executeSignaturesUSDS(bytes memory message, bytes memory signatures)`  
+   -> claim USDS on Ethereum
+
+### 3.1 How to Relay Tokens
+
+1. **Approve** the BridgeRouter to spend your token:
+
+   ```solidity
+   // if sending DAI or USDS:
+   IERC20(token).approve(BridgeRouterAddress, amount);
+   ```
+
+2. **Call** `relayTokens` on BridgeRouter:
+
+   ```solidity
+   BridgeRouter.relayTokens(
+     address token,            // address of DAI or USDS
+     address recipient, // who receives xDAI on Gnosis Chain
+     uint256 amount            // how much to send
+   );
+   ```
+
+- **What happens inside?**
+
+  - If `token` is DAI: it's converted to USDS, then locked in xDAI Foreign Bridge cotntracts.
+  - If `token` is USDS: it's locked in xDAI Foreign Bridge cotntracts directly.
+  - If `token` is any other ERC20 or ETH: it goes through Omnibridge as before.
+
+---
+
+### 3.2 How to Claim Tokens
+
+Once your tokens have been initiated from Gnosis Chain, you can claim them back on Ethereum:
+
+- **Claim DAI:**
+
+  ```solidity
+  BridgeRouter.executeSignatures(message, signatures);
+  ```
+
+  - Always returns DAI.
+
+- **Claim USDS (new):**
+
+  ```solidity
+  BridgeRouter.executeSignaturesUSDS(message, signatures);
+  ```
+
+  - Only works after the upgrade; [reverts](https://github.com/gnosischain/tokenbridge-contracts/blob/feat/xdai-usds-migration/contracts/upgradeable_contracts/erc20_to_native/BridgeRouter.sol#L105) before.
+
+- **Other tokens:**
+
+  ```solidity
+  BridgeRouter.safeExecuteSignaturesWithAutoGasLimit(message, signatures);
+  ```
+
+  - Same process as before via Omnibridge.
+
+- To fetch the `message` and `signatures` parameters, please check the guide for xDai Bridge [here](./xdai-bridge.md#how-to-claim-dai-on-ethereum), for AMB/Omnibridge [here](./amb-bridge.md#how-to-call-executesignatures-on-foreign-amb-ethereum).
+
+---
+
+## 4. Next Steps
+
+- **Update your code**:
+
+  - Replace direct xDAI Foreign bridge calls with **BridgeRouter** methods (`relayTokens`, `executeSignatures`, `executeSignaturesUSDS`).
+
+- **Monitor migration**:
+
+  - Ensure you use `executeSignaturesUSDS` only once the upgrade is live.
+
+### 4.1 How to test with post migration environment
+
+To simulate the actual mainnet environment, we use Tenderly Virtual TestNets for both Ethereum and Gnosis Chain. Third-party applications are encouraged to use the following RPC endpoints to simulate the post-migration environment.
+
+Switch your RPC:
+
+| Chain        | Description | URL                                                                                           |
+| ------------ | ----------- | --------------------------------------------------------------------------------------------- |
+| Ethereum     | RPC         | https://virtual.mainnet.rpc.tenderly.co/f7d3ce08-c1ea-42da-87f1-4a40f335dda9                  |
+| Ethereum     | Explorer    | https://dashboard.tenderly.co/explorer/vnet/f7d3ce08-c1ea-42da-87f1-4a40f335dda9/transactions |
+| Gnosis Chain | RPC         | https://virtual.gnosis.rpc.tenderly.co/c9ef8faf-bac8-40d0-8530-ded119b8012a                   |
+| Gnosis Chain | Explorer    | https://dashboard.tenderly.co/explorer/vnet/c9ef8faf-bac8-40d0-8530-ded119b8012a/transactions |
+
+If you run into any issues or have any questions, please reach out to our comms channel: [Telegram](https://t.me/gnosischain), [X](https://x.com/gnosischain), [Discord](https://discord.com/invite/gnosis) for assistance.