Carteira de Ciclos no ICP

Como foi discutido em Tokens and cycles, tokens ICP podem ser convertidos em ciclos para potencializar as operações canister. Os ciclos refletem o custo operacional de comunicação, computação e armazenamento que os dapps consomem. (Nota da tradutora: conceito de canister retirado da Internet Computer. Um canister é semelhante a um recipiente no sentido de que ambos são implantados como uma unidade de software que contém código compilado e dependências para uma aplicação ou serviço)

Ao contrário dos tokens ICP, os ciclos estão associados apenas a canisters e não a usuários ou desenvolvedores. Como somente os canisters requerem e consomem ciclos - para realizar operações e para pagar pelos recursos que utilizam - usuários e desenvolvedores gerenciam a distribuição e propriedade dos ciclos através de um tipo especial de canister chamado carteira de ciclos. Como a carteira de ciclos detém os ciclos necessários para realizar operações, como a criação de novos canisters, estas operações são executadas utilizando a entidade de canister para a carteira de ciclos em vez da entidade de seu usuário.

Com a finalidade de utilizar o ambiente local de execução do canister, o SDK cria automaticamente uma carteira de ciclos padrão para você em cada projeto e a maioria das operações realizadas utilizando a carteira de ciclos acontece nos bastidores. Por exemplo, a carteira de ciclos atua em seu nome para registrar as entidades dos canisters e distribuir canisters no ambiente local de execução de canisters.

Em um ambiente de produção, entretanto, é necessário registrar explicitamente e transferir ciclos para novas canisters, especificar as entidades que podem atuar como guardiões, e administrar as entidades com direitos de propriedade. Você pode realizar algumas destas tarefas usando o dapp de carteira de ciclos padrão executado em um navegador da web. Dependendo da ação específica que você deseja realizar, você também pode executar estas tarefas de gerenciamento de ciclos e canisters executando comandos de dfx wallet em um terminal ou chamando diretamente os processos do canister da carteira de ciclos padrão.

Você deve ter em mente, entretanto, que as chamadas para o canister da carteira de ciclos são executadas usando a entidade da carteira de ciclos associada à identidade do usuário atualmente selecionada. Dependendo de sua identidade atualmente selecionada e se a entidade associada a essa identidade foi adicionada como controlador ou guardião de uma carteira, você poderá ver resultados diferentes ou ser-lhe negado o acesso a um processo específico.

Para verificar a identidade que você está usando atualmente, execute o seguinte comando:

dfx identity whoami

Funções de Controlador e Guardião

Uma entidade usuário ou de canister pode ser designada a um papel de controlador ou guardião.

NOTA

O papel de controlador de que fala este documento NÃO é o mesmo papel de controlador normalmente destinado quando se fala do Internet Computer. Tipicamente, o controlador se refere a uma entidade que controla um canister. Aqui, um controlador tem um papel de carteira interno que por acaso tem o mesmo nome. Para uma diferenciação mais detalhada, veja o post neste forum.

Um controlador tem a função mais privilegiada e uma entidade designada para a função de controlador pode executar tarefas privilegiadas, incluindo as seguintes:

• Adicionar ou remover outras entidades como controladores.
• Autorizar ou desautorizar outras entidades como guardiões.
• Acrescentar entradas ao livro de endereços da carteira de ciclos.
• Acessar o saldo da carteira de ciclos e todas as outras informações relacionadas à carteira.
• Enviar ciclos para outros canisters.
• Aceitar o recebimento de ciclos de outros canisters.
• Renomear a carteira de ciclos.
• Criar canisters e carteiras de ciclos adicionais.

Uma entidade designada para a função de guardião só pode executar um subconjunto de tarefas de gerenciamento de carteira de ciclos, incluindo o seguinte:

• Acessar o saldo da carteira de ciclos e todas as outras informações relacionadas à carteira.
• Enviar ciclos para outros canisters.
• Aceitar o recebimento de ciclos de outros canisters.
• Criar canisters.

