@hashgraph/system-contracts-forking v0.1.2

Hedera Forking for System Contracts

This projects allows Smart Contract developers working on Hedera to use fork testing while using Hedera System Contracts. It does so by providing an emulation layer for the Hedera Token Service (more System Contracts to come) written in Solidity. Given it is written in Solidity, it can be executed in a forked network environment, such as Foundry or Hardhat.

You can use either our Foundry library or Hardhat plugin to enable HTS emulation in your project.

See Hedera Token Service Supported Methods for a list of methods currently implemented as part of this project.

!IMPORTANT The HTS emulation contract SHOULD BE ONLY used to ease development workflow when working with Hedera Tokens. The HTS emulation contract DOES NOT replicate Hedera Token Services fully. That is, behavior might differ when switching from local development to a real Hedera network. Always test your contracts against a real Hedera network before launching your contracts.

For detailed information on how this project works, see Internals.

!NOTE The FAQ provides common issues that this project solves.

Foundry library

We provide a Foundry library that enables fork testing when using HTS Tokens.

To see how this library works in details, see Foundry library in Internals.

Installation

First, install our library in your Foundry project

forge install hashgraph/hedera-forking

Set up

To use this library in your tests, you need to enable ffi. You can do so by adding the following lines to your .toml file

[profile.default]
ffi = true

Alternatively, you can add the --ffi flag to your execution script.

This is necessary because

• On Unix-like operating systems, the library relies on curl to make HTTP requests to the Hedera remote network. This allows the library to fetch token state from the remote network. Since curl is an external command, ffi must be enabled.
• On Windows, if PowerShell is available, the library uses the Invoke-WebRequest command to handle HTTP requests, which also requires ffi to be enabled.

!NOTE
The Foundry library assumes it is running on either a Windows system with PowerShell or a Unix-like operating system.

• On Unix-like systems, it uses curl, bash, tail, sed, and tr to make requests and parse responses.
• On Windows, it uses Invoke-WebRequest and Start-Process in PowerShell for a similar effect.

To activate HTS emulation in your tests, you need to add the following setup code in your test files. Import our wrapper function to deploy HTS emulation and enable cheat codes for it.

import {htsSetup} from "hedera-forking/contracts/htsSetup.sol";

and then invoke it in your test setup

    function setUp() public {
        htsSetup();
    }

Running your Tests

Now you can use Hedera Token Services and remote tokens as if they were deployed locally when fork testing. For example

// SPDX-License-Identifier: Apache-2.0
pragma solidity ^0.8.0;

import {Test} from "forge-std/Test.sol";
import {htsSetup} from "hedera-forking/contracts/htsSetup.sol";
import {IERC20} from "hedera-forking/contracts/IERC20.sol";

contract USDCExampleTest is Test {
    // https://hashscan.io/mainnet/token/0.0.456858
    address USDC_mainnet = 0x000000000000000000000000000000000006f89a;

    address private user1;

    function setUp() external {
        htsSetup();

        user1 = makeAddr("user1");
        deal(USDC_mainnet, user1, 1000 * 10e8);
    }

    function test_get_balance_of_existing_account() view external {
        // https://hashscan.io/mainnet/account/0.0.1528
        address usdcHolder = 0x00000000000000000000000000000000000005f8;
        // Balance retrieved from mainnet at block 72433403
        assertEq(IERC20(USDC_mainnet).balanceOf(usdcHolder), 28_525_752677);
    }

    function test_dealt_balance_of_local_account() view external {
        assertEq(IERC20(USDC_mainnet).balanceOf(user1), 1000 * 10e8);
    }
}

To run your tests, use the usual command

forge test --fork-url https://mainnet.hashio.io/api

You can also include a specific block number. For example, the test above is known to work at block 72433403

forge test --fork-url https://mainnet.hashio.io/api --fork-block-number 72433403

You can use all the tools and cheatcodes Foundry provides, e.g., console.log

// SPDX-License-Identifier: Apache-2.0
pragma solidity ^0.8.0;

import {Test, console} from "forge-std/Test.sol";
import {htsSetup} from "hedera-forking/contracts/htsSetup.sol";
import {IERC20} from "hedera-forking/contracts/IERC20.sol";

contract USDCConsoleExampleTest is Test {
    function setUp() external {
        htsSetup();
    }

    function test_using_console_log() view external {
        // https://hashscan.io/mainnet/token/0.0.456858
        address USDC_mainnet = 0x000000000000000000000000000000000006f89a;

        string memory name = IERC20(USDC_mainnet).name();
        string memory symbol = IERC20(USDC_mainnet).symbol();
        uint8 decimals = IERC20(USDC_mainnet).decimals();
        assertEq(name, "USD Coin");
        assertEq(symbol, "USDC");
        assertEq(decimals, 6);

        console.log("name: %s, symbol: %s, decimals: %d", name, symbol, decimals);
    }
}

Hardhat plugin

We provide a Hardhat plugin that enables fork testing when using HTS Tokens.

In addition, this plugin provides the following features

• Sets up Hardfork history for Hedera networks. This solves the issue No known hardfork for execution on historical block.
• Avoids Missing access list error. Hardhat throws this error when a blockNumber is provided in the forking configuration. The plugin solves this issue.

This plugin intercepts the calls made by Hardhat to fetch remote state, _i.e., eth_getCode and eth_getStorageAt, to provide emulation for HTS. It assigns the Hedera Token Service code to the 0x167 address. In your tests, you will be able to query Hedera Token data as if they were stored as regular Smart Contracts.

