@oracle-agent/oracle 0.13.0 → 0.13.1

package/dist/assets/skills/oracle-receipts.md

@@ -0,0 +1,29 @@
+---
+name: oracle-receipts
+description: Use whenever reporting the outcome of any on-chain action (swap, bridge, mint, send, list, accept-offer).
+---
+
+# Receipt format
+
+## Required fields
+- tx hash (full, with chain explorer link)
+- chain + chainId
+- action (swap/bridge/mint/send/list/accept-offer)
+- from → to (addresses)
+- amount in → amount out (with token symbols)
+- gas used + gas cost in USD
+- status: confirmed / pending / failed
+
+## Explorer links
+- Ethereum: https://etherscan.io/tx/{hash}
+- Base: https://basescan.org/tx/{hash}
+- Arbitrum: https://arbiscan.io/tx/{hash}
+- Optimism: https://optimistic.etherscan.io/tx/{hash}
+- Polygon: https://polygonscan.com/tx/{hash}
+- BSC: https://bscscan.com/tx/{hash}
+- HyperEVM: https://www.hyperscan.com/tx/{hash}
+
+## Never claim
+- "submitted" = confirmed. Only tx receipt with status=1 is confirmed.
+- A prepare is not a fill. Report prepare as "prepared, unsigned."
+- A sign is not a send. Report sign as "signed, not broadcast."

package/dist/assets/skills/oracle-rfq-tokenized-assets/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: oracle-rfq-tokenized-assets
+description: RFQ/intent routing across supported chains and guarded buys for tokenized Robinhood assets when user keys/routes are configured.
+---
+
+# Oracle RFQ + tokenized asset routing
+
+Use when a user asks for RFQ, solver/intent quotes, request-for-quote execution,
+or buying tokenized Robinhood-style assets/stocks on supported chains.
+
+## RFQ scope
+
+Oracle should treat RFQ as another best-execution source, not a bypass:
+
+- Query RFQ/intent venues where the chain and token pair are supported and the
+  user has configured any required API keys.
+- Compare RFQ quotes against AMM/aggregator routes on net received after gas,
+  fees, solver spread, and settlement assumptions.
+- Return `artifactKind` precisely: signed typed-data order vs unsigned tx vs
+  wallet-provider action.
+- Re-quote immediately before prepare/signing. RFQ expiry/nonce is short-lived.
+- Do not fabricate RFQ support for a chain without a configured venue.
+
+## Every-chain rule
+
+"Across all chains" means every configured chain is attempted and capability-labeled:
+
+- `RFQ_READY`: venue configured, quote live, prepare path verified.
+- `QUOTE_ONLY`: quote available, but no reviewed prepare path.
+- `UNCONFIGURED`: needs user API key or venue credentials.
+- `UNAVAILABLE`: no RFQ venue for that chain/token pair.
+- `BLOCKED`: policy, unsupported asset, compliance, or route guard rejected.
+
+Unsupported is an honest result, not a failure to hide.
+
+## Tokenized Robinhood assets
+
+Treat tokenized Robinhood assets as normal on-chain assets plus extra identity/risk
+checks:
+
+1. Resolve the exact chain and contract/mint from the official issuer/venue or a
+   user-provided contract. Never infer from ticker alone.
+2. Check asset metadata, decimals, supply, issuer/proxy/admin controls, transfer
+   restrictions, and redeemability/custody disclosures when public.
+3. Verify the venue/router can quote and prepare the asset on that chain.
+4. For buys, run the same route and slippage guard as any ERC-20/SPL swap.
+5. For sells, run sellability/reverse route first; tokenized assets may trade like
+   wrappers and can have restricted-transfer or allowlist rules.
+6. User signs; Oracle does not custody or guarantee redemption.
+
+## Output contract
+
+Return a table per chain/venue:
+
+- chain / venue / asset id
+- RFQ status and expiry
+- gross quote, estimated gas/fees, net output
+- artifact kind and signing path
+- policy blockers
+- confidence and data timestamp
+
+## Pitfalls
+
+- Calling a solver/RFQ quote "gasless" when the cost is hidden in spread.
+- Using an RFQ quote after expiry.
+- Treating a tokenized stock ticker as identity without contract provenance.
+- Ignoring transfer restrictions that make buys possible but exits blocked.
+- Routing tokenized Robinhood assets through DEMI/RH private executor by default;
+  public users must use their own wallet/key/API setup.

