From 1eb338f1ee141b6c80db7a18eb7bc91867502a10 Mon Sep 17 00:00:00 2001 From: Denis Fadeev Date: Mon, 19 Aug 2024 16:19:58 +0300 Subject: [PATCH] ci: generate v2 docs using forge doc (#334) --- .github/workflows/generated-files_v2.yaml | 4 +- v2/docs/.gitignore | 1 + v2/docs/book.css | 13 + v2/docs/book.toml | 12 + v2/docs/solidity.min.js | 74 +++ v2/docs/src/README.md | 55 ++ v2/docs/src/SUMMARY.md | 38 ++ v2/docs/src/contracts/README.md | 8 + .../Revert.sol/interface.Revertable.md | 22 + .../Revert.sol/struct.RevertContext.md | 22 + .../Revert.sol/struct.RevertOptions.md | 26 + .../ERC20Custody.sol/contract.ERC20Custody.md | 249 ++++++++ .../evm/GatewayEVM.sol/contract.GatewayEVM.md | 480 ++++++++++++++++ v2/docs/src/contracts/evm/README.md | 9 + .../abstract.ZetaConnectorBase.md | 173 ++++++ .../contract.ZetaConnectorNative.md | 130 +++++ .../contract.ZetaConnectorNonNative.md | 188 +++++++ .../interface.IERC20Custody.md | 85 +++ .../interface.IERC20CustodyErrors.md | 31 + .../interface.IERC20CustodyEvents.md | 96 ++++ .../IGatewayEVM.sol/interface.IGatewayEVM.md | 201 +++++++ .../interface.IGatewayEVMErrors.md | 79 +++ .../interface.IGatewayEVMEvents.md | 101 ++++ .../interface.IZetaConnectorEvents.md | 55 ++ .../interface.IZetaNonEthNew.md | 47 ++ .../src/contracts/evm/interfaces/README.md | 11 + .../GatewayZEVM.sol/contract.GatewayZEVM.md | 458 +++++++++++++++ v2/docs/src/contracts/zevm/README.md | 7 + .../zevm/ZRC20.sol/contract.ZRC20.md | 531 ++++++++++++++++++ .../zevm/ZRC20.sol/interface.ZRC20Errors.md | 55 ++ .../interface.IGatewayZEVM.md | 267 +++++++++ .../interface.IGatewayZEVMErrors.md | 103 ++++ .../interface.IGatewayZEVMEvents.md | 67 +++ .../ISystem.sol/interface.ISystem.md | 51 ++ .../interfaces/IWZETA.sol/interface.IWETH9.md | 88 +++ .../interfaces/IZRC20.sol/enum.CoinType.md | 14 + .../interfaces/IZRC20.sol/interface.IZRC20.md | 116 ++++ .../IZRC20.sol/interface.IZRC20Metadata.md | 31 + .../IZRC20.sol/interface.ZRC20Events.md | 55 ++ .../src/contracts/zevm/interfaces/README.md | 15 + .../interface.UniversalContract.md | 19 + .../interface.zContract.md | 12 + .../UniversalContract.sol/struct.zContext.md | 12 + v2/docs/src/index.md | 97 ++++ v2/package.json | 5 +- v2/pkg/beaconproxy.sol/beaconproxy.go | 368 ------------ v2/scripts/generate_docs.sh | 13 + 47 files changed, 4222 insertions(+), 372 deletions(-) create mode 100644 v2/docs/.gitignore create mode 100644 v2/docs/book.css create mode 100644 v2/docs/book.toml create mode 100644 v2/docs/solidity.min.js create mode 100644 v2/docs/src/README.md create mode 100644 v2/docs/src/SUMMARY.md create mode 100644 v2/docs/src/contracts/README.md create mode 100644 v2/docs/src/contracts/Revert.sol/interface.Revertable.md create mode 100644 v2/docs/src/contracts/Revert.sol/struct.RevertContext.md create mode 100644 v2/docs/src/contracts/Revert.sol/struct.RevertOptions.md create mode 100644 v2/docs/src/contracts/evm/ERC20Custody.sol/contract.ERC20Custody.md create mode 100644 v2/docs/src/contracts/evm/GatewayEVM.sol/contract.GatewayEVM.md create mode 100644 v2/docs/src/contracts/evm/README.md create mode 100644 v2/docs/src/contracts/evm/ZetaConnectorBase.sol/abstract.ZetaConnectorBase.md create mode 100644 v2/docs/src/contracts/evm/ZetaConnectorNative.sol/contract.ZetaConnectorNative.md create mode 100644 v2/docs/src/contracts/evm/ZetaConnectorNonNative.sol/contract.ZetaConnectorNonNative.md create mode 100644 v2/docs/src/contracts/evm/interfaces/IERC20Custody.sol/interface.IERC20Custody.md create mode 100644 v2/docs/src/contracts/evm/interfaces/IERC20Custody.sol/interface.IERC20CustodyErrors.md create mode 100644 v2/docs/src/contracts/evm/interfaces/IERC20Custody.sol/interface.IERC20CustodyEvents.md create mode 100644 v2/docs/src/contracts/evm/interfaces/IGatewayEVM.sol/interface.IGatewayEVM.md create mode 100644 v2/docs/src/contracts/evm/interfaces/IGatewayEVM.sol/interface.IGatewayEVMErrors.md create mode 100644 v2/docs/src/contracts/evm/interfaces/IGatewayEVM.sol/interface.IGatewayEVMEvents.md create mode 100644 v2/docs/src/contracts/evm/interfaces/IZetaConnector.sol/interface.IZetaConnectorEvents.md create mode 100644 v2/docs/src/contracts/evm/interfaces/IZetaNonEthNew.sol/interface.IZetaNonEthNew.md create mode 100644 v2/docs/src/contracts/evm/interfaces/README.md create mode 100644 v2/docs/src/contracts/zevm/GatewayZEVM.sol/contract.GatewayZEVM.md create mode 100644 v2/docs/src/contracts/zevm/README.md create mode 100644 v2/docs/src/contracts/zevm/ZRC20.sol/contract.ZRC20.md create mode 100644 v2/docs/src/contracts/zevm/ZRC20.sol/interface.ZRC20Errors.md create mode 100644 v2/docs/src/contracts/zevm/interfaces/IGatewayZEVM.sol/interface.IGatewayZEVM.md create mode 100644 v2/docs/src/contracts/zevm/interfaces/IGatewayZEVM.sol/interface.IGatewayZEVMErrors.md create mode 100644 v2/docs/src/contracts/zevm/interfaces/IGatewayZEVM.sol/interface.IGatewayZEVMEvents.md create mode 100644 v2/docs/src/contracts/zevm/interfaces/ISystem.sol/interface.ISystem.md create mode 100644 v2/docs/src/contracts/zevm/interfaces/IWZETA.sol/interface.IWETH9.md create mode 100644 v2/docs/src/contracts/zevm/interfaces/IZRC20.sol/enum.CoinType.md create mode 100644 v2/docs/src/contracts/zevm/interfaces/IZRC20.sol/interface.IZRC20.md create mode 100644 v2/docs/src/contracts/zevm/interfaces/IZRC20.sol/interface.IZRC20Metadata.md create mode 100644 v2/docs/src/contracts/zevm/interfaces/IZRC20.sol/interface.ZRC20Events.md create mode 100644 v2/docs/src/contracts/zevm/interfaces/README.md create mode 100644 v2/docs/src/contracts/zevm/interfaces/UniversalContract.sol/interface.UniversalContract.md create mode 100644 v2/docs/src/contracts/zevm/interfaces/UniversalContract.sol/interface.zContract.md create mode 100644 v2/docs/src/contracts/zevm/interfaces/UniversalContract.sol/struct.zContext.md create mode 100644 v2/docs/src/index.md delete mode 100644 v2/pkg/beaconproxy.sol/beaconproxy.go create mode 100755 v2/scripts/generate_docs.sh diff --git a/.github/workflows/generated-files_v2.yaml b/.github/workflows/generated-files_v2.yaml index 05617e8b..18d243c3 100644 --- a/.github/workflows/generated-files_v2.yaml +++ b/.github/workflows/generated-files_v2.yaml @@ -5,12 +5,12 @@ on: branches: - main paths: - - 'v2/**' + - "v2/**" pull_request: branches: - "*" paths: - - 'v2/**' + - "v2/**" types: - synchronize - opened diff --git a/v2/docs/.gitignore b/v2/docs/.gitignore new file mode 100644 index 00000000..4e42a1bc --- /dev/null +++ b/v2/docs/.gitignore @@ -0,0 +1 @@ +book/ \ No newline at end of file diff --git a/v2/docs/book.css b/v2/docs/book.css new file mode 100644 index 00000000..b5ce903f --- /dev/null +++ b/v2/docs/book.css @@ -0,0 +1,13 @@ +table { + margin: 0 auto; + border-collapse: collapse; + width: 100%; +} + +table td:first-child { + width: 15%; +} + +table td:nth-child(2) { + width: 25%; +} \ No newline at end of file diff --git a/v2/docs/book.toml b/v2/docs/book.toml new file mode 100644 index 00000000..9fe0d553 --- /dev/null +++ b/v2/docs/book.toml @@ -0,0 +1,12 @@ +[book] +src = "src" +title = "" + +[output.html] +no-section-label = true +additional-js = ["solidity.min.js"] +additional-css = ["book.css"] +git-repository-url = "https://github.com/zeta-chain/protocol-contracts" + +[output.html.fold] +enable = true diff --git a/v2/docs/solidity.min.js b/v2/docs/solidity.min.js new file mode 100644 index 00000000..19249329 --- /dev/null +++ b/v2/docs/solidity.min.js @@ -0,0 +1,74 @@ +hljs.registerLanguage("solidity",(()=>{"use strict";function e(){try{return!0 +}catch(e){return!1}} +var a=/-?(\b0[xX]([a-fA-F0-9]_?)*[a-fA-F0-9]|(\b[1-9](_?\d)*(\.((\d_?)*\d)?)?|\.\d(_?\d)*)([eE][-+]?\d(_?\d)*)?|\b0)(?!\w|\$)/ +;e()&&(a=a.source.replace(/\\b/g,"(?{ +var a=r(e),o=l(e),c=/[A-Za-z_$][A-Za-z_$0-9.]*/,d=e.inherit(e.TITLE_MODE,{ +begin:/[A-Za-z$_][0-9A-Za-z$_]*/,lexemes:c,keywords:n}),u={className:"params", +begin:/\(/,end:/\)/,excludeBegin:!0,excludeEnd:!0,lexemes:c,keywords:n, +contains:[e.C_LINE_COMMENT_MODE,e.C_BLOCK_COMMENT_MODE,a,o,s]},_={ +className:"operator",begin:/:=|->/};return{keywords:n,lexemes:c, +contains:[a,o,i,t,e.C_LINE_COMMENT_MODE,e.C_BLOCK_COMMENT_MODE,s,_,{ +className:"function",lexemes:c,beginKeywords:"function",end:"{",excludeEnd:!0, +contains:[d,u,e.C_LINE_COMMENT_MODE,e.C_BLOCK_COMMENT_MODE,_]}]}}, +solAposStringMode:r,solQuoteStringMode:l,HEX_APOS_STRING_MODE:i, +HEX_QUOTE_STRING_MODE:t,SOL_NUMBER:s,isNegativeLookbehindAvailable:e} +;const{baseAssembly:c,solAposStringMode:d,solQuoteStringMode:u,HEX_APOS_STRING_MODE:_,HEX_QUOTE_STRING_MODE:m,SOL_NUMBER:b,isNegativeLookbehindAvailable:E}=o +;return e=>{for(var a=d(e),s=u(e),n=[],i=0;i<32;i++)n[i]=i+1 +;var t=n.map((e=>8*e)),r=[];for(i=0;i<=80;i++)r[i]=i +;var l=n.map((e=>"bytes"+e)).join(" ")+" ",o=t.map((e=>"uint"+e)).join(" ")+" ",g=t.map((e=>"int"+e)).join(" ")+" ",M=[].concat.apply([],t.map((e=>r.map((a=>e+"x"+a))))),p={ +keyword:"var bool string int uint "+g+o+"byte bytes "+l+"fixed ufixed "+M.map((e=>"fixed"+e)).join(" ")+" "+M.map((e=>"ufixed"+e)).join(" ")+" enum struct mapping address new delete if else for while continue break return throw emit try catch revert unchecked _ function modifier event constructor fallback receive error virtual override constant immutable anonymous indexed storage memory calldata external public internal payable pure view private returns import from as using pragma contract interface library is abstract type assembly", +literal:"true false wei gwei szabo finney ether seconds minutes hours days weeks years", +built_in:"self this super selfdestruct suicide now msg block tx abi blockhash gasleft assert require Error Panic sha3 sha256 keccak256 ripemd160 ecrecover addmod mulmod log0 log1 log2 log3 log4" +},O={className:"operator",begin:/[+\-!~*\/%<>&^|=]/ +},C=/[A-Za-z_$][A-Za-z_$0-9]*/,N={className:"params",begin:/\(/,end:/\)/, +excludeBegin:!0,excludeEnd:!0,lexemes:C,keywords:p, +contains:[e.C_LINE_COMMENT_MODE,e.C_BLOCK_COMMENT_MODE,a,s,b,"self"]},f={ +begin:/\.\s*/,end:/[^A-Za-z0-9$_\.]/,excludeBegin:!0,excludeEnd:!0,keywords:{ +built_in:"gas value selector address length push pop send transfer call callcode delegatecall staticcall balance code codehash wrap unwrap name creationCode runtimeCode interfaceId min max" +},relevance:2},y=e.inherit(e.TITLE_MODE,{begin:/[A-Za-z$_][0-9A-Za-z$_]*/, +lexemes:C,keywords:p}),w={className:"built_in", +begin:(E()?"(?.s.sol: --rpc-url --private-key +``` + +### Cast + +```shell +$ cast +``` + +### Help + +```shell +$ forge --help +$ anvil --help +$ cast --help +``` diff --git a/v2/docs/src/SUMMARY.md b/v2/docs/src/SUMMARY.md new file mode 100644 index 00000000..b222ddca --- /dev/null +++ b/v2/docs/src/SUMMARY.md @@ -0,0 +1,38 @@ +# Summary +- [Home](README.md) +# contracts + - [❱ evm](contracts/evm/README.md) + - [❱ interfaces](contracts/evm/interfaces/README.md) + - [IERC20CustodyEvents](contracts/evm/interfaces/IERC20Custody.sol/interface.IERC20CustodyEvents.md) + - [IERC20CustodyErrors](contracts/evm/interfaces/IERC20Custody.sol/interface.IERC20CustodyErrors.md) + - [IERC20Custody](contracts/evm/interfaces/IERC20Custody.sol/interface.IERC20Custody.md) + - [IGatewayEVMEvents](contracts/evm/interfaces/IGatewayEVM.sol/interface.IGatewayEVMEvents.md) + - [IGatewayEVMErrors](contracts/evm/interfaces/IGatewayEVM.sol/interface.IGatewayEVMErrors.md) + - [IGatewayEVM](contracts/evm/interfaces/IGatewayEVM.sol/interface.IGatewayEVM.md) + - [IZetaConnectorEvents](contracts/evm/interfaces/IZetaConnector.sol/interface.IZetaConnectorEvents.md) + - [IZetaNonEthNew](contracts/evm/interfaces/IZetaNonEthNew.sol/interface.IZetaNonEthNew.md) + - [ERC20Custody](contracts/evm/ERC20Custody.sol/contract.ERC20Custody.md) + - [GatewayEVM](contracts/evm/GatewayEVM.sol/contract.GatewayEVM.md) + - [ZetaConnectorBase](contracts/evm/ZetaConnectorBase.sol/abstract.ZetaConnectorBase.md) + - [ZetaConnectorNative](contracts/evm/ZetaConnectorNative.sol/contract.ZetaConnectorNative.md) + - [ZetaConnectorNonNative](contracts/evm/ZetaConnectorNonNative.sol/contract.ZetaConnectorNonNative.md) + - [❱ zevm](contracts/zevm/README.md) + - [❱ interfaces](contracts/zevm/interfaces/README.md) + - [IGatewayZEVMEvents](contracts/zevm/interfaces/IGatewayZEVM.sol/interface.IGatewayZEVMEvents.md) + - [IGatewayZEVMErrors](contracts/zevm/interfaces/IGatewayZEVM.sol/interface.IGatewayZEVMErrors.md) + - [IGatewayZEVM](contracts/zevm/interfaces/IGatewayZEVM.sol/interface.IGatewayZEVM.md) + - [ISystem](contracts/zevm/interfaces/ISystem.sol/interface.ISystem.md) + - [IWETH9](contracts/zevm/interfaces/IWZETA.sol/interface.IWETH9.md) + - [IZRC20](contracts/zevm/interfaces/IZRC20.sol/interface.IZRC20.md) + - [IZRC20Metadata](contracts/zevm/interfaces/IZRC20.sol/interface.IZRC20Metadata.md) + - [ZRC20Events](contracts/zevm/interfaces/IZRC20.sol/interface.ZRC20Events.md) + - [CoinType](contracts/zevm/interfaces/IZRC20.sol/enum.CoinType.md) + - [zContext](contracts/zevm/interfaces/UniversalContract.sol/struct.zContext.md) + - [zContract](contracts/zevm/interfaces/UniversalContract.sol/interface.zContract.md) + - [UniversalContract](contracts/zevm/interfaces/UniversalContract.sol/interface.UniversalContract.md) + - [GatewayZEVM](contracts/zevm/GatewayZEVM.sol/contract.GatewayZEVM.md) + - [ZRC20Errors](contracts/zevm/ZRC20.sol/interface.ZRC20Errors.md) + - [ZRC20](contracts/zevm/ZRC20.sol/contract.ZRC20.md) + - [RevertOptions](contracts/Revert.sol/struct.RevertOptions.md) + - [RevertContext](contracts/Revert.sol/struct.RevertContext.md) + - [Revertable](contracts/Revert.sol/interface.Revertable.md) diff --git a/v2/docs/src/contracts/README.md b/v2/docs/src/contracts/README.md new file mode 100644 index 00000000..aea1f3f5 --- /dev/null +++ b/v2/docs/src/contracts/README.md @@ -0,0 +1,8 @@ + + +# Contents +- [evm](/contracts/evm) +- [zevm](/contracts/zevm) +- [RevertOptions](Revert.sol/struct.RevertOptions.md) +- [RevertContext](Revert.sol/struct.RevertContext.md) +- [Revertable](Revert.sol/interface.Revertable.md) diff --git a/v2/docs/src/contracts/Revert.sol/interface.Revertable.md b/v2/docs/src/contracts/Revert.sol/interface.Revertable.md new file mode 100644 index 00000000..30281bd5 --- /dev/null +++ b/v2/docs/src/contracts/Revert.sol/interface.Revertable.md @@ -0,0 +1,22 @@ +# Revertable +[Git Source](https://github.com/zeta-chain/protocol-contracts/blob/c157025a39efca61d83e5991d093a94548f342fb/contracts/Revert.sol) + +Interface for contracts that support revertable calls. + + +## Functions +### onRevert + +Called when a revertable call is made. + + +```solidity +function onRevert(RevertContext calldata revertContext) external; +``` +**Parameters** + +|Name|Type|Description| +|----|----|-----------| +|`revertContext`|`RevertContext`|Revert context to pass to onRevert.| + + diff --git a/v2/docs/src/contracts/Revert.sol/struct.RevertContext.md b/v2/docs/src/contracts/Revert.sol/struct.RevertContext.md new file mode 100644 index 00000000..536cfe42 --- /dev/null +++ b/v2/docs/src/contracts/Revert.sol/struct.RevertContext.md @@ -0,0 +1,22 @@ +# RevertContext +[Git Source](https://github.com/zeta-chain/protocol-contracts/blob/c157025a39efca61d83e5991d093a94548f342fb/contracts/Revert.sol) + +Struct containing revert context passed to onRevert. + + +```solidity +struct RevertContext { + address asset; + uint64 amount; + bytes revertMessage; +} +``` + +**Properties** + +|Name|Type|Description| +|----|----|-----------| +|`asset`|`address`|Address of asset, empty if it's gas token.| +|`amount`|`uint64`|Amount specified with the transaction.| +|`revertMessage`|`bytes`|Arbitrary data sent back in onRevert.| + diff --git a/v2/docs/src/contracts/Revert.sol/struct.RevertOptions.md b/v2/docs/src/contracts/Revert.sol/struct.RevertOptions.md new file mode 100644 index 00000000..d575bafd --- /dev/null +++ b/v2/docs/src/contracts/Revert.sol/struct.RevertOptions.md @@ -0,0 +1,26 @@ +# RevertOptions +[Git Source](https://github.com/zeta-chain/protocol-contracts/blob/c157025a39efca61d83e5991d093a94548f342fb/contracts/Revert.sol) + +Struct containing revert options + + +```solidity +struct RevertOptions { + address revertAddress; + bool callOnRevert; + address abortAddress; + bytes revertMessage; + uint256 onRevertGasLimit; +} +``` + +**Properties** + +|Name|Type|Description| +|----|----|-----------| +|`revertAddress`|`address`|Address to receive revert.| +|`callOnRevert`|`bool`|Flag if onRevert hook should be called.| +|`abortAddress`|`address`|Address to receive funds if aborted.| +|`revertMessage`|`bytes`|Arbitrary data sent back in onRevert.| +|`onRevertGasLimit`|`uint256`|Gas limit for revert tx, unused on GatewayZEVM methods| + diff --git a/v2/docs/src/contracts/evm/ERC20Custody.sol/contract.ERC20Custody.md b/v2/docs/src/contracts/evm/ERC20Custody.sol/contract.ERC20Custody.md new file mode 100644 index 00000000..8a66e112 --- /dev/null +++ b/v2/docs/src/contracts/evm/ERC20Custody.sol/contract.ERC20Custody.md @@ -0,0 +1,249 @@ +# ERC20Custody +[Git Source](https://github.com/zeta-chain/protocol-contracts/blob/c157025a39efca61d83e5991d093a94548f342fb/contracts/evm/ERC20Custody.sol) + +**Inherits:** +[IERC20Custody](/contracts/evm/interfaces/IERC20Custody.sol/interface.IERC20Custody.md), ReentrancyGuard, AccessControl, Pausable + +Holds the ERC20 tokens deposited on ZetaChain and includes functionality to call a contract. + +*This contract does not call smart contracts directly, it passes through the Gateway contract.* + + +## State Variables +### gateway +Gateway contract. + + +```solidity +IGatewayEVM public immutable gateway; +``` + + +### whitelisted +Mapping of whitelisted tokens => true/false. + + +```solidity +mapping(address => bool) public whitelisted; +``` + + +### tssAddress +The address of the TSS (Threshold Signature Scheme) contract. + + +```solidity +address public tssAddress; +``` + + +### supportsLegacy +Used to flag if contract supports legacy methods (eg. deposit). + + +```solidity +bool public supportsLegacy; +``` + + +### PAUSER_ROLE +New role identifier for pauser role. + + +```solidity +bytes32 public constant PAUSER_ROLE = keccak256("PAUSER_ROLE"); +``` + + +### WITHDRAWER_ROLE +New role identifier for withdrawer role. + + +```solidity +bytes32 public constant WITHDRAWER_ROLE = keccak256("WITHDRAWER_ROLE"); +``` + + +### WHITELISTER_ROLE +New role identifier for whitelister role. + + +```solidity +bytes32 public constant WHITELISTER_ROLE = keccak256("WHITELISTER_ROLE"); +``` + + +## Functions +### constructor + +Constructor for ERC20Custody. + +*Set admin as default admin and pauser, and tssAddress as tss role.* + + +```solidity +constructor(address gateway_, address tssAddress_, address admin_); +``` + +### pause + +Pause contract. + + +```solidity +function pause() external onlyRole(PAUSER_ROLE); +``` + +### unpause + +Unpause contract. + + +```solidity +function unpause() external onlyRole(PAUSER_ROLE); +``` + +### setSupportsLegacy + +Unpause contract. + + +```solidity +function setSupportsLegacy(bool _supportsLegacy) external onlyRole(DEFAULT_ADMIN_ROLE); +``` + +### whitelist + +Whitelist ERC20 token. + + +```solidity +function whitelist(address token) external onlyRole(WHITELISTER_ROLE); +``` +**Parameters** + +|Name|Type|Description| +|----|----|-----------| +|`token`|`address`|address of ERC20 token| + + +### unwhitelist + +Unwhitelist ERC20 token. + + +```solidity +function unwhitelist(address token) external onlyRole(WHITELISTER_ROLE); +``` +**Parameters** + +|Name|Type|Description| +|----|----|-----------| +|`token`|`address`|address of ERC20 token| + + +### withdraw + +Withdraw directly transfers the tokens to the destination address without contract call. + +*This function can only be called by the TSS address.* + + +```solidity +function withdraw( + address to, + address token, + uint256 amount +) + external + nonReentrant + onlyRole(WITHDRAWER_ROLE) + whenNotPaused; +``` +**Parameters** + +|Name|Type|Description| +|----|----|-----------| +|`to`|`address`|Destination address for the tokens.| +|`token`|`address`|Address of the ERC20 token.| +|`amount`|`uint256`|Amount of tokens to withdraw.| + + +### withdrawAndCall + +WithdrawAndCall transfers tokens to Gateway and call a contract through the Gateway. + +*This function can only be called by the TSS address.* + + +```solidity +function withdrawAndCall( + address to, + address token, + uint256 amount, + bytes calldata data +) + public + nonReentrant + onlyRole(WITHDRAWER_ROLE) + whenNotPaused; +``` +**Parameters** + +|Name|Type|Description| +|----|----|-----------| +|`to`|`address`|Address of the contract to call.| +|`token`|`address`|Address of the ERC20 token.| +|`amount`|`uint256`|Amount of tokens to withdraw.| +|`data`|`bytes`|Calldata to pass to the contract call.| + + +### withdrawAndRevert + +WithdrawAndRevert transfers tokens to Gateway and call a contract with a revert functionality through +the Gateway. + +*This function can only be called by the TSS address.* + + +```solidity +function withdrawAndRevert( + address to, + address token, + uint256 amount, + bytes calldata data, + RevertContext calldata revertContext +) + public + nonReentrant + onlyRole(WITHDRAWER_ROLE) + whenNotPaused; +``` +**Parameters** + +|Name|Type|Description| +|----|----|-----------| +|`to`|`address`|Address of the contract to call.| +|`token`|`address`|Address of the ERC20 token.| +|`amount`|`uint256`|Amount of tokens to withdraw.| +|`data`|`bytes`|Calldata to pass to the contract call.| +|`revertContext`|`RevertContext`|Revert context to pass to onRevert.| + + +### deposit + +Deposits asset to custody and pay fee in zeta erc20. + + +```solidity +function deposit( + bytes calldata recipient, + IERC20 asset, + uint256 amount, + bytes calldata message +) + external + nonReentrant + whenNotPaused; +``` + diff --git a/v2/docs/src/contracts/evm/GatewayEVM.sol/contract.GatewayEVM.md b/v2/docs/src/contracts/evm/GatewayEVM.sol/contract.GatewayEVM.md new file mode 100644 index 00000000..b266db07 --- /dev/null +++ b/v2/docs/src/contracts/evm/GatewayEVM.sol/contract.GatewayEVM.md @@ -0,0 +1,480 @@ +# GatewayEVM +[Git Source](https://github.com/zeta-chain/protocol-contracts/blob/c157025a39efca61d83e5991d093a94548f342fb/contracts/evm/GatewayEVM.sol) + +**Inherits:** +Initializable, AccessControlUpgradeable, UUPSUpgradeable, [IGatewayEVM](/contracts/evm/interfaces/IGatewayEVM.sol/interface.IGatewayEVM.md), ReentrancyGuardUpgradeable, PausableUpgradeable + +The GatewayEVM contract is the endpoint to call smart contracts on external chains. + +*The contract doesn't hold any funds and should never have active allowances.* + + +## State Variables +### custody +The address of the custody contract. + + +```solidity +address public custody; +``` + + +### tssAddress +The address of the TSS (Threshold Signature Scheme) contract. + + +```solidity +address public tssAddress; +``` + + +### zetaConnector +The address of the ZetaConnector contract. + + +```solidity +address public zetaConnector; +``` + + +### zetaToken +The address of the Zeta token contract. + + +```solidity +address public zetaToken; +``` + + +### TSS_ROLE +New role identifier for tss role. + + +```solidity +bytes32 public constant TSS_ROLE = keccak256("TSS_ROLE"); +``` + + +### ASSET_HANDLER_ROLE +New role identifier for asset handler role. + + +```solidity +bytes32 public constant ASSET_HANDLER_ROLE = keccak256("ASSET_HANDLER_ROLE"); +``` + + +### PAUSER_ROLE +New role identifier for pauser role. + + +```solidity +bytes32 public constant PAUSER_ROLE = keccak256("PAUSER_ROLE"); +``` + + +## Functions +### constructor + + +```solidity +constructor(); +``` + +### initialize + +Initialize with tss address. address of zeta token and admin account set as DEFAULT_ADMIN_ROLE. + +*Using admin to authorize upgrades and pause, and tss for tss role.* + + +```solidity +function initialize(address tssAddress_, address zetaToken_, address admin_) public initializer; +``` + +### _authorizeUpgrade + +*Authorizes the upgrade of the contract, sender must be owner.* + + +```solidity +function _authorizeUpgrade(address newImplementation) internal override onlyRole(DEFAULT_ADMIN_ROLE); +``` +**Parameters** + +|Name|Type|Description| +|----|----|-----------| +|`newImplementation`|`address`|Address of the new implementation.| + + +### _execute + +*Internal function to execute a call to a destination address.* + + +```solidity +function _execute(address destination, bytes calldata data) internal returns (bytes memory); +``` +**Parameters** + +|Name|Type|Description| +|----|----|-----------| +|`destination`|`address`|Address to call.| +|`data`|`bytes`|Calldata to pass to the call.| + +**Returns** + +|Name|Type|Description| +|----|----|-----------| +|``|`bytes`|The result of the call.| + + +### pause + +Pause contract. + + +```solidity +function pause() external onlyRole(PAUSER_ROLE); +``` + +### unpause + +Unpause contract. + + +```solidity +function unpause() external onlyRole(PAUSER_ROLE); +``` + +### executeRevert + +Transfers msg.value to destination contract and executes it's onRevert function. + +*This function can only be called by the TSS address and it is payable.* + + +```solidity +function executeRevert( + address destination, + bytes calldata data, + RevertContext calldata revertContext +) + public + payable + onlyRole(TSS_ROLE) + whenNotPaused + nonReentrant; +``` +**Parameters** + +|Name|Type|Description| +|----|----|-----------| +|`destination`|`address`|Address to call.| +|`data`|`bytes`|Calldata to pass to the call.| +|`revertContext`|`RevertContext`|| + + +### execute + +Executes a 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 + nonReentrant + returns (bytes memory); +``` +**Parameters** + +|Name|Type|Description| +|----|----|-----------| +|`destination`|`address`|Address to call.| +|`data`|`bytes`|Calldata to pass to the call.| + +**Returns** + +|Name|Type|Description| +|----|----|-----------| +|``|`bytes`|The result of the call.| + + +### executeWithERC20 + +Executes a call to a destination contract using ERC20 tokens. + +*This function can only be called by the custody or connector address. +It uses the ERC20 allowance system, resetting gateway allowance at the end.* + + +```solidity +function executeWithERC20( + address token, + address to, + uint256 amount, + bytes calldata data +) + public + onlyRole(ASSET_HANDLER_ROLE) + whenNotPaused + nonReentrant; +``` +**Parameters** + +|Name|Type|Description| +|----|----|-----------| +|`token`|`address`|Address of the ERC20 token.| +|`to`|`address`|Address of the contract to call.| +|`amount`|`uint256`|Amount of tokens to transfer.| +|`data`|`bytes`|Calldata to pass to the call.| + + +### revertWithERC20 + +Directly transfers ERC20 tokens and calls onRevert. + +*This function can only be called by the custody or connector address.* + + +```solidity +function revertWithERC20( + address token, + address to, + uint256 amount, + bytes calldata data, + RevertContext calldata revertContext +) + external + onlyRole(ASSET_HANDLER_ROLE) + whenNotPaused + nonReentrant; +``` +**Parameters** + +|Name|Type|Description| +|----|----|-----------| +|`token`|`address`|Address of the ERC20 token.| +|`to`|`address`|Address of the contract to call.| +|`amount`|`uint256`|Amount of tokens to transfer.| +|`data`|`bytes`|Calldata to pass to the call.| +|`revertContext`|`RevertContext`|Revert context to pass to onRevert.| + + +### deposit + +Deposits ETH to the TSS address. + + +```solidity +function deposit(address receiver, RevertOptions calldata revertOptions) external payable whenNotPaused nonReentrant; +``` +**Parameters** + +|Name|Type|Description| +|----|----|-----------| +|`receiver`|`address`|Address of the receiver.| +|`revertOptions`|`RevertOptions`|Revert options.| + + +### deposit + +Deposits ERC20 tokens to the custody or connector contract. + + +```solidity +function deposit( + address receiver, + uint256 amount, + address asset, + RevertOptions calldata revertOptions +) + external + whenNotPaused + nonReentrant; +``` +**Parameters** + +|Name|Type|Description| +|----|----|-----------| +|`receiver`|`address`|Address of the receiver.| +|`amount`|`uint256`|Amount of tokens to deposit.| +|`asset`|`address`|Address of the ERC20 token.| +|`revertOptions`|`RevertOptions`|Revert options.| + + +### depositAndCall + +Deposits ETH to the TSS address and calls an omnichain smart contract. + + +```solidity +function depositAndCall( + address receiver, + bytes calldata payload, + RevertOptions calldata revertOptions +) + external + payable + whenNotPaused + nonReentrant; +``` +**Parameters** + +|Name|Type|Description| +|----|----|-----------| +|`receiver`|`address`|Address of the receiver.| +|`payload`|`bytes`|Calldata to pass to the call.| +|`revertOptions`|`RevertOptions`|Revert options.| + + +### depositAndCall + +Deposits ERC20 tokens to the custody or connector contract and calls an omnichain smart contract. + + +```solidity +function depositAndCall( + address receiver, + uint256 amount, + address asset, + bytes calldata payload, + RevertOptions calldata revertOptions +) + external + whenNotPaused + nonReentrant; +``` +**Parameters** + +|Name|Type|Description| +|----|----|-----------| +|`receiver`|`address`|Address of the receiver.| +|`amount`|`uint256`|Amount of tokens to deposit.| +|`asset`|`address`|Address of the ERC20 token.| +|`payload`|`bytes`|Calldata to pass to the call.| +|`revertOptions`|`RevertOptions`|Revert options.| + + +### call + +Calls an omnichain smart contract without asset transfer. + + +```solidity +function call( + address receiver, + bytes calldata payload, + RevertOptions calldata revertOptions +) + external + whenNotPaused + nonReentrant; +``` +**Parameters** + +|Name|Type|Description| +|----|----|-----------| +|`receiver`|`address`|Address of the receiver.| +|`payload`|`bytes`|Calldata to pass to the call.| +|`revertOptions`|`RevertOptions`|Revert options.| + + +### setCustody + +Sets the custody contract address. + + +```solidity +function setCustody(address custody_) external onlyRole(DEFAULT_ADMIN_ROLE); +``` +**Parameters** + +|Name|Type|Description| +|----|----|-----------| +|`custody_`|`address`|Address of the custody contract.| + + +### setConnector + +Sets the connector contract address. + + +```solidity +function setConnector(address zetaConnector_) external onlyRole(DEFAULT_ADMIN_ROLE); +``` +**Parameters** + +|Name|Type|Description| +|----|----|-----------| +|`zetaConnector_`|`address`|Address of the connector contract.| + + +### resetApproval + +*Resets the approval of a token for a specified address. +This is used to ensure that the approval is set to zero before setting it to a new value.* + + +```solidity +function resetApproval(address token, address to) private returns (bool); +``` +**Parameters** + +|Name|Type|Description| +|----|----|-----------| +|`token`|`address`|Address of the ERC20 token.| +|`to`|`address`|Address to reset the approval for.| + +**Returns** + +|Name|Type|Description| +|----|----|-----------| +|``|`bool`|True if the approval reset was successful, false otherwise.| + + +### transferFromToAssetHandler + +*Transfers tokens from the sender to the asset handler. +This function handles the transfer of tokens to either the connector or custody contract based on the asset +type.* + + +```solidity +function transferFromToAssetHandler(address from, address token, uint256 amount) private; +``` +**Parameters** + +|Name|Type|Description| +|----|----|-----------| +|`from`|`address`|Address of the sender.| +|`token`|`address`|Address of the ERC20 token.| +|`amount`|`uint256`|Amount of tokens to transfer.| + + +### transferToAssetHandler + +*Transfers tokens to the asset handler. +This function handles the transfer of tokens to either the connector or custody contract based on the asset +type.* + + +```solidity +function transferToAssetHandler(address token, uint256 amount) private; +``` +**Parameters** + +|Name|Type|Description| +|----|----|-----------| +|`token`|`address`|Address of the ERC20 token.| +|`amount`|`uint256`|Amount of tokens to transfer.| + + diff --git a/v2/docs/src/contracts/evm/README.md b/v2/docs/src/contracts/evm/README.md new file mode 100644 index 00000000..cf13d938 --- /dev/null +++ b/v2/docs/src/contracts/evm/README.md @@ -0,0 +1,9 @@ + + +# Contents +- [interfaces](/contracts/evm/interfaces) +- [ERC20Custody](ERC20Custody.sol/contract.ERC20Custody.md) +- [GatewayEVM](GatewayEVM.sol/contract.GatewayEVM.md) +- [ZetaConnectorBase](ZetaConnectorBase.sol/abstract.ZetaConnectorBase.md) +- [ZetaConnectorNative](ZetaConnectorNative.sol/contract.ZetaConnectorNative.md) +- [ZetaConnectorNonNative](ZetaConnectorNonNative.sol/contract.ZetaConnectorNonNative.md) diff --git a/v2/docs/src/contracts/evm/ZetaConnectorBase.sol/abstract.ZetaConnectorBase.md b/v2/docs/src/contracts/evm/ZetaConnectorBase.sol/abstract.ZetaConnectorBase.md new file mode 100644 index 00000000..42fc26bf --- /dev/null +++ b/v2/docs/src/contracts/evm/ZetaConnectorBase.sol/abstract.ZetaConnectorBase.md @@ -0,0 +1,173 @@ +# ZetaConnectorBase +[Git Source](https://github.com/zeta-chain/protocol-contracts/blob/c157025a39efca61d83e5991d093a94548f342fb/contracts/evm/ZetaConnectorBase.sol) + +**Inherits:** +[IZetaConnectorEvents](/contracts/evm/interfaces/IZetaConnector.sol/interface.IZetaConnectorEvents.md), ReentrancyGuard, Pausable, AccessControl + +Abstract base contract for ZetaConnector. + +*This contract implements basic functionality for handling tokens and interacting with the Gateway contract.* + + +## State Variables +### gateway +The Gateway contract used for executing cross-chain calls. + + +```solidity +IGatewayEVM public immutable gateway; +``` + + +### zetaToken +The address of the Zeta token. + + +```solidity +address public immutable zetaToken; +``` + + +### WITHDRAWER_ROLE +New role identifier for withdrawer role. + + +```solidity +bytes32 public constant WITHDRAWER_ROLE = keccak256("WITHDRAWER_ROLE"); +``` + + +### PAUSER_ROLE +New role identifier for pauser role. + + +```solidity +bytes32 public constant PAUSER_ROLE = keccak256("PAUSER_ROLE"); +``` + + +### TSS_ROLE +New role identifier for tss role. + + +```solidity +bytes32 public constant TSS_ROLE = keccak256("TSS_ROLE"); +``` + + +## Functions +### constructor + +Constructor for ZetaConnectors. + +*Set admin as default admin and pauser, and tssAddress as tss role.* + + +```solidity +constructor(address gateway_, address zetaToken_, address tssAddress_, address admin_); +``` + +### pause + +Pause contract. + + +```solidity +function pause() external onlyRole(PAUSER_ROLE); +``` + +### unpause + +Unpause contract. + + +```solidity +function unpause() external onlyRole(PAUSER_ROLE); +``` + +### withdraw + +Withdraw tokens to a specified address. + + +```solidity +function withdraw(address to, uint256 amount, bytes32 internalSendHash) external virtual; +``` +**Parameters** + +|Name|Type|Description| +|----|----|-----------| +|`to`|`address`|The address to withdraw tokens to.| +|`amount`|`uint256`|The amount of tokens to withdraw.| +|`internalSendHash`|`bytes32`|A hash used for internal tracking of the transaction.| + + +### withdrawAndCall + +Withdraw tokens and call a contract through Gateway. + + +```solidity +function withdrawAndCall(address to, uint256 amount, bytes calldata data, bytes32 internalSendHash) external virtual; +``` +**Parameters** + +|Name|Type|Description| +|----|----|-----------| +|`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.| +|`internalSendHash`|`bytes32`|A hash used for internal tracking of the transaction.| + + +### withdrawAndRevert + +Withdraw tokens and call a contract with a revert callback through Gateway. + + +```solidity +function withdrawAndRevert( + address to, + uint256 amount, + bytes calldata data, + bytes32 internalSendHash, + RevertContext calldata revertContext +) + external + virtual; +``` +**Parameters** + +|Name|Type|Description| +|----|----|-----------| +|`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.| +|`internalSendHash`|`bytes32`|A hash used for internal tracking of the transaction.| +|`revertContext`|`RevertContext`|Revert context to pass to onRevert.| + + +### receiveTokens + +Handle received tokens. + + +```solidity +function receiveTokens(uint256 amount) external virtual; +``` +**Parameters** + +|Name|Type|Description| +|----|----|-----------| +|`amount`|`uint256`|The amount of tokens received.| + + +## Errors +### ZeroAddress +Error indicating that a zero address was provided. + + +```solidity +error ZeroAddress(); +``` + diff --git a/v2/docs/src/contracts/evm/ZetaConnectorNative.sol/contract.ZetaConnectorNative.md b/v2/docs/src/contracts/evm/ZetaConnectorNative.sol/contract.ZetaConnectorNative.md new file mode 100644 index 00000000..87b292d1 --- /dev/null +++ b/v2/docs/src/contracts/evm/ZetaConnectorNative.sol/contract.ZetaConnectorNative.md @@ -0,0 +1,130 @@ +# ZetaConnectorNative +[Git Source](https://github.com/zeta-chain/protocol-contracts/blob/c157025a39efca61d83e5991d093a94548f342fb/contracts/evm/ZetaConnectorNative.sol) + +**Inherits:** +[ZetaConnectorBase](/contracts/evm/ZetaConnectorBase.sol/abstract.ZetaConnectorBase.md) + +Implementation of ZetaConnectorBase for native token handling. + +*This contract directly transfers Zeta tokens and interacts with the Gateway contract.* + + +## Functions +### constructor + + +```solidity +constructor( + address gateway_, + address zetaToken_, + address tssAddress_, + address admin_ +) + ZetaConnectorBase(gateway_, zetaToken_, tssAddress_, admin_); +``` + +### withdraw + +Withdraw tokens to a specified address. + +*This function can only be called by the TSS address.* + + +```solidity +function withdraw( + address to, + uint256 amount, + bytes32 internalSendHash +) + external + override + nonReentrant + onlyRole(WITHDRAWER_ROLE) + whenNotPaused; +``` +**Parameters** + +|Name|Type|Description| +|----|----|-----------| +|`to`|`address`|The address to withdraw tokens to.| +|`amount`|`uint256`|The amount of tokens to withdraw.| +|`internalSendHash`|`bytes32`|A hash used for internal tracking of the transaction.| + + +### withdrawAndCall + +Withdraw tokens and call a contract through Gateway. + +*This function can only be called by the TSS address.* + + +```solidity +function withdrawAndCall( + address to, + uint256 amount, + bytes calldata data, + bytes32 internalSendHash +) + external + override + nonReentrant + onlyRole(WITHDRAWER_ROLE) + whenNotPaused; +``` +**Parameters** + +|Name|Type|Description| +|----|----|-----------| +|`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.| +|`internalSendHash`|`bytes32`|A hash used for internal tracking of the transaction.| + + +### withdrawAndRevert + +Withdraw tokens and call a contract with a revert callback through Gateway. + +*This function can only be called by the TSS address.* + + +```solidity +function withdrawAndRevert( + address to, + uint256 amount, + bytes calldata data, + bytes32 internalSendHash, + RevertContext calldata revertContext +) + external + override + nonReentrant + onlyRole(WITHDRAWER_ROLE) + whenNotPaused; +``` +**Parameters** + +|Name|Type|Description| +|----|----|-----------| +|`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.| +|`internalSendHash`|`bytes32`|A hash used for internal tracking of the transaction.| +|`revertContext`|`RevertContext`|Revert context to pass to onRevert.| + + +### receiveTokens + +Handle received tokens. + + +```solidity +function receiveTokens(uint256 amount) external override whenNotPaused; +``` +**Parameters** + +|Name|Type|Description| +|----|----|-----------| +|`amount`|`uint256`|The amount of tokens received.| + + diff --git a/v2/docs/src/contracts/evm/ZetaConnectorNonNative.sol/contract.ZetaConnectorNonNative.md b/v2/docs/src/contracts/evm/ZetaConnectorNonNative.sol/contract.ZetaConnectorNonNative.md new file mode 100644 index 00000000..21492448 --- /dev/null +++ b/v2/docs/src/contracts/evm/ZetaConnectorNonNative.sol/contract.ZetaConnectorNonNative.md @@ -0,0 +1,188 @@ +# ZetaConnectorNonNative +[Git Source](https://github.com/zeta-chain/protocol-contracts/blob/c157025a39efca61d83e5991d093a94548f342fb/contracts/evm/ZetaConnectorNonNative.sol) + +**Inherits:** +[ZetaConnectorBase](/contracts/evm/ZetaConnectorBase.sol/abstract.ZetaConnectorBase.md) + +Implementation of ZetaConnectorBase for non-native token handling. + +*This contract mints and burns Zeta tokens and interacts with the Gateway contract.* + + +## State Variables +### maxSupply +Max supply for minting. + + +```solidity +uint256 public maxSupply = type(uint256).max; +``` + + +## Functions +### constructor + + +```solidity +constructor( + address gateway_, + address zetaToken_, + address tssAddress_, + address admin_ +) + ZetaConnectorBase(gateway_, zetaToken_, tssAddress_, admin_); +``` + +### setMaxSupply + +Set max supply for minting. + +*This function can only be called by the TSS address.* + + +```solidity +function setMaxSupply(uint256 maxSupply_) external onlyRole(TSS_ROLE) whenNotPaused; +``` +**Parameters** + +|Name|Type|Description| +|----|----|-----------| +|`maxSupply_`|`uint256`|New max supply.| + + +### withdraw + +Withdraw tokens to a specified address. + +*This function can only be called by the TSS address.* + + +```solidity +function withdraw( + address to, + uint256 amount, + bytes32 internalSendHash +) + external + override + nonReentrant + onlyRole(WITHDRAWER_ROLE) + whenNotPaused; +``` +**Parameters** + +|Name|Type|Description| +|----|----|-----------| +|`to`|`address`|The address to withdraw tokens to.| +|`amount`|`uint256`|The amount of tokens to withdraw.| +|`internalSendHash`|`bytes32`|A hash used for internal tracking of the transaction.| + + +### withdrawAndCall + +Withdraw tokens and call a contract through Gateway. + +*This function can only be called by the TSS address, and mints if supply is not reached.* + + +```solidity +function withdrawAndCall( + address to, + uint256 amount, + bytes calldata data, + bytes32 internalSendHash +) + external + override + nonReentrant + onlyRole(WITHDRAWER_ROLE) + whenNotPaused; +``` +**Parameters** + +|Name|Type|Description| +|----|----|-----------| +|`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.| +|`internalSendHash`|`bytes32`|A hash used for internal tracking of the transaction.| + + +### withdrawAndRevert + +Withdraw tokens and call a contract with a revert callback through Gateway. + +*This function can only be called by the TSS address, and mints if supply is not reached.* + + +```solidity +function withdrawAndRevert( + address to, + uint256 amount, + bytes calldata data, + bytes32 internalSendHash, + RevertContext calldata revertContext +) + external + override + nonReentrant + onlyRole(WITHDRAWER_ROLE) + whenNotPaused; +``` +**Parameters** + +|Name|Type|Description| +|----|----|-----------| +|`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.| +|`internalSendHash`|`bytes32`|A hash used for internal tracking of the transaction.| +|`revertContext`|`RevertContext`|Revert context to pass to onRevert.| + + +### receiveTokens + +Handle received tokens and burn them. + + +```solidity +function receiveTokens(uint256 amount) external override whenNotPaused; +``` +**Parameters** + +|Name|Type|Description| +|----|----|-----------| +|`amount`|`uint256`|The amount of tokens received.| + + +### _mintTo + +*mints to provided account and checks if totalSupply will be exceeded* + + +```solidity +function _mintTo(address to, uint256 amount, bytes32 internalSendHash) internal; +``` + +## Events +### MaxSupplyUpdated +Event triggered when max supply is updated. + + +```solidity +event MaxSupplyUpdated(uint256 maxSupply); +``` + +**Parameters** + +|Name|Type|Description| +|----|----|-----------| +|`maxSupply`|`uint256`|New max supply.| + +## Errors +### ExceedsMaxSupply + +```solidity +error ExceedsMaxSupply(); +``` + diff --git a/v2/docs/src/contracts/evm/interfaces/IERC20Custody.sol/interface.IERC20Custody.md b/v2/docs/src/contracts/evm/interfaces/IERC20Custody.sol/interface.IERC20Custody.md new file mode 100644 index 00000000..0dce2739 --- /dev/null +++ b/v2/docs/src/contracts/evm/interfaces/IERC20Custody.sol/interface.IERC20Custody.md @@ -0,0 +1,85 @@ +# IERC20Custody +[Git Source](https://github.com/zeta-chain/protocol-contracts/blob/c157025a39efca61d83e5991d093a94548f342fb/contracts/evm/interfaces/IERC20Custody.sol) + +**Inherits:** +[IERC20CustodyEvents](/contracts/evm/interfaces/IERC20Custody.sol/interface.IERC20CustodyEvents.md), [IERC20CustodyErrors](/contracts/evm/interfaces/IERC20Custody.sol/interface.IERC20CustodyErrors.md) + + +## Functions +### whitelisted + +Mapping of whitelisted tokens => true/false. + + +```solidity +function whitelisted(address token) external view returns (bool); +``` + +### withdraw + +Withdraw directly transfers the tokens to the destination address without contract call. + +*This function can only be called by the TSS address.* + + +```solidity +function withdraw(address token, address to, uint256 amount) external; +``` +**Parameters** + +|Name|Type|Description| +|----|----|-----------| +|`token`|`address`|Address of the ERC20 token.| +|`to`|`address`|Destination address for the tokens.| +|`amount`|`uint256`|Amount of tokens to withdraw.| + + +### withdrawAndCall + +WithdrawAndCall transfers tokens to Gateway and call a contract through the Gateway. + +*This function can only be called by the TSS address.* + + +```solidity +function withdrawAndCall(address token, address to, uint256 amount, bytes calldata data) external; +``` +**Parameters** + +|Name|Type|Description| +|----|----|-----------| +|`token`|`address`|Address of the ERC20 token.| +|`to`|`address`|Address of the contract to call.| +|`amount`|`uint256`|Amount of tokens to withdraw.| +|`data`|`bytes`|Calldata to pass to the contract call.| + + +### withdrawAndRevert + +WithdrawAndRevert transfers tokens to Gateway and call a contract with a revert functionality through +the Gateway. + +*This function can only be called by the TSS address.* + + +```solidity +function withdrawAndRevert( + address token, + address to, + uint256 amount, + bytes calldata data, + RevertContext calldata revertContext +) + external; +``` +**Parameters** + +|Name|Type|Description| +|----|----|-----------| +|`token`|`address`|Address of the ERC20 token.| +|`to`|`address`|Address of the contract to call.| +|`amount`|`uint256`|Amount of tokens to withdraw.| +|`data`|`bytes`|Calldata to pass to the contract call.| +|`revertContext`|`RevertContext`|Revert context to pass to onRevert.| + + diff --git a/v2/docs/src/contracts/evm/interfaces/IERC20Custody.sol/interface.IERC20CustodyErrors.md b/v2/docs/src/contracts/evm/interfaces/IERC20Custody.sol/interface.IERC20CustodyErrors.md new file mode 100644 index 00000000..2d9792af --- /dev/null +++ b/v2/docs/src/contracts/evm/interfaces/IERC20Custody.sol/interface.IERC20CustodyErrors.md @@ -0,0 +1,31 @@ +# IERC20CustodyErrors +[Git Source](https://github.com/zeta-chain/protocol-contracts/blob/c157025a39efca61d83e5991d093a94548f342fb/contracts/evm/interfaces/IERC20Custody.sol) + +Interface for the errors used in the ERC20 custody contract. + + +## Errors +### ZeroAddress +Error for zero address input. + + +```solidity +error ZeroAddress(); +``` + +### NotWhitelisted +Error for not whitelisted ERC20 token + + +```solidity +error NotWhitelisted(); +``` + +### LegacyMethodsNotSupported +Error for calling not supported legacy methods. + + +```solidity +error LegacyMethodsNotSupported(); +``` + diff --git a/v2/docs/src/contracts/evm/interfaces/IERC20Custody.sol/interface.IERC20CustodyEvents.md b/v2/docs/src/contracts/evm/interfaces/IERC20Custody.sol/interface.IERC20CustodyEvents.md new file mode 100644 index 00000000..f50b6fa9 --- /dev/null +++ b/v2/docs/src/contracts/evm/interfaces/IERC20Custody.sol/interface.IERC20CustodyEvents.md @@ -0,0 +1,96 @@ +# IERC20CustodyEvents +[Git Source](https://github.com/zeta-chain/protocol-contracts/blob/c157025a39efca61d83e5991d093a94548f342fb/contracts/evm/interfaces/IERC20Custody.sol) + +Interface for the events emitted by the ERC20 custody contract. + + +## Events +### Withdrawn +Emitted when tokens are withdrawn. + + +```solidity +event Withdrawn(address indexed to, address indexed token, uint256 amount); +``` + +**Parameters** + +|Name|Type|Description| +|----|----|-----------| +|`to`|`address`|The address receiving the tokens.| +|`token`|`address`|The address of the ERC20 token.| +|`amount`|`uint256`|The amount of tokens withdrawn.| + +### WithdrawnAndCalled +Emitted when tokens are withdrawn and a contract call is made. + + +```solidity +event WithdrawnAndCalled(address indexed to, address indexed token, uint256 amount, bytes data); +``` + +**Parameters** + +|Name|Type|Description| +|----|----|-----------| +|`to`|`address`|The address receiving the tokens.| +|`token`|`address`|The address of the ERC20 token.| +|`amount`|`uint256`|The amount of tokens withdrawn.| +|`data`|`bytes`|The calldata passed to the contract call.| + +### WithdrawnAndReverted +Emitted when tokens are withdrawn and a revertable contract call is made. + + +```solidity +event WithdrawnAndReverted( + address indexed to, address indexed token, uint256 amount, bytes data, RevertContext revertContext +); +``` + +**Parameters** + +|Name|Type|Description| +|----|----|-----------| +|`to`|`address`|The address receiving the tokens.| +|`token`|`address`|The address of the ERC20 token.| +|`amount`|`uint256`|The amount of tokens withdrawn.| +|`data`|`bytes`|The calldata passed to the contract call.| +|`revertContext`|`RevertContext`|Revert context to pass to onRevert.| + +### Whitelisted +Emitted when ERC20 token is whitelisted + + +```solidity +event Whitelisted(address indexed token); +``` + +**Parameters** + +|Name|Type|Description| +|----|----|-----------| +|`token`|`address`|address of ERC20 token.| + +### Unwhitelisted +Emitted when ERC20 token is unwhitelisted + + +```solidity +event Unwhitelisted(address indexed token); +``` + +**Parameters** + +|Name|Type|Description| +|----|----|-----------| +|`token`|`address`|address of ERC20 token.| + +### Deposited +Emitted in legacy deposit method. + + +```solidity +event Deposited(bytes recipient, IERC20 indexed asset, uint256 amount, bytes message); +``` + diff --git a/v2/docs/src/contracts/evm/interfaces/IGatewayEVM.sol/interface.IGatewayEVM.md b/v2/docs/src/contracts/evm/interfaces/IGatewayEVM.sol/interface.IGatewayEVM.md new file mode 100644 index 00000000..5f3ec5e4 --- /dev/null +++ b/v2/docs/src/contracts/evm/interfaces/IGatewayEVM.sol/interface.IGatewayEVM.md @@ -0,0 +1,201 @@ +# IGatewayEVM +[Git Source](https://github.com/zeta-chain/protocol-contracts/blob/c157025a39efca61d83e5991d093a94548f342fb/contracts/evm/interfaces/IGatewayEVM.sol) + +**Inherits:** +[IGatewayEVMErrors](/contracts/evm/interfaces/IGatewayEVM.sol/interface.IGatewayEVMErrors.md), [IGatewayEVMEvents](/contracts/evm/interfaces/IGatewayEVM.sol/interface.IGatewayEVMEvents.md) + +Interface for the GatewayEVM contract. + + +## Functions +### executeWithERC20 + +Executes a call to a contract using ERC20 tokens. + + +```solidity +function executeWithERC20(address token, address to, uint256 amount, bytes calldata data) external; +``` +**Parameters** + +|Name|Type|Description| +|----|----|-----------| +|`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.| +|`data`|`bytes`|The calldata to pass to the contract call.| + + +### executeRevert + +Transfers msg.value to destination contract and executes it's onRevert function. + +*This function can only be called by the TSS address and it is payable.* + + +```solidity +function executeRevert( + address destination, + bytes calldata data, + RevertContext calldata revertContext +) + external + payable; +``` +**Parameters** + +|Name|Type|Description| +|----|----|-----------| +|`destination`|`address`|Address to call.| +|`data`|`bytes`|Calldata to pass to the call.| +|`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| +|----|----|-----------| +|``|`bytes`|The result of the contract call.| + + +### revertWithERC20 + +Executes a revertable call to a contract using ERC20 tokens. + + +```solidity +function revertWithERC20( + address token, + address to, + uint256 amount, + bytes calldata data, + RevertContext calldata revertContext +) + external; +``` +**Parameters** + +|Name|Type|Description| +|----|----|-----------| +|`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.| +|`data`|`bytes`|The calldata to pass to the contract call.| +|`revertContext`|`RevertContext`|Revert context to pass to onRevert.| + + +### deposit + +Deposits ETH to the TSS address. + + +```solidity +function deposit(address receiver, RevertOptions calldata revertOptions) external payable; +``` +**Parameters** + +|Name|Type|Description| +|----|----|-----------| +|`receiver`|`address`|Address of the receiver.| +|`revertOptions`|`RevertOptions`|Revert options.| + + +### deposit + +Deposits ERC20 tokens to the custody or connector contract. + + +```solidity +function deposit(address receiver, uint256 amount, address asset, RevertOptions calldata revertOptions) external; +``` +**Parameters** + +|Name|Type|Description| +|----|----|-----------| +|`receiver`|`address`|Address of the receiver.| +|`amount`|`uint256`|Amount of tokens to deposit.| +|`asset`|`address`|Address of the ERC20 token.| +|`revertOptions`|`RevertOptions`|Revert options.| + + +### depositAndCall + +Deposits ETH to the TSS address and calls an omnichain smart contract. + + +```solidity +function depositAndCall( + address receiver, + bytes calldata payload, + RevertOptions calldata revertOptions +) + external + payable; +``` +**Parameters** + +|Name|Type|Description| +|----|----|-----------| +|`receiver`|`address`|Address of the receiver.| +|`payload`|`bytes`|Calldata to pass to the call.| +|`revertOptions`|`RevertOptions`|Revert options.| + + +### depositAndCall + +Deposits ERC20 tokens to the custody or connector contract and calls an omnichain smart contract. + + +```solidity +function depositAndCall( + address receiver, + uint256 amount, + address asset, + bytes calldata payload, + RevertOptions calldata revertOptions +) + external; +``` +**Parameters** + +|Name|Type|Description| +|----|----|-----------| +|`receiver`|`address`|Address of the receiver.| +|`amount`|`uint256`|Amount of tokens to deposit.| +|`asset`|`address`|Address of the ERC20 token.| +|`payload`|`bytes`|Calldata to pass to the call.| +|`revertOptions`|`RevertOptions`|Revert options.| + + +### call + +Calls an omnichain smart contract without asset transfer. + + +```solidity +function call(address receiver, bytes calldata payload, RevertOptions calldata revertOptions) external; +``` +**Parameters** + +|Name|Type|Description| +|----|----|-----------| +|`receiver`|`address`|Address of the receiver.| +|`payload`|`bytes`|Calldata to pass to the call.| +|`revertOptions`|`RevertOptions`|Revert options.| + + diff --git a/v2/docs/src/contracts/evm/interfaces/IGatewayEVM.sol/interface.IGatewayEVMErrors.md b/v2/docs/src/contracts/evm/interfaces/IGatewayEVM.sol/interface.IGatewayEVMErrors.md new file mode 100644 index 00000000..72f91335 --- /dev/null +++ b/v2/docs/src/contracts/evm/interfaces/IGatewayEVM.sol/interface.IGatewayEVMErrors.md @@ -0,0 +1,79 @@ +# IGatewayEVMErrors +[Git Source](https://github.com/zeta-chain/protocol-contracts/blob/c157025a39efca61d83e5991d093a94548f342fb/contracts/evm/interfaces/IGatewayEVM.sol) + +Interface for the errors used in the GatewayEVM contract. + + +## Errors +### ExecutionFailed +Error for failed execution. + + +```solidity +error ExecutionFailed(); +``` + +### DepositFailed +Error for failed deposit. + + +```solidity +error DepositFailed(); +``` + +### InsufficientETHAmount +Error for insufficient ETH amount. + + +```solidity +error InsufficientETHAmount(); +``` + +### InsufficientERC20Amount +Error for insufficient ERC20 token amount. + + +```solidity +error InsufficientERC20Amount(); +``` + +### ZeroAddress +Error for zero address input. + + +```solidity +error ZeroAddress(); +``` + +### ApprovalFailed +Error for failed token approval. + + +```solidity +error ApprovalFailed(); +``` + +### CustodyInitialized +Error for already initialized custody. + + +```solidity +error CustodyInitialized(); +``` + +### ConnectorInitialized +Error for already initialized connector. + + +```solidity +error ConnectorInitialized(); +``` + +### NotWhitelistedInCustody +Error when trying to transfer not whitelisted token to custody. + + +```solidity +error NotWhitelistedInCustody(); +``` + diff --git a/v2/docs/src/contracts/evm/interfaces/IGatewayEVM.sol/interface.IGatewayEVMEvents.md b/v2/docs/src/contracts/evm/interfaces/IGatewayEVM.sol/interface.IGatewayEVMEvents.md new file mode 100644 index 00000000..a59ed493 --- /dev/null +++ b/v2/docs/src/contracts/evm/interfaces/IGatewayEVM.sol/interface.IGatewayEVMEvents.md @@ -0,0 +1,101 @@ +# IGatewayEVMEvents +[Git Source](https://github.com/zeta-chain/protocol-contracts/blob/c157025a39efca61d83e5991d093a94548f342fb/contracts/evm/interfaces/IGatewayEVM.sol) + +Interface for the events emitted by the GatewayEVM contract. + + +## Events +### Executed +Emitted when a contract call is executed. + + +```solidity +event Executed(address indexed destination, uint256 value, bytes data); +``` + +**Parameters** + +|Name|Type|Description| +|----|----|-----------| +|`destination`|`address`|The address of the contract called.| +|`value`|`uint256`|The amount of ETH sent with the call.| +|`data`|`bytes`|The calldata passed to the contract call.| + +### Reverted +Emitted when a contract call is reverted. + + +```solidity +event Reverted(address indexed to, address indexed token, uint256 amount, bytes data, RevertContext revertContext); +``` + +**Parameters** + +|Name|Type|Description| +|----|----|-----------| +|`to`|`address`|The address of the contract called.| +|`token`|`address`|The address of the ERC20 token, empty if gas token| +|`amount`|`uint256`|The amount of ETH sent with the call.| +|`data`|`bytes`|The calldata passed to the contract call.| +|`revertContext`|`RevertContext`|Revert context to pass to onRevert.| + +### ExecutedWithERC20 +Emitted when a contract call with ERC20 tokens is executed. + + +```solidity +event ExecutedWithERC20(address indexed token, address indexed to, uint256 amount, bytes data); +``` + +**Parameters** + +|Name|Type|Description| +|----|----|-----------| +|`token`|`address`|The address of the ERC20 token.| +|`to`|`address`|The address of the contract called.| +|`amount`|`uint256`|The amount of tokens transferred.| +|`data`|`bytes`|The calldata passed to the contract call.| + +### Deposited +Emitted when a deposit is made. + + +```solidity +event Deposited( + 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.| +|`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.| +|`revertOptions`|`RevertOptions`|Revert options.| + +### Called +Emitted when an omnichain smart contract call is made without asset transfer. + + +```solidity +event Called(address indexed sender, address indexed receiver, bytes payload, RevertOptions revertOptions); +``` + +**Parameters** + +|Name|Type|Description| +|----|----|-----------| +|`sender`|`address`|The address of the sender.| +|`receiver`|`address`|The address of the receiver.| +|`payload`|`bytes`|The calldata passed to the call.| +|`revertOptions`|`RevertOptions`|Revert options.| + diff --git a/v2/docs/src/contracts/evm/interfaces/IZetaConnector.sol/interface.IZetaConnectorEvents.md b/v2/docs/src/contracts/evm/interfaces/IZetaConnector.sol/interface.IZetaConnectorEvents.md new file mode 100644 index 00000000..f1ba7798 --- /dev/null +++ b/v2/docs/src/contracts/evm/interfaces/IZetaConnector.sol/interface.IZetaConnectorEvents.md @@ -0,0 +1,55 @@ +# IZetaConnectorEvents +[Git Source](https://github.com/zeta-chain/protocol-contracts/blob/c157025a39efca61d83e5991d093a94548f342fb/contracts/evm/interfaces/IZetaConnector.sol) + +Interface for the events emitted by the ZetaConnector contracts. + + +## Events +### Withdrawn +Emitted when tokens are withdrawn. + + +```solidity +event Withdrawn(address indexed to, uint256 amount); +``` + +**Parameters** + +|Name|Type|Description| +|----|----|-----------| +|`to`|`address`|The address to which the tokens are withdrawn.| +|`amount`|`uint256`|The amount of tokens withdrawn.| + +### WithdrawnAndCalled +Emitted when tokens are withdrawn and a contract is called. + + +```solidity +event WithdrawnAndCalled(address indexed to, uint256 amount, bytes data); +``` + +**Parameters** + +|Name|Type|Description| +|----|----|-----------| +|`to`|`address`|The address to which the tokens are withdrawn.| +|`amount`|`uint256`|The amount of tokens withdrawn.| +|`data`|`bytes`|The calldata passed to the contract call.| + +### WithdrawnAndReverted +Emitted when tokens are withdrawn and a contract is called with a revert callback. + + +```solidity +event WithdrawnAndReverted(address indexed to, uint256 amount, bytes data, RevertContext revertContext); +``` + +**Parameters** + +|Name|Type|Description| +|----|----|-----------| +|`to`|`address`|The address to which the tokens are withdrawn.| +|`amount`|`uint256`|The amount of tokens withdrawn.| +|`data`|`bytes`|The calldata passed to the contract call.| +|`revertContext`|`RevertContext`|Revert context to pass to onRevert.| + diff --git a/v2/docs/src/contracts/evm/interfaces/IZetaNonEthNew.sol/interface.IZetaNonEthNew.md b/v2/docs/src/contracts/evm/interfaces/IZetaNonEthNew.sol/interface.IZetaNonEthNew.md new file mode 100644 index 00000000..a7a370f0 --- /dev/null +++ b/v2/docs/src/contracts/evm/interfaces/IZetaNonEthNew.sol/interface.IZetaNonEthNew.md @@ -0,0 +1,47 @@ +# IZetaNonEthNew +[Git Source](https://github.com/zeta-chain/protocol-contracts/blob/c157025a39efca61d83e5991d093a94548f342fb/contracts/evm/interfaces/IZetaNonEthNew.sol) + +**Inherits:** +IERC20 + +IZetaNonEthNew is a mintable / burnable version of IERC20. + + +## Functions +### burnFrom + +Burns the specified amount of tokens from the specified account. + +*Emits a {Transfer} event with `to` set to the zero address.* + + +```solidity +function burnFrom(address account, uint256 amount) external; +``` +**Parameters** + +|Name|Type|Description| +|----|----|-----------| +|`account`|`address`|The address of the account from which tokens will be burned.| +|`amount`|`uint256`|The amount of tokens to burn.| + + +### mint + +Mints the specified amount of tokens to the specified account. + +*Emits a {Transfer} event with `from` set to the zero address.* + + +```solidity +function mint(address mintee, uint256 value, bytes32 internalSendHash) external; +``` +**Parameters** + +|Name|Type|Description| +|----|----|-----------| +|`mintee`|`address`|The address of the account to which tokens will be minted.| +|`value`|`uint256`|The amount of tokens to mint.| +|`internalSendHash`|`bytes32`|A hash used for internal tracking of the minting transaction.| + + diff --git a/v2/docs/src/contracts/evm/interfaces/README.md b/v2/docs/src/contracts/evm/interfaces/README.md new file mode 100644 index 00000000..1c636c76 --- /dev/null +++ b/v2/docs/src/contracts/evm/interfaces/README.md @@ -0,0 +1,11 @@ + + +# Contents +- [IERC20CustodyEvents](IERC20Custody.sol/interface.IERC20CustodyEvents.md) +- [IERC20CustodyErrors](IERC20Custody.sol/interface.IERC20CustodyErrors.md) +- [IERC20Custody](IERC20Custody.sol/interface.IERC20Custody.md) +- [IGatewayEVMEvents](IGatewayEVM.sol/interface.IGatewayEVMEvents.md) +- [IGatewayEVMErrors](IGatewayEVM.sol/interface.IGatewayEVMErrors.md) +- [IGatewayEVM](IGatewayEVM.sol/interface.IGatewayEVM.md) +- [IZetaConnectorEvents](IZetaConnector.sol/interface.IZetaConnectorEvents.md) +- [IZetaNonEthNew](IZetaNonEthNew.sol/interface.IZetaNonEthNew.md) diff --git a/v2/docs/src/contracts/zevm/GatewayZEVM.sol/contract.GatewayZEVM.md b/v2/docs/src/contracts/zevm/GatewayZEVM.sol/contract.GatewayZEVM.md new file mode 100644 index 00000000..360fa048 --- /dev/null +++ b/v2/docs/src/contracts/zevm/GatewayZEVM.sol/contract.GatewayZEVM.md @@ -0,0 +1,458 @@ +# GatewayZEVM +[Git Source](https://github.com/zeta-chain/protocol-contracts/blob/c157025a39efca61d83e5991d093a94548f342fb/contracts/zevm/GatewayZEVM.sol) + +**Inherits:** +[IGatewayZEVM](/contracts/zevm/interfaces/IGatewayZEVM.sol/interface.IGatewayZEVM.md), Initializable, AccessControlUpgradeable, UUPSUpgradeable, ReentrancyGuardUpgradeable, PausableUpgradeable + +The GatewayZEVM contract is the endpoint to call smart contracts on omnichain. + +*The contract doesn't hold any funds and should never have active allowances.* + + +## State Variables +### FUNGIBLE_MODULE_ADDRESS +The constant address of the Fungible module. + + +```solidity +address public constant FUNGIBLE_MODULE_ADDRESS = 0x735b14BB79463307AAcBED86DAf3322B1e6226aB; +``` + + +### zetaToken +The address of the Zeta token. + + +```solidity +address public zetaToken; +``` + + +### PAUSER_ROLE +New role identifier for pauser role. + + +```solidity +bytes32 public constant PAUSER_ROLE = keccak256("PAUSER_ROLE"); +``` + + +## Functions +### onlyFungible + +*Only Fungible module address allowed modifier.* + + +```solidity +modifier onlyFungible(); +``` + +### constructor + + +```solidity +constructor(); +``` + +### initialize + +Initialize with address of zeta token and admin account set as DEFAULT_ADMIN_ROLE. + +*Using admin to authorize upgrades and pause.* + + +```solidity +function initialize(address zetaToken_, address admin_) public initializer; +``` + +### _authorizeUpgrade + +*Authorizes the upgrade of the contract.* + + +```solidity +function _authorizeUpgrade(address newImplementation) internal override onlyRole(DEFAULT_ADMIN_ROLE); +``` +**Parameters** + +|Name|Type|Description| +|----|----|-----------| +|`newImplementation`|`address`|The address of the new implementation.| + + +### receive + +*Receive function to receive ZETA from WETH9.withdraw().* + + +```solidity +receive() external payable whenNotPaused; +``` + +### pause + +Pause contract. + + +```solidity +function pause() external onlyRole(PAUSER_ROLE); +``` + +### unpause + +Unpause contract. + + +```solidity +function unpause() external onlyRole(PAUSER_ROLE); +``` + +### _withdrawZRC20 + +*Internal function to withdraw ZRC20 tokens.* + + +```solidity +function _withdrawZRC20(uint256 amount, address zrc20) internal returns (uint256); +``` +**Parameters** + +|Name|Type|Description| +|----|----|-----------| +|`amount`|`uint256`|The amount of tokens to withdraw.| +|`zrc20`|`address`|The address of the ZRC20 token.| + +**Returns** + +|Name|Type|Description| +|----|----|-----------| +|``|`uint256`|The gas fee for the withdrawal.| + + +### _withdrawZRC20WithGasLimit + +*Internal function to withdraw ZRC20 tokens with gas limit.* + + +```solidity +function _withdrawZRC20WithGasLimit(uint256 amount, address zrc20, uint256 gasLimit) internal returns (uint256); +``` +**Parameters** + +|Name|Type|Description| +|----|----|-----------| +|`amount`|`uint256`|The amount of tokens to withdraw.| +|`zrc20`|`address`|The address of the ZRC20 token.| +|`gasLimit`|`uint256`|Gas limit.| + +**Returns** + +|Name|Type|Description| +|----|----|-----------| +|``|`uint256`|The gas fee for the withdrawal.| + + +### _transferZETA + +*Internal function to transfer ZETA tokens.* + + +```solidity +function _transferZETA(uint256 amount, address to) internal; +``` +**Parameters** + +|Name|Type|Description| +|----|----|-----------| +|`amount`|`uint256`|The amount of tokens to transfer.| +|`to`|`address`|The address to transfer the tokens to.| + + +### withdraw + +Withdraw ZRC20 tokens to an external chain. + + +```solidity +function withdraw( + bytes memory receiver, + uint256 amount, + address zrc20, + RevertOptions calldata revertOptions +) + external + nonReentrant + whenNotPaused; +``` +**Parameters** + +|Name|Type|Description| +|----|----|-----------| +|`receiver`|`bytes`|The receiver address on the external chain.| +|`amount`|`uint256`|The amount of tokens to withdraw.| +|`zrc20`|`address`|The address of the ZRC20 token.| +|`revertOptions`|`RevertOptions`|Revert options.| + + +### withdrawAndCall + +Withdraw ZRC20 tokens and call a smart contract on an external chain. + + +```solidity +function withdrawAndCall( + bytes memory receiver, + uint256 amount, + address zrc20, + bytes calldata message, + uint256 gasLimit, + RevertOptions calldata revertOptions +) + external + nonReentrant + whenNotPaused; +``` +**Parameters** + +|Name|Type|Description| +|----|----|-----------| +|`receiver`|`bytes`|The receiver address on the external chain.| +|`amount`|`uint256`|The amount of tokens to withdraw.| +|`zrc20`|`address`|The address of the ZRC20 token.| +|`message`|`bytes`|The calldata to pass to the contract call.| +|`gasLimit`|`uint256`|Gas limit.| +|`revertOptions`|`RevertOptions`|Revert options.| + + +### withdraw + +Withdraw ZETA tokens to an external chain. + + +```solidity +function withdraw( + bytes memory receiver, + uint256 amount, + uint256 chainId, + RevertOptions calldata revertOptions +) + external + nonReentrant + whenNotPaused; +``` +**Parameters** + +|Name|Type|Description| +|----|----|-----------| +|`receiver`|`bytes`|The receiver address on the external chain.| +|`amount`|`uint256`|The amount of tokens to withdraw.| +|`chainId`|`uint256`|| +|`revertOptions`|`RevertOptions`|Revert options.| + + +### withdrawAndCall + +Withdraw ZETA tokens and call a smart contract on an external chain. + + +```solidity +function withdrawAndCall( + bytes memory receiver, + uint256 amount, + uint256 chainId, + bytes calldata message, + RevertOptions calldata revertOptions +) + external + nonReentrant + whenNotPaused; +``` +**Parameters** + +|Name|Type|Description| +|----|----|-----------| +|`receiver`|`bytes`|The receiver address on the external chain.| +|`amount`|`uint256`|The amount of tokens to withdraw.| +|`chainId`|`uint256`|Chain id of the external chain.| +|`message`|`bytes`|The calldata to pass to the contract call.| +|`revertOptions`|`RevertOptions`|Revert options.| + + +### call + +Call a smart contract on an external chain without asset transfer. + + +```solidity +function call( + bytes memory receiver, + address zrc20, + bytes calldata message, + uint256 gasLimit, + RevertOptions calldata revertOptions +) + external + nonReentrant + whenNotPaused; +``` +**Parameters** + +|Name|Type|Description| +|----|----|-----------| +|`receiver`|`bytes`|The receiver address on the external chain.| +|`zrc20`|`address`|Address of zrc20 to pay fees.| +|`message`|`bytes`|The calldata to pass to the contract call.| +|`gasLimit`|`uint256`|Gas limit.| +|`revertOptions`|`RevertOptions`|Revert options.| + + +### deposit + +Deposit foreign coins into ZRC20. + + +```solidity +function deposit(address zrc20, uint256 amount, address target) external onlyFungible whenNotPaused; +``` +**Parameters** + +|Name|Type|Description| +|----|----|-----------| +|`zrc20`|`address`|The address of the ZRC20 token.| +|`amount`|`uint256`|The amount of tokens to deposit.| +|`target`|`address`|The target address to receive the deposited tokens.| + + +### execute + +Execute a user-specified contract on ZEVM. + + +```solidity +function execute( + zContext calldata context, + address zrc20, + uint256 amount, + address target, + bytes calldata message +) + external + onlyFungible + whenNotPaused; +``` +**Parameters** + +|Name|Type|Description| +|----|----|-----------| +|`context`|`zContext`|The context of the cross-chain call.| +|`zrc20`|`address`|The address of the ZRC20 token.| +|`amount`|`uint256`|The amount of tokens to transfer.| +|`target`|`address`|The target contract to call.| +|`message`|`bytes`|The calldata to pass to the contract call.| + + +### depositAndCall + +Deposit foreign coins into ZRC20 and call a user-specified contract on ZEVM. + + +```solidity +function depositAndCall( + zContext calldata context, + address zrc20, + uint256 amount, + address target, + bytes calldata message +) + external + onlyFungible + whenNotPaused; +``` +**Parameters** + +|Name|Type|Description| +|----|----|-----------| +|`context`|`zContext`|The context of the cross-chain call.| +|`zrc20`|`address`|The address of the ZRC20 token.| +|`amount`|`uint256`|The amount of tokens to transfer.| +|`target`|`address`|The target contract to call.| +|`message`|`bytes`|The calldata to pass to the contract call.| + + +### depositAndCall + +Deposit ZETA and call a user-specified contract on ZEVM. + + +```solidity +function depositAndCall( + zContext calldata context, + uint256 amount, + address target, + bytes calldata message +) + external + onlyFungible + whenNotPaused; +``` +**Parameters** + +|Name|Type|Description| +|----|----|-----------| +|`context`|`zContext`|The context of the cross-chain call.| +|`amount`|`uint256`|The amount of tokens to transfer.| +|`target`|`address`|The target contract to call.| +|`message`|`bytes`|The calldata to pass to the contract call.| + + +### executeRevert + +Revert a user-specified contract on ZEVM. + + +```solidity +function executeRevert(address target, RevertContext calldata revertContext) external onlyFungible whenNotPaused; +``` +**Parameters** + +|Name|Type|Description| +|----|----|-----------| +|`target`|`address`|The target contract to call.| +|`revertContext`|`RevertContext`|Revert context to pass to onRevert.| + + +### depositAndRevert + +Deposit foreign coins into ZRC20 and revert a user-specified contract on ZEVM. + + +```solidity +function depositAndRevert( + address zrc20, + uint256 amount, + address target, + RevertContext calldata revertContext +) + external + onlyFungible + whenNotPaused; +``` +**Parameters** + +|Name|Type|Description| +|----|----|-----------| +|`zrc20`|`address`|The address of the ZRC20 token.| +|`amount`|`uint256`|The amount of tokens to revert.| +|`target`|`address`|The target contract to call.| +|`revertContext`|`RevertContext`|Revert context to pass to onRevert.| + + +## Errors +### ZeroAddress +Error indicating a zero address was provided. + + +```solidity +error ZeroAddress(); +``` + diff --git a/v2/docs/src/contracts/zevm/README.md b/v2/docs/src/contracts/zevm/README.md new file mode 100644 index 00000000..6bff934d --- /dev/null +++ b/v2/docs/src/contracts/zevm/README.md @@ -0,0 +1,7 @@ + + +# Contents +- [interfaces](/contracts/zevm/interfaces) +- [GatewayZEVM](GatewayZEVM.sol/contract.GatewayZEVM.md) +- [ZRC20Errors](ZRC20.sol/interface.ZRC20Errors.md) +- [ZRC20](ZRC20.sol/contract.ZRC20.md) diff --git a/v2/docs/src/contracts/zevm/ZRC20.sol/contract.ZRC20.md b/v2/docs/src/contracts/zevm/ZRC20.sol/contract.ZRC20.md new file mode 100644 index 00000000..c2ddc955 --- /dev/null +++ b/v2/docs/src/contracts/zevm/ZRC20.sol/contract.ZRC20.md @@ -0,0 +1,531 @@ +# ZRC20 +[Git Source](https://github.com/zeta-chain/protocol-contracts/blob/c157025a39efca61d83e5991d093a94548f342fb/contracts/zevm/ZRC20.sol) + +**Inherits:** +[IZRC20Metadata](/contracts/zevm/interfaces/IZRC20.sol/interface.IZRC20Metadata.md), [ZRC20Errors](/contracts/zevm/ZRC20.sol/interface.ZRC20Errors.md), [ZRC20Events](/contracts/zevm/interfaces/IZRC20.sol/interface.ZRC20Events.md) + + +## State Variables +### FUNGIBLE_MODULE_ADDRESS +Fungible address is always the same, maintained at the protocol level + + +```solidity +address public constant FUNGIBLE_MODULE_ADDRESS = 0x735b14BB79463307AAcBED86DAf3322B1e6226aB; +``` + + +### CHAIN_ID +Chain id.abi + + +```solidity +uint256 public immutable CHAIN_ID; +``` + + +### COIN_TYPE +Coin type, checkout Interfaces.sol. + + +```solidity +CoinType public immutable COIN_TYPE; +``` + + +### SYSTEM_CONTRACT_ADDRESS +System contract address. + +*Name is in upper case to maintain compatibility with ZRC20.sol v1* + + +```solidity +address public SYSTEM_CONTRACT_ADDRESS; +``` + + +### GAS_LIMIT +Gas limit. + +*Name is in upper case to maintain compatibility with ZRC20.sol v1* + + +```solidity +uint256 public GAS_LIMIT; +``` + + +### PROTOCOL_FLAT_FEE +Protocol flat fee. + +*Name is in upper case to maintain compatibility with ZRC20.sol v1* + + +```solidity +uint256 public override PROTOCOL_FLAT_FEE; +``` + + +### _balances + +```solidity +mapping(address => uint256) private _balances; +``` + + +### _allowances + +```solidity +mapping(address => mapping(address => uint256)) private _allowances; +``` + + +### _totalSupply + +```solidity +uint256 private _totalSupply; +``` + + +### _name + +```solidity +string private _name; +``` + + +### _symbol + +```solidity +string private _symbol; +``` + + +### _decimals + +```solidity +uint8 private _decimals; +``` + + +### gatewayAddress +Gateway contract address. + +*This variable is added at last position to maintain storage layout with ZRC20.sol v1* + + +```solidity +address public gatewayAddress; +``` + + +## Functions +### _msgSender + + +```solidity +function _msgSender() internal view virtual returns (address); +``` + +### onlyFungible + +*Only fungible module modifier.* + + +```solidity +modifier onlyFungible(); +``` + +### constructor + +*The only one allowed to deploy new ZRC20 is fungible address.* + + +```solidity +constructor( + string memory name_, + string memory symbol_, + uint8 decimals_, + uint256 chainid_, + CoinType coinType_, + uint256 gasLimit_, + address systemContractAddress_, + address gatewayAddress_ +); +``` + +### name + +*ZRC20 name* + + +```solidity +function name() public view virtual override returns (string memory); +``` +**Returns** + +|Name|Type|Description| +|----|----|-----------| +|``|`string`|name as string| + + +### setName + +*Name can be updated by fungible module account.* + + +```solidity +function setName(string memory newName) external override onlyFungible; +``` + +### setSymbol + +*Symbol can be updated by fungible module account.* + + +```solidity +function setSymbol(string memory newSymbol) external override onlyFungible; +``` + +### symbol + +*ZRC20 symbol.* + + +```solidity +function symbol() public view virtual override returns (string memory); +``` +**Returns** + +|Name|Type|Description| +|----|----|-----------| +|``|`string`|symbol as string.| + + +### decimals + +*ZRC20 decimals.* + + +```solidity +function decimals() public view virtual override returns (uint8); +``` +**Returns** + +|Name|Type|Description| +|----|----|-----------| +|``|`uint8`|returns uint8 decimals.| + + +### totalSupply + +*ZRC20 total supply.* + + +```solidity +function totalSupply() public view virtual override returns (uint256); +``` +**Returns** + +|Name|Type|Description| +|----|----|-----------| +|``|`uint256`|returns uint256 total supply.| + + +### balanceOf + +*Returns ZRC20 balance of an account.* + + +```solidity +function balanceOf(address account) public view virtual override returns (uint256); +``` +**Parameters** + +|Name|Type|Description| +|----|----|-----------| +|`account`|`address`|| + +**Returns** + +|Name|Type|Description| +|----|----|-----------| +|``|`uint256`|uint256 account balance.| + + +### transfer + +*Returns ZRC20 balance of an account.* + + +```solidity +function transfer(address recipient, uint256 amount) public virtual override returns (bool); +``` +**Parameters** + +|Name|Type|Description| +|----|----|-----------| +|`recipient`|`address`|| +|`amount`|`uint256`|| + +**Returns** + +|Name|Type|Description| +|----|----|-----------| +|``|`bool`|true/false if transfer succeeded/failed.| + + +### allowance + +*Returns token allowance from owner to spender.* + + +```solidity +function allowance(address owner, address spender) public view virtual override returns (uint256); +``` +**Parameters** + +|Name|Type|Description| +|----|----|-----------| +|`owner`|`address`|| +|`spender`|`address`|| + +**Returns** + +|Name|Type|Description| +|----|----|-----------| +|``|`uint256`|uint256 allowance.| + + +### approve + +*Approves amount transferFrom for spender.* + + +```solidity +function approve(address spender, uint256 amount) public virtual override returns (bool); +``` +**Parameters** + +|Name|Type|Description| +|----|----|-----------| +|`spender`|`address`|| +|`amount`|`uint256`|| + +**Returns** + +|Name|Type|Description| +|----|----|-----------| +|``|`bool`|true/false if succeeded/failed.| + + +### transferFrom + +*Transfers tokens from sender to recipient.* + + +```solidity +function transferFrom(address sender, address recipient, uint256 amount) public virtual override returns (bool); +``` +**Parameters** + +|Name|Type|Description| +|----|----|-----------| +|`sender`|`address`|| +|`recipient`|`address`|| +|`amount`|`uint256`|| + +**Returns** + +|Name|Type|Description| +|----|----|-----------| +|``|`bool`|true/false if succeeded/failed.| + + +### burn + +*Burns an amount of tokens.* + + +```solidity +function burn(uint256 amount) external override returns (bool); +``` +**Parameters** + +|Name|Type|Description| +|----|----|-----------| +|`amount`|`uint256`|| + +**Returns** + +|Name|Type|Description| +|----|----|-----------| +|``|`bool`|true/false if succeeded/failed.| + + +### _transfer + + +```solidity +function _transfer(address sender, address recipient, uint256 amount) internal virtual; +``` + +### _mint + + +```solidity +function _mint(address account, uint256 amount) internal virtual; +``` + +### _burn + + +```solidity +function _burn(address account, uint256 amount) internal virtual; +``` + +### _approve + + +```solidity +function _approve(address owner, address spender, uint256 amount) internal virtual; +``` + +### deposit + +*Deposits corresponding tokens from external chain, only callable by Fungible module.* + + +```solidity +function deposit(address to, uint256 amount) external override returns (bool); +``` +**Parameters** + +|Name|Type|Description| +|----|----|-----------| +|`to`|`address`|| +|`amount`|`uint256`|| + +**Returns** + +|Name|Type|Description| +|----|----|-----------| +|``|`bool`|true/false if succeeded/failed.| + + +### withdrawGasFee + +*Withdraws gas fees.* + + +```solidity +function withdrawGasFee() public view override returns (address, uint256); +``` +**Returns** + +|Name|Type|Description| +|----|----|-----------| +|``|`address`|returns the ZRC20 address for gas on the same chain of this ZRC20, and calculates the gas fee for withdraw()| +|``|`uint256`|| + + +### withdrawGasFeeWithGasLimit + +*Withdraws gas fees with specified gasLimit* + + +```solidity +function withdrawGasFeeWithGasLimit(uint256 gasLimit) public view override returns (address, uint256); +``` +**Returns** + +|Name|Type|Description| +|----|----|-----------| +|``|`address`|returns the ZRC20 address for gas on the same chain of this ZRC20, and calculates the gas fee for withdraw()| +|``|`uint256`|| + + +### withdraw + +*Withraws ZRC20 tokens to external chains, this function causes cctx module to send out outbound tx to the +outbound chain +this contract should be given enough allowance of the gas ZRC20 to pay for outbound tx gas fee.* + + +```solidity +function withdraw(bytes memory to, uint256 amount) external override returns (bool); +``` +**Parameters** + +|Name|Type|Description| +|----|----|-----------| +|`to`|`bytes`|| +|`amount`|`uint256`|| + +**Returns** + +|Name|Type|Description| +|----|----|-----------| +|``|`bool`|true/false if succeeded/failed.| + + +### updateSystemContractAddress + +*Updates system contract address. Can only be updated by the fungible module.* + + +```solidity +function updateSystemContractAddress(address addr) external onlyFungible; +``` +**Parameters** + +|Name|Type|Description| +|----|----|-----------| +|`addr`|`address`|| + + +### updateGatewayAddress + +*Updates gateway contract address. Can only be updated by the fungible module.* + + +```solidity +function updateGatewayAddress(address addr) external onlyFungible; +``` +**Parameters** + +|Name|Type|Description| +|----|----|-----------| +|`addr`|`address`|| + + +### updateGasLimit + +*Updates gas limit. Can only be updated by the fungible module.* + + +```solidity +function updateGasLimit(uint256 gasLimit_) external onlyFungible; +``` +**Parameters** + +|Name|Type|Description| +|----|----|-----------| +|`gasLimit_`|`uint256`|| + + +### updateProtocolFlatFee + +*Updates protocol flat fee. Can only be updated by the fungible module.* + + +```solidity +function updateProtocolFlatFee(uint256 protocolFlatFee_) external onlyFungible; +``` +**Parameters** + +|Name|Type|Description| +|----|----|-----------| +|`protocolFlatFee_`|`uint256`|| + + diff --git a/v2/docs/src/contracts/zevm/ZRC20.sol/interface.ZRC20Errors.md b/v2/docs/src/contracts/zevm/ZRC20.sol/interface.ZRC20Errors.md new file mode 100644 index 00000000..50612d52 --- /dev/null +++ b/v2/docs/src/contracts/zevm/ZRC20.sol/interface.ZRC20Errors.md @@ -0,0 +1,55 @@ +# ZRC20Errors +[Git Source](https://github.com/zeta-chain/protocol-contracts/blob/c157025a39efca61d83e5991d093a94548f342fb/contracts/zevm/ZRC20.sol) + +*Custom errors for ZRC20* + + +## Errors +### CallerIsNotFungibleModule + +```solidity +error CallerIsNotFungibleModule(); +``` + +### InvalidSender + +```solidity +error InvalidSender(); +``` + +### GasFeeTransferFailed + +```solidity +error GasFeeTransferFailed(); +``` + +### ZeroGasCoin + +```solidity +error ZeroGasCoin(); +``` + +### ZeroGasPrice + +```solidity +error ZeroGasPrice(); +``` + +### LowAllowance + +```solidity +error LowAllowance(); +``` + +### LowBalance + +```solidity +error LowBalance(); +``` + +### ZeroAddress + +```solidity +error ZeroAddress(); +``` + diff --git a/v2/docs/src/contracts/zevm/interfaces/IGatewayZEVM.sol/interface.IGatewayZEVM.md b/v2/docs/src/contracts/zevm/interfaces/IGatewayZEVM.sol/interface.IGatewayZEVM.md new file mode 100644 index 00000000..c9283203 --- /dev/null +++ b/v2/docs/src/contracts/zevm/interfaces/IGatewayZEVM.sol/interface.IGatewayZEVM.md @@ -0,0 +1,267 @@ +# IGatewayZEVM +[Git Source](https://github.com/zeta-chain/protocol-contracts/blob/c157025a39efca61d83e5991d093a94548f342fb/contracts/zevm/interfaces/IGatewayZEVM.sol) + +**Inherits:** +[IGatewayZEVMErrors](/contracts/zevm/interfaces/IGatewayZEVM.sol/interface.IGatewayZEVMErrors.md), [IGatewayZEVMEvents](/contracts/zevm/interfaces/IGatewayZEVM.sol/interface.IGatewayZEVMEvents.md) + +Interface for the GatewayZEVM contract. + +*Defines functions for cross-chain interactions and token handling.* + + +## Functions +### withdraw + +Withdraw ZRC20 tokens to an external chain. + + +```solidity +function withdraw( + bytes memory receiver, + uint256 amount, + address zrc20, + RevertOptions calldata revertOptions +) + external; +``` +**Parameters** + +|Name|Type|Description| +|----|----|-----------| +|`receiver`|`bytes`|The receiver address on the external chain.| +|`amount`|`uint256`|The amount of tokens to withdraw.| +|`zrc20`|`address`|The address of the ZRC20 token.| +|`revertOptions`|`RevertOptions`|Revert options.| + + +### withdraw + +Withdraw ZETA tokens to an external chain. + + +```solidity +function withdraw( + bytes memory receiver, + uint256 amount, + uint256 chainId, + RevertOptions calldata revertOptions +) + external; +``` +**Parameters** + +|Name|Type|Description| +|----|----|-----------| +|`receiver`|`bytes`|The receiver address on the external chain.| +|`amount`|`uint256`|The amount of tokens to withdraw.| +|`chainId`|`uint256`|| +|`revertOptions`|`RevertOptions`|Revert options.| + + +### withdrawAndCall + +Withdraw ZRC20 tokens and call a smart contract on an external chain. + + +```solidity +function withdrawAndCall( + bytes memory receiver, + uint256 amount, + address zrc20, + bytes calldata message, + uint256 gasLimit, + RevertOptions calldata revertOptions +) + external; +``` +**Parameters** + +|Name|Type|Description| +|----|----|-----------| +|`receiver`|`bytes`|The receiver address on the external chain.| +|`amount`|`uint256`|The amount of tokens to withdraw.| +|`zrc20`|`address`|The address of the ZRC20 token.| +|`message`|`bytes`|The calldata to pass to the contract call.| +|`gasLimit`|`uint256`|Gas limit.| +|`revertOptions`|`RevertOptions`|Revert options.| + + +### withdrawAndCall + +Withdraw ZETA tokens and call a smart contract on an external chain. + + +```solidity +function withdrawAndCall( + bytes memory receiver, + uint256 amount, + uint256 chainId, + bytes calldata message, + RevertOptions calldata revertOptions +) + external; +``` +**Parameters** + +|Name|Type|Description| +|----|----|-----------| +|`receiver`|`bytes`|The receiver address on the external chain.| +|`amount`|`uint256`|The amount of tokens to withdraw.| +|`chainId`|`uint256`|Chain id of the external chain.| +|`message`|`bytes`|The calldata to pass to the contract call.| +|`revertOptions`|`RevertOptions`|Revert options.| + + +### call + +Call a smart contract on an external chain without asset transfer. + + +```solidity +function call( + bytes memory receiver, + address zrc20, + bytes calldata message, + uint256 gasLimit, + RevertOptions calldata revertOptions +) + external; +``` +**Parameters** + +|Name|Type|Description| +|----|----|-----------| +|`receiver`|`bytes`|The receiver address on the external chain.| +|`zrc20`|`address`|Address of zrc20 to pay fees.| +|`message`|`bytes`|The calldata to pass to the contract call.| +|`gasLimit`|`uint256`|Gas limit.| +|`revertOptions`|`RevertOptions`|Revert options.| + + +### deposit + +Deposit foreign coins into ZRC20. + + +```solidity +function deposit(address zrc20, uint256 amount, address target) external; +``` +**Parameters** + +|Name|Type|Description| +|----|----|-----------| +|`zrc20`|`address`|The address of the ZRC20 token.| +|`amount`|`uint256`|The amount of tokens to deposit.| +|`target`|`address`|The target address to receive the deposited tokens.| + + +### execute + +Execute a user-specified contract on ZEVM. + + +```solidity +function execute( + zContext calldata context, + address zrc20, + uint256 amount, + address target, + bytes calldata message +) + external; +``` +**Parameters** + +|Name|Type|Description| +|----|----|-----------| +|`context`|`zContext`|The context of the cross-chain call.| +|`zrc20`|`address`|The address of the ZRC20 token.| +|`amount`|`uint256`|The amount of tokens to transfer.| +|`target`|`address`|The target contract to call.| +|`message`|`bytes`|The calldata to pass to the contract call.| + + +### depositAndCall + +Deposit foreign coins into ZRC20 and call a user-specified contract on ZEVM. + + +```solidity +function depositAndCall( + zContext calldata context, + address zrc20, + uint256 amount, + address target, + bytes calldata message +) + external; +``` +**Parameters** + +|Name|Type|Description| +|----|----|-----------| +|`context`|`zContext`|The context of the cross-chain call.| +|`zrc20`|`address`|The address of the ZRC20 token.| +|`amount`|`uint256`|The amount of tokens to transfer.| +|`target`|`address`|The target contract to call.| +|`message`|`bytes`|The calldata to pass to the contract call.| + + +### depositAndCall + +Deposit ZETA and call a user-specified contract on ZEVM. + + +```solidity +function depositAndCall(zContext calldata context, uint256 amount, address target, bytes calldata message) external; +``` +**Parameters** + +|Name|Type|Description| +|----|----|-----------| +|`context`|`zContext`|The context of the cross-chain call.| +|`amount`|`uint256`|The amount of tokens to transfer.| +|`target`|`address`|The target contract to call.| +|`message`|`bytes`|The calldata to pass to the contract call.| + + +### executeRevert + +Revert a user-specified contract on ZEVM. + + +```solidity +function executeRevert(address target, RevertContext calldata revertContext) external; +``` +**Parameters** + +|Name|Type|Description| +|----|----|-----------| +|`target`|`address`|The target contract to call.| +|`revertContext`|`RevertContext`|Revert context to pass to onRevert.| + + +### depositAndRevert + +Deposit foreign coins into ZRC20 and revert a user-specified contract on ZEVM. + + +```solidity +function depositAndRevert( + address zrc20, + uint256 amount, + address target, + RevertContext calldata revertContext +) + external; +``` +**Parameters** + +|Name|Type|Description| +|----|----|-----------| +|`zrc20`|`address`|The address of the ZRC20 token.| +|`amount`|`uint256`|The amount of tokens to revert.| +|`target`|`address`|The target contract to call.| +|`revertContext`|`RevertContext`|Revert context to pass to onRevert.| + + diff --git a/v2/docs/src/contracts/zevm/interfaces/IGatewayZEVM.sol/interface.IGatewayZEVMErrors.md b/v2/docs/src/contracts/zevm/interfaces/IGatewayZEVM.sol/interface.IGatewayZEVMErrors.md new file mode 100644 index 00000000..1a3e6962 --- /dev/null +++ b/v2/docs/src/contracts/zevm/interfaces/IGatewayZEVM.sol/interface.IGatewayZEVMErrors.md @@ -0,0 +1,103 @@ +# IGatewayZEVMErrors +[Git Source](https://github.com/zeta-chain/protocol-contracts/blob/c157025a39efca61d83e5991d093a94548f342fb/contracts/zevm/interfaces/IGatewayZEVM.sol) + +Interface for the errors used in the GatewayZEVM contract. + + +## Errors +### WithdrawalFailed +Error indicating a withdrawal failure. + + +```solidity +error WithdrawalFailed(); +``` + +### InsufficientZRC20Amount +Error indicating an insufficient ZRC20 token amount. + + +```solidity +error InsufficientZRC20Amount(); +``` + +### InsufficientZetaAmount +Error indicating an insufficient zeta amount. + + +```solidity +error InsufficientZetaAmount(); +``` + +### ZRC20BurnFailed +Error indicating a failure to burn ZRC20 tokens. + + +```solidity +error ZRC20BurnFailed(); +``` + +### ZRC20TransferFailed +Error indicating a failure to transfer ZRC20 tokens. + + +```solidity +error ZRC20TransferFailed(); +``` + +### ZRC20DepositFailed +Error indicating a failure to deposit ZRC20 tokens. + + +```solidity +error ZRC20DepositFailed(); +``` + +### GasFeeTransferFailed +Error indicating a failure to transfer gas fee. + + +```solidity +error GasFeeTransferFailed(); +``` + +### CallerIsNotFungibleModule +Error indicating that the caller is not the Fungible module. + + +```solidity +error CallerIsNotFungibleModule(); +``` + +### InvalidTarget +Error indicating an invalid target address. + + +```solidity +error InvalidTarget(); +``` + +### FailedZetaSent +Error indicating a failure to send ZETA tokens. + + +```solidity +error FailedZetaSent(); +``` + +### OnlyWZETAOrFungible +Error indicating that only WZETA or the Fungible module can call the function. + + +```solidity +error OnlyWZETAOrFungible(); +``` + +### EmptyMessage +Error indicating call method received empty message as argument. + + +```solidity +error EmptyMessage(); +``` + diff --git a/v2/docs/src/contracts/zevm/interfaces/IGatewayZEVM.sol/interface.IGatewayZEVMEvents.md b/v2/docs/src/contracts/zevm/interfaces/IGatewayZEVM.sol/interface.IGatewayZEVMEvents.md new file mode 100644 index 00000000..7c799bbc --- /dev/null +++ b/v2/docs/src/contracts/zevm/interfaces/IGatewayZEVM.sol/interface.IGatewayZEVMEvents.md @@ -0,0 +1,67 @@ +# IGatewayZEVMEvents +[Git Source](https://github.com/zeta-chain/protocol-contracts/blob/c157025a39efca61d83e5991d093a94548f342fb/contracts/zevm/interfaces/IGatewayZEVM.sol) + +Interface for the events emitted by the GatewayZEVM contract. + + +## Events +### Called +Emitted when a cross-chain call is made. + + +```solidity +event Called( + address indexed sender, + address indexed zrc20, + bytes receiver, + bytes message, + uint256 gasLimit, + RevertOptions revertOptions +); +``` + +**Parameters** + +|Name|Type|Description| +|----|----|-----------| +|`sender`|`address`|The address of the sender.| +|`zrc20`|`address`|Address of zrc20 to pay fees.| +|`receiver`|`bytes`|The receiver address on the external chain.| +|`message`|`bytes`|The calldata passed to the contract call.| +|`gasLimit`|`uint256`|Gas limit.| +|`revertOptions`|`RevertOptions`|Revert options.| + +### Withdrawn +Emitted when a withdrawal is made. + + +```solidity +event Withdrawn( + address indexed sender, + uint256 indexed chainId, + bytes receiver, + address zrc20, + uint256 value, + uint256 gasfee, + uint256 protocolFlatFee, + bytes message, + uint256 gasLimit, + RevertOptions revertOptions +); +``` + +**Parameters** + +|Name|Type|Description| +|----|----|-----------| +|`sender`|`address`|The address from which the tokens are withdrawn.| +|`chainId`|`uint256`|Chain id of external chain.| +|`receiver`|`bytes`|The receiver address on the external chain.| +|`zrc20`|`address`|The address of the ZRC20 token.| +|`value`|`uint256`|The amount of tokens withdrawn.| +|`gasfee`|`uint256`|The gas fee for the withdrawal.| +|`protocolFlatFee`|`uint256`|The protocol flat fee for the withdrawal.| +|`message`|`bytes`|The calldata passed to the contract call.| +|`gasLimit`|`uint256`|Gas limit.| +|`revertOptions`|`RevertOptions`|Revert options.| + diff --git a/v2/docs/src/contracts/zevm/interfaces/ISystem.sol/interface.ISystem.md b/v2/docs/src/contracts/zevm/interfaces/ISystem.sol/interface.ISystem.md new file mode 100644 index 00000000..1094a7ad --- /dev/null +++ b/v2/docs/src/contracts/zevm/interfaces/ISystem.sol/interface.ISystem.md @@ -0,0 +1,51 @@ +# ISystem +[Git Source](https://github.com/zeta-chain/protocol-contracts/blob/c157025a39efca61d83e5991d093a94548f342fb/contracts/zevm/interfaces/ISystem.sol) + +Interface for the System contract. + +*Defines functions for system contract callable by fungible module.* + + +## Functions +### FUNGIBLE_MODULE_ADDRESS + + +```solidity +function FUNGIBLE_MODULE_ADDRESS() external view returns (address); +``` + +### wZetaContractAddress + + +```solidity +function wZetaContractAddress() external view returns (address); +``` + +### uniswapv2FactoryAddress + + +```solidity +function uniswapv2FactoryAddress() external view returns (address); +``` + +### gasPriceByChainId + + +```solidity +function gasPriceByChainId(uint256 chainID) external view returns (uint256); +``` + +### gasCoinZRC20ByChainId + + +```solidity +function gasCoinZRC20ByChainId(uint256 chainID) external view returns (address); +``` + +### gasZetaPoolByChainId + + +```solidity +function gasZetaPoolByChainId(uint256 chainID) external view returns (address); +``` + diff --git a/v2/docs/src/contracts/zevm/interfaces/IWZETA.sol/interface.IWETH9.md b/v2/docs/src/contracts/zevm/interfaces/IWZETA.sol/interface.IWETH9.md new file mode 100644 index 00000000..56031e6b --- /dev/null +++ b/v2/docs/src/contracts/zevm/interfaces/IWZETA.sol/interface.IWETH9.md @@ -0,0 +1,88 @@ +# IWETH9 +[Git Source](https://github.com/zeta-chain/protocol-contracts/blob/c157025a39efca61d83e5991d093a94548f342fb/contracts/zevm/interfaces/IWZETA.sol) + +Interface for the Weth9 contract. + + +## Functions +### totalSupply + + +```solidity +function totalSupply() external view returns (uint256); +``` + +### balanceOf + + +```solidity +function balanceOf(address owner) external view returns (uint256); +``` + +### allowance + + +```solidity +function allowance(address owner, address spender) external view returns (uint256); +``` + +### approve + + +```solidity +function approve(address spender, uint256 wad) external returns (bool); +``` + +### transfer + + +```solidity +function transfer(address to, uint256 wad) external returns (bool); +``` + +### transferFrom + + +```solidity +function transferFrom(address from, address to, uint256 wad) external returns (bool); +``` + +### deposit + + +```solidity +function deposit() external payable; +``` + +### withdraw + + +```solidity +function withdraw(uint256 wad) external; +``` + +## Events +### Approval + +```solidity +event Approval(address indexed owner, address indexed spender, uint256 value); +``` + +### Transfer + +```solidity +event Transfer(address indexed from, address indexed to, uint256 value); +``` + +### Deposit + +```solidity +event Deposit(address indexed dst, uint256 wad); +``` + +### Withdrawal + +```solidity +event Withdrawal(address indexed src, uint256 wad); +``` + diff --git a/v2/docs/src/contracts/zevm/interfaces/IZRC20.sol/enum.CoinType.md b/v2/docs/src/contracts/zevm/interfaces/IZRC20.sol/enum.CoinType.md new file mode 100644 index 00000000..02c70b1e --- /dev/null +++ b/v2/docs/src/contracts/zevm/interfaces/IZRC20.sol/enum.CoinType.md @@ -0,0 +1,14 @@ +# CoinType +[Git Source](https://github.com/zeta-chain/protocol-contracts/blob/c157025a39efca61d83e5991d093a94548f342fb/contracts/zevm/interfaces/IZRC20.sol) + +*Coin types for ZRC20. Zeta value should not be used.* + + +```solidity +enum CoinType { + Zeta, + Gas, + ERC20 +} +``` + diff --git a/v2/docs/src/contracts/zevm/interfaces/IZRC20.sol/interface.IZRC20.md b/v2/docs/src/contracts/zevm/interfaces/IZRC20.sol/interface.IZRC20.md new file mode 100644 index 00000000..220c1fff --- /dev/null +++ b/v2/docs/src/contracts/zevm/interfaces/IZRC20.sol/interface.IZRC20.md @@ -0,0 +1,116 @@ +# IZRC20 +[Git Source](https://github.com/zeta-chain/protocol-contracts/blob/c157025a39efca61d83e5991d093a94548f342fb/contracts/zevm/interfaces/IZRC20.sol) + +Interface for the ZRC20 token contract. + + +## Functions +### totalSupply + + +```solidity +function totalSupply() external view returns (uint256); +``` + +### balanceOf + + +```solidity +function balanceOf(address account) external view returns (uint256); +``` + +### transfer + + +```solidity +function transfer(address recipient, uint256 amount) external returns (bool); +``` + +### allowance + + +```solidity +function allowance(address owner, address spender) external view returns (uint256); +``` + +### approve + + +```solidity +function approve(address spender, uint256 amount) external returns (bool); +``` + +### transferFrom + + +```solidity +function transferFrom(address sender, address recipient, uint256 amount) external returns (bool); +``` + +### deposit + + +```solidity +function deposit(address to, uint256 amount) external returns (bool); +``` + +### burn + + +```solidity +function burn(uint256 amount) external returns (bool); +``` + +### withdraw + + +```solidity +function withdraw(bytes memory to, uint256 amount) external returns (bool); +``` + +### withdrawGasFee + + +```solidity +function withdrawGasFee() external view returns (address, uint256); +``` + +### withdrawGasFeeWithGasLimit + + +```solidity +function withdrawGasFeeWithGasLimit(uint256 gasLimit) external view returns (address, uint256); +``` + +### PROTOCOL_FLAT_FEE + +*Name is in upper case to maintain compatibility with ZRC20.sol v1* + + +```solidity +function PROTOCOL_FLAT_FEE() external view returns (uint256); +``` + +### GAS_LIMIT + +*Name is in upper case to maintain compatibility with ZRC20.sol v1* + + +```solidity +function GAS_LIMIT() external view returns (uint256); +``` + +### setName + + +```solidity +function setName(string memory newName) external; +``` + +### setSymbol + + +```solidity +function setSymbol(string memory newSymbol) external; +``` + diff --git a/v2/docs/src/contracts/zevm/interfaces/IZRC20.sol/interface.IZRC20Metadata.md b/v2/docs/src/contracts/zevm/interfaces/IZRC20.sol/interface.IZRC20Metadata.md new file mode 100644 index 00000000..74798425 --- /dev/null +++ b/v2/docs/src/contracts/zevm/interfaces/IZRC20.sol/interface.IZRC20Metadata.md @@ -0,0 +1,31 @@ +# IZRC20Metadata +[Git Source](https://github.com/zeta-chain/protocol-contracts/blob/c157025a39efca61d83e5991d093a94548f342fb/contracts/zevm/interfaces/IZRC20.sol) + +**Inherits:** +[IZRC20](/contracts/zevm/interfaces/IZRC20.sol/interface.IZRC20.md) + +Interface for the ZRC20 metadata. + + +## Functions +### name + + +```solidity +function name() external view returns (string memory); +``` + +### symbol + + +```solidity +function symbol() external view returns (string memory); +``` + +### decimals + + +```solidity +function decimals() external view returns (uint8); +``` + diff --git a/v2/docs/src/contracts/zevm/interfaces/IZRC20.sol/interface.ZRC20Events.md b/v2/docs/src/contracts/zevm/interfaces/IZRC20.sol/interface.ZRC20Events.md new file mode 100644 index 00000000..cf66ba84 --- /dev/null +++ b/v2/docs/src/contracts/zevm/interfaces/IZRC20.sol/interface.ZRC20Events.md @@ -0,0 +1,55 @@ +# ZRC20Events +[Git Source](https://github.com/zeta-chain/protocol-contracts/blob/c157025a39efca61d83e5991d093a94548f342fb/contracts/zevm/interfaces/IZRC20.sol) + +Interface for the ZRC20 events. + + +## Events +### Transfer + +```solidity +event Transfer(address indexed from, address indexed to, uint256 value); +``` + +### Approval + +```solidity +event Approval(address indexed owner, address indexed spender, uint256 value); +``` + +### Deposit + +```solidity +event Deposit(bytes from, address indexed to, uint256 value); +``` + +### Withdrawal + +```solidity +event Withdrawal(address indexed from, bytes to, uint256 value, uint256 gasFee, uint256 protocolFlatFee); +``` + +### UpdatedSystemContract + +```solidity +event UpdatedSystemContract(address systemContract); +``` + +### UpdatedGateway + +```solidity +event UpdatedGateway(address gateway); +``` + +### UpdatedGasLimit + +```solidity +event UpdatedGasLimit(uint256 gasLimit); +``` + +### UpdatedProtocolFlatFee + +```solidity +event UpdatedProtocolFlatFee(uint256 protocolFlatFee); +``` + diff --git a/v2/docs/src/contracts/zevm/interfaces/README.md b/v2/docs/src/contracts/zevm/interfaces/README.md new file mode 100644 index 00000000..b412a802 --- /dev/null +++ b/v2/docs/src/contracts/zevm/interfaces/README.md @@ -0,0 +1,15 @@ + + +# Contents +- [IGatewayZEVMEvents](IGatewayZEVM.sol/interface.IGatewayZEVMEvents.md) +- [IGatewayZEVMErrors](IGatewayZEVM.sol/interface.IGatewayZEVMErrors.md) +- [IGatewayZEVM](IGatewayZEVM.sol/interface.IGatewayZEVM.md) +- [ISystem](ISystem.sol/interface.ISystem.md) +- [IWETH9](IWZETA.sol/interface.IWETH9.md) +- [IZRC20](IZRC20.sol/interface.IZRC20.md) +- [IZRC20Metadata](IZRC20.sol/interface.IZRC20Metadata.md) +- [ZRC20Events](IZRC20.sol/interface.ZRC20Events.md) +- [CoinType](IZRC20.sol/enum.CoinType.md) +- [zContext](UniversalContract.sol/struct.zContext.md) +- [zContract](UniversalContract.sol/interface.zContract.md) +- [UniversalContract](UniversalContract.sol/interface.UniversalContract.md) diff --git a/v2/docs/src/contracts/zevm/interfaces/UniversalContract.sol/interface.UniversalContract.md b/v2/docs/src/contracts/zevm/interfaces/UniversalContract.sol/interface.UniversalContract.md new file mode 100644 index 00000000..b8b6afc9 --- /dev/null +++ b/v2/docs/src/contracts/zevm/interfaces/UniversalContract.sol/interface.UniversalContract.md @@ -0,0 +1,19 @@ +# UniversalContract +[Git Source](https://github.com/zeta-chain/protocol-contracts/blob/c157025a39efca61d83e5991d093a94548f342fb/contracts/zevm/interfaces/UniversalContract.sol) + + +## Functions +### onCrossChainCall + + +```solidity +function onCrossChainCall(zContext calldata context, address zrc20, uint256 amount, bytes calldata message) external; +``` + +### onRevert + + +```solidity +function onRevert(RevertContext calldata revertContext) external; +``` + diff --git a/v2/docs/src/contracts/zevm/interfaces/UniversalContract.sol/interface.zContract.md b/v2/docs/src/contracts/zevm/interfaces/UniversalContract.sol/interface.zContract.md new file mode 100644 index 00000000..759183e2 --- /dev/null +++ b/v2/docs/src/contracts/zevm/interfaces/UniversalContract.sol/interface.zContract.md @@ -0,0 +1,12 @@ +# zContract +[Git Source](https://github.com/zeta-chain/protocol-contracts/blob/c157025a39efca61d83e5991d093a94548f342fb/contracts/zevm/interfaces/UniversalContract.sol) + + +## Functions +### onCrossChainCall + + +```solidity +function onCrossChainCall(zContext calldata context, address zrc20, uint256 amount, bytes calldata message) external; +``` + diff --git a/v2/docs/src/contracts/zevm/interfaces/UniversalContract.sol/struct.zContext.md b/v2/docs/src/contracts/zevm/interfaces/UniversalContract.sol/struct.zContext.md new file mode 100644 index 00000000..0f5b5074 --- /dev/null +++ b/v2/docs/src/contracts/zevm/interfaces/UniversalContract.sol/struct.zContext.md @@ -0,0 +1,12 @@ +# zContext +[Git Source](https://github.com/zeta-chain/protocol-contracts/blob/c157025a39efca61d83e5991d093a94548f342fb/contracts/zevm/interfaces/UniversalContract.sol) + + +```solidity +struct zContext { + bytes origin; + address sender; + uint256 chainID; +} +``` + diff --git a/v2/docs/src/index.md b/v2/docs/src/index.md new file mode 100644 index 00000000..b2ed4dfb --- /dev/null +++ b/v2/docs/src/index.md @@ -0,0 +1,97 @@ +--- +title: "Protocol contracts" +--- + +### ⚠️ Important Notice: V2 in Development + +We are currently developing Version 2 (V2) of our smart contract architecture. This new version will significantly enhance the developer experience for building Universal Apps. + +Developers can already begin testing the new interface by referring to [the V2 Localnet guide](./scripts/localnet//v2_localnet.md). + +### Build + +```shell +$ forge build +``` + +### Test + +```shell +$ forge test +``` + +### Format + +```shell +$ forge fmt +``` + +### Gas Snapshots + +```shell +$ forge snapshot +``` + +### Anvil + +```shell +$ anvil +``` + +### Deploy using script + +```shell +$ forge script script/.s.sol: --rpc-url --private-key +``` + +### Cast + +```shell +$ cast +``` + +### Help + +```shell +$ forge --help +$ anvil --help +$ cast --help +``` +# Summary +- [Home](README.md) +# contracts + - [❱ evm](protocol/contracts/evm/README.md) + - [❱ interfaces](protocol/contracts/evm/interfaces/README.md) + - [IERC20CustodyEvents](protocol/contracts/evm/interfaces/IERC20Custody.sol/interface.IERC20CustodyEvents.md) + - [IERC20CustodyErrors](protocol/contracts/evm/interfaces/IERC20Custody.sol/interface.IERC20CustodyErrors.md) + - [IERC20Custody](protocol/contracts/evm/interfaces/IERC20Custody.sol/interface.IERC20Custody.md) + - [IGatewayEVMEvents](protocol/contracts/evm/interfaces/IGatewayEVM.sol/interface.IGatewayEVMEvents.md) + - [IGatewayEVMErrors](protocol/contracts/evm/interfaces/IGatewayEVM.sol/interface.IGatewayEVMErrors.md) + - [IGatewayEVM](protocol/contracts/evm/interfaces/IGatewayEVM.sol/interface.IGatewayEVM.md) + - [IZetaConnectorEvents](protocol/contracts/evm/interfaces/IZetaConnector.sol/interface.IZetaConnectorEvents.md) + - [IZetaNonEthNew](protocol/contracts/evm/interfaces/IZetaNonEthNew.sol/interface.IZetaNonEthNew.md) + - [ERC20Custody](protocol/contracts/evm/ERC20Custody.sol/contract.ERC20Custody.md) + - [GatewayEVM](protocol/contracts/evm/GatewayEVM.sol/contract.GatewayEVM.md) + - [ZetaConnectorBase](protocol/contracts/evm/ZetaConnectorBase.sol/abstract.ZetaConnectorBase.md) + - [ZetaConnectorNative](protocol/contracts/evm/ZetaConnectorNative.sol/contract.ZetaConnectorNative.md) + - [ZetaConnectorNonNative](protocol/contracts/evm/ZetaConnectorNonNative.sol/contract.ZetaConnectorNonNative.md) + - [❱ zevm](protocol/contracts/zevm/README.md) + - [❱ interfaces](protocol/contracts/zevm/interfaces/README.md) + - [IGatewayZEVMEvents](protocol/contracts/zevm/interfaces/IGatewayZEVM.sol/interface.IGatewayZEVMEvents.md) + - [IGatewayZEVMErrors](protocol/contracts/zevm/interfaces/IGatewayZEVM.sol/interface.IGatewayZEVMErrors.md) + - [IGatewayZEVM](protocol/contracts/zevm/interfaces/IGatewayZEVM.sol/interface.IGatewayZEVM.md) + - [ISystem](protocol/contracts/zevm/interfaces/ISystem.sol/interface.ISystem.md) + - [IWETH9](protocol/contracts/zevm/interfaces/IWZETA.sol/interface.IWETH9.md) + - [IZRC20](protocol/contracts/zevm/interfaces/IZRC20.sol/interface.IZRC20.md) + - [IZRC20Metadata](protocol/contracts/zevm/interfaces/IZRC20.sol/interface.IZRC20Metadata.md) + - [ZRC20Events](protocol/contracts/zevm/interfaces/IZRC20.sol/interface.ZRC20Events.md) + - [CoinType](protocol/contracts/zevm/interfaces/IZRC20.sol/enum.CoinType.md) + - [zContext](protocol/contracts/zevm/interfaces/UniversalContract.sol/struct.zContext.md) + - [zContract](protocol/contracts/zevm/interfaces/UniversalContract.sol/interface.zContract.md) + - [UniversalContract](protocol/contracts/zevm/interfaces/UniversalContract.sol/interface.UniversalContract.md) + - [GatewayZEVM](protocol/contracts/zevm/GatewayZEVM.sol/contract.GatewayZEVM.md) + - [ZRC20Errors](protocol/contracts/zevm/ZRC20.sol/interface.ZRC20Errors.md) + - [ZRC20](protocol/contracts/zevm/ZRC20.sol/contract.ZRC20.md) + - [RevertOptions](protocol/contracts/Revert.sol/struct.RevertOptions.md) + - [RevertContext](protocol/contracts/Revert.sol/struct.RevertContext.md) + - [Revertable](protocol/contracts/Revert.sol/interface.Revertable.md) diff --git a/v2/package.json b/v2/package.json index 88aa3229..538b66de 100644 --- a/v2/package.json +++ b/v2/package.json @@ -14,8 +14,9 @@ "test": "forge clean && forge test -vvv", "coverage": "forge clean && forge coverage --no-match-coverage \"(script|test)\" --report lcov", "typechain": "npx typechain --target ethers-v6 \"out/**/!(*.t|test).sol/!(*.abi).json\" --out-dir types", - "generate": "forge clean && forge build && forge fmt && ./scripts/generate_go.sh || true && yarn lint:fix && yarn typechain", - "prepublishOnly": "copyfiles -u 1 'out/**/*' 'abi'" + "generate": "forge clean && forge build && forge fmt && ./scripts/generate_go.sh || true && yarn lint:fix && yarn typechain && yarn docs", + "prepublishOnly": "copyfiles -u 1 'out/**/*' 'abi'", + "docs": "./scripts/generate_docs.sh" }, "devDependencies": { "@eslint/js": "^9.7.0", diff --git a/v2/pkg/beaconproxy.sol/beaconproxy.go b/v2/pkg/beaconproxy.sol/beaconproxy.go deleted file mode 100644 index c8a80b2b..00000000 --- a/v2/pkg/beaconproxy.sol/beaconproxy.go +++ /dev/null @@ -1,368 +0,0 @@ -// Code generated - DO NOT EDIT. -// This file is a generated binding and any manual changes will be lost. - -package beaconproxy - -import ( - "errors" - "math/big" - "strings" - - ethereum "github.com/ethereum/go-ethereum" - "github.com/ethereum/go-ethereum/accounts/abi" - "github.com/ethereum/go-ethereum/accounts/abi/bind" - "github.com/ethereum/go-ethereum/common" - "github.com/ethereum/go-ethereum/core/types" - "github.com/ethereum/go-ethereum/event" -) - -// Reference imports to suppress errors if they are not otherwise used. -var ( - _ = errors.New - _ = big.NewInt - _ = strings.NewReader - _ = ethereum.NotFound - _ = bind.Bind - _ = common.Big1 - _ = types.BloomLookup - _ = event.NewSubscription - _ = abi.ConvertType -) - -// BeaconProxyMetaData contains all meta data concerning the BeaconProxy contract. -var BeaconProxyMetaData = &bind.MetaData{ - ABI: "[{\"type\":\"constructor\",\"inputs\":[{\"name\":\"beacon\",\"type\":\"address\",\"internalType\":\"address\"},{\"name\":\"data\",\"type\":\"bytes\",\"internalType\":\"bytes\"}],\"stateMutability\":\"payable\"},{\"type\":\"fallback\",\"stateMutability\":\"payable\"},{\"type\":\"event\",\"name\":\"BeaconUpgraded\",\"inputs\":[{\"name\":\"beacon\",\"type\":\"address\",\"indexed\":true,\"internalType\":\"address\"}],\"anonymous\":false},{\"type\":\"error\",\"name\":\"AddressEmptyCode\",\"inputs\":[{\"name\":\"target\",\"type\":\"address\",\"internalType\":\"address\"}]},{\"type\":\"error\",\"name\":\"ERC1967InvalidBeacon\",\"inputs\":[{\"name\":\"beacon\",\"type\":\"address\",\"internalType\":\"address\"}]},{\"type\":\"error\",\"name\":\"ERC1967InvalidImplementation\",\"inputs\":[{\"name\":\"implementation\",\"type\":\"address\",\"internalType\":\"address\"}]},{\"type\":\"error\",\"name\":\"ERC1967NonPayable\",\"inputs\":[]},{\"type\":\"error\",\"name\":\"FailedInnerCall\",\"inputs\":[]}]", - Bin: "0x60a06040526040516105eb3803806105eb83398101604081905261002291610387565b61002c828261003e565b506001600160a01b0316608052610484565b610047826100fe565b6040516001600160a01b038316907f1cf3b03a6cf19fa2baba4df148e9dcabedea7f8a5c07840e207e5c089be95d3e90600090a28051156100f2576100ed826001600160a01b0316635c60da1b6040518163ffffffff1660e01b8152600401602060405180830381865afa1580156100c3573d6000803e3d6000fd5b505050506040513d601f19601f820116820180604052508101906100e7919061044d565b82610211565b505050565b6100fa610288565b5050565b806001600160a01b03163b60000361013957604051631933b43b60e21b81526001600160a01b03821660048201526024015b60405180910390fd5b807fa3f0ad74e5423aebfd80d3ef4346578335a9a72aeaee59ff6cb3582b35133d5080546001600160a01b0319166001600160a01b0392831617905560408051635c60da1b60e01b81529051600092841691635c60da1b9160048083019260209291908290030181865afa1580156101b5573d6000803e3d6000fd5b505050506040513d601f19601f820116820180604052508101906101d9919061044d565b9050806001600160a01b03163b6000036100fa57604051634c9c8ce360e01b81526001600160a01b0382166004820152602401610130565b6060600080846001600160a01b03168460405161022e9190610468565b600060405180830381855af49150503d8060008114610269576040519150601f19603f3d011682016040523d82523d6000602084013e61026e565b606091505b50909250905061027f8583836102a9565b95945050505050565b34156102a75760405163b398979f60e01b815260040160405180910390fd5b565b6060826102be576102b982610308565b610301565b81511580156102d557506001600160a01b0384163b155b156102fe57604051639996b31560e01b81526001600160a01b0385166004820152602401610130565b50805b9392505050565b8051156103185780518082602001fd5b604051630a12f52160e11b815260040160405180910390fd5b80516001600160a01b038116811461034857600080fd5b919050565b634e487b7160e01b600052604160045260246000fd5b60005b8381101561037e578181015183820152602001610366565b50506000910152565b6000806040838503121561039a57600080fd5b6103a383610331565b60208401519092506001600160401b038111156103bf57600080fd5b8301601f810185136103d057600080fd5b80516001600160401b038111156103e9576103e961034d565b604051601f8201601f19908116603f011681016001600160401b03811182821017156104175761041761034d565b60405281815282820160200187101561042f57600080fd5b610440826020830160208601610363565b8093505050509250929050565b60006020828403121561045f57600080fd5b61030182610331565b6000825161047a818460208701610363565b9190910192915050565b60805161014d61049e60003960006024015261014d6000f3fe608060405261000c61000e565b005b61001e610019610020565b6100b6565b565b60007f000000000000000000000000000000000000000000000000000000000000000073ffffffffffffffffffffffffffffffffffffffff16635c60da1b6040518163ffffffff1660e01b8152600401602060405180830381865afa15801561008d573d6000803e3d6000fd5b505050506040513d601f19601f820116820180604052508101906100b191906100da565b905090565b3660008037600080366000845af43d6000803e8080156100d5573d6000f35b3d6000fd5b6000602082840312156100ec57600080fd5b815173ffffffffffffffffffffffffffffffffffffffff8116811461011057600080fd5b939250505056fea26469706673582212200ff5a1b777e58d2c4306d8462abce5779db9190c8550ebdc7ff4780457dc1d5764736f6c634300081a0033", -} - -// BeaconProxyABI is the input ABI used to generate the binding from. -// Deprecated: Use BeaconProxyMetaData.ABI instead. -var BeaconProxyABI = BeaconProxyMetaData.ABI - -// BeaconProxyBin is the compiled bytecode used for deploying new contracts. -// Deprecated: Use BeaconProxyMetaData.Bin instead. -var BeaconProxyBin = BeaconProxyMetaData.Bin - -// DeployBeaconProxy deploys a new Ethereum contract, binding an instance of BeaconProxy to it. -func DeployBeaconProxy(auth *bind.TransactOpts, backend bind.ContractBackend, beacon common.Address, data []byte) (common.Address, *types.Transaction, *BeaconProxy, error) { - parsed, err := BeaconProxyMetaData.GetAbi() - if err != nil { - return common.Address{}, nil, nil, err - } - if parsed == nil { - return common.Address{}, nil, nil, errors.New("GetABI returned nil") - } - - address, tx, contract, err := bind.DeployContract(auth, *parsed, common.FromHex(BeaconProxyBin), backend, beacon, data) - if err != nil { - return common.Address{}, nil, nil, err - } - return address, tx, &BeaconProxy{BeaconProxyCaller: BeaconProxyCaller{contract: contract}, BeaconProxyTransactor: BeaconProxyTransactor{contract: contract}, BeaconProxyFilterer: BeaconProxyFilterer{contract: contract}}, nil -} - -// BeaconProxy is an auto generated Go binding around an Ethereum contract. -type BeaconProxy struct { - BeaconProxyCaller // Read-only binding to the contract - BeaconProxyTransactor // Write-only binding to the contract - BeaconProxyFilterer // Log filterer for contract events -} - -// BeaconProxyCaller is an auto generated read-only Go binding around an Ethereum contract. -type BeaconProxyCaller struct { - contract *bind.BoundContract // Generic contract wrapper for the low level calls -} - -// BeaconProxyTransactor is an auto generated write-only Go binding around an Ethereum contract. -type BeaconProxyTransactor struct { - contract *bind.BoundContract // Generic contract wrapper for the low level calls -} - -// BeaconProxyFilterer is an auto generated log filtering Go binding around an Ethereum contract events. -type BeaconProxyFilterer struct { - contract *bind.BoundContract // Generic contract wrapper for the low level calls -} - -// BeaconProxySession is an auto generated Go binding around an Ethereum contract, -// with pre-set call and transact options. -type BeaconProxySession struct { - Contract *BeaconProxy // Generic contract binding to set the session for - CallOpts bind.CallOpts // Call options to use throughout this session - TransactOpts bind.TransactOpts // Transaction auth options to use throughout this session -} - -// BeaconProxyCallerSession is an auto generated read-only Go binding around an Ethereum contract, -// with pre-set call options. -type BeaconProxyCallerSession struct { - Contract *BeaconProxyCaller // Generic contract caller binding to set the session for - CallOpts bind.CallOpts // Call options to use throughout this session -} - -// BeaconProxyTransactorSession is an auto generated write-only Go binding around an Ethereum contract, -// with pre-set transact options. -type BeaconProxyTransactorSession struct { - Contract *BeaconProxyTransactor // Generic contract transactor binding to set the session for - TransactOpts bind.TransactOpts // Transaction auth options to use throughout this session -} - -// BeaconProxyRaw is an auto generated low-level Go binding around an Ethereum contract. -type BeaconProxyRaw struct { - Contract *BeaconProxy // Generic contract binding to access the raw methods on -} - -// BeaconProxyCallerRaw is an auto generated low-level read-only Go binding around an Ethereum contract. -type BeaconProxyCallerRaw struct { - Contract *BeaconProxyCaller // Generic read-only contract binding to access the raw methods on -} - -// BeaconProxyTransactorRaw is an auto generated low-level write-only Go binding around an Ethereum contract. -type BeaconProxyTransactorRaw struct { - Contract *BeaconProxyTransactor // Generic write-only contract binding to access the raw methods on -} - -// NewBeaconProxy creates a new instance of BeaconProxy, bound to a specific deployed contract. -func NewBeaconProxy(address common.Address, backend bind.ContractBackend) (*BeaconProxy, error) { - contract, err := bindBeaconProxy(address, backend, backend, backend) - if err != nil { - return nil, err - } - return &BeaconProxy{BeaconProxyCaller: BeaconProxyCaller{contract: contract}, BeaconProxyTransactor: BeaconProxyTransactor{contract: contract}, BeaconProxyFilterer: BeaconProxyFilterer{contract: contract}}, nil -} - -// NewBeaconProxyCaller creates a new read-only instance of BeaconProxy, bound to a specific deployed contract. -func NewBeaconProxyCaller(address common.Address, caller bind.ContractCaller) (*BeaconProxyCaller, error) { - contract, err := bindBeaconProxy(address, caller, nil, nil) - if err != nil { - return nil, err - } - return &BeaconProxyCaller{contract: contract}, nil -} - -// NewBeaconProxyTransactor creates a new write-only instance of BeaconProxy, bound to a specific deployed contract. -func NewBeaconProxyTransactor(address common.Address, transactor bind.ContractTransactor) (*BeaconProxyTransactor, error) { - contract, err := bindBeaconProxy(address, nil, transactor, nil) - if err != nil { - return nil, err - } - return &BeaconProxyTransactor{contract: contract}, nil -} - -// NewBeaconProxyFilterer creates a new log filterer instance of BeaconProxy, bound to a specific deployed contract. -func NewBeaconProxyFilterer(address common.Address, filterer bind.ContractFilterer) (*BeaconProxyFilterer, error) { - contract, err := bindBeaconProxy(address, nil, nil, filterer) - if err != nil { - return nil, err - } - return &BeaconProxyFilterer{contract: contract}, nil -} - -// bindBeaconProxy binds a generic wrapper to an already deployed contract. -func bindBeaconProxy(address common.Address, caller bind.ContractCaller, transactor bind.ContractTransactor, filterer bind.ContractFilterer) (*bind.BoundContract, error) { - parsed, err := BeaconProxyMetaData.GetAbi() - if err != nil { - return nil, err - } - return bind.NewBoundContract(address, *parsed, caller, transactor, filterer), nil -} - -// Call invokes the (constant) contract method with params as input values and -// sets the output to result. The result type might be a single field for simple -// returns, a slice of interfaces for anonymous returns and a struct for named -// returns. -func (_BeaconProxy *BeaconProxyRaw) Call(opts *bind.CallOpts, result *[]interface{}, method string, params ...interface{}) error { - return _BeaconProxy.Contract.BeaconProxyCaller.contract.Call(opts, result, method, params...) -} - -// Transfer initiates a plain transaction to move funds to the contract, calling -// its default method if one is available. -func (_BeaconProxy *BeaconProxyRaw) Transfer(opts *bind.TransactOpts) (*types.Transaction, error) { - return _BeaconProxy.Contract.BeaconProxyTransactor.contract.Transfer(opts) -} - -// Transact invokes the (paid) contract method with params as input values. -func (_BeaconProxy *BeaconProxyRaw) Transact(opts *bind.TransactOpts, method string, params ...interface{}) (*types.Transaction, error) { - return _BeaconProxy.Contract.BeaconProxyTransactor.contract.Transact(opts, method, params...) -} - -// Call invokes the (constant) contract method with params as input values and -// sets the output to result. The result type might be a single field for simple -// returns, a slice of interfaces for anonymous returns and a struct for named -// returns. -func (_BeaconProxy *BeaconProxyCallerRaw) Call(opts *bind.CallOpts, result *[]interface{}, method string, params ...interface{}) error { - return _BeaconProxy.Contract.contract.Call(opts, result, method, params...) -} - -// Transfer initiates a plain transaction to move funds to the contract, calling -// its default method if one is available. -func (_BeaconProxy *BeaconProxyTransactorRaw) Transfer(opts *bind.TransactOpts) (*types.Transaction, error) { - return _BeaconProxy.Contract.contract.Transfer(opts) -} - -// Transact invokes the (paid) contract method with params as input values. -func (_BeaconProxy *BeaconProxyTransactorRaw) Transact(opts *bind.TransactOpts, method string, params ...interface{}) (*types.Transaction, error) { - return _BeaconProxy.Contract.contract.Transact(opts, method, params...) -} - -// Fallback is a paid mutator transaction binding the contract fallback function. -// -// Solidity: fallback() payable returns() -func (_BeaconProxy *BeaconProxyTransactor) Fallback(opts *bind.TransactOpts, calldata []byte) (*types.Transaction, error) { - return _BeaconProxy.contract.RawTransact(opts, calldata) -} - -// Fallback is a paid mutator transaction binding the contract fallback function. -// -// Solidity: fallback() payable returns() -func (_BeaconProxy *BeaconProxySession) Fallback(calldata []byte) (*types.Transaction, error) { - return _BeaconProxy.Contract.Fallback(&_BeaconProxy.TransactOpts, calldata) -} - -// Fallback is a paid mutator transaction binding the contract fallback function. -// -// Solidity: fallback() payable returns() -func (_BeaconProxy *BeaconProxyTransactorSession) Fallback(calldata []byte) (*types.Transaction, error) { - return _BeaconProxy.Contract.Fallback(&_BeaconProxy.TransactOpts, calldata) -} - -// BeaconProxyBeaconUpgradedIterator is returned from FilterBeaconUpgraded and is used to iterate over the raw logs and unpacked data for BeaconUpgraded events raised by the BeaconProxy contract. -type BeaconProxyBeaconUpgradedIterator struct { - Event *BeaconProxyBeaconUpgraded // Event containing the contract specifics and raw log - - contract *bind.BoundContract // Generic contract to use for unpacking event data - event string // Event name to use for unpacking event data - - logs chan types.Log // Log channel receiving the found contract events - sub ethereum.Subscription // Subscription for errors, completion and termination - done bool // Whether the subscription completed delivering logs - fail error // Occurred error to stop iteration -} - -// Next advances the iterator to the subsequent event, returning whether there -// are any more events found. In case of a retrieval or parsing error, false is -// returned and Error() can be queried for the exact failure. -func (it *BeaconProxyBeaconUpgradedIterator) Next() bool { - // If the iterator failed, stop iterating - if it.fail != nil { - return false - } - // If the iterator completed, deliver directly whatever's available - if it.done { - select { - case log := <-it.logs: - it.Event = new(BeaconProxyBeaconUpgraded) - if err := it.contract.UnpackLog(it.Event, it.event, log); err != nil { - it.fail = err - return false - } - it.Event.Raw = log - return true - - default: - return false - } - } - // Iterator still in progress, wait for either a data or an error event - select { - case log := <-it.logs: - it.Event = new(BeaconProxyBeaconUpgraded) - if err := it.contract.UnpackLog(it.Event, it.event, log); err != nil { - it.fail = err - return false - } - it.Event.Raw = log - return true - - case err := <-it.sub.Err(): - it.done = true - it.fail = err - return it.Next() - } -} - -// Error returns any retrieval or parsing error occurred during filtering. -func (it *BeaconProxyBeaconUpgradedIterator) Error() error { - return it.fail -} - -// Close terminates the iteration process, releasing any pending underlying -// resources. -func (it *BeaconProxyBeaconUpgradedIterator) Close() error { - it.sub.Unsubscribe() - return nil -} - -// BeaconProxyBeaconUpgraded represents a BeaconUpgraded event raised by the BeaconProxy contract. -type BeaconProxyBeaconUpgraded struct { - Beacon common.Address - Raw types.Log // Blockchain specific contextual infos -} - -// FilterBeaconUpgraded is a free log retrieval operation binding the contract event 0x1cf3b03a6cf19fa2baba4df148e9dcabedea7f8a5c07840e207e5c089be95d3e. -// -// Solidity: event BeaconUpgraded(address indexed beacon) -func (_BeaconProxy *BeaconProxyFilterer) FilterBeaconUpgraded(opts *bind.FilterOpts, beacon []common.Address) (*BeaconProxyBeaconUpgradedIterator, error) { - - var beaconRule []interface{} - for _, beaconItem := range beacon { - beaconRule = append(beaconRule, beaconItem) - } - - logs, sub, err := _BeaconProxy.contract.FilterLogs(opts, "BeaconUpgraded", beaconRule) - if err != nil { - return nil, err - } - return &BeaconProxyBeaconUpgradedIterator{contract: _BeaconProxy.contract, event: "BeaconUpgraded", logs: logs, sub: sub}, nil -} - -// WatchBeaconUpgraded is a free log subscription operation binding the contract event 0x1cf3b03a6cf19fa2baba4df148e9dcabedea7f8a5c07840e207e5c089be95d3e. -// -// Solidity: event BeaconUpgraded(address indexed beacon) -func (_BeaconProxy *BeaconProxyFilterer) WatchBeaconUpgraded(opts *bind.WatchOpts, sink chan<- *BeaconProxyBeaconUpgraded, beacon []common.Address) (event.Subscription, error) { - - var beaconRule []interface{} - for _, beaconItem := range beacon { - beaconRule = append(beaconRule, beaconItem) - } - - logs, sub, err := _BeaconProxy.contract.WatchLogs(opts, "BeaconUpgraded", beaconRule) - if err != nil { - return nil, err - } - return event.NewSubscription(func(quit <-chan struct{}) error { - defer sub.Unsubscribe() - for { - select { - case log := <-logs: - // New log arrived, parse the event and forward to the user - event := new(BeaconProxyBeaconUpgraded) - if err := _BeaconProxy.contract.UnpackLog(event, "BeaconUpgraded", log); err != nil { - return err - } - event.Raw = log - - select { - case sink <- event: - case err := <-sub.Err(): - return err - case <-quit: - return nil - } - case err := <-sub.Err(): - return err - case <-quit: - return nil - } - } - }), nil -} - -// ParseBeaconUpgraded is a log parse operation binding the contract event 0x1cf3b03a6cf19fa2baba4df148e9dcabedea7f8a5c07840e207e5c089be95d3e. -// -// Solidity: event BeaconUpgraded(address indexed beacon) -func (_BeaconProxy *BeaconProxyFilterer) ParseBeaconUpgraded(log types.Log) (*BeaconProxyBeaconUpgraded, error) { - event := new(BeaconProxyBeaconUpgraded) - if err := _BeaconProxy.contract.UnpackLog(event, "BeaconUpgraded", log); err != nil { - return nil, err - } - event.Raw = log - return event, nil -} diff --git a/v2/scripts/generate_docs.sh b/v2/scripts/generate_docs.sh new file mode 100755 index 00000000..1f8adb68 --- /dev/null +++ b/v2/scripts/generate_docs.sh @@ -0,0 +1,13 @@ +#!/bin/bash + +forge doc + +cat docs/src/README.md docs/src/SUMMARY.md > docs/src/index.md + +echo -e "---\ntitle: \"Protocol contracts\"\n---\n" | cat - docs/src/index.md > temp && mv temp docs/src/index.md + +if [[ "$OSTYPE" == "darwin"* ]]; then + sed -i '' 's|contracts/|protocol/contracts/|g' docs/src/index.md +else + sed -i 's|contracts/|protocol/contracts/|g' docs/src/index.md +fi