Trixy Protocol - Backend

A Go-based backend server for Trixy Protocol, a prediction market platform built on Flow blockchain. This server provides REST API endpoints for managing markets, bets, protocols, and integrates with Flow blockchain for on-chain market creation.

🏗️ Architecture

Tech Stack

• Language: Go 1.25+
• Web Framework: Gin
• Database: PostgreSQL (with pgx driver)
• Blockchain: Flow (testnet/mainnet)
• Dependencies: See go.mod

Project Structure

backend/
├── main.go              # Server entry point
├── seed.go              # Database seeding
├── internal/            # Internal packages
│   ├── database/        # Database connection
│   ├── models/          # Data models
│   ├── handlers/        # HTTP handlers
│   ├── services/        # Business logic
│   └── utils/           # Utilities
├── migrations/          # SQL migrations
├── .env                 # Environment variables
├── Makefile            # Build commands
└── go.mod              # Go dependencies

🚀 Quick Start

Prerequisites

• Go 1.25 or higher
• PostgreSQL database
• Flow testnet account (optional, for blockchain features)

Installation

1. Clone and navigate to the backend directory

   cd backend

2. Install dependencies

   make install
   # or
   go mod download

3. Set up environment variables

   cp .env.example .env
   # Edit .env with your configuration

4. Run migrations

   psql $DATABASE_URL -f migrations/*.sql

5. Seed the database

   make seed
   # or
   go run . seed

6. Start the server

   make run
   # or
   go run .

📝 Environment Variables

See .env.example for all available configuration options:

Variable	Description	Default
DATABASE_URL	PostgreSQL connection string	Required
PORT	Server port	8080
FLOW_NETWORK	Flow blockchain network (testnet or mainnet)	testnet
TRIXY_PROTOCOL_ADDR	TrixyProtocol contract address	Required
FLOW_SIGNER_ADDRESS	Flow account address for transactions	Optional
FLOW_SIGNER_PRIVATE_KEY	Flow account private key	Optional
RUN_SEEDS	Run seeds on startup	false
SEED_FLOW_MARKETS	Create test markets on Flow	false

🛠️ Commands

Using Makefile

make run          # Run the server
make seed         # Seed the database
make build        # Build binary
make test         # Run tests
make clean        # Clean build artifacts
make install      # Install dependencies

Using Go directly

go run .          # Run server
go run . seed     # Seed database
go build          # Build binary
go test ./...     # Run tests

📡 API Endpoints

General

• GET /api/ - API info
• GET /api/health - Health check

Markets

• GET /api/markets - List all markets
• GET /api/markets/:id - Get market by ID
• GET /api/markets/:id/bets - Get bets for a market

Bets

• GET /api/bets - List all bets
• POST /api/bets - Place a bet
• GET /api/bets/:id - Get bet by ID
• GET /api/bets/user/:address - Get bets by user
• GET /api/bets/market/:market_id - Get bets by market
• GET /api/bets/stats/summary - Get betting statistics

Users

• GET /api/users/:address - Get user info
• GET /api/users/:address/bets - Get user's bets
• GET /api/users/:address/stats - Get user statistics

Protocols

• GET /api/protocols - List all protocols
• GET /api/protocols/:id - Get protocol by ID
• GET /api/protocols/address/:address - Get protocol by address

Flow Blockchain

• GET /api/flow/markets - Get Flow blockchain markets
• GET /api/flow/markets/:market_id - Get specific Flow market
• GET /api/flow/bets - Get Flow blockchain bets
• GET /api/flow/users/:address/stats - Get Flow user stats
• GET /api/flow/users/:address/markets/:market_id/bets - Get user's market bets

Blockchain Info

• GET /api/blockchain/info - Get blockchain information
• GET /api/blockchain/status - Get blockchain status
• GET /api/blockchain/latest-block - Get latest block

Charts

• GET /api/charts/market/:id - Get market chart data
• GET /api/charts/platform - Get platform chart data

Oracle

• GET /api/oracle/price/latest - Get latest price
• GET /api/oracle/price/history - Get price history
• GET /api/oracle/price/stats - Get price statistics
• GET /api/oracle/price/chart - Get price chart data

Stats

• GET /api/stats/platform - Get platform statistics
• GET /api/stats/leaderboard - Get leaderboard

🗄️ Database

Migrations

Migrations are located in migrations/ directory:

1. 001_initial_schema.sql - Base schema
2. 002_flow_prediction_markets.sql - Flow market tables
3. 003_prediction_markets.sql - Prediction market tables
4. 004_add_image_url.sql - Add image URL fields
5. 005_fix_flow_event_schemas.sql - Fix Flow event schemas
6. 006_prediction_markets_tables.sql - Additional market tables
7. 007_price_oracle.sql - Oracle price tables
8. 008_protocol_apy_snapshots.sql - Protocol APY tracking

Seeding

The seed command populates the database with initial data:

make seed

Seeded data includes:

• Protocols: Ankr, Increment, Figment (with updated icons)
• Markets (optional): Test prediction markets on Flow blockchain

🔧 Development

Project Structure Details

Handlers (internal/handlers/)

• HTTP request handlers
• Input validation
• Response formatting

Services (internal/services/)

• Business logic
• External API calls
• Blockchain interactions

Models (internal/models/)

• Data structures
• Type definitions

Database (internal/database/)

• Connection management
• Pool configuration

Utils (internal/utils/)

• Image utilities
• Helper functions

Adding New Endpoints

1. Create handler in internal/handlers/
2. Create service in internal/services/
3. Add route in main.go
4. Update this README

Code Style

• Follow standard Go conventions
• Use gofmt for formatting
• Run go vet before committing
• Write tests for new features

🧪 Testing

make test
# or
go test ./...

📦 Building

Development Build

make build

Production Build

go build -ldflags="-s -w" -o trixy-backend

🚢 Deployment

1. Set production environment variables
2. Run migrations
3. Build the binary
4. Start the server

export DATABASE_URL="postgresql://..."
export PORT=8080
export FLOW_NETWORK=testnet
./trixy-backend

🔐 Security

• Never commit .env files
• Use environment variables for secrets
• Keep FLOW_SIGNER_PRIVATE_KEY secure
• Enable HTTPS in production
• Validate all user inputs

📄 License

See LICENSE file for details.

🤝 Contributing

1. Fork the repository
2. Create your feature branch
3. Commit your changes
4. Push to the branch
5. Create a Pull Request

📞 Support

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