@lifi/compose-spec 0.4.1 → 0.5.1

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/README.md CHANGED
@@ -16,7 +16,7 @@ npm install @lifi/compose-spec
16
16
  - **Resource types** — `Resource`, `Availability`, `OutputAmount`, `SimulatedAmounts`, plus helpers like `erc20Token`, `foldResource`, `resourceKey`
17
17
  - **Manifest types** — `ComposeManifest`, `ManifestOperation`, `ManifestGuard`, `ManifestMaterialiser`, `ManifestPrecondition`
18
18
  - **Port types** — `ResourcePort`, `HandlePort`, `OpInputPort`, `OpOutputPort`, and type guards
19
- - **Ref utilities** — `parseRef`, `foldRef`, `refKey` for working with flow references
19
+ - **Ref utilities** — `ref` to build bind refs (`ref.input('amount')`, `ref.context.sender`, `ref('nodeId.port')`), plus `parseRef`, `foldRef`, `refKey` for working with flow references
20
20
  - **Constructors** — `linear`, `copy`, `handle`, `native`, `erc20`, `resource`, `readResource`, `opHandle`, `resourceOutput`
21
21
  - **Zod schemas** — Runtime validation for manifests, ports, guards, and operations
22
22
  - **Effect schemas** — `FlowSchema`, `ResourceSchema`, `CallSchema`, etc. for flow document validation
