🚫Don't trust. Verify!

This document gives an overview of how Boltz API clients should verify information generated by Boltz and other general measurements that should be undertaken to minimize trust.

Basics

As a general concept, Boltz API clients should not trust any critical information obtained via the Boltz API. This applies especially to chain addresses and lightning invoices where users will send bitcoin to.

UTXO Chain Address Verification

Taproot

The scripting section explains how to verify P2TR addresses in Taproot Swaps.

Legacy

Boltz currently supports two types of addresses for legacy swaps:

• P2SH nested P2WSH for Normal Submarine Swaps

• P2WSH for Reverse Submarine Swaps

Boltz API returns a redeem script and a derived chain address when creating swaps. Boltz API clients should verify that the redeem script is valid by checking preimage hash, public key, timeout block height of the HTLC and OP codes. An example of an implementation in TypeScript can be found here. Boltz API clients should also verify the correctness of the given address:

P2SH nested P2WSH

Although the output script of the P2SH nested P2WSH addresses is the same as the one of plain P2SH addresses, other data is hashed. Here, not the plain redeem script is hashed, but a P2WSH output script is constructed and first hashed with SHA256 and then hashed again with RIPEMD-160. The output script will look like this:

OP_HASH160
<RIPEMD-160 hash of the SHA256 hash of the P2WSH output script>
OP_EQUAL

P2WSH

In P2WSH addresses the reedem script is hashed with SHA256. The output script is also a little simpler:

OP_0
<SHA256 hash of the redeem script>

Examples

Examples for generating all of these addresses with Node.js can be found in the boltz-core reference library.

Address verification applies to all swap types involving a UTXO chain. A list of Bitcoin mainchain Opcodes with description can be found on the Bitcoin Wiki.

Lightning Invoice Verification

Swap amounts should be calculated by the API client (taking into account network fee & Boltz fee from /getpairs). Boltz API clients then should decode and verify that a Lightning invoice generated by Boltz

• Has the same preimage hash that the client previously generated and used to call /createswap.

• Has the same amount than the amount used to call /createswap.

Examples in JavaScript can be found here.

Boltz API clients should also verify that amounts in user-provided invoices match calculated swap amounts to prevent user error.

EVM Chain Contract Verification

Boltz API clients should verify that EVM swaps are carried out using the correct contract by comparing the bytecode of the contract.

General Measurements

Boltz API client should verify that expectedAmount in Boltz API responses matches locally calculated amount.