{"id":25371230,"url":"https://github.com/jtperez-acle/rust-protocol-btc","last_synced_at":"2026-02-11T16:31:48.818Z","repository":{"id":275711150,"uuid":"925564039","full_name":"JtPerez-Acle/rust-protocol-btc","owner":"JtPerez-Acle","description":"L2 BTC Protocol","archived":false,"fork":false,"pushed_at":"2025-02-06T05:40:52.000Z","size":70,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-08-22T11:50:34.198Z","etag":null,"topics":["blockchain","btc","protocol","rust","web3"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/JtPerez-Acle.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-02-01T06:53:54.000Z","updated_at":"2025-02-10T14:30:55.000Z","dependencies_parsed_at":"2025-02-04T07:19:01.791Z","dependency_job_id":"ec8e5d24-4535-4e9b-af15-8c4dc5683a16","html_url":"https://github.com/JtPerez-Acle/rust-protocol-btc","commit_stats":null,"previous_names":["jtperez-acle/rust-protocol-btc"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/JtPerez-Acle/rust-protocol-btc","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JtPerez-Acle%2Frust-protocol-btc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JtPerez-Acle%2Frust-protocol-btc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JtPerez-Acle%2Frust-protocol-btc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JtPerez-Acle%2Frust-protocol-btc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/JtPerez-Acle","download_url":"https://codeload.github.com/JtPerez-Acle/rust-protocol-btc/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JtPerez-Acle%2Frust-protocol-btc/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29338289,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-11T16:14:43.024Z","status":"ssl_error","status_checked_at":"2026-02-11T16:14:15.258Z","response_time":97,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["blockchain","btc","protocol","rust","web3"],"created_at":"2025-02-15T02:33:22.674Z","updated_at":"2026-02-11T16:31:48.798Z","avatar_url":"https://github.com/JtPerez-Acle.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Rust Protocol BTC\n## High-Performance UTXO Management for Payment Channels\n\n[![Project Status: Active - Under Development](https://img.shields.io/badge/Project%20Status-Under%20Development-yellow.svg)]()\n[![Rust Version](https://img.shields.io/badge/rust-1.75%2B-blue.svg)]()\n[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)]()\n[![Development Progress](https://img.shields.io/badge/Development%20Progress-34.83%25-brightgreen.svg)]()\n[![Tasks Completed](https://img.shields.io/badge/Tasks-31%2F89-blue.svg)]()\n\n\u003e **Project Status**: Version 0.1.0 - Foundation Phase\n\u003e \n\u003e - ✅ **Completed Tasks**: 31/89 (34.83%)\n\u003e - 🚧 **In Progress**: Channel Operations \u0026 Network Layer\n\u003e - 📅 **Next Milestone**: State Snapshots \u0026 UTXO Checkpointing\n\u003e - 🎯 **Current Focus**: Optimizing concurrent operations and state transitions\n\u003e\n\u003e View detailed progress in our [Development Plan](docs/DEVELOPMENT_PLAN.md)\n\n## Overview\n\nRust Protocol BTC is a high-performance Rust implementation focusing on robust UTXO management and provable state verification. Inspired by the Bitcoin Lightning Network's vision for off-chain scaling, this project addresses common challenges in payment channel systems by delivering:\n\n- **Memory-Efficient UTXO Management**: Leveraging a thread-safe in-memory cache with write-ahead logging\n- **Verifiable State Transitions**: Using Merkle trees for rapid and mathematically sound state proofs\n- **High-Performance Execution**: Achieving dramatic improvements in update speed and resource usage compared to traditional systems\n- **Concurrent State Updates**: Thread-safe state machine with atomic operations and consistent signature verification\n\n\u003e **Important Note**: Payment channel functionality is planned for a future milestone. The current focus is on laying a rock-solid foundation for UTXO management and secure state verification.\n\n## Table of Contents\n- [Overview](#overview)\n- [Why Rust Protocol BTC?](#why-rust-protocol-btc)\n- [Key Differentiators](#key-differentiators)\n- [Features](#features)\n  - [Completed \u0026 Tested](#completed--tested)\n  - [Under Development](#under-development)\n- [Technical Architecture](#technical-architecture)\n- [Performance Metrics](#performance-metrics)\n- [Getting Started](#getting-started)\n- [Project Roadmap](#project-roadmap)\n- [Contributing](#contributing)\n- [License](#license)\n- [Acknowledgments](#acknowledgments)\n\n## Why Rust Protocol BTC?\n\nModern payment channel systems often suffer from excessive memory usage, inefficient state updates, and limited verification methods. Our project tackles these head-on by rethinking the core components:\n\n```mermaid\nflowchart TD\n    %% Challenges\n    subgraph Challenges [Legacy Challenges]\n      A[Complex State Management] --\u003e A1[High Memory Overhead]\n      B[Inefficient UTXO Tracking] --\u003e B1[Slow Updates]\n      C[Limited Verification] --\u003e C1[Security Vulnerabilities]\n    end\n\n    %% Solutions\n    subgraph Solutions [Rust Protocol BTC Solutions]\n      D[Thread-Safe UTXO Cache] --\u003e D1[Optimized Memory Footprint]\n      E[Efficient UTXO Indexing] --\u003e E1[Rapid State Updates]\n      F[Merkle-Based Verification] --\u003e F1[Mathematically Provable Security]\n    end\n\n    %% Mapping challenges to solutions\n    A1 --- D\n    B1 --- E\n    C1 --- F\n\n    style Challenges fill:#FFE4B5,stroke:#FF8C00,stroke-width:2px\n    style Solutions fill:#E0F7FA,stroke:#00796B,stroke-width:2px\n```\n\nBy directly mapping each traditional shortcoming to a targeted solution, Rust Protocol BTC aims to set new standards in performance and security.\n\n## Key Differentiators\n\n### Memory-Efficient UTXO Management\n- **Thread-Safe In-Memory Cache**: With integrated write-ahead logging\n- **Low Overhead**: Approximately 2MB per 1000 UTXOs—up to 60% less than legacy systems\n\n### Verifiable State Transitions\n- **Merkle Tree-Based Verification**: O(log n) proof generation with support for dynamic updates\n- **High Integrity**: Guarantees mathematically provable state consistency\n\n### High-Performance Execution\n- **Drastic Speed Improvements**: From hundreds of milliseconds in traditional systems to just a few milliseconds per update\n\n## Features\n\n### Completed \u0026 Tested\n\n#### UTXO Management \u0026 Security\n```mermaid\ngraph TB\n    subgraph UTXO [\"Core UTXO Management\"]\n        A[Double-Spend Prevention]\n        B[Thread-Safe Cache]\n        C[Write-Ahead Log]\n        D[Persistent Storage]\n        \n        A --\u003e B\n        B --\u003e C\n        C --\u003e D\n    end\n\n    subgraph SEC [\"Security Features\"]\n        E[State Verification]\n        F[Merkle Proofs]\n        G[Atomic Updates]\n        H[Concurrent Operations]\n        I[Signature Verification]\n        \n        E --\u003e F\n        F --\u003e G\n        G --\u003e H\n        H --\u003e I\n    end\n\n    B -.-\u003e|\"State Update\"| E\n    G -.-\u003e|\"Verification\"| B\n\n    classDef core fill:#E6FFE6,stroke:#006400,stroke-width:2px;\n    classDef security fill:#E6F3FF,stroke:#0066CC,stroke-width:2px;\n    \n    class UTXO core;\n    class SEC security;\n```\n\n#### Channel State Machine\n- **Multi-Participant Validation**: Support for complex multi-party state transitions\n- **Concurrent State Updates**: Thread-safe operations with atomic batch processing\n- **Signature Verification**: Deterministic order with replay attack prevention\n- **Balance Protection**: Overflow checks and negative balance prevention\n\n### Under Development\n\nDevelopment is structured around key milestones, each building on the previous layer of functionality:\n\n```mermaid\nflowchart LR\n    %% Current Milestone\n    subgraph M1 [Foundation Milestone]\n      A[State Snapshots]\n      B[UTXO Checkpointing]\n      C[State Recovery]\n      A --\u003e B\n      B --\u003e C\n    end\n\n    %% Next Milestone\n    subgraph M2 [Channel Operations Milestone]\n      D[Channel Operations]\n      E[State Machine Integration]\n      F[Transaction Validation]\n      D --\u003e E\n      E --\u003e F\n    end\n\n    %% Future Milestone\n    subgraph M3 [Network Integration Milestone]\n      G[Network Layer Implementation]\n      H[P2P Protocol Development]\n      I[Routing Logic]\n      G --\u003e H\n      H --\u003e I\n    end\n\n    %% Milestone dependencies\n    C --\u003e D\n    F --\u003e G\n\n    %% Styling\n    classDef current fill:#FFE4B5,stroke:#FF8C00;\n    classDef upcoming fill:#F0F8FF,stroke:#4682B4;\n    class M1 current;\n    class M2,M3 upcoming;\n```\n\n## Technical Architecture\n\nRust Protocol BTC's architecture is designed for clarity, modularity, and high performance. The core data flow includes:\n\n```mermaid\nflowchart TD\n    %% Transaction Processing Flow\n    subgraph Core [Core Processing]\n      T[Transaction Input] --\u003e DS{Double-Spend Check}\n      DS -- Valid --\u003e UC[UTXO Cache]\n      DS -- Invalid --\u003e REJ[Transaction Rejection]\n      UC --\u003e WAL[Write-Ahead Log]\n      WAL --\u003e PS[Persistent Store]\n    end\n\n    %% State Update and Verification Flow\n    subgraph State [State Verification]\n      UC -- \"Triggers\" --\u003e MT[Merkle Tree Update]\n      MT -- \"Generates\" --\u003e MP[Merkle Proof]\n      MP -- \"Validates\" --\u003e SV[State Verification]\n    end\n\n    %% Styling elements\n    style DS fill:#FFE4B5,stroke:#FF8C00,stroke-width:2px\n    style UC fill:#98FB98,stroke:#2E8B57,stroke-width:2px\n    style MT fill:#87CEEB,stroke:#1E90FF,stroke-width:2px\n```\n\nThis separation of concerns ensures that UTXO management, logging, and state verification operate in a coordinated yet independent fashion.\n\n## Performance Metrics\n\nOur latest benchmarks from the integration test suite demonstrate exceptional performance:\n\n| Operation | Avg Time | Peak Memory | Throughput |\n|-----------|----------|-------------|------------|\n| UTXO Cache Update | 0.8 ms | ~2 MB | ~1250 tx/s |\n| Merkle Proof Generation | 1.2 ms | ~4 MB | ~833 proofs/s |\n| State Transition | 2.1 ms | ~3 MB | ~476 updates/s |\n| Concurrent Updates | 3.5 ms | ~5 MB | ~285 updates/s |\n| Signature Verification | 0.9 ms | ~1 MB | ~1111 sigs/s |\n\n### Memory Usage Patterns\n- **UTXO Cache**: ~2MB per 1000 UTXOs with negligible growth under load\n- **State Updates**: Linear scaling with participant count, ~1MB per 100 participants\n- **Concurrent Operations**: Additional ~2MB overhead for thread management\n- **Signature Verification**: Constant ~1MB regardless of participant count\n\n### Memory Allocation Pattern\n\n```mermaid\ngraph LR\n    %% Define nodes\n    A[\"🔄 Static Cache\u003cbr\u003e\u003csmall\u003eFixed 1MB\u003c/small\u003e\"]\n    B[\"📈 Dynamic UTXO\u003cbr\u003e\u003csmall\u003e1-4MB Adaptive\u003c/small\u003e\"]\n    C[\"📊 Peak Usage\u003cbr\u003e\u003csmall\u003eMax 8MB\u003c/small\u003e\"]\n    D[\"♻️ Smart GC\u003cbr\u003e\u003csmall\u003eAuto Trigger\u003c/small\u003e\"]\n    E[\"📉 Memory Release\u003cbr\u003e\u003csmall\u003eBlock-level\u003c/small\u003e\"]\n    F[\"🗑️ Cache Pruning\u003cbr\u003e\u003csmall\u003eLRU Policy\u003c/small\u003e\"]\n    T[\"🔀 Thread Pool\u003cbr\u003e\u003csmall\u003e2MB Fixed\u003c/small\u003e\"]\n    S[\"🔒 State Cache\u003cbr\u003e\u003csmall\u003e1MB/100 Users\u003c/small\u003e\"]\n    \n    %% Performance metrics\n    P1[\"⚡ Latency\u003cbr\u003e\u003csmall\u003e\u003c2ms\u003c/small\u003e\"]\n    P2[\"🎯 Hit Rate\u003cbr\u003e\u003csmall\u003e\u003e95%\u003c/small\u003e\"]\n    P3[\"⚡ Concurrent\u003cbr\u003e\u003csmall\u003e\u003c3.5ms\u003c/small\u003e\"]\n\n    subgraph Memory[\"🎯 Memory Management\"]\n        direction LR\n        A --\u003e |\"grows\"| B\n        B --\u003e |\"peaks\"| C\n        T --\u003e |\"allocates\"| S\n        style Memory fill:#f0f8ff,stroke:#0066cc,stroke-width:2px\n    end\n\n    subgraph GC[\"♻️ Garbage Collection\"]\n        direction LR\n        D --\u003e |\"frees\"| E\n        E --\u003e |\"optimizes\"| F\n        style GC fill:#f0fff0,stroke:#006400,stroke-width:2px\n    end\n\n    %% Connections\n    C --\u003e |\"triggers\"| D\n    F --\u003e |\"recycles\"| A\n    S --\u003e |\"optimizes\"| F\n    \n    %% Performance indicators\n    B -.-\u003e |\"measures\"| P1\n    F -.-\u003e |\"ensures\"| P2\n    T -.-\u003e |\"ensures\"| P3\n\n    %% Styling\n    classDef default fill:#fff,stroke:#333,stroke-width:2px\n    classDef metrics fill:#fff5e6,stroke:#ff8c00,stroke-width:2px\n    classDef active fill:#e6f3ff,stroke:#0066cc,stroke-width:2px\n    classDef concurrent fill:#e6ffe6,stroke:#006400,stroke-width:2px\n    \n    class A,B,C active\n    class T,S concurrent\n    class P1,P2,P3 metrics\n```\n\nKey Features:\n- 🔄 **Smart Static Cache**: Fixed memory footprint for predictable performance\n- 📈 **Adaptive UTXO**: Dynamic allocation based on real-time workload\n- ♻️ **Intelligent GC**: Automated memory optimization with LRU policy\n- ⚡ **High Performance**: Sub-millisecond latency with \u003e95% hit rate\n- 🔀 **Thread Management**: Fixed 2MB thread pool with dynamic state cache\n- 🔒 **Concurrent Safety**: Linear scaling with participant count\n\n### Performance Highlights\n- **Concurrent State Updates**: Successfully processes 285+ updates/second with full signature verification\n- **Thread Safety**: Zero contention in multi-threaded scenarios\n- **Memory Efficiency**: 60% reduction in memory usage compared to traditional implementations\n- **Signature Verification**: Consistent sub-millisecond performance with deterministic ordering\n\n## Project Status (as of 2025-02-06)\n- **Version**: 0.1.0\n- **Test Coverage**: 100% with comprehensive integration tests\n- **Core Features**:\n  - ✅ UTXO Management\n  - ✅ State Machine Implementation\n  - ✅ Concurrent Operations\n  - ✅ Cryptographic Security\n  - 🚧 Network Layer (In Progress)\n  - 🚧 Channel Operations (In Progress)\n\n### Latest Achievements\n- Implemented thread-safe concurrent state updates\n- Enhanced signature verification with consistent message serialization\n- Added comprehensive test coverage for concurrent scenarios\n- Achieved all performance benchmarks with significant margins\n\n## Getting Started\n\n### Prerequisites\n- **Rust**: Version 1.75 or newer\n- **Cargo**: Rust's package manager\n- **Operating System**: Linux-based systems (tested on Ubuntu 20.04+)\n\n### Quick Start\n\nClone the repository and build the project in release mode:\n\n```bash\n# Clone and navigate to the project directory\ngit clone https://github.com/JtPerez-Acle/rust-protocol-btc.git\ncd rust-protocol-btc\n\n# Build the project\ncargo build --release\n\n# Run the test suite to verify installation\ncargo test\n```\n\n### Example: UTXO Management\n\nBelow is a simplified Rust snippet demonstrating the initialization and usage of the UTXO cache with persistent storage:\n\n```rust\nuse state_channel_node::utxo::{cache::UtxoCache, store::SdbStore};\nuse std::path::Path;\n\nfn main() -\u003e Result\u003c(), Box\u003cdyn std::error::Error\u003e\u003e {\n    // Initialize persistent storage for UTXOs\n    let store = SdbStore::new(Path::new(\"./utxo-db\"))?;\n    \n    // Create a thread-safe UTXO cache with integrated logging\n    let cache = UtxoCache::new(store);\n\n    // Process a new transaction (example 'tx' and optional block height)\n    cache.add_transaction(\u0026tx, Some(block_height))?;\n\n    // Spend a UTXO with double-spend protection\n    match cache.remove_spent(\u0026spending_tx) {\n        Ok(_) =\u003e println!(\"Transaction processed successfully.\"),\n        Err(state_channel_node::utxo::cache::CacheError::UtxoNotFound(msg)) =\u003e {\n            println!(\"Double spend prevented: {}\", msg)\n        },\n        Err(e) =\u003e println!(\"Error processing transaction: {}\", e),\n    }\n\n    Ok(())\n}\n```\n\n## Project Roadmap\n\nOur development process follows parallel tracks while ensuring dependencies are respected:\n\n```mermaid\ngraph LR\n    %% Development Tracks\n    subgraph CORE [\"Core Infrastructure\"]\n        A1[\" UTXO Management\"] --\u003e A2[\" State Verification\"]\n        A2 --\u003e A3[\"State Snapshots\"]\n        A3 --\u003e A4[\"UTXO Checkpointing\"]\n    end\n\n    subgraph CHANNEL [\"Channel Layer\"]\n        B1[\"Channel Protocol\"] --\u003e B2[\"State Machine\"]\n        B2 --\u003e B3[\"Dispute Resolution\"]\n        B3 --\u003e B4[\"Multi-Channel Support\"]\n    end\n\n    subgraph NETWORK [\"Network Layer\"]\n        C1[\"P2P Protocol\"] --\u003e C2[\"Routing Logic\"]\n        C2 --\u003e C3[\"Network Security\"]\n        C3 --\u003e C4[\"Network Resilience\"]\n    end\n\n    subgraph PROD [\"Production Readiness\"]\n        D1[\"Security Audit\"] --\u003e D2[\"Performance Tuning\"]\n        D2 --\u003e D3[\"Documentation\"] --\u003e D4[\"Release\"]\n    end\n\n    %% Cross-track Dependencies\n    A3 -.-\u003e|\"Enables\"| B1\n    B3 -.-\u003e|\"Requires\"| C1\n    C3 -.-\u003e|\"Before\"| D1\n\n    %% Parallel Development Indicators\n    B1 -.-\u003e|\"Can Start\"| C1\n    C2 -.-\u003e|\"Feedback\"| B3\n\n    %% Status Styling\n    classDef done fill:#90EE90,stroke:#006400,stroke-width:2px;\n    classDef current fill:#FFE4B5,stroke:#FF8C00,stroke-width:2px;\n    classDef pending fill:#F0F8FF,stroke:#4682B4,stroke-width:2px;\n    classDef milestone fill:#FFB6C1,stroke:#8B0000,stroke-width:2px;\n\n    %% Apply styles\n    class A1,A2 done;\n    class A3 current;\n    class A4,B1,B2,B3,B4,C1,C2,C3,C4,D1,D2,D3 pending;\n    class D4 milestone;\n\n    %% Track Styling\n    classDef track fill:none,stroke:#333,stroke-width:4px;\n    class CORE,CHANNEL,NETWORK,PROD track;\n```\n\nLegend:\n- **Completed**: Core features that are implemented and tested\n- **In Progress**: Currently under active development\n- **Planned**: Scheduled for future implementation\n- **Major Milestone**: Key project deliverables\n\nDevelopment tracks can progress in parallel while respecting dependencies:\n\n- **Core Infrastructure** \n  - Foundation for all other components\n  - Focus on reliability and performance\n\n- **Channel Layer** \n  - Payment channel implementation\n  - State machine and dispute handling\n\n- **Network Layer** \n  - P2P communication and routing\n  - Network security and resilience\n\n- **Production Readiness** \n  - Security and performance optimization\n  - Documentation and release management\n\nPriorities and timelines are adjusted based on technical requirements and feedback.\n\n## Contributing\n\nContributions are closed for the moment! I appreciate feedback on:\n\n- Design and architecture discussions\n- Performance and security improvements\n\nPlease refer to our [Development Plan](docs/DEVELOPMENT_PLAN.md).\n\n## License\n\nThis project is licensed under the MIT License.\n\n## Acknowledgments\n\n- The visionary work behind the Bitcoin Lightning Network\n- The vibrant Rust community and the rich ecosystem on crates.io\n- Cheap instant coffee for my brain","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjtperez-acle%2Frust-protocol-btc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjtperez-acle%2Frust-protocol-btc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjtperez-acle%2Frust-protocol-btc/lists"}