API ReferenceSetup and configurationInterface
AnvilDependencies
The dependencies an AnvilSDK instance needs to operate: your viem clients plus a generated
environment profile and optional subgraph, oracle, and LOC-policy configuration. Pass one to
new AnvilSDK(deps).
Example
const profile = anvilProfiles.testnet;
const deps: AnvilDependencies = { publicClient, walletClient, profile, // From useAccount().address: lets reads run before the wallet // reconnects. accountAddress: '0x2222222222222222222222222222222222222222', // ENS lives on mainnet even when the protocol chain is Sepolia. mainnetRpcUrl: 'https://your-mainnet-rpc-url', oracleConfig: { // Reject Hermes data more than five minutes from the local clock. maxPriceAgeSeconds: 300, // Separately reserve 60s inside the deployment's on-chain window. updateBufferSeconds: 60, },};
return new AnvilSDK(deps);Properties
accountAddress?
optional accountAddress?: `0x${string}`;Connected account address for read operations (balance queries, validation, allowance checks).
Resolves before walletClient in wagmi — set this from useAccount().address so reads work
immediately without waiting for the wallet connector to reconnect.
Falls back to walletClient.account.address if not set. Explicit undefined is equivalent to
omission.
locConfig?
optional locConfig?: LOCConfig;LOC management behavior and display configuration (beneficiary allowlist, default destination, token
allowlists, etc.). See LOCConfig for what the SDK enforces versus what only the
React components read. Explicit undefined is equivalent to omission.
mainnetRpcUrl?
optional mainnetRpcUrl?: string;RPC URL for a dedicated, mainnet-pinned viem client used only for ENS operations (resolveAddress,
getEnsName). ENS is a mainnet-only protocol, so this lets ENS resolution work correctly even when
publicClient above is configured for another chain (for example Sepolia, which testnet uses).
ENS resolution on non-mainnet protocol chains requires mainnetRpcUrl. When not provided, ENS
actions fall back to publicClient — correct only when the protocol chain IS mainnet.
oracleConfig?
optional oracleConfig?: OracleConfig;Pyth Hermes settings, used only by Dynamic LOC operations and price reads. Every field is optional:
hermesEndpoint: the Hermes URL,https://hermes.pyth.networkby default, which rejects requests without an API key. In a browser, point it at your own proxy that adds the key server-side.hermesAccessToken: the Pyth API key, sent as a Bearer token. Set it only where the SDK runs server-side; never ship it in a browser bundle.maxPriceAgeSeconds: the oldest Hermes price accepted, 300 seconds by default;Infinityturns the freshness check off.updateBufferSeconds: time validation allows for a price-update transaction to confirm, 30 seconds by default.
profile
profile: AnvilSdkProfile;The environment profile: import testnetProfile or
mainnetProfile directly so bundlers can drop the other, or select
anvilProfiles[name] at runtime by environment name. The profile supplies contract addresses, the
ABI bound at each of those addresses, the subgraph URL, and the environment’s token-alias map.
subgraphUrl may override the profile’s endpoint.
The ABIs are what make this more than address configuration: a profile binds each address to the interface derived from the deployment at that address, and the SDK encodes calldata, decodes returns, and names revert errors against that interface rather than against its bundled modules, so environments running different deployed generations each get their own.
Contract-address resolution asserts the live chain equals profile.chainId, throwing ConfigError
on disagreement so a client wired to the wrong network fails loudly instead of transacting at
another environment’s addresses. More than one environment can share a chain id, and the guard
cannot tell those apart — the profile you pass is the selector; the guard catches cross-chain
wiring mistakes.
The SDK does not read profile.pyth.hermesPath. Price reads go to oracleConfig.hermesEndpoint.
publicClient
publicClient: object;viem PublicClient for every read: contract calls, chain-id resolution, and (absent
mainnetRpcUrl) ENS. Its chain must match the generated AnvilDependencies.profile.
Create one with viem’s createPublicClient({ chain, transport }), or in React take wagmi’s
usePublicClient().
subgraphHeaders?
optional subgraphHeaders?: Record<string, string>;HTTP headers to send with every subgraph request (e.g. authorization).
subgraphUrl?
optional subgraphUrl?: string;GraphQL endpoint of the Anvil subgraph. Required for indexed reads — LOC and vault listings,
history, collateral-token discovery — which throw ConfigError without it; direct contract reads
(sdk.loc.getOutstandingLetterOfCredit, balances, prices) do not need it, and each published
profile carries its endpoint at <profile>.subgraph.url.
walletClient?
optional walletClient?: object;viem WalletClient that signs and sends transactions. Omit it for read-only use: queries,
validation, and workflow building work without a wallet, while a built workflow’s execute() and
any other write throw WalletNotConnectedError until one is supplied here or via
AnvilSDK.updateWalletClient. Explicit undefined is
equivalent to omission. Create one with viem’s createWalletClient({ account, chain, transport }),
or in React take data from wagmi’s useWalletClient().