Documentation

Get started with ClearSign

Install the CLI, build your first proposal, and add the SDK to your app in minutes.

Open sourceOWS-compatibleMCP-ready

Quick start

Install the ClearSign CLI with a single command.

Install

$ curl -fsSL https://app.clearsign.fun/setup.sh | bash

Once installed, generate a keypair and create your first proposal:

First proposal

$ clearsign keygen# → generates signer keypair at ~/.clearsign/keys/$ clearsign propose \ --title "Send 500 USDC to alice.sol" \ --asset USDC \ --amount 500 \ --to alice.sol \ --ttl 30m# → writes proposal.json with SHA-256 hash + expiry$ clearsign review ./proposal.json# → displays human-readable summary for inspection$ clearsign sign ./proposal.json# → signs the hash, writes signature to proposal.signed.json

SHA-256 locked — the hash is computed from a canonical serialization of the proposal object. Signing only succeeds if the hash matches the reviewed artifact.

CLI reference

The CLI is the primary operator interface. Every command operates locally — no keys ever leave the machine.

clearsign keygen

Generate a new ECDSA P-256 keypair. The private key is written to ~/.clearsign/keys/ and never transmitted.

clearsign propose

Build a new proposal JSON with a deterministic SHA-256 hash and explicit expiry.

--title: Human-readable description of the intent
--asset: Token symbol (USDC, SOL, …)
--amount: Quantity to transfer
--to: Recipient address or .sol name
--ttl: Time-to-live, e.g. 30m, 2h
--signers: Comma-separated public keys for multisig
--threshold: Minimum signatures required (multisig)

clearsign review

Print a human-readable summary of a proposal file and verify the hash matches the contents.

<file>: Path to proposal.json

clearsign sign

Sign the proposal hash with the local private key and append the signature to the output file.

<file>: Path to proposal.json
--key: Path to key (default: ~/.clearsign/keys/default)
--out: Output path (default: proposal.signed.json)

clearsign gate

Run all enforcement checks: hash integrity, TTL, anomaly detection, address allowlist. Exits non-zero if any check fails.

<file>: Path to proposal.signed.json
--policy: Path to policy config (optional)

SDK

Install the package and embed the same approval model inside treasury apps, operator dashboards, or execution services.

Install

$ npm install clearsign# or: bun add clearsign

buildProposal

Construct a canonical, hash-locked proposal object.

TypeScript

import { buildProposal } from "clearsign";

const proposal = await buildProposal({
  title: "Monthly Treasury Rebalance",
  description: "Move 150k USDC to strategy vault",
  asset: "USDC",
  amount: 150_000,
  to: "vault.sol",
  ttlSeconds: 1800,           // 30 minutes
  signers: ["alice.sol"],     // public keys
});

// proposal.hash — SHA-256 of canonical JSON
// proposal.expiresAt — ISO timestamp
// proposal.json — serialized artifact

ExecutionGate

Run all enforcement checks before executing a signed proposal.

TypeScript

import { ExecutionGate } from "clearsign";

const gate = new ExecutionGate({ policy: "./policy.json" });

const result = await gate.check(signedProposal);
// result.ok        — true if all checks pass
// result.checks    — per-check breakdown
// result.errors    — array of failure reasons

if (!result.ok) throw new Error(result.errors.join(", "));
await execute(signedProposal);

Multisig

Coordinate approvals across multiple signers using MultiSigCoordinator. Each signer reviews and signs from their own machine. The coordinator collects signatures and checks the threshold before handing off to the gate.

TypeScript

import { buildProposal, MultiSigCoordinator, ExecutionGate } from "clearsign";

const proposal = await buildProposal({
  title: "Treasury rebalance",
  asset: "USDC",
  amount: 150_000,
  to: "vault.sol",
  ttlSeconds: 3600,
  signers: [alicePubkey, bobPubkey, carolPubkey],
  threshold: 2,               // 2-of-3 required
});

// --- on each signer's machine ---
await proposal.review();     // display + verify hash
const sig = await proposal.sign(privateKey);

// --- back on the coordinator ---
const coordinator = new MultiSigCoordinator(proposal);
coordinator.addSignature(aliceSig);
coordinator.addSignature(bobSig);

if (coordinator.thresholdMet()) {
  const gate = new ExecutionGate();
  const result = await gate.check(coordinator.toSigned());
  if (result.ok) await execute(coordinator.toSigned());
}

Private keys never move. The proposal JSON (with its hash) travels between signers — the private key stays on each signer's machine.

MCP & Skill

Connect ClearSign to agent systems via the Model Context Protocol server or the Claude skill. Requests from agents stay reviewable, time-boxed, and policy-gated.

MCP server

Shell

$ node mcp/clearsign-server/index.mjs

The MCP server exposes propose, review, and gate as tools any MCP-compatible agent can call. All tool calls produce human-readable proposals that must pass the execution gate before any on-chain action occurs.

Claude skill

Shell

# Point Claude Code at the skill definition$ cat skills/clearsign/SKILL.md

The skill definition tells the agent how to construct a proposal, when to route through ClearSign, and what the enforcement invariants are. Drop skills/clearsign/SKILL.md into your agent's skills directory to enable it.

Proposal schema

Every proposal is a deterministically serialized JSON object. The SHA-256 hash is computed over the canonical form (keys sorted, no whitespace).

JSON

{
  "version": "clearsign/v1",
  "title": "Monthly Treasury Rebalance",
  "description": "Move 150k USDC to strategy vault",
  "asset": "USDC",
  "amount": 150000,
  "to": "vault.sol",
  "signers": ["alice.sol", "bob.sol", "carol.sol"],
  "threshold": 2,
  "expires_at": "2026-05-05T12:00:00Z",
  "hash": "sha256:8f3c9a2b4d1ef7a03c...",
  "signatures": [
    { "signer": "alice.sol", "sig": "3045...", "ts": "2026-05-05T11:31:00Z" },
    { "signer": "bob.sol",   "sig": "3046...", "ts": "2026-05-05T11:32:00Z" }
  ]
}

versionstringSchema version — always clearsign/v1

titlestringHuman-readable intent summary

descriptionstringExtended description shown to signers

assetstringToken symbol

amountnumberTransfer quantity (base units)

tostringRecipient address or .sol name

signersstring[]Ordered list of authorized signer public keys

thresholdnumberMinimum signatures required for execution

expires_atISO 8601Hard expiry — gate rejects after this timestamp

hashsha256:hexSHA-256 of canonical proposal (excluding this field)

signaturesobject[]Collected signatures, each with signer, sig, and timestamp