{"id":31395816,"url":"https://github.com/khelechy/pearbook","last_synced_at":"2025-09-29T10:50:58.626Z","repository":{"id":313404350,"uuid":"1051230003","full_name":"Khelechy/pearbook","owner":"Khelechy","description":"An offline first peer-to-peer distributed expense tracker proof-of-concept demonstrating Conflict-Free Replicated Data Types (CRDTs) in a peer-to-peer network using Kademlia DHT, built for research on eventual consistency and the CAP theorem.","archived":false,"fork":false,"pushed_at":"2025-09-23T11:39:01.000Z","size":10344,"stargazers_count":15,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-09-23T13:29:37.693Z","etag":null,"topics":["consensus","crdt","dht","distributed-systems","peer-to-peer"],"latest_commit_sha":null,"homepage":"","language":"Go","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/Khelechy.png","metadata":{"files":{"readme":"README.md","changelog":null,"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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-05T16:39:12.000Z","updated_at":"2025-09-23T11:39:04.000Z","dependencies_parsed_at":"2025-09-05T21:21:03.278Z","dependency_job_id":"c1af15b6-ed74-43a4-a6a1-090b01fb8b7f","html_url":"https://github.com/Khelechy/pearbook","commit_stats":null,"previous_names":["khelechy/pearbook"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Khelechy/pearbook","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Khelechy%2Fpearbook","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Khelechy%2Fpearbook/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Khelechy%2Fpearbook/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Khelechy%2Fpearbook/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Khelechy","download_url":"https://codeload.github.com/Khelechy/pearbook/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Khelechy%2Fpearbook/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":277503530,"owners_count":25829214,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-29T02:00:09.175Z","response_time":84,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["consensus","crdt","dht","distributed-systems","peer-to-peer"],"created_at":"2025-09-29T10:50:54.551Z","updated_at":"2025-09-29T10:50:58.618Z","avatar_url":"https://github.com/Khelechy.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# PearBook\n\n![PearBook](https://github.com/Khelechy/pearbook/blob/main/d5c27f66-1f5c-495f-900c-67358ae018a9.jpeg)\n\nA peer-to-peer distributed expense tracker proof-of-concept demonstrating Conflict-Free Replicated Data Types (CRDTs) in a peer-to-peer network using Kademlia DHT, built for research on eventual consistency and the CAP theorem.\n\n[Reference research paper here](https://doi.org/10.64388/IREV9I2-1710338-8995)\n\n## Overview\n\nPearBook is a decentralized application that allows users to track shared expenses without relying on central servers. It uses custom CRDT implementations (OR-Set, PN-Counter, OR-Map) over an actual Kademlia DHT using libp2p to ensure eventual consistency across distributed nodes.\n\nThis project serves as a research prototype for exploring:\n- CRDTs in distributed systems\n- Kademlia DHT for peer-to-peer data storage and retrieval\n- Peer-to-peer expense management\n- Eventual consistency without central coordination\n- CAP theorem trade-offs in real-world applications\n\n## Quick Start\n\n```bash\n# Clone and enter the project\ngit clone https://github.com/khelechy/pearbook.git\ncd pearbook/pearbook_core\n\n# Install dependencies\ngo mod tidy\n\n# Generate cryptographic keys\ngo run cmd/pearbook/main.go genkey --output my_key.pem\n\n# Start the server\ngo run cmd/pearbook/main.go server\n```\n\nThe server will start on `http://localhost:8081` and connect to the libp2p DHT network. Use the CLI tools to generate signed operations for the API endpoints.\n\n## Project Structure\n\n- **pearbook_core/**: Go-based backend implementing the core logic, CRDTs, actual Kademlia DHT using libp2p, HTTP API, and CLI tools. See [README](pearbook_core/README.md) for setup and usage.\n  - **CLI Commands**: `genkey` (key generation), `sign` (operation signing), `server` (run API server)\n  - **API Endpoints**: RESTful HTTP API with cryptographic security\n  - **CRDTs**: OR-Set, OR-Map, PN-Counter implementations\n  - **DHT**: Real libp2p Kademlia implementation\n- **mobile/** (planned): Mobile app codebase for iOS/Android clients.\n- **docs/** (planned): Research papers, CRDT explanations, and architecture docs.\n\n## Features\n\n- **Cryptographic Security**: Client-side ECDSA key generation with digital signatures for all operations\n- **CLI Tools**: Command-line interface for key generation (`genkey`), operation signing (`sign`), and server management (`server`)\n- **Decentralized Groups**: Create and join expense groups without a central server\n- **User Identity Management**: Separation of operational user IDs and display names\n- **Single Approval System**: Simplified group joining with single approval instead of majority consensus\n- **CRDT-Based Syncing**: Automatic conflict resolution using OR-Set (members), OR-Map (expenses), and PN-Counter (balances)\n- **Kademlia DHT Networking**: Actual DHT using libp2p for data storage and retrieval in a real P2P network\n- **Global Group Registry**: Decentralized discovery system for finding groups across nodes\n- **Cache-First Performance**: Local sharded cache prioritized over network calls for optimal performance\n- **RESTful HTTP API**: Proper GET/POST endpoints for group management, expense operations, and balance queries\n- **Eventual Consistency**: Merges data from multiple nodes to resolve conflicts\n- **Sharded Local Cache**: Hash-based indexing with 16 shards for high concurrency and performance\n- **Worker-Based Syncing**: Concurrent worker pools for efficient periodic data propagation\n\n## Architecture\n\n### Core Components\n- **CLI Tools**: Command-line interface for key management, operation signing, and server control\n- **Cryptographic Security**: ECDSA key pairs generated client-side with digital signature verification\n- **Node**: Manages groups with sharded local cache (16 shards), DHT, and CRDT operations using concurrent workers\n- **CRDTs**: OR-Set for members, OR-Map for expenses, PN-Counter for balances ensure eventual consistency without conflicts\n- **Actual Kademlia DHT using libp2p**: Real P2P network for decentralized data storage and retrieval\n- **HTTP API**: RESTful interface with GET/POST methods and JSON request/response formats\n\n### Syncing Mechanism\n- **Cache-First**: All operations check local cache before network calls for optimal performance\n- **Joining**: Fetches group data when a user joins with automatic local caching\n- **Periodic**: Syncs all groups every 5 seconds in the background using concurrent worker pools\n- **Global Discovery**: Decentralized group registry enables cross-node group discovery\n- **On-Demand**: Syncs before balance queries for up-to-date data with cache updates\n- **Merging**: Uses CRDT Merge functions to resolve conflicts and achieve eventual consistency\n- **Unique Tags**: Generates UUIDs for each CRDT operation to ensure proper conflict resolution\n\n## CLI Tools\n\nPearBook includes a comprehensive command-line interface for development and testing:\n\n### Key Generation\n```bash\ngo run cmd/pearbook/main.go genkey --output my_key.pem\n```\nGenerates ECDSA key pairs and outputs the public key in hex format ready for API use.\n\n### Operation Signing\n```bash\n# Create operation data\necho '{\"user\":{\"user_name\":\"Alice\",\"public_key\":\"04...\"}}' \u003e data.json\n\n# Sign the operation\ngo run cmd/pearbook/main.go sign --operation join_group --group-id \"group123\" --user-id \"abc123\" --data-file data.json --key my_key.pem\n```\nCreates cryptographically signed operations for secure API interactions.\n\n### Server Management\n```bash\ngo run cmd/pearbook/main.go server\n```\nStarts the HTTP API server on port 8081 with libp2p DHT connectivity.\n\n## Research Context\n\nThis project is designed as a proof-of-concept for academic research on:\n- **CRDTs**: Practical implementation of operation-based CRDTs.\n- **Kademlia DHT**: Distributed hash table for decentralized data management.\n- **CAP Theorem**: Demonstrating eventual consistency in a distributed system.\n- **Peer-to-Peer Systems**: Decentralized data management without central authorities.\n\n[Reference research paper here](https://doi.org/10.64388/IREV9I2-1710338-8995)\n\n## Contributing\n\nContributions are welcome! Please:\n1. Fork the repository.\n2. Create a feature branch.\n3. Submit a pull request with a clear description.\n\n## License\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n## Contact\n\nFor questions or research collaborations, contact Kelechi Onyekwere at [onyekwerekelechimac@gmail.com].\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkhelechy%2Fpearbook","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkhelechy%2Fpearbook","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkhelechy%2Fpearbook/lists"}