safehands-pharos 1.2.0 → 1.2.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (175) hide show
  1. package/.env.example +26 -0
  2. package/README.md +311 -350
  3. package/contracts/RiskRegistry.json +75 -1
  4. package/contracts/RiskRegistry.sol +29 -1
  5. package/dist/cli.d.ts +6 -0
  6. package/dist/cli.d.ts.map +1 -0
  7. package/dist/cli.js +91 -0
  8. package/dist/cli.js.map +1 -0
  9. package/dist/demo.d.ts +2 -0
  10. package/dist/demo.d.ts.map +1 -0
  11. package/dist/demo.js +172 -0
  12. package/dist/demo.js.map +1 -0
  13. package/dist/index.js +181 -169
  14. package/dist/index.js.map +1 -1
  15. package/dist/init.d.ts +2 -0
  16. package/dist/init.d.ts.map +1 -0
  17. package/dist/init.js +66 -0
  18. package/dist/init.js.map +1 -0
  19. package/dist/lib/constants.d.ts +122 -7
  20. package/dist/lib/constants.d.ts.map +1 -1
  21. package/dist/lib/constants.js +139 -13
  22. package/dist/lib/constants.js.map +1 -1
  23. package/dist/lib/dodoApi.d.ts +14 -0
  24. package/dist/lib/dodoApi.d.ts.map +1 -1
  25. package/dist/lib/dodoApi.js +78 -22
  26. package/dist/lib/dodoApi.js.map +1 -1
  27. package/dist/lib/http.d.ts +15 -0
  28. package/dist/lib/http.d.ts.map +1 -0
  29. package/dist/lib/http.js +119 -0
  30. package/dist/lib/http.js.map +1 -0
  31. package/dist/lib/pharosClient.d.ts +4 -3
  32. package/dist/lib/pharosClient.d.ts.map +1 -1
  33. package/dist/lib/pharosClient.js +8 -5
  34. package/dist/lib/pharosClient.js.map +1 -1
  35. package/dist/lib/policy/actionPolicyEngine.d.ts +54 -0
  36. package/dist/lib/policy/actionPolicyEngine.d.ts.map +1 -0
  37. package/dist/lib/policy/actionPolicyEngine.js +213 -0
  38. package/dist/lib/policy/actionPolicyEngine.js.map +1 -0
  39. package/dist/lib/signer/index.d.ts +25 -0
  40. package/dist/lib/signer/index.d.ts.map +1 -0
  41. package/dist/lib/signer/index.js +90 -0
  42. package/dist/lib/signer/index.js.map +1 -0
  43. package/dist/lib/testDodoLive.d.ts +2 -0
  44. package/dist/lib/testDodoLive.d.ts.map +1 -0
  45. package/dist/lib/testDodoLive.js +105 -0
  46. package/dist/lib/testDodoLive.js.map +1 -0
  47. package/dist/lib/testLiveSafehands.d.ts +2 -0
  48. package/dist/lib/testLiveSafehands.d.ts.map +1 -0
  49. package/dist/lib/testLiveSafehands.js +93 -0
  50. package/dist/lib/testLiveSafehands.js.map +1 -0
  51. package/dist/lib/testRpcLive.d.ts +2 -0
  52. package/dist/lib/testRpcLive.d.ts.map +1 -0
  53. package/dist/lib/testRpcLive.js +89 -0
  54. package/dist/lib/testRpcLive.js.map +1 -0
  55. package/dist/lib/testTools.js +363 -354
  56. package/dist/lib/testTools.js.map +1 -1
  57. package/dist/lib/testX402Live.d.ts +2 -0
  58. package/dist/lib/testX402Live.d.ts.map +1 -0
  59. package/dist/lib/testX402Live.js +160 -0
  60. package/dist/lib/testX402Live.js.map +1 -0
  61. package/dist/lib/toolResponse.d.ts +26 -0
  62. package/dist/lib/toolResponse.d.ts.map +1 -0
  63. package/dist/lib/toolResponse.js +54 -0
  64. package/dist/lib/toolResponse.js.map +1 -0
  65. package/dist/lib/wallet/index.d.ts +19 -0
  66. package/dist/lib/wallet/index.d.ts.map +1 -0
  67. package/dist/lib/wallet/index.js +71 -0
  68. package/dist/lib/wallet/index.js.map +1 -0
  69. package/dist/tools/approveToken.d.ts +19 -20
  70. package/dist/tools/approveToken.d.ts.map +1 -1
  71. package/dist/tools/approveToken.js +44 -21
  72. package/dist/tools/approveToken.js.map +1 -1
  73. package/dist/tools/assessRisk.d.ts +22 -9
  74. package/dist/tools/assessRisk.d.ts.map +1 -1
  75. package/dist/tools/assessRisk.js +32 -9
  76. package/dist/tools/assessRisk.js.map +1 -1
  77. package/dist/tools/checkAllowance.d.ts +6 -6
  78. package/dist/tools/checkTokenSecurity.d.ts +9 -16
  79. package/dist/tools/checkTokenSecurity.d.ts.map +1 -1
  80. package/dist/tools/checkTokenSecurity.js +17 -22
  81. package/dist/tools/checkTokenSecurity.js.map +1 -1
  82. package/dist/tools/createAgentWallet.d.ts +27 -0
  83. package/dist/tools/createAgentWallet.d.ts.map +1 -0
  84. package/dist/tools/createAgentWallet.js +60 -0
  85. package/dist/tools/createAgentWallet.js.map +1 -0
  86. package/dist/tools/estimateGas.d.ts +31 -21
  87. package/dist/tools/estimateGas.d.ts.map +1 -1
  88. package/dist/tools/estimateGas.js +91 -95
  89. package/dist/tools/estimateGas.js.map +1 -1
  90. package/dist/tools/executeSwap.d.ts +13 -29
  91. package/dist/tools/executeSwap.d.ts.map +1 -1
  92. package/dist/tools/executeSwap.js +68 -46
  93. package/dist/tools/executeSwap.js.map +1 -1
  94. package/dist/tools/explainRisk.d.ts +30 -0
  95. package/dist/tools/explainRisk.d.ts.map +1 -0
  96. package/dist/tools/explainRisk.js +33 -0
  97. package/dist/tools/explainRisk.js.map +1 -0
  98. package/dist/tools/getAgentWallet.d.ts +22 -0
  99. package/dist/tools/getAgentWallet.d.ts.map +1 -0
  100. package/dist/tools/getAgentWallet.js +28 -0
  101. package/dist/tools/getAgentWallet.js.map +1 -0
  102. package/dist/tools/getAgentWalletBalance.d.ts +12 -0
  103. package/dist/tools/getAgentWalletBalance.d.ts.map +1 -0
  104. package/dist/tools/getAgentWalletBalance.js +71 -0
  105. package/dist/tools/getAgentWalletBalance.js.map +1 -0
  106. package/dist/tools/getExecutionHistory.d.ts +4 -4
  107. package/dist/tools/getGasPrice.d.ts +26 -8
  108. package/dist/tools/getGasPrice.d.ts.map +1 -1
  109. package/dist/tools/getGasPrice.js +43 -35
  110. package/dist/tools/getGasPrice.js.map +1 -1
  111. package/dist/tools/getPoolInfo.d.ts +47 -59
  112. package/dist/tools/getPoolInfo.d.ts.map +1 -1
  113. package/dist/tools/getPoolInfo.js +96 -57
  114. package/dist/tools/getPoolInfo.js.map +1 -1
  115. package/dist/tools/getTokenPrice.d.ts +95 -9
  116. package/dist/tools/getTokenPrice.d.ts.map +1 -1
  117. package/dist/tools/getTokenPrice.js +95 -56
  118. package/dist/tools/getTokenPrice.js.map +1 -1
  119. package/dist/tools/getWalletBalance.d.ts +40 -11
  120. package/dist/tools/getWalletBalance.d.ts.map +1 -1
  121. package/dist/tools/getWalletBalance.js +64 -47
  122. package/dist/tools/getWalletBalance.js.map +1 -1
  123. package/dist/tools/publishRiskScore.d.ts +12 -10
  124. package/dist/tools/publishRiskScore.d.ts.map +1 -1
  125. package/dist/tools/publishRiskScore.js +33 -19
  126. package/dist/tools/publishRiskScore.js.map +1 -1
  127. package/dist/tools/queryRiskRegistry.d.ts +3 -3
  128. package/dist/tools/safehandsPreflightCheck.d.ts +78 -0
  129. package/dist/tools/safehandsPreflightCheck.d.ts.map +1 -0
  130. package/dist/tools/safehandsPreflightCheck.js +48 -0
  131. package/dist/tools/safehandsPreflightCheck.js.map +1 -0
  132. package/dist/tools/safehandsRiskReport.d.ts +82 -0
  133. package/dist/tools/safehandsRiskReport.d.ts.map +1 -0
  134. package/dist/tools/safehandsRiskReport.js +29 -0
  135. package/dist/tools/safehandsRiskReport.js.map +1 -0
  136. package/dist/tools/safehandsSafeExecute.d.ts +21 -0
  137. package/dist/tools/safehandsSafeExecute.d.ts.map +1 -0
  138. package/dist/tools/safehandsSafeExecute.js +76 -0
  139. package/dist/tools/safehandsSafeExecute.js.map +1 -0
  140. package/dist/tools/safehandsWalletHealth.d.ts +15 -0
  141. package/dist/tools/safehandsWalletHealth.d.ts.map +1 -0
  142. package/dist/tools/safehandsWalletHealth.js +104 -0
  143. package/dist/tools/safehandsWalletHealth.js.map +1 -0
  144. package/dist/tools/safehandsX402Preflight.d.ts +27 -0
  145. package/dist/tools/safehandsX402Preflight.d.ts.map +1 -0
  146. package/dist/tools/safehandsX402Preflight.js +66 -0
  147. package/dist/tools/safehandsX402Preflight.js.map +1 -0
  148. package/dist/tools/sendPayment.d.ts +13 -35
  149. package/dist/tools/sendPayment.d.ts.map +1 -1
  150. package/dist/tools/sendPayment.js +53 -47
  151. package/dist/tools/sendPayment.js.map +1 -1
  152. package/dist/tools/simulateTransaction.d.ts +4 -4
  153. package/dist/tools/tokenRegistryStatus.d.ts +27 -0
  154. package/dist/tools/tokenRegistryStatus.d.ts.map +1 -0
  155. package/dist/tools/tokenRegistryStatus.js +97 -0
  156. package/dist/tools/tokenRegistryStatus.js.map +1 -0
  157. package/dist/tools/x402PayAndFetch.d.ts +40 -16
  158. package/dist/tools/x402PayAndFetch.d.ts.map +1 -1
  159. package/dist/tools/x402PayAndFetch.js +115 -47
  160. package/dist/tools/x402PayAndFetch.js.map +1 -1
  161. package/dist/x402Server.js +149 -115
  162. package/dist/x402Server.js.map +1 -1
  163. package/examples/pharos-skill-engine/SKILL.safehands.md +85 -0
  164. package/examples/pharos-skill-engine/assets/safehands/example-actions.json +49 -0
  165. package/examples/pharos-skill-engine/assets/safehands/policy-defaults.json +11 -0
  166. package/examples/pharos-skill-engine/references/safehands.md +345 -0
  167. package/examples/scenario-hack.ts +38 -0
  168. package/package.json +19 -5
  169. package/skill/SKILL.md +127 -0
  170. package/skill/assets/safehands/example-actions.json +49 -0
  171. package/skill/assets/safehands/policy-defaults.json +11 -0
  172. package/skill/references/safehands.md +345 -0
  173. package/.agents/skill/safehands/SKILL.md +0 -200
  174. package/.agents/skill/safehands/assets/networks.json +0 -24
  175. package/.agents/skill/safehands/assets/tokens.json +0 -60
