Skip to content

quick-start.md

Latest commit

 

History

History
369 lines (257 loc) · 8.04 KB

quick-start.md

File metadata and controls

369 lines (257 loc) · 8.04 KB
Raw
id quick-start
title Quick Start - Try the Web App
sidebar_label Quick Start
sidebar_position 1

Quick Start - Try the Mass Payout App

Quick start guide to run the Mass Payout application for managing large-scale payment distributions.

Prerequisites

  • Node.js: v24.0.0 or newer (for backend)
  • npm: v10.9.0 or newer
  • Docker: For PostgreSQL database (or install PostgreSQL 12+ manually)
  • Hedera Account: Testnet or mainnet account with HBAR

Installation

1. Clone the Repository

git clone https://github.com/hashgraph/asset-tokenization-studio.git
cd asset-tokenization-studio

2. Setup Mass Payout

You have two options:

Option A: Quick Setup (Recommended)

Run this single command from the monorepo root to install dependencies and build everything:

npm run mass-payout:setup

This will automatically install dependencies, build contracts, SDK, backend, and frontend.

Option B: Manual Setup

If you prefer to run each step manually:

# Install dependencies
npm ci

# Build contracts and SDKs
npm run mass-payout:contracts:build
npm run mass-payout:sdk:build
npm run mass-payout:backend:build
npm run mass-payout:frontend:build

3. Setup PostgreSQL Database

Option 1: Using Docker (Recommended)

Start PostgreSQL using the included docker-compose:

cd apps/mass-payout/backend
docker-compose up -d
cd ../../..

This will start PostgreSQL on port 5432 with default credentials (postgres/postgres).

Option 2: Manual PostgreSQL Installation

If you have PostgreSQL installed:

# Connect to PostgreSQL
psql -U postgres

# Create database
CREATE DATABASE mass_payout;

Configuration

Backend Configuration

Create Environment File

cd apps/mass-payout/backend
cp .env.example .env

Configure Environment Variables

Edit apps/mass-payout/backend/.env:

Database Configuration

If you're using Docker (from Step 2), use these default values:

# PostgreSQL Connection (Docker defaults)
DATABASE_HOST=localhost
DATABASE_PORT=5432
DATABASE_USERNAME=postgres
DATABASE_PASSWORD=postgres
DATABASE_NAME=postgres
DATABASE_SCHEMA=public
DATABASE_SYNCHRONIZE=true  # Set to false in production

If you created a custom database, adjust DATABASE_NAME accordingly.

Blockchain Configuration
# Mirror Node and Contract ID
BLOCKCHAIN_MIRROR_NODE_URL=https://testnet.mirrornode.hedera.com
BLOCKCHAIN_CONTRACT_ID=0.0.429274
BLOCKCHAIN_TOKEN_DECIMALS=6
BLOCKCHAIN_LISTENER_POLL_TIMEOUT=10000
BLOCKCHAIN_LISTENER_START_TIMESTAMP=2025-08-26T00:00:00.000Z
Asset Tokenization Studio (ATS) Integration
# ATS Network Configuration
ATS_NETWORK=testnet
ATS_MIRROR_URL=https://testnet.mirrornode.hedera.com/api/v1/
ATS_RPC_URL=https://testnet.hashio.io/api

# ATS Contract Addresses
ATS_FACTORY_ADDRESS=0.0.123456
ATS_RESOLVER_ADDRESS=0.0.123457

# Payment Token (USDC)
HEDERA_USDC_ADDRESS=0.0.429274
DFNS Custodial Wallet (Required)

The backend uses DFNS for secure transaction signing. Configure your DFNS wallet:

# Service Account Authentication
DFNS_SERVICE_ACCOUNT_AUTHORIZATION_TOKEN=your_dfns_service_account_token_here
DFNS_SERVICE_ACCOUNT_CREDENTIAL_ID=cr-xxxxx-xxxxx-xxxxxxxxxxxxxxxxx
DFNS_SERVICE_ACCOUNT_PRIVATE_KEY_OR_PATH="-----BEGIN EC PRIVATE KEY-----
your_private_key_here
-----END EC PRIVATE KEY-----"

