@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/README.md CHANGED
@@ -4,50 +4,58 @@ The buyer gate for agents that pay: before your wallet signs anything, it confir
4
4
  hashes to the value the payment will carry, and builds the payment with that hash.
5
5
 
6
6
  ```sh
7
- npm install @integraledger/terms @integraledger/lcp
7
+ npm install @integraledger/terms@0.3.1 @integraledger/lcp@0.4.2
8
8
  ```
9
9
 
10
10
  ## What it is
11
11
 
12
12
  A seller that follows the Legal Context Protocol publishes the agreement's record, an **Agentic Transaction Record
13
- (ATR)**, at an `https` link, and advertises its hash beside the payment request. The payment your agent signs carries
14
- that hash, so paying is agreeing to that exact record.
13
+ (ATR)**, at an `https` link, and advertises its hash beside the payment request. Where the payment your agent approves
14
+ carries that hash, that approval is the buyer's acceptance of that exact record; where it does not, the pairing's
15
+ `proves` says so.
15
16
 
16
17
  That only holds if the hash in the payment is the hash of the record you can read. This package is the check that makes
17
18
  sure it is. It fetches the record, computes its SHA-256, compares it with what the seller advertised, and only on a
18
- match hands your signer a request built with that hash. After your signer answers, it reads the hash back out of what
19
- was signed and returns the payment only if it is still the hash of the bytes you received.
19
+ match hands your signer a request built with that hash. After your signer answers, the pairing reads the hash back from
20
+ the completed payment, and the payment is returned only if it is the hash of the bytes you received, or, where the proof
21
+ is the agreement payment, without that reading.
20
22
 
21
- It runs in your process, with your HTTP client and your signer. It holds no keys, moves no funds, and never reads the
22
- record's content: what the record says is for you and your principal to judge.
23
+ It runs in your process, with your HTTP client and your signer. It holds no keys and never reads the record's content:
24
+ what the record says is for you and your principal to judge. The one payment it sends is the agreement payment your
25
+ agent approved, to the agreement URL.
23
26
 
24
27
  ## Key concepts
25
28
 
26
- - **Agentic Transaction Record (ATR):** the agreement's record, a JSON document the seller serves.
29
+ - **Agentic Transaction Record (ATR):** the agreement's record: the exact bytes the seller serves; `assemble` in
30
+ `@integraledger/lcp` writes them as one JSON object.
27
31
  - **ATR hash (H):** SHA-256 over the ATR's exact bytes, `0x` and 64 hex digits. It is computed over the bytes as
28
32
  received, never over a parsed and re-serialised copy.
29
- - **Legal Context Protocol (LCP):** the pattern this package implements: the payment carries H, so paying is agreeing
30
- to that exact record.
33
+ - **Legal Context Protocol (LCP):** the pattern this package implements: where the payment the buyer approves carries
34
+ H, that approval is the buyer's acceptance of that exact record; where it does not, the pairing's `proves` says so.
31
35
  - **Pairing:** a payment protocol, scheme and rail combination, such as `x402/exact/eip155/eip3009`.
