# Carbon Offset Trading Platform

A blockchain-enabled carbon offset trading platform that connects project developers with willing buyers. This platform allows project developers to list their carbon offset projects and enables buyers to purchase verified carbon credits through blockchain transactions.

## Features

### For Project Developers
- Register as a project developer
- Create and manage carbon offset projects
- Upload project verification documents
- Track project performance and sales
- Integrate with blockchain for tokenization

### For Buyers
- Register as a buyer
- Browse verified carbon offset projects
- Purchase carbon credits
- Link blockchain wallets for transactions
- Track purchase history and carbon offset ownership

### Blockchain Integration
- Wallet linking support (Ethereum-compatible)
- Smart contract integration for carbon credit tokens
- Transaction verification and tracking
- Secure blockchain-based ownership records

## Tech Stack

- **Backend**: Node.js with Express.js and TypeScript
- **Database**: SQLite with Prisma ORM
- **Authentication**: JWT tokens with bcrypt password hashing
- **Blockchain**: Web3.js and Ethers.js for Ethereum integration
- **Validation**: Joi for request validation
- **Security**: Helmet, CORS, Rate limiting

## Project Structure

```
├── src/
│   ├── server.ts           # Express application entry point
│   ├── types/              # TypeScript type definitions
│   │   └── index.ts        # Main types and interfaces
│   ├── routes/             # API endpoints
│   │   ├── auth.ts         # Authentication endpoints
│   │   ├── wallet.ts       # Wallet management endpoints
│   │   ├── projects.ts     # Project management endpoints
│   │   └── trading.ts      # Trading and marketplace endpoints
│   ├── middleware/         # Express middleware
│   │   ├── auth.ts         # Authentication middleware
│   │   ├── validation.ts   # Request validation middleware
│   │   ├── security.ts     # Security middleware
│   │   └── error.ts        # Error handling middleware
│   ├── services/           # Business logic services
│   │   ├── blockchain.ts   # Blockchain integration
│   │   └── wallet.ts       # Wallet management
│   └── utils/              # Utility functions
│       ├── database.ts     # Database connection and utilities
│       └── auth.ts         # Authentication utilities
├── prisma/
│   └── schema.prisma       # Database schema
├── storage/                # Application storage directory
│   └── db/                 # SQLite database files
├── package.json            # Node.js dependencies and scripts
├── tsconfig.json          # TypeScript configuration
└── .env.example           # Environment variables template
```

## Installation

1. Install dependencies:
```bash
npm install
```

2. Set up environment variables:
```bash
cp .env.example .env
# Edit .env with your configuration
```

3. Generate Prisma client and run migrations:
```bash
npm run db:generate
npm run db:migrate
```

## Running the Application

### Development
Start the development server with hot reload:
```bash
npm run dev
```

### Production
Build and start the production server:
```bash
npm run build
npm start
```

The application will be available at:
- **API**: http://localhost:8000
- **Health Check**: http://localhost:8000/health
- **API Documentation**: http://localhost:8000/api/docs

## Environment Variables

| Variable | Description | Required | Default |
|----------|-------------|----------|---------|
| `NODE_ENV` | Environment mode | No | development |
| `PORT` | Server port | No | 8000 |
| `JWT_SECRET` | JWT token secret | Yes | - |
| `DATABASE_URL` | SQLite database file path | No | file:./storage/db/database.db |
| `BLOCKCHAIN_RPC_URL` | Ethereum RPC endpoint | No | http://localhost:8545 |
| `CORS_ORIGIN` | CORS allowed origins | No | * |

## API Endpoints

### Authentication
- `POST /api/auth/register` - Register new user (developer or buyer)
- `POST /api/auth/login` - User login

### Wallet Management
- `POST /api/wallet/link` - Link blockchain wallet to user account
- `DELETE /api/wallet/unlink` - Unlink wallet from user account
- `GET /api/wallet/info` - Get wallet information and balance
- `POST /api/wallet/generate-test-wallet` - Generate test wallet for development

### Project Management (Developers)
- `POST /api/projects/` - Create new carbon offset project
- `GET /api/projects/my-projects` - Get developer's projects
- `PUT /api/projects/{project_id}` - Update project
- `DELETE /api/projects/{project_id}` - Delete project

### Marketplace & Trading
- `GET /api/projects/` - Browse all available projects
- `GET /api/projects/{project_id}` - Get project details
- `POST /api/trading/purchase` - Purchase carbon offsets
- `GET /api/trading/my-transactions` - Get user's transactions
- `GET /api/trading/marketplace/stats` - Get marketplace statistics

### System
- `GET /` - Platform information
- `GET /health` - Health check endpoint

## Database Schema

### Users
- User authentication and profile information
- Wallet linking for blockchain integration
- User types: DEVELOPER or BUYER

### Carbon Projects
- Project details and metadata
- Verification status and documents
- Credit availability and pricing
- Blockchain contract information

### Carbon Offsets
- Individual carbon credit tokens
- Serial numbers and vintage years
- Blockchain token IDs and hashes
- Ownership tracking

### Transactions
- Purchase records and blockchain transactions
- Transaction status and confirmation details
- Gas usage and block information

## Development

### Database Migrations

Generate Prisma client:
```bash
npm run db:generate
```

Create and apply migrations:
```bash
npm run db:migrate
```

View database in Prisma Studio:
```bash
npm run db:studio
```

### Code Quality

Run linting:
```bash
npm run lint
```

Fix linting issues:
```bash
npm run lint:fix
```

Build TypeScript:
```bash
npm run build
```

### Testing Wallet Integration

Use the test wallet generation endpoint to create wallets for development:
```bash
curl -X POST http://localhost:8000/api/wallet/generate-test-wallet
```

## Security Features

- JWT-based authentication with secure token generation
- Password hashing with bcrypt (12 rounds)
- Role-based access control (DEVELOPER/BUYER)
- Rate limiting and CORS protection
- Helmet security headers
- Input validation with Joi
- Blockchain wallet verification
- Transaction signing and verification

## Production Deployment

1. Set production environment variables in `.env`
2. Build the application: `npm run build`
3. Start the production server: `npm start`
4. Ensure database is properly migrated
5. Configure reverse proxy (nginx/Apache)
6. Set up SSL certificates
7. Configure firewall and security groups

## Contributing

1. Follow TypeScript best practices
2. Use the existing code structure and patterns
3. Add comprehensive input validation
4. Include proper error handling
5. Update documentation for API changes
6. Test blockchain integration thoroughly
7. Follow the established commit message format

## License

This project is part of a carbon offset trading platform implementation.