Skip to main content

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.

Nacre is a two-chain protocol with a small, well-defined set of moving parts. This page describes the v1 architecture; for where it’s headed, see the Roadmap.

​
Trust model in one sentence

Every state transition that moves PRL or mints/burns wPRL requires a threshold signature from a quorum of independent validators, and every user deposit has a unilateral 7-day emergency exit.

​
System components

┌────────────────────────────────────┐         ┌──────────────────────────────────┐
│              PEARL L1              │         │              SOLANA              │
│                                    │         │                                  │
│  Hot Reserve (per-user)            │         │  Nacre programs:                 │
│   key-path: validator quorum       │◄────────┤    two_way_peg                   │
│   script-path: USER + 7d CSV       │         │    liquidity_management          │
│                                    │         │    layer_ca                      │
│  Cold Reserve (shared)             │         │    layer_fee_management          │
│   key-path: validator quorum       │◄────────┤    protocol_config               │
│   script-path: ADMIN + 7d CSV      │         │    validator_registry            │
└─────────────▲──────────────────────┘         │                                  │
              │                                 │  wPRL SPL mint                   │
              │                                 │  Admin multisig (3-of-5)         │
              │                                 └────────────▲─────────────────────┘
              │                                              │
              │              ┌───────────────────────────────┴──────────────┐
              │              │   Signature aggregator (2–3 redundant)       │
              │              │   • Collects validator signatures            │
              │              │   • Pre-flight checks                         │
              │              │   • Forwards to custody at threshold          │
              │              │   • Broadcasts signed tx                      │
              │              └▲────────▲────────────────────────▲────────────┘
              │               │        │                        │
              │   ┌───────────┴┐ ┌─────┴──────┐ ┌──────────────┴─┐ ┌────────────┐
              │   │ Validator 1│ │ Validator 2│ │  Validator 3   │ │ Validator 4│
              │   │  (oracle)  │ │  (oracle)  │ │   (oracle)     │ │  (oracle)  │
              │   └────────────┘ └────────────┘ └────────────────┘ └────────────┘
              │     each runs: Pearl full node + Solana RPC + P-256 signing key

​
Pearl side: Taproot leaves

Nacre uses BIP-341 Taproot on Pearl. Both reserves are Taproot outputs with a key-path controlled by the validator quorum and a single script-path leaf for emergency recovery.

​
Hot Reserve (per-user deposit address)

Hot Reserve = Taproot(
  internal_key = validator-quorum-signed key,
  script_tree  = [
    leaf 0: <1008> OP_CSV OP_DROP <user_xonly_pubkey> OP_CHECKSIG
  ]
)
  • Key-path sweeps user deposits into the Cold Reserve once validators reach quorum.
  • Script-path lets the user reclaim their deposit after 7 days (1,008 blocks) with no validator involvement.
Each user gets a distinct Hot Reserve, deterministically derived from their Solana public key. Anyone can re-derive the address client-side and verify it against the on-chain record before depositing.

​
Cold Reserve (shared vault)

Cold Reserve = Taproot(
  internal_key = validator-quorum-signed key,
  script_tree  = [
    leaf 0: <1008> OP_CSV OP_DROP <admin_3of5_musig2_pubkey> OP_CHECKSIG
  ]
)
  • Key-path pays out user redemptions and rotations under validator quorum authority. This is the normal-operations path.
  • Script-path is emergency only — admin (3-of-5 multisig, aggregated via MuSig2) can sweep the Cold Reserve after a 7-day timelock if the validator quorum is permanently lost. Off-chain monitors publicly log any use of this path.

​
Pearl deposit address derivation

A user’s Hot Reserve internal key is derived deterministically:
  1. The validator quorum’s Pearl key serves as the base internal key.
  2. A taproot tweak is computed from the user’s Solana public key plus a protocol-specific tag.
  3. The tweaked key becomes the Hot Reserve’s internal key.
The same Solana key always yields the same Hot Reserve address. Implementations of the derivation are cross-validated against shared test vectors so the SDK, validator, indexer, and reclaim CLI all agree byte-for-byte.

​
Solana side: Anchor programs

Six Anchor programs split the on-chain logic by responsibility:
ProgramResponsibility
nacre_two_way_pegMint/burn state machine. Owns deposit attestations, withdrawal requests, fee math.
nacre_liquidity_managementwPRL vault. Holds the SPL mint authority. Store / Retrieve only via CPI.
nacre_layer_ca”Cold-account” registry. Maps Pearl reserve addresses to on-chain config.
nacre_layer_fee_managementValidator margin pool + protocol treasury.
nacre_protocol_configTunable parameters (fee bps, validator margin, pause flag, admin pubkeys).
nacre_validator_registrySource of truth for which P-256 keys count toward the quorum.
Each program is independently upgradeable by the admin multisig, subject to a 14-day timelock for two_way_peg and liquidity_management.

​
Validators are independent oracles

The quorum is not a consensus group. Validators do not gossip, vote, or exchange messages. Each validator:
  1. Runs its own Pearl full node and Solana RPC client.
  2. Independently observes on-chain events on both chains.
  3. Deterministically constructs proposals from finalized state.
  4. Signs the proposal hash with its P-256 key.
  5. POSTs the signature to every signature aggregator instance.
Because every validator builds proposals from the same finalized state using the same canonical encoding, two honest validators produce byte-identical proposals and therefore the same proposal_id = sha256(canonical_borsh(proposal)). Equivocation is observable. Determinism is enforced by cross-implementation test vectors and fuzz harnesses.

​
The signature aggregator

The aggregator is a stateless coordination service. It does not have any signing authority — it cannot mint, burn, or move PRL on its own. Its job:
  • Collect P-256 signatures keyed by proposal_id.
  • Reject invalid signatures or signatures from unknown validators.
  • Run pre-flight checks (multi-RPC consistency, rate limits, output-address whitelist, circuit breaker) before forwarding.
  • At the 3-of-4 threshold, forward to custody (Privy in v1) with the three validator signatures as authorization.
  • Broadcast the signed transaction.
Two to three aggregator instances run in parallel. Validators POST to all of them; whichever reaches threshold first broadcasts.

​
Authority hierarchy

AuthorityRoleSurface
Validator quorum (3-of-4)Authorizes all normal mint, burn, and sweep operationsPearl key-path + Solana mint/burn attestations
Admin multisig (3-of-5)Cold Reserve emergency recovery; program upgrades; parameter changes; fee distributionPearl script-path leaf 0; Solana admin instructions
Signature aggregatorPre-flight checks; cannot authorize anythingHTTP service, subtractive only
Off-chain monitorDetects anomalies and alerts; cannot authorize anythingPages on-call humans
Validators have no admin powers. Admin has no validator powers. The two authorities are cryptographically disjoint.