@1001-digital/proxies 0.0.1

package/dist/index.js

@@ -0,0 +1,442 @@
+var __defProp = Object.defineProperty;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
+import { keccak_256 } from "@noble/hashes/sha3";
+const encoder = new TextEncoder();
+function computeSelector(signature) {
+  const hash = keccak_256(encoder.encode(signature));
+  let hex = "0x";
+  for (let i = 0; i < 4; i++) {
+    hex += hash[i].toString(16).padStart(2, "0");
+  }
+  return hex;
+}
+function canonicalSignature(fn) {
+  if (!fn.name) throw new Error("Cannot build signature: entry has no name");
+  const types = (fn.inputs ?? []).map(canonicalType).join(",");
+  return `${fn.name}(${types})`;
+}
+function canonicalType(p) {
+  if (p.type.startsWith("tuple")) {
+    const suffix = p.type.slice("tuple".length);
+    const inner = (p.components ?? []).map(canonicalType).join(",");
+    return `(${inner})${suffix}`;
+  }
+  return p.type;
+}
+function filterAbiBySelectors(abi, selectors) {
+  const set = new Set(selectors.map((s) => s.toLowerCase()));
+  return abi.filter((item) => {
+    if (!isAbiFunction(item)) return true;
+    try {
+      const sel = computeSelector(canonicalSignature(item)).toLowerCase();
+      return set.has(sel);
+    } catch {
+      return false;
+    }
+  });
+}
+function buildCompositeAbi(abis) {
+  const seenSelectors = /* @__PURE__ */ new Set();
+  const seenEventErrors = /* @__PURE__ */ new Set();
+  const composite = [];
+  for (const abi of abis) {
+    for (const item of abi) {
+      if (isAbiFunction(item)) {
+        try {
+          const sel = computeSelector(canonicalSignature(item)).toLowerCase();
+          if (seenSelectors.has(sel)) continue;
+          seenSelectors.add(sel);
+        } catch {
+        }
+      } else if (isEventOrError(item)) {
+        try {
+          const key = `${item.type}:${canonicalSignature(item)}`;
+          if (seenEventErrors.has(key)) continue;
+          seenEventErrors.add(key);
+        } catch {
+        }
+      }
+      composite.push(item);
+    }
+  }
+  return composite;
+}
+function isAbiFunction(item) {
+  return typeof item === "object" && item !== null && item.type === "function" && typeof item.name === "string";
+}
+function isEventOrError(item) {
+  if (typeof item !== "object" || item === null) return false;
+  const t = item.type;
+  return (t === "event" || t === "error") && typeof item.name === "string";
+}
+const SUPPORTS_INTERFACE_SELECTOR = "0x01ffc9a7";
+const DIAMOND_LOUPE_INTERFACE_ID = "0x48e2b093";
+const FACETS_SELECTOR = "0x7a0ed627";
+const IMPLEMENTATION_SELECTOR = "0x5c60da1b";
+const EIP1967_IMPL_SLOT = "0x360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc";
+const EIP1967_BEACON_SLOT = "0xa3f0ad74e5423aebfd80d3ef4346578335a9a72aeaee59ff6cb3582b35133d50";
+const EIP1967_ADMIN_SLOT = "0xb53127684a568b3173ae13b9f8a6016e243e63b6e8ee1178d6a717850b5d6103";
+const EIP1822_PROXIABLE_SLOT = "0xc5f16f0fcc7e328891200cdca4c1c57b2b360c12265401510d42209b5829f8e2";
+const EIP1167_BYTECODE_PREFIX = "363d3d373d3d3d363d73";
+const EIP1167_BYTECODE_SUFFIX = "5af43d82803e903d91602b57fd5bf3";
+const ZERO_ADDRESS = "0x0000000000000000000000000000000000000000";
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+class ProxiesError extends Error {
+  constructor(message, options) {
+    super(message, options);
+    this.name = "ProxiesError";
+  }
+}
+class ProxiesDecodeError extends ProxiesError {
+  constructor(message, options) {
+    super(message, options);
+    this.name = "ProxiesDecodeError";
+  }
+}
+class ProxiesFetchError extends ProxiesError {
+  constructor(message, details, options) {
+    super(message, options);
+    __publicField(this, "status");
+    this.name = "ProxiesFetchError";
+    this.status = details.status;
+  }
+}
+const MAX_FACETS = 200;
+const MAX_SELECTORS_PER_FACET = 1e3;
+function decodeFacets(hex) {
+  const h = hex.startsWith("0x") ? hex.slice(2) : hex;
+  const W = 64;
+  const readWord = (pos) => {
+    if (pos < 0 || pos + W > h.length) {
+      throw new ProxiesDecodeError("malformed facets() return: out of bounds");
+    }
+    return h.slice(pos, pos + W);
+  };
+  const readUint = (pos) => {
+    const word = readWord(pos);
+    if (!/^0{48}/.test(word)) {
+      throw new ProxiesDecodeError("malformed facets() return: value too large");
+    }
+    return parseInt(word, 16);
+  };
+  const outerOff = readUint(0) * 2;
+  const n = readUint(outerOff);
+  if (n > MAX_FACETS) {
+    throw new ProxiesDecodeError(`malformed facets() return: ${n} facets exceeds limit`);
+  }
+  const head = outerOff + W;
+  const facets = [];
+  for (let i = 0; i < n; i++) {
+    const tupleOff = readUint(head + i * W) * 2;
+    const tx = head + tupleOff;
+    const addrWord = readWord(tx);
+    if (!/^0{24}/.test(addrWord)) {
+      throw new ProxiesDecodeError("malformed facets() return: invalid address");
+    }
+    const facetAddress = "0x" + addrWord.slice(24).toLowerCase();
+    const selOff = readUint(tx + W) * 2;
+    const selStart = tx + selOff;
+    const m = readUint(selStart);
+    if (m > MAX_SELECTORS_PER_FACET) {
+      throw new ProxiesDecodeError(
+        `malformed facets() return: ${m} selectors exceeds limit`
+      );
+    }
+    const selectors = [];
+    for (let j = 0; j < m; j++) {
+      const slot = readWord(selStart + W + j * W);
+      selectors.push("0x" + slot.slice(0, 8).toLowerCase());
+    }
+    facets.push({ facetAddress, functionSelectors: selectors });
+  }
+  return facets;
+}
+function parseBool(hex) {
+  if (hex.length !== 66) return null;
+  const body = hex.slice(2).toLowerCase();
+  if (!/^0{63}[01]$/.test(body)) return null;
+  return body.slice(-1) === "1";
+}
+function parseAddress(hex) {
+  if (hex.length !== 66) return null;
+  const body = hex.slice(2).toLowerCase();
+  if (!/^0{24}[0-9a-f]{40}$/.test(body)) return null;
+  return "0x" + body.slice(24);
+}
+async function jsonRpcCall(rpc, method, params, fetchFn) {
+  let res;
+  try {
+    res = await fetchFn(rpc, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ jsonrpc: "2.0", id: 1, method, params })
+    });
+  } catch (error) {
+    throw new ProxiesFetchError(
+      `RPC request failed: ${errorMessage(error)}`,
+      { status: 0 },
+      { cause: error }
+    );
+  }
+  if (!res.ok) {
+    throw new ProxiesFetchError(
+      `RPC request failed: ${res.status}`,
+      { status: res.status }
+    );
+  }
+  let json;
+  try {
+    json = await res.json();
+  } catch (error) {
+    throw new ProxiesFetchError(
+      `Invalid JSON from RPC: ${errorMessage(error)}`,
+      { status: res.status },
+      { cause: error }
+    );
+  }
+  if (json.error) {
+    throw new ProxiesFetchError(
+      `RPC error: ${json.error.message}`,
+      { status: 0 }
+    );
+  }
+  return json.result ?? "0x";
+}
+function ethCall(rpc, to, data, fetchFn) {
+  return jsonRpcCall(rpc, "eth_call", [{ to, data }, "latest"], fetchFn);
+}
+function ethGetStorageAt(rpc, address, slot, fetchFn) {
+  return jsonRpcCall(rpc, "eth_getStorageAt", [address, slot, "latest"], fetchFn);
+}
+function ethGetCode(rpc, address, fetchFn) {
+  return jsonRpcCall(rpc, "eth_getCode", [address, "latest"], fetchFn);
+}
+async function detectDiamond(rpc, address, fetchFn) {
+  const calldata = SUPPORTS_INTERFACE_SELECTOR + DIAMOND_LOUPE_INTERFACE_ID.slice(2).padEnd(64, "0");
+  try {
+    const res = await ethCall(rpc, address, calldata, fetchFn);
+    const bool = parseBool(res);
+    if (bool === true) return tryFacets(rpc, address, fetchFn);
+    if (bool === false) return null;
+  } catch {
+  }
+  return tryFacets(rpc, address, fetchFn);
+}
+const MIN_FACETS_PAYLOAD_LEN = 130;
+async function tryFacets(rpc, address, fetchFn) {
+  let res;
+  try {
+    res = await ethCall(rpc, address, FACETS_SELECTOR, fetchFn);
+  } catch {
+    return null;
+  }
+  if (res === "0x" || res.length < MIN_FACETS_PAYLOAD_LEN) return null;
+  let facets;
+  try {
+    facets = decodeFacets(res);
+  } catch {
+    return null;
+  }
+  const targets = facets.filter((f) => f.facetAddress !== ZERO_ADDRESS).map((f) => ({ address: f.facetAddress, selectors: f.functionSelectors }));
+  return targets.length > 0 ? { pattern: "eip-2535-diamond", targets } : null;
+}
+async function detectEip1167(rpc, address, fetchFn) {
+  let code;
+  try {
+    code = await ethGetCode(rpc, address, fetchFn);
+  } catch {
+    return null;
+  }
+  const body = code.toLowerCase().replace(/^0x/, "");
+  if (body.length !== 90) return null;
+  if (!body.startsWith(EIP1167_BYTECODE_PREFIX)) return null;
+  if (!body.endsWith(EIP1167_BYTECODE_SUFFIX)) return null;
+  const impl = "0x" + body.slice(EIP1167_BYTECODE_PREFIX.length, EIP1167_BYTECODE_PREFIX.length + 40);
+  if (impl === ZERO_ADDRESS) return null;
+  return {
+    pattern: "eip-1167",
+    targets: [{ address: impl }]
+  };
+}
+async function detectEip1822(rpc, address, fetchFn) {
+  let raw;
+  try {
+    raw = await ethGetStorageAt(rpc, address, EIP1822_PROXIABLE_SLOT, fetchFn);
+  } catch {
+    return null;
+  }
+  const impl = parseAddress(raw);
+  if (!impl || impl === ZERO_ADDRESS) return null;
+  return {
+    pattern: "eip-1822",
+    targets: [{ address: impl }]
+  };
+}
+async function detectEip1967(rpc, address, fetchFn) {
+  let implRaw;
+  let adminRaw;
+  try {
+    [implRaw, adminRaw] = await Promise.all([
+      ethGetStorageAt(rpc, address, EIP1967_IMPL_SLOT, fetchFn),
+      ethGetStorageAt(rpc, address, EIP1967_ADMIN_SLOT, fetchFn).catch(() => "0x")
+    ]);
+  } catch {
+    return null;
+  }
+  const impl = parseAddress(implRaw);
+  if (!impl || impl === "0x0000000000000000000000000000000000000000") return null;
+  const proxy = {
+    pattern: "eip-1967",
+    targets: [{ address: impl }]
+  };
+  const admin = parseAddress(adminRaw);
+  if (admin && admin !== "0x0000000000000000000000000000000000000000") {
+    proxy.admin = admin;
+  }
+  return proxy;
+}
+async function detectEip1967Beacon(rpc, address, fetchFn) {
+  let beaconRaw;
+  try {
+    beaconRaw = await ethGetStorageAt(rpc, address, EIP1967_BEACON_SLOT, fetchFn);
+  } catch {
+    return null;
+  }
+  const beacon = parseAddress(beaconRaw);
+  if (!beacon || beacon === ZERO_ADDRESS) return null;
+  let implRaw;
+  try {
+    implRaw = await ethCall(rpc, beacon, IMPLEMENTATION_SELECTOR, fetchFn);
+  } catch {
+    return null;
+  }
+  const impl = parseAddress(implRaw);
+  if (!impl || impl === ZERO_ADDRESS) return null;
+  return {
+    pattern: "eip-1967-beacon",
+    targets: [{ address: impl }],
+    beacon
+  };
+}
+async function detectEip897(rpc, address, fetchFn) {
+  let raw;
+  try {
+    raw = await ethCall(rpc, address, IMPLEMENTATION_SELECTOR, fetchFn);
+  } catch {
+    return null;
+  }
+  const impl = parseAddress(raw);
+  if (!impl || impl === ZERO_ADDRESS) return null;
+  return {
+    pattern: "eip-897",
+    targets: [{ address: impl }]
+  };
+}
+const SAFE_SINGLETON_SLOT = "0x0000000000000000000000000000000000000000000000000000000000000000";
+async function detectGnosisSafe(rpc, address, fetchFn) {
+  let raw;
+  try {
+    raw = await ethGetStorageAt(rpc, address, SAFE_SINGLETON_SLOT, fetchFn);
+  } catch {
+    return null;
+  }
+  const impl = parseAddress(raw);
+  if (!impl || impl === ZERO_ADDRESS) return null;
+  return {
+    pattern: "gnosis-safe",
+    targets: [{ address: impl }]
+  };
+}
+const DETECTORS = [
+  detectDiamond,
+  detectEip1967,
+  detectEip1967Beacon,
+  detectEip1822,
+  detectEip1167,
+  detectGnosisSafe,
+  detectEip897
+];
+async function detectProxy(rpc, address, fetchFn) {
+  for (const detect of DETECTORS) {
+    try {
+      const match = await detect(rpc, address, fetchFn);
+      if (match) return match;
+    } catch {
+    }
+  }
+  return null;
+}
+async function enrichTargets(targets, enrich) {
+  const enrichments = enrich ? await Promise.all(
+    targets.map((t) => enrich(t.address).catch(() => null))
+  ) : targets.map(() => null);
+  return targets.map((t, i) => {
+    const src = enrichments[i];
+    const info = { address: t.address };
+    if (t.selectors !== void 0) info.selectors = t.selectors;
+    if (src == null ? void 0 : src.abi) {
+      info.abi = t.selectors !== void 0 ? filterAbiBySelectors(src.abi, t.selectors) : src.abi;
+    }
+    return info;
+  });
+}
+function createProxies(config = {}) {
+  const fetchFn = config.fetch ?? globalThis.fetch;
+  const defaultEnrich = config.enrich ?? null;
+  return {
+    detect(rpc, address) {
+      return detectProxy(rpc, address, fetchFn);
+    },
+    async fetch(rpc, address, options) {
+      const raw = await detectProxy(rpc, address, fetchFn);
+      if (!raw) return null;
+      const enricher = (options == null ? void 0 : options.enrich) === false ? null : (options == null ? void 0 : options.enrich) ?? defaultEnrich;
+      const targets = await enrichTargets(raw.targets, enricher);
+      const abiLayers = targets.map((t) => t.abi).filter((a) => a !== void 0);
+      const compositeAbi = abiLayers.length > 0 ? buildCompositeAbi(abiLayers) : void 0;
+      const proxy = { pattern: raw.pattern, targets };
+      if (raw.beacon) proxy.beacon = raw.beacon;
+      if (raw.admin) proxy.admin = raw.admin;
+      if (compositeAbi) proxy.compositeAbi = compositeAbi;
+      return proxy;
+    }
+  };
+}
+export {
+  DIAMOND_LOUPE_INTERFACE_ID,
+  EIP1167_BYTECODE_PREFIX,
+  EIP1167_BYTECODE_SUFFIX,
+  EIP1822_PROXIABLE_SLOT,
+  EIP1967_ADMIN_SLOT,
+  EIP1967_BEACON_SLOT,
+  EIP1967_IMPL_SLOT,
+  FACETS_SELECTOR,
+  IMPLEMENTATION_SELECTOR,
+  ProxiesDecodeError,
+  ProxiesError,
+  ProxiesFetchError,
+  SUPPORTS_INTERFACE_SELECTOR,
+  ZERO_ADDRESS,
+  buildCompositeAbi,
+  canonicalSignature,
+  computeSelector,
+  createProxies,
+  decodeFacets,
+  detectDiamond,
+  detectEip1167,
+  detectEip1822,
+  detectEip1967,
+  detectEip1967Beacon,
+  detectEip897,
+  detectGnosisSafe,
+  detectProxy,
+  enrichTargets,
+  ethCall,
+  ethGetCode,
+  ethGetStorageAt,
+  filterAbiBySelectors,
+  parseAddress
+};

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@1001-digital/proxies",
+  "version": "0.0.1",
+  "description": "Ethereum proxy pattern detection primitives — ERC-2535 diamonds, EIP-1967, EIP-1167, beacon, Safe, EIP-1822, EIP-897. Detect, enrich, compose.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/1001-digital/diamonds.git"
+  },
+  "keywords": [
+    "ethereum",
+    "proxy",
+    "erc-2535",
+    "diamond",
+    "eip-1967",
+    "eip-1167",
+    "eip-1822",
+    "eip-897",
+    "beacon",
+    "gnosis-safe",
+    "loupe",
+    "facets",
+    "abi"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@noble/hashes": "^1.7.0"
+  },
+  "devDependencies": {
+    "@changesets/changelog-github": "^0.6.0",
+    "@changesets/cli": "^2.30.0",
+    "vite": "^6.0.0",
+    "vite-plugin-dts": "^4.0.0",
+    "vitest": "^3.0.0"
+  },
+  "scripts": {
+    "build": "vite build",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "changeset": "changeset"
+  }
+}

