{"id":50500628,"url":"https://github.com/prof-faustus/bonded-subsat-channel","last_synced_at":"2026-06-02T11:02:06.524Z","repository":{"id":361170885,"uuid":"1253336829","full_name":"prof-faustus/bonded-subsat-channel","owner":"prof-faustus","description":"Bonded sub-satoshi channels on BSV (post-Genesis) — reference implementation + standalone embedded node, wallet, and watchtower.","archived":false,"fork":false,"pushed_at":"2026-05-29T13:34:58.000Z","size":124,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-29T14:04:19.974Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","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/prof-faustus.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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-29T11:08:43.000Z","updated_at":"2026-05-29T13:31:22.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/prof-faustus/bonded-subsat-channel","commit_stats":null,"previous_names":["prof-faustus/bonded-subsat-channel"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/prof-faustus/bonded-subsat-channel","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prof-faustus%2Fbonded-subsat-channel","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prof-faustus%2Fbonded-subsat-channel/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prof-faustus%2Fbonded-subsat-channel/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prof-faustus%2Fbonded-subsat-channel/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/prof-faustus","download_url":"https://codeload.github.com/prof-faustus/bonded-subsat-channel/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prof-faustus%2Fbonded-subsat-channel/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33818568,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-02T02:00:07.132Z","response_time":109,"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":"2026-06-02T11:02:05.879Z","updated_at":"2026-06-02T11:02:06.518Z","avatar_url":"https://github.com/prof-faustus.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Bonded Sub-Satoshi Channels (BSV, post-Genesis) — Reference Implementation\n\n[![CI](https://github.com/prof-faustus/bonded-subsat-channel/actions/workflows/ci.yml/badge.svg)](https://github.com/prof-faustus/bonded-subsat-channel/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![Python](https://img.shields.io/badge/python-3.11%20%7C%203.12-blue.svg)](pyproject.toml)\n\n\u003e **⚠ RESEARCH CODE — NOT FOR PRODUCTION USE.** This is a reference\n\u003e implementation accompanying an academic paper. It runs in **regtest only**\n\u003e by default. Do not connect it to mainnet, do not put real funds in it.\n\u003e See [LICENSE](LICENSE) and [docs/PRIVACY.md](docs/PRIVACY.md).\n\nThis repository is the reference implementation accompanying the paper on\n**bonded sub-satoshi channels** for Bitcoin SV in its post-Genesis form.\nIt demonstrates three claims:\n\n1. **Sub-satoshi divisibility under exact whole-satoshi settlement.** A funded\n   satoshi is subdivided off-chain into `k` micro-units; on-chain settlement is\n   always in whole satoshis, reconciled by a deterministic netting rule `Q*`.\n2. **Fixed risked capital of one bonded satoshi per participant.** Risked\n   capital is independent of payment size and path length.\n3. **Economic deterrence by bond forfeiture.** A superseded broadcast forfeits\n   the offender's bond; honest cooperative settlement is the unique rational\n   outcome.\n\nThe construction uses only original-protocol primitives that remain meaningful\non post-Genesis BSV: integer-valued outputs, `nSequence`/`nLockTime`\ntransaction finality (the original replacement rule), SIGHASH flags, and\nlocking scripts built from `OP_HASH160`, `OP_EQUALVERIFY`, `OP_CHECKSIG`,\n`OP_IF`/`OP_ELSE`/`OP_ENDIF`, and `OP_CHECKMULTISIG`.\n\nCrucially, `OP_CHECKLOCKTIMEVERIFY` and `OP_CHECKSEQUENCEVERIFY` are inert\nno-ops on post-Genesis BSV; this implementation therefore **never** places\nany in-script timelock opcode in any locking script. Timing is enforced\nexclusively at the transaction level by `nLockTime` / `nSequence`.\n\n## Install\n\nPython 3.11+ is required.\n\n```\npip install -r requirements.txt\n```\n\n`bitcoinx` depends on a native `secp256k1` build. On Debian/Ubuntu install:\n\n```\nsudo apt-get install -y libsecp256k1-dev\n```\n\nIf the wheel fails to build on your platform, fall back to conda:\n\n```\nconda create -n channel python=3.11\nconda activate channel\nconda install -c conda-forge secp256k1\npip install -r requirements.txt\n```\n\n## Run tests\n\n```\npytest -v\nmypy src/\n```\n\nOptional 9000-party scale test:\n\n```\npytest -v -m slow\n```\n\n## CLI\n\nAfter install:\n\n```\nchannel open --parties 4 --k 1000 --funded 1 --bond 1\nchannel transfer --script transfers.json\nchannel close\nchannel contested\n```\n\nUse `--log-level DEBUG` to see structured logs.\n\n## Interpreter execution methodology (the hard rule)\n\nEvery spend in the test suite is executed through the real Bitcoin Script\ninterpreter exposed by `bitcoinx`:\n\n```python\nfrom bitcoinx import TxInputContext, InterpreterLimits, MinerPolicy\nlimits = InterpreterLimits(policy, is_genesis_enabled=True, is_consensus=True)\nTxInputContext(tx, input_index, utxo).verify_input(limits, is_utxo_after_genesis=True)\n```\n\nSignature spot-checks (verifying a signature in Python rather than running the\nscript through the VM) are **not** used as a substitute. Negative tests fail\ninside the interpreter, not in hand-written Python guards.\n\n## One-command quickstart\n\n```bash\n./scripts/quickstart.sh              # full flow: venv + tests + tiny-transfers + Phase 12\n./scripts/quickstart.sh --with-docker # also build + run the Docker image\n./scripts/quickstart.sh --cleanup    # remove the venv + Docker image\n```\n\nOn Windows / PowerShell:\n\n```powershell\n.\\scripts\\quickstart.ps1\n.\\scripts\\quickstart.ps1 -WithDocker\n.\\scripts\\quickstart.ps1 -Cleanup\n```\n\nThe full flow (without Docker) takes about **30 s** on a modern host.\nIt creates a `.venv-quickstart/` venv, runs the test suite + mypy +\nbandit, runs the tiny-transfers demo (sub-satoshi off-chain, integer\non-chain), and prints the Phase 12 end-to-end transcript.\n\nSee **[docs/QUICKSTART.md](docs/QUICKSTART.md)** for the full\nstep-by-step walkthrough.\n\n### Just the demo\n\n```bash\npython scripts/tiny_transfers_demo.py                            # default: n=4, k=1000, 200 transfers\npython scripts/tiny_transfers_demo.py --k 1000000 --transfers 1000 # finer granularity\n```\n\n## Documentation\n\n| File | Purpose |\n|---|---|\n| `docs/QUICKSTART.md` | Step-by-step walkthrough for the quickstart scripts |\n| `docs/REPORT.md` | Full technical report with proofs and §10.8 line-level proof→test→source map |\n| `docs/AUDIT.md` | Audit findings (G1–G10 + P1–P7 + L) and their resolution |\n| `docs/DECISIONS.md` | Recorded design decisions (D1–D14) |\n| `docs/PRIVACY.md` | Privacy properties, on-chain leaks, and a six-item privacy roadmap |\n| `docs/PHASE12_TRANSCRIPT.txt` | Last successful Phase 12 transcript (regenerated by each test run) |\n| `LICENSE` | MIT license with research-code notice |\n\n## Safety\n\n- The CLI prints a `RESEARCH CODE` banner by default; suppress with `--no-banner`.\n- Mainnet mode is opt-in: `--mainnet --i-understand-this-is-research-code`.\n- See `src/channel/safety.py` and `tests/test_safety.py`.\n\n## Part II — standalone consumer-ready BSV system\n\nThe package extends Part I (the channel reference implementation) with a\nfully self-contained BSV system, runnable on one machine with **zero\nexternal services**.\n\nComponents:\n\n- `channel.node` — embedded BSV node: native P2P wire protocol\n  (`version`/`verack`, `ping`/`pong`, `inv`/`getdata`, `tx`, `block`,\n  `headers`/`getheaders`), header PoW chain with cumulative-work\n  longest-chain selection, SQLite-backed block/UTXO store, mempool with\n  conflict detection and original-protocol replacement, and an\n  `EmbeddedNode` regtest run mode that generates blocks locally.\n- `channel.wallet` — full HD wallet: BIP32-style derivation, encrypted\n  seed storage, UTXO tracking against the embedded node, coin selection,\n  fee-aware transaction construction, and high-level `pay_p2pkh`.\n- `channel.watchtower` — custody-free watchtower that **discharges the\n  liveness assumption** of Part I. Monitors the node's mempool, detects\n  superseded-state broadcasts, rebroadcasts the current state under the\n  replacement rule, and executes pre-signed bond forfeitures.\n- `channel.store` — durable system store (SQLite) for wallet seed,\n  channel states, bond records, and the tower registry.\n- `channel.runtime` — per-channel lock-based concurrency: many channels\n  in parallel; per-channel transfers serialised; closes use the latest\n  committed state.\n- `channel.fees` — per-byte fee model, whole-satoshi only.\n- `channel.obs` — structured logging, in-process metrics counters, health\n  snapshot.\n- `channel.daemon` — service daemon (TCP loopback, JSON line protocol)\n  hosting node + wallet + manager + tower.\n\n### Running the daemon\n\n```\nchannel daemon-start --port 9000 --db /tmp/system.sqlite\n```\n\nThe daemon listens on `127.0.0.1:\u003cport\u003e` (a local control surface only,\nnot an external API). Issue commands from a separate process:\n\n```\nchannel ping --port 9000\nchannel status --port 9000\nchannel node-generate --port 9000 --payout-hex \u003chex of pubkey\u003e\nchannel daemon-stop --port 9000\n```\n\n### Integration test transcript\n\n`pytest tests/test_integration.py -v -s` runs the full Phase 12\nend-to-end flow:\n\n```\n[1] init wallet\n[2] embedded regtest node up; tip = genesis at h=0\n[3] wallet funded; balance = 5000000000 satoshis at h=1\n[4] opened channel 1 (4 parties, k=10000, S=1)\n[5] applied 250 transfers on channel 1\n[6] routed payment over 3 hops; every hop settled (secret revealed)\n[7] cooperative close of channel 1; settled 5 sat (expected 5)\n[8] watchtower intervened on stale state and overtook it\n    watchtower forfeited bond of party 0 (1 sat)\n[9] conservation: channel 1 sum(Q*) = 1 == S = 1\n[10] simulating restart; recovered channel produced a verifying coop close\nPhase 12 — PASSED\n```\n\nEvery spend in every step is verified through the real Bitcoin Script\ninterpreter; no signature spot-checks substitute for VM execution.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprof-faustus%2Fbonded-subsat-channel","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fprof-faustus%2Fbonded-subsat-channel","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprof-faustus%2Fbonded-subsat-channel/lists"}