[Boltz v2] Notes on expected behaviour with v2

[i5hi]

Boltz v2 is currently supported in boltz-dart and bullbitcoin-mobile can now update the V1Swap classes to V2Swap classes without any major breaking changes. All the existing methods work however there will be some new methods to support stuff like cooperative signing.

With the addition on taproot support, it is now possible for claims and refunds to be signed cooperatively - which has the benefit of the swap looking like a standard single sig taproot. If cooperative signing is not possible, we can use the script path signing, which is like v1 and onchain it will be clear that the transaction is a swap.

The main benefit of the cooperative sign is in the cases of submarine swap refund. We have not faced this issue in dev but in prod it is quite common that for non-malicious reasons, boltz is unable to complete the swap - for example, if their liquidity sees a sudden drop just after the moment the user starts a swap. Boltz has reported that they have had several cases where swaps cannot be completed from their end which leads to a user needing to do a refund. This will be reflected by a transaction status:

transaction.lockupFailed or transaction.invoiceFailedToPay - this should trigger a cooperative refund.

In v1, users would have to wait for 2 weeks to refund. Now in v2, with cooperative signing, we can request a refund immediately and boltz can cooperatively sign with us to refund the transactiontransaction.claim.pending.

Additionally, for submarine swaps - there is a status transaction.claim.pending - where basically boltz needs to claim the transaction and requires us to support them in creating a cooperative claim. So submarine swap has the additional step of posting cooperative claim details to boltz when we get this status. Boltz will not wait long for us to cooperate. If they don't get a response for a while, they will claim via script path, and thats a chance lost to improve privacy.

The flow for reverse swaps is unchanged. the claim() internally always chooses a cooperative spend. We need to also support script path, in the extremely rare case that boltz refuses to cooperate.

[i5hi]

TL;DR (please do read though ;)

New methods in *V2Swap, only applicable to submarine swaps

• coopRefund() triggered by status transaction.lockupFailed or transaction.invoiceFailedToPay - to request boltz to cooperate in our refund tx
• coopClaim() triggered by status transaction.claim.pending - to cooperate with boltz in their claim tx

reverse swaps flow stays unchanged

[i5hi]

reverse swap defaults to coopoerative, we need to add a check, incase boltz doesnt cooperate we need to fall back to script path spend - where try_cooperate: false