package/src/abi.ts

@@ -0,0 +1,72 @@
+import { canonicalSignature, computeSelector } from './selector'
+import type { AbiFunctionLike } from './types'
+
+/**
+ * Keep all non-function ABI entries; keep function entries whose computed
+ * selector is in the provided selector set. Verified facet contracts may
+ * declare extra functions not actually mounted on the diamond — this trims them.
+ */
+export function filterAbiBySelectors(abi: unknown[], selectors: string[]): unknown[] {
+  const set = new Set(selectors.map(s => s.toLowerCase()))
+
+  return abi.filter(item => {
+    if (!isAbiFunction(item)) return true
+    try {
+      const sel = computeSelector(canonicalSignature(item)).toLowerCase()
+      return set.has(sel)
+    } catch {
+      return false
+    }
+  })
+}
+
+/**
+ * Combine multiple ABIs into a single composite. First-occurrence wins:
+ *   - functions deduped by selector
+ *   - events and errors deduped by `type:name(canonicalInputs)`
+ *   - other entries (constructor, fallback, receive) kept as-is
+ */
+export function buildCompositeAbi(abis: unknown[][]): unknown[] {
+  const seenSelectors = new Set<string>()
+  const seenEventErrors = new Set<string>()
+  const composite: unknown[] = []
+
+  for (const abi of abis) {
+    for (const item of abi) {
+      if (isAbiFunction(item)) {
+        try {
+          const sel = computeSelector(canonicalSignature(item)).toLowerCase()
+          if (seenSelectors.has(sel)) continue
+          seenSelectors.add(sel)
+        } catch {
+          // Include items we can't key
+        }
+      } else if (isEventOrError(item)) {
+        try {
+          const key = `${item.type}:${canonicalSignature(item)}`
+          if (seenEventErrors.has(key)) continue
+          seenEventErrors.add(key)
+        } catch {
+          // Include items we can't key
+        }
+      }
+      composite.push(item)
+    }
+  }
+
+  return composite
+}
+
+function isAbiFunction(item: unknown): item is AbiFunctionLike {
+  return typeof item === 'object'
+    && item !== null
+    && (item as { type?: unknown }).type === 'function'
+    && typeof (item as { name?: unknown }).name === 'string'
+}
+
+function isEventOrError(item: unknown): item is AbiFunctionLike {
+  if (typeof item !== 'object' || item === null) return false
+  const t = (item as { type?: unknown }).type
+  return (t === 'event' || t === 'error')
+    && typeof (item as { name?: unknown }).name === 'string'
+}

