Hardhat Ethoko

Hardhat plugin in order to interact with Ethoko, warehouse for smart contract compilation artifacts.

Installation

Installation can be made using any package manager

pnpm install hardhat-ethoko
npm install hardhat-ethoko
yarn add hardhat-ethoko

Configuration

In the hardhat.config.ts/js file, one should import the hardhat-ethoko plugin and fill the Ethoko configuration.

import { HardhatUserConfig } from "hardhat/config";
...
import "hardhat-ethoko";

export const config: HardhatUserConfig = {
  ... // Existing configuration
  // Example configuration for Ethoko with AWS S3 as storage for compilation artifacts
  ethoko: {
    project: "doubtful-project", // Name of the project, used when pushing artifacts and as default for other commands
    pulledArtifactsPath: ".ethoko", // Local path for pulled artifacts, default to `.ethoko`
    typingsPath: ".ethoko-typings", // Local path for generated typings, default to `.ethoko-typings`
    compilationOutputPath: "./artifacts", // Local path for generated artifacts, allows to avoid providing --artifact-path for push/diff commands
    storageConfiguration: { // Configuration of the storage, see "Storage configurations"
      type: "aws",
      awsRegion: MY_AWS_REGION,
      awsBucketName: MY_AWS_S3_BUCKET,
      awsAccessKeyId: MY_AWS_ACCESS_KEY_ID,
      awsSecretAccessKey: MY_AWS_SECRET_ACCESS_KEY,
      // Optional IAM role assumption
      awsRole: {
        roleArn: MY_AWS_ROLE_ARN,
        externalId: MY_AWS_EXTERNAL_ID, // Optional, required if role policy enforces it
        sessionName: "ethoko-hardhat-session", // Optional, default is "ethoko-hardhat-session"
        durationSeconds: 3600, // Optional, 900-43200 (must be allowed by role)
      },
    },
    debug: false, // If true, all tasks are running with debug mode enabled, default to `false`
  },
}

It is recommended to add the folders for pulled artifacts and typings to the .gitignore file. They can be regenerated at any time.

Projects, tags and IDs

A unique ID, e.g. b5e41181986a, is derived for each compilation artifact. The ID is based on the content of the artifact.

A tag, e.g. 2026-02-02 or v1.2.3, can be associated to a compilation artifact when pushed.

A project, e.g. doubtful-project, will gather many compilation artifacts.

The project setup in the Hardhat Config will be used as

• target project when pushing new compilation artifacts,
• default project for pulling artifacts or other commands, different project can be specified for those commands.

Tasks

[!NOTE] The code snippets in this section uses npx but one can choose something else

An overview of the Ethoko tasks is exposed by running the ethoko task:

npx hardhat ethoko

Help about any task scopped under ethoko is available:

npx hardhat help ethoko push

Push

Push a local compilation artifact for the configured project to the storage, creating the remote artifact with its ID and optionally tagging it.

Only push the compilation artifact without an additional tag:

npx hardhat ethoko push

Or use a tag to associate the compilation artifact with it

npx hardhat ethoko push --tag 2026-02-02

If not setup in the configuration or need to be overriden, the path to the compilation artifact can be provided

# e.g. ./artifacts for Hardhat, ./out for Foundry, etc...
npx hardhat ethoko push --artifact-path ./path/to/artifacts

[!NOTE] Hardhat Ethoko will try to read the compilation artifact from the configured or provided path. If multiple choices are possible, it will ask the user to select one of them. One can avoid this prompt by providing the full path to the compilation artifact or ensure there is only one compilation artifact in the provided path.

Pull

Pull locally the missing artifacts from the configured storage.

One can pull all the artifacts from the configured project

npx hardhat ethoko pull

Or target a specific artifact using its tag or ID or another project:

npx hardhat ethoko pull --id b5e41181986a
npx hardhat ethoko pull --tag 2026-02-02
npx hardhat ethoko pull --tag v1.2.3 --project another-project

Typings

Once the artifacts have been pulled, one can generate the TypeScript typings based on the pulled projects.

npx hardhat ethoko typings

[!NOTE] If no projects have been pulled, one can still generate the default typings using this command. It may be helpful for those who do not care about the scripts involving Ethoko but want to be unblocked in case of missing files.

List artifacts

List the pulled compilation artifacts with their project.

npx hardhat ethoko artifacts

Inspect

Inspect a pulled compilation artifact to list contracts and metadata.

npx hardhat ethoko inspect --tag 2026-02-02
npx hardhat ethoko inspect --id b5e41181986a

Target a different project:

npx hardhat ethoko inspect --project another-project --tag 2026-02-02

Output JSON for scripting:

npx hardhat ethoko inspect --tag 2026-02-02 --json

Export

Export a contract artifact from a locally pulled artifact.

npx hardhat ethoko export --tag 2026-02-02 --contract Counter
npx hardhat ethoko export --id b5e41181986a --contract contracts/Counter.sol:Counter

Write the contract artifact to a file (overwrites if it exists):

npx hardhat ethoko export --tag 2026-02-02 --contract Counter --output ./Counter.json

Pipe the artifact to another tool:

