Stellar Transaction Visualizer

A powerful visualization tool and SDK for Stellar blockchain transactions with advanced Soroban smart contract support.

Table of Contents

• Prerequisites
• Installation
• Quick Start
• Features
• Configuration
• Integration Options
• SDK API Overview
• Examples
• Documentation
• Development
• Testing
• Contributing
• License

Prerequisites

Before installing, ensure you have:

• Node.js >= 16.x
• npm >= 8.x (or yarn >= 1.22.x)
• @stellar/stellar-sdk >= 11.x (peer dependency)

Installation

Install via npm:

npm install @nibrasd/transaction-visualizer

Or using yarn:

yarn add @nibrasd/transaction-visualizer

Peer Dependencies

This package requires React as a peer dependency:

npm install react react-dom

Note: If you're only using the SDK functions (without React components), you can skip installing React.

Quick Start

Basic Usage

import { StellarTransactionVisualizer } from '@nibrasd/transaction-visualizer';

// Initialize with network configuration
const visualizer = new StellarTransactionVisualizer({
  isTestnet: true
});

// Fetch and analyze a transaction
try {
  const tx = await visualizer.getTransactionDetails('YOUR_TX_HASH');

  console.log('Status:', tx.status);
  console.log('Operations:', tx.operations.length);
  console.log('Smart Contracts:', visualizer.getSorobanOperations(tx).length);
} catch (error) {
  console.error('Failed to fetch transaction:', error);
}

Standalone Functions

import { fetchTransaction, setNetwork } from '@nibrasd/transaction-visualizer';

// Configure network
setNetwork({
  isTestnet: true,
  networkUrl: 'https://horizon-testnet.stellar.org',
  networkPassphrase: 'Test SDF Network ; September 2015'
});

// Fetch transaction with error handling
try {
  const transaction = await fetchTransaction('YOUR_TX_HASH');
  console.log('Transaction fetched:', transaction);
} catch (error) {
  console.error('Error:', error.message);
}

Features

Transaction Analysis

• Visualize all Stellar operation types
• Detailed operation breakdown with amounts, accounts, and assets
• Error detection and analysis
• Transaction status tracking
• Real-time transaction monitoring

Smart Contract Support

• Extract and display contract IDs from invoke_host_function operations
• Identify plant, harvest, and custom contract functions
• Contract event visualization
• Cross-contract call detection and visualization
• State changes and TTL extension tracking
• Resource usage breakdown (fees, CPU, memory)

Advanced Visualization

• Interactive flow diagrams showing operation sequences
• Color-coded operation types for quick identification
• Special icons for contract operations (plant 🌱, harvest 🌾)
• Path payment visualization with trading paths

Transaction Simulation & Contract Testing

• Simulate transactions before submission (Testnet only)
• Contract simulator with smart argument parsing
  • Automatic Stellar address detection (G... and C... addresses)
  • Intelligent type conversion (u32, u64, i64)
  • Support for complex types (arrays, objects)
• Resource usage analysis
• Comprehensive debugging information
• Operation-level breakdowns

Network Support

• Mainnet and Testnet compatibility
• Easy network switching
• Custom network configuration

Configuration

Configuration Options

All configuration options for StellarTransactionVisualizer:

| Option | Type | Required | Default | Description | |--------|------|----------|---------|-------------| | isTestnet | boolean | No | false | Use testnet network | | networkUrl | string | No | Auto-detected | Custom Horizon URL | | networkPassphrase | string | No | Auto-detected | Network passphrase |

Network Configuration Examples

Testnet Configuration:

const visualizer = new StellarTransactionVisualizer({
  isTestnet: true,
  networkUrl: 'https://horizon-testnet.stellar.org',
  networkPassphrase: 'Test SDF Network ; September 2015'
});

Mainnet Configuration:

const visualizer = new StellarTransactionVisualizer({
  isTestnet: false,
  networkUrl: 'https://horizon.stellar.org',
  networkPassphrase: 'Public Global Stellar Network ; September 2015'
});

