@oracle-agent/oracle 0.3.1 → 0.3.3

package/README.md

@@ -18,18 +18,43 @@ alongside it — same split we run ourselves.
 
 ---
 
-## Install
+## Start in 5 steps
+
+Latest: **oracle `0.3.1`** · **operator `0.6.1`**
 
 ```bash
-# prepare-only (safe default)
-npm i @oracle-agent/oracle
+# 1) install both packages
+npm i @oracle-agent/oracle@0.3.1 @oracle-agent/operator@0.6.1
+
+# 2) put keys ONLY on your machine (example: HL/EVM hex key file)
+mkdir -p ~/.config/oracle/keys && chmod 700 ~/.config/oracle/keys
+# write key, then: npx oracle-vault encrypt ~/.config/oracle/keys/evm.key
+export HL_KEY_FILE=~/.config/oracle/keys/evm.key.vault.json
+export ORACLE_VAULT_PASSPHRASE='...'   # signer shell only — never in the agent chat
+```
+
+```js
+// 3) prepare (no keys)
+import { data } from "@oracle-agent/oracle";
+const prepared = await data.call("hl-perps", "prepareOrder", { /* coin, side, size... */ });
+
+// 4) keys local → operator signs (this is the sign step — no MetaMask)
+import { hlSignAndSubmit } from "@oracle-agent/operator";
+await hlSignAndSubmit(prepared, {
+  keyFile: process.env.HL_KEY_FILE,
+  userInitiated: true, // app confirmed the action; or use autonomous/daemon below
+});
+```
 
-# full self-host lane (keys stay on YOUR machine) — same model we run
-npm i @oracle-agent/oracle @oracle-agent/operator
+```bash
+# 5) unattended desk (no click each trade) — HL/Poly capped
+export ORACLE_AUTONOMOUS_TRADING=1
+# or: npx oracle-signer
 ```
 
-See the operator [SETUP](https://github.com/demi-hl/oracle-operator/blob/main/SETUP.md)
-for local key vault + Hyperliquid sign-and-submit.
+Full vault / multi-chain / daemon detail → operator [SETUP](https://github.com/demi-hl/oracle-operator/blob/main/SETUP.md).
+
+---
 
 ## What Oracle is
 
@@ -174,10 +199,14 @@ Oracle's default pack is deliberately broad but disarmed:
 
 - **Trader** — best-execution route comparison, quote/prepare, simulation, and
   receipt checks; no set-and-forget custody.
-- **Builder** — protocol, NFT, gacha, DEX, and launchpad scaffolds with unsigned
-  deploy/admin transactions.
+- **Builder** - chain-family fungible-token and NFT-collection launch plans,
+  protocol, gacha, DEX, and launchpad scaffolds with unsigned deploy/admin actions.
+  Unsupported chain adapters fail closed instead of pretending one deploy fits all.
 - **Analyzer** — token, contract, venue, portfolio, market, and risk research with
-  evidence labels.
+  evidence labels. `/balance` or plain `balance` runs one deterministic snapshot
+  across every configured EVM chain plus Solana, Bitcoin, Hyperliquid, and
+  discoverable NFTs. Profile-local observations power history and SVG value graphs;
+  unavailable values stay null instead of becoming fake zeroes.
 - **On-chain scanner** — chain-config scanners for tokens, pools, launches,
   risk, exits, and smart-wallet boards.
 - **Meme-token sniper** — fast launch/liquidity monitoring across configured
@@ -248,7 +277,8 @@ Oracle is a library. Drive it with Claude, GPT, Gemini, Grok, a local model, or
 a plain script — the tools are ordinary functions plus an MCP server:
 
 ```bash
-npx oracle-data-mcp     # works with any MCP client
+npx oracle-data         # local read plane on 127.0.0.1:8787
+npx oracle-data-mcp     # MCP stdio server (any MCP client); needs oracle-data up
 ```
 
 It is better under [Hermes](https://claude-code.nousresearch.com/docs), because
@@ -269,7 +299,9 @@ Oracle ships an installable 8-lane mesh for Hermes:
 
 ```bash
 oracle-init            # dry run -- shows exactly what it would do
-oracle-init --apply    # create profiles, install SOULs + skills, wire MCP
+oracle-init --apply    # create profiles, install SOULs + skills, wire MCP config
+npx oracle-data        # keep running — MCP tools call the local read plane on :8787
+hermes -p oracle chat  # router lane; inherits whatever model Hermes already uses
 ```
 
 Lanes: `oracle` (router), `polymarket-agent`, `hyperliquid-agent`,

package/SETUP.md

@@ -103,6 +103,39 @@ export BASE_RPC_URL=https://...
 export SOLANA_RPC_URL=https://...
 ```
 
+`/balance` and plain `balance` need only public addresses. Set any families the
+wallet uses, then start `oracle-data` from the same environment:
+
+```bash
+export ORACLE_EVM_ADDRESS=0x...
+export ORACLE_SOLANA_ADDRESS=...
+export ORACLE_BITCOIN_ADDRESS=bc1...
+export ORACLE_HYPERLIQUID_ADDRESS=0x...  # optional, defaults to EVM address
+npx oracle-data
+```
+
+Missing address families are reported as `not-configured`, failed providers as
+`unavailable`, and unsupported chain families as `unsupported`. They are never
+reported as zero. EVM native balances cover every configured EVM chain. Solana
+adds SPL and Token-2022 accounts, Bitcoin adds Runes and inscriptions when an
+address indexer is configured, Hyperliquid adds spot and perp account state, and
+NFT inventory adds OpenSea-supported EVM/Solana collections plus Bitcoin
+inscriptions where owner indexers are available.
+
+Every `portfolio_snapshot` call appends one compact observation to
+`$HERMES_HOME/state/oracle/portfolio-history.jsonl` with mode `0600`. It stores a
+public-address fingerprint, coverage, value breakdown, and warnings, not keys,
+prepared transactions, or raw NFT metadata. Override the internal location only
+when needed:
+
+```bash
+export ORACLE_PORTFOLIO_HISTORY_FILE="$HOME/.local/state/oracle/portfolio-history.jsonl"
+```
+
+`portfolio_history` reads those observations. `portfolio_value_graph` returns an
+SVG chart of known priced value and omits unavailable observations instead of
+plotting them as zero.
+
 ---
 
 ## Where keys are stored
@@ -202,7 +235,8 @@ Gemini, Grok, a local Llama, or your own script at it. The tools are plain
 functions and an MCP server.
 
 ```bash
-npx oracle-data-mcp     # MCP stdio server, works with any MCP client
+npx oracle-data         # local read plane on 127.0.0.1:8787
+npx oracle-data-mcp     # MCP stdio server, works with any MCP client (needs oracle-data up)
 ```
 
 **Why [Hermes](https://claude-code.nousresearch.com/docs) is the better host: per-profile routing.**
@@ -293,3 +327,17 @@ npm run protocol:gate -- safe-erc20
 
 `prepareTemplateDeploy` will not stamp an unsigned deploy unless `forge test` passes.
 **Not a paid security-firm audit** — see each template `SECURITY.md`.
+
+
+## Optional keyed prepare stamps (hardening)
+
+Integrity hash is always on. For a shared HMAC between prepare process and signer:
+
+```bash
+# same secret on prepare host and signer host (not in the agent chat)
+export ORACLE_STAMP_HMAC_SECRET='long-random-secret'
+# signer-only: refuse envelopes without MAC
+export ORACLE_STAMP_REQUIRE_MAC=1
+```
+
+Default remains hash-only (public GO path). HMAC is opt-in hardening.

package/artifacts/specialist-packs/oracle-full-crypto.json

@@ -1,9 +1,9 @@
 {
   "id": "oracle-full-crypto",
   "name": "Oracle Full Crypto Pack",
-  "version": 1,
+  "version": 4,
   "audience": "public-users",
-  "description": "Default capability set for public Oracle: trader, builder, analyzer, multichain scanner, meme-token sniping, RFQ routing, tokenized-asset buys, NFT mint gas-war limits, Solana, Bitcoin inscriptions, NFT/gacha/DEX launches, and protocol build under bound grants. User signs everything.",
+  "description": "Default capability set for public Oracle: trader, builder, analyzer, deterministic /balance aggregation, multichain scanner, meme-token sniping, RFQ routing, tokenized-asset buys, NFT mint gas-war limits, Solana, Bitcoin inscriptions, chain-family token/NFT collections, gacha/DEX launches, and protocol build under bound grants. User signs everything.",
   "posture": {
     "default": "DISARMED",
     "custody": "self-custodial",
@@ -62,6 +62,8 @@
       "oracle-protocol-builder",
       "oracle-contract-research",
       "oracle-protocol-security",
+      "oracle-multichain-token-launch",
+      "oracle-multichain-nft-launch",
       "oracle-nft-gacha-launch",
       "oracle-dex-launch",
       "protocol-api-key-integration",
@@ -80,6 +82,8 @@
       "oracle-nft-gacha-launch",
       "oracle-dex-launch",
       "oracle-protocol-security",
+      "oracle-multichain-token-launch",
+      "oracle-multichain-nft-launch",
       "oracle-nft-mint-gas-war"
     ],
     "analysis": [
@@ -88,6 +92,7 @@
       "oracle-smart-wallet-scanner",
       "oracle-meme-token-sniper",
       "oracle-best-execution",
+      "balance",
       "oracle-chain-graphs-telegram-cards",
       "oracle-rfq-tokenized-assets"
     ]
@@ -109,7 +114,9 @@
       "write-deploy-scripts",
       "prepare-unsigned-deploy-txs",
       "security-checklist",
-      "launchpad-public-surface"
+      "launchpad-public-surface",
+      "multichain-token-launch",
+      "multichain-nft-collection-launch"
     ],
     "user_signs": true,
     "grant_actions_example": [
@@ -119,7 +126,7 @@
       "prepare:verify"
     ],
     "targets": "user-provided factory/router/implementations only unless added to destination allowlist",
-    "copy": "Oracle can design and prepare protocol, NFT/gacha, and DEX launches. You still sign. Grants bind chain, spend, and destinations."
+    "copy": "Oracle can classify and prepare chain-family token, NFT collection, protocol, gacha, and DEX launches. Unsupported adapters fail closed. You still sign every side effect."
   },
   "profiles": [
     {
@@ -201,10 +208,12 @@
         "oracle-protocol-security",
         "oracle-nft-gacha-launch",
         "oracle-dex-launch",
-        "oracle-receipts"
+        "oracle-receipts",
+        "oracle-multichain-token-launch",
+        "oracle-multichain-nft-launch"
       ],
       "label": "protocol builder",
-      "description": "Scaffold, review, and prepare deploys for NFT, gacha, DEX, and protocol launches."
+      "description": "Classify by chain family, then scaffold, review, and prepare unsigned token, NFT collection, gacha, DEX, and protocol launches."
     }
   ],
   "default_tools": {
@@ -216,7 +225,14 @@
       "btc_health",
       "btc_fees",
       "btc_inscription_info",
-      "solana_balance"
+      "solana_balance",
+      "portfolio_balance",
+      "portfolio_snapshot",
+      "portfolio_history",
+      "portfolio_value_graph",
+      "nft_inventory",
+      "nft_gallery",
+      "nft_pnl"
     ],
     "prepare": [
       "evm_prepare",
@@ -224,7 +240,8 @@
       "evm_protocol_quote",
       "jupiter_quote",
       "jupiter_prepare",
-      "bitcoin_inscribe_prepare"
+      "bitcoin_inscribe_prepare",
+      "nft_prepare_list"
     ],
     "never_public_default": [
       "evm_sign",
@@ -268,6 +285,11 @@
     "solana-nft-marketplace",
     "solana-nft-mint",
     "hypercore-hype-staking",
-    "hypercore-validator-delegation"
+    "hypercore-validator-delegation",
+    "multichain-token-launch",
+    "multichain-nft-collection-launch",
+    "multichain-balance",
+    "nft-inventory-gallery-pnl",
+    "portfolio-balance-history-graph"
   ]
 }

package/bin/oracle-data-mcp.mjs

@@ -2,14 +2,17 @@
 // Oracle data MCP — read-only multichain market/discovery plane.
 // Loaded by an Oracle/Hermes profile. Never expose signing or broadcast here.
 //
-// Every tool is a READ. No key, no signing, no broadcast. Routes to the Oracle
-// data server read plane (/data/call), which is unauthenticated on loopback.
+// Every tool is a READ or a prepared unsigned action. No key handling, signing,
+// or broadcast. Routes to the Oracle data server read/prepare plane (/data/call),
+// which is unauthenticated on loopback.
 // This is the "scan all public APIs" surface: DeFiLlama protocol TVL, DexScreener
 // token/search, LI.FI + Uniswap quotes, multi-chain RPC balances/blocks.
 //
 // Mirrors the Oracle exec MCP stdio JSON-RPC shape.
 
+import fs from "node:fs";
 import process from "node:process";
+import { fileURLToPath } from "node:url";
 import { env } from "../src/oracle-env.mjs";
 
 const DATA_URL = (env("ORACLE_DATA_URL", "MAD_DESK_URL", "http://127.0.0.1:8787")).replace(/\/$/, "");
@@ -96,6 +99,201 @@ const tools = [
       },
     },
   },
+  {
+    name: "portfolio_balance",
+    description:
+      "Read-only balance aggregation across every configured EVM chain plus Solana, Bitcoin, and Hyperliquid. Reports native assets, supported token/collectible reads, failed or missing providers, unverified assets, timestamps, and known priced value without pretending it is a complete total. Public addresses only; never signs or broadcasts.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        addresses: {
+          type: "object",
+          description: "Optional public wallet addresses by family. Omit configured families to use ORACLE_*_ADDRESS defaults.",
+          properties: {
+            evm: { type: "string" },
+            solana: { type: "string" },
+            bitcoin: { type: "string" },
+            hyperliquid: { type: "string" },
+          },
+        },
+        evmChainIds: {
+          type: "array",
+          items: { type: "number" },
+          description: "Optional EVM chain subset. Default is every configured EVM chain.",
+        },
+        includeTokens: { type: "boolean", description: "Include supported token reads. Default true." },
+        includeCollectibles: { type: "boolean", description: "Include supported collectible reads. Default true." },
+        includePrices: { type: "boolean", description: "Fetch current DeFiLlama native prices. Default true." },
+      },
+    },
+  },
+  {
+    name: "portfolio_snapshot",
+    description:
+      "Query the current multichain balance and NFT inventory, then append one compact profile-local observation for historical tracking. Stores public-address fingerprint, coverage, breakdown, and known priced value only; no keys, signatures, executable payloads, or raw NFT metadata. Returns the live balance, NFT result, and recorded snapshot.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        addresses: {
+          type: "object",
+          properties: {
+            evm: { type: "string" },
+            solana: { type: "string" },
+            bitcoin: { type: "string" },
+            hyperliquid: { type: "string" },
+          },
+        },
+        evmChainIds: { type: "array", items: { type: "number" } },
+        includeTokens: { type: "boolean" },
+        includeCollectibles: { type: "boolean" },
+        includePrices: { type: "boolean" },
+        includeNfts: { type: "boolean", description: "Include provider-estimated NFT value. Default true." },
+      },
+    },
+  },
+  {
+    name: "portfolio_history",
+    description:
+      "Read profile-local portfolio observations in a time range. Unknown or unavailable values remain null and are never converted to zero. Defaults to the configured public-address portfolio fingerprint.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        addresses: {
+          type: "object",
+          properties: {
+            evm: { type: "string" },
+            solana: { type: "string" },
+            bitcoin: { type: "string" },
+            hyperliquid: { type: "string" },
+          },
+        },
+        portfolioId: { type: "string" },
+        allPortfolios: { type: "boolean", description: "Return observations for every public-address fingerprint in this profile." },
+        since: { type: "string", description: "Inclusive ISO 8601 lower bound." },
+        until: { type: "string", description: "Inclusive ISO 8601 upper bound." },
+        limit: { type: "number", description: "1-1000, default 100." },
+        order: { type: "string", enum: ["asc", "desc"] },
+      },
+    },
+  },
+  {
+    name: "portfolio_value_graph",
+    description:
+      "Render a static SVG line graph from profile-local portfolio snapshots. Plots known priced value only, labels incomplete coverage, includes provider-estimated NFT values when recorded, and omits unavailable observations instead of plotting fake zeroes.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        addresses: {
+          type: "object",
+          properties: {
+            evm: { type: "string" },
+            solana: { type: "string" },
+            bitcoin: { type: "string" },
+            hyperliquid: { type: "string" },
+          },
+        },
+        portfolioId: { type: "string" },
+        allPortfolios: { type: "boolean" },
+        since: { type: "string" },
+        until: { type: "string" },
+        limit: { type: "number", description: "Historical observations to consider, max 1000." },
+        maxPoints: { type: "number", description: "Rendered point cap, 2-500, default 200." },
+      },
+    },
+  },
+  {
+    name: "nft_inventory",
+    description:
+      "Read all discoverable NFTs for configured EVM, Solana, and Bitcoin addresses. Returns normalized assets, image URLs, estimated values, per-chain partial failures, flagged/NSFW items separated from visible items, listing coverage, and explicit unsupported chains. Read-only.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        addresses: {
+          type: "object",
+          properties: {
+            evm: { type: "string" },
+            solana: { type: "string" },
+            bitcoin: { type: "string" },
+          },
+        },
+        chains: { type: "array", items: { type: "string" }, description: "Optional chain slug subset." },
+        pageSize: { type: "number", description: "OpenSea items per page, max 200." },
+        maxPages: { type: "number", description: "Maximum pages per chain, max 25." },
+        bitcoinLimit: { type: "number" },
+        includePnl: { type: "boolean", description: "Include OpenSea-indexed account PnL when available. Default true." },
+        costBasis: { type: "object", description: "Optional user-supplied assetKey -> {costUsd,feesUsd,acquiredAt,source}. Missing basis stays unavailable, never zero." },
+      },
+    },
+  },
+  {
+    name: "nft_gallery",
+    description:
+      "Generate one static NFT contact-sheet image page from wallet inventory or supplied normalized items. External metadata is never rendered as HTML; only allowlisted JPEG/PNG/WebP bytes are embedded and unsafe or missing media becomes a placeholder.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        addresses: {
+          type: "object",
+          properties: { evm: { type: "string" }, solana: { type: "string" }, bitcoin: { type: "string" } },
+        },
+        chains: { type: "array", items: { type: "string" } },
+        items: { type: "array", items: { type: "object" }, description: "Optional normalized inventory items. Omit to scan configured wallets." },
+        page: { type: "number", description: "1-based gallery page." },
+        pageSize: { type: "number", description: "1-12 items per page." },
+      },
+    },
+  },
+  {
+    name: "nft_pnl",
+    description:
+      "NFT PnL with explicit methodology. Returns OpenSea-indexed account-level PnL where available plus per-item unrealized estimates only when both user-supplied acquisition cost and provider estimated current value exist. Missing history is unavailable, never zero.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        addresses: {
+          type: "object",
+          properties: { evm: { type: "string" }, solana: { type: "string" }, bitcoin: { type: "string" } },
+        },
+        chains: { type: "array", items: { type: "string" } },
+        costBasis: { type: "object" },
+      },
+    },
+  },
+  {
+    name: "nft_prepare_list",
+    description:
+      "Prepare an NFT listing for OpenSea EVM, Magic Eden Solana, or Satflow Bitcoin after explicit user review. Requires userConfirmed=true plus asset, marketplace, price, currency where applicable, and future expiry. Returns approval/signing actions, an unsigned Solana transaction, or an unsigned Bitcoin PSBT. Never signs, submits, or broadcasts.",
+    inputSchema: {
+      type: "object",
+      required: ["marketplace", "userConfirmed"],
+      properties: {
+        marketplace: { type: "string", enum: ["opensea", "magiceden", "magiceden-sol", "satflow"] },
+        userConfirmed: { type: "boolean" },
+        chain: { type: "string" },
+        seller: { type: "string" },
+        contract: { type: "string" },
+        tokenId: { type: "string" },
+        quantity: { type: "number" },
+        priceAmount: { type: "string" },
+        currency: { type: "string" },
+        endTime: { type: "string" },
+        useCreatorFee: { type: "boolean" },
+        taker: { type: "string" },
+        tokenMint: { type: "string" },
+        tokenATA: { type: "string" },
+        auctionHouse: { type: "string" },
+        priceSol: { type: "string" },
+        expiry: { description: "Future ISO 8601 timestamp or Unix seconds." },
+        inscriptionId: { type: "string" },
+        runesOutput: { type: "string" },
+        ordAddress: { type: "string" },
+        receiveAddress: { type: "string" },
+        priceSats: { type: "string" },
+        tapKey: { type: "string" },
+        collectionSlug: { type: "string" },
+      },
+    },
+  },
   {
     name: "rpc_balance",
     description:
@@ -427,6 +625,24 @@ const ROUTES = {
       fromAddress: a.fromAddress || DEFAULT_ADDRESS || undefined,
     },
   }),
+  portfolio_balance: (a) => ({
+    provider: "portfolio",
+    op: "balances",
+    args: {
+      addresses: a.addresses,
+      evmChainIds: a.evmChainIds,
+      includeTokens: a.includeTokens,
+      includeCollectibles: a.includeCollectibles,
+      includePrices: a.includePrices,
+    },
+  }),
+  portfolio_snapshot: (a) => ({ provider: "portfolio", op: "snapshot", args: a }),
+  portfolio_history: (a) => ({ provider: "portfolio", op: "history", args: a }),
+  portfolio_value_graph: (a) => ({ provider: "portfolio", op: "valueGraph", args: a }),
+  nft_inventory: (a) => ({ provider: "nft-portfolio", op: "inventory", args: a }),
+  nft_gallery: (a) => ({ provider: "nft-portfolio", op: "gallery", args: a }),
+  nft_pnl: (a) => ({ provider: "nft-portfolio", op: "pnl", args: a }),
+  nft_prepare_list: (a) => ({ provider: "nft-portfolio", op: "prepareList", args: a }),
   rpc_balance: (a) => {
     const addr = a.address || DEFAULT_ADDRESS;
     if (!addr) throw new Error("address required (set ORACLE_DEFAULT_ADDRESS to supply a default)");
@@ -567,7 +783,21 @@ async function handle(request) {
   if (method === "tools/call") {
     try {
       const result = await callTool(params?.name, params?.arguments || {});
-      send({ jsonrpc: "2.0", id, result: { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] } });
+      if (result?.dataBase64 && /^image\/(?:svg\+xml|png|jpeg|webp)$/.test(String(result.mimeType || ""))) {
+        const { dataBase64, ...metadata } = result;
+        send({
+          jsonrpc: "2.0",
+          id,
+          result: {
+            content: [
+              { type: "image", data: dataBase64, mimeType: result.mimeType },
+              { type: "text", text: JSON.stringify(metadata, null, 2) },
+            ],
+          },
+        });
+      } else {
+        send({ jsonrpc: "2.0", id, result: { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] } });
+      }
     } catch (err) {
       send({ jsonrpc: "2.0", id, result: { isError: true, content: [{ type: "text", text: err.message }] } });
     }
@@ -596,7 +826,20 @@ function startStdioLoop() {
   });
 }
 
-if (import.meta.url === `file://${process.argv[1]}`) {
+// npm bin wrappers are symlinks. Comparing import.meta.url to argv[1] as strings
+// fails for `npx oracle-data-mcp` / node_modules/.bin/oracle-data-mcp and the
+// process exits without ever starting the stdio loop (Hermes sees Connection closed).
+function isMainModule() {
+  const entry = process.argv[1];
+  if (!entry) return false;
+  try {
+    return fs.realpathSync(entry) === fs.realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    return false;
+  }
+}
+
+if (isMainModule()) {
   startStdioLoop();
 }