@oracle-agent/oracle 0.13.1 → 0.14.1

package/CONTRIBUTING.md

@@ -0,0 +1,99 @@
+# Contributing to Oracle
+
+Thanks for looking. Oracle is a control plane for money movement, so the review
+bar is about safety and honesty more than style.
+
+## Before you start
+
+Run the suite:
+
+```bash
+npm install
+npm test
+```
+
+`test-baseline.json` records the current suite count and `npm run test:count`
+prevents silent test loss. A failure on a clean checkout is a bug; report it
+with the exact command output.
+
+## The one rule that matters
+
+**The public plane may never reach a private key or a house signer.**
+
+Oracle ships the data plane, the policy plane, and the control plane. It does not
+ship the executor. A PR that imports signer or keystore code into public modules
+will fail `test/custody-boundary.test.mjs`, and the fix is not to edit the
+forbidden list.
+
+If your feature seems to need a key, restructure it: build an unsigned
+transaction or a typed-data intent and hand it back to the caller to sign.
+
+## What we want
+
+- **Real bugs, fixed at the class level.** Reproduce it, point at the line, fix
+  every sibling call path — not just the one that was reported.
+- **New chains and providers.** This is the most useful contribution. See below.
+- **Honest capability tiers.** If a provider can only quote, mark it
+  `quote-only`. Do not mark it `prepare` because a prepare function exists but
+  was never validated against a live route.
+- **Tests that assert invariants**, not snapshots. `assert` that a minimum output
+  is enforced; don't freeze today's provider list into an equality check.
+- **Guards recomputed before signing.** A quote-time check that isn't re-verified
+  at broadcast is decoration.
+
+## What gets rejected
+
+- A signer, private key, or house-custody path in the public tree.
+- A destination allowlist that defaults to permissive, or an empty allowlist read
+  as "allow all."
+- Slippage widened past the 100 bps cap to make a trade go through. Block,
+  requote, or split instead.
+- A claim of execution support with no live prepare/simulate evidence.
+- Secrets in code, tests, fixtures, or docs — including a real wallet address as
+  a default `from` for quotes. Use `src/data/quote-placeholder.mjs`.
+- "It worked when I ran it" with no test.
+
+## Adding a provider
+
+1. Create `src/data/providers/<name>.mjs`.
+2. Export a `health()` plus the ops you actually implement.
+3. Register it in `src/data/catalog.mjs` with truthful `chainIds`, `auth`, `ops`,
+   and `execution` tier.
+4. Add a test with a mocked transport. Do not require a live network for CI.
+5. If it needs a key, the health check must report
+   `{ ok: false, configured: false }` rather than throwing.
+
+## Adding a chain
+
+1. Add an entry to `CHAINS` in `src/chains.mjs` with its `rpcEnv` names.
+2. Verify every router/venue address on-chain (`eth_getCode` must return real
+   bytecode) before adding it to `src/venues.mjs`.
+3. Comment each venue addition with how you verified it and when.
+4. An unverified chain stays fail-closed. That is a safe state, not a gap.
+
+Never allowlist a router you found only in a blog post or a model's answer. The
+destination allowlist is the highest-leverage control in the system.
+
+## Commits and PRs
+
+Conventional prefixes: `fix:`, `feat:`, `refactor:`, `docs:`, `test:`, `chore:`.
+
+In the PR body, state:
+
+- what broke or what's new
+- how you verified it (paste the real command output)
+- whether anything touches the custody boundary
+
+Small, reviewable PRs get merged. A 3000-line PR mixing a refactor with a policy
+change will sit.
+
+## Style
+
+- ES modules, Node 20+, no build step.
+- No new runtime dependency without a reason in the PR description.
+- Comments explain *why*, not *what*. If a line encodes a hard-won fact — a
+  provider's unit quirk, a revert cause — say so, and say how it was learned.
+
+## License
+
+Contributions are accepted under the repository's then-current outbound license in [LICENSE](LICENSE). Current source is BUSL-1.1; npm releases `0.1.0` through `0.11.0` remain Apache-2.0.

package/README.md

