Shielded Transfers

Overview

Shielded transfers let entities move ETH and ERC-20 tokens privately on-chain. The system uses a UTXO-based note model with Poseidon commitments and Halo2-KZG zero-knowledge proofs on BN254.

Three operations are supported:

How It Works

Shield (Deposit)

1. Entity calls POST /api/privacy/shield with token, amount, and chain
2. The API derives the entity's key set, computes a Poseidon commitment, and encrypts the note data
3. A UserOp is submitted through the entity's smart wallet to ShieldedTransferFacet
4. The facet calls ConfidentialLedger.shield(), which inserts the commitment into the Merkle tree
5. The scanner detects the NoteCreated event, trial-decrypts it, and records the note in the database

Private Transfer

1. Entity calls POST /api/privacy/prove-transfer with recipient, token, and amount
2. The API selects input notes (coin selection), fetches Merkle paths from on-chain
3. A JoinSplit proof is generated via the native Halo2-KZG prover (2 inputs, 2 outputs)
4. The proof bundle is returned to the client, which submits it to POST /api/relay/transfer
5. The relay submits the transfer anonymously — the sender's wallet never appears on-chain
6. The ConfidentialLedger verifies the proof, records nullifiers, and inserts new commitments

Unshield (Withdrawal)

1. Entity calls POST /api/privacy/unshield with token, amount, and optional recipient
2. The API selects input notes, generates a proof with value_delta equal to the withdrawal amount
3. A UserOp is submitted to ShieldedTransferFacet.unshieldTokens()
4. The facet calls ConfidentialLedger.unshield(), which verifies the proof and sends tokens to the recipient

Token Support

Native ETH uses the address(0) sentinel in the ConfidentialLedger. The contract wraps/unwraps ETH automatically.

Gas Estimates

All operations are sponsored by the platform paymaster — entities do not need to hold ETH for gas.

Accounting Integration

Shielded transfers are automatically classified and posted through the posting engine: