Sui Transaction Explainer

A comprehensive Sui blockchain transaction explorer that transforms complex on-chain transactions into clear, human-readable explanations using AI-powered natural language processing.

Features • Installation • Usage • API • Docker • Contributing

📋 Project Overview

Sui Transaction Explainer is a web application designed to bridge the gap between complex blockchain transactions and everyday users. Whether you're a beginner exploring the Sui ecosystem or a developer needing quick transaction insights, this tool translates raw blockchain data into plain English using both rule-based analysis and Gemini AI.

What This Solves

Complexity Barrier: Blockchain transactions contain technical data that is difficult for non-technical users to understand
Information Overload: Raw transaction data includes many fields that aren't immediately relevant
Context Gap: Users need explanations of what happened, not just raw numbers

Key Capabilities

🔍 Real-time Fetching: Query any Sui transaction by digest or explorer URL
📝 AI-Powered Translation: Convert technical data into easy-to-understand explanations using Gemini
📊 3-Tier Explanations: Choose from Beginner, Intermediate, or Technical explanation levels
💰 Financial Analysis: Identify transaction types (swap, transfer, buy, sell, mint, burn, DeFi)
📈 Enhanced Data: Blockberry API integration for detailed events, balance changes, and USDC values
🔧 Move Call Breakdown: Understand smart contract interactions without learning Move syntax
🎨 Visual Flow Diagrams: Interactive React Flow visualizations showing 7-stage transaction flow
🚀 Docker Ready: Production-ready Docker multi-stage build for containerized deployment

✨ Features

Core Features

Feature	Description
Transaction Input	Paste transaction digests (hex or Base58) or full Sui explorer URLs
Automatic Validation	Input validation ensures correct formats before processing
Real-time RPC Queries	Fetches transaction data directly from Sui RPC endpoints
AI-Powered Summary	Gemini-generated natural language explanations
3-Tier Explanation Levels	Beginner (simple), Intermediate (detailed), Technical (full)
Gas Analysis	Detailed breakdown of computation, storage, and gas fees
Balance Changes	Track all token and SUI balance changes
Object Activity	Monitor NFTs, coins, and custom objects (create, transfer, modify, delete)
Error Handling	User-friendly error messages with suggested solutions

Advanced Features

Transaction Type Detection: Automatically identifies buy, sell, swap, transfer, mint, burn, DeFi, and programmable transactions
USD Value Estimation: Shows approximate USD values for SUI and common tokens (including USDC via Blockberry)
Visual Flow Diagrams: Animated 7-stage React Flow visualization (Sender → Initiation → Verification → Processing → Confirmation → Completion → Recipients)
Move Call Explorer: Step-by-step breakdown of smart contract calls with plain-English explanations
Blockberry Integration: Enhanced indexing for detailed events, balance changes, and USDC values
Dark Mode: Full dark mode support for comfortable viewing
Responsive Design: Optimized for desktop and mobile devices

🛠 Prerequisites

Before you begin, ensure you have:

Node.js: Version 18.17.0 or higher
```
node --version
```
npm or yarn: Package manager (npm comes with Node.js)
```
npm --version
```
Docker (optional): For containerized deployment
```
docker --version
```
API Keys (optional):
- Gemini API key for AI-powered explanations
- Blockberry API key for enhanced transaction data

📦 Installation

1. Clone the Repository

git clone https://github.com/yourusername/sui-transaction-explainer.git
cd sui-transaction-explainer

2. Install Dependencies

# Using npm
npm install

# Using yarn
yarn install

3. Configure Environment Variables

Create a .env.local file in the project root:

# Sui RPC Endpoints
NEXT_PUBLIC_SUI_RPC_URL=https://fullnode.mainnet.sui.io:443
NEXT_PUBLIC_SUI_TESTNET_RPC_URL=https://fullnode.testnet.sui.io:443

# Gemini API (optional - for AI explanations)
GEMINI_API_KEY=your_gemini_api_key_here

# Blockberry API (optional - for enhanced data)
BLOCKBERRY_API_KEY=your_blockberry_api_key_here

Note: The application works without optional API keys using rule-based explanations and basic RPC data.

4. Run the Development Server

npm run dev

The application will be available at http://localhost:3000

5. Build for Production

npm run build
npm run start

🐳 Docker Deployment

Quick Start

# Build the Docker image
docker build -t sui-transaction-explainer .

# Run with environment file
docker run -p 3000:3000 --env-file .env.production sui-transaction-explainer

Using Docker Compose

Create a docker-compose.yml file:

version: '3.8'

services:
  app:
    build: .
    ports:
      - "3000:3000"
    environment:
      - NEXT_PUBLIC_SUI_RPC_URL=https://fullnode.mainnet.sui.io:443
      - GEMINI_API_KEY=${GEMINI_API_KEY}
      - BLOCKBERRY_API_KEY=${BLOCKBERRY_API_KEY}
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
      interval: 30s
      timeout: 10s
      retries: 3

docker-compose up -d

Environment Variables for Production

See .env.production.example for production environment configuration.

📁 Project Structure

sui-transaction-explainer/
├── .env.local                    # Development environment variables
├── .env.production.example       # Production environment template
├── .dockerignore                 # Docker ignore file
├── Dockerfile                    # Multi-stage Docker build
├── docker-compose.yml            # Docker Compose configuration
├── next.config.ts                # Next.js configuration
├── tailwind.config.ts            # Tailwind CSS configuration
├── tsconfig.json                 # TypeScript configuration
├── package.json                  # Project dependencies
└── src/
    ├── app/                      # Next.js App Router
    │   ├── api/
    │   │   ├── transactions/
    │   │   │   └── [digest]/
    │   │   │       ├── route.ts         # Transaction API endpoint
    │   │   │       └── explain/         # AI explanation endpoint
    │   │   │           └── route.ts
    │   │   └── blockberry/
    │   │       └── [hash]/
    │   │           └── route.ts         # Blockberry API proxy
    │   ├── globals.css           # Global styles
    │   ├── layout.tsx            # Root layout component
    │   └── page.tsx              # Home page
    ├── components/               # React components
    │   ├── transaction/
    │   │   ├── TransactionFlow.tsx       # 7-stage flow visualization
    │   │   ├── TransactionInput.tsx      # Digest input form
    │   │   ├── TransactionSteps.tsx       # Step-by-step breakdown
    │   │   ├── TransactionSummary.tsx     # Main summary display
    │   │   ├── EnhancedDataDisplay.tsx    # Enhanced data display
    │   │   ├── MoveCallBreakdown.tsx      # Move call breakdown
    │   │   └── FinancialSummary.tsx       # Financial analysis
    │   └── ui/                   # Reusable UI components
    │       ├── Badge.tsx
    │       ├── Button.tsx
    │       ├── Card.tsx
    │       ├── Input.tsx
    │       └── Skeleton.tsx
    ├── lib/                      # Utility libraries and services
    │   ├── backend/              # Backend services
    │   │   ├── errors.ts         # Error handling
    │   │   ├── index.ts          # Backend exports
    │   │   └── validators/       # Input validators
    │   │       ├── digestValidator.ts
    │   │       └── index.ts
    │   ├── gemini/              # Gemini AI integration
    │   │   ├── client.ts         # Gemini API client
    │   │   └── prompt.ts         # Prompt templates
    │   ├── sui/                  # Sui blockchain utilities
    │   │   ├── client.ts         # Sui RPC client
    │   │   └── types.ts          # Sui type definitions
    │   ├── blockberry/           # Blockberry API integration
    │   │   ├── client.ts         # Blockberry API client
    │   │   └── types.ts          # Blockberry types
    │   ├── services/             # Business logic services
    │   │   ├── enhancedTransactionService.ts
    │   │   └── transactionService.ts
    │   ├── utils/                # Utility functions
    │   │   ├── formatting.ts
    │   │   └── validation.ts
    │   └── hooks/                 # Custom React hooks
    │       └── useTransaction.ts
    └── types/                    # TypeScript type definitions
        ├── index.ts
        ├── transaction.ts
        └── visualization.ts

🚀 Usage

Input Methods

The application accepts three input formats:

Hex Digest (64 characters):

0x8f0f2c7b3e4d1f9a8c7b6e5d4c3b2a1901234567890abcdef1234567890abcd

Base58 Digest:

4TtJvM51NrG1Z8yCFVp8h1D7R4TnTbP8W3mN5Kp7Rz9

Sui Explorer URL:

https://explorer.sui.io/transaction/0x8f0f2c7b3e4d1f9a8c7b6e5d4c3b2a1901234567890abcdef1234567890abcd

Explanation Levels

Choose the explanation level that fits your needs:

Level	Description	Best For
Beginner	Simple, non-technical summary	New users, general overview
Intermediate	Detailed with context	Regular users, some technical details
Technical	Full technical breakdown	Developers, complete information

