@lifi/compose-spec 0.4.0 → 0.5.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
@@ -126,17 +126,12 @@ var CallSchema = Schema.Struct({
126
126
  ),
127
127
  guards: Schema.optional(Schema.Array(AppliedGuardSchema))
128
128
  });
129
- var ContinuationSchema = Schema.Struct({
130
- awaits: Schema.String,
131
- flowId: Schema.String
132
- });
133
129
  var FlowSchema = Schema.Struct({
134
130
  version: Schema.Literal(1),
135
131
  id: Schema.String,
136
132
  chainId: ChainIdSchema,
137
133
  inputs: Schema.Array(FlowInputSchema),
138
- nodes: Schema.Array(CallSchema),
139
- continuations: Schema.optional(Schema.Array(ContinuationSchema))
134
+ nodes: Schema.Array(CallSchema)
140
135
  });
141
136
 
142
137
  // src/continuation.ts
@@ -166,16 +161,21 @@ var ContinuationIntentSchema = Schema2.Struct({
166
161
  continuationFlow: Schema2.optional(FlowSchema),
167
162
  validity: Schema2.Struct({ expiresAtMs: Schema2.Number }),
168
163
  perpetual: Schema2.optional(Schema2.Boolean),
169
- provider: Schema2.optional(Schema2.String)
164
+ provider: Schema2.optional(Schema2.String),
165
+ // Funding-path mode. The HTTP wire contract is documented by
166
+ // `ComposeActionsSchema` in `@lifi/api-schemas`.
167
+ funding: Schema2.optional(Schema2.Literal("inline", "external"))
170
168
  });
