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

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.


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.


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.


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:

mkdir -p src/
cd src/

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 | 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.

Was this page helpful?