🌐 STO Web Client

Part of the ODW ASSETTECH Legacy RWA / STO Reference Stack

⚡ About This Repository

This is the STO Web Client: a Next.js-based web application that exposes STO and RWA interactions to end-users. It handles wallet connection, role-aware views (admin / whitelisted / non-whitelisted), token issuance and redemption flows, and on-chain document and account management, integrating directly with the ERC-1400 contracts and the backend API.

Back in 2024, the ODW Team built a full Security Token Offering (STO) solution using the ERC‑1400 token standard on a private EVM chain running ConsenSys Quorum. Since then, the ecosystem has evolved: Quorum is no longer actively supported by ConsenSys (with Hyperledger Besu recommended as the successor), and STOs are now more commonly framed under the broader Real‑World Assets (RWA) narrative.

On the token side, ERC‑3643 (T‑REX) and ERC‑1155 have emerged as the most commonly used standards for regulated STO/RWA projects, with ERC‑3643 gaining prominence for its advanced, on‑chain compliance (DID, KYC/AML, transfer restrictions), and ERC‑1155 enabling efficient multi‑asset, multi‑class tokenization.

We are open‑sourcing this repository as a reference implementation to share architecture, design patterns, and integration approaches around ERC‑1400‑based STOs on permissioned EVM chains.

Important: This repository is not intended for production use. A production‑grade RWA/STO system today should:

• Migrate from Quorum → Hyperledger Besu (or another actively maintained EVM execution client), and
• Refactor token logic from ERC‑1400 → ERC‑3643 and/or ERC‑1155, with modern compliance and identity tooling.

---

📚 Repository Series

This repository is part of the ODW ASSETTECH legacy RWA collection:

1. ERC1400 Token Dashboard (Frontend Dashboard)
2. STO Backend API (Express.js API with JWT, Wallet Auth)
3. STO Web Client ← You are here (Next.js Web Interface)
4. ERC1400 Smart Contracts (Solidity Implementation)

Each repository can be explored independently, but together they form a complete STO platform architecture.

---

🎯 Overview

This is the web client application for the Security Token Offering platform built with Next.js. It provides a comprehensive user interface for token issuance, redemption, transfer, document management, and account administration.

Key Features

• Wallet Connection: Connect via Web3Modal (MetaMask, WalletConnect, etc.)
• Role-Based Access: Different views for Admin, Whitelisted, and Non-Whitelisted users
• Token Operations: Issue, redeem, and transfer tokens
• Document Management: Store and retrieve documents on-chain
• Account Management: Admin tools for whitelisting/removing accounts
• Responsive Design: Works on desktop and mobile devices

🛠️ Architecture

Tech Stack

• Framework: Next.js 13.1.2
• Frontend: React 18
• Web3: Wagmi v0.11.2, Ethers.js v5.7.2
• Wallet Integration: Web3Modal v2.0.0
• Language: TypeScript
• Styling: CSS

Project Structure

sto-web-client/
├── src/
│   ├── components/          # React components
│   │   ├── documents/       # Document management components
│   │   ├── requests/        # User sign-in/sign-up components
│   │   └── token/           # Token operation components
│   ├── config/              # Configuration files
│   │   └── customChains.tsx # Custom blockchain configuration
│   ├── data/                # Contract ABIs and definitions
│   ├── interfaces/          # TypeScript interfaces
│   ├── lib/                 # Utility libraries
│   │   ├── abi/            # Contract ABIs
│   │   ├── hooks/          # Custom React hooks
│   │   ├── utils/         # Utility functions
│   │   └── constants.ts   # Application constants
│   ├── pages/              # Next.js pages
│   │   ├── admin/         # Admin pages
│   │   └── *.tsx          # Route pages
│   └── styles.css         # Global styles
├── public/                # Static assets
├── .eslintrc.js          # ESLint configuration
├── .prettierrc.js        # Prettier configuration
├── next.config.js        # Next.js configuration
├── package.json          # Dependencies and scripts
└── tsconfig.json         # TypeScript configuration

Key Components

1. Web3Provider Setup (src/pages/_app.tsx)

   • Configures Wagmi client and Web3Modal
   • Handles network switching
   • Provides Web3 context to all pages

2. Custom Hooks (src/lib/hooks/)

   • useContractTransaction: Unified transaction handling
   • Provides consistent loading states and error handling

