Creating Visualizations

This guide explains how to design effective transaction visualizations using VisualSign's field system.

Visualization Patterns

Pattern 1: Simple Transfer

For basic value transfers, focus on the key elements:

{
  "Version": "0",
  "Title": "Ethereum Transfer",
  "Fields": [
    {
      "Type": "amount_v2",
      "Label": "You're sending",
      "FallbackText": "0.005 ETH",
      "AmountV2": {
        "Amount": "0.005",
        "Abbreviation": "ETH"
      }
    },
    {
      "Type": "address_v2",
      "Label": "To",
      "FallbackText": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb7",
      "AddressV2": {
        "Address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb7"
      }
    }
  ]
}

Visual Result:

┌──────────────────────────────┐
│ Ethereum Transfer            │
├──────────────────────────────┤
│ You're sending               │
│ 0.005 ETH                    │
│                              │
│ To                           │
│ 0x742d...bEb7               │
└──────────────────────────────┘

Pattern 2: Transaction with Instructions

For transactions with multiple instructions (based on actual Solana fixture):

{
  "Version": "0",
  "Title": "Solana Transaction",
  "Fields": [
    {
      "Type": "text_v2",
      "FallbackText": "Solana",
      "Label": "Network",
      "TextV2": {
        "Text": "Solana"
      }
    },
    {
      "Type": "preview_layout",
      "FallbackText": "Program ID: JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4",
      "Label": "Instruction",
      "PreviewLayout": {
        "Title": {
          "Text": "Jupiter Swap"
        },
        "Subtitle": {
          "Text": "DeFi Protocol"
        },
        "Condensed": {
          "Fields": [
            {
              "Type": "text_v2",
              "FallbackText": "Jupiter Swap",
              "Label": "Instruction",
              "TextV2": {
                "Text": "Jupiter Swap"
              }
            }
          ]
        },
        "Expanded": {
          "Fields": [
            {
              "Type": "text_v2",
              "FallbackText": "JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4",
              "Label": "Program ID",
              "TextV2": {
                "Text": "JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4"
              }
            }
          ]
        }
      }
    }
  ]
}

Pattern 3: Smart Contract Interaction

For complex operations, use progressive disclosure with real field structure:

{
  "Version": "0",
  "Title": "Ethereum Transaction",
  "Fields": [
    {
      "Type": "text_v2",
      "Label": "Network",
      "FallbackText": "Ethereum Mainnet",
      "TextV2": {
        "Text": "Ethereum Mainnet"
      }
    },
    {
      "Type": "address_v2",
      "Label": "To",
      "FallbackText": "0x3fC91A3afd70395Cd496C647d5a6CC9D4B2b7FAD",
      "AddressV2": {
        "Address": "0x3fC91A3afd70395Cd496C647d5a6CC9D4B2b7FAD"
      }
    },
    {
      "Type": "amount_v2",
      "Label": "Value",
      "FallbackText": "0 ETH",
      "AmountV2": {
        "Amount": "0",
        "Abbreviation": "ETH"
      }
    },
    {
      "Type": "preview_layout",
      "Label": "Universal Router",
      "FallbackText": "Uniswap Universal Router Execute",
      "PreviewLayout": {
        "Title": {
          "Text": "Uniswap Universal Router Execute"
        },
        "Subtitle": {
          "Text": "4 commands"
        },
        "Condensed": {
          "Fields": [
            {
              "Type": "text_v2",
              "Label": "Commands",
              "FallbackText": "4 operations",
              "TextV2": {
                "Text": "Permit2, Swap, Pay, Unwrap"
              }
            }
          ]
        },
        "Expanded": {
          "Fields": [
            {
              "Type": "text_v2",
              "Label": "Command 1",
              "FallbackText": "Permit2 Permit",
              "TextV2": {
                "Text": "Permit2 Permit"
              }
            },
            {
              "Type": "text_v2",
              "Label": "Command 2",
              "FallbackText": "V2 Swap Exact In",
              "TextV2": {
                "Text": "V2 Swap Exact In"
              }
            },
            {
              "Type": "text_v2",
              "Label": "Command 3",
              "FallbackText": "Pay Portion",
              "TextV2": {
                "Text": "Pay Portion"
              }
            },
            {
              "Type": "text_v2",
              "Label": "Command 4",
              "FallbackText": "Unwrap WETH",
              "TextV2": {
                "Text": "Unwrap WETH"
              }
            }
          ]
        }
      }
    }
  ]
}

Design Guidelines

1. Information Hierarchy

Structure information by importance:

// Primary: What is happening?
Title: "Swap ETH for USDC"

// Secondary: Key parameters
Amount: "1.5 ETH → 2,850 USDC"

// Tertiary: Additional context
Slippage: "0.5%"
Route: "Uniswap V3"

2. Use Semantic Field Types

Choose the right field type for the data:

Data Type	Field Type	Example
Monetary values	`amount_v2`	Token amounts, fees
Addresses	`address_v2`	Recipients, contracts
Status/Labels	`text_v2`	Network, protocol names
Groups	`list_layout`	Related parameters
Complex data	`preview_layout`	Expandable details

