On-Chain Shard Map v2 PROPOSAL v2

Complete audit results

Every file in the ShardKeep/Citadel codebase was audited for impact. The on-chain shard map architecture affects only the shard coordination layer — the vault program, wallet flows, and browser extension UI are untouched.

What does NOT change (confirmed by audit)

• Anchor vault program (4hfvirYMHxW4nZSuTreWRQQD45Hfc4LKmUyy3hFYcZVP) — zero modifications. The vault stores encrypted credentials; it has no knowledge of shards or shard locations.
• Vault PDA structure — ["vault", owner_pubkey] seed derivation unchanged. Entry fields (entry_id, site, username, encrypted_data, iv, timestamps) unchanged.
• Client-side encryption — AES-256-GCM encryption in popup.js unchanged. Key derivation from wallet signature unchanged.
• Wallet connect flow — Solana Wallet Standard integration unchanged. Signature-based auth unchanged.
• Heartbeat / XNode / version check — background.js node reporting unchanged.

How it works

Rotation happens only when the user opens the extension. Since password manager users open their extension daily (for auto-fill), this is a natural trigger.

Rotation schedule by tier:

What if the user doesn't open the extension?

• 7 days without rotation: Extension shows subtle badge "Rotation overdue"
• 14+ days: Push notification (if browser allows) — "Your shards haven't been rotated. Open ShardKeep to refresh."
• 30+ days: Shards remain valid and accessible — rotation is a security enhancement, not a requirement for access. Old shard locations still work.

The vision: zero-knowledge rotation

A new Solana program (separate from the vault program) that coordinates shard swaps between vault nodes without any single entity seeing the full shard map.

What the blind swap program looks like (Anchor/Rust):

// Program: shardkeep_rotation (NEW, separate from shardkeep_vault)
// Network: DevNet for testing

#[program]
pub mod shardkeep_rotation {
    use anchor_lang::prelude::*;

    /// Issue a batch of shard swap instructions.
    /// Only the cNFT owner (verified via wallet signature) can call this.
    pub fn rotate_shards(ctx: Context<RotateShards>, swaps: Vec<SwapInstruction>) -> Result<()> {
        // Verify caller owns the shard map cNFT (Bubblegum ownership check)
        // Emit individual SwapEvent for each instruction
        // Nodes listen for their own events via WebSocket subscription
        for swap in swaps {
            emit!(SwapEvent {
                source_node: swap.source_node,
                target_node: swap.target_node,
                shard_hash: swap.shard_hash,
                nonce: swap.nonce,
            });
        }
        Ok(())
    }
}

#[derive(AnchorSerialize, AnchorDeserialize)]
pub struct SwapInstruction {
    pub source_node: [u8; 32],  // Source node public key
    pub target_node: [u8; 32],  // Target node public key
    pub shard_hash: [u8; 32],   // Blob identifier
    pub nonce: u64,             // Replay protection
}

#[event]
pub struct SwapEvent {
    pub source_node: [u8; 32],
    pub target_node: [u8; 32],
    pub shard_hash: [u8; 32],
    pub nonce: u64,
}

What each party sees during blind rotation:

Node-side: listening for swap events

Migration strategy: shadow table approach

Keep the existing citadel_shards table operational during transition. Add cNFT references alongside, then phase out the node_id column once cNFT flow is validated.

-- Phase 1: Add cNFT columns to existing table
ALTER TABLE citadel_shards
    ADD COLUMN nft_mint VARCHAR(44) DEFAULT NULL AFTER hmac_key,
    ADD COLUMN nft_tree VARCHAR(44) DEFAULT NULL AFTER nft_mint,
    ADD COLUMN nft_leaf_index BIGINT DEFAULT NULL AFTER nft_tree,
    ADD COLUMN map_purged_at DATETIME DEFAULT NULL AFTER nft_leaf_index;

-- Phase 2: Shadow table for cNFT-first lookups
CREATE TABLE citadel_shard_maps (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    wallet_address VARCHAR(64) NOT NULL,
    entry_id VARCHAR(64) NOT NULL,
    nft_mint VARCHAR(44) NOT NULL,
    nft_tree VARCHAR(44) NOT NULL,
    leaf_index BIGINT NOT NULL,
    security_tier ENUM('shield','guardian','sentinel','fortress') NOT NULL,
    shard_count TINYINT NOT NULL,
    threshold TINYINT NOT NULL,
    encrypted_map VARBINARY(2048),  -- Encrypted shard map (backup, also on-chain)
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    rotated_at DATETIME DEFAULT NULL,
    burned_at DATETIME DEFAULT NULL,
    INDEX idx_wallet (wallet_address),
    INDEX idx_entry (entry_id),
    UNIQUE INDEX idx_mint (nft_mint)
) ENGINE=InnoDB;

-- Phase 3: After validation, drop node_id from citadel_shards
-- ALTER TABLE citadel_shards DROP COLUMN node_id;
-- (Only after Option A is fully operational and tested)

Three methods require modification

storeSecret() — lines 195-227

retrieveSecret() — lines 302-378

deleteEntry() — lines 384-392

Node.js packages (for shard map minting)

npm install @metaplex-foundation/mpl-bubblegum \
            @metaplex-foundation/mpl-token-metadata \
            @metaplex-foundation/umi \
            @metaplex-foundation/umi-bundle-defaults \
            @solana/spl-account-compression

Anchor (for Option D blind swap program)

# New program, separate workspace
anchor init shardkeep_rotation --solana-version 1.18
# Deploy to DevNet only during R&D phase

The existing shardkeep_vault Anchor workspace and program ID are completely untouched.

Two tracks, running simultaneously