assay

assay is a contract-verification-as-code tool.

pnpm add @cmichel/assay --ignore-scripts

Features

• Verification as code: The verification files are standard TypeScript files that come with full programmability.
• Bytecode validation: Compares deployment init code and deployed runtime bytecode against compiler artifact bytecode, with support for immutable value assertions.
• Full state assertions: Checks the full on-chain state by recomputing the storage root hash from the written assertions. This ensures that no hidden state variables exist besides your written assertions.
• Typed storage paths: Storage paths and values are derived from the artifact's storageLayout, including support for struct value types.
• Actionable diagnostics: Actionable failure diagnostics with slot-level & path-level storage diffs and highlighted expected/actual mismatches.
• Cached RPC responses: Caches the RPC responses if the block is pinned for faster revalidation.
• Works with standard RPCs: Running the verification works with standard public (archive) RPCs; no chain replay with costly RPCs like debug_traceTransaction required.

Example

See example.

import { encodeAbiParameters } from "viem";
import {
  defineCreationBytecodeLayout,
  defineDeployedBytecodeLayout,
  defineStorageLayout,
  validateEVM,
} from "@cmichel/assay";
import artifact from "./SkyOFTAdapter.js";

const storageLayout = defineStorageLayout(artifact.storageLayout);
const creationBytecodeLayout = defineCreationBytecodeLayout(artifact.bytecode);
const deployedBytecodeLayout = defineDeployedBytecodeLayout(artifact.deployedBytecode);
const initCodeMetadataDigestOffset = 20_523;

await validateEVM({
  deployment: {
    chain: "ethereum",
    address: "0x1e1D42781FC170EF9da004Fb735f56F0276d01B8",
    blockNumber: 25_253_198,
  },
  creation: {
    initCode: {
      layout: creationBytecodeLayout,
      source: {
        type: "transaction",
        hash: "0x9026755d5cd45724543d13e7c2f072fc80997bb0b9feb5c6e5bb4271407ee798",
      },
      assertions: () => ({
        constructorArgs: encodeAbiParameters(
          [{ type: "address" }, { type: "address" }, { type: "address" }],
          [
            "0xdc035d45d973e3ec169d2276ddab16f1e407384f", // _token
            "0x1a44076050125825900e736c501f859c50fe728c", // _lzEndpoint
            "0x12e85b7a985283bbff212a059e2d226397b78f95", // _delegate
          ],
        ),
        // Ignore only the top-level Solidity metadata IPFS digest in the init code.
        ignoredRegions: [{ offset: initCodeMetadataDigestOffset, length: 32 }],
      }),
    },
    runtimeCode: {
      layout: deployedBytecodeLayout,
      assertions: () => ({
        immutables: [
          {
            astId: "875",
            varName: "innerToken",
            value: "0xdc035d45d973e3ec169d2276ddab16f1e407384f",
          },
          {
            astId: "12372",
            varName: "endpoint",
            value: "0x1a44076050125825900e736c501f859c50fe728c",
          },
          {
            astId: "14194",
            varName: "decimalConversionRate",
            value: 1_000_000_000_000n,
          },
        ],
      }),
    },
  },
  storage: {
    layout: storageLayout,
    assertions: (s) => {
      s.add("_owner", "0xbe8e3e3618f7474f8cb1d074a26affef007e98fb");
      s.add("feeBalance", 2432794048422n);
      s.add("peers.30106", "0x0000000000000000000000004fec40719fd9a8ae3f8e20531669dec5962d2619");
      s.add("peers.30168", "0x9825dc0cbeaf22836931c00cb891592f0a96d0dc6a65a4c67992b01e0db8d122");
      s.add("enforcedOptions.30106.1", "0x0003010011010000000000000000000000000001fbd0");
      s.add("enforcedOptions.30106.2", "0x0003010011010000000000000000000000000001fbd0");
      s.add(
        "enforcedOptions.30168.1",
        "0x00030100210100000000000000000000000000030d40000000000000000000000000001f1df0",
      );
      s.add(
        "enforcedOptions.30168.2",
        "0x00030100210100000000000000000000000000030d40000000000000000000000000001f1df0",
      );
      s.add("outboundRateLimits.30106", {
        lastUpdated: 1778508083n,
        window: 86400n,
        amountInFlight: 0n,
        limit: 0n,
      });
      s.add("outboundRateLimits.30168", {
        lastUpdated: 1780569623n,
        window: 86400n,
        amountInFlight: 0n,
        limit: 5_000_000_000_000_000_000_000_000n,
      });
      s.add("inboundRateLimits.30106", {
        lastUpdated: 1778508083n,
        window: 86400n,
        amountInFlight: 0n,
        limit: 5_000_000_000_000_000_000_000_000n,
      });
      s.add("inboundRateLimits.30168", {
        lastUpdated: 1780569623n,
        window: 86400n,
        amountInFlight: 561_063_938_124_888_888_888_889n,
        limit: 5_000_000_000_000_000_000_000_000n,
      });
      s.add("pausers.0x38d1114b4ce3e079cc0f627df6ac2776b5887776", true);
    },
  },
});

FAQ:

1. How do I get the expected bytecode / storage layout / build artifacts of a contract?

   Run forge build --ast --build-info --extra-output storageLayout or the equivalent compilation command if the project is not using forge. Alternatively, ask the AI to create the storage layout for you.

2. Why does storage root validation fail if all asserted slots match?

   Because there is at least one nonzero-value live slot missing from the assertions.

3. How do I find missing nonzero-value storage slots?

   There is no single RPC call that returns all storage slots for a contract. You need to have access to an RPC that supports debug_traceTransaction or similar functions and replay the transactions looking for sstores; or use third-party tools that already did this for you like evmchronicle.

4. What's the fastest way to create a validation code file?

   The fastest way is to work backwards. Create the build artifacts, then ask your AI to create the validation file and work on it until it validates - there is a scaffold SKILL for that. Once you have a file that validates, check that the build artifacts were not changed and the written storage assertions are the expected ones.

5. How to set a custom RPC for verification?

   It first tries to read the RPC from the env var "<CHAIN_NAME>_RPC_URL", f.i., for mainnet it is "ETHEREUM_RPC_URL". If none is set, it falls back to a default RPC for that chain.