{"id":30596437,"url":"https://github.com/ac12644/blockchain-secp-falcon","last_synced_at":"2025-08-29T21:43:34.051Z","repository":{"id":50528958,"uuid":"479880394","full_name":"ac12644/blockchain-secp-falcon","owner":"ac12644","description":"Learn-by-doing blockchain: modular consensus (PoW/PoS), pluggable crypto (secp256k1 / Falcon PQC), P2P gossip, Merkle trees, blocks, state, and a tiny REST API.🚀","archived":false,"fork":false,"pushed_at":"2025-08-26T09:47:47.000Z","size":271,"stargazers_count":21,"open_issues_count":0,"forks_count":16,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-08-26T11:50:47.216Z","etag":null,"topics":["blockchain","cli","crypto-js","discovery-swarm","ecdsa","falcon512","leveldb","nodejs","peer2peer","proof-of-stake","proof-of-work","wallet"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ac12644.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":"2022-04-10T01:02:44.000Z","updated_at":"2025-08-26T09:47:50.000Z","dependencies_parsed_at":"2024-01-26T23:25:38.949Z","dependency_job_id":"8daa55a9-0874-466e-bba9-072d1cd0cd46","html_url":"https://github.com/ac12644/blockchain-secp-falcon","commit_stats":null,"previous_names":["ac12644/blockchain-secp-falcon"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/ac12644/blockchain-secp-falcon","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ac12644%2Fblockchain-secp-falcon","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ac12644%2Fblockchain-secp-falcon/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ac12644%2Fblockchain-secp-falcon/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ac12644%2Fblockchain-secp-falcon/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ac12644","download_url":"https://codeload.github.com/ac12644/blockchain-secp-falcon/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ac12644%2Fblockchain-secp-falcon/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":272767564,"owners_count":24989523,"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-08-29T02:00:10.610Z","response_time":87,"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","cli","crypto-js","discovery-swarm","ecdsa","falcon512","leveldb","nodejs","peer2peer","proof-of-stake","proof-of-work","wallet"],"created_at":"2025-08-29T21:43:33.294Z","updated_at":"2025-08-29T21:43:34.032Z","avatar_url":"https://github.com/ac12644.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003c!-- PROJECT SHIELDS --\u003e\n\n[![GitHub stars](https://img.shields.io/github/stars/ac12644/blockchain-secp-falcon?style=flat)](https://github.com/ac12644/blockchain-secp-falcon/stargazers)\n[![GitHub forks](https://img.shields.io/github/forks/ac12644/blockchain-secp-falcon?style=flat)](https://github.com/ac12644/blockchain-secp-falcon/network/members)\n[![GitHub issues](https://img.shields.io/github/issues/ac12644/blockchain-secp-falcon?style=flat)](https://github.com/ac12644/blockchain-secp-falcon/issues)\n[![Tests](https://github.com/ac12644/blockchain-secp-falcon/actions/workflows/tests.yml/badge.svg)](https://github.com/ac12644/blockchain-secp-falcon/actions/workflows/tests.yml)\n\n\u003c!-- PROJECT LOGO --\u003e\n\u003cbr /\u003e\n\u003cdiv align=\"center\"\u003e\n  \u003ca href=\"https://github.com/ac12644/blockchain-secp-falcon\"\u003e\n    \u003cimg src=\"img/blockchain.svg\" alt=\"Logo\" width=\"80\" height=\"80\"\u003e\n  \u003c/a\u003e\n\n  \u003ch3 align=\"center\"\u003eBlockchain — a hackable educational L1 in Node.js\u003c/h3\u003e\n\n  \u003cp align=\"center\"\u003e\n    Learn-by-doing blockchain: modular consensus (PoW/PoS), pluggable crypto (secp256k1 / Falcon PQC), P2P gossip, Merkle trees, blocks, state, and a tiny REST API.\n    \u003cbr /\u003e\u003cbr /\u003e\n    \u003cstrong\u003e⭐ Star this repo if you like real, readable blockchain code!\u003c/strong\u003e\n  \u003c/p\u003e\n\u003c/div\u003e\n\n---\n\n## Why this project?\n\nMost tutorials hide the moving parts. This repo shows the **whole path** end-to-end:\n\n- block and header structure\n- merkle trees and block hashing\n- PoW/PoS consensus (switchable)\n- transaction signing \u0026 verification\n- P2P sync \u0026 fork choice (longest chain)\n- dynamic HTTP API for quick experiments\n- unit tests for the core primitives\n\nYou’ll be able to **run multiple nodes locally**, **mine blocks**, **send signed transactions**, and **watch chains sync**.\n\n---\n\n## Quick Start (5 minutes)\n\n```bash\n# 1) Install\nnpm install\n\n# 2) Run your first node (PoW + secp256k1)\nnpm start\n# watch logs:\n# [http] listening on :8080\n# [p2p] listening on \u003crandom\u003e\n# [wallet] address: \u003cyour 40-hex address\u003e\n\n# 3) In another terminal, run a second node\nnpm start\n# second node picks a new HTTP port (e.g., :8081) and connects\n\n# 4) Mine an empty block on node A (instant, easy PoW target via /mine)\ncurl -X POST http://localhost:8080/mine\n\n# 5) Check both nodes now show the same tip:\ncurl http://localhost:8080/latest\ncurl http://localhost:8081/latest\n```\n\nIf both latest blocks match, congrats — you have a tiny blockchain cluster syncing locally.\n\n---\n\n## Project Structure\n\n```\nsrc/\n├─ consensus/          # PoW / PoS implementations\n├─ core/               # block, chain, merkle, state\n├─ crypto/             # Crypto adapter (secp256k1 or Falcon)\n├─ network/            # P2P gossip + HTTP server\n├─ tx/                 # transaction model \u0026 verification\n├─ wallet/             # wallet init \u0026 key persist\n└─ index.js            # entrypoint (starts P2P and HTTP)\ntest/                  # Jest tests for core modules\n```\n\n---\n\n## How it works (short theory)\n\n- **BlockHeader:** links to previous block, commits to the Merkle root of txs, includes timestamp + PoW/PoS fields.\n- **Merkle Tree:** deterministic hash of the tx list; order matters; last leaf duplicates when odd.\n- **PoW:** mines a header hash under a target (nBits). We add `/mine` with an **easy** target for instant demos.\n- **PoS:** selects a validator with probability proportional to stake (demo stakes are in-memory).\n- **Chain Validity:** checks parent linkage, timestamps, consensus-specific validity, and per-tx signature/balance/nonce.\n- **P2P:** peers gossip new blocks, request missing blocks, and can request a full chain on forks; longest chain wins.\n\n---\n\n## Switch Consensus \u0026 Crypto\n\n### Consensus\n\n```bash\n# Proof-of-Work (default)\nnpm run start:pow\n# Proof-of-Stake\nnpm run start:pos\n```\n\nor:\n\n```bash\nCONSENSUS_MODE=pow node src/index.js\nCONSENSUS_MODE=pos node src/index.js\n```\n\n### Cryptography\n\n```bash\n# Classic ECDSA (secp256k1) — default\nnpm run start:secp\n# Post-Quantum Falcon-512 (requires pqclean)\nnpm run start:falcon\n```\n\nor:\n\n```bash\nCRYPTO_MODE=falcon node src/index.js\n```\n\nYou can combine:\n\n```bash\nCRYPTO_MODE=falcon CONSENSUS_MODE=pos node src/index.js\n```\n\n---\n\n## HTTP API (learn by calling)\n\nEach node auto-picks a free port (8080, 8081, …).\n\n- `GET /blocks` → entire chain\n- `GET /block/:index` → block by index\n- `GET /latest` → latest block\n- `GET /state/:address` → `{ balance, nonce }`\n- `POST /mine` → mine an empty block (PoW demo, instant)\n- `POST /tx` → submit a **signed** transaction (see below)\n\n### Example: Mine and Inspect\n\n```bash\ncurl -X POST http://localhost:8080/mine\ncurl http://localhost:8080/latest\ncurl http://localhost:8080/blocks | jq 'length'\n```\n\n---\n\n## Submitting a **signed transaction** (end-to-end)\n\nTransactions must be signed using the same crypto mode the node is running.\n\nWe’ll:\n\n1. read your local wallet,\n2. sign a tx in a one-liner Node script,\n3. POST it to the node.\n\n### 1) Get your address (from logs)\n\nWhen you start the node you’ll see:\n\n```\n[wallet] address: 09c8186fc8073ee1728f9a2586a221b81d4f5c2a\n```\n\n### 2) Prepare recipient\n\n```\nexport FROM=09c8186fc8073ee1728f9a2586a221b81d4f5c2a\nexport TO=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\n```\n\n### 3) Build \u0026 sign a tx\n\n```bash\nnode -e \"(\n  async () =\u003e {\n    const fs = require('fs');\n    const CryptoAdapter = require('./src/crypto/cryptoAdapter');\n    const pk = fs.readFileSync('./src/wallet/private_key','utf8').trim();\n    const pub = fs.readFileSync('./src/wallet/public_key','utf8').trim();\n    const from = process.env.FROM;\n    const to = process.env.TO;\n    const amount = 1, fee = 0, nonce = 1;\n    const message = from + to + amount;\n    const signature = await CryptoAdapter.sign(message, pk);\n    const tx = { fromAddress: from, toAddress: to, amount, fee, nonce, publicKey: pub, signature };\n    console.log(JSON.stringify(tx));\n  }\n)()\" \u003e /tmp/tx.json\n```\n\n### 4) Submit the tx\n\n```bash\ncurl -X POST http://localhost:8080/tx   -H \"Content-Type: application/json\"   --data-binary @/tmp/tx.json\n```\n\nCheck balances:\n\n```bash\ncurl http://localhost:8080/state/$FROM\ncurl http://localhost:8080/state/$TO\n```\n\n---\n\n## Running multiple nodes (sync demo)\n\n1. Terminal A:\n\n```bash\nnpm start\n# [http] :8080\n```\n\n2. Terminal B:\n\n```bash\nnpm start\n# [http] :8081\n# [p2p] connected...\n```\n\n3. Mine on A:\n\n```bash\ncurl -X POST http://localhost:8080/mine\n```\n\n4. Both tips match:\n\n```bash\ncurl http://localhost:8080/latest\ncurl http://localhost:8081/latest\n```\n\n---\n\n## Tests\n\n```bash\nnpm test\nnpm run test:watch\nnpm run test:cov\n```\n\nCovers:\n\n- merkle root\n- block hashing\n- PoW \u0026 PoS validation\n- tx signing + balance/nonce\n- chain add/replace\n\n---\n\n## Configuration\n\n- `CONSENSUS_MODE` — pow | pos\n- `CRYPTO_MODE` — secp256k1 | falcon\n- `HTTP_PORT` — preferred port (auto-picks next free otherwise)\n\n---\n\n## Troubleshooting\n\n- **Port in use** → set `HTTP_PORT` or let auto-pick.\n- **Peers not connecting** → check firewall; discovery-swarm needs LAN.\n- **Nothing mines** → POST `/mine` for instant PoW demo.\n- **Tx rejected** → wrong nonce, insufficient balance, or crypto mode mismatch.\n\n---\n\n## Next steps\n\n- Add coinbase reward to miner.\n- Persist state in RocksDB.\n- On-chain stakes for PoS.\n- Implement a mempool.\n- Difficulty retarget for PoW.\n- Build a block explorer UI.\n\n---\n\n## Contributing\n\nPRs, issues, and stars welcome 🙌\n\n1. Fork\n2. Branch `feat/my-feature`\n3. Commit + Push\n4. PR 🎉\n\n---\n\n\u003cp align=\"right\"\u003e(\u003ca href=\"#top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fac12644%2Fblockchain-secp-falcon","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fac12644%2Fblockchain-secp-falcon","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fac12644%2Fblockchain-secp-falcon/lists"}