Autorizar uma entidade como guardião não concede automaticamente à entidade acesso a uma carteira de ciclos. A identidade atribuída à função de guardião também deve ser atribuída a uma entidade de carteira de ciclos. Por exemplo, se você autorizar a identidade alice_custodian como depositária de uma carteira de ciclos (rwlgt-iiaaa-aaaaa-aaaaa-cai) em um projeto local, esse usuário também precisará ser designado para usar essa carteira com o comando dfx identity set-wallet rwlgt-iiaaa-aaaaa-aaaaa-cai command.

Crie uma Carteira de Ciclos

Se você estiver fazendo desenvolvimento local, sua carteira de ciclos é criada quando você registra uma nova entidade de canister usando dfx canister create ou quando você registra, constrói e implanta um canister com dfx deploy.

Se você estiver implantando no Internet Computer, você normalmente cria sua carteira de ciclos convertendo os tokens ICP em ciclos, transferindo os ciclos para uma nova entidade de canister e atualizando o canister com o módulo padrão de WebAssembly da carteira de ciclos (WASM). Converter ICO em ciclos mostra como fazer isso

Existem dapps que podem ajudá-lo a converter ICP em ciclos e criar uma nova carteira de ciclos, por exemplo, NNS dapp.

Verifique o saldo do ciclo​

No ambiente de execução de canister local ou com uma carteira de ciclos no Internet Computer, você pode usar o comando dfx wallet balance ou o método wallet_balance para checar o saldo corrente do ciclo.

Verifique o saldo de seus ciclos ao desenvolver localmente

Se você estiver fazendo desenvolvimento local, você pode usar o comando dfx wallet balance para verificar o saldo dos ciclos atuais em uma base projeto a projeto.

Para verificar o saldo dos ciclos em um projeto local

1. Abra um terminal e navegue até o diretório raiz do projeto.

2. Inicie o ambiente local de execução do canister executando o seguinte comando:
   dfx start --background

3. Exiba o saldo dos ciclos da carteira de ciclos associados à identidade atualmente selecionada, executando o seguinte comando:
   dfx wallet balance

4. O comando exibe saída semelhante ao seguinte:
   78.000 TC (trilhões de ciclos).

Verifique o saldo dos ciclos no Internet Computer​

Se você implantou uma carteira de ciclos no Internet Computer, você pode usar o comando dfx wallet balance para verificar o saldo atual dos ciclos na rede.

Para verificar o saldo dos ciclos no Internet Computer:

1. Abra um terminal e navegue até um diretório que contenha um arquivo de configuração dfx.json.

2. Verifique sua conexão com o Internet Computer executando o seguinte comando:
   dfx ping ic

3. Exiba o saldo do ciclo da carteira de ciclos associada à identidade atualmente selecionada, executando o seguinte comando:

dfx wallet --network ic balance

1. O comando exibe saída semelhante ao seguinte: 67.992 TC (trilhões de ciclos).

Chame o método wallet_balance de ciclos

Você também pode verificar o saldo de ciclos chamando o método wallet_balance diretamente no canister da carteira de ciclos. Por exemplo, se o sua entidade é um controlador da carteira de ciclos h5aet-waaaa-aaaab-qaamq-cai cycles, você pode verificar o saldo do ciclo atual, executando o seguinte comando:

dfx canister --network ic call h5aet-waaaa-aaaab-qaamq-cai wallet_balance

O comando retorna o saldo no formato Candid como um arquivo com um campo valor (representado pelo hash 3_573_748_184) e um saldo de 6,895,656,625,450 ciclos como esse:

(record { 3_573_748_184 = 6_895_656_625_450 })

Outras Funções de Carteira suportada por dfx

A carteira de ciclos suporta muito mais funções por meio do dfx. Para uma lista completa das operações suportadas, veja a referência de carteira dfx.

Métodos Adicionais na Carteira de Ciclos Padrão

O canister da carteira de ciclos padrão inclui métodos adicionais que não são expostos como comandos de dfx wallet. Os métodos adicionais suportam tarefas mais avançadas de gerenciamento de ciclos, tais como a criação de novos canisters e o gerenciamento de eventos

Crie uma nova carteira de ciclos

