### Install Project Dependencies with Yarn

Source: https://github.com/zeta-chain/protocol-contracts/blob/main/README.md

Installs all necessary dependencies for the ZetaChain protocol contracts project using Yarn. This is a prerequisite for building and testing the contracts.

```shell
yarn
```

--------------------------------

### Start Local Forked Network with Anvil

Source: https://github.com/zeta-chain/protocol-contracts/blob/main/scripts/deploy/readme.md

Starts a local forked blockchain node using Anvil. This is a prerequisite for simulating contract upgrades locally. You need to specify the RPC URL of the chain you want to fork. Two examples are provided: one for an Ethereum Sepolia testnet and another for ZetaChain Athens.

```bash
anvil --fork-url <rpc>
```

```bash
anvil --fork-url https://ethereum-sepolia.rpc.subquery.network/public
```

```bash
anvil --fork-url https://zetachain-athens.g.allthatnode.com/archive/evm
```

--------------------------------

### Environment Configuration (.env) Example (Text)

Source: https://github.com/zeta-chain/protocol-contracts/blob/main/scripts/safe/readme.md

This is an example of the `.env` file required to configure the Safe upgrade proposal script. It includes placeholders for the Safe API key, the private key of the wallet that will propose the upgrade, and the address of that wallet. An optional `UPGRADE_DATA` variable can also be set.

```dotenv
# Safe API Configuration
SAFE_API_KEY=your_safe_api_key_here

# Proposer Wallet Configuration
PROPOSER_PRIVATE_KEY=0x1234567890abcdef...  # Private key of the proposer wallet
PROPOSER_ADDRESS=0x1234567890123456789012345678901234567890  # Address of the proposer wallet

# Optional: Default upgrade data
UPGRADE_DATA=0x  # Default: empty bytes (0x)

```

--------------------------------

### Deterministic Deployment Example with Forge

Source: https://github.com/zeta-chain/protocol-contracts/blob/main/scripts/deploy/readme.md

This illustrates the concept of deterministic deployments using create2 with Foundry. It involves calculating the expected address, using a salt, and performing basic assertions to ensure address consistency across EVM chains. The provided code snippet is conceptual and refers to Foundry's create2 tutorial.

```shell
# Conceptual example, refer to Foundry create2 tutorial for implementation details.
# This involves calculating expected address, adding a salt, and deploying.
```

--------------------------------

### Hardhat CLI Usage Examples (Shell)

Source: https://github.com/zeta-chain/protocol-contracts/blob/main/scripts/safe/readme.md

These commands demonstrate how to execute the Hardhat upgrade proposal script from the command line. They show basic usage for testnet and mainnet, as well as options for providing custom upgrade data directly, from a file, or via an environment variable.

```bash
# Create upgrade proposals for testnet networks
npx hardhat upgradeProposal --testnet

# Create upgrade proposals for mainnet networks
npx hardhat upgradeProposal --mainnet

# Pass upgrade data directly
npx hardhat upgradeProposal --testnet --upgrade-data "0x1234567890abcdef"

# Load upgrade data from file
npx hardhat upgradeProposal --testnet --upgrade-data-file upgrade_data.txt

# Using environment variable
UPGRADE_DATA="0x1234567890abcdef" npx hardhat upgradeProposal --testnet

```

--------------------------------

### Get All Contracts Information - Solidity

Source: https://github.com/zeta-chain/protocol-contracts/blob/main/docs/index.md

Retrieves information for all contracts registered within the system. This function returns an array of `ContractInfoDTO` structs, containing details about each contract.

```solidity
function getAllContracts() external view returns (ContractInfoDTO[] memory);
```

--------------------------------

### Get All Chains Information (Solidity)

Source: https://github.com/zeta-chain/protocol-contracts/blob/main/docs/index.md

This function returns an array of `ChainInfoDTO` structs, containing information for all chains registered in the ZetaChain system, regardless of their active status. This provides a comprehensive overview of all chains.

```solidity
function getAllChains() external view returns (ChainInfoDTO[] memory chainsInfo);
```

--------------------------------

### Get All Contracts Information (Solidity)

Source: https://github.com/zeta-chain/protocol-contracts/blob/main/docs/index.md

This function returns an array of `ContractInfoDTO` structs, providing information about all contracts registered within the ZetaChain system. This is useful for auditing and understanding the deployed contract landscape.

```solidity
function getAllContracts() external view returns (ContractInfoDTO[] memory contractsInfo);
```

--------------------------------

### Get All Chains Information - Solidity

Source: https://github.com/zeta-chain/protocol-contracts/blob/main/docs/index.md

Fetches comprehensive information for all registered chains, including both active and inactive ones. This function returns an array of `ChainInfoDTO` structs, providing details for each chain.

```solidity
function getAllChains() external view returns (ChainInfoDTO[] memory);
```

--------------------------------

### Get ZRC20 Information with Shell Script

Source: https://github.com/zeta-chain/protocol-contracts/blob/main/scripts/deploy/readme.md

This utility script retrieves information required for deploying or verifying ZRC20 contracts. It requires the 'cast' CLI tool from the Foundry suite. The output provides environment variables for contract deployment.

```shell
./scripts/utils/get_zrc20_info.sh <zrc20_address> <rpc>
```

--------------------------------

### GatewayEVM Initialization and Upgrade

Source: https://github.com/zeta-chain/protocol-contracts/blob/main/docs/index.md

Documentation for initializing and authorizing upgrades for the GatewayEVM contract.

```APIDOC
## Initialization and Upgrade Functions

### initialize

#### Description
Initialize the contract with the TSS address, Zeta token address, and admin account. The admin account is set as the DEFAULT_ADMIN_ROLE for upgrades and pausing, while the TSS address is assigned the TSS role.

#### Method
`public initializer`

#### Parameters
- **tssAddress_** (`address`) - The address of the TSS contract.
- **zetaToken_** (`address`) - The address of the Zeta token contract.
- **admin_** (`address`) - The address of the admin account.

### _authorizeUpgrade

#### Description
Authorizes the upgrade of the contract. This function can only be called by the owner (DEFAULT_ADMIN_ROLE).

#### Method
`internal override onlyRole(DEFAULT_ADMIN_ROLE)`

#### Parameters
- **newImplementation** (`address`) - The address of the new implementation contract.
```

--------------------------------

### Get Active Chains (Solidity)

Source: https://github.com/zeta-chain/protocol-contracts/blob/main/docs/index.md

This function retrieves an array of chain IDs for all currently active chains in the ZetaChain registry. It provides a simple way to get a list of operational chains.

```solidity
function getActiveChains() external view returns (uint256[] memory);
```

--------------------------------

### Deploy GatewayEVM Implementation with Forge

Source: https://github.com/zeta-chain/protocol-contracts/blob/main/scripts/deploy/readme.md

Deploys a new implementation contract for GatewayEVM using Forge scripts. This process does not require environment variables or parameters for the deployment itself. It supports verification and broadcasting the transaction. Ensure you replace placeholders like <PRIVATE_KEY>, <RPC_URL>, <ETHERSCAN_API_KEY>, and <CHAIN_ID>.

```bash
forge script scripts/deploy/deterministic/DeployGatewayEVMImplementation.s.sol \
  --private-key <PRIVATE_KEY> \
  --rpc-url <RPC_URL> \
  --verify \
  --etherscan-api-key <ETHERSCAN_API_KEY> \
  --chain-id <CHAIN_ID> \
  --broadcast
```

--------------------------------

### Get GatewayZEVM Address (Solidity)

Source: https://github.com/zeta-chain/protocol-contracts/blob/main/docs/index.md

This external function returns the address of the GatewayZEVM contract. This is essential for interacting with the gateway to perform cross-chain operations and manage tokens.

```solidity
function gatewayZEVM() external returns (address);
```

--------------------------------

### Get Maximum Message Size (Solidity)

Source: https://github.com/zeta-chain/protocol-contracts/blob/main/docs/index.md

A pure function that returns the maximum allowed size for messages. This is useful for determining payload limits in cross-chain communications.

```solidity
function getMaxMessageSize() external pure returns (uint256);

```

--------------------------------

### Deploy GatewayZEVM Implementation with Forge

Source: https://github.com/zeta-chain/protocol-contracts/blob/main/scripts/deploy/readme.md

Initiates the deployment of a new GatewayZEVM implementation contract via Forge. This script requires connection details for the RPC URL and verification settings, including a verifier URL. Replace placeholders for private key, RPC URL, verification URL, and chain ID.

```bash
forge script scripts/deploy/deterministic/DeployGatewayZEVMImplementation.s.sol \
  --private-key <PRIVATE_KEY> \
  --rpc-url <RPC_URL> \
  --verify \
  --verifier blockscout \
  --verifier-url <VERIFIER_URL> \
  --chain-id <CHAIN_ID> \
  --broadcast
```

--------------------------------

### Get All ZRC20 Tokens Information - Solidity

Source: https://github.com/zeta-chain/protocol-contracts/blob/main/docs/index.md

Fetches information for all ZRC20 tokens that are currently active. This function returns an array of `ZRC20Info` structs, providing details for each token.

```solidity
function getAllZRC20Tokens() external view returns (ZRC20Info[] memory);
```

--------------------------------

### Get Minimum Gas Limit (Solidity)

Source: https://github.com/zeta-chain/protocol-contracts/blob/main/docs/index.md

A pure function that returns the minimum gas limit that is permitted for transactions. This helps in setting appropriate gas values for operations.

```solidity
function getMinGasLimit() external pure returns (uint256);

```

--------------------------------

### Constructor for ZetaConnectorZEVM

Source: https://github.com/zeta-chain/protocol-contracts/blob/main/docs/index.md

Initializes the ZetaConnectorZEVM contract with the provided WZETA address. This constructor sets up the contract to interact with WZETA for ZETA token management.

```solidity
constructor(address wzeta_);
```

--------------------------------

### Build Project Contracts with Forge

Source: https://github.com/zeta-chain/protocol-contracts/blob/main/README.md

Compiles all Solidity contracts in the project using the Forge build command. This is a necessary step before testing or deploying the contracts.

```shell
forge build
```

--------------------------------

### Solidity Constructor: SystemContract

Source: https://github.com/zeta-chain/protocol-contracts/blob/main/docs/index.md

The constructor for the SystemContract, which can only be deployed by the fungible module. It initializes addresses for wZETA, Uniswap V2 factory, and Uniswap V2 router.

```solidity
constructor(address wzeta_, address uniswapv2Factory_, address uniswapv2Router02_);
```

--------------------------------

### Deploy Project Contracts with Forge Script

