@1001-digital/proxies 0.0.1

package/src/rpc.ts

@@ -0,0 +1,93 @@
+import { ProxiesFetchError, errorMessage } from './errors'
+
+interface JsonRpcResponse {
+  result?: string
+  error?: { message: string }
+}
+
+async function jsonRpcCall(
+  rpc: string,
+  method: string,
+  params: unknown[],
+  fetchFn: typeof globalThis.fetch,
+): Promise<string> {
+  let res: Response
+  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: JsonRpcResponse
+  try {
+    json = await res.json() as JsonRpcResponse
+  } 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'
+}
+
+/**
+ * Minimal JSON-RPC `eth_call` client. Invokes a view call on the given address
+ * at the latest block and returns the raw hex result.
+ */
+export function ethCall(
+  rpc: string,
+  to: string,
+  data: string,
+  fetchFn: typeof globalThis.fetch,
+): Promise<string> {
+  return jsonRpcCall(rpc, 'eth_call', [{ to, data }, 'latest'], fetchFn)
+}
+
+/**
+ * Minimal JSON-RPC `eth_getStorageAt` client. Reads a single 32-byte storage
+ * slot at the latest block.
+ */
+export function ethGetStorageAt(
+  rpc: string,
+  address: string,
+  slot: string,
+  fetchFn: typeof globalThis.fetch,
+): Promise<string> {
+  return jsonRpcCall(rpc, 'eth_getStorageAt', [address, slot, 'latest'], fetchFn)
+}
+
+/**
+ * Minimal JSON-RPC `eth_getCode` client. Returns the deployed runtime bytecode
+ * at the latest block.
+ */
+export function ethGetCode(
+  rpc: string,
+  address: string,
+  fetchFn: typeof globalThis.fetch,
+): Promise<string> {
+  return jsonRpcCall(rpc, 'eth_getCode', [address, 'latest'], fetchFn)
+}

package/src/selector.ts

@@ -0,0 +1,37 @@
+import { keccak_256 } from '@noble/hashes/sha3'
+import type { AbiFunctionLike, AbiParam } from './types'
+
+const encoder = new TextEncoder()
+
+/**
+ * Compute the 4-byte selector for a canonical function signature.
+ * Example: `computeSelector('transfer(address,uint256)')` → `'0xa9059cbb'`.
+ */
+export function computeSelector(signature: string): string {
+  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
+}
+
+/**
+ * Build the canonical signature for an ABI function/event/error entry,
+ * recursively expanding `tuple` into `(innerTypes)` while preserving any
+ * `[]` or `[N]` array suffix. This is the form hashed to produce selectors.
+ */
+export function canonicalSignature(fn: AbiFunctionLike): string {
+  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: AbiParam): string {
+  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
+}

package/src/types.ts

@@ -0,0 +1,131 @@
+// ── Patterns ──
+
+/** Discriminator for all supported proxy patterns. */
+export type ProxyPattern =
+  | 'eip-2535-diamond'
+  | 'eip-1967'
+  | 'eip-1967-beacon'
+  | 'eip-1822'
+  | 'eip-1167'
+  | 'gnosis-safe'
+  | 'eip-897'
+
+// ── Configuration ──
+
+export interface ProxiesConfig {
+  /**
+   * Default enricher used by `fetch` when no per-call enricher is passed.
+   * Receives each target address and returns whatever ABI the caller can find.
+   * Leave unset to return targets with address + selectors only.
+   */
+  enrich?: TargetEnricher
+  /** Custom fetch function. Default: `globalThis.fetch`. */
+  fetch?: typeof globalThis.fetch
+}
+
+export interface FetchProxyOptions {
+  /**
+   * Override the client's default enricher for this call. Pass `false` to
+   * disable enrichment entirely (address + selectors only).
+   */
+  enrich?: TargetEnricher | false
+}
+
+// ── On-chain / raw ──
+
+/**
+ * A resolved target behind a proxy — an implementation address, with optional
+ * selector scope.
+ *
+ * - `selectors: string[]` — this target serves exactly these selectors (diamond facets).
+ * - `selectors: undefined` — this target receives all calls (every other proxy pattern).
+ */
+export interface ResolvedTarget {
+  address: string
+  selectors?: string[]
+}
+
+/**
+ * Raw on-chain detection result. Contains a pattern discriminator and the
+ * resolved target(s). Single-impl proxies carry exactly one target; diamonds
+ * carry one per facet.
+ */
+export interface RawProxy {
+  pattern: ProxyPattern
+  targets: ResolvedTarget[]
+  /** EIP-1967 beacon address (only set for `eip-1967-beacon`). */
+  beacon?: string
+  /** EIP-1967 admin address (only set for `eip-1967` when the admin slot is non-zero). */
+  admin?: string
+}
+
+// ── Enrichment ──
+
+/**
+ * User-supplied per-target enricher. Receives a target's address and returns
+ * its ABI. Return `null` for unknown targets — errors are swallowed per-target
+ * so one bad fetch does not fail the whole resolution.
+ *
+ * The package is intentionally narrow here: it only composes ABIs. For
+ * richer per-target metadata, use {@link ProxiesClient.detect} and enrich
+ * the raw targets yourself.
+ */
+export type TargetEnricher = (address: string) => Promise<TargetEnrichment | null>
+
+export interface TargetEnrichment {
+  abi?: unknown[]
+}
+
+// ── Public result shapes ──
+
+export interface EnrichedTarget {
+  address: string
+  /** Selector scope for diamond facets; undefined for single-impl proxies (all selectors). */
+  selectors?: string[]
+  /**
+   * ABI for this target. Filtered to `selectors` for diamonds; full implementation
+   * ABI for single-impl proxies.
+   */
+  abi?: unknown[]
+}
+
+export interface Proxy {
+  pattern: ProxyPattern
+  targets: EnrichedTarget[]
+  beacon?: string
+  admin?: string
+  /** Composite ABI across targets, deduped by selector (first-wins). */
+  compositeAbi?: unknown[]
+}
+
+// ── Client ──
+
+export interface ProxiesClient {
+  /**
+   * Detect the proxy pattern and resolve its target(s). Returns `null` if the
+   * contract is not a recognised proxy.
+   */
+  detect: (rpc: string, address: string) => Promise<RawProxy | null>
+  /**
+   * Detect + enrich. Returns `null` when the contract is not a recognised proxy.
+   * Uses the config-level enricher by default; override per-call via `options.enrich`.
+   */
+  fetch: (
+    rpc: string,
+    address: string,
+    options?: FetchProxyOptions,
+  ) => Promise<Proxy | null>
+}
+
+// ── ABI shape helpers (structural) ──
+
+export interface AbiParam {
+  type: string
+  components?: AbiParam[]
+}
+
+export interface AbiFunctionLike {
+  type: string
+  name?: string
+  inputs?: AbiParam[]
+}