Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 11 additions & 9 deletions .claude/commands/challenge.md
Original file line number Diff line number Diff line change
@@ -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

Expand All @@ -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 <rpc_url>/v1/graphs/<graph_id> | 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:
Expand All @@ -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
```
20 changes: 10 additions & 10 deletions .claude/commands/run-challenger-node.md
Original file line number Diff line number Diff line change
@@ -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

Expand All @@ -12,33 +12,33 @@ 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/<network>/bitvm-noded/challenge_0/.env.challenge_0 .env
cp deployment/<network>/bitvm-noded/verifier_0/.env.verifier_0 .env
```

3. Check if the `bitvm-noded` binary exists at `./bin/bitvm-noded`. If not, run:
```bash
.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 <rpc_addr> --metrics-addr <metrics_addr> --db-path <db_path> --p2p-port <p2p_port> --bootnodes "$BOOTNODES"
```

To run in the background:
```bash
nohup ./bin/bitvm-noded --rpc-addr <rpc_addr> --metrics-addr <metrics_addr> --db-path <db_path> --p2p-port <p2p_port> --bootnodes "$BOOTNODES" >challenger_$(date +'%Y%m%d').log 2>&1 &
nohup ./bin/bitvm-noded --rpc-addr <rpc_addr> --metrics-addr <metrics_addr> --db-path <db_path> --p2p-port <p2p_port> --bootnodes "$BOOTNODES" >verifier_$(date +'%Y%m%d').log 2>&1 &
```

5. Verify the node is running:
Expand All @@ -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`.
4 changes: 2 additions & 2 deletions .github/workflows/docker-proof-builder-rpc-regtest.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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 }}
15 changes: 9 additions & 6 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand All @@ -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"
Expand Down
2 changes: 2 additions & 0 deletions deployment/regtest/bitvm-noded/committee_0/run.sh
Original file line number Diff line number Diff line change
@@ -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 &
4 changes: 3 additions & 1 deletion deployment/regtest/bitvm-noded/committee_1/run.sh
Original file line number Diff line number Diff line change
@@ -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 &
4 changes: 3 additions & 1 deletion deployment/regtest/bitvm-noded/operator_0/run.sh
Original file line number Diff line number Diff line change
@@ -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 &
2 changes: 1 addition & 1 deletion deployment/regtest/bitvm-noded/start_nodes.sh
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
4 changes: 3 additions & 1 deletion deployment/regtest/bitvm-noded/verifier_0/run.sh
Original file line number Diff line number Diff line change
@@ -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 &
4 changes: 3 additions & 1 deletion deployment/regtest/bitvm-noded/watchtower_0/run.sh
Original file line number Diff line number Diff line change
@@ -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 &
4 changes: 3 additions & 1 deletion deployment/testnet4/bitvm-noded/committee_0/run.sh
Original file line number Diff line number Diff line change
@@ -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 &
4 changes: 3 additions & 1 deletion deployment/testnet4/bitvm-noded/committee_1/run.sh
Original file line number Diff line number Diff line change
@@ -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 &
4 changes: 3 additions & 1 deletion deployment/testnet4/bitvm-noded/operator_0/run.sh
Original file line number Diff line number Diff line change
@@ -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 &
2 changes: 1 addition & 1 deletion deployment/testnet4/bitvm-noded/start_nodes.sh
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
4 changes: 3 additions & 1 deletion deployment/testnet4/bitvm-noded/verifier_0/run.sh
Original file line number Diff line number Diff line change
@@ -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 &
4 changes: 3 additions & 1 deletion deployment/testnet4/bitvm-noded/watchtower_0/run.sh
Original file line number Diff line number Diff line change
@@ -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 &
34 changes: 31 additions & 3 deletions node/src/main.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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<String>,

/// Dedicated Prometheus metrics listener address, e.g. `10.0.0.7:9108`.
Expand Down Expand Up @@ -110,6 +110,13 @@ enum KeyCommands {
FundingAddress,
}

impl Opts {
/// The configured bootnodes; an empty `BOOTNODES=` means none.
fn bootnodes(&self) -> Vec<String> {
self.bootnodes.iter().filter(|addr| !addr.trim().is_empty()).cloned().collect()
}
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn Error>> {
dotenv::dotenv().ok();
Expand Down Expand Up @@ -188,7 +195,7 @@ async fn main() -> Result<(), Box<dyn Error>> {
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(),
Expand Down Expand Up @@ -816,3 +823,24 @@ pub async fn start_handle_swarm_msg_task(
) -> anyhow::Result<String> {
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") };
}
}
Loading