🥶 Slightly BelowZero

packages/ua-utils-evm/.eslintignore

@@ -0,0 +1,2 @@
+dist
+node_modules

packages/ua-utils-evm/.mocharc.json

@@ -0,0 +1,5 @@
+{
+    "extensions": ["ts"],
+    "spec": ["**/*.test.*"],
+    "loader": "ts-node/esm"
+}

packages/ua-utils-evm/.prettierignore

@@ -0,0 +1,2 @@
+dist/
+node_modules/

packages/ua-utils-evm/README.md

@@ -0,0 +1,27 @@
+<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-evm</h1>
+
+<!-- The badges section -->
+<p align="center">
+  <!-- Shields.io NPM published package version -->
+  <a href="https://www.npmjs.com/package/@layerzerolabs/ua-utils-evm"><img alt="NPM Version" src="https://img.shields.io/npm/v/@layerzerolabs/ua-utils-evm"/></a>
+  <!-- Shields.io NPM downloads -->
+  <a href="https://www.npmjs.com/package/@layerzerolabs/ua-utils-evm"><img alt="Downloads" src="https://img.shields.io/npm/dm/@layerzerolabs/ua-utils-evm"/></a>
+  <!-- Shields.io license badge -->
+  <a href="https://www.npmjs.com/package/@layerzerolabs/ua-utils-evm"><img alt="NPM License" src="https://img.shields.io/npm/l/@layerzerolabs/ua-utils-evm"/></a>
+</p>
+
+## Installation
+
+```bash
+yarn add @layerzerolabs/ua-utils-evm
+
+pnpm add @layerzerolabs/ua-utils-evm
+
+npm install @layerzerolabs/ua-utils-evm
+```

packages/ua-utils-evm/package.json

@@ -0,0 +1,49 @@
+{
+    "name": "@layerzerolabs/ua-utils-evm",
+    "description": "Utilities for working with LayerZero EVM projects",
+    "version": "0.0.1",
+    "license": "MIT",
+    "private": true,
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "module": "./dist/index.mjs",
+    "exports": {
+        "types": "./dist/index.d.ts",
+        "require": "./dist/index.js",
+        "import": "./dist/index.mjs"
+    },
+    "files": [
+        "./dist/index.*"
+    ],
+    "scripts": {
+        "build": "npx tsup",
+        "clean": "rm -rf dist",
+        "dev": "npx tsup --watch",
+        "lint": "npx eslint '**/*.{js,ts,json}'",
+        "prebuild": "npx tsc --noEmit -p tsconfig.build.json",
+        "test": "mocha --parallel"
+    },
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/LayerZero-Labs/lz-utils.git",
+        "directory": "packages/ua-utils-evm"
+    },
+    "devDependencies": {
+        "@ethersproject/contracts": "5.7.0",
+        "@layerzerolabs/lz-definitions": "~1.5.58",
+        "@layerzerolabs/ua-utils": "~0.1.0",
+        "@types/mocha": "^10.0.1",
+        "@types/sinon": "^17.0.2",
+        "chai": "^4.3.10",
+        "mocha": "^10.2.0",
+        "sinon": "^17.0.1",
+        "ts-node": "^10.9.1",
+        "tsup": "~7.2.0",
+        "typescript": "^5.2.2"
+    },
+    "peerDependencies": {
+        "@ethersproject/contracts": "5.7.0",
+        "@layerzerolabs/lz-definitions": "~1.5.58",
+        "@layerzerolabs/ua-utils": "~0.1.0"
+    }
+}

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

@@ -0,0 +1 @@
+export * from "./oapp"

packages/ua-utils-evm/src/oapp.ts

@@ -0,0 +1,14 @@
+import { Contract } from "@ethersproject/contracts"
+import { GetPropertyValue, createProperty } from "@layerzerolabs/ua-utils"
+import { EndpointId } from "@layerzerolabs/lz-definitions"
+
+type SetPeerConfigurableContext = [oapp: Contract, endpointId: EndpointId]
+
+type SetPeerConfigurableValue = string
+
+export const createSetPeerProperty = (desired: GetPropertyValue<SetPeerConfigurableContext, SetPeerConfigurableValue>) =>
+    createProperty<SetPeerConfigurableContext, SetPeerConfigurableValue>({
+        desired,
+        get: (oapp, endpointId) => oapp.peers(endpointId),
+        set: (oapp, endpointId, peer) => oapp.setPeer(endpointId, peer),
+    })

packages/ua-utils-evm/test/oapp.test.ts

