Splendor Shield: Technical Documentation

System Architecture

Core Components

1. Smart Contract (EnhancedAnonymousMixer.sol)

The contract implements a commitment-based privacy system with the following key features:

// Fixed denominations for anonymity sets
uint256[] public depositDenominations = [
    1 ether,
    10 ether,
    100 ether,
    1000 ether,
    10000 ether
];
 
// Commitment structure
struct Deposit {
    uint256 amount;
    bytes32 commitment;
    uint256 timestamp;
    bool withdrawn;
    uint256 denominationIndex;
}

2. Relayer Service (relayer.js)

The relayer service handles:

• Transaction processing
• Signature verification
• Gas estimation
• Event monitoring

// Key relayer features
const RELAYER_FEE_PERCENT = 0.5; // 0.5%
const RECIPIENT_MUST_WITHDRAW = process.env.RECIPIENT_MUST_WITHDRAW === '1';

Technical Implementation

1. Commitment System

function calculateCommitment(
    address _recipient,
    bytes32 _nullifier
) public pure returns (bytes32) {
    return keccak256(abi.encodePacked(
        MIXER_DOMAIN, 
        _recipient, 
        _nullifier
    ));
}

2. Withdrawal Verification

const messageHash = ethers.solidityPackedKeccak256(
    ['address', 'bytes32', 'bytes32', 'address'],
    [recipient, nullifier, commitment, MIXER_ADDRESS]
);
const recoveredAddress = ethers.verifyMessage(
    ethers.getBytes(messageHash), 
    signature
);

Security Features

1. Commitment Verification:

   • Unique commitment check
   • Nullifier verification
   • Recipient signature validation

2. Transaction Safety:

   • Gas estimation with 20% margin
   • Balance checks
   • Withdrawal time delays

3. Access Control:

   • Recipient-only withdrawals
   • Signature verification
   • Amount validation

System Flow

1. Deposit Process:

   User -> Generate Commitment -> Send Deposit -> Store on Chain

2. Withdrawal Process:

   Recipient -> Sign Request -> Relayer -> Verify -> Transfer

API Endpoints

1. Commitment Verification:

   GET /api/commitment/:commitment

2. Withdrawal Request:

   POST /api/withdraw

3. Relayer Information:

   GET /api/info

Configuration

// Environment Variables
BLOCKCHAIN_URL=https://testchain.splendor.org
RELAYER_PRIVATE_KEY=your_private_key
RELAYER_URL=http://localhost:3009
PORT=3009
MIXER_ADDRESS=
SKIP_WAITING=1
RECIPIENT_MUST_WITHDRAW=1

Technical Limitations

1. Privacy Level:

   • Commitment scheme
   • Fixed denomination amounts

2. Security Considerations:

   • Relayer dependency
   • Gas price fluctuations
   • Network congestion

3. Performance Constraints:

   • Single relayer architecture
   • Synchronous processing
   • Limited scalability

Future Improvements

1. Enhanced Privacy:

   • Implement zk-SNARKs
   • Variable denomination support
   • Improved anonymity sets

2. Scalability:

   • Multiple relayer support
   • Batch processing
   • Cross-chain compatibility

3. Security:

   • Advanced signature schemes
   • Rate limiting
   • Enhanced monitoring