@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

Quick Start — Install, Enable, Verify, Disable

1. Install

openclaw plugins install @trucore/openclaw-atf

2. Enable (minimal config — zero keys required)

Add to your OpenClaw config:

{
  "plugins": {
    "trucore-atf": {}
  }
}

That's it. All defaults are safe and correct for most environments.

3. Restart and verify

openclaw gateway restart
openclaw tool call atf_integration_doctor

Healthy state checklist:

• status = "ok"
• plugin_loaded = true
• native_tools_available lists all 13 tools
• native_tools_missing is empty []
• config_validation.valid = true
• warnings is empty or contains only informational items

4. Disable (if needed)

Remove trucore-atf from your plugins config:

{
  "plugins": {}
}

Then: openclaw gateway restart. This has zero effect on ATF CLI/API.

See also: examples/ for copy-paste-safe config files.

What this plugin does

This plugin registers 13 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.

Diagnostic tools

atf_bot_preflight is a lightweight readiness check designed for bot startup: it probes CLI/API availability, validates plugin config, and returns a single ready: true/false signal with remediation steps if needed.

atf_tx_explain maps ATF deny reason codes to structured human-readable explanations with category, description, and remediation guidance. It works offline and requires no backend — it reads from the built-in reason code catalog. Pass either a reasonCodes array or a full receipt object.

Enable tools

The simplest config enables all plugin tools with safe defaults:

{
  "plugins": {
    "trucore-atf": {}
  }
}

To explicitly allowlist individual tools and customize settings:

{
  "plugins": {
    "trucore-atf": {
      "prefer": "cli",
      "receiptsDir": "./atf_receipts"
    }
  },
  "tools": {
    "allowlist": [
      "atf_health",
      "atf_protect_intent",
      "atf_verify_receipt",
      "atf_integration_doctor"
    ]
  }
}

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

Config reference

Integration Doctor

Validate the full integration in one step:

openclaw tool call atf_integration_doctor

Returns a structured readiness report including:

• Plugin loading status
• CLI / API availability
• Backend preference vs effective backend (with fallback details)
• Registered tool inventory
• Configuration warnings and remediation steps

Status values: ok, degraded, misconfigured, unavailable.

See the operator runbook for expected outputs and troubleshooting.

Backend preference

The plugin supports two backends:

Set prefer in your plugin config. If the preferred backend is unavailable, the plugin falls back to the other automatically. Both atf_health and atf_integration_doctor report what was preferred, what was chosen, and why fallback occurred.

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
node --test tests/test_integration_hardening.mjs
node --test tests/test_doctor.mjs
node --test tests/test_config_ux.mjs
node --test tests/test_activate_validation.mjs
node --test tests/test_native_tools.mjs

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

Plugin exports

The plugin provides the following entry-points:

The canonical plugin ID is trucore-atf everywhere: manifest, package.json, config, docs.

Activation-time config validation

When the plugin activates, it validates the config and surfaces any issues as console.warn messages. Invalid config never blocks activation. The plugin always loads and remains operational.

• Valid config — activates silently, no warnings.
• Config with warnings — activates normally; warnings logged with [trucore-atf] prefix.
• Config with errors / unsupported keys — activates normally; errors and unsupported keys logged clearly.
• Warnings include remediation guidance and recommend running atf_integration_doctor for full details.

This gives operators immediate feedback at startup without breaking the integration.

Graceful degradation

• If ATF CLI is not installed, tools return clear error messages — never crash.
• If ATF API is unreachable, tools degrade to CLI fallback or return errors.
• If the plugin receives an invalid api object, it logs a warning and skips registration.
• If activate() receives invalid or missing context, it degrades silently.
• All tool handlers are wrapped in a safe-handler that catches runtime errors.
• Plugin failure never breaks the OpenClaw gateway or other plugins.

License

MIT — TruCore AI