{"id":13619945,"url":"https://github.com/FairgateLabs/rust-bitcoin-script-stack","last_synced_at":"2025-04-14T18:32:44.040Z","repository":{"id":239187659,"uuid":"798454485","full_name":"FairgateLabs/rust-bitcoin-script-stack","owner":"FairgateLabs","description":"Helper lib to write complex bitcoin scripts","archived":false,"fork":false,"pushed_at":"2025-04-03T22:54:12.000Z","size":164,"stargazers_count":18,"open_issues_count":0,"forks_count":15,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-04-03T23:29:11.755Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/FairgateLabs.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}},"created_at":"2024-05-09T20:10:29.000Z","updated_at":"2024-12-12T01:33:28.000Z","dependencies_parsed_at":"2024-05-10T15:48:02.802Z","dependency_job_id":"380105f1-4267-4b9a-819f-3b4e747400c5","html_url":"https://github.com/FairgateLabs/rust-bitcoin-script-stack","commit_stats":null,"previous_names":["fairgatelabs/rust-bitcoin-script-stack"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FairgateLabs%2Frust-bitcoin-script-stack","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FairgateLabs%2Frust-bitcoin-script-stack/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FairgateLabs%2Frust-bitcoin-script-stack/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FairgateLabs%2Frust-bitcoin-script-stack/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/FairgateLabs","download_url":"https://codeload.github.com/FairgateLabs/rust-bitcoin-script-stack/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248936975,"owners_count":21186135,"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-01T21:00:50.424Z","updated_at":"2025-04-14T18:32:43.691Z","avatar_url":"https://github.com/FairgateLabs.png","language":"Rust","funding_links":[],"categories":["Libraries"],"sub_categories":["Potential Use Case"],"readme":"### Disclaimer\nThis is a work in progress library and future changes might break backward compatibility. \n\n### Bitcoin Script Stack\n\nThis library aims to help in the development of complex bitcoin scripts.\n\nIn the process of creating an optimized version of SHA256 on chain, it was necessary to track the position of moving parts on the stack and a lot of debugging effort.\n\nStackTracker and StackVariable are the core parts of this lib and as this an example of usage it that allows to do the following:\n```\nlet mut stack = StackTracker::new();    //creates the tracker\n                                        // STACK:\nlet var1 = stack.number(1);             // 1\nlet var2 = stack.number(10);            // 1 10\nlet copy_of_1 = stack.copy_var(var1);   // 1 10 1\nstack.move_var(\u0026mut var2);              // 1 1 10\nstack.drop(var2);                       // 1 1\nstack.op_equalverify();                 // \nstack.op_true();                        // 1\nassert!(stack.run().success)\n```\n\n### Debugging\nDebugging the scripts\n\nAt any moment that StackTracker objects are being constructed it is possible to debug its internal state using the functions inside the debugger.\ni.e:\n\n```\nlet mut stack = StackTracker::new();        //creates the tracker\n                                        // STACK:\nlet var1 = stack.number(1);             // 1\nlet mut var2 = stack.number(10);        // 1 10\nlet copy_of_1 = stack.copy_var(var1);   // 1 10 1\n....\nstack.debug();\n...\n\n```\nThis would output something like this:\n```\nLast opcode: \"OP_PICK\"\n======= STACK: ======\nid: 1       | size: 1       | name: number(0x1)          |  1\nid: 2       | size: 1       | name: number(0xa)          |  a\nid: 3       | size: 1       | name: copy(number(0x1))    |  1\n==== ALT-STACK: ====\n```\n\n### Interactive Debugging\nThere is also an interactive debugger that allows running the script step by step.\nTake a look to [examples/interactive.rs](examples/interactive.rs)\nTo enable it it requires `--features interactive`\n\n```\nInteractive mode. n: next bp | p: previous bp | Step commands: \u003c- (-1) | -\u003e (+1) | Up (-100) | Down (+100) | PgUp (-100) | PgDown (+100) | +Shift (x10) | t (trim) | q (exit)\nStep: 8 BP:\nLast opcode: OP_TOALTSTACK\n======= STACK: ======\nid: 1       | size: 1       | name: number(0x1)          |  1\nid: 2       | size: 1       | name: number(0xa)          |  a\n==== ALT-STACK: ====\nid: 7       | size: 1       | name: OP_ADD()             |  8\n```\n\n### Breakpoints\nWhen writing complex functions or scripts that perform a lot of operations, tracking the right step becomes a challenge.\nSo it's is possible to set up breakpoints that will make the debugging easier.\n```\nstack.custom(....)                          // some complex operation\nstack.set_breakpoint(\"breakpoint-name-1\");  // set breakpoint\n```\n\n### OP_ROLL\nOp roll is not implemented as direct operation as the modification of the stack can not be calculated in advance.\nUse `move_var` and `move_var_sub_n` to achieve the same goal, and take advantage of position tracking.\n\n\n### Conditionals\nFor now, conditional branches are not 100% supported.\nThe main constraint is that on each branch result in the same amount of variables consumed and produced needs to be the same.\n\nThere are two ways of using it: \nWith `custom` (or `custom_ex`) and writing the script as it is done in this example: `test_conditional` on [src/stack.rs](src/stack.rs)\n\nOr using `open_if` and `end_if`. The first function returns two copies of the stack, one for the true branch and one for the false branch.\nTake a look to the example:\n`test_open_if` on [src/stack.rs](src/stack.rs). Some internal branch debugging seems to be possible but it was not very well tested yet.\n\nAt some point a different way to handle conditionals might be implemented as part of the lib, allowing bettery debugging of each branch.\n\n\n### OP_IFDUP\nAs this op modifies the stack depth at runtime it is not possible to implement it here.\n\n-----\n\n### TODO:\nList of pending tasks:\n- Improve branching debugging \n- Define transaction templates to validate withness inputs \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FFairgateLabs%2Frust-bitcoin-script-stack","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FFairgateLabs%2Frust-bitcoin-script-stack","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FFairgateLabs%2Frust-bitcoin-script-stack/lists"}