Class WalletPaymentInstrumentService

A self-custody blockchain wallet

Hierarchy (View Summary)

PaymentInstrumentCache
- WalletPaymentInstrumentService

Index

Constructors

constructor

new WalletPaymentInstrumentService(
    args: {
        chainService: ChainService;
        db: B2bDatabase;
        entityService: EntityService;
        eventPublisher: CustomerEventPublisher;
        limits: Partial<Limits>;
        nominisClient: NominisClient;
        paymentInstrumentBlacklistService: PaymentInstrumentBlacklistService;
        valkeyClient: ValkeyClient | null;
    },
): WalletPaymentInstrumentService
Parameters
- args: {
      chainService: ChainService;
      db: B2bDatabase;
      entityService: EntityService;
      eventPublisher: CustomerEventPublisher;
      limits: Partial<Limits>;
      nominisClient: NominisClient;
      paymentInstrumentBlacklistService: PaymentInstrumentBlacklistService;
      valkeyClient: ValkeyClient | null;
  }
  - chainService: ChainService
    
    Resolves the target chain's runtime (drives per-chain address validation).
  - db: B2bDatabase
  - entityService: EntityService
  - eventPublisher: CustomerEventPublisher
  - limits: Partial<Limits>
    
    The max number of each instrument kind that a given entity type can have at any time.
    
    If undefined, it defaults to infinity.
  - nominisClient: NominisClient
  - paymentInstrumentBlacklistService: PaymentInstrumentBlacklistService
  - valkeyClient: ValkeyClient | null
Returns WalletPaymentInstrumentService
Overrides PaymentInstrumentCache.constructor
- Defined in packages/payment-instrument-services/src/instruments/WalletPaymentInstrumentService.ts:125

Properties

`Protected` `Readonly`cache

cache: ServiceCache<CachedSearchPage<PaymentInstrumentSearchItem>>

`Static`instance

instance: (...args: []) => WalletPaymentInstrumentService = ...

The process default: no per-entity cap, as every app configures it.

Methods

adminUpdate

adminUpdate(
    input: { data: WalletAdminUpdateData; id: string },
): Promise<
    | {
        ok: true;
        value: {
            address: string;
            beneficiaryName: string
            | null;
            chain: string;
            createdAt: Date;
            deletedAt: Date | null;
            id: string;
            name?: string;
            nominisWalletScreen?: {
                data?: {
                    data?: {
                        activity?: (...) | (...);
                        address_data?: (...) | (...);
                        asset_distribution_in?: (...) | (...);
                        asset_distribution_out?: (...) | (...);
                        balance?: (...) | (...);
                        depth?: (...) | (...);
                        destination_of_funds?: (...) | (...);
                        exposure?: (...) | (...);
                        geoint?: (...) | (...);
                        intel?: (...) | (...);
                        risk_categories?: (...) | (...);
                        risk_score?: (...) | (...);
                        source_of_funds?: (...) | (...);
                    };
                    status?: "pending"
                    | "done";
                };
                error?: string;
                req_id?: string;
                request_type?: "check_exposure";
                status?: "ok"
                | "fail";
                time?: number;
            };
            nominisWalletScreenRequestId?: string;
            origin?: "DEPOSIT_SENDER";
            providerId: string;
            referenceId?: string;
            sendEnabled: boolean;
            status: | "DELETED"
            | "PENDING_VERIFICATION"
            | "ACTION_REQUIRED"
            | "APPROVED"
            | "BLOCKED";
            statusDescription: string;
            type: "WALLET";
            typeDescription: string;
            updatedAt: Date;
        };
    }
    | { error: WalletAdminUpdateError; ok: false },
