@oracle-agent/oracle 0.12.0 → 0.13.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +13 -498
- package/bin/oracle.mjs +25 -0
- package/package.json +16 -61
- package/SECURITY.md +0 -114
- package/SETUP.md +0 -316
- package/artifacts/inscription/oracle-was-here-preview.png +0 -0
- package/artifacts/inscription/oracle-was-here.svg +0 -1
- package/artifacts/specialist-packs/oracle-full-crypto.json +0 -295
- package/dist/action-receipts.mjs +0 -1
- package/dist/action-semantics.mjs +0 -1
- package/dist/address-book.mjs +0 -2
- package/dist/bin/desk-server.mjs +0 -14
- package/dist/bin/oracle-data-mcp.mjs +0 -8
- package/dist/bin/oracle-init.mjs +0 -24
- package/dist/bin/oracle-public-server.mjs +0 -5
- package/dist/bin/oracle-route.mjs +0 -22
- package/dist/bin/oracle-scan.mjs +0 -18
- package/dist/bin/oracle-upgrade.mjs +0 -21
- package/dist/bin/oracle.mjs +0 -68
- package/dist/chains.mjs +0 -1
- package/dist/cli/commands/auth.mjs +0 -16
- package/dist/cli/commands/bootstrap.mjs +0 -18
- package/dist/cli/commands/chain.mjs +0 -21
- package/dist/cli/commands/chat.mjs +0 -35
- package/dist/cli/commands/credential.mjs +0 -1
- package/dist/cli/commands/data-mcp.mjs +0 -2
- package/dist/cli/commands/data.mjs +0 -12
- package/dist/cli/commands/doctor.mjs +0 -5
- package/dist/cli/commands/gate.mjs +0 -13
- package/dist/cli/commands/help.mjs +0 -1
- package/dist/cli/commands/init.mjs +0 -3
- package/dist/cli/commands/mcp.mjs +0 -33
- package/dist/cli/commands/model.mjs +0 -44
- package/dist/cli/commands/prepare.mjs +0 -2
- package/dist/cli/commands/public.mjs +0 -3
- package/dist/cli/commands/route.mjs +0 -2
- package/dist/cli/commands/runner.mjs +0 -1
- package/dist/cli/commands/scan.mjs +0 -2
- package/dist/cli/commands/setup.mjs +0 -34
- package/dist/cli/commands/sign.mjs +0 -4
- package/dist/cli/commands/signer.mjs +0 -1
- package/dist/cli/commands/upgrade.mjs +0 -2
- package/dist/cli/commands/vault.mjs +0 -1
- package/dist/cli/commands/version.mjs +0 -2
- package/dist/data/desk-data.mjs +0 -12
- package/dist/index.mjs +0 -17
- package/dist/nft-gas-war-guard.mjs +0 -1
- package/dist/onboarding/harness-configs.mjs +0 -4
- package/dist/portfolio-risk.mjs +0 -1
- package/dist/prepare-envelope.mjs +0 -1
- package/dist/public-control/policy-schema.mjs +0 -1
- package/dist/router/index.mjs +0 -2
- package/dist/scanner/index.mjs +0 -4
- package/dist/signals/index.mjs +0 -1
- package/dist/watch-preferences.mjs +0 -1
- package/public/agent-connect/app.js +0 -84
- package/public/agent-connect/index.html +0 -83
- package/public/agent-connect/styles.css +0 -70
- package/public/index.html +0 -12
- package/public/oracle-console/app.js +0 -272
- package/public/oracle-console/bitcoin-wallets.js +0 -206
- package/public/oracle-console/index.html +0 -91
- package/public/oracle-console/styles.css +0 -239
- package/public/oracle-splash/assets/cli-chain-hyperliquid.jpg +0 -0
- package/public/oracle-splash/assets/hero/orb.avif +0 -0
- package/public/oracle-splash/assets/hero/orb.webm +0 -0
- package/public/oracle-splash/assets/llms/claude.svg +0 -1
- package/public/oracle-splash/assets/llms/codex-icon.svg +0 -1
- package/public/oracle-splash/assets/llms/codex.svg +0 -1
- package/public/oracle-splash/assets/llms/cursor-icon.svg +0 -12
- package/public/oracle-splash/assets/llms/cursor.svg +0 -17
- package/public/oracle-splash/assets/llms/deepseek.svg +0 -1
- package/public/oracle-splash/assets/llms/gemini-icon.svg +0 -1
- package/public/oracle-splash/assets/llms/gemini.svg +0 -1
- package/public/oracle-splash/assets/llms/grok.svg +0 -8
- package/public/oracle-splash/assets/llms/hermes.png +0 -0
- package/public/oracle-splash/assets/llms/kimi-icon.svg +0 -1
- package/public/oracle-splash/assets/llms/kimi.svg +0 -1
- package/public/oracle-splash/assets/llms/manus.svg +0 -18
- package/public/oracle-splash/assets/llms/openclaw.svg +0 -22
- package/public/oracle-splash/assets/llms/perplexity.svg +0 -1
- package/public/oracle-splash/assets/llms/qwen.svg +0 -1
- package/public/oracle-splash/assets/llms/windsurf.svg +0 -1
- package/public/oracle-splash/assets/protocols/abcdex.png +0 -0
- package/public/oracle-splash/assets/protocols/across.png +0 -0
- package/public/oracle-splash/assets/protocols/aerodrome.png +0 -0
- package/public/oracle-splash/assets/protocols/balancer.png +0 -0
- package/public/oracle-splash/assets/protocols/cowswap.png +0 -0
- package/public/oracle-splash/assets/protocols/curve.png +0 -0
- package/public/oracle-splash/assets/protocols/dreamcash.png +0 -0
- package/public/oracle-splash/assets/protocols/felix.png +0 -0
- package/public/oracle-splash/assets/protocols/gmx.png +0 -0
- package/public/oracle-splash/assets/protocols/hyena.png +0 -0
- package/public/oracle-splash/assets/protocols/hyperbeat.png +0 -0
- package/public/oracle-splash/assets/protocols/hyperliquid.png +0 -0
- package/public/oracle-splash/assets/protocols/hyperswap.png +0 -0
- package/public/oracle-splash/assets/protocols/jupiter.png +0 -0
- package/public/oracle-splash/assets/protocols/kinetiq.png +0 -0
- package/public/oracle-splash/assets/protocols/lfj.png +0 -0
- package/public/oracle-splash/assets/protocols/lifi.png +0 -0
- package/public/oracle-splash/assets/protocols/magic-eden.png +0 -0
- package/public/oracle-splash/assets/protocols/morpho.png +0 -0
- package/public/oracle-splash/assets/protocols/odos.png +0 -0
- package/public/oracle-splash/assets/protocols/oneinch.png +0 -0
- package/public/oracle-splash/assets/protocols/opensea.png +0 -0
- package/public/oracle-splash/assets/protocols/pancakeswap.png +0 -0
- package/public/oracle-splash/assets/protocols/paragon.png +0 -0
- package/public/oracle-splash/assets/protocols/paraswap.png +0 -0
- package/public/oracle-splash/assets/protocols/pendle.png +0 -0
- package/public/oracle-splash/assets/protocols/polymarket.png +0 -0
- package/public/oracle-splash/assets/protocols/quickswap.png +0 -0
- package/public/oracle-splash/assets/protocols/relay.png +0 -0
- package/public/oracle-splash/assets/protocols/stargate.png +0 -0
- package/public/oracle-splash/assets/protocols/tradexyz.png +0 -0
- package/public/oracle-splash/assets/protocols/uniswap.png +0 -0
- package/public/oracle-splash/assets/protocols/velodrome.png +0 -0
- package/public/oracle-splash/assets/protocols/ventuals.png +0 -0
- package/public/oracle-splash/assets/wordmarks/across-icon.webp +0 -0
- package/public/oracle-splash/assets/wordmarks/across.svg +0 -4
- package/public/oracle-splash/assets/wordmarks/aerodrome.svg +0 -23
- package/public/oracle-splash/assets/wordmarks/balancer.svg +0 -3
- package/public/oracle-splash/assets/wordmarks/cowswap.svg +0 -1
- package/public/oracle-splash/assets/wordmarks/curve.png +0 -0
- package/public/oracle-splash/assets/wordmarks/gmx.svg +0 -13
- package/public/oracle-splash/assets/wordmarks/hop-icon.webp +0 -0
- package/public/oracle-splash/assets/wordmarks/hyena.svg +0 -7
- package/public/oracle-splash/assets/wordmarks/hyperliquid.svg +0 -21
- package/public/oracle-splash/assets/wordmarks/hyperswap.svg +0 -13
- package/public/oracle-splash/assets/wordmarks/jupiter.svg +0 -35
- package/public/oracle-splash/assets/wordmarks/kinetiq.svg +0 -1
- package/public/oracle-splash/assets/wordmarks/lfj.webp +0 -0
- package/public/oracle-splash/assets/wordmarks/lifi.png +0 -0
- package/public/oracle-splash/assets/wordmarks/magic-eden.svg +0 -1
- package/public/oracle-splash/assets/wordmarks/markets.svg +0 -1
- package/public/oracle-splash/assets/wordmarks/morpho.svg +0 -1
- package/public/oracle-splash/assets/wordmarks/odos.svg +0 -3
- package/public/oracle-splash/assets/wordmarks/oneinch-icon.webp +0 -0
- package/public/oracle-splash/assets/wordmarks/oneinch.svg +0 -6
- package/public/oracle-splash/assets/wordmarks/opensea-icon.svg +0 -17
- package/public/oracle-splash/assets/wordmarks/opensea.svg +0 -1
- package/public/oracle-splash/assets/wordmarks/outcome.svg +0 -16
- package/public/oracle-splash/assets/wordmarks/pancakeswap.svg +0 -18
- package/public/oracle-splash/assets/wordmarks/paragon.svg +0 -9
- package/public/oracle-splash/assets/wordmarks/paraswap.svg +0 -16
- package/public/oracle-splash/assets/wordmarks/pendle.png +0 -0
- package/public/oracle-splash/assets/wordmarks/polymarket.png +0 -0
- package/public/oracle-splash/assets/wordmarks/quickswap.png +0 -0
- package/public/oracle-splash/assets/wordmarks/relay.svg +0 -8
- package/public/oracle-splash/assets/wordmarks/satflow-icon.png +0 -0
- package/public/oracle-splash/assets/wordmarks/stargate-icon.webp +0 -0
- package/public/oracle-splash/assets/wordmarks/stargate.svg +0 -15
- package/public/oracle-splash/assets/wordmarks/uniswap.svg +0 -18
- package/public/oracle-splash/assets/wordmarks/velodrome.svg +0 -84
- package/public/oracle-splash/assets/wordmarks/xyz.svg +0 -12
- package/public/oracle-splash/assets/wordmarks/zerox-icon.webp +0 -0
- package/public/oracle-splash/brand/aave.webp +0 -0
- package/public/oracle-splash/brand/aavev2.webp +0 -0
- package/public/oracle-splash/brand/aborean.webp +0 -0
- package/public/oracle-splash/brand/across.webp +0 -0
- package/public/oracle-splash/brand/aerodrome.webp +0 -0
- package/public/oracle-splash/brand/afi.webp +0 -0
- package/public/oracle-splash/brand/arcus.webp +0 -0
- package/public/oracle-splash/brand/aster.webp +0 -0
- package/public/oracle-splash/brand/avant.webp +0 -0
- package/public/oracle-splash/brand/balancer.webp +0 -0
- package/public/oracle-splash/brand/beefy.webp +0 -0
- package/public/oracle-splash/brand/benqi.webp +0 -0
- package/public/oracle-splash/brand/bestinslot.ico +0 -0
- package/public/oracle-splash/brand/bitfi.webp +0 -0
- package/public/oracle-splash/brand/bonkswap.webp +0 -0
- package/public/oracle-splash/brand/bouncebit.webp +0 -0
- package/public/oracle-splash/brand/camelot.webp +0 -0
- package/public/oracle-splash/brand/compound.webp +0 -0
- package/public/oracle-splash/brand/concrete.webp +0 -0
- package/public/oracle-splash/brand/cow.webp +0 -0
- package/public/oracle-splash/brand/curve.webp +0 -0
- package/public/oracle-splash/brand/derive.webp +0 -0
- package/public/oracle-splash/brand/dolomite.webp +0 -0
- package/public/oracle-splash/brand/eigenlayer.webp +0 -0
- package/public/oracle-splash/brand/ekubo.webp +0 -0
- package/public/oracle-splash/brand/ethena.webp +0 -0
- package/public/oracle-splash/brand/etherfi.webp +0 -0
- package/public/oracle-splash/brand/etherfiborrow.webp +0 -0
- package/public/oracle-splash/brand/felix.webp +0 -0
- package/public/oracle-splash/brand/fluid.webp +0 -0
- package/public/oracle-splash/brand/fluxbeam.webp +0 -0
- package/public/oracle-splash/brand/folks.webp +0 -0
- package/public/oracle-splash/brand/fortyacres.webp +0 -0
- package/public/oracle-splash/brand/gainsnetwork.webp +0 -0
- package/public/oracle-splash/brand/gassss.webp +0 -0
- package/public/oracle-splash/brand/gmx.webp +0 -0
- package/public/oracle-splash/brand/harmonix.webp +0 -0
- package/public/oracle-splash/brand/hlorderbook.webp +0 -0
- package/public/oracle-splash/brand/hlp.webp +0 -0
- package/public/oracle-splash/brand/hop.webp +0 -0
- package/public/oracle-splash/brand/hyperbeat.webp +0 -0
- package/public/oracle-splash/brand/hyperlend.webp +0 -0
- package/public/oracle-splash/brand/hyperliquid.webp +0 -0
- package/public/oracle-splash/brand/hyperliquidhpl.webp +0 -0
- package/public/oracle-splash/brand/hyperliquidspot.webp +0 -0
- package/public/oracle-splash/brand/hyperswap.webp +0 -0
- package/public/oracle-splash/brand/hypha.webp +0 -0
- package/public/oracle-splash/brand/joedex.webp +0 -0
- package/public/oracle-splash/brand/jupiter.webp +0 -0
- package/public/oracle-splash/brand/kelp.webp +0 -0
- package/public/oracle-splash/brand/kinetiq.webp +0 -0
- package/public/oracle-splash/brand/kmhype.webp +0 -0
- package/public/oracle-splash/brand/kona.webp +0 -0
- package/public/oracle-splash/brand/konalend.webp +0 -0
- package/public/oracle-splash/brand/lfj.webp +0 -0
- package/public/oracle-splash/brand/lido.webp +0 -0
- package/public/oracle-splash/brand/lifi.webp +0 -0
- package/public/oracle-splash/brand/lighter.webp +0 -0
- package/public/oracle-splash/brand/lista.webp +0 -0
- package/public/oracle-splash/brand/loopedhype.webp +0 -0
- package/public/oracle-splash/brand/lorenzo.webp +0 -0
- package/public/oracle-splash/brand/magic-eden.webp +0 -0
- package/public/oracle-splash/brand/magiceden.webp +0 -0
- package/public/oracle-splash/brand/mempool.png +0 -0
- package/public/oracle-splash/brand/meteora.webp +0 -0
- package/public/oracle-splash/brand/morpho.webp +0 -0
- package/public/oracle-splash/brand/myriad.webp +0 -0
- package/public/oracle-splash/brand/noxa.webp +0 -0
- package/public/oracle-splash/brand/odos.webp +0 -0
- package/public/oracle-splash/brand/oneinch.webp +0 -0
- package/public/oracle-splash/brand/openbook.webp +0 -0
- package/public/oracle-splash/brand/opensea.webp +0 -0
- package/public/oracle-splash/brand/orca.webp +0 -0
- package/public/oracle-splash/brand/ordinals.png +0 -0
- package/public/oracle-splash/brand/ostium.webp +0 -0
- package/public/oracle-splash/brand/pancakeswap.webp +0 -0
- package/public/oracle-splash/brand/pendle.webp +0 -0
- package/public/oracle-splash/brand/perena.webp +0 -0
- package/public/oracle-splash/brand/pharaoh.webp +0 -0
- package/public/oracle-splash/brand/phoenix.webp +0 -0
- package/public/oracle-splash/brand/polymarket.webp +0 -0
- package/public/oracle-splash/brand/polynomial.webp +0 -0
- package/public/oracle-splash/brand/projectx.webp +0 -0
- package/public/oracle-splash/brand/pumpfun.webp +0 -0
- package/public/oracle-splash/brand/quickswap.webp +0 -0
- package/public/oracle-splash/brand/rain.webp +0 -0
- package/public/oracle-splash/brand/raydium.webp +0 -0
- package/public/oracle-splash/brand/relay.webp +0 -0
- package/public/oracle-splash/brand/rocketpool.webp +0 -0
- package/public/oracle-splash/brand/saber.webp +0 -0
- package/public/oracle-splash/brand/sakuraswap.webp +0 -0
- package/public/oracle-splash/brand/sanctum.webp +0 -0
- package/public/oracle-splash/brand/satflow.png +0 -0
- package/public/oracle-splash/brand/sierra.webp +0 -0
- package/public/oracle-splash/brand/sky.webp +0 -0
- package/public/oracle-splash/brand/solv.webp +0 -0
- package/public/oracle-splash/brand/spark.webp +0 -0
- package/public/oracle-splash/brand/sparksavings.webp +0 -0
- package/public/oracle-splash/brand/sphere.webp +0 -0
- package/public/oracle-splash/brand/ssv.webp +0 -0
- package/public/oracle-splash/brand/stabble.webp +0 -0
- package/public/oracle-splash/brand/stableswap.webp +0 -0
- package/public/oracle-splash/brand/stakewise.webp +0 -0
- package/public/oracle-splash/brand/stargate.webp +0 -0
- package/public/oracle-splash/brand/sthype.webp +0 -0
- package/public/oracle-splash/brand/sushiswap.webp +0 -0
- package/public/oracle-splash/brand/unisat.png +0 -0
- package/public/oracle-splash/brand/uniswap.webp +0 -0
- package/public/oracle-splash/brand/uniswapv2.webp +0 -0
- package/public/oracle-splash/brand/uniswapv4.webp +0 -0
- package/public/oracle-splash/brand/unit.webp +0 -0
- package/public/oracle-splash/brand/velodrome.webp +0 -0
- package/public/oracle-splash/brand/velora.webp +0 -0
- package/public/oracle-splash/brand/venus.webp +0 -0
- package/public/oracle-splash/brand/wbeth.webp +0 -0
- package/public/oracle-splash/brand/xsy.webp +0 -0
- package/public/oracle-splash/brand/yieldyak.webp +0 -0
- package/public/oracle-splash/brand/zerobase.webp +0 -0
- package/public/oracle-splash/brand/zerox.webp +0 -0
- package/public/oracle-splash/favicon.ico +0 -0
- package/public/oracle-splash/favicon.svg +0 -6
- package/public/oracle-splash/index.html +0 -1568
- package/public/oracle-splash/mesh-graph.png +0 -0
- package/public/oracle-splash/mesh-graph.svg +0 -216
package/README.md
CHANGED
|
@@ -1,508 +1,23 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @oracle-agent/oracle
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
**This package is a pointer, not the product.**
|
|
4
4
|
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
oracle --version
|
|
8
|
-
oracle auth login claude # or codex / grok
|
|
9
|
-
oracle # native Oracle chat
|
|
10
|
-
oracle doctor # verify local posture
|
|
11
|
-
```
|
|
12
|
-
|
|
13
|
-
Prefer an API key instead? `oracle auth api-key openrouter` accepts hidden
|
|
14
|
-
interactive input. `oracle auth status` reports providers without printing
|
|
15
|
-
credentials. Linux, Windows, and macOS apps are in beta.
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
**Prepare-only multichain agent control plane.** Policy-bounded intents; your wallet signs.
|
|
19
|
-
|
|
20
|
-
Specialist agent profiles, real protocol intents, self-custody by default,
|
|
21
|
-
receipts or it didn't happen.
|
|
22
|
-
|
|
23
|
-
Built for [Hermes](https://github.com/NousResearch/hermes-agent), the
|
|
24
|
-
open-source agent runtime from [Nous Research](https://nousresearch.com), but
|
|
25
|
-
Hermes is optional.
|
|
26
|
-
|
|
27
|
-
Oracle can run standalone model auth directly with API keys or Claude, Codex,
|
|
28
|
-
and Grok OAuth. OAuth credentials use the OS keychain when available, with a
|
|
29
|
-
private `0600` local fallback when keychain storage is unavailable.
|
|
30
|
-
|
|
31
|
-
This package is **prepare-only**: it never takes a private key and never
|
|
32
|
-
broadcasts. The owner-operated signer/executor is private infrastructure, is
|
|
33
|
-
not published on npm, and is not part of holder onboarding. Never paste a seed,
|
|
34
|
-
private key, vault passphrase, or signer token into Oracle chat.
|
|
35
|
-
|
|
36
|
-
---
|
|
37
|
-
|
|
38
|
-
## Start safely
|
|
39
|
-
|
|
40
|
-
1. Install the public CLI and authenticate a model provider as shown above.
|
|
41
|
-
2. Run `oracle chain list`, then `oracle chain use <name>`.
|
|
42
|
-
3. Use reads, research, quotes, simulations, and unsigned preparation.
|
|
43
|
-
4. Review every prepared artifact in the wallet that will sign it.
|
|
44
|
-
5. Treat only a confirmed transaction hash plus receipt as execution.
|
|
45
|
-
|
|
46
|
-
Hermes is optional. To add its isolated runtime, specialist profiles, and local
|
|
47
|
-
read plane later:
|
|
48
|
-
|
|
49
|
-
```bash
|
|
50
|
-
oracle bootstrap
|
|
51
|
-
oracle init --apply # writes profiles + local HMAC attestation config; no wallet key
|
|
52
|
-
oracle data serve # loopback only: 127.0.0.1:8787
|
|
53
|
-
oracle doctor
|
|
54
|
-
```
|
|
55
|
-
|
|
56
|
-
Library users can prepare directly:
|
|
57
|
-
|
|
58
|
-
```js
|
|
59
|
-
import { data } from "@oracle-agent/oracle";
|
|
60
|
-
const prepared = await data.call("hl-perps", "prepareOrder", {
|
|
61
|
-
/* coin, side, size, owner wallet address */
|
|
62
|
-
});
|
|
63
|
-
// Oracle stops here. The user's wallet reviews, signs, and submits.
|
|
64
|
-
```
|
|
65
|
-
|
|
66
|
-
See [SETUP.md](SETUP.md) for clean installation and troubleshooting,
|
|
67
|
-
[docs/holder-beta.md](docs/holder-beta.md) for the Locals-only launch gate, and
|
|
68
|
-
[docs/buzz-integration.md](docs/buzz-integration.md) for the Buzz HTTP contract.
|
|
69
|
-
|
|
70
|
-
---
|
|
71
|
-
|
|
72
|
-
## What Oracle is
|
|
73
|
-
|
|
74
|
-
Most "AI crypto agent" projects give a model a hot wallet and hope. Oracle does
|
|
75
|
-
the opposite: the model *proposes*, the owner *authorizes*, and the policy layer
|
|
76
|
-
decides what may even be asked.
|
|
77
|
-
|
|
78
|
-
Three properties define it:
|
|
79
|
-
|
|
80
|
-
1. **Self-custody by default.** The public package never accepts your private
|
|
81
|
-
key. It builds unsigned transactions and typed-data intents; your wallet
|
|
82
|
-
signs them.
|
|
83
|
-
2. **Bound grants.** A grant is a signed, scoped, expiring permission: max
|
|
84
|
-
value, chain, venue, destination allowlist, TTL. Oracle canonicalizes it,
|
|
85
|
-
renders it for review, and refuses to prepare anything outside it. Runtime
|
|
86
|
-
enforcement is the wallet's or smart account's job — this package never
|
|
87
|
-
signs, so it cannot be the thing that stops a transaction.
|
|
88
|
-
3. **Receipts or it didn't happen.** A claim without a transaction hash, a
|
|
89
|
-
receipt, and a balance delta is not a result.
|
|
90
|
-
|
|
91
|
-
Default posture is `DISARMED`.
|
|
92
|
-
|
|
93
|
-
## Why it's different
|
|
94
|
-
|
|
95
|
-
The differentiators are **policy, custody, and receipts** — not a smarter chat
|
|
96
|
-
loop.
|
|
97
|
-
|
|
98
|
-
| | Typical agent | Oracle |
|
|
99
|
-
|---|---|---|
|
|
100
|
-
| Custody | house wallet holds keys | user signs, no house custody |
|
|
101
|
-
| Authority | prompt-level "be careful" | signed grant: chain, spend, targets, TTL — enforced by your wallet, not by us |
|
|
102
|
-
| Destinations | whatever the model emits | reviewed per-chain allowlist, fail-closed |
|
|
103
|
-
| Slippage | fixed % | live guard recomputed per leg, hard 100 bps cap |
|
|
104
|
-
| Proof | model says "done" | hash + verified successful on-chain receipt + expected balance delta or it failed |
|
|
105
|
-
| Surface | swap only | swaps, bridges, perps, vaults, yield, NFTs, intents |
|
|
106
|
-
|
|
107
|
-
## Architecture
|
|
108
|
-
|
|
109
|
-
```
|
|
110
|
-
you
|
|
111
|
-
|
|
|
112
|
-
Task
|
|
113
|
-
|
|
|
114
|
-
oracle <- routes, never authorizes custody
|
|
115
|
-
|
|
|
116
|
-
+------+------+------+------+------+------+------+
|
|
117
|
-
| | | | | | | |
|
|
118
|
-
poly hyper robin solana bitcoin stable protocol
|
|
119
|
-
market liquid hood builder
|
|
120
|
-
```
|
|
121
|
-
|
|
122
|
-
Each lane is a Hermes **profile**: its own system prompt, skills, memory, and
|
|
123
|
-
sessions. The `oracle` lane routes intent to the right specialist. Adding a lane
|
|
124
|
-
is adding a directory.
|
|
125
|
-
|
|
126
|
-
Three planes, and the boundary between them is mechanically enforced:
|
|
127
|
-
|
|
128
|
-
- **Data plane** (public) — read/quote across chains and protocols. No keys.
|
|
129
|
-
- **Policy plane** (public) — destination allowlists, slippage guards, route and
|
|
130
|
-
vault attestations, grant schema. Holds no keys; constrains what a signer may
|
|
131
|
-
be asked to do.
|
|
132
|
-
- **Exec plane** (private, optional) — signing and broadcast live only in
|
|
133
|
-
separately operated owner infrastructure. It is not published on npm, not in
|
|
134
|
-
this artifact, and not available to holder installs.
|
|
135
|
-
|
|
136
|
-
`test/custody-boundary.test.mjs` walks the import graph and fails if any public
|
|
137
|
-
module reaches wallet key material or a house signer. The split is a test, not a
|
|
138
|
-
promise.
|
|
139
|
-
|
|
140
|
-
## Coverage
|
|
141
|
-
|
|
142
|
-
**11 EVM chains** built in: Ethereum, Optimism, BNB, Polygon, Stable, HyperEVM,
|
|
143
|
-
Abstract, Robinhood Chain, Base, Arbitrum, Avalanche. Plus Solana and Bitcoin L1
|
|
144
|
-
lanes. Solana covers Jupiter quote/prepare, SPL account research, live
|
|
145
|
-
simulation of the prepared swap, and Magic Eden NFT reads with unsigned
|
|
146
|
-
buy/list/mint tickets. Bitcoin covers Esplora fee/UTXO reads, Ordinals/runes
|
|
147
|
-
research, Satflow PSBT intents, and inscription PSBT preparation. Hyperliquid
|
|
148
|
-
adds HyperCore HYPE staking: validator reads plus EIP-712 stake, delegate,
|
|
149
|
-
undelegate, and unstake preparation. User wallets sign.
|
|
150
|
-
|
|
151
|
-
**Any other EVM chain is config, not code:**
|
|
152
|
-
|
|
153
|
-
```js
|
|
154
|
-
import { registerCustomChain } from "@oracle-agent/oracle/scanner";
|
|
155
|
-
|
|
156
|
-
registerCustomChain({
|
|
157
|
-
key: "mychain",
|
|
158
|
-
chainId: 7777,
|
|
159
|
-
name: "My Chain",
|
|
160
|
-
rpcEnv: ["MYCHAIN_RPC_URL"],
|
|
161
|
-
nativeCurrency: { symbol: "MYC", decimals: 18 },
|
|
162
|
-
});
|
|
163
|
-
```
|
|
164
|
-
|
|
165
|
-
That chain immediately has block reads, balances, on-chain token resolution, log
|
|
166
|
-
scanning, and structural risk checks. See
|
|
167
|
-
[`docs/adding-a-chain.md`](docs/adding-a-chain.md).
|
|
168
|
-
|
|
169
|
-
```bash
|
|
170
|
-
oracle-scan chains # coverage matrix
|
|
171
|
-
oracle-scan token base 0x8335...2913 # on-chain identity
|
|
172
|
-
oracle-scan pools base 0x4200...0006 # pools ranked by liquidity
|
|
173
|
-
oracle-scan risk base 0x8335...2913 # structural checks + sell simulation
|
|
174
|
-
oracle-scan sell base 0x8335...2913 # round trip: can you actually exit?
|
|
175
|
-
```
|
|
176
|
-
|
|
177
|
-
**8 of 11 chains ship verified venues**: Ethereum, Optimism, BNB, Polygon, Base,
|
|
178
|
-
Arbitrum, Avalanche, and Robinhood Chain. They have all 10 capabilities including
|
|
179
|
-
live quotes, round-trip sell simulation, and unsigned swap preparation. The remaining
|
|
180
|
-
three (Stable, HyperEVM, Abstract) are at 7 and **fail-closed for routing value** until
|
|
181
|
-
someone verifies a venue: read and research work, moving money does not. That is a safe
|
|
182
|
-
default, not a gap.
|
|
183
|
-
|
|
184
|
-
Every venue address was verified **functionally, not by codesize** — a re-runnable
|
|
185
|
-
prober (`scripts/verify-v3-venues.mjs`) asks each candidate to price a pair with a
|
|
186
|
-
known answer. This matters: the canonical QuoterV2 address also has bytecode on
|
|
187
|
-
Base, but does not price that chain's pairs. A codesize check would have
|
|
188
|
-
allowlisted the wrong contract.
|
|
189
|
-
|
|
190
|
-
**42 provider modules** in the read/quote catalog, covering **219 unique
|
|
191
|
-
protocols/venues** across EVM, Solana, and Bitcoin (115 EVM + cross-chain, 98
|
|
192
|
-
Solana venues backed by 101 verified Jupiter program IDs, 6 Bitcoin surfaces).
|
|
193
|
-
One module can cover many protocols: the Jupiter module alone routes 98 Solana
|
|
194
|
-
venues, so provider-module count and protocol count are different numbers.
|
|
195
|
-
|
|
196
|
-
| Class | Providers |
|
|
197
|
-
|---|---|
|
|
198
|
-
| Chain / explorer | EVM JSON-RPC, Blockscout, Solana RPC, Bitcoin Esplora |
|
|
199
|
-
| Market data | DexScreener, GeckoTerminal, DeFiLlama |
|
|
200
|
-
| DEX / aggregator | Uniswap V3/V4, Aerodrome, Curve, Balancer, LI.FI, ParaSwap, Odos, 0x, 1inch, HyperEVM DEXes |
|
|
201
|
-
| Solana | Jupiter (98 venue labels, 101 verified program IDs) |
|
|
202
|
-
| Intents | CoW Protocol, RFQ |
|
|
203
|
-
| Perps / lending / yield | GMX v2, Morpho, Pendle |
|
|
204
|
-
| Bridges | Across, Hop, Relay |
|
|
205
|
-
| Venues | Hyperliquid (core perps + HIP-3 builder dexs + HIP-4 outcomes), Polymarket (read + local CLOB prepare) |
|
|
206
|
-
| NFT | OpenSea, Satflow, Magic Eden (Solana) |
|
|
207
|
-
| Bitcoin | mempool/Esplora, Ordinals, Runes, UniSat, Best-in-Slot, Satflow |
|
|
208
|
-
|
|
209
|
-
Every provider and every scanner capability declares an honest tier —
|
|
210
|
-
`read-only`, `quote-only`, `prepare`, or `intent`. **API coverage is not execution
|
|
211
|
-
support**, and the catalog says which is which. A chain with no verified venue is
|
|
212
|
-
fail-closed for routing value: read and research work, moving money does not. That
|
|
213
|
-
is a safe default, not a gap.
|
|
214
|
-
|
|
215
|
-
## Capability pack
|
|
216
|
-
|
|
217
|
-
Oracle's default pack is deliberately broad but disarmed:
|
|
218
|
-
|
|
219
|
-
- **Trader** — best-execution route comparison, quote/prepare, simulation, and
|
|
220
|
-
receipt checks; no set-and-forget custody.
|
|
221
|
-
- **Builder** - chain-family fungible-token and NFT-collection launch plans,
|
|
222
|
-
protocol, gacha, DEX, and launchpad scaffolds with unsigned deploy/admin actions.
|
|
223
|
-
Unsupported chain adapters fail closed instead of pretending one deploy fits all.
|
|
224
|
-
- **Analyzer** — token, contract, venue, portfolio, market, and risk research with
|
|
225
|
-
evidence labels. `/balance` or plain `balance` runs one deterministic snapshot
|
|
226
|
-
across every configured EVM chain plus Solana, Bitcoin, Hyperliquid, and
|
|
227
|
-
discoverable NFTs. Profile-local observations power history and SVG value graphs;
|
|
228
|
-
unavailable values stay null instead of becoming fake zeroes.
|
|
229
|
-
- **On-chain scanner** — chain-config scanners for tokens, pools, launches,
|
|
230
|
-
risk, exits, and smart-wallet boards.
|
|
231
|
-
- **Meme-token sniper** — fast launch/liquidity monitoring across configured
|
|
232
|
-
chains, guarded by identity checks, sell-sim/reverse-route proof, caps, and
|
|
233
|
-
unsigned user-wallet tickets.
|
|
234
|
-
- **Per-chain graphs + Telegram cards** — charted scanner alerts, route cards,
|
|
235
|
-
meme-launch cards, Hyperliquid HIP-3/HIP-4 cards, and Polymarket cards. User
|
|
236
|
-
API-key actions activate only when self-hosted keys are configured.
|
|
237
|
-
- **NFT mint gas-war limits** — public mint bots enforce chain-bound gas caps,
|
|
238
|
-
per-unit fee caps, and optional priority-fee caps before returning unsigned
|
|
239
|
-
mint transactions. Import `validateNftMintGasWar` from the package root or
|
|
240
|
-
`@oracle-agent/oracle/nft-gas-war`.
|
|
241
|
-
- **Cross-chain RFQ + tokenized assets** — RFQ/intent venues are compared across
|
|
242
|
-
supported chains where configured, and tokenized Robinhood-style assets can be
|
|
243
|
-
bought only after exact contract, venue, route, and sellability checks.
|
|
244
|
-
- **Solana** — SPL accounts, Jupiter quotes, unsigned swap transactions, and
|
|
245
|
-
simulation.
|
|
246
|
-
- **Bitcoin** — L1 reads, Ordinals/runes, Satflow PSBT intents, and inscription
|
|
247
|
-
PSBT preparation.
|
|
248
|
-
|
|
249
|
-
Every money-moving path stays prepare/simulate first. Signing and broadcast are
|
|
250
|
-
wallet/grant actions, not model authority. Meme-token sniping defaults to fast
|
|
251
|
-
scan + prepared ticket; blind broadcast requires a separate capped local signer
|
|
252
|
-
loop and explicit opt-in. NFT mint bots must also honor gas-war caps before any
|
|
253
|
-
wallet-signable transaction is returned. RFQ and tokenized-asset routes are
|
|
254
|
-
capability-labeled per chain; unconfigured venues stay unavailable instead of faked.
|
|
255
|
-
|
|
256
|
-
## Install
|
|
257
|
-
|
|
258
|
-
```bash
|
|
259
|
-
npm install @oracle-agent/oracle # Node >= 20.19.0
|
|
260
|
-
```
|
|
261
|
-
|
|
262
|
-
Or from source, if you want to run the suite:
|
|
263
|
-
|
|
264
|
-
```bash
|
|
265
|
-
git clone https://github.com/demi-hl/oracle.git
|
|
266
|
-
cd oracle
|
|
267
|
-
npm install
|
|
268
|
-
npm test
|
|
269
|
-
```
|
|
5
|
+
Oracle is distributed to [Locals Only](https://opensea.io/collection/locals-only-hyperevm) holders.
|
|
6
|
+
Versions `<=0.12.0` on this registry are deprecated and unmaintained.
|
|
270
7
|
|
|
271
|
-
|
|
272
|
-
owner-local source lane.** The short version:
|
|
8
|
+
## Get a build
|
|
273
9
|
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
- User wallets authorize prepared actions outside the public data plane.
|
|
277
|
-
- Owner-local signing exists only in separately operated private infrastructure;
|
|
278
|
-
it is not published on npm and is not a holder capability. When installed by
|
|
279
|
-
the owner, its generic signer exposes six policy-bounded surfaces: `hl`,
|
|
280
|
-
`poly`, `evm-swap`, `evm-bridge`, `btc`, and `sol`, with explicit caps and
|
|
281
|
-
fail-closed allowlists.
|
|
10
|
+
Visit **https://oracle.demi.la**, prove your wallet holds a Locals Only NFT, and install
|
|
11
|
+
the artifact the gate returns:
|
|
282
12
|
|
|
283
|
-
### Action vocabulary and execution planes
|
|
284
|
-
|
|
285
|
-
Oracle keeps capability and authorization separate:
|
|
286
|
-
|
|
287
|
-
- Public Oracle reads, quotes, simulates, and prepares unsigned artifacts.
|
|
288
|
-
- **Path A:** owner/main, browser, smart-account, hardware, or protocol-native
|
|
289
|
-
wallets sign the prepared artifact. This is the default self-custody path.
|
|
290
|
-
- **Path B:** private owner-local infrastructure may sign on the same host with
|
|
291
|
-
the owner's key and policy. It is deployment-specific, unavailable to holder
|
|
292
|
-
installs, and must never expose a vault passphrase or signer credential to the
|
|
293
|
-
agent process.
|
|
294
|
-
- The generic unattended signer exposes six bounded surfaces: `hl`, `poly`,
|
|
295
|
-
`evm-swap`, `evm-bridge`, `btc`, `sol`. Each surface decodes its own
|
|
296
|
-
envelope, enforces its caps, and refuses while its allowlists are empty.
|
|
297
|
-
- Ordinary EVM preparation remains user-wallet signed unless a trusted
|
|
298
|
-
owner-controlled direct-exec process is explicitly installed and armed.
|
|
299
|
-
- `ORACLE_AUTONOMOUS_TRADING=1` is direct execution for trusted owner-controlled
|
|
300
|
-
local code only. It is never model/agent authority and should not be framed as
|
|
301
|
-
equivalent to the `oracle-signer` agent-process path.
|
|
302
|
-
- A deployment may separately install a same-host, owner-gated EVM executor.
|
|
303
|
-
Oracle must verify that executor before describing bounded EVM execution as
|
|
304
|
-
available. Missing deployment capability means "unavailable here," not
|
|
305
|
-
"Oracle can never execute EVM."
|
|
306
|
-
- `watch`, `watch this`, and `ping me` always create `active: true, actionMode: alert_only`.
|
|
307
|
-
- `arm` creates `active: true, actionMode: execute` only for one exact owner-authorized action. It is never inferred from a watch.
|
|
308
|
-
|
|
309
|
-
The package exports this binding as `@oracle-agent/oracle/action-semantics`. Legacy watch stores can migrate `status: watching|armed` with `migrateLegacyWatchRecord()`; because it is specifically a watch-store migration, both statuses become `alert_only`, never execution authority.
|
|
310
|
-
|
|
311
|
-
Run the read-only data plane:
|
|
312
|
-
|
|
313
|
-
```bash
|
|
314
|
-
npm run start:data
|
|
315
|
-
npm run health
|
|
316
|
-
```
|
|
317
|
-
|
|
318
|
-
Run the public console (wallet connect, grant editor, receipts):
|
|
319
|
-
|
|
320
|
-
```bash
|
|
321
|
-
npm run start:public
|
|
322
|
-
# http://127.0.0.1:8799/
|
|
323
|
-
```
|
|
324
|
-
|
|
325
|
-
This is an unauthenticated loopback development server, not a holder gate or a
|
|
326
|
-
public deployment. Keep it off LAN/tailnet/public interfaces and place a tested
|
|
327
|
-
admission gateway in front of any hosted beta.
|
|
328
|
-
|
|
329
|
-
## Model providers
|
|
330
|
-
|
|
331
|
-
Oracle is a library. Drive it with Claude, GPT, Gemini, Grok, a local model, or
|
|
332
|
-
a plain script — the tools are ordinary functions plus an MCP server:
|
|
333
|
-
|
|
334
|
-
```bash
|
|
335
|
-
npx oracle-data # local read plane on 127.0.0.1:8787
|
|
336
|
-
npx oracle-data-mcp # MCP stdio server (any MCP client); needs oracle-data up
|
|
337
|
-
```
|
|
338
|
-
|
|
339
|
-
It is better under [Hermes](https://hermes-agent.nousresearch.com/docs), because
|
|
340
|
-
a trading stack is several workloads with opposite needs and **per-profile
|
|
341
|
-
routing** gives each its own model, tools, and key scope: cheap wide context for
|
|
342
|
-
research, a fast model for execution where latency is money, the strongest model
|
|
343
|
-
for risk review, something small for unattended crons. The research profile can
|
|
344
|
-
hold no signing key at all.
|
|
345
|
-
|
|
346
|
-
Oracle's own pre-release audit ran four model lineages — Grok 4.5, Opus 5,
|
|
347
|
-
Fable 5, GPT-5.6 — and **each found a critical bug the others missed**. One
|
|
348
|
-
model reviewing its own work would have shipped three of them.
|
|
349
|
-
|
|
350
|
-
|
|
351
|
-
## Agent profiles
|
|
352
|
-
|
|
353
|
-
Oracle ships an installable 8-lane mesh for Hermes:
|
|
354
|
-
|
|
355
|
-
```bash
|
|
356
|
-
oracle-init # dry run -- shows exactly what it would do
|
|
357
|
-
oracle-init --apply # create profiles, install SOULs + skills, wire MCP config
|
|
358
|
-
npx oracle-data # keep running — MCP tools call the local read plane on :8787
|
|
359
|
-
oracle # premium boxed TTY on the same oracle profile as messaging
|
|
360
|
-
oracle model # choose provider/model; persona stays oracle
|
|
361
|
-
oracle chain use hyperliquid
|
|
362
|
-
oracle setup # telegram / discord / slack messaging
|
|
363
13
|
```
|
|
364
|
-
|
|
365
|
-
Terminal and configured messaging channels are transports into the same Hermes
|
|
366
|
-
`oracle` profile. When a local operator/MCP is configured, an explicit owner
|
|
367
|
-
trade instruction can execute from either interface. The selected model never
|
|
368
|
-
bypasses signer-owned grants, allowlists, caps, MAC checks, simulation, or
|
|
369
|
-
receipt verification.
|
|
370
|
-
|
|
371
|
-
Lanes: `oracle` (router), `polymarket-agent`, `hyperliquid-agent`,
|
|
372
|
-
`robinhood-agent`, `solana-agent`, `bitcoin-agent`, `stable-agent`,
|
|
373
|
-
`protocol-builder`, plus `_template` for your own. Details in
|
|
374
|
-
[`docs/profiles.md`](docs/profiles.md).
|
|
375
|
-
|
|
376
|
-
Every lane installs **DISARMED**. No lane requests a broadcast or signing action —
|
|
377
|
-
only read, simulate, and prepare — and a test enforces that so widening custody
|
|
378
|
-
can't pass review quietly. An existing `SOUL.md` is never overwritten without
|
|
379
|
-
`--force`, and `--force` writes a timestamped backup first.
|
|
380
|
-
|
|
381
|
-
Oracle does not issue its own model credential. Standalone chat uses the OAuth
|
|
382
|
-
login or API key the user configured; Hermes mode uses whichever provider that
|
|
383
|
-
Hermes installation already supports.
|
|
384
|
-
|
|
385
|
-
**Why "built for Hermes" and not just "works anywhere":** Oracle's read plane is
|
|
386
|
-
an MCP server, so any MCP client can call it. But the *mesh* — per-lane memory,
|
|
387
|
-
skills, sessions, and separate model choice per specialist — is Hermes profile
|
|
388
|
-
machinery. You can use Oracle from any agent; you get the architecture in the
|
|
389
|
-
diagram above from Hermes.
|
|
390
|
-
|
|
391
|
-
## Best-execution routing
|
|
392
|
-
|
|
393
|
-
The highest quote is not the cheapest swap. Oracle ranks on **net received after
|
|
394
|
-
gas and fees**, comparing every available source in parallel:
|
|
395
|
-
|
|
396
|
-
```bash
|
|
397
|
-
oracle-route swap base 0x4200...0006 0x8335...2913 # WETH -> USDC
|
|
398
|
-
oracle-route bridge arbitrum base # ETH across chains
|
|
399
|
-
```
|
|
400
|
-
|
|
14
|
+
curl -fL -o oracle.tgz "<link-from-gate>" && npm i -g ./oracle.tgz
|
|
401
15
|
```
|
|
402
|
-
source net out gross cost
|
|
403
|
-
* paraswap 1,903.880867 1,903.893053 $0.01
|
|
404
|
-
cow 1,903.693798 1,903.693798 gasless (solver)
|
|
405
|
-
lifi 1,894.432632 1,899.20966 $4.78
|
|
406
|
-
```
|
|
407
|
-
|
|
408
|
-
Sources: **LI.FI, CoW, ParaSwap, 0x, 1inch** for swaps · **LI.FI, Relay, Across**
|
|
409
|
-
for bridges. 0x and 1inch activate when their API key is present; the rest need
|
|
410
|
-
none.
|
|
411
|
-
|
|
412
|
-
Why net matters:
|
|
413
|
-
|
|
414
|
-
- **Gas is part of the price.** A route quoting 0.2% more but costing $14 more in
|
|
415
|
-
gas loses on a $500 swap and wins on a $50k one. The crossover depends on trade
|
|
416
|
-
size, so any fixed preference is wrong on one side of it.
|
|
417
|
-
- **Intents can beat AMMs.** CoW's solver pays the gas, so a slightly lower gross
|
|
418
|
-
quote often wins on net — the case naive ranking always gets backwards.
|
|
419
|
-
- **Sources disagree about what they mean.** Some report gas in USD, some in native
|
|
420
|
-
wei, some not at all. Oracle normalizes, and marks what was measured.
|
|
421
|
-
|
|
422
|
-
**Unknown cost is never scored as zero.** A source that does not report gas is
|
|
423
|
-
ranked on gross and flagged, because scoring an unknown as free is how the worst
|
|
424
|
-
route wins a comparison. When the top two routes measure cost differently, Oracle
|
|
425
|
-
quotes **no spread at all** rather than a number that compares different things.
|
|
426
|
-
|
|
427
|
-
Then prepare the winner in one step:
|
|
428
|
-
|
|
429
|
-
```bash
|
|
430
|
-
oracle-route prepare base <tokenIn> <tokenOut> <yourWallet>
|
|
431
|
-
```
|
|
432
|
-
|
|
433
|
-
You get back an **unsigned transaction** (LI.FI, ParaSwap, 0x) or **EIP-712 typed
|
|
434
|
-
data** for an off-chain order (CoW). `artifactKind` says which — they need different
|
|
435
|
-
wallet actions, and one is not broadcast at all. Prepare **re-quotes** and reports
|
|
436
|
-
`driftBps` against the comparison, because a minimum computed from a stale quote is
|
|
437
|
-
not a minimum.
|
|
438
|
-
|
|
439
|
-
Bridges prepare too:
|
|
440
|
-
|
|
441
|
-
```bash
|
|
442
|
-
oracle-route prepare-bridge arbitrum base <yourWallet>
|
|
443
|
-
```
|
|
444
|
-
|
|
445
|
-
Bridge artifacts are always a **list** of transactions — some routes need an approval
|
|
446
|
-
and a deposit signed in order, and signing only the first leaves funds approved but
|
|
447
|
-
not bridged. Both chains are reported, and a transaction whose chain does not match
|
|
448
|
-
the origin is refused. Oracle states plainly that **bridging is not atomic**: the
|
|
449
|
-
origin transaction confirming does not mean funds arrived.
|
|
450
|
-
|
|
451
|
-
Routing never signs. `taker` must be the real wallet; placeholder addresses are
|
|
452
|
-
rejected, since quoting is anonymous but preparing is not. Signing happens in
|
|
453
|
-
the user's wallet or in a separately operated source-only execution lane.
|
|
454
|
-
|
|
455
|
-
Individual source failures degrade the comparison by one source instead of breaking
|
|
456
|
-
it — verified in practice when Odos sunset their public API mid-development
|
|
457
|
-
(HTTP 410); the router kept ranking and the provider was marked `unavailable`.
|
|
458
|
-
|
|
459
|
-
## Examples
|
|
460
|
-
|
|
461
|
-
```bash
|
|
462
|
-
node examples/add-a-chain.mjs # register an unseen chain, no code
|
|
463
|
-
node examples/research-a-token.mjs # honest token research on live data
|
|
464
|
-
node examples/oracle-pack-template.mjs # skeleton for a safe Oracle protocol pack
|
|
465
|
-
```
|
|
466
|
-
|
|
467
|
-
## MCP
|
|
468
|
-
|
|
469
|
-
Oracle exposes its read plane over the Model Context Protocol, so any MCP client
|
|
470
|
-
(Hermes, Claude Code, others) can use it:
|
|
471
|
-
|
|
472
|
-
```bash
|
|
473
|
-
oracle-data-mcp
|
|
474
|
-
```
|
|
475
|
-
|
|
476
|
-
## Security
|
|
477
|
-
|
|
478
|
-
- Oracle never receives private keys.
|
|
479
|
-
- The router can propose, simulate, explain, and draft. It cannot authorize.
|
|
480
|
-
- Public modules may not import signer or executor code (enforced by test).
|
|
481
|
-
- Destination allowlists are per-chain and fail-closed: an empty allowlist
|
|
482
|
-
refuses everything rather than allowing everything.
|
|
483
|
-
- Report vulnerabilities per [SECURITY.md](SECURITY.md). Please do not open a
|
|
484
|
-
public issue for a live exploit.
|
|
485
|
-
|
|
486
|
-
## What Oracle is not
|
|
487
|
-
|
|
488
|
-
- Not an autonomous trader. There is no "set and forget."
|
|
489
|
-
- Not custodial. If a design needs your key on our server, that design is wrong.
|
|
490
|
-
- Not a guarantee. Crypto execution carries real risk; read the code you run.
|
|
491
|
-
|
|
492
|
-
## License
|
|
493
|
-
|
|
494
|
-
[Business Source License 1.1](LICENSE) — source-available, not open source.
|
|
495
|
-
|
|
496
|
-
You may read, modify, self-host, and use Oracle freely for internal use,
|
|
497
|
-
evaluation, research, and personal use. What you may not do is offer Oracle,
|
|
498
|
-
or substantially its functionality, to third parties as a competing product
|
|
499
|
-
or hosted service without a commercial license.
|
|
500
16
|
|
|
501
|
-
|
|
502
|
-
release). Versions `0.1.0` through `0.11.0` were published under Apache-2.0
|
|
503
|
-
and remain under those terms.
|
|
17
|
+
Prefer no terminal? The desktop app is at https://oracle.demi.la/downloads/
|
|
504
18
|
|
|
505
|
-
|
|
506
|
-
an official deployment when shipping a fork.
|
|
19
|
+
## Why
|
|
507
20
|
|
|
508
|
-
|
|
21
|
+
A holder check that runs on your machine can always be switched off. Serving the
|
|
22
|
+
artifact from a server that verifies ownership is the only version of this that means
|
|
23
|
+
anything. Keys and signing never live in the public package either way.
|
package/bin/oracle.mjs
ADDED
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
// This is not Oracle. It is a pointer to the gate that distributes Oracle.
|
|
3
|
+
//
|
|
4
|
+
// The product moved to holder-gated distribution. The public registry copy
|
|
5
|
+
// cannot be unpublished (npm blocks it above 300 weekly downloads), so the
|
|
6
|
+
// next best thing is that `latest` carries no product code at all.
|
|
7
|
+
const GATE = "https://oracle.demi.la";
|
|
8
|
+
console.log(`
|
|
9
|
+
Oracle is distributed to Locals Only holders.
|
|
10
|
+
|
|
11
|
+
This npm package is a pointer, not the product. It contains no Oracle code.
|
|
12
|
+
|
|
13
|
+
To get a build:
|
|
14
|
+
1. Visit ${GATE}
|
|
15
|
+
2. Prove your wallet holds a Locals Only NFT
|
|
16
|
+
3. Install the artifact the gate returns:
|
|
17
|
+
|
|
18
|
+
curl -fL -o oracle.tgz "<link-from-gate>" && npm i -g ./oracle.tgz
|
|
19
|
+
|
|
20
|
+
Desktop app (no terminal required): ${GATE}/downloads/
|
|
21
|
+
|
|
22
|
+
Contract 0x62FCFAf7573AD8B41a0FBF347AfEb85e06599A75
|
|
23
|
+
Chain HyperEVM (999)
|
|
24
|
+
`);
|
|
25
|
+
process.exit(1);
|
package/package.json
CHANGED
|
@@ -1,72 +1,27 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@oracle-agent/oracle",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"description": "Oracle
|
|
5
|
-
"license": "BUSL-1.1",
|
|
3
|
+
"version": "0.13.0",
|
|
4
|
+
"description": "Oracle is distributed to Locals Only holders. This package is a pointer to the gate, not the product.",
|
|
6
5
|
"type": "module",
|
|
7
|
-
"
|
|
8
|
-
"access": "public"
|
|
9
|
-
},
|
|
10
|
-
"homepage": "https://github.com/demi-hl/oracle",
|
|
11
|
-
"repository": {
|
|
12
|
-
"type": "git",
|
|
13
|
-
"url": "https://github.com/demi-hl/oracle.git"
|
|
14
|
-
},
|
|
15
|
-
"keywords": [
|
|
16
|
-
"ai-agent",
|
|
17
|
-
"multichain",
|
|
18
|
-
"evm",
|
|
19
|
-
"self-custody",
|
|
20
|
-
"defi",
|
|
21
|
-
"hermes",
|
|
22
|
-
"nous",
|
|
23
|
-
"mcp"
|
|
24
|
-
],
|
|
6
|
+
"license": "SEE LICENSE IN LICENSE",
|
|
25
7
|
"engines": {
|
|
26
8
|
"node": ">=20.19.0"
|
|
27
9
|
},
|
|
28
10
|
"bin": {
|
|
29
|
-
"oracle": "
|
|
30
|
-
"oracle-data": "./dist/bin/desk-server.mjs",
|
|
31
|
-
"oracle-public": "./dist/bin/oracle-public-server.mjs",
|
|
32
|
-
"oracle-data-mcp": "./dist/bin/oracle-data-mcp.mjs",
|
|
33
|
-
"oracle-init": "./dist/bin/oracle-init.mjs",
|
|
34
|
-
"oracle-upgrade": "./dist/bin/oracle-upgrade.mjs",
|
|
35
|
-
"oracle-scan": "./dist/bin/oracle-scan.mjs",
|
|
36
|
-
"oracle-route": "./dist/bin/oracle-route.mjs"
|
|
37
|
-
},
|
|
38
|
-
"exports": {
|
|
39
|
-
".": "./dist/index.mjs",
|
|
40
|
-
"./data": "./dist/data/desk-data.mjs",
|
|
41
|
-
"./policy": "./dist/public-control/policy-schema.mjs",
|
|
42
|
-
"./chains": "./dist/chains.mjs",
|
|
43
|
-
"./scanner": "./dist/scanner/index.mjs",
|
|
44
|
-
"./router": "./dist/router/index.mjs",
|
|
45
|
-
"./action-semantics": "./dist/action-semantics.mjs",
|
|
46
|
-
"./address-book": "./dist/address-book.mjs",
|
|
47
|
-
"./nft-gas-war": "./dist/nft-gas-war-guard.mjs",
|
|
48
|
-
"./prepare-envelope": "./dist/prepare-envelope.mjs",
|
|
49
|
-
"./connect": "./dist/onboarding/harness-configs.mjs",
|
|
50
|
-
"./receipts": "./dist/action-receipts.mjs",
|
|
51
|
-
"./risk": "./dist/portfolio-risk.mjs",
|
|
52
|
-
"./watch": "./dist/watch-preferences.mjs",
|
|
53
|
-
"./signals": "./dist/signals/index.mjs"
|
|
54
|
-
},
|
|
55
|
-
"dependencies": {
|
|
56
|
-
"@msgpack/msgpack": "^3.1.3",
|
|
57
|
-
"@noble/curves": "^2.2.0",
|
|
58
|
-
"@noble/hashes": "^2.2.0",
|
|
59
|
-
"@scure/base": "^2.2.0",
|
|
60
|
-
"ethers": "^6.16.0",
|
|
61
|
-
"viem": "^2.55.8"
|
|
11
|
+
"oracle": "bin/oracle.mjs"
|
|
62
12
|
},
|
|
63
13
|
"files": [
|
|
64
|
-
"
|
|
65
|
-
"public/",
|
|
66
|
-
"artifacts/",
|
|
14
|
+
"bin/",
|
|
67
15
|
"README.md",
|
|
68
|
-
"
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
16
|
+
"LICENSE"
|
|
17
|
+
],
|
|
18
|
+
"keywords": [
|
|
19
|
+
"oracle",
|
|
20
|
+
"locals-only"
|
|
21
|
+
],
|
|
22
|
+
"repository": {
|
|
23
|
+
"type": "git",
|
|
24
|
+
"url": "git+https://github.com/demi-hl/oracle.git"
|
|
25
|
+
},
|
|
26
|
+
"homepage": "https://oracle.demi.la"
|
|
72
27
|
}
|