🚫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 redeem 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](https://en.bitcoin.it/wiki/Script).

Lightning Invoice Verification

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

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

• Has the same amount as 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 check that EVM swaps are carried out using a legitimate contract by comparing the bytecode of it to a verified version or hardcoding the address of a verified version.

Taproot Swaps Script Path Fallback

Key path spends in the Taproot Swap protocol rely on Boltz cooperating. Should Boltz disappear or refuse to cooperate, for Chain and Normal Submarine Swaps, Boltz API clients must implement a fallback to the script path to be able to enforce claim and refund transactions.

General Measurements

Boltz API clients should calculate swap amounts locally to verify that expectedAmount in the API responses matches the locally calculated amount.