Global Finance Token

Global Finance Token is a full-stack platform for discovering, trading, and managing tokenized real-world assets (RWAs). It combines a React trading terminal, an Express indexing and verification API, PostgreSQL persistence, and regulated EVM tokens settled through smart contracts.

Features

• Tokenized RWA marketplace covering real estate, bonds, commodities, private equity, and infrastructure
• Portfolio dashboard, holdings, performance, and allocation views
• Buy, sell, limit-order, watchlist, and transaction workflows
• Liquidity pools and yield-income tracking
• Risk, benchmark, rebalancing, correlation, tax, and yield-calendar analytics
• KYC/compliance status and notification management
• ERC-20-compatible regulated asset tokens with T-REX-style identity and compliance registries
• Claim topics, trusted issuers, country allowlists, balance limits, pause, freeze, forced transfer, and wallet recovery
• Mock USDC marketplace settlement on local Hardhat and Polygon Amoy
• MetaMask and WalletConnect support through Wagmi and Viem
• Backend verification of marketplace events before a transaction updates PostgreSQL holdings
• Python/NumPy Monte Carlo forecasts with deterministic seeds and TypeScript fallback
• Go event indexer with Polygon confirmation tracking, reorg recovery, and PostgreSQL balance projections
• Dark and light themes with a terminal-inspired interface
• Simulated live asset prices over WebSocket

Technology

• React 19, Vite, TypeScript, Tailwind CSS, and shadcn/ui
• TanStack Query, Wouter, Recharts, and Framer Motion
• Node.js, Express 5, and WebSocket
• PostgreSQL, Drizzle ORM, and Zod
• Solidity 0.8.24, Hardhat, OpenZeppelin Contracts, Wagmi, and Viem
• Python 3.11+, FastAPI, NumPy, Pydantic, and Pytest
• Go 1.26, go-ethereum, and pgx
• OpenAPI and Orval-generated API clients
• pnpm workspaces

Repository structure

artifacts/
  analytics-python/ Python risk forecasting and financial analytics service
  indexer-go/       Polygon/Hardhat event indexer and PostgreSQL synchronizer
  blockchain/       Solidity contracts, tests, deployments, and admin scripts
  api-server/       Express API and price simulator
  rwa-platform/     Main React application
  mockup-sandbox/   UI mockup development sandbox
lib/
  api-client-react/ Generated React Query client exports
  api-spec/         OpenAPI specification and Orval configuration
  api-zod/          Generated validation schemas
  db/               Drizzle database schema and configuration
scripts/            Workspace utility scripts
docs/               Architecture and measured performance gates

Requirements

• Node.js 24 or later
• pnpm 10 or later
• PostgreSQL 16 or later
• Python 3.11 or later
• Go 1.26 or later
• MetaMask or another EIP-1193 wallet
• A WalletConnect Cloud project ID when WalletConnect QR login is required

Enable pnpm through Corepack if it is not installed:

corepack enable
corepack prepare pnpm@latest --activate

Installation

git clone <repository-url>
cd Global-Finance-Token
pnpm install

Create a PostgreSQL database, then set DATABASE_URL.

macOS/Linux:

export DATABASE_URL="postgresql://postgres:password@localhost:5432/global_finance_token"

Windows PowerShell:

$env:DATABASE_URL = "postgresql://postgres:password@localhost:5432/global_finance_token"

Create or update the database tables:

pnpm --filter @workspace/db run push

Python analytics service

Create the isolated Python environment:

Windows PowerShell:

cd artifacts/analytics-python
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -r requirements-dev.txt

macOS/Linux:

cd artifacts/analytics-python
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements-dev.txt

Start the service:

python -m uvicorn analytics_service.main:app --host 127.0.0.1 --port 8000

The Express endpoint GET /api/analytics/forecast calls this service. Query parameters are horizonDays, simulations, and seed. If Python is unavailable or exceeds the configured timeout, Express returns a fast analytical TypeScript fallback with engine: "typescript-fallback".

Run Python verification:

python -m pytest -q
python -m ruff check .
python -m benchmarks.forecast_benchmark

See performance gates before introducing further runtime services.

Go blockchain indexer

The Go service monitors confirmed local Hardhat or Polygon Amoy blocks, decodes marketplace and RWA-token events, and synchronizes canonical data with PostgreSQL. It stores raw on-chain events, maintains exact integer balances, confirms matching API transactions, and rolls back orphaned blocks during a chain reorganization.

Configure it from artifacts/indexer-go/.env.example, then run:

cd artifacts/indexer-go
go mod download
go test ./...
go run ./cmd/indexer

Use INDEXER_CONFIRMATIONS=0 for local Hardhat. For Polygon Amoy, use chain ID 80002, its deployment file, and a conservative confirmation depth such as 20. Health and synchronization lag are available at http://127.0.0.1:8081/healthz.

See the indexer guide for its full configuration and data model.

