@1001-digital/proxies 0.0.1

package/src/decode.ts

@@ -0,0 +1,103 @@
+import { ProxiesDecodeError } from './errors'
+
+// Sanity limits to reject malformed data that accidentally decodes.
+// Real diamonds have <100 facets and <200 selectors/facet; bound malformed-input cost.
+const MAX_FACETS = 200
+const MAX_SELECTORS_PER_FACET = 1000
+
+/**
+ * Literal on-chain facet tuple (`(address, bytes4[])`) — the shape returned by
+ * the ERC-2535 loupe `facets()` call. Use {@link decodeFacets} to parse it.
+ */
+export interface DecodedFacet {
+  facetAddress: string
+  functionSelectors: string[]
+}
+
+/**
+ * Decode the return value of `facets()` — type `(address, bytes4[])[]`.
+ * Throws {@link ProxiesDecodeError} on malformed input.
+ */
+export function decodeFacets(hex: string): DecodedFacet[] {
+  const h = hex.startsWith('0x') ? hex.slice(2) : hex
+  const W = 64 // one 32-byte word in hex chars
+
+  const readWord = (pos: number): string => {
+    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: number): number => {
+    const word = readWord(pos)
+    // Upper 24 bytes must be zero for the value to fit safely in a JS number
+    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: DecodedFacet[] = []
+
+  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: string[] = []
+    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
+}
+
+/**
+ * Parse a 32-byte ABI-encoded bool. Returns `null` if the response is not a
+ * well-formed bool (wrong length, or non-zero high bits).
+ */
+export function parseBool(hex: string): boolean | null {
+  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'
+}
+
+/**
+ * Parse a 32-byte ABI-encoded address (right-padded). Returns the lowercase
+ * `0x` address, or `null` if the payload is not a well-formed address (wrong
+ * length, or non-zero high bytes).
+ */
+export function parseAddress(hex: string): string | null {
+  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)
+}

package/src/detect.ts

@@ -0,0 +1,60 @@
+import { detectDiamond } from './patterns/diamond'
+import { detectEip1167 } from './patterns/eip1167'
+import { detectEip1822 } from './patterns/eip1822'
+import { detectEip1967 } from './patterns/eip1967'
+import { detectEip1967Beacon } from './patterns/eip1967-beacon'
+import { detectEip897 } from './patterns/eip897'
+import { detectGnosisSafe } from './patterns/safe'
+import type { RawProxy } from './types'
+
+type Detector = (
+  rpc: string,
+  address: string,
+  fetchFn: typeof globalThis.fetch,
+) => Promise<RawProxy | null>
+
+/**
+ * Priority order used by {@link detectProxy}. First detector that returns
+ * non-null wins. Diamonds come first because the loupe probe is a specific,
+ * low-false-positive signal; standard storage slots follow; Safe's slot-0
+ * convention and EIP-897's `implementation()` view function come last.
+ */
+const DETECTORS: Detector[] = [
+  detectDiamond,
+  detectEip1967,
+  detectEip1967Beacon,
+  detectEip1822,
+  detectEip1167,
+  detectGnosisSafe,
+  detectEip897,
+]
+
+/**
+ * Detect any supported proxy pattern at `address`.
+ *
+ * Tries the built-in detectors in priority order (`eip-2535-diamond → eip-1967
+ * → eip-1967-beacon → eip-1822 → eip-1167 → gnosis-safe → eip-897`). Returns
+ * the first match, or `null` when no pattern matches.
+ *
+ * Each detector runs with error isolation — an RPC failure in one pattern does
+ * not poison the probe for subsequent ones.
+ *
+ * Single-hop only: if the resolved implementation is itself a proxy, the
+ * result describes the direct pattern only. Re-run detection on the resolved
+ * implementation to chain manually.
+ */
+export async function detectProxy(
+  rpc: string,
+  address: string,
+  fetchFn: typeof globalThis.fetch,
+): Promise<RawProxy | null> {
+  for (const detect of DETECTORS) {
+    try {
+      const match = await detect(rpc, address, fetchFn)
+      if (match) return match
+    } catch {
+      // Detector-level errors shouldn't block later detectors
+    }
+  }
+  return null
+}

package/src/enrich.ts

