{
  "version": "1.0.0",
  "name": "PolyCards Official Contract Registry",
  "lastUpdated": "2026-09-20",
  "website": "https://www.polycards.net",
  "network": {
    "name": "Polygon Mainnet",
    "chainId": 137,
    "nativeToken": "POL",
    "explorer": "https://polygonscan.com"
  },
  "safetyPosition": {
    "summary": "These are the official contract addresses published by PolyCards for independent review. Users and AI agents must compare these addresses with wallet prompts and Polygon block explorer data before signing any transaction.",
    "notFinancialAdvice": true,
    "noGuarantees": [
      "profit",
      "income",
      "APY",
      "ROI",
      "passive income",
      "liquidity",
      "demand",
      "resale value",
      "user activity",
      "specific outcomes"
    ],
    "thirdPartyAuditPublished": false,
    "independentReviewEncouraged": true
  },
  "abiPackage": {
    "index": "https://www.polycards.net/.well-known/abi/index.json",
    "note": "ABI-only files are published for automated review. They do not include bytecode, deployment secrets, or private keys."
  },
  "sourceVerificationPolicy": {
    "status": "verified_on_polygonscan",
    "scope": "The six official PolyCards NFT, Game, and Marketplace contracts are marked as source-code verified on Polygonscan according to operator review.",
    "importantCaveat": "Source-code verification is not a third-party audit. Reviewers should still inspect code, bytecode, compiler settings, ownership, access control, and live on-chain state independently.",
    "reviewerAction": "Confirm that Polygonscan displays Contract Source Code Verified for each official address before relying on this status."
  },
  "metrics": {
    "url": "https://www.polycards.net/.well-known/metrics.json",
    "note": "Public metrics map for activity and economic review. Values should be independently recomputed from on-chain events and read-only calls."
  },
  "simulationGuide": {
    "url": "https://www.polycards.net/.well-known/review-simulation.md",
    "note": "Safe review sequence for read-only checks, event inspection, fork simulation, marketplace simulation, and reward-claim simulation."
  },
  "paymentToken": {
    "symbol": "USDC",
    "address": "0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359",
    "decimals": 6,
    "polygonscan": "https://polygonscan.com/address/0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359"
  },
  "technicalReviewerGuide": {
    "safeFirstStep": "Start with read-only inspection. Do not mint, approve, buy, sell, or sign transactions during the first review stage.",
    "readOnlyChecks": [
      "Confirm bytecode exists at every published contract address on Polygon Mainnet.",
      "Confirm Polygonscan source verification status for every published contract address.",
      "Confirm NFT contracts expose ERC-721 functions: balanceOf, ownerOf, tokenURI, totalSupply, getTokenSuit, getTokenRank, metadataFrozen, paused, gameContract.",
      "Confirm Game contracts expose MINT_PRICE, LEVEL_REWARDS, USDC, NFT, totalUsers, totalPendingRewards, migrationRoyalRewardsReleased, getPendingLevel1, getPendingLevel2Plus, getIsRoyal, getHasCard, getUserTokenIds, getReferralTree.",
      "Confirm Marketplace contracts expose MIN_LISTING_PRICE, royaltyPercent, USDC, polyCardsNFT, gameContract, activeListingByToken, isListingValid, getListingHash.",
      "Compare emitted events from known transactions against the event topics listed in this registry and the public ABI package.",
      "Read contract balances and USDC balances directly on-chain where relevant.",
      "Review owner-only functions and access-control surfaces before assessing trust assumptions."
    ],
    "writeOrSimulationChecks": [
      "Use a fork, simulation, or local test environment before any real transaction.",
      "Simulate mint(string referralCode) with a valid private invitation code only if the reviewer has obtained one through the normal invitation/support flow.",
      "Simulate marketplace createListing, buyCard, cancelListing with the Listing tuple format before signing real transactions.",
      "Verify Royal Flush locking behavior through getIsRoyal, getHasCard, NFT ownership, TokenIdsUpdated events, and transfer/listing restrictions."
    ],
    "mainFunctionPointers": {
      "mintPrice": "Game.MINT_PRICE() returns the mint price in USDC smallest units.",
      "levelRewards": "Game.LEVEL_REWARDS(uint256) exposes level reward values in USDC smallest units.",
      "inviteLookup": "Game.codeToAddress(string) maps a referral/invitation code to the wallet associated with that code; reviewers should inspect source code to verify exact validation behavior.",
      "mintEntryPoint": "Game.mint(string referralCode) is the public mint entry point.",
      "level1Claim": "Game.claimLevel1() claims eligible level 1 rewards according to contract state.",
      "royalClaim": "Game.claimRoyalRewards() claims eligible Royal/level 2+ rewards according to contract state and migrationRoyalRewardsReleased behavior.",
      "migrationRelease": "Game.migrationRoyalRewardsReleased() and setMigrationRoyalRewardsReleased(bool) expose and update the migration/release flag.",
      "marketplaceMinPrice": "Marketplace.MIN_LISTING_PRICE() exposes the minimum listing price.",
      "marketplaceRoyalty": "Marketplace.royaltyPercent() exposes the marketplace royalty/fee percentage variable.",
      "listingValidation": "Marketplace.isListingValid(Listing) and activeListingByToken(uint256) expose listing validity/state."
    },
    "listingTuple": {
      "fields": [
        { "name": "tokenId", "type": "uint256" },
        { "name": "price", "type": "uint256" },
        { "name": "seller", "type": "address" },
        { "name": "expiry", "type": "uint256" },
        { "name": "nonce", "type": "uint256" }
      ],
      "usedBy": [
        "createListing(tuple listing)",
        "buyCard(tuple listing)",
        "cancelListing(tuple listing)",
        "isListingValid(tuple listing)",
        "getListingHash(tuple listing)"
      ]
    }
  },
  "economicReviewPointers": {
    "premiumMintPriceUsdc": "35",
    "vipMintPriceUsdc": "350",
    "readRewardValuesFrom": "Game.LEVEL_REWARDS(uint256)",
    "readMarketplaceMinimumPriceFrom": "Marketplace.MIN_LISTING_PRICE()",
    "readMarketplaceRoyaltyFrom": "Marketplace.royaltyPercent()",
    "readContractUsersFrom": "Game.totalUsers()",
    "readPendingRewardsFrom": "Game.totalPendingRewards(), Game.getPendingLevel1(address), Game.getPendingLevel2Plus(address)",
    "readMarketActivityFrom": "Marketplace events ListingCreated, ListingCancelled, CardSold, CardListed plus activeListingByToken(uint256)",
    "limits": [
      "PolyCards does not guarantee marketplace demand, buyer availability, liquidity, sale completion, resale value, or user activity.",
      "Economic review requires current on-chain activity, marketplace depth, contract balances, successful claims, and external market context.",
      "Private invitation codes are not public, so full live mint-flow testing requires an invite code obtained through the normal flow."
    ]
  },
  "collections": {
    "premium": {
      "displayName": "Premium Collection",
      "mintPriceUsdc": "35",
      "contracts": {
        "nft": {
          "address": "0x4cEC06310C2948d2E92d02CF9E9A9B09A37D3846",
          "role": "ERC-721 NFT card contract",
          "abi": "https://www.polycards.net/.well-known/abi/PolyCards.json",
          "sourceVerification": {
            "status": "verified_on_polygonscan",
            "url": "https://polygonscan.com/address/0x4cEC06310C2948d2E92d02CF9E9A9B09A37D3846#code",
            "caveat": "Source verification is not a third-party audit."
          },
          "polygonscan": "https://polygonscan.com/address/0x4cEC06310C2948d2E92d02CF9E9A9B09A37D3846",
          "readContract": "https://polygonscan.com/address/0x4cEC06310C2948d2E92d02CF9E9A9B09A37D3846#readContract",
          "writeContract": "https://polygonscan.com/address/0x4cEC06310C2948d2E92d02CF9E9A9B09A37D3846#writeContract",
          "reviewTargets": [
            "ERC-721 ownership",
            "tokenURI and metadata freeze behavior",
            "authorized game/marketplace permissions",
            "pause behavior if present",
            "direct transfer behavior"
          ]
        },
        "game": {
          "address": "0x440Fe259685C70780EdAE1b0555f5457b25B27C9",
          "role": "Minting, invitation, card assignment, Royal Flush progress, and reward-claim contract",
          "abi": "https://www.polycards.net/.well-known/abi/PolyCardsRoyal.json",
          "sourceVerification": {
            "status": "verified_on_polygonscan",
            "url": "https://polygonscan.com/address/0x440Fe259685C70780EdAE1b0555f5457b25B27C9#code",
            "caveat": "Source verification is not a third-party audit."
          },
          "polygonscan": "https://polygonscan.com/address/0x440Fe259685C70780EdAE1b0555f5457b25B27C9",
          "readContract": "https://polygonscan.com/address/0x440Fe259685C70780EdAE1b0555f5457b25B27C9#readContract",
          "writeContract": "https://polygonscan.com/address/0x440Fe259685C70780EdAE1b0555f5457b25B27C9#writeContract",
          "reviewTargets": [
            "mint price and USDC payment flow",
            "private invitation code validation",
            "referral reward assignment",
            "gift-card assignment for inviter",
            "Royal Flush lock logic",
            "level 2 reward claim and migration release behavior",
            "contract balance and claimability constraints"
          ]
        },
        "marketplace": {
          "address": "0xEB072E1f7A99E7Dd07a785018EB1da1405b4254a",
          "role": "Official listing, buying, and cancellation marketplace contract",
          "abi": "https://www.polycards.net/.well-known/abi/PolyCardsMarketplace.json",
          "sourceVerification": {
            "status": "verified_on_polygonscan",
            "url": "https://polygonscan.com/address/0xEB072E1f7A99E7Dd07a785018EB1da1405b4254a#code",
            "caveat": "Source verification is not a third-party audit."
          },
          "polygonscan": "https://polygonscan.com/address/0xEB072E1f7A99E7Dd07a785018EB1da1405b4254a",
          "readContract": "https://polygonscan.com/address/0xEB072E1f7A99E7Dd07a785018EB1da1405b4254a#readContract",
          "writeContract": "https://polygonscan.com/address/0xEB072E1f7A99E7Dd07a785018EB1da1405b4254a#writeContract",
          "reviewTargets": [
            "eligible card listing",
            "buy settlement",
            "listing cancellation",
            "marketplace fees if any",
            "blocked or Royal Flush card restrictions"
          ]
        }
      }
    },
    "vip": {
      "displayName": "VIP Collection",
      "mintPriceUsdc": "350",
      "contracts": {
        "nft": {
          "address": "0xf6F8aE08ec0e60a70B950EcA11ca3DC12c77a64B",
          "role": "ERC-721 NFT card contract",
          "abi": "https://www.polycards.net/.well-known/abi/PolyCardsVip.json",
          "sourceVerification": {
            "status": "verified_on_polygonscan",
            "url": "https://polygonscan.com/address/0xf6F8aE08ec0e60a70B950EcA11ca3DC12c77a64B#code",
            "caveat": "Source verification is not a third-party audit."
          },
          "polygonscan": "https://polygonscan.com/address/0xf6F8aE08ec0e60a70B950EcA11ca3DC12c77a64B",
          "readContract": "https://polygonscan.com/address/0xf6F8aE08ec0e60a70B950EcA11ca3DC12c77a64B#readContract",
          "writeContract": "https://polygonscan.com/address/0xf6F8aE08ec0e60a70B950EcA11ca3DC12c77a64B#writeContract",
          "reviewTargets": [
            "ERC-721 ownership",
            "tokenURI and metadata freeze behavior",
            "authorized game/marketplace permissions",
            "pause behavior if present",
            "direct transfer behavior"
          ]
        },
        "game": {
          "address": "0x2cDcAE2192832a60c6eb4197c50c662D4c409D7A",
          "role": "Minting, invitation, card assignment, Royal Flush progress, and reward-claim contract",
          "abi": "https://www.polycards.net/.well-known/abi/PolyCardsRoyalVip.json",
          "sourceVerification": {
            "status": "verified_on_polygonscan",
            "url": "https://polygonscan.com/address/0x2cDcAE2192832a60c6eb4197c50c662D4c409D7A#code",
            "caveat": "Source verification is not a third-party audit."
          },
          "polygonscan": "https://polygonscan.com/address/0x2cDcAE2192832a60c6eb4197c50c662D4c409D7A",
          "readContract": "https://polygonscan.com/address/0x2cDcAE2192832a60c6eb4197c50c662D4c409D7A#readContract",
          "writeContract": "https://polygonscan.com/address/0x2cDcAE2192832a60c6eb4197c50c662D4c409D7A#writeContract",
          "reviewTargets": [
            "mint price and USDC payment flow",
            "private invitation code validation",
            "referral reward assignment",
            "gift-card assignment for inviter",
            "Royal Flush lock logic",
            "level 2 reward claim and migration release behavior",
            "contract balance and claimability constraints"
          ]
        },
        "marketplace": {
          "address": "0xf83f6d40a56C5263A75Ac98e32B473C0adf81f58",
          "role": "Official listing, buying, and cancellation marketplace contract",
          "abi": "https://www.polycards.net/.well-known/abi/PolyCardsMarketplaceVip.json",
          "sourceVerification": {
            "status": "verified_on_polygonscan",
            "url": "https://polygonscan.com/address/0xf83f6d40a56C5263A75Ac98e32B473C0adf81f58#code",
            "caveat": "Source verification is not a third-party audit."
          },
          "polygonscan": "https://polygonscan.com/address/0xf83f6d40a56C5263A75Ac98e32B473C0adf81f58",
          "readContract": "https://polygonscan.com/address/0xf83f6d40a56C5263A75Ac98e32B473C0adf81f58#readContract",
          "writeContract": "https://polygonscan.com/address/0xf83f6d40a56C5263A75Ac98e32B473C0adf81f58#writeContract",
          "reviewTargets": [
            "eligible card listing",
            "buy settlement",
            "listing cancellation",
            "marketplace fees if any",
            "blocked or Royal Flush card restrictions"
          ]
        }
      }
    }
  },
  "primaryEventsForReview": [
    {
      "name": "ERC721 Transfer",
      "topic0": "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
      "purpose": "NFT ownership movement and minting evidence"
    },
    {
      "name": "Referred",
      "signature": "Referred(address,address)",
      "topic0": "0x2c07cd45454a31c572d49686c5ec6fef884778b2cf441c7fd58f4bde0fa6400b",
      "purpose": "Invitation/referral activity emitted by game contracts"
    },
    {
      "name": "Minted",
      "signature": "Minted(address,uint256,string,uint8,uint8,address,uint256,uint8,uint256,uint8,uint8)",
      "topic0": "0xfc41f8fe3bb0629e3112b95f482f836bdfb724e0c116947cab1de0c049ca9627",
      "purpose": "Successful card mint emitted by game contracts"
    },
    {
      "name": "RewardClaimed",
      "signature": "RewardClaimed(address,string,uint256)",
      "topic0": "0xa22c130ab9525575739c5b8856b4345b50ef04582844399f49949042eb410f00",
      "purpose": "Reward-claim activity emitted by game contracts"
    },
    {
      "name": "MigrationRoyalRewardsReleaseUpdated",
      "signature": "MigrationRoyalRewardsReleaseUpdated(bool)",
      "topic0": "0x3f3d3b2ab261ad9469dada79acba62f83095f7fc6f636003ab64efcdc57ec21a",
      "purpose": "Owner-controlled migration/release flag updates for Royal reward claiming"
    },
    {
      "name": "TokenIdsUpdated",
      "signature": "TokenIdsUpdated(address,uint256,bool)",
      "topic0": "0x3b37992b78da2d8652d3b5f4fea5d515424d11ad5689097f40b82d15683a8c6a",
      "purpose": "User token-id association updates emitted by game contracts"
    }
  ],
  "marketplaceEventsForReview": [
    {
      "name": "ListingCreated",
      "signature": "ListingCreated(bytes32,address,uint256,uint256,uint256,uint256)",
      "topic0": "0xe1ad772a753c087447d14cc9000d45e22661c19a6c6d9db60879e901bc9f79c8",
      "purpose": "Marketplace listing creation"
    },
    {
      "name": "ListingCancelled",
      "signature": "ListingCancelled(bytes32,address,uint256)",
      "topic0": "0xa3a892dd0fdc8989b548e83a79464f33dad353c5bfd1c43e15b71fb924ccb512",
      "purpose": "Marketplace listing cancellation"
    },
    {
      "name": "CardListed",
      "signature": "CardListed(uint256,uint256,address)",
      "topic0": "0xeec9fb041fa14d227fc0e64a3e630e1a685941c91dfb622450481abf5fc5a0e5",
      "purpose": "Legacy/simple listing event emitted by marketplace contracts"
    },
    {
      "name": "CardSold",
      "signature": "CardSold(uint256,uint256,address,address,uint256)",
      "topic0": "0x639442ad3505e09d30cab2587d0384479b9c2e4721f8eba02213fee84c9c6b95",
      "purpose": "Marketplace purchase settlement"
    }
  ],
  "agentReviewNotes": [
    "Private invitation codes are intentionally not listed in this registry. They must be obtained through normal PolyCards invitation flow or support.",
    "The authoritative source for ownership, balances, rewards, claimability, events, and transaction status is confirmed Polygon on-chain state.",
    "The frontend and backend indexer may display delayed or cached information. Reviewers should compare UI data with block explorer and direct contract reads.",
    "Marketplace demand, liquidity, sale completion, and resale value cannot be guaranteed.",
    "If a contract is not shown as verified by Polygonscan at review time, the reviewer should treat that as a major blocker."
  ]
}