@lifi/compose-spec 0.5.1 → 0.6.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/README.md CHANGED
@@ -13,7 +13,8 @@ npm install @lifi/compose-spec
13
13
  ## What's included
14
14
 
15
15
  - **Flow schema types** — `Flow`, `Call`, `Continuation`, `Ref`, `BindValue`, and related types that define the structure of a Compose flow document
16
- - **Resource types** — `Resource`, `Availability`, `OutputAmount`, `SimulatedAmounts`, plus helpers like `erc20Token`, `foldResource`, `resourceKey`
16
+ - **Resource types** — `Resource`, `Availability`, plus helpers like `erc20Token`, `foldResource`, `resourceKey`
17
+ - **Output types** — `Outputs`, `Output`, `ConsumedOutput`, `TerminalOutput`, `Amount`, `Estimate`, `Minimum`, `Delivery`, `EstimateBasis`, `MinimumBasis` — the per-port `outputs` record on a compile result
17
18
  - **Manifest types** — `ComposeManifest`, `ManifestOperation`, `ManifestGuard`, `ManifestMaterialiser`, `ManifestPrecondition`
18
19
  - **Port types** — `ResourcePort`, `HandlePort`, `OpInputPort`, `OpOutputPort`, and type guards
19
20
  - **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
package/dist/index.cjs CHANGED
@@ -145,7 +145,8 @@ __export(index_exports, {
145
145
  resourceKey: () => resourceKey,
146
146
  resourceOutput: () => resourceOutput,
147
147
  resourceToken: () => resourceToken,
148
- resourcesEqual: () => resourcesEqual
148
+ resourcesEqual: () => resourcesEqual,
149
+ settledOutcome: () => settledOutcome
149
150
  });
150
151
  module.exports = __toCommonJS(index_exports);
151
152
 
@@ -410,6 +411,7 @@ var ContinuationPlanSchema = import_effect2.Schema.Struct({
410
411
  validity: import_effect2.Schema.Struct({ expiresAtMs: import_effect2.Schema.Number }),
411
412
  correlationId: import_effect2.Schema.optional(import_effect2.Schema.String)
412
413
  });
414
+ var settledOutcome = (intent) => intent.outcomes[0];
413
415
  var isGTECheck = (check) => check.kind === "call" && check.comparator === "gte";
414
416
  var isLTECheck = (check) => check.kind === "call" && check.comparator === "lte";
415
417
  var isEQCheck = (check) => check.kind === "call" && check.comparator === "eq";
@@ -680,12 +682,13 @@ var parseVersion = (version) => {
680
682
  return { major, minor, patch };
681
683
  };
682
684
  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
- }
685
+ var checkCompatibility = (client, server, minimum = {
686
+ major: server.major,
687
+ minor: server.minor,
688
+ patch: 0
689
+ }) => {
690
+ if (compareVersions(client, server) > 0) return "server_outdated";
691
+ if (compareVersions(client, minimum) < 0) return "sdk_outdated";
689
692
  return "compatible";
690
693
  };
691
694
 
@@ -1046,5 +1049,6 @@ var ContinuationPlanZod = import_zod.default.object({
1046
1049
  resourceKey,
1047
1050
  resourceOutput,
1048
1051
  resourceToken,
1049
- resourcesEqual
1052
+ resourcesEqual,
1053
+ settledOutcome
1050
1054
  });
package/dist/index.d.cts CHANGED
@@ -557,6 +557,7 @@ type Phase1Artifact = typeof Phase1ArtifactSchema.Type;
557
557
  type Check = typeof CheckSchema.Type;
558
558
  type AssertionSpec = typeof AssertionSpecSchema.Type;
559
559
  type ContinuationPlan = typeof ContinuationPlanSchema.Type;
560
+ declare const settledOutcome: (intent: ContinuationIntent) => ContinuationOutcome;
560
561
  type CheckComparator = 'gte' | 'eq' | 'lte';
561
562
  declare const isGTECheck: (check: Check) => boolean;
562
563
  declare const isLTECheck: (check: Check) => boolean;
@@ -773,16 +774,6 @@ type Resource = {
773
774
  readonly token: string;
774
775
  readonly chainId: number;
775
776
  };