# DFNS Application Settings
DFNS_APP_ID=ap-xxxxx-xxxxx-xxxxxxxxxxxxxxxxx
DFNS_APP_ORIGIN=http://localhost:3000
DFNS_BASE_URL=https://api.dfns.ninja

# DFNS Wallet Configuration
DFNS_WALLET_ID=wa-xxxxx-xxxxx-xxxxxxxxxxxxxxxxx
DFNS_WALLET_PUBLIC_KEY=your_wallet_public_key_here
DFNS_HEDERA_ACCOUNT_ID=0.0.123456

:::info To obtain DFNS credentials:

  1. Create an account at DFNS
  2. Set up a service account for API access
  3. Create a Hedera wallet in your DFNS dashboard
  4. Copy the credentials to your .env file :::
Application Settings
# Server Port
PORT=3000

# API Prefix
API_PREFIX=api

# CORS Origins (comma-separated list of allowed origins)
CORS_ORIGINS=http://localhost:5173,http://localhost:3000

Frontend Configuration

Create Environment File

cd apps/mass-payout/frontend
cp .env.example .env

Configure Environment Variables

Edit apps/mass-payout/frontend/.env:

# Backend API URL
VITE_API_URL=http://localhost:3000

# Frontend Port (optional)
VITE_PORT=5173

Running the Application

Important: Ensure PostgreSQL is running via Docker Compose (see step 3) or your local PostgreSQL installation before starting the backend.

1. Start the Backend

The backend must be started from its own directory to properly load environment variables:

cd apps/mass-payout/backend
npm run start:dev

The backend API will be available at http://localhost:3000

Note: The backend loads the .env file from its current working directory, so it must be run from apps/mass-payout/backend/.

2. Start the Frontend

In a new terminal, from the monorepo root:

npm run mass-payout:frontend:dev

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

Tip: Keep both terminals open to see logs from each service.

First Steps

1. Import an Asset

  • Click "Import Asset" in the dashboard
  • Enter the token contract ID from ATS
  • The system will sync token holders and balances

2. Create a Distribution

  • Select an imported asset
  • Click "New Distribution"
  • Choose distribution type (dividend, coupon payment)
  • Set amount and payment token
  • Configure distribution parameters

3. Execute Payout

  • Review distribution details
  • Click "Execute Payout"
  • The system will process batch payments to all holders
  • Monitor transaction status in real-time

4. View History

  • Check distribution history
  • View payout details and transaction records
  • Track failed payments and retry if needed

Troubleshooting

Database Connection Failed

# Verify PostgreSQL is running
sudo systemctl status postgresql

# Test connection
psql -U postgres -d mass_payout

# Check credentials in .env
DATABASE_USERNAME=postgres
DATABASE_PASSWORD=your_correct_password

Port Already in Use

# Kill process on backend port
lsof -ti:3000 | xargs kill -9

# Kill process on frontend port
lsof -ti:5173 | xargs kill -9

Docker Database Issues

# Check if PostgreSQL container is running
docker ps

# View PostgreSQL logs
cd apps/mass-payout/backend
docker-compose logs -f

# Restart PostgreSQL container
docker-compose restart

# Stop and remove container
docker-compose down

Build Errors

# Clean and rebuild
npm run mass-payout:clean
npm run mass-payout:build

Contract Interaction Errors

  • Verify operator account has sufficient HBAR balance
  • Check that contract IDs are correct for your network
  • Ensure operator private key is valid
  • Verify the LifeCycle Cash Flow contract is deployed

Migration Errors

Database migrations run automatically. If you encounter issues:

# Rebuild database (WARNING: This deletes all data)
# In PostgreSQL:
DROP DATABASE mass_payout;
CREATE DATABASE mass_payout;

# Restart backend to run migrations
npm run mass-payout:backend:dev

Production Deployment

Important Settings for Production

# Backend .env
DATABASE_SYNCHRONIZE=false  # Never use sync in production
NODE_ENV=production

# Use connection pooling
DATABASE_POOL_SIZE=10

Security Considerations

  • Store private keys securely (use secrets manager)
  • Enable HTTPS for both frontend and backend
  • Restrict CORS origins to your domain only
  • Use strong database passwords
  • Implement rate limiting on API endpoints

Next Steps

Need Help?