coin-recovery-progress

Emitted while the testingRecoverCoins operation scans an exchange for coins that belong to the wallet and recovers them. The progressToken matches the progress token of the initiating request.

The payload is a CoinRecoveryProgressNotification object.

interface CoinRecoveryProgressNotification {
  type: NotificationType.CoinRecoveryProgress;
  exchangeBaseUrl: string;
  progressToken: string;
  phase: CoinRecoveryPhase;
  numChecked: number;
  numDiscovered: number;
  numQueued: number;
  numRecovered: number;
  recoveredAmount: AmountString;
  numIssues: number;
}

type CoinRecoveryPhase =
  | "starting"
  | "history"
  | "derive"
  | "melt"
  | "reveal"
  | "refresh"
  | "complete"
  | "incomplete"
  | "failed"
  | "cancelled";

balance-change

Invalidates balance data, including flags and refresh information. The monetary amounts need not have changed, for example when a refresh cost becomes ready. Clients should re-query getBalances in response.

The payload is a BalanceChangeNotification object.

interface BalanceChangeNotification {
  type: NotificationType.BalanceChange;

  // If set to true, the balance change is internal to the wallet
  // and not visible to the user.  (For example when the material
  // balance changes via a refresh, but the available balance
  // stays the same.)
  isInternal?: boolean;

  // Transaction ID of the transaction that caused the balance
  // update.  Only used as a hint for debugging, should not be
  // relied upon by clients.
  hintTransactionId: string;
}

bank-account-change

Emitted when a bank account known to the wallet was added, changed or deleted. Clients should re-query listBankAccounts.

The payload is a BankAccountChangeNotification object.

interface BankAccountChangeNotification {
  type: NotificationType.BankAccountChange;

  // ID of the affected bank account.
  bankAccountId: string;
}

backup-error

Signals the failure of a backup operation. The current wallet-core implementation does not emit this notification.

The payload is a BackupOperationErrorNotification object.

interface BackupOperationErrorNotification {
  type: NotificationType.BackupOperationError;
  error: TalerErrorDetail;
}

contact-added

Emitted when a contact was added to the wallet’s address book. Clients should re-query getContacts.

The payload is a ContactAddedNotification object.

interface ContactAddedNotification {
  type: NotificationType.ContactAdded;

  // The contact that was added.
  contact: ContactEntry;
}

contact-deleted

Emitted when a contact was deleted from the wallet’s address book. Clients should re-query getContacts.

The payload is a ContactDeletedNotification object.

interface ContactDeletedNotification {
  type: NotificationType.ContactDeleted;

  // The contact that was deleted.
  contact: ContactEntry;
}

mailbox-message-added

Emitted when a message was added to the wallet’s mailbox, for example a payment request received from another wallet user.

The payload is a MailboxMessageAddedNotification object.

interface MailboxMessageAddedNotification {
  type: NotificationType.MailboxMessageAdded;

  // The message that was added.
  message: MailboxMessageRecord;
}

mailbox-message-deleted

Emitted when a message was deleted from the wallet’s mailbox.

The payload is a MailboxMessageDeletedNotification object.

interface MailboxMessageDeletedNotification {
  type: NotificationType.MailboxMessageDeleted;

  // The message that was deleted.
  message: MailboxMessageRecord;
}

transaction-state-transition

Emitted when a transaction moves from one state to another. Clients should re-query the affected transaction; the causeHint is only a debugging aid and must not be relied upon.

The payload is a TransactionStateTransitionNotification object.

interface TransactionStateTransitionNotification {
  type: NotificationType.TransactionStateTransition;

  // Identifier of the affected transaction.
  transactionId: string;

  // A hint as to why the transition happened.
  // Should not be relied upon by clients.
  causeHint: string | undefined;

  // State before the transition.
  oldTxState: TransactionState;

  // State after the transition.
  newTxState: TransactionState;

  // Internal ID of the new state.  Must not be used by the UI,
  // only used for testing.
  newStId: number;

  // Short summary of the error for an error transition.
  errorInfo?: ErrorInfoSummary;
}

interface ErrorInfoSummary {
  code: number;
  hint?: string;
  message?: string;
}

