@oracle-agent/oracle 0.10.0 → 0.12.0

package/docs/adding-a-chain.md

@@ -1,229 +0,0 @@
-# Adding a chain
-
-Oracle treats a chain as **configuration**. You do not write an integration.
-
-## The short version
-
-```js
-import { registerCustomChain } from "@oracle-agent/oracle/scanner";
-
-registerCustomChain({
-  key: "mychain",
-  chainId: 7777,
-  name: "My Chain",
-  rpcEnv: ["MYCHAIN_RPC_URL"],
-  nativeCurrency: { symbol: "MYC", decimals: 18 },
-});
-```
-
-That chain now has block reads, native and ERC-20 balances, on-chain token
-resolution, log scanning, and structural risk checks. No code was written.
-
-```bash
-export MYCHAIN_RPC_URL=https://rpc.mychain.example
-oracle-scan head mychain
-```
-
-## Config fields
-
-| Field | Required | Notes |
-|---|---|---|
-| `key` | yes | lowercase slug, used on the CLI |
-| `chainId` | yes | positive integer |
-| `name` | yes | display name |
-| `rpcEnv` | yes | env var names, `UPPER_SNAKE`. Never a literal URL |
-| `nativeCurrency` | no | `{ symbol, decimals }` |
-| `explorer` | no | base URL |
-| `dexscreenerSlug` | no | enables pool discovery — see below |
-| `venues` | no | verified routers/quoters — required for routing value |
-
-**RPC URLs live in the environment, never in config.** A repo carrying an endpoint
-is both a leak and a rate-limit problem for whoever else uses that key.
-
-## Why `dexscreenerSlug` matters
-
-Pool discovery goes through market data rather than walking a factory. A factory
-walk finds pools that *exist*; a trader needs pools with *liquidity*.
-
-The slug is DexScreener's own chain identifier — not the chain id, and not always
-the obvious name. If you don't know it, **leave it out**. Pool discovery then
-reports `UNAVAILABLE`, which is honest. A wrong slug silently returns another
-chain's pools, which is worse than no answer.
-
-## Adding venues (routing value)
-
-A chain with no verified venue is **fail-closed**: read and research work, routing
-value does not. That is a safe default, not a gap.
-
-To enable routing you must record *provenance*:
-
-```js
-venues: [
-  {
-    kind: "router",
-    address: "0x...",
-    verified: {
-      method: "eth_getCode + protocol /chains API",
-      source: "https://li.quest/v1/chains",
-      date: "2026-07-30",
-    },
-  },
-]
-```
-
-Validation **refuses** a venue without `verified`. This is not bureaucracy: the
-destination allowlist is the highest-leverage control in the system, and
-allowlisting a spoofed router makes every other guard irrelevant.
-
-### How to actually verify
-
-1. **Bytecode exists** — `eth_getCode` must return real code. `0x` means nothing is
-   deployed at that address on that chain.
-2. **The protocol's own API or docs** names that address, for that chain, today.
-   Query the source (e.g. LI.FI's `/v1/chains` returns each chain's official
-   `diamondAddress`) rather than trusting a blog post or a model's recollection.
-3. **Constructor-bound addresses match** — read `factory()`, `WETH9()` back off the
-   deployed contract and confirm they're what you expect.
-4. **Per chain, separately.** An address verified on Arbitrum is not verified on
-   Ethereum, even when the canonical deployment shares an address across chains.
-
-Record how and when. The audit trail has to outlive your session.
-
-## Capabilities
-
-Ten capabilities exist. The generic EVM scanner provides seven out of the box:
-
-| Capability | Generic? | Why |
-|---|---|---|
-| `blockNumber` | yes | standard RPC |
-| `nativeBalance` | yes | standard RPC |
-| `tokenBalance` | yes | ERC-20 is ERC-20 |
-| `resolveToken` | yes | reads metadata off the contract |
-| `resolvePools` | yes* | needs `dexscreenerSlug` |
-| `scanBlocks` | yes | chunked `eth_getLogs` |
-| `scoreRisk` | yes | structural checks |
-| `quote` | venue | needs a verified router |
-| `sellSimulation` | venue | needs a verified router |
-| `prepareUnsignedTx` | venue | needs a verified router |
-
-Calling an unimplemented capability **throws**, naming what is supported. It never
-returns `undefined` that a caller could mistake for "no result."
-
-## Enabling quote / sell / prepare
-
-Add a verified router plus two fields:
-
-```js
-{
-  key: "base",
-  chainId: 8453,
-  // ...
-  venueKind: "uniswap-v2",
-  wrappedNative: "0x4200000000000000000000000000000000000006",
-  venues: [{ kind: "router", address: "0x...", verified: { /* ... */ } }],
-}
-```
-
-`src/scanner/chains.config.mjs` ships **Base** wired this way as the reference. It
-gets all 10 capabilities; every other built-in stays at 7 and fail-closed until
-someone verifies a venue for it.
-
-What you get:
-
-- **`quote`** — live exact-input pricing via `getAmountsOut`
-- **`sellSimulation`** — a state-free round trip (buy then sell back) that catches
-  the honeypot signature: buy leg quotes fine, sell leg fails. This is the single
-  most valuable check on a low-cap venue, because most losses are not bad entries
-  but tokens that cannot be exited
-- **`prepareUnsignedTx`** — an **unsigned** swap with a `minOut` computed from the
-  live quote, a deadline, and an explicit `approve` step listed separately so
-  "approved" and "swapped" are never collapsed into one claim
-
-`scoreRisk` also upgrades automatically: with a router it reports real sellability
-instead of `UNKNOWN`.
-
-### The slippage ceiling is hard
-
-A supplied `slippageBps` is a **maximum**, capped at 100 bps. Above that,
-`prepareUnsignedTx` throws rather than widening:
-
-```
-slippageBps 250 exceeds the 100 bps ceiling. Block and requote or split
-the order -- do not widen the guard to force a fill.
-```
-
-A cap that yields under pressure is decoration.
-
-### V3 / V4 / custom quoters
-
-Two adapters ship:
-
-| `venueKind` | Requires | Prices via |
-|---|---|---|
-| `uniswap-v2` | `router` | `getAmountsOut` on the router |
-| `uniswap-v3` | `quoter` **and** `router` | `quoteExactInputSingle` on QuoterV2 |
-
-V3 is **not** V2 with different addresses: it has no `getAmountsOut`, prices through
-a separate Quoter contract, and needs an explicit fee tier per hop. Encoding a V3
-swap with V2 assumptions yields a transaction that reverts, or worse routes through
-the wrong pool. That is why they are sibling adapters.
-
-The V3 adapter searches all four fee tiers (100 / 500 / 3000 / 10000) and keeps the
-best. This is necessary, not a nicety — liquidity concentrates in one tier and which
-tier varies by pair and chain. On Arbitrum WETH→USDC the 500 tier returns ~2.4% more
-than the 100 tier; defaulting to 0.3% because it is the common choice silently
-misprices stable and exotic pairs alike.
-
-A V3 chain needs **both** a quoter and a router. A router alone stays fail-closed:
-it could encode a swap, but with no priced expectation to guard against — exactly
-the state that produces an unbounded fill.
-
-**V4 and custom-quoter venues still need their own adapter.** Some forks require an
-off-chain signed quote you cannot produce locally. Write a sibling module rather
-than bending an existing one; silently mis-encoding a swap is far worse than
-declaring the capability unsupported.
-
-### Verifying a venue: run the prober
-
-`scripts/verify-v3-venues.mjs` probes candidate addresses on every chain and prints
-a pass/fail with the live price it got:
-
-```bash
-node scripts/verify-v3-venues.mjs
-```
-
-**Codesize is not verification.** The canonical mainnet QuoterV2 address returns
-2109 bytes of bytecode on Base — it is *some* contract, just not a working quoter
-for that chain. A codesize check waves it through; the functional probe caught it
-and pointed at Base's real quoter (8273 bytes, prices WETH→USDC correctly).
-
-The rule: **a contract that correctly prices a pair you can sanity-check IS the
-thing you think it is.** Anything less is a guess with an address attached.
-
-## Honest evidence
-
-Every finding carries a label. Respect the distinction:
-
-- `LIVE` — read this call
-- `CACHED` — recent, within stated TTL
-- `STALE` — older than TTL; usable only with the caveat stated
-- `UNKNOWN` — we tried and could not determine it
-- `UNAVAILABLE` — this chain/provider cannot answer at all
-
-`UNKNOWN` and `UNAVAILABLE` are different facts. Collapsing them is how people end
-up sizing against stale reserves.
-
-Risk verdicts are coarse on purpose — `PASS` / `CAUTION` / `FAIL` / `UNKNOWN`. A
-score like "risk 62/100" invites trading a number nobody understands.
-
-**`UNKNOWN` is not `PASS`.** The generic scanner returns `UNKNOWN` for sellability
-because it cannot prove exitability without a verified router. A token is not
-tradeable until a round-trip sell simulation succeeds.
-
-## Contributing a chain upstream
-
-Append to `CHAIN_CONFIGS` in `src/scanner/chains.config.mjs` and open a PR. Tests
-already assert every built-in config validates and that none embeds an RPC URL, so
-CI will catch a malformed entry.
-
-If you add venues, put the verification method and date in the PR body.

