@oracle-agent/oracle 0.13.0 → 0.13.1

package/dist/assets/skills/oracle-multichain-token-launch/SKILL.md

@@ -0,0 +1,300 @@
+---
+name: oracle-multichain-token-launch
+description: Use when planning, building, reviewing, or preparing a fungible token launch on EVM, Solana, Bitcoin Runes, Cosmos, Move, Hyperliquid, or another chain family. Fail closed on unsupported adapters; prepare and simulate only; the user signs each side effect.
+---
+
+# Multichain token launch
+
+## Contract
+
+Use this skill for fungible asset creation, initial distribution, public sale setup,
+and liquidity bootstrap preparation.
+
+"Every chain" means route the request to a verified chain-family path. It does not
+mean one bytecode artifact or one transaction encoder works everywhere. Never call
+a chain launch-ready because its RPC responds.
+
+Oracle researches, scaffolds, validates, simulates, and prepares unsigned actions.
+The user signs deployment, mint, metadata, authority, liquidity, and verification
+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.
+
+## Support status language
+
+Use exactly one status before building:
+
+| Status | Meaning |
+|---|---|
+| `TEMPLATE_READY` | Oracle ships a gated template and unsigned prepare path for this exact standard. |
+| `ADAPTER_READY` | A chain-specific encoder exists and passed live simulation or testnet verification. |
+| `GUIDED_BUILD` | Oracle can scaffold and test it, but no generic transaction adapter is shipped. |
+| `RESEARCH_ONLY` | Oracle can verify chain mechanics and produce a launch plan, not a deployable bundle. |
+| `UNSUPPORTED` | Required chain primitives or trustworthy tooling cannot be verified. Stop. |
+
+Do not upgrade a status without evidence. A compiler pass alone is not
+`ADAPTER_READY`. A mainnet-ready claim needs exact chain identity, final artifacts,
+simulation, fee estimate, and source/program verification path.
+
+## Current family matrix
+
+| Family | Common standards | Default status | Required path |
+|---|---|---|---|
+| EVM | ERC-20 | `TEMPLATE_READY` only for Oracle `safe-erc20`; custom tax, mint, proxy, or hook designs are `GUIDED_BUILD` | Foundry gate, chain-id proof, unsigned deploy, source verification |
+| Solana | SPL Token, Token-2022 | `GUIDED_BUILD` | Select extensions explicitly, construct unsigned transactions, simulate, user wallet signs |
+| Bitcoin | Runes | `RESEARCH_ONLY` until an etch adapter is present | Commit/reveal plan, UTXO and fee model, exact terms review |
+| Cosmos | tokenfactory, CW20 | `RESEARCH_ONLY` by default | Resolve the chain's module or CosmWasm messages; EVM-enabled Cosmos chains use the EVM path only when verified |
+| Sui | Coin, regulated coin primitives | `RESEARCH_ONLY` by default | Move package, treasury capability model, devnet/testnet publish first |
+| Aptos | Coin, Fungible Asset | `RESEARCH_ONLY` by default | Move module/object model, upgrade policy, testnet publish first |
+| Hyperliquid L1 | spot asset deployment | `RESEARCH_ONLY` | Verify current native deployment/auction process; HIP-3 is a market deployment, not a generic token contract |
+| HyperEVM | ERC-20 | EVM status | Use the exact HyperEVM chain id and verified gas/DEX addresses |
+| Other | chain-native | `UNSUPPORTED` until classified | Add and verify a dedicated adapter before preparing transactions |
+
+This matrix is the minimum truth bar, not a marketing ceiling. If a verified adapter
+lands later, update its status with tests and evidence.
+
+## 1. Build the launch manifest
+
+Do not write code until all required fields are known:
+
+```yaml
+asset:
+  name: ""
+  symbol: ""
+  chain_family: ""
+  chain_name: ""
+  chain_id_or_genesis: ""
+  network: mainnet|testnet|devnet|local
+  standard: ""
+  decimals: null
+  max_supply: ""
+  initial_supply: ""
+  allocation:
+    treasury: ""
+    public: ""
+    liquidity: ""
+    team: ""
+    community: ""
+authorities:
+  mint: none|wallet|multisig|timelock|program
+  freeze: none|wallet|multisig|timelock|program
+  pause: none|wallet|multisig|timelock
+  upgrade: none|wallet|multisig|timelock
+  metadata: immutable|wallet|multisig|timelock
+mechanics:
+  transfer_tax_bps: 0
+  blacklist: false
+  transfer_hook: none
+  sale: none
+  liquidity: none
+verification:
+  source: required
+  simulation: required
+  firm_audit: false
+```
+
+Reject ambiguous supply units. Record raw base units and human-readable units.
+Percent allocations must total 100 percent before deploy preparation.
+
+## 2. Verify the chain, standard, and tooling
+
+1. Resolve the exact chain identity from a live RPC or official client.
+2. Verify native gas asset, address format, finality model, fee fields, explorer,
+   compiler/toolchain version, and source/program verification mechanism.
+3. Verify the intended standard from official chain or standards documentation.
+4. Prefer a boring official or widely reviewed implementation.
+5. Record every external factory, router, program, module, and metadata endpoint.
+6. Mark unverified addresses and deprecated tooling `UNSUPPORTED`, not best effort.
+
+Chain names are not identities. `mainnet`, `testnet`, and forks must carry distinct
+IDs and RPC evidence.
+
+## 3. Force an authority decision
+
+Before generating transactions, print a table for:
+
+- mint or treasury capability
+- freeze or deny-list capability
+- pause capability
+- upgrade authority
+- metadata authority
+- fee/tax setter
+- transfer-hook owner
+- sale contract owner
+- liquidity position owner
+- treasury and royalty recipients
+
+For each authority, state who holds it at creation, whether it can change, the
+transfer/revoke transaction, and what breaks if revoked.
+
+Defaults:
+
+- fixed supply when future minting is not a product requirement
+- no transfer tax
+- no blacklist
+- no proxy upgradeability
+- no hidden owner balance changes
+- multisig or timelock for powers that must remain
+- revoke only after verification and launch operations that need the authority
+
+Never claim "renounced" until independent on-chain read-back proves it.
+
+## 4. Family-specific build paths
+
+### EVM
+
+For a plain fixed-supply token, use Oracle's gated template:
+
+```js
+data.call("protocol-templates", "gate", { templateId: "safe-erc20" })
+data.call("protocol-templates", "prepareDeploy", {
+  templateId: "safe-erc20",
+  chainId,
+  args: [name, symbol, supply, initialHolder, initialOwner],
+})
+```
+
+Required gates:
+
+1. Verify chain id and RPC reality.
+2. `forge test` passes.
+3. Static analysis runs when available.
+4. Constructor units and addresses decode back exactly.
+5. Dry-run deployment succeeds on the target chain fork when archive state exists.
+6. Unsigned deploy is stamped; source verification input is prepared separately.
+7. Liquidity and ownership changes remain separate unsigned actions.
+
+Any custom minting, tax, blacklist, transfer hook, proxy, permit, votes, vesting, or
+cross-chain bridge logic leaves `safe-erc20` and becomes a custom `GUIDED_BUILD`.
+Do not silently bolt features onto the reviewed template.
+
+### Solana
+
+Choose standard SPL Token unless a specific Token-2022 extension is required.
+For Token-2022, enumerate every selected extension and its authority, including
+transfer fees, permanent delegate, transfer hook, default account state, metadata
+pointer, interest bearing, confidential transfer, and non-transferable behavior.
+
+Prepare distinct unsigned transactions for:
+
+1. create mint account and initialize mint
+2. create metadata when used
+3. create distribution token accounts
+4. mint initial supply
+5. transfer or revoke mint authority
+6. transfer or revoke freeze authority
+7. create sale or liquidity positions, only if separately approved
+
+Simulate each transaction against the intended cluster. A blockhash-expired result
+must be rebuilt, never manually edited.
+
+### Bitcoin Runes
+
+A Rune launch is an etching, not a smart-contract deployment. Collect and print:
+
+- rune name and spacers
+- divisibility and symbol
+- premine
+- mint amount and cap
+- start and end heights or offsets
+- turbo flag
+- commit UTXO, reveal destination, fee rate, and expected total fees
+
+Prepare commit/reveal artifacts only through a verified adapter. Protect the commit
+UTXO from accidental spend, account for the reveal window and reorg risk, and never
+promise an indexer ticker reservation before the etching confirms. Without an
+adapter, status stays `RESEARCH_ONLY`.
+
+### Cosmos
+
+First determine whether the target uses a native tokenfactory module, CosmWasm
+CW20, or an EVM runtime. These are different launch paths.
+
+- tokenfactory: verify denom creation, mint, burn, admin-change, and metadata message
+  types from that chain's running version
+- CW20: compile and test the exact contract artifact, instantiate message, minter
+  model, marketing info, and migration admin
+- EVM runtime: use the EVM path only after proving chain id and JSON-RPC behavior
+
+Never transplant Osmosis, Injective, Sei, or another chain's message type by name.
+
+### Sui and Aptos
+
+Sui and Aptos need separate Move packages and authority models. Do not share source
+because both languages are called Move.
+
+- Sui: identify one-time witness, treasury capability, metadata/display objects,
+  deny-list or regulated-coin powers, package upgrade policy, and object ownership
+- Aptos: choose Coin or Fungible Asset, define mint/burn/freeze capability objects,
+  metadata object, store model, and module upgrade policy
+
+Publish and exercise the full lifecycle on devnet/testnet first. Mainnet remains
+`RESEARCH_ONLY` until the exact package and publish transaction pass review.
+
+### Hyperliquid
+
+Do not conflate HIP-3 builder-deployed perp markets, HIP-1 or native spot assets,
+HyperEVM ERC-20s, and HIP-4 outcomes. Route HyperEVM assets to EVM. For Hyperliquid
+L1 native assets, verify current official deployment, auction, genesis allocation,
+and deployer requirements before naming a prepare path. Without a dedicated native
+adapter, status is `RESEARCH_ONLY`.
+
+## 5. Distribution, sale, and liquidity are separate actions
+
+Token creation does not authorize a sale or pool. For each follow-on action, show:
+
+- destination contract/program/module
+- token and quote amounts
+- opening price and implied fully diluted value
+- slippage and deadline
+- LP ownership, lock, burn, or withdrawal rights
+- treasury recipient
+- vesting terms and clawback/admin powers
+- simulation and fee estimate
+
+Verify DEX factories and routers on the exact chain. A canonical address on Ethereum
+is not canonical on a sibling EVM chain.
+
+Never auto-create liquidity after deployment. Never auto-revoke authority before
+metadata, distribution, or verification actions that need it are complete.
+
+## 6. Required artifacts
+
+A completed prepare run returns:
+
+1. `launch-manifest.yaml` with exact units and chain identity
+2. authority and mutability table
+3. source/package hash and dependency lock
+4. test and static-analysis results
+5. target-chain simulation or an explicit reason it is unavailable
+6. fee and balance estimate
+7. ordered unsigned transaction bundle with hashes
+8. source/program verification payload
+9. separate liquidity/distribution bundle when requested
+10. a final user approval checklist, one side effect per line
+
+Do not emit a signed payload, private key request, seed phrase request, or broadcast
+command with signing enabled.
+
+## Refusals
+
+Refuse hidden minting, honeypots, selective sell blocks, fake renouncement, covert
+taxes, wash liquidity, fake volume, stolen upgrade keys, undisclosed permanent
+delegates, and misleading supply claims.
+
+## Completion gate
+
+A launch is only `PREPARED` when:
+
+- chain and standard are exact
+- support status is honest
+- supply and allocation reconcile
+- all authorities are disclosed
+- tests pass
+- simulation passes or the missing capability is explicit
+- every destination and payload hash is recorded
+- no signing or broadcast occurred
+
+Anything less is `DRAFT`, `RESEARCH_ONLY`, or `UNSUPPORTED`.