package/dist/index.cjs CHANGED
@@ -40,6 +40,8 @@ __export(index_exports, {
40
40
  AssertionSpecZod: () => AssertionSpecZod,
41
41
  BindValueSchema: () => BindValueSchema,
42
42
  Bytes32HexSchema: () => Bytes32HexSchema,
43
+ COMPOSER_SDK_VERSION_HEADER: () => COMPOSER_SDK_VERSION_HEADER,
44
+ COMPOSE_VERSION_HEADER: () => COMPOSE_VERSION_HEADER,
43
45
  CONTINUATION_COMMITMENT_OP_ID: () => CONTINUATION_COMMITMENT_OP_ID,
44
46
  CallCheckSpecSchema: () => CallCheckSpecSchema,
45
47
  CallSchema: () => CallSchema,
@@ -50,7 +52,6 @@ __export(index_exports, {
50
52
  ContinuationOutcomeSchema: () => ContinuationOutcomeSchema,
51
53
  ContinuationPlanSchema: () => ContinuationPlanSchema,
52
54
  ContinuationPlanZod: () => ContinuationPlanZod,
53
- ContinuationSchema: () => ContinuationSchema,
54
55
  EVM_NATIVE_SENTINEL: () => EVM_NATIVE_SENTINEL,
55
56
  Erc20BalanceDeltaGteSpecSchema: () => Erc20BalanceDeltaGteSpecSchema,
56
57
  Erc20BalanceGteSpecSchema: () => Erc20BalanceGteSpecSchema,
@@ -92,6 +93,7 @@ __export(index_exports, {
92
93
  VerificationDescriptorZod: () => VerificationDescriptorZod,
93
94
  canonicalAssertedPredicate: () => canonicalAssertedPredicate,
94
95
  canonicalNativeAddress: () => canonicalNativeAddress,
96
+ checkCompatibility: () => checkCompatibility,
95
97
  copy: () => copy,
96
98
  erc20: () => erc20,
97
99
  erc20Allowance: () => erc20Allowance,
@@ -106,7 +108,6 @@ __export(index_exports, {
106
108
  foldResource: () => foldResource,
107
109
  getChainCapabilities: () => getChainCapabilities,
108
110
  handle: () => handle,
109
- inputRef: () => inputRef,
110
111
  isAsErc20Chain: () => isAsErc20Chain,
111
112
  isContextKey: () => isContextKey,
112
113
  isEQCheck: () => isEQCheck,
@@ -133,11 +134,12 @@ __export(index_exports, {
133
134
  normalizeNativeTokenAddress: () => normalizeNativeTokenAddress,
134
135
  normalizeResource: () => normalizeResource,
135
136
  opHandle: () => opHandle,
136
- outputRef: () => outputRef,
137
137
  parseRef: () => parseRef,
138
+ parseVersion: () => parseVersion,
138
139
  providerKindByName: () => providerKindByName,
139
140
  providerKindNames: () => providerKindNames,
140
141
  readResource: () => readResource,
142
+ ref: () => ref,
141
143
  refKey: () => refKey,
142
144
  resource: () => resource,
143
145
  resourceKey: () => resourceKey,
@@ -275,17 +277,12 @@ var CallSchema = import_effect.Schema.Struct({
275
277
  ),
276
278
  guards: import_effect.Schema.optional(import_effect.Schema.Array(AppliedGuardSchema))
277
279
  });
278
- var ContinuationSchema = import_effect.Schema.Struct({
279
- awaits: import_effect.Schema.String,
280
- flowId: import_effect.Schema.String
281
- });
282
280
  var FlowSchema = import_effect.Schema.Struct({
283
281
  version: import_effect.Schema.Literal(1),
284
282
  id: import_effect.Schema.String,
285
283
  chainId: ChainIdSchema,
286
284
  inputs: import_effect.Schema.Array(FlowInputSchema),
287
- nodes: import_effect.Schema.Array(CallSchema),
288
- continuations: import_effect.Schema.optional(import_effect.Schema.Array(ContinuationSchema))
285
+ nodes: import_effect.Schema.Array(CallSchema)
289
286
  });
290
287
 
291
288
  // src/continuation.ts
@@ -315,16 +312,21 @@ var ContinuationIntentSchema = import_effect2.Schema.Struct({
315
312
  continuationFlow: import_effect2.Schema.optional(FlowSchema),
316
313
  validity: import_effect2.Schema.Struct({ expiresAtMs: import_effect2.Schema.Number }),
317
314
  perpetual: import_effect2.Schema.optional(import_effect2.Schema.Boolean),
318
- provider: import_effect2.Schema.optional(import_effect2.Schema.String)
315
+ provider: import_effect2.Schema.optional(import_effect2.Schema.String),
316
+ // Funding-path mode. The HTTP wire contract is documented by
317
+ // `ComposeActionsSchema` in `@lifi/api-schemas`.
318
+ funding: import_effect2.Schema.optional(import_effect2.Schema.Literal("inline", "external"))
319
319
  });
320
320
  var Phase1ArtifactSchema = import_effect2.Schema.Union(
321
321
  import_effect2.Schema.Struct({
322
322
  kind: import_effect2.Schema.Literal("transaction"),
323
+ funding: import_effect2.Schema.Literal("inline", "external"),
323
324
  transactionRequest: import_effect2.Schema.optional(
324
325
  import_effect2.Schema.Struct({
325
326
  to: import_effect2.Schema.String,
326
327
  data: import_effect2.Schema.String,
327
- value: import_effect2.Schema.String
328
+ value: import_effect2.Schema.String,
329
+ chainId: import_effect2.Schema.Number
328
330
  })
329
331
  )
330
332
  }),
@@ -544,10 +546,6 @@ var providerKindByName = {
544
546
  };
545
547
 
546
548
  // src/constructors.ts
547
- var inputRef = (port) => ({ $ref: `input.${port}` });
548
- var outputRef = (node, port) => ({
549
- $ref: `${node}.${port}`
550
- });
551
549
  var optionalProp = (key, value) => value !== void 0 && value !== null ? { [key]: value } : {};
552
550
  var linear = (name, type) => ({
553
551
  name,
@@ -614,12 +612,12 @@ var RESERVED_REF_SCOPES = /* @__PURE__ */ new Set([
614
612
  "literal"
615
613
  ]);
616
614
  var isRef = (v) => typeof v === "object" && v !== null && "$ref" in v && typeof v.$ref === "string";
617
- var parseRef = (ref) => {
618
- const dot = ref.$ref.indexOf(".");
615
+ var parseRef = (ref2) => {
616
+ const dot = ref2.$ref.indexOf(".");
619
617
  if (dot === -1)
620
- throw new Error(`Invalid ref: "${ref.$ref}" (must contain a dot)`);
621
- const prefix = ref.$ref.slice(0, dot);
622
- const suffix = ref.$ref.slice(dot + 1);
618
+ throw new Error(`Invalid ref: "${ref2.$ref}" (must contain a dot)`);
619
+ const prefix = ref2.$ref.slice(0, dot);
620
+ const suffix = ref2.$ref.slice(dot + 1);
623
621
  if (prefix === "input") return { scope: "input", port: suffix };
624
622
  if (prefix === "context") {
625
623
  if (!isContextKey(suffix))
@@ -628,12 +626,28 @@ var parseRef = (ref) => {
628
626
  }
629
627
  return { scope: "output", node: prefix, port: suffix };
630
628
  };
631
- var foldRef = (ref, cases) => {
632
- if (ref.scope === "input") return cases.input(ref.port);
633
- if (ref.scope === "context") return cases.context(ref.key);
634
- return cases.output(ref.node, ref.port);
629
+ var buildRef = (path) => {
630
+ if (path.indexOf(".") < 1)
631
+ throw new Error(
632
+ `Invalid ref: "${path}" (must be a dotpath like "input.name" or "nodeId.port")`
633
+ );
634
+ const built = { $ref: path };
635
+ parseRef(built);
636
+ return built;
637
+ };
638
+ var ref = Object.assign(buildRef, {
639
+ input: (port) => buildRef(`input.${port}`),
640
+ context: {
641
+ sender: buildRef("context.sender"),
642
+ executionAddress: buildRef("context.executionAddress")
643
+ }
644
+ });
645
+ var foldRef = (ref2, cases) => {
646
+ if (ref2.scope === "input") return cases.input(ref2.port);
647
+ if (ref2.scope === "context") return cases.context(ref2.key);
648
+ return cases.output(ref2.node, ref2.port);
635
649
  };
636
- var refKey = (ref) => foldRef(parseRef(ref), {
650
+ var refKey = (ref2) => foldRef(parseRef(ref2), {
637
651
  input: (port) => `input:${port}`,
638
652
  context: (key) => `context:${key}`,
639
653
  output: (node, port) => `output:${node}:${port}`
@@ -650,6 +664,31 @@ var isNativeBalancePrecondition = (p) => p.type === "NativeBalance";
650
664
  var SIMULATE_MAX_TRACKED_BALANCES = 40;
651
665
  var SIMULATE_MAX_REQUIREMENTS = 40;
652
666
 
667
+ // src/headers.ts
668
+ var COMPOSER_SDK_VERSION_HEADER = "x-lifi-composer-sdk";
669
+ var COMPOSE_VERSION_HEADER = "x-lifi-composer-version";
670
+
671
+ // src/version.ts
672
+ var SEMANTIC_VERSION_PATTERN = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*)(?:\.(?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*))*))?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
673
+ var parseVersion = (version) => {
674
+ const match = SEMANTIC_VERSION_PATTERN.exec(version);
675
+ if (!match) return void 0;
676
+ const major = Number(match[1]);
677
+ const minor = Number(match[2]);
678
+ const patch = Number(match[3]);
679
+ if (![major, minor, patch].every(Number.isSafeInteger)) return void 0;
680
+ return { major, minor, patch };
681
+ };
682
+ var compareVersions = (a, b) => a.major !== b.major ? a.major - b.major : a.minor !== b.minor ? a.minor - b.minor : a.patch - b.patch;
683
+ var checkCompatibility = (client, server) => {
684
+ const order = compareVersions(client, server);
685
+ if (order > 0) return "server_outdated";
686
+ if (client.major !== server.major || client.minor !== server.minor) {
687
+ return "sdk_outdated";
688
+ }
689
+ return "compatible";
690
+ };
691
+
653
692
  // src/materialiserMetadata.ts
654
693
  var foldMaterialiserMetadata = (meta, cases) => {
655
694
  if (meta.kind === "exact") return cases.exact(meta.amount);
@@ -794,11 +833,7 @@ var ComposeManifestZod = import_zod.default.object({
794
833
  var Phase1ArtifactZod = import_zod.default.discriminatedUnion("kind", [
795
834
  import_zod.default.object({
796
835
  kind: import_zod.default.literal("transaction"),
797
- transactionRequest: import_zod.default.object({
798
- to: import_zod.default.string(),
799
- data: import_zod.default.string(),
800
- value: import_zod.default.string()
801
- }).optional()
836
+ funding: import_zod.default.enum(["inline", "external"])
802
837
  }),
803
838
  import_zod.default.object({
804
839
  kind: import_zod.default.literal("signables"),
@@ -906,6 +941,8 @@ var ContinuationPlanZod = import_zod.default.object({
906
941
  AssertionSpecZod,
907
942
  BindValueSchema,
908
943
  Bytes32HexSchema,
944
+ COMPOSER_SDK_VERSION_HEADER,
945
+ COMPOSE_VERSION_HEADER,
909
946
  CONTINUATION_COMMITMENT_OP_ID,
910
947
  CallCheckSpecSchema,
911
948
  CallSchema,
@@ -916,7 +953,6 @@ var ContinuationPlanZod = import_zod.default.object({
916
953
  ContinuationOutcomeSchema,
917
954
  ContinuationPlanSchema,
918
955
  ContinuationPlanZod,
919
- ContinuationSchema,
920
956
  EVM_NATIVE_SENTINEL,
921
957
  Erc20BalanceDeltaGteSpecSchema,
922
958
  Erc20BalanceGteSpecSchema,
@@ -958,6 +994,7 @@ var ContinuationPlanZod = import_zod.default.object({
958
994
  VerificationDescriptorZod,
959
995
  canonicalAssertedPredicate,
960
996
  canonicalNativeAddress,
997
+ checkCompatibility,
961
998
  copy,
962
999
  erc20,
963
1000
  erc20Allowance,
@@ -972,7 +1009,6 @@ var ContinuationPlanZod = import_zod.default.object({
972
1009
  foldResource,
973
1010
  getChainCapabilities,
974
1011
  handle,
975
- inputRef,
976
1012
  isAsErc20Chain,
977
1013
  isContextKey,
978
1014
  isEQCheck,
@@ -999,11 +1035,12 @@ var ContinuationPlanZod = import_zod.default.object({
999
1035
  normalizeNativeTokenAddress,
1000
1036
  normalizeResource,
1001
1037
  opHandle,
1002
- outputRef,
1003
1038
  parseRef,
1039
+ parseVersion,
1004
1040
  providerKindByName,
1005
1041
  providerKindNames,
1006
1042
  readResource,
1043
+ ref,
1007
1044
  refKey,
1008
1045
  resource,
1009
1046
  resourceKey,
package/dist/index.d.cts CHANGED
@@ -138,10 +138,6 @@ declare const CallSchema: Schema.Struct<{
138
138
  readonly value: typeof Schema.Unknown;
139
139
  }]>>>;
140
140
  }>;
141
- declare const ContinuationSchema: Schema.Struct<{
142
- awaits: typeof Schema.String;
143
- flowId: typeof Schema.String;
144
- }>;
145
141
  declare const FlowSchema: Schema.Struct<{
146
142
  version: Schema.Literal<[1]>;
147
143
  id: typeof Schema.String;
@@ -195,10 +191,6 @@ declare const FlowSchema: Schema.Struct<{
195
191
  readonly value: typeof Schema.Unknown;
196
192
  }]>>>;
197
193
  }>>;
198
- continuations: Schema.optional<Schema.Array$<Schema.Struct<{
199
- awaits: typeof Schema.String;
200
- flowId: typeof Schema.String;
201
- }>>>;
202
194
  }>;
203
195
  type SolType = typeof SolTypeSchema.Type;
204
196
  type ResourceInput = typeof ResourceInputSchema.Type;
@@ -209,7 +201,6 @@ type LiteralBinding = typeof LiteralBindingSchema.Type;
209
201
  type BindValue = typeof BindValueSchema.Type;
210
202
  type AppliedGuard = typeof AppliedGuardSchema.Type;
211
203
  type Call = typeof CallSchema.Type;
212
- type Continuation = typeof ContinuationSchema.Type;
213
204
  type Flow = typeof FlowSchema.Type;
214
205
 
215
206
  declare const CONTINUATION_COMMITMENT_OP_ID = "continuation.commitment";
@@ -299,23 +290,22 @@ declare const ContinuationIntentSchema: Schema.Struct<{
299
290
  readonly value: typeof Schema.Unknown;
300
291
  }]>>>;
301
292
  }>>;
302
- continuations: Schema.optional<Schema.Array$<Schema.Struct<{
303
- awaits: typeof Schema.String;
304
- flowId: typeof Schema.String;
305
- }>>>;
306
293
  }>>;
307
294
  validity: Schema.Struct<{
308
295
  expiresAtMs: typeof Schema.Number;
309
296
  }>;
310
297
  perpetual: Schema.optional<typeof Schema.Boolean>;
311
298
  provider: Schema.optional<typeof Schema.String>;
299
+ funding: Schema.optional<Schema.Literal<["inline", "external"]>>;
312
300
  }>;
313
301
  declare const Phase1ArtifactSchema: Schema.Union<[Schema.Struct<{
314
302
  kind: Schema.Literal<["transaction"]>;
303
+ funding: Schema.Literal<["inline", "external"]>;
315
304
  transactionRequest: Schema.optional<Schema.Struct<{
316
305
  to: typeof Schema.String;
317
306
  data: typeof Schema.String;
318
307
  value: typeof Schema.String;
308
+ chainId: typeof Schema.Number;
319
309
  }>>;
320
310
  }>, Schema.Struct<{
321
311
  kind: Schema.Literal<["signables"]>;
@@ -500,10 +490,6 @@ declare const ContinuationPlanSchema: Schema.Struct<{
500
490
  readonly value: typeof Schema.Unknown;
501
491
  }]>>>;
502
492
  }>>;
503
- continuations: Schema.optional<Schema.Array$<Schema.Struct<{
504
- awaits: typeof Schema.String;
505
- flowId: typeof Schema.String;
506
- }>>>;
507
493
  }>;
508
494
  check: Schema.transform<Schema.Union<[Schema.Struct<{
509
495
  kind: Schema.Literal<["erc20BalanceGte"]>;
@@ -795,6 +781,7 @@ type ProducedResource = Resource & {
795
781
  readonly availability: Availability;
796
782
  readonly simulated?: SimulatedAmounts;
797
783
  readonly owner: string;
784
+ readonly etaSeconds?: number;
798
785
  };
799
786
  declare const erc20Resource: (token: string, chainId: number) => Resource;
800
787
  declare const nativeResource: (chainId: number) => Resource;
@@ -1386,11 +1373,10 @@ declare const ComposeManifestZod: z.ZodObject<{
1386
1373
  }, z.core.$strip>;
1387
1374
  declare const Phase1ArtifactZod: z.ZodDiscriminatedUnion<[z.ZodObject<{
1388
1375
  kind: z.ZodLiteral<"transaction">;
1389
- transactionRequest: z.ZodOptional<z.ZodObject<{
1390
- to: z.ZodString;
1391
- data: z.ZodString;
1392
- value: z.ZodString;
1393
- }, z.core.$strip>>;
1376
+ funding: z.ZodEnum<{
1377
+ inline: "inline";
1378
+ external: "external";
1379
+ }>;
1394
1380
  }, z.core.$strip>, z.ZodObject<{
1395
1381
  kind: z.ZodLiteral<"signables">;
1396
1382
  typedData: z.ZodArray<z.ZodUnknown>;
@@ -1804,6 +1790,12 @@ interface ComposeRun {
1804
1790
  readonly maxPriceImpactBps?: number;
1805
1791
  readonly sweepTo?: SweepTo;
1806
1792
  readonly simulationPolicy?: SimulationPolicy;
1793
+ /**
1794
+ * Also simulate the final user-facing transaction. Defaults to `false`;
1795
+ * reverts honour `simulationPolicy` and a success is echoed back as
1796
+ * `userProgramSimulation`.
1797
+ */
1798
+ readonly simulateUserProgram?: boolean;
1807
1799
  readonly checkOnChainAllowances?: boolean;
1808
1800
  }
1809
1801
  interface ComposeCompileRequest {
@@ -1840,34 +1832,56 @@ interface SimulationRevert {
1840
1832
  }
1841
1833
  interface ComposeTransactionRequest {
1842
1834
  readonly to: string;
1835
+ readonly chainId: number;
1843
1836
  readonly data: string;
1844
1837
  readonly value: string;
1845
1838
  readonly gasLimit?: string;
1846
1839
  }
1847
- interface ComposeContinuation {
1848
- readonly awaits: string;
1849
- readonly flowId: string;
1840
+ interface ComposeAction {
1841
+ readonly kind: 'transaction';
1842
+ readonly purpose: 'approval' | 'execute' | 'fundEscrow';
1843
+ readonly submitter: 'signer' | 'anyone';
1844
+ readonly transactionRequest: ComposeTransactionRequest;
1845
+ readonly nodeId?: string;
1850
1846
  }
1851
1847
  interface ComposeContinuationData {
1852
- readonly continuations?: readonly ComposeContinuation[];
1853
1848
  readonly phase1ByNode?: Record<string, Phase1ArtifactWire>;
1854
1849
  readonly continuationPlans?: Record<string, ContinuationPlanWire>;
1855
1850
  }
1856
1851
  interface SpendEntry {
1852
+ readonly input: string;
1857
1853
  readonly token: string;
1854
+ readonly chainId: number;
1858
1855
  readonly amount: string;
1856
+ readonly nodeId?: string;
1857
+ }
1858
+ interface ComposeFee {
1859
+ readonly input: string;
1860
+ readonly token: string;
1861
+ readonly recipient: 'lifi' | 'integrator';
1862
+ readonly recipientAddress: string;
1863
+ readonly bps: number;
1864
+ readonly amount?: string;
1865
+ }
1866
+ interface ComposeUserProgramSimulation {
1867
+ readonly status: 'ok';
1868
+ readonly returnData: string;
1869
+ }
1870
+ interface ComposeFill {
1871
+ readonly spends: readonly SpendEntry[];
1872
+ readonly validUntilMs?: number;
1859
1873
  }
1860
1874
  interface ComposeCompileSuccessData extends ComposeContinuationData {
1861
1875
  readonly producedResources: Record<string, ProducedResource>;
1862
- readonly transactionRequest: ComposeTransactionRequest;
1876
+ readonly transactionRequest?: ComposeTransactionRequest;
1877
+ readonly actions?: readonly ComposeAction[];
1863
1878
  readonly userProxy: string;
1864
1879
  readonly priceImpact?: PriceImpact;
1865
1880
  readonly approvals?: readonly ApprovalEntry[];
1866
- readonly spends?: readonly SpendEntry[];
1867
- readonly quote?: {
1868
- readonly validUntilMs: number;
1869
- };
1870
- readonly verificationDescriptor?: VerificationDescriptor;
1881
+ readonly fees?: readonly ComposeFee[];
1882
+ readonly userProgramSimulation?: ComposeUserProgramSimulation;
1883
+ readonly fill?: ComposeFill;
1884
+ readonly verificationByNode?: Record<string, VerificationDescriptor>;
1871
1885
  }
1872
1886
  interface ComposeCompilePartialData extends ComposeContinuationData {
1873
1887
  readonly producedResources: Record<string, ProducedResource>;
@@ -1875,6 +1889,9 @@ interface ComposeCompilePartialData extends ComposeContinuationData {
1875
1889
  readonly userProxy: string;
1876
1890
  readonly simulationRevert: SimulationRevert;
1877
1891
  readonly approvals?: readonly ApprovalEntry[];
1892
+ readonly actions?: readonly ComposeAction[];
1893
+ readonly fees?: readonly ComposeFee[];
1894
+ readonly userProgramSimulation?: ComposeUserProgramSimulation;
1878
1895
  }
1879
1896
  type ComposeCompileResult = (ComposeCompileSuccessData & {
1880
1897
  readonly status: 'success';
@@ -1902,6 +1919,10 @@ declare const isHandlePort: (port: OpInputPort | OpOutputPort) => port is Handle
1902
1919
  declare const isResourceOutputPort: (port: OpInputPort | OpOutputPort) => port is ResourceOutputPort;
1903
1920
  declare const isFutureResourceOutput: (port: OpInputPort | OpOutputPort) => boolean;
1904
1921
  type ComposeErrorKind = 'decode_error' | 'validation_error' | 'linearity_error' | 'resolve_error' | 'preparation_error' | 'provider_error' | 'no_route_error' | 'resolution_error' | 'resolution_rejected' | 'lowering_error' | 'empty_program' | 'simulation_error' | 'simulation_setup_error' | 'simulation_insufficient_funds' | 'simulation_gas_limit' | 'simulation_rpc_error' | 'simulation_revert' | 'subgraph_simulation_revert' | 'guard_error' | 'continuation_error' | 'compilation_error' | 'verification_error' | 'price_impact_exceeded' | 'fee_resolution_error' | 'fee_resolution_unavailable' | 'flashloan_unauthorized' | 'deadline_exceeded';
1922
+ /**
1923
+ * Errors raised by compose routes outside the compile pipeline.
1924
+ */
1925
+ type ComposeRouteErrorKind = 'chain_validation_error' | 'unsupported_token' | 'zero_output' | 'service_unavailable' | 'verification_unavailable' | 'deployment_check_unavailable' | 'manifest_error' | 'sdk_outdated' | 'server_outdated';
1905
1926
  type GenericComposeErrorKind = Exclude<ComposeErrorKind, 'preparation_error' | 'simulation_revert'>;
1906
1927
  interface FailedPreparedOp {
1907
1928
  readonly callId: string;
@@ -1963,8 +1984,6 @@ interface OpHandleOptions<Opt extends boolean = boolean> {
1963
1984
  readonly units?: HandleUnits;
1964
1985
  readonly optional?: Opt;
1965
1986
  }
1966
- declare const inputRef: (port: string) => Ref;
1967
- declare const outputRef: (node: string, port: string) => Ref;
1968
1987
  declare const linear: <N extends string, T extends SolType>(name: N, type: T) => Port & {
1969
1988
  readonly name: N;
1970
1989
  readonly type: T;
@@ -2037,6 +2056,22 @@ declare const isContextKey: (key: string) => key is ContextKey;
2037
2056
  declare const RESERVED_REF_SCOPES: ReadonlySet<string>;
2038
2057
  declare const isRef: (v: unknown) => v is Ref;
2039
2058
  declare const parseRef: (ref: Ref) => ParsedRef;
2059
+ /** A ref path: a dotpath such as `input.amount` or `nodeId.port`. */
2060
+ type RefPath = `${string}.${string}`;
2061
+ /**
2062
+ * Builds a bind ref. `ref.input(port)` for a flow input, `ref.context.*` for a
2063
+ * context ref, and a dotpath for a node output (`ref('deposit.shares')`).
2064
+ * Prefer the named forms: `parseRef` reads an unrecognised prefix as a node id,
2065
+ * so a misspelled `input.`/`context.` silently becomes an output ref.
2066
+ */
2067
+ interface RefBuilder {
2068
+ (path: RefPath): Ref;
2069
+ input(port: string): Ref;
2070
+ readonly context: {
2071
+ readonly [K in ContextKey]: Ref;
2072
+ };
2073
+ }
2074
+ declare const ref: RefBuilder;
2040
2075
  declare const foldRef: <R>(ref: ParsedRef, cases: {
2041
2076
  readonly input: (port: string) => R;
2042
2077
  readonly context: (key: ContextKey) => R;
@@ -2154,16 +2189,18 @@ declare const normalizeNativeTokenAddress: (token: string, chainId: number) => s
2154
2189
  * format is always a decimal string, which the SDK serialises for you.
2155
2190
  *
2156
2191
  * `/compose/route` trades authoring power for brevity. Instead of a full flow
2157
- * document it takes a single from/to token pair; the server builds a
2158
- * `lifi.zap` flow with a `directDeposit` input on the caller's behalf and runs
2159
- * it through the same compile pipeline as `POST /compose`. As of today the flow
2160
- * it builds is a single zap step — one edge of the server's routing catalog —
2161
- * and it is meant to author richer flows later, which this request shape is
2162
- * deliberately agnostic about. Its response body is byte-identical to that of
2163
- * `POST /compose` — the enveloped `ComposeCompileSuccessData` on HTTP 200 and
2164
- * `ComposeCompilePartialData` on HTTP 206 — so this file declares only the
2165
- * request shape and reuses `ComposeCompileResult` from `./compile.js` for the
2166
- * result.
2192
+ * document it takes a single from/to token pair; the server builds a one-node
2193
+ * zap flow with a `directDeposit` input on the caller's behalf and runs it
2194
+ * through the same compile pipeline as `POST /compose`. It routes through
2195
+ * `lifi.zap` unless the pair is reachable only asynchronously and the request
2196
+ * set `allowAsyncRoutes`, in which case it uses `lifi.zapAsync`. As of today
2197
+ * the flow it builds is a single zap step — one edge of the server's routing
2198
+ * catalog — and it is meant to author richer flows later, which this request
2199
+ * shape is deliberately agnostic about. Its response body is byte-identical to
2200
+ * that of `POST /compose` — the enveloped `ComposeCompileSuccessData` on HTTP
2201
+ * 200 and `ComposeCompilePartialData` on HTTP 206 — so this file declares only
2202
+ * the request shape and reuses `ComposeCompileResult` from `./compile.js` for
2203
+ * the result.
2167
2204
  *
2168
2205
  * These are the single source of truth for the request shape, hand-authored
2169
2206
  * here for the same reason as `./compile.ts` and `./simulate.ts` rather than
@@ -2269,6 +2306,16 @@ interface ComposeRouteRequest {
2269
2306
  * omitting approvals that are already sufficient. Defaults to `false`.
2270
2307
  */
2271
2308
  readonly checkOnChainAllowances?: boolean;
2309
+ /**
2310
+ * Accept a route whose output is delivered only after the initiating
2311
+ * transaction settles (`availability: 'future'` on the produced resource).
2312
+ * Such a route obliges you to track settlement rather than treat the
2313
+ * transaction as completing the job, and carries no slippage floor, so it is
2314
+ * opt-in. Defaults to `false` server-side, which leaves a pair reachable
2315
+ * only asynchronously rejected with `no_route_error` and guarantees every
2316
+ * produced resource is `availability: 'now'`.
2317
+ */
2318
+ readonly allowAsyncRoutes?: boolean;
2272
2319
  }
2273
2320
 
2274
2321
  /**
@@ -2452,6 +2499,58 @@ interface SimulateSetupErrorResult {
2452
2499
  */
2453
2500
  type SimulateResult = SimulateOkResult | SimulateRevertResult | SimulateSetupErrorResult;
2454
2501
 
2502
+ /**
2503
+ * HTTP header names on the compose wire.
2504
+ *
2505
+ * Both the SDK (which sends the request header) and the backend (which reads it
2506
+ * and answers with the response header) are part of the same handshake, so the
2507
+ * names belong to the wire format rather than to either side of it.
2508
+ */
2509
+ /** Compose contract version the client was built against. Sent on every request. */
2510
+ declare const COMPOSER_SDK_VERSION_HEADER = "x-lifi-composer-sdk";
2511
+ /** Compose contract version the backend serves. Returned on every compose response. */
2512
+ declare const COMPOSE_VERSION_HEADER = "x-lifi-composer-version";
2513
+
2514
+ /**
2515
+ * Compose contract version compatibility.
2516
+ *
2517
+ * The version triple carries the compatibility class, and the rule is
2518
+ * permanent: 1.0 does not change it. A patch bump is additive: new ops, edge
2519
+ * families, materialisers, guards, preconditions, or new optional config
2520
+ * fields. A minor or major bump is breaking: anything removed, any existing
2521
+ * schema changed, or a semantics change under an unchanged wire shape. Both
2522
+ * sides of the handshake (see `headers.ts`) decide with `checkCompatibility`,
2523
+ * so the rule lives in exactly one place.
2524
+ */
2525
+ interface ComposeVersion {
2526
+ readonly major: number;
2527
+ readonly minor: number;
2528
+ readonly patch: number;
2529
+ }
2530
+ type VersionCompatibility = 'compatible' | 'sdk_outdated' | 'server_outdated';
2531
+ /**
2532
+ * Parses the numeric triple of a semantic version. Prerelease and build
2533
+ * suffixes are accepted and ignored: `0.5.1-staging.3` compares as `0.5.1`.
2534
+ * Returns `undefined` for anything that is not a complete semver string,
2535
+ * including the `dev` sentinel the SDK sends when it runs unbundled.
2536
+ */
2537
+ declare const parseVersion: (version: string) => ComposeVersion | undefined;
2538
+ /**
2539
+ * Decides whether a client built against `client` may talk to a server that
2540
+ * serves `server`.
2541
+ *
2542
+ * - Same `major.minor` with the client at or behind the server's patch is
2543
+ * compatible: patch releases only add, so an older client never emits
2544
+ * anything the server lacks.
2545
+ * - A client below the server's `major.minor` is `sdk_outdated`: the server
2546
+ * made a breaking change the client does not know about.
2547
+ * - A client ahead in any component is `server_outdated`. Even a patch-ahead
2548
+ * client may send a field the server has never seen, and the guarantee must
2549
+ * not depend on every server schema staying strict. This is the rollout
2550
+ * window between an npm publish and the prod image bump.
2551
+ */
2552
+ declare const checkCompatibility: (client: ComposeVersion, server: ComposeVersion) => VersionCompatibility;
2553
+
2455
2554
  type MaterialiserMetadata = {
2456
2555
  readonly kind: 'exact';
2457
2556
  readonly amount: bigint;
@@ -2471,4 +2570,4 @@ declare const foldMaterialiserMetadata: <R>(meta: MaterialiserMetadata, cases: {
2471
2570
  readonly runtime: () => R;
2472
2571
  }) => R;
2473
2572
 
2474
- export { type AppliedGuard, AppliedGuardSchema, type ApprovalEntry, AssertedErc20BalanceGteSpecSchema, AssertedNativeBalanceGteSpecSchema, type AssertedPredicate, AssertedPredicateSchema, type AssertedPredicateWire, AssertedPredicateZod, type AssertionOwner, AssertionOwnerSchema, type AssertionSpec, AssertionSpecSchema, type AssertionSpecWire, AssertionSpecZod, type Availability, type BindValue, BindValueSchema, Bytes32HexSchema, CONTINUATION_COMMITMENT_OP_ID, type Call, CallCheckSpecSchema, CallSchema, type ChainCapabilities, type Check, type CheckComparator, CheckSchema, CheckZod, type ComposeCompilePartialData, type ComposeCompileRequest, type ComposeCompileResult, type ComposeCompileSuccessData, type ComposeContinuation, type ComposeError, type ComposeErrorKind, type ComposeManifest, ComposeManifestZod, type ComposeRouteRequest, type ComposeRun, type ComposeTransactionRequest, type ContextKey, type Continuation, type ContinuationIntent, ContinuationIntentSchema, type ContinuationOutcome, ContinuationOutcomeSchema, type ContinuationPlan, ContinuationPlanSchema, type ContinuationPlanWire, ContinuationPlanZod, ContinuationSchema, EVM_NATIVE_SENTINEL, type Erc20AllowancePrecondition, type Erc20AllowanceRequirement, Erc20BalanceDeltaGteSpecSchema, Erc20BalanceGteSpecSchema, type Erc20BalancePrecondition, type Erc20BalanceRequirement, type FailedPreparedOp, type FlashloanMaterialiserInput, type Flow, type FlowInput, FlowInputSchema, FlowSchema, type GenericComposeError, type GenericComposeErrorKind, type GuardCompatibility, GuardCompatibilityZod, type GuardSelector, GuardSelectorZod, HANDLE_UNITS, type HandleInput, HandleInputSchema, type HandlePort, HandlePortZod, type HandleUnits, HandleUnitsZod, HexStringSchema, InputPortZod, type InputSpec, type LiteralBinding, LiteralBindingSchema, type ManifestGuard, ManifestGuardZod, type ManifestMaterialiser, ManifestMaterialiserZod, type ManifestOperation, ManifestOperationZod, type ManifestPrecondition, ManifestPreconditionZod, type MaterialiserConfigOf, type MaterialiserInput, type MaterialiserInputBase, type MaterialiserInputOf, type MaterialiserMetadata, type MaterialiserResolution, NativeBalanceDeltaGteSpecSchema, NativeBalanceGteSpecSchema, type NativeBalancePrecondition, type NativeBalanceRequirement, type NativeErc20, type OpInputPort, type OpOutputPort, type OutputAmount, OutputPortZod, PROVIDER_KIND, type ParsedRef, type Phase1Artifact, Phase1ArtifactSchema, type Phase1ArtifactWire, Phase1ArtifactZod, type Port, type Precondition, type PreconditionBase, type PreconditionConfigOf, type PreconditionOf, type PreparationComposeError, type PriceImpact, type ProducedResource, type ProviderKindName, RESERVED_REF_SCOPES, type Ref, RefSchema, type RefScope, type Resource, type ResourceInput, ResourceInputSchema, type ResourceOutputPort, ResourceOutputPortZod, type ResourcePort, ResourcePortZod, ResourceSchema, type RouteAmount, type RouteAmountAll, type RouteAmountExact, SIMULATE_MAX_REQUIREMENTS, SIMULATE_MAX_TRACKED_BALANCES, STATIC_SOL_TYPES, type SimulateBalanceEntry, type SimulateOkResult, type SimulateRequest, type SimulateResult, type SimulateRevertDecodeResult, type SimulateRevertResult, type SimulateSetupErrorResult, type SimulatedAmounts, type SimulationPolicy, type SimulationRevert, type SimulationRevertComposeError, type SlotFinderRequirement, type SolType, SolTypeSchema, type SpendEntry, type StaticSolType, StaticSolTypeZod, type SweepTo, TEMPO_CHAIN_ID, TEMPO_NATIVE_ERC20, type TrackedBalance, type VerificationDescriptor, VerificationDescriptorSchema, type VerificationDescriptorWire, VerificationDescriptorZod, canonicalAssertedPredicate, canonicalNativeAddress, copy, erc20, erc20Allowance, erc20Balance, erc20Resource, erc20Token, flowInputMode, flowInputResource, flowInputType, foldMaterialiserMetadata, foldRef, foldResource, getChainCapabilities, handle, inputRef, isAsErc20Chain, isContextKey, isEQCheck, isERC20Resource, isErc20AllowancePrecondition, isFutureResourceOutput, isGTECheck, isHandlePort, isLTECheck, isMaterialiserInput, isMsgValueNative, isNativeAddressForChain, isNativeBalancePrecondition, isNativeResource, isRef, isResourceInput, isResourceOutputPort, isResourcePort, isStaticSolType, linear, native, nativeBalance, nativeResource, normalizeNativeTokenAddress, normalizeResource, opHandle, outputRef, parseRef, providerKindByName, providerKindNames, readResource, refKey, resource, resourceKey, resourceOutput, resourceToken, resourcesEqual };
2573
+ export { type AppliedGuard, AppliedGuardSchema, type ApprovalEntry, AssertedErc20BalanceGteSpecSchema, AssertedNativeBalanceGteSpecSchema, type AssertedPredicate, AssertedPredicateSchema, type AssertedPredicateWire, AssertedPredicateZod, type AssertionOwner, AssertionOwnerSchema, type AssertionSpec, AssertionSpecSchema, type AssertionSpecWire, AssertionSpecZod, type Availability, type BindValue, BindValueSchema, Bytes32HexSchema, COMPOSER_SDK_VERSION_HEADER, COMPOSE_VERSION_HEADER, CONTINUATION_COMMITMENT_OP_ID, type Call, CallCheckSpecSchema, CallSchema, type ChainCapabilities, type Check, type CheckComparator, CheckSchema, CheckZod, type ComposeAction, type ComposeCompilePartialData, type ComposeCompileRequest, type ComposeCompileResult, type ComposeCompileSuccessData, type ComposeError, type ComposeErrorKind, type ComposeFee, type ComposeFill, type ComposeManifest, ComposeManifestZod, type ComposeRouteErrorKind, type ComposeRouteRequest, type ComposeRun, type ComposeTransactionRequest, type ComposeUserProgramSimulation, type ComposeVersion, type ContextKey, type ContinuationIntent, ContinuationIntentSchema, type ContinuationOutcome, ContinuationOutcomeSchema, type ContinuationPlan, ContinuationPlanSchema, type ContinuationPlanWire, ContinuationPlanZod, EVM_NATIVE_SENTINEL, type Erc20AllowancePrecondition, type Erc20AllowanceRequirement, Erc20BalanceDeltaGteSpecSchema, Erc20BalanceGteSpecSchema, type Erc20BalancePrecondition, type Erc20BalanceRequirement, type FailedPreparedOp, type FlashloanMaterialiserInput, type Flow, type FlowInput, FlowInputSchema, FlowSchema, type GenericComposeError, type GenericComposeErrorKind, type GuardCompatibility, GuardCompatibilityZod, type GuardSelector, GuardSelectorZod, HANDLE_UNITS, type HandleInput, HandleInputSchema, type HandlePort, HandlePortZod, type HandleUnits, HandleUnitsZod, HexStringSchema, InputPortZod, type InputSpec, type LiteralBinding, LiteralBindingSchema, type ManifestGuard, ManifestGuardZod, type ManifestMaterialiser, ManifestMaterialiserZod, type ManifestOperation, ManifestOperationZod, type ManifestPrecondition, ManifestPreconditionZod, type MaterialiserConfigOf, type MaterialiserInput, type MaterialiserInputBase, type MaterialiserInputOf, type MaterialiserMetadata, type MaterialiserResolution, NativeBalanceDeltaGteSpecSchema, NativeBalanceGteSpecSchema, type NativeBalancePrecondition, type NativeBalanceRequirement, type NativeErc20, type OpInputPort, type OpOutputPort, type OutputAmount, OutputPortZod, PROVIDER_KIND, type ParsedRef, type Phase1Artifact, Phase1ArtifactSchema, type Phase1ArtifactWire, Phase1ArtifactZod, type Port, type Precondition, type PreconditionBase, type PreconditionConfigOf, type PreconditionOf, type PreparationComposeError, type PriceImpact, type ProducedResource, type ProviderKindName, RESERVED_REF_SCOPES, type Ref, type RefBuilder, type RefPath, RefSchema, type RefScope, type Resource, type ResourceInput, ResourceInputSchema, type ResourceOutputPort, ResourceOutputPortZod, type ResourcePort, ResourcePortZod, ResourceSchema, type RouteAmount, type RouteAmountAll, type RouteAmountExact, SIMULATE_MAX_REQUIREMENTS, SIMULATE_MAX_TRACKED_BALANCES, STATIC_SOL_TYPES, type SimulateBalanceEntry, type SimulateOkResult, type SimulateRequest, type SimulateResult, type SimulateRevertDecodeResult, type SimulateRevertResult, type SimulateSetupErrorResult, type SimulatedAmounts, type SimulationPolicy, type SimulationRevert, type SimulationRevertComposeError, type SlotFinderRequirement, type SolType, SolTypeSchema, type SpendEntry, type StaticSolType, StaticSolTypeZod, type SweepTo, TEMPO_CHAIN_ID, TEMPO_NATIVE_ERC20, type TrackedBalance, type VerificationDescriptor, VerificationDescriptorSchema, type VerificationDescriptorWire, VerificationDescriptorZod, type VersionCompatibility, canonicalAssertedPredicate, canonicalNativeAddress, checkCompatibility, copy, erc20, erc20Allowance, erc20Balance, erc20Resource, erc20Token, flowInputMode, flowInputResource, flowInputType, foldMaterialiserMetadata, foldRef, foldResource, getChainCapabilities, handle, isAsErc20Chain, isContextKey, isEQCheck, isERC20Resource, isErc20AllowancePrecondition, isFutureResourceOutput, isGTECheck, isHandlePort, isLTECheck, isMaterialiserInput, isMsgValueNative, isNativeAddressForChain, isNativeBalancePrecondition, isNativeResource, isRef, isResourceInput, isResourceOutputPort, isResourcePort, isStaticSolType, linear, native, nativeBalance, nativeResource, normalizeNativeTokenAddress, normalizeResource, opHandle, parseRef, parseVersion, providerKindByName, providerKindNames, readResource, ref, refKey, resource, resourceKey, resourceOutput, resourceToken, resourcesEqual };