safehands-pharos 1.2.0 → 1.2.4

package/README.md

@@ -1,481 +1,442 @@
 <p align="center">
   <img src="https://img.shields.io/badge/TypeScript-3178C6?style=for-the-badge&logo=typescript&logoColor=white" />
-  <img src="https://img.shields.io/badge/MCP_Skill-000000?style=for-the-badge&logo=anthropic&logoColor=white" />
+  <img src="https://img.shields.io/badge/MCP_Skill-000000?style=for-the-badge" />
   <img src="https://img.shields.io/badge/Pharos_Atlantic-688689-blueviolet?style=for-the-badge" />
-  <img src="https://img.shields.io/badge/Tools-17-orange?style=for-the-badge" />
-  <img src="https://img.shields.io/badge/License-MIT-green?style=for-the-badge" />
-  <img src="https://img.shields.io/badge/Security-Self--Audited-blue?style=for-the-badge" />
-  <img src="https://img.shields.io/npm/v/safehands-pharos?style=for-the-badge&logo=npm&logoColor=white&color=CB3837" />
+  <img src="https://img.shields.io/badge/Tools-27-orange?style=for-the-badge" />
+  <img src="https://img.shields.io/badge/Testnet_Only-SAFE-blue?style=for-the-badge" />
 </p>
 
-<h1 align="center">🛡️ SafeHands</h1>
+# SafeHands-Pharos: Transaction Safety Firewall for AI Agents
 
-<p align="center">
-  <strong>The execution safety layer for Pharos agents.</strong><br/>
-  <em>"Agents that execute without thinking are dangerous. SafeHands executes anything on Pharos — but never blindly."</em>
-</p>
+SafeHands-Pharos is a **Pharos Skill Engine-compatible MCP package** that protects AI agents before they execute payments, token approvals, swaps, x402 paid requests, or contract interactions.
 
-<p align="center">
-  <a href="#-the-problem">Problem</a> •
-  <a href="#-the-solution">Solution</a> •
-  <a href="#-tools-17">Tools</a> •
-  <a href="#-agent-integration">Agent Integration</a> •
-  <a href="#-composability">Composability</a> •
-  <a href="#-quick-start">Quick Start</a> •
-  <a href="#%EF%B8%8F-on-chain-risk-registry">Registry</a> •
-  <a href="#-live-transaction-proof">Proof</a> •
-  <a href="https://www.npmjs.com/package/safehands-pharos">npm</a>
-</p>
+Before an AI agent sends a payment, approves tokens, swaps assets, publishes risk data, or pays an x402 resource, SafeHands runs a policy-based preflight check and returns a deterministic decision:
+
+```text
+ALLOW | WARN | BLOCK | REQUIRE_CONFIRMATION | REQUIRE_FUNDING | REQUIRE_TOKEN_REVIEW
+```
+
+Every decision includes a risk level, human-readable reasons, required next actions, environment metadata, and structured JSON that agents can parse.
+
+> **Testnet scope:** SafeHands targets **Pharos Atlantic Testnet only**. It is not audited for mainnet and should not be used with mainnet funds.
 
 ---
 
-## ❗ The Problem
+## Why AI Agents Need Transaction Safety Middleware
 
-AI agents on Pharos move **real value**. Swaps, payments, approvals — all executed autonomously, with real tokens at stake.
+Autonomous agents can now hold wallets, call APIs, pay x402 resources, approve tokens, and interact on-chain. Generic Web3 tools usually answer: "Can this transaction be sent?" SafeHands answers a more important question first:
 
-Most agent execution skills today just execute. They don't assess. They don't simulate. They don't protect.
+> **Should this action be allowed at all?**
 
-| Risk | What goes wrong |
-|------|----------------|
-| **Slippage attacks** | Agent swaps at a terrible price — thin liquidity, high impact, value lost |
-| **Blind transfers** | Agent sends to a wrong, empty, or flagged address — funds gone |
-| **Failed transactions** | Agent wastes gas on transactions destined to revert — no pre-check |
-| **No cross-agent trust** | Agent B interacts with a wallet that Agent A already flagged as dangerous |
+Common agent-execution risks:
 
-When agents control real wallets in the Pharos AI economy, **"just execute" is not a strategy**.
+| Risk | What can go wrong | SafeHands guardrail |
+|---|---|---|
+| Unlimited approval | Agent approves a malicious spender forever | Blocks unlimited approval by default |
+| Wrong chain | Agent signs on mainnet or the wrong testnet | Blocks mainnet and chain ID mismatch |
+| Risky x402 URL | Agent pays or fetches SSRF-sensitive endpoints | Blocks localhost/private IPs by default |
+| Overspending | Agent pays above configured limits | Blocks payments above limits |
+| Unknown token | Agent swaps/approves unverified token | Warns or requires token review |
+| Missing signer | Agent tries write action without safe signer | Returns structured signer error |
 
 ---
 
-## ✅ The Solution
+## What SafeHands Is, and What It Is Not
 
-SafeHands is an **MCP Skill** — a 17-tool risk intelligence middleware layer. It sits between agent intent and on-chain execution, scoring risk, simulating outcomes, and gating dangerous operations automatically.
+SafeHands is a **Transaction Safety Firewall / Guardrail Skill** for Pharos agents. SafeHands is a guardrail layer before execution, not a generic Web3 toolbox.
 
