Alpen full node operator guide

Prerequisites

Before you begin, ensure you have met the following requirements:

• Docker: Make sure Docker is installed on your machine. You can download it from here.

• Docker Compose: Ensure Docker Compose is installed. It typically comes bundled with Docker Desktop.

• Git: To clone the repository. Download from here.

Installation

Follow these steps to set up and run the project.

1. Clone the alpen repository

git clone https://github.com/alpenlabs/alpen.git
cd alpen
git checkout releases/0.2.0
cd docker

2. Configure environment variables

Create a .env file in the docker/ directory of the repository with the following contents:

Testnet .env Content:

# signet
SIGNETCHALLENGE=0014d9cbf4a8f28335be5e4ab2e1bc6ef3141cf9dc16
ADDNODE=bitcoin.testnet.alpenlabs.io

# reth
JWTSECRET=/app/configs/jwt.hex

Fullnode must use the provided .env to connect to and sync from alpen testnet chain.

3. Configure parameters

Create a params.json file in the configs directory with the following contents.

{
  "rollup_name": "alpn",
  "block_time": 5000,
  "da_tag": "strata-da",
  "checkpoint_tag": "strata-ckpt",
  "cred_rule": {
    "schnorr_key": "56853901c9c138419efb50e0fb1ff88d669ba81d2524ed46d1601627444d0793"
  },
  "horizon_l1_height": 90,
  "genesis_l1_height": 100,
  "operator_config": {
    "static": [
        { "signing_pk" : "73d5bb0995cd5f3e799f56646dd54195d4f9d6c56a70a37a4a5d79390eae1c8a", "wallet_pk" : "0x072bd753063d293f0420525dde2000661204d3f5fd1a1ab2632330986735b591" },
        { "signing_pk" : "d644794228df8782bd7ecc238887dba9d062b9f429537291d310c5dc6ffc592d", "wallet_pk" : "0x7b8d21b6ad6e2bf8dc0e7eca02e388b87f4330d5589bc908cc4e0a22d20600d4" },
        { "signing_pk" : "d644794228df8782bd7ecc238887dba9d062b9f429537291d310c5dc6ffc592d", "wallet_pk" : "0x694db4b2bfcd8621d49a640eaa07f098d22131aa13fa3611d0e707116470fcdf" },
        { "signing_pk" : "d644794228df8782bd7ecc238887dba9d062b9f429537291d310c5dc6ffc592d", "wallet_pk" : "0x392b9767f6f50ebfa09a2ab891a15947bd9741f9fda94141a2a93043b50e25f6" }
    ]
  },
  "evm_genesis_block_hash": "7746263a5cd7323bd2c31045c385db79947e35fe646e7cba3fbadd5ed6220b0e",
  "evm_genesis_block_state_root": "56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421",
  "l1_reorg_safe_depth": 4,
  "target_l2_batch_size": 64,
  "address_length": 20,
  "deposit_amount": 1000000000,
  "rollup_vk": {
    "sp1": "002daefe7f3a6c10aae976b13e16542d1a9c4036f23978c5188f20f66dcae897"
  },
  "dispatch_assignment_dur": 64,
  "proof_publish_mode": {"timeout":10800},
  "max_deposits_in_block": 16,
  "network": "signet"
}

Full node must use the provided params.json to be in consensus with the strata testnet chain.

4. Generate keys

Generate jwt.hex inside configs directory file with jwt keys. This is used for authentication between alpen-reth and alpen-client for engine-api auth-rpc.

od -An -tx1 -N32 /dev/urandom | tr -d ' \n' > configs/jwt.hex

Running the services

Once you have configured the environment and generated the necessary keys, you can start the services using Docker Compose.

docker compose -f docker-compose-fullnode.yml up -d

Make sure you have correctly installed docker and docker is up and running.

Initial sync can take several hours based on network latency and machine load. The sync status can be checked using an rpc call to strata_syncStatus method:

curl --location 'localhost:8432' \
--header 'Content-Type: application/json' \
--data '{
 "jsonrpc":"2.0",
 "method":"strata_syncStatus",
 "params":[],
 "id": 1
}'

Pairing with a local wallet

If your wallet supports connecting to custom EVM networks, then you can connect your wallet to your Alpen full node to view your account balance and send transactions.

1. Click the button in your wallet that enables you to add a custom network

2. Enter the following values:

   1. Network name: Alpen Testnet

   2. Default RPC URL: http://localhost:8545

   3. Chain ID: 2892

   4. Currency symbol: sBTC

   5. Block explorer URL: https://explorer.testnet.alpenlabs.io

Troubleshooting

• Service fails to start:

  • Ensure all environment variables in .env are correctly set.

  • Verify that params.json is correctly placed in the configs directory.

  • Check Docker logs for more details:

docker compose -f docker-compose-fullnode.yml logs -f

• Ports already in use:

  • If any of the specified ports are already in use, either stop the conflicting service or modify the port mappings in the docker-compose.yml file.

• Client cannot connect to bitcoin node and exits:

  • Make sure the environment variables in .env are correctly set as in step 2.

  • Bitcoin node probably started later than the client. Make sure bitcoin node has started and then restart client.

• Initial Sync does not make progress or fails

  • Check that the urls provided in .env are accessible from the machine.

  • If FATAL ERROR: block not found: is seen in the client logs after restart, delete data/reth and data/strata directories and restart.

• If nothing else seems to work

  • Stop all the containers: docker compose -f docker-compose-fullnode.yml down

  • Delete the data directory and restart the containers: docker compose -f docker compose-fullnode.yml up