Skip to main content
All notable changes to the Clavion / ISCL project are documented here. The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

​
[Unreleased]

​
Planned

  • Rootless Podman support for the sandbox executor (@clavion/sandbox)
  • CI/CD pipeline via GitHub Actions
  • SDK package (@clavion/sdk) — currently a stub placeholder

​
[0.1.0] - 2025-02-10

Initial release of the ISCL (Independent Secure Crypto Layer) runtime. 15 packages across 3 trust domains, 639+ tests passing, full transaction pipeline verified end-to-end with Anvil fork.

​
Added

  • Fastify-based HTTP API server with 14 endpoints under /v1/
  • JSON Schema validation via AJV in strict mode (additionalProperties: false)
  • Structured logging with pino
  • Health endpoint (GET /v1/health) reporting version, uptime, and status
  • X-ISCL-Version response header on all API responses
  • Demo boot script for local development (demo-boot.ts)
  • TxIntent v1 schema supporting 5 action types: transfer, transfer_native, approve, swap_exact_in, swap_exact_out
  • Transaction builders for all 5 action types with per-action validation
  • JCS canonicalization + keccak256 hashing for intent integrity verification
  • Uniswap V3 swap routing with per-chain router addresses
  • 1inch DEX Aggregator integration (optional, enabled via ONEINCH_API_KEY):
    • 1inch Swap API v6 for optimized multi-DEX routing
    • Automatic silent fallback to Uniswap V3 on 1inch failure
    • swap_exact_out always routed through Uniswap V3 (1inch API v6 limitation)
    • Router address validation per chain before API calls
    • Slippage conversion from basis points to percentage for 1inch API
  • Transaction broadcast with receipt tracking via GET /v1/tx/:hash
  • Async buildFromIntent() supporting both Uniswap and 1inch builders
  • Shared TypeScript interfaces for TxIntent, TxPlan, PolicyDecision, ApprovalToken, SkillManifest, AuditEvent, and RPC types
  • JSON Schema definitions for all API request/response payloads
  • TxIntent schema with $defs/$ref for composable action validation
  • AES-256-GCM encrypted keystore with scrypt key derivation
  • WalletService for transaction signing (viem-based)
  • BIP-39 mnemonic import with configurable account and address indices
  • Random key generation
PolicyEngine with 8 configurable evaluation rules:
  1. Allowed chains whitelist
  2. Allowed tokens whitelist
  3. Allowed contracts whitelist
  4. Maximum transaction value threshold
  5. Approval-required-above value threshold
  6. Recipient allowlist/denylist
  7. Risk score ceiling
  8. Rate limiting (sliding window, configurable maxTxPerHour)
Policy configuration validation with sensible defaults.
  • eth_call simulation against live or forked RPC
  • Gas estimation for built transactions
  • Balance diff tracking (before/after simulation)
  • Token allowance change detection
  • Risk scoring algorithm with 7 weighted factors (0—100 scale)
  • Chain-scoped RPC override support for multi-chain simulation
Three approval modes controlled by ISCL_APPROVAL_MODE env var:
ModeDescription
cliReadline-based terminal approval
webBrowser-based approval dashboard
autoAutomatic approval (testing/demos only)
Additional features:
  • promptFn option override for programmatic control in tests
  • Approval tokens: single-use, TTL-bound (300 seconds), intent-bound
  • PendingApprovalStore: in-memory store with deferred Promises and TTL cleanup
  • Web approval UI (GET /approval-ui): dark theme, zero external dependencies, 1-second pending poll, 5-second history poll, risk color coding
  • Approval API: GET /v1/approvals/pending, POST /v1/approvals/:id/decide, GET /v1/approvals/history
  • Append-only SQLite audit log with WAL journal mode
  • 14 event types with intentId correlation across the full pipeline
  • Rate limit tracking in a dedicated table
  • Queryable recent events via getRecentEvents(limit) (API and direct access)
  • SkillManifest v1 with ECDSA signing (JCS + keccak256)
  • 6-step registration pipeline: schema validation, signature verification, hash verification, static code scan, duplicate check, insert
  • Static scanner with 5 pattern rules: eval, child_process, network access, filesystem writes, obfuscation detection
  • CRUD API: POST /v1/skills/register, GET /v1/skills, GET /v1/skills/:name, DELETE /v1/skills/:name
  • Docker-based container isolation runner
  • API-only communication with ISCL Core (no key access, no unrestricted network)
  • Domain C trust boundary enforcement