@@ -0,0 +1,345 @@
1
+ # SafeHands Guard Reference
2
+
3
+ ## Overview
4
+
5
+ SafeHands Guard is a Transaction Safety Firewall / Guardrail Skill for Pharos Skill Engine. It lets an AI agent run policy-based preflight checks before execution. The CLI adapter returns the same standard response envelope as the MCP tools.
6
+
7
+ ```json
8
+ {
9
+ "success": true,
10
+ "data": {},
11
+ "error": null,
12
+ "timestamp": "ISO_DATE_STRING"
13
+ }
14
+ ```
15
+
16
+ Failure responses use:
17
+
18
+ ```json
19
+ {
20
+ "success": false,
21
+ "data": null,
22
+ "error": {
23
+ "code": "ERROR_CODE",
24
+ "message": "Human-readable message",
25
+ "retryable": false,
26
+ "source": "source_name"
27
+ },
28
+ "timestamp": "ISO_DATE_STRING"
29
+ }
30
+ ```
31
+
32
+ ## Command Template
33
+
34
+ ```bash
35
+ npx safehands-pharos skill <tool_name> --input-json '<json>'
36
+ ```
37
+
38
+ All outputs are valid JSON. Do not parse stdout as prose.
39
+
40
+ ## SafeHands Preflight Check
41
+
42
+ ### Overview
43
+
44
+ Use this command before any payment, token approval, swap, x402 payment, registry publish, or custom contract call. It returns `ALLOW`, `WARN`, `BLOCK`, `REQUIRE_CONFIRMATION`, `REQUIRE_FUNDING`, or `REQUIRE_TOKEN_REVIEW`.
45
+
46
+ ### Command Template
47
+
48
+ ```bash
49
+ npx safehands-pharos skill safehands_preflight_check --input-json '<action_json>'
50
+ ```
51
+
52
+ Example:
53
+
54
+ ```bash
55
+ npx safehands-pharos skill safehands_preflight_check --input-json '{"actionType":"approve_token","chainId":688689,"tokenAddress":"0xE0BE08c77f415F577A1B3A9aD7a1Df1479564ec8","spenderAddress":"0x0000000000000000000000000000000000000001","amount":"1"}'
56
+ ```
57
+
58
+ ### Parameters
59
+
60
+ | Parameter | Type | Required | Description |
61
+ |---|---|---|---|
62
+ | actionType | string | Yes | `send_payment`, `approve_token`, `execute_swap`, `x402_pay_and_fetch`, `publish_risk_score`, `custom_contract_call` |
63
+ | chainId | number | Yes | Must be `688689` for Pharos Atlantic Testnet |
64
+ | walletAddress | address | Optional | Agent wallet address |
65
+ | targetAddress | address | Optional | Recipient, spender, or contract target |
66
+ | tokenAddress | address | Optional | Token involved in the action |
67
+ | amount | string | Optional | Amount to send, approve, swap, or pay |
68
+ | url | string | Optional | x402 URL for x402 actions |
69
+ | approvalAmount | string | Optional | Approval amount, including `max` for unlimited approval |
70
+ | recipient | address | Optional | Payment recipient |
71
+ | spender | address | Optional | Token spender |
72
+
73
+ ### Output Parsing
74
+
75
+ | Field | Meaning |
76
+ |---|---|
77
+ | decision | `ALLOW`, `WARN`, `BLOCK`, `REQUIRE_CONFIRMATION`, `REQUIRE_FUNDING`, `REQUIRE_TOKEN_REVIEW` |
78
+ | riskLevel | `LOW`, `MEDIUM`, `HIGH`, `CRITICAL`, `UNKNOWN` |
79
+ | safeToExecute | `true` or `false` |
80
+ | reasons | Why SafeHands made the decision |
81
+ | requiredActions | What user/agent should do next |
82
+ | checks | Individual policy checks |
83
+ | environment | Expected to be `atlantic-testnet` |
84
+ | chainId | Expected to be `688689` |
85
+ | isMainnet | Expected to be `false` |
86
+
87
+ ### Error Handling
88
+
89
+ | Error code | Meaning | Agent action |
90
+ |---|---|---|
91
+ | `TOOL_EXECUTION_FAILED` | Input failed schema validation or handler threw | Fix the JSON input and retry |
92
+ | `CHAIN_ID_MISMATCH` | Action targets the wrong chain | Switch to Pharos Atlantic Testnet |
93
+ | `MAINNET_NOT_SUPPORTED` | Mainnet action was requested | Do not execute |
94
+ | `POLICY_BLOCKED` | Safety policy blocked execution | Explain reasons to the user |
95
+
96
+ ### Agent Guidelines
97
+
98
+ 1. Always run preflight before write actions.
99
+ 2. If decision is `BLOCK`, do not execute the action.
100
+ 3. If decision is `WARN`, explain the risk and ask for user confirmation.
101
+ 4. If decision is `REQUIRE_CONFIRMATION`, ask for explicit user approval.
102
+ 5. If decision is `ALLOW`, the action may continue through Pharos Skill Engine or MCP execution.
103
+
104
+ ## SafeHands x402 Preflight
105
+
106
+ ### Overview
107
+
108
+ Use this command before paying any x402 resource. It checks URL safety, SSRF protection, endpoint probing when requested, payment amount, token, signer readiness, `MAX_X402_PAYMENT_USDC`, and whether payment appears required.
109
+
110
+ ### Command Template
111
+
112
+ ```bash
113
+ npx safehands-pharos skill safehands_x402_preflight --input-json '<x402_action_json>'
114
+ ```
115
+
116
+ Example:
117
+
118
+ ```bash
119
+ npx safehands-pharos skill safehands_x402_preflight --input-json '{"url":"https://example.com/assess-risk","paymentAmountUsdc":"0.001","probeEndpoint":false}'
120
+ ```
121
+
122
+ ### Parameters
123
+
124
+ | Parameter | Type | Required | Description |
125
+ |---|---|---|---|
126
+ | url | string | Yes | x402 resource URL |
127
+ | method | string | Optional | HTTP method, default `GET` |
128
+ | paymentAmountUsdc | string | Optional | Estimated USDC payment amount |
129
+ | paymentTokenAddress | address | Optional | x402 payment token address |
130
+ | agentId | string | Optional | Managed wallet agent ID for signer readiness |
131
+ | probeEndpoint | boolean | Optional | If true, SafeHands probes the endpoint to detect HTTP 402 |
132
+
133
+ ### Output Parsing
134
+
135
+ | Field | Meaning |
136
+ |---|---|
137
+ | decision | Safety decision for payment |
138
+ | safeToExecute | Whether the agent may continue |
139
+ | safeToPay | Interpret as true only when `decision` is `ALLOW` |
140
+ | paymentAmountUsdc | Estimated payment amount |
141
+ | maxPaymentUsdc | Configured `MAX_X402_PAYMENT_USDC` |
142
+ | signerAvailable | Whether a signer is available if payment is required |
143
+ | probe.paymentRequired | `true`, `false`, or `unknown` |
144
+
145
+ ### Error Handling
146
+
147
+ | Error code | Meaning | Agent action |
148
+ |---|---|---|
149
+ | `SSRF_BLOCKED` | URL points to local/private/unsafe host | Do not fetch or pay |
150
+ | `NO_SIGNER_AVAILABLE` | Payment may require signer but none is ready | Ask user to configure managed wallet or signer |
151
+ | `POLICY_BLOCKED` | Amount, URL, token, or chain failed policy | Do not pay |
152
+
153
+ ### Agent Guidelines
154
+
155
+ 1. Run x402 preflight before paying any x402 resource.
156
+ 2. If the endpoint is free, do not request a private key.
157
+ 3. If HTTP 402/payment is required, verify amount, token, URL, and signer readiness.
158
+ 4. If decision is `BLOCK`, do not pay.
159
+ 5. If signer is unavailable, ask user to configure managed wallet or signer.
160
+
161
+ ## SafeHands Wallet Health
162
+
163
+ ### Overview
164
+
165
+ Use this command to check whether the current or managed agent wallet can pay gas, pay x402 resources, and execute write tools safely.
166
+
167
+ ### Command Template
168
+
169
+ ```bash
170
+ npx safehands-pharos skill safehands_wallet_health --input-json '{}'
171
+ ```
172
+
173
+ ### Parameters
174
+
175
+ | Parameter | Type | Required | Description |
176
+ |---|---|---|---|
177
+ | agentId | string | Optional | Managed wallet agent ID |
178
+ | walletAddress | address | Optional | Explicit wallet address for read-only balance checks |
179
+
180
+ ### Output Parsing
181
+
182
+ | Field | Meaning |
183
+ |---|---|
184
+ | status | `READY`, `DEGRADED`, or `NOT_READY` |
185
+ | walletReady | Treat as true only when status is `READY` |
186
+ | walletMode | `none`, `env`, `managed-testnet`, or future signer mode |
187
+ | writeToolsEnabled | Whether execution tools can broadcast |
188
+ | readiness.canPayGas | PHRS gas readiness |
189
+ | readiness.canPayX402 | USDC x402 readiness |
190
+ | readiness.canExecuteWrites | Signer + gas + write-tool readiness |
191
+ | balances.PHRS | Native gas balance if RPC is available |
192
+ | balances.USDC | USDC balance if RPC is available |
193
+
194
+ ### Error Handling
195
+
196
+ | Error code | Meaning | Agent action |
197
+ |---|---|---|
198
+ | `RPC_UNAVAILABLE` | RPC balance read failed | Treat wallet health as degraded and retry later |
199
+ | `NO_SIGNER_AVAILABLE` | No signer mode configured | Ask user to configure wallet mode |
200
+ | `WALLET_ENCRYPTION_KEY_REQUIRED` | Persistent managed wallet needs encryption key | Ask user to configure testnet wallet storage |
201
+
202
+ ### Agent Guidelines
203
+
204
+ 1. Run wallet health before x402 payment or write execution.
205
+ 2. Do not execute writes if `writeToolsEnabled` is false.
206
+ 3. If RPC is unavailable, report degraded status rather than assuming the wallet is funded.
207
+ 4. If signer is unavailable, do not ask the user to paste a key into chat.
208
+
209
+ ## Token Registry Status
210
+
211
+ ### Overview
212
+
213
+ Use this command to classify whether a token is canonical, test liquidity, custom/non-registry, unknown, or invalid. The exact user-provided token address is checked; SafeHands does not silently replace it.
214
+
215
+ ### Command Template
216
+
217
+ ```bash
218
+ npx safehands-pharos skill token_registry_status --input-json '{"token":"<token_address>"}'
219
+ ```
220
+
221
+ ### Parameters
222
+
223
+ | Parameter | Type | Required | Description |
224
+ |---|---|---|---|
225
+ | token | string | Yes | Token symbol or exact contract address to classify |
226
+
227
+ ### Status Values
228
+
229
+ | Status | Meaning |
230
+ |---|---|
231
+ | `CANONICAL_TESTNET_TOKEN` | Token is recognized as canonical for this testnet config |
232
+ | `TEST_LIQUIDITY_TOKEN` | Token is a test/demo liquidity token |
233
+ | `CUSTOM_NON_REGISTRY` | Valid address but not in SafeHands registry |
234
+ | `UNKNOWN` | Unknown status |
235
+ | `INVALID_ADDRESS` | Input is not a valid EVM address or known symbol |
236
+
237
+ ### Output Parsing
238
+
239
+ | Field | Meaning |
240
+ |---|---|
241
+ | status | Registry classification |
242
+ | normalizedAddress | Checksummed address when valid |
243
+ | verificationStatus | `DOCS_VERIFIED`, `PROJECT_CONFIGURED`, `UNVERIFIED_CUSTOM_TOKEN`, etc. |
244
+ | docsSource | Source used for classification, when available |
245
+
246
+ ### Error Handling
247
+
248
+ | Error code | Meaning | Agent action |
249
+ |---|---|---|
250
+ | `TOOL_EXECUTION_FAILED` | Missing token input or malformed request | Ask for exact token address |
251
+
252
+ ### Agent Guidelines
253
+
254
+ 1. Never silently replace user-provided token addresses.
255
+ 2. If token is custom, clearly say it is custom/non-registry.
256
+ 3. If token is canonical, show `docsSource` or `verificationStatus`.
257
+
258
+ ## Explain Risk
259
+
260
+ ### Overview
261
+
262
+ Use this command to convert a policy result into a concise human-readable explanation.
263
+
264
+ ### Command Template
265
+
266
+ ```bash
267
+ npx safehands-pharos skill explain_risk --input-json '<risk_json>'
268
+ ```
269
+
270
+ ### Parameters
271
+
272
+ | Parameter | Type | Required | Description |
273
+ |---|---|---|---|
274
+ | decision | string | Yes | Policy decision |
275
+ | riskLevel | string | Yes | Risk level |
276
+ | reasons | string[] | Optional | Reasons returned by policy engine |
277
+ | requiredActions | string[] | Optional | Required next actions |
278
+
279
+ ### Output Parsing
280
+
281
+ | Field | Meaning |
282
+ |---|---|
283
+ | explanation | Human-readable explanation |
284
+ | decision | Original policy decision |
285
+ | riskLevel | Original risk level |
286
+
287
+ ### Error Handling
288
+
289
+ | Error code | Meaning | Agent action |
290
+ |---|---|---|
291
+ | `TOOL_EXECUTION_FAILED` | Invalid risk JSON | Re-run with a policy result or valid fields |
292
+
293
+ ### Agent Guidelines
294
+
295
+ 1. Use this after a preflight result when the user asks “why?”.
296
+ 2. Keep the explanation factual and tied to SafeHands reasons.
297
+ 3. Do not override a `BLOCK` decision with reassuring language.
298
+
299
+ ## SafeHands Risk Report
300
+
301
+ ### Overview
302
+
303
+ Use this command to generate a judge/demo-friendly safety report. It runs preflight and returns a summary, reasons, required actions, checks, and environment.
304
+
305
+ ### Command Template
306
+
307
+ ```bash
308
+ npx safehands-pharos skill safehands_risk_report --input-json '<action_or_policy_result_json>'
309
+ ```
310
+
311
+ ### Parameters
312
+
313
+ | Parameter | Type | Required | Description |
314
+ |---|---|---|---|
315
+ | actionType | string | Yes | Same action type list as preflight |
316
+ | chainId | number | Optional | Defaults to Pharos Atlantic Testnet |
317
+ | amount | string | Optional | Amount involved |
318
+ | tokenAddress | address | Optional | Token involved |
319
+ | url | string | Optional | x402 URL when relevant |
320
+ | includeChecks | boolean | Optional | Include detailed policy checks, default true |
321
+
322
+ ### Output Parsing
323
+
324
+ | Field | Meaning |
325
+ |---|---|
326
+ | summary | Human-readable risk report |
327
+ | decision | Safety decision |
328
+ | riskLevel | Risk level |
329
+ | reasons | Reasons for decision |
330
+ | requiredActions | Next steps |
331
+ | checks | Detailed checks when requested |
332
+
333
+ ### Error Handling
334
+
335
+ | Error code | Meaning | Agent action |
336
+ |---|---|---|
337
+ | `TOOL_EXECUTION_FAILED` | Invalid action JSON | Fix the action JSON and retry |
338
+ | `POLICY_BLOCKED` | Safety policy blocked the action | Do not execute the action |
339
+
340
+ ### Agent Guidelines
341
+
342
+ 1. Use this for demos, user-facing summaries, and audit trails.
343
+ 2. If the report says `BLOCK`, stop execution.
344
+ 3. If the report says `WARN` or `REQUIRE_CONFIRMATION`, ask for explicit user confirmation.
345
+ 4. If the report says `ALLOW`, the action may continue through Pharos Skill Engine or MCP execution.
@@ -1,200 +0,0 @@
1
- name: safehands
2
- version: 1.0.0
3
- description: Risk intelligence middleware for Pharos agents. 17 production tools that assess, simulate, and gate every on-chain action — swaps, payments, approvals — with a 5-dimension risk engine, an on-chain RiskRegistry, and x402 protocol micro-payments.
4
- author: "SZtch"
5
- chain: pharos
6
- tags: [execution, safety, defi, swap, payment, risk, registry, middleware, composable, x402]
7
- categories: [safety, execution, defi, intelligence]
8
- ---
9
-
10
- # SafeHands
11
-
12
- > *"Agents that execute without thinking are dangerous. SafeHands executes anything on Pharos — but never blindly."*
13
-
14
- SafeHands is **risk intelligence middleware** for the Pharos AI Agent economy. It sits between agent intent and on-chain execution, providing a 17-tool safety layer that any agent can compose into their workflow. Every swap, transfer, and approval flows through a 5-dimension risk assessment before touching the chain.
15
-
16
- SafeHands is not an agent — it's the safety layer other agents depend on.
17
-
18
- ---
19
-
20
- ## Tools (17)
21
-
22
- ### Core Safety — Assess before you execute
23
-
24
- | Tool | Description |
25
- |------|-------------|
26
- | `assess_risk` | 5-dimension risk score (0–100) for any swap or transfer. Auto-publishes to on-chain RiskRegistry when privateKey is provided. |
27
- | `check_token_security` | Check token contract security (honeypot check, tax checks, mint privileges) via GoPlus Security API. |
28
- | `simulate_transaction` | Dry run via eth_call — zero gas. Returns expected output, gas estimate, and revert reasons before committing. |
29
- | `estimate_gas` | Pre-execution gas cost in PHRS and USD. Checks whether the wallet has sufficient funds for gas + value. |
30
-
31
- ### Execution — Act with guardrails
32
-
33
- | Tool | Description |
34
- |------|-------------|
35
- | `execute_swap` | Swap tokens via FaroSwap (DODO) with built-in risk gate. Automatically blocks if risk score exceeds 80. |
36
- | `send_payment` | Native PHRS transfer with risk assessment, address validation, balance checks, and high-exposure warnings. Blocks if risk score exceeds 80. |
37
- | `approve_token` | ERC-20 approval for DODO router. Supports exact amounts or unlimited ("max") approval. |
38
-
39
- ### Market Intelligence — Know before you trade
40
-
41
- | Tool | Description |
42
- |------|-------------|
43
- | `get_token_price` | Real-time PHRS, USDC, USDT prices derived from DODO liquidity quotes on Pharos. |
44
- | `get_pool_info` | DODO pool data for any token pair — price ratio, price impact, and fees. |
45
- | `get_gas_price` | Current Pharos gas price with trend classification (low/normal/high) and cost estimates. |
46
-
47
- ### Wallet & History — Observe the full picture
48
-
49
- | Tool | Description |
50
- |------|-------------|
51
- | `get_wallet_balance` | PHRS, USDC, USDT balances for any wallet with total USD estimate. |
52
- | `check_allowance` | Check ERC-20 allowance granted to DODO router. Reports whether approval is needed before a swap. |
53
- | `get_transaction_status` | Look up any transaction by hash — status, block number, gas used, explorer link. |
54
- | `get_execution_history` | On-chain audit trail for any wallet. Categorizes activity as swaps, transfers, or other. |
55
-
56
- ### On-Chain Risk Registry — Share risk intelligence across agents
57
-
58
- | Tool | Description |
59
- |------|-------------|
60
- | `publish_risk_score` | Run risk assessment and publish the result to the on-chain RiskRegistry smart contract. |
61
- | `query_risk_registry` | Read any wallet's published risk score from the registry. Read-only — no private key needed. |
62
-
63
- ### x402 Payments — Composable micro-payment gating
64
-
65
- | Tool | Description |
66
- |------|-------------|
67
- | `x402_pay_and_fetch` | Fetch resources from an HTTP x402 payment-gated server. Automatically handles HTTP 402 payment challenge by signing a payment payload and completing the fetch. |
68
-
69
- ---
70
-
71
- ## Composability
72
-
73
- SafeHands is designed as a **building block**, not a standalone application. Other skills and agents compose SafeHands into their workflows by calling its tools as middleware.
74
-
75
- ### Read-only tools (safe for any agent, no key needed)
76
- `check_token_security` · `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`
77
-
78
- ### Read+Write tool (read without key, auto-publishes with key)
79
- `assess_risk` — returns risk score without a key; if `privateKey` is provided, also publishes the result to the on-chain RiskRegistry.
80
-
81
- ### Write tools (require privateKey per-request)
82
- `execute_swap` · `send_payment` · `approve_token` · `publish_risk_score` · `x402_pay_and_fetch`
83
-
84
- ### How Phase 2 agents compose with SafeHands
85
-
86
- ```
87
- ┌─────────────────────────────────────────────────────┐
88
- │ Phase 2 Agent (DeFi bot, payment agent, etc.) │
89
- │ │
90
- │ 1. Call assess_risk → get risk score │
91
- │ 2. Call simulate_transaction → dry run │
92
- │ 3. If safe → call execute_swap or send_payment │
93
- │ 4. Call get_transaction_status → confirm result │
94
- │ 5. Call query_risk_registry → check counterparty │
95
- └─────────────────────────────────────────────────────┘
96
- ```
97
-
98
- Any agent (including those built with **Anvita Flow**) that performs on-chain actions on Pharos can import SafeHands as its safety layer. The agent handles user intent and strategy; SafeHands handles risk gating and execution.
99
-
100
- ### Cross-agent risk intelligence
101
-
102
- The RiskRegistry contract (`0x71fc28ed3a31016b42f18764889cd911f22b67b8`) enables agents to share risk assessments:
103
-
104
- - **Agent A** publishes a risk score for a wallet via `publish_risk_score`
105
- - **Agent B** queries that score via `query_risk_registry` before interacting with the same wallet
106
- - No API keys, no centralized service — purely on-chain, permissionless
107
-
108
- ---
109
-
110
- ## Usage Examples
111
-
112
- **Example 1 — Pre-trade safety check:**
113
- ```
114
- User: "Swap 100 PHRS to USDC"
115
- Agent: → assess_risk(swap, PHRS, USDC, 100, wallet)
116
- → Score 12/100, low risk, proceed
117
- → simulate_transaction(swap, PHRS, USDC, 100)
118
- → Would succeed, ~166 USDC out
119
- → execute_swap(PHRS, USDC, 100, wallet, privateKey)
120
- → ✅ TX confirmed
121
- ```
122
-
123
- **Example 2 — Risk-gated payment:**
124
- ```
125
- User: "Send 500 PHRS to 0xabc..."
126
- Agent: → assess_risk(transfer, 500, toAddress=0xabc)
127
- → Score 85/100, critical, BLOCKED
128
- → "This transfer uses 95% of your wallet. Reduce amount or confirm override."
129
- ```
130
-
131
- **Example 3 — Portfolio check before action:**
132
- ```
133
- User: "What's in my wallet?"
134
- Agent: → get_wallet_balance(wallet) → PHRS=19.4, USDC=0.85, USDT=0
135
- → get_token_price(PHRS) → $1.66
136
- → "Your portfolio: $32.21 USD across 3 tokens"
137
- ```
138
-
139
- **Example 4 — Cross-agent reputation lookup:**
140
- ```
141
- Agent B: → query_risk_registry(0xsuspicious...)
142
- → Score 92, critical, block
143
- → "This wallet was flagged high-risk by another agent. Refusing to interact."
144
- ```
145
-
146
- ---
147
-
148
- ## Safety Model
149
-
150
- 1. **Risk-first execution** — every write tool (`execute_swap`, `send_payment`) internally calls `assess_risk` before proceeding.
151
- 2. **Automatic blocking** — actions scoring above 80 are prevented. No override without explicit `bypassRiskCheck`.
152
- 3. **Transient keys** — private keys are passed per-request and never stored, logged, or persisted.
153
- 4. **Simulation before commitment** — `simulate_transaction` lets agents verify outcomes at zero cost before committing gas.
154
- 5. **On-chain audit** — all risk scores can be published to the RiskRegistry, creating a permanent, verifiable record.
155
-
156
- ---
157
-
158
- ## On-Chain Registry
159
-
160
- **Contract:** `0x71fc28ed3a31016b42f18764889cd911f22b67b8`
161
- **Chain:** Pharos Atlantic Testnet (688689)
162
-
163
- The RiskRegistry is a Solidity smart contract deployed on Pharos that stores risk assessments on-chain. Any agent can publish. Any agent can query. No API keys, no centralized infrastructure.
164
-
165
- When `assess_risk` is called with a `privateKey`, the result is automatically published — making every risk assessment a permanent, queryable on-chain record that other agents can trust.
166
-
167
- ---
168
-
169
- ## x402 Monetized API Server
170
-
171
- 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.
172
-
173
- ### API Endpoints
174
- - `GET /health` (Free) — Health check, token registry, and receiver addresses.
175
- - `GET /assess-risk` (Paid: USDC 0.001) — Gate queries with 5-dimension risk score checks.
176
- - `GET /check-token-security` (Paid: USDC 0.001) — Verify contract security, honeypots, and token code privileges.
177
- - `GET /simulate-transaction` (Paid: USDC 0.001) — Perform dry-runs of transfers and swaps.
178
-
179
- ### Flow Architecture
180
- 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.
181
- 2. **On-Chain Settlement:** The client signs a standard authorization envelope with their private key, transferring the micro-payment directly to the recipient wallet.
182
- 3. **Resubmission:** The client resubmits the request, appending the payload signature in the `PAYMENT-SIGNATURE` header.
183
- 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.
184
-
185
- ---
186
-
187
- ## Supported Tokens
188
-
189
- Pharos Atlantic Testnet registered tokens:
190
- - **PHRS**: Native Pharos token (`0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE`)
191
- - **USDC**: USD Coin (`0xcfC8330f4BCAB529c625D12781b1C19466A9Fc8B`) - Canonical address from the official Pharos Token Registry
192
- - **USDT**: Tether USD (`0xE7E84B8B4f39C507499c40B4ac199B050e2882d5`)
193
- - **WBTC**: Wrapped BTC (`0x0c64F03EEa5c30946D5c55B4b532D08ad74638a4`)
194
- - **WETH**: Wrapped ETH (`0x7d211F77525ea39A0592794f793cC1036eEaccD5`)
195
- - **WPHRS**: Wrapped PHRS (`0x838800b758277CC111B2d48Ab01e5E164f8E9471`)
196
- - **tUSDC**: Test USDC (`0xE0BE08c77f415F577A1B3A9aD7a1Df1479564ec8`) - Legacy test token used in some x402 examples
197
-
198
- ## Chain
199
-
200
- Pharos Atlantic Testnet — Chain ID 688689 — RPC: `https://atlantic.dplabs-internal.com/`
@@ -1,24 +0,0 @@
1
- {
2
- "atlantic": {
3
- "name": "Pharos Atlantic Testnet",
4
- "chainId": 688689,
5
- "rpcUrl": "https://atlantic.dplabs-internal.com/",
6
- "explorerUrl": "https://atlantic.pharosscan.xyz/",
7
- "nativeCurrency": {
8
- "name": "PHRS",
9
- "symbol": "PHRS",
10
- "decimals": 18
11
- }
12
- },
13
- "pacific": {
14
- "name": "Pharos Pacific Mainnet",
15
- "chainId": 1672,
16
- "rpcUrl": "https://rpc.pharos.xyz",
17
- "explorerUrl": "https://www.pharosscan.xyz",
18
- "nativeCurrency": {
19
- "name": "PROS",
20
- "symbol": "PROS",
21
- "decimals": 18
22
- }
23
- }
24
- }
@@ -1,60 +0,0 @@
1
- {
2
- "atlantic": [
3
- {
4
- "symbol": "USDC",
5
- "name": "USD Coin",
6
- "address": "0xcfC8330f4BCAB529c625D12781b1C19466A9Fc8B",
7
- "decimals": 6
8
- },
9
- {
10
- "symbol": "USDT",
11
- "name": "Tether USD",
12
- "address": "0xE7E84B8B4f39C507499c40B4ac199B050e2882d5",
13
- "decimals": 6
14
- },
15
- {
16
- "symbol": "WBTC",
17
- "name": "Wrapped BTC",
18
- "address": "0x0c64F03EEa5c30946D5c55B4b532D08ad74638a4",
19
- "decimals": 18
20
- },
21
- {
22
- "symbol": "WETH",
23
- "name": "Wrapped ETH",
24
- "address": "0x7d211F77525ea39A0592794f793cC1036eEaccD5",
25
- "decimals": 18
26
- },
27
- {
28
- "symbol": "WPHRS",
29
- "name": "Wrapped PHRS",
30
- "address": "0x838800b758277CC111B2d48Ab01e5E164f8E9471",
31
- "decimals": 18
32
- }
33
- ],
34
- "pacific": [
35
- {
36
- "symbol": "WPROS",
37
- "name": "Wrapped PROS",
38
- "address": "0x52c48d4213107b20bc583832b0d951fb9ca8f0b0",
39
- "decimals": 18
40
- },
41
- {
42
- "symbol": "USDC",
43
- "name": "USD Coin",
44
- "address": "0xc879c018db60520f4355c26ed1a6d572cdac1815",
45
- "decimals": 6
46
- },
47
- {
48
- "symbol": "LINK",
49
- "name": "Chainlink Token",
50
- "address": "0x51e2A24742Db77604B881d6781Ee16B5b8fcBE29",
51
- "decimals": 18
52
- },
53
- {
54
- "symbol": "WETH",
55
- "name": "Wrapped ETH",
56
- "address": "0x1f4b7011Ee3d53969bb67F59428a9ec0477856E9",
57
- "decimals": 18
58
- }
59
- ]
60
- }