Error Handling

Contract calls can revert with on-chain errors. The SDK decodes raw revert data into typed error classes with decoded arguments and human-readable recovery hints.

Decoding revert errors

Use parseContractError() to decode raw revert data from a failed transaction or simulation:

import { parseContractError, getRevertData } from '@oaknetwork/contracts-sdk';

function handleError(err) {
  // If the error is already a typed SDK error (thrown by simulate methods)
  if (typeof err?.recoveryHint === 'string') {
    console.error('Reverted:', err.name);
    console.error('Args:', err.args);
    console.error('Hint:', err.recoveryHint);
    return;
  }
  // Otherwise extract raw revert hex from the viem error chain and decode it
  const revertData = getRevertData(err);
  const parsed = parseContractError(revertData ?? '');
  if (parsed) {
    console.error('Reverted:', parsed.name);
    console.error('Args:', parsed.args);
    if (parsed.recoveryHint) console.error('Hint:', parsed.recoveryHint);
    return;
  }
  console.error('Unknown error:', err.message);
}

try {
  const txHash = await factory.createCampaign({ ... });
} catch (err) {
  handleError(err);
}

getRevertData(error)

Walks the error cause chain and extracts the first 0x-prefixed hex string from error.data. Returns null if no revert data is found.

parseContractError(revertData)

Takes a hex string (selector + encoded args) and returns a typed ContractErrorBase or null if the error is not recognized.

ContractErrorBase

All typed errors implement this interface:

interface ContractErrorBase {
  readonly name: string;                    // e.g. "GlobalParamsUnauthorized"
  readonly args: Record<string, unknown>;   // decoded error arguments
  readonly recoveryHint?: string;           // human-readable suggestion
}

Simulation with error decoding

Use simulateWithErrorDecode() to wrap a simulateContract call. It catches reverts, decodes them, and re-throws as typed SDK errors:

import { simulateWithErrorDecode } from '@oaknetwork/contracts-sdk';

try {
  await simulateWithErrorDecode(() =>
    gp.simulate.enlistPlatform(platformHash, admin, fee, adapter)
  );
  // Safe to send
  const txHash = await gp.enlistPlatform(platformHash, admin, fee, adapter);
} catch (err) {
  if ('recoveryHint' in err) {
    console.error(err.name, '-', err.recoveryHint);
  }
}

Or use the simulate namespace directly on any entity — it already throws typed errors:

try {
  await gp.simulate.enlistPlatform(platformHash, admin, fee, adapter);
} catch (err) {
  console.error(err.name, err.recoveryHint);
}

Error types by contract

GlobalParams errors

Error	When it occurs	Recovery hint
`GlobalParamsInvalidInput`	Invalid address, fee, or bytes input	Check addresses, fee percent, and platform bytes
`GlobalParamsPlatformAlreadyListed`	Enlisting a platform that exists	Use a different platform hash or update
`GlobalParamsPlatformNotListed`	Operating on unlisted platform	Enlist the platform first
`GlobalParamsUnauthorized`	Caller is not protocol admin	Use the admin account
`GlobalParamsPlatformAdminNotSet`	Platform admin not configured	Set the platform admin address first
`GlobalParamsPlatformFeePercentIsZero`	Zero fee percent	Fee must be greater than zero
`GlobalParamsCurrencyHasNoTokens`	Currency has no accepted tokens	Add at least one token
`GlobalParamsTokenNotInCurrency`	Token not in currency list	Use an approved token
`GlobalParamsPlatformLineItemTypeNotFound`	Line item type not registered	Register the line item type first
`GlobalParamsPlatformDataAlreadySet`	Data key already exists	Use a different key
`GlobalParamsPlatformDataNotSet`	Data key not found	Add platform data first
`GlobalParamsPlatformDataSlotTaken`	Data slot occupied	Use a different key
`GlobalParamsCurrencyTokenLengthMismatch`	Array length mismatch	Match currencies and tokens array lengths

CampaignInfoFactory errors

Error	When it occurs	Recovery hint
`CampaignInfoFactoryInvalidInput`	Invalid campaign creation params	Check creator, platforms, and data
`CampaignInfoFactoryPlatformNotListed`	Selected platform not in GlobalParams	Enlist the platform first
`CampaignInfoFactoryCampaignWithSameIdentifierExists`	Duplicate identifier hash	Use a different identifier
`CampaignInfoFactoryCampaignInitializationFailed`	Clone failed to initialize	Check campaign data and implementation
`CampaignInfoInvalidTokenList`	Currency tokens don’t match GlobalParams	Fix token list for campaign currency

