Core Candy Machine 防机器人保护最佳实践

https://yourproject.com/metadata/0.json
https://yourproject.com/metadata/1.json
https://yourproject.com/metadata/2.json

import fs from "fs";
import mime from "mime";
import { createGenericFile } from "@metaplex-foundation/umi";

const umi = // import or create your umi instance.

// Upload files - UMI automatically creates unpredictable transaction IDs
async function uploadFiles(filePaths: string[]): Promise<string[]> {
  const files = filePaths.map((filePath) => {
    const file = fs.readFileSync(filePath);
    const mimeType = mime.getType(filePath);
    return createGenericFile(file, "file", {
      tags: mimeType ? [{ name: "content-type", value: mimeType }] : [],
    });
  });

  const uploadedUris = await umi.uploader.upload(files);

  // Log each uploaded URI with its index for tracking
  uploadedUris.forEach((uri, index) => {
    console.log(`Uploaded file #${index} -> ${uri}`);
  });

  return uploadedUris;
}

// CRITICAL: Store all returned URIs - you'll need them for the reveal mapping!
const uploadedUris = await uploadFiles(allFilePaths);

// Result: Automatically unpredictable URIs that MUST be stored
// uploadedUris[0] = "https://arweave.net/BrG44HdsEhzapvs8bEqzvkq4egwevS3fRE6kLuCyOdCd"
// uploadedUris[1] = "https://arweave.net/9jK3LpM7NqR5xY8vZ2BwC4tE6gH9sF1D3a7Q8eR2nM4K"
// uploadedUris[2] = "https://arweave.net/5tH8GpN3MqL7wV9xB2CeD4yR6kJ1sK3F8gQ7eP5nL9M2"
// ... etc for all your files

// STORE THESE SECURELY - you cannot regenerate them!
// These URIs are from the underlying service (Irys/ArDrive Turbo) via UMI
fs.writeFileSync("./uploaded-uris.json", JSON.stringify(uploadedUris, null, 2));
await securelyStoreUris(uploadedUris);

{
  "name": "Mystery Asset",
  "description": "This asset will be revealed after mint completion. Each asset is unique and will be unveiled with its true traits and rarity soon!",
  "image": "https://yourproject.com/images/mystery-box.png",
  "attributes": [
    {
      "trait_type": "Status",
      "value": "Unrevealed"
    },
    {
      "trait_type": "Collection",
      "value": "Your Project Name"
    }
  ]
}

https://yourproject.com/metadata/placeholder.json

// Generate secure mapping BEFORE creating your Candy Machine
function generateSecureMapping(totalSupply: number): number[] {
  // Create array of indices [0, 1, 2, ..., totalSupply-1]
  const indices = Array.from({ length: totalSupply }, (_, i) => i);

  // Use cryptographically secure shuffle (Fisher-Yates)
  for (let i = indices.length - 1; i > 0; i--) {
    const j = Math.floor(crypto.getRandomValues(new Uint32Array(1))[0] / (2**32) * (i + 1));
    [indices[i], indices[j]] = [indices[j], indices[i]];
  }

  return indices;
}

// Example: For a 4000 NFT collection
const secureMapping = generateSecureMapping(4000);
// Result: [2847, 91, 3756, 128, 2904, 567, ...]
// This means:
// - Mint index 0 will reveal as metadata index 2847
// - Mint index 1 will reveal as metadata index 91
// - Mint index 2 will reveal as metadata index 3756
// etc.

// Store this mapping securely - it's your reveal key!
await storeMapping(secureMapping);

