@lifi/compose-spec 0.4.1 → 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.d.ts 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';
@@ -1963,8 +1980,6 @@ interface OpHandleOptions<Opt extends boolean = boolean> {
1963
1980
  readonly units?: HandleUnits;
1964
1981
  readonly optional?: Opt;
1965
1982
  }
1966
- declare const inputRef: (port: string) => Ref;
1967
- declare const outputRef: (node: string, port: string) => Ref;
1968
1983
  declare const linear: <N extends string, T extends SolType>(name: N, type: T) => Port & {
1969
1984
  readonly name: N;
1970
1985
  readonly type: T;
@@ -2037,6 +2052,22 @@ declare const isContextKey: (key: string) => key is ContextKey;
2037
2052
  declare const RESERVED_REF_SCOPES: ReadonlySet<string>;
2038
2053
  declare const isRef: (v: unknown) => v is Ref;
2039
2054
  declare const parseRef: (ref: Ref) => ParsedRef;
2055
+ /** A ref path: a dotpath such as `input.amount` or `nodeId.port`. */
2056
+ type RefPath = `${string}.${string}`;
2057
+ /**
2058
+ * Builds a bind ref. `ref.input(port)` for a flow input, `ref.context.*` for a
2059
+ * context ref, and a dotpath for a node output (`ref('deposit.shares')`).
2060
+ * Prefer the named forms: `parseRef` reads an unrecognised prefix as a node id,
2061
+ * so a misspelled `input.`/`context.` silently becomes an output ref.
2062
+ */
2063
+ interface RefBuilder {
2064
+ (path: RefPath): Ref;
2065
+ input(port: string): Ref;
2066
+ readonly context: {
2067
+ readonly [K in ContextKey]: Ref;
2068
+ };
2069
+ }
2070
+ declare const ref: RefBuilder;
2040
2071
  declare const foldRef: <R>(ref: ParsedRef, cases: {
2041
2072
  readonly input: (port: string) => R;
2042
2073
  readonly context: (key: ContextKey) => R;
@@ -2154,16 +2185,18 @@ declare const normalizeNativeTokenAddress: (token: string, chainId: number) => s
2154
2185
  * format is always a decimal string, which the SDK serialises for you.
2155
2186
  *
2156
2187
  * `/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.
2188
+ * document it takes a single from/to token pair; the server builds a one-node
2189
+ * zap flow with a `directDeposit` input on the caller's behalf and runs it
2190
+ * through the same compile pipeline as `POST /compose`. It routes through
2191
+ * `lifi.zap` unless the pair is reachable only asynchronously and the request
2192
+ * set `allowAsyncRoutes`, in which case it uses `lifi.zapAsync`. As of today
2193
+ * the flow it builds is a single zap step — one edge of the server's routing
2194
+ * catalog — and it is meant to author richer flows later, which this request
2195
+ * shape is deliberately agnostic about. Its response body is byte-identical to
2196
+ * that of `POST /compose` — the enveloped `ComposeCompileSuccessData` on HTTP
2197
+ * 200 and `ComposeCompilePartialData` on HTTP 206 — so this file declares only
2198
+ * the request shape and reuses `ComposeCompileResult` from `./compile.js` for
2199
+ * the result.
2167
2200
  *
2168
2201
  * These are the single source of truth for the request shape, hand-authored
2169
2202
  * here for the same reason as `./compile.ts` and `./simulate.ts` rather than
@@ -2269,6 +2302,16 @@ interface ComposeRouteRequest {
2269
2302
  * omitting approvals that are already sufficient. Defaults to `false`.
2270
2303
  */
2271
2304
  readonly checkOnChainAllowances?: boolean;
2305
+ /**
2306
+ * Accept a route whose output is delivered only after the initiating
2307
+ * transaction settles (`availability: 'future'` on the produced resource).
2308
+ * Such a route obliges you to track settlement rather than treat the
2309
+ * transaction as completing the job, and carries no slippage floor, so it is
2310
+ * opt-in. Defaults to `false` server-side, which leaves a pair reachable
2311
+ * only asynchronously rejected with `no_route_error` and guarantees every
2312
+ * produced resource is `availability: 'now'`.
2313
+ */
2314
+ readonly allowAsyncRoutes?: boolean;
2272
2315
  }
2273
2316
 
2274
2317
  /**
@@ -2471,4 +2514,4 @@ declare const foldMaterialiserMetadata: <R>(meta: MaterialiserMetadata, cases: {
2471
2514
  readonly runtime: () => R;
2472
2515
  }) => R;
2473
2516
 
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 };
2517
+ 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 ComposeAction, type ComposeCompilePartialData, type ComposeCompileRequest, type ComposeCompileResult, type ComposeCompileSuccessData, type ComposeError, type ComposeErrorKind, type ComposeFee, type ComposeFill, type ComposeManifest, ComposeManifestZod, type ComposeRouteRequest, type ComposeRun, type ComposeTransactionRequest, type ComposeUserProgramSimulation, 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, canonicalAssertedPredicate, canonicalNativeAddress, 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, providerKindByName, providerKindNames, readResource, ref, refKey, resource, resourceKey, resourceOutput, resourceToken, resourcesEqual };
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
  }),
@@ -395,10 +395,6 @@ var providerKindByName = {
395
395
  };
396
396
 
397
397
  // src/constructors.ts
398
- var inputRef = (port) => ({ $ref: `input.${port}` });
399
- var outputRef = (node, port) => ({
400
- $ref: `${node}.${port}`
401
- });
402
398
  var optionalProp = (key, value) => value !== void 0 && value !== null ? { [key]: value } : {};
403
399
  var linear = (name, type) => ({
404
400
  name,
@@ -465,12 +461,12 @@ var RESERVED_REF_SCOPES = /* @__PURE__ */ new Set([
465
461
  "literal"
466
462
  ]);
467
463
  var isRef = (v) => typeof v === "object" && v !== null && "$ref" in v && typeof v.$ref === "string";
468
- var parseRef = (ref) => {
469
- const dot = ref.$ref.indexOf(".");
464
+ var parseRef = (ref2) => {
465
+ const dot = ref2.$ref.indexOf(".");
470
466
  if (dot === -1)
471
- throw new Error(`Invalid ref: "${ref.$ref}" (must contain a dot)`);
472
- const prefix = ref.$ref.slice(0, dot);
473
- 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);
474
470
  if (prefix === "input") return { scope: "input", port: suffix };
475
471
  if (prefix === "context") {
476
472
  if (!isContextKey(suffix))
@@ -479,12 +475,28 @@ var parseRef = (ref) => {
479
475
  }
480
476
  return { scope: "output", node: prefix, port: suffix };
481
477
  };
482
- var foldRef = (ref, cases) => {
483
- if (ref.scope === "input") return cases.input(ref.port);
484
- if (ref.scope === "context") return cases.context(ref.key);
485
- 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);
486
498
  };
487
- var refKey = (ref) => foldRef(parseRef(ref), {
499
+ var refKey = (ref2) => foldRef(parseRef(ref2), {
488
500
  input: (port) => `input:${port}`,
489
501
  context: (key) => `context:${key}`,
490
502
  output: (node, port) => `output:${node}:${port}`
@@ -645,11 +657,7 @@ var ComposeManifestZod = z.object({
645
657
  var Phase1ArtifactZod = z.discriminatedUnion("kind", [
646
658
  z.object({
647
659
  kind: z.literal("transaction"),
648
- transactionRequest: z.object({
649
- to: z.string(),
650
- data: z.string(),
651
- value: z.string()
652
- }).optional()
660
+ funding: z.enum(["inline", "external"])
653
661
  }),
654
662
  z.object({
655
663
  kind: z.literal("signables"),
@@ -766,7 +774,6 @@ export {
766
774
  ContinuationOutcomeSchema,
767
775
  ContinuationPlanSchema,
768
776
  ContinuationPlanZod,
769
- ContinuationSchema,
770
777
  EVM_NATIVE_SENTINEL,
771
778
  Erc20BalanceDeltaGteSpecSchema,
772
779
  Erc20BalanceGteSpecSchema,
@@ -822,7 +829,6 @@ export {
822
829
  foldResource,
823
830
  getChainCapabilities,
824
831
  handle,
825
- inputRef,
826
832
  isAsErc20Chain,
827
833
  isContextKey,
828
834
  isEQCheck,
@@ -849,11 +855,11 @@ export {
849
855
  normalizeNativeTokenAddress,
850
856
  normalizeResource,
851
857
  opHandle,
852
- outputRef,
853
858
  parseRef,
854
859
  providerKindByName,
855
860
  providerKindNames,
856
861
  readResource,
862
+ ref,
857
863
  refKey,
858
864
  resource,
859
865
  resourceKey,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@lifi/compose-spec",
3
- "version": "0.4.1",
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",
@@ -58,8 +53,6 @@
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
57
  "typescript": "^6.0.3",
65
58
  "vitest": "^3.2.4"
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 =
@@ -4,7 +4,7 @@ import type {
4
4
  ResourceOutputPort,
5
5
  ResourcePort,
6
6
  } from './flow.js';
7
- import type { HandleInput, Ref, ResourceInput, SolType } from './flowSchema.js';
7
+ import type { HandleInput, ResourceInput, SolType } from './flowSchema.js';
8
8
  import type { Availability } from './resource.js';
9
9
  import { erc20Resource, nativeResource } from './resource.js';
10
10
  import type { HandleUnits } from './zodSchemas.js';
@@ -15,12 +15,6 @@ export interface OpHandleOptions<Opt extends boolean = boolean> {
15
15
  readonly optional?: Opt;
16
16
  }
17
17
 
18
- export const inputRef = (port: string): Ref => ({ $ref: `input.${port}` });
19
-
20
- export const outputRef = (node: string, port: string): Ref => ({
21
- $ref: `${node}.${port}`,
22
- });
23
-
24
18
  /** Returns `{ [key]: value }` when `value` is not nullish, else `{}`. */
25
19
  const optionalProp = <K extends string, V>(
26
20
  key: K,