@lifi/compose-spec 0.6.0 → 0.6.2

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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@lifi/compose-spec",
3
- "version": "0.6.0",
3
+ "version": "0.6.2",
4
4
  "description": "Public wire-format types and schemas for Compose flows",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {
@@ -4,15 +4,26 @@ import type { Resource } from './resource.js';
4
4
  * Per-chain native-asset semantics.
5
5
  *
6
6
  * Most EVM chains have an ETH-style native gas coin sent via `msg.value` (the
7
- * `evm-native` policy). A small number — currently only Tempo — express their
8
- * "native" coin as an ERC-20 token (the `as-erc20` policy). Code that needs to
9
- * lower or simulate a `Resource` of kind `"native"` should consult
10
- * `getChainCapabilities(chainId)` rather than hardcoding chain IDs.
7
+ * `evm-native` policy). A small number express their "native" coin as an
8
+ * ERC-20 token: on `as-erc20` chains (Tempo) no `msg.value` coin exists at
9
+ * all, while on `native-mirrored-erc20` chains (Arc) a real `msg.value` coin
10
+ * exists but is canonically routed through an ERC-20 facade that mirrors the
11
+ * native balance (`balanceOf == native wei / nativeScale`, with no balance
12
+ * storage of its own). Code that needs to lower or simulate a `Resource` of
13
+ * kind `"native"` should consult `getChainCapabilities(chainId)` rather than
14
+ * hardcoding chain IDs.
11
15
  *
12
16
  * The compose compiler uses this registry to transparently normalise native
13
- * resources into ERC-20 resources on `as-erc20` chains at schema-decode time
14
- * (see `normalizeResource` below and the `ResourceSchema` transform in
15
- * `flowSchema.ts`).
17
+ * resources into ERC-20 resources on both ERC-20-canonical kinds at
18
+ * schema-decode time (see `normalizeResource` below and the `ResourceSchema`
19
+ * transform in `flowSchema.ts`).
20
+ *
21
+ * The two ERC-20-canonical kinds behave identically at the resource level —
22
+ * `hasErc20CanonicalNative` is the predicate for that shared behaviour. They
23
+ * diverge only at the simulation layer: `as-erc20` balances live in ordinary
24
+ * token storage, while `native-mirrored-erc20` balances have no storage slot
25
+ * and are satisfied by a native balance override scaled by `nativeScale`
26
+ * (see compose-core's `rewritePreconditions`).
16
27
  *
17
28
  * This union is the extension point for future native-asset policies. A chain
18
29
  * with no canonical native asset would get a `reject-native` arm, under which a
@@ -25,6 +36,13 @@ export type ChainCapabilities =
25
36
  readonly kind: 'as-erc20';
26
37
  readonly chainId: number;
27
38
  readonly nativeErc20: NativeErc20;
39
+ }
40
+ | {
41
+ readonly kind: 'native-mirrored-erc20';
42
+ readonly chainId: number;
43
+ readonly nativeErc20: NativeErc20;
44
+ /** Native wei per 1 unit of the facade ERC-20 (1e12 on Arc: 18-dec native, 6-dec USDC). */
45
+ readonly nativeScale: bigint;
28
46
  };
29
47
 