@@ -0,0 +1,30 @@
+import { Contract } from "@ethersproject/contracts"
+import { EndpointId } from "@layerzerolabs/lz-definitions"
+import { expect } from "chai"
+import { describe } from "mocha"
+import sinon from "sinon"
+import { createSetPeerProperty } from "../src/oapp"
+import { isMisconfigured } from "@layerzerolabs/ua-utils"
+
+describe("oapp", () => {
+    describe("createSetPeerProperty", () => {
+        it("should check peers and return Misconfigured if they don't match", async () => {
+            const peers = sinon.stub().resolves("peer-not-set")
+            const setPeer = sinon.stub().resolves("okay")
+            const oapp = { peers, setPeer } as unknown as Contract
+
+            const desired = (oapp: Contract, endpointId: EndpointId) => `peer-on-${endpointId}`
+            const configurable = createSetPeerProperty(desired)
+            const state = await configurable(oapp, EndpointId.AAVEGOTCHI_TESTNET)
+
+            expect(isMisconfigured(state)).to.be.true
+            expect(state.value).to.eql("peer-not-set")
+            expect(state.desiredValue).to.eql(`peer-on-${EndpointId.AAVEGOTCHI_TESTNET}`)
+
+            const result = await state.configure?.()
+
+            expect(result).to.eql("okay")
+            expect(setPeer.calledOnceWith(EndpointId.AAVEGOTCHI_TESTNET, `peer-on-${EndpointId.AAVEGOTCHI_TESTNET}`)).to.be.true
+        })
+    })
+})

packages/ua-utils-evm/tsconfig.build.json

@@ -0,0 +1,4 @@
+{
+    "extends": "./tsconfig.json",
+    "exclude": ["node_modules", "dist", "test"]
+}

packages/ua-utils-evm/tsconfig.json

@@ -0,0 +1,9 @@
+{
+    "extends": "../../tsconfig.json",
+    "exclude": ["dist", "node_modules"],
+    "include": ["src", "test", "*.config.ts"],
+    "compilerOptions": {
+        "module": "commonjs",
+        "types": ["node", "mocha"]
+    }
+}

packages/ua-utils-evm/tsup.config.ts

@@ -0,0 +1,12 @@
+import { defineConfig } from "tsup"
+
+export default defineConfig({
+    entry: ["src/index.ts"],
+    outDir: "./dist",
+    clean: true,
+    dts: true,
+    sourcemap: true,
+    splitting: false,
+    treeshake: true,
+    format: ["esm", "cjs"],
+})

packages/ua-utils/.eslintignore

@@ -0,0 +1,2 @@
+dist
+node_modules

packages/ua-utils/.mocharc.json

@@ -0,0 +1,5 @@
+{
+    "extensions": ["ts"],
+    "spec": ["**/*.test.*"],
+    "loader": "ts-node/esm"
+}

packages/ua-utils/.prettierignore

@@ -0,0 +1,2 @@
+dist/
+node_modules/

packages/ua-utils/README.md

@@ -0,0 +1,161 @@
+<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
+
+```bash
+yarn add @layerzerolabs/ua-utils
+
+pnpm add @layerzerolabs/ua-utils
+
+npm install @layerzerolabs/ua-utils
+```
+
+## Usage
+
+### `createProperty`
+
+Creates a `Property` object - an abstract wrapper around a getter and setter of a (typically contract) property.
+
+`Property` objects can be evaluated - this evaluation results in a `PropertyState` object which comes in two varieties:
+
+-   `Configured` object represents a property whose desired value matches the current, actual value
+-   `Misconfigured` object represents a property whose desired value does not match the current value. It can be further executed using its `configure` method to set the desired property value
+
+```typescript
+import type { Contract } from "@etherspropject/contracts"
+import { createProperty, isMisconfigured } from "@layerzerolabs/ua-utils"
+
+// In this example we'll creating a property that is executed within a context of a contract
+//
+// What this means is that the property requires a contract to be evaluated. This context
+// is then passed to the getter, setter and the desired value getter
+const myContractProperty = createProperty({
+    get: (contract: Contract) => contract.getFavouriteAddress(),
+    set: (contract: Contract, favouriteAddress: string) => contract.setFavouriteAddress(favouriteAddress),
+    desired: (contract: Contract) => "0x00000000219ab540356cbb839cbe05303d7705fa",
+})
+
+// Let's pretend we have a contract at hand
+declare const myContract: Contract
+
+// We'll evaluate this property by passing myContract in. This contract will then be passed
+// to the getter, setter and desired value getter
+//
+// The result of this evaluation is a PropertyState object
+const state = await myContractProperty(myContract)
+
+// This package comes with two type narrowing utilities for working with PropertyState objects:
+//
+// - isConfigured
+// - isMisconfigured
+//
+// Using these we can discern between the two varieties of PropertyState
+if (isMisconfigured(state)) {
+    await state.configure()
+}
+```
+
+In the example above we used a simple `Contract` object as our context. We can use arbitrary context as the following example shows:
+
+```typescript
+import { createProperty, isMisconfigured } from "@layerzerolabs/ua-utils"
+
+const myContractPropertyWithParams = createProperty({
+    get: (contract: Contract, when: number, where: string) => contract.getFavouriteAddress(when, where),
+    set: (contract: Contract, when: number, where: string, favouriteAddress: string) =>
+        contract.setFavouriteAddress(when, where, favouriteAddress),
+    desired: (contract: Contract, when: number, where: string) => "0x00000000219ab540356cbb839cbe05303d7705fa",
+})
+
+// We'll again pretend we have a contract at hand
+declare const myContract: Contract
+const when = Date.now()
+const where = "Antractica"
+
+// We'll evaluate this property by passing the required context in - in this case
+// the context consists of a contract, a numeric value and a string value
+//
+// The result of this evaluation is a PropertyState object
+const state = await myContractPropertyWithParams(myContract, when, where)
+
+// The execution goes just like before
+if (isMisconfigured(state)) {
+    await state.configure()
+}
+```
+
+The `createProperty` is completely abstract though and does not require us to get a single contract property or set it directly. in the following, completely made-up example we'll get multiple properties at once and instead of setting them, we'll just populate the transactions for further executions:
+
+```typescript
+import { createProperty, isMisconfigured } from "@layerzerolabs/ua-utils"
+
+const myContractPropertyWithParams = createProperty({
+    get: (contract: Contract) => Promise.all([contract.getA(), contract.getB()]),
+    set: (contract: Contract, [a, b, c]) => [
+        contract.pupulateTransaction.setA(a),
+        contract.pupulateTransaction.setB(b),
+        contract.pupulateTransaction.setC(c),
+    ],
+    desired: (contract: Contract) => [7, 11, 17],
+})
+
+// We'll again pretend we have a contract at hand
+declare const myContract: Contract
+
+// We'll evaluate this property by passing the required context in - in this case
+// the context consists of a contract, a numeric value and a string value
+//
+// The result of this evaluation is a PropertyState object
+const state = await myContractPropertyWithParams(myContract, when, where)
+
+// The execution goes just like before
+if (isMisconfigured(state)) {
+    const transactions = await state.configure()
+
+    // We now have a list of populated transactions to execute
+}
+```
+
+### `isConfigured`
+
+Helper type assertion utility that narrows down the `PropertyState` type to `Configured`:
+
+```typescript
+import { PropertyState, isConfigured } from "@layerzerolabs/ua-utils"
+
+declare const state: PropertyState
+
+if (isConfigured(state)) {
+    // state is now Configured, no action is needed as the property is in its desired state
+}
+```
+
+### `isMisconfigured`
+
+Helper type assertion utility that narrows down the `PropertyState` type to `Misconfigured`:
+
+```typescript
+import { PropertyState, isMisconfigured } from "@layerzerolabs/ua-utils"
+
+declare const state: PropertyState
+
+if (isMisconfigured(state)) {
+    // state is now Misconfigured, we can e.g. call .configure
+}
+```

packages/ua-utils/package.json

@@ -0,0 +1,41 @@
+{
+    "name": "@layerzerolabs/ua-utils",
+    "description": "Utilities for working with LayerZero projects",
+    "version": "0.1.0",
+    "license": "MIT",
+    "private": true,
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "module": "./dist/index.mjs",
+    "exports": {
+        "types": "./dist/index.d.ts",
+        "require": "./dist/index.js",
+        "import": "./dist/index.mjs"
+    },
+    "files": [
+        "./dist/index.*"
+    ],
+    "scripts": {
+        "build": "npx tsup",
+        "clean": "rm -rf dist",
+        "dev": "npx tsup --watch",
+        "lint": "npx eslint '**/*.{js,ts,json}'",
+        "prebuild": "npx tsc --noEmit -p tsconfig.build.json",
+        "test": "mocha --parallel"
+    },
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/LayerZero-Labs/lz-utils.git",
+        "directory": "packages/ua-utils"
+    },
+    "devDependencies": {
+        "@types/mocha": "^10.0.1",
+        "@types/sinon": "^17.0.2",
+        "chai": "^4.3.10",
+        "mocha": "^10.2.0",
+        "sinon": "^17.0.1",
+        "ts-node": "^10.9.1",
+        "tsup": "~7.2.0",
+        "typescript": "^5.2.2"
+    }
+}

packages/ua-utils/src/index.ts

@@ -0,0 +1 @@
+export * from "./property"