Dados e Computação Off-Chain com Funções Chainlink.

Neste guia, usaremos Funções Chainlink para executar JavaScript personalizado ealcançar dois resultados principais: dar ao nosso contrato inteligente acesso a uma API (Application Programming Interface ou Interface de Programação de Aplicativos) de xadrez para encontrar os dois melhores jogadores e suas classificações ELO¹ e, posteriormente, calcular suas novas classificações dependendo do resultado de uma partida futura. Usaremos o Dashboard para importar, interagir e implantar nossos contratos para simplificar o processo de começar com as Funções. Este exemplo demonstrará os dois enormes benefícios de usar Funções Chainlink em seus contratos inteligentes: chamadas de API com minimização de confiança e cálculos complexos off-chain ( fora da cadeia ) com os resultados postados on-chain ( dentro da cadeia ), reduzindo assim as taxas de gas.

As Funções Chainlink permitem que os usuários solicitem dados de quase qualquer API e realizem cálculos personalizados usando JavaScript de maneira descentralizada e com minimização de confiança, utilizando uma rede oráculo descentralizada Chainlink (DON). Ao usar o thirdweb para implantar, gerenciar e interagir com seus contratos, as Funções Chainlink se tornam simples de usar!

O código-fonte para este guia pode ser encontrado aqui!

Por que as Funções Chainlink são necessárias?

As Funções Chainlink permitem que os usuários obtenham cálculos off-chain descentralizados on-chain para uso em aplicativos descentralizados. Isso é útil por duas razões:

cálculos complexos são caros quando executados on-chain.

Obter dados do mundo real, dados off-chain, que podem ser sujeitos a manipulação maliciosa.

As Funções Chainlink resolvem esses dois problemas utilizando uma rede oráculo descentralizada para executar qualquer JavaScript personalizado definido pelo usuário. Isso significa que os usuários podem chamar APIs externas e obter os resultados sem correr o risco do resultado ser manipulado e, em seguida, realizar cálculos e processamentos complexos nos dados retornados off-chain, com o resultado sendo verificado, agregado e retornado on-chain para uso em contratos inteligentes.

Existem muitos casos de uso de exemplo para as Funções Chainlink, como:

Jogos Web3: realizar cálculos complexos, como calcular uma classificação ELO.

Chamando uma API: obter estatísticas do jogo, metadados de NFT, obtenção de dados para a digitalização de ativos do mundo real.

Verificação on-chain.

Whitelisting com base em certas condições personalizadas.

Cálculos de função de preços complexos.

Como Funciona?

Quando uma solicitação é enviada de um contrato consumidor, cada nó na rede oráculo descentralizada executa simultaneamente o JavaScript personalizado (por exemplo, uma chamada de API). O OCR da Chainlink é usado para agregar os resultados e chegar a um consenso. O resultado é retornado ao contrato inteligente solicitante por meio de uma função de retorno de chamada, onde cálculos extras podem ser executados juntamente com a solicitação retornada.

Para não expor as chaves de API usadas para autenticação, as Funções Chainlink também permitem que os usuários compartilhem segredos criptografados com cada nó na rede oráculo descentralizada. Isso permite que os usuários acessem APIs que exigem autenticação sem expor publicamente suas chaves

Como Construir Funções em seu Contrato Inteligente?

💡 As Funções Chainlink usam o método de Assinatura para financiar e gerenciar contratos consumidores. Isso segue o mesmo formato das assinaturas do Chainlink VRF - detalhes podem ser encontrados aqui.

Para usar as Funções Chainlink, seguiremos alguns passos:

• Criar um contrato consumidor.
• Importar o Registro de Faturamento de Funções para nosso Painel para criar e gerenciar assinaturas que são usadas para financiar e gerenciar seus contratos consumidores.
• Importar o contrato do Token Link para financiar suas assinaturas.
• Usar o Painel para criar solicitações e ler a solicitação retornada.

Criar um Contrato Consumidor de Funções

