@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.
Files changed (44) hide show
  1. package/README.md +88 -52
  2. package/dist/agreement.d.ts +14 -4
  3. package/dist/agreement.js +139 -49
  4. package/dist/channels.d.ts +47 -14
  5. package/dist/channels.js +147 -74
  6. package/dist/gate.d.ts +37 -16
  7. package/dist/gate.js +69 -45
  8. package/dist/pairings/batch.d.ts +2 -5
  9. package/dist/pairings/batch.js +1 -11
  10. package/dist/pairings/card.js +0 -2
  11. package/dist/pairings/common.d.ts +17 -4
  12. package/dist/pairings/common.js +35 -4
  13. package/dist/pairings/lnbtc-request.d.ts +1 -1
  14. package/dist/pairings/lnbtc-request.js +14 -5
  15. package/dist/pairings/mpp-charge-hedera.d.ts +13 -11
  16. package/dist/pairings/mpp-charge-hedera.js +16 -14
  17. package/dist/pairings/mpp-charge-tempo-memo.d.ts +1 -9
  18. package/dist/pairings/mpp-charge-tempo-memo.js +3 -7
  19. package/dist/pairings/mpp-charge-tempo-push.d.ts +6 -1
  20. package/dist/pairings/mpp-charge-tempo-push.js +4 -13
  21. package/dist/pairings/mpp-charge-xrpl.js +3 -3
  22. package/dist/pairings/mpp-rails.d.ts +1 -1
  23. package/dist/pairings/mpp-session-hedera.js +3 -4
  24. package/dist/pairings/mpp-session-xrpl.js +3 -4
  25. package/dist/pairings/mpp.d.ts +14 -17
  26. package/dist/pairings/mpp.js +35 -114
  27. package/dist/pairings/protocol-groups.d.ts +1 -1
  28. package/dist/pairings/x402-account-rails.d.ts +1 -1
  29. package/dist/pairings/x402-batch-settlement-solana.d.ts +2 -0
  30. package/dist/pairings/x402-batch-settlement-solana.js +2 -1
  31. package/dist/pairings/x402-exact-hedera.d.ts +4 -1
  32. package/dist/pairings/x402-exact-hedera.js +5 -2
  33. package/dist/pairings/x402-exact-near.js +23 -2
  34. package/dist/pairings/x402-exact-solana.d.ts +4 -4
  35. package/dist/pairings/x402-exact-solana.js +3 -2
  36. package/dist/pairings/x402-exact-sui.js +3 -1
  37. package/dist/pairings/x402-exact-tvm.js +10 -2
  38. package/dist/pairings/x402-exact-xrpl.js +2 -4
  39. package/dist/pairings/x402-rail.d.ts +3 -2
  40. package/dist/pairings/x402-rail.js +1 -1
  41. package/dist/transact.d.ts +3 -2
  42. package/dist/transact.js +9 -6
  43. package/dist/types.d.ts +6 -16
  44. 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 what was signed carries the hash. Once sent, the same signed payment is sent again after each 202, 5xx
8
- * or timeout, each paid request bounded by min(`maxTimeoutSeconds`, 120) + 60 + 10 seconds and the whole exchange by
9
- * the paid option's `maxTimeoutSeconds` + 180 seconds; no second agreement payment is signed, and every decline after
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
- /** Standard base64 of the UTF-8 bytes of `text`. */
38
- function toBase64(text) {
39
- const bytes = new TextEncoder().encode(text);
40
- let binary = "";
41
- for (const b of bytes)
42
- binary += String.fromCharCode(b);
43
- return btoa(binary);
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
- /** The JSON value a base64 header carries, or undefined when it is not base64 of UTF-8 JSON. */
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
- if (header.length > MAX_ANSWER_BYTES)
56
+ const bytes = header.length > MAX_ANSWER_BYTES ? null : fromBase64(header);
57
+ if (bytes === null)
48
58
  return undefined;
49
59
  try {
50
- const binary = atob(header);
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
- /** `retry-after` in whole seconds, at least 1; 2 when absent or not a number of seconds. */
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?.trim();
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 declared = response.headers.get("content-length")?.trim();
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
- /** The receipt a 200 carries, when it is the agreement receipt for `h`. */
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 === 0)
213
- return declined("offer-unreadable", "x402/no-payable-option");
214
- if (accepts.length > MAX_OPTIONS)
215
- return declined("offer-unreadable", "x402/option-malformed");
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
- /** The option chosen from `required` for `h`, with its bounds, once the challenge is found to advertise `h`. */
258
- async function paying(required, h, account, inputs) {
259
- const selected = await select(required, account, inputs);
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. `bytes` are the ATR the gate compared, whose hash
278
- * the agreement payment carries; `inputs` are the buyer's own chain values; `signal` ends the exchange.
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 ?? {}, undefined);
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's detail carries it with
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 === undefined ? "The agreement URL is not an https URL." : `${ns}/${fault}`);
376
+ return declined("link-not-https", `${ns ?? "x402"}/${fault}`);
291
377
  }
292
- const { approved, signal } = options;
293
- const inputs = isObject(options.inputs) ? options.inputs : {};
294
- if (approved !== undefined && !isAgreementPayment(approved)) {
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({ ...approved.required, accepts: [approved.option] }, h, signer.account, inputs);
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 payment = toBase64(JSON.stringify(signed));
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));
@@ -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, re-deriving everything from the hold and never from
5
- * the new challenge, and only when that challenge advertises the held ATR's hash. It serves x402's batch channels and
6
- * MPP's sessions through the binding's `buildWithin`. `recordCharge` records the server's cumulative charge, bounded by
7
- * what was signed.
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
- /** Base64 of the ATR bytes the opening compared. */
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
- /** The signed opening payment, exactly as the gate returned it. */
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 opening, with that receipt, must be of kind `open`,
29
- * carry the hash of these bytes, and name its channel; the hold keeps all three together.
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, and the challenge must advertise the held hash. A voucher's
35
- * `maxClaimableAmount` is the recorded charge plus the option's amount; a refund's is the recorded charge. `inputs`
36
- * are the buyer's own chain values a refund's build takes. Before the signer is called, the channel the built payment
37
- * would name must be the held one. What was signed must be of the expected kind and belong to the held channel, or it
38
- * is dropped.
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;