Source: https://github.com/zeta-chain/protocol-contracts/blob/main/README.md

Deploys the project's smart contracts to a specified RPC URL using a private key. This command requires a deployment script and network connection details.

```shell
forge script script/<DeployScript>.s.sol:<DeployScript> --rpc-url <your_rpc_url> --private-key <your_private_key>
```

--------------------------------

### Bootstrap Contracts Data in Solidity

Source: https://github.com/zeta-chain/protocol-contracts/blob/main/docs/index.md

Initializes the registry with contract data. This function takes arrays of ContractInfoDTO and ContractConfigEntry structures. It can only be invoked by an address with the REGISTRY_MANAGER_ROLE and requires the system to be unpaused.

```solidity
function bootstrapContracts(
    ContractInfoDTO[] calldata contracts,
    ContractConfigEntry[] calldata configEntries
)
    external
    onlyRole(REGISTRY_MANAGER_ROLE)
    whenNotPaused;
```

--------------------------------

### Get ZRC20 Address by Foreign Asset (Solidity)

Source: https://github.com/zeta-chain/protocol-contracts/blob/main/docs/index.md

This function returns the ZetaChain ZRC20 token address corresponding to a given asset on a foreign chain. It requires the `originChainId` and the `originAddress` of the asset. This is essential for cross-chain asset mapping.

```solidity
function getZRC20AddressByForeignAsset(
    uint256 originChainId,
    bytes calldata originAddress
)
    external
    view
    returns (address);
```

--------------------------------

### Get Maximum Revert Gas Limit (Solidity)

Source: https://github.com/zeta-chain/protocol-contracts/blob/main/docs/index.md

A pure function that returns the maximum gas limit allowed for revert operations. This parameter is crucial for managing gas costs associated with failed transactions or revert scenarios.

```solidity
function getMaxRevertGasLimit() external pure returns (uint256);

```

--------------------------------

### ZetaConnectorZEVM - constructor

Source: https://github.com/zeta-chain/protocol-contracts/blob/main/docs/index.md

Initializes the ZetaConnectorZEVM contract with the address of the WZETA token.

```APIDOC
## constructor ZetaConnectorZEVM

### Description
Initializes the ZetaConnectorZEVM contract with the provided WZETA token address.

### Method
CONSTRUCTOR

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **wzeta_** (address) - The address of the WZETA token contract.

### Request Example
```solidity
constructor(address wzeta_);
```

### Response
N/A
```

--------------------------------

### UniversalContract - constructor

Source: https://github.com/zeta-chain/protocol-contracts/blob/main/docs/index.md

Initializes the UniversalContract by retrieving the gateway address from the registry. It fetches the gateway contract address for the current chain from the registry. If the gateway is not active or not found, the gateway will remain uninitialized.

```APIDOC
## constructor UniversalContract

### Description
Initializes the contract by retrieving the gateway address from the registry.
Fetches the gateway contract address for the current chain from the registry. If the gateway is not active or not found, the gateway will remain uninitialized (address(0)).

### Method
CONSTRUCTOR

### Endpoint
N/A

### Parameters
None

### Request Example
```solidity
constructor();
```

### Response
N/A
```

--------------------------------

### Get Next Action Index (Solidity)

Source: https://github.com/zeta-chain/protocol-contracts/blob/main/docs/index.md

An internal function that retrieves and increments the transaction action counter using transient storage for gas efficiency. Transient storage is cleared after each transaction. It returns the current action index.

```solidity
function _getNextActionIndex() internal returns (uint256 currentIndex);

```

--------------------------------

### Constructor for ZetaEth ERC20 Token in Solidity

Source: https://github.com/zeta-chain/protocol-contracts/blob/main/docs/index.md

Initializes the ZetaEth ERC20 token. It requires the address of the creator and an initial supply of tokens to be minted upon deployment.

```solidity
constructor(address creator, uint256 initialSupply);
```

--------------------------------

### Define ContractConfigEntry Struct in Solidity

Source: https://github.com/zeta-chain/protocol-contracts/blob/main/docs/index.md

Defines the ContractConfigEntry structure for storing configuration details of contracts during bootstrapping. It includes the chain ID, contract type, a key, and a byte-encoded value. This allows for flexible and dynamic contract setup.

```solidity
struct ContractConfigEntry {
    uint256 chainId;
    string contractType;
    string key;
    bytes value;
}
```

--------------------------------

### Deploy ERC20Custody Implementation with Forge

Source: https://github.com/zeta-chain/protocol-contracts/blob/main/scripts/deploy/readme.md

Deploys a new implementation contract for ERC20Custody using Forge scripts. Similar to GatewayEVM, this deployment does not need specific environment variables or parameters. The command includes options for verification, broadcasting, and requires placeholders for private key, RPC URL, Etherscan API key, and chain ID.

```bash
forge script scripts/deploy/deterministic/DeployERC20CustodyImplementation.s.sol \
  --private-key <PRIVATE_KEY> \
  --rpc-url <RPC_URL> \
  --verify \
  --etherscan-api-key <ETHERSCAN_API_KEY> \
  --chain-id <CHAIN_ID> \
  --broadcast
```

--------------------------------

### Get All ZRC20 Tokens Information (Solidity)

Source: https://github.com/zeta-chain/protocol-contracts/blob/main/docs/index.md