171
169
  var Phase1ArtifactSchema = Schema2.Union(
172
170
  Schema2.Struct({
173
171
  kind: Schema2.Literal("transaction"),
172
+ funding: Schema2.Literal("inline", "external"),
174
173
  transactionRequest: Schema2.optional(
175
174
  Schema2.Struct({
176
175
  to: Schema2.String,
177
176
  data: Schema2.String,
178
- value: Schema2.String
177
+ value: Schema2.String,
178
+ chainId: Schema2.Number
179
179
  })
180
180
  )
181
181
  }),
@@ -335,6 +335,7 @@ var flowInputResource = (input) => isResourceInput(input) ? input.resource : voi
335
335
  var isResourcePort = (port) => port.kind === "resource";
336
336
  var isHandlePort = (port) => port.kind === "handle";
337
337
  var isResourceOutputPort = (port) => port.kind === "resource_output";
338
+ var isFutureResourceOutput = (port) => isResourceOutputPort(port) && port.availability === "future";
338
339
  var isMaterialiserInput = (s) => typeof s === "object" && s !== null && "kind" in s;
339
340
 
340
341
  // src/resource.ts
@@ -394,16 +395,28 @@ var providerKindByName = {
394
395
  };
395
396
 
396
397
  // src/constructors.ts
397
- var inputRef = (port) => ({ $ref: `input.${port}` });
398
- var outputRef = (node, port) => ({
399
- $ref: `${node}.${port}`
400
- });
401
398
  var optionalProp = (key, value) => value !== void 0 && value !== null ? { [key]: value } : {};
402
- var linear = (name, type) => ({ name, type, mode: "linear", availability: "now" });
403
- var copy = (name, type) => ({ name, type, mode: "copy", availability: "now" });
399
+ var linear = (name, type) => ({
400
+ name,
401
+ type,
402
+ mode: "linear",
403
+ availability: "now"
404
+ });
405
+ var copy = (name, type) => ({
406
+ name,
407
+ type,
408
+ mode: "copy",
409
+ availability: "now"
410
+ });
404
411
  var handle = (name, type) => ({ name, type });
405
- var native = (name, chainId) => ({ name, resource: nativeResource(chainId) });
406
- var erc20 = (name, token, chainId) => ({ name, resource: erc20Resource(token, chainId) });
412
+ var native = (name, chainId) => ({
413
+ name,
414
+ resource: nativeResource(chainId)
415
+ });
416
+ var erc20 = (name, token, chainId) => ({
417
+ name,
418
+ resource: erc20Resource(token, chainId)
419
+ });
407
420
  var resource = (name, accepts, options) => ({
408
421
  kind: "resource",
409
422
  name,
@@ -411,17 +424,24 @@ var resource = (name, accepts, options) => ({
411
424
  mode: "linear",
412
425
  ...optionalProp("optional", options?.optional)
413
426
  });
414
- var readResource = (name, accepts) => ({ kind: "resource", name, accepts, mode: "copy" });
427
+ var readResource = (name, accepts) => ({
428
+ kind: "resource",
429
+ name,
430
+ accepts,
431
+ mode: "copy"
432
+ });
415
433
  var opHandle = (name, type, options) => ({
416
434
  kind: "handle",
417
435
  name,
418
436
  type,
419
437
  mode: "copy",
420
438
  ...optionalProp("expose", options?.expose),
421
- ...optionalProp("units", options?.units)
439
+ ...optionalProp("units", options?.units),
440
+ ...optionalProp("optional", options?.optional)
422
441
  });
423
442
  var resourceOutput = (name, options) => {
424
- const opts = typeof options === "string" ? { availability: options } : options;
443
+ const raw = options;
444
+ const opts = typeof raw === "string" ? { availability: raw } : raw;
425
445
  return {
426
446
  kind: "resource_output",
427
447
  name,
@@ -441,12 +461,12 @@ var RESERVED_REF_SCOPES = /* @__PURE__ */ new Set([
441
461
  "literal"
442
462
  ]);
443
463
  var isRef = (v) => typeof v === "object" && v !== null && "$ref" in v && typeof v.$ref === "string";
444
- var parseRef = (ref) => {
445
- const dot = ref.$ref.indexOf(".");
464
+ var parseRef = (ref2) => {
465
+ const dot = ref2.$ref.indexOf(".");
446
466
  if (dot === -1)
447
- throw new Error(`Invalid ref: "${ref.$ref}" (must contain a dot)`);
448
- const prefix = ref.$ref.slice(0, dot);
449
- const suffix = ref.$ref.slice(dot + 1);
467
+ throw new Error(`Invalid ref: "${ref2.$ref}" (must contain a dot)`);
468
+ const prefix = ref2.$ref.slice(0, dot);
469
+ const suffix = ref2.$ref.slice(dot + 1);
450
470
  if (prefix === "input") return { scope: "input", port: suffix };
451
471
  if (prefix === "context") {
452
472
  if (!isContextKey(suffix))
@@ -455,17 +475,40 @@ var parseRef = (ref) => {
455
475
  }
456
476
  return { scope: "output", node: prefix, port: suffix };
457
477
  };
458
- var foldRef = (ref, cases) => {
459
- if (ref.scope === "input") return cases.input(ref.port);
460
- if (ref.scope === "context") return cases.context(ref.key);
461
- return cases.output(ref.node, ref.port);
478
+ var buildRef = (path) => {
479
+ if (path.indexOf(".") < 1)
480
+ throw new Error(
481
+ `Invalid ref: "${path}" (must be a dotpath like "input.name" or "nodeId.port")`
482
+ );
483
+ const built = { $ref: path };
484
+ parseRef(built);
485
+ return built;
486
+ };
487
+ var ref = Object.assign(buildRef, {
488
+ input: (port) => buildRef(`input.${port}`),
489
+ context: {
490
+ sender: buildRef("context.sender"),
491
+ executionAddress: buildRef("context.executionAddress")
492
+ }
493
+ });
494
+ var foldRef = (ref2, cases) => {
495
+ if (ref2.scope === "input") return cases.input(ref2.port);
496
+ if (ref2.scope === "context") return cases.context(ref2.key);
497
+ return cases.output(ref2.node, ref2.port);
462
498
  };
463
- var refKey = (ref) => foldRef(parseRef(ref), {
499
+ var refKey = (ref2) => foldRef(parseRef(ref2), {
464
500
  input: (port) => `input:${port}`,
465
501
  context: (key) => `context:${key}`,
466
502
  output: (node, port) => `output:${node}:${port}`
467
503
  });
468
504
 
505
+ // src/preconditions.ts
506
+ var erc20Balance = (config) => ({ type: "Erc20Balance", ...config });
507
+ var nativeBalance = (config) => ({ type: "NativeBalance", ...config });
508
+ var erc20Allowance = (config) => ({ type: "Erc20Allowance", ...config });
509
+ var isErc20AllowancePrecondition = (p) => p.type === "Erc20Allowance";
510
+ var isNativeBalancePrecondition = (p) => p.type === "NativeBalance";
511
+
469
512
  // src/simulate.ts
470
513
  var SIMULATE_MAX_TRACKED_BALANCES = 40;
471
514
  var SIMULATE_MAX_REQUIREMENTS = 40;
@@ -531,7 +574,8 @@ var HandlePortZod = z.object({
531
574
  type: SolTypeZod,
532
575
  mode: z.enum(["linear", "copy"]),
533
576
  expose: z.boolean().optional(),
534
- units: HandleUnitsZod.optional()
577
+ units: HandleUnitsZod.optional(),
578
+ optional: z.boolean().optional()
535
579
  });
536
580
  var InputPortZod = z.discriminatedUnion("kind", [
537
581
  ResourcePortZod,
@@ -613,11 +657,7 @@ var ComposeManifestZod = z.object({
613
657
  var Phase1ArtifactZod = z.discriminatedUnion("kind", [
614
658
  z.object({
615
659
  kind: z.literal("transaction"),
616
- transactionRequest: z.object({
617
- to: z.string(),
618
- data: z.string(),
619
- value: z.string()
620
- }).optional()
660
+ funding: z.enum(["inline", "external"])
621
661
  }),
622
662
  z.object({
623
663
  kind: z.literal("signables"),
@@ -734,7 +774,6 @@ export {
734
774
  ContinuationOutcomeSchema,
735
775
  ContinuationPlanSchema,
736
776
  ContinuationPlanZod,
737
- ContinuationSchema,
738
777
  EVM_NATIVE_SENTINEL,
739
778
  Erc20BalanceDeltaGteSpecSchema,
740
779
  Erc20BalanceGteSpecSchema,
@@ -778,6 +817,8 @@ export {
778
817
  canonicalNativeAddress,
779
818
  copy,
780
819
  erc20,
820
+ erc20Allowance,
821
+ erc20Balance,
781
822
  erc20Resource,
782
823
  erc20Token,
783
824
  flowInputMode,
@@ -788,17 +829,19 @@ export {
788
829
  foldResource,
789
830
  getChainCapabilities,
790
831
  handle,
791
- inputRef,
792
832
  isAsErc20Chain,
793
833
  isContextKey,
794
834
  isEQCheck,
795
835
  isERC20Resource,
836
+ isErc20AllowancePrecondition,
837
+ isFutureResourceOutput,
796
838
  isGTECheck,
797
839
  isHandlePort,
798
840
  isLTECheck,
799
841
  isMaterialiserInput,
800
842
  isMsgValueNative,
801
843
  isNativeAddressForChain,
844
+ isNativeBalancePrecondition,
802
845
  isNativeResource,
803
846
  isRef,
804
847
  isResourceInput,
@@ -807,15 +850,16 @@ export {
807
850
  isStaticSolType,
808
851
  linear,
809
852
  native,
853
+ nativeBalance,
810
854
  nativeResource,
811
855
  normalizeNativeTokenAddress,
812
856
  normalizeResource,
813
857
  opHandle,
814
- outputRef,
815
858
  parseRef,
816
859
  providerKindByName,
817
860
  providerKindNames,
818
861
  readResource,
862
+ ref,
819
863
  refKey,
820
864
  resource,
821
865
  resourceKey,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@lifi/compose-spec",
3
- "version": "0.4.0",
3
+ "version": "0.5.0",
4
4
  "description": "Public wire-format types and schemas for Compose flows",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {
@@ -28,21 +28,16 @@
28
28
  "publishConfig": {
29
29
  "access": "public"
30
30
  },
31
- "prettier": {
32
- "singleQuote": true
33
- },
34
31
  "scripts": {
35
32
  "build": "yarn check:types && tsup",
36
33
  "check:types": "tsc --noEmit",
37
34
  "clean": "rm -rf dist out",
38
35
  "pack:local": "yarn build && mkdir -p out && yarn pack --out 'out/%s-%v.tgz'",
39
36
  "test": "vitest run --config vitest.config.ts",
40
- "fix": "run-s fix:lint fix:prettier",
37
+ "fix": "yarn fix:lint",
41
38
  "fix:lint": "eslint src --fix",
42
- "fix:prettier": "prettier \"src/**/*.ts\" --write",
43
39
  "lint": "eslint src",
44
- "test:lint": "eslint src",
45
- "test:prettier": "prettier \"src/**/*.ts\" --list-different"
40
+ "test:lint": "eslint src"
46
41
  },
47
42
  "dependencies": {
48
43
  "effect": "^3.21.0",
@@ -51,17 +46,15 @@
51
46
  "devDependencies": {
52
47
  "@eslint/compat": "^1.4.0",
53
48
  "@lifi/eslint-plugin": "workspace:^",
54
- "@typescript-eslint/eslint-plugin": "^8.44.1",
55
- "@typescript-eslint/parser": "^8.44.1",
49
+ "@typescript-eslint/eslint-plugin": "^8.68.0",
50
+ "@typescript-eslint/parser": "^8.68.0",
56
51
  "eslint": "^9.36.0",
57
52
  "eslint-config-prettier": "^9.0.0",
58
53
  "eslint-plugin-eslint-comments": "^3.2.0",
59
54
  "eslint-plugin-import": "^2.22.0",
60
55
  "eslint-plugin-require-extensions": "^0.1.3",
61
- "npm-run-all": "^4.1.5",
62
- "prettier": "^3.9.4",
63
56
  "tsup": "^8.5.1",
64
- "typescript": "^5.9.2",
57
+ "typescript": "^6.0.3",
65
58
  "vitest": "^3.2.4"
66
59
  },
67
60
  "files": [
package/src/compile.ts CHANGED
@@ -23,6 +23,12 @@ export interface ComposeRun {
23
23
  readonly maxPriceImpactBps?: number;
24
24
  readonly sweepTo?: SweepTo;
25
25
  readonly simulationPolicy?: SimulationPolicy;
26
+ /**
27
+ * Also simulate the final user-facing transaction. Defaults to `false`;
28
+ * reverts honour `simulationPolicy` and a success is echoed back as
29
+ * `userProgramSimulation`.
30
+ */
31
+ readonly simulateUserProgram?: boolean;
26
32
  readonly checkOnChainAllowances?: boolean;
27
33
  }
28
34
 
@@ -64,17 +70,20 @@ export interface SimulationRevert {
64
70
 
65
71
  export interface ComposeTransactionRequest {
66
72
  readonly to: string;
73
+ readonly chainId: number;
67
74
  readonly data: string;
68
75
  readonly value: string;
69
76
  readonly gasLimit?: string;
70
77
  }
71
78
 
72
- // A single continuation pointer: the node whose `future` output is awaited and
73
- // the downstream flow that consumes its proceeds. A flow can declare several,
74
- // carried in the response as `continuations`.
75
- export interface ComposeContinuation {
76
- readonly awaits: string;
77
- readonly flowId: string;
79
+ // Hand-mirrored from `ComposeActionSchema`, the OpenAPI source of truth in
80
+ // `@lifi/api-schemas`.
81
+ export interface ComposeAction {
82
+ readonly kind: 'transaction';
83
+ readonly purpose: 'approval' | 'execute' | 'fundEscrow';
84
+ readonly submitter: 'signer' | 'anyone';
85
+ readonly transactionRequest: ComposeTransactionRequest;
86
+ readonly nodeId?: string;
78
87
  }
79
88
 
80
89
  // Continuation fields shared by the success and partial-error responses, so the
@@ -82,8 +91,6 @@ export interface ComposeContinuation {
82
91
  // Zod-inferred wire types from `zodSchemas.ts`, pinning these SDK-facing types
83
92
  // to the server contract rather than hand-transcribing them.
84
93
  interface ComposeContinuationData {
85
- // One pointer per `continuation.settle` branch (a flow can fork into several).
86
- readonly continuations?: readonly ComposeContinuation[];
87
94
  // Phase-1 action to sign/fund now, keyed by settle node. Absent for an atomic flow.
88
95
  readonly phase1ByNode?: Record<string, Phase1ArtifactWire>;
89
96
  // Self-serve second leg to re-submit later, keyed by settle node. Present only
@@ -91,29 +98,81 @@ interface ComposeContinuationData {
91
98
  readonly continuationPlans?: Record<string, ContinuationPlanWire>;
92
99
  }
93
100
 
94
- // One funding leg the compiled fill consumes: the resource input's token
95
- // (native → zero address) and its statically resolved amount as a decimal
96
- // string (verified continuations, plan GD-8, seam C5).
101
+ // One funding leg the compiled fill consumes: the resource input's name, its
102
+ // token (native → zero address) and chain, and the statically resolved amount
103
+ // as a decimal string (verified continuations, plan GD-8, seam C5). `nodeId`
104
+ // names the `continuation.settle` node this input funds (the `phase1ByNode` /
105
+ // `actions` key); absent when the input funds no settle leg (e.g. a plain
106
+ // swap's input).
97
107
  export interface SpendEntry {
108
+ readonly input: string;
98
109
  readonly token: string;
110
+ readonly chainId: number;
99
111
  readonly amount: string;
112
+ readonly nodeId?: string;
113
+ }
114
+
115
+ // One fee row per (input, recipient), as the compiled fill charges it.
116
+ // Hand-mirrored from api-schemas' `ComposeFeeSchema` (the OpenAPI source of
117
+ // truth; this package cannot depend on it). `recipient` names WHO is charged
118
+ // — never an address; the address is the sibling `recipientAddress`. `amount`
119
+ // is absent when the gross is only known on-chain at execution time (a
120
+ // balance-materialiser input).
121
+ export interface ComposeFee {
122
+ readonly input: string;
123
+ // Zero address for native, otherwise the ERC-20 contract.
124
+ readonly token: string;
125
+ readonly recipient: 'lifi' | 'integrator';
126
+ readonly recipientAddress: string;
127
+ readonly bps: number;
128
+ readonly amount?: string;
129
+ }
130
+
131
+ // The optional user-program simulation result, present only when the request
132
+ // opted in via `run.simulateUserProgram` and the simulation succeeded.
133
+ // Hand-mirrored from api-schemas' `ComposeUserProgramSimulationOkSchema`.
134
+ export interface ComposeUserProgramSimulation {
135
+ readonly status: 'ok';
136
+ readonly returnData: string;
137
+ }
138
+
139
+ // The solver-extractable fill (verified continuations, GD-8/GD-6, seam C5),
140
+ // present on every compiled success. Hand-mirrored to api-schemas' `fill`
141
+ // object (the OpenAPI source of truth; this package cannot depend on it).
142
+ // `spends` is what the fill consumes per funding input; `validUntilMs` is the
143
+ // fill freshness bound (earliest prepared-node expiry) — ABSENT = no expiry.
144
+ // The fill is transaction-scoped; the leg-scoped C4 verification echo lives in
145
+ // the sibling `verificationByNode` record.
146
+ export interface ComposeFill {
147
+ readonly spends: readonly SpendEntry[];
148
+ readonly validUntilMs?: number;
100
149
  }
101
150
 
102
151
  export interface ComposeCompileSuccessData extends ComposeContinuationData {
103
152
  readonly producedResources: Record<string, ProducedResource>;
104
- readonly transactionRequest: ComposeTransactionRequest;
153
+ // The OpenAPI source of truth documents the optionality and funding modes.
154
+ readonly transactionRequest?: ComposeTransactionRequest;
155
+ readonly actions?: readonly ComposeAction[];
105
156
  readonly userProxy: string;
106
157
  readonly priceImpact?: PriceImpact;
107
158
  readonly approvals?: readonly ApprovalEntry[];
108
- // GD-8 settlement-fill fields (seam C5), additive on every success response:
109
- // `spends` (the exact token amounts the fill consumes) and `quote.validUntilMs`
110
- // (fill freshness bound — earliest prepared-node `expiresAtMs`, else a
111
- // far-future sentinel).
112
- // `verificationDescriptor` (the echo) is present only when the flow carried a
113
- // `continuation.commitment` node.
114
- readonly spends?: readonly SpendEntry[];
115
- readonly quote?: { readonly validUntilMs: number };
116
- readonly verificationDescriptor?: VerificationDescriptor;
159
+ // The per-(input, recipient) fee rows the compiled fill charges. Absent when
160
+ // no fee applies.
161
+ readonly fees?: readonly ComposeFee[];
162
+ // The optional user-program simulation echo, present only when the request
163
+ // opted in via `run.simulateUserProgram` and the simulation succeeded.
164
+ readonly userProgramSimulation?: ComposeUserProgramSimulation;
165
+ // GD-8 settlement-fill surface (seam C5): the solver-extractable `fill`,
166
+ // present on every success response — the funding legs it consumes and the
167
+ // freshness bound (absent = no expiry).
168
+ readonly fill?: ComposeFill;
169
+ // The C4 verification echo, keyed by the flow node that carried the
170
+ // commitment (the `continuation.commitment` node on a settlement
171
+ // re-submission, the `continuation.settle` node on authoring-time provider
172
+ // verification). Present only when the compile committed a validation
173
+ // program; today at most one entry (the compiler rejects multi-node
174
+ // committed verification).
175
+ readonly verificationByNode?: Record<string, VerificationDescriptor>;
117
176
  }
118
177
 
119
178
  export interface ComposeCompilePartialData extends ComposeContinuationData {
@@ -122,6 +181,13 @@ export interface ComposeCompilePartialData extends ComposeContinuationData {
122
181
  readonly userProxy: string;
123
182
  readonly simulationRevert: SimulationRevert;
124
183
  readonly approvals?: readonly ApprovalEntry[];
184
+ readonly actions?: readonly ComposeAction[];
185
+ // The per-(input, recipient) fee rows the compiled fill charges. Absent when
186
+ // no fee applies.
187
+ readonly fees?: readonly ComposeFee[];
188
+ // The optional user-program simulation echo, present only when the request
189
+ // opted in via `run.simulateUserProgram` and the simulation succeeded.
190
+ readonly userProgramSimulation?: ComposeUserProgramSimulation;
125
191
  }
126
192
 
127
193
  export type ComposeCompileResult =