@lifi/compose-spec 0.2.0-staging.5 → 0.2.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.cjs CHANGED
@@ -57,6 +57,8 @@ __export(index_exports, {
57
57
  ResourceOutputPortZod: () => ResourceOutputPortZod,
58
58
  ResourcePortZod: () => ResourcePortZod,
59
59
  ResourceSchema: () => ResourceSchema,
60
+ SIMULATE_MAX_REQUIREMENTS: () => SIMULATE_MAX_REQUIREMENTS,
61
+ SIMULATE_MAX_TRACKED_BALANCES: () => SIMULATE_MAX_TRACKED_BALANCES,
60
62
  STATIC_SOL_TYPES: () => STATIC_SOL_TYPES,
61
63
  SolTypeSchema: () => SolTypeSchema,
62
64
  StaticSolTypeZod: () => StaticSolTypeZod,
@@ -315,6 +317,10 @@ var refKey = (ref) => foldRef(parseRef(ref), {
315
317
  output: (node, port) => `output:${node}:${port}`
316
318
  });
317
319
 
320
+ // src/simulate.ts
321
+ var SIMULATE_MAX_TRACKED_BALANCES = 40;
322
+ var SIMULATE_MAX_REQUIREMENTS = 40;
323
+
318
324
  // src/materialiserMetadata.ts
319
325
  var foldMaterialiserMetadata = (meta, cases) => {
320
326
  if (meta.kind === "exact") return cases.exact(meta.amount);
@@ -483,6 +489,8 @@ var ComposeManifestZod = import_zod.default.object({
483
489
  ResourceOutputPortZod,
484
490
  ResourcePortZod,
485
491
  ResourceSchema,
492
+ SIMULATE_MAX_REQUIREMENTS,
493
+ SIMULATE_MAX_TRACKED_BALANCES,
486
494
  STATIC_SOL_TYPES,
487
495
  SolTypeSchema,
488
496
  StaticSolTypeZod,
package/dist/index.d.cts CHANGED
@@ -995,6 +995,172 @@ declare const foldRef: <R>(ref: ParsedRef, cases: {
995
995
  }) => R;
996
996
  declare const refKey: (ref: Ref) => string;
997
997
 
998
+ /**
999
+ * Canonical wire-format types for the standalone `POST /simulate` endpoint.
1000
+ *
1001
+ * `/simulate` takes a raw, pre-encoded transaction (a `to` address, hex `data`,
1002
+ * optional native `value`), funds a sender, runs it in one `eth_call`, and
1003
+ * reports the watched balances before and after, their signed deltas, and the
1004
+ * inner-call gas. Unlike `POST /compose`, its response body is **un-enveloped**:
1005
+ * `{ status, block, timestamp, ... }` lives at the top level (no `{ data }`
1006
+ * wrapper).
1007
+ *
1008
+ * These are the single source of truth for the request/response shapes. The
1009
+ * server-side Zod schemas in `@lifi/api-schemas` (`src/routes/simulate.ts`)
1010
+ * validate the same contract and are kept in lockstep by a compile-time
1011
+ * conformance assertion (`src/routes/simulate.typecheck.ts`).
1012
+ *
1013
+ * Mirrors the hand-authored style of `src/compile.ts`.
1014
+ */
1015
+ /**
1016
+ * Maximum number of watched `(token, owner)` pairs accepted by `POST /simulate`.
1017
+ *
1018
+ * The limit comes from the VM's hard register budget (~123 usable registers,
1019
+ * checked on the final ISA layout). Each pair costs two result registers — a
1020
+ * before-read and an after-read — that are both live at the closing abi-encode,
1021
+ * so the compiler cannot coalesce them; that `2 × N` is the cost that scales.
1022
+ * Token and owner address literals do not scale it, since constant-propagation
1023
+ * merges identical-valued literals into one register. The cap leaves headroom
1024
+ * for the inner-call / gas-measurement / abi-encode scaffolding.
1025
+ */
1026
+ declare const SIMULATE_MAX_TRACKED_BALANCES = 40;
1027
+ /**
1028
+ * Maximum number of funding `requirements` accepted by `POST /simulate`.
1029
+ *
1030
+ * Each requirement triggers a slot-discovery cycle (access-list probe + sentinel
1031
+ * verification + RPC round trips) in slot-finder, so an unbounded array lets a
1032
+ * single request amplify into arbitrary upstream RPC work. Bounded here at the
1033
+ * trust boundary and re-enforced server-side in `rawSimulation.ts`.
1034
+ */
1035
+ declare const SIMULATE_MAX_REQUIREMENTS = 40;
1036
+ /** A `(token, owner)` pair whose balance is watched across the simulation. */
1037
+ interface TrackedBalance {
1038
+ /** Token to watch (use the zero address for native balance). */
1039
+ readonly token: string;
1040
+ /** Account whose balance of `token` is watched. */
1041
+ readonly owner: string;
1042
+ }
1043
+ /**
1044
+ * Funding instruction: seed an ERC-20 balance on a wallet before simulation.
1045
+ * Amounts accept `bigint | string` — the SDK serialises `bigint` to a decimal
1046
+ * string; the string side covers values already stringified.
1047
+ */
1048
+ interface Erc20BalanceRequirement {
1049
+ readonly type: "Erc20Balance";
1050
+ readonly wallet: string;
1051
+ readonly token: string;
1052
+ readonly balance: bigint | string;
1053
+ }
1054
+ /** Funding instruction: seed a native balance on a wallet before simulation. */
1055
+ interface NativeBalanceRequirement {
1056
+ readonly type: "NativeBalance";
1057
+ readonly wallet: string;
1058
+ readonly balance: bigint | string;
1059
+ }
1060
+ /** Funding instruction: seed an ERC-20 allowance before simulation. */
1061
+ interface Erc20AllowanceRequirement {
1062
+ readonly type: "Erc20Allowance";
1063
+ readonly owner: string;
1064
+ readonly spender: string;
1065
+ readonly token: string;
1066
+ readonly allowance: bigint | string;
1067
+ }
1068
+ /**
1069
+ * The funding-instruction union applied before a simulation. Three variants,
1070
+ * discriminated by `type`.
1071
+ */
1072
+ type SlotFinderRequirement = Erc20BalanceRequirement | NativeBalanceRequirement | Erc20AllowanceRequirement;
1073
+ /** Request body for `POST /simulate`. */
1074
+ interface SimulateRequest {
1075
+ /** EVM chain id. */
1076
+ readonly chainId: number;
1077
+ /**
1078
+ * Sender of the simulated transaction. The VM bytecode is injected here so
1079
+ * the inner call carries `msg.sender == from`.
1080
+ */
1081
+ readonly from: string;
1082
+ /** Target contract of the raw transaction. */
1083
+ readonly to: string;
1084
+ /** Pre-encoded transaction calldata (`0x`-prefixed hex). */
1085
+ readonly data: string;
1086
+ /**
1087
+ * Native value (wei) sent with the inner call. Accepts `bigint | string`;
1088
+ * defaults to `"0"` server-side when omitted.
1089
+ */
1090
+ readonly value?: bigint | string;
1091
+ /**
1092
+ * Block number to simulate against. Omitted ⇒ the chain head. Named tags
1093
+ * (e.g. "latest") are rejected with HTTP 400.
1094
+ */
1095
+ readonly block?: number;
1096
+ /** Funding instructions applied before simulation (max 40). */
1097
+ readonly requirements?: readonly SlotFinderRequirement[];
1098
+ /** Balances to read before and after the transaction (1–40 pairs). */
1099
+ readonly trackedBalances: readonly TrackedBalance[];
1100
+ }
1101
+ /**
1102
+ * One watched balance in a simulation response. `amount` is a decimal string;
1103
+ * for `deltas` it is signed (`after - before`).
1104
+ */
1105
+ interface SimulateBalanceEntry {
1106
+ readonly token: string;
1107
+ readonly owner: string;
1108
+ readonly amount: string;
1109
+ }
1110
+ /**
1111
+ * HTTP 200, `status: "ok"`: the simulation ran successfully. Balance arrays are
1112
+ * ordered to match the request `trackedBalances`. `gasUsed` is inner-call
1113
+ * execution gas only.
1114
+ *
1115
+ * Note: the array element types are intentionally mutable (`SimulateBalanceEntry[]`,
1116
+ * not `readonly SimulateBalanceEntry[]`) so they stay structurally identical to
1117
+ * the Zod-inferred wire types, which `z.array(...)` infers as mutable `T[]`. The
1118
+ * bidirectional conformance assertion in `@lifi/api-schemas` relies on this.
1119
+ */
1120
+ interface SimulateOkResult {
1121
+ readonly status: "ok";
1122
+ readonly block: number;
1123
+ readonly timestamp: number;
1124
+ readonly balancesBefore: SimulateBalanceEntry[];
1125
+ readonly balancesAfter: SimulateBalanceEntry[];
1126
+ readonly deltas: SimulateBalanceEntry[];
1127
+ readonly gasUsed: string;
1128
+ }
1129
+ /** Decoded revert diagnostics, when slot-finder can parse the revert reason. */
1130
+ interface SimulateRevertDecodeResult {
1131
+ readonly errorCandidates?: {
1132
+ readonly decodedErrorSignature: string;
1133
+ readonly decodedParams: string[];
1134
+ }[];
1135
+ readonly error?: string;
1136
+ }
1137
+ /**
1138
+ * HTTP 200, `status: "revert"`: the simulation ran but the transaction reverted
1139
+ * on-chain. A revert is a *successful simulation*, not a transport error.
1140
+ */
1141
+ interface SimulateRevertResult {
1142
+ readonly status: "revert";
1143
+ readonly block: number;
1144
+ readonly timestamp: number;
1145
+ readonly revertReason?: string;
1146
+ readonly code?: number;
1147
+ readonly rawErrorBytes?: string;
1148
+ readonly decodeResult?: SimulateRevertDecodeResult;
1149
+ }
1150
+ /**
1151
+ * HTTP 422, `status: "error"`: the request was well-formed but the simulation
1152
+ * could not be set up or run. `message` is intentionally generic.
1153
+ */
1154
+ interface SimulateSetupErrorResult {
1155
+ readonly status: "error";
1156
+ readonly message: string;
1157
+ }
1158
+ /**
1159
+ * Discriminated result of `POST /simulate`. `switch (result.status)` narrows to
1160
+ * one member: `ok` and `revert` come back with HTTP 200, `error` with HTTP 422.
1161
+ */
1162
+ type SimulateResult = SimulateOkResult | SimulateRevertResult | SimulateSetupErrorResult;
1163
+
998
1164
  type MaterialiserMetadata = {
999
1165
  readonly kind: 'exact';
1000
1166
  readonly amount: bigint;
@@ -1014,4 +1180,4 @@ declare const foldMaterialiserMetadata: <R>(meta: MaterialiserMetadata, cases: {
1014
1180
  readonly runtime: () => R;
1015
1181
  }) => R;
1016
1182
 
1017
- export { type AppliedGuard, AppliedGuardSchema, type ApprovalEntry, type Availability, type BindValue, BindValueSchema, type Call, CallSchema, type ComposeCompilePartialData, type ComposeCompileRequest, type ComposeCompileResult, type ComposeCompileSuccessData, type ComposeContinuation, type ComposeError, type ComposeErrorKind, type ComposeManifest, ComposeManifestZod, type ComposeRun, type ComposeTransactionRequest, type ContextKey, type Continuation, ContinuationSchema, type FailedPreparedOp, type FlashloanMaterialiserInput, type Flow, type FlowInput, FlowInputSchema, FlowSchema, type GenericComposeError, type GenericComposeErrorKind, type GuardCompatibility, GuardCompatibilityZod, type GuardSelector, GuardSelectorZod, HANDLE_UNITS, type HandleInput, HandleInputSchema, type HandlePort, HandlePortZod, type HandleUnits, HandleUnitsZod, InputPortZod, type InputSpec, type LiteralBinding, LiteralBindingSchema, type ManifestGuard, ManifestGuardZod, type ManifestMaterialiser, ManifestMaterialiserZod, type ManifestOperation, ManifestOperationZod, type ManifestPrecondition, ManifestPreconditionZod, type MaterialiserConfigOf, type MaterialiserInput, type MaterialiserInputBase, type MaterialiserInputOf, type MaterialiserMetadata, type MaterialiserResolution, type OpInputPort, type OpOutputPort, type OutputAmount, OutputPortZod, PROVIDER_KIND, type ParsedRef, type Port, type Precondition, type PreconditionBase, type PreconditionConfigOf, type PreconditionOf, type PreparationComposeError, type PriceImpact, type ProducedResource, type ProviderKindName, RESERVED_REF_SCOPES, type Ref, RefSchema, type RefScope, type Resource, type ResourceInput, ResourceInputSchema, type ResourceOutputPort, ResourceOutputPortZod, type ResourcePort, ResourcePortZod, ResourceSchema, STATIC_SOL_TYPES, type SimulatedAmounts, type SimulationPolicy, type SimulationRevert, type SimulationRevertComposeError, type SolType, SolTypeSchema, type StaticSolType, StaticSolTypeZod, type SweepTo, copy, erc20, erc20Resource, erc20Token, flowInputMode, flowInputResource, flowInputType, foldMaterialiserMetadata, foldRef, foldResource, handle, inputRef, isContextKey, isERC20Resource, isHandlePort, isMaterialiserInput, isNativeResource, isRef, isResourceInput, isResourceOutputPort, isResourcePort, isStaticSolType, linear, native, nativeResource, opHandle, outputRef, parseRef, providerKindByName, providerKindNames, readResource, refKey, resource, resourceKey, resourceOutput, resourcesEqual };
1183
+ export { type AppliedGuard, AppliedGuardSchema, type ApprovalEntry, type Availability, type BindValue, BindValueSchema, type Call, CallSchema, type ComposeCompilePartialData, type ComposeCompileRequest, type ComposeCompileResult, type ComposeCompileSuccessData, type ComposeContinuation, type ComposeError, type ComposeErrorKind, type ComposeManifest, ComposeManifestZod, type ComposeRun, type ComposeTransactionRequest, type ContextKey, type Continuation, ContinuationSchema, type Erc20AllowanceRequirement, type Erc20BalanceRequirement, type FailedPreparedOp, type FlashloanMaterialiserInput, type Flow, type FlowInput, FlowInputSchema, FlowSchema, type GenericComposeError, type GenericComposeErrorKind, type GuardCompatibility, GuardCompatibilityZod, type GuardSelector, GuardSelectorZod, HANDLE_UNITS, type HandleInput, HandleInputSchema, type HandlePort, HandlePortZod, type HandleUnits, HandleUnitsZod, InputPortZod, type InputSpec, type LiteralBinding, LiteralBindingSchema, type ManifestGuard, ManifestGuardZod, type ManifestMaterialiser, ManifestMaterialiserZod, type ManifestOperation, ManifestOperationZod, type ManifestPrecondition, ManifestPreconditionZod, type MaterialiserConfigOf, type MaterialiserInput, type MaterialiserInputBase, type MaterialiserInputOf, type MaterialiserMetadata, type MaterialiserResolution, type NativeBalanceRequirement, type OpInputPort, type OpOutputPort, type OutputAmount, OutputPortZod, PROVIDER_KIND, type ParsedRef, type Port, type Precondition, type PreconditionBase, type PreconditionConfigOf, type PreconditionOf, type PreparationComposeError, type PriceImpact, type ProducedResource, type ProviderKindName, RESERVED_REF_SCOPES, type Ref, RefSchema, type RefScope, type Resource, type ResourceInput, ResourceInputSchema, type ResourceOutputPort, ResourceOutputPortZod, type ResourcePort, ResourcePortZod, ResourceSchema, SIMULATE_MAX_REQUIREMENTS, SIMULATE_MAX_TRACKED_BALANCES, STATIC_SOL_TYPES, type SimulateBalanceEntry, type SimulateOkResult, type SimulateRequest, type SimulateResult, type SimulateRevertDecodeResult, type SimulateRevertResult, type SimulateSetupErrorResult, type SimulatedAmounts, type SimulationPolicy, type SimulationRevert, type SimulationRevertComposeError, type SlotFinderRequirement, type SolType, SolTypeSchema, type StaticSolType, StaticSolTypeZod, type SweepTo, type TrackedBalance, copy, erc20, erc20Resource, erc20Token, flowInputMode, flowInputResource, flowInputType, foldMaterialiserMetadata, foldRef, foldResource, handle, inputRef, isContextKey, isERC20Resource, isHandlePort, isMaterialiserInput, isNativeResource, isRef, isResourceInput, isResourceOutputPort, isResourcePort, isStaticSolType, linear, native, nativeResource, opHandle, outputRef, parseRef, providerKindByName, providerKindNames, readResource, refKey, resource, resourceKey, resourceOutput, resourcesEqual };
package/dist/index.d.ts CHANGED
@@ -995,6 +995,172 @@ declare const foldRef: <R>(ref: ParsedRef, cases: {
995
995
  }) => R;
996
996
  declare const refKey: (ref: Ref) => string;
997
997
 
998
+ /**
999
+ * Canonical wire-format types for the standalone `POST /simulate` endpoint.
1000
+ *
1001
+ * `/simulate` takes a raw, pre-encoded transaction (a `to` address, hex `data`,
1002
+ * optional native `value`), funds a sender, runs it in one `eth_call`, and
1003
+ * reports the watched balances before and after, their signed deltas, and the
1004
+ * inner-call gas. Unlike `POST /compose`, its response body is **un-enveloped**:
1005
+ * `{ status, block, timestamp, ... }` lives at the top level (no `{ data }`
1006
+ * wrapper).
1007
+ *
1008
+ * These are the single source of truth for the request/response shapes. The
1009
+ * server-side Zod schemas in `@lifi/api-schemas` (`src/routes/simulate.ts`)
1010
+ * validate the same contract and are kept in lockstep by a compile-time
1011
+ * conformance assertion (`src/routes/simulate.typecheck.ts`).
1012
+ *
1013
+ * Mirrors the hand-authored style of `src/compile.ts`.
1014
+ */
1015
+ /**
1016
+ * Maximum number of watched `(token, owner)` pairs accepted by `POST /simulate`.
1017
+ *
1018
+ * The limit comes from the VM's hard register budget (~123 usable registers,
1019
+ * checked on the final ISA layout). Each pair costs two result registers — a
1020
+ * before-read and an after-read — that are both live at the closing abi-encode,
1021
+ * so the compiler cannot coalesce them; that `2 × N` is the cost that scales.
1022
+ * Token and owner address literals do not scale it, since constant-propagation
1023
+ * merges identical-valued literals into one register. The cap leaves headroom
1024
+ * for the inner-call / gas-measurement / abi-encode scaffolding.
1025
+ */
1026
+ declare const SIMULATE_MAX_TRACKED_BALANCES = 40;
1027
+ /**
1028
+ * Maximum number of funding `requirements` accepted by `POST /simulate`.
1029
+ *
1030
+ * Each requirement triggers a slot-discovery cycle (access-list probe + sentinel
1031
+ * verification + RPC round trips) in slot-finder, so an unbounded array lets a
1032
+ * single request amplify into arbitrary upstream RPC work. Bounded here at the
1033
+ * trust boundary and re-enforced server-side in `rawSimulation.ts`.
1034
+ */
1035
+ declare const SIMULATE_MAX_REQUIREMENTS = 40;
1036
+ /** A `(token, owner)` pair whose balance is watched across the simulation. */
1037
+ interface TrackedBalance {
1038
+ /** Token to watch (use the zero address for native balance). */
1039
+ readonly token: string;
1040
+ /** Account whose balance of `token` is watched. */
1041
+ readonly owner: string;
1042
+ }
1043
+ /**
1044
+ * Funding instruction: seed an ERC-20 balance on a wallet before simulation.
1045
+ * Amounts accept `bigint | string` — the SDK serialises `bigint` to a decimal
1046
+ * string; the string side covers values already stringified.
1047
+ */
1048
+ interface Erc20BalanceRequirement {
1049
+ readonly type: "Erc20Balance";
1050
+ readonly wallet: string;
1051
+ readonly token: string;
1052
+ readonly balance: bigint | string;
1053
+ }
1054
+ /** Funding instruction: seed a native balance on a wallet before simulation. */
1055
+ interface NativeBalanceRequirement {
1056
+ readonly type: "NativeBalance";
1057
+ readonly wallet: string;
1058
+ readonly balance: bigint | string;
1059
+ }
1060
+ /** Funding instruction: seed an ERC-20 allowance before simulation. */
1061
+ interface Erc20AllowanceRequirement {
1062
+ readonly type: "Erc20Allowance";
1063
+ readonly owner: string;
1064
+ readonly spender: string;
1065
+ readonly token: string;
1066
+ readonly allowance: bigint | string;
1067
+ }
1068
+ /**
1069
+ * The funding-instruction union applied before a simulation. Three variants,
1070
+ * discriminated by `type`.
1071
+ */
1072
+ type SlotFinderRequirement = Erc20BalanceRequirement | NativeBalanceRequirement | Erc20AllowanceRequirement;
1073
+ /** Request body for `POST /simulate`. */
1074
+ interface SimulateRequest {
1075
+ /** EVM chain id. */
1076
+ readonly chainId: number;
1077
+ /**
1078
+ * Sender of the simulated transaction. The VM bytecode is injected here so
1079
+ * the inner call carries `msg.sender == from`.
1080
+ */
1081
+ readonly from: string;
1082
+ /** Target contract of the raw transaction. */
1083
+ readonly to: string;
1084
+ /** Pre-encoded transaction calldata (`0x`-prefixed hex). */
1085
+ readonly data: string;
1086
+ /**
1087
+ * Native value (wei) sent with the inner call. Accepts `bigint | string`;
1088
+ * defaults to `"0"` server-side when omitted.
1089
+ */
1090
+ readonly value?: bigint | string;
1091
+ /**
1092
+ * Block number to simulate against. Omitted ⇒ the chain head. Named tags
1093
+ * (e.g. "latest") are rejected with HTTP 400.
1094
+ */
1095
+ readonly block?: number;
1096
+ /** Funding instructions applied before simulation (max 40). */
1097
+ readonly requirements?: readonly SlotFinderRequirement[];
1098
+ /** Balances to read before and after the transaction (1–40 pairs). */
1099
+ readonly trackedBalances: readonly TrackedBalance[];
1100
+ }
1101
+ /**
1102
+ * One watched balance in a simulation response. `amount` is a decimal string;
1103
+ * for `deltas` it is signed (`after - before`).
1104
+ */
1105
+ interface SimulateBalanceEntry {
1106
+ readonly token: string;
1107
+ readonly owner: string;
1108
+ readonly amount: string;
1109
+ }
1110
+ /**
1111
+ * HTTP 200, `status: "ok"`: the simulation ran successfully. Balance arrays are
1112
+ * ordered to match the request `trackedBalances`. `gasUsed` is inner-call
1113
+ * execution gas only.
1114
+ *
1115
+ * Note: the array element types are intentionally mutable (`SimulateBalanceEntry[]`,
1116
+ * not `readonly SimulateBalanceEntry[]`) so they stay structurally identical to
1117
+ * the Zod-inferred wire types, which `z.array(...)` infers as mutable `T[]`. The
1118
+ * bidirectional conformance assertion in `@lifi/api-schemas` relies on this.
1119
+ */
1120
+ interface SimulateOkResult {
1121
+ readonly status: "ok";
1122
+ readonly block: number;
1123
+ readonly timestamp: number;
1124
+ readonly balancesBefore: SimulateBalanceEntry[];
1125
+ readonly balancesAfter: SimulateBalanceEntry[];
1126
+ readonly deltas: SimulateBalanceEntry[];
1127
+ readonly gasUsed: string;
1128
+ }
1129
+ /** Decoded revert diagnostics, when slot-finder can parse the revert reason. */
1130
+ interface SimulateRevertDecodeResult {
1131
+ readonly errorCandidates?: {
1132
+ readonly decodedErrorSignature: string;
1133
+ readonly decodedParams: string[];
1134
+ }[];
1135
+ readonly error?: string;
1136
+ }
1137
+ /**
1138
+ * HTTP 200, `status: "revert"`: the simulation ran but the transaction reverted
1139
+ * on-chain. A revert is a *successful simulation*, not a transport error.
1140
+ */
1141
+ interface SimulateRevertResult {
1142
+ readonly status: "revert";
1143
+ readonly block: number;
1144
+ readonly timestamp: number;
1145
+ readonly revertReason?: string;
1146
+ readonly code?: number;
1147
+ readonly rawErrorBytes?: string;
1148
+ readonly decodeResult?: SimulateRevertDecodeResult;
1149
+ }
1150
+ /**
1151
+ * HTTP 422, `status: "error"`: the request was well-formed but the simulation
1152
+ * could not be set up or run. `message` is intentionally generic.
1153
+ */
1154
+ interface SimulateSetupErrorResult {
1155
+ readonly status: "error";
1156
+ readonly message: string;
1157
+ }
1158
+ /**
1159
+ * Discriminated result of `POST /simulate`. `switch (result.status)` narrows to
1160
+ * one member: `ok` and `revert` come back with HTTP 200, `error` with HTTP 422.
1161
+ */
1162
+ type SimulateResult = SimulateOkResult | SimulateRevertResult | SimulateSetupErrorResult;
1163
+
998
1164
  type MaterialiserMetadata = {
999
1165
  readonly kind: 'exact';
1000
1166
  readonly amount: bigint;
@@ -1014,4 +1180,4 @@ declare const foldMaterialiserMetadata: <R>(meta: MaterialiserMetadata, cases: {
1014
1180
  readonly runtime: () => R;
1015
1181
  }) => R;
1016
1182
 
1017
- export { type AppliedGuard, AppliedGuardSchema, type ApprovalEntry, type Availability, type BindValue, BindValueSchema, type Call, CallSchema, type ComposeCompilePartialData, type ComposeCompileRequest, type ComposeCompileResult, type ComposeCompileSuccessData, type ComposeContinuation, type ComposeError, type ComposeErrorKind, type ComposeManifest, ComposeManifestZod, type ComposeRun, type ComposeTransactionRequest, type ContextKey, type Continuation, ContinuationSchema, type FailedPreparedOp, type FlashloanMaterialiserInput, type Flow, type FlowInput, FlowInputSchema, FlowSchema, type GenericComposeError, type GenericComposeErrorKind, type GuardCompatibility, GuardCompatibilityZod, type GuardSelector, GuardSelectorZod, HANDLE_UNITS, type HandleInput, HandleInputSchema, type HandlePort, HandlePortZod, type HandleUnits, HandleUnitsZod, InputPortZod, type InputSpec, type LiteralBinding, LiteralBindingSchema, type ManifestGuard, ManifestGuardZod, type ManifestMaterialiser, ManifestMaterialiserZod, type ManifestOperation, ManifestOperationZod, type ManifestPrecondition, ManifestPreconditionZod, type MaterialiserConfigOf, type MaterialiserInput, type MaterialiserInputBase, type MaterialiserInputOf, type MaterialiserMetadata, type MaterialiserResolution, type OpInputPort, type OpOutputPort, type OutputAmount, OutputPortZod, PROVIDER_KIND, type ParsedRef, type Port, type Precondition, type PreconditionBase, type PreconditionConfigOf, type PreconditionOf, type PreparationComposeError, type PriceImpact, type ProducedResource, type ProviderKindName, RESERVED_REF_SCOPES, type Ref, RefSchema, type RefScope, type Resource, type ResourceInput, ResourceInputSchema, type ResourceOutputPort, ResourceOutputPortZod, type ResourcePort, ResourcePortZod, ResourceSchema, STATIC_SOL_TYPES, type SimulatedAmounts, type SimulationPolicy, type SimulationRevert, type SimulationRevertComposeError, type SolType, SolTypeSchema, type StaticSolType, StaticSolTypeZod, type SweepTo, copy, erc20, erc20Resource, erc20Token, flowInputMode, flowInputResource, flowInputType, foldMaterialiserMetadata, foldRef, foldResource, handle, inputRef, isContextKey, isERC20Resource, isHandlePort, isMaterialiserInput, isNativeResource, isRef, isResourceInput, isResourceOutputPort, isResourcePort, isStaticSolType, linear, native, nativeResource, opHandle, outputRef, parseRef, providerKindByName, providerKindNames, readResource, refKey, resource, resourceKey, resourceOutput, resourcesEqual };
1183
+ export { type AppliedGuard, AppliedGuardSchema, type ApprovalEntry, type Availability, type BindValue, BindValueSchema, type Call, CallSchema, type ComposeCompilePartialData, type ComposeCompileRequest, type ComposeCompileResult, type ComposeCompileSuccessData, type ComposeContinuation, type ComposeError, type ComposeErrorKind, type ComposeManifest, ComposeManifestZod, type ComposeRun, type ComposeTransactionRequest, type ContextKey, type Continuation, ContinuationSchema, type Erc20AllowanceRequirement, type Erc20BalanceRequirement, type FailedPreparedOp, type FlashloanMaterialiserInput, type Flow, type FlowInput, FlowInputSchema, FlowSchema, type GenericComposeError, type GenericComposeErrorKind, type GuardCompatibility, GuardCompatibilityZod, type GuardSelector, GuardSelectorZod, HANDLE_UNITS, type HandleInput, HandleInputSchema, type HandlePort, HandlePortZod, type HandleUnits, HandleUnitsZod, InputPortZod, type InputSpec, type LiteralBinding, LiteralBindingSchema, type ManifestGuard, ManifestGuardZod, type ManifestMaterialiser, ManifestMaterialiserZod, type ManifestOperation, ManifestOperationZod, type ManifestPrecondition, ManifestPreconditionZod, type MaterialiserConfigOf, type MaterialiserInput, type MaterialiserInputBase, type MaterialiserInputOf, type MaterialiserMetadata, type MaterialiserResolution, type NativeBalanceRequirement, type OpInputPort, type OpOutputPort, type OutputAmount, OutputPortZod, PROVIDER_KIND, type ParsedRef, type Port, type Precondition, type PreconditionBase, type PreconditionConfigOf, type PreconditionOf, type PreparationComposeError, type PriceImpact, type ProducedResource, type ProviderKindName, RESERVED_REF_SCOPES, type Ref, RefSchema, type RefScope, type Resource, type ResourceInput, ResourceInputSchema, type ResourceOutputPort, ResourceOutputPortZod, type ResourcePort, ResourcePortZod, ResourceSchema, SIMULATE_MAX_REQUIREMENTS, SIMULATE_MAX_TRACKED_BALANCES, STATIC_SOL_TYPES, type SimulateBalanceEntry, type SimulateOkResult, type SimulateRequest, type SimulateResult, type SimulateRevertDecodeResult, type SimulateRevertResult, type SimulateSetupErrorResult, type SimulatedAmounts, type SimulationPolicy, type SimulationRevert, type SimulationRevertComposeError, type SlotFinderRequirement, type SolType, SolTypeSchema, type StaticSolType, StaticSolTypeZod, type SweepTo, type TrackedBalance, copy, erc20, erc20Resource, erc20Token, flowInputMode, flowInputResource, flowInputType, foldMaterialiserMetadata, foldRef, foldResource, handle, inputRef, isContextKey, isERC20Resource, isHandlePort, isMaterialiserInput, isNativeResource, isRef, isResourceInput, isResourceOutputPort, isResourcePort, isStaticSolType, linear, native, nativeResource, opHandle, outputRef, parseRef, providerKindByName, providerKindNames, readResource, refKey, resource, resourceKey, resourceOutput, resourcesEqual };
package/dist/index.js CHANGED
@@ -214,6 +214,10 @@ var refKey = (ref) => foldRef(parseRef(ref), {
214
214
  output: (node, port) => `output:${node}:${port}`
215
215
  });
216
216
 
217
+ // src/simulate.ts
218
+ var SIMULATE_MAX_TRACKED_BALANCES = 40;
219
+ var SIMULATE_MAX_REQUIREMENTS = 40;
220
+
217
221
  // src/materialiserMetadata.ts
218
222
  var foldMaterialiserMetadata = (meta, cases) => {
219
223
  if (meta.kind === "exact") return cases.exact(meta.amount);
@@ -381,6 +385,8 @@ export {
381
385
  ResourceOutputPortZod,
382
386
  ResourcePortZod,
383
387
  ResourceSchema,
388
+ SIMULATE_MAX_REQUIREMENTS,
389
+ SIMULATE_MAX_TRACKED_BALANCES,
384
390
  STATIC_SOL_TYPES,
385
391
  SolTypeSchema,
386
392
  StaticSolTypeZod,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@lifi/compose-spec",
3
- "version": "0.2.0-staging.5",
3
+ "version": "0.2.0",
4
4
  "description": "Public wire-format types and schemas for Compose flows",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {
@@ -23,7 +23,7 @@
23
23
  "./package.json": "./package.json"
24
24
  },
25
25
  "engines": {
26
- "node": ">=18"
26
+ "node": ">=24"
27
27
  },
28
28
  "publishConfig": {
29
29
  "access": "public"
package/src/index.ts CHANGED
@@ -138,6 +138,25 @@ export type {
138
138
  ComposeCompileResult,
139
139
  } from "./compile.js";
140
140
 
141
+ export type {
142
+ TrackedBalance,
143
+ Erc20BalanceRequirement,
144
+ NativeBalanceRequirement,
145
+ Erc20AllowanceRequirement,
146
+ SlotFinderRequirement,
147
+ SimulateRequest,
148
+ SimulateBalanceEntry,
149
+ SimulateOkResult,
150
+ SimulateRevertDecodeResult,
151
+ SimulateRevertResult,
152
+ SimulateSetupErrorResult,
153
+ SimulateResult,
154
+ } from "./simulate.js";
155
+ export {
156
+ SIMULATE_MAX_TRACKED_BALANCES,
157
+ SIMULATE_MAX_REQUIREMENTS,
158
+ } from "./simulate.js";
159
+
141
160
  export type {
142
161
  MaterialiserMetadata,
143
162
  MaterialiserResolution,
@@ -0,0 +1,185 @@
1
+ /**
2
+ * Canonical wire-format types for the standalone `POST /simulate` endpoint.
3
+ *
4
+ * `/simulate` takes a raw, pre-encoded transaction (a `to` address, hex `data`,
5
+ * optional native `value`), funds a sender, runs it in one `eth_call`, and
6
+ * reports the watched balances before and after, their signed deltas, and the
7
+ * inner-call gas. Unlike `POST /compose`, its response body is **un-enveloped**:
8
+ * `{ status, block, timestamp, ... }` lives at the top level (no `{ data }`
9
+ * wrapper).
10
+ *
11
+ * These are the single source of truth for the request/response shapes. The
12
+ * server-side Zod schemas in `@lifi/api-schemas` (`src/routes/simulate.ts`)
13
+ * validate the same contract and are kept in lockstep by a compile-time
14
+ * conformance assertion (`src/routes/simulate.typecheck.ts`).
15
+ *
16
+ * Mirrors the hand-authored style of `src/compile.ts`.
17
+ */
18
+
19
+ /**
20
+ * Maximum number of watched `(token, owner)` pairs accepted by `POST /simulate`.
21
+ *
22
+ * The limit comes from the VM's hard register budget (~123 usable registers,
23
+ * checked on the final ISA layout). Each pair costs two result registers — a
24
+ * before-read and an after-read — that are both live at the closing abi-encode,
25
+ * so the compiler cannot coalesce them; that `2 × N` is the cost that scales.
26
+ * Token and owner address literals do not scale it, since constant-propagation
27
+ * merges identical-valued literals into one register. The cap leaves headroom
28
+ * for the inner-call / gas-measurement / abi-encode scaffolding.
29
+ */
30
+ export const SIMULATE_MAX_TRACKED_BALANCES = 40;
31
+
32
+ /**
33
+ * Maximum number of funding `requirements` accepted by `POST /simulate`.
34
+ *
35
+ * Each requirement triggers a slot-discovery cycle (access-list probe + sentinel
36
+ * verification + RPC round trips) in slot-finder, so an unbounded array lets a
37
+ * single request amplify into arbitrary upstream RPC work. Bounded here at the
38
+ * trust boundary and re-enforced server-side in `rawSimulation.ts`.
39
+ */
40
+ export const SIMULATE_MAX_REQUIREMENTS = 40;
41
+
42
+ /** A `(token, owner)` pair whose balance is watched across the simulation. */
43
+ export interface TrackedBalance {
44
+ /** Token to watch (use the zero address for native balance). */
45
+ readonly token: string;
46
+ /** Account whose balance of `token` is watched. */
47
+ readonly owner: string;
48
+ }
49
+
50
+ /**
51
+ * Funding instruction: seed an ERC-20 balance on a wallet before simulation.
52
+ * Amounts accept `bigint | string` — the SDK serialises `bigint` to a decimal
53
+ * string; the string side covers values already stringified.
54
+ */
55
+ export interface Erc20BalanceRequirement {
56
+ readonly type: "Erc20Balance";
57
+ readonly wallet: string;
58
+ readonly token: string;
59
+ readonly balance: bigint | string;
60
+ }
61
+
62
+ /** Funding instruction: seed a native balance on a wallet before simulation. */
63
+ export interface NativeBalanceRequirement {
64
+ readonly type: "NativeBalance";
65
+ readonly wallet: string;
66
+ readonly balance: bigint | string;
67
+ }
68
+
69
+ /** Funding instruction: seed an ERC-20 allowance before simulation. */
70
+ export interface Erc20AllowanceRequirement {
71
+ readonly type: "Erc20Allowance";
72
+ readonly owner: string;
73
+ readonly spender: string;
74
+ readonly token: string;
75
+ readonly allowance: bigint | string;
76
+ }
77
+
78
+ /**
79
+ * The funding-instruction union applied before a simulation. Three variants,
80
+ * discriminated by `type`.
81
+ */
82
+ export type SlotFinderRequirement =
83
+ | Erc20BalanceRequirement
84
+ | NativeBalanceRequirement
85
+ | Erc20AllowanceRequirement;
86
+
87
+ /** Request body for `POST /simulate`. */
88
+ export interface SimulateRequest {
89
+ /** EVM chain id. */
90
+ readonly chainId: number;
91
+ /**
92
+ * Sender of the simulated transaction. The VM bytecode is injected here so
93
+ * the inner call carries `msg.sender == from`.
94
+ */
95
+ readonly from: string;
96
+ /** Target contract of the raw transaction. */
97
+ readonly to: string;
98
+ /** Pre-encoded transaction calldata (`0x`-prefixed hex). */
99
+ readonly data: string;
100
+ /**
101
+ * Native value (wei) sent with the inner call. Accepts `bigint | string`;
102
+ * defaults to `"0"` server-side when omitted.
103
+ */
104
+ readonly value?: bigint | string;
105
+ /**
106
+ * Block number to simulate against. Omitted ⇒ the chain head. Named tags
107
+ * (e.g. "latest") are rejected with HTTP 400.
108
+ */
109
+ readonly block?: number;
110
+ /** Funding instructions applied before simulation (max 40). */
111
+ readonly requirements?: readonly SlotFinderRequirement[];
112
+ /** Balances to read before and after the transaction (1–40 pairs). */
113
+ readonly trackedBalances: readonly TrackedBalance[];
114
+ }
115
+
116
+ /**
117
+ * One watched balance in a simulation response. `amount` is a decimal string;
118
+ * for `deltas` it is signed (`after - before`).
119
+ */
120
+ export interface SimulateBalanceEntry {
121
+ readonly token: string;
122
+ readonly owner: string;
123
+ readonly amount: string;
124
+ }
125
+
126
+ /**
127
+ * HTTP 200, `status: "ok"`: the simulation ran successfully. Balance arrays are
128
+ * ordered to match the request `trackedBalances`. `gasUsed` is inner-call
129
+ * execution gas only.
130
+ *
131
+ * Note: the array element types are intentionally mutable (`SimulateBalanceEntry[]`,
132
+ * not `readonly SimulateBalanceEntry[]`) so they stay structurally identical to
133
+ * the Zod-inferred wire types, which `z.array(...)` infers as mutable `T[]`. The
134
+ * bidirectional conformance assertion in `@lifi/api-schemas` relies on this.
135
+ */
136
+ export interface SimulateOkResult {
137
+ readonly status: "ok";
138
+ readonly block: number;
139
+ readonly timestamp: number;
140
+ readonly balancesBefore: SimulateBalanceEntry[];
141
+ readonly balancesAfter: SimulateBalanceEntry[];
142
+ readonly deltas: SimulateBalanceEntry[];
143
+ readonly gasUsed: string;
144
+ }
145
+
146
+ /** Decoded revert diagnostics, when slot-finder can parse the revert reason. */
147
+ export interface SimulateRevertDecodeResult {
148
+ readonly errorCandidates?: {
149
+ readonly decodedErrorSignature: string;
150
+ readonly decodedParams: string[];
151
+ }[];
152
+ readonly error?: string;
153
+ }
154
+
155
+ /**
156
+ * HTTP 200, `status: "revert"`: the simulation ran but the transaction reverted
157
+ * on-chain. A revert is a *successful simulation*, not a transport error.
158
+ */
159
+ export interface SimulateRevertResult {
160
+ readonly status: "revert";
161
+ readonly block: number;
162
+ readonly timestamp: number;
163
+ readonly revertReason?: string;
164
+ readonly code?: number;
165
+ readonly rawErrorBytes?: string;
166
+ readonly decodeResult?: SimulateRevertDecodeResult;
167
+ }
168
+
169
+ /**
170
+ * HTTP 422, `status: "error"`: the request was well-formed but the simulation
171
+ * could not be set up or run. `message` is intentionally generic.
172
+ */
173
+ export interface SimulateSetupErrorResult {
174
+ readonly status: "error";
175
+ readonly message: string;
176
+ }
177
+
178
+ /**
179
+ * Discriminated result of `POST /simulate`. `switch (result.status)` narrows to
180
+ * one member: `ok` and `revert` come back with HTTP 200, `error` with HTTP 422.
181
+ */
182
+ export type SimulateResult =
183
+ | SimulateOkResult
184
+ | SimulateRevertResult
185
+ | SimulateSetupErrorResult;