Give an AI agent a Solana wallet it cannot drain

1Install

npm install coldstar-agent-signer @solana/web3.js tweetnacl

The package is MIT-licensed and published from github.com/ExpertVagabond/coldstar-agent-signer. It exports ColdstarWallet, the policy engine, and two commands: coldstar-sign-policy for the cold side and coldstar-signer-mcp for the agent side.

2Write the policy

A short JSON file. Rules are evaluated in this order, first match wins: blocklist, program allowlist, escalate threshold, per-transaction limit, recipient allowlist, daily cap, then auto-sign.

{
  "version": 1,
  "limits": { "perTxSol": 0.05, "dailySol": 0.2 },
  "allowPrograms": [
    "11111111111111111111111111111111",              // System program (SOL transfers)
    "ComputeBudget111111111111111111111111111111"   // most SDKs prepend a priority-fee instruction
  ],
  "allowRecipients": ["<address the agent may pay>"],
  "allowTokens": ["SOL"],
  "blockRecipients": ["<address that must never receive funds>"],
  "escalateAboveSol": 0.05
}

Keep the program allowlist short. A transfer through an allowlisted program such as Jupiter cannot be statically decoded to an amount, so allowlisting a program means trusting what it does internally. Simulation-based accounting is available opt-in (COLDSTAR_SIMULATE=1) and tightens this; it does not remove it.

3Have the root sign it (cold side)

This is the step that makes the model real. The root key signs the policy for one session public key, with an expiry. Run it on the offline machine; the output is plain JSON that crosses the gap by file or QR. The root is not needed again until the policy changes or the grant expires.

# on the air-gapped machine; root.json never leaves it
coldstar-sign-policy --root /media/cold/root.json --policy coldstar.policy.json \
  --session <session public key> --expires 7d > envelope.json

On the online host, the signer verifies the signature, that the envelope names the session key it holds, and the expiry, and refuses to start otherwise. Pin the root's public key too; without it, any key could have "signed" the policy.

Trying it on one laptop? Generate a throwaway root with solana-keygen new -o root.json, or run the Solana Agent Kit starter, whose npm run sign-policy does this with a clearly labelled demo root.

4Connect the agent

Add the server to your MCP client's config. The model gets five tools and never a key: status, verdict, sign, sign-and-send, and transfer SOL. Every outcome comes back as data (signed, escalated, rejected, send_failed) so the model reads the reason and stops instead of retrying.

{
  "mcpServers": {
    "coldstar": {
      "command": "npx",
      "args": ["-y", "-p", "coldstar-agent-signer", "coldstar-signer-mcp"],
      "env": {
        "RPC_URL": "https://api.devnet.solana.com",
        "COLDSTAR_POLICY": "/abs/path/envelope.json",
        "COLDSTAR_ROOT_PUBKEY": "<root public key>",
        "COLDSTAR_REQUIRE_ENVELOPE": "1",
        "COLDSTAR_SESSION_KEYFILE": "/abs/path/session.json",
        "COLDSTAR_LEDGER": "/abs/path/ledger.json"
      }
    }
  }
}

ColdstarWallet implements the kit's BaseWallet, so it replaces KeypairWallet and every plugin keeps working. Use the kit's signOnly mode and broadcast yourself; the kit's default send path signs each transaction twice, which a metering wallet correctly counts twice.

import { SolanaAgentKit } from "solana-agent-kit";
import TokenPlugin from "@solana-agent-kit/plugin-token";
import { ColdstarWallet, FileSpendLedger } from "coldstar-agent-signer";

const wallet = ColdstarWallet.fromEnvelope({
  envelope: JSON.parse(fs.readFileSync("envelope.json", "utf8")),
  expectedRoot: process.env.COLDSTAR_ROOT_PUBKEY,
  session,                                        // the Keypair the root authorised; disposable
  rpcUrl: RPC_URL,
  ledger: new FileSpendLedger(".coldstar-ledger.json"),  // daily cap survives restarts
  onEscalate: async (tx, reason) => null,        // hand tx to the cold device; return it signed, or null
});
const agent = new SolanaAgentKit(wallet, RPC_URL, { signOnly: true }).use(TokenPlugin);

5Watch the three outcomes

Ask the agent to send a small amount to the allowed address and it will. Ask it to send everything to the blocked address and watch the tool call fail closed. That second request is the whole reason this exists.

Frequently asked questions