@lifi/compose-spec 0.0.1-alpha → 0.1.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/package.json CHANGED
@@ -1,8 +1,13 @@
1
1
  {
2
2
  "name": "@lifi/compose-spec",
3
- "version": "0.0.1-alpha",
3
+ "version": "0.1.0",
4
4
  "description": "Public wire-format types and schemas for Compose flows",
5
5
  "license": "Apache-2.0",
6
+ "repository": {
7
+ "type": "git",
8
+ "url": "git+https://github.com/lifinance/Yggdrasil.git",
9
+ "directory": "ts/packages/compose-spec"
10
+ },
6
11
  "type": "module",
7
12
  "sideEffects": false,
8
13
  "main": "./dist/index.cjs",
package/src/compile.ts CHANGED
@@ -1,5 +1,5 @@
1
- import type { Flow } from "./flowSchema.js";
2
1
  import type { InputSpec, Precondition } from "./flow.js";
2
+ import type { Flow } from "./flowSchema.js";
3
3
  import type { ProducedResource } from "./resource.js";
4
4
 
5
5
  export type SimulationPolicy = "strict" | "allow-revert";
@@ -17,6 +17,7 @@ export interface ComposeRun {
17
17
  readonly signer: string;
18
18
  readonly assumptions?: Record<string, bigint>;
19
19
  readonly referrer?: string;
20
+ readonly integratorFeeBps?: number;
20
21
  readonly maxPriceImpactBps?: number;
21
22
  readonly sweepTo?: SweepTo;
22
23
  readonly simulationPolicy?: SimulationPolicy;
@@ -1,4 +1,4 @@
1
- import type { HandleInput, ResourceInput, SolType } from "./flowSchema.js";
1
+ import type { HandleInput, Ref, ResourceInput, SolType } from "./flowSchema.js";
2
2
  import type {
3
3
  Port,
4
4
  ResourcePort,
@@ -6,6 +6,26 @@ import type {
6
6
  ResourceOutputPort,
7
7
  } from "./flow.js";
8
8
  import type { Availability } from "./resource.js";
9
+ import { erc20Resource, nativeResource } from "./resource.js";
10
+ import type { HandleUnits } from "./zodSchemas.js";
11
+
12
+ export interface OpHandleOptions {
13
+ readonly expose?: boolean;
14
+ readonly units?: HandleUnits;
15
+ }
16
+
17
+ export const inputRef = (port: string): Ref => ({ $ref: `input.${port}` });
18
+
19
+ export const outputRef = (node: string, port: string): Ref => ({
20
+ $ref: `${node}.${port}`,
21
+ });
22
+
23
+ /** Returns `{ [key]: value }` when `value` is not nullish, else `{}`. */
24
+ const optionalProp = <K extends string, V>(
25
+ key: K,
26
+ value: V | undefined | null
27
+ ): Partial<Record<K, V>> =>
28
+ value != null ? ({ [key]: value } as Partial<Record<K, V>>) : {};
9
29
 
10
30
  export const linear = <N extends string, T extends SolType>(
11
31
  name: N,
@@ -37,7 +57,7 @@ export const native = <N extends string>(
37
57
  name: N,
38
58
  chainId: number
39
59
  ): ResourceInput & { readonly name: N } =>
40
- ({ name, resource: { kind: "native", chainId } } as ResourceInput & {
60
+ ({ name, resource: nativeResource(chainId) } as ResourceInput & {
41
61
  readonly name: N;
42
62
  });
43
63
 
@@ -46,17 +66,22 @@ export const erc20 = <N extends string>(
46
66
  token: string,
47
67
  chainId: number
48
68
  ): ResourceInput & { readonly name: N } =>
49
- ({ name, resource: { kind: "erc20", token, chainId } } as ResourceInput & {
69
+ ({ name, resource: erc20Resource(token, chainId) } as ResourceInput & {
50
70
  readonly name: N;
51
71
  });
52
72
 
53
- export const resource = <N extends string>(
73
+ export const resource = <N extends string, Opt extends boolean = false>(
54
74
  name: N,
55
- accepts: "erc20" | "native" | "any"
56
- ): ResourcePort & { readonly name: N } =>
57
- ({ kind: "resource", name, accepts, mode: "linear" } as ResourcePort & {
58
- readonly name: N;
59
- });
75
+ accepts: "erc20" | "native" | "any",
76
+ options?: { optional?: Opt }
77
+ ): ResourcePort & { readonly name: N; readonly optional: Opt } =>
78
+ ({
79
+ kind: "resource",
80
+ name,
81
+ accepts,
82
+ mode: "linear",
83
+ ...optionalProp("optional", options?.optional),
84
+ } as ResourcePort & { readonly name: N; readonly optional: Opt });
60
85
 
61
86
  export const readResource = <N extends string>(
62
87
  name: N,
@@ -69,9 +94,17 @@ export const readResource = <N extends string>(
69
94
 
70
95
  export const opHandle = <N extends string, T extends SolType>(
71
96
  name: N,
72
- type: T
97
+ type: T,
98
+ options?: OpHandleOptions
73
99
  ): HandlePort & { readonly name: N; readonly type: T } =>
74
- ({ kind: "handle", name, type, mode: "copy" } as HandlePort & {
100
+ ({
101
+ kind: "handle",
102
+ name,
103
+ type,
104
+ mode: "copy",
105
+ ...optionalProp("expose", options?.expose),
106
+ ...optionalProp("units", options?.units),
107
+ } as HandlePort & {
75
108
  readonly name: N;
76
109
  readonly type: T;
77
110
  });
@@ -93,13 +126,9 @@ export const resourceOutput = <N extends string>(
93
126
  kind: "resource_output",
94
127
  name,
95
128
  mode: "linear",
96
- ...(opts?.availability != null && { availability: opts.availability }),
97
- ...(opts?.providesMinimum != null && {
98
- providesMinimum: opts.providesMinimum,
99
- }),
100
- ...(opts?.omitIfZero != null && { omitIfZero: opts.omitIfZero }),
101
- ...(opts?.deliveryAddressInput != null && {
102
- deliveryAddressInput: opts.deliveryAddressInput,
103
- }),
129
+ ...optionalProp("availability", opts?.availability),
130
+ ...optionalProp("providesMinimum", opts?.providesMinimum),
131
+ ...optionalProp("omitIfZero", opts?.omitIfZero),
132
+ ...optionalProp("deliveryAddressInput", opts?.deliveryAddressInput),
104
133
  } as ResourceOutputPort & { readonly name: N };
105
134
  };
@@ -0,0 +1,41 @@
1
+ // Mirrors the Solidity `ProviderKind` enum in
2
+ // `Yggdrasil-VirtualMachine/src/flashloan/FlashloanLeg.sol`. The numeric
3
+ // values are wire format; the Rust EVM backend consumes them in
4
+ // `executeWithFlashloan(adapter, legs, programBytes)`. Drift between this
5
+ // file and the Solidity source is a bug.
6
+
7
+ export const PROVIDER_KIND = {
8
+ AAVE_V3: 0,
9
+ ERC3156: 1,
10
+ BALANCER_V2: 2,
11
+ MORPHO_BLUE: 3,
12
+ } as const;
13
+
14
+ export const providerKindNames = [
15
+ "aave-v3",
16
+ "erc3156",
17
+ "balancer-v2",
18
+ "morpho-blue",
19
+ ] as const;
20
+
21
+ export type ProviderKindName = (typeof providerKindNames)[number];
22
+
23
+ export const providerKindByName: Record<ProviderKindName, number> = {
24
+ "aave-v3": PROVIDER_KIND.AAVE_V3,
25
+ erc3156: PROVIDER_KIND.ERC3156,
26
+ "balancer-v2": PROVIDER_KIND.BALANCER_V2,
27
+ "morpho-blue": PROVIDER_KIND.MORPHO_BLUE,
28
+ };
29
+
30
+ // The fully-narrowed JSON shape of a `flashloan` MaterialiserInput once it
31
+ // has crossed from untrusted Flow JSON through structural validation. The
32
+ // literal `kind: "flashloan"` discriminates inside the `MaterialiserInput`
33
+ // union; `providerKind` and `amount` are the two flashloan-specific fields.
34
+ // `amount` is the wire form (decimal-integer string); the flashloan
35
+ // materialiser's `configSchema` (see compose-builtins/materialisers/flashloan)
36
+ // validates the shape before any consumer reads it.
37
+ export interface FlashloanMaterialiserInput {
38
+ readonly kind: "flashloan";
39
+ readonly providerKind: ProviderKindName;
40
+ readonly amount: string;
41
+ }
package/src/flow.ts CHANGED
@@ -1,20 +1,21 @@
1
- import type { Availability, Resource } from "./resource.js";
1
+ import type { SimulationRevert } from "./compile.js";
2
2
  import type { FlowInput, ResourceInput, SolType } from "./flowSchema.js";
3
+ import type { Availability, Resource } from "./resource.js";
3
4
 
4
5
  export type {
5
- ResourcePort,
6
6
  HandlePort,
7
7
  OpInputPort,
8
- ResourceOutputPort,
9
8
  OpOutputPort,
9
+ ResourceOutputPort,
10
+ ResourcePort,
10
11
  } from "./zodSchemas.js";
11
12
 
12
13
  import type {
14
+ HandlePort,
13
15
  OpInputPort,
14
16
  OpOutputPort,
15
- ResourcePort,
16
- HandlePort,
17
17
  ResourceOutputPort,
18
+ ResourcePort,
18
19
  } from "./zodSchemas.js";
19
20
 
20
21
  export interface Port {
@@ -54,23 +55,61 @@ export type ComposeErrorKind =
54
55
  | "linearity_error"
55
56
  | "resolve_error"
56
57
  | "preparation_error"
58
+ | "provider_error"
57
59
  | "no_route_error"
58
60
  | "lowering_error"
59
61
  | "simulation_error"
60
62
  | "simulation_setup_error"
61
63
  | "simulation_revert"
64
+ | "subgraph_simulation_revert"
62
65
  | "guard_error"
63
66
  | "continuation_error"
64
67
  | "compilation_error"
65
68
  | "verification_error"
66
- | "price_impact_exceeded";
69
+ | "price_impact_exceeded"
70
+ | "fee_resolution_error"
71
+ | "fee_resolution_unavailable"
72
+ | "flashloan_unauthorized";
73
+
74
+ export type GenericComposeErrorKind = Exclude<
75
+ ComposeErrorKind,
76
+ "preparation_error" | "simulation_revert"
77
+ >;
78
+
79
+ export interface FailedPreparedOp {
80
+ readonly callId: string;
81
+ readonly op: string;
82
+ readonly kind: GenericComposeErrorKind;
83
+ readonly message: string;
84
+ readonly path?: string;
85
+ }
67
86
 
68
- export interface ComposeError {
69
- readonly kind: ComposeErrorKind;
87
+ interface ComposeErrorBase {
70
88
  readonly message: string;
71
89
  readonly path?: string;
72
90
  }
73
91
 
92
+ export interface PreparationComposeError extends ComposeErrorBase {
93
+ readonly kind: "preparation_error";
94
+ readonly failedOps: readonly FailedPreparedOp[];
95
+ readonly succeededOps: readonly string[];
96
+ }
97
+
98
+ export interface SimulationRevertComposeError extends ComposeErrorBase {
99
+ readonly kind: "simulation_revert";
100
+ readonly details?: SimulationRevert;
101
+ }
102
+
103
+ export interface GenericComposeError extends ComposeErrorBase {
104
+ readonly kind: GenericComposeErrorKind;
105
+ readonly [key: string]: unknown;
106
+ }
107
+
108
+ export type ComposeError =
109
+ | PreparationComposeError
110
+ | SimulationRevertComposeError
111
+ | GenericComposeError;
112
+
74
113
  export interface MaterialiserInputBase {
75
114
  readonly kind: string;
76
115
  }
package/src/index.ts CHANGED
@@ -35,6 +35,11 @@ export type {
35
35
  OpOutputPort,
36
36
  ComposeError,
37
37
  ComposeErrorKind,
38
+ GenericComposeErrorKind,
39
+ PreparationComposeError,
40
+ SimulationRevertComposeError,
41
+ GenericComposeError,
42
+ FailedPreparedOp,
38
43
  MaterialiserInputBase,
39
44
  MaterialiserInput,
40
45
  MaterialiserInputOf,
@@ -63,7 +68,26 @@ export type {
63
68
  ProducedResource,
64
69
  SimulatedAmounts,
65
70
  } from "./resource.js";
66
- export { erc20Token, foldResource, resourceKey } from "./resource.js";
71
+ export {
72
+ erc20Resource,
73
+ erc20Token,
74
+ foldResource,
75
+ isERC20Resource,
76
+ isNativeResource,
77
+ nativeResource,
78
+ resourceKey,
79
+ resourcesEqual,
80
+ } from "./resource.js";
81
+
82
+ export type {
83
+ ProviderKindName,
84
+ FlashloanMaterialiserInput,
85
+ } from "./flashloan.js";
86
+ export {
87
+ PROVIDER_KIND,
88
+ providerKindByName,
89
+ providerKindNames,
90
+ } from "./flashloan.js";
67
91
 
68
92
  export {
69
93
  linear,
@@ -75,6 +99,8 @@ export {
75
99
  readResource,
76
100
  opHandle,
77
101
  resourceOutput,
102
+ inputRef,
103
+ outputRef,
78
104
  } from "./constructors.js";
79
105
 
80
106
  export type { ParsedRef, RefScope, ContextKey } from "./ref.js";
@@ -82,6 +108,7 @@ export {
82
108
  parseRef,
83
109
  foldRef,
84
110
  refKey,
111
+ isRef,
85
112
  isContextKey,
86
113
  RESERVED_REF_SCOPES,
87
114
  } from "./ref.js";
@@ -120,6 +147,11 @@ export { foldMaterialiserMetadata } from "./materialiserMetadata.js";
120
147
  export {
121
148
  ResourcePortZod,
122
149
  HandlePortZod,
150
+ HandleUnitsZod,
151
+ StaticSolTypeZod,
152
+ HANDLE_UNITS,
153
+ STATIC_SOL_TYPES,
154
+ isStaticSolType,
123
155
  InputPortZod,
124
156
  ResourceOutputPortZod,
125
157
  OutputPortZod,
@@ -131,3 +163,4 @@ export {
131
163
  GuardSelectorZod,
132
164
  GuardCompatibilityZod,
133
165
  } from "./zodSchemas.js";
166
+ export type { HandleUnits, StaticSolType } from "./zodSchemas.js";
package/src/ref.ts CHANGED
@@ -24,6 +24,12 @@ export const RESERVED_REF_SCOPES: ReadonlySet<string> = new Set([
24
24
  "literal",
25
25
  ]);
26
26
 
27
+ export const isRef = (v: unknown): v is Ref =>
28
+ typeof v === "object" &&
29
+ v !== null &&
30
+ "$ref" in v &&
31
+ typeof (v as { $ref: unknown }).$ref === "string";
32
+
27
33
  export const parseRef = (ref: Ref): ParsedRef => {
28
34
  const dot = ref.$ref.indexOf(".");
29
35
  if (dot === -1)
package/src/resource.ts CHANGED
@@ -24,12 +24,43 @@ export type ProducedResource = Resource & {
24
24
  readonly owner: string;
25
25
  };
26
26
 
27
+ export const erc20Resource = (token: string, chainId: number): Resource => ({
28
+ kind: "erc20",
29
+ token,
30
+ chainId,
31
+ });
32
+
33
+ export const nativeResource = (chainId: number): Resource => ({
34
+ kind: "native",
35
+ chainId,
36
+ });
37
+
38
+ export const isERC20Resource = (
39
+ r: Resource,
40
+ ): r is Extract<Resource, { kind: "erc20" }> => r.kind === "erc20";
41
+
42
+ export const isNativeResource = (
43
+ r: Resource,
44
+ ): r is Extract<Resource, { kind: "native" }> => r.kind === "native";
45
+
46
+ export const resourcesEqual = (a: Resource, b: Resource): boolean => {
47
+ if (isNativeResource(a) && isNativeResource(b)) {
48
+ return a.chainId === b.chainId;
49
+ }
50
+ if (isERC20Resource(a) && isERC20Resource(b)) {
51
+ return (
52
+ a.chainId === b.chainId && a.token.toLowerCase() === b.token.toLowerCase()
53
+ );
54
+ }
55
+ return false;
56
+ };
57
+
27
58
  export const foldResource = <R>(
28
59
  r: Resource,
29
60
  cases: {
30
61
  readonly native: (chainId: number) => R;
31
62
  readonly erc20: (token: string, chainId: number) => R;
32
- }
63
+ },
33
64
  ): R =>
34
65
  r.kind === "native"
35
66
  ? cases.native(r.chainId)
package/src/zodSchemas.ts CHANGED
@@ -22,13 +22,48 @@ export const ResourcePortZod = z.object({
22
22
  name: z.string(),
23
23
  accepts: z.enum(["erc20", "native", "any"]),
24
24
  mode: z.enum(["linear", "copy"]),
25
+ optional: z.boolean().optional(),
25
26
  });
26
27
 
28
+ export const HANDLE_UNITS = [
29
+ "raw",
30
+ "wad",
31
+ "ray",
32
+ "bps",
33
+ "token-decimals",
34
+ ] as const;
35
+
36
+ // NOTE: the uint members below must stay in sync with the `UintN` union in
37
+ // `ts/packages/lifi_ir1_ts/src/types/ValueHandle.ts`. When adding a new
38
+ // uintN width, update both locations.
39
+ export const STATIC_SOL_TYPES = [
40
+ "uint256",
41
+ "uint128",
42
+ "uint64",
43
+ "uint32",
44
+ "uint16",
45
+ "uint8",
46
+ "address",
47
+ "bool",
48
+ "bytes32",
49
+ ] as const;
50
+
51
+ export const HandleUnitsZod = z.enum(HANDLE_UNITS);
52
+
53
+ export const StaticSolTypeZod = z.enum(STATIC_SOL_TYPES);
54
+
55
+ const STATIC_SOL_TYPE_SET: ReadonlySet<string> = new Set(STATIC_SOL_TYPES);
56
+
57
+ export const isStaticSolType = (value: string): value is StaticSolType =>
58
+ STATIC_SOL_TYPE_SET.has(value);
59
+
27
60
  export const HandlePortZod = z.object({
28
61
  kind: z.literal("handle"),
29
62
  name: z.string(),
30
63
  type: SolTypeZod,
31
64
  mode: z.enum(["linear", "copy"]),
65
+ expose: z.boolean().optional(),
66
+ units: HandleUnitsZod.optional(),
32
67
  });
33
68
 
34
69
  export const InputPortZod = z.discriminatedUnion("kind", [
@@ -125,6 +160,8 @@ export const ComposeManifestZod = z.object({
125
160
 
126
161
  export type ResourcePort = z.infer<typeof ResourcePortZod>;
127
162
  export type HandlePort = z.infer<typeof HandlePortZod>;
163
+ export type HandleUnits = z.infer<typeof HandleUnitsZod>;
164
+ export type StaticSolType = z.infer<typeof StaticSolTypeZod>;
128
165
  export type OpInputPort = z.infer<typeof InputPortZod>;
129
166
  export type ResourceOutputPort = z.infer<typeof ResourceOutputPortZod>;
130
167
  export type OpOutputPort = z.infer<typeof OutputPortZod>;