npx hardhat ethoko export --tag 2026-02-02 --contract Counter | jq

Export the ABI as a TypeScript const:

echo "export const MY_ABI = $(npx hardhat ethoko export --tag 2026-02-02 --contract Counter | jq .abi) as const;" > ./my-abi.ts

Restore

Restore original compilation artifacts from a locally pulled artifact to a local directory.

npx hardhat ethoko restore --id b5e41181986a --output ./restored
npx hardhat ethoko restore --tag 2026-02-02 --output ./restored
npx hardhat ethoko restore --tag v1.2.3 --project another-project --output ./restored

[!NOTE] The artifact must be pulled locally before restoring, and the output directory must be empty unless the --force flag is used.

Diff

Compare a local compilation artifacts with an existing compilation artifact and print the contracts for which differences have been found.

npx hardhat ethoko diff --tag 2026-02-02

npx hardhat ethoko diff --id b5e41181986a

If not setup in the configuration or need to be overriden, the path to the compilation artifact can be provided

# e.g. ./artifacts for Hardhat, ./out for Foundry, etc...
npx hardhat ethoko diff --tag 2026-02-02 --artifact-path ./path/to/artifacts

Using the typings

The typings are exposed in order to help the developer retrieve easily and safely a contract artifact (ABI, bytecode, etc...).

There are two available utils in order to retrieve a contract artifact, it would depend on the task at hand:

• start with a contract, select one of its available tags

import { project } from "../.ethoko-typings";

const artifact = await project("doubtful-project")
  .contract("src/path/to/my/contract.sol:Foo")
  .getArtifact("2026-02-02");

• start with a tag, select a contract within it

import { project } from "../.ethoko-typings";

const artifact = await project("doubtful-project")
  .tag("2026-02-02")
  .getContractArtifact("src/path/to/my/contract.sol:Foo");

If typings have been generated from existing projects, the inputs of the utils will be strongly typed and wrong project, tags or contracts names will be detected.

In case there are no projects or the projects have not been pulled, the generated typings are made in such a way that strong typecheck disappears and any string can be used with the helper functions.

Retrieve full compilation artifact

The full compilation artifact of a tag can be retrieved using the project("doubtful-project").tag("2026-02-02").getCompilationArtifact method.

Example with hardhat-deploy v2

An example can be made with the hardhat-deploy plugin for deploying a released smart contract.

The advantage of this deployment is that it only works with frozen artifacts. New development will never have an impact on it.

import { deployScript } from "../rocketh/deploy.js";
import { project } from "../.ethoko-typings";

export default deployScript(
  async ({ deploy, namedAccounts }) => {
    const { deployer } = namedAccounts;

    const fooArtifact = await project("doubtful-project")
      .tag("2026-02-04")
      .getContractArtifact("src/Foo.sol:Foo");

    if (!fooArtifact.metadata)
      throw new Error("Metadata is required for hardhat-deploy v2");

    await deploy(`Foo@2026-02-04`, {
      account: deployer,
      artifact: {
        // Hardhat Deploy works with the abitype dependency, strongly typing the ABI. It is not yet available here.
        // eslint-disable-next-line @typescript-eslint/no-explicit-any
        abi: fooArtifact.abi as any,
        bytecode: `0x${fooArtifact.evm.bytecode.object}`,
        metadata: fooArtifact.metadata,
      },
    });
  },
  { tags: ["Foo", "Foo_deploy", "2026-02-04"] },
);

Storage configurations

Ethoko supports AWS S3 and local filesystem storage providers.

AWS S3

Compilation artifacts are stored in an AWS S3 bucket.

Before using Ethoko with AWS S3, one need to create an S3 bucket and have AWS credentials with access to it. The configuration requires:

• awsRegion: AWS region where the S3 bucket is located
• awsBucketName: Name of the S3 bucket
• awsAccessKeyId: AWS access key ID of the credentials
• awsSecretAccessKey: AWS secret access key of the credentials.

Optionally, you can assume an IAM role using the provided credentials:

• awsRole.roleArn: ARN of the IAM role to assume
• awsRole.externalId: Optional external ID for cross-account role assumption
• awsRole.sessionName: Optional role session name (default: ethoko-hardhat-session)
• awsRole.durationSeconds: Optional session duration in seconds (900-43200)

Make sure the credentials used have the right permissions to read and write objects in the S3 bucket.

When awsRole is provided, Ethoko assumes the role using the access key and secret key, and uses the temporary credentials for S3 operations. The credentials are cached in memory for the duration of the task.

It is possible to use a single bucket for multiple projects, Ethoko will handle the organization of the artifacts within the bucket.

Local filesystem

The local filesystem provider stores artifacts in a local directory, making it a good fit for lightweight organizations or small teams that want a simpler setup while keeping proper versioning of compilation artifacts.

This storage is compatible with sharing through version control (commit the storage directory) or a shared drive.

Configuration example:

storageConfiguration: {
  type: "local",
  path: "./ethoko-storage",
}

Use this provider when you want to keep the setup light and local while still tracking versions of artifacts across your team.

Integration examples

The monorepo contains integration examples that can be used as references.

Contributing

See CONTRIBUTING.md for test and development guidelines.