{"id":49560731,"url":"https://github.com/pool2win/bitcoin-contracts-tlaplus","last_synced_at":"2026-05-03T08:15:11.172Z","repository":{"id":196819706,"uuid":"697200376","full_name":"pool2win/bitcoin-contracts-tlaplus","owner":"pool2win","description":"Bitcoin layer 2 contracts specifications using TLA+","archived":false,"fork":false,"pushed_at":"2023-10-19T13:09:31.000Z","size":5219,"stargazers_count":2,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2023-10-19T13:43:33.884Z","etag":null,"topics":["bitcoin","lightning","lightning-network","tla-plus"],"latest_commit_sha":null,"homepage":"","language":"TLA","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pool2win.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}},"created_at":"2023-09-27T08:57:38.000Z","updated_at":"2023-10-23T11:36:50.974Z","dependencies_parsed_at":"2023-09-27T19:31:56.470Z","dependency_job_id":"a8c16d85-35c0-4da2-8359-f0322949ef88","html_url":"https://github.com/pool2win/bitcoin-contracts-tlaplus","commit_stats":null,"previous_names":["pool2win/lightning-network-tlaplus"],"tags_count":0,"template":null,"template_full_name":null,"purl":"pkg:github/pool2win/bitcoin-contracts-tlaplus","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pool2win%2Fbitcoin-contracts-tlaplus","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pool2win%2Fbitcoin-contracts-tlaplus/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pool2win%2Fbitcoin-contracts-tlaplus/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pool2win%2Fbitcoin-contracts-tlaplus/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pool2win","download_url":"https://codeload.github.com/pool2win/bitcoin-contracts-tlaplus/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pool2win%2Fbitcoin-contracts-tlaplus/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32562234,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-03T06:36:36.687Z","status":"ssl_error","status_checked_at":"2026-05-03T06:36:09.306Z","response_time":103,"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":["bitcoin","lightning","lightning-network","tla-plus"],"created_at":"2026-05-03T08:15:07.992Z","updated_at":"2026-05-03T08:15:11.165Z","avatar_url":"https://github.com/pool2win.png","language":"TLA","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n** Read [Notes on lighting contracts](./lightning-contracts-notes.md) **\n\n# Bitcoin layer two contracts and communication protocols in TLA+\n\n\n## Problem\n\nLayer 2 contracts for bitcoin are hard to reason about. Often times it\ncomes down to writing contracts in code and then running\nsimulations. However, simulations are expensive to write and it is\neven harder to cover all the corner cases.\n\n## Goals\n\nCapture L2 protocols in TLA+ to helps us think about the the\nbehaviours these contracts support, as well as explore corner cases\nwithout dealing with complicated programming language issues.\n\nThere are two simple goals of this repo:\n\n1. Provide basis to capture layer 2 contracts in TLA+.\n2. Exercise the communication protocols required to implement layer 2\n   contracts - this can have some dependencies on 1.\n\nTo develop the above two we start with lightning network. By using the\nabove two to capture behaviours of LN contracts we can state the\nproject's goals have been achieved.\n\n\n## Progress\n\n### October 2023\n\n#### BitcoinTransactions module with Unspent Outputs\n\nAdded helper functions to find unspent outputs. This came from the\nwork on moving LNContracts to use the new BitcoinTransactions module.\n\n#### Separate module for Bitcoin Transactions\n\nAfter working on simple dual LN channels (without HTLCs), it became\nclear how we can move the bitcoin transactions and bitcoin chain\ndetails into a separate module. I started on it and there is now a\n`BitcoinTransactions.tla` module where we can move the complications\nof creating, broadcasting and spending bitcoin transactions of various\ntypes. This change will allow us to focus only on the behaviour of\nparties when creating LN transactions in `Contracts.tla`.\n\nAt the moment the BitcoinTransactions modules only has a simple\ntransaction. I'll be adding multisig and htlc transaction types\nthere. This way the LN contracts can extend that module and focus only\non the LN contracts behaviours.\n\n#### Lightning contracts\n\nAdded the initial commitment, superseding, offending and breach remedy\ntransactions. Added liveness properties for breach remedy\ntransactions. I am capturing notes on lightning contracts\n[here](lightning-contracts-notes.md).\n\n#### Moving Bitcoin Txs out of Contracts.tla\n\nIt will be nice to separate out bitcoin actions and variables in to a\nseparate module.\n\nWorking on LN Contracts showed how we can move some of the Bitcoin\nrelated actions into a separate module. For example, the mempool,\npublished, chain_height and Broadcast*Tx can move to a Bitcoin\nmodule.\n\nWe kind of knew it would make sense but working LN contracts makes\nthings much cleaner in terms of what we want to model. For example, we\ndon't need to model all the Script opcodes, instead, we allow\nmodelling of how a tx can be spent. We can also incorporate sighash\nrules without actually implementing the nitty gritty of it all.\n\n### September 2023\n\n#### HTLC\n\nThe first protocol I am interested in capturing is the HTLC forwarding\nprotocol as specified in [Bolt #2 section on forwarding\nHTLC](https://github.com/lightning/bolts/blob/master/02-peer-protocol.md#forwarding-htlcs)\n\nYou can see the initial HTLC protocol in [htlc.pdf](./htlc.pdf). Note,\nthe spec needs some changes to move the focus from HTLC to commitment\ntransaction instead. I am parking this for the moment and switching to\nwork on specifying L2 contracts - we need this to make the project a\nsuccess.\n\n#### Bitcoin contracts\n\nThis is a challenging goal, and the initial design captures the\nbehaviour of a bitcoin transaction. So the spec is for a bitcoin\ntransaction - that is the system we spec. The environment is made up\nof keys, signatures, UTXO set, chain height and spend conditions that\ncan attached to transactions.\n\nA transaction can thus be created and acted up by the various actors\nin the environment and the transaction can then move from state to\nstate - specifying it's behaviour. L2 protocol authors will then write\nnew spend conditions and be able to check if the transaction behaviour\nsupport the properties the want from the protocol.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpool2win%2Fbitcoin-contracts-tlaplus","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpool2win%2Fbitcoin-contracts-tlaplus","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpool2win%2Fbitcoin-contracts-tlaplus/lists"}