Skip to main content

​
Overview

This guide will walk you through setting up a Core Lane node on Bitcoin regtest for local development and testing. You’ll have a fully functional node running in under 10 minutes.
This quickstart uses Bitcoin regtest for local development. For testnet or mainnet setup, see Running a Node.

​
Prerequisites

Before starting, ensure you have:

Rust & Cargo

Install via rustup: curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Docker

Required for running Bitcoin regtest. Install from docker.com

Git

To clone the repository

8GB+ RAM

Recommended for building and running

​
Installation

1

Clone the repository

Clone the Core Lane repository from GitHub:
git clone https://github.com/lanelayer/core-lane
cd core-lane
2

Build the node

Build the Core Lane node binary using Cargo:
cargo build --release
This will compile the core-lane-node binary to target/release/core-lane-node.
The first build may take 5-10 minutes as Cargo downloads and compiles dependencies. Subsequent builds are much faster.
For faster compilation during development, use debug mode:
cargo build
The binary will be at target/debug/core-lane-node. Debug builds compile faster but run slower.
3

Verify installation

Verify the build succeeded:
./target/release/core-lane-node --help
You should see the Core Lane command-line interface help output.

​
Start Development Environment

The easiest way to get started is using the provided development environment script:
1

Start the environment

Use the Makefile command to start the complete development stack:
make dev-start
This script will:
  • Start a Bitcoin regtest Docker container
  • Create a BDK wallet with a new mnemonic
  • Mine initial blocks to fund the wallet
  • Start the Core Lane node
  • Begin automatic block mining
The dev-start command runs scripts/dev-environment.sh, which:
  1. Starts Bitcoin Core 30.0 in regtest mode on port 18443
  2. Creates a BDK wallet and saves the mnemonic to .dev-wallets/mnemonic_regtest.txt
  3. Mines 111 blocks to the wallet address (101 for coinbase maturity + 10 buffer)
  4. Launches the Core Lane node with JSON-RPC on port 8546
  5. Starts a mining loop that creates new blocks every 10 seconds
2

Check status

Verify everything is running:
make dev-status
You should see:
  • Bitcoin container status
  • Block height
  • Core Lane node status
  • Wallet balance
3

Access the node

Your Core Lane node is now running with a JSON-RPC server at:
http://127.0.0.1:8546
Test it with a simple balance query:
curl -X POST http://127.0.0.1:8546 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "eth_getBalance",
    "params": ["0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266", "latest"],
    "id": 1
  }'
The development environment saves your wallet mnemonic to .dev-wallets/mnemonic_regtest.txt. Keep this file secure and never commit it to version control.

​
Manual Setup (Alternative)

If you prefer to set up components manually:
1

Start Bitcoin regtest

Start a Bitcoin regtest node using Docker:
docker run --rm -d --name bitcoin-regtest \
  -p 18443:18443 -p 18444:18444 \
  -v $HOME/bitcoin-regtest:/bitcoin/.bitcoin \
  bitcoin/bitcoin:30.0 \
  -regtest \
  -fallbackfee=0.0002 \
  -server=1 \
  -rpcuser=bitcoin \
  -rpcpassword=bitcoin123 \
  -rpcallowip=0.0.0.0/0 \
  -rpcbind=0.0.0.0 \
  -txindex=1
2

Create wallet

Create a new Core Lane wallet:
./target/release/core-lane-node create-wallet --network regtest
Save the output mnemonic to a file:
mkdir -p .wallets
echo "your mnemonic words here" > .wallets/mnemonic.txt
chmod 600 .wallets/mnemonic.txt
3

Get wallet address

Get your wallet’s Bitcoin address:
./target/release/core-lane-node get-address \
  --network regtest \
  --mnemonic-file .wallets/mnemonic.txt
4

Fund the wallet

Mine blocks to your wallet address:
# Mine 101 blocks for coinbase maturity
docker exec bitcoin-regtest bitcoin-cli \
  -regtest -rpcuser=bitcoin -rpcpassword=bitcoin123 \
  generatetoaddress 101 "YOUR_WALLET_ADDRESS"
5

Start Core Lane node

Start the Core Lane node:
./target/release/core-lane-node start \
  --bitcoin-rpc-read-url http://127.0.0.1:18443 \
  --bitcoin-rpc-read-user bitcoin \
  --bitcoin-rpc-read-password bitcoin123 \
  --mnemonic-file .wallets/mnemonic.txt \
  --http-host 127.0.0.1 \
  --http-port 8545
