Skip to main content

Refunds

When a swap in the Smart Chain → Bitcoin direction fails, you can refund your tokens back to your wallet, this can happen when:

  • the LP tried to execute but failed (e.g. Lightning routing failed) and returned a cooperative refund authorization allowing the user to refund immediately.
  • the LP went offline and didn't execute the swap within the timelock period, in this case you have to wait for the timelock to expire this is 12 hours for Bitcoin on-chain swaps and 4-5 days for Lightning network swaps (swap then becomes refundable automatically).
Runnable Example

See the complete working example: utils/pastSwaps.ts

Checking Refund Status​

Check if a swap is refundable with the isRefundable() function exposed in ToBTCSwap and ToBTCLNSwap classes. You can also use the getExpiry() function to determine when the swap becomes refundable in case of LP going offline.

// Check if swap is refundable
if (swap.isRefundable()) {
  // Refund with a signer object
  await swap.refund(signer);
} else if (swap.isInProgress()) {
  // Check when the swap becomes refundable if the LP doesn't execute it
  const refundableAt: number = swap.getExpiry(); // Returns UNIX timestamp milliseconds
  console.log(`The swap will become refundable at ${new Date(refundableAt).toString()}`);
}

Get All Refundable Swaps​

tip

It's good practice to check for refundable swaps when your app starts and also periodically if your app is long-running. You can then either refund the swaps automatically or prompt the user to authorize a refund.

To retrieve all the swaps that are currently refundable call the getRefundableSwaps() function on the swapper, which returns the swaps with IToBTCSwap abstract class. You can also pass in the chain identifier and signer address to retrieve swaps only for that respective smart chain and/or signer.

import {IToBTCSwap} from "@atomiqlabs/sdk";

// Returns all refundable swaps from storage if no argument is passed
const allRefundableSwaps: IToBTCSwap[] = await swapper.getRefundableSwaps();
// You can check the respective swap's chain by reading its chainIdentifier property
for (let swap of allRefundableSwaps) {
  const chainId = swap.chainIdentifier; // Retrieves smart chain type of the swap, e.g.: SOLANA, STARKNET, CITREA, ...
  // Retrieve the relevant smart chain signer for the chainId
  const signer = smartChainSigners[chainId];
  // We can also additionally check if the swap is indeed created by the signer
  if (swap.getInputAddress() === signer.getAddress()) {
    await swap.refund(signer);
  }
}
info

Type of the signer object passed to the refund() function is dependent on the source network:

Manually Signing Transactions​

You can alternatively use the txsRefund() function to retrieve the smart chain transactions that you can then sign and send manually:

const txsRefund = await swap.txsRefund();
... // Sign and send refund transactions here
// Important to wait till SDK processes the swap refund and updates the swap state
await swap.waitTillRefunded();
info

The transactions returned by the txsRefund() function use the following types:

For more information about how to sign and send these transactions manually refer to the Manual Transactions page.

API Reference​