investigation-report

> **${var}** — Base subject to investigate, plus optional flags: `<token-address> [--checks=rug,contract,deployer,holders,honeypot,lp] [--depth=quick|deep]`. The first token is the subject contract address (`0x…`, required). `--checks=` is a comma-list selecting which analyzers to run (**default = all six**). `--depth=` is `quick` (the old rug-scan fast path — minimal reads) or `deep` (full standalone logic of each selected check; **default**). If the subject address is empty, log `REPORT_NO_TARGET` and exit cleanly (no notify).
>
> Examples:
> - `0xToken` → all six checks, deep report.
> - `0xToken --checks=honeypot` → only the honeypot simulation (reproduces the standalone honeypot-check exactly, incl. its `HONEYPOT_*` end-states).
> - `0xToken --checks=rug,lp --depth=quick` → rug verdict + LP-lock, fast path.
> - `0xToken --checks=contract,deployer,holders --depth=deep` → structural audit + deployer entity intel + full concentration.

The "tell me everything about this token" skill. Instead of running six checks by hand, this composes them into one structured report behind a selector: **rug risk**, **contract audit** (verification / owner powers / proxy), **deployer trace** (who shipped it and their history), **holder concentration** (whale risk), **honeypot** (can you actually sell?), and **LP lock** (can the team pull liquidity?) — with a one-line summary on top.

Designed to **degrade gracefully**: each selected section runs independently, so a section that needs a key (or returns nothing) is marked `unavailable` without aborting the rest. Selecting a single check makes the composite behave as that one analyzer — same steps, same thresholds, same notify format, same status codes.

## Config

- Subject = the first token of `${var}` (validate: `0x` + 40 hex). Chain = Base (`chainid=8453`, explorer `basescan.org`).
- **Etherscan v2 unified API** (`https://api.etherscan.io/v2/api?chainid=8453&…`) — used by the `rug`, `contract`, `deployer`, `holders` checks. Works **keyless** at a lower rate limit.
- **Base RPC** (`${BASE_RPC_URL:-https://mainnet.base.org}`) — used by `honeypot`, `lp`, and the `eth_call`/`eth_getLogs`/`eth_getStorageAt`/`eth_getCode` reads inside the other checks. Keyless; any standard JSON-RPC endpoint works.
- Secrets (all **optional**):
  - `ETHERSCAN_API_KEY` (a.k.a. `BASESCAN_API_KEY` — same Etherscan v2 key) — appended to the Etherscan URL as `&apikey=…` via `./secretcurl`'s `{ETHERSCAN_API_KEY}` placeholder (never a bare `$SECRET` on the line, never a header). Raises the rate limit and unlocks verified source, full deployer history, and the holder list. Used by `rug`, `contract`, `deployer`, `holders`.
  - `BASE_RPC_URL` — overrides the default public Base RPC. Used by every RPC read; primary for `honeypot` and `lp`.
- **Preamble (run once, before dispatch):** read `memory/MEMORY.md` and the last ~2–3 days of `memory/logs/` so a repeat investigation can note what changed since last time and avoid re-reporting the same signal. Parse `${var}` → subject address, `--checks` (default all six), `--depth` (default `deep`).

## Steps

Dispatch to each selected check below (default: all six). Each is self-contained — collect its verdict/section; **never let one check's failure stop the others**. `--depth=quick` runs the lightweight path noted in each branch (rug-scan-style inline sampling, fewer calls); `--depth=deep` runs the full standalone logic.

### Check `rug` — Rug Scan

A fast, opinionated rug verdict: does the contract let someone print, freeze, or drain — and is supply/liquidity concentrated enough to pull?

**1. Verify contract + pull source**
```bash
TOKEN="${var}"
# ./secretcurl substitutes {ETHERSCAN_API_KEY} internally, so no `$SECRET` hits the
# command line (a bare one is refused by the Bash permission analyzer). Append the key
# only when set — Etherscan v2 works keyless at a lower rate limit.
KEYQ=""; [ -n "${ETHERSCAN_API_KEY:+x}" ] && KEYQ="&apikey={ETHERSCAN_API_KEY}"
./secretcurl -m 10 -s "https://api.etherscan.io/v2/api?chainid=8453&module=contract&action=getsourcecode&address=${TOKEN}${KEYQ}" | jq '.result[0]'
```
Capture `ContractName`, `Proxy`, `Implementation`, `SourceCode`. Empty `SourceCode` = **unverified** → strong risk signal.

**2. Scan source for dangerous powers** — grep the returned source (case-insensitive) for these signals and record which fire:

| Signal | Patterns | Weight |
|--------|----------|--------|
| Unverified source | empty `SourceCode` | +3 |
| Mint authority | `function mint`, `_mint(` callable by owner | +2 |
| Blacklist / freeze | `blacklist`, `isBlocked`, `_freeze`, `addBan` | +2 |
| Pausable transfers | `whenNotPaused`, `function pause` | +1 |
| Mutable fees/tax | `setFee`, `setTax`, `updateTaxes` | +2 |
| Owner not renounced | owner != `0x0` (see step 3) | +1 |
| Proxy / upgradeable | `Proxy == "1"` or `delegatecall` + upgrade fn | +2 |
| Trading toggle | `enableTrading`, `tradingActive`, `setSwapEnabled` | +1 |

**3. Check ownership state** — call `owner()` (selector `0x8da5cb5b`) via `eth_call`:
```bash
curl -m 10 -s -X POST "${BASE_RPC_URL:-https://mainnet.base.org}" -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_call","params":[{"to":"'"$TOKEN"'","data":"0x8da5cb5b"},"latest"],"id":1}' | jq -r '.result'
```
Trailing 40 hex chars = the owner address. All-zero → ownership renounced (lowers risk). A live EOA/multisig → flag the step-2 powers as *currently exercisable*.

**4. Holder concentration (quick read)**
```bash
KEYQ=""; [ -n "${ETHERSCAN_API_KEY:+x}" ] && KEYQ="&apikey={ETHERSCAN_API_KEY}"
./secretcurl -m 10 -s "https://api.etherscan.io/v2/api?chainid=8453&module=token&action=tokenholderlist&contractaddress=${TOKEN}&page=1&offset=10${KEYQ}" | jq '.result'
```
Compute top-1 and top-10 share of supply. Flag `+2` if top-1 > 30% (excluding known LP/lock/burn addresses), `+1` if top-10 > 70%. If this endpoint returns empty on the keyless tier, note `holders=unavailable` and skip this