EthVaultPQ MetaMask Snap 🦊🔐

Post-quantum secure vesting vault management directly in MetaMask

🌟 Features

• Post-Quantum Signatures: Generate Dilithium3 (ML-DSA-65) signatures
• ZK-SNARK Proofs: Create Groth16 proofs for on-chain verification (~250K gas)
• Vesting Tracking: Monitor multiple vault schedules in real-time
• Transaction Insights: See vesting details before confirming transactions
• Secure Key Management: Keys derived from MetaMask seed phrase
• Native Integration: Works seamlessly with existing EthVaultPQ contracts

🚀 Quick Start

Installation

npm install @ethvaultpq/snap

Or install directly in MetaMask:

await window.ethereum.request({
  method: 'wallet_requestSnaps',
  params: {
    '@ethvaultpq/snap': {}
  }
});

Usage Example

// Create a PQ wallet
const result = await window.ethereum.request({
  method: 'wallet_invokeSnap',
  params: {
    snapId: '@ethvaultpq/snap',
    request: {
      method: 'pqwallet_createWallet'
    }
  }
});

console.log('Public Key:', result.publicKey);
console.log('Address:', result.address);

// Sign a transaction
const signedTx = await window.ethereum.request({
  method: 'wallet_invokeSnap',
  params: {
    snapId: '@ethvaultpq/snap',
    request: {
      method: 'pqwallet_signTransaction',
      params: {
        transaction: {
          to: '0x...',
          data: '0x...',
          value: '0',
          chainId: 1
        }
      }
    }
  }
});

// Add a vault to track
await window.ethereum.request({
  method: 'wallet_invokeSnap',
  params: {
    snapId: '@ethvaultpq/snap',
    request: {
      method: 'pqwallet_addVault',
      params: {
        vaultAddress: '0x...',
        tokenAddress: '0x...',
        tokenSymbol: 'TOKEN'
      }
    }
  }
});

// Get vesting schedule
const schedule = await window.ethereum.request({
  method: 'wallet_invokeSnap',
  params: {
    snapId: '@ethvaultpq/snap',
    request: {
      method: 'pqwallet_getVestingSchedule',
      params: {
        vaultAddress: '0x...'
      }
    }
  }
});

console.log('Vesting Progress:', schedule.vestingProgress);
console.log('Claimable:', schedule.claimableAmount);

📚 API Reference

Wallet Management

pqwallet_createWallet

Create a new post-quantum wallet with Dilithium3 keypair.

Parameters: None

Returns:

{
  publicKey: string;  // Hex-encoded Dilithium3 public key
  address: string;    // Wallet address
}

pqwallet_getPublicKey

Get the current wallet's public key.

Returns: string - Hex-encoded public key

pqwallet_getWalletAddress

Get the current wallet's address.

Returns: string - Wallet address

Transaction Signing

pqwallet_signTransaction

Sign a transaction with Dilithium3 and generate ZK-SNARK proof.

Parameters:

{
  transaction: {
    to: string;
    data: string;
    value?: string;
    chainId: number;
  }
}

Returns:

{
  signature: string;      // Dilithium3 signature (hex)
  zkProof: {             // Groth16 proof
    proof: object;
    publicSignals: string[];
  };
  messageHash: string;
}

pqwallet_signMessage

Sign an arbitrary message.

Parameters:

{
  message: string;
}

Returns: string - Dilithium3 signature (hex)

Vault Management

pqwallet_getVaults

Get all tracked vaults.

Returns:

Array<{
  address: string;
  tokenAddress: string;
  tokenSymbol: string;
  totalAmount: string;
  claimedAmount: string;
  startBlock: number;
  endBlock: number;
  cliffBlock: number;
  beneficiary: string;
}>

pqwallet_getVestingSchedule

Get vesting schedule for a specific vault.

Parameters:

{
  vaultAddress: string;
  currentBlock?: number;  // Optional, defaults to latest
}

Returns:

{
  totalAmount: bigint;
  startBlock: number;
  endBlock: number;
  cliffBlock: number;
  vestedAmount: bigint;
  claimableAmount: bigint;
  claimedAmount: bigint;
  vestingProgress: number;  // 0-100%
}

pqwallet_addVault

Add a vault to track.

Parameters:

{
  vaultAddress: string;
  tokenAddress: string;
  tokenSymbol?: string;
}

pqwallet_removeVault

Remove a tracked vault.

Parameters:

{
  vaultAddress: string;
}

Utility

pqwallet_getSnapState

Get current Snap state (for debugging).

Returns: Snap state object (secret key redacted)

pqwallet_resetSnap

Reset Snap and clear all data.

Returns: { success: boolean }

🔐 Security

Post-Quantum Cryptography

