@lifi/compose-spec 0.11.3 → 0.13.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/src/simulate.ts CHANGED
@@ -67,13 +67,41 @@ export type NativeBalanceRequirement = NativeBalancePrecondition;
67
67
  export type Erc20AllowanceRequirement = Erc20AllowancePrecondition;
68
68
 
69
69
  /**
70
- * The funding-instruction union applied before a simulation. Three variants,
70
+ * Funding instruction: seed a Uniswap Permit2 `AllowanceTransfer` allowance
71
+ * before simulation, so a `Permit2.transferFrom(owner, _, amount, token)` sent
72
+ * by `spender` passes Permit2's own check.
73
+ *
74
+ * slot-finder writes two overrides: Permit2's `allowance[owner][token][spender]`
75
+ * (no expiry, the owner's live nonce kept) and the ERC-20 allowance
76
+ * `owner` → Permit2 that the pull spends. It does not fund the owner's token
77
+ * balance: add an `Erc20Balance` for that. Only the canonical Permit2 address
78
+ * `0x000000000022D473030F116dDEE9F6B43aC78BA3` is supported; on a chain
79
+ * without code there the simulation answers HTTP 422.
80
+ *
81
+ * Unlike the other variants this is not a compile precondition: no op declares
82
+ * a Permit2 allowance, so only a `POST /simulate` caller sends one.
83
+ */
84
+ export type Permit2AllowanceRequirement = {
85
+ readonly type: 'Permit2Allowance';
86
+ /** Address whose tokens Permit2 pulls. */
87
+ readonly owner: string;
88
+ /** ERC-20 token Permit2 pulls. */
89
+ readonly token: string;
90
+ /** Address that calls `Permit2.transferFrom`. */
91
+ readonly spender: string;
92
+ /** Permit2 allowance amount, in the token's base units. */
93
+ readonly amount: bigint | string;
94
+ };
95
+
96
+ /**
97
+ * The funding-instruction union applied before a simulation. Four variants,
71
98
  * discriminated by `type`.
72
99
  */
73
100
  export type SlotFinderRequirement =
74
101
  | Erc20BalanceRequirement
75
102
  | NativeBalanceRequirement
76
- | Erc20AllowanceRequirement;
103
+ | Erc20AllowanceRequirement
104
+ | Permit2AllowanceRequirement;
77
105
 
78
106
  /** Request body for `POST /simulate`. */
79
107
  export interface SimulateRequest {
package/src/zodSchemas.ts CHANGED
@@ -4,7 +4,6 @@ import {
4
4
  BYTES32_LOWER_HEX,
5
5
  DECIMAL_UINT,
6
6
  EVM_ADDRESS_HEX,
7
- HEX_BYTES,
8
7
  MAX_UINT256,
9
8
  } from './hexPatterns.js';
10
9
 
@@ -12,11 +11,10 @@ import {
12
11
  // `flowSchema.ts`, single-sourced so the wire schemas stay consistent.
13
12
  export const chainIdZod = z.number().int().positive();
14
13
 
15
- // Zod mirrors of `EVMAddressString`, `HexBytesString` and `IntegerString` in
16
- // `flowSchema.ts`, built from the same `hexPatterns.ts` constants.
14
+ // Zod mirrors of `EVMAddressString` and `IntegerString` in `flowSchema.ts`,
15
+ // built from the same `hexPatterns.ts` constants.
17
16
  // `continuationParity.spec.ts` holds the two sides in lockstep.
18
17
  const evmAddressZod = z.string().regex(EVM_ADDRESS_HEX);
19
- const hexBytesZod = z.string().regex(HEX_BYTES);
20
18
  // One refinement, like `IntegerString`'s filter: Zod runs later checks after
21
19
  // a failed `.regex`, so a separate bound check would hand `BigInt` a
22
20
  // non-digit string and throw.
@@ -207,7 +205,7 @@ export const ComposeManifestZod = z.object({
207
205
  });
208
206
 
209
207
  // Prefix-only `0x` check, mirroring `HexStringSchema`; used only by the escrow
210
- // record, which the settlement service returns.
208
+ // and binding records, which the settlement service returns.
211
209
  const hexStringZod = z.string().startsWith('0x');
212
210
 
213
211
  // Mirror of `Phase1EscrowSchema` (continuation.ts): the escrow a settlement
@@ -228,115 +226,86 @@ export const SettlementEscrowZod = z.object({
228
226
  expiresAtMs: z.number().int().positive(),
229
227
  });
230
228
 
229
+ // Mirror of `Phase1BindingSchema` (continuation.ts): the executor binding of
230
+ // an `exact` settle. The settlement service hashed `payload` into the escrow's
231
+ // execute constraint, so a fill runs only that executor call;
232
+ // `payloadHash === keccak256(payload)`. `calldata` is what the executor's
233
+ // proxy runs (the leg's compiled bytes) and `approvals` the allowances it
234
+ // grants first. Absent unless the settle is `exact`. `approvals` is
235
+ // `.readonly()` so the inferred type matches the readonly artifact type
236
+ // without a copy at the handler.
237
+ export const SettlementBindingZod = z.object({
238
+ executionTarget: hexStringZod,
239
+ payload: hexStringZod,
240
+ payloadHash: hexStringZod,
241
+ calldata: hexStringZod,
242
+ approvals: z
243
+ .array(z.object({ token: hexStringZod, spender: hexStringZod }))
244
+ .readonly(),
245
+ });
246
+
231
247
  // Mirror of `AssertionOwnerSchema` (continuation.ts): a concrete address or
232
- // one of the two symbolic owners resolved at settlement. Applies ONLY to the
233
- // derivation-only delta members — the three absolute members keep
234
- // address-only owners (see the note in continuation.ts).
248
+ // one of the two symbolic owners resolved at settlement.
235
249
  const assertionOwnerZod = z.union([
236
250
  evmAddressZod,
237
251
  z.enum(['escrow', 'delivery']),
238
252
  ]);
239
253
 
240
- // HTTP-layer mirror of `AssertionSpecSchema` (continuation.ts): the three
241
- // absolute members plus the two derivation-only members. Amounts are decimal
242
- // strings on the wire.
254
+ // HTTP-layer mirror of `AssertionSpecSchema` (continuation.ts): the two
255
+ // balance members and the `call` member. Amounts are decimal strings on the
256
+ // wire; the `call` member's `signature` / `args` contract is documented on
257
+ // `CallCheckSpecSchema`, and its `args` is `.readonly()` so the inferred type
258
+ // matches the readonly spec type without a copy at the handler. It is also the
259
+ // descriptor's `assertedPredicate` element (`AssertedPredicateSchema` decodes
260
+ // the same shape).
243
261
  export const AssertionSpecZod = z.discriminatedUnion('kind', [
244
262
  z.object({
245
263
  kind: z.literal('erc20BalanceGte'),
246
264
  chainId: chainIdZod,
247
265
  token: evmAddressZod,
248
- owner: evmAddressZod,
266
+ owner: assertionOwnerZod,
249
267
  minAmount: uintStringZod,
250
268
  }),
251
269
  z.object({
252
270
  kind: z.literal('nativeBalanceGte'),
253
271
  chainId: chainIdZod,
254
- owner: evmAddressZod,
272
+ owner: assertionOwnerZod,
255
273
  minAmount: uintStringZod,
256
274
  }),
257
275
  z.object({
258
276
  kind: z.literal('call'),
259
277
  chainId: chainIdZod,
260
278
  to: evmAddressZod,
261
- calldata: hexBytesZod,
279
+ signature: z.string(),
280
+ args: z.array(z.string()).readonly(),
262
281
  comparator: z.enum(['gte', 'eq', 'lte']),
263
- value: uintStringZod,
264
- }),
265
- z.object({
266
- kind: z.literal('erc20BalanceDeltaGte'),
267
- chainId: z.number().int().positive(),
268
- token: evmAddressZod,
269
- owner: assertionOwnerZod,
270
- minDelta: uintStringZod,
271
- }),
272
- z.object({
273
- kind: z.literal('nativeBalanceDeltaGte'),
274
- chainId: z.number().int().positive(),
275
- owner: assertionOwnerZod,
276
- minDelta: uintStringZod,
282
+ threshold: uintStringZod,
277
283
  }),
278
284
  ]);
279
285
 
280
286
  export type AssertionSpecWire = z.infer<typeof AssertionSpecZod>;
281
287
 
282
- // HTTP-layer mirror of the GD-3 descriptor union `AssertedPredicateSchema`
283
- // (descriptor.ts, seam C4). It is the disclosure-path widening of
284
- // `AssertionSpecZod`: the two balance-`Gte` members accept a symbolic owner
285
- // (`assertionOwnerZod`) as well as hex, because the derivation resolves symbolic
286
- // owners to validator-injected slots at settlement. The `AssertionSpecZod`
287
- // balance members stay hex-only; this widening is confined to the descriptor.
288
- // The `call` member and the two derivation-only delta members are reused
289
- // verbatim by selecting them from `AssertionSpecZod.options` by their `kind`
290
- // literal, so they cannot drift from the source union.
291
- const assertionSpecOptionByKind = (kind: string) => {
292
- const option = AssertionSpecZod.options.find(
293
- (o) => o.shape.kind.value === kind,
294
- );
295
- if (option === undefined) {
296
- throw new Error(`AssertionSpecZod has no member with kind "${kind}"`);
297
- }
298
- return option;
299
- };
300
-
301
- export const AssertedPredicateZod = z.discriminatedUnion('kind', [
302
- z.object({
303
- kind: z.literal('erc20BalanceGte'),
304
- chainId: z.number().int().positive(),
305
- token: evmAddressZod,
306
- owner: assertionOwnerZod,
307
- minAmount: uintStringZod,
308
- }),
309
- z.object({
310
- kind: z.literal('nativeBalanceGte'),
311
- chainId: z.number().int().positive(),
312
- owner: assertionOwnerZod,
313
- minAmount: uintStringZod,
314
- }),
315
- assertionSpecOptionByKind('call'),
316
- assertionSpecOptionByKind('erc20BalanceDeltaGte'),
317
- assertionSpecOptionByKind('nativeBalanceDeltaGte'),
318
- ]);
319
-
320
288
  export const VerificationDescriptorZod = z.object({
321
289
  validationProgramHash: z.string().regex(BYTES32_LOWER_HEX),
322
290
  // The C5 echo's second hash (GD-8): the params-vector content hash
323
291
  // (`paramsHash`, C1). Required and jointly necessary with the value-blind
324
292
  // `validationProgramHash`.
325
293
  paramsHash: z.string().regex(BYTES32_LOWER_HEX),
326
- assertedPredicate: z.array(AssertedPredicateZod),
294
+ assertedPredicate: z.array(AssertionSpecZod).readonly(),
327
295
  });
328
296
 
329
- export type AssertedPredicateWire = z.infer<typeof AssertedPredicateZod>;
330
297
  export type VerificationDescriptorWire = z.infer<
331
298
  typeof VerificationDescriptorZod
332
299
  >;
333
300
 
334
301
  // What the response says about how one `continuation.settle` node settles.
335
- // `escrow` is present when the provider registered an escrow; a settle node
336
- // that discloses none is an empty entry. Carries no calldata and no typed
337
- // data: what to submit or sign lives in `actions`.
302
+ // `escrow` is present when the provider registered an escrow and `binding`
303
+ // when the settle is `exact`; a settle node that discloses neither is an empty
304
+ // entry. Carries nothing to submit or sign: that lives in `actions`.
305
+ // `binding.calldata` is what the executor runs, disclosed for checking.
338
306
  export const SettlementZod = z.object({
339
307
  escrow: SettlementEscrowZod.optional(),
308
+ binding: SettlementBindingZod.optional(),
340
309
  });
341
310
 
342
311
  export type ResourcePort = z.infer<typeof ResourcePortZod>;
@@ -355,4 +324,5 @@ export type ManifestPrecondition = z.infer<typeof ManifestPreconditionZod>;
355
324
  export type ManifestRouting = z.infer<typeof ManifestRoutingZod>;
356
325
  export type ComposeManifest = z.infer<typeof ComposeManifestZod>;
357
326
  export type SettlementEscrowWire = z.infer<typeof SettlementEscrowZod>;
327
+ export type SettlementBindingWire = z.infer<typeof SettlementBindingZod>;
358
328
  export type SettlementWire = z.infer<typeof SettlementZod>;