ShieldedPoolLib

Title: ShieldedPoolLib

Author: David Dada <daveproxy80@gmail.com> (https://github.com/dadadave80)

Library implementing fixed-denomination shielded (private) ERC-20 transfers (Tornado-style): deposits insert Poseidon(nullifier, secret) commitments into a Poseidon LeanIMT; withdrawals prove membership in zero knowledge and burn a one-time nullifier hash to an arbitrary recipient.

Three-layer pattern: this library holds the logic + namespaced storage; the stateless ShieldedPool facet forwards to it. The on-chain mechanics are wrapped from the shared IncrementalMerkleTreeLib (Poseidon LeanIMT + recent-root ring) and NullifierRegistryLib; the withdraw circuit + verifier are consumer-supplied per pool. Withdrawals follow strict CEI: the nullifier is spent BEFORE any token transfer, so a reentrant token cannot replay a spend.

Functions

shieldedPoolStorage

function shieldedPoolStorage() internal pure returns (ShieldedPoolStorage storage $);

Returns

Name	Type	Description
$	`ShieldedPoolStorage`

__ShieldedPool_init

Initializes the ShieldedPool module.

Must be called inside a pre/postInitializer block. Registers IShieldedPool for ERC-165.

function __ShieldedPool_init() internal;

registerInterface

Registers support for the IShieldedPool interface via ERC-165.

function registerInterface() internal;

createPool

Creates a fixed-denomination shielded pool. Gated on the default admin role.

function createPool(address token, uint256 denomination, address verifier) internal returns (uint256 poolId);

Parameters

Name	Type	Description
token	`address`
denomination	`uint256`
verifier	`address`

Returns

Name	Type	Description
poolId	`uint256`

deposit

Deposits one denomination and inserts commitment.

Pulls denomination from msg.sender first, then inserts the leaf. Guarded against reentrancy (the diamond-wide guard also blocks cross-entry reentry into withdraw).

function deposit(uint256 poolId, uint256 commitment) internal;

Parameters

Name	Type	Description
poolId	`uint256`
commitment	`uint256`

withdraw

Withdraws denomination - fee to recipient and fee to relayer against a proof.

Strict CEI: verify → spend nullifier → transfer. The proof's 5 public signals are [root, nullifierHash, recipient, relayer, fee], binding the destination + fee.

function withdraw(
        uint256 poolId,
        IShieldedPool.WithdrawProof calldata proof,
        uint256 root,
        uint256 nullifierHash,
        address recipient,
        address relayer,
        uint256 fee
    ) internal;

Parameters

Name	Type	Description
poolId	`uint256`
proof	`IShieldedPool.WithdrawProof`
root	`uint256`
nullifierHash	`uint256`
recipient	`address`
relayer	`address`
fee	`uint256`

poolCount

function poolCount() internal view returns (uint256);

Returns

Name	Type	Description
<none>	`uint256`

getPool

function getPool(uint256 poolId)
        internal
        view
        returns (address token, uint256 denomination, address verifier, uint256 merkleRoot, uint256 numLeaves);

Parameters

Name	Type	Description
poolId	`uint256`

Returns

Name	Type	Description
token	`address`
denomination	`uint256`
verifier	`address`
merkleRoot	`uint256`
numLeaves	`uint256`

isSpent

function isSpent(uint256 poolId, uint256 nullifierHash) internal view returns (bool);

Parameters

Name	Type	Description
poolId	`uint256`
nullifierHash	`uint256`

Returns

Name	Type	Description
<none>	`bool`

isKnownRoot

function isKnownRoot(uint256 poolId, uint256 root) internal view returns (bool);

Parameters

Name	Type	Description
poolId	`uint256`
root	`uint256`

Returns

Name	Type	Description
<none>	`bool`

_safeTransferFrom

transferFrom tolerating non-standard (no-return) ERC-20s; reverts on explicit failure, and on empty return data from an address with no code (matches OpenZeppelin SafeERC20).

function _safeTransferFrom(address token, address from, address to, uint256 amount) private;

Parameters

Name	Type	Description
token	`address`
from	`address`
to	`address`
amount	`uint256`

_safeTransfer

transfer tolerating non-standard (no-return) ERC-20s; reverts on explicit failure, and on empty return data from an address with no code (matches OpenZeppelin SafeERC20).

function _safeTransfer(address token, address to, uint256 amount) private;

Parameters

Name	Type	Description
token	`address`
to	`address`
amount	`uint256`