@marigoldlabs/web3-tester 0.1.1 → 0.4.1

package/.env.example

@@ -1,27 +1,36 @@
-# App under test
-DAPP_URL=https://v4.fjordfoundry.com
-
-# Local Anvil
+# --- Library: local Anvil (used by `npm test`) ---
 ANVIL_RUNTIME=binary
 ANVIL_EXECUTABLE=anvil
 ANVIL_DOCKER_IMAGE=ghcr.io/foundry-rs/foundry:latest
 ANVIL_HOST=127.0.0.1
-ANVIL_PORT=8545
+# Anvil refuses to bind beyond loopback (its admin RPC is unauthenticated)
+# unless this is explicitly set to true.
+ANVIL_ALLOW_NON_LOOPBACK=false
+# Worker base port; worker index is added for isolation. Defaults to 8645 so
+# it never collides with a developer-run node on 8545.
+ANVIL_PORT=8645
 ANVIL_CHAIN_ID=31337
 ANVIL_FORK_URL=
 ANVIL_SILENT=true
 
-# Live Sepolia QA
+# --- Library: live-chain fixtures ---
 # Never commit a real value here. Set it only in your shell or CI secret store.
-FJORD_PRIVATE_KEY=
-SEPOLIA_RPC_URL=
+WEB3_TESTER_PRIVATE_KEY=
+WEB3_TESTER_RPC_URL=
+
+# --- Real-wallet (MetaMask extension) mode ---
+WEB3_TESTER_METAMASK_VERSION=
+WEB3_TESTER_REAL_WALLET_EXTENSION_PATH=
+WEB3_TESTER_REAL_WALLET_PROFILE_DIR=
+WEB3_TESTER_REAL_WALLET_PASSWORD=
+WEB3_TESTER_REAL_WALLET_SECRET_RECOVERY_PHRASE=
+# Required choice for real-wallet runs: true or false (no default). Headed
+# (false) is the fully validated mode; headless needs the full Chromium
+# binary (npx playwright install chromium).
+WEB3_TESTER_REAL_WALLET_HEADLESS=
+# Set true to run the opt-in real-MetaMask smoke suite.
+WEB3_TESTER_REAL_WALLET_SMOKE=
 
-# Explicit live-mutation gates
-FJORD_RUN_TRANSACTIONS=false
-FJORD_MUTATE_STATE=false
-FJORD_PUBLISH_SALES=false
-FJORD_ADMIN_MUTATE=false
-FJORD_QA_RUN_ID=
-FJORD_RESUME_DRAFT_NAME=
-FJORD_PROJECT_TOKEN_ADDRESS=
-FJORD_EXPLORE_SALE_CREATE=false
+# --- WalletConnect simulation (opt-in relay suite) ---
+# Reown project id; needed only for the './walletconnect' relay tests.
+WEB3_TESTER_WC_PROJECT_ID=

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Marigold Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -8,16 +8,16 @@ The injected fixtures test dApp behavior with a programmable EIP-1193 provider.
 
 - Playwright fixtures that start one Anvil node per worker for parallel-safe local EVM tests.
 - Automatic `evm_snapshot` and `evm_revert` around every wallet test.
-- A programmable `MockWalletController` for approval, rejection, disconnects, account changes, and network-change events.
-- EIP-6963 provider announcements for wallet selector testing.
+- A programmable `MockWalletController` for approval, rejection, pending-approval holds, disconnects, account changes, and network-change events, with transaction recording (`sentTransactions`, `waitForNextTransaction`).
+- EIP-6963 provider announcements (one distinct provider object per wallet) for wallet selector testing.
 - Viem-backed chain helpers for impersonation, balance setup, time travel, and block mining.
