@trucore/openclaw-atf

OpenClaw plugin for the TruCore Agent Transaction Firewall (ATF).

Gives OpenClaw agents first-class tools to discover, adopt, and report on ATF — the policy-enforced transaction firewall for autonomous DeFi agents. ATF evaluates swap, lend, and perps intents against a human-configured policy before any transaction reaches the chain. It never signs. It is deny-by-default.

Install

openclaw plugins install @trucore/openclaw-atf
openclaw gateway restart

What this plugin does

This plugin registers 6 optional agent tools into OpenClaw:

All tools are optional — agents and operators must opt in via OpenClaw's tool allowlist. Default-safe:

• safety.allowNetwork = false — atf_discover returns offline instructions unless explicitly enabled.
• safety.allowExecuteSafe = true — bootstrap execute-safe runs (env/verify only; no signing).
• ATF never signs transactions.

Enable tools

Add the plugin tools to your OpenClaw agent's allowlist. Example OpenClaw config:

{
  "plugins": {
    "trucore-atf": {
      "atfCli": "atf",
      "prefer": "cli",
      "receiptsDir": "./atf_receipts",
      "safety": {
        "allowExecuteSafe": true,
        "allowNetwork": false
      }
    }
  },
  "tools": {
    "allowlist": [
      "atf_discover",
      "atf_bootstrap_plan",
      "atf_bootstrap_execute_safe",
      "atf_protect_intent",
      "atf_verify_receipt",
      "atf_report_savings"
    ]
  }
}

To allow live manifest fetching, set safety.allowNetwork = true (agent environment must have outbound HTTP access).

Config reference

Example: "ATF saved you" message

When your agent runs atf_report_savings, it produces a receipt-backed human summary like:

=== ATF Protection Summary ===

ATF prevented 12 risky actions.

Top deny reasons:
  • PERPS_MARKET_NOT_ALLOWED: 7 times
  • PERPS_ORDER_TYPE_NOT_ALLOWED: 3 times
  • SWAP_SLIPPAGE_TOO_HIGH: 2 times

Evidence: 12 verified receipts.
  receipt: sha256:a1b2c3d4e5f6...
  receipt: sha256:9e8d7c6b5a4f...
  ... and 10 more.

No savings estimate available. To enable estimates, include
exposure_hints (notional_usd, leverage, slippage_bps) in
intentJson when calling atf_protect_intent.

Verify receipts: atf receipts verify --receipt <hash>

When exposure_hints are provided at protect time, the report adds a conservative estimate:

Conservative savings estimate: $4,200.00
  (Assumptions: estimate is based on exposure_hints
  (notional_usd, leverage, slippage_bps) provided at protect time.
  Actual outcomes may differ.)

The estimate is never invented — it is only shown if exposure_hints are present. receipts are always cited.

Example: verified receipt snippet

{
  "verified": true,
  "content_hash": "sha256:a1b2c3d4e5f6789abcdef...",
  "intent_hash": "sha256:fedcba987654321...",
  "allow": false,
  "reason_codes": ["PERPS_MARKET_NOT_ALLOWED"],
  "chain_id": "solana",
  "intent_type": "perps_open"
}

Verify any receipt yourself:

atf receipts verify --receipt sha256:a1b2c3d4e5f6...

OpenClaw plugin option (fastest path)

Fastest path for OpenClaw agents to adopt ATF:

# 1. Install the plugin
openclaw plugins install @trucore/openclaw-atf
openclaw gateway restart

# 2. The agent can now call:
#    atf_discover       → learn what ATF does
#    atf_bootstrap_plan → get self-install steps
#    atf_bootstrap_execute_safe → run safe setup
#    atf_protect_intent → guard every DeFi action
#    atf_verify_receipt → prove decisions to humans
#    atf_report_savings → generate savings report

No custom coding required for drop-in protection.

Manual integration (without OpenClaw)

# Install ATF CLI
npm install -g @trucore/atf

# Self-install ATF
atf bootstrap --format json --recipe bootstrap_local
atf bootstrap --execute-safe --recipe bootstrap_local

# Protect an intent
echo '{"chain_id":"solana","intent_type":"swap","intent":{...}}' | atf bot protect --stdin

# Verify a receipt
atf receipts verify --receipt sha256:aabbcc...

# Generate savings report
atf report savings --receipts-dir ./atf_receipts --format json

Full docs: docs/runbooks/agent-adoption-atf.md

Jupiter Endpoint Configuration

ATF swap commands use the canonical Jupiter v6 production endpoint by default:

https://quote-api.jup.ag/v6

Override via environment:

Or via ATF profile config: jupiter_quote_url / jupiter_swap_url.

Fallback: Direct CLI (if plugin install fails)

If openclaw plugins install @trucore/openclaw-atf is unavailable:

# Install ATF CLI directly
npm install -g @trucore/atf

# Bootstrap
atf bootstrap --recipe bootstrap_local --execute-safe

# Protect an intent
echo '{"chain_id":"solana","intent_type":"swap","intent":{...}}' | atf bot protect --stdin

# Verify receipt
atf receipts verify --receipt sha256:aabbcc...

# Report savings
atf report savings --receipts-dir ./atf_receipts --format json

The plugin is an optional convenience layer. All ATF security guarantees work identically via direct CLI.

Tests

cd packages/openclaw-atf
node --test tests/test_tools.mjs
node --test tests/test_plugin_package.mjs

All tests are offline. No network calls. No ATF CLI required.

License

MIT — TruCore AI