@trucore/trucore-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/trucore-atf
openclaw gateway restart

Install from local .tgz artifact (RC / offline)

# Build the artifact (from the repo)
cd packages/openclaw-atf
npm pack
# Produces: trucore-trucore-atf-0.2.11.tgz

# Transfer to target machine, then install
openclaw plugins install ./trucore-trucore-atf-0.2.11.tgz
openclaw gateway restart

Quick Start — Install, Enable, Verify, Disable

1. Install

openclaw plugins install @trucore/trucore-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 17 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 17 optional agent tools into OpenClaw:

| Tool | Purpose | |---|---| | atf_health | Check ATF CLI/API availability and readiness | | atf_discover | Fetch and summarise the ATF manifest (capabilities, recipes, feature gates) | | atf_bootstrap_plan | Generate ATF self-install steps for a recipe (plan only, no side effects) | | atf_bootstrap_execute_safe | Run safe bootstrap steps locally (env setup + verify, no signing) | | atf_protect_intent | Submit a DeFi intent for policy evaluation — returns allow/deny + receipt | | atf_verify_receipt | Verify a receipt deterministically (proof for humans) | | atf_report_savings | Generate a receipt-backed "ATF saved you" report | | atf_integration_doctor | Run integration readiness check — reports plugin/backend/tool status | | atf_bot_preflight | Pre-session readiness check — returns go/no-go with backend + config diagnostics | | atf_tx_explain | Explain ATF deny decisions — maps reason codes to human-readable explanations | | atf_billing_info | Billing/pricing metadata for the advanced bot package | | atf_billing_claim | Verify on-chain payment and process billing claim | | atf_adoption_advisor | Deterministic adoption recommendation for bots | | atf_setup | Start zero-terminal device claim setup flow | | atf_claim_status | Check/resume pending device claim | | atf_logout | Remove locally stored credentials | | atf_whoami | Show current ATF identity and credential source |

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

| Field | Type | Default | Description | |---|---|---|---| | atfCli | string | "atf" | CLI command name or absolute path | | atfBaseUrl | string | — | Base URL for HTTP API mode (e.g. https://api.trucore.xyz) | | prefer | "cli" | "api" | "cli" | Whether to call ATF via CLI subprocess or HTTP API | | receiptsDir | string | — | Directory of ATF receipt JSON files (used by atf_report_savings) | | safety.allowExecuteSafe | boolean | true | Allow atf_bootstrap_execute_safe to run | | safety.allowNetwork | boolean | false | Allow atf_discover to fetch the manifest over the network | | safety.enableUapPermits | boolean | false | Enable UAP permit-protected execution for atf_protect_intent (opt-in) |

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:

| Backend | When to use | |---|---| | cli (default) | Local dev, offline, ATF CLI installed | | api | Hosted environments, shared infra, centrally deployed ATF API |

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/trucore-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:

| Variable | Purpose | | --- | --- | | ATF_JUPITER_BASE | Full override (takes priority over all other settings) | | ATF_JUPITER_API_KEY | API key for x-api-key header (never logged) | | ATF_JUPITER_PREPROD | Set to 1 for preprod endpoint (explicit opt-in only) |

Or via ATF profile config: jupiter_quote_url / jupiter_swap_url.

Fallback: Direct CLI (if plugin install fails)

If openclaw plugins install @trucore/trucore-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:

| Export | Type | Purpose | |---|---|---| | default | function(api) | Legacy single-function entry (calls register(api)) | | register(api) | function | OpenClaw lifecycle: register tools | | activate(ctx) | function | OpenClaw lifecycle: activate (runs non-blocking config validation) | | deactivate() | function | OpenClaw lifecycle: deactivate (no-op for stateless ATF) | | PLUGIN_ID | string | Canonical plugin identity: trucore-atf | | PLUGIN_VERSION | string | Current plugin version | | buildHumanSummary(report) | function | Human messaging helper for savings reports | | REASON_CODE_CATALOG | object | Frozen map of deny reason codes → {category, explanation, remediation} | | ATF_BILLING_MANIFEST | object | Machine-readable billing/pricing metadata | | evaluateAdoption | function | Adoption advisor evaluation function | | verifyBillingClaim | function | Billing claim verification function | | CLAIM_STATUS | object | Claim status enum | | CLAIM_DENY_CODES | object | Claim deny code catalog | | TREASURY_ADDRESS | string | Canonical treasury address | | USDC_MINT | string | Canonical Solana mainnet USDC mint address | | CONTRACT_FAMILIES | object | Universal contract family definitions | | TOOL_FAMILY_MAP | object | Tool → contract family mapping | | CANONICAL_TOOLS | array | Frozen list of all 17 tool names | | CANONICAL_TOOL_COUNT | number | Number of canonical tools (17) |

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)

| Marker | Phase | Meaning | |---|---|---| | OpenClaw installed : YES | readiness | Binary detected | | Compatible (>=0.1.0) : YES | readiness | Version meets minimum | | [e2e] SKIP: | e2e | Binary absent — informational skip | | [e2e] Packed: | e2e | Tarball packed | | [e2e] Plugin installed successfully. | e2e | Install OK | | [e2e] Config written to: | e2e | Config enable OK | | [e2e] Gateway restarted. | e2e | Restart OK | | : PASS | e2e | Tool call OK | | [e2e] RESULT: ALL CHECKS PASSED | e2e | Overall E2E pass | | [e2e] RESULT: SOME CHECKS FAILED | e2e | One or more steps failed |

Failure codes

| Code | Severity | Meaning | Operator action | |---|---|---|---| | binary_missing | skip | Binary not found | Install OpenClaw | | version_incompatible | warn | Version < 0.1.0 | Upgrade OpenClaw | | install_failed | hard | Install command failed | Check tarball / openclaw plugins install --help | | config_write_failed | hard | Config write failed | Check OPENCLAW_HOME permissions | | restart_failed | warn | Restart returned nonzero | Try openclaw server restart or restart manually | | restart_incompatible | warn | Restart not recognized | Try alternative restart commands | | tool_call_failed | hard | Tool call failed | Check tool registration / try alt syntax |

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

| Variable | Required | Description | |---|---|---| | OPENCLAW_E2E | Yes (for E2E) | Must be 1 to run E2E phase | | OPENCLAW_BIN | No | Path to openclaw binary (default: openclaw) | | OPENCLAW_HOME | No | Override home dir (default: temp dir) | | OPENCLAW_E2E_ARTIFACT | No | Set to 1 to write JSON artifact | | OPENCLAW_E2E_ARTIFACT_PATH | No | Custom artifact file path |

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:

| Field | Value | |---|---| | Date | | | OpenClaw version | | | Command forms: install | | | Command forms: restart | | | Command forms: tool call | | | Install path used | tarball / npm | | Result | passed / failed / skipped | | Notes | |

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