-- Optional live-chain fixtures for controlled Sepolia QA with a runtime-only private key.
-- Real MetaMask launch, profile resolution, unlock/import, dapp connection, signature confirmation, transaction confirmation, and token approval helpers.
-- Fjord v4 QA specs and reports that document the current state of `https://v4.fjordfoundry.com`.
+- Optional live-chain fixtures for controlled testnet QA with a runtime-only private key (`createLiveFixtures` for custom chains/env names).
+- Optional WalletConnect/AppKit simulation (`@marigoldlabs/web3-tester/walletconnect`): a headless WC v2 wallet peer that pairs with the dapp's QR modal and answers every request through the same wallet gating — needs the optional `@walletconnect/*` peers and a Reown project id.
+- Real MetaMask mode: pinned-version extension download (`prepareMetaMaskExtension`), one-time onboarding into a cached profile with disposable per-test clones (`buildWalletProfile`/`cloneWalletProfile`), Playwright fixtures (`@marigoldlabs/web3-tester/real-wallet-fixtures`), wallet-side network add/switch, dapp connection, signature/transaction confirmation and rejection, and token approval helpers — validated end to end by an opt-in smoke suite against the pinned MetaMask build.
 
 ## Install In A Consumer App
 
-From the Fjord v4 package, install this repo as a dev dependency:
+Install as a dev dependency:
 
 ```bash
 npm install --save-dev @marigoldlabs/web3-tester
@@ -41,34 +41,93 @@ test('user can submit a wallet transaction', async ({ page, wallet }) => {
 });
 ```
 
-For live Sepolia tests, import the live fixture instead:
+> Note: fixtures are lazy. The provider is only injected when a test
+> references the `wallet` fixture — a test that destructures only `page`
+> will have no `window.ethereum`.
+
+Testing pending-approval UI and rejection paths:
+
+```ts
+test('shows a pending state until the user confirms', async ({ page, wallet }) => {
+  const held = wallet.holdNextRequest('eth_sendTransaction');
+  await page.getByRole('button', { name: /swap/i }).click();
+  await expect(page.getByText(/confirm in your wallet/i)).toBeVisible();
+
+  (await held).approve();
+  await expect(page.getByText(/success/i)).toBeVisible();
+});
+```
+
+For live testnet tests, import the live fixture (Sepolia by default; use
+`createLiveFixtures({ chain })` for other chains):
 
 ```ts
 import { expect, test } from '@marigoldlabs/web3-tester/live-fixtures';
 
 test('signs in through SIWE on Sepolia', async ({ page, wallet }) => {
   await page.goto('/');
+
+  // Live wallets are deny-by-default: arm each prompt before triggering it.
+  wallet.approveNext('eth_requestAccounts');
   await page.getByRole('button', { name: /connect/i }).click();
+
+  wallet.approveNext('personal_sign');
+  await page.getByRole('button', { name: /sign in/i }).click();
+
   await expect(page.getByText(wallet.primaryAccount.slice(0, 6))).toBeVisible();
 });
 ```
 
-For fully in-UI real wallet tests, launch MetaMask through the package:
+To deliberately auto-approve a whole test instead, use
+`test.use({ liveOptions: { walletOptions: { autoApprove: true } } })`.
+
+For fully in-UI real wallet tests, use the real-wallet fixtures. The pinned
+MetaMask build is downloaded automatically, onboarding runs once into a
+cached profile, and every test gets a disposable clone of that profile:
+
+```ts
+import { expect, test } from '@marigoldlabs/web3-tester/real-wallet-fixtures';
+
+test.use({
+  realWalletOptions: {
+    setup: { seedPhrase: process.env.WEB3_TESTER_REAL_WALLET_SECRET_RECOVERY_PHRASE },
+    baseURL: 'https://app.example.com',
+    // Required: pick headed or headless explicitly (or set
+    // WEB3_TESTER_REAL_WALLET_HEADLESS). Headed is the fully validated mode.
+    headless: false,
+  },
+});
+
+test('confirms a real MetaMask transaction', async ({ page, realWallet }) => {
+  await realWallet.addNetwork({
+    name: 'Anvil Local',
+    rpcUrl: 'http://127.0.0.1:8645',
+    chainId: 31337,
+    symbol: 'ETH',
+  });
+  await realWallet.switchNetwork('Anvil Local');
+
+  await page.goto('/');
+  await page.getByRole('button', { name: /connect/i }).click();
+  await realWallet.connectToDapp();
+
+  await page.getByRole('button', { name: /swap/i }).click();
+  await realWallet.confirmTransaction();
+});
+```
+
+The imperative API remains available for custom setups (preconfigured
+profiles, attaching to a real Chrome profile):
 
 ```ts
 import { launchRealWallet } from '@marigoldlabs/web3-tester/real-wallet';
+import { prepareMetaMaskExtension } from '@marigoldlabs/web3-tester/metamask-extension';
 
 const wallet = await launchRealWallet({
-  baseURL: 'https://v4.fjordfoundry.com',
-  expectedAddress: process.env.FJORD_REAL_WALLET_ADDRESS,
-  extensionPath: process.env.FJORD_REAL_WALLET_EXTENSION_PATH as string,
-  profileDir: process.env.FJORD_REAL_WALLET_PROFILE_DIR as string,
-  setup: process.env.FJORD_REAL_WALLET_PASSWORD
-    ? {
-        password: process.env.FJORD_REAL_WALLET_PASSWORD,
-        seedPhrase: process.env.FJORD_REAL_WALLET_SECRET_RECOVERY_PHRASE,
-      }
-    : undefined,
+  extensionPath: await prepareMetaMaskExtension(),
+  profileDir: process.env.WEB3_TESTER_REAL_WALLET_PROFILE_DIR as string,
+  setup: { seedPhrase: process.env.WEB3_TESTER_REAL_WALLET_SECRET_RECOVERY_PHRASE },
+  headless: false,
 });
 
 await wallet.connectToDapp();
@@ -77,6 +136,20 @@ await wallet.confirmTransaction();
 await wallet.close();
 ```
 
