diff --git a/.claude/commands/challenge.md b/.claude/commands/challenge.md index c3bf74b79..836695162 100644 --- a/.claude/commands/challenge.md +++ b/.claude/commands/challenge.md @@ -1,12 +1,12 @@ Broadcast a Challenge transaction for a graph via the `challenge` binary. -The challenge binary calls the node's REST API, so a **Challenger node** must be running and reachable. +The challenge binary calls the node's REST API, so a **Verifier node** built with the `rpc-debug-endpoints` feature must be running and reachable. Release binaries are built without that feature: they serve no challenge endpoint and ship no `challenge` binary. -## Prerequisites — Running a Challenger Node +## Prerequisites — Running a Verifier Node -Before using this command, ensure a Challenger role node (`ACTOR=Challenger`) is running. +Before using this command, ensure a Verifier role node (`ACTOR=Verifier`) built with `rpc-debug-endpoints` is running. -Use the `/run-challenger-node` skill to start one, or see `deployment/README.md` (section **Challenger**) for full details. +Use the `/run-challenger-node` skill to start one, or see `deployment/README.md` for full details. ## Instructions @@ -20,18 +20,20 @@ Use the `/run-challenger-node` skill to start one, or see `deployment/README.md` ``` If it is not set, ask the user to export it before continuing. -3. Confirm that the Challenger node is running and reachable at the given `rpc_url`. If the user hasn't started a node yet, walk them through the `/run-challenger-node` skill. +3. Confirm that the Verifier node is running and reachable at the given `rpc_url`. If the user hasn't started a node yet, walk them through the `/run-challenger-node` skill. -4. **Verify the graph is synced** on the local challenger node. The challenger syncs graph data via P2P from other nodes, so the target graph must exist locally before a challenge can be sent. Check by calling: +4. **Verify the graph is synced** on the local Verifier node. The node syncs graph data via P2P from other nodes, so the target graph must exist locally before a challenge can be sent. Check by calling: ```bash curl -s /v1/graphs/ | jq . ``` - If the response contains a non-null `"graph"` field, the graph is synced and ready. - If `"graph"` is null or the request fails, the node has not yet synced this graph. Ask the user to wait for P2P sync to complete and retry. The node must be connected to the network (correct `BOOTNODES`, `PROTO_NAME`) and the graph must exist on peer nodes. -5. Check if the `challenge` binary exists at `./bin/challenge`. If not, run: +5. Check if the `challenge` binary exists at `./bin/challenge`. If not, build it, and the node it talks to, from source with the debug endpoints: ```bash - .claude/commands/install-bitvm.sh install + source ~/.zkm-toolchain/env + cargo build -r -p bitvm-noded --features rpc-debug-endpoints --bin challenge --bin bitvm-noded + mkdir -p bin && cp target/release/challenge target/release/bitvm-noded bin/ ``` 6. Run the command using the pre-built binary: @@ -46,6 +48,6 @@ Use the `/run-challenger-node` skill to start one, or see `deployment/README.md` # Default API URL (http://localhost:8080) ./bin/challenge --graph-id 6ba7b810-9dad-11d1-80b4-00c04fd430c8 -# Custom API URL (e.g. challenger node on port 8906) +# Custom API URL (e.g. Verifier node on port 8906) ./bin/challenge --graph-id 6ba7b810-9dad-11d1-80b4-00c04fd430c8 --rpc-url http://127.0.0.1:8906 ``` diff --git a/.claude/commands/run-challenger-node.md b/.claude/commands/run-challenger-node.md index c3b3a93a1..81e194004 100644 --- a/.claude/commands/run-challenger-node.md +++ b/.claude/commands/run-challenger-node.md @@ -1,6 +1,6 @@ -Run a BitVM Challenger node locally. +Run a BitVM Verifier node locally (the `Verifier` role, which challenges operators when needed). -The Challenger verifies operator operations and submits challenges if necessary. +The Verifier checks operator operations and submits challenges if necessary. ## Instructions @@ -12,17 +12,17 @@ The Challenger verifies operator operations and submits challenges if necessary. - **db_path**: SQLite database path. Default: `sqlite:$PWD/bitvm-node.db` 2. Ensure the `.env` file exists in the working directory. Template configs are at: - - **testnet4**: `deployment/testnet4/bitvm-noded/challenge_0/.env.challenge_0` - - **regtest**: `deployment/regtest/bitvm-noded/challenge_0/.env.challenge_0` + - **testnet4**: `deployment/testnet4/bitvm-noded/verifier_0/.env.verifier_0` + - **regtest**: `deployment/regtest/bitvm-noded/verifier_0/.env.verifier_0` The user **must** fill in these required secrets: - `BITVM_SECRET` - Node BTC key (hex or `seed:...`) - - `GOAT_ADDRESS` - Challenger's EVM address + - `GOAT_ADDRESS` - Verifier's EVM address - `PEER_KEY` - libp2p private key for node identity Copy the template if needed: ```bash - cp deployment//bitvm-noded/challenge_0/.env.challenge_0 .env + cp deployment//bitvm-noded/verifier_0/.env.verifier_0 .env ``` 3. Check if the `bitvm-noded` binary exists at `./bin/bitvm-noded`. If not, run: @@ -30,7 +30,7 @@ The Challenger verifies operator operations and submits challenges if necessary. .claude/commands/install-bitvm.sh install ``` -4. Start the challenger node: +4. Start the Verifier node (`ACTOR=Verifier` in `.env`): ```bash ./bin/bitvm-noded --rpc-addr --metrics-addr --db-path --p2p-port --bootnodes "$BOOTNODES" @@ -38,7 +38,7 @@ The Challenger verifies operator operations and submits challenges if necessary. To run in the background: ```bash -nohup ./bin/bitvm-noded --rpc-addr --metrics-addr --db-path --p2p-port --bootnodes "$BOOTNODES" >challenger_$(date +'%Y%m%d').log 2>&1 & +nohup ./bin/bitvm-noded --rpc-addr --metrics-addr --db-path --p2p-port --bootnodes "$BOOTNODES" >verifier_$(date +'%Y%m%d').log 2>&1 & ``` 5. Verify the node is running: @@ -52,9 +52,9 @@ Prometheus metrics in OpenMetrics text format. ### Example (testnet4) ```bash -cp deployment/testnet4/bitvm-noded/challenge_0/.env.challenge_0 .env +cp deployment/testnet4/bitvm-noded/verifier_0/.env.verifier_0 .env # Edit .env to fill in BITVM_SECRET, GOAT_ADDRESS, PEER_KEY ./bin/bitvm-noded --rpc-addr 127.0.0.1:8906 --metrics-addr 127.0.0.1:9902 --db-path sqlite:$PWD/bitvm-node.db --p2p-port 8449 --bootnodes /ip4/34.215.238.232/tcp/8445/p2p/12D3KooWCrPTAmhFdC5DBGgkxZvJi6iuSeiDWKRL87isrt4iMHXv ``` -For full deployment documentation, see `deployment/README.md` (section **Challenger**). +For full deployment documentation, see `deployment/README.md`. diff --git a/.github/workflows/docker-proof-builder-rpc-regtest.yml b/.github/workflows/docker-proof-builder-rpc-regtest.yml index a208bfcbd..5147e3ca0 100644 --- a/.github/workflows/docker-proof-builder-rpc-regtest.yml +++ b/.github/workflows/docker-proof-builder-rpc-regtest.yml @@ -80,5 +80,5 @@ jobs: file: ./proof-builder-rpc/Dockerfile push: true tags: | - ghcr.io/${{ env.REPO_LOWER }}-proof-builder-rpc:latest - ghcr.io/${{ env.REPO_LOWER }}-proof-builder-rpc:${{ env.VERSION_TAG }} + ghcr.io/${{ env.REPO_LOWER }}-proof-builder-rpc:regtest + ghcr.io/${{ env.REPO_LOWER }}-proof-builder-rpc:regtest-${{ env.VERSION_TAG }} diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 61e6275e5..6cd606829 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -74,7 +74,6 @@ jobs: BINS=( "target/release/bitvm-noded" "target/release/sequencer-set-publish" - "target/release/challenge" "target/release/send-rbf" "target/release/pegin-request" "target/release/pegout" @@ -94,13 +93,17 @@ jobs: STAGING_DIR="release-staging" mkdir -p "$STAGING_DIR" + # `challenge` needs the rpc-debug-endpoints feature, which release + # builds leave out, so it is not listed. A listed binary must exist. for bin in "${BINS[@]}"; do - if [ -f "$bin" ]; then - BASENAME=$(basename "$bin") - cp "$bin" "$STAGING_DIR/" - chmod +x "$STAGING_DIR/$BASENAME" - echo "✓ $BASENAME" + if [ ! -f "$bin" ]; then + echo "missing release binary: $bin" >&2 + exit 1 fi + BASENAME=$(basename "$bin") + cp "$bin" "$STAGING_DIR/" + chmod +x "$STAGING_DIR/$BASENAME" + echo "✓ $BASENAME" done ARCHIVE_NAME="bitvm-node-${VERSION}-${PLATFORM}.tar.gz" diff --git a/deployment/regtest/bitvm-noded/committee_0/run.sh b/deployment/regtest/bitvm-noded/committee_0/run.sh index a074600cb..2e7efe228 100644 --- a/deployment/regtest/bitvm-noded/committee_0/run.sh +++ b/deployment/regtest/bitvm-noded/committee_0/run.sh @@ -1 +1,3 @@ +# Load this node's settings, including BOOTNODES. +set -a; . ./.env.committee_0; set +a nohup ../bitvm-noded --rpc-addr 0.0.0.0:8900 --metrics-addr 127.0.0.1:9900 --db-path sqlite:$PWD/bitvm-node.db --p2p-port 8444 >$PWD/$(date +'%Y%m%d').log 2>&1 & diff --git a/deployment/regtest/bitvm-noded/committee_1/run.sh b/deployment/regtest/bitvm-noded/committee_1/run.sh index 5dd31c89f..12abbc491 100644 --- a/deployment/regtest/bitvm-noded/committee_1/run.sh +++ b/deployment/regtest/bitvm-noded/committee_1/run.sh @@ -1 +1,3 @@ -nohup ../bitvm-noded --rpc-addr 127.0.0.1:8901 --metrics-addr 127.0.0.1:9901 --db-path sqlite:$PWD/bitvm-node.db --p2p-port 8445 --bootnodes $bootnode_urls >$PWD/$(date +'%Y%m%d').log 2>&1 & +# Load this node's settings, including BOOTNODES. +set -a; . ./.env.committee_1; set +a +nohup ../bitvm-noded --rpc-addr 127.0.0.1:8901 --metrics-addr 127.0.0.1:9901 --db-path sqlite:$PWD/bitvm-node.db --p2p-port 8445 >$PWD/$(date +'%Y%m%d').log 2>&1 & diff --git a/deployment/regtest/bitvm-noded/operator_0/run.sh b/deployment/regtest/bitvm-noded/operator_0/run.sh index e0c2a412a..421770ad2 100644 --- a/deployment/regtest/bitvm-noded/operator_0/run.sh +++ b/deployment/regtest/bitvm-noded/operator_0/run.sh @@ -1 +1,3 @@ -nohup ../bitvm-noded --rpc-addr 127.0.0.1:8902 --metrics-addr 127.0.0.1:9903 --db-path sqlite:$PWD/bitvm-node.db --p2p-port 8446 --bootnodes $bootnode_urls >$PWD/$(date +'%Y%m%d').log 2>&1 & +# Load this node's settings, including BOOTNODES. +set -a; . ./.env.operator_0; set +a +nohup ../bitvm-noded --rpc-addr 127.0.0.1:8902 --metrics-addr 127.0.0.1:9903 --db-path sqlite:$PWD/bitvm-node.db --p2p-port 8446 >$PWD/$(date +'%Y%m%d').log 2>&1 & diff --git a/deployment/regtest/bitvm-noded/start_nodes.sh b/deployment/regtest/bitvm-noded/start_nodes.sh index a27f14869..1fa99c2a4 100644 --- a/deployment/regtest/bitvm-noded/start_nodes.sh +++ b/deployment/regtest/bitvm-noded/start_nodes.sh @@ -13,7 +13,7 @@ cd .. echo "start operator_0" sleep 1 cd operator_0 -sh -x .run.sh +sh -x ./run.sh cd .. sleep 1 diff --git a/deployment/regtest/bitvm-noded/verifier_0/run.sh b/deployment/regtest/bitvm-noded/verifier_0/run.sh index e0fc8a417..97846abae 100644 --- a/deployment/regtest/bitvm-noded/verifier_0/run.sh +++ b/deployment/regtest/bitvm-noded/verifier_0/run.sh @@ -1 +1,3 @@ -nohup ../bitvm-noded --rpc-addr 127.0.0.1:8906 --metrics-addr 127.0.0.1:9902 --db-path sqlite:$PWD/bitvm-node.db --p2p-port 8450 --bootnodes $bootnode_urls >$PWD/$(date +'%Y%m%d').log 2>&1 & +# Load this node's settings, including BOOTNODES. +set -a; . ./.env.verifier_0; set +a +nohup ../bitvm-noded --rpc-addr 127.0.0.1:8906 --metrics-addr 127.0.0.1:9902 --db-path sqlite:$PWD/bitvm-node.db --p2p-port 8450 >$PWD/$(date +'%Y%m%d').log 2>&1 & diff --git a/deployment/regtest/bitvm-noded/watchtower_0/run.sh b/deployment/regtest/bitvm-noded/watchtower_0/run.sh index 3cbc2b737..e12ebfb65 100644 --- a/deployment/regtest/bitvm-noded/watchtower_0/run.sh +++ b/deployment/regtest/bitvm-noded/watchtower_0/run.sh @@ -1 +1,3 @@ -nohup ../bitvm-noded --rpc-addr 127.0.0.1:8904 --metrics-addr 127.0.0.1:9904 --db-path sqlite:$PWD/bitvm-node.db --p2p-port 8448 --bootnodes $bootnode_urls >$PWD/$(date +'%Y%m%d').log 2>&1 & +# Load this node's settings, including BOOTNODES. +set -a; . ./.env.watchtower_0; set +a +nohup ../bitvm-noded --rpc-addr 127.0.0.1:8904 --metrics-addr 127.0.0.1:9904 --db-path sqlite:$PWD/bitvm-node.db --p2p-port 8448 >$PWD/$(date +'%Y%m%d').log 2>&1 & diff --git a/deployment/testnet4/bitvm-noded/committee_0/run.sh b/deployment/testnet4/bitvm-noded/committee_0/run.sh index cbac102c5..32c4d82dc 100644 --- a/deployment/testnet4/bitvm-noded/committee_0/run.sh +++ b/deployment/testnet4/bitvm-noded/committee_0/run.sh @@ -1 +1,3 @@ -nohup ../bitvm-noded --rpc-addr 127.0.0.1:8902 --metrics-addr 127.0.0.1:9900 --db-path sqlite:$PWD/bitvm-node.db --p2p-port 8445 >$PWD/$(date +'%Y%m%d').log 2>&1 & +# Load this node's settings, including BOOTNODES. +set -a; . ./.env.committee_0; set +a +nohup ../bitvm-noded --rpc-addr 127.0.0.1:8900 --metrics-addr 127.0.0.1:9900 --db-path sqlite:$PWD/bitvm-node.db --p2p-port 8445 >$PWD/$(date +'%Y%m%d').log 2>&1 & diff --git a/deployment/testnet4/bitvm-noded/committee_1/run.sh b/deployment/testnet4/bitvm-noded/committee_1/run.sh index 15356a59f..5ee26e89a 100644 --- a/deployment/testnet4/bitvm-noded/committee_1/run.sh +++ b/deployment/testnet4/bitvm-noded/committee_1/run.sh @@ -1 +1,3 @@ -nohup ../bitvm-noded --rpc-addr 127.0.0.1:8901 --metrics-addr 127.0.0.1:9901 --db-path sqlite:$PWD/bitvm-node.db --p2p-port 8444 --bootnodes $bootnode_urls >$PWD/$(date +'%Y%m%d').log 2>&1 & +# Load this node's settings, including BOOTNODES. +set -a; . ./.env.committee_1; set +a +nohup ../bitvm-noded --rpc-addr 127.0.0.1:8901 --metrics-addr 127.0.0.1:9901 --db-path sqlite:$PWD/bitvm-node.db --p2p-port 8444 >$PWD/$(date +'%Y%m%d').log 2>&1 & diff --git a/deployment/testnet4/bitvm-noded/operator_0/run.sh b/deployment/testnet4/bitvm-noded/operator_0/run.sh index 85e6f32e4..421770ad2 100644 --- a/deployment/testnet4/bitvm-noded/operator_0/run.sh +++ b/deployment/testnet4/bitvm-noded/operator_0/run.sh @@ -1 +1,3 @@ -nohup ../bitvm-noded --rpc-addr 127.0.0.1:8902 --metrics-addr 127.0.0.1:9903 --db-path sqlite:$PWD/bitvm-node.db --p2p-port 8445 --bootnodes $bootnode_urls >$PWD/$(date +'%Y%m%d').log 2>&1 & +# Load this node's settings, including BOOTNODES. +set -a; . ./.env.operator_0; set +a +nohup ../bitvm-noded --rpc-addr 127.0.0.1:8902 --metrics-addr 127.0.0.1:9903 --db-path sqlite:$PWD/bitvm-node.db --p2p-port 8446 >$PWD/$(date +'%Y%m%d').log 2>&1 & diff --git a/deployment/testnet4/bitvm-noded/start_nodes.sh b/deployment/testnet4/bitvm-noded/start_nodes.sh index a27f14869..1fa99c2a4 100644 --- a/deployment/testnet4/bitvm-noded/start_nodes.sh +++ b/deployment/testnet4/bitvm-noded/start_nodes.sh @@ -13,7 +13,7 @@ cd .. echo "start operator_0" sleep 1 cd operator_0 -sh -x .run.sh +sh -x ./run.sh cd .. sleep 1 diff --git a/deployment/testnet4/bitvm-noded/verifier_0/run.sh b/deployment/testnet4/bitvm-noded/verifier_0/run.sh index e977a1557..23a4e27a5 100644 --- a/deployment/testnet4/bitvm-noded/verifier_0/run.sh +++ b/deployment/testnet4/bitvm-noded/verifier_0/run.sh @@ -1 +1,3 @@ -nohup ../bitvm-noded --rpc-addr 127.0.0.1:8906 --metrics-addr 127.0.0.1:9902 --db-path sqlite:$PWD/bitvm-node.db --p2p-port 8449 --bootnodes $bootnode_urls >$PWD/$(date +'%Y%m%d').log 2>&1 & +# Load this node's settings, including BOOTNODES. +set -a; . ./.env.verifier_0; set +a +nohup ../bitvm-noded --rpc-addr 127.0.0.1:8906 --metrics-addr 127.0.0.1:9902 --db-path sqlite:$PWD/bitvm-node.db --p2p-port 8449 >$PWD/$(date +'%Y%m%d').log 2>&1 & diff --git a/deployment/testnet4/bitvm-noded/watchtower_0/run.sh b/deployment/testnet4/bitvm-noded/watchtower_0/run.sh index 03c9dec1b..2cc968b83 100644 --- a/deployment/testnet4/bitvm-noded/watchtower_0/run.sh +++ b/deployment/testnet4/bitvm-noded/watchtower_0/run.sh @@ -1 +1,3 @@ -nohup ../bitvm-noded --rpc-addr 127.0.0.1:8904 --metrics-addr 127.0.0.1:9904 --db-path sqlite:$PWD/bitvm-node.db --p2p-port 8447 --bootnodes $bootnode_urls >$PWD/$(date +'%Y%m%d').log 2>&1 & +# Load this node's settings, including BOOTNODES. +set -a; . ./.env.watchtower_0; set +a +nohup ../bitvm-noded --rpc-addr 127.0.0.1:8904 --metrics-addr 127.0.0.1:9904 --db-path sqlite:$PWD/bitvm-node.db --p2p-port 8447 >$PWD/$(date +'%Y%m%d').log 2>&1 & diff --git a/node/src/main.rs b/node/src/main.rs index 769cb5763..d25e40ffd 100644 --- a/node/src/main.rs +++ b/node/src/main.rs @@ -51,8 +51,8 @@ struct Opts { #[arg(long, default_value = "sqlite:/tmp/bitvm-node.db")] pub db_path: String, - /// Peer nodes as the bootnodes - #[arg(long)] + /// Peer nodes as the bootnodes. Also read from `BOOTNODES`, comma-separated. + #[arg(long, env = "BOOTNODES", value_delimiter = ',')] bootnodes: Vec, /// Dedicated Prometheus metrics listener address, e.g. `10.0.0.7:9108`. @@ -110,6 +110,13 @@ enum KeyCommands { FundingAddress, } +impl Opts { + /// The configured bootnodes; an empty `BOOTNODES=` means none. + fn bootnodes(&self) -> Vec { + self.bootnodes.iter().filter(|addr| !addr.trim().is_empty()).cloned().collect() + } +} + #[tokio::main] async fn main() -> Result<(), Box> { dotenv::dotenv().ok(); @@ -188,7 +195,7 @@ async fn main() -> Result<(), Box> { BitvmSwarmConfig { local_key: env::get_peer_key(), p2p_port: opt.p2p_port, - bootnodes: opt.bootnodes, + bootnodes: opt.bootnodes(), topic_names: vec![ Actor::Committee.to_string(), Actor::Verifier.to_string(), @@ -816,3 +823,24 @@ pub async fn start_handle_swarm_msg_task( ) -> anyhow::Result { swarm.run(actor, handler, cancellation_token).await } + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn bootnodes_come_from_the_flag_or_a_comma_separated_env() { + let parse = |args: &[&str]| Opts::try_parse_from(args).unwrap().bootnodes(); + unsafe { std::env::set_var("BOOTNODES", "/ip4/1.2.3.4/tcp/1,/ip4/5.6.7.8/tcp/2") }; + assert_eq!(parse(&["bitvm-noded"]), ["/ip4/1.2.3.4/tcp/1", "/ip4/5.6.7.8/tcp/2"]); + // The flag takes precedence over the environment. + assert_eq!( + parse(&["bitvm-noded", "--bootnodes", "/ip4/9.9.9.9/tcp/3"]), + ["/ip4/9.9.9.9/tcp/3"] + ); + // An empty value, as in `.env.template`, means no bootnodes. + unsafe { std::env::set_var("BOOTNODES", "") }; + assert!(parse(&["bitvm-noded"]).is_empty()); + unsafe { std::env::remove_var("BOOTNODES") }; + } +}