Adding a New Precompile Interface

intermediate advanced 20 min

Learn how to define a new Solidity interface for a custom precompiled contract, compile it, and generate the ABI artifact needed for the Go implementation.

What You Will Learn

✓How to structure directories for a new precompile.
✓How to write a Solidity interface for a precompile.
✓How to use the compilation script to generate an `abi.json` file.
✓How the generated ABI is used in the Go module.

Prerequisites

A local clone of the Maroo repository.
Basic understanding of Solidity interfaces.
Familiarity with the concept of precompiled contracts.

Tools Needed

Python 3.8+Node.js 18+Yarn

In Maroo, precompiled contracts are implemented in Go but exposed to the EVM through a standard Solidity interface. This allows smart contracts to interact with core blockchain logic seamlessly. This tutorial will guide you through the process of creating a new interface for a hypothetical 'Oracle' precompile.

1. Set Up the Directory Structure

First, we need to create a directory for our new precompile within the precompiles/ folder. This co-locates the interface with its future Go implementation.

terminal bash

mkdir -p precompiles/oracle

2. Define the Solidity Interface

Now, create a new Solidity file named IOracle.sol inside the precompiles/oracle/ directory. Define an interface with a function to get a price and an event to log the update. This interface defines the exact function signatures the EVM will use.

precompiles/oracle/IOracle.sol solidity

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

interface IOracle {
    /**
     * @dev Emitted when a price is updated.
     */
    event PriceUpdated(string indexed symbol, uint256 price);

    /**
     * @dev Returns the latest price for a given symbol.
     */
    function getPrice(string calldata symbol) external view returns (uint256);
}

3. Install Hardhat Dependencies

Before running the compilation script, you need to install the dependencies for the central Hardhat project. Navigate to the contracts directory and run yarn.

terminal bash

cd contracts
yarn install

Tip: You only need to do this once, or when dependencies in `contracts/package.json` change.

4. Compile the Interface

Now, run the compilation script to process our new interface. The script will find IOracle.sol, copy it to the Hardhat project, compile it, and place the resulting artifact back into our precompiles/oracle/ directory.

terminal bash

# Navigate back to the script's directory from 'contracts/'
cd ../scripts/compile_smart_contracts

python3 compile_smart_contracts.py --compile

5. Verify the Artifact

After the script finishes, you will find a new abi.json file in precompiles/oracle/. This file contains the ABI for your IOracle interface. The Go implementation of the oracle precompile will load this file to understand how to parse function calls and emit events correctly.

terminal bash

ls -l precompiles/oracle

output text

total 8
-rw-r--r--  1 user  staff  1234 Date Time abi.json
-rw-r--r--  1 user  staff   321 Date Time IOracle.sol

Conclusion

You have successfully defined a Solidity interface for a new precompile and used the Maroo build system to generate the necessary ABI artifact. This abi.json is the critical bridge that connects your Go logic to the EVM, enabling powerful and efficient custom extensions to the Maroo network.

What You Will Learn

Prerequisites

Tools Needed

1. Set Up the Directory Structure

2. Define the Solidity Interface

3. Install Hardhat Dependencies

4. Compile the Interface

5. Verify the Artifact

Conclusion

Related