Panini America

We express our gratitude to the Panini America team for the collaborative engagement that enabled the execution of this Smart Contract Security Assessment.

Panini is an on-chain collectibles platform that allows authorised operators to mint NFTs, and users to lock NFTs for bridging, and unlock escrowed tokens via signature-verified requests while enforcing marketplace-whitelisted trades. It also manages royalty funds through a dedicated custody vault that supports controlled withdrawals and Uniswap-based token swaps.

The system users should acknowledge all the risks summed up in the risks section of the report

{Finding_Table?columns=title,severity,status&setting.filter.type=Vulnerability}

Documentation quality

• Functional requirements are clearly outlined within the documentation and NatSpec comments across all contracts.

• Technical descriptions and intended behaviour are included for core functionalities.

• Inline comments are consistently used throughout the codebase, improving readability and developer understanding.

Code quality

• Contract inheritance and modularity are well-structured, allowing separation between NFT logic, access control, validation, and royalty vault functionalities.

• The implementation uses sufficient input validation, role-based access modifiers, and event logging for traceability.

• Several template code patterns from OpenZeppelin (Ownable, AccessControl, Pausable, ReentrancyGuard) are implemented.

Test coverage

Code coverage of the project is 39.4% (branch coverage).

• Negative cases are partially covered.

• A comprehensive set of tests validates deployment, minting, role-based access, pausing, burning, approvals, and signature-based operations.

• The tests execute correctly after uncommenting specific sections as instructed by the development team.

The Panini Protocol is an on-chain collectibles and royalty management system designed to enable secure minting, transfer, locking, and unlocking of NFTs through cryptographic validation and managed fund custody. It allows authorized operators to mint NFTs, and users to bridge them across networks by locking or unlocking assets via signatures, enforce marketplace whitelisting for compliant trading, and manage royalty proceeds using a secure, role-based vault.

PaniniNFTs — an upgradeable ERC-721 collection with royalties and strict, role-based controls. It supports operator-gated minting (single or batch), optional burning with burned token ID reuse protection, and signature-based mint/unlock flows that use nonces and expirations for replay resistance. The lock flow escrows tokens to the contract for bridging, while transfers and approvals are filtered through the Panini lock and marketplace whitelisting (SmartValidator) as well as the external transfer-policy hook (CreatorTokenValidator). Managers can also pause/unpause operations and update token URIs when necessary.

SmartValidator — is an access-controlled validation module enforcing marketplace whitelisting and Panini lock logic, ensuring that only approved operators or marketplaces can execute transfers and approvals when the lock is active.

CreatorTokenValidator — is an abstract module for enforcing customizable transfer validation policies, allowing integration with external transfer validators and ensuring compatibility with the LimitBreak creator token standard.

PaniniRoyaltyVault — is a secure upgradeable vault contract that manages both ETH and ERC20 funds, allowing authorized roles to withdraw or swap tokens through Uniswap, while maintaining pausing, access control, and non-reentrancy safeguards.

Privileged roles

Privileged roles of the PaniniNFTs contract:

• The DEFAULT_ADMIN_ROLE role can grant and revoke all AccessControl roles used by the NFT system, including PANINI_NFT_MANAGER, PANINI_NFT_OPERATOR, and WHITELISTED_MARKETPLACE, thereby controlling the contract’s role-based access system.

• The PANINI_NFT_MANAGER role can pause and unpause transfers, force-update token metadata via updateTokenURI, and freeze or unfreeze specific user accounts for this NFT collection via the configured external transfer validator.

• The PANINI_NFT_OPERATOR role can mint and batch mint NFTs to users (subject to the global minting flag), and also acts as the signing authority for the signature-based bridging flows (batchMintOrUnlock and batchLockNFT), since signatures are accepted only if recovered signer holds PANINI_NFT_OPERATOR.

• The owner can configure royalties, toggle minting and burning permissions globally, and set or change the external transfer validator that enforces the collection’s transfer-policy rules (including account freeze/unfreeze behavior).

Privileged roles of the PaniniRoyaltyVault contract:

• The DEFAULT_ADMIN_ROLE role can grant and revoke all vault roles (including VAULT_MANAGER, VAULT_PAUSER, and WHITELISTED_RECEIVER) and can update the Uniswap router address via updateUniswapRouter() function.

• The VAULT_MANAGER role can withdraw ETH and ERC20 tokens to whitelisted receivers and can execute swaps (ETH to ERC20 and ERC20 to ERC20) through the configured Uniswap V3 router.

• The VAULT_PAUSER role can pause and unpause vault operations, restricting withdrawals and swaps during maintenance or security incidents.

• The owner can transfer or renounce ownership; additionally, the owner is granted DEFAULT_ADMIN_ROLE during initialization, so the owner is the initial authority for vault role administration unless this is later reconfigured.

Privileged roles of the SmartValidator contract:

• The WHITELISTED_MARKETPLACE role allows approved marketplace or operator addresses to perform approvals and initiate transfers while the Panini lock mechanism is active, bypassing the default restriction that otherwise permits only token owners to perform these actions.

• The DEFAULT_ADMIN_ROLE role can enable or disable the Panini lock mechanism globally via setPaniniLock() function, directly affecting whether approvals and transfers are gated by WHITELISTED_MARKETPLACE restrictions.

Privileged roles of the CreatorTokenValidator contract:

• The owner can set or change the transfer validator contract via setTransferValidator(address), thereby defining (or replacing) the collection’s external transfer-policy enforcement logic that is invoked on transfers and is also used to apply administrative actions such as freezing and unfreezing accounts for the collection.

The scope of the project includes the following smart contracts from the provided repository:

Assets in Scope