github.com/MetalBlockchain/subnet-evm@v0.4.9/contract-examples/README.md (about)

     1  # Subnet EVM Contracts
     2  
     3  CONTRACTS HERE ARE [ALPHA SOFTWARE](https://en.wikipedia.org/wiki/Software_release_life_cycle#Alpha) AND ARE NOT AUDITED. USE AT YOUR OWN RISK!
     4  
     5  ## Introduction
     6  
     7  Metal is an open-source platform for launching decentralized applications and enterprise blockchain deployments in one interoperable, highly scalable ecosystem. Metal gives you complete control on both the network and application layers—helping you build anything you can imagine.
     8  
     9  The Metal Network is composed of many subnets and chains. Chains in subnets run with customizable virtual machines. One of these virtual machines is Subnet EVM. The Subnet EVM's API is almost identical to an Ethereum node's API. Subnet EVM brings its own features like minting native tokens via contracts, restrincting contract deployer etc. These features are presented with `Stateful Precompile Contracts`. These contracts are precompiled and deployed when they're activated.
    10  
    11  The goal of this guide is to lay out best practices regarding writing, testing and deployment of smart contracts to Metal's Subnet EVM. We'll be building smart contracts with development environment [Hardhat](https://hardhat.org).
    12  
    13  ## Prerequisites
    14  
    15  ### NodeJS and Yarn
    16  
    17  First, install the LTS (long-term support) version of [nodejs](https://nodejs.org/en). This is `16.2.0` at the time of writing. NodeJS bundles `npm`.
    18  
    19  Next, install [yarn](https://yarnpkg.com):
    20  
    21  ```zsh
    22  npm install -g yarn
    23  ```
    24  
    25  ### Solidity and Metal
    26  
    27  It is also helpful to have a basic understanding of [Solidity](https://docs.soliditylang.org) and [Metal](https://docs.metalblockchain.org).
    28  
    29  ## Dependencies
    30  
    31  Clone the repo and install the necessary packages via `yarn`.
    32  
    33  ```zsh
    34  $ git clone https://github.com/MetalBlockchain/subnet-evm.git
    35  $ cd contract-examples
    36  $ yarn
    37  ```
    38  
    39  ## Write Contracts
    40  
    41  `AllowList.sol` is the base contract which provided AllowList precompile capabilities to inheriting contracts.
    42  
    43  `ERC20NativeMinter.sol` is based on [Open Zeppelin](https://openzeppelin.com) [ERC20](https://eips.ethereum.org/EIPS/eip-20) contract powered by native minting capabilities of Subnet EVM. ERC20 is a popular smart contract interface. It uses `INativeMinter` interface to interact with `NativeMinter` precompile.
    44  
    45  `ExampleDeployerList` shows how `ContractDeployerAllowList` precompile can be used in a smart contract. It uses `IAllowList` to interact with `ContractDeployerAllowList` precompile. When the precompile is activated only those allowed can deploy contracts.
    46  
    47  `ExampleFeeManager` shows how a contract can change fee configuration with the `FeeConfigManager` precompile.
    48  
    49  All of these `NativeMinter`, `FeeManager` and `AllowList` contracts should be enabled by a chain config in genesis or as an upgrade. See the example genesis under [Tests](#tests) section.
    50  
    51  For more information about precompiles see [subnet-evm precompiles](https://github.com/ava-labs/subnet-evm#precompiles).
    52  
    53  ## Hardhat Config
    54  
    55  Hardhat uses `hardhat.config.js` as the configuration file. You can define tasks, networks, compilers and more in that file. For more information see [here](https://hardhat.org/config/).
    56  
    57  In Subnet-EVM, we provide a pre-configured file [hardhat.config.ts](https://github.com/ava-labs/avalanche-smart-contract-quickstart/blob/main/hardhat.config.ts).
    58  
    59  The HardHat config file includes a single network configuration: `local`. `local` defaults to using the following values for the RPC URL and the Chain ID:
    60  
    61  ```
    62  var local_rpc_uri = process.env.RPC_URI || "http://127.0.0.1:9650/ext/bc/C/rpc"
    63  var local_chain_id = process.env.CHAIN_ID || 99999
    64  ```
    65  
    66  You can use this network configuration by providing the environment variables and specifying the `--network` flag, as Subnet-EVM does in its testing suite:
    67  
    68  ```bash
    69  RPC_URI=http://127.0.0.1:9650/ext/bc/28N1Tv5CZziQ3FKCaXmo8xtxoFtuoVA6NvZykAT5MtGjF4JkGs/rpc CHAIN_ID=77777 npx hardhat test --network local
    70  ```
    71  
    72  Alternatively, you can copy and paste the `local` network configuration to create a new network configuration for your own local testing. For example, you can copy and paste the `local` network configuration to create your own network and fill in the required details:
    73  
    74  ```json
    75  {
    76    networks: {
    77      mynetwork: {
    78        url: "http://127.0.0.1:9650/ext/bc/28N1Tv5CZziQ3FKCaXmo8xtxoFtuoVA6NvZykAT5MtGjF4JkGs/rpc",
    79        chainId: 33333,
    80        accounts: [
    81          "0x56289e99c94b6912bfc12adc093c9b51124f0dc54ac7a766b2bc5ccf558d8027",
    82          "0x7b4198529994b0dc604278c99d153cfd069d594753d471171a1d102a10438e07",
    83          "0x15614556be13730e9e8d6eacc1603143e7b96987429df8726384c2ec4502ef6e",
    84          "0x31b571bf6894a248831ff937bb49f7754509fe93bbd2517c9c73c4144c0e97dc",
    85          "0x6934bef917e01692b789da754a0eae31a8536eb465e7bff752ea291dad88c675",
    86          "0xe700bdbdbc279b808b1ec45f8c2370e4616d3a02c336e68d85d4668e08f53cff",
    87          "0xbbc2865b76ba28016bc2255c7504d000e046ae01934b04c694592a6276988630",
    88          "0xcdbfd34f687ced8c6968854f8a99ae47712c4f4183b78dcc4a903d1bfe8cbf60",
    89          "0x86f78c5416151fe3546dece84fda4b4b1e36089f2dbc48496faf3a950f16157c",
    90          "0x750839e9dbbd2a0910efe40f50b2f3b2f2f59f5580bb4b83bd8c1201cf9a010a"
    91        ],
    92        pollingInterval: "1s"
    93      },
    94    }
    95  }
    96  ```
    97  
    98  By creating your own network configuration in the HardHat config, you can run HardHat commands directly on your subnet:
    99  
   100  ```bash
   101  npx hardhat accounts --network mynetwork
   102  ```
   103  
   104  ## Hardhat Tasks
   105  
   106  You can define custom hardhat tasks in [tasks.ts](https://github.com/ava-labs/avalanche-smart-contract-quickstart/blob/main/tasks.ts). Tasks contain helpers for precompiles `allowList` and `minter`. Precompiles have their own contract already-deployed when they're activated. So these can be called without deploying any intermediate contract. See `npx hardhat --help` for more information about available tasks.
   107  
   108  ## Tests
   109  
   110  Tests are written for a local network which runs a Subnet-EVM Blockchain.
   111  
   112  E.g `RPC_URI=http://127.0.0.1:9650/ext/bc/28N1Tv5CZziQ3FKCaXmo8xtxoFtuoVA6NvZykAT5MtGjF4JkGs/rpc CHAIN_ID=77777 npx hardhat test --network local`.
   113  
   114  Subnet-EVM must activate any precompiles used in the test in the genesis:
   115  
   116  ```json
   117  {
   118    "config": {
   119      "chainId": 43214,
   120      "homesteadBlock": 0,
   121      "eip150Block": 0,
   122      "eip150Hash": "0x2086799aeebeae135c246c65021c82b4e15a2c451340993aacfd2751886514f0",
   123      "eip155Block": 0,
   124      "eip158Block": 0,
   125      "byzantiumBlock": 0,
   126      "constantinopleBlock": 0,
   127      "petersburgBlock": 0,
   128      "istanbulBlock": 0,
   129      "muirGlacierBlock": 0,
   130      "subnetEVMTimestamp": 0,
   131      "feeConfig": {
   132        "gasLimit": 8000000,
   133        "minBaseFee": 25000000000,
   134        "targetGas": 15000000,
   135        "baseFeeChangeDenominator": 36,
   136        "minBlockGasCost": 0,
   137        "maxBlockGasCost": 1000000,
   138        "targetBlockRate": 2,
   139        "blockGasCostStep": 200000
   140      },
   141      "contractDeployerAllowListConfig": {
   142        "blockTimestamp": 0,
   143        "adminAddresses": ["0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC"]
   144      },
   145      "contractNativeMinterConfig": {
   146        "blockTimestamp": 0,
   147        "adminAddresses": ["0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC"]
   148      },
   149      "allowFeeRecipients": false
   150    },
   151    "alloc": {
   152      "8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC": {
   153        "balance": "0x295BE96E64066972000000"
   154      }
   155    },
   156    "nonce": "0x0",
   157    "timestamp": "0x0",
   158    "extraData": "0x00",
   159    "gasLimit": "0x7A1200",
   160    "difficulty": "0x0",
   161    "mixHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
   162    "coinbase": "0x0000000000000000000000000000000000000000",
   163    "number": "0x0",
   164    "gasUsed": "0x0",
   165    "parentHash": "0x0000000000000000000000000000000000000000000000000000000000000000"
   166  }
   167  ```