{"id":32397183,"url":"https://github.com/xdagger/xdagj-p2p","last_synced_at":"2025-10-25T07:35:30.010Z","repository":{"id":319063114,"uuid":"1002036862","full_name":"XDagger/xdagj-p2p","owner":"XDagger","description":"🚀 High-performance Java P2P networking library for XDAG blockchain - Java 21 + Netty + Kademlia DHT + EIP-1459 DNS discovery","archived":false,"fork":false,"pushed_at":"2025-10-16T11:30:01.000Z","size":2193,"stargazers_count":2,"open_issues_count":0,"forks_count":2,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-10-17T11:42:01.935Z","etag":null,"topics":["blockchain","dht","dns-discovery","eip-1459","high-performance","java","java21","kademlia","netty","networking","p2p","protocol-buffers","xdag","zero-copy"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/XDagger.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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-06-14T15:23:39.000Z","updated_at":"2025-06-19T12:28:03.000Z","dependencies_parsed_at":"2025-10-18T00:08:34.144Z","dependency_job_id":"f38f9218-24cd-40b8-9869-f40ef6720150","html_url":"https://github.com/XDagger/xdagj-p2p","commit_stats":null,"previous_names":["xdagger/xdagj-p2p"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/XDagger/xdagj-p2p","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/XDagger%2Fxdagj-p2p","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/XDagger%2Fxdagj-p2p/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/XDagger%2Fxdagj-p2p/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/XDagger%2Fxdagj-p2p/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/XDagger","download_url":"https://codeload.github.com/XDagger/xdagj-p2p/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/XDagger%2Fxdagj-p2p/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":280923473,"owners_count":26414233,"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-10-25T02:00:06.499Z","response_time":81,"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":["blockchain","dht","dns-discovery","eip-1459","high-performance","java","java21","kademlia","netty","networking","p2p","protocol-buffers","xdag","zero-copy"],"created_at":"2025-10-25T07:35:25.251Z","updated_at":"2025-10-25T07:35:30.002Z","avatar_url":"https://github.com/XDagger.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# XDAGJ-P2P\n\n[![Java](https://img.shields.io/badge/Java-21+-orange.svg)](https://openjdk.java.net/)\n[![Maven](https://img.shields.io/badge/Maven-3.6+-blue.svg)](https://maven.apache.org/)\n[![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)\n[![Tests](https://img.shields.io/badge/Tests-859%20Total-brightgreen.svg)](#testing)\n[![Coverage](https://img.shields.io/badge/Coverage-76%25-brightgreen.svg)](#testing)\n\nHigh-performance Java P2P networking library for the XDAG blockchain ecosystem, built with modern Java technologies and comprehensive testing.\n\n**Key Features:** Kademlia DHT discovery • Persistent reputation system • Graduated ban management • Layered network statistics • Production-ready with 859 tests\n\n---\n\n## What's New in v0.1.3\n\n### Test Coverage Expansion (v0.1.3)\n- **Massive Test Suite Growth**: 503 → 859 tests (+356 tests, +71%)\n- **Coverage Improvement**: 75% → 76% instruction coverage\n- **DNS Module Tests**: Added comprehensive tests for dns.tree, dns.sync, dns.update modules\n  - TreeTest: 30 tests, Tree class coverage 59% → 82%\n  - ClientTreeTest: 21 tests for ClientTree functionality\n  - LinkCacheTest: 22 tests for link cache management\n  - PublishConfigTest: 17 tests for DNS publishing configuration\n- **All Tests Passing**: 859/859 tests with zero flaky tests\n\n### Previous Features (v0.1.2)\n\n### Breaking Change: Node ID Migration\n- Migrated from 520-bit to **160-bit Node ID** format (XDAG address-based)\n- Perfect Kademlia DHT compliance (BitTorrent DHT standard)\n- 69% storage reduction per node (65 bytes → 20 bytes)\n- ⚠️ Not compatible with v0.1.0/0.1.1 nodes\n\n### New Features\n- **Reputation System Persistence**: Automatic disk-based saves with time-based decay\n- **Simplified Ban Management**: Graduated durations and whitelist support\n- **Enhanced Monitoring**: LayeredStats for network and application layer metrics\n- **Improved Test Coverage**: 88.9% for XdagMessageHandler, 57.2% for P2pPacketDecoder\n\n### Code Quality\n- Removed 2,277 lines of dead code following extreme simplicity principles\n- Simplified statistics system (5 classes → 1 class, -72% code)\n- Added 368+ new tests (859 total, all passing)\n- Overall coverage improved: 62.9% → 76% (+13.1%)\n\nSee [CHANGELOG.md](CHANGELOG.md) for complete release notes.\n\n---\n\n## Quick Start\n\n### Prerequisites\n- **Java 21+** (Latest LTS with Virtual Threads support)\n- **Maven 3.6+** for dependency management\n\n### Maven Dependency\n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003eio.xdag\u003c/groupId\u003e\n    \u003cartifactId\u003exdagj-p2p\u003c/artifactId\u003e\n    \u003cversion\u003e0.1.3\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n\u003e **⚠️ Breaking Change**: Node ID format changed from 520-bit to 160-bit XDAG address. Not compatible with v0.1.0/0.1.1 nodes.\n\n### Basic Usage\n\n```java\n// 1. Configure P2P service\nP2pConfig config = new P2pConfig();\nconfig.setPort(16783);\nconfig.setDiscoverEnable(true);\nconfig.setSeedNodes(Arrays.asList(\n    new InetSocketAddress(\"\u003cSEED_NODE_IP\u003e\", 16783)\n));\n\n// 2. Implement event handler\npublic class MyEventHandler extends P2pEventHandler {\n    @Override\n    public void onConnect(Channel channel) {\n        System.out.println(\"Connected: \" + channel.getRemoteAddress());\n    }\n\n    @Override\n    public void onMessage(Channel channel, Bytes data) {\n        // Process incoming messages\n    }\n}\n\n// 3. Start P2P service\nP2pService p2pService = new P2pService();\np2pService.register(new MyEventHandler());\np2pService.start(config);\n```\n\n### Run Standalone Node\n\n```bash\n# Build the project\nmvn clean package -DskipTests\n\n# Run P2P node\njava -jar target/xdagj-p2p-0.1.3-jar-with-dependencies.jar \\\n  -p 16783 \\\n  -s \u003cSEED_NODE_IP\u003e:16783\n```\n\n**See [docs/EXAMPLES.md](docs/EXAMPLES.md) for more examples including custom message implementation.**\n\n---\n\n## Core Features\n\n### Kademlia DHT Discovery\n- **160-bit Node ID** based on XDAG address\n- Distributed hash table protocol for decentralized peer discovery\n- UDP-based PING/PONG for liveness detection\n- Recursive node discovery via FIND_NODE/NEIGHBORS\n- Self-healing network topology\n\n### Node Reputation System\n- Persistent disk-based scoring (0-200 range)\n- Time-based reputation decay (5 points/day towards neutral)\n- Automatic save with atomic file operations\n- Thread-safe concurrent operations\n\n### Ban Management\n- Graduated ban durations for repeat offenders (2x per offense, max 30 days)\n- Whitelist support for trusted nodes\n- Automatic expiry and cleanup\n\n### Layered Statistics\n- **Network Layer**: TCP/Netty frame-level metrics (messages sent/received, bytes transferred)\n- **Application Layer**: Business logic metrics (processed, duplicated, forwarded messages)\n- Per-channel statistics tracking\n- Zero external dependencies\n\n**See [docs/NODE_DISCOVERY.md](docs/NODE_DISCOVERY.md) for detailed discovery configuration.**\n\n---\n\n## Performance\n\n### Benchmark Results\n```\nMessage Processing:     1.3M - 8M ops/sec\nNetwork I/O:            0.8M - 2M ops/sec\nSerialization:          4M - 22M ops/sec\nData Access:            98M - 206M ops/sec\nConcurrent (4 threads): 19M ops/sec\n\nNetwork Throughput:     17,000+ msg/sec (6-node cluster)\nMessage Latency:        1-8ms (95% under 8ms)\nError Rate:            0% (7M+ messages tested)\n```\n\n### Test Coverage\n```\nTests:          859 test cases (100% pass rate)\nInstructions:   76% (12,162 / 15,810)\nBranches:       64% (911 / 1,409)\nLines:          77% (2,851 / 3,669)\nExecution:      ~30 seconds, zero flaky tests\n```\n\n**See [docs/PERFORMANCE.md](docs/PERFORMANCE.md) for detailed benchmark methodology and results.**\n\n---\n\n## Architecture\n\n```mermaid\ngraph TB\n    subgraph \"Application Layer\"\n        A[\"XDAG Blockchain Nodes\"]\n    end\n\n    subgraph \"P2P Network Layer\"\n        B[\"XDAGJ-P2P Library\"]\n    end\n\n    subgraph \"Core Components\"\n        C[\"Discovery\u003cbr/\u003e(Kademlia DHT)\"]\n        D[\"Connection\u003cbr/\u003e(Netty + Pools)\"]\n        E[\"Messaging\u003cbr/\u003e(SimpleCodec)\"]\n    end\n\n    A --\u003e B\n    B --\u003e C\n    B --\u003e D\n    B --\u003e E\n\n    style A fill:#e3f2fd,stroke:#1976d2,stroke-width:2px\n    style B fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px\n    style C fill:#e8f5e8,stroke:#388e3c,stroke-width:2px\n    style D fill:#e8f5e8,stroke:#388e3c,stroke-width:2px\n    style E fill:#e8f5e8,stroke:#388e3c,stroke-width:2px\n```\n\n### Components\n\n**Discovery Engine**\n- Kademlia DHT for distributed peer discovery\n- K-bucket routing table (k=16, 160 buckets)\n- Automatic stale node detection and replacement\n\n**Connection Manager**\n- Netty async I/O with event loops\n- Connection pool with adaptive limits\n- Automatic recovery from failures\n\n**Message Router**\n- Custom SimpleCodec encoding (extensible, backward-compatible)\n- Type-safe message definitions\n- Efficient message delivery with batching\n\n---\n\n## Technology Stack\n\n### Core\n- **Java 21 LTS**: Virtual threads and modern APIs\n- **Netty 4.2.6.Final**: Async I/O framework with zero-copy buffers\n- **Custom SimpleCodec**: High-performance binary encoding\n\n### Cryptography\n- **Hyperledger Besu 25.5.0**: Crypto primitives\n- **BouncyCastle 1.80**: Crypto provider\n- **Tuweni 2.7.0**: Packet processing utilities\n\n### Testing\n- **JUnit 5.12.2 + Mockito 5.14.2**: 859 comprehensive tests\n- **JaCoCo**: 76% instruction coverage\n- **Professional test suite**: Multi-node network testing\n\n---\n\n## Network Performance Visualization\n\nReal-world P2P network testing with 20 nodes demonstrating production-level performance.\n\n\u003cdiv align=\"center\"\u003e\n\n#### Network Topology Analysis\n![Network Topology](docs/images/clean_network_topology.png)\n*Distributed node connections with network diameter of 5 hops*\n\n#### Node Performance Comparison\n![Node Performance](docs/images/node_performance.png)\n*Consistent sub-10ms latency across all nodes*\n\n#### Connection Statistics\n![Connection Statistics](docs/images/connection_statistics.png)\n*Network health and load distribution*\n\n#### Message Latency Distribution\n![Latency Distribution](docs/images/latency_distribution.png)\n*95% of messages under 8ms response time*\n\n\u003c/div\u003e\n\n**Key Metrics:**\n```\nNetwork Scale:       20 distributed nodes\nTotal Connections:   108 P2P links\nNetwork Diameter:    5 hops maximum\nAverage Path:        2.38 hops\nConnection Success:  \u003e99% reliability\n```\n\n---\n\n## Testing\n\n### Run Unit Tests\n```bash\n# All 859 tests\nmvn test\n\n# Generate coverage report\nmvn clean test jacoco:report\nopen target/site/jacoco/index.html\n```\n\n### Professional Network Testing\n```bash\ncd test-nodes\n\n# Quick test: 6 nodes\n./start-p2p-network.sh 6\n./monitor-nodes.sh\n\n# Stress test: 20 nodes\n./start-p2p-network.sh 20\nsleep 300\npython3 analyze-network-performance.py --logs-dir logs\n\n# Stop all nodes\n./stop-nodes.sh\n```\n\n**Test Capabilities:**\n- 17 message types for comprehensive coverage\n- Automated 5-30 node scaling tests\n- Real-time monitoring and visualization\n- Professional reports with CSV export\n\n**See [test-nodes/README.md](test-nodes/README.md) for detailed testing guide.**\n\n---\n\n## Use Cases\n\n### XDAG Blockchain Network\n- Peer discovery for XDAG blockchain nodes\n- Block and transaction propagation\n- Consensus mechanism communication\n- Enhanced network connectivity and decentralization\n\n### General Purpose\n- Blockchain networks (universal P2P solution)\n- Distributed systems (service discovery, data replication)\n- IoT networks (self-organizing mesh networks)\n\n---\n\n## Node Discovery\n\nXDAGJ-P2P uses **Kademlia DHT** for fully decentralized peer-to-peer discovery.\n\n### Current Method (v0.1.3)\n\n```bash\n# Start node with seed nodes\njava -jar xdagj-p2p-0.1.3.jar \\\n  -p 16783 \\\n  -s \u003cSEED_NODE_IP_1\u003e:16783,\u003cSEED_NODE_IP_2\u003e:16783\n```\n\n**How it works:**\n1. Connect to seed nodes via TCP\n2. Exchange UDP PING/PONG for liveness detection\n3. Recursive peer discovery via FIND_NODE/NEIGHBORS\n4. Build network topology with 160-bit Node IDs\n5. Maintain routing table with active nodes\n\n**Advantages:**\n- Fully decentralized (no central authority)\n- Self-organizing network topology\n- No single point of failure\n- Real-time node discovery\n\n### Configuration Examples\n\n**Production (24/7 nodes):**\n```bash\njava -jar xdagj-p2p-0.1.3.jar \\\n  -p 16783 \\\n  -s \u003cSEED_NODE_IP_1\u003e:16783,\u003cSEED_NODE_IP_2\u003e:16783,\u003cSEED_NODE_IP_3\u003e:16783\n```\n\n**Development/Testing:**\n```bash\njava -jar xdagj-p2p-0.1.3.jar \\\n  -p 16783 \\\n  -s 127.0.0.1:10000,192.168.1.100:16783\n```\n\n**Private Networks:**\n```bash\njava -jar xdagj-p2p-0.1.3.jar \\\n  -p 16783 \\\n  -s 10.0.1.10:16783,10.0.1.11:16783\n```\n\n**See [docs/NODE_DISCOVERY.md](docs/NODE_DISCOVERY.md) for technical details, best practices, and future DNS discovery plans.**\n\n---\n\n## Documentation\n\n- **[User Guide](docs/USER_GUIDE.md)** - Complete usage guide\n- **[Examples](docs/EXAMPLES.md)** - Code examples and use cases\n- **[Node Discovery](docs/NODE_DISCOVERY.md)** - Discovery mechanisms and configuration\n- **[DNS Configuration](docs/DNS_CONFIGURATION.md)** - EIP-1459 DNS discovery setup with AWS Route53\n- **[Reputation System](docs/REPUTATION.md)** - Node credit scoring and persistence\n- **[Performance](docs/PERFORMANCE.md)** - Benchmark methodology and results\n- **[Roadmap](docs/ROADMAP.md)** - Development roadmap and planned features\n- **[Migration Guide](NODE_ID_MIGRATION_PLAN.md)** - 520-bit to 160-bit migration\n- **[Testing Guide](test-nodes/README.md)** - Professional network testing\n- **[Change Log](CHANGELOG.md)** - Version history\n\n---\n\n## Contributing\n\nWe welcome contributions! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.\n\n### Development\n```bash\n# Build\nmvn clean package\n\n# Run tests\nmvn test\n\n# Run coverage\nmvn clean test jacoco:report\n```\n\n---\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n---\n\n## Support\n\n- **GitHub Issues**: [Report bugs or request features](https://github.com/XDagger/xdagj-p2p/issues)\n- **XDAG Community**: Join the XDAG network community for discussions\n- **Documentation**: See [docs/](docs/) for comprehensive guides\n\n---\n\n**Status:** v0.1.3 Production-Ready | **Tests:** 859 passing | **Coverage:** 76%\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxdagger%2Fxdagj-p2p","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fxdagger%2Fxdagj-p2p","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxdagger%2Fxdagj-p2p/lists"}