@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.
- package/README.md +135 -65
- package/dist/agreement.d.ts +21 -17
- package/dist/agreement.js +279 -85
- package/dist/channels.d.ts +35 -12
- package/dist/channels.js +152 -70
- package/dist/gate.d.ts +41 -18
- package/dist/gate.js +81 -47
- package/dist/index.d.ts +1 -1
- package/dist/pairings/batch.d.ts +2 -5
- package/dist/pairings/batch.js +3 -13
- package/dist/pairings/card.js +0 -2
- package/dist/pairings/common.d.ts +7 -1
- package/dist/pairings/common.js +17 -2
- package/dist/pairings/evm-x402.js +3 -3
- package/dist/pairings/lightning.js +1 -1
- package/dist/pairings/lnbtc-request.d.ts +1 -1
- package/dist/pairings/lnbtc-request.js +1 -1
- package/dist/pairings/mpp-charge-hedera.d.ts +7 -7
- package/dist/pairings/mpp-charge-hedera.js +1 -1
- package/dist/pairings/mpp-charge-stellar.js +1 -1
- 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 +0 -1
- package/dist/pairings/mpp-charge-tempo-push.js +2 -10
- package/dist/pairings/mpp-charge-xrpl.js +3 -3
- package/dist/pairings/mpp-rails.d.ts +1 -1
- package/dist/pairings/mpp-session-solana.js +2 -2
- package/dist/pairings/mpp-session-xrpl.js +3 -4
- package/dist/pairings/mpp-session.js +1 -1
- package/dist/pairings/mpp.d.ts +12 -16
- package/dist/pairings/mpp.js +32 -109
- 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-eip155.js +1 -1
- package/dist/pairings/x402-batch-settlement-solana.d.ts +2 -0
- package/dist/pairings/x402-batch-settlement-solana.js +3 -2
- package/dist/pairings/x402-exact-casper.js +3 -3
- package/dist/pairings/x402-exact-ccd.js +3 -3
- package/dist/pairings/x402-exact-hedera.d.ts +4 -1
- package/dist/pairings/x402-exact-hedera.js +5 -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-stellar.js +1 -1
- 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 +1 -1
- package/dist/transact.d.ts +14 -9
- package/dist/transact.js +30 -24
- package/dist/types.d.ts +43 -18
- 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.
|
|
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.0 @integraledger/lcp@0.4.0
|
|
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.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/${
|
|
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 =
|
|
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
|
|
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
|
|
153
|
-
|
|
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
|
|
170
|
+
### Pay with `transact`
|
|
161
171
|
|
|
162
|
-
`transact(doc, binding, signer, fetch, options?)` runs the whole order: compare, pay the agreement
|
|
163
|
-
pairing needs one, sign, finish.
|
|
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
|
|
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
|
-
|
|
174
|
-
|
|
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/${
|
|
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
|
|
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.
|
|
244
|
-
|
|
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
|
|
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(
|
|
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/${
|
|
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`
|
|
342
|
-
|
|
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
|
|
347
|
-
bytes you kept.
|
|
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
|
-
|
|
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
|
|
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,
|
|
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` |
|
|
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
|
|
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
|
|
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` | `(
|
|
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
|
|
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
|
-
| `
|
|
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
|
-
- **
|
|
498
|
-
hash of the compared bytes
|
|
499
|
-
agreement's receipt for that
|
|
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
|
|
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.
|
|
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
|
package/dist/agreement.d.ts
CHANGED
|
@@ -1,23 +1,27 @@
|
|
|
1
|
+
import type { AgreeOptions, AgreementReceipt, Declined, Fetch, Signer, ToApprove } from "./types.js";
|
|
1
2
|
/**
|
|
2
|
-
*
|
|
3
|
-
*
|
|
4
|
-
*
|
|
5
|
-
*
|
|
6
|
-
*
|
|
7
|
-
*
|
|
8
|
-
*
|
|
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
|
-
|
|
11
|
-
|
|
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
|
-
*
|
|
14
|
-
*
|
|
15
|
-
*
|
|
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
|
|
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>;
|