Developer Documentation

// Using ethers.js v6
import { ethers } from "ethers";

// Connect to provider
const provider = new ethers.JsonRpcProvider("https://base.llamarpc.com");
const signer = new ethers.Wallet(PRIVATE_KEY, provider);

// BoosterDropV2 contract
const boosterDrop = new ethers.Contract(
  BOOSTER_DROP_ADDRESS,
  IBoosterDropV2_ABI,
  signer
);

// Get mint price for packs (example: 5 packs)
const mintPrice = await boosterDrop.getMintPrice(5);

// Mint packs with referral (earn fees!)
await boosterDrop.mint(
  5, // amount of packs
  signer.address, // recipient
  YOUR_ADDRESS, // referrer (example: earn portion of fees)
  YOUR_ADDRESS, // originReferrer (example: earn additional portion)
  { value: mintPrice } // ETH payment
);

// BoosterTokenV2 contract
const boosterToken = new ethers.Contract(
  BOOSTER_TOKEN_ADDRESS,
  IBoosterTokenV2_ABI,
  signer
);

// Check current market type
const marketType = await boosterToken.marketType();
// 0 = BONDING_CURVE, 1 = UNISWAP_POOL

// Get sell quote for tokens (example: 100,000 tokens)
const tokenAmount = ethers.parseUnits("100000", 18);
const ethReceived = await boosterToken.getTokenSellQuote(tokenAmount);

// Sell tokens with slippage protection
const minPayout = (ethReceived * 98n) / 100n; // Example: 2% slippage
await boosterToken.sell(
  tokenAmount,
  signer.address, // recipient of ETH
  minPayout, // minimum ETH to accept
  YOUR_ADDRESS, // referrer
  YOUR_ADDRESS // originReferrer
);

// Get entropy fee required for opening
const entropyFee = await boosterDrop.getEntropyFee();

// Open multiple packs (requires ETH for entropy)
const tokenIds = [1, 2, 3]; // Your unopened pack token IDs
await boosterDrop.open(tokenIds, { value: entropyFee });

// Get rarity info after randomness is fulfilled
const rarityInfo = await boosterDrop.getTokenRarity(tokenIds[0]);
console.log({
  rarity: rarityInfo.rarity, // 1=Common, 2=Rare, 3=Epic, 4=Legendary
  randomValue: rarityInfo.randomValue,
  randomness: rarityInfo.tokenSpecificRandomness,
});

// Sell single NFT (opened or unopened)
await boosterDrop.sellAndClaimOffer(tokenId);

// Batch sell multiple NFTs
const tokenIds = [1, 2, 3];
await boosterDrop.sellAndClaimOfferBatch(tokenIds);

// Exchange values are examples only - actual values vary by collection:
// Unopened packs example: 80,000-100,000 tokens (80-100% of mint cost) [100% for packs created after August 1st, 2025]
// Opened packs examples based on rarity:
// - Common: 20,000 tokens (example)
// - Rare: 120,000 tokens (example)
// - Epic: 420,000 tokens (example)
// - Legendary: 3,000,000 tokens (example)
// Note: This optional exchange feature may not be available for all collections

// Check if pack is opened by getting rarity
try {
  const rarityInfo = await boosterDrop.getTokenRarity(tokenId);
  console.log("Pack is opened, rarity:", rarityInfo.rarity);
} catch {
  console.log("Pack is unopened");
}

// Track mint events
const mintFilter = boosterDrop.filters.BoosterDropsMinted();
const mintEvents = await boosterDrop.queryFilter(mintFilter);

// Track pack openings
const openFilter = boosterDrop.filters.BoosterDropOpened();
const openEvents = await boosterDrop.queryFilter(openFilter);

// Get token metadata URI
const tokenURI = await boosterDrop.tokenURI(tokenId);

// Track user's cards via transfer events
const userAddress = "0x...";
const transferFilter = boosterDrop.filters.BoosterDropTransfer(
  null,
  userAddress
);
const transferEvents = await boosterDrop.queryFilter(transferFilter);

