Visão Geral

A gestão de coleções está no cerne do CreateKit. Este guia cobre tudo o que você precisa saber sobre a criação, configuração e gerenciamento de coleções NFT usando o protocolo BaseMint.

Estrutura de Metadados da Coleção

Cada coleção requer metadados específicos que definem suas características:

Parâmetros Obrigatórios

name
string
O nome da sua coleção NFT (ex.: “Bored Ape Yacht Club”)
symbol
string
O símbolo/ticker da sua coleção (ex.: “BAYC”)
creator
0x${string}
O endereço Ethereum do criador da coleção
gameOwner
0x${string}
O endereço Ethereum do proprietário do jogo (pode ser o mesmo que o criador)

Parâmetros Opcionais

maxSupply
bigint
default:"10000n"
Número máximo de tokens que podem ser cunhados
mintPrice
bigint
default:"0n"
Preço por token em wei (use parseEther() para valores em ETH)
maxPerWallet
bigint
default:"100n"
Máximo de tokens que podem ser cunhados por carteira
isWhitelistEnabled
boolean
default:"false"
Se a cunhagem apenas para whitelist está habilitada
startTime
bigint
default:"0n"
Timestamp Unix quando a cunhagem começa (0 = imediato)
endTime
bigint
default:"BigInt(Date.now() / 1000 + 86400 * 365 * 100)"
Timestamp Unix quando a cunhagem termina
tokenStandard
'ERC721' | 'ERC1155'
default:"'ERC721'"
O padrão de token a ser usado
chainId
number
default:"1993"
ID da cadeia (1993 = Testnet B3, 8333 = Mainnet B3)

Criando Coleções

Coleção Básica

Criação de Coleção Básica
import { CollectionManager, b3Testnet } from '@b3dotfun/basemint'
import { createPublicClient, createWalletClient, http } from 'viem'
import { privateKeyToAccount } from 'viem/accounts'