To see how this plugin works in details, see Hardhat plugin in Internals.

Installation

To use this plugin, install it via your package manager.

If you are using npm

npm install --save-dev @hashgraph/system-contracts-forking

or using yarn

yarn add --dev @hashgraph/system-contracts-forking

Set up

Next, add the following line to the top of your Hardhat config file, e.g., hardhat.config.js

require('@hashgraph/system-contracts-forking/plugin');

or if you are using TypeScript, include the following line into your hardhat.config.ts

import '@hashgraph/system-contracts-forking/plugin';

This will automatically create a worker thread to intercept calls to fetch remote state. You can then proceed with writing your tests, and the plugin will allow you to query Hedera token data seamlessly.

Configuration

By default, the plugin uses the Hedera Mirror Node based on the guessed chain ID from the currently forked network.

Two additional values needs to be set in order to activate the plugin.

• chainId. The call to eth_chainId of configuration parameter hardhat.forking.url needs to match the chainId configuration argument. Only chain IDs 295 (Mainnet), 296 (Testnet), and 297 (Previewnet) are supported.
• workerPort. Any free port to start the worker to intercept Hardhat calls to fetch remote state.

For example

    networks: {
        hardhat: {
            forking: {
                url: 'https://mainnet.hashio.io/api',
                // This allows Hardhat to enable JSON-RPC's response cache.
                // Forking from a block is not fully integrated yet into HTS emulation.
                blockNumber: 70531900,
                chainId: 295,
                workerPort: 1235,
            },
        },
    },

!NOTE These configuration settings cannot be set automatically by the Plugin. This is because the way Hardhat plugins are loaded by Hardhat. The main issue is "since Hardhat needs to be loadable via require call, configuration must be synchronous". See here and here for more details.

Creating a Worker so we can hook into eth_getCode and eth_getStorageAt to provide HTS emulation and querying the chainId of a remote network are asynchronous operations. That is why we need to shift the setting of chainId and workerPort to the user.

Running Your Tests

For example, to query USDC information on mainnet you can use the following test

const { expect } = require('chai');
const { ethers: { getContractAt } } = require('hardhat');

describe('USDC example -- informational', function () {
    it('should get name, symbol and decimals', async function () {
        // https://hashscan.io/mainnet/token/0.0.456858
        const usdc = await getContractAt('IERC20', '0x000000000000000000000000000000000006f89a');
        expect(await usdc['name']()).to.be.equal('USD Coin');
        expect(await usdc['symbol']()).to.be.equal('USDC');
        expect(await usdc['decimals']()).to.be.equal(6n);
    });
});

Then run your Hardhat tests as usual

npx hardhat

You can also query an existing account's balance. For example using the blockNumber as shown above in Configuration, you can query the USDC balance for an existing account.

const { expect } = require('chai');
const { ethers: { getContractAt } } = require('hardhat');

describe('USDC example -- balanceOf', function () {
    it('should get `balanceOf` account holder', async function () {
        // https://hashscan.io/mainnet/token/0.0.456858
        const usdc = await getContractAt('IERC20', '0x000000000000000000000000000000000006f89a');

        // https://hashscan.io/mainnet/account/0.0.6279
        const holderAddress = '0x0000000000000000000000000000000000001887';
        expect(await usdc['balanceOf'](holderAddress)).to.be.equal(31_166_366226);
    });
});

You can also perform modifications in the forked network. Let's see an example where we execute the transfer method from an existing account to a local Hardhat signer. It is usually paired with Fixtures, so that each test can start in a known state. Moreover, you can use the tools you are already familiar with, for example, hardhat_impersonateAccount.

const { expect } = require('chai');
const { ethers: { getSigner, getSigners, getContractAt }, network: { provider } } = require('hardhat');
const { loadFixture } = require('@nomicfoundation/hardhat-toolbox/network-helpers');

describe('USDC example -- transfer', function () {
    async function id() {
        return [(await getSigners())[0]];
    }

    it("should `tranfer` tokens from account holder to one of Hardhat' signers", async function () {
        const [receiver] = await loadFixture(id);

        // https://hashscan.io/mainnet/account/0.0.6279
        const holderAddress = '0x0000000000000000000000000000000000001887';
        await provider.request({
            method: 'hardhat_impersonateAccount',
            params: [holderAddress],
        });
        const holder = await getSigner(holderAddress);

        // https://hashscan.io/mainnet/token/0.0.456858
        const usdc = await getContractAt('IERC20', '0x000000000000000000000000000000000006f89a');

        expect(await usdc['balanceOf'](receiver.address)).to.be.equal(0n);

        await usdc.connect(holder)['transfer'](receiver, 10_000_000n);

        expect(await usdc['balanceOf'](receiver.address)).to.be.equal(10_000_000n);
    });
});

Hedera Token Service Supported Methods

Given your HTS token address, you can invoke these functions whether the token is either fungible or non-fungible.

Fungible Tokens

The following methods and events are applicable to Fungible Tokens.

ERC20 Interface

Association Methods Interface

Non-Fungible Tokens

The following methods and events are applicable to Non-Fungible Tokens.

Association Methods Interface

Hedera Token Service (located at address 0x167)

The following methods can be invoked on the Hedera Token Service contract located at address 0x167.