Skip to main content

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 two core traits that define the parsing and conversion interface:

/// Trait for blockchain transactions that can be parsed from raw data
pub trait Transaction: Debug + Clone {
    /// Parse a transaction from a string representation (hex, base64, etc.)
    fn from_string(data: &str) -> Result<Self, TransactionParseError>
    where
        Self: Sized;

    /// Get the transaction type name (e.g., "Solana", "Ethereum", "Bitcoin")
    fn transaction_type(&self) -> String;
}

/// Trait for converting parsed transactions to VisualSign format
pub trait VisualSignConverter<T: Transaction> {
    fn to_visual_sign_payload(
        &self,
        transaction: T,
        options: VisualSignOptions,
    ) -> Result<SignablePayload, VisualSignError>;
}

Each chain module implements these traits:

  1. Transaction - Handles parsing raw transaction bytes into chain-specific structures
  2. VisualSignConverter - Transforms parsed transactions into the VisualSign JSON format

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 DataVisualSign FieldExample
Token amountsamount_v2ETH, SOL, USDC
Addressesaddress_v2Recipients, contracts
Methods/Instructionstext_v2 or preview_layoutFunction calls
Multiple operationslist_layoutBatch transactions
Gas/Feespreview_layoutExpandable fee details

Source Code​

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

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 Transaction and VisualSignConverter traits - 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​