@raac/rpc 2.0.0-beta.0 → 2.0.0-beta.1

package/dist/RPCLibrary.js

@@ -98,6 +98,7 @@ const getContractAddress_1 = __importDefault(require("./contracts/getContractAdd
 const getContract_1 = __importDefault(require("./contracts/getContract"));
 const findContract_1 = require("./contracts/findContract");
 const decodeCall_1 = require("./contracts/decodeCall");
+const resolveName_1 = require("./contracts/resolveName");
 // House Prices
 const getLatestPrice_1 = __importDefault(require("./contracts/housePrices/getLatestPrice"));
 const setOracle_1 = __importDefault(require("./contracts/housePrices/setOracle"));
@@ -457,6 +458,8 @@ class RPCLibrary {
             getContract: getContract_1.default,
             findContract: findContract_1.findContract,
             decodeCall: decodeCall_1.decodeCall,
+            resolveName: resolveName_1.resolveName,
+            resolveNames: resolveName_1.resolveNames,
             feeCollector: {
                 claimRewardFromPool: claimRewardFromPool_1.default,
             },

package/dist/configs/registry/1.json

@@ -0,0 +1 @@
+{}

package/dist/configs/registry/11155111.json

@@ -0,0 +1 @@
+{}

package/dist/configs/registry/17000.json

@@ -0,0 +1 @@
+{}

package/dist/configs/registry/18453.json

@@ -0,0 +1 @@
+{}

package/dist/configs/registry/8453.json

@@ -0,0 +1 @@
+{}

package/dist/configs/registry/index.js

@@ -0,0 +1,24 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+// @ts-ignore
+const _1_json_1 = __importDefault(require("./1.json"));
+const _8453_json_1 = __importDefault(require("./8453.json"));
+const _17000_json_1 = __importDefault(require("./17000.json"));
+const _11155111_json_1 = __importDefault(require("./11155111.json"));
+const _18453_json_1 = __importDefault(require("./18453.json"));
+/**
+ * Curated, off-chain-known addresses per chain (wallets, external protocols),
+ * keyed by checksummed address. Empty until entries are reviewed and added -
+ * see resolveName.ts for why this ships empty rather than with guessed data.
+ */
+const registries = {
+    1: _1_json_1.default,
+    8453: _8453_json_1.default,
+    17000: _17000_json_1.default,
+    11155111: _11155111_json_1.default,
+    18453: _18453_json_1.default,
+};
+exports.default = registries;

package/dist/contracts/findContract.js

@@ -50,6 +50,21 @@ function listContracts(chainId) {
     }
     return found;
 }
+const contractsByAddress = new Map();
+/** Address -> entry index for a chain, built on first use. First match wins, as in `listContracts`. */
+function getContractIndex(chainId) {
+    const key = String(chainId);
+    let index = contractsByAddress.get(key);
+    if (!index) {
+        index = {};
+        for (const entry of listContracts(chainId)) {
+            if (!(entry.address in index))
+                index[entry.address] = entry;
+        }
+        contractsByAddress.set(key, index);
+    }
+    return index;
+}
 /**
  * Finds a contract by address in the chain config.
  * Reads the chain config only; no RPC call is made.
@@ -61,8 +76,7 @@ function listContracts(chainId) {
 const findContract = (chainId, address) => {
     if (!ethers_1.ethers.isAddress(address))
         return null;
-    const target = ethers_1.ethers.getAddress(address);
-    return listContracts(chainId).find((c) => c.address === target) ?? null;
+    return getContractIndex(chainId)[ethers_1.ethers.getAddress(address)] ?? null;
 };
 exports.findContract = findContract;
 exports.default = exports.findContract;

package/dist/contracts/resolveName.js

@@ -0,0 +1,128 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveName = resolveName;
+exports.resolveNames = resolveNames;
+const ethers_1 = require("ethers");
+const chains_1 = __importDefault(require("../configs/chains"));
+const findContract_1 = require("./findContract");
+const registry_1 = __importDefault(require("../configs/registry"));
+const ZERO_ADDRESS = "0x0000000000000000000000000000000000000000";
+const BURN_ADDRESS = "0x000000000000000000000000000000000000dEaD";
+/** Universal, chain-agnostic entries that do not belong in a per-chain registry file. */
+const BUILTIN_REGISTRY = {
+    [ZERO_ADDRESS]: { name: "None", kind: "external" },
+    [ethers_1.ethers.getAddress(BURN_ADDRESS)]: { name: "Burn", kind: "external" },
+};
+/** address -> { name, expiresAt } | null (a confirmed miss, cached too so a repeat lookup does not re-hit the network). */
+const ensCache = new Map();
+const ENS_TTL_MS = 60 * 60 * 1000;
+function contractInfoToAddressName(info) {
+    return {
+        address: info.address,
+        name: info.name,
+        kind: info.section === "gauges" ? "gauge" : "contract",
+        source: "config",
+    };
+}
+function lookupRegistry(chainId, address) {
+    const builtin = BUILTIN_REGISTRY[address];
+    if (builtin)
+        return { address, ...builtin, source: "registry" };
+    const registry = registry_1.default[String(chainId)];
+    const entry = registry?.[address];
+    if (!entry)
+        return null;
+    return { address, ...entry, source: "registry" };
+}
+async function lookupEns(address, provider) {
+    const cached = ensCache.get(address);
+    if (cached && cached.expiresAt > Date.now()) {
+        return cached.name ? { address, name: cached.name, kind: "ens", source: "ens" } : null;
+    }
+    try {
+        const runner = provider ?? new ethers_1.ethers.JsonRpcProvider(chains_1.default[1].rpcs[0]);
+        const ensName = await runner.lookupAddress(address);
+        // Forward-verify: an ENS reverse record is set by its owner and can point anywhere,
+        // so trust it only once the name's forward resolution points back to this address.
+        const verified = ensName && ethers_1.ethers.getAddress((await runner.resolveName(ensName)) ?? "") === address;
+        const name = verified ? ensName : null;
+        ensCache.set(address, { name, expiresAt: Date.now() + ENS_TTL_MS });
+        return name ? { address, name, kind: "ens", source: "ens" } : null;
+    }
+    catch {
+        // A broken or slow ENS lookup must not fail the rest of resolution.
+        return null;
+    }
+}
+/**
+ * Resolves an address to a readable name.
+ *
+ * Checks the chain config (via `findContract`), then a curated registry of
+ * off-chain-known addresses (wallets, external protocols), then - mainnet
+ * only, and only once the first two miss - an ENS reverse lookup, forward-
+ * verified against the name it returns.
+ *
+ * @param chainId - The chain/network to use.
+ * @param address - Any-case address.
+ * @param options - `ens: false` skips the ENS step; `provider` reuses an existing connection for it.
+ * @returns The resolved name, or null when nothing matches.
+ */
+async function resolveName(chainId, address, options) {
+    if (!ethers_1.ethers.isAddress(address))
+        return null;
+    const target = ethers_1.ethers.getAddress(address);
+    const configMatch = (0, findContract_1.findContract)(chainId, target);
+    if (configMatch)
+        return contractInfoToAddressName(configMatch);
+    const registryMatch = lookupRegistry(chainId, target);
+    if (registryMatch)
+        return registryMatch;
+    if (options?.ens === false || String(chainId) !== "1")
+        return null;
+    return lookupEns(target, options?.provider);
+}
+/**
+ * Batch form of {@link resolveName}. Config and registry lookups run
+ * synchronously per address; only addresses that fall through to ENS pay for
+ * a network round trip, and those run concurrently.
+ *
+ * @param chainId - The chain/network to use.
+ * @param addresses - Any-case addresses.
+ * @param options - Same as {@link resolveName}.
+ * @returns A map from the (checksummed) input address to its resolved name, or null.
+ */
+async function resolveNames(chainId, addresses, options) {
+    const result = {};
+    const pending = [];
+    for (const raw of addresses) {
+        if (!ethers_1.ethers.isAddress(raw))
+            continue;
+        const target = ethers_1.ethers.getAddress(raw);
+        const configMatch = (0, findContract_1.findContract)(chainId, target);
+        if (configMatch) {
+            result[target] = contractInfoToAddressName(configMatch);
+            continue;
+        }
+        const registryMatch = lookupRegistry(chainId, target);
+        if (registryMatch) {
+            result[target] = registryMatch;
+            continue;
+        }
+        if (options?.ens === false || String(chainId) !== "1") {
+            result[target] = null;
+            continue;
+        }
+        pending.push(target);
+    }
+    if (pending.length > 0) {
+        const ensResults = await Promise.all(pending.map((address) => lookupEns(address, options?.provider)));
+        pending.forEach((address, i) => {
+            result[address] = ensResults[i];
+        });
+    }
+    return result;
+}
+exports.default = resolveName;

package/dist/types/RPCLibrary.d.ts

@@ -44,6 +44,7 @@ import getContractAddress from "./contracts/getContractAddress";
 import getContract from "./contracts/getContract";
 import { findContract } from "./contracts/findContract";
 import { decodeCall } from "./contracts/decodeCall";
+import { resolveName, resolveNames } from "./contracts/resolveName";
 import getLatestPrice from "./contracts/housePrices/getLatestPrice";
 import setOracle from "./contracts/housePrices/setOracle";
 import tick from "./minter/tick";
@@ -338,6 +339,8 @@ declare class RPCLibrary {
         getContract: typeof getContract;
         findContract: typeof findContract;
         decodeCall: typeof decodeCall;
+        resolveName: typeof resolveName;
+        resolveNames: typeof resolveNames;
         feeCollector: {
             claimRewardFromPool: typeof claimRewardFromPool;
         };

package/dist/types/configs/registry/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Curated, off-chain-known addresses per chain (wallets, external protocols),
+ * keyed by checksummed address. Empty until entries are reviewed and added -
+ * see resolveName.ts for why this ships empty rather than with guessed data.
+ */
+declare const registries: {
+    1: {};
+    8453: {};
+    17000: {};
+    11155111: {};
+    18453: {};
+};
+export default registries;

package/dist/types/contracts/resolveName.d.ts

@@ -0,0 +1,42 @@
+import { Provider } from "ethers";
+import { ChainId } from "../configs/chains";
+export interface AddressName {
+    /** Checksummed. */
+    address: string;
+    name: string;
+    kind: "contract" | "gauge" | "wallet" | "external" | "ens";
+    source: "config" | "registry" | "ens";
+    url?: string;
+}
+export interface ResolveNameOptions {
+    /** Attempt an ENS reverse lookup when nothing else matches. Mainnet only regardless of this flag. Default true. */
+    ens?: boolean;
+    /** Reuse an existing provider for the ENS lookup instead of constructing one from the chain config. */
+    provider?: Provider;
+}
+/**
+ * Resolves an address to a readable name.
+ *
+ * Checks the chain config (via `findContract`), then a curated registry of
+ * off-chain-known addresses (wallets, external protocols), then - mainnet
+ * only, and only once the first two miss - an ENS reverse lookup, forward-
+ * verified against the name it returns.
+ *
+ * @param chainId - The chain/network to use.
+ * @param address - Any-case address.
+ * @param options - `ens: false` skips the ENS step; `provider` reuses an existing connection for it.
+ * @returns The resolved name, or null when nothing matches.
+ */
+export declare function resolveName(chainId: ChainId, address: string, options?: ResolveNameOptions): Promise<AddressName | null>;
+/**
+ * Batch form of {@link resolveName}. Config and registry lookups run
+ * synchronously per address; only addresses that fall through to ENS pay for
+ * a network round trip, and those run concurrently.
+ *
+ * @param chainId - The chain/network to use.
+ * @param addresses - Any-case addresses.
+ * @param options - Same as {@link resolveName}.
+ * @returns A map from the (checksummed) input address to its resolved name, or null.
+ */
+export declare function resolveNames(chainId: ChainId, addresses: string[], options?: ResolveNameOptions): Promise<Record<string, AddressName | null>>;
+export default resolveName;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@raac/rpc",
-	"version": "2.0.0-beta.0",
+	"version": "2.0.0-beta.1",
 	"description": "RPC Library for RAAC",
 	"main": "dist/index.js",
 	"types": "dist/types/index.d.ts",