Retrieves an array of ZRC20Info structs, each containing details about a registered ZRC20 token. This function is viewable, meaning it does not modify the blockchain state. It is essential for querying the registry's current token inventory.

```solidity
function getAllZRC20Tokens() external view returns (ZRC20Info[] memory tokensInfo);
```

--------------------------------

### Set Environment Variables for Upgrade Simulation

Source: https://github.com/zeta-chain/protocol-contracts/blob/main/scripts/deploy/readme.md

Sets the necessary environment variables required before running the upgrade simulation scripts. PROXY_ADDRESS should be set to the address of the contract you intend to test, and ADMIN_ADDRESS should be the address of the contract's administrator.

```bash
export PROXY_ADDRESS=<proxy address of the contract to test>
export ADMIN_ADDRESS=<address of the admin that upgrade the contract>
```

--------------------------------

### GatewayEVM Constructor and Initialization

Source: https://github.com/zeta-chain/protocol-contracts/blob/main/docs/index.md

Handles the initialization of the GatewayEVM contract. The constructor is marked as unsafe for upgrades, while the initialize function sets up the TSS address, Zeta token address, and the default admin role, which is used for authorization and pausing.

```solidity
constructor();

function initialize(address tssAddress_, address zetaToken_, address admin_) public initializer;
```

--------------------------------

### Get Protocol Flat Fee from Registry

Source: https://github.com/zeta-chain/protocol-contracts/blob/main/docs/index.md

Helper function to retrieve the protocol's flat fee for a given external chain from a registry. It takes the chain ID of the external chain as input and returns the flat fee amount. This is a view function.

```solidity
function _getProtocolFlatFeeFromRegistry(uint256 chainId) private view returns (uint256 protocolFlatFee);
```

--------------------------------

### ZRC20 Token Metadata Interface Functions (Solidity)

Source: https://github.com/zeta-chain/protocol-contracts/blob/main/docs/index.md

Defines the interface for retrieving metadata of ZRC20 tokens on ZetaChain. This includes functions to get the token's name, symbol, and the number of decimal places it uses. These functions are essential for interacting with tokens in a user-friendly manner.

```solidity
function name() external view returns (string memory);
```

```solidity
function symbol() external view returns (string memory);
```

```solidity
function decimals() external view returns (uint8);
```

--------------------------------

### Format Project Contracts with Forge

Source: https://github.com/zeta-chain/protocol-contracts/blob/main/README.md

Formats all Solidity code within the project according to standard conventions using the Forge fmt command. This helps maintain code readability and consistency.

```shell
forge fmt
```

--------------------------------

### Get Gas Limit for ZETA Transfer

Source: https://github.com/zeta-chain/protocol-contracts/blob/main/docs/index.md

Helper function to retrieve the gas limit required for a ZETA transfer to an external chain. It takes the chain ID of the external chain as input and returns the calculated gas limit. This is a view function, meaning it does not modify the contract's state.

```solidity
function _getGasLimitForZETATransfer(uint256 chainId) private view returns (uint256 gasLimit);
```

--------------------------------

### ZetaConnectorBase Contract

Source: https://github.com/zeta-chain/protocol-contracts/blob/main/docs/index.md

Documentation for the base contract functionalities, including initialization, authorization, address updates, and pausing/unpausing.

```APIDOC
## ZetaConnectorBase Contract

### Functions

#### constructor

**Description:**
Contract constructor.

### Method

`constructor()`

#### initialize

**Description:**
Initializer for ZetaConnectors. Sets admin as default admin and pauser, and tssAddress as tss role.

### Method

`initialize(address gateway_, address zetaToken_, address tssAddress_, address admin_)

#### _authorizeUpgrade

**Description:**
Authorizes the upgrade of the contract. Sender must be the owner.

### Method

`_authorizeUpgrade(address newImplementation)

### Parameters

#### Path Parameters
- **newImplementation** (address) - Required - Address of the new implementation.

#### updateTSSAddress

**Description:**
Update tss address.

### Method

`updateTSSAddress(address newTSSAddress)

### Parameters

#### Path Parameters
- **newTSSAddress** (address) - Required - new tss address

#### pause

**Description:**
Pause contract.

### Method

`pause()

#### unpause

**Description:**
Unpause contract.

### Method

`unpause()

#### deposit

**Description:**
Handle received tokens.

### Method

`deposit(uint256 amount)

### Parameters

#### Path Parameters
- **amount** (uint256) - Required - The amount of tokens received.

### Errors

#### ZeroAddress

**Description:**
Error indicating that a zero address was provided.

### Method

`error ZeroAddress()`
```

--------------------------------

### Deploy GatewayZEVM Contract on ZetaChain

Source: https://github.com/zeta-chain/protocol-contracts/blob/main/scripts/deploy/readme.md

Deploys the GatewayZEVM contract on ZetaChain. Requires specific environment variables like GATEWAY_ADMIN_ADDRESS_ZEVM and WZETA. This deployment uses Blockscout for verification.

```shell
forge script scripts/deploy/deterministic/DeployGatewayZEVM.s.sol \
  --private-key <PRIVATE_KEY> \
  --rpc-url <RPC_URL> \
  --verify \
  --verifier blockscout \
  --verifier-url <VERIFIER_URL> \
  --chain-id <CHAIN_ID> \
  --broadcast
```

--------------------------------

### Bootstrap Chains Data in Solidity

Source: https://github.com/zeta-chain/protocol-contracts/blob/main/docs/index.md

