Skip to main content

Parser CLI Development

The parser_cli tool is essential for developing and testing VisualSign parsers. It allows you to quickly parse raw transaction data and see the resulting visual representation.

Installation​

# Install from the visualsign-parser repository
cd ~/projects/visualsign-parser
cargo build --release

Basic Usage​

parser_cli --chain <chain> -t <transaction_hex> --output <format>

Parameters​

  • --chain: Blockchain type (ethereum, solana, sui, bitcoin)
  • -t: Raw transaction data (hex encoded)
  • --output: Output format (human, json)
  • --condensed-only: Show only condensed view (what users see on hardware wallets)

Real-World Examples​

Ethereum: Complex Uniswap Transaction​

The following command parses a real Uniswap Universal Router transaction that includes multiple DeFi operations:

parser_cli --chain ethereum -t 0x02f904cf0181b78477359400847c17b3e383045307943fc91a3afd70395cd496c647d5a6cc9d4b2b7fad80b904a424856bc30000000000000000000000000000000000000000000000000000000000000040000000000000000000000000000000000000000000000000000000000000008000000000000000000000000000000000000000000000000000000000000000040a08060c00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000400000000000000000000000000000000000000000000000000000000000000800000000000000000000000000000000000000000000000000000000000000200000000000000000000000000000000000000000000000000000000000000032000000000000000000000000000000000000000000000000000000000000003a0000000000000000000000000000000000000000000000000000000000000016000000000000000000000072b658bd674f9c2b4954682f517c17d14476e417000000000000000000000000ffffffffffffffffffffffffffffffffffffffff000000000000000000000000000000000000000000000000000000006940571900000000000000000000000000000000000000000000000000000000000000000000000000000000000000003fc91a3afd70395cd496c647d5a6cc9d4b2b7fad000000000000000000000000000000000000000000000000000000006918d12100000000000000000000000000000000000000000000000000000000000000e000000000000000000000000000000000000000000000000000000000000000412eb0933411b0970637515316fb50511bea7908d3f85808074ceed3bf881562bc06da5178104470e54fb5be96075169b30799c30f30975317ae14113ffdb84bc81c000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000000000200000000000000000000000000000000000000000000000285aaa58c1a1a183d0000000000000000000000000000000000000000000000000009cf200e607a0800000000000000000000000000000000000000000000000000000000000000a00000000000000000000000000000000000000000000000000000000000000001000000000000000000000000000000000000000000000000000000000000000200000000000000000000000072b658bd674f9c2b4954682f517c17d14476e417000000000000000000000000c02aaa39b223fe8d0a0e5c4f27ead9083c756cc20000000000000000000000000000000000000000000000000000000000000060000000000000000000000000c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2000000000000000000000000000000fee13a103a10d593b9ae06b3e05f2e7e1c000000000000000000000000000000000000000000000000000000000000001900000000000000000000000000000000000000000000000000000000000000400000000000000000000000008419e7eda8577dfc49591a49cad965a0fc6716cf0000000000000000000000000000000000000000000000000009c8d8ef9ef49bc0 --output human

Output Breakdown​

┌─ Transaction: Ethereum Transaction
│  Version: 0
│  Type: EthereumTx
│
└─ Fields:
   ├─ Network: Ethereum Mainnet
   ├─ To: 0x3fC91A3afd70395Cd496C647d5a6CC9D4B2b7FAD
   ├─ Value: 0 ETH
   ├─ Gas Limit: 283399
   ├─ Gas Price: 2.081928163 gwei
   ├─ Max Priority Fee Per Gas: 2 gwei
   ├─ Nonce: 183
   └─ Universal Router
         Title: Uniswap Universal Router Execute
         Detail: 4 commands
         📖 Expanded View:
         ├─ Permit2 Permit
         │     Title: Permit2 Permit
         │     Detail: Permit 0x3fC91A3afd70395Cd496C647d5a6CC9D4B2b7FAD to spend Unlimited Amount of 0x72b658bd674f9c2b4954682f517c17d14476e417
         │     📖 Expanded View:
         │     ├─ Token: 0x72b658bd674f9c2b4954682f517c17d14476e417
         │     ├─ Amount: 1461501637330902918203684832716283019655932542975
         │     ├─ Spender: 0x3fc91a3afd70395cd496c647d5a6cc9d4b2b7fad
         │     ├─ Expires: 2025-12-15 18:44 UTC
         │     └─ Sig Deadline: 2025-11-15 19:14 UTC
         ├─ V2 Swap Exact In
         │     Title: V2 Swap Exact In
         │     Detail: Swap 46525180921656252477 0x72b658bd674f9c2b4954682f517c17d14476e417 for >=0.002761011377502728 WETH via V2 (1 hops)
         │     📖 Expanded View:
         │     ├─ Input Token: 0x72b658bd674f9c2b4954682f517c17d14476e417
         │     ├─ Input Amount: 46525180921656252477
         │     ├─ Output Token: WETH
         │     ├─ Minimum Output: >=0.002761011377502728
         │     └─ Hops: 1
         ├─ Pay Portion
         │     Title: Pay Portion
         │     Detail: Pay 0.2500% of WETH to 0x000000fee13a103A10D593b9AE06b3e05F2E7E1c
         │     📖 Expanded View:
         │     ├─ Token: WETH
         │     ├─ Percentage: 0.2500%
         │     └─ Recipient: 0x000000fee13a103a10d593b9ae06b3e05f2e7e1c
         └─ Unwrap WETH
               Title: Unwrap WETH
               Detail: Unwrap >=0.002754108849058971 WETH to ETH for 0x8419e7Eda8577Dfc49591a49CAd965a0Fc6716cF
               📖 Expanded View:
               ├─ Minimum Amount: >=0.002754108849058971 WETH
               └─ Recipient: 0x8419e7eda8577dfc49591a49cad965a0fc6716cf

