Skip to main content

API Reference

Field Types​

VisualSign supports various field types to represent different kinds of transaction data.

text_v2​

Displays plain text information.

{
  "Type": "text_v2",
  "Label": "Network",
  "FallbackText": "Unknown",
  "TextV2": {
    "Text": "Solana Mainnet"
  }
}

amount_v2​

Displays amounts with optional currency/abbreviation.

{
  "Type": "amount_v2",
  "Label": "Transfer Amount",
  "FallbackText": "N/A",
  "AmountV2": {
    "Amount": "100.50",
    "Currency": "USDC",
    "Abbreviation": "USDC"
  }
}

address_v2​

Displays blockchain addresses with optional metadata.

{
  "Type": "address_v2",
  "Label": "Recipient",
  "FallbackText": "No address",
  "AddressV2": {
    "Address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb7",
    "Name": "Alice's Wallet",
    "Memo": "Payment for services",
    "AssetLabel": "ETH",
    "BadgeText": "Verified"
  }
}

list_layout​

Groups related fields together.

{
  "Type": "list_layout",
  "Label": "Transaction Details",
  "FallbackText": "No details",
  "ListLayout": {
    "Fields": [
      {
        "Type": "text_v2",
        "Label": "Fee",
        "TextV2": {
          "Text": "0.001 ETH"
        }
      }
    ]
  }
}

preview_layout​

Expandable sections with condensed and expanded views.

{
  "Type": "preview_layout",
  "Label": "Advanced Details",
  "FallbackText": "No details",
  "PreviewLayout": {
    "Title": {
      "Text": "Transaction Metadata"
    },
    "Subtitle": {
      "Text": "Click to expand"
    },
    "Condensed": {
      "Fields": [
        // Fields shown when collapsed
      ]
    },
    "Expanded": {
      "Fields": [
        // Additional fields shown when expanded
      ]
    }
  }
}

divider​

Visual separator between sections.

{
  "Type": "divider",
  "Label": "",
  "FallbackText": "",
  "Divider": {
    "Style": ""
  }
}

Transaction Structure​

Root Object​

interface TransactionData {
  Version: string;           // Format version
  Title: string;             // Transaction title
  Subtitle?: string;         // Optional subtitle
  Fields: Field[];           // Array of field objects
  ReplayProtection?: string; // Optional replay protection
  VaultSubID?: string;       // Optional vault sub-ID
  EndorsedParamsDigest?: string; // Optional params digest
}

Parser gRPC API​

The VisualSign Parser exposes a gRPC service for transaction parsing.

ParseTransaction​

Parses a raw transaction and returns structured JSON.

Request:

message ParseRequest {
  bytes raw_transaction = 1;
  string chain = 2; // "solana", "ethereum", "sui", "bitcoin"
}

Response:

message ParseResponse {
  string json_output = 1; // Structured TransactionData JSON
  string error = 2;        // Error message if parsing fails
}

Integration Examples​

JavaScript/TypeScript​

import { TransactionDisplay } from '@visualsign/display';

const transactionData = {
  Version: "0",
  Title: "Token Transfer",
  Fields: [
    // ... field data
  ]
};

// Render the transaction
<TransactionDisplay data={transactionData} />

Python​

import json
import grpc
from visualsign_pb2 import ParseRequest
from visualsign_pb2_grpc import ParserStub

# Connect to parser service
channel = grpc.insecure_channel('localhost:44020')
stub = ParserStub(channel)

# Parse transaction
request = ParseRequest(
    raw_transaction=raw_tx_bytes,
    chain='ethereum'
)
response = stub.ParseTransaction(request)

# Get structured data
transaction_data = json.loads(response.json_output)

Error Handling​

The parser returns errors in the following format:

{
  "error": "Invalid transaction format",
  "code": "INVALID_FORMAT",
  "details": "Transaction missing required fields"
}

Common error codes:

  • INVALID_FORMAT - Malformed transaction data
  • UNSUPPORTED_CHAIN - Chain not supported
  • PARSING_ERROR - Error during parsing
  • VERIFICATION_FAILED - Signature verification failed