-```
-┌──────────────────────────────────────────────────────┐
-│                    Agent Intent                      │
-│         "Swap 100 PHRS to USDC"                      │
-└──────────────────┬───────────────────────────────────┘
-                   │
-                   ▼
-┌──────────────────────────────────────────────────────┐
-│              🛡️  SafeHands Layer                      │
-│                                                      │
-│   1. assess_risk         → Score 12/100, proceed     │
-│   2. simulate_transaction → Would succeed, 166 USDC  │
-│   3. estimate_gas        → 0.004 PHRS, sufficient    │
-│   4. execute_swap        → ✅ TX confirmed           │
-│                                                      │
-│   Score > 80?  → 🚫 BLOCKED automatically            │
-│   Score < 80?  → ✅ PROCEED with full transparency   │
-└──────────────────────────────────────────────────────┘
-                   │
-                   ▼
-            Pharos Atlantic
-              (on-chain)
+It is **not** a generic Web3 toolbox and does not replace Pharos Skill Engine. It complements the Skill Engine by adding a safety layer before execution:
+
+```text
+User intent
+→ SafeHands preflight
+→ ALLOW / WARN / BLOCK
+→ Pharos Skill Engine or MCP execution if safe
+→ SafeHands risk report
 ```
 
-SafeHands is not an agent — it's the safety layer other agents depend on.
+### Difference from Reputation Systems
 
-### Before vs After
+SafeHands is also different from pure reputation systems:
 
-| Without SafeHands | With SafeHands |
+| System type | Main question |
 |---|---|
-| Agent swaps at 12% price impact — value lost | `assess_risk` scores 87/100 — swap blocked automatically |
-| Agent sends 950 PHRS to unverified address — funds gone | `send_payment` warns: using 95% of wallet balance |
-| Agent wastes gas on transaction that reverts | `simulate_transaction` catches revert reason before execution |
-| Agent B interacts with wallet Agent A flagged dangerous | `query_risk_registry` returns score 92 — interaction refused |
+| Agent reputation, such as AgentLeash-style trust systems | "Can I trust this agent?" |
+| SafeHands | "Can I trust this action right now?" |
 
-### Risk Engine — 5 Dimensions
+SafeHands can use reputation signals, but its core purpose is **action-level risk gating**.
 
-| Dimension | Weight | What it checks |
-|-----------|--------|----------------|
-| Liquidity Risk | 25% | DODO route available? Price impact? |
-| Slippage Risk | 25% | Estimated slippage from DODO quote |
-| Counterparty Risk | 20% | Address valid? Zero address? Self-send? |
-| Balance Risk | 15% | Sufficient balance + gas buffer? |
-| Market Condition Risk | 15% | Block times, gas price, chain health |
+---
 
-**Thresholds:**
-- `0–30` → ✅ **proceed**
-- `31–60` → ⚠️ **caution** — review recommended
-- `61–80` → 🟠 **high** — agent warned
-- `81–100` → 🚫 **block** — execution prevented
+## Pharos Atlantic Testnet Context
 
-> To our knowledge, SafeHands is the only MCP Skill on Pharos with a built-in multi-dimension risk scoring engine and an on-chain reputation registry for cross-agent trust.
+Default project configuration:
 
----
+| Item | Value |
+|---|---|
+| Environment | `atlantic-testnet` |
+| Chain ID | `688689` |
+| RPC URL | `https://atlantic.dplabs-internal.com` |
+| Explorer | `https://atlantic.pharosscan.xyz/` |
+| Mainnet support | `false` |
+| RiskRegistry | `0x61962a6c812ee9f57b207e1ea47c19ae70bb7141` |
+| Primary Pharos Skill Engine USDC | `0xE0BE08c77f415F577A1B3A9aD7a1Df1479564ec8` |
+| Alternate Circle-referenced USDC | `0xcfC8330f4BCAB529c625D12781b1C19466A9Fc8B` |
 
-## 🔧 Tools (17)
+The project treats router and pool addresses that are not directly verified from official docs as **project-configured**, not universal canonical values.
 
-All tools hit live Pharos RPC and the DODO Route API. Zero mocks, zero stubs.
+### 🧠 Smart Liquidity Fallback
+Testnet liquidity is often fragmented or missing. SafeHands includes a **Smart Fallback Engine** within its DODO API integration. 
+If an AI agent requests a swap to the primary `USDC` token and the routing engine returns `NO_ROUTE_AVAILABLE`, SafeHands will automatically and silently retry the route query using the `Alternate Circle-referenced USDC` address. This prevents unnecessary transaction failures during live agent demos.
 
-### Core Safety — Assess before you execute
+---
 
