> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nacrelabs.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Redeem wPRL for PRL

> Request a withdrawal and receive native PRL on Pearl.

Redeeming wPRL for PRL is the mirror image of minting. You submit a
**withdrawal request** on Solana, the validator quorum signs a Pearl
redemption transaction, Pearl confirms it, and only then is your wPRL burned.

<Note>
  **UI walkthrough placeholder.** Exact button labels and screenshots will be
  filled in once the Nacre app is published.
</Note>

## How redemption works at a glance

Your wPRL is not burned the moment you click "Withdraw". Instead, it moves
into a **pending withdrawal vault** controlled by the `nacre_two_way_peg`
program. The vault holds your wPRL in escrow until one of two things happens:

* **Pearl confirms your redemption** → the program burns the escrowed wPRL
  and your PRL is in your Pearl wallet.
* **The request expires or you cancel** → the program transfers the escrowed
  wPRL back to your Solana wallet. No burn, no re-mint, nothing destroyed.

This design has a useful consequence: **the wPRL supply on Solana never dips
below the PRL backing it on Pearl**. Tokens are burned only after the
corresponding PRL has already left the Cold Reserve. There is no window where
your wPRL is gone but your PRL hasn't arrived yet.

## Prerequisites

* A Solana wallet holding the wPRL you want to redeem and a small amount of
  SOL for transaction fees.
* A Pearl address where you want to receive PRL.

## Step-by-step

<Steps>
  <Step title="Open the Nacre app and click Withdraw">
    Connect the Solana wallet that holds your wPRL and select **Withdraw PRL**.
    *(UI: withdraw form — screenshot TBD.)*
  </Step>

  <Step title="Enter amount and Pearl recipient">
    Enter the amount of wPRL to redeem and the Pearl address that should
    receive PRL. The app shows you the net PRL you'll receive after fees.
  </Step>

  <Step title="Submit the withdrawal request">
    The app calls `request_withdrawal` on `nacre_two_way_peg`. This:

    * Transfers your wPRL into the **pending withdrawal vault** — a
      program-owned token account that holds it in escrow.
    * Creates a `WithdrawalRequest` PDA describing where the PRL should be
      sent.
    * Emits a `WithdrawalRequestCreated` event the validators see.

    <Tip>
      Your wPRL is held in escrow, **not burned**, until Pearl confirms the
      redemption. If anything goes wrong, the escrow is returned to you in
      full.
    </Tip>

    <Note>
      **No transfer-fee surprises.** wPRL is a Token-2022 mint that supports
      a configurable transfer fee. For the user → vault escrow step the
      program waives that fee (it harvests and refunds the withheld amount in
      the same transaction), so the vault holds the full amount you asked to
      withdraw.
    </Note>
  </Step>

  <Step title="Validators claim a Cold Reserve UTXO">
    Validators independently observe `WithdrawalRequestCreated`, agree on
    which Cold Reserve UTXO will fund your redemption, and post a claim
    on-chain. This binds the chosen UTXO to your request — no two open
    requests can claim the same UTXO.
  </Step>

  <Step title="Wait for the Pearl redemption">
    The aggregator broadcasts the Pearl redemption transaction (Cold
    Reserve → your recipient). The Nacre app shows live progress:

    1. **Requested** — withdrawal request created; wPRL escrowed on Solana.
    2. **UTXO claimed** — validator quorum has bound a Cold Reserve UTXO
       to your request.
    3. **Signed** — quorum has signed the Pearl redemption transaction.
    4. **Broadcast** — redemption transaction in the Pearl mempool.
    5. **Confirmed on Pearl** — Pearl confirms the redemption.
    6. **Burned on Solana** — `complete_redemption` runs; escrowed wPRL is
       burned and your request is closed.
  </Step>

  <Step title="Receive PRL on Pearl">
    PRL arrives at your specified recipient address as soon as the Pearl
    redemption transaction confirms — which happens **before** your wPRL is
    burned on Solana.
  </Step>
</Steps>

## Fees

Burn fees follow the same three-component structure as mint fees. See
[Fees](/wprl/overview#fees) for the current parameters.

```
user_net_prl = withdraw_amount − miner_fee − validator_margin − protocol_fee
```

The Token-2022 transfer fee is **not** charged on the user → vault escrow
step, so the only fees you pay are the three above.

## How long does it take?

| Phase                                      | Typical duration        |
| ------------------------------------------ | ----------------------- |
| Solana withdrawal request (escrow)         | \< 1 minute             |
| Cold Reserve UTXO claim on Solana          | seconds                 |
| Validator quorum signing + Pearl broadcast | seconds to minutes      |
| Pearl redemption confirmation              | 1 Pearl block (\~`TBD`) |
| Solana attestation + escrow burn           | seconds                 |
| **End-to-end**                             | **`TBD`**               |

## What if it doesn't go through?

If the redemption is not completed before the request's expiry, anyone can
call `cancel_expired_withdrawal` (the Nacre app does this for you). This
returns the **full escrowed amount** from the vault to your Solana wallet
via a Token-2022 transfer — no fee, no re-mint, no token destroyed. The
Cold Reserve UTXO that was bound to your request is freed for a future
request.

## Troubleshooting

<AccordionGroup>
  <Accordion title="I submitted the withdrawal but PRL hasn't arrived">
    Check the request status in the Nacre app. If the redemption has been
    broadcast it will appear in your Pearl wallet after one confirmation. If
    the request is stuck for more than a few hours, contact support (`TBD`).
    If the request reaches its expiry without completing, you (or anyone)
    can cancel it and the escrowed wPRL will be returned to your wallet in
    full.
  </Accordion>

  <Accordion title="I want to cancel a pending withdrawal">
    Withdrawals that have not yet been signed by the quorum can be cancelled
    from the Nacre app, which returns the escrowed wPRL to your wallet.
    Once a Pearl redemption has been broadcast, the request can no longer be
    cancelled — wait for it to confirm.
  </Accordion>

  <Accordion title="I burned wPRL with the SPL burn instruction directly">
    The SPL `Burn` instruction destroys tokens but does **not** release PRL
    on Pearl. There is no recovery path — only withdrawals initiated via
    `request_withdrawal` redeem the underlying PRL. Always use the Nacre
    app or call `nacre_two_way_peg` directly.
  </Accordion>
</AccordionGroup>