Skip to content

Warnet project implementation with one-tank network and attack scenario #2

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Aug 11, 2025
Merged

Warnet project implementation with one-tank network and attack scenario #2

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
72e141e
docs: add comprehensive README for Warnet demo project
b-l-u-e Jun 26, 2025
266e04a
Complete Warnet project implementation
b-l-u-e Jul 4, 2025
73db4c9
refactor: restructure project with standard Warnet format and improve…
b-l-u-e Jul 16, 2025
2119ceb
docs: updated the quickstart link
b-l-u-e Jul 16, 2025
510a09a
clean up extra config, get dashboard working, re-order steps in guide
pinheadmz Jul 23, 2025
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
209 changes: 208 additions & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1 +1,208 @@
# warnet-demo-project
# Warnet Demo Project

A hands-on Warnet project to help you learn Bitcoin network analysis with a simple one-node network and attack scenario.

## What is this?

This is a complete Warnet project that demonstrates how to:

- **Deploy a single-node Bitcoin network** using Warnet
- **Run a simple attack scenario** against the network
- **Monitor network behavior** and observe node responses
- **Understand basic Bitcoin network interactions**

The project includes a pre-configured network (`94.0.0-5k-inv`) and a beginner-friendly scenario (`my_first_attack_5kinv.py`) that you can run immediately.

## Prerequisites

1. Python 3.8+
2. Docker or Kubernetes (local)
3. Basic understanding of Bitcoin concepts

## Quick Start

### 1. Set up Warnet

