@bsv/sdk 1.10.4 → 2.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/cjs/mod.js +1 -0
- package/dist/cjs/mod.js.map +1 -1
- package/dist/cjs/package.json +2 -3
- package/dist/cjs/src/auth/Peer.js +18 -20
- package/dist/cjs/src/auth/Peer.js.map +1 -1
- package/dist/cjs/src/identity/IdentityClient.js +20 -124
- package/dist/cjs/src/identity/IdentityClient.js.map +1 -1
- package/dist/cjs/src/primitives/TransactionSignature.js +115 -10
- package/dist/cjs/src/primitives/TransactionSignature.js.map +1 -1
- package/dist/cjs/src/primitives/utils.js +13 -112
- package/dist/cjs/src/primitives/utils.js.map +1 -1
- package/dist/cjs/src/remittance/CommsLayer.js +3 -0
- package/dist/cjs/src/remittance/CommsLayer.js.map +1 -0
- package/dist/cjs/src/remittance/IdentityLayer.js +3 -0
- package/dist/cjs/src/remittance/IdentityLayer.js.map +1 -0
- package/dist/cjs/src/remittance/RemittanceManager.js +1245 -0
- package/dist/cjs/src/remittance/RemittanceManager.js.map +1 -0
- package/dist/cjs/src/remittance/RemittanceModule.js +3 -0
- package/dist/cjs/src/remittance/RemittanceModule.js.map +1 -0
- package/dist/cjs/src/remittance/index.js +23 -0
- package/dist/cjs/src/remittance/index.js.map +1 -0
- package/dist/cjs/src/remittance/modules/BasicBRC29.js +225 -0
- package/dist/cjs/src/remittance/modules/BasicBRC29.js.map +1 -0
- package/dist/cjs/src/remittance/modules/index.js +18 -0
- package/dist/cjs/src/remittance/modules/index.js.map +1 -0
- package/dist/cjs/src/remittance/types.js +22 -0
- package/dist/cjs/src/remittance/types.js.map +1 -0
- package/dist/cjs/src/script/OP.js +15 -13
- package/dist/cjs/src/script/OP.js.map +1 -1
- package/dist/cjs/src/script/Script.js +4 -1
- package/dist/cjs/src/script/Script.js.map +1 -1
- package/dist/cjs/src/script/Spend.js +128 -46
- package/dist/cjs/src/script/Spend.js.map +1 -1
- package/dist/cjs/src/transaction/BeefTx.js +2 -2
- package/dist/cjs/src/transaction/Transaction.js +160 -0
- package/dist/cjs/src/transaction/Transaction.js.map +1 -1
- package/dist/cjs/tsconfig.cjs.tsbuildinfo +1 -1
- package/dist/esm/mod.js +1 -0
- package/dist/esm/mod.js.map +1 -1
- package/dist/esm/src/auth/Peer.js +18 -20
- package/dist/esm/src/auth/Peer.js.map +1 -1
- package/dist/esm/src/identity/IdentityClient.js +20 -124
- package/dist/esm/src/identity/IdentityClient.js.map +1 -1
- package/dist/esm/src/primitives/TransactionSignature.js +115 -10
- package/dist/esm/src/primitives/TransactionSignature.js.map +1 -1
- package/dist/esm/src/primitives/utils.js +13 -112
- package/dist/esm/src/primitives/utils.js.map +1 -1
- package/dist/esm/src/remittance/CommsLayer.js +2 -0
- package/dist/esm/src/remittance/CommsLayer.js.map +1 -0
- package/dist/esm/src/remittance/IdentityLayer.js +2 -0
- package/dist/esm/src/remittance/IdentityLayer.js.map +1 -0
- package/dist/esm/src/remittance/RemittanceManager.js +1254 -0
- package/dist/esm/src/remittance/RemittanceManager.js.map +1 -0
- package/dist/esm/src/remittance/RemittanceModule.js +2 -0
- package/dist/esm/src/remittance/RemittanceModule.js.map +1 -0
- package/dist/esm/src/remittance/index.js +7 -0
- package/dist/esm/src/remittance/index.js.map +1 -0
- package/dist/esm/src/remittance/modules/BasicBRC29.js +227 -0
- package/dist/esm/src/remittance/modules/BasicBRC29.js.map +1 -0
- package/dist/esm/src/remittance/modules/index.js +2 -0
- package/dist/esm/src/remittance/modules/index.js.map +1 -0
- package/dist/esm/src/remittance/types.js +19 -0
- package/dist/esm/src/remittance/types.js.map +1 -0
- package/dist/esm/src/script/OP.js +15 -13
- package/dist/esm/src/script/OP.js.map +1 -1
- package/dist/esm/src/script/Script.js +4 -1
- package/dist/esm/src/script/Script.js.map +1 -1
- package/dist/esm/src/script/Spend.js +129 -46
- package/dist/esm/src/script/Spend.js.map +1 -1
- package/dist/esm/src/transaction/BeefTx.js +3 -3
- package/dist/esm/src/transaction/BeefTx.js.map +1 -1
- package/dist/esm/src/transaction/Transaction.js +160 -0
- package/dist/esm/src/transaction/Transaction.js.map +1 -1
- package/dist/esm/tsconfig.esm.tsbuildinfo +1 -1
- package/dist/types/mod.d.ts +1 -0
- package/dist/types/mod.d.ts.map +1 -1
- package/dist/types/src/auth/Peer.d.ts +3 -7
- package/dist/types/src/auth/Peer.d.ts.map +1 -1
- package/dist/types/src/identity/IdentityClient.d.ts +0 -8
- package/dist/types/src/identity/IdentityClient.d.ts.map +1 -1
- package/dist/types/src/primitives/TransactionSignature.d.ts +16 -4
- package/dist/types/src/primitives/TransactionSignature.d.ts.map +1 -1
- package/dist/types/src/primitives/utils.d.ts +1 -0
- package/dist/types/src/primitives/utils.d.ts.map +1 -1
- package/dist/types/src/remittance/CommsLayer.d.ts +50 -0
- package/dist/types/src/remittance/CommsLayer.d.ts.map +1 -0
- package/dist/types/src/remittance/IdentityLayer.d.ts +35 -0
- package/dist/types/src/remittance/IdentityLayer.d.ts.map +1 -0
- package/dist/types/src/remittance/RemittanceManager.d.ts +452 -0
- package/dist/types/src/remittance/RemittanceManager.d.ts.map +1 -0
- package/dist/types/src/remittance/RemittanceModule.d.ts +106 -0
- package/dist/types/src/remittance/RemittanceModule.d.ts.map +1 -0
- package/dist/types/src/remittance/index.d.ts +7 -0
- package/dist/types/src/remittance/index.d.ts.map +1 -0
- package/dist/types/src/remittance/modules/BasicBRC29.d.ts +133 -0
- package/dist/types/src/remittance/modules/BasicBRC29.d.ts.map +1 -0
- package/dist/types/src/remittance/modules/index.d.ts +2 -0
- package/dist/types/src/remittance/modules/index.d.ts.map +1 -0
- package/dist/types/src/remittance/types.d.ts +238 -0
- package/dist/types/src/remittance/types.d.ts.map +1 -0
- package/dist/types/src/script/OP.d.ts +5 -3
- package/dist/types/src/script/OP.d.ts.map +1 -1
- package/dist/types/src/script/Script.d.ts.map +1 -1
- package/dist/types/src/script/Spend.d.ts +7 -0
- package/dist/types/src/script/Spend.d.ts.map +1 -1
- package/dist/types/src/transaction/BeefTx.d.ts +2 -2
- package/dist/types/src/transaction/Transaction.d.ts +14 -0
- package/dist/types/src/transaction/Transaction.d.ts.map +1 -1
- package/dist/types/src/wallet/Wallet.interfaces.d.ts +5 -5
- package/dist/types/src/wallet/Wallet.interfaces.d.ts.map +1 -1
- package/dist/types/tsconfig.types.tsbuildinfo +1 -1
- package/dist/umd/bundle.js +13 -13
- package/dist/umd/bundle.js.map +1 -1
- package/docs/index.md +2 -14
- package/docs/reference/auth.md +6 -12
- package/docs/reference/primitives.md +20 -78
- package/docs/reference/remittance.md +2166 -0
- package/docs/reference/script.md +11 -3
- package/docs/reference/transaction.md +27 -1
- package/docs/reference/wallet.md +6 -5
- package/docs/remittance-getting-started.md +138 -0
- package/mod.ts +1 -0
- package/package.json +12 -3
- package/src/auth/Peer.ts +18 -29
- package/src/auth/__tests/Peer.test.ts +253 -1
- package/src/identity/IdentityClient.ts +29 -153
- package/src/identity/__tests/IdentityClient.test.ts +1 -289
- package/src/overlay-tools/__tests/SHIPBroadcaster.test.ts +7 -9
- package/src/primitives/TransactionSignature.ts +129 -10
- package/src/primitives/__tests/utils.test.ts +30 -7
- package/src/primitives/utils.ts +13 -129
- package/src/remittance/CommsLayer.ts +41 -0
- package/src/remittance/IdentityLayer.ts +32 -0
- package/src/remittance/RemittanceManager.ts +1672 -0
- package/src/remittance/RemittanceModule.ts +92 -0
- package/src/remittance/__tests/BasicBRC29.test.ts +188 -0
- package/src/remittance/__tests/RemittanceManager.test.ts +493 -0
- package/src/remittance/__tests/examples.ts +130 -0
- package/src/remittance/index.ts +6 -0
- package/src/remittance/modules/BasicBRC29.ts +361 -0
- package/src/remittance/modules/index.ts +1 -0
- package/src/remittance/types.ts +284 -0
- package/src/script/OP.ts +15 -13
- package/src/script/Script.ts +3 -1
- package/src/script/Spend.ts +128 -52
- package/src/script/__tests/Chronicle.test.ts +186 -0
- package/src/script/__tests/Spend.test.ts +1 -1
- package/src/script/__tests/SpendValildVectors.test.ts +63 -0
- package/src/script/__tests/lrshiftnum.test.ts +185 -0
- package/src/script/__tests/sighashTestData.ts +1031 -0
- package/src/script/__tests/spend.valid.vectors.ts +9 -16
- package/src/transaction/BeefTx.ts +3 -3
- package/src/transaction/Transaction.ts +186 -0
- package/src/transaction/__tests/Beef.test.ts +2 -0
- package/src/transaction/__tests/Transaction.test.ts +641 -3
- package/src/wallet/Wallet.interfaces.ts +5 -5
|
@@ -0,0 +1,452 @@
|
|
|
1
|
+
import type { Invoice, IdentityVerificationRequest, IdentityVerificationResponse, IdentityVerificationAcknowledgment, Settlement, Receipt, Termination, RemittanceEnvelope, ThreadId, UnixMillis, LoggerLike, RemittanceOptionId, RemittanceThreadState } from './types.js';
|
|
2
|
+
import type { CommsLayer } from './CommsLayer.js';
|
|
3
|
+
import type { IdentityLayer } from './IdentityLayer.js';
|
|
4
|
+
import type { RemittanceModule } from './RemittanceModule.js';
|
|
5
|
+
import { OriginatorDomainNameStringUnder250Bytes, PubKeyHex, WalletInterface } from '../wallet/Wallet.interfaces.js';
|
|
6
|
+
export declare const DEFAULT_REMITTANCE_MESSAGEBOX = "remittance_inbox";
|
|
7
|
+
export interface RemittanceManagerRuntimeOptions {
|
|
8
|
+
/** Identity verification options. */
|
|
9
|
+
identityOptions?: {
|
|
10
|
+
/** At what point should a maker request identity verification? */
|
|
11
|
+
makerRequestIdentity?: 'never' | 'beforeInvoicing' | 'beforeSettlement';
|
|
12
|
+
/** At what point should a taker request identity verification? */
|
|
13
|
+
takerRequestIdentity?: 'never' | 'beforeInvoicing' | 'beforeSettlement';
|
|
14
|
+
};
|
|
15
|
+
/** If true, payees are expected to send receipts. */
|
|
16
|
+
receiptProvided: boolean;
|
|
17
|
+
/** If true, manager auto-sends receipts as soon as a settlement is processed. */
|
|
18
|
+
autoIssueReceipt: boolean;
|
|
19
|
+
/** Invoice expiry in seconds, or -1 for no expiry. */
|
|
20
|
+
invoiceExpirySeconds: number;
|
|
21
|
+
/** Identity verification timeout in milliseconds. */
|
|
22
|
+
identityTimeoutMs: number;
|
|
23
|
+
/** Identity verification poll interval in milliseconds. */
|
|
24
|
+
identityPollIntervalMs: number;
|
|
25
|
+
}
|
|
26
|
+
export interface RemittanceManagerConfig {
|
|
27
|
+
/** Optional message box name to use for communication. */
|
|
28
|
+
messageBox?: string;
|
|
29
|
+
/** Optional originator forwarded to wallet APIs. */
|
|
30
|
+
originator?: OriginatorDomainNameStringUnder250Bytes;
|
|
31
|
+
/**
|
|
32
|
+
* Provide a logger. If omitted, RemittanceManager stays quiet.
|
|
33
|
+
*
|
|
34
|
+
* The manager itself never throws on network/message parsing errors; it will mark threads as errored.
|
|
35
|
+
*/
|
|
36
|
+
logger?: LoggerLike;
|
|
37
|
+
/** Runtime options that influence core behavior. */
|
|
38
|
+
options?: Partial<RemittanceManagerRuntimeOptions>;
|
|
39
|
+
/** Modules (remittance options) available to this manager. */
|
|
40
|
+
remittanceModules: Array<RemittanceModule<any, any, any>>;
|
|
41
|
+
/** Optional identity layer for exchanging certificates before transacting. */
|
|
42
|
+
identityLayer?: IdentityLayer;
|
|
43
|
+
/** Optional event callback for remittance lifecycle events. */
|
|
44
|
+
onEvent?: (event: RemittanceEvent) => void;
|
|
45
|
+
/** Optional event callbacks keyed by process. */
|
|
46
|
+
events?: RemittanceEventHandlers;
|
|
47
|
+
/** Persist manager state (threads). */
|
|
48
|
+
stateSaver?: (state: RemittanceManagerState) => Promise<void> | void;
|
|
49
|
+
/** Load manager state (threads). */
|
|
50
|
+
stateLoader?: () => Promise<RemittanceManagerState | undefined> | RemittanceManagerState | undefined;
|
|
51
|
+
/** Injectable clock for tests. */
|
|
52
|
+
now?: () => UnixMillis;
|
|
53
|
+
/** Injectable thread id factory for tests. */
|
|
54
|
+
threadIdFactory?: () => ThreadId;
|
|
55
|
+
}
|
|
56
|
+
export type RemittanceEvent = {
|
|
57
|
+
type: 'threadCreated';
|
|
58
|
+
threadId: ThreadId;
|
|
59
|
+
thread: Thread;
|
|
60
|
+
} | {
|
|
61
|
+
type: 'stateChanged';
|
|
62
|
+
threadId: ThreadId;
|
|
63
|
+
previous: RemittanceThreadState;
|
|
64
|
+
next: RemittanceThreadState;
|
|
65
|
+
reason?: string;
|
|
66
|
+
} | {
|
|
67
|
+
type: 'envelopeSent';
|
|
68
|
+
threadId: ThreadId;
|
|
69
|
+
envelope: RemittanceEnvelope;
|
|
70
|
+
transportMessageId: string;
|
|
71
|
+
} | {
|
|
72
|
+
type: 'envelopeReceived';
|
|
73
|
+
threadId: ThreadId;
|
|
74
|
+
envelope: RemittanceEnvelope;
|
|
75
|
+
transportMessageId: string;
|
|
76
|
+
} | {
|
|
77
|
+
type: 'identityRequested';
|
|
78
|
+
threadId: ThreadId;
|
|
79
|
+
direction: 'in' | 'out';
|
|
80
|
+
request: IdentityVerificationRequest;
|
|
81
|
+
} | {
|
|
82
|
+
type: 'identityResponded';
|
|
83
|
+
threadId: ThreadId;
|
|
84
|
+
direction: 'in' | 'out';
|
|
85
|
+
response: IdentityVerificationResponse;
|
|
86
|
+
} | {
|
|
87
|
+
type: 'identityAcknowledged';
|
|
88
|
+
threadId: ThreadId;
|
|
89
|
+
direction: 'in' | 'out';
|
|
90
|
+
acknowledgment: IdentityVerificationAcknowledgment;
|
|
91
|
+
} | {
|
|
92
|
+
type: 'invoiceSent';
|
|
93
|
+
threadId: ThreadId;
|
|
94
|
+
invoice: Invoice;
|
|
95
|
+
} | {
|
|
96
|
+
type: 'invoiceReceived';
|
|
97
|
+
threadId: ThreadId;
|
|
98
|
+
invoice: Invoice;
|
|
99
|
+
} | {
|
|
100
|
+
type: 'settlementSent';
|
|
101
|
+
threadId: ThreadId;
|
|
102
|
+
settlement: Settlement;
|
|
103
|
+
} | {
|
|
104
|
+
type: 'settlementReceived';
|
|
105
|
+
threadId: ThreadId;
|
|
106
|
+
settlement: Settlement;
|
|
107
|
+
} | {
|
|
108
|
+
type: 'receiptSent';
|
|
109
|
+
threadId: ThreadId;
|
|
110
|
+
receipt: Receipt;
|
|
111
|
+
} | {
|
|
112
|
+
type: 'receiptReceived';
|
|
113
|
+
threadId: ThreadId;
|
|
114
|
+
receipt: Receipt;
|
|
115
|
+
} | {
|
|
116
|
+
type: 'terminationSent';
|
|
117
|
+
threadId: ThreadId;
|
|
118
|
+
termination: Termination;
|
|
119
|
+
} | {
|
|
120
|
+
type: 'terminationReceived';
|
|
121
|
+
threadId: ThreadId;
|
|
122
|
+
termination: Termination;
|
|
123
|
+
} | {
|
|
124
|
+
type: 'error';
|
|
125
|
+
threadId: ThreadId;
|
|
126
|
+
error: string;
|
|
127
|
+
};
|
|
128
|
+
export interface RemittanceEventHandlers {
|
|
129
|
+
onThreadCreated?: (event: Extract<RemittanceEvent, {
|
|
130
|
+
type: 'threadCreated';
|
|
131
|
+
}>) => void;
|
|
132
|
+
onStateChanged?: (event: Extract<RemittanceEvent, {
|
|
133
|
+
type: 'stateChanged';
|
|
134
|
+
}>) => void;
|
|
135
|
+
onEnvelopeSent?: (event: Extract<RemittanceEvent, {
|
|
136
|
+
type: 'envelopeSent';
|
|
137
|
+
}>) => void;
|
|
138
|
+
onEnvelopeReceived?: (event: Extract<RemittanceEvent, {
|
|
139
|
+
type: 'envelopeReceived';
|
|
140
|
+
}>) => void;
|
|
141
|
+
onIdentityRequested?: (event: Extract<RemittanceEvent, {
|
|
142
|
+
type: 'identityRequested';
|
|
143
|
+
}>) => void;
|
|
144
|
+
onIdentityResponded?: (event: Extract<RemittanceEvent, {
|
|
145
|
+
type: 'identityResponded';
|
|
146
|
+
}>) => void;
|
|
147
|
+
onIdentityAcknowledged?: (event: Extract<RemittanceEvent, {
|
|
148
|
+
type: 'identityAcknowledged';
|
|
149
|
+
}>) => void;
|
|
150
|
+
onInvoiceSent?: (event: Extract<RemittanceEvent, {
|
|
151
|
+
type: 'invoiceSent';
|
|
152
|
+
}>) => void;
|
|
153
|
+
onInvoiceReceived?: (event: Extract<RemittanceEvent, {
|
|
154
|
+
type: 'invoiceReceived';
|
|
155
|
+
}>) => void;
|
|
156
|
+
onSettlementSent?: (event: Extract<RemittanceEvent, {
|
|
157
|
+
type: 'settlementSent';
|
|
158
|
+
}>) => void;
|
|
159
|
+
onSettlementReceived?: (event: Extract<RemittanceEvent, {
|
|
160
|
+
type: 'settlementReceived';
|
|
161
|
+
}>) => void;
|
|
162
|
+
onReceiptSent?: (event: Extract<RemittanceEvent, {
|
|
163
|
+
type: 'receiptSent';
|
|
164
|
+
}>) => void;
|
|
165
|
+
onReceiptReceived?: (event: Extract<RemittanceEvent, {
|
|
166
|
+
type: 'receiptReceived';
|
|
167
|
+
}>) => void;
|
|
168
|
+
onTerminationSent?: (event: Extract<RemittanceEvent, {
|
|
169
|
+
type: 'terminationSent';
|
|
170
|
+
}>) => void;
|
|
171
|
+
onTerminationReceived?: (event: Extract<RemittanceEvent, {
|
|
172
|
+
type: 'terminationReceived';
|
|
173
|
+
}>) => void;
|
|
174
|
+
onError?: (event: Extract<RemittanceEvent, {
|
|
175
|
+
type: 'error';
|
|
176
|
+
}>) => void;
|
|
177
|
+
}
|
|
178
|
+
export interface Thread {
|
|
179
|
+
threadId: ThreadId;
|
|
180
|
+
counterparty: PubKeyHex;
|
|
181
|
+
myRole: 'maker' | 'taker';
|
|
182
|
+
theirRole: 'maker' | 'taker';
|
|
183
|
+
createdAt: UnixMillis;
|
|
184
|
+
updatedAt: UnixMillis;
|
|
185
|
+
state: RemittanceThreadState;
|
|
186
|
+
/** State transition log for audit purposes. */
|
|
187
|
+
stateLog: Array<{
|
|
188
|
+
at: UnixMillis;
|
|
189
|
+
from: RemittanceThreadState;
|
|
190
|
+
to: RemittanceThreadState;
|
|
191
|
+
reason?: string;
|
|
192
|
+
}>;
|
|
193
|
+
/** Transport messageIds processed for this thread (dedupe across retries). */
|
|
194
|
+
processedMessageIds: string[];
|
|
195
|
+
/** Protocol envelopes received/sent (for debugging/audit). */
|
|
196
|
+
protocolLog: Array<{
|
|
197
|
+
direction: 'in' | 'out';
|
|
198
|
+
envelope: RemittanceEnvelope;
|
|
199
|
+
transportMessageId: string;
|
|
200
|
+
}>;
|
|
201
|
+
identity: {
|
|
202
|
+
certsSent: IdentityVerificationResponse['certificates'];
|
|
203
|
+
certsReceived: IdentityVerificationResponse['certificates'];
|
|
204
|
+
requestSent: boolean;
|
|
205
|
+
responseSent: boolean;
|
|
206
|
+
acknowledgmentSent: boolean;
|
|
207
|
+
acknowledgmentReceived: boolean;
|
|
208
|
+
};
|
|
209
|
+
invoice?: Invoice;
|
|
210
|
+
settlement?: Settlement;
|
|
211
|
+
receipt?: Receipt;
|
|
212
|
+
termination?: Termination;
|
|
213
|
+
flags: {
|
|
214
|
+
hasIdentified: boolean;
|
|
215
|
+
hasInvoiced: boolean;
|
|
216
|
+
hasPaid: boolean;
|
|
217
|
+
hasReceipted: boolean;
|
|
218
|
+
error: boolean;
|
|
219
|
+
};
|
|
220
|
+
lastError?: {
|
|
221
|
+
message: string;
|
|
222
|
+
at: UnixMillis;
|
|
223
|
+
};
|
|
224
|
+
}
|
|
225
|
+
export interface RemittanceManagerState {
|
|
226
|
+
v: 1;
|
|
227
|
+
threads: Thread[];
|
|
228
|
+
defaultPaymentOptionId?: string;
|
|
229
|
+
}
|
|
230
|
+
export interface ComposeInvoiceInput {
|
|
231
|
+
/** Human note/memo. */
|
|
232
|
+
note?: string;
|
|
233
|
+
/** Line items. */
|
|
234
|
+
lineItems: Invoice['lineItems'];
|
|
235
|
+
/** Total amount. */
|
|
236
|
+
total: Invoice['total'];
|
|
237
|
+
invoiceNumber?: string;
|
|
238
|
+
arbitrary?: Record<string, unknown>;
|
|
239
|
+
}
|
|
240
|
+
/**
|
|
241
|
+
* RemittanceManager.
|
|
242
|
+
*
|
|
243
|
+
* Responsibilities:
|
|
244
|
+
* - message transport via CommsLayer
|
|
245
|
+
* - thread lifecycle and persistence (via stateSaver/stateLoader)
|
|
246
|
+
* - invoice creation and transmission (when invoices are used)
|
|
247
|
+
* - settlement and settlement routing to the appropriate module
|
|
248
|
+
* - receipt issuance and receipt routing to the appropriate module
|
|
249
|
+
* - identity and identity certificate exchange (when identity layer is used)
|
|
250
|
+
*
|
|
251
|
+
* Non-responsibilities (left to modules):
|
|
252
|
+
* - transaction structure (whether UTXO “offer” formats, token logic, BRC-98/99 specifics, etc.)
|
|
253
|
+
* - validation rules for settlement (e.g. partial tx templates, UTXO validity, etc.)
|
|
254
|
+
* - on-chain broadcasting strategy or non-chain settlement specifics (like legacy payment protocols)
|
|
255
|
+
* - Providing option terms for invoices
|
|
256
|
+
* - Building settlement artifacts
|
|
257
|
+
* - Accepting/rejecting settlements
|
|
258
|
+
* - Deciding which identity certificates to request
|
|
259
|
+
* - Deciding about sufficiency of identity certificates
|
|
260
|
+
* - Preparing/processing specific receipt formats
|
|
261
|
+
* - Internal business logic like order fulfillment, refunds, etc.
|
|
262
|
+
*/
|
|
263
|
+
export declare class RemittanceManager {
|
|
264
|
+
readonly wallet: WalletInterface;
|
|
265
|
+
readonly comms: CommsLayer;
|
|
266
|
+
readonly cfg: RemittanceManagerConfig;
|
|
267
|
+
private readonly messageBox;
|
|
268
|
+
private readonly now;
|
|
269
|
+
private readonly threadIdFactory;
|
|
270
|
+
private readonly moduleRegistry;
|
|
271
|
+
private readonly runtime;
|
|
272
|
+
private readonly eventListeners;
|
|
273
|
+
private readonly stateWaiters;
|
|
274
|
+
private readonly eventHandlers?;
|
|
275
|
+
/** Default option id used when paying an invoice, if not overridden per-call. */
|
|
276
|
+
private defaultPaymentOptionId?;
|
|
277
|
+
/** Mutable threads list (persisted via stateSaver). */
|
|
278
|
+
threads: Thread[];
|
|
279
|
+
/** Cached identity key if wallet provides it. */
|
|
280
|
+
private myIdentityKey?;
|
|
281
|
+
constructor(cfg: RemittanceManagerConfig, wallet: WalletInterface, commsLayer: CommsLayer, threads?: Thread[]);
|
|
282
|
+
/**
|
|
283
|
+
* Loads persisted state from cfg.stateLoader (if provided).
|
|
284
|
+
*
|
|
285
|
+
* Safe to call multiple times.
|
|
286
|
+
*/
|
|
287
|
+
init(): Promise<void>;
|
|
288
|
+
/**
|
|
289
|
+
* Registers a remittance event listener.
|
|
290
|
+
*/
|
|
291
|
+
onEvent(listener: (event: RemittanceEvent) => void): () => void;
|
|
292
|
+
/**
|
|
293
|
+
* Sets a default payment option (module id) to use when paying invoices.
|
|
294
|
+
*/
|
|
295
|
+
preselectPaymentOption(optionId: string): void;
|
|
296
|
+
/**
|
|
297
|
+
* Returns an immutable snapshot of current manager state suitable for persistence.
|
|
298
|
+
*/
|
|
299
|
+
saveState(): RemittanceManagerState;
|
|
300
|
+
/**
|
|
301
|
+
* Loads state from an object previously produced by saveState().
|
|
302
|
+
*/
|
|
303
|
+
loadState(state: RemittanceManagerState): void;
|
|
304
|
+
/**
|
|
305
|
+
* Persists current state via cfg.stateSaver (if provided).
|
|
306
|
+
*/
|
|
307
|
+
persistState(): Promise<void>;
|
|
308
|
+
/**
|
|
309
|
+
* Syncs threads by fetching pending messages from the comms layer and processing them.
|
|
310
|
+
*
|
|
311
|
+
* Processing is idempotent using transport messageIds tracked per thread.
|
|
312
|
+
* Messages are acknowledged after they are successfully applied to local state.
|
|
313
|
+
*/
|
|
314
|
+
syncThreads(hostOverride?: string): Promise<void>;
|
|
315
|
+
/**
|
|
316
|
+
* Starts listening for live messages (if the CommsLayer supports it).
|
|
317
|
+
*/
|
|
318
|
+
startListening(hostOverride?: string): Promise<void>;
|
|
319
|
+
/**
|
|
320
|
+
* Creates, records, and sends an invoice to a counterparty.
|
|
321
|
+
*
|
|
322
|
+
* Returns a handle you can use to wait for payment/receipt.
|
|
323
|
+
*/
|
|
324
|
+
sendInvoice(to: PubKeyHex, input: ComposeInvoiceInput, hostOverride?: string): Promise<InvoiceHandle>;
|
|
325
|
+
/**
|
|
326
|
+
* Sends an invoice for an existing thread, e.g. after an identity request was received.
|
|
327
|
+
*/
|
|
328
|
+
sendInvoiceForThread(threadId: ThreadId, input: ComposeInvoiceInput, hostOverride?: string): Promise<InvoiceHandle>;
|
|
329
|
+
/**
|
|
330
|
+
* Returns invoice handles that this manager can pay (we are the taker/payer).
|
|
331
|
+
*/
|
|
332
|
+
findInvoicesPayable(counterparty?: PubKeyHex): InvoiceHandle[];
|
|
333
|
+
/**
|
|
334
|
+
* Returns invoice handles that we issued and are waiting to receive settlement for.
|
|
335
|
+
*/
|
|
336
|
+
findReceivableInvoices(counterparty?: PubKeyHex): InvoiceHandle[];
|
|
337
|
+
/**
|
|
338
|
+
* Pays an invoice by selecting a remittance option and sending a settlement message.
|
|
339
|
+
*
|
|
340
|
+
* If receipts are enabled (receiptProvided), this method will optionally wait for a receipt.
|
|
341
|
+
*/
|
|
342
|
+
pay(threadId: ThreadId, optionId?: string, hostOverride?: string): Promise<Receipt | Termination | undefined>;
|
|
343
|
+
/**
|
|
344
|
+
* Waits for a receipt to arrive for a thread.
|
|
345
|
+
*
|
|
346
|
+
* Uses polling via syncThreads because live listeners are optional.
|
|
347
|
+
*/
|
|
348
|
+
waitForReceipt(threadId: ThreadId, opts?: {
|
|
349
|
+
timeoutMs?: number;
|
|
350
|
+
pollIntervalMs?: number;
|
|
351
|
+
}): Promise<Receipt | Termination>;
|
|
352
|
+
/**
|
|
353
|
+
* Waits for a thread to reach a specific state.
|
|
354
|
+
*/
|
|
355
|
+
waitForState(threadId: ThreadId, state: RemittanceThreadState, opts?: {
|
|
356
|
+
timeoutMs?: number;
|
|
357
|
+
pollIntervalMs?: number;
|
|
358
|
+
}): Promise<Thread>;
|
|
359
|
+
/**
|
|
360
|
+
* Waits for identity exchange to complete for a thread.
|
|
361
|
+
*/
|
|
362
|
+
waitForIdentity(threadId: ThreadId, opts?: {
|
|
363
|
+
timeoutMs?: number;
|
|
364
|
+
pollIntervalMs?: number;
|
|
365
|
+
}): Promise<Thread>;
|
|
366
|
+
/**
|
|
367
|
+
* Waits for a settlement to arrive for a thread.
|
|
368
|
+
*/
|
|
369
|
+
waitForSettlement(threadId: ThreadId, opts?: {
|
|
370
|
+
timeoutMs?: number;
|
|
371
|
+
pollIntervalMs?: number;
|
|
372
|
+
}): Promise<Settlement | Termination>;
|
|
373
|
+
/**
|
|
374
|
+
* Sends an unsolicited settlement to a counterparty.
|
|
375
|
+
*/
|
|
376
|
+
sendUnsolicitedSettlement(to: PubKeyHex, args: {
|
|
377
|
+
moduleId: RemittanceOptionId;
|
|
378
|
+
option: unknown;
|
|
379
|
+
optionId?: RemittanceOptionId;
|
|
380
|
+
note?: string;
|
|
381
|
+
}, hostOverride?: string): Promise<ThreadHandle>;
|
|
382
|
+
/**
|
|
383
|
+
* Returns a thread by id (if present).
|
|
384
|
+
*/
|
|
385
|
+
getThread(threadId: ThreadId): Thread | undefined;
|
|
386
|
+
/**
|
|
387
|
+
* Returns a thread handle by id, or throws if the thread does not exist.
|
|
388
|
+
*/
|
|
389
|
+
getThreadHandle(threadId: ThreadId): ThreadHandle;
|
|
390
|
+
/**
|
|
391
|
+
* Returns a thread by id or throws.
|
|
392
|
+
*
|
|
393
|
+
* Public so helper handles (e.g. InvoiceHandle) can call it.
|
|
394
|
+
*/
|
|
395
|
+
getThreadOrThrow(threadId: ThreadId): Thread;
|
|
396
|
+
private moduleContext;
|
|
397
|
+
private makeEnvelope;
|
|
398
|
+
private sendEnvelope;
|
|
399
|
+
private getOrCreateThreadFromInboundEnvelope;
|
|
400
|
+
private handleInboundMessage;
|
|
401
|
+
private applyInboundEnvelope;
|
|
402
|
+
private maybeSendTermination;
|
|
403
|
+
private sendTermination;
|
|
404
|
+
private shouldRequestIdentity;
|
|
405
|
+
private shouldRequireIdentityBeforeSettlement;
|
|
406
|
+
private ensureIdentityExchange;
|
|
407
|
+
private waitForIdentityAcknowledgment;
|
|
408
|
+
private safeAck;
|
|
409
|
+
private markThreadError;
|
|
410
|
+
private ensureThreadState;
|
|
411
|
+
private deriveThreadState;
|
|
412
|
+
private transitionThreadState;
|
|
413
|
+
private resolveStateWaiters;
|
|
414
|
+
private rejectStateWaiters;
|
|
415
|
+
private emitEvent;
|
|
416
|
+
private refreshMyIdentityKey;
|
|
417
|
+
private requireMyIdentityKey;
|
|
418
|
+
private composeInvoice;
|
|
419
|
+
}
|
|
420
|
+
/**
|
|
421
|
+
* A lightweight wrapper around a thread's invoice, with convenience methods.
|
|
422
|
+
*/
|
|
423
|
+
export declare class ThreadHandle {
|
|
424
|
+
protected readonly manager: RemittanceManager;
|
|
425
|
+
readonly threadId: ThreadId;
|
|
426
|
+
constructor(manager: RemittanceManager, threadId: ThreadId);
|
|
427
|
+
get thread(): Thread;
|
|
428
|
+
waitForState(state: RemittanceThreadState, opts?: {
|
|
429
|
+
timeoutMs?: number;
|
|
430
|
+
pollIntervalMs?: number;
|
|
431
|
+
}): Promise<Thread>;
|
|
432
|
+
waitForIdentity(opts?: {
|
|
433
|
+
timeoutMs?: number;
|
|
434
|
+
pollIntervalMs?: number;
|
|
435
|
+
}): Promise<Thread>;
|
|
436
|
+
waitForSettlement(opts?: {
|
|
437
|
+
timeoutMs?: number;
|
|
438
|
+
pollIntervalMs?: number;
|
|
439
|
+
}): Promise<Settlement | Termination>;
|
|
440
|
+
waitForReceipt(opts?: {
|
|
441
|
+
timeoutMs?: number;
|
|
442
|
+
pollIntervalMs?: number;
|
|
443
|
+
}): Promise<Receipt | Termination>;
|
|
444
|
+
}
|
|
445
|
+
export declare class InvoiceHandle extends ThreadHandle {
|
|
446
|
+
get invoice(): Invoice;
|
|
447
|
+
/**
|
|
448
|
+
* Pays the invoice using the selected remittance option.
|
|
449
|
+
*/
|
|
450
|
+
pay(optionId?: string): Promise<Receipt | Termination | undefined>;
|
|
451
|
+
}
|
|
452
|
+
//# sourceMappingURL=RemittanceManager.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"RemittanceManager.d.ts","sourceRoot":"","sources":["../../../../src/remittance/RemittanceManager.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,106 @@
|
|
|
1
|
+
import { PubKeyHex } from '../wallet/index.js';
|
|
2
|
+
import { Invoice, ModuleContext, RemittanceOptionId, ThreadId, Termination, Settlement } from './types.js';
|
|
3
|
+
/**
|
|
4
|
+
* A remittance module implements a specific settlement system.
|
|
5
|
+
*
|
|
6
|
+
* The RemittanceManager core uses module ids as the only “capability mechanism”:
|
|
7
|
+
* if an invoice contains an option with module id X, a payer can only satisfy it
|
|
8
|
+
* if they are configured with module X.
|
|
9
|
+
*/
|
|
10
|
+
export interface RemittanceModule<TOptionTerms = unknown, TSettlementArtifact = unknown, TReceiptData = unknown> {
|
|
11
|
+
/** Unique id used as the invoice.options key and as settlement.moduleId. */
|
|
12
|
+
id: RemittanceOptionId;
|
|
13
|
+
/** Human-readable name for UIs. */
|
|
14
|
+
name: string;
|
|
15
|
+
/**
|
|
16
|
+
* Whether this module allows unsolicited settlements (i.e. settlement without an invoice).
|
|
17
|
+
*
|
|
18
|
+
* If true, the payer can build a settlement without an invoice being provided by the payee.
|
|
19
|
+
* In this case, the option terms provided to `buildSettlement` may be used in lieu of an invoice.
|
|
20
|
+
*
|
|
21
|
+
* If false, an invoice must always be provided to `buildSettlement`.
|
|
22
|
+
*/
|
|
23
|
+
allowUnsolicitedSettlements: boolean;
|
|
24
|
+
/**
|
|
25
|
+
* Creates module-defined option terms that will be embedded into the invoice.
|
|
26
|
+
*
|
|
27
|
+
* In UTXO-ish offers, these option terms may include a partially-signed transaction template.
|
|
28
|
+
*
|
|
29
|
+
* Optional because some modules may not require any option data, or may only support unsolicited settlements.
|
|
30
|
+
*
|
|
31
|
+
* However, a module MAY still create option terms/invoices even if it can sometimes support unsolicited settlements.
|
|
32
|
+
*/
|
|
33
|
+
createOption?: (args: {
|
|
34
|
+
threadId: ThreadId;
|
|
35
|
+
invoice: Invoice;
|
|
36
|
+
}, ctx: ModuleContext) => Promise<TOptionTerms>;
|
|
37
|
+
/**
|
|
38
|
+
* Builds the settlement artifact for a chosen option.
|
|
39
|
+
*
|
|
40
|
+
* For UTXO settlement systems, this is usually a transaction (or partially-signed tx) to be broadcast.
|
|
41
|
+
*
|
|
42
|
+
* 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.
|
|
43
|
+
*
|
|
44
|
+
* For example, the option terms may include a tx template with outputs to fulfill the settlement.
|
|
45
|
+
*
|
|
46
|
+
* When `allowUnsolicitedSettlements` is false, an invoice will always be provided.
|
|
47
|
+
*
|
|
48
|
+
* Termination can be returned to abort the protocol with a reason.
|
|
49
|
+
*/
|
|
50
|
+
buildSettlement: (args: {
|
|
51
|
+
threadId: ThreadId;
|
|
52
|
+
invoice?: Invoice;
|
|
53
|
+
option: TOptionTerms;
|
|
54
|
+
note?: string;
|
|
55
|
+
}, ctx: ModuleContext) => Promise<{
|
|
56
|
+
action: 'settle';
|
|
57
|
+
artifact: TSettlementArtifact;
|
|
58
|
+
} | {
|
|
59
|
+
action: 'terminate';
|
|
60
|
+
termination: Termination;
|
|
61
|
+
}>;
|
|
62
|
+
/**
|
|
63
|
+
* Accepts a settlement artifact on the payee side.
|
|
64
|
+
*
|
|
65
|
+
* The module should validate and internalize/store whatever it needs.
|
|
66
|
+
* The manager will wrap the returned value as receipt.receiptData.
|
|
67
|
+
*
|
|
68
|
+
* 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.
|
|
69
|
+
*/
|
|
70
|
+
acceptSettlement: (args: {
|
|
71
|
+
threadId: ThreadId;
|
|
72
|
+
invoice?: Invoice;
|
|
73
|
+
settlement: TSettlementArtifact;
|
|
74
|
+
sender: PubKeyHex;
|
|
75
|
+
}, ctx: ModuleContext) => Promise<{
|
|
76
|
+
action: 'accept';
|
|
77
|
+
receiptData?: TReceiptData;
|
|
78
|
+
} | {
|
|
79
|
+
action: 'terminate';
|
|
80
|
+
termination: Termination;
|
|
81
|
+
}>;
|
|
82
|
+
/**
|
|
83
|
+
* Processes a receipt on the payer side.
|
|
84
|
+
*
|
|
85
|
+
* This is where a module can automatically internalize a refund, mark a local order fulfilled, receive goods and services, etc.
|
|
86
|
+
*/
|
|
87
|
+
processReceipt?: (args: {
|
|
88
|
+
threadId: ThreadId;
|
|
89
|
+
invoice?: Invoice;
|
|
90
|
+
receiptData: TReceiptData;
|
|
91
|
+
sender: PubKeyHex;
|
|
92
|
+
}, ctx: ModuleContext) => Promise<void>;
|
|
93
|
+
/**
|
|
94
|
+
* Processes a termination on either side.
|
|
95
|
+
*
|
|
96
|
+
* This is where a module can clean up any internal state, reverse provisional actions, take refunds, etc.
|
|
97
|
+
*/
|
|
98
|
+
processTermination?: (args: {
|
|
99
|
+
threadId: ThreadId;
|
|
100
|
+
invoice?: Invoice;
|
|
101
|
+
settlement?: Settlement;
|
|
102
|
+
termination: Termination;
|
|
103
|
+
sender: PubKeyHex;
|
|
104
|
+
}, ctx: ModuleContext) => Promise<void>;
|
|
105
|
+
}
|
|
106
|
+
//# sourceMappingURL=RemittanceModule.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"RemittanceModule.d.ts","sourceRoot":"","sources":["../../../../src/remittance/RemittanceModule.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAA;AAC9C,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,kBAAkB,EAAE,QAAQ,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAE1G;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB,CAC/B,YAAY,GAAG,OAAO,EACtB,mBAAmB,GAAG,OAAO,EAC7B,YAAY,GAAG,OAAO;IAEtB,4EAA4E;IAC5E,EAAE,EAAE,kBAAkB,CAAA;IACtB,mCAAmC;IACnC,IAAI,EAAE,MAAM,CAAA;IAEZ;;;;;;;OAOG;IACH,2BAA2B,EAAE,OAAO,CAAA;IAEpC;;;;;;;;OAQG;IACH,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE;QAAE,QAAQ,EAAE,QAAQ,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,EAAE,GAAG,EAAE,aAAa,KAAK,OAAO,CAAC,YAAY,CAAC,CAAA;IAE5G;;;;;;;;;;;;OAYG;IACH,eAAe,EAAE,CACf,IAAI,EAAE;QAAE,QAAQ,EAAE,QAAQ,CAAC;QAAC,OAAO,CAAC,EAAE,OAAO,CAAC;QAAC,MAAM,EAAE,YAAY,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,EACpF,GAAG,EAAE,aAAa,KACf,OAAO,CAAC;QAAE,MAAM,EAAE,QAAQ,CAAC;QAAC,QAAQ,EAAE,mBAAmB,CAAA;KAAE,GAAG;QAAE,MAAM,EAAE,WAAW,CAAC;QAAC,WAAW,EAAE,WAAW,CAAA;KAAE,CAAC,CAAA;IAErH;;;;;;;OAOG;IACH,gBAAgB,EAAE,CAChB,IAAI,EAAE;QAAE,QAAQ,EAAE,QAAQ,CAAC;QAAC,OAAO,CAAC,EAAE,OAAO,CAAC;QAAC,UAAU,EAAE,mBAAmB,CAAC;QAAC,MAAM,EAAE,SAAS,CAAA;KAAE,EACnG,GAAG,EAAE,aAAa,KACf,OAAO,CAAC;QAAE,MAAM,EAAE,QAAQ,CAAC;QAAC,WAAW,CAAC,EAAE,YAAY,CAAA;KAAE,GAAG;QAAE,MAAM,EAAE,WAAW,CAAC;QAAC,WAAW,EAAE,WAAW,CAAA;KAAE,CAAC,CAAA;IAElH;;;;OAIG;IACH,cAAc,CAAC,EAAE,CACf,IAAI,EAAE;QAAE,QAAQ,EAAE,QAAQ,CAAC;QAAC,OAAO,CAAC,EAAE,OAAO,CAAC;QAAC,WAAW,EAAE,YAAY,CAAC;QAAC,MAAM,EAAE,SAAS,CAAA;KAAE,EAC7F,GAAG,EAAE,aAAa,KACf,OAAO,CAAC,IAAI,CAAC,CAAA;IAElB;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,CACnB,IAAI,EAAE;QAAE,QAAQ,EAAE,QAAQ,CAAC;QAAC,OAAO,CAAC,EAAE,OAAO,CAAC;QAAC,UAAU,CAAC,EAAE,UAAU,CAAC;QAAC,WAAW,EAAE,WAAW,CAAC;QAAC,MAAM,EAAE,SAAS,CAAA;KAAE,EACrH,GAAG,EAAE,aAAa,KACf,OAAO,CAAC,IAAI,CAAC,CAAA;CACnB"}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/remittance/index.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAA;AAC/B,cAAc,oBAAoB,CAAA;AAClC,cAAc,wBAAwB,CAAA;AACtC,cAAc,uBAAuB,CAAA;AACrC,cAAc,oBAAoB,CAAA;AAClC,cAAc,YAAY,CAAA"}
|