Initializes the registry with chain data. This function accepts an array of ChainInfoDTO and ChainMetadataEntry structures. It is exclusively callable by an address holding the REGISTRY_MANAGER_ROLE and ensures the system is not paused.

```solidity
function bootstrapChains(
    ChainInfoDTO[] calldata chains,
    ChainMetadataEntry[] calldata metadataEntries
)
    external
    onlyRole(REGISTRY_MANAGER_ROLE)
    whenNotPaused;
```

--------------------------------

### General Forge Deployment Script

Source: https://github.com/zeta-chain/protocol-contracts/blob/main/scripts/deploy/readme.md

This is the general command format for executing any Forge deployment script. It requires specifying the script path, RPC URL, and private key. The `--broadcast` flag is used to execute the transaction.

```shell
forge script scripts/deploy/<Script>.s.sol --rpc-url <RPC_URL> --private-key <PRIVATE_KEY> --broadcast 
```

--------------------------------

### Run Project Tests with Forge

Source: https://github.com/zeta-chain/protocol-contracts/blob/main/README.md

Executes all unit tests for the ZetaChain protocol contracts using the Forge test command. This ensures the contracts function as expected.

```shell
forge test
```

--------------------------------

### Simulate GatewayEVM Upgrade with Forge

Source: https://github.com/zeta-chain/protocol-contracts/blob/main/scripts/deploy/readme.md

Runs a Forge script to simulate the upgrade process for GatewayEVM on a locally forked network. This script helps in verifying the contract's state before and after an upgrade without affecting the main network. It requires a local RPC URL, typically http://localhost:8545.

```bash
forge script scripts/upgrade/SimulateGatewayEVMUpgrade.s.sol --rpc-url http://localhost:8545
```

--------------------------------

### Implement initialize Function in CoreRegistry

Source: https://github.com/zeta-chain/protocol-contracts/blob/main/docs/index.md

Initializes the CoreRegistry contract by setting the admin, registry manager, and GatewayZEVM contract addresses. This function is crucial for setting up the registry's core components and roles.

```solidity
function initialize(address admin_, address registryManager_, address gatewayZEVM_) public initializer;
```

--------------------------------

### Initialize GatewayZEVM (Solidity)

Source: https://github.com/zeta-chain/protocol-contracts/blob/main/docs/index.md

The initialization function for the GatewayZEVM contract. It sets the Zeta token address and designates an admin account for upgrades and pausing. It requires the zeta token address and admin address as parameters.

```solidity
function initialize(address zetaToken_, address admin_) public initializer;

```

--------------------------------

### IGatewayEVM Interface Functions

Source: https://github.com/zeta-chain/protocol-contracts/blob/main/docs/index.md

Documentation for the functions available in the IGatewayEVM interface, including executeWithERC20, executeRevert, execute, revertWithERC20, and deposit.

```APIDOC
## executeWithERC20

### Description
Executes a call to a contract using ERC20 tokens.

### Method
`external`

### Endpoint
N/A (Contract function)

### Parameters

#### Function Parameters

- **messageContext** (MessageContext) - Message context containing sender and arbitrary call flag.
- **token** (address) - The address of the ERC20 token.
- **to** (address) - The address of the contract to call.
- **amount** (uint256) - The amount of tokens to transfer.
- **data** (bytes) - The calldata to pass to the contract call.

### Request Example

```solidity
function executeWithERC20(
    MessageContext calldata messageContext,
    address token,
    address to,
    uint256 amount,
    bytes calldata data
)
    external;
```
```

```APIDOC
## executeRevert

### Description
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.

### Method
`external payable`

### Endpoint
N/A (Contract function)

### Parameters

#### Function Parameters

- **destination** (address) - Address to call.
- **data** (bytes) - Calldata to pass to the call.
- **revertContext** (RevertContext) - Revert context to pass to onRevert.

### Request Example

```solidity
function executeRevert(
    address destination,
    bytes calldata data,
    RevertContext calldata revertContext
)
    external
    payable;
```
```

```APIDOC
## execute

### Description
Executes a call to a destination address without ERC20 tokens. This function can only be called by the TSS address and it is payable.

### Method
`external payable returns (bytes memory)`

### Endpoint
N/A (Contract function)

### Parameters

#### Function Parameters

- **messageContext** (MessageContext) - Message context containing sender and arbitrary call flag.
- **destination** (address) - Address to call.
- **data** (bytes) - Calldata to pass to the call.

### Returns

#### Return Values

- **(bytes memory)** - The result of the call.

### Request Example

```solidity
function execute(
    MessageContext calldata messageContext,
    address destination,
    bytes calldata data
)
    external
    payable
    returns (bytes memory);
```
```

```APIDOC
## revertWithERC20

### Description
Executes a revertable call to a contract using ERC20 tokens.

### Method
`external`

### Endpoint
N/A (Contract function)

### Parameters

#### Function Parameters

- **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.

### Request Example

```solidity
function revertWithERC20(
    address token,
    address to,
    uint256 amount,
    bytes calldata data,
    RevertContext calldata revertContext
)
    external;
```
```

```APIDOC
## deposit (ETH)

### Description
Deposits ETH to the TSS address.

### Method
`external payable`

### Endpoint
N/A (Contract function)

### Parameters

#### Function Parameters

- **receiver** (address) - Address of the receiver.
- **revertOptions** (RevertOptions) - Revert options.

### Request Example

```solidity
function deposit(address receiver, RevertOptions calldata revertOptions) external payable;
```
```