Follow the [Warnet installation guide](https://github.com/bitcoin-dev-project/warnet?tab=readme-ov-file#quick-start) for detailed setup instructions:

```sh
# Create virtual environment
python3 -m venv .venv
source ./venv/bin/activate
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
source ./venv/bin/activate
source .venv/bin/activate


# Install Warnet
pip install warnet

# Set up dependencies
warnet setup
```

When prompted, choose your preferred backend:

- **Minikube** - Local Kubernetes cluster (recommended for beginners)
- **Docker Desktop** - If you have Docker Desktop with Kubernetes enabled
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Personally I think Docker Desktop is better for beginners because it has a GUI. I would assume Docker Desktop for mac users and minikube for linux users


### 2. Deploy the one-node network

This project includes a pre-configured one-node network. Deploy it with:

```sh
warnet deploy warnet-demo
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I expected this to be warnet deploy networks/warnet-demo or warnet deploy networks/94.0.0-5k-inv. I was surprised this command worked but I realized its because your directory structure is not standard for warnet. I think it should be something like this (I created this using warnet new and then following the inquirer prompts):

warnet-demo/
├── networks
│   └── 5k-inv-attack
│       ├── network.yaml
│       └── node-defaults.yaml
├── plugins
│   ├── __init__.py
│   ├── simln
│   │   ├── README.md
│   │   ├── charts
│   │   └── plugin.py
│   └── tor
│       ├── charts
│       └── plugin.py
└── scenarios
    ├── __init__.py
    ├── commander.py
    ├── ln_framework
    │   ├── __init__.py
    │   └── ln.py
    ├── ln_init.py
    ├── miner_std.py
    ├── reconnaissance.py
    ├── signet_miner.py
    ├── test_framework
    │   ├── __init__.py
    │   ├── ...
    └── tx_flood.py

```

This will create a simple Bitcoin network with 1 node for basic experimentation.

### 3. Run the attack scenario

Execute the included scenario to see the network in action:

```sh
warnet run warnet-demo/scenarios/my_first_attack_5kinv.py
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
warnet run warnet-demo/scenarios/my_first_attack_5kinv.py
warnet run warnet-demo/scenarios/my_first_attack_5kinv.py --debug

This might be more fun to show some running-time output of the scenario, but of course it will consume the shell foreground so for other commands like warnet dashboard we might not want to add --debug what do you think?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

i think it will make it more engaging for users and for learning purposes to see what's happening....
perhaps incase when user is multitasking they can always omit --debug..

```

This scenario will:

- Wait for all nodes to be ready
- Generate initial blocks to create funds
- Create test transactions
- Monitor transaction propagation across the network
- Show you how nodes communicate and synchronize
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So, I thought we were going to test an attack, literally https://github.com/bitcoin-dev-project/battle-of-galen-erso/blob/main/scenarios/my_first_attack_5kinv.py

What you have here is actually very cool and totally fine - but then we mine as well add 1-2 more nodes so we can actually see actual network propogation. Then go ahead and just rename the scenario something like propogation-check and instruct the user to do warnet dashboard etc

and THEN....
we can still run the attack from Galen Erso and watch a node die. (if you like?)


### 4. Monitor your tiny network and watch the attack progress

#### **Option A: Web Dashboard (Recommended)**

Open the Warnet dashboard to visualize your network in real-time:

```sh
warnet dashboard
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Did you try this command? It doesn't work for me.

I think the network you defined is missing the settings to enable the dashboard. Again, warnet new asks if you want these features, and will add to network.yaml:

caddy:
  enabled: true
fork_observer:
  configQueryInterval: 20
  enabled: true

```

This opens a web interface where you can:

- See your node's status and connections
- Monitor network activity in real-time
- View logs and metrics
- Watch the attack scenario execute step-by-step

**Note**: If using Minikube, you may need to run `minikube tunnel` in another terminal first.

#### **Option B: Command Line Monitoring**

Monitor your network from the terminal:

```sh
# Check network status
warnet status

# View real-time logs
warnet logs
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

real time logs would need an -f


# Get detailed node information
warnet logs tank-0000
```

#### **Option C: Direct Node Access**

Connect directly to your Bitcoin node:

```sh
# Get node info
warnet exec tank-0000 bitcoin-cli getnetworkinfo

# Check mempool (pending transactions)
warnet exec tank-0000 bitcoin-cli getmempoolinfo

# View recent blocks
warnet exec tank-0000 bitcoin-cli getblockcount
```
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Did you try these commands? They don't work. exec is not a warnet command. The correct syntax looks like this:

warnet bitcoin rpc tank-0000 getnetworkinfo

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oops my bad!


#### **What to Watch For:**

When running the attack scenario, you'll see:

- **Step 1**: Node startup and readiness
- **Step 2**: Block generation (creating initial funds)
- **Step 3**: Transaction creation and broadcasting
- **Step 4**: Network propagation (how transactions spread)
- **Step 5**: Final network state analysis

The dashboard will show these activities happening in real-time!

### 5. Clean up

When you're done experimenting:

```sh
warnet down
```

## What You'll Learn

By running this project, you'll understand:

1. **Network Deployment**: How Warnet creates and manages Bitcoin networks
2. **Node Communication**: How Bitcoin nodes connect and share information
3. **Transaction Propagation**: How transactions flow through the network
4. **Network Monitoring**: How to observe network behavior in real-time
5. **Scenario Execution**: How to run and create attack scenarios

## Project Structure

```
warnet-demo/
├── warnet.yaml # Project configuration
├── node-defaults.yaml # Default node settings
├── networks/
│ └── 94.0.0-5k-inv.yaml # One-node network configuration
├── scenarios/
│ └── my_first_attack_5kinv.py # Your first attack scenario
└── plugins/ # Network plugins
```

## The Network: 94.0.0-5k-inv

This is a simple one-node Bitcoin network:

```
tank-0000
```

This single node runs Bitcoin Core 26.0 in regtest mode, making it perfect for learning and experimentation without the complexity of multiple nodes.

## The Scenario: my_first_attack_5kinv.py

This scenario demonstrates basic network interaction:

1. **Network Readiness Check**: Ensures all nodes are online and connected
2. **Block Generation**: Creates initial funds by mining blocks
3. **Transaction Creation**: Sends test transactions across the network
4. **Propagation Monitoring**: Observes how transactions spread between nodes
5. **Network State Analysis**: Shows the final state of all nodes

## Next Steps

After completing this tutorial, you can:

1. **Modify the scenario**: Edit `my_first_attack_5kinv.py` to try different network interactions
2. **Add more nodes**: Modify `94.0.0-5k-inv.yaml` to create larger networks
3. **Create custom scenarios**: Use the existing scenario as a template for your own
4. **Explore advanced features**: Check out the main [Warnet documentation](https://github.com/bitcoin-dev-project/warnet)

## Troubleshooting

- **Network won't start**: Make sure your chosen backend (Minikube/Docker Desktop) is running
- **Scenario fails**: Check that the network is fully deployed first with `warnet status`
- **Dashboard not accessible**:
- For Minikube: Run `minikube tunnel` in another terminal
- For Docker Desktop: Check that Kubernetes is enabled
- **Setup fails**: Make sure you have Docker installed and running

## Resources

- **[Warnet Documentation](https://github.com/bitcoin-dev-project/warnet)** - Complete guide to Warnet features and usage
- **[Warnet Quick Start](https://github.com/bitcoin-dev-project/warnet?tab=readme-ov-file#quick-start)** - Step-by-step installation guide
- **[Warnet Scenarios](https://github.com/bitcoin-dev-project/warnet?tab=readme-ov-file#scenarios)** - Learn how to create custom attack scenarios
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Did you try these links? They don't work.

use

https://github.com/bitcoin-dev-project/warnet/blob/main/docs/scenarios.md

...etc.

- **[Warnet Networks](https://github.com/bitcoin-dev-project/warnet?tab=readme-ov-file#networks)** - Understanding network configuration
- **[Bitcoin Core Test Framework](https://github.com/bitcoin/bitcoin/tree/master/test/functional)** - Framework used by Warnet scenarios
- **[Bitcoin Development Guide](https://bitcoin.org/en/development)** - General Bitcoin development resources
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

i think we can just drop this

132 changes: 132 additions & 0 deletions warnet-demo/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,132 @@
# Warnet Demo Project
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What's this extra README for? It describes a 5-node network which we don't have.


A hands-on Warnet project to help you learn Bitcoin network analysis with a simple 5-node network and attack scenario.

## What is this?

This is a complete Warnet project that demonstrates how to:

- **Deploy a 5-node Bitcoin network** using Warnet
- **Run a simple attack scenario** against the network
- **Monitor network behavior** and observe node responses
- **Understand basic Bitcoin network interactions**

The project includes a pre-configured network (`94.0.0-5k-inv`) and a beginner-friendly scenario (`my_first_attack_5kinv.py`) that you can run immediately.

## Project Structure

```
warnet-demo/
├── warnet.yaml # Project configuration
├── node-defaults.yaml # Default node settings
├── networks/
│ └── 94.0.0-5k-inv.yaml # 5-node network configuration
├── scenarios/
│ ├── my_first_attack_5kinv.py # Your first attack scenario
│ ├── miner_std.py # Basic mining scenario
│ ├── tx_flood.py # Transaction flooding
│ ├── reconnaissance.py # Network discovery
│ └── ... # Other scenarios
└── plugins/ # Network plugins
├── tor/ # Tor network integration
└── simln/ # Lightning Network simulation
```

## The Network: 94.0.0-5k-inv

This is a simple 5-node Bitcoin network with the following topology:

```
tank-0000 ──── tank-0001 ──── tank-0003
│ │ │
└─── tank-0002 ────────┘
```

Each node runs Bitcoin Core in regtest mode, making it perfect for learning and experimentation.

## The Scenario: my_first_attack_5kinv.py

This scenario demonstrates basic network interaction:

1. **Network Readiness Check**: Ensures all nodes are online and connected
2. **Block Generation**: Creates initial funds by mining blocks
3. **Transaction Creation**: Sends test transactions across the network
4. **Propagation Monitoring**: Observes how transactions spread between nodes
5. **Network State Analysis**: Shows the final state of all nodes

## Quick Start

### 1. Set up Warnet

Follow the [Warnet installation guide](https://github.com/bitcoin-dev-project/warnet?tab=readme-ov-file#quick-start):

```sh
# Create virtual environment
python3 -m venv .venv
source ./venv/bin/activate

# Install Warnet
pip install warnet

# Set up dependencies
warnet setup
```

### 2. Deploy the 5-node network

```sh
warnet deploy warnet-demo
```

### 3. Run the attack scenario

```sh
warnet run warnet-demo/scenarios/my_first_attack_5kinv.py
```

### 4. Monitor your network

```sh
warnet dashboard
```

### 5. Clean up

```sh
warnet down
```

## What You'll Learn

By running this project, you'll understand:

1. **Network Deployment**: How Warnet creates and manages Bitcoin networks
2. **Node Communication**: How Bitcoin nodes connect and share information
3. **Transaction Propagation**: How transactions flow through the network
4. **Network Monitoring**: How to observe network behavior in real-time
5. **Scenario Execution**: How to run and create attack scenarios

## Next Steps

After completing this tutorial, you can:

1. **Modify the scenario**: Edit `my_first_attack_5kinv.py` to try different network interactions
2. **Add more nodes**: Modify `94.0.0-5k-inv.yaml` to create larger networks
3. **Try other scenarios**: Experiment with the other included scenarios
4. **Create custom scenarios**: Use the existing scenarios as templates for your own
5. **Explore advanced features**: Check out the main [Warnet documentation](https://github.com/bitcoin-dev-project/warnet)

## Troubleshooting

- **Network won't start**: Make sure your chosen backend (Minikube/Docker Desktop) is running
- **Scenario fails**: Check that the network is fully deployed first with `warnet status`
- **Dashboard not accessible**:
- For Minikube: Run `minikube tunnel` in another terminal
- For Docker Desktop: Check that Kubernetes is enabled
- **Setup fails**: Make sure you have Docker installed and running

## Resources

- [Warnet Documentation](https://github.com/bitcoin-dev-project/warnet)
- [Bitcoin Core Test Framework](https://github.com/bitcoin/bitcoin/tree/master/test/functional)
- [Bitcoin Development Guide](https://bitcoin.org/en/development)
19 changes: 19 additions & 0 deletions warnet-demo/network.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
# Simple one-node Bitcoin network for learning Warnet
# This creates a tiny network topology for beginners

nodes:
- name: tank-0000
bitcoin_config: |
server=1
rpcuser=warnet
rpcpassword=warnet
rpcallowip=0.0.0.0/0
regtest=1
listen=1
bind=0.0.0.0
blockmintxfee=0.00001
debug=net
logips=1

# Network-wide settings
chain: regtest
19 changes: 19 additions & 0 deletions warnet-demo/networks/94.0.0-5k-inv.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
# Simple one-node Bitcoin network for learning Warnet
# This creates a tiny network topology for beginners

nodes:
- name: tank-0000
bitcoin_config: |
server=1
rpcuser=warnet
rpcpassword=warnet
rpcallowip=0.0.0.0/0
regtest=1
listen=1
bind=0.0.0.0
blockmintxfee=0.00001
debug=net
logips=1

# Network-wide settings
chain: regtest
Loading