uLxLy Bridge Commands

cmd/ulxly/BridgeAssetUsage.md

@@ -0,0 +1,61 @@
+This command will attempt to send a deposit transaction to the bridge contract.
+
+```solidity
+    /**
+     * @notice Deposit add a new leaf to the merkle tree
+     * note If this function is called with a reentrant token, it would be possible to `claimTokens` in the same call
+     * Reducing the supply of tokens on this contract, and actually locking tokens in the contract.
+     * Therefore we recommend to third parties bridges that if they do implement reentrant call of `beforeTransfer` of some reentrant tokens
+     * do not call any external address in that case
+     * note User/UI must be aware of the existing/available networks when choosing the destination network
+     * @param destinationNetwork Network destination
+     * @param destinationAddress Address destination
+     * @param amount Amount of tokens
+     * @param token Token address, 0 address is reserved for ether
+     * @param forceUpdateGlobalExitRoot Indicates if the new global exit root is updated or not
+     * @param permitData Raw data of the call `permit` of the token
+     */
+    function bridgeAsset(
+        uint32 destinationNetwork,
+        address destinationAddress,
+        uint256 amount,
+        address token,
+        bool forceUpdateGlobalExitRoot,
+        bytes calldata permitData
+    );
+
+```
+
+Each transaction will require manual input of parameters. Example usage:
+
+```bash
+polycli ulxly bridge-asset \
+        --private-key 12d7de8621a77640c9241b2595ba78ce443d05e94090365ab3bb5e19df82c625 \
+        --gas-limit 300000 \
+        --amount 1000000000000000000 \
+        --rpc-url http://127.0.0.1:8545 \
+        --bridge-address 0xD71f8F956AD979Cc2988381B8A743a2fE280537D \
+        --destination-network 1 \
+        --destination-address 0xE34aaF64b29273B7D567FCFc40544c014EEe9970
+```
+
+This command would use the supplied private key and attempt to send a deposit transaction to the bridge contract address with the input flags.
+Successful deposit transaction will output logs like below:
+
+```bash
+Deposit Transaction Successful: 0x8c9b82e8abdfb4aad5fccd91879397acfa73e4261282c8dc634734d05ad889d3
+```
+
+Upon successful deposit, the transaction can be queried using `polycli ulxly deposit-get` command
+
+
+Failed deposit transactions will output logs like below: 
+
+```bash
+Deposit Transaction Failed: 0x60385209b0e9db359c24c88c2fb8a5c9e4628fffe8d5fb2b5e64dfac3a2b7639
+Try increasing the gas limit:
+Current gas limit: 100000
+Cumulative gas used for transaction: 98641
+```
+
+The reason for failing may likely be due to the `out of gas` error. Increasing the `--gas-limit` flag value will likely resolve this. 

cmd/ulxly/BridgeMessageUsage.md

@@ -0,0 +1,53 @@
+This command will attempt to send a deposit transaction to the bridge contract.
+
+```solidity
+    /**
+     * @notice Bridge message and send ETH value
+     * note User/UI must be aware of the existing/available networks when choosing the destination network
+     * @param destinationNetwork Network destination
+     * @param destinationAddress Address destination
+     * @param forceUpdateGlobalExitRoot Indicates if the new global exit root is updated or not
+     * @param metadata Message metadata
+     */
+    function bridgeMessage(
+        uint32 destinationNetwork,
+        address destinationAddress,
+        bool forceUpdateGlobalExitRoot,
+        bytes calldata metadata
+    );
+```
+
+Each transaction will require manual input of parameters. Example usage:
+
+```bash
+polycli ulxly bridge-message \
+        --private-key 12d7de8621a77640c9241b2595ba78ce443d05e94090365ab3bb5e19df82c625 \
+        --gas-limit 300000 \
+        --amount 1000000000000000000 \
+        --rpc-url http://127.0.0.1:8545 \
+        --bridge-address 0xD71f8F956AD979Cc2988381B8A743a2fE280537D \
+        --destination-network 1 \
+        --destination-address 0xE34aaF64b29273B7D567FCFc40544c014EEe9970
+        --call-data 0x001010109200090028979743971976836486868648629808961824738090896826764980866fac97863898ca08928fc7279643
+```
+
+This command would use the supplied private key and attempt to send a deposit transaction to the bridge contract address with the input flags.
+Successful deposit transaction will output logs like below:
+
+```bash
+Deposit Transaction Successful: 0x8c9b82e8abdfb4aad5fccd91879397acfa73e4261282c8dc634734d05ad889d3
+```
+
+Upon successful deposit, the transaction can be queried using `polycli ulxly deposit-get` command
+
+
+Failed deposit transactions will output logs like below: 
+
+```bash
+Deposit Transaction Failed: 0x60385209b0e9db359c24c88c2fb8a5c9e4628fffe8d5fb2b5e64dfac3a2b7639
+Try increasing the gas limit:
+Current gas limit: 100000
+Cumulative gas used for transaction: 98641
+```
+
+The reason for failing may likely be due to the `out of gas` error. Increasing the `--gas-limit` flag value will likely resolve this. 

cmd/ulxly/BridgeWETHMessageUsage.md

@@ -0,0 +1,55 @@
+This command will attempt to send a deposit transaction to the bridge contract.
+
+```solidity
+    /**
+     * @notice Bridge message and send ETH value
+     * note User/UI must be aware of the existing/available networks when choosing the destination network
+     * @param destinationNetwork Network destination
+     * @param destinationAddress Address destination
+     * @param amountWETH Amount of WETH tokens
+     * @param forceUpdateGlobalExitRoot Indicates if the new global exit root is updated or not
+     * @param metadata Message metadata
+     */
+    function bridgeMessageWETH(
+        uint32 destinationNetwork,
+        address destinationAddress,
+        uint256 amountWETH,
+        bool forceUpdateGlobalExitRoot,
+        bytes calldata metadata
+    );
+```
+
+Each transaction will require manual input of parameters. Example usage:
+
+```bash
+polycli ulxly bridge-message-weth \
+        --private-key 12d7de8621a77640c9241b2595ba78ce443d05e94090365ab3bb5e19df82c625 \
+        --gas-limit 300000 \
+        --amount 1000000000000000000 \
+        --rpc-url http://127.0.0.1:8545 \
+        --bridge-address 0xD71f8F956AD979Cc2988381B8A743a2fE280537D \
+        --destination-network 1 \
+        --destination-address 0xE34aaF64b29273B7D567FCFc40544c014EEe9970
+        --call-data 0x001010109200090028979743971976836486868648629808961824738090896826764980866fac97863898ca08928fc7279643
+```
+
+This command would use the supplied private key and attempt to send a deposit transaction to the bridge contract address with the input flags.
+Successful deposit transaction will output logs like below:
+
+```bash
+Deposit Transaction Successful: 0x8c9b82e8abdfb4aad5fccd91879397acfa73e4261282c8dc634734d05ad889d3
+```
+
+Upon successful deposit, the transaction can be queried using `polycli ulxly deposit-get` command
+
+
+Failed deposit transactions will output logs like below: 
+
+```bash
+Deposit Transaction Failed: 0x60385209b0e9db359c24c88c2fb8a5c9e4628fffe8d5fb2b5e64dfac3a2b7639
+Try increasing the gas limit:
+Current gas limit: 100000
+Cumulative gas used for transaction: 98641
+```
+
+The reason for failing may likely be due to the `out of gas` error. Increasing the `--gas-limit` flag value will likely resolve this. 

cmd/ulxly/ClaimAssetUsage.md