@@ -0,0 +1,36 @@
+import { filterAbiBySelectors } from './abi'
+import type { EnrichedTarget, ResolvedTarget, TargetEnricher } from './types'
+
+/**
+ * Apply an enricher to each resolved target, producing an `EnrichedTarget[]`.
+ *
+ * Enricher errors are swallowed per-target — one bad fetch does not fail the
+ * whole resolution. Pass `null` to skip enrichment entirely (targets will
+ * carry only `address` + `selectors`).
+ *
+ * When a target has `selectors` defined (diamond facets), the returned ABI is
+ * filtered to those selectors. When `selectors` is undefined (any single-impl
+ * proxy pattern), the full implementation ABI is passed through untouched.
+ */
+export async function enrichTargets(
+  targets: ResolvedTarget[],
+  enrich: TargetEnricher | null,
+): Promise<EnrichedTarget[]> {
+  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: EnrichedTarget = { address: t.address }
+    if (t.selectors !== undefined) info.selectors = t.selectors
+    if (src?.abi) {
+      info.abi = t.selectors !== undefined
+        ? filterAbiBySelectors(src.abi, t.selectors)
+        : src.abi
+    }
+    return info
+  })
+}

package/src/errors.ts

@@ -0,0 +1,33 @@
+export function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error)
+}
+
+export class ProxiesError extends Error {
+  constructor(message: string, options?: ErrorOptions) {
+    super(message, options)
+    this.name = 'ProxiesError'
+  }
+}
+
+/** Raised when the on-chain `facets()` return value cannot be decoded. */
+export class ProxiesDecodeError extends ProxiesError {
+  constructor(message: string, options?: ErrorOptions) {
+    super(message, options)
+    this.name = 'ProxiesDecodeError'
+  }
+}
+
+/** Raised when a JSON-RPC request fails at the transport level. */
+export class ProxiesFetchError extends ProxiesError {
+  public readonly status: number
+
+  constructor(
+    message: string,
+    details: { status: number },
+    options?: ErrorOptions,
+  ) {
+    super(message, options)
+    this.name = 'ProxiesFetchError'
+    this.status = details.status
+  }
+}

package/src/index.ts

@@ -0,0 +1,122 @@
+import { buildCompositeAbi } from './abi'
+import { detectProxy } from './detect'
+import { enrichTargets } from './enrich'
+import type {
+  FetchProxyOptions,
+  Proxy,
+  ProxiesClient,
+  ProxiesConfig,
+  TargetEnricher,
+} from './types'
+
+/**
+ * Create a proxy inspection client.
+ *
+ * ```ts
+ * const proxies = createProxies()
+ * const result = await proxies.fetch('https://rpc…', '0x…')
+ * if (result) console.log(result.pattern, result.targets)
+ * ```
+ *
+ * Pass `config.enrich` to populate each target's ABI from any source
+ * (Sourcify, Etherscan, a local cache). Omit it to get raw targets with
+ * address + (optional) selectors only.
+ */
+export function createProxies(config: ProxiesConfig = {}): ProxiesClient {
+  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): Promise<Proxy | null> {
+      const raw = await detectProxy(rpc, address, fetchFn)
+      if (!raw) return null
+
+      const enricher: TargetEnricher | null = options?.enrich === false
+        ? null
+        : (options?.enrich ?? defaultEnrich)
+
+      const targets = await enrichTargets(raw.targets, enricher)
+
+      const abiLayers = targets
+        .map(t => t.abi)
+        .filter((a): a is unknown[] => a !== undefined)
+      const compositeAbi = abiLayers.length > 0
+        ? buildCompositeAbi(abiLayers)
+        : undefined
+
+      const proxy: 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
+    },
+  }
+}
+
+// ── Detection ──
+
+export { detectProxy } from './detect'
+export { detectDiamond } from './patterns/diamond'
+export { detectEip1967 } from './patterns/eip1967'
+export { detectEip1967Beacon } from './patterns/eip1967-beacon'
+export { detectEip1822 } from './patterns/eip1822'
+export { detectEip1167 } from './patterns/eip1167'
+export { detectGnosisSafe } from './patterns/safe'
+export { detectEip897 } from './patterns/eip897'
+
+// ── Composition ──
+
+export { enrichTargets } from './enrich'
+export { filterAbiBySelectors, buildCompositeAbi } from './abi'
+
+// ── Utilities ──
+
+export { decodeFacets, parseAddress } from './decode'
+export { computeSelector, canonicalSignature } from './selector'
+
+// ── RPC ──
+
+export { ethCall, ethGetStorageAt, ethGetCode } from './rpc'
+
+// ── Constants ──
+
+export {
+  SUPPORTS_INTERFACE_SELECTOR,
+  DIAMOND_LOUPE_INTERFACE_ID,
+  FACETS_SELECTOR,
+  IMPLEMENTATION_SELECTOR,
+  EIP1967_IMPL_SLOT,
+  EIP1967_BEACON_SLOT,
+  EIP1967_ADMIN_SLOT,
+  EIP1822_PROXIABLE_SLOT,
+  EIP1167_BYTECODE_PREFIX,
+  EIP1167_BYTECODE_SUFFIX,
+  ZERO_ADDRESS,
+} from './constants'
+
+// ── Errors ──
+
+export { ProxiesError, ProxiesDecodeError, ProxiesFetchError } from './errors'
+
+// ── Types ──
+
+export type {
+  ProxiesConfig,
+  ProxiesClient,
+  FetchProxyOptions,
+  ProxyPattern,
+  ResolvedTarget,
+  RawProxy,
+  EnrichedTarget,
+  Proxy,
+  TargetEnrichment,
+  TargetEnricher,
+  AbiParam,
+  AbiFunctionLike,
+} from './types'
+
+export type { DecodedFacet } from './decode'

package/src/patterns/diamond.ts

@@ -0,0 +1,77 @@
+import {
+  DIAMOND_LOUPE_INTERFACE_ID,
+  FACETS_SELECTOR,
+  SUPPORTS_INTERFACE_SELECTOR,
+  ZERO_ADDRESS,
+} from '../constants'
+import { decodeFacets, parseBool } from '../decode'
+import { ethCall } from '../rpc'
+import type { DecodedFacet } from '../decode'
+import type { RawProxy, ResolvedTarget } from '../types'
+
+/**
+ * Detect whether a contract implements ERC-2535 (Diamond) and return its
+ * facets as a {@link RawProxy}. Returns `null` if not a diamond.
+ *
+ * Strategy:
+ *   1. Try ERC-165 `supportsInterface(0x48e2b093)`.
+ *      - Valid bool `true`  → fetch and return facets
+ *      - Valid bool `false` → definitively not a diamond (null)
+ *      - Malformed / error  → fall through to step 2
+ *   2. Probe `facets()` directly. If it returns a non-empty decoded array,
+ *      treat the contract as a diamond.
+ *
+ * Zero-address facets (deleted selectors) are filtered out of the result.
+ */
+export async function detectDiamond(
+  rpc: string,
+  address: string,
+  fetchFn: typeof globalThis.fetch,
+): Promise<RawProxy | null> {
+  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
+    // Malformed response — fall through to facets() probe
+  } catch {
+    // RPC/revert error — fall through to facets() probe
+  }
+
+  return tryFacets(rpc, address, fetchFn)
+}
+
+// Minimum valid `facets()` payload: outer offset word + length word = 2 × 32
+// bytes → 128 hex chars + '0x' prefix.
+const MIN_FACETS_PAYLOAD_LEN = 130
+
+async function tryFacets(
+  rpc: string,
+  address: string,
+  fetchFn: typeof globalThis.fetch,
+): Promise<RawProxy | null> {
+  let res: string
+  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: DecodedFacet[]
+  try {
+    facets = decodeFacets(res)
+  } catch {
+    return null
+  }
+
+  const targets: ResolvedTarget[] = 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
+}

package/src/patterns/eip1167.ts

@@ -0,0 +1,45 @@
+import {
+  EIP1167_BYTECODE_PREFIX,
+  EIP1167_BYTECODE_SUFFIX,
+  ZERO_ADDRESS,
+} from '../constants'
+import { ethGetCode } from '../rpc'
+import type { RawProxy } from '../types'
+
+/**
+ * Detect an EIP-1167 minimal proxy (clone) from runtime bytecode.
+ *
+ * Matches the canonical 45-byte runtime:
+ *   `363d3d373d3d3d363d73<20-byte impl>5af43d82803e903d91602b57fd5bf3`
+ *
+ * Does NOT match the "optimized" variants (e.g. push-based relays) that some
+ * tooling emits — this is the standards-compliant shape per EIP-1167.
+ *
+ * Returns `null` when the bytecode does not match.
+ */
+export async function detectEip1167(
+  rpc: string,
+  address: string,
+  fetchFn: typeof globalThis.fetch,
+): Promise<RawProxy | null> {
+  let code: string
+  try {
+    code = await ethGetCode(rpc, address, fetchFn)
+  } catch {
+    return null
+  }
+
+  const body = code.toLowerCase().replace(/^0x/, '')
+  // 20 prefix + 40 address + 30 suffix = 90 hex chars
+  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 }],
+  }
+}

package/src/patterns/eip1822.ts