>
An operator's edit, whoever owns the row: skips only the entity capability check. A new address or chain re-runs every create-time check, including a fresh Nominis screen, and drops the old address's verdict.
Parameters
- input: { data: WalletAdminUpdateData; id: string }
Returns Promise<
    | {
        ok: true;
        value: {
            address: string;
            beneficiaryName: string
            | null;
            chain: string;
            createdAt: Date;
            deletedAt: Date | null;
            id: string;
            name?: string;
            nominisWalletScreen?: {
                data?: {
                    data?: {
                        activity?: (...) | (...);
                        address_data?: (...) | (...);
                        asset_distribution_in?: (...) | (...);
                        asset_distribution_out?: (...) | (...);
                        balance?: (...) | (...);
                        depth?: (...) | (...);
                        destination_of_funds?: (...) | (...);
                        exposure?: (...) | (...);
                        geoint?: (...) | (...);
                        intel?: (...) | (...);
                        risk_categories?: (...) | (...);
                        risk_score?: (...) | (...);
                        source_of_funds?: (...) | (...);
                    };
                    status?: "pending"
                    | "done";
                };
                error?: string;
                req_id?: string;
                request_type?: "check_exposure";
                status?: "ok"
                | "fail";
                time?: number;
            };
            nominisWalletScreenRequestId?: string;
            origin?: "DEPOSIT_SENDER";
            providerId: string;
            referenceId?: string;
            sendEnabled: boolean;
            status: | "DELETED"
            | "PENDING_VERIFICATION"
            | "ACTION_REQUIRED"
            | "APPROVED"
            | "BLOCKED";
            statusDescription: string;
            type: "WALLET";
            typeDescription: string;
            updatedAt: Date;
        };
    }
    | { error: WalletAdminUpdateError; ok: false },
>
- Defined in packages/payment-instrument-services/src/instruments/WalletPaymentInstrumentService.ts:402

create

create(
    __namedParameters: CreateInput,
): Promise<
    | {
        ok: true;
        value: {
            address: string;
            beneficiaryName: string
            | null;
            chain: string;
            createdAt: Date;
            deletedAt: Date | null;
            id: string;
            name?: string;
            nominisWalletScreen?: {
                data?: {
                    data?: {
                        activity?: (...) | (...);
                        address_data?: (...) | (...);
                        asset_distribution_in?: (...) | (...);
                        asset_distribution_out?: (...) | (...);
                        balance?: (...) | (...);
                        depth?: (...) | (...);
                        destination_of_funds?: (...) | (...);
                        exposure?: (...) | (...);
                        geoint?: (...) | (...);
                        intel?: (...) | (...);
                        risk_categories?: (...) | (...);
                        risk_score?: (...) | (...);
                        source_of_funds?: (...) | (...);
                    };
                    status?: "pending"
                    | "done";
                };
                error?: string;
                req_id?: string;
                request_type?: "check_exposure";
                status?: "ok"
                | "fail";
                time?: number;
            };
            nominisWalletScreenRequestId?: string;
            origin?: "DEPOSIT_SENDER";
            providerId: string;
            referenceId?: string;
            sendEnabled: boolean;
            status: | "DELETED"
            | "PENDING_VERIFICATION"
            | "ACTION_REQUIRED"
            | "APPROVED"
            | "BLOCKED";
            statusDescription: string;
            type: "WALLET";
            typeDescription: string;
            updatedAt: Date;
        };
    }
    | {
        error: | ServiceError<
            "INVALID_ENTITY"
            | "PAYMENT_INSTRUMENT_DUPLICATE"
            | "INVALID_CHAIN",
        >
        | WalletPaymentInstrumentCheckLimitsError;
        ok: false;
    },