30
48
  export interface NativeErc20 {
@@ -62,6 +80,25 @@ export const TEMPO_NATIVE_ERC20: NativeErc20 = {
62
80
  decimals: 6,
63
81
  };
64
82
 
83
+ export const ARC_CHAIN_ID = 5042;
84
+
85
+ /**
86
+ * Arc's native gas coin is USDC (18-decimal wei at the EVM level). The USDC
87
+ * ERC-20 at this address is a view over native balances: `balanceOf` returns
88
+ * `native wei / 1e12` and has no balance storage slot; allowances live in
89
+ * regular storage. The composer interacts with USDC exclusively through this
90
+ * facade, never via `msg.value`.
91
+ */
92
+ export const ARC_NATIVE_ERC20: NativeErc20 = {
93
+ token: '0x3600000000000000000000000000000000000000',
94
+ symbol: 'USDC',
95
+ decimals: 6,
96
+ };
97
+
98
+ // Derived from the facade's decimals so a decimal-count change cannot leave
99
+ // the scale silently wrong. Native wei is 18-decimal at the EVM level.
100
+ export const ARC_NATIVE_SCALE = 10n ** BigInt(18 - ARC_NATIVE_ERC20.decimals);
101
+
65
102
  const REGISTRY: ReadonlyMap<number, ChainCapabilities> = new Map<
66
103
  number,
67
104
  ChainCapabilities
@@ -74,41 +111,166 @@ const REGISTRY: ReadonlyMap<number, ChainCapabilities> = new Map<
74
111
  nativeErc20: TEMPO_NATIVE_ERC20,
75
112
  },
76
113
  ],
114
+ [
115
+ ARC_CHAIN_ID,
116
+ {
117
+ kind: 'native-mirrored-erc20',
118
+ chainId: ARC_CHAIN_ID,
119
+ nativeErc20: ARC_NATIVE_ERC20,
120
+ nativeScale: ARC_NATIVE_SCALE,
121
+ },
122
+ ],
77
123
  ]);
78
124
 
125
+ /**
126
+ * Every chain with a non-default policy, in registration order. The registry
127
+ * itself stays private so runtime callers go through `getChainCapabilities`;
128
+ * this is the enumeration surface for tooling that must check *all* registered
129
+ * chains against an external source (the slot-finder parity spec), where
130
+ * scanning exported `*_CHAIN_ID` constants would silently miss a chain that
131
+ * skipped the naming convention.
132
+ *
133
+ * @internal Exported only so `chainCapabilitiesSlotFinderParity.spec.ts` can
134
+ * enumerate the registry. Not part of the package barrel.
135
+ */
136
+ export const registeredChainCapabilities = (): readonly ChainCapabilities[] => [
137
+ ...REGISTRY.values(),
138
+ ];
139
+
79
140
  export const getChainCapabilities = (chainId: number): ChainCapabilities =>
80
141
  REGISTRY.get(chainId) ?? { kind: 'evm-native', chainId };
81
142
 
143
+ /**
144
+ * Structural fold over the `ChainCapabilities` union — the capabilities
145
+ * counterpart of `foldResource`/`foldRef`. Dispatches on `kind` and hands each
146
+ * case its narrowed fields, so consumers that must branch on the native-asset
147
+ * policy (e.g. compose-core's `rewritePreconditions`) do so through one
148
+ * combinator whose exhaustiveness the compiler enforces: adding a new arm to
149
+ * the union above turns every `foldChainCapabilities` call into a type error
150
+ * until it handles the new case.
151
+ */
152
+ export const foldChainCapabilities = <R>(
153
+ caps: ChainCapabilities,
154
+ cases: {
155
+ readonly evmNative: (chainId: number) => R;
156
+ readonly asErc20: (nativeErc20: NativeErc20, chainId: number) => R;
157
+ readonly nativeMirroredErc20: (
158
+ nativeErc20: NativeErc20,
159
+ nativeScale: bigint,
160
+ chainId: number,
161
+ ) => R;
162
+ },
163
+ ): R => {
164
+ switch (caps.kind) {
165
+ case 'evm-native':
166
+ return cases.evmNative(caps.chainId);
167
+ case 'as-erc20':
168
+ return cases.asErc20(caps.nativeErc20, caps.chainId);
169
+ case 'native-mirrored-erc20':
170
+ return cases.nativeMirroredErc20(
171
+ caps.nativeErc20,
172
+ caps.nativeScale,
173
+ caps.chainId,
174
+ );
175
+ }
176
+ };
177
+
178
+ /**
179
+ * What a wire-level native-balance check (`nativeBalanceGte`) must become on
180
+ * a chain, decided once here from the native-asset policy:
181
+ *
182
+ * - `keep` — `evm-native`: the native read is the right read.
183
+ * - `rewrite` — `as-erc20` (Tempo): no `msg.value` coin exists, so the check
184
+ * becomes an `erc20BalanceGte` of `token`, the stand-in ERC-20. Amounts were
185
+ * always facade-denominated, so `minAmount` carries over verbatim.
186
+ * - `reject` — `native-mirrored-erc20` (Arc): a native read returns real
187
+ * 18-decimal wei, `nativeScale`× the facade's units, so no interpretation of
188
+ * `minAmount` is safe — reusing it on a facade read is 1e12 too strict for a
189
+ * wei-denominated check, keeping the native read lets a facade-denominated
190
+ * check pass 1e12 too easily. The check must be authored as
191
+ * `erc20BalanceGte` of the facade; `reason` says so.
192
+ *
193
+ * Consumers (the `CheckSchema` / `AssertedPredicateSchema` decodes and
194
+ * compose-core's derive backstop) are adapters over this result, so the unit
195
+ * rule lives in one place and the fold's exhaustiveness reaches every site.
196
+ */
197
+ export type NativeCheckPolicy =
198
+ | { readonly kind: 'keep' }
199
+ | { readonly kind: 'rewrite'; readonly token: `0x${string}` }
200
+ | { readonly kind: 'reject'; readonly reason: string };
201
+
202
+ export const nativeCheckPolicy = (chainId: number): NativeCheckPolicy =>
203
+ foldChainCapabilities<NativeCheckPolicy>(getChainCapabilities(chainId), {
204
+ evmNative: () => ({ kind: 'keep' }),
205
+ asErc20: (nativeErc20) => ({ kind: 'rewrite', token: nativeErc20.token }),
206
+ nativeMirroredErc20: (nativeErc20) => ({
207
+ kind: 'reject',
208
+ reason:
209
+ `nativeBalanceGte is not accepted on chain ${chainId}: its canonical ` +
210
+ `native asset is an ERC-20 facade whose units differ from native wei — ` +
211
+ `author the check as erc20BalanceGte of ${nativeErc20.token}`,
212
+ }),
213
+ });
214
+
215
+ /**
216
+ * Exact-kind check for `as-erc20` (currently Tempo only) — the rare case that
217
+ * genuinely means "no `msg.value` coin exists on this chain". Most consumers
218
+ * want `hasErc20CanonicalNative` instead, which also covers
219
+ * `native-mirrored-erc20` chains (Arc), where the composer's ERC-20-only
220
+ * policy applies even though `msg.value` works. Code that must treat the two
221
+ * ERC-20-native kinds differently goes through `foldChainCapabilities` or
222
+ * `nativeCheckPolicy`, never a second exact-kind predicate.
223
+ */
82
224
  export const isAsErc20Chain = (chainId: number): boolean =>
83
225
  getChainCapabilities(chainId).kind === 'as-erc20';
84
226
 
227
+ /**
228
+ * The chain's stand-in native ERC-20 when its canonical native asset is an
229
+ * ERC-20 (`as-erc20` and `native-mirrored-erc20`), `undefined` on plain
230
+ * `evm-native` chains. Module-local narrowing helper behind the exported
231
+ * predicates and rewrites below.
232
+ */
233
+ const erc20CanonicalNative = (
234
+ caps: ChainCapabilities,
235
+ ): NativeErc20 | undefined =>
236
+ caps.kind === 'as-erc20' || caps.kind === 'native-mirrored-erc20'
237
+ ? caps.nativeErc20
238
+ : undefined;
239
+
240
+ /**
241
+ * Whether the chain's canonical native asset is an ERC-20 — true for both
242
+ * `as-erc20` chains (Tempo: no `msg.value` coin exists) and
243
+ * `native-mirrored-erc20` chains (Arc: `msg.value` exists but is never used).
244
+ * This is the predicate for the shared resource-level behaviour: native
245
+ * resources are rewritten to the ERC-20, native routing edges are dropped, and
246
+ * a surviving native resource is a compile error.
247
+ */
248
+ export const hasErc20CanonicalNative = (chainId: number): boolean =>
249
+ erc20CanonicalNative(getChainCapabilities(chainId)) !== undefined;
250
+
85
251
  /**
86
252
  * The address that represents the chain's native asset.
87
253
  *
88
- * On EVM-native chains this is the zero-address sentinel `0x0…0`. On
89
- * `as-erc20` chains it is the chain's stand-in ERC-20 (e.g. PathUSD on Tempo).
254
+ * On EVM-native chains this is the zero-address sentinel `0x0…0`. On chains
255
+ * whose canonical native asset is an ERC-20 it is the chain's stand-in token
256
+ * (PathUSD on Tempo, the USDC facade on Arc).
90
257
  */
