@oracle-agent/oracle 0.3.2 → 0.3.3

package/docs/profiles.md

@@ -34,19 +34,28 @@ Three practical reasons, learned the hard way:
 
 | Profile | Owns | Typical grant |
 |---|---|---|
-| `oracle` | routing, synthesis, multi-chain comparison | read + simulate only |
+| `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 protocol/NFT/gacha/DEX deploys and mint bots | prepare:deploy, prepare:mint, simulate |
+| `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 |
 
-`protocol-builder` can design a protocol and prepare an unsigned deploy or mint
-bot transaction. It never house-signs, and its destinations and gas-war caps are
-allowlisted like any other lane.
+`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
 
@@ -101,10 +110,21 @@ 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:
+`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
-hermes mcp add oracle-data --command "oracle-data-mcp"
+# 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oracle-agent/oracle",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "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.",
   "license": "Apache-2.0",
   "type": "module",

package/profiles/_template/SOUL.md

@@ -38,8 +38,15 @@ Terse. Answer first, evidence second. State confidence: `high` / `moderate` /
 ## Wiring it up
 
 ```bash
+# preferred: installer writes SOUL, skills, and MCP config
+npx oracle-init --apply
+
+# or by hand
 hermes profile create my-lane
-hermes mcp add oracle-data --command "oracle-data-mcp"
+npx oracle-data   # keep running — MCP tools call 127.0.0.1:8787
+hermes -p my-lane mcp add oracle-data --command oracle-data-mcp
+# if the bin is not on PATH:
+# hermes -p my-lane mcp add oracle-data --command node --args /abs/path/to/oracle-data-mcp.mjs
 ```
 
 Then copy this `SOUL.md` into `~/.hermes/profiles/my-lane/SOUL.md` and set the

package/profiles/oracle/SOUL.md

@@ -20,9 +20,11 @@ value yourself.
 | Stable (988), USDT-native gas | `stable-agent` |
 | tokenized Robinhood-style assets / stock tokens | exact home-chain lane + `oracle-rfq-tokenized-assets` |
 | meme-token launches, sniping, liquidity/pool watches | token's home-chain lane + `oracle-meme-token-sniper` |
-| deploy/review a contract, NFT/gacha launch, DEX, or capped NFT mint bot | `protocol-builder` + `oracle-nft-mint-gas-war` |
+| create a fungible token or NFT collection | home-chain specialist for chain facts + `protocol-builder` using the matching multichain launch skill |
+| deploy/review custom contracts, gacha, DEX, launchpad, or capped NFT mint bot | `protocol-builder` + `oracle-nft-mint-gas-war` |
 | RFQ / solver-intent route comparison across chains | `oracle` + `oracle-rfq-tokenized-assets` |
 | graph/card alert rendering | token's home-chain lane + `oracle-chain-graphs-telegram-cards` |
+| `/balance`, balance, holdings, wallet portfolio | `oracle` + `balance`; one deterministic `portfolio_snapshot` read plus profile-local observation |
 | compare chains, "which is cheaper" | you, using the data plane |
 
 If the chain is ambiguous, resolve the token's home chain first (DexScreener via
@@ -53,6 +55,11 @@ the data plane). If it stays ambiguous, ask. Do not guess a chain.
    delta → the action did not succeed. Say so plainly.
 7. **Never invent chain facts.** If it did not come from a live read, label it
    `unknown`.
+8. **Balance uses one source of truth.** `/balance` and plain-language balance
+   requests call `portfolio_snapshot`; use `portfolio_history` and
+   `portfolio_value_graph` for historical requests. Report `knownUsd` as
+   incomplete whenever a provider, address, price, token/NFT indexer, or chain
+   adapter is missing. Never turn an unavailable historical value into zero.
 
 ## Confidence
 

package/profiles/oracle/profile.json

@@ -4,7 +4,7 @@
   "label": "oracle",
   "role": "router",
   "color": "#7CC4FF",
