Chain Module Architecture

Each blockchain requires a specialized module to parse its unique transaction format into VisualSign JSON. This section explains the architecture and design patterns used across all chain modules.

Adding Support for a New Blockchain?

See our comprehensive Adding a New Chain guide for step-by-step instructions on integrating your blockchain into VisualSign.

Core Architecture

All chain modules implement a common trait that defines the parsing interface:

trait ChainParser {
    fn parse_transaction(&self, raw_tx: &[u8]) -> Result<VisualSignJSON, Error>;
    fn get_chain_type(&self) -> Chain;
    fn decode_with_abi(&self, tx: &[u8], abi: Option<&str>) -> Result<Fields, Error>;
}

Key Design Principles

1. Progressive Disclosure

Show the most important information first, with details available on demand through expandable sections.

2. Risk Highlighting

Critical information like warnings, first-time addresses, or large amounts should be prominently displayed.

3. Chain-Specific Context

Each chain has unique concepts that need appropriate visualization:

• Ethereum: Gas fees, contract interactions, token standards
• Solana: Instructions, programs, compute units
• Sui: Objects, Move modules, gas objects
• Tron: Energy, bandwidth, TRC standards

Implementation Pattern

Each chain module follows this general pattern:

1. Decode - Parse raw transaction bytes into chain-specific structures
2. Extract - Pull out key information (sender, recipient, amounts, etc.)
3. Enrich - Add context (resolve names, check contracts, calculate fees)
4. Transform - Convert to VisualSign field types
5. Organize - Structure fields for optimal user understanding

Supported Chains

• Ethereum - Account-based model with smart contracts
• Solana - High-performance chain with parallel processing
• Sui - Object-oriented blockchain with Move
• Tron - EVM-compatible with energy system

Field Type Mapping

Each chain's native data types map to VisualSign field types:

Chain Data	VisualSign Field	Example
Token amounts	amount_v2	ETH, SOL, USDC
Addresses	address_v2	Recipients, contracts
Methods/Instructions	text_v2 or preview_layout	Function calls
Multiple operations	list_layout	Batch transactions
Gas/Fees	preview_layout	Expandable fee details

Source Code

The full implementation of all chain modules can be found in the visualsign-parser repository:

• Parser Core
• Chain Modules
• Field Types
• Test Cases

Adding New Chains

To add support for a new blockchain:

1. Study the transaction format - Understand how transactions are encoded
2. Identify key information - What users need to see for this chain
3. Implement the ChainParser trait - Follow the pattern of existing modules
4. Map to field types - Use appropriate VisualSign fields for visualization
5. Add tests - Ensure parsing works with real transaction data

See the contribution guide for detailed instructions.

Best Practices

Performance

• Cache frequently accessed data (names, ABIs, token info)
• Avoid blocking operations in the parse path
• Use efficient decoding libraries

Accuracy

• Validate all decoded data
• Handle malformed transactions gracefully
• Provide clear error messages

Maintainability

• Follow existing patterns for consistency
• Document chain-specific quirks
• Keep modules isolated and testable

Next Steps

• Review individual chain documentation for specific details
• Explore the Field Types reference
• Check visualization patterns for UI guidance
• View the source code for implementation details