// Get card details including randomness for game mechanics
const userCards = [];
for (const event of transferEvents) {
  const tokenId = event.args.tokenId;

  try {
    const rarityInfo = await boosterDrop.getTokenRarity(tokenId);
    userCards.push({
      tokenId,
      rarity: rarityInfo.rarity,
      randomValue: rarityInfo.randomValue, // Use for game RNG
      randomness: rarityInfo.tokenSpecificRandomness, // Unique per card
      isOpened: true,
    });

    // Use randomness for unique card attributes (example values)
    const uniqueSeed = rarityInfo.randomValue;
    const attackPower = 100 + (uniqueSeed % 50); // Example calculation
    const defense = 80 + (uniqueSeed % 30); // Example calculation
  } catch {
    // Rarity not defined - pack hasn't been opened yet
    userCards.push({
      tokenId,
      rarity: 0,
      isOpened: false,
    });
  }
}

// Grant game benefits based on collection
const legendaryCount = userCards.filter((c) => c.rarity === 4).length;
if (legendaryCount > 0) {
  // Unlock special game features
}

// IBoosterCardSeedUtils contract address on Base
const SEED_UTILS_ADDRESS = "0x002aaaa42354bf8f09f9924977bf0c531933f999";

// Connect to the BoosterCardSeedUtils contract
const seedUtils = new ethers.Contract(
  SEED_UTILS_ADDRESS,
  IBoosterCardSeedUtils_ABI,
  provider
);

// Get rarity info from a card (must be opened)
const tokenId = 123; // Your opened pack token ID
const rarityInfo = await boosterDrop.getTokenRarity(tokenId);

// Use tokenSpecificRandomness as the seed for wear & foil
const seed = rarityInfo.tokenSpecificRandomness;

// Get wear value (string with 10 decimal places, e.g., "0.1234567890")
const wear = await seedUtils.wearFromSeed(seed);
console.log("Card wear:", wear);

// Get foil type (returns "Prize", "Standard", or "Normal")
const foilType = await seedUtils.getFoilMappingFromSeed(seed);
console.log("Card foil:", foilType);

// Get both wear and foil in a single call
const cardData = await seedUtils.getCardSeedData(seed);
console.log({
  wear: cardData.wear, // e.g., "0.0123456789"
  foilType: cardData.foilType, // e.g., "Normal", "Standard", or "Prize"
});

// Example: Process multiple cards to get their wear & foil
const userCards = [101, 102, 103]; // Token IDs of opened packs
const cardDetails = [];

for (const tokenId of userCards) {
  try {
    const rarityInfo = await boosterDrop.getTokenRarity(tokenId);
    const [wear, foilType] = await seedUtils.getCardSeedData(
      rarityInfo.tokenSpecificRandomness
    );

    cardDetails.push({
      tokenId,
      rarity: rarityInfo.rarity,
      wear,
      foilType,
      // Use wear for game mechanics
      condition:
        parseFloat(wear) < 0.05
          ? "Pristine"
          : parseFloat(wear) < 0.2
          ? "Mint"
          : parseFloat(wear) < 0.45
          ? "Lightly Played"
          : parseFloat(wear) < 0.75
          ? "Moderately Played"
          : "Heavily Played",
    });
  } catch (error) {
    console.log(`Token ${tokenId} is unopened or invalid`);
  }
}

// Build game features based on foil & wear
const prizeCards = cardDetails.filter((c) => c.foilType === "Prize");
const mintConditionCards = cardDetails.filter((c) => parseFloat(c.wear) < 0.05);

Random Value Range (0 - 999,999)
├─ Legendary (0 - 4,999): 0.5%
│  └─ Cards split range evenly (e.g., 10 cards = ~500 values each)
├─ Epic (5,000 - 84,999): 8.0%
│  └─ Cards split range evenly (e.g., 20 cards = ~4,000 values each)
├─ Rare (85,000 - 334,999): 25.0%
│  └─ Cards split range evenly (e.g., 30 cards = ~8,333 values each)
└─ Common (335,000 - 999,999): 66.5%
   └─ Cards split range evenly (e.g., 40 cards = ~16,625 values each)