3. Color and Visual Cues

Use visual indicators for important information:

{
  "Type": "address_v2",
  "Label": "Recipient",
  "FallbackText": "0x...",
  "AddressV2": {
    "Address": "0x...",
    "BadgeText": "⚠️ New Address"  // Warning indicator
  }
}

{
  "Type": "amount_v2",
  "Label": "Amount",
  "FallbackText": "10 ETH",
  "AmountV2": {
    "Amount": "10",  // Large amount - render prominently
    "Abbreviation": "ETH"
  }
}

Chain-Specific Visualizations

Ethereum: Gas Optimization

Show gas costs clearly:

{
  "Type": "preview_layout",
  "Label": "Network Fee",
  "PreviewLayout": {
    "Title": {
      "Text": "~$12.50"
    },
    "Condensed": {
      "Fields": [
        {
          "Type": "text_v2",
          "Label": "Gas",
          "TextV2": {
            "Text": "0.002 ETH"
          }
        }
      ]
    },
    "Expanded": {
      "Fields": [
        {
          "Type": "text_v2",
          "Label": "Gas Price",
          "TextV2": {
            "Text": "30 gwei"
          }
        },
        {
          "Type": "text_v2",
          "Label": "Gas Limit",
          "TextV2": {
            "Text": "65,000"
          }
        },
        {
          "Type": "text_v2",
          "Label": "Max Fee",
          "TextV2": {
            "Text": "0.00195 ETH"
          }
        }
      ]
    }
  }
}

Solana: Multiple Instructions

Group related instructions (based on actual test data):

{
  "Type": "list_layout",
  "Label": "Instructions",
  "FallbackText": "Transaction Instructions",
  "ListLayout": {
    "Fields": [
      {
        "Type": "text_v2",
        "Label": "Instruction 1",
        "FallbackText": "AdvanceNonceAccount",
        "TextV2": {
          "Text": "AdvanceNonceAccount"
        }
      },
      {
        "Type": "text_v2",
        "Label": "Instruction 2",
        "FallbackText": "Jupiter Swap",
        "TextV2": {
          "Text": "Jupiter Swap"
        }
      }
    ]
  }
}

Sui: Move Calls

Show Move module interactions (based on presets):

{
  "Type": "list_layout",
  "Label": "Commands",
  "FallbackText": "Transaction Commands",
  "ListLayout": {
    "Fields": [
      {
        "Type": "text_v2",
        "Label": "Module",
        "FallbackText": "pool_script_v2",
        "TextV2": {
          "Text": "pool_script_v2::swap_a2b"
        }
      },
      {
        "Type": "amount_v2",
        "Label": "Amount",
        "FallbackText": "1000000 MIST",
        "AmountV2": {
          "Amount": "1000000",
          "Abbreviation": "MIST"
        }
      }
    ]
  }
}

Risk Indicators

High-Value Warnings

{
  "Type": "text_v2",
  "Label": "⚠️ WARNING",
  "TextV2": {
    "Text": "This transaction moves more than $10,000"
  }
}

Unknown Contracts

{
  "Type": "address_v2",
  "Label": "Contract",
  "AddressV2": {
    "Address": "0x...",
    "BadgeText": "⚠️ Unverified",
    "Name": "Unknown Contract"
  }
}

Irreversible Actions

{
  "Type": "text_v2",
  "Label": "⛔ IRREVERSIBLE",
  "TextV2": {
    "Text": "This action cannot be undone"
  }
}

Testing Visualizations

Validation Checklist

Before deploying a visualization:

Clarity: Can a non-technical user understand what will happen?
Completeness: Are all important parameters shown?
Accuracy: Do amounts and addresses match the raw transaction?
Risk Communication: Are warnings prominently displayed?
Mobile Compatibility: Does it work on small screens?

User Testing

Test with different user personas:

Novice: First-time crypto user
Regular: Daily DeFi user
Expert: Smart contract developer

Edge Cases

Handle these scenarios:

Zero amounts
Failed transactions
Contract creation
Multi-signature operations
Batch transactions

Best Practices

Keep titles action-oriented: "Send ETH" not "Ethereum Transaction"
Use familiar terms: "Send" not "Transfer", "Swap" not "Exchange"
Show both technical and friendly names: "Uniswap V3 (0x68b3...)"
Group related information: Use list_layout for coherent sections
Provide context: Include network, protocol, estimated time
Be consistent: Use the same patterns across similar operations

Visualization Patterns​

Pattern 1: Simple Transfer​

Pattern 2: Transaction with Instructions​

Pattern 3: Smart Contract Interaction​

Design Guidelines​

1. Information Hierarchy​

2. Use Semantic Field Types​

3. Color and Visual Cues​

Chain-Specific Visualizations​

Ethereum: Gas Optimization​

Solana: Multiple Instructions​

Sui: Move Calls​

Risk Indicators​

High-Value Warnings​

Unknown Contracts​

Irreversible Actions​

Testing Visualizations​

Validation Checklist​

User Testing​

Edge Cases​

Best Practices​