Advanced Topics

This section covers advanced features of the Flashnet AMM SDK including fund recovery mechanisms, background monitoring, and manual clawback operations.

Automatic Fund Recovery

Good news: The SDK automatically handles fund recovery for most failures. When operations like swaps or liquidity additions fail, the SDK attempts to clawback your funds before throwing an error.

How Auto-Clawback Works

When you execute an operation that sends funds to a pool (swap, route swap, add liquidity, or confirm deposit), the SDK:

Transfers your funds to the pool
Executes the operation (signing intents, calling the API)
If the operation fails, checks if the error requires clawback
Automatically claws back your funds if needed
Returns a typed error with recovery status

import { isFlashnetError } from '@flashnet/sdk';

try {
  await client.executeSwap({
    poolId: "pool-id",
    assetInAddress: "btc-address",
    assetOutAddress: "usdb-address",
    amountIn: "100000000",
    minAmountOut: "99000000",
    maxSlippageBps: 100,
  });
} catch (error) {
  if (isFlashnetError(error)) {
    // Check auto-clawback results
    if (error.wasClawbackAttempted()) {
      const summary = error.clawbackSummary!;
      console.log(`Recovery: ${summary.successCount}/${summary.totalTransfers} transfers`);
      
      if (error.wereAllTransfersRecovered()) {
        console.log('✅ All funds recovered!');
      } else {
        console.log('⚠️ Some funds may need manual recovery:', summary.unrecoveredTransferIds);
      }
    }
    
    // Business errors (slippage, liquidity) auto-refund without clawback
    if (error.willAutoRefund()) {
      console.log('Funds will be returned automatically');
    }
  }
}

Operations with Auto-Clawback

Operation	Transfer(s) Protected
`executeSwap`	Input asset transfer
`executeRouteSwap`	Initial asset transfer to first pool
`addLiquidity`	Both asset A and asset B transfers
`createSingleSidedPool`	Initial reserve transfer (during confirm)

Clawback Monitor

For applications that need continuous fund recovery, the SDK provides a background monitor that automatically recovers any stuck transfers.

Starting the Monitor

const monitor = client.startClawbackMonitor({
  intervalMs: 60000,     // Poll every 60 seconds
  batchSize: 2,          // Process 2 clawbacks per batch (rate limit safe)
  batchDelayMs: 500,     // 500ms between batches
  maxTransfersPerPoll: 100,
  
  onClawbackSuccess: (result) => {
    console.log(`✅ Recovered: ${result.transferId}`);
  },
  
  onClawbackError: (transferId, error) => {
    console.error(`❌ Failed to recover ${transferId}:`, error);
  },
  
  onPollComplete: (result) => {
    if (result.transfersFound > 0) {
      console.log(`Poll: ${result.clawbacksSucceeded}/${result.transfersFound} recovered`);
    }
  },
  
  onPollError: (error) => {
    console.error('Poll failed:', error);
  },
});

Monitor Options

Option	Type	Default	Description
`intervalMs`	number	60000	Polling interval in milliseconds
`batchSize`	number	2	Clawbacks per batch (for rate limiting)
`batchDelayMs`	number	500	Delay between batches
`maxTransfersPerPoll`	number	100	Max transfers to fetch per poll
`onClawbackSuccess`	function	-	Called on successful clawback
`onClawbackError`	function	-	Called on failed clawback
`onPollComplete`	function	-	Called after each poll cycle
`onPollError`	function	-	Called if polling itself fails

Controlling the Monitor

// Check if running
console.log('Running:', monitor.isRunning());

// Trigger immediate poll
const result = await monitor.pollNow();
console.log('Found:', result.transfersFound);
console.log('Recovered:', result.clawbacksSucceeded);

// Stop gracefully (waits for current poll to complete)
await monitor.stop();

Poll Result Structure

interface ClawbackPollResult {
  transfersFound: number;      // Clawbackable transfers found
  clawbacksAttempted: number;  // Clawback attempts made
  clawbacksSucceeded: number;  // Successful recoveries
  clawbacksFailed: number;     // Failed attempts
  results: ClawbackAttemptResult[]; // Detailed results
}

