@agirails/sdk 2.0.4 → 2.2.1
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/README.md +536 -87
- package/dist/ACTPClient.d.ts +200 -0
- package/dist/ACTPClient.d.ts.map +1 -1
- package/dist/ACTPClient.js +266 -2
- package/dist/ACTPClient.js.map +1 -1
- package/dist/abi/ACTPKernel.json +16 -0
- package/dist/adapters/AdapterRegistry.d.ts +140 -0
- package/dist/adapters/AdapterRegistry.d.ts.map +1 -0
- package/dist/adapters/AdapterRegistry.js +166 -0
- package/dist/adapters/AdapterRegistry.js.map +1 -0
- package/dist/adapters/AdapterRouter.d.ts +165 -0
- package/dist/adapters/AdapterRouter.d.ts.map +1 -0
- package/dist/adapters/AdapterRouter.js +350 -0
- package/dist/adapters/AdapterRouter.js.map +1 -0
- package/dist/adapters/BaseAdapter.d.ts +17 -0
- package/dist/adapters/BaseAdapter.d.ts.map +1 -1
- package/dist/adapters/BaseAdapter.js +21 -0
- package/dist/adapters/BaseAdapter.js.map +1 -1
- package/dist/adapters/BasicAdapter.d.ts +72 -3
- package/dist/adapters/BasicAdapter.d.ts.map +1 -1
- package/dist/adapters/BasicAdapter.js +178 -2
- package/dist/adapters/BasicAdapter.js.map +1 -1
- package/dist/adapters/IAdapter.d.ts +230 -0
- package/dist/adapters/IAdapter.d.ts.map +1 -0
- package/dist/adapters/IAdapter.js +44 -0
- package/dist/adapters/IAdapter.js.map +1 -0
- package/dist/adapters/StandardAdapter.d.ts +80 -6
- package/dist/adapters/StandardAdapter.d.ts.map +1 -1
- package/dist/adapters/StandardAdapter.js +203 -6
- package/dist/adapters/StandardAdapter.js.map +1 -1
- package/dist/adapters/X402Adapter.d.ts +208 -0
- package/dist/adapters/X402Adapter.d.ts.map +1 -0
- package/dist/adapters/X402Adapter.js +423 -0
- package/dist/adapters/X402Adapter.js.map +1 -0
- package/dist/adapters/index.d.ts +8 -0
- package/dist/adapters/index.d.ts.map +1 -1
- package/dist/adapters/index.js +19 -1
- package/dist/adapters/index.js.map +1 -1
- package/dist/cli/commands/init.d.ts +4 -0
- package/dist/cli/commands/init.d.ts.map +1 -1
- package/dist/cli/commands/init.js +146 -4
- package/dist/cli/commands/init.js.map +1 -1
- package/dist/config/networks.d.ts +9 -0
- package/dist/config/networks.d.ts.map +1 -1
- package/dist/config/networks.js +27 -12
- package/dist/config/networks.js.map +1 -1
- package/dist/erc8004/ERC8004Bridge.d.ts +155 -0
- package/dist/erc8004/ERC8004Bridge.d.ts.map +1 -0
- package/dist/erc8004/ERC8004Bridge.js +325 -0
- package/dist/erc8004/ERC8004Bridge.js.map +1 -0
- package/dist/erc8004/ReputationReporter.d.ts +223 -0
- package/dist/erc8004/ReputationReporter.d.ts.map +1 -0
- package/dist/erc8004/ReputationReporter.js +266 -0
- package/dist/erc8004/ReputationReporter.js.map +1 -0
- package/dist/erc8004/index.d.ts +36 -0
- package/dist/erc8004/index.d.ts.map +1 -0
- package/dist/erc8004/index.js +46 -0
- package/dist/erc8004/index.js.map +1 -0
- package/dist/index.d.ts +11 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +51 -2
- package/dist/index.js.map +1 -1
- package/dist/level0/provide.d.ts.map +1 -1
- package/dist/level0/provide.js +2 -1
- package/dist/level0/provide.js.map +1 -1
- package/dist/level1/Agent.d.ts.map +1 -1
- package/dist/level1/Agent.js +11 -3
- package/dist/level1/Agent.js.map +1 -1
- package/dist/protocol/ACTPKernel.d.ts +1 -1
- package/dist/protocol/ACTPKernel.d.ts.map +1 -1
- package/dist/protocol/ACTPKernel.js +23 -12
- package/dist/protocol/ACTPKernel.js.map +1 -1
- package/dist/protocol/DIDResolver.js +1 -1
- package/dist/protocol/DIDResolver.js.map +1 -1
- package/dist/protocol/EASHelper.d.ts.map +1 -1
- package/dist/protocol/EASHelper.js +2 -3
- package/dist/protocol/EASHelper.js.map +1 -1
- package/dist/protocol/MessageSigner.d.ts.map +1 -1
- package/dist/protocol/MessageSigner.js +8 -8
- package/dist/protocol/MessageSigner.js.map +1 -1
- package/dist/runtime/BlockchainRuntime.d.ts +7 -0
- package/dist/runtime/BlockchainRuntime.d.ts.map +1 -1
- package/dist/runtime/BlockchainRuntime.js +40 -22
- package/dist/runtime/BlockchainRuntime.js.map +1 -1
- package/dist/runtime/IACTPRuntime.d.ts +21 -0
- package/dist/runtime/IACTPRuntime.d.ts.map +1 -1
- package/dist/runtime/MockRuntime.d.ts +19 -0
- package/dist/runtime/MockRuntime.d.ts.map +1 -1
- package/dist/runtime/MockRuntime.js +56 -4
- package/dist/runtime/MockRuntime.js.map +1 -1
- package/dist/runtime/types/MockState.d.ts +11 -2
- package/dist/runtime/types/MockState.d.ts.map +1 -1
- package/dist/runtime/types/MockState.js.map +1 -1
- package/dist/storage/ArchiveBundleBuilder.d.ts +150 -0
- package/dist/storage/ArchiveBundleBuilder.d.ts.map +1 -0
- package/dist/storage/ArchiveBundleBuilder.js +468 -0
- package/dist/storage/ArchiveBundleBuilder.js.map +1 -0
- package/dist/storage/ArweaveClient.d.ts +271 -0
- package/dist/storage/ArweaveClient.d.ts.map +1 -0
- package/dist/storage/ArweaveClient.js +761 -0
- package/dist/storage/ArweaveClient.js.map +1 -0
- package/dist/storage/FilebaseClient.d.ts +193 -0
- package/dist/storage/FilebaseClient.d.ts.map +1 -0
- package/dist/storage/FilebaseClient.js +643 -0
- package/dist/storage/FilebaseClient.js.map +1 -0
- package/dist/storage/index.d.ts +47 -0
- package/dist/storage/index.d.ts.map +1 -0
- package/dist/storage/index.js +64 -0
- package/dist/storage/index.js.map +1 -0
- package/dist/storage/types.d.ts +291 -0
- package/dist/storage/types.d.ts.map +1 -0
- package/dist/storage/types.js +18 -0
- package/dist/storage/types.js.map +1 -0
- package/dist/types/adapter.d.ts +359 -0
- package/dist/types/adapter.d.ts.map +1 -0
- package/dist/types/adapter.js +115 -0
- package/dist/types/adapter.js.map +1 -0
- package/dist/types/erc8004.d.ts +184 -0
- package/dist/types/erc8004.d.ts.map +1 -0
- package/dist/types/erc8004.js +132 -0
- package/dist/types/erc8004.js.map +1 -0
- package/dist/types/index.d.ts +3 -0
- package/dist/types/index.d.ts.map +1 -1
- package/dist/types/index.js +3 -0
- package/dist/types/index.js.map +1 -1
- package/dist/types/state.d.ts +5 -4
- package/dist/types/state.d.ts.map +1 -1
- package/dist/types/state.js +10 -9
- package/dist/types/state.js.map +1 -1
- package/dist/types/transaction.d.ts +12 -0
- package/dist/types/transaction.d.ts.map +1 -1
- package/dist/types/x402.d.ts +162 -0
- package/dist/types/x402.d.ts.map +1 -0
- package/dist/types/x402.js +162 -0
- package/dist/types/x402.js.map +1 -0
- package/dist/utils/IPFSClient.d.ts.map +1 -1
- package/dist/utils/IPFSClient.js +5 -2
- package/dist/utils/IPFSClient.js.map +1 -1
- package/dist/utils/NonceManager.d.ts.map +1 -1
- package/dist/utils/NonceManager.js +3 -2
- package/dist/utils/NonceManager.js.map +1 -1
- package/dist/utils/UsedAttestationTracker.d.ts.map +1 -1
- package/dist/utils/UsedAttestationTracker.js +3 -3
- package/dist/utils/UsedAttestationTracker.js.map +1 -1
- package/dist/utils/circuitBreaker.d.ts +136 -0
- package/dist/utils/circuitBreaker.d.ts.map +1 -0
- package/dist/utils/circuitBreaker.js +253 -0
- package/dist/utils/circuitBreaker.js.map +1 -0
- package/dist/utils/retry.d.ts +120 -0
- package/dist/utils/retry.d.ts.map +1 -0
- package/dist/utils/retry.js +260 -0
- package/dist/utils/retry.js.map +1 -0
- package/dist/utils/validation.d.ts +100 -0
- package/dist/utils/validation.d.ts.map +1 -1
- package/dist/utils/validation.js +248 -1
- package/dist/utils/validation.js.map +1 -1
- package/package.json +16 -3
- package/src/ACTPClient.ts +318 -2
- package/src/abi/ACTPKernel.json +16 -0
- package/src/adapters/AdapterRegistry.ts +173 -0
- package/src/adapters/AdapterRouter.ts +417 -0
- package/src/adapters/BaseAdapter.ts +25 -0
- package/src/adapters/BasicAdapter.ts +210 -3
- package/src/adapters/IAdapter.ts +292 -0
- package/src/adapters/StandardAdapter.ts +246 -7
- package/src/adapters/X402Adapter.ts +653 -0
- package/src/adapters/index.ts +27 -0
- package/src/cli/commands/init.ts +166 -3
- package/src/config/networks.ts +36 -12
- package/src/erc8004/ERC8004Bridge.ts +461 -0
- package/src/erc8004/ReputationReporter.ts +472 -0
- package/src/erc8004/index.ts +61 -0
- package/src/index.ts +97 -0
- package/src/level0/provide.ts +2 -1
- package/src/level1/Agent.ts +13 -3
- package/src/protocol/ACTPKernel.ts +33 -12
- package/src/protocol/DIDResolver.ts +1 -1
- package/src/protocol/EASHelper.ts +2 -5
- package/src/protocol/MessageSigner.ts +8 -14
- package/src/runtime/BlockchainRuntime.ts +41 -45
- package/src/runtime/IACTPRuntime.ts +22 -0
- package/src/runtime/MockRuntime.ts +58 -4
- package/src/runtime/types/MockState.ts +12 -2
- package/src/storage/ArchiveBundleBuilder.ts +563 -0
- package/src/storage/ArweaveClient.ts +945 -0
- package/src/storage/FilebaseClient.ts +790 -0
- package/src/storage/index.ts +96 -0
- package/src/storage/types.ts +348 -0
- package/src/types/adapter.ts +296 -0
- package/src/types/erc8004.ts +293 -0
- package/src/types/index.ts +3 -0
- package/src/types/state.ts +10 -9
- package/src/types/transaction.ts +12 -0
- package/src/types/x402.ts +219 -0
- package/src/utils/IPFSClient.ts +5 -4
- package/src/utils/NonceManager.ts +3 -2
- package/src/utils/UsedAttestationTracker.ts +3 -5
- package/src/utils/circuitBreaker.ts +324 -0
- package/src/utils/fsSafe.ts +5 -0
- package/src/utils/retry.ts +365 -0
- package/src/utils/validation.ts +295 -1
|
@@ -25,6 +25,8 @@ const BaseAdapter_1 = require("./BaseAdapter");
|
|
|
25
25
|
*
|
|
26
26
|
* All complexity is hidden behind smart defaults.
|
|
27
27
|
*
|
|
28
|
+
* Implements IAdapter for router integration.
|
|
29
|
+
*
|
|
28
30
|
* @example
|
|
29
31
|
* ```typescript
|
|
30
32
|
* const client = await ACTPClient.create({ mode: 'mock' });
|
|
@@ -56,6 +58,18 @@ class BasicAdapter extends BaseAdapter_1.BaseAdapter {
|
|
|
56
58
|
super(requesterAddress);
|
|
57
59
|
this.runtime = runtime;
|
|
58
60
|
this.easHelper = easHelper;
|
|
61
|
+
/**
|
|
62
|
+
* Adapter metadata for router selection.
|
|
63
|
+
*/
|
|
64
|
+
this.metadata = {
|
|
65
|
+
id: 'basic',
|
|
66
|
+
name: 'Basic Adapter',
|
|
67
|
+
usesEscrow: true,
|
|
68
|
+
supportsDisputes: true,
|
|
69
|
+
requiresIdentity: false,
|
|
70
|
+
settlementMode: 'timed', // Auto-release after dispute window
|
|
71
|
+
priority: 50, // Default priority
|
|
72
|
+
};
|
|
59
73
|
}
|
|
60
74
|
/**
|
|
61
75
|
* Create a payment transaction with smart defaults.
|
|
@@ -75,19 +89,20 @@ class BasicAdapter extends BaseAdapter_1.BaseAdapter {
|
|
|
75
89
|
* - Cannot pay yourself
|
|
76
90
|
*
|
|
77
91
|
* @param params - Payment parameters
|
|
92
|
+
* @param agentId - Optional ERC-8004 agent ID (for reputation reporting)
|
|
78
93
|
* @returns User-friendly payment result
|
|
79
94
|
* @throws {ValidationError} If inputs are invalid
|
|
80
95
|
*
|
|
81
96
|
* @example
|
|
82
97
|
* ```typescript
|
|
83
|
-
* const result = await adapter.
|
|
98
|
+
* const result = await adapter.payBasic({
|
|
84
99
|
* to: '0xProvider123',
|
|
85
100
|
* amount: '100.50',
|
|
86
101
|
* deadline: '+7d', // Optional: 7 days from now
|
|
87
102
|
* });
|
|
88
103
|
* ```
|
|
89
104
|
*/
|
|
90
|
-
async
|
|
105
|
+
async payBasic(params, agentId) {
|
|
91
106
|
// Validate and parse inputs
|
|
92
107
|
const provider = this.validateAddress(params.to, 'to');
|
|
93
108
|
const amount = this.parseAmount(params.amount);
|
|
@@ -103,6 +118,14 @@ class BasicAdapter extends BaseAdapter_1.BaseAdapter {
|
|
|
103
118
|
if (deadline <= currentTime) {
|
|
104
119
|
throw new BaseAdapter_1.ValidationError('Deadline must be in the future');
|
|
105
120
|
}
|
|
121
|
+
// SECURITY: Enforce transaction amount limit on unaudited mainnet contracts
|
|
122
|
+
const maxAmount = this.runtime.maxTransactionAmount;
|
|
123
|
+
const amountInUsdc = Number(amount) / 1000000; // Convert from wei to USDC
|
|
124
|
+
if (maxAmount !== undefined && amountInUsdc > maxAmount) {
|
|
125
|
+
throw new BaseAdapter_1.ValidationError(`Transaction amount $${amountInUsdc.toFixed(2)} exceeds maximum allowed $${maxAmount}. ` +
|
|
126
|
+
`This limit exists because contracts have not been formally audited. ` +
|
|
127
|
+
`For larger amounts, please contact support@agirails.io.`);
|
|
128
|
+
}
|
|
106
129
|
// Create transaction
|
|
107
130
|
const txId = await this.runtime.createTransaction({
|
|
108
131
|
provider,
|
|
@@ -110,6 +133,7 @@ class BasicAdapter extends BaseAdapter_1.BaseAdapter {
|
|
|
110
133
|
amount: amount.toString(),
|
|
111
134
|
deadline,
|
|
112
135
|
disputeWindow,
|
|
136
|
+
agentId, // ERC-8004 agent ID for reputation reporting
|
|
113
137
|
});
|
|
114
138
|
// Link escrow (auto-transitions to COMMITTED)
|
|
115
139
|
await this.runtime.linkEscrow(txId, amount.toString());
|
|
@@ -163,6 +187,158 @@ class BasicAdapter extends BaseAdapter_1.BaseAdapter {
|
|
|
163
187
|
canDispute: tx.state === 'DELIVERED' && tx.completedAt !== null && tx.completedAt + tx.disputeWindow > now,
|
|
164
188
|
};
|
|
165
189
|
}
|
|
190
|
+
// ==========================================================================
|
|
191
|
+
// IAdapter Implementation
|
|
192
|
+
// ==========================================================================
|
|
193
|
+
/**
|
|
194
|
+
* Execute payment through this adapter.
|
|
195
|
+
*
|
|
196
|
+
* This is the IAdapter-compatible pay() method that returns UnifiedPayResult.
|
|
197
|
+
* For the legacy BasicPayResult API, use payBasic().
|
|
198
|
+
*
|
|
199
|
+
* @param params - Unified payment parameters
|
|
200
|
+
* @returns Promise resolving to unified payment result
|
|
201
|
+
*/
|
|
202
|
+
async pay(params) {
|
|
203
|
+
// Validate using IAdapter validate()
|
|
204
|
+
this.validate(params);
|
|
205
|
+
// Map to BasicPayParams
|
|
206
|
+
const basicParams = {
|
|
207
|
+
to: params.to,
|
|
208
|
+
amount: params.amount,
|
|
209
|
+
deadline: params.deadline,
|
|
210
|
+
disputeWindow: params.disputeWindow,
|
|
211
|
+
};
|
|
212
|
+
// Call existing payBasic() with optional agentId
|
|
213
|
+
const result = await this.payBasic(basicParams, params.erc8004AgentId);
|
|
214
|
+
// Map to UnifiedPayResult
|
|
215
|
+
return {
|
|
216
|
+
txId: result.txId,
|
|
217
|
+
escrowId: result.txId, // In ACTP, escrowId === txId
|
|
218
|
+
adapter: this.metadata.id,
|
|
219
|
+
state: 'COMMITTED',
|
|
220
|
+
success: true,
|
|
221
|
+
amount: result.amount,
|
|
222
|
+
releaseRequired: true, // ACTP requires explicit release()
|
|
223
|
+
provider: result.provider,
|
|
224
|
+
requester: result.requester,
|
|
225
|
+
deadline: result.deadline,
|
|
226
|
+
erc8004AgentId: params.erc8004AgentId,
|
|
227
|
+
};
|
|
228
|
+
}
|
|
229
|
+
/**
|
|
230
|
+
* Check if this adapter can handle the given parameters.
|
|
231
|
+
*
|
|
232
|
+
* BasicAdapter can handle any Ethereum address recipient.
|
|
233
|
+
*
|
|
234
|
+
* @param params - Payment parameters to check
|
|
235
|
+
* @returns True if params have a valid Ethereum address
|
|
236
|
+
*/
|
|
237
|
+
canHandle(params) {
|
|
238
|
+
// BasicAdapter handles Ethereum addresses only
|
|
239
|
+
if (typeof params.to !== 'string') {
|
|
240
|
+
return false;
|
|
241
|
+
}
|
|
242
|
+
// Check if it's an Ethereum address (0x-prefixed hex)
|
|
243
|
+
return /^0x[a-fA-F0-9]{40}$/.test(params.to);
|
|
244
|
+
}
|
|
245
|
+
/**
|
|
246
|
+
* Validate parameters before execution.
|
|
247
|
+
*
|
|
248
|
+
* @param params - Parameters to validate
|
|
249
|
+
* @throws {ValidationError} If params are invalid
|
|
250
|
+
*/
|
|
251
|
+
validate(params) {
|
|
252
|
+
// Validate address
|
|
253
|
+
this.validateAddress(params.to, 'to');
|
|
254
|
+
// Validate amount (will throw if invalid)
|
|
255
|
+
this.parseAmount(params.amount);
|
|
256
|
+
// Validate deadline if provided
|
|
257
|
+
if (params.deadline !== undefined) {
|
|
258
|
+
this.parseDeadline(params.deadline);
|
|
259
|
+
}
|
|
260
|
+
// Validate dispute window if provided
|
|
261
|
+
if (params.disputeWindow !== undefined) {
|
|
262
|
+
this.validateDisputeWindow(params.disputeWindow);
|
|
263
|
+
}
|
|
264
|
+
}
|
|
265
|
+
/**
|
|
266
|
+
* Get transaction status by ID.
|
|
267
|
+
*
|
|
268
|
+
* Returns TransactionStatus with action hints.
|
|
269
|
+
*
|
|
270
|
+
* @param txId - Transaction ID
|
|
271
|
+
* @returns Promise resolving to transaction status
|
|
272
|
+
*/
|
|
273
|
+
async getStatus(txId) {
|
|
274
|
+
const tx = await this.runtime.getTransaction(txId);
|
|
275
|
+
if (!tx) {
|
|
276
|
+
throw new Error(`Transaction ${txId} not found`);
|
|
277
|
+
}
|
|
278
|
+
const now = this.runtime.time.now();
|
|
279
|
+
const disputeWindowEnds = tx.completedAt
|
|
280
|
+
? tx.completedAt + tx.disputeWindow
|
|
281
|
+
: undefined;
|
|
282
|
+
return {
|
|
283
|
+
state: tx.state,
|
|
284
|
+
canStartWork: tx.state === 'COMMITTED',
|
|
285
|
+
canDeliver: tx.state === 'IN_PROGRESS',
|
|
286
|
+
canRelease: tx.state === 'DELIVERED' &&
|
|
287
|
+
disputeWindowEnds !== undefined &&
|
|
288
|
+
now >= disputeWindowEnds,
|
|
289
|
+
canDispute: tx.state === 'DELIVERED' &&
|
|
290
|
+
disputeWindowEnds !== undefined &&
|
|
291
|
+
now < disputeWindowEnds,
|
|
292
|
+
amount: this.formatAmount(tx.amount),
|
|
293
|
+
deadline: new Date(tx.deadline * 1000).toISOString(),
|
|
294
|
+
disputeWindowEnds: disputeWindowEnds
|
|
295
|
+
? new Date(disputeWindowEnds * 1000).toISOString()
|
|
296
|
+
: undefined,
|
|
297
|
+
provider: tx.provider,
|
|
298
|
+
requester: tx.requester,
|
|
299
|
+
};
|
|
300
|
+
}
|
|
301
|
+
/**
|
|
302
|
+
* Transition to IN_PROGRESS state (provider starts work).
|
|
303
|
+
*
|
|
304
|
+
* @param txId - Transaction ID
|
|
305
|
+
*/
|
|
306
|
+
async startWork(txId) {
|
|
307
|
+
await this.runtime.transitionState(txId, 'IN_PROGRESS');
|
|
308
|
+
}
|
|
309
|
+
/**
|
|
310
|
+
* Transition to DELIVERED state (provider completes work).
|
|
311
|
+
*
|
|
312
|
+
* When no proof is provided, fetches the transaction's actual disputeWindow
|
|
313
|
+
* and encodes it as proof. This ensures consistency with the dispute window
|
|
314
|
+
* specified at transaction creation time.
|
|
315
|
+
*
|
|
316
|
+
* @param txId - Transaction ID
|
|
317
|
+
* @param proof - Optional delivery proof (ABI-encoded dispute window).
|
|
318
|
+
* If not provided, uses transaction's disputeWindow.
|
|
319
|
+
*/
|
|
320
|
+
async deliver(txId, proof) {
|
|
321
|
+
let deliveryProof = proof;
|
|
322
|
+
if (!deliveryProof) {
|
|
323
|
+
// Fetch transaction to get its actual disputeWindow
|
|
324
|
+
const tx = await this.runtime.getTransaction(txId);
|
|
325
|
+
if (!tx) {
|
|
326
|
+
throw new Error(`Transaction ${txId} not found`);
|
|
327
|
+
}
|
|
328
|
+
// Use transaction's disputeWindow, not a default
|
|
329
|
+
deliveryProof = this.encodeDisputeWindowProof(tx.disputeWindow);
|
|
330
|
+
}
|
|
331
|
+
await this.runtime.transitionState(txId, 'DELIVERED', deliveryProof);
|
|
332
|
+
}
|
|
333
|
+
/**
|
|
334
|
+
* Release escrow funds (EXPLICIT settlement).
|
|
335
|
+
*
|
|
336
|
+
* @param escrowId - Escrow ID (usually same as txId)
|
|
337
|
+
* @param attestationUID - Optional attestation UID for verification
|
|
338
|
+
*/
|
|
339
|
+
async release(escrowId, attestationUID) {
|
|
340
|
+
await this.runtime.releaseEscrow(escrowId, attestationUID);
|
|
341
|
+
}
|
|
166
342
|
}
|
|
167
343
|
exports.BasicAdapter = BasicAdapter;
|
|
168
344
|
//# sourceMappingURL=BasicAdapter.js.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"BasicAdapter.js","sourceRoot":"","sources":["../../src/adapters/BasicAdapter.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;GAaG;;;AAEH,+CAA6D;
|
|
1
|
+
{"version":3,"file":"BasicAdapter.js","sourceRoot":"","sources":["../../src/adapters/BasicAdapter.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,230 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* IAdapter - Common interface for all payment adapters.
|
|
3
|
+
*
|
|
4
|
+
* This interface defines the contract that all payment adapters must implement,
|
|
5
|
+
* enabling the AdapterRouter to select and use any adapter interchangeably.
|
|
6
|
+
*
|
|
7
|
+
* CRITICAL ACTP COMPLIANCE:
|
|
8
|
+
* - pay() creates transaction + locks escrow -> state = COMMITTED
|
|
9
|
+
* - Caller must transition to IN_PROGRESS before work
|
|
10
|
+
* - Caller must transition to DELIVERED with proof after work
|
|
11
|
+
* - Caller must call release() to settle (NO auto-settle)
|
|
12
|
+
*
|
|
13
|
+
* @module adapters/IAdapter
|
|
14
|
+
*/
|
|
15
|
+
import { AdapterMetadata, UnifiedPayParams, UnifiedPayResult } from '../types/adapter';
|
|
16
|
+
/**
|
|
17
|
+
* Valid transaction states across all adapters.
|
|
18
|
+
*/
|
|
19
|
+
export type AdapterTransactionState = 'INITIATED' | 'COMMITTED' | 'IN_PROGRESS' | 'DELIVERED' | 'SETTLED' | 'DISPUTED' | 'CANCELLED';
|
|
20
|
+
/**
|
|
21
|
+
* Transaction status returned by getStatus().
|
|
22
|
+
*
|
|
23
|
+
* Provides a consistent view of transaction state across different
|
|
24
|
+
* adapter implementations with action hints for what can be done next.
|
|
25
|
+
*/
|
|
26
|
+
export interface TransactionStatus {
|
|
27
|
+
/** Current transaction state */
|
|
28
|
+
state: AdapterTransactionState;
|
|
29
|
+
/** Can provider start work? (COMMITTED -> IN_PROGRESS) */
|
|
30
|
+
canStartWork: boolean;
|
|
31
|
+
/** Can provider mark as delivered? (IN_PROGRESS -> DELIVERED) */
|
|
32
|
+
canDeliver: boolean;
|
|
33
|
+
/** Can escrow be released? (DELIVERED + dispute window expired) */
|
|
34
|
+
canRelease: boolean;
|
|
35
|
+
/** Can requester dispute? (DELIVERED, within dispute window) */
|
|
36
|
+
canDispute: boolean;
|
|
37
|
+
/** Transaction amount (formatted string) */
|
|
38
|
+
amount: string;
|
|
39
|
+
/** Deadline as ISO 8601 string (optional) */
|
|
40
|
+
deadline?: string;
|
|
41
|
+
/** Dispute window end as ISO 8601 string (optional) */
|
|
42
|
+
disputeWindowEnds?: string;
|
|
43
|
+
/** Provider address */
|
|
44
|
+
provider: string;
|
|
45
|
+
/** Requester address */
|
|
46
|
+
requester: string;
|
|
47
|
+
}
|
|
48
|
+
/**
|
|
49
|
+
* Common interface for all payment adapters.
|
|
50
|
+
*
|
|
51
|
+
* Implementations include:
|
|
52
|
+
* - BasicAdapter: High-level, opinionated API
|
|
53
|
+
* - StandardAdapter: Balanced control API
|
|
54
|
+
* - X402Adapter: HTTP 402 Payment Required protocol (Phase 1 Step 2)
|
|
55
|
+
* - ERC8004Adapter: Identity-based payments (Phase 1 Step 3)
|
|
56
|
+
*
|
|
57
|
+
* @example
|
|
58
|
+
* ```typescript
|
|
59
|
+
* class CustomAdapter implements IAdapter {
|
|
60
|
+
* readonly metadata: AdapterMetadata = {
|
|
61
|
+
* id: 'custom',
|
|
62
|
+
* name: 'Custom Adapter',
|
|
63
|
+
* usesEscrow: true,
|
|
64
|
+
* supportsDisputes: true,
|
|
65
|
+
* requiresIdentity: false,
|
|
66
|
+
* settlementMode: 'explicit',
|
|
67
|
+
* priority: 50,
|
|
68
|
+
* };
|
|
69
|
+
*
|
|
70
|
+
* async pay(params: UnifiedPayParams): Promise<UnifiedPayResult> {
|
|
71
|
+
* // Implementation...
|
|
72
|
+
* }
|
|
73
|
+
*
|
|
74
|
+
* canHandle(params: UnifiedPayParams): boolean {
|
|
75
|
+
* return true; // Can handle all params
|
|
76
|
+
* }
|
|
77
|
+
*
|
|
78
|
+
* validate(params: UnifiedPayParams): void {
|
|
79
|
+
* // Throw if invalid
|
|
80
|
+
* }
|
|
81
|
+
* }
|
|
82
|
+
* ```
|
|
83
|
+
*/
|
|
84
|
+
export interface IAdapter {
|
|
85
|
+
/**
|
|
86
|
+
* Adapter metadata describing capabilities.
|
|
87
|
+
*
|
|
88
|
+
* Used by AdapterRouter for selection and by developers
|
|
89
|
+
* to understand adapter behavior.
|
|
90
|
+
*/
|
|
91
|
+
readonly metadata: AdapterMetadata;
|
|
92
|
+
/**
|
|
93
|
+
* Execute payment through this adapter.
|
|
94
|
+
*
|
|
95
|
+
* IMPORTANT: Returns with state=COMMITTED, NOT settled.
|
|
96
|
+
* Caller must follow ACTP lifecycle:
|
|
97
|
+
* 1. pay() -> COMMITTED
|
|
98
|
+
* 2. startWork() -> IN_PROGRESS
|
|
99
|
+
* 3. deliver() -> DELIVERED
|
|
100
|
+
* 4. release() -> SETTLED (explicit!)
|
|
101
|
+
*
|
|
102
|
+
* @param params - Unified payment parameters
|
|
103
|
+
* @returns Promise resolving to payment result
|
|
104
|
+
* @throws {ValidationError} If params are invalid
|
|
105
|
+
*
|
|
106
|
+
* @example
|
|
107
|
+
* ```typescript
|
|
108
|
+
* const result = await adapter.pay({
|
|
109
|
+
* to: '0xProvider...',
|
|
110
|
+
* amount: '100',
|
|
111
|
+
* deadline: '+24h',
|
|
112
|
+
* });
|
|
113
|
+
* console.log(result.state); // 'COMMITTED'
|
|
114
|
+
* console.log(result.releaseRequired); // true
|
|
115
|
+
* ```
|
|
116
|
+
*/
|
|
117
|
+
pay(params: UnifiedPayParams): Promise<UnifiedPayResult>;
|
|
118
|
+
/**
|
|
119
|
+
* Check if this adapter can handle the given parameters.
|
|
120
|
+
*
|
|
121
|
+
* Used by AdapterRouter to filter adapters that are capable
|
|
122
|
+
* of processing a specific payment request.
|
|
123
|
+
*
|
|
124
|
+
* @param params - Payment parameters to check
|
|
125
|
+
* @returns True if adapter can handle these params
|
|
126
|
+
*
|
|
127
|
+
* @example
|
|
128
|
+
* ```typescript
|
|
129
|
+
* if (adapter.canHandle({ to: 'https://api.example.com', amount: '10' })) {
|
|
130
|
+
* // This adapter supports HTTP endpoints
|
|
131
|
+
* }
|
|
132
|
+
* ```
|
|
133
|
+
*/
|
|
134
|
+
canHandle(params: UnifiedPayParams): boolean;
|
|
135
|
+
/**
|
|
136
|
+
* Validate parameters before execution.
|
|
137
|
+
*
|
|
138
|
+
* Called by AdapterRouter before routing to ensure
|
|
139
|
+
* parameters are valid for this specific adapter.
|
|
140
|
+
*
|
|
141
|
+
* @param params - Parameters to validate
|
|
142
|
+
* @throws {ValidationError} If params are invalid
|
|
143
|
+
*
|
|
144
|
+
* @example
|
|
145
|
+
* ```typescript
|
|
146
|
+
* try {
|
|
147
|
+
* adapter.validate(params);
|
|
148
|
+
* } catch (error) {
|
|
149
|
+
* console.error('Invalid params:', error.message);
|
|
150
|
+
* }
|
|
151
|
+
* ```
|
|
152
|
+
*/
|
|
153
|
+
validate(params: UnifiedPayParams): void;
|
|
154
|
+
/**
|
|
155
|
+
* Get transaction status by ID.
|
|
156
|
+
*
|
|
157
|
+
* Returns current state plus action hints indicating
|
|
158
|
+
* what operations are available.
|
|
159
|
+
*
|
|
160
|
+
* @param txId - Transaction ID
|
|
161
|
+
* @returns Promise resolving to transaction status
|
|
162
|
+
* @throws {Error} If transaction not found
|
|
163
|
+
*
|
|
164
|
+
* @example
|
|
165
|
+
* ```typescript
|
|
166
|
+
* const status = await adapter.getStatus(txId);
|
|
167
|
+
* if (status.canRelease) {
|
|
168
|
+
* await adapter.release(escrowId);
|
|
169
|
+
* }
|
|
170
|
+
* ```
|
|
171
|
+
*/
|
|
172
|
+
getStatus(txId: string): Promise<TransactionStatus>;
|
|
173
|
+
/**
|
|
174
|
+
* Transition to IN_PROGRESS state (provider starts work).
|
|
175
|
+
*
|
|
176
|
+
* Must be called by provider after accepting the transaction.
|
|
177
|
+
* ACTP requires this explicit transition.
|
|
178
|
+
*
|
|
179
|
+
* @param txId - Transaction ID
|
|
180
|
+
* @throws {Error} If transaction not found or wrong state
|
|
181
|
+
*
|
|
182
|
+
* @example
|
|
183
|
+
* ```typescript
|
|
184
|
+
* // Provider acknowledges and starts work
|
|
185
|
+
* await adapter.startWork(txId);
|
|
186
|
+
* ```
|
|
187
|
+
*/
|
|
188
|
+
startWork(txId: string): Promise<void>;
|
|
189
|
+
/**
|
|
190
|
+
* Transition to DELIVERED state (provider completes work).
|
|
191
|
+
*
|
|
192
|
+
* @param txId - Transaction ID
|
|
193
|
+
* @param proof - Delivery proof (ABI-encoded dispute window)
|
|
194
|
+
* @throws {Error} If transaction not found or wrong state
|
|
195
|
+
*
|
|
196
|
+
* @example
|
|
197
|
+
* ```typescript
|
|
198
|
+
* // Provider marks work as delivered with 2-hour dispute window
|
|
199
|
+
* const proof = ethers.AbiCoder.defaultAbiCoder().encode(['uint256'], [7200]);
|
|
200
|
+
* await adapter.deliver(txId, proof);
|
|
201
|
+
* ```
|
|
202
|
+
*/
|
|
203
|
+
deliver(txId: string, proof: string): Promise<void>;
|
|
204
|
+
/**
|
|
205
|
+
* Release escrow funds (EXPLICIT settlement).
|
|
206
|
+
*
|
|
207
|
+
* MUST be called after dispute window expires or requester approves.
|
|
208
|
+
* This is the ONLY way to settle - NO auto-settle.
|
|
209
|
+
*
|
|
210
|
+
* @param escrowId - Escrow ID (usually same as txId)
|
|
211
|
+
* @param attestationUID - Optional attestation UID for verification
|
|
212
|
+
* @throws {Error} If escrow not found or dispute window active
|
|
213
|
+
*
|
|
214
|
+
* @example
|
|
215
|
+
* ```typescript
|
|
216
|
+
* // After dispute window expires
|
|
217
|
+
* await adapter.release(result.escrowId);
|
|
218
|
+
* // Transaction is now SETTLED
|
|
219
|
+
* ```
|
|
220
|
+
*/
|
|
221
|
+
release(escrowId: string, attestationUID?: string): Promise<void>;
|
|
222
|
+
}
|
|
223
|
+
/**
|
|
224
|
+
* Type guard to check if an object implements IAdapter.
|
|
225
|
+
*
|
|
226
|
+
* @param obj - Object to check
|
|
227
|
+
* @returns True if object implements IAdapter
|
|
228
|
+
*/
|
|
229
|
+
export declare function isAdapter(obj: unknown): obj is IAdapter;
|
|
230
|
+
//# sourceMappingURL=IAdapter.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"IAdapter.d.ts","sourceRoot":"","sources":["../../src/adapters/IAdapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,gBAAgB,EACjB,MAAM,kBAAkB,CAAC;AAM1B;;GAEG;AACH,MAAM,MAAM,uBAAuB,GAC/B,WAAW,GACX,WAAW,GACX,aAAa,GACb,WAAW,GACX,SAAS,GACT,UAAU,GACV,WAAW,CAAC;AAEhB;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,gCAAgC;IAChC,KAAK,EAAE,uBAAuB,CAAC;IAE/B,0DAA0D;IAC1D,YAAY,EAAE,OAAO,CAAC;IAEtB,iEAAiE;IACjE,UAAU,EAAE,OAAO,CAAC;IAEpB,mEAAmE;IACnE,UAAU,EAAE,OAAO,CAAC;IAEpB,gEAAgE;IAChE,UAAU,EAAE,OAAO,CAAC;IAEpB,4CAA4C;IAC5C,MAAM,EAAE,MAAM,CAAC;IAEf,6CAA6C;IAC7C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB,uDAAuD;IACvD,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAE3B,uBAAuB;IACvB,QAAQ,EAAE,MAAM,CAAC;IAEjB,wBAAwB;IACxB,SAAS,EAAE,MAAM,CAAC;CACnB;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,MAAM,WAAW,QAAQ;IACvB;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAC;IAEnC;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,GAAG,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAEzD;;;;;;;;;;;;;;;OAeG;IACH,SAAS,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC;IAE7C;;;;;;;;;;;;;;;;;OAiBG;IACH,QAAQ,CAAC,MAAM,EAAE,gBAAgB,GAAG,IAAI,CAAC;IAEzC;;;;;;;;;;;;;;;;;OAiBG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAEpD;;;;;;;;;;;;;;OAcG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEvC;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEpD;;;;;;;;;;;;;;;;OAgBG;IACH,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,cAAc,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACnE;AAMD;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,QAAQ,CAmBvD"}
|
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
/**
|
|
3
|
+
* IAdapter - Common interface for all payment adapters.
|
|
4
|
+
*
|
|
5
|
+
* This interface defines the contract that all payment adapters must implement,
|
|
6
|
+
* enabling the AdapterRouter to select and use any adapter interchangeably.
|
|
7
|
+
*
|
|
8
|
+
* CRITICAL ACTP COMPLIANCE:
|
|
9
|
+
* - pay() creates transaction + locks escrow -> state = COMMITTED
|
|
10
|
+
* - Caller must transition to IN_PROGRESS before work
|
|
11
|
+
* - Caller must transition to DELIVERED with proof after work
|
|
12
|
+
* - Caller must call release() to settle (NO auto-settle)
|
|
13
|
+
*
|
|
14
|
+
* @module adapters/IAdapter
|
|
15
|
+
*/
|
|
16
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
17
|
+
exports.isAdapter = void 0;
|
|
18
|
+
// ============================================================================
|
|
19
|
+
// Type Guards
|
|
20
|
+
// ============================================================================
|
|
21
|
+
/**
|
|
22
|
+
* Type guard to check if an object implements IAdapter.
|
|
23
|
+
*
|
|
24
|
+
* @param obj - Object to check
|
|
25
|
+
* @returns True if object implements IAdapter
|
|
26
|
+
*/
|
|
27
|
+
function isAdapter(obj) {
|
|
28
|
+
if (!obj || typeof obj !== 'object') {
|
|
29
|
+
return false;
|
|
30
|
+
}
|
|
31
|
+
const adapter = obj;
|
|
32
|
+
return (typeof adapter.metadata === 'object' &&
|
|
33
|
+
adapter.metadata !== null &&
|
|
34
|
+
typeof adapter.metadata.id === 'string' &&
|
|
35
|
+
typeof adapter.pay === 'function' &&
|
|
36
|
+
typeof adapter.canHandle === 'function' &&
|
|
37
|
+
typeof adapter.validate === 'function' &&
|
|
38
|
+
typeof adapter.getStatus === 'function' &&
|
|
39
|
+
typeof adapter.startWork === 'function' &&
|
|
40
|
+
typeof adapter.deliver === 'function' &&
|
|
41
|
+
typeof adapter.release === 'function');
|
|
42
|
+
}
|
|
43
|
+
exports.isAdapter = isAdapter;
|
|
44
|
+
//# sourceMappingURL=IAdapter.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"IAdapter.js","sourceRoot":"","sources":["../../src/adapters/IAdapter.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;GAaG;;;AAyPH,+EAA+E;AAC/E,cAAc;AACd,+EAA+E;AAE/E;;;;;GAKG;AACH,SAAgB,SAAS,CAAC,GAAY;IACpC,IAAI,CAAC,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;QACpC,OAAO,KAAK,CAAC;IACf,CAAC;IAED,MAAM,OAAO,GAAG,GAAwB,CAAC;IAEzC,OAAO,CACL,OAAO,OAAO,CAAC,QAAQ,KAAK,QAAQ;QACpC,OAAO,CAAC,QAAQ,KAAK,IAAI;QACzB,OAAO,OAAO,CAAC,QAAQ,CAAC,EAAE,KAAK,QAAQ;QACvC,OAAO,OAAO,CAAC,GAAG,KAAK,UAAU;QACjC,OAAO,OAAO,CAAC,SAAS,KAAK,UAAU;QACvC,OAAO,OAAO,CAAC,QAAQ,KAAK,UAAU;QACtC,OAAO,OAAO,CAAC,SAAS,KAAK,UAAU;QACvC,OAAO,OAAO,CAAC,SAAS,KAAK,UAAU;QACvC,OAAO,OAAO,CAAC,OAAO,KAAK,UAAU;QACrC,OAAO,OAAO,CAAC,OAAO,KAAK,UAAU,CACtC,CAAC;AACJ,CAAC;AAnBD,8BAmBC"}
|
|
@@ -15,6 +15,8 @@ import { BaseAdapter } from './BaseAdapter';
|
|
|
15
15
|
import { IACTPRuntime } from '../runtime/IACTPRuntime';
|
|
16
16
|
import { MockTransaction, TransactionState } from '../runtime/types/MockState';
|
|
17
17
|
import { EASHelper } from '../protocol/EASHelper';
|
|
18
|
+
import { IAdapter, TransactionStatus } from './IAdapter';
|
|
19
|
+
import { AdapterMetadata, UnifiedPayParams, UnifiedPayResult } from '../types/adapter';
|
|
18
20
|
/**
|
|
19
21
|
* Parameters for creating a transaction (standard level).
|
|
20
22
|
*
|
|
@@ -31,6 +33,8 @@ export interface StandardTransactionParams {
|
|
|
31
33
|
disputeWindow?: number;
|
|
32
34
|
/** Optional: Service description */
|
|
33
35
|
serviceDescription?: string;
|
|
36
|
+
/** Optional: ERC-8004 agent ID (for reputation reporting) */
|
|
37
|
+
agentId?: string;
|
|
34
38
|
}
|
|
35
39
|
/**
|
|
36
40
|
* StandardAdapter - Balanced API for transaction lifecycle control.
|
|
@@ -64,9 +68,13 @@ export interface StandardTransactionParams {
|
|
|
64
68
|
* await client.standard.releaseEscrow(escrowId);
|
|
65
69
|
* ```
|
|
66
70
|
*/
|
|
67
|
-
export declare class StandardAdapter extends BaseAdapter {
|
|
71
|
+
export declare class StandardAdapter extends BaseAdapter implements IAdapter {
|
|
68
72
|
private runtime;
|
|
69
73
|
private easHelper?;
|
|
74
|
+
/**
|
|
75
|
+
* Adapter metadata for router selection.
|
|
76
|
+
*/
|
|
77
|
+
readonly metadata: AdapterMetadata;
|
|
70
78
|
/**
|
|
71
79
|
* Creates a new StandardAdapter instance.
|
|
72
80
|
*
|
|
@@ -119,22 +127,27 @@ export declare class StandardAdapter extends BaseAdapter {
|
|
|
119
127
|
* Valid transitions:
|
|
120
128
|
* - INITIATED → QUOTED, COMMITTED, CANCELLED
|
|
121
129
|
* - QUOTED → COMMITTED, CANCELLED
|
|
122
|
-
* - COMMITTED → IN_PROGRESS,
|
|
130
|
+
* - COMMITTED → IN_PROGRESS, CANCELLED
|
|
123
131
|
* - IN_PROGRESS → DELIVERED, CANCELLED
|
|
124
132
|
* - DELIVERED → SETTLED, DISPUTED
|
|
125
|
-
* - DISPUTED → SETTLED
|
|
133
|
+
* - DISPUTED → SETTLED, CANCELLED (admin/pauser)
|
|
126
134
|
*
|
|
127
135
|
* @param txId - Transaction ID
|
|
128
136
|
* @param newState - Target state
|
|
137
|
+
* @param proof - Optional proof data (required for DELIVERED transition with dispute window)
|
|
129
138
|
* @throws {Error} If transition is invalid
|
|
130
139
|
*
|
|
131
140
|
* @example
|
|
132
141
|
* ```typescript
|
|
133
|
-
* // Provider
|
|
134
|
-
* await adapter.transitionState(txId, '
|
|
142
|
+
* // Provider starts work
|
|
143
|
+
* await adapter.transitionState(txId, 'IN_PROGRESS');
|
|
144
|
+
*
|
|
145
|
+
* // Provider marks work as delivered (with dispute window proof)
|
|
146
|
+
* const disputeWindowProof = ethers.AbiCoder.defaultAbiCoder().encode(['uint256'], [7200]);
|
|
147
|
+
* await adapter.transitionState(txId, 'DELIVERED', disputeWindowProof);
|
|
135
148
|
* ```
|
|
136
149
|
*/
|
|
137
|
-
transitionState(txId: string, newState: TransactionState): Promise<void>;
|
|
150
|
+
transitionState(txId: string, newState: TransactionState, proof?: string): Promise<void>;
|
|
138
151
|
/**
|
|
139
152
|
* Release escrow funds to the provider.
|
|
140
153
|
*
|
|
@@ -207,5 +220,66 @@ export declare class StandardAdapter extends BaseAdapter {
|
|
|
207
220
|
* ```
|
|
208
221
|
*/
|
|
209
222
|
getTransaction(txId: string): Promise<MockTransaction | null>;
|
|
223
|
+
/**
|
|
224
|
+
* Unified pay method for IAdapter interface.
|
|
225
|
+
*
|
|
226
|
+
* Creates transaction AND links escrow in one call.
|
|
227
|
+
*
|
|
228
|
+
* @param params - Unified payment parameters
|
|
229
|
+
* @returns Promise resolving to unified payment result
|
|
230
|
+
*/
|
|
231
|
+
pay(params: UnifiedPayParams): Promise<UnifiedPayResult>;
|
|
232
|
+
/**
|
|
233
|
+
* Check if this adapter can handle the given parameters.
|
|
234
|
+
*
|
|
235
|
+
* StandardAdapter can handle any Ethereum address recipient.
|
|
236
|
+
*
|
|
237
|
+
* @param params - Payment parameters to check
|
|
238
|
+
* @returns True if params have a valid Ethereum address
|
|
239
|
+
*/
|
|
240
|
+
canHandle(params: UnifiedPayParams): boolean;
|
|
241
|
+
/**
|
|
242
|
+
* Validate parameters before execution.
|
|
243
|
+
*
|
|
244
|
+
* @param params - Parameters to validate
|
|
245
|
+
* @throws {ValidationError} If params are invalid
|
|
246
|
+
*/
|
|
247
|
+
validate(params: UnifiedPayParams): void;
|
|
248
|
+
/**
|
|
249
|
+
* Get transaction status by ID.
|
|
250
|
+
*
|
|
251
|
+
* Returns TransactionStatus with action hints.
|
|
252
|
+
*
|
|
253
|
+
* @param txId - Transaction ID
|
|
254
|
+
* @returns Promise resolving to transaction status
|
|
255
|
+
*/
|
|
256
|
+
getStatus(txId: string): Promise<TransactionStatus>;
|
|
257
|
+
/**
|
|
258
|
+
* Transition to IN_PROGRESS state (provider starts work).
|
|
259
|
+
*
|
|
260
|
+
* @param txId - Transaction ID
|
|
261
|
+
*/
|
|
262
|
+
startWork(txId: string): Promise<void>;
|
|
263
|
+
/**
|
|
264
|
+
* Transition to DELIVERED state (provider completes work).
|
|
265
|
+
*
|
|
266
|
+
* When no proof is provided, fetches the transaction's actual disputeWindow
|
|
267
|
+
* and encodes it as proof. This ensures consistency with the dispute window
|
|
268
|
+
* specified at transaction creation time.
|
|
269
|
+
*
|
|
270
|
+
* @param txId - Transaction ID
|
|
271
|
+
* @param proof - Optional delivery proof (ABI-encoded dispute window).
|
|
272
|
+
* If not provided, uses transaction's disputeWindow.
|
|
273
|
+
*/
|
|
274
|
+
deliver(txId: string, proof?: string): Promise<void>;
|
|
275
|
+
/**
|
|
276
|
+
* Release escrow funds (EXPLICIT settlement).
|
|
277
|
+
*
|
|
278
|
+
* Wrapper around releaseEscrow() for IAdapter interface.
|
|
279
|
+
*
|
|
280
|
+
* @param escrowId - Escrow ID (usually same as txId)
|
|
281
|
+
* @param attestationUID - Optional attestation UID for verification
|
|
282
|
+
*/
|
|
283
|
+
release(escrowId: string, attestationUID?: string): Promise<void>;
|
|
210
284
|
}
|
|
211
285
|
//# sourceMappingURL=StandardAdapter.d.ts.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"StandardAdapter.d.ts","sourceRoot":"","sources":["../../src/adapters/StandardAdapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,WAAW,EAAmB,MAAM,eAAe,CAAC;AAC7D,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AACvD,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAC/E,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;
|
|
1
|
+
{"version":3,"file":"StandardAdapter.d.ts","sourceRoot":"","sources":["../../src/adapters/StandardAdapter.ts"],"names":[],"mappings":"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"}
|