SEATrax - Shipping Invoice Funding Platform

🌊 Shipping Excellence Across Borders - Blockchain-based trade finance platform connecting exporters, investors, and administrators

📖 Table of Contents

Overview
Key Features
Technology Stack
Smart Contract
Getting Started
Environment Setup

🌊 Overview

SEATrax is a blockchain platform that revolutionizes trade finance by tokenizing shipping invoices as NFTs and enabling decentralized funding through investor pools. The platform provides a secure, transparent, and efficient way for exporters to access immediate liquidity while offering investors attractive returns on trade finance investments.

How It Works

Exporters submit shipping invoices and receive up to 70-100% advance funding
Investors browse curated invoice pools and invest to earn 4% returns
Admin verifies exporters, approves invoices, and manages investment pools
Smart Contracts automate fund distribution, payments, and profit sharing
Blockchain ensures transparency, immutability, and trust

✨ Key Features

For Exporters

✅ Invoice Tokenization: Convert shipping invoices into NFTs
✅ Instant Liquidity: Access funds when invoices reach 70% funding
✅ Document Storage: Secure IPFS-based document management via Pinata
✅ Real-time Tracking: Monitor funding progress and payment status
✅ Automatic Withdrawal: Seamless fund withdrawal to wallet

For Investors

✅ Curated Pools: Browse admin-verified investment opportunities
✅ Risk Assessment: View pool risk categories and invoice details
✅ Guaranteed Returns: Earn 4% yield on successful settlements
✅ Portfolio Tracking: Monitor active investments and claimed returns
✅ Transparent Metrics: Real-time pool performance analytics

For Administrators

✅ User Verification: Approve exporter applications with KYC data
✅ Invoice Review: Validate and approve submitted invoices
✅ Pool Creation: Curate invoice pools for investor funding
✅ Payment Confirmation: Verify importer payments via oracle
✅ Platform Analytics: Monitor platform-wide metrics and performance

Technical Features

✅ Unified Contract: Single SEATrax smart contract with all functionality
✅ Hybrid Sync System: Smart contract authority + Supabase metadata
✅ Responsive Design: Mobile-first UI with adaptive components
✅ Error Handling: Comprehensive error boundaries and recovery
✅ Security: Production-grade headers, env validation, role guards
✅ Real-time Conversion: USD ↔ ETH via CurrencyFreaks API

🔄 How It Works

Invoice Lifecycle

Exporter creates shipping invoice with documents
Admin verifies and approves invoice
Admin creates investment pool with approved invoices
Investors fund the pool with ETH
Exporter withdraws funds when pool reaches 70%+ funding
Importer pays invoice after shipment
Investors claim 4% returns after payment confirmation

Key Business Rules

70% Threshold: Exporters can withdraw when invoice is 70%+ funded
Auto-Distribution: Funds automatically distributed at 100% pool funding
Returns: 4% to investors, 1% platform fee
Minimum Investment: 1000 tokens per pool

Frontend

Framework: Next.js 15 with App Router
Language: TypeScript 5
Styling: Tailwind CSS 4
UI Components: shadcn/ui (Radix UI primitives)
Icons: Lucide React
State Management: React Hooks & Context

Blockchain

Network: Lisk Sepolia Testnet
Wallet Integration: Panna SDK (for users), MetaMask (for admin)
Smart Contract Interaction: Thirdweb SDK
Smart Contract: Unified SEATrax contract (all-in-one architecture)
- Repository: github.com/SEATrax/smart-contract
- Contract Address: 0x561D0d...1F233E
- Deployed: January 12, 2026
- Features: Role management, invoice NFTs, pool NFTs, investment tracking, payment oracle, platform analytics

Backend & Storage

Database: Supabase (PostgreSQL)
File Storage: Pinata (IPFS)
Currency API: CurrencyFreaks (USD ↔ ETH)

Development Tools

Package Manager: npm
Linting: ESLint
Type Checking: TypeScript Compiler
Build Tool: Next.js

