Testnet Instructions (#1219)

* create run-testnet.dm

* add testnet full node config

* add run-testnet.md

* make initial doc

* update instructions

* fix curls

* add testnet genesis

* remove todo

README.md

@@ -26,8 +26,9 @@ Citrea's vision is to build scalable infrastructure that advances Bitcoin into i
 | Question                                         | Answer                                                                                                                      |
 | ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------- |
 | How do I set up the development environment?     | [dev-setup.md](./docs/dev-setup.md)                                                                                         |
-| How do I run Citrea for testing and development? | [run.md](./docs/run.md)                                                                                                     |
+| How do I run Citrea for testing and development? | [run-dev.md](./docs/run-dev.md)                                                                                                     |
 | Where can I read more about the architecture?    | Technical docs for the repo are in progress, in the meantime refer to [our official documentation.](https://docs.citrea.xyz) |
+| How do I run a Citrea testnet node?              | [run-testnet.md](./docs/run-testnet.md) |
 
 ## Official Links
 

docker-compose.yml

@@ -1,55 +1,69 @@
-services:
-  citrea-bitcoin-signet:
-    image: chainwayxyz/citrea-bitcoin-signet:devnet
-    container_name: bitcoin-signet
-    environment:
-      - SIGNETCHALLENGE=512102653734c749d5f7227d9576b3305574fd3b0efdeaa64f3d500f121bf235f0a43151ae
-      - RPCUSER=citrea
-      - RPCPASSWORD=citrea
-      - ADDNODE=signet.citrea.xyz:38333
-    volumes:
-      - resources/dbs/citrea-bitcoin-signet-data:/mnt/task/btc-data
+services:  
+  citrea-bitcoin-testnet4:
+    image: bitcoin/bitcoin:28.0rc1
+    container_name: bitcoin-testnet4
     ports:
-      - "38332:38332"
-      - "38333:38333"
+      - "18443:18443"
+      - "18444:18444"
+    command:
+      -printtoconsole
+      -testnet4=1
+      -rest
+      -rpcbind=0.0.0.0
+      -rpcallowip=0.0.0.0/0
+      -rpcport=18443
+      -rpcuser=citrea
+      -rpcpassword=citrea
+      -server
+      -txindex=1
+    volumes:
+      - bitcoin-testnet4:/home/bitcoin/.bitcoin
     networks:
-      - citrea-devnet-network
+      - citrea-testnet-network
 
+
   citrea-full-node:
     depends_on:
-      - citrea-bitcoin-signet
-    image: chainwayxyz/citrea-full-node:devnet
+      - citrea-bitcoin-testnet4
+    image: chainwayxyz/citrea-full-node:testnet
     platform: linux/amd64
     container_name: full-node
     environment:
-      - ROLLUP__PUBLIC_KEYS__SEQUENCER_PUBLIC_KEY=52f41a5076498d1ae8bdfa57d19e91e3c2c94b6de21985d099cd48cfa7aef174
-      - ROLLUP__PUBLIC_KEYS__SEQUENCER_DA_PUB_KEY=039cd55f9b3dcf306c4d54f66cd7c4b27cc788632cd6fb73d80c99d303c6536486
-      - ROLLUP__PUBLIC_KEYS__PROVER_DA_PUB_KEY=03fc6fb2ef68368009c895d2d4351dcca4109ec2f5f327291a0553570ce769f5e5
-      - ROLLUP__DA__NETWORK=signet
-      - ROLLUP__STORAGE__PATH=/mnt/task/citrea-db
-      - ROLLUP__RPC__BIND_HOST=0.0.0.0
-      - ROLLUP__RPC__MAX_CONNECTIONS=1000
-      - ROLLUP__RPC__BIND_PORT=8080
-      - JSON_LOGS=1
-      - ROLLUP__DA__NODE_URL=http://citrea-bitcoin-signet:38332/wallet/citrea
+      - ROLLUP__PUBLIC_KEYS__SEQUENCER_PUBLIC_KEY=4682a70af1d3fae53a5a26b682e2e75f7a1de21ad5fc8d61794ca889880d39d1
+      - ROLLUP__PUBLIC_KEYS__SEQUENCER_DA_PUB_KEY=03015a7c4d2cc1c771198686e2ebef6fe7004f4136d61f6225b061d1bb9b821b9b
+      - ROLLUP__PUBLIC_KEYS__PROVER_DA_PUB_KEY=0357d255ab93638a2d880787ebaadfefdfc9bb51a26b4a37e5d588e04e54c60a42
+      - ROLLUP__DA__NODE_URL=http://citrea-bitcoin-testnet4:18443/
       - ROLLUP__DA__NODE_USERNAME=citrea
       - ROLLUP__DA__NODE_PASSWORD=citrea
-      - ROLLUP__RUNNER__SEQUENCER_CLIENT_URL=https://rpc.devnet.citrea.xyz
-      - ROLLUP__RUNNER__INCLUDE_TX_BODY=true
+      - ROLLUP__DA__NETWORK=testnet
+      - ROLLUP__DA__TX_BACKUP_DIR=
+      - ROLLUP__STORAGE__PATH=/mnt/task/citrea-db
       - ROLLUP__STORAGE__DB_MAX_OPEN_FILES=5000
+      - ROLLUP__RPC__BIND_HOST=0.0.0.0
+      - ROLLUP__RPC__BIND_PORT=8080
+      - ROLLUP__RPC__MAX_CONNECTIONS=100
+      - ROLLUP__RPC__MAX_REQUEST_BODY_SIZE=10485760
+      - ROLLUP__RPC__MAX_RESPONSE_BODY_SIZE=10485760
+      - ROLLUP__RPC__BATCH_REQUESTS_LIMIT=50
+      - ROLLUP__RPC__ENABLE_SUBSCRIPTIONS=true
+      - ROLLUP__RPC__MAX_SUBSCRIPTIONS_PER_CONNECTION=10
+      - ROLLUP__RUNNER__SEQUENCER_CLIENT_URL=https://rpc.testnet.citrea.xyz
+      - ROLLUP__RUNNER__INCLUDE_TX_BODY=false
+      - ROLLUP__RUNNER__SYNC_BLOCKS_COUNT=10
       - RUST_LOG=info
-    volumes:
-      - resources/dbs/citrea-full-node-data:/mnt/task/citrea-db
+      - JSON_LOGS=1
     ports:
       - "8080:8080"
+    volumes:
+      - citrea-full-node:/mnt/task/citrea-db
     networks:
-      - citrea-devnet-network
+      - citrea-testnet-network
 
 volumes:
-  citrea-bitcoin-signet-data:
-  citrea-full-node-data:
+  bitcoin-testnet4:
+  citrea-full-node:
 
 
 networks:
-  citrea-devnet-network:
+  citrea-testnet-network:
     driver: bridge

docs/run-testnet.md

@@ -0,0 +1,177 @@
+
+## TL; DR: I want to run it ASAP
+Download our testnet docker-compose file:
+
+```sh
+curl https://raw.githubusercontent.com/chainwayxyz/citrea/nightly/docker-compose.yml --output docker-compose.yml
+```
+
+Then use `docker-compose` to both launch a Bitcoin testnet4 node and Citrea full node:
+```sh
+docker-compose -f docker-compose.yml up
+```
+
+# Run a Citrea Testnet Full Node
+
+This guide goes over how to run a full node for Citrea testnet.
+
+It demonstrates different methods for running required software.
+
+
+## Bitcoin Testnet Setup
+
+Citrea testnet uses Bitcoin testnet4 as its DA and settlement layer.
+
+So running a Citrea fullnode requires a fully synced Bitcoin testnet4 node.
+
+Testnet4 is only enabled in version 28.0rc.1.
+
+### Option 1: Build from source
+
+#### Step 1.1: Clone Bitcoin Core Repo
+
+
+```sh
+git clone https://github.com/bitcoin/bitcoin.git
+cd bitcoin
+git checkout v28.0rc1
+```
+
+#### Step 1.2: Build Bitcoin Core
+
+Then follow the instructions on the links below for the build. However, don't clone the repository since we already did.
+
+OSX: https://github.com/bitcoin/bitcoin/blob/v28.0rc1/doc/build-osx.md
+
+Linux: https://github.com/bitcoin/bitcoin/blob/v28.0rc1/doc/build-unix.md
+
+
+#### Step 1.3: Run testnet4 node:
+
+After the setup, execute these commands to run a Bitcoin testnet4 node:
+
+```sh
+bitcoind -testnet4 -daemon -txindex=1 -rpcbind=0.0.0.0 -rpcport=18443 -rpcuser=citrea -rpcpassword=citrea 
+```
+
+You can edit RPC parameters as you wish, but you also have to edit `rollup_config.toml`
+
+### Option 2: Run Docker container
+
+If you are also going to run Citrea in Docker, follow [these steps](#tl-dr-i-want-to-run-it-asap).
+
+#### Step 2.1: Install Docker
+
+Follow instructions to install Docker here: https://docs.docker.com/engine/install/
+
+#### Step 2.2: Run testnet4 node:
+
+After Docker is installed, run this command to pull Bitcoin v0.28rc.1 image and run it as a container:
+
+```sh
+docker run -d \
+  -v ${PWD}/bitcoin-testnet4:/home/bitcoin/.bitcoin \
+  --name bitcoin-testnet4 \
+  -p 18443:18443 \
+  -p 18444:18444 \
+  bitcoin/bitcoin:28.0rc1 \
+  -printtoconsole \
+  -testnet4=1 \
+  -rest \
+  -rpcbind=0.0.0.0 \
+  -rpcallowip=0.0.0.0/0 \
+  -rpcport=18443 \
+  -rpcuser=citrea \
+  -rpcpassword=citrea \
+  -server \
+  -txindex=1
+```
+
+You can edit RPC parameters as you wish, but you have to also edit `rollup_config.toml`
+
+
+## Citrea Full Node Setup
+
+There is three different ways to run a Citra full node: using a [pre-built binary](#option-1-using-pre-built-binary), [building from source](#option-2-build-from-source) and [using docker](#option-3-using-docker).
+
+### Option 1: Using pre-built binary
+
+Before continueuing we suggest creating a `citrea/` directory and executing these commands in that directory.
+
+#### Step 1.1: Download neccessary files
+
+Go to this [webpage](https://github.com/chainwayxyz/citrea/releases) and download latest binary for your operating system under "Assets" section.
+
+Run this command to download full node config and testnet genesis files:
+```sh
+curl https://raw.githubusercontent.com/chainwayxyz/citrea/nightly/resources/configs/testnet/rollup_config.toml --output rollup_config.toml
+curl https://static.testnet.citrea.xyz/genesis.tar.gz --output genesis.tar.gz
+tar -xzvf genesis.tar.gz
+```
+
+Look through the `rollup_config.toml` and apply changes as you wish, if you modified any Bitcoin RPC configs, change corresponding values under `[da]`.
+
+#### Step 1.2: Run Citrea Full Node
+
+Finally run this command to run your Citrea full node:
+
+Mac:
+```sh
+./citrea-v0.5.0-osx-arm64 --da-layer bitcoin --rollup-config-path ./rollup_config.toml --genesis-paths ./genesis
+```
+
+Linux:
+```sh
+./citrea-v0.5.0-linux-amd64 --da-layer bitcoin --rollup-config-path ./rollup_config.toml --genesis-paths ./genesis
+```
+
+Your full node should be serving RPC at `http://0.0.0.0:8080` now.
+
+### Option 2: Build from source
+
+
+#### Step 2.1: Install Rust
+
+If you don't have it, install it from [here](https://www.rust-lang.org/tools/install).
+
+
+#### Step 2.2: Clone the source code
+
+Clone the repository and checkout the latest tag:
+```sh
+git clone https://github.com/chainwayxyz/citrea
+cd citrea
+git fetch --tags
+git checkout $(git describe --tags `git rev-list --tags --max-count=1`)
+```
+
+#### Step 2.3: Build Citrea
+If you wish to verify ZK-Proofs, then you'll need to compile our ZK VM binaries inside docker. To do so, follow instructions to install Docker: https://docs.docker.com/engine/install/
+
+Install development dependencies:
+
+```sh
+make install-dev-tools
+```
+
+Compile Citrea by running command:
+
+```sh
+cargo build --release
+```
+
+If you wish to verify ZK-Proofs, add `REPR_GUEST_BUILD=1` before `cargo b...`
+
+#### Step 2.4: Run Citrea
+
+Look through the `rollup_config.toml` and apply changes as you wish, if you modified any Bitcoin RPC configs, change corresponding values under `[da]`.
+
+And then run the full node by executing this command
+
+```sh
+./target/release/citrea --da-layer bitcoin --rollup-config-path ./resources/configs/testnet/rollup_config.toml --genesis-paths ./resources/genesis/testnet
+```
+
+### Option 3: Using Docker
+
+See the [top section](#tl-dr-i-want-to-run-it-asap).

resources/configs/testnet/rollup_config.toml

@@ -0,0 +1,56 @@
+[public_keys]
+sequencer_public_key = "4682a70af1d3fae53a5a26b682e2e75f7a1de21ad5fc8d61794ca889880d39d1"
+sequencer_da_pub_key = "03015a7c4d2cc1c771198686e2ebef6fe7004f4136d61f6225b061d1bb9b821b9b"
+prover_da_pub_key = "0357d255ab93638a2d880787ebaadfefdfc9bb51a26b4a37e5d588e04e54c60a42"
+
+[da]
+# put in the url of your Bitcoin node
+node_url = "http://0.0.0.0:18443"
+
+#  put in the username and password of your Bitcoin node
+node_username = "citrea"
+node_password = "citrea"
+
+# leave this as is
+network = "testnet"
+tx_backup_dir = ""
+
+[storage]
+path = "./db"
+
+# comment out if you want to set custom max open files
+# if you leave it like this, it will use the system limit
+# db_max_open_files = 5000
+
+[rpc]
+# the host and port to bind the rpc server for
+bind_host = "0.0.0.0"
+bind_port = 8080
+
+# for below if you don't want to use default values
+# comment out and set to desired value
+
+# max connections are deafult to 100
+# max_connections = 100
+
+# max request body size is default to 10MB
+# max_request_body_size = 1048576
+
+# max response body size is default to 10MB
+# max_response_body_size = 1048576
+
+# max batch rpc requests count it default to 50
+# batch_requests_limit = 50
+
+#  subscriptions are enabled by default
+# enable_subscriptions = true
+
+# max subscriptions per connection is default to 100
+# max_subscriptions_per_connection = 100
+
+[runner]
+sequencer_client_url = "https://rpc.testnet.citrea.xyz"
+
+# if you want to store full soft confirmations in your node
+# set this to true
+include_tx_body = false

resources/genesis/testnet/accounts.json

@@ -0,0 +1,3 @@
+{
+  "pub_keys": []
+}