API

Links: API, Interfaces, Classes, Functions, Types, Enums, Variables

Interfaces


Amount	IdentityVerificationResponse	RemittanceEnvelope
Brc29OptionTerms	InstrumentBase	RemittanceEventHandlers
Brc29ReceiptData	Invoice	RemittanceManagerConfig
Brc29RemittanceModuleConfig	LineItem	RemittanceManagerRuntimeOptions
Brc29SettlementArtifact	LockingScriptProvider	RemittanceManagerState
CommsLayer	LoggerLike	RemittanceModule
ComposeInvoiceInput	ModuleContext	Settlement
IdentityLayer	NonceProvider	Termination
IdentityVerificationAcknowledgment	PeerMessage	Thread
IdentityVerificationRequest	Receipt	Unit

Links: API, Interfaces, Classes, Functions, Types, Enums, Variables

Interface: Amount

export interface Amount {
    value: string;
    unit: Unit;
}

Property value

Decimal string. Avoid floats at the protocol layer.

value: string

Links: API, Interfaces, Classes, Functions, Types, Enums, Variables

Interface: Brc29OptionTerms

BRC-29-like payment option terms.

This module intentionally keeps option terms minimal: - Amount is taken from the invoice total (and validated as satoshis) - The payer derives the payee's per-payment public key using wallet.getPublicKey with a stable protocolID

export interface Brc29OptionTerms {
    amountSatoshis: number;
    payee: PubKeyHex;
    outputIndex?: number;
    protocolID?: WalletProtocol;
    labels?: string[];
    description?: string;
}

Property amountSatoshis

Payment amount in satoshis.

amountSatoshis: number

Property description

Optional description for createAction.

description?: string

Property labels

Optional labels for createAction.

labels?: string[]

Property outputIndex

Which output index to internalize, default 0.

outputIndex?: number

Property payee

The recipient of the payment

payee: PubKeyHex

See also: PubKeyHex

Property protocolID

Optionally override the protocolID used in getPublicKey.

protocolID?: WalletProtocol

Interface: Brc29ReceiptData

Receipt data for BRC-29 settlements.

export interface Brc29ReceiptData {
    internalizeResult?: unknown;
    rejectedReason?: string;
    refund?: {
        token: Brc29SettlementArtifact;
        feeSatoshis: number;
    };
}

Property internalizeResult

Result returned from wallet.internalizeAction, if accepted.

internalizeResult?: unknown

Property refund

If rejected with refund, contains the refund payment token.

refund?: {
    token: Brc29SettlementArtifact;
    feeSatoshis: number;
}

Property rejectedReason

Human-readable rejection reason, if rejected.

rejectedReason?: string

Links: API, Interfaces, Classes, Functions, Types, Enums, Variables

Interface: Brc29RemittanceModuleConfig

export interface Brc29RemittanceModuleConfig {
    protocolID?: WalletProtocol;
    labels?: string[];
    description?: string;
    outputDescription?: string;
    refundFeeSatoshis?: number;
    minRefundSatoshis?: number;
    internalizeProtocol?: "wallet payment" | "basket insertion";
    nonceProvider?: NonceProvider;
    lockingScriptProvider?: LockingScriptProvider;
}

Property description

Description applied to created actions.

description?: string

Property internalizeProtocol

How wallet internalizes the payment.

internalizeProtocol?: "wallet payment" | "basket insertion"

Property labels

Labels applied to created actions.

labels?: string[]

Property minRefundSatoshis

Minimum refund to issue. If refund would be smaller, module will reject without refund.

minRefundSatoshis?: number

Property outputDescription

Output description for created actions.

outputDescription?: string

Property protocolID

Default protocolID to use with wallet.getPublicKey.

protocolID?: WalletProtocol

Property refundFeeSatoshis

Fee charged on refunds, in satoshis.

refundFeeSatoshis?: number

Links: API, Interfaces, Classes, Functions, Types, Enums, Variables

Interface: Brc29SettlementArtifact

Settlement artifact carried in the settlement message.

export interface Brc29SettlementArtifact {
    customInstructions: {
        derivationPrefix: string;
        derivationSuffix: string;
    };
    transaction: number[];
    amountSatoshis: number;
    outputIndex?: number;
}

Links: API, Interfaces, Classes, Functions, Types, Enums, Variables

Interface: CommsLayer

Abstract communications layer.

This intentionally mirrors the essential subset of message-box-client / MessageBoxClient. RemittanceManager never talks directly to HTTP/WebSockets – it only uses this interface.

export interface CommsLayer {
    sendMessage: (args: {
        recipient: PubKeyHex;
        messageBox: string;
        body: string;
    }, hostOverride?: string) => Promise<string>;
    sendLiveMessage?: (args: {
        recipient: PubKeyHex;
        messageBox: string;
        body: string;
    }, hostOverride?: string) => Promise<string>;
    listMessages: (args: {
        messageBox: string;
        host?: string;
    }) => Promise<PeerMessage[]>;
    acknowledgeMessage: (args: {
        messageIds: string[];
    }) => Promise<void>;
    listenForLiveMessages?: (args: {
        messageBox: string;
        overrideHost?: string;
        onMessage: (msg: PeerMessage) => void;
    }) => Promise<void>;
}

Property acknowledgeMessage

Acknowledges messages (deletes them from the server / inbox).

acknowledgeMessage: (args: {
    messageIds: string[];
}) => Promise<void>

Property listMessages

Lists pending messages for a message box.

listMessages: (args: {
    messageBox: string;
    host?: string;
}) => Promise<PeerMessage[]>

Property listenForLiveMessages

Optional live listener.

listenForLiveMessages?: (args: {
    messageBox: string;
    overrideHost?: string;
    onMessage: (msg: PeerMessage) => void;
}) => Promise<void>

Property sendLiveMessage

Sends a message over the live channel (e.g. WebSocket). Returns the transport messageId. Implementers may throw if live sending is not possible. RemittanceManager will fall back to sendMessage where appropriate.

sendLiveMessage?: (args: {
    recipient: PubKeyHex;
    messageBox: string;
    body: string;
}, hostOverride?: string) => Promise<string>

See also: PubKeyHex

Property sendMessage

Sends a message over the store-and-forward channel. Returns the transport messageId.

sendMessage: (args: {
    recipient: PubKeyHex;
    messageBox: string;
    body: string;
}, hostOverride?: string) => Promise<string>

See also: PubKeyHex

Links: API, Interfaces, Classes, Functions, Types, Enums, Variables

Interface: ComposeInvoiceInput

export interface ComposeInvoiceInput {
    note?: string;
    lineItems: Invoice["lineItems"];
    total: Invoice["total"];
    invoiceNumber?: string;
    arbitrary?: Record<string, unknown>;
}

Property lineItems

Line items.

lineItems: Invoice["lineItems"]

Property note

Human note/memo.

note?: string

Property total

Total amount.

total: Invoice["total"]

Interface: IdentityLayer

The Identity Layer handles identity certificate exchange and verification. It is optional and pluggable. Modules can use it to request/verify identity before accepting settlements.

The runtime configuration can be used to determine whether and at what point identity exchange occurs: before invoicing, before settlement, etc.

Makers and takers can both implement this layer as needed, and request/respond to identity verification at different points in the protocol.

export interface IdentityLayer {
    determineCertificatesToRequest: (args: {
        counterparty: PubKeyHex;
        threadId: ThreadId;
    }, ctx: ModuleContext) => Promise<IdentityVerificationRequest>;
    respondToRequest: (args: {
        counterparty: PubKeyHex;
        threadId: ThreadId;
        request: IdentityVerificationRequest;
    }, ctx: ModuleContext) => Promise<{
        action: "respond";
        response: IdentityVerificationResponse;
    } | {
        action: "terminate";
        termination: Termination;
    }>;
    assessReceivedCertificateSufficiency: (counterparty: PubKeyHex, received: IdentityVerificationResponse, threadId: ThreadId) => Promise<IdentityVerificationAcknowledgment | Termination>;
}

Property assessReceivedCertificateSufficiency

Assess whether received certificates satisfy the requirements for transaction settlement.

assessReceivedCertificateSufficiency: (counterparty: PubKeyHex, received: IdentityVerificationResponse, threadId: ThreadId) => Promise<IdentityVerificationAcknowledgment | Termination>

Property determineCertificatesToRequest

Determine which certificates to request from a counterparty.

determineCertificatesToRequest: (args: {
    counterparty: PubKeyHex;
    threadId: ThreadId;
}, ctx: ModuleContext) => Promise<IdentityVerificationRequest>

Property respondToRequest

Respond to an incoming identity verification request.

respondToRequest: (args: {
    counterparty: PubKeyHex;
    threadId: ThreadId;
    request: IdentityVerificationRequest;
}, ctx: ModuleContext) => Promise<{
    action: "respond";
    response: IdentityVerificationResponse;
} | {
    action: "terminate";
    termination: Termination;
}>

Links: API, Interfaces, Classes, Functions, Types, Enums, Variables

Interface: IdentityVerificationAcknowledgment

An identity verification acknowledgment.

A simple ack message indicating that a requested identity verification has been completed successfully.

export interface IdentityVerificationAcknowledgment {
    kind: "identityVerificationAcknowledgment";
    threadId: ThreadId;
}

Interface: IdentityVerificationRequest

An identity certificate request.

Contains a list of requested certificate types, fields from each, plus acceptable certifiers.

export interface IdentityVerificationRequest {
    kind: "identityVerificationRequest";
    threadId: ThreadId;
    request: {
        types: Record<string, string[]>;
        certifiers: PubKeyHex[];
    };
}

Property request

Details of the requested certificates.

request: {
    types: Record<string, string[]>;
    certifiers: PubKeyHex[];
}

See also: PubKeyHex

Links: API, Interfaces, Classes, Functions, Types, Enums, Variables

Interface: IdentityVerificationResponse

An identity certificate response.

Contains certificates issued by the certifiers named in the corresponding request, with fields revealed to the counterparty.

export interface IdentityVerificationResponse {
    kind: "identityVerificationResponse";
    threadId: ThreadId;
    certificates: Array<{
        type: Base64String;
        certifier: PubKeyHex;
        subject: PubKeyHex;
        fields: Record<string, Base64String>;
        signature: HexString;
        serialNumber: Base64String;
        revocationOutpoint: OutpointString;
        keyringForVerifier: Record<string, Base64String>;
    }>;
}

Property certificates

List of certificates issued by the certifiers named in the corresponding request, with fields revealed to the counterparty.

certificates: Array<{
    type: Base64String;
    certifier: PubKeyHex;
    subject: PubKeyHex;
    fields: Record<string, Base64String>;
    signature: HexString;
    serialNumber: Base64String;
    revocationOutpoint: OutpointString;
    keyringForVerifier: Record<string, Base64String>;
}>

Links: API, Interfaces, Classes, Functions, Types, Enums, Variables

Interface: InstrumentBase

Shared commercial/metadata fields for invoice and receipt-like instruments.

NOTE: "payee" and "payer" are identity keys, not addresses. Payment addresses / scripts are settlement-module concerns.

export interface InstrumentBase {
    threadId: ThreadId;
    payee: PubKeyHex;
    payer: PubKeyHex;
    note?: string;
    lineItems: LineItem[];
    total: Amount;
    invoiceNumber: string;
    createdAt: UnixMillis;
    arbitrary?: Record<string, unknown>;
}

See also: Amount, LineItem, PubKeyHex, ThreadId, UnixMillis

Links: API, Interfaces, Classes, Functions, Types, Enums, Variables

Interface: Invoice

Invoice (solicitation) that contains N remittance options.

Each remittance option is keyed by a module id. The payload for each option is module-defined and opaque to the core.

This is where “UTXO offers” live: a module option payload can include a partial tx template, UTXO references, scripts, overlay anchors, SPV, etc. The manager does not interpret them.

export interface Invoice extends InstrumentBase {
    kind: "invoice";
    expiresAt?: UnixMillis;
    options: Record<RemittanceOptionId, unknown>;
}

Links: API, Interfaces, Classes, Functions, Types, Enums, Variables

Interface: LineItem

export interface LineItem {
    id?: string;
    description: string;
    quantity?: string;
    unitPrice?: Amount;
    amount?: Amount;
    metadata?: Record<string, unknown>;
}

Property amount

Total amount for the line (optional if derivable).

amount?: Amount

Property quantity

Decimal string, e.g. '1', '2', '0.5'.

quantity?: string

Links: API, Interfaces, Classes, Functions, Types, Enums, Variables

Interface: LockingScriptProvider

export interface LockingScriptProvider {
    pubKeyToP2PKHLockingScript: (publicKey: string) => Promise<string> | string;
}

Property pubKeyToP2PKHLockingScript

Converts a public key string to a P2PKH locking script hex.

pubKeyToP2PKHLockingScript: (publicKey: string) => Promise<string> | string

Links: API, Interfaces, Classes, Functions, Types, Enums, Variables

Interface: LoggerLike

Simple logger interface.

export interface LoggerLike {
    log: (...args: any[]) => void;
    warn: (...args: any[]) => void;
    error: (...args: any[]) => void;
}

Links: API, Interfaces, Classes, Functions, Types, Enums, Variables

Interface: ModuleContext

Context object passed to module methods.

export interface ModuleContext {
    wallet: WalletInterface;
    originator?: unknown;
    now: () => number;
    logger?: LoggerLike;
}

Property originator

Optional originator domain forwarded to wallet methods.

originator?: unknown

Links: API, Interfaces, Classes, Functions, Types, Enums, Variables

Interface: NonceProvider

export interface NonceProvider {
    createNonce: (wallet: WalletInterface, scope: WalletCounterparty, originator?: unknown) => Promise<string>;
}

Links: API, Interfaces, Classes, Functions, Types, Enums, Variables

Interface: PeerMessage

Transport message format expected from the CommsLayer.

It closely matches the message-box-client shapes: messageId, sender, body, etc.

export interface PeerMessage {
    messageId: string;
    sender: PubKeyHex;
    recipient: PubKeyHex;
    messageBox: string;
    body: string;
}

See also: PubKeyHex

Links: API, Interfaces, Classes, Functions, Types, Enums, Variables

Interface: Receipt

Receipt issued by the payee (or service provider).

A receipt could be a PDF, a photo/oroof-of-delivery, a copy of the payment transaction, etc.

A receipt should NOT be issued when a settlement is rejected/failed. Use a Termination instead.

export interface Receipt {
    kind: "receipt";
    threadId: ThreadId;
    moduleId: RemittanceOptionId;
    optionId: RemittanceOptionId;
    payee: PubKeyHex;
    payer: PubKeyHex;
    createdAt: UnixMillis;
    receiptData: unknown;
}

Links: API, Interfaces, Classes, Functions, Types, Enums, Variables

Interface: RemittanceEnvelope

Protocol envelope.

This is what RemittanceManager serializes into the CommsLayer message body.

export interface RemittanceEnvelope<K extends RemittanceKind = RemittanceKind, P = unknown> {
    v: 1;
    id: string;
    kind: K;
    threadId: ThreadId;
    createdAt: UnixMillis;
    payload: P;
}

See also: RemittanceKind, ThreadId, UnixMillis

Property id

Envelope id (idempotency key). Not the transport messageId.

id: string

Property v

Protocol version.

v: 1

Links: API, Interfaces, Classes, Functions, Types, Enums, Variables

Interface: RemittanceEventHandlers

export interface RemittanceEventHandlers {
    onThreadCreated?: (event: Extract<RemittanceEvent, {
        type: "threadCreated";
    }>) => void;
    onStateChanged?: (event: Extract<RemittanceEvent, {
        type: "stateChanged";
    }>) => void;
    onEnvelopeSent?: (event: Extract<RemittanceEvent, {
        type: "envelopeSent";
    }>) => void;
    onEnvelopeReceived?: (event: Extract<RemittanceEvent, {
        type: "envelopeReceived";
    }>) => void;
    onIdentityRequested?: (event: Extract<RemittanceEvent, {
        type: "identityRequested";
    }>) => void;
    onIdentityResponded?: (event: Extract<RemittanceEvent, {
        type: "identityResponded";
    }>) => void;
    onIdentityAcknowledged?: (event: Extract<RemittanceEvent, {
        type: "identityAcknowledged";
    }>) => void;
    onInvoiceSent?: (event: Extract<RemittanceEvent, {
        type: "invoiceSent";
    }>) => void;
    onInvoiceReceived?: (event: Extract<RemittanceEvent, {
        type: "invoiceReceived";
    }>) => void;
    onSettlementSent?: (event: Extract<RemittanceEvent, {
        type: "settlementSent";
    }>) => void;
    onSettlementReceived?: (event: Extract<RemittanceEvent, {
        type: "settlementReceived";
    }>) => void;
    onReceiptSent?: (event: Extract<RemittanceEvent, {
        type: "receiptSent";
    }>) => void;
    onReceiptReceived?: (event: Extract<RemittanceEvent, {
        type: "receiptReceived";
    }>) => void;
    onTerminationSent?: (event: Extract<RemittanceEvent, {
        type: "terminationSent";
    }>) => void;
    onTerminationReceived?: (event: Extract<RemittanceEvent, {
        type: "terminationReceived";
    }>) => void;
    onError?: (event: Extract<RemittanceEvent, {
        type: "error";
    }>) => void;
}

Interface: RemittanceManagerConfig

export interface RemittanceManagerConfig {
    messageBox?: string;
    originator?: OriginatorDomainNameStringUnder250Bytes;
    logger?: LoggerLike;
    options?: Partial<RemittanceManagerRuntimeOptions>;
    remittanceModules: Array<RemittanceModule<any, any, any>>;
    identityLayer?: IdentityLayer;
    onEvent?: (event: RemittanceEvent) => void;
    events?: RemittanceEventHandlers;
    stateSaver?: (state: RemittanceManagerState) => Promise<void> | void;
    stateLoader?: () => Promise<RemittanceManagerState | undefined> | RemittanceManagerState | undefined;
    now?: () => UnixMillis;
    threadIdFactory?: () => ThreadId;
}

Property events

Optional event callbacks keyed by process.

events?: RemittanceEventHandlers

Property identityLayer

Optional identity layer for exchanging certificates before transacting.

identityLayer?: IdentityLayer

Property logger

Provide a logger. If omitted, RemittanceManager stays quiet.

The manager itself never throws on network/message parsing errors; it will mark threads as errored.

logger?: LoggerLike

Property messageBox

Optional message box name to use for communication.

messageBox?: string

Property now

Injectable clock for tests.

now?: () => UnixMillis

Property onEvent

Optional event callback for remittance lifecycle events.

onEvent?: (event: RemittanceEvent) => void

Property options

Runtime options that influence core behavior.

options?: Partial<RemittanceManagerRuntimeOptions>

Property originator

Optional originator forwarded to wallet APIs.

originator?: OriginatorDomainNameStringUnder250Bytes

Property remittanceModules

Modules (remittance options) available to this manager.

remittanceModules: Array<RemittanceModule<any, any, any>>

Property stateLoader

Load manager state (threads).

stateLoader?: () => Promise<RemittanceManagerState | undefined> | RemittanceManagerState | undefined

See also: RemittanceManagerState

Property stateSaver

Persist manager state (threads).

stateSaver?: (state: RemittanceManagerState) => Promise<void> | void

See also: RemittanceManagerState

Property threadIdFactory

Injectable thread id factory for tests.

threadIdFactory?: () => ThreadId

Interface: RemittanceManagerRuntimeOptions

export interface RemittanceManagerRuntimeOptions {
    identityOptions?: {
        makerRequestIdentity?: "never" | "beforeInvoicing" | "beforeSettlement";
        takerRequestIdentity?: "never" | "beforeInvoicing" | "beforeSettlement";
    };
    receiptProvided: boolean;
    autoIssueReceipt: boolean;
    invoiceExpirySeconds: number;
    identityTimeoutMs: number;
    identityPollIntervalMs: number;
}

Property autoIssueReceipt

If true, manager auto-sends receipts as soon as a settlement is processed.

autoIssueReceipt: boolean

Property identityOptions

Identity verification options.

identityOptions?: {
    makerRequestIdentity?: "never" | "beforeInvoicing" | "beforeSettlement";
    takerRequestIdentity?: "never" | "beforeInvoicing" | "beforeSettlement";
}

Property identityPollIntervalMs

Identity verification poll interval in milliseconds.

identityPollIntervalMs: number

Property identityTimeoutMs

Identity verification timeout in milliseconds.

identityTimeoutMs: number

Property invoiceExpirySeconds

Invoice expiry in seconds, or -1 for no expiry.

invoiceExpirySeconds: number

Property receiptProvided

If true, payees are expected to send receipts.

receiptProvided: boolean

Links: API, Interfaces, Classes, Functions, Types, Enums, Variables

Interface: RemittanceManagerState

export interface RemittanceManagerState {
    v: 1;
    threads: Thread[];
    defaultPaymentOptionId?: string;
}

Interface: RemittanceModule

A remittance module implements a specific settlement system.

The RemittanceManager core uses module ids as the only “capability mechanism”: if an invoice contains an option with module id X, a payer can only satisfy it if they are configured with module X.

export interface RemittanceModule<TOptionTerms = unknown, TSettlementArtifact = unknown, TReceiptData = unknown> {
    id: RemittanceOptionId;
    name: string;
    allowUnsolicitedSettlements: boolean;
    createOption?: (args: {
        threadId: ThreadId;
        invoice: Invoice;
    }, ctx: ModuleContext) => Promise<TOptionTerms>;
    buildSettlement: (args: {
        threadId: ThreadId;
        invoice?: Invoice;
        option: TOptionTerms;
        note?: string;
    }, ctx: ModuleContext) => Promise<{
        action: "settle";
        artifact: TSettlementArtifact;
    } | {
        action: "terminate";
        termination: Termination;
    }>;
    acceptSettlement: (args: {
        threadId: ThreadId;
        invoice?: Invoice;
        settlement: TSettlementArtifact;
        sender: PubKeyHex;
    }, ctx: ModuleContext) => Promise<{
        action: "accept";
        receiptData?: TReceiptData;
    } | {
        action: "terminate";
        termination: Termination;
    }>;
    processReceipt?: (args: {
        threadId: ThreadId;
        invoice?: Invoice;
        receiptData: TReceiptData;
        sender: PubKeyHex;
    }, ctx: ModuleContext) => Promise<void>;
    processTermination?: (args: {
        threadId: ThreadId;
        invoice?: Invoice;
        settlement?: Settlement;
        termination: Termination;
        sender: PubKeyHex;
    }, ctx: ModuleContext) => Promise<void>;
}

Property acceptSettlement

