@cfxlabsinc/b2b-services
    Preparing search index...

    Class UtilaCustodialWalletAdminService

    Hierarchy (View Summary)

    Index
    constructor
    db instance
    countsByCustomer create delete entityNameExpression get getBalances search supportedChainCount
    db: B2bDatabase
    instance: (...args: []) => UtilaCustodialWalletAdminService = ...

    The process default: built from each dependency's own instance().

    • How many of a customer's custodial wallets are live, and how many are hidden.

      One scan with FILTER aggregates rather than two search calls: the deleted count is only meaningful next to the live one — "2, 1 deleted" is a single fact about the customer, so it should cost a single round trip. Exact, unlike counting a capped page.

      Parameters

      • args: { customerId: string }

      Returns Promise<{ ok: true; value: { deleted: number; live: number } }>

    • Parameters

      • args: { entityId: string; existingWalletId?: string; label?: string }
        • entityId: string
        • OptionalexistingWalletId?: string
        • Optionallabel?: string

          Label for a newly-created vault wallet; ignored when existingWalletId is given (that wallet already has a name we cannot change — Utila has no rename). Defaults to the entity's display name.

          This is the label only: CUSTODIAL_WALLET_NAME_PREFIX is always applied on top, so an operator cannot mint a wallet that reads as a sweep wallet in a shared vault.

          Operator-supplied because an entity being given a replacement wallet cannot reuse the retired one's name while that wallet still exists, and only the operator knows what distinguishes this generation.

      Returns Promise<
          | {
              ok: true;
              value: {
                  addresses: Record<UtilaBlockchain, UtilaWalletAddress[]>;
                  createdAt: Date;
                  deletedAt: Date | null;
                  id: string;
                  updatedAt: Date;
                  vaultId: string;
              } & UtilaCustodialWalletReferences;
          }
          | { error: ServiceError; ok: false },
      >

    • Soft-delete or restore a custodial wallet, mirroring the transition onto the Utila wallet by archiving / un-archiving it.

      The DB write comes first, deliberately. Archiving first and then failing the update would leave a wallet archived in the vault but still live in CFX. In this order the worst case is the benign one — hidden in CFX, still un-archived in the vault — which a retry fixes.

      The Utila call is best-effort. It runs after a committed DB write, so there is nothing to roll back, and a vault outage must not stop an operator retiring a wallet. Reported as archiveFailed rather than swallowed, so the caller can say "hidden, but not yet archived" instead of a clean success.

      Parameters

      • args: { deleted: boolean; id: string }

      Returns Promise<
          | { ok: true; value: { archiveFailed: boolean; id: string } }
          | { error: ServiceError; ok: false },
      >

    • Asset balances for one custodial wallet, read from the vault that wallet lives in, or — with walletId omitted — for every wallet in every live vault that holds custodial wallets, one call per vault.

      The vault-wide form is what makes balances affordable on the list page: each returned row carries its own walletId, so one request per vault covers a whole page of wallets instead of one request per row.

      Returns a functional error rather than throwing, because a custody-vault outage must degrade the balance column to "unavailable" without taking down a page whose other columns are pure DB reads. An unconfigured stage fails inside token signing rather than at the API, so a thrown fault is caught as well as a refusal.

      Balances are NOT paginated through here: the vault-wide query can span many wallets, so the caller gets hasMore and decides. Rendering a partial set silently would be a wrong number presented as a right one.

      Parameters

      • Optionalargs: { pageSize?: number; walletId?: string }
        • OptionalpageSize?: number

          Per vault.

        • OptionalwalletId?: string

          Omit to query every wallet in every vault holding custodial wallets.

      Returns Promise<
          | {
              ok: true;
              value: {
                  balances: {
                      asset?: string;
                      assetId: string
                      | undefined;
                      frozenValue?: string;
                      rawValue?: string;
                      value?: string;
                      wallet?: string;
                      walletId: string | undefined;
                  }[];
                  hasMore: boolean;
              };
          }
          | { error: ServiceError; ok: false },
      >

    • Parameters

      • __namedParameters: {
            createdAt?: DbTimestampCriteria;
            customerIds?: string[];
            entityIds?: string[];
            entityTypes?: ("PERSON" | "BUSINESS")[];
            ids?: string[];
            includeDeleted?: boolean;
            orderBy?: DbOrderByCriterion<
                Omit<
                    PgTableWithColumns<
                        {
                            columns: {
                                createdAt: PgBuildColumn<
                                    "utila_custodial_wallet",
                                    SetHasDefault<SetNotNull<(...)>>,
                                    {
                                        data: Date;
                                        dataType: "object date";
                                        driverParam: string;
                                        enumValues: undefined;
                                        generated: undefined;
                                        hasDefault: true;
                                        hasRuntimeDefault: false;
                                        identity: undefined;
                                        isAutoincrement: false;
                                        isPrimaryKey: false;
                                        name: string;
                                        notNull: true;
                                        tableName: "utila_custodial_wallet";
                                    },
                                >;
                                customerExternalId: PgBuildColumn<
                                    "utila_custodial_wallet",
                                    SetNotNull<PgTextBuilder<(...)>>,
                                    {
                                        data: string;
                                        dataType: "string";
                                        driverParam: string;
                                        enumValues: undefined;
                                        generated: undefined;
                                        hasDefault: false;
                                        hasRuntimeDefault: false;
                                        identity: undefined;
                                        isAutoincrement: false;
                                        isPrimaryKey: false;
                                        name: string;
                                        notNull: true;
                                        tableName: "utila_custodial_wallet";
                                    },
                                >;
                                customerId: PgBuildColumn<
                                    "utila_custodial_wallet",
                                    SetNotNull<PgIntegerBuilder>,
                                    {
                                        data: number;
                                        dataType: "number int32";
                                        driverParam: (...) | (...);
                                        enumValues: undefined;
                                        generated: undefined;
                                        hasDefault: false;
                                        hasRuntimeDefault: false;
                                        identity: undefined;
                                        isAutoincrement: false;
                                        isPrimaryKey: false;
                                        name: string;
                                        notNull: true;
                                        tableName: "utila_custodial_wallet";
                                    },
                                >;
                                data: PgBuildColumn<
                                    "utila_custodial_wallet",
                                    SetNotNull<Set$Type<(...), (...)>>,
                                    {
                                        data: { addresses: ... };
                                        dataType: "object json";
                                        driverParam: unknown;
                                        enumValues: undefined;
                                        generated: undefined;
                                        hasDefault: false;
                                        hasRuntimeDefault: false;
                                        identity: undefined;
                                        isAutoincrement: false;
                                        isPrimaryKey: false;
                                        name: string;
                                        notNull: true;
                                        tableName: "utila_custodial_wallet";
                                    },
                                >;
                                deletedAt: PgBuildColumn<
                                    "utila_custodial_wallet",
                                    PgTimestampBuilder,
                                    {
                                        data: Date;
                                        dataType: "object date";
                                        driverParam: string;
                                        enumValues: undefined;
                                        generated: undefined;
                                        hasDefault: false;
                                        hasRuntimeDefault: false;
                                        identity: undefined;
                                        isAutoincrement: false;
                                        isPrimaryKey: false;
                                        name: string;
                                        notNull: false;
                                        tableName: "utila_custodial_wallet";
                                    },
                                >;
                                id: PgBuildColumn<
                                    "utila_custodial_wallet",
                                    HasIdentity<SetIsPrimaryKey<(...)>, "byDefault">,
                                    {
                                        data: number;
                                        dataType: "number int32";
                                        driverParam: (...) | (...);
                                        enumValues: undefined;
                                        generated: undefined;
                                        hasDefault: true;
                                        hasRuntimeDefault: false;
                                        identity: "byDefault";
                                        isAutoincrement: false;
                                        isPrimaryKey: false;
                                        name: string;
                                        notNull: true;
                                        tableName: "utila_custodial_wallet";
                                    },
                                >;
                                identityExternalId: PgBuildColumn<
                                    "utila_custodial_wallet",
                                    PgTextBuilder<[(...), ...(...)[]]>,
                                    {
                                        data: string;
                                        dataType: "string";
                                        driverParam: string;
                                        enumValues: undefined;
                                        generated: undefined;
                                        hasDefault: false;
                                        hasRuntimeDefault: false;
                                        identity: undefined;
                                        isAutoincrement: false;
                                        isPrimaryKey: false;
                                        name: string;
                                        notNull: false;
                                        tableName: "utila_custodial_wallet";
                                    },
                                >;
                                identityId: PgBuildColumn<
                                    "utila_custodial_wallet",
                                    PgIntegerBuilder,
                                    {
                                        data: number;
                                        dataType: "number int32";
                                        driverParam: (...)
                                        | (...);
                                        enumValues: undefined;
                                        generated: undefined;
                                        hasDefault: false;
                                        hasRuntimeDefault: false;
                                        identity: undefined;
                                        isAutoincrement: false;
                                        isPrimaryKey: false;
                                        name: string;
                                        notNull: false;
                                        tableName: "utila_custodial_wallet";
                                    },
                                >;
                                organizationExternalId: PgBuildColumn<
                                    "utila_custodial_wallet",
                                    PgTextBuilder<[(...), ...(...)[]]>,
                                    {
                                        data: string;
                                        dataType: "string";
                                        driverParam: string;
                                        enumValues: undefined;
                                        generated: undefined;
                                        hasDefault: false;
                                        hasRuntimeDefault: false;
                                        identity: undefined;
                                        isAutoincrement: false;
                                        isPrimaryKey: false;
                                        name: string;
                                        notNull: false;
                                        tableName: "utila_custodial_wallet";
                                    },
                                >;
                                organizationId: PgBuildColumn<
                                    "utila_custodial_wallet",
                                    PgIntegerBuilder,
                                    {
                                        data: number;
                                        dataType: "number int32";
                                        driverParam: (...)
                                        | (...);
                                        enumValues: undefined;
                                        generated: undefined;
                                        hasDefault: false;
                                        hasRuntimeDefault: false;
                                        identity: undefined;
                                        isAutoincrement: false;
                                        isPrimaryKey: false;
                                        name: string;
                                        notNull: false;
                                        tableName: "utila_custodial_wallet";
                                    },
                                >;
                                searchDocument: PgBuildColumn<
                                    "utila_custodial_wallet",
                                    SetHasGenerated<SetNotNull<(...)>>,
                                    {
                                        data: string;
                                        dataType: "string";
                                        driverParam: string;
                                        enumValues: undefined;
                                        generated: true;
                                        hasDefault: true;
                                        hasRuntimeDefault: false;
                                        identity: undefined;
                                        isAutoincrement: false;
                                        isPrimaryKey: false;
                                        name: string;
                                        notNull: true;
                                        tableName: "utila_custodial_wallet";
                                    },
                                >;
                                updatedAt: PgBuildColumn<
                                    "utila_custodial_wallet",
                                    SetHasDefault<SetHasDefault<(...)>>,
                                    {
                                        data: Date;
                                        dataType: "object date";
                                        driverParam: string;
                                        enumValues: undefined;
                                        generated: undefined;
                                        hasDefault: true;
                                        hasRuntimeDefault: false;
                                        identity: undefined;
                                        isAutoincrement: false;
                                        isPrimaryKey: false;
                                        name: string;
                                        notNull: true;
                                        tableName: "utila_custodial_wallet";
                                    },
                                >;
                                utilaVaultExternalId: PgBuildColumn<
                                    "utila_custodial_wallet",
                                    SetNotNull<PgTextBuilder<(...)>>,
                                    {
                                        data: string;
                                        dataType: "string";
                                        driverParam: string;
                                        enumValues: undefined;
                                        generated: undefined;
                                        hasDefault: false;
                                        hasRuntimeDefault: false;
                                        identity: undefined;
                                        isAutoincrement: false;
                                        isPrimaryKey: false;
                                        name: string;
                                        notNull: true;
                                        tableName: "utila_custodial_wallet";
                                    },
                                >;
                                utilaVaultId: PgBuildColumn<
                                    "utila_custodial_wallet",
                                    SetNotNull<PgIntegerBuilder>,
                                    {
                                        data: number;
                                        dataType: "number int32";
                                        driverParam: (...) | (...);
                                        enumValues: undefined;
                                        generated: undefined;
                                        hasDefault: false;
                                        hasRuntimeDefault: false;
                                        identity: undefined;
                                        isAutoincrement: false;
                                        isPrimaryKey: false;
                                        name: string;
                                        notNull: true;
                                        tableName: "utila_custodial_wallet";
                                    },
                                >;
                                walletId: PgBuildColumn<
                                    "utila_custodial_wallet",
                                    SetNotNull<PgTextBuilder<(...)>>,
                                    {
                                        data: string;
                                        dataType: "string";
                                        driverParam: string;
                                        enumValues: undefined;
                                        generated: undefined;
                                        hasDefault: false;
                                        hasRuntimeDefault: false;
                                        identity: undefined;
                                        isAutoincrement: false;
                                        isPrimaryKey: false;
                                        name: string;
                                        notNull: true;
                                        tableName: "utila_custodial_wallet";
                                    },
                                >;
                            };
                            dialect: "pg";
                            isAlias: false;
                            name: "utila_custodial_wallet";
                            schema: "b2b";
                        },
                    >,
                    "enableRLS",
                >,
                "createdAt"
                | "updatedAt",
            >[];
            page?: number;
            pageSize?: number;
            q?: string;
            updatedAt?: DbTimestampCriteria;
        }
        • OptionalcreatedAt?: DbTimestampCriteria
        • OptionalcustomerIds?: string[]
        • OptionalentityIds?: string[]
        • OptionalentityTypes?: ("PERSON" | "BUSINESS")[]

          Narrow to wallets owned by people (identity_id) or by businesses (organization_id). Distinct from entityIds, which names specific entities — this is the "all people" / "all businesses" cut.

        • Optionalids?: string[]
        • OptionalincludeDeleted?: boolean

          Include soft-deleted wallets. Off by default so every caller that forgets it gets the live set. Admin-only: the consumer service has no such flag, because a deleted wallet is precisely one a customer must not see.

        • OptionalorderBy?: DbOrderByCriterion<
              Omit<
                  PgTableWithColumns<
                      {
                          columns: {
                              createdAt: PgBuildColumn<
                                  "utila_custodial_wallet",
                                  SetHasDefault<SetNotNull<(...)>>,
                                  {
                                      data: Date;
                                      dataType: "object date";
                                      driverParam: string;
                                      enumValues: undefined;
                                      generated: undefined;
                                      hasDefault: true;
                                      hasRuntimeDefault: false;
                                      identity: undefined;
                                      isAutoincrement: false;
                                      isPrimaryKey: false;
                                      name: string;
                                      notNull: true;
                                      tableName: "utila_custodial_wallet";
                                  },
                              >;
                              customerExternalId: PgBuildColumn<
                                  "utila_custodial_wallet",
                                  SetNotNull<PgTextBuilder<(...)>>,
                                  {
                                      data: string;
                                      dataType: "string";
                                      driverParam: string;
                                      enumValues: undefined;
                                      generated: undefined;
                                      hasDefault: false;
                                      hasRuntimeDefault: false;
                                      identity: undefined;
                                      isAutoincrement: false;
                                      isPrimaryKey: false;
                                      name: string;
                                      notNull: true;
                                      tableName: "utila_custodial_wallet";
                                  },
                              >;
                              customerId: PgBuildColumn<
                                  "utila_custodial_wallet",
                                  SetNotNull<PgIntegerBuilder>,
                                  {
                                      data: number;
                                      dataType: "number int32";
                                      driverParam: (...) | (...);
                                      enumValues: undefined;
                                      generated: undefined;
                                      hasDefault: false;
                                      hasRuntimeDefault: false;
                                      identity: undefined;
                                      isAutoincrement: false;
                                      isPrimaryKey: false;
                                      name: string;
                                      notNull: true;
                                      tableName: "utila_custodial_wallet";
                                  },
                              >;
                              data: PgBuildColumn<
                                  "utila_custodial_wallet",
                                  SetNotNull<Set$Type<(...), (...)>>,
                                  {
                                      data: { addresses: ... };
                                      dataType: "object json";
                                      driverParam: unknown;
                                      enumValues: undefined;
                                      generated: undefined;
                                      hasDefault: false;
                                      hasRuntimeDefault: false;
                                      identity: undefined;
                                      isAutoincrement: false;
                                      isPrimaryKey: false;
                                      name: string;
                                      notNull: true;
                                      tableName: "utila_custodial_wallet";
                                  },
                              >;
                              deletedAt: PgBuildColumn<
                                  "utila_custodial_wallet",
                                  PgTimestampBuilder,
                                  {
                                      data: Date;
                                      dataType: "object date";
                                      driverParam: string;
                                      enumValues: undefined;
                                      generated: undefined;
                                      hasDefault: false;
                                      hasRuntimeDefault: false;
                                      identity: undefined;
                                      isAutoincrement: false;
                                      isPrimaryKey: false;
                                      name: string;
                                      notNull: false;
                                      tableName: "utila_custodial_wallet";
                                  },
                              >;
                              id: PgBuildColumn<
                                  "utila_custodial_wallet",
                                  HasIdentity<SetIsPrimaryKey<(...)>, "byDefault">,
                                  {
                                      data: number;
                                      dataType: "number int32";
                                      driverParam: (...) | (...);
                                      enumValues: undefined;
                                      generated: undefined;
                                      hasDefault: true;
                                      hasRuntimeDefault: false;
                                      identity: "byDefault";
                                      isAutoincrement: false;
                                      isPrimaryKey: false;
                                      name: string;
                                      notNull: true;
                                      tableName: "utila_custodial_wallet";
                                  },
                              >;
                              identityExternalId: PgBuildColumn<
                                  "utila_custodial_wallet",
                                  PgTextBuilder<[(...), ...(...)[]]>,
                                  {
                                      data: string;
                                      dataType: "string";
                                      driverParam: string;
                                      enumValues: undefined;
                                      generated: undefined;
                                      hasDefault: false;
                                      hasRuntimeDefault: false;
                                      identity: undefined;
                                      isAutoincrement: false;
                                      isPrimaryKey: false;
                                      name: string;
                                      notNull: false;
                                      tableName: "utila_custodial_wallet";
                                  },
                              >;
                              identityId: PgBuildColumn<
                                  "utila_custodial_wallet",
                                  PgIntegerBuilder,
                                  {
                                      data: number;
                                      dataType: "number int32";
                                      driverParam: (...)
                                      | (...);
                                      enumValues: undefined;
                                      generated: undefined;
                                      hasDefault: false;
                                      hasRuntimeDefault: false;
                                      identity: undefined;
                                      isAutoincrement: false;
                                      isPrimaryKey: false;
                                      name: string;
                                      notNull: false;
                                      tableName: "utila_custodial_wallet";
                                  },
                              >;
                              organizationExternalId: PgBuildColumn<
                                  "utila_custodial_wallet",
                                  PgTextBuilder<[(...), ...(...)[]]>,
                                  {
                                      data: string;
                                      dataType: "string";
                                      driverParam: string;
                                      enumValues: undefined;
                                      generated: undefined;
                                      hasDefault: false;
                                      hasRuntimeDefault: false;
                                      identity: undefined;
                                      isAutoincrement: false;
                                      isPrimaryKey: false;
                                      name: string;
                                      notNull: false;
                                      tableName: "utila_custodial_wallet";
                                  },
                              >;
                              organizationId: PgBuildColumn<
                                  "utila_custodial_wallet",
                                  PgIntegerBuilder,
                                  {
                                      data: number;
                                      dataType: "number int32";
                                      driverParam: (...)
                                      | (...);
                                      enumValues: undefined;
                                      generated: undefined;
                                      hasDefault: false;
                                      hasRuntimeDefault: false;
                                      identity: undefined;
                                      isAutoincrement: false;
                                      isPrimaryKey: false;
                                      name: string;
                                      notNull: false;
                                      tableName: "utila_custodial_wallet";
                                  },
                              >;
                              searchDocument: PgBuildColumn<
                                  "utila_custodial_wallet",
                                  SetHasGenerated<SetNotNull<(...)>>,
                                  {
                                      data: string;
                                      dataType: "string";
                                      driverParam: string;
                                      enumValues: undefined;
                                      generated: true;
                                      hasDefault: true;
                                      hasRuntimeDefault: false;
                                      identity: undefined;
                                      isAutoincrement: false;
                                      isPrimaryKey: false;
                                      name: string;
                                      notNull: true;
                                      tableName: "utila_custodial_wallet";
                                  },
                              >;
                              updatedAt: PgBuildColumn<
                                  "utila_custodial_wallet",
                                  SetHasDefault<SetHasDefault<(...)>>,
                                  {
                                      data: Date;
                                      dataType: "object date";
                                      driverParam: string;
                                      enumValues: undefined;
                                      generated: undefined;
                                      hasDefault: true;
                                      hasRuntimeDefault: false;
                                      identity: undefined;
                                      isAutoincrement: false;
                                      isPrimaryKey: false;
                                      name: string;
                                      notNull: true;
                                      tableName: "utila_custodial_wallet";
                                  },
                              >;
                              utilaVaultExternalId: PgBuildColumn<
                                  "utila_custodial_wallet",
                                  SetNotNull<PgTextBuilder<(...)>>,
                                  {
                                      data: string;
                                      dataType: "string";
                                      driverParam: string;
                                      enumValues: undefined;
                                      generated: undefined;
                                      hasDefault: false;
                                      hasRuntimeDefault: false;
                                      identity: undefined;
                                      isAutoincrement: false;
                                      isPrimaryKey: false;
                                      name: string;
                                      notNull: true;
                                      tableName: "utila_custodial_wallet";
                                  },
                              >;
                              utilaVaultId: PgBuildColumn<
                                  "utila_custodial_wallet",
                                  SetNotNull<PgIntegerBuilder>,
                                  {
                                      data: number;
                                      dataType: "number int32";
                                      driverParam: (...) | (...);
                                      enumValues: undefined;
                                      generated: undefined;
                                      hasDefault: false;
                                      hasRuntimeDefault: false;
                                      identity: undefined;
                                      isAutoincrement: false;
                                      isPrimaryKey: false;
                                      name: string;
                                      notNull: true;
                                      tableName: "utila_custodial_wallet";
                                  },
                              >;
                              walletId: PgBuildColumn<
                                  "utila_custodial_wallet",
                                  SetNotNull<PgTextBuilder<(...)>>,
                                  {
                                      data: string;
                                      dataType: "string";
                                      driverParam: string;
                                      enumValues: undefined;
                                      generated: undefined;
                                      hasDefault: false;
                                      hasRuntimeDefault: false;
                                      identity: undefined;
                                      isAutoincrement: false;
                                      isPrimaryKey: false;
                                      name: string;
                                      notNull: true;
                                      tableName: "utila_custodial_wallet";
                                  },
                              >;
                          };
                          dialect: "pg";
                          isAlias: false;
                          name: "utila_custodial_wallet";
                          schema: "b2b";
                      },
                  >,
                  "enableRLS",
              >,
              "createdAt"
              | "updatedAt",
          >[]
        • Optionalpage?: number

          Defaults to 1

        • OptionalpageSize?: number

          Defaults to 10

        • Optionalq?: string

          Case-insensitive substring over the Utila wallet id, the owning customer's name, the entity's name, and the derived addresses — an operator most often arrives holding an address off a block explorer and needs the wallet it belongs to.

        • OptionalupdatedAt?: DbTimestampCriteria

      Returns Promise<
          {
              ok: true;
              value: {
                  hasNext: boolean;
                  items: (
                      {
                          addresses: Record<UtilaBlockchain, UtilaWalletAddress[]>;
                          createdAt: Date;
                          deletedAt: Date | null;
                          id: string;
                          updatedAt: Date;
                          vaultId: string;
                      } & UtilaCustodialWalletReferences
                  )[];
                  total: number;
              };
          },
      >

    • How many chains a fully-derived custodial wallet has addresses on — the denominator for "3 chains" on a list row, which is otherwise unjudgeable.

      Comes from the client's supported-chain set, a pure function of the vault env (22 chains on prod, 7 on dev) needing no credentials and no network.

      Returns Promise<number>

    Settings
    Member Visibility

    On This Page
    Constructors
    Properties
    Methods