Devnet

regtest devnet (bitcoind + 2x lnd) manual runbook

Use this doc to run a local regtest devnet (Bitcoin Core + two lnd nodes). It exercises go-lcpd Lightning integration (custom messages, invoice binding, payments).

This devnet is managed by ./scripts/devnet. It stores all state/logs under ./.data/devnet/ (gitignored).

If a step fails, check logs/state under ./.data/devnet/. Re-run with LCPD_LOG_LEVEL=debug.

This doc runs a minimal Quote → Pay → Stream flow with two roles:

• Alice: Provider. Configure Provider mode only on Alice. Use LCPD_BACKEND=deterministic to avoid external APIs.
• Bob: Requester.

Prerequisites

• Go 1.24.4+
• bitcoind / bitcoin-cli on PATH
• lnd / lncli on PATH
• jq on PATH (used in the commands below)

Build go-lcpd CLI tools (one-time)

Install binaries into go-lcpd/bin/:

cd go-lcpd
mkdir -p bin
GOBIN="$PWD/bin" go install ./tools/lcpd-grpcd ./tools/lcpdctl ./tools/lcpd-oneshot

Start / stop

Start:

cd go-lcpd
./scripts/devnet up

Status:

./scripts/devnet status
./scripts/devnet info

Stop:

./scripts/devnet down

Wallet init / unlock (first time)

lnd can start without an initialized wallet, but you must create a wallet before using RPCs (payments/channels/invoices).

First time (interactive):

./scripts/devnet lncli alice create
./scripts/devnet lncli bob create

If unlock is required after restart (interactive):

./scripts/devnet lncli alice unlock
./scripts/devnet lncli bob unlock

Smoke check:

./scripts/devnet lncli alice getinfo
./scripts/devnet lncli bob getinfo

Fund on-chain (make Alice the miner)

1. Create a receive address for Alice:

ADDR="$(./scripts/devnet lncli alice newaddress p2wkh | jq -r .address)"
echo "$ADDR"

2. Mine blocks on regtest to fund Alice (mine 101 blocks to satisfy coinbase maturity):

./scripts/devnet bitcoin-cli generatetoaddress 101 "$ADDR"
./scripts/devnet lncli alice walletbalance

Connect nodes / open channel / pay (make Bob able to pay Alice)

1) Connect to Bob

BOB_PUBKEY="$(./scripts/devnet lncli bob getinfo | jq -r .identity_pubkey)"
BOB_P2P_ADDR="$(./scripts/devnet paths bob | awk -F= '/^p2p_addr=/{print $2}')"

./scripts/devnet lncli alice connect "${BOB_PUBKEY}@${BOB_P2P_ADDR}"
./scripts/devnet lncli alice listpeers

2) Open a channel from Alice → Bob (push funds so Bob can pay)

./scripts/devnet lncli alice openchannel --node_key "$BOB_PUBKEY" --local_amt 10000000 --push_amt 5000000
./scripts/devnet bitcoin-cli generatetoaddress 3 "$ADDR"
./scripts/devnet lncli alice listchannels
./scripts/devnet lncli bob listchannels

# confirm Bob has enough outbound balance to pay Alice (assumes `push_amt` shows up on Bob)
./scripts/devnet lncli bob channelbalance

3) Bob pays an invoice from Alice (connectivity/route check)

PAY_REQ="$(./scripts/devnet lncli alice addinvoice --amt 1000 | jq -r .payment_request)"
./scripts/devnet lncli bob payinvoice "$PAY_REQ"

Try go-lcpd (custom messages / Quote → Pay → Stream)

Once the two lnd nodes are connected as peers, start go-lcpd on both sides. This triggers lcp_manifest exchange over BOLT #1 custom messages. You can observe it via ListLCPPeers.

In this walkthrough, Alice runs as a Provider, streams the result, and sends lcp_result without external dependencies. It uses LCPD_BACKEND=deterministic.

Provider configuration is YAML-first (LCPD_PROVIDER_CONFIG_PATH).

0) Create a Provider YAML config

Example: go-lcpd/provider.devnet.yaml

cd go-lcpd
cat > provider.devnet.yaml <<'YAML'
enabled: true
quote_ttl_seconds: 300

llm:
  max_output_tokens: 512
  models:
    gpt-5.2:
      price:
        # regtest example pricing (choose any policy you like)
        input_msat_per_mtok: 1
        output_msat_per_mtok: 1
YAML

1) Start go-lcpd on Alice (Provider / separate terminal)

cd go-lcpd

export LCPD_BACKEND=deterministic
export LCPD_LOG_LEVEL=debug

export LCPD_PROVIDER_CONFIG_PATH="$PWD/provider.devnet.yaml"

export LCPD_LND_RPC_ADDR="$(./scripts/devnet paths alice | awk -F= '/^rpc_addr=/{print $2}')"
export LCPD_LND_TLS_CERT_PATH="$(./scripts/devnet paths alice | awk -F= '/^tls_cert_path=/{print $2}')"

./bin/lcpd-grpcd -grpc_addr=127.0.0.1:23051

2) Start go-lcpd on Bob (Requester-only / separate terminal)

cd go-lcpd
export LCPD_BACKEND=disabled
export LCPD_LOG_LEVEL=debug

export LCPD_LND_RPC_ADDR="$(./scripts/devnet paths bob | awk -F= '/^rpc_addr=/{print $2}')"
export LCPD_LND_TLS_CERT_PATH="$(./scripts/devnet paths bob | awk -F= '/^tls_cert_path=/{print $2}')"

./bin/lcpd-grpcd -grpc_addr=127.0.0.1:23052

3) Call ListLCPPeers (confirm manifest exchange)

cd go-lcpd
./bin/lcpdctl lcpd list-lcp-peers -s 127.0.0.1:23052 -o prettyjson

If you can see gpt-5.2 under peers[0].remoteManifest.supportedTasks[].openaiChatCompletionsV1.model, it means the Provider successfully advertised the model.

4) Send one job from Bob to Alice (Quote → Pay → Stream)

cd go-lcpd

ALICE_PUBKEY="$(./scripts/devnet lncli alice getinfo | jq -r .identity_pubkey)"

./bin/lcpd-oneshot \
  -server-addr 127.0.0.1:23052 \
  -peer-id "$ALICE_PUBKEY" \
  -pay-invoice \
  -model gpt-5.2 \
  -prompt "Say hello in one word." \
  -timeout 60s

Logs / data locations

• state/log: ./.data/devnet/
• bitcoind log: ./.data/devnet/logs/bitcoind.log
• lnd log: ./.data/devnet/logs/lnd-alice.log / ./.data/devnet/logs/lnd-bob.log

To rebuild from scratch (destructive):

./scripts/devnet down
rm -rf ./.data/devnet