laos-btc

laos-btc is an indexer, block explorer, and command-line wallet. It is experimental software with no warranty. See LICENSE for more details.

It is based on the protocol described in the BRC-721 research paper.

BRC-721 scales the creation, management, and trading of non-fungible tokens (NFTs) on Bitcoin by extending Bridgeless Minting patterns previously used on other blockchains.

The protocol leverages on-chain Bitcoin data to handle all aspects of token ownership, including trading, while integrating a secondary consensus system for minting and optionally modifying token metadata.

To minimize its on-chain footprint, the protocol utilizes the OP_RETURN mechanism for ownership records, while complementary NFT-related actions are stored on the LAOS blockchain. All data remains permanently on-chain, with no reliance on bridges or third-party operators.

The OP_RETURN pattern is heavily inspired by the Runes Protocol, which greatly simplifies previous patterns based on Ordinal Theory, used by Inscriptions/Ordinals.

Wallet

laos-btc relies on Bitcoin Core for private key management and transaction signing. This has a number of implications that you must understand in order to use laos-btc wallet commands safely:

• Bitcoin Core is not aware of inscriptions and does not perform sat control. Using bitcoin-cli commands and RPC calls with laos-btc wallets may lead to loss of inscriptions.

• laos-btc wallet commands automatically load the laos-btc wallet given by the --name option, which defaults to 'laos-btc'. Keep in mind that after running an laos-btc wallet command, an laos-btc wallet may be loaded.

• Because laos-btc has access to your Bitcoin Core wallets, laos-btc should not be used with wallets that contain a material amount of funds. Keep ordinal and cardinal wallets segregated.

Installation

laos-btc is written in Rust and can be built from source.

Once laos-btc is installed, you should be able to run laos-btc --version on the command line.

Building

On Linux, laos-btc requires libssl-dev when building from source.

On Debian-derived Linux distributions (including Ubuntu):

sudo apt-get install pkg-config libssl-dev build-essential

On Red Hat-derived Linux distributions:

yum install -y pkgconfig openssl-devel
yum groupinstall "Development Tools"

You'll also need Rust:

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

Clone the laos-btc repo:

git clone https://github.com/freeverseio/laos-btc.git
cd laos-btc

And finally to actually build laos-btc:

cargo build --release

Once built, the laos-btc binary can be found at ./target/release/laos-btc.

Docker

A Docker image can be built with:

docker build -t laos-btc .

Syncing

laos-btc requires a synced bitcoind node with -txindex to build the index of satoshi locations. laos-btc communicates with bitcoind via RPC.

If bitcoind is run locally by the same user, without additional configuration, laos-btc should find it automatically by reading the .cookie file from bitcoind's datadir, and connecting using the default RPC port.

If bitcoind is not on mainnet, is not run by the same user, has a non-default datadir, or a non-default port, you'll need to pass additional flags to laos-btc. See laos-btc --help for details.

bitcoind RPC Authentication

laos-btc makes RPC calls to bitcoind, which usually requires a username and password.

By default, laos-btc looks a username and password in the cookie file created by bitcoind.

The cookie file path can be configured using --cookie-file:

laos-btc --cookie-file /path/to/cookie/file server

Alternatively, laos-btc can be supplied with a username and password on the command line:

laos-btc --bitcoin-rpc-username foo --bitcoin-rpc-password bar server

Using environment variables:

export ORD_BITCOIN_RPC_USERNAME=foo
export ORD_BITCOIN_RPC_PASSWORD=bar
laos-btc server

Or in the config file:

bitcoin_rpc_username: foo
bitcoin_rpc_password: bar

Logging

laos-btc uses env_logger. Set the RUST_LOG environment variable in order to turn on logging. For example, run the server and show info-level log messages and above:

$ RUST_LOG=info cargo run server

Set the RUST_BACKTRACE environment variable in order to turn on full rust backtrace. For example, run the server and turn on debugging and full backtrace:

$ RUST_BACKTRACE=1 RUST_LOG=debug laos-btc server