@oracle-agent/oracle 0.13.0 → 0.13.1

package/dist/assets/profiles/stable-agent/profile.json

@@ -0,0 +1,38 @@
+{
+  "$schema": "./profile.schema.json",
+  "id": "stable-agent",
+  "label": "stable agent",
+  "role": "venue",
+  "color": "#F0B90B",
+  "description": "Stable mainnet (988): USDT-native gas, bridge-in routes, DEX-fork pools, launch/meme-token scans.",
+  "model": {
+    "note": "New-chain work is full of surprises; wants a careful model that verifies rather than assumes.",
+    "suggested": "careful-verifier"
+  },
+  "skills": [
+    "oracle-contract-research",
+    "oracle-receipts",
+    "oracle-circuit-breaker",
+    "oracle-best-execution",
+    "oracle-equities",
+    "oracle-meme-token-sniper",
+    "oracle-chain-graphs-telegram-cards",
+    "oracle-rfq-tokenized-assets"
+  ],
+  "mcp": [
+    "oracle-data"
+  ],
+  "chains": [
+    988
+  ],
+  "posture": {
+    "default": "DISARMED",
+    "grantActions": [
+      "read:chain",
+      "simulate:tx",
+      "prepare:swap"
+    ],
+    "signing": "user-wallet",
+    "rationale": "A young chain has thin liquidity and unverified forks. Every venue needs on-chain verification before use."
+  }
+}

package/dist/assets/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/dist/assets/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/dist/assets/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/dist/assets/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/dist/assets/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/dist/assets/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/dist/assets/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.

package/dist/assets/skills/oracle-best-execution/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: oracle-best-execution
+description: Use whenever swapping or bridging. The rule that the highest quote is not the cheapest trade, and how to compare routes honestly.
+---
+
+# Best execution
+
+The biggest `amountOut` is not the best route. Rank on **net received after gas and
+fees**, every time.
+
+## Get the comparison
+
+```
+best_swap_route   { chainId, tokenIn, tokenOut, amountIn, decimalsIn, decimalsOut }
+best_bridge_route { fromChainId, toChainId, tokenIn, tokenOut, amountIn }
+```
+
+Or at a shell:
+
+```bash
+oracle-route swap   base <tokenIn> <tokenOut> [amountIn]
+oracle-route bridge arbitrum base [token] [amountIn]
+```
+
+## Read the result properly
+
+Report the winner **and** the runners-up. A user who sees only the winner cannot tell
+whether it won by 0.01% or 3%, and that difference decides whether the route is worth
+any extra risk.
+
+Three fields carry most of the meaning:
+
+- **`rankedOn`** — `net-of-cost` means gas was accounted for. `gross` means it was
+  **not**, and the ordering may be wrong.
+- **`costAccounted`** (per route) — `false` means that route's gas is unknown. It is
+  ranked on gross, which **flatters it**. Say so.
+- **`improvementBps`** — `null` means no honest spread exists, usually because the
+  top two routes measure cost differently. Do not invent one.
+
+## What to say
+
+Good: *"ParaSwap nets 1903.88 USDC after $0.01 gas. CoW is 0.01% behind but gasless,
+so on a larger size it likely wins. LI.FI quotes competitively but $4.78 of gas puts
+it 0.5% down."*
+
+Bad: *"Best route: LI.FI, 1899 USDC."* — that is the gross number, and it lost.
+
+## Preparing the winner
+
+`prepare_best_route` compares, then builds the signable artifact for the winner:
+
+```
+prepare_best_route { chainId, tokenIn, tokenOut, amountIn, taker }
+```
+
+`taker` must be the **real wallet that will sign**. Quoting is anonymous; preparing
+is not. Placeholder and burn addresses are rejected.
+
+**Check `artifactKind` before telling the user what to do.** They are not
+interchangeable:
+
+- `unsigned-transaction` (LI.FI, ParaSwap, 0x) — sign and **broadcast** it.
+- `typed-data-order` (CoW) — sign the data and **submit it to the CoW API**. There is
+  nothing to broadcast. Signing authorizes a solver to settle on your behalf.
+
+**Approval comes first, and the spender is not always the destination.** For CoW the
+approval goes to the *vault relayer*, not the settlement contract — approving the
+wrong one produces an order that silently never fills. Read `requiresApproval.spender`
+rather than assuming it equals `destination`.
+
+Some venues refuse to build calldata until the approval already exists on-chain
+(ParaSwap does). That surfaces as `failureKind: "approval-required-first"`, which is
+a real ordering constraint, not a bug: approve, then prepare again.
+
+If the winner has no prepare path, the result names an `alternative`. Say that the
+winner could not be prepared and what you used instead — do not silently substitute.
+
+**Read `driftBps`.** Prepare re-quotes, so this is how far the route moved since the
+comparison. A large negative number means the ranking may no longer hold.
+
+## Preparing a bridge
+
+`prepare_best_bridge_route` — same idea, different hazards.
+
+**`transactions` is always a list.** Some routes need an approval *and* a deposit,
+signed in order. Tell the user how many and that order matters: signing only the
+first leaves funds approved but not bridged.
+
+**Two chains are in play.** Every transaction executes on `fromChainId`; the value
+lands on `toChainId`. Report both. A prepared artifact whose transaction chain does
+not match the origin is refused outright (`failureKind: "chain-mismatch"`).
+
+**Bridging is not atomic — say so unprompted.** The origin transaction confirming does
+**not** mean funds arrived. Give the `durationSeconds` estimate and tell the user not
+to re-send while pending. This is the single most common bridging panic, and silence
+here causes double-sends.
+
+**Across quotes but cannot be prepared** in this build. It often wins on gross because
+its gas is unreported, so expect `failureKind: "no-prepare-path"` with an
+`alternative`. Say the winner could not be prepared and name what you used instead.
+
+## Rules
+
+**One answer is not a comparison.** If only one source responded, say the route is
+unbenchmarked. `sourcesAnswered` vs `sourcesTried` tells you.
+
+**Never present an unknown cost as zero.** A route missing gas data is not free; it
+is unmeasured. Those are different claims and only one of them is true.
+
+**Duration is a cost on bridges.** A route saving $2 that takes 30 minutes is not
+strictly better than one costing $2 more that lands in 20 seconds. Surface both and
+let the user choose — do not silently pick for them.
+
+**Quotes decay.** Every number here is from a past block. Re-quote immediately before
+preparing, and never carry a minOut computed from a stale quote into a signature.
+
+**A comparison is not an execution.** Ranking a route does not prepare, sign, or send
+it. Preparing is a separate step, and signing belongs to the user.
+
+## When sources fail
+
+Aggregators go down, rate-limit, and get sunset (Odos sunset its public API in
+July 2026). Individual failures are expected and appear in `failed[]`. Two things
+follow:
+
+1. Fewer sources means a weaker comparison. Report `sourcesAnswered`, do not hide it.
+2. A failing source is **not** a bad price. Never rank it last — it did not answer.

