@oracle-agent/oracle 0.3.5 → 0.3.6

package/profiles/robinhood-agent/SOUL.md

@@ -34,9 +34,15 @@ that moves value.
 1. **Sell-simulation before any prepared buy.** No exception for a good story.
 2. **Never size against stale or virtual reserves.**
 3. **A fuzzy ticker match is not confirmation** — surface the CA.
-4. **You do not sign.** Swaps are prepared for the user's wallet.
-5. **Receipts or it didn't happen.**
-6. **Floor price is not a bid.** Accept-offer fills at the bid; a listing waits
+4. **The public lane does not sign.** Ordinary swaps are prepared for the user's
+   wallet. The generic unattended signer remains `hl`/`poly`; a separately installed,
+   owner-gated EVM executor may handle one exact bounded Robinhood Chain action after
+   explicit `arm`. Verify that executor before claiming it is available.
+5. **Watch is alert-only.** `watch`, `watch this`, and `ping me` persist as
+   `active: true, actionMode: alert_only`. Only explicit `arm` can produce
+   `actionMode: execute`; never infer execution from a watch or legacy `status: armed`.
+6. **Receipts or it didn't happen.**
+7. **Floor price is not a bid.** Accept-offer fills at the bid; a listing waits
    for a buyer. Never conflate them.
 
 ## Voice

package/profiles/robinhood-agent/profile.json