-| # | Tool | Type | Description |
-|---|------|------|-------------|
-| 1 | `assess_risk` | Read+Write | 5-dimension risk score (0–100). Auto-publishes to on-chain RiskRegistry when `privateKey` provided. |
-| 2 | `check_token_security` | Read | Check token security, honeypot risk, buy/sell tax, and mint privileges via GoPlus Security API. |
-| 3 | `simulate_transaction` | Read | Dry run via `eth_call` — zero gas. Returns expected output, gas estimate, revert reasons. |
-| 4 | `estimate_gas` | Read | Gas cost in PHRS and USD. Checks wallet sufficiency before execution. |
+## Official Pharos Skill Engine Alignment
 
-### Execution — Act with guardrails
+- SafeHands follows the official `SKILL.md` + `references` + `assets` structure (found in the `skill/` package directory).
+- SafeHands complements Pharos Skill Engine by adding preflight safety checks before write actions.
+- Pharos Skill Engine provides general on-chain capabilities.
+- SafeHands answers: "Is this action safe to execute?"
+- Default network remains Pharos Atlantic Testnet.
+- No mainnet readiness is claimed.
 
-| # | Tool | Type | Description |
-|---|------|------|-------------|
-| 5 | `execute_swap` | Write | Swap via FaroSwap (DODO) with built-in risk gate. Blocks if score > 80. |
-| 6 | `send_payment` | Write | Native PHRS transfer with address validation, balance checks, exposure warnings. |
-| 7 | `approve_token` | Write | ERC-20 approval for DODO router. Supports exact amount or `"max"`. |
+---
 
-### Market Intelligence — Know before you trade
+## Supported Usage Modes
 
-| # | Tool | Type | Description |
-|---|------|------|-------------|
-| 8 | `get_token_price` | Read | Real-time PHRS/USDC/USDT price from DODO liquidity quotes. |
-| 9 | `get_pool_info` | Read | DODO pool data for any token pair — price ratio, impact, fees. |
-| 10 | `get_gas_price` | Read | Current gas price with trend classification and cost estimates. |
+SafeHands supports three usage modes:
 
-### Wallet & History — Observe the full picture
+1. **MCP server usage** for Claude Desktop, Anvita Flow, and other MCP-compatible clients.
+2. **npm/npx CLI usage** for terminal and CI checks.
+3. **Pharos Skill Engine reference-file usage** through the `skill/` package.
 
-| # | Tool | Type | Description |
-|---|------|------|-------------|
-| 11 | `get_wallet_balance` | Read | PHRS, USDC, USDT balances with total USD estimate. |
-| 12 | `check_allowance` | Read | ERC-20 allowance for DODO router. Reports if approval needed. |
-| 13 | `get_transaction_status` | Read | TX lookup by hash — status, block, gas, explorer link. |
-| 14 | `get_execution_history` | Read | On-chain audit trail. Categorizes swaps, transfers, other. |
+---
 
-### On-Chain Risk Registry — Share risk across agents
+## Quick Start
 
-| # | Tool | Type | Description |
-|---|------|------|-------------|
-| 15 | `publish_risk_score` | Write | Assess + publish to on-chain RiskRegistry. Other agents can query. |
-| 16 | `query_risk_registry` | Read | Read any wallet's risk score from registry. No key needed. |
+```bash
+npm install
+npm run build
+npm run test:all
+npm run demo
+```
 
-### x402 Payments — Gated paid APIs
+Run as MCP server:
 
-| # | Tool | Type | Description |
-|---|------|------|-------------|
-| 17 | `x402_pay_and_fetch` | Write | Fetch resources from a paid HTTP x402 server. Automatically executes payment authorization and retries fetch. |
+```bash
+npx safehands-pharos
+```
 
----
+Show CLI help:
 
-## 🔌 Agent Integration
+```bash
+npx safehands-pharos --help
+```
 
-SafeHands is safety middleware — other agents plug it into their execution pipeline instead of building their own risk logic. Because it implements the standard Model Context Protocol (MCP), it is natively compatible with **Anvita Flow** agent orchestration frameworks, Claude Desktop, and any standard MCP client.
+Run deterministic demo:
 
-### Example: DeFi Trading Agent
+```bash
+npx safehands-pharos --demo
+```
 
-A Phase 2 trading agent delegates all risk and execution to SafeHands:
+Run a Skill Engine-compatible CLI call:
 
+```bash
+npx safehands-pharos skill safehands_preflight_check --input-json '{"actionType":"approve_token","chainId":688689,"isMainnet":false,"approvalAmount":"max","spender":"0x0000000000000000000000000000000000000001"}'
 ```
-Agent receives: "Buy USDC with 50 PHRS"
-
-Step 1: get_wallet_balance(wallet)          → check funds
-Step 2: get_token_price(PHRS)               → current market price
-Step 3: assess_risk(swap, PHRS, USDC, 50)   → risk score 5, proceed
-Step 4: simulate_transaction(swap, 50)      → would succeed, ~83 USDC out
-Step 5: estimate_gas(swap, PHRS, USDC, 50)  → 0.004 PHRS, sufficient
-Step 6: execute_swap(PHRS, USDC, 50, key)   → ✅ TX confirmed
-Step 7: get_transaction_status(txHash)      → success, block 23961005
+
+The CLI returns the standard response envelope:
+
+```json
+{
+  "success": true,
+  "data": {
+    "decision": "BLOCK",
+    "riskLevel": "HIGH",
+    "safeToExecute": false,
+    "reasons": ["Unlimited approval requested."],
+    "requiredActions": ["Use a limited approval amount."],
+    "environment": "atlantic-testnet",
+    "chainId": 688689,
+    "isMainnet": false
+  },
+  "error": null,
+  "timestamp": "2026-06-12T00:00:00.000Z"
+}
 ```
 