>
Parameters
- __namedParameters: CreateInput
Returns Promise<
    | {
        ok: true;
        value: {
            address: string;
            beneficiaryName: string
            | null;
            chain: string;
            createdAt: Date;
            deletedAt: Date | null;
            id: string;
            name?: string;
            nominisWalletScreen?: {
                data?: {
                    data?: {
                        activity?: (...) | (...);
                        address_data?: (...) | (...);
                        asset_distribution_in?: (...) | (...);
                        asset_distribution_out?: (...) | (...);
                        balance?: (...) | (...);
                        depth?: (...) | (...);
                        destination_of_funds?: (...) | (...);
                        exposure?: (...) | (...);
                        geoint?: (...) | (...);
                        intel?: (...) | (...);
                        risk_categories?: (...) | (...);
                        risk_score?: (...) | (...);
                        source_of_funds?: (...) | (...);
                    };
                    status?: "pending"
                    | "done";
                };
                error?: string;
                req_id?: string;
                request_type?: "check_exposure";
                status?: "ok"
                | "fail";
                time?: number;
            };
            nominisWalletScreenRequestId?: string;
            origin?: "DEPOSIT_SENDER";
            providerId: string;
            referenceId?: string;
            sendEnabled: boolean;
            status: | "DELETED"
            | "PENDING_VERIFICATION"
            | "ACTION_REQUIRED"
            | "APPROVED"
            | "BLOCKED";
            statusDescription: string;
            type: "WALLET";
            typeDescription: string;
            updatedAt: Date;
        };
    }
    | {
        error: | ServiceError<
            "INVALID_ENTITY"
            | "PAYMENT_INSTRUMENT_DUPLICATE"
            | "INVALID_CHAIN",
        >
        | WalletPaymentInstrumentCheckLimitsError;
        ok: false;
    },
>
- Defined in packages/payment-instrument-services/src/instruments/WalletPaymentInstrumentService.ts:157

delete

delete(
    __namedParameters: { customerId: string; entityId: string; id: string },
): Promise<
    { ok: true; value: undefined }
    | { error: ServiceError; ok: false },
>
Parameters
- __namedParameters: { customerId: string; entityId: string; id: string }
Returns Promise<{ ok: true; value: undefined } | { error: ServiceError; ok: false }>
- Defined in packages/payment-instrument-services/src/instruments/WalletPaymentInstrumentService.ts:618

invalidateCache

invalidateCache(
    args: {
        customerIds: readonly string[];
        keys?: readonly CacheKey[];
        records?: readonly string[];
    },
): Promise<void>
Also clears payment-instrument.text. Every writer busts by customer alone, which reaches no field tag, yet each write may change the text a cached transaction q page matched on.
Parameters
- args: {
      customerIds: readonly string[];
      keys?: readonly CacheKey[];
      records?: readonly string[];
  }
Returns Promise<void>
Inherited from PaymentInstrumentCache.invalidateCache
- Defined in packages/payment-instrument-services/src/PaymentInstrumentCache.ts:67

`Protected`searchTags

searchTags(
    __namedParameters: {
        customerIds: readonly string[] | undefined;
        fields?: readonly string[];
        records?: readonly string[];
    },
): string[]
Tags for a page: the scope its query searched (each customer's membership tag, else the collection tag), so an empty page is bustable too, plus the records it projects and the fields that chose or ordered its rows.
Parameters
- __namedParameters: {
      customerIds: readonly string[] | undefined;
      fields?: readonly string[];
      records?: readonly string[];
  }
Returns string[]
Inherited from PaymentInstrumentCache.searchTags
- Defined in packages/db/src/valkey/service-cache.ts:519

update

update(
    input: {
        customerId: string;
        data: Partial<
            {
                name: WalletPaymentInstrument["name"]
                | null;
                referenceId: WalletPaymentInstrument["referenceId"] | null;
                sendEnabled: WalletPaymentInstrument["sendEnabled"];
            },
        >;
        id: string;
    },
): Promise<
    | {
        ok: true;
        value: {
            address: string;
            beneficiaryName: string
            | null;
            chain: string;
            createdAt: Date;
            deletedAt: Date | null;
            id: string;
            name?: string;
            nominisWalletScreen?: {
                data?: {
                    data?: {
                        activity?: (...) | (...);
                        address_data?: (...) | (...);
                        asset_distribution_in?: (...) | (...);
                        asset_distribution_out?: (...) | (...);
                        balance?: (...) | (...);
                        depth?: (...) | (...);
                        destination_of_funds?: (...) | (...);
                        exposure?: (...) | (...);
                        geoint?: (...) | (...);
                        intel?: (...) | (...);
                        risk_categories?: (...) | (...);
                        risk_score?: (...) | (...);
                        source_of_funds?: (...) | (...);
                    };
                    status?: "pending"
                    | "done";
                };
                error?: string;
                req_id?: string;
                request_type?: "check_exposure";
                status?: "ok"
                | "fail";
                time?: number;
            };
            nominisWalletScreenRequestId?: string;
            origin?: "DEPOSIT_SENDER";
            providerId: string;
            referenceId?: string;
            sendEnabled: boolean;
            status: | "DELETED"
            | "PENDING_VERIFICATION"
            | "ACTION_REQUIRED"
            | "APPROVED"
            | "BLOCKED";
            statusDescription: string;
            type: "WALLET";
            typeDescription: string;
            updatedAt: Date;
        };
    }
    | { error: WalletUpdateError; ok: false },
>
Parameters
- input: {
      customerId: string;
      data: Partial<
          {
              name: WalletPaymentInstrument["name"]
              | null;
              referenceId: WalletPaymentInstrument["referenceId"] | null;
              sendEnabled: WalletPaymentInstrument["sendEnabled"];
          },
      >;
      id: string;
  }
  - customerId: string
  - data: Partial<
        {
            name: WalletPaymentInstrument["name"]
            | null;
            referenceId: WalletPaymentInstrument["referenceId"] | null;
            sendEnabled: WalletPaymentInstrument["sendEnabled"];
        },
    >
    
    The consumer-writable slice. The Nominis screening verdict is deliberately absent — it is partner-produced and lands via PaymentInstrumentAdminService.update.
  - id: string
Returns Promise<
    | {
        ok: true;
        value: {
            address: string;
            beneficiaryName: string
            | null;
            chain: string;
            createdAt: Date;
            deletedAt: Date | null;
            id: string;
            name?: string;
            nominisWalletScreen?: {
                data?: {
                    data?: {
                        activity?: (...) | (...);
                        address_data?: (...) | (...);
                        asset_distribution_in?: (...) | (...);
                        asset_distribution_out?: (...) | (...);
                        balance?: (...) | (...);
                        depth?: (...) | (...);
                        destination_of_funds?: (...) | (...);
                        exposure?: (...) | (...);
                        geoint?: (...) | (...);
                        intel?: (...) | (...);
                        risk_categories?: (...) | (...);
                        risk_score?: (...) | (...);
                        source_of_funds?: (...) | (...);
                    };
                    status?: "pending"
                    | "done";
                };
                error?: string;
                req_id?: string;
                request_type?: "check_exposure";
                status?: "ok"
                | "fail";
                time?: number;
            };
            nominisWalletScreenRequestId?: string;
            origin?: "DEPOSIT_SENDER";
            providerId: string;
            referenceId?: string;
            sendEnabled: boolean;
            status: | "DELETED"
            | "PENDING_VERIFICATION"
            | "ACTION_REQUIRED"
            | "APPROVED"
            | "BLOCKED";
            statusDescription: string;
            type: "WALLET";
            typeDescription: string;
            updatedAt: Date;
        };
    }
    | { error: WalletUpdateError; ok: false },
>
- Defined in packages/payment-instrument-services/src/instruments/WalletPaymentInstrumentService.ts:373

upsert

upsert(
    input: UpsertInput,
): Promise<
    | {
        ok: true;
        value: {
            instrument: {
                address: string;
                beneficiaryName: string
                | null;
                chain: string;
                createdAt: Date;
                deletedAt: Date | null;
                id: string;
                name?: string;
                nominisWalletScreen?: {
                    data?: {
                        data?: {
                            activity?: ...;
                            address_data?: ...;
                            asset_distribution_in?: ...;
                            asset_distribution_out?: ...;
                            balance?: ...;
                            depth?: ...;
                            destination_of_funds?: ...;
                            exposure?: ...;
                            geoint?: ...;
                            intel?: ...;
                            risk_categories?: ...;
                            risk_score?: ...;
                            source_of_funds?: ...;
                        };
                        status?: "pending"
                        | "done";
                    };
                    error?: string;
                    req_id?: string;
                    request_type?: "check_exposure";
                    status?: "ok"
                    | "fail";
                    time?: number;
                };
                nominisWalletScreenRequestId?: string;
                origin?: "DEPOSIT_SENDER";
                providerId: string;
                referenceId?: string;
                sendEnabled: boolean;
                status: | "DELETED"
                | "PENDING_VERIFICATION"
                | "ACTION_REQUIRED"
                | "APPROVED"
                | "BLOCKED";
                statusDescription: string;
                type: "WALLET";
                typeDescription: string;
                updatedAt: Date;
            };
            screenFailure?: ScreenFailure;
        };
    }
    | { error: ServiceError; ok: false },
>
The wallet that sent a deposit, as a WALLET instrument of the receiving ledger account's owner (origin: "DEPOSIT_SENDER", sending off); the live one when the owner already holds it. Publishes nothing. A screen that cannot be started comes back as screenFailure, and the next call starts it.
Parameters
- input: UpsertInput
Returns Promise<
    | {
        ok: true;
        value: {
            instrument: {
                address: string;
                beneficiaryName: string
                | null;
                chain: string;
                createdAt: Date;
                deletedAt: Date | null;
                id: string;
                name?: string;
                nominisWalletScreen?: {
                    data?: {
                        data?: {
                            activity?: ...;
                            address_data?: ...;
                            asset_distribution_in?: ...;
                            asset_distribution_out?: ...;
                            balance?: ...;
                            depth?: ...;
                            destination_of_funds?: ...;
                            exposure?: ...;
                            geoint?: ...;
                            intel?: ...;
                            risk_categories?: ...;
                            risk_score?: ...;
                            source_of_funds?: ...;
                        };
                        status?: "pending"
                        | "done";
                    };
                    error?: string;
                    req_id?: string;
                    request_type?: "check_exposure";
                    status?: "ok"
                    | "fail";
                    time?: number;
                };
                nominisWalletScreenRequestId?: string;
                origin?: "DEPOSIT_SENDER";
                providerId: string;
                referenceId?: string;
                sendEnabled: boolean;
                status: | "DELETED"
                | "PENDING_VERIFICATION"
                | "ACTION_REQUIRED"
                | "APPROVED"
                | "BLOCKED";
                statusDescription: string;
                type: "WALLET";
                typeDescription: string;
                updatedAt: Date;
            };
            screenFailure?: ScreenFailure;
        };
    }
    | { error: ServiceError; ok: false },
>
- Defined in packages/payment-instrument-services/src/instruments/WalletPaymentInstrumentService.ts:293

Class WalletPaymentInstrumentService

Hierarchy (View Summary)

Index

Constructors

Properties

Methods

Constructors

constructor

Parameters

chainService: ChainService

db: B2bDatabase

entityService: EntityService

eventPublisher: CustomerEventPublisher

limits: Partial<Limits>

nominisClient: NominisClient

paymentInstrumentBlacklistService: PaymentInstrumentBlacklistService

valkeyClient: ValkeyClient | null

Returns WalletPaymentInstrumentService

Properties

Protected Readonlycache

Staticinstance

Methods

adminUpdate

Parameters

create

Parameters

delete

Parameters

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

invalidateCache

Parameters

Returns Promise<void>

ProtectedsearchTags

Parameters

Returns string[]

update

Parameters

customerId: string

data: Partial< { name: WalletPaymentInstrument["name"] | null; referenceId: WalletPaymentInstrument["referenceId"] | null; sendEnabled: WalletPaymentInstrument["sendEnabled"]; },>

id: string

upsert

Parameters

Settings

On This Page

`Protected` `Readonly`cache

`Static`instance

`Protected`searchTags

data: Partial<
{
name: WalletPaymentInstrument["name"]
| null;
referenceId: WalletPaymentInstrument["referenceId"] | null;
sendEnabled: WalletPaymentInstrument["sendEnabled"];
},
>