@vurto/sign-tx
v0.2.0
Published
Vurto AnA local browser-signer CLI: opens a single-use page on 127.0.0.1 that lets you sign a prepared transaction with MetaMask/Rabby and returns the tx hash to stdout.
Maintainers
Readme
@vurto/sign-tx
Local browser-signer CLI for the Vurto AnA MCP hard-wallet flow.
Your AI agent never sees your private key. When an MCP tool prepares a transaction (supply, repay, withdraw, borrow, swap, zap, …), it returns the calldata plus a short summary. Pipe that into sign-tx, and this CLI spins up a single-use local page on 127.0.0.1 that connects to your MetaMask / Rabby / Ledger / Trezor and asks you to sign. The transaction hash is printed to stdout so the agent can pick it back up and continue the workflow.
The page works fully offline from Vurto's network — every asset is inlined, the Content-Security-Policy denies all external loads.
Install
npm install -g @vurto/sign-txYou can also run it ad hoc without installing:
npx @vurto/sign-tx --tx '<json>'Faster cold start (hosted bundle). The same signer is published as a single dependency-free file served from the AnA origin, so you can skip the npm dependency install.
prepare_signingreturns amethods.fastblock with the URL, asha256, and a ready-to-runshellsnippet that downloads to a temp file, verifies the hash, runs it, and cleans up. Use the npm install above when you want npm's independent provenance check or are on Windows.
Quick start
sign-tx --tx '{
"txData": {
"to": "0xA238Dd80C259a72e81d7e4664a9801593F98d1c5",
"data": "0x617ba037...",
"chainId": 8453,
"value": "0x0"
},
"summary": {
"action": "supply",
"humanDescription": "Supply 100 USDC on Base to Aave V3"
},
"walletAddress": "0xYourWalletHere",
"transactionId": 17
}'What happens:
sign-txbinds an HTTP server on127.0.0.1(free port chosen by the OS).- The system browser opens the signer page.
- You connect MetaMask / Rabby (the page validates wallet and chain).
- You inspect the decoded calldata, gas estimate, and destination contract.
- You click Sign (or Reject).
sign-txprints the result JSON to stdout and exits.
Result on stdout
{
"txHash": "0xabc...",
"from": "0xYour...",
"chainId": 8453,
"signedAt": "2026-05-27T12:34:56.000Z"
}Exit codes
| Code | Meaning | |------|--------------------------------------------| | 0 | Transaction signed and broadcast | | 1 | User rejected the request | | 2 | Timed out waiting for approval | | 3 | Validation error (bad flags or bad JSON) |
Flags
| Flag | Default | Description |
|-----------------------|-----------|-------------|
| --tx <json> | — | Inline JSON payload. Required unless you pipe via stdin. |
| --mode <browser\|key> | browser | Signing method (see below). |
| --rpc <url> | built-in | RPC endpoint for --mode key (per-chain default, or VURTO_RPC_<chainId>). |
| --port <n> | 0 | TCP port on 127.0.0.1. 0 = OS picks a free port. browser mode only. |
| --no-open | off | Do not auto-open the browser; just print the URL on stderr. browser mode only. |
| --timeout <seconds> | 180 | Approval timeout. After this, the CLI exits with code 2. browser mode only. |
| --report-to <url> | — | Optional HTTPS endpoint to POST the result to (e.g. an MCP webhook). |
| --help | — | Print help. |
| --version | — | Print version. |
You can also pipe the JSON instead of using --tx:
cat tx.json | sign-tx --no-openSigning methods
--mode browser (default). Opens the local page; you approve in your own wallet
(MetaMask / Rabby / Ledger / Trezor). No private key is ever handled by the CLI or the agent.
--mode key (headless). For runs without a browser/extension. The CLI prompts for a
private key in this terminal with echo off, signs and broadcasts locally via ethers, and
prints the result. The key is read by this process only — never from --tx/stdin, never sent
to any server, never written to disk, never logged. The key's address must match the build's
walletAddress or signing is refused. For automation/CI the key may instead be provided via
the VURTO_SIGN_PRIVATE_KEY env var (opt-in; same guarantees).
cat tx.json | sign-tx --mode key # prompts for the key in the terminalNever ask for, paste, or echo a private key into an agent chat — agent transcripts are persisted. Offer
--mode key; the user enters the key into the CLI, not into the chat.
RPC — always use the Vurto RPC for the chain. --mode key broadcasts via an RPC. Prefer the
load-balanced Vurto endpoint over a random public node by setting VURTO_RPC_<chainId> (or
--rpc <url>): https://rpc.vurto.cc/<network> — eth (1), optimism (10), bnb (56),
gnosis (100), polygon (137), sonic (146), base (8453), arbitrum (42161),
avalanche (43114). E.g. export VURTO_RPC_137="https://rpc.vurto.cc/polygon".
Multi-step flows (steps[])
A payload may carry an ordered steps array instead of a single txData — e.g. a debt swap
(approveDelegation → swapDebt) or collateral swap (aToken approve → swapAndDeposit).
One signer session walks every step: in browser mode the page shows "STEP n OF N", waits for
each tx to confirm onchain (the next step depends on it), then auto-advances with the wallet
still connected; in key mode the steps are signed sequentially with a confirmation wait
between. All tx hashes come back in a steps array on stdout.
{
"steps": [
{ "txData": { "to": "0x…", "data": "0xc04a8a10…", "chainId": 8453 }, "summary": { "humanDescription": "Approve credit delegation" } },
{ "txData": { "to": "0x…", "data": "0xb8bd1c6b…", "chainId": 8453 }, "summary": { "humanDescription": "Execute debt swap" } }
],
"summary": { "humanDescription": "Debt swap 50 USDC → EURC" },
"walletAddress": "0xYourWalletHere"
}EIP-712 signing (typedData)
A step may carry typedData instead of txData — an off-chain EIP-712 message (e.g. a CoW
Protocol order) instead of a transaction. There is no gas, no broadcast, and no transaction
hash for this step; the result is a signature instead of a txHash. A flow can mix both step
kinds — e.g. approve a token (txData), then sign an order (typedData) — in one session.
{
"steps": [
{ "txData": { "to": "0x…", "data": "0x095ea7b3…", "chainId": 8453 }, "summary": { "humanDescription": "Approve VaultRelayer" } },
{
"typedData": {
"domain": { "name": "Gnosis Protocol", "version": "v2", "chainId": 8453, "verifyingContract": "0x9008D19f58AAbD9eD0D60971565AA8510560ab41" },
"primaryType": "Order",
"types": { "Order": [{ "name": "sellToken", "type": "address" }, { "name": "buyAmount", "type": "uint256" }] },
"message": { "sellToken": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "buyAmount": "500000000000000" }
},
"summary": { "humanDescription": "Sign a CoW order" }
}
],
"summary": { "humanDescription": "Swap 1 USDC for WETH via CoW" },
"walletAddress": "0xYourWalletHere"
}Do not include an EIP712Domain entry in types — both signing paths derive it from domain
themselves (the browser page builds it for the raw eth_signTypedData_v4 call; --mode key
lets ethers derive it, which throws if one is already present).
Result on stdout for a signature step:
{ "signature": "0x…", "from": "0xYour...", "chainId": 8453, "signedAt": "2026-08-04T12:00:00.000Z" }A mixed multi-step flow's steps[] array carries txHash on transaction steps and signature
on signature steps, same as the top-level result reflects whichever the last step produced.
Safety mitigations
- 127.0.0.1 only. The HTTP server never binds to a public interface.
- Single-use session. A random session token is required for
POST /result. After a result is delivered, every route returns 410 Gone. - Strict CSP.
default-src 'none'; scripts and styles whitelisted by nonce; no external loads possible. No cross-origin frames, no form submissions. - Allow-list of destinations. Vurto Dual-Aave Adapter, Aave V3 Pool, ParaSwap Augustus V6.2 and TokenTransferProxy, and CoW Protocol's GPv2Settlement/VaultRelayer/ETH-flow contracts, across 9 chains. Unknown destinations show a red banner; you can still sign, but only after acknowledging it.
- Wallet match. The connected
eth_accounts[0]must equal the expectedwalletAddress. Sign is disabled otherwise. - Chain match. The wallet's current
chainIdmust equal the payload'schainId.sign-txtriggerswallet_switchEthereumChainautomatically; if you reject the switch, Sign stays disabled. - Unlimited-approval guard.
approve(spender, MAX_UINT256)(or any amount > 1B raw units of a known stablecoin) shows a red card with the spender address and forces you to tick "I understand I'm approving an unlimited amount of {TOKEN}" before Sign enables. - Whole-byte calldata.
datamust be even-length hex (complete bytes). An odd-length field means a nibble was dropped/added in transit; some wallets/RPCs silently left-pad a0(0xb8bd1c6b→0x0b8bd1c6b), shifting the selector and reverting on chain. It is rejected loudly at every layer (prepare_signing, CLIvalidatePayload, and the browsersendTx) instead of being signed. See ticket #178014218903628. - Decoded calldata first, raw second. The page leads with the human-readable summary and decoded named parameters. The raw
to/data/valuetriplet lives behind a collapsible.
Sigstore verification
Releases are signed with sigstore/cosign. To verify a published tarball:
# Download the tarball + bundle from the GitHub release page, then:
cosign verify-blob \
--bundle vurto-sign-tx-0.1.0.tgz.sigstore \
--certificate-identity-regexp 'https://github\.com/vurto-cc/vurto-a/\.github/workflows/.*' \
--certificate-oidc-issuer 'https://token.actions.githubusercontent.com' \
vurto-sign-tx-0.1.0.tgzA successful verify means the tarball was built by the canonical GitHub Actions workflow in vurto-cc/vurto-a — no human can sneak in a malicious build.
Dev usage from a checkout
If you're hacking on this CLI inside the vurto-a repo:
cd tools/sign-cli
npm install
node bin/sign-tx.js --help
node --test tests/A handy smoke test (will time out after 5s with exit code 2):
node bin/sign-tx.js --tx '{
"txData": {
"to": "0xA238Dd80C259a72e81d7e4664a9801593F98d1c5",
"data": "0x617ba037000000000000000000000000af88d065e77c8cc2239327c5edb3a432268e58310000000000000000000000000000000000000000000000000000000005f5e1000000000000000000000000001234567890123456789012345678901234567890000000000000000000000000000000000000000000000000000000000000000a",
"chainId": 42161,
"value": "0x0"
},
"summary": { "action": "supply", "humanDescription": "Supply 100 USDC on Arbitrum to Aave V3" },
"walletAddress": "0x1234567890123456789012345678901234567890",
"transactionId": 1
}' --no-open --timeout 5License
MIT.
