PolyCards Docs Internal system review

Internal technical review and trust assumptions report

PolyCards three-contract system review

This document reviews the PolyCards NFT, Game/Royal, and Marketplace contracts as a combined system. It is written for technical triage by human reviewers, AI agents, and potential diligence workflows.

Not a third-party audit Polygon chain 137 Scope: NFT + Game + Marketplace Date: 2026-10-09
Important limitation: This is an internal review. It was not produced by an independent external auditor and does not guarantee security, solvency, legality, profitability, liquidity, or user demand. External scans and source-code verification should be treated as evidence inputs, not final approval.

Scope

The review covers the two deployed collection sets listed in the public contract registry. Each set has the same functional shape: one ERC-721 card contract, one Game/Royal contract, and one Marketplace contract.

Collection Contract Address Primary role
Premium NFT 0x4cEC06310C2948d2E92d02CF9E9A9B09A37D3846 ERC-721 card ownership, card metadata, pause state, game-authorized minting.
Premium Game/Royal 0x440Fe259685C70780EdAE1b0555f5457b25B27C9 Minting flow, invitation code mapping, card assignment, referral rewards, Royal Flush progress, claims.
Premium Marketplace 0xEB072E1f7A99E7Dd07a785018EB1da1405b4254a Listing creation, listing cancellation, purchase settlement, marketplace fee configuration.
VIP NFT 0xf6F8aE08ec0e60a70B950EcA11ca3DC12c77a64B ERC-721 card ownership, card metadata, pause state, game-authorized minting.
VIP Game/Royal 0x2cDcAE2192832a60c6eb4197c50c662D4c409D7A Minting flow, invitation code mapping, card assignment, referral rewards, Royal Flush progress, claims.
VIP Marketplace 0xf83f6d40a56C5263A75Ac98e32B473C0adf81f58 Listing creation, listing cancellation, purchase settlement, marketplace fee configuration.

System Architecture

The NFT contract is the source of ERC-721 ownership. The Game/Royal contract is the state machine for minting, invitations, card assignment, rewards, and Royal Flush progress. The Marketplace contract handles listing and purchase flow for eligible cards. The system should be assessed as a coordinated application, not as three unrelated contracts.

Core state boundaries

  • NFT ownership is determined by ERC-721 state in the NFT contract.
  • Royal Flush progress and reward accounting are determined by the Game/Royal contract.
  • Marketplace listing state is determined by the Marketplace contract and listing hashes.
  • USDC movement is performed using the Polygon USDC contract at 0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359.

Primary trust boundary

  • The system is not fully trustless because owner/admin and updater permissions exist.
  • Some functions are operationally useful for migration, support, metadata setup, pause control, and game-state maintenance.
  • Those permissions must be documented as trust assumptions for users and reviewers.

Main Flows

Mint Flow

A user calls Game.mint(string referralCode) with a private invitation code. The Game/Royal contract validates the flow, handles USDC payment logic, records user/referral state, calls the NFT contract to mint the assigned card, and may mint two gift NFT cards for the inviter according to the contract rules. At least one gift card may help the inviter's Royal Flush progress; eligible non-locked gift cards may be listed in the official marketplace. The expected event evidence includes USDC Transfer, ERC-721 Transfer from the zero address, Referred, TokenIdsUpdated, and Minted.

Royal Flush Progress

Royal Flush progress is a game-state layer on top of ERC-721 ownership. The NFT contract records token ownership and card attributes. The Game/Royal contract records user progress through getHasCard, getIsRoyal, getCardsCollected, and token-id association methods. Reviewers should verify whether the stored Royal Flush state matches current NFT ownership and expected transfer/listing restrictions.

Marketplace Flow

The Marketplace contract uses a listing tuple containing token ID, price, seller, expiry, and nonce. Users can create, buy, or cancel listings. Reviewers should verify listing validity, seller ownership, approval behavior, stale listing handling, cancellation behavior, purchase settlement, royalty/fee behavior, and restrictions for Royal Flush cards.

Admin And Updater Surfaces

Automated scanners may report owner-controlled balance or accounting risks because the system contains privileged configuration and updater functions. This report accepts that finding as an admin/trust risk and explains its expected role.

