Binocular enables Cardano smart contracts to access and verify Bitcoin blockchain state. Anyone can submit Bitcoin block headers to a single on-chain Oracle UTxO without registration or bonding. All blocks are validated against Bitcoin consensus rules (proof-of-work, difficulty adjustment, timestamp constraints) enforced by a Plutus smart contract written in Scalus.

Using Nix with flakes and/or direnv is recommended.

nix develop

or

direnv allow

Then build with sbt:

sbt compile
sbt test

Binocular uses HOCON configuration with PureConfig. Configuration is loaded with the following priority (highest wins):

environment variables > --config file > application.conf > reference.conf

Pass a config file with --config:

binocular --config application-preprod.conf <command>

Set bitcoin-node.network to one of: mainnet, testnet, testnet4, regtest.

Set cardano.backend to one of:

• blockfrost -- requires blockfrost-project-id
• yaci -- local Yaci DevKit, uses yaci-store-url and yaci-admin-url

All commands accept --config <path> to specify a configuration file.

These commands support the Bifrost bridge protocol by relaying signed Treasury Movement transactions from Cardano to Bitcoin.

binocular --config application-preprod.conf run

binocular --config application-preprod.conf init --start-block 129400

binocular --config application-preprod.conf prove-transaction <BTC_TX_ID>

# Start the relay daemon
binocular --config application-preprod.conf relay

# Dry-run: check for TMTx UTxOs without broadcasting
binocular --config application-preprod.conf relay --dry-run

# Create a test TMTx UTxO with some hex bytes as the Bitcoin transaction
binocular --config application-preprod.conf create-tmtx 0200000001abcdef...

# Clean up: destroy all TMTx UTxOs
binocular --config application-preprod.conf spend-tmtx

To test with real Bitcoin data, you need Bitcoin Core running locally or access to a remote node.

Quick setup:

export BITCOIN_NODE_URL="http://localhost:8332"
export BITCOIN_NODE_USER="bitcoin"
export BITCOIN_NODE_PASSWORD="your_password"

For detailed setup instructions, see docs/BITCOIN_SETUP.md.

The relay command broadcasts Bitcoin transactions it finds parked on Cardano as TMTx UTxOs. To exercise that flow without waiting on real mempool activity, use regtest-create-tmtx.sh: it mines regtest funds, crafts a BTC transaction, and submits the raw hex as a TMTx on Cardano.

Prerequisites:

• bitcoind running in regtest mode with an RPC-enabled bitcoin.conf
• The Cardano wallet in application-regtest.conf has preprod tADA (override the mnemonic via WALLET_MNEMONIC if you'd rather not commit it)

Run it:

BITCOIN_CONF=/path/to/bitcoin.conf ./regtest-create-tmtx.sh

Optional env overrides: BINOCULAR_CONFIG (default application-regtest.conf), BTC_WALLET (default binocular-regtest), BTC_SEND_AMOUNT (default 0.001).

Verify the relay picks it up:

sbt "run --config application-regtest.conf relay --dry-run"

Drop --dry-run to actually broadcast to regtest bitcoind.

• Whitepaper -- complete technical specification
• Litepaper -- concise overview

./generate-pdfs.sh

Requirements:

• All dependencies are included in the Nix development environment
• On macOS: install Chrome or Chromium separately (brew install --cask google-chrome)
• On Linux: Chromium is provided through Nix

Output: pdfs/Litepaper.pdf, pdfs/Whitepaper.pdf