Skip to main content

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
caution

Stateful precompiles are alpha software. Build at your own risk.

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:

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.

info

See here for instructions on setting the GOPATH based on system configurations.

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:

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

Clone the repository:

git clone [email protected]:ava-labs/subnet-evm.git

Then run the following commands:

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

Complete Code​

You can inspect example pull request for the complete code.

Subnet-EVM Hello World Pull Request

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

Was this page helpful?