@integraledger/terms 0.1.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/LICENSE +202 -0
- package/README.md +539 -0
- package/dist/agreement.d.ts +23 -0
- package/dist/agreement.js +264 -0
- package/dist/channels.d.ts +49 -0
- package/dist/channels.js +395 -0
- package/dist/gate.d.ts +69 -0
- package/dist/gate.js +347 -0
- package/dist/index.d.ts +5 -0
- package/dist/index.js +4 -0
- package/dist/pairings/ack-payment-request.d.ts +1 -0
- package/dist/pairings/ack-payment-request.js +12 -0
- package/dist/pairings/acp-checkout-delegated.d.ts +2 -0
- package/dist/pairings/acp-checkout-delegated.js +28 -0
- package/dist/pairings/acp-checkout-undelegated.d.ts +1 -0
- package/dist/pairings/acp-checkout-undelegated.js +11 -0
- package/dist/pairings/ap2-checkout-mandate.d.ts +2 -0
- package/dist/pairings/ap2-checkout-mandate.js +23 -0
- package/dist/pairings/batch.d.ts +29 -0
- package/dist/pairings/batch.js +83 -0
- package/dist/pairings/card-mastercard-vi-autonomous.d.ts +1 -0
- package/dist/pairings/card-mastercard-vi-autonomous.js +3 -0
- package/dist/pairings/card-mastercard-vi-immediate.d.ts +1 -0
- package/dist/pairings/card-mastercard-vi-immediate.js +3 -0
- package/dist/pairings/card-seller-reference.d.ts +1 -0
- package/dist/pairings/card-seller-reference.js +3 -0
- package/dist/pairings/card-visa-tap.d.ts +1 -0
- package/dist/pairings/card-visa-tap.js +3 -0
- package/dist/pairings/card.d.ts +7 -0
- package/dist/pairings/card.js +68 -0
- package/dist/pairings/common.d.ts +54 -0
- package/dist/pairings/common.js +134 -0
- package/dist/pairings/evm-x402.d.ts +3 -0
- package/dist/pairings/evm-x402.js +49 -0
- package/dist/pairings/index.d.ts +3 -0
- package/dist/pairings/index.js +134 -0
- package/dist/pairings/lightning.d.ts +17 -0
- package/dist/pairings/lightning.js +112 -0
- package/dist/pairings/lnbtc-request.d.ts +24 -0
- package/dist/pairings/lnbtc-request.js +175 -0
- package/dist/pairings/mpp-charge-card.d.ts +1 -0
- package/dist/pairings/mpp-charge-card.js +3 -0
- package/dist/pairings/mpp-charge-evm-authorization.d.ts +1 -0
- package/dist/pairings/mpp-charge-evm-authorization.js +3 -0
- package/dist/pairings/mpp-charge-evm-hash.d.ts +1 -0
- package/dist/pairings/mpp-charge-evm-hash.js +3 -0
- package/dist/pairings/mpp-charge-evm-permit2.d.ts +1 -0
- package/dist/pairings/mpp-charge-evm-permit2.js +3 -0
- package/dist/pairings/mpp-charge-evm-transaction.d.ts +1 -0
- package/dist/pairings/mpp-charge-evm-transaction.js +3 -0
- package/dist/pairings/mpp-charge-hedera.d.ts +23 -0
- package/dist/pairings/mpp-charge-hedera.js +137 -0
- package/dist/pairings/mpp-charge-nearintents.d.ts +2 -0
- package/dist/pairings/mpp-charge-nearintents.js +19 -0
- package/dist/pairings/mpp-charge-solana.d.ts +1 -0
- package/dist/pairings/mpp-charge-solana.js +25 -0
- package/dist/pairings/mpp-charge-stellar.d.ts +1 -0
- package/dist/pairings/mpp-charge-stellar.js +16 -0
- package/dist/pairings/mpp-charge-stripe.d.ts +1 -0
- package/dist/pairings/mpp-charge-stripe.js +3 -0
- package/dist/pairings/mpp-charge-tempo-memo.d.ts +9 -0
- package/dist/pairings/mpp-charge-tempo-memo.js +10 -0
- package/dist/pairings/mpp-charge-tempo-push.d.ts +12 -0
- package/dist/pairings/mpp-charge-tempo-push.js +21 -0
- package/dist/pairings/mpp-charge-usdc-evm.d.ts +1 -0
- package/dist/pairings/mpp-charge-usdc-evm.js +6 -0
- package/dist/pairings/mpp-charge-usdc-gateway.d.ts +2 -0
- package/dist/pairings/mpp-charge-usdc-gateway.js +33 -0
- package/dist/pairings/mpp-charge-usdc-solana.d.ts +1 -0
- package/dist/pairings/mpp-charge-usdc-solana.js +25 -0
- package/dist/pairings/mpp-charge-usdc-stacks.d.ts +1 -0
- package/dist/pairings/mpp-charge-usdc-stacks.js +17 -0
- package/dist/pairings/mpp-charge-xrpl.d.ts +1 -0
- package/dist/pairings/mpp-charge-xrpl.js +20 -0
- package/dist/pairings/mpp-confirm-only.d.ts +2 -0
- package/dist/pairings/mpp-confirm-only.js +21 -0
- package/dist/pairings/mpp-rails.d.ts +48 -0
- package/dist/pairings/mpp-rails.js +71 -0
- package/dist/pairings/mpp-session-evm.d.ts +1 -0
- package/dist/pairings/mpp-session-evm.js +3 -0
- package/dist/pairings/mpp-session-hedera.d.ts +2 -0
- package/dist/pairings/mpp-session-hedera.js +41 -0
- package/dist/pairings/mpp-session-solana.d.ts +1 -0
- package/dist/pairings/mpp-session-solana.js +60 -0
- package/dist/pairings/mpp-session-tempo.d.ts +1 -0
- package/dist/pairings/mpp-session-tempo.js +3 -0
- package/dist/pairings/mpp-session-xrpl.d.ts +1 -0
- package/dist/pairings/mpp-session-xrpl.js +42 -0
- package/dist/pairings/mpp-session.d.ts +5 -0
- package/dist/pairings/mpp-session.js +65 -0
- package/dist/pairings/mpp-subscription-stripe.d.ts +1 -0
- package/dist/pairings/mpp-subscription-stripe.js +6 -0
- package/dist/pairings/mpp-subscription-tempo.d.ts +2 -0
- package/dist/pairings/mpp-subscription-tempo.js +2 -0
- package/dist/pairings/mpp.d.ts +43 -0
- package/dist/pairings/mpp.js +194 -0
- package/dist/pairings/protocol-groups.d.ts +17 -0
- package/dist/pairings/protocol-groups.js +27 -0
- package/dist/pairings/ucp-booking-ap2-mandate.d.ts +1 -0
- package/dist/pairings/ucp-booking-ap2-mandate.js +3 -0
- package/dist/pairings/ucp-booking-unsigned.d.ts +1 -0
- package/dist/pairings/ucp-booking-unsigned.js +3 -0
- package/dist/pairings/ucp-checkout-ap2-mandate.d.ts +1 -0
- package/dist/pairings/ucp-checkout-ap2-mandate.js +3 -0
- package/dist/pairings/ucp-checkout-unsigned.d.ts +1 -0
- package/dist/pairings/ucp-checkout-unsigned.js +3 -0
- package/dist/pairings/ucp.d.ts +5 -0
- package/dist/pairings/ucp.js +35 -0
- package/dist/pairings/x402-account-rails.d.ts +25 -0
- package/dist/pairings/x402-account-rails.js +52 -0
- package/dist/pairings/x402-auth-capture-eip155-eip3009.d.ts +1 -0
- package/dist/pairings/x402-auth-capture-eip155-eip3009.js +3 -0
- package/dist/pairings/x402-auth-capture-eip155-permit2.d.ts +1 -0
- package/dist/pairings/x402-auth-capture-eip155-permit2.js +3 -0
- package/dist/pairings/x402-batch-settlement-cloudflare.d.ts +2 -0
- package/dist/pairings/x402-batch-settlement-cloudflare.js +21 -0
- package/dist/pairings/x402-batch-settlement-eip155.d.ts +2 -0
- package/dist/pairings/x402-batch-settlement-eip155.js +32 -0
- package/dist/pairings/x402-batch-settlement-solana.d.ts +2 -0
- package/dist/pairings/x402-batch-settlement-solana.js +55 -0
- package/dist/pairings/x402-exact-algorand.d.ts +1 -0
- package/dist/pairings/x402-exact-algorand.js +37 -0
- package/dist/pairings/x402-exact-aptos.d.ts +1 -0
- package/dist/pairings/x402-exact-aptos.js +9 -0
- package/dist/pairings/x402-exact-cardano.d.ts +1 -0
- package/dist/pairings/x402-exact-cardano.js +7 -0
- package/dist/pairings/x402-exact-casper.d.ts +2 -0
- package/dist/pairings/x402-exact-casper.js +21 -0
- package/dist/pairings/x402-exact-ccd.d.ts +2 -0
- package/dist/pairings/x402-exact-ccd.js +20 -0
- package/dist/pairings/x402-exact-eip155-eip3009.d.ts +1 -0
- package/dist/pairings/x402-exact-eip155-eip3009.js +3 -0
- package/dist/pairings/x402-exact-eip155-erc7710-salt.d.ts +1 -0
- package/dist/pairings/x402-exact-eip155-erc7710-salt.js +3 -0
- package/dist/pairings/x402-exact-eip155-erc7710.d.ts +1 -0
- package/dist/pairings/x402-exact-eip155-erc7710.js +3 -0
- package/dist/pairings/x402-exact-eip155-permit2.d.ts +1 -0
- package/dist/pairings/x402-exact-eip155-permit2.js +3 -0
- package/dist/pairings/x402-exact-hedera-transfer-executor.d.ts +1 -0
- package/dist/pairings/x402-exact-hedera-transfer-executor.js +23 -0
- package/dist/pairings/x402-exact-hedera.d.ts +3 -0
- package/dist/pairings/x402-exact-hedera.js +46 -0
- package/dist/pairings/x402-exact-near.d.ts +2 -0
- package/dist/pairings/x402-exact-near.js +34 -0
- package/dist/pairings/x402-exact-polkadot-lcp-assets-remark.d.ts +2 -0
- package/dist/pairings/x402-exact-polkadot-lcp-assets-remark.js +20 -0
- package/dist/pairings/x402-exact-solana.d.ts +11 -0
- package/dist/pairings/x402-exact-solana.js +36 -0
- package/dist/pairings/x402-exact-starknet.d.ts +2 -0
- package/dist/pairings/x402-exact-starknet.js +20 -0
- package/dist/pairings/x402-exact-stellar.d.ts +1 -0
- package/dist/pairings/x402-exact-stellar.js +17 -0
- package/dist/pairings/x402-exact-sui.d.ts +1 -0
- package/dist/pairings/x402-exact-sui.js +10 -0
- package/dist/pairings/x402-exact-tron-lcp-trc20-memo.d.ts +2 -0
- package/dist/pairings/x402-exact-tron-lcp-trc20-memo.js +45 -0
- package/dist/pairings/x402-exact-tvm.d.ts +2 -0
- package/dist/pairings/x402-exact-tvm.js +35 -0
- package/dist/pairings/x402-exact-xrpl.d.ts +1 -0
- package/dist/pairings/x402-exact-xrpl.js +27 -0
- package/dist/pairings/x402-rail.d.ts +31 -0
- package/dist/pairings/x402-rail.js +65 -0
- package/dist/pairings/x402-upto-eip155-permit2.d.ts +1 -0
- package/dist/pairings/x402-upto-eip155-permit2.js +3 -0
- package/dist/pairings/x402-upto-solana.d.ts +1 -0
- package/dist/pairings/x402-upto-solana.js +42 -0
- package/dist/transact.d.ts +20 -0
- package/dist/transact.js +53 -0
- package/dist/types.d.ts +169 -0
- package/dist/types.js +2 -0
- package/package.json +64 -0
package/README.md
ADDED
|
@@ -0,0 +1,539 @@
|
|
|
1
|
+
# @integraledger/terms
|
|
2
|
+
|
|
3
|
+
The buyer gate for agents that pay: before your wallet signs anything, it confirms that the record a seller serves
|
|
4
|
+
hashes to the value the payment will carry, and builds the payment with that hash.
|
|
5
|
+
|
|
6
|
+
```sh
|
|
7
|
+
npm install @integraledger/terms @integraledger/lcp
|
|
8
|
+
```
|
|
9
|
+
|
|
10
|
+
## What it is
|
|
11
|
+
|
|
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.
|
|
15
|
+
|
|
16
|
+
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
|
+
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.
|
|
20
|
+
|
|
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
|
+
|
|
24
|
+
## Key concepts
|
|
25
|
+
|
|
26
|
+
- **Agentic Transaction Record (ATR):** the agreement's record, a JSON document the seller serves.
|
|
27
|
+
- **ATR hash (H):** SHA-256 over the ATR's exact bytes, `0x` and 64 hex digits. It is computed over the bytes as
|
|
28
|
+
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.
|
|
31
|
+
- **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.
|
|
35
|
+
- **Buyer gate:** this package: the buyer-side check that compares the served bytes with H before anything is signed.
|
|
36
|
+
- **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.
|
|
38
|
+
- **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.
|
|
40
|
+
|
|
41
|
+
## Install
|
|
42
|
+
|
|
43
|
+
```sh
|
|
44
|
+
npm install @integraledger/terms @integraledger/lcp
|
|
45
|
+
```
|
|
46
|
+
|
|
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.
|
|
51
|
+
|
|
52
|
+
## Quickstart
|
|
53
|
+
|
|
54
|
+
The seller answered with an x402 `402 Payment Required` whose `PAYMENT-REQUIRED` document advertises H and the link.
|
|
55
|
+
This example pays it with [viem](https://viem.sh) as the wallet. It uses the ATR, the document and the payer key of
|
|
56
|
+
the shared vectors, and a local stand-in for the network, so it runs offline and prints the same values every time.
|
|
57
|
+
|
|
58
|
+
```ts
|
|
59
|
+
import { transact, type Fetch, type Signer } from "@integraledger/terms";
|
|
60
|
+
import { exactEip3009, type Eip3009Payment } from "@integraledger/lcp/x402";
|
|
61
|
+
import { privateKeyToAccount } from "viem/accounts";
|
|
62
|
+
|
|
63
|
+
// The ATR, exactly as the seller's link serves it. The gate hashes these bytes and never parses them.
|
|
64
|
+
const atr = new TextEncoder().encode(
|
|
65
|
+
'{"atrVersion":"1","id":"0f8fad5b-d9cb-469f-a165-70867728950e","x402":{"z":1.0,"a":"caf\\u00e9"},"seller":{"note":"Café — 30 días ✓"}}',
|
|
66
|
+
);
|
|
67
|
+
const H = "0x8b1e122580ae3f6a8c3d36a24294e1260a87bde70f597279b973e39310072938";
|
|
68
|
+
const link = `https://atr.seller.example/${H}`;
|
|
69
|
+
|
|
70
|
+
// The seller's x402 payment request, advertising H and the link.
|
|
71
|
+
const offer = {
|
|
72
|
+
x402Version: 2,
|
|
73
|
+
resource: { url: "https://api.seller.example/v1/quote" },
|
|
74
|
+
accepts: [
|
|
75
|
+
{
|
|
76
|
+
scheme: "exact",
|
|
77
|
+
network: "eip155:84532",
|
|
78
|
+
amount: "10000",
|
|
79
|
+
asset: "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
|
|
80
|
+
payTo: "0x209693Bc6afc0C5328bA36FaF03C514EF312287C",
|
|
81
|
+
maxTimeoutSeconds: 60,
|
|
82
|
+
extra: { name: "USDC", version: "2" },
|
|
83
|
+
},
|
|
84
|
+
],
|
|
85
|
+
extensions: {
|
|
86
|
+
legalContext: { info: { type: "sha256", value: H, legalContextUrl: link }, schema: {} },
|
|
87
|
+
},
|
|
88
|
+
};
|
|
89
|
+
|
|
90
|
+
// A stand-in for the network: the link serves the ATR. In production, pass globalThis.fetch.
|
|
91
|
+
const fetch: Fetch = async (url) => (url === link ? new Response(atr) : new Response(null, { status: 404 }));
|
|
92
|
+
|
|
93
|
+
// The published Anvil development key. Never use it for real funds.
|
|
94
|
+
const wallet = privateKeyToAccount("0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80");
|
|
95
|
+
const signer: Signer = {
|
|
96
|
+
account: `eip155:84532:${wallet.address}`,
|
|
97
|
+
async sign(request) {
|
|
98
|
+
if (request.kind !== "eip712") throw new Error(`this wallet signs EIP-712 only, not ${request.kind}`);
|
|
99
|
+
return wallet.signTypedData(request.typedData as Parameters<typeof wallet.signTypedData>[0]);
|
|
100
|
+
},
|
|
101
|
+
};
|
|
102
|
+
|
|
103
|
+
const result = await transact(offer, exactEip3009, signer, fetch);
|
|
104
|
+
if ("decline" in result) throw new Error(`${result.decline.code}: ${result.decline.detail}`);
|
|
105
|
+
|
|
106
|
+
const payment = result.signed as Eip3009Payment;
|
|
107
|
+
console.log("H ", result.h);
|
|
108
|
+
console.log("signed nonce", payment.payload.authorization.nonce);
|
|
109
|
+
console.log("kept bytes ", result.bytes.length);
|
|
110
|
+
|
|
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));
|
|
113
|
+
console.log("header ", header.length > 0 ? "ready" : "empty");
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
```text output
|
|
117
|
+
H 0x8b1e122580ae3f6a8c3d36a24294e1260a87bde70f597279b973e39310072938
|
|
118
|
+
signed nonce 0x8b1e122580ae3f6a8c3d36a24294e1260a87bde70f597279b973e39310072938
|
|
119
|
+
kept bytes 138
|
|
120
|
+
header ready
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
The nonce your wallet signed is the hash of the 138 bytes the link served. Keep `result.bytes` with the payment: they
|
|
124
|
+
are your copy of the record.
|
|
125
|
+
|
|
126
|
+
If the link had served one byte more, less or different, `transact` would have returned
|
|
127
|
+
`{ decline: { code: "hash-mismatch", … } }` and never called the signer.
|
|
128
|
+
|
|
129
|
+
## How it works
|
|
130
|
+
|
|
131
|
+
```mermaid
|
|
132
|
+
sequenceDiagram
|
|
133
|
+
participant A as Your agent
|
|
134
|
+
participant G as Buyer gate
|
|
135
|
+
participant S as Seller
|
|
136
|
+
participant W as Your signer
|
|
137
|
+
A->>G: confirm(offer, binding, account, fetch)
|
|
138
|
+
G->>S: GET the link (https, no redirect, at most 1 MiB, 10 s)
|
|
139
|
+
S-->>G: The ATR's bytes
|
|
140
|
+
G->>G: SHA-256(bytes) equals H?
|
|
141
|
+
G-->>A: The signing request, built with H
|
|
142
|
+
A->>W: sign(request)
|
|
143
|
+
W-->>A: The signature
|
|
144
|
+
A->>G: finish(bytes, chosen, signature)
|
|
145
|
+
G-->>A: The payment, only when what was signed carries H
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
1. **Read.** The pairing's binding reads the seller's document: H, the link, and the payment options.
|
|
149
|
+
2. **Compare.** The gate fetches the link once and hashes the bytes it received. No match: a decline, and no signer
|
|
150
|
+
call.
|
|
151
|
+
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.
|
|
154
|
+
|
|
155
|
+
Every function returns a value, never throws for a protocol outcome: either its result, or
|
|
156
|
+
`{ decline: { code, detail } }`.
|
|
157
|
+
|
|
158
|
+
## Guides
|
|
159
|
+
|
|
160
|
+
### Pay in one call: `transact`
|
|
161
|
+
|
|
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:
|
|
164
|
+
|
|
165
|
+
| Member | What it is |
|
|
166
|
+
| --- | --- |
|
|
167
|
+
| `signed` | The payment to send, in the protocol's own form. `null` when the pairing gives the buyer nothing to sign. |
|
|
168
|
+
| `bytes` | The ATR's exact bytes: your copy of the record. |
|
|
169
|
+
| `h` | Their SHA-256. |
|
|
170
|
+
| `agreement` | The agreement's receipt, where an agreement was paid first. |
|
|
171
|
+
| `landed` | A landed receipt to keep beside the payment, for the few pairings that return one. |
|
|
172
|
+
|
|
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.
|
|
175
|
+
|
|
176
|
+
### Sign elsewhere: `confirm`, then `finish`
|
|
177
|
+
|
|
178
|
+
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:
|
|
180
|
+
|
|
181
|
+
```ts
|
|
182
|
+
import { confirm, finish, type Fetch } from "@integraledger/terms";
|
|
183
|
+
import { exactEip3009, type Eip3009Payment } from "@integraledger/lcp/x402";
|
|
184
|
+
import { privateKeyToAccount } from "viem/accounts";
|
|
185
|
+
|
|
186
|
+
const atr = new TextEncoder().encode(
|
|
187
|
+
'{"atrVersion":"1","id":"0f8fad5b-d9cb-469f-a165-70867728950e","x402":{"z":1.0,"a":"caf\\u00e9"},"seller":{"note":"Café — 30 días ✓"}}',
|
|
188
|
+
);
|
|
189
|
+
const H = "0x8b1e122580ae3f6a8c3d36a24294e1260a87bde70f597279b973e39310072938";
|
|
190
|
+
const link = `https://atr.seller.example/${H}`;
|
|
191
|
+
const offer = {
|
|
192
|
+
x402Version: 2,
|
|
193
|
+
resource: { url: "https://api.seller.example/v1/quote" },
|
|
194
|
+
accepts: [
|
|
195
|
+
{
|
|
196
|
+
scheme: "exact",
|
|
197
|
+
network: "eip155:84532",
|
|
198
|
+
amount: "10000",
|
|
199
|
+
asset: "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
|
|
200
|
+
payTo: "0x209693Bc6afc0C5328bA36FaF03C514EF312287C",
|
|
201
|
+
maxTimeoutSeconds: 60,
|
|
202
|
+
extra: { name: "USDC", version: "2" },
|
|
203
|
+
},
|
|
204
|
+
],
|
|
205
|
+
extensions: { legalContext: { info: { type: "sha256", value: H, legalContextUrl: link }, schema: {} } },
|
|
206
|
+
};
|
|
207
|
+
const fetch: Fetch = async (url) => (url === link ? new Response(atr) : new Response(null, { status: 404 }));
|
|
208
|
+
|
|
209
|
+
// 1. Compare, and build the request with H.
|
|
210
|
+
const confirmed = await confirm(offer, exactEip3009, "eip155:84532:0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266", fetch);
|
|
211
|
+
if ("decline" in confirmed) throw new Error(confirmed.decline.code);
|
|
212
|
+
if (confirmed.request === null || confirmed.request.kind !== "eip712") throw new Error("expected an EIP-712 request");
|
|
213
|
+
|
|
214
|
+
// What crosses to the signing side and back: plain JSON and the bytes.
|
|
215
|
+
const handOff = JSON.stringify({ chosen: confirmed.chosen, atr: Buffer.from(confirmed.bytes).toString("base64") });
|
|
216
|
+
|
|
217
|
+
// 2. Sign exactly the request, elsewhere. The published Anvil development key; never use it for real funds.
|
|
218
|
+
const wallet = privateKeyToAccount("0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80");
|
|
219
|
+
const signature = await wallet.signTypedData(
|
|
220
|
+
confirmed.request.typedData as Parameters<typeof wallet.signTypedData>[0],
|
|
221
|
+
);
|
|
222
|
+
|
|
223
|
+
// 3. Finish from what came back. finish recomputes H from the bytes; it trusts nothing it did not rebuild.
|
|
224
|
+
const back = JSON.parse(handOff);
|
|
225
|
+
const done = await finish(new Uint8Array(Buffer.from(back.atr, "base64")), back.chosen, signature, exactEip3009);
|
|
226
|
+
if ("decline" in done) throw new Error(done.decline.code);
|
|
227
|
+
if ("next" in done) throw new Error("this pairing signs in one step");
|
|
228
|
+
|
|
229
|
+
console.log("nonce is H:", (done.signed as Eip3009Payment).payload.authorization.nonce === H);
|
|
230
|
+
```
|
|
231
|
+
|
|
232
|
+
```text output
|
|
233
|
+
nonce is H: true
|
|
234
|
+
```
|
|
235
|
+
|
|
236
|
+
A pairing signed in two steps (a channel funding, then its first voucher) makes `finish` return `{ next, h }`: sign
|
|
237
|
+
`next` and call `finish` again with every answer so far, in order, as a list. `transact` does this for you.
|
|
238
|
+
|
|
239
|
+
### Pay the agreement first
|
|
240
|
+
|
|
241
|
+
Some payments are not a public proof of H: a card charge, a Stripe payment, a Lightning invoice, a checkout in which
|
|
242
|
+
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:
|
|
245
|
+
|
|
246
|
+
```json
|
|
247
|
+
{
|
|
248
|
+
"atrHash": "0x8b1e122580ae3f6a8c3d36a24294e1260a87bde70f597279b973e39310072938",
|
|
249
|
+
"agreed": true,
|
|
250
|
+
"network": "eip155:84532",
|
|
251
|
+
"transaction": "0xabababababababababababababababababababababababababababababababab"
|
|
252
|
+
}
|
|
253
|
+
```
|
|
254
|
+
|
|
255
|
+
- The agreement URL's `402` must advertise the same H, or nothing is signed (`hash-mismatch`).
|
|
256
|
+
- 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.
|
|
258
|
+
- 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.
|
|
260
|
+
|
|
261
|
+
### Channels and sessions
|
|
262
|
+
|
|
263
|
+
In an x402 batch-settlement channel or an MPP session, one ATR covers the whole channel. The gate compares it once, at
|
|
264
|
+
the opening; you keep a **hold** and sign every later voucher from it:
|
|
265
|
+
|
|
266
|
+
```ts
|
|
267
|
+
import { openChannel, recordCharge, transact, within, type Fetch, type Signature, type Signer, type SigningRequest } from "@integraledger/terms";
|
|
268
|
+
import { batchEvm } from "@integraledger/lcp/x402-batch-settlement";
|
|
269
|
+
import { privateKeyToAccount } from "viem/accounts";
|
|
270
|
+
|
|
271
|
+
const atr = new TextEncoder().encode(
|
|
272
|
+
'{"atrVersion":"1","id":"0f8fad5b-d9cb-469f-a165-70867728950e","x402":{"z":1.0,"a":"caf\\u00e9"},"seller":{"note":"Café — 30 días ✓"}}',
|
|
273
|
+
);
|
|
274
|
+
const H = "0x8b1e122580ae3f6a8c3d36a24294e1260a87bde70f597279b973e39310072938";
|
|
275
|
+
const link = `https://atr.seller.example/${H}`;
|
|
276
|
+
|
|
277
|
+
// The seller's batch-settlement offer: 1000 units per request, into a channel.
|
|
278
|
+
const offer = {
|
|
279
|
+
x402Version: 2,
|
|
280
|
+
resource: { url: "https://api.seller.example/v1/quote" },
|
|
281
|
+
accepts: [
|
|
282
|
+
{
|
|
283
|
+
scheme: "batch-settlement",
|
|
284
|
+
network: "eip155:84532",
|
|
285
|
+
amount: "1000",
|
|
286
|
+
asset: "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
|
|
287
|
+
payTo: "0x209693Bc6afc0C5328bA36FaF03C514EF312287C",
|
|
288
|
+
maxTimeoutSeconds: 3600,
|
|
289
|
+
extra: { receiverAuthorizer: "0x90F79bf6EB2c4f870365E785982E1f101E93b906", withdrawDelay: 900, name: "USDC", version: "2" },
|
|
290
|
+
},
|
|
291
|
+
],
|
|
292
|
+
extensions: { legalContext: { info: { type: "sha256", value: H, legalContextUrl: link }, schema: {} } },
|
|
293
|
+
};
|
|
294
|
+
const fetch: Fetch = async (url) => (url === link ? new Response(atr) : new Response(null, { status: 404 }));
|
|
295
|
+
|
|
296
|
+
// Anvil development keys: the payer funds the channel, the payer authorizer signs vouchers. Never use them for real funds.
|
|
297
|
+
const payer = privateKeyToAccount("0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80");
|
|
298
|
+
const authorizer = privateKeyToAccount("0x59c6995e998f97a5a0044966f0945389dc9e86dae88c7a8412f4603b6b78690d");
|
|
299
|
+
type TypedData = Parameters<typeof payer.signTypedData>[0];
|
|
300
|
+
const signer: Signer = {
|
|
301
|
+
account: `eip155:84532:${payer.address}`,
|
|
302
|
+
async sign(request: SigningRequest): Promise<Signature> {
|
|
303
|
+
if (request.kind !== "batch") throw new Error(`unexpected ${request.kind}`);
|
|
304
|
+
const answers: Signature[] = [];
|
|
305
|
+
for (const each of request.requests) {
|
|
306
|
+
const typedData = (each as { typedData: TypedData }).typedData;
|
|
307
|
+
const key = typedData.primaryType === "Voucher" ? authorizer : payer;
|
|
308
|
+
answers.push(await key.signTypedData(typedData));
|
|
309
|
+
}
|
|
310
|
+
return answers;
|
|
311
|
+
},
|
|
312
|
+
};
|
|
313
|
+
|
|
314
|
+
// Open: compare the ATR once, sign the deposit and the first voucher.
|
|
315
|
+
const opened = await transact(offer, batchEvm, signer, fetch, {
|
|
316
|
+
inputs: { payerAuthorizer: authorizer.address, deposit: "100000" },
|
|
317
|
+
});
|
|
318
|
+
if ("decline" in opened || opened.signed === null) throw new Error("the channel did not open");
|
|
319
|
+
let hold = await openChannel(opened.bytes, opened.signed, batchEvm);
|
|
320
|
+
if ("decline" in hold) throw new Error(hold.decline.code);
|
|
321
|
+
console.log("channel ", hold.channel);
|
|
322
|
+
|
|
323
|
+
// Each later request: the seller's new offer must advertise the held H.
|
|
324
|
+
for (const charged of ["1000", "2000"]) {
|
|
325
|
+
const next = await within(offer, hold, batchEvm, signer);
|
|
326
|
+
if ("decline" in next) throw new Error(next.decline.code);
|
|
327
|
+
console.log("voucher up to", next.hold.signedMax);
|
|
328
|
+
// The seller reports its cumulative charge; it may not exceed what was signed.
|
|
329
|
+
const recorded = recordCharge(next.hold, charged);
|
|
330
|
+
if ("decline" in recorded) throw new Error(recorded.decline.code);
|
|
331
|
+
hold = recorded;
|
|
332
|
+
}
|
|
333
|
+
```
|
|
334
|
+
|
|
335
|
+
```text output
|
|
336
|
+
channel 0x9c2d7031768ecb3fe688ae307c45f2e3a3d98b0d9ce1a6afcd27131fabb67e56
|
|
337
|
+
voucher up to 1000
|
|
338
|
+
voucher up to 2000
|
|
339
|
+
```
|
|
340
|
+
|
|
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.
|
|
343
|
+
|
|
344
|
+
### Confirm a payment later: `check`
|
|
345
|
+
|
|
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.
|
|
348
|
+
|
|
349
|
+
### Declines and `moved`
|
|
350
|
+
|
|
351
|
+
A decline is `{ decline: { code, detail } }`. `code` is one of twelve values; `detail` is a sentence or the protocol
|
|
352
|
+
package's refusal code. Where your signer moved the payment itself before the gate declined (a Lightning node paid the
|
|
353
|
+
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.
|
|
355
|
+
|
|
356
|
+
| Code | Meaning |
|
|
357
|
+
| --- | --- |
|
|
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. |
|
|
359
|
+
| `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. |
|
|
361
|
+
| `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). |
|
|
363
|
+
| `atr-too-large` | The ATR is larger than 1 MiB (1,048,576 bytes). |
|
|
364
|
+
| `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
|
+
| `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. |
|
|
367
|
+
| `agreement-not-offered` | The pairing's payment is not a public proof, and the offer names no agreement URL. |
|
|
368
|
+
| `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. |
|
|
370
|
+
|
|
371
|
+
## API reference
|
|
372
|
+
|
|
373
|
+
Everything below is exported from `@integraledger/terms`.
|
|
374
|
+
|
|
375
|
+
### Functions
|
|
376
|
+
|
|
377
|
+
| Export | Signature | What it does |
|
|
378
|
+
| --- | --- | --- |
|
|
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. |
|
|
382
|
+
| `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. |
|
|
384
|
+
| `openChannel` | `(bytes, opened, binding, landed?) => Promise<ChannelHold \| Declined>` | Hold a channel opened for the compared ATR. |
|
|
385
|
+
| `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
|
+
| `recordCharge` | `(hold, chargedCumulativeAmount) => ChannelHold \| Declined` | Record the seller's cumulative charge, between the last recorded and the most signed. |
|
|
387
|
+
|
|
388
|
+
### Types
|
|
389
|
+
|
|
390
|
+
| Export | What it is |
|
|
391
|
+
| --- | --- |
|
|
392
|
+
| `Binding` | A pairing's binding from `@integraledger/lcp`. |
|
|
393
|
+
| `Signer` | `{ account: string; sign(request: SigningRequest): Promise<Signature> }`. `account` is CAIP-10. |
|
|
394
|
+
| `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. |
|
|
396
|
+
| `Fetch` | WHATWG `fetch`, or anything with its call shape. |
|
|
397
|
+
| `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 }`. |
|
|
400
|
+
| `Presented` | A payment in its protocol's form. |
|
|
401
|
+
| `AgreementReceipt` | `{ atrHash, agreed: true, network, transaction }`. |
|
|
402
|
+
| `ChannelHold` | `{ pairing, network, channel, h, atr, opening, charged, signedMax }`, all JSON. |
|
|
403
|
+
| `Declined` | `{ decline: Reason; moved?: { signed, bytes, h } }`. |
|
|
404
|
+
| `Reason` | `{ code: DeclineCode; detail: string }`. |
|
|
405
|
+
| `DeclineCode` | The twelve codes in the table above. |
|
|
406
|
+
|
|
407
|
+
The full reference, with every request kind and the answer it takes, is in the
|
|
408
|
+
[documentation](https://github.com/IntegraLedger/integra-agentic-terms/tree/main/docs).
|
|
409
|
+
|
|
410
|
+
## Supported pairings
|
|
411
|
+
|
|
412
|
+
Generated from `@integraledger/lcp`'s `BINDINGS` and the gate's own registry. "Agreement payment first" marks the
|
|
413
|
+
pairings whose payment is not itself a public proof of H. The
|
|
414
|
+
[pairings reference](https://github.com/IntegraLedger/integra-agentic-terms/blob/main/docs/reference/pairings.md) adds
|
|
415
|
+
what each payment proves, and the [rails guide](https://github.com/IntegraLedger/integra-agentic-terms/blob/main/docs/guides/rails.md)
|
|
416
|
+
the inputs each build reads.
|
|
417
|
+
|
|
418
|
+
<!-- pairings:typescript:start -->
|
|
419
|
+
| Rail | Pairing | Binding export | Buyer signs H | Agreement payment first |
|
|
420
|
+
| --- | --- | --- | --- | --- |
|
|
421
|
+
| EVM | `mpp/charge/evm/authorization` | `evmAuthorization` from `@integraledger/lcp/mpp` | yes | no |
|
|
422
|
+
| EVM | `mpp/charge/evm/hash` | `evmHash` from `@integraledger/lcp/mpp` | no | yes |
|
|
423
|
+
| EVM | `mpp/charge/evm/permit2` | `evmPermit2` from `@integraledger/lcp/mpp` | yes | no |
|
|
424
|
+
| EVM | `mpp/charge/evm/transaction` | `evmTransaction` from `@integraledger/lcp/mpp` | no | yes |
|
|
425
|
+
| EVM | `mpp/charge/usdc/evm` | `chargeUsdcEvm` from `@integraledger/lcp/mpp` | yes | no |
|
|
426
|
+
| EVM | `mpp/charge/usdc/gateway` | `chargeUsdcGateway` from `@integraledger/lcp/mpp` | yes | no |
|
|
427
|
+
| EVM | `mpp/session/evm` | `sessionEvm` from `@integraledger/lcp/mpp` | yes | no |
|
|
428
|
+
| EVM | `x402/auth-capture/eip155/eip3009` | `authCaptureEip3009` from `@integraledger/lcp/x402` | yes | no |
|
|
429
|
+
| EVM | `x402/auth-capture/eip155/permit2` | `authCapturePermit2` from `@integraledger/lcp/x402` | yes | no |
|
|
430
|
+
| EVM | `x402/batch-settlement/eip155` | `batchEvm` from `@integraledger/lcp/x402-batch-settlement` | yes | no |
|
|
431
|
+
| EVM | `x402/exact/eip155/eip3009` | `exactEip3009` from `@integraledger/lcp/x402` | yes | no |
|
|
432
|
+
| EVM | `x402/exact/eip155/erc7710` | `exactErc7710` from `@integraledger/lcp/x402` | no | yes |
|
|
433
|
+
| EVM | `x402/exact/eip155/erc7710-salt` | `exactErc7710Salt` from `@integraledger/lcp/x402` | yes | no |
|
|
434
|
+
| EVM | `x402/exact/eip155/permit2` | `exactPermit2` from `@integraledger/lcp/x402` | yes | no |
|
|
435
|
+
| EVM | `x402/upto/eip155/permit2` | `uptoPermit2` from `@integraledger/lcp/x402` | yes | no |
|
|
436
|
+
| Tempo | `mpp/charge/tempo/memo` | `tempoMemo` from `@integraledger/lcp/mpp` | no | no |
|
|
437
|
+
| Tempo | `mpp/charge/tempo/push` | `tempoPush` from `@integraledger/lcp/mpp` | no | no |
|
|
438
|
+
| Tempo | `mpp/session/tempo` | `sessionTempo` from `@integraledger/lcp/mpp` | yes | no |
|
|
439
|
+
| Tempo | `mpp/subscription/tempo` | `subscriptionTempo` from `@integraledger/lcp/mpp` | yes | no |
|
|
440
|
+
| Solana | `mpp/charge/solana` | `chargeSolana` from `@integraledger/lcp/mpp` | yes | no |
|
|
441
|
+
| Solana | `mpp/charge/usdc/solana` | `chargeUsdcSolana` from `@integraledger/lcp/mpp` | yes | no |
|
|
442
|
+
| Solana | `mpp/session/solana` | `sessionSolana` from `@integraledger/lcp/mpp` | no | no |
|
|
443
|
+
| Solana | `x402/batch-settlement/solana` | `batchSvm` from `@integraledger/lcp/x402-batch-settlement` | yes | no |
|
|
444
|
+
| Solana | `x402/exact/solana` | `exactSvm` from `@integraledger/lcp/x402-exact-solana` | yes | no |
|
|
445
|
+
| Solana | `x402/upto/solana` | `uptoSvm` from `@integraledger/lcp/x402-upto-solana` | yes | no |
|
|
446
|
+
| Stellar | `mpp/charge/stellar` | `chargeStellar` from `@integraledger/lcp/mpp` | no | no |
|
|
447
|
+
| Stellar | `x402/exact/stellar` | `exactStellar` from `@integraledger/lcp/x402-exact-stellar` | no | no |
|
|
448
|
+
| XRP Ledger | `mpp/charge/xrpl` | `chargeXrpl` from `@integraledger/lcp/mpp` | yes | no |
|
|
449
|
+
| XRP Ledger | `mpp/session/xrpl` | `sessionXrpl` from `@integraledger/lcp/mpp` | yes | no |
|
|
450
|
+
| XRP Ledger | `x402/exact/xrpl` | `exactXrpl` from `@integraledger/lcp/x402-exact-xrpl` | yes | no |
|
|
451
|
+
| Hedera | `mpp/charge/hedera` | `chargeHedera` from `@integraledger/lcp/hedera` | no | no |
|
|
452
|
+
| Hedera | `mpp/session/hedera` | `sessionHedera` from `@integraledger/lcp/mpp` | yes | no |
|
|
453
|
+
| Hedera | `x402/exact/hedera` | `exactHedera` from `@integraledger/lcp/hedera` | yes | no |
|
|
454
|
+
| Hedera | `x402/exact/hedera/transfer-executor` | `exactHederaExecutor` from `@integraledger/lcp/hedera` | no | yes |
|
|
455
|
+
| Algorand | `x402/exact/algorand` | `exactAvm` from `@integraledger/lcp/avm` | yes | no |
|
|
456
|
+
| Aptos | `x402/exact/aptos` | `exactAptos` from `@integraledger/lcp/aptos` | no | yes |
|
|
457
|
+
| Sui | `x402/exact/sui` | `exactSui` from `@integraledger/lcp/sui` | yes | no |
|
|
458
|
+
| NEAR | `mpp/charge/nearintents` | `chargeNearIntents` from `@integraledger/lcp/mpp` | no | yes |
|
|
459
|
+
| NEAR | `x402/exact/near` | `exactNear` from `@integraledger/lcp/near` | yes | no |
|
|
460
|
+
| Starknet | `x402/exact/starknet` | `exactStarknet` from `@integraledger/lcp/starknet` | yes | no |
|
|
461
|
+
| Polkadot | `x402/exact/polkadot/lcp-assets-remark` | `exactPolkadotRemark` from `@integraledger/lcp/polkadot` | yes | no |
|
|
462
|
+
| TRON | `x402/exact/tron/lcp-trc20-memo` | `exactTronMemo` from `@integraledger/lcp/tron` | yes | no |
|
|
463
|
+
| TON | `x402/exact/tvm` | `exactTvm` from `@integraledger/lcp/tvm` | yes | no |
|
|
464
|
+
| Cardano | `x402/exact/cardano` | `exactCardano` from `@integraledger/lcp/cardano` | yes | no |
|
|
465
|
+
| Casper | `x402/exact/casper` | `exactCasper` from `@integraledger/lcp/casper` | yes | no |
|
|
466
|
+
| Concordium | `x402/exact/ccd` | `exactCcd` from `@integraledger/lcp/ccd` | yes | no |
|
|
467
|
+
| Stacks | `mpp/charge/usdc/stacks` | `chargeUsdcStacks` from `@integraledger/lcp/mpp` | yes | no |
|
|
468
|
+
| Lightning | `mpp/charge/lightning` | `chargeLightning` from `@integraledger/lcp/lightning` | no | yes |
|
|
469
|
+
| Lightning | `mpp/session/lightning` | `sessionLightning` from `@integraledger/lcp/lightning` | no | yes |
|
|
470
|
+
| Lightning | `x402/exact/lnbtc` | `exactLnbtc` from `@integraledger/lcp/lightning` | no | yes |
|
|
471
|
+
| Lightning | `x402/exact/lnbtc/invoice-named` | `exactLnbtcNamed` from `@integraledger/lcp/lightning` | no | yes |
|
|
472
|
+
| Cloudflare | `x402/batch-settlement/cloudflare` | `batchCloudflare` from `@integraledger/lcp/x402-batch-settlement` | yes | yes |
|
|
473
|
+
| Card | `card/mastercard-vi/autonomous` | `viAutonomous` from `@integraledger/lcp/card` | yes | yes |
|
|
474
|
+
| Card | `card/mastercard-vi/immediate` | `viImmediate` from `@integraledger/lcp/card` | yes | yes |
|
|
475
|
+
| Card | `card/seller-reference` | `sellerReference` from `@integraledger/lcp/card` | no | yes |
|
|
476
|
+
| Card | `card/visa-tap` | `visaTap` from `@integraledger/lcp/card` | yes | yes |
|
|
477
|
+
| Card | `mpp/charge/card` | `chargeCard` from `@integraledger/lcp/mpp` | no | yes |
|
|
478
|
+
| Stripe | `mpp/charge/stripe` | `chargeStripe` from `@integraledger/lcp/mpp` | no | yes |
|
|
479
|
+
| Stripe | `mpp/subscription/stripe` | `subscriptionStripe` from `@integraledger/lcp/mpp` | no | yes |
|
|
480
|
+
| Mandate | `ap2/checkout-mandate` | `checkoutMandate` from `@integraledger/lcp/ap2` | yes | yes |
|
|
481
|
+
| Mandate | `ucp/booking/ap2-mandate` | `bookingAp2Mandate` from `@integraledger/lcp/ucp` | yes | yes |
|
|
482
|
+
| Mandate | `ucp/checkout/ap2-mandate` | `ap2Mandate` from `@integraledger/lcp/ucp` | yes | yes |
|
|
483
|
+
| Checkout | `ack/payment-request` | `paymentRequest` from `@integraledger/lcp/ack` | no | yes |
|
|
484
|
+
| Checkout | `acp/checkout/delegated` | `delegated` from `@integraledger/lcp/acp` | no | yes |
|
|
485
|
+
| Checkout | `acp/checkout/undelegated` | `undelegated` from `@integraledger/lcp/acp` | no | yes |
|
|
486
|
+
| Checkout | `ucp/booking/unsigned` | `bookingUnsigned` from `@integraledger/lcp/ucp` | no | yes |
|
|
487
|
+
| Checkout | `ucp/checkout/unsigned` | `unsigned` from `@integraledger/lcp/ucp` | no | yes |
|
|
488
|
+
<!-- pairings:typescript:end -->
|
|
489
|
+
|
|
490
|
+
## Security model
|
|
491
|
+
|
|
492
|
+
What the gate guarantees, in the code:
|
|
493
|
+
|
|
494
|
+
- **Nothing is signed before the comparison.** The signer is called only after SHA-256 of the served bytes equals the
|
|
495
|
+
advertised H, compared as 32 decoded bytes.
|
|
496
|
+
- **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.
|
|
500
|
+
- **One bounded fetch.** One `GET` of an `https` link, no redirect, one 10-second deadline over headers and body, at most
|
|
501
|
+
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.
|
|
503
|
+
- **No keys.** The gate hands requests to your signer and holds nothing that could sign.
|
|
504
|
+
- **Your network policy.** Every request goes through the `fetch` you pass.
|
|
505
|
+
|
|
506
|
+
What it does not do:
|
|
507
|
+
|
|
508
|
+
- 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.
|
|
510
|
+
- It carries no business or legal logic.
|
|
511
|
+
- It does not store the ATR, talk to a facilitator, or settle a payment.
|
|
512
|
+
|
|
513
|
+
A seller's statement of what each pairing's payment proves is its binding's `pattern.proves`, in
|
|
514
|
+
`@integraledger/lcp`.
|
|
515
|
+
|
|
516
|
+
## Test vectors and conformance
|
|
517
|
+
|
|
518
|
+
The rules are fixed by the shared vectors that `@integraledger/lcp` ships in its `vectors/` directory: the buyer rows
|
|
519
|
+
of `buyer.json` (the hash, a record changed by one byte, the fetch bounds, the agreement exchange) and each pairing's
|
|
520
|
+
file (the request it builds and the payment it completes). This package's tests run every one, and the Python gate runs
|
|
521
|
+
the same files, so both languages compute the same hashes, build the same requests and give the same declines.
|
|
522
|
+
|
|
523
|
+
## Requirements
|
|
524
|
+
|
|
525
|
+
- Node.js `>=26.10.0`.
|
|
526
|
+
- An HTTP client with WHATWG `fetch`'s call shape (Node's global `fetch` is one).
|
|
527
|
+
- Cloudflare Workers, with or without the `nodejs_compat` flag: pass the Worker's own `fetch`, and install
|
|
528
|
+
`@integraledger/lcp`'s optional peer dependencies before bundling. See
|
|
529
|
+
[In a Cloudflare Worker](https://github.com/IntegraLedger/integra-agentic-terms/blob/main/docs/guides/pay-with-the-gate.md#in-a-cloudflare-worker).
|
|
530
|
+
- A signer for the pairings you pay.
|
|
531
|
+
|
|
532
|
+
## Contributing
|
|
533
|
+
|
|
534
|
+
See the [repository README](https://github.com/IntegraLedger/integra-agentic-terms#readme) and
|
|
535
|
+
[CONTRIBUTING.md](https://github.com/IntegraLedger/integra-agentic-terms/blob/main/CONTRIBUTING.md).
|
|
536
|
+
|
|
537
|
+
## License
|
|
538
|
+
|
|
539
|
+
[Apache-2.0](https://github.com/IntegraLedger/integra-agentic-terms/blob/main/agentic-terms/LICENSE)
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
/**
|
|
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`.
|
|
9
|
+
*/
|
|
10
|
+
import { type AtrHash } from "@integraledger/lcp";
|
|
11
|
+
import type { AgreementReceipt, Declined, Fetch, Inputs, Signer } from "./types.js";
|
|
12
|
+
/**
|
|
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.
|
|
16
|
+
*/
|
|
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<{
|
|
22
|
+
receipt: AgreementReceipt;
|
|
23
|
+
} | Declined>;
|