@lifi/compose-spec 0.5.0 → 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 +2 -1
- package/dist/index.cjs +39 -2
- package/dist/index.d.cts +105 -15
- package/dist/index.d.ts +105 -15
- package/dist/index.js +33 -1
- package/package.json +1 -1
- package/src/compile.ts +9 -3
- package/src/continuation.ts +10 -0
- package/src/flow.ts +14 -0
- package/src/headers.ts +13 -0
- package/src/index.ts +22 -7
- package/src/output.ts +67 -0
- package/src/resource.ts +0 -16
- package/src/route.ts +2 -2
- package/src/version.ts +82 -0
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`,
|
|
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
|
@@ -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,
|
|
@@ -141,7 +145,8 @@ __export(index_exports, {
|
|
|
141
145
|
resourceKey: () => resourceKey,
|
|
142
146
|
resourceOutput: () => resourceOutput,
|
|
143
147
|
resourceToken: () => resourceToken,
|
|
144
|
-
resourcesEqual: () => resourcesEqual
|
|
148
|
+
resourcesEqual: () => resourcesEqual,
|
|
149
|
+
settledOutcome: () => settledOutcome
|
|
145
150
|
});
|
|
146
151
|
module.exports = __toCommonJS(index_exports);
|
|
147
152
|
|
|
@@ -406,6 +411,7 @@ var ContinuationPlanSchema = import_effect2.Schema.Struct({
|
|
|
406
411
|
validity: import_effect2.Schema.Struct({ expiresAtMs: import_effect2.Schema.Number }),
|
|
407
412
|
correlationId: import_effect2.Schema.optional(import_effect2.Schema.String)
|
|
408
413
|
});
|
|
414
|
+
var settledOutcome = (intent) => intent.outcomes[0];
|
|
409
415
|
var isGTECheck = (check) => check.kind === "call" && check.comparator === "gte";
|
|
410
416
|
var isLTECheck = (check) => check.kind === "call" && check.comparator === "lte";
|
|
411
417
|
var isEQCheck = (check) => check.kind === "call" && check.comparator === "eq";
|
|
@@ -660,6 +666,32 @@ var isNativeBalancePrecondition = (p) => p.type === "NativeBalance";
|
|
|
660
666
|
var SIMULATE_MAX_TRACKED_BALANCES = 40;
|
|
661
667
|
var SIMULATE_MAX_REQUIREMENTS = 40;
|
|
662
668
|
|
|
669
|
+
// src/headers.ts
|
|
670
|
+
var COMPOSER_SDK_VERSION_HEADER = "x-lifi-composer-sdk";
|
|
671
|
+
var COMPOSE_VERSION_HEADER = "x-lifi-composer-version";
|
|
672
|
+
|
|
673
|
+
// src/version.ts
|
|
674
|
+
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-]+)*)?$/;
|
|
675
|
+
var parseVersion = (version) => {
|
|
676
|
+
const match = SEMANTIC_VERSION_PATTERN.exec(version);
|
|
677
|
+
if (!match) return void 0;
|
|
678
|
+
const major = Number(match[1]);
|
|
679
|
+
const minor = Number(match[2]);
|
|
680
|
+
const patch = Number(match[3]);
|
|
681
|
+
if (![major, minor, patch].every(Number.isSafeInteger)) return void 0;
|
|
682
|
+
return { major, minor, patch };
|
|
683
|
+
};
|
|
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;
|
|
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";
|
|
692
|
+
return "compatible";
|
|
693
|
+
};
|
|
694
|
+
|
|
663
695
|
// src/materialiserMetadata.ts
|
|
664
696
|
var foldMaterialiserMetadata = (meta, cases) => {
|
|
665
697
|
if (meta.kind === "exact") return cases.exact(meta.amount);
|
|
@@ -912,6 +944,8 @@ var ContinuationPlanZod = import_zod.default.object({
|
|
|
912
944
|
AssertionSpecZod,
|
|
913
945
|
BindValueSchema,
|
|
914
946
|
Bytes32HexSchema,
|
|
947
|
+
COMPOSER_SDK_VERSION_HEADER,
|
|
948
|
+
COMPOSE_VERSION_HEADER,
|
|
915
949
|
CONTINUATION_COMMITMENT_OP_ID,
|
|
916
950
|
CallCheckSpecSchema,
|
|
917
951
|
CallSchema,
|
|
@@ -963,6 +997,7 @@ var ContinuationPlanZod = import_zod.default.object({
|
|
|
963
997
|
VerificationDescriptorZod,
|
|
964
998
|
canonicalAssertedPredicate,
|
|
965
999
|
canonicalNativeAddress,
|
|
1000
|
+
checkCompatibility,
|
|
966
1001
|
copy,
|
|
967
1002
|
erc20,
|
|
968
1003
|
erc20Allowance,
|
|
@@ -1004,6 +1039,7 @@ var ContinuationPlanZod = import_zod.default.object({
|
|
|
1004
1039
|
normalizeResource,
|
|
1005
1040
|
opHandle,
|
|
1006
1041
|
parseRef,
|
|
1042
|
+
parseVersion,
|
|
1007
1043
|
providerKindByName,
|
|
1008
1044
|
providerKindNames,
|
|
1009
1045
|
readResource,
|
|
@@ -1013,5 +1049,6 @@ var ContinuationPlanZod = import_zod.default.object({
|
|
|
1013
1049
|
resourceKey,
|
|
1014
1050
|
resourceOutput,
|
|
1015
1051
|
resourceToken,
|
|
1016
|
-
resourcesEqual
|
|
1052
|
+
resourcesEqual,
|
|
1053
|
+
settledOutcome
|
|
1017
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
|
|
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
|
|
1915
|
+
readonly outputs: Outputs;
|
|
1888
1916
|
readonly transactionRequest: ComposeTransactionRequest;
|
|
1889
1917
|
readonly userProxy: string;
|
|
1890
1918
|
readonly simulationRevert: SimulationRevert;
|
|
@@ -1919,6 +1947,10 @@ declare const isHandlePort: (port: OpInputPort | OpOutputPort) => port is Handle
|
|
|
1919
1947
|
declare const isResourceOutputPort: (port: OpInputPort | OpOutputPort) => port is ResourceOutputPort;
|
|
1920
1948
|
declare const isFutureResourceOutput: (port: OpInputPort | OpOutputPort) => boolean;
|
|
1921
1949
|
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';
|
|
1950
|
+
/**
|
|
1951
|
+
* Errors raised by compose routes outside the compile pipeline.
|
|
1952
|
+
*/
|
|
1953
|
+
type ComposeRouteErrorKind = 'chain_validation_error' | 'unsupported_token' | 'zero_output' | 'service_unavailable' | 'verification_unavailable' | 'deployment_check_unavailable' | 'manifest_error' | 'sdk_outdated' | 'server_outdated';
|
|
1922
1954
|
type GenericComposeErrorKind = Exclude<ComposeErrorKind, 'preparation_error' | 'simulation_revert'>;
|
|
1923
1955
|
interface FailedPreparedOp {
|
|
1924
1956
|
readonly callId: string;
|
|
@@ -2304,12 +2336,12 @@ interface ComposeRouteRequest {
|
|
|
2304
2336
|
readonly checkOnChainAllowances?: boolean;
|
|
2305
2337
|
/**
|
|
2306
2338
|
* Accept a route whose output is delivered only after the initiating
|
|
2307
|
-
* transaction settles (`
|
|
2339
|
+
* transaction settles (`delivery.when: 'future'` on the terminal output).
|
|
2308
2340
|
* Such a route obliges you to track settlement rather than treat the
|
|
2309
2341
|
* transaction as completing the job, and carries no slippage floor, so it is
|
|
2310
2342
|
* opt-in. Defaults to `false` server-side, which leaves a pair reachable
|
|
2311
2343
|
* only asynchronously rejected with `no_route_error` and guarantees every
|
|
2312
|
-
*
|
|
2344
|
+
* terminal output is `delivery.when: 'now'`.
|
|
2313
2345
|
*/
|
|
2314
2346
|
readonly allowAsyncRoutes?: boolean;
|
|
2315
2347
|
}
|
|
@@ -2495,6 +2527,64 @@ interface SimulateSetupErrorResult {
|
|
|
2495
2527
|
*/
|
|
2496
2528
|
type SimulateResult = SimulateOkResult | SimulateRevertResult | SimulateSetupErrorResult;
|
|
2497
2529
|
|
|
2530
|
+
/**
|
|
2531
|
+
* HTTP header names on the compose wire.
|
|
2532
|
+
*
|
|
2533
|
+
* Both the SDK (which sends the request header) and the backend (which reads it
|
|
2534
|
+
* and answers with the response header) are part of the same handshake, so the
|
|
2535
|
+
* names belong to the wire format rather than to either side of it.
|
|
2536
|
+
*/
|
|
2537
|
+
/** Compose contract version the client was built against. Sent on every request. */
|
|
2538
|
+
declare const COMPOSER_SDK_VERSION_HEADER = "x-lifi-composer-sdk";
|
|
2539
|
+
/** Compose contract version the backend serves. Returned on every compose response. */
|
|
2540
|
+
declare const COMPOSE_VERSION_HEADER = "x-lifi-composer-version";
|
|
2541
|
+
|
|
2542
|
+
/**
|
|
2543
|
+
* Compose contract version compatibility.
|
|
2544
|
+
*
|
|
2545
|
+
* The version triple carries the compatibility class, and the rule is
|
|
2546
|
+
* permanent: 1.0 does not change it. A patch bump is additive: new ops, edge
|
|
2547
|
+
* families, materialisers, guards, preconditions, or new optional config
|
|
2548
|
+
* fields. A minor or major bump is breaking: anything removed, any existing
|
|
2549
|
+
* schema changed, or a semantics change under an unchanged wire shape. Both
|
|
2550
|
+
* sides of the handshake (see `headers.ts`) decide with `checkCompatibility`,
|
|
2551
|
+
* so the rule lives in exactly one place.
|
|
2552
|
+
*/
|
|
2553
|
+
interface ComposeVersion {
|
|
2554
|
+
readonly major: number;
|
|
2555
|
+
readonly minor: number;
|
|
2556
|
+
readonly patch: number;
|
|
2557
|
+
}
|
|
2558
|
+
type VersionCompatibility = 'compatible' | 'sdk_outdated' | 'server_outdated';
|
|
2559
|
+
/**
|
|
2560
|
+
* Parses the numeric triple of a semantic version. Prerelease and build
|
|
2561
|
+
* suffixes are accepted and ignored: `0.5.1-staging.3` compares as `0.5.1`.
|
|
2562
|
+
* Returns `undefined` for anything that is not a complete semver string,
|
|
2563
|
+
* including the `dev` sentinel the SDK sends when it runs unbundled.
|
|
2564
|
+
*/
|
|
2565
|
+
declare const parseVersion: (version: string) => ComposeVersion | undefined;
|
|
2566
|
+
/**
|
|
2567
|
+
* Decides whether a client built against `client` may talk to a server that
|
|
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.
|
|
2580
|
+
*
|
|
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.
|
|
2585
|
+
*/
|
|
2586
|
+
declare const checkCompatibility: (client: ComposeVersion, server: ComposeVersion, minimum?: ComposeVersion) => VersionCompatibility;
|
|
2587
|
+
|
|
2498
2588
|
type MaterialiserMetadata = {
|
|
2499
2589
|
readonly kind: 'exact';
|
|
2500
2590
|
readonly amount: bigint;
|
|
@@ -2514,4 +2604,4 @@ declare const foldMaterialiserMetadata: <R>(meta: MaterialiserMetadata, cases: {
|
|
|
2514
2604
|
readonly runtime: () => R;
|
|
2515
2605
|
}) => R;
|
|
2516
2606
|
|
|
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
|
|
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
|
|
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
|
|
1915
|
+
readonly outputs: Outputs;
|
|
1888
1916
|
readonly transactionRequest: ComposeTransactionRequest;
|
|
1889
1917
|
readonly userProxy: string;
|
|
1890
1918
|
readonly simulationRevert: SimulationRevert;
|
|
@@ -1919,6 +1947,10 @@ declare const isHandlePort: (port: OpInputPort | OpOutputPort) => port is Handle
|
|
|
1919
1947
|
declare const isResourceOutputPort: (port: OpInputPort | OpOutputPort) => port is ResourceOutputPort;
|
|
1920
1948
|
declare const isFutureResourceOutput: (port: OpInputPort | OpOutputPort) => boolean;
|
|
1921
1949
|
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';
|
|
1950
|
+
/**
|
|
1951
|
+
* Errors raised by compose routes outside the compile pipeline.
|
|
1952
|
+
*/
|
|
1953
|
+
type ComposeRouteErrorKind = 'chain_validation_error' | 'unsupported_token' | 'zero_output' | 'service_unavailable' | 'verification_unavailable' | 'deployment_check_unavailable' | 'manifest_error' | 'sdk_outdated' | 'server_outdated';
|
|
1922
1954
|
type GenericComposeErrorKind = Exclude<ComposeErrorKind, 'preparation_error' | 'simulation_revert'>;
|
|
1923
1955
|
interface FailedPreparedOp {
|
|
1924
1956
|
readonly callId: string;
|
|
@@ -2304,12 +2336,12 @@ interface ComposeRouteRequest {
|
|
|
2304
2336
|
readonly checkOnChainAllowances?: boolean;
|
|
2305
2337
|
/**
|
|
2306
2338
|
* Accept a route whose output is delivered only after the initiating
|
|
2307
|
-
* transaction settles (`
|
|
2339
|
+
* transaction settles (`delivery.when: 'future'` on the terminal output).
|
|
2308
2340
|
* Such a route obliges you to track settlement rather than treat the
|
|
2309
2341
|
* transaction as completing the job, and carries no slippage floor, so it is
|
|
2310
2342
|
* opt-in. Defaults to `false` server-side, which leaves a pair reachable
|
|
2311
2343
|
* only asynchronously rejected with `no_route_error` and guarantees every
|
|
2312
|
-
*
|
|
2344
|
+
* terminal output is `delivery.when: 'now'`.
|
|
2313
2345
|
*/
|
|
2314
2346
|
readonly allowAsyncRoutes?: boolean;
|
|
2315
2347
|
}
|
|
@@ -2495,6 +2527,64 @@ interface SimulateSetupErrorResult {
|
|
|
2495
2527
|
*/
|
|
2496
2528
|
type SimulateResult = SimulateOkResult | SimulateRevertResult | SimulateSetupErrorResult;
|
|
2497
2529
|
|
|
2530
|
+
/**
|
|
2531
|
+
* HTTP header names on the compose wire.
|
|
2532
|
+
*
|
|
2533
|
+
* Both the SDK (which sends the request header) and the backend (which reads it
|
|
2534
|
+
* and answers with the response header) are part of the same handshake, so the
|
|
2535
|
+
* names belong to the wire format rather than to either side of it.
|
|
2536
|
+
*/
|
|
2537
|
+
/** Compose contract version the client was built against. Sent on every request. */
|
|
2538
|
+
declare const COMPOSER_SDK_VERSION_HEADER = "x-lifi-composer-sdk";
|
|
2539
|
+
/** Compose contract version the backend serves. Returned on every compose response. */
|
|
2540
|
+
declare const COMPOSE_VERSION_HEADER = "x-lifi-composer-version";
|
|
2541
|
+
|
|
2542
|
+
/**
|
|
2543
|
+
* Compose contract version compatibility.
|
|
2544
|
+
*
|
|
2545
|
+
* The version triple carries the compatibility class, and the rule is
|
|
2546
|
+
* permanent: 1.0 does not change it. A patch bump is additive: new ops, edge
|
|
2547
|
+
* families, materialisers, guards, preconditions, or new optional config
|
|
2548
|
+
* fields. A minor or major bump is breaking: anything removed, any existing
|
|
2549
|
+
* schema changed, or a semantics change under an unchanged wire shape. Both
|
|
2550
|
+
* sides of the handshake (see `headers.ts`) decide with `checkCompatibility`,
|
|
2551
|
+
* so the rule lives in exactly one place.
|
|
2552
|
+
*/
|
|
2553
|
+
interface ComposeVersion {
|
|
2554
|
+
readonly major: number;
|
|
2555
|
+
readonly minor: number;
|
|
2556
|
+
readonly patch: number;
|
|
2557
|
+
}
|
|
2558
|
+
type VersionCompatibility = 'compatible' | 'sdk_outdated' | 'server_outdated';
|
|
2559
|
+
/**
|
|
2560
|
+
* Parses the numeric triple of a semantic version. Prerelease and build
|
|
2561
|
+
* suffixes are accepted and ignored: `0.5.1-staging.3` compares as `0.5.1`.
|
|
2562
|
+
* Returns `undefined` for anything that is not a complete semver string,
|
|
2563
|
+
* including the `dev` sentinel the SDK sends when it runs unbundled.
|
|
2564
|
+
*/
|
|
2565
|
+
declare const parseVersion: (version: string) => ComposeVersion | undefined;
|
|
2566
|
+
/**
|
|
2567
|
+
* Decides whether a client built against `client` may talk to a server that
|
|
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.
|
|
2580
|
+
*
|
|
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.
|
|
2585
|
+
*/
|
|
2586
|
+
declare const checkCompatibility: (client: ComposeVersion, server: ComposeVersion, minimum?: ComposeVersion) => VersionCompatibility;
|
|
2587
|
+
|
|
2498
2588
|
type MaterialiserMetadata = {
|
|
2499
2589
|
readonly kind: 'exact';
|
|
2500
2590
|
readonly amount: bigint;
|
|
@@ -2514,4 +2604,4 @@ declare const foldMaterialiserMetadata: <R>(meta: MaterialiserMetadata, cases: {
|
|
|
2514
2604
|
readonly runtime: () => R;
|
|
2515
2605
|
}) => R;
|
|
2516
2606
|
|
|
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
|
|
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";
|
|
@@ -513,6 +514,32 @@ var isNativeBalancePrecondition = (p) => p.type === "NativeBalance";
|
|
|
513
514
|
var SIMULATE_MAX_TRACKED_BALANCES = 40;
|
|
514
515
|
var SIMULATE_MAX_REQUIREMENTS = 40;
|
|
515
516
|
|
|
517
|
+
// src/headers.ts
|
|
518
|
+
var COMPOSER_SDK_VERSION_HEADER = "x-lifi-composer-sdk";
|
|
519
|
+
var COMPOSE_VERSION_HEADER = "x-lifi-composer-version";
|
|
520
|
+
|
|
521
|
+
// src/version.ts
|
|
522
|
+
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-]+)*)?$/;
|
|
523
|
+
var parseVersion = (version) => {
|
|
524
|
+
const match = SEMANTIC_VERSION_PATTERN.exec(version);
|
|
525
|
+
if (!match) return void 0;
|
|
526
|
+
const major = Number(match[1]);
|
|
527
|
+
const minor = Number(match[2]);
|
|
528
|
+
const patch = Number(match[3]);
|
|
529
|
+
if (![major, minor, patch].every(Number.isSafeInteger)) return void 0;
|
|
530
|
+
return { major, minor, patch };
|
|
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;
|
|
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";
|
|
540
|
+
return "compatible";
|
|
541
|
+
};
|
|
542
|
+
|
|
516
543
|
// src/materialiserMetadata.ts
|
|
517
544
|
var foldMaterialiserMetadata = (meta, cases) => {
|
|
518
545
|
if (meta.kind === "exact") return cases.exact(meta.amount);
|
|
@@ -764,6 +791,8 @@ export {
|
|
|
764
791
|
AssertionSpecZod,
|
|
765
792
|
BindValueSchema,
|
|
766
793
|
Bytes32HexSchema,
|
|
794
|
+
COMPOSER_SDK_VERSION_HEADER,
|
|
795
|
+
COMPOSE_VERSION_HEADER,
|
|
767
796
|
CONTINUATION_COMMITMENT_OP_ID,
|
|
768
797
|
CallCheckSpecSchema,
|
|
769
798
|
CallSchema,
|
|
@@ -815,6 +844,7 @@ export {
|
|
|
815
844
|
VerificationDescriptorZod,
|
|
816
845
|
canonicalAssertedPredicate,
|
|
817
846
|
canonicalNativeAddress,
|
|
847
|
+
checkCompatibility,
|
|
818
848
|
copy,
|
|
819
849
|
erc20,
|
|
820
850
|
erc20Allowance,
|
|
@@ -856,6 +886,7 @@ export {
|
|
|
856
886
|
normalizeResource,
|
|
857
887
|
opHandle,
|
|
858
888
|
parseRef,
|
|
889
|
+
parseVersion,
|
|
859
890
|
providerKindByName,
|
|
860
891
|
providerKindNames,
|
|
861
892
|
readResource,
|
|
@@ -865,5 +896,6 @@ export {
|
|
|
865
896
|
resourceKey,
|
|
866
897
|
resourceOutput,
|
|
867
898
|
resourceToken,
|
|
868
|
-
resourcesEqual
|
|
899
|
+
resourcesEqual,
|
|
900
|
+
settledOutcome
|
|
869
901
|
};
|
package/package.json
CHANGED
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 {
|
|
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
|
-
|
|
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
|
-
|
|
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;
|
package/src/continuation.ts
CHANGED
|
@@ -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/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
|
@@ -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 {
|
|
@@ -76,6 +77,7 @@ export type {
|
|
|
76
77
|
OpOutputPort,
|
|
77
78
|
ComposeError,
|
|
78
79
|
ComposeErrorKind,
|
|
80
|
+
ComposeRouteErrorKind,
|
|
79
81
|
GenericComposeErrorKind,
|
|
80
82
|
PreparationComposeError,
|
|
81
83
|
SimulationRevertComposeError,
|
|
@@ -103,13 +105,7 @@ export {
|
|
|
103
105
|
isMaterialiserInput,
|
|
104
106
|
} from './flow.js';
|
|
105
107
|
|
|
106
|
-
export type {
|
|
107
|
-
Availability,
|
|
108
|
-
OutputAmount,
|
|
109
|
-
Resource,
|
|
110
|
-
ProducedResource,
|
|
111
|
-
SimulatedAmounts,
|
|
112
|
-
} from './resource.js';
|
|
108
|
+
export type { Availability, OutputAmount, Resource } from './resource.js';
|
|
113
109
|
export {
|
|
114
110
|
erc20Resource,
|
|
115
111
|
erc20Token,
|
|
@@ -122,6 +118,19 @@ export {
|
|
|
122
118
|
resourcesEqual,
|
|
123
119
|
} from './resource.js';
|
|
124
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
|
+
|
|
125
134
|
export type {
|
|
126
135
|
ProviderKindName,
|
|
127
136
|
FlashloanMaterialiserInput,
|
|
@@ -241,6 +250,12 @@ export {
|
|
|
241
250
|
SIMULATE_MAX_TRACKED_BALANCES,
|
|
242
251
|
SIMULATE_MAX_REQUIREMENTS,
|
|
243
252
|
} from './simulate.js';
|
|
253
|
+
export {
|
|
254
|
+
COMPOSER_SDK_VERSION_HEADER,
|
|
255
|
+
COMPOSE_VERSION_HEADER,
|
|
256
|
+
} from './headers.js';
|
|
257
|
+
export type { ComposeVersion, VersionCompatibility } from './version.js';
|
|
258
|
+
export { checkCompatibility, parseVersion } from './version.js';
|
|
244
259
|
|
|
245
260
|
export type {
|
|
246
261
|
MaterialiserMetadata,
|
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 (`
|
|
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
|
-
*
|
|
136
|
+
* terminal output is `delivery.when: 'now'`.
|
|
137
137
|
*/
|
|
138
138
|
readonly allowAsyncRoutes?: boolean;
|
|
139
139
|
}
|
package/src/version.ts
ADDED
|
@@ -0,0 +1,82 @@
|
|
|
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` and accepts clients down to `minimum`.
|
|
53
|
+
*
|
|
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.
|
|
69
|
+
*/
|
|
70
|
+
export const checkCompatibility = (
|
|
71
|
+
client: ComposeVersion,
|
|
72
|
+
server: ComposeVersion,
|
|
73
|
+
minimum: ComposeVersion = {
|
|
74
|
+
major: server.major,
|
|
75
|
+
minor: server.minor,
|
|
76
|
+
patch: 0,
|
|
77
|
+
},
|
|
78
|
+
): VersionCompatibility => {
|
|
79
|
+
if (compareVersions(client, server) > 0) return 'server_outdated';
|
|
80
|
+
if (compareVersions(client, minimum) < 0) return 'sdk_outdated';
|
|
81
|
+
return 'compatible';
|
|
82
|
+
};
|