rgb-lib methods psbt_op_prepare, psbt_op_apply, and psbt_op_abort for external HTLC spends.
Build the lock template
Utexo calls the user-broadcast transaction callback. The request includespsbt_data.protocol_pub_key and psbt_data.user_source_pub_key.
- Load the asset and amount from the quote. The callback request does not include them.
- Build the Bitcoin HTLC with the NUMS internal key, the resolver claim leaf, the protocol timelock refund leaf, and the cooperative fast-refund leaf.
- Build the template PSBT with the intent tag at output
0and the P2TR HTLC at output1. - Return the template as
calldata.Psbt.bitcoin_psbt, withpsbt,x_only_public_key,refund_control_block, andfast_refund_control_block. - Persist the lock address, Taproot spend data, and resolver claim leaf.
destination_script_hex field.
Utexo derives the invoice from the template. The user’s RGB wallet then creates and broadcasts the colored lock transaction. Track the actual deposit outpoint rather than the template’s transaction ID.
Fulfill the swap
AfterUserDepositConfirmed, deliver the destination asset and report the fulfillment through the Protocol API.
Claim the RGB allocation
After fulfillment, retrieve the revealed secret and spend the HTLC into a witness receive output owned by your RGB wallet.- Fetch the lock consignment with
fetch_consignment_by_recipient_id_unchecked. - Check that its transaction ID and output index match the confirmed lock. Import it with
accept_transfer_from_consignment_uncheckedand anExpectedTransferfor the exact asset, schema, and amount. - Check the HTLC allocation with
contract_assignments_for_outpoints. - Create a witness receive destination in your wallet.
- Build an unsigned claim PSBT. Use the HTLC as the input, an empty
OP_RETURNat output0, and your receive destination at output1. - Add the claim leaf, control block, and witness UTXO to the HTLC input.
- Call
psbt_op_preparewith the asset assigned to output1and the HTLC as the input that carries RGB. Save the returnedoperation_id. - Post the resulting consignment to the RGB proxy.
- Sign the HTLC input with the witness stack
[signature, secret, script, control block]. - Broadcast the claim transaction.
- Once the transaction is visible to the indexer, call
psbt_op_applywithoperation_id. Refresh the wallet.
psbt_op_abort with operation_id.
The checked fetch_and_accept_transfer_by_recipient_id method requires a wallet-owned witness script and rejects the external HTLC. The unchecked import still validates the consignment, but your integration must check the lock outpoint and expected transfer.
Color the PSBT before you sign any input. Include every input that holds RGB and assign its full allocation. Use the final output indexes in the asset map.
The HTLC is not a wallet UTXO. Accept its consignment before you inspect the allocation, and do not register the HTLC as a wallet output.