Running a Node - Core Lane

Starting the Node

The primary command to run a Core Lane node is start. This launches the JSON-RPC server and begins scanning Bitcoin blocks for Core Lane transactions.

Basic Start Command

core-lane-node start \
  --bitcoin-rpc-read-url http://127.0.0.1:18443 \
  --bitcoin-rpc-read-user bitcoin \
  --bitcoin-rpc-read-password yourpassword \
  --mnemonic-file .mnemonic

Start Command 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

--bitcoin-rpc-write-url

string

Optional separate RPC URL for write/wallet operations (defaults to read URL)

--bitcoin-rpc-write-user

string

Bitcoin RPC username for write operations (defaults to read user)

--bitcoin-rpc-write-password

string

Bitcoin RPC password for write operations (defaults to read password)

--start-block

integer

Bitcoin block height to start scanning from. Only applied on fresh start; ignored when resuming from saved state.

--http-host

string

default:"127.0.0.1"

HTTP server bind address. Use 0.0.0.0 to accept connections from any interface.

--http-port

integer

default:"8545"

HTTP server port for JSON-RPC API

--mnemonic

string

BIP-39 mnemonic phrase (not recommended - visible in process list)

--mnemonic-file

string

Path to file containing mnemonic phrase (recommended)

--electrum-url

string

Electrum server URL for non-regtest networks (e.g., ssl://electrum.blockstream.info:50002)

--sequencer-rpc-url

string

Sequencer RPC URL for forwarding eth_sendRawTransaction calls

--sequencer-address

address

Ethereum address receiving priority fees. Defaults to Anvil test address if not specified.

--on-demand-polling

boolean

default:"false"

Enable on-demand polling mode. Block scanning only occurs when triggered via POST /do_poll.

Operating Modes

Standard Mode
On-Demand Polling
Derived Mode
Espresso Mode

Standard Bitcoin Anchor Mode

Default mode where Core Lane reads taproot DA from Bitcoin blocks:

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 .mnemonic \
  --start-block 100

Behavior:

Scans Bitcoin blocks every 10 seconds
Processes taproot transactions with Core Lane bundles
Builds Core Lane blocks from Bitcoin anchors
Serves JSON-RPC on configured port

On-Demand Polling Mode

Disable automatic scanning, trigger via HTTP:

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 .mnemonic \
  --on-demand-polling

Trigger block scan:

curl -X POST http://127.0.0.1:8545/do_poll

Use cases:

Testing environments
Manual control over block processing
Resource-constrained environments

Derived Chain Mode

Read bundles from another Core Lane instance:

core-lane-node derived-start \
  --core-rpc-url http://127.0.0.1:8545 \
  --chain-id 1281453634 \
  --derived-da-address 0xYourDAAddress \
  --http-port 8546 \
  --start-block 0

Parameters:

--core-rpc-url: Upstream Core Lane JSON-RPC endpoint
--chain-id: Chain ID for this derived instance
--derived-da-address: Address to read DA from
--start-block: Core Lane block to start from (optional)

Espresso Derived Mode

Read bundles from Espresso DA:

core-lane-node derived-espresso-start \
  --espresso-base-url https://query.decaf.testnet.espresso.network/v1 \
  --espresso-namespace 1281453637 \
  --chain-id 1281453634 \
  --core-lane-rpc-url http://127.0.0.1:8545 \
  --http-port 8546

Parameters:

--espresso-base-url: Espresso query service URL
--espresso-namespace: Namespace ID (default: 1281453637 = “LanE”)
--chain-id: Chain ID for this instance
--core-lane-rpc-url: Upstream Core Lane RPC for reorg handling
--start-block: Core Lane block number to start from
--start-anchor: Espresso anchor height to start from

Wallet Management Commands

Create Wallet

Generate a new BIP-39 mnemonic and wallet database:

core-lane-node create-wallet --network regtest

Options:

--network

string

default:"regtest"

Network: bitcoin, mainnet, testnet, testnet4, signet, or regtest

--mnemonic

string

Restore from existing mnemonic instead of generating new one

--mnemonic-only

boolean

default:"false"

Only generate and output mnemonic without creating database file

--electrum-url

string

Perform initial blockchain sync with Electrum server (for non-regtest networks)

Example: Restore from mnemonic:

core-lane-node create-wallet \
  --network mainnet \
  --mnemonic "your twelve word recovery phrase here" \
  --electrum-url ssl://electrum.blockstream.info:50002

Get Wallet Address

Retrieve a receive address from your wallet:

core-lane-node get-address \
  --network regtest \
  --mnemonic-file .mnemonic

Check Bitcoin Balance

Query wallet balance:

core-lane-node get-bitcoin-balance \
  --network regtest \
  --mnemonic-file .mnemonic \
  --rpc-url http://127.0.0.1:18443 \
  --rpc-user bitcoin \
  --rpc-password bitcoin123

For mainnet/testnet, use Electrum:

core-lane-node get-bitcoin-balance \
  --network mainnet \
  --mnemonic-file .mnemonic \
  --electrum-url ssl://electrum.blockstream.info:50002

Transaction Commands

Burn BTC to Core Lane

Create a burn transaction to mint tokens on Core Lane:

core-lane-node burn \
  --burn-amount 1000000 \
  --chain-id 1281453634 \
  --eth-address 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266 \
  --network regtest \
  --mnemonic-file .mnemonic \
  --rpc-password bitcoin123

Parameters:

--burn-amount

integer

required

Amount to burn in satoshis (1 BTC = 100,000,000 sats)

--chain-id

integer

required

Target Core Lane chain ID

--eth-address

address

required

Recipient Ethereum address on Core Lane

--network

string

default:"regtest"

Bitcoin network

Send Transaction

Broadcast a raw Bitcoin transaction:

core-lane-node send-transaction \
  --raw-tx-hex 0201000000... \
  --network regtest \
  --mnemonic-file .mnemonic \
  --rpc-password bitcoin123

Send Bundle

Send a bundle of transactions with optional sequencer payment:

core-lane-node send-bundle \
  --raw-tx-hex 0201000000... \
  --raw-tx-hex 0201000001... \
  --network regtest \
  --mnemonic-file .mnemonic \
  --sequencer-payment-recipient 0xSequencerAddress \
  --marker head

Parameters:

--raw-tx-hex

string

Raw transaction hex strings (specify multiple times for bundle)

--sequencer-payment-recipient

address

Recipient for sequencer payment

--marker

string

default:"standard"

Bundle marker: head (priority) or standard

Store Blob

Store arbitrary data on Core Lane via the blob storage system:

core-lane-node store-blob \
  --rpc-url http://127.0.0.1:8545 \
  --contract 0x0000000000000000000000000000000000000045 \
  --private-key 0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80 \
  --file ./data.bin \
  --max-fee-per-gas 1000000000

Parameters:

--rpc-url

string

default:"http://127.0.0.1:8546"

Core Lane RPC URL

--contract

address

default:"0x0000000000000000000000000000000000000045"

IntentSystem contract address

--private-key

string

required

Private key for signing the transaction (hex format with 0x prefix)

--file

string

required

Path to file containing data to store

--max-fee-per-gas

integer

Maximum fee per gas unit (in wei)

--max-priority-fee-per-gas

integer

default:"0"

Maximum priority fee per gas (in wei)

Blobs are stored on-chain and can be referenced in intents via their hash. Useful for storing program code or large intent parameters.

Bitcoin Cache Server

Run a caching Bitcoin RPC proxy for improved performance:

core-lane-node bitcoin-cache \
  --host 127.0.0.1 \
  --port 8332 \
  --cache-dir ./bitcoin-cache \
  --bitcoin-rpc-url http://127.0.0.1:8332 \
  --bitcoin-rpc-user bitcoin \
  --bitcoin-rpc-password bitcoin123 \
  --block-archive http://144.76.56.210/blocks

Parameters:

--host

string

default:"127.0.0.1"

Cache server bind address

--port

integer

default:"8332"

Cache server port

--cache-dir

string

default:"./bitcoin-cache"

Directory for cached blocks

--bitcoin-rpc-url

string

required

Upstream Bitcoin RPC URL

--no-rpc-auth

boolean

default:"false"

Disable RPC authentication requirement

--block-archive

string

default:"http://144.76.56.210/blocks"

HTTP block archive for historical data

--starting-block-count

integer

Initial block count for cache warmup

--disable-archive-fetch

boolean

default:"false"

Disable fetching from block archive

--s3-bucket

string

S3 bucket name for block storage

--s3-region

string

default:"us-east-1"

S3 region

--s3-endpoint

string

Custom S3 endpoint URL

Wallet Management

Create Wallet

Create a new BDK wallet database with a mnemonic:

core-lane-node create-wallet \
  --network regtest

Parameters:

--network

string

default:"regtest"

Network: bitcoin, testnet, testnet4, signet, or regtest

--mnemonic

string

Optional mnemonic phrase to restore existing wallet (12 or 24 words)

--mnemonic-only

boolean

default:"false"

Only generate and output mnemonic without creating database file

--electrum-url

string

Electrum server URL for non-regtest networks. Performs initial full scan during creation.

Output: Mnemonic phrase and wallet database file (wallet_<network>.sqlite3).

Store the mnemonic phrase securely. It’s required for all operations and cannot be recovered if lost.

Get Wallet Address

Retrieve the wallet’s receiving address:

core-lane-node get-address \
  --network regtest \
  --mnemonic-file .mnemonic

Parameters:

--network

string

default:"regtest"

Network of the wallet to load

--mnemonic

string

Mnemonic phrase (not recommended - visible in process list)

--mnemonic-file

string

Path to file containing mnemonic phrase (recommended)

Get Bitcoin Balance

Check wallet’s Bitcoin balance:

core-lane-node get-bitcoin-balance \
  --network regtest \
  --mnemonic-file .mnemonic \
  --rpc-url http://127.0.0.1:18443 \
  --rpc-user bitcoin \
  --rpc-password bitcoin123

For Regtest:

--rpc-url

string

default:"http://127.0.0.1:18443"

Bitcoin RPC URL

--rpc-user

string

Bitcoin RPC username

--rpc-password

string

Bitcoin RPC password

For Mainnet/Testnet:

--electrum-url

string

Electrum server URL (e.g., ssl://electrum.blockstream.info:50002)

Output:

Total balance
Confirmed balance
Unconfirmed balance
Amounts in both satoshis and BTC

Construct Exit Intent

Create an AnchorBitcoinFill intent for withdrawing to Bitcoin L1:

core-lane-node construct-exit-intent \
  --bitcoin-address bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh \
  --amount 100000 \
  --max-fee 1000 \
  --expire-by 1735689600

Parameters:

--bitcoin-address

string

required

Destination Bitcoin address

--amount

integer

required

Amount in satoshis to withdraw

--max-fee

integer

default:"1000"

Maximum fee in satoshis willing to pay solver

--expire-by

integer

required

Unix timestamp when intent expires

Output: CBOR-encoded intent data ready for submission via intent() call.

Monitoring and Logs

Log Levels

Control logging verbosity with RUST_LOG:

# Info level (default)
RUST_LOG=info core-lane-node start ...

# Debug level (verbose)
RUST_LOG=debug core-lane-node start ...

# Specific module debugging
RUST_LOG=core_lane::state=debug,info core-lane-node start ...

Health Check Endpoint

When running via Docker with Fly.io configuration, health checks are available:

curl http://localhost:8545/health

Metrics

Core Lane tracks operational metrics:

Reorgs detected: Count of blockchain reorganizations
Total sequencer payments: Cumulative priority fees (in wei)
Last block processing time: Duration of last block processing (ms)
Total burned amount: Base fees burned via EIP-1559 (in wei)

Access via state queries or implement custom monitoring endpoints.

State Management

State Persistence

Core Lane automatically persists state to disk:

Full state snapshots: Saved after each block
Delta files: Incremental changes per block
Metastate: EIP-1559 fee manager and totals
Chain index: Bitcoin height to Core Lane block mapping
Tip marker: Current chain tip for crash recovery

State Recovery

On restart, Core Lane:

Reads the tip file to determine last committed block
Loads full chain from chain_index/ (blocks 1..N)
Falls back to tip-only restore if index is incomplete
Resumes scanning from last processed Bitcoin height

Manual State Reset

To reset state and rescan from genesis:

rm -rf blocks/ metastate/ deltas/ chain_index/ tip
core-lane-node start --start-block 0 ...

Production Deployment

Using Docker Compose

version: '3.8'
services:
  core-lane:
    image: ghcr.io/lanelayer/core-lane/core-lane:latest
    ports:
      - "8545:8545"
    volumes:
      - core-lane-data:/data
      - ./mnemonic:/mnemonic:ro
    environment:
      - HTTP_HOST=0.0.0.0
      - HTTP_PORT=8545
      - NETWORK=mainnet
      - ELECTRUM_URL=ssl://electrum.blockstream.info:50002
    command: |
      start 
      --mnemonic-file /mnemonic 
      --http-host 0.0.0.0 
      --http-port 8545

volumes:
  core-lane-data:

Fly.io Deployment

Core Lane includes fly.toml configuration:

# Deploy to Fly.io
fly deploy

# Set secrets
fly secrets set CORE_LANE_MNEMONIC="your mnemonic here"

# Monitor logs
fly logs

# Check status
fly status

Troubleshooting

Node Won’t Start

Check Bitcoin RPC connectivity:

curl --user bitcoin:bitcoin123 \
  --data-binary '{"jsonrpc":"1.0","id":"test","method":"getblockchaininfo","params":[]}' \
  http://127.0.0.1:18443

Verify mnemonic file:

ls -l .mnemonic
cat .mnemonic  # Should show 12 or 24 words

State Corruption

If you see “Failed to deserialize state” errors:

# Nuclear option: wipe all state
rm -rf blocks/ metastate/ deltas/ chain_index/ tip wallet_*.sqlite3
core-lane-node create-wallet --network regtest
core-lane-node start --start-block 0 ...

Port Already in Use

# Find process using port 8545
lsof -i :8545

# Use different port
core-lane-node start --http-port 8546 ...

Wallet Balance Not Updating

For regtest, ensure BDK wallet sync:

# Check balance explicitly
core-lane-node get-bitcoin-balance \
  --network regtest \
  --mnemonic-file .mnemonic \
  --rpc-url http://127.0.0.1:18443 \
  --rpc-user bitcoin \
  --rpc-password bitcoin123

For mainnet/testnet, sync with Electrum happens automatically on startup.

Next Steps

JSON-RPC API

Interact with your node via JSON-RPC

Development Environment

Set up automated testing environment

Overview

Setup & Deployment

Core Concepts

Node Operations

Library Integration

​Starting the Node

​Basic Start Command

​Start Command Options

​Operating Modes

​Standard Bitcoin Anchor Mode

​On-Demand Polling Mode

​Derived Chain Mode

​Espresso Derived Mode

​Wallet Management Commands

​Create Wallet

​Get Wallet Address

​Check Bitcoin Balance

​Transaction Commands

​Burn BTC to Core Lane

​Send Transaction

​Send Bundle

​Store Blob

​Bitcoin Cache Server

​Wallet Management

​Create Wallet

​Get Wallet Address

​Get Bitcoin Balance

​Construct Exit Intent

​Monitoring and Logs

​Log Levels

​Health Check Endpoint

​Metrics

​State Management

​State Persistence

​State Recovery

​Manual State Reset

​Production Deployment

​Using Docker Compose

​Fly.io Deployment

​Troubleshooting

​Node Won’t Start

​State Corruption

​Port Already in Use

​Wallet Balance Not Updating

​Next Steps

JSON-RPC API

Development Environment

Build docs developers (and LLMs) love

Starting the Node

Basic Start Command

Start Command Options

Operating Modes

Standard Bitcoin Anchor Mode

On-Demand Polling Mode

Derived Chain Mode

Espresso Derived Mode

Wallet Management Commands

Create Wallet

Get Wallet Address

Check Bitcoin Balance

Transaction Commands

Burn BTC to Core Lane

Send Transaction

Send Bundle

Store Blob

Bitcoin Cache Server

Wallet Management

Create Wallet

Get Wallet Address

Get Bitcoin Balance

Construct Exit Intent

Monitoring and Logs

Log Levels

Health Check Endpoint

Metrics

State Management

State Persistence

State Recovery

Manual State Reset

Production Deployment

Using Docker Compose

Fly.io Deployment

Troubleshooting

Node Won’t Start

State Corruption

Port Already in Use

Wallet Balance Not Updating

Next Steps