Background and Requirements

This is a brief overview of what this tutorial will cover.

• Write a Solidity interface
• Generate the precompile template
• Implement the precompile functions in Golang
• Write and run tests

In this tutorial, we used a branch based on Subnet-EVM version v0.5.2. You can find the branch here. The code in this branch is the same as Subnet-EVM except for the precompile/contracts/helloworld directory. The directory contains the code for the HelloWorld precompile. We will be using this precompile as an example to learn how to write a stateful precompile. The code in this branch can become outdated. You should always use the latest version of Subnet-EVM when you develop your own precompile.

Precompile-EVM

Subnet-EVM precompiles can be registered from an external repo. This allows developer to build their precompiles without maintaining a fork of Subnet-EVM. The precompiles are then registered in the Subnet-EVM at build time.

The difference between using Subnet-EVM and Precompile-EVM is that with Subnet-EVM you can change EVM internals to interact with your precompiles. Such as changing fee structure, adding new opcodes, changing how to build a block, etc. With Precompile-EVM you can only add new stateful precompiles that can interact with the StateDB. Precompiles built with Precompile-EVM are still very powerful because it can directly access to the state and modify it.

There is a template repo for how to build a precompile with this way called Precompile-EVM. Both Subnet-EVM and Precompile-EVM share similar directory structures and common codes.

You can reference the Precompile-EVM PR that adds Hello World precompile here.

Requirements

This tutorial assumes familiarity with Golang and JavaScript.

Additionally, users should be deeply familiar with the EVM in order to understand its invariants since adding a Stateful Precompile modifies the EVM itself.

Here are some recommended resources to learn the ins and outs of the EVM:

• The Ethereum Virtual Machine
• Precompiles in Solidity
• Deconstructing a Smart Contract
• Layout of State Variables in Storage
• Layout in Memory
• Layout of Call Data
• Contract ABI Specification
• Customizing the EVM with Stateful Precompiles

Please install the following before getting started.

First, install the latest version of Go. Follow the instructions here. You can verify by running go version.

Set the $GOPATH environment variable properly for Go to look for Go Workspaces. Please read this for details. You can verify by running echo $GOPATH.

As a few things will be installed into $GOPATH/bin, please make sure that $GOPATH/bin is in your $PATH, otherwise, you may get an error running the commands below. To do that, run the command: export PATH=$PATH:$GOROOT/bin:$GOPATH/bin

Download the following prerequisites into your $GOPATH:

• Git Clone the repository (Subnet-EVM or Precompile-EVM)
• Git Clone AvalancheGo repository
• Install Avalanche Network Runner
• Install solc
• Install Node.js and NPM For easy copy paste, use the below commands:

cd $GOPATH
mkdir -p src/github.com/ava-labs
cd src/github.com/ava-labs

Clone the repository:

git clone git@github.com:ava-labs/subnet-evm.git

git clone git@github.com:ava-labs/avalanchego.git
curl -sSfL https://raw.githubusercontent.com/ava-labs/avalanche-network-runner/main/scripts/install.sh | sh -s
npm install -g solc

Complete Code

You can inspect example pull request for the complete code.

For a full-fledged example, you can also check out the Reward Manager Precompile.