wait for condition

waitForCondition

waitForCondition repeatedly invokes an async check function until it returns something other than null or undefined, or until wall-clock time exceeds timeout. It lives in core/utils and is re-exported from the package root alongside other utilities.

Use it for orchestration scripts and integration tests when you must wait for ledger-visible state (wallet balance, contract visibility) without blocking the event loop with blind sleeps.

import { waitForCondition } from '@fairmint/canton-node-sdk';

Example — poll until balance positive

import { Canton, waitForCondition } from '@fairmint/canton-node-sdk';

const canton = new Canton({
  network: 'localnet',
  partyId: 'OWN_PARTY_ID',
});

const balanceStr = await waitForCondition(async () => {
  const wallet = await canton.validator.getWalletBalance();
  const total = wallet.effective_unlocked_qty ?? '0';
  const n = parseFloat(total);
  if (Number.isFinite(n) && n > 0) {
    return total;
  }
  return undefined;
}, {
  timeout: 60_000,
  interval: 2_000,
  timeoutMessage: 'Wallet still empty after 60s',
});

console.log('Funded:', balanceStr);

Parameters

waitForCondition(check, options?)

• check (required, () => Promise<T | null | undefined>) — Return null or undefined to keep polling; return any other value (including 0, false, '') to succeed immediately with that value.
• options.timeout (optional, number, default 30000) — Maximum milliseconds before failure.
• options.interval (optional, number, default 1000) — Delay between attempts.
• options.timeoutMessage (optional, string, default 'Timeout waiting for condition') — Message on the thrown OperationError.

Returns

Promise<T> — First successful non-null/non-undefined result.

Errors

On timeout throws OperationError with code OperationErrorCode.TRANSACTION_FAILED and context { timeoutMs } (see errors).

Pitfalls

• Tight loops: Very small interval against remote APIs can amplify rate limits — align with participant tolerance.
• Falsy success: Remember 0/false/'' stop polling; return null/undefined explicitly while waiting.

See also

• createParty — uses waitForCondition internally for transfer settlement.
• Errors — OperationError.

Source

src/core/utils/polling.ts on GitHub.