feat: OmniGraph

.eslintrc.json

@@ -26,7 +26,7 @@
     // Intermediate deescalation to warnings
     //
     // FIXME Slowly remove these problems, then remove these overrides
-    "no-undef": "warn",
+    "no-undef": "off",
     "no-constant-condition": "warn",
 
     "no-unused-vars": "off",

packages/create-lz-oapp/src/utilities/prompts.ts

@@ -4,7 +4,7 @@ import { isPackageManagerAvailable } from './installation.js'
 import { isDirectory } from './filesystem.js'
 import { resolve } from 'path'
 
-const handlePromptState = (state: any) => {
+const handlePromptState = (state: { aborted: boolean }) => {
     if (state.aborted) {
         // If we don't re-enable the terminal cursor before exiting
         // the program, the cursor will remain hidden

packages/ua-utils/.eslintignore

@@ -0,0 +1,3 @@
+.turbo
+dist
+node_modules

packages/ua-utils/.eslintrc.json

@@ -0,0 +1,3 @@
+{
+  "extends": "../../.eslintrc.json"
+}

packages/ua-utils/README.md

@@ -0,0 +1,23 @@
+<p align="center">
+  <a href="https://layerzero.network">
+    <img alt="LayerZero" style="max-width: 500px" src="https://d3a2dpnnrypp5h.cloudfront.net/bridge-app/lz.png"/>
+  </a>
+</p>
+
+<h1 align="center">@layerzerolabs/ua-utils</h1>
+
+<!-- The badges section -->
+<p align="center">
+  <!-- Shields.io NPM published package version -->
+  <a href="https://www.npmjs.com/package/@layerzerolabs/ua-utils"><img alt="NPM Version" src="https://img.shields.io/npm/v/@layerzerolabs/ua-utils"/></a>
+  <!-- Shields.io NPM downloads -->
+  <a href="https://www.npmjs.com/package/@layerzerolabs/ua-utils"><img alt="Downloads" src="https://img.shields.io/npm/dm/@layerzerolabs/ua-utils"/></a>
+  <!-- Shields.io license badge -->
+  <a href="https://www.npmjs.com/package/@layerzerolabs/ua-utils"><img alt="NPM License" src="https://img.shields.io/npm/l/@layerzerolabs/ua-utils"/></a>
+</p>
+
+## Installation
+
+```sh
+$ npm install @layerzerolabs/ua-utils
+```

packages/ua-utils/jest.config.js

@@ -0,0 +1,8 @@
+/** @type {import('ts-jest').JestConfigWithTsJest} */
+module.exports = {
+    preset: 'ts-jest',
+    testEnvironment: 'node',
+    moduleNameMapper: {
+        '^@/(.*)$': '<rootDir>/src/$1',
+    },
+};

packages/ua-utils/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@layerzerolabs/ua-utils",
+  "version": "0.1.0",
+  "private": true,
+  "description": "Utilities for working with LayerZero contracts",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/LayerZero-Labs/lz-utils.git",
+    "directory": "packages/ua-utils"
+  },
+  "license": "MIT",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.js",
+      "import": "./dist/index.mjs"
+    }
+  },
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist/",
+    "LICENSE"
+  ],
+  "scripts": {
+    "prebuild": "tsc -noEmit",
+    "build": "npx tsup",
+    "clean": "rm -rf dist",
+    "lint": "npx eslint '**/*.{js,ts,json}'",
+    "test": "jest"
+  },
+  "devDependencies": {
+    "@layerzerolabs/lz-definitions": "~1.5.58",
+    "@types/jest": "^29.5.10",
+    "fast-check": "^3.14.0",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.1.1",
+    "ts-node": "^10.9.1",
+    "tsup": "^7.2.0",
+    "typescript": "^5.2.2",
+    "zod": "^3.22.4"
+  },
+  "peerDependencies": {
+    "@layerzerolabs/lz-definitions": "~1.5.58",
+    "zod": "^3.22.4"
+  }
+}

packages/ua-utils/src/index.ts

@@ -0,0 +1 @@
+export * from './omnigraph'

packages/ua-utils/src/omnigraph/coordinates.ts

@@ -0,0 +1,44 @@
+import { OmniEdgeCoordinates, OmniNodeCoordinate } from './types'
+
+/**
+ * Compares two coordinates by value
+ *
+ * @param a `OmniNodeCoordinate`
+ * @param b `OmniNodeCoordinate`
+ *
+ * @returns `true` if the coordinates point to the same point in omniverse
+ */
+export const isCoordinateEqual = (a: OmniNodeCoordinate, b: OmniNodeCoordinate): boolean =>
+    a.address === b.address && a.eid === b.eid
+
+/**
+ * Compares two coordinate vectors
+ *
+ * @param a `OmniEdgeCoordinates`
+ * @param b `OmniEdgeCoordinates`
+ *
+ * @returns `true` if the coordinates point from and to the same point in omniverse
+ */
+export const areCoordinatesEqual = (a: OmniEdgeCoordinates, b: OmniEdgeCoordinates): boolean =>
+    isCoordinateEqual(a.from, b.from) && isCoordinateEqual(a.to, b.to)
+
+/**
+ * Serializes a coordinate. Useful for when coordinates need to be used in Map
+ * where we cannot adjust the default behavior of using a reference equality
+ *
+ * @param coordinate `OmniNodeCoordinate`
+ *
+ * @returns `string`
+ */
+export const serializeCoordinate = ({ address, eid }: OmniNodeCoordinate): string => `${eid}|${address}`
+
+/**
+ * Serializes coordinate vector. Useful for when coordinates need to be used in Map
+ * where we cannot adjust the default behavior of using a reference equality
+ *
+ * @param coordinate `OmniEdgeCoordinates`
+ *
+ * @returns `string`
+ */
+export const serializeCoordinates = ({ from, to }: OmniEdgeCoordinates): string =>
+    `${serializeCoordinate(from)} → ${serializeCoordinate(to)}`

packages/ua-utils/src/omnigraph/index.ts

@@ -0,0 +1,3 @@
+export * from './coordinates'
+export * from './schema'
+export * from './types'

packages/ua-utils/src/omnigraph/schema.ts

@@ -0,0 +1,49 @@
+import { EndpointId } from '@layerzerolabs/lz-definitions'
+import { z } from 'zod'
+import type { OmniNodeCoordinate, OmniNode, OmniEdgeCoordinates, OmniEdge } from './types'
+
+export const AddressSchema = z.string()
+
+export const EndpointIdSchema: z.ZodSchema<EndpointId, z.ZodTypeDef, unknown> = z
+    .nativeEnum(EndpointId)
+    .pipe(z.number())
+
+export const OmniNodeCoordinateSchema: z.ZodSchema<OmniNodeCoordinate, z.ZodTypeDef, unknown> = z.object({
+    address: AddressSchema,
+    eid: EndpointIdSchema,
+})
+
+export const OmniEdgeCoordinatesSchema: z.ZodSchema<OmniEdgeCoordinates, z.ZodTypeDef, unknown> = z.object({
+    from: OmniNodeCoordinateSchema,
+    to: OmniNodeCoordinateSchema,
+})
+
+/**
+ * Factory for OmniNode schemas
+ *
+ * @param configSchema Schema of the config contained in the node
+ *
+ * @returns `z.ZodSchema<OmniNode<TConfig>>` schema for a node with the particular config type
+ */
+export const createOmniNodeSchema = <TConfig = unknown>(
+    configSchema: z.ZodSchema<TConfig, z.ZodTypeDef, unknown>
+): z.ZodSchema<OmniNode<TConfig>, z.ZodTypeDef, unknown> =>
+    z.object({
+        coordinate: OmniNodeCoordinateSchema,
+        config: configSchema,
+    }) as z.ZodSchema<OmniNode<TConfig>, z.ZodTypeDef, unknown>
+
+/**
+ * Factory for OmniEdge schemas
+ *
+ * @param configSchema `z.ZodSchema<TConfig>` Schema of the config contained in the edge
+ *
+ * @returns `z.ZodSchema<OmniEdge<TConfig>>` schema for an edge with the particular config type
+ */
+export const createOmniEdgeSchema = <TConfig = unknown>(
+    configSchema: z.ZodSchema<TConfig, z.ZodTypeDef, unknown>
+): z.ZodSchema<OmniEdge<TConfig>, z.ZodTypeDef, unknown> =>
+    z.object({
+        coordinates: OmniEdgeCoordinatesSchema,
+        config: configSchema,
+    }) as z.ZodSchema<OmniEdge<TConfig>, z.ZodTypeDef, unknown>