package/dist/assets/skills/oracle-smart-wallet-scanner/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: oracle-smart-wallet-scanner
+description: Use when finding, scoring, or monitoring smart wallets from on-chain behavior across tokens, NFTs, and venues.
+---
+
+# Smart-wallet scanner
+
+Use this for on-chain wallet intelligence: early buyers, profitable exits, repeat
+edge, copy-radar, cabal detection candidates, and wallet boards.
+
+## Smart wallet definition
+
+A wallet is not smart because it bought one winner. Require repeatable evidence:
+
+- early across multiple unrelated assets
+- profitable realized exits, not just mark-to-market bags
+- enough trade count and not only one ticker
+- entry before broad social consensus
+- exits before liquidity drain or sell imbalance
+- behavior survives fees, gas, and failed trades
+
+## Scan pattern
+
+1. Start from live events: pair creates, swaps, mint transfers, order fills,
+   marketplace sales, bridge inflows.
+2. Normalize wallet, chain, token/NFT, time, size, and realized PnL.
+3. Cluster funding and common recipients separately; do not call it a bundle
+   without launch-block clustering and common-funder evidence.
+4. Score wallets by multi-asset repeatability and drawdown, not raw largest win.
+5. Track holds vs exits. A smart buyer becoming a smart seller changes the signal.
+6. Emit confidence and evidence window with every wallet label.
+
+## Output standard
+
+For each wallet surface:
+
+- address and chain
+- sample wins/losses
+- realized PnL basis and limitations
+- first-seen timing vs launch/volume
+- current holdings/exit state if known
+- confidence: high / moderate / low / unknown
+
+## Hard rules
+
+- Never expose a private operator wallet as a public smart-wallet seed.
+- Never use one-token PnL as a primary smart label.
+- Cabal candidates are seeds for deeper analysis, not proof of manipulation.
+- If sell data is unavailable, label PnL `UNKNOWN`, not profitable.

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

@@ -0,0 +1,65 @@
+---
+name: oracle-solana
+description: Use for Solana research and swap preparation — Jupiter routes, SPL accounts, simulation, blockhash expiry.
+---
+
+# Solana
+
+Read and prepare through Oracle's data plane (`solana-rpc`, `jupiter`). No key
+required. Signing happens in the user's wallet; Oracle returns unsigned
+transactions.
+
+## Ops
+
+| Need | Op |
+|---|---|
+| SOL balance | `getBalance` |
+| SPL accounts | `tokenAccounts` |
+| fresh blockhash | `latestBlockhash` |
+| dry run | `simulate` |
+| route price | `jupiter.quote` |
+| unsigned swap tx | `jupiter.prepare` |
+
+## Blockhash expiry is the trap
+
+A Solana transaction carries a recent blockhash and dies in roughly 60–90 seconds.
+
+Consequences that catch people:
+
+- a transaction prepared two minutes ago is **dead** — re-prepare, don't retry
+- do not prepare, go do other tool work, then hand it over
+- if the user takes a while to approve, prepare again
+
+An expired transaction fails with a confusing error that looks like a routing bug.
+It isn't.
+
+## Simulate every time
+
+`simulateTransaction` is cheap and tells you the actual failure before the user
+signs. There is no reason to skip it. Check:
+
+- does it succeed at all
+- compute units consumed (near the limit → it will fail under load)
+- logs for the real revert reason
+
+## Account creation costs rent
+
+Swapping into a token the wallet has never held requires creating an associated
+token account, which costs SOL rent. Budget it, and say so — a wallet with exactly
+enough SOL for the swap will fail on the account creation.
+
+## Decimals are not standard
+
+Nine is common, six is common, others exist. Read the mint. Assuming decimals is how
+an amount ends up 1000x off.
+
+## Hard rules
+
+1. **Simulate before returning any transaction for signature.**
+2. **Never relay a caller-supplied RPC** — a hostile endpoint can lie about
+   simulation.
+3. **Return unsigned only.** Never a fully-signed transaction.
+4. **Solana authority is separate from EVM authority.** No EVM key satisfies a
+   Solana grant.
+5. Name the **mint address**, not just the ticker.
+6. Receipts or it didn't happen — confirmed signature or it failed.

