{"id":13651080,"url":"https://github.com/friedger/clarity-bitcoin","last_synced_at":"2025-04-22T22:30:27.931Z","repository":{"id":65681022,"uuid":"400448556","full_name":"friedger/clarity-bitcoin","owner":"friedger","description":"Clarity library for parsing Bitcoin transactions and verifying Merkle proofs","archived":false,"fork":true,"pushed_at":"2023-12-03T18:01:05.000Z","size":185,"stargazers_count":15,"open_issues_count":7,"forks_count":7,"subscribers_count":4,"default_branch":"main","last_synced_at":"2024-05-01T18:04:03.537Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Clarity","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"jcnelson/clarity-bitcoin","license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/friedger.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}},"created_at":"2021-08-27T08:56:11.000Z","updated_at":"2024-04-27T02:32:10.000Z","dependencies_parsed_at":"2023-02-18T12:45:21.235Z","dependency_job_id":null,"html_url":"https://github.com/friedger/clarity-bitcoin","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/friedger%2Fclarity-bitcoin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/friedger%2Fclarity-bitcoin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/friedger%2Fclarity-bitcoin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/friedger%2Fclarity-bitcoin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/friedger","download_url":"https://codeload.github.com/friedger/clarity-bitcoin/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250333847,"owners_count":21413468,"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","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":"2024-08-02T02:00:44.824Z","updated_at":"2025-04-22T22:30:27.921Z","avatar_url":"https://github.com/friedger.png","language":"Clarity","funding_links":[],"categories":["Clarity Resources"],"sub_categories":["Libraries \u0026 Protocols"],"readme":"# Introduction\n\nA Clarity library for parsing Bitcoin transactions and verifying Merkle proofs\n\nBased on work from [Jude Nelson](https://github.com/jcnelson/clarity-bitcoin) and from the team at [Trust Maschine](https://github.com/Trust-Machines/stacks-sbtc/tree/main/sbtc-mini) (in particular @FriendsFerdinand, @MarvinJanssen, @setzeus, @jo-tm).\n\nDeployments on mainnet:\n\n- [Version 5](https://explorer.hiro.so/txid/0xfe25941d97a1b965b09699b622ec1d701997be62708dbac2e7a8c36a49e3e9bc?chain=mainnet): Adds support for txid generation and improves security to reject left over data\n- [Version 4](https://explorer.hiro.so/txid/0x7442d23307f2d7e9ec67eb1d63d643321cdc8bb603a375888f9c1f5bed9fb5d8?chain=mainnet): Adds support for segwit transactions\n- [Version 3](https://explorer.hiro.so/txid/0xd493b9ada8899be8773d3f55b21d300ef83ac5c0dd38c8a4dd52a295bd71d539?chain=mainnet): Uses get-burn-block-info of Clarity V2 to verify txs in flash blocks\n- Version 2: Buggy - Do not use\n- [Version 1](https://explorer.hiro.so/txid/0x8b112f2b50c1fa864997b7496aaad1e3940700309a3fdcc6c07f1c6f8b9cfb7b?chain=mainnet): Initial version with no verification for tx in flash blocks\n\nBranch (`docs`)[https://github.com/friedger/clarity-bitcoin/tree/docs] contains a gitbook: (Clarity \u003c-\u003e Bitcoin Library)[https://clarity-bitcoin.gitbook.io/clarity-bitcoin-library/].\n\n## Clarity Functions\n\nThe main function is about verifying that a non-segwit transaction was mined in a certain bitcoin block. The verification happens in two steps:\n\n1. compare the provided block header information with the actual chain\n2. compare the merkle root from the provided merkle proof with the merkle root of the provided block header\n\n### Was Tx Mined?\n\nThese are the main functions that can be used to verify that a tx was mined in a given bitcoin block.\n\nThe block header can be provided as an object with the header details or as a buffer.\n\n- was-tx-mined-compact (header as a buffer)\n- was-segwit-tx-mined-compact (header as buffer)\n\nThe two functions for non-segwit transaction take the following arguments in the same order:\n\n1. Bitcoin block height\n2. Raw tx hex\n3. Bitcoin block header either as hex or as a tuple\n4. Merkle proof\n\nThe header object has the following properties using the reverse hex of the shown values in the bitcoin explorer:\n\n- version: (buff 4)\n- parent: (buff 32)\n- merkle-root: (buff 32)\n- timestamp: (buff 4)\n- nbits: (buff 4)\n- nonce: (buff 4)\n\nThe function for segwit transaction takes the following arguments:\n\n1. Bitcoin block height\n2. Raw tx hex\n3. Bitcoin block header either as hex\n4. The index of the tx in the block\n5. The Merkle tree depth of the block\n6. The Merkle proof for witness data\n7. The Merkle root for witness data stored in the coinbase tx of the block\n8. The reserved data value used in the coinbase tx\n9. The coinbase tx in non-segwit format\n10. The Merkle proof of the coinbase tx\n\n### Verification Functions for Non-Segwit Transactions in Bitcoin Block\n\nThe verification happens in two steps:\n\n1. verify that the hash of the given header is equal to the header hash of the given block height.\n2. verify that the given merkle proof for the given transaction id results in the merkle root contained in the header.\n\n- verify-block-header\n- verify-merkle-proof\n\n### Verification Functions for Segwit Transactions in Bitcoin Block\n\nThe verification happens in two steps:\n\n1. verify that the coinbase tx was mined using the verification for non-segwit transactions as described above.\n2. verify that the Merkle root for witness data is contained in the coinbase tx.\n3. verify that the Merkle proof for witness data is valid for the wtxid of the transaction.\n\n- get-commitment-scriptPubKey\n\n### Helper Function for Tx Verification\n\nOnce the tx id was confirmed to be mined in the given block, the inputs and outputs of the tx can be used to trigger certain actions in a smart contract. To verify e.g. that an input is indeed an input of the verified tx id, the hash of a transaction buffer must match the tx id. Then the inputs and outputs of the transaction can be used either\n\n- by parsing the transaction buffer into an object with inputs, outputs, timelock, etc. or\n- by concatenating the transaction object to a buffer with the correct hash.\n\n## Examples\n\nAs requirements, `clarinet` and `deno` needs to be installed.\n\n### Send to First Input\n\nThis example sends an amount of STX to the sender of a bitcoin transaction using p2pkh addresses. It exists in two version, one using the header object, the other the header buffer (compact).\n\n1. Deploy all contracts\n\n```\nclarinet integrate\n```\n\n2. Call deployment plan to send 0.1 BTC\n\n```\nclarinet deployments apply -p deployments/send-btc.devnet-plan.yaml --no-dashboard\n```\n\n3. Confirm to continue\n4. Copy the tx hex from the Transaction\n5. Press N to mine the block in the clarinet dashboard\n6. Generate deployment plan for the stacks transaction by running the following command with the copied tx hex (replace `01..txhex`). (The generation script takes care of reversing the properties of the block header.)\n\n```\ndeno run --allow-net ./src/generatePlan.ts 01..txhex \u003e deployments/send-to-first-input-plan.yaml\n```\n\n7. Call deployment plan to send STX to the bitcoin sender\n\n```\nclarinet deployments apply -p deployments/sent-to-first-input-plan.yaml\n```\n\n8.  Check the stacks explorer at localhost: 8001 about the result for the transactions of the two versions\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffriedger%2Fclarity-bitcoin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffriedger%2Fclarity-bitcoin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffriedger%2Fclarity-bitcoin/lists"}