```APIDOC
## deposit (ETH with Amount)

### Description
Deposits ETH to the TSS address with specified amount.

### Method
`external payable`

### Endpoint
N/A (Contract function)

### Parameters

#### Function Parameters

- **receiver** (address) - Address of the receiver.
- **amount** (uint256) - Amount of ETH to deposit.
- **revertOptions** (RevertOptions) - Revert options.

### Request Example

```solidity
function deposit(address receiver, uint256 amount, RevertOptions calldata revertOptions) external payable;
```
```

```APIDOC
## deposit (ERC20)

### Description
Deposits ERC20 tokens to the custody or connector contract.

### Method
`external payable`

### Endpoint
N/A (Contract function)

### Parameters

#### Function Parameters

- **receiver** (address) - Address of the receiver.
- **amount** (uint256) - Amount of tokens to deposit.
- **asset** (address) - Address of the ERC20 token.
- **revertOptions** (RevertOptions) - Revert options.

### Request Example

```solidity
function deposit(
    address receiver,
    uint256 amount,
    address asset,
    RevertOptions calldata revertOptions
)
    external
    payable;
```
```

--------------------------------

### Solidity: Initialize Registry Contract

Source: https://github.com/zeta-chain/protocol-contracts/blob/main/docs/index.md

Initializes the Registry contract with administrative and configuration addresses. This function sets up roles and critical contract pointers upon deployment.

```solidity
function initialize(
    address admin_,
    address registryManager_,
    address gatewayEVM_,
    address coreRegistry_
)
    public
    initializer;

```

--------------------------------

### Deploy Gateway ZEVM Implementation Contract (Solidity)

Source: https://github.com/zeta-chain/protocol-contracts/blob/main/scripts/deploy/readme.md

This Forge script deploys the implementation contract for the Gateway contract on ZetaChain, used for upgrades.

```solidity
forge script deterministic/DeployGatewayZEVMImplementation.s.sol --rpc-url <RPC_URL> --private-key <PRIVATE_KEY> --broadcast
```

--------------------------------

### bootstrapContracts

Source: https://github.com/zeta-chain/protocol-contracts/blob/main/docs/index.md

Bootstraps the registry with contract data. This function can only be called by an address with the REGISTRY_MANAGER_ROLE.

```APIDOC
## POST /bootstrapContracts

### Description
Bootstrap the registry with contract data. This function can only be called by an address with the REGISTRY_MANAGER_ROLE.

### Method
POST

### Endpoint
/bootstrapContracts

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **contracts** (ContractInfoDTO[]) - Required - Array of contract data structures to bootstrap
- **configEntries** (ContractConfigEntry[]) - Required - Array of contract configuration entries

### Request Example
```json
{
  "contracts": [
    {
      "chainId": 1,
      "contractType": "ExampleContract",
      "address": "0x..."
    }
  ],
  "configEntries": [
    {
      "chainId": 1,
      "contractType": "ExampleContract",
      "key": "configKey",
      "value": "0x..."
    }
  ]
}
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the operation was successful.

#### Response Example
```json
{
  "success": true
}
```
```

--------------------------------

### Bootstrap ZRC20 Tokens Data in Solidity

Source: https://github.com/zeta-chain/protocol-contracts/blob/main/docs/index.md

Initializes the registry with ZRC20 token data. This function accepts an array of ZRC20Info structures. It is restricted to addresses with the REGISTRY_MANAGER_ROLE and ensures the contract is not paused.

```solidity
function bootstrapZRC20Tokens(ZRC20Info[] calldata tokens) external onlyRole(REGISTRY_MANAGER_ROLE) whenNotPaused;
```

--------------------------------

### Constructor for ZetaConnector Contracts

Source: https://github.com/zeta-chain/protocol-contracts/blob/main/docs/index.md

The constructor function is used to initialize the contract. It's marked with 'oz-upgrades-unsafe-allow: constructor' to permit its use with upgradeable contracts.

```solidity
constructor();
```

--------------------------------

### Deploy GatewayEVM Contract

Source: https://github.com/zeta-chain/protocol-contracts/blob/main/scripts/deploy/readme.md

Deploys the GatewayEVM contract on connected chains. Requires environment variables like TSS_ADDRESS, GATEWAY_ADMIN_ADDRESS_EVM, and ZETA_ERC20_EVM to be set. Supports optional verification with Etherscan or Blockscout.

```shell
forge script scripts/deploy/deterministic/DeployGatewayEVM.s.sol \
  --private-key <PRIVATE_KEY> \
  --rpc-url <RPC_URL> \
  --verify \
  --etherscan-api-key <ETHERSCAN_API_KEY> \
  --chain-id <CHAIN_ID> \
  --broadcast
```

```shell
forge script scripts/deploy/deterministic/DeployGatewayEVM.s.sol \
  --private-key <PRIVATE_KEY> \
  --rpc-url <RPC_URL> \
  --verify \
  --verifier blockscout \
  --verifier-url <VERIFIER_URL> \
  --chain-id <CHAIN_ID> \
  --broadcast
```

--------------------------------

### Compare ZRC20 Contract Information with Shell Script

Source: https://github.com/zeta-chain/protocol-contracts/blob/main/scripts/deploy/readme.md

This utility script verifies if a newly deployed reference ZRC20 contract matches the constructor arguments of a base contract. It takes the addresses of both contracts and the RPC endpoint as input.

```shell
./scripts/utils/compare_zrc20_info.sh <base_contract> <reference_contract> <rpc>
```

--------------------------------

### GatewayEVM Contract Information

Source: https://github.com/zeta-chain/protocol-contracts/blob/main/docs/index.md

Provides an overview of the GatewayEVM contract, its purpose, and key state variables.

```APIDOC
## GatewayEVM Contract

### Description
The GatewayEVM contract is the endpoint to call smart contracts on external chains. It does not hold any funds and should never have active allowances.

### State Variables

#### custody
- **Type**: address
- **Description**: The address of the custody contract.

#### tssAddress
- **Type**: address
- **Description**: The address of the TSS (Threshold Signature Scheme) contract.

#### zetaConnector
- **Type**: address
- **Description**: The address of the ZetaConnector contract.

#### zetaToken
- **Type**: address
- **Description**: The address of the Zeta token contract.

#### additionalActionFeeWei
- **Type**: uint256
- **Description**: Fee charged for additional cross-chain actions within the same transaction. The first action is free, subsequent actions incur this fee. Configurable by the admin role.

#### TSS_ROLE
- **Type**: bytes32
- **Description**: Role identifier for the TSS role.

#### ASSET_HANDLER_ROLE
- **Type**: bytes32
- **Description**: Role identifier for the asset handler role.

#### PAUSER_ROLE
- **Type**: bytes32
- **Description**: Role identifier for the pauser role.

#### MAX_PAYLOAD_SIZE
- **Type**: uint256
- **Description**: Maximum size of payload + revertOptions revert message.

#### _TRANSACTION_ACTION_COUNT_KEY
- **Type**: uint256
- **Description**: Storage slot key for tracking transaction action count, uses transient storage for gas efficiency. Value 0x01 is used as a unique identifier.
```

--------------------------------

### Compile Contracts with Hardhat

Source: https://github.com/zeta-chain/protocol-contracts/blob/main/scripts/checksum/readme.md

Compiles the smart contracts using the Hardhat development environment. This step is typically required before running verification scripts to generate necessary artifacts.

```bash
npx hardhat compile
```

--------------------------------

### Deploy Gateway EVM Implementation Contract (Solidity)

Source: https://github.com/zeta-chain/protocol-contracts/blob/main/scripts/deploy/readme.md

This Forge script deploys the implementation contract for the GatewayEVM contract, used for contract upgrades.

```solidity
forge script deterministic/DeployGatewayEVMImplementation.s.sol --rpc-url <RPC_URL> --private-key <PRIVATE_KEY> --broadcast
```

--------------------------------

### Deploy ZRC20 Contract with Forge Script

Source: https://github.com/zeta-chain/protocol-contracts/blob/main/scripts/deploy/readme.md

This command deploys a ZRC20 contract using Forge, the command-line interface for Foundry. It requires environment variables to be set beforehand and supports contract verification. Ensure you replace placeholders like <PRIVATE_KEY> and <RPC_URL>.

```shell
forge script scripts/deploy/DeployZRC20.s.sol \
  --private-key <PRIVATE_KEY> \
  --rpc-url <RPC_URL> \
  --verify \
  --verifier blockscout \
  --verifier-url <VERIFIER_URL> \
  --chain-id <CHAIN_ID> \
  --broadcast
```

--------------------------------

### Simulate GatewayZEVM Upgrade with Forge

Source: https://github.com/zeta-chain/protocol-contracts/blob/main/scripts/deploy/readme.md

Runs a Forge script to locally simulate an upgrade for the GatewayZEVM contract. This is crucial for testing the integrity of the contract's state post-upgrade in a controlled environment. The script connects to a local RPC endpoint, typically http://localhost:8545.

```bash
forge script scripts/upgrade/SimulateGatewayZEVMUpgrade.s.sol --rpc-url http://localhost:8545
```

--------------------------------

### bootstrapZRC20Tokens

Source: https://github.com/zeta-chain/protocol-contracts/blob/main/docs/index.md

Bootstraps the registry with ZRC20 token data. This function can only be called by an address with the REGISTRY_MANAGER_ROLE.

```APIDOC
## POST /bootstrapZRC20Tokens

### Description
Bootstrap the registry with ZRC20 token data. This function can only be called by an address with the REGISTRY_MANAGER_ROLE.

### Method
POST

### Endpoint
/bootstrapZRC20Tokens

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **tokens** (ZRC20Info[]) - Required - Array of ZRC20 token data structures to bootstrap

### Request Example
```json
{
  "tokens": [
    {
      "address_": "0x123...",
      "symbol": "ZRC20Symbol",
      "originChainId": 10,
      "originAddress": "0xabc...",
      "coinType": "erc20",
      "decimals": 18
    }
  ]
}
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the operation was successful.

#### Response Example
```json
{
  "success": true
}
```
```

--------------------------------

### Constructor (Solidity)

Source: https://github.com/zeta-chain/protocol-contracts/blob/main/docs/index.md

The constructor function for the GatewayZEVM contract. It is marked with 'oz-upgrades-unsafe-allow: constructor', indicating potential upgrade-related considerations.

```solidity
constructor();

```

--------------------------------

### Deploy ERC20Custody Contract

