# Dedaub Decompiler API

> REST API that returns a smart contract's ABI, classic decompilation, and
> AI-based decompilation ("AI reconstruction") from Dedaub. It auto-follows
> proxies to their implementation and aggregates EIP-2535 diamond facets.
> Responses are cached, so repeated calls are cheap.

## Authentication
Every endpoint except `/health` requires an API token, sent as a header:
`Authorization: Bearer <token>`  (or `X-API-Key: <token>`).
Missing/invalid token -> 401.

## Conventions
- `{network}`: chain name. Common values: ethereum, arbitrum, base, polygon, optimism, bsc, avalanche.
- `{address}`: hex `0x...` contract address, case-insensitive.
- Errors are JSON: `{"detail": "..."}`. 404 = no contract at address (EOA or unknown to Dedaub).
- Booleans in query strings: `true` / `false`.

## Primary endpoint (use this by default)
GET /bundle/{network}/{address}
  Returns everything in one JSON object:
    - network, query_address, resolved_address
    - is_proxy, is_diamond, proxy_type, name
    - abi                 (JSON array; for diamonds, merged union of all facets)
    - decompiled          (string; classic decompilation)
    - ai_reconstruction   (string; AI source reconstruction, more readable Solidity)
    - source              (verified source if available: string or {filename: source})
    - available           ({abi, decompiled, ai_reconstruction, source} booleans)
    - facets, facet_count (diamonds only: per-facet address, selectors, and code)
  Query params:
    - follow_proxy=true|false   (default true)  follow proxy -> implementation
    - facets=true|false         (default true)  aggregate diamond facets
  Returns 404 if the address has no contract.
  Example:
    curl -H "Authorization: Bearer $TOKEN" \
      "https://HOST/bundle/ethereum/0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"

## Single-artifact endpoints (plain text or JSON)
GET /decompiled/{network}/{address}?follow_proxy=false   -> text/plain, classic decompilation
GET /ai/{network}/{address}?follow_proxy=false           -> text/plain, AI reconstruction
GET /abi/{network}/{address}?follow_proxy=false          -> application/json, ABI array
GET /code/{network}/{address}                            -> raw Dedaub payload (all levels)
GET /proxy/{network}/{address}                           -> proxy info (404 if not a proxy)

## Full resolution (structured, never 404 on EOA)
GET /resolve/{network}/{address}?follow_proxy=true&facets=false
  Always 200. Fields: exists, is_proxy, is_diamond, proxy, resolved_address,
  metadata, artifacts, implementation, facets, reason.
  For an EOA/unknown address: {"exists": false, "reason": "no_contract_or_eoa"}.

## Meta / admin
GET  /health          -> {"status":"ok"} (no auth)
GET  /whoami          -> Dedaub account in use
GET  /admin/cache     -> cache stats
POST /admin/cache/purge -> drop expired cache entries
DELETE /admin/cache   -> clear cache

## Tips for agents
- Prefer /bundle; read `available` before assuming an artifact exists.
- To analyze a proxy's real logic, keep follow_proxy=true (default).
- For a diamond, /bundle already merges all facets; per-facet detail is in `facets`.
- Calls are idempotent GETs and cached; retrying is safe.