coin/README.md

# aicoin

A complete blockchain implementation similar to Bitcoin, designed for circulation within the AIverse game ecosystem with ATProto account integration.

## Features

- 🔗 **Full Blockchain Implementation** - Complete Proof of Work consensus
- 🌐 **P2P Network** - Decentralized peer-to-peer communication using libp2p
- 💰 **Transaction Fees** - 0.1% fee system with automatic calculation
- 📈 **Dynamic Difficulty** - Automatic mining difficulty adjustment
- 🔐 **Secure Wallets** - ed25519 digital signatures with import/export
- 🔗 **ATProto Integration** - Support for decentralized identity
- 🌐 **REST API** - Web API for external applications
- ⚡ **High Performance** - Written in Rust for maximum speed
- 🧪 **Well Tested** - Comprehensive test suite

## Installation

```bash
# Build from source
cargo build --release

# Run tests
cargo test
```

## Quick Start

```bash
# Create a new wallet
cargo run -- wallet

# Check genesis balance
cargo run -- balance genesis

# Send coins from genesis
cargo run -- send <recipient> 100.0 --private-key <genesis_key>

# Mine pending transactions
cargo run -- mine <your_address>

# Start API server
cargo run -- server --port 8080

# Start P2P node
cargo run -- node --port 9000
```

## Commands

### Wallet Management

```bash
# Create new wallet
aicoin wallet

# Create wallet with ATProto DID
aicoin wallet --atproto-did did:plc:example123

# Create and export wallet
aicoin wallet --export my_wallet.json

# Import existing wallet
aicoin import my_wallet.json
```

### Transactions

```bash
# Check balance
aicoin balance <address>

# Send coins
aicoin send <to_address> <amount> --private-key <your_private_key>

# Send with ATProto DID
aicoin send <to_address> <amount> --private-key <key> --atproto-did did:plc:example
```

### Mining & Blockchain

```bash
# Mine pending transactions
aicoin mine <miner_address>

# Show blockchain info
aicoin info

# Validate blockchain
aicoin validate
```

### Network Services

```bash
# Start REST API server
aicoin server --port 8080

# Start P2P network node
aicoin node --port 9000
```

## API Endpoints

When running the API server, the following endpoints are available:

- `GET /api/balance/:address` - Get wallet balance
- `GET /api/info` - Get blockchain information
- `POST /api/wallet` - Create new wallet
- `POST /api/transaction` - Submit transaction
- `POST /api/mine/:address` - Mine block

## Network Protocol

The P2P network supports:
- **Peer Discovery** - Automatic discovery via mDNS
- **Block Broadcasting** - New blocks propagated across network
- **Transaction Pool** - Shared pending transaction pool
- **Consensus** - Proof of Work with difficulty adjustment

## Transaction Fees

- **Fee Rate**: 0.1% of transaction amount
- **Minimum Fee**: 0.01 AIC
- **Fee Distribution**: All fees go to the block miner
- **Fee Calculation**: Automatic during transaction creation

## Mining

- **Algorithm**: SHA-256 Proof of Work
- **Block Time**: 30 seconds target
- **Difficulty Adjustment**: Every 10 blocks
- **Mining Reward**: 50 AIC per block
- **Fee Rewards**: All transaction fees to miner

## Technical Architecture

### Core Components

- **Blockchain**: Block and transaction management
- **Wallet**: Key management and signing
- **Network**: P2P communication layer
- **API**: REST interface for external apps
- **CLI**: Command-line interface

### Dependencies

- **libp2p**: Peer-to-peer networking
- **ed25519-dalek**: Digital signatures
- **sha2**: Hash algorithms
- **axum**: Web framework
- **tokio**: Async runtime
- **serde**: Serialization

## File Structure

```
src/
├── blockchain/     # Core blockchain logic
│   ├── block.rs   # Block structure and mining
│   ├── chain.rs   # Blockchain and consensus
│   └── transaction.rs # Transaction handling
├── wallet/        # Wallet management
├── network/       # P2P networking
├── api/          # REST API server
└── cli/          # Command-line interface

tests/            # Comprehensive test suite
```

## Testing

Run the complete test suite:

```bash
cargo test
```

Tests cover:
- Blockchain operations
- Transaction validation
- Wallet functionality
- Mining and consensus
- Fee calculations

## Configuration

The blockchain uses these default settings:

- **Block Time**: 30 seconds
- **Difficulty Adjustment**: Every 10 blocks
- **Mining Reward**: 50 AIC
- **Initial Difficulty**: 2
- **Fee Rate**: 0.1%
- **Minimum Fee**: 0.01 AIC

## Security

- **Cryptographic Signatures**: ed25519 for all transactions
- **Hash Security**: SHA-256 for block hashing
- **Private Key Protection**: Keys never stored in plaintext
- **Network Security**: Encrypted P2P communication
- **Validation**: Full transaction and block validation

## Integration with AIverse

aicoin is designed for seamless integration with the AIverse ecosystem:

- **ATProto Support**: Native decentralized identity integration
- **Game Currency**: Optimized for in-game transactions
- **Low Fees**: Suitable for microtransactions
- **Fast Confirmation**: 30-second block times
- **API Access**: Easy integration with game clients

## Development

### Building

```bash
# Debug build
cargo build

# Release build
cargo build --release

# Run with logging
RUST_LOG=debug cargo run -- <command>
```

### Contributing

1. Fork the repository
2. Create feature branch
3. Add tests for new functionality
4. Ensure all tests pass
5. Submit pull request

## License

This project is part of the ai.ai ecosystem for creating transparent, heart-centered AI systems.