"docs: update protocol contract docs"

zeta-chain · Nov 2, 2024 · 6ed66e0 · 6ed66e0
1 parent 925fe5b
commit 6ed66e0
Show file tree

Hide file tree

Showing 15 changed files with 142 additions and 105 deletions.
diff --git a/src/pages/developers/architecture/protocol/README.md b/src/pages/developers/architecture/protocol/README.md
@@ -41,12 +41,18 @@ $ forge snapshot
 $ anvil
 ```
 
-### Deploy using script
+### Deploy
 
 ```shell
 $ forge script script/<DeployScript>.s.sol:<DeployScript> --rpc-url <your_rpc_url> --private-key <your_private_key>
 ```
 
+##### More detailed instructions
+
+To view detailed instructions on how to deploy the contracts, please refer to the [Deployment Guide](./scripts/deploy/readme.md).
+
+This guide covers all steps required to deploy the contracts, including environment setup, commands, and best practices.
+
 ### Cast
 
 ```shell

diff --git a/...rs/architecture/protocol/contracts/Errors.sol/interface.INotSupportedMethods.md b/...rs/architecture/protocol/contracts/Errors.sol/interface.INotSupportedMethods.md
@@ -11,3 +11,9 @@ Interface for contracts that with non supported methods.
 error ZETANotSupported();
 ```
 
+### CallOnRevertNotSupported
+
+```solidity
+error CallOnRevertNotSupported();
+```
+
diff --git a/...s/architecture/protocol/contracts/evm/ERC20Custody.sol/contract.ERC20Custody.md b/...s/architecture/protocol/contracts/evm/ERC20Custody.sol/contract.ERC20Custody.md
@@ -208,6 +208,7 @@ WithdrawAndCall transfers tokens to Gateway and call a contract through the Gate
 
 ```solidity
 function withdrawAndCall(
+    MessageContext calldata messageContext,
     address to,
     address token,
     uint256 amount,
@@ -222,6 +223,7 @@ function withdrawAndCall(
 
 |Name|Type|Description|
 |----|----|-----------|
+|`messageContext`|`MessageContext`|Message context containing sender.|
 |`to`|`address`|Address of the contract to call.|
 |`token`|`address`|Address of the ERC20 token.|
 |`amount`|`uint256`|Amount of tokens to withdraw.|
@@ -264,9 +266,6 @@ function withdrawAndRevert(
 
 Deposits asset to custody and pay fee in zeta erc20.
 
-**Note:**
-This method is deprecated.
-
 
 ```solidity
 function deposit(

diff --git a/...opers/architecture/protocol/contracts/evm/GatewayEVM.sol/contract.GatewayEVM.md b/...opers/architecture/protocol/contracts/evm/GatewayEVM.sol/contract.GatewayEVM.md
@@ -85,9 +85,6 @@ uint256 public constant MAX_PAYLOAD_SIZE = 1024;
 ## Functions
 ### constructor
 
-**Note:**
-constructor
-
 
 ```solidity
 constructor();
@@ -167,9 +164,9 @@ function executeRevert(
 )
     public
     payable
+    nonReentrant
     onlyRole(TSS_ROLE)
-    whenNotPaused
-    nonReentrant;
+    whenNotPaused;
 ```
 **Parameters**
 
@@ -182,7 +179,7 @@ function executeRevert(
 
 ### execute
 
-Executes an authenticated call to a destination address without ERC20 tokens.
+Executes a call to a destination address without ERC20 tokens.
 
 *This function can only be called by the TSS address and it is payable.*
 
@@ -195,40 +192,7 @@ function execute(
 )
     external
     payable
-    onlyRole(TSS_ROLE)
-    whenNotPaused
     nonReentrant
-    returns (bytes memory);
-```
-**Parameters**
-
-|Name|Type|Description|
-|----|----|-----------|
-|`messageContext`|`MessageContext`|Message context containing sender.|
-|`destination`|`address`|Address to call.|
-|`data`|`bytes`|Calldata to pass to the call.|
-
-**Returns**
-
-|Name|Type|Description|
-|----|----|-----------|
-|`<none>`|`bytes`|The result of the call.|
-
-
-### execute
-
-Executes an arbitrary call to a destination address without ERC20 tokens.
-
-*This function can only be called by the TSS address and it is payable.*
-
-
-```solidity
-function execute(
-    address destination,
-    bytes calldata data
-)
-    external
-    payable
     onlyRole(TSS_ROLE)
     whenNotPaused
     returns (bytes memory);
@@ -237,6 +201,7 @@ function execute(
 
 |Name|Type|Description|
 |----|----|-----------|
+|`messageContext`|`MessageContext`|Message context containing sender.|
 |`destination`|`address`|Address to call.|
 |`data`|`bytes`|Calldata to pass to the call.|
 
@@ -257,20 +222,22 @@ It uses the ERC20 allowance system, resetting gateway allowance at the end.*
 
 ```solidity
 function executeWithERC20(
+    MessageContext calldata messageContext,
     address token,
     address to,
     uint256 amount,
     bytes calldata data
 )
     public
+    nonReentrant
     onlyRole(ASSET_HANDLER_ROLE)
-    whenNotPaused
-    nonReentrant;
+    whenNotPaused;
 ```
 **Parameters**
 
 |Name|Type|Description|
 |----|----|-----------|
+|`messageContext`|`MessageContext`|Message context containing sender.|
 |`token`|`address`|Address of the ERC20 token.|
 |`to`|`address`|Address of the contract to call.|
 |`amount`|`uint256`|Amount of tokens to transfer.|
@@ -293,9 +260,9 @@ function revertWithERC20(
     RevertContext calldata revertContext
 )
     external
+    nonReentrant
     onlyRole(ASSET_HANDLER_ROLE)
-    whenNotPaused
-    nonReentrant;
+    whenNotPaused;
 ```
 **Parameters**
 
@@ -314,7 +281,7 @@ Deposits ETH to the TSS address.
 
 
 ```solidity
-function deposit(address receiver, RevertOptions calldata revertOptions) external payable whenNotPaused nonReentrant;
+function deposit(address receiver, RevertOptions calldata revertOptions) external payable whenNotPaused;
 ```
 **Parameters**
 
@@ -337,8 +304,7 @@ function deposit(
     RevertOptions calldata revertOptions
 )
     external
-    whenNotPaused
-    nonReentrant;
+    whenNotPaused;
 ```
 **Parameters**
 
@@ -363,8 +329,7 @@ function depositAndCall(
 )
     external
     payable
-    whenNotPaused
-    nonReentrant;
+    whenNotPaused;
 ```
 **Parameters**
 
@@ -389,8 +354,7 @@ function depositAndCall(
     RevertOptions calldata revertOptions
 )
     external
-    whenNotPaused
-    nonReentrant;
+    whenNotPaused;
 ```
 **Parameters**
 
@@ -409,14 +373,7 @@ Calls an omnichain smart contract without asset transfer.
 
 
 ```solidity
-function call(
-    address receiver,
-    bytes calldata payload,
-    RevertOptions calldata revertOptions
-)
-    external
-    whenNotPaused
-    nonReentrant;
+function call(address receiver, bytes calldata payload, RevertOptions calldata revertOptions) external whenNotPaused;
 ```
 **Parameters**
 

diff --git a/...ture/protocol/contracts/evm/ZetaConnectorBase.sol/abstract.ZetaConnectorBase.md b/...ture/protocol/contracts/evm/ZetaConnectorBase.sol/abstract.ZetaConnectorBase.md
@@ -155,12 +155,21 @@ Withdraw tokens and call a contract through Gateway.
 
 
 ```solidity
-function withdrawAndCall(address to, uint256 amount, bytes calldata data, bytes32 internalSendHash) external virtual;
+function withdrawAndCall(
+    MessageContext calldata messageContext,
+    address to,
+    uint256 amount,
+    bytes calldata data,
+    bytes32 internalSendHash
+)
+    external
+    virtual;
 ```
 **Parameters**
 
 |Name|Type|Description|
 |----|----|-----------|
+|`messageContext`|`MessageContext`|Message context containing sender.|
 |`to`|`address`|The address to withdraw tokens to.|
 |`amount`|`uint256`|The amount of tokens to withdraw.|
 |`data`|`bytes`|The calldata to pass to the contract call.|

diff --git a/.../protocol/contracts/evm/ZetaConnectorNative.sol/contract.ZetaConnectorNative.md b/.../protocol/contracts/evm/ZetaConnectorNative.sol/contract.ZetaConnectorNative.md
@@ -62,6 +62,7 @@ Withdraw tokens and call a contract through Gateway.
 
 ```solidity
 function withdrawAndCall(
+    MessageContext calldata messageContext,
     address to,
     uint256 amount,
     bytes calldata data,
@@ -77,6 +78,7 @@ function withdrawAndCall(
 
 |Name|Type|Description|
 |----|----|-----------|
+|`messageContext`|`MessageContext`|Message context containing sender.|
 |`to`|`address`|The address to withdraw tokens to.|
 |`amount`|`uint256`|The amount of tokens to withdraw.|
 |`data`|`bytes`|The calldata to pass to the contract call.|

diff --git a/...col/contracts/evm/ZetaConnectorNonNative.sol/contract.ZetaConnectorNonNative.md b/...col/contracts/evm/ZetaConnectorNonNative.sol/contract.ZetaConnectorNonNative.md
@@ -89,6 +89,7 @@ Withdraw tokens and call a contract through Gateway.
 
 ```solidity
 function withdrawAndCall(
+    MessageContext calldata messageContext,
     address to,
     uint256 amount,
     bytes calldata data,
@@ -104,6 +105,7 @@ function withdrawAndCall(
 
 |Name|Type|Description|
 |----|----|-----------|
+|`messageContext`|`MessageContext`|Message context containing sender.|
 |`to`|`address`|The address to withdraw tokens to.|
 |`amount`|`uint256`|The amount of tokens to withdraw.|
 |`data`|`bytes`|The calldata to pass to the contract call.|

diff --git a/.../protocol/contracts/evm/interfaces/IERC20Custody.sol/interface.IERC20Custody.md b/.../protocol/contracts/evm/interfaces/IERC20Custody.sol/interface.IERC20Custody.md
@@ -42,12 +42,20 @@ WithdrawAndCall transfers tokens to Gateway and call a contract through the Gate
 
 
 ```solidity
-function withdrawAndCall(address token, address to, uint256 amount, bytes calldata data) external;
+function withdrawAndCall(
+    MessageContext calldata messageContext,
+    address token,
+    address to,
+    uint256 amount,
+    bytes calldata data
+)
+    external;
 ```
 **Parameters**
 
 |Name|Type|Description|
 |----|----|-----------|
+|`messageContext`|`MessageContext`|Message context containing sender.|
 |`token`|`address`|Address of the ERC20 token.|
 |`to`|`address`|Address of the contract to call.|
 |`amount`|`uint256`|Amount of tokens to withdraw.|

diff --git a/...ture/protocol/contracts/evm/interfaces/IGatewayEVM.sol/interface.IGatewayEVM.md b/...ture/protocol/contracts/evm/interfaces/IGatewayEVM.sol/interface.IGatewayEVM.md
@@ -14,12 +14,20 @@ Executes a call to a contract using ERC20 tokens.
 
 
 ```solidity
-function executeWithERC20(address token, address to, uint256 amount, bytes calldata data) external;
+function executeWithERC20(
+    MessageContext calldata messageContext,
+    address token,
+    address to,
+    uint256 amount,
+    bytes calldata data
+)
+    external;
 ```
 **Parameters**
 
 |Name|Type|Description|
 |----|----|-----------|
+|`messageContext`|`MessageContext`|Message context containing sender and arbitrary call flag.|
 |`token`|`address`|The address of the ERC20 token.|
 |`to`|`address`|The address of the contract to call.|
 |`amount`|`uint256`|The amount of tokens to transfer.|
@@ -51,28 +59,6 @@ function executeRevert(
 |`revertContext`|`RevertContext`|Revert context to pass to onRevert.|
 
 
-### execute
-
-Executes a call to a contract.
-
-
-```solidity
-function execute(address destination, bytes calldata data) external payable returns (bytes memory);
-```
-**Parameters**
-
-|Name|Type|Description|
-|----|----|-----------|
-|`destination`|`address`|The address of the contract to call.|
-|`data`|`bytes`|The calldata to pass to the contract call.|
-
-**Returns**
-
-|Name|Type|Description|
-|----|----|-----------|
-|`<none>`|`bytes`|The result of the contract call.|
-
-
 ### execute
 
 Executes a call to a destination address without ERC20 tokens.

diff --git a/...rotocol/contracts/evm/interfaces/IGatewayEVM.sol/interface.IGatewayEVMEvents.md b/...rotocol/contracts/evm/interfaces/IGatewayEVM.sol/interface.IGatewayEVMEvents.md
@@ -73,6 +73,32 @@ event Deposited(
 
 **Parameters**
 
+|Name|Type|Description|
+|----|----|-----------|
+|`sender`|`address`|The address of the sender.|
+|`receiver`|`address`|The address of the receiver.|
+|`amount`|`uint256`|The amount of ETH or tokens deposited.|
+|`asset`|`address`|The address of the ERC20 token (zero address if ETH).|
+|`payload`|`bytes`|The calldata passed with the deposit. No longer used. Kept to maintain compatibility.|
+|`revertOptions`|`RevertOptions`|Revert options.|
+
+### DepositedAndCalled
+Emitted when a deposit and call is made.
+
+
+```solidity
+event DepositedAndCalled(
+    address indexed sender,
+    address indexed receiver,
+    uint256 amount,
+    address asset,
+    bytes payload,
+    RevertOptions revertOptions
+);
+```
+
+**Parameters**
+
 |Name|Type|Description|
 |----|----|-----------|
 |`sender`|`address`|The address of the sender.|