Default Configuration (Mainnet):

const visualizer = new StellarTransactionVisualizer();
// Automatically uses Mainnet with default settings

Changing Network at Runtime

const visualizer = new StellarTransactionVisualizer({ isTestnet: true });

// Switch to mainnet
visualizer.setNetwork({
  isTestnet: false,
  networkUrl: 'https://horizon.stellar.org',
  networkPassphrase: 'Public Global Stellar Network ; September 2015'
});

Integration Options

This project can be integrated into your product in multiple ways:

1. NPM Package (Recommended)

Install and use in your React/JavaScript application:

npm install @nibrasd/transaction-visualizer

import { StellarTransactionVisualizer } from '@nibrasd/transaction-visualizer';

2. Embedded Widget

Deploy the web app and embed it as an iframe:

<!-- Basic embed -->
<iframe
  src="YOUR_DEPLOYMENT_URL?tx=TRANSACTION_HASH"
  width="100%"
  height="800px"
  frameborder="0"
  sandbox="allow-scripts allow-same-origin"
></iframe>

Security Considerations:

• Always deploy to HTTPS
• Use appropriate sandbox attributes
• Validate transaction hashes before embedding
• Consider CSP (Content Security Policy) headers

URL Parameters:

• tx - Transaction hash (required)
• network - Network type: testnet or mainnet (optional, default: mainnet)

Example:

<iframe src="https://your-domain.com?tx=abc123&network=testnet"></iframe>

3. Direct SDK

Use the SDK functions directly without UI components for custom implementations:

import {
  fetchTransaction,
  setNetwork,
  decodeScVal
} from '@nibrasd/transaction-visualizer';

See integration examples:

• Quick Start Guide - Get started in 5 minutes
• Complete Examples - Node.js, React, Next.js, Express
• API Documentation - Full API reference

SDK API Overview

Class-based API (Recommended)

const visualizer = new StellarTransactionVisualizer(config);

// Core methods
visualizer.getTransactionDetails(hash)      // Fetch and analyze transaction
visualizer.getSorobanOperations(tx)        // Extract smart contract operations
visualizer.getContractEvents(tx)           // Get contract events
visualizer.getStateChanges(tx)             // Get state changes
visualizer.getCrossContractCalls(tx)       // Get cross-contract calls
visualizer.getTransactionEffects(tx)       // Get transaction effects
visualizer.decodeScVal(scVal)              // Decode Soroban values
visualizer.setNetwork(config)              // Change network

Standalone Functions

import {
  fetchTransaction,      // Fetch transaction details
  setNetwork,           // Configure network
  decodeScVal,          // Decode Soroban values
  simulateTransaction   // Simulate transaction (testnet only)
} from '@nibrasd/transaction-visualizer';

Full API documentation: SDK_DOCUMENTATION.md

Examples

Transaction Monitoring

import { fetchTransaction, setNetwork } from '@nibrasd/transaction-visualizer';
import * as StellarSdk from '@stellar/stellar-sdk';

// Configure network
setNetwork({ isTestnet: true });

async function monitorAccount(accountId: string) {
  const server = new StellarSdk.Server('https://horizon-testnet.stellar.org');

  let stream: any;

  try {
    stream = server
      .transactions()
      .forAccount(accountId)
      .cursor('now')
      .stream({
        onmessage: async (tx: any) => {
          try {
            const details = await fetchTransaction(tx.hash);
            console.log('New transaction:', {
              hash: tx.hash,
              status: details.status,
              operations: details.operations.length
            });
          } catch (error) {
            console.error('Error processing transaction:', error);
          }
        },
        onerror: (error: any) => {
          console.error('Stream error:', error);
        }
      });

    console.log('Monitoring account:', accountId);

    // Stop stream after 1 hour
    setTimeout(() => {
      if (stream) {
        stream();
        console.log('Stopped monitoring');
      }
    }, 3600000);

  } catch (error) {
    console.error('Failed to start monitoring:', error);
  }
}