By default, the node scans from Bitcoin block 0. Use --start-block to start from a specific block height.

​
Try Your First Transaction

Now that your node is running, let’s create a burn transaction to bridge Bitcoin to Core Lane:
1

Create a burn transaction

Use the burn command to send Bitcoin to an unspendable address and mint equivalent balance on Core Lane:
./target/release/core-lane-node burn \
  --burn-amount 500000 \
  --chain-id 1 \
  --eth-address "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266" \
  --network regtest \
  --mnemonic-file .wallets/mnemonic.txt \
  --rpc-url http://127.0.0.1:18443 \
  --rpc-user bitcoin \
  --rpc-password bitcoin123
This burns 500,000 satoshis (0.005 BTC) and mints the equivalent on Core Lane to the specified Ethereum address.
2

Mine a block

Mine a Bitcoin block to confirm the burn transaction:
docker exec bitcoin-regtest bitcoin-cli \
  -regtest -rpcuser=bitcoin -rpcpassword=bitcoin123 \
  generate 1
3

Check balance

Query the Core Lane balance:
curl -X POST http://127.0.0.1:8545 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "eth_getBalance",
    "params": ["0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266", "latest"],
    "id": 1
  }'
You should see a non-zero balance representing the burned Bitcoin.

​
Available Make Commands

The project includes a comprehensive Makefile with helpful commands:

​
Build Commands

make build          # Build the Core Lane node
make clean          # Clean build artifacts
make check          # Run cargo check
make fmt            # Format code with rustfmt
make clippy         # Run clippy linter

​
Test Commands

make test           # Run all tests (unit + integration)
make test-unit      # Run unit tests only
make test-integration  # Run integration tests only

​
Development Environment

make dev-start      # Start complete dev environment
make dev-stop       # Stop dev environment
make dev-status     # Check environment status
make dev-balances   # Check wallet balances

​
Demo Commands

make run-burn       # Run a demo burn transaction
make run-node       # Run the Core Lane node

​
Stopping the Environment

When you’re done: 
make dev-stop
This will:
  • Stop the Core Lane node
  • Stop the mining loop
  • Stop the Bitcoin regtest container
Stopping the environment will remove the Bitcoin regtest data. Your Core Lane state is preserved in the working directory.

​
Configuration Options

The core-lane-node start command supports many configuration options:
​
bitcoin-rpc-read-url
string
default:"http://127.0.0.1:18443"
Bitcoin RPC URL for reading blockchain data
​
bitcoin-rpc-read-user
string
default:"user"
Bitcoin RPC username for read operations
​
bitcoin-rpc-read-password
string
required
Bitcoin RPC password for read operations
​
mnemonic-file
string
required
Path to file containing 12 or 24 word mnemonic phrase
​
electrum-url
string
Electrum server URL (required for mainnet/testnet)
​
start-block
integer
Bitcoin block height to start scanning from
​
http-host
string
default:"127.0.0.1"
Host for JSON-RPC server
​
http-port
integer
default:"8545"
Port for JSON-RPC server
​
sequencer-rpc-url
string
Sequencer RPC URL for transaction forwarding
​
sequencer-address
string
Sequencer address for priority fee collection
​
on-demand-polling
boolean
Enable on-demand polling mode (disable automatic block scanning)

​
Troubleshooting

Make sure you have the latest Rust toolchain:
rustup update
cargo clean
cargo build --release
Check if Docker is running:
docker info
Make sure port 18443 is not already in use:
lsof -i :18443
Verify Bitcoin RPC is accessible:
curl --user bitcoin:bitcoin123 \
  --data-binary '{"jsonrpc":"1.0","id":"1","method":"getblockchaininfo","params":[]}' \
  -H 'content-type: text/plain;' \
  http://127.0.0.1:18443/
Make sure the data directory is writable:
chmod 755 .
Try specifying a custom data directory:
./target/release/core-lane-node --data-dir ./data create-wallet --network regtest

​
Next Steps

Architecture Overview

Learn how Core Lane works under the hood

JSON-RPC API

Explore the full API reference

Node Configuration

Configure your node for production

Intent System

Create intent-based transactions

Build docs developers (and LLMs) love

Get started for freeTalk to us