Class BackofficeWalletService

constructor

• new BackofficeWalletService(
      __namedParameters: {
          backofficeWalletQueryService: BackofficeWalletQueryService;
          db: B2bDatabase;
          solanaNonceAdminService: SolanaNonceAdminService;
          temporalClient: TemporalWorkflowClient<Workflows>;
          walletApiClient: WalletApiClient;
      },
  ): BackofficeWalletService

  Parameters

  • __namedParameters: {
        backofficeWalletQueryService: BackofficeWalletQueryService;
        db: B2bDatabase;
        solanaNonceAdminService: SolanaNonceAdminService;
        temporalClient: TemporalWorkflowClient<Workflows>;
        walletApiClient: WalletApiClient;
    }

    • backofficeWalletQueryService: BackofficeWalletQueryService

    • db: B2bDatabase

    • solanaNonceAdminService: SolanaNonceAdminService

      Reads a nonce row's pool hold, which ends its deadline.

    • temporalClient: TemporalWorkflowClient<Workflows>

      Starts each AWAITING_SIGNATURE row's deadline check, on the worker queue.

    • walletApiClient: WalletApiClient

  Returns BackofficeWalletService

Staticinstance

cancel

• cancel(
      __namedParameters: { reason: unknown; walletTransactionId: string },
  ): Promise<
      | { ok: true; value: { status: "CANCELLED" } }
      | { error: WalletApiCancelError; ok: false },
  >

  Call off a transaction that was never broadcast: the row and its nonce.

  Parameters

  • __namedParameters: { reason: unknown; walletTransactionId: string }

    • reason: unknown

      Why, stored on the row as its error.

    • walletTransactionId: string

  Returns Promise<
      | { ok: true; value: { status: "CANCELLED" } }
      | { error: WalletApiCancelError; ok: false },
  >

createNonce

• createNonce(
      __namedParameters: { reference: IdempotencyKey },
  ): Promise<
      | { ok: true; value: WalletApiNonceCreated }
      | { error: WalletApiNonceCreateError; ok: false },
  >

  Have wallet-api build and send a pool nonce account; callers never sign nonce instructions. Idempotent by reference; pooled once finalized.

  Parameters

  • __namedParameters: { reference: IdempotencyKey }

  Returns Promise<
      | { ok: true; value: WalletApiNonceCreated }
      | { error: WalletApiNonceCreateError; ok: false },
  >

deadline

• deadline(
      row: Pick<SelectWalletTransaction, "createdAt" | "solanaNonceAddress">,
  ): Promise<Instant>

  When row's deadline check fires: BLOCKHASH_DEADLINE after it was stored, or when its pool nonce's hold ends (nonceHoldDeadline). A hold already over fires at once, at the row's own createdAt so its workflow id is stable across retries.

  Parameters

  • row: Pick<SelectWalletTransaction, "createdAt" | "solanaNonceAddress">

  Returns Promise<Instant>

expire

• expire(
      __namedParameters: {
          nonceHoldLapsed: boolean;
          walletTransactionId: string;
      },
  ): Promise<
      | { ok: true; value: WalletApiExpired }
      | { error: ServiceError; ok: false },
  >

  Expire a row still awaiting a signature at its deadline: wallet-api cancels the row once its lifetime lapsed, else answers NOT_EXPIRED.

  Parameters

  • __namedParameters: { nonceHoldLapsed: boolean; walletTransactionId: string }

  Returns Promise<
      | { ok: true; value: WalletApiExpired }
      | { error: ServiceError; ok: false },
  >

getDeadlineRun

• getDeadlineRun(
      __namedParameters: { deadline: Instant; walletTransactionId: string },
  ): Promise<
      | TemporalWorkflowExecution & {
          pendingActivities: TemporalPendingActivity[];
      }
      | null,
  >

  The deadline check started for row walletTransactionId at deadline, if one was.

  Parameters

  • __namedParameters: { deadline: Instant; walletTransactionId: string }

  Returns Promise<
      | TemporalWorkflowExecution & {
          pendingActivities: TemporalPendingActivity[];
      }
      | null,
  >

releaseNonce

• releaseNonce(
      __namedParameters: { walletTransactionId: string },
  ): Promise<
      | { ok: true; value: { status: WalletApiReleaseStatus } }
      | { error: WalletApiReleaseError; ok: false },
  >

  End a nonced transaction and hand its pool nonce back. wallet-api settles it from the chain, advancing a nonce that never moved so the signed bytes cannot land later; PENDING means it has not settled yet.

  Parameters

  • __namedParameters: { walletTransactionId: string }

  Returns Promise<
      | { ok: true; value: { status: WalletApiReleaseStatus } }
      | { error: WalletApiReleaseError; ok: false },
  >

scheduleDeadline