Manual Clawback

For cases where you need manual control over fund recovery.

Check Clawback Eligibility

Before attempting clawback, verify a transfer is eligible:

const eligibility = await client.checkClawbackEligibility({
  sparkTransferId: "transfer-id-here"
});

if (eligibility.accepted) {
  console.log('Transfer is eligible for clawback');
} else {
  console.log('Cannot clawback:', eligibility.error);
}

List Clawbackable Transfers

Get all your transfers that can be clawed back:

const response = await client.listClawbackableTransfers({
  limit: 100,
  offset: 0
});

for (const transfer of response.transfers) {
  console.log(`Transfer: ${transfer.id}`);
  console.log(`  Pool: ${transfer.lpIdentityPublicKey}`);
  console.log(`  Created: ${transfer.createdAt}`);
}

Execute Single Clawback

Recover a specific stuck transfer:

async function recoverTransfer(transferId: string, poolId: string) {
  try {
    const response = await client.clawback({
      sparkTransferId: transferId,
      lpIdentityPublicKey: poolId,
    });

    if (response.accepted) {
      console.log('Clawback initiated!');
      console.log('Request ID:', response.internalRequestId);
      console.log('Tracking ID:', response.sparkStatusTrackingId);
    } else {
      console.error('Rejected:', response.error);
    }
  } catch (error) {
    console.error('Clawback failed:', error);
  }
}

Batch Clawback

Recover multiple transfers at once:

const results = await client.clawbackMultiple(
  ['transfer-1', 'transfer-2', 'transfer-3'],
  'pool-id'
);

for (const result of results) {
  if (result.success) {
    console.log(`✅ ${result.transferId} recovered`);
  } else {
    console.log(`❌ ${result.transferId} failed: ${result.error}`);
  }
}

When to Use Manual Clawback

Manual clawback is useful when:

Auto-clawback partially failed - Check error.getUnrecoveredTransferIds() and retry manually
Application crashed mid-operation - Use the monitor or listClawbackableTransfers to find stuck funds
Debugging - Investigate specific transfers before recovery
Custom recovery logic - Implement your own retry strategies

Clawback Eligibility Rules

A transfer is eligible for clawback if:

The authenticated user is the original sender
The transfer was sent to an LP wallet
The transfer is not already reserved or spent
The transfer has not been claimed/settled
The transfer is less than 23 hours old (for eligibility check) or 10 days old (for listing)

Transfers become ineligible after the time limit expires. Use the clawback monitor for continuous recovery.

Error Recovery Decision Tree

Next Steps

Learn about Error Codes and their meanings
See Swaps for swap operations
See Liquidity for liquidity operations

AMM

Quick Start

Concentrated Liquidity (V3)

Position Locks

Position Transfers

Automatic Fund Recovery

How Auto-Clawback Works

Operations with Auto-Clawback

Clawback Monitor

Starting the Monitor

Monitor Options

Controlling the Monitor

Poll Result Structure

Manual Clawback

Check Clawback Eligibility

List Clawbackable Transfers

Execute Single Clawback

Batch Clawback

When to Use Manual Clawback

Clawback Eligibility Rules

Error Recovery Decision Tree

Next Steps

​Automatic Fund Recovery

​How Auto-Clawback Works

​Operations with Auto-Clawback

​Clawback Monitor

​Starting the Monitor

​Monitor Options

​Controlling the Monitor

​Poll Result Structure

​Manual Clawback

​Check Clawback Eligibility

​List Clawbackable Transfers

​Execute Single Clawback

​Batch Clawback

​When to Use Manual Clawback

​Clawback Eligibility Rules

​Error Recovery Decision Tree

​Next Steps

Automatic Fund Recovery

How Auto-Clawback Works

Operations with Auto-Clawback

Clawback Monitor

Starting the Monitor

Monitor Options

Controlling the Monitor

Poll Result Structure

Manual Clawback

Check Clawback Eligibility

List Clawbackable Transfers

Execute Single Clawback

Batch Clawback

When to Use Manual Clawback

Clawback Eligibility Rules

Error Recovery Decision Tree

Next Steps