Vulcan

Development framework for Foundry projects, with a focus on developer experience and readability.

Built on top of forge-std

Initially, Vulcan will provide functionality similar to what is already included in forge's VM and forge-std.

Over time, Vulcan will grow to include more functionality and utilities, eventually becoming a feature-rich development framework.

Why Vulcan?

Our goal is to provide:

Better naming for VM functionality (no more prank, roll, warp, ...)
A testing framework with better readability and a familiar syntax
Improved ergonomics
Huff language support out of the box

Vulcan test example:

import { Test, expect, commands, Command, CommandResult, println } from "vulcan/test.sol";

contract TestSomething is Test {

    function testSomething() external {
        // Format strings with rust-like syntax
        println("Hello {s}", abi.encode("world!")); // Hello world!

        // Format numbers as decimals
        println("Balance: {u:d18}", abi.encode(1e17)); // Balance: 0.1

        // Nice external command API!
        Command memory ping = commands.create("ping").args(["-c", "1"]);
        CommandResult pingResult = ping.arg("etherscan.io").run();

        // Rust-like results
        bytes memory pingOutput = pingResult.expect("Ping command failed").stdout;

        println("Ping result: {s}", abi.encode(pingOutput));

        // Expect style assertions!
        expect(pingResult.isError()).toBeFalse();
        expect(pingResult.isOk()).toBeTrue();

        // And much more!
    }
}

Planned Features

Mocking framework
Deployment management framework

At this stage we are looking for all kinds of feedback, as the general direction of the project is not fully defined yet. If you have any ideas to improve naming, ergonomics, or anything else, please open an issue or a PR.

Installation

In an existing Foundry project, use forge install:

$ forge install nomoixyz/vulcan

Or install a specific release with:

$ forge install nomoixyz/vulcan@x.y.z

Release tags can be found here

To reduce compatibility issues, vulcan utilizes a particular version of forge-std. To avoid such problems in your project, consider including the following in your remappings:

forge-std/=lib/vulcan/lib/forge-std/src/
vulcan/=lib/vulcan/src/

Testing

Vulcan provides a simple testing framework through the base Test contract and the expect function.

import { Test, expect } from "vulcan/test.sol";

contract ExampleTest is Test {
    function test_something() external {
        uint256 value = 1;
        expect(value).toEqual(1);
        expect(value).not.toEqual(2);
        expect(value).toBeLessThan(2);
        expect("Hello World!").toContain("World");
    }
}

Invariant testing

In addition to the basic testing framework, Vulcan also provides utilities to facilitate the use of Foundry's invariant testing. These functions are provided through the invariants module.

import { Test, invariants, accounts } from "vulcan/test.sol";

contract ExampleTest is Test {
    function setUp() external {
        // { Bootstrap invariant testing scenario }

        invariants.excludeContract(myContract);

        // Use 10 different senders
        invariants.targetSenders(accounts.createMany(10));
    }

    function invariant_checkSomething() external {
        //...
    }
}

Scripts

Most of Vulcan's modules used for testing can be used in Scripts but not all the functions are recommended to be used in this context. A few examples are:

Accounts: Only the functions in the accountsSafe library should be used. If there is a need to use unsafe functions use the accountsUnsafe module exported in vulcan/script.sol.
Context: Only the functions in the ctxSafe library should be used. If there is a need to use unsafe functions use the ctxUnsafe module exported in vulcan/script.sol;
Forks: None of the functions in this module should be used. If there is a need to use unsafe functions use the forksUnsafe module exported in vulcan/script.sol.

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

import {MyContract} from "src/MyContract.sol";
import {Script, ctx, println, request} from "vulcan/script.sol";

contract DeployScript is Script {
    function run() public {
        ctx.startBroadcast();

        new MyContract();

        ctx.stopBroadcast();

        println("Notifying API");

        request
            .create()
            .post("https://my-api.io/webhook/notify/deployment")
            .send()
            .expect("Failed to trigger webhook");
    }
}

Accounts

Utilities to operate over accounts (balances, impersonation, etc.)

Examples

Create an address

How to create a simple address

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

import {Test, expect, accounts} from "vulcan/test.sol";

contract AccountsExample is Test {
    function test() external {
        address alice = accounts.create();

        expect(alice).not.toEqual(address(0));
    }
}

Create a labeled address

Creating an address labeled as "Alice"

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

import {Test, expect, accounts} from "vulcan/test.sol";

contract AccountsExample is Test {
    function test() external {
        address alice = accounts.create("Alice");

        expect(alice).not.toEqual(address(0));
    }
}

Create multiple addresses

Creating multiple addresses

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

import {Test, expect, accounts} from "vulcan/test.sol";

contract AccountsExample is Test {
    function test() external {
        address[] memory addresses = accounts.createMany(10);

        expect(addresses.length).toEqual(10);
    }
}

Create multiple labeled addresses with a prefix

Creating multiple addresses labeled with the prefix Account

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

import {Test, expect, accounts} from "vulcan/test.sol";

contract AccountsExample is Test {
    function test() external {
        address[] memory addresses = accounts.createMany(10, "Account");

        expect(addresses.length).toEqual(10);
    }
}

Use method chaining on addresses

Use method chaining on addresses to call multiple methods

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

import {Test, expect, accounts} from "vulcan/test.sol";

contract AccountsExample05 is Test {
    using accounts for address;

    function test() external {
        address alice = accounts.create("Alice").setNonce(666).setBalance(100e18);

        address bob = accounts.create("Bob").setBalance(10e18).impersonateOnce();

        payable(alice).transfer(bob.balance);

        expect(alice.balance).toEqual(110e18);
        expect(alice.getNonce()).toEqual(666);
        expect(bob.balance).toEqual(0);
    }
}

Accounts API reference

Commands

Execute external commands. The ffi setting must be enabled on foundry.toml for this module to work. The commands module uses Results when returning values.

Examples

Run a simple command

Run a simple command and obtain the output

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

import {Test, expect, commands, CommandResult, CommandOutput} from "vulcan/test.sol";

contract RunCommandExample is Test {
    function test() external {
        // Run the command
        CommandOutput memory result = commands.run(["echo", "Hello, World!"]).unwrap();

        // Check the output
        expect(string(result.stdout)).toEqual("Hello, World!");
    }
}

Reuse a command

Reuse a command with different arguments

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

import {Test, expect, commands, Command, CommandResult, CommandOutput} from "vulcan/test.sol";

contract ReuseACommandExample is Test {
    function test() external {
        // Create a command
        Command memory echo = commands.create("echo");

        // Run the commands and unwrap the results
        CommandOutput memory fooOutput = echo.arg("foo").run().unwrap();
        CommandOutput memory barOutput = echo.arg("bar").run().unwrap();

        // Check the outputs
        expect(string(fooOutput.stdout)).toEqual("foo");
        expect(string(barOutput.stdout)).toEqual("bar");
    }
}

Commands API reference

Context

Functionality to interact with the current runtime context:

Block data
Gas metering
Forge's expectRevert, expectEmit and mockCall (for an alternative, see watchers)
Vm state snapshots

Examples

Modify chain parameters

Use the context module to modify chain parameters

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

import {Test, expect, ctx} from "vulcan/test.sol";

contract ContextExample is Test {
    function test() external {
        ctx.setBlockTimestamp(1);
        expect(block.timestamp).toEqual(1);

        ctx.setBlockNumber(123);
        expect(block.number).toEqual(123);

        ctx.setBlockBaseFee(99999);
        expect(block.basefee).toEqual(99999);

        ctx.setBlockPrevrandao(bytes32(uint256(123)));
        expect(block.prevrandao).toEqual(uint256(bytes32(uint256(123))));

        ctx.setChainId(666);
        expect(block.chainid).toEqual(666);

        ctx.setBlockCoinbase(address(1));
        expect(block.coinbase).toEqual(address(1));

        ctx.setGasPrice(1e18);
        expect(tx.gasprice).toEqual(1e18);
    }
}

Modify chain parameters using method chaining

Use the context module to modify chain parameters using method chaining

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

import {Test, expect, ctx} from "vulcan/test.sol";

contract ContextExample is Test {
    function test() external {
        ctx.setBlockTimestamp(1).setBlockNumber(123).setBlockBaseFee(99999).setBlockPrevrandao(bytes32(uint256(123)))
            .setChainId(666).setBlockCoinbase(address(1)).setGasPrice(1e18);

        expect(block.timestamp).toEqual(1);
        expect(block.number).toEqual(123);
        expect(block.basefee).toEqual(99999);
        expect(block.prevrandao).toEqual(uint256(bytes32(uint256(123))));
        expect(block.chainid).toEqual(666);
        expect(block.coinbase).toEqual(address(1));
        expect(tx.gasprice).toEqual(1e18);
    }
}

