{"id":34568866,"url":"https://github.com/catalyst-network/catalyst-node-rust","last_synced_at":"2026-05-24T20:32:33.024Z","repository":{"id":300223845,"uuid":"1005569822","full_name":"catalyst-network/catalyst-node-rust","owner":"catalyst-network","description":"Rust node for version 2 of Catalyst protocol","archived":false,"fork":false,"pushed_at":"2025-08-23T12:47:57.000Z","size":972,"stargazers_count":0,"open_issues_count":27,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-23T13:43:01.712Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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/catalyst-network.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}},"created_at":"2025-06-20T12:43:30.000Z","updated_at":"2025-08-23T10:21:10.000Z","dependencies_parsed_at":"2025-06-20T14:25:31.374Z","dependency_job_id":"ad295cd1-ddb4-41ad-90cc-f48f1ce9b4bb","html_url":"https://github.com/catalyst-network/catalyst-node-rust","commit_stats":null,"previous_names":["catalyst-network/catalyst-node-rust"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/catalyst-network/catalyst-node-rust","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/catalyst-network%2Fcatalyst-node-rust","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/catalyst-network%2Fcatalyst-node-rust/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/catalyst-network%2Fcatalyst-node-rust/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/catalyst-network%2Fcatalyst-node-rust/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/catalyst-network","download_url":"https://codeload.github.com/catalyst-network/catalyst-node-rust/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/catalyst-network%2Fcatalyst-node-rust/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":27999539,"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-12-24T02:00:07.193Z","response_time":83,"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":[],"created_at":"2025-12-24T09:13:58.817Z","updated_at":"2026-05-24T20:32:33.015Z","avatar_url":"https://github.com/catalyst-network.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Catalyst Network Node\n\nA truly decentralized blockchain node implementation that prioritizes accessibility, fairness, and real-world utility over speculation and wealth concentration.\n\n## 🌟 Key Features\n\n- **True Decentralization**: Anyone can participate without expensive hardware or large token stakes\n- **Collaborative Consensus**: Energy-efficient, work-based consensus mechanism\n- **Multi-Runtime Support**: EVM, SVM, and WASM smart contract execution\n- **Web2 Integration**: Service bus for seamless traditional application integration\n- **Modular Architecture**: Pluggable components for future extensibility\n- **Fair Launch**: No pre-mine, no ICO, earn through contribution\n\n## 🏗️ Architecture\n\n```\n┌─────────────────┬─────────────────┬─────────────────┐\n│   Consensus     │    Database     │    Network      │\n│   Module        │    Module       │    Module       │\n├─────────────────┼─────────────────┼─────────────────┤\n│ Collaborative   │ Multi-level     │ libp2p-based    │\n│ 4-phase         │ RocksDB         │ Peer Discovery  │\n└─────────────────┴─────────────────┴─────────────────┘\n┌─────────────────┬─────────────────┬─────────────────┐\n│   File System   │ Virtual Machine │    Service Bus  │\n│   Module        │    Module       │    Module       │\n├─────────────────┼─────────────────┼─────────────────┤\n│ Content-addressed│ EVM/SVM/WASM   │ WebSocket +     │\n│ DFS (CID sync)  │ Multi-runtime   │ Webhook Events  │\n└─────────────────┴─────────────────┴─────────────────┘\n```\n\n## 🚀 Quick Start\n\n### Prerequisites\n\n- Rust 1.75+ ([install](https://rustup.rs/))\n- Git\n- IPFS: optional. The local testnet uses a built-in, local content store for CID-addressed data (no daemon required).\n\n#### Linux system packages (required for building)\n\nSome crates use native dependencies (e.g. RocksDB / zstd / OpenSSL) and require a C toolchain + headers.\n\n- **Ubuntu/Debian**:\n  - `sudo apt update \u0026\u0026 sudo apt install -y build-essential pkg-config libssl-dev clang libclang-dev cmake`\n- **Fedora/RHEL**:\n  - `sudo dnf install -y gcc gcc-c++ make pkgconf-pkg-config openssl-devel clang clang-devel cmake`\n\n#### Working from a network filesystem (GVFS/SMB)\n\nIf your repo lives under a GVFS mount (paths containing `/gvfs/`), Cargo’s file locking inside `target/` may fail with **`Operation not supported (os error 95)`**.\nThis repo’s `makefile`/`Makefile` automatically sets `CARGO_TARGET_DIR` to a local cache dir in that case.\n\nAdditionally, some GVFS/SMB mounts prevent Cargo from updating `Cargo.lock`. In that case, `make build` will build from a **local rsynced mirror** under `~/.cache/catalyst-node/gvfs-workdir/src` to avoid lockfile write failures.\n\n### Build and Run\n\n```bash\n# Clone the repository\ngit clone https://github.com/catalyst-network/catalyst-node-rust\ncd catalyst-node-rust\n\n# Set up development environment\nmake setup\n\n# Build the project\nmake build\n\n# Run a basic node\nmake run\n\n# Run as validator\nmake run-validator\n\n# Run with storage provision\nmake run-storage\n```\n\n## Local Testnet (recommended for validating current functionality)\n\nThis repo includes a working local testnet harness that runs **3 nodes** with:\n- deterministic faucet funding\n- RPC enabled on node1 (`http://127.0.0.1:8545`)\n- signature + nonce validation\n- LSU application into RocksDB state\n- DFS-backed LSU sync (CID gossip + local content store)\n- persistent mempool with deterministic re-broadcast on restart\n\n### Start / stop\n\nStart:\n\n```bash\nmake testnet\n```\n\nStop:\n\n```bash\nmake stop-testnet\n```\n\n### Faster iteration helpers (non-blocking start + status + basic check)\n\n`make testnet` blocks (it waits on node processes). For day-to-day testing, use:\n\n```bash\nmake testnet-up\nmake testnet-status\nmake testnet-basic-test\nmake testnet-down\n```\n\nTail logs:\n\n```bash\nmake testnet-logs NODE=node1\n```\n\n### Contract sanity check (EVM execution)\n\nThis uses a deterministic initcode fixture (`testdata/evm/return_2a_initcode.hex`) that deploys a contract which returns `0x2a` on empty calldata.\n\n```bash\nmake testnet-up\nmake testnet-contract-test\nmake testnet-down\n```\n\n### Smoke test (single command)\n\nRuns an end-to-end test that:\n- starts the 3-node testnet\n- submits a faucet transaction to node1\n- restarts node1 to test mempool persistence + rehydrate + deterministic re-broadcast\n- verifies node1 balance increases\n- stops the testnet\n\n```bash\nmake smoke-testnet\n```\n\nLogs:\n- `testnet/node1/logs/stdout.log`\n- `testnet/node2/logs/stdout.log`\n- `testnet/node3/logs/stdout.log`\n\n### Send a transaction (faucet → node1)\n\nGet node1 public key (used as the “address” in this scaffold):\n\n```bash\nNODE1_PUBKEY=$(grep -a \"Node ID:\" -m1 testnet/node1/logs/stdout.log | awk '{print $NF}')\necho \"node1_pubkey=$NODE1_PUBKEY\"\n```\n\nSend 25 units from the faucet:\n\n```bash\ncargo run -p catalyst-cli -- send $NODE1_PUBKEY 25 --key-file testnet/faucet.key --rpc-url http://127.0.0.1:8545\n```\n\nCheck node1 balance:\n\n```bash\ncargo run -p catalyst-cli -- balance $NODE1_PUBKEY --rpc-url http://127.0.0.1:8545\n```\n\n### Query peers / chain head / nonce\n\nPeers:\n\n```bash\ncargo run -p catalyst-cli -- peers --rpc-url http://127.0.0.1:8545\n```\n\nHead:\n\n```bash\ncargo run -p catalyst-cli -- status --rpc-url http://127.0.0.1:8545\n```\n\nNonce (faucet):\n\n```bash\nFAUCET_PUBKEY=$(python3 -c 'print(\"fa\"*32)')\ncurl -s -X POST http://127.0.0.1:8545 -H 'content-type: application/json' \\\n  -d \"{\\\"jsonrpc\\\":\\\"2.0\\\",\\\"id\\\":1,\\\"method\\\":\\\"catalyst_getNonce\\\",\\\"params\\\":[\\\"0x${FAUCET_PUBKEY}\\\"]}\"\necho\n```\n\n### Mempool persistence + deterministic re-broadcast\n\nPending protocol transactions are persisted in RocksDB and reloaded on startup. On restart, node1 will:\n- rehydrate the mempool from persisted txs (after revalidation)\n- deterministically rebroadcast them periodically (stable txid order)\n- prune them once their sender nonce is applied (LSU application)\n\n### Docker\n\n```bash\n# Build Docker image\nmake docker-build\n\n# Run with Docker\nmake docker-run\n```\n\n## Stable Devnet (invite others to connect)\n\nYou can run a single-node “devnet” that:\n- listens on a public P2P port\n- exposes RPC externally (binds to `0.0.0.0`)\n- prints the bootstrap multiaddr + RPC URL to share\n\nStart (replace `HOST` with your public IP or DNS name):\n\n```bash\nmake devnet-up HOST=\u003cpublic_ip_or_dns\u003e P2P_PORT=30333 RPC_PORT=8545\n```\n\nStop:\n\n```bash\nmake devnet-down\n```\n\n### How others connect\n\nOn a remote machine, they run their node and point it at your bootstrap address:\n\n```bash\ncargo run -p catalyst-cli -- start \\\n  --validator --rpc --rpc-address 127.0.0.1 --rpc-port 8545 \\\n  --bootstrap-peers \"/ip4/\u003cHOST\u003e/tcp/30333\"\n```\n\n### Bootstrap via DNS seeds (optional)\n\nInstead of hard-coding `--bootstrap-peers`, operators can set **DNS seeds** in the node config. Seeds resolve via:\n- **TXT records** (preferred): multiaddrs, `ip[:port]`, or host:port tokens\n- **A/AAAA fallback**: resolved IPs mapped to `/ip{4,6}/.../tcp/\u003cport\u003e`\n\nConfig example:\n\n```toml\n[network]\nbootstrap_peers = [\"/ip4/\u003cHOST\u003e/tcp/30333\"]\ndns_seeds = [\"seed1.example.org\", \"seed2.example.org\"]\n```\n\n### Multi-hop WAN propagation\n\nNodes will **relay broadcast envelopes with deduplication** to improve propagation in non-fully-meshed WAN topologies (e.g. A ↔ B ↔ C).\nBootstrap dialing uses **per-peer exponential backoff with jitter** to avoid hammering unreachable peers.\n\n### Smart contract execution (current state)\n\nThe repo supports **basic EVM execution** in the local testnet harness (see “Contract sanity check (EVM execution)”).\nThe CLI provides:\n- `catalyst deploy \u003cbytecode_file\u003e`: deploy bytecode via RPC\n- `catalyst call \u003ccontract\u003e \"\u003csig(args)\u003e\"`: call a function (read-only or state-changing if `--key-file` is provided)\n\n\n## 📋 Usage\n\n### Starting a Node\n\n```bash\n# Basic node (user role)\ncatalyst start\n\n# Validator node with RPC\ncatalyst start --validator --rpc\n\n# Storage provider node\ncatalyst start --storage --storage-capacity 100\n\n# Full node (validator + storage + RPC)\ncatalyst start --validator --storage --rpc\n```\n\n### Configuration\n\nCreate a configuration file:\n\n```bash\n# Generate default configuration\ncatalyst start --config catalyst.toml\n\n# Generate node identity\ncatalyst generate-identity --output identity.json\n\n# Create genesis configuration\ncatalyst create-genesis --output genesis.json\n```\n\n### Interacting with the Network\n\n```bash\n# Check node status\ncatalyst status\n\n# View connected peers\ncatalyst peers\n\n# Send KAT tokens\ncatalyst send \u003crecipient_address\u003e \u003camount\u003e --key-file wallet.key\n\n# Check account balance\ncatalyst balance \u003caddress\u003e\n\n# Deploy a smart contract\ncatalyst deploy contract.bytecode --runtime evm --key-file wallet.key\n\n# Call a smart contract\ncatalyst call \u003ccontract_address\u003e \"transfer(address,uint256)\" --key-file wallet.key\n```\n\n## 🔧 Development\n\n### Project Structure\n\n```\ncatalyst-node-rust/\n├── crates/\n│   ├── catalyst-core/         # Core traits and types\n│   ├── catalyst-consensus/    # Collaborative consensus implementation\n│   ├── catalyst-network/      # P2P networking (libp2p)\n│   ├── catalyst-storage/      # RocksDB storage layer\n│   ├── catalyst-runtime-evm/  # Ethereum Virtual Machine runtime\n│   ├── catalyst-runtime-svm/  # Solana Virtual Machine runtime\n│   ├── catalyst-service-bus/  # Web2 integration service bus\n│   ├── catalyst-dfs/          # Content-addressed DFS utilities\n│   ├── catalyst-crypto/       # Cryptographic utilities\n│   ├── catalyst-rpc/          # JSON-RPC server\n│   ├── catalyst-config/       # Configuration management\n│   ├── catalyst-utils/        # Common utilities\n│   └── catalyst-cli/          # Command-line interface\n├── configs/                   # Configuration files\n├── docs/                      # Documentation\n├── scripts/                   # Build and deployment scripts\n└── tests/                     # Integration tests\n```\n\n### Development Commands\n\n```bash\n# Format code\nmake fmt\n\n# Run lints\nmake clippy\n\n# Run tests\nmake test\n\n# Run benchmarks\nmake bench\n\n# Generate documentation\nmake docs\n\n# Start local testnet\nmake testnet\n\n# Watch for changes\nmake watch\n```\n\n### Adding a New Module\n\n1. Create a new crate: `cargo new --lib crates/catalyst-my-module`\n2. Add to workspace in root `Cargo.toml`\n3. Implement the appropriate trait from `catalyst-core`\n4. Register in the main node configuration\n\nExample module implementation:\n\n```rust\nuse async_trait::async_trait;\nuse catalyst_core::{CatalystModule, CatalystResult};\n\npub struct MyModule {\n    // Module state\n}\n\n#[async_trait]\nimpl CatalystModule for MyModule {\n    fn name(\u0026self) -\u003e \u0026'static str {\n        \"my-module\"\n    }\n\n    fn version(\u0026self) -\u003e \u0026'static str {\n        \"0.1.0\"\n    }\n\n    async fn initialize(\u0026mut self) -\u003e CatalystResult\u003c()\u003e {\n        // Initialize module\n        Ok(())\n    }\n\n    async fn start(\u0026mut self) -\u003e CatalystResult\u003c()\u003e {\n        // Start module processing\n        Ok(())\n    }\n\n    async fn stop(\u0026mut self) -\u003e CatalystResult\u003c()\u003e {\n        // Stop module gracefully\n        Ok(())\n    }\n\n    async fn health_check(\u0026self) -\u003e CatalystResult\u003cbool\u003e {\n        // Check module health\n        Ok(true)\n    }\n}\n```\n\n## 🌐 Web2 Integration\n\n### Service Bus Example\n\nConnect traditional applications to blockchain events:\n\n```javascript\n// Node.js example\nconst CatalystServiceBus = require('catalyst-service-bus');\n\nconst bus = new CatalystServiceBus('ws://localhost:8546');\n\n// Listen for token transfers\nbus.on('token_transfer', (event) =\u003e {\n    console.log('Token transfer:', event);\n    \n    // Update your traditional database\n    updateUserBalance(event.to_address, event.amount);\n    \n    // Send notification\n    sendPushNotification(event.to_address, 'Payment received');\n});\n\nbus.connect();\n```\n\n```python\n# Python example\nfrom catalyst_service_bus import ServiceBus\n\nbus = ServiceBus('ws://localhost:8546')\n\n@bus.on('contract_event')\ndef handle_contract_event(event):\n    if event.event_name == 'Transfer':\n        # Process transfer event\n        process_transfer(event.data)\n\nbus.start()\n```\n\n### Smart Contract Deployment\n\nDeploy existing Ethereum contracts:\n\n```bash\n# Deploy with Hardhat/Truffle configuration\nnpx hardhat deploy --network catalyst\n\n# Or use Catalyst CLI directly\ncatalyst deploy MyContract.sol --runtime evm --args \"constructor_arg\"\n```\n\n## 📊 Economics\n\n### Token Model (KAT)\n\n- **Fair Launch**: No pre-mine, no ICO\n- **Genesis Supply**: `0 KAT` (issuance starts after genesis)\n- **Work-Based Rewards**: Earn through network contribution\n- **Fixed Issuance Baseline**: `1 KAT` per successful cycle (v1 model)\n- **Low Fees**: Optimized for usage, not speculation\n\nCanonical parameter details live in `docs/tokenomics-model.md`.\n\n### Earning Opportunities\n\n1. **Validator Rewards**: Participate in consensus\n2. **Storage Rewards**: Provide file storage\n3. **Compute Rewards**: Execute smart contracts\n4. **Development Rewards**: Contribute code\n\n### Hardware Requirements\n\n**Minimum (User Node):**\n- 2 CPU cores\n- 4 GB RAM\n- 20 GB storage\n- Broadband internet\n\n**Recommended (Validator):**\n- 4 CPU cores\n- 8 GB RAM\n- 100 GB SSD storage\n- Stable internet connection\n\n**No Special Hardware Required** - runs on commodity computers\n\n## 🔐 Security\n\n### Consensus Security\n\n- **Byzantine Fault Tolerance**: Secure with \u003c33% malicious nodes\n- **Sybil Resistance**: Resource proofs prevent fake nodes\n- **Economic Security**: Attack cost scales with network size\n\n### Cryptographic Foundations\n\n- **Curve25519**: Elliptic curve for signatures and keys\n- **Blake2b**: Fast, secure hashing\n- **Bulletproofs**: Confidential transaction privacy\n- **Schnorr Signatures**: Efficient signature aggregation\n\n## 🧪 Testing\n\n### Unit Tests\n\n```bash\n# Run all tests\nmake test\n\n# Run specific module tests\ncargo test --package catalyst-consensus\n\n# Run with output\ncargo test -- --nocapture\n```\n\n### Integration Tests\n\n```bash\n# Run integration tests\nmake test-integration\n\n# Start local testnet for testing\nmake testnet\n```\n\n### Benchmarks\n\n```bash\n# Run performance benchmarks\nmake bench\n\n# Profile performance\nmake profile\n```\n\n## 📚 Documentation\n\n- [Technical Consensus Paper](docs/consensus-protocol.pdf) - Detailed mathematical specification\n- [API Documentation](https://docs.catalyst.network) - Complete API reference\n- [Developer Guide](docs/developer-guide.md) - Building on Catalyst\n- [Node Operator Guide](docs/node-operator-guide.md) - Running infrastructure\n\n## 🤝 Contributing\n\nWe welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md).\n\n### Getting Started\n\n1. Fork the repository\n2. Create a feature branch: `git checkout -b feature/amazing-feature`\n3. Make your changes\n4. Run tests: `make test`\n5. Submit a pull request\n\n### Code Standards\n\n- Format code: `make fmt`\n- Pass lints: `make clippy`\n- Add tests for new features\n- Update documentation\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🌍 Community\n\n- **Discord**: [Join our Discord](https://discord.gg/catalyst)\n- **GitHub**: [Contribute on GitHub](https://github.com/catalyst-network/catalyst-node-rust)\n- **Forum**: [Community Forum](https://forum.catalyst.network)\n- **Documentation**: [docs.catalyst.network](https://docs.catalyst.network)\n\n## 🗺️ Roadmap\n\n### Phase 1: Foundation (Q1-Q2 2025)\n- ✅ Modular architecture\n- ✅ Collaborative consensus\n- ✅ EVM compatibility\n- ✅ Basic networking\n- 🔄 Fair launch preparation\n\n### Phase 2: Integration (Q3-Q4 2025)\n- 🔄 Service bus implementation\n- 📋 SVM runtime integration\n- 📋 Mobile applications\n- 📋 Developer tools expansion\n\n### Phase 3: Ecosystem (2026+)\n- 📋 Cross-chain bridges\n- 📋 Enterprise tools\n- 📋 Additional runtimes\n- 📋 Global scaling\n\n## ❓ FAQ\n\n**Q: How is Catalyst different from Ethereum?**\nA: Catalyst prioritizes accessibility over artificial scarcity. No 32 ETH required to validate, collaborative consensus instead of competitive staking.\n\n**Q: Can I run existing Ethereum contracts?**\nA: Yes! Catalyst supports EVM compatibility, so existing Ethereum smart contracts can be deployed without modification.\n\n**Q: How do I earn rewards?**\nA: Run a node and contribute resources - validation, storage, or computation. Rewards are proportional to contribution, not capital.\n\n**Q: What's the service bus?**\nA: A WebSocket/webhook system that lets traditional web applications receive blockchain events like database triggers.\n\n**Q: Is there a token sale?**\nA: No. Catalyst launches fairly like Bitcoin - anyone can run a node and earn from day one.\n\n---\n\n*\"The future of blockchain is not about who can afford to participate, but about who chooses to contribute.\"*","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcatalyst-network%2Fcatalyst-node-rust","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcatalyst-network%2Fcatalyst-node-rust","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcatalyst-network%2Fcatalyst-node-rust/lists"}