v2.0.0-rc.1 release candidate
The API is frozen and later candidates carry fixes only, except the receipt-free and Safe create surface of /fhe-airdrop, which is @beta. Published on the next dist-tag; latest stays on 1.6.0 until 2.0.0.Testnet Faucet 2.0 · Errors · 16@tokenops/sdk/testnet-faucet
Testnet Faucet 2.0 errors you can catch by class.
No roles, no pause, no encryptor: faucet failures cluster around the chain, the deployment address, the wallet, and the one supply cap on the confidential mint. Every class below is exported from both /testnet-faucet and /testnet-faucet/react.
For the catch-ladder pattern + how SDK-level and generic-fallback errors fit alongside these, read Concepts › Typed errors + recovery.
| Class | When thrown | Recovery |
|---|---|---|
| UnsupportedChainError | The client was built on mainnet or any chain outside TESTNET_FAUCET_SUPPORTED_CHAIN_IDS. context carries chainId, method ("TestnetFaucetClient") and a hint that says the faucet runs on Sepolia only and how to point the clients there. In React the hooks catch it as resolutionError: reads stay disabled and the mint hooks reject with it. | Gate the UI with isTestnetFaucetChainId and prompt a switch to Sepolia. The chainId option only selects addresses; it does not change the RPC the clients query. useMintConfidential |
| DeploymentAddressUnavailableError | No CTTT address is registered for the resolved chain and none was passed as address (local Anvil, for example). context.reason is chain-id-missing, registry-not-deployed or registry-unknown-chain. | Pass address to the client or hook options, or resolve the Sepolia deployment with requireConfidentialTestTokenAddress. The TTT backing token is read from the CTTT wrapper, so there is no second address to supply. |
| FaucetSupplyExhaustedError | mintConfidential would push the wrapper's backing past maxTotalSupply (type(uint64).max). Mapped from ERC7984TotalSupplyOverflow. A shared ceiling anyone can hit, not a per-caller limit; context names the method and contractAddress. | Compare useInferredTotalSupply against useMaxTotalSupply before minting and lower the amount. Capacity frees up only when CTTT is unwrapped. TTT mints are not subject to the cap. useMaxTotalSupply |
| InvalidArgumentError | A mint failed validation before dispatch: a zero-address recipient, a CTTT amount outside uint64, a TTT amount outside uint256, a per-call gas that is not a positive bigint, or a negative or non-finite gasHeadroomPercent. | Validate amounts against each token's decimals (CTTT 6, TTT 18) and keep confidential amounts within uint64. |
| TokenOpsValidationError | Shares the TOKENOPS_INVALID_ARGUMENT code with InvalidArgumentError and carries a free-form context. New as a /testnet-faucet/react re-export, so a React-only import can catch it by class. | Branch on error.code === "TOKENOPS_INVALID_ARGUMENT" to handle both validation classes at once. |
| MissingWalletClientError | A mint ran on a client created without a walletClient. | Construct the client with a walletClient, or use the mint hooks, which read the connected wagmi wallet. useMintUnderlying |
| MissingAccountError | A mint or balance read could not resolve an account: no account argument and no default account on the walletClient. | Pass account, set a default account on the walletClient, or connect a wallet. |
| WalletChainMismatchError | The wallet's chain is not the public client's chain. Every SDK write refuses it before estimating gas, so nothing is sent to the wrong network. | Ask the wallet to switch to Sepolia, or build both clients on the same chain. |
| ReceiptEventNotFoundError | mintConfidential's receipt held no ConfidentialMint event from the configured address. | Inspect the transaction by hash and confirm the configured address is the deployed CTTT proxy. |
| ReceiptEventAmbiguousError | The CTTT mint receipt held more than one matching ConfidentialMint event, so the SDK could not pick one. | Usually a non-canonical token address or a forwarder in the path: verify the configured CTTT address. |
| ContractRevertError | The preflight simulate or the send hit a decoded revert that no faucet or shared class maps. context carries method, contractAddress, revertName, revertSelector, revertArgs and revertReason. | Branch on context.revertName; the original viem error is on err.cause. |
| TokenOpsContractError | A mint transaction was mined but its receipt status is reverted. context carries contract, call ("mint") and tx. | Inspect the transaction by hash. Reverts caught before sending surface as ContractRevertError or a typed class instead. |
| WalletRejectedError | The user cancelled the mint in the wallet. | Treat it as a benign cancel: re-enable the mint button and let the user retry. |
| InsufficientGasFundsError | The sending account cannot pay for gas. | Fund the account with Sepolia ETH and retry. |
| NetworkError | The RPC request failed at the HTTP layer while sending the mint. context.statusCode carries the HTTP status. | Retry, or point the clients at a healthier RPC. |
| UnknownWriteFailureError | The send failed in a way the SDK could not classify as a revert, rejection, gas or network failure. | Inspect err.cause for the underlying error. |
TokenOpsSdkError and carries the offending values under err.context — render specific messages instead of generic "transaction failed."Read the catch ladder