OpenClaw Audit Skill (FORAY Protocol)

Name: Skill
Rating: 76
Author: DUNIN7

Version: 1.0.0
Author: Marvin Percival (marvinp@dunin7.com)
Repository: github.com/DUNIN7/openclaw-audit-skill
License: BSL-1.1

Overview

This skill enables OpenClaw agents to create tamper-evident audit trails for trading activity using the FORAY Protocol and Kaspa blockchain. Every trade executed by the agent is structured, hashed, and anchored — providing cryptographic proof of what happened, when, and under whose authority.

Why this matters: You're giving an AI agent control over real money. FORAY ensures there's an immutable record of every decision, every execution, and every outcome — for accountability, compliance, tax reporting, and dispute resolution.

Capabilities

Command	Description
`audit this trade`	Generate FORAY JSON for the most recent trade
`audit my last N trades`	Batch audit recent trading activity
`anchor to kaspa`	Commit audit trail to Kaspa blockchain
`show audit history`	Display anchored transactions
`verify trade [tx_id]`	Verify a trade against its blockchain anchor
`export audit report`	Generate PDF/JSON audit report for tax/compliance

Natural Language Commands

Single Trade Audit

code

"Audit my last trade"
"Create an audit trail for that BTC short"
"Generate FORAY record for my Polymarket position"
"Audit the ETH trade I just made on Hyperliquid"

Batch Audit

code

"Audit all my trades from today"
"Create audit trail for my last 10 trades"
"Audit everything since Monday"
"Generate FORAY records for all my Polymarket activity this week"

Blockchain Anchoring

code

"Anchor my audit trail to Kaspa"
"Commit today's trades to blockchain"
"Anchor and verify my trading history"
"Send audit hash to Kaspa testnet"

Verification & Reporting

code

"Verify my BTC trade from yesterday"
"Show me proof that trade was recorded"
"Export my Q1 trading audit for taxes"
"Generate compliance report for my Hyperliquid activity"

How It Works

1. Trade Capture

When you execute a trade (or approve one), OpenClaw captures:

•Order details: Asset, direction, quantity, price, exchange
•Execution details: Fill price, slippage, fees, timestamp
•Authorization: Who approved (you or auto-trade rule)
•Context: Market conditions, rationale if provided

2. FORAY Structuring

The trade is decomposed into FORAY Protocol v4.1 components:

code

┌─────────────────────────────────────────────────────────────┐
│  ARRANGEMENT (ARR)                                          │
│  - Trading account agreement                                │
│  - Risk parameters you set                                  │
│  - Human-in-the-loop permissions                            │
└─────────────────────┬───────────────────────────────────────┘
                      │
                      ▼
┌─────────────────────────────────────────────────────────────┐
│  ACCRUAL (ACC)                                              │
│  - Entry price calculation                                  │
│  - Fee computation                                          │
│  - Slippage measurement                                     │
│  - PnL formula                                              │
└─────────────────────┬───────────────────────────────────────┘
                      │
                      ▼
┌─────────────────────────────────────────────────────────────┐
│  ANTICIPATION (ANT)                                         │
│  - Expected settlement                                      │
│  - Target price / stop loss                                 │
│  - Expected proceeds                                        │
└─────────────────────┬───────────────────────────────────────┘
                      │
                      ▼
┌─────────────────────────────────────────────────────────────┐
│  ACTION (ACT)                                               │
│  - Actual execution                                         │
│  - Fill confirmation                                        │
│  - Settlement status                                        │
└─────────────────────┬───────────────────────────────────────┘
                      │
                      ▼
┌─────────────────────────────────────────────────────────────┐
│  ATTESTATION (ATT)                                          │
│  - Exchange confirms execution                              │
│  - Blockchain confirms settlement                           │
│  - Agent attests decision rationale                         │
└─────────────────────────────────────────────────────────────┘

3. Merkle Root Generation

All components are hashed into a single Merkle root — a cryptographic fingerprint of the entire trade record.

4. Kaspa Anchoring

The Merkle root is embedded in a Kaspa transaction using OP_RETURN. This provides:

•Timestamp: Kaspa's ~1-second block time proves when the record existed
•Immutability: Cannot be altered after anchoring
•Verifiability: Anyone can verify the hash against the original data

Configuration

Required Environment Variables

bash

# Kaspa network (testnet-10 or mainnet)
KASPA_NETWORK=testnet-10

# Your Kaspa wallet address for anchoring
KASPA_WALLET_ADDRESS=kaspa:qr...

# Optional: FORAY API endpoint for advanced features
FORAY_API_ENDPOINT=https://foray.dunin7.com/api

Skill Settings

Add to your OpenClaw config:

yaml

skills:
  openclaw-audit:
    enabled: true
    auto_audit: true          # Automatically audit every trade
    auto_anchor: false        # Require manual anchor command
    anchor_batch_size: 10     # Batch trades before anchoring
    network: testnet-10       # Kaspa network
    include_rationale: true   # Include agent's decision reasoning
    privacy_level: medium     # low|medium|high|critical