Para usar as Funções Chainlink, primeiro você precisa criar um contrato consumidor. Um contrato consumidor é um contrato compatível com as Funções: ele segue a interface de Funções e é o contrato que faz uma solicitação de Funções à DON. Isso é feito importando a interface e incluindo implementações das seguintes funções:

• executeRequest: faz a solicitação e atualiza latestResponse e latestError para que os valores possam ser acessados.
• fulfillRequest: callback (chamada de retorno) invocado assim que a DON resolveu a solicitação ou encontrou um erro. Funcionalidades extras podem ser adicionadas aqui que serão executadas quando a solicitação for retornada.

Uma solicitação simples pode ser iniciada usando este exemplo de contrato inteligente. Crie uma versão local deste repositório executando o seguinte:

npx thirdweb create --template thirdweb-chainlink-functions

Isso irá criar um diretório chamado chainlink-functions, no qual você precisará navegar. Abra o arquivo contracts/FunctionsConsumer.sol

Dentro deste arquivo, você será capaz de ver as implementações das funções mencionadas anteriormente. Também adicionamos algumas funcionalidades para decodificar a solicitação. Estamos esperando um retorno de classificação, que será um número, então decodificaremos a resposta como um uint256.

/**
   * @notice Callback that is invoked once the DON has resolved the request or hit an error
   *
   * @param requestId The request ID, returned by sendRequest()
   * @param response Aggregated response from the user code
   * @param err Aggregated error from the user code or from the execution pipeline
   * Either response or error parameter will be set, but never both
   */
  function fulfillRequest(
    bytes32 requestId,
    bytes memory response,
    bytes memory err
  ) internal override {
    latestResponse = abi.decode(response, (uint256));
    latestError = err;
    emit OCRResponse(requestId, response, err);
  }

Para implantar seu contrato, execute o seguinte:

npx thirdweb deploy

Isso irá construir o contrato e pedir que você selecione o contrato.

FunctionsConsumer

Isso abrirá uma janela do navegador pedindo que você preencha o(s) parâmetro(s) do contrato. Você precisará colar o endereço do oracle correspondente à rede em que está trabalhando. Para este exemplo, estaremos trabalhando no teste do Polygon Mumbai, então o endereço do oracle será:

• 0xeA6721aC65BCeD841B8ec3fc5fEdeA6141a0aDE4

Chainlink também suporta o Sepolia Ethereum testnet. Uma lista completa de redes suportadas e seus endereços correspondentes podem ser encontrados no README do repositório do GitHub.

Você pode modificar esse valor posteriormente chamando a função updateOracleAddress no seu contrato do consumidor no Dashboard da Chainlink.

Importando Contratos Necessários

Um Subscription Manager é usado para criar um Subscription Id para gerenciar e financiar o contrato do consumidor. Este método segue o mesmo formato do Chainlink VRF. Atualmente, não há um front-end (interface gráfica) para executar essas ações, mas usando o Dashboard da thirdweb, isso é simples.

Em primeiro lugar, importe o contrato FunctionsBillingRegistry correspondente à rede em que deseja trabalhar. Uma lista pode ser encontrada aqui. Basta colar o endereço do contrato na barra de pesquisa no topo da página inicial do seu Dashboard e clicar em Add to your Dashboard, localizado ao lado do endereço do contrato. Isso permite que você acesse este contrato posteriormente, selecionando-o em seus contratos na guia Contratos.

Em segundo lugar, importe o contrato linkToken usando o mesmo método. Isso permite que você use a função transferAndCall para financiar sua assinatura com LINK para permitir que você faça chamadas para a DON.

Como estamos trabalhando no testnet de Mumbai, os endereços do contrato serão os seguintes:

• FunctionsBillingRegistry: 0xEe9Bf52E5Ea228404bB54BCFbbDa8c21131b9039
• linkToken: 0x326C977E6efc84E512bB9C30f76E30c160eD06FB

Criando uma assinatura

Para criar uma assinatura, na aba Explorer, dentro da sub-aba Write Functions, chame a função createSubscription.

Assim que você confirmar a transação e ela for executada, vá para a guia Events. Abra o evento SubscriptionCreated e copie o ID da assinatura.

