Interface ObservabilityHooks

Lifecycle callbacks that the SDK invokes around every mutating method (state-changing contract calls) and every RPC call.

All hooks are optional — supply only the callbacks you need. Hooks must not throw; any uncaught exception is silently swallowed so that instrumentation never breaks the core SDK flow.

Example

const hooks: ObservabilityHooks = {
  onTransactionStart: (method, params) => metrics.increment(`sdk.tx.${method}`),
  onTransactionSuccess: (method, result, durationMs) => {
    metrics.histogram('sdk.tx.duration', durationMs, { method });
  },
  onTransactionError: (method, error, durationMs) => {
    logger.error({ method, error, durationMs });
  },
  onRpcCall: (method, params, durationMs) => {
    metrics.histogram('sdk.rpc.duration', durationMs, { method });
  },
};
interface ObservabilityHooks {
    onRpcCall?: ((method: string, params: unknown, durationMs: number) => void);
    onTransactionError?: ((method: string, error: Error, durationMs: number) => void);
    onTransactionStart?: ((method: string, params: unknown) => void);
    onTransactionSuccess?: ((method: string, result: unknown, durationMs: number) => void);
}

Properties

onRpcCall? onTransactionError? onTransactionStart? onTransactionSuccess?

Properties

OptionalonRpcCall

onRpcCall?: ((method: string, params: unknown, durationMs: number) => void)

Called after every internal RPC call (simulation, account fetch, send, etc.) whether it succeeded or failed. This provides fine-grained visibility into how long each network round-trip took.

Type declaration

    • (method, params, durationMs): void

    • Parameters

      • method: string

        A descriptive label for the RPC call (e.g. 'simulateTransaction', 'getAccount', 'sendTransaction').

      • params: unknown

        Relevant call parameters for correlation (e.g. contract method name).

      • durationMs: number

        Wall-clock milliseconds the call took.

      Returns void

OptionalonTransactionError

onTransactionError?: ((method: string, error: Error, durationMs: number) => void)

Called when a mutating SDK method throws an unexpected exception. Normal status: 'failed' returns do NOT trigger this; only unhandled exceptions propagated out of the method do.

Type declaration

    • (method, error, durationMs): void

    • Parameters

      • method: string

        The SDK method name.

      • error: Error

        The caught exception.

      • durationMs: number

        Wall-clock milliseconds elapsed before the throw.

      Returns void

OptionalonTransactionStart

onTransactionStart?: ((method: string, params: unknown) => void)

Called immediately before a mutating SDK method is executed (before any RPC calls or transaction building takes place).

Type declaration

    • (method, params): void

    • Parameters

      • method: string

        The SDK method name (e.g. 'fundCAddress').

      • params: unknown

        The parameters passed to the method (sanitised — keypairs are excluded, only plain option objects are forwarded).

      Returns void

OptionalonTransactionSuccess

onTransactionSuccess?: ((method: string, result: unknown, durationMs: number) => void)

Called when a mutating SDK method completes without throwing. Note: status: 'failed' results still trigger this hook; check result.status if you want to distinguish submission failures from network errors.

Type declaration

    • (method, result, durationMs): void

    • Parameters

      • method: string

        The SDK method name.

      • result: unknown

        The TransactionResult (or array of results for batch calls).

      • durationMs: number

        Wall-clock milliseconds from onTransactionStart to completion.

      Returns void

Settings

Member Visibility

On This Page

Properties