+MetaMask version pinning: selectors are maintained against
+`DEFAULT_METAMASK_VERSION` (currently 13.34.1, current MetaMask) and validated
+by the opt-in smoke suite (`npm run smoke:real-wallet`), which runs the full
+journey — onboarding, add/switch network, connect, sign, send, reject — plus
+the account/token/settings surface against the real extension. The UI
+generation (13.x "multichain" vs the older 12.x) is an explicit configuration,
+derived from the extension manifest at launch and overridable via the
+`generation` option: only the configured generation's selectors are driven —
+the other generation is never probed as a fallback. Set
+`WEB3_TESTER_METAMASK_VERSION` to pin a specific build (e.g. `12.23.1`; 12.x
+is supported on a best-effort validation cadence — 13.x gates releases). Bump
+the pin deliberately and re-run the smoke suite, since MetaMask UI selectors
+can drift between releases.
+
 ## Local Development
 
 ```bash
@@ -84,7 +157,8 @@ npm install
 npx playwright install chromium
 npm run typecheck
 npm run build
-npm test
+npm test          # hermetic library tests (needs anvil)
+npm run smoke:real-wallet  # opt-in real-MetaMask smoke suite (headed)
 ```
 
 Foundry's `anvil` executable must be available on `PATH`, or set `ANVIL_EXECUTABLE`.
@@ -117,26 +191,25 @@ Copy `.env.example` for local reference. Do not commit real private keys.
 
 | Variable | Default | Purpose |
 | --- | --- | --- |
-| `DAPP_URL` | `https://v4.fjordfoundry.com` | Playwright base URL for app tests. |
 | `ANVIL_EXECUTABLE` | `anvil` | Path to the Anvil binary. |
 | `ANVIL_RUNTIME` | `binary` | Set to `docker` to run Anvil through Docker Desktop. |
 | `ANVIL_DOCKER_IMAGE` | `ghcr.io/foundry-rs/foundry:latest` | Docker image used when `ANVIL_RUNTIME=docker`. |
-| `ANVIL_HOST` | `127.0.0.1` | Host for worker Anvil RPC endpoints. |
-| `ANVIL_PORT` | `8545` | Base port. Playwright worker index is added for isolation. |
+| `ANVIL_HOST` | `127.0.0.1` | Host for worker Anvil RPC endpoints. Non-loopback hosts are refused unless `ANVIL_ALLOW_NON_LOOPBACK=true`. |
+| `ANVIL_ALLOW_NON_LOOPBACK` | `false` | Explicit opt-in to bind Anvil beyond loopback (exposes its unauthenticated admin RPC to the network). |
+| `ANVIL_PORT` | `8645` | Base port (worker index is added for isolation). Defaults off 8545 so a developer-run dev node never collides. |
 | `ANVIL_CHAIN_ID` | `31337` | Chain ID exposed by local Anvil and the injected provider. |
 | `ANVIL_FORK_URL` | unset | Optional fork RPC URL. |
 | `ANVIL_SILENT` | `true` | Set to `false` to stream Anvil logs. |