Você usará esta assinatura para registrar seu contrato de consumidor e financiar suas solicitações com LINK.

Financie sua assinatura

Primeiramente, você precisará obter alguns LINK, no nosso caso o LINK da Polygon Mumbai, que você pode obter nesta faucet (torneira).

Vá para o contrato do token LINK que você importou e clique na função de escrita transferAndCall. Esta função enviará o LINK para o Registro de Faturamento. O parâmetro Data permitirá que você use calldata para especificar o ID da assinatura para enviar o LINK (codificado em HEX). Preencha os parâmetros da seguinte forma:

• Para: o endereço do Registro de Faturamento das Funções
• Valor: a quantidade de LINK em JUELS, por exemplo, 5 LINK seria 5000000000000000000 *Dados: o ID da assinatura convertido em HEX, por exemplo, o ID da assinatura 25.

Para converter seu ID de assinatura, você precisará codificá-lo com ABI ( Interface Binária de Aplicativo Application Binary Interface ou Interface Binária de Aplicativo ). Para fazer isso, usaremos o Foundry, portanto, certifique-se de tê-lo instalado. O Foundry vem com uma ferramenta chamada Cast, que usaremos para codificar os dados. No seu terminal, execute o seguinte comando:

cast abi-encode "f(uint256)" <your-subscription-id>

Uma explicação sobre a codificação de ABI usando o Cast pode ser encontrada aqui.

Cole a saída deste comando na entrada Data juntamente com os campos To e Value. Essas entradas devem parecer algo assim:

Execute esta transação e sua assinatura terá sido financiada com 5 LINK prontos para realizar solicitações!

Adicione seu Contrato de Consumidor à sua Assinatura
Seu contrato de consumidor que você implantou precisa ser adicionado ao ID de assinatura que você criou para que as solicitações possam ser feitas ao DON. Acesse o contrato de Registro de Faturamento das Funções e selecione a função de escrita addConsumer.

Preencha seu ID de assinatura e o endereço do contrato de consumidor e clique em Execute. Assim que a transação for assinada e executada, seu contrato de consumidor estará pronto para enviar solicitações!

Exemplo de Classificação ELO

Para enviar uma solicitação, primeiro precisamos escrever algum código JavaScript que será executado pelo DON. Como exemplo de caso de uso para as Funções Chainlink, faremos uso de dois benefícios: chamadas de API descentralizadas e computação off-chain verificada e publicada on-chain.

Como exemplo, calcularemos a nova classificação ELO de dois dos principais jogadores de xadrez com base em quem ganha o jogo subsequente. Se você quiser saber mais sobre as classificações ELO e como implementá-las em seus próprios jogos, este é um ótimo artigo.

Primeiro, chamaremos uma API de xadrez para obter os dois melhores jogadores do leaderboard. Em seguida, faremos outra solicitação de API para obter suas respectivas classificações ELO. Finalmente, calcularemos suas novas classificações ELO, dependendo de quem ganhar uma partida subsequente.

Abra o arquivo scripts/functions.js do modelo clonado para visualizar o código JavaScript que executaremos usando Funções. Há dois pontos principais a serem observados:

• Para realizar solicitações HTTP, use a função Functions.makeHttpRequest da biblioteca de funções expostas. Por padrão, isso é uma solicitação GET, mas pode ser configurado para executar outros métodos. Os detalhes dos parâmetros podem ser encontrados aqui.

• Para retornar valores JavaScript na cadeia, eles precisam ser convertidos em Buffers, que representam os bytes que são retornados on-chain: Functions.encodeUint256(x), Functions.encodeInt256(x) e Functions.encodeString(x). Essas funções retornam um Buffer de 32 bytes representando x como um tipo de solidity, uint256, int256 e string solidity, respectivamente.

• Argumentos podem ser usados ​​opcionalmente para definir parâmetros modificáveis. Usaremos argumentos para definir o índice do jogador que gostaríamos de visualizar a classificação (0 para o jogador principal ou 1 para o segundo jogador) e se o jogador venceu ou perdeu (com 1 representando vitória e 0 representando derrota). Os argumentos podem ser acessados ​​por args[index] em seu JavaScript.