package/src/constants.ts

@@ -0,0 +1,42 @@
+// ── ERC-165 / ERC-2535 ──
+
+/** ERC-165 `supportsInterface(bytes4)`. */
+export const SUPPORTS_INTERFACE_SELECTOR = '0x01ffc9a7'
+
+/** ERC-2535 Diamond Loupe `IDiamondLoupe` interface ID. */
+export const DIAMOND_LOUPE_INTERFACE_ID = '0x48e2b093'
+
+/** ERC-2535 `facets()` — returns `(address, bytes4[])[]`. */
+export const FACETS_SELECTOR = '0x7a0ed627'
+
+/** `implementation()` — used by EIP-897 proxies and EIP-1967 beacons. */
+export const IMPLEMENTATION_SELECTOR = '0x5c60da1b'
+
+// ── EIP-1967 storage slots ──
+// Per EIP-1967, slots are `bytes32(uint256(keccak256('eip1967.proxy.<field>')) - 1)`.
+
+/** EIP-1967 implementation slot: `keccak256('eip1967.proxy.implementation') - 1`. */
+export const EIP1967_IMPL_SLOT = '0x360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc'
+
+/** EIP-1967 beacon slot: `keccak256('eip1967.proxy.beacon') - 1`. */
+export const EIP1967_BEACON_SLOT = '0xa3f0ad74e5423aebfd80d3ef4346578335a9a72aeaee59ff6cb3582b35133d50'
+
+/** EIP-1967 admin slot: `keccak256('eip1967.proxy.admin') - 1`. */
+export const EIP1967_ADMIN_SLOT = '0xb53127684a568b3173ae13b9f8a6016e243e63b6e8ee1178d6a717850b5d6103'
+
+// ── EIP-1822 ──
+
+/** EIP-1822 UUPS PROXIABLE slot: `keccak256('PROXIABLE')`. */
+export const EIP1822_PROXIABLE_SLOT = '0xc5f16f0fcc7e328891200cdca4c1c57b2b360c12265401510d42209b5829f8e2'
+
+// ── EIP-1167 minimal-proxy bytecode markers ──
+// Reference: https://eips.ethereum.org/EIPS/eip-1167
+// Runtime: 0x363d3d373d3d3d363d73<20-byte impl>5af43d82803e903d91602b57fd5bf3 (45 bytes = 90 hex chars)
+
+/** Prefix preceding the 20-byte implementation address in an EIP-1167 minimal proxy. */
+export const EIP1167_BYTECODE_PREFIX = '363d3d373d3d3d363d73'
+
+/** Suffix following the 20-byte implementation address in an EIP-1167 minimal proxy. */
+export const EIP1167_BYTECODE_SUFFIX = '5af43d82803e903d91602b57fd5bf3'
+
+export const ZERO_ADDRESS = '0x0000000000000000000000000000000000000000'