• Algorithm: Dilithium3 (ML-DSA-65)
• NIST Standard: FIPS 204
• Security Level: NIST Level 3 (192-bit quantum security)
• Library: @noble/post-quantum

Key Derivation

Keys are derived from your MetaMask seed phrase using BIP-44:

m/44'/60'/0'/0/0 → Entropy → Dilithium3 Keypair

Benefits:

• Backup = MetaMask seed phrase (no extra keys to store)
• Deterministic generation (same keys from same seed)
• Encrypted storage within MetaMask

ZK-SNARK Proofs

• Scheme: Groth16
• Curve: BN254 (BN128)
• On-chain Cost: ~250K gas
• Off-chain Time: ~1-2 seconds
• Library: snarkjs

🏗️ Architecture

┌─────────────────────────────────────────┐
│         MetaMask Snap                   │
├─────────────────────────────────────────┤
│                                          │
│  📦 Key Management                       │
│    └─ BIP-44 → Dilithium3 Keypair      │
│                                          │
│  🔐 Signature Operations                 │
│    ├─ Sign with Dilithium3             │
│    └─ Generate ZK-SNARK proof          │
│                                          │
│  📊 Vault Tracking                       │
│    ├─ Monitor vesting schedules        │
│    ├─ Calculate claimable amounts      │
│    └─ Track multiple vaults            │
│                                          │
│  🔍 Transaction Insights                 │
│    ├─ Decode vault operations          │
│    ├─ Show vesting details             │
│    └─ Warn on unsafe withdrawals       │
│                                          │
└─────────────────────────────────────────┘
          ↓ RPC Methods
┌─────────────────────────────────────────┐
│         Your DApp                        │
└─────────────────────────────────────────┘

🧪 Development

Setup

# Clone repository
git clone https://github.com/ethvaultpq/ethvaultpq-snap
cd metamask-snap

# Install dependencies
npm install

# Build the Snap
npm run build

# Serve locally for testing
npm run serve

Testing

# Run tests
npm test

# Run with coverage
npm run test:coverage

# Lint
npm run lint

Local Testing in MetaMask

1. Build the Snap: npm run build
2. Serve locally: npm run serve
3. Open MetaMask Flask (developer version)
4. Connect to http://localhost:8080

📦 Project Structure

metamask-snap/
├── src/
│   ├── index.ts              # Main entry point
│   ├── crypto/
│   │   ├── keyManagement.ts  # PQ key generation & storage
│   │   └── signing.ts        # Dilithium3 & ZK proof generation
│   ├── rpc/
│   │   └── handlers.ts       # RPC method implementations
│   ├── ui/
│   │   └── transactionInsight.ts  # Transaction insight UI
│   ├── utils/
│   │   └── vaultUtils.ts     # Vault interaction helpers
│   └── types/
│       └── index.ts          # TypeScript definitions
├── snap.manifest.json        # Snap configuration
├── package.json
└── tsconfig.json

🚧 Roadmap

Phase 1: Core Functionality ✅

• [x] Dilithium3 key generation
• [x] Transaction signing
• [x] ZK proof structure (mock)
• [x] Vault tracking
• [x] Transaction insights

Phase 2: ZK Integration 🔄

• [ ] Compile Dilithium verification circuit
• [ ] Host circuit files (IPFS/CDN)
• [ ] Integrate real ZK proof generation
• [ ] Test on-chain verification

Phase 3: Enhanced Features 📋

• [ ] Multi-signature support
• [ ] Batch operations
• [ ] Token price integration
• [ ] Mobile optimization
• [ ] Gasless transactions (meta-transactions)

Phase 4: Production 🎯

• [ ] Security audit
• [ ] NPM publication
• [ ] MetaMask Snaps directory listing
• [ ] Comprehensive documentation
• [ ] Video tutorials

🤝 Contributing

Contributions welcome! Please read CONTRIBUTING.md first.

📄 License

MIT License - see LICENSE file for details.

🔗 Links

• EthVaultPQ Dashboard: https://ethvault.qkey.co
• ZK API: https://api.ethvault.qkey.co
• Documentation: https://docs.ethvaultpq.com
• GitHub: https://github.com/ethvaultpq
• Discord: https://discord.gg/ethvaultpq

🙏 Acknowledgments

• MetaMask Snaps: For the extensibility framework
• @noble/post-quantum: For Dilithium3 implementation
• snarkjs: For ZK-SNARK proof generation
• NIST: For ML-DSA standardization

⚠️ Disclaimer

THIS IS EXPERIMENTAL SOFTWARE

• This Snap is in early development (v0.1.0)
• ZK proof generation is currently mocked
• Do NOT use with real funds on mainnet
• Testnet only until security audit is complete

Built with 💜 by the EthVaultPQ Team

Securing tomorrow's tokens with today's quantum-resistant cryptography