safehands-pharos 1.4.0 → 2.6.0

package/.agents/policies/default.json

@@ -0,0 +1,15 @@
+{
+  "profile": "balanced",
+  "limits": {
+    "maxPaymentPROS": "1",
+    "maxSwapPROS": "10",
+    "maxDailySpendPROS": "25",
+    "maxX402PaymentUSDC": "0.1",
+    "maxApprovalUSDC": "50"
+  },
+  "flags": {
+    "allowUnknownTokens": false,
+    "allowCustomContractCalls": false,
+    "requireConfirmationAboveRisk": "MEDIUM"
+  }
+}

package/.env.example

@@ -1,64 +1,81 @@
-NODE_ENV=development
-
-PHAROS_ENVIRONMENT=atlantic-testnet
-PHAROS_CHAIN_ID=688689
-# Primary RPC URL (single endpoint)
-PHAROS_RPC_URL=https://atlantic.dplabs-internal.com
-# Optional: comma-separated list of RPC URLs for failover (takes priority over PHAROS_RPC_URL)
-# PHAROS_RPC_URLS=https://atlantic.dplabs-internal.com,https://rpc2.pharos.xyz
-
-# DODO API key for swap routing (required for execute_swap, get_pool_info, simulate_transaction swap mode)
-DODO_API_KEY=
-
-# ── Wallet Configuration ──────────────────────────────────────────────────────
-# WALLET_MODE controls how write tools resolve a signer.
-#   none             — no signer; write tools return NO_SIGNER_AVAILABLE (default, safe)
-#   env              — reads PRIVATE_KEY from this file (testnet developer mode)
-#   managed-testnet  — uses a wallet created via create_agent_wallet
-WALLET_MODE=none
-PRIVATE_KEY=
-X402_SIGNER_PRIVATE_KEY=
-WALLET_ADDRESS=
-
-# Encryption key for AES-256-GCM encrypted managed wallet store (WALLET_STORE_PATH).
-# If unset, a random per-process key is generated (wallets do not persist across restarts).
-WALLET_ENCRYPTION_KEY=
-
-# Path to persist managed agent wallets across restarts (optional).
-# If unset, wallets are in-memory only and lost on server restart.
-# WALLET_STORE_PATH=./.agents/wallets.json
-
-# ── Write Tool Gates ──────────────────────────────────────────────────────────
-WRITE_TOOLS_ENABLED=false
-ALLOW_UNLIMITED_APPROVAL=false
-ALLOW_LOCAL_X402_FETCH=false
-
-# ── Spend Limits ──────────────────────────────────────────────────────────────
-MAX_TX_AMOUNT_PHRS=0.1
-MAX_X402_PAYMENT_USDC=0.01
-MAX_APPROVAL_AMOUNT_USDC=10
-
-# Enforced in-memory per-wallet (resets at UTC midnight).
-# USD value of PHRS is estimated using PHRS_USD_PRICE below.
-MAX_DAILY_SPEND_USD=10
-# Assumed PHRS/USD price for daily spend accounting (update as needed)
-PHRS_USD_PRICE=1.0
-
-# ── Observability ─────────────────────────────────────────────────────────────
-# Path to append-only JSON audit log (one JSON object per line).
-# Leave empty to disable. Example: AUDIT_LOG_PATH=./logs/safehands-audit.jsonl
-# AUDIT_LOG_PATH=
-
-# Per-tool MCP rate limits (calls/minute). Defaults shown.
-# MCP_RATE_LIMIT_HEAVY=5        # get_execution_history
-# MCP_RATE_LIMIT_WRITE=15       # execute_swap, send_payment, approve_token, etc.
-# MCP_RATE_LIMIT_DEFAULT=120    # all other tools
-
-# ── x402 Server (only needed when running `npm run x402-server`) ──
-# Receiver wallet address for x402 micro-payments (defaults to WALLET_ADDRESS if unset)
-# X402_PAY_TO=
-# Private key for the x402 facilitator (settles payments on-chain)
-# X402_FACILITATOR_PRIVATE_KEY=
-# Price per paid endpoint in USDC (default: 0.001)
-# X402_PRICE_USDC=0.001
-X402_SERVER_PORT=4021
+# ─────────────────────────────────────────────────────────────────────────────
+# SafeHands-Pharos — environment template.   Copy to .env:  cp .env.example .env
+#
+# Read-only preflight works with NO .env at all. Everything below is optional and
+# OFF by default. .env is gitignored — NEVER commit real secrets. This template
+# holds placeholders only: never put a real private key here.
+# ─────────────────────────────────────────────────────────────────────────────
+
+# ── Network (read-only defaults) ─────────────────────────────────────────────
+PHAROS_ENVIRONMENT=pacific-mainnet
+PHAROS_CHAIN_ID=1672
+PHAROS_RPC_URL=https://rpc.pharos.xyz
+# SAFEHANDS_NETWORK=pacific-mainnet          # pacific-mainnet | atlantic-testnet
+# Optional premium RPC (read from env only; never hardcoded):
+# PHAROS_MAINNET_RPC_URL=
+# ZAN_PHAROS_MAINNET_RPC_URL=
+# ALCHEMY_PHAROS_MAINNET_RPC_URL=
+# PHAROS_RPC_PROVIDER=                       # zan | alchemy | nirvana | custom | pharos-public
+# GOPLUS_API_BASE=https://api.gopluslabs.io  # GoPlus threat-intel base URL (keyless; honored by backend + hosted engine)
+
+# ── Live SafeHands contracts on Pharos Pacific (1672) ────────────────────────
+SAFEHANDS_REGISTRY_ADDRESS=0x428e02bf85412e7242d991cd6725ec59e8b06c8d
+SAFEHANDS_ATTESTATION_ADDRESS=0x71a7a87b3b1ab6d86204cad691bb32fd75b4588c
+
+# ── Safety gates (ALL default false → read-only, zero-custody) ───────────────
+# WRITE_TOOLS_ENABLED is the master switch — required before ANY write/payment
+# tool can run. The two gates below it are ADDITIONAL and independently enforced:
+#   SAFE_EXECUTE_ENABLED   → also required for the safehands_safe_execute
+#                            preflight→execute path (read-only preflight_check needs neither).
+#   MANAGED_WALLET_ENABLED → also required (with WALLET_MODE=managed-mainnet) before a
+#                            stored managed wallet is ever used to sign.
+WRITE_TOOLS_ENABLED=false
+SAFE_EXECUTE_ENABLED=false
+MANAGED_WALLET_ENABLED=false
+PUBLISH_RISK_RECORDS_ENABLED=false
+# ALLOW_UNLIMITED_APPROVAL=false
+# ALLOW_LOCAL_X402_FETCH=false
+
+# ── Self-hosted managed execution (opt-in; single-tenant, on a machine you control)
+# WALLET_MODE=none                           # none | env | managed-mainnet
+# PRIVATE_KEY=                               # env-wallet mode only — NEVER commit a real key
+# DODO_API_KEY=                              # required for price / pool / swap routing
+# OKX_API_KEY=                               # okx swap venue (execute_swap venue: okx); signed API access
+# OKX_API_SECRET=                            # NEVER commit a real secret; used only to sign OKX requests
+# OKX_API_PASSPHRASE=
+# OKX_API_PROJECT_ID=                        # only if your OKX project requires the OK-ACCESS-PROJECT header
+# PROS_USD_PRICE=1.0                         # STATIC fallback price used to convert PROS→USD for
+#                                            # the daily spend caps (no oracle). If unset, 1.0 is
+#                                            # assumed — set it CONSERVATIVELY (i.e. at or above the
+#                                            # real market price) so caps never under-count spend.
+# GOLDSKY_SUBGRAPH_URL=
+
+# ── On-chain attestation (opt-in; attester key is separate from any user wallet)
+# SAFEHANDS_ATTESTER_PRIVATE_KEY=            # NEVER commit a real key
+# SAFEHANDS_ATTESTATION_REQUIRED=false
+# SAFEHANDS_USER_SIGNED_BROADCAST_ENABLED=false
+# SAFEHANDS_LOCAL_WALLET_HELPER_ENABLED=false
+
+# ── x402 paid endpoints (opt-in) ─────────────────────────────────────────────
+# RECOMMENDED (zero-custody, public production): the Guardian API /paid/* gate
+# uses an EXTERNAL facilitator — no signing key ever touches this host. Paid
+# routes are active only when BOTH are set; otherwise they fail closed (503).
+# X402_PAY_TO=                               # receive-only address for earned fees
+# X402_FACILITATOR_URL=                      # external x402 facilitator (verify/settle off-host)
+# X402_PRICE_USDC=0.01
+#
+# DEV / self-hosted single-tenant ONLY: the standalone x402 server
+# (`npm run start:x402`) signs settlements locally with this key (custody).
+# With NODE_ENV=production it refuses to start unless
+# SAFEHANDS_ALLOW_LOCAL_FACILITATOR=true is also set explicitly.
+# X402_FACILITATOR_PRIVATE_KEY=              # NEVER commit a real key
+# SAFEHANDS_ALLOW_LOCAL_FACILITATOR=false
+
+# ── Production hosting (Guardian API) ────────────────────────────────────────
+# NODE_ENV=production
+# PORT=3000
+# SAFEHANDS_STATE_DIR=/data                  # persistent volume path (durability)
+# SAFEHANDS_CORS_ORIGIN=https://your.app     # tighten from * for guarded/paid surfaces
+# SAFEHANDS_ALLOW_MANAGED_ON_PUBLIC=false    # required to run managed execution on a public host
+# UPSTASH_REDIS_REST_URL=                    # x402 replay durability (optional)
+# UPSTASH_REDIS_REST_TOKEN=