• scheduleDeadline(
      __namedParameters: {
          deadline: Instant;
          recheckAt?: Instant;
          walletTransactionId: string;
      },
  ): Promise<Run>

  Start row walletTransactionId's deadline check at deadline, idempotent by both (and by recheckAt, the backstop's re-check after that run closed). Throws when the start fails, so the activity that signed retries rather than leave the row with nothing to expire it.

  Parameters

  • __namedParameters: { deadline: Instant; recheckAt?: Instant; walletTransactionId: string }

  Returns Promise<Run>

search

• search(
      __namedParameters: {
          createdAt?: DbTimestampCriteria;
          ids?: string[];
          nonceUnreleased?: boolean;
          references?: string[];
          solanaNonceAddresses?: string[];
          statuses?: WalletTransactionStatus[];
      },
  ): Promise<
      {
          ok: true;
          value: {
              items: (
                  Pick<
                      {
                          awsRequestId: string
                          | null;
                          blockTime: Date | null;
                          cancelledAt: Date | null;
                          chain: WalletTransactionChain;
                          chainData:
                              | JsonObject
                              | {
                                  blockTime: number;
                                  indexWithinBlock: number;
                                  meta: {
                                      err: JsonValue;
                                      fee: number;
                                      innerInstructions: (...)[];
                                      loadedAddresses: { readonly: ...; writable: ... };
                                      logMessages: (...)[];
                                      postBalances: (...)[];
                                      postTokenBalances: (...)[];
                                      preBalances: (...)[];
                                      preTokenBalances: (...)[];
                                  };
                                  slot: number;
                                  transaction: {
                                      message: {
                                          accountKeys: ...;
                                          addressTableLookups?: ...;
                                          header: ...;
                                          instructions: ...;
                                          recentBlockhash: ...;
                                          transactionConfig?: ...;
                                      };
                                      signatures: (...)[];
                                  };
                                  version?: 0
                                  | 1
                                  | "legacy";
                              }
                              | null;
                          chainId: number;
                          confirmedAt: Date
                          | null;
                          createdAt: Date;
                          data: JsonObject | null;
                          error: JsonValue;
                          evmFrom: string | null;
                          evmNonce: bigint | null;
                          externalId: string;
                          finalizedAt: Date | null;
                          id: number;
                          indexWithinBlock: number | null;
                          lastValidBlockHeight: bigint | null;
                          memoIks: string[] | null;
                          messageHash: Buffer<ArrayBufferLike> | null;
                          nonce: string | null;
                          nonceReleasedAt: Date | null;
                          parsedEvents: ParsedSolanaTransactionEvent[] | null;
                          payload: Buffer<ArrayBufferLike> | null;
                          reference: string | null;
                          requestedBy: string | null;
                          signedAt: Date | null;
                          slot: number | null;
                          solanaNonceAddress: string | null;
                          solanaNonceId: number | null;
                          source: WalletTransactionSource;
                          status: WalletTransactionStatus;
                          submittedAt: Date | null;
                          txHash: string | null;
                          type: WalletTransactionType;
                          updatedAt: Date;
                          utilaTransactionId: string | null;
                          utilaVaultExternalId: string | null;
                          utilaVaultId: number | null;
                      },
                      | "createdAt"
                      | "status"
                      | "reference"
                      | "txHash"
                      | "solanaNonceAddress"
                      | "nonce",
                  > & { id: string }
              )[];
          };
      },
  >

  Wallet transactions by reference or by the pool nonce they hold, oldest first.

  Parameters

  • __namedParameters: {
        createdAt?: DbTimestampCriteria;
        ids?: string[];
        nonceUnreleased?: boolean;
        references?: string[];
        solanaNonceAddresses?: string[];
        statuses?: WalletTransactionStatus[];
    }

    • OptionalcreatedAt?: DbTimestampCriteria

    • Optionalids?: string[]

    • OptionalnonceUnreleased?: boolean

      Only those still holding their pool nonce.

    • Optionalreferences?: string[]

    • OptionalsolanaNonceAddresses?: string[]

    • Optionalstatuses?: WalletTransactionStatus[]

  Returns Promise<
      {
          ok: true;
          value: {
              items: (
                  Pick<
                      {
                          awsRequestId: string
                          | null;
                          blockTime: Date | null;
                          cancelledAt: Date | null;
                          chain: WalletTransactionChain;
                          chainData:
                              | JsonObject
                              | {
                                  blockTime: number;
                                  indexWithinBlock: number;
                                  meta: {
                                      err: JsonValue;
                                      fee: number;
                                      innerInstructions: (...)[];
                                      loadedAddresses: { readonly: ...; writable: ... };
                                      logMessages: (...)[];
                                      postBalances: (...)[];
                                      postTokenBalances: (...)[];
                                      preBalances: (...)[];
                                      preTokenBalances: (...)[];
                                  };
                                  slot: number;
                                  transaction: {
                                      message: {
                                          accountKeys: ...;
                                          addressTableLookups?: ...;
                                          header: ...;
                                          instructions: ...;
                                          recentBlockhash: ...;
                                          transactionConfig?: ...;
                                      };
                                      signatures: (...)[];
                                  };
                                  version?: 0
                                  | 1
                                  | "legacy";
                              }
                              | null;
                          chainId: number;
                          confirmedAt: Date
                          | null;
                          createdAt: Date;
                          data: JsonObject | null;
                          error: JsonValue;
                          evmFrom: string | null;
                          evmNonce: bigint | null;
                          externalId: string;
                          finalizedAt: Date | null;
                          id: number;
                          indexWithinBlock: number | null;
                          lastValidBlockHeight: bigint | null;
                          memoIks: string[] | null;
                          messageHash: Buffer<ArrayBufferLike> | null;
                          nonce: string | null;
                          nonceReleasedAt: Date | null;
                          parsedEvents: ParsedSolanaTransactionEvent[] | null;
                          payload: Buffer<ArrayBufferLike> | null;
                          reference: string | null;
                          requestedBy: string | null;
                          signedAt: Date | null;
                          slot: number | null;
                          solanaNonceAddress: string | null;
                          solanaNonceId: number | null;
                          source: WalletTransactionSource;
                          status: WalletTransactionStatus;
                          submittedAt: Date | null;
                          txHash: string | null;
                          type: WalletTransactionType;
                          updatedAt: Date;
                          utilaTransactionId: string | null;
                          utilaVaultExternalId: string | null;
                          utilaVaultId: number | null;
                      },
                      | "createdAt"
                      | "status"
                      | "reference"
                      | "txHash"
                      | "solanaNonceAddress"
                      | "nonce",
                  > & { id: string }
              )[];
          };
      },
  >

