Introduction

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

Set its prt option to also generate code for the PRT (Permissionless Refereed Tournaments) contracts from the dave repository.

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/client and @cartesi/react themselves for their code generation.

Installation

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

Usage

Add rollupsContracts to your wagmi.config.ts. With no options, it uses the tarballs of the rollups-contracts v3.0.0-alpha.10 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.

Devnet addresses

Besides the supported livenets, the addresses cover the local devnet (chain 31337), read from the release's anvil tarball — the same tarball that carries the anvil state dump the devnet is started from. That is also where the devnet-only test tokens (TestFungibleToken, TestNonFungibleToken, TestMultiToken, TestUsdc) and the devnet USD withdrawal output builder are deployed.

The core contracts are deployed deterministically, so their devnet address is the same as on every livenet and they still collapse to a single address.

To leave the devnet out, set anvil to false:

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

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.10";
const releaseUrl = `https://github.com/cartesi/rollups-contracts/releases/download/v${version}`;
 
export default defineConfig({
    out: "src/generated.ts",
    plugins: [
        rollupsContracts({
            artifacts: {
                url: `${releaseUrl}/cartesi-rollups-contracts-${version}-artifacts.tar.gz`,
                sha256: "5213ce59d0f5a1c4fef4ebf17b6ef999be709c32b4b94511c320729bb2afa959",
            },
            deployments: {
                url: `${releaseUrl}/cartesi-rollups-contracts-${version}-deployment-addresses.tar.gz`,
                sha256: "ba92d98c5f1ccbc3edf3b05e3717dc7292f56187b363f86d2569d00b6eedf4b5",
            },
        }),
    ],
});

Tarballs are downloaded on every run and extracted to a temporary directory that is removed once the contracts have been read, so code generation needs network access.

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