Metadata-Version: 2.4
Name: chain-signer
Version: 0.5.31
Summary: Security suite for AI agents — catch the dangerous thing before it's signed. Preflight an unsigned EVM transaction for drains, inspect EIP-712 signatures for permit-phishing, and gate agent actions by policy. Pairs with any wallet or MCP stack; ships a non-custodial wallet too.
Project-URL: Homepage, https://github.com/Kevthetech143/chain-signer
Project-URL: Documentation, https://github.com/Kevthetech143/chain-signer#readme
Author: chain-signer
License: MIT
License-File: LICENSE
Keywords: agent-security,agent-tools,ai-agents,crypto,drain-protection,eip-712,ethereum,evm,mcp,mcp-server,non-custodial,permit-phishing,preflight,transaction-security,wallet,web3
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: eth-abi
Requires-Dist: eth-account
Requires-Dist: eth-utils
Requires-Dist: web3>=7
Provides-Extra: all
Requires-Dist: base58; extra == 'all'
Requires-Dist: bit; extra == 'all'
Requires-Dist: solders; extra == 'all'
Provides-Extra: bitcoin
Requires-Dist: bit; extra == 'bitcoin'
Provides-Extra: solana
Requires-Dist: base58; extra == 'solana'
Requires-Dist: solders; extra == 'solana'
Description-Content-Type: text/markdown

# 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. The library works
regardless; to use the CLI directly, add that dir to PATH or run `python -m chain_signer ...`.

## Tool surface (for any AI / MCP / CLI)
`chain_signer.mcp_server` exposes `list_tools()` and `call_tool(name, arguments)`. CLI:
```
python -m chain_signer list
python -m chain_signer call create_wallet '{"chain":"evm"}'
```

## Responsible use
General-purpose, non-custodial tooling. You are responsible for using it within the laws and
terms of service that apply to you. Not intended or marketed for any restricted or prohibited
trading in your jurisdiction.

## Notes
- Balances/broadcast use the Etherscan v2 indexer (authoritative), never a free public RPC.
- Low-level building blocks (`tx.send`, `call_contract`, explicit nonce/gas) remain available for advanced use.

## Pay an x402 API in one call
```python
from chain_signer import burner, sign_x402_payment
w = burner()
payload = sign_x402_payment(w, token=USDC, to=PAY_TO, value=1000, valid_before=EXPIRES, chain_id=8453)
# -> {"signature", "authorization"} ready for the x402 payment header. Signed locally, no prompt.
```
Builds + signs the EIP-3009 authorization x402 expects (the "exact" scheme). Your agent pays a
paid API by itself — no password prompt, no signup, no custody.

## Sign typed data (EIP-712) — for agent payments / x402
```python
from chain_signer import burner, sign_typed_data
w = burner()
sig = sign_typed_data(w, domain, types, message)  # EIP-712; for x402 / EIP-3009 authorizations
```
Your agent can authorize a payment by signing typed data locally — no password prompt, no signup.

## Run as an MCP server
chain-signer is also a Model Context Protocol (MCP) server, so MCP-aware agents can use it directly:
```
pip install chain-signer
chain-signer-mcp          # speaks MCP over stdio (JSON-RPC 2.0)
```
Exposes 9 tools. The three security guards (the wedge): `preflight`, `inspect_signature`,
`check_action`. Plus the non-custodial wallet: create_wallet, get_balance, send, call_contract, swap, bridge.

Wire it into any MCP client (Claude Desktop, Cursor, etc.) by adding it to the client's
`mcpServers` config:
```json
{
  "mcpServers": {
    "chain-signer": {
      "command": "chain-signer-mcp",
      "env": { "ETHERSCAN_API_KEY": "your-key-for-live-balance-and-broadcast" }
    }
  }
}
```
That's all — the agent can now screen every tx, signature, and action through the guards before it
acts, and (optionally) hold its own wallet to read balances, send, and swap as native tools.
(`ETHERSCAN_API_KEY` is optional; needed only for live balance reads and broadcasting.)
