From 07ae254f1afc2a451bb6d86f35ca4601133b9c17 Mon Sep 17 00:00:00 2001 From: Lucas Bertrand Date: Thu, 18 Jul 2024 13:58:17 +0200 Subject: [PATCH 1/3] chore: add gitattributes to mark generated directories (#237) --- .gitattributes | 3 +++ 1 file changed, 3 insertions(+) create mode 100644 .gitattributes diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 00000000..23732538 --- /dev/null +++ b/.gitattributes @@ -0,0 +1,3 @@ +# Mark all files in the directories as generated +pkg/* linguist-generated +typechain-types/* linguist-generated \ No newline at end of file From 8f89b49bb936010d7bce8e8b2014d6031c152ae2 Mon Sep 17 00:00:00 2001 From: Lucas Bertrand Date: Thu, 18 Jul 2024 14:10:41 +0200 Subject: [PATCH 2/3] docs: initialize a guide to use the V2 contracts in localnet (#235) Co-authored-by: skosito --- readme.md | 6 +++ v2_localnet.md | 139 +++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 145 insertions(+) create mode 100644 v2_localnet.md diff --git a/readme.md b/readme.md index 25c42190..e889516a 100644 --- a/readme.md +++ b/readme.md @@ -1,3 +1,9 @@ +### ⚠️ 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](/v2_localnet.md). + # ZetaChain Protocol Contracts This repository contains ZetaChain protocol contracts: Solidity source code, diff --git a/v2_localnet.md b/v2_localnet.md new file mode 100644 index 00000000..4b162346 --- /dev/null +++ b/v2_localnet.md @@ -0,0 +1,139 @@ +# V2 Contracts - Local Development Environment + +Important Notice: The new architecture (V2) is currently in active development. While the high-level interface presented in this document is expected to remain stable, some aspects of the architecture may change. + +## Introduction + +The new architecture aims to streamline the developer experience for building Universal Apps. Developers will primarily interact with two contracts: GatewayZEVM and GatewayEVM. + +* `GatewayEVM`: Deployed on each connected chain to interact with ZetaChain. +* `GatewayZEVM`: Deployed on ZetaChain to interact with connected chains. + +V2 contracts source code is currently located in [prototypes](/contracts/prototypes/) + +## Contract Interfaces + +The interface of the gateway contracts is centered around the deposit, withdraw, and call terminology: + +* Deposit: Transfer of assets from a connected chain to ZetaChain. +* Withdraw: Transfer of assets from ZetaChain to a connected chain. +* Call: Smart contract call involved in cross-chain transactions. + + +In consequence, the interface is as follow: +* `GatewayEVM`: `deposit`, `depositAndCall`, and `call` +* `GatewayZEVM`: `withdraw`, `withdrawAndCall`, and `call` + +The motivation behind this interface is intuitiveness and simplicity. We support different asset types by using function overloading. + +### `GatewayEVM` + +* Deposit of native tokens to addresses on ZetaChain: + +```solidity +function deposit(address receiver) payable +``` + +* Deposit of ERC-20 tokens to addresses on ZetaChain: + +```solidity +function deposit(address receiver, uint256 amount, address asset) +``` + +* Deposit of native tokens and smart contract call on ZetaChain: + +```solidity +function depositAndCall(address receiver, bytes calldata payload) payable +``` + +* Deposit of ERC-20 tokens and smart contract call on ZetaChain: + +```solidity +depositAndCall(address receiver, uint256 amount, address asset, bytes calldata payload) +``` + +* Simple Universal App contract call: + +```solidity +function call(address receiver, bytes calldata payload) +``` + +### `GatewayZEVM` + +* Withdraw of ZRC-20 tokens to its native connected chain: + +```solidity +function withdraw(bytes memory receiver, uint256 amount, address zrc20) +``` + +* Withdraw of ZRC-20 tokens and smart contract call on connected chain: + +```solidity +function withdrawAndCall(bytes memory receiver, uint256 amount, address zrc20, bytes calldata message) +``` + +* Simple call to a contract on a connected chain: + +```solidity +function call(bytes memory receiver, bytes calldata message) external +``` + +## Experimenting with the New Architecture + +To experiment with the new architecture, you can deploy a local network using Hardhat and test the gateways using the following commands: + +Clone the repository +``` +git clone https://github.com/zeta-chain/protocol-contracts.git +cd protocol-contracts +``` + +Start the local environment network +Note: `--hide="NODE"` is used to prevent verbose logging +``` +yarn +yarn localnet --hide="NODE" +``` + +The `localnet` command launches two processes: + +- A local Ethereum network (using Hardhat) with the two gateway contracts deployed +- A background worker that relay messages between the two gateway contracts. It simulates the cross-chain message relaying that would normally happen between live networks with the [observers/signers](https://www.zetachain.com/docs/developers/architecture/observers/) mechanism. This allows to simulate a cross-chain environment on a single local chain. + +Running the command will deploy the two gateway contracts: + +``` +[WORKER] GatewayEVM: 0xe7f1725E7734CE288F8367e1Bb143E90bb3F0512 +[WORKER] GatewayZEVM: 0x0165878A594ca255338adfa4d48449f69242Eb8F +``` + +The developers can develop application using these addresses, the messages will automatically be relayed by the worker. + +The local environment uses Hardhat localnet. Therefore, the default Hardhat localnet accounts can be used to interact with the network. + +``` +Account #0: 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266 (10000 ETH) +Private Key: 0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80 + +Account #1: 0x70997970C51812dc3A010C7d01b50e0d17dc79C8 (10000 ETH) +Private Key: 0x59c6995e998f97a5a0044966f0945389dc9e86dae88c7a8412f4603b6b78690d + +Account #2: 0x3C44CdDdB6a900fa2b585dd299e03d12FA4293BC (10000 ETH) +Private Key: 0x5de4111afa1a4b94908f83103eb1f1706367c2e68ca870fc3fb9a804cdab365a +``` + +### Examples + +The example contracts demonstrate how the V2 interface can be leveraged to build Universal Apps. + +* [TestZContract](/contracts/prototypes/zevm/TestZContract.sol): ZetaChain contract (Universal App) that can be called from a connected chains +* [SenderZEVM](/contracts/prototypes/zevm/SenderZEVM.sol): ZetaChain contract calling a smart contract on a connected chains +* [ReceiverEVM](/contracts/prototypes/evm/ReceiverEVM.sol): contract on connected chain that can be called from ZetaChain + +The following commands can be used to test interactions between these contracts: +``` +npx hardhat zevm-call --network localhost +npx hardhat zevm-withdraw-and-call --network localhost +npx hardhat evm-call --network localhost +npx hardhat evm-deposit-and-call --network localhost +``` \ No newline at end of file From 00b18ad1907db2e070a9862753049edcfef07f34 Mon Sep 17 00:00:00 2001 From: skosito Date: Fri, 19 Jul 2024 09:51:26 +0100 Subject: [PATCH 3/3] fix: publish workflow missing foundry (#241) --- .github/workflows/publish-npm.yaml | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/.github/workflows/publish-npm.yaml b/.github/workflows/publish-npm.yaml index 677fceec..91cedb1b 100644 --- a/.github/workflows/publish-npm.yaml +++ b/.github/workflows/publish-npm.yaml @@ -11,6 +11,8 @@ jobs: steps: - name: Checkout Repository uses: actions/checkout@v3 + with: + submodules: recursive - name: Setup Node.js uses: actions/setup-node@v3 @@ -18,6 +20,9 @@ jobs: node-version: "18" registry-url: "https://registry.npmjs.org" + - name: Install Foundry + uses: foundry-rs/foundry-toolchain@v1 + - name: Install Dependencies run: yarn install