Precious Metal Trading & NFT Platform

A full-stack decentralized application for trading physical gold and silver using USDC on Solana, with NFT receipts for ownership and a secondary marketplace.

🏗️ Architecture

• Frontend: Next.js 14 (App Router) + TypeScript + TailwindCSS
• Blockchain: Solana (Anchor framework)
• Database: PostgreSQL

📦 Project Structure

/
├── app/               # Next.js pages & API routes
│   ├── api/           # Backend API routes (TypeScript)
│   ├── dashboard/
│   ├── marketplace/
│   └── portfolio/
├── components/        # React components
├── lib/               # Utilities & services
│   ├── db.ts          # Database connection
│   ├── oracle.ts      # Price oracle
│   └── blockchain.ts  # Solana helpers
├── programs/          # Solana Anchor programs (Rust)
└── prisma/            # Database schema

🚀 Features

• Unified Trading Page: Mint new metals and browse marketplace in one place
• 4 Fixed Denominations: 1g Gold, 1oz Gold, 1oz Silver, 10oz Silver
• NFT Receipts: On-chain proof of ownership for purchased metals
• Integrated Marketplace: Buy from other users below the mint section
• Automated Fees: 3.5% platform fee on all transactions
• Secure PDA Vaults: All USDC stored in Solana PDAs
• Real-time Pricing: Live gold and silver prices via oracle

🛠️ Tech Stack

Frontend

• Next.js 14 with App Router
• TypeScript
• TailwindCSS + shadcn/ui
• Solana Wallet Adapter
• SWR for data fetching

Blockchain

• Anchor framework
• Solana programs for vault, NFT minting
• Metaplex for NFT metadata
• Pyth Network for price feeds

Database

• PostgreSQL
• Prisma ORM

📋 Prerequisites

• Node.js 18+
• PostgreSQL 14+
• Solana wallet (Phantom, Solflare, etc.)

🏃 Getting Started

1. Clone and Install

git clone <repo-url>
cd goldsilver
npm install

2. Set Up Environment

cp .env.example .env.local

Edit .env.local with your configuration. See .env.example for required variables.

3. Set Up Database

# Create database
createdb goldsilver

# Generate Prisma Client
npm run db:generate

# Push schema to database
npm run db:push

# Optional: Open Prisma Studio to view data
npm run db:studio

4. Start Development Server

npm run dev

Visit http://localhost:3000

🔑 Environment Variables

See .env.example for a complete list of required environment variables.

Key Variables:

• DATABASE_URL - PostgreSQL connection string
• NEXT_PUBLIC_SOLANA_NETWORK - Network (mainnet-beta recommended)
• NEXT_PUBLIC_SOLANA_RPC_URL - Your RPC endpoint (Helius, QuickNode, etc.)
• NEXT_PUBLIC_VAULT_PROGRAM_ID - Deployed vault program ID
• NEXT_PUBLIC_NFT_PROGRAM_ID - Deployed NFT program ID
• NEXT_PUBLIC_USDC_MINT - USDC mint address
• ORACLE_API_KEY - Metal price API key
• ADMIN_WALLET - Platform admin wallet

🎯 Metal Denominations

Gold

• 1 gram (1.0 gram)
• 1 troy ounce (31.1035 grams)

Silver

• 1 troy ounce (31.1035 grams)
• 10 troy ounces (311.035 grams)

💰 Fee Structure

• Primary Market: 3.5% fee on buy/sell transactions
• Secondary Market: 3.5% fee on marketplace trades
• All fees automatically routed to fee vault PDA

🔒 Security

• PDA-based USDC vault for secure fund custody
• Wallet signature verification on all transactions
• Price staleness checks (5-minute max)
• Rate limiting on API endpoints
• Admin controls for platform management

🏛️ Smart Contracts

The platform uses Solana programs written in Rust with the Anchor framework:

• Vault Program (856dDCHFkE3zTuri5PiHt1uV2cFBKPqokW7g3oVAHYaV) - Manages USDC custody
• NFT Mint Program (HMX6ht3VLNkxHRiBCs4z9KKXw7RGpnWNuExHLyh95aMm) - Mints/burns NFT receipts

Source code is available in the programs/ directory.

🔧 Available Scripts

npm run dev              # Start development server
npm run build            # Build for production
npm run start            # Start production server
npm run db:generate      # Generate Prisma client
npm run db:push          # Push schema to database
npm run db:studio        # Open Prisma Studio
npm run check:env        # Validate environment variables
npm run db:backup        # Backup database
npm run db:restore       # Restore database

📄 License

MIT

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📞 Support

For questions or issues, please open an issue on GitHub.