package/docs/architecture.md

@@ -1,136 +0,0 @@
-# Architecture
-
-Three planes. The boundary between them is enforced by a test, not a convention.
-
-```
-                    user's wallet
-                         ^
-                         | signs (only the user can)
-                         |
-   +---------------------+---------------------+
-   |            unsigned artifacts             |
-   |                                           |
-   |  PUBLIC (this repo)                       |
-   |                                           |
-   |  data plane      read / quote             |
-   |  policy plane    allowlists, guards,      |
-   |                  attestations, grants     |
-   |  control plane   grant lifecycle,         |
-   |                  session keys, AA, router |
-   +-------------------------------------------+
-                         |
-                         x  no import may cross
-                         |
-   +-------------------------------------------+
-   |  OWNER-LOCAL (companion package)          |
-   |  @oracle-agent/operator                   |
-   |  key-vault / hl-exec / oracle-vault       |
-   +-------------------------------------------+
-```
-
-## Why three planes
-
-The design assumption is that **the model can be wrong or adversarially steered**.
-Everything follows from treating it as an untrusted proposer.
-
-If the model is untrusted, then authorization cannot come from the model. It comes
-from an owner signature over a bounded grant. And if authorization is separate from
-proposal, then the code that proposes must be unable to reach the code that signs —
-otherwise the separation is aspirational.
-
-That is why the boundary is a test (`test/custody-boundary.test.mjs`) rather than a
-paragraph in a README. It walks the import graph from every shipped entrypoint and
-fails on:
-
-- any public module importing signer or key material
-- a dangling local import that reaches a signer from a shipped entrypoint
-- a secret-shaped literal anywhere
-- a packed npm artifact that still contains signer/vault modules
-
-## Data plane
-
-`src/data/` — 30+ providers, each declaring an honest tier.
-
-| Tier | Meaning |
-|---|---|
-| `read-only` | data only; no execution claim |
-| `quote-only` | can price a route; no reviewed transaction builder |
-| `prepare` | returns a policy-bound unsigned transaction |
-| `intent` | returns typed data to sign (CoW orders, GMX orders) |
-
-The tier is load-bearing. "We support protocol X" is ambiguous and has caused real
-confusion; the tier is not. **API coverage ≠ execution support.**
-
-`src/data/catalog.mjs` is the registry; `dataHealth()` probes liveness. Note the
-distinction in health output: a promise that resolved with `{ok: false}` is
-*degraded*, not healthy — and an HTTP 200 serving an explorer error page is not a
-successful read.
-
-## Policy plane
-
-The moat. Holds no keys; constrains what a signer may be asked to do.
-
-- **Destination allowlist** (`src/venues.mjs`) — per chain, fail-closed. An empty
-  allowlist refuses everything. It never means "allow anything."
-- **Auto-slippage** (`src/auto-slippage.mjs`) — a guard computed from live depth and
-  volatility per leg, recomputed before each broadcast. A caller-supplied tolerance
-  is a *maximum*, not the selected value. Hard ceiling 100 bps; over that, block and
-  requote rather than widen.
-- **Attestations** (`route-`, `vault-`, `gmx-attestation.mjs`) — dynamic execution
-  targets require an attestation minted inside the trusted boundary. Model-authored
-  JSON is not authorization.
-- **Approval guard** — exact-amount approvals, never unlimited by default, with
-  allowance read back after the approve lands.
-
-Guards are re-checked at **sign and broadcast** time. A stale minimum is not a
-minimum.
-
-## Control plane
-
-`src/public-control/` — grant schema and rendering, session-key model, ERC-4337
-adapter, bundler client, grant indexer.
-
-`src/router/` — model routing with a custody firewall. `risk-classifier.mjs` scores
-an action's risk; `proposal.mjs` refuses to construct a proposal containing
-dangerous fields (private keys, mnemonics, bearer tokens) at any nesting depth. The
-router can propose, simulate, explain, and draft. It cannot authorize.
-
-## Scanner framework
-
-`src/scanner/` — makes a chain data rather than an integration.
-
-- `contract.mjs` — 10 capabilities, a validator, a registry, coverage matrix
-- `evm-scanner.mjs` — one generic implementation for any EVM JSON-RPC chain
-- `chains.config.mjs` — the 11 built-ins as config, plus `registerCustomChain()`
-
-Unimplemented capabilities are **absent, not faked**: calling one throws a message
-naming what *is* supported. A caller can never mistake `undefined` for a negative
-result.
-
-Evidence labels (`LIVE` / `CACHED` / `STALE` / `UNKNOWN` / `UNAVAILABLE`) and risk
-verdicts (`PASS` / `CAUTION` / `FAIL` / `UNKNOWN`) exist to stop the collapse that
-causes losses: **`UNKNOWN` is not `PASS`**, and "we could not check" is a different
-fact from "there is nothing there."
-
-## Agent mesh
-
-`profiles/` + `skills/` — seven installable Hermes lanes plus a template.
-
-A lane is narrow on purpose: smaller context is cheaper and more accurate, per-lane
-memory doesn't cross-contaminate, and a grant scoped to one lane can't be spent by
-another.
-
-Every lane ships DISARMED, and every grant action a lane may request is read,
-simulate, or prepare. No lane may request broadcast or signing — enforced in
-`test/profiles.test.mjs`, so widening custody cannot pass review quietly.
-
-No lane pins a model. `profile.json` carries a capability *class*
-(`strong-reasoner`, `fast-tool-caller`), so the installer never writes a vendor into
-a user's config.
-
-## What is not in the public package
-
-House custody, an always-on exec server, and capability minting are not shipped.
-Owner-local signer modules (`key-vault`, `hl-exec`, `oracle-vault`) live in the
-companion package `@oracle-agent/operator` on the user's machine. This prepare
-package has nothing to steal: it never takes a key and never broadcasts.

