Pacto P2P

A decentralized OTC (Over-The-Counter) platform for Stellar stablecoins

Enabling peer-to-peer trading of CRCX, MXNX, and USDC using regional payment rails like SINPE and SPEI.

---

🌟 Overview

Pacto P2P is a non-custodial trading platform that connects buyers and sellers of Stellar stablecoins through secure, blockchain-backed escrows. Every trade is secured by Trustless Work smart contracts on the Stellar blockchain, ensuring transparency and security without requiring a trusted intermediary.

Key Features

• 🔒 Non-Custodial Trading: Your funds are secured by smart contracts, not held by us
• 🌍 Borderless Payments: Trade using regional payment methods (SINPE, SPEI, etc.)
• ⚡ Fast Settlements: Stellar blockchain enables near-instant transactions
• 🛡️ Dispute Resolution: Built-in dispute system for trade conflicts
• 💼 Merchant Profiles: Verified merchant accounts with public profiles
• 📊 Real-time Tracking: Live status updates for trades and escrows

Supported Assets

• CRCX - Costa Rican Colón Token
• MXNX - Mexican Peso Token
• USDC - USD Coin (Global, various payment methods)

🚀 Quick Start

Prerequisites

• Node.js 18+
• npm 9+

Installation

# Clone the repository
git clone https://github.com/your-username/pacto-p2p.git
cd pacto-p2p

# Install all dependencies
npm install

# Build all packages
npm run build

# Start development server
npm run dev

The application will be available at http://localhost:3000

Environment Setup

Create a .env.local file in apps/web with the following variables:

# Stellar & Trustless Work
NEXT_PUBLIC_TLW_API_KEY=your_trustless_work_api_key
NEXT_PUBLIC_ROLE_ADDRESS=your_stellar_role_address
NEXT_PUBLIC_PLATFORM_FEE=0.01

# Supabase
NEXT_PUBLIC_SUPABASE_URL=your_supabase_url
NEXT_PUBLIC_SUPABASE_ANON_KEY=your_supabase_anon_key

# Optional: Mock Mode
NEXT_PUBLIC_USE_MOCK=0

🏗️ Architecture

Monorepo Structure

pacto-p2p/
├── apps/
│   └── web/                 # Next.js web application
│       ├── app/             # Next.js App Router pages
│       ├── components/      # React components
│       ├── hooks/           # Custom React hooks
│       ├── lib/             # Utilities and services
│       └── providers/       # React context providers
│
├── packages/
│   ├── shared/              # Shared utilities and services
│   ├── ui/                  # Reusable UI components (Radix UI)
│   ├── types/               # TypeScript type definitions
│   └── config/              # Configuration and scripts
│
├── docs/                    # Documentation
│   ├── DEVELOPMENT.md       # Development guide
│   └── DATABASE_SCHEMA.md   # Database schema
│
├── scripts/                 # Utility scripts
├── CONTRIBUTING.md          # Contribution guidelines
└── README.md                # This file

Technology Stack

• Frontend: Next.js 15, React 19, TypeScript
• Styling: TailwindCSS, Shadcn UI, Radix UI
• State Management: Zustand, TanStack Query
• Blockchain: Stellar, Trustless Work
• Database: Supabase (PostgreSQL)
• Code Quality: Biome, TypeScript
• Build System: Turborepo, npm workspaces

📦 Workspaces

Apps

• apps/web - Main Next.js web application
  • Dashboard for managing listings, escrows, and trades
  • Stellar wallet integration via Trustless Work
  • Supabase backend integration
  • Merchant profiles and public pages

Packages

• packages/shared - Common utilities and services

  • Database services (Supabase client)
  • Stellar wallet utilities
  • State management (Zustand stores)
  • Validation schemas (Zod)

• packages/ui - Reusable UI components

  • Radix UI primitives
  • Custom themed components
  • Form components
  • Layout components

• packages/types - TypeScript type definitions

  • Escrow types
  • API response types
  • Database schema types

• packages/config - Configuration and scripts

  • Database initialization scripts
  • Environment configurations
  • Build configurations

🎯 Usage

Connecting Your Wallet

1. Click "Sign In" on the homepage
2. Choose your preferred Stellar wallet (Freighter, WalletConnect, etc.)
3. Approve the connection in your wallet
4. You'll be redirected to the dashboard

Creating a Listing

1. Navigate to "Listings" in the dashboard
2. Click "New Listing"
3. Fill in the trade details:
   • Token type (CRCX, MXNX, USDC)
   • Amount and rate
   • Payment method
   • Description
4. Submit the listing

Making a Trade

1. Browse available listings on the marketplace
2. Click on a listing to view details
3. Click "Trade" to initiate an escrow
4. Follow the escrow process:
   • Deposit funds to the escrow contract
   • Send fiat payment to the seller
   • Upload payment receipt
   • Wait for seller confirmation
   • Funds are automatically released

🛠️ Development

Available Scripts

# Development
npm run dev              # Start web app in development mode
npm run build            # Build all packages and apps
npm run start            # Start web app in production mode

# Code Quality
npm run lint             # Lint all packages
npm run biome:check      # Check code with Biome
npm run biome:format     # Format code with Biome
npm run biome:fix        # Fix code issues with Biome
npm run type-check       # Type check all packages

# Maintenance
npm run clean            # Clean all build artifacts

Development Workflow

1. Create a feature branch:

   git checkout -b feature/your-feature-name

2. Make your changes following our coding standards

3. Test your changes:

   npm run type-check
   npm run biome:check
   npm run build

4. Commit using Conventional Commits:

   git commit -m "feat: add new feature"

5. Push and create a Pull Request

For detailed development instructions, see docs/DEVELOPMENT.md.

Adding New Packages

1. Create a new directory in packages/
2. Add package.json with workspace dependencies
3. Add TypeScript configuration
4. Update root package.json workspaces if needed

Adding New Apps

1. Create a new directory in apps/
2. Add package.json with workspace dependencies
3. Add necessary configuration files (next.config.ts, tsconfig.json, etc.)
4. Update root package.json workspaces if needed

🔧 Configuration

TypeScript

• Root tsconfig.json provides base configuration
• Each package extends the root config
• Path mapping for workspace dependencies

Biome

• Consistent code formatting and linting
• Shared configuration across all packages
• Automatic fixes and formatting

Workspace Dependencies

Use workspace:* for internal dependencies:

{
  "dependencies": {
    "@pacto-p2p/shared": "workspace:*",
    "@pacto-p2p/ui": "workspace:*"
  }
}

🚀 Deployment

Web App

# Build the web app
npm run build

# Start production server
npm run start

Environment Variables

Ensure all required environment variables are set in your deployment environment. See Quick Start for the list of required variables.

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details on:

• Code of Conduct
• Development workflow
• Coding standards
• Pull request process
• Reporting issues

Quick Contribution Guide

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Run tests and linting (npm run type-check && npm run biome:check)
5. Commit your changes (git commit -m 'feat: add amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

📚 Documentation

• Development Guide - Detailed development instructions and architecture
• Database Schema - Database structure and relationships
• Contributing Guide - How to contribute to the project

🔐 Security

If you discover a security vulnerability, please email security concerns privately to the maintainers. Do not open public issues for security vulnerabilities.

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Stellar Development Foundation
• Trustless Work for escrow infrastructure
• Next.js for the amazing framework
• All our contributors and supporters

---

Made with ❤️ by the Pacto P2P team

Documentation • Contributing • Issues