React provider and hooks

Connect React applications to the SDK: the provider, read and workflow hooks, and incremental validation.

One AnvilProvider near the root of the tree makes a configured SDK available to everything beneath it, and useAnvilSDK returns it — throwing if a component renders outside the provider; useAnvilSDKOptional returns undefined instead when that is more convenient.

Read hooks such as useCollateralTokens, useTokenPrice, and useRequiredCollateral wrap the core actions and carry their own loading and error state. Workflow hooks such as useCreateLOCWorkflow validate a form, report per-field issues, and hand back a workflow only once the params are valid — useIncrementalValidation drives that per-field state from the core validation rule sets directly, for a form that does not need a full workflow hook.

The beta components built on these hooks — CreateLOCFlow and the rest — are in React components; the instance these hooks need is built in Setup and configuration.

Provider at the root, hook in a component:

export function App() {
  // Build the SDK once (module scope or useMemo); hooks key on it.
  return (
    <AnvilProvider sdk={sdk}>
      <LOCBeneficiary id={1n} />
    </AnvilProvider>
  );
}

function LOCBeneficiary({ id }: { id: bigint }) {
  // Throws if this component renders outside <AnvilProvider>.
  const sdk = useAnvilSDK();
  const [loc, setLoc] = useState<OutstandingLetterOfCredit>();

  useEffect(() => {
    void sdk.loc.getOutstandingLetterOfCredit({ id }).then(setLoc);
  }, [sdk, id]);

  return <p>Beneficiary: {loc?.beneficiary ?? 'loading'}</p>;
}

Primary APIs

Provider

• AnvilProvider — React context provider that makes one configured AnvilSDK available to every hook and component beneath it.
• useAnvilSDK — Returns the AnvilSDK instance from context — the one passed to <AnvilProvider sdk={...}> — so sdk.loc, sdk.vault, sdk.pricing,…
• useAnvilSDKOptional — Returns the AnvilSDK instance from context, or null if no provider is present.

Read hooks

• useCollateralTokens — Fetches the Anvil protocol’s collateral tokens.
• useCreditedTokens — Fetches the credited-token collection for dynamic-LOC selection.
• useCollateralTokensForCreditedToken — Fetches the CollateralTokens eligible as collateral for a given credited token.
• useAvailableVaultAndWalletTokenBalances — Helper hook to fetch the total available balance of a token for an account.
• useVaultWithdrawalFeeBasisPoints — Fetches the CollateralVault’s current withdrawal fee in basis points.
• useToken — Resolves an ERC-20’s identity and display metadata.
• useTokenPrice — Fetches a token’s USD price through the SDK’s oracle read.
• useTokenUsdValues — Fetches the USD-equivalent value of each entry’s balance through one SDK batch read.
• useTokenPairPrice — Fetches the oracle exchange rate between two tokens.
• useRequiredCollateral — Fetches the minimum collateral a dynamic LOC must lock to clear the pair’s creation collateral factor.
• useCollateralFactor — Fetches the current collateral factor for an ordered token pair.
• useRiskFactor — Computes risk factor data for the provided dynamic LOC values.
• useLiquidationDetails — Computes liquidation-facing values used by dynamic LOC UIs.

Workflow hooks

• useCreateLOCWorkflow — Headless create-LOC orchestration using the canonical workflow-hook envelope.
• useModifyLOCCollateralWorkflow — Headless modify-collateral orchestration using the canonical workflow-hook envelope.
• useExtendLOCWorkflow — Headless extend-LOC orchestration using the canonical workflow-hook envelope.
• useDepositToVaultWorkflow — Validates and prepares a CollateralVault deposit.
• useWithdrawFromVaultWorkflow — Validates and prepares a CollateralVault withdrawal.
• useCancelLOCWorkflow — Validates and prepares a direct LOC cancellation.
• useCancelLOCsAndWithdrawWorkflow — Validates and prepares a sequential cancel-and-withdraw: cancel the listed LOCs, then withdraw the collateral they release.
• useCancelLOCAuthorizationWorkflow — Validates and prepares the beneficiary’s signed cancellation authorization — the EIP-712 payload that lets someone other than the…
• useRedeemLOCAuthorizationWorkflow — Validates and prepares the beneficiary’s signed redemption authorization — the EIP-712 payload a holder submits to redeem against the LOC.
• useModifyVaultAllowanceAuthorizationWorkflow — Validates and prepares a signed authorization adjusting a collateralizable contract’s CollateralVault allowance.
• useVaultDepositAuthorizationWorkflow — Validates and prepares a signed authorization permitting a collateralizable contract to deposit into the CollateralVault on the signer’s…
• useInvalidateVaultNoncesWorkflow — Validates and prepares the transaction that burns CollateralVault authorization nonces.
• useWorkflowLifecycle — Beta

Validation

• useIncrementalValidation — Incrementally validates form values against a set of rules.

Workflow settlement

• WorkflowSettlement — Beta
• getWorkflowSettlementMessage — Beta
• getWalletFailureSettlement — Beta
• toWorkflowSettlement — Beta
• UnconfirmedSend — Beta
• describeUnconfirmedSend — Beta
• getUnconfirmedSend — Beta

Utilities

• useResolveAddress — Hook that returns the resolveAddress action configured with the current Anvil SDK context.
• useEnsName — Hook that returns the getEnsName action configured with the current Anvil SDK context.
• useNowSeconds — The current Unix time in whole seconds, re-rendering only at the moments a caller names.
• bindOnAccountChanged — Binds an event listener to the accountsChanged event of the injected browser wallet (window.ethereum), if it exists.
• unbindOnAccountChanged — Unbinds an event listener from the accountsChanged event of the injected browser wallet (window.ethereum), if it exists.

Supporting types and functions in this group are not listed here; each has its own page, listed with the group in the sidebar.