description |
---|
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. |
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.
The scripting section explains how P2TR addresses are created for Taproot swaps.
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:
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
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 for generating all of these addresses with Node.js
can be found in the boltz-core
reference library.
Note: 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.
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.
Boltz API clients should verify that EVM swaps are carried out using the correct contract by comparing the bytecode of the contract.
Boltz API client should verify that expectedAmount
in Boltz API responses matches locally calculated amount.