3. Utility Functions (src/lib/utils/)

   • errorHandler.ts: Centralized error logging and formatting
   • validation.ts: Input validation utilities

4. Constants (src/lib/constants.ts)

   • Contract addresses
   • Default gas limits
   • Environment variable validation

🚀 Getting Started

Prerequisites

• Node.js: Version 14.0.9 or higher (16.x or 18.x recommended)
• Package Manager: Yarn or npm
• Blockchain: Access to a Quorum network or compatible Ethereum network
• Wallet: MetaMask or compatible Web3 wallet

Installation

1. Clone the repository

   git clone https://github.com/OnDemandWorld/sto-web-client.git
   cd sto-web-client

2. Install dependencies

   yarn install
   # or
   npm install

3. Set up environment variables

   Copy .env.example to .env.local and fill in the required values:

   cp .env.example .env.local

   See Environment Variables for details.

4. Start the development server

   yarn dev
   # or
   npm run dev

5. Open your browser

   Navigate to http://localhost:3000 (or the port shown in the terminal)

⚙️ Configuration

Next.js Configuration

The application is configured in next.config.js:

• Transpilation: Web3Modal packages are transpiled for compatibility
• TypeScript: Build errors are ignored (should be fixed in production)
• ESLint: Build-time linting is disabled (should be enabled in production)

TypeScript Configuration

TypeScript is configured in tsconfig.json:

• Strict Mode: Currently disabled (should be enabled for production)
• JSX: Preserved for Next.js
• Module Resolution: Node.js style

Blockchain Configuration

Custom chain configuration is in src/config/customChains.tsx:

• Configured for Quorum networks
• Supports custom RPC URLs and chain IDs
• Environment-based configuration

🔧 Environment Variables

Create a .env.local file in the root directory with the following variables:

Required Variables

# WalletConnect Project ID
# Get your project ID at https://cloud.walletconnect.com
NEXT_PUBLIC_PROJECT_ID=your_walletconnect_project_id

# Blockchain Configuration
NEXT_PUBLIC_CHAIN_ID=1337
NEXT_PUBLIC_RPC_URL=http://localhost:8545
NEXT_PUBLIC_BLOCK_EXPLORER=http://localhost:26000
NEXT_PUBLIC_QUORUM_CHAIN=Quorum Dev

# Contract Addresses
# These should be set after deploying your contracts
NEXT_PUBLIC_TOKENS_CONTRACT_ADDRESS=0x0000000000000000000000000000000000000000
NEXT_PUBLIC_TOKENS_VALIDATOR_CONTRACT_ADDRESS=0x0000000000000000000000000000000000000000

Variable Descriptions

Variable	Description	Example
NEXT_PUBLIC_PROJECT_ID	WalletConnect Cloud project ID	abc123def456...
NEXT_PUBLIC_CHAIN_ID	Network chain ID	1337 (local), 1 (mainnet)
NEXT_PUBLIC_RPC_URL	RPC endpoint URL	http://localhost:8545
NEXT_PUBLIC_BLOCK_EXPLORER	Block explorer URL	http://localhost:26000
NEXT_PUBLIC_QUORUM_CHAIN	Chain display name	Quorum Dev
NEXT_PUBLIC_TOKENS_CONTRACT_ADDRESS	ERC1400 token contract address	0x...
NEXT_PUBLIC_TOKENS_VALIDATOR_CONTRACT_ADDRESS	Validator contract address	0x...

📝 Scripts

Development

# Start development server
yarn dev
# or
npm run dev

Production

# Build for production
yarn build
# or
npm run build

# Start production server (runs on port 5000)
yarn start
# or
npm start

Code Quality

# Run ESLint
yarn lint
# or
npm run lint

# Format code with Prettier
yarn format
# or
npm run format

Other Scripts

# Link contracts (if using symlinks)
yarn link-contracts

🚢 Deployment

Build Process

1. Set environment variables in your deployment platform

2. Build the application:

   yarn build

3. Start the production server:

   yarn start

Deployment Platforms

Vercel (Recommended for Next.js)

1. Connect your repository to Vercel
2. Set environment variables in Vercel dashboard
3. Deploy automatically on push to main branch

Docker

Create a Dockerfile:

FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN yarn install
COPY . .
RUN yarn build
EXPOSE 5000
CMD ["yarn", "start"]

Traditional Server