Accepts a settlement artifact on the payee side.

The module should validate and internalize/store whatever it needs. The manager will wrap the returned value as receipt.receiptData.

If the settlement is invalid, the module should return either a termination or receiptData (possibly with a refund or indicating the failure), depending how the module chooses to handle it.

acceptSettlement: (args: {
    threadId: ThreadId;
    invoice?: Invoice;
    settlement: TSettlementArtifact;
    sender: PubKeyHex;
}, ctx: ModuleContext) => Promise<{
    action: "accept";
    receiptData?: TReceiptData;
} | {
    action: "terminate";
    termination: Termination;
}>

Property allowUnsolicitedSettlements

Whether this module allows unsolicited settlements (i.e. settlement without an invoice).

If true, the payer can build a settlement without an invoice being provided by the payee. In this case, the option terms provided to buildSettlement may be used in lieu of an invoice.

If false, an invoice must always be provided to buildSettlement.

allowUnsolicitedSettlements: boolean

Property buildSettlement

Builds the settlement artifact for a chosen option.

For UTXO settlement systems, this is usually a transaction (or partially-signed tx) to be broadcast.

For unsolicited settlements, an invoice may not always be provided and the option terms may be used in lieu of an invoice to settle against.

For example, the option terms may include a tx template with outputs to fulfill the settlement.

When allowUnsolicitedSettlements is false, an invoice will always be provided.

Termination can be returned to abort the protocol with a reason.

buildSettlement: (args: {
    threadId: ThreadId;
    invoice?: Invoice;
    option: TOptionTerms;
    note?: string;
}, ctx: ModuleContext) => Promise<{
    action: "settle";
    artifact: TSettlementArtifact;
} | {
    action: "terminate";
    termination: Termination;
}>

See also: Invoice, ModuleContext, Termination, ThreadId

Property createOption

Creates module-defined option terms that will be embedded into the invoice.

In UTXO-ish offers, these option terms may include a partially-signed transaction template.

Optional because some modules may not require any option data, or may only support unsolicited settlements.

However, a module MAY still create option terms/invoices even if it can sometimes support unsolicited settlements.

createOption?: (args: {
    threadId: ThreadId;
    invoice: Invoice;
}, ctx: ModuleContext) => Promise<TOptionTerms>

See also: Invoice, ModuleContext, ThreadId

Property id

Unique id used as the invoice.options key and as settlement.moduleId.

id: RemittanceOptionId

Property name

Human-readable name for UIs.

name: string

Property processReceipt

Processes a receipt on the payer side.

This is where a module can automatically internalize a refund, mark a local order fulfilled, receive goods and services, etc.

processReceipt?: (args: {
    threadId: ThreadId;
    invoice?: Invoice;
    receiptData: TReceiptData;
    sender: PubKeyHex;
}, ctx: ModuleContext) => Promise<void>

See also: Invoice, ModuleContext, PubKeyHex, ThreadId

Property processTermination

Processes a termination on either side.

This is where a module can clean up any internal state, reverse provisional actions, take refunds, etc.

processTermination?: (args: {
    threadId: ThreadId;
    invoice?: Invoice;
    settlement?: Settlement;
    termination: Termination;
    sender: PubKeyHex;
}, ctx: ModuleContext) => Promise<void>

Links: API, Interfaces, Classes, Functions, Types, Enums, Variables

Interface: Settlement

A settlement attempt.

This is module-agnostic: "artifact" can be a transaction, a partial transaction, a stablecoin transfer result, even a fiat card-payment approval code, etc.

export interface Settlement {
    kind: "settlement";
    threadId: ThreadId;
    moduleId: RemittanceOptionId;
    optionId: RemittanceOptionId;
    sender: PubKeyHex;
    createdAt: UnixMillis;
    artifact: unknown;
    note?: string;
}

Links: API, Interfaces, Classes, Functions, Types, Enums, Variables

Interface: Termination

Termination details for failed operations.

export interface Termination {
    code: string;
    message: string;
    details?: unknown;
}

Property code

Reason code (module-specific).

code: string

Property details

Optional module-specific details or refund information.

details?: unknown

Property message

Human-readable message.

message: string

Links: API, Interfaces, Classes, Functions, Types, Enums, Variables

Interface: Thread

export interface Thread {
    threadId: ThreadId;
    counterparty: PubKeyHex;
    myRole: "maker" | "taker";
    theirRole: "maker" | "taker";
    createdAt: UnixMillis;
    updatedAt: UnixMillis;
    state: RemittanceThreadState;
    stateLog: Array<{
        at: UnixMillis;
        from: RemittanceThreadState;
        to: RemittanceThreadState;
        reason?: string;
    }>;
    processedMessageIds: string[];
    protocolLog: Array<{
        direction: "in" | "out";
        envelope: RemittanceEnvelope;
        transportMessageId: string;
    }>;
    identity: {
        certsSent: IdentityVerificationResponse["certificates"];
        certsReceived: IdentityVerificationResponse["certificates"];
        requestSent: boolean;
        responseSent: boolean;
        acknowledgmentSent: boolean;
        acknowledgmentReceived: boolean;
    };
    invoice?: Invoice;
    settlement?: Settlement;
    receipt?: Receipt;
    termination?: Termination;
    flags: {
        hasIdentified: boolean;
        hasInvoiced: boolean;
        hasPaid: boolean;
        hasReceipted: boolean;
        error: boolean;
    };
    lastError?: {
        message: string;
        at: UnixMillis;
    };
}

Property processedMessageIds

Transport messageIds processed for this thread (dedupe across retries).

processedMessageIds: string[]

Property protocolLog

Protocol envelopes received/sent (for debugging/audit).

protocolLog: Array<{
    direction: "in" | "out";
    envelope: RemittanceEnvelope;
    transportMessageId: string;
}>

Property stateLog