@@ -3,11 +3,7 @@
 ## Quickstart (standalone CLI)
 
 ```bash
-# Oracle is distributed to Locals Only holders. Prove ownership at the gate,
-# then install the artifact it returns:
-oracle gate status                                  # if you already have a build
-curl -fL -o oracle.tgz "$ORACLE_GATE_LINK" && npm i -g ./oracle.tgz
-# Node >= 20.19
+npm i -g @oracle-agent/oracle            # Node >= 20.19
 oracle --version
 oracle auth login claude               # or codex / grok
 oracle                                  # native Oracle chat
@@ -18,6 +14,13 @@ Prefer an API key instead? `oracle auth api-key openrouter` accepts hidden
 interactive input. `oracle auth status` reports providers without printing
 credentials. Linux, Windows, and macOS apps are in beta.
 
+The CLI, source, and desktop beta are public to everyone. Locals Only holders
+receive a 0% Oracle integrator fee; the NFT does not gate product access.
+
+Hyperliquid perp orders disclose Oracle's 5 bps builder code. The exact address,
+approval flow, wire units, and separation from the Locals Only waiver are documented in
+[Hyperliquid builder code](docs/hyperliquid-builder-code.md).
+
 
 **Prepare-only multichain agent control plane.** Policy-bounded intents; your wallet signs.
 
@@ -37,7 +40,7 @@ private `0600` local fallback when keychain storage is unavailable.
 
 This package is **prepare-only**: it never takes a private key and never
 broadcasts. The owner-operated signer/executor is private infrastructure, is
-not published on npm, and is not part of holder onboarding. Never paste a seed,
+not published on npm, and is not part of public onboarding. Never paste a seed,
 private key, vault passphrase, or signer token into Oracle chat.
 
 ---
@@ -71,7 +74,7 @@ const prepared = await data.call("hl-perps", "prepareOrder", {
 ```
 
 See [SETUP.md](SETUP.md) for clean installation and troubleshooting,
-[docs/holder-beta.md](docs/holder-beta.md) for the Locals-only launch gate, and
+[docs/locals-only-fee-waiver.md](docs/locals-only-fee-waiver.md) for the 0% holder fee, and
 [docs/buzz-integration.md](docs/buzz-integration.md) for the Buzz HTTP contract.
 
 ---
@@ -181,12 +184,11 @@ oracle-scan risk  base 0x8335...2913  # structural checks + sell simulation
 oracle-scan sell  base 0x8335...2913  # round trip: can you actually exit?
 ```
 
-**8 of 11 chains ship verified venues**: Ethereum, Optimism, BNB, Polygon, Base,
-Arbitrum, Avalanche, and Robinhood Chain. They have all 10 capabilities including
-live quotes, round-trip sell simulation, and unsigned swap preparation. The remaining
-three (Stable, HyperEVM, Abstract) are at 7 and **fail-closed for routing value** until
-someone verifies a venue: read and research work, moving money does not. That is a safe
-default, not a gap.
+All 11 built-in EVM chains currently report the full 10-capability scanner
+matrix, including live quote, sell simulation, and unsigned preparation where
+the selected provider supports that operation. Capability coverage is not a
+claim that every protocol supports every action; unsupported paths still fail
+closed.
 
 Every venue address was verified **functionally, not by codesize** — a re-runnable
 prober (`scripts/verify-v3-venues.mjs`) asks each candidate to price a pair with a
@@ -262,8 +264,12 @@ capability-labeled per chain; unconfigured venues stay unavailable instead of fa
 
 ## Install
 
+Install the full public package from npm, or use the public desktop downloads at
+https://oracle.demi.la/downloads/. No wallet or NFT is required. Node `20.19.0`
+or newer is required for the CLI.
+
 ```bash
-npm install @oracle-agent/oracle    # Node >= 20.19.0
+npm i -g @oracle-agent/oracle
 ```
 
 Or from source, if you want to run the suite:

package/SECURITY.md

@@ -27,8 +27,7 @@ In scope:
 - grant forgery, replay, or scope escalation
 - route/vault/order attestation forgery
 - secret leakage through an API response or log
-- holder-gate bypass, challenge replay, or cross-user data access in an official
-  hosted beta
+- fee-waiver misclassification or cross-user data access in an official hosted service
 - Buzz capability forgery or audit-chain tampering
 
 Out of scope:
@@ -56,9 +55,8 @@ Consequences of that assumption, which are the invariants worth attacking:
    targets require an attestation minted inside the trusted boundary.
 5. **Guards are recomputed at sign and broadcast time**, not just at quote time,
    because a stale minimum is not a minimum.
-6. **The shipped public HTTP server is not a holder-authentication service.** It
-   is loopback-only and rate limited, but unauthenticated. A hosted Locals beta
-   needs a separate server-side ownership gate and per-user isolation.
+6. **The shipped public HTTP server is unauthenticated.** It is loopback-only and
+   rate limited. A hosted service needs ordinary authentication and per-user isolation.
 
 If you find a path where model-authored text becomes an authorized on-chain
 action without an owner signature and a policy check, that is the bug we most
@@ -109,6 +107,6 @@ still apply after the public boundary hardening:
    secret scanning depend on repository visibility and account tier. Verify the
    live settings; do not infer them from this document. The local CI boundary,
    packed-artifact, and secret-scan gates remain mandatory.
-8. **Holder admission is deployment code.** The npm package does not prove
-   Locals ownership or isolate hosted tenants. See
-   [docs/holder-beta.md](docs/holder-beta.md) before exposing any shared surface.
+8. **Locals Only is fee policy, not admission.** Oracle access is public. The NFT
+   only waives Oracle's integrator fee; hosted user isolation remains a separate
+   deployment responsibility.

package/SETUP.md

@@ -5,7 +5,7 @@ research, quote, simulate, and build unsigned artifacts. It does not need Hermes
 it does not accept wallet private keys, and it does not broadcast transactions.
 
 The owner-operated signer/executor is private infrastructure. It is not published
-on npm and is not part of public or holder onboarding.
+on npm and is not part of public onboarding.
 
 ## Requirements
 
@@ -19,21 +19,18 @@ Linux, Windows, and macOS apps are in beta.
 ## 1. Install the standalone CLI
 
 ```bash
