OpenClaw Audit Skill (FORAY Protocol)

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

"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

"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

"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

"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:

┌─────────────────────────────────────────────────────────────┐
│  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

# 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:

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

"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

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

"Anchor this trade to Kaspa"

Response:

✓ 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

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

---

Use Cases

Tax Reporting

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

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

Dispute Resolution

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

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

Compliance

"Generate audit report for regulatory review"

Full transaction history with attestations, suitable for regulatory examination.

Agent Accountability

"Show me why the agent made that trade"

Displays ATT_AGENT_RATIONALE with decision reasoning captured at execution time.

---

Installation

# 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)

Copyright (c) 2026 Marvin Percival. All rights reserved.