@integraledger/terms 0.2.0 → 0.3.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 +88 -52
- package/dist/agreement.d.ts +14 -4
- package/dist/agreement.js +139 -49
- package/dist/channels.d.ts +47 -14
- package/dist/channels.js +147 -74
- package/dist/gate.d.ts +37 -16
- package/dist/gate.js +69 -45
- package/dist/pairings/batch.d.ts +2 -5
- package/dist/pairings/batch.js +1 -11
- package/dist/pairings/card.js +0 -2
- package/dist/pairings/common.d.ts +17 -4
- package/dist/pairings/common.js +35 -4
- package/dist/pairings/lnbtc-request.d.ts +1 -1
- package/dist/pairings/lnbtc-request.js +14 -5
- package/dist/pairings/mpp-charge-hedera.d.ts +13 -11
- package/dist/pairings/mpp-charge-hedera.js +16 -14
- package/dist/pairings/mpp-charge-tempo-memo.d.ts +1 -9
- package/dist/pairings/mpp-charge-tempo-memo.js +3 -7
- package/dist/pairings/mpp-charge-tempo-push.d.ts +6 -1
- package/dist/pairings/mpp-charge-tempo-push.js +4 -13
- package/dist/pairings/mpp-charge-xrpl.js +3 -3
- package/dist/pairings/mpp-rails.d.ts +1 -1
- package/dist/pairings/mpp-session-hedera.js +3 -4
- package/dist/pairings/mpp-session-xrpl.js +3 -4
- package/dist/pairings/mpp.d.ts +14 -17
- package/dist/pairings/mpp.js +35 -114
- package/dist/pairings/protocol-groups.d.ts +1 -1
- package/dist/pairings/x402-account-rails.d.ts +1 -1
- package/dist/pairings/x402-batch-settlement-solana.d.ts +2 -0
- package/dist/pairings/x402-batch-settlement-solana.js +2 -1
- package/dist/pairings/x402-exact-hedera.d.ts +4 -1
- package/dist/pairings/x402-exact-hedera.js +5 -2
- package/dist/pairings/x402-exact-near.js +23 -2
- package/dist/pairings/x402-exact-solana.d.ts +4 -4
- package/dist/pairings/x402-exact-solana.js +3 -2
- package/dist/pairings/x402-exact-sui.js +3 -1
- package/dist/pairings/x402-exact-tvm.js +10 -2
- package/dist/pairings/x402-exact-xrpl.js +2 -4
- package/dist/pairings/x402-rail.d.ts +3 -2
- package/dist/pairings/x402-rail.js +1 -1
- package/dist/transact.d.ts +3 -2
- package/dist/transact.js +9 -6
- package/dist/types.d.ts +6 -16
- package/package.json +10 -12
package/dist/agreement.js
CHANGED
|
@@ -4,13 +4,13 @@
|
|
|
4
4
|
* option, in document order, that the signer can pay with a pairing whose payment is itself a public proof of the ATR
|
|
5
5
|
* hash. Called with the payment the agent approved, it signs exactly that payment, sends it, and returns the resource's
|
|
6
6
|
* receipt once the payment is recorded. Nothing is signed when the challenge advertises another hash, and nothing is
|
|
7
|
-
* sent unless
|
|
8
|
-
* or timeout, each paid request bounded by min(`maxTimeoutSeconds`, 120) + 60 + 10 seconds and the
|
|
9
|
-
* the paid option's `maxTimeoutSeconds` + 180 seconds; no second agreement payment is signed, and
|
|
10
|
-
* it was sent carries it as `moved`. A caller's `signal` ends the exchange at its next step.
|
|
7
|
+
* sent unless the pairing reads the hash from the completed payment. Once sent, the same signed payment is sent again
|
|
8
|
+
* after each 202, 5xx or timeout, each paid request bounded by min(`maxTimeoutSeconds`, 120) + 60 + 10 seconds and the
|
|
9
|
+
* whole exchange by the paid option's `maxTimeoutSeconds` + 180 seconds; no second agreement payment is signed, and
|
|
10
|
+
* every decline after it was sent carries it as `moved`. A caller's `signal` ends the exchange at its next step.
|
|
11
11
|
*/
|
|
12
|
-
import { BINDINGS, hash, hashEquals, isHttpsLink, isOtherSchemeLink, parseJson, } from "@integraledger/lcp";
|
|
13
|
-
import { IDENTITY, isIdentity, newRef, pay, pieceOf, redirected } from "./gate.js";
|
|
12
|
+
import { BINDINGS, canonicalJson, fromBase64, hash, hashEquals, isHttpsLink, isOtherSchemeLink, parseJson, toBase64, } from "@integraledger/lcp";
|
|
13
|
+
import { hasAccount, IDENTITY, isIdentity, newRef, pay, pieceOf, redirected, trimHttpWhitespace } from "./gate.js";
|
|
14
14
|
import { isRefusal } from "./pairings/common.js";
|
|
15
15
|
const UNPAID_DEADLINE_MS = 10_000;
|
|
16
16
|
const EXCHANGE_CAP_S = 120;
|
|
@@ -34,30 +34,41 @@ const ended = () => failed("The caller's signal ended the agreement exchange bef
|
|
|
34
34
|
function isObject(v) {
|
|
35
35
|
return typeof v === "object" && v !== null && !Array.isArray(v);
|
|
36
36
|
}
|
|
37
|
-
/**
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
37
|
+
/**
|
|
38
|
+
* The JSON text `JSON.stringify` writes for the agreement payment, which the protocol package reads back: nested at
|
|
39
|
+
* most 64 levels. Undefined when it nests deeper, or `JSON.stringify` writes nothing for it or throws.
|
|
40
|
+
*/
|
|
41
|
+
function paymentText(signed) {
|
|
42
|
+
try {
|
|
43
|
+
const text = JSON.stringify(signed);
|
|
44
|
+
return text !== undefined && parseJson(text) !== undefined ? text : undefined;
|
|
45
|
+
}
|
|
46
|
+
catch {
|
|
47
|
+
return undefined;
|
|
48
|
+
}
|
|
44
49
|
}
|
|
45
|
-
/**
|
|
50
|
+
/**
|
|
51
|
+
* The JSON value a header of at most 64 KiB carries as padded standard base64 (RFC 4648 section 4) whose final
|
|
52
|
+
* character's unused bits are zero, of UTF-8 JSON text nested at most 64 levels deep whose leading byte order mark is
|
|
53
|
+
* kept as a character; undefined for anything else.
|
|
54
|
+
*/
|
|
46
55
|
function fromBase64Json(header) {
|
|
47
|
-
|
|
56
|
+
const bytes = header.length > MAX_ANSWER_BYTES ? null : fromBase64(header);
|
|
57
|
+
if (bytes === null)
|
|
48
58
|
return undefined;
|
|
49
59
|
try {
|
|
50
|
-
|
|
51
|
-
const bytes = Uint8Array.from(binary, (c) => c.charCodeAt(0));
|
|
52
|
-
return parseJson(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
|
|
60
|
+
return parseJson(new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes));
|
|
53
61
|
}
|
|
54
62
|
catch {
|
|
55
63
|
return undefined;
|
|
56
64
|
}
|
|
57
65
|
}
|
|
58
|
-
/**
|
|
66
|
+
/**
|
|
67
|
+
* `retry-after` as one to nine decimal digits of seconds, surrounding spaces, tabs, CRs and LFs aside, at least 1; 2
|
|
68
|
+
* for any other value or none.
|
|
69
|
+
*/
|
|
59
70
|
function retrySeconds(header) {
|
|
60
|
-
const v = header
|
|
71
|
+
const v = header === null ? undefined : trimHttpWhitespace(header);
|
|
61
72
|
if (v === undefined || !DECIMAL.test(v))
|
|
62
73
|
return RETRY_DEFAULT_S;
|
|
63
74
|
return Math.max(RETRY_MIN_S, Number(v));
|
|
@@ -122,7 +133,8 @@ async function get(fetch, url, signature, ms, signal) {
|
|
|
122
133
|
}
|
|
123
134
|
if (response.status !== 200)
|
|
124
135
|
return answer;
|
|
125
|
-
const
|
|
136
|
+
const length = response.headers.get("content-length");
|
|
137
|
+
const declared = length === null ? undefined : trimHttpWhitespace(length);
|
|
126
138
|
if (declared !== undefined && /^[0-9]+$/.test(declared) && Number(declared) > MAX_ANSWER_BYTES) {
|
|
127
139
|
return failed("The agreement receipt is larger than 64 KiB.");
|
|
128
140
|
}
|
|
@@ -176,11 +188,14 @@ function cancel(s) {
|
|
|
176
188
|
// A body that cannot be cancelled is left to the fetch's own abort.
|
|
177
189
|
}
|
|
178
190
|
}
|
|
179
|
-
/**
|
|
191
|
+
/**
|
|
192
|
+
* The receipt a 200 carries, read as UTF-8 JSON text whose leading byte order mark is kept as a character, when it is
|
|
193
|
+
* the agreement receipt for `h`.
|
|
194
|
+
*/
|
|
180
195
|
function receiptOf(body, h) {
|
|
181
196
|
let parsed;
|
|
182
197
|
try {
|
|
183
|
-
parsed = parseJson(new TextDecoder("utf-8", { fatal: true }).decode(body ?? new Uint8Array(0)));
|
|
198
|
+
parsed = parseJson(new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(body ?? new Uint8Array(0)));
|
|
184
199
|
}
|
|
185
200
|
catch {
|
|
186
201
|
return failed("The agreement URL answered 200 without a JSON receipt.");
|
|
@@ -205,18 +220,30 @@ const X402 = BINDINGS.filter((b) => String(b.id).startsWith("x402/") && pieceOf(
|
|
|
205
220
|
/**
|
|
206
221
|
* The option the agreement is paid with, by the main payment's rule: the options in document order, and the first one
|
|
207
222
|
* the signer can pay whose pairing's payment is itself a public proof. An option's pairing is the first x402 pairing,
|
|
208
|
-
* in the protocol package's order, whose read accepts the challenge holding only that option.
|
|
223
|
+
* in the protocol package's order, whose read accepts the challenge holding only that option. An option whose
|
|
224
|
+
* `maxTimeoutSeconds` gives no deadline (`bounds`) is not payable, whichever pairing reads it. An `accepts` that is
|
|
225
|
+
* not a list, holds more than 32 entries or holds no object serves no option, and is declined `offer-unreadable` with
|
|
226
|
+
* the code the read gives the whole challenge (`unservedCode`). With `approved`, the challenge is checked whole in the
|
|
227
|
+
* same way and for a fault of its own (`challengeFault`), declined `offer-unreadable` with that code; then `approved`
|
|
228
|
+
* must be one of `accepts` (`isOffered`), else it is declined `offer-unreadable` with `x402/option-not-in-document`;
|
|
229
|
+
* and it is the one option read and chosen.
|
|
209
230
|
*/
|
|
210
|
-
async function select(required, account, inputs) {
|
|
231
|
+
async function select(required, account, inputs, approved) {
|
|
211
232
|
const accepts = required["accepts"];
|
|
212
|
-
if (!Array.isArray(accepts) || accepts.length
|
|
213
|
-
return declined("offer-unreadable",
|
|
214
|
-
|
|
215
|
-
|
|
233
|
+
if (!Array.isArray(accepts) || accepts.length > MAX_OPTIONS || !accepts.some((option) => isObject(option))) {
|
|
234
|
+
return declined("offer-unreadable", unservedCode(required));
|
|
235
|
+
}
|
|
236
|
+
if (approved !== undefined) {
|
|
237
|
+
const fault = challengeFault(required);
|
|
238
|
+
if (fault !== undefined)
|
|
239
|
+
return declined("offer-unreadable", fault);
|
|
240
|
+
if (!isOffered(accepts, approved))
|
|
241
|
+
return declined("offer-unreadable", "x402/option-not-in-document");
|
|
242
|
+
}
|
|
216
243
|
const now = Math.floor(Date.now() / 1000);
|
|
217
244
|
let unreadable;
|
|
218
245
|
let unpayable;
|
|
219
|
-
for (const option of accepts) {
|
|
246
|
+
for (const option of approved === undefined ? accepts : [approved]) {
|
|
220
247
|
if (!isObject(option))
|
|
221
248
|
continue;
|
|
222
249
|
const only = { ...required, accepts: [option] };
|
|
@@ -232,18 +259,59 @@ async function select(required, account, inputs) {
|
|
|
232
259
|
}
|
|
233
260
|
if (found === undefined || !isPublicProof(found.binding))
|
|
234
261
|
continue;
|
|
262
|
+
const limits = bounds(option);
|
|
263
|
+
if (limits === undefined)
|
|
264
|
+
continue;
|
|
235
265
|
const piece = pieceOf(found.binding);
|
|
236
266
|
const chosen = await piece.choose(found.read, account, inputs, now, newRef(), only);
|
|
237
267
|
if (isRefusal(chosen)) {
|
|
238
268
|
unpayable ??= chosen.code;
|
|
239
269
|
continue;
|
|
240
270
|
}
|
|
241
|
-
return { option: option, binding: found.binding, read: found.read, chosen };
|
|
271
|
+
return { option: option, binding: found.binding, read: found.read, chosen, limits };
|
|
242
272
|
}
|
|
243
273
|
if (unpayable === undefined && unreadable !== undefined)
|
|
244
274
|
return declined("offer-unreadable", unreadable);
|
|
245
275
|
return declined("no-payable-option", unpayable ?? "x402/no-payable-option");
|
|
246
276
|
}
|
|
277
|
+
/**
|
|
278
|
+
* The code the x402 reads give a challenge that serves no option: the first refusal, in the protocol package's order,
|
|
279
|
+
* that is not `x402/no-payable-option` (a fault of the whole challenge, such as its version or legal context, or an
|
|
280
|
+
* `accepts` that is not a list of at most 32 entries), else `x402/no-payable-option`.
|
|
281
|
+
*/
|
|
282
|
+
function unservedCode(required) {
|
|
283
|
+
for (const binding of X402) {
|
|
284
|
+
const read = binding.read(required);
|
|
285
|
+
if (isRefusal(read) && read.code !== "x402/no-payable-option")
|
|
286
|
+
return read.code;
|
|
287
|
+
}
|
|
288
|
+
return "x402/no-payable-option";
|
|
289
|
+
}
|
|
290
|
+
/**
|
|
291
|
+
* The code the x402 reads give a challenge that none of them serves for a fault of its own beside its options, such as
|
|
292
|
+
* its version, legal context or agreement URL (`unservedCode`); undefined when a read serves it, or when none refuses it
|
|
293
|
+
* with a code other than `x402/no-payable-option`.
|
|
294
|
+
*/
|
|
295
|
+
function challengeFault(required) {
|
|
296
|
+
if (X402.some((binding) => !isRefusal(binding.read(required)))) {
|
|
297
|
+
return undefined;
|
|
298
|
+
}
|
|
299
|
+
const code = unservedCode(required);
|
|
300
|
+
return code === "x402/no-payable-option" ? undefined : code;
|
|
301
|
+
}
|
|
302
|
+
/**
|
|
303
|
+
* Whether `option` is one of `accepts`, by identity or by equal RFC 8785 form (`canonicalJson`), as the protocol
|
|
304
|
+
* package's build holds a chosen option to the document's: member order is not compared, and a number is its JSON
|
|
305
|
+
* value.
|
|
306
|
+
*/
|
|
307
|
+
function isOffered(accepts, option) {
|
|
308
|
+
return accepts.some((a) => {
|
|
309
|
+
if (a === option)
|
|
310
|
+
return true;
|
|
311
|
+
const text = canonicalJson(a);
|
|
312
|
+
return typeof text === "string" && text === canonicalJson(option);
|
|
313
|
+
});
|
|
314
|
+
}
|
|
247
315
|
/**
|
|
248
316
|
* The paid request's deadline and the whole exchange's, in seconds, from the option's `maxTimeoutSeconds`: a JSON number
|
|
249
317
|
* with an integral value from 1 to 2^53 - 1.
|
|
@@ -254,18 +322,18 @@ function bounds(option) {
|
|
|
254
322
|
return undefined;
|
|
255
323
|
return { request: Math.min(t, EXCHANGE_CAP_S) + SETTLE_S + VERIFY_S, exchange: t + WINDOW_EXTRA_S };
|
|
256
324
|
}
|
|
257
|
-
/**
|
|
258
|
-
|
|
259
|
-
|
|
325
|
+
/**
|
|
326
|
+
* The option chosen from `required` for `h`, `approved` when given, with its bounds, once the challenge is found to
|
|
327
|
+
* advertise `h`.
|
|
328
|
+
*/
|
|
329
|
+
async function paying(required, h, account, inputs, approved) {
|
|
330
|
+
const selected = await select(required, account, inputs, approved);
|
|
260
331
|
if ("decline" in selected)
|
|
261
332
|
return selected;
|
|
262
|
-
const limits = bounds(selected.option);
|
|
263
|
-
if (limits === undefined)
|
|
264
|
-
return declined("offer-unreadable", "x402/option-malformed");
|
|
265
333
|
if (!hashEquals(selected.read.h, h)) {
|
|
266
334
|
return declined("hash-mismatch", "The agreement challenge advertises another ATR hash.");
|
|
267
335
|
}
|
|
268
|
-
return { selected, limits };
|
|
336
|
+
return { selected, limits: selected.limits };
|
|
269
337
|
}
|
|
270
338
|
/** Whether `v` has the form of an agreement payment: an agreement URL, an option and a payment request. */
|
|
271
339
|
function isAgreementPayment(v) {
|
|
@@ -274,24 +342,43 @@ function isAgreementPayment(v) {
|
|
|
274
342
|
/**
|
|
275
343
|
* Without `approved`: asks the agreement URL for its challenge and returns the agreement payment to approve, signing
|
|
276
344
|
* nothing, or the receipt where the agreement is already recorded. With `approved`: signs exactly that payment with
|
|
277
|
-
* `signer`, sends it to `url`, and returns the receipt once recorded
|
|
278
|
-
*
|
|
345
|
+
* `signer`, sends it to `url`, and returns the receipt once recorded; a payment whose challenge the protocol package's
|
|
346
|
+
* read refuses for a fault of its own (its version, legal context or agreement URL, or an `accepts` that is not a list
|
|
347
|
+
* of at most 32 entries holding an object) is declined as the unpaid request declines that challenge, and one whose
|
|
348
|
+
* option is not one of that challenge's `accepts`, by RFC 8785 form, is declined `offer-unreadable` with
|
|
349
|
+
* `x402/option-not-in-document`, each before any fetch or signer call.
|
|
350
|
+
* `bytes` are the ATR the gate compared, whose hash the agreement payment carries; `inputs` are the buyer's own chain
|
|
351
|
+
* values; `signal` ends the exchange. Options holding anything but `approved`, `inputs` and `signal`, a `signal` that
|
|
352
|
+
* is not an `AbortSignal`, an `approved` that is not of the agreement payment's form, `inputs` that is not an object,
|
|
353
|
+
* or a signer whose `account` is not a string, is declined `no-payable-option` with `x402/input-malformed` before any
|
|
354
|
+
* fetch or signer call. A `url` that is not an https URL is declined `link-not-https` with `x402/link-not-https` for an
|
|
355
|
+
* absolute URL of another scheme and `x402/legal-context-malformed` for any other value, before any fetch.
|
|
279
356
|
*/
|
|
280
357
|
export function agree(bytes, url, signer, fetch, options) {
|
|
281
|
-
return exchange(bytes, url, signer, fetch, options
|
|
358
|
+
return exchange(bytes, url, signer, fetch, options === undefined ? {} : options, undefined);
|
|
359
|
+
}
|
|
360
|
+
const OPTION_KEYS = ["approved", "inputs", "signal"];
|
|
361
|
+
/** Whether `agree`'s options are an object holding only `approved`, `inputs` and `signal`, the signal an `AbortSignal`. */
|
|
362
|
+
function optionsOk(options) {
|
|
363
|
+
if (!isObject(options) || !Object.keys(options).every((k) => OPTION_KEYS.includes(k)))
|
|
364
|
+
return false;
|
|
365
|
+
const signal = options["signal"];
|
|
366
|
+
return signal === undefined || signal instanceof AbortSignal;
|
|
282
367
|
}
|
|
283
368
|
/**
|
|
284
|
-
* `agree`, where `ns` is the namespace of the pairing whose offer named the URL: a refused URL
|
|
285
|
-
* the protocol package's code
|
|
369
|
+
* `agree`, where `ns` is the namespace of the pairing whose offer named the URL, x402 when none did: a refused URL
|
|
370
|
+
* declines `link-not-https`, its detail the protocol package's code in that namespace, `link-not-https` for an absolute
|
|
371
|
+
* URL of another scheme and `legal-context-malformed` for any other value.
|
|
286
372
|
*/
|
|
287
373
|
export async function exchange(bytes, url, signer, fetch, options, ns) {
|
|
288
374
|
if (!isHttpsLink(url)) {
|
|
289
375
|
const fault = isOtherSchemeLink(url) ? "link-not-https" : "legal-context-malformed";
|
|
290
|
-
return declined("link-not-https", ns
|
|
376
|
+
return declined("link-not-https", `${ns ?? "x402"}/${fault}`);
|
|
291
377
|
}
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
378
|
+
if (!optionsOk(options))
|
|
379
|
+
return declined("no-payable-option", `${ns ?? "x402"}/input-malformed`);
|
|
380
|
+
const { approved, signal, inputs = {} } = options;
|
|
381
|
+
if ((approved !== undefined && !isAgreementPayment(approved)) || !isObject(inputs) || !hasAccount(signer)) {
|
|
295
382
|
return declined("no-payable-option", `${ns ?? "x402"}/input-malformed`);
|
|
296
383
|
}
|
|
297
384
|
if (isEnded(signal))
|
|
@@ -301,7 +388,7 @@ export async function exchange(bytes, url, signer, fetch, options, ns) {
|
|
|
301
388
|
return offer(bytes, h, url, signer, fetch, inputs, signal);
|
|
302
389
|
if (approved.url !== url)
|
|
303
390
|
return failed("The approved agreement payment names another agreement URL.");
|
|
304
|
-
const found = await paying(
|
|
391
|
+
const found = await paying(approved.required, h, signer.account, inputs, approved.option);
|
|
305
392
|
if ("decline" in found)
|
|
306
393
|
return found;
|
|
307
394
|
const { selected, limits } = found;
|
|
@@ -313,7 +400,10 @@ export async function exchange(bytes, url, signer, fetch, options, ns) {
|
|
|
313
400
|
if (isEnded(signal))
|
|
314
401
|
return ended();
|
|
315
402
|
const signed = paid.signed;
|
|
316
|
-
const
|
|
403
|
+
const text = paymentText(signed);
|
|
404
|
+
if (text === undefined)
|
|
405
|
+
return declined("signed-not-bound", "The agreement payment is not plain JSON.");
|
|
406
|
+
const payment = toBase64(new TextEncoder().encode(text));
|
|
317
407
|
const moved = { signed, bytes, h };
|
|
318
408
|
const keep = (d) => ({ ...d, moved });
|
|
319
409
|
const pending = (detail) => keep(declined("agreement-pending", detail));
|
package/dist/channels.d.ts
CHANGED
|
@@ -1,12 +1,13 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* The buyer's channel steps. One ATR covers a whole channel: the gate compares it once, at the opening, and the caller
|
|
3
3
|
* keeps the result as a `ChannelHold`, the ATR's bytes together with the signed opening and the channel it names.
|
|
4
|
-
* `within` signs a later voucher only for a channel held this way,
|
|
5
|
-
* the
|
|
6
|
-
* MPP's sessions
|
|
7
|
-
*
|
|
4
|
+
* `within` signs a later voucher only for a channel held this way: the ATR's bytes, its hash and the channel come from
|
|
5
|
+
* the hold, and the amount from the new challenge. On x402's batch channels that challenge must advertise the held
|
|
6
|
+
* ATR's hash. On MPP's sessions a challenge that names another channel or another hash is declined, and one with no
|
|
7
|
+
* legal context is signed under the held hash. Both are served through the binding's `buildWithin`. `recordCharge`
|
|
8
|
+
* records the server's cumulative charge, bounded by what was signed.
|
|
8
9
|
*/
|
|
9
|
-
import { type AtrHash, type Json } from "@integraledger/lcp";
|
|
10
|
+
import { type AtrHash, type Json } from "@integraledger/lcp/core";
|
|
10
11
|
import { type Binding, type Declined, type Inputs, type Presented, type Signer } from "./types.js";
|
|
11
12
|
/** A channel the buyer opened for an ATR it compared, as JSON the caller keeps and hands back. */
|
|
12
13
|
export interface ChannelHold {
|
|
@@ -14,10 +15,20 @@ export interface ChannelHold {
|
|
|
14
15
|
network: string;
|
|
15
16
|
channel: string;
|
|
16
17
|
h: AtrHash;
|
|
17
|
-
/**
|
|
18
|
+
/** Padded standard base64 of the ATR bytes the opening compared, in its canonical form (RFC 4648 sections 3.5, 4). */
|
|
18
19
|
atr: string;
|
|
19
|
-
/**
|
|
20
|
+
/**
|
|
21
|
+
* The signed opening payment as the gate returned it, written as plain JSON: its own members, as signed. A member of
|
|
22
|
+
* its own, `landed` or any other, is never read as the read made for the opening.
|
|
23
|
+
*/
|
|
20
24
|
opening: Json;
|
|
25
|
+
/**
|
|
26
|
+
* The read made for the opening, as a JSON object: the `landed` receipt `openChannel` took, else the read the opening
|
|
27
|
+
* held under its own `FETCHED` member (`@integraledger/lcp`'s symbol, which no wire form carries), each bigint as its
|
|
28
|
+
* decimal string. Absent when there is neither. `within` holds it under the opening's own `FETCHED` member, as
|
|
29
|
+
* `bound` reads it.
|
|
30
|
+
*/
|
|
31
|
+
landed?: Json;
|
|
21
32
|
/** The server's cumulative charge last recorded, decimal; "0" at the opening. */
|
|
22
33
|
charged: string;
|
|
23
34
|
/** The largest `maxClaimableAmount` signed in this channel, decimal. */
|
|
@@ -25,20 +36,42 @@ export interface ChannelHold {
|
|
|
25
36
|
}
|
|
26
37
|
/**
|
|
27
38
|
* Takes a channel pairing's signed opening and the ATR bytes the gate compared for it, with the landed receipt
|
|
28
|
-
* `transact` returned beside the opening, where it returned one. The
|
|
29
|
-
*
|
|
39
|
+
* `transact` returned beside the opening, where it returned one. The caller passes as `landed` only the receipt its own
|
|
40
|
+
* reader read for the opening, as `transact` returned it, never a value another party sent. The opening, with that
|
|
41
|
+
* receipt held under its own `FETCHED` member, must be of kind `open`, the pairing must read the hash of these bytes
|
|
42
|
+
* from it, and it must name its channel; the hold keeps all three together. Without `landed`, an opening that holds its
|
|
43
|
+
* read under its own `FETCHED` member, as `@integraledger/lcp`'s `fetchPresented` returns it, is read with that read,
|
|
44
|
+
* and the hold keeps it. The hold keeps the opening as signed, and the read as its own `landed` member; a member of the
|
|
45
|
+
* opening's own, `landed` or any other, is never read as the read.
|
|
30
46
|
*/
|
|
31
47
|
export declare function openChannel(bytes: Uint8Array, opened: Presented, binding: Binding, landed?: unknown): Promise<ChannelHold | Declined>;
|
|
32
48
|
/**
|
|
33
49
|
* Signs one later voucher, or a refund, in a held channel. The ATR bytes, the opening's hash and the opening's
|
|
34
|
-
* channel are re-derived from the hold
|
|
35
|
-
*
|
|
36
|
-
*
|
|
37
|
-
*
|
|
38
|
-
*
|
|
50
|
+
* channel are re-derived from the hold. An x402 challenge must advertise the held hash. An MPP session's challenge
|
|
51
|
+
* that names another channel or another hash is declined, and one with no legal context is signed under the held
|
|
52
|
+
* hash. A voucher's `maxClaimableAmount` is the recorded charge plus the option's amount; a refund's is the recorded
|
|
53
|
+
* charge. `inputs` are the buyer's own chain values a refund's build takes; `inputs` that is not an object is declined
|
|
54
|
+
* `no-payable-option` with `<namespace>/input-malformed`.
|
|
55
|
+
*
|
|
56
|
+
* A Solana refund is the voucher alone. Taken again after the receiver's binding is unavailable, it also carries the
|
|
57
|
+
* payer-signed `request_close`, built with the `recentBlockhash`, `computeUnitLimit` and `computeUnitPrice` of
|
|
58
|
+
* `inputs`: when the `errorReason` of `refund.paymentResponse`, the settle failure's decoded `PAYMENT-RESPONSE`, read
|
|
59
|
+
* first, or else the challenge's `error`, is `invalid_batch_settlement_svm_receiver_binding_unavailable`. A Solana
|
|
60
|
+
* refund value given in another form, or a `paymentResponse` that is not an object or whose `errorReason` is not a
|
|
61
|
+
* string, is declined `no-payable-option` with `x402/input-malformed`, and the refund taken again without a
|
|
62
|
+
* `recentBlockhash` with `x402/input-missing`. No other pairing's refund reads these values or this code.
|
|
63
|
+
*
|
|
64
|
+
* On x402's batch channels, the channel the built payment would name must be the held one before the signer is called.
|
|
65
|
+
* On MPP's sessions, a channel the challenge names must be the held one and a legal context, where present, must name
|
|
66
|
+
* the held hash, before the signer is called, and the voucher is built from the held opening. In both, the signed
|
|
67
|
+
* payment must then be of the expected kind, commit to the held hash where the pairing's voucher carries one, and
|
|
68
|
+
* name the held channel, or it is dropped.
|
|
39
69
|
*/
|
|
40
70
|
export declare function within(doc: unknown, hold: ChannelHold, binding: Binding, signer: Signer, refund?: {
|
|
41
71
|
amount?: string;
|
|
72
|
+
paymentResponse?: {
|
|
73
|
+
errorReason?: string;
|
|
74
|
+
};
|
|
42
75
|
}, inputs?: Inputs): Promise<{
|
|
43
76
|
signed: Presented;
|
|
44
77
|
hold: ChannelHold;
|