> ## 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.

# Solana side

> The four Anchor programs that handle wPRL on Solana.

Four Anchor programs split the on-chain logic by responsibility:

| Program                      | Responsibility                                                                                                                                                                                                                                                       |
| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `nacre_two_way_peg`          | Mint / escrow-claim-burn state machine. Owns deposit attestations, withdrawal requests, Cold Reserve UTXO claims, the wPRL mint authority (via a `[mint_authority]` PDA), the fee math, and the `protocol_treasury` PDA every fee lands in.                          |
| `nacre_liquidity_management` | Hot Reserve + Cold Reserve registry. Holds per-user `HotReserveBucket` PDAs and the global `ColdReserveBucket`.                                                                                                                                                      |
| `nacre_layer_ca`             | Validator certificate authority. Stores `ValidatorCertificate` PDAs keyed by the validator's raw P-256 pubkey, with a human-readable operator name. Payout addresses, jurisdiction, and quorum membership all live off-chain in the sig-aggregator config.           |
| `nacre_protocol_config`      | Tunable parameters (fee bps, confirmation depth, pause flag, admin pubkeys) **and** the active validator set — `validator_count`, `validator_quorum_threshold`, and the custody-wallet pubkeys the quorum controls. There is no separate validator-registry program. |

Validator payouts happen off-chain by joining the `submitter_pubkey`
field on `DepositAttestationFinalized` / `RedemptionAttestationFinalized`
events against the aggregator-side validator roster, and disbursing
from the swept treasury. The bridge does not run pro-rata distribution
on-chain.

Each program is independently upgradeable by the admin multisig, subject to
the protocol-config timelock.

## Burn lifecycle: escrow, then claim, then burn

Burning wPRL is a three-instruction state machine rather than a single
"burn now, redeem later" call:

1. **`request_withdrawal`** — the user's wPRL transfers into a
   program-owned **pending withdrawal vault** (a shared ATA). It is *not*
   burned yet. The Token-2022 transfer fee is waived for this internal
   escrow move (harvested back to the vault in the same transaction).
2. **`claim_cold_reserve_utxo`** — after the validator quorum agrees on
   which Cold Reserve UTXO will fund the redemption, an aggregator submits
   a validator-attested binding. A per-outpoint PDA (`ColdReserveUtxoClaim`)
   is opened, which atomically enforces that no two open requests can
   claim the same UTXO.
3. **`complete_redemption`** — after Pearl has confirmed the redemption
   transaction and validators have attested to it, the escrowed wPRL is
   burned from the vault (signed by the vault-owner PDA), the request and
   claim PDAs are closed, and fees are deposited.

If a request expires unfulfilled, `cancel_expired_withdrawal` transfers the
escrowed wPRL back to the user from the vault and closes any open claim
PDA. No re-mint is required — and so `nacre_two_way_peg` does **not** hold
unconditional mint authority for the cancel path. The mint authority is
only exercised by `mint_deposit`.

Two invariants drop out of this design:

* **`wPRL_supply ≤ PRL_backing`** — tokens are burned only after Pearl has
  confirmed the corresponding PRL has already left the Cold Reserve. The
  bound is an inequality because escrowed wPRL (for in-flight withdrawals)
  sits between the user's burn intent and the Pearl payout: those tokens
  are out of user hands but still part of the on-chain supply until the
  redemption confirms.
* **A Cold Reserve UTXO can be bound to at most one open withdrawal at a
  time** — enforced atomically by PDA uniqueness.