@lifi/compose-spec 0.10.0 → 0.12.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/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.
@@ -181,6 +179,16 @@ export const ManifestPreconditionZod = z.object({
181
179
  configSchema: z.unknown().optional(),
182
180
  });
183
181
 
182
+ // The deployment's planning bounds for `POST /compose/route`. `maxRouteHops`
183
+ // is the hop ceiling, swap included; `1` means the deployment never chains.
184
+ // `swapHops` is where a planned route may contain an aggregator swap: only as
185
+ // its first hop (`head`), or nowhere (`none`). The bounds are necessary, not
186
+ // sufficient: a pair inside them can still return `no_route_error`.
187
+ export const ManifestRoutingZod = z.object({
188
+ maxRouteHops: z.number().int().min(1),
189
+ swapHops: z.enum(['head', 'none']),
190
+ });
191
+
184
192
  export const ComposeManifestZod = z.object({
185
193
  manifestVersion: z.number(),
186
194
  manifestHash: z.string(),
@@ -189,10 +197,15 @@ export const ComposeManifestZod = z.object({
189
197
  guards: z.array(ManifestGuardZod),
190
198
  materialisers: z.array(ManifestMaterialiserZod),
191
199
  preconditions: z.array(ManifestPreconditionZod).optional(),
200
+ // Deployment data, not catalog data: `GET /compose/manifest` sets it from
201
+ // compose 0.10.2 on, the static catalog manifest never does, and
202
+ // `manifestHash` does not cover it. Absent means unknown bounds, not a
203
+ // default: a client must not reject a pair on bounds it was not given.
204
+ routing: ManifestRoutingZod.optional(),
192
205
  });
193
206
 
194
207
  // Prefix-only `0x` check, mirroring `HexStringSchema`; used only by the escrow
195
- // record, which the settlement service returns.
208
+ // and binding records, which the settlement service returns.
196
209
  const hexStringZod = z.string().startsWith('0x');
197
210
 
198
211
  // Mirror of `Phase1EscrowSchema` (continuation.ts): the escrow a settlement
@@ -207,120 +220,92 @@ export const SettlementEscrowZod = z.object({
207
220
  token: hexStringZod,
208
221
  amount: z.string(),
209
222
  cap: z.string(),
223
+ floor: z.string(),
210
224
  owner: hexStringZod,
211
225
  refund: hexStringZod,
212
226
  expiresAtMs: z.number().int().positive(),
213
227
  });
214
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
+
215
247
  // Mirror of `AssertionOwnerSchema` (continuation.ts): a concrete address or
216
- // one of the two symbolic owners resolved at settlement. Applies ONLY to the
217
- // derivation-only delta members — the three absolute members keep
218
- // address-only owners (see the note in continuation.ts).
248
+ // one of the two symbolic owners resolved at settlement.
219
249
  const assertionOwnerZod = z.union([
220
250
  evmAddressZod,
221
251
  z.enum(['escrow', 'delivery']),
222
252
  ]);
223
253
 
224
- // HTTP-layer mirror of `AssertionSpecSchema` (continuation.ts): the three
225
- // absolute members plus the two derivation-only members. Amounts are decimal
226
- // 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).
227
261
  export const AssertionSpecZod = z.discriminatedUnion('kind', [
228
262
  z.object({
229
263
  kind: z.literal('erc20BalanceGte'),
230
264
  chainId: chainIdZod,
231
265
  token: evmAddressZod,
232
- owner: evmAddressZod,
266
+ owner: assertionOwnerZod,
233
267
  minAmount: uintStringZod,
234
268
  }),
235
269
  z.object({
236
270
  kind: z.literal('nativeBalanceGte'),
237
271
  chainId: chainIdZod,
238
- owner: evmAddressZod,
272
+ owner: assertionOwnerZod,
239
273
  minAmount: uintStringZod,
240
274
  }),
241
275
  z.object({
242
276
  kind: z.literal('call'),
243
277
  chainId: chainIdZod,
244
278
  to: evmAddressZod,
245
- calldata: hexBytesZod,
279
+ signature: z.string(),
280
+ args: z.array(z.string()).readonly(),
246
281
  comparator: z.enum(['gte', 'eq', 'lte']),
247
- value: uintStringZod,
248
- }),
249
- z.object({
250
- kind: z.literal('erc20BalanceDeltaGte'),
251
- chainId: z.number().int().positive(),
252
- token: evmAddressZod,
253
- owner: assertionOwnerZod,
254
- minDelta: uintStringZod,
255
- }),
256
- z.object({
257
- kind: z.literal('nativeBalanceDeltaGte'),
258
- chainId: z.number().int().positive(),
259
- owner: assertionOwnerZod,
260
- minDelta: uintStringZod,
282
+ threshold: uintStringZod,
261
283
  }),
262
284
  ]);
263
285
 
264
286
  export type AssertionSpecWire = z.infer<typeof AssertionSpecZod>;
265
287
 
266
- // HTTP-layer mirror of the GD-3 descriptor union `AssertedPredicateSchema`
267
- // (descriptor.ts, seam C4). It is the disclosure-path widening of
268
- // `AssertionSpecZod`: the two balance-`Gte` members accept a symbolic owner
269
- // (`assertionOwnerZod`) as well as hex, because the derivation resolves symbolic
270
- // owners to validator-injected slots at settlement. The `AssertionSpecZod`
271
- // balance members stay hex-only; this widening is confined to the descriptor.
272
- // The `call` member and the two derivation-only delta members are reused
273
- // verbatim by selecting them from `AssertionSpecZod.options` by their `kind`
274
- // literal, so they cannot drift from the source union.
275
- const assertionSpecOptionByKind = (kind: string) => {
276
- const option = AssertionSpecZod.options.find(
277
- (o) => o.shape.kind.value === kind,
278
- );
279
- if (option === undefined) {
280
- throw new Error(`AssertionSpecZod has no member with kind "${kind}"`);
281
- }
282
- return option;
283
- };
284
-
285
- export const AssertedPredicateZod = z.discriminatedUnion('kind', [
286
- z.object({
287
- kind: z.literal('erc20BalanceGte'),
288
- chainId: z.number().int().positive(),
289
- token: evmAddressZod,
290
- owner: assertionOwnerZod,
291
- minAmount: uintStringZod,
292
- }),
293
- z.object({
294
- kind: z.literal('nativeBalanceGte'),
295
- chainId: z.number().int().positive(),
296
- owner: assertionOwnerZod,
297
- minAmount: uintStringZod,
298
- }),
299
- assertionSpecOptionByKind('call'),
300
- assertionSpecOptionByKind('erc20BalanceDeltaGte'),
301
- assertionSpecOptionByKind('nativeBalanceDeltaGte'),
302
- ]);
303
-
304
288
  export const VerificationDescriptorZod = z.object({
305
289
  validationProgramHash: z.string().regex(BYTES32_LOWER_HEX),
306
290
  // The C5 echo's second hash (GD-8): the params-vector content hash
307
291
  // (`paramsHash`, C1). Required and jointly necessary with the value-blind
308
292
  // `validationProgramHash`.
309
293
  paramsHash: z.string().regex(BYTES32_LOWER_HEX),
310
- assertedPredicate: z.array(AssertedPredicateZod),
294
+ assertedPredicate: z.array(AssertionSpecZod).readonly(),
311
295
  });
312
296
 
313
- export type AssertedPredicateWire = z.infer<typeof AssertedPredicateZod>;
314
297
  export type VerificationDescriptorWire = z.infer<
315
298
  typeof VerificationDescriptorZod
316
299
  >;
317
300
 
318
301
  // What the response says about how one `continuation.settle` node settles.
319
- // `escrow` is present when the provider registered an escrow; a settle node
320
- // that discloses none is an empty entry. Carries no calldata and no typed
321
- // 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.
322
306
  export const SettlementZod = z.object({
323
307
  escrow: SettlementEscrowZod.optional(),
308
+ binding: SettlementBindingZod.optional(),
324
309
  });
325
310
 
326
311
  export type ResourcePort = z.infer<typeof ResourcePortZod>;
@@ -336,6 +321,8 @@ export type GuardCompatibility = z.infer<typeof GuardCompatibilityZod>;
336
321
  export type ManifestGuard = z.infer<typeof ManifestGuardZod>;
337
322
  export type ManifestMaterialiser = z.infer<typeof ManifestMaterialiserZod>;
338
323
  export type ManifestPrecondition = z.infer<typeof ManifestPreconditionZod>;
324
+ export type ManifestRouting = z.infer<typeof ManifestRoutingZod>;
339
325
  export type ComposeManifest = z.infer<typeof ComposeManifestZod>;
340
326
  export type SettlementEscrowWire = z.infer<typeof SettlementEscrowZod>;
327
+ export type SettlementBindingWire = z.infer<typeof SettlementBindingZod>;
341
328
  export type SettlementWire = z.infer<typeof SettlementZod>;