package/dist/assets/skills/oracle-nft-gacha-launch/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: oracle-nft-gacha-launch
+description: Use when designing or preparing NFT collections, mint pages, reveal mechanics, and gacha-style pack/loot drops.
+---
+
+# NFT and gacha launch builder
+
+Use this when a user wants to launch an NFT collection, pack opening, loot box,
+claim pass, or randomized reveal product.
+
+## Product shape first
+
+State the launch mechanics before code:
+
+- asset standard: ERC-721, ERC-1155, Ordinals collection, SPL/NFT, or hybrid
+- supply, per-wallet caps, allowlist/public phases, price, treasury, royalties
+- reveal style: instant, delayed, commit-reveal, VRF-backed, or fully deterministic
+- pack/gacha odds and whether duplicates are possible
+- admin powers: owner, pauser, metadata updater, withdrawer, upgrader
+
+## Safety rails
+
+- User signs every deploy/mint/admin transaction; Oracle prepares and simulates.
+- Randomness must be honest. Do not use miner/block timestamp as gacha randomness.
+- Publish odds for gacha/loot mechanics and keep them deterministic/auditable.
+- No hidden mint, owner reroll, metadata rug, or unbounded treasury withdrawal.
+- Per-wallet caps and phase windows are enforced on-chain when material.
+- Marketplaces are secondary: floor price is not a guaranteed bid.
+- Public mint bots enforce gas-war limits across chains: total gas cap, optional
+  per-unit fee cap, and optional priority-fee cap before returning unsigned
+  mint calldata. Missing caps fail closed.
+
+## Build checklist
+
+1. Choose the boring audited base contract unless novelty is required.
+2. Write the authority model in plain language.
+3. Add tests for mint limits, payment/refund, reveal, withdraw, and admin changes.
+4. Simulate deploy and first mint before returning unsigned transactions.
+5. Produce metadata schema, asset pipeline, and provenance hash/manifest.
+6. Prepare marketplace setup only after contract addresses and metadata are stable.
+
+## Gacha-specific checks
+
+- Show odds table and expected value in user terms.
+- Cap max spend per wallet/session.
+- Separate entertainment mechanics from investment claims.
+- If jurisdictional gambling risk is plausible, flag it and keep the launch
+  non-custodial/transparent rather than pretending it is just an NFT mint.