State transition log for audit purposes.

stateLog: Array<{
    at: UnixMillis;
    from: RemittanceThreadState;
    to: RemittanceThreadState;
    reason?: string;
}>

Links: API, Interfaces, Classes, Functions, Types, Enums, Variables

Interface: Unit

export interface Unit {
    namespace: string;
    code: string;
    decimals?: number;
}

Property code

Unit code within the namespace, e.g. 'sat', 'USD', 'mnee'.

code: string

Property decimals

Optional decimal places for display/normalization.

decimals?: number

Property namespace

Namespace for disambiguation, e.g. 'bsv', 'iso4217', 'token'.

namespace: string

Links: API, Interfaces, Classes, Functions, Types, Enums, Variables

Classes


Brc29RemittanceModule
InvoiceHandle
RemittanceManager
ThreadHandle

Links: API, Interfaces, Classes, Functions, Types, Enums, Variables

Class: Brc29RemittanceModule

BRC-29-based remittance module. - payer creates a payment action to a derived P2PKH output - payer sends { tx, derivationPrefix, derivationSuffix } as settlement artifact - payee internalizes the tx output using wallet.internalizeAction - optional rejection can include a refund token embedded in the termination details

export class Brc29RemittanceModule implements RemittanceModule<Brc29OptionTerms, Brc29SettlementArtifact, Brc29ReceiptData> {
    readonly id: RemittanceOptionId = "brc29.p2pkh";
    readonly name = "BSV (BRC-29 derived P2PKH)";
    readonly allowUnsolicitedSettlements = true;
    constructor(cfg: Brc29RemittanceModuleConfig = {}) 
    async buildSettlement(args: {
        threadId: string;
        option: Brc29OptionTerms;
        note?: string;
    }, ctx: ModuleContext): Promise<{
        action: "settle";
        artifact: Brc29SettlementArtifact;
    } | {
        action: "terminate";
        termination: Termination;
    }> 
    async acceptSettlement(args: {
        threadId: string;
        settlement: Brc29SettlementArtifact;
        sender: PubKeyHex;
    }, ctx: ModuleContext): Promise<{
        action: "accept";
        receiptData?: Brc29ReceiptData;
    } | {
        action: "terminate";
        termination: Termination;
    }> 
}

Links: API, Interfaces, Classes, Functions, Types, Enums, Variables

Class: InvoiceHandle

export class InvoiceHandle extends ThreadHandle {
    get invoice(): Invoice 
    async pay(optionId?: string): Promise<Receipt | Termination | undefined> 
}

See also: Invoice, Receipt, Termination, ThreadHandle

Method pay

Pays the invoice using the selected remittance option.

async pay(optionId?: string): Promise<Receipt | Termination | undefined>

Class: RemittanceManager

RemittanceManager.

Responsibilities: - message transport via CommsLayer - thread lifecycle and persistence (via stateSaver/stateLoader) - invoice creation and transmission (when invoices are used) - settlement and settlement routing to the appropriate module - receipt issuance and receipt routing to the appropriate module - identity and identity certificate exchange (when identity layer is used)

Non-responsibilities (left to modules): - transaction structure (whether UTXO “offer” formats, token logic, BRC-98/99 specifics, etc.) - validation rules for settlement (e.g. partial tx templates, UTXO validity, etc.) - on-chain broadcasting strategy or non-chain settlement specifics (like legacy payment protocols) - Providing option terms for invoices - Building settlement artifacts - Accepting/rejecting settlements - Deciding which identity certificates to request - Deciding about sufficiency of identity certificates - Preparing/processing specific receipt formats - Internal business logic like order fulfillment, refunds, etc.

export class RemittanceManager {
    readonly wallet: WalletInterface;
    readonly comms: CommsLayer;
    readonly cfg: RemittanceManagerConfig;
    threads: Thread[];
    constructor(cfg: RemittanceManagerConfig, wallet: WalletInterface, commsLayer: CommsLayer, threads: Thread[] = []) 
    async init(): Promise<void> 
    onEvent(listener: (event: RemittanceEvent) => void): () => void 
    preselectPaymentOption(optionId: string): void 
    saveState(): RemittanceManagerState 
    loadState(state: RemittanceManagerState): void 
    async persistState(): Promise<void> 
    async syncThreads(hostOverride?: string): Promise<void> 
    async startListening(hostOverride?: string): Promise<void> 
    async sendInvoice(to: PubKeyHex, input: ComposeInvoiceInput, hostOverride?: string): Promise<InvoiceHandle> 
    async sendInvoiceForThread(threadId: ThreadId, input: ComposeInvoiceInput, hostOverride?: string): Promise<InvoiceHandle> 
    findInvoicesPayable(counterparty?: PubKeyHex): InvoiceHandle[] 
    findReceivableInvoices(counterparty?: PubKeyHex): InvoiceHandle[] 
    async pay(threadId: ThreadId, optionId?: string, hostOverride?: string): Promise<Receipt | Termination | undefined> 
    async waitForReceipt(threadId: ThreadId, opts: {
        timeoutMs?: number;
        pollIntervalMs?: number;
    } = {}): Promise<Receipt | Termination> 
    async waitForState(threadId: ThreadId, state: RemittanceThreadState, opts: {
        timeoutMs?: number;
        pollIntervalMs?: number;
    } = {}): Promise<Thread> 
    async waitForIdentity(threadId: ThreadId, opts?: {
        timeoutMs?: number;
        pollIntervalMs?: number;
    }): Promise<Thread> 
    async waitForSettlement(threadId: ThreadId, opts: {
        timeoutMs?: number;
        pollIntervalMs?: number;
    } = {}): Promise<Settlement | Termination> 
    async sendUnsolicitedSettlement(to: PubKeyHex, args: {
        moduleId: RemittanceOptionId;
        option: unknown;
        optionId?: RemittanceOptionId;
        note?: string;
    }, hostOverride?: string): Promise<ThreadHandle> 
    getThread(threadId: ThreadId): Thread | undefined 
    getThreadHandle(threadId: ThreadId): ThreadHandle 
    getThreadOrThrow(threadId: ThreadId): Thread 
}

Property threads

Mutable threads list (persisted via stateSaver).

threads: Thread[]

Method findInvoicesPayable

Returns invoice handles that this manager can pay (we are the taker/payer).

findInvoicesPayable(counterparty?: PubKeyHex): InvoiceHandle[]

Method findReceivableInvoices

Returns invoice handles that we issued and are waiting to receive settlement for.

findReceivableInvoices(counterparty?: PubKeyHex): InvoiceHandle[]

Method getThread

Returns a thread by id (if present).

getThread(threadId: ThreadId): Thread | undefined

Method getThreadHandle

Returns a thread handle by id, or throws if the thread does not exist.

getThreadHandle(threadId: ThreadId): ThreadHandle

Method getThreadOrThrow

Returns a thread by id or throws.

Public so helper handles (e.g. InvoiceHandle) can call it.

getThreadOrThrow(threadId: ThreadId): Thread

Method init

Loads persisted state from cfg.stateLoader (if provided).

Safe to call multiple times.

async init(): Promise<void>

Method loadState

Loads state from an object previously produced by saveState().

loadState(state: RemittanceManagerState): void

See also: RemittanceManagerState

Method onEvent

Registers a remittance event listener.

onEvent(listener: (event: RemittanceEvent) => void): () => void

Method pay

Pays an invoice by selecting a remittance option and sending a settlement message.

If receipts are enabled (receiptProvided), this method will optionally wait for a receipt.

async pay(threadId: ThreadId, optionId?: string, hostOverride?: string): Promise<Receipt | Termination | undefined>

See also: Receipt, Termination, ThreadId

Method persistState

Persists current state via cfg.stateSaver (if provided).

async persistState(): Promise<void>

Method preselectPaymentOption

Sets a default payment option (module id) to use when paying invoices.

preselectPaymentOption(optionId: string): void

Method saveState

Returns an immutable snapshot of current manager state suitable for persistence.

saveState(): RemittanceManagerState

See also: RemittanceManagerState

Method sendInvoice

Creates, records, and sends an invoice to a counterparty.

Returns a handle you can use to wait for payment/receipt.

async sendInvoice(to: PubKeyHex, input: ComposeInvoiceInput, hostOverride?: string): Promise<InvoiceHandle>

Method sendInvoiceForThread

Sends an invoice for an existing thread, e.g. after an identity request was received.

async sendInvoiceForThread(threadId: ThreadId, input: ComposeInvoiceInput, hostOverride?: string): Promise<InvoiceHandle>

Method sendUnsolicitedSettlement

Sends an unsolicited settlement to a counterparty.

async sendUnsolicitedSettlement(to: PubKeyHex, args: {
    moduleId: RemittanceOptionId;
    option: unknown;
    optionId?: RemittanceOptionId;
    note?: string;
}, hostOverride?: string): Promise<ThreadHandle>

Method startListening

Starts listening for live messages (if the CommsLayer supports it).

async startListening(hostOverride?: string): Promise<void>

Method syncThreads

Syncs threads by fetching pending messages from the comms layer and processing them.

Processing is idempotent using transport messageIds tracked per thread. Messages are acknowledged after they are successfully applied to local state.

async syncThreads(hostOverride?: string): Promise<void>

Method waitForIdentity

Waits for identity exchange to complete for a thread.

async waitForIdentity(threadId: ThreadId, opts?: {
    timeoutMs?: number;
    pollIntervalMs?: number;
}): Promise<Thread>

Method waitForReceipt

Waits for a receipt to arrive for a thread.

Uses polling via syncThreads because live listeners are optional.

async waitForReceipt(threadId: ThreadId, opts: {
    timeoutMs?: number;
    pollIntervalMs?: number;
} = {}): Promise<Receipt | Termination>

See also: Receipt, Termination, ThreadId

Method waitForSettlement

Waits for a settlement to arrive for a thread.

async waitForSettlement(threadId: ThreadId, opts: {
    timeoutMs?: number;
    pollIntervalMs?: number;
} = {}): Promise<Settlement | Termination>

See also: Settlement, Termination, ThreadId

Method waitForState

Waits for a thread to reach a specific state.

async waitForState(threadId: ThreadId, state: RemittanceThreadState, opts: {
    timeoutMs?: number;
    pollIntervalMs?: number;
} = {}): Promise<Thread>

Links: API, Interfaces, Classes, Functions, Types, Enums, Variables

Class: ThreadHandle

A lightweight wrapper around a thread's invoice, with convenience methods.

export class ThreadHandle {
    constructor(protected readonly manager: RemittanceManager, public readonly threadId: ThreadId) 
    get thread(): Thread 
    async waitForState(state: RemittanceThreadState, opts?: {
        timeoutMs?: number;
        pollIntervalMs?: number;
    }): Promise<Thread> 
    async waitForIdentity(opts?: {
        timeoutMs?: number;
        pollIntervalMs?: number;
    }): Promise<Thread> 
    async waitForSettlement(opts?: {
        timeoutMs?: number;
        pollIntervalMs?: number;
    }): Promise<Settlement | Termination> 
    async waitForReceipt(opts?: {
        timeoutMs?: number;
        pollIntervalMs?: number;
    }): Promise<Receipt | Termination> 
}

Links: API, Interfaces, Classes, Functions, Types, Enums, Variables

Functions

Types


RemittanceEvent
RemittanceKind
RemittanceOptionId
RemittanceThreadState
ThreadId
UnixMillis