Context API reference

Expect

The Expect module introduces the expect function, designed to validate if specified conditions are satisfied. Depending on the type of the input parameter, the expect function offers a range of matchers tailored to the context. For instance, with a string like "Hello World", you can use .toContain("Hello"), or for numbers, expect(1).toBeGreaterThan(0) can be applied. This adaptability ensures precise and concise condition checking across various data types.

Examples

Use different matchers

Using the expect function and its different matchers

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

import {Test, accounts, expect} from "vulcan/test.sol";

contract ExpectExample is Test {
    function test() external {
        expect(string("foo")).toEqual("foo");
        expect(string("foo")).not.toEqual("bar");
        expect(string("foo bar")).toContain("foo");
        expect(string("foo bar")).toContain("bar");

        expect(uint256(1)).toEqual(1);
        expect(uint256(1)).not.toEqual(0);
        expect(uint256(1)).toBeGreaterThan(0);
        expect(uint256(1)).toBeGreaterThanOrEqual(1);
        expect(uint256(0)).toBeLessThan(1);
        expect(uint256(0)).toBeLessThanOrEqual(0);

        address alice = accounts.create("Alice");
        address bob = accounts.create("Bob");
        expect(alice).toEqual(alice);
        expect(alice).not.toEqual(bob);

        expect(true).toBeTrue();
        expect(false).toBeFalse();
        expect((10 % 5) == 0).toBeTrue();
        expect((10 % 6) == 4).toBeTrue();
    }
}

Expect API reference

Fe

Provides Fe compiler support. The ffi setting must be enabled on foundry.toml for this module to work. This module requires the fe binary installed in order to work.

Examples

How to compile `fe` code

How to compile fe using the fe module (Requires to have fe installed)

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

import {Test, expect, fe, Fe} from "vulcan/test.sol";

contract FeExample is Test {
    function test() external {
        Fe memory feCmd = fe.create().setFilePath("./test/mocks/guest_book.fe").setOverwrite(true);

        // Compile the bytecode and revert if there is an error
        feCmd.build().unwrap();

        bytes memory bytecode = feCmd.getBytecode("MyFeContract").toValue();

        expect(bytecode).toEqual("600180600c6000396000f3fe00");
    }
}

Fe API reference

Format

The format function defined under the fmt module enables you to format strings dynamically by using a template string and the ABI encoded arguments.

The accepted placeholders are:

{address} or {a} for the address type.
{bytes32} or {b32} for the bytes32 type.
{string} or {s} for the string type.
{bytes} or {b} for the bytes type.
{uint} or {u} for the uint256 type.
{int} or {i} for the int256 type.
{bool} for the bool type.

For the uint256 type there is a special placeholder to deal with decimals {u:dx} where x is the number of decimals, for example {u:d18} to format numbers with 18 decimals.

Examples

Using templates

Using templates with the format module to format data

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

import {Test, accounts, expect, fmt, println} from "vulcan/test.sol";

contract FormatExample is Test {
    using accounts for address;

    function test() external {
        address target = address(1).setBalance(1);
        uint256 balance = target.balance;

        // Store it as a string
        // NOTE: The {address} and {uint} placeholders can be abbreviated as {a} and {u}
        // For available placeholders and abbreviations see: TODO
        string memory result = fmt.format("The account {address} has {uint} wei", abi.encode(target, balance));

        expect(result).toEqual("The account 0x0000000000000000000000000000000000000001 has 1 wei");

        // Format is also used internally by Vulcan's println, which you can use as an alternative to console.log
        println("The account {address} has {uint} wei", abi.encode(target, balance));
    }
}

Formatting decimals

Use the {uint:dx} placeholder to format numbers with decimals

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

import {Test, accounts, expect, fmt} from "vulcan/test.sol";

contract FormatExample is Test {
    using accounts for address;

    function test() external {
        address target = address(1).setBalance(1e17);
        uint256 balance = target.balance;

        // Store it as a string
        string memory result = fmt.format("The account {address} has {uint:d18} eth", abi.encode(target, balance));

        expect(result).toEqual("The account 0x0000000000000000000000000000000000000001 has 0.1 eth");
    }
}

Format API reference

Fs

Provides utilities to interact with the filesystem. In order to use this module the fs_permissions setting must be set correctly in foundry.toml.

Examples

Reading files

Read files as string or bytes

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

import {Test, expect, fs, BytesResult, StringResult} from "vulcan/test.sol";

contract FsExample is Test {
    // These files are available only on the context of vulcan
    // You will need to provide your own files and edit the read permissions accordingly
    string constant HELLO_WORLD = "./test/fixtures/fs/read/hello_world.txt";
    string constant BINARY_TEST_FILE = "./test/fixtures/fs/write/test_binary.txt";

    function test() external {
        string memory stringResult = fs.readFile(HELLO_WORLD).unwrap();
        expect(stringResult).toEqual("Hello, World!\n");

        bytes memory bytesResult = fs.readFileBinary(HELLO_WORLD).unwrap();
        expect(bytesResult).toEqual("Hello, World!\n");
    }
}

Writing files

Write files as strings or bytes

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

import {Test, expect, fs, BytesResult, StringResult, EmptyResult} from "vulcan/test.sol";

contract FsExample is Test {
    // These files are available only on the context of vulcan
    // You will need to provide your own files and edit the read permissions accordingly
    string constant TEXT_TEST_FILE = "./test/fixtures/fs/write/example.txt";

    function test() external {
        // Write string
        fs.writeFile(TEXT_TEST_FILE, "This is a test").expect("Failed to write file");

        string memory readStringResult = fs.readFile(TEXT_TEST_FILE).unwrap();

        expect(readStringResult).toEqual("This is a test");

        // Write binary
        fs.writeFileBinary(TEXT_TEST_FILE, "This is a test in binary").expect("Failed to write file");

        bytes memory readBytesResult = fs.readFileBinary(TEXT_TEST_FILE).unwrap();

        expect(readBytesResult).toEqual("This is a test in binary");
    }
}

Other operations

Obtain metadata and check if file exists

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

import {Test} from "vulcan/test.sol";
import {expect} from "vulcan/test/Expect.sol";
import {fs, FsMetadata} from "vulcan/test/Fs.sol";
import {BoolResult} from "vulcan/test/Result.sol";

contract FsExample is Test {
    // These files are available only on the context of vulcan
    // You will need to provide your own files and edit the read permissions accordingly
    string constant READ_EXAMPLE = "./test/fixtures/fs/read/hello_world.txt";
    string constant NOT_FOUND_EXAMPLE = "./test/fixtures/fs/read/lkjjsadflkjasdf.txt";

    function test() external {
        FsMetadata memory metadata = fs.metadata(READ_EXAMPLE).expect("Failed to get metadata");
        expect(metadata.isDir).toBeFalse();

        bool exists = fs.fileExists(READ_EXAMPLE).unwrap();
        expect(exists).toBeTrue();

        exists = fs.fileExists(NOT_FOUND_EXAMPLE).unwrap();
        expect(exists).toBeFalse();
    }
}

Fs API reference

Provides method to measure gas usage in a more granular way.

Examples

Measuring gas

Obtain the gas cost of a operation

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

import {Test, expect, gas} from "vulcan/test.sol";

contract GasExample is Test {
    function test() external {
        // Start recording gas usage
        gas.record("example");

        payable(0).transfer(1e18);

        // Stop recording and obtain the amount of gas used
        uint256 used = gas.stopRecord("example");

        expect(used).toBeGreaterThan(0);
    }
}

Gas API reference

Huff

Provides Huff compiler support. The ffi setting must be enabled on foundry.toml for this module to work. This module requires the huffc binary installed in order to work.

Examples

How to compile `huff` code

How to compile huff code using the huff module (Requires to have huff installed)

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

import {Test, expect, huff, CommandOutput} from "vulcan/test.sol";

contract HuffExample is Test {
    function test() external {
        CommandOutput memory result = huff.create().setFilePath("./test/mocks/Getter.huff").compile().unwrap();
        expect(result.stdout.length).toBeGreaterThan(0);
    }
}

Huff API reference

Json

Manipulate JSON data.

Examples

Work with JSON objects

Create a JSON object, populate it and read it

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

import {Test, expect, json, JsonObject} from "vulcan/test.sol";

