chain-signer

# chain-signer

<!-- mcp-name: io.github.Kevthetech143/chain-signer -->

![PyPI](https://img.shields.io/pypi/v/chain-signer) ![Python](https://img.shields.io/pypi/pyversions/chain-signer) ![License](https://img.shields.io/pypi/l/chain-signer) ![Release](https://github.com/Kevthetech143/chain-signer/actions/workflows/release.yml/badge.svg)


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.

```python
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
```
```python
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)
```python
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.
```python
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:
```python
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.

## 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):
```python
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`](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.
- `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.

## Handling the key (read this)
`w.private_key` is the keys to the wallet. Treat it like a password:
- NEVER log it, print it in production, or write it into notes/memory/chat. Anyone who has it controls the funds.
- For a burner holding a few dollars this is low-stakes by design — but the rule still holds.
- To reuse a wallet later, store the key in a secret manager / env var, then `restore(key)`.
- Better: `export_encrypted(w, password)` gives a password-protected keystore dict to store at rest; `load_encrypted(keystore, password)` brings the wallet back. Never store the raw key if you can store the keystore.

## Signing idiom (note for web3.py users)
The wallet does not expose `sign_transaction` / `sign_message` methods. Signing is done by
function helpers you pass the wallet to — e.g. `send_ether(w, to, amount)` signs and broadcasts,
and `sign_message(w, "text")` returns an EIP-191 signature for auth / sign-in flows
(recoverable via eth_account `Account.recover_message`).

## CLI on PATH
`pip install` may warn that the `chain-signer` script dir isn't on your PATH. T