Use o método wallet_create_wallet para criar um novo canister de carteira de ciclos com um saldo de ciclo inicial e, opcionalmente, com uma entidade específica como seu controlador. Se você não especificar uma entidade controladora, a carteira de ciclos que você usa para criar a nova carteira será o novo controlador da carteira.

Por exemplo, você pode executar um comando semelhante ao seguinte para criar uma nova carteira e designar uma entidade como controlador:

dfx canister --network  call f3yw6-7qaaa-aaaab-qaabq-cai wallet_create_wallet '(record { cycles = 5000000000000 : nat64; controller = principal "vpqee-nujda-46rtu-4noo7-qnxmb-zqs7g-5gvqf-4gy7t-vuprx-u2urx-gqe"})'

O comando retorna a entidade para a nova carteira:

(record { 1_313_628_723 = principal "dcxxq-jqaaa-aaaab-qaavq-cai" })

Registre uma nova entidade de canister

Use o método wallet_create_canister para registrar uma nova entidade de canister no Internet Computer. Este método cria um novo canister "vazio" com um saldo de ciclo inicial e, opcionalmente, com uma entidade específica como seu controlador. Após ter registrado a entidade do canister, você pode instalar o código para seu canister como uma etapa separada.

Por exemplo, você pode executar um comando semelhante ao seguinte para criar uma nova carteira e designar uma entidade como controladora:

dfx canister --network  call f3yw6-7qaaa-aaaab-qaabq-cai wallet_create_canister '(record { cycles = 5000000000000 : nat64; controller = principal "vpqee-nujda-46rtu-4noo7-qnxmb-zqs7g-5gvqf-4gy7t-vuprx-u2urx-gqe"})'

O comando retorna a entidade para o novo canister que você criou:

(record { 1_313_628_723 = principal "dxqg5-iyaaa-aaaab-qaawa-cai" })

Receba ciclos de um canister

Use o método wallet_receive como um ponto final para receber ciclos.

Encaminhe chamadas a partir de uma carteira

Use o método wallet_call para encaminhar chamadas usando a entidade da carteira de ciclos como chamada.

Gerencie os endereços

Use os seguintes métodos para gerenciar as entradas do catálogo de endereços:

• add_address: (address: AddressEntry) → ();
• remove_address: (address: principal) → ();

Gerenciar eventos

Use os seguintes métodos para recuperar informações de eventos e gráficos.

• get_events: (opt record { from: opt nat32; to: opt nat32; }) → (vec Event) query;
• get_chart: (opt record { count: opt nat32; precision: opt nat64; } ) → (vec record { nat64; nat64; }) query;

Por exemplo, você pode usar o método get_events para retornar canister_create e outros eventos, executando um comando semelhante ao seguinte:

dfx canister call <cycles-wallet-principal> get_events '(record {from = null; to = null})'

Se a carteira de ciclos (gastn-uqaaa-aaaae-aaafq-cai) é implantada na rede principal do Internet Computer, você pode executar um comando parecido com isso para retornar eventos:

dfx canister --network ic call gastn-uqaaa-aaaae-aaafq-cai get_events '(record {from = null; to = null})'

A saída do comando está no formato Candid semelhante ao seguinte:

(

 vec { record { 23_515 = 0; 1_191_829_844 = variant { 4_271_600_268 = record { 23_515 = principal "tsqwz-udeik-5migd-ehrev-pvoqv-szx2g-akh5s-fkyqc-zy6q7-snav6-uqe"; 1_224_700_491 = null; 1_269_754_742 = variant { 4_218_395_836 };} }; 2_781_795_542 = 1_621_456_688_636_513_683;}; record { 23_515 = 1; 1_191_829_844 = variant { 4_271_600_268 = record { 23_515 = principal "ejta3-neil3-qek6c-i7rdw-sxreh-lypfe-v6hjg-6so7x-5ugze-3iohr-2qe"; 1_224_700_491 = null; 1_269_754_742 = variant { 2_494_206_670 };} }; 2_781_795_542 = 1_621_461_468_638_569_551;}; record { 23_515 = 2; 1_191_829_844 = variant { 1_205_528_161 = record { 2_190_693_645 = 11_000_000_000_000; 2_631_180_839 = principal "gvvca-vyaaa-aaaae-aaaga-cai";} }; 2_781_795_542 = 1_621_462_573_993_647_258;}; record { 23_515 = 3; 1_191_829_844 = variant { 1_205_528_161 = record { 2_190_693_645 = 11_000_000_000_000; 2_631_180_839 = principal "gsueu-yaaaa-aaaae-aaagq-cai";} }; 2_781_795_542 = 1_621_462_579_193_578_440;}; record { 23_515 = 4; 1_191_829_844 = variant { 1_955_698_212 = record { 2_190_693_645 = 0; 2_374_371_241 = "install_code"; 2_631_180_839 = principal "aaaaa-aa";} }; 2_781_795_542 = 1_621_462_593_047_590_026;}; record { 23_515 = 5; 1_191_829_844 = variant { 1_955_698_212 = record { 2_190_693_645 = 0; 2_374_371_241 = "install_code"; 2_631_180_839 = principal "aaaaa-aa";} }; 2_781_795_542 = 1_621_462_605_779_157_885;}; record { 23_515 = 6; 1_191_829_844 = variant { 1_955_698_212 = record { 2_190_693_645 = 0; 2_374_371_241 = "authorize"; 2_631_180_839 = principal "gsueu-yaaaa-aaaae-aaagq-cai";} }; 2_781_795_542 = 1_621_462_609_036_146_536;}; record { 23_515 = 7; 1_191_829_844 = variant { 1_955_698_212 = record { 2_190_693_645 = 0; 2_374_371_241 = "greet"; 2_631_180_839 = principal "gvvca-vyaaa-aaaae-aaaga-cai";} }; 2_781_795_542 = 1_621_463_144_066_333_270;}; record { 23_515 = 8; 1_191_829_844 = variant { 4_271_600_268 = record { 23_515 = principal "ejta3-neil3-qek6c-i7rdw-sxreh-lypfe-v6hjg-6so7x-5ugze-3iohr-2qe"; 1_224_700_491 = null; 1_269_754_742 = variant { 2_494_206_670 };} }; 2_781_795_542 = 1_621_463_212_828_477_570;}; record { 23_515 = 9; 1_191_829_844 = variant { 1_955_698_212 = record { 2_190_693_645 = 0; 2_374_371_241 = "wallet_balance"; 2_631_180_839 = principal "gastn-uqaaa-aaaae-aaafq-cai";} }; 2_781_795_542 = 1_621_878_637_071_884_946;}; record { 23_515 = 10; 1_191_829_844 = variant { 4_271_600_268 = record { 23_515 = principal "b5quc-npdph-l6qp4-kur4u-oxljq-7uddl-vfdo6-x2uo5-6y4a6-4pt6v-7qe"; 1_224_700_491 = null; 1_269_754_742 = variant { 4_218_395_836 };} }; 2_781_795_542 = 1_621_879_473_916_547_313;}; record { 23_515 = 11; 1_191_829_844 = variant { 313_999_214 = record { 1_136_829_802 = principal "gastn-uqaaa-aaaae-aaafq-cai"; 3_573_748_184 = 10_000_000_000;} }; 2_781_795_542 = 1_621_977_470_023_492_664;}; record { 23_515 = 12; 1_191_829_844 = variant { 2_171_739_429 = record { 25_979 = principal "gastn-uqaaa-aaaae-aaafq-cai"; 3_573_748_184 = 10_000_000_000; 4_293_698_680 = 0;} }; 2_781_795_542 = 1_621_977_470_858_839_320;};},
)

Neste exemplo, há doze registros de eventos. O campo da Função (representado pelo hash 1_269_754_742) específica se a entidade é o controlador (representado pelo hash 4_218_395_836) ou o guardião (representado pelo hash 2_494_206_670). Os eventos nesse exemplo também ilustram um campo de valor (representado pelo hash 3_573_748_184) com uma transferência de 10,000,000,000 ciclos.

Este artigo é da Internet Computer, foi traduzido por Fátima Lima e seu original pode ser lido aqui.