contract JSONExample is Test {
    function test() external {
        // Create an empty JsonObject
        JsonObject memory obj = json.create();

        string memory key = "foo";
        string memory value = "bar";

        obj.set(key, value);

        expect(obj.getString(".foo")).toEqual(value);

        // Create a populated JsonObject
        obj = json.create("{ \"foo\": { \"bar\": \"baz\" } }").unwrap();

        expect(obj.getString(".foo.bar")).toEqual("baz");
    }
}

Json API reference

Results & Errors

The concept of "Results" is inspired by Rust. It centers around using specific types for returning values while also offering mechanisms to handle any potential errors.

Similar to Rust's Results API, Vulcan implements the following functions for all result types:

unwrap(): if the Result is an Error, reverts with the default error message. If if is Ok, it returns the underlying value
expect(message): same as unwrap(), but reverts with the provided error message
isError(): returns true if the Result is an error, false otherwise
isOk(): the oposite of isError()
toError(): transforms the Result into an Error
toValue(): gets the Result's underlying value (if the Result is Ok)

Examples

Working with result values

Different methods of getting the underlyng value of a Result

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

import {Test, expect, StringResult} from "vulcan/test.sol";
// This import is just to demonstration, it's not meant to be imported on projects using Vulcan
import {Ok} from "vulcan/_internal/Result.sol";

contract ResultExample is Test {
    function test() external {
        StringResult result = Ok(string("foo"));

        // Use unwrap to get the value or revert if the result is an `Error`
        string memory value = result.unwrap();
        expect(value).toEqual("foo");

        // Use expect to get the value or revert with a custom message if
        // the result is an `Error`
        value = result.expect("Result failed");
        expect(value).toEqual("foo");

        // Safely handling the result
        if (result.isOk()) {
            value = result.toValue();
            expect(value).toEqual("foo");
        }
    }
}

Working with Errors

Different ways of handling errors.

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

import {Test, commands, ctx, expect, CommandResult, CommandError} from "vulcan/test.sol";

contract ResultExample is Test {
    function test() external {
        // Run a non existent command
        CommandResult result = commands.run(["asdf12897u391723"]);

        ctx.expectRevert();

        // Use unwrap to revert with the default error message
        result.unwrap();

        ctx.expectRevert("Command not executed");

        // Use expect to revert with a custom error message
        result.expect("Command not executed");

        bool failed = false;

        // Handle the error manually
        if (result.isError()) {
            if (result.toError().matches(CommandError.NotExecuted)) {
                failed = true;
            }
        }

        expect(failed).toBeTrue();
    }
}

Results API reference

Errors API reference

Requests

The request module is inspired by Rust's reqwest crate. It provides a flexible API to interact with external web services allowing to work with request headers, request authorization, response headers, parsing a response body as JSON and others.

Examples

Sending requests

How to send requests to an http server

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

import {Test, expect, request, Response} from "vulcan/test.sol";

contract RequestExample is Test {
    function test() external {
        Response memory getResponse = request.create().get("https://httpbin.org/get").send().unwrap();
        Response memory postResponse = request.create().post("https://httpbin.org/post").send().unwrap();
        Response memory patchResponse = request.create().patch("https://httpbin.org/patch").send().unwrap();
        Response memory putResponse = request.create().put("https://httpbin.org/put").send().unwrap();
        Response memory deleteResponse = request.create().del("https://httpbin.org/delete").send().unwrap();

        expect(getResponse.status).toEqual(200);
        expect(postResponse.status).toEqual(200);
        expect(patchResponse.status).toEqual(200);
        expect(putResponse.status).toEqual(200);
        expect(deleteResponse.status).toEqual(200);
    }
}

Request authentication

How to use different methods of authentication

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

import {Test, expect, request, Response, RequestClient} from "vulcan/test.sol";

contract RequestExample is Test {
    function test() external {
        RequestClient memory client = request.create();

        Response memory basicAuthRes =
            client.get("https://httpbin.org/basic-auth/user/pass").basicAuth("user", "pass").send().unwrap();

        expect(basicAuthRes.status).toEqual(200);

        Response memory bearerAuthRes = client.get("https://httpbin.org/bearer").bearerAuth("token").send().unwrap();

        expect(bearerAuthRes.status).toEqual(200);
    }
}

Working with headers

Using the request module to work with request headers

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

import {Test, expect, request, Headers, Response, Request, RequestClient} from "vulcan/test.sol";

contract RequestExample is Test {
    function test() external {
        // Setting a default header as key value
        RequestClient memory client = request.create().defaultHeader("X-Foo", "true");

        expect(client.headers.get("X-Foo")).toEqual("true");

        // The default header gets passed to the request
        Request memory req = client.post("https://some-http-server.com").request.unwrap();

        expect(req.headers.get("X-Foo")).toEqual("true");

        // Setting multiple headers with a Header variable
        Headers headers = request.createHeaders().insert("X-Bar", "true").insert("X-Baz", "true");
        client = request.create().defaultHeaders(headers);

        expect(client.headers.get("X-Bar")).toEqual("true");
        expect(client.headers.get("X-Baz")).toEqual("true");
    }
}

Utils

This module provides a set of utility functions that make use of other modules in Vulcan.

Some of the utility functions:

format: Formats a string in a similar way to rust format! macro. This function uses the fmt module underneath meaning that all templating options from the fmt module are available.
println: Logs a formatted string in a similar way to rust println! macro. This function uses the format function underneath

Examples

Using println

Using the println function to log formatted data

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

import {Test, expect, println} from "vulcan/test.sol";

contract UtilsExample is Test {
    function test() external view {
        println("Log a simple string");

        string memory someString = "someString";
        println("This is a string: {s}", abi.encode(someString));

        uint256 aNumber = 123;
        println("This is a uint256: {u}", abi.encode(aNumber));

        println("A string: {s} and a number: {u}", abi.encode(someString, aNumber));
    }
}

Using format

Using the format function to format data

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

import {Test, expect, format} from "vulcan/test.sol";

contract FormatExample is Test {
    function test() external {
        uint256 uno = 1;

        string memory formatted = format("is {u} greater than 0? {bool}", abi.encode(uno, uno > 0));

        expect(formatted).toEqual("is 1 greater than 0? true");
    }
}

Utils API reference

Other modules

Config

Access the Foundry project configuration. For now it can only read RPC URLs.

Examples

Obtain a specific RPC URL

Read a specific RPC URL from the foundry configuration

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

import {Test, expect, config} from "vulcan/test.sol";

contract ConfigExample is Test {
    function test() external {
        string memory key = "mainnet";

        expect(config.rpcUrl(key)).toEqual("https://mainnet.rpc.io");
    }
}

Obtain all the RPC URLs

Read all the RPC URLs from the foundry configuration

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

import {Test, expect, config} from "vulcan/test.sol";

contract ConfigExample is Test {
    function test() external {
        string[2][] memory rpcs = config.rpcUrls();

        expect(rpcs.length).toEqual(2);
        expect(rpcs[0][0]).toEqual("arbitrum");
        expect(rpcs[0][1]).toEqual("https://arbitrum.rpc.io");
        expect(rpcs[1][0]).toEqual("mainnet");
        expect(rpcs[1][1]).toEqual("https://mainnet.rpc.io");
    }
}

Obtain all the RPC URLs using structs

Read all the RPC URL from the foundry configuration as structs

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

import {Test, expect, config, RpcConfig} from "vulcan/test.sol";

contract ConfigExample is Test {
    function test() external {
        RpcConfig[] memory rpcs = config.rpcUrlStructs();

        expect(rpcs.length).toEqual(2);
        expect(rpcs[0].name).toEqual("arbitrum");
        expect(rpcs[0].url).toEqual("https://arbitrum.rpc.io");
        expect(rpcs[1].name).toEqual("mainnet");
        expect(rpcs[1].url).toEqual("https://mainnet.rpc.io");
    }
}

Config API reference

Console

Print to the console. Uses forge-std/console2.sol.

Examples

Log values

Use the console function to log values.

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

import {Test, expect, console} from "vulcan/test.sol";

contract ConsoleExample is Test {
    function test() external pure {
        string memory foo = "foo";
        string memory bar = "bar";

        uint256 oneTwoThree = 123;
        uint256 threeTwoOne = 321;

        bool isTrue = true;

        console.log(foo);
        console.log(foo, bar);
        console.log(foo, bar, threeTwoOne);
        console.log(foo, bar, threeTwoOne, isTrue);
        console.log(threeTwoOne, oneTwoThree);
        console.log(threeTwoOne + oneTwoThree);
        console.log(1 > 0);
    }
}

Env

Set and read environmental variables.

Examples

Set and get environment variables

Use the env module to set and read environment variables

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

import {Test, expect, env} from "vulcan/test.sol";