-The trading agent handles strategy. SafeHands handles risk scoring, simulation, gas checks, and execution.
+---
+
+## Environment Setup
 
-### Example: Risk Auditor Agent
+Copy `.env.example` if you need local configuration:
 
+```bash
+cp .env.example .env
 ```
-Agent receives: "Is this wallet safe to interact with?"
 
-Step 1: query_risk_registry(0xsuspicious)   → score 87, critical, block
-Step 2: get_execution_history(0xsuspicious) → 2 failed swaps, 1 large transfer
-Response: "This wallet has a risk score of 87/100. Not recommended."
+Safe defaults:
+
+```env
+WALLET_MODE=none
+WRITE_TOOLS_ENABLED=false
+ALLOW_UNLIMITED_APPROVAL=false
+ALLOW_LOCAL_X402_FETCH=false
 ```
 
----
+Read-only and preflight tools do not require a private key. Write tools require `WRITE_TOOLS_ENABLED=true` and a safe signer source.
 
-## 🧩 Composability
+### 💾 Agent Wallet Backups
+By default, testnet wallets created via `create_agent_wallet` are strictly **In-Memory** and will not persist after the MCP server restarts.
+To enable persistent local storage for your AI agent wallets, set the following environment variable:
+```env
+WALLET_STORE_PATH=./.agents/wallets.json
+```
+This will securely XOR-obfuscate and save the agent's private key to your local `.agents` folder (which is explicitly ignored by Git to prevent accidental leakage).
 
-SafeHands is a building block, not a standalone app.
+---
 
-### Read vs Write Tools
+## MCP Tools: 27 Total
 
-| Access Level | Tools | Who can call |
-|---|---|---|
-| **Read-only** (11 tools) | `simulate_transaction`, `estimate_gas`, `get_token_price`, `get_pool_info`, `get_gas_price`, `get_wallet_balance`, `check_allowance`, `get_transaction_status`, `get_execution_history`, `query_risk_registry`, `check_token_security` | Any agent, no wallet needed |
-| **Read+Write** (1 tool) | `assess_risk` | Scores risk without a key; auto-publishes to RiskRegistry with key |
-| **Write** (5 tools) | `execute_swap`, `send_payment`, `approve_token`, `publish_risk_score`, `x402_pay_and_fetch` | Agents with privateKey |
+SafeHands currently exposes **27 MCP tools**:
 
-12 of 17 tools need **no wallet at all** — any agent can use SafeHands for risk intelligence without holding keys. `assess_risk` works without a key too, but upgrades to a write operation when one is provided.
+- 17 legacy/core Web3 safety/execution tools
+- 3 managed testnet wallet tools
+- 7 branded SafeHands guardrail tools
 
-### Cross-Agent Risk Intelligence
+### Branded SafeHands Guardrail Tools
 
-The RiskRegistry contract turns risk scores into shared, on-chain data:
+| Tool | Purpose |
+|---|---|
+| `safehands_preflight_check` | Policy-based ALLOW/WARN/BLOCK check before execution |
+| `safehands_safe_execute` | Guarded wrapper around payment, approval, swap, and x402 execution |
+| `safehands_wallet_health` | Checks whether an agent wallet is ready to act |
+| `safehands_x402_preflight` | Checks URL, payment amount, token, signer, and x402 safety before paying |
+| `safehands_risk_report` | Generates a human-readable risk report for demos and judges |
+| `explain_risk` | Converts policy results into plain-English explanations |
+| `token_registry_status` | Classifies token addresses as canonical, test, custom, unknown, or invalid |
 
-```
-Agent A assesses wallet X  →  publish_risk_score  →  On-Chain Registry
-                                                          │
-Agent B wants to trade     →  query_risk_registry  ←──────┘
-with wallet X                    "Score 87, block"
-```
+### Core Safety and Execution Tools
 
-- **Permissionless writes** — any agent can publish assessments
-- **Permissionless reads** — any agent can query scores
-- **No centralized API** — data lives on Pharos chain
-- **Timestamped** — agents see when scores were last updated
+| Tool | Type | Purpose |
+|---|---|---|
+| `assess_risk` | Read / optional write | 5-dimension risk score |
+| `check_token_security` | Read | GoPlus token security profile |
+| `simulate_transaction` | Read | Dry-run transaction simulation |
+| `estimate_gas` | Read | Gas estimate and sufficiency check |
+| `execute_swap` | Write | FaroSwap/DODO swap with guardrails |
+| `send_payment` | Write | Native PHRS payment |
+| `approve_token` | Write | ERC-20 approval with unlimited-approval guard |
+| `get_token_price` | Read | Token price data |
+| `get_pool_info` | Read | DODO/FaroSwap pool and route info |
+| `get_gas_price` | Read | Current gas price |
+| `get_wallet_balance` | Read | Wallet balances |
+| `check_allowance` | Read | ERC-20 allowance check |
+| `get_transaction_status` | Read | Transaction status by hash |
+| `get_execution_history` | Read | Wallet transaction history |
+| `publish_risk_score` | Write | Publish score to RiskRegistry |
+| `query_risk_registry` | Read | Query on-chain risk score |
+| `x402_pay_and_fetch` | Write when HTTP 402 | Fetch x402 resources and pay only after a payment challenge |
+
+### Managed Testnet Wallet Tools
+
+| Tool | Purpose |
+|---|---|
+| `create_agent_wallet` | Explicitly create a managed testnet wallet |
+| `get_agent_wallet` | Return public wallet metadata, never private key |
+| `get_agent_wallet_balance` | Check managed wallet balances |
 
 ---
 