CampaignInfo errors

Error	When it occurs	Recovery hint
`CampaignInfoInvalidInput`	Invalid update input	Check input values
`CampaignInfoIsLocked`	Campaign is locked	Cannot modify locked campaigns
`CampaignInfoUnauthorized`	Caller not authorized	Use the campaign owner account
`CampaignInfoPlatformNotSelected`	Platform not selected	Select the platform first
`CampaignInfoPlatformAlreadyApproved`	Platform already approved	Platform is already set up
`CampaignInfoInvalidPlatformUpdate`	Invalid platform update	Check platform hash and data

PaymentTreasury errors

Error	When it occurs	Recovery hint
`PaymentTreasuryInvalidInput`	Invalid payment parameters	Check payment data
`PaymentTreasuryPaymentAlreadyExist`	Duplicate payment ID	Use a unique payment ID
`PaymentTreasuryPaymentNotExist`	Payment not found	Check the payment ID
`PaymentTreasuryPaymentAlreadyConfirmed`	Payment already confirmed	Cannot re-confirm
`PaymentTreasuryPaymentAlreadyExpired`	Payment expired	Create a new payment
`PaymentTreasuryPaymentNotConfirmed`	Payment not yet confirmed	Confirm the payment first
`PaymentTreasuryPaymentNotClaimable`	Payment does not meet refund eligibility	May not be confirmed, expired, or claim window not reached
`PaymentTreasuryTokenNotAccepted`	Token not accepted	Use an accepted token
`PaymentTreasuryUnAuthorized`	Caller not authorized	Use authorized account
`PaymentTreasuryCampaignInfoIsPaused`	Campaign is paused	Unpause the campaign first
`PaymentTreasurySuccessConditionNotFulfilled`	Goal not reached	Goal amount must be reached before withdrawing
`PaymentTreasuryCryptoPayment`	Wrong flow for crypto payment	Use `processCryptoPayment()` instead
`PaymentTreasuryInsufficientBalance`	Insufficient token balance	Fund the account
`PaymentTreasuryInsufficientFundsForFee`	Insufficient funds for withdrawal fee	Ensure treasury has enough balance for the fee
`PaymentTreasuryFeeNotDisbursed`	Fees not yet disbursed	Call `disburseFees()` first
`PaymentTreasuryAlreadyWithdrawn`	Already withdrawn	Cannot withdraw twice
`PaymentTreasuryExpirationExceedsMax`	Payment expiration too long	Use a shorter expiration time
`PaymentTreasuryClaimWindowNotReached`	Claim attempted too early	Wait until the claimableAt timestamp
`PaymentTreasuryNoFundsToClaim`	No funds available	No refundable funds

AllOrNothing errors

Error	When it occurs	Recovery hint
`AllOrNothingInvalidInput`	Invalid parameters	Check input values
`AllOrNothingNotSuccessful`	Goal not met	Cannot withdraw — goal was not reached
`AllOrNothingNotClaimable`	Refund not available	Refund conditions not met
`AllOrNothingRewardExists`	Duplicate reward name	Use a different reward name
`AllOrNothingTokenNotAccepted`	Token not accepted	Use an accepted token
`AllOrNothingUnAuthorized`	Caller not authorized	Use authorized account
`AllOrNothingFeeAlreadyDisbursed`	Fees already disbursed	Already processed
`AllOrNothingFeeNotDisbursed`	Fees not disbursed	Call `disburseFees()` first
`AllOrNothingTransferFailed`	Token transfer failed	Check balances and allowances
`TreasurySuccessConditionNotFulfilled`	Goal not met	Goal amount must be reached before withdrawing

KeepWhatsRaised errors