contract EnvExample is Test {
    function test() external {
        env.set("SomeString", "foo");
        env.set("SomeUint", "100000000000000000000000");
        env.set("SomeBool", "true");
        env.set("SomeArray", "1,2,3,4");

        expect(env.getString("SomeString")).toEqual("foo");
        expect(env.getUint("SomeUint")).toEqual(100_000_000_000_000_000_000_000);
        expect(env.getBool("SomeBool")).toBeTrue();
        expect(env.getUintArray("SomeArray", ",")[0]).toEqual(1);
        expect(env.getUintArray("SomeArray", ",")[1]).toEqual(2);
        expect(env.getUintArray("SomeArray", ",")[2]).toEqual(3);
        expect(env.getUintArray("SomeArray", ",")[3]).toEqual(4);
    }
}

Env API reference

Events

Provides utilities to get logs and transform values into their topic representation.

Examples

Logging events

Logging events and reading events topics and data

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

import {Test, expect, events, Log} from "vulcan/test.sol";

contract EventsExample is Test {
    using events for *;

    event SomeEvent(uint256 indexed a, address b);

    function run() external {
        uint256 a = 666;
        address b = address(333);

        events.recordLogs();

        emit SomeEvent(a, b);

        Log[] memory logs = events.getRecordedLogs();

        expect(logs.length).toEqual(1);
        expect(logs[0].emitter).toEqual(address(this));
        expect(logs[0].topics[0]).toEqual(SomeEvent.selector);
        expect(logs[0].topics[1]).toEqual(a.topic());
        expect(logs[0].data).toEqual(abi.encode(b));
    }
}

Events API reference

Forks

Forking functionality.

Examples

How to use forks

How to use forks. This example assumes there is a JSON RPC server running at localhost:8545

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

import {Test, expect, vulcan} from "vulcan/test.sol";
import {forks, Fork} from "vulcan/test/Forks.sol";
import {ctx} from "vulcan/test/Context.sol";

contract ForksExample is Test {
    string constant RPC_URL = "http://localhost:8545";

    function test() external {
        forks.create(RPC_URL).select();

        expect(block.chainid).toEqual(31337);
    }
}

Forks API reference

RPC

The rpc module provides methods to interact with JSON-RPC APIs. The list of official Ethereum RPC methods can be found here.

Examples

Calling an RPC

Calling an rpc using the eth_chainId method

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

import {Test, expect} from "vulcan/test.sol";
import {rpc} from "vulcan/test/Rpc.sol";
import {Fork, forks} from "vulcan/test/Forks.sol";

contract RpcTest is Test {
    function testNetVersion() external {
        forks.create("https://rpc.mevblocker.io/fast").select();

        string memory method = "eth_chainId";
        string memory params = "[]";

        bytes memory data = rpc.call(method, params);

        uint8 chainId;

        assembly {
            chainId := mload(add(data, 0x01))
        }

        expect(chainId).toEqual(block.chainid);
    }
}

Strings

Convert basic types from / to strings.

Examples

Transforming and parsing

Transform values to strings and parse strings to values

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

import {Test, expect, strings} from "vulcan/test.sol";

contract StringsExample is Test {
    using strings for *;

    function test() external {
        uint256 uintValue = 123;
        string memory uintString = uintValue.toString();
        expect(uintString).toEqual("123");
        expect(uintString.parseUint()).toEqual(uintValue);

        bool boolValue = true;
        string memory boolString = boolValue.toString();
        expect(boolString).toEqual("true");
        expect(boolString.parseBool()).toEqual(true);

        bytes32 bytes32Value = bytes32(uintValue);
        string memory bytes32String = bytes32Value.toString();
        expect(bytes32String).toEqual("0x000000000000000000000000000000000000000000000000000000000000007b");
        expect(bytes32String.parseBytes32()).toEqual(bytes32Value);
    }
}

Strings API reference

Accounts

accountsSafe

Accounts module for scripts

readStorage(address who, bytes32 slot) → (bytes32)

Reads the storage at the specified slot for the given who address and returns the content.

sign(uint256 privKey, bytes32 digest) → (uint8, bytes32, bytes32)

Signs the specified digest using the provided privKey and returns the signature in the form of (v, r, s).

derive(uint256 privKey) → (address)

Derives the Ethereum address corresponding to the provided privKey.

deriveKey(string mnemonicOrPath, uint32 index) → (uint256)

Derives the private key corresponding to the specified mnemonicOrPath and index.

deriveKey(string mnemonicOrPath, string derivationPath, uint32 index) → (uint256)

Derives the private key corresponding to the specified mnemonicOrPath, derivationPath, and index.

rememberKey(uint256 privKey) → (address)

Adds the specified privKey to the local forge wallet.

getNonce(address who) → (uint64)

Returns the current nonce of the specified who address.

recordStorage()

Starts recording all storage reads and writes for later analysis.

getStorageAccesses(address who) → (bytes32[] reads, bytes32[] writes)

Obtains an array of slots that have been read and written for the specified address who.

label(address who, string lbl) → (address)

Adds a label to the specified address who for identification purposes in debug traces.

create() → (address)

Creates an address without label.

create(string name) → (address)

Creates an address using the hash of the specified name as the private key and adds a label to the address.

create(string name, string lbl) → (address)

Creates an address using the hash of the specified name as the private key and adds a label to the address.

getDeploymentAddress(address who, uint64 nonce) → (address)

Calculates the deployment address of who with nonce nonce.

getDeploymentAddress(address who) → (address)

Calculates the deployment address of who with the current nonce.

createMany(uint256 length) → (address[])

Generates an array of addresses with a specific length.

createMany(uint256 length, string prefix) → (address[])

Generates an array of addresses with a specific length and a prefix as label. The label for each address will be {prefix}_{i}.

accountsUnsafe

Accounts module for tests

stdStore() → (StdStorage s)

readStorage(address who, bytes32 slot) → (bytes32)

sign(uint256 privKey, bytes32 digest) → (uint8, bytes32, bytes32)

derive(uint256 privKey) → (address)

deriveKey(string mnemonicOrPath, uint32 index) → (uint256)

deriveKey(string mnemonicOrPath, string derivationPath, uint32 index) → (uint256)

rememberKey(uint256 privKey) → (address)

getNonce(address who) → (uint64)

recordStorage()

getStorageAccesses(address who) → (bytes32[] reads, bytes32[] writes)

label(address who, string lbl) → (address)

create() → (address)

create(string name) → (address)

create(string name, string lbl) → (address)

getDeploymentAddress(address who, uint64 nonce) → (address)

Calculates the deployment address of who with nonce nonce.

getDeploymentAddress(address who) → (address)

Calculates the deployment address of who with the current nonce.

setStorage(address self, bytes32 slot, bytes32 value) → (address)

Sets the specified slot in the storage of the given self address to the provided value.

setNonce(address self, uint64 n) → (address)

Sets the nonce of the given self address to the provided value n. It will revert if

setNonceUnsafe(address self, uint64 n) → (address)

Sets the nonce of the given self address to the arbitrary provided value n.

impersonateOnce(address self) → (address)

Sets the msg.sender of the next call to self.

impersonate(address self) → (address)

impersonateOnce(address self, address origin) → (address)

Sets the msg.sender of the next call to self and the tx.origin to origin.

impersonate(address self, address origin) → (address)

Sets the msg.sender and tx.origin of all the subsequent calls to self and origin respectively until stopImpersonate is called.

stopImpersonate()

setBalance(address self, uint256 bal) → (address)

Sets the balance of an address and returns the address that was modified.

mintToken(address self, address token, uint256 amount) → (address)

Mints an amount of tokens to an address. This operation modifies the total supply of the token. self The address that will own the tokens. token The token to mint. amount The amount of tokens to mint.

burnToken(address self, address token, uint256 amount) → (address)

Burns an amount of tokens from an address. This operation modifies the total supply of the token. self The address that owns the tokens. token The token to burn. amount The amount of tokens to burn.

setTokenBalance(address self, address token, uint256 bal) → (address)

Sets the token balance of an address.

setCode(address self, bytes code) → (address)

Sets the code of an address.

createMany(uint256 length) → (address[])

Generates an array of addresses with a specific length.

createMany(uint256 length, string prefix) → (address[])

Generates an array of addresses with a specific length and a prefix as label. The label for each address will be {prefix}_{i}.

Commands

Custom types

CommandResult

type CommandResult is bytes32;

Structs

Command

struct Command {
	string[] inputs
}

Struct used to hold command parameters. Useful for creating commands that can be run multiple times

CommandOutput

struct CommandOutput {
	int32 exitCode
	bytes stdout
	bytes stderr
	Command command
}

Functions

