@integraledger/terms 0.1.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (51) hide show
  1. package/README.md +135 -65
  2. package/dist/agreement.d.ts +21 -17
  3. package/dist/agreement.js +279 -85
  4. package/dist/channels.d.ts +35 -12
  5. package/dist/channels.js +152 -70
  6. package/dist/gate.d.ts +41 -18
  7. package/dist/gate.js +81 -47
  8. package/dist/index.d.ts +1 -1
  9. package/dist/pairings/batch.d.ts +2 -5
  10. package/dist/pairings/batch.js +3 -13
  11. package/dist/pairings/card.js +0 -2
  12. package/dist/pairings/common.d.ts +7 -1
  13. package/dist/pairings/common.js +17 -2
  14. package/dist/pairings/evm-x402.js +3 -3
  15. package/dist/pairings/lightning.js +1 -1
  16. package/dist/pairings/lnbtc-request.d.ts +1 -1
  17. package/dist/pairings/lnbtc-request.js +1 -1
  18. package/dist/pairings/mpp-charge-hedera.d.ts +7 -7
  19. package/dist/pairings/mpp-charge-hedera.js +1 -1
  20. package/dist/pairings/mpp-charge-stellar.js +1 -1
  21. package/dist/pairings/mpp-charge-tempo-memo.d.ts +1 -9
  22. package/dist/pairings/mpp-charge-tempo-memo.js +3 -7
  23. package/dist/pairings/mpp-charge-tempo-push.d.ts +0 -1
  24. package/dist/pairings/mpp-charge-tempo-push.js +2 -10
  25. package/dist/pairings/mpp-charge-xrpl.js +3 -3
  26. package/dist/pairings/mpp-rails.d.ts +1 -1
  27. package/dist/pairings/mpp-session-solana.js +2 -2
  28. package/dist/pairings/mpp-session-xrpl.js +3 -4
  29. package/dist/pairings/mpp-session.js +1 -1
  30. package/dist/pairings/mpp.d.ts +12 -16
  31. package/dist/pairings/mpp.js +32 -109
  32. package/dist/pairings/protocol-groups.d.ts +1 -1
  33. package/dist/pairings/x402-account-rails.d.ts +1 -1
  34. package/dist/pairings/x402-batch-settlement-eip155.js +1 -1
  35. package/dist/pairings/x402-batch-settlement-solana.d.ts +2 -0
  36. package/dist/pairings/x402-batch-settlement-solana.js +3 -2
  37. package/dist/pairings/x402-exact-casper.js +3 -3
  38. package/dist/pairings/x402-exact-ccd.js +3 -3
  39. package/dist/pairings/x402-exact-hedera.d.ts +4 -1
  40. package/dist/pairings/x402-exact-hedera.js +5 -2
  41. package/dist/pairings/x402-exact-solana.d.ts +4 -4
  42. package/dist/pairings/x402-exact-solana.js +3 -2
  43. package/dist/pairings/x402-exact-stellar.js +1 -1
  44. package/dist/pairings/x402-exact-sui.js +3 -1
  45. package/dist/pairings/x402-exact-tvm.js +10 -2
  46. package/dist/pairings/x402-exact-xrpl.js +2 -4
  47. package/dist/pairings/x402-rail.d.ts +1 -1
  48. package/dist/transact.d.ts +14 -9
  49. package/dist/transact.js +30 -24
  50. package/dist/types.d.ts +43 -18
  51. package/package.json +11 -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.0 @integraledger/lcp@0.4.0
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.0 @integraledger/lcp@0.4.0
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.0`): 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`, `near-api-js` and `ripple-binary-codec`, at the versions `@integraledger/lcp`
58
+ names. Install the 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 = {
@@ -102,14 +110,15 @@ const signer: Signer = {
102
110
 
103
111
  const result = await transact(offer, exactEip3009, signer, fetch);
104
112
  if ("decline" in result) throw new Error(`${result.decline.code}: ${result.decline.detail}`);
113
+ if ("approve" in result) throw new Error("this pairing pays no agreement first");
105
114
 
106
115
  const payment = result.signed as Eip3009Payment;
107
116
  console.log("H ", result.h);
108
117
  console.log("signed nonce", payment.payload.authorization.nonce);
109
118
  console.log("kept bytes ", result.bytes.length);
110
119
 
111
- // x402 over HTTP sends the payment as base64 of its JSON, in the PAYMENT-SIGNATURE header.
112
- 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");
113
122
  console.log("header ", header.length > 0 ? "ready" : "empty");
114
123
  ```
115
124
 
@@ -135,48 +144,70 @@ sequenceDiagram
135
144
  participant S as Seller
136
145
  participant W as Your signer
137
146
  A->>G: confirm(offer, binding, account, fetch)
138
- G->>S: GET the link (https, no redirect, at most 1 MiB, 10 s)
147
+ G->>S: GET the link (https, identity coding, no redirect, at most 1 MiB, 10 s)
139
148
  S-->>G: The ATR's bytes
140
149
  G->>G: SHA-256(bytes) equals H?
141
150
  G-->>A: The signing request, built with H
142
151
  A->>W: sign(request)
143
152
  W-->>A: The signature
144
153
  A->>G: finish(bytes, chosen, signature)
145
- 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
146
155
  ```
147
156
 
148
157
  1. **Read.** The pairing's binding reads the seller's document: H, the link, and the payment options.
149
158
  2. **Compare.** The gate fetches the link once and hashes the bytes it received. No match: a decline, and no signer
150
159
  call.
151
160
  3. **Build.** On a match, the gate builds the payment with the hash it computed, not the string the seller advertised.
152
- 4. **Finish.** The gate joins your signer's answer, reads H back out of what was signed, and returns the payment only
153
- 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.
154
164
 
155
165
  Every function returns a value, never throws for a protocol outcome: either its result, or
156
166
  `{ decline: { code, detail } }`.
157
167
 
158
168
  ## Guides
159
169
 
160
- ### Pay in one call: `transact`
170
+ ### Pay with `transact`
161
171
 
162
- `transact(doc, binding, signer, fetch, options?)` runs the whole order: compare, pay the agreement first where the
163
- pairing needs one, sign, finish. Its result is:
172
+ `transact(doc, binding, signer, fetch, options?)` runs the whole order: compare, pay the agreement your agent approved
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:
164
177
 
165
178
  | Member | What it is |
166
179
  | --- | --- |
167
180
  | `signed` | The payment to send, in the protocol's own form. `null` when the pairing gives the buyer nothing to sign. |
168
181
  | `bytes` | The ATR's exact bytes: your copy of the record. |
169
182
  | `h` | Their SHA-256. |
170
- | `agreement` | The agreement's receipt, where an agreement was paid first. |
183
+ | `agreement` | The agreement's receipt, where the pairing needs an agreement payment. |
171
184
  | `landed` | A landed receipt to keep beside the payment, for the few pairings that return one. |
172
185
 
173
- `options` takes `inputs` (the buyer's own values a build needs, such as a recent blockhash) and `agreementSigner`
174
- (the wallet that pays the agreement, where it is not `signer`). Any other member is declined before any fetch.
186
+ Where the pairing needs an agreement payment that is not yet recorded, the result is instead
187
+ `{ approve, bytes, h }`, and nothing has been signed: see [Pay the agreement first](#pay-the-agreement-first).
188
+
189
+ `options` takes:
190
+
191
+ | Member | What it is |
192
+ | --- | --- |
193
+ | `inputs` | The buyer's own values a build needs, such as a recent blockhash. |
194
+ | `agreementSigner` | The wallet that pays the agreement, where it is not `signer`. |
195
+ | `approved` | The agreement payment your agent approved, exactly as a previous call returned it in `approve`. |
196
+ | `signal` | An `AbortSignal` that ends the agreement exchange. |
197
+
198
+ Any other member, or a member of the wrong kind, is declined before any fetch.
175
199
 
176
200
  ### Sign elsewhere: `confirm`, then `finish`
177
201
 
178
202
  When the key lives in a hardware wallet or a signing service, split the order. `chosen` is plain JSON, so it crosses
179
- 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.
180
211
 
181
212
  ```ts
182
213
  import { confirm, finish, type Fetch } from "@integraledger/terms";
@@ -187,7 +218,7 @@ const atr = new TextEncoder().encode(
187
218
  '{"atrVersion":"1","id":"0f8fad5b-d9cb-469f-a165-70867728950e","x402":{"z":1.0,"a":"caf\\u00e9"},"seller":{"note":"Café — 30 días ✓"}}',
188
219
  );
189
220
  const H = "0x8b1e122580ae3f6a8c3d36a24294e1260a87bde70f597279b973e39310072938";
190
- const link = `https://atr.seller.example/${H}`;
221
+ const link = `https://atr.seller.example/${crypto.randomUUID()}`;
191
222
  const offer = {
192
223
  x402Version: 2,
193
224
  resource: { url: "https://api.seller.example/v1/quote" },
@@ -220,7 +251,7 @@ const signature = await wallet.signTypedData(
220
251
  confirmed.request.typedData as Parameters<typeof wallet.signTypedData>[0],
221
252
  );
222
253
 
223
- // 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.
224
255
  const back = JSON.parse(handOff);
225
256
  const done = await finish(new Uint8Array(Buffer.from(back.atr, "base64")), back.chosen, signature, exactEip3009);
226
257
  if ("decline" in done) throw new Error(done.decline.code);
@@ -240,8 +271,16 @@ A pairing signed in two steps (a channel funding, then its first voucher) makes
240
271
 
241
272
  Some payments are not a public proof of H: a card charge, a Stripe payment, a Lightning invoice, a checkout in which
242
273
  the buyer signs nothing. For those pairings the seller's offer also names an **agreement URL**, an x402 resource for the
243
- same H whose payment is a public proof. `transact` pays it first, and signs the main payment only after the agreement
244
- URL answers with its receipt:
274
+ same H whose payment is a public proof. The agreement payment is a payment like any other, so your agent approves it
275
+ before anything is signed:
276
+
277
+ 1. `transact` fetches the agreement URL's payment request and returns `{ approve, bytes, h }`, signing nothing.
278
+ `approve.option` is the option it would pay: its `amount`, `asset`, `payTo` and `network`. `approve.url` is the
279
+ agreement URL, and `approve.required` the payment request as served.
280
+ 2. Your agent approves it as it approves any payment. To pay it, call `transact` again with the same arguments and
281
+ `{ approved: approve }`.
282
+ 3. The second call signs exactly that payment, sends it, and signs the main payment only after the agreement URL
283
+ answers with its receipt:
245
284
 
246
285
  ```json
247
286
  {
@@ -252,11 +291,24 @@ URL answers with its receipt:
252
291
  }
253
292
  ```
254
293
 
294
+ - The option paid is the first, in document order, that your signer can pay with a pairing whose payment is itself a
295
+ public proof: the same rule as for the main payment's options.
255
296
  - The agreement URL's `402` must advertise the same H, or nothing is signed (`hash-mismatch`).
256
297
  - Once the agreement payment is sent, the gate sends the same payment again after each `202`, `5xx` or timeout, within
257
- the agreement option's `maxTimeoutSeconds` plus 180 seconds. It never signs a second agreement 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.
258
303
  - A pairing that needs an agreement and whose offer names none is declined with `agreement-not-offered`.
259
- - `agree(h, url, signer, fetch, { bytes, inputs })` runs the exchange on its own, for an agent that drives each step.
304
+ - `agree(bytes, url, signer, fetch, { approved, inputs, signal })` runs the exchange on its own, in the same two calls,
305
+ for an agent that drives each step.
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.
260
312
 
261
313
  ### Channels and sessions
262
314
 
@@ -272,7 +324,7 @@ const atr = new TextEncoder().encode(
272
324
  '{"atrVersion":"1","id":"0f8fad5b-d9cb-469f-a165-70867728950e","x402":{"z":1.0,"a":"caf\\u00e9"},"seller":{"note":"Café — 30 días ✓"}}',
273
325
  );
274
326
  const H = "0x8b1e122580ae3f6a8c3d36a24294e1260a87bde70f597279b973e39310072938";
275
- const link = `https://atr.seller.example/${H}`;
327
+ const link = `https://atr.seller.example/${crypto.randomUUID()}`;
276
328
 
277
329
  // The seller's batch-settlement offer: 1000 units per request, into a channel.
278
330
  const offer = {
@@ -315,7 +367,7 @@ const signer: Signer = {
315
367
  const opened = await transact(offer, batchEvm, signer, fetch, {
316
368
  inputs: { payerAuthorizer: authorizer.address, deposit: "100000" },
317
369
  });
318
- if ("decline" in opened || opened.signed === null) throw new Error("the channel did not open");
370
+ if ("decline" in opened || "approve" in opened || opened.signed === null) throw new Error("the channel did not open");
319
371
  let hold = await openChannel(opened.bytes, opened.signed, batchEvm);
320
372
  if ("decline" in hold) throw new Error(hold.decline.code);
321
373
  console.log("channel ", hold.channel);
@@ -338,35 +390,39 @@ voucher up to 1000
338
390
  voucher up to 2000
339
391
  ```
340
392
 
341
- The hold is plain JSON: store it, and pass the latest one to each call. `within` re-derives everything from the hold,
342
- never from the new challenge, and signs only when that challenge advertises the held H.
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.
343
397
 
344
398
  ### Confirm a payment later: `check`
345
399
 
346
- `check(bytes, presented, binding)` confirms that a payment you hold carries, inside what was signed, the SHA-256 of the
347
- bytes you kept. Where `finish` or `transact` returned `landed`, put it back into the payment as `landed` first.
400
+ `check(bytes, presented, binding)` confirms that the ATR hash the pairing reads from a payment you hold is the SHA-256
401
+ of the bytes you kept. A payment from which the pairing reads no ATR hash is declined `signed-not-bound`. Where `finish`
402
+ or `transact` returned `landed`, put it back into the payment as `landed` first.
348
403
 
349
404
  ### Declines and `moved`
350
405
 
351
406
  A decline is `{ decline: { code, detail } }`. `code` is one of twelve values; `detail` is a sentence or the protocol
352
407
  package's refusal code. Where your signer moved the payment itself before the gate declined (a Lightning node paid the
353
408
  invoice, a signer broadcast a transaction), the decline also carries `moved: { signed, bytes, h }`. Keep it, and present
354
- it again rather than signing a new payment.
409
+ that same payment again rather than signing a new one. Where `moved` is an agreement payment, collect its receipt by
410
+ calling again without `approved`, as [Pay the agreement first](#pay-the-agreement-first) says.
355
411
 
356
412
  | Code | Meaning |
357
413
  | --- | --- |
358
- | `pairing-not-supported` | The binding names no pairing the gate serves; `chosen` or a hold belongs to another pairing; the pairing has no channel; or the agreement URL's option is not paid with a public-proof pairing. |
414
+ | `pairing-not-supported` | The binding names no pairing the gate serves; `chosen` or a hold belongs to another pairing; or the pairing has no channel. |
359
415
  | `offer-unreadable` | The seller's document, the chosen option or a build could not be read, or a recorded charge is out of range. `detail` carries the reason. |
360
- | `no-payable-option` | No option is payable by this account, an input the build needs is missing or malformed, or `transact`'s options are malformed. |
416
+ | `no-payable-option` | No option is payable by this account (for the agreement, with a public-proof pairing), an input the build needs is missing or malformed, the options of `transact` or `agree` are malformed, or a later channel challenge asks for a payment in a channel the hold did not open. |
361
417
  | `link-not-https` | The ATR link or the agreement URL is not an `https` URL. Nothing was fetched. |
362
- | `atr-unfetchable` | The link did not answer `200` with the bytes within 10 seconds (a redirect counts as a failure). |
418
+ | `atr-unfetchable` | The link did not answer `200` with the bytes within 10 seconds (a redirect counts as a failure), or answered `200` with a `Content-Encoding` other than `identity`. |
363
419
  | `atr-too-large` | The ATR is larger than 1 MiB (1,048,576 bytes). |
364
420
  | `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. |
365
421
  | `signer-failed` | Your signer threw. |
366
- | `signed-not-bound` | What was signed does not carry the hash of the compared bytes. The payment is not returned. |
422
+ | `signed-not-bound` | The pairing does not read the hash of the compared bytes from the payment. The payment is not returned. |
367
423
  | `agreement-not-offered` | The pairing's payment is not a public proof, and the offer names no agreement URL. |
368
424
  | `agreement-pending` | The agreement payment was sent and is not yet recorded, or another is already settling. |
369
- | `agreement-failed` | The agreement URL could not be reached, or answered with something other than a receipt for this H. |
425
+ | `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. |
370
426
 
371
427
  ## API reference
372
428
 
@@ -376,11 +432,11 @@ Everything below is exported from `@integraledger/terms`.
376
432
 
377
433
  | Export | Signature | What it does |
378
434
  | --- | --- | --- |
379
- | `transact` | `(doc, binding, signer, fetch, options?) => Promise<{ signed, bytes, h, agreement?, landed? } \| Declined>` | Compare, pay the agreement first where needed, sign, finish. |
380
- | `confirm` | `(doc, binding, account, fetch, inputs?) => Promise<{ chosen, request, bytes, h, agreement? } \| Declined>` | Read, fetch, compare, and build the signing request with H. `request` is `null` when there is nothing to sign. |
381
- | `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. |
435
+ | `transact` | `(doc, binding, signer, fetch, options?) => Promise<{ signed, bytes, h, agreement?, landed? } \| ToApprove \| Declined>` | Compare, pay the approved agreement first where needed, sign, finish. |
436
+ | `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. |
437
+ | `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. |
382
438
  | `check` | `(bytes, presented, binding) => Promise<{ h } \| Declined>` | Confirm a held payment carries the hash of the kept bytes. |
383
- | `agree` | `(h, url, signer, fetch, { bytes, inputs?, ns? }) => Promise<{ receipt } \| Declined>` | Pay an agreement URL for H and return its receipt. |
439
+ | `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. |
384
440
  | `openChannel` | `(bytes, opened, binding, landed?) => Promise<ChannelHold \| Declined>` | Hold a channel opened for the compared ATR. |
385
441
  | `within` | `(doc, hold, binding, signer, refund?, inputs?) => Promise<{ signed, hold } \| Declined>` | Sign a later voucher, or a refund with `refund`, in a held channel. |
386
442
  | `recordCharge` | `(hold, chargedCumulativeAmount) => ChannelHold \| Declined` | Record the seller's cumulative charge, between the last recorded and the most signed. |
@@ -392,12 +448,15 @@ Everything below is exported from `@integraledger/terms`.
392
448
  | `Binding` | A pairing's binding from `@integraledger/lcp`. |
393
449
  | `Signer` | `{ account: string; sign(request: SigningRequest): Promise<Signature> }`. `account` is CAIP-10. |
394
450
  | `SigningRequest` | What a signer is handed: one kind per signing scheme, such as `eip712`, `solana-message`, `xrpl-tx`, `bolt11-pay` or `batch`. |
395
- | `Signature` | The signer's answer, as JSON. Byte strings are `0x` hex. |
451
+ | `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. |
396
452
  | `Fetch` | WHATWG `fetch`, or anything with its call shape. |
397
453
  | `Inputs` | The buyer's own values a build needs: `{ [name]: Json }`. |
398
- | `TransactOptions` | `{ inputs?, agreementSigner? }`. |
399
- | `Chosen` | What the gate chose to pay, as plain JSON: `{ pairing, choice, ref }`. |
454
+ | `TransactOptions` | `{ inputs?, agreementSigner?, approved?, signal? }`. |
455
+ | `AgreeOptions` | `{ approved?, inputs?, signal? }`. |
456
+ | `Chosen` | What the gate chose to pay, as plain JSON: `{ pairing, choice, ref, agreement? }`. |
400
457
  | `Presented` | A payment in its protocol's form. |
458
+ | `AgreementPayment` | The agreement payment to approve: `{ url, option, required }`. |
459
+ | `ToApprove` | `{ approve: AgreementPayment; bytes; h }`. |
401
460
  | `AgreementReceipt` | `{ atrHash, agreed: true, network, transaction }`. |
402
461
  | `ChannelHold` | `{ pairing, network, channel, h, atr, opening, charged, signedMax }`, all JSON. |
403
462
  | `Declined` | `{ decline: Reason; moved?: { signed, bytes, h } }`. |
@@ -494,19 +553,30 @@ What the gate guarantees, in the code:
494
553
  - **Nothing is signed before the comparison.** The signer is called only after SHA-256 of the served bytes equals the
495
554
  advertised H, compared as 32 decoded bytes.
496
555
  - **The payment carries the computed hash.** The build takes the hash the gate computed, not the advertised string.
497
- - **What was signed is read back.** `finish` returns a payment only when the binding reads, from what was signed, the
498
- hash of the compared bytes. For a pairing whose payment is not a public proof, the payment is returned only after the
499
- agreement's receipt for that hash.
556
+ - **The hash is read back from the payment.** `finish` returns a payment only when the binding reads, from the completed
557
+ payment, the hash of the compared bytes, or, where the proof is the agreement payment, without that reading. For a
558
+ pairing whose payment is not a public proof, `transact` signs the payment only after the agreement's receipt for that
559
+ hash. `confirm` and `finish` neither pay nor check the agreement: a caller that drives them signs `request` only with
560
+ the receipt `agree` returns.
561
+ - **Every payment is shown before it is signed.** The agreement payment is returned for your agent's approval, with its
562
+ amount, asset, payee and network, and is signed only when a second call carries it back.
500
563
  - **One bounded fetch.** One `GET` of an `https` link, no redirect, one 10-second deadline over headers and body, at most
501
564
  1 MiB read. A declared or streamed length over the bound cancels the body.
502
- - **Exact bytes.** The ATR is hashed as received and returned as received. It is never parsed.
565
+ - **Exact bytes.** The ATR is hashed as received and returned as received. It is never parsed. Every request asks for
566
+ `Accept-Encoding: identity`, and a `200` whose `Content-Encoding` names any coding is declined unread, so nothing is
567
+ decompressed: the bytes hashed are the bytes sent.
503
568
  - **No keys.** The gate hands requests to your signer and holds nothing that could sign.
504
569
  - **Your network policy.** Every request goes through the `fetch` you pass.
505
570
 
506
571
  What it does not do:
507
572
 
508
573
  - It does not read or judge the ATR's content.
509
- - It does not check amount, payee, asset, timing or payer against the ATR. A discrepancy is between the parties.
574
+ - It does not check amount, payee, asset, timing or payer against the ATR, and applies no spending limit. A
575
+ discrepancy is between the parties; what to approve is your agent's decision.
576
+ - It does not authenticate the agreement's receipt. The receipt is the agreement URL's statement: the gate checks its
577
+ form and that its `atrHash` is H, and does not look up the transaction it names. A `200` to the first, unpaid
578
+ request is taken as an agreement already recorded. The public proof is the transaction the receipt names, on its
579
+ network.
510
580
  - It carries no business or legal logic.
511
581
  - It does not store the ATR, talk to a facilitator, or settle a payment.
512
582
 
@@ -522,7 +592,7 @@ the same files, so both languages compute the same hashes, build the same reques
522
592
 
523
593
  ## Requirements
524
594
 
525
- - Node.js `>=26.10.0`.
595
+ - Node.js `>=26.11.1`.
526
596
  - An HTTP client with WHATWG `fetch`'s call shape (Node's global `fetch` is one).
527
597
  - Cloudflare Workers, with or without the `nodejs_compat` flag: pass the Worker's own `fetch`, and install
528
598
  `@integraledger/lcp`'s optional peer dependencies before bundling. See
@@ -1,23 +1,27 @@
1
+ import type { AgreeOptions, AgreementReceipt, Declined, Fetch, Signer, ToApprove } from "./types.js";
1
2
  /**
2
- * The agreement payment. `agree` asks the agreement URL for its challenge, pays it through the buyer piece of the
3
- * pairing that placed it, a pairing whose payment is itself a public proof of the ATR hash, and returns the resource's
4
- * receipt once the payment is recorded. Nothing is signed when the challenge advertises another hash, and nothing is
5
- * sent unless what was signed carries the hash. Once sent, the same signed payment is sent again after each 202, 5xx or
6
- * timeout, each paid request bounded by min(`maxTimeoutSeconds`, 120) + 60 + 10 seconds and the whole exchange by the
7
- * agreement option's `maxTimeoutSeconds` + 180 seconds; no second agreement payment is signed, and every decline after
8
- * it was sent carries it as `moved`.
3
+ * Without `approved`: asks the agreement URL for its challenge and returns the agreement payment to approve, signing
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; 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.
9
16
  */
10
- import { type AtrHash } from "@integraledger/lcp";
11
- import type { AgreementReceipt, Declined, Fetch, Inputs, Signer } from "./types.js";
17
+ export declare function agree(bytes: Uint8Array, url: string, signer: Signer, fetch: Fetch, options?: AgreeOptions): Promise<ToApprove | {
18
+ receipt: AgreementReceipt;
19
+ } | Declined>;
12
20
  /**
13
- * Pays the agreement for `h` at `url` with `signer`, and returns the receipt. `bytes` are the ATR the gate compared,
14
- * for a pairing whose build reads them; `inputs` are the buyer's own chain values; `ns` is the namespace of the pairing
15
- * whose offer named the URL, which a refused URL's detail carries with 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.
16
24
  */
17
- export declare function agree(h: AtrHash, url: string, signer: Signer, fetch: Fetch, held: {
18
- bytes: Uint8Array;
19
- inputs?: Inputs;
20
- ns?: string;
21
- }): Promise<{
25
+ export declare function exchange(bytes: Uint8Array, url: string, signer: Signer, fetch: Fetch, options: AgreeOptions, ns: string | undefined): Promise<ToApprove | {
22
26
  receipt: AgreementReceipt;
23
27
  } | Declined>;