first
This commit is contained in:
240
README.md
Normal file
240
README.md
Normal file
@ -0,0 +1,240 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user