Ok(CommandOutput value) → (CommandResult)

commands

create() → (Command cmd)

Creates a new 'Command' struct with empty arguments.

create(string input) → (Command)

Creates a new Command struct using the provided input as the executable.

arg(Command self, string _arg) → (Command)

args(Command self, string[] _args) → (Command)

args(Command self, string[1] _args) → (Command)

args(Command self, string[2] _args) → (Command)

args(Command self, string[3] _args) → (Command)

args(Command self, string[4] _args) → (Command)

args(Command self, string[5] _args) → (Command)

args(Command self, string[6] _args) → (Command)

args(Command self, string[7] _args) → (Command)

args(Command self, string[8] _args) → (Command)

args(Command self, string[9] _args) → (Command)

args(Command self, string[10] _args) → (Command)

args(Command self, string[11] _args) → (Command)

args(Command self, string[12] _args) → (Command)

args(Command self, string[13] _args) → (Command)

args(Command self, string[14] _args) → (Command)

args(Command self, string[15] _args) → (Command)

args(Command self, string[16] _args) → (Command)

args(Command self, string[17] _args) → (Command)

args(Command self, string[18] _args) → (Command)

args(Command self, string[19] _args) → (Command)

args(Command self, string[20] _args) → (Command)

toString(Command self) → (string)

Transforms a command to its string representation.

run(Command self) → (CommandResult)

Runs a command using the specified Command struct as parameters and returns the result.

run(string[] inputs) → (CommandResult)

Runs a command with the specified inputs as parameters and returns the result.

run(string[1] inputs) → (CommandResult)

run(string[2] inputs) → (CommandResult)

run(string[3] inputs) → (CommandResult)

run(string[4] inputs) → (CommandResult)

run(string[5] inputs) → (CommandResult)

run(string[6] inputs) → (CommandResult)

run(string[7] inputs) → (CommandResult)

run(string[8] inputs) → (CommandResult)

run(string[9] inputs) → (CommandResult)

run(string[10] inputs) → (CommandResult)

run(string[11] inputs) → (CommandResult)

run(string[12] inputs) → (CommandResult)

run(string[13] inputs) → (CommandResult)

run(string[14] inputs) → (CommandResult)

run(string[15] inputs) → (CommandResult)

run(string[16] inputs) → (CommandResult)

run(string[17] inputs) → (CommandResult)

run(string[18] inputs) → (CommandResult)

run(string[19] inputs) → (CommandResult)

run(string[20] inputs) → (CommandResult)

CommandError

NotExecuted(string reason) → (Error)

toCommandResult(Error self) → (CommandResult)

LibCommandOutputPointer

toCommandOutput(Pointer self) → (CommandOutput output)

toCommandResult(Pointer self) → (CommandResult result)

toPointer(CommandOutput self) → (Pointer ptr)

LibCommandResult

isOk(CommandResult self) → (bool)

isError(CommandResult self) → (bool)

unwrap(CommandResult self) → (CommandOutput)

expect(CommandResult self, string err) → (CommandOutput)

toError(CommandResult self) → (Error)

toValue(CommandResult self) → (CommandOutput)

toPointer(CommandResult self) → (Pointer)

Config

Structs

RpcConfig

struct RpcConfig {
	string name
	string url
}

Struct that represents an RPC endpoint

config

rpcUrl(string name) → (string)

Obtains a specific RPC from the configuration by name.

rpcUrls() → (string[2][])

Obtains all the RPCs from the configuration.

rpcUrlStructs() → (RpcConfig[] rpcs)

Obtains all the RPCs from the configuration.

Context

Custom types

Context

type Context is bytes32;

ctxSafe

broadcast()

broadcast(address from)

broadcast(uint256 privKey)

startBroadcast()

startBroadcast(address from)

startBroadcast(uint256 privKey)

stopBroadcast()

assume(bool condition)

pauseGasMetering()

resumeGasMetering()

startGasReport(string name)

endGasReport()

ctxUnsafe

init()

Function to initialize and set the code of CALL_CONTEXT_ADDRESS.

broadcast()

broadcast(address from)

broadcast(uint256 privKey)

startBroadcast()

startBroadcast(address from)

startBroadcast(uint256 privKey)

stopBroadcast()

assume(bool condition)

pauseGasMetering()

resumeGasMetering()

startGasReport(string name)

endGasReport()

isStaticcall() → (bool)

Checks whether the current call is a static call or not.

setBlockTimestamp(Context self, uint256 ts) → (Context)

sets the block.timestamp to ts

setBlockTimestamp(uint256 ts) → (Context)

sets the block.timestamp to ts

setBlockNumber(Context self, uint256 blockNumber) → (Context)

sets the block.number to blockNumber

setBlockNumber(uint256 blockNumber) → (Context)

sets the block.number to blockNumber

setBlockBaseFee(Context self, uint256 baseFee) → (Context)

sets the block.basefee to baseFee

setBlockBaseFee(uint256 baseFee) → (Context)

sets the block.basefee to baseFee

setBlockPrevrandao(Context self, bytes32 newPrevrandao) → (Context)

Sets block.prevrandao.

setBlockPrevrandao(bytes32 newPrevrandao) → (Context)

Sets block.prevrandao.

setChainId(Context self, uint64 chainId) → (Context)

sets the block.chainid to chainId

setChainId(uint64 chainId) → (Context)

sets the block.chainid to chainId

setBlockCoinbase(Context self, address who) → (Context)

Sets the block coinbase to who.

setBlockCoinbase(address who) → (Context)

Sets the block coinbase to who.

setGasPrice(Context self, uint256 newGasPrice) → (Context)

Sets the transaction gas price.

setGasPrice(uint256 newGasPrice) → (Context)

Sets the transaction gas price.

expectRevert(bytes revertData)

Function used to check whether the next call reverts or not.

expectRevert(bytes4 revertData)

Function used to check whether the next call reverts or not.

expectRevert()

Function used to check whether the next call reverts or not.

expectEmit(bool checkTopic1, bool checkTopic2, bool checkTopic3, bool checkData)

Checks if an event was emitted with the given properties.

expectEmit(bool checkTopic1, bool checkTopic2, bool checkTopic3, bool checkData, address emitter)

Checks if an event was emitted with the given properties.

mockCall(address callee, bytes data, bytes returnData)

Function to mock a call to a specified address.

mockCall(address callee, uint256 msgValue, bytes data, bytes returnData)

Function to mock a call to a specified address.

clearMockedCalls()

Function to clear all the mocked calls.

expectCall(address callee, bytes data)

Used to check if a call to callee with data was made.

expectCall(address callee, uint256 msgValue, bytes data)

Used to check if a call to callee with data and msgValue was made.

expectCallMinGas(address callee, uint256 msgValue, uint64 minGas, bytes data)

Expect a call to an address with the specified msg.value and calldata, and a minimum amount of gas.

expectCallMinGas(address callee, uint256 msgValue, uint64 minGas, bytes data, uint64 count)

Expect a number call to an address with the specified msg.value and calldata, and a minimum amount of gas.

expectSafeMemory(uint64 min, uint64 max)

Allows to write on memory only between [0x00, 0x60) and [min, max) in the current. subcontext.

expectsafememorycall(uint64 min, uint64 max)

Allows to write on memory only between [0x00, 0x60) and [min, max) in the next

snapshot(Context) → (uint256)

Takes a snapshot of the current state of the vm and returns an identifier.

snapshot() → (uint256)

Takes a snapshot of the current state of the vm and returns an identifier.

revertToSnapshot(Context, uint256 snapshotId) → (bool)

Reverts the state of the vm to the snapshot with id snapshotId.

revertToSnapshot(uint256 snapshotId) → (bool)

Reverts the state of the vm to the snapshot with id snapshotId.

addBreakpoint(Context self, string name) → (Context)

Creates a breakpoint to jump to in the debugger.

addBreakpoint(string name) → (Context)

Creates a breakpoint to jump to in the debugger.

addConditionalBreakpoint(Context self, string name, bool condition) → (Context)

Creates a breakpoint to jump to in the debugger.

addConditionalBreakpoint(string name, bool condition) → (Context)

Creates a breakpoint to jump to in the debugger.

Env

env

set(string name, string value)

sets the value of the environment variable with name name to value.

getBool(string name) → (bool)

Reads the environment variable with name name and returns the value as bool.

getUint(string name) → (uint256)

Reads the environment variable with name name and returns the value as uint256.

getInt(string name) → (int256)

Reads the environment variable with name name and returns the value as int256.

getAddress(string name) → (address)

Reads the environment variable with name name and returns the value as address.

getBytes32(string name) → (bytes32)