@@ -11,6 +11,7 @@
   },
   "skills": [
     "oracle-token-research",
+    "oracle-action-semantics",
     "oracle-receipts",
     "oracle-circuit-breaker",
     "oracle-best-execution",

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/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 surfaces remain `hl` and `poly`. This does not grant EVM authority.
+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/skills/oracle-multichain-nft-launch/SKILL.md

@@ -0,0 +1,338 @@
+---
+name: oracle-multichain-nft-launch
+description: Use when planning, building, reviewing, or preparing an NFT collection launch across EVM, Solana, Bitcoin Ordinals, Cosmos, Move, HyperEVM, or another chain family. Fail closed on unsupported adapters; preserve metadata provenance; prepare only; the user signs every side effect.
+---
+
+# Multichain NFT collection launch
+
+## Contract
+
+Use this skill for collection contracts or programs, metadata and media manifests,
+allowlists, public mints, royalties, reveals, editions, inscriptions, and collection
+verification.
+
+"Every chain" means classify the chain family and use a verified native standard.
+There is no universal NFT transaction. An ERC-721, a Metaplex collection, a Bitcoin
+parent inscription, a CW721 contract, and a Move object are different products.
+
+Oracle researches, scaffolds, tests, simulates, and prepares unsigned actions. The
+user signs collection creation, mint, metadata, authority, treasury, marketplace,
+and reveal actions separately. Never broadcast from this skill.
+
+When loaded by the `oracle` router, use this skill to classify the request, then
+route chain research to the relevant specialist and build/prepare work to
+`protocol-builder`. The router remains read and simulate only.
+
+If the launch uses randomized packs or loot mechanics, load
+`oracle-nft-gacha-launch` as an additional safety layer.
+
+## Support status language
+
+Use exactly one status before building:
+
+| Status | Meaning |
+|---|---|
+| `TEMPLATE_READY` | Oracle ships a gated collection template and prepare adapter for the exact standard. |
+| `ADAPTER_READY` | A chain-specific creation/mint encoder exists and passed simulation or testnet verification. |
+| `GUIDED_BUILD` | Oracle can scaffold and test the project, but no generic transaction adapter is shipped. |
+| `RESEARCH_ONLY` | Oracle can verify standards and produce a launch plan, not a deployable bundle. |
+| `UNSUPPORTED` | Required primitives or trustworthy tooling cannot be verified. Stop. |
+
+Do not call marketplace read or mint-bot support a collection-deployment adapter.
+Buying an NFT, minting from an existing contract, and creating a collection are
+three separate capabilities.
+
+## Current family matrix
+
+| Family | Collection primitive | Default status | Required path |
+|---|---|---|---|
+| EVM | ERC-721, ERC-1155, ERC-2981 | `GUIDED_BUILD` until a gated Oracle collection template ships | Foundry tests, metadata/reveal tests, fork simulation, unsigned deploy |
+| Solana | Metaplex Core, Token Metadata collection, Candy Machine/drop programs | `GUIDED_BUILD` | Select one standard, validate authorities, simulate ordered unsigned transactions |
+| Bitcoin | Ordinals parent/child inscriptions and indexer collection manifests | `GUIDED_BUILD` for content and commit/reveal planning; adapter evidence required for `ADAPTER_READY` | Provenance manifest, parent link, UTXO/fee/reveal safety |
+| Cosmos | CW721 or chain-native NFT module | `RESEARCH_ONLY` by default | Verify chain-specific instantiate/execute messages and migration admin |
+| Sui | object-based collection and kiosk ecosystem | `RESEARCH_ONLY` by default | Move package, object capabilities, display metadata, testnet publish |
+| Aptos | Digital Asset standard or chain-native collection objects | `RESEARCH_ONLY` by default | Collection/mint refs, mutation permissions, testnet publish |
+| HyperEVM | ERC-721 or ERC-1155 | EVM status | Exact HyperEVM chain id and verified RPC/toolchain |
+| Hyperliquid L1 | no generic NFT contract path assumed | `UNSUPPORTED` unless an official native primitive is verified | Route to HyperEVM when the product is EVM-native |
+| Other | chain-native | `UNSUPPORTED` until classified | Add and verify a dedicated adapter before preparing transactions |
+
+## 1. Build the collection manifest
+
+Do not generate contract or metadata artifacts until this manifest is complete:
+
+```yaml
+collection:
+  name: ""
+  symbol: ""
+  chain_family: ""
+  chain_name: ""
+  chain_id_or_genesis: ""
+  network: mainnet|testnet|devnet|local
+  standard: ""
+  supply: 0
+  edition_size: 1
+  onchain_media: false
+  license: ""
+  content_rating: ""
+mint:
+  price: ""
+  currency: ""
+  treasury: ""
+  per_wallet: 0
+  allowlist_root: none
+  allowlist_start: null
+  public_start: null
+  public_end: null
+  reveal: immediate|delayed|commit-reveal|vrf
+metadata:
+  base_uri: ""
+  storage: ipfs|arweave|onchain|other
+  mutable: false
+  provenance_root: ""
+  placeholder_uri: none
+royalties:
+  bps: 0
+  recipients: []
+authorities:
+  owner: ""
+  mint: ""
+  metadata_update: none
+  freeze: none
+  pause: none
+  withdraw: ""
+  upgrade: none
+```
+
+Validate supply against generated metadata count. Record raw payment units and
+human-readable units. Royalty splits must reconcile exactly.
+
+## 2. Set rights, metadata, and provenance first
+
+1. State who owns the media and which license collectors receive.
+2. Hash every final media and metadata file.
+3. Validate token IDs or asset indexes are unique and contiguous when required.
+4. Pin or upload content only after the user approves that side effect.
+5. Build a deterministic provenance root over the final ordered assets.
+6. Separate placeholder metadata from final metadata.
+7. State whether metadata can change, who can change it, and how that authority is
+   transferred or revoked.
+8. Never promise immutable media when the JSON points to mutable HTTP storage.
+
+Metadata upload, contract deployment, first mint, reveal, marketplace verification,
+and authority revocation are separate actions.
+
+## 3. Force an authority and economics review
+
+Before preparing transactions, print a table for:
+
+- contract, package, or program upgrade authority
+- collection owner
+- mint authority
+- freeze or transfer-restriction authority
+- metadata update authority
+- reveal authority
+- pause authority
+- treasury withdrawal authority
+- royalty recipient and royalty update authority
+- allowlist root setter
+- supply increase or edition authority
+
+For each, state initial holder, mutability, transfer/revoke action, and operational
+consequence of revocation.
+
+Also disclose:
+
+- total supply and reserved supply
+- mint phases and wallet caps
+- mint price and payment token
+- treasury destination
+- creator/team allocation
+- royalties and whether marketplaces can ignore them
+- upgradeability
+- delayed reveal and randomness assumptions
+- estimated deploy, storage, mint, and reveal costs
+
+Never market royalties as guaranteed income. Many marketplaces treat them as
+optional.
+
+## 4. Family-specific build paths
+
+### EVM
+
+Choose ERC-721 for unique items and ERC-1155 for editions or mixed fungibility.
+Add ERC-2981 only as a royalty signal, not enforcement.
+
+Prefer reviewed OpenZeppelin bases and minimal immutable deployment. If a proxy is
+required, show proxy admin, implementation upgrade authority, and timelock.
+
+Required Foundry coverage:
+
+- maximum supply and reserved supply cannot be exceeded
+- per-wallet and per-phase caps
+- exact payment and refund behavior
+- treasury withdrawal and reentrancy resistance
+- allowlist proof validation and replay boundaries
+- reveal ordering and provenance
+- metadata freeze or update permissions
+- royalty values and recipients
+- pause behavior
+- owner cannot mint hidden supply
+- ERC-721 or ERC-1155 interface conformance
+
+Run `forge test`, static analysis when available, fork or RPC simulation, and dry-run
+deploy. Prepare contract verification separately. Initial mint, public mint opening,
+base URI change, reveal, and ownership transfer are separate unsigned actions.
+
+### Solana
+
+Choose one product shape before code:
+
+- Metaplex Core for a modern asset/collection model
+- Token Metadata collection for compatibility with legacy NFT tooling
+- Candy Machine or another audited drop program for staged public mints
+
+Do not mix models casually. Print all collection, update, freeze/delegate, mint,
+rule-set, and candy-machine authorities.
+
+Prepare ordered unsigned transactions for:
+
+1. create the collection asset or collection mint
+2. create and verify collection metadata
+3. create drop/mint configuration when used
+4. fund storage/rent accounts
+5. mint or reserve initial assets
+6. verify items into the collection
+7. transfer or revoke update/mint authorities
+
+Simulate against the intended cluster. Validate account owners, rent, compute units,
+address lookup tables, and transaction size. Rebuild expired blockhashes rather than
+editing signed data.
+
+### Bitcoin Ordinals
+
+A Bitcoin collection is normally an indexer-recognized group of inscriptions, not a
+collection smart contract. Build:
+
+- canonical collection metadata and provenance manifest
+- parent inscription plan
+- child inscription relationships when supported
+- exact content type and content hash for every item
+- deterministic inscription order
+- commit and reveal PSBT plan
+- postage, fee rate, reveal destinations, and recovery addresses
+
+Protect commit UTXOs from accidental spends. Account for fee changes, reorgs,
+inscription ordering, and cursed/unbound outcomes. Do not promise stable inscription
+numbers before confirmation. Collection listing with an indexer or marketplace is a
+separate side effect after confirmed inscription IDs exist.
+
+### Cosmos
+
+First identify the target's actual NFT primitive. CW721, a chain-native NFT module,
+and an EVM runtime are not interchangeable.
+
+For CW721, verify the exact code artifact, checksum, instantiate message, minter,
+metadata extension schema, royalty extension if any, migration admin, and chain gas
+model. For a native module, verify current protobuf messages and authority behavior
+from the running chain version. Use the EVM path only for a proven EVM runtime.
+
+### Sui
+
+Model collection, item objects, treasury or publisher capabilities, display
+metadata, transfer policy, royalties/kiosk behavior, package upgrade policy, and
+shared versus owned objects. Test package publish, collection creation, mint,
+transfer, and authority transfer on testnet before any mainnet prepare.
+
+### Aptos
+
+Use the current Digital Asset or chain-native collection standard verified against
+the target network. Define collection mutability, token mutability, mint refs,
+burn/transfer refs, royalty data, supply caps, and module upgrade policy. Publish and
+exercise the lifecycle on testnet first.
+
+### Hyperliquid
+
+HyperEVM NFT launches use the EVM path. Do not assume Hyperliquid L1 has a generic
+NFT collection primitive because HyperCore supports spot, perps, staking, or outcome
+markets. Without a verified official L1 standard and adapter, mark it `UNSUPPORTED`.
+
+## 5. Mint phases and randomness
+
+For allowlists:
+
+- bind proofs to chain, contract/program, phase, wallet, allowance, price, and expiry
+- publish the snapshot method and Merkle root
+- prevent proof reuse across phases or contracts
+- test wallet caps across allowlist and public phases together
+
+For delayed reveal or randomized assignment:
+
+- commit the final provenance before mint
+- do not use timestamp, recent block hash, predictable block fields, or validator
+  discretion as sole randomness
+- use a verified randomness source or a deterministic disclosed assignment
+- show who can trigger reveal and whether they can reroll
+- publish gacha odds when rarity is randomized
+
+Load `oracle-nft-gacha-launch` for packs, loot boxes, or paid random outcomes.
+
+## 6. Marketplace and launch-page setup
+
+Marketplace listing is not deployment. Only prepare it after contract/program or
+inscription identifiers are final.
+
+Before a mint page can claim ready:
+
+- wallet and network switching work
+- contract/program and payment destinations are exact
+- total and per-wallet cost include gas/fees
+- sold-out and phase transitions read chain state
+- failed/rejected transactions surface clearly
+- mint count cannot exceed the approved cap
+- metadata preview comes from the pinned manifest
+- no private key or seed phrase is requested
+
+Never fabricate floor price, bids, volume, rarity, or sold count.
+
+## 7. Required artifacts
+
+A completed prepare run returns:
+
+1. `collection-manifest.yaml`
+2. ordered metadata/media checksums and provenance root
+3. rights/license statement
+4. authority and mutability table
+5. source/package hash and dependency lock
+6. test and static-analysis results
+7. target-chain simulation or an explicit missing-capability note
+8. fee, rent, postage, and treasury estimate as applicable
+9. ordered unsigned transaction or PSBT bundle with payload hashes
+10. source/program verification payload
+11. separate metadata upload, marketplace, reveal, and authority-revoke actions
+12. final user approval checklist, one side effect per line
+
+Do not emit signed transactions, private keys, seed phrases, keystore passwords, or
+broadcast commands with signing enabled.
+
+## Refusals
+
+Refuse stolen media, hidden supply, owner-only rerolls, fake randomness, metadata
+rugs, undisclosed upgrades, wash trading, fake floor/volume, deceptive rarity,
+royalty claims presented as guaranteed, and wallet-draining mint pages.
+
+## Completion gate
+
+A collection is only `PREPARED` when:
+
+- chain and standard are exact
+- support status is honest
+- supply matches metadata
+- rights and storage are explicit
+- all authorities and mutable fields are disclosed
+- tests pass
+- simulation passes or the missing capability is explicit
+- every destination and payload hash is recorded
+- no signing, upload, marketplace listing, or broadcast occurred without separate
+  user approval
+
+Anything less is `DRAFT`, `RESEARCH_ONLY`, or `UNSUPPORTED`.