web3agent 0.1.0 → 0.2.0

package/README.md

@@ -24,14 +24,113 @@ npx web3agent --help
 npx web3agent --version
 ```
 
+## Programmatic Usage
+
+### Root API
+
+Use the package root when you want stable, typed Web3 capabilities from another app or agent layer.
+
+```js
+import { getChain, listChainTokens, resolveCanonicalTokenSync, resolveToken } from "web3agent";
+
+const chain = getChain(8453);
+const usdc = resolveCanonicalTokenSync({ symbol: "USDC", chainId: 8453 });
+const tokens = listChainTokens({ chainId: 8453 });
+const discovered = await resolveToken({ symbol: "DEGEN", chainId: 8453 });
+
+console.log(chain?.name, usdc?.address, discovered.address, tokens.tokens.length);
+```
+
+Use `resolveCanonicalToken()` / `resolveCanonicalTokenSync()` when you only want well-known registry tokens and native-token aliases. Use `resolveToken()` when you want registry resolution plus DexScreener discovery fallback for long-tail assets.
+
+Root API helpers lazily create a shared default runtime under the hood. Long-lived processes can import `shutdownDefaultRuntime` from `web3agent/runtime` to release those resources when finished.
+
+### Browser Wallet Flows
+
+Use the root package API when your app owns the signer, for example a browser wallet connected through wagmi or AppKit.
+
+```js
+import { prepareOperation, resumeOperation, simulateTransaction } from "web3agent";
+```
+
+The primary flow is generic:
+
+1. `prepareOperation(...)` returns the next wallet actions plus `resumeState`
+2. Your app executes those actions with the browser wallet
+3. `resumeOperation(...)` continues until the operation completes
+
+Protocol-specific helpers like `prepareSwapIntent()` and `submitSignedSwap()` remain available as compatibility wrappers, but new integrations should target the generic prepared-operation API first.
+
+Prepared browser-wallet flows are staged. `prepareOperation()` and `resumeOperation()` only return the next required actions, and `resumeOperation()` persists previously completed action results inside the opaque resume state so callers only need to submit newly finished actions on each round.
+
+Transaction actions are only considered complete once the caller returns a confirmed result:
+
+```js
+{ type: "transaction", txHash: "0x...", status: "confirmed" }
+```
+
+`resumeOperation()` independently verifies the receipt before advancing to the next stage.
+
+For LI.FI compatibility helpers, `prepareBridgeIntent()` now returns both `steps` and `actions` as the transaction-only sequence for browser wallets, including any required approval transactions before the bridge call. Use `prepareOperation()` with `integration: "lifi"` when you need the staged external-wallet flow with typed-data signing.
+
+`simulateTransaction()` returns a success payload on successful simulation and throws structured `Web3AgentError` failures for invalid inputs, reverts, or RPC errors. When `debug_traceCall` is unavailable, balance changes come from a best-effort fallback decoder.
+
+Architecture notes live in [docs/architecture/browser-wallet-operations.md](./docs/architecture/browser-wallet-operations.md).
+
+### Runtime API
+
+Use `web3agent/runtime` when you need tool discovery, generic invocation, wallet flows, or upstream passthrough tools.
+
+```js
+import { createRuntime } from "web3agent/runtime";
+
+const runtime = await createRuntime();
+
+try {
+  console.log(runtime.getHealth());
+  console.log(runtime.listTools().slice(0, 5).map((tool) => tool.name));
+  const result = await runtime.invokeTool("list_supported_chains");
+  console.log(result.structuredContent);
+} finally {
+  await runtime.shutdown();
+}
+```
+
+## Smoke Tests
+
+Run the standard repo checks first:
+
+```bash
+pnpm lint
+pnpm typecheck
+pnpm test
+pnpm build
+```
+
+Then run the packaged API smoke scripts:
+
+```bash
+node examples/root-api-smoke.mjs
+node examples/runtime-smoke.mjs
+node examples/runtime-smoke.mjs --run
+```
+
+`root-api-smoke.mjs` is fully local. `runtime-smoke.mjs` without flags verifies the runtime import surface only. `runtime-smoke.mjs --run` starts the real runtime in read-only mode, so upstream services may appear as degraded or fail if network access is unavailable.
+
+The env-gated browser-wallet e2e test in [`tests/e2e/browser-wallet-flow.test.ts`](tests/e2e/browser-wallet-flow.test.ts) runs when these variables are present: `BROWSER_WALLET_E2E`, `BROWSER_WALLET_E2E_CHAIN_ID`, `BROWSER_WALLET_E2E_ACCOUNT`, `BROWSER_WALLET_E2E_FROM_TOKEN`, `BROWSER_WALLET_E2E_TO_TOKEN`, `BROWSER_WALLET_E2E_IN_AMOUNT`, and `BROWSER_WALLET_E2E_SIGNATURE`.
+
 ## What you get
 
-- **Blockscout** — indexed blockchain data (address info, tx history, NFTs, contract ABIs)
-- **EVM MCP** — live on-chain state (balances, contract reads, gas, ENS)
-- **GOAT plugins** — Uniswap, Balancer, ERC-20/721, DexScreener
-- **LI.FI** — cross-chain bridging and swaps
+- **Blockscout** — indexed blockchain data (address info, tx history, NFTs, contract ABIs). Supported on 8 chains: Ethereum, Polygon, Arbitrum, Optimism, Base, Gnosis, Scroll, zkSync Era.
+- **Etherscan** — contract ABI fetching (requires `ETHERSCAN_API_KEY`)
+- **EVM MCP** — live on-chain state (balances, contract reads/writes, gas, ENS, multicall)
+- **GOAT plugins** — Uniswap, Balancer, ERC-20/721, ENS, DexScreener
+- **Optional GOAT plugins** — 0x (requires `ZEROX_API_KEY`), CoinGecko (requires `COINGECKO_API_KEY`)
+- **LI.FI** — cross-chain bridging and swaps across 20+ chains
 - **Orbs** — Liquidity Hub aggregated swaps, dTWAP, dLIMIT orders
-- **Wallet management** — generate, persist, derive addresses
+- **Token resolver** — symbol-to-address resolution with built-in registry and DexScreener fallback
+- **Wallet management** — generate, persist, activate/deactivate, derive addresses, sign messages
+- **Confirmation queue** — write operations require explicit confirmation by default
 
 ## Supported Hosts
 
@@ -52,9 +151,16 @@ Default: **Base (8453)**. Override with `CHAIN_ID` env var or `chainId` paramete
 
 See [WEB3_CONTEXT.md](./WEB3_CONTEXT.md) for the full environment variable table.
 
+## Known Limitations
+
+- **Blockscout** tools only work on 8 chains (Ethereum, Polygon, Arbitrum, Optimism, Base, Gnosis, Scroll, zkSync Era)
+- **dSLTP** (stop-loss/take-profit orders) is not yet available
+- **0x** and **CoinGecko** plugins require their respective API keys
+- **Browser wallet signing over MCP** is indirect: MCP can prepare, simulate, and submit signed payloads, but generic MCP hosts cannot open a browser wallet prompt on their own
+
 ## Requirements
 
-- Node.js 18+
+- Node.js 22+
 - pnpm (for development)
 
 ## License

package/WEB3_CONTEXT.md

@@ -18,11 +18,20 @@ Live on-chain state: current balances, contract reads, gas estimation, ENS resol
 - `wallet_from_mnemonic` — derive address from mnemonic
 - `wallet_derive_addresses` — batch derive 1-20 addresses
 - `wallet_get_active` — get current wallet address, chain, mode
+- `wallet_activate` — activate wallet from private key or mnemonic, persists to disk (mode 0600)
+- `wallet_deactivate` — deactivate current wallet, delete key file, revert to read-only
+- `wallet_set_confirmation` — toggle write confirmation at runtime (enabled/disabled)
 
 ### Transaction management
 - `transaction_confirm(id)` — execute a queued write operation
 - `transaction_deny(id)` — discard a queued operation
 - `transaction_list()` — list pending operations
+- `transaction_simulate()` — simulate an unsigned transaction, estimate gas, and preview balance changes
+
+### Browser-wallet operations
+- `operation_prepare` — prepare the next external-wallet actions plus opaque `resumeState`
+- `operation_resume` — continue a prepared operation after signatures or transactions complete externally
+- These are the primary MCP tools for browser-wallet flows across Orbs, LI.FI, and GOAT
 
 ### DeFi tools
 
@@ -35,18 +44,78 @@ Live on-chain state: current balances, contract reads, gas estimation, ENS resol
 - `lifi_get_chains` — list supported chains
 - `lifi_get_quote` — get bridge/swap quote
 - `lifi_execute_bridge` — execute cross-chain bridge (write, confirmation-gated)
+- `lifi_prepare_bridge_intent` — prepare raw bridge transaction steps for an external wallet (read-only)
+  Compatibility note: `operation_prepare` / `operation_resume` are the preferred generic MCP flow
 
 **Orbs DeFi** (prefix: `orbs_`):
 - `orbs_get_quote` — Liquidity Hub aggregated swap quote (chains: 137, 56, 8453, 59144, 81457, 42161)
 - `orbs_swap` — execute swap (write, confirmation-gated)
+- `orbs_prepare_swap_intent` — prepare swap quote + EIP-712 payload for an external wallet (read-only)
+- `orbs_get_required_approvals` — check wrap / Permit2 approval steps before signing (read-only)
+- `orbs_swap_status` — check status of a pending Liquidity Hub swap (takes chainId, sessionId, user)
 - `orbs_place_twap` — place dTWAP order (write, confirmation-gated)
+- `orbs_prepare_twap_intent` — prepare dTWAP order data for an external wallet (read-only)
 - `orbs_place_limit` — place dLIMIT order (write, confirmation-gated)
+- `orbs_prepare_limit_intent` — prepare dLIMIT order data for an external wallet (read-only)
+- `orbs_submit_signed_swap` — submit an externally signed Orbs swap (write)
+- `orbs_submit_signed_twap_order` — submit an externally signed dTWAP or dLIMIT order (write)
 - `orbs_list_orders` — list open TWAP/dLIMIT orders
+  Compatibility note: these remain supported, but `operation_prepare` / `operation_resume` are the generic-first browser-wallet flow
+
+### Browser-wallet limitation
+The browser-wallet tools are MCP-compatible, but generic MCP hosts cannot trigger browser wallet popups themselves. Use MCP to prepare, simulate, and resume operations; perform the actual wallet signing in the surrounding app or host integration.
+
+### Token resolution (prefix: none)
+- `resolve_token(symbol, chainId)` — resolve token symbol to contract address and decimals. Uses built-in registry with DexScreener fallback. ALWAYS use this before swaps/bridges.
+- `list_chain_tokens(chainId)` — list all well-known tokens for a chain from the built-in registry
 
 ### Utilities
 - `server_status` — wallet mode, active chain, confirmation setting, backend health
 - `list_supported_chains` — all 17 supported chains with IDs and names
 
+### Agentic Economy — x402 Payments (prefix: `x402_`)
+HTTP-native stablecoin payments for AI agent services. Use `x402_check_requirements` first to preview cost, then `x402_fetch` to execute.
+- `x402_check_requirements` — probe a URL for payment requirements (amount, token, network). Returns null if no payment needed. (read-only)
+- `x402_fetch` — fetch a URL with automatic x402 payment. Shows cost in confirmation before paying. (write, confirmation-gated)
+
+### Agentic Economy — Job Escrow / ERC-8183 (prefix: `erc8183_`)
+EIP-8183 specification reference implementation (no canonical deployed contract). Job flow: create → setBudget → fund → submit → complete/reject. Expired jobs support `erc8183_claim_refund`. Distinct from `acp_*` tools which target the Virtuals production ACPRouter on Base.
+- `erc8183_create_job` — create a new job specifying provider, evaluator, description, and expiry duration (write)
+- `erc8183_set_budget` — set the budget for a job (write)
+- `erc8183_fund_job` — approve token allowance + fund job escrow in one confirmation (write)
+- `erc8183_submit_job` — submit a deliverable (string, gets keccak256-hashed on-chain) (write)
+- `erc8183_complete_job` — mark job complete, release payment to provider (write)
+- `erc8183_reject_job` — reject submitted deliverable, funds remain in escrow (write)
+- `erc8183_claim_refund` — reclaim escrowed funds after job expiry (write)
+- `erc8183_get_job` — read current job state: client, provider, budget, status, deliverable (read-only)
+
+### Agentic Economy — Virtuals ACP / ACPRouter (prefix: `acp_`)
+On-chain job lifecycle on the Virtuals ACPRouter V2 (Base mainnet and Base Sepolia). Uses a memo-based protocol: jobs progress through phases (Request → Negotiation → Transaction → Evaluation → Completed/Rejected) via memos that participants create and sign. No `ACP_CONTRACT_ADDRESS` env var needed — canonical addresses are hardcoded.
+- `acp_create_job` — create a job specifying provider, evaluator, description, expiry, and optional budget (write)
+- `acp_set_budget` — set or update job budget with payment token (write)
+- `acp_fund_job` — approve token allowance + fund job via payable escrow memo (write)
+- `acp_submit_job` — submit deliverable as a memo, advancing job to evaluation phase (write)
+- `acp_complete_job` — approve the latest pending memo (auto-resolved), completing the job (write)
+- `acp_reject_job` — reject the latest pending memo (auto-resolved), rejecting the deliverable (write)
+- `acp_claim_refund` — claim escrowed budget after job completion or expiry (write)
+- `acp_get_job` — read job state with full memo history, phase, participants, and pending actions (read-only)
+
+### Agentic Economy — Agent Marketplace / aGDP (prefix: `agdp_`)
+Discover and hire agents on the Virtuals Protocol aGDP marketplace (`acpx.virtuals.io`). No wallet required for discovery.
+- `agdp_get_offerings` — search agent marketplace by query string; returns name, wallet, offerings, metrics (read-only)
+- `agdp_get_offering` — get details of a specific agent by ID (read-only)
+- `agdp_get_my_jobs` — list active or completed jobs for the current wallet (read-only)
+- `agdp_hire_agent` — hire an agent via aGDP API (write, confirmation-gated). For on-chain job creation, use `acp_create_job` separately.
+- `agdp_create_offering` — register an agent offering on aGDP. Requires `LITE_AGENT_API_KEY` from Virtuals — visit agdp.io/join to register.
+
+### Agentic Economy — Agent Identity / ERC-8004 (prefix: `erc8004_`)
+On-chain agent identity (ERC-721) and reputation registry. Canonical contracts deployed on Base and Base Sepolia. Requires IPFS hosting or `PINATA_JWT` for registration JSON.
+- `erc8004_register_agent` — register agent on-chain: checks for duplicate, validates JSON, pins to IPFS via Pinata or uses provided `agentURI` (write, confirmation-gated)
+- `erc8004_get_agent` — get agent info by agentId or wallet address (read-only)
+- `erc8004_update_agent` — update agent registration URI on-chain (write, confirmation-gated)
+- `erc8004_submit_feedback` — submit reputation feedback (-100 to +100) for an agent (write, confirmation-gated)
+- `erc8004_get_feedback` — get aggregated reputation summary for an agent (read-only)
+
 ## Chain Selection
 Default chain: **Base (8453)**. Override per-call with `chainId` parameter.
 
@@ -89,3 +158,13 @@ Write operations (swaps, bridges, transfers) are queued by default. Use `transac
 | `LIFI_API_KEY` | — | LI.Fi API key |
 | `ZEROX_API_KEY` | — | 0x API key (enables 0x plugin) |
 | `COINGECKO_API_KEY` | — | CoinGecko API key (enables CoinGecko plugin) |