sign

• sign(
      __namedParameters: {
          backofficeWallets: BackofficeWalletType[];
          extraSigners?: readonly KeyPairSigner[];
          message: TransactionMessage & (
              TransactionMessageWithFeePayer<string> & TransactionMessageWithLifetime
          );
          reference: string;
          walletId?: string;
      },
  ): Promise<
      | {
          ok: true;
          value: Readonly<
              { messageBytes: TransactionMessageBytes; signatures: SignaturesMap },
          > & TransactionWithLifetime & WalletApiBroadcast;
      }
      | { error: WalletApiSignError; ok: false },
  >

  Sign a message with the backofficeWallets roles, plus any extraSigners held in this process; fully signed, with the message's lifetime. With extraSigners wallet-api broadcasts it itself (broadcastByWalletApi); with CFX's keys alone the caller broadcasts it.

  Parameters

  • __namedParameters: {
        backofficeWallets: BackofficeWalletType[];
        extraSigners?: readonly KeyPairSigner[];
        message: TransactionMessage & (
            TransactionMessageWithFeePayer<string> & TransactionMessageWithLifetime
        );
        reference: string;
        walletId?: string;
    }

    • backofficeWallets: BackofficeWalletType[]

      Exactly the roles whose keys the message requires; wallet-api refuses any other set.

    • OptionalextraSigners?: readonly KeyPairSigner[]

    • message: TransactionMessage & (
          TransactionMessageWithFeePayer<string> & TransactionMessageWithLifetime
      )

    • reference: string

      The caller's own durable id: a quote, withdrawal, escrow or deploy.

    • OptionalwalletId?: string

      A customer wallet wallet-api also signs as, every address of it the message requires.

  Returns Promise<
      | {
          ok: true;
          value: Readonly<
              { messageBytes: TransactionMessageBytes; signatures: SignaturesMap },
          > & TransactionWithLifetime & WalletApiBroadcast;
      }
      | { error: WalletApiSignError; ok: false },
  >

signCompiledTransaction

• signCompiledTransaction<
      T extends
          Readonly<
              { messageBytes: TransactionMessageBytes; signatures: SignaturesMap },
          >,
  >(
      __namedParameters: {
          backofficeWallets: BackofficeWalletType[];
          reference: string;
          transaction: T;
          walletId?: string;
      },
  ): Promise<
      | { error: WalletApiSignError; ok: false }
      | { ok: true; value: T & WalletApiBroadcast },
  >

  Add CFX's signatures to a transaction compiled elsewhere (stored unsigned, or signed by a customer), keeping every signature it already carries. One with no empty slot (signed through sign already) comes back as it is. One carrying a signer wallet-api does not hold is broadcast by wallet-api once CFX signs it (broadcastByWalletApi), so the caller never sends it again.

  Type Parameters

  • T extends Readonly<{ messageBytes: TransactionMessageBytes; signatures: SignaturesMap }>

  Parameters

  • __namedParameters: {
        backofficeWallets: BackofficeWalletType[];
        reference: string;
        transaction: T;
        walletId?: string;
    }

    • backofficeWallets: BackofficeWalletType[]

      Exactly the roles whose keys the message requires, signed slots included.

    • reference: string

    • transaction: T

    • OptionalwalletId?: string

      A customer wallet wallet-api also signs as, every address of it the message requires.

  Returns Promise<
      | { error: WalletApiSignError; ok: false }
      | { ok: true; value: T & WalletApiBroadcast },
  >