4 supported chains:
ChainChain ID
Ethereum1
Optimism10
Arbitrum42161
Base8453
  • RpcRouter implementing RpcClient interface with per-chain dispatch
  • ISCL_RPC_URL_{chainId} env vars with BASE_RPC_URL legacy fallback
  • Chain-scoped balance queries via GET /v1/balance/:token/:account?chainId=N
  • Single-URL backward compatibility (plain ViemRpcClient when one URL provided)
4 key management commands:
clavion-cli key import             # Import private key from stdin
clavion-cli key import-mnemonic    # Import from BIP-39 mnemonic via stdin
clavion-cli key generate           # Generate a new random keypair
clavion-cli key list               # List all keystore addresses
Options: --keystore-path, --account-index, --address-index
  • Thin skill wrappers for OpenClaw execution backend
  • ISCLClient for HTTP communication with ISCL Core API
  • Skill types: clavion-swap, clavion-transfer, and others
  • Model Context Protocol server for AI-native tool integration
  • Compatible with Claude Desktop, Cursor, and other MCP-enabled IDEs
  • Tool definitions for transfer, swap, balance, and approval operations
  • ElizaOS (ai16z) plugin with 5 actions
  • Service layer wrapping ISCLClient for ElizaOS runtime
  • moduleResolution: "Bundler" compatibility for @elizaos/core
  • grammY-based Telegram bot with same-chat agent and approval flow
  • 7 commands: /transfer, /send, /swap, /approve, /balance, /status, /help
  • InlineKeyboard approval with callback query handling
  • ActiveTransactionStore for tracking in-flight approvals
  • Chat authorization via ISCL_TELEGRAM_ALLOWED_CHATS env var
  • Same-sender verification for approval callbacks
  • HTML parse mode for Ethereum address formatting
  • Multi-stage Dockerfile.core with non-root iscl user
  • Docker Compose with 3-service stack: Anvil, ISCL Core, OpenClaw
  • demo profile for full integration demonstration
  • 639+ unit and integration tests via vitest
  • 6 end-to-end tests with Anvil Base fork (tokens actually move on-chain)
  • 8 sandbox security tests requiring Docker
  • Security test suite verifying all 3 trust domain boundaries
  • Full pipeline verified: OpenClaw skill -> ISCL API -> policy -> preflight -> approval -> sign -> broadcast -> Anvil receipt
  • Test fixture infrastructure in tools/fixtures/ with hash generation
  • One valid fixture per action type plus invalid and edge-case variants

​
Security

The security architecture is a fundamental design constraint, not a feature that can be relaxed. All 6 invariants are enforced by both code structure and automated tests.
Three trust domain architecture enforced across all packages:

Domain A (Untrusted)

Adapters and agent skills. No keys, no RPC, no signing.

Domain B (Trusted)

Core, signer, audit, policy, preflight, registry. Keys and blockchain access.

Domain C (Limited Trust)

Sandbox. No keys, API-only communication.
6 security invariants:
  1. Private keys never leave Domain B (verified by security tests)
  2. No signRaw or arbitrary calldata signing — all operations use TxIntent v1
  3. All signing requires both a PolicyDecision and a valid ApprovalToken
  4. Tampered package detection in the skill registry static scanner
  5. Approval tokens are cryptographically bound to specific intents
  6. Rate limiting prevents transaction flooding per wallet address
Domain boundary integrity tests in tests/security/ verify these invariants on every test run.