-| `FJORD_PRIVATE_KEY` | unset | Runtime-only private key for live Sepolia QA. |
-| `SEPOLIA_RPC_URL` | Viem default | Optional Sepolia RPC URL for live tests. |
-| `FJORD_RUN_TRANSACTIONS` | unset | Must be `true` to run live transaction-spending tests. |
-| `FJORD_MUTATE_STATE` | unset | Must be `true` to deploy QA tokens or create sale drafts. |
-| `FJORD_PUBLISH_SALES` | unset | Must be `true` to attempt live sale publishing. |
-| `FJORD_ADMIN_MUTATE` | unset | Must be `true` to attempt admin mutation tests. |
-| `FJORD_REAL_WALLET_EXTENSION_PATH` | unset | Path to the unpacked MetaMask extension for real-wallet tests. |
-| `FJORD_REAL_WALLET_PROFILE_DIR` | unset | Persistent Chromium user-data directory, or a Chrome profile directory such as `Profile 1`. |
-| `FJORD_REAL_WALLET_ADDRESS` | unset | Optional expected account address checked after unlock/import. |
-| `FJORD_REAL_WALLET_PASSWORD` | unset | Optional MetaMask password used to unlock or import the profile. |
-| `FJORD_REAL_WALLET_SECRET_RECOVERY_PHRASE` | unset | Optional seed phrase used only when MetaMask opens on onboarding. |
+| `WEB3_TESTER_PRIVATE_KEY` | unset | Runtime-only private key for live-chain fixtures. |
+| `WEB3_TESTER_RPC_URL` | Viem default | Optional RPC URL for live fixtures (`SEPOLIA_RPC_URL` legacy alias). |
+| `WEB3_TESTER_METAMASK_VERSION` | pinned default | MetaMask release downloaded by `prepareMetaMaskExtension`. |
+| `WEB3_TESTER_REAL_WALLET_EXTENSION_PATH` | auto-download | Path to an unpacked MetaMask extension (skips the download). |
+| `WEB3_TESTER_REAL_WALLET_PROFILE_DIR` | profile cache | Explicit persistent Chromium user-data directory, or a Chrome profile directory such as `Profile 1`. Disables the per-test profile cache. |
+| `WEB3_TESTER_REAL_WALLET_PASSWORD` | deterministic test password | MetaMask password used to unlock profiles. |
+| `WEB3_TESTER_REAL_WALLET_SECRET_RECOVERY_PHRASE` | unset | Seed phrase used to build the cached real-wallet profile. |
+| `WEB3_TESTER_REAL_WALLET_HEADLESS` | none — explicit choice required | `true`/`false`. Real-wallet launches refuse to guess: pick headed (fully validated) or headless (needs the full Chromium from `npx playwright install chromium`) here or via the `headless` option. |
+| `WEB3_TESTER_REAL_WALLET_SMOKE` | unset | Set `true` to run the real-MetaMask smoke suite (`npm run smoke:real-wallet`). |
+| `WEB3_TESTER_WC_PROJECT_ID` | unset | Reown project id; set to run the opt-in WalletConnect relay suite. |
 
 ## Package Surface
 
@@ -146,6 +219,8 @@ The installable package exports:
 - `@marigoldlabs/web3-tester/fixtures`
 - `@marigoldlabs/web3-tester/live-fixtures`
 - `@marigoldlabs/web3-tester/real-wallet`
+- `@marigoldlabs/web3-tester/real-wallet-fixtures`
+- `@marigoldlabs/web3-tester/metamask-extension`
 - `@marigoldlabs/web3-tester/anvil`
 - `@marigoldlabs/web3-tester/mock-wallet-controller`
 - `@marigoldlabs/web3-tester/private-key-rpc-client`
@@ -159,6 +234,11 @@ await chain.impersonateAccount('0x0000000000000000000000000000000000000001');
 await chain.setBalance(wallet.primaryAccount, 10_000n * 10n ** 18n);
 await chain.fastForward(7 * 24 * 60 * 60);
 await chain.mine(3);
