# Solana Redeem

Redeem BTC.b on Solana to receive BTC.

***

### Overview

The Solana Redeem action burns BTC.b on Solana and releases native BTC to a Bitcoin address. The burn is executed via the Asset Router program, which dispatches a cross-chain GMP (General Message Passing) message to trigger the BTC payout on Bitcoin.

**Flow:** BTC.b (Solana) -> BTC (Bitcoin)

***

### Basic Usage

```typescript
import { createLombardSDK, Chain, AssetId, Env } from '@lombard.finance/sdk';

const sdk = await createLombardSDK({
  env: Env.stage,
  providers: {
    solana: () => window.solana,
  },
});

const redeem = sdk.chain.solana.redeem({
  assetIn: AssetId.BTCb,
  assetOut: AssetId.BTC,
  sourceChain: Chain.SOLANA_DEVNET,
  destChain: Chain.BITCOIN_SIGNET,
});

await redeem.prepare({
  amount: '0.01',
  recipient: 'tb1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh',
});

const result = await redeem.execute();
// result.txHash: '...'
```

***

### Parameters

#### Redeem Options

| Parameter   | Type    | Required | Description                      |
| ----------- | ------- | -------- | -------------------------------- |
| assetIn     | AssetId | Yes      | Input asset (AssetId.BTCb)       |
| assetOut    | AssetId | Yes      | Output asset (AssetId.BTC)       |
| sourceChain | Chain   | Yes      | Solana chain where BTC.b is held |
| destChain   | Chain   | Yes      | Bitcoin network to receive BTC   |

#### Prepare Parameters

| Parameter | Type   | Required | Description                                     |
| --------- | ------ | -------- | ----------------------------------------------- |
| amount    | string | Yes      | Amount of BTC.b to redeem (in BTC, e.g. "0.01") |
| recipient | string | Yes      | Bitcoin address to receive BTC                  |

***

### Supported Routes

| Source Chain   | Destination Chain | Asset In | Asset Out | Environment |
| -------------- | ----------------- | -------- | --------- | ----------- |
| SOLANA\_DEVNET | BITCOIN\_SIGNET   | BTC.b    | BTC       | stage, dev  |

***

### Status Flow

```
IDLE -> READY -> CONFIRMING
```

The flow ends at `CONFIRMING` rather than `COMPLETED`. The Solana-side burn and GMP message dispatch are confirmed, but the Bitcoin-side BTC release is a cross-chain async process that the SDK cannot track directly.

***

### Progress Events

Subscribe to progress events to track the redeem lifecycle:

```typescript
import { createLombardSDK, Chain, AssetId, Env } from '@lombard.finance/sdk';

const sdk = await createLombardSDK({
  env: Env.stage,
  providers: {
    solana: () => window.solana,
  },
});

const redeem = sdk.chain.solana.redeem({
  assetIn: AssetId.BTCb,
  assetOut: AssetId.BTC,
  sourceChain: Chain.SOLANA_DEVNET,
  destChain: Chain.BITCOIN_SIGNET,
});

redeem.on('progress', (progress) => {
  // progress.status: 'IDLE' | 'READY' | 'CONFIRMING'
  // progress.steps.burning: 'IDLE' | 'PENDING' | 'COMPLETE'
  // progress.steps.releasing: 'IDLE' | 'PENDING'
});

await redeem.prepare({
  amount: '0.01',
  recipient: 'tb1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh',
});

const result = await redeem.execute();
```

#### Step Progression

| Phase            | burning  | releasing |
| ---------------- | -------- | --------- |
| After prepare()  | IDLE     | IDLE      |
| During execute() | PENDING  | IDLE      |
| After execute()  | COMPLETE | PENDING   |

The `releasing` step remains `PENDING` because BTC release happens asynchronously on the Bitcoin network.

***

### How It Differs from EVM Redeem

|                   | EVM Redeem               | Solana Redeem              |
| ----------------- | ------------------------ | -------------------------- |
| **Source chain**  | EVM chain (Katana, etc.) | Solana                     |
| **Mechanism**     | Smart contract burn      | Asset Router program + GMP |
| **Final status**  | COMPLETED                | CONFIRMING                 |
| **Approval step** | None                     | None                       |
| **Provider**      | EVM (window\.ethereum)   | Solana (window\.solana)    |

Both redeem flows burn BTC.b and release BTC. The key difference is that Solana uses the Asset Router program with cross-chain GMP messaging, and the final status is `CONFIRMING` because the SDK cannot observe the Bitcoin-side release.

***

### Low-Level Usage

For direct access without the SDK action lifecycle, use the `@lombard.finance/sdk-solana` package:

```typescript
import { redeemForBtc } from '@lombard.finance/sdk-solana';

const txHash = await redeemForBtc(provider, {
  amount: '1000000',
  btcAddress: 'tb1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh',
  network: 'devnet',
  env: 'stage',
});
```

> **Important:** The low-level `redeemForBtc` function expects `amount` in satoshis (integer string), while the high-level `redeem` action accepts amount in BTC (decimal string, e.g. "0.01"). The SDK converts automatically.

#### Low-Level Parameters

| Parameter  | Type          | Required | Description                            |
| ---------- | ------------- | -------- | -------------------------------------- |
| amount     | string        | Yes      | Amount in satoshis (integer string)    |
| btcAddress | string        | Yes      | Bitcoin destination address            |
| tokenMint  | string        | No       | BTC.b mint address override            |
| network    | SolanaNetwork | Yes      | 'mainnet-beta', 'testnet', or 'devnet' |
| env        | Env           | No       | Environment override                   |
| rpcUrl     | string        | No       | Custom RPC endpoint                    |
| debug      | boolean       | No       | Enable debug logging                   |

***

### Error Handling

Common errors for Solana redeem:

| Error                | Cause                                                |
| -------------------- | ---------------------------------------------------- |
| `ROUTE_NOT_FOUND`    | Route not supported for the given chains/environment |
| `INVALID_PARAMETER`  | Amount or recipient is invalid                       |
| `MISSING_PARAMETER`  | prepare() was not called before execute()            |
| Insufficient balance | BTC.b balance is less than the requested amount      |
| Contract paused      | The Asset Router program is in a paused state        |

***

### Provider Setup

The Solana provider must be registered when creating the SDK instance.

```typescript
import { createLombardSDK, Env } from '@lombard.finance/sdk';

const sdk = await createLombardSDK({
  env: Env.stage,
  providers: {
    solana: () => window.solana,
  },
});
```