GuardSkill — a pre-transaction security gate for Pharos AI agents

GuardSkill is a read-only skill that an autonomous agent calls before it signs a transaction to (or approves) a contract on Pharos. It returns a structured risk verdict — is the target upgradeable, who can mint, can it pause/blacklist/freeze, does it self-destruct, are there honeypot-style fee/trading controls, can a privileged role pull funds — and a clear ok / caution / block recommendation.

The Pharos Agent Carnival's premise is agents that are native on-chain economic actors: they transfer, pay, swap, and approve autonomously. The missing primitive in that vision is a safety gate before the signature. GuardSkill is that gate, and it is the kind of secure-by-default building block the hackathon's CertiK Skill Scanner standard is asking for.

Why this matters

An agent that can move funds without a human in the loop will, sooner or later, be pointed at a malicious or mutable contract: an upgradeable proxy whose logic is swapped after the agent "trusted" it, a token with an owner that can mint or blacklist, a honeypot that accepts buys and blocks sells, a contract with selfdestruct or a privileged withdrawAll. A trading/payments agent has no built-in way to notice. GuardSkill gives every other agent a single tool to ask "is it safe to transact with this address?" and a policy to act on the answer.

What it checks (from bytecode + on-chain state, no source required)

• Upgradeability — EIP-1967 (transparent/UUPS), beacon proxies, EIP-1167 minimal proxies, and upgradeTo / upgradeToAndCall / changeAdmin in the dispatch table. Upgradeable logic is the single biggest "trusted it yesterday, rugged today" risk for an agent.
• Ownership / admin powers — transferOwnership, setOwner, a live owner() account.
• Supply control — mint(...), mutable max supply.
• Freeze / censorship — pause, blacklist / addBlackList / setBlocked / freeze.
• Honeypot / fee skim — adjustable setFee / setTaxFee / setMaxTxAmount / trading toggles on a token.
• Fund movement / rug — withdrawAll, emergencyWithdraw, sweep, rescueTokens, and the raw SELFDESTRUCT opcode.

Detection is done with a proper opcode walker that skips PUSH immediates (so data bytes are never mistaken for opcodes) and strips the Solidity metadata trailer (so the CBOR tail is never scanned as code). Dangerous function selectors are computed at load time from their signatures, so the curated list can't drift out of sync with reality. The result: it works on unverified contracts, and it does not raise the kind of false positives a naive byte-search would.

It is read-only by design — only eth_getCode, eth_getStorageAt, and view calls. It never sends a transaction and never needs a private key, which is exactly the trust profile a security tool should have.

Three ways to consume it

1. LangChain / LangGraph tool (drop into any pharos-agent-kit agent's tool array):

   import { GuardSkillTool } from "pharos-guardskill";
   const tools = [ new GuardSkillTool(), /* ...your other Pharos tools */ ];
   // system prompt: "Before any transfer/approve, call guard_skill_check_contract_risk;
   //                 if level == 'block', refuse and escalate."
   

2. Model Context Protocol server (mount in Claude / any MCP host / the kit's MCP host):

   npm run mcp           # exposes the `check_contract_risk` tool over stdio
   

3. pharos-agent-kit Action (register in the kit's action registry; auto-exposed to its MCP + Vercel AI adapters):

   import { checkContractRiskAction } from "pharos-guardskill";
   

Core engine, if you just want the function:

import { analyzeContract, makePharosClient } from "pharos-guardskill";
const report = await analyzeContract(makePharosClient(), "0xTarget");

Live evidence

Run against any EVM RPC where the bytecode is real (Pharos is EVM, so the analysis is identical):

$ GUARD_RPC_URL=https://ethereum-rpc.publicnode.com npm run demo

[BLOCK]  USDC (upgradeable proxy + admin powers)   risk 100/100
   - [high] upgradeTo(address) / upgradeToAndCall(...) / changeAdmin(address) — logic is upgradeable
   - [low]  live owner() = 0xFcb1…AE3a
   => BLOCK: do not transact autonomously; require human review / allowlist.

[OK]     WETH (immutable, no owner/mint)            risk 0/100
   => OK: no high-risk controls in bytecode (still cap approvals).

[OK]     EOA (no code at address)
   => externally-owned account; native transfer carries no contract-logic risk.

The agent-side gate:

$ GUARD_RPC_URL=https://ethereum-rpc.publicnode.com npm run demo:agent

Agent wants to: approve + swap on USDC  -> GuardSkill level=block -> DECISION: REFUSE, escalate to human.
Agent wants to: wrap ETH via WETH       -> GuardSkill level=ok    -> DECISION: PROCEED (bounded approval).

Run it

npm install
npm test          # network-free unit tests for the bytecode walker
npm run demo      # screen addresses; pass your own:  npm run demo -- 0xYourContract
npm run mcp       # start the MCP server

Point it at Pharos with PHAROS_RPC_URL (and PHAROS_CHAIN_ID / PHAROS_NETWORK_NAME if needed); it defaults to Pharos Devnet (chainId 50002) to match pharos-agent-kit.

Scope and honest limitations

• It is a heuristic bytecode + state scan, not a full audit. It surfaces capabilities and control surfaces, not proof of intent. A flagged contract may be perfectly safe (e.g. an upgradeable protocol governed by a timelock+multisig); an unflagged one can still have logic bugs.
• Source-verification status and off-chain reputation are out of scope here; they slot in as additional flags if an explorer/reputation API is available on the target network.
• The dangerous-signature list is curated and extensible (src/selectors.ts). It favors recall (better to flag for human review than to miss a control).

Roadmap (if it advances)

• Pull source-verification + creation-tx age from the Pharos explorer API as extra flags.
• Integrate GoPlus-style token-security signals where available on Pharos.
• An on-chain allowlist/denylist registry so agents can share verdicts and a curator can vouch for known-good contracts.

License

MIT.