+
+// Token seeding and deployment (forge-style cheatcodes):
+const token = await chain.deployErc20({ symbol: 'USDX', decimals: 6 });
+await chain.dealErc20(token.address, wallet.primaryAccount, 5_000_000_000n);
+// dealErc20 also works on ANVIL_FORK_URL forks against real mainnet tokens.
 ```
 
 ## Wallet Control
@@ -167,8 +247,39 @@ await chain.mine(3);
 await wallet.simulateRejection('eth_sendTransaction');
 await wallet.disconnect();
 await wallet.reconnect();
-await wallet.setAccounts(['0x0000000000000000000000000000000000000001']);
+// Accounts are validated against the node's signers — use chain.accounts()
+// entries (or chain.impersonateAccount(addr) first for send-only flows).
+const [, second] = await chain.accounts();
+await wallet.setAccounts([second]);
+await wallet.switchAccount(second); // reorders + emits accountsChanged
 await wallet.switchNetwork(11155111);
+
+// Pending-approval simulation and transaction assertions:
+const held = wallet.holdNextRequest('personal_sign');
+// ... trigger the dapp action, assert the pending UI ...
+(await held).reject('User changed their mind.');
+
+const txPromise = wallet.waitForNextTransaction();
+// ... trigger the dapp action ...
+const hash = await txPromise;
+```
+
+Dapp-initiated `wallet_switchEthereumChain` follows MetaMask semantics: it
+throws 4902 for chains the wallet does not know; chains become known via
+`wallet_addEthereumChain` or a test-driven `wallet.switchNetwork(...)`.
+
+Multi-account and multi-user testing:
+
+```ts
+// Start connected with three anvil accounts:
+test.use({ walletOptions: { accountIndexes: [0, 1, 2] } });
+
+// Two users, one chain — seller lists, buyer purchases:
+test('buyer sees the listing', async ({ page, wallet, createUser }) => {
+  const buyer = await createUser(); // own context + page, anvil account #1
+  await buyer.page.goto('/listings/1');
+  await buyer.page.getByRole('button', { name: 'Buy' }).click();
+});
 ```
 
 ## Multiple Wallet Selectors
