@lifi/compose-spec 0.4.1 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -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
- // The phase-1 action a client must take after compiling a deferred flow.
69
- //
70
- // - `transaction` — a funding transaction (fund an escrow / call a protocol
71
- // open). Usually the client funds via the main response-level
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/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/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 {
@@ -144,12 +142,17 @@ export {
144
142
  readResource,
145
143
  opHandle,
146
144
  resourceOutput,
147
- inputRef,
148
- outputRef,
149
145
  } from './constructors.js';
150
146
 
151
- export type { ParsedRef, RefScope, ContextKey } from './ref.js';
147
+ export type {
148
+ ParsedRef,
149
+ RefScope,
150
+ ContextKey,
151
+ RefPath,
152
+ RefBuilder,
153
+ } from './ref.js';
152
154
  export {
155
+ ref,
153
156
  parseRef,
154
157
  foldRef,
155
158
  refKey,
@@ -187,7 +190,10 @@ export type {
187
190
  ComposeRun,
188
191
  ComposeCompileRequest,
189
192
  ComposeCompileSuccessData,
190
- ComposeContinuation,
193
+ ComposeFill,
194
+ ComposeFee,
195
+ ComposeUserProgramSimulation,
196
+ ComposeAction,
191
197
  PriceImpact,
192
198
  SpendEntry,
193
199
  SimulationPolicy,
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
- * `lifi.zap` flow with a `directDeposit` input on the caller's behalf and runs
9
- * it through the same compile pipeline as `POST /compose`. As of today the flow
10
- * it builds is a single zap step — one edge of the server's routing catalog —
11
- * and it is meant to author richer flows later, which this request shape is
12
- * deliberately agnostic about. Its response body is byte-identical to that of
13
- * `POST /compose` — the enveloped `ComposeCompileSuccessData` on HTTP 200 and
14
- * `ComposeCompilePartialData` on HTTP 206 — so this file declares only the
15
- * request shape and reuses `ComposeCompileResult` from `./compile.js` for the
16
- * result.
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/zodSchemas.ts CHANGED
@@ -165,22 +165,13 @@ export const ComposeManifestZod = z.object({
165
165
  preconditions: z.array(ManifestPreconditionZod).optional(),
166
166
  });
167
167
 
168
- // HTTP-layer mirror of `Phase1ArtifactSchema` (the Effect schema in
169
- // `continuation.ts`). The Effect schema validates the Flow; this Zod schema
170
- // validates the `/compose` response. `transaction` carries an optional
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
- transactionRequest: z
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'),