Error	When it occurs	Recovery hint
`KeepWhatsRaisedInvalidInput`	Invalid parameters	Check input values
`KeepWhatsRaisedConfigLocked`	Configuration is locked	Wait for lock period to expire
`KeepWhatsRaisedDisabled`	Feature is disabled	Cannot perform this operation
`KeepWhatsRaisedAlreadyEnabled`	Already enabled	Already configured
`KeepWhatsRaisedAlreadyClaimed`	Already claimed	Cannot claim twice
`KeepWhatsRaisedAlreadyWithdrawn`	Already withdrawn	Cannot withdraw twice
`KeepWhatsRaisedNotClaimable`	Not claimable	Conditions not met for claim
`KeepWhatsRaisedNotClaimableAdmin`	Admin claim conditions not met	Ensure campaign is in the correct state
`KeepWhatsRaisedRewardExists`	Duplicate reward name	Use a different reward name
`KeepWhatsRaisedTokenNotAccepted`	Token not accepted	Use an accepted token
`KeepWhatsRaisedUnAuthorized`	Caller not authorized	Use authorized account
`KeepWhatsRaisedPledgeAlreadyProcessed`	Pledge already processed	Cannot re-process
`KeepWhatsRaisedInsufficientFundsForFee`	Insufficient funds for fee	Ensure sufficient balance
`KeepWhatsRaisedInsufficientFundsForWithdrawalAndFee`	Insufficient funds for withdrawal + fee	Reduce withdrawal or wait for more pledges
`KeepWhatsRaisedDisbursementBlocked`	Disbursement blocked	Conditions not met

TreasuryFactory errors

Error	When it occurs	Recovery hint
`TreasuryFactoryUnauthorized`	Caller not authorized	Use authorized account
`TreasuryFactoryInvalidAddress`	Invalid contract address	Check the address
`TreasuryFactoryInvalidKey`	Invalid implementation key	Check implementation ID
`TreasuryFactoryImplementationNotSet`	Implementation not registered	Register the implementation first
`TreasuryFactoryImplementationNotSetOrApproved`	Not set or not approved	Register and approve the implementation
`TreasuryFactoryTreasuryCreationFailed`	Treasury deploy failed	Check campaign and implementation
`TreasuryFactoryTreasuryInitializationFailed`	Treasury init failed	Check configuration
`TreasuryFactorySettingPlatformInfoFailed`	Platform info update failed	Check platform configuration

Shared errors (cross-contract)

Error	When it occurs	Recovery hint
`AccessCheckerUnauthorized`	Generic access control failure	Check permissions
`AdminAccessCheckerUnauthorized`	Not an admin	Only admins can do this
`CurrentTimeIsGreater`	Timestamp in the past	Provide a future timestamp
`CurrentTimeIsLess`	Time not yet reached	Wait until the specified time
`CurrentTimeIsNotWithinRange`	Outside allowed time window	Operation only valid in range
`TreasuryCampaignInfoIsPaused`	Campaign is paused	Unpause the campaign first
`TreasuryFeeNotDisbursed`	Fees not disbursed	Call `disburseFees()` first
`TreasuryTransferFailed`	Token transfer failed	Check balances and allowances

Checking error types

import {
  GlobalParamsPlatformNotListedError,
  CampaignInfoFactoryInvalidInputError,
} from '@oaknetwork/contracts-sdk';

try {
  await factory.createCampaign(params);
} catch (err) {
  if (err instanceof GlobalParamsPlatformNotListedError) {
    console.error('Platform not listed:', err.args.platformHash);
  } else if (err instanceof CampaignInfoFactoryInvalidInputError) {
    console.error('Invalid input:', err.recoveryHint);
  }
}

getRecoveryHint

Convenience function to extract the recovery hint from any typed error:

import { getRecoveryHint } from '@oaknetwork/contracts-sdk';

const hint = getRecoveryHint(err);
if (hint) console.log('Suggestion:', hint);

Getting Started

Contract Entities

Examples

Use Cases

Reference

Decoding revert errors

getRevertData(error)

parseContractError(revertData)

ContractErrorBase

Simulation with error decoding

Error types by contract

GlobalParams errors

CampaignInfoFactory errors

CampaignInfo errors

PaymentTreasury errors

AllOrNothing errors

KeepWhatsRaised errors

TreasuryFactory errors

Shared errors (cross-contract)

Checking error types

getRecoveryHint

​Decoding revert errors

​getRevertData(error)

​parseContractError(revertData)

​ContractErrorBase

​Simulation with error decoding

​Error types by contract

​GlobalParams errors

​CampaignInfoFactory errors

​CampaignInfo errors

​PaymentTreasury errors

​AllOrNothing errors

​KeepWhatsRaised errors

​TreasuryFactory errors

​Shared errors (cross-contract)

​Checking error types

​getRecoveryHint

Decoding revert errors

getRevertData(error)

parseContractError(revertData)

ContractErrorBase

Simulation with error decoding

Error types by contract

GlobalParams errors

CampaignInfoFactory errors

CampaignInfo errors

PaymentTreasury errors

AllOrNothing errors

KeepWhatsRaised errors

TreasuryFactory errors

Shared errors (cross-contract)

Checking error types

getRecoveryHint