Running the complete local blockchain stack

Start the persistent Hardhat network in the first terminal:

pnpm --filter @workspace/blockchain run node

Deploy all registries, four RWA tokens, mock USDC, compliance modules, and the marketplace in a second terminal:

pnpm --filter @workspace/blockchain run deploy:local

Deployment addresses are written to:

• artifacts/blockchain/deployments/31337.json
• artifacts/rwa-platform/public/contracts/31337.json

The deployment registers the first ten Hardhat accounts as development investors and gives accounts 2–10 mock USDC. Import one of the private keys printed by hardhat node into MetaMask. These keys are public development keys and must never receive real funds.

Add the local network to MetaMask:

Field	Value
Network name	Hardhat Local
RPC URL	http://127.0.0.1:8545
Chain ID	31337
Currency symbol	ETH

Create the database tables or update their blockchain columns:

pnpm --filter @workspace/db run push

Run the API in a third terminal:

macOS/Linux:

PORT=3001 pnpm --filter @workspace/api-server run build
PORT=3001 pnpm --filter @workspace/api-server run start

Windows PowerShell:

$env:PORT = "3001"
pnpm --filter @workspace/api-server run build
pnpm --filter @workspace/api-server run start

Run the frontend in a fourth terminal:

pnpm --filter @workspace/rwa-platform run dev

Open http://localhost:3000. Vite proxies /api and WebSocket traffic to http://127.0.0.1:3001.

Copy artifacts/rwa-platform/.env.example to .env in that directory and set VITE_WALLETCONNECT_PROJECT_ID to enable WalletConnect. MetaMask works without a WalletConnect project ID.

The frontend uses these optional environment variables:

Variable	Default	Purpose
PORT	3000	Frontend development port
BASE_PATH	/	Vite application base path
VITE_API_TARGET	http://127.0.0.1:3001	API proxy target
VITE_LOCAL_RPC_URL	http://127.0.0.1:8545	Local Hardhat RPC
VITE_AMOY_RPC_URL	Polygon public RPC	Polygon Amoy RPC
VITE_WALLETCONNECT_PROJECT_ID	Empty	WalletConnect Cloud project identifier

The API uses:

Variable	Default	Purpose
PORT	3001	API server port
DATABASE_URL	Required	PostgreSQL connection string
LOG_LEVEL	info	Server logging level
LOCAL_RPC_URL	http://127.0.0.1:8545	Receipt-verification RPC
AMOY_RPC_URL	Polygon public RPC	Polygon Amoy verification RPC
BLOCKCHAIN_DEPLOYMENTS_DIR	Auto-detected	Directory containing chain deployment JSON
ANALYTICS_SERVICE_URL	http://127.0.0.1:8000	Python analytics service
ANALYTICS_TIMEOUT_MS	2000	Timeout before TypeScript fallback

Polygon Amoy deployment

Copy artifacts/blockchain/.env.example to .env in that directory, fund the deployer with Amoy POL, and set DEPLOYER_PRIVATE_KEY. Never commit that file.

pnpm --filter @workspace/blockchain run deploy:amoy

The deployment writes 80002.json for both the API and frontend. Register an approved investor after KYC:

macOS/Linux:

INVESTOR_WALLET=0x... COUNTRY_CODE=840 pnpm --filter @workspace/blockchain run register:amoy

Windows PowerShell:

$env:INVESTOR_WALLET = "0x..."
$env:COUNTRY_CODE = "840"
pnpm --filter @workspace/blockchain run register:amoy

COUNTRY_CODE uses the ISO 3166-1 numeric code. The development deployer is the identity issuer, registry agent, token agent, minter, compliance owner, and marketplace owner. Move these roles to separate multisig-controlled accounts before any production deployment.

Development commands

# Type-check the entire workspace
pnpm run typecheck

# Type-check and build all packages
pnpm run build

# Compile and test smart contracts
pnpm --filter @workspace/blockchain run build
pnpm --filter @workspace/blockchain run test

# Test the Go chain indexer
cd artifacts/indexer-go && go test ./...

# Regenerate API clients and validation schemas
pnpm --filter @workspace/api-spec run codegen

# Push schema changes to the development database
pnpm --filter @workspace/db run push

# Run the UI mockup sandbox (http://localhost:3002)
pnpm --filter @workspace/mockup-sandbox run dev

After API code generation, verify that lib/api-zod/src/index.ts contains only:

export * from "./generated/api";

Production build

pnpm run build

Build artifacts are written to:

• artifacts/rwa-platform/dist/public
• artifacts/api-server/dist

Set production environment variables in your hosting platform, serve the frontend build with a static web server, and route /api plus WebSocket connections to the API service.

Security status

The contracts are a development implementation of the selected T-REX-style architecture. They have automated tests but have not received an independent smart-contract audit, formal verification, legal review, or production key-management review. Do not deploy them with real assets or investor funds until those reviews are complete.

License

MIT