Links: API, Interfaces, Classes, Functions, Types, Enums, Variables

Type: RemittanceEvent

export type RemittanceEvent = {
    type: "threadCreated";
    threadId: ThreadId;
    thread: Thread;
} | {
    type: "stateChanged";
    threadId: ThreadId;
    previous: RemittanceThreadState;
    next: RemittanceThreadState;
    reason?: string;
} | {
    type: "envelopeSent";
    threadId: ThreadId;
    envelope: RemittanceEnvelope;
    transportMessageId: string;
} | {
    type: "envelopeReceived";
    threadId: ThreadId;
    envelope: RemittanceEnvelope;
    transportMessageId: string;
} | {
    type: "identityRequested";
    threadId: ThreadId;
    direction: "in" | "out";
    request: IdentityVerificationRequest;
} | {
    type: "identityResponded";
    threadId: ThreadId;
    direction: "in" | "out";
    response: IdentityVerificationResponse;
} | {
    type: "identityAcknowledged";
    threadId: ThreadId;
    direction: "in" | "out";
    acknowledgment: IdentityVerificationAcknowledgment;
} | {
    type: "invoiceSent";
    threadId: ThreadId;
    invoice: Invoice;
} | {
    type: "invoiceReceived";
    threadId: ThreadId;
    invoice: Invoice;
} | {
    type: "settlementSent";
    threadId: ThreadId;
    settlement: Settlement;
} | {
    type: "settlementReceived";
    threadId: ThreadId;
    settlement: Settlement;
} | {
    type: "receiptSent";
    threadId: ThreadId;
    receipt: Receipt;
} | {
    type: "receiptReceived";
    threadId: ThreadId;
    receipt: Receipt;
} | {
    type: "terminationSent";
    threadId: ThreadId;
    termination: Termination;
} | {
    type: "terminationReceived";
    threadId: ThreadId;
    termination: Termination;
} | {
    type: "error";
    threadId: ThreadId;
    error: string;
}

Links: API, Interfaces, Classes, Functions, Types, Enums, Variables

Type: RemittanceKind

Protocol envelope kinds. Everything runs in “threads” and carries a threadId.

export type RemittanceKind = "invoice" | "identityVerificationRequest" | "identityVerificationResponse" | "identityVerificationAcknowledgment" | "settlement" | "receipt" | "termination"

Links: API, Interfaces, Classes, Functions, Types, Enums, Variables

Type: RemittanceOptionId

export type RemittanceOptionId = Base64String

Type: RemittanceThreadState

Remittance thread state machine.

States: - new: thread exists but no identity/invoice/settlement activity yet. - identityRequested: identity request sent or received. - identityResponded: identity response sent or received. - identityAcknowledged: identity response acknowledged (required before proceeding). - invoiced: invoice sent or received. - settled: settlement sent or received. - receipted: receipt issued or received. - terminated: thread terminated with a reason. - errored: unexpected error occurred while processing the thread.

export type RemittanceThreadState = "new" | "identityRequested" | "identityResponded" | "identityAcknowledged" | "invoiced" | "settled" | "receipted" | "terminated" | "errored"

Links: API, Interfaces, Classes, Functions, Types, Enums, Variables

Type: ThreadId

Types for core Remittance protocol.

The goal is to keep the core protocol: - UTXO-friendly (transactions and partial transactions can be carried as artifacts) - Denomination-agnostic (amounts are typed, not forced to satoshis) - Module-oriented (remittance option payloads are opaque to the core)

export type ThreadId = Base64String

Type: UnixMillis

export type UnixMillis = number

Links: API, Interfaces, Classes, Functions, Types, Enums, Variables

Enums

Variables


DEFAULT_REMITTANCE_MESSAGEBOX
DefaultLockingScriptProvider
DefaultNonceProvider
REMITTANCE_STATE_TRANSITIONS
SAT_UNIT

Links: API, Interfaces, Classes, Functions, Types, Enums, Variables

Variable: DEFAULT_REMITTANCE_MESSAGEBOX

DEFAULT_REMITTANCE_MESSAGEBOX = "remittance_inbox"

Links: API, Interfaces, Classes, Functions, Types, Enums, Variables

Variable: DefaultLockingScriptProvider

DefaultLockingScriptProvider: LockingScriptProvider = {
    async pubKeyToP2PKHLockingScript(publicKey: string) {
        const address = PublicKey.fromString(publicKey).toAddress();
        return new P2PKH().lock(address).toHex();
    }
}

Links: API, Interfaces, Classes, Functions, Types, Enums, Variables

Variable: DefaultNonceProvider

DefaultNonceProvider: NonceProvider = {
    async createNonce(wallet, scope, originator) {
        const origin = originator as OriginatorDomainNameStringUnder250Bytes | undefined;
        return await createNonce(wallet, scope, origin);
    }
}

Links: API, Interfaces, Classes, Functions, Types, Enums, Variables

Variable: REMITTANCE_STATE_TRANSITIONS

REMITTANCE_STATE_TRANSITIONS: Record<RemittanceThreadState, RemittanceThreadState[]> = {
    new: ["identityRequested", "invoiced", "settled", "terminated", "errored"],
    identityRequested: ["identityResponded", "identityAcknowledged", "invoiced", "settled", "terminated", "errored"],
    identityResponded: ["identityAcknowledged", "invoiced", "settled", "terminated", "errored"],
    identityAcknowledged: ["invoiced", "settled", "terminated", "errored"],
    invoiced: ["identityRequested", "identityResponded", "identityAcknowledged", "settled", "terminated", "errored"],
    settled: ["receipted", "terminated", "errored"],
    receipted: ["terminated", "errored"],
    terminated: ["errored"],
    errored: []
}

Variable: SAT_UNIT

SAT_UNIT: Unit = { namespace: "bsv", code: "sat", decimals: 0 }