Reads the environment variable with name name and returns the value as bytes32.

getString(string name) → (string)

Reads the environment variable with name name and returns the value as string.

getBytes(string name) → (bytes)

Reads the environment variable with name name and returns the value as bytes.

getBoolArray(string name, string delim) → (bool[])

Reads the environment variable with name name and returns the value as bool[].

getUintArray(string name, string delim) → (uint256[])

Reads the environment variable with name name and returns the value as uint256[].

getIntArray(string name, string delim) → (int256[])

Reads the environment variable with name name and returns the value as int256[].

getAddressArray(string name, string delim) → (address[])

Reads the environment variable with name name and returns the value as address[].

getBytes32Array(string name, string delim) → (bytes32[])

Reads the environment variable with name name and returns the value as bytes32[].

getStringArray(string name, string delim) → (string[])

Reads the environment variable with name name and returns the value as string[].

getBytesArray(string name, string delim) → (bytes[])

Reads the environment variable with name name and returns the value as bytes[].

getBool(string name, bool defaultValue) → (bool value)

Reads the environment variable with name name and returns the value as bool.

getUint(string name, uint256 defaultValue) → (uint256 value)

Reads the environment variable with name name and returns the value as uint256.

getInt(string name, int256 defaultValue) → (int256 value)

Reads the environment variable with name name and returns the value as int256.

getAddress(string name, address defaultValue) → (address value)

Reads the environment variable with name name and returns the value as address.

getBytes32(string name, bytes32 defaultValue) → (bytes32 value)

Reads the environment variable with name name and returns the value as bytes32.

getString(string name, string defaultValue) → (string value)

Reads the environment variable with name name and returns the value as string.

getBytes(string name, bytes defaultValue) → (bytes value)

Reads the environment variable with name name and returns the value as bytes.

getBoolArray(string name, string delim, bool[] defaultValue) → (bool[] value)

Reads the environment variable with name name and returns the value as bool[].

getUintArray(string name, string delim, uint256[] defaultValue) → (uint256[] value)

Reads the environment variable with name name and returns the value as uint256[].

getIntArray(string name, string delim, int256[] defaultValue) → (int256[] value)

Reads the environment variable with name name and returns the value as int256[].

getAddressArray(string name, string delim, address[] defaultValue) → (address[] value)

Reads the environment variable with name name and returns the value as address[].

getBytes32Array(string name, string delim, bytes32[] defaultValue) → (bytes32[] value)

Reads the environment variable with name name and returns the value as bytes32[].

getStringArray(string name, string delim, string[] defaultValue) → (string[] value)

Reads the environment variable with name name and returns the value as string[].

getBytesArray(string name, string delim, bytes[] defaultValue) → (bytes[] value)

Reads the environment variable with name name and returns the value as bytes[].

Error

Custom types

Error

type Error is bytes32;

LibError

toPointer(Error err) → (Pointer)

decode(Error err) → (bytes32 id, string message, bytes data)

encodeError(function fn, string message) → (Error err)

toErrorId(function fn) → (bytes32 id)

matches(Error err, function fn) → (bool)

decodeAs(Error, function)

encodeError(function fn, string message, uint256 p0) → (Error err)

toErrorId(function fn) → (bytes32 id)

matches(Error err, function fn) → (bool)

decodeAs(Error err, function) → (uint256)

encodeError(function fn, string message, string p0) → (Error err)

toErrorId(function fn) → (bytes32 id)

matches(Error err, function fn) → (bool)

decodeAs(Error err, function) → (string)

toStringResult(Error self) → (StringResult)

toBytesResult(Error self) → (BytesResult)

toBoolResult(Error self) → (BoolResult)

Events

events

topic(uint256 _param) → (bytes32)

Obtains the topic representation of an uint256 parameter.

topic(string _param) → (bytes32)

Obtains the topic representation of a string parameter.

topic(address _param) → (bytes32)

Obtains the topic representation of an address parameter.

topic(bytes32 _param) → (bytes32)

Obtains the topic representation of a bytes32 parameter.

topic(bytes _param) → (bytes32)

Obtains the topic representation of a bytes parameter.

topic(bool _param) → (bytes32)

Obtains the topic representation of a bool parameter.

topic(int256 _param) → (bytes32)

Obtains the topic representation of a int256 parameter.

recordLogs()

Starts recording all transactions logs.

getRecordedLogs() → (Log[] logs)

Obtains all recorded transactions logs.

Expect

Structs

_BoolExpectation

struct _BoolExpectation {
	bool actual
	_BoolExpectationNot not
}

_BoolExpectationNot

struct _BoolExpectationNot {
	bool actual
}

_UintExpectation

struct _UintExpectation {
	uint256 actual
	_UintExpectationNot not
}

_UintExpectationNot

struct _UintExpectationNot {
	uint256 actual
}

_IntExpectation

struct _IntExpectation {
	int256 actual
	_IntExpectationNot not
}

_IntExpectationNot

struct _IntExpectationNot {
	int256 actual
}

_AddressExpectation

struct _AddressExpectation {
	address actual
	_AddressExpectationNot not
}

_AddressExpectationNot

struct _AddressExpectationNot {
	address actual
}

_Bytes32Expectation

struct _Bytes32Expectation {
	bytes32 actual
	_Bytes32ExpectationNot not
}

_Bytes32ExpectationNot

struct _Bytes32ExpectationNot {
	bytes32 actual
}

_BytesExpectation

struct _BytesExpectation {
	bytes actual
	_BytesExpectationNot not
}

_BytesExpectationNot

struct _BytesExpectationNot {
	bytes actual
}

_StringExpectation

struct _StringExpectation {
	string actual
	_StringExpectationNot not
}

_StringExpectationNot

struct _StringExpectationNot {
	string actual
}

_CallExpectation

struct _CallExpectation {
	Call call
	_CallExpectationNot not
}

_CallExpectationNot

struct _CallExpectationNot {
	Call call
}

Functions

expect(bool actual) → (_BoolExpectation)

expect(uint256 actual) → (_UintExpectation)

expect(int256 actual) → (_IntExpectation)

expect(address actual) → (_AddressExpectation)

expect(bytes32 actual) → (_Bytes32Expectation)

expect(bytes actual) → (_BytesExpectation)

expect(string actual) → (_StringExpectation)

expect(Call call) → (_CallExpectation)

any() → (bytes32)

ExpectLib

toEqual(_BoolExpectation self, bool expected)

toEqual(_BoolExpectation self, bool expected, string message)

toEqual(_BoolExpectationNot self, bool expected)

toEqual(_BoolExpectationNot self, bool expected, string message)

toBeTrue(_BoolExpectation self)

toBeTrue(_BoolExpectation self, string message)

toBeFalse(_BoolExpectation self)

toBeFalse(_BoolExpectation self, string message)

toEqual(_AddressExpectation self, address expected)

toEqual(_AddressExpectation self, address expected, string message)

toEqual(_AddressExpectationNot self, address expected)

toEqual(_AddressExpectationNot self, address expected, string message)

toBeAContract(_AddressExpectation self)

toBeAContract(_AddressExpectation self, string message)

toBeAContract(_AddressExpectationNot self)

toBeAContract(_AddressExpectationNot self, string message)

toEqual(_Bytes32Expectation self, bytes32 expected)

toEqual(_Bytes32Expectation self, bytes32 expected, string message)

toEqual(_Bytes32ExpectationNot self, bytes32 expected)

toEqual(_Bytes32ExpectationNot self, bytes32 expected, string message)

toBeTheHashOf(_Bytes32Expectation self, bytes data)

toBeTheHashOf(_Bytes32Expectation self, bytes data, string message)

toBeTheHashOf(_Bytes32ExpectationNot self, bytes data)

toBeTheHashOf(_Bytes32ExpectationNot self, bytes data, string message)

toEqual(_BytesExpectation self, bytes expected)

toEqual(_BytesExpectation self, bytes expected, string message)

toEqual(_BytesExpectationNot self, bytes expected)

toEqual(_BytesExpectationNot self, bytes expected, string message)

toEqual(_StringExpectation self, string expected)

toEqual(_StringExpectation self, string expected, string message)

toEqual(_StringExpectationNot self, string expected)

toEqual(_StringExpectationNot self, string expected, string message)

toContain(_StringExpectation self, string contained)

toContain(_StringExpectation self, string contained, string message)

toContain(_StringExpectationNot self, string contained)

toContain(_StringExpectationNot self, string contained, string message)

toHaveLength(_StringExpectation self, uint256 expected)

toHaveLength(_StringExpectation self, uint256 expected, string message)

toHaveLength(_StringExpectationNot self, uint256 expected)

toHaveLength(_StringExpectationNot self, uint256 expected, string message)

toEqual(_UintExpectation self, uint256 expected)

toEqual(_UintExpectation self, uint256 expected, string message)

toEqual(_UintExpectationNot self, uint256 expected)

toEqual(_UintExpectationNot self, uint256 expected, string message)

toBeCloseTo(_UintExpectation self, uint256 expected, uint256 d)

toBeCloseTo(_UintExpectation self, uint256 expected, uint256 d, string message)

toBeLessThan(_UintExpectation self, uint256 expected)

toBeLessThan(_UintExpectation self, uint256 expected, string message)

toBeLessThanOrEqual(_UintExpectation self, uint256 expected)

toBeLessThanOrEqual(_UintExpectation self, uint256 expected, string message)

toBeGreaterThan(_UintExpectation self, uint256 expected)

toBeGreaterThan(_UintExpectation self, uint256 expected, string message)

toBeGreaterThanOrEqual(_UintExpectation self, uint256 expected)

toBeGreaterThanOrEqual(_UintExpectation self, uint256 expected, string message)

toEqual(_IntExpectation self, int256 expected)

toEqual(_IntExpectation self, int256 expected, string message)

toEqual(_IntExpectationNot self, int256 expected)

toEqual(_IntExpectationNot self, int256 expected, string message)

toBeCloseTo(_IntExpectation self, int256 expected, uint256 d)

toBeCloseTo(_IntExpectation self, int256 expected, uint256 d, string message)

toBeLessThan(_IntExpectation self, int256 expected)

toBeLessThan(_IntExpectation self, int256 expected, string message)

toBeLessThanOrEqual(_IntExpectation self, int256 expected)

toBeLessThanOrEqual(_IntExpectation self, int256 expected, string message)

toBeGreaterThan(_IntExpectation self, int256 expected)

toBeGreaterThan(_IntExpectation self, int256 expected, string message)

toBeGreaterThanOrEqual(_IntExpectation self, int256 expected)

toBeGreaterThanOrEqual(_IntExpectation self, int256 expected, string message)

toHaveReverted(_CallExpectation self)

toHaveReverted(_CallExpectation self, string message)

toHaveRevertedWith(_CallExpectation self, bytes4 expectedSelector)

toHaveRevertedWith(_CallExpectation self, bytes4 expectedSelector, string message)

toHaveRevertedWith(_CallExpectationNot self, bytes4 expectedSelector)

toHaveRevertedWith(_CallExpectationNot self, bytes4 expectedSelector, string message)

toHaveRevertedWith(_CallExpectation self, string error)

toHaveRevertedWith(_CallExpectation self, string error, string message)

toHaveRevertedWith(_CallExpectationNot self, string error)

toHaveRevertedWith(_CallExpectationNot self, string error, string message)

toHaveRevertedWith(_CallExpectation self, bytes expectedError)

toHaveRevertedWith(_CallExpectation self, bytes expectedError, string message)

toHaveRevertedWith(_CallExpectationNot self, bytes expectedError)

toHaveRevertedWith(_CallExpectationNot self, bytes expectedError, string message)

toHaveSucceeded(_CallExpectation self)

toHaveSucceeded(_CallExpectation self, string message)

toHaveEmitted(_CallExpectation self, string eventSig)

toHaveEmitted(_CallExpectation self, string eventSig, string message)

toHaveEmitted(_CallExpectation self, bytes32[1] topics)

toHaveEmitted(_CallExpectation self, bytes32[1] topics, string message)

toHaveEmitted(_CallExpectation self, bytes32[2] topics)

toHaveEmitted(_CallExpectation self, bytes32[2] topics, string message)

toHaveEmitted(_CallExpectation self, bytes32[3] topics)

toHaveEmitted(_CallExpectation self, bytes32[3] topics, string message)

toHaveEmitted(_CallExpectation self, bytes32[4] topics)

toHaveEmitted(_CallExpectation self, bytes32[4] topics, string message)

toHaveEmitted(_CallExpectation self, string eventSig, bytes data)

toHaveEmitted(_CallExpectation self, string eventSig, bytes data, string message)

toHaveEmitted(_CallExpectation self, string eventSig, bytes32[1] topics)

toHaveEmitted(_CallExpectation self, string eventSig, bytes32[1] topics, string message)

toHaveEmitted(_CallExpectation self, string eventSig, bytes32[2] topics)

toHaveEmitted(_CallExpectation self, string eventSig, bytes32[2] topics, string message)

toHaveEmitted(_CallExpectation self, string eventSig, bytes32[3] topics)

toHaveEmitted(_CallExpectation self, string eventSig, bytes32[3] topics, string message)

toHaveEmitted(_CallExpectation self, bytes32[1] topics, bytes data)

toHaveEmitted(_CallExpectation self, bytes32[1] topics, bytes data, string message)

toHaveEmitted(_CallExpectation self, bytes32[2] topics, bytes data)

toHaveEmitted(_CallExpectation self, bytes32[2] topics, bytes data, string message)

toHaveEmitted(_CallExpectation self, bytes32[3] topics, bytes data)

toHaveEmitted(_CallExpectation self, bytes32[3] topics, bytes data, string message)

toHaveEmitted(_CallExpectation self, bytes32[4] topics, bytes data)

toHaveEmitted(_CallExpectation self, bytes32[4] topics, bytes data, string message)

toHaveEmitted(_CallExpectation self, string eventSig, bytes32[1] topics, bytes data)

toHaveEmitted(_CallExpectation self, string eventSig, bytes32[1] topics, bytes data, string message)

toHaveEmitted(_CallExpectation self, string eventSig, bytes32[2] topics, bytes data)

toHaveEmitted(_CallExpectation self, string eventSig, bytes32[2] topics, bytes data, string message)

toHaveEmitted(_CallExpectation self, string eventSig, bytes32[3] topics, bytes data)

toHaveEmitted(_CallExpectation self, string eventSig, bytes32[3] topics, bytes data, string message)

toHaveEmitted(_CallExpectation self, string eventSig, bytes32[] topics, bytes data)

toHaveEmitted(_CallExpectation self, string eventSig, bytes32[] topics, bytes data, string message)

printMessage(string message)

AnyLib

value() → (bytes32)

check(bytes32 val) → (bool res)

Fe

Structs

Fe

struct Fe {
	string compilerPath
	string filePath
	string outputDir
	bool overwrite
}

fe

create() → (Fe)

Creates a new Fe struct with default values.

build(Fe self) → (CommandResult)

Builds a binary file from a .fe file.

toCommand(Fe self) → (Command)

Transforms a Fe struct to a Command struct.

setCompilerPath(Fe self, string compilerPath) → (Fe)

Sets the fe compiler path.

setFilePath(Fe self, string filePath) → (Fe)

Sets the fe file path to build.

setOutputDir(Fe self, string outputDir) → (Fe)

Sets the fe build command output directory.

setOverwrite(Fe self, bool overwrite) → (Fe)

Sets the fe build command overwrite flag.

getBytecode(Fe self, string contractName) → (BytesResult)

Obtains the bytecode of a compiled contract with contractName.

Fmt

Structs

Placeholder

struct Placeholder {
	uint256 start
	uint256 end
	Type t
	bytes mod
}

fmt

format(string template, bytes args) → (string)

Forks

Custom types

Fork

type Fork is uint256;

Holds a fork's id.

forksUnsafe

create(string nameOrEndpoint) → (Fork)

Create a new fork using the provided endpoint.

createAtBlock(string nameOrEndpoint, uint256 blockNumber) → (Fork)

Create a new fork using the provided endpoint at a given block number.

createBeforeTx(string nameOrEndpoint, bytes32 txHash) → (Fork)

Create a new fork using the provided endpoint at a state right before the provided transaction hash.

select(Fork self) → (Fork)

Set the provided fork as the current active fork.

active() → (Fork)

Get the current active fork.

setBlockNumber(Fork self, uint256 blockNumber) → (Fork)

Set the block number of the provided fork.

beforeTx(Fork self, bytes32 txHash) → (Fork)

Set the provided fork to the state right before the provided transaction hash.

persistBetweenForks(address self) → (address)

Make the state of the provided address persist between forks.

persistBetweenForks(address who1, address who2)

Make the state of the provided addresses persist between forks.

persistBetweenForks(address who1, address who2, address who3)

Make the state of the provided addresses persist between forks.

persistBetweenForks(address[] whos)

Make the state of the provided addresses persist between forks.

stopPersist(address who) → (address)

Revoke the persistent state of the provided address.

stopPersist(address[] whos)

Revoke the persistent state of the provided addresses.