package/dist/assets/skills/oracle-best-execution.md

@@ -0,0 +1,27 @@
+---
+name: oracle-best-execution
+description: Use whenever swapping or bridging. The rule that the highest-output route wins.
+---
+
+# Best execution
+
+## One rule
+The highest **net output** (after gas + bridge + impact) wins. Not the best quote, not the shortest route, not the prettiest UI.
+
+## Swap flow
+1. `data dex_search` → resolve token to chain + address
+2. `data dex_token` → get live pairs, liquidity, price
+3. `exec evm_quote` → exact-input quote from Uniswap V3
+4. `data best_swap_route` → compare across aggregators (Li.Fi, Paraswap, 0x, CoW)
+5. `data best_bridge_route` → if cross-chain, rank by net output
+6. `exec evm_prepare` → build unsigned tx
+7. Report: best route, net output, slippage, gas estimate
+
+## Comparison always in USD
+Convert gas + bridge fees to USD. 0.001 ETH ≠ 0.001 ETH across chains.
+
+## Slippage
+- Stable pools: 0.1% default
+- Volatile pools: 0.5% default  
+- Memecoins: 1-3% or auto-detect from depth
+- Block >1% slippage without explicit user approval

package/dist/assets/skills/oracle-bitcoin/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: oracle-bitcoin
+description: Use for Bitcoin L1, Ordinals/runes research, and inscription PSBT preparation. User-wallet signing only.
+---
+
+# Bitcoin L1 / Ordinals
+
+Bitcoin is a separate signing plane. Do not route it through EVM grants, EVM
+signers, or EVM calldata policy.
+
+## What this skill owns
+
+- Bitcoin L1 reads through Esplora: tip height, fee rates, address state, UTXOs,
+  transactions.
+- Ordinals/runes reads through the Bitcoin metaprotocol data providers.
+- Satflow marketplace research and unsigned PSBT intents for ordinals/runes market
+  actions when a Satflow key is configured.
+- Inscription planning and **PSBT preparation** for user-wallet signing.
+
+## Inscription flow
+
+Default path is self-custodial:
+
+1. Collect the inscription content, MIME type, destination address, change address,
+   and fee preference.
+2. Check Bitcoin health, fee rates, and the inscription body-size cap.
+3. Estimate commit/reveal cost and UTXO needs before preparing.
+4. Prepare commit/reveal PSBTs or unsigned artifacts.
+5. User signs in Xverse, UniSat, Leather, OKX, Phantom, Magic Eden wallet, or a
+   compatible injected Bitcoin wallet.
+6. Broadcast only after explicit user confirmation.
+7. Report commit txid, reveal txid, inscription id when known, and mempool/receipt
+   status.
+
+## Hard rules
+
+- Never request or print a seed, WIF, xprv, or wallet export.
+- Operator WIF/local signing is not part of the public default. If a deployment
+  has it, it must be separately armed and still explicit-confirm gated.
+- Inscribe is Bitcoin L1 commit/reveal. Satflow is marketplace inventory/listing,
+  not the inscription path.
+- Fee facts are live facts. Re-read fees immediately before prepare.
+- If content exceeds the current cap, refuse and offer compression/splitting.
+- Never claim an inscription landed without a real reveal txid or inscription id.
+
+## Review checklist
+
+- Content hash and byte length shown before signing.
+- MIME type shown in plain language.
+- Destination and change addresses displayed and user-confirmed.
+- Fee rate, estimated vbytes, and worst-case spend shown.
+- Commit/reveal sequence explained as non-atomic.
+- Mempool status checked after broadcast.

