Skip to content

Developer Guide

This page covers atomic swaps, RPC integration, block explorers, mining pools, and other developer workflows for the Bitcoin Gold ecosystem.

Atomic swap

Hashed timelock contracts are the building block for atomic swaps between compatible UTXO chains. Bitcoin Gold exposes the required script primitives, but a safe swap also depends on transaction-signing rules, fee handling, timelock selection, reorganization policy, and well-tested counterparty software. Treat the following flow as a design concept, not a ready-to-use product.

How it works

  1. Party A (BTG holder) creates a HTLC on the BTG chain that locks funds. The contract includes:
  2. A hash of a secret H(x)
  3. A refund timeout (e.g. 48 hours)
  4. Party B (BTC holder) creates a corresponding HTLC on the BTC chain using the same H(x).
  5. Party A claims the BTC by revealing x on the BTC chain.
  6. Party B, now knowing x, claims the BTG before the timeout expires.

No maintained turnkey BTG atomic-swap package is recommended here. Review BIP-199, inspect the exact scripts and sighash behavior, and test every success and refund path on regtest before risking funds.

Manual HTLC example

# Create a P2SH address that encumbers funds with a SHA256 hashlock
# and a timelock refund. This is a simplified conceptual example.

# 1. Generate the redeem script (HTLC)
#    OP_IF
#        OP_SHA256 <hash> OP_EQUALVERIFY OP_DUP OP_HASH160 <pubkey> OP_EQUALVERIFY OP_CHECKSIG
#    OP_ELSE
#        <timeout> OP_CHECKLOCKTIMEVERIFY OP_DROP OP_DUP OP_HASH160 <pubkey> OP_EQUALVERIFY OP_CHECKSIG
#    OP_ENDIF

# 2. Fund the P2SH address with bgold-cli
bgold-cli sendtoaddress <p2sh_address> <amount>

# 3. Redeem by revealing the preimage
bgold-cli createrawtransaction ...

Additional developer topics

RPC API integration

BTG Core exposes a Bitcoin Core-derived JSON-RPC API with version-specific and Bitcoin Gold-specific differences. Treat bgold-cli help on the deployed binary as the source of truth. Common integration patterns include:

  • Block monitoring: poll getblockcount and getblock for new blocks.
  • Transaction broadcasting: use sendrawtransaction to relay signed txs.
  • Wallet operations: getbalance, listunspent, createrawtransaction, signrawtransactionwithwallet.

Building a block explorer

The original Trezor Blockbook project includes Bitcoin Gold support and an upstream bgold coin definition. It can build an address index in RocksDB and expose APIs for addresses, transactions, and blocks. See the Blockbook operator guide.

Creating a mining pool

Start from actively maintained pool software that explicitly supports Equihash-BTG (N=144, K=5 and BgoldPoW). Do not adapt an Ethereum pool or assume generic Equihash support is sufficient. See the Mining pool guide for the required constants and validation steps.

Smart contracts

BTG does not natively support Turing-complete smart contracts (no EVM). However, you can use: - OP_RETURN outputs to embed limited application data on-chain. - Multisignature wallets for cooperative custody. - HTLC-based contract patterns for conditional payments and atomic swaps.

Development environment setup

# Install BTG Core from source or use a pre-built binary
sudo apt install -y build-essential libtool autotools-dev automake pkg-config \
  libssl-dev libevent-dev bsdmainutils libboost-all-dev \
  libminiupnpc-dev libzmq3-dev libdb-dev libdb++-dev

# Clone and build
git clone https://github.com/BTCGPU/BTCGPU.git
cd BTCGPU
./autogen.sh
./configure --without-gui --with-incompatible-bips
make -j"$(nproc)"
sudo make install

Testing and debugging

  • regtest mode: Fast, local-only chain for rapid iteration.
  • testnet v3: Public test network; verify that working peers and test coins are available before depending on it.
  • bgold-cli generatetoaddress: Mine regtest blocks to an address returned by the local wallet.
  • -debug=1: Enable verbose logging.
  • -printtoconsole: Log to stdout (useful in Docker).

Further reading