-## 🚀 Quick Start
+## Policy Engine Behavior
 
-> Built and tested on Pharos Atlantic Testnet. All tools execute against live RPC — no mocks, no stubs.
+The reusable policy engine lives at:
 
-### Option 1 — npx (recommended)
+```text
+src/lib/policy/actionPolicyEngine.ts
+```
 
-No install required. Add to your Claude Desktop `claude_desktop_config.json`:
+Supported action types:
 
-```json
-{
-  "mcpServers": {
-    "safehands": {
-      "command": "npx",
-      "args": ["-y", "safehands-pharos"]
-    }
-  }
-}
+```text
+send_payment
+approve_token
+execute_swap
+x402_pay_and_fetch
+publish_risk_score
+custom_contract_call
 ```
 
-Restart Claude Desktop. All 17 SafeHands tools appear automatically.
+Key guardrails:
 
-### Option 2 — Clone & Build
+- Block mainnet actions.
+- Block chain ID mismatch.
+- Block unlimited approvals by default.
+- Block SSRF-sensitive x402 URLs.
+- Block payment above configured limits.
+- Block x402 payment above `MAX_X402_PAYMENT_USDC`.
+- Block approvals above `MAX_APPROVAL_AMOUNT_USDC` unless consciously configured.
+- Warn when a token is custom, non-registry, or token-security provider is unavailable.
+- Require confirmation for medium-risk actions.
+- Allow low-risk Pharos Atlantic Testnet actions.
 
-```bash
-git clone https://github.com/SZtch/safehands-pharos.git
-cd safehands-pharos
-npm install
-npm run build
-```
+---
 
-Add to `claude_desktop_config.json`:
+## x402 Behavior
 
-```json
-{
-  "mcpServers": {
-    "safehands": {
-      "command": "node",
-      "args": ["/absolute/path/to/safehands-pharos/dist/index.js"]
-    }
-  }
-}
-```
+SafeHands has both x402 client and server behavior:
 
-### Configure Credentials
+### Free endpoints
 
-12 of 17 tools work without any credentials. Only write operations need a private key.
+- `GET /supported`
+- `GET /health`
 
-**Recommended — pass via MCP client config:**
+These do **not** require a user private key.
 
-```json
-{
-  "mcpServers": {
-    "safehands": {
-      "command": "npx",
-      "args": ["-y", "safehands-pharos"],
-      "env": {
-        "PRIVATE_KEY": "0xYOUR_PRIVATE_KEY",
-        "WALLET_ADDRESS": "0xYOUR_WALLET_ADDRESS"
-      }
-    }
-  }
-}
-```
+### Paid endpoints
 
-**Alternative — `.env` file:**
+- `GET /assess-risk`
+- `GET /check-token-security`
+- `GET /simulate-transaction`
 
-```env
-PRIVATE_KEY=0xYOUR_PRIVATE_KEY_HERE
-WALLET_ADDRESS=0xYOUR_WALLET_ADDRESS_HERE
-```
+Expected demo price: `0.001 USDC`.
 
-> ⚠️ Private keys are **never stored** by SafeHands — passed per-request only, never logged. Only 5 tools require a private key: `execute_swap`, `send_payment`, `approve_token`, `publish_risk_score`, `x402_pay_and_fetch`.
+Client flow:
 
-### Verify
+1. Fetch normally first.
+2. If HTTP 200, return `paymentExecuted=false`.
+3. If HTTP 402, run SafeHands x402 preflight.
+4. Request signer only after HTTP 402.
+5. Do not log or return signed payment payloads.
 
-```bash
-npm run test:rpc
-```
+---
 
-```
-🔌 Connecting to Pharos Atlantic Testnet...
-   Chain ID returned: 688689
-✅ SUCCESS — Chain ID matches expected 688689
-```
+## Using SafeHands with Pharos Skill Engine
 
----
+SafeHands includes a Pharos Skill Engine adapter under:
 
-## ⛓️ On-Chain Risk Registry
-
-SafeHands ships a deployed **RiskRegistry** smart contract — the first on-chain risk reputation layer for Pharos agents.
-
-| Field | Value |
-|-------|-------|
-| **Contract** | [`0x71fc28ed3a31016b42f18764889cd911f22b67b8`](https://atlantic.pharosscan.xyz/address/0x71fc28ed3a31016b42f18764889cd911f22b67b8) |
-| **Chain** | Pharos Atlantic Testnet (688689) |
-| **Deploy TX** | [`0x7f2106b5...`](https://atlantic.pharosscan.xyz/tx/0x7f2106b5bc8c5eddcd2ea7782669ccb0b4a107da4943cffd5d49357ab5820d2e) |
-| **Source** | [`contracts/RiskRegistry.sol`](contracts/RiskRegistry.sol) |
-
-```solidity
-contract RiskRegistry {
-    struct RiskRecord {
-        uint256 score;
-        string riskLevel;
-        string recommendation;
-        uint256 timestamp;
-        address assessedBy;
-    }
-
-    function publish(address wallet, uint256 score, string riskLevel, string recommendation) external;
-    function query(address wallet) external view returns (RiskRecord memory);
-}
+> **Note:** The canonical publishable Skill package is in `skill/`. The `examples/pharos-skill-engine/` folder is retained as an integration example.
+
+```text
+examples/pharos-skill-engine/
+├── SKILL.safehands.md
+├── references/
+│   └── safehands.md
+└── assets/
+    └── safehands/
+        ├── policy-defaults.json
+        └── example-actions.json
 ```
 
