chain-signer

A security suite for AI agents — the seatbelt that catches the dangerous thing BEFORE it happens. Three guards, each callable on its own (and as MCP tools), pairing with any wallet or identity stack:

• preflight(tx) — decode an unsigned transaction and flag drains before signing (unlimited/large approval, approve-all, token & NFT transferFrom, proxy upgrade, on-chain permit, on-chain Permit2 approve/permit/transferFrom, approvals hidden in multicall incl. Uniswap router batches and Multicall3 aggregate/aggregate3/aggregate3Value (the batch helper on every EVM chain), approvals wrapped in ERC-4337/smart-account execute/executeBatch, Gnosis Safe multiSend/execTransaction and DSProxy execute, drains routed through the Uniswap Universal Router (Permit2 permit/transferFrom commands incl. sub-plans), 1inch AggregationRouter v5 swap() with redirected output or zero slippage, 0x ExchangeProxy transformERC20() with zero slippage, EIP-7702 account delegation, will-revert).
• inspect_typed_data(td) — catch permit-phishing in an EIP-712 message before the agent signs it (ERC-2612, Uniswap Permit2 incl. SignatureTransfer + witness variants, DAI-style permits) and Seaport orders that give assets away — zero consideration, proceeds routed to a third party, or hidden in a BulkOrder tree.
• check_action(action, policy) — enforce allow/forbid + value/recipient limits before the agent acts.

All three fail safe and are guards, not guarantees. Also bundled: a non-custodial multi-chain wallet (burner, balance, send, swap) — the agent holds its own key and signs locally. No MetaMask, no account, no custody.

from chain_signer import assert_safe
assert_safe(tx)   # raises if the tx is a drain/unlimited-approval/revert — review before signing

Install

pip install chain-signer
export ETHERSCAN_API_KEY=...   # for live balance reads + broadcast (Etherscan v2)

Bitcoin/Solana support is optional: pip install "chain-signer[all]".

Quickstart (10 seconds — offline, no key, no funds, no network)

pip install chain-signer

from chain_signer import preflight
spender = "0x" + "22" * 20
tx = {"to": "0x" + "33" * 20, "data": "0x095ea7b3" + spender[2:].rjust(64, "0") + "f" * 64, "value": 0}
print(preflight(tx))   # ok=False — flags unlimited_approval before you'd ever sign

That's the wedge: the drain gets flagged before you'd ever sign it — no key, no funds, no network.

Bundled wallet (optional — the guards pair with any wallet)

from chain_signer import burner, send_ether
from chain_signer.balance import get_balance

w = burner()                          # fresh throwaway wallet; the agent owns w.private_key
print(w.address, get_balance(w))      # live on-chain balance
send_ether(w, "0x...recipient", 0.001)  # auto nonce+gas, signed locally, broadcast

Full runnable demos are in the repo: examples/agent_safety_demo.py (all three guards stop three real attacks) and examples/quickstart.py (wallet) — clone to run them, or just import as above.

Safety preflight (the wedge)

Before an agent signs, hand the unsigned tx to preflight() — it decodes the calldata and returns the risks, or use assert_safe() to hard-stop on a HIGH flag. Offline, no network, never raises.

from chain_signer import preflight, assert_safe

# an unlimited-allowance approve() to a spender — the classic drain setup
tx = {"to": token, "data": "0x095ea7b3" + spender_padded + "f"*64, "value": 0}

report = preflight(tx)
# {'decoded': {...}, 'ok': False,
#  'risk_flags': [{'code': 'unlimited_approval', 'severity': 'HIGH',
#                  'detail': 'approve() grants an effectively-unlimited allowance ...'}]}

assert_safe(tx)          # raises ValueError on a HIGH flag; pass force=True to override
assert_safe(tx, sim=my_simulator)   # optional: also flag will-revert via your simulation hook

What it flags today: unlimited/large approval, increaseAllowance, setApprovalForAll, ERC-20 transferFrom + ERC-721/1155 safeTransferFrom (token & NFT drains), ERC-777 authorizeOperator/operatorSend (operator-grant + operator-pull drains), on-chain ERC-2612 and DAI-style permit, on-chain Permit2 approve/permit/transferFrom (single and batch — the dominant approval router: unlimited uint160 allowance + drain pull) plus Permit2 SignatureTransfer permit(Witness)TransferFrom (the one-shot signed-permit pull intent/filler protocols use), proxy upgradeTo/upgradeToAndCall, approvals hidden inside multicall (all router variants, nested) and Multicall3 aggregate/aggregate3/aggregate3Value (the canonical batch helper deployed at one address on every EVM chain), approvals wrapped in ERC-4337/smart-account execute/executeBatch, Gnosis Safe multiSend/execTransaction, or DSProxy execute(target,data)/execute(code,data) (decoded and recursed), drains routed through the Uniswap Universal Router (execute(commands,inputs) — Permit2 permit/transferFrom commands, batch and EXECUTE_SUB_PLAN), EIP-7702 account delegation (the "wallet upgrade" drainer), large native value, opaque calldata, malformed calls, and will-revert (with a sim hook). Honest limits (read these): this is STATIC analysis — it decodes calldata and matches known drain patterns. It is NOT a transaction simulator: it won't catch a novel/obfuscated drain it can't decode (those get a low-severity "unknown" flag, not a block), and simulation-based scanners go deeper there. Safety coverage is EVM-only today (no Solana/Bitcoin tx analysis). And it is not yet field-proven at scale. A first-line guard for known patterns — not a guarantee. Pair it with simulation + human review for high-value actions.

Signed-message inspector (the off-chain half)

A drain doesn't need a transaction. A dApp can ask the agent to sign an EIP-712 message — most dangerously a permit granting an unlimited token allowance, which preflight (a tx check) can't see. inspect_typed_data() catches it before the agent signs:

from chain_signer import inspect_typed_data
report = inspect_typed_data(typed_data)   # the EIP-712 object you're about to sign
# ok=False, risk_flags=[{'code': 'unlimited_permit_signature', 'severity': 'HIGH', ...}]

Covers all three major permit shapes: ERC-2612, Uniswap Permit2 (PermitSingle/PermitBatch, plus SignatureTransfer and the witness variants intent protocols use), and DAI-style (allowed: true), plus Seaport marketplace orders that hand assets over for nothing — zero consideration, proceeds routed to a third party while your asset leaves, or the same giveaway buried in a BulkOrder merkle tree. Offline, never raises.

Guarded signer (screen + sign in one call)

inspect_typed_data only protects when the agent remembers to call it first — sign_typed_data alone will happily sign a permit-phishing message. guarded_sign_typed_data() composes the two so signing is screened by default: it inspects, then refuses to sign a HIGH-risk drain.

from chain_signer import guarded_sign_typed_data, SignatureBlocked
sig = guarded_sign_typed_data(wallet, domain, types, message, "Permit")  # raises SignatureBlocked on a drain

On a clean message the signature is byte-identical to sign_typed_data; pass force=True to override.

Action-policy gate (inspect what the agent DOES)

Identity tells you who the agent is; it doesn't stop a bad action. check_action() enforces a policy on a proposed tool call before it runs — fail-safe (denies on unreadable input):

from chain_signer import check_action
policy = {"forbid_tools": ["bridge"], "max_value_wei": 10**18, "allow_recipients": [trusted_addr]}
r = check_action({"tool": "send", "args": {"to": addr, "value_wei": 5*10**18}}, policy)
# {'allowed': False, 'violations': [{'code': 'value_over_limit', ...}]}

All three guards are exposed as MCP tools (preflight, inspect_signature, check_action) — any agent runtime (Claude, Cursor, …) can call them directly, read-only, no key.

What's caught and what isn't — the honest threat-coverage map: docs/THREAT-COVERAGE.md.

What you get

• preflight(tx) / assert_safe(tx) — decode an unsigned tx and flag drain patterns before signing.
• inspect_typed_data(td) — flag permit-phishing in an EIP-712 message before the agent signs it.
• guarded_sign_typed_data(w, domain, types, message, primary_type) — screen then sign; refuses a drain.
• check_action(action, policy) — enforce allow/forbid + value/recipient limits before the agent acts.
• burner() — a fresh wallet for a one-off task; discard it when done.
• restore(key) — reload a wallet later from its exported private key (same key → same address).
• send_ether(w, to, amount) — send in ETH (not wei); nonce, gas, and broadcast handled for you.
• get_balance(w) — live balance from the chain (Etherscan v2 indexer, not a flaky public RPC).
• swap(...) — token swaps via 0x/Paraswap.
• Optional Solana + Bitcoin wallets via the [all] extra.

Non-custodial guarantee

The private key is generated/loaded locally, used only to sign, and never logged, returned, or stored by this library. You hold the key; we never touch your funds. That is the whole design.