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.6.0 (AvalancheGo v1.11.0, RPCChainVM protocol 33). This branch is in the archived ava-labs/subnet-evm repository. Subnet-EVM is now in the AvalancheGo repository, in the graft/subnet-evm directory, and some APIs in this tutorial changed after v0.6.0. 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.

The Precompile-EVM template repository is archived and deprecated. Its last release builds against Subnet-EVM v0.8.0 (RPCChainVM protocol 44). AvalancheGo v1.15.0 and v1.15.1 use protocol 46, so a Precompile-EVM binary does not run on a current node. Build your precompile in the Subnet-EVM code of the AvalancheGo repository (graft/subnet-evm).

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 AvalancheGo repository. Subnet-EVM is in its graft/subnet-evm directory.
• Install Avalanche Network Runner. The deployment step of this tutorial uses it. Its last release is v1.8.3 (2024-09-10). AvalancheGo now runs local test networks with tmpnet.
• 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 [email protected]: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
cd avalanchego/graft/subnet-evm

Complete Code

You can inspect example pull request for the complete code.

Subnet-EVM Hello World branch (archived repository, Subnet-EVM v0.6.0)

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