package/dist/assets/skills/oracle-nft-mint-gas-war/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: oracle-nft-mint-gas-war
+description: Guard public NFT mint bots with chain-wide gas-war caps before any wallet-signed mint transaction is returned.
+---
+
+# Oracle NFT mint gas-war guard
+
+Use when a public Oracle lane prepares NFT mint transactions or runs a mint bot
+across configured chains.
+
+## Rule
+
+A mint bot may move fast, but it must not bid uncapped gas.
+
+Every prepared mint transaction must carry a gas envelope that fits the user's
+explicit grant or bot policy:
+
+- `maxTotalGasWei` / grant `maxGasWei`: total gas spend cap (`gasLimit * maxFeePerGas` or `gasLimit * gasPrice`)
+- optional `maxFeePerGasWei`: per-unit fee cap
+- optional `maxPriorityFeePerGasWei`: tip cap for gas wars
+- chain id: required and bound to the prepared transaction
+
+Missing caps fail closed. A mint returning calldata without gas caps is not
+public-safe.
+
+## Implementation hook
+
+Use `validateNftMintGasWar()` or `assertNftMintGasWar()` from the public package
+before returning a wallet-signable NFT mint transaction.
+
+```js
+import { assertNftMintGasWar } from "oracle-agent";
+
+assertNftMintGasWar({
+  chainId,
+  tx: { gasLimit, maxFeePerGas, maxPriorityFeePerGas },
+  policy: {
+    grant, // may provide maxGasWei
+    maxFeePerGasWei,
+    maxPriorityFeePerGasWei,
+  },
+});
+```
+
+## Public behavior
+
+- PASS: return the unsigned mint transaction with the gas verdict fields.
+- BLOCK: show the cap breached and ask the user to raise the cap or skip.
+- Never silently widen gas during a gas war.
+- Never treat mint price cap as gas cap; mint value and gas spend are separate.
+- Never backend-sign public mints. User wallet or explicit self-hosted session
+grant signs.
+
+## Verification
+
+Run:
+
+```bash
+node --test test/nft-gas-war-guard.test.mjs test/package-surface.test.mjs
+```
+
+Full public release gate still requires `npm test`, package dry-run, and secret
+scan before publishing.

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