// Generate verification hashes BEFORE mint launch
async function generateVerificationHashes(
  mapping: number[],
  metadataFiles: string[],
  uploadedUris: string[]
): Promise<{masterHash: string, metadataHashes: string[]}> {

  // 1. Hash each individual metadata file
  const metadataHashes = metadataFiles.map(metadata =>
    crypto.createHash('sha256').update(metadata).digest('hex')
  );

  // 2. Extract transaction IDs from uploaded URIs
  const transactionIds = uploadedUris.map(uri => {
    // Extract transaction ID from URI (e.g., https://arweave.net/[ID])
    return uri.split('/').pop();
  });

  // 3. Create verification data structure
  const verificationData = mapping.map((finalIndex, mintIndex) => ({
    mintIndex,
    finalIndex,
    transactionId: transactionIds[finalIndex],
    metadataUri: uploadedUris[finalIndex],
    metadataHash: metadataHashes[finalIndex],
  }));

  // 4. Generate master hash of entire mapping
  const masterHash = crypto
    .createHash('sha256')
    .update(JSON.stringify(verificationData))
    .digest('hex');

  return { masterHash, metadataHashes };
}

const { masterHash, metadataHashes } = await generateVerificationHashes(
  secureMapping,
  allMetadataFiles,
  uploadedUris
);

{
  "projectName": "Your Project",
  "totalSupply": 4000,
  "masterMappingHash": "a7b9c3d2e8f4g5h6i1j0k9l8m7n6o5p4q3r2s1t0u9v8w7x6y5z4",
  "metadataHashes": [
    "b1c2d3e4f5g6h7i8j9k0l1m2n3o4p5q6r7s8t9u0v1w2x3y4z5a6",
    "c2d3e4f5g6h7i8j9k0l1m2n3o4p5q6r7s8t9u0v1w2x3y4z5a6b7",
    // ... all 4000 metadata hashes
  ],
  "publishedAt": "2024-01-15T10:00:00Z",
  "verificationInstructions": "After reveal, verify your metadata hash matches the published hash for your revealed index"
}

// Option 1: Simple placeholder approach
const items = Array.from({ length: 4000 }, (_, index) => ({
  name: `Mystery Asset #${index + 1}`,
  uri: "https://yourproject.com/placeholder.json"
}));

// Option 2: Pre-randomized placeholder order for additional unpredictability
function createRandomizedPlaceholders(totalSupply: number): ConfigLine[] {
  const indices = Array.from({ length: totalSupply }, (_, i) => i);

  // Shuffle the indices for random mint order
  for (let i = indices.length - 1; i > 0; i--) {
    const j = Math.floor(Math.random() * (i + 1));
    [indices[i], indices[j]] = [indices[j], indices[i]];
  }

  return indices.map((randomIndex, position) => ({
    name: `Mystery Asset #${position + 1}`,
    uri: "https://yourproject.com/placeholder.json"
  }));
}

const randomizedItems = createRandomizedPlaceholders(4000);

// Insert placeholder items into your Candy Machine
await addConfigLines(umi, {
  candyMachine: candyMachine.publicKey,
  index: 0,
  configLines: randomizedItems,
}).sendAndConfirm(umi);

{
  "name": "Mystery Asset",
  "description": "This asset will be revealed after mint completion. Each asset is unique and will be unveiled with its true traits and rarity soon!",
  "image": "https://yourproject.com/images/mystery-box.png",
  "attributes": [
    {
      "trait_type": "Status",
      "value": "Unrevealed"
    },
    {
      "trait_type": "Collection",
      "value": "Your Project Name"
    }
  ]
}

// pages/api/mint.ts or app/api/mint/route.ts
// Built-in backend - no separate server needed!

const guards = {
  thirdPartySigner: {
    signerKey: backendSignerWallet.publicKey,
  },
  botTax: {
    lamports: sol(0.01), // Tax for failed attempts
    lastInstruction: true,
  },
  solPayment: {
    lamports: sol(0.1), // Mint price
    destination: treasuryWallet.publicKey,
  },
};

// pages/api/mint.ts (Pages Router) or app/api/mint/route.ts (App Router)
import type { NextApiRequest, NextApiResponse } from 'next';

