add hello world example

Author: ceyonur

.github/workflows/sync.yml

@@ -0,0 +1,24 @@
+name: Sync
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  sync-branches:
+    runs-on: ubuntu-latest
+    name: Syncing branches
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v2
+      - name: Set up Node
+        uses: actions/setup-node@v1
+        with:
+          node-version: 12
+      - name: Opening pull request
+        id: pull
+        uses: tretuna/[email protected]
+        with:
+          GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}
+          FROM_BRANCH: "main"
+          TO_BRANCH: "develop"

README.md

@@ -35,10 +35,111 @@ To get a comprehensive introduction to Precompile-EVM, take the Avalanche Academ
 
 There is an example branch [hello-world-example](https://github.com/ava-labs/precompile-evm/tree/hello-world-example) in this repository. You can check the example branch to see how to register precompiles and test them.
 
+### Clone the Repo
+
+```zsh
+git clone https://github.com/ava-labs/precompile-evm.git
+cd precompile-evm/ # change directory to the precompile-evm/ directory
+```
+
+### Checkout the `hello-world-example` Branch
+
+```zsh
+git checkout hello-world-example
+
+branch 'hello-world-example' set up to track 'origin/hello-world-example'.
+Switched to a new branch 'hello-world-example'
+```
+
+### Install NodeJS Dependencies
+
+First you have to `cd contracts/` and run `npm install` to get the dependencies.
+
+```zsh
+cd contracts/ # change directory to the contracts/ directory
+npm install
+```
+
+### Create a New Contract
+
+`hello-world-example` branch has already a precompile contract called `HelloWorld.sol`. All necessary files were already created for you. You can check existing files and see how a fully implemented precompile should look like. If you'd like to redo steps to create a new precompile contract, you can follow the steps below.
+
+Copy the existing `IHelloWorld.sol` interface to a new file called `IHolaMundo.sol`.
+
+```zsh
+cd .. # change directory back to the root of the repo
+cp contracts/contracts/interfaces/IHelloWorld.sol contracts/contracts/interfaces/IHolaMundo.sol
+```
+
+### Install `solc` and Confirm Dependency Version
+
+Install the `solc` dependency.
+
+```zsh
+brew install solidity
+```
+
+Confirm `solc` is >=0.8.8.
+
+```zsh
+solc --version
+
+solc, the solidity compiler commandline interface
+Version: 0.8.17+commit.8df45f5f.Darwin.appleclang
+```
+
+### Generate an `.abi`
+
+Now generate a `.abi` from a `.sol` using `solc`.
+
+Passing in the following flags
+
+- `--abi`
+  - ABI specification of the contracts.
+- `--base-path path`
+  - Use the given path as the root of the source tree instead of the root of the filesystem.
+- `--include-path path`
+  - Make an additional source directory available to the default import callback. Use this option if you want to import contracts whose location is not fixed in relation to your main source tree, e.g. third-party libraries installed using a package manager. Can be used multiple times. Can only be used if base path has a non-empty value.
+- `--output-dir path`
+  - If given, creates one file per output component and contract/file at the specified directory.
+- `--overwrite`
+  - Overwrite existing files (used together with `--output-dir`).
+
+```zsh
+cd contracts/ # change directory to the contracts/ directory
+solc --abi contracts/interfaces/IHolaMundo.sol --output-dir abis --base-path . --include-path ./node_modules --overwrite
+
+Compiler run successful. Artifact(s) can be found in directory "abis".
+```
+
 ### Generate Precompile Files
 
 First, you need to create your precompile contract interface in the `contracts` directory and build the ABI. Then you can generate your precompile files with `./scripts/generate_precompile.sh --abi {abiPath} --out {outPath}`. This script installs the `precompilegen` tool from Subnet-EVM and runs it to generate your precompile.
 
+```zsh
+cd .. # change directory back to the root directory of the repo
+./scripts/generate_precompile.sh --abi contracts/abis/IHolaMundo.abi --out holamundo/
+
+Using branch: hello-world-example
+installing precompilegen from Subnet-EVM v0.5.2
+generating precompile with Subnet-EVM v0.5.2
+Precompile files generated successfully at:  holamundo/
+```
+
+Confirm that the new `holamundo/` directory has the appropriate files.
+
+```zsh
+ls -lh helloworld
+
+-rw-r--r--  1 user group 2.3K Jul  5 13:26 README.md
+-rw-r--r--  1 user group 2.3K Jul  5 13:26 config.go
+-rw-r--r--  1 user group 2.8K Jul  5 13:26 config_test.go
+-rw-r--r--  1 user group 963B Jul  5 13:26 contract.abi
+-rw-r--r--  1 user group 8.1K Jul  5 13:26 contract.go
+-rw-r--r--  1 user group 8.3K Jul  5 13:26 contract_test.go
+-rw-r--r--  1 user group 2.7K Jul  5 13:26 module.go
+```
+
 ### Register Precompile
 
 In `plugin/main.go` Subnet-EVM is already imported and ready to be Run from the main package. All you need to do is explicitly register your precompiles to Subnet-EVM in `plugin/main.go` and build it together with Subnet-EVM. Precompiles generated by `precompilegen` tool have a self-registering mechanism in their `module.go/init()` function. All you need to do is to force-import your precompile packprecompile package in `plugin/main.go`.

contracts/README.md

@@ -111,15 +111,6 @@ Subnet-EVM must activate any precompiles used in the test in the genesis:
 {
   "config": {
     "chainId": 43214,
-    "homesteadBlock": 0,
-    "eip150Block": 0,
-    "eip155Block": 0,
-    "eip158Block": 0,
-    "byzantiumBlock": 0,
-    "constantinopleBlock": 0,
-    "petersburgBlock": 0,
-    "istanbulBlock": 0,
-    "muirGlacierBlock": 0,
     "feeConfig": {
       "gasLimit": 8000000,
       "minBaseFee": 25000000000,

contracts/contracts/.gitkeep

@@ -0,0 +1,19 @@
+//SPDX-License-Identifier: MIT
+pragma solidity ^0.8.0;
+
+import "./interfaces/IHelloWorld.sol";
+
+address constant HELLO_WORLD_ADDRESS = 0x0300000000000000000000000000000000000000;
+
+// ExampleHelloWorld shows how the HelloWorld precompile can be used in a smart contract.
+contract ExampleHelloWorld {
+  IHelloWorld helloWorld = IHelloWorld(HELLO_WORLD_ADDRESS);
+
+  function sayHello() public view returns (string memory) {
+    return helloWorld.sayHello();
+  }
+
+  function setGreeting(string calldata greeting) public {
+    helloWorld.setGreeting(greeting);
+  }
+}

contracts/contracts/ExampleHelloWorld.sol

@@ -0,0 +1,13 @@
+// SPDX-License-Identifier: MIT
+
+pragma solidity >=0.8.0;
+import "@avalabs/subnet-evm-contracts/contracts/interfaces/IAllowList.sol";
+
+interface IHelloWorld is IAllowList {
+  event GreetingChanged(address indexed sender, string oldGreeting, string newGreeting);
+  // sayHello returns the stored greeting string
+  function sayHello() external view returns (string calldata result);
+
+  // setGreeting  stores the greeting string
+  function setGreeting(string calldata response) external;
+}

contracts/contracts/interfaces/.gitkeep

@@ -0,0 +1,42 @@
+//SPDX-License-Identifier: MIT
+pragma solidity ^0.8.0;
+
+import "../ExampleHelloWorld.sol";
+import "../interfaces/IHelloWorld.sol";
+import "@avalabs/subnet-evm-contracts/contracts/test/AllowListTest.sol";
+
+contract ExampleHelloWorldTest is AllowListTest {
+  IHelloWorld helloWorld = IHelloWorld(HELLO_WORLD_ADDRESS);
+
+  function step_getDefaultHelloWorld() public {
+    ExampleHelloWorld example = new ExampleHelloWorld();
+    address exampleAddress = address(example);
+
+    assertRole(helloWorld.readAllowList(exampleAddress), AllowList.Role.None);
+    assertEq(example.sayHello(), "Hello World!");
+  }
+
+  function step_doesNotSetGreetingBeforeEnabled() public {
+    ExampleHelloWorld example = new ExampleHelloWorld();
+    address exampleAddress = address(example);
+
+    assertRole(helloWorld.readAllowList(exampleAddress), AllowList.Role.None);
+
+    try example.setGreeting("testing") {
+      assertTrue(false, "setGreeting should fail");
+    } catch {} // TODO should match on an error to make sure that this is failing in the way that's expected
+  }
+
+  function step_setAndGetGreeting() public {
+    ExampleHelloWorld example = new ExampleHelloWorld();
+    address exampleAddress = address(example);
+
+    assertRole(helloWorld.readAllowList(exampleAddress), AllowList.Role.None);
+    helloWorld.setEnabled(exampleAddress);
+    assertRole(helloWorld.readAllowList(exampleAddress), AllowList.Role.Enabled);
+
+    string memory greeting = "testgreeting";
+    example.setGreeting(greeting);
+    assertEq(example.sayHello(), greeting);
+  }
+}