waitTransactionStateread-only

Wait until a transaction is in a particular state. The operation blocks until the transaction reaches the requested state, an error occurs, or the timeout expires.

Request:

The request args must be a WaitTransactionStateRequest object.

Response:

On success, the result is a WaitTransactionStateResponse object.

Details:

This is a long-polling operation: it returns once the transaction’s state matches txState, matches one of the bailStates, or (with bailOnError) an error is recorded for the transaction. The response’s matched field says which of the two sets of states ended the wait.

The txState and bailStates fields are TestingWaitTxStateSpec values: a TransactionStatePattern or a list of patterns (matching when any pattern matches), a wallet-internal numeric state ID, or one of the shorthands nonpending (any major state other than pending) and final (any final major state). In a pattern, major, minor and working accept the wildcard *; a pattern without minor only matches states that have no minor state, while a pattern without working matches regardless of the flag.

Without bailStates or bailOnError, a transaction that reaches a state it will never leave keeps the caller waiting until the timeout expires; the wait then fails with GENERIC_TIMEOUT.

If no transaction with the given transactionId exists, the wait fails with WALLET_TRANSACTION_NOT_FOUND instead of waiting.

When progressToken is set, the wait reports request progress notifications (including recorded transaction errors with their retry counter and remaining retry delay) and can be cancelled with cancelProgressToken or nudged with retryProgressTokenNow. Cancellation fails the wait with WALLET_CORE_REQUEST_CANCELLED; it stops only the wait, not the transaction.

interface WaitTransactionStateRequest {
  transactionId: TransactionIdStr;

  // Receive request progress notifications and control this wait
  // via cancelProgressToken/retryProgressTokenNow.
  // Cancellation stops only the wait.  Retry-now retries the
  // transaction if its current state allows it, without
  // restarting the wait or extending its timeout.  Transaction
  // errors are reported with their recorded retry counter and
  // remaining delay; without a recorded error retry, the counter
  // is zero and the delay is "forever".
  progressToken?: string;

  // Additional identifier that is used in the logs to easily
  // find the status of the particular wait request.
  logId?: string;

  // After the timeout has passed, give up on waiting for the
  // desired state and raise an error instead.
  timeout?: DurationUnitSpec;

  // If set to true, wait until the desired state is reached
  // with an error.
  requireError?: boolean;

  // State(s) to wait for.
  txState: TestingWaitTxStateSpec;

  // States that end the wait even though they are not the state
  // that was waited for.  The response says which of the two
  // sets matched.  Without this, a transaction that ends up in
  // a state it will never leave keeps the caller waiting until
  // the timeout.
  bailStates?: TestingWaitTxStateSpec;

  // End the wait as soon as an error is recorded for the
  // transaction.  Beware that this includes transient errors of
  // retried operations, which are cleared again once the
  // operation succeeds.
  bailOnError?: boolean;
}

interface WaitTransactionStateResponse {
  // Which set of states ended the wait: the requested state or
  // one of the bail states.
  matched: "target" | "bail";

  // State that ended the wait.
  txState: TransactionState;

  // Wallet-internal state ID, only used for debugging and
  // testing.
  stId: number;
}

// State(s) to wait for: a plain pattern or a list of patterns
// (matching any of them), a wallet-internal numeric state ID, or
// one of the shorthands for a category of states.
type TestingWaitTxStateSpec =
  | TransactionStatePattern
  | TransactionStatePattern[]
  | number
  | "nonpending"
  | "final";

interface TransactionStatePattern {
  major: TransactionMajorState | TransactionStateWildcard;

  minor?: TransactionMinorState | TransactionStateWildcard;

  // Required value of the "working" flag of the transaction
  // state.  A transaction state without the flag counts as
  // false.  If left undefined, the flag is not taken into
  // account when matching, i.e. it behaves like a wildcard.
  working?: boolean | TransactionStateWildcard;
}

type TransactionStateWildcard = "*";

// A duration given as a sum of the specified units; used for
// timeouts.
interface DurationUnitSpec {
  seconds?: number;

  minutes?: number;

  hours?: number;

  days?: number;

  months?: number;

  years?: number;
}