📊 Sui Transaction Explainer API

A professional-grade backend API that translates complex Sui blockchain transactions into human-readable explanations and visual diagrams.

---

🚀 Overview

Sui transactions can be complex, involving multiple object changes, gas fees, and programmable transaction blocks (PTBs). This API simplifies the experience by providing:

• Plain English Explanations: Converts raw transaction data into clear, natural language summaries.
• Visual Diagrams: Generates Mermaid.js diagrams and SVGs to visualize transaction flow.
• Address Analysis: Analyzes recent activity for any Sui address.
• Developer-Friendly: Fully typed with TypeScript, documented REST endpoints, and Docker-ready.

---

🛠 Tech Stack

• Runtime: Node.js (v20+)
• Language: TypeScript
• Framework: Express.js
• Blockchain SDK: @mysten/sui.js
• Visualization: Mermaid.js, @mermaid-js/mermaid-cli
• Security: Helmet, CORS, Compression
• Testing: Jest, Supertest

---

✨ Features

1. Natural Language Engine

Translates technical transaction effects into sentences like: "User A transferred 5 SUI to User B and mutated 2 objects."

2. Visualization System

Automatically generates:

• Mermaid Diagrams: Code representation of the transaction flow.
• SVG Diagrams: Ready-to-use visual maps of actors and object interactions.
• Web View: Interactive HTML page to preview transaction details.

3. Advanced Analysis

• Batch Processing: Explain up to 10 transactions in a single request.
• URL Extraction: Paste a SuiScan URL, and the API does the rest.
• Object Classification: Identifies created, mutated, and deleted objects.

---

🏁 Getting Started

Prerequisites

• Node.js v20 or higher
• npm or yarn

Installation

1. Clone the repository

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

2. Install dependencies

   npm install

3. Configure environment

   cp .env.example .env 

4. Start in development mode

   npm run dev

---

⚙️ Configuration

Variable	Description	Default
PORT	API Port	3001
NODE_ENV	Environment (development/production)	your_enviroment
SUI_NETWORK	Sui network (mainnet/testnet/devnet)	your_network
SUI_RPC_URL	Custom RPC endpoint	your_rpc_url
LOG_LEVEL	Logging verbosity (debug/info/warn/error)	your_log_level
CORS_ORIGIN	Allowed CORS origins	your_cors_origin

---

📡 API Reference

Explainer Endpoints

Method	Endpoint	Description
GET	/explain/:digest	Explains a single transaction digest
GET	/explain/:digest/plain	Plain English explanation + summary
GET	/explain/:digest/visual	Full explanation + Mermaid diagram + SVG
GET	/explain/:digest/view	HTML preview page of the transaction
POST	/explain/batch	Batch process multiple digests (max 10)
POST	/explain/url	Extract digest from SuiScan URL and explain
GET	/explain/address/:addr/latest	Explain the latest transaction for an address

Utility Endpoints

Method	Endpoint	Description
GET	/health	Service health status
GET	/	API Information and documentation overview

---

🧪 Testing & Quality

• Unit/Integration Tests: npm test
• Linting: npm run lint
• Code Formatting: npm run format
• Integration Scripts:
  • make english: Test plain English output
  • make address: Test address analysis
  • make nft: Test NFT detection logic

---

🐳 Deployment

Docker

docker build -t sui-explainer .
docker run -p 3001:3001 --env-file .env sui-explainer

---

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

---

📄 License

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

---

Built with ❤️ by JES-labs