@@ -0,0 +1,34 @@
+import { EIP1822_PROXIABLE_SLOT, ZERO_ADDRESS } from '../constants'
+import { parseAddress } from '../decode'
+import { ethGetStorageAt } from '../rpc'
+import type { RawProxy } from '../types'
+
+/**
+ * Detect an EIP-1822 UUPS proxy.
+ *
+ * Reads the PROXIABLE slot (`keccak256('PROXIABLE')`). Returns `null` when the
+ * slot is empty or malformed.
+ *
+ * Note: most modern UUPS proxies use the EIP-1967 slot instead — this detector
+ * only catches the older EIP-1822 convention.
+ */
+export async function detectEip1822(
+  rpc: string,
+  address: string,
+  fetchFn: typeof globalThis.fetch,
+): Promise<RawProxy | null> {
+  let raw: string
+  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 }],
+  }
+}

package/src/patterns/eip1967-beacon.ts

@@ -0,0 +1,43 @@
+import { EIP1967_BEACON_SLOT, IMPLEMENTATION_SELECTOR, ZERO_ADDRESS } from '../constants'
+import { parseAddress } from '../decode'
+import { ethCall, ethGetStorageAt } from '../rpc'
+import type { RawProxy } from '../types'
+
+/**
+ * Detect an EIP-1967 beacon proxy.
+ *
+ * Reads the beacon slot (`0xa3f0…750d`); if non-zero, calls `implementation()`
+ * on the beacon contract. Returns `null` when the slot is empty or the beacon
+ * call fails.
+ */
+export async function detectEip1967Beacon(
+  rpc: string,
+  address: string,
+  fetchFn: typeof globalThis.fetch,
+): Promise<RawProxy | null> {
+  let beaconRaw: string
+  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: string
+  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,
+  }
+}

package/src/patterns/eip1967.ts

@@ -0,0 +1,44 @@
+import { EIP1967_ADMIN_SLOT, EIP1967_IMPL_SLOT } from '../constants'
+import { parseAddress } from '../decode'
+import { ethGetStorageAt } from '../rpc'
+import type { RawProxy } from '../types'
+
+/**
+ * Detect an EIP-1967 transparent or UUPS proxy.
+ *
+ * Reads the implementation slot (`0x3608…3bc3`). If non-zero, reads the admin
+ * slot in parallel and attaches it when present.
+ *
+ * Returns `null` when the implementation slot is empty or malformed.
+ */
+export async function detectEip1967(
+  rpc: string,
+  address: string,
+  fetchFn: typeof globalThis.fetch,
+): Promise<RawProxy | null> {
+  let implRaw: string
+  let adminRaw: string
+  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: RawProxy = {
+    pattern: 'eip-1967',
+    targets: [{ address: impl }],
+  }
+
+  const admin = parseAddress(adminRaw)
+  if (admin && admin !== '0x0000000000000000000000000000000000000000') {
+    proxy.admin = admin
+  }
+
+  return proxy
+}

package/src/patterns/eip897.ts

@@ -0,0 +1,35 @@
+import { IMPLEMENTATION_SELECTOR, ZERO_ADDRESS } from '../constants'
+import { parseAddress } from '../decode'
+import { ethCall } from '../rpc'
+import type { RawProxy } from '../types'
+
+/**
+ * Detect an EIP-897 delegate proxy by calling `implementation()` as a view
+ * function.
+ *
+ * Last-resort detector — any contract with a public `implementation()` view
+ * returning a non-zero address will match. Only reached when all other
+ * pattern detectors have returned `null`.
+ *
+ * Returns `null` when the call reverts or returns zero.
+ */
+export async function detectEip897(
+  rpc: string,
+  address: string,
+  fetchFn: typeof globalThis.fetch,
+): Promise<RawProxy | null> {
+  let raw: string
+  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 }],
+  }
+}

package/src/patterns/safe.ts

@@ -0,0 +1,37 @@
+import { ZERO_ADDRESS } from '../constants'
+import { parseAddress } from '../decode'
+import { ethGetStorageAt } from '../rpc'
+import type { RawProxy } from '../types'
+
+const SAFE_SINGLETON_SLOT = '0x0000000000000000000000000000000000000000000000000000000000000000'
+
+/**
+ * Detect a Gnosis Safe proxy — the singleton (implementation) address is
+ * stored at storage slot 0.
+ *
+ * Returns `null` when slot 0 is empty or not address-shaped.
+ *
+ * Cheap, but has a higher false-positive surface than the standard slots
+ * because any contract may use storage slot 0. Detector priority puts this
+ * after all EIP-standard patterns to keep the match rate clean.
+ */
+export async function detectGnosisSafe(
+  rpc: string,
+  address: string,
+  fetchFn: typeof globalThis.fetch,
+): Promise<RawProxy | null> {
+  let raw: string
+  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 }],
+  }
+}