🛠️ Technology Stack

Unified Architecture

SEATrax uses a single unified smart contract that handles all platform functionality:

Contract Address: 0x561D0d65160B6E57FAa6a0a9e9C05deCEB1F233E
Network: Lisk Sepolia Testnet
Deployed: January 12, 2026
Verified: ✅ Yes

Contract Features

Module	Functionality
Role Management	Admin, Exporter, Investor roles with access control
Invoice NFT	ERC-721 tokenization of shipping invoices
Pool NFT	ERC-721 tokenization of investment pools
Investment Tracking	On-chain record of investor contributions
Payment Oracle	Importer payment verification
Platform Analytics	Real-time metrics and statistics

Key Functions

// Invoice Management
createInvoice(company, importer, email, amount, loan, date, ipfsHash)
approveInvoice(invoiceId)
withdrawFunds(invoiceId)

// Pool Management
createPool(name, invoiceIds, startDate, endDate)
invest(poolId) payable
claimReturns(poolId)

// Payment & Distribution
markInvoicePaid(invoiceId)
distributeProfits(poolId)

� Getting Started

Prerequisites

Before starting, ensure you have:

✅ Node.js 18+ installed (Download)
✅ npm or yarn package manager
✅ Wallet (MetaMask or compatible EVM wallet)
✅ Lisk Sepolia ETH (Get from faucet)

Quick Setup (5 minutes)

1. Clone the Repository

git clone https://github.com/seatrax/apps.git
cd apps

2. Install Dependencies

npm install

3. Configure Environment Variables

cp .env.example .env.local

Edit .env.local with your configuration (see Environment Configuration section below).

4. Setup Supabase Database

Run the SQL migration in your Supabase SQL Editor:

