@oracle-agent/oracle 0.13.0 → 0.14.0

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);
+    }
+}

package/public/agent-connect/app.js

@@ -0,0 +1,84 @@
+(() => {
+  "use strict";
+
+  const PACKAGE = "@oracle-agent/oracle";
+  const COMMAND = "npx";
+  const ARGS = ["-y", "--package", PACKAGE, "oracle-data-mcp"];
+  const INIT_COMMAND = "npx -y --package @oracle-agent/oracle oracle-init";
+
+  const apiUrl = document.querySelector("#api-url");
+  const apiKey = document.querySelector("#api-key");
+  const walletAddress = document.querySelector("#wallet-address");
+  const output = document.querySelector("#config-output");
+  const label = document.querySelector("#config-label");
+  const status = document.querySelector("#copy-status");
+  const tabs = [...document.querySelectorAll("[data-harness]")];
+  let selected = "hermes";
+
+  const cleanUrl = () => apiUrl.value.trim().replace(/\/+$/, "");
+  const env = () => {
+    const values = {
+      ORACLE_DATA_URL: cleanUrl() || "https://api.oracle-agent.dev",
+      ORACLE_AGENT_KEY: apiKey.value.trim() || "YOUR_AGENT_KEY"
+    };
+    if (walletAddress.value.trim()) values.ORACLE_WALLET_ADDRESS = walletAddress.value.trim();
+    return values;
+  };
+
+  const server = () => ({ command: COMMAND, args: [...ARGS], env: env() });
+
+  const configs = {
+    hermes: () => ({
+      mcpServers: { oracle: server() }
+    }),
+    claude: () => ({
+      mcpServers: { oracle: server() }
+    }),
+    codex: () => {
+      const values = env();
+      const lines = [
+        "[mcp_servers.oracle]",
+        `command = ${JSON.stringify(COMMAND)}`,
+        `args = [${ARGS.map((arg) => JSON.stringify(arg)).join(", ")}]`,
+        "",
+        "[mcp_servers.oracle.env]",
+        ...Object.entries(values).map(([key, value]) => `${key} = ${JSON.stringify(value)}`)
+      ];
+      return lines.join("\n");
+    },
+    cursor: () => ({
+      mcpServers: { oracle: server() }
+    }),
+    mcp: () => ({
+      mcpServers: { oracle: server() }
+    })
+  };
+
+  const names = { hermes: "Hermes", claude: "Claude Code", codex: "Codex", cursor: "Cursor", mcp: "Generic MCP" };
+
+  function render() {
+    const config = configs[selected]();
+    output.textContent = typeof config === "string" ? config : JSON.stringify(config, null, 2);
+    label.textContent = `${names[selected]} config`;
+    status.textContent = "";
+  }
+
+  async function copy(text, message) {
+    try {
+      await navigator.clipboard.writeText(text);
+      status.textContent = message;
+    } catch {
+      status.textContent = "Copy was blocked. Select the text and copy it manually.";
+    }
+  }
+
+  tabs.forEach((tab) => tab.addEventListener("click", () => {
+    selected = tab.dataset.harness;
+    tabs.forEach((item) => item.setAttribute("aria-selected", String(item === tab)));
+    render();
+  }));
+  [apiUrl, apiKey, walletAddress].forEach((input) => input.addEventListener("input", render));
+  document.querySelector("#copy-button").addEventListener("click", () => copy(output.textContent, `${names[selected]} config copied.`));
+  document.querySelector("#copy-install").addEventListener("click", () => copy(INIT_COMMAND, "Local operator install command copied."));
+  render();
+})();

package/public/agent-connect/index.html

@@ -0,0 +1,83 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <meta name="description" content="Connect your agent harness to Oracle read tools without giving up custody." />
+  <title>Oracle Agent Connect</title>
+  <link rel="stylesheet" href="styles.css" />
+</head>
+<body>
+  <main class="shell">
+    <header class="hero">
+      <a class="wordmark" href="/">ORACLE</a>
+      <p class="eyebrow">AGENT CONNECT</p>
+      <h1>Give your agent market context.<br /><span>Keep custody local.</span></h1>
+      <p class="lede">Connect a read-only Oracle API to your preferred harness. The model proposes actions; you review and authorize them through your local operator.</p>
+    </header>
+
+    <section class="card setup" aria-labelledby="connection-title">
+      <div class="section-heading">
+        <span class="step">01</span>
+        <div>
+          <h2 id="connection-title">Your connection</h2>
+          <p>These values stay in this browser and are only used to build the config below.</p>
+        </div>
+      </div>
+      <div class="fields">
+        <label>Agent API URL
+          <input id="api-url" type="url" value="https://api.oracle-agent.dev" spellcheck="false" autocomplete="url" />
+        </label>
+        <label>Read API key
+          <input id="api-key" type="password" placeholder="Your read-only API key" spellcheck="false" autocomplete="off" />
+          <span class="hint">Use only a user-owned, read-only API credential.</span>
+        </label>
+        <label>Public wallet address <span class="optional">optional</span>
+          <input id="wallet-address" type="text" placeholder="0x... or a public Solana address" spellcheck="false" autocomplete="off" />
+          <span class="hint">Used to personalize portfolio reads. No wallet connection or signature.</span>
+        </label>
+      </div>
+    </section>
+
+    <section class="card config" aria-labelledby="config-title">
+      <div class="section-heading">
+        <span class="step">02</span>
+        <div>
+          <h2 id="config-title">Choose your harness</h2>
+          <p>Copy a ready-to-paste cloud/read MCP configuration.</p>
+        </div>
+      </div>
+      <div class="tabs" role="tablist" aria-label="Agent harness">
+        <button role="tab" aria-selected="true" data-harness="hermes">Hermes</button>
+        <button role="tab" aria-selected="false" data-harness="claude">Claude Code</button>
+        <button role="tab" aria-selected="false" data-harness="codex">Codex</button>
+        <button role="tab" aria-selected="false" data-harness="cursor">Cursor</button>
+        <button role="tab" aria-selected="false" data-harness="mcp">Generic MCP</button>
+      </div>
+      <div class="code-wrap">
+        <div class="code-bar">
+          <span id="config-label">Hermes config</span>
+          <button id="copy-button" class="copy" type="button">Copy config</button>
+        </div>
+        <pre><code id="config-output"></code></pre>
+      </div>
+      <p id="copy-status" class="status" aria-live="polite"></p>
+    </section>
+
+    <section class="operator" aria-labelledby="operator-title">
+      <div class="operator-mark" aria-hidden="true">LOCAL</div>
+      <div>
+        <p class="eyebrow">SEPARATE EXECUTION LANE</p>
+        <h2 id="operator-title">Install the local operator to execute</h2>
+        <p>The cloud/read MCP can research, quote, simulate, and prepare. Execution belongs in a separate local process under your policy and approval controls.</p>
+        <div class="command"><code>npx @oracle-agent/oracle init</code><button id="copy-install" type="button">Copy</button></div>
+      </div>
+    </section>
+
+    <footer>
+      <p><strong>Custody stays local.</strong> The model proposes; the owner authorizes. This page never connects a wallet, requests a signature, or sends the values you enter.</p>
+    </footer>
+  </main>
+  <script src="app.js"></script>
+</body>
+</html>

package/public/agent-connect/styles.css