1. Build the application: yarn build
2. Copy the .next folder and package.json to the server
3. Install production dependencies: yarn install --production
4. Start with PM2 or similar: yarn start

Environment-Specific Configuration

• Development: Use .env.local for local development
• Staging: Set environment variables in your staging platform
• Production: Use secure environment variable management

🐛 Troubleshooting

Common Issues

1. "Failed to load web3" Error

Problem: Wallet not connected or network mismatch

Solution:

• Ensure MetaMask or another wallet is installed
• Check that you're on the correct network
• Verify NEXT_PUBLIC_CHAIN_ID matches your network

2. "Invalid address" Errors

Problem: Invalid Ethereum address format

Solution:

• Ensure addresses start with 0x and are 42 characters long
• Use checksummed addresses when possible

3. Transaction Failures

Problem: Transactions failing to execute

Solution:

• Check wallet has sufficient balance for gas
• Verify contract addresses are correct
• Ensure user has required permissions (admin, whitelisted, etc.)
• Check network connectivity

4. Build Errors

Problem: TypeScript or ESLint errors during build

Solution:

• Run yarn lint to see specific errors
• Fix TypeScript errors or temporarily disable strict mode
• Ensure all environment variables are set

5. Network Switching Issues

Problem: App doesn't switch to required network

Solution:

• Ensure NEXT_PUBLIC_CHAIN_ID is correct
• Check RPC URL is accessible
• Verify network is added to wallet

Debug Mode

Enable debug logging by setting:

NODE_ENV=development

🤝 Contributing

Development Workflow

1. Fork the repository

2. Create a feature branch

   git checkout -b feature/your-feature-name

3. Make your changes

4. Run linting and formatting

   yarn lint
   yarn format

5. Test your changes

   • Test in development mode
   • Verify all functionality works
   • Check for console errors

6. Commit your changes

   git commit -m "feat: add your feature description"

7. Push and create a Pull Request

Code Style

• TypeScript: Use TypeScript for all new code
• Formatting: Use Prettier (configured in .prettierrc.js)
• Linting: Follow ESLint rules (configured in .eslintrc.js)
• Naming: Use camelCase for variables, PascalCase for components
• Comments: Add JSDoc comments for functions and components

Commit Messages

Follow conventional commits:

• feat: New feature
• fix: Bug fix
• docs: Documentation changes
• style: Code style changes
• refactor: Code refactoring
• test: Test additions/changes
• chore: Maintenance tasks

📄 License

MIT

---

🌟 Support & Community

If this repository is useful to you as a reference for STO/RWA design, please consider:

• Giving the project a ⭐ star on GitHub
• Watching the repo to follow updates
• Opening issues for questions, ideas, or problems you hit
• Submitting pull requests with improvements or fixes

Your feedback and contributions help us decide how much more to invest in evolving these open‑source building blocks.

---

💼 Work with the ODW Team

ODW ASSETTECH specializes in:

• RWA / STO architecture & solution design
• Web development - User interfaces for blockchain applications
• Smart contract engineering (ERC‑3643, ERC‑1155, custom compliance modules)
• Migration of legacy ERC‑1400 / Quorum stacks to Hyperledger Besu and modern standards
• Backend & frontend integration (wallet flows, KYC/AML, dashboards, ops tooling)
• Regulated environments: focusing on compliance‑aware tokenization flows

If you are:

• A financial institution or issuer exploring tokenization,
• A startup building an RWA platform, or
• An engineering team looking to modernize an existing STO stack,

we'd be happy to discuss how we can help.

📧 Contact the ODW Team

• Email: office@odw.ai
• Contact Page: https://ondemandworld.com/contact-us/
• GitHub Issues: Report bugs and request features
• GitHub Discussions: Ask questions and share ideas

---

🔗 Related Repositories in This Series

• ERC1400 Token Dashboard – Next.js dashboard UI for managing ERC‑1400 tokens
• STO Backend API – TypeScript/Express backend for auth, users, and wallet integration
• STO Web Client – Next.js web client for end‑user STO workflows
• ERC1400 Smart Contracts – Solidity implementation of ERC‑1400 and related extensions

This repository is one component of a 4‑repo reference stack. For a fuller picture, explore the other repos in the ODW ASSETTECH organization.

---

Made by the ODW Team – sharing our 2024 STO stack as a reference for today's RWA builders.