packages/ua-utils/src/omnigraph/types.ts

@@ -0,0 +1,53 @@
+import type { EndpointId } from '@layerzerolabs/lz-definitions'
+
+export type Address = string
+
+/**
+ * OmniNodeCoordinate identifies a point in omniverse, an omnichain universe.
+ *
+ * In layman terms this is a contract deployed on a particular network (represented by an endpoint).
+ */
+export interface OmniNodeCoordinate {
+    eid: EndpointId
+    address: Address
+}
+
+/**
+ * OmniEdgeCoordinates identify a line in omniverse, an omnichain universe.
+ *
+ * In layman terms this is a directional connection between two contracts
+ */
+export interface OmniEdgeCoordinates {
+    from: OmniNodeCoordinate
+    to: OmniNodeCoordinate
+}
+
+/**
+ * OmniNode represents a point in omniverse
+ * with an additional piece of information attached
+ */
+export interface OmniNode<TConfig = unknown> {
+    coordinate: OmniNodeCoordinate
+    config: TConfig
+}
+
+/**
+ * OmniEdge represents a connection between two points in omniverse
+ * with an additional piece of information attached
+ */
+export interface OmniEdge<TConfig = unknown> {
+    coordinates: OmniEdgeCoordinates
+    config: TConfig
+}
+
+/**
+ * OmniGraph is a collection of nodes and edges of omniverse
+ * that together represent an omnichain app a.k.a. OApp.
+ *
+ * For purposes of readability and to avoid overabstraction on the user end,
+ * the names are set to be `contracts` rather than `nodes` and `connections` rather than `edges`
+ */
+export interface OmniGraph<TNodeConfig = unknown, TEdgeConfig = unknown> {
+    contracts: OmniNode<TNodeConfig>[]
+    connections: OmniEdge<TEdgeConfig>[]
+}

packages/ua-utils/test/__utils__/arbitraries.ts

@@ -0,0 +1,18 @@
+import fc from 'fast-check'
+import { EndpointId } from '@layerzerolabs/lz-definitions'
+import { ENDPOINT_IDS } from './constants'
+import { OmniNodeCoordinate, OmniEdgeCoordinates } from '@/omnigraph/types'
+
+export const addressArbitrary = fc.string()
+
+export const endpointArbitrary: fc.Arbitrary<EndpointId> = fc.constantFrom(...ENDPOINT_IDS)
+
+export const coordinateArbitrary: fc.Arbitrary<OmniNodeCoordinate> = fc.record({
+    eid: endpointArbitrary,
+    address: addressArbitrary,
+})
+
+export const coordinatesArbitrary: fc.Arbitrary<OmniEdgeCoordinates> = fc.record({
+    from: coordinateArbitrary,
+    to: coordinateArbitrary,
+})

packages/ua-utils/test/__utils__/constants.ts

@@ -0,0 +1,6 @@
+import { EndpointId } from '@layerzerolabs/lz-definitions'
+import { EndpointIdSchema } from '../../src/omnigraph/schema'
+
+export const ENDPOINT_IDS = Object.values(EndpointId).filter(
+    (value): value is EndpointId => EndpointIdSchema.safeParse(value).success
+)