32
- - **Binding:** how H rides in a pairing's payment, the field its specification defines. For
33
- `x402/exact/eip155/eip3009` it is the EIP-3009 `nonce`. Bindings are exported by
34
- [`@integraledger/lcp`](https://github.com/IntegraLedger/integra-protocol), one per pairing.
36
+ - **Binding:** how H rides in a pairing's payment: the field of that payment, as the protocol's own specification
37
+ defines the payment, that carries H. For `x402/exact/eip155/eip3009` it is the EIP-3009 `nonce`. Bindings are exported
38
+ by [`@integraledger/lcp`](https://github.com/IntegraLedger/integra-protocol), one per pairing.
35
39
  - **Buyer gate:** this package: the buyer-side check that compares the served bytes with H before anything is signed.
36
40
  - **Seller:** the party serving the resource.
37
- - **Facilitator:** the x402 role that verifies and settles. The gate never talks to one: it returns the payment to you.
41
+ - **Facilitator:** the x402 role that verifies and settles. The gate never talks to one. It returns the payment to you,
42
+ except the approved agreement payment, which it sends to the agreement URL.
38
43
  - **Vectors:** the shared test cases that fix the rules byte for byte across languages. This package and the Python
39
- gate, [`integraledger-terms`](https://pypi.org/project/integraledger-terms/), pass the same ones.
44
+ gate, [`integraledger-terms`](https://pypi.org/project/integraledger-terms/), run the same `buyer` rows and pairing
45
+ vectors.
40
46
 
41
47
  ## Install
42
48
 
43
49
  ```sh
44
- npm install @integraledger/terms @integraledger/lcp
50
+ npm install @integraledger/terms@0.3.1 @integraledger/lcp@0.4.2
45
51
  ```
46
52
 
47
- - Node.js `>=26.10.0`. ESM only.
48
- - `@integraledger/lcp` is a dependency of this package; install it beside it to import the bindings you pass in.
49
- - Chain libraries (`@solana/kit`, `@stellar/stellar-sdk` and others) are optional peers of `@integraledger/lcp`,
50
- needed only by the pairings that use them.
53
+ - Node.js `>=26.11.1`. ESM only.
54
+ - `@integraledger/lcp` is a peer dependency of this package (`~0.4.2`): install it beside it, so your application and
55
+ the gate share one copy, and import from it the bindings you pass in.
56
+ - Chain libraries are optional peers of `@integraledger/lcp`: `@mysten/sui`, `@solana/kit`, `@stellar/stellar-sdk`,
57
+ `@ton/core`, `algosdk`, `borsh` and `ripple-binary-codec`, at the versions `@integraledger/lcp` names. Install the
58
+ ones the pairings you pay use.
51
59
 
52
60
  ## Quickstart
53
61
 
@@ -65,7 +73,7 @@ const atr = new TextEncoder().encode(
65
73
  '{"atrVersion":"1","id":"0f8fad5b-d9cb-469f-a165-70867728950e","x402":{"z":1.0,"a":"caf\\u00e9"},"seller":{"note":"Café — 30 días ✓"}}',
66
74
  );
67
75
  const H = "0x8b1e122580ae3f6a8c3d36a24294e1260a87bde70f597279b973e39310072938";
68
- const link = `https://atr.seller.example/${H}`;
76
+ const link = `https://atr.seller.example/${crypto.randomUUID()}`;
69
77
 
70
78
  // The seller's x402 payment request, advertising H and the link.
71
79
  const offer = {
@@ -109,8 +117,8 @@ console.log("H ", result.h);
109
117
  console.log("signed nonce", payment.payload.authorization.nonce);
110
118
  console.log("kept bytes ", result.bytes.length);
111
119
 
112
- // x402 over HTTP sends the payment as base64 of its JSON, in the PAYMENT-SIGNATURE header.
113
- const header = btoa(JSON.stringify(result.signed));
120
+ // x402 over HTTP sends the payment as base64 of the UTF-8 bytes of its JSON, in the PAYMENT-SIGNATURE header.
121
+ const header = Buffer.from(JSON.stringify(result.signed), "utf8").toString("base64");
114
122
  console.log("header ", header.length > 0 ? "ready" : "empty");
115
123
  ```
116
124
 
@@ -143,25 +151,29 @@ sequenceDiagram
143
151
  A->>W: sign(request)
144
152
  W-->>A: The signature
145
153
  A->>G: finish(bytes, chosen, signature)
146
- G-->>A: The payment, only when what was signed carries H
154
+ G-->>A: The payment, only when the pairing reads H from it, or the proof is the agreement payment
147
155
  ```
148
156
 
149
157
  1. **Read.** The pairing's binding reads the seller's document: H, the link, and the payment options.
150
158
  2. **Compare.** The gate fetches the link once and hashes the bytes it received. No match: a decline, and no signer
151
159
  call.
152
160
  3. **Build.** On a match, the gate builds the payment with the hash it computed, not the string the seller advertised.
153
- 4. **Finish.** The gate joins your signer's answer, reads H back out of what was signed, and returns the payment only
154
- when it is the hash of the compared bytes.
161
+ 4. **Finish.** The gate joins your signer's answer and returns the payment only when the pairing reads H back from the
162
+ completed payment as the hash of the compared bytes, or, where the proof is the agreement payment, without that
163
+ reading.
155
164
 
156
165
  Every function returns a value, never throws for a protocol outcome: either its result, or
157
166
  `{ decline: { code, detail } }`.
158
167
 
159
168
  ## Guides
160
169
 
161
- ### Pay in one call: `transact`
170
+ ### Pay with `transact`
162
171
 
163
172
  `transact(doc, binding, signer, fetch, options?)` runs the whole order: compare, pay the agreement your agent approved
164
- where the pairing needs one, sign, finish. Its result is:
173
+ where the pairing needs one, sign, finish. For most pairings that is one call. For a pairing that needs an agreement
174
+ payment, the first call returns that payment for your agent's approval, and a second call, with `approved`, pays it and
175
+ then the resource. The payment for the resource is handed to your signer directly: approving it is your agent's step
176
+ before it calls `transact`, and the gate applies no spending limit. Its result is:
165
177
 
166
178
  | Member | What it is |
167
179
  | --- | --- |
@@ -188,7 +200,14 @@ Any other member, or a member of the wrong kind, is declined before any fetch.
188
200
  ### Sign elsewhere: `confirm`, then `finish`
189
201
 
190
202
  When the key lives in a hardware wallet or a signing service, split the order. `chosen` is plain JSON, so it crosses
191
- process boundaries with the bytes:
203
+ process boundaries with the bytes. `finish` recomputes H from the bytes you hand back and rebuilds the payment from
204
+ `chosen`; it trusts both. Keep `chosen` and the bytes on your side of the boundary, or seal them, and carry `request`
205
+ to the signer over a channel you trust.
206
+
207
+ `confirm` and `finish` neither pay nor check the agreement; only `transact` and `agree` do. When `chosen.agreement` is
208
+ set, the pairing's payment is not itself a public proof of H: do not sign yet. Call
209
+ `agree(bytes, chosen.agreement, signer, fetch)`, have your agent approve the `approve` it returns, call `agree` again
210
+ with `{ approved }`, and sign `request` only with its `receipt` in hand.
192
211
 
193
212
  ```ts
194
213
  import { confirm, finish, type Fetch } from "@integraledger/terms";
@@ -199,7 +218,7 @@ const atr = new TextEncoder().encode(
199
218
  '{"atrVersion":"1","id":"0f8fad5b-d9cb-469f-a165-70867728950e","x402":{"z":1.0,"a":"caf\\u00e9"},"seller":{"note":"Café — 30 días ✓"}}',
200
219
  );
201
220
  const H = "0x8b1e122580ae3f6a8c3d36a24294e1260a87bde70f597279b973e39310072938";
202
- const link = `https://atr.seller.example/${H}`;
221
+ const link = `https://atr.seller.example/${crypto.randomUUID()}`;
203
222
  const offer = {
204
223
  x402Version: 2,
205
224
  resource: { url: "https://api.seller.example/v1/quote" },
@@ -232,7 +251,7 @@ const signature = await wallet.signTypedData(
232
251
  confirmed.request.typedData as Parameters<typeof wallet.signTypedData>[0],
233
252
  );
234
253
 
235
- // 3. Finish from what came back. finish recomputes H from the bytes; it trusts nothing it did not rebuild.
254
+ // 3. Finish from what came back. finish recomputes H from the bytes and rebuilds the payment from chosen.
236
255
  const back = JSON.parse(handOff);
237
256
  const done = await finish(new Uint8Array(Buffer.from(back.atr, "base64")), back.chosen, signature, exactEip3009);
238
257
  if ("decline" in done) throw new Error(done.decline.code);
@@ -276,13 +295,21 @@ before anything is signed:
276
295
  public proof: the same rule as for the main payment's options.
277
296
  - The agreement URL's `402` must advertise the same H, or nothing is signed (`hash-mismatch`).
278
297
  - Once the agreement payment is sent, the gate sends the same payment again after each `202`, `5xx` or timeout, within
279
- the paid option's `maxTimeoutSeconds` plus 180 seconds. It never signs a second agreement payment. `signal` ends the
280
- exchange sooner.
281
- - Where the agreement is already recorded, the first call goes straight on to the main payment.
298
+ the paid option's `maxTimeoutSeconds` plus 180 seconds. Within one call it never signs a second agreement payment.
299
+ `signal` ends the exchange sooner.
300
+ - The receipt is the agreement URL's statement: the gate checks its form and that its `atrHash` is H, and does not
301
+ look up the transaction it names. A `200` to the first, unpaid request is taken as an agreement already recorded,
302
+ and the first call goes straight on to the main payment.
282
303
  - A pairing that needs an agreement and whose offer names none is declined with `agreement-not-offered`.
283
304
  - `agree(bytes, url, signer, fetch, { approved, inputs, signal })` runs the exchange on its own, in the same two calls,
284
305
  for an agent that drives each step.
285
306
 
307
+ Once the agreement payment is sent, every decline carries it as `moved`: `agreement-pending` when it may settle yet,
308
+ and `agreement-failed` when the agreement URL answered otherwise. Either way, it has left your wallet. To collect the
309
+ receipt, call again without `approved`: the gate asks the agreement URL unpaid and goes on once it answers `200` with
310
+ the receipt, or declines `agreement-pending` again while it answers `202`, signing nothing. Never call again with
311
+ `approved` for the same agreement: every call with `approved` signs and sends a new agreement payment.
312
+
286
313
  ### Channels and sessions
287
314
 
288
315
  In an x402 batch-settlement channel or an MPP session, one ATR covers the whole channel. The gate compares it once, at
@@ -297,7 +324,7 @@ const atr = new TextEncoder().encode(
297
324
  '{"atrVersion":"1","id":"0f8fad5b-d9cb-469f-a165-70867728950e","x402":{"z":1.0,"a":"caf\\u00e9"},"seller":{"note":"Café — 30 días ✓"}}',
298
325
  );
299
326
  const H = "0x8b1e122580ae3f6a8c3d36a24294e1260a87bde70f597279b973e39310072938";
300
- const link = `https://atr.seller.example/${H}`;
327
+ const link = `https://atr.seller.example/${crypto.randomUUID()}`;
301
328
 
302
329
  // The seller's batch-settlement offer: 1000 units per request, into a channel.
303
330
  const offer = {
@@ -363,21 +390,26 @@ voucher up to 1000
363
390
  voucher up to 2000
364
391
  ```
365
392
 
366
- The hold is plain JSON: store it, and pass the latest one to each call. `within` re-derives everything from the hold,
367
- never from the new challenge, and signs only when that challenge advertises the held H and the payment it builds names
368
- the held channel.
393
+ The hold is plain JSON: store it, and pass the latest one to each call. `within` takes the bytes, H and the channel
394
+ from the hold, and the amount from the new challenge. On x402's batch channels it signs only when that challenge
395
+ advertises the held H and the payment it builds names the held channel. On an MPP session it declines a challenge that
396
+ names another channel or another H, and signs one with no legal context under the held H.
369
397
 
370
398
  ### Confirm a payment later: `check`
371
399
 
372
- `check(bytes, presented, binding)` confirms that a payment you hold carries, inside what was signed, the SHA-256 of the
373
- bytes you kept. Where `finish` or `transact` returned `landed`, put it back into the payment as `landed` first.
400
+ `check(bytes, presented, binding, landed?)` confirms that the ATR hash the pairing reads from a payment you hold is the
401
+ SHA-256 of the bytes you kept. A payment from which the pairing reads no ATR hash is declined `signed-not-bound`. Where
402
+ `finish` or `transact` returned `landed`, pass it as `landed`, beside the payment: a `landed` member written into the
403
+ payment is not read. The caller passes as `landed` only the receipt its own reader read for the payment, as `finish` or
404
+ `transact` returned it, never a value another party sent.
374
405
 
375
406
  ### Declines and `moved`
376
407
 
377
408
  A decline is `{ decline: { code, detail } }`. `code` is one of twelve values; `detail` is a sentence or the protocol
378
409
  package's refusal code. Where your signer moved the payment itself before the gate declined (a Lightning node paid the
379
410
  invoice, a signer broadcast a transaction), the decline also carries `moved: { signed, bytes, h }`. Keep it, and present
380
- it again rather than signing a new payment.
411
+ that same payment again rather than signing a new one. Where `moved` is an agreement payment, collect its receipt by
412
+ calling again without `approved`, as [Pay the agreement first](#pay-the-agreement-first) says.
381
413
 
382
414
  | Code | Meaning |
383
415
  | --- | --- |
@@ -389,7 +421,7 @@ it again rather than signing a new payment.
389
421
  | `atr-too-large` | The ATR is larger than 1 MiB (1,048,576 bytes). |
390
422
  | `hash-mismatch` | The served bytes do not hash to the advertised H; the agreement URL or a later channel challenge advertises another H; or a hold's bytes do not hash to its H. Nothing was signed. |
391
423
  | `signer-failed` | Your signer threw. |
392
- | `signed-not-bound` | What was signed does not carry the hash of the compared bytes. The payment is not returned. |
424
+ | `signed-not-bound` | The pairing does not read the hash of the compared bytes from the payment. The payment is not returned. |
393
425
  | `agreement-not-offered` | The pairing's payment is not a public proof, and the offer names no agreement URL. |
394
426
  | `agreement-pending` | The agreement payment was sent and is not yet recorded, or another is already settling. |
395
427
  | `agreement-failed` | The agreement URL could not be reached, answered `200` or `402` with a `Content-Encoding` other than `identity`, or answered with something other than a receipt for this H; the approved payment names another agreement URL; or `signal` ended the exchange before the payment was sent. |
@@ -404,7 +436,7 @@ Everything below is exported from `@integraledger/terms`.
404
436
  | --- | --- | --- |
405
437
  | `transact` | `(doc, binding, signer, fetch, options?) => Promise<{ signed, bytes, h, agreement?, landed? } \| ToApprove \| Declined>` | Compare, pay the approved agreement first where needed, sign, finish. |
406
438
  | `confirm` | `(doc, binding, account, fetch, inputs?) => Promise<{ chosen, request, bytes, h } \| Declined>` | Read, fetch, compare, and build the signing request with H. `request` is `null` when there is nothing to sign; `chosen.agreement` is the agreement URL, where the pairing needs one. |
407
- | `finish` | `(bytes, chosen, signature, binding) => Promise<{ signed, h, landed? } \| { next, h } \| Declined>` | Rebuild from `chosen` and the bytes, join the signature, and return the payment only when what was signed carries H. |
439
+ | `finish` | `(bytes, chosen, signature, binding) => Promise<{ signed, h, landed? } \| { next, h } \| Declined>` | Rebuild from `chosen` and the bytes, join the signature, and return the payment only when the pairing reads H from the completed payment, or, where the proof is the agreement payment, without that reading. |
408
440
  | `check` | `(bytes, presented, binding) => Promise<{ h } \| Declined>` | Confirm a held payment carries the hash of the kept bytes. |
409
441
  | `agree` | `(bytes, url, signer, fetch, options?) => Promise<ToApprove \| { receipt } \| Declined>` | Without `options.approved`, return the agreement payment to approve, signing nothing; with it, pay that payment and return the receipt. |
410
442
  | `openChannel` | `(bytes, opened, binding, landed?) => Promise<ChannelHold \| Declined>` | Hold a channel opened for the compared ATR. |
@@ -418,7 +450,7 @@ Everything below is exported from `@integraledger/terms`.
418
450
  | `Binding` | A pairing's binding from `@integraledger/lcp`. |
419
451
  | `Signer` | `{ account: string; sign(request: SigningRequest): Promise<Signature> }`. `account` is CAIP-10. |
420
452
  | `SigningRequest` | What a signer is handed: one kind per signing scheme, such as `eip712`, `solana-message`, `xrpl-tx`, `bolt11-pay` or `batch`. |
421
- | `Signature` | The signer's answer, as JSON. Byte strings are `0x` hex. |
453
+ | `Signature` | The signer's answer, as JSON, in the form the [signers guide](https://github.com/IntegraLedger/integra-agentic-terms/blob/main/docs/guides/signers.md) names for its kind. |
422
454
  | `Fetch` | WHATWG `fetch`, or anything with its call shape. |
423
455
  | `Inputs` | The buyer's own values a build needs: `{ [name]: Json }`. |
424
456
  | `TransactOptions` | `{ inputs?, agreementSigner?, approved?, signal? }`. |
@@ -428,7 +460,7 @@ Everything below is exported from `@integraledger/terms`.
428
460
  | `AgreementPayment` | The agreement payment to approve: `{ url, option, required }`. |
429
461
  | `ToApprove` | `{ approve: AgreementPayment; bytes; h }`. |
430
462
  | `AgreementReceipt` | `{ atrHash, agreed: true, network, transaction }`. |
431
- | `ChannelHold` | `{ pairing, network, channel, h, atr, opening, charged, signedMax }`, all JSON. |
463
+ | `ChannelHold` | `{ pairing, network, channel, h, atr, opening, landed?, charged, signedMax }`, all JSON. |
432
464
  | `Declined` | `{ decline: Reason; moved?: { signed, bytes, h } }`. |
433
465
  | `Reason` | `{ code: DeclineCode; detail: string }`. |
434
466
  | `DeclineCode` | The twelve codes in the table above. |
@@ -523,9 +555,11 @@ What the gate guarantees, in the code:
523
555
  - **Nothing is signed before the comparison.** The signer is called only after SHA-256 of the served bytes equals the
524
556
  advertised H, compared as 32 decoded bytes.
525
557
  - **The payment carries the computed hash.** The build takes the hash the gate computed, not the advertised string.
526
- - **What was signed is read back.** `finish` returns a payment only when the binding reads, from what was signed, the
527
- hash of the compared bytes. For a pairing whose payment is not a public proof, the payment is returned only after the
528
- agreement's receipt for that hash.
558
+ - **The hash is read back from the payment.** `finish` returns a payment only when the binding reads, from the completed
559
+ payment, the hash of the compared bytes, or, where the proof is the agreement payment, without that reading. For a
560
+ pairing whose payment is not a public proof, `transact` signs the payment only after the agreement's receipt for that
561
+ hash. `confirm` and `finish` neither pay nor check the agreement: a caller that drives them signs `request` only with
562
+ the receipt `agree` returns.
529
563
  - **Every payment is shown before it is signed.** The agreement payment is returned for your agent's approval, with its
530
564
  amount, asset, payee and network, and is signed only when a second call carries it back.
531
565
  - **One bounded fetch.** One `GET` of an `https` link, no redirect, one 10-second deadline over headers and body, at most
@@ -539,9 +573,11 @@ What the gate guarantees, in the code:
539
573
  What it does not do:
540
574
 
541
575
  - It does not read or judge the ATR's content.
542
- - It does not check amount, payee, asset, timing or payer against the ATR, and applies no spending limit to the
543
- agreement payment. A discrepancy is between the parties; what to approve is your agent's decision.
544
- - It does not authenticate the agreement's receipt. The public proof is the transaction the receipt names, on its
576
+ - It does not check amount, payee, asset, timing or payer against the ATR, and applies no spending limit. A
577
+ discrepancy is between the parties; what to approve is your agent's decision.
578
+ - It does not authenticate the agreement's receipt. The receipt is the agreement URL's statement: the gate checks its
579
+ form and that its `atrHash` is H, and does not look up the transaction it names. A `200` to the first, unpaid
580
+ request is taken as an agreement already recorded. The public proof is the transaction the receipt names, on its
545
581
  network.
546
582
  - It carries no business or legal logic.
547
583
  - It does not store the ATR, talk to a facilitator, or settle a payment.
@@ -558,7 +594,7 @@ the same files, so both languages compute the same hashes, build the same reques
558
594
 
559
595
  ## Requirements
560
596
 
561
- - Node.js `>=26.10.0`.
597
+ - Node.js `>=26.11.1`.
562
598
  - An HTTP client with WHATWG `fetch`'s call shape (Node's global `fetch` is one).
563
599
  - Cloudflare Workers, with or without the `nodejs_compat` flag: pass the Worker's own `fetch`, and install
564
600
  `@integraledger/lcp`'s optional peer dependencies before bundling. See
@@ -2,15 +2,25 @@ import type { AgreeOptions, AgreementReceipt, Declined, Fetch, Signer, ToApprove
2
2
  /**
3
3
  * Without `approved`: asks the agreement URL for its challenge and returns the agreement payment to approve, signing
4
4
  * nothing, or the receipt where the agreement is already recorded. With `approved`: signs exactly that payment with
5
- * `signer`, sends it to `url`, and returns the receipt once recorded. `bytes` are the ATR the gate compared, whose hash
6
- * the agreement payment carries; `inputs` are the buyer's own chain values; `signal` ends the exchange.
5
+ * `signer`, sends it to `url`, and returns the receipt once recorded; a payment whose challenge the protocol package's
6
+ * read refuses for a fault of its own (its version, legal context or agreement URL, or an `accepts` that is not a list
7
+ * of at most 32 entries holding an object) is declined as the unpaid request declines that challenge, and one whose
8
+ * option is not one of that challenge's `accepts`, by RFC 8785 form, is declined `offer-unreadable` with
9
+ * `x402/option-not-in-document`, each before any fetch or signer call.
10
+ * `bytes` are the ATR the gate compared, whose hash the agreement payment carries; `inputs` are the buyer's own chain
11
+ * values; `signal` ends the exchange. Options holding anything but `approved`, `inputs` and `signal`, a `signal` that
12
+ * is not an `AbortSignal`, an `approved` that is not of the agreement payment's form, `inputs` that is not an object,
13
+ * or a signer whose `account` is not a string, is declined `no-payable-option` with `x402/input-malformed` before any
14
+ * fetch or signer call. A `url` that is not an https URL is declined `link-not-https` with `x402/link-not-https` for an
15
+ * absolute URL of another scheme and `x402/legal-context-malformed` for any other value, before any fetch.
7
16
  */
8
17
  export declare function agree(bytes: Uint8Array, url: string, signer: Signer, fetch: Fetch, options?: AgreeOptions): Promise<ToApprove | {
9
18
  receipt: AgreementReceipt;
10
19
  } | Declined>;
11
20
  /**
12
- * `agree`, where `ns` is the namespace of the pairing whose offer named the URL: a refused URL's detail carries it with
13
- * the protocol package's code.
21
+ * `agree`, where `ns` is the namespace of the pairing whose offer named the URL, x402 when none did: a refused URL
22
+ * declines `link-not-https`, its detail the protocol package's code in that namespace, `link-not-https` for an absolute
23
+ * URL of another scheme and `legal-context-malformed` for any other value.
14
24
  */
15
25
  export declare function exchange(bytes: Uint8Array, url: string, signer: Signer, fetch: Fetch, options: AgreeOptions, ns: string | undefined): Promise<ToApprove | {
16
26
  receipt: AgreementReceipt;