@integraledger/terms 0.1.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (51) hide show
  1. package/README.md +135 -65
  2. package/dist/agreement.d.ts +21 -17
  3. package/dist/agreement.js +279 -85
  4. package/dist/channels.d.ts +35 -12
  5. package/dist/channels.js +152 -70
  6. package/dist/gate.d.ts +41 -18
  7. package/dist/gate.js +81 -47
  8. package/dist/index.d.ts +1 -1
  9. package/dist/pairings/batch.d.ts +2 -5
  10. package/dist/pairings/batch.js +3 -13
  11. package/dist/pairings/card.js +0 -2
  12. package/dist/pairings/common.d.ts +7 -1
  13. package/dist/pairings/common.js +17 -2
  14. package/dist/pairings/evm-x402.js +3 -3
  15. package/dist/pairings/lightning.js +1 -1
  16. package/dist/pairings/lnbtc-request.d.ts +1 -1
  17. package/dist/pairings/lnbtc-request.js +1 -1
  18. package/dist/pairings/mpp-charge-hedera.d.ts +7 -7
  19. package/dist/pairings/mpp-charge-hedera.js +1 -1
  20. package/dist/pairings/mpp-charge-stellar.js +1 -1
  21. package/dist/pairings/mpp-charge-tempo-memo.d.ts +1 -9
  22. package/dist/pairings/mpp-charge-tempo-memo.js +3 -7
  23. package/dist/pairings/mpp-charge-tempo-push.d.ts +0 -1
  24. package/dist/pairings/mpp-charge-tempo-push.js +2 -10
  25. package/dist/pairings/mpp-charge-xrpl.js +3 -3
  26. package/dist/pairings/mpp-rails.d.ts +1 -1
  27. package/dist/pairings/mpp-session-solana.js +2 -2
  28. package/dist/pairings/mpp-session-xrpl.js +3 -4
  29. package/dist/pairings/mpp-session.js +1 -1
  30. package/dist/pairings/mpp.d.ts +12 -16
  31. package/dist/pairings/mpp.js +32 -109
  32. package/dist/pairings/protocol-groups.d.ts +1 -1
  33. package/dist/pairings/x402-account-rails.d.ts +1 -1
  34. package/dist/pairings/x402-batch-settlement-eip155.js +1 -1
  35. package/dist/pairings/x402-batch-settlement-solana.d.ts +2 -0
  36. package/dist/pairings/x402-batch-settlement-solana.js +3 -2
  37. package/dist/pairings/x402-exact-casper.js +3 -3
  38. package/dist/pairings/x402-exact-ccd.js +3 -3
  39. package/dist/pairings/x402-exact-hedera.d.ts +4 -1
  40. package/dist/pairings/x402-exact-hedera.js +5 -2
  41. package/dist/pairings/x402-exact-solana.d.ts +4 -4
  42. package/dist/pairings/x402-exact-solana.js +3 -2
  43. package/dist/pairings/x402-exact-stellar.js +1 -1
  44. package/dist/pairings/x402-exact-sui.js +3 -1
  45. package/dist/pairings/x402-exact-tvm.js +10 -2
  46. package/dist/pairings/x402-exact-xrpl.js +2 -4
  47. package/dist/pairings/x402-rail.d.ts +1 -1
  48. package/dist/transact.d.ts +14 -9
  49. package/dist/transact.js +30 -24
  50. package/dist/types.d.ts +43 -18
  51. package/package.json +11 -12
@@ -2,20 +2,27 @@
2
2
  * The buyer pieces shared by MPP's pairings: the first challenge, in document order, that offers the pairing on the
3
3
  * signer's chain; the build's request exactly as built; and the credential the signer's answer completes.
4
4
  */
5
- import type { AtrHash, Refusal } from "@integraledger/lcp";
6
- import { type MppChallenge, type MppUnsigned } from "@integraledger/lcp/mpp";
5
+ import type { Json, Refusal } from "@integraledger/lcp/core";
6
+ import { type MppChallenge } from "@integraledger/lcp/mpp";
7
7
  import type { BuyerPiece, Choose, Chosen, Presented, Signature, SigningRequest } from "../types.js";
8
8
  import { inputsOf } from "./common.js";
9
9
  type Spec = Parameters<typeof inputsOf>[2];
10
- /** The request a challenge carries, decoded from base64url JSON, or undefined. */
10
+ /** The request a challenge carries, read by `decodeObject`, or undefined. */
11
11
  export declare function requestOf(c: MppChallenge): Record<string, unknown> | undefined;
12
+ /**
13
+ * The JSON object a base64url value holds, read as the protocol package reads an MPP challenge's `request` and
14
+ * `opaque`: base64url without padding, its final character's unused bits zero, at most 8 KiB decoded; UTF-8 whose
15
+ * leading byte order mark is kept as a character; one JSON object, nested at most 16 levels deep, that has an RFC 8785
16
+ * form. Undefined for anything else.
17
+ */
18
+ export declare function decodeObject(s: unknown): Record<string, Json> | undefined;
12
19
  /** Whether a placed challenge offers the pairing, by the protocol package's `pairingsOfPlaced`. */
13
20
  export declare function offers(c: MppChallenge, pairing: string): boolean;
14
21
  /**
15
22
  * The first challenge offering `pairing` on the account's EVM network, as MPP's `network` reads it, with the choice
16
23
  * MPP's build takes: the challenge, `from`, `now`, and the buyer's own inputs named in `spec`.
17
24
  */
18
- export declare function mppChoose(pairing: string, spec: Spec, accept?: (c: MppChallenge) => Refusal | null): Choose;
25
+ export declare function mppChoose(pairing: string, spec: Spec): Choose;
19
26
  /** The choice as MPP's build takes it, with `deposit` as a bigint where the choice carries one. */
20
27
  export declare function mppChoice(chosen: Chosen): unknown;
21
28
  /** The build's request, exactly as built. */
@@ -23,18 +30,7 @@ export declare function mppRequest(unsigned: unknown): SigningRequest | Refusal;
23
30
  /** The credential for a one-value answer: a signature, a signed transaction or a transaction hash, as `0x` hex. */
24
31
  export declare function mppComplete(unsigned: unknown, signature: Signature): Promise<Presented | Refusal>;
25
32
  /** A buyer piece for an MPP charge pairing whose answer is one value. */
26
- export declare function mppChargePiece(pairing: string, spec: Spec, accept?: (c: MppChallenge) => Refusal | null): BuyerPiece;
27
- /** Accepts a Tempo challenge whose splits are well formed and leave the primary recipient more than zero. */
28
- export declare function acceptSplits(c: MppChallenge): Refusal | null;
29
- type TempoBinding = {
30
- build(choice: never, h: AtrHash): Promise<MppUnsigned | Refusal>;
31
- };
32
- /**
33
- * A Tempo charge's build. Without splits it is the binding's own `tempo-call`. With splits it is `tempo-calls`: the
34
- * binding's primary call, carrying its attribution memo, for `amount` less the splits, then one call per split in
35
- * array order, `transferWithMemo` where the split names a memo and `transfer` otherwise, all on `currency`.
36
- */
37
- export declare function tempoBuild(binding: TempoBinding): NonNullable<BuyerPiece["build"]>;
33
+ export declare function mppChargePiece(pairing: string, spec: Spec): BuyerPiece;
38
34
  /**
39
35
  * The credential for a pushed Tempo transfer: the answer is `{hash, landed?: {transaction, blockNumber, logs}}`, the
40
36
  * hash the signer broadcast and, where the signer gives it, its landed receipt, which carries the memo `bound` reads.
@@ -1,23 +1,42 @@
1
- import { parseJson } from "@integraledger/lcp";
1
+ import { base64UrlBytes, canonicalJson, parseJson } from "@integraledger/lcp/core";
2
2
  import { network, pairingsOfPlaced } from "@integraledger/lcp/mpp";
3
- import { memoCalldata } from "@integraledger/lcp/tempo";
4
3
  import { accountOf, bigintOf, broadcasts, choiceOf, inputsOf, isObject, isRefusal, refuse } from "./common.js";
5
4
  const EVM_ADDRESS = /^0x[0-9a-fA-F]{40}$/;
6
- /** The request a challenge carries, decoded from base64url JSON, or undefined. */
5
+ const MAX_DECODED = 8192;
6
+ const MAX_JSON_DEPTH = 16;
7
+ /** The request a challenge carries, read by `decodeObject`, or undefined. */
7
8
  export function requestOf(c) {
8
- if (typeof c.request !== "string")
9
+ return isObject(c) ? decodeObject(c["request"]) : undefined;
10
+ }
11
+ /**
12
+ * The JSON object a base64url value holds, read as the protocol package reads an MPP challenge's `request` and
13
+ * `opaque`: base64url without padding, its final character's unused bits zero, at most 8 KiB decoded; UTF-8 whose
14
+ * leading byte order mark is kept as a character; one JSON object, nested at most 16 levels deep, that has an RFC 8785
15
+ * form. Undefined for anything else.
16
+ */
17
+ export function decodeObject(s) {
18
+ const bytes = base64UrlBytes(s, MAX_DECODED);
19
+ if (typeof bytes === "string")
9
20
  return undefined;
10
21
  try {
11
- const b64 = c.request.replace(/-/g, "+").replace(/_/g, "/");
12
- const binary = atob(b64 + "=".repeat((4 - (b64.length % 4)) % 4));
13
- const bytes = Uint8Array.from(binary, (ch) => ch.charCodeAt(0));
14
- const v = parseJson(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
15
- return isObject(v) ? v : undefined;
22
+ const v = parseJson(new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes));
23
+ if (!isObject(v) || depthOf(v, 0) > MAX_JSON_DEPTH)
24
+ return undefined;
25
+ return typeof canonicalJson(v) === "string" ? v : undefined;
16
26
  }
17
27
  catch {
18
28
  return undefined;
19
29
  }
20
30
  }
31
+ /** The nesting depth of objects and arrays in `v`, counting from `d`, stopping once past `MAX_JSON_DEPTH`. */
32
+ function depthOf(v, d) {
33
+ if (d > MAX_JSON_DEPTH || typeof v !== "object" || v === null)
34
+ return d;
35
+ let max = d + 1;
36
+ for (const x of Object.values(v))
37
+ max = Math.max(max, depthOf(x, d + 1));
38
+ return max;
39
+ }
21
40
  /** Whether a placed challenge offers the pairing, by the protocol package's `pairingsOfPlaced`. */
22
41
  export function offers(c, pairing) {
23
42
  return pairingsOfPlaced(c).some((p) => p === pairing);
@@ -26,7 +45,7 @@ export function offers(c, pairing) {
26
45
  * The first challenge offering `pairing` on the account's EVM network, as MPP's `network` reads it, with the choice
27
46
  * MPP's build takes: the challenge, `from`, `now`, and the buyer's own inputs named in `spec`.
28
47
  */
29
- export function mppChoose(pairing, spec, accept) {
48
+ export function mppChoose(pairing, spec) {
30
49
  return (read, account, inputs, now, ref) => {
31
50
  const a = accountOf(account);
32
51
  if (a === undefined || a.namespace !== "eip155" || !EVM_ADDRESS.test(a.address))
@@ -36,9 +55,6 @@ export function mppChoose(pairing, spec, accept) {
36
55
  const challenge = challenges.find((c) => offers(c, pairing) && network(c) === a.network);
37
56
  if (challenge === undefined)
38
57
  return refuse("mpp/no-payable-option");
39
- const refused = accept?.(challenge) ?? null;
40
- if (refused !== null)
41
- return refused;
42
58
  const given = inputsOf(inputs, pairing, spec);
43
59
  if (isRefusal(given))
44
60
  return given;
@@ -66,108 +82,15 @@ export async function mppComplete(unsigned, signature) {
66
82
  return unsigned.complete(signature);
67
83
  }
68
84
  /** A buyer piece for an MPP charge pairing whose answer is one value. */
69
- export function mppChargePiece(pairing, spec, accept) {
85
+ export function mppChargePiece(pairing, spec) {
70
86
  return Object.freeze({
71
- choose: mppChoose(pairing, spec, accept),
87
+ choose: mppChoose(pairing, spec),
72
88
  choice: mppChoice,
73
89
  request: mppRequest,
74
90
  complete: mppComplete,
75
91
  moves: broadcasts,
76
92
  });
77
93
  }
78
- const MAX_SPLITS = 10;
79
- const DECIMAL = /^[0-9]{1,78}$/;
80
- const WORD = /^0x[0-9a-fA-F]{64}$/;
81
- const TRANSFER_SELECTOR = "a9059cbb";
82
- /**
83
- * A Tempo challenge's `methodDetails.splits`: none, or 1–10 entries, each with a recipient address, an amount above
84
- * zero and an optional 32-byte memo.
85
- */
86
- function tempoSplits(c) {
87
- const details = requestOf(c)?.["methodDetails"];
88
- const splits = isObject(details) ? details["splits"] : undefined;
89
- if (splits === undefined)
90
- return [];
91
- if (!Array.isArray(splits) || splits.length < 1 || splits.length > MAX_SPLITS)
92
- return refuse("mpp/splits-malformed");
93
- const out = [];
94
- for (const s of splits) {
95
- if (!isObject(s))
96
- return refuse("mpp/splits-malformed");
97
- const { recipient, amount, memo } = s;
98
- if (typeof recipient !== "string" || !EVM_ADDRESS.test(recipient))
99
- return refuse("mpp/splits-malformed");
100
- if (typeof amount !== "string" || !DECIMAL.test(amount) || BigInt(amount) === 0n)
101
- return refuse("mpp/splits-malformed");
102
- if (memo !== undefined && (typeof memo !== "string" || !WORD.test(memo)))
103
- return refuse("mpp/splits-malformed");
104
- out.push({ recipient: recipient, amount: BigInt(amount), ...(memo !== undefined ? { memo: memo } : {}) });
105
- }
106
- return out;
107
- }
108
- /** What the primary recipient receives: `amount` less the splits, which must leave more than zero. */
109
- function primaryAmount(c, splits) {
110
- const amount = requestOf(c)?.["amount"];
111
- if (typeof amount !== "string" || !DECIMAL.test(amount))
112
- return refuse("mpp/request-malformed");
113
- const primary = BigInt(amount) - splits.reduce((sum, s) => sum + s.amount, 0n);
114
- return primary > 0n ? primary : refuse("mpp/input-malformed");
115
- }
116
- /** Accepts a Tempo challenge whose splits are well formed and leave the primary recipient more than zero. */
117
- export function acceptSplits(c) {
118
- const splits = tempoSplits(c);
119
- if (isRefusal(splits))
120
- return splits;
121
- const primary = primaryAmount(c, splits);
122
- return isRefusal(primary) ? primary : null;
123
- }
124
- /** `transfer(address,uint256)` calldata. */
125
- function transferCalldata(to, amount) {
126
- return `0x${TRANSFER_SELECTOR}${"0".repeat(24)}${to.slice(2).toLowerCase()}${amount.toString(16).padStart(64, "0")}`;
127
- }
128
- /**
129
- * A Tempo charge's build. Without splits it is the binding's own `tempo-call`. With splits it is `tempo-calls`: the
130
- * binding's primary call, carrying its attribution memo, for `amount` less the splits, then one call per split in
131
- * array order, `transferWithMemo` where the split names a memo and `transfer` otherwise, all on `currency`.
132
- */
133
- export function tempoBuild(binding) {
134
- return async (choice, h) => {
135
- const unsigned = await binding.build(choice, h);
136
- if (isRefusal(unsigned))
137
- return unsigned;
138
- const challenge = choice.challenge;
139
- const splits = tempoSplits(challenge);
140
- if (isRefusal(splits) || splits.length === 0)
141
- return isRefusal(splits) ? splits : unsigned;
142
- const primary = primaryAmount(challenge, splits);
143
- if (isRefusal(primary))
144
- return primary;
145
- const request = unsigned.request;
146
- if (request.kind !== "tempo-call")
147
- return refuse("mpp/request-malformed");
148
- const recipient = requestOf(challenge)?.["recipient"];
149
- const memo = `0x${request.call.data.slice(-64)}`;
150
- const primaryCall = memoCalldata(recipient, primary, memo);
151
- if (isRefusal(primaryCall))
152
- return primaryCall;
153
- const currency = request.call.to;
154
- const calls = [{ to: currency, data: primaryCall }];
155
- for (const s of splits) {
156
- const data = s.memo !== undefined ? memoCalldata(s.recipient, s.amount, s.memo) : transferCalldata(s.recipient, s.amount);
157
- if (isRefusal(data))
158
- return data;
159
- calls.push({ to: currency, data });
160
- }
161
- const tempoCalls = {
162
- kind: "tempo-calls",
163
- chainId: request.chainId,
164
- calls,
165
- validBefore: request.validBefore,
166
- broadcast: request.broadcast,
167
- };
168
- return { request: tempoCalls, complete: (s) => unsigned.complete(s) };
169
- };
170
- }
171
94
  /**
172
95
  * The credential for a pushed Tempo transfer: the answer is `{hash, landed?: {transaction, blockNumber, logs}}`, the
173
96
  * hash the signer broadcast and, where the signer gives it, its landed receipt, which carries the memo `bound` reads.
@@ -176,7 +99,7 @@ export async function pushComplete(unsigned, signature) {
176
99
  if (!isObject(signature) || typeof signature["hash"] !== "string")
177
100
  return refuse("mpp/credential-malformed");
178
101
  const credential = unsigned.complete(signature["hash"]);
179
- if ("refused" in credential)
102
+ if (isRefusal(credential))
180
103
  return credential;
181
104
  const landed = signature["landed"];
182
105
  if (landed === undefined)
@@ -2,7 +2,7 @@
2
2
  * What the protocol-group pieces (card, AP2, UCP, ACP, ACK) share: the buyer's CAIP-10 account, which names the buyer,
3
3
  * the object choice revived from `Chosen`, and the piece of a pairing whose build has nothing for the buyer to sign.
4
4
  */
5
- import type { Json, Refusal } from "@integraledger/lcp";
5
+ import type { Json, Refusal } from "@integraledger/lcp/core";
6
6
  import type { BuyerPiece, Chosen, Inputs, Read } from "../types.js";
7
7
  /** A refusal `<ns>/no-payable-option` unless the account is CAIP-10. */
8
8
  export declare function unnamedBuyer(account: string, ns: string): Refusal | undefined;
@@ -3,7 +3,7 @@
3
3
  * percent-decoded as CAIP-10 writes it, and the piece for pairings where the payer's wallet builds and signs the
4
4
  * rail's own payment around what the build hands it.
5
5
  */
6
- import type { Refusal } from "@integraledger/lcp";
6
+ import type { Refusal } from "@integraledger/lcp/core";
7
7
  import type { PaymentRequired, PaymentRequirements } from "@integraledger/lcp/x402";
8
8
  import type { BuyerPiece, Chosen, Presented, Read } from "../types.js";
9
9
  /**
@@ -6,7 +6,7 @@ const HASH32 = /^0x[0-9a-fA-F]{64}$/;
6
6
  export const x402BatchSettlementEip155 = Object.freeze({
7
7
  choose(read, account, inputs, now, ref) {
8
8
  const o = firstOption(read, account, "eip155", PAIRING, EVM_ADDRESS);
9
- if ("refused" in o)
9
+ if (isRefusal(o))
10
10
  return refuse("x402/no-payable-option");
11
11
  const given = optionalInputs(inputs, "x402", { payerAuthorizer: EVM_ADDRESS, authSalt: HASH32 });
12
12
  if (isRefusal(given))
@@ -1,2 +1,4 @@
1
1
  import type { BuyerPiece } from "../types.js";
2
+ /** A Solana key or blockhash in base58: 32 to 44 characters of the Bitcoin alphabet. */
3
+ export declare const KEY: RegExp;
2
4
  export declare const x402BatchSettlementSolana: BuyerPiece;
@@ -1,14 +1,15 @@
1
1
  import { batchComplete, batchRequest, depositOf, optionalInputs, randomU64, reviveDecimals } from "./batch.js";
2
2
  import { firstOption, inputsOf, isObject, isRefusal, refuse, uintOf, x402Chosen } from "./common.js";
3
3
  const PAIRING = "x402/batch-settlement/solana";
4
- const KEY = /^[1-9A-HJ-NP-Za-km-z]{32,44}$/;
4
+ /** A Solana key or blockhash in base58: 32 to 44 characters of the Bitcoin alphabet. */
5
+ export const KEY = /^[1-9A-HJ-NP-Za-km-z]{32,44}$/;
5
6
  const U64 = /^[0-9]{1,20}$/;
6
7
  const U64_LIMIT = 1n << 64n;
7
8
  const isU64 = (v) => typeof v === "string" && U64.test(v) && BigInt(v) < U64_LIMIT;
8
9
  export const x402BatchSettlementSolana = Object.freeze({
9
10
  choose(read, account, inputs, now, ref) {
10
11
  const o = firstOption(read, account, "solana", PAIRING, KEY);
11
- if ("refused" in o)
12
+ if (isRefusal(o))
12
13
  return refuse("x402/no-payable-option");
13
14
  const extra = isObject(o.accepted.extra) ? o.accepted.extra : {};
14
15
  const offered = extra["recentBlockhash"];
@@ -1,9 +1,9 @@
1
- import { choiceOf, firstOption, isObject, refuse, withPaymentIdentifier, x402Chosen } from "./common.js";
1
+ import { choiceOf, firstOption, isObject, isRefusal, refuse, withPaymentIdentifier, x402Chosen } from "./common.js";
2
2
  const ID = "x402/exact/casper";
3
3
  export const x402ExactCasper = Object.freeze({
4
4
  choose(read, account, _inputs, now, ref) {
5
5
  const o = firstOption(read, account, "casper", ID);
6
- if ("refused" in o)
6
+ if (isRefusal(o))
7
7
  return refuse("x402/no-payable-option");
8
8
  return x402Chosen(ID, { required: o.required, accepted: o.accepted, from: o.address, now }, ref);
9
9
  },
@@ -14,7 +14,7 @@ export const x402ExactCasper = Object.freeze({
14
14
  return refuse("x402/signature-malformed");
15
15
  }
16
16
  const signed = unsigned.complete(signature["publicKey"], signature["signature"]);
17
- if ("refused" in signed)
17
+ if (isRefusal(signed))
18
18
  return signed;
19
19
  return withPaymentIdentifier(signed, choiceOf(chosen)?.["required"], chosen.ref);
20
20
  },
@@ -1,9 +1,9 @@
1
- import { choiceOf, firstOption, isObject, refuse, withPaymentIdentifier, x402Chosen } from "./common.js";
1
+ import { choiceOf, firstOption, isObject, isRefusal, refuse, withPaymentIdentifier, x402Chosen } from "./common.js";
2
2
  const ID = "x402/exact/ccd";
3
3
  export const x402ExactCcd = Object.freeze({
4
4
  choose(read, account, _inputs, now, ref) {
5
5
  const o = firstOption(read, account, "ccd", ID);
6
- if ("refused" in o)
6
+ if (isRefusal(o))
7
7
  return refuse("x402/no-payable-option");
8
8
  return x402Chosen(ID, { required: o.required, accepted: o.accepted, now }, ref);
9
9
  },
@@ -13,7 +13,7 @@ export const x402ExactCcd = Object.freeze({
13
13
  if (!isObject(signature))
14
14
  return refuse("x402/signature-malformed");
15
15
  const signed = unsigned.complete(signature);
16
- if ("refused" in signed)
16
+ if (isRefusal(signed))
17
17
  return signed;
18
18
  return withPaymentIdentifier(signed, choiceOf(chosen)?.["required"], chosen.ref);
19
19
  },
@@ -1,3 +1,6 @@
1
- /** A Hedera entity id, `shard.realm.num`. */
1
+ /**
2
+ * A Hedera entity id, `shard.realm.num`, as `@integraledger/lcp`'s Hedera pairings read it: each part 0, or up to 19
3
+ * digits with no leading zero.
4
+ */
2
5
  export declare const HEDERA_ENTITY: RegExp;
3
6
  export declare const x402ExactHedera: import("../types.js").BuyerPiece;
@@ -1,8 +1,11 @@
1
1
  import { bigintOf, bytesOf, inputsOf, isObject, isRefusal, refuse } from "./common.js";
2
2
  import { railPiece } from "./x402-rail.js";
3
3
  const PAIRING = "x402/exact/hedera";
4
- /** A Hedera entity id, `shard.realm.num`. */
5
- export const HEDERA_ENTITY = /^[0-9]{1,20}\.[0-9]{1,20}\.[0-9]{1,20}$/;
4
+ /**
5
+ * A Hedera entity id, `shard.realm.num`, as `@integraledger/lcp`'s Hedera pairings read it: each part 0, or up to 19
6
+ * digits with no leading zero.
7
+ */
8
+ export const HEDERA_ENTITY = /^(0|[1-9][0-9]{0,18})\.(0|[1-9][0-9]{0,18})\.(0|[1-9][0-9]{0,18})$/;
6
9
  const KEY_TYPES = ["ed25519", "ecdsa-secp256k1"];
7
10
  function inputs(_accepted, given) {
8
11
  const read = inputsOf(given, PAIRING, { node: "string", validStart: "object", maxFee: "decimal", decimals: "optional-uint" });
@@ -1,10 +1,10 @@
1
1
  /**
2
2
  * The buyer piece for `x402/exact/solana`: the v0 message whose one memo is the option's `extra.memo`, signed by the
3
- * payer as `solana-message`. The recent blockhash is the option's `extra.recentBlockhash` when it names one, else the
4
- * buyer's; the mint's decimals and token program are the buyer's reads.
3
+ * payer as `solana-message`. The recent blockhash is the option's `extra.recentBlockhash` when it is a base58 key of 32
4
+ * bytes, else the buyer's; the mint's decimals and token program are the buyer's reads.
5
5
  */
6
- import type { Refusal } from "@integraledger/lcp";
7
- /** A Solana address: base58 of 32 bytes. */
6
+ import type { Refusal } from "@integraledger/lcp/core";
7
+ /** A Solana address or blockhash in base58: 32 to 44 characters of the Bitcoin alphabet. */
8
8
  export declare const SOLANA_ADDRESS: RegExp;
9
9
  /** `computeUnitPrice` as the build's bigint, where the choice carries one. */
10
10
  export declare function withUnitPrice(c: Record<string, unknown>): Record<string, unknown> | Refusal;
@@ -1,7 +1,8 @@
1
+ import { isKey } from "@integraledger/lcp/svm";
1
2
  import { bigintOf, inputsOf, isRefusal, refuse } from "./common.js";
2
3
  import { railPiece, signature64 } from "./x402-rail.js";
3
4
  const PAIRING = "x402/exact/solana";
4
- /** A Solana address: base58 of 32 bytes. */
5
+ /** A Solana address or blockhash in base58: 32 to 44 characters of the Bitcoin alphabet. */
5
6
  export const SOLANA_ADDRESS = /^[1-9A-HJ-NP-Za-km-z]{32,44}$/;
6
7
  /** `computeUnitPrice` as the build's bigint, where the choice carries one. */
7
8
  export function withUnitPrice(c) {
@@ -12,7 +13,7 @@ export function withUnitPrice(c) {
12
13
  }
13
14
  function inputs(accepted, given) {
14
15
  const offered = accepted.extra?.["recentBlockhash"];
15
- const fromOffer = typeof offered === "string" && offered !== "";
16
+ const fromOffer = isKey(offered);
16
17
  const read = inputsOf(given, PAIRING, {
17
18
  decimals: "uint",
18
19
  tokenProgram: "string",
@@ -8,7 +8,7 @@ export const x402ExactStellar = railPiece({
8
8
  pairing: PAIRING,
9
9
  namespace: "stellar",
10
10
  address: /^G[A-Z2-7]{55}$/,
11
- payer: null,
11
+ payer: "payer",
12
12
  now: false,
13
13
  inputs,
14
14
  revive: (c) => c,
@@ -1,6 +1,8 @@
1
1
  /**
2
2
  * The buyer piece for `x402/exact/sui`: the wallet builds the scheme's payment, adds the request's `pureInput` as the
3
- * one unused `Pure` input, bounds the expiration by epoch, signs, and answers `{signature, transaction}`.
3
+ * one unused `Pure` input, bounds the expiration by epoch as the request asks, signs, and answers
4
+ * `{signature, transaction}`. The epoch bound is this piece's choice, not a condition of the record: a signed
5
+ * transaction without one that carries the hash completes, and is recorded.
4
6
  */
5
7
  import { walletBuiltPiece } from "./x402-account-rails.js";
6
8
  const SUI_ADDRESS = /^0x[0-9a-fA-F]{64}$/;
@@ -1,10 +1,18 @@
1
1
  import { bigintOf, bytesOf, choiceOf, inputsOf, isRefusal, refuse, x402Chosen } from "./common.js";
2
2
  import { identified, railOption } from "./x402-account-rails.js";
3
3
  const PAIRING = "x402/exact/tvm";
4
- const RAW_ADDRESS = /^-?[0-9]{1,10}:[0-9a-fA-F]{64}$/;
4
+ const RAW_ADDRESS = /^(-?[0-9]{1,10}):[0-9a-fA-F]{64}$/;
5
+ /**
6
+ * A raw `workchain:hex` address whose workchain fits TL-B's `addr_std` `workchain_id:int8`, [-128, 127], as lcp's
7
+ * TON filter reads one.
8
+ */
9
+ function isRawAddress(a) {
10
+ const m = RAW_ADDRESS.exec(a);
11
+ return m !== null && Number(m[1]) >= -128 && Number(m[1]) <= 127;
12
+ }
5
13
  export const x402ExactTvm = Object.freeze({
6
14
  choose(read, account, inputs, now, ref) {
7
- const o = railOption(read, account, ["tvm"], PAIRING, (a) => RAW_ADDRESS.test(a));
15
+ const o = railOption(read, account, ["tvm"], PAIRING, isRawAddress);
8
16
  if (isRefusal(o))
9
17
  return o;
10
18
  const given = inputsOf(inputs, PAIRING, {
@@ -1,7 +1,6 @@
1
1
  import { inputsOf, refuse } from "./common.js";
2
2
  import { railPiece } from "./x402-rail.js";
3
3
  const PAIRING = "x402/exact/xrpl";
4
- const BLOB = /^0x((?:[0-9a-fA-F]{2})+)$/;
5
4
  function inputs(accepted, given) {
6
5
  const ticket = accepted.extra?.["assetTransferMethod"] === "ticketSequence";
7
6
  return inputsOf(given, PAIRING, {
@@ -10,10 +9,9 @@ function inputs(accepted, given) {
10
9
  lastLedgerSequence: "uint",
11
10
  });
12
11
  }
13
- /** The signed blob's hex digits, from `0x` hex. */
12
+ /** The signed blob as given: the build's `complete` reads it as hex digits without `0x`. */
14
13
  function blob(signature) {
15
- const m = typeof signature === "string" ? BLOB.exec(signature) : null;
16
- return m === null ? refuse("x402/signature-malformed") : m[1];
14
+ return typeof signature === "string" ? signature : refuse("x402/signature-malformed");
17
15
  }
18
16
  export const x402ExactXrpl = railPiece({
19
17
  pairing: PAIRING,
@@ -3,7 +3,7 @@
3
3
  * on the account's network, the buyer's own inputs beside it as JSON, the build's request exactly as built, and the
4
4
  * payment the signer's answer completes, with the payment identifier appended where the challenge advertises it.
5
5
  */
6
- import type { Json, Refusal } from "@integraledger/lcp";
6
+ import type { Json, Refusal } from "@integraledger/lcp/core";
7
7
  import type { PaymentRequirements } from "@integraledger/lcp/x402";
8
8
  import type { BuyerPiece, Inputs, Signature } from "../types.js";
9
9
  /** One x402 rail pairing's buyer piece, described by what differs between rails. */
@@ -1,15 +1,20 @@
1
1
  /**
2
2
  * `transact` is `confirm`, the agreement payment when the pairing's payment is not itself a public proof, the signer,
3
- * then `finish`.
3
+ * then `finish`. The agreement payment is signed only once the buyer's agent has approved it: the first call returns it
4
+ * in `approve`, and a second call with that payment as `approved` pays it and then the resource.
4
5
  */
5
- import type { AtrHash } from "@integraledger/lcp";
6
- import type { AgreementReceipt, Binding, Declined, Fetch, Presented, Signer, TransactOptions } from "./types.js";
6
+ import type { AtrHash } from "@integraledger/lcp/core";
7
+ import type { AgreementReceipt, Binding, Declined, Fetch, Presented, Signer, ToApprove, TransactOptions } from "./types.js";
7
8
  /**
8
- * `confirm`, then, for a pairing whose payment is not itself a public proof, the agreement payment and its receipt,
9
- * then the signer, then `finish`. On a decline before the signer the signer is never called. Where the build is itself
10
- * the payment the signer is not called; where the pairing has nothing for the buyer to sign, `signed` is null after the
11
- * comparison. When the agreement was paid first, `agreement` is its receipt. `landed` is `finish`'s, where it gives one.
12
- * Options holding anything but `inputs` and `agreementSigner` are declined before any fetch or signer call.
9
+ * `confirm`, then, for a pairing whose payment is not itself a public proof, the agreement, then the signer, then
10
+ * `finish`. Without `approved`, an agreement not yet recorded is returned as `approve`, the agreement payment for the
11
+ * agent to approve, and nothing is signed; with `approved`, that payment is signed and paid, and the resource's payment
12
+ * is signed only with the agreement's receipt in hand. On a decline before the signer the signer is never called. Where
13
+ * the build is itself the payment the signer is not called; where the pairing has nothing for the buyer to sign,
14
+ * `signed` is null after the comparison. `agreement` is the agreement's receipt, where the pairing needs one. `landed`
15
+ * is `finish`'s, where it gives one. `signal` ends the agreement exchange. Options holding anything but `inputs`,
16
+ * `agreementSigner`, `approved` and `signal`, or a signer or agreement signer whose `account` is not a string, are
17
+ * declined `no-payable-option` with `<namespace>/input-malformed` before any fetch or signer call.
13
18
  */
14
19
  export declare function transact(doc: unknown, binding: Binding, signer: Signer, fetch: Fetch, options?: TransactOptions): Promise<{
15
20
  signed: Presented | null;
@@ -17,4 +22,4 @@ export declare function transact(doc: unknown, binding: Binding, signer: Signer,
17
22
  bytes: Uint8Array;
18
23
  h: AtrHash;
19
24
  agreement?: AgreementReceipt;
20
- } | Declined>;
25
+ } | ToApprove | Declined>;
package/dist/transact.js CHANGED
@@ -1,32 +1,31 @@
1
- import { agree } from "./agreement.js";
2
- import { confirm, declined, isObject, namespaceOf, pieceOf, signSteps, unsupported } from "./gate.js";
1
+ import { exchange } from "./agreement.js";
2
+ import { confirm, declined, hasAccount, isObject, namespaceOf, pieceOf, signSteps, unsupported } from "./gate.js";
3
3
  /**
4
- * `confirm`, then, for a pairing whose payment is not itself a public proof, the agreement payment and its receipt,
5
- * then the signer, then `finish`. On a decline before the signer the signer is never called. Where the build is itself
6
- * the payment the signer is not called; where the pairing has nothing for the buyer to sign, `signed` is null after the
7
- * comparison. When the agreement was paid first, `agreement` is its receipt. `landed` is `finish`'s, where it gives one.
8
- * Options holding anything but `inputs` and `agreementSigner` are declined before any fetch or signer call.
4
+ * `confirm`, then, for a pairing whose payment is not itself a public proof, the agreement, then the signer, then
5
+ * `finish`. Without `approved`, an agreement not yet recorded is returned as `approve`, the agreement payment for the
6
+ * agent to approve, and nothing is signed; with `approved`, that payment is signed and paid, and the resource's payment
7
+ * is signed only with the agreement's receipt in hand. On a decline before the signer the signer is never called. Where
8
+ * the build is itself the payment the signer is not called; where the pairing has nothing for the buyer to sign,
9
+ * `signed` is null after the comparison. `agreement` is the agreement's receipt, where the pairing needs one. `landed`
10
+ * is `finish`'s, where it gives one. `signal` ends the agreement exchange. Options holding anything but `inputs`,
11
+ * `agreementSigner`, `approved` and `signal`, or a signer or agreement signer whose `account` is not a string, are
12
+ * declined `no-payable-option` with `<namespace>/input-malformed` before any fetch or signer call.
9
13
  */
10
14
  export async function transact(doc, binding, signer, fetch, options) {
11
15
  if (pieceOf(binding) === undefined)
12
16
  return unsupported(binding);
13
- if (!optionsOk(options))
14
- return declined("no-payable-option", `${namespaceOf(binding)}/input-malformed`);
15
- const given = options ?? {};
16
- const inputs = given.inputs ?? {};
17
- const agreementSigner = given.agreementSigner;
17
+ const ns = namespaceOf(binding);
18
+ if (!optionsOk(options) || !hasAccount(signer))
19
+ return declined("no-payable-option", `${ns}/input-malformed`);
20
+ const { inputs = {}, agreementSigner, approved, signal } = options ?? {};
18
21
  const confirmed = await confirm(doc, binding, signer.account, fetch, inputs);
19
22
  if ("decline" in confirmed)
20
23
  return confirmed;
21
24
  const { bytes, chosen } = confirmed;
22
25
  let receipt = {};
23
- if (confirmed.agreement !== undefined) {
24
- const agreed = await agree(confirmed.h, confirmed.agreement, agreementSigner ?? signer, fetch, {
25
- bytes,
26
- inputs,
27
- ns: namespaceOf(binding),
28
- });
29
- if ("decline" in agreed)
26
+ if (chosen.agreement !== undefined) {
27
+ const agreed = await exchange(bytes, chosen.agreement, agreementSigner ?? signer, fetch, { approved, inputs, signal }, ns);
28
+ if (!("receipt" in agreed))
30
29
  return agreed;
31
30
  receipt = { agreement: agreed.receipt };
32
31
  }
@@ -36,18 +35,25 @@ export async function transact(doc, binding, signer, fetch, options) {
36
35
  const landed = done.landed === undefined ? {} : { landed: done.landed };
37
36
  return { signed: done.signed, ...landed, bytes, h: done.h, ...receipt };
38
37
  }
39
- const OPTION_KEYS = ["inputs", "agreementSigner"];
38
+ const OPTION_KEYS = ["inputs", "agreementSigner", "approved", "signal"];
40
39
  /**
41
- * Whether `transact`'s options are absent, or an object holding only `inputs` (an object, or undefined) and
42
- * `agreementSigner` (an object with a `sign` function, or undefined).
40
+ * Whether `transact`'s options are absent, or an object holding only `inputs` (an object, or undefined),
41
+ * `agreementSigner` (an object with a `sign` function and a string `account`, or undefined), `approved` (an object, or
42
+ * undefined) and `signal` (an `AbortSignal`, or undefined).
43
43
  */
44
44
  function optionsOk(options) {
45
45
  if (options === undefined)
46
46
  return true;
47
47
  if (!isObject(options) || !Object.keys(options).every((k) => OPTION_KEYS.includes(k)))
48
48
  return false;
49
- const { inputs, agreementSigner } = options;
49
+ const { inputs, agreementSigner, approved, signal } = options;
50
50
  if (inputs !== undefined && !isObject(inputs))
51
51
  return false;
52
- return agreementSigner === undefined || (isObject(agreementSigner) && typeof agreementSigner["sign"] === "function");
52
+ if (approved !== undefined && !isObject(approved))
53
+ return false;
54
+ if (signal !== undefined && !(signal instanceof AbortSignal))
55
+ return false;
56
+ if (agreementSigner === undefined)
57
+ return true;
58
+ return isObject(agreementSigner) && typeof agreementSigner["sign"] === "function" && hasAccount(agreementSigner);
53
59
  }