Privacy Levels

Level	What's On-Chain	What's Off-Chain
low	Full transaction details	Nothing
medium	Hashed identifiers, amounts visible	Party names, rationale
high	Only Merkle root	All details
critical	Merkle root + decoy pools	All details + formula obfuscation

Example Output

Trade Input

code

"I just shorted 0.5 BTC at $97,250 on Hyperliquid with 5x leverage. 
Stop loss at $99,000, take profit at $92,000."

Generated FORAY JSON

json

{
  "transaction_id": "TRADE_2026_Q1_BTC_SHORT_001",
  "schema_version": "4.1",
  "timestamp": "2026-02-03T18:45:00Z",
  
  "foray_core": {
    "entity": "OpenClaw Agent (User: 0x7a3b...)",
    "entity_hash": "sha256:user_wallet_hash...",
    "transaction_type": "leveraged_short",
    "total_value": 48625.00,
    "currency": "USD",
    "status": "active",
    "compliance_flags": ["AGENT_EXECUTED", "HUMAN_APPROVED"]
  },
  
  "arrangements": [
    {
      "id": "ARR_HYPERLIQUID_MARGIN",
      "foray_core": {
        "type": "margin_trading_agreement",
        "effective_date": "2026-02-03T18:45:00Z",
        "parties": [
          { "role": "trader", "name": "User Wallet 0x7a3b...", "jurisdiction": "DEFI" },
          { "role": "exchange", "name": "Hyperliquid", "jurisdiction": "DEFI" }
        ],
        "description": "Leveraged perpetual futures position",
        "total_value": 48625.00,
        "currency": "USD",
        "terms": {
          "leverage": 5,
          "margin_required": 9725.00,
          "liquidation_price": 101850.00,
          "funding_rate_interval": "8h"
        },
        "dependencies": []
      }
    }
  ],
  
  "accruals": [
    {
      "id": "ACC_POSITION_VALUE",
      "foray_core": {
        "arrangement_refs": ["ARR_HYPERLIQUID_MARGIN"],
        "type": "position_valuation",
        "description": "Short position mark-to-market",
        "computation_method": "Calculated",
        "formula_id": "sha256:perpetual_pnl_formula...",
        "inputs": {
          "entry_price": 97250.00,
          "quantity": 0.5,
          "direction": "short",
          "leverage": 5
        },
        "output": 48625.00,
        "currency": "USD",
        "dependencies": ["ARR_HYPERLIQUID_MARGIN"]
      }
    },
    {
      "id": "ACC_TRADING_FEES",
      "foray_core": {
        "arrangement_refs": ["ARR_HYPERLIQUID_MARGIN"],
        "type": "fee_calculation",
        "description": "Taker fee on entry",
        "computation_method": "Calculated",
        "formula_id": "sha256:hyperliquid_fee_schedule...",
        "inputs": {
          "notional_value": 48625.00,
          "fee_rate": 0.00035
        },
        "output": 17.02,
        "currency": "USD",
        "dependencies": ["ARR_HYPERLIQUID_MARGIN"]
      }
    }
  ],
  
  "anticipations": [
    {
      "id": "ANT_STOP_LOSS",
      "foray_core": {
        "accrual_refs": ["ACC_POSITION_VALUE"],
        "arrangement_refs": ["ARR_HYPERLIQUID_MARGIN"],
        "type": "stop_loss_trigger",
        "description": "Automatic position close at stop loss",
        "expected_amount": -875.00,
        "currency": "USD",
        "expected_date": null,
        "condition": "BTC_PRICE >= 99000",
        "probability_factor": 0.35,
        "dependencies": ["ACC_POSITION_VALUE"]
      }
    },
    {
      "id": "ANT_TAKE_PROFIT",
      "foray_core": {
        "accrual_refs": ["ACC_POSITION_VALUE"],
        "arrangement_refs": ["ARR_HYPERLIQUID_MARGIN"],
        "type": "take_profit_trigger",
        "description": "Automatic position close at target",
        "expected_amount": 2625.00,
        "currency": "USD",
        "expected_date": null,
        "condition": "BTC_PRICE <= 92000",
        "probability_factor": 0.45,
        "dependencies": ["ACC_POSITION_VALUE"]
      }
    }
  ],
  
  "actions": [
    {
      "id": "ACT_POSITION_OPENED",
      "foray_core": {
        "anticipation_refs": [],
        "accrual_refs": ["ACC_POSITION_VALUE", "ACC_TRADING_FEES"],
        "arrangement_refs": ["ARR_HYPERLIQUID_MARGIN"],
        "type": "position_entry",
        "description": "Short position opened",
        "amount_settled": 9742.02,
        "currency": "USD",
        "settlement_date": "2026-02-03T18:45:02Z",
        "settlement_status": "completed",
        "payment_method": "crypto",
        "counterparty": "Hyperliquid Clearinghouse",
        "allocations": [
          {
            "ref": "ACC_POSITION_VALUE",
            "ref_type": "accrual",
            "amount": 9725.00,
            "currency": "USD",
            "allocation_type": "margin_deposit"
          },
          {
            "ref": "ACC_TRADING_FEES",
            "ref_type": "accrual",
            "amount": 17.02,
            "currency": "USD",
            "allocation_type": "fee_payment"
          }
        ],
        "dependencies": ["ACC_POSITION_VALUE", "ACC_TRADING_FEES"]
      }
    }
  ],
  
  "attestations": [
    {
      "id": "ATT_EXCHANGE_CONFIRMATION",
      "foray_core": {
        "attestor": "Hyperliquid",
        "attestor_hash": "sha256:hyperliquid_api_pubkey...",
        "attestor_type": "oracle",
        "attestor_credentials": ["DEX", "PERPETUALS", "API_SIGNED"],
        "subject_refs": ["ACT_POSITION_OPENED"],
        "attestation_type": "verification",
        "attestation_date": "2026-02-03T18:45:02Z",
        "outcome": "approved",
        "evidence_hash": "sha256:api_response_hash...",
        "evidence_location": "off-chain",
        "dependencies": []
      }
    },
    {
      "id": "ATT_AGENT_RATIONALE",
      "foray_core": {
        "attestor": "OpenClaw Agent",
        "attestor_hash": "sha256:agent_instance_id...",
        "attestor_type": "oracle",
        "attestor_credentials": ["AI_AGENT", "HUMAN_APPROVED"],
        "subject_refs": ["ARR_HYPERLIQUID_MARGIN", "ACT_POSITION_OPENED"],
        "attestation_type": "approval",
        "attestation_date": "2026-02-03T18:44:55Z",
        "outcome": "approved",
        "evidence_hash": "sha256:decision_rationale...",
        "evidence_location": "off-chain",
        "rationale": "Technicals show RSI overbought at 78, resistance at $98K. User macro view bearish. Risk/reward acceptable at 1:3.",
        "dependencies": []
      }
    }
  ],
  
  "merkle_root": "sha256:e5f6789012345678...",
  
  "blockchain_anchor": {
    "kaspa_tx_id": "pending",
    "block_height": null,
    "confirmation_time_ms": null,
    "anchored_at": null
  },
  
  "privacy_metadata": {
    "formulas_obfuscated": 1,
    "instance_pools": 0,
    "attack_complexity": "N/A"
  }
}