cat supabase/migrations/*.sql | pbcopy  # Copy SQL
# Then paste in Supabase SQL Editor and run

Or use the migration script:

chmod +x scripts/apply-migrations.sh
./scripts/apply-migrations.sh

5. Start Development Server

npm run dev

Open http://localhost:3000 in your browser.

First Steps

Connect Wallet: Use MetaMask or compatible wallet
Get Test ETH: Get Lisk Sepolia ETH from faucet
Select Role: Choose Exporter, Investor, or Admin
Complete Onboarding: Fill required profile information
Start Using: Create invoices, invest in pools, or manage platform

� Project Structure

apps/
├── src/
│   ├── app/                      # Next.js App Router
│   │   ├── (auth)/login/         # Role selection & wallet connection
│   │   ├── onboarding/           # User registration flows
│   │   │   ├── exporter/         # Exporter onboarding
│   │   │   └── investor/         # Investor onboarding
│   │   ├── exporter/             # Exporter features (5 pages)
│   │   │   ├── page.tsx          # Dashboard
│   │   │   ├── invoices/         # Invoice management
│   │   │   │   ├── page.tsx      # Invoice list
│   │   │   │   ├── new/          # Create invoice
│   │   │   │   └── [id]/         # Invoice detail
│   │   │   └── payments/         # Payment tracking
│   │   ├── investor/             # Investor features (5 pages)
│   │   │   ├── page.tsx          # Dashboard
│   │   │   ├── pools/            # Pool browsing
│   │   │   │   ├── page.tsx      # Pool list
│   │   │   │   └── [id]/         # Pool detail & invest
│   │   │   ├── investments/      # Portfolio tracking
│   │   │   └── returns/          # Claim returns
│   │   ├── admin/                # Admin features (7 pages)
│   │   │   ├── page.tsx          # Dashboard
│   │   │   ├── roles/            # Role management
│   │   │   ├── invoices/         # Review invoices
│   │   │   │   └── [id]/         # Invoice review detail
│   │   │   ├── pools/            # Pool management
│   │   │   │   ├── new/          # Create pool (with autofill)
│   │   │   │   └── [id]/         # Pool detail
│   │   │   ├── payments/         # Payment confirmation
│   │   │   └── health/           # Data health monitor
│   │   ├── pay/[invoiceId]/      # Public payment page (importer)
│   │   └── api/                  # API routes
│   │       ├── currency/         # USD ↔ ETH conversion
│   │       └── payment/          # Payment processing
│   ├── components/
│   │   ├── ui/                   # shadcn/ui components (40+)
│   │   ├── common/               # Shared components
│   │   │   ├── Logo.tsx          # Brand logo (responsive)
│   │   │   ├── ErrorBoundary.tsx # Error handling
│   │   │   ├── ErrorMessage.tsx  # Error display
│   │   │   ├── Skeleton.tsx      # Loading states
│   │   │   ├── MobileNav.tsx     # Mobile navigation
│   │   │   └── ResponsiveTable.tsx
│   │   ├── invoice/              # Invoice components
│   │   └── pool/                 # Pool components
│   ├── hooks/                    # Custom React hooks
│   │   ├── useAccessControl.ts   # Role management
│   │   ├── useInvoiceNFT.ts      # Invoice operations
│   │   ├── usePoolNFT.ts         # Pool operations
│   │   ├── usePoolFunding.ts     # Investment logic
│   │   ├── usePaymentOracle.ts   # Payment verification
│   │   ├── usePlatformAnalytics.ts # Metrics
│   │   ├── useTransaction.ts     # Transaction management
│   │   ├── usePanna.ts           # Wallet connection
│   │   └── use-toast.tsx         # Toast notifications
│   ├── lib/
│   │   ├── contract.ts           # Contract ABIs & addresses
│   │   ├── currency.ts           # Currency conversion
│   │   ├── supabase.ts           # Database client
│   │   ├── pinata.ts             # IPFS upload
│   │   ├── env.ts                # Environment validation
│   │   └── utils.ts              # Utilities
│   ├── providers/                # Context providers
│   ├── config/                   # App configuration
│   └── types/                    # TypeScript types
├── supabase/
│   ├── migrations/               # Database migrations
│   └── config.toml               # Supabase config
├── public/                       # Static assets
│   ├── navbar.png                # Logo for navigation (720x183)
│   ├── logo.png                  # Logo for hero (767x363)
│   ├── icon.png                  # Square icon (840x848)
│   └── favicon.png               # Browser favicon (1200x1200)
├── scripts/                      # Utility scripts
│   ├── apply-migrations.sh       # Database setup
│   └── check-db.sh               # Verify database
├── .github/                      # Documentation
│   ├── copilot-instructions.md   # Development guidelines
│   ├── implementation-checklist.md # Feature tracking
│   ├── plan.md                   # Development roadmap
│   ├── PROJECT_STATUS.md         # Current status
│   └── business-process-documentation.md # Business logic
├── .env.local                    # Environment variables
├── package.json                  # Dependencies
├── next.config.ts                # Next.js config (security headers)
├── tailwind.config.ts            # Tailwind config
└── tsconfig.json                 # TypeScript config

⚙️ Environment Setup

Required Environment Variables

Create .env.local file with the following variables:

# ========================
# BLOCKCHAIN CONFIGURATION
# ========================

# Smart Contract Address (Unified SEATrax Contract)
# Deployed: January 12, 2026
# Source: https://github.com/seatrax/smart-contract
NEXT_PUBLIC_CONTRACT_ADDRESS="0x561D0d65160B6E57FAa6a0a9e9C05deCEB1F233E"

# Network Configuration
NEXT_PUBLIC_CHAIN_ID=4202
NEXT_PUBLIC_RPC_URL=https://rpc.sepolia-api.lisk.com

# ========================
# WALLET & AUTHENTICATION
# ========================

# Panna SDK (Wallet Provider)
# Sign up: https://panna.io/
NEXT_PUBLIC_PANNA_CLIENT_ID=your_panna_client_id
NEXT_PUBLIC_PANNA_PARTNER_ID=your_panna_partner_id

# ========================
# DATABASE & STORAGE
# ========================

# Supabase (PostgreSQL Database)
# Create project: https://supabase.com/
NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your_supabase_anon_key
SUPABASE_SERVICE_KEY=your_supabase_service_key

# Pinata (IPFS Storage)
# Sign up: https://pinata.cloud/
NEXT_PUBLIC_PINATA_GATEWAY=https://gateway.pinata.cloud
PINATA_JWT=your_pinata_jwt_token

# ========================
# EXTERNAL APIS
# ========================

# CurrencyFreaks (USD ↔ ETH Conversion)
# Get API key: https://currencyfreaks.com/
CURRENCY_FREAKS_API_KEY=your_currencyfreaks_api_key

# ========================
# PLATFORM CONFIGURATION
# ========================

# Admin Wallet Addresses (comma-separated, lowercase)
ADMIN_ADDRESSES=0xaddress1,0xaddress2,0xaddress3

# Platform Treasury Address
PLATFORM_TREASURY_ADDRESS=0xyour_treasury_address

# App Settings
NEXT_PUBLIC_APP_NAME=SEATrax
NEXT_PUBLIC_APP_URL=http://localhost:3000

How to Get API Keys

1. Supabase Setup

1. Go to https://supabase.com/ and create account
2. Create new project
3. Go to Settings → API
4. Copy "Project URL" → NEXT_PUBLIC_SUPABASE_URL
5. Copy "anon public" key → NEXT_PUBLIC_SUPABASE_ANON_KEY
6. Copy "service_role" key → SUPABASE_SERVICE_KEY
7. Run migrations (see Getting Started section)

2. Pinata IPFS Setup

1. Go to https://pinata.cloud/ and sign up
2. Go to API Keys → New Key
3. Enable "pinFileToIPFS" permission
4. Generate key
5. Copy JWT token → PINATA_JWT
6. Go to Gateways → Create Gateway
7. Copy gateway URL → NEXT_PUBLIC_PINATA_GATEWAY

3. CurrencyFreaks Setup

1. Go to https://currencyfreaks.com/
2. Sign up for free account
3. Get API key from dashboard
4. Copy API key → CURRENCY_FREAKS_API_KEY

4. Panna SDK Setup

1. Contact Panna team or use test credentials
2. Get Client ID and Partner ID
3. Copy to NEXT_PUBLIC_PANNA_CLIENT_ID and NEXT_PUBLIC_PANNA_PARTNER_ID

🛠️ Available Scripts

# Development
npm run dev          # Start dev server
npm run build        # Build for production
npm run start        # Start production server
npm run lint         # Run ESLint

# Database
./scripts/apply-migrations.sh   # Setup Supabase
./scripts/check-db.sh           # Verify database

# Deployment
npm run build        # Build application
vercel --prod        # Deploy to Vercel

� Documentation

Project Documentation

Located in .github/ folder:

copilot-instructions.md - Development guidelines, architecture patterns, coding conventions
implementation-checklist.md - Feature implementation tracking, completion status
plan.md - Development roadmap, priority tasks, timeline
PROJECT_STATUS.md - Comprehensive project status report, achievements, metrics
business-process-documentation.md - Business logic, process flows, smart contract integration

Smart Contract Documentation

Smart contracts are maintained in a separate repository:

Repository: https://github.com/seatrax/smart-contract
Contracts: AccessControl, InvoiceNFT, PoolNFT, PoolFundingManager, PaymentOracle, PlatformAnalytics
Network: Lisk Sepolia Testnet
Documentation: See smart-contract repository README

API Documentation

Currency Conversion

// GET /api/currency
// Returns current USD to ETH exchange rate
const response = await fetch('/api/currency');
const { rate, timestamp } = await response.json();

Payment Processing

// GET /api/payment/[invoiceId]
// Returns payment details for specific invoice
const response = await fetch(`/api/payment/${invoiceId}`);
const { invoice, amountDue, paymentLink } = await response.json();

Component Documentation

Common Components

ErrorBoundary: Catches React errors and displays fallback UI
ErrorMessage: Formats and displays blockchain error messages
Skeleton: Loading state placeholders (6 variants)
TransactionPending: Transaction progress indicators
MobileNav: Mobile navigation (hamburger + bottom tabs)
ResponsiveTable: Auto-converts tables to cards on mobile
Logo: Responsive brand logo (4 variants)

Custom Hooks

useSEATrax: Unified hook for all contract interactions (invoices, pools, investments, payments)
useAdminContract: Admin-specific operations using MetaMask (approve, create pool, distribute)
useMetaMaskAdmin: Admin wallet connection and network management
usePanna: User wallet connection and account management (Panna SDK)
useTransaction: Transaction state management
useExporterProfile: Exporter registration and profile
useInvestorProfile: Investor registration and profile

📄 License

This project is proprietary software developed for SEATrax platform.

🙏 Acknowledgments

Technologies

Next.js - React framework
TypeScript - Type safety
Tailwind CSS - Styling
shadcn/ui - UI components
Lisk - Blockchain platform
Supabase - Backend infrastructure
Pinata - IPFS storage
Thirdweb - Web3 development

Smart Contracts

Smart contract development and deployment managed separately at: https://github.com/seatrax/smart-contract

� Links

Contract Explorer: View on BlockScout
Lisk Sepolia Faucet: Get Test ETH
Network RPC: https://rpc.sepolia-api.lisk.com

Built with ❤️ by the SEATrax Team

🌊 Shipping Excellence Across Borders ⚓️

📄 License

MIT License

Name		Name	Last commit message	Last commit date
Latest commit History 86 Commits
.github		.github
.idea		.idea
contracts		contracts
deployments		deployments
docs		docs
public		public
scripts		scripts
src		src
supabase		supabase
test		test
.env.example		.env.example
.gitignore		.gitignore
.gitignore.hardhat		.gitignore.hardhat
.nvmrc		.nvmrc
README.md		README.md
check-admin-role.js		check-admin-role.js
check-invoice.js		check-invoice.js
check-tx.js		check-tx.js
eslint.config.mjs		eslint.config.mjs
hardhat.config.js		hardhat.config.js
next-env.d.ts		next-env.d.ts
next.config.ts		next.config.ts
package-lock.json		package-lock.json
package.json		package.json
postcss.config.mjs		postcss.config.mjs
tailwind.config.ts		tailwind.config.ts
test-get-invoice.js		test-get-invoice.js
test-register.js		test-register.js
test-thirdweb-return.js		test-thirdweb-return.js
tsconfig.json		tsconfig.json
tsconfig.tsbuildinfo		tsconfig.tsbuildinfo

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

SEATrax - Shipping Invoice Funding Platform

📖 Table of Contents

🌊 Overview

How It Works

✨ Key Features

For Exporters

For Investors

For Administrators

Technical Features

🔄 How It Works

Invoice Lifecycle

Key Business Rules

Frontend

Blockchain

Backend & Storage

Development Tools

🛠️ Technology Stack

Unified Architecture

Contract Features

Key Functions

� Getting Started

Prerequisites

Quick Setup (5 minutes)

1. Clone the Repository

2. Install Dependencies

3. Configure Environment Variables

4. Setup Supabase Database

5. Start Development Server

First Steps

� Project Structure

⚙️ Environment Setup

Required Environment Variables

How to Get API Keys

1. Supabase Setup

2. Pinata IPFS Setup

3. CurrencyFreaks Setup

4. Panna SDK Setup

🛠️ Available Scripts

� Documentation

Project Documentation

Smart Contract Documentation

API Documentation

Currency Conversion

Payment Processing

Component Documentation

Common Components

Custom Hooks

📄 License

🙏 Acknowledgments

Technologies

Smart Contracts

� Links

📄 License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages