@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/dist/index.js CHANGED
@@ -12,11 +12,11 @@ import z from "zod";
12
12
  */
13
13
  const EVM_NATIVE_SENTINEL = "0x0000000000000000000000000000000000000000";
14
14
  /**
15
- * Whether `address` is the EVM-native zero-address sentinel, compared
16
- * case-insensitively. Module-local: the two call-sites below share this exact
17
- * comparison; it is not part of the package's public surface.
15
+ * Whether `address` is the EVM zero address (the native sentinel), compared
16
+ * case-insensitively. Inlined comparison: `compose-spec` cannot import
17
+ * `toAddress` from `@lifi/utils` (see `EVM_NATIVE_SENTINEL`).
18
18
  */
19
- const isNativeSentinel = (address) => address.toLowerCase() === EVM_NATIVE_SENTINEL.toLowerCase();
19
+ const isZeroAddress = (address) => address.toLowerCase() === EVM_NATIVE_SENTINEL.toLowerCase();
20
20
  const TEMPO_CHAIN_ID = 4217;
21
21
  const TEMPO_NATIVE_ERC20 = {
22
22
  token: "0x20C0000000000000000000000000000000000000",
@@ -139,7 +139,7 @@ const isNativeAddressForChain = (chainId, address) => {
139
139
  * `isNativeAddressForChain`, which returns `true` for the stand-in ERC-20
140
140
  * (PathUSD on Tempo) and would wrongly route it to `msg.value`.
141
141
  */
142
- const isMsgValueNative = (chainId, address) => !hasErc20CanonicalNative(chainId) && isNativeSentinel(address);
142
+ const isMsgValueNative = (chainId, address) => !hasErc20CanonicalNative(chainId) && isZeroAddress(address);
143
143
  /**
144
144
  * Rewrite a single `Resource` according to its chain's capabilities.
145
145
  *
@@ -175,12 +175,11 @@ const normalizeResource = (r) => {
175
175
  * chains whose canonical native asset is an ERC-20, the native sentinel is
176
176
  * rewritten to the chain's stand-in ERC-20; every other address passes through.
177
177
  */
178
- const normalizeNativeTokenAddress = (token, chainId) => hasErc20CanonicalNative(chainId) && isNativeSentinel(token) ? canonicalNativeAddress(chainId) : token;
178
+ const normalizeNativeTokenAddress = (token, chainId) => hasErc20CanonicalNative(chainId) && isZeroAddress(token) ? canonicalNativeAddress(chainId) : token;
179
179
  //#endregion
180
180
  //#region src/hexPatterns.ts
181
181
  const BYTES32_LOWER_HEX = /^0x[0-9a-f]{64}$/;
182
182
  const EVM_ADDRESS_HEX = /^0x[0-9a-fA-F]{40}$/;
183
- const HEX_BYTES = /^0x(?:[0-9a-fA-F]{2})*$/;
184
183
  const DECIMAL_UINT = /^[0-9]+$/;
185
184
  const MAX_UINT256 = 2n ** 256n - 1n;
186
185
  const MAX_DATE_MS = 864e13;
@@ -189,7 +188,6 @@ const MAX_DATE_MS = 864e13;
189
188
  const SolTypeSchema = Schema.Literal("uint8", "uint16", "uint32", "uint64", "uint128", "uint256", "int128", "int256", "address", "bool", "bytes", "bytes4", "bytes32", "string");
190
189
  const ChainIdSchema = Schema.Number.pipe(Schema.int(), Schema.positive());
191
190
  const EVMAddressString = Schema.String.pipe(Schema.pattern(EVM_ADDRESS_HEX, { message: () => "expected a 0x-prefixed 20-byte EVM address" })).annotations({ description: "EVM address: 0x followed by 40 hex characters" });
192
- const HexBytesString = Schema.String.pipe(Schema.pattern(HEX_BYTES, { message: () => "expected 0x-prefixed hex of whole bytes" })).annotations({ description: "Hex bytes: 0x followed by an even number of hex characters" });
193
191
  const EpochMsSchema = Schema.Number.pipe(Schema.int(), Schema.between(-864e13, MAX_DATE_MS));
194
192
  const IntegerString = Schema.String.pipe(Schema.filter((value) => {
195
193
  if (!DECIMAL_UINT.test(value)) return "amount must be a decimal integer string";
@@ -263,38 +261,51 @@ const LineageSchema = Schema.Struct({
263
261
  journeyId: UuidSchema,
264
262
  parentRequestId: UuidSchema
265
263
  });
264
+ const ForwardToSchema = Schema.Union(EVMAddressString, RefSchema);
265
+ const EpilogueForwardSchema = Schema.Struct({
266
+ resource: ResourceSchema,
267
+ to: ForwardToSchema
268
+ });
269
+ const EpilogueSchema = Schema.Struct({
270
+ forwards: Schema.optional(Schema.NonEmptyArray(EpilogueForwardSchema)),
271
+ remainder: Schema.optional(ForwardToSchema)
272
+ }).pipe(Schema.filter((e) => e.forwards !== void 0 || e.remainder !== void 0, { message: () => "epilogue needs forwards, a remainder, or both" }));
266
273
  const FlowSchema = Schema.Struct({
267
274
  version: Schema.Literal(1),
268
275
  id: Schema.String,
269
276
  chainId: ChainIdSchema,
270
277
  inputs: Schema.Array(FlowInputSchema),
271
278
  nodes: Schema.Array(CallSchema),
272
- lineage: Schema.optional(LineageSchema)
279
+ lineage: Schema.optional(LineageSchema),
280
+ epilogue: Schema.optional(EpilogueSchema)
273
281
  });
274
282
  //#endregion
275
283
  //#region src/continuation.ts
276
284
  const CONTINUATION_COMMITMENT_OP_ID = "continuation.commitment";
277
- const RawContinuationOutcomeSchema = Schema.Struct({
285
+ const outcomeFields = (minAmount) => ({
278
286
  token: EVMAddressString,
279
- minAmount: IntegerString,
287
+ minAmount,
280
288
  destination: EVMAddressString,
281
289
  chainId: ChainIdSchema
282
290
  });
283
- const ContinuationOutcomeSchema = Schema.transform(RawContinuationOutcomeSchema, Schema.typeSchema(RawContinuationOutcomeSchema), {
291
+ const normalizingOutcome = (raw) => Schema.transform(raw, Schema.typeSchema(raw), {
284
292
  strict: true,
285
- decode: (raw) => ({
286
- ...raw,
287
- token: normalizeNativeTokenAddress(raw.token, raw.chainId)
293
+ decode: (outcome) => ({
294
+ ...outcome,
295
+ token: normalizeNativeTokenAddress(outcome.token, outcome.chainId)
288
296
  }),
289
297
  encode: (outcome) => outcome
290
298
  });
299
+ const ContinuationOutcomeSchema = normalizingOutcome(Schema.Struct(outcomeFields(Schema.optional(IntegerString))));
300
+ const CommittedOutcomeSchema = normalizingOutcome(Schema.Struct(outcomeFields(IntegerString)));
291
301
  const ContinuationIntentSchema = Schema.Struct({
292
302
  outcomes: Schema.NonEmptyArray(ContinuationOutcomeSchema),
293
303
  continuationFlow: Schema.optional(FlowSchema),
294
304
  validity: Schema.Struct({ expiresAtMs: EpochMsSchema }),
295
- perpetual: Schema.optional(Schema.Boolean),
296
305
  provider: Schema.optional(Schema.String),
297
- funding: Schema.optional(Schema.Literal("inline", "external"))
306
+ funding: Schema.optional(Schema.Literal("inline", "external")),
307
+ refund: Schema.optional(EVMAddressString.pipe(Schema.filter((address) => !isZeroAddress(address), { message: () => "refund must not be the zero address" }))),
308
+ exact: Schema.optional(Schema.Boolean)
298
309
  });
299
310
  const HexStringSchema = Schema.String.pipe(Schema.startsWith("0x"));
300
311
  const Phase1EscrowSchema = Schema.Struct({
@@ -303,20 +314,32 @@ const Phase1EscrowSchema = Schema.Struct({
303
314
  token: HexStringSchema,
304
315
  amount: Schema.String,
305
316
  cap: Schema.String,
317
+ floor: Schema.String,
306
318
  owner: HexStringSchema,
307
319
  refund: HexStringSchema,
308
320
  expiresAtMs: Schema.Number.pipe(Schema.int(), Schema.positive())
309
321
  });
322
+ const Phase1BindingSchema = Schema.Struct({
323
+ executionTarget: HexStringSchema,
324
+ payload: HexStringSchema,
325
+ payloadHash: HexStringSchema,
326
+ calldata: HexStringSchema,
327
+ approvals: Schema.Array(Schema.Struct({
328
+ token: HexStringSchema,
329
+ spender: HexStringSchema
330
+ }))
331
+ });
310
332
  const Phase1ArtifactSchema = Schema.Union(Schema.Struct({
311
333
  kind: Schema.Literal("transaction"),
312
- funding: Schema.Literal("inline", "external"),
334
+ funding: Schema.Literal("inline", "external", "delivered"),
313
335
  transactionRequest: Schema.optional(Schema.Struct({
314
336
  to: Schema.String,
315
337
  data: Schema.String,
316
338
  value: Schema.String,
317
339
  chainId: Schema.Number
318
340
  })),
319
- escrow: Schema.optional(Phase1EscrowSchema)
341
+ escrow: Schema.optional(Phase1EscrowSchema),
342
+ binding: Schema.optional(Phase1BindingSchema)
320
343
  }), Schema.Struct({
321
344
  kind: Schema.Literal("signables"),
322
345
  typedData: Schema.Array(Schema.Unknown)
@@ -326,22 +349,23 @@ const Erc20BalanceGteSpecSchema = Schema.Struct({
326
349
  kind: Schema.Literal("erc20BalanceGte"),
327
350
  chainId: ChainIdSchema,
328
351
  token: EVMAddressString,
329
- owner: EVMAddressString,
352
+ owner: AssertionOwnerSchema,
330
353
  minAmount: IntegerString
331
354
  });
332
355
  const NativeBalanceGteSpecSchema = Schema.Struct({
333
356
  kind: Schema.Literal("nativeBalanceGte"),
334
357
  chainId: ChainIdSchema,
335
- owner: EVMAddressString,
358
+ owner: AssertionOwnerSchema,
336
359
  minAmount: IntegerString
337
360
  });
338
361
  const CallCheckSpecSchema = Schema.Struct({
339
362
  kind: Schema.Literal("call"),
340
363
  chainId: ChainIdSchema,
341
364
  to: EVMAddressString,
342
- calldata: HexBytesString,
365
+ signature: Schema.String,
366
+ args: Schema.Array(Schema.String),
343
367
  comparator: Schema.Literal("gte", "eq", "lte"),
344
- value: IntegerString
368
+ threshold: IntegerString
345
369
  });
346
370
  const asErc20BalanceGteCheck = (check, token) => ({
347
371
  kind: "erc20BalanceGte",
@@ -358,39 +382,12 @@ const decodeNativeBalanceGte = (check, ast) => {
358
382
  case "reject": return ParseResult.fail(new ParseResult.Type(ast, check, policy.reason));
359
383
  }
360
384
  };
361
- const Erc20BalanceDeltaGteSpecSchema = Schema.Struct({
362
- kind: Schema.Literal("erc20BalanceDeltaGte"),
363
- chainId: ChainIdSchema,
364
- token: EVMAddressString,
365
- owner: AssertionOwnerSchema,
366
- minDelta: IntegerString
367
- });
368
- const NativeBalanceDeltaGteSpecSchema = Schema.Struct({
369
- kind: Schema.Literal("nativeBalanceDeltaGte"),
370
- chainId: ChainIdSchema,
371
- owner: AssertionOwnerSchema,
372
- minDelta: IntegerString
373
- });
374
- const AssertionSpecSchema = Schema.Union(Erc20BalanceGteSpecSchema, NativeBalanceGteSpecSchema, CallCheckSpecSchema, Erc20BalanceDeltaGteSpecSchema, NativeBalanceDeltaGteSpecSchema);
385
+ const AssertionSpecSchema = Schema.Union(Erc20BalanceGteSpecSchema, NativeBalanceGteSpecSchema, CallCheckSpecSchema);
375
386
  const settledOutcome = (intent) => intent.outcomes[0];
376
387
  //#endregion
377
388
  //#region src/descriptor.ts
378
389
  const Bytes32HexSchema = Schema.String.pipe(Schema.pattern(BYTES32_LOWER_HEX));
379
- const AssertedErc20BalanceGteSpecSchema = Schema.Struct({
380
- kind: Schema.Literal("erc20BalanceGte"),
381
- chainId: ChainIdSchema,
382
- token: EVMAddressString,
383
- owner: AssertionOwnerSchema,
384
- minAmount: IntegerString
385
- });
386
- const AssertedNativeBalanceGteSpecSchema = Schema.Struct({
387
- kind: Schema.Literal("nativeBalanceGte"),
388
- chainId: ChainIdSchema,
389
- owner: AssertionOwnerSchema,
390
- minAmount: IntegerString
391
- });
392
- const RawAssertedPredicateSchema = Schema.Union(AssertedErc20BalanceGteSpecSchema, AssertedNativeBalanceGteSpecSchema, CallCheckSpecSchema, Erc20BalanceDeltaGteSpecSchema, NativeBalanceDeltaGteSpecSchema);
393
- const AssertedPredicateSchema = Schema.transformOrFail(RawAssertedPredicateSchema, Schema.typeSchema(RawAssertedPredicateSchema), {
390
+ const AssertedPredicateSchema = Schema.transformOrFail(AssertionSpecSchema, Schema.typeSchema(AssertionSpecSchema), {
394
391
  strict: true,
395
392
  decode: (pred, _options, ast) => pred.kind === "nativeBalanceGte" ? decodeNativeBalanceGte(pred, ast) : ParseResult.succeed(pred),
396
393
  encode: (pred) => ParseResult.succeed(pred)
@@ -434,18 +431,24 @@ const nativeResource = (chainId) => ({
434
431
  const isERC20Resource = (r) => r.kind === "erc20";
435
432
  const isNativeResource = (r) => r.kind === "native";
436
433
  const resourcesEqual = (a, b) => {
437
- if (isNativeResource(a) && isNativeResource(b)) return a.chainId === b.chainId;
438
- if (isERC20Resource(a) && isERC20Resource(b)) return a.chainId === b.chainId && a.token.toLowerCase() === b.token.toLowerCase();
439
- return false;
434
+ switch (a.kind) {
435
+ case "native": return b.kind === "native" && a.chainId === b.chainId;
436
+ case "erc20": return b.kind === "erc20" && a.chainId === b.chainId && a.token.toLowerCase() === b.token.toLowerCase();
437
+ }
438
+ };
439
+ const foldResource = (r, cases) => {
440
+ switch (r.kind) {
441
+ case "native": return cases.native(r);
442
+ case "erc20": return cases.erc20(r);
443
+ }
440
444
  };
441
- const foldResource = (r, cases) => r.kind === "native" ? cases.native(r.chainId) : cases.erc20(r.token, r.chainId);
442
445
  const resourceToken = (r) => foldResource(r, {
443
446
  native: () => EVM_NATIVE_SENTINEL,
444
- erc20: (token) => token
447
+ erc20: ({ token }) => token
445
448
  });
446
449
  const resourceKey = (r) => foldResource(r, {
447
- native: (chainId) => `native:${chainId}`,
448
- erc20: (token, chainId) => `erc20:${token.toLowerCase()}:${chainId}`
450
+ native: ({ chainId }) => `native:${chainId}`,
451
+ erc20: ({ token, chainId }) => `erc20:${token.toLowerCase()}:${chainId}`
449
452
  });
450
453
  const erc20Token = (r) => {
451
454
  if (r.kind !== "erc20") throw new Error(`Expected erc20 resource, got ${r.kind}`);
@@ -728,13 +731,12 @@ const foldMaterialiserMetadata = (meta, cases) => {
728
731
  if (meta.kind === "exact") return cases.exact(meta.amount);
729
732
  if (meta.kind === "exact-native") return cases.exactNative(meta.amount);
730
733
  if (meta.kind === "capped") return cases.capped(meta.amount, meta.min);
731
- return cases.runtime();
734
+ return cases.runtime(meta.min);
732
735
  };
733
736
  //#endregion
734
737
  //#region src/zodSchemas.ts
735
738
  const chainIdZod = z.number().int().positive();
736
739
  const evmAddressZod = z.string().regex(EVM_ADDRESS_HEX);
737
- const hexBytesZod = z.string().regex(HEX_BYTES);
738
740
  const uintStringZod = z.string().refine((value) => DECIMAL_UINT.test(value) && BigInt(value) <= MAX_UINT256, { message: "expected a uint256 decimal integer string" });
739
741
  const SolTypeZod = z.enum([
740
742
  "uint8",
@@ -862,6 +864,10 @@ const ManifestPreconditionZod = z.object({
862
864
  description: z.string().optional(),
863
865
  configSchema: z.unknown().optional()
864
866
  });
867
+ const ManifestRoutingZod = z.object({
868
+ maxRouteHops: z.number().int().min(1),
869
+ swapHops: z.enum(["head", "none"])
870
+ });
865
871
  const ComposeManifestZod = z.object({
866
872
  manifestVersion: z.number(),
867
873
  manifestHash: z.string(),
@@ -869,7 +875,8 @@ const ComposeManifestZod = z.object({
869
875
  operations: z.array(ManifestOperationZod),
870
876
  guards: z.array(ManifestGuardZod),
871
877
  materialisers: z.array(ManifestMaterialiserZod),
872
- preconditions: z.array(ManifestPreconditionZod).optional()
878
+ preconditions: z.array(ManifestPreconditionZod).optional(),
879
+ routing: ManifestRoutingZod.optional()
873
880
  });
874
881
  const hexStringZod = z.string().startsWith("0x");
875
882
  const SettlementEscrowZod = z.object({
@@ -878,79 +885,58 @@ const SettlementEscrowZod = z.object({
878
885
  token: hexStringZod,
879
886
  amount: z.string(),
880
887
  cap: z.string(),
888
+ floor: z.string(),
881
889
  owner: hexStringZod,
882
890
  refund: hexStringZod,
883
891
  expiresAtMs: z.number().int().positive()
884
892
  });
893
+ const SettlementBindingZod = z.object({
894
+ executionTarget: hexStringZod,
895
+ payload: hexStringZod,
896
+ payloadHash: hexStringZod,
897
+ calldata: hexStringZod,
898
+ approvals: z.array(z.object({
899
+ token: hexStringZod,
900
+ spender: hexStringZod
901
+ })).readonly()
902
+ });
885
903
  const assertionOwnerZod = z.union([evmAddressZod, z.enum(["escrow", "delivery"])]);
886
904
  const AssertionSpecZod = z.discriminatedUnion("kind", [
887
905
  z.object({
888
906
  kind: z.literal("erc20BalanceGte"),
889
907
  chainId: chainIdZod,
890
908
  token: evmAddressZod,
891
- owner: evmAddressZod,
909
+ owner: assertionOwnerZod,
892
910
  minAmount: uintStringZod
893
911
  }),
894
912
  z.object({
895
913
  kind: z.literal("nativeBalanceGte"),
896
914
  chainId: chainIdZod,
897
- owner: evmAddressZod,
915
+ owner: assertionOwnerZod,
898
916
  minAmount: uintStringZod
899
917
  }),
900
918
  z.object({
901
919
  kind: z.literal("call"),
902
920
  chainId: chainIdZod,
903
921
  to: evmAddressZod,
904
- calldata: hexBytesZod,
922
+ signature: z.string(),
923
+ args: z.array(z.string()).readonly(),
905
924
  comparator: z.enum([
906
925
  "gte",
907
926
  "eq",
908
927
  "lte"
909
928
  ]),
910
- value: uintStringZod
911
- }),
912
- z.object({
913
- kind: z.literal("erc20BalanceDeltaGte"),
914
- chainId: z.number().int().positive(),
915
- token: evmAddressZod,
916
- owner: assertionOwnerZod,
917
- minDelta: uintStringZod
918
- }),
919
- z.object({
920
- kind: z.literal("nativeBalanceDeltaGte"),
921
- chainId: z.number().int().positive(),
922
- owner: assertionOwnerZod,
923
- minDelta: uintStringZod
929
+ threshold: uintStringZod
924
930
  })
925
931
  ]);
926
- const assertionSpecOptionByKind = (kind) => {
927
- const option = AssertionSpecZod.options.find((o) => o.shape.kind.value === kind);
928
- if (option === void 0) throw new Error(`AssertionSpecZod has no member with kind "${kind}"`);
929
- return option;
930
- };
931
- const AssertedPredicateZod = z.discriminatedUnion("kind", [
932
- z.object({
933
- kind: z.literal("erc20BalanceGte"),
934
- chainId: z.number().int().positive(),
935
- token: evmAddressZod,
936
- owner: assertionOwnerZod,
937
- minAmount: uintStringZod
938
- }),
939
- z.object({
940
- kind: z.literal("nativeBalanceGte"),
941
- chainId: z.number().int().positive(),
942
- owner: assertionOwnerZod,
943
- minAmount: uintStringZod
944
- }),
945
- assertionSpecOptionByKind("call"),
946
- assertionSpecOptionByKind("erc20BalanceDeltaGte"),
947
- assertionSpecOptionByKind("nativeBalanceDeltaGte")
948
- ]);
949
932
  const VerificationDescriptorZod = z.object({
950
933
  validationProgramHash: z.string().regex(BYTES32_LOWER_HEX),
951
934
  paramsHash: z.string().regex(BYTES32_LOWER_HEX),
952
- assertedPredicate: z.array(AssertedPredicateZod)
935
+ assertedPredicate: z.array(AssertionSpecZod).readonly()
936
+ });
937
+ const SettlementZod = z.object({
938
+ escrow: SettlementEscrowZod.optional(),
939
+ binding: SettlementBindingZod.optional()
953
940
  });
954
- const SettlementZod = z.object({ escrow: SettlementEscrowZod.optional() });
955
941
  //#endregion
956
- export { ARC_CHAIN_ID, ARC_NATIVE_ERC20, ARC_NATIVE_SCALE, AppliedGuardSchema, AssertedErc20BalanceGteSpecSchema, AssertedNativeBalanceGteSpecSchema, AssertedPredicateSchema, AssertedPredicateZod, AssertionOwnerSchema, AssertionSpecSchema, AssertionSpecZod, BindValueSchema, Bytes32HexSchema, COMPOSER_SDK_VERSION_HEADER, COMPOSE_VERSION_HEADER, CONTINUATION_COMMITMENT_OP_ID, CallCheckSpecSchema, CallSchema, ComposeManifestZod, ContinuationIntentSchema, ContinuationOutcomeSchema, EVMAddressString, EVM_NATIVE_SENTINEL, Erc20BalanceDeltaGteSpecSchema, Erc20BalanceGteSpecSchema, FlowInputSchema, FlowSchema, GuardCompatibilityZod, GuardSelectorZod, HANDLE_UNITS, HandleInputSchema, HandlePortZod, HandleUnitsZod, HexStringSchema, InputPortZod, IntegerString, LineageSchema, LiteralBindingSchema, ManifestGuardZod, ManifestMaterialiserZod, ManifestOperationZod, ManifestPreconditionZod, NativeBalanceDeltaGteSpecSchema, NativeBalanceGteSpecSchema, OutputPortZod, PROVIDER_KIND, Phase1ArtifactSchema, RESERVED_REF_SCOPES, RefSchema, ResourceInputSchema, ResourceOutputPortZod, ResourcePortZod, ResourceSchema, SIMULATE_MAX_REQUIREMENTS, SIMULATE_MAX_TRACKED_BALANCES, STATIC_SOL_TYPES, SettlementZod, SolTypeSchema, StaticSolTypeZod, TEMPO_CHAIN_ID, TEMPO_NATIVE_ERC20, UuidSchema, VerificationDescriptorSchema, VerificationDescriptorZod, canonicalAssertedPredicate, canonicalNativeAddress, checkCompatibility, copy, erc20, erc20Allowance, erc20Balance, erc20Resource, erc20Token, expandOutputPorts, familySize, flowInputMode, flowInputResource, flowInputType, foldChainCapabilities, foldMaterialiserMetadata, foldRef, foldResource, getChainCapabilities, handle, hasErc20CanonicalNative, instancePortName, isAsErc20Chain, isContextKey, isERC20Resource, isErc20AllowancePrecondition, isErc20BalancePrecondition, isFutureResourceOutput, isHandlePort, isMaterialiserInput, isMsgValueNative, isNativeAddressForChain, isNativeBalancePrecondition, isNativeResource, isOutputFamily, isRef, isResourceInput, isResourceOutputPort, isResourcePort, isStaticSolType, linear, native, nativeBalance, nativeCheckPolicy, nativeResource, normalizeNativeTokenAddress, normalizeResource, opHandle, parseRef, parseVersion, providerKindByName, providerKindNames, readResource, ref, refKey, resource, resourceKey, resourceOutput, resourceToken, resourcesEqual, settledOutcome };
942
+ export { ARC_CHAIN_ID, ARC_NATIVE_ERC20, ARC_NATIVE_SCALE, AppliedGuardSchema, AssertedPredicateSchema, AssertionOwnerSchema, AssertionSpecSchema, AssertionSpecZod, BindValueSchema, Bytes32HexSchema, COMPOSER_SDK_VERSION_HEADER, COMPOSE_VERSION_HEADER, CONTINUATION_COMMITMENT_OP_ID, CallCheckSpecSchema, CallSchema, CommittedOutcomeSchema, ComposeManifestZod, ContinuationIntentSchema, ContinuationOutcomeSchema, EVMAddressString, EVM_NATIVE_SENTINEL, EpilogueForwardSchema, EpilogueSchema, Erc20BalanceGteSpecSchema, FlowInputSchema, FlowSchema, ForwardToSchema, GuardCompatibilityZod, GuardSelectorZod, HANDLE_UNITS, HandleInputSchema, HandlePortZod, HandleUnitsZod, HexStringSchema, InputPortZod, IntegerString, LineageSchema, LiteralBindingSchema, ManifestGuardZod, ManifestMaterialiserZod, ManifestOperationZod, ManifestPreconditionZod, ManifestRoutingZod, NativeBalanceGteSpecSchema, OutputPortZod, PROVIDER_KIND, Phase1ArtifactSchema, RESERVED_REF_SCOPES, RefSchema, ResourceInputSchema, ResourceOutputPortZod, ResourcePortZod, ResourceSchema, SIMULATE_MAX_REQUIREMENTS, SIMULATE_MAX_TRACKED_BALANCES, STATIC_SOL_TYPES, SettlementZod, SolTypeSchema, StaticSolTypeZod, TEMPO_CHAIN_ID, TEMPO_NATIVE_ERC20, UuidSchema, VerificationDescriptorSchema, VerificationDescriptorZod, canonicalAssertedPredicate, canonicalNativeAddress, checkCompatibility, copy, erc20, erc20Allowance, erc20Balance, erc20Resource, erc20Token, expandOutputPorts, familySize, flowInputMode, flowInputResource, flowInputType, foldChainCapabilities, foldMaterialiserMetadata, foldRef, foldResource, getChainCapabilities, handle, hasErc20CanonicalNative, instancePortName, isAsErc20Chain, isContextKey, isERC20Resource, isErc20AllowancePrecondition, isErc20BalancePrecondition, isFutureResourceOutput, isHandlePort, isMaterialiserInput, isMsgValueNative, isNativeAddressForChain, isNativeBalancePrecondition, isNativeResource, isOutputFamily, isRef, isResourceInput, isResourceOutputPort, isResourcePort, isStaticSolType, linear, native, nativeBalance, nativeCheckPolicy, nativeResource, normalizeNativeTokenAddress, normalizeResource, opHandle, parseRef, parseVersion, providerKindByName, providerKindNames, readResource, ref, refKey, resource, resourceKey, resourceOutput, resourceToken, resourcesEqual, settledOutcome };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@lifi/compose-spec",
3
- "version": "0.10.0",
3
+ "version": "0.12.0",
4
4
  "description": "Public wire-format types and schemas for Compose flows",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {
@@ -65,11 +65,11 @@ export const EVM_NATIVE_SENTINEL: `0x${string}` =
65
65
  '0x0000000000000000000000000000000000000000';
66
66
 
67
67
  /**
68
- * Whether `address` is the EVM-native zero-address sentinel, compared
69
- * case-insensitively. Module-local: the two call-sites below share this exact
70
- * comparison; it is not part of the package's public surface.
68
+ * Whether `address` is the EVM zero address (the native sentinel), compared
69
+ * case-insensitively. Inlined comparison: `compose-spec` cannot import
70
+ * `toAddress` from `@lifi/utils` (see `EVM_NATIVE_SENTINEL`).
71
71
  */
72
- const isNativeSentinel = (address: string): boolean =>
72
+ export const isZeroAddress = (address: string): boolean =>
73
73
  address.toLowerCase() === EVM_NATIVE_SENTINEL.toLowerCase();
74
74
 
75
75
  export const TEMPO_CHAIN_ID = 4217;
@@ -291,7 +291,7 @@ export const isNativeAddressForChain = (
291
291
  * (PathUSD on Tempo) and would wrongly route it to `msg.value`.
292
292
  */
293
293
  export const isMsgValueNative = (chainId: number, address: string): boolean =>
294
- !hasErc20CanonicalNative(chainId) && isNativeSentinel(address);
294
+ !hasErc20CanonicalNative(chainId) && isZeroAddress(address);
295
295
 
296
296
  /**
297
297
  * Rewrite a single `Resource` according to its chain's capabilities.
@@ -333,6 +333,6 @@ export const normalizeNativeTokenAddress = (
333
333
  token: string,
334
334
  chainId: number,
335
335
  ): string =>
336
- hasErc20CanonicalNative(chainId) && isNativeSentinel(token)
336
+ hasErc20CanonicalNative(chainId) && isZeroAddress(token)
337
337
  ? canonicalNativeAddress(chainId)
338
338
  : token;
package/src/compile.ts CHANGED
@@ -1,27 +1,22 @@
1
1
  import type { VerificationDescriptor } from './descriptor.js';
2
2
  import type { InputSpec, Precondition } from './flow.js';
3
- import type { Flow } from './flowSchema.js';
3
+ import type { Flow, ForwardTo } from './flowSchema.js';
4
4
  import type { Outputs } from './output.js';
5
+ import type { Resource } from './resource.js';
5
6
  import type { SettlementWire } from './zodSchemas.js';
6
7
 
7
8
  export type SimulationPolicy = 'strict' | 'allow-revert';
8
9
 
9
- /**
10
- * Destination for sweeping proxy-held terminal resources after execution.
11
- * Either a literal EVM address or a `{ $ref }` context reference
12
- * (e.g. `{ $ref: "context.sender" }`).
13
- */
14
- export type SweepTo = string | { readonly $ref: string };
15
-
16
10
  export interface ComposeRun {
17
11
  readonly inputs: Record<string, InputSpec>;
18
12
  readonly preconditions?: readonly Precondition[];
19
13
  readonly signer: string;
20
14
  readonly assumptions?: Record<string, bigint>;
21
15
  readonly referrer?: string;
22
- readonly integratorFeeBps?: number;
23
16
  readonly maxPriceImpactBps?: number;
24
- readonly sweepTo?: SweepTo;
17
+ // Sugar for `flow.epilogue.remainder`; zap-backend desugars it before the
18
+ // compile.
19
+ readonly sweepTo?: ForwardTo;
25
20
  readonly simulationPolicy?: SimulationPolicy;
26
21
  /**
27
22
  * Also simulate the final user-facing transaction. Defaults to `false`;
@@ -125,22 +120,6 @@ export interface SpendEntry {
125
120
  readonly nodeId?: string;
126
121
  }
127
122
 
128
- // One fee row per (input, recipient), as the compiled fill charges it.
129
- // Hand-mirrored from api-schemas' `ComposeFeeSchema` (the OpenAPI source of
130
- // truth; this package cannot depend on it). `recipient` names WHO is charged
131
- // — never an address; the address is the sibling `recipientAddress`. `amount`
132
- // is absent when the gross is only known on-chain at execution time (a
133
- // balance-materialiser input).
134
- export interface ComposeFee {
135
- readonly input: string;
136
- // Zero address for native, otherwise the ERC-20 contract.
137
- readonly token: string;
138
- readonly recipient: 'lifi' | 'integrator';
139
- readonly recipientAddress: string;
140
- readonly bps: number;
141
- readonly amount?: string;
142
- }
143
-
144
123
  // The optional user-program simulation result, present only when the request
145
124
  // opted in via `run.simulateUserProgram` and the simulation succeeded.
146
125
  // Hand-mirrored from api-schemas' `ComposeUserProgramSimulationOkSchema`.
@@ -149,6 +128,19 @@ export interface ComposeUserProgramSimulation {
149
128
  readonly returnData: string;
150
129
  }
151
130
 
131
+ // One advisory finding the compiler raised without failing the compile, e.g. a
132
+ // tight slippage bound on a highly volatile token. Hand-mirrored from
133
+ // api-schemas' `ComposeWarningSchema`. `path`, `port`, and `fix` mean what they
134
+ // mean on a compile error. `kind` is an open set: a new kind ships in a patch
135
+ // release, so a reader must tolerate a kind it does not know.
136
+ export interface ComposeWarning {
137
+ readonly kind: string;
138
+ readonly message: string;
139
+ readonly path?: string;
140
+ readonly port?: string;
141
+ readonly fix?: string;
142
+ }
143
+
152
144
  // The solver-extractable fill (verified continuations, GD-8/GD-6, seam C5),
153
145
  // present on every compiled success. Hand-mirrored to api-schemas' `fill`
154
146
  // object (the OpenAPI source of truth; this package cannot depend on it).
@@ -163,21 +155,38 @@ export interface ComposeFill {
163
155
  readonly validUntilMs?: number;
164
156
  }
165
157
 
158
+ // One named epilogue forward as executed: the proxy's whole balance of
159
+ // `resource`, moved to `to`, as the simulation measured it. Hand-mirrored from
160
+ // api-schemas' `ExecutedForwardSchema`; the SDK decodes `amount` to `bigint`.
161
+ export interface ExecutedForward {
162
+ readonly resource: Resource;
163
+ readonly to: string;
164
+ readonly amount: bigint;
165
+ }
166
+
167
+ // The flow's epilogue as executed. The remainder is not measured: it reports
168
+ // its resolved address only, and its effect on `outputs` is a re-owned
169
+ // `owner`. Absent when the flow has no epilogue (and never on a partial
170
+ // result, which measured nothing).
171
+ export interface ExecutedEpilogue {
172
+ readonly forwards: readonly ExecutedForward[];
173
+ readonly remainder?: string;
174
+ }
175
+
166
176
  export interface ComposeCompileSuccessData extends ComposeContinuationData {
167
177
  // Every linear resource output port, consumed or terminal, keyed
168
- // `<nodeId>.<portName>`. See `Output` for the per-entry rules. Hand-mirrored
178
+ // `<nodeId>.<portName>`, and every resource input no node spends, keyed
179
+ // `input.<name>`. See `Output` for the per-entry rules. Hand-mirrored
169
180
  // from api-schemas' `OutputSchema` (the OpenAPI source of truth; this
170
181
  // package cannot depend on it); the SDK decodes the wire strings to `bigint`.
171
182
  readonly outputs: Outputs;
183
+ readonly epilogue?: ExecutedEpilogue;
172
184
  // The OpenAPI source of truth documents the optionality and funding modes.
173
185
  readonly transactionRequest?: ComposeTransactionRequest;
174
186
  readonly actions?: readonly ComposeAction[];
175
187
  readonly userProxy: string;
176
188
  readonly priceImpact?: PriceImpact;
177
189
  readonly approvals?: readonly ApprovalEntry[];
178
- // The per-(input, recipient) fee rows the compiled fill charges. Absent when
179
- // no fee applies.
180
- readonly fees?: readonly ComposeFee[];
181
190
  // The optional user-program simulation echo, present only when the request
182
191
  // opted in via `run.simulateUserProgram` and the simulation succeeded.
183
192
  readonly userProgramSimulation?: ComposeUserProgramSimulation;
@@ -192,6 +201,9 @@ export interface ComposeCompileSuccessData extends ComposeContinuationData {
192
201
  // committed a validation program; one entry per committing node, so a
193
202
  // fan-out across committed settles carries several.
194
203
  readonly verificationByNode?: Record<string, VerificationDescriptor>;
204
+ // Advisory findings in the order the compiler raised them. Absent when it
205
+ // raised none; never an empty array.
206
+ readonly warnings?: readonly ComposeWarning[];
195
207
  }
196
208
 
197
209
  export interface ComposeCompilePartialData extends ComposeContinuationData {
@@ -203,12 +215,12 @@ export interface ComposeCompilePartialData extends ComposeContinuationData {
203
215
  readonly simulationRevert: SimulationRevert;
204
216
  readonly approvals?: readonly ApprovalEntry[];
205
217
  readonly actions?: readonly ComposeAction[];
206
- // The per-(input, recipient) fee rows the compiled fill charges. Absent when
207
- // no fee applies.
208
- readonly fees?: readonly ComposeFee[];
209
218
  // The optional user-program simulation echo, present only when the request
210
219
  // opted in via `run.simulateUserProgram` and the simulation succeeded.
211
220
  readonly userProgramSimulation?: ComposeUserProgramSimulation;
221
+ // Mirrors `ComposeCompileSuccessData.warnings`: a reverted compile keeps the
222
+ // warnings its compile raised.
223
+ readonly warnings?: readonly ComposeWarning[];
212
224
  }
213
225
 
214
226
  export type ComposeCompileResult =