@oracle-agent/oracle 0.13.1 → 0.14.0

package/docs/locals-only-fee-waiver.md

@@ -0,0 +1,34 @@
+# Locals Only fee waiver
+
+Oracle is public to everyone. Source access, npm installation, CLI commands,
+desktop downloads, ordinary product use, and execution arming are not gated by
+an NFT.
+
+It does not gate Oracle downloads, access, source, CLI use, desktop use, or
+execution preparation.
+
+A wallet holding a Locals Only NFT receives a **0% Oracle integrator fee**. A
+non-holder can use the same product and routes, but the standard disclosed
+Oracle fee applies when fee collection is configured.
+
+## Collection
+
+- Chain: HyperEVM, chain ID `999`
+- Contract: `0x62FCFAf7573AD8B41a0FBF347AfEb85e06599A75`
+- Check: read-only ERC-721 `balanceOf(address)`
+
+The balance check does not request a signature, approval, private key, seed
+phrase, or transaction. Run `oracle fees status` for the configured wallet or
+`oracle fees check <address>` for any public address.
+
+## Fee behavior
+
+- No fee recipient configured: Oracle charges no integrator fee to anyone.
+- Fee recipient configured, non-holder: the configured fee applies, capped at
+  100 basis points.
+- Fee recipient configured, Locals Only holder: Oracle's integrator fee is 0%.
+- Hyperliquid builder fees are not waived. Provider fees, bridge fees, gas,
+  slippage, LP fees, and network costs also remain separate.
+
+Fee resolution stays separate from custody. The public package remains keyless
+and prepare-only; the user's wallet reviews, signs, and submits.

package/docs/oracle-pack-standard.md

@@ -0,0 +1,29 @@
+# Oracle protocol pack standard
+
+An Oracle protocol pack is a package-safe ESM module that turns an intent into an unsigned action and decodes independently obtained receipts. A pack is an adapter, not a wallet, signer, broadcaster, or authority. See `examples/oracle-pack-template.mjs` for the smallest complete shape.
+
+## Required surface
+
+Every pack exports a default object with these members (named exports may mirror them):
+
+- `provider`: stable provider identity, semantic version, supported chain IDs, and provenance/trust metadata. Remote token names, symbols, descriptions, image fields, URLs, and NFT metadata remain untrusted data.
+- `prepare(intent)`: validates the intent and returns an unsigned transaction or typed action. It must not accept keys, sign, submit, broadcast, or report execution success.
+- `decode(receipt)`: validates and converts a chain/provider receipt into a documented result. Unknown or malformed receipts fail closed.
+- `riskRules`: an array or function describing enforceable limits and refusal conditions. Human-readable warnings alone are not rules.
+- `tests`: non-empty metadata naming the local test command and covered properties. Tests must be deterministic and require no credentials or network.
+
+## Prompt-injection boundary
+
+Treat every provider response and token/NFT metadata string as inert data. Never concatenate metadata into system/developer instructions, interpret it as tool directions, or let it modify recipients, calldata, limits, and policy. Render or quote it through a data channel and retain its provenance. Packs should test adversarial values such as “ignore previous instructions,” requests for secrets, and demands to sign or invoke tools.
+
+## Custody boundary
+
+Pack exports must not expose signers, wallets, private keys, seed phrases, signing functions, transaction submission, or broadcasting. `prepare` returns data to a separately authorized custody surface. Environment variables and provider credentials must not appear in prepared output, logs, errors, fixtures, or metadata. Imports should be side-effect free; merely loading a pack must not make network calls.
+
+## Receipt gate
+
+Preparation is not execution. A prepared result declares a `receiptGate` and consumers must not mark an action successful until `decode` receives a receipt from an independent, trusted transport and verifies its chain, transaction identity, status, and required confirmations. Timeouts, pending receipts, mismatches, reverts, and undecodable responses are not success.
+
+## Local adversarial benchmark
+
+Run `node scripts/adversarial-bench.mjs <pack.mjs> [...]`. It imports only the named local modules, invokes no pack functions, emits one deterministic JSON summary, and exits `1` when a gate fails (`2` for usage/load errors). It checks required surface fields, forbidden custody exports, missing test metadata, and prompt-injection strings nested in provider or pack metadata. This static public gate complements, rather than replaces, behavioral tests of preparation and receipt verification.

