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
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.
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
$GOPATH environment variable properly for Go to look for Go Workspaces. Please read
this for details. You can verify by running
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:
Download the following prerequisites into your
- 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:
mkdir -p src/github.com/ava-labs
Clone the repository:
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
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?