@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.

New to the Protected Bot Execution Standard? Start with the Developer Adoption Guide for quickstarts, adapter chooser, and canonical field reference.

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 (~/.openclaw/openclaw.json by default, or $OPENCLAW_CONFIG if set):

{
  "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)

Set plugin entries to empty in ~/.openclaw/openclaw.json:

{
  "plugins": {}
}

Then: openclaw gateway restart. The install is preserved — re-enable at any time by adding "trucore-atf": {} back. 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": {
    "alsoAllow": [
      "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
node --test tests/test_entrypoint_regression.mjs
node --test tests/test_gateway_load_compat.mjs
node --test tests/test_schema_strict_walk.mjs
node --test tests/test_strict_gateway_validation.mjs
node --test tests/test_toolcard_integrity.mjs
node --test tests/test_pack_artifact.mjs
node --test tests/test_contracts.mjs
node --test tests/test_billing.mjs
node --test tests/test_billing_claim.mjs
node --test tests/test_adoption_advisor.mjs
node --test tests/test_perps_contract.mjs
node --test tests/test_plugin_stabilization.mjs
node --test tests/test_cjs_bridge_dispatch.mjs
node --test tests/test_openclaw_e2e_harness.mjs

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

Real E2E Smoke (opt-in)

OPENCLAW_E2E=1 node scripts/openclaw_e2e_smoke.mjs

Requires openclaw binary. Uses an isolated temp home by default. Skips safely when OpenClaw is unavailable. See docs/runbooks/openclaw-smoke-test.md.

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

Install Readiness Check

Before running the real E2E harness, use the readiness script for a deterministic diagnostic that works even when OpenClaw is NOT installed:

cd packages/openclaw-atf
node scripts/openclaw_readiness.mjs

What it does:

• Detects whether openclaw binary exists on PATH (or OPENCLAW_BIN)
• Shows version and compatibility status if present
• Lists all supported environment variables
• Prints the exact next command to run and the exact success marker
• Maps every failure class to operator remediation
• Generates a copy-paste-ready operator checklist

Deterministic operator sequence:

1. node scripts/openclaw_readiness.mjs → checklist and next steps
2. Install OpenClaw if absent → https://openclaw.dev
3. node scripts/openclaw_readiness.mjs → confirm Installed: YES
4. OPENCLAW_E2E=1 node scripts/openclaw_e2e_smoke.mjs → expect [e2e] RESULT: ALL CHECKS PASSED
5. node --test tests/*.mjs → all offline tests pass

Execution Contract

All success markers and failure codes are defined in scripts/openclaw_execution_contract.mjs (contract version 1.0.0). Both the readiness script and the E2E harness import from this single source of truth. Changes to markers or failure codes require a contract version bump.

Success markers (grep-friendly)

Failure codes

Quick validation block

# Step 1: readiness (always safe, always exit 0)
cd packages/openclaw-atf
node scripts/openclaw_readiness.mjs

# Step 2: E2E (requires openclaw binary)
OPENCLAW_E2E=1 node scripts/openclaw_e2e_smoke.mjs

# Expected success: "[e2e] RESULT: ALL CHECKS PASSED"
# Expected skip if no OpenClaw: "[e2e] SKIP: ..."
# On failure: check the failure code in output against table above

One-Command Real Validation (Real Runner)

The real-runner scaffold wraps readiness + E2E into a single deterministic command for operators and CI runners:

cd packages/openclaw-atf
OPENCLAW_E2E=1 node scripts/openclaw_real_runner.mjs

What it does

1. Runs readiness check (binary detection, version, compatibility)
2. If OpenClaw missing → exits 0 with contract-driven informational output
3. If OpenClaw present + OPENCLAW_E2E=1 → runs the full E2E harness
4. Prints a concise final summary block with:
   • Contract version
   • Binary/version status
   • Compatibility status
   • Resolved command forms
   • Result class (SKIPPED / PASSED / FAILED)
   • Observed success markers
5. Optionally writes a sanitized JSON artifact

Environment variables

Expected output

Binary missing (default CI):

Result class       : SKIPPED

Binary present and compatible:

Result class       : PASSED
Success markers    : e2e_pack_ok, e2e_install_ok, e2e_config_ok, ...

E2E failure:

Result class       : FAILED
Failure code       : <failure_code>

Optional artifact output

When OPENCLAW_E2E_ARTIFACT=1, the runner writes a sanitized JSON file:

{
  "timestamp": "2026-03-10T00:00:00.000Z",
  "contract_version": "1.0.0",
  "openclaw_detected": true,
  "openclaw_version": "0.3.0",
  "compatible": true,
  "resolved_command_forms": {
    "install": ["plugins", "install"],
    "restart": ["gateway", "restart"],
    "tool_call": ["tool", "call"]
  },
  "result_status": "passed",
  "failure_code": null,
  "success_markers_observed": ["e2e_pack_ok", "e2e_install_ok", "..."]
}

The artifact contains only non-sensitive metadata. No secrets, no raw home paths, no tokens.

Compatibility row capture template

After the first successful real validation, record the result:

Or generate a prefilled row from the artifact:

node scripts/openclaw_compat_row.mjs /tmp/openclaw-binary-present-proof.json

Binary-Present Proof Run

When OpenClaw is installed and you want to validate the full E2E path in one shot, use the binary-present proof checklist:

# Full sequence:
cd packages/openclaw-atf
openclaw --version                     # A. confirm binary
node scripts/openclaw_readiness.mjs    # B. readiness check
OPENCLAW_E2E=1 \
OPENCLAW_E2E_ARTIFACT=1 \
OPENCLAW_E2E_ARTIFACT_PATH=/tmp/openclaw-binary-present-proof.json \
  node scripts/openclaw_real_runner.mjs  # C. real-runner with artifact
cat /tmp/openclaw-binary-present-proof.json | python3 -m json.tool  # D. inspect
node scripts/openclaw_compat_row.mjs /tmp/openclaw-binary-present-proof.json  # E. row
node --test tests/*.mjs                # F. offline tests

Pass: Result class: PASSED and result_status: "passed" in artifact. Fail: Check failure_code — see failure codes table above. Skip: Binary not detected — install OpenClaw first.

Full step-by-step: docs/openclaw_binary_present_proof_checklist.md