Skip to content

README.md

Latest commit

 

History

History
292 lines (206 loc) · 7.26 KB

README.md

File metadata and controls

292 lines (206 loc) · 7.26 KB

Noot Explorer

A modern blockchain explorer for the Noot smart contract platform, built with React Router.

Features

  • Chain Statistics: View total transactions, token count, and recent activity
  • Transaction Browser: Browse all transactions with operation types and details
  • Token Registry: View all created tokens with supply and holder information
  • Token Details: Inspect individual tokens and their balance distributions
  • Message Sender: Create and send contract messages directly from the UI
  • Preflight Validation: Validate messages before sending to catch errors early
  • Network Filtering: Automatically filters transactions by configured network (testnet/mainnet)
  • Real-time Updates: Live updates via Krist websocket connection

Getting Started

Prerequisites

  • Node.js 18+
  • pnpm
  • A running Noot client (configured via config.json)

Installation

From the repository root:

pnpm install

Configuration

Create a config.json file in the explorer directory:

{
  "dbPath": "chain.db",
  "network": "T",
  "privateKey": "your_krist_private_key_here",
  "unsafe": false
}

Configuration Options:

  • dbPath: Path to the SQLite database file (default: chain.db)
  • network: Network to operate on - "T" for testnet, "N" for mainnet
  • privateKey: Your Krist private key (required for sending messages)
  • unsafe: Set to true to disable error isolation (not recommended)
  • kristApiUrl: Optional custom Krist API URL
  • startFromTransaction: Optional transaction ID to start syncing from

Development

Start the development server:

pnpm dev

The explorer will be available at http://localhost:5173

Production Build

Build the application:

pnpm build

Start the production server:

pnpm start

Architecture

Tech Stack

  • React Router 7: Full-stack React framework with server-side rendering
  • Vite: Fast build tool and dev server
  • TypeScript: Type-safe development
  • Drizzle ORM: Type-safe database queries
  • @tmpim/noot: Core Noot client library

Project Structure

packages/explorer/
├── app/
│   ├── components/        # Reusable UI components
│   │   ├── Header.tsx     # Navigation header
│   │   ├── Footer.tsx     # Page footer
│   │   └── Layout.tsx     # Page layout wrapper
│   ├── lib/
│   │   ├── api.server.ts  # Server-side API functions
│   │   ├── format.ts      # Formatting utilities
│   │   └── noot-context.ts # Noot client singleton
│   ├── routes/            # Page routes
│   │   ├── home.tsx       # Dashboard
│   │   ├── transactions.tsx # Transaction list
│   │   ├── tokens.tsx     # Token list
│   │   ├── token-detail.tsx # Token details
│   │   └── send.tsx       # Message sender
│   ├── root.tsx           # Root layout
│   ├── routes.ts          # Route configuration
│   └── styles.css         # Global styles
├── config.json            # Noot client configuration
└── react-router.config.ts # React Router configuration

Pages

Dashboard (/)

Displays chain statistics and recent activity:

  • Total transactions and daily count
  • Token count
  • Recent transactions (last 10)
  • Recent tokens (last 5)

Transactions (/transactions)

Browse all transactions with:

  • Transaction hash
  • Operation type (Genesis, Create Token, Mint, Transfer, etc.)
  • From/To addresses
  • Amount
  • Timestamp

Tokens (/tokens)

View all tokens with:

  • Token ID
  • Name and symbol
  • Owner address
  • Total supply
  • Holder count

Token Details (/tokens/:id)

Detailed view of a specific token:

  • Token metadata
  • Total supply and holder count
  • Complete balance distribution table

Send Message (/send)

Create and send contract messages:

  • Operation selector: Choose from Genesis, Create Token, Mint, Transfer, etc.
  • Dynamic form fields: Form adapts based on selected operation
  • Preflight validation: Test messages before sending
  • Simulated state preview: See what the chain state will look like after the message
  • Network enforcement: Automatically uses the configured network

Contract Operations

The explorer supports all Noot contract operations:

  • Genesis (G): Initialize the chain
  • Create Token (CT): Create a new token
  • Mint Token (MT): Mint tokens to an address
  • Transfer Token (TT): Transfer tokens between addresses
  • Burn Token (BT): Burn tokens from circulation
  • Transfer Token Ownership (TTO): Transfer token ownership
  • Flag (F): Set a flag message

API Functions

Server-side API (app/lib/api.server.ts)

  • getStats(): Get chain statistics
  • getTransactions(limit, offset): Get paginated transactions
  • getTokens(limit, offset): Get paginated tokens
  • getToken(id): Get token details
  • preflightMessage(formData): Validate a message without sending
  • sendMessage(formData): Send a message to the blockchain

Network Filtering

The explorer automatically filters transactions based on the configured network:

  • Testnet ("T"): Only processes testnet messages
  • Mainnet ("N"): Only processes mainnet messages

Messages from other networks are silently ignored, ensuring clean separation between environments.

Preflight Validation

Before sending a message, you can use the preflight feature to:

  1. Validate the message structure
  2. Check if the operation will succeed
  3. Preview the simulated chain state after the message
  4. See token counts and balances

This helps catch errors before spending KST on failed transactions.

Styling

The explorer uses a modern, clean design with:

  • Dark theme optimized for readability
  • Responsive layout for mobile and desktop
  • Color-coded operation badges
  • Hover effects and transitions
  • Accessible form controls

Development Tips

Hot Module Replacement

The dev server supports HMR for fast iteration:

pnpm dev

Changes to routes, components, and styles will update instantly.

Type Safety

All routes are fully typed with React Router's type generation:

pnpm typegen

This generates types for loaders, actions, and route parameters.

Database Inspection

Inspect the SQLite database:

sqlite3 chain.db

Useful queries:

-- View recent transactions
SELECT * FROM krist_transactions ORDER BY id DESC LIMIT 10;

-- View all tokens
SELECT * FROM noots WHERE message_op = 'CT';

-- View chain state
SELECT * FROM chain_state ORDER BY id DESC LIMIT 1;

Troubleshooting

Port Already in Use

If port 5173 is in use:

pnpm dev --port 3000

Database Locked

If you get a "database is locked" error, ensure no other processes are using the database:

# Stop all dev servers
# Delete the database and restart
rm chain.db
pnpm dev

Network Mismatch

If you're seeing unexpected transactions, verify your config.json network setting matches your intent:

  • "T" for testnet
  • "N" for mainnet

Contributing

Contributions are welcome! Please ensure:

  • TypeScript types are correct
  • Code follows existing style
  • New features include appropriate error handling
  • UI changes maintain accessibility

License

MIT License - see the root LICENSE file for details.