// Usage
monitorAccount('GXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX');

Path Payment Analysis

import { fetchTransaction } from '@nibrasd/transaction-visualizer';

async function analyzePathPayment(txHash: string) {
  try {
    const tx = await fetchTransaction(txHash);

    tx.operations.forEach((operation, index) => {
      if (operation.type === 'path_payment_strict_send') {
        console.log(`\nPath Payment #${index + 1}:`);
        console.log('Send:', operation.sendAmount, operation.send_asset_code || 'XLM');
        console.log('Receive (min):', operation.destMin, operation.dest_asset_code || 'XLM');
        console.log('Path hops:', operation.path?.length || 0);

        if (operation.path && operation.path.length > 0) {
          console.log('Trading path:');
          operation.path.forEach((asset: any, i: number) => {
            console.log(`  ${i + 1}. ${asset.asset_code || 'XLM'}`);
          });
        }
      }
    });
  } catch (error) {
    console.error('Failed to analyze path payment:', error);
  }
}

Smart Contract Analysis

import { StellarTransactionVisualizer } from '@nibrasd/transaction-visualizer';

async function analyzeSmartContract(txHash: string) {
  const visualizer = new StellarTransactionVisualizer({ isTestnet: true });

  try {
    const tx = await visualizer.getTransactionDetails(txHash);
    const sorobanOps = visualizer.getSorobanOperations(tx);

    if (sorobanOps.length === 0) {
      console.log('No smart contract operations found');
      return;
    }

    console.log(`Found ${sorobanOps.length} smart contract operation(s)\n`);

    sorobanOps.forEach((op, index) => {
      console.log(`Contract Operation #${index + 1}:`);
      console.log('Contract ID:', op.contractId || 'Unknown');
      console.log('Function:', op.functionName || 'Unknown');

      if (op.resourceUsage) {
        console.log('\nResource Usage:');
        console.log('CPU Instructions:', op.resourceUsage.cpuInstructions);
        console.log('Memory (bytes):', op.resourceUsage.memoryBytes);
        console.log('Refundable Fee:', op.resourceUsage.refundableFee, 'stroops');
        console.log('Non-refundable Fee:', op.resourceUsage.nonRefundableFee, 'stroops');
      }

      if (op.crossContractCalls && op.crossContractCalls.length > 0) {
        console.log('\nCross-contract calls:');
        op.crossContractCalls.forEach(call => {
          console.log(`  ${call.fromContract} → ${call.toContract}`);
          console.log(`  Function: ${call.functionName || 'Unknown'}`);
          console.log(`  Status: ${call.success ? 'Success' : 'Failed'}`);
        });
      }

      console.log('\n---\n');
    });

    // Get contract events
    const events = visualizer.getContractEvents(tx);
    if (events.length > 0) {
      console.log(`Contract Events: ${events.length}`);
      events.forEach((event, i) => {
        console.log(`Event #${i + 1}:`, event);
      });
    }

  } catch (error) {
    console.error('Failed to analyze smart contract:', error);
  }
}

Transaction Simulation

import { StellarTransactionVisualizer } from '@nibrasd/transaction-visualizer';

async function simulateContractCall() {
  const visualizer = new StellarTransactionVisualizer({ isTestnet: true });

  try {
    const result = await visualizer.simulateTransaction({
      contractId: 'CXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX',
      functionName: 'transfer',
      args: [
        'GXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX', // from
        'GXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX', // to
        '1000000' // amount (1 XLM in stroops)
      ],
      sourceAccount: 'GXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
    });

    console.log('Simulation result:', result);
    console.log('Estimated fee:', result.minResourceFee);
    console.log('Success:', result.success);

  } catch (error) {
    console.error('Simulation failed:', error);
  }
}

Operation Support

The visualizer supports all Stellar operations:

Payments

• payment - Direct payments
• path_payment_strict_send - Path payments (strict send)
• path_payment_strict_receive - Path payments (strict receive)