package/dist/assets/skills/oracle-chain-graphs-telegram-cards/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: oracle-chain-graphs-telegram-cards
+description: Render per-chain market graphs and Telegram cards for Oracle alerts, including meme launches, HL HIP-3/HIP-4, and Polymarket.
+---
+
+# Oracle chain graphs + Telegram cards
+
+Use when Oracle needs visual alerts: per-chain scanner cards, meme-token launch
+cards, route-comparison charts, Hyperliquid HIP-3/HIP-4 cards, or Polymarket
+cards.
+
+## Surfaces
+
+- Per-chain token charts: price, volume, liquidity, market cap, age, and venue.
+- Launch/sniper cards: token, chain, pool, route readiness, sellability, smart-wallet
+  overlap, risk status, and prepared-ticket status.
+- Hyperliquid HIP-3 builder-dex cards: dex, market, mark/oracle, funding, OI,
+  depth, liquidation/risk notes when account context is provided.
+- Hyperliquid HIP-4 outcome-market cards: event/outcome, bid/ask, depth, edge,
+  held-position context when API keys/account reads are configured.
+- Polymarket cards: event, market, Yes/No prices, volume, BBO, resolution-risk
+  notes, and prepared order intent only when user auth/API keys are configured.
+
+## Data rules
+
+- Public/keyless reads are allowed where the venue supports them.
+- API-key surfaces activate only when the user self-hosts and provides their own
+  keys. Never ship DEMI keys or assume hosted secrets.
+- A graph is evidence, not authorization. It can trigger a prepared ticket; it
+  must not bypass quote freshness, sell-sim, grant caps, or wallet signing.
+- Every card states chain/venue and confidence. Unknown data stays `UNKNOWN`.
+
+## Telegram card rules
+
+- Send text card and graph as separate messages when the card is long.
+- Avoid markdown traps: no unescaped underscore labels, avoid repeated `$` spans.
+- Keep full contracts/mints visible; never truncate the only identifier.
+- Chart rendering must soft-fail: card still sends if the image fails.
+- No buy/sell buttons unless the recipient has a valid local grant/session.
+
+## Graph schema
+
+A graph payload should include:
+
+- `chainId` / `cluster` / venue
+- token/market id
+- time window and candle interval
+- price/volume/liquidity series or order-book snapshots
+- source/provider and fetched timestamp
+- warnings for stale, sparse, or degraded data
+
+## HIP-3 / HIP-4 / Polymarket notes
+
+- HIP-3 builder perps require Hyperliquid `perpDexs` and `metaAndAssetCtxs` with
+  `dex` selected; core `meta` does not include all builder-dex markets.
+- HIP-4 outcome markets require the configured Hyperliquid/API-key path for user
+  account/order actions. Keyless cards can still show public market data.
+- Polymarket public reads work keyless; trading/order placement needs the user's
+  CLOB auth/API setup and stays prepared/user-signed.