{"id":29038182,"url":"https://github.com/qdrvm/beamsim","last_synced_at":"2025-06-26T13:36:57.545Z","repository":{"id":300895972,"uuid":"988377272","full_name":"qdrvm/beamsim","owner":"qdrvm","description":"Beam chain networking simulator","archived":false,"fork":false,"pushed_at":"2025-06-24T06:19:03.000Z","size":583,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-06-24T06:32:42.078Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/qdrvm.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}},"created_at":"2025-05-22T13:08:20.000Z","updated_at":"2025-06-23T14:29:14.000Z","dependencies_parsed_at":"2025-06-24T06:32:45.871Z","dependency_job_id":"2a9e2c12-2fc6-4ab6-8388-4ee6eb7cecc2","html_url":"https://github.com/qdrvm/beamsim","commit_stats":null,"previous_names":["qdrvm/beamsim"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/qdrvm/beamsim","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qdrvm%2Fbeamsim","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qdrvm%2Fbeamsim/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qdrvm%2Fbeamsim/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qdrvm%2Fbeamsim/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/qdrvm","download_url":"https://codeload.github.com/qdrvm/beamsim/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qdrvm%2Fbeamsim/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262077162,"owners_count":23255132,"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","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":[],"created_at":"2025-06-26T13:36:56.520Z","updated_at":"2025-06-26T13:36:57.524Z","avatar_url":"https://github.com/qdrvm.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# BeamSim - Beam Chain Networking Simulator\n\nA high-performance simulation framework for testing beam signature aggregation protocols with support for multiple network backends and communication topologies.\n\n## Overview\n\nBeamSim simulates validator networks with configurable group structures, supporting both direct communication, gossip-based protocols, and grid topology. The simulator can run on different backends including simple delay models, queue-based networks, and full NS-3 network simulation.\n\n## Features\n\n- **Multiple Simulation Backends**: Delay-based, queue-based, and NS-3 network simulation\n- **Communication Topologies**: Direct peer-to-peer and gossip protocol communication\n- **Configurable Network Structure**: Customizable validator groups and group sizes\n- **MPI Support**: Distributed simulation capabilities with NS-3 backend\n- **Command Line Interface**: Easy configuration without code changes\n\n## Prerequisites\n\n### Required Dependencies\n\n- **C++23 compatible compiler** (GCC 13+, Clang 15+, or similar)\n- **CMake** 3.20 or higher\n- **MPI** (for NS-3 backend support)\n\n### Optional Dependencies\n\n- **NS-3** (for advanced network simulation)\n\n## Building the Project\n\n### Docker Build (Recommended)\n\nThe easiest way to build and run BeamSim is using Docker:\n\n```bash\n# Build Docker image\nmake docker_image\n\n# Test the build\nmake docker_test\n\n# Run BeamSim in container\ndocker run --rm qdrvm/beamsim/beamsim:$(git rev-parse --short=7 HEAD)-amd64\n```\n\nFor detailed Docker build configuration and options, see [`docs/BUILD.md`](docs/BUILD.md) and [`docs/MAKEFILE.md`](docs/MAKEFILE.md).\n\n### Local Build (without NS-3)\n\n```bash\n# Configure and build\ncmake -G Ninja -B build -D CMAKE_BUILD_TYPE=RelWithDebInfo\nninja -C build\n```\n\n### Local Build with NS-3 Support\n\n1. **Setup NS-3** (automated):\n   ```bash\n   # Run the setup script (downloads and builds NS-3)\n   ./setup_ns3.sh\n   ```\n\n2. **Build the project**:\n   ```bash\n   cmake -G Ninja -B build -D CMAKE_BUILD_TYPE=RelWithDebInfo -D ns3_DIR=external/ns-allinone-3.44/install/lib/cmake/ns3\n   ninja -C build\n   ```\n\nThe NS-3 setup script will:\n- Download NS-3 version 3.44\n- Configure and build NS-3 with optimized settings\n- Install NS-3 to `external/ns-allinone-3.44/install/`\n\n## Usage\n\n### Command Line Interface\n\n```bash\n./build/main [options]\n```\n\n### Options\n\n| Option | Description | Default |\n|--------|-------------|---------|\n| `-b, --backend \u003ctype\u003e` | Simulation backend: `delay`, `queue`, `ns3` | `delay` |\n| `-t, --topology \u003ctype\u003e` | Communication topology: `direct`, `gossip` | `direct` |\n| `-g, --groups \u003cnumber\u003e` | Number of validator groups | `4` |\n| `-gv, --group-validators \u003cnumber\u003e` | Number of validators per group | `3` |\n| `-h, --help` | Show help message | - |\n\n### Examples\n\n#### Basic Usage\n\n```bash\n# Run with default settings (4 groups, 3 validators each, delay backend, direct topology)\n./build/main\n\n# Show help\n./build/main --help\n```\n\n#### Backend Selection\n\n```bash\n# Use delay-based network simulation (fastest)\n./build/main --backend delay\n\n# Use queue-based network simulation\n./build/main --backend queue\n\n# Use NS-3 network simulation (most realistic, requires NS-3)\n./build/main --backend ns3\n```\n\n#### Topology Configuration\n\n```bash\n# Direct peer-to-peer communication\n./build/main --topology direct\n\n# Gossip protocol communication\n./build/main --topology gossip\n```\n\n#### Network Size Configuration\n\n```bash\n# Small network: 2 groups of 5 validators each (10 total)\n./build/main --groups 2 --group-validators 5\n\n# Large network: 20 groups of 50 validators each (1000 total)\n./build/main --groups 20 --group-validators 50\n```\n\n#### Combined Configuration\n\n```bash\n# Realistic simulation with gossip protocol\n./build/main --backend ns3 --topology gossip --groups 10 --group-validators 10\n\n# Performance testing with queue backend\n./build/main --backend queue --topology direct --groups 5 --group-validators 20\n```\n\n## Simulation Backends\n\n### Delay Backend\n- **Type**: Simplified network model\n- **Use Case**: Algorithm development and testing\n- **Performance**: Fastest\n- **Features**: Basic message delays\n\n### Queue Backend  \n- **Type**: Queue-based network simulation\n- **Use Case**: Performance analysis with queuing effects\n- **Performance**: Medium\n- **Features**: Message queuing, contention modeling\n\n### NS-3 Backend\n- **Type**: Full network stack simulation\n- **Use Case**: Realistic network behavior analysis\n- **Performance**: Slowest (most detailed)\n- **Features**: Complete network protocols, routing, realistic delays\n- **Requirements**: NS-3 installation, MPI for distributed simulation\n\n## Communication Topologies\n\n### Direct Topology\n- **Method**: Point-to-point connections\n- **Structure**: Hierarchical (validators → local aggregators → global aggregator)\n- **Use Case**: Traditional blockchain consensus\n- **Scalability**: Limited by aggregator bottlenecks\n\n### Gossip Topology\n- **Method**: Epidemic/gossip protocol\n- **Structure**: Overlay network with topic-based subscription\n- **Use Case**: Scalable consensus protocols\n- **Scalability**: Better for large networks\n\n## Output\n\nThe simulator provides detailed timing and status information:\n\n```\nConfiguration:\n  Backend: ns3\n  Topology: gossip\n  Groups: 4\n  Validators per group: 3\n  Total validators: 12\n\nrouting table rules: 49\nTime: 2088ms, Real: 190ms, Status: SUCCESS\n```\n\n- **Time**: Simulated time to complete consensus\n- **Real**: Wall-clock time for simulation\n- **Status**: SUCCESS/FAILURE based on consensus completion\n\n## MPI Support\n\nWhen using the NS-3 backend, the simulator supports distributed execution:\n\n```bash\n# Run with MPI (example with 4 processes)\nmpirun -np 4 ./build/main --backend ns3 --topology gossip\n```\n\n## Development\n\n### Project Structure\n\n```\nbeamsim/\n├── main.cpp              # Main simulation entry point with CLI\n├── src/beamsim/          # Core simulation framework\n│   ├── example/          # Example consensus protocol implementation\n│   ├── gossip/           # Gossip protocol implementation  \n│   └── ns3/              # NS-3 integration\n├── external/             # External dependencies (NS-3)\n└── build/                # Build artifacts\n```\n\n### Adding New Features\n\n1. **New Backend**: Implement `ISimulator` interface in `src/beamsim/`\n2. **New Topology**: Extend `PeerBase` class in `beamsim::example` namespace\n3. **New Parameters**: Add to `SimulationConfig` struct in `main.cpp`\n\n## Troubleshooting\n\n### Common Issues\n\n1. **NS-3 not found**: Run `./setup_ns3.sh` or set `ns3_FOUND=OFF` in CMake\n2. **MPI errors**: Ensure MPI is properly installed and configured\n3. **Compilation errors**: Verify C++23 compiler support\n\n### Performance Tips\n\n- Use `delay` backend for algorithm development\n- Use `queue` backend for performance analysis\n- Use `ns3` backend only when network realism is critical\n- Start with small network sizes and scale up gradually\n\n### Verifying Installation\n\nAfter building, verify the installation works correctly:\n\n```bash\n# Test basic functionality\n./build/main --help\n\n# Run a quick simulation\n./build/main --groups 2 --group-validators 3\n\n# Test different backends (if available)\n./build/main --backend delay\n./build/main --backend queue\n./build/main --backend ns3  # Only if NS-3 is installed\n```\n\nExpected output should show configuration details and simulation results with \"Status: SUCCESS\".\n\n## Documentation\n\nFor detailed information about building, configuration, and development:\n\n- **[Build Guide](docs/BUILD.md)**: Complete Docker build instructions, configuration options, and troubleshooting\n- **[Makefile Reference](docs/MAKEFILE.md)**: Comprehensive guide to all Makefile targets and variables\n\n## License\n\nSee [LICENSE](LICENSE) file for license information.\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests if applicable\n5. Submit a pull request\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fqdrvm%2Fbeamsim","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fqdrvm%2Fbeamsim","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fqdrvm%2Fbeamsim/lists"}