@lifi/compose-spec 0.5.1 → 0.6.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.
@@ -1,8 +1,7 @@
1
- import { Schema } from 'effect';
1
+ import { type Effect, ParseResult, Schema, type SchemaAST } from 'effect';
2
2
 
3
3
  import {
4
- canonicalNativeAddress,
5
- isAsErc20Chain,
4
+ nativeCheckPolicy,
6
5
  normalizeNativeTokenAddress,
7
6
  } from './chainCapabilities.js';
8
7
  import { ChainIdSchema, FlowSchema } from './flowSchema.js';
@@ -155,25 +154,55 @@ export const CallCheckSpecSchema = Schema.Struct({
155
154
  value: Schema.String,
156
155
  });
157
156
 
158
- // The equivalent `erc20BalanceGte` of a `nativeBalanceGte` spec on an
159
- // `as-erc20` chain: the chain's stand-in ERC-20 (PathUSD on Tempo) as `token`,
160
- // every other field carried through. Shared by `CheckSchema` and the descriptor
161
- // union `AssertedPredicateSchema` so both wire shapes rewrite identically —
162
- // authoring↔settlement hash parity requires the readiness capture and the
163
- // committed re-assertion to derive the *same* program. `owner` is `string` for
164
- // both callers (`AssertionOwnerSchema.Type` collapses to `string`).
165
- export const asErc20BalanceGteCheck = (
166
- chainId: number,
167
- owner: string,
168
- minAmount: string,
157
+ // The shape shared by the wire `nativeBalanceGte` check and the descriptor's
158
+ // symbolic-owner variant. `owner` is `string` for both (`AssertionOwnerSchema.Type`
159
+ // collapses to `string`).
160
+ interface NativeBalanceGteLike {
161
+ readonly kind: 'nativeBalanceGte';
162
+ readonly chainId: number;
163
+ readonly owner: string;
164
+ readonly minAmount: string;
165
+ }
166
+
167
+ // The equivalent `erc20BalanceGte` of a `nativeBalanceGte` spec: `token` is
168
+ // the chain's stand-in ERC-20 (PathUSD on Tempo), every other field carried
169
+ // through.
170
+ const asErc20BalanceGteCheck = (
171
+ check: NativeBalanceGteLike,
172
+ token: `0x${string}`,
169
173
  ) => ({
170
174
  kind: 'erc20BalanceGte' as const,
171
- chainId,
172
- token: canonicalNativeAddress(chainId),
173
- owner,
174
- minAmount,
175
+ chainId: check.chainId,
176
+ token,
177
+ owner: check.owner,
178
+ minAmount: check.minAmount,
175
179
  });
176
180
 
181
+ // Decode adapter over `nativeCheckPolicy` (`chainCapabilities.ts` holds the
182
+ // unit reasoning): a `nativeBalanceGte` check is kept on an evm-native chain,
183
+ // rewritten to `erc20BalanceGte` of the stand-in ERC-20 on an `as-erc20`
184
+ // chain, and rejected on a `native-mirrored-erc20` chain. Shared by
185
+ // `CheckSchema` and the descriptor's `AssertedPredicateSchema` so the
186
+ // readiness capture and the committed re-assertion derive the same program
187
+ // (authoring↔settlement hash parity).
188
+ export const decodeNativeBalanceGte = <C extends NativeBalanceGteLike>(
189
+ check: C,
190
+ ast: SchemaAST.AST,
191
+ ): Effect.Effect<
192
+ C | ReturnType<typeof asErc20BalanceGteCheck>,
193
+ ParseResult.ParseIssue
194
+ > => {
195
+ const policy = nativeCheckPolicy(check.chainId);
196
+ switch (policy.kind) {
197
+ case 'keep':
198
+ return ParseResult.succeed(check);
199
+ case 'rewrite':
200
+ return ParseResult.succeed(asErc20BalanceGteCheck(check, policy.token));
201
+ case 'reject':
202
+ return ParseResult.fail(new ParseResult.Type(ast, check, policy.reason));
203
+ }
204
+ };
205
+
177
206
  // The pre-transform union of the three named members.
178
207
  const RawCheckSchema = Schema.Union(
179
208
  Erc20BalanceGteSpecSchema,
@@ -181,28 +210,18 @@ const RawCheckSchema = Schema.Union(
181
210
  CallCheckSpecSchema,
182
211
  );
183
212
 
184
- // Decode transform mirroring `ContinuationOutcomeSchema`: a `nativeBalanceGte`
185
- // check carries no `token`, so on an `as-erc20` chain it is rewritten into an
186
- // `erc20BalanceGte` of the chain's stand-in ERC-20. Without this it lowers to
187
- // `builder.native.getBalance` (in the assertion→builder lowering, a later PR of
188
- // this stack), which reads ~0 on a
189
- // chain whose gas coin is really an ERC-20 — the readiness check and its
190
- // embedded on-chain assertion then fail permanently, making a legitimate
191
- // continuation un-settleable. Kind-changing (unlike the outcome fix's token
192
- // swap) because the native member has no `token` field. Only `nativeBalanceGte`
193
- // is touched; every other member decodes unchanged. Idempotent: an already
194
- // `erc20BalanceGte` spec and every evm-native chain pass through. Encode is the
195
- // identity (the erc20 form is valid wire input).
196
- export const CheckSchema = Schema.transform(
213
+ // Only `nativeBalanceGte` is touched (via `decodeNativeBalanceGte`); every
214
+ // other member decodes unchanged. Encode is the identity.
215
+ export const CheckSchema = Schema.transformOrFail(
197
216
  RawCheckSchema,
198
217
  Schema.typeSchema(RawCheckSchema),
199
218
  {
200
219
  strict: true,
201
- decode: (check) =>
202
- check.kind === 'nativeBalanceGte' && isAsErc20Chain(check.chainId)
203
- ? asErc20BalanceGteCheck(check.chainId, check.owner, check.minAmount)
204
- : check,
205
- encode: (check) => check,
220
+ decode: (check, _options, ast) =>
221
+ check.kind === 'nativeBalanceGte'
222
+ ? decodeNativeBalanceGte(check, ast)
223
+ : ParseResult.succeed(check),
224
+ encode: (check) => ParseResult.succeed(check),
206
225
  },
207
226
  );
208
227
 
@@ -263,6 +282,16 @@ export type Check = typeof CheckSchema.Type;
263
282
  export type AssertionSpec = typeof AssertionSpecSchema.Type;
264
283
  export type ContinuationPlan = typeof ContinuationPlanSchema.Type;
265
284
 
285
+ // The outcome a `continuation.settle` node's single `output` port stands for.
286
+ // The wire format admits several outcomes, but the op produces one resource,
287
+ // discloses one owner, and every shipped provider rejects a multi-outcome
288
+ // intent, so the first outcome is the settled one everywhere. `NonEmptyArray`
289
+ // makes `[0]` present by construction. Keep this the only place that picks
290
+ // it: a multi-outcome design changes one accessor, not a scatter of `[0]`s.
291
+ export const settledOutcome = (
292
+ intent: ContinuationIntent,
293
+ ): ContinuationOutcome => intent.outcomes[0];
294
+
266
295
  // The comparison operator carried by a `call` check. Mirrors the inline
267
296
  // `comparator` literal on the `call` member of `RawCheckSchema` above.
268
297
  export type CheckComparator = 'gte' | 'eq' | 'lte';
package/src/descriptor.ts CHANGED
@@ -1,10 +1,9 @@
1
- import { Schema } from 'effect';
1
+ import { ParseResult, Schema } from 'effect';
2
2
 
3
- import { isAsErc20Chain } from './chainCapabilities.js';
4
3
  import {
5
- asErc20BalanceGteCheck,
6
4
  AssertionOwnerSchema,
7
5
  CallCheckSpecSchema,
6
+ decodeNativeBalanceGte,
8
7
  Erc20BalanceDeltaGteSpecSchema,
9
8
  HexStringSchema,
10
9
  NativeBalanceDeltaGteSpecSchema,
@@ -71,24 +70,21 @@ const RawAssertedPredicateSchema = Schema.Union(
71
70
  NativeBalanceDeltaGteSpecSchema,
72
71
  );
73
72
 
74
- // Same `nativeBalanceGte` → `erc20BalanceGte` rewrite as `CheckSchema` (see
75
- // there), applied to the disclosed/committed predicate so the settlement-side
76
- // re-assertion derives the identical program on `as-erc20` chains and the
77
- // authoring↔settlement hashes stay equal. A committed action authored through
78
- // the fixed `CheckSchema` already carries the erc20 form, so this pass is
79
- // idempotent there; it additionally normalizes a hand-forged committed action
80
- // that embeds a raw native check. The delta members (`nativeBalanceDeltaGte`)
81
- // are intentionally untouched — they derive from already-normalized outcomes.
82
- export const AssertedPredicateSchema = Schema.transform(
73
+ // Same `nativeBalanceGte` handling as `CheckSchema`, applied to the
74
+ // disclosed/committed predicate so settlement derives the identical program.
75
+ // Idempotent on actions authored through `CheckSchema`; normalizes or refuses
76
+ // a hand-forged committed action that embeds a raw native check. The delta
77
+ // members are untouched — they derive from already-normalized outcomes.
78
+ export const AssertedPredicateSchema = Schema.transformOrFail(
83
79
  RawAssertedPredicateSchema,
84
80
  Schema.typeSchema(RawAssertedPredicateSchema),
85
81
  {
86
82
  strict: true,
87
- decode: (pred) =>
88
- pred.kind === 'nativeBalanceGte' && isAsErc20Chain(pred.chainId)
89
- ? asErc20BalanceGteCheck(pred.chainId, pred.owner, pred.minAmount)
90
- : pred,
91
- encode: (pred) => pred,
83
+ decode: (pred, _options, ast) =>
84
+ pred.kind === 'nativeBalanceGte'
85
+ ? decodeNativeBalanceGte(pred, ast)
86
+ : ParseResult.succeed(pred),
87
+ encode: (pred) => ParseResult.succeed(pred),
92
88
  },
93
89
  );
94
90
 
package/src/index.ts CHANGED
@@ -52,6 +52,7 @@ export {
52
52
  isGTECheck,
53
53
  isLTECheck,
54
54
  isEQCheck,
55
+ settledOutcome,
55
56
  } from './continuation.js';
56
57
 
57
58
  export type {
@@ -104,13 +105,7 @@ export {
104
105
  isMaterialiserInput,
105
106
  } from './flow.js';
106
107
 
107
- export type {
108
- Availability,
109
- OutputAmount,
110
- Resource,
111
- ProducedResource,
112
- SimulatedAmounts,
113
- } from './resource.js';
108
+ export type { Availability, OutputAmount, Resource } from './resource.js';
114
109
  export {
115
110
  erc20Resource,
116
111
  erc20Token,
@@ -123,6 +118,19 @@ export {
123
118
  resourcesEqual,
124
119
  } from './resource.js';
125
120
 
121
+ export type {
122
+ Amount,
123
+ ConsumedOutput,
124
+ Delivery,
125
+ Estimate,
126
+ EstimateBasis,
127
+ Minimum,
128
+ MinimumBasis,
129
+ Output,
130
+ Outputs,
131
+ TerminalOutput,
132
+ } from './output.js';
133
+
126
134
  export type {
127
135
  ProviderKindName,
128
136
  FlashloanMaterialiserInput,
@@ -172,13 +180,23 @@ export type {
172
180
  GuardCompatibility,
173
181
  } from './manifest.js';
174
182
 
175
- export type { ChainCapabilities, NativeErc20 } from './chainCapabilities.js';
183
+ export type {
184
+ ChainCapabilities,
185
+ NativeCheckPolicy,
186
+ NativeErc20,
187
+ } from './chainCapabilities.js';
176
188
  export {
177
189
  EVM_NATIVE_SENTINEL,
178
190
  TEMPO_CHAIN_ID,
179
191
  TEMPO_NATIVE_ERC20,
192
+ ARC_CHAIN_ID,
193
+ ARC_NATIVE_ERC20,
194
+ ARC_NATIVE_SCALE,
180
195
  getChainCapabilities,
196
+ foldChainCapabilities,
197
+ nativeCheckPolicy,
181
198
  isAsErc20Chain,
199
+ hasErc20CanonicalNative,
182
200
  canonicalNativeAddress,
183
201
  isNativeAddressForChain,
184
202
  isMsgValueNative,
@@ -235,6 +253,7 @@ export {
235
253
  erc20Balance,
236
254
  nativeBalance,
237
255
  erc20Allowance,
256
+ isErc20BalancePrecondition,
238
257
  isErc20AllowancePrecondition,
239
258
  isNativeBalancePrecondition,
240
259
  } from './preconditions.js';
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>;
@@ -42,6 +42,10 @@ export const erc20Allowance = (
42
42
  config: Omit<Erc20AllowancePrecondition, 'type'>,
43
43
  ): Erc20AllowancePrecondition => ({ type: 'Erc20Allowance', ...config });
44
44
 
45
+ export const isErc20BalancePrecondition = (
46
+ p: Precondition,
47
+ ): p is Erc20BalancePrecondition => p.type === 'Erc20Balance';
48
+
45
49
  export const isErc20AllowancePrecondition = (
46
50
  p: Precondition,
47
51
  ): p is Erc20AllowancePrecondition => p.type === 'Erc20Allowance';
package/src/resource.ts CHANGED
@@ -15,22 +15,6 @@ export type Resource =
15
15
  readonly chainId: number;
16
16
  };
17
17
 
18
- export type SimulatedAmounts = {
19
- readonly amountOut: bigint;
20
- readonly amountOutMin?: bigint;
21
- };
22
-
23
- export type ProducedResource = Resource & {
24
- readonly availability: Availability;
25
- readonly simulated?: SimulatedAmounts;
26
- readonly owner: string;
27
- // Wire ETA: seconds until deferred proceeds land, echoed from the routing edge
28
- // that produced this output. Only valid alongside `availability: 'future'`;
29
- // absent means no published estimate, never zero. See "ETA" in
30
- // `docs/glossary.md` (COM-1564).
31
- readonly etaSeconds?: number;
32
- };
33
-
34
18
  export const erc20Resource = (token: string, chainId: number): Resource => ({
35
19
  kind: 'erc20',
36
20
  token,
package/src/route.ts CHANGED
@@ -128,12 +128,12 @@ export interface ComposeRouteRequest {
128
128
  readonly checkOnChainAllowances?: boolean;
129
129
  /**
130
130
  * Accept a route whose output is delivered only after the initiating
131
- * transaction settles (`availability: 'future'` on the produced resource).
131
+ * transaction settles (`delivery.when: 'future'` on the terminal output).
132
132
  * Such a route obliges you to track settlement rather than treat the
133
133
  * transaction as completing the job, and carries no slippage floor, so it is
134
134
  * opt-in. Defaults to `false` server-side, which leaves a pair reachable
135
135
  * only asynchronously rejected with `no_route_error` and guarantees every
136
- * produced resource is `availability: 'now'`.
136
+ * terminal output is `delivery.when: 'now'`.
137
137
  */
138
138
  readonly allowAsyncRoutes?: boolean;
139
139
  }
package/src/version.ts CHANGED
@@ -49,26 +49,34 @@ const compareVersions = (a: ComposeVersion, b: ComposeVersion): number =>
49
49
 
50
50
  /**
51
51
  * Decides whether a client built against `client` may talk to a server that
52
- * serves `server`.
52
+ * serves `server` and accepts clients down to `minimum`.
53
53
  *
54
- * - Same `major.minor` with the client at or behind the server's patch is
55
- * compatible: patch releases only add, so an older client never emits
56
- * anything the server lacks.
57
- * - A client below the server's `major.minor` is `sdk_outdated`: the server
58
- * made a breaking change the client does not know about.
59
- * - A client ahead in any component is `server_outdated`. Even a patch-ahead
60
- * client may send a field the server has never seen, and the guarantee must
61
- * not depend on every server schema staying strict. This is the rollout
62
- * window between an npm publish and the prod image bump.
54
+ * - A client ahead of the server in any component is `server_outdated`. Even
55
+ * a patch-ahead client may send a field the server has never seen, and the
56
+ * guarantee must not depend on every server schema staying strict. This is
57
+ * the rollout window between an npm publish and the prod image bump.
58
+ * - A client below `minimum` is `sdk_outdated`: the server no longer serves
59
+ * the contract that client speaks.
60
+ * - Anything in between is compatible. Patch releases only add, so a client
61
+ * at or behind the server's patch never emits anything the server lacks;
62
+ * a client on an older minor is served because the server still emits the
63
+ * shapes that minor reads.
64
+ *
65
+ * `minimum` defaults to the server's own `major.minor.0`, which makes every
66
+ * minor bump a hard cutover. The backend passes its explicit floor so a minor
67
+ * bump can ship with the previous line still accepted; the SDK passes no floor
68
+ * because the server, not the client, decides how far back it serves.
63
69
  */
64
70
  export const checkCompatibility = (
65
71
  client: ComposeVersion,
66
72
  server: ComposeVersion,
73
+ minimum: ComposeVersion = {
74
+ major: server.major,
75
+ minor: server.minor,
76
+ patch: 0,
77
+ },
67
78
  ): VersionCompatibility => {
68
- const order = compareVersions(client, server);
69
- if (order > 0) return 'server_outdated';
70
- if (client.major !== server.major || client.minor !== server.minor) {
71
- return 'sdk_outdated';
72
- }
79
+ if (compareVersions(client, server) > 0) return 'server_outdated';
80
+ if (compareVersions(client, minimum) < 0) return 'sdk_outdated';
73
81
  return 'compatible';
74
82
  };