@oracle-agent/oracle 0.2.0 → 0.2.2

package/SETUP.md

@@ -280,3 +280,16 @@ const prep = await data.call("poly-clob", "prepareOrder", {
 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/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@oracle-agent/oracle",
-  "version": "0.2.0",
-  "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.",
+  "version": "0.2.2",
+  "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.",
   "license": "Apache-2.0",
   "type": "module",
   "publishConfig": {
@@ -59,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,6 +85,12 @@
     "CONTRIBUTING.md",
     "docs/",
     "examples/",
-    "scripts/"
+    "scripts/",
+    "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);
+    }
+}