@integraledger/terms 0.2.0 → 0.3.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +88 -52
- package/dist/agreement.d.ts +14 -4
- package/dist/agreement.js +139 -49
- package/dist/channels.d.ts +47 -14
- package/dist/channels.js +147 -74
- package/dist/gate.d.ts +37 -16
- package/dist/gate.js +69 -45
- package/dist/pairings/batch.d.ts +2 -5
- package/dist/pairings/batch.js +1 -11
- package/dist/pairings/card.js +0 -2
- package/dist/pairings/common.d.ts +17 -4
- package/dist/pairings/common.js +35 -4
- package/dist/pairings/lnbtc-request.d.ts +1 -1
- package/dist/pairings/lnbtc-request.js +14 -5
- package/dist/pairings/mpp-charge-hedera.d.ts +13 -11
- package/dist/pairings/mpp-charge-hedera.js +16 -14
- package/dist/pairings/mpp-charge-tempo-memo.d.ts +1 -9
- package/dist/pairings/mpp-charge-tempo-memo.js +3 -7
- package/dist/pairings/mpp-charge-tempo-push.d.ts +6 -1
- package/dist/pairings/mpp-charge-tempo-push.js +4 -13
- package/dist/pairings/mpp-charge-xrpl.js +3 -3
- package/dist/pairings/mpp-rails.d.ts +1 -1
- package/dist/pairings/mpp-session-hedera.js +3 -4
- package/dist/pairings/mpp-session-xrpl.js +3 -4
- package/dist/pairings/mpp.d.ts +14 -17
- package/dist/pairings/mpp.js +35 -114
- package/dist/pairings/protocol-groups.d.ts +1 -1
- package/dist/pairings/x402-account-rails.d.ts +1 -1
- package/dist/pairings/x402-batch-settlement-solana.d.ts +2 -0
- package/dist/pairings/x402-batch-settlement-solana.js +2 -1
- package/dist/pairings/x402-exact-hedera.d.ts +4 -1
- package/dist/pairings/x402-exact-hedera.js +5 -2
- package/dist/pairings/x402-exact-near.js +23 -2
- package/dist/pairings/x402-exact-solana.d.ts +4 -4
- package/dist/pairings/x402-exact-solana.js +3 -2
- package/dist/pairings/x402-exact-sui.js +3 -1
- package/dist/pairings/x402-exact-tvm.js +10 -2
- package/dist/pairings/x402-exact-xrpl.js +2 -4
- package/dist/pairings/x402-rail.d.ts +3 -2
- package/dist/pairings/x402-rail.js +1 -1
- package/dist/transact.d.ts +3 -2
- package/dist/transact.js +9 -6
- package/dist/types.d.ts +6 -16
- package/package.json +10 -12
package/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.
|
|
14
|
-
that hash,
|
|
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,
|
|
19
|
-
|
|
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
|
|
22
|
-
|
|
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
|
|
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
|
|
30
|
-
|
|
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
|
|
33
|
-
`x402/exact/eip155/eip3009` it is the EIP-3009 `nonce`. Bindings are exported
|
|
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
|
|
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/),
|
|
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.
|
|
48
|
-
- `@integraledger/lcp` is a dependency of this package
|
|
49
|
-
|
|
50
|
-
|
|
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/${
|
|
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 =
|
|
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
|
|
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
|
|
154
|
-
|
|
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
|
|
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.
|
|
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/${
|
|
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
|
|
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.
|
|
280
|
-
exchange sooner.
|
|
281
|
-
-
|
|
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/${
|
|
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`
|
|
367
|
-
|
|
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
|
|
373
|
-
bytes you kept.
|
|
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
|
-
|
|
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` |
|
|
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
|
|
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
|
|
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
|
-
- **
|
|
527
|
-
hash of the compared bytes
|
|
528
|
-
agreement's receipt for that
|
|
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
|
|
543
|
-
|
|
544
|
-
- It does not authenticate the agreement's receipt. The
|
|
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.
|
|
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
|
package/dist/agreement.d.ts
CHANGED
|
@@ -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
|
|
6
|
-
*
|
|
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
|
|
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;
|