Account Management

• create_account - Account creation
• account_merge - Account merging
• set_options - Account configuration
• bump_sequence - Sequence number bumping

Assets & Trust

• change_trust - Trustline creation/modification
• allow_trust - Trustline authorization
• set_trust_line_flags - Flag management
• clawback - Asset clawback

Trading (DEX)

• manage_sell_offer - Create/update sell offers
• manage_buy_offer - Create/update buy offers
• create_passive_sell_offer - Passive offers

Smart Contracts (Soroban)

• invoke_host_function - Contract invocations
• Special function detection (plant, harvest, swap, transfer)
• Contract ID extraction
• Event parsing
• Cross-contract call detection

Sponsorship

• begin_sponsoring_future_reserves
• end_sponsoring_future_reserves
• revoke_sponsorship

Documentation

📚 API Documentation - Comprehensive API reference and examples

📚 Quick Reference - Quick lookup for common patterns

📚 Integration Examples - Real-world integration examples

TypeScript Support

Full TypeScript support with comprehensive type definitions:

import type {
  TransactionDetails,
  SorobanOperation,
  ContractEvent,
  NetworkConfig,
  ResourceUsage,
  CrossContractCall
} from '@nibrasd/transaction-visualizer';

Development

Setup

# Clone repository
git clone https://github.com/NibrasD/stellar-transaction-visualizer.git
cd stellar-transaction-visualizer

# Install dependencies
npm install

Build

# Build SDK for distribution
npm run build:sdk

# Build web application
npm run build:web

# Build everything (SDK + web app)
npm run build

# Run development server
npm run dev

Project Structure

stellar-transaction-visualizer/
├── src/
│   ├── components/          # React components
│   │   ├── TransactionFlow.tsx
│   │   ├── OperationNode.tsx
│   │   ├── TransactionSearch.tsx
│   │   └── SimulationPanel.tsx
│   ├── services/
│   │   └── stellar.ts      # Core SDK functions
│   ├── types/
│   │   └── stellar.ts      # TypeScript definitions
│   └── sdk/
│       └── index.ts        # SDK entry point
├── examples/               # Integration examples
├── dist/                   # Build output
├── package.json
└── README.md

Testing

Run Tests

# Run all tests
npm test

# Run linter
npm run lint

# Run type checking
npm run type-check

Testing Framework

This project uses:

• ESLint for code linting
• TypeScript for type checking
• Testing integration examples available in /examples

Writing Tests

When contributing, ensure your code:

1. Passes TypeScript compilation
2. Follows ESLint rules
3. Includes proper error handling
4. Has examples in documentation

Getting Help

If you encounter issues not covered here:

1. Check GitHub Issues
2. Review API Documentation

Browser Compatibility

| Browser | Support | |---------|---------| | Chrome/Edge | ✅ Latest 2 versions | | Firefox | ✅ Latest 2 versions | | Safari | ✅ Latest 2 versions | | Mobile Safari | ✅ iOS 13+ | | Chrome Mobile | ✅ Android 8+ |

Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create a feature branch

   git checkout -b feature/amazing-feature

3. Make your changes
   • Write clean, documented code
   • Follow existing code style
   • Add tests if applicable
4. Commit your changes

   git commit -m 'Add amazing feature'

5. Push to the branch

   git push origin feature/amazing-feature

6. Open a Pull Request

Contribution Guidelines

• Follow TypeScript best practices
• Maintain test coverage
• Update documentation for new features
• Keep commits atomic and well-described
• Be respectful and constructive

Resources

• Stellar Documentation
• Stellar SDK
• Stellar Laboratory
• Full API Documentation

License

MIT License © 2025 NibrasD

Support

• GitHub Issues: Report bugs or request features

Acknowledgments

Built with:

• Stellar SDK
• React Flow
• Vite
• TypeScript

⭐ If you find this project helpful, please consider giving it a star on GitHub!