Token Shielding and Unshielding

Token shielding (deposit) and unshielding (withdrawal) are the entry and exit points between public and private states:

Shielding Process (Public → Private):

┌──────────────────┐
│  User's Public   │
│  Wallet Balance  │
│  (Transparent)   │
└────────┬─────────┘
         ↓
    Approve Token
         ↓
┌────────▼─────────┐
│  Generate        │
│  Commitment &    │
│  Proof (Client)  │
└────────┬─────────┘
         ↓
┌────────▼─────────┐
│  Call            │
│  deposit()       │
│  Function        │
└────────┬─────────┘
         ↓
┌────────▼─────────┐
│  Smart Contract: │
│  • Verify Proof  │
│  • Transfer Token│
│  • Store Commit. │
└────────┬─────────┘
         ↓
┌────────▼─────────┐
│  Private Pool    │
│  (Shielded)      │
│  🔒              │
└──────────────────┘

Shielding Details:

1. User selects amount and token to shield

2. Client generates random secret and commitment

3. Client creates ZK proof showing: “I know the opening of this commitment”

4. User approves token spending (ERC-20 only, not needed for BNB)

5. User submits transaction with commitment and proof

6. Contract verifies proof and transfers tokens from user to pool

7. Contract stores commitment in user’s stealth address commitment set

8. User stores commitment details locally (encrypted)

Unshielding Process (Private → Public):

┌──────────────────┐
│  Private Pool    │
│  (Shielded)      │
│  🔒              │
└────────┬─────────┘
         ↓
┌────────▼─────────┐
│  Select UTXOs    │
│  to Spend        │
│  (Client)        │
└────────┬─────────┘
         ↓
┌────────▼─────────┐
│  Generate        │
│  Nullifiers &    │
│  Proof (Client)  │
└────────┬─────────┘
         ↓
┌────────▼─────────┐
│  Call            │
│  withdraw()      │
│  Function        │
└────────┬─────────┘
         ↓
┌────────▼─────────┐
│  Smart Contract: │
│  • Verify Proof  │
│  • Check Nullif. │
│  • Transfer Token│
└────────┬─────────┘
         ↓
┌────────▼─────────┐
│  Recipient's     │
│  Public Wallet   │
│  (Transparent)   │
└──────────────────┘

Unshielding Details:

1. User selects amount and destination address for withdrawal

2. Client selects sufficient commitments (UTXOs) to cover amount

3. Client generates nullifiers for selected commitments

4. If withdrawal amount < total UTXOs, create change commitment

5. Client creates ZK proof showing: “I know the secrets for these commitments, and their sum ≥ withdrawal amount”

6. User submits transaction with nullifiers, destination, and proof

7. Contract verifies proof and checks nullifiers not previously used

8. Contract marks nullifiers as spent

9. Contract transfers tokens from pool to destination address

10. If there’s change, create new commitment for remaining balance

Pool Management:

• Pool holds all shielded tokens in custody

• Maintains separate balances for each token type

• Uses ReentrancyGuard to prevent attacks

• Emits events for transparency (amounts hidden in commitments)

• Supports emergency pause mechanism