@oracle-agent/oracle 0.14.1 → 0.16.0

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

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

@@ -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,151 +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 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

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

@@ -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}`);

package/examples/oracle-pack-template.mjs

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

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