Operações de blockchain da cena

Aprenda o que o SDK oferece para realizar operações com a blockchain Ethereum

Uma scene do Decentraland pode se integrar com a blockchain Ethereum. Isso pode servir para obter dados sobre a wallet do usuário e os tokens nela, ou para acionar transações que podem envolver qualquer token Ethereum, fungível ou não fungível. Isso pode ser usado de várias formas, por exemplo para vender tokens, para recompensar tokens como parte de uma mecânica de jogo, para mudar como um player interage com uma scene se ele possuir certos tokens, etc.

Observe que todas as transações na mainnet Ethereum que forem acionadas por uma scene exigirão que o player aprove e pague uma taxa de gas.

Todas as operações de blockchain também precisam ser realizadas como funções assíncronas, já que o tempo depende de eventos externos.

Obtenha a conta ethereum de um player

Para obter a conta Ethereum de um player, use a getPlayer() function.

import { getPlayer } from "@dcl/sdk/src/players";

export function main() {
  let userData = getPlayer();
  if (!userData.isGuest) {
    console.log(userData.userId);
  } else {
    log("Player is not connected with Web3");
  }
}

Observe que, se um player entrou no Decentraland como guest, ele não terá uma wallet ethereum conectada. Se ele estiver conectado como guest, o isGuest campo na resposta de getPlayer() será true. Se hasConnectedWeb3 for true, então você pode obter o endereço do player no campo publicKey. Saiba mais sobre os dados que você pode obter de um player em get player data

Você deve envolver a function em uma async() function, saiba mais sobre isso em async functions

📔 Observação: Embora o endereço eth possa conter caracteres maiúsculos, alguns browsers convertem automaticamente a string retornada para minúsculas. Se você quiser comparar valores de endereço e fazer isso funcionar em todos os browsers, use o .toLowerCase() method para converter o valor para minúsculas.

Verificar o preço do gas

Depois de importar a eth-connect library, você deve instanciar um web3 provider e um request manager, o que permitirá que você se conecte via web3 ao Metamask no browser do player.

A function abaixo obtém o preço atual do gas na main network Ethereum e o imprime.

import { RequestManager } from "eth-connect";
import { createEthereumProvider } from "@dcl/sdk/ethereum-provider";

executeTask(async function () {
  // criar uma instância do web3 provider para se integrar com o Metamask
  const provider = createEthereumProvider();
  // Crie o objeto que irá lidar com o envio e o recebimento de mensagens RPC
  const requestManager = new RequestManager(provider);
  // Verifique o preço atual do gas na rede Ethereum
  const gasPrice = await requestManager.eth_gasPrice();
  // registrar resposta
  console.log({ gasPrice });
});

💡 Dica: Observe que as functions tratadas pelo requestManager devem ser chamadas usando await, já que dependem da obtenção de dados externos e podem levar algum tempo para serem concluídas.

Importar uma ABI de contract

Uma ABI (Application Binary Interface) descreve como interagir com um contract Ethereum, determinando quais functions estão disponíveis, quais inputs elas recebem e o que elas retornam. Cada contract Ethereum tem sua própria ABI; você deve importar as ABIs de todos os contracts que deseja usar no seu project.

Por exemplo, aqui está um exemplo de uma function na ABI da MANA:

{
  anonymous: false,
  inputs: [
    {
      indexed: true,
      name: 'burner',
      type: 'address'
    },
    {
      indexed: false,
      name: 'value',
      type: 'uint256'
    }
  ],
  name: 'Burn',
  type: 'event'
}

As definições da ABI podem ser bastante extensas, já que frequentemente incluem muitas functions, então recomendamos colar o conteúdo JSON de um arquivo ABI em um .ts arquivo separado e importá-lo para outros arquivos da scene a partir dele. Também recomendamos manter todos os arquivos ABI em uma pasta separada da sua scene, chamada /contracts.

import { abi } from "../contracts/mana";

Aqui estão links para diferentes contracts do Decentraland. Obtenha a ABI de cada contract clicando Export ABI e escolhendo JSON Format.

• MANA Token ABI

• Decentraland Marketplace

• LAND ABI

• Estate ABI

• AvatarNameRegistry ABI

• Catalyst ABI

Estes são os contracts das várias coleções de Wearables: (cada coleção foi emitida como um contract separado)

• ExclusiveMasksCollection ABI

• Halloween2019Collection ABI

• Halloween2019CollectionFactory ABI

• Xmas2019Collection ABI

• MCHCollection ABI

• CommunityContestCollection ABI

• DCLLaunchCollection ABI

• DCGCollection ABI

💡 Dica: Para ver claramente as functions expostas por um contract, abra-o em abitopic.io. Basta colar o endereço do contract lá e abrir a aba functions para ver a lista completa de functions suportadas e seus argumentos. Você pode até testar a chamada das functions com diferentes parâmetros pela webpage.

Configurar o TypeScript para conseguir importar de um arquivo JSON tem suas dificuldades. A solução alternativa mais fácil e recomendada é alterar a ABI.JSON extensão do arquivo para .ts e modificá-lo ligeiramente para que seu conteúdo comece com export default.