Anchor Command

code

"Anchor this trade to Kaspa"

Response:

code

✓ Trade anchored to Kaspa testnet-10
  Transaction: kaspa:qr7x8y9z...
  Block: 2,851,234
  Confirmation: 1.1 seconds
  Merkle Root: sha256:e5f6789012345678...
  
  Verify at: https://explorer.kaspa.org/txs/kaspa:qr7x8y9z...

Supported Platforms

Platform	Trade Types	Status
Hyperliquid	Perpetuals, Spot	✅ Full support
Polymarket	Prediction markets	✅ Full support
Jupiter	Solana swaps	✅ Full support
Raydium	Solana AMM	✅ Full support
Uniswap	ETH swaps	✅ Full support
Binance	CEX (via API)	⚠️ Requires API key
Coinbase	CEX (via API)	⚠️ Requires API key

Security Considerations

•Private keys never touch FORAY — Only transaction metadata is captured
•Wallet addresses are hashed — Privacy preserved unless you choose otherwise
•Rationale is optional — Agent reasoning can be excluded from audit
•Off-chain storage — Full details stored locally; only hash on-chain

Use Cases

Tax Reporting

code

"Export all my 2026 trades as FORAY JSON for my accountant"

Generates complete audit trail with cost basis, gains/losses, and timestamps.

Dispute Resolution

code

"Prove I had a stop loss set at $99K"

Shows the Anticipation component with condition, anchored before the loss occurred.

Compliance

code

"Generate audit report for regulatory review"

Full transaction history with attestations, suitable for regulatory examination.

Agent Accountability

code

"Show me why the agent made that trade"

Displays ATT_AGENT_RATIONALE with decision reasoning captured at execution time.

Installation

bash

# Clone the skill
git clone https://github.com/DUNIN7/openclaw-audit-skill.git ~/.openclaw/skills/openclaw-audit

# Or via OpenClaw CLI
openclaw skill install openclaw-audit

Dependencies

•OpenClaw v0.5.0+
•Node.js 18+ (for Kaspa SDK)
•Kaspa wallet with small KAS balance for anchoring (~0.01 KAS per anchor)

Support

•Documentation: https://foray.dunin7.com/docs
•GitHub Issues: https://github.com/DUNIN7/foray-kaspathon/issues
•Email: marvinp@dunin7.com

License

Business Source License 1.1 (BSL-1.1)