exchange-state-transition

Emitted when the state of an exchange entry changes. If oldExchangeState is missing, the entry was newly created; if newExchangeState is missing, the entry was deleted.

The payload is an ExchangeStateTransitionNotification object.

interface ExchangeStateTransitionNotification {
  type: NotificationType.ExchangeStateTransition;

  // Identification of the exchange entry that this
  // notification is about.
  exchangeBaseUrl: string;

  // A hint as to why the transition happened.
  // Should not be relied upon by clients.
  causeHint: string | undefined;

  // If missing, the notification means that
  // the exchange entry is newly created.
  oldExchangeState?: ExchangeEntryState;

  // New state of the exchange.
  // If missing, the exchange entry got deleted.
  newExchangeState?: ExchangeEntryState;

  // Summary of the error that occurred when trying to update
  // the exchange entry, if applicable.
  errorInfo?: ErrorInfoSummary;
}

interface ExchangeEntryState {
  // Status of the exchange's terms of service.
  tosStatus: ExchangeTosStatus;

  // Lifecycle status of the exchange entry.
  exchangeEntryStatus: ExchangeEntryStatus;

  // Status of the last update of the exchange's key material.
  exchangeUpdateStatus: ExchangeUpdateStatus;
}

idle

Emitted when wallet-core becomes idle, that is when no background task that keeps the wallet active is running anymore. Mainly useful for test harnesses that wait for the wallet to quiesce.

The payload is an IdleNotification object.

interface IdleNotification {
  type: NotificationType.Idle;
}

task-observability-event

Reports a single observability event of a background task. These notifications are only emitted when the testing option emitObservabilityEvents is enabled in the wallet run configuration.

The payload is a TaskProgressNotification object.

interface TaskProgressNotification {
  type: NotificationType.TaskObservabilityEvent;
  taskId: string;
  event: ObservabilityEvent;
}

type ObservabilityEvent =
  | {
      id: string;
      when: AbsoluteTime;
      type: ObservabilityEventType.HttpFetchStart;
      url: string;
      longPolling: boolean;
    }
  | {
      id: string;
      when: AbsoluteTime;
      type: ObservabilityEventType.HttpFetchFinishSuccess;
      url: string;
      status: number;
      durationMs: number;
      longPolling: boolean;
    }
  | {
      id: string;
      when: AbsoluteTime;
      type: ObservabilityEventType.HttpFetchFinishError;
      url: string;
      error: TalerErrorDetail;
      durationMs: number;
      longPolling: boolean;
    }
  | {
      type: ObservabilityEventType.DbQueryStart;
      name: string;
      location: string;
    }
  | {
      type: ObservabilityEventType.DbQueryFinishSuccess;
      name: string;
      location: string;
      durationMs: number;
    }
  | {
      type: ObservabilityEventType.DbQueryFinishError;
      name: string;
      location: string;
      error: TalerErrorDetail;
      durationMs: number;
    }
  | {
      type: ObservabilityEventType.RequestStart;
      name: string;
    }
  | {
      type: ObservabilityEventType.RequestFinishSuccess;
      operation: string;
      requestId: string;
      durationMs: number;
    }
  | {
      type: ObservabilityEventType.RequestFinishError;
      operation: string;
      requestId: string;
      durationMs: number;
    }
  | {
      type: ObservabilityEventType.TaskStart;
      taskId: string;
    }
  | {
      type: ObservabilityEventType.TaskStop;
      taskId: string;
    }
  | {
      type: ObservabilityEventType.TaskReset;
      taskId: string;
    }
  | {
      type: ObservabilityEventType.DeclareTaskDependency;
      taskId: string;
    }
  | {
      type: ObservabilityEventType.CryptoStart;
      operation: string;
    }
  | {
      type: ObservabilityEventType.CryptoFinishSuccess;
      operation: string;
      durationMs: number;
    }
  | {
      type: ObservabilityEventType.CryptoFinishError;
      operation: string;
      durationMs: number;
    }
  | {
      type: ObservabilityEventType.ShepherdTaskResult;
      taskId: string;
      resultType: string;
      durationMs: number;
    }
  | {
      type: ObservabilityEventType.Message;
      contents: string;
    }
  | {
      type: ObservabilityEventType.DeclareConcernsTransaction;
      transactionId: TransactionIdStr;
    };

