Add agent-risk-firewall plugin

[maixuancanh]

Plugin Submission

Plugin name: agent-risk-firewall
Version: 1.2.0
Type: new-plugin

Checklist

• plugin-store lint passes locally with no errors
• I have read the Development Guide
• My plugin does NOT use reserved prefixes (okx-, official-, plugin-store-)
• LICENSE file is included
• SKILL.md has YAML frontmatter with name and description

What does this plugin do?

agent-risk-firewall is a pre-trade risk firewall for OKX Agentic Wallet workflows on X Layer and Solana. It evaluates proposed swaps, token trades, and approvals before signing, then returns a deterministic JSON verdict: allow, warn, or block.

It supports policy profiles (balanced, strict, competition, degen-small-size), optional external evidence from other plugins, approval-specific risk checks, and audit trail fields (decisionId, policyVersion, evidenceHash). It does not sign, broadcast, execute swaps, revoke approvals, or handle private keys.

Update: v1.2.0 adds Competition Mode Enhancer, including competition context checks, join/status validation, supported-chain checks, participation threshold warnings, and stable/native-only pair blocking.

Which onchainos commands does it use?

The Python CLI may call these read-only / pre-execution OnchainOS commands when enough input context is available:

• onchainos security token-scan
• onchainos security tx-scan
• onchainos gateway simulate
• onchainos token liquidity

The plugin documentation also describes integration patterns where a separate trading skill or agent may call:

• onchainos swap quote
• onchainos swap swap

agent-risk-firewall itself does not call onchainos swap execute.

Security Considerations

This plugin is a defensive pre-sign guardrail. It never asks for, stores, or handles private keys, seed phrases, mnemonics, wallet credentials, or API secrets.

It does not sign transactions, broadcast transactions, execute swaps, revoke approvals, or transfer assets. It only evaluates intent/quote/transaction context and returns a verdict for the agent to follow.

If scan or simulation data is unavailable, the firewall treats verification as incomplete. In balanced, competition, and degen-small-size profiles this returns at least warn; in strict profile it returns block.

Agent behavior is explicitly defined:

• allow: agent may continue only if the user already requested execution
• warn: agent must show reasons and ask for explicit confirmation
• block: agent must stop and must not ask the user to sign or broadcast

Testing

Local validation completed:

• plugin-store lint .\skills\agent-risk-firewall passed
• python -m pytest .\skills\agent-risk-firewall\tests -q -p no:cacheprovider passed with 28 tests

Test coverage includes:

• token HIGH -> warn
• token CRITICAL buy/swap -> block
• token CRITICAL sell -> warn
• tx-scan warn -> warn
• tx-scan block -> block
• simulation revert -> block
• slippage and price impact thresholds
• address/chain mismatch
• scan timeout/unavailable behavior
• policy profiles: balanced, strict, competition, degen-small-size
• external evidence from GoPlus, Birdeye, and RootData
• approval-specific risk checks
• deterministic audit trail

Integration dry-runs with real OnchainOS were also performed without signing or broadcasting:

• Solana SOL -> USDC dry-run using unsigned transaction context, token scan, tx-scan, liquidity, and simulation
• X Layer OKB -> USDT quote/token-level dry-run