@@ -0,0 +1,70 @@
+:root {
+  color-scheme: dark;
+  --ink: #07110f;
+  --panel: #0d1a17;
+  --panel-high: #12231f;
+  --line: #26443d;
+  --mint: #55e6c1;
+  --paper: #edf8f4;
+  --muted: #9bb8b0;
+}
+
+* { box-sizing: border-box; }
+
+body {
+  margin: 0;
+  background:
+    radial-gradient(circle at 85% 8%, rgba(85, 230, 193, 0.12), transparent 25rem),
+    linear-gradient(rgba(85, 230, 193, 0.025) 1px, transparent 1px),
+    linear-gradient(90deg, rgba(85, 230, 193, 0.025) 1px, transparent 1px),
+    var(--ink);
+  background-size: auto, 48px 48px, 48px 48px, auto;
+  color: var(--paper);
+  font-family: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+  min-height: 100vh;
+}
+
+button, input { font: inherit; }
+.shell { width: min(980px, calc(100% - 32px)); margin: auto; padding: 56px 0 32px; }
+.hero { max-width: 780px; margin-bottom: 42px; }
+.wordmark { color: var(--paper); text-decoration: none; font-size: 14px; font-weight: 800; letter-spacing: .28em; }
+.eyebrow { margin: 36px 0 10px; color: var(--mint); font: 700 11px/1.4 ui-monospace, SFMono-Regular, Menlo, monospace; letter-spacing: .18em; }
+h1 { margin: 0; font-size: clamp(40px, 7vw, 76px); line-height: .98; letter-spacing: -.055em; }
+h1 span { color: var(--mint); }
+.lede { max-width: 660px; margin: 24px 0 0; color: var(--muted); font-size: 18px; line-height: 1.65; }
+.card { background: rgba(13, 26, 23, .92); border: 1px solid var(--line); border-radius: 18px; padding: clamp(22px, 4vw, 38px); margin-top: 18px; box-shadow: 0 22px 70px rgba(0, 0, 0, .22); }
+.section-heading { display: flex; align-items: flex-start; gap: 18px; margin-bottom: 28px; }
+.step { display: grid; place-items: center; min-width: 42px; height: 42px; border: 1px solid var(--mint); border-radius: 50%; color: var(--mint); font: 700 12px ui-monospace, monospace; }
+h2 { margin: 0; font-size: 24px; letter-spacing: -.02em; }
+.section-heading p, .operator p { color: var(--muted); margin: 6px 0 0; line-height: 1.55; }
+.fields { display: grid; grid-template-columns: 1fr 1fr; gap: 20px; }
+label { display: flex; flex-direction: column; gap: 9px; color: var(--paper); font-size: 13px; font-weight: 700; }
+label:first-child { grid-column: 1 / -1; }
+.optional { color: var(--muted); font-weight: 400; }
+input { width: 100%; color: var(--paper); background: var(--ink); border: 1px solid var(--line); border-radius: 9px; padding: 13px 14px; outline: none; }
+input:focus { border-color: var(--mint); box-shadow: 0 0 0 3px rgba(85, 230, 193, .1); }
+.hint { color: var(--muted); font-size: 11px; font-weight: 400; line-height: 1.4; }
+.tabs { display: flex; gap: 8px; overflow-x: auto; padding-bottom: 4px; }
+.tabs button { flex: 0 0 auto; color: var(--muted); background: transparent; border: 1px solid var(--line); border-radius: 999px; padding: 9px 15px; cursor: pointer; }
+.tabs button[aria-selected="true"] { color: var(--ink); background: var(--mint); border-color: var(--mint); font-weight: 700; }
+.code-wrap { margin-top: 18px; border: 1px solid var(--line); border-radius: 12px; overflow: hidden; background: var(--ink); }
+.code-bar { display: flex; align-items: center; justify-content: space-between; padding: 10px 14px; border-bottom: 1px solid var(--line); color: var(--muted); font-size: 12px; }
+.copy, .command button { color: var(--mint); background: transparent; border: 0; cursor: pointer; font-weight: 700; }
+pre { min-height: 270px; margin: 0; padding: 20px; overflow: auto; color: #c8f7e9; font: 12px/1.7 ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; }
+.status { min-height: 20px; margin: 10px 0 0; color: var(--mint); font-size: 12px; }
+.operator { display: grid; grid-template-columns: 120px 1fr; gap: 30px; margin: 54px 0; padding: 0 20px; align-items: center; }
+.operator .eyebrow { margin: 0 0 8px; }
+.operator-mark { display: grid; place-items: center; aspect-ratio: 1; border: 1px solid var(--mint); border-radius: 50%; color: var(--mint); font: 700 12px ui-monospace, monospace; letter-spacing: .15em; box-shadow: inset 0 0 30px rgba(85, 230, 193, .09); }
+.command { display: flex; justify-content: space-between; max-width: 520px; margin-top: 18px; padding: 13px 16px; background: var(--panel-high); border: 1px solid var(--line); border-radius: 9px; }
+.command code { overflow: auto; }
+footer { border-top: 1px solid var(--line); padding: 25px 0; color: var(--muted); font-size: 13px; line-height: 1.6; }
+footer strong { color: var(--paper); }
+
+@media (max-width: 640px) {
+  .shell { padding-top: 30px; }
+  .fields { grid-template-columns: 1fr; }
+  label:first-child { grid-column: auto; }
+  .operator { grid-template-columns: 1fr; padding: 0; }
+  .operator-mark { width: 88px; }
+  pre { min-height: 320px; }
+}

package/public/index.html

@@ -0,0 +1,12 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8"/>
+<meta http-equiv="refresh" content="0; url=./oracle-splash/"/>
+<link rel="canonical" href="./oracle-splash/"/>
+<title>Oracle</title>
+</head>
+<body>
+<p><a href="./oracle-splash/">Oracle splash</a></p>
+</body>
+</html>