Architecture Decision Records

​

Context

1. Agent holds keys directly — Simple to implement but catastrophic if the agent is compromised. A single malicious skill or prompt injection can drain the wallet. There is no policy layer, no audit trail, and no approval step.
2. Hardware wallet with manual approval — Secure key isolation, but every transaction requires physical human interaction. This is incompatible with autonomous agent workflows where an agent may execute dozens of operations per hour.
3. Custodial API (third-party signing service) — Introduces counterparty risk, requires trusting an external entity with key material, and creates a single point of failure. Not viable for users who require self-custody.
4. Embedded TEE / secure enclave — Hardware-dependent, complex to deploy, and does not solve the policy or approval problem. The agent still needs to be told “yes” or “no” based on risk assessment.

• Multiple agent frameworks exist (OpenClaw, ElizaOS, MCP, custom bots) and the solution must be framework-agnostic.
• Skills are authored by third parties and cannot be fully trusted, even after code review.
• The attack surface includes prompt injection, supply chain compromise, malicious skill packages, and compromised RPC endpoints.
• Operations range from low-risk (balance queries) to high-risk (large transfers, unlimited approvals), requiring graduated security responses.
• Audit and compliance require a tamper-evident record of every signing operation.

​

Decision

• Construct declarative TxIntents (JSON objects describing desired operations)
• Communicate with Domain B exclusively via localhost HTTP API
• Read balance and transaction status data through Domain B

• No access to private keys or any key material
• No direct signing capability
• No direct blockchain RPC access
• No control over approval summaries shown to users
• No access to policy configuration or audit data

TxIntent --> PolicyEngine.evaluate() --> TxBuilder.build() --> PreflightService.simulate()
--> ApprovalService.requestApproval() --> WalletService.sign() --> Broadcast --> AuditTrace

• Keys are encrypted at rest (scrypt + AES-256-GCM) and decrypted only in memory for signing
• Policy engine evaluates every intent against configurable rules (value limits, contract allowlists, token allowlists)
• Preflight simulation detects anomalies before signing (balance changes, gas estimation, risk scoring)
• Approval tokens are single-use with TTL — no replay attacks
• Every critical step is written to an append-only audit trail with intentId correlation
• RPC access uses an allowlist — only approved endpoints are contacted

• --network none by default (no network access)
• --read-only root filesystem
• --cap-drop ALL (all Linux capabilities dropped)
• --security-opt no-new-privileges
• seccomp profile blocks clone, fork, exec (no process spawning)
• Resource limits: memory (128MB), CPU (0.5 cores), execution timeout

• Package level: Domain B packages are never imported by Domain A code. TypeScript project references enforce this at build time.
• Network level: Keys are never transmitted over HTTP, even on localhost. Only approval tokens and signed transaction hashes cross the API boundary.
• Process level: Sandbox containers have no access to the host filesystem where keys are stored.
• Runtime level: The API server validates all inputs against strict JSON schemas (additionalProperties: false) — no undocumented fields pass through.
• Test level: A dedicated security test suite (tests/security/) verifies domain boundaries, including tests for key exfiltration attempts, import graph integrity, and cross-domain access.

Domain A  --HTTP-->  Domain B (ISCL Core API)
Domain C  --HTTP-->  Domain B (ISCL Core API)

​

Consequences

​

Context

1. Incident forensics. When something goes wrong — a transaction is unexpectedly approved, a policy bypass is suspected, or funds move to an unrecognized address — operators need a complete, tamper-evident record of every step that led to the outcome, correlated by a single intent ID.
2. Compliance and accountability. Each audit event captures who requested what, which policy rules were applied, what risk score was calculated, whether the user approved, and when the signature was produced. This provides a provable chain of custody for every signing operation.
3. Rate limiting. The policy engine enforces per-wallet transaction rate limits (e.g., 10 transactions per hour). This requires durable, queryable state that survives process restarts — counting recent transactions by wallet address within a sliding time window.

• Append-only writes. Events are inserted but never updated or deleted. This prevents retroactive tampering with the audit record.
• Correlation queries. Retrieve all events for a given intent ID to reconstruct the full lifecycle of a single operation.
• Time-ordered retrieval. List recent events across all intents for dashboard display and monitoring.
• Rate limit queries. Count events per wallet within a time window, with efficient indexed lookups.
• Zero external dependencies. ISCL is a local runtime — it should not require a database server, connection pool, or network-accessible data store.
• Durability. Events must survive process crashes without data loss.
• Low latency. Audit logging is in the critical path of every transaction. Inserts must not block the pipeline.

1. PostgreSQL / MySQL — Full-featured relational databases. Satisfy all query requirements but introduce an external server dependency, connection management, schema migrations, and operational overhead (backups, user management, network configuration). Dramatically overweight for a local single-user runtime.
2. Flat-file JSON / JSONL — Simple append-only writing. No dependencies. But queries require scanning the entire file. Rate limit counts and correlation queries become O(n) as the log grows. No indexing, no transactions, no crash safety guarantees.
3. LevelDB / RocksDB — Embedded key-value stores. Low overhead, no external dependencies. But key-value semantics are awkward for the access patterns needed: range queries over timestamps, filtering by intent ID, counting by wallet address within a window. Would require building a secondary index layer on top.
4. In-memory only — Fastest option. But all audit data is lost on process restart. Unacceptable for forensics, compliance, and rate limiting that must survive restarts.

​

Decision

CREATE TABLE IF NOT EXISTS audit_events (
  id TEXT PRIMARY KEY,           -- UUID, generated per event
  timestamp INTEGER NOT NULL,    -- Unix milliseconds (Date.now())
  intent_id TEXT NOT NULL,       -- Correlation key linking all events for one intent
  event TEXT NOT NULL,           -- Event type (e.g. "policy_evaluated", "signed")
  data TEXT NOT NULL,            -- JSON payload with event-specific details
  created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

CREATE INDEX idx_intent_id ON audit_events(intent_id);
CREATE INDEX idx_event ON audit_events(event);
CREATE INDEX idx_timestamp ON audit_events(timestamp);

CREATE TABLE IF NOT EXISTS rate_limit_events (
  wallet_address TEXT NOT NULL,  -- Checksummed 0x address
  timestamp INTEGER NOT NULL     -- Unix milliseconds
);

CREATE INDEX idx_rate_wallet_ts ON rate_limit_events(wallet_address, timestamp);

• Concurrent reads during writes. The audit trail can be queried (e.g., for the web dashboard) while new events are being written without blocking.
• Better write performance. WAL batches writes to a separate log file before merging, reducing filesystem synchronization overhead.
• Crash safety. WAL ensures that committed transactions survive process crashes. An incomplete write during a crash is automatically rolled back on next open.

• Audit writes complete before the pipeline proceeds to the next step. There is no risk of “audit gap” where a signing event occurs but the corresponding audit record is lost due to an async write queue.
• The synchronous API simplifies error handling — a failed write throws immediately in the calling context.
• Latency of SQLite inserts (with WAL, on SSD) is typically 10-50 microseconds. This is negligible compared to RPC calls (~50-500ms) and blockchain confirmation (~2-12 seconds) in the same pipeline.

​

Consequences

​

Context

• No policy enforcement. Raw calldata is opaque — the policy engine cannot determine whether a transaction is a benign transfer or a malicious contract call without decoding every possible contract ABI.
• No simulation safety. The signing layer cannot meaningfully simulate or explain what a raw transaction does without understanding the target contract.
• Attack surface. A compromised agent can craft arbitrary calldata: call selfdestruct, interact with attacker-controlled contracts, set unlimited approvals, or perform reentrancy attacks. The signing layer has no semantic understanding to prevent this.
• No user-readable approval. The approval prompt would show raw hex calldata. Users cannot meaningfully approve or deny what they cannot understand.

• Library sharing violates trust boundaries. If the agent imports the signing SDK, it has access to the signing functions in its process memory. A compromised agent could call signing functions directly, bypassing policy and approval.
• No audit trail. Operations happen as function calls within the agent process. There is no natural interception point for logging, policy enforcement, or user confirmation.
• Framework coupling. Each agent framework (OpenClaw, ElizaOS, MCP, Telegram) has different language and runtime requirements. A single SDK would need to support all of them.

​

Decision

1. Agents express “what”, never “how”. A TxIntent says “transfer 100 USDC to 0xAlice” — it does not specify the ERC-20 transfer(address,uint256) function selector, ABI encoding, gas price, nonce, or chain-specific parameters. ISCL Core handles all of that.
2. Closed set of action types. TxIntent v1 defines exactly five action types: transfer, transfer_native, approve, swap_exact_in, and swap_exact_out. There is no generic “call” or “execute” action. This means every possible operation is known at compile time, can be validated against a strict schema, and can be explained in human-readable terms.
3. Strict schema validation. The schema uses additionalProperties: false at every level. No undocumented fields pass validation. This prevents agents from injecting unexpected data that might be interpreted by downstream components.
4. Canonical form for integrity. TxIntents are canonicalized using JCS (JSON Canonicalization Scheme) and hashed with keccak256. This produces a deterministic fingerprint used for approval token binding — the token is tied to a specific intent, preventing substitution attacks.

TxIntent v1
+-- version: "1"                    -- Schema version for forward compatibility
+-- id: UUID                        -- Idempotency key and audit correlation
+-- timestamp: number               -- Unix milliseconds, creation time
+-- chain
|   +-- type: "evm"                 -- Chain family (only EVM in v1)
|   +-- chainId: number             -- Target chain (1, 10, 42161, 8453)
|   +-- rpcHint?: string            -- Optional RPC URL hint (informational only)
+-- wallet
|   +-- address: "0x..."            -- Signing wallet
|   +-- profile?: string            -- Optional wallet profile name
+-- action: (one of)
|   +-- transfer                    -- ERC-20 transfer
|   +-- transfer_native             -- Native ETH transfer
|   +-- approve                     -- ERC-20 spending approval
|   +-- swap_exact_in               -- DEX swap with exact input
|   +-- swap_exact_out              -- DEX swap with exact output
+-- constraints
|   +-- maxGasWei: string           -- Hard cap on gas cost
|   +-- deadline: number            -- Unix timestamp expiry
|   +-- maxSlippageBps: number      -- Slippage tolerance (basis points)
+-- preferences?
|   +-- gasSpeed?: string           -- slow | normal | fast
|   +-- privateRelay?: boolean      -- Use private mempool
+-- metadata?
    +-- source?: string             -- Adapter name (for audit)
    +-- note?: string               -- Human-readable context

• Arbitrary contract calls. There is no call(address, calldata) action type. An agent cannot interact with contracts that are not ERC-20 tokens or known DEX routers.
• Self-destruct or delegate calls. No action type maps to these operations.
• Unlimited approvals by default. The approve action requires an explicit amount. The policy engine can enforce a cap via maxApprovalAmount.
• Calldata injection. ISCL Core constructs calldata from typed parameters. The agent never provides raw hex calldata.
• Gas manipulation. Gas parameters are set by ISCL Core based on RPC estimation, not by the agent. The maxGasWei constraint provides a ceiling but not a floor.

​

Consequences

​

Context

• Trigger transaction signing (with valid approval tokens)
• Read wallet balances and transaction history
• Approve or deny pending transactions
• Register and manage skills
• Access audit trail data

1. Remote exploitation. An attacker on the same network (or internet, if port-forwarded) could submit TxIntents directly, bypassing the agent entirely. While policy and approval would still apply, the attack surface expands dramatically.
2. Man-in-the-middle on approval tokens. Approval tokens are bearer tokens — anyone who holds one can use it to trigger signing. If tokens traverse a network, they can be intercepted.
3. Information disclosure. Balance queries, audit trail data, and pending approval details contain sensitive financial information.
4. Denial of service. An exposed API can be flooded with requests, overwhelming the single-process ISCL Core.

• Individual operators running an AI agent on their workstation or VPS
• Development teams running agents in containerized environments (Docker Compose)
• Small-team deployments where agent and signer co-locate by design

1. Network-accessible API with authentication — Expose on 0.0.0.0 with API key or JWT auth. This would allow remote agents to connect to a shared ISCL Core. However, it introduces authentication management, token rotation, TLS certificate management, and a larger attack surface. For v0.1, this complexity is not justified.
2. Unix domain socket — Bind to a filesystem socket instead of TCP. Provides strong access control via filesystem permissions. However, Docker networking does not natively support Unix sockets for inter-container communication, and the Fastify ecosystem has better-tested TCP support. Could be considered for v0.2.
3. mTLS with client certificates — Mutual TLS ensures both parties are authenticated. Strong security but very high operational overhead: certificate generation, distribution, rotation, and CA management. Completely disproportionate for a localhost service.

​

Decision

await server.listen({ host: "127.0.0.1", port: 3100 });

ports:
  - "127.0.0.1:3100:3100"

• Remote agents connecting to a central signer (e.g., multiple agents on different machines sharing one keystore)
• Mobile approval workflows (user approves from a phone, signer is on a server)
• Multi-machine Docker Swarm or Kubernetes deployments

​

Consequences