@@ -0,0 +1,60 @@
+---
+name: oracle-polymarket
+description: Use for Polymarket prediction markets — event pricing, books, and resolution risk via the public CLOB and Gamma APIs.
+---
+
+# Polymarket
+
+Read through Oracle's data plane (`poly-public` provider: CLOB + Gamma REST, no
+key). Settles on Polygon (137).
+
+## Ops
+
+| Need | Op |
+|---|---|
+| market list | `markets` |
+| events | `events` |
+| order book | `book` |
+| midpoint | `midpoint` |
+| spread | `spread` |
+| last price | `price` |
+
+## A price is not a probability
+
+0.62 means the last trader transacted there — net of fees, liquidity constraints,
+and whoever is hedging an off-platform position. Before treating it as a forecast:
+
+- **depth** — 0.62 on $40 of size carries no information
+- **spread** — wide means nobody defends an opinion
+- **time to resolution** — a 3-day market and a 3-month market at the same price
+  are not saying the same thing
+- **fee drag** — round-trip costs eat thin edges
+
+## Resolution text is the real risk
+
+The most expensive mistake here is not mispricing probability. It is being *right*
+about the world and *wrong* about the resolution criteria.
+
+Read the rules before discussing edge. Flag:
+
+- ambiguous wording that could settle against the consensus reading
+- who resolves it and on what source
+- what happens on an edge case, a delay, or a cancelled event
+- whether the market can resolve early
+
+If the rules could plausibly settle the "obviously right" side as a loss, that is
+the headline, not a footnote.
+
+## Correlated markets
+
+Related markets often disagree. A set of outcome prices summing well past 1.00 is
+either a fee/liquidity artifact or a genuine inconsistency. Check the sum before
+calling something mispriced.
+
+## Hard rules
+
+1. Read the resolution criteria before discussing edge.
+2. Never present a market price as your own forecast without saying which you mean.
+3. Quote depth alongside price.
+4. You prepare; the user's wallet signs.
+5. Receipts or it didn't happen.

package/dist/assets/skills/oracle-protocol-builder/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: oracle-protocol-builder
+description: Use when the user wants Oracle to scaffold/deploy protocol templates. Gated Foundry templates; prepare-only deploy; not a firm audit.
+---
+
+# Protocol builder
+
+Oracle scaffolds and **prepares unsigned deploys**. The user signs. Custody boundary unchanged.
+
+## Security gate (v1)
+
+Before any template deploy prepare:
+
+1. `forge test` must pass on the template
+2. Slither runs when installed (optional skip if missing; set `REQUIRE_SLITHER=1` to hard-require)
+3. JS `runProtocolTemplateGate` / `prepareTemplateDeploy` refuse otherwise
+
+```js
+// list
+data.call("protocol-templates", "list")
+// gate
+data.call("protocol-templates", "gate", { templateId: "safe-erc20" })
+// unsigned deploy prepare (stamped)
+data.call("protocol-templates", "prepareDeploy", {
+  templateId: "safe-erc20",
+  chainId: 8453,
+  args: [name, symbol, supply, initialHolder, initialOwner],
+})
+```
+
+CLI: `npm run protocol:gate -- safe-erc20`
+
+## Shipped template: `safe-erc20`
+
+- Fixed supply, mint once in constructor (no hidden mint)
+- Ownable2Step + pause
+- No tax / blacklist / max-tx / upgrade proxy
+- Foundry tests included
+
+## Honesty
+
+**Reviewed templates + automated tests ≠ paid Solidity audit.**
+
+Docs and prepare envelopes always set `firmAudit: false` and carry the disclaimer.
+Mainnet TVL → independent firm audit.
+
+## Required order (custom work)
+
+1. Authority model  
+2. Threat model  
+3. Tests (Foundry)  
+4. Static analysis when available  
+5. Gate green  
+6. Prepare unsigned only  
+7. User signs + verify source  
+
+## Refusal line
+
+Refuse hidden drains, honeypots, wash-trading systems, undisclosed tax switches, fake TVL, or any contract whose main purpose is deceiving buyers.

package/dist/assets/skills/oracle-protocol-security/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: oracle-protocol-security
+description: Use before preparing any contract deploy or reviewing protocol code. Authority model first, then the vulnerability checklist.
+---
+
+# Protocol security
+
+Deploys are permanent. This skill runs **before** code is written, not after.
+
+## Authority model comes first
+
+Before reviewing a single line of logic, answer these in plain language:
+
+1. **Who owns it** after deployment — owner, admin, upgrader, pauser, treasury
+2. **What is upgradeable**, and who can upgrade
+3. **What is immutable** once live
+4. **What breaks if the deployer key is lost** — or is stolen
+5. **What an attacker gains** from each privileged function
+
+If a contract mints privileged roles to an address, **name that address** and make
+the user confirm it is the intended one. A deploy that hands ownership to the wrong
+key is unrecoverable.
+
+## Review checklist
+
+| Area | What to actually check |
+|---|---|
+| access control | every privileged fn gated; no missing modifier |
+| initialization | can `initialize` be front-run or called twice? |
+| reentrancy | state written *before* external calls |
+| external calls | return values checked; no blind `call` |
+| integer handling | unchecked blocks justified individually |
+| approvals | exact amount, never unlimited by default |
+| upgrade path | storage layout compatible; gap reserved |
+| emergency stop | exists, and someone can actually reach it |
+| oracle use | manipulation cost vs the value it secures |
+| withdrawal | can funds ever be stranded? |
+
+## Prefer boring
+
+A fork of an audited contract with a small, reviewed diff beats elegant clean-room
+code. If you propose something novel, justify why the boring option fails.
+
+## Verify, never assume
+
+- Explorer contract **names are not verification**. Clones share names.
+- Confirm bytecode exists: `eth_getCode` returning `0x` means nothing is deployed
+  there. Codesize 2 is an empty stub.
+- Confirm constructor-bound addresses (factory, WETH, router) match what you
+  expect — read them back from the deployed contract.
+- Verify a router or venue from the protocol's **own API or docs**, per chain, and
+  record how and when you verified it.
+
+## Deploy discipline
+
+Review → simulate → prepare **unsigned** → user signs. Never house-sign. The
+destination allowlist applies to deploy targets like any other destination.
+
+Decode constructor arguments and read them back to the user in plain language
+before they sign. "Trust the calldata" is not consent.

