{"id":27804024,"url":"https://github.com/abdelstark/collidervm_toy","last_synced_at":"2025-05-01T08:15:36.093Z","repository":{"id":288234441,"uuid":"962416041","full_name":"AbdelStark/collidervm_toy","owner":"AbdelStark","description":"ColliderVM: Stateful Computation on Bitcoin without Fraud Proofs","archived":false,"fork":false,"pushed_at":"2025-04-30T17:59:52.000Z","size":1710,"stargazers_count":9,"open_issues_count":1,"forks_count":4,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-05-01T08:15:25.760Z","etag":null,"topics":["bitcoin","bitvm","fraud-proofs","starks","zero-knowledge-proofs"],"latest_commit_sha":null,"homepage":"https://eprint.iacr.org/2025/591","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AbdelStark.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":"2025-04-08T06:04:25.000Z","updated_at":"2025-04-30T17:59:57.000Z","dependencies_parsed_at":"2025-04-16T11:14:58.133Z","dependency_job_id":null,"html_url":"https://github.com/AbdelStark/collidervm_toy","commit_stats":null,"previous_names":["abdelstark/collidervm_toy"],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AbdelStark%2Fcollidervm_toy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AbdelStark%2Fcollidervm_toy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AbdelStark%2Fcollidervm_toy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AbdelStark%2Fcollidervm_toy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AbdelStark","download_url":"https://codeload.github.com/AbdelStark/collidervm_toy/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251843656,"owners_count":21652855,"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":["bitcoin","bitvm","fraud-proofs","starks","zero-knowledge-proofs"],"created_at":"2025-05-01T08:15:35.465Z","updated_at":"2025-05-01T08:15:36.087Z","avatar_url":"https://github.com/AbdelStark.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n\u003ca href=\"https://github.com/AbdelStark/collidervm_toy/actions/workflows/test.yml\"\u003e\u003cimg alt=\"GitHub Workflow Status\" src=\"https://img.shields.io/github/actions/workflow/status/AbdelStark/collidervm_toy/test.yml?style=for-the-badge\" height=30\u003e\u003c/a\u003e\n\u003ca href=\"https://bitcoin.org/\"\u003e \u003cimg alt=\"Bitcoin\" src=\"https://img.shields.io/badge/Bitcoin-000?style=for-the-badge\u0026logo=bitcoin\u0026logoColor=white\" height=30\u003e\u003c/a\u003e\n\n\u003c/div\u003e\n\n# ColliderVM Toy Simulation\n\n\u003cdiv align=\"center\"\u003e\n  \u003ch3\u003e\n    \u003ca href=\"https://github.com/AbdelStark/collidervm_toy/discussions/5\"\u003e\n      DEMO\n    \u003c/a\u003e\n    \u003cspan\u003e | \u003c/span\u003e\n    \u003ca href=\"https://eprint.iacr.org/2025/591\"\u003e\n      COLLIDERVM PAPER\n    \u003c/a\u003e\n    \u003cspan\u003e | \u003c/span\u003e\n    \u003ca href=\"https://github.com/AbdelStark/collidervm_toy?tab=readme-ov-file#how-to-run\"\u003e\n      QUICKSTART\n    \u003c/a\u003e\n  \u003c/h3\u003e\n\n  \u003cimg src=\"./docs/images/collidervm-logo-concept.png\" alt=\"Mikan\" width=\"300\"\u003e\n\u003c/div\u003e\n\nThis project provides a simplified Rust simulation of the concepts presented in the [ColliderVM: Stateful Computation on Bitcoin](https://eprint.iacr.org/2025/591) paper. It demonstrates the core mechanisms of ColliderVM, particularly the use of presigned transaction flows and hash collision challenges for enabling stateful computation on Bitcoin without relying on fraud proofs.\n\n**Disclaimer:** This is a _toy_ simulation and does **not** implement a production-ready ColliderVM protocol. It simplifies some aspects for clarity and focuses on the protocol's structural flow and the hash collision mechanism.\n\n## Background: ColliderVM Core Concepts\n\nThe ColliderVM paper proposes a method to achieve stateful computation on Bitcoin, addressing limitations of the Bitcoin script language. Key concepts include:\n\n- **Stateful Computation:** Enabling computations (data \u0026 logic) to persist across multiple Bitcoin transactions.\n- **Actors:**\n  - **Signers (n):** Offline setup participants who create and sign transaction templates (flows). Assume 1-of-n are honest for safety (preventing invalid state transitions).\n  - **Operators (m):** Online execution participants who provide inputs, find nonces via hashing, and broadcast transactions. Assume 1-of-m are honest for liveness (ensuring the process can proceed).\n- **Presigned Flows (`D`):** A set of `2^L` pre-agreed, parallel transaction sequences. Each flow corresponds to a unique identifier `d` from the set `D`.\n- **Hash Collision Challenge:** To ensure the _same_ input `x` is used across steps in a chosen flow `d`, the Operator must find a nonce `r` such that the first `B` bits of a hash `H(x, r)` match that specific flow identifier `d` (i.e., `H(x, r)|_B = d ∈ D`).\n- **Computational Gap:**\n  - **Honest Work:** Finding _any_ valid pair `(x, r)` such that `H(x, r)|_B ∈ D` takes `~2^(B-L)` hash computations.\n  - **Malicious Work (Double Collision):** Finding _two different pairs_ `(x, r) ≠ (x', r')` that map to the _same_ flow `d` (i.e., `H(x, r)|_B = H(x', r')|_B = d`) takes significantly more work (`~2^(B-L/2)`), making it computationally expensive to cheat by using different inputs within the same flow.\n- **Capital Efficiency:** A key goal is to avoid the capital lock-up periods associated with fraud-proof-based systems like BitVM2.\n\n## ColliderVM Toy: Design Choices \u0026 Simplifications\n\nThis simulation implements a minimal proof-of-concept:\n\n- **Simple Function (`F`):** Instead of complex logic (like STARK verification), the computation `F(x)` is split into two subfunctions:\n  - `F1(x)`: Checks if `input_value \u003e 100`.\n  - `F2(x)`: Checks if `input_value \u003c 200`.\n  - The overall computation succeeds only if `F1(x) AND F2(x)` is true for the _same_ input `x` within the chosen flow.\n- **Simulated Actors:** Generates `n` Signers and `m` Operators with `secp256k1` key pairs (`SignerInfo`, `OperatorInfo`), but their roles in complex multi-party signing or liveness are simplified.\n- **Simulated Presigning:** Creates placeholder Bitcoin `Transaction` structures (`create_placeholder_tx`) and calculates simplified sighash messages (`create_toy_sighash_message`). It collects real Schnorr signatures but doesn't handle actual UTXO management or realistic fee calculation.\n- **Simplified Bitcoin Script:**\n  - **Hash Check:** The script check `H(x, r)|_B = d` is executed according to the rules of the paper for the prefix check.\n  - **Signature Check:** Scripts include `OP_CHECKSIGVERIFY` and the Signer's public key. However, the `bitvm::execute_script_buf` function used for simulation does _not_ perform cryptographic signature verification. It checks script logic but assumes signatures are valid if provided.\n- **Limited Flows:** Generates `min(2^L, 16)` flows instead of the full `2^L` for performance reasons in this demo.\n- **Off-Chain Hashing:** The Operator's nonce search (`find_valid_nonce`) uses Rust's `blake3` library to simulate the `~2^(B-L)` off-chain work.\n\n## Project Structure\n\nThe codebase is organized into three main Rust modules:\n\n- **`src/main.rs`**:\n  - The executable entry point.\n  - Parses command-line arguments (for the input value `x`).\n  - Sets up the `ColliderVmConfig` (n, m, L, B, k).\n  - Calls `simulation::run_simulation` to orchestrate the entire process.\n  - Prints the final simulation results.\n- **`src/core.rs`**:\n  - Defines the core data structures (`ColliderVmConfig`, `SignerInfo`, `OperatorInfo`, `PresignedStep`, `PresignedFlow`).\n  - Contains constants (e.g., `F1_THRESHOLD`).\n  - Implements helper functions primarily used _off-chain_ or for setup:\n    - `create_toy_sighash_message`: Simulates sighash generation.\n    - `calculate_flow_id`: Computes `H(x, r)|_B` using Blake3.\n    - `find_valid_nonce`: Simulates the Operator's hash search.\n  - Implements functions to _build_ the Bitcoin locking scripts (`build_script_f1_locked`, `build_script_f2_locked`) incorporating the simplified logic, hash, and signature checks.\n- **`src/simulation.rs`**:\n  - Implements the two main phases of the ColliderVM simulation protocol:\n    - `offline_setup`: Simulates the Signers generating keys and creating/signing all the `PresignedFlow`s for all potential flow IDs `d`.\n    - `online_execution`: Simulates the Operator finding a nonce for a given input `x`, selecting the corresponding flow `d`, constructing the full witness and script, and executing the F1 and F2 scripts.\n  - Uses helper functions and data structures from `core.rs`.\n  - Uses `bitvm::execute_script_buf` to simulate the execution of the constructed Bitcoin scripts.\n\n## Simulation End-to-End Flow\n\nThe `cargo run [input_value]` command triggers the following sequence:\n\n1. **Initialization (`main.rs`)**: Parses the optional `input_value` (or defaults to 114) and sets up the `ColliderVmConfig` (n=3, m=2, L=4, B=8, k=2).\n\n2. **Offline Setup Phase (`simulation::offline_setup`)**: Simulates actions performed by Signers _before_ the input `x` is known.\n\n    - Generates keypairs for 3 Signers and 2 Operators.\n    - Loops `2^L = 16` times (for `flow_id` 0 to 15).\n    - **Inside the loop (for each `flow_id` `d`)**:\n      - **F1 Setup**:\n        - Builds the F1 locking script (`build_script_f1_locked`) containing checks for `x \u003e 100`, `flow_id == d`, and a Signer signature.\n        - Creates a placeholder F1 transaction (`create_placeholder_tx`) spending a dummy input.\n        - Calculates a toy sighash for F1 (`create_toy_sighash_message`).\n        - All 3 Signers sign this sighash, producing signatures.\n        - Stores the F1 template, sighash, signatures, and script in a `PresignedStep`.\n      - **F2 Setup**:\n        - Builds the F2 locking script (`build_script_f2_locked`) containing checks for `x \u003c 200`, `flow_id == d`, and a Signer signature.\n        - Creates a placeholder F2 transaction spending the _output_ of the F1 placeholder transaction.\n        - Calculates a toy sighash for F2.\n        - All 3 Signers sign this sighash.\n        - Stores the F2 template, sighash, signatures, and script in a second `PresignedStep`.\n      - Adds the `PresignedFlow` (containing the F1 and F2 steps) to a `HashMap` keyed by the `flow_id` (`d`).\n    - Returns the generated Signer/Operator info and the `presigned_flows_map`.\n\n3. **Online Execution Phase (`simulation::online_execution`)**: Simulates actions performed by an Operator _after_ the input `x` (`input_value`) is known.\n\n    - **Nonce Search**: Calls `find_valid_nonce(input_value, B, L)`.\n      - This function starts with `nonce = 0`.\n      - It repeatedly calculates `d = calculate_flow_id(input_value, nonce, B, L)` (which computes `Blake3(input_value || nonce)|_B`).\n      - If `d \u003c 2^L` (i.e., `d` is in the set `D` = {0..15}), it returns the successful `(nonce, d)`. This simulates the `~2^(B-L)` = `~2^(8-4)` = `~16` expected hashes.\n      - If not, it increments the nonce and tries again.\n    - **Flow Selection**: Retrieves the `PresignedFlow` for the `flow_id` (`d`) returned by `find_valid_nonce` from the `presigned_flows_map`.\n    - **(Optional) Off-Chain Checks**: Verifies the Signer 0 signature for F1/F2 and the hash calculation `H(x,r)|_B = d` using Rust crypto functions (for logging/debugging).\n    - **F1 Script Execution**:\n      - Constructs the witness script: `script_builder.push(sig_f1).push(flow_id).push(input_value)`.\n      - Concatenates the witness script bytes with the F1 locking script bytes (`step_f1.locking_script`).\n      - Calls `bitvm::execute_script_buf` on the combined script.\n      - Stores the success/failure result (`script_f1_success`).\n    - **F2 Script Execution**:\n      - Constructs the witness script: `script_builder.push(sig_f2).push(flow_id).push(input_value)`.\n      - Concatenates the witness script bytes with the F2 locking script bytes (`step_f2.locking_script`).\n      - Calls `bitvm::execute_script_buf` on the combined script.\n      - Stores the success/failure result (`script_f2_success`).\n    - **Result Calculation**: Determines overall `success` as `script_f1_success \u0026\u0026 script_f2_success`.\n    - Returns a `SimulationResult` containing the success status and results of individual script executions.\n\n4. **Output (`main.rs`)**: Prints a summary message indicating whether the simulation succeeded or failed, based on the returned `SimulationResult`.\n\n## How to Run\n\n- **Prerequisites:** Ensure you have Rust and Cargo installed ([https://www.rust-lang.org/tools/install](https://www.rust-lang.org/tools/install)).\n- **Build:** Navigate to the project directory and build the project:\n\n```bash\nUsage: collidervm_toy [OPTIONS]\n\nOptions:\n  -i, --input \u003cINPUT\u003e\n          Input value to test (default: 114)\n          \n          [default: 114]\n\n  -p, --preset \u003cPRESET\u003e\n          Preset configuration to use\n          \n          [default: default]\n\n          Possible values:\n          - default: Default configuration (quick to run for demos)\n          - medium:  Medium difficulty (10-15 seconds)\n          - hard:    Higher difficulty (~1 minute)\n          - custom:  Custom configuration (use with -n, -m, -l, -b, -k options)\n\n  -s, --signers \u003cSIGNERS\u003e\n          Number of signers (1-of-n honest for safety)\n\n  -o, --operators \u003cOPERATORS\u003e\n          Number of operators (1-of-m honest for liveness)\n\n  -l, --l-param \u003cL_PARAM\u003e\n          Flow set size parameter L (set D size = 2^L)\n\n  -b, --b-param \u003cB_PARAM\u003e\n          Hash prefix bits parameter B\n\n  -k, --k-param \u003cK_PARAM\u003e\n          Number of subfunctions (fixed at 2 for the toy model)\n\n      --hash-rate \u003cHASH_RATE\u003e\n          Skip hash rate calibration and use the provided value\n\n      --no-calibration\n          Disable hash rate calibration\n\n  -h, --help\n          Print help (see a summary with '-h')\n\n  -V, --version\n          Print version\n```\n\n## References\n\n- [ColliderVM: Stateful Computation on Bitcoin](https://eprint.iacr.org/2025/591)\n\n---\n\nStarted with love by [AbdelStark](https://github.com/AbdelStark) 🧡\n\nFeel free to follow me on Nostr if you’d like, using my public key:\n\n```text\nnpub1hr6v96g0phtxwys4x0tm3khawuuykz6s28uzwtj5j0zc7lunu99snw2e29\n```\n\nOr just **scan this QR code** to find me:\n\n![Nostr Public Key QR Code](https://hackmd.io/_uploads/SkAvwlYYC.png)\n\n## Contributors ✨\n\nThanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):\n\n\u003c!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section --\u003e\n\u003c!-- prettier-ignore-start --\u003e\n\u003c!-- markdownlint-disable --\u003e\n\u003ctable\u003e\n  \u003ctbody\u003e\n    \u003ctr\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href=\"https://github.com/AbdelStark\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/45264458?v=4?s=100\" width=\"100px;\" alt=\"A₿del ∞/21M\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eA₿del ∞/21M\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/AbdelStark/collidervm_toy/commits?author=AbdelStark\" title=\"Code\"\u003e💻\u003c/a\u003e \u003ca href=\"https://github.com/AbdelStark/collidervm_toy/commits?author=AbdelStark\" title=\"Documentation\"\u003e📖\u003c/a\u003e \u003ca href=\"#ideas-AbdelStark\" title=\"Ideas, Planning, \u0026 Feedback\"\u003e🤔\u003c/a\u003e\u003c/td\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href=\"https://github.com/eigmax\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/81497928?v=4?s=100\" width=\"100px;\" alt=\"Stephen\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eStephen\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/AbdelStark/collidervm_toy/commits?author=eigmax\" title=\"Code\"\u003e💻\u003c/a\u003e\u003c/td\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href=\"https://github.com/trungnotchung\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/66519569?v=4?s=100\" width=\"100px;\" alt=\"Phạm Xuân Trung\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003ePhạm Xuân Trung\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/AbdelStark/collidervm_toy/commits?author=trungnotchung\" title=\"Code\"\u003e💻\u003c/a\u003e\u003c/td\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href=\"https://github.com/maciejka\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/190855?v=4?s=100\" width=\"100px;\" alt=\"Maciej Kamiński @ StarkWare\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eMaciej Kamiński @ StarkWare\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/AbdelStark/collidervm_toy/commits?author=maciejka\" title=\"Code\"\u003e💻\u003c/a\u003e\u003c/td\u003e\n    \u003c/tr\u003e\n  \u003c/tbody\u003e\n\u003c/table\u003e\n\n\u003c!-- markdownlint-restore --\u003e\n\u003c!-- prettier-ignore-end --\u003e\n\n\u003c!-- ALL-CONTRIBUTORS-LIST:END --\u003e\n\nThis project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fabdelstark%2Fcollidervm_toy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fabdelstark%2Fcollidervm_toy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fabdelstark%2Fcollidervm_toy/lists"}