+| `ACP_PAYMENT_TOKEN` | — | ERC-20 token address for ACP escrow (defaults to USDC on active chain) |
+| `PINATA_JWT` | — | Pinata JWT for auto-pinning ERC-8004 agent registration JSON to IPFS |
+| `ERC8004_AGENT_URI` | — | Advertised MCP endpoint URI for ERC-8004 agent registration |
+| `AGDP_API_URL` | https://acpx.virtuals.io/api | aGDP marketplace API base URL |
+
+## Known Limitations
+
+- **Blockscout chain coverage**: Blockscout hosted instances support only 8 chains (Ethereum, Polygon, Arbitrum, Optimism, Base, Gnosis, Scroll, zkSync Era). Other chains (BSC, Linea, Avalanche, Blast, Mantle, Mode) are NOT supported by Blockscout tools.
+- **dSLTP (Stop Loss/Take Profit)**: Not yet available. Feature-gated for future release.
+- **CoinGecko and 0x plugins**: Require API keys (`COINGECKO_API_KEY`, `ZEROX_API_KEY`) to activate.

package/dist/agdp/api.d.ts

@@ -0,0 +1,65 @@
+declare const AGDP_DEFAULT_URL = "https://acpx.virtuals.io/api";
+interface AgdpOffering {
+    id: number;
+    name: string;
+    description: string;
+    price: number;
+    type: string;
+    requiredFunds: boolean;
+    slaMinutes: number;
+}
+interface AgdpAgent {
+    id: number;
+    name: string;
+    description: string;
+    walletAddress: string;
+    contractAddress: string;
+    metrics: {
+        successRate: number | null;
+        isOnline: boolean;
+    };
+    jobs: AgdpOffering[];
+}
+interface AgdpJob {
+    id: number;
+    phase: string;
+    providerName: string;
+    providerWalletAddress: string;
+    clientWalletAddress: string;
+    deliverable: string;
+    memos: Array<{
+        nextPhase: string;
+        content: string;
+        createdAt: string;
+    }>;
+}
+interface AgdpJobResponse {
+    id: number;
+    phase: string;
+    providerName: string;
+    [key: string]: unknown;
+}
+declare function getAgdpBaseUrl(): string;
+declare function searchOfferings(params: {
+    query?: string;
+    topK?: number;
+}): Promise<AgdpAgent[]>;
+declare function getOfferingById(offeringId: number | string, cachedAgents?: AgdpAgent[]): Promise<AgdpAgent | null>;
+declare function getJobs(params: {
+    walletAddress: string;
+    status?: "active" | "completed";
+}): Promise<AgdpJob[]>;
+declare function createJobViaApi(params: {
+    providerWalletAddress: string;
+    jobOfferingName: string;
+    serviceRequirements?: Record<string, unknown>;
+}): Promise<AgdpJobResponse>;
+declare function createOfferingViaApi(_params: {
+    name: string;
+    description: string;
+    price: number;
+    category?: string;
+    walletAddress: string;
+}): Promise<unknown>;
+
+export { AGDP_DEFAULT_URL, type AgdpAgent, type AgdpJob, type AgdpJobResponse, type AgdpOffering, createJobViaApi, createOfferingViaApi, getAgdpBaseUrl, getJobs, getOfferingById, searchOfferings };

package/dist/agdp/api.js

@@ -0,0 +1,19 @@
+import {
+  AGDP_DEFAULT_URL,
+  createJobViaApi,
+  createOfferingViaApi,
+  getAgdpBaseUrl,
+  getJobs,
+  getOfferingById,
+  searchOfferings
+} from "../chunk-ETI3ZR2C.js";
+import "../chunk-7QEKU2RP.js";
+export {
+  AGDP_DEFAULT_URL,
+  createJobViaApi,
+  createOfferingViaApi,
+  getAgdpBaseUrl,
+  getJobs,
+  getOfferingById,
+  searchOfferings
+};

package/dist/chunk-4G55KHRO.js

@@ -0,0 +1,63 @@
+import {
+  getActiveAccount,
+  getTransportForChain
+} from "./chunk-KPRIUALX.js";
+import {
+  getChainById
+} from "./chunk-7QEKU2RP.js";
+
+// src/x402/client.ts
+import { decodePaymentRequiredHeader } from "@x402/core/http";
+import { ExactEvmScheme, toClientEvmSigner } from "@x402/evm";
+import { wrapFetchWithPayment, x402Client } from "@x402/fetch";
+import { createPublicClient, createWalletClient, publicActions } from "viem";
+function createX402Client(chainId) {
+  const chain = getChainById(chainId);
+  if (!chain) {
+    throw new Error(`[x402] Unsupported chain ID: ${chainId}`);
+  }
+  const transport = getTransportForChain(chainId);
+  const publicClient = createPublicClient({ chain, transport });
+  const account = getActiveAccount();
+  const walletClient = createWalletClient({ account, chain, transport }).extend(publicActions);
+  const localAccount = walletClient.account ?? account;
+  const signer = toClientEvmSigner(localAccount, publicClient);
+  const scheme = new ExactEvmScheme(signer);
+  const client = new x402Client().register("eip155:*", scheme);
+  const fetchWithPayment = wrapFetchWithPayment(globalThis.fetch, client);
+  return { client, fetchWithPayment };
+}
+async function probePaymentRequirements(url, method = "GET", headers = {}, body) {
+  const response = await globalThis.fetch(url, {
+    method,
+    headers,
+    body: body ?? void 0
+  });
+  if (response.status !== 402) {
+    return { requirements: null, probeResponse: response };
+  }
+  const headerValue = response.headers.get("PAYMENT-REQUIRED");
+  if (headerValue) {
+    try {
+      return { requirements: decodePaymentRequiredHeader(headerValue), probeResponse: response };
+    } catch (err) {
+      process.stderr.write(`[x402] Failed to decode PAYMENT-REQUIRED header: ${err}
+`);
+    }
+  }
+  try {
+    const text = await response.text();
+    if (text) {
+      return { requirements: JSON.parse(text), probeResponse: response };
+    }
+  } catch (err) {
+    process.stderr.write(`[x402] Failed to parse 402 response body from ${url}: ${err}
+`);
+  }
+  return { requirements: null, probeResponse: response };
+}
+
+export {
+  createX402Client,
+  probePaymentRequirements
+};

package/dist/chunk-7ITJ5WGE.js

@@ -0,0 +1,26 @@
+import {
+  createRuntime
+} from "./chunk-B4LSSN7C.js";
+
+// src/runtime/default.ts
+var defaultRuntimePromise;
+function getDefaultRuntime() {
+  if (!defaultRuntimePromise) {
+    defaultRuntimePromise = createRuntime();
+  }
+  return defaultRuntimePromise;
+}
+async function shutdownDefaultRuntime() {
+  if (!defaultRuntimePromise) {
+    return;
+  }
+  const runtimePromise = defaultRuntimePromise;
+  defaultRuntimePromise = void 0;
+  const runtime = await runtimePromise;
+  await runtime.shutdown();
+}
+
+export {
+  getDefaultRuntime,
+  shutdownDefaultRuntime
+};

package/dist/{chunk-BF4PA46E.js → chunk-7QEKU2RP.js}

@@ -1,5 +1,3 @@
-#!/usr/bin/env node
-
 // src/chains/registry.ts
 import * as viemChains from "viem/chains";
 var CHAINS_BY_ID = /* @__PURE__ */ new Map();
@@ -14,6 +12,14 @@ for (const value of Object.values(viemChains)) {
 function getChainById(id) {
   return CHAINS_BY_ID.get(id);
 }
+function getRequiredChain(chainId) {
+  const chain = getChainById(chainId);
+  if (!chain) throw new Error(`Unsupported chain ID: ${chainId}`);
+  return chain;
+}
+function getChainByName(name) {
+  return CHAINS_BY_NAME.get(name.toLowerCase());
+}
 function isSupported(id) {
   return CHAINS_BY_ID.has(id);
 }
@@ -75,33 +81,59 @@ function parseEnv(env = {}) {
     rpcUrl: env.RPC_URL || void 0,
     chainRpcUrls: parseChainRpcUrls(env),
     confirmWrites: parseBoolean(env.CONFIRM_WRITES, true),
+    confirmTtlMinutes: parseIntStrict("CONFIRM_TTL_MINUTES", env.CONFIRM_TTL_MINUTES, 30),
     blockscoutMcpUrl: env.BLOCKSCOUT_MCP_URL || BLOCKSCOUT_DEFAULT_URL,
     etherscanMcpUrl: env.ETHERSCAN_MCP_URL || ETHERSCAN_DEFAULT_URL,
     etherscanApiKey: env.ETHERSCAN_API_KEY || void 0,
     lifiApiKey: env.LIFI_API_KEY || void 0,
     zeroxApiKey: env.ZEROX_API_KEY || void 0,
     coingeckoApiKey: env.COINGECKO_API_KEY || void 0,
-    orbsPartner: env.ORBS_PARTNER || void 0
+    orbsPartner: env.ORBS_PARTNER || void 0,
+    acpContractAddress: env.ACP_CONTRACT_ADDRESS || void 0,
+    acpPaymentToken: env.ACP_PAYMENT_TOKEN || void 0,
+    pinataJwt: env.PINATA_JWT || void 0,
+    erc8004AgentUri: env.ERC8004_AGENT_URI || void 0,
+    agdpApiUrl: env.AGDP_API_URL || "https://acpx.virtuals.io/api"
   };
 }
 var cached;
 function setConfig(config) {
   cached = config;
 }
+function resetConfig() {
+  cached = void 0;
+}
 function getConfig() {
   if (!cached) {
     throw new Error("Config not initialized \u2014 call setConfig() during startup");
   }
   return cached;
 }
+function tryGetConfig() {
+  return cached;
+}
+async function withConfig(config, fn) {
+  const previous = cached;
+  cached = config;
+  try {
+    return await fn();
+  } finally {
+    cached = previous;
+  }
+}
 
 export {
   getChainById,
+  getRequiredChain,
+  getChainByName,
   isSupported,
   BLOCKSCOUT_DEFAULT_URL,
   ETHERSCAN_DEFAULT_URL,
   ValidationError,
   parseEnv,
   setConfig,
-  getConfig
+  resetConfig,
+  getConfig,
+  tryGetConfig,
+  withConfig
 };