package/dist/assets/skills/oracle-public-product/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: oracle-public-product
+description: Use for Oracle public product UX/copy: non-custodial, prepare-first, graph/evidence-led, no operator framing.
+---
+
+# Oracle public product
+
+Use this when writing Oracle public docs, console copy, landing pages, launch notes,
+or capability-pack language.
+
+## Positioning
+
+Oracle is a public multichain crypto agent interface:
+
+- trader: quote, route, simulate, prepare, and verify receipts
+- builder: scaffold contracts/apps and prepare unsigned deploy/admin txs
+- analyzer: token, contract, venue, wallet, and market research
+- scanner: chain scanners and smart-wallet boards
+- non-EVM lanes: Solana and Bitcoin/Ordinals where supported
+
+The product voice is user-facing. Do not describe internal operator plumbing,
+private wallets, VPS paths, hot-wallet ops, or house execution.
+
+## Custody copy
+
+Always state the invariant clearly:
+
+- Oracle prepares; the user's wallet signs.
+- Broadcast needs explicit user/grant authority.
+- Prepare is not sign. Sign is not broadcast.
+- Server API keys are scoped agent keys, not wallet keys.
+
+## Forbidden public framing
+
+- no autonomous custody promises
+- no hidden operator signer references
+- no guaranteed-profit or floor-guarantee claims
+- no "we execute for you" without the grant/user-wallet boundary
+- no references to private infrastructure, hostnames, paths, or internal agents
+
+## Output standard
+
+Lead with what the user can do. Then name the guardrail. Keep it concrete and
+short: capability, boundary, evidence.

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

@@ -0,0 +1,52 @@
+---
+name: oracle-receipts
+description: Use whenever reporting the outcome of any on-chain action. Enforces that a claim of success carries a hash, a receipt, and a balance delta.
+---
+
+# Receipts or it didn't happen
+
+The failure mode this prevents: an agent says "done, swapped 0.5 ETH for USDC" when
+the transaction reverted, was never broadcast, or landed with a different output
+than promised. The user then acts on a false balance.
+
+## The rule
+
+A money-moving action is **complete** only when you can show:
+
+1. **transaction hash** — the real one, from the broadcast response
+2. **receipt status** — `1`. A receipt with status `0` is a *failed* transaction
+   that still consumed gas; that is not success
+3. **balance delta** — the output token balance actually changed, read back after
+   the receipt
+4. **the log** proving the intended event fired (`Swap`, `Transfer` to the right
+   recipient, `OrderFilled`)
+
+Missing any of the four → report what you have and call it incomplete.
+
+## Language discipline
+
+| Don't say | Say |
+|---|---|
+| "swapped" (before receipt) | "prepared" / "broadcast, awaiting receipt" |
+| "done" | "receipt 1, balance +NNN USDC, hash 0x..." |
+| "it should have gone through" | "unknown — no receipt yet" |
+| "approved and swapped" | name each transaction separately |
+
+**Preparing is not signing. Signing is not broadcasting. Broadcasting is not
+confirmation.** Four distinct states; never collapse them in a report.
+
+## Multi-step actions
+
+An ERC-20 swap is at minimum two transactions: `approve` then the swap. Report each
+separately with its own hash. If the approve landed and the swap reverted, the
+honest report is "allowance set, swap failed" — not "swap failed" (the user now has
+a live allowance they should know about).
+
+For a raw-pair or multi-leg route: funding a pool is **not** a buy. Until the swap
+call itself has a receipt, the tokens are sitting somewhere they can be taken.
+
+## When it fails
+
+Say what failed, the revert reason if you have it, and what you tried. Never
+substitute a plausible-looking result for one you could not obtain. A reported
+blocker is useful; an invented success is a loss.