Por exemplo, se o conteúdo do arquivo ABI começa com [{"constant":true,"inputs":[{"internalType":"bytes4" ...etc, modifique-o para que comece com export default [{"constant":true,"inputs":[{"internalType":"bytes4" ...etc.

Instanciar um contract

Depois de importar a eth-connect library e a abide um contract, você deve instanciar vários objetos que permitirão usar as functions do contract e se conectar ao Metamask no browser do player.

Você também deve importar o web3 provider. Isso porque o Metamask no browser do player usa web3, então precisamos de uma forma de interagir com isso.

import { RequestManager, ContractFactory } from "eth-connect";
import { createEthereumProvider } from "@dcl/sdk/ethereum-provider";
import { abi } from "../contracts/mana";

executeTask(async () => {
  // criar uma instância do web3 provider para se integrar com o Metamask
  const provider = createEthereumProvider();
  // Crie o objeto que irá lidar com o envio e o recebimento de mensagens RPC
  const requestManager = new RequestManager(provider);
  // Crie um objeto factory com base na abi
  const factory = new ContractFactory(requestManager, abi);
  // Use o objeto factory para instanciar um objeto `contract`, referenciando um contract específico
  const contract = (await factory.at(
    "0x2a8fd99c19271f4f04b1b7b9c4f7cf264b626edb"
  )) as any;
});

💡 Dica: Para contracts que seguem o mesmo standard, como ERC20 ou ERC721, você pode importar uma única ABI genérica para todos. Em seguida, você gera um único ContractFactory object com essa ABI e usa esse mesmo factory para instanciar interfaces para cada contract.

Chamar os methods de um contract

Depois de criar um contract object, você pode facilmente chamar as functions definidas em sua ABI, passando os parâmetros de input especificados.

import { getPlayer } from "@dcl/sdk/src/players";
import { createEthereumProvider } from "@dcl/sdk/ethereum-provider";
import { RequestManager, ContractFactory } from "eth-connect";
import { abi } from "../contracts/mana";

executeTask(async () => {
  try {
    // Etapas de configuração explicadas na seção acima
    const provider = createEthereumProvider();
    const requestManager = new RequestManager(provider);
    const factory = new ContractFactory(requestManager, abi);
    const contract = (await factory.at(
      "0x2a8fd99c19271f4f04b1b7b9c4f7cf264b626edb"
    )) as any;
    let userData = getPlayer();
    if (userData.isGuest) {
      return;
    }

    // Executar uma function do contract
    const res = await contract.setBalance(
      "0xaFA48Fad27C7cAB28dC6E970E4BFda7F7c8D60Fb",
      100,
      {
        from: userData.userId,
      }
    );
    // Registrar resposta
    console.log(res);
  } catch (error: any) {
    console.log(error.toString());
  }
});

O exemplo acima usa a abi do contract MANA do Ropsten e transfere 100 fake MANA para a sua conta na rede de teste Ropsten.

Outras functions

A library eth-connect inclui vários outros helpers que você pode usar. Por exemplo, para:

• Obter um preço estimado de gas

• Obter o saldo de um endereço dado

• Obter um recibo de transaction

• Obter o número de transactions enviadas a partir de um endereço

• Converter entre vários formats, incluindo hexadecimal, binário, utf8, etc.

Usando a rede de teste Ethereum

Ao testar sua scene, para evitar transferir MANA real ou outras currencies, você pode usar a Ethereum Sepolia test network e transferir fake testnet MANA em vez disso.

Para usar a rede de teste, você deve configurar a extensão Metamask Chrome para usar a Sepolia test network em vez de Main network.

Você deve adquirir Sepolia Ether, que pode ser obtido gratuitamente em vários faucets externos como este.

💡 Dica: Para executar a transaction de transferir Sepolia MANA para sua wallet, você precisará pagar uma taxa de gas em Sepolia Ether.

Para visualizar sua scene usando a rede de teste, cole a seguinte URL em uma aba do browser. Isso abrirá a scene no desktop client do Decentraland:

decentraland://realm=http://127.0.0.1:8000&local-scene=true&debug=true&dclenv=zone&position=0,0

💡 Dica: Altere o parâmetro position para as coordinates da sua scene, para carregar diretamente na sua scene..

Quaisquer transactions que você aceitar enquanto visualiza a scene neste modo ocorrerão apenas na rede de teste e não afetarão o saldo de MANA na sua wallet real.

Se você precisar testar transactions na Polygon Testnet e precisar ter MANA nessa testnet, você precisará fazer swap de MANA para essa network depois de adquiri-lo na Sepolia. Para fazer bridge do Sepolia MANA para a Polygon Testnet, visite sua página da conta Decentraland na Sepolia e clique em ‘swap’ no lado Ethereum MANA.

Ao executar uma preview no legacy web client, de uma scene que usa uma das libraries ethereum, você deve abrir a preview em uma janela separada do browser, ter o Metamask aberto no seu browser e incluir manualmente a string &ENABLE_WEB3.

Enviar mensagens RPC personalizadas

Use a function sendAsync() para enviar mensagens via protocolo RPC.

import { sendAsync } from "~system/EthereumController";

// enviar uma mensagem
await sendAsync({
  id: 1,
  method: "myMethod",
  jsonParams: "{ myParam: myValue }",
});

Smart contracts do Decentraland

No link a seguir, você pode encontrar uma lista de smart contracts Etherum relevantes para o ecossistema Decentraland. A lista inclui os contracts na mainnet, bem como em outras redes de teste Ethereum.

contracts.decentraland.org