package/docs/profiles.md

@@ -0,0 +1,151 @@
+# Agent profiles
+
+Oracle is not one agent. It's a mesh of specialists with a router in front.
+
+```
+        you
+         |
+       Task
+         |
+      oracle            <- routes, never authorizes custody
+         |
+  +------+------+------+------+------+------+------+
+  |      |      |      |      |      |      |      |
+ poly   hyper  robin  solana bitcoin stable protocol
+ market liquid hood                         builder
+```
+
+Each lane is a [Hermes](https://github.com/NousResearch/hermes-agent) **profile**:
+its own system prompt, skill set, memory, and session store. They share a wallet
+policy and a receipts discipline, nothing else.
+
+## Why profiles instead of one big agent
+
+Three practical reasons, learned the hard way:
+
+1. **Context stays small.** A Polymarket question shouldn't load Bitcoin
+   ordinals knowledge. Smaller context is cheaper, faster, and more accurate.
+2. **Memory doesn't cross-contaminate.** What the perps lane learned about
+   funding rates should not leak into the NFT lane's judgment.
+3. **Blast radius is bounded.** A grant scoped to one lane's venues can't be
+   spent by another.
+
+## The lanes
+
+| Profile | Owns | Typical grant |
+|---|---|---|
+| `oracle` | routing, synthesis, multi-chain comparison, `/balance` portfolio aggregation | read + simulate only |
+| `polymarket-agent` | prediction markets, event odds, CLOB cards/API-key order intents | read, quote, prepare |
+| `hyperliquid-agent` | perps, spot, HIP-3 builder dexs, HIP-4 outcomes | read, quote, prepare |
+| `robinhood-agent` | Robinhood Chain (4663) tokens, NFTs, tokenized Robinhood-style assets, capped NFT mints | read, quote, prepare |
+| `solana-agent` | Solana swaps, research, Jupiter routes | read, quote, prepare |
+| `bitcoin-agent` | Bitcoin L1, Ordinals/runes, inscriptions | read, prepare:inscription |
+| `stable-agent` | Stable (988), USDT-native gas quirks | read, quote, prepare |
+| `protocol-builder` | scaffold, review, prepare chain-family token/NFT collections, gacha, DEX, and protocol deploys | prepare:deploy, prepare:mint, simulate |
+| `_template` | your new lane | you decide |
+
+These grants describe the public prepare plane, not every capability an operator may install beside it. The generic unattended signer exposes six bounded surfaces (`hl`, `poly`, `evm-swap`, `evm-bridge`, `btc`, `sol`), each of which decodes its own envelope and refuses while its allowlists are empty. A separately installed, same-host, owner-gated EVM executor may expose one exact bounded action after explicit `arm`; profiles must verify it before claiming availability. `watch`, `watch this`, and `ping me` remain `alert_only` regardless of executor presence.
+
+`protocol-builder` classifies each launch by chain family, then designs and
+prepares unsigned token, NFT collection, protocol, or mint-bot transactions. It
+fails closed when no verified adapter exists, never house-signs, and keeps deploy,
+metadata, liquidity, mint, and authority actions as separate user approvals.
+
+The root `oracle` lane owns `/balance`, natural-language balance, and portfolio
+history requests. Its `balance` skill calls the read-only
+`portfolio_snapshot` MCP tool once, records a compact profile-local observation,
+reports partial coverage and unavailable providers, and labels `knownUsd` as
+incomplete instead of inventing a full portfolio total. `portfolio_history`
+reads those observations and `portfolio_value_graph` renders the known-value
+series while omitting unavailable values rather than plotting fake zeroes.
+
+## Model choice is yours
+
+Oracle makes **no model calls**. It has no LLM client, no API key, no inference
+dependency — its runtime deps are `ethers`, `viem`, and three `@noble`/`@scure`
+crypto libraries. Every lane inherits whatever provider your Hermes is configured
+with.
+
+So there is nothing to sign up for. If Hermes already talks to a model, Oracle
+works.
+
+What profiles *do* give you is **per-lane** model choice, because each profile has
+its own `config.yaml`:
+
+```yaml
+# ~/.hermes/profiles/<name>/config.yaml
+model:
+  provider: anthropic        # or openai-codex, nous, xai-oauth, a local model...
+  default: claude-opus-5
+```
+
+That lets you put a heavy reasoner on the router and something cheap and fast on
+a polling lane:
+
+| Lane | Wants | Why |
+|---|---|---|
+| `oracle` | strongest reasoner | routing and synthesis need judgment |
+| `protocol-builder` | strongest reasoner | contract review is unforgiving |
+| `hyperliquid-agent` | fast, numeric, tool-heavy | many small tool calls |
+| `polymarket-agent` | news-shaped reasoning | event pricing is narrative |
+| research fan-out | cheap and parallel | breadth over depth |
+
+Starting point, not doctrine. Benchmark on your own workload.
+
+### If you want one login for many models
+
+Optional convenience, not a requirement: [Nous
+Portal](https://nousresearch.com) fronts the frontier set (Claude, GPT, Grok,
+DeepSeek, Qwen and more) behind a single Hermes credential, so each lane can pick
+a different model without five separate API keys and five bills.
+
+```bash
+hermes auth add nous
+```
+
+Any Hermes-supported provider works equally well. Oracle does not care.
+
+## Creating a lane
+
+```bash
+hermes profile create polymarket-agent
+```
+
+Then give it a `SOUL.md` (who it is, what it owns, what it must refuse) and a
+`config.yaml` (model + provider). Point it at Oracle's MCP read plane.
+
+`oracle-init --apply` writes this for you. Manual form (Hermes wants command and
+args as separate tokens):
+
+```bash
+# terminal 1 — local read plane the MCP tools call
+npx oracle-data
+
+# terminal 2 — wire MCP into a lane
+hermes -p polymarket-agent mcp add oracle-data --command oracle-data-mcp
+```
+
+Now that lane can read 70 provider modules covering 219 protocols/venues across
+EVM, Solana, and Bitcoin, quote real routes, and
+prepare unsigned transactions — and it still cannot sign anything.
+
+## Posture
+
+Every lane starts `DISARMED`. Arming is a deliberate, scoped, expiring act:
+
+```
+grant:
+  chain: 8453
+  actions: [read:chain, simulate:tx, prepare:swap]
+  targets: [<router address>]
+  maxValueWei: <cap>
+  expiresAt: <unix ts>
+```
+
+An action outside the grant is refused, not negotiated. When the grant expires,
+the lane goes back to reading.
+
+## A rule worth keeping
+
+Give a lane the narrowest grant that makes it useful, and let it expire. A
+permanent broad grant is just a hot wallet with extra steps.

package/docs/public-surface.md

@@ -0,0 +1,206 @@
+# Public surface
+
+Every supported import subpath, executable, and runtime environment variable in
+`@oracle-agent/oracle`. If something is in `exports`/`bin` it is a public
+contract and belongs here; if it is not meant to be public it should be removed
+from the manifest rather than left undocumented.
+
+Generated counts are asserted by `test/public-surface-doc.test.mjs`, so this
+file cannot silently drift from `package.json`.
+
+## Import subpaths
+
+| Subpath | What it gives you |
+|---|---|
+| `@oracle-agent/oracle` | package root — re-exports the common surface |
+| `@oracle-agent/oracle/data` | provider catalog + `dataCall` read plane |
+| `@oracle-agent/oracle/policy` | grant policy schema: validation, canonicalization, caps constants |
+| `@oracle-agent/oracle/chains` | chain registry and per-chain metadata |
+| `@oracle-agent/oracle/scanner` | token/contract scanner capabilities |
+| `@oracle-agent/oracle/router` | route sources and quote routing |
+| `@oracle-agent/oracle/equities` | cross-chain on-chain equities best execution (HIP-3 / Arcus / RH / Solana / TON), prepare-only |
+| `@oracle-agent/oracle/action-semantics` | decoded-action semantics for review |
+| `@oracle-agent/oracle/address-book` | label store — refuses key material |
+| `@oracle-agent/oracle/agent-grants` | bounded, revocable, time-boxed agent permissions: `planConnection` builds the unsigned grant, `activateSession` accepts the owner's signature, `revokeSession` revokes, and `listActiveGrants`/`getGrant`/`classifyGrant` read it back. Reads are pure over an injected store with an explicit clock. Oracle prepares and validates; the user signs and Oracle never holds a key |
+| `@oracle-agent/oracle/names` | cross-chain name resolution: `.hl` (HLNames), `.hype` (dotHYPE), `.eth` (ENS), Basenames. Forward and reverse, keyless on-chain reads via the read-only RPC allowlist; never signs or broadcasts |
+| `@oracle-agent/oracle/nft-gas-war` | NFT mint/gas-war helpers |
+| `@oracle-agent/oracle/prepare-envelope` | `stampPrepared` / `assertPreparedEnvelope` |
+| `@oracle-agent/oracle/connect` | deterministic MCP harness configuration snippets for Hermes, Claude Code, Codex, Cursor, and generic clients |
+| `@oracle-agent/oracle/receipts` | caller-fact action-receipt normalization — refuses secret-bearing fields; does not verify chain success |
+| `@oracle-agent/oracle/risk` | risk scoring helpers |
+| `@oracle-agent/oracle/watch` | watch/alert subscriptions |
+| `@oracle-agent/oracle/signals` | signal feed helpers |
+| `@oracle-agent/oracle/farming` | farming method presets, live farm scoring (`discoverFarms`), and airdrop expected-value math (`airdropEV`) — read-only discovery and prepare-plan design; never signs or broadcasts |
+
+`./package.json` is deliberately **not** exported. Do not derive internal paths
+with `require.resolve('@oracle-agent/oracle/package.json')` — it throws
+`ERR_PACKAGE_PATH_NOT_EXPORTED`. Invoke the shipped bins by name instead.
+
+## Executables
+
+| Bin | Purpose |
+|---|---|
+| `oracle` | main CLI |
+| `oracle-data` | local read-plane server (`oracle data serve`) |
+| `oracle-public` | public-plane server (`oracle public serve`) |
+| `oracle-data-mcp` | MCP stdio server for agent lanes |
+| `oracle-init` | write config + attestation secret (`oracle init --apply`) |
+| `oracle-upgrade` | in-place upgrade helper (`oracle upgrade`) |
+| `oracle-scan` | scanner entrypoint |
+| `oracle-route` | route/quote entrypoint |
+| `oracle-equities` | on-chain equities best execution (HIP-3 / Arcus / RH / Solana / TON) |
+
+## Environment variables
+
+### Arming flags — default OFF, enable only on literal `1`
+
+These are the gates that decide whether anything can ever be signed or
+broadcast. `envFlag` is strict: `true`, `yes`, `on`, or any other value leaves
+them OFF. Setting them is not sufficient to move funds — the signer's own
+policy and custody wall still apply.
+
+| Name | Default | Meaning |
+|---|---|---|
+| `ORACLE_EXECUTE_ENABLED` | off | allow the signing surface to arm at all |
+| `ORACLE_DEPLOY_ENABLED` | off | allow contract deployment paths to arm |
+| `ORACLE_ONBOARD_HTTP` | off | expose onboarding routes over HTTP |
+| `ORACLE_PUBLIC_API_MODE` | off | run the server in public-plane mode |
+| `ORACLE_ALLOW_CREATE` | off | allow create/deploy-shaped actions |
+| `ORACLE_ALLOW_EPHEMERAL_CAPS` | off | allow ephemeral cap grants |
+
+### Guard rails — default ON, honor disable words
+
+| Name | Default | Meaning |
+|---|---|---|
+| `ORACLE_VALUE_CAPS_ENABLED` | on | per-transaction value caps. Uses strict `!== "0"` so a stray `false` leaves the cap wall standing |
+
+### Integrity and attestation
+
+| Name | Meaning |
+|---|---|
+| `ORACLE_ROUTE_ATTESTATION_SECRET` | keyed route attestation HMAC. Written by `oracle init --apply` |
+| `MAD_ROUTE_ATTESTATION_SECRET` | legacy alias for the above |
+| `ORACLE_ATTESTATION_SECRET` | alternate attestation secret name |
+| `ORACLE_STAMP_HMAC_SECRET` | keyed MAC over prepared envelopes. A verifier holding this secret **requires** a valid MAC — an envelope with the MAC stripped is refused, so the keyed mode cannot be silently downgraded to the unkeyed checksum |
+| `ORACLE_STAMP_REQUIRE_MAC` | set `1` to require a MAC even when the verifier has no secret configured. With a secret set this is already implied |
+| `ORACLE_PREPARE_HARD_MAX_AGE_MS` | hard ceiling on prepared-envelope age |
+
+### Servers and endpoints
+
+| Name | Default | Meaning |
+|---|---|---|
+| `ORACLE_INTEGRATOR_FEE_BPS` | unset (no fee) | Integrator fee in basis points on routed swaps, clamped to 100 (1%). Unset, zero, negative or malformed means **no fee**. Locals Only holders receive a 0% Oracle integrator-fee rate regardless of this value; ownership never changes product access |
+| `ORACLE_INTEGRATOR_FEE_RECIPIENT` | unset | EVM address that receives the fee. **Required**: a fee configured without a valid recipient fails closed to no fee, because otherwise the basis points are charged and silently kept by the aggregator |
+| `ORACLE_INTEGRATOR_ID` | `oracle` | Integrator/partner string sent to route providers. ParaSwap accepts any value with no registration; LI.FI requires the id to be registered at portal.li.fi or the quote 400s |
+| `ORACLE_DATA_HOST` | `127.0.0.1` | read-plane bind host (loopback enforced) |
+| `ORACLE_DATA_PORT` | `8787` | read-plane port |
+| `ORACLE_DATA_URL` | `http://127.0.0.1:8787` | where the CLI looks for the data server |
+| `ORACLE_PUBLIC_HOST` | `127.0.0.1` | public-plane bind host (loopback enforced) |
+| `ORACLE_PUBLIC_PORT` | — | public-plane port |
+| `ORACLE_TRUST_PROXY` | unset (off) | when `1`, read the caller IP from `X-Forwarded-For` for rate limiting. Set this ONLY when the service sits behind a proxy you control that overwrites the header. Enabling it on a directly-exposed server lets any client spoof a fresh identity per request and bypass the rate limit entirely. |
+| `ORACLE_INDEXER_RPC_<CHAINID>` | unset | optional `eth_getLogs`-capable endpoint for one chain, e.g. `ORACLE_INDEXER_RPC_1`. Enables full approval discovery on that chain instead of the curated candidate probe. |
+| `ORACLE_INDEXER_RPC_DEFAULT` | unset | fallback indexer endpoint for chains without a specific override. |
+| `ORACLE_INDEXER_CHUNK_SPAN` | `10000` | max block span per `eth_getLogs` query. Many endpoints refuse wider ranges; lower it if yours caps harder. |
+
+### Approval discovery coverage
+
+Without an indexer endpoint, approval scanning probes a curated set of known
+routers and tokens with `allowance()`. That works on any public RPC but is
+scoped: an approval to a spender outside the list is not found, so an empty
+result means "nothing found in that scope", never "this wallet is safe". The UI
+states the scope rather than implying safety.
+
+Configuring `ORACLE_INDEXER_RPC_*` upgrades discovery to log-derived, covering
+all tokens and spenders. Liveness is still confirmed by re-reading
+`allowance()` / `isApprovedForAll()`, because log state alone reports
+long-revoked approvals as active.
+
+### Rate limiting and admission
+
+#### `0.12.0` clock migration
+
+`buildConnectRequest`, `assembleUnsignedGrant`, and `planConnection` now require
+`opts.now` even when the input already supplies an absolute `expiresAt`. Callers
+migrating from `0.11.x` must pass a positive unix-seconds integer. This is an
+intentional fail-closed API change: live construction no longer silently falls
+back to shape-only validation. Hosted HTTP callers should not send a security
+clock; the server replaces caller time with its own clock.
+
+Live grants have a hard maximum TTL of 24 hours. Direct library calls to
+`buildConnectRequest` and `assembleUnsignedGrant` require an explicit
+`opts.now` so deterministic tests and offline clients cannot fall back to an
+implicit clock. At the HTTP boundary, caller-provided `opts.now` is ignored:
+the server clock is authoritative for connect, assemble, active-list, and
+grant-status routes. Caller-provided `allowWildcardActions` is also ignored;
+hosted grant routes always reject wildcard scope. Shape-only normalization
+without `now` is reserved for historical identification/indexing and does not
+establish live authority.
+
+The public plane is unauthenticated, so both planes are throttled per caller IP
+in fixed 60-second windows: 120 requests for cheap reads, and 10 for
+`/public/approvals`, which fans a single request out to many upstream RPC calls.
+A throttled caller gets `429` with `Retry-After` before any request body is
+parsed. `chainIds` is additionally capped at 12 per request so one call cannot
+cost as much as many.
+
+This limiter is an abuse brake, not authentication. Keep the server on loopback;
+a hosted service requires server-side authentication and per-user isolation.
+Buzz discovery, capability verification, and audit routes are documented in
+[buzz-integration.md](buzz-integration.md).
+
+Counters are in memory and reset on restart. That is sufficient for accidental
+hammering and casual abuse; a distributed flood still needs an edge/WAF in
+front.
+
+The data server serves `/health`; `/` intentionally returns 404 with a route
+list.
+
+### Paths and config
+
+| Name | Meaning |
+|---|---|
+| `ORACLE_CONFIG_DIR` | config directory (default `~/.config/oracle`) |
+| `ORACLE_EXEC_ENV_FILE` | path to `exec.env` |
+| `ORACLE_AGENT_KEYS_PATH` | agent key store path |
+| `ORACLE_AUTH_FILE_STORE` | auth file store path |
+| `ORACLE_ADDRESS_BOOK` | address-book path |
+| `ORACLE_OPERATOR_BIN_DIR` | operator binary directory |
+| `ORACLE_AUDIT_STREAM` | audit stream destination |
+
+### Packaged desktop mode
+
+The desktop app sets these itself. They are documented because they change
+security-relevant behavior, and an operator should be able to find out exactly
+what the bundled app does differently from a plain `npm i -g` install.
+
+| Name | Default | Meaning |
+|---|---|---|
+| `ORACLE_PUBLIC_DESKTOP` | off | Marks the process as the packaged public desktop. While on: the sign-plane operator is never resolved even if one is installed on the host, remote compute backends are refused, and legacy `~/.config/mad-desk` fallbacks resolve to the app-owned config dir instead of the host's. |
+| `ORACLE_REMOTE_COMPUTE_DISABLE` | off | Refuses any remote/SSH chat compute backend regardless of stored config. |
+
+### Routing and defaults
+
+| Name | Meaning |
+|---|---|
+| `ORACLE_ALLOWED_CHAINS` | restrict routing to a chain allowlist |
+| `ORACLE_DEFAULT_ADDRESS` | default address for reads |
+| `ORACLE_PROFILE` | active profile name |
+| `ORACLE_PRIVY_APP_ID` | Privy app id for connect flows |
+
+### Runtime integration
+
+| Name | Meaning |
+|---|---|
+| `ORACLE_HERMES_BIN` | path to the agent runtime binary |
+| `ORACLE_CLAUDE_CODE_VERSION` | pinned agent runtime version |
+| `ORACLE_PYTHON` / `ORACLE_UV_BIN` | interpreter overrides |
+| `ORACLE_NATIVE_TUI` / `ORACLE_FORCE_CHAT` / `ORACLE_PLAIN_HARNESS` | CLI presentation modes |
+| `ORACLE_NO_BOOTSTRAP` | skip bootstrap on start |
+| `ORACLE_CLI_DEBUG` | verbose CLI diagnostics |
+
+### Test-only
+
+| Name | Meaning |
+|---|---|
+| `ORACLE_TEST_ISOLATE_SECRETS` | isolate secrets during tests |
+| `ORACLE_FAKE_HOME` | redirect `$HOME` during tests |

package/examples/add-a-chain.mjs

@@ -0,0 +1,65 @@
+// Example: register a chain Oracle has never seen, then use it.
+//
+// Run:  node examples/add-a-chain.mjs
+//
+// The point of this example is that there is no adapter to write. A chain is a
+// config object; the generic EVM scanner supplies the capabilities.
+
+import { registerCustomChain } from "../src/scanner/chains.config.mjs";
+import { scannerCoverage } from "../src/scanner/contract.mjs";
+
+// 1. Describe the chain. Note rpcEnv holds VARIABLE NAMES, not URLs -- endpoints
+//    stay in the environment so nothing sensitive lands in source control.
+const scanner = registerCustomChain({
+  key: "examplechain",
+  chainId: 424242,
+  name: "Example Chain",
+  rpcEnv: ["EXAMPLECHAIN_RPC_URL"],
+  nativeCurrency: { symbol: "EXC", decimals: 18 },
+  explorer: "https://explorer.example",
+
+  // Omitted deliberately: dexscreenerSlug. Without it, pool discovery reports
+  // UNAVAILABLE rather than guessing -- a wrong slug would return another chain's
+  // pools, which is worse than no answer.
+
+  // Omitted deliberately: venues. With none, the chain is read/research capable and
+  // fail-closed for routing value. Adding one requires recorded provenance; see
+  // docs/adding-a-chain.md.
+});
+
+console.log(`registered: ${scanner.name} (chain ${scanner.chainId})`);
+
+// 2. Ask what it can actually do. The answer is honest -- unimplemented
+//    capabilities are listed as unsupported, not silently absent.
+const caps = scanner.capabilities();
+console.log(`\nsupported   (${caps.supported.length}): ${caps.supported.join(", ")}`);
+console.log(`unsupported (${caps.unsupported.length}): ${caps.unsupported.join(", ")}`);
+
+// 3. An unimplemented capability throws with an actionable message. It never
+//    returns undefined, which a caller could mistake for "no result".
+try {
+  await scanner.quote({ from: "0x", to: "0x", amount: "1" });
+} catch (err) {
+  console.log(`\nquote() correctly refused:\n  ${err.message.split("\n")[0]}`);
+}
+
+// 4. Pool discovery is UNAVAILABLE, and says why.
+const pools = await scanner.resolvePools("0x1111111111111111111111111111111111111111");
+console.log(`\nresolvePools evidence: ${pools.evidence}`);
+console.log(`  reason: ${pools.reason}`);
+
+// 5. Live reads need an RPC. Show the exact variable to set rather than failing
+//    with a generic network error.
+console.log(`\nto make live reads, set one of: ${scanner.rpcEnv.join(", ")}`);
+try {
+  const head = await scanner.blockNumber();
+  console.log(`  head: ${head.blockNumber} (${head.evidence})`);
+} catch {
+  console.log("  (no RPC configured -- expected for this example chain)");
+}
+
+// 6. The coverage matrix now includes it alongside the built-ins.
+const cov = scannerCoverage();
+console.log(`\ncoverage: ${cov.chainCount} chain(s) registered`);
+const mine = cov.chains[424242];
+console.log(`  examplechain failClosed for routing: ${mine.failClosed}`);

package/examples/oracle-pack-template.mjs

@@ -0,0 +1,38 @@
+import assert from "node:assert/strict";
+
+// Minimal Oracle protocol pack. It prepares unsigned actions; it never receives
+// keys, signs, broadcasts, or claims that untrusted metadata is an instruction.
+
+export const provider = Object.freeze({
+  id: "example-protocol",
+  version: "1.0.0",
+  chains: [8453],
+  metadata: { source: "on-chain", trust: "untrusted-data" },
+});
+
+export function prepare(intent) {
+  assert.ok(intent && provider.chains.includes(intent.chainId), "unsupported chain");
+  return {
+    kind: "unsigned-transaction",
+    chainId: intent.chainId,
+    transaction: { to: intent.to, data: intent.data ?? "0x", value: intent.value ?? "0" },
+    receiptGate: { required: true, confirmations: 1, match: ["chainId", "transaction.to"] },
+  };
+}
+
+export function decode(receipt) {
+  assert.ok(receipt && typeof receipt.status !== "undefined", "receipt required");
+  return { success: receipt.status === 1 || receipt.status === "0x1", transactionHash: receipt.transactionHash };
+}
+
+export const riskRules = Object.freeze([
+  { id: "explicit-recipient", field: "transaction.to", required: true },
+  { id: "receipt-before-success", field: "receiptGate.required", equals: true },
+]);
+
+export const tests = Object.freeze({
+  command: "node --test test/oracle-pack-standard.test.mjs",
+  covers: ["prepare-is-unsigned", "decode-requires-receipt", "metadata-is-untrusted"],
+});
+
+export default Object.freeze({ provider, prepare, decode, riskRules, tests });

package/examples/research-a-token.mjs

@@ -0,0 +1,70 @@
+// Example: research a token end to end, honestly.
+//
+// Run:  node examples/research-a-token.mjs
+//       node examples/research-a-token.mjs base 0x<address>
+//
+// Demonstrates the discipline the desk is built around: read the identity off the
+// chain, find pools with real liquidity, and report UNKNOWN where a check could not
+// run rather than letting silence read as approval.
+
+import { registerBuiltinScanners } from "../src/scanner/chains.config.mjs";
+import { getScanner, listScanners, EVIDENCE, RISK } from "../src/scanner/contract.mjs";
+
+registerBuiltinScanners();
+
+const chainRef = process.argv[2] || "base";
+// Base USDC by default -- a token whose answers are easy to sanity-check.
+const token = process.argv[3] || "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913";
+
+const scanner =
+  listScanners().find((s) => s.key === chainRef) || getScanner(Number(chainRef));
+if (!scanner) {
+  console.error(`unknown chain "${chainRef}"`);
+  process.exit(1);
+}
+
+console.log(`chain: ${scanner.name} (${scanner.chainId})`);
+console.log(`token: ${token}\n`);
+
+// 1. Identity from the CONTRACT, not a token list. A list can be stale or omit a
+//    two-hour-old launch, and the on-chain answer is what governs a transfer.
+const meta = await scanner.resolveToken(token);
+if (meta.evidence !== EVIDENCE.LIVE) {
+  console.log(`identity: ${meta.evidence} -- ${meta.warning ?? meta.error}`);
+  console.log("stopping: without ERC-20 metadata there is nothing to price.");
+  process.exit(0);
+}
+console.log(`identity: ${meta.symbol} (${meta.name}), ${meta.decimals} decimals`);
+
+// 2. Pools, ranked by liquidity. Depth is what determines your fill; the headline
+//    price is a fiction for anything but the smallest clip.
+const pools = await scanner.resolvePools(token);
+console.log(`\npools: ${pools.evidence}`);
+if (pools.reason) console.log(`  ${pools.reason}`);
+for (const p of pools.pools.slice(0, 5)) {
+  const liq = p.liquidityUsd == null ? "unknown" : `$${Math.round(p.liquidityUsd).toLocaleString()}`;
+  console.log(`  ${p.dex.padEnd(14)} ${liq.padStart(14)}  ${p.pair}`);
+}
+
+// 3. Structural risk. Read the verdict AND the individual checks -- an overall
+//    UNKNOWN often hides several passes plus one unprovable item, and which item is
+//    unprovable is the decision-relevant part.
+const risk = await scanner.scoreRisk(token);
+console.log(`\nrisk verdict: ${risk.verdict}`);
+for (const c of risk.checks) {
+  console.log(`  ${c.result.padEnd(8)} ${c.check.padEnd(16)} ${c.detail ?? ""}`);
+}
+
+// 4. The honest close. UNKNOWN is not PASS, and a buy path is not an exit path.
+console.log("");
+if (risk.verdict === RISK.FAIL) {
+  console.log("FAIL: disqualifying finding above. Do not trade.");
+} else if (risk.verdict === RISK.UNKNOWN) {
+  console.log(
+    "UNKNOWN is not PASS. Structural checks looked fine, but sellability is\n" +
+      "unproven without a verified router on this chain. Until a round-trip sell\n" +
+      "simulation succeeds, treat this token as not exitable.",
+  );
+} else {
+  console.log(`${risk.verdict}: structural checks only -- still not a recommendation.`);
+}