# 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**: FastAPI (Python)
- **Database**: SQLite with SQLAlchemy ORM
- **Authentication**: JWT tokens with bcrypt password hashing
- **Blockchain**: Web3.py for Ethereum integration
- **Database Migrations**: Alembic
- **API Documentation**: OpenAPI/Swagger

## Project Structure

```
├── main.py                 # FastAPI application entry point
├── requirements.txt        # Python dependencies
├── alembic.ini            # Database migration configuration
├── openapi.json           # API specification
├── app/
│   ├── api/               # API endpoints
│   │   ├── auth.py        # Authentication endpoints
│   │   ├── wallet.py      # Wallet management endpoints
│   │   ├── projects.py    # Project management endpoints
│   │   └── trading.py     # Trading and marketplace endpoints
│   ├── core/              # Core functionality
│   │   ├── security.py    # Authentication and security
│   │   └── deps.py        # Dependency injection
│   ├── db/                # Database configuration
│   │   ├── base.py        # SQLAlchemy base
│   │   └── session.py     # Database session management
│   ├── models/            # Database models
│   │   ├── user.py        # User model
│   │   ├── carbon_project.py  # Carbon project model
│   │   ├── carbon_offset.py   # Carbon offset model
│   │   └── transaction.py     # Transaction model
│   ├── schemas/           # Pydantic schemas
│   │   ├── user.py        # User schemas
│   │   ├── carbon_project.py  # Project schemas
│   │   └── transaction.py     # Transaction schemas
│   └── services/          # Business logic services
│       ├── blockchain.py  # Blockchain integration
│       └── wallet.py      # Wallet management
└── alembic/               # Database migrations
    └── versions/          # Migration files
```

## Installation

1. Install dependencies:
```bash
pip install -r requirements.txt
```

2. Run database migrations:
```bash
alembic upgrade head
```

3. Set required environment variables:
```bash
export SECRET_KEY="your-secret-key-here"
export BLOCKCHAIN_RPC_URL="https://your-ethereum-rpc-url"  # Optional, defaults to localhost
```

## Running the Application

Start the development server:
```bash
uvicorn main:app --host 0.0.0.0 --port 8000 --reload
```

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

## Environment Variables

| Variable | Description | Required | Default |
|----------|-------------|----------|---------|
| `SECRET_KEY` | JWT token secret key | Yes | - |
| `BLOCKCHAIN_RPC_URL` | Ethereum RPC endpoint | No | http://localhost:8545 |

## API Endpoints

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

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

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

### Marketplace & Trading
- `GET /projects/` - Browse all available projects
- `GET /projects/{project_id}` - Get project details
- `POST /trading/purchase` - Purchase carbon offsets
- `GET /trading/my-transactions` - Get user's transactions
- `GET /trading/marketplace` - 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

Create a new migration:
```bash
alembic revision --autogenerate -m "Description of changes"
```

Apply migrations:
```bash
alembic upgrade head
```

### Testing Wallet Integration

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

## Security Features

- JWT-based authentication
- Password hashing with bcrypt
- Role-based access control (developer/buyer)
- Blockchain wallet verification
- Transaction signing and verification

## Contributing

1. Follow the existing code structure and patterns
2. Use type hints for all functions and methods
3. Add appropriate error handling and validation
4. Update documentation for any API changes
5. Test wallet integration thoroughly

## License

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