776
- type SimulatedAmounts = {
777
- readonly amountOut: bigint;
778
- readonly amountOutMin?: bigint;
779
- };
780
- type ProducedResource = Resource & {
781
- readonly availability: Availability;
782
- readonly simulated?: SimulatedAmounts;
783
- readonly owner: string;
784
- readonly etaSeconds?: number;
785
- };
786
777
  declare const erc20Resource: (token: string, chainId: number) => Resource;
787
778
  declare const nativeResource: (chainId: number) => Resource;
788
779
  declare const isERC20Resource: (r: Resource) => r is Extract<Resource, {
@@ -800,6 +791,43 @@ declare const resourceToken: (r: Resource) => string;
800
791
  declare const resourceKey: (r: Resource) => string;
801
792
  declare const erc20Token: (r: Resource) => string;
802
793
 
794
+ type EstimateBasis = 'simulated' | 'quoted';
795
+ type MinimumBasis = 'guard' | 'op' | 'declared';
796
+ interface Estimate {
797
+ readonly basis: EstimateBasis;
798
+ readonly value: bigint;
799
+ }
800
+ interface Minimum {
801
+ readonly basis: MinimumBasis;
802
+ readonly value: bigint;
803
+ }
804
+ interface Amount {
805
+ readonly estimate?: Estimate;
806
+ readonly minimum?: Minimum;
807
+ }
808
+ type Delivery = {
809
+ readonly when: 'now';
810
+ } | {
811
+ readonly when: 'future';
812
+ readonly etaSeconds?: number;
813
+ readonly provider?: string;
814
+ };
815
+ interface OutputBase {
816
+ readonly resource: Resource;
817
+ readonly amount: Amount;
818
+ }
819
+ interface ConsumedOutput extends OutputBase {
820
+ readonly role: 'consumed';
821
+ readonly consumedBy: string;
822
+ }
823
+ interface TerminalOutput extends OutputBase {
824
+ readonly role: 'terminal';
825
+ readonly owner: string;
826
+ readonly delivery: Delivery;
827
+ }
828
+ type Output = ConsumedOutput | TerminalOutput;
829
+ type Outputs = Record<string, Output>;
830
+
803
831
  declare const ResourcePortZod: z.ZodObject<{
804
832
  kind: z.ZodLiteral<"resource">;
805
833
  name: z.ZodString;
@@ -1872,7 +1900,7 @@ interface ComposeFill {
1872
1900
  readonly validUntilMs?: number;
1873
1901
  }
1874
1902
  interface ComposeCompileSuccessData extends ComposeContinuationData {
1875
- readonly producedResources: Record<string, ProducedResource>;
1903
+ readonly outputs: Outputs;
1876
1904
  readonly transactionRequest?: ComposeTransactionRequest;
1877
1905
  readonly actions?: readonly ComposeAction[];
1878
1906
  readonly userProxy: string;
@@ -1884,7 +1912,7 @@ interface ComposeCompileSuccessData extends ComposeContinuationData {
1884
1912
  readonly verificationByNode?: Record<string, VerificationDescriptor>;
1885
1913
  }
1886
1914
  interface ComposeCompilePartialData extends ComposeContinuationData {
1887
- readonly producedResources: Record<string, ProducedResource>;
1915
+ readonly outputs: Outputs;
1888
1916
  readonly transactionRequest: ComposeTransactionRequest;
1889
1917
  readonly userProxy: string;
1890
1918
  readonly simulationRevert: SimulationRevert;
@@ -2308,12 +2336,12 @@ interface ComposeRouteRequest {
2308
2336
  readonly checkOnChainAllowances?: boolean;
2309
2337
  /**
2310
2338
  * Accept a route whose output is delivered only after the initiating
2311
- * transaction settles (`availability: 'future'` on the produced resource).
2339
+ * transaction settles (`delivery.when: 'future'` on the terminal output).
2312
2340
  * Such a route obliges you to track settlement rather than treat the
2313
2341
  * transaction as completing the job, and carries no slippage floor, so it is
2314
2342
  * opt-in. Defaults to `false` server-side, which leaves a pair reachable
2315
2343
  * only asynchronously rejected with `no_route_error` and guarantees every
2316
- * produced resource is `availability: 'now'`.
2344
+ * terminal output is `delivery.when: 'now'`.
2317
2345
  */
2318
2346
  readonly allowAsyncRoutes?: boolean;
2319
2347
  }
@@ -2537,19 +2565,25 @@ type VersionCompatibility = 'compatible' | 'sdk_outdated' | 'server_outdated';
2537
2565
  declare const parseVersion: (version: string) => ComposeVersion | undefined;
2538
2566
  /**
2539
2567
  * Decides whether a client built against `client` may talk to a server that
2540
- * serves `server`.
2568
+ * serves `server` and accepts clients down to `minimum`.
2569
+ *
2570
+ * - A client ahead of the server in any component is `server_outdated`. Even
2571
+ * a patch-ahead client may send a field the server has never seen, and the
2572
+ * guarantee must not depend on every server schema staying strict. This is
2573
+ * the rollout window between an npm publish and the prod image bump.
2574
+ * - A client below `minimum` is `sdk_outdated`: the server no longer serves
2575
+ * the contract that client speaks.
2576
+ * - Anything in between is compatible. Patch releases only add, so a client
2577
+ * at or behind the server's patch never emits anything the server lacks;
2578
+ * a client on an older minor is served because the server still emits the
2579
+ * shapes that minor reads.
2541
2580
  *
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.
2581
+ * `minimum` defaults to the server's own `major.minor.0`, which makes every
2582
+ * minor bump a hard cutover. The backend passes its explicit floor so a minor
2583
+ * bump can ship with the previous line still accepted; the SDK passes no floor
2584
+ * because the server, not the client, decides how far back it serves.
2551
2585
  */
2552
- declare const checkCompatibility: (client: ComposeVersion, server: ComposeVersion) => VersionCompatibility;
2586
+ declare const checkCompatibility: (client: ComposeVersion, server: ComposeVersion, minimum?: ComposeVersion) => VersionCompatibility;
2553
2587
 
2554
2588
  type MaterialiserMetadata = {
2555
2589
  readonly kind: 'exact';
@@ -2570,4 +2604,4 @@ declare const foldMaterialiserMetadata: <R>(meta: MaterialiserMetadata, cases: {
2570
2604
  readonly runtime: () => R;
2571
2605
  }) => R;
2572
2606
 
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 };
2607
+ export { type Amount, 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 ConsumedOutput, type ContextKey, type ContinuationIntent, ContinuationIntentSchema, type ContinuationOutcome, ContinuationOutcomeSchema, type ContinuationPlan, ContinuationPlanSchema, type ContinuationPlanWire, ContinuationPlanZod, type Delivery, EVM_NATIVE_SENTINEL, type Erc20AllowancePrecondition, type Erc20AllowanceRequirement, Erc20BalanceDeltaGteSpecSchema, Erc20BalanceGteSpecSchema, type Erc20BalancePrecondition, type Erc20BalanceRequirement, type Estimate, type EstimateBasis, 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, type Minimum, type MinimumBasis, NativeBalanceDeltaGteSpecSchema, NativeBalanceGteSpecSchema, type NativeBalancePrecondition, type NativeBalanceRequirement, type NativeErc20, type OpInputPort, type OpOutputPort, type Output, type OutputAmount, OutputPortZod, type Outputs, 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 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 SimulationPolicy, type SimulationRevert, type SimulationRevertComposeError, type SlotFinderRequirement, type SolType, SolTypeSchema, type SpendEntry, type StaticSolType, StaticSolTypeZod, type SweepTo, TEMPO_CHAIN_ID, TEMPO_NATIVE_ERC20, type TerminalOutput, 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, settledOutcome };
package/dist/index.d.ts CHANGED
@@ -557,6 +557,7 @@ type Phase1Artifact = typeof Phase1ArtifactSchema.Type;
557
557
  type Check = typeof CheckSchema.Type;
558
558
  type AssertionSpec = typeof AssertionSpecSchema.Type;
559
559
  type ContinuationPlan = typeof ContinuationPlanSchema.Type;
560
+ declare const settledOutcome: (intent: ContinuationIntent) => ContinuationOutcome;
560
561
  type CheckComparator = 'gte' | 'eq' | 'lte';
561
562
  declare const isGTECheck: (check: Check) => boolean;
562
563
  declare const isLTECheck: (check: Check) => boolean;
@@ -773,16 +774,6 @@ type Resource = {
773
774
  readonly token: string;
774
775
  readonly chainId: number;
775
776
  };
776
- type SimulatedAmounts = {
777
- readonly amountOut: bigint;
778
- readonly amountOutMin?: bigint;
779
- };
780
- type ProducedResource = Resource & {
781
- readonly availability: Availability;
782
- readonly simulated?: SimulatedAmounts;
783
- readonly owner: string;
784
- readonly etaSeconds?: number;
785
- };
786
777
  declare const erc20Resource: (token: string, chainId: number) => Resource;
787
778
  declare const nativeResource: (chainId: number) => Resource;
788
779
  declare const isERC20Resource: (r: Resource) => r is Extract<Resource, {
@@ -800,6 +791,43 @@ declare const resourceToken: (r: Resource) => string;
800
791
  declare const resourceKey: (r: Resource) => string;
801
792
  declare const erc20Token: (r: Resource) => string;
802
793
 
794
+ type EstimateBasis = 'simulated' | 'quoted';
795
+ type MinimumBasis = 'guard' | 'op' | 'declared';
796
+ interface Estimate {
797
+ readonly basis: EstimateBasis;
798
+ readonly value: bigint;
799
+ }
800
+ interface Minimum {
801
+ readonly basis: MinimumBasis;
802
+ readonly value: bigint;
803
+ }
804
+ interface Amount {
805
+ readonly estimate?: Estimate;
806
+ readonly minimum?: Minimum;
807
+ }
808
+ type Delivery = {
809
+ readonly when: 'now';
810
+ } | {
811
+ readonly when: 'future';
812
+ readonly etaSeconds?: number;
813
+ readonly provider?: string;
814
+ };
815
+ interface OutputBase {
816
+ readonly resource: Resource;
817
+ readonly amount: Amount;
818
+ }
819
+ interface ConsumedOutput extends OutputBase {
820
+ readonly role: 'consumed';
821
+ readonly consumedBy: string;
822
+ }
823
+ interface TerminalOutput extends OutputBase {
824
+ readonly role: 'terminal';
825
+ readonly owner: string;
826
+ readonly delivery: Delivery;
827
+ }
828
+ type Output = ConsumedOutput | TerminalOutput;
829
+ type Outputs = Record<string, Output>;
830
+
803
831
  declare const ResourcePortZod: z.ZodObject<{
804
832
  kind: z.ZodLiteral<"resource">;
805
833
  name: z.ZodString;
@@ -1872,7 +1900,7 @@ interface ComposeFill {
1872
1900
  readonly validUntilMs?: number;
1873
1901
  }
1874
1902
  interface ComposeCompileSuccessData extends ComposeContinuationData {
1875
- readonly producedResources: Record<string, ProducedResource>;
1903
+ readonly outputs: Outputs;
1876
1904
  readonly transactionRequest?: ComposeTransactionRequest;
1877
1905
  readonly actions?: readonly ComposeAction[];
1878
1906
  readonly userProxy: string;
@@ -1884,7 +1912,7 @@ interface ComposeCompileSuccessData extends ComposeContinuationData {
1884
1912
  readonly verificationByNode?: Record<string, VerificationDescriptor>;
1885
1913
  }
1886
1914
  interface ComposeCompilePartialData extends ComposeContinuationData {
1887
- readonly producedResources: Record<string, ProducedResource>;
1915
+ readonly outputs: Outputs;
1888
1916
  readonly transactionRequest: ComposeTransactionRequest;
1889
1917
  readonly userProxy: string;
1890
1918
  readonly simulationRevert: SimulationRevert;
@@ -2308,12 +2336,12 @@ interface ComposeRouteRequest {
2308
2336
  readonly checkOnChainAllowances?: boolean;
2309
2337
  /**
2310
2338
  * Accept a route whose output is delivered only after the initiating
2311
- * transaction settles (`availability: 'future'` on the produced resource).
2339
+ * transaction settles (`delivery.when: 'future'` on the terminal output).
2312
2340
  * Such a route obliges you to track settlement rather than treat the
2313
2341
  * transaction as completing the job, and carries no slippage floor, so it is
2314
2342
  * opt-in. Defaults to `false` server-side, which leaves a pair reachable
2315
2343
  * only asynchronously rejected with `no_route_error` and guarantees every
2316
- * produced resource is `availability: 'now'`.
2344
+ * terminal output is `delivery.when: 'now'`.
2317
2345
  */
2318
2346
  readonly allowAsyncRoutes?: boolean;
2319
2347
  }
@@ -2537,19 +2565,25 @@ type VersionCompatibility = 'compatible' | 'sdk_outdated' | 'server_outdated';
2537
2565
  declare const parseVersion: (version: string) => ComposeVersion | undefined;
2538
2566
  /**
2539
2567
  * Decides whether a client built against `client` may talk to a server that
2540
- * serves `server`.
2568
+ * serves `server` and accepts clients down to `minimum`.
2569
+ *
2570
+ * - A client ahead of the server in any component is `server_outdated`. Even
2571
+ * a patch-ahead client may send a field the server has never seen, and the
2572
+ * guarantee must not depend on every server schema staying strict. This is
2573
+ * the rollout window between an npm publish and the prod image bump.
2574
+ * - A client below `minimum` is `sdk_outdated`: the server no longer serves
2575
+ * the contract that client speaks.
2576
+ * - Anything in between is compatible. Patch releases only add, so a client
2577
+ * at or behind the server's patch never emits anything the server lacks;
2578
+ * a client on an older minor is served because the server still emits the
2579
+ * shapes that minor reads.
2541
2580
  *
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.
2581
+ * `minimum` defaults to the server's own `major.minor.0`, which makes every
2582
+ * minor bump a hard cutover. The backend passes its explicit floor so a minor
2583
+ * bump can ship with the previous line still accepted; the SDK passes no floor
2584
+ * because the server, not the client, decides how far back it serves.
2551
2585
  */
2552
- declare const checkCompatibility: (client: ComposeVersion, server: ComposeVersion) => VersionCompatibility;
2586
+ declare const checkCompatibility: (client: ComposeVersion, server: ComposeVersion, minimum?: ComposeVersion) => VersionCompatibility;
2553
2587
 
2554
2588
  type MaterialiserMetadata = {
2555
2589
  readonly kind: 'exact';
@@ -2570,4 +2604,4 @@ declare const foldMaterialiserMetadata: <R>(meta: MaterialiserMetadata, cases: {
2570
2604
  readonly runtime: () => R;
2571
2605
  }) => R;
2572
2606
 
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 };
2607
+ export { type Amount, 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 ConsumedOutput, type ContextKey, type ContinuationIntent, ContinuationIntentSchema, type ContinuationOutcome, ContinuationOutcomeSchema, type ContinuationPlan, ContinuationPlanSchema, type ContinuationPlanWire, ContinuationPlanZod, type Delivery, EVM_NATIVE_SENTINEL, type Erc20AllowancePrecondition, type Erc20AllowanceRequirement, Erc20BalanceDeltaGteSpecSchema, Erc20BalanceGteSpecSchema, type Erc20BalancePrecondition, type Erc20BalanceRequirement, type Estimate, type EstimateBasis, 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, type Minimum, type MinimumBasis, NativeBalanceDeltaGteSpecSchema, NativeBalanceGteSpecSchema, type NativeBalancePrecondition, type NativeBalanceRequirement, type NativeErc20, type OpInputPort, type OpOutputPort, type Output, type OutputAmount, OutputPortZod, type Outputs, 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 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 SimulationPolicy, type SimulationRevert, type SimulationRevertComposeError, type SlotFinderRequirement, type SolType, SolTypeSchema, type SpendEntry, type StaticSolType, StaticSolTypeZod, type SweepTo, TEMPO_CHAIN_ID, TEMPO_NATIVE_ERC20, type TerminalOutput, 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, settledOutcome };
package/dist/index.js CHANGED
@@ -259,6 +259,7 @@ var ContinuationPlanSchema = Schema2.Struct({
259
259
  validity: Schema2.Struct({ expiresAtMs: Schema2.Number }),
260
260
  correlationId: Schema2.optional(Schema2.String)
261
261
  });
262
+ var settledOutcome = (intent) => intent.outcomes[0];
262
263
  var isGTECheck = (check) => check.kind === "call" && check.comparator === "gte";
263
264
  var isLTECheck = (check) => check.kind === "call" && check.comparator === "lte";
264
265
  var isEQCheck = (check) => check.kind === "call" && check.comparator === "eq";
@@ -529,12 +530,13 @@ var parseVersion = (version) => {
529
530
  return { major, minor, patch };
530
531
  };
531
532
  var compareVersions = (a, b) => a.major !== b.major ? a.major - b.major : a.minor !== b.minor ? a.minor - b.minor : a.patch - b.patch;
532
- var checkCompatibility = (client, server) => {
533
- const order = compareVersions(client, server);
534
- if (order > 0) return "server_outdated";
535
- if (client.major !== server.major || client.minor !== server.minor) {
536
- return "sdk_outdated";
537
- }
533
+ var checkCompatibility = (client, server, minimum = {
534
+ major: server.major,
535
+ minor: server.minor,
536
+ patch: 0
537
+ }) => {
538
+ if (compareVersions(client, server) > 0) return "server_outdated";
539
+ if (compareVersions(client, minimum) < 0) return "sdk_outdated";
538
540
  return "compatible";
539
541
  };
540
542
 
@@ -894,5 +896,6 @@ export {
894
896
  resourceKey,
895
897
  resourceOutput,
896
898
  resourceToken,
897
- resourcesEqual
899
+ resourcesEqual,
900
+ settledOutcome
898
901
  };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@lifi/compose-spec",
3
- "version": "0.5.1",
3
+ "version": "0.6.0",
4
4
  "description": "Public wire-format types and schemas for Compose flows",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {
package/src/compile.ts CHANGED
@@ -1,7 +1,7 @@
1
1
  import type { VerificationDescriptor } from './descriptor.js';
2
2
  import type { InputSpec, Precondition } from './flow.js';
3
3
  import type { Flow } from './flowSchema.js';
4
- import type { ProducedResource } from './resource.js';
4
+ import type { Outputs } from './output.js';
5
5
  import type { ContinuationPlanWire, Phase1ArtifactWire } from './zodSchemas.js';
6
6
 
7
7
  export type SimulationPolicy = 'strict' | 'allow-revert';
@@ -149,7 +149,11 @@ export interface ComposeFill {
149
149
  }
150
150
 
151
151
  export interface ComposeCompileSuccessData extends ComposeContinuationData {
152
- readonly producedResources: Record<string, ProducedResource>;
152
+ // Every linear resource output port, consumed or terminal, keyed
153
+ // `<nodeId>.<portName>`. See `Output` for the per-entry rules. Hand-mirrored
154
+ // from api-schemas' `OutputSchema` (the OpenAPI source of truth; this
155
+ // package cannot depend on it); the SDK decodes the wire strings to `bigint`.
156
+ readonly outputs: Outputs;
153
157
  // The OpenAPI source of truth documents the optionality and funding modes.
154
158
  readonly transactionRequest?: ComposeTransactionRequest;
155
159
  readonly actions?: readonly ComposeAction[];
@@ -176,7 +180,9 @@ export interface ComposeCompileSuccessData extends ComposeContinuationData {
176
180
  }
177
181
 
178
182
  export interface ComposeCompilePartialData extends ComposeContinuationData {
179
- readonly producedResources: Record<string, ProducedResource>;
183
+ // Mirrors `ComposeCompileSuccessData.outputs`. A revert measured nothing, so
184
+ // estimates are quotes and minimums are op-sourced.
185
+ readonly outputs: Outputs;
180
186
  readonly transactionRequest: ComposeTransactionRequest;
181
187
  readonly userProxy: string;
182
188
  readonly simulationRevert: SimulationRevert;
@@ -263,6 +263,16 @@ export type Check = typeof CheckSchema.Type;
263
263
  export type AssertionSpec = typeof AssertionSpecSchema.Type;
264
264
  export type ContinuationPlan = typeof ContinuationPlanSchema.Type;
265
265
 
266
+ // The outcome a `continuation.settle` node's single `output` port stands for.
267
+ // The wire format admits several outcomes, but the op produces one resource,
268
+ // discloses one owner, and every shipped provider rejects a multi-outcome
269
+ // intent, so the first outcome is the settled one everywhere. `NonEmptyArray`
270
+ // makes `[0]` present by construction. Keep this the only place that picks
271
+ // it: a multi-outcome design changes one accessor, not a scatter of `[0]`s.
272
+ export const settledOutcome = (
273
+ intent: ContinuationIntent,
274
+ ): ContinuationOutcome => intent.outcomes[0];
275
+
266
276
  // The comparison operator carried by a `call` check. Mirrors the inline
267
277
  // `comparator` literal on the `call` member of `RawCheckSchema` above.
268
278
  export type CheckComparator = 'gte' | 'eq' | 'lte';
package/src/index.ts CHANGED
@@ -52,6 +52,7 @@ export {
52
52
  isGTECheck,
53
53
  isLTECheck,
54
54
  isEQCheck,
55
+ settledOutcome,
55
56
  } from './continuation.js';
56
57
 
57
58
  export type {
@@ -104,13 +105,7 @@ export {
104
105
  isMaterialiserInput,
105
106
  } from './flow.js';
106
107
 
107
- export type {
108
- Availability,
109
- OutputAmount,
110
- Resource,
111
- ProducedResource,
112
- SimulatedAmounts,
113
- } from './resource.js';
108
+ export type { Availability, OutputAmount, Resource } from './resource.js';
114
109
  export {
115
110
  erc20Resource,
116
111
  erc20Token,
@@ -123,6 +118,19 @@ export {
123
118
  resourcesEqual,
124
119
  } from './resource.js';
125
120
 
121
+ export type {
122
+ Amount,
123
+ ConsumedOutput,
124
+ Delivery,
125
+ Estimate,
126
+ EstimateBasis,
127
+ Minimum,
128
+ MinimumBasis,
129
+ Output,
130
+ Outputs,
131
+ TerminalOutput,
132
+ } from './output.js';
133
+
126
134
  export type {
127
135
  ProviderKindName,
128
136
  FlashloanMaterialiserInput,
package/src/output.ts ADDED
@@ -0,0 +1,67 @@
1
+ import type { Resource } from './resource.js';
2
+
3
+ // The per-port `outputs` record on the compose compile response, keyed
4
+ // `<nodeId>.<portName>`. One entry exists for every linear resource output
5
+ // port in the flow, whether a later node spends it (`consumed`) or it is
6
+ // delivered to `owner` (`terminal`). An entry is omitted only when its port
7
+ // declares `omitIfZero` and the simulation measured it at zero. `estimate` is
8
+ // the measured value when the simulation observed the port, otherwise the
9
+ // prepared op's quote, otherwise absent. `minimum` is the enforced floor: the
10
+ // larger of a guard floor and an op floor when either exists (tagged with its
11
+ // source, `guard` on a tie), else the estimate echoed when the port declares
12
+ // `providesMinimum` (`declared`), else absent. There is no zero placeholder;
13
+ // an absent `minimum` means no floor is known.
14
+
15
+ export type EstimateBasis = 'simulated' | 'quoted';
16
+
17
+ export type MinimumBasis = 'guard' | 'op' | 'declared';
18
+
19
+ export interface Estimate {
20
+ readonly basis: EstimateBasis;
21
+ readonly value: bigint;
22
+ }
23
+
24
+ export interface Minimum {
25
+ readonly basis: MinimumBasis;
26
+ readonly value: bigint;
27
+ }
28
+
29
+ export interface Amount {
30
+ readonly estimate?: Estimate;
31
+ readonly minimum?: Minimum;
32
+ }
33
+
34
+ // `etaSeconds` is the routing edge's or prepared quote's published estimate of
35
+ // how long deferred proceeds take to land; absent means no estimate is
36
+ // published, never zero. `provider` is the key of the external system that
37
+ // delivers them — for `lifi.bridge` the LI.FI tool key, which is the `bridge`
38
+ // parameter of LI.FI's `/v1/status` lookup; absent when the op does not name
39
+ // one.
40
+ export type Delivery =
41
+ | { readonly when: 'now' }
42
+ | {
43
+ readonly when: 'future';
44
+ readonly etaSeconds?: number;
45
+ readonly provider?: string;
46
+ };
47
+
48
+ interface OutputBase {
49
+ readonly resource: Resource;
50
+ readonly amount: Amount;
51
+ }
52
+
53
+ export interface ConsumedOutput extends OutputBase {
54
+ readonly role: 'consumed';
55
+ // The id of the call whose non-copy input binds this port.
56
+ readonly consumedBy: string;
57
+ }
58
+
59
+ export interface TerminalOutput extends OutputBase {
60
+ readonly role: 'terminal';
61
+ readonly owner: string;
62
+ readonly delivery: Delivery;
63
+ }
64
+
65
+ export type Output = ConsumedOutput | TerminalOutput;
66
+
67
+ export type Outputs = Record<string, Output>;
package/src/resource.ts CHANGED
@@ -15,22 +15,6 @@ export type Resource =
15
15
  readonly chainId: number;
16
16
  };
17
17
 
18
- export type SimulatedAmounts = {
19
- readonly amountOut: bigint;
20
- readonly amountOutMin?: bigint;
21
- };
22
-
23
- export type ProducedResource = Resource & {
24
- readonly availability: Availability;
25
- readonly simulated?: SimulatedAmounts;
26
- readonly owner: string;
27
- // Wire ETA: seconds until deferred proceeds land, echoed from the routing edge
28
- // that produced this output. Only valid alongside `availability: 'future'`;
29
- // absent means no published estimate, never zero. See "ETA" in
30
- // `docs/glossary.md` (COM-1564).
31
- readonly etaSeconds?: number;
32
- };
33
-
34
18
  export const erc20Resource = (token: string, chainId: number): Resource => ({
35
19
  kind: 'erc20',
36
20
  token,
package/src/route.ts CHANGED
@@ -128,12 +128,12 @@ export interface ComposeRouteRequest {
128
128
  readonly checkOnChainAllowances?: boolean;
129
129
  /**
130
130
  * Accept a route whose output is delivered only after the initiating
131
- * transaction settles (`availability: 'future'` on the produced resource).
131
+ * transaction settles (`delivery.when: 'future'` on the terminal output).
132
132
  * Such a route obliges you to track settlement rather than treat the
133
133
  * transaction as completing the job, and carries no slippage floor, so it is
134
134
  * opt-in. Defaults to `false` server-side, which leaves a pair reachable
135
135
  * only asynchronously rejected with `no_route_error` and guarantees every
136
- * produced resource is `availability: 'now'`.
136
+ * terminal output is `delivery.when: 'now'`.
137
137
  */
138
138
  readonly allowAsyncRoutes?: boolean;
139
139
  }
package/src/version.ts CHANGED
@@ -49,26 +49,34 @@ const compareVersions = (a: ComposeVersion, b: ComposeVersion): number =>
49
49
 
50
50
  /**
51
51
  * Decides whether a client built against `client` may talk to a server that
52
- * serves `server`.
52
+ * serves `server` and accepts clients down to `minimum`.
53
53
  *
54
- * - Same `major.minor` with the client at or behind the server's patch is
55
- * compatible: patch releases only add, so an older client never emits
56
- * anything the server lacks.
57
- * - A client below the server's `major.minor` is `sdk_outdated`: the server
58
- * made a breaking change the client does not know about.
59
- * - A client ahead in any component is `server_outdated`. Even a patch-ahead
60
- * client may send a field the server has never seen, and the guarantee must
61
- * not depend on every server schema staying strict. This is the rollout
62
- * window between an npm publish and the prod image bump.
54
+ * - A client ahead of the server in any component is `server_outdated`. Even
55
+ * a patch-ahead client may send a field the server has never seen, and the
56
+ * guarantee must not depend on every server schema staying strict. This is
57
+ * the rollout window between an npm publish and the prod image bump.
58
+ * - A client below `minimum` is `sdk_outdated`: the server no longer serves
59
+ * the contract that client speaks.
60
+ * - Anything in between is compatible. Patch releases only add, so a client
61
+ * at or behind the server's patch never emits anything the server lacks;
62
+ * a client on an older minor is served because the server still emits the
63
+ * shapes that minor reads.
64
+ *
65
+ * `minimum` defaults to the server's own `major.minor.0`, which makes every
66
+ * minor bump a hard cutover. The backend passes its explicit floor so a minor
67
+ * bump can ship with the previous line still accepted; the SDK passes no floor
68
+ * because the server, not the client, decides how far back it serves.
63
69
  */
64
70
  export const checkCompatibility = (
65
71
  client: ComposeVersion,
66
72
  server: ComposeVersion,
73
+ minimum: ComposeVersion = {
74
+ major: server.major,
75
+ minor: server.minor,
76
+ patch: 0,
77
+ },
67
78
  ): VersionCompatibility => {
68
- const order = compareVersions(client, server);
69
- if (order > 0) return 'server_outdated';
70
- if (client.major !== server.major || client.minor !== server.minor) {
71
- return 'sdk_outdated';
72
- }
79
+ if (compareVersions(client, server) > 0) return 'server_outdated';
80
+ if (compareVersions(client, minimum) < 0) return 'sdk_outdated';
73
81
  return 'compatible';
74
82
  };