| 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. |
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: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).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.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.
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.