Refunds
Anything paid to a SwapIn's address, beyond the deposit the server was paid
for, stays the user's. swap.funds() lists each such output and where its
refund stands:
| Listed | When |
|---|---|
| A stray: a wrong amount, a second deposit, a late one | always |
| The deposit | once the swap is Canceled |
An output the server took by its own path is not listed.
On Liquid only outputs of the swap's asset are listed. One of another asset, such as USDt sent by mistake, stays the user's, but the SDK neither lists nor refunds it: getting it back takes a wallet that spends the swap's script with keys from the same mnemonic and pays the fee in L-BTC.
| Fund state | Meaning |
|---|---|
Locked | Under the CSV until block at, or unconfirmed with no at. |
Refundable | Spendable now and worth its refund: the next refund takes it. |
Dust | Not worth its refund at the last rate: the fee, plus 546 sat on Bitcoin for the smallest output any address takes. Refundable once fees fall far enough. |
Refunding | In our refund txid, paying fee, unconfirmed. |
Refunded | In our refund txid, paying fee, confirmed. |
A refund's fee is the whole transaction's, so every fund it took shows the
same one. Group by txid before adding fees up.
When a fund is refundable
| Situation | Refund |
|---|---|
| The server canceled and handed over its key | at once, by the keypath |
| The server is silent | by the CSV path, once the CSV matures |
A stray lands after the swap is Completed | by the CSV path, once the CSV matures |
The AnySwap server leaves a stray alone once the swap is Completed, but
nothing on chain holds it to that: a server running other code can take the
stray first, and the take can show as Refunding or Refunded. Stop showing
the address once the swap is Completed.
One refund takes at most 8 funds, the most valuable first. The rest stay
Refundable and go in the next refund, once this one confirms. A refund pays
the current fee estimate, capped at
max_fee_rate. While
it is unconfirmed, a pass replaces it at the estimate once the estimate is above
its rate, paid to the address a new refund would go to.
Where refunds go
| The swap has | Refunds |
|---|---|
| A refund address, given at creation | go there by themselves |
| None, and a destinations hook | go where the hook says, by themselves; it is asked once per swap |
| Neither | wait for swap.refund(&address) |
An address of another network, or on Liquid one that is not confidential, is refused wherever it comes from, and the hook is asked again on the next pass.
The hook gives the address of a SwapIn's refund, and of a SwapOut created without a claim address:
- Rust
- TypeScript
#[async_trait]
impl Destinations for MyWallet {
async fn claim_address(&self, chain: Chain) -> Result<String, String> {
self.next_address(chain).await.map_err(|e| e.to_string())
}
async fn refund_address(&self, chain: Chain) -> Result<String, String> {
self.next_address(chain).await.map_err(|e| e.to_string())
}
}
let driver = driver.with_destinations(my_wallet);
driver.withDestinations({
claimAddress: (chain) => myWallet.nextAddress(chain),
refundAddress: (chain) => myWallet.nextAddress(chain),
});
An error from the hook fails the call that asked. A slow hook delays every swap, so bound any remote call in it with a timeout, and never wait on the user there.
refund makes one pass that refunds every Refundable fund to
the address, in any status, and returns the refund's txid. It returns None
while nothing is refundable, or while an earlier refund is unconfirmed and the
fee estimate is not above its rate.
Late deposits
In the background, run keeps watching a
SwapIn after it ends: while its funds are still moving, and for
refund_timeout
after that. It does not see a deposit sent later. Find one with a pass by
hand, step:
- Rust
- TypeScript
if let Some(swap) = driver.get(swap_id).await? {
swap.step().await?;
let funds = swap.funds().await?;
}
const swap = await driver.get(swapId);
if (swap) {
await swap.step();
const funds = await swap.funds();
}
The deposit shows in funds, and the status stays as it was. With somewhere
to refund it, run drives the swap again until that refund confirms. step
finds only a deposit already sent.