@oracle-agent/oracle 0.9.8 → 0.11.0

package/README.md

@@ -20,11 +20,12 @@ Specialist agent profiles, real protocol intents, self-custody by default,
 receipts or it didn't happen.
 
 Built for [Hermes](https://github.com/NousResearch/hermes-agent), the
-open-source agent runtime from [Nous Research](https://nousresearch.com).
+open-source agent runtime from [Nous Research](https://nousresearch.com), but
+Hermes is optional.
 
-Oracle itself makes **no model calls and needs no API key**. On first chat it
-installs an isolated local agent runtime and opens its model/provider picker.
-An existing compatible runtime is reused when available.
+Oracle can run standalone model auth directly with API keys or Claude, Codex,
+and Grok OAuth. OAuth credentials use the OS keychain when available, with a
+private `0600` local fallback when keychain storage is unavailable.
 
 This package is **prepare-only**: it never takes a private key and never
 broadcasts. For agentic trading with **your** keys on **your** machine, install
@@ -35,9 +36,7 @@ alongside it — same split we run ourselves.
 
 ## Start in 5 steps
 
-Source tree: **oracle `0.5.0`** · **operator `0.14.0`**
-
-Published npm: **oracle `0.4.2`** · **operator `0.13.7`** until this source release is published.
+Source tree: **oracle `0.11.0`** · **operator `0.7.0`**
 
 ```bash
 # 1) install Oracle's public prepare plane
@@ -212,18 +211,24 @@ known answer. This matters: the canonical QuoterV2 address also has bytecode on
 Base, but does not price that chain's pairs. A codesize check would have
 allowlisted the wrong contract.
 
-**30+ providers** in the read/quote catalog:
+**42 provider modules** in the read/quote catalog, covering **219 unique
+protocols/venues** across EVM, Solana, and Bitcoin (115 EVM + cross-chain, 98
+Solana venues backed by 101 verified Jupiter program IDs, 6 Bitcoin surfaces).
+One module can cover many protocols: the Jupiter module alone routes 98 Solana
+venues, so provider-module count and protocol count are different numbers.
 
 | Class | Providers |
 |---|---|
 | Chain / explorer | EVM JSON-RPC, Blockscout, Solana RPC, Bitcoin Esplora |
 | Market data | DexScreener, GeckoTerminal, DeFiLlama |
-| DEX / aggregator | Uniswap V3, Aerodrome, Curve, Balancer, LI.FI, ParaSwap, Odos, 0x, 1inch |
-| Intents | CoW Protocol |
+| DEX / aggregator | Uniswap V3/V4, Aerodrome, Curve, Balancer, LI.FI, ParaSwap, Odos, 0x, 1inch, HyperEVM DEXes |
+| Solana | Jupiter (98 venue labels, 101 verified program IDs) |
+| Intents | CoW Protocol, RFQ |
 | Perps / lending / yield | GMX v2, Morpho, Pendle |
 | Bridges | Across, Hop, Relay |
 | Venues | Hyperliquid (core perps + HIP-3 builder dexs + HIP-4 outcomes), Polymarket (read + local CLOB prepare) |
 | NFT | OpenSea, Satflow, Magic Eden (Solana) |
+| Bitcoin | mempool/Esplora, Ordinals, Runes, UniSat, Best-in-Slot, Satflow |
 
 Every provider and every scanner capability declares an honest tier —
 `read-only`, `quote-only`, `prepare`, or `intent`. **API coverage is not execution

package/bin/oracle-data-mcp.mjs

@@ -345,6 +345,14 @@ const tools = [
       properties: { transaction: { type: "string" }, sigVerify: { type: "boolean" }, replaceRecentBlockhash: { type: "boolean" } },
     },
   },
+  {
+    name: "jupiter_venues",
+    description: "Jupiter Solana venue map, optionally verified on-chain against executable BPF loader ownership. Read-only.",
+    inputSchema: {
+      type: "object",
+      properties: { verify: { type: "boolean" }, rpc: { type: "string" } },
+    },
+  },
   {
     name: "jupiter_quote",
     description: "Jupiter Solana Swap API quote with a hard <=100 bps slippage cap. Read-only.",
@@ -768,6 +776,7 @@ const ROUTES = {
   solana_balance: (a) => ({ provider: "solana-rpc", op: "getBalance", args: { address: a.address, commitment: a.commitment } }),
   solana_token_accounts: (a) => ({ provider: "solana-rpc", op: "tokenAccounts", args: { owner: a.owner, mint: a.mint, commitment: a.commitment } }),
   solana_simulate: (a) => ({ provider: "solana-rpc", op: "simulate", args: { transaction: a.transaction, sigVerify: a.sigVerify, replaceRecentBlockhash: a.replaceRecentBlockhash } }),
+  jupiter_venues: (a) => ({ provider: "jupiter", op: "venues", args: { verify: a.verify, rpc: a.rpc } }),
   jupiter_quote: (a) => ({ provider: "jupiter", op: "quote", args: { inputMint: a.inputMint, outputMint: a.outputMint, amount: a.amount, slippageBps: a.slippageBps } }),
   jupiter_prepare: (a) => ({ provider: "jupiter", op: "prepare", args: { userPublicKey: a.userPublicKey, quoteResponse: a.quoteResponse, inputMint: a.inputMint, outputMint: a.outputMint, amount: a.amount, slippageBps: a.slippageBps } }),
   btc_health: () => ({ provider: "bitcoin-esplora", op: "health", args: {} }),

package/docs/architecture.md

@@ -49,7 +49,9 @@ fails on:
 
 ## Data plane
 
-`src/data/` — 30+ providers, each declaring an honest tier.
+`src/data/` — 42 provider modules covering 219 unique protocols/venues, each
+declaring an honest tier. One module can cover many protocols: the Jupiter
+module alone routes 98 Solana venues.
 
 | Tier | Meaning |
 |---|---|

package/docs/profiles.md

@@ -122,14 +122,11 @@ args as separate tokens):
 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
+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
+Now that lane can read 42 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

package/docs/public-surface.md

@@ -0,0 +1,133 @@
+# 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` | transaction policy: caps, allowlists, `enforceTxPolicy` |
+| `@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/action-semantics` | decoded-action semantics for review |
+| `@oracle-agent/oracle/address-book` | label store — refuses key material |
+| `@oracle-agent/oracle/nft-gas-war` | NFT mint/gas-war helpers |
+| `@oracle-agent/oracle/prepare-envelope` | `stampPrepared` / `assertPreparedEnvelope` |
+| `@oracle-agent/oracle/connect` | wallet-connect request/assemble surface |
+| `@oracle-agent/oracle/receipts` | action receipts — refuses secret-bearing fields |
+| `@oracle-agent/oracle/risk` | risk scoring helpers |
+| `@oracle-agent/oracle/watch` | watch/alert subscriptions |
+| `@oracle-agent/oracle/signals` | signal feed helpers |
+
+`./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 |
+
+## 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_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 |
+
+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 |
+
+### 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/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@oracle-agent/oracle",
-  "version": "0.9.8",
-  "description": "Oracle: prepare-only multichain agent control plane. Policy-bounded intents for a user-signed wallet. Self-custody by default — the public package never takes your key. Built for Hermes; no model key required.",
+  "version": "0.11.0",
+  "description": "Oracle: standalone prepare-only multichain agent control plane with optional Hermes integration. Policy-bounded intents for a user-signed wallet; the public package never takes your key.",
   "license": "Apache-2.0",
   "type": "module",
   "publishConfig": {
@@ -85,6 +85,7 @@
   "files": [
     "bin/",
     "src/",
+    "!src/**/__pycache__/**",
     "profiles/",
     "skills/",
     "skins/",