BitVM Bridge CLI Ready for Demo (BitVM#224)

chainwayxyz · Feb 25, 2025 · cd4c4ed · cd4c4ed
1 parent 0fd74a2
commit cd4c4ed
Show file tree

Hide file tree

Showing 62 changed files with 1,806 additions and 708 deletions.
diff --git a/Cargo.lock b/Cargo.lock
diff --git a/DEMO_INSTRUCTIONS.md b/DEMO_INSTRUCTIONS.md
@@ -0,0 +1,261 @@
+Before running the demo for the first time, see [Environment Setup](#environment-setup) section below.
+
+# Demo Prep: Funding UTXOs
+The bridge peg-in and peg-out execution consumes three funding UTXOs. For convenience, prepare them before running the demo. This process remains the same across all scenarios. You can use the recommended amounts as below:
+
+1. Peg-in graph - 'peg-in depost' tx input: **2097447 SAT** - will be spent by [DEPOSITOR] (use `-d` to get their address)
+2. Peg-out graph - 'peg-out confirm' tx input: **3562670 SAT** - will be spent by [OPERATOR] (use `-o` to get their address)
+3. Withdrawer peg-out - 'peg-out' tx input: **2097274 SAT** - will be spent by [OPERATOR] (use `-o` to get their address)
+
+# Demo Steps
+The following is the list of command line arguments that are passed to the CLI tool in sequence by the respective actors. The arguments can be used either with `cargo run --bin bridge --` or when running the CLI binary directly.
+
+## Rejected Disprove Scenario (a.k.a. 'happy peg-out' execution path).
+#### [DEPOSITOR] Initiate peg-in
+`<TXID>:<VOUT>` = Bridge deposit UTXO that includes the expected peg-in amount. It must be spendable by the depositor private key. Suggested test amount: `2097447 sats`. It is the UTXO #1 in [Demo Prep](#demo-prep-funding-utxos).
+```
+-n -u <TXID>:<VOUT> -d <EVM_ADDRESS>
+```
+#### [OPERATOR] Create peg-out graph
+`<TXID>:<VOUT>` = UTXO funding the peg-out confirm tx. Must be spendable by the operator private key. Suggested test amount: `3562670 sats`. It is the UTXO #2 in [Demo Prep](#demo-prep-funding-utxos).
+```
+-t -u <TXID>:<VOUT> -i <PEG_IN_GRAPH_ID>
+```
+#### [VERIFIER_0] Push verifier_0 nonces for peg-in graph
+```
+-c -i <GRAPH_ID>
+```
+#### [VERIFIER_1] Push verifier_1 nonces for peg-in graph
+```
+-c -i <GRAPH_ID>
+```
+#### [VERIFIER_0] Push verifier_0 signatures for peg-in graph
+```
+-g -i <GRAPH_ID>
+```
+#### [VERIFIER_1] Push verifier_1 signatures for peg-in graph
+```
+-g -i <GRAPH_ID>
+```
+#### [OPERATOR] or [VERIFIER_0] or [VERIFIER_1] Broadcast peg-in confirm
+```
+-b pegin -g <PEG_IN_GRAPH_ID> confirm
+```
+Record the peg-in confirm txid.
+#### [VERIFIER_0] Push verifier_0 nonces for peg-out graph
+```
+-c -i <GRAPH_ID>
+```
+#### [VERIFIER_1] Push verifier_1 nonces for peg-out graph
+```
+-c -i <GRAPH_ID>
+```
+#### [VERIFIER_0] Push verifier_0 signatures for peg-out graph
+```
+-g -i <GRAPH_ID>
+```
+#### [VERIFIER_1] Push verifier_1 signatures for peg-out graph
+```
+-g -i <GRAPH_ID>
+```
+#### [OPERATOR] Mock L2 peg-out event (requires peg-in confirm txid mined earlier)
+> [!IMPORTANT]
+> Start the CLI in interactive mode here.
+
+`<TXID>:<VOUT>` = The peg-in confirm txid recorded above and output index 0.
+```
+-x -u <TXID>:<VOUT>
+```
+#### [OPERATOR] Broadcast peg-out
+`<TXID>:<VOUT>` = UTXO funding the payout to the withdrawer. Must be spendable by the operator private key. Suggested test amount: `2097274 sats`. It is the UTXO #3 in [Demo Prep](#demo-prep-funding-utxos).
+```
+-b tx -g <GRAPH_ID> -u <TXID>:<VOUT> peg_out
+```
+#### [OPERATOR] Broadcast peg-out confirm
+```
+-b tx -g <GRAPH_ID> peg_out_confirm
+```
+#### [OPERATOR] Broadcast kick-off 1
+```
+-b tx -g <GRAPH_ID> kick_off_1
+```
+#### [OPERATOR] Broadcast kick-off 2
+```
+-b tx -g <GRAPH_ID> kick_off_2
+```
+#### [OPERATOR] Broadcast assert-initial
+```
+-b tx -g <GRAPH_ID> assert_initial
+```
+#### [OPERATOR] Broadcast assert-commit 1
+```
+-b tx -g <GRAPH_ID> assert_commit_1
+```
+#### [OPERATOR] Broadcast assert-commit 2
+```
+-b tx -g <GRAPH_ID> assert_commit_2
+```
+#### [OPERATOR] Broadcast assert-final
+```
+-b tx -g <GRAPH_ID> assert_final
+```
+#### [VERIFIER_1] Broadcast disprove (should fail)
+`<BTC_ADDRESS>` = Receiver of the disprove reward.
+```
+-b tx -g <GRAPH_ID> -a <BTC_ADDRESS> disprove
+```
+#### [OPERATOR] Broadcast take 2
+```
+-b tx -g <GRAPH_ID> take_2
+```
+
+## Successful Disprove Scenario (a.k.a. 'unhappy peg-out' execution path).
+#### [DEPOSITOR] Initiate peg-in
+`<TXID>:<VOUT>` = Bridge deposit UTXO that includes the expected peg-in amount. It must be spendable by the depositor private key. Suggested test amount: `2097447 sats`.
+```
+-n -u <TXID>:<VOUT> -d <EVM_ADDRESS>
+```
+#### [OPERATOR] Create peg-out graph
+`<TXID>:<VOUT>` = UTXO funding the peg-out confirm tx. Must be spendable by the operator private key. Suggested test amount: `3562670 sats`.
+```
+-t -u <TXID>:<VOUT> -i <PEG_IN_GRAPH_ID>
+```
+#### [VERIFIER_0] Push verifier_0 nonces for peg-in graph
+```
+-c -i <GRAPH_ID>
+```
+#### [VERIFIER_1] Push verifier_1 nonces for peg-in graph
+```
+-c -i <GRAPH_ID>
+```
+#### [VERIFIER_0] Push verifier_0 signatures for peg-in graph
+```
+-g -i <GRAPH_ID>
+```
+#### [VERIFIER_0] Push verifier_1 signatures for peg-in graph
+```
+-g -i <GRAPH_ID>
+```
+#### [OPERATOR] or [VERIFIER_0] or [VERIFIER_1] Broadcast peg-in confirm
+```
+-b pegin -g <PEG_IN_GRAPH_ID> confirm
+```
+Record the peg-in confirm txid.
+#### [VERIFIER_0] Push verifier_0 nonces for peg-out graph
+```
+-c -i <GRAPH_ID>
+```
+#### [VERIFIER_1] Push verifier_1 nonces for peg-out graph
+```
+-c -i <GRAPH_ID>
+```
+#### [VERIFIER_0] Push verifier_0 signatures for peg-out graph
+```
+-g -i <GRAPH_ID>
+```
+#### [VERIFIER_1] Push verifier_1 signatures for peg-out graph
+```
+-g -i <GRAPH_ID>
+```
+#### [OPERATOR] Mock L2 peg-out event (requires peg-in confirm txid mined earlier)
+> [!IMPORTANT]
+> Start the CLI in interactive mode here.
+
+`<TXID>:<VOUT>` = The peg-in confirm txid recorded above and output index 0.
+```
+-x -u <TXID>:<VOUT>
+```
+#### [OPERATOR] Broadcast peg-out
+`<TXID>:<VOUT>` = UTXO funding the payout to the withdrawer. Must be spendable by the operator private key. Suggested test amount: `2097274 sats`.
+```
+-b tx -g <GRAPH_ID> -u <TXID>:<VOUT> peg_out
+```
+#### [OPERATOR] Broadcast peg-out confirm
+```
+-b tx -g <GRAPH_ID> peg_out_confirm
+```
+#### [OPERATOR] Broadcast kick-off 1
+```
+-b tx -g <GRAPH_ID> kick_off_1
+```
+#### [OPERATOR] Broadcast kick-off 2
+```
+-b tx -g <GRAPH_ID> kick_off_2
+```
+#### [OPERATOR] Broadcast assert-initial
+```
+-b tx -g <GRAPH_ID> assert_initial
+```
+#### [OPERATOR] Broadcast assert-commit 1 with invalid proof
+```
+-b tx -g <GRAPH_ID> assert_commit_1_invalid
+```
+#### [OPERATOR] Broadcast assert-commit 2 with invalid proof
+```
+-b tx -g <GRAPH_ID> assert_commit_2_invalid
+```
+#### [OPERATOR] Broadcast assert-final
+```
+-b tx -g <GRAPH_ID> assert_final
+```
+#### [VERIFIER_1] Broadcast disprove
+`<BTC_ADDRESS>` = Receiver of the disprove reward.
+```
+-b tx -g <GRAPH_ID> -a <BTC_ADDRESS> disprove
+```
+
+# Environment Setup
+Clone and build this repository. The CLI executable is called `bridge`.
+
+## [DEPOSITOR] and [OPERATOR] and [VERIFIER_0]
+All the above users can execute commands using a single setup (from the same directory).
+
+#### `bridge.toml`
+Sample `bridge.toml` file that contains private keys of protocol participants and the ZK proof verifying key:
+```toml
+[keys]
+depositor = "b8f17ea979be24199e7c3fec71ee88914d92fd4ca508443f765d56ce024ef1d7"
+operator = "3076ca1dfc1e383be26d5dd3c0c427340f96139fa8c2520862cf551ec2d670ac"
+verifier = "ee0817eac0c13aa8ee2dd3256304041f09f0499d1089b56495310ae8093583e2"
+verifying_key = "9c3815c2ec66950b63e60c86dc9a2a658e0224d55ea45efe1f633be052dc7d867aff76a9e983210318f1b808aacbbba1dc04b6ac4e6845fa0cc887aeacaf5a068ab9aeaf8142740612ff2f3377ce7bfa7433936aaa23e3f3749691afaa06301fd03f043c097556e7efdf6862007edf3eb868c736d917896c014c54754f65182ae0c198157f92e667b6572ba60e6a52d58cb70dbeb3791206e928ea5e65c6199d25780cedb51796a8a43e40e192d1b23d0cfaf2ddd03e4ade7c327dbc427999244bf4b47b560cf65d672c86ef448eb5061870d3f617bd3658ad6917d0d32d9296020000000000000008f167c3f26c93dbfb91f3077b66bc0092473a15ef21c30f43d3aa96776f352a33622830e9cfcb48bdf8d3145aa0cf364bd19bbabfb3c73e44f56794ee65dc8a"
+```
+Place the file in `.bitvm-bridge` directory in the user home directory.
+
+#### `.env`
+Sample `.env` file that must be present in the same directory as the CLI tool or any of its parent directories (if you clone this repository, you can put it in the root directory).
+```
+export BRIDGE_DATA_STORE_CLIENT_DATA_SUFFIX=-"bridge-client-data-demo-feb-2025.json"
+
+export BRIDGE_AWS_ACCESS_KEY_ID=""
+export BRIDGE_AWS_SECRET_ACCESS_KEY=""
+export BRIDGE_AWS_REGION=""
+export BRIDGE_AWS_BUCKET=""
+
+# All verifier public keys
+export VERIFIERS="026cc14f56ad7e8fdb323378287895c6c0bcdbb37714c74fba175a0c5f0cd0d56f,02452556ed6dbac394cbb7441fbaf06c446d1321467fa5a138895c6c9e246793dd"
+```
+
+## [VERIFIER_1]
+Install the CLI tool in a different directory and make sure it doesn't share the `.env` file with the setup above. You can either clone this repository at another location or just copy the binary along with the .env.
+
+#### `bridge.toml`
+Create a 'bitvm-bridge-verifier-1' directory there and put the following `bridge.toml` file there:
+```toml
+[keys]
+verifier = "fc294c70faf210d4d0807ea7a3dba8f7e41700d90c119e1ae82a0687d89d297f"
+verifying_key = "9c3815c2ec66950b63e60c86dc9a2a658e0224d55ea45efe1f633be052dc7d867aff76a9e983210318f1b808aacbbba1dc04b6ac4e6845fa0cc887aeacaf5a068ab9aeaf8142740612ff2f3377ce7bfa7433936aaa23e3f3749691afaa06301fd03f043c097556e7efdf6862007edf3eb868c736d917896c014c54754f65182ae0c198157f92e667b6572ba60e6a52d58cb70dbeb3791206e928ea5e65c6199d25780cedb51796a8a43e40e192d1b23d0cfaf2ddd03e4ade7c327dbc427999244bf4b47b560cf65d672c86ef448eb5061870d3f617bd3658ad6917d0d32d9296020000000000000008f167c3f26c93dbfb91f3077b66bc0092473a15ef21c30f43d3aa96776f352a33622830e9cfcb48bdf8d3145aa0cf364bd19bbabfb3c73e44f56794ee65dc8a"
+```
+#### `.env`
+```
+export BRIDGE_DATA_STORE_CLIENT_DATA_SUFFIX=-"bridge-client-data-demo-feb-2025.json"
+
+export BRIDGE_AWS_ACCESS_KEY_ID=""
+export BRIDGE_AWS_SECRET_ACCESS_KEY=""
+export BRIDGE_AWS_REGION=""
+export BRIDGE_AWS_BUCKET=""
+
+export KEY_DIR="bitvm-bridge-verifier-1"
+
+# All verifier public keys
+export VERIFIERS="026cc14f56ad7e8fdb323378287895c6c0bcdbb37714c74fba175a0c5f0cd0d56f,02452556ed6dbac394cbb7441fbaf06c446d1321467fa5a138895c6c9e246793dd"
+```
diff --git a/README.md b/README.md
@@ -118,9 +118,10 @@ The BitVM CLI application can be invoked with various commands. The general synt
 
 ### Global Options
 
-- -r, --verifiers <VERIFIER_PUBKEYS>: Optional; Comma-separated list of public keys for verifiers (max: 1000). Can also be set via the VERIFIERS environment variable.
-- -e, --environment <ENVIRONMENT>: Specify the Bitcoin network environment (mainnet, testnet). Defaults to testnet. Can also be set via the ENVIRONMENT environment variable.
-- --key-dir <DIRECTORY>: Directory containing the private keys. Can also be set via the KEY_DIR environment variable.
+- -r, --verifiers <VERIFIER_PUBKEYS>: Comma-separated list of public keys for verifiers (max: 1000). Can also be set via the VERIFIERS environment variable.
+- -e, --environment <ENVIRONMENT>: Optional; Specify the Bitcoin network environment (mainnet, testnet, regtest). Defaults to testnet. Can also be set via the ENVIRONMENT environment variable.
+- --key-dir <DIRECTORY>: Optional; Directory containing the private keys. Can also be set via the KEY_DIR environment variable.
+- -p, --user-profile <USER_PROFILE>: Optional; An arbitrary name of the user running the client (e.g. 'operator_one', 'verifier_0'). Used as a namespace separator in the local file path for storing private and public client data. Can also be set by the USER_PROFILE environment variable.
 
 ### Available Commands
 
@@ -137,6 +138,21 @@ The BitVM CLI application can be invoked with various commands. The general synt
 - -o, --operator <SECRET_KEY>: Secret key for the operator.
 - -v, --verifier <SECRET_KEY>: Secret key for the verifier.
 - -w, --withdrawer <SECRET_KEY>: Secret key for the withdrawer.
+- -k, --vk <KEY>: Zero-knowledge proof verifying key.
+
+#### Get Operator Address:
+1. Description: Retrieve the address spendable by the registered operator key.
+2. Usage:
+```bash
+./target/release/bridge get-operator-address
+```
+
+#### Get Operator UTXOs:
+1. Description: Retrieve a list of the operator's UTXOs.
+2. Usage:
+```bash
+./target/release/bridge get-operator-utxos
+```
 
 #### Get Depositor Address:
 1. Description: Retrieve the address spendable by the registered depositor key.
@@ -159,6 +175,34 @@ The BitVM CLI application can be invoked with various commands. The general synt
 ./target/release/bridge initiate-peg-in --utxo <TXID>:<VOUT> --destination_address <EVM_ADDRESS>
 ```
 
+#### Create Peg-Out graph:
+1. Description: Create the peg-out graph for the corresponding peg-in graph.
+2. Usage:
+```bash
+./target/release/bridge create-peg-out --utxo <TXID>:<VOUT> --peg_in_id <PEG_IN_GRAPH_ID>
+```
+
+#### Push nonces (MuSig2 signing process):
+1. Description: Push nonces for the corresponding peg-out or peg-in graph.
+2. Usage:
+```bash
+./target/release/bridge push-nonces --id <GRAPH_ID>
+```
+
+#### Push signatures (MuSig2 signing process):
+1. Description: Push signatures for the corresponding peg-out or peg-in graph.
+2. Usage:
+```bash
+./target/release/bridge push-signatures --id <GRAPH_ID>
+```
+
+#### Mock L2 peg-out event:
+1. Description: FOR TEST PURPOSES ONLY! Mocks L2 chain service with specified peg-in-confirm txid.
+2. Usage:
+```bash
+./target/release/bridge mock-l2-pegout-event --utxo <TXID>:<VOUT>
+```
+
 #### Broadcast Transactions:
 1. Description: Send various types of transactions related to peg-ins and peg-outs.
 2. Usage:
@@ -199,9 +243,10 @@ You can set the following environment variables to configure the CLI:
 - BRIDGE_AWS_REGION : The AWS region where your storage bucket is located. Required if using AWS for storage.
 - BRIDGE_AWS_BUCKET : The name of the S3 bucket where files will be stored. Required if using AWS for storage.
 
-- KEY_DIR: Directory containing private keys.
+- KEY_DIR: Optional; Directory containing private keys.
 - VERIFIERS: Comma-separated list of public keys for verifiers.
-- ENVIRONMENT: Bitcoin network environment (default: mainnet).
+- ENVIRONMENT: Optional; Bitcoin network environment (default: testnet).
+- USER_PROFILE: Optional; An arbitrary name of the user running the client (e.g. 'operator_one', 'verifier_0'). Used as a namespace separator in the local file path for storing private and public client data.
 
 #### FTP/SFTP Environment Variables
 

diff --git a/bridge/Cargo.toml b/bridge/Cargo.toml
@@ -45,6 +45,7 @@ ark-relations.workspace = true
 secp256k1.workspace = true
 zstd = "0.13.2"
 bitcode = "0.6.3"
+human_bytes = { version = "0.4", features = ["fast"] }
 
 [profile.dev]
 opt-level = 3