package/docs/cli.md

@@ -1,47 +0,0 @@
-# Oracle unified CLI
-
-Root command: `oracle <noun> <verb> [args]`.
-
-The public `@oracle-agent/oracle` package is **prepare-only**. Signing commands
-dispatch to a separately installed `@oracle-agent/operator` process on the same
-machine. Oracle never imports operator signing modules.
-
-See also [connectors.md](./connectors.md).
-
-## Exit codes
-
-| Code | Meaning |
-|---|---|
-| 0 | ok |
-| 1 | usage / general error |
-| 2 | operator self-reported error |
-| 3 | operator package not installed |
-| 4 | data server not running |
-
-## Chat surface
-
-```bash
-oracle                      # TTY: premium boxed oracle chat
-oracle --help               # command help
-oracle model                # interactive provider/model picker
-oracle -m <model>           # launch this session on a selected model
-oracle chain list           # working chains
-oracle chain use hyperliquid
-oracle setup                # telegram/discord/slack messaging menu
-oracle setup telegram       # writes TELEGRAM_BOT_TOKEN into profile .env
-oracle setup messaging      # full hermes gateway setup wizard
-```
-
-Inside chat:
-
-- `/chain` list or select build/trade chain
-- `/setup` configure messaging platforms
-- `/model` switch models; persona stays oracle
-
-Terminal and configured messaging channels are transports into the same Hermes
-profile. A configured local operator/MCP can execute an owner-confirmed action
-from either interface. The interface and selected model never bypass grants,
-allowlists, caps, MAC checks, simulation, or receipt verification.
-
-Hosted remote models stay read/prepare-only. Local hermes + operator remain the
-only signing path, and only via child process.

package/docs/connectors.md

@@ -1,13 +0,0 @@
-# Oracle AI-client connectors
-
-ChatGPT is hosted and can NEVER sign or reach your keys. This connector is read/prepare only; anything it prepares is unsigned until you sign it locally.
-
-```bash
-oracle mcp print --target claude-code
-oracle mcp install claude-code
-oracle mcp install codex
-oracle mcp install chatgpt
-oracle mcp install claude-code --with-control   # requires local operator
-```
-
-Oracle does not create tunnels for hosted clients.

package/docs/oracle-pack-standard.md

@@ -1,29 +0,0 @@
-# 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

@@ -1,154 +0,0 @@
-# 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 node \
-  --args "$(node -p "require.resolve('@oracle-agent/oracle/package.json').replace(/package\\.json$/, 'bin/oracle-data-mcp.mjs')")"
-# or after npm link / PATH has the bin:
-# hermes -p polymarket-agent mcp add oracle-data --command oracle-data-mcp
-```
-
-Now that lane can read 30+ providers across 11 chains, 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/examples/add-a-chain.mjs

@@ -1,65 +0,0 @@
-// 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}`);