@lifi/compose-spec 0.4.1 → 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/README.md +1 -1
- package/dist/index.cjs +70 -33
- package/dist/index.d.cts +144 -45
- package/dist/index.d.ts +144 -45
- package/dist/index.js +65 -30
- package/package.json +3 -10
- package/src/compile.ts +87 -21
- package/src/constructors.ts +1 -7
- package/src/continuation.ts +9 -9
- package/src/flow.ts +14 -0
- package/src/flowSchema.ts +0 -7
- package/src/headers.ts +13 -0
- package/src/index.ts +19 -6
- package/src/ref.ts +33 -0
- package/src/resource.ts +5 -0
- package/src/route.ts +22 -10
- package/src/version.ts +74 -0
- package/src/zodSchemas.ts +4 -13
package/src/compile.ts
CHANGED
|
@@ -23,6 +23,12 @@ export interface ComposeRun {
|
|
|
23
23
|
readonly maxPriceImpactBps?: number;
|
|
24
24
|
readonly sweepTo?: SweepTo;
|
|
25
25
|
readonly simulationPolicy?: SimulationPolicy;
|
|
26
|
+
/**
|
|
27
|
+
* Also simulate the final user-facing transaction. Defaults to `false`;
|
|
28
|
+
* reverts honour `simulationPolicy` and a success is echoed back as
|
|
29
|
+
* `userProgramSimulation`.
|
|
30
|
+
*/
|
|
31
|
+
readonly simulateUserProgram?: boolean;
|
|
26
32
|
readonly checkOnChainAllowances?: boolean;
|
|
27
33
|
}
|
|
28
34
|
|
|
@@ -64,17 +70,20 @@ export interface SimulationRevert {
|
|
|
64
70
|
|
|
65
71
|
export interface ComposeTransactionRequest {
|
|
66
72
|
readonly to: string;
|
|
73
|
+
readonly chainId: number;
|
|
67
74
|
readonly data: string;
|
|
68
75
|
readonly value: string;
|
|
69
76
|
readonly gasLimit?: string;
|
|
70
77
|
}
|
|
71
78
|
|
|
72
|
-
//
|
|
73
|
-
//
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
readonly
|
|
77
|
-
readonly
|
|
79
|
+
// Hand-mirrored from `ComposeActionSchema`, the OpenAPI source of truth in
|
|
80
|
+
// `@lifi/api-schemas`.
|
|
81
|
+
export interface ComposeAction {
|
|
82
|
+
readonly kind: 'transaction';
|
|
83
|
+
readonly purpose: 'approval' | 'execute' | 'fundEscrow';
|
|
84
|
+
readonly submitter: 'signer' | 'anyone';
|
|
85
|
+
readonly transactionRequest: ComposeTransactionRequest;
|
|
86
|
+
readonly nodeId?: string;
|
|
78
87
|
}
|
|
79
88
|
|
|
80
89
|
// Continuation fields shared by the success and partial-error responses, so the
|
|
@@ -82,8 +91,6 @@ export interface ComposeContinuation {
|
|
|
82
91
|
// Zod-inferred wire types from `zodSchemas.ts`, pinning these SDK-facing types
|
|
83
92
|
// to the server contract rather than hand-transcribing them.
|
|
84
93
|
interface ComposeContinuationData {
|
|
85
|
-
// One pointer per `continuation.settle` branch (a flow can fork into several).
|
|
86
|
-
readonly continuations?: readonly ComposeContinuation[];
|
|
87
94
|
// Phase-1 action to sign/fund now, keyed by settle node. Absent for an atomic flow.
|
|
88
95
|
readonly phase1ByNode?: Record<string, Phase1ArtifactWire>;
|
|
89
96
|
// Self-serve second leg to re-submit later, keyed by settle node. Present only
|
|
@@ -91,29 +98,81 @@ interface ComposeContinuationData {
|
|
|
91
98
|
readonly continuationPlans?: Record<string, ContinuationPlanWire>;
|
|
92
99
|
}
|
|
93
100
|
|
|
94
|
-
// One funding leg the compiled fill consumes: the resource input's
|
|
95
|
-
// (native → zero address) and
|
|
96
|
-
// string (verified continuations, plan GD-8, seam C5).
|
|
101
|
+
// One funding leg the compiled fill consumes: the resource input's name, its
|
|
102
|
+
// token (native → zero address) and chain, and the statically resolved amount
|
|
103
|
+
// as a decimal string (verified continuations, plan GD-8, seam C5). `nodeId`
|
|
104
|
+
// names the `continuation.settle` node this input funds (the `phase1ByNode` /
|
|
105
|
+
// `actions` key); absent when the input funds no settle leg (e.g. a plain
|
|
106
|
+
// swap's input).
|
|
97
107
|
export interface SpendEntry {
|
|
108
|
+
readonly input: string;
|
|
98
109
|
readonly token: string;
|
|
110
|
+
readonly chainId: number;
|
|
99
111
|
readonly amount: string;
|
|
112
|
+
readonly nodeId?: string;
|
|
113
|
+
}
|
|
114
|
+
|
|
115
|
+
// One fee row per (input, recipient), as the compiled fill charges it.
|
|
116
|
+
// Hand-mirrored from api-schemas' `ComposeFeeSchema` (the OpenAPI source of
|
|
117
|
+
// truth; this package cannot depend on it). `recipient` names WHO is charged
|
|
118
|
+
// — never an address; the address is the sibling `recipientAddress`. `amount`
|
|
119
|
+
// is absent when the gross is only known on-chain at execution time (a
|
|
120
|
+
// balance-materialiser input).
|
|
121
|
+
export interface ComposeFee {
|
|
122
|
+
readonly input: string;
|
|
123
|
+
// Zero address for native, otherwise the ERC-20 contract.
|
|
124
|
+
readonly token: string;
|
|
125
|
+
readonly recipient: 'lifi' | 'integrator';
|
|
126
|
+
readonly recipientAddress: string;
|
|
127
|
+
readonly bps: number;
|
|
128
|
+
readonly amount?: string;
|
|
129
|
+
}
|
|
130
|
+
|
|
131
|
+
// The optional user-program simulation result, present only when the request
|
|
132
|
+
// opted in via `run.simulateUserProgram` and the simulation succeeded.
|
|
133
|
+
// Hand-mirrored from api-schemas' `ComposeUserProgramSimulationOkSchema`.
|
|
134
|
+
export interface ComposeUserProgramSimulation {
|
|
135
|
+
readonly status: 'ok';
|
|
136
|
+
readonly returnData: string;
|
|
137
|
+
}
|
|
138
|
+
|
|
139
|
+
// The solver-extractable fill (verified continuations, GD-8/GD-6, seam C5),
|
|
140
|
+
// present on every compiled success. Hand-mirrored to api-schemas' `fill`
|
|
141
|
+
// object (the OpenAPI source of truth; this package cannot depend on it).
|
|
142
|
+
// `spends` is what the fill consumes per funding input; `validUntilMs` is the
|
|
143
|
+
// fill freshness bound (earliest prepared-node expiry) — ABSENT = no expiry.
|
|
144
|
+
// The fill is transaction-scoped; the leg-scoped C4 verification echo lives in
|
|
145
|
+
// the sibling `verificationByNode` record.
|
|
146
|
+
export interface ComposeFill {
|
|
147
|
+
readonly spends: readonly SpendEntry[];
|
|
148
|
+
readonly validUntilMs?: number;
|
|
100
149
|
}
|
|
101
150
|
|
|
102
151
|
export interface ComposeCompileSuccessData extends ComposeContinuationData {
|
|
103
152
|
readonly producedResources: Record<string, ProducedResource>;
|
|
104
|
-
|
|
153
|
+
// The OpenAPI source of truth documents the optionality and funding modes.
|
|
154
|
+
readonly transactionRequest?: ComposeTransactionRequest;
|
|
155
|
+
readonly actions?: readonly ComposeAction[];
|
|
105
156
|
readonly userProxy: string;
|
|
106
157
|
readonly priceImpact?: PriceImpact;
|
|
107
158
|
readonly approvals?: readonly ApprovalEntry[];
|
|
108
|
-
//
|
|
109
|
-
//
|
|
110
|
-
|
|
111
|
-
//
|
|
112
|
-
//
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
159
|
+
// The per-(input, recipient) fee rows the compiled fill charges. Absent when
|
|
160
|
+
// no fee applies.
|
|
161
|
+
readonly fees?: readonly ComposeFee[];
|
|
162
|
+
// The optional user-program simulation echo, present only when the request
|
|
163
|
+
// opted in via `run.simulateUserProgram` and the simulation succeeded.
|
|
164
|
+
readonly userProgramSimulation?: ComposeUserProgramSimulation;
|
|
165
|
+
// GD-8 settlement-fill surface (seam C5): the solver-extractable `fill`,
|
|
166
|
+
// present on every success response — the funding legs it consumes and the
|
|
167
|
+
// freshness bound (absent = no expiry).
|
|
168
|
+
readonly fill?: ComposeFill;
|
|
169
|
+
// The C4 verification echo, keyed by the flow node that carried the
|
|
170
|
+
// commitment (the `continuation.commitment` node on a settlement
|
|
171
|
+
// re-submission, the `continuation.settle` node on authoring-time provider
|
|
172
|
+
// verification). Present only when the compile committed a validation
|
|
173
|
+
// program; today at most one entry (the compiler rejects multi-node
|
|
174
|
+
// committed verification).
|
|
175
|
+
readonly verificationByNode?: Record<string, VerificationDescriptor>;
|
|
117
176
|
}
|
|
118
177
|
|
|
119
178
|
export interface ComposeCompilePartialData extends ComposeContinuationData {
|
|
@@ -122,6 +181,13 @@ export interface ComposeCompilePartialData extends ComposeContinuationData {
|
|
|
122
181
|
readonly userProxy: string;
|
|
123
182
|
readonly simulationRevert: SimulationRevert;
|
|
124
183
|
readonly approvals?: readonly ApprovalEntry[];
|
|
184
|
+
readonly actions?: readonly ComposeAction[];
|
|
185
|
+
// The per-(input, recipient) fee rows the compiled fill charges. Absent when
|
|
186
|
+
// no fee applies.
|
|
187
|
+
readonly fees?: readonly ComposeFee[];
|
|
188
|
+
// The optional user-program simulation echo, present only when the request
|
|
189
|
+
// opted in via `run.simulateUserProgram` and the simulation succeeded.
|
|
190
|
+
readonly userProgramSimulation?: ComposeUserProgramSimulation;
|
|
125
191
|
}
|
|
126
192
|
|
|
127
193
|
export type ComposeCompileResult =
|
package/src/constructors.ts
CHANGED
|
@@ -4,7 +4,7 @@ import type {
|
|
|
4
4
|
ResourceOutputPort,
|
|
5
5
|
ResourcePort,
|
|
6
6
|
} from './flow.js';
|
|
7
|
-
import type { HandleInput,
|
|
7
|
+
import type { HandleInput, ResourceInput, SolType } from './flowSchema.js';
|
|
8
8
|
import type { Availability } from './resource.js';
|
|
9
9
|
import { erc20Resource, nativeResource } from './resource.js';
|
|
10
10
|
import type { HandleUnits } from './zodSchemas.js';
|
|
@@ -15,12 +15,6 @@ export interface OpHandleOptions<Opt extends boolean = boolean> {
|
|
|
15
15
|
readonly optional?: Opt;
|
|
16
16
|
}
|
|
17
17
|
|
|
18
|
-
export const inputRef = (port: string): Ref => ({ $ref: `input.${port}` });
|
|
19
|
-
|
|
20
|
-
export const outputRef = (node: string, port: string): Ref => ({
|
|
21
|
-
$ref: `${node}.${port}`,
|
|
22
|
-
});
|
|
23
|
-
|
|
24
18
|
/** Returns `{ [key]: value }` when `value` is not nullish, else `{}`. */
|
|
25
19
|
const optionalProp = <K extends string, V>(
|
|
26
20
|
key: K,
|
package/src/continuation.ts
CHANGED
|
@@ -63,25 +63,25 @@ export const ContinuationIntentSchema = Schema.Struct({
|
|
|
63
63
|
validity: Schema.Struct({ expiresAtMs: Schema.Number }),
|
|
64
64
|
perpetual: Schema.optional(Schema.Boolean),
|
|
65
65
|
provider: Schema.optional(Schema.String),
|
|
66
|
+
// Funding-path mode. The HTTP wire contract is documented by
|
|
67
|
+
// `ComposeActionsSchema` in `@lifi/api-schemas`.
|
|
68
|
+
funding: Schema.optional(Schema.Literal('inline', 'external')),
|
|
66
69
|
});
|
|
67
70
|
|
|
68
|
-
//
|
|
69
|
-
//
|
|
70
|
-
//
|
|
71
|
-
//
|
|
72
|
-
// `transactionRequest`; a venue whose phase-1 tx differs may instead emit an
|
|
73
|
-
// explicit `transactionRequest` override here.
|
|
74
|
-
// - `signables` — EIP-712 order(s) to sign (for signed-order venues; not
|
|
75
|
-
// produced in v1, defined for the seam).
|
|
76
|
-
// - `none` — nothing to sign now.
|
|
71
|
+
// Internal phase-1 artifact. The HTTP layer projects `transaction` artifacts
|
|
72
|
+
// to metadata and publishes real external-funding calldata through
|
|
73
|
+
// `ComposeActionsSchema`. The internal `transactionRequest` remains optional
|
|
74
|
+
// because inline funding and dry runs do not produce a submittable transfer.
|
|
77
75
|
export const Phase1ArtifactSchema = Schema.Union(
|
|
78
76
|
Schema.Struct({
|
|
79
77
|
kind: Schema.Literal('transaction'),
|
|
78
|
+
funding: Schema.Literal('inline', 'external'),
|
|
80
79
|
transactionRequest: Schema.optional(
|
|
81
80
|
Schema.Struct({
|
|
82
81
|
to: Schema.String,
|
|
83
82
|
data: Schema.String,
|
|
84
83
|
value: Schema.String,
|
|
84
|
+
chainId: Schema.Number,
|
|
85
85
|
}),
|
|
86
86
|
),
|
|
87
87
|
}),
|
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/flowSchema.ts
CHANGED
|
@@ -112,18 +112,12 @@ export const CallSchema = Schema.Struct({
|
|
|
112
112
|
guards: Schema.optional(Schema.Array(AppliedGuardSchema)),
|
|
113
113
|
});
|
|
114
114
|
|
|
115
|
-
export const ContinuationSchema = Schema.Struct({
|
|
116
|
-
awaits: Schema.String,
|
|
117
|
-
flowId: Schema.String,
|
|
118
|
-
});
|
|
119
|
-
|
|
120
115
|
export const FlowSchema = Schema.Struct({
|
|
121
116
|
version: Schema.Literal(1),
|
|
122
117
|
id: Schema.String,
|
|
123
118
|
chainId: ChainIdSchema,
|
|
124
119
|
inputs: Schema.Array(FlowInputSchema),
|
|
125
120
|
nodes: Schema.Array(CallSchema),
|
|
126
|
-
continuations: Schema.optional(Schema.Array(ContinuationSchema)),
|
|
127
121
|
});
|
|
128
122
|
|
|
129
123
|
export type SolType = typeof SolTypeSchema.Type;
|
|
@@ -135,5 +129,4 @@ export type LiteralBinding = typeof LiteralBindingSchema.Type;
|
|
|
135
129
|
export type BindValue = typeof BindValueSchema.Type;
|
|
136
130
|
export type AppliedGuard = typeof AppliedGuardSchema.Type;
|
|
137
131
|
export type Call = typeof CallSchema.Type;
|
|
138
|
-
export type Continuation = typeof ContinuationSchema.Type;
|
|
139
132
|
export type Flow = typeof FlowSchema.Type;
|
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
|
@@ -8,7 +8,6 @@ export type {
|
|
|
8
8
|
BindValue,
|
|
9
9
|
AppliedGuard,
|
|
10
10
|
Call,
|
|
11
|
-
Continuation,
|
|
12
11
|
Flow,
|
|
13
12
|
} from './flowSchema.js';
|
|
14
13
|
export {
|
|
@@ -23,7 +22,6 @@ export {
|
|
|
23
22
|
BindValueSchema,
|
|
24
23
|
AppliedGuardSchema,
|
|
25
24
|
CallSchema,
|
|
26
|
-
ContinuationSchema,
|
|
27
25
|
} from './flowSchema.js';
|
|
28
26
|
|
|
29
27
|
export type {
|
|
@@ -78,6 +76,7 @@ export type {
|
|
|
78
76
|
OpOutputPort,
|
|
79
77
|
ComposeError,
|
|
80
78
|
ComposeErrorKind,
|
|
79
|
+
ComposeRouteErrorKind,
|
|
81
80
|
GenericComposeErrorKind,
|
|
82
81
|
PreparationComposeError,
|
|
83
82
|
SimulationRevertComposeError,
|
|
@@ -144,12 +143,17 @@ export {
|
|
|
144
143
|
readResource,
|
|
145
144
|
opHandle,
|
|
146
145
|
resourceOutput,
|
|
147
|
-
inputRef,
|
|
148
|
-
outputRef,
|
|
149
146
|
} from './constructors.js';
|
|
150
147
|
|
|
151
|
-
export type {
|
|
148
|
+
export type {
|
|
149
|
+
ParsedRef,
|
|
150
|
+
RefScope,
|
|
151
|
+
ContextKey,
|
|
152
|
+
RefPath,
|
|
153
|
+
RefBuilder,
|
|
154
|
+
} from './ref.js';
|
|
152
155
|
export {
|
|
156
|
+
ref,
|
|
153
157
|
parseRef,
|
|
154
158
|
foldRef,
|
|
155
159
|
refKey,
|
|
@@ -187,7 +191,10 @@ export type {
|
|
|
187
191
|
ComposeRun,
|
|
188
192
|
ComposeCompileRequest,
|
|
189
193
|
ComposeCompileSuccessData,
|
|
190
|
-
|
|
194
|
+
ComposeFill,
|
|
195
|
+
ComposeFee,
|
|
196
|
+
ComposeUserProgramSimulation,
|
|
197
|
+
ComposeAction,
|
|
191
198
|
PriceImpact,
|
|
192
199
|
SpendEntry,
|
|
193
200
|
SimulationPolicy,
|
|
@@ -235,6 +242,12 @@ export {
|
|
|
235
242
|
SIMULATE_MAX_TRACKED_BALANCES,
|
|
236
243
|
SIMULATE_MAX_REQUIREMENTS,
|
|
237
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';
|
|
238
251
|
|
|
239
252
|
export type {
|
|
240
253
|
MaterialiserMetadata,
|
package/src/ref.ts
CHANGED
|
@@ -45,6 +45,39 @@ export const parseRef = (ref: Ref): ParsedRef => {
|
|
|
45
45
|
return { scope: 'output', node: prefix, port: suffix };
|
|
46
46
|
};
|
|
47
47
|
|
|
48
|
+
/** A ref path: a dotpath such as `input.amount` or `nodeId.port`. */
|
|
49
|
+
export type RefPath = `${string}.${string}`;
|
|
50
|
+
|
|
51
|
+
const buildRef = (path: RefPath): Ref => {
|
|
52
|
+
if (path.indexOf('.') < 1)
|
|
53
|
+
throw new Error(
|
|
54
|
+
`Invalid ref: "${path}" (must be a dotpath like "input.name" or "nodeId.port")`,
|
|
55
|
+
);
|
|
56
|
+
const built: Ref = { $ref: path };
|
|
57
|
+
parseRef(built); // rejects an unknown `context.*` key
|
|
58
|
+
return built;
|
|
59
|
+
};
|
|
60
|
+
|
|
61
|
+
/**
|
|
62
|
+
* Builds a bind ref. `ref.input(port)` for a flow input, `ref.context.*` for a
|
|
63
|
+
* context ref, and a dotpath for a node output (`ref('deposit.shares')`).
|
|
64
|
+
* Prefer the named forms: `parseRef` reads an unrecognised prefix as a node id,
|
|
65
|
+
* so a misspelled `input.`/`context.` silently becomes an output ref.
|
|
66
|
+
*/
|
|
67
|
+
export interface RefBuilder {
|
|
68
|
+
(path: RefPath): Ref;
|
|
69
|
+
input(port: string): Ref;
|
|
70
|
+
readonly context: { readonly [K in ContextKey]: Ref };
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
export const ref: RefBuilder = Object.assign(buildRef, {
|
|
74
|
+
input: (port: string): Ref => buildRef(`input.${port}`),
|
|
75
|
+
context: {
|
|
76
|
+
sender: buildRef('context.sender'),
|
|
77
|
+
executionAddress: buildRef('context.executionAddress'),
|
|
78
|
+
},
|
|
79
|
+
});
|
|
80
|
+
|
|
48
81
|
export const foldRef = <R>(
|
|
49
82
|
ref: ParsedRef,
|
|
50
83
|
cases: {
|
package/src/resource.ts
CHANGED
|
@@ -24,6 +24,11 @@ export type ProducedResource = Resource & {
|
|
|
24
24
|
readonly availability: Availability;
|
|
25
25
|
readonly simulated?: SimulatedAmounts;
|
|
26
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;
|
|
27
32
|
};
|
|
28
33
|
|
|
29
34
|
export const erc20Resource = (token: string, chainId: number): Resource => ({
|
package/src/route.ts
CHANGED
|
@@ -4,16 +4,18 @@
|
|
|
4
4
|
* format is always a decimal string, which the SDK serialises for you.
|
|
5
5
|
*
|
|
6
6
|
* `/compose/route` trades authoring power for brevity. Instead of a full flow
|
|
7
|
-
* document it takes a single from/to token pair; the server builds a
|
|
8
|
-
*
|
|
9
|
-
*
|
|
10
|
-
*
|
|
11
|
-
*
|
|
12
|
-
*
|
|
13
|
-
*
|
|
14
|
-
*
|
|
15
|
-
*
|
|
16
|
-
*
|
|
7
|
+
* document it takes a single from/to token pair; the server builds a one-node
|
|
8
|
+
* zap flow with a `directDeposit` input on the caller's behalf and runs it
|
|
9
|
+
* through the same compile pipeline as `POST /compose`. It routes through
|
|
10
|
+
* `lifi.zap` unless the pair is reachable only asynchronously and the request
|
|
11
|
+
* set `allowAsyncRoutes`, in which case it uses `lifi.zapAsync`. As of today
|
|
12
|
+
* the flow it builds is a single zap step — one edge of the server's routing
|
|
13
|
+
* catalog — and it is meant to author richer flows later, which this request
|
|
14
|
+
* shape is deliberately agnostic about. Its response body is byte-identical to
|
|
15
|
+
* that of `POST /compose` — the enveloped `ComposeCompileSuccessData` on HTTP
|
|
16
|
+
* 200 and `ComposeCompilePartialData` on HTTP 206 — so this file declares only
|
|
17
|
+
* the request shape and reuses `ComposeCompileResult` from `./compile.js` for
|
|
18
|
+
* the result.
|
|
17
19
|
*
|
|
18
20
|
* These are the single source of truth for the request shape, hand-authored
|
|
19
21
|
* here for the same reason as `./compile.ts` and `./simulate.ts` rather than
|
|
@@ -124,4 +126,14 @@ export interface ComposeRouteRequest {
|
|
|
124
126
|
* omitting approvals that are already sufficient. Defaults to `false`.
|
|
125
127
|
*/
|
|
126
128
|
readonly checkOnChainAllowances?: boolean;
|
|
129
|
+
/**
|
|
130
|
+
* Accept a route whose output is delivered only after the initiating
|
|
131
|
+
* transaction settles (`availability: 'future'` on the produced resource).
|
|
132
|
+
* Such a route obliges you to track settlement rather than treat the
|
|
133
|
+
* transaction as completing the job, and carries no slippage floor, so it is
|
|
134
|
+
* opt-in. Defaults to `false` server-side, which leaves a pair reachable
|
|
135
|
+
* only asynchronously rejected with `no_route_error` and guarantees every
|
|
136
|
+
* produced resource is `availability: 'now'`.
|
|
137
|
+
*/
|
|
138
|
+
readonly allowAsyncRoutes?: boolean;
|
|
127
139
|
}
|
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
|
+
};
|
package/src/zodSchemas.ts
CHANGED
|
@@ -165,22 +165,13 @@ export const ComposeManifestZod = z.object({
|
|
|
165
165
|
preconditions: z.array(ManifestPreconditionZod).optional(),
|
|
166
166
|
});
|
|
167
167
|
|
|
168
|
-
//
|
|
169
|
-
//
|
|
170
|
-
//
|
|
171
|
-
// `transactionRequest` only if a venue later needs it; for v1 it is just
|
|
172
|
-
// `{ kind: "transaction" }` and the client funds via the existing
|
|
173
|
-
// response-level `transactionRequest`.
|
|
168
|
+
// Metadata-only HTTP projection of `Phase1ArtifactSchema`. The authoritative
|
|
169
|
+
// funding and action contract lives on `ComposeActionsSchema` in
|
|
170
|
+
// `@lifi/api-schemas`.
|
|
174
171
|
export const Phase1ArtifactZod = z.discriminatedUnion('kind', [
|
|
175
172
|
z.object({
|
|
176
173
|
kind: z.literal('transaction'),
|
|
177
|
-
|
|
178
|
-
.object({
|
|
179
|
-
to: z.string(),
|
|
180
|
-
data: z.string(),
|
|
181
|
-
value: z.string(),
|
|
182
|
-
})
|
|
183
|
-
.optional(),
|
|
174
|
+
funding: z.enum(['inline', 'external']),
|
|
184
175
|
}),
|
|
185
176
|
z.object({
|
|
186
177
|
kind: z.literal('signables'),
|