What Information is Displayed

AI-Powered Summary

Natural language explanation of the transaction
Sender and recipient addresses (truncated for readability)
Transaction type (swap, transfer, buy, sell, mint, burn, DeFi, programmable)
Gas fees in SUI with USD approximation
Asset movement summary

Financial Details

Assets sent/received
Token amounts
USD value estimates (SUI, USDC, stablecoins)
Total transaction value
Gas breakdown (computation, storage)

Transaction Flow Visualization

7-stage interactive flow diagram showing:

Sender - Origin of the transaction
Initiation - Transaction creation and signing
Verification - Protocol validation
Processing - Smart contract execution
Confirmation - Transaction finalization
Completion - State updates
Recipients - Final asset destinations

Smart Contract Activity

Programmable Transaction Blocks (PTBs)
Package, module, and function names
Arguments breakdown
Plain English explanations of common Move functions

🔌 API Documentation

GET /api/transactions/[digest]

Fetches and processes a Sui transaction.

Request Format

GET /api/transactions/0x...

Response Format (Success)

{
  "digest": "0x...",
  "dataSource": "sui-rpc|blockberry",
  "transaction": {
    "data": { ... },
    "effects": { ... },
    "events": [ ... ],
    "objectChanges": [ ... ],
    "balanceChanges": [ ... ]
  },
  "analysis": {
    "type": "transfer|swap|buy|sell|mint|burn|defi|programmable",
    "summary": "Natural language summary",
    "financial": { ... },
    "flowNodes": [ ... ],
    "flowEdges": [ ... ]
  }
}

POST /api/transactions/[digest]/explain

Generates AI-powered explanation using Gemini.

Request Format

POST /api/transactions/0x...
Content-Type: application/json

{
  "level": "beginner|intermediate|technical"
}

Response Format (Success)

{
  "digest": "0x...",
  "level": "beginner",
  "explanation": {
    "title": "Transaction Explanation",
    "summary": "Plain English summary...",
    "details": {
      "sender": "...",
      "recipients": [ ... ],
      "assets": [ ... ],
      "gas": { ... }
    },
    "steps": [ ... ],
    "technicalInfo": { ... }
  },
  "generatedAt": "2024-01-15T10:30:00Z"
}

GET /api/blockberry/[hash]

Blockberry API proxy for enhanced transaction data.

Request Format

GET /api/blockberry/0x...

Response Format (Success)

{
  "digest": "...",
  "dataSource": "blockberry",
  "rawTransaction": { ... },
  "metadata": {
    "firstExecutedSeqNr": 12345,
    "validation": { ... },
    "sender": "0x...",
    "gasConfig": { ... }
  },
  "effects": { ... },
  "events": [ ... ],
  "balanceChanges": [ ... ],
  "objectChanges": [ ... ]
}

Features

Enhanced State Changes: Detailed object state changes (created, modified, deleted, wrapped, unwrapped)
Parsed Events: Events with structured data for easier analysis
Detailed Balance Changes: Token transfers with formatted amounts including USDC values
Fallback: Returns partial data if Blockberry API is unavailable

Error Responses

Status	Code	Message
400	INVALID_PARAMS	Invalid parameters provided
400	INVALID_DIGEST	Invalid transaction digest format
404	NOT_FOUND	Transaction does not exist
500	RPC_ERROR	Failed to connect to Sui RPC
500	AI_ERROR	Failed to generate AI explanation
503	SERVICE_UNAVAILABLE	External service temporarily unavailable

🧪 Technology Stack

Technology	Purpose	Version
Next.js	React framework	14.2.0
TypeScript	Type safety	5.4.0
Tailwind CSS	Styling	3.4.0
@mysten/sui.js	Sui blockchain SDK	1.12.0
React Flow	Interactive flow diagrams	11.11.0
Zustand	State management	4.5.0
TanStack Query	Data fetching	5.28.0
Lucide React	Icons	0.372.0
Framer Motion	Animations	11.1.0
Gemini API	AI-powered explanations	Latest
Blockberry	Enhanced indexing	Latest
Docker	Containerization	Latest
Jest	Testing	29.7.0

⚙️ Configuration

Environment Variables

Variable	Description	Default
`NEXT_PUBLIC_SUI_RPC_URL`	Mainnet RPC endpoint	`https://fullnode.mainnet.sui.io:443`
`NEXT_PUBLIC_SUI_TESTNET_RPC_URL`	Testnet RPC endpoint	`https://fullnode.testnet.sui.io:443`
`GEMINI_API_KEY`	Gemini API key for AI explanations	(optional)
`BLOCKBERRY_API_KEY`	Blockberry API key for enhanced data	(optional)

