koii-network · SatoshiShibanuma · Apr 26, 2025
diff --git a/README.md b/README.md
@@ -1,94 +1,134 @@
 # BTC-Koii: Bitcoin Mining Pools on Koii Network
 
-resolves: https://github.com/koii-network/koii-improvement-proposals/issues/31
+## Project Overview
 
-## 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.
+BTC-Koii is an innovative project that implements decentralized Bitcoin mining pools using Koii nodes and Orca tasks, with a focus on secure and fair reward distribution. The project aims to create a transparent, efficient mechanism for mining Bitcoin while leveraging the Koii Network's Gradual Consensus model.
 
-## 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
+### Key Objectives
+- Develop a decentralized Bitcoin mining pool infrastructure
+- Enable fair and transparent mining reward distribution
+- Utilize Koii Network's unique consensus and task management capabilities
+- Create a modular, scalable mining solution
 
-## System Architecture
+## Getting Started
+
+### Prerequisites
+- Docker and Docker Compose
+- Python 3.8+
+- Koii Network access
+- KNO SDK (`pip install kno-sdk`)
+
+### Installation
+1. Clone the repository
+   ```bash
+   git clone https://github.com/your-org/btc-koii.git
+   cd btc-koii
+   ```
+
+2. Navigate to the test environment
+   ```bash
+   cd phase-0/test
+   ```
+
+3. Start the Docker environment
+   ```bash
+   docker-compose up
+   ```
+
+## Features and Capabilities
 
 ### 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
+- **Orca Task Container**: Docker-based Bitcoin mining client
+- **Share Collection System**: Off-chain database for tracking mining shares
+- **K2 Integration**: Native reward distribution mechanism
+- **Bitcoin Wallet**: Single-sig with plans for 2-of-3 multisig upgrade
+
+### Workflow Stages
+1. **Work Phase**: Nodes run Bitcoin miners and generate shares
+2. **Submission Phase**: Shares stored in off-chain database with CID generation
+3. **Audit Phase**: Share validity verification by network nodes
 4. **Distribution Phase**: Rewards distributed via K2 task contract
 
-## Implementation Phases
+## Project Structure
+
+```
+btc-koii/
+│
+├── phase-0/                # Initial feasibility and prototype phase
+│   ├── test/               # Test environment and configurations
+│   │   ├── config/         # Bitcoin and monitoring configurations
+│   │   ├── scripts/        # Mining and monitoring scripts
+│   │   └── docker/         # Containerization resources
+│
+├── phase-1/                # Orca task development
+│   ├── scripts/            # Task implementation scripts
+│   ├── src/                # Core source code
+│   └── tests/              # Unit and integration tests
+│
+├── directives/             # Operational guidelines and protocols
+├── logs/                   # System and task logs
+└── docker-compose.yml      # Primary Docker composition
+```
+
+## Technologies Used
+
+- **Languages**: Python, Docker
+- **Blockchain**: Bitcoin Core, Koii Network
+- **Tools**: 
+  - Docker
+  - Prometheus (Monitoring)
+  - KNO SDK (Code Analysis)
+  - Orca Task Framework
+
+## Implementation Roadmap
+
+### Completed Phases
+- **Phase 0**: Feasibility study and local prototype
+- **Phase 1**: Orca task development and initial implementation
+
+### Upcoming Phases
+Refer to the [implementation plan](plan.md) for details on future development stages.
 
-### Phase 0: Feasibility Study
-- Prototype Docker container with Bitcoin mining
-- Test local share collection
-- Validate mining performance metrics
+## KNO SDK Integration
 
-### Phase 1: Orca Task Development
-- Fork Orca template
-- Implement required endpoints
-- Local Docker testing and validation
+The project integrates the KNO SDK to enhance:
+- Semantic code search
+- AI-assisted code analysis
+- Knowledge persistence
+- Collaborative development
 
-### Phase 2-5
-See [implementation plan](plan.md) for details on later phases.
+## Usage Examples
 
-## Getting Started
+Run mining test script:
+```bash
+cd phase-0/test
+python scripts/miner.py
+```
 
-### Prerequisites
-- Docker and Docker Compose
-- Python 3.8+
-- Access to Koii Network
-- KNO SDK (`pip install kno-sdk`) for semantic code analysis
+Monitor mining performance:
+```bash
+python scripts/monitor.py
+```
 
-### Testing Environment Setup
-1. Clone this repository
-2. Navigate to `phase-0/test` directory
-3. Run `docker-compose up` to start the test environment
+## Development Guidelines
+
+When contributing:
+- Follow established Bitcoin mining protocols
+- Prioritize security and efficiency
+- Maintain clear separation between mining and reward distribution logic
+- Implement comprehensive error handling and logging
 
 ## Documentation
+
 - [Main Implementation Plan](plan.md)
-- [Phase 0 Plan](phase-0/plan.md)
+- [Phase 0 Detailed Plan](phase-0/plan.md)
 - [Test Documentation](phase-0/test/README.md)
-- [KNO SDK Usage](KNO_SDK_README.md)
+- [KNO SDK Usage Guide](KNO_SDK_README.md)
 
-## 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:
-
-- Semantic code chunk extraction and embedding
-- Vector-based code search capabilities
-- Autonomous code analysis using LLMs
-- Knowledge persistence and sharing via `.kno/` folder
+## License
 
-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
+This project is licensed under the MIT License. See the LICENSE file for complete details.
 
-For usage details, see the [KNO SDK documentation](KNO_SDK_README.md).
+## Disclaimer
 
-## 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
+This is a research and development project focused on legal, transparent Bitcoin mining pool technologies. All operations are conducted in controlled, test environments.