Source: https://github.com/zeta-chain/protocol-contracts/blob/main/scripts/deploy/readme.md

Deploys the ERC20Custody contract on connected chains. Requires GatewayEVM deployment and specific environment variables including ERC20_CUSTODY_ADMIN_ADDRESS_EVM and GATEWAY_PROXY_EVM. Supports optional verification.

```shell
forge script scripts/deploy/deterministic/DeployERC20Custody.s.sol \
  --private-key <PRIVATE_KEY> \
  --rpc-url <RPC_URL> \
  --verify \
  --etherscan-api-key <ETHERSCAN_API_KEY> \
  --chain-id <CHAIN_ID> \
  --broadcast
```

--------------------------------

### Initialize ZetaConnectors Base Contract

Source: https://github.com/zeta-chain/protocol-contracts/blob/main/docs/index.md

Initializes the ZetaConnectors contract, setting the admin and tssAddress roles. This function is typically called once during contract deployment.

```solidity
function initialize(
    address gateway_,
    address zetaToken_,
    address tssAddress_,
    address admin_
)
    public
    virtual
    onlyInitializing;

```

--------------------------------

### Deploy Gateway EVM Contract (Solidity)

Source: https://github.com/zeta-chain/protocol-contracts/blob/main/scripts/deploy/readme.md

This Forge script deploys the GatewayEVM contract on a connected EVM chain using deterministic deployment.

```solidity
forge script deterministic/DeployGatewayEVM.s.sol --rpc-url <RPC_URL> --private-key <PRIVATE_KEY> --broadcast
```

--------------------------------

### Deploy ZetaConnector Contracts

Source: https://github.com/zeta-chain/protocol-contracts/blob/main/scripts/deploy/readme.md

Deploys ZetaConnector contracts. ZetaConnectorNative is used for Ethereum, while ZetaConnectorNonNative is for other connected EVMs. Requires ZETA_CONNECTOR_ADMIN_ADDRESS_EVM and other environment variables. Supports optional verification.

```shell
forge script scripts/deploy/deterministic/DeployZetaConnectorNative.s.sol \
  --private-key <PRIVATE_KEY> \
  --rpc-url <RPC_URL> \
  --verify \
  --etherscan-api-key <ETHERSCAN_API_KEY> \
  --chain-id 1 \
  --broadcast
```

```shell
forge script scripts/deploy/deterministic/DeployZetaConnectorNonNative.s.sol \
  --private-key <PRIVATE_KEY> \
  --rpc-url <RPC_URL> \
  --verify \
  --etherscan-api-key <ETHERSCAN_API_KEY> \
  --chain-id <CHAIN_ID> \
  --broadcast
```

--------------------------------

### Solidity: ZetaConnectorBase Constructor

Source: https://github.com/zeta-chain/protocol-contracts/blob/main/docs/index.md

Initializes the ZetaConnectorBase contract by requiring addresses for zetaToken, tssAddress, tssAddressUpdater, and pauserAddress. Only zetaToken is immutable.

```solidity
constructor(address zetaToken_, address tssAddress_, address tssAddressUpdater_, address pauserAddress_);
```

--------------------------------

### Initialize ZetaConnectorNative

Source: https://github.com/zeta-chain/protocol-contracts/blob/main/docs/index.md

Initializes the ZetaConnectorNative contract, which is responsible for handling native token transfers. It overrides the base initializer.

```solidity
function initialize(
    address gateway_,
    address zetaToken_,
    address tssAddress_,
    address admin_
)
    public
    override
    initializer;

```

--------------------------------

### IZetaNonEthNew Functions

Source: https://github.com/zeta-chain/protocol-contracts/blob/main/docs/index.md

Interface for a mintable/burnable version of IERC20, providing burnFrom and mint functionalities.

```APIDOC
## IZetaNonEthNew Functions

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. |
```

--------------------------------

### bootstrapChains

Source: https://github.com/zeta-chain/protocol-contracts/blob/main/docs/index.md

Bootstraps the registry with chain data. This function can only be called by an address with the REGISTRY_MANAGER_ROLE.

```APIDOC
## POST /bootstrapChains

### Description
Bootstrap the registry with chain data. This function can only be called by an address with the REGISTRY_MANAGER_ROLE.

### Method
POST

### Endpoint
/bootstrapChains

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **chains** (ChainInfoDTO[]) - Required - Array of chain data structures to bootstrap
- **metadataEntries** (ChainMetadataEntry[]) - Required - Array of chain metadata entries

### Request Example
```json
{
  "chains": [
    {
      "chainId": 1,
      "name": "Ethereum",
      "isZetaChain": false
    }
  ],
  "metadataEntries": [
    {
      "chainId": 1,
      " ZetaName": "ETH",
      "address": "0x..."
    }
  ]
}
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the operation was successful.

#### Response Example
```json
{
  "success": true
}
```
```

--------------------------------

### Simulate ERC20Custody Upgrade with Forge

Source: https://github.com/zeta-chain/protocol-contracts/blob/main/scripts/deploy/readme.md

Executes a Forge script designed to simulate an upgrade for the ERC20Custody contract within a local forked environment. This simulation allows for state verification before and after the upgrade. Ensure your local Anvil instance is running and accessible via the specified RPC URL.

```bash
forge script scripts/upgrade/SimulateERC20CustodyUpgrade.s.sol --rpc-url http://localhost:8545
```