@oracle-agent/oracle 0.13.0 → 0.14.0

package/scripts/verify-dist.mjs

@@ -0,0 +1,29 @@
+// Smoke-test the bundled dist against the real package surface.
+import { readFileSync } from "node:fs";
+
+const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url)));
+const rows = [];
+
+for (const [name, target] of Object.entries(pkg.exports || {})) {
+  if (typeof target !== "string" || !target.startsWith("./src/")) continue;
+  const distPath = "../dist/" + target.replace(/^\.\/src\//, "");
+  try {
+    const srcMod = await import(new URL(target.replace("./", "../"), import.meta.url).href);
+    const dstMod = await import(new URL(distPath, import.meta.url).href);
+    const s = Object.keys(srcMod).sort();
+    const d = Object.keys(dstMod).sort();
+    const missing = s.filter((k) => !d.includes(k));
+    rows.push({ name, src: s.length, dist: d.length, missing });
+  } catch (e) {
+    rows.push({ name, error: String(e.message).slice(0, 80) });
+  }
+}
+
+let bad = 0;
+for (const r of rows) {
+  if (r.error) { bad++; console.log(`  FAIL ${r.name.padEnd(20)} ${r.error}`); continue; }
+  if (r.missing.length) { bad++; console.log(`  FAIL ${r.name.padEnd(20)} missing: ${r.missing.join(",")}`); continue; }
+  console.log(`  OK   ${r.name.padEnd(20)} ${r.dist} exports match`);
+}
+console.log(`\n${rows.length} entry points, ${bad} broken`);
+process.exitCode = bad ? 1 : 0;

package/scripts/verify-v3-venues.mjs

@@ -0,0 +1,233 @@
+#!/usr/bin/env node
+// Functionally verify Uniswap V3 venue addresses on every chain.
+//
+// Codesize alone is NOT verification -- an unrelated contract also has bytecode, and
+// on Base the canonical mainnet addresses returned 2109 bytes for two different
+// contracts, which is exactly the kind of false positive a size check waves through.
+//
+// The real test is behavioural: ask the candidate quoter to price a pair we already
+// know the answer to. A contract that returns a sane WETH->USDC quote at a standard
+// fee tier IS a working V3 quoter, regardless of what any doc claims.
+//
+// Output is a provenance record per chain, ready to paste into chains.config.mjs.
+
+import { rpcCall } from "../src/data/providers/evm-rpc.mjs";
+
+// Candidates. Most chains share the canonical deployment; Base, BSC and Avalanche
+// have their own. All of these are CANDIDATES until the probe passes.
+const CANONICAL_QUOTER = "0x61fFE014bA17989E743c5F6cB21bF9697530B21e";
+const CANONICAL_ROUTER = "0x68b3465833fb72A70ecDF485E0e4C7bD8665Fc45";
+
+const CANDIDATES = {
+  1: {
+    name: "ethereum",
+    quoter: CANONICAL_QUOTER,
+    router: CANONICAL_ROUTER,
+    tokenIn: "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2", // WETH
+    tokenOut: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", // USDC
+    decIn: 18,
+    decOut: 6,
+  },
+  10: {
+    name: "optimism",
+    quoter: CANONICAL_QUOTER,
+    router: CANONICAL_ROUTER,
+    tokenIn: "0x4200000000000000000000000000000000000006",
+    tokenOut: "0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85",
+    decIn: 18,
+    decOut: 6,
+  },
+  56: {
+    name: "bsc",
+    quoter: "0x78D78E420Da98ad378D7799bE8f4AF69033EB077",
+    router: "0xB971eF87ede563556b2ED4b1C0b0019111Dd85d2",
+    tokenIn: "0xbb4CdB9CBd36B01bD1cBaEBF2De08d9173bc095c", // WBNB
+    tokenOut: "0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d", // USDC (18dp on BSC)
+    decIn: 18,
+    decOut: 18,
+  },
+  137: {
+    name: "polygon",
+    quoter: CANONICAL_QUOTER,
+    router: CANONICAL_ROUTER,
+    tokenIn: "0x0d500B1d8E8eF31E21C99d1Db9A6444d3ADf1270", // WMATIC
+    tokenOut: "0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359", // USDC native
+    decIn: 18,
+    decOut: 6,
+  },
+  8453: {
+    name: "base",
+    quoter: "0x3d4e44Eb1374240CE5F1B871ab261CD16335B76a",
+    router: "0x2626664c2603336E57B271c5C0b26F421741e481",
+    tokenIn: "0x4200000000000000000000000000000000000006",
+    tokenOut: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
+    decIn: 18,
+    decOut: 6,
+  },
+  42161: {
+    name: "arbitrum",
+    quoter: CANONICAL_QUOTER,
+    router: CANONICAL_ROUTER,
+    tokenIn: "0x82aF49447D8a07e3bd95BD0d56f35241523fBab1",
+    tokenOut: "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
+    decIn: 18,
+    decOut: 6,
+  },
+  // HyperEVM 999 is a FORK deployment (HyperSwap), not the canonical Uniswap
+  // addresses -- which is exactly why it sat fail-closed: it was never in this
+  // map, so it was never tested, and "untested" printed the same as "broken".
+  999: {
+    name: "hyperevm",
+    quoter: "0x03A918028f22D9E1473B7959C927AD7425A45C7C",
+    router: "0x4E2960a8cd19B467b82d26D83fAcb0fAE26b094D",
+    tokenIn: "0x5555555555555555555555555555555555555555", // WHYPE
+    tokenOut: "0xB8CE59FC3717ada4C02eaDF9682A9e934F625ebb", // USDT0
+    decIn: 18,
+    decOut: 6,
+  },
+  // Stable 988 is a CANONICAL deployment (Official Uniswap v3 Deployments List,
+  // 2026-05-12) but was never in this map either. Pair is thin, so amountIn is
+  // sized up: 1 TOAST rounds to zero out, 10000 does not.
+  988: {
+    name: "stable",
+    quoter: "0xb070179E7032CdA868b53e6C1742F80c9e940d1A",
+    router: "0x32eaf9B5d5F2CD7361c5012890C943D7de84C22a",
+    tokenIn: "0x817997Ca8394E26CCE3dE3A076a4889b27DbF9dE", // WgUSDT
+    tokenOut: "0xd9c2E67afbc787ba9C7a886dd09947c127D3cC0d", // LEVCAT
+    decIn: 18,
+    decOut: 18,
+    feeTiers: [100],
+    // Deepest live pool on this chain (liquidity 1.41e24). An earlier candidate
+    // (TOAST/USDT0) drained from 1.4e19 to 0 mid-verification, so pick on depth.
+  },
+  // Abstract 2741 is a ZK-stack chain: canonical Uniswap addresses do not exist
+  // here (codesize 0), which is why probing them made it look like Abstract had
+  // no V3 at all. These are the real deployment, found from live swap traffic.
+  2741: {
+    name: "abstract",
+    quoter: "0x728BD3eC25D5EDBafebB84F3d67367Cd9EBC7693",
+    router: "0x7712FA47387542819d4E35A23f8116C90C18767C",
+    tokenIn: "0x3439153EB7AF838Ad19d56E1571FBD09333C2809", // WETH
+    tokenOut: "0x84A71ccD554Cc1b02749b35d22F684CC8ec987e1", // USDC.e
+    decIn: 18,
+    decOut: 6,
+    feeTiers: [500],
+  },
+  43114: {
+    name: "avalanche",
+    quoter: "0xbe0F5544EC67e9B3b2D979aaA43f18Fd87E6257F",
+    router: "0xbb00FF08d01D300023C629E8fFfFcb65A5a578cE",
+    tokenIn: "0xB31f66AA3C1e785363F0875A1B74E27b85FD66c7", // WAVAX
+    tokenOut: "0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E", // USDC
+    decIn: 18,
+    decOut: 6,
+  },
+};
+
+const FEE_TIERS = [500, 3000, 10000];
+
+const word = (v) => BigInt(v).toString(16).padStart(64, "0");
+const addrWord = (a) => a.slice(2).toLowerCase().padStart(64, "0");
+
+// QuoterV2.quoteExactInputSingle((address,address,uint256,uint24,uint160))
+// selector 0xc6a5026a -- struct is encoded inline as 5 words.
+function encodeQuote({ tokenIn, tokenOut, amountIn, fee }) {
+  return (
+    "0xc6a5026a" +
+    addrWord(tokenIn) +
+    addrWord(tokenOut) +
+    word(amountIn) +
+    word(fee) +
+    word(0) // sqrtPriceLimitX96 = 0 (no limit)
+  );
+}
+
+async function codesize(chainId, address) {
+  const r = await rpcCall(chainId, "eth_getCode", [address, "latest"]).catch(() => null);
+  const raw = r?.result ?? r;
+  return raw && raw !== "0x" ? (raw.length - 2) / 2 : 0;
+}
+
+async function probe(chainId, cfg) {
+  const result = {
+    chainId: Number(chainId),
+    name: cfg.name,
+    quoter: cfg.quoter,
+    router: cfg.router,
+    quoterCodesize: 0,
+    routerCodesize: 0,
+    workingFeeTier: null,
+    quotedOut: null,
+    humanPrice: null,
+    verdict: "FAIL",
+    reason: "",
+  };
+
+  result.quoterCodesize = await codesize(chainId, cfg.quoter);
+  result.routerCodesize = await codesize(chainId, cfg.router);
+
+  if (!result.quoterCodesize || !result.routerCodesize) {
+    result.reason = "no bytecode at candidate address on this chain";
+    return result;
+  }
+
+  // Behavioural probe: does it actually price a pair we can sanity-check?
+  const units = cfg.amountIn ?? 1n;
+  const amountIn = units * 10n ** BigInt(cfg.decIn);
+  for (const fee of cfg.feeTiers ?? FEE_TIERS) {
+    const data = encodeQuote({
+      tokenIn: cfg.tokenIn,
+      tokenOut: cfg.tokenOut,
+      amountIn,
+      fee,
+    });
+    const r = await rpcCall(chainId, "eth_call", [{ to: cfg.quoter, data }, "latest"]).catch(
+      () => null,
+    );
+    const raw = r?.result ?? r;
+    if (!raw || raw === "0x" || raw.length < 66) continue;
+
+    const out = BigInt(`0x${raw.slice(2, 66)}`);
+    if (out === 0n) continue;
+
+    result.workingFeeTier = fee;
+    result.quotedOut = out.toString();
+    result.humanPrice = Number(out) / 10 ** cfg.decOut;
+    break;
+  }
+
+  if (result.workingFeeTier == null) {
+    result.reason = "bytecode present but no fee tier returned a quote -- not a working V3 quoter";
+    return result;
+  }
+
+  // Sanity band. A working quoter on a major pair should land in a plausible range;
+  // a wildly wrong number means we are talking to the wrong contract or decoding it
+  // wrong, and either way it must not be allowlisted.
+  if (result.humanPrice <= 0 || !Number.isFinite(result.humanPrice)) {
+    result.reason = `implausible quote ${result.humanPrice}`;
+    return result;
+  }
+
+  result.verdict = "PASS";
+  result.reason =
+    `quoteExactInputSingle at fee ${result.workingFeeTier} returned ` +
+    `${result.humanPrice} for 1 unit in -- a live, working V3 quote`;
+  return result;
+}
+
+const out = [];
+for (const [chainId, cfg] of Object.entries(CANDIDATES)) {
+  const r = await probe(chainId, cfg);
+  out.push(r);
+  const line =
+    `${r.name.padEnd(10)} ${r.verdict.padEnd(5)} ` +
+    `quoter=${String(r.quoterCodesize).padStart(6)} router=${String(r.routerCodesize).padStart(6)} ` +
+    (r.workingFeeTier ? `fee=${String(r.workingFeeTier).padStart(5)} price=${r.humanPrice}` : r.reason);
+  console.log(line);
+}
+
+console.log(`\n${out.filter((r) => r.verdict === "PASS").length}/${out.length} chains verified`);
+if (process.argv.includes("--json")) {
+  console.log(JSON.stringify(out, null, 2));
+}

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.

package/skills/bitcoin-l1.md

@@ -0,0 +1,33 @@
+---
+name: bitcoin-l1
+description: Use for Bitcoin L1, Ordinals, and Runes operations.
+---
+
+# Bitcoin L1
+
+## Read
+- `data btc_balance <addr>` — balance in sats
+- `data btc_utxos <addr>` — UTXO set
+- `data btc_fees` — current fee rates (sats/vB)
+- `data btc_tx <txid>` — transaction lookup
+
+## Ordinals
+- `data btc_inscriptions <addr>` — inscriptions held
+- `data btc_inscription_info <id>` — inscription metadata
+- `data satflow_floors <collection>` — floor prices
+- `data satflow_floor_listings <collection>` — active listings
+
+## Runes
+- `data btc_rune_balance <addr>` — rune balances
+- `exec bitcoin_runes_prepare_transfer` — prepare transfer
+
+## Prepare
+- `exec bitcoin_prepare <from> <to> <amountSats>` — payment intent
+- `exec bitcoin_inscribe_prepare` — inscription commit/reveal
+- `exec bitcoin_satflow_prepare_purchase` — buy ordinals/rune
+
+## Key rules
+- 1 BTC = 100,000,000 sats
+- Never consume inscribed/rare-sat UTXOs as fee inputs
+- PSBT review before sign — user must approve
+- Payment and ordinals addresses should be distinct when wallet separates them

package/skills/chain-defi-ecosystem-profiling.md

@@ -0,0 +1,27 @@
+---
+name: chain-defi-ecosystem-profiling
+description: Use when profiling a chain's DeFi ecosystem — TVL, protocols, gaps.
+---
+
+# Chain ecosystem profiling
+
+## Data sources
+- `data llama_protocols` — DeFiLlama protocol list with TVL
+- `data llama_prices` — current prices keyed by chain:address
+- `data dex_search` — token discovery
+- `data data_health` — which data providers are live
+- `data scanner_coverage` — which chains scanner supports
+
+## What to report
+1. **TVL** — total value locked, top 5 protocols by TVL
+2. **DEX volume** — 24h volume, active pairs
+3. **Lending** — money markets, rates
+4. **Bridges** — canonical bridge, third-party options
+5. **Gaps** — missing primitives (no lending, no stablecoin, etc.)
+6. **Risk** — bridge risk, oracle risk, concentration risk
+
+## Confidence
+- Live DeFiLlama data = high confidence
+- Recent but not real-time = moderate
+- Community estimates = low
+- Unknown = say unknown

package/skills/evm-contract-research.md

@@ -0,0 +1,27 @@
+---
+name: evm-contract-research
+description: Use when researching or verifying EVM contracts, routers, factories, or tokens.
+---
+
+# EVM contract research
+
+## Verification
+1. `data dex_search <symbol>` → find token home chain + address
+2. `data dex_token <address>` → live pairs, volume, liquidity, age
+3. `data rpc_balance <address>` → native balance on chain
+4. `exec evm_erc20_allowance <owner> <spender>` → check approvals
+5. Use block explorer for source code verification
+
+## Red flags
+- No verified contract on explorer
+- Created < 24h ago
+- Liquidity < $10k
+- Single LP holding > 50%
+- Buy/sell tax > 5%
+- Honeypot (can buy, can't sell)
+- Proxy with unverified implementation
+
+## Trusted routers (verify on-chain, don't assume)
+- Uniswap V2 Router: 0x7a250d5630B4cF539739dF2C5dAcb4c659F2488D (Ethereum)
+- Uniswap V3 Router: 0xE592427A0AEce92De3Edee1F18E0157C05861564
+- UniversalRouter: 0x3fC91A3afd70395Cd496C647d5a6CC9D4B2b7FAD

package/skills/hyperliquid.md

@@ -0,0 +1,26 @@
+---
+name: hyperliquid
+description: Use when working with Hyperliquid L1 — perps, spot, points, or HyperEVM.
+---
+
+# Hyperliquid
+
+## Read plane (keyless)
+- `data data_call hl-info allMids` — all perp mid prices
+- `data data_call hl-info l2Book` — L2 orderbook depth
+- `data data_call hl-info userState` — user positions + margin
+- `data data_call hl-info userFills` — trade history
+- `data data_call hl-info candleSnapshot` — OHLCV candles
+- `data data_call hl-info spotMeta` — spot market metadata
+- `data data_call hl-ws allMids` — fast WS snapshot
+
+## HyperEVM (chain 999)
+- RPC: https://rpc.hyperliquid.xyz/evm
+- Explorer: https://www.hyperscan.com
+- DEX search via `data dex_token` on chain 999
+- Gas: paid in HyperEVM native token, ~0.1-0.5 USD typical
+
+## Points
+- Earned through perp trading volume
+- No public API for points balance — uses userState for volume inference
+- Wallet age + volume are primary signals

package/skills/multichain-exec-desk.md

@@ -0,0 +1,33 @@
+---
+name: multichain-exec-desk
+description: Use for cross-chain or multi-chain execution tasks.
+---
+
+# Multichain execution desk
+
+## Chain routing
+- RH 4663 → oracle owns it (rhbot executor)
+- Hyperliquid → hl-info / hl-ws (read-only, keyless)
+- EVM chains → mad_exec evm_* tools
+- Solana → Jupiter tools
+- Bitcoin → btc_* tools
+
+## Execution flow
+1. `data evm_chains` — list supported chains
+2. `data dex_search` — resolve token
+3. `exec evm_quote` — quote swap
+4. `data best_swap_route` — compare aggregators
+5. `exec evm_prepare` — build unsigned tx
+6. `exec evm_simulate` — simulate (optional but recommended)
+7. `exec evm_sign` — sign (gated)
+8. `exec evm_send` — broadcast (gated)
+
+## Cross-chain
+- `data best_bridge_route` — compare bridge providers
+- `data prepare_best_bridge_route` — build signable bridge tx
+- `data rfq_quote` — RFQ/intent routing for large sizes
+
+## Safety
+- Verify destination chainId matches intent
+- Check bridge provider is live (data health first)
+- Never route through unverified contracts

package/skills/oracle-action-semantics/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: oracle-action-semantics
+description: Use for watch, ping, prepare, arm, sign, send, or execution-capability questions.
+---
+
+# Oracle action semantics
+
+Keep these planes distinct:
+
+1. **Public prepare plane**: reads, quotes, simulates, and prepares unsigned artifacts. It never signs or broadcasts.
+2. **Generic Oracle signer**: the unattended daemon exposes six *bounded* surfaces — `hl`, `poly`, `evm-swap`, `evm-bridge`, `btc`, `sol`. Bounded is not generic chain authority: each surface decodes and validates its own envelope shape and refuses while its allowlists are empty. Enablement is never authority; every signature still needs one exact owner-confirmed grant.
+3. **User-wallet EVM**: ordinary EVM preparations require the user's wallet signature.
+4. **Optional bounded EVM execution**: a deployment may expose a separate same-host, owner-gated EVM executor such as MAD. Verify its status and policy before saying it is available. Never infer it from the public package or the generic signer.
+
+Do not turn a deployment fact into a universal claim. If no bounded EVM executor is installed or healthy, say the current deployment cannot execute EVM. Do not say Oracle can never execute EVM.
+
+## Binding vocabulary
+
+- `watch`, `watch this`, `ping`, `ping me`, `alert`, and `notify` mean notification only.
+- Persist them as `active: true` and `actionMode: alert_only`.
+- `arm` means authorization intent for one exact bounded action.
+- Persist it as `active: true` and `actionMode: execute` only after the exact action and owner authorization are present.
+- Never convert `watch` into execution.
+- Never convert `arm` into a watch.
+- A status field such as `armed` is not action authority. Current records require explicit `active` and `actionMode` fields.
+
+Before accepting `arm`, require the exact chain, token pair, amount or fraction, trigger, recipient, router, deadline, slippage bound, and approval bound. Require the owner-gated executor to be healthy and disarmed until that exact action is authorized. Refuse global, implied, or reusable authorization.
+
+## Execution states
+
+Report each state separately:
+
+- `executionReady`
+- `requiresUserSignature`
+- `signingReady`
+- `broadcastReady`
+
+A quote is not a preparation. A preparation is not a signature. A signature is not a broadcast. A broadcast is not mined execution. Claim success only after a transaction hash, successful receipt, and expected balance delta.
+
+ERC-20 approval is a separate transaction. Use an exact bounded amount unless the user explicitly authorizes another cap. Never silently create an unlimited approval.