isPersistent(address who) → (bool)

Check if the provided address is being persisted between forks.

allowCheatcodes(address who) → (address)

Allow cheatcodes to be used by the provided address in forking mode.

executeTx(bytes32 txHash)

Executes an existing transaction in the current active fork.

executeTx(Fork self, bytes32 txHash) → (Fork)

Executes an existing transaction in the provided fork.

Fs

Custom types

FsMetadataResult

type FsMetadataResult is bytes32;

Structs

FsMetadata

struct FsMetadata {
	bool isDir
	bool isSymlink
	uint256 length
	bool readOnly
	uint256 modified
	uint256 accessed
	uint256 created
}

Functions

Ok(FsMetadata value) → (FsMetadataResult)

fs

readFile(string path) → (StringResult)

Reads the file on path and returns its content as a StringResult.

readFileBinary(string path) → (BytesResult)

Reads the file on path and returns its content as a BytesResult.

projectRoot() → (StringResult)

Obtains the current project's root.

metadata(string fileOrDir) → (FsMetadataResult)

Obtains the metadata of the specified file or directory.

readLine(string path) → (StringResult)

Reads the next line of the file on path.

writeFile(string path, string data) → (EmptyResult)

Modifies the content of the file on path with data.

writeFileBinary(string path, bytes data) → (EmptyResult)

Modifies the content of the file on path with data.

writeLine(string path, string data) → (EmptyResult)

Adds a new line to the file on path.

closeFile(string path) → (EmptyResult)

Resets the state of the file on path.

removeFile(string path) → (EmptyResult)

Deletes the file on path.

copyFile(string origin, string target) → (EmptyResult)

Copies a file from origin to target.

moveFile(string origin, string target) → (EmptyResult)

Moves a file from origin to target.

fileExists(string path) → (BoolResult)

Checks if a file or directory exists.

getCode(string path) → (BytesResult)

Obtains the creation code from an artifact file located at path

getDeployedCode(string path) → (BytesResult)

Obtains the deployed code from an artifact file located at path

FsErrors

FailedToRead(string reason) → (Error)

FailedToReadLine(string reason) → (Error)

FailedToReadMetadata(string reason) → (Error)

FailedToGetProjectRoot(string reason) → (Error)

Forbidden(string reason) → (Error)

FailedToWrite(string reason) → (Error)

FailedToWriteLine(string reason) → (Error)

FailedToCloseFile(string reason) → (Error)

FailedToRemoveFile(string reason) → (Error)

FailedToGetCode(string reason) → (Error)

toFsMetadataResult(Error self) → (FsMetadataResult)

toEmptyResult(Error self) → (EmptyResult)

LibFsMetadataPointer

toFsMetadata(Pointer self) → (FsMetadata metadata)

toFsMetadataResult(Pointer self) → (FsMetadataResult ptr)

toPointer(FsMetadata self) → (Pointer ptr)

LibFsMetadataResult

isOk(FsMetadataResult self) → (bool)

isError(FsMetadataResult self) → (bool)

unwrap(FsMetadataResult self) → (FsMetadata val)

expect(FsMetadataResult self, string err) → (FsMetadata)

toError(FsMetadataResult self) → (Error)

toValue(FsMetadataResult self) → (FsMetadata val)

toPointer(FsMetadataResult self) → (Pointer)

Gas

gas

record(string name)

stopRecord(string name) → (uint256)

getRecord(string name) → (uint256, uint256)

used(string name) → (uint256)

Huff

Structs

Huffc

struct Huffc {
	string compilerPath
	string filePath
	string outputPath
	string mainName
	string constructorName
	bool onlyRuntime
	string[] constantOverrides
}

huff

create() → (Huffc)

compile(Huffc self) → (CommandResult)

toCommand(Huffc self) → (Command)

setCompilerPath(Huffc self, string compilerPath) → (Huffc)

setFilePath(Huffc self, string filePath) → (Huffc)

setOutputPath(Huffc self, string outputPath) → (Huffc)

setMainName(Huffc self, string mainName) → (Huffc)

setConstructorName(Huffc self, string constructorName) → (Huffc)

setOnlyRuntime(Huffc self, bool onlyRuntime) → (Huffc)

addConstantOverride(Huffc self, string const, bytes32 value) → (Huffc)

Invariants

Structs

FuzzSelector

struct FuzzSelector {
	address addr
	bytes4[] selectors
}

A struct that represents a Fuzz Selector

invariants

getState() → (State state)

Returns the state struct that contains the invariants related data

excludeContract(address newExcludedContract)

Excludes a contract

excludeContracts(address[] newExcludedContracts)

Excludes multiple contracts

excludeSender(address newExcludedSender)

Excludes a sender

excludeSenders(address[] newExcludedSenders)

Excludes multiple senders

excludeArtifact(string newExcludedArtifact)

Excludes an artifact

excludeArtifacts(string[] newExcludedArtifacts)

Excludes multiple artifacts

targetArtifact(string newTargetedArtifact)

Targets an artifact

targetArtifacts(string[] newTargetedArtifacts)

Targets multiple artifacts

targetArtifactSelector(FuzzSelector newTargetedArtifactSelector)

Targets an artifact selector

targetArtifactSelectors(FuzzSelector[] newTargetedArtifactSelectors)

Targets multiple artifact selectors

targetContract(address newTargetedContract)

Targets a contract

targetContracts(address[] newTargetedContracts)

Targets multiple contracts

targetSelector(FuzzSelector newTargetedSelector)

Targets a selector

targetSelectors(FuzzSelector[] newTargetedSelectors)

Targets multiple selectors

targetSender(address newTargetedSender)

Targets a sender

targetSenders(address[] newTargetedSenders)

Targets multiple senders

Json

Custom types

JsonResult

type JsonResult is bytes32;

Structs

JsonObject

struct JsonObject {
	string id
	string serialized
}

Functions

Ok(JsonObject value) → (JsonResult)

JsonError

Invalid() → (Error)

toJsonResult(Error self) → (JsonResult)

LibJsonObjectPointer

toJsonObject(Pointer self) → (JsonObject obj)

toJsonResult(Pointer self) → (JsonResult result)

toPointer(JsonObject obj) → (Pointer ptr)

LibJsonResult

isOk(JsonResult self) → (bool)

isError(JsonResult self) → (bool)

unwrap(JsonResult self) → (JsonObject val)

expect(JsonResult self, string err) → (JsonObject)

toError(JsonResult self) → (Error)

toValue(JsonResult self) → (JsonObject val)

toPointer(JsonResult self) → (Pointer)

json

getObject(JsonObject jsonObj, string key) → (bytes abiEncodedData)

Parses a json object struct by key and returns an ABI encoded value.

parse(JsonObject jsonObj) → (bytes abiEncodedData)

Parses a json object struct and returns an ABI encoded tuple.

isValid(string jsonObj) → (bool)

containsKey(JsonObject obj, string key) → (bool)

getUint(JsonObject obj, string key) → (uint256)

Parses the value of the key contained on jsonStr as uint256.

getUintArray(JsonObject obj, string key) → (uint256[])

Parses the value of the key contained on jsonStr as uint256[].

getInt(JsonObject obj, string key) → (int256)

Parses the value of the key contained on jsonStr as int256.

getIntArray(JsonObject obj, string key) → (int256[])

Parses the value of the key contained on jsonStr as int256[].

getBool(JsonObject obj, string key) → (bool)

Parses the value of the key contained on jsonStr as bool.

getBoolArray(JsonObject obj, string key) → (bool[])

Parses the value of the key contained on jsonStr as bool[].

getAddress(JsonObject obj, string key) → (address)

Parses the value of the key contained on jsonStr as address.

getAddressArray(JsonObject obj, string key) → (address[])

Parses the value of the key contained on jsonStr as address.

getString(JsonObject obj, string key) → (string)

Parses the value of the key contained on jsonStr as string.

getStringArray(JsonObject obj, string key) → (string[])

Parses the value of the key contained on jsonStr as string[].

getBytes(JsonObject obj, string key) → (bytes)

Parses the value of the key contained on jsonStr as bytes.

getBytesArray(JsonObject obj, string key) → (bytes[])

Parses the value of the key contained on jsonStr as bytes[].

getBytes32(JsonObject obj, string key) → (bytes32)

Parses the value of the key contained on jsonStr as bytes32.

getBytes32Array(JsonObject obj, string key) → (bytes32[])

Parses the value of the key contained on jsonStr as bytes32[].

getKeys(JsonObject obj, string key) → (string[])

getKeys(JsonObject obj) → (string[])

create() → (JsonObject)

Creates a new JsonObject struct.