-npm view @oracle-agent/oracle version
-# Oracle is distributed to Locals Only holders. Prove ownership at the gate,
-# then install the artifact it returns:
-oracle gate status                                  # if you already have a build
-curl -fL -o oracle.tgz "$ORACLE_GATE_LINK" && npm i -g ./oracle.tgz
+npm i -g @oracle-agent/oracle
 oracle --version
 ```
 
-The npm `latest` tag is the install source of truth. The repository can contain
-an unreleased next version, so do not infer the published version from a branch.
+npm `latest` is the public CLI installation source of truth. Locals Only
+ownership is not required to install or use Oracle; holders receive a 0% Oracle
+integrator fee.
 
 For a project-local library install instead:
 
 ```bash
-npm i @oracle-agent/oracle@latest
+npm i @oracle-agent/oracle
 ```
 
 The package declares this floor through `engines`; `oracle doctor` treats an
@@ -146,11 +143,9 @@ The public plane binds to `127.0.0.1` and exposes read, connect, grant,
 portfolio, approval, prepare, Buzz-auth, and audit contracts. It has no signer,
 key, send, execute, or broadcast route.
 
-The service is rate limited but unauthenticated. It is **not** a Locals-holder
-gate and must not be exposed directly to the internet, LAN, or tailnet. A hosted
-deployment needs a controlled reverse proxy, TLS, edge limits, and the
-server-side holder gate described in
-[holder-beta.md](docs/holder-beta.md).
+The service is rate limited but unauthenticated and must not be exposed directly
+to the internet, LAN, or tailnet. A hosted deployment needs a controlled reverse
+proxy, TLS, edge limits, authentication, and per-user isolation.
 
 Verify liveness only after starting it:
 
@@ -171,9 +166,8 @@ oracle setup gateway start
 ```
 
 Interactive bot-token entry is hidden. Do not use `--token` in a normal shell;
-arguments can be retained in history or visible to other local processes. For a
-holder beta, do not run one shared messaging bot without a separate holder
-admission layer and per-user session isolation.
+arguments can be retained in history or visible to other local processes. Do not
+run one shared messaging bot without authentication and per-user session isolation.
 
 ## Public wallet addresses and portfolio reads
 
@@ -211,15 +205,19 @@ expiry, approvals, and fees in the user's wallet. Oracle's public package stops
 before signing. Report success only after a real transaction hash, successful
 receipt, and expected balance or state change.
 
-## Locals-only holder beta
+## Locals Only fee waiver
 
-Current release status is **HOLD for a holder-gated hosted launch**. The package
-is safe to distribute for local read/research/prepare use, but this repository
-does not contain an integrated Locals ownership gate. UI hiding, a wallet text
-field, or possession of a URL is not access control.
+Oracle access is public. A Locals Only NFT only waives Oracle's integrator fee.
+Use `oracle fees status` to check the configured wallet. See
+[locals-only-fee-waiver.md](docs/locals-only-fee-waiver.md).
 
-Do not invite holders to a hosted surface until every required gate in
-[holder-beta.md](docs/holder-beta.md) passes.
+## Hyperliquid builder code
+
+Eligible Hyperliquid perp orders disclose the separate 5 bps builder code before
+wallet review, including orders prepared for Locals Only holders. The Locals Only
+waiver does not waive the Hyperliquid builder fee. The main wallet must separately
+sign the revocable maximum-fee approval; Oracle only prepares that action. See
+[hyperliquid-builder-code.md](docs/hyperliquid-builder-code.md).
 
 ## Buzz integration
 
@@ -241,12 +239,12 @@ A clean standalone install can legitimately show warnings for:
 - `hermes_lanes` before optional `oracle init --apply`.
 
 A Node-version failure is blocking. Signing warnings are irrelevant to the
-public holder path because signing is not installed there.
+public package because signing is not installed there.
 
 ## Upgrade
 
 ```bash
-curl -fL -o oracle.tgz "$ORACLE_GATE_LINK" && npm i -g ./oracle.tgz
+npm i -g @oracle-agent/oracle@latest
 oracle --version
 oracle doctor
 ```
@@ -313,7 +311,7 @@ as a workaround.
 
 - [CLI reference](docs/cli.md)
 - [Public API and environment surface](docs/public-surface.md)
-- [Locals-holder beta launch gate](docs/holder-beta.md)
+- [Locals Only 0% fee waiver](docs/locals-only-fee-waiver.md)
 - [Buzz integration](docs/buzz-integration.md)
 - [Architecture](docs/architecture.md)
 - [Security policy](SECURITY.md)