Surface Contract Reason it exists Residual risk
setGameContract NFT Connects the NFT contract to the authorized game/minting contract. If left mutable, changing the game address changes the authorized minting path.
mintWithCard NFT Allows the authorized game flow to mint cards with suit/rank attributes. Scanner may classify this as privileged balance modification. Review should confirm caller restrictions in source.
setPaused NFT Operational safety control to pause NFT behavior if needed. Users depend on owner/admin not abusing pause powers.
setCardTokenURI, setCardTokenURIs, freezeMetadata NFT Metadata configuration and finalization. Before metadata is frozen, token presentation may be changed by admin action.
setAllowedUpdater Game/Royal Allows operational addresses to update game-state links and progress where required. Updater authorization is a sensitive permission and can affect internal accounting state.
addTokenIdToUser, removeTokenIdFromUser Game/Royal Maintains the relationship between users and token IDs for dashboard/progress logic. May affect displayed or claim-related state even if ERC-721 ownership itself is elsewhere.
updateRoyalFlushProgress Game/Royal Updates Royal Flush progress after relevant card ownership or marketplace events. Incorrect or unauthorized updates could misrepresent progress or eligibility.
setMigrationRoyalRewardsReleased Game/Royal Migration/release control for Royal rewards behavior. Changes claim availability assumptions for level 2+ reward flow.
creatorWithdraw Game/Royal Allows creator-withdrawable funds to be withdrawn. Reviewers should compare withdrawable funds, pending rewards, and actual USDC balance.
setRoyaltyPercent, setCreator Marketplace Configures marketplace fee recipient and percent. Fee changes alter economic assumptions for sellers and buyers.

Findings Summary

F-001: Three-contract design is reviewable. The public contract registry, ABI package, event topics, simulation guide, and machine-readable review packet allow independent reviewers to reconstruct expected flows.
F-002: Admin/updater trust assumptions are material. Owner and updater functions exist and can affect minting authority, pause state, metadata configuration, game-state token association, Royal Flush progress, reward release behavior, marketplace fee settings, and creator recipient configuration.
F-003: Automated scans require context. A single-contract scanner may flag the Game/Royal contract as high risk because it sees updater-controlled accounting surfaces without understanding the NFT + Game + Marketplace relationship. The finding should be accepted as a trust-risk signal, not dismissed.
F-004: External machine checks are not audits. Coin Railz and SolidityScan style outputs are useful triage artifacts but must not be presented as manual third-party audit approval.

Recommended Review Procedure

  • Confirm bytecode exists at every published contract address on Polygon Mainnet.
  • Confirm source-code verification on Polygonscan for each contract.
  • Read owner, game contract, creator, royalty percent, pause, metadata frozen, total users, total pending rewards, and USDC balances directly on-chain.
  • Decode recent mint transactions and confirm USDC transfer, NFT mint transfers, Minted, Referred, and TokenIdsUpdated logs.
  • Simulate listing, buying, cancellation, Royal Flush progress, and reward claim flows before any real transaction.
  • Compare pending rewards and creator-withdrawable values against actual contract USDC balance.
  • Document any mismatch between frontend state, contract state, and explorer state.

Frontend Independence And Claim Continuity

The frontend, backend, dashboard, and indexer are convenience layers. The authoritative state for NFT ownership, claimability, balances, and confirmed transactions is Polygon on-chain state at the deployed contract addresses.

If the PolyCards website or backend becomes unavailable, the deployed contracts may still be reachable through Polygonscan or another Polygon interface. Users can perform read-only checks against the official Game contracts, including getPendingLevel1(address), getPendingLevel2Plus(address), migrationRoyalRewardsReleased(), and related balance/state reads. If contract conditions are met and available balances exist, users may be able to call write functions such as claimLevel1() or claimRoyalRewards() directly from Polygonscan's Contract tab.

This continuity depends on the Polygon network, the deployed contracts, correct wallet connection, available contract balance, claim conditions, gas, and release flags where relevant. It does not guarantee successful claims, marketplace liquidity, support, future hosting, or replacement of off-chain services.

Residual Risk Position

PolyCards should be described as an administratively operated NFT card-game and marketplace system with public contracts and machine-readable review materials. It should not be described as fully trustless or externally audited. The correct external statement is that admin and updater powers are known, documented, and part of the current deployed architecture.

Non-Goals

  • This document does not provide a legal opinion or designate a jurisdiction.
  • This document does not evaluate securities, gambling, consumer, tax, financial-promotion, or other regulatory classification.
  • This document does not claim that rewards, liquidity, resale value, user activity, or profitability will occur.
  • This document does not replace independent technical review.