Realizando a solicitação

Para realizar o pedido, dirija-se ao painel de controle do contrato do consumidor e selecione a função de escrita do executeRequest. Preencha os parâmetros da seguinte forma:

• Origem: Cole seu JavaScript aqui, por exemplo, o código dentro de scripts/functions.js

• Segredos: Isso pode fornecer opcionalmente ao DON um objeto secreto, como uma chave de API criptografada. Usaremos o valor 0x para indicar nenhum segredo.

• Localização dos segredos: definida como 1 se os segredos estiverem armazenados remotamente ou 0 se armazenados online.

• Argumentos: uma matriz de string de formato JSON de argumentos. Para nosso exemplo, usaremos ["0", "1"] para ler a classificação do jogador superior (o primeiro argumento, 1 para o segundo jogador) se eles venceram (o segundo argumento).

• ID da assinatura: o ID da assinatura que você copiou anteriormente.

• Limite de gas: o limite de gás de retorno de chamada. Vamos definir isso como 100000.

Execute esta solicitação, certificando-se de definir um limite de gas manual dentro da sua carteira, por exemplo, a MetaMask, para 500,000, pois esta transação requer mais gas do que o valor padrão; caso contrário, sua transação será revertida. Isso iniciará a solicitação e enviará a solicitação ao DON. Cada nó executará o código fonte simultaneamente antes de chegar a um consenso sobre os resultados. Finalmente, o resultado médio é retornado ao contrato do consumidor por meio da função de retorno de chamada fulfillRequest. Esse processo levará alguns segundos.

Para verificar se o resultado foi retornado, acesse a guia Events, onde você deverá poder ver um evento RequestSent e subsequentes eventos OCRResponse e RequestFulfilled assim que a resposta for retornada.

Para visualizar o resultado da solicitação, selecione a função de leitura lastestResponse, permitindo que você obtenha a nova classificação do jogador. Agora, você pode usar esses dados em seus projetos e facilmente criar funções Chainlink em um front-end usando nosso React SDK. Por exemplo, você poderia criar um NFT com a classificação como uma propriedade nos metadados para uso como um ativo em jogo.

Parabéns - você obteve com sucesso dados descentralizados off-chain e computação on-chain de forma confiável usando as funções do Chainlink!

Considerações finais

O código fonte completo pode ser encontrado neste repositório GitHub.

Se você deseja saber mais sobre como usar as Funções Chainlink, incluindo como usar segredos, verifique este Repositório de Exemplos Chainlink para obter mais detalhes.

Se você deseja aprender mais sobre o desenvolvimento Web3, visite nossos documentos para desenvolvedores, ou se você tiver alguma dúvida, verifique o Discord da thirdweb , onde você pode falar diretamente com alguém da equipe. Alternativamente, você pode se juntar ao Discord da Chainlink para aprender mais sobre as funções Chainlink.

¹ A classificação Elo é um sistema de pontuação utilizado para calcular as habilidades relativas de jogadores de xadrez (ou outros jogos similares). Foi criado por Arpad Elo e é usado amplamente em competições de xadrez e em outras modalidades de jogos de tabuleiro. O sistema funciona atribuindo uma pontuação a cada jogador, baseada em sua performance em partidas anteriores, bem como na pontuação dos oponentes que ele enfrentou. A pontuação Elo de um jogador pode ser utilizada para prever o resultado de uma partida contra outro jogador com pontuação Elo conhecida. A diferença entre as pontuações Elo dos dois jogadores é utilizada para calcular as probabilidades de vitória, empate ou derrota para cada jogador. A classificação Elo é atualizada após cada partida, de acordo com o resultado e a pontuação dos oponentes envolvidos. O sistema é utilizado em muitos outros jogos, como tênis, futebol, jogos de cartas e videogames.

Este artigo foi escrito por Ciara Nightingale e traduzido para o português por Rafael Ojeda

Você pode encontrar o artigo original em inglês [aqui][(https://blog.thirdweb.com/guides/chainlink-functions/)