package/dist/assets/skills/oracle-solana-nft/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: oracle-solana-nft
+description: Research Solana NFT collections and prepare unsigned Magic Eden buy, list, and mint transactions.
+---
+
+# Solana NFT lane (Magic Eden)
+
+Use when someone asks Oracle to check a Solana NFT collection's floor, find
+listings, buy an NFT, list one they hold, or mint from a launchpad drop.
+
+## Tiers
+
+| Op | Key needed | What it returns |
+|---|---|---|
+| `stats` | none | floor in SOL, listed count, 24h volume |
+| `listings` | none | mint, seller, auctionHouse, tokenATA, price |
+| `tokenListings` | none | listings for one specific mint |
+| `prepareBuy` | `MAGICEDEN_API_KEY` | unsigned base64 transaction |
+| `prepareList` | `MAGICEDEN_API_KEY` | unsigned base64 transaction |
+| `prepareMint` | `MAGICEDEN_API_KEY` | unsigned base64 transaction |
+
+Reads are keyless. Instruction builders need the user's own Magic Eden key. If
+the key is missing, say so plainly and stop; do not fake a ticket.
+
+## Flow for a buy
+
+1. `desk.solana.nftStats({ symbol })` - confirm the collection is real and get
+   the floor.
+2. `desk.solana.nftListings({ symbol, limit })` - pull live listings. The
+   cheapest listing is the first one when sorted by price.
+3. Set `maxPriceSol` from the user's stated ceiling, not from the floor. The cap
+   is checked before any network call, so a listing that moved above the ceiling
+   is rejected without touching the API.
+4. `desk.solana.nftPrepareBuy({ buyer, seller, auctionHouse, tokenMint, tokenATA, priceSol, maxPriceSol })`.
+5. Simulate the returned base64 through `desk.solana.simulate` before handing it
+   over. A prepared transaction that fails simulation is a prepared loss.
+6. Hand the user the unsigned transaction. Their wallet signs and sends.
+
+## Rules
+
+- Floor price is not a bid. Buying fills at the listing price, which can move
+  between the read and the signature.
+- Always pass `maxPriceSol`. Without it there is no ceiling on a mint or buy.
+- Collection symbols are validated as slugs. `../` and empty strings are
+  rejected, not encoded into a URL.
+- Every prepare returns `signingReady: false` and `broadcastReady: false`. Oracle
+  never signs a Solana transaction and never sends one.
+- Solana lamports are integers. `priceSol` is decimal SOL; the module converts.
+
+## Verification
+
+`npm run e2e:solana-bitcoin` hits live Magic Eden reads, a live Jupiter quote,
+a live prepared swap, and a live simulation, then asserts the prepare posture
+held.

package/dist/assets/skills/oracle-token-research/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: oracle-token-research
+description: Use when researching any token, especially low-cap or newly launched. The sell-side-first checklist that catches honeypots.
+---
+
+# Token research
+
+The default assumption for a new token is **hostile**. Research exists to disprove
+that, not to confirm a story.
+
+## Sell side first
+
+Most losses here are not bad entries. They are tokens that **buy cleanly and cannot
+be sold**. So the first question is never "will it go up" — it is "can I get out."
+
+Run a **round-trip simulation** in one state-free call: wrap native → buy token →
+sell token back → require a minimum return. Treat any of these as FAIL:
+
+- quote failure in either direction
+- transfer failure
+- router revert
+- round-trip return below the no-tax reverse quote by more than a small tolerance
+
+A successful **buy** quote proves nothing about the sell.
+
+## Price against the real pool
+
+A launchpad or bonding-curve token often exposes its **own** `getReserves()`
+returning zero or virtual values. The tradeable market is a *different* pair.
+
+- `blockTimestampLast == 0` → not a live pool. Do not size against it.
+- Find the real pair via `factory.getPair(a, b)` or a live swap's decoded target
+- A pair with `kLast`, `price0CumulativeLast`, `MINIMUM_LIQUIDITY` is standard V2
+  even when the router in front of it is a custom fork
+
+Sizing against stale reserves is how a "0.4% impact" trade becomes 3%.
+
+## Identity before action
+
+Tickers collide and get squatted. A fuzzy name match is a **candidate**, never
+confirmation.
+
+Always surface the **contract address** and require explicit confirmation before
+anything that moves value. `FEFUR` vs `FEFER` is a real class of loss.
+
+## The rest of the checklist
+
+| Check | Red flag |
+|---|---|
+| holder concentration | top 5 hold most of supply |
+| liquidity depth | thin relative to your size |
+| LP status | unlocked or removable |
+| age | hours old with heavy volume |
+| router | non-canonical clone with a familiar name |
+| mint authority | still open |
+| transfer logic | fees or blocks that change post-launch |
+
+## Label your evidence
+
+Mark every finding `LIVE`, `STALE`, `UNKNOWN`, or `UNAVAILABLE` with a timestamp.
+Do not call holder-concentration analysis "bundle detection" — bundles require
+launch-block clustering and common-funder evidence, which is a different query.
+
+## Honest output
+
+`unknown` is a correct and frequent answer about a two-hour-old token. Say it.
+Never let narrative quality substitute for a passing sell simulation.

package/dist/assets/skills/solana.md

@@ -0,0 +1,22 @@
+---
+name: solana
+description: Use for Solana reads and swap preparation.
+---
+
+# Solana
+
+## Read
+- `data solana_balance <pubkey>` — SOL balance
+- `data solana_token_accounts <pubkey>` — SPL token accounts
+- `data dex_search <symbol>` → resolve to Solana token
+
+## Swap
+- `data jupiter_quote` — get best swap route (≤100 bps slippage)
+- `data jupiter_prepare` — build unsigned swap tx
+- `data solana_simulate` — simulate before signing
+
+## Key facts
+- No EVM — separate address format, separate tools
+- Jupiter is the primary aggregator
+- Never sign a Solana tx without simulating first
+- Read/prepare only on this plane — signing uses operator package