{"id":47987826,"url":"https://github.com/ryo-zen/zeicoin","last_synced_at":"2026-04-04T11:29:56.866Z","repository":{"id":332886288,"uuid":"1064425300","full_name":"ryo-zen/zeicoin","owner":"ryo-zen","description":"ZeiCoin is a minimalist cryptocurrency blockchain written in Zig with cumulative proof-of-work consensus, RandomX ASIC-resistant mining and peer-to-peer networking.","archived":false,"fork":false,"pushed_at":"2026-03-19T04:07:53.000Z","size":1473,"stargazers_count":3,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-03-19T04:54:39.297Z","etag":null,"topics":["blockchain","crypto","zig"],"latest_commit_sha":null,"homepage":"https://www.zeicoin.com","language":"Zig","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/ryo-zen.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-09-26T02:45:38.000Z","updated_at":"2026-03-18T03:18:00.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ryo-zen/zeicoin","commit_stats":null,"previous_names":["ryo-zen/zeicoin"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/ryo-zen/zeicoin","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ryo-zen%2Fzeicoin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ryo-zen%2Fzeicoin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ryo-zen%2Fzeicoin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ryo-zen%2Fzeicoin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ryo-zen","download_url":"https://codeload.github.com/ryo-zen/zeicoin/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ryo-zen%2Fzeicoin/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31397980,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-04T10:20:44.708Z","status":"ssl_error","status_checked_at":"2026-04-04T10:20:06.846Z","response_time":60,"last_error":"SSL_read: 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","crypto","zig"],"created_at":"2026-04-04T11:29:56.760Z","updated_at":"2026-04-04T11:29:56.833Z","avatar_url":"https://github.com/ryo-zen.png","language":"Zig","funding_links":[],"categories":["Network \u0026 Web","Applications"],"sub_categories":["Web3 Framework"],"readme":"# ⚡ ZeiCoin ⚡\n\nA minimalist blockchain written in Zig with longest chain consensus, RandomX mining, and peer-to-peer networking.\n\n\u003e [!WARNING]\n\u003e ZeiCoin is under active development for educational and research purposes. The software is in **TestNet phase** and breaking changes may occur between releases. Do not use for real value transfers.\n\n## Overview\n\nZeiCoin is a blockchain implemented from scratch in Zig, a modern systems programming language with explicit error handling, no hidden control flow, and compile-time memory safety. The core implementation totals approximately 20,000 lines of code.\n\nKey features include an account-based transaction model, concurrent blockchain analytics via RocksDB secondary instances, and a modular 14-message network protocol. The cryptographic stack comprises RandomX ASIC-resistant mining, Ed25519 signatures, BLAKE3 hashing, and ChaCha20-Poly1305 wallet encryption.\n\n### Current Use Cases\n- **Educational**: Learning blockchain development and consensus algorithms\n- **Research**: Experimenting with blockchain protocols and network behavior\n- **Development**: Testing multi-node synchronization and P2P networking\n\n### Not Production Ready\n\n\u003e [!CAUTION]\n\u003e **TestNet Only!** This blockchain is currently in testnet phase and not ready for production use.\n\n### Key Features\n\n- **Longest Chain Consensus** - Cumulative proof-of-work with configurable peer verification\n- **RandomX Mining** - ASIC-resistant with Light (256MB) and Fast (2GB) modes\n- **HD Wallets** - BIP39/BIP32 hierarchical deterministic wallets with mnemonic recovery\n- **Modern Cryptography** - ChaCha20-Poly1305 encryption, Argon2id key derivation, Ed25519 signatures\n- **Analytics Platform** - TimescaleDB integration with REST API (optional)\n- **P2P Networking** - Custom binary protocol with CRC32 integrity\n- **High Performance** - ~15 tps, concurrent indexing, efficient sync protocols\n- **Layer 2 Messaging** - Rich transaction metadata with PostgreSQL indexing (testnet, optional)\n- **Testnet Faucet** - Rate-limited signed ZEI distribution for testnet (optional)\n\n## Quick Start\n\n### Prerequisites\n\n- **Zig** 0.16.0-dev.2193+fc517bd01 (nightly)\n- **RandomX** proof-of-work mining algorithm\n- **RocksDB** libraries (`librocksdb-dev` on Ubuntu/Debian)\n- **Memory**: 2GB+ RAM recommended. For 1GB nodes, **4GB of swap is required** (see `systemd/README.md`).\n\n### Optional (Not Required for Running a Node)\n- **PostgreSQL** 12+ (only for analytics and L2 messaging features)\n\n### Installation\n\n```bash\n# Clone the repository\ngit clone https://github.com/ryo-zen/zeicoin.git\ncd zeicoin\n\n# Configure environment\ncp .env.example .env\n# Edit .env with your settings\n\n# Build (debug mode)\nzig build\n\n# Build (optimized mode)\nzig build -Doptimize=ReleaseFast\n```\n\n### Running a Sync Only Node\n\n```bash\n# Start server (no mining)\nZEICOIN_SERVER=127.0.0.1 ./zig-out/bin/zen_server\n```\n\n### Running a Mining Node\n\n```bash\n# Create a miner wallet (interactive password prompt)\nZEICOIN_SERVER=127.0.0.1 ./zig-out/bin/zeicoin wallet create miner\n\n# Start with mining enabled\nZEICOIN_SERVER=127.0.0.1 ./zig-out/bin/zen_server --mine miner\n\n# Connect to bootstrap nodes (automatic from .env)\n# Default bootstrap: 209.38.84.23:10801\n```\n\n### CLI Usage\n\n```bash\n# Create a wallet (interactive password prompt)\nZEICOIN_SERVER=127.0.0.1 ./zig-out/bin/zeicoin wallet create alice\n\n# Check balance\nZEICOIN_SERVER=127.0.0.1 ./zig-out/bin/zeicoin balance alice\n\n# Get wallet address\nZEICOIN_SERVER=127.0.0.1 ./zig-out/bin/zeicoin address alice\n\n# Send transaction\nZEICOIN_SERVER=127.0.0.1 ./zig-out/bin/zeicoin send 100 \u003caddress\u003e alice\n\n# View transaction history\nZEICOIN_SERVER=127.0.0.1 ./zig-out/bin/zeicoin history alice\n\n# Get blockchain status\nZEICOIN_SERVER=127.0.0.1 ./zig-out/bin/zeicoin status\n\n# Backup wallet (show 12-word mnemonic)\nZEICOIN_SERVER=127.0.0.1 ./zig-out/bin/zeicoin seed alice\n\n# Restore wallet from mnemonic\nZEICOIN_SERVER=127.0.0.1 ./zig-out/bin/zeicoin wallet restore recovered word1 word2 ... word12\n```\n\n## Architecture\n\n### Project Structure\n\n```\nzeicoin/\n├── src/\n│   ├── core/              # Core blockchain components (relative imports)\n│   │   ├── types/         # Data structures and constants\n│   │   ├── crypto/        # Cryptography (Ed25519, Bech32, RandomX, BIP39)\n│   │   ├── storage/       # RocksDB persistence and serialization\n│   │   ├── network/       # P2P networking and protocol\n│   │   ├── chain/         # Chain management and validation\n│   │   ├── mempool/       # Transaction pool management\n│   │   ├── miner/         # Mining subsystem\n│   │   ├── sync/          # Synchronization protocols\n│   │   ├── wallet/        # Wallet management\n│   │   └── server/        # Server components\n│   ├── apps/              # Applications (use zeicoin module)\n│   │   ├── main.zig            # Server entry point\n│   │   ├── cli.zig             # Command-line interface\n│   │   ├── indexer.zig         # PostgreSQL blockchain indexer\n│   │   └── transaction_api.zig # Transaction API service\n│   └── lib.zig            # Public API (zeicoin module)\n├── sql/                   # Database schemas\n├── randomx/               # RandomX C library\n└── tests/                 # Test suite\n```\n\n### Core Components\n\n#### Consensus\n- Cumulative proof-of-work\n- Configurable peer block hash consensus (disabled/optional/enforced)\n- Difficulty adjustment every 3 blocks\n- Coinbase maturity: 100 blocks\n\n#### Mining\n- **RandomX Algorithm**: ASIC-resistant proof-of-work\n- **TestNet**: Light mode (256MB RAM), difficulty threshold: 0xF0000000\n- **MainNet**: Fast mode (2GB RAM), difficulty threshold: 0x00008000\n- Mining rewards locked for 100 blocks (coinbase maturity)\n\n#### Network Protocol\n- **Ports**: P2P (10801), Client API (10802), JSON-RPC (10803), REST API (8080)\n- **Bootstrap Nodes**: 209.38.84.23:10801\n- **Address Format**: Bech32 with BLAKE3 hashing (tzei1... for TestNet, zei1... for MainNet)\n- **Message Types**: Handshake, Ping/Pong, Block, Transaction, GetBlocks, GetPeers, BlockHash\n- **Integrity**: CRC32 checksums on all messages\n\n#### Wallet Security\n- **Encryption**: ChaCha20-Poly1305 AEAD (Authenticated Encryption)\n- **Key Derivation**: Argon2id (64MB memory, 3 iterations)\n- **HD Wallets**: BIP39 (12-word mnemonic) + BIP32 derivation\n- **Signatures**: Ed25519 for transaction signing\n- **Password Requirements**: Minimum 8 characters\n- **Memory Protection**: Passwords cleared after use\n\n## Layer 2 Messaging System (TestNet)\n\n\u003e [!NOTE]\n\u003e Layer 2 is an optional feature for testnet. Running a ZeiCoin node does **not** require PostgreSQL or any L2 components. The core blockchain operates independently with just RocksDB.\n\nZeiCoin includes an optional Layer 2 messaging layer that adds rich metadata to blockchain transactions.\n\n### Features\n- **Transaction Messages**: Attach messages, categories, and metadata to ZEI transactions\n- **Auto-Linking**: Indexer automatically links L2 messages to confirmed blockchain transactions\n- **REST API**: Complete API for L2 message management and querying\n\n### Requirements\n- **Core Node**: RocksDB only (no additional dependencies)\n- **L2 Features**: PostgreSQL 12+ (optional, only if you want L2 messaging)\n- **Analytics**: TimescaleDB (optional, only if you want analytics dashboards)\n\n### L2 Workflow\n1. Create message with metadata (draft status)\n2. Update to pending before sending transaction\n3. Send actual ZEI transaction on blockchain\n4. Indexer automatically confirms L2 message with tx_hash\n\n## Testnet Faucet (TestNet)\n\n\u003e [!NOTE]\n\u003e The faucet is an optional testnet service for distributing test ZEI. It is not part of the core node.\n\nThe testnet faucet distributes small amounts of ZEI to new addresses with rate limiting and signed payouts to prevent abuse.\n\n- **Rate Limiting**: One payout per address per time window\n- **Signed Payouts**: All faucet transactions are cryptographically signed\n- **REST API**: Simple endpoint to request testnet ZEI\n\n## Analytics \u0026 Data Infrastructure (Optional)\n\n\u003e [!IMPORTANT]\n\u003e\n\u003e Analytics and indexing are optional features. You can run a fully functional mining or sync node without any of these components.\n\n### Concurrent Indexer\n\nZeiCoin features an optional concurrent indexer that runs simultaneously with the mining node without database conflicts:\n\n```bash\n# One-time DB setup for the indexer schema (no sample rows)\ncreatedb zeicoin_testnet\npsql zeicoin_testnet \u003c sql/indexer_schema.sql\n\n# Start mining node\nZEICOIN_SERVER=127.0.0.1 ./zig-out/bin/zen_server --mine miner \u0026\n\n# Run indexer (indexes new blocks and exits)\nZEICOIN_DB_PASSWORD=testpass123 ./zig-out/bin/zeicoin_indexer\n\n# Or run continuously (automated monitoring)\nwhile true; do\n    ZEICOIN_DB_PASSWORD=testpass123 ./zig-out/bin/zeicoin_indexer\n    sleep 30\ndone \u0026\n```\n\n**Architecture**:\n- Primary Database: RocksDB (mining node, exclusive write)\n- Secondary Database: RocksDB secondary instance (indexer, concurrent read)\n- Analytics Database: PostgreSQL/TimescaleDB (indexed data)\n- Zero conflicts between mining and indexing\n\n### TimescaleDB Analytics\n\nHigh-performance analytics system with continuous aggregates:\n\n- **Hypertables**: Time-partitioned tables (7-day chunks)\n- **Continuous Aggregates**: Real-time materialized views\n- **Compression**: 90%+ space savings on older data\n- **Performance**: 1000x faster than raw blockchain queries\n\n**REST API Endpoints**:\n- `GET /health` - Service health check\n- `GET /api/network/health` - Network metrics (24h)\n- `GET /api/transactions/volume` - Transaction volume (30d)\n- Port: 8080, CORS enabled\n\n## Configuration\n\nKey environment variables (see `.env.example` for all options):\n\n```bash\n# Network Configuration\nZEICOIN_NETWORK=testnet                    # testnet or mainnet\nZEICOIN_BOOTSTRAP=209.38.31.77:10801       # Bootstrap nodes\nZEICOIN_SERVER=127.0.0.1                   # Server address\n\n# Consensus Configuration\nZEICOIN_CONSENSUS_MODE=optional             # disabled, optional, enforced\nZEICOIN_CONSENSUS_THRESHOLD=0.5             # 50% peer agreement required\nZEICOIN_CONSENSUS_MIN_PEERS=0               # Minimum peer responses\n\n# Mining Configuration\nZEICOIN_MINE_ENABLED=false                  # Enable mining\nZEICOIN_MINER_WALLET=miner                  # Mining wallet name\n\n# Database Configuration\nZEICOIN_DB_PASSWORD=***                     # PostgreSQL password\nZEICOIN_DATA_DIR=zeicoin_data               # Data directory\n\n# Wallet Security\nZEICOIN_WALLET_PASSWORD=***                 # Optional: for automation only\n```\n\n## Testnet Deployment\n\n### Systemd Services\n\nFor automatic startup and management on testnet servers, use the included systemd service files:\n\n```bash\n# Install services\nsudo cp systemd/*.service /etc/systemd/system/\nsudo cp systemd/*.timer /etc/systemd/system/\nsudo cp systemd/*.target /etc/systemd/system/\nsudo systemctl daemon-reload\n\n# Enable and start all services\nsudo systemctl enable zeicoin.target\nsudo systemctl start zeicoin.target\n\n# Check status\nsudo systemctl status zeicoin.target\n```\n\n**Available Services**:\n- `zeicoin-mining.service` - Main mining server with auto-restart\n- `zeicoin-server.service` - Non-mining blockchain server\n- `zeicoin-indexer.timer` - Automatic indexing every 30 seconds\n- `zeicoin.target` - Start/stop all services together\n\nSee [systemd/README.md](systemd/README.md) for detailed installation and configuration instructions.\n\n## Testing\n\n```bash\n# Run all tests\nzig build test\n\n# Run specific module tests\nzig build test-crypto\nzig build test-blockchain\nzig build test-network\n\n# Fast compilation check\nzig build check\n\n# Clean build artifacts\nzig build clean\n```\n\n## Network Information\n\n### TestNet\n- **Address Prefix**: `tzei1...`\n- **Mining Mode**: Light (256MB RAM)\n- **Difficulty**: 0xF0000000 (easy)\n- **Bootstrap Nodes**: 209.38.84.23:10801\n- **Database**: `zeicoin_testnet`\n\n### MainNet (Future)\n- **Address Prefix**: `zei1...`\n- **Mining Mode**: Fast (2GB RAM)\n- **Difficulty**: 0x00008000 (hard)\n- **Database**: `zeicoin_mainnet`\n\n### Network Limits\n- Block size: 16MB hard limit, 2MB soft limit (mining)\n- Transaction size: 100KB maximum\n- Message field: 512 bytes maximum\n- Mempool: 10,000 transactions, 50MB total size\n\n## Development\n\n### Build Commands\n\n```bash\nzig build                          # Debug build\nzig build -Doptimize=ReleaseFast   # Optimized build\nzig build test                     # Run tests\nzig build check                    # Fast compilation check\nzig build docs                     # Generate documentation\nzig build clean                    # Clean artifacts\n```\n\n## Security Features\n\n### Implemented Protections\n- Difficulty validation (prevents difficulty spoofing attacks)\n- Peer block hash consensus (prevents chain forks)\n- Signature verification (Ed25519)\n- Wallet encryption (ChaCha20-Poly1305 + Argon2id)\n- Coinbase maturity (100 blocks)\n- Transaction size limits\n- Mempool limits and validation\n\n## Current Status\n\n**Feature Freeze Active** - The codebase is feature-complete for testnet validation.\n\n**Focus Areas**:\n\n- libp2p implementation\n- Multi-node mining and sync testing\n- Bug fixes and stability improvements\n- Documentation improvements\n- Performance optimization\n- Website docs\n\n**Next Steps**:\n\n- Complete testnet validation\n- Community feedback\n\n## Contributing\n\nContributions to ZeiCoin are welcome.\n\n### Code Contributions\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/fire-feature`)\n3. Test your changes (`zig build test`)\n4. Commit your changes (`git commit -m 'feature: fire feature'`)\n5. Push to the branch (`git push origin feature/fire-feature`)\n6. Open a Pull Request\n\n**Development Guidelines**:\n- Follow Zig best practices\n- Add tests for new features\n- Update documentation\n- Ensure code compiles and tests pass\n\n## License\n\nMIT License - See [LICENSE](LICENSE) file for details.\n\n---\n\n**ZeiCoin v0.0.1-testnet** (pronounced ZEE-koyn; IPA: /ziː kɔɪn/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fryo-zen%2Fzeicoin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fryo-zen%2Fzeicoin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fryo-zen%2Fzeicoin/lists"}