Aceitar cycles a partir de uma carteira

Quando você estiver fazendo desenvolvimento local, você pode usar a carteira padrão em seu projeto para enviar e verificar seu saldo de cycles. Mas e os cânisters que precisam receber e usar esses cycles, por exemplo, para executar suas funções e fornecer serviços aos usuários? Este tutorial fornece um exemplo simples para ilustrar como você pode adicionar as funções para receber e verificar seu saldo de cycles em um programa modelo padrão.

Este exemplo consiste no seguinte:

A função wallet_balance permite verificar o saldo de cycles atual do cânister.

A função wallet_receive permite que o programa aceite os cycles que são enviados para o cânister.

A função greet aceita um argumento de texto e exibe uma saudação em um terminal.

A função owner retorna o conteúdo utilizado pelo autor da mensagem.

Antes de começar

Antes de iniciar o tutorial, verifique o seguinte:

Você baixou e instalou o pacote SDK como descrito em Baixar e instalar.

Você instalou o plug-in Visual Studio Code para Motoko como descrito em Instalar o plug-in do editor de idiomas se você estiver usando o Visual Studio Code como seu IDE.

Você interrompeu qualquer sistema local de execução de cânisters rodando no computador local.

Crie um novo projeto

Crie um novo diretório de projetos para testar o controle de acesso e a troca de identidades de usuários:

Abrir um terminal em seu computador local, se você ainda não tiver um aberto.

Mudar a pasta que você está usando para seus projetos de Internet Computer, se você estiver usando uma.

Crie um novo projeto executando o seguinte comando:

dfx new cycles_hello

Mude para seu diretório de projetos executando o seguinte comando:

cd cycles_hello

Modificar o programa padrão

Para este tutorial, você vai modificar o código fonte modelo para incluir novas funções de aceitação e verificação do saldo de cycles.

Para modificar o programa padrão:

Abra o arquivo src/cycles_hello/main.mo em um editor de texto e exclua o conteúdo existente.

Copie e cole este código no arquivo.

Vamos dar uma olhada em alguns elementos-chave deste programa:

O programa importa uma biblioteca base Motoko - ExperimentalCycles - que fornece funções básicas para trabalhar com cycles.

O programa utiliza uma actor class em vez de um único ator para que possa ter múltiplas instâncias de atores para aceitar diferentes quantidades de cycles, até uma capacity para todas as instâncias.

A capacity é passada como um argumento para a actor class.

O msg.caller identifica o usuário associado com a chamada.

Salve suas mudanças e feche o arquivo main.mo para continuar.

Iniciar o ambiente local de execução do cânister

Antes de construir o projeto access_hello, você precisa se conectar ao ambiente de execução de cânisters executado localmente em seu ambiente de desenvolvimento, ou você precisa se conectar a uma sub-rede que você possa acessar.

Para iniciar o ambiente local de execução de cânisters:

Abra uma nova janela de terminal ou uma aba em seu computador local.

Navegue até o diretório raiz de seu projeto, se necessário.

Inicie o ambiente local de execução de cânisters em sua máquina executando o seguinte comando:

dfx start --clean --background

Depois que o ambiente local de execução do cânister completar suas operações de inicialização, você pode continuar para o próximo passo.

Registrar, construir e implantar o dapp

Após a conexão com o ambiente local de execução do cânister, você pode registrar, construir e implantar seu dapp localmente.

Para implantar o dapp localmente:

Verifique se você ainda está no diretório raiz do seu projeto, se necessário.

Registre, construa e implante seu dapp, executando o seguinte comando:

dfx deploy --argument '(360000000000)'

Este exemplo define a capacity do cânister para 360.000.000.000 de cycles. A saída de comando dfx deploy então exibe informações sobre as operações que ele realiza, incluindo a identidade associada ao cânister de carteira criado para este projeto local e o identificador do cânister de carteira.

Por exemplo:

Deploying all canisters.
Creating canisters...
Creating canister "cycles_hello"...
Creating the canister using the wallet canister...
Creating a wallet canister on the local network.
The wallet canister on the "local" network for user "default" is "rwlgt-iiaaa-aaaaa-aaaaa-cai"
"cycles_hello" canister created with canister id: "rrkah-fqaaa-aaaaa-aaaaq-cai"
Creating canister "cycles_hello_assets"...
Creating the canister using the wallet canister...
"cycles_hello_assets" canister created with canister id: "ryjl3-tyaaa-aaaaa-aaaba-cai"
Building canisters...
Building frontend...
Installing canisters...
Installing code for canister cycles_hello, with canister_id rrkah-fqaaa-aaaaa-aaaaq-cai
Installing code for canister cycles_hello_assets, with canister_id ryjl3-tyaaa-aaaaa-aaaba-cai
Authorizing our identity (default) to the asset canister...
Uploading assets to asset canister...
Deployed canisters.

Teste o dapp

Depois de ter implantado o dapp em seu ambiente local de execução de cânisters, você pode experimentar as funções de carteira e testar seu programa usando os comandos dfx canister call.

Para testar o dapp:

Verifique o conteúdo para a identidade do usuário default executando o seguinte comando:

dfx canister call cycles_hello owner

O comando exibe resultados semelhantes aos seguintes para a identidade atual:

(principal "g3jww-sbmtm-gxsag-4mecu-72yc4-kef5v-euixq-og2kd-sav2v-p2sb3-pae")

Se você não fez mudanças na identidade que estava usando para executar o comando dfx deploy, você deve obter o mesmo conteúdo executando o comando dfx identity get-principal. Isto é importante porque você deve ser o proprietário do cânister da carteira para executar certas tarefas, tais como enviar cycles ou conceder permissão a outros guardiões de identidade para enviar cycles.

Verifique o saldo inicial de cycles da carteira executando o seguinte comando:

dfx canister call cycles_hello wallet_balance

Você não enviou nenhum cycle para o cânister, então o comando exibe o seguinte saldo:

(0)

Envie alguns cycles de seu cânister de carteira padrão para cânister cycles_hello utilizando o canister principal, executando um comando semelhante ao seguinte:

dfx canister call rwlgt-iiaaa-aaaaa-aaaaa-cai wallet_send '(record { canister = principal "rrkah-fqaaa-aaaaa-aaaaq-cai"; amount = (256000000000:nat64); } )'

Chame a função wallet_balance para ver que o cânister de cycles_hello tem o número de cycles que você transferiu, se você especificou uma quantidade sob a capacidade permitida, ou a capacity que você especificou quando você executou o comando dfx deploy.

dfx canister call cycles_hello wallet_balance

O comando exibe saída semelhante à seguinte:

(256_000_000_000)

Chame a função wallet_balance para ver o número de cycles em sua carteira padrão, executando um comando semelhante ao seguinte:

dfx canister call rwlgt-iiaaa-aaaaa-aaaaa-cai wallet_balance

O comando retorna o saldo para o identificador da carteira cânister que você especificou como um registro usando o formato Candidato. Por exemplo, o comando pode exibir um registro com um campo de amount (representado pelo hash 3_573_748_184) e um saldo de 97.738.624.621.042 cycles como este:

(record { 3_573_748_184 = 97_738_624_621_042 })

Para este simples tutorial, os cycles só são consumidos a partir do saldo no cânister padrão da carteira, não a partir do cânister de cycles_hello.

Chame a função greet executando um comando semelhante ao seguinte:

dfx canister call cycles_hello greet '("from DFINITY")'

Repita a chamada para a função wallet_balance para ver o número de cycles deduzidos de sua carteira padrão:

dfx canister call rwlgt-iiaaa-aaaaa-aaaaa-cai wallet_balance

Por exemplo, você pode ter um resultado semelhante a este:

(record { 3_573_748_184 = 97_638_622_179_500 })

Parar o ambiente local de execução de cânister

Depois de terminar de experimentar o programa, você pode parar o ambiente local de execução do cânister para que ele não continue funcionando em segundo plano.

Para parar o ambiente local de execução do cânister:

No terminal que exibe as operações, pressione Control-C para interromper o processo.

Pare o ambiente local de execução do cânister executando o seguinte comando:

dfx stop

Deseja saber mais?

Se você está procurando mais informações sobre como trabalhar com cycles, confira os seguintes recursos relacionados:

Tokens e cycles (visão geral)

dfx identity (referência de comando)

Gestão de cycles (referência linguística)

ExperimentalCycles (módulo base)

Este artigo foi escrito por Severin Siffert e traduzido para o português por Rafael Ojeda

Você pode ler o artigo original em inglês aqui