@1001-digital/proxies 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 1001.digital
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,276 @@
+# @1001-digital/proxies
+
+Ethereum proxy pattern detection primitives for TypeScript — ERC-2535 diamonds, EIP-1967, EIP-1167, beacon, Safe, EIP-1822, EIP-897.
+
+Given a contract address, resolve where the real code lives: one implementation (plain proxy) or N facets (diamond). Uniform detect → enrich → compose pipeline across all patterns.
+
+Narrow on purpose: this package knows proxy conventions, selectors, and ABIs. Anything richer — Sourcify, NatSpec, repository metadata — is the consumer's concern. Bring your own enricher.
+
+## Install
+
+```bash
+pnpm add @1001-digital/proxies
+```
+
+## Usage
+
+### Detect + fetch a proxy
+
+```ts
+import { createProxies } from '@1001-digital/proxies'
+
+const proxies = createProxies()
+
+const result = await proxies.fetch(
+  'https://eth.llamarpc.com',
+  '0xProxyAddress…',
+)
+
+if (result) {
+  console.log(result.pattern)        // 'eip-1967' | 'eip-2535-diamond' | …
+  console.log(result.targets)        // [{ address, selectors?, abi? }, …]
+  console.log(result.compositeAbi)   // undefined — no enricher configured
+}
+```
+
+### Enrich with Sourcify (or anything else)
+
+The enricher returns each target's ABI. Anything richer (sources, bytecode,
+documentation, …) is the consumer's concern — see *Detect and do your own
+enrichment* below.
+
+```ts
+import { createProxies } from '@1001-digital/proxies'
+
+async function sourcifyAbi(address: string) {
+  const res = await fetch(
+    `https://sourcify.dev/server/v2/contract/1/${address}?fields=abi`,
+  )
+  if (!res.ok) return null
+  const { abi } = await res.json()
+  return { abi }
+}
+
+const proxies = createProxies({ enrich: sourcifyAbi })
+
+const result = await proxies.fetch(
+  'https://eth.llamarpc.com',
+  '0xProxyAddress…',
+)
+
+if (result) {
+  console.log(result.targets[0].abi) // ABI (filtered to selectors for diamonds, full for plain proxies)
+  console.log(result.compositeAbi)   // all target ABIs deduped by selector
+}
+```
+
+### Detect and do your own enrichment
+
+For richer per-target metadata, use `detect` and own the enrichment step
+end-to-end. `filterAbiBySelectors` and `buildCompositeAbi` remain useful
+primitives.
+
+```ts
+import {
+  createProxies,
+  filterAbiBySelectors,
+  buildCompositeAbi,
+} from '@1001-digital/proxies'
+
+const proxies = createProxies()
+const raw = await proxies.detect(rpc, address)
+
+if (raw) {
+  const enriched = await Promise.all(raw.targets.map(async t => {
+    const src = await mySource(t.address)
+    return {
+      ...t,
+      abi: src?.abi && t.selectors
+        ? filterAbiBySelectors(src.abi, t.selectors)
+        : src?.abi,
+      metadata: src?.metadata,
+    }
+  }))
+
+  const compositeAbi = buildCompositeAbi(
+    enriched.map(t => t.abi).filter((a): a is unknown[] => !!a),
+  )
+}
+```
+
+### Standalone primitives
+
+All low-level utilities are exported directly — use them without the factory:
+
+```ts
+import {
+  detectProxy,
+  detectDiamond,
+  detectEip1967,
+  decodeFacets,
+  computeSelector,
+  canonicalSignature,
+  filterAbiBySelectors,
+  buildCompositeAbi,
+  enrichTargets,
+} from '@1001-digital/proxies'
+
+decodeFacets('0x…')                            // parse a facets() return value
+computeSelector('transfer(address,uint256)')   // '0xa9059cbb'
+canonicalSignature({ type: 'function', name: 'transfer', inputs: [/*…*/] })
+```
+
+## API
+
+### `createProxies(config?)`
+
+Creates a proxies client.
+
+**Config options:**
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `enrich` | `TargetEnricher` | — | Default per-target enricher. Called with each target address; return `{ abi? }` or `null`. Errors are swallowed per-target. |
+| `fetch` | `typeof fetch` | `globalThis.fetch` | Custom fetch function. |
+
+**Returns** a `ProxiesClient` with:
+
+- **`detect(rpc, address)`** — `Promise<RawProxy | null>`. On-chain probe only.
+- **`fetch(rpc, address, options?)`** — `Promise<Proxy | null>`. Detect, enrich, and compose.
+  - `options.enrich` — per-call enricher (overrides config-level)
+  - `options.enrich = false` — skip enrichment for this call
+
+### Detection
+
+- **`detectProxy(rpc, address, fetchFn)`** — tries all patterns in priority order (`diamond → 1967 → 1967-beacon → 1822 → 1167 → safe → 897`), returns the first match.
+- **`detectDiamond`** — ERC-165 probe, then `facets()` fallback.
+- **`detectEip1967`** — reads impl slot `0x3608…3bc3`; optionally admin slot.
+- **`detectEip1967Beacon`** — reads beacon slot `0xa3f0…750d`, then `implementation()` on the beacon.
+- **`detectEip1822`** — reads PROXIABLE slot `0xc5f1…f8e2`.
+- **`detectEip1167`** — `eth_getCode`, matches minimal proxy bytecode (`363d3d…bf3`).
+- **`detectGnosisSafe`** — reads storage slot 0.
+- **`detectEip897`** — calls `implementation()` as a last resort.
+
+Each detector returns `null` if the pattern doesn't match; otherwise a `RawProxy`.
+
+### Composition
+
+- **`enrichTargets(targets, enricher | null)`** — applies the enricher to each target; ABIs are filtered to live selectors for diamonds, passed through for plain proxies.
+- **`buildCompositeAbi(abis)`** — pure; dedupes functions/events/errors across ABIs (first-wins).
+
+### Utilities
+
+- **`decodeFacets(hex)`** — pure; decodes `(address, bytes4[])[]` loupe return.
+- **`computeSelector(signature)`** — pure; keccak256-based 4-byte selector.
+- **`canonicalSignature(abiEntry)`** — pure; normalizes tuples/arrays into a signature string.
+- **`filterAbiBySelectors(abi, selectors)`** — pure; keeps non-functions, filters functions by selector.
+- **`ethCall`**, **`ethGetStorageAt`**, **`ethGetCode`** — minimal JSON-RPC helpers.
+
+### Constants
+
+```ts
+SUPPORTS_INTERFACE_SELECTOR      // '0x01ffc9a7'
+DIAMOND_LOUPE_INTERFACE_ID       // '0x48e2b093'
+FACETS_SELECTOR                  // '0x7a0ed627'
+IMPLEMENTATION_SELECTOR          // '0x5c60da1b'
+EIP1967_IMPL_SLOT
+EIP1967_BEACON_SLOT
+EIP1967_ADMIN_SLOT
+EIP1822_PROXIABLE_SLOT
+EIP1167_BYTECODE_PREFIX
+EIP1167_BYTECODE_SUFFIX
+ZERO_ADDRESS
+```
+
+### Errors
+
+- **`ProxiesError`** — base class.
+- **`ProxiesDecodeError`** — malformed `facets()` return.
+- **`ProxiesFetchError`** — JSON-RPC transport error.
+
+The client's `detect` and `fetch` methods swallow RPC-layer errors and return
+`null`; only `decodeFacets` (called directly) can throw `ProxiesDecodeError`
+on malformed input.
+
+## Shapes
+
+### `ProxyPattern`
+
+```ts
+type ProxyPattern =
+  | 'eip-2535-diamond'
+  | 'eip-1967'
+  | 'eip-1967-beacon'
+  | 'eip-1822'
+  | 'eip-1167'
+  | 'gnosis-safe'
+  | 'eip-897'
+```
+
+### `ResolvedTarget`
+
+```ts
+{
+  address: string
+  // undefined = all selectors route here (plain proxy)
+  // defined = diamond facet selector scope
+  selectors?: string[]
+}
+```
+
+### `RawProxy`
+
+```ts
+{
+  pattern: ProxyPattern
+  targets: ResolvedTarget[]   // 1 entry except for diamonds
+  beacon?: string             // only for eip-1967-beacon
+  admin?: string              // only for eip-1967 when admin slot is set
+}
+```
+
+### `EnrichedTarget`
+
+```ts
+{
+  address: string
+  selectors?: string[]
+  abi?: unknown[]
+}
+```
+
+### `Proxy`
+
+```ts
+{
+  pattern: ProxyPattern
+  targets: EnrichedTarget[]
+  beacon?: string
+  admin?: string
+  compositeAbi?: unknown[]   // deduped by selector
+}
+```
+
+### `TargetEnrichment`
+
+```ts
+{ abi?: unknown[] }
+```
+
+### `TargetEnricher`
+
+```ts
+type TargetEnricher = (address: string) => Promise<TargetEnrichment | null>
+```
+
+## Design notes
+
+- **Narrow scope** — detects patterns and composes ABIs; no opinion on documentation formats or richer per-target metadata.
+- **Dependency-injected enrichment** — the factory wires I/O when you ask; the primitives work offline.
+- **First-wins ABI dedup** — pass the most authoritative ABI first (e.g. main contract → impl, or main diamond → facets).
+- **Single-hop resolution** — if a resolved implementation is itself a proxy, `detectProxy` does not recurse. Beacon stays supported as a defined two-step pattern.
+- **Minimal runtime deps** — only `@noble/hashes` for keccak256.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,353 @@
+export declare interface AbiFunctionLike {
+    type: string;
+    name?: string;
+    inputs?: AbiParam[];
+}
+
+export declare interface AbiParam {
+    type: string;
+    components?: AbiParam[];
+}
+
+/**
+ * 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 declare function buildCompositeAbi(abis: unknown[][]): unknown[];
+
+/**
+ * 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 declare function canonicalSignature(fn: AbiFunctionLike): string;
+
+/**
+ * Compute the 4-byte selector for a canonical function signature.
+ * Example: `computeSelector('transfer(address,uint256)')` → `'0xa9059cbb'`.
+ */
+export declare function computeSelector(signature: string): string;
+
+/**
+ * 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 declare function createProxies(config?: ProxiesConfig): ProxiesClient;
+
+/**
+ * Literal on-chain facet tuple (`(address, bytes4[])`) — the shape returned by
+ * the ERC-2535 loupe `facets()` call. Use {@link decodeFacets} to parse it.
+ */
+export declare interface DecodedFacet {
+    facetAddress: string;
+    functionSelectors: string[];
+}
+
+/**
+ * Decode the return value of `facets()` — type `(address, bytes4[])[]`.
+ * Throws {@link ProxiesDecodeError} on malformed input.
+ */
+export declare function decodeFacets(hex: string): DecodedFacet[];
+
+/**
+ * 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 declare function detectDiamond(rpc: string, address: string, fetchFn: typeof globalThis.fetch): Promise<RawProxy | null>;
+
+/**
+ * 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 declare function detectEip1167(rpc: string, address: string, fetchFn: typeof globalThis.fetch): Promise<RawProxy | null>;
+
+/**
+ * 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 declare function detectEip1822(rpc: string, address: string, fetchFn: typeof globalThis.fetch): Promise<RawProxy | null>;
+
+/**
+ * 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 declare function detectEip1967(rpc: string, address: string, fetchFn: typeof globalThis.fetch): Promise<RawProxy | null>;
+
+/**
+ * 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 declare function detectEip1967Beacon(rpc: string, address: string, fetchFn: typeof globalThis.fetch): Promise<RawProxy | null>;
+
+/**
+ * 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 declare function detectEip897(rpc: string, address: string, fetchFn: typeof globalThis.fetch): Promise<RawProxy | null>;
+
+/**
+ * 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 declare function detectGnosisSafe(rpc: string, address: string, fetchFn: typeof globalThis.fetch): Promise<RawProxy | null>;
+
+/**
+ * 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 declare function detectProxy(rpc: string, address: string, fetchFn: typeof globalThis.fetch): Promise<RawProxy | null>;
+
+/** ERC-2535 Diamond Loupe `IDiamondLoupe` interface ID. */
+export declare const DIAMOND_LOUPE_INTERFACE_ID = "0x48e2b093";
+
+/** Prefix preceding the 20-byte implementation address in an EIP-1167 minimal proxy. */
+export declare const EIP1167_BYTECODE_PREFIX = "363d3d373d3d3d363d73";
+
+/** Suffix following the 20-byte implementation address in an EIP-1167 minimal proxy. */
+export declare const EIP1167_BYTECODE_SUFFIX = "5af43d82803e903d91602b57fd5bf3";
+
+/** EIP-1822 UUPS PROXIABLE slot: `keccak256('PROXIABLE')`. */
+export declare const EIP1822_PROXIABLE_SLOT = "0xc5f16f0fcc7e328891200cdca4c1c57b2b360c12265401510d42209b5829f8e2";
+
+/** EIP-1967 admin slot: `keccak256('eip1967.proxy.admin') - 1`. */
+export declare const EIP1967_ADMIN_SLOT = "0xb53127684a568b3173ae13b9f8a6016e243e63b6e8ee1178d6a717850b5d6103";
+
+/** EIP-1967 beacon slot: `keccak256('eip1967.proxy.beacon') - 1`. */
+export declare const EIP1967_BEACON_SLOT = "0xa3f0ad74e5423aebfd80d3ef4346578335a9a72aeaee59ff6cb3582b35133d50";
+
+/** EIP-1967 implementation slot: `keccak256('eip1967.proxy.implementation') - 1`. */
+export declare const EIP1967_IMPL_SLOT = "0x360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc";
+
+export declare 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[];
+}
+
+/**
+ * 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 declare function enrichTargets(targets: ResolvedTarget[], enrich: TargetEnricher | null): Promise<EnrichedTarget[]>;
+
+/**
+ * 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 declare function ethCall(rpc: string, to: string, data: string, fetchFn: typeof globalThis.fetch): Promise<string>;
+
+/**
+ * Minimal JSON-RPC `eth_getCode` client. Returns the deployed runtime bytecode
+ * at the latest block.
+ */
+export declare function ethGetCode(rpc: string, address: string, fetchFn: typeof globalThis.fetch): Promise<string>;
+
+/**
+ * Minimal JSON-RPC `eth_getStorageAt` client. Reads a single 32-byte storage
+ * slot at the latest block.
+ */
+export declare function ethGetStorageAt(rpc: string, address: string, slot: string, fetchFn: typeof globalThis.fetch): Promise<string>;
+
+/** ERC-2535 `facets()` — returns `(address, bytes4[])[]`. */
+export declare const FACETS_SELECTOR = "0x7a0ed627";
+
+export declare interface FetchProxyOptions {
+    /**
+     * Override the client's default enricher for this call. Pass `false` to
+     * disable enrichment entirely (address + selectors only).
+     */
+    enrich?: TargetEnricher | false;
+}
+
+/**
+ * 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 declare function filterAbiBySelectors(abi: unknown[], selectors: string[]): unknown[];
+
+/** `implementation()` — used by EIP-897 proxies and EIP-1967 beacons. */
+export declare const IMPLEMENTATION_SELECTOR = "0x5c60da1b";
+
+/**
+ * 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 declare function parseAddress(hex: string): string | null;
+
+export declare 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_2 | null>;
+}
+
+export declare 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;
+}
+
+/** Raised when the on-chain `facets()` return value cannot be decoded. */
+export declare class ProxiesDecodeError extends ProxiesError {
+    constructor(message: string, options?: ErrorOptions);
+}
+
+export declare class ProxiesError extends Error {
+    constructor(message: string, options?: ErrorOptions);
+}
+
+/** Raised when a JSON-RPC request fails at the transport level. */
+export declare class ProxiesFetchError extends ProxiesError {
+    readonly status: number;
+    constructor(message: string, details: {
+        status: number;
+    }, options?: ErrorOptions);
+}
+
+declare interface Proxy_2 {
+    pattern: ProxyPattern;
+    targets: EnrichedTarget[];
+    beacon?: string;
+    admin?: string;
+    /** Composite ABI across targets, deduped by selector (first-wins). */
+    compositeAbi?: unknown[];
+}
+export { Proxy_2 as Proxy }
+
+/** Discriminator for all supported proxy patterns. */
+export declare type ProxyPattern = 'eip-2535-diamond' | 'eip-1967' | 'eip-1967-beacon' | 'eip-1822' | 'eip-1167' | 'gnosis-safe' | 'eip-897';
+
+/**
+ * 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 declare 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;
+}
+
+/**
+ * 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 declare interface ResolvedTarget {
+    address: string;
+    selectors?: string[];
+}
+
+/** ERC-165 `supportsInterface(bytes4)`. */
+export declare const SUPPORTS_INTERFACE_SELECTOR = "0x01ffc9a7";
+
+/**
+ * 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 declare type TargetEnricher = (address: string) => Promise<TargetEnrichment | null>;
+
+export declare interface TargetEnrichment {
+    abi?: unknown[];
+}
+
+export declare const ZERO_ADDRESS = "0x0000000000000000000000000000000000000000";
+
+export { }