This visualization shows how VisualSign transforms a complex 1236-character hex string into a clear, hierarchical representation that anyone can understand.

Hardware Wallet View​

Use --condensed-only to see what users see on hardware wallets with limited screen space:

parser_cli --chain ethereum -t <transaction_hex> --output human --condensed-only

This shows only the most essential information that fits on small screens.

Available Test Fixtures​

The parser includes real-world transaction examples from production networks:

Ethereum Fixtures​

Located in src/chain_parsers/visualsign-ethereum/tests/fixtures/:

  • legacy.input: Simple ETH transfer
  • 1559.input: Complex Uniswap V3 multicall transaction
  • v2swap.input: Uniswap V2 swap transaction

Solana Fixtures​

Located in src/chain_parsers/visualsign-solana/tests/fixtures/:

  • jupiter_swap/: Real mainnet Jupiter aggregator swap
    • WSOL → USELESS token swap
    • 25 accounts including Whirlpool DEX integration
    • Transaction signature: 441ttot8CzpgsiRHvAHnNTCBwbSnPuhuy43pCjzZU9BKwBuJeW8f4TMU7FYLeqBst6WJeMEHprdQxr4thxqZSxRs

Sui Fixtures​

Located in src/chain_parsers/visualsign-sui/src/presets/:

  • cetus/: Concentrated liquidity DEX operations

    • Swaps (A→B, B→A, with/without partner fees)
    • Liquidity provision at specific price ranges

  • momentum/: Liquidity protocol operations

    • Position management (open, close, add, remove)
    • Fee and reward collection

  • suilend/: Lending protocol operations

    • Borrow, deposit, repay operations
    • Collateral token management
    • Staking and unstaking

Development Workflow​

1. Testing New Parsers​

When developing a new parser or modifying existing ones:

# Test with a raw transaction
parser_cli --chain ethereum -t <your_tx_hex> --output json > result.json

# Compare with expected output
diff result.json expected.json

2. Debugging Complex Transactions​

For complex DeFi transactions with nested operations:

# Get full JSON output for analysis
parser_cli --chain ethereum -t <tx_hex> --output json | jq '.'

# Focus on specific fields
parser_cli --chain ethereum -t <tx_hex> --output json | jq '.Fields[-1]'

3. Validating Hardware Wallet Display​

Ensure your parser output works well on constrained devices:

# Check condensed view fits requirements
parser_cli --chain ethereum -t <tx_hex> --output human --condensed-only

# Verify character limits and formatting
parser_cli --chain ethereum -t <tx_hex> --output json | jq '.PreviewLayout.Condensed'

Output Formats​

Human Format​

Best for development and debugging. Shows hierarchical structure with indentation and Unicode box drawing characters.

JSON Format​

Machine-readable format following the VisualSign JSON schema. Use with jq for analysis:

# Extract all field titles
parser_cli --chain ethereum -t <tx> --output json | jq -r '.. | .Title? // empty'

# Find all addresses
parser_cli --chain ethereum -t <tx> --output json | jq -r '.. | .Address? // empty'

Best Practices​

  1. Always test with real transactions: Use mainnet transactions from block explorers
  2. Verify both views: Check both expanded and condensed layouts
  3. Test edge cases: Large numbers, special characters, long addresses
  4. Validate against hardware: Ensure condensed view fits actual device constraints
  5. Document complex logic: Add comments for protocol-specific parsing

Common Issues and Solutions​

Issue: Transaction parsing fails​

Solution: Verify the hex encoding and chain type match

Issue: Output too verbose for hardware wallet​

Solution: Adjust the condensed view to show only critical fields

Issue: Missing protocol details​

Solution: Add protocol-specific presets to decode contract calls

Next Steps​