@@ -0,0 +1,76 @@
+This command will attempt to send a claim transaction to the bridge contract.
+
+```solidity
+    /**
+     * @notice Verify merkle proof and withdraw tokens/ether
+     * @param smtProofLocalExitRoot Smt proof to proof the leaf against the network exit root
+     * @param smtProofRollupExitRoot Smt proof to proof the rollupLocalExitRoot against the rollups exit root
+     * @param globalIndex Global index is defined as:
+     * | 191 bits |    1 bit     |   32 bits   |     32 bits    |
+     * |    0     |  mainnetFlag | rollupIndex | localRootIndex |
+     * note that only the rollup index will be used only in case the mainnet flag is 0
+     * note that global index do not assert the unused bits to 0.
+     * This means that when synching the events, the globalIndex must be decoded the same way that in the Smart contract
+     * to avoid possible synch attacks
+     * @param mainnetExitRoot Mainnet exit root
+     * @param rollupExitRoot Rollup exit root
+     * @param originNetwork Origin network
+     * @param originTokenAddress  Origin token address, 0 address is reserved for ether
+     * @param destinationNetwork Network destination
+     * @param destinationAddress Address destination
+     * @param amount Amount of tokens
+     * @param metadata Abi encoded metadata if any, empty otherwise
+     */
+    function claimAsset(
+        bytes32[_DEPOSIT_CONTRACT_TREE_DEPTH] calldata smtProofLocalExitRoot,
+        bytes32[_DEPOSIT_CONTRACT_TREE_DEPTH] calldata smtProofRollupExitRoot,
+        uint256 globalIndex,
+        bytes32 mainnetExitRoot,
+        bytes32 rollupExitRoot,
+        uint32 originNetwork,
+        address originTokenAddress,
+        uint32 destinationNetwork,
+        address destinationAddress,
+        uint256 amount,
+        bytes calldata metadata
+    );
+
+```
+
+Each transaction will require manual input of parameters. Example usage:
+
+```bash
+polycli ulxly deposit-claim \
+        --bridge-address 0xD71f8F956AD979Cc2988381B8A743a2fE280537D \
+        --private-key 12d7de8621a77640c9241b2595ba78ce443d05e94090365ab3bb5e19df82c625 \
+        --claim-index 0 \
+        --claim-address 0xE34aaF64b29273B7D567FCFc40544c014EEe9970 \
+        --claim-network 0 \
+        --rpc-url http://127.0.0.1:32790 \
+        --bridge-service-url http://127.0.0.1:32804
+```
+
+This command would use the supplied private key and attempt to send a claim transaction to the bridge contract address with the input flags.
+Successful deposit transaction will output logs like below:
+
+```bash
+Claim Transaction Successful: 0x7180201b19e1aa596503d8541137d6f341e682835bf7a54aab6422c89158866b
+```
+
+Upon successful claim, the transferred funds can be queried in the destination network using tools like `cast balance <claim-address> --rpc-url <destination-network-url>`
+
+
+Failed deposit transactions will output logs like below: 
+
+```bash
+Claim Transaction Failed: 0x32ac34797159c79e57ae801c350bccfe5f8105d4dd3b717e31d811397e98036a
+```
+
+The reason for failing may be very difficult to debug. I have personally spun up a bridge-ui and compared the byte data of a successful transaction to the byte data of a failing claim transaction queried using:
+
+```!
+curl http://127.0.0.1:32790 \
+-X POST \
+-H "Content-Type: application/json" \
+--data '{"method":"debug_traceTransaction","params":["0x32ac34797159c79e57ae801c350bccfe5f8105d4dd3b717e31d811397e98036a", {"tracer": "callTracer"}], "id":1,"jsonrpc":"2.0"}' | jq '.'
+```

cmd/ulxly/ClaimMessageUsage.md

@@ -0,0 +1,57 @@
+This command will attempt to send a claim transaction to the bridge contract.
+
+```solidity
+    /**
+     * @notice Bridge message and send ETH value
+     * note User/UI must be aware of the existing/available networks when choosing the destination network
+     * @param destinationNetwork Network destination
+     * @param destinationAddress Address destination
+     * @param forceUpdateGlobalExitRoot Indicates if the new global exit root is updated or not
+     * @param metadata Message metadata
+     */
+    function bridgeMessage(
+        uint32 destinationNetwork,
+        address destinationAddress,
+        bool forceUpdateGlobalExitRoot,
+        bytes calldata metadata
+    );
+
+```
+
+Each transaction will require manual input of parameters. Example usage:
+
+```bash
+polycli ulxly deposit-claim \
+        --bridge-address 0xD71f8F956AD979Cc2988381B8A743a2fE280537D \
+        --private-key 12d7de8621a77640c9241b2595ba78ce443d05e94090365ab3bb5e19df82c625 \
+        --claim-index 0 \
+        --claim-address 0xE34aaF64b29273B7D567FCFc40544c014EEe9970 \
+        --claim-network 0 \
+        --rpc-url http://127.0.0.1:32790 \
+        --bridge-service-url http://127.0.0.1:32804
+```
+
+This command would use the supplied private key and attempt to send a claim transaction to the bridge contract address with the input flags.
+Successful deposit transaction will output logs like below:
+
+```bash
+Claim Transaction Successful: 0x7180201b19e1aa596503d8541137d6f341e682835bf7a54aab6422c89158866b
+```
+
+Upon successful claim, the transferred funds can be queried in the destination network using tools like `cast balance <claim-address> --rpc-url <destination-network-url>`
+
+
+Failed deposit transactions will output logs like below: 
+
+```bash
+Claim Transaction Failed: 0x32ac34797159c79e57ae801c350bccfe5f8105d4dd3b717e31d811397e98036a
+```
+
+The reason for failing may be very difficult to debug. I have personally spun up a bridge-ui and compared the byte data of a successful transaction to the byte data of a failing claim transaction queried using:
+
+```!
+curl http://127.0.0.1:32790 \
+-X POST \
+-H "Content-Type: application/json" \
+--data '{"method":"debug_traceTransaction","params":["0x32ac34797159c79e57ae801c350bccfe5f8105d4dd3b717e31d811397e98036a", {"tracer": "callTracer"}], "id":1,"jsonrpc":"2.0"}' | jq '.'
+```

cmd/ulxly/delete.md

@@ -0,0 +1,70 @@
+This command will attempt to send a deposit transaction to the bridge contract.
+
+```solidity
+    /**
+     * @notice Deposit add a new leaf to the merkle tree
+     * note If this function is called with a reentrant token, it would be possible to `claimTokens` in the same call
+     * Reducing the supply of tokens on this contract, and actually locking tokens in the contract.
+     * Therefore we recommend to third parties bridges that if they do implement reentrant call of `beforeTransfer` of some reentrant tokens
+     * do not call any external address in that case
+     * note User/UI must be aware of the existing/available networks when choosing the destination network
+     * @param destinationNetwork Network destination
+     * @param destinationAddress Address destination
+     * @param amount Amount of tokens
+     * @param token Token address, 0 address is reserved for ether
+     * @param forceUpdateGlobalExitRoot Indicates if the new global exit root is updated or not
+     * @param permitData Raw data of the call `permit` of the token
+     */
+    function bridgeAsset(
+        uint32 destinationNetwork,
+        address destinationAddress,
+        uint256 amount,
+        address token,
+        bool forceUpdateGlobalExitRoot,
+        bytes calldata permitData
+    );
+
+```
+
+Each transaction will require manual input of parameters. Example usage:
+
+```bash
+polycli ulxly deposit-new \
+        --private-key 12d7de8621a77640c9241b2595ba78ce443d05e94090365ab3bb5e19df82c625 \
+        --gas-limit 300000 \
+        --amount 1000000000000000000 \
+        --rpc-url http://127.0.0.1:8545 \
+        --bridge-address 0xD71f8F956AD979Cc2988381B8A743a2fE280537D \
+        --destination-network 1 \
+        --destination-address 0xE34aaF64b29273B7D567FCFc40544c014EEe9970
+```
+go run ulxly.go ulxly bridge-asset --private-key 846f556e5509c36b5756fa3741009310908d606db18d5916d43e6c7d22e0f5a7 --gas-limit 300000 --rpc-url https://sepolia.infura.io/v3/7c490aa772fa466293ee1ac62761330a --bridge-address 0x1348947e282138d8f377b467f7d9c2eb0f335d1f --destination-network 1 --amount 19
+
+go run main.go ulxly bridge-message --private-key 846f556e5509c36b5756fa3741009310908d606db18d5916d43e6c7d22e0f5a7 --gas-limit 300000 --rpc-url https://sepolia.infura.io/v3/7c490aa772fa466293ee1ac62761330a --bridge-address 0x1348947e282138d8f377b467f7d9c2eb0f335d1f --destination-network 1 --amount 19 --call-data 0x18976546789087654356789654345678976543567897654356789765435468797865435468797654354678907654356879765436798765435467986543
+
+go run main.go ulxly claim-asset --private-key 846f556e5509c36b5756fa3741009310908d606db18d5916d43e6c7d22e0f5a7 --gas-limit 30000000 --rpc-url https://sepolia.infura.io/v3/7c490aa772fa466293ee1ac62761330a --bridge-address 0x1348947e282138d8f377b467f7d9c2eb0f335d1f --claim-address 0x2536C2745Ac4A584656A830f7bdCd329c94e8F30 --claim-index 7780 --bridge-service-url https://bridge-api.internal.zkevm-rpc.com --deposit-network 1
+
+go run main.go ulxly claim-message --private-key 846f556e5509c36b5756fa3741009310908d606db18d5916d43e6c7d
+22e0f5a7 --gas-limit 300000 --rpc-url https://sepolia.infura.io/v3/7c490aa772fa466293ee1ac62761330a --bridge-address 0x1348947e282138d8f377b467f7d9c2eb0f335d1f  --claim-address 0x2536C2745Ac4A584656A830f7bdCd329c94e8F30 --claim-index 7780 --call-data 0x18976546789087654356789654345678976543567897654356789765435468797865435468797654354678907654356879765436798765435467986543 --bridge-service-url https://bridge-api.internal.zkevm-rpc.com
+
+
+This command would use the supplied private key and attempt to send a deposit transaction to the bridge contract address with the input flags.
+Successful deposit transaction will output logs like below:
+
+```bash
+Deposit Transaction Successful: 0x8c9b82e8abdfb4aad5fccd91879397acfa73e4261282c8dc634734d05ad889d3
+```
+
+Upon successful deposit, the transaction can be queried using `polycli ulxly deposit-get` command
+
+
+Failed deposit transactions will output logs like below: 
+
+```bash
+Deposit Transaction Failed: 0x60385209b0e9db359c24c88c2fb8a5c9e4628fffe8d5fb2b5e64dfac3a2b7639
+Try increasing the gas limit:
+Current gas limit: 100000
+Cumulative gas used for transaction: 98641
+```
+
+The reason for failing may likely be due to the `out of gas` error. Increasing the `--gas-limit` flag value will likely resolve this.