@@ -190,16 +301,32 @@ test.use({
 | Path | Purpose |
 | --- | --- |
 | `src/` | Reusable package source. |
-| `tests/provider-injection.spec.ts` | Harness self-tests. |
-| `tests/fjord*.spec.ts` | Fjord v4 public, live, and mutation QA specs. |
-| `docs/` | Dependency, API, architecture, and Fjord QA documentation. |
+| `tests/` (library project) | Hermetic harness self-tests: `anvil`, `live-fixtures`, `mock-wallet`, `private-key-rpc-client`, `provider-injection`, `real-wallet`, `real-wallet-smoke` (opt-in). |
+| `docs/` | API, architecture, and roadmap documentation. |
 | `examples/` | Copyable consumer-app snippets. |
-| `reports/` | Current Fjord v4 QA reports. |
 
 ## Safety Model
 
-- Local tests use deterministic Anvil accounts only.
+- Local tests use deterministic Anvil accounts only, and Anvil refuses to
+  bind beyond loopback unless `ANVIL_ALLOW_NON_LOOPBACK=true` is set — its
+  admin RPC (impersonation, `setBalance`, the fork URL) is unauthenticated.
 - Live tests require explicit environment variables and never store private keys in source.
+- Live wallets are deny-by-default: signing, sending (including
+  `eth_sendRawTransaction`), and wallet prompts (`eth_requestAccounts`
+  included, even though the wallet starts pre-connected) throw `4001` until
+  the test arms them — `wallet.approveNext(methods?, match?)` per request, or
+  `wallet.autoApprove(true)` /
+  `test.use({ liveOptions: { walletOptions: { autoApprove: true } } })` as a
+  deliberate whole-test opt-in. So page scripts — including third-party
+  includes on the dapp under test — cannot spend or sign unprompted.
+- When Playwright's `baseURL` is configured, the live provider is
+  origin-scoped to it: out-of-scope frames get no `window.ethereum` at all
+  and the RPC bridge refuses them with `4100`. Override with
+  `allowedOrigins`; without a `baseURL`, every frame is served.
+- `PrivateKeyRpcClient` refuses chains that are not testnets or local dev
+  chains unless constructed with `allowMainnet: true`, and verifies the RPC
+  endpoint's `eth_chainId` matches the configured chain before the first
+  broadcast (`eth_sendTransaction` / `eth_sendRawTransaction`).
 - Real-wallet tests use a persistent browser profile and keep extension-side automation inside this package.
 - Mutation tests are skipped unless their opt-in flag is set.
 - Published reports redact secrets and record transaction hashes only when useful for auditability.
@@ -207,7 +334,6 @@ test.use({
 ## More Documentation
 
 - [docs/API.md](docs/API.md)
+- [docs/ROADMAP.md](docs/ROADMAP.md)
 - [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)
-- [docs/CONSUMING_FROM_FJORD.md](docs/CONSUMING_FROM_FJORD.md)
-- [docs/FJORD_LIVE_QA.md](docs/FJORD_LIVE_QA.md)
 - [docs/RELEASE_CHECKLIST.md](docs/RELEASE_CHECKLIST.md)

package/dist/anvil.d.ts

@@ -1,5 +1,56 @@
-import { type Address, type Chain, type Hex, type PublicActions, type TestClient, type Transport, type WalletActions } from 'viem';
+import { type Abi, type Address, type Chain, type Hex, type PublicActions, type TestClient, type TransactionReceipt, type Transport, type WalletActions } from 'viem';
+import type { Account, SignedAuthorization } from 'viem';
+import { TEST_ERC20_ABI } from './contracts/test-erc20.js';
+import { type DealErc20Options } from './erc20.js';
+import { type DecodedTransaction } from './transactions.js';
 import type { JsonRpcRequest, RpcClient } from './types.js';
+export type DeployContractOptions = {
+    abi: Abi;
+    bytecode: Hex;
+    args?: readonly unknown[];
+    /** Defaults to the first Anvil unlocked account. */
+    from?: Address;
+    value?: bigint;
+};
+export type DeployedContract = {
+    address: Address;
+    hash: Hex;
+    receipt: TransactionReceipt;
+};
+export type DeployErc20Options = {
+    name?: string;
+    symbol?: string;
+    decimals?: number;
+    /** Minted to mintTo in the constructor. Default 0n. */
+    initialSupply?: bigint;
+    /** Defaults to the deployer. */
+    mintTo?: Address;
+    from?: Address;
+};
+export type DeployedErc20 = DeployedContract & {
+    abi: typeof TEST_ERC20_ABI;
+    name: string;
+    symbol: string;
+    decimals: number;
+};
+export type ChainAuthorizationOptions = {
+    /** Authority: a viem local account or a raw private key. */
+    account: Account | Hex;
+    /** The delegate contract; the zero address revokes. */
+    contractAddress: Address;
+    nonce?: number;
+    /** Default: this chain's id. 0 = valid on any chain. */
+    chainId?: number;
+    /** 'self' when the authority submits its own type-4 tx (nonce+1 rules). */
+    executor?: 'self';
+};
+export type DelegateOptions = {
+    /** Authority whose key signs the authorization. */
+    account: Account | Hex;
+    contractAddress: Address;
+    /** Unlocked anvil account paying gas. Default: accounts()[0]. */
+    sponsor?: Address;
+};
 export type AnvilOptions = {
     runtime?: 'binary' | 'docker';
     executable?: string;
@@ -13,8 +64,12 @@ export type AnvilOptions = {
     mnemonic?: string;
     blockTime?: number;
     forkUrl?: string;
+    forkBlockNumber?: number;
+    extraArgs?: readonly string[];
     timeoutMs?: number;
     silent?: boolean;
+    /** Opt in to binding Anvil to a non-loopback interface. */
+    allowNonLoopbackHost?: boolean;
 };
 export type AnvilSnapshotId = Hex;
 export type AnvilViemClient = TestClient<'anvil', Transport, Chain> & PublicActions<Transport, Chain> & WalletActions<Chain>;
@@ -28,7 +83,7 @@ export declare class AnvilInstance {
     private constructor();
     static start(options?: AnvilOptions): Promise<AnvilInstance>;
     stop(): Promise<void>;
-    private isReady;
+    private reportedChainId;
 }
 export type ChainControllerOptions = {
     rpcUrl: string;
@@ -48,5 +103,38 @@ export declare class ChainController implements RpcClient {
     setBalance(address: Address, value: bigint): Promise<void>;
     fastForward(seconds: number): Promise<void>;
     mine(blocks?: number): Promise<void>;
+    /**
+     * Waits for the receipt and returns it with decoded logs (when an abi is
+     * given) and, for reverted transactions, the recovered revert reason.
+     */
+    waitForTransaction(hash: Hex, options?: {
+        abi?: Abi;
+        timeoutMs?: number;
+    }): Promise<DecodedTransaction>;
+    private readonly erc20SlotCache;
+    deployContract(options: DeployContractOptions): Promise<DeployedContract>;
+    deployErc20(options?: DeployErc20Options): Promise<DeployedErc20>;
+    /** forge-std deal parity: set any standard ERC-20 balance, fork included. */
+    dealErc20(token: Address, account: Address, amount: bigint, options?: DealErc20Options): Promise<void>;
+    getErc20Balance(token: Address, account: Address): Promise<bigint>;
+    setStorageAt(address: Address, slot: Hex | bigint | number, value: Hex | bigint): Promise<void>;
+    setCode(address: Address, bytecode: Hex): Promise<void>;
+    setNonce(address: Address, nonce: number): Promise<void>;
+    signAuthorization(options: ChainAuthorizationOptions): Promise<SignedAuthorization>;
+    /**
+     * Signs and submits a type-4 delegation from an unlocked sponsor; resolves
+     * once the authority's code is the 0xef0100‖address designator.
+     */
+    delegate(options: DelegateOptions): Promise<{
+        hash: Hex;
+        authority: Address;
+    }>;
+    /** Authorization to the zero address: resets the authority's code to 0x. */
+    revokeDelegation(options: Omit<DelegateOptions, 'contractAddress'>): Promise<{
+        hash: Hex;
+        authority: Address;
+    }>;
+    /** Parses the EIP-7702 designator out of eth_getCode; null when not delegated. */
+    getDelegation(authority: Address): Promise<Address | null>;
 }
 //# sourceMappingURL=anvil.d.ts.map

package/dist/anvil.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"anvil.d.ts","sourceRoot":"","sources":["../src/anvil.ts"],"names":[],"mappings":"AAGA,OAAO,EAKL,KAAK,OAAO,EACZ,KAAK,KAAK,EACV,KAAK,GAAG,EACR,KAAK,aAAa,EAClB,KAAK,UAAU,EACf,KAAK,SAAS,EACd,KAAK,aAAa,EACnB,MAAM,MAAM,CAAC;AAEd,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5D,MAAM,MAAM,YAAY,GAAG;IACzB,OAAO,CAAC,EAAE,QAAQ,GAAG,QAAQ,CAAC;IAC9B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG,GAAG,CAAC;AAClC,MAAM,MAAM,eAAe,GAAG,UAAU,CAAC,OAAO,EAAE,SAAS,EAAE,KAAK,CAAC,GACjE,aAAa,CAAC,SAAS,EAAE,KAAK,CAAC,GAC/B,aAAa,CAAC,KAAK,CAAC,CAAC;AAwDvB,qBAAa,aAAa;IAOtB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAExB,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAC;IARjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAExB,OAAO;WAWM,KAAK,CAAC,OAAO,GAAE,YAAiB,GAAG,OAAO,CAAC,aAAa,CAAC;IA0FhE,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;YAab,OAAO;CAkBtB;AAED,MAAM,MAAM,sBAAsB,GAAG;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF,qBAAa,eAAgB,YAAW,SAAS;IAC/C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAC;gBAErB,OAAO,EAAE,sBAAsB;IAYrC,QAAQ,IAAI,OAAO,CAAC,eAAe,CAAC;IAIpC,MAAM,CAAC,EAAE,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAI1C,QAAQ,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;IAI9B,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,OAAO,CAAC;IAIlD,kBAAkB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAInD,wBAAwB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAIzD,UAAU,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI1D,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAK3C,IAAI,CAAC,MAAM,SAAI,GAAG,OAAO,CAAC,IAAI,CAAC;CAGtC"}
+{"version":3,"file":"anvil.d.ts","sourceRoot":"","sources":["../src/anvil.ts"],"names":[],"mappings":"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"}