export default async function handler(req: NextApiRequest, res: NextApiResponse) {
  if (req.method !== 'POST') {
    return res.status(405).json({ error: 'Method not allowed' });
  }

  try {
    // 1. Validate user (rate limiting, captcha, etc.)
    const { userWallet } = req.body;

    // 2. Generate mint transaction with required guards.
    // You may need to supply additional guard args from the front end.
    const mintTransaction = await mintV1(umi, {
      candyMachine: candyMachine.publicKey,
      asset: generateSigner(umi),
      minter: createNoopSigner(userWallet),
      mintArgs: {
        thirdPartySigner: {
          signer: backendSigner,
        },
      },
    }).buildWithLatestBlockhash(umi);;

    // 3. Partially sign with backend signer
    const signedTransaction = await backendSigner.signTransaction(mintTransaction);

    // 4. Return transaction for user to sign on front end
    res.json({
      transaction: base64.encode(signedTransaction.serialize()),
      asset: mintTransaction.asset.publicKey.toString(),
    });

  } catch (error) {
    res.status(500).json({ error: 'Mint failed' });
  }
}

// Traditional Express or serverless function
app.post('/api/mint', async (req, res) => {
  try {
    // 1. Validate user (rate limiting, captcha, etc.)
    const { userWallet, captchaToken } = req.body;

    // 2. Generate mint transaction with required guards
    const mintTransaction = await mintV1(umi, {
      candyMachine: candyMachine.publicKey,
      asset: generateSigner(umi),
      minter: createNoopSigner(userWallet),
      mintArgs: {
        thirdPartySigner: {
          signer: backendSigner,
        },
      },
    }).buildWithLatestBlockhash(umi);

    // 3. Partially sign with backend signer
    const signedTransaction = await backendSigner.signTransaction(mintTransaction);

    // 4. Return transaction for user to complete
    res.json({
      transaction: base64.encode(signedTransaction.serialize()),
      asset: mintTransaction.asset.publicKey.toString(),
    });

  } catch (error) {
    res.status(500).json({ error: 'Mint failed' });
  }
});

// Publish the complete mapping after reveal
const fullMappingData = {
  projectName: "Your Project",
  totalSupply: 4000,
  revealDate: "2024-01-20T15:30:00Z",
  mapping: secureMapping.map((finalIndex, mintIndex) => ({
    mintIndex,
    finalIndex,
    transactionId: uploadedUris[finalIndex].split('/').pop(),
    metadataUri: uploadedUris[finalIndex]
  })),
  masterHash: masterHash, // From pre-launch verification
  verificationInstructions: "Use the verification function below to check your asset"
};

// Publish to IPFS, your website, and community channels
await publishMapping(fullMappingData);

// Verification function users can run to verify their assets
function verifyAssetMapping(
  mintIndex: number,
  finalIndex: number,
  receivedMetadata: string,
  publishedHashes: string[]
): boolean {
  // 1. Hash the received metadata
  const metadataHash = crypto
    .createHash('sha256')
    .update(receivedMetadata)
    .digest('hex');

  // 2. Check against published hash
  const expectedHash = publishedHashes[finalIndex];

  // 3. Verify the mapping is correct
  return metadataHash === expectedHash;
}

// Usage example for users
const isValid = verifyAssetMapping(
  0, // Their mint index
  2847, // The revealed final index
  theirMetadataJson, // The metadata they received
  publishedMetadataHashes // The hashes published pre-mint
);

console.log(`Asset verification: ${isValid ? 'VALID' : 'INVALID'}`);

// Implement rate limiting per wallet
const mintAttempts = new Map<string, number>();

function checkRateLimit(wallet: string): boolean {
  const attempts = mintAttempts.get(wallet) || 0;
  return attempts < MAX_ATTEMPTS_PER_HOUR;
}

// Monitor for suspicious patterns
function detectSuspiciousActivity(requests: MintRequest[]): boolean {
  // Check for identical timing patterns
  // Detect rapid-fire requests from multiple wallets
  // Flag requests with identical metadata
  return false; // Implement your detection logic
}

// Implement rate limiting with express-rate-limit
import rateLimit from 'express-rate-limit';

const limiter = rateLimit({
  windowMs: 15 * 60 * 1000, // 15 minutes
  max: 5, // limit each IP to 5 requests per windowMs
});

// Use middleware for API routes
export default limiter(handler);