@hyperlane-xyz/registry 1.1.2 → 1.3.0

package/dist/registry/{LocalRegistry.js → FileSystemRegistry.js}

@@ -4,11 +4,16 @@ import { parse as yamlParse } from 'yaml';
 import { SCHEMA_REF } from '../consts.js';
 import { ChainAddressesSchema } from '../types.js';
 import { toYamlString } from '../utils.js';
-import { BaseRegistry, CHAIN_FILE_REGEX } from './BaseRegistry.js';
+import { CHAIN_FILE_REGEX } from './BaseRegistry.js';
 import { RegistryType, } from './IRegistry.js';
+import { SynchronousRegistry } from './SynchronousRegistry.js';
 import { warpConfigToWarpAddresses } from './warp-utils.js';
-export class LocalRegistry extends BaseRegistry {
-    type = RegistryType.Local;
+/**
+ * A registry that uses a local file system path as its data source.
+ * Requires file system access so it cannot be used in the browser.
+ */
+export class FileSystemRegistry extends SynchronousRegistry {
+    type = RegistryType.FileSystem;
     constructor(options) {
         super(options);
     }
@@ -29,9 +34,6 @@ export class LocalRegistry extends BaseRegistry {
         // TODO add handling for deployment artifact files here too
         return (this.listContentCache = { chains, deployments: {} });
     }
-    getChains() {
-        return Object.keys(this.listRegistryContent().chains);
-    }
     getMetadata() {
         if (this.metadataCache)
             return this.metadataCache;
@@ -45,10 +47,6 @@ export class LocalRegistry extends BaseRegistry {
         }
         return (this.metadataCache = chainMetadata);
     }
-    getChainMetadata(chainName) {
-        const metadata = this.getMetadata();
-        return metadata[chainName] ?? null;
-    }
     getAddresses() {
         if (this.addressCache)
             return this.addressCache;
@@ -62,34 +60,10 @@ export class LocalRegistry extends BaseRegistry {
         }
         return (this.addressCache = chainAddresses);
     }
-    getChainAddresses(chainName) {
-        const addresses = this.getAddresses();
-        return addresses[chainName] ?? null;
-    }
-    addChain(chain) {
-        const currentChains = this.listRegistryContent().chains;
-        if (currentChains[chain.chainName])
-            throw new Error(`Chain ${chain.chainName} already exists in registry`);
-        this.createOrUpdateChain(chain);
-    }
-    updateChain(chain) {
-        const currentChains = this.listRegistryContent();
-        if (!currentChains.chains[chain.chainName]) {
-            this.logger.debug(`Chain ${chain.chainName} not found in registry, adding it now`);
-        }
-        this.createOrUpdateChain(chain);
-    }
     removeChain(chainName) {
-        const currentChains = this.listRegistryContent().chains;
-        if (!currentChains[chainName])
-            throw new Error(`Chain ${chainName} does not exist in registry`);
-        this.removeFiles(Object.values(currentChains[chainName]));
-        if (this.listContentCache?.chains[chainName])
-            delete this.listContentCache.chains[chainName];
-        if (this.metadataCache?.[chainName])
-            delete this.metadataCache[chainName];
-        if (this.addressCache?.[chainName])
-            delete this.addressCache[chainName];
+        const chainFiles = this.listRegistryContent().chains[chainName];
+        super.removeChain(chainName);
+        this.removeFiles(Object.values(chainFiles));
     }
     listFiles(dirPath) {
         if (!fs.existsSync(dirPath))

package/dist/registry/GithubRegistry.d.ts

@@ -9,6 +9,11 @@ export interface GithubRegistryOptions {
     authToken?: string;
     logger?: Logger;
 }
+/**
+ * A registry that uses a github repository as its data source.
+ * Reads are performed via the github API and github's raw content URLs.
+ * Writes are not yet supported (TODO)
+ */
 export declare class GithubRegistry extends BaseRegistry implements IRegistry {
     readonly type = RegistryType.Github;
     readonly url: URL;

package/dist/registry/GithubRegistry.js

@@ -3,6 +3,11 @@ import { DEFAULT_GITHUB_REGISTRY, GITHUB_FETCH_CONCURRENCY_LIMIT } from '../cons
 import { concurrentMap } from '../utils.js';
 import { BaseRegistry, CHAIN_FILE_REGEX } from './BaseRegistry.js';
 import { RegistryType, } from './IRegistry.js';
+/**
+ * A registry that uses a github repository as its data source.
+ * Reads are performed via the github API and github's raw content URLs.
+ * Writes are not yet supported (TODO)
+ */
 export class GithubRegistry extends BaseRegistry {
     type = RegistryType.Github;
     url;

package/dist/registry/IRegistry.d.ts

@@ -11,7 +11,9 @@ export interface RegistryContent {
 }
 export declare enum RegistryType {
     Github = "github",
-    Local = "local"
+    FileSystem = "filesystem",
+    Merged = "merged",
+    Partial = "partial"
 }
 export interface IRegistry {
     type: RegistryType;
@@ -35,4 +37,5 @@ export interface IRegistry {
     }): MaybePromise<void>;
     removeChain(chain: ChainName): MaybePromise<void>;
     addWarpRoute(config: WarpCoreConfig): MaybePromise<void>;
+    merge(otherRegistry: IRegistry): IRegistry;
 }

package/dist/registry/IRegistry.js

@@ -1,5 +1,7 @@
 export var RegistryType;
 (function (RegistryType) {
     RegistryType["Github"] = "github";
-    RegistryType["Local"] = "local";
+    RegistryType["FileSystem"] = "filesystem";
+    RegistryType["Merged"] = "merged";
+    RegistryType["Partial"] = "partial";
 })(RegistryType || (RegistryType = {}));

package/dist/registry/MergedRegistry.d.ts

@@ -0,0 +1,43 @@
+import type { Logger } from 'pino';
+import type { ChainMap, ChainMetadata, ChainName, WarpCoreConfig } from '@hyperlane-xyz/sdk';
+import { ChainAddresses } from '../types.js';
+import { IRegistry, RegistryContent, RegistryType } from './IRegistry.js';
+export interface MergedRegistryOptions {
+    registries: Array<IRegistry>;
+    logger?: Logger;
+}
+/**
+ * A registry that accepts multiple sub-registries.
+ * Read methods are performed on all sub-registries and the results are merged.
+ * Write methods are performed on all sub-registries.
+ * Can be created manually or by calling `.merge()` on an existing registry.
+ */
+export declare class MergedRegistry implements IRegistry {
+    readonly type = RegistryType.Merged;
+    readonly uri = "__merged_registry__";
+    readonly registries: Array<IRegistry>;
+    protected readonly logger: Logger;
+    constructor({ registries, logger }: MergedRegistryOptions);
+    listRegistryContent(): Promise<RegistryContent>;
+    getChains(): Promise<Array<ChainName>>;
+    getMetadata(): Promise<ChainMap<ChainMetadata>>;
+    getChainMetadata(chainName: ChainName): Promise<ChainMetadata | null>;
+    getAddresses(): Promise<ChainMap<ChainAddresses>>;
+    getChainAddresses(chainName: ChainName): Promise<ChainAddresses | null>;
+    getChainLogoUri(chainName: ChainName): Promise<string | null>;
+    addChain(chain: {
+        chainName: ChainName;
+        metadata?: ChainMetadata;
+        addresses?: ChainAddresses;
+    }): Promise<void>;
+    updateChain(chain: {
+        chainName: ChainName;
+        metadata?: ChainMetadata;
+        addresses?: ChainAddresses;
+    }): Promise<void>;
+    removeChain(chain: ChainName): Promise<void>;
+    addWarpRoute(config: WarpCoreConfig): Promise<void>;
+    protected multiRegistryRead<R>(readFn: (registry: IRegistry) => Promise<R> | R): Promise<(Awaited<R> | Awaited<R>)[]>;
+    protected multiRegistryWrite(writeFn: (registry: IRegistry) => Promise<void>, logMsg: string): Promise<void>;
+    merge(otherRegistry: IRegistry): IRegistry;
+}

package/dist/registry/MergedRegistry.js

@@ -0,0 +1,88 @@
+import { objMerge } from '../utils.js';
+import { RegistryType } from './IRegistry.js';
+/**
+ * A registry that accepts multiple sub-registries.
+ * Read methods are performed on all sub-registries and the results are merged.
+ * Write methods are performed on all sub-registries.
+ * Can be created manually or by calling `.merge()` on an existing registry.
+ */
+export class MergedRegistry {
+    type = RegistryType.Merged;
+    uri = '__merged_registry__';
+    registries;
+    logger;
+    constructor({ registries, logger }) {
+        if (!registries.length)
+            throw new Error('At least one registry URI is required');
+        this.registries = registries;
+        // @ts-ignore
+        this.logger = logger || console;
+    }
+    async listRegistryContent() {
+        const results = await this.multiRegistryRead((r) => r.listRegistryContent());
+        return results.reduce((acc, content) => objMerge(acc, content), {
+            chains: {},
+            deployments: {},
+        });
+    }
+    async getChains() {
+        return Object.keys(await this.getMetadata());
+    }
+    async getMetadata() {
+        const results = await this.multiRegistryRead((r) => r.getMetadata());
+        return results.reduce((acc, content) => objMerge(acc, content), {});
+    }
+    async getChainMetadata(chainName) {
+        return (await this.getMetadata())[chainName] || null;
+    }
+    async getAddresses() {
+        const results = await this.multiRegistryRead((r) => r.getAddresses());
+        return results.reduce((acc, content) => objMerge(acc, content), {});
+    }
+    async getChainAddresses(chainName) {
+        return (await this.getAddresses())[chainName] || null;
+    }
+    async getChainLogoUri(chainName) {
+        const results = await this.multiRegistryRead((r) => r.getChainLogoUri(chainName));
+        return results.find((uri) => !!uri) || null;
+    }
+    async addChain(chain) {
+        return this.multiRegistryWrite(async (registry) => await registry.addChain(chain), `adding chain ${chain.chainName}`);
+    }
+    async updateChain(chain) {
+        return this.multiRegistryWrite(async (registry) => await registry.updateChain(chain), `updating chain ${chain.chainName}`);
+    }
+    async removeChain(chain) {
+        return this.multiRegistryWrite(async (registry) => await registry.removeChain(chain), `removing chain ${chain}`);
+    }
+    async addWarpRoute(config) {
+        return this.multiRegistryWrite(async (registry) => await registry.addWarpRoute(config), 'adding warp route');
+    }
+    multiRegistryRead(readFn) {
+        return Promise.all(this.registries.map(readFn));
+    }
+    async multiRegistryWrite(writeFn, logMsg) {
+        for (const registry of this.registries) {
+            // TODO remove this when GithubRegistry supports write methods
+            if (registry.type === RegistryType.Github) {
+                this.logger.warn(`Skipping ${logMsg} at ${registry.type} registry`);
+                continue;
+            }
+            try {
+                this.logger.info(`Now ${logMsg} at ${registry.type} registry at ${registry.uri}`);
+                await writeFn(registry);
+                this.logger.info(`Done ${logMsg} at ${registry.type} registry`);
+            }
+            catch (error) {
+                // To prevent loss of artifacts, MergedRegistry write methods are failure tolerant
+                this.logger.error(`Failure ${logMsg} at ${registry.type} registry`, error);
+            }
+        }
+    }
+    merge(otherRegistry) {
+        return new MergedRegistry({
+            registries: [...this.registries, otherRegistry],
+            logger: this.logger,
+        });
+    }
+}

package/dist/registry/PartialRegistry.d.ts

@@ -0,0 +1,30 @@
+import type { Logger } from 'pino';
+import type { ChainMap, ChainMetadata, ChainName, WarpCoreConfig } from '@hyperlane-xyz/sdk';
+import { ChainAddresses } from '../types.js';
+import { IRegistry, RegistryContent, RegistryType } from './IRegistry.js';
+import { SynchronousRegistry } from './SynchronousRegistry.js';
+/**
+ * A registry that accepts partial data, such as incomplete chain metadata or addresses.
+ * Useful for merging with other registries force overrides of subsets of data.
+ */
+export interface PartialRegistryOptions {
+    chainMetadata?: ChainMap<Partial<ChainMetadata>>;
+    chainAddresses?: ChainMap<Partial<ChainAddresses>>;
+    logger?: Logger;
+}
+export declare class PartialRegistry extends SynchronousRegistry implements IRegistry {
+    readonly type = RegistryType.Partial;
+    chainMetadata: ChainMap<Partial<ChainMetadata>>;
+    chainAddresses: ChainMap<Partial<ChainAddresses>>;
+    constructor({ chainMetadata, chainAddresses, logger }: PartialRegistryOptions);
+    listRegistryContent(): RegistryContent;
+    getMetadata(): ChainMap<ChainMetadata>;
+    getAddresses(): ChainMap<ChainAddresses>;
+    removeChain(chainName: ChainName): void;
+    addWarpRoute(_config: WarpCoreConfig): void;
+    protected createOrUpdateChain(chain: {
+        chainName: ChainName;
+        metadata?: ChainMetadata;
+        addresses?: ChainAddresses;
+    }): void;
+}

package/dist/registry/PartialRegistry.js

@@ -0,0 +1,50 @@
+import { RegistryType } from './IRegistry.js';
+import { SynchronousRegistry } from './SynchronousRegistry.js';
+const PARTIAL_URI_PLACEHOLDER = '__partial_registry__';
+export class PartialRegistry extends SynchronousRegistry {
+    type = RegistryType.Partial;
+    chainMetadata;
+    chainAddresses;
+    constructor({ chainMetadata, chainAddresses, logger }) {
+        super({ uri: PARTIAL_URI_PLACEHOLDER, logger });
+        this.chainMetadata = chainMetadata || {};
+        this.chainAddresses = chainAddresses || {};
+    }
+    listRegistryContent() {
+        const chains = {};
+        Object.keys(this.chainMetadata).forEach((c) => {
+            chains[c] ||= {};
+            chains[c].metadata = PARTIAL_URI_PLACEHOLDER;
+        });
+        Object.keys(this.chainAddresses).forEach((c) => {
+            chains[c] ||= {};
+            chains[c].addresses = PARTIAL_URI_PLACEHOLDER;
+        });
+        return {
+            chains,
+            deployments: {},
+        };
+    }
+    getMetadata() {
+        return this.chainMetadata;
+    }
+    getAddresses() {
+        return this.chainAddresses;
+    }
+    removeChain(chainName) {
+        super.removeChain(chainName);
+        if (this.chainMetadata?.[chainName])
+            delete this.chainMetadata[chainName];
+        if (this.chainAddresses?.[chainName])
+            delete this.chainAddresses[chainName];
+    }
+    addWarpRoute(_config) {
+        throw new Error('Method not implemented.');
+    }
+    createOrUpdateChain(chain) {
+        if (chain.metadata)
+            this.chainMetadata[chain.chainName] = chain.metadata;
+        if (chain.addresses)
+            this.chainAddresses[chain.chainName] = chain.addresses;
+    }
+}

package/dist/registry/SynchronousRegistry.d.ts

@@ -0,0 +1,34 @@
+import type { ChainMap, ChainMetadata, ChainName, WarpCoreConfig } from '@hyperlane-xyz/sdk';
+import { ChainAddresses } from '../types.js';
+import { BaseRegistry } from './BaseRegistry.js';
+import { IRegistry, RegistryContent } from './IRegistry.js';
+/**
+ * Shared code for sync registries like the FileSystem and Partial registries.
+ * This is required because of the inconsistent sync/async methods across registries.
+ * If the Infra package can be updated to work with async-only methods, this code can be moved to the BaseRegistry class.
+ */
+export declare abstract class SynchronousRegistry extends BaseRegistry implements IRegistry {
+    abstract listRegistryContent(): RegistryContent;
+    getChains(): Array<ChainName>;
+    abstract getMetadata(): ChainMap<ChainMetadata>;
+    getChainMetadata(chainName: ChainName): ChainMetadata | null;
+    abstract getAddresses(): ChainMap<ChainAddresses>;
+    getChainAddresses(chainName: ChainName): ChainAddresses | null;
+    addChain(chain: {
+        chainName: ChainName;
+        metadata?: ChainMetadata;
+        addresses?: ChainAddresses;
+    }): void;
+    updateChain(chain: {
+        chainName: ChainName;
+        metadata?: ChainMetadata;
+        addresses?: ChainAddresses;
+    }): void;
+    removeChain(chainName: ChainName): void;
+    abstract addWarpRoute(config: WarpCoreConfig): void;
+    protected abstract createOrUpdateChain(chain: {
+        chainName: ChainName;
+        metadata?: ChainMetadata;
+        addresses?: ChainAddresses;
+    }): void;
+}

package/dist/registry/SynchronousRegistry.js

@@ -0,0 +1,41 @@
+import { BaseRegistry } from './BaseRegistry.js';
+/**
+ * Shared code for sync registries like the FileSystem and Partial registries.
+ * This is required because of the inconsistent sync/async methods across registries.
+ * If the Infra package can be updated to work with async-only methods, this code can be moved to the BaseRegistry class.
+ */
+export class SynchronousRegistry extends BaseRegistry {
+    getChains() {
+        return Object.keys(this.listRegistryContent().chains);
+    }
+    getChainMetadata(chainName) {
+        return this.getMetadata()[chainName] || null;
+    }
+    getChainAddresses(chainName) {
+        return this.getAddresses()[chainName] || null;
+    }
+    addChain(chain) {
+        const currentChains = this.listRegistryContent().chains;
+        if (currentChains[chain.chainName])
+            throw new Error(`Chain ${chain.chainName} already exists in registry`);
+        this.createOrUpdateChain(chain);
+    }
+    updateChain(chain) {
+        const currentChains = this.listRegistryContent();
+        if (!currentChains.chains[chain.chainName]) {
+            this.logger.debug(`Chain ${chain.chainName} not found in registry, adding it now`);
+        }
+        this.createOrUpdateChain(chain);
+    }
+    removeChain(chainName) {
+        const currentChains = this.listRegistryContent().chains;
+        if (!currentChains[chainName])
+            throw new Error(`Chain ${chainName} does not exist in registry`);
+        if (this.listContentCache?.chains[chainName])
+            delete this.listContentCache.chains[chainName];
+        if (this.metadataCache?.[chainName])
+            delete this.metadataCache[chainName];
+        if (this.addressCache?.[chainName])
+            delete this.addressCache[chainName];
+    }
+}

package/dist/utils.d.ts

@@ -1,2 +1,4 @@
 export declare function toYamlString(data: any, prefix?: string): string;
 export declare function concurrentMap<A, B>(concurrency: number, xs: A[], mapFn: (val: A, idx: number) => Promise<B>): Promise<B[]>;
+export declare function isObject(item: any): any;
+export declare function objMerge(a: Record<string, any>, b: Record<string, any>, max_depth?: number): any;

package/dist/utils.js

@@ -13,3 +13,34 @@ export async function concurrentMap(concurrency, xs, mapFn) {
     }
     return res;
 }
+export function isObject(item) {
+    return item && typeof item === 'object' && !Array.isArray(item);
+}
+// Recursively merges b into a
+// Where there are conflicts, b takes priority over a
+export function objMerge(a, b, max_depth = 10) {
+    if (max_depth === 0) {
+        throw new Error('objMerge tried to go too deep');
+    }
+    if (isObject(a) && isObject(b)) {
+        const ret = {};
+        const aKeys = new Set(Object.keys(a));
+        const bKeys = new Set(Object.keys(b));
+        const allKeys = new Set([...aKeys, ...bKeys]);
+        for (const key of allKeys.values()) {
+            if (aKeys.has(key) && bKeys.has(key)) {
+                ret[key] = objMerge(a[key], b[key], max_depth - 1);
+            }
+            else if (aKeys.has(key)) {
+                ret[key] = a[key];
+            }
+            else {
+                ret[key] = b[key];
+            }
+        }
+        return ret;
+    }
+    else {
+        return b ? b : a;
+    }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@hyperlane-xyz/registry",
   "description": "A collection of configs, artifacts, and schemas for Hyperlane",
-  "version": "1.1.2",
+  "version": "1.3.0",
   "dependencies": {
     "yaml": "^2",
     "zod": "^3.21.2"
@@ -16,6 +16,7 @@
     "chai": "^4.3.6",
     "eslint": "^9.0.0",
     "eslint-config-prettier": "^9.1.0",
+    "eslint-plugin-yml": "^1.14.0",
     "husky": "^9.0.11",
     "lint-staged": "^15.2.2",
     "mocha": "^10.2.0",
@@ -30,7 +31,7 @@
     ".": "./dist/index.js",
     "./chains/schema.json": "./dist/chains/schema.json",
     "./chains/*": "./dist/chains/*",
-    "./local": "./dist/index-local.js"
+    "./fs": "./dist/index-fs.js"
   },
   "types": "./dist/index.d.ts",
   "typesVersions": {
@@ -57,14 +58,15 @@
   ],
   "license": "MIT",
   "scripts": {
-    "clean": "rm -rf ./dist ./tmp",
     "build": "tsx ./scripts/build.ts && tsc --project tsconfig.publish.json",
-    "lint": "eslint ./src/",
+    "clean": "rm -rf ./dist ./tmp",
+    "lint": "eslint ./src/ ./chains ./deployments",
+    "lint:fix": "yarn lint --fix",
     "prettier": "prettier --write ./chains ./deployments",
-    "test:unit": "yarn build && mocha --config .mocharc.json './test/unit/*.test.ts' --exit",
-    "test:health": "yarn build && mocha --config .mocharc.json './test/health/*.test.ts' --exit",
     "prepare": "husky",
     "release": "yarn build && yarn changeset publish",
+    "test:unit": "yarn build && mocha --config .mocharc.json './test/unit/*.test.ts' --exit",
+    "test:health": "yarn build && mocha --config .mocharc.json './test/health/*.test.ts' --exit",
     "version:prepare": "yarn changeset version && yarn install --no-immutable",
     "version:check": "yarn changeset status"
   },

package/dist/index-local.d.ts

@@ -1 +0,0 @@
-export { LocalRegistry } from './registry/LocalRegistry.js';