Card Charges Escrow

The CardChargesEscrow is a passive receiver of confidential tokens that settles accumulated balances to card networks through the RaycashWrapper's two-phase unwrap flow.

Key Design: Passive Reception

The escrow never initiates charges. It has no function to pull tokens from users. Instead, the backend uses FHE Permit authorization to transfer confidential tokens from users into the escrow via the wrapper's standard transfer() function.

Settlement Flow

Settlements use the wrapper's two-phase unwrap. The escrow uses the cleartext initUnwrap(uint64, address) overload since it cannot generate FHE encrypted inputs.

Functions

settle(destination, amount)

Admin-only. Initiates a settlement to the given destination address.

1. Increments the settlement nonce
2. Compresses the amount via rate()
3. Calls wrapper.initUnwrap(compressed, destination)
4. Stores the pending handle for later finalization

finalizeSettlement(amount, decryptionProof)

Callable by admin or the pending destination. Completes the settlement by forwarding the decryption proof to the wrapper.

setAdmin(newAdmin)

Admin-only. Transfers admin authority to a new address.

Key Properties

• Sequential settlements — At most one pending settlement at a time. settle() reverts if a settlement is already in flight.
• No underlying custody — The escrow never holds cleartext ERC-20 tokens. The wrapper sends underlying directly to the destination.
• Dual finalization — Both the admin and the destination can finalize. The receiving party can trigger finalization independently.
• Monotonic nonce — Each settlement gets a unique, incrementing nonce for tracking.
• Admin mutability — The admin role can be transferred. The new admin immediately has full settlement authority.

Hook Interaction

The escrow is a regular address in the wrapper's ERC-7984 ledger:

• Transfer hook (KYC) — If configured, the escrow address must have a valid KYC attestation to receive confidential transfers. The backend must attest the escrow address.
• Unwrap hook — Called via try/catch during settlement. Cannot block the unwrap.
• Once tokens are in the escrow, they can always be settled regardless of subsequent KYC changes, because initUnwrap burns tokens (which skips the transfer hook).