@oracle-agent/oracle 0.1.0 → 0.2.1

package/README.md

@@ -11,13 +11,26 @@ open-source agent runtime from [Nous Research](https://nousresearch.com).
 Oracle itself makes **no model calls and needs no API key**. It is the tool layer
 an agent drives. Bring whatever model your Hermes is already using.
 
-The **public package is prepare-only**: it never takes a private key and never
-broadcasts. Owner-local signer modules may exist in a private tree for operator
-deployments; they are excluded from the npm artifact and from every public
-entrypoint.
+This package is **prepare-only**: it never takes a private key and never
+broadcasts. For agentic trading with **your** keys on **your** machine, install
+the companion [`@oracle-agent/operator`](https://github.com/demi-hl/oracle-operator)
+alongside it — same split we run ourselves.
 
 ---
 
+## Install
+
+```bash
+# prepare-only (safe default)
+npm i @oracle-agent/oracle
+
+# full self-host lane (keys stay on YOUR machine) — same model we run
+npm i @oracle-agent/oracle @oracle-agent/operator
+```
+
+See the operator [SETUP](https://github.com/demi-hl/oracle-operator/blob/main/SETUP.md)
+for local key vault + Hyperliquid sign-and-submit.
+
 ## What Oracle is
 
 Most "AI crypto agent" projects give a model a hot wallet and hope. Oracle does
@@ -78,9 +91,9 @@ Three planes, and the boundary between them is mechanically enforced:
 - **Policy plane** (public) — destination allowlists, slippage guards, route and
   vault attestations, grant schema. Holds no keys; constrains what a signer may
   be asked to do.
-- **Exec plane** (owner-local source only) - signing and broadcast modules exist
-  for private operator deployments, but are excluded from every public package
-  entrypoint and from the npm artifact.
+- **Exec plane** (optional companion) - signing and broadcast live in
+  [`@oracle-agent/operator`](https://github.com/demi-hl/oracle-operator) on
+  your machine with your key. Not in this package or its npm artifact.
 
 `test/custody-boundary.test.mjs` walks the import graph and fails if any public
 module reaches wallet key material or a house signer. The split is a test, not a
@@ -146,7 +159,7 @@ allowlisted the wrong contract.
 | Intents | CoW Protocol |
 | Perps / lending / yield | GMX v2, Morpho, Pendle |
 | Bridges | Across, Hop, Relay |
-| Venues | Hyperliquid (incl. HyperCore staking), Polymarket |
+| Venues | Hyperliquid (core perps + HIP-3 builder dexs + HIP-4 outcomes), Polymarket (read + local CLOB prepare) |
 | NFT | OpenSea, Satflow, Magic Eden (Solana) |
 
 Every provider and every scanner capability declares an honest tier —
@@ -194,8 +207,11 @@ capability-labeled per chain; unconfigured venues stay unavailable instead of fa
 
 ## Install
 
-The npm package is intentionally unpublished while release hardening is in
-progress. Install from source:
+```bash
+npm install @oracle-agent/oracle    # Node >= 20.19.0
+```
+
+Or from source, if you want to run the suite:
 
 ```bash
 git clone https://github.com/demi-hl/oracle.git
@@ -382,3 +398,14 @@ oracle-data-mcp
 
 The code is open source. The **Oracle** name and marks are reserved; please
 don't imply endorsement by an official deployment when shipping a fork.
+
+### Operator hardening (0.4+)
+
+Prefer the local signer daemon so the agent never sees the vault passphrase:
+
+```bash
+npx oracle-signer   # has ORACLE_VAULT_PASSPHRASE
+# agent: ORACLE_SIGNER_URL + ORACLE_SIGNER_TOKEN only
+```
+
+See [oracle-operator SETUP](https://github.com/demi-hl/oracle-operator/blob/main/SETUP.md).

package/SECURITY.md

@@ -70,20 +70,20 @@ A security claim that isn't enforced by a test is just a comment.
 
 ## Residual operator notes
 
-These are not public-package custody holes. They are operator / release-process
-constraints that still apply after the public boundary hardening:
-
-1. **Owner-local signer modules may exist in the git tree** (`hl-exec`,
-   `key-vault`, `oracle-vault`) and are excluded from public entrypoints and the
-   npm artifact. Do not restore them to the public package for compatibility.
-   Before making the repository public, keep that exclusion intentional or move
-   the modules to a private operator repo.
+These are not public-package custody holes. They are operator constraints that
+still apply after the public boundary hardening:
+
+1. **Owner-local signer modules live in the public companion**
+   [`@oracle-agent/operator`](https://github.com/demi-hl/oracle-operator)
+   (`hl-exec`, `key-vault`, `oracle-vault`). Keys stay on the operator's
+   machine. They must not be restored into this prepare-only package or its
+   npm artifact. CI fails if a pack of *this* repo includes those paths.
 2. **Prepare helpers that validate executable routes require an attestation
    secret** (`requireSigned`) so they cannot be used as a softer pre-broadcast
    gate than `enforceTxPolicy`.
 3. **Daily spend ledger locks are pid + TTL based.** A live owner holds the
    lock; a dead pid or expired lock is reclaimed. Override TTL with
    `ORACLE_LEDGER_LOCK_TTL_MS` only if you know you need a longer window.
-4. **GitHub branch protection, code scanning, and vulnerability alerts** are
-   process controls outside this package. Enable them on `main` before treating
-   a public release as fully hardened operations.
+4. **GitHub process controls** (branch protection, CodeQL, secret scanning,
+   Dependabot) are enabled on this public repo and are independent of the
+   package boundary tests.

package/SETUP.md

@@ -5,8 +5,11 @@ a wallet private key. Prepared actions are signed in the user's wallet.
 
 ## Install
 
-The npm package is intentionally unpublished while release hardening is in
-progress. Install the source checkout with Node 20.19 or newer:
+```bash
+npm install @oracle-agent/oracle    # Node >= 20.19.0
+```
+
+Or from source, if you want to run the suite:
 
 ```bash
 git clone https://github.com/demi-hl/oracle.git
@@ -22,7 +25,7 @@ Oracle has two distribution boundaries and they are separate on purpose:
 | Plane | What it does | Needs a key? |
 |---|---|---|
 | **Read / prepare** | Market data, quotes, and *unsigned* transactions or EIP-712 actions | No, mostly |
-| **Owner-local source lane** | Optional private operator signing code, excluded from npm and public entrypoints | Yes |
+| **Owner-local source lane** | Optional companion `@oracle-agent/operator` — keys on YOUR machine | Yes |
 
 A prepared object is inert. It becomes real only when something signs it. You
 choose whether that something is your browser wallet or separately operated
@@ -129,8 +132,11 @@ Keeps the secret out of the process environment.
 
 ### 3. An encrypted vault (recommended)
 
+Install the companion and use its CLI (not shipped in this package):
+
 ```bash
-node bin/oracle-vault.mjs encrypt ~/.config/oracle/keys/hl.key
+npm i -g @oracle-agent/operator   # or npm i -D in your project
+oracle-vault encrypt ~/.config/oracle/keys/hl.key
 # writes  hl.key.vault.json          (scrypt N=2^17 + AES-256-GCM)
 # moves   hl.key -> hl.key.plaintext.bak
 
@@ -138,23 +144,22 @@ export ORACLE_VAULT_PASSPHRASE="..."         # or be prompted
 export HL_KEY_FILE=~/.config/oracle/keys/hl.key.vault.json
 
 # verify it unlocks, THEN destroy the plaintext backup
-node bin/oracle-vault.mjs inspect ~/.config/oracle/keys/hl.key.vault.json
+oracle-vault inspect ~/.config/oracle/keys/hl.key.vault.json
 shred -u ~/.config/oracle/keys/hl.key.plaintext.bak
 ```
 
-Oracle detects a vault file and decrypts it in memory. The key is never written
-back to disk, never logged, and never included in any returned object — there
-is a test asserting exactly that.
+The operator vault decrypts in memory only. The key is never written back to
+disk, never logged, and never included in any returned object.
 
 **What the vault does and does not protect.** It defends against a key file read
 by something that is not you: a synced backup, a stolen laptop at rest, an
 overly-broad `chmod`, a leaked tarball. It does **not** defend against malware
-running as your user while Oracle is unlocked. Nothing file-based does. If you
-need that, use a hardware wallet and the prepare-only path.
+running as your user while the vault is unlocked. Nothing file-based does. If
+you need that, use a hardware wallet and the prepare-only path.
 
 ```bash
-node bin/oracle-vault.mjs rekey <vault>     # rotate the passphrase
-node bin/oracle-vault.mjs inspect <vault>   # show KDF params, no secret
+oracle-vault rekey <vault>     # rotate the passphrase
+oracle-vault inspect <vault>   # show KDF params, no secret
 ```
 
 ---
@@ -178,10 +183,10 @@ const order = await data.call("hl-perps", "prepareOrder", {
 
 ### B. Owner-local execution
 
-The public `data.call()` facade refuses `hl-exec`. Private operator deployments
-must wire the source-only signer behind their own authenticated execution
-boundary. It is intentionally not exported or documented as a public package
-API.
+The public `data.call()` facade refuses `hl-exec`. Operator signing lives in
+[`@oracle-agent/operator`](https://github.com/demi-hl/oracle-operator) on your
+machine with your key. Import `hlSignAndSubmit` from that package — never from
+this one. Do not expose it on a public HTTP port.
 
 The public prepare path hard-caps slippage at 100 bps, bounds leverage by the
 asset maximum, rounds sizes and prices to venue precision, and makes brackets
@@ -233,3 +238,58 @@ routing is what makes running several practical instead of theoretical.
 
 Everything still works fine with a single provider. It is just better with a
 router that knows which brain to use for which job.
+
+### Operator hardening (0.4+)
+
+Prefer the local signer daemon so the agent never sees the vault passphrase:
+
+```bash
+npx oracle-signer   # has ORACLE_VAULT_PASSPHRASE
+# agent: ORACLE_SIGNER_URL + ORACLE_SIGNER_TOKEN only
+```
+
+See [oracle-operator SETUP](https://github.com/demi-hl/oracle-operator/blob/main/SETUP.md).
+
+## Local HIP-3 / HIP-4 / Polymarket (no VPS)
+
+### Hyperliquid HIP-3 (builder perps)
+```js
+const prep = await data.call("hl-perps", "prepareOrder", {
+  coin: "xyz:TSLA", side: "buy", type: "limit", price: "250", size: "1",
+});
+await hlSignAndSubmit(prep, { keyFile, userInitiated: true });
+// or signViaDaemon({ surface: "hl", prepared: prep, userInitiated: true })
+```
+
+### Hyperliquid HIP-4 (outcomes)
+```js
+const prep = await data.call("hl-outcome", "prepareOrder", {
+  outcome: 969, side: "yes", // or coin: "#9690"
+  side: "buy", type: "limit", price: "0.42", size: "20",
+});
+await hlSignAndSubmit(prep, { keyFile, userInitiated: true });
+```
+
+### Polymarket (local CLOB)
+```js
+const prep = await data.call("poly-clob", "prepareOrder", {
+  tokenId, side: "BUY", price: 0.45, size: 10,
+  maker: eoa, signer: eoa, tickSize: "0.01",
+});
+// signer process needs POLYMARKET_API_KEY/SECRET/PASSPHRASE + key
+await polySignAndSubmit(prep, { keyFile, userInitiated: true });
+// or signViaDaemon({ surface: "poly", prepared: prep, userInitiated: true })
+```
+
+## Protocol templates (builder)
+
+Gated Foundry templates under `protocols/templates/`.
+
+```bash
+# requires Foundry (forge)
+cd protocols/templates/safe-erc20 && forge install && forge test
+npm run protocol:gate -- safe-erc20
+```
+
+`prepareTemplateDeploy` will not stamp an unsigned deploy unless `forge test` passes.
+**Not a paid security-firm audit** — see each template `SECURITY.md`.

package/bin/desk-server.mjs

@@ -421,7 +421,9 @@ const server = createServer(async (req, res) => {
     if (e instanceof HttpError) {
       return send(res, e.status, { error: e.code, message: e.message });
     }
-    return send(res, 500, { error: String(e.message || e) });
+    // Never echo raw Error objects or stacks to the client.
+    console.error("desk-server internal error:", e && e.stack ? e.stack : e);
+    return send(res, 500, { error: "internal-error" });
   }
 });
 

package/docs/architecture.md

@@ -22,8 +22,9 @@ Three planes. The boundary between them is enforced by a test, not a convention.
                          x  no import may cross
                          |
    +-------------------------------------------+
-   |  PRIVATE (not published)                  |
-   |  keystore, house signer, exec-server      |
+   |  OWNER-LOCAL (companion package)          |
+   |  @oracle-agent/operator                   |
+   |  key-vault / hl-exec / oracle-vault       |
    +-------------------------------------------+
 ```
 
@@ -41,10 +42,10 @@ That is why the boundary is a test (`test/custody-boundary.test.mjs`) rather tha
 paragraph in a README. It walks the import graph from every shipped entrypoint and
 fails on:
 
-- a private module present in the tree
 - any public module importing signer or key material
-- a dangling local import (extraction left something behind)
+- a dangling local import that reaches a signer from a shipped entrypoint
 - a secret-shaped literal anywhere
+- a packed npm artifact that still contains signer/vault modules
 
 ## Data plane
 
@@ -127,9 +128,9 @@ No lane pins a model. `profile.json` carries a capability *class*
 (`strong-reasoner`, `fast-tool-caller`), so the installer never writes a vendor into
 a user's config.
 
-## What is not here
+## What is not in the public package
 
-The exec plane: keystore, house signer, local-signer service, exec-server,
-capability minting, and the venue adapters that hold signing authority. That is
-operator infrastructure. Its absence is the point — a self-hosted Oracle has nothing
-to steal.
+House custody, an always-on exec server, and capability minting are not shipped.
+Owner-local signer modules (`key-vault`, `hl-exec`, `oracle-vault`) live in the
+companion package `@oracle-agent/operator` on the user's machine. This prepare
+package has nothing to steal: it never takes a key and never broadcasts.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@oracle-agent/oracle",
-  "version": "0.1.0",
-  "description": "Oracle: prepare-only multichain agent control plane. Policy-bounded intents for a user-signed wallet. Self-custody by default — the public package never takes your key. Built for Hermes; no model key required.",
+  "version": "0.2.1",
+  "description": "Oracle: prepare-only multichain agent control plane. Policy-bounded intents for a user-signed wallet. Self-custody by default \u2014 the public package never takes your key. Built for Hermes; no model key required.",
   "license": "Apache-2.0",
   "type": "module",
   "publishConfig": {
@@ -40,7 +40,8 @@
     "./chains": "./src/chains.mjs",
     "./scanner": "./src/scanner/index.mjs",
     "./router": "./src/router/index.mjs",
-    "./nft-gas-war": "./src/nft-gas-war-guard.mjs"
+    "./nft-gas-war": "./src/nft-gas-war-guard.mjs",
+    "./prepare-envelope": "./src/prepare-envelope.mjs"
   },
   "scripts": {
     "test": "ORACLE_TEST_ISOLATE_SECRETS=1 ORACLE_ROUTE_ATTESTATION_SECRET=oracle-unit-test-secret node --test test/*.test.mjs",
@@ -58,7 +59,9 @@
     "route": "node bin/oracle-route.mjs",
     "scan:secrets": "node scripts/secret-scan.mjs",
     "test:count": "node scripts/check-test-count.mjs",
-    "test:count:update": "node scripts/check-test-count.mjs --update"
+    "test:count:update": "node scripts/check-test-count.mjs --update",
+    "test:protocol-templates": "RUN_PROTOCOL_TEMPLATE_TESTS=1 node --test test/protocol-templates.test.mjs",
+    "protocol:gate": "node scripts/protocol-template-gate.mjs"
   },
   "dependencies": {
     "@msgpack/msgpack": "^3.1.3",
@@ -83,8 +86,11 @@
     "docs/",
     "examples/",
     "scripts/",
-    "!bin/oracle-vault.mjs",
-    "!src/key-vault.mjs",
-    "!src/data/providers/hl-exec.mjs"
+    "protocols/templates/**/src/**",
+    "protocols/templates/**/test/**",
+    "protocols/templates/**/foundry.toml",
+    "protocols/templates/**/remappings.txt",
+    "protocols/templates/**/SECURITY.md",
+    "src/protocol-templates/**"
   ]
 }

package/protocols/templates/safe-erc20/SECURITY.md

@@ -0,0 +1,16 @@
+# SafeERC20 template security notice
+
+**Not a paid security-firm audit.**
+
+This template is:
+- fixed-supply ERC20
+- Ownable2Step + pause
+- no tax / blacklist / upgrade proxy
+- covered by Foundry unit tests in `test/`
+
+Before mainnet capital:
+1. Keep or expand Foundry tests green
+2. Run static analysis (Slither/Aderyn) if available
+3. Book an independent Solidity auditor for any real TVL
+
+Oracle only prepares unsigned deploys after the JS gate confirms `forge test` passes.

package/protocols/templates/safe-erc20/foundry.toml

@@ -0,0 +1,12 @@
+[profile.default]
+src = "src"
+out = "out"
+libs = ["lib"]
+solc = "0.8.24"
+optimizer = true
+optimizer_runs = 200
+ffi = false
+fs_permissions = [{ access = "read", path = "./" }]
+
+[fmt]
+line_length = 100

package/protocols/templates/safe-erc20/remappings.txt

@@ -0,0 +1,2 @@
+@openzeppelin/contracts/=lib/openzeppelin-contracts/contracts/
+forge-std/=lib/forge-std/src/

package/protocols/templates/safe-erc20/src/SafeERC20.sol

@@ -0,0 +1,53 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.24;
+
+import {ERC20} from "@openzeppelin/contracts/token/ERC20/ERC20.sol";
+import {ERC20Burnable} from "@openzeppelin/contracts/token/ERC20/extensions/ERC20Burnable.sol";
+import {ERC20Pausable} from "@openzeppelin/contracts/token/ERC20/extensions/ERC20Pausable.sol";
+import {Ownable} from "@openzeppelin/contracts/access/Ownable.sol";
+import {Ownable2Step} from "@openzeppelin/contracts/access/Ownable2Step.sol";
+
+/**
+ * @title SafeERC20
+ * @notice Opinionated fixed-supply ERC20 for Oracle protocol-builder v1.
+ *
+ * Security posture (templates, NOT a firm audit):
+ * - Fixed supply minted once to `initialHolder` in constructor (no hidden mint).
+ * - Ownable2Step ownership (no single-tx accidental transfer).
+ * - Pausable emergency stop (owner only).
+ * - No transfer tax, no blacklist, no max-tx, no trading cooldown.
+ * - No upgradeability / no proxy.
+ * - Burn optional by holders only (ERC20Burnable).
+ *
+ * This is a reviewed starter template with Foundry tests. It is NOT a paid
+ * security-firm audit. Do not put mainnet TVL on custom forks without one.
+ */
+contract SafeERC20 is ERC20, ERC20Burnable, ERC20Pausable, Ownable2Step {
+    constructor(
+        string memory name_,
+        string memory symbol_,
+        uint256 initialSupply,
+        address initialHolder,
+        address initialOwner
+    ) ERC20(name_, symbol_) Ownable(initialOwner) {
+        require(initialHolder != address(0), "SafeERC20: holder zero");
+        require(initialOwner != address(0), "SafeERC20: owner zero");
+        require(initialSupply > 0, "SafeERC20: supply zero");
+        _mint(initialHolder, initialSupply);
+    }
+
+    function pause() external onlyOwner {
+        _pause();
+    }
+
+    function unpause() external onlyOwner {
+        _unpause();
+    }
+
+    function _update(address from, address to, uint256 value)
+        internal
+        override(ERC20, ERC20Pausable)
+    {
+        super._update(from, to, value);
+    }
+}

package/protocols/templates/safe-erc20/test/SafeERC20.t.sol

@@ -0,0 +1,72 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.24;
+
+import {Test} from "forge-std/Test.sol";
+import {SafeERC20} from "../src/SafeERC20.sol";
+
+contract SafeERC20Test is Test {
+    SafeERC20 internal token;
+    address internal owner = makeAddr("owner");
+    address internal holder = makeAddr("holder");
+    address internal alice = makeAddr("alice");
+    address internal bob = makeAddr("bob");
+
+    uint256 internal constant SUPPLY = 1_000_000 ether;
+
+    function setUp() public {
+        token = new SafeERC20("Safe", "SAFE", SUPPLY, holder, owner);
+    }
+
+    function test_fixedSupply_noHiddenMint() public view {
+        assertEq(token.totalSupply(), SUPPLY);
+        assertEq(token.balanceOf(holder), SUPPLY);
+        assertEq(token.balanceOf(owner), 0);
+    }
+
+    function test_transfer_noTax() public {
+        vm.prank(holder);
+        token.transfer(alice, 100 ether);
+        assertEq(token.balanceOf(alice), 100 ether);
+        assertEq(token.balanceOf(holder), SUPPLY - 100 ether);
+    }
+
+    function test_pause_blocksTransfers() public {
+        vm.prank(owner);
+        token.pause();
+        vm.prank(holder);
+        vm.expectRevert();
+        token.transfer(alice, 1 ether);
+    }
+
+    function test_onlyOwner_canPause() public {
+        vm.prank(alice);
+        vm.expectRevert();
+        token.pause();
+    }
+
+    function test_ownable2Step_requiresAccept() public {
+        vm.prank(owner);
+        token.transferOwnership(alice);
+        // still owner until accept
+        assertEq(token.owner(), owner);
+        vm.prank(alice);
+        token.acceptOwnership();
+        assertEq(token.owner(), alice);
+    }
+
+    function test_burn_reducesSupply() public {
+        vm.prank(holder);
+        token.burn(10 ether);
+        assertEq(token.totalSupply(), SUPPLY - 10 ether);
+    }
+
+    function test_rejectZeroHolder() public {
+        vm.expectRevert(bytes("SafeERC20: holder zero"));
+        new SafeERC20("X", "X", SUPPLY, address(0), owner);
+    }
+
+    function test_rejectZeroSupply() public {
+        vm.expectRevert(bytes("SafeERC20: supply zero"));
+        new SafeERC20("X", "X", 0, holder, owner);
+    }
+}