-When `assess_risk` is called with a `privateKey`, the score is **automatically published** — every assessment becomes a permanent, queryable on-chain record.
+The reference files teach the Skill Engine how to call SafeHands through terminal commands such as:
 
-> **Design note:** The RiskRegistry is intentionally permissionless — any agent can publish assessments for any wallet. This mirrors how reputation systems work in open networks: scores are weighted by who published them, not gated by who can publish. Agents should consider the `assessedBy` field when evaluating scores from unknown publishers.
+```bash
+npx safehands-pharos skill safehands_preflight_check --input-json '<json>'
+npx safehands-pharos skill safehands_x402_preflight --input-json '<json>'
+npx safehands-pharos skill safehands_wallet_health --input-json '{}'
+npx safehands-pharos skill token_registry_status --input-json '{"tokenAddress":"0xE0BE08c77f415F577A1B3A9aD7a1Df1479564ec8"}'
+```
 
----
+Use SafeHands before Pharos Skill Engine performs write actions. SafeHands complements the Skill Engine and should not be treated as a replacement.
 
-## 🔗 Live Transaction Proof
+---
 
-All 17 tools tested against **Pharos Atlantic Testnet** with real on-chain transactions:
+## Security Guardrails
 
-| Tool | TX Hash | Result |
-|------|---------|--------|
-| `execute_swap` | [`0xdb814a33...`](https://atlantic.pharosscan.xyz/tx/0xdb814a334337d47a3d2b18cbe4f9015356a3842412dada6ca2138d14287f50cb) | 0.01 PHRS → 0.0317 USDC |
-| `send_payment` | [`0xbf26b767...`](https://atlantic.pharosscan.xyz/tx/0xbf26b767cb8a5e599b6acaec90998a66577dbec9036526e7c1876a43a1e79471) | 0.001 PHRS sent |
-| `approve_token` | [`0xca21ac22...`](https://atlantic.pharosscan.xyz/tx/0xca21ac22c870f1bc69c432f1f02c9459066f390a1dead92fca8b0d1119d30422) | 100 USDC approved |
-| `publish_risk_score` | [`0x3f5cefe5...`](https://atlantic.pharosscan.xyz/tx/0x3f5cefe5725512b57f3dc7c08bb8f588fa3691fc4592ccec66ba2cb6ef4c9a3a) | Score 3 published |
-| Registry deploy | [`0x7f2106b5...`](https://atlantic.pharosscan.xyz/tx/0x7f2106b5bc8c5eddcd2ea7782669ccb0b4a107da4943cffd5d49357ab5820d2e) | Contract created |
+SafeHands defaults to defensive behavior:
 
-### Test Results — 17 Tools, All Passing
-
-```
-  #  │ Status  │ Tool                    │ Key Output
-──────────────────────────────────────────────────────────────────────────────────────────
-  1 │ ✅ PASS │ assess_risk             │ score=2, low, proceed
-  2 │ ✅ PASS │ simulate_transaction    │ wouldSucceed=true, gas=633592
-  3 │ ✅ PASS │ simulate_tx (xfer)      │ wouldSucceed=true, gas=21000
-  4 │ ✅ PASS │ get_token_price         │ PHRS=$unavailable
-  5 │ ✅ PASS │ get_wallet_balance      │ PHRS=19.363297355, USDC=0.050675, total=$0....
-  6 │ ✅ PASS │ check_allowance         │ allowance=100, needsApproval=false
-  7 │ ✅ PASS │ estimate_gas            │ gas=624491, cost=0.00624491 PHRS, sufficien...
-  8 │ ✅ PASS │ get_gas_price           │ 10.0000 Gwei, trend=normal
-  9 │ ✅ PASS │ get_pool_info           │ available=false, no pool
- 10 │ ✅ PASS │ execute_swap            │ out=0.0317053705 USDC, tx=0xdb814a334337d47...
- 11 │ ✅ PASS │ send_payment            │ sent 0.001 PHRS, tx=0xbf26b767cb8a5e599b6ac...
- 12 │ ✅ PASS │ approve_token           │ approved 100 USDC, tx=0xca21ac22c870f1bc69c...
- 13 │ ✅ PASS │ get_transaction_status  │ status=success, block=23970700
- 14 │ ✅ PASS │ publish_risk_score      │ score=3, tx=0x3f5cefe5725512b57f3dc7c08bb8f...
- 15 │ ✅ PASS │ query_risk_registry     │ score=3, level=low, ts=2026-06-11T11:53:17....
- 16 │ ✅ PASS │ check_token_security    │ score=100, honeypot=false
- 17 │ ✅ PASS │ get_execution_history   │ 5 txs
-```
+- `WRITE_TOOLS_ENABLED=false` by default.
+- `WALLET_MODE=none` by default.
+- No wallet is created on install, import, or startup.
+- Managed wallets are created only through `create_agent_wallet`.
+- Private keys are never returned in MCP or CLI responses.
+- Private keys and payment proofs are not logged.
+- Unlimited approvals are blocked unless explicitly allowed.
+- SSRF-sensitive x402 URLs are blocked unless local testing is explicitly enabled.
+- Mainnet actions are blocked.
+- External API failures return structured errors rather than crashing tool calls.
 
 ---
 
-## 🪙 x402 Monetized API Server
+## Demo
 
-SafeHands exposes a paid HTTP REST API server using the Coinbase-designed **x402 micro-payment protocol** on Pharos Atlantic. This allows developers to offer risk gating and intelligence tools as a paid utility to external AI agents.
+Run:
 
-### API Endpoints
-- `GET /health` (Free) — Health check, token registry, and receiver addresses.
-- `GET /assess-risk` (Paid: USDC 0.001) — Gate queries with 5-dimension risk score checks.
-- `GET /check-token-security` (Paid: USDC 0.001) — Verify contract security, honeypots, and token code privileges.
-- `GET /simulate-transaction` (Paid: USDC 0.001) — Perform dry-runs of transfers and swaps.
+```bash
+npm run demo
+```
 
-### Flow Architecture
-1. **Challenge:** When a client fetches a gated resource, the server replies with `HTTP 402 Payment Required` and a Base64-encoded `PAYMENT-REQUIRED` header specifying token address, receiver wallet, and pricing details.
-2. **On-Chain Settlement:** The client signs a standard authorization envelope with their private key, transferring the micro-payment directly to the recipient wallet.
-3. **Resubmission:** The client resubmits the request, appending the payload signature in the `PAYMENT-SIGNATURE` header.
-4. **Unlocking Content:** The integrated Facilitator verifies the signature, settles the transfer on-chain, and responds with `HTTP 200 OK` carrying the resource response payload.
+or:
 
-### Quick Start (Server)
-Start the paid server:
 ```bash
-npm run x402-server
+npx safehands-pharos --demo
 ```
 
-### Quick Start (Client)
-Use the `x402_pay_and_fetch` tool:
-```json
-{
-  "name": "x402_pay_and_fetch",
-  "arguments": {
-    "url": "http://localhost:4021/assess-risk?action=swap&tokenIn=PHRS&tokenOut=USDC&amount=0.01&walletAddress=0x6730d3a2a217108ab53ccfe60ffdad05d3c124e5"
-  }
-}
-```
+The default demo is deterministic and non-destructive. It shows wallet health, allowed preflight, blocked approval, token registry status, x402 preflight, free x402 endpoint behavior, paid x402 without signer, SSRF blocking, write-tool blocking, and a human-readable risk explanation.
 
 ---
 
-## 🔒 Security
-
-Security self-audit — compliant with Pharos Skill Scanner guidelines:
-
-- ✅ **Private keys never stored** — passed per-request, never logged or persisted
-- ✅ **No hardcoded secrets** — all sensitive config via `.env`
-- ✅ **No shell execution** — pure TypeScript with viem RPC calls
-- ✅ **No file system abuse** — no local file reads/writes during tool execution
-- ✅ **Risk gating on execution** — `execute_swap` and `send_payment` run full risk assessment before execution. All write tools enforce safety checks before touching the chain.
-- ✅ **Automatic blocking** — score > 80 halts execution, no silent failures
+## Real Testnet Verification
 
-### Third-Party API Usage
+SafeHands includes live verification commands that test against real Pharos Atlantic Testnet infrastructure:
 
-SafeHands connects to three external services — all well-known, publicly documented Web3 infrastructure:
+| Command | What it does | Requires |
+|---------|-------------|----------|
+| `npm run test:rpc:live` | Reads chain ID, block number, optional wallet balance from live RPC | Network access |
+| `npm run test:live:safehands` | Runs 7 CLI safety checks against built dist (no broadcast) | Built dist |
+| `npm run test:x402:live` | Tests x402 free/paid endpoint behavior locally | Nothing |
+| `npm run test:dodo:live` | Tests DODO API route if `DODO_API_KEY` set; skips cleanly if not | `DODO_API_KEY` (optional) |
 
-| Service | Endpoint | Purpose | Data Sent |
-|---------|----------|---------|----------|
-| **Pharos RPC** | `atlantic.dplabs-internal.com` | On-chain reads/writes | Standard JSON-RPC calls (public data) |
-| **DODO Route API** | `api.dodoex.io` | DEX swap routing & quotes | Public token addresses, amounts |
-| **GoPlus Security API** | `api.gopluslabs.io` | Token contract security scanning | Public token contract address |
+**Important distinctions:**
 
-> No private keys, wallet balances, or user-identifying data are ever sent to any external API. The DODO API key is a public, read-only key from DODO's official documentation.
+1. **Live RPC checks** (`test:rpc`, `test:rpc:live`) connect to the real Pharos Atlantic Testnet RPC and read chain ID + block number.
+2. **Live CLI checks** (`test:live:safehands`) run real CLI invocations against built dist, testing policy decisions deterministically.
+3. **x402 behavior checks** (`test:x402:live`) use a **local test server** labeled `LOCAL_X402_SERVER_DOCS_BEHAVIOR_TEST`. They do not connect to a remote Pharos x402 endpoint.
+4. **DODO checks** (`test:dodo:live`) performs live read-only DODO/FaroSwap checks when `DODO_API_KEY` is configured. The public API key can be provided through an environment variable. The key is not required for the normal deterministic demo. A missing key results in a clean skip. A live API pass does not automatically make router addresses docs-verified.
+5. **Smoke tests** (`test:all`) are deterministic and do not require network connectivity (except DODO/RPC-dependent tools, which degrade gracefully).
+6. **Address verification statuses** (DOCS_VERIFIED, DOCS_DEMO_NON_OFFICIAL, PROJECT_CONFIGURED) are sourced from `docs/reports/OFFICIAL_DOCS_ALIGNMENT_REPORT.md`.
+7. **No real transactions are broadcast by default.** Write tools require explicit `WRITE_TOOLS_ENABLED=true`.
 
 ---
 
-## 🗺️ Roadmap
+## Tests and Validation
 
-### Phase 1 — Hackathon (Current) ✅
-- [x] 17 MCP tools with real on-chain execution
-- [x] 5-dimension risk scoring engine
-- [x] FaroSwap (DODO) integration
-- [x] On-chain RiskRegistry smart contract
-- [x] 17/17 integration tests passing on Pharos Atlantic
+```bash
+npm ci
+npm run build
+npx tsc -p tsconfig.all.json --pretty false
+npm run test:all                # 43-point smoke test suite
+npm audit --omit=dev --audit-level=high
+npm pack --dry-run
+```
 
-### Phase 2 — NPM Package
-- [x] Publish `safehands-pharos` to npm
-- [x] One-line install: `npx safehands-pharos`
-- [ ] Configurable risk thresholds per-agent
+Live verification (requires network):
 
-### Phase 3 — Agent Arena
-- [ ] Agent-to-agent risk score sharing via registry
-- [ ] Reputation scoring from historical risk behavior
-- [ ] Multi-agent swap coordination with risk consensus
+```bash
+npm run test:rpc                # Basic RPC connectivity
+npm run test:rpc:live           # Full live RPC verification with structured output
+npm run test:live:safehands     # 7 CLI safety checks (read-only)
+npm run test:x402:live          # x402 behavior checks (local server)
+npm run test:dodo:live          # DODO API check (requires DODO_API_KEY, skips if missing)
+```
 
-### Phase 4 — DeFi & x402 Integration
-- [x] **x402 Paywall & Monetization:** Native integration with the Pharos x402 HTTP-payment standard. Enable SafeHands to charge micro-amounts of USDC per risk assessment request, allowing agents to monetize their safety gating services autonomously.
-- [ ] ELFi lending protocol integration
-- [ ] Multi-hop route optimization for large swaps
-- [ ] Smart contract escrow for agent-to-agent payments
-- [ ] Cross-chain risk assessment (Pharos Mainnet)
+`test:rpc` and `test:rpc:live` depend on DNS/network access to Pharos RPC and may fail in restricted environments. This should be reported honestly as a provider/network limitation, not hidden.
 
 ---
 
-## 📄 License
+## Known Limitations and TODOs
 
-MIT — see [LICENSE](LICENSE) for details.
+- Testnet-only, not audited for mainnet use.
+- Managed wallet storage is testnet-grade unless a real KMS/Vault is integrated.
+- DODO/FaroSwap router addresses are project-configured unless official docs confirm them.
+- GoPlus/DODO/FaroSwap availability depends on external services and API limits.
+- `npm audit` for production dependencies is clean; full dev audit may report dev-only dependency issues depending on upstream packages.
+- Formal unit tests with mocked RPC/DODO/GoPlus providers would improve long-term maintainability.
 
 ---
 
-<p align="center">
-  <strong>Built for the Pharos AI Agent economy.</strong><br/>
-  <em>Where agents move real value — and real value deserves real protection.</em>
-</p>
+## Hackathon Summary
+
+**Project name:** SafeHands-Pharos: Transaction Safety Firewall for AI Agents
+
+**Short description:** SafeHands-Pharos is a Pharos Skill Engine-compatible MCP package that protects AI agents before they execute payments, token approvals, swaps, or x402 paid requests by returning ALLOW, WARN, or BLOCK decisions with human-readable risk explanations.