Como construir um portal de colecionáveis digitais usando fluxo e cadência (parte 1)

Neste tutorial, aprenderemos como construir um site para coleta de itens colecionáveis digitais (ou NFTs) no blockchain Flow. Usaremos a linguagem de contrato inteligente Cadence junto com React para fazer tudo acontecer. Também aprenderemos sobre o Flow, suas vantagens e as ferramentas divertidas que podemos usar. Ao final deste artigo, você terá as ferramentas e o conhecimento necessários para criar seu próprio aplicativo descentralizado no blockchain Flow. Vamos mergulhar de cabeça! O que estamos construindo? Estamos construindo um aplicativo para colecionáveis digitais. Cada colecionável é um Token Não Fungível (NFT). Nosso aplicativo permitirá que você colete NFTs, e cada item será único em relação aos demais. (Se você é novo e não entende de NFT, dê uma olhada aqui.) Para fazer tudo isso funcionar, usaremos o NonFungibleToken Standard do Flow, que é um conjunto de regras que nos ajuda a gerenciar esses itens digitais especiais (semelhante ao ERC-721 no Ethereum). Pré-requisitos Antes de começar, certifique-se de instalar o Flow CLI em seu sistema. Caso ainda não tenha feito isso, siga estas . instruções de instalação Configurando Se você estiver pronto para iniciar seu projeto, primeiro digite o comando flow setup. Este comando faz mágica nos bastidores para estabelecer a base do seu projeto. Ele cria um sistema de pastas e configura um arquivo chamado flow.json para configurar seu projeto, garantindo que tudo esteja organizado e pronto para uso! Estrutura do Projeto O projeto conterá uma pasta e um arquivo . (Um arquivo flow.json é um arquivo de configuração do seu projeto, mantido automaticamente.) A pasta Cadence contém o seguinte: cadence flow.json /contratos: Contém todos os contratos Cadence. /scripts: contém todos os scripts do Cadence. /transactions: Armazena todas as transações do Cadence. Siga as etapas abaixo para usar o Flow NFT Standard. Etapa 1: crie um arquivo. Primeiro, vá para a pasta e encontre a pasta . Em seguida, abra a pasta . Crie um novo arquivo e nomeie-o como . flow-collectibles-portal cadence contracts NonFungibleToken.cdc Etapa 2: copiar e colar. Agora, abra o link chamado que contém o padrão NFT. Copie todo o conteúdo desse arquivo e cole-o no novo arquivo que você acabou de criar ("NonFungibleToken.cdc"). NonFungibleToken É isso! Você configurou com sucesso os padrões para seu projeto. Agora, vamos escrever algum código! No entanto, antes de mergulharmos na codificação, é importante que os desenvolvedores estabeleçam um modelo mental de como estruturar seu código. No nível superior, nossa base de código consiste em três componentes principais: NFT: Cada colecionável é representado como um NFT. Coleção: Uma coleção refere-se a um grupo de NFTs de propriedade de um usuário específico. Funções e Variáveis Globais: São funções e variáveis definidas em nível global para o contrato inteligente e não estão associadas a nenhum recurso específico. Estrutura de contrato inteligente Estrutura Básica do Contrato Inteligente Crie um novo arquivo chamado dentro de . É aqui que escreveremos o código. Collectibles.cdc cadence/contracts Estrutura do Contrato import NonFungibleToken from "./NonFungibleToken.cdc" pub contract Collectibles: NonFungibleToken{ pub var totalSupply: UInt64 // other code will come here init(){ self.totalSupply = 0 } } Vamos dividir o código linha por linha: Primeiro, precisaremos padronizar que estamos construindo um NFT, incluindo o chamado “NonFungibleToken”. Este é um padrão NFT desenvolvido pela Flow que define o seguinte conjunto de funcionalidades que devem ser incluídas em cada contrato inteligente NFT. Após a importação, vamos criar nosso contrato. Para fazer isso, usamos . Use a mesma sintaxe sempre que criar um novo contrato. Você pode preencher o com o nome que desejar. No nosso caso, vamos chamá-lo . pub contract [contract name] contract name Collectibles Em seguida, queremos ter certeza de que nosso contrato segue um determinado conjunto de funcionalidades e regras do NonFungibleToken. Para fazer isso, adicionamos uma interface NonFungibleToken com a ajuda de `:`. Assim ( ) `pub contract Collectibles: NonFungibleToken{}` Cada contrato ter a função . É chamado quando o contrato é implantado inicialmente. Isso é semelhante ao que o Solidity chama de Construtor. DEVE init() Agora, vamos criar uma variável global chamada com tipo de dados . Esta variável acompanhará o total de seus itens colecionáveis. totalSupply UInt64 Agora, inicialize com valor . totalSupply 0 É isso! Estabelecemos a base para o nosso contrato . Agora podemos começar a adicionar mais recursos e funcionalidades para torná-lo ainda mais interessante. Collectibles Antes de prosseguir, verifique o trecho de código para entender como definimos variáveis no Cadence: Recurso NFT Adicione o seguinte código ao seu contrato inteligente: import NonFungibleToken from "./NonFungibleToken.cdc" pub contract Collectibles: NonFungibleToken{ // above code… pub resource NFT: NonFungibleToken.INFT{ pub let id: UInt64 pub var name: String pub var image: String init(_id:UInt64, _name:String, _image:String){ self.id = _id self.name = _name self.image = _image } } // init()... } Como você viu antes, o contrato implementa a interface padrão NFT, representada pelo . Da mesma forma, os recursos também podem implementar várias interfaces de recursos. pub contract Collectibles: NonFungibleToken Então, vamos adicionar a interface ao recurso NFT, que exige a existência de uma propriedade pública chamada id dentro do recurso. Aqui estão as variáveis que usaremos no recurso NFT: NonFungibleToken.INFT Mantém o ID do NFT id: Nome do NFT. name: URL da imagem do NFT. image: Depois de definir a variável, certifique-se de inicializá-la na função . init() Vamos seguir em frente e criar outro recurso chamado . Collection Resource Recurso de coleção Primeiro, você precisa entender como funcionam . Collection Resources Se você precisasse armazenar um arquivo de música e diversas fotos em seu laptop, o que você faria? Normalmente, você navegaria para uma unidade local (digamos, seu D-Drive) e criaria uma pasta e uma pasta . Em seguida, você copiaria e colaria os arquivos de música e fotos nas pastas de destino. Da mesma forma, é assim que funcionam seus itens colecionáveis digitais no Flow. music photos Imagine seu laptop como uma , seu D-Drive como e uma pasta como uma . Flow Blockchain Account Account Storage Collection Assim, ao interagir com qualquer projeto de compra de NFTs, o projeto cria sua no , semelhante à criação de uma pasta no seu D-Drive. Ao interagir com 10 projetos NFT diferentes, você terá 10 coleções diferentes em sua conta. collection account storage É como ter um espaço pessoal para armazenar e organizar seus tesouros digitais exclusivos! import NonFungibleToken from "./NonFungibleToken.cdc" pub contract Collectibles: NonFungibleToken{ //Above code NFT Resource… // Collection Resource pub resource Collection{ } // Below code… } Cada possui uma variável para armazenar os . collection ownedNFTs NFT Resources pub resource Collection { pub var ownedNFTs: @{UInt64: NonFungibleToken.NFT} init(){ self.ownedNFTs <- {} } } Interfaces de recursos Uma interface no Flow é semelhante às interfaces de outras linguagens de programação. Ele fica sobre um recurso e garante que o recurso que o implementa tenha a funcionalidade necessária conforme definido pela interface. resource Também pode ser usado para restringir o acesso a todo o recurso e ser mais restritivo em termos de modificadores de acesso do que o próprio recurso. No padrão , existem várias interfaces de recursos como , , e . NonFungibleToken INFT Provider Receiver CollectionPublic Cada uma dessas interfaces possui funções e campos específicos que precisam ser implementados pelo recurso que as utiliza. Neste contrato, usaremos essas três interfaces do , e . Essas interfaces definem funções como , , e . Explicaremos cada um deles em detalhes à medida que avançamos. NonFungibleToken: Provider Receiver CollectionPublic deposit withdraw borrowNFT getIDs Também adicionaremos alguns eventos que emitiremos a partir dessas funções, bem como declararemos algumas variáveis que usaremos mais adiante no tutorial. pub contract Collectibles:NonFungibleToken{ // rest of the code… pub event ContractInitialized() pub event Withdraw(id: UInt64, from: Address?) pub event Deposit(id: UInt64, to: Address?) pub let CollectionStoragePath: StoragePath pub let CollectionPublicPath: PublicPath pub resource interface CollectionPublic{ pub fun deposit(token: @NonFungibleToken.NFT) pub fun getIDs(): [UInt64] pub fun borrowNFT(id: UInt64): &NonFungibleToken.NFT } pub resource Collection: CollectionPublic, NonFungibleToken.Provider, NonFungibleToken.Receiver, NonFungibleToken.CollectionPublic{ pub var ownedNFTs: @{UInt64: NonFungibleToken.NFT} init(){ self.ownedNFTs <- {} } } } Retirar Agora, vamos criar a função exigida pela interface. withdraw() pub resource Collection: CollectionPublic, NonFungibleToken.Provider, NonFungibleToken.Receiver, NonFungibleToken.CollectionPublic{ // other code pub fun withdraw(withdrawID: UInt64): @NonFungibleToken.NFT { let token <- self.ownedNFTs.remove(key: withdrawID) ?? panic("missing NFT") emit Withdraw(id: token.id, from: self.owner?.address) return <- token } init()... } Com a ajuda desta função, você pode retirar o recurso NFT da coleção. Se isso: : entra em pânico e gera um erro. Falha : emite um evento de retirada e retorna o recurso ao chamador. Bem-sucedido O chamador pode então usar esse recurso e salvá-lo no armazenamento de sua conta. Depósito Agora é hora da função exigida por . deposit() NonFungibleToken.Receiver pub resource Collection: CollectionPublic, NonFungibleToken.Provider, NonFungibleToken.Receiver, NonFungibleToken.CollectionPublic{ // other code pub fun withdraw(withdrawID: UInt64): @NonFungibleToken.NFT { let token <- self.ownedNFTs.remove(key: withdrawID) ?? panic("missing NFT") emit Withdraw(id: token.id, from: self.owner?.address) return <- token } pub fun deposit(token: @NonFungibleToken.NFT) { let id = token.id let oldToken <- self.ownedNFTs[id] <-token destroy oldToken emit Deposit(id: id, to: self.owner?.address) } init()... } Emprestar e obter ID Agora, vamos nos concentrar nas duas funções exigidas por e . NonFungibleToken.CollectionPublic: borrowNFT() getID() pub resource Collection: CollectionPublic, NonFungibleToken.Provider, NonFungibleToken.Receiver, NonFungibleToken.CollectionPublic{ // other code pub fun withdraw(withdrawID: UInt64): @NonFungibleToken.NFT { let token <- self.ownedNFTs.remove(key: withdrawID) ?? panic("missing NFT") emit Withdraw(id: token.id, from: self.owner?.address) return <- token } pub fun deposit(token: @NonFungibleToken.NFT) { let id = token.id let oldToken <- self.ownedNFTs[id] <-token destroy oldToken emit Deposit(id: id, to: self.owner?.address) } pub fun borrowNFT(id: UInt64): &NonFungibleToken.NFT { if self.ownedNFTs[id] != nil { return (&self.ownedNFTs[id] as &NonFungibleToken.NFT?)! } panic("NFT not found in collection.") } pub fun getIDs(): [UInt64]{ return self.ownedNFTs.keys } init()... } Destruidor A última coisa que precisamos para o Collection Resource é um destruidor. destroy (){ destroy self.ownedNFTs } Como o recurso Collection contém outros recursos (recursos NFT), precisamos especificar um destruidor. Um destruidor é executado quando o objeto é destruído. Isso garante que os recursos não fiquem “sem abrigo” quando seu recurso pai for destruído. Não precisamos de um destruidor para o recurso NFT, pois ele não contém nenhum outro recurso. Vejamos o código-fonte completo do recurso de coleção: import NonFungibleToken from "./NonFungibleToken.cdc" pub contract Collectibles: NonFungibleToken{ pub var totalSupply: UInt64 pub resource NFT: NonFungibleToken.INFT{ pub let id: UInt64 pub var name: String pub var image: String init(_id:UInt64, _name:String, _image:String){ self.id = _id self.name = _name self.image = _image } } pub resource interface CollectionPublic{ pub fun deposit(token: @NonFungibleToken.NFT) pub fun getIDs(): [UInt64] pub fun borrowNFT(id: UInt64): &NonFungibleToken.NFT } pub event ContractInitialized() pub event Withdraw(id: UInt64, from: Address?) pub event Deposit(id: UInt64, to: Address?) pub let CollectionStoragePath: StoragePath pub let CollectionPublicPath: PublicPath pub resource Collection: CollectionPublic, NonFungibleToken.Provider, NonFungibleToken.Receiver, NonFungibleToken.CollectionPublic{ pub var ownedNFTs: @{UInt64: NonFungibleToken.NFT} init(){ self.ownedNFTs <- {} } destroy (){ destroy self.ownedNFTs } pub fun withdraw(withdrawID: UInt64): @NonFungibleToken.NFT { let token <- self.ownedNFTs.remove(key: withdrawID) ?? panic("missing NFT") emit Withdraw(id: token.id, from: self.owner?.address) return <- token } pub fun deposit(token: @NonFungibleToken.NFT) { let id = token.id let oldToken <- self.ownedNFTs[id] <-token destroy oldToken emit Deposit(id: id, to: self.owner?.address) } pub fun borrowNFT(id: UInt64): &NonFungibleToken.NFT { if self.ownedNFTs[id] != nil { return (&self.ownedNFTs[id] as &NonFungibleToken.NFT?)! } panic("NFT not found in collection.") } pub fun getIDs(): [UInt64]{ return self.ownedNFTs.keys } } init(){ self.CollectionPublicPath = /public/NFTCollection self.CollectionStoragePath = /storage/NFTCollection self.totalSupply = 0 emit ContractInitialized() } } Agora terminamos todos os recursos. A seguir, veremos a função global. Função Global Funções Globais são funções definidas no nível global do contrato inteligente, o que significa que não fazem parte de nenhum recurso. Eles são acessíveis e chamados pelo público e expõem ao público a funcionalidade central do contrato inteligente. : esta função inicializa um vazio no armazenamento da conta do chamador. createEmptyCollection Collectibles.Collection : esta função útil ajuda você a descobrir se sua conta já possui ou não um recurso . checkCollection collection : Essa função é super legal porque permite que qualquer pessoa crie um NFT. mintNFT // pub resource Collection… pub fun createEmptyCollection(): @Collection{ return (Collectibles.CollectionPublicPath)! .check() } pub fun mintNFT(name:String, image:String): @NFT{ Collectibles.totalSupply = Collectibles.totalSupply + 1 let nftId = Collectibles.totalSupply var newNFT <- create NFT(_id:nftId, _name:name, _image:image) return <- newNFT } init()... Concluindo o Contrato Inteligente E agora, FINALMENTE, com tudo pronto, terminamos de escrever nosso contrato inteligente. Dê uma olhada no código final . aqui Agora, vamos ver como um usuário interage com contratos inteligentes implantados no blockchain Flow. Existem duas etapas para interagir com o blockchain Flow: Altere o estado executando transações. Consulte o blockchain executando um script. Mude o estado executando transações As transações são dados assinados criptograficamente que contêm um conjunto de instruções que interagem com o contrato inteligente para atualizar o estado do Flow. Em termos simples, é como uma chamada de função que altera os dados no blockchain. As transações geralmente envolvem algum custo, que pode variar dependendo do blockchain em que você está. Uma transação inclui várias fases opcionais: , , e fase. prepare pre execute post . Cada fase tem um propósito; as duas fases mais importantes são e . Você pode ler mais sobre isso no documento de referência da Cadence sobre transações prepare execute : Esta fase é utilizada para acessar dados e informações dentro da conta do assinante (permitido pelo tipo AuthAccount). Prepare Phase : esta fase é usada para executar ações. Execute Phase Agora, vamos criar uma transação para nosso projeto. Siga as etapas abaixo para criar uma transação na pasta do seu projeto. Etapa 1: crie um arquivo. Primeiro, vá para a pasta do projeto e abra a pasta . Dentro dela, abra a pasta e crie um novo arquivo com os nomes e cadence transaction Create_Collection.cdc mint_nft.cdc Etapa 2: adicione o código de transação de criação de coleção. import Collectibles from "../contracts/Collectibles.cdc" transaction { prepare(signer: AuthAccount) { if signer.borrow (from: Collectibles.CollectionStoragePath) == nil { let collection (Collectibles.CollectionStoragePath) signer.capabilities.publish( cap, at: Collectibles.CollectionPublicPath) } } } Vamos dividir esse código linha por linha: Esta transação interage com o contrato inteligente de Colecionáveis. Em seguida, ele verifica se o remetente (signatário) possui um recurso Collection armazenado em sua conta, emprestando uma referência ao recurso Collection do caminho de armazenamento especificado . Se a referência for nula, significa que o signatário ainda não possui uma coleção. Collectibles.CollectionStoragePath Se o signatário não tiver uma coleção, ele criará uma coleção vazia chamando a função . createEmptyCollection() Depois de criar a coleção vazia, coloque-a na conta do signatário no caminho de armazenamento especificado . Collectibles.CollectionStoragePath Isso estabelece um link entre a conta do signatário e a coleção recém-criada usando . link() Etapa 3: adicione o código de transação Mint NFT. import NonFungibleToken from "../contracts/NonFungibleToken.cdc" import Collectibles from "../contracts/Collectibles.cdc" transaction(name:String, image:String){ let receiverCollectionRef: &{NonFungibleToken.CollectionPublic} prepare(signer:AuthAccount){ self.receiverCollectionRef = signer.borrow (from: Collectibles.CollectionStoragePath) ?? panic("could not borrow Collection reference") } execute{ let nft <- Collectibles.mintNFT(name:name, image:image) self.receiverCollectionRef.deposit(token: <-nft) } } Vamos dividir esse código linha por linha: Primeiro importamos o e Collectibles. Collectibles contract NonFungibleToken Esta linha define uma nova transação. São necessários dois argumentos, nome e imagem, ambos do tipo String. Esses argumentos são usados para passar o nome e a imagem do NFT que está sendo cunhado. transaction(name: String, image: String) Esta linha declara uma nova variável É uma referência a uma coleção pública de NFTs do tipo . Esta referência será utilizada para interagir com a coleção onde depositaremos o NFT recém-cunhado. let receiverCollectionRef: &{NonFungibleToken.CollectionPublic} receiverCollectionRef. NonFungibleToken.CollectionPublic Esta linha inicia o bloco de preparação, que é executado antes da transação. É necessário um assinante de argumento do tipo . representa a conta do signatário da transação. prepare(signer: AuthAccount) AuthAccount AuthAccount Ele empresta uma referência ao do armazenamento do signatário dentro do bloco de preparação. Ele usa a função de empréstimo para acessar a referência à coleção e armazená-la na variável . Collectibles.Collection receiverCollectionRef Se a referência não for encontrada (se a coleção não existir no armazenamento do signatário, por exemplo), será gerada a mensagem de erro “não foi possível emprestar a referência da coleção”. O bloco contém a lógica de execução principal da transação. O código dentro deste bloco será executado após a conclusão bem-sucedida do bloco . execute prepare Dentro do bloco , esta linha chama a função do contrato com os argumentos de nome e imagem fornecidos. Espera-se que esta função crie um novo NFT com o nome e imagem fornecidos. O símbolo indica que o NFT está sendo recebido como um objeto que pode ser movido (um recurso). nft <- Collectibles.mintNFT(_name: name, image: image) execute mintNFT Collectibles <- Esta linha deposita o NFT recém-criado na coleção especificada. Ele usa a função de depósito no para transferir a propriedade do NFT da conta de execução da transação para a coleção. O símbolo aqui também indica que o NFT está sendo movido como um recurso durante o processo . self.receiverCollectionRef.deposit(token: <-nft) receiverCollectionRef <- deposit Consulte o Blockchain executando um script Usamos um script para visualizar ou ler dados do blockchain. Os scripts são gratuitos e não precisam de assinatura. Siga as etapas abaixo para criar um script na pasta do seu projeto. Etapa 1: crie um arquivo. Primeiro, vá para a pasta do projeto e abra a pasta . Dentro dele, abra a pasta e crie um novo arquivo com o nome . cadence script view_nft.cdc Etapa 2: visualizar o script NFT import NonFungibleToken from "../contracts/NonFungibleToken.cdc" import Collectibles from "../contracts/Collectibles.cdc" pub fun main(user: Address, id: UInt64): &NonFungibleToken.NFT? { let collectionCap= getAccount(user).capabilities .get (/public/NFTCollection) ?? panic("This public capability does not exist.") let collectionRef = collectionCap.borrow()! return collectionRef.borrowNFT(id: id) } Vamos dividir esse código linha por linha: Primeiro, importamos o contrato e . NonFungibleToken Collectibles Esta linha define o ponto de entrada do script, que é uma função pública chamada main. A função leva dois parâmetros: pub fun main(acctAddress: Address, id: UInt64): &NonFungibleToken.NFT? : um parâmetro do tipo que representa o endereço de uma conta no blockchain Flow. acctAddress Address : um parâmetro do tipo que representa o identificador exclusivo do NFT na coleção. id UInt64 Em seguida, usamos para buscar o recurso para o especificado. Uma capacidade é uma referência a um recurso que permite acesso às suas funções e dados. Nesse caso, ele está buscando a capacidade para o tipo de recurso . getCapability Collectibles.Collection acctAddress Collectibles.Collection Em seguida, pegamos emprestado um NFT de usando a função . A função usa o parâmetro , que é o identificador exclusivo do NFT dentro da coleção. A função em um recurso permite a leitura dos dados do recurso. collectionRef borrowNFT borrowNFT id borrow Finalmente, retornamos o NFT da função. Etapa 3: implantação da rede de teste Agora é hora de implantar nosso contrato inteligente na testnet Flow. 1. Configure uma conta do Flow. Execute o seguinte comando no terminal para gerar uma conta Flow: flow keys generate Certifique-se de anotar sua chave pública e sua chave privada. A seguir, iremos para , crie um novo endereço com base em nossas chaves e financie nossa conta com alguns tokens de teste. Conclua as seguintes etapas para criar sua conta: a torneira de fluxo Cole sua chave pública no campo de entrada especificado. Mantenha os algoritmos de assinatura e hash definidos como padrão. Complete o Captcha. Clique em Criar conta. Depois de configurar uma conta, recebemos um diálogo com nosso novo endereço de Flow contendo 1.000 tokens de teste de Flow. . Copie o endereço para que possamos usá-lo daqui para frente 2. Configure o projeto. Agora vamos configurar nosso projeto. Inicialmente, quando montamos o projeto, ele criou um arquivo . flow.json Este é o arquivo de configuração do Flow CLI e define a configuração das ações que o Flow CLI pode executar para você. Pense nisso como aproximadamente equivalente a no Ethereum. hardhat.config.js Agora, abra seu editor de código e copie e cole o código abaixo em seu arquivo . flow.json { "contracts": { "Collectibles": "./cadence/contracts/Collectibles.cdc", "NonFungibleToken": { "source": "./cadence/contracts/NonFungibleToken.cdc", "aliases": { "testnet": "0x631e88ae7f1d7c20" } } }, "networks": { "testnet": "access.devnet.nodes.onflow.org:9000" }, "accounts": { "testnet-account": { "address": "ENTER YOUR ADDRESS FROM FAUCET HERE", "key": "ENTER YOUR GENERATED PRIVATE KEY HERE" } }, "deployments": { "testnet": { "testnet-account": [ "Collectibles" ] } } } Copiar e colar. Cole sua chave privada gerada no local (chave: “INSIRA SUA CHAVE PRIVADA GERADA AQUI”) no código. Executar. Agora, execute o código na testnet. Vá para o terminal e execute o seguinte código: flow project deploy --network testnet 5. Aguarde a confirmação. Após enviar a transação, você receberá um ID da transação. Aguarde a confirmação da transação na testnet, indicando que o contrato inteligente foi implantado com sucesso. Verifique seu contrato implantado . aqui Verifique o código completo no . GitHub Considerações Finais e Parabéns! Parabéns! Agora você construiu um portal de colecionáveis no blockchain Flow e o implantou na testnet. Qual é o próximo? Agora, você pode trabalhar na construção do frontend que abordaremos na parte 2 desta série. Tenha um ótimo dia! Também publicado aqui