Introduction

@cartesi/wagmi-plugin is a Wagmi CLI plugin that generates code for the Cartesi Rollups smart contracts directly from an official release: ABIs come from the foundry build artifacts tarball, and deployment addresses from the deployment addresses tarball.

Combined with other Wagmi CLI plugins, it can generate fully typed viem contract actions or React hooks for the Cartesi contracts. It is the tool used by @cartesi/viem and @cartesi/wagmi themselves for their code generation.

Installation

Add the plugin and the Wagmi CLI as development dependencies of your project.

Usage

Add the plugin to your wagmi.config.ts. With no options, it uses the tarballs of the rollups-contracts v3.0.0-alpha.6 GitHub release, verified against known SHA-256 hashes.

import { rollupsContracts } from "@cartesi/wagmi-plugin";
import { defineConfig } from "@wagmi/cli";
 
export default defineConfig({
    out: "src/generated.ts",
    plugins: [rollupsContracts()],
});

Then run code generation:

pnpm wagmi generate

The generated file exports one ABI per contract, plus its deployment address on every supported chain: a single address when it is identical across chains, or a per-chain record otherwise.

Using a different release

To generate code from another rollups-contracts release, point artifacts and deployments at that release's tarballs. Each accepts a plain URL string, or an object with an expected SHA-256 hash of the tarball for integrity verification (recommended).

import { rollupsContracts } from "@cartesi/wagmi-plugin";
import { defineConfig } from "@wagmi/cli";
 
const version = "3.0.0-alpha.6";
const releaseUrl = `https://github.com/cartesi/rollups-contracts/releases/download/v${version}`;
 
export default defineConfig({
    out: "src/generated.ts",
    plugins: [
        rollupsContracts({
            artifacts: {
                url: `${releaseUrl}/rollups-contracts-${version}-artifacts.tar.gz`,
                sha256: "ad1e0880766d25419fc6da1858ea4e7b9074b400e9d9ef68da88b12f4a8bba45",
            },
            deployments: {
                url: `${releaseUrl}/rollups-contracts-${version}-deployment-addresses.tar.gz`,
                sha256: "bd6ee9b339e0541ce464ea3368e5e70595627b35fe0a68c6f5e044ef433ab895",
            },
        }),
    ],
});

Tarballs are downloaded and extracted to the operating system temporary directory and cached across runs, so repeated code generation does not download them again.

Selecting contracts

Use include and exclude to select which contracts are generated. Both accept contract names or regular expressions, and apply to every contract in the artifacts, whether it has a deployment or not:

• Neither defined: all contracts are included.
• Only include: only the matching contracts are included.
• Only exclude: all contracts are included except the matching ones.
• Both: include is applied first, then exclude.

For example, to generate only the Inputs and Outputs contracts:

import { rollupsContracts } from "@cartesi/wagmi-plugin";
import { defineConfig } from "@wagmi/cli";
 
export default defineConfig({
    out: "src/generated.ts",
    plugins: [
        rollupsContracts({
            include: ["Inputs", "Outputs"],
        }),
    ],
});

Or to generate all portal contracts except the interfaces:

import { rollupsContracts } from "@cartesi/wagmi-plugin";
import { defineConfig } from "@wagmi/cli";
 
export default defineConfig({
    out: "src/generated.ts",
    plugins: [
        rollupsContracts({
            include: [/Portal$/],
            exclude: [/^I[A-Z]/],
        }),
    ],
});

Generating React hooks

Compose the plugin with the Wagmi CLI react plugin to generate React hooks for the Cartesi contracts.

import { rollupsContracts } from "@cartesi/wagmi-plugin";
import { defineConfig } from "@wagmi/cli";
import { react } from "@wagmi/cli/plugins";
 
export default defineConfig({
    out: "src/generated.ts",
    plugins: [rollupsContracts(), react()],
});

Options