@lifi/compose-spec 0.11.3 → 0.12.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/dist/index.js CHANGED
@@ -180,7 +180,6 @@ const normalizeNativeTokenAddress = (token, chainId) => hasErc20CanonicalNative(
180
180
  //#region src/hexPatterns.ts
181
181
  const BYTES32_LOWER_HEX = /^0x[0-9a-f]{64}$/;
182
182
  const EVM_ADDRESS_HEX = /^0x[0-9a-fA-F]{40}$/;
183
- const HEX_BYTES = /^0x(?:[0-9a-fA-F]{2})*$/;
184
183
  const DECIMAL_UINT = /^[0-9]+$/;
185
184
  const MAX_UINT256 = 2n ** 256n - 1n;
186
185
  const MAX_DATE_MS = 864e13;
@@ -189,7 +188,6 @@ const MAX_DATE_MS = 864e13;
189
188
  const SolTypeSchema = Schema.Literal("uint8", "uint16", "uint32", "uint64", "uint128", "uint256", "int128", "int256", "address", "bool", "bytes", "bytes4", "bytes32", "string");
190
189
  const ChainIdSchema = Schema.Number.pipe(Schema.int(), Schema.positive());
191
190
  const EVMAddressString = Schema.String.pipe(Schema.pattern(EVM_ADDRESS_HEX, { message: () => "expected a 0x-prefixed 20-byte EVM address" })).annotations({ description: "EVM address: 0x followed by 40 hex characters" });
192
- const HexBytesString = Schema.String.pipe(Schema.pattern(HEX_BYTES, { message: () => "expected 0x-prefixed hex of whole bytes" })).annotations({ description: "Hex bytes: 0x followed by an even number of hex characters" });
193
191
  const EpochMsSchema = Schema.Number.pipe(Schema.int(), Schema.between(-864e13, MAX_DATE_MS));
194
192
  const IntegerString = Schema.String.pipe(Schema.filter((value) => {
195
193
  if (!DECIMAL_UINT.test(value)) return "amount must be a decimal integer string";
@@ -304,10 +302,10 @@ const ContinuationIntentSchema = Schema.Struct({
304
302
  outcomes: Schema.NonEmptyArray(ContinuationOutcomeSchema),
305
303
  continuationFlow: Schema.optional(FlowSchema),
306
304
  validity: Schema.Struct({ expiresAtMs: EpochMsSchema }),
307
- perpetual: Schema.optional(Schema.Boolean),
308
305
  provider: Schema.optional(Schema.String),
309
306
  funding: Schema.optional(Schema.Literal("inline", "external")),
310
- refund: Schema.optional(EVMAddressString.pipe(Schema.filter((address) => !isZeroAddress(address), { message: () => "refund must not be the zero address" })))
307
+ refund: Schema.optional(EVMAddressString.pipe(Schema.filter((address) => !isZeroAddress(address), { message: () => "refund must not be the zero address" }))),
308
+ exact: Schema.optional(Schema.Boolean)
311
309
  });
312
310
  const HexStringSchema = Schema.String.pipe(Schema.startsWith("0x"));
313
311
  const Phase1EscrowSchema = Schema.Struct({
@@ -321,6 +319,16 @@ const Phase1EscrowSchema = Schema.Struct({
321
319
  refund: HexStringSchema,
322
320
  expiresAtMs: Schema.Number.pipe(Schema.int(), Schema.positive())
323
321
  });
322
+ const Phase1BindingSchema = Schema.Struct({
323
+ executionTarget: HexStringSchema,
324
+ payload: HexStringSchema,
325
+ payloadHash: HexStringSchema,
326
+ calldata: HexStringSchema,
327
+ approvals: Schema.Array(Schema.Struct({
328
+ token: HexStringSchema,
329
+ spender: HexStringSchema
330
+ }))
331
+ });
324
332
  const Phase1ArtifactSchema = Schema.Union(Schema.Struct({
325
333
  kind: Schema.Literal("transaction"),
326
334
  funding: Schema.Literal("inline", "external", "delivered"),
@@ -330,7 +338,8 @@ const Phase1ArtifactSchema = Schema.Union(Schema.Struct({
330
338
  value: Schema.String,
331
339
  chainId: Schema.Number
332
340
  })),
333
- escrow: Schema.optional(Phase1EscrowSchema)
341
+ escrow: Schema.optional(Phase1EscrowSchema),
342
+ binding: Schema.optional(Phase1BindingSchema)
334
343
  }), Schema.Struct({
335
344
  kind: Schema.Literal("signables"),
336
345
  typedData: Schema.Array(Schema.Unknown)
@@ -340,22 +349,23 @@ const Erc20BalanceGteSpecSchema = Schema.Struct({
340
349
  kind: Schema.Literal("erc20BalanceGte"),
341
350
  chainId: ChainIdSchema,
342
351
  token: EVMAddressString,
343
- owner: EVMAddressString,
352
+ owner: AssertionOwnerSchema,
344
353
  minAmount: IntegerString
345
354
  });
346
355
  const NativeBalanceGteSpecSchema = Schema.Struct({
347
356
  kind: Schema.Literal("nativeBalanceGte"),
348
357
  chainId: ChainIdSchema,
349
- owner: EVMAddressString,
358
+ owner: AssertionOwnerSchema,
350
359
  minAmount: IntegerString
351
360
  });
352
361
  const CallCheckSpecSchema = Schema.Struct({
353
362
  kind: Schema.Literal("call"),
354
363
  chainId: ChainIdSchema,
355
364
  to: EVMAddressString,
356
- calldata: HexBytesString,
365
+ signature: Schema.String,
366
+ args: Schema.Array(Schema.String),
357
367
  comparator: Schema.Literal("gte", "eq", "lte"),
358
- value: IntegerString
368
+ threshold: IntegerString
359
369
  });
360
370
  const asErc20BalanceGteCheck = (check, token) => ({
361
371
  kind: "erc20BalanceGte",
@@ -372,39 +382,12 @@ const decodeNativeBalanceGte = (check, ast) => {
372
382
  case "reject": return ParseResult.fail(new ParseResult.Type(ast, check, policy.reason));
373
383
  }
374
384
  };
375
- const Erc20BalanceDeltaGteSpecSchema = Schema.Struct({
376
- kind: Schema.Literal("erc20BalanceDeltaGte"),
377
- chainId: ChainIdSchema,
378
- token: EVMAddressString,
379
- owner: AssertionOwnerSchema,
380
- minDelta: IntegerString
381
- });
382
- const NativeBalanceDeltaGteSpecSchema = Schema.Struct({
383
- kind: Schema.Literal("nativeBalanceDeltaGte"),
384
- chainId: ChainIdSchema,
385
- owner: AssertionOwnerSchema,
386
- minDelta: IntegerString
387
- });
388
- const AssertionSpecSchema = Schema.Union(Erc20BalanceGteSpecSchema, NativeBalanceGteSpecSchema, CallCheckSpecSchema, Erc20BalanceDeltaGteSpecSchema, NativeBalanceDeltaGteSpecSchema);
385
+ const AssertionSpecSchema = Schema.Union(Erc20BalanceGteSpecSchema, NativeBalanceGteSpecSchema, CallCheckSpecSchema);
389
386
  const settledOutcome = (intent) => intent.outcomes[0];
390
387
  //#endregion
391
388
  //#region src/descriptor.ts
392
389
  const Bytes32HexSchema = Schema.String.pipe(Schema.pattern(BYTES32_LOWER_HEX));
393
- const AssertedErc20BalanceGteSpecSchema = Schema.Struct({
394
- kind: Schema.Literal("erc20BalanceGte"),
395
- chainId: ChainIdSchema,
396
- token: EVMAddressString,
397
- owner: AssertionOwnerSchema,
398
- minAmount: IntegerString
399
- });
400
- const AssertedNativeBalanceGteSpecSchema = Schema.Struct({
401
- kind: Schema.Literal("nativeBalanceGte"),
402
- chainId: ChainIdSchema,
403
- owner: AssertionOwnerSchema,
404
- minAmount: IntegerString
405
- });
406
- const RawAssertedPredicateSchema = Schema.Union(AssertedErc20BalanceGteSpecSchema, AssertedNativeBalanceGteSpecSchema, CallCheckSpecSchema, Erc20BalanceDeltaGteSpecSchema, NativeBalanceDeltaGteSpecSchema);
407
- const AssertedPredicateSchema = Schema.transformOrFail(RawAssertedPredicateSchema, Schema.typeSchema(RawAssertedPredicateSchema), {
390
+ const AssertedPredicateSchema = Schema.transformOrFail(AssertionSpecSchema, Schema.typeSchema(AssertionSpecSchema), {
408
391
  strict: true,
409
392
  decode: (pred, _options, ast) => pred.kind === "nativeBalanceGte" ? decodeNativeBalanceGte(pred, ast) : ParseResult.succeed(pred),
410
393
  encode: (pred) => ParseResult.succeed(pred)
@@ -748,13 +731,12 @@ const foldMaterialiserMetadata = (meta, cases) => {
748
731
  if (meta.kind === "exact") return cases.exact(meta.amount);
749
732
  if (meta.kind === "exact-native") return cases.exactNative(meta.amount);
750
733
  if (meta.kind === "capped") return cases.capped(meta.amount, meta.min);
751
- return cases.runtime();
734
+ return cases.runtime(meta.min);
752
735
  };
753
736
  //#endregion
754
737
  //#region src/zodSchemas.ts
755
738
  const chainIdZod = z.number().int().positive();
756
739
  const evmAddressZod = z.string().regex(EVM_ADDRESS_HEX);
757
- const hexBytesZod = z.string().regex(HEX_BYTES);
758
740
  const uintStringZod = z.string().refine((value) => DECIMAL_UINT.test(value) && BigInt(value) <= MAX_UINT256, { message: "expected a uint256 decimal integer string" });
759
741
  const SolTypeZod = z.enum([
760
742
  "uint8",
@@ -908,75 +890,53 @@ const SettlementEscrowZod = z.object({
908
890
  refund: hexStringZod,
909
891
  expiresAtMs: z.number().int().positive()
910
892
  });
893
+ const SettlementBindingZod = z.object({
894
+ executionTarget: hexStringZod,
895
+ payload: hexStringZod,
896
+ payloadHash: hexStringZod,
897
+ calldata: hexStringZod,
898
+ approvals: z.array(z.object({
899
+ token: hexStringZod,
900
+ spender: hexStringZod
901
+ })).readonly()
902
+ });
911
903
  const assertionOwnerZod = z.union([evmAddressZod, z.enum(["escrow", "delivery"])]);
912
904
  const AssertionSpecZod = z.discriminatedUnion("kind", [
913
905
  z.object({
914
906
  kind: z.literal("erc20BalanceGte"),
915
907
  chainId: chainIdZod,
916
908
  token: evmAddressZod,
917
- owner: evmAddressZod,
909
+ owner: assertionOwnerZod,
918
910
  minAmount: uintStringZod
919
911
  }),
920
912
  z.object({
921
913
  kind: z.literal("nativeBalanceGte"),
922
914
  chainId: chainIdZod,
923
- owner: evmAddressZod,
915
+ owner: assertionOwnerZod,
924
916
  minAmount: uintStringZod
925
917
  }),
926
918
  z.object({
927
919
  kind: z.literal("call"),
928
920
  chainId: chainIdZod,
929
921
  to: evmAddressZod,
930
- calldata: hexBytesZod,
922
+ signature: z.string(),
923
+ args: z.array(z.string()).readonly(),
931
924
  comparator: z.enum([
932
925
  "gte",
933
926
  "eq",
934
927
  "lte"
935
928
  ]),
936
- value: uintStringZod
937
- }),
938
- z.object({
939
- kind: z.literal("erc20BalanceDeltaGte"),
940
- chainId: z.number().int().positive(),
941
- token: evmAddressZod,
942
- owner: assertionOwnerZod,
943
- minDelta: uintStringZod
944
- }),
945
- z.object({
946
- kind: z.literal("nativeBalanceDeltaGte"),
947
- chainId: z.number().int().positive(),
948
- owner: assertionOwnerZod,
949
- minDelta: uintStringZod
929
+ threshold: uintStringZod
950
930
  })
951
931
  ]);
952
- const assertionSpecOptionByKind = (kind) => {
953
- const option = AssertionSpecZod.options.find((o) => o.shape.kind.value === kind);
954
- if (option === void 0) throw new Error(`AssertionSpecZod has no member with kind "${kind}"`);
955
- return option;
956
- };
957
- const AssertedPredicateZod = z.discriminatedUnion("kind", [
958
- z.object({
959
- kind: z.literal("erc20BalanceGte"),
960
- chainId: z.number().int().positive(),
961
- token: evmAddressZod,
962
- owner: assertionOwnerZod,
963
- minAmount: uintStringZod
964
- }),
965
- z.object({
966
- kind: z.literal("nativeBalanceGte"),
967
- chainId: z.number().int().positive(),
968
- owner: assertionOwnerZod,
969
- minAmount: uintStringZod
970
- }),
971
- assertionSpecOptionByKind("call"),
972
- assertionSpecOptionByKind("erc20BalanceDeltaGte"),
973
- assertionSpecOptionByKind("nativeBalanceDeltaGte")
974
- ]);
975
932
  const VerificationDescriptorZod = z.object({
976
933
  validationProgramHash: z.string().regex(BYTES32_LOWER_HEX),
977
934
  paramsHash: z.string().regex(BYTES32_LOWER_HEX),
978
- assertedPredicate: z.array(AssertedPredicateZod)
935
+ assertedPredicate: z.array(AssertionSpecZod).readonly()
936
+ });
937
+ const SettlementZod = z.object({
938
+ escrow: SettlementEscrowZod.optional(),
939
+ binding: SettlementBindingZod.optional()
979
940
  });
980
- const SettlementZod = z.object({ escrow: SettlementEscrowZod.optional() });
981
941
  //#endregion
982
- export { ARC_CHAIN_ID, ARC_NATIVE_ERC20, ARC_NATIVE_SCALE, AppliedGuardSchema, AssertedErc20BalanceGteSpecSchema, AssertedNativeBalanceGteSpecSchema, AssertedPredicateSchema, AssertedPredicateZod, AssertionOwnerSchema, AssertionSpecSchema, AssertionSpecZod, BindValueSchema, Bytes32HexSchema, COMPOSER_SDK_VERSION_HEADER, COMPOSE_VERSION_HEADER, CONTINUATION_COMMITMENT_OP_ID, CallCheckSpecSchema, CallSchema, CommittedOutcomeSchema, ComposeManifestZod, ContinuationIntentSchema, ContinuationOutcomeSchema, EVMAddressString, EVM_NATIVE_SENTINEL, EpilogueForwardSchema, EpilogueSchema, Erc20BalanceDeltaGteSpecSchema, Erc20BalanceGteSpecSchema, FlowInputSchema, FlowSchema, ForwardToSchema, GuardCompatibilityZod, GuardSelectorZod, HANDLE_UNITS, HandleInputSchema, HandlePortZod, HandleUnitsZod, HexStringSchema, InputPortZod, IntegerString, LineageSchema, LiteralBindingSchema, ManifestGuardZod, ManifestMaterialiserZod, ManifestOperationZod, ManifestPreconditionZod, ManifestRoutingZod, NativeBalanceDeltaGteSpecSchema, NativeBalanceGteSpecSchema, OutputPortZod, PROVIDER_KIND, Phase1ArtifactSchema, RESERVED_REF_SCOPES, RefSchema, ResourceInputSchema, ResourceOutputPortZod, ResourcePortZod, ResourceSchema, SIMULATE_MAX_REQUIREMENTS, SIMULATE_MAX_TRACKED_BALANCES, STATIC_SOL_TYPES, SettlementZod, SolTypeSchema, StaticSolTypeZod, TEMPO_CHAIN_ID, TEMPO_NATIVE_ERC20, UuidSchema, VerificationDescriptorSchema, VerificationDescriptorZod, canonicalAssertedPredicate, canonicalNativeAddress, checkCompatibility, copy, erc20, erc20Allowance, erc20Balance, erc20Resource, erc20Token, expandOutputPorts, familySize, flowInputMode, flowInputResource, flowInputType, foldChainCapabilities, foldMaterialiserMetadata, foldRef, foldResource, getChainCapabilities, handle, hasErc20CanonicalNative, instancePortName, isAsErc20Chain, isContextKey, isERC20Resource, isErc20AllowancePrecondition, isErc20BalancePrecondition, isFutureResourceOutput, isHandlePort, isMaterialiserInput, isMsgValueNative, isNativeAddressForChain, isNativeBalancePrecondition, isNativeResource, isOutputFamily, isRef, isResourceInput, isResourceOutputPort, isResourcePort, isStaticSolType, linear, native, nativeBalance, nativeCheckPolicy, nativeResource, normalizeNativeTokenAddress, normalizeResource, opHandle, parseRef, parseVersion, providerKindByName, providerKindNames, readResource, ref, refKey, resource, resourceKey, resourceOutput, resourceToken, resourcesEqual, settledOutcome };
942
+ export { ARC_CHAIN_ID, ARC_NATIVE_ERC20, ARC_NATIVE_SCALE, AppliedGuardSchema, AssertedPredicateSchema, AssertionOwnerSchema, AssertionSpecSchema, AssertionSpecZod, BindValueSchema, Bytes32HexSchema, COMPOSER_SDK_VERSION_HEADER, COMPOSE_VERSION_HEADER, CONTINUATION_COMMITMENT_OP_ID, CallCheckSpecSchema, CallSchema, CommittedOutcomeSchema, ComposeManifestZod, ContinuationIntentSchema, ContinuationOutcomeSchema, EVMAddressString, EVM_NATIVE_SENTINEL, EpilogueForwardSchema, EpilogueSchema, Erc20BalanceGteSpecSchema, FlowInputSchema, FlowSchema, ForwardToSchema, GuardCompatibilityZod, GuardSelectorZod, HANDLE_UNITS, HandleInputSchema, HandlePortZod, HandleUnitsZod, HexStringSchema, InputPortZod, IntegerString, LineageSchema, LiteralBindingSchema, ManifestGuardZod, ManifestMaterialiserZod, ManifestOperationZod, ManifestPreconditionZod, ManifestRoutingZod, NativeBalanceGteSpecSchema, OutputPortZod, PROVIDER_KIND, Phase1ArtifactSchema, RESERVED_REF_SCOPES, RefSchema, ResourceInputSchema, ResourceOutputPortZod, ResourcePortZod, ResourceSchema, SIMULATE_MAX_REQUIREMENTS, SIMULATE_MAX_TRACKED_BALANCES, STATIC_SOL_TYPES, SettlementZod, SolTypeSchema, StaticSolTypeZod, TEMPO_CHAIN_ID, TEMPO_NATIVE_ERC20, UuidSchema, VerificationDescriptorSchema, VerificationDescriptorZod, canonicalAssertedPredicate, canonicalNativeAddress, checkCompatibility, copy, erc20, erc20Allowance, erc20Balance, erc20Resource, erc20Token, expandOutputPorts, familySize, flowInputMode, flowInputResource, flowInputType, foldChainCapabilities, foldMaterialiserMetadata, foldRef, foldResource, getChainCapabilities, handle, hasErc20CanonicalNative, instancePortName, isAsErc20Chain, isContextKey, isERC20Resource, isErc20AllowancePrecondition, isErc20BalancePrecondition, isFutureResourceOutput, isHandlePort, isMaterialiserInput, isMsgValueNative, isNativeAddressForChain, isNativeBalancePrecondition, isNativeResource, isOutputFamily, isRef, isResourceInput, isResourceOutputPort, isResourcePort, isStaticSolType, linear, native, nativeBalance, nativeCheckPolicy, nativeResource, normalizeNativeTokenAddress, normalizeResource, opHandle, parseRef, parseVersion, providerKindByName, providerKindNames, readResource, ref, refKey, resource, resourceKey, resourceOutput, resourceToken, resourcesEqual, settledOutcome };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@lifi/compose-spec",
3
- "version": "0.11.3",
3
+ "version": "0.12.0",
4
4
  "description": "Public wire-format types and schemas for Compose flows",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {
package/src/compile.ts CHANGED
@@ -13,7 +13,6 @@ export interface ComposeRun {
13
13
  readonly signer: string;
14
14
  readonly assumptions?: Record<string, bigint>;
15
15
  readonly referrer?: string;
16
- readonly integratorFeeBps?: number;
17
16
  readonly maxPriceImpactBps?: number;
18
17
  // Sugar for `flow.epilogue.remainder`; zap-backend desugars it before the
19
18
  // compile.
@@ -121,22 +120,6 @@ export interface SpendEntry {
121
120
  readonly nodeId?: string;
122
121
  }
123
122
 
124
- // One fee row per (input, recipient), as the compiled fill charges it.
125
- // Hand-mirrored from api-schemas' `ComposeFeeSchema` (the OpenAPI source of
126
- // truth; this package cannot depend on it). `recipient` names WHO is charged
127
- // — never an address; the address is the sibling `recipientAddress`. `amount`
128
- // is absent when the gross is only known on-chain at execution time (a
129
- // balance-materialiser input).
130
- export interface ComposeFee {
131
- readonly input: string;
132
- // Zero address for native, otherwise the ERC-20 contract.
133
- readonly token: string;
134
- readonly recipient: 'lifi' | 'integrator';
135
- readonly recipientAddress: string;
136
- readonly bps: number;
137
- readonly amount?: string;
138
- }
139
-
140
123
  // The optional user-program simulation result, present only when the request
141
124
  // opted in via `run.simulateUserProgram` and the simulation succeeded.
142
125
  // Hand-mirrored from api-schemas' `ComposeUserProgramSimulationOkSchema`.
@@ -204,9 +187,6 @@ export interface ComposeCompileSuccessData extends ComposeContinuationData {
204
187
  readonly userProxy: string;
205
188
  readonly priceImpact?: PriceImpact;
206
189
  readonly approvals?: readonly ApprovalEntry[];
207
- // The per-(input, recipient) fee rows the compiled fill charges. Absent when
208
- // no fee applies.
209
- readonly fees?: readonly ComposeFee[];
210
190
  // The optional user-program simulation echo, present only when the request
211
191
  // opted in via `run.simulateUserProgram` and the simulation succeeded.
212
192
  readonly userProgramSimulation?: ComposeUserProgramSimulation;
@@ -235,9 +215,6 @@ export interface ComposeCompilePartialData extends ComposeContinuationData {
235
215
  readonly simulationRevert: SimulationRevert;
236
216
  readonly approvals?: readonly ApprovalEntry[];
237
217
  readonly actions?: readonly ComposeAction[];
238
- // The per-(input, recipient) fee rows the compiled fill charges. Absent when
239
- // no fee applies.
240
- readonly fees?: readonly ComposeFee[];
241
218
  // The optional user-program simulation echo, present only when the request
242
219
  // opted in via `run.simulateUserProgram` and the simulation succeeded.
243
220
  readonly userProgramSimulation?: ComposeUserProgramSimulation;
@@ -10,7 +10,6 @@ import {
10
10
  EpochMsSchema,
11
11
  EVMAddressString,
12
12
  FlowSchema,
13
- HexBytesString,
14
13
  IntegerString,
15
14
  } from './flowSchema.js';
16
15
 
@@ -83,7 +82,7 @@ export const CommittedOutcomeSchema = normalizingOutcome(
83
82
  // Backend-neutral config for the `continuation.settle` op. Note: the funding
84
83
  // input is NOT a config field — the deferred step's funding resource/amount is
85
84
  // wired via the node's `bind.input` (see M3b). Only the committed terms below
86
- // (`outcomes`/`continuationFlow`/`validity`/`perpetual`/`provider`) are the
85
+ // (`outcomes`/`continuationFlow`/`validity`/`provider`) are the
87
86
  // node's `config`.
88
87
  //
89
88
  // `continuationFlow` is an inlined Flow document that the settlement backend
@@ -96,7 +95,6 @@ export const ContinuationIntentSchema = Schema.Struct({
96
95
  outcomes: Schema.NonEmptyArray(ContinuationOutcomeSchema),
97
96
  continuationFlow: Schema.optional(FlowSchema),
98
97
  validity: Schema.Struct({ expiresAtMs: EpochMsSchema }),
99
- perpetual: Schema.optional(Schema.Boolean),
100
98
  provider: Schema.optional(Schema.String),
101
99
  // Funding-path mode. The HTTP wire contract is documented by
102
100
  // `ComposeActionsSchema` in `@lifi/api-schemas`. A settle funded by a
@@ -112,12 +110,17 @@ export const ContinuationIntentSchema = Schema.Struct({
112
110
  }),
113
111
  ),
114
112
  ),
113
+ // Bind the settlement to the leg's compiled bytes: the fill runs exactly the
114
+ // calldata the compile proved, so the solver chooses nothing. Needs a
115
+ // `continuationFlow` and a provider that advertises the capability.
116
+ exact: Schema.optional(Schema.Boolean),
115
117
  });
116
118
 
117
119
  // A `0x`-prefixed string, prefix checked only. Continuation vocabulary no
118
120
  // longer uses it for addresses (those take `EVMAddressString`); it remains
119
- // for the escrow record below, which the settlement service returns, and for
120
- // op configs not yet tightened. `zodSchemas.ts` mirrors it as `hexStringZod`.
121
+ // for the escrow and binding records below, which the settlement service
122
+ // returns, and for op configs not yet tightened. `zodSchemas.ts` mirrors it
123
+ // as `hexStringZod`.
121
124
  export const HexStringSchema = Schema.String.pipe(Schema.startsWith('0x'));
122
125
 
123
126
  // The escrow a settlement provider registered for a settle node, disclosed on
@@ -126,9 +129,9 @@ export const HexStringSchema = Schema.String.pipe(Schema.startsWith('0x'));
126
129
  // providers that fund no escrow never set it. Every field is present whenever
127
130
  // the record is. Mirrored by `SettlementEscrowZod`.
128
131
  //
129
- // - `chainId` + `address` — the escrow and its chain. The escrow is keyed by
130
- // the funding user, so the pair identifies that user's escrow on the chain,
131
- // not one settlement.
132
+ // - `chainId` + `address` — the escrow and its chain. Every registration gets
133
+ // a fresh escrow, so the pair identifies this one settlement; never fund it
134
+ // for another.
132
135
  // - `token` + `amount` — the funding asset (native → `EVM_NATIVE_SENTINEL`)
133
136
  // and the raw amount the escrow was sized from. The program transfers the
134
137
  // amount realised at execution, which can differ when an upstream op
@@ -141,9 +144,8 @@ export const HexStringSchema = Schema.String.pipe(Schema.startsWith('0x'));
141
144
  // - `refund` — where the escrow balance returns when the settlement expires.
142
145
  // - `expiresAtMs` — when the settlement expires: the effective expiry the
143
146
  // settlement service stores, which can be earlier than the authored
144
- // `validity.expiresAtMs` or, for a re-registered perpetual escrow, the
145
- // existing escrow's expiry (later, or already past); after it the escrow is
146
- // never filled and its balance is refunded.
147
+ // `validity.expiresAtMs`; after it the escrow is never filled and its
148
+ // balance is refunded.
147
149
  const Phase1EscrowSchema = Schema.Struct({
148
150
  chainId: ChainIdSchema,
149
151
  address: HexStringSchema,
@@ -156,12 +158,34 @@ const Phase1EscrowSchema = Schema.Struct({
156
158
  expiresAtMs: Schema.Number.pipe(Schema.int(), Schema.positive()),
157
159
  });
158
160
 
159
- // Internal phase-1 artifact. The HTTP layer projects its `escrow` onto
160
- // `settlements` and publishes external-funding calldata and typed data through
161
- // `ComposeActionsSchema`. The internal `transactionRequest` remains optional
162
- // because inline funding does not produce a submittable transfer, and
163
- // `delivered` funding (a bridge delivers into the escrow) produces none
164
- // either.
161
+ // The executor binding of an `exact` settle, disclosed on the `transaction`
162
+ // artifact and projected onto the wire as `settlements[nodeId].binding`.
163
+ // Absent unless the settle is `exact`. Every field is present whenever the
164
+ // record is. Mirrored by `SettlementBindingZod`.
165
+ //
166
+ // - `executionTarget` — the executor that runs the fill.
167
+ // - `payload` — the executor call the settlement service hashed into the
168
+ // escrow's execute constraint; a fill that runs anything else is rejected.
169
+ // - `payloadHash` — `keccak256(payload)`, the committed hash.
170
+ // - `calldata` — what the executor's proxy runs: the leg's compiled bytes.
171
+ // - `approvals` — the allowances the executor grants before it runs
172
+ // `calldata`.
173
+ const Phase1BindingSchema = Schema.Struct({
174
+ executionTarget: HexStringSchema,
175
+ payload: HexStringSchema,
176
+ payloadHash: HexStringSchema,
177
+ calldata: HexStringSchema,
178
+ approvals: Schema.Array(
179
+ Schema.Struct({ token: HexStringSchema, spender: HexStringSchema }),
180
+ ),
181
+ });
182
+
183
+ // Internal phase-1 artifact. The HTTP layer projects its `escrow` and
184
+ // `binding` onto `settlements` and publishes external-funding calldata and
185
+ // typed data through `ComposeActionsSchema`. The internal `transactionRequest`
186
+ // remains optional because inline funding does not produce a submittable
187
+ // transfer, and `delivered` funding (a bridge delivers into the escrow)
188
+ // produces none either.
165
189
  export const Phase1ArtifactSchema = Schema.Union(
166
190
  Schema.Struct({
167
191
  kind: Schema.Literal('transaction'),
@@ -175,6 +199,7 @@ export const Phase1ArtifactSchema = Schema.Union(
175
199
  }),
176
200
  ),
177
201
  escrow: Schema.optional(Phase1EscrowSchema),
202
+ binding: Schema.optional(Phase1BindingSchema),
178
203
  }),
179
204
  Schema.Struct({
180
205
  kind: Schema.Literal('signables'),
@@ -183,29 +208,36 @@ export const Phase1ArtifactSchema = Schema.Union(
183
208
  Schema.Struct({ kind: Schema.Literal('none') }),
184
209
  );
185
210
 
186
- // The absolute assertion members of `AssertionSpec` below: each is a predicate
187
- // over on-chain state that a derived validation program enforces. Amounts are
188
- // decimal strings on the wire because JSON has no bigint.
211
+ // The members of `AssertionSpec` below: each is an absolute predicate over
212
+ // on-chain state that a derived validation program enforces at settlement.
213
+ // Every register operand of a member (an owner, a call argument, a threshold)
214
+ // becomes a committed validation param; the constants a member bakes into the
215
+ // program (a token, a call target, a function signature) are committed by the
216
+ // program hash. Amounts are decimal strings on the wire because JSON has no
217
+ // bigint.
189
218
  //
190
219
  // - `erc20BalanceGte` — `owner`'s balance of `token` on `chainId` is at least
191
220
  // `minAmount`.
192
221
  // - `nativeBalanceGte` — `owner`'s native balance on `chainId` is at least
193
222
  // `minAmount`.
194
- // - `call` — a generic `eth_call` to `to` with `calldata`, comparing the
195
- // returned value against `value` using `comparator`.
223
+ // - `call` — a static call to `to` on `chainId` of `signature` with `args`,
224
+ // whose `uint256` return compares against `threshold` using `comparator`.
196
225
  //
197
- // Addresses (`token`/`owner`/`to`) take `EVMAddressString`, `calldata` takes
198
- // `HexBytesString`, and amounts (`minAmount`/`value`, and `minDelta` below)
199
- // take `IntegerString`, so a malformed value fails at decode instead of in
200
- // lowering. Amounts are not positive-only: a persisted descriptor re-decodes
201
- // these members, and a zero threshold is well-formed (just vacuous).
226
+ // Addresses (`token`/`to`) take `EVMAddressString`, `owner` takes
227
+ // `AssertionOwnerSchema` (below), and amounts
228
+ // (`minAmount`/`threshold`) take `IntegerString`, so a malformed value fails at
229
+ // decode instead of in lowering. Amounts are not positive-only: a persisted
230
+ // descriptor re-decodes these members, and a zero threshold is well-formed
231
+ // (just vacuous).
202
232
 
203
- // A balance owner in a derivation-only assertion spec. Concrete addresses stay
204
- // hex; the two symbolic owners `"escrow"` / `"delivery"` are resolved to
205
- // validator-injected register handles at settlement time (see the
206
- // verified-continuations derivation). This widening applies ONLY to the
207
- // derivation-only delta members below — never to the three absolute members,
208
- // whose owner is always a concrete address once an invariant is captured.
233
+ // A balance owner: a concrete address, or one of the two symbolic owners
234
+ // `"escrow"` / `"delivery"`. The symbolic owners are thunk terms: a committed
235
+ // thunk carries one when it is assembled by hand (the uc1 fixtures) or echoed
236
+ // back from the commitment, and the derivation resolves each to a
237
+ // validator-injected register (see the verified-continuations derivation). An
238
+ // op's `asserts` hook cannot emit one: in compose-core its spec type is
239
+ // `AssertionSpecOf<H>`, so an owner is always an operand the hook received.
240
+ // The descriptor discloses the same values the program derives from.
209
241
  export const AssertionOwnerSchema = Schema.Union(
210
242
  EVMAddressString,
211
243
  Schema.Literal('escrow', 'delivery'),
@@ -213,51 +245,49 @@ export const AssertionOwnerSchema = Schema.Union(
213
245
  export type AssertionOwner = typeof AssertionOwnerSchema.Type;
214
246
 
215
247
  // The three absolute members are exported by name so `AssertionSpecSchema` and
216
- // the descriptor's predicate union can reuse them without re-declaring their
217
- // shape. Their `owner` is hex-only: a captured invariant always resolves to a
218
- // concrete address.
248
+ // the descriptor's predicate union share one declaration.
219
249
  export const Erc20BalanceGteSpecSchema = Schema.Struct({
220
250
  kind: Schema.Literal('erc20BalanceGte'),
221
251
  chainId: ChainIdSchema,
222
252
  token: EVMAddressString,
223
- owner: EVMAddressString,
253
+ owner: AssertionOwnerSchema,
224
254
  minAmount: IntegerString,
225
255
  });
226
256
 
227
257
  export const NativeBalanceGteSpecSchema = Schema.Struct({
228
258
  kind: Schema.Literal('nativeBalanceGte'),
229
259
  chainId: ChainIdSchema,
230
- owner: EVMAddressString,
260
+ owner: AssertionOwnerSchema,
231
261
  minAmount: IntegerString,
232
262
  });
233
263
 
264
+ // `signature` is the ethers human-readable form, e.g.
265
+ // `function balanceOf(address) returns (uint256)`, with exactly one `uint256`
266
+ // return and only `address` / `uint256` parameters. `args` has one entry per
267
+ // parameter, each written as that parameter's canonical string (a 20-byte hex
268
+ // address, a decimal integer). The derivation parses the signature once and
269
+ // rejects anything else; this schema is a shape check only.
234
270
  export const CallCheckSpecSchema = Schema.Struct({
235
271
  kind: Schema.Literal('call'),
236
272
  chainId: ChainIdSchema,
237
273
  to: EVMAddressString,
238
- calldata: HexBytesString,
274
+ signature: Schema.String,
275
+ args: Schema.Array(Schema.String),
239
276
  comparator: Schema.Literal('gte', 'eq', 'lte'),
240
- value: IntegerString,
277
+ threshold: IntegerString,
241
278
  });
242
279
 
243
- // The shape shared by the hex-owner `nativeBalanceGte` spec and the
244
- // descriptor's symbolic-owner variant. `owner` is `string` for both
245
- // (`AssertionOwnerSchema.Type` collapses to `string`).
246
- interface NativeBalanceGteLike {
247
- readonly kind: 'nativeBalanceGte';
248
- readonly chainId: number;
249
- readonly owner: string;
250
- readonly minAmount: string;
251
- }
280
+ type Erc20BalanceGteSpec = typeof Erc20BalanceGteSpecSchema.Type;
281
+ type NativeBalanceGteSpec = typeof NativeBalanceGteSpecSchema.Type;
252
282
 
253
283
  // The equivalent `erc20BalanceGte` of a `nativeBalanceGte` spec: `token` is
254
284
  // the chain's stand-in ERC-20 (PathUSD on Tempo), every other field carried
255
285
  // through.
256
286
  const asErc20BalanceGteCheck = (
257
- check: NativeBalanceGteLike,
287
+ check: NativeBalanceGteSpec,
258
288
  token: `0x${string}`,
259
- ) => ({
260
- kind: 'erc20BalanceGte' as const,
289
+ ): Erc20BalanceGteSpec => ({
290
+ kind: 'erc20BalanceGte',
261
291
  chainId: check.chainId,
262
292
  token,
263
293
  owner: check.owner,
@@ -270,11 +300,11 @@ const asErc20BalanceGteCheck = (
270
300
  // chain, and rejected on a `native-mirrored-erc20` chain. Used by the
271
301
  // descriptor's `AssertedPredicateSchema` so the disclosed and the committed
272
302
  // predicate derive the same program (authoring↔settlement hash parity).
273
- export const decodeNativeBalanceGte = <C extends NativeBalanceGteLike>(
274
- check: C,
303
+ export const decodeNativeBalanceGte = (
304
+ check: NativeBalanceGteSpec,
275
305
  ast: SchemaAST.AST,
276
306
  ): Effect.Effect<
277
- C | ReturnType<typeof asErc20BalanceGteCheck>,
307
+ NativeBalanceGteSpec | Erc20BalanceGteSpec,
278
308
  ParseResult.ParseIssue
279
309
  > => {
280
310
  const policy = nativeCheckPolicy(check.chainId);
@@ -291,36 +321,11 @@ export const decodeNativeBalanceGte = <C extends NativeBalanceGteLike>(
291
321
  // The derivation vocabulary (verified continuations, plan GD-1). An
292
322
  // `AssertionSpec` is the structured, backend-neutral form of one invariant a
293
323
  // derived validation program must enforce against the executor's re-quoted
294
- // fill. It extends the three absolute members above (reused verbatim) with two
295
- // derivation-only members. Amounts stay decimal strings on the wire.
296
- //
297
- // - `erc20BalanceDeltaGte` / `nativeBalanceDeltaGte` — `owner`'s post-fill
298
- // balance of `token` (native) on `chainId` must exceed its pre-fill balance
299
- // by at least `minDelta`. The settlement validator already checks each
300
- // committed outcome's floor itself, so the derivation lowers neither kind
301
- // into a program and rejects them as an authored invariant; they stay in
302
- // the vocabulary so a descriptor that carries one still decodes.
303
- export const Erc20BalanceDeltaGteSpecSchema = Schema.Struct({
304
- kind: Schema.Literal('erc20BalanceDeltaGte'),
305
- chainId: ChainIdSchema,
306
- token: EVMAddressString,
307
- owner: AssertionOwnerSchema,
308
- minDelta: IntegerString,
309
- });
310
-
311
- export const NativeBalanceDeltaGteSpecSchema = Schema.Struct({
312
- kind: Schema.Literal('nativeBalanceDeltaGte'),
313
- chainId: ChainIdSchema,
314
- owner: AssertionOwnerSchema,
315
- minDelta: IntegerString,
316
- });
317
-
324
+ // fill: one of the three members above, reused verbatim.
318
325
  export const AssertionSpecSchema = Schema.Union(
319
326
  Erc20BalanceGteSpecSchema,
320
327
  NativeBalanceGteSpecSchema,
321
328
  CallCheckSpecSchema,
322
- Erc20BalanceDeltaGteSpecSchema,
323
- NativeBalanceDeltaGteSpecSchema,
324
329
  );
325
330
 
326
331
  export type ContinuationOutcome = typeof ContinuationOutcomeSchema.Type;
@@ -328,6 +333,7 @@ export type CommittedOutcome = typeof CommittedOutcomeSchema.Type;
328
333
  export type ContinuationIntent = typeof ContinuationIntentSchema.Type;
329
334
  export type Phase1Artifact = typeof Phase1ArtifactSchema.Type;
330
335
  export type AssertionSpec = typeof AssertionSpecSchema.Type;
336
+ export type CallCheckSpec = typeof CallCheckSpecSchema.Type;
331
337
 
332
338
  // The outcome a `continuation.settle` node's single `output` port stands for.
333
339
  // The wire format admits several outcomes, but the op produces one resource,