const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`)
const publicClient = createPublicClient({
  chain: b3Testnet,
  transport: http()
})

const walletClient = createWalletClient({
  chain: b3Testnet,
  transport: http(),
  account
})

const collectionManager = new CollectionManager(publicClient)

// Definir coleção básica
const basicCollection = {
  name: "Minha Coleção de Arte",
  symbol: "MAC",
  creator: account.address,
  gameOwner: account.address,
  description: "Uma coleção de peças de arte digital",
  image: "https://example.com/collection-image.png"
}

// Gerar assinatura do criador
const creatorSignature = await collectionManager.generateCreatorSignature(
  walletClient,
  basicCollection
)

Configuração Avançada da Coleção

Configuração Avançada da Coleção
import { parseEther } from 'viem'

const advancedCollection = {
  // Obrigatório
  name: "Itens de Jogo Premium",
  symbol: "PGI",
  creator: account.address,
  gameOwner: "0x1234567890123456789012345678901234567890", // Proprietário do jogo diferente
  
  // Suprimento e preço
  maxSupply: 5000n,
  mintPrice: parseEther("0.01"), // 0.01 ETH
  maxPerWallet: 5n,
  
  // Controles de tempo
  startTime: BigInt(Math.floor(Date.now() / 1000) + 3600), // Começa em 1 hora
  endTime: BigInt(Math.floor(Date.now() / 1000) + 86400 * 7), // Termina em 7 dias
  
  // Configuração de whitelist
  isWhitelistEnabled: true,
  whitelistMerkleRoot: "0x..." as `0x${string}`,
  
  // Metadados
  description: "Itens de jogo exclusivos para jogadores premium",
  image: "https://example.com/premium-collection.png",
  external_url: "https://mygame.com/premium-items",
  animation_url: "https://example.com/collection-animation.mp4",
  
  // Atributos da coleção
  attributes: [
    { trait_type: "Categoria", value: "Jogos" },
    { trait_type: "Raridade", value: "Premium" },
    { trait_type: "Edição", value: "Primeira" }
  ],
  
  // Técnico
  tokenStandard: "ERC1155" as const,
  chainId: 1993
}

Padrões de Token

CreateKit suporta ambos os padrões ERC721 e ERC1155:
const erc721Collection = {
  name: "Peças de Arte Únicas",
  symbol: "UAP",
  creator: account.address,
  gameOwner: account.address,
  tokenStandard: "ERC721" as const,
  maxSupply: 1000n, // Cada token é único
  description: "Peças de arte digital únicas"
}

// Cunhagem ERC721 (quantidade sempre 1)
const collection721 = collectionManager.createCollection(
  predictedAddress,
  "ERC721"
)

await collection721.mint(
  walletClient,
  1n, // Sempre 1 para ERC721
  undefined, // URI dos metadados
  mintPrice,
  proof
)

Gerenciamento de Metadados

Metadados no Nível da Coleção

Metadados da Coleção
const collectionMetadata = {
  name: "Minha Coleção",
  description: "Uma fantástica coleção de ativos digitais",
  image: "https://example.com/collection-image.png",
  external_url: "https://mywebsite.com/collection",
  
  // Cor de fundo e banner para marketplaces
  background_color: "ffffff",
  banner_image_url: "https://example.com/banner.png",
  
  // Atributos da coleção
  attributes: [
    { trait_type: "Tema", value: "Fantasia" },
    { trait_type: "Artista", value: "Criador Digital" }
  ]
}

Metadados no Nível do Token

CreateKit gera automaticamente metadados do token com base nas configurações da sua coleção:
import { NFTMetadataManager, MediaType } from '@b3dotfun/basemint'

// Gera metadados para diferentes tipos de mídia
const artworkMetadata = NFTMetadataManager.generateNFTMetadata(
  collectionMetadata,
  MediaType.ARTWORK
)

const model3dMetadata = NFTMetadataManager.generateNFTMetadata(
  collectionMetadata,
  MediaType.MODEL_3D
)

const videoMetadata = NFTMetadataManager.generateNFTMetadata(
  collectionMetadata,
  MediaType.VIDEO
)

// Converter para JSON
const metadataJson = NFTMetadataManager.generateJSON(artworkMetadata)
console.log(metadataJson)

Validação da Coleção

CreateKit fornece validação integrada para parâmetros da coleção:
Validação de Parâmetros
import { validateCollectionMetadata } from '@b3dotfun/basemint'

try {
  // Valida metadados da coleção
  const validation = validateCollectionMetadata(collectionMetadata)
  
  if (!validation.isValid) {
    console.error("Erros de validação:", validation.errors)
    return
  }
  
  console.log("✅ Metadados da coleção são válidos")
  
  // Prossiga com a geração da assinatura
  const signature = await collectionManager.generateCreatorSignature(
    walletClient,
    collectionMetadata
  )
} catch (error) {
  console.error("Validação falhou:", error)
}

Previsão de Endereço

Uma das principais funcionalidades do CreateKit é a previsão determinística de endereços:
Previsão de Endereço
// Gere a assinatura do criador primeiro
const creatorSignature = await collectionManager.generateCreatorSignature(
  walletClient,
  collectionMetadata
)

// Preveja o endereço da coleção
const predictedAddress = collectionManager.predictCollectionAddress(
  collectionMetadata,
  creatorSignature
)

console.log(`A coleção será implantada em: ${predictedAddress}`)

// Agora você pode usar este endereço antes da implantação
// para integração com marketplaces, exibição no frontend, etc.

Operações de Gerenciamento da Coleção

Verificando o Status da Coleção

Status da Coleção
const collection = collectionManager.createCollection(
  predictedAddress,
  "ERC721"
)

// Verifique se a coleção está implantada
const isDeployed = await collection.isDeployed()
console.log(`Implantada: ${isDeployed}`)

// Obtenha informações da coleção (só funciona após a implantação)
if (isDeployed) {
  const info = await collection.getCollectionInfo()
  console.log("Informações da Coleção:", {
    name: info.name,
    symbol: info.symbol,
    totalSupply: info.totalSupply.toString(),
    maxSupply: info.maxSupply.toString(),
    mintPrice: info.mintPrice.toString(),
    maxPerWallet: info.maxPerWallet.toString()
  })
}

Atualizando Configurações da Coleção

A maioria dos parâmetros da coleção não pode ser alterada após a implantação. Planeje a configuração da sua coleção com cuidado.
Gerenciamento Pós-Implantação
// Somente certas operações são possíveis após a implantação

// Verifique o preço atual da cunhagem (se a precificação dinâmica for implementada)
const currentPrice = await collection.getCurrentMintPrice()

// Verifique se a cunhagem está ativa no momento
const isMintingActive = await collection.isMintingActive()

// Obtenha o suprimento restante
const remainingSupply = await collection.getRemainingSupply()

console.log({
  currentPrice: currentPrice.toString(),
  isMintingActive,
  remainingSupply: remainingSupply.toString()
})

Melhores Práticas

1. Planejamento da Coleção

Estratégia de Suprimento

  • Defina o máximo de suprimento apropriado com base no caso de uso
  • Considere a demanda futura e a escassez
  • Deixe espaço para crescimento ou edições especiais

Estratégia de Preço

  • Pesquise coleções semelhantes para referência de preço
  • Considere os custos de gas e taxas de transação
  • Planeje para diferentes condições de mercado

2. Qualidade dos Metadados

Metadados de Alta Qualidade
const qualityCollection = {
  name: "Coleção de Arte Profissional",
  symbol: "PAC",
  creator: account.address,
  gameOwner: account.address,
  
  // Descrições de alta qualidade
  description: "Uma coleção selecionada de obras de arte digitais apresentando temas contemporâneos e técnicas inovadoras.",
  
  // Imagens profissionais (mínimo de 640x640px)
  image: "https://example.com/high-res-collection-image.png",
  
  // Atributos abrangentes para melhor descoberta
  attributes: [
    { trait_type: "Estilo de Arte", value: "Contemporâneo" },
    { trait_type: "Meio", value: "Digital" },
    { trait_type: "Verificação do Artista", value: "Verificado" },
    { trait_type: "Tipo de Edição", value: "Limitada" }
  ],
  
  // Links externos para credibilidade
  external_url: "https://professionalartist.com/collection"
}

3. Considerações de Segurança

Solução de Problemas

Próximos Passos

Agora que você entende a gestão de coleções, explore estes tópicos relacionados: