veil-cli: A terminal wallet that decodes Ethereum transactions before you sign

Ethereum’s transaction system is powerful but opaque. When you click "confirm" in a wallet, you’re often signing raw calldata like 0xa9059cbb… without understanding its effects. This isn’t just a usability issue—it’s a security risk. The veil-cli project addresses this by forcing clarity before authorization, ensuring users see decoded functions, simulated balance changes, and risk assessments before their private keys are ever involved.

Why raw transaction data fails users

Most Ethereum wallets display transactions as generic "contract interactions" with gas estimates, leaving users in the dark about what they’re actually signing. A raw hex string like 0xa9059cbb000000000000000000000000... is meaningless to humans, yet it represents actions ranging from simple token transfers to complex DeFi operations. veil-cli’s core innovation is making this data intelligible by decoding it into human-readable function names and relevant details before any signing occurs.

The tool achieves this by resolving contract data from multiple sources in a specific order:

• Etherscan’s verified contracts: If the contract is published and you have an API key
• Sourcify’s decentralized repository: No API key required, but coverage varies
• 4byte.directory: A fallback option using function selector hashes, which covers most common operations

For example, running veil decode on a transaction hash or raw calldata provides immediate clarity:

veil decode 0xabc123... --chain mainnet

Risk assessment beyond basic validation

Decoding is just the first step. veil-cli goes further by running a multi-layered risk analysis on the destination contract. This includes:

• Proxy contract detection to identify upgradeable contracts
• Bytecode size checks for suspicious complexity
• EOA (Externally Owned Account) verification to distinguish between wallets and contracts
• Integration with the GoPlus Security API for additional checks like honeypot detection, blacklist flags, and high sell taxes

The veil risk command provides a quick health check on any address:

veil risk 0xdAC17F958D2ee523a2206206994597C13D831ec7

Perhaps most critically, veil-cli simulates transactions locally using Foundry’s Anvil tool. This reveals issues that standard RPC validation misses—like transactions that would revert on-chain but appear valid during pre-flight checks. By catching these errors before gas is spent, users avoid unnecessary costs and frustration.

Secure private key storage with zero new dependencies

A security tool that handles private keys must prioritize safe storage. veil-cli implements the Ethereum keystore v3 format, the same standard used by geth, MetaMask, and MyCrypto. This ensures compatibility with existing wallet ecosystems while maintaining robust encryption.

The keystore creation process works in three secure steps:

• A password-derived key is generated using scrypt with parameters N=131072
• The private key is encrypted with AES-128-CTR using the first 16 bytes of the derived key
• A MAC (Message Authentication Code) is computed over the last 16 bytes and ciphertext to detect incorrect passwords

All cryptographic operations use Node.js’s built-in node:crypto module, with the exception of keccak256 hashing borrowed from the viem library. This approach minimizes dependency bloat while ensuring security best practices.

Two implementation details stood out during development:

• The default maxmem setting of 32MB in Node.js wasn’t sufficient for the scrypt parameters, requiring an increase to 160MB
• Timing-safe comparisons (crypto.timingSafeEqual) are used for password verification to prevent potential timing attacks, even though this is an edge case for local CLI tools

Users can easily manage wallets with simple commands:

veil wallet create  # Generates a new encrypted wallet
veil wallet import  # Imports an existing private key
veil wallet list    # Displays all stored wallets

The full signing pipeline: clarity before authorization

veil-cli’s flagship feature is its transaction pipeline, which forces users to understand a transaction before signing it. The complete workflow follows this sequence:

1. Transaction construction (either via veil tx build or an external file)
2. Decoding of the transaction details
3. Risk assessment of the destination contract
4. Local simulation to preview balance changes
5. Summary presentation to the user
6. Final confirmation prompt
7. Private key unlock and broadcast

The summary screen provides all critical information in a digestible format:

┌ Transaction summary ─────────────────────────────────
 │ From 0xYourWallet
 │ To 0xUniswapRouter
 │ Value 0.5 ETH
 │ Method swapExactETHForTokens
 │ Risk ✔ LOW
 │ Gas ~142,381
 └──────────────────────────────────────────────────────
 ETH -0.500000
 PEPE +2,184,112.000000
 ? Sign and broadcast? › (y/N)

Crucially, the private key remains locked until the very last step. By the time the user enters their password, the transaction details have already been thoroughly vetted, making the actual signing a formality.

The tool’s design also emphasizes flexibility in transaction construction. Instead of requiring inline input, veil send accepts a transaction file (tx.json), enabling:

• Pre-review of transaction details
• Version control of transaction configurations
• Integration with external tools like Gnosis Safe exports or cast calldata outputs

Handling unverified contracts transparently

A significant challenge in Ethereum transaction security is unverified contracts. Many deployed contracts lack source code on Etherscan or entries in Sourcify, leaving users with no way to understand their functionality through standard decoding.

veil-cli takes an honest approach to this problem. While most tools either display nothing useful or pretend decoding succeeded, veil-cli presents the raw calldata with clear indicators that the contract couldn’t be decoded. This transparency empowers users to make informed decisions rather than relying on potentially misleading assumptions.

Limitations and future improvements

The current risk detection engine catches obvious red flags like honeypots, blacklisted addresses, and high sell taxes. However, it misses more sophisticated threats such as:

• Recently upgraded proxies pointing to malicious implementations
• Multisig wallets with altered signatory sets

Detecting these cases requires either deep event log analysis or off-chain data sources, which presents a technical challenge the team continues to explore.

The philosophy behind veil-cli

This project isn’t about making Ethereum transactions harder—it’s about making them smarter. The goal is to shift the point of understanding from after-signing to before-signing, ensuring users never commit to a transaction they don’t fully grasp. With veil-cli, by the time the password prompt appears, the transaction should already be boring in its predictability and safety.