Docker Configuration

The Dockerfile uses a multi-stage build for minimal production images:

Stage 1 (deps): Install dependencies with proper caching
Stage 2 (builder): Build the Next.js application with standalone output
Stage 3 (runner): Minimal production image with non-root user

# Build arguments
ARG NODE_VERSION=20-alpine

# Production settings
ENV NODE_ENV=production
ENV NEXT_TELEMETRY_DISABLED=1

Customization

Adding New Move Function Explanations

Edit src/lib/services/translationService.ts to add explanations for new Move functions:

const MOVE_FUNCTION_EXPLANATIONS: Record<string, string> = {
  'new': 'Creates a new object instance',
  'transfer': 'Transfers ownership of an object',
  'swap': 'Exchanges one asset for another',
  // Add more functions here
};

Styling

The application uses a custom Sui-themed color palette. Modify tailwind.config.ts to customize:

theme: {
  extend: {
    colors: {
      sui: {
        primary: '#4D6AFF',
        secondary: '#6D28D9',
        // Customize other colors
      },
    },
  },
}

🧪 Testing

# Run unit tests
npm run test

# Run tests with coverage
npm run test:coverage

# Run tests in watch mode
npm run test:watch

# Run e2e tests
npm run test:e2e

🤝 Contributing

We welcome contributions! Please follow these guidelines:

Reporting Issues

Search existing issues before creating a new one
Use the issue template when available
Include steps to reproduce, expected behavior, and actual behavior
Add screenshots if relevant

Submitting Pull Requests

Fork the repository
Create a feature branch: git checkout -b feature/amazing-feature
Make your changes
Run tests: npm run test
Run linting: npm run lint
Commit your changes: git commit -m 'Add amazing feature'
Push to the branch: git push origin feature/amazing-feature
Open a Pull Request

Coding Standards

TypeScript: Strict mode enabled, no any types
Formatting: Prettier (included via ESLint)
Testing: Jest for unit tests, aim for 80% coverage
Commits: Conventional commits format preferred
Documentation: Update README and code comments

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Sui Foundation for the Sui blockchain
Mysten Labs for the @mysten/sui.js SDK
Google AI for the Gemini API
Blockberry for enhanced indexing
Next.js team for the excellent React framework
React Flow for the visualization components
All contributors who help improve this project

Built with ❤️ for the Sui ecosystem

Name		Name	Last commit message	Last commit date
Latest commit History 2 Commits
public		public
src		src
.dockerignore		.dockerignore
.env.production		.env.production
.env.production.example		.env.production.example
.gitignore		.gitignore
Dockerfile		Dockerfile
README.md		README.md
docker-compose.yml		docker-compose.yml
eslint.config.js		eslint.config.js
explain-prompt.js		explain-prompt.js
jest.config.js		jest.config.js
jest.setup.ts		jest.setup.ts
next.config.js		next.config.js
next.config.mjs		next.config.mjs
next.config.ts		next.config.ts
package-lock.json		package-lock.json
package.json		package.json
postcss.config.js		postcss.config.js
tailwind.config.ts		tailwind.config.ts
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

Sui Transaction Explainer

📋 Project Overview

What This Solves

Key Capabilities

✨ Features

Core Features

Advanced Features

🛠 Prerequisites

📦 Installation

1. Clone the Repository

2. Install Dependencies

3. Configure Environment Variables

4. Run the Development Server

5. Build for Production

🐳 Docker Deployment

Quick Start

Using Docker Compose

Environment Variables for Production

📁 Project Structure

🚀 Usage

Input Methods

Explanation Levels

What Information is Displayed

AI-Powered Summary

Financial Details

Transaction Flow Visualization

Smart Contract Activity

🔌 API Documentation

GET /api/transactions/[digest]

Request Format

Response Format (Success)

POST /api/transactions/[digest]/explain

Request Format

Response Format (Success)

GET /api/blockberry/[hash]

Request Format

Response Format (Success)

Features

Error Responses

🧪 Technology Stack

⚙️ Configuration

Environment Variables

Docker Configuration

Customization

Adding New Move Function Explanations

Styling

🧪 Testing

🤝 Contributing

Reporting Issues

Submitting Pull Requests

Coding Standards

📄 License

🙏 Acknowledgments

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages