🏆 Built for XRPL Bizthon Hackathon
A quantum-resistant payment system for the XRP Ledger using SHA-256 preimage escrows
- Overview
- The Quantum Problem
- Our Solution
- Quick Start
- Demo Usage
- Detailed Project Architecture
- Security Analysis
- Testing
- API Reference
- Best Practices
- Contributing
The XRPL Quantum Protection Layer is a revolutionary payment system that provides quantum-resistant security for XRP Ledger transactions. Built for the XRPL Bizthon Hackathon, this project demonstrates how to protect digital assets against future quantum computing threats using existing XRPL infrastructure.
- 🔒 Quantum-Resistant Security: Uses SHA-256 preimage resistance (~2^128 quantum operations)
- ⚡ Zero Protocol Changes: Works with current XRPL infrastructure
- 📊 Interactive Demo: Complete wallet-to-wallet quantum-proof transfer showcase
Traditional blockchain payments rely on Elliptic Curve Cryptography (ECC) for digital signatures:
Traditional XRPL Payment:
[Sender] --ECC Signature--> [XRPL] --> [Immediate Transfer]
↑
Vulnerable to Shor's Algorithm
(~2^3 operations with quantum computer)
Threat Timeline:
- Now: ECC provides ~256-bit classical security
- 2030-2035: Large-scale quantum computers expected
- Impact: All ECC-based systems become vulnerable overnight
- $30B+ market cap at risk
- Millions of wallets using ECC keys
- Critical infrastructure for payments and DeFi
- No migration path without breaking changes
Quantum-Protected XRPL Payment:
[Sender] --ECC sig--> [XRPL] --SHA-256 check--> [Escrow Release]
↑ ↑
Submits transaction Quantum-Resistant
(compromisable) (Grover: 2^128 ops)
We leverage XRPL's native escrow functionality with PREIMAGE-SHA-256 conditions to create a quantum-resistant enforcement layer:
- Payment Creation: Funds locked in escrow with SHA-256 condition
- Payment Authorization: Secret preimage required for release
- Quantum Security: Breaking requires SHA-256 preimage collision (~2^128 operations)
- Node.js 18+ with npm/yarn
- Git for cloning
- Internet connection for XRPL testnet access
# Clone the repository
git clone https://github.com/your-username/xrp-quantum.git
cd xrp-quantum
# Install dependencies
npm install
# Run comprehensive tests
npm test
# Start interactive demo
npm run demo# Verify installation
npm run build # Should compile without errors
npm test # Should show 19/19 tests passingExperience quantum-resistant payments in action:
npm run demo- 🌐 Connection: Connects to XRPL Testnet
- 👛 Wallet Generation: Creates fresh sender/receiver wallets
- 💰 Auto-Funding: Automatically funds wallets via testnet faucet
- 🔐 Paycode Generation: Creates 256-bit quantum-safe paycode
- 🔒 Escrow Creation: Locks funds with SHA-256 condition
- 🔍 Verification: Confirms escrow on XRPL ledger
- 🔓 Payment Claim: Releases funds using preimage proof
- ✅ Success Confirmation: Verifies quantum-resistant transfer
🔒 XRPL Quantum Protection Demo
=================================
📡 Connecting to XRPL Testnet...
✅ Connected successfully
👛 Generating test wallets...
Sender Address: rPvPvw7v56tUfBc4Ru1PGz4Twz1onLGYro
Receiver Address: rEEfUsGR6XGPeMkLPu2w7CzoN9zwn1Q5qs
💰 Funding wallets automatically...
✅ Successfully funded wallets
🔐 Generating quantum-safe paycode...
Paycode ID: qp_1758881767118_ace81f48
Preimage: 728f3acac7b6ece69e26019b10d106a95f37b0dcdb70ddbbd178d9806f21b17a
SHA-256 Hash: d4cfb8d6b084c1d4fb76843b93b7c73ba2e5e4a0e0f1de55ed69ac0b1c6b3696
Condition: A0258020D4CFB8D6B084C1D4FB76843B93B7C73BA2E5E4A0E0F1DE55ED69AC0B1C6B3696810120
💡 Security Analysis:
SHA-256 preimage resistance: ~2^128 operations against quantum adversary
🔒 Creating quantum-protected escrow (1 XRP)...
✅ Escrow created successfully!
Transaction Hash: 058068C6F4BD3D723E25C7D2AEB81ECA7C3E35490C454C169C9AFE6FBFCD85D9
🔍 Verifying escrow on ledger...
✅ Escrow confirmed on XRPL ledger
🔓 Claiming payment with preimage...
🎉 Payment completed successfully!
✅ Funds transferred using quantum-resistant proof
┌─────────────────────────────────────────────────────────────────┐
│ XRPL Quantum Protection Layer │
└─────────────────────────────────────────────────────────────────┘
│
┌───────────────┴───────────────┐
│ │
┌───────▼───────┐ ┌──────▼──────┐
│ QuantumCrypto │ │ QuantumEscrow│
│ (crypto.ts) │ │ (escrow.ts) │
└───────┬───────┘ └──────┬──────┘
│ │
┌───────────▼────────────┐ ┌──────────▼──────────┐
│ • Generate preimages │ │ • XRPL client mgmt │
│ • Create conditions │ │ • Escrow operations │
│ • Validate fulfillments│ │ • Balance queries │
│ • Prevent reuse │ │ • Auto wallet funding│
└────────────────────────┘ └─────────────────────┘
│
┌──────────▼──────────┐
│ XRPL Testnet │
│ Native Escrows │
└─────────────────────┘
Purpose: Cryptographic operations for quantum-resistant paycodes
Key Methods:
class QuantumCrypto {
// Generate 256-bit quantum-safe paycode
static generatePaycode(): Paycode
// Validate preimage-hash pairs
static validatePreimage(preimage: string, hash: string): boolean
// Create XRPL-compatible condition
static createCondition(preimage: string): string
// Create fulfillment for escrow finish
static createFulfillment(preimage: string): string
// Track used preimages (prevent double-spend)
static markAsUsed(preimage: string): void
}Security Implementation:
- Entropy Source: Node.js
crypto.randomBytes(32)(256-bit) - Hash Function: SHA-256 via Node.js native crypto
- Condition Format: PREIMAGE-SHA-256 crypto-condition (RFC standard)
- Reuse Prevention: In-memory tracking with persistent storage hooks
Purpose: XRPL escrow management and quantum payment orchestration
Key Methods:
class QuantumEscrow {
// Create quantum-protected payment
async createQuantumPayment(
senderWallet: Wallet,
destinationAddress: string,
amount: number,
paycode: Paycode
): Promise<QuantumPayment>
// Claim payment with preimage
async finishQuantumPayment(
receiverWallet: Wallet,
escrowSequence: number,
escrowOwner: string,
paycode: Paycode
): Promise<string>
// Auto-fund testnet wallets
async fundWallet(address: string): Promise<boolean>
}XRPL Integration:
- Client Management: WebSocket connection to testnet
- Transaction Building: Uses official
xrpllibrary - Error Handling: Comprehensive validation and retry logic
- Balance Monitoring: Real-time account balance queries
Purpose: Type safety and data structure definitions
interface Paycode {
id: string; // Unique identifier
preimage: string; // 256-bit secret (hex)
condition: string; // SHA-256 hash (hex)
hash: string; // Raw SHA-256 for validation
createdAt: Date; // Timestamp
used: boolean; // Reuse prevention flag
}
interface EscrowData {
escrowId: string; // Owner:Sequence format
owner: string; // Sender XRPL address
destination: string; // Receiver XRPL address
amount: string; // XRP amount
condition: string; // PREIMAGE-SHA-256 condition
createdAt: Date; // Creation timestamp
status: 'created' | 'finished' | 'expired';
}1. Preimage Generation (256-bit random):
x = randomBytes(32) // 256-bit entropy
2. Condition Creation:
condition = PREIMAGE-SHA-256(x)
hash = SHA-256(x)
3. Escrow Creation (XRPL):
EscrowCreate {
Condition: condition,
Amount: amount,
Destination: receiver
}
4. Payment Authorization:
EscrowFinish {
Fulfillment: x,
Condition: condition
}
5. XRPL Verification:
if SHA-256(x) == condition:
release_funds()
Theorem: Funds cannot be stolen without knowledge of preimage x.
Proof:
- Escrow Enforcement: XRPL validates
SHA-256(fulfillment) == condition - Preimage Security: Finding
xsuch thatSHA-256(x) == hashrequires:- Classical: ~2^256 operations (brute force)
- Quantum: ~2^128 operations (Grover's algorithm)
- ECC Independence: Signature compromise cannot bypass condition check
Attack Resistance:
- ✅ Quantum ECC Break: Attacker can forge signatures but cannot produce fulfillment
- ✅ Network Interception: Only hash is transmitted, preimage remains secret
- ✅ Blockchain Analysis: Public ledger contains only hash, not preimage
- ✅ Brute Force: 2^128 operations required even with quantum computers
Adversary Capabilities:
- 🔴 Quantum Computer: Can break ECC signatures using Shor's algorithm
- 🔴 Network Access: Can intercept all communications
- 🔴 Blockchain Access: Can analyze all public ledger data
- 🔴 Computational Power: Unlimited classical and quantum resources
- ⭕ Preimage Knowledge: Cannot know secret preimages without transmission
| Attack Vector | Traditional XRPL | Quantum Protection Layer |
|---|---|---|
| Private Key Compromise | 🔴 Complete Loss | 🟢 Protected (needs preimage) |
| Quantum ECC Break | 🔴 System-wide failure | 🟢 Resistant (SHA-256 based) |
| Man-in-the-Middle | 🟡 Partial risk | 🟢 Secure (hash transmission only) |
| Replay Attacks | 🟡 Sequence protection | 🟢 Immune (one-time preimages) |
| Brute Force | 🔴 2^3 quantum ops | 🟢 2^128 quantum ops |
Security Reduction: The security of the quantum protection layer reduces to the preimage resistance of SHA-256.
Quantum Security Level: 128-bit (equivalent to AES-256 classical security)
Expected Lifetime: Secure against quantum attacks for decades (SHA-256 is quantum-resistant)
# Install dependencies
npm install
# Start development server
npm run dev
# Run tests in watch mode
npm run test:watch# TypeScript compilation
npm run build
# Output: dist/ directory with compiled JavaScript# Linting (if configured)
npm run lint
# Type checking
npx tsc --noEmit
# Test coverage
npm run test:coverage# Development (.env.development)
XRPL_SERVER=wss://s.altnet.rippletest.net:51233
LOG_LEVEL=debug
# Production (.env.production)
XRPL_SERVER=wss://xrplcluster.com
LOG_LEVEL=infoThis project was developed for the XRPL Bizthon Hackathon, demonstrating innovative use of XRPL's native capabilities to solve the quantum computing threat to blockchain security.
- ✅ Innovation: Novel application of existing XRPL features for quantum resistance
- ✅ Practical Impact: Addresses real future threat to $30B+ XRPL ecosystem
- ✅ Demonstrability: Working demo with automatic wallet funding
The quantum computing threat is not theoretical, it's an approaching reality that will affect all blockchain systems using ECC signatures. This project provides:
- Immediate Solution: Works with current XRPL infrastructure
- Future-Proof Security: Protects against quantum attacks
- Developer-Friendly: Easy integration with existing XRPL applications
- Scalable Architecture: Can be extended for enterprise use cases
MIT License - see LICENSE file for details.
We welcome contributions to enhance the quantum protection capabilities!
- Fork the repository
- Create a feature branch (
git checkout -b feature/quantum-enhancement) - Implement your changes with tests
- Ensure all tests pass (
npm test) - Submit a pull request
- 🔐 Enhanced Security: Additional cryptographic primitives
- 📱 Mobile Support: React Native integration
- 🏢 Enterprise Features: Multi-signature quantum protection
- 🔍 Monitoring Tools: Advanced escrow analytics
- 📚 Documentation: Tutorials and guides
For security-related contributions:
- Private Disclosure: Email security issues privately first
- Responsible Timeline: Allow time for patches before public disclosure
- Testing: Include comprehensive security tests
Built with ❤️ for the XRPL Community
Securing the future of blockchain payments against quantum threats