Field Types Reference

Building blocks for displaying blockchain data in visualizations

Field types are the building blocks of VisualSign visualizations. Each type displays specific kinds of blockchain data in a clear, consistent way.

Core field types

text_v2

Displays plain text information. Use for labels, status messages, and non-monetary values.

{
  "Type": "text_v2",
  "Label": "Network",
  "TextV2": {
    "Text": "Ethereum Mainnet"
  }
}

When to use:

• Network names
• Protocol identifiers
• Status messages
• Transaction types
• Warning messages

amount_v2

Displays monetary values with proper formatting. Automatically handles decimal places and currency symbols.

{
  "Type": "amount_v2",
  "Label": "You're sending",
  "AmountV2": {
    "Amount": "1234.56",
    "Abbreviation": "USDC"
  }
}

Properties:

• Amount: Numeric string (must be a valid signed decimal number)
• Abbreviation: Token symbol or currency code

Visual treatment:

• Large, prominent display for amounts
• Currency symbol or code shown clearly
• Automatic formatting for readability

address_v2

Displays blockchain addresses with optional identity resolution and verification badges.

{
  "Type": "address_v2",
  "Label": "Recipient",
  "AddressV2": {
    "Address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb7",
    "Name": "Uniswap V3 Router",
    "BadgeText": "Verified Contract"
  }
}

Properties:

• Address: The blockchain address
• Name (optional): ENS name, contract name, or identity
• BadgeText (optional): Verification status or warning

Visual features:

• Truncated address display (0x742d…bEb7)
• Copy-to-clipboard functionality
• Visual badges for verification status
• Color coding for risk levels

Layout field types

list_layout

Groups related fields together in a vertical list. Perfect for showing multiple related parameters.

{
  "Type": "list_layout",
  "Label": "Token Swap",
  "ListLayout": {
    "Fields": [
      {
        "Type": "amount_v2",
        "Label": "From",
        "AmountV2": {
          "Amount": "1.5",
          "Abbreviation": "ETH"
        }
      },
      {
        "Type": "amount_v2",
        "Label": "To",
        "AmountV2": {
          "Amount": "2,850.00",
          "Abbreviation": "USDC"
        }
      }
    ]
  }
}

When to use:

• Grouping related parameters
• Showing inputs/outputs
• Listing multiple recipients
• Displaying step sequences

preview_layout

Provides expandable/collapsible content with progressive disclosure. Shows essential info collapsed, full details when expanded.

{
  "Type": "preview_layout",
  "Label": "Advanced Settings",
  "PreviewLayout": {
    "Title": {
      "Text": "Gas Settings"
    },
    "Subtitle": {
      "Text": "~$12.50"
    },
    "Condensed": {
      "Fields": [
        {
          "Type": "text_v2",
          "Label": "Fee",
          "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"
          }
        }
      ]
    }
  }
}

Properties:

• Title: Main heading for the preview
• Subtitle (optional): Secondary information
• Condensed: Fields shown when collapsed
• Expanded: Full field list when expanded

Visual behavior:

• Chevron indicator for expand/collapse
• Smooth animation between states
• Preserves user’s expand/collapse choice

Field type selection guide

Data Type	Recommended Field	Example Use Case
Token amounts	amount_v2	”Sending 100 USDC”
Fees	amount_v2	”Network fee: 0.002 ETH”
Wallet addresses	address_v2	”To: alice.eth”
Contract addresses	address_v2	”Interacting with: Compound V3”
Status/State	text_v2	”Status: Pending”
Network info	text_v2	”Network: Ethereum Mainnet”
Multiple values	list_layout	List of recipients
Complex data	preview_layout	Detailed gas breakdown
Warnings	text_v2	”Warning: High slippage”
Parse diagnostics	diagnostic	OOB indices, data quality checks

Combining field types

Example: DeFi position

{
  "Version": "0",
  "Title": "Supply to Aave",
  "Fields": [
    {
      "Type": "text_v2",
      "Label": "Protocol",
      "TextV2": {
        "Text": "Aave V3"
      }
    },
    {
      "Type": "amount_v2",
      "Label": "Supplying",
      "AmountV2": {
        "Amount": "10,000",
        "Abbreviation": "USDC"
      }
    },
    {
      "Type": "preview_layout",
      "Label": "Position Details",
      "PreviewLayout": {
        "Title": {
          "Text": "After Transaction"
        },
        "Condensed": {
          "Fields": [
            {
              "Type": "text_v2",
              "Label": "APY",
              "TextV2": {
                "Text": "4.2%"
              }
            }
          ]
        },
        "Expanded": {
          "Fields": [
            {
              "Type": "text_v2",
              "Label": "Current APY",
              "TextV2": {
                "Text": "4.2%"
              }
            },
            {
              "Type": "amount_v2",
              "Label": "Total Supplied",
              "AmountV2": {
                "Amount": "25,000",
                "Abbreviation": "USDC"
              }
            },
            {
              "Type": "text_v2",
              "Label": "Health Factor",
              "TextV2": {
                "Text": "2.5"
              }
            },
            {
              "Type": "address_v2",
              "Label": "Pool Contract",
              "AddressV2": {
                "Address": "0x87870Bca3F3fD6335C3F4ce8392D69350B4fA4E2",
                "Name": "Aave V3 Pool",
                "BadgeText": "Verified"
              }
            }
          ]
        }
      }
    }
  ]
}

Best practices

1. Label clarity

• Use action-oriented labels (“You’re sending” vs “Amount”)
• Keep labels concise but descriptive
• Use consistent terminology across transactions

2. Progressive complexity

• Show critical information with basic field types
• Use preview_layout for advanced details
• Group related items with list_layout

3. Risk communication

{
  "Type": "text_v2",
  "Label": "WARNING",
  "TextV2": {
    "Text": "First time interacting with this contract"
  }
}

4. Visual hierarchy

• Primary action: Large amount_v2 fields
• Recipients: Clear address_v2 with names
• Context: text_v2 for supporting information
• Details: preview_layout for optional viewing

Platform considerations

Mobile optimization

• Field types automatically adapt to screen size
• preview_layout defaults to collapsed on mobile
• Touch-friendly expand/collapse controls
• Horizontal scrolling for addresses

Accessibility

• All field types support screen readers
• Keyboard navigation between fields
• High contrast mode support
• ARIA labels for interactive elements

Internationalization

Parser output is ASCII-only (see Character set validation). Wallet applications handle localization:

• Locale-aware number formatting (decimal separators, grouping)
• Currency symbol positioning based on locale
• Date/time formatting for timestamps
• UI translation of standard labels

Validation

Each field type has validation rules:

Character set (all fields)

All text content is restricted to printable ASCII characters only (codes 0x20-0x7E). The following are rejected:

• Unicode characters (Chinese, Japanese, Arabic, Cyrillic, etc.)
• Emoji
• Non-ASCII currency symbols (€, £, ¥)
• Control characters and zero-width characters
• Unicode escape sequences (\u)

This restriction prevents security attacks including:

• Homoglyph attacks: Cyrillic “а” (U+0430) looks identical to Latin “a” (U+0061)
• Right-to-left override: Characters that reverse text direction
• Invisible characters: Zero-width spaces that hide content

Token names and other content must use ASCII equivalents (e.g., “EUR” instead of ”€“).

amount_v2

• Amount must be a valid signed decimal number (validated by regex)
• Abbreviation must be non-empty
• Supports decimal places
• Large numbers should use decimal notation, not scientific notation

address_v2

• Must be valid for target chain
• Ethereum: 40 hex characters with 0x prefix
• Solana: Valid Base58 public key
• Sui: 32-byte hex address with 0x prefix
• Tron: Base58 address starting with T

text_v2

• Maximum 500 characters
• ASCII printable characters only (see character set above)
• HTML is escaped for security

Layout types

• Maximum 20 nested fields
• Recursive nesting not allowed
• At least one field required

Chain-specific patterns

Ethereum ERC-20 approval

{
  "Version": "0",
  "Title": "Approve USDC Spending",
  "Fields": [
    {
      "Type": "address_v2",
      "Label": "Token Contract",
      "AddressV2": {
        "Address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
        "Name": "USDC",
        "BadgeText": "Verified"
      }
    },
    {
      "Type": "address_v2",
      "Label": "Spender",
      "AddressV2": {
        "Address": "0x68b3465833fb72A70ecDF485E0e4C7bD8665Fc45",
        "Name": "Uniswap V3 Router",
        "BadgeText": "Verified"
      }
    },
    {
      "Type": "amount_v2",
      "Label": "Allowance",
      "AmountV2": {
        "Amount": "Unlimited",
        "Abbreviation": "USDC"
      }
    }
  ]
}

Solana SPL token transfer

{
  "Version": "0",
  "Title": "Transfer SPL Tokens",
  "Fields": [
    {
      "Type": "list_layout",
      "Label": "Instructions",
      "ListLayout": {
        "Fields": [
          {
            "Type": "text_v2",
            "Label": "1",
            "TextV2": {
              "Text": "Create Associated Token Account"
            }
          },
          {
            "Type": "amount_v2",
            "Label": "2",
            "AmountV2": {
              "Amount": "100",
              "Abbreviation": "USDC"
            }
          }
        ]
      }
    }
  ]
}

Diagnostic field type

diagnostic

Reports data quality findings from the parser’s lint framework. Diagnostics are attested alongside display fields in the signed payload, so the HSM/attester can verify what the parser checked and what it found.

{
  "Type": "diagnostic",
  "Label": "transaction::oob_program_id",
  "FallbackText": "warn: instruction 1: program_id_index 8 out of bounds (5 account keys)",
  "Diagnostic": {
    "Rule": "transaction::oob_program_id",
    "Domain": "transaction",
    "Level": "warn",
    "Message": "instruction 1: program_id_index 8 out of bounds (5 account keys)",
    "InstructionIndex": 1
  }
}

Properties:

• Rule: Rule identifier in domain::rule_name format
• Domain: Category of the check (e.g., transaction, decode, idl)
• Level: Severity of the finding
  • ok — rule ran and found no issues (boot-metric attestation)
  • warn — data quality issue found, parsing continued
  • error — serious issue found
• Message: Human-readable description of the finding
• InstructionIndex (optional): Which instruction triggered the diagnostic

Wallet handling:

• Wallets that don’t recognize Type: "diagnostic" can display the FallbackText
• Diagnostics always appear after all display fields (network, instructions, accounts)
• When report_all_rules is enabled (default), every rule emits a diagnostic — ok, warn, or error — so the attester can verify all expected rules ran

Current rules:

Rule	Domain	Description
transaction::oob_program_id	transaction	Instruction’s program_id_index is out of bounds in account_keys
transaction::oob_account_index	transaction	Instruction references account indices beyond account_keys
transaction::empty_account_keys	transaction	Transaction has no account keys
decode::visualizer_error	decode	A visualizer failed to decode an instruction (always-on)

Future field types

Planned additions to the field type system:

• image_v2: NFT previews and token logos
• chart_v2: Price charts and historical data
• qr_v2: QR codes for addresses
• signature_v2: Signature visualization
• timeline_v2: Transaction history display