91
- export const canonicalNativeAddress = (chainId: number): `0x${string}` => {
92
- const caps = getChainCapabilities(chainId);
93
- return caps.kind === 'as-erc20'
94
- ? caps.nativeErc20.token
95
- : EVM_NATIVE_SENTINEL;
96
- };
258
+ export const canonicalNativeAddress = (chainId: number): `0x${string}` =>
259
+ erc20CanonicalNative(getChainCapabilities(chainId))?.token ??
260
+ EVM_NATIVE_SENTINEL;
97
261
 
98
262
  /**
99
263
  * Whether `address` represents the native asset of `chainId`.
100
264
  *
101
265
  * On EVM-native chains, this is the case-insensitive zero-address check. On
102
- * `as-erc20` chains, the literal zero address returns `false` — only the
103
- * chain's stand-in ERC-20 address matches.
266
+ * chains whose canonical native asset is an ERC-20, the literal zero address
267
+ * returns `false` — only the chain's stand-in ERC-20 address matches.
104
268
  */
105
269
  export const isNativeAddressForChain = (
106
270
  chainId: number,
107
271
  address: string,
108
272
  ): boolean => {
109
- const caps = getChainCapabilities(chainId);
110
- const target =
111
- caps.kind === 'as-erc20' ? caps.nativeErc20.token : EVM_NATIVE_SENTINEL;
273
+ const target = canonicalNativeAddress(chainId);
112
274
  return address.toLowerCase() === target.toLowerCase();
113
275
  };
114
276
 
@@ -119,30 +281,32 @@ export const isNativeAddressForChain = (
119
281
  * This is the single predicate that gates `msg.value` semantics — choosing a
120
282
  * `NativeBalance` over an `Erc20Balance` simulation requirement, and skipping
121
283
  * the ERC-20 approval a native input would otherwise need. It returns `false`
122
- * for every address on an `as-erc20` chain (including the zero sentinel),
123
- * because there the "native" coin is a real ERC-20 moved via `transferFrom`,
124
- * never `msg.value`. Use this rather than re-deriving
125
- * `!isAsErc20Chain(chainId) && address === EVM_NATIVE_SENTINEL` at call sites,
126
- * and rather than `isNativeAddressForChain`, which returns `true` for the
127
- * stand-in ERC-20 (PathUSD) on `as-erc20` chains and would wrongly route it to
128
- * `msg.value`.
284
+ * for every address on a chain whose canonical native asset is an ERC-20
285
+ * (including the zero sentinel): on `as-erc20` chains the "native" coin is a
286
+ * real ERC-20 moved via `transferFrom`, never `msg.value`, and on
287
+ * `native-mirrored-erc20` chains `msg.value` works but the composer's policy
288
+ * is to move the coin exclusively through the ERC-20 facade. Use this rather
289
+ * than re-deriving the check at call sites, and rather than
290
+ * `isNativeAddressForChain`, which returns `true` for the stand-in ERC-20
291
+ * (PathUSD on Tempo) and would wrongly route it to `msg.value`.
129
292
  */
130
293
  export const isMsgValueNative = (chainId: number, address: string): boolean =>
131
- !isAsErc20Chain(chainId) && isNativeSentinel(address);
294
+ !hasErc20CanonicalNative(chainId) && isNativeSentinel(address);
132
295
 
133
296
  /**
134
297
  * Rewrite a single `Resource` according to its chain's capabilities.
135
298
  *
136
299
  * On chains with the default `evm-native` policy, every resource is returned
137
- * unchanged. On `as-erc20` chains (currently only Tempo, chainId 4217), a
138
- * resource of kind `"native"` is rewritten into the equivalent ERC-20
139
- * resource pointing at the chain's stand-in token (PathUSD for Tempo).
300
+ * unchanged. On chains whose canonical native asset is an ERC-20 (`as-erc20`
301
+ * Tempo, `native-mirrored-erc20` Arc), a resource of kind `"native"` is
302
+ * rewritten into the equivalent ERC-20 resource pointing at the chain's
303
+ * stand-in token (PathUSD on Tempo, the USDC facade on Arc).
140
304
  *
141
305
  * This is the rewrite primitive behind the `ResourceSchema` decode transform
142
306
  * (see `flowSchema.ts`), which is THE chokepoint: it runs every time a
143
307
  * `Resource` is parsed — flow inputs via `FlowSchema`, op configs via
144
308
  * `decodeConfig` — so every downstream pass (`normalizeFlow`, `resolve`,
145
- * `lower`, `simulate`) sees only ERC-20 resources on `as-erc20` chains.
309
+ * `lower`, `simulate`) sees only ERC-20 resources on those chains.
146
310
  *
147
311
  * The function preserves referential identity when nothing changes (returns the
148
312
  * input `r` unchanged on evm-native chains and for ERC-20 resources) and is
@@ -150,25 +314,25 @@ export const isMsgValueNative = (chainId: number, address: string): boolean =>
150
314
  */
151
315
  export const normalizeResource = (r: Resource): Resource => {
152
316
  if (r.kind !== 'native') return r;
153
- const caps = getChainCapabilities(r.chainId);
154
- if (caps.kind !== 'as-erc20') return r;
317
+ const erc20 = erc20CanonicalNative(getChainCapabilities(r.chainId));
318
+ if (erc20 === undefined) return r;
155
319
  return {
156
320
  kind: 'erc20',
157
321
  chainId: r.chainId,
158
- token: caps.nativeErc20.token,
322
+ token: erc20.token,
159
323
  };
160
324
  };
161
325
 
162
326
  /**
163
327
  * Address-level counterpart of `normalizeResource` for wire fields that carry a
164
328
  * native asset as a bare token string (a continuation outcome's `token`). On
165
- * `as-erc20` chains the native sentinel is rewritten to the chain's stand-in
166
- * ERC-20; every other address passes through.
329
+ * chains whose canonical native asset is an ERC-20, the native sentinel is
330
+ * rewritten to the chain's stand-in ERC-20; every other address passes through.
167
331
  */
168
332
  export const normalizeNativeTokenAddress = (
169
333
  token: string,
170
334
  chainId: number,
171
335
  ): string =>
172
- isAsErc20Chain(chainId) && isNativeSentinel(token)
336
+ hasErc20CanonicalNative(chainId) && isNativeSentinel(token)
173
337
  ? canonicalNativeAddress(chainId)
174
338
  : token;
package/src/compile.ts CHANGED
@@ -139,8 +139,10 @@ export interface ComposeUserProgramSimulation {
139
139
  // The solver-extractable fill (verified continuations, GD-8/GD-6, seam C5),
140
140
  // present on every compiled success. Hand-mirrored to api-schemas' `fill`
141
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.
142
+ // `spends` is the amount the fill may spend of each funding input — the exact
143
+ // amount, or the pull cap of a non-exact deposit whose realised deposit is
144
+ // measured on-chain; `validUntilMs` is the fill freshness bound (earliest
145
+ // prepared-node expiry) — ABSENT = no expiry.
144
146
  // The fill is transaction-scoped; the leg-scoped C4 verification echo lives in
145
147
  // the sibling `verificationByNode` record.
146
148
  export interface ComposeFill {
@@ -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
 
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/flow.ts CHANGED
@@ -112,11 +112,21 @@ export interface FailedPreparedOp {
112
112
  readonly kind: GenericComposeErrorKind;
113
113
  readonly message: string;
114
114
  readonly path?: string;
115
+ readonly port?: string;
116
+ readonly fix?: string;
115
117
  }
116
118
 
119
+ // `path` names the node the rejection is about, `port` the bound input port
120
+ // when the rejection is about what that port binds, and `fix` the one action
121
+ // that clears it. A `continuation.settle` authoring rejection carries `path`
122
+ // and `fix`, plus `port` when it is about a bind; other `validation_error`s may
123
+ // omit `fix`. A deployment or internal fault carries none of the three, because
124
+ // no edit to the flow clears it.
117
125
  interface ComposeErrorBase {
118
126
  readonly message: string;
119
127
  readonly path?: string;
128
+ readonly port?: string;
129
+ readonly fix?: string;
120
130
  }
121
131
 
122
132
  export interface PreparationComposeError extends ComposeErrorBase {
package/src/index.ts CHANGED
@@ -180,13 +180,23 @@ export type {
180
180
  GuardCompatibility,
181
181
  } from './manifest.js';
182
182
 
183
- export type { ChainCapabilities, NativeErc20 } from './chainCapabilities.js';
183
+ export type {
184
+ ChainCapabilities,
185
+ NativeCheckPolicy,
186
+ NativeErc20,
187
+ } from './chainCapabilities.js';
184
188
  export {
185
189
  EVM_NATIVE_SENTINEL,
186
190
  TEMPO_CHAIN_ID,
187
191
  TEMPO_NATIVE_ERC20,
192
+ ARC_CHAIN_ID,
193
+ ARC_NATIVE_ERC20,
194
+ ARC_NATIVE_SCALE,
188
195
  getChainCapabilities,
196
+ foldChainCapabilities,
197
+ nativeCheckPolicy,
189
198
  isAsErc20Chain,
199
+ hasErc20CanonicalNative,
190
200
  canonicalNativeAddress,
191
201
  isNativeAddressForChain,
192
202
  isMsgValueNative,
@@ -243,6 +253,7 @@ export {
243
253
  erc20Balance,
244
254
  nativeBalance,
245
255
  erc20Allowance,
256
+ isErc20BalancePrecondition,
246
257
  isErc20AllowancePrecondition,
247
258
  isNativeBalancePrecondition,
248
259
  } from './preconditions.js';
@@ -3,6 +3,10 @@ import type { Precondition } from './flow.js';
3
3
  export type MaterialiserMetadata =
4
4
  | { readonly kind: 'exact'; readonly amount: bigint }
5
5
  | { readonly kind: 'exact-native'; readonly amount: bigint }
6
+ // The program pulls at most `amount` and consumes the measured result;
7
+ // `amount` is what an authoriser signs and what a spend report states, not
8
+ // what was deposited.
9
+ | { readonly kind: 'capped'; readonly amount: bigint }
6
10
  | { readonly kind: 'runtime' };
7
11
 
8
12
  export interface MaterialiserResolution {
@@ -15,10 +19,12 @@ export const foldMaterialiserMetadata = <R>(
15
19
  cases: {
16
20
  readonly exact: (amount: bigint) => R;
17
21
  readonly exactNative: (amount: bigint) => R;
22
+ readonly capped: (amount: bigint) => R;
18
23
  readonly runtime: () => R;
19
24
  },
20
25
  ): R => {
21
26
  if (meta.kind === 'exact') return cases.exact(meta.amount);
22
27
  if (meta.kind === 'exact-native') return cases.exactNative(meta.amount);
28
+ if (meta.kind === 'capped') return cases.capped(meta.amount);
23
29
  return cases.runtime();
24
30
  };
@@ -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';