enum ObservabilityEventType {
  HttpFetchStart = "http-fetch-start",
  HttpFetchFinishError = "http-fetch-finish-error",
  HttpFetchFinishSuccess = "http-fetch-finish-success",
  DbQueryStart = "db-query-start",
  DbQueryFinishSuccess = "db-query-finish-success",
  DbQueryFinishError = "db-query-finish-error",
  RequestStart = "request-start",
  RequestFinishSuccess = "request-finish-success",
  RequestFinishError = "request-finish-error",
  TaskStart = "task-start",
  TaskStop = "task-stop",
  TaskReset = "task-reset",
  ShepherdTaskResult = "shepherd-task-result",
  DeclareTaskDependency = "declare-task-dependency",
  CryptoStart = "crypto-start",
  CryptoFinishSuccess = "crypto-finish-success",
  CryptoFinishError = "crypto-finish-error",
  Message = "message",

  // Declares that an observability event is relevant to a particular
  // transaction.  If emitted from a request/task, all past/future
  // events for that request/task should be shown for the
  // transaction as well.
  DeclareConcernsTransaction = "declare-concerns-transaction",
}

request-observability-event

Reports a single observability event of an API request; requestId matches the id of the corresponding request envelope. These notifications are only emitted when the testing option emitObservabilityEvents is enabled in the wallet run configuration.

The payload is a RequestObservabilityEventNotification object.

interface RequestObservabilityEventNotification {
  type: NotificationType.RequestObservabilityEvent;
  requestId: string;
  operation: string;
  event: ObservabilityEvent;
}

request-progress-error

Emitted when an attempt of a long-running request with a progressToken failed and will be retried automatically after nextRetryDelay. The client can cancel the request with cancelProgressToken or trigger an immediate retry with retryProgressTokenNow.

The payload is a RequestProgressNotification object.

interface RequestProgressNotification {
  type: NotificationType.RequestProgressError;
  progressToken: string;
  operation: string;
  error: TalerErrorDetail;
  nextRetryDelay: TalerProtocolDuration;
  retryCounter: number;
}

request-progress-phase

Emitted when a long-running request with a progressToken takes longer than expected: delayed after about five seconds, stalled after about ten seconds (at which point the user may want to retry), and done when the request finished and no further progress notifications will be sent.

The payload is a RequestProgressPhaseNotification object.

interface RequestProgressPhaseNotification {
  type: NotificationType.RequestProgressPhase;
  progressToken: string;
  operation: string;

  // delayed: request is taking longer than expected (usually
  //   after 5s)
  // stalled: request is taking *very* long, user can retry
  //   (usually after 10s)
  // done: no further progress notifications will be sent
  phase: "delayed" | "stalled" | "done";
}

database-maintenance-progress

Emitted while startup fixups or a database migration hold the database gate, reporting progress of the maintenance operation. Intermediate updates may be coalesced by wallet-core, but the first and the terminal (complete or failed) events are always delivered.

The payload is a DatabaseMaintenanceProgressNotification object.

interface DatabaseMaintenanceProgressNotification {
  type: NotificationType.DatabaseMaintenanceProgress;
  operation:
    | "indexeddb-fixup"
    | "indexeddb-to-native-migration"
    | "cross-backend-import";

  // Token of the API request that initiated this operation,
  // when available.
  progressToken?: string;

  phase: "fixup" | "copy" | "verify" | "complete" | "failed";

  // Current fixup or backend-neutral store, when one is active.
  step?: string;

  completedSteps: number;
  totalSteps: number;

  // Records completed in the current phase across the
  // whole migration.
  processedRecords?: number;

  // Total records in the whole migration, known before
  // copying starts.
  totalRecords?: number;

  // Rough overall migration completion, from 0 through 100.
  completionPercent?: number;

  // Why the maintenance operation failed.  Present when
  // phase is "failed".
  error?: TalerErrorDetail;
}