@lifi/compose-spec 0.5.0 → 0.5.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.cjs CHANGED
@@ -40,6 +40,8 @@ __export(index_exports, {
40
40
  AssertionSpecZod: () => AssertionSpecZod,
41
41
  BindValueSchema: () => BindValueSchema,
42
42
  Bytes32HexSchema: () => Bytes32HexSchema,
43
+ COMPOSER_SDK_VERSION_HEADER: () => COMPOSER_SDK_VERSION_HEADER,
44
+ COMPOSE_VERSION_HEADER: () => COMPOSE_VERSION_HEADER,
43
45
  CONTINUATION_COMMITMENT_OP_ID: () => CONTINUATION_COMMITMENT_OP_ID,
44
46
  CallCheckSpecSchema: () => CallCheckSpecSchema,
45
47
  CallSchema: () => CallSchema,
@@ -91,6 +93,7 @@ __export(index_exports, {
91
93
  VerificationDescriptorZod: () => VerificationDescriptorZod,
92
94
  canonicalAssertedPredicate: () => canonicalAssertedPredicate,
93
95
  canonicalNativeAddress: () => canonicalNativeAddress,
96
+ checkCompatibility: () => checkCompatibility,
94
97
  copy: () => copy,
95
98
  erc20: () => erc20,
96
99
  erc20Allowance: () => erc20Allowance,
@@ -132,6 +135,7 @@ __export(index_exports, {
132
135
  normalizeResource: () => normalizeResource,
133
136
  opHandle: () => opHandle,
134
137
  parseRef: () => parseRef,
138
+ parseVersion: () => parseVersion,
135
139
  providerKindByName: () => providerKindByName,
136
140
  providerKindNames: () => providerKindNames,
137
141
  readResource: () => readResource,
@@ -660,6 +664,31 @@ var isNativeBalancePrecondition = (p) => p.type === "NativeBalance";
660
664
  var SIMULATE_MAX_TRACKED_BALANCES = 40;
661
665
  var SIMULATE_MAX_REQUIREMENTS = 40;
662
666
 
667
+ // src/headers.ts
668
+ var COMPOSER_SDK_VERSION_HEADER = "x-lifi-composer-sdk";
669
+ var COMPOSE_VERSION_HEADER = "x-lifi-composer-version";
670
+
671
+ // src/version.ts
672
+ var SEMANTIC_VERSION_PATTERN = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*)(?:\.(?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*))*))?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
673
+ var parseVersion = (version) => {
674
+ const match = SEMANTIC_VERSION_PATTERN.exec(version);
675
+ if (!match) return void 0;
676
+ const major = Number(match[1]);
677
+ const minor = Number(match[2]);
678
+ const patch = Number(match[3]);
679
+ if (![major, minor, patch].every(Number.isSafeInteger)) return void 0;
680
+ return { major, minor, patch };
681
+ };
682
+ var compareVersions = (a, b) => a.major !== b.major ? a.major - b.major : a.minor !== b.minor ? a.minor - b.minor : a.patch - b.patch;
683
+ var checkCompatibility = (client, server) => {
684
+ const order = compareVersions(client, server);
685
+ if (order > 0) return "server_outdated";
686
+ if (client.major !== server.major || client.minor !== server.minor) {
687
+ return "sdk_outdated";
688
+ }
689
+ return "compatible";
690
+ };
691
+
663
692
  // src/materialiserMetadata.ts
664
693
  var foldMaterialiserMetadata = (meta, cases) => {
665
694
  if (meta.kind === "exact") return cases.exact(meta.amount);
@@ -912,6 +941,8 @@ var ContinuationPlanZod = import_zod.default.object({
912
941
  AssertionSpecZod,
913
942
  BindValueSchema,
914
943
  Bytes32HexSchema,
944
+ COMPOSER_SDK_VERSION_HEADER,
945
+ COMPOSE_VERSION_HEADER,
915
946
  CONTINUATION_COMMITMENT_OP_ID,
916
947
  CallCheckSpecSchema,
917
948
  CallSchema,
@@ -963,6 +994,7 @@ var ContinuationPlanZod = import_zod.default.object({
963
994
  VerificationDescriptorZod,
964
995
  canonicalAssertedPredicate,
965
996
  canonicalNativeAddress,
997
+ checkCompatibility,
966
998
  copy,
967
999
  erc20,
968
1000
  erc20Allowance,
@@ -1004,6 +1036,7 @@ var ContinuationPlanZod = import_zod.default.object({
1004
1036
  normalizeResource,
1005
1037
  opHandle,
1006
1038
  parseRef,
1039
+ parseVersion,
1007
1040
  providerKindByName,
1008
1041
  providerKindNames,
1009
1042
  readResource,
package/dist/index.d.cts CHANGED
@@ -1919,6 +1919,10 @@ declare const isHandlePort: (port: OpInputPort | OpOutputPort) => port is Handle
1919
1919
  declare const isResourceOutputPort: (port: OpInputPort | OpOutputPort) => port is ResourceOutputPort;
1920
1920
  declare const isFutureResourceOutput: (port: OpInputPort | OpOutputPort) => boolean;
1921
1921
  type ComposeErrorKind = 'decode_error' | 'validation_error' | 'linearity_error' | 'resolve_error' | 'preparation_error' | 'provider_error' | 'no_route_error' | 'resolution_error' | 'resolution_rejected' | 'lowering_error' | 'empty_program' | 'simulation_error' | 'simulation_setup_error' | 'simulation_insufficient_funds' | 'simulation_gas_limit' | 'simulation_rpc_error' | 'simulation_revert' | 'subgraph_simulation_revert' | 'guard_error' | 'continuation_error' | 'compilation_error' | 'verification_error' | 'price_impact_exceeded' | 'fee_resolution_error' | 'fee_resolution_unavailable' | 'flashloan_unauthorized' | 'deadline_exceeded';
1922
+ /**
1923
+ * Errors raised by compose routes outside the compile pipeline.
1924
+ */
1925
+ type ComposeRouteErrorKind = 'chain_validation_error' | 'unsupported_token' | 'zero_output' | 'service_unavailable' | 'verification_unavailable' | 'deployment_check_unavailable' | 'manifest_error' | 'sdk_outdated' | 'server_outdated';
1922
1926
  type GenericComposeErrorKind = Exclude<ComposeErrorKind, 'preparation_error' | 'simulation_revert'>;
1923
1927
  interface FailedPreparedOp {
1924
1928
  readonly callId: string;
@@ -2495,6 +2499,58 @@ interface SimulateSetupErrorResult {
2495
2499
  */
2496
2500
  type SimulateResult = SimulateOkResult | SimulateRevertResult | SimulateSetupErrorResult;
2497
2501
 
2502
+ /**
2503
+ * HTTP header names on the compose wire.
2504
+ *
2505
+ * Both the SDK (which sends the request header) and the backend (which reads it
2506
+ * and answers with the response header) are part of the same handshake, so the
2507
+ * names belong to the wire format rather than to either side of it.
2508
+ */
2509
+ /** Compose contract version the client was built against. Sent on every request. */
2510
+ declare const COMPOSER_SDK_VERSION_HEADER = "x-lifi-composer-sdk";
2511
+ /** Compose contract version the backend serves. Returned on every compose response. */
2512
+ declare const COMPOSE_VERSION_HEADER = "x-lifi-composer-version";
2513
+
2514
+ /**
2515
+ * Compose contract version compatibility.
2516
+ *
2517
+ * The version triple carries the compatibility class, and the rule is
2518
+ * permanent: 1.0 does not change it. A patch bump is additive: new ops, edge
2519
+ * families, materialisers, guards, preconditions, or new optional config
2520
+ * fields. A minor or major bump is breaking: anything removed, any existing
2521
+ * schema changed, or a semantics change under an unchanged wire shape. Both
2522
+ * sides of the handshake (see `headers.ts`) decide with `checkCompatibility`,
2523
+ * so the rule lives in exactly one place.
2524
+ */
2525
+ interface ComposeVersion {
2526
+ readonly major: number;
2527
+ readonly minor: number;
2528
+ readonly patch: number;
2529
+ }
2530
+ type VersionCompatibility = 'compatible' | 'sdk_outdated' | 'server_outdated';
2531
+ /**
2532
+ * Parses the numeric triple of a semantic version. Prerelease and build
2533
+ * suffixes are accepted and ignored: `0.5.1-staging.3` compares as `0.5.1`.
2534
+ * Returns `undefined` for anything that is not a complete semver string,
2535
+ * including the `dev` sentinel the SDK sends when it runs unbundled.
2536
+ */
2537
+ declare const parseVersion: (version: string) => ComposeVersion | undefined;
2538
+ /**
2539
+ * Decides whether a client built against `client` may talk to a server that
2540
+ * serves `server`.
2541
+ *
2542
+ * - Same `major.minor` with the client at or behind the server's patch is
2543
+ * compatible: patch releases only add, so an older client never emits
2544
+ * anything the server lacks.
2545
+ * - A client below the server's `major.minor` is `sdk_outdated`: the server
2546
+ * made a breaking change the client does not know about.
2547
+ * - A client ahead in any component is `server_outdated`. Even a patch-ahead
2548
+ * client may send a field the server has never seen, and the guarantee must
2549
+ * not depend on every server schema staying strict. This is the rollout
2550
+ * window between an npm publish and the prod image bump.
2551
+ */
2552
+ declare const checkCompatibility: (client: ComposeVersion, server: ComposeVersion) => VersionCompatibility;
2553
+
2498
2554
  type MaterialiserMetadata = {
2499
2555
  readonly kind: 'exact';
2500
2556
  readonly amount: bigint;
@@ -2514,4 +2570,4 @@ declare const foldMaterialiserMetadata: <R>(meta: MaterialiserMetadata, cases: {
2514
2570
  readonly runtime: () => R;
2515
2571
  }) => R;
2516
2572
 
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 };
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 };
package/dist/index.d.ts CHANGED
@@ -1919,6 +1919,10 @@ declare const isHandlePort: (port: OpInputPort | OpOutputPort) => port is Handle
1919
1919
  declare const isResourceOutputPort: (port: OpInputPort | OpOutputPort) => port is ResourceOutputPort;
1920
1920
  declare const isFutureResourceOutput: (port: OpInputPort | OpOutputPort) => boolean;
1921
1921
  type ComposeErrorKind = 'decode_error' | 'validation_error' | 'linearity_error' | 'resolve_error' | 'preparation_error' | 'provider_error' | 'no_route_error' | 'resolution_error' | 'resolution_rejected' | 'lowering_error' | 'empty_program' | 'simulation_error' | 'simulation_setup_error' | 'simulation_insufficient_funds' | 'simulation_gas_limit' | 'simulation_rpc_error' | 'simulation_revert' | 'subgraph_simulation_revert' | 'guard_error' | 'continuation_error' | 'compilation_error' | 'verification_error' | 'price_impact_exceeded' | 'fee_resolution_error' | 'fee_resolution_unavailable' | 'flashloan_unauthorized' | 'deadline_exceeded';
1922
+ /**
1923
+ * Errors raised by compose routes outside the compile pipeline.
1924
+ */
1925
+ type ComposeRouteErrorKind = 'chain_validation_error' | 'unsupported_token' | 'zero_output' | 'service_unavailable' | 'verification_unavailable' | 'deployment_check_unavailable' | 'manifest_error' | 'sdk_outdated' | 'server_outdated';
1922
1926
  type GenericComposeErrorKind = Exclude<ComposeErrorKind, 'preparation_error' | 'simulation_revert'>;
1923
1927
  interface FailedPreparedOp {
1924
1928
  readonly callId: string;
@@ -2495,6 +2499,58 @@ interface SimulateSetupErrorResult {
2495
2499
  */
2496
2500
  type SimulateResult = SimulateOkResult | SimulateRevertResult | SimulateSetupErrorResult;
2497
2501
 
2502
+ /**
2503
+ * HTTP header names on the compose wire.
2504
+ *
2505
+ * Both the SDK (which sends the request header) and the backend (which reads it
2506
+ * and answers with the response header) are part of the same handshake, so the
2507
+ * names belong to the wire format rather than to either side of it.
2508
+ */
2509
+ /** Compose contract version the client was built against. Sent on every request. */
2510
+ declare const COMPOSER_SDK_VERSION_HEADER = "x-lifi-composer-sdk";
2511
+ /** Compose contract version the backend serves. Returned on every compose response. */
2512
+ declare const COMPOSE_VERSION_HEADER = "x-lifi-composer-version";
2513
+
2514
+ /**
2515
+ * Compose contract version compatibility.
2516
+ *
2517
+ * The version triple carries the compatibility class, and the rule is
2518
+ * permanent: 1.0 does not change it. A patch bump is additive: new ops, edge
2519
+ * families, materialisers, guards, preconditions, or new optional config
2520
+ * fields. A minor or major bump is breaking: anything removed, any existing
2521
+ * schema changed, or a semantics change under an unchanged wire shape. Both
2522
+ * sides of the handshake (see `headers.ts`) decide with `checkCompatibility`,
2523
+ * so the rule lives in exactly one place.
2524
+ */
2525
+ interface ComposeVersion {
2526
+ readonly major: number;
2527
+ readonly minor: number;
2528
+ readonly patch: number;
2529
+ }
2530
+ type VersionCompatibility = 'compatible' | 'sdk_outdated' | 'server_outdated';
2531
+ /**
2532
+ * Parses the numeric triple of a semantic version. Prerelease and build
2533
+ * suffixes are accepted and ignored: `0.5.1-staging.3` compares as `0.5.1`.
2534
+ * Returns `undefined` for anything that is not a complete semver string,
2535
+ * including the `dev` sentinel the SDK sends when it runs unbundled.
2536
+ */
2537
+ declare const parseVersion: (version: string) => ComposeVersion | undefined;
2538
+ /**
2539
+ * Decides whether a client built against `client` may talk to a server that
2540
+ * serves `server`.
2541
+ *
2542
+ * - Same `major.minor` with the client at or behind the server's patch is
2543
+ * compatible: patch releases only add, so an older client never emits
2544
+ * anything the server lacks.
2545
+ * - A client below the server's `major.minor` is `sdk_outdated`: the server
2546
+ * made a breaking change the client does not know about.
2547
+ * - A client ahead in any component is `server_outdated`. Even a patch-ahead
2548
+ * client may send a field the server has never seen, and the guarantee must
2549
+ * not depend on every server schema staying strict. This is the rollout
2550
+ * window between an npm publish and the prod image bump.
2551
+ */
2552
+ declare const checkCompatibility: (client: ComposeVersion, server: ComposeVersion) => VersionCompatibility;
2553
+
2498
2554
  type MaterialiserMetadata = {
2499
2555
  readonly kind: 'exact';
2500
2556
  readonly amount: bigint;
@@ -2514,4 +2570,4 @@ declare const foldMaterialiserMetadata: <R>(meta: MaterialiserMetadata, cases: {
2514
2570
  readonly runtime: () => R;
2515
2571
  }) => R;
2516
2572
 
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 };
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 };
package/dist/index.js CHANGED
@@ -513,6 +513,31 @@ var isNativeBalancePrecondition = (p) => p.type === "NativeBalance";
513
513
  var SIMULATE_MAX_TRACKED_BALANCES = 40;
514
514
  var SIMULATE_MAX_REQUIREMENTS = 40;
515
515
 
516
+ // src/headers.ts
517
+ var COMPOSER_SDK_VERSION_HEADER = "x-lifi-composer-sdk";
518
+ var COMPOSE_VERSION_HEADER = "x-lifi-composer-version";
519
+
520
+ // src/version.ts
521
+ var SEMANTIC_VERSION_PATTERN = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*)(?:\.(?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*))*))?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
522
+ var parseVersion = (version) => {
523
+ const match = SEMANTIC_VERSION_PATTERN.exec(version);
524
+ if (!match) return void 0;
525
+ const major = Number(match[1]);
526
+ const minor = Number(match[2]);
527
+ const patch = Number(match[3]);
528
+ if (![major, minor, patch].every(Number.isSafeInteger)) return void 0;
529
+ return { major, minor, patch };
530
+ };
531
+ 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
+ }
538
+ return "compatible";
539
+ };
540
+
516
541
  // src/materialiserMetadata.ts
517
542
  var foldMaterialiserMetadata = (meta, cases) => {
518
543
  if (meta.kind === "exact") return cases.exact(meta.amount);
@@ -764,6 +789,8 @@ export {
764
789
  AssertionSpecZod,
765
790
  BindValueSchema,
766
791
  Bytes32HexSchema,
792
+ COMPOSER_SDK_VERSION_HEADER,
793
+ COMPOSE_VERSION_HEADER,
767
794
  CONTINUATION_COMMITMENT_OP_ID,
768
795
  CallCheckSpecSchema,
769
796
  CallSchema,
@@ -815,6 +842,7 @@ export {
815
842
  VerificationDescriptorZod,
816
843
  canonicalAssertedPredicate,
817
844
  canonicalNativeAddress,
845
+ checkCompatibility,
818
846
  copy,
819
847
  erc20,
820
848
  erc20Allowance,
@@ -856,6 +884,7 @@ export {
856
884
  normalizeResource,
857
885
  opHandle,
858
886
  parseRef,
887
+ parseVersion,
859
888
  providerKindByName,
860
889
  providerKindNames,
861
890
  readResource,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@lifi/compose-spec",
3
- "version": "0.5.0",
3
+ "version": "0.5.1",
4
4
  "description": "Public wire-format types and schemas for Compose flows",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {
package/src/flow.ts CHANGED
@@ -87,6 +87,20 @@ export type ComposeErrorKind =
87
87
  // The request exceeded its wall-clock budget and was cancelled mid-flight.
88
88
  | 'deadline_exceeded';
89
89
 
90
+ /**
91
+ * Errors raised by compose routes outside the compile pipeline.
92
+ */
93
+ export type ComposeRouteErrorKind =
94
+ | 'chain_validation_error'
95
+ | 'unsupported_token'
96
+ | 'zero_output'
97
+ | 'service_unavailable'
98
+ | 'verification_unavailable'
99
+ | 'deployment_check_unavailable'
100
+ | 'manifest_error'
101
+ | 'sdk_outdated'
102
+ | 'server_outdated';
103
+
90
104
  export type GenericComposeErrorKind = Exclude<
91
105
  ComposeErrorKind,
92
106
  'preparation_error' | 'simulation_revert'
package/src/headers.ts ADDED
@@ -0,0 +1,13 @@
1
+ /**
2
+ * HTTP header names on the compose wire.
3
+ *
4
+ * Both the SDK (which sends the request header) and the backend (which reads it
5
+ * and answers with the response header) are part of the same handshake, so the
6
+ * names belong to the wire format rather than to either side of it.
7
+ */
8
+
9
+ /** Compose contract version the client was built against. Sent on every request. */
10
+ export const COMPOSER_SDK_VERSION_HEADER = 'x-lifi-composer-sdk';
11
+
12
+ /** Compose contract version the backend serves. Returned on every compose response. */
13
+ export const COMPOSE_VERSION_HEADER = 'x-lifi-composer-version';
package/src/index.ts CHANGED
@@ -76,6 +76,7 @@ export type {
76
76
  OpOutputPort,
77
77
  ComposeError,
78
78
  ComposeErrorKind,
79
+ ComposeRouteErrorKind,
79
80
  GenericComposeErrorKind,
80
81
  PreparationComposeError,
81
82
  SimulationRevertComposeError,
@@ -241,6 +242,12 @@ export {
241
242
  SIMULATE_MAX_TRACKED_BALANCES,
242
243
  SIMULATE_MAX_REQUIREMENTS,
243
244
  } from './simulate.js';
245
+ export {
246
+ COMPOSER_SDK_VERSION_HEADER,
247
+ COMPOSE_VERSION_HEADER,
248
+ } from './headers.js';
249
+ export type { ComposeVersion, VersionCompatibility } from './version.js';
250
+ export { checkCompatibility, parseVersion } from './version.js';
244
251
 
245
252
  export type {
246
253
  MaterialiserMetadata,
package/src/version.ts ADDED
@@ -0,0 +1,74 @@
1
+ /**
2
+ * Compose contract version compatibility.
3
+ *
4
+ * The version triple carries the compatibility class, and the rule is
5
+ * permanent: 1.0 does not change it. A patch bump is additive: new ops, edge
6
+ * families, materialisers, guards, preconditions, or new optional config
7
+ * fields. A minor or major bump is breaking: anything removed, any existing
8
+ * schema changed, or a semantics change under an unchanged wire shape. Both
9
+ * sides of the handshake (see `headers.ts`) decide with `checkCompatibility`,
10
+ * so the rule lives in exactly one place.
11
+ */
12
+
13
+ export interface ComposeVersion {
14
+ readonly major: number;
15
+ readonly minor: number;
16
+ readonly patch: number;
17
+ }
18
+
19
+ export type VersionCompatibility =
20
+ 'compatible' | 'sdk_outdated' | 'server_outdated';
21
+
22
+ const SEMANTIC_VERSION_PATTERN =
23
+ /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*)(?:\.(?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*))*))?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
24
+
25
+ /**
26
+ * Parses the numeric triple of a semantic version. Prerelease and build
27
+ * suffixes are accepted and ignored: `0.5.1-staging.3` compares as `0.5.1`.
28
+ * Returns `undefined` for anything that is not a complete semver string,
29
+ * including the `dev` sentinel the SDK sends when it runs unbundled.
30
+ */
31
+ export const parseVersion = (version: string): ComposeVersion | undefined => {
32
+ const match = SEMANTIC_VERSION_PATTERN.exec(version);
33
+ if (!match) return undefined;
34
+
35
+ const major = Number(match[1]);
36
+ const minor = Number(match[2]);
37
+ const patch = Number(match[3]);
38
+ if (![major, minor, patch].every(Number.isSafeInteger)) return undefined;
39
+
40
+ return { major, minor, patch };
41
+ };
42
+
43
+ const compareVersions = (a: ComposeVersion, b: ComposeVersion): number =>
44
+ a.major !== b.major
45
+ ? a.major - b.major
46
+ : a.minor !== b.minor
47
+ ? a.minor - b.minor
48
+ : a.patch - b.patch;
49
+
50
+ /**
51
+ * Decides whether a client built against `client` may talk to a server that
52
+ * serves `server`.
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.
63
+ */
64
+ export const checkCompatibility = (
65
+ client: ComposeVersion,
66
+ server: ComposeVersion,
67
+ ): 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
+ }
73
+ return 'compatible';
74
+ };