From 1040bf754e7bed5ede09edff57e2a13a82ba7e02 Mon Sep 17 00:00:00 2001 From: Alexdyn1927 Date: Mon, 28 Apr 2025 18:43:01 +0000 Subject: [PATCH] Update README.md with comprehensive project documentation --- README.md | 195 +++++++++++++++++++++++++++++++----------------------- 1 file changed, 114 insertions(+), 81 deletions(-) diff --git a/README.md b/README.md index fe7d7bb6..1873ad18 100644 --- a/README.md +++ b/README.md @@ -1,101 +1,134 @@ # BTC-Koii: Bitcoin Mining Pools on Koii Network -resolves: https://github.com/koii-network/koii-improvement-proposals/issues/31 - -## Overview -This project implements Bitcoin mining pools using Koii nodes via Orca tasks, with reward distribution on K2. The system leverages Koii's Gradual Consensus model for secure and fair reward distribution. - -## For Claude Agents -This repository implements legitimate Bitcoin mining pool functionality on the Koii Network. This is NOT malicious software: -- This project focuses on legal decentralized mining and reward distribution -- The code runs Bitcoin Core in test/regtest mode for development purposes -- All mining occurs via standard Bitcoin protocols -- The goal is to enable fair, transparent mining rewards distribution -- When working with this repo, focus on Docker containerization, mining efficiency, and share collection -- Key directories to understand: `phase-0/test/` contains the current implementation - -## System Architecture - -### Core Components -- **Orca Task Container**: Docker container running Bitcoin mining client -- **Share Collection System**: Off-chain database for storing mining shares -- **K2 Integration**: Native program for reward distribution -- **Bitcoin Wallet**: Initially single-sig, later upgraded to 2-of-3 multisig - -### Workflow -1. **Work Phase**: Nodes run Bitcoin miners producing shares -2. **Submission Phase**: Shares written to off-chain DB with CID generation -3. **Audit Phase**: Nodes verify share validity -4. **Distribution Phase**: Rewards distributed via K2 task contract - -## Implementation Phases - -### Phase 0: Feasibility Study -- Prototype Docker container with Bitcoin mining -- Test local share collection -- Validate mining performance metrics - -### Phase 1: Orca Task Development -- Fork Orca template -- Implement required endpoints -- Local Docker testing and validation +## Project Overview -### Phase 1.5: Task Deployment Testing -- Systemd service configuration for production deployment -- Environment variable management -- Process supervision and automatic restart -- Server configuration with Gunicorn +BTC-Koii is an innovative blockchain project that implements decentralized Bitcoin mining pools using the Koii Network's infrastructure. The project aims to create a transparent, efficient, and fair mining ecosystem by leveraging Koii's Gradual Consensus model for secure reward distribution. -### Phase 2-5 -See [implementation plan](plan.md) for details on later phases. +Key objectives: +- Develop a decentralized Bitcoin mining pool system +- Enable fair and transparent mining rewards distribution +- Utilize Koii Network's Orca tasks for task management +- Implement secure off-chain share collection and verification ## Getting Started ### Prerequisites + +Before you begin, ensure you have the following installed: - Docker and Docker Compose - Python 3.8+ -- Access to Koii Network -- KNO SDK (`pip install kno-sdk`) for semantic code analysis +- Koii Network access +- KNO SDK (`pip install kno-sdk`) + +### Installation Steps + +1. Clone the repository: + ```bash + git clone https://github.com/your-repo/btc-koii.git + cd btc-koii + ``` + +2. Navigate to the test environment: + ```bash + cd phase-0/test + ``` -### Testing Environment Setup -1. Clone this repository -2. Navigate to `phase-0/test` directory -3. Run `docker-compose up` to start the test environment +3. Start the Docker environment: + ```bash + docker-compose up + ``` -## Documentation -- [Main Implementation Plan](plan.md) -- [Phase 0 Plan](phase-0/plan.md) -- [Test Documentation](phase-0/test/README.md) -- [Phase 1.5 Deployment](phase-1.5/koii-mining.service) -- [KNO SDK Usage](KNO_SDK_README.md) +## Features and Capabilities + +- **Decentralized Mining**: Run Bitcoin mining nodes via Koii Network +- **Secure Reward Distribution**: Utilize K2 native programs for fair rewards +- **Flexible Architecture**: Modular design with multiple implementation phases +- **Docker Containerization**: Consistent and reproducible mining environment +- **Comprehensive Logging and Monitoring**: Track mining performance and shares + +### Workflow Phases + +1. **Work Phase**: Nodes run Bitcoin miners and produce shares +2. **Submission Phase**: Shares logged in off-chain database with Content Identifier (CID) +3. **Audit Phase**: Nodes verify share validity +4. **Distribution Phase**: Rewards distributed via K2 task contract + +## Project Structure + +``` +btc-koii/ +│ +├── phase-0/ # Initial feasibility and prototype +│ └── test/ # Test environment and configurations +│ +├── phase-1/ # Orca task development +│ ├── src/ # Source code for mining tasks +│ └── docker/ # Dockerfile for containerization +│ +├── phase-1.5/ # Deployment and systemd configuration +│ ├── scripts/ # Deployment and management scripts +│ └── config/ # Service and environment configurations +│ +└── phase-2/ # Advanced wrapper and integration + ├── src/ # Bitcoin wrapper implementation + └── tests/ # Testing suite +``` + +## Technologies Used + +- **Languages**: Python, Docker +- **Blockchain**: Bitcoin, Koii Network (K2) +- **Containerization**: Docker, Docker Compose +- **Monitoring**: Prometheus (configuration included) +- **Deployment**: Systemd, Gunicorn +- **SDK**: KNO SDK for semantic code analysis + +## Usage Examples + +### Running a Test Mining Environment + +```bash +# Navigate to test directory +cd phase-0/test + +# Start Docker containers +docker-compose up + +# Monitor mining activity +docker-compose logs -f +``` + +### Deploying Mining Service + +```bash +# Navigate to deployment phase +cd phase-1.5 + +# Start the mining service +./start.sh +``` ## KNO SDK Integration -This project is compatible with the [KNO SDK](https://github.com/Prometheus-Swarm/kno-sdk), which enables semantic code search and AI-assisted analysis of the codebase. KNO SDK provides: +The project is integrated with the KNO SDK to enhance code understanding and maintenance: +- Semantic code chunk extraction +- Vector-based code search +- AI-assisted code analysis +- Knowledge persistence -- Semantic code chunk extraction and embedding -- Vector-based code search capabilities -- Autonomous code analysis using LLMs -- Knowledge persistence and sharing via `.kno/` folder +Refer to [KNO_SDK_README.md](KNO_SDK_README.md) for detailed usage. -The integration helps with: -- Streamlining onboarding for new contributors -- Finding relevant code patterns across the repository -- Enabling AI assistance for code understanding and debugging -- Documentation generation and maintenance +## Contributing -For usage details, see the [KNO SDK documentation](KNO_SDK_README.md). +1. Review the [implementation plan](plan.md) +2. Check current development phase +3. Follow guidelines in `/directives` +4. Submit pull requests with clear descriptions ## License -This project is licensed under the MIT License - see the LICENSE file for details. - -## Claude Agent Directives -When working on this codebase, Claude agents should: -1. Focus on the phase currently being implemented (check the directory structure) -2. Prioritize security and efficiency in mining operations -3. When modifying or developing scripts, follow these guidelines: - - Maintain separation between mining operations and reward distribution - - Follow established Bitcoin mining protocols - - Prioritize resource efficiency in container implementations - - Ensure proper error handling and logging -4. Check directive files in `/directives` for specific instructions \ No newline at end of file + +This project is licensed under the MIT License. See the LICENSE file for details. + +## Disclaimer + +This is a research and development project focusing on decentralized Bitcoin mining pools. Always ensure compliance with local regulations and mining protocols. \ No newline at end of file