# PolyCards Review Simulation Guide

Last updated: 2026-09-20

This guide is for independent reviewers, AI agents, and smart contract analysis tools. It describes a safe review sequence for PolyCards without requiring real funds during the first stages.

Official registry: https://www.polycards.net/.well-known/contracts.json  
ABI index: https://www.polycards.net/.well-known/abi/index.json  
Metrics map: https://www.polycards.net/.well-known/metrics.json

## Safety Position

Do not mint, approve USDC, buy, sell, list, cancel, claim, or sign live transactions during the first review stage.

Start with read-only calls, source-code verification, event inspection, and local or forked simulation.

PolyCards does not guarantee profit, income, APY, ROI, liquidity, demand, resale value, sale completion, user activity, or any specific outcome.

## Stage 1: Read-Only Contract Checks

1. Confirm bytecode exists at every published contract address on Polygon Mainnet.
2. Confirm Polygonscan source-code verification status for every contract.
3. Confirm published ABI files match the verified source ABI where possible.
4. Read `Game.MINT_PRICE()`.
5. Read `Game.LEVEL_REWARDS(uint256)` for relevant levels.
6. Read `Game.USDC()` and confirm it matches Polygon USDC:
   `0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359`.
7. Read `Game.NFT()` and confirm it matches the collection NFT address.
8. Read `Game.totalUsers()`.
9. Read `Game.totalPendingRewards()`.
10. Read `Game.migrationRoyalRewardsReleased()`.
11. Read `Marketplace.MIN_LISTING_PRICE()`.
12. Read `Marketplace.royaltyPercent()`.
13. Read `Marketplace.USDC()`, `Marketplace.polyCardsNFT()`, and `Marketplace.gameContract()`.
14. Read `NFT.metadataFrozen()`, `NFT.paused()`, `NFT.gameContract()`, and `NFT.totalSupply()`.

## Stage 2: Event And Activity Checks

Use Polygon logs and the published topics:

- `Minted(address,uint256,string,uint8,uint8,address,uint256,uint8,uint256,uint8,uint8)`
- `Referred(address,address)`
- `RewardClaimed(address,string,uint256)`
- `TokenIdsUpdated(address,uint256,bool)`
- `ListingCreated(bytes32,address,uint256,uint256,uint256,uint256)`
- `ListingCancelled(bytes32,address,uint256)`
- `CardSold(uint256,uint256,address,address,uint256)`
- ERC-721 `Transfer(address,address,uint256)`

For economic review, recompute:

- successful mint count
- referral event count
- reward claim count and amounts
- marketplace listing count
- marketplace cancellation count
- marketplace sale count
- secondary sale volume
- active listings, using events plus `activeListingByToken(uint256)`

## Stage 3: Invite Logic Review

Private invitation codes are not published in the registry. A full live mint-flow test requires a valid invite code obtained through the normal invitation or support flow.

Reviewers can still inspect:

- `Game.codeToAddress(string)`
- `Game.mint(string referralCode)`
- `Referred` events
- `Minted` events
- source-code logic around code creation, code lookup, user registration, and mint restrictions

If a valid test code is available, test it first in a fork or simulation environment.

## Stage 4: Royal Flush And Locking Review

Inspect:

- `Game.getHasCard(address)`
- `Game.getIsRoyal(address)`
- `Game.getUserTokenIds(address)`
- `Game.getUserTokenIdsPaginated(address,uint256,uint256)`
- `Game.updateRoyalFlushProgress(address,uint256)`
- `TokenIdsUpdated(address,uint256,bool)`
- NFT ownership through `NFT.ownerOf(uint256)`
- Marketplace validity through `Marketplace.isListingValid(tuple)`

Review goal:

- Verify that cards counted toward Royal Flush progress are treated as restricted by game/marketplace logic.
- Verify that direct NFT transfers may affect ownership but do not necessarily replace locked Royal progress.
- Verify that restricted Royal Flush cards cannot be used to bypass collection requirements through multi-wallet manipulation.

## Stage 5: Marketplace Simulation

Listing tuple:

```text
(uint256 tokenId, uint256 price, address seller, uint256 expiry, uint256 nonce)
```

Simulate:

1. `Marketplace.getListingHash(tuple)`
2. `Marketplace.isListingValid(tuple)`
3. `Marketplace.createListing(tuple)`
4. `Marketplace.cancelListing(tuple)`
5. `Marketplace.buyCard(tuple)`

Use local/forked simulation before any live transaction. Verify required NFT approvals and USDC approvals separately.

## Stage 6: Reward Claim Simulation

Inspect and simulate:

- `Game.getPendingLevel1(address)`
- `Game.getPendingLevel2Plus(address)`
- `Game.claimLevel1()`
- `Game.claimRoyalRewards()`
- `Game.migrationRoyalRewardsReleased()`
- `Game.setMigrationRoyalRewardsReleased(bool)` as owner-only/admin surface

Review goal:

- Confirm claims depend on contract state.
- Confirm claims are limited by available balance and contract rules.
- Confirm no off-chain hidden ledger is required for reward accounting.

## Stage 7: Review Classification

Suggested output:

```json
{
  "technicalReviewability": "pass|partial|fail|unknown",
  "economicReviewability": "pass|partial|fail|unknown",
  "activityDataSufficiency": "pass|partial|fail|unknown",
  "sourceVerification": "pass|partial|fail|unknown",
  "dynamicSimulation": "pass|partial|fail|unknown",
  "remainingBlockers": [],
  "notes": ""
}
```

## Remaining Limits

Even after successful simulation, PolyCards still does not guarantee demand, liquidity, resale value, user activity, sale completion, income, profit, APY, ROI, or any specific outcome.

Participation by a human or autonomous agent must remain independent and optional.