{"id":28862707,"url":"https://github.com/distributed-lab/op_rand","last_synced_at":"2026-04-02T02:40:41.279Z","repository":{"id":299632019,"uuid":"991897240","full_name":"distributed-lab/op_rand","owner":"distributed-lab","description":"Trustless Randomness Generation on Bitcoin","archived":false,"fork":false,"pushed_at":"2025-06-17T13:28:02.000Z","size":15594,"stargazers_count":9,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-17T14:31:58.996Z","etag":null,"topics":["bitcoin","noir","rust"],"latest_commit_sha":null,"homepage":"https://arxiv.org/pdf/2501.16451","language":"Noir","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/distributed-lab.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-05-28T10:05:53.000Z","updated_at":"2025-06-17T13:28:02.000Z","dependencies_parsed_at":"2025-06-17T14:44:53.291Z","dependency_job_id":null,"html_url":"https://github.com/distributed-lab/op_rand","commit_stats":null,"previous_names":["distributed-lab/op_rand"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/distributed-lab/op_rand","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/distributed-lab%2Fop_rand","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/distributed-lab%2Fop_rand/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/distributed-lab%2Fop_rand/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/distributed-lab%2Fop_rand/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/distributed-lab","download_url":"https://codeload.github.com/distributed-lab/op_rand/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/distributed-lab%2Fop_rand/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260898111,"owners_count":23079226,"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","noir","rust"],"created_at":"2025-06-20T06:39:08.173Z","updated_at":"2026-04-02T02:40:41.273Z","avatar_url":"https://github.com/distributed-lab.png","language":"Noir","funding_links":[],"categories":["Libraries"],"sub_categories":["Blockchain Specifics"],"readme":"# OP_RAND: VRF on Bitcoin\n\n[![Paper](https://img.shields.io/badge/paper-arXiv-red.svg)](https://arxiv.org/pdf/2501.16451)\n\nThis is a method of emulation of OP_RAND opcode on Bitcoin through a trustless interactive game between transaction counterparties. The game result is probabilistic and doesn’t allow any party to cheat, increasing their chance of winning on any protocol step. The protocol is organized in a way unrecognizable to any external party and doesn’t require any specific scripts\nor Bitcoin protocol updates.\n\n## 📖 Overview\n\nOP_RAND allows two (currently) users to create the set of transactions, the UTXO of the final one of which \ncan be spent with some probability by each counterparty. For that, OP_RAND uses:\n\n- **Commitments**: The protocol allows the challenger to create commitments on random values, only one of each  is used for the final address formation. An acceptor also mast create the commitment for their final public key, but without the knowledge if that can be spent.\n- **Zero-Knowledge Proofs**: For proving the correctness of all actions (with hiding the secret data) between challenger and acceptor it uses Noir circuits with Barretenberg backend. \n- **Bitcoin Script**: OP_RAND doesn't require and update of the Bitcoin protocol or appearance of new op codes\n- **Interactive Protocol**: Two-party commit-reveal scheme\n\n### Key Features\n\n- 🎲 **True Randomness**: Cryptographically secure 50/50 outcomes\n- 🔒 **Trustless**: No third parties or oracles required\n- 🕵️ **Private**: Commitment selection hidden until revelation\n- ✅ **Verifiable**: All parties can verify proof correctness\n- 🏃 **Fast**: Efficient zero-knowledge proof generation and verification\n- 💰 **Economic**: Winner-takes-all incentive mechanism\n- 👻 **Stealthy**: Appears as normal Bitcoin transactions\n\n## 🏗️ Architecture\n\nThe project consists of several key components:\n\n### Core Crates\n\n- **`op-rand-types`** - Fundamental data structures and commitment types\n- **`op-rand-prover`** - Zero-knowledge proof generation and verification using Barretenberg\n- **`op-rand-transaction-builder`** - Bitcoin transaction construction utilities\n\n### Applications\n\n- **`apps/cli`** - Full-featured command-line interface for protocol interaction\n\n### Circuits\n\n- **`circuits/crates/challenger_circuit`** - ZK circuit for challenger proofs\n- **`circuits/crates/acceptor_circuit`** - ZK circuit for acceptor proofs\n- **`circuits/crates/common`** - Shared cryptographic utilities\n\n## 🚀 Installation\n\n### From Source\n\n```bash\n# Clone the repository\ngit clone https://github.com/distributed-lab/op_rand\ncd op_rand\n\n# Build the project\ncargo build --release\n\n# Install the CLI globally\ncargo install --path apps/cli\n```\n\n### Verify Installation\n\n```bash\nop-rand-cli --help\n```\n\n## 🎮 Quick Start\n\n### 1. Setup Configuration\n\nCreate a `config.toml` file:\n\n```toml\n# Your Bitcoin private key (WIF format)\nprivate_key = \"cVt4o7BGAig1UXywgGSmARhxMdzP5qvQsxKkSsc1XEkw3tDTQFpy\"\n\n# Esplora API endpoint\nesplora_url = \"https://blockstream.info/testnet/api\"\n\n# Bitcoin network (testnet, regtest, bitcoin)\nnetwork = \"testnet\"\n```\n\n\u003e ⚠️ **Security Warning**: Never use mainnet private keys with real funds in development environments.\n\n### 2. Complete Workflow Example\n\n#### As Challenger (Party A):\n\n```bash\n# Create a 100,000 satoshi challenge\nop-rand-cli create-challenge --amount 100000 --locktime 144\n\n# This creates:\n# - challenger.json (share with acceptor)\n# - private_challenger.json (keep secret)\n```\n\n#### As Acceptor (Party B):\n\n```bash\n# Inspect the challenge first\nop-rand-cli info --challenge-file challenger.json\n\n# Accept the challenge by selecting a commitment\nop-rand-cli accept-challenge \\\n  --challenge-file challenger.json \\\n  --selected-commitment 0\n\n# This creates:\n# - acceptor.json (send back to challenger)\n```\n\n#### Complete the Challenge (Challenger):\n\n```bash\n# Finalize and broadcast the challenge\nop-rand-cli complete-challenge \\\n  --challenger-file challenger.json \\\n  --challenger-private-file private_challenger.json \\\n  --acceptor-file acceptor.json\n\n# Returns: Transaction ID and reveals the random outcome\n```\n\n#### Claim Winnings:\n\n```bash\n# The winner can spend the locked funds\nop-rand-cli try-spend \\\n  --challenge-tx \"transaction_hex_from_previous_step\" \\\n  --challenger  # or --acceptor depending on who won\n```\n\n## 📚 Documentation\n\n- **[CLI Reference](apps/cli/README.md)** - Complete command-line interface documentation\n- **[Research Paper](https://arxiv.org/pdf/2501.16451)** - \"Emulating OP_RAND in Bitcoin\" by Rarimo Protocol\n\n## 🔬 How It Works\n\n### Protocol Overview\n\n1. **Commitment Phase**: Challenger generates cryptographic commitments to secret values\n2. **Challenge Creation**: Zero-knowledge proof demonstrates commitment validity\n3. **Acceptance Phase**: Acceptor blindly selects one commitment and provides their own proof\n4. **Revelation Phase**: Challenger reveals selected commitment, determining the winner\n5. **Settlement Phase**: Winner can claim the locked Bitcoin funds\n\n### Cryptographic Guarantees\n\n- **Unpredictability**: Neither party can predict the outcome\n- **Fairness**: Each party has exactly 50% probability of winning\n- **Binding**: Commitments cannot be changed after creation\n- **Hiding**: Commitment selection remains private until revelation\n- **Verifiability**: All proofs can be independently verified\n\n### Zero-Knowledge Circuits\n\nThe protocol uses two main ZK circuits:\n\n- **Challenger Circuit**: Proves knowledge of commitment secrets without revealing them\n- **Acceptor Circuit**: Proves valid signature and commitment selection\n\n## 🛠️ Development\n\n### Project Structure\n\n```\nop_rand/\n├── apps/\n│   └── cli/                    # Command-line interface\n├── crates/\n│   ├── types/                  # Core data structures\n│   ├── prover/                 # ZK proof system\n│   └── transaction-builder/    # Bitcoin transaction utilities\n├── circuits/\n│   └── crates/\n│       ├── challenger_circuit/ # Challenger ZK circuit\n│       ├── acceptor_circuit/   # Acceptor ZK circuit\n│       └── common/             # Shared circuit utilities\n└── target/                     # Build artifacts\n```\n\n## 🏢 About\n\nDeveloped by [Distributed Lab](https://distributedlab.com/)\n\n## 🔗 Links\n\n- 📖 **[CLI Documentation](apps/cli/README.md)**\n- 📄 **[Research Paper](https://arxiv.org/pdf/2501.16451)**\n\n## 🎯 TODO\n- Support of P2TR addresses\n- Implement flexible probability (better than 1/n)\n\n## 🙏 Acknowledgments\n\nSpecial thanks to [passport-zk-circuits-noir](https://github.com/rarimo/passport-zk-circuits-noir) contributors for secp256k1 circuits which were instrumental in implementing the cryptographic primitives for this project.\n\n---\n\n_Build trustless randomness on Bitcoin with cryptographic guarantees._\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdistributed-lab%2Fop_rand","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdistributed-lab%2Fop_rand","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdistributed-lab%2Fop_rand/lists"}