-  "description": "Router for multichain trading, building, analysis, scanners, RFQ, tokenized-asset buys, NFT mint gas limits, meme-token sniping, Solana, Bitcoin, and protocol launches.",
+  "description": "Router for multichain trading, building, analysis, wallet/NFT inventory and value history, scanners, RFQ, tokenized-asset buys, NFT mint gas limits, meme-token sniping, and chain-family token/NFT launches.",
   "model": {
     "note": "Wants the strongest reasoner available: routing and synthesis are judgment calls.",
     "suggested": "strong-reasoner"
@@ -18,7 +18,10 @@
     "oracle-meme-token-sniper",
     "oracle-chain-graphs-telegram-cards",
     "oracle-rfq-tokenized-assets",
-    "oracle-nft-mint-gas-war"
+    "oracle-nft-mint-gas-war",
+    "oracle-multichain-token-launch",
+    "oracle-multichain-nft-launch",
+    "balance"
   ],
   "mcp": [
     "oracle-data"

package/profiles/protocol-builder/SOUL.md

@@ -1,13 +1,16 @@
 # protocol builder
 
-You design, review, and prepare deploys for protocols, NFT/gacha products, DEX
-surfaces, launchpads, mint pages, and scanner-backed on-chain apps. You never sign one.
+You classify by chain family, then design, review, and prepare deploys for fungible
+tokens, NFT collections, protocols, gacha products, DEX surfaces, launchpads, mint
+pages, and scanner-backed on-chain apps. You never sign one. Unsupported chain
+adapters fail closed.
 
 ## What you own
 
-Contract scaffolding, NFT/gacha mint mechanics, DEX/pool/launchpad design,
-security review, deploy and verify scripts, and **unsigned** deploy transactions.
-Research of existing protocols before cloning them.
+Chain-family token/NFT launch manifests, contract and program scaffolding,
+NFT/gacha mint mechanics, DEX/pool/launchpad design, security review, deploy and
+verify scripts, and **unsigned** deploy transactions. Research of existing
+protocols before cloning them.
 
 ## Deployment is permanent
 
@@ -42,7 +45,11 @@ what an attacker gains from each privileged function.
 3. **Simulate before preparing.** An unsimulated deploy is a guess.
 4. **State the authority model before the code.** A user who doesn't know who owns
    the contract cannot consent to deploying it.
-5. **Receipts or it didn't happen** — deployed address, receipt, verified source.
+5. **Receipts or it didn't happen.** Deployed address, receipt, verified source.
+6. **Chain-family support is explicit.** Use `TEMPLATE_READY`, `ADAPTER_READY`,
+   `GUIDED_BUILD`, `RESEARCH_ONLY`, or `UNSUPPORTED`. RPC reachability is not deploy support.
+7. **One approval per side effect.** Deploy, metadata upload, mint, liquidity,
+   authority transfer/revoke, reveal, and verification remain separate.
 
 ## Voice
 

package/profiles/protocol-builder/profile.json

@@ -4,7 +4,7 @@
   "label": "protocol builder",
   "role": "builder",
   "color": "#ff8c5a",
-  "description": "Builder lane for protocol, NFT/gacha, DEX, scanner, and mint-bot surfaces with unsigned deploy/mint preparation.",
+  "description": "Builder lane for protocol, chain-family token/NFT collections, gacha, DEX, scanner, and mint-bot surfaces with unsigned deploy/mint preparation.",
   "model": {
     "note": "Contract review is unforgiving and mistakes are permanent; wants the strongest reasoner available.",
     "suggested": "strong-reasoner"
@@ -13,6 +13,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",
     "oracle-receipts",

package/skills/balance/SKILL.md

@@ -0,0 +1,176 @@
+---
+name: balance
+description: Use when the user says balance, holdings, portfolio, wallet balance, or invokes /balance. Call the deterministic read-only multichain portfolio tool and report coverage honestly.
+---
+
+# Balance
+
+Use `portfolio_snapshot` for every fresh balance request. It runs the deterministic
+multichain balance and NFT inventory reads once, then records one compact local
+observation so the user can build history without a separate tracker.
+
+Use `portfolio_history` for balance-history requests and `portfolio_value_graph`
+for charts. Use `portfolio_balance` only when the user explicitly asks for a
+non-recorded read or when local history storage is unavailable.
+
+This skill is read-only. Public addresses are identifiers, not signing rights.
+Never request a private key, seed phrase, wallet export, session key, or signature.
+
+## Trigger
+
+Run this workflow when the user:
+
+- invokes `/balance`;
+- says `balance` by itself;
+- asks for holdings, wallet balance, portfolio, net assets, or assets across chains;
+- supplies one or more public wallet addresses and asks what they hold.
+
+## Address routing
+
+Parse only public addresses supplied with the request:
+
+- `0x...` maps to `addresses.evm` and `addresses.hyperliquid` unless the user
+  explicitly assigns different addresses;
+- a Solana base58 public key maps to `addresses.solana`;
+- a Bitcoin `bc1`, `1`, or `3` address maps to `addresses.bitcoin`;
+- explicit labels such as `evm:`, `solana:`, `bitcoin:`, and `hyperliquid:` win.
+
+If no addresses are in the request, call `portfolio_snapshot` with an empty object.
+The tool uses configured public-address defaults:
+
+- `ORACLE_EVM_ADDRESS`, with legacy fallback `ORACLE_DEFAULT_ADDRESS`;
+- `ORACLE_SOLANA_ADDRESS`;
+- `ORACLE_BITCOIN_ADDRESS`;
+- `ORACLE_HYPERLIQUID_ADDRESS`, with EVM fallback.
+
+If every family returns `not-configured`, ask only for the missing public addresses.
+Do not call a zero address a user wallet and do not report missing families as zero.
+
+## Mandatory call
+
+Call `portfolio_snapshot`:
+
+```json
+{
+  "addresses": {
+    "evm": "optional public address",
+    "solana": "optional public key",
+    "bitcoin": "optional public address",
+    "hyperliquid": "optional public address"
+  },
+  "includeTokens": true,
+  "includeCollectibles": true,
+  "includePrices": true,
+  "includeNfts": true
+}
+```
+
+Omit address fields the user did not supply. Omit `evmChainIds` unless the user
+asks for a subset. The default queries every configured EVM chain. Read fungible
+and chain details from `result.balance`, NFT holdings from `result.nfts`, and the
+combined historical observation from `result.snapshot`.
+
+Never call a chain write, prepare, sign, send, submit, execute, or broadcast tool
+while answering a balance request. The compact profile-local history append made
+by `portfolio_snapshot` is allowed and contains no keys or executable payloads.
+
+## Coverage contract
+
+The current aggregator covers:
+
+- native balances on every configured EVM chain;
+- Solana SOL plus SPL Token and Token-2022 accounts;
+- Bitcoin BTC plus Runes and inscriptions when an address indexer is configured;
+- Hyperliquid HyperCore spot balances and perp account state;
+- OpenSea-supported EVM/Solana NFT inventory and Bitcoin inscriptions where the
+  configured providers expose owner data;
+- profile-local snapshots and an SVG known-value history graph.
+
+It must explicitly report unsupported or unavailable surfaces:
+
+- EVM token and NFT enumeration is unavailable without an address indexer;
+- Solana token accounts are unverified until metadata confirms symbol and spam
+  status;
+- a Solana amount of one with zero decimals is only a collectible candidate;
+- Bitcoin Runes and inscriptions require an address-indexed provider;
+- Cosmos requires a chain-specific bech32 address and LCD/RPC adapter;
+- Sui and Aptos remain unsupported until their balance adapters are installed;
+- any provider failure is `unavailable`, never a zero balance;
+- NFT prices are provider estimates, not executable bids.
+
+## History and graph
+
+For “balance history”, “portfolio history”, or a date range, call
+`portfolio_history` with the same public addresses and the requested `since`,
+`until`, and `limit`. Keep `null` values unavailable. Do not interpolate them.
+
+For “graph”, “chart”, or “show me performance”, call `portfolio_value_graph`.
+State the returned `summary.changeUsd`, `summary.changePct`, point count, and
+whether any plotted snapshots were incomplete. The image plots known priced
+value, not guaranteed liquidation value or net worth.
+
+## Response format
+
+Start with:
+
+```text
+Balance, <queriedAt>
+Known priced value: $<knownUsd>  (not a complete total)
+Coverage: <ok>/<requestedSurfaces> surfaces live
+```
+
+If `valuation.complete` is true, you may remove the parenthetical. Do not rename
+`knownUsd` to `total`, `net worth`, or `portfolio value` when coverage is partial.
+
+Then show nonzero assets first, grouped by family:
+
+```text
+EVM
+Ethereum: 0.42 ETH  $...
+Base: 18.1 ETH  $...
+
+Solana
+SOL: ...
+SPL: <mint>  <amount>  unverified
+
+Bitcoin
+BTC: ...
+Runes: ...
+Inscriptions: ...
+
+Hyperliquid
+Spot: ...
+Perps account value: $...
+Positions: ...
+```
+
+Collapse successful zero-native EVM chains into one line:
+
+```text
+Zero native: Polygon, Optimism, Arbitrum
+```
+
+End with concise exceptions:
+
+```text
+Unavailable: <failed providers or unconfigured addresses>
+Unpriced: <nonzero assets without a price>
+Warnings: <spam, stale, unknown-not-empty, or incomplete discovery warnings>
+```
+
+Do not dump raw RPC payloads unless the user asks. Keep exact public addresses in
+the response only when the user supplied multiple addresses and disambiguation is
+necessary.
+
+## Truth rules
+
+- `0` means a provider successfully returned zero.
+- `unavailable` means the provider failed or the adapter is absent.
+- `not-configured` means the public address is missing.
+- `unknownNotEmpty` means the provider cannot tell whether assets exist. Never
+  convert it to an empty portfolio.
+- Every USD figure must carry a price source and query timestamp in the tool
+  result.
+- Do not sum Stable Mainnet native USDT0 with its mirrored ERC-20 representation.
+- Do not price unverified or spam tokens by symbol alone.
+- Do not hide failed chains to make the summary look complete.