Tutorial de PDA em programa Solana com Rust e Anchor

Quando estamos começando a estudar desenvolvimento de programas para a blockchain Solana, uma das primeiras coisas que temos de entender é sobre Accounts. Resumidamente accounts são carteiras na blockchain (par de chaves) que podem conter dados ou um programa executável. Isso porque a arquitetura da Solana separa essas duas responsabilidades. Não obstante, as accounts precisam ser inicializadas e na sua inicialização o seu espaço total precisa ser definido. E aí começam os problemas.

Problema #1: quanto de espaço meu programa vai precisar?

No exemplo do tutorial anterior, de CRUD de livros, eu aloquei espaço para um cálculo aproximado de 50 livros. Mas e se eu quisesse ter milhares de livros? Teoricamente era só ajustar o espaço de acordo, mas lembre-se que a Solana possui o conceito de rent/aluguel, logo, quanto mais espaço você inicializar na sua account, mais caro vai se tornar para colocar seu programa na blockchain.

Problema #2: quanto de espaço uma account suporta?

Ainda que você tenha recursos para alocar quantidades imensas de espaço, temos problemas ligados à capacidade das accounts. Uma account jamais pode consumir mais de ~10MB de espaço na blockchain. Ou seja, mesmo que dinheiro não seja um problema na inicialização do projeto, vai acabar esbarrando neste outro limit e se a sua account chegar nele, simplesmente o programa não vai conseguir salvar mais dados, gerando erros constantes.

Em virtude disso, em programas onde se deseje adicionar dados indefinidamente, como um CRUD para todos os livros que existem e que ainda vão existir, faz-se necessário mudar de estratégia. Ao invés de um imenso vetor de livros, a estratégia mais profissional (e correta) é um vetor de accounts. Assim, cada livro terá o seu próprio endereço na blockchain, todos indexados na account principal do programa, usando um conceito chamado PDA ou Program Derived Address, que falaremos neste tutorial.

Vamos lá!

#1 – Setup do Projeto

Vou partir do pressuposto que você já está habituado a criar projetos Solana com Anchor e que talvez até já tenha feito meu tutorial anterior de CRUD de livros pois esse aqui é um estudo derivado. Digamos então que você tenha a seguinte estrutura para livros no lib.rs:

Nada demais, certo? O id dos livros será autoincremental, definido a partir de outra estrutura que guarda metadados da biblioteca, como abaixo.

Assim, sempre que a gente for cadastrar um novo livro, podemos usar o next_id da library para gerar um novo.

Como toda account, a Library precisa ser inicializada, enquanto que Book somente será usado mais tarde, quando adicionarmos livros. Então abaixo segue a struct para o contexto da função initialize e a dito-cuja.

O InitializeContext diz respeito somente à library, que como tem apenas um u32 como propriedade, precisa apenas 8+4 bytes de espaço (8 é para o descritor da account). Sendo um contexto de criação de account, temos ainda o user que vai pagar o rent e o programa de sistema que fará a criação. Já a função initialize apenas inicializa o next_id como 1.

Mas e aqueles seeds e bump ali? Eles são Constraint Seeds, um conceito diretamente relacionado à PDA. Resumidamente eles ditam as regras para o endereço válido da account de library e vou entrar mais detalhes a seguir, mas hora, repare que nossa seed é fixa, a string “library” em bytes (b). Pense nisso em termos de hashing: a mesma palavra sempre trará a mesma saída, certo? Assim, com essa constraint fixa, eu garanto que nosso programa terá somente uma account de library, para todo o sempre, o que chamamos de PDA Singleton. Em situações que queremos permitir várias accounts, podemos ter Constraint Seeds dinâmicos (como faremos logo mais) ou nem usar Constraint Seeds, mas neste último caso apenas útil para situações em que o estado realmente não importa.

Em nossos testes, teremos uma etapa preparatória como abaixo.

Aqui carregamos o provider (nó local de Solana), a carteira default do usuário, o programa que construímos e calculamos o endereço fixo da account library que nosso programa usa. Antes de cada teste, chamamos a initialize para alocar o espaço da account library na blockchain. Como cada teste tem de ser independente e estamos usando um endereço único, teremos uma função de limpeza mais à frente, para evitar colisões.

Mas onde entra PDA nisso?

#2 – Introdução a PDA

Quando queremos adicionar dados indefinidamente precisamos aprender a gerar accounts indefinidamente, pensando nelas como “caixinhas” para guardar os dados individualmente. Quer guardar três livros? Vai precisar de três accounts com o espaço de um book cada.

Mas se cada account tem o seu próprio endereço na blockchain, como saber quais accounts são de quais programas? Aí que entram os endereços derivados do programa, ou PDAs (Program Derived Address). Através de um algoritmo determinístico que nós vamos disparar usando seeds definidas pela gente, serão gerados endereços para cada livro que vamos adicionar no programa, de modo que depois consigamos acessar esses endereços sem precisar tomar nota de todos eles, usando apenas o id do livro como referência. No entanto, existem algumas diferenças da geração de accounts PDA de accounts comuns.

A primeira delas é que accounts comuns possuem par de chaves (keypair), ou seja, podem assinar transações, enquanto que PDAs não. PDAs servem apenas para guardar dados mesmo, como se fossem contas “burras”. A segunda diferença é que os endereços PDAs não podem colidir com endereços de accounts comuns e aí entra um outro conceito chamado “bump”, que combinados com as “seeds” vão gerar endereços únicos. Falarei mais a seguir, mas antes disso, vamos dar uma olhada no tipo do contexto de adição de livros.

Primeiro, temos a account de Library, necessária pois usamos o next_id  dela e vamos incrementar o mesmo após a adição (motivo dela ser mut/mutável). Repare que usamos aqui a mesma constraint seed da inicicialização, o que garante que estamos falando sempre da mesma library.

Segundo, temos a account de book, que terá de ser inicializada (init) na adição, como o payer sendo o user (Signer), o space sendo calculado com base nos campos de Book e finalmente as seeds que serão usadas na geração dos endereços e a sinalização do uso de bump.

Sobre as seeds, estamos usando três binários como seeds (quanto mais, mais forte, mas mais custo computacional a cada cadastro de livro):

• b”book”: isso quer dizer para pegar os bytes da palavra book (igual fizemos com library);
• library.key().as_ref(): isso quer dizer para pegar os bytes do endereço da account library;
• &library.next_id.to_le_bytes(): isso quer dizer para pegar os bytes do id que será cadastrado nesse livro;

Essas sementes garantem que cada endereço seja único, mas não garantem que ele seja válido pois não pode colidir com um endereço de um keypair (mesmo que ele seque exista, não pode gerar endereço de keypair). Assim, a instrução bump diz para incluir no cálculo uma seed adicional de 1 byte que funciona como “nonce”, ou seja, um número arbitrário de 0 a 255 que é adicionado às seeds para aumentar a força da PDA. Se com o bump 255 gerar um endereço inválido, será tentando com bump 254 e assim sucessivamente.

Mas voltando à struct AddBookContext, os demais campos não são novidades, então vamos ver a função add_book abaixo, que usa uma struct BookInput que também reproduzo abaixo.

Começamos pegando cópias mutáveis da library e do livro que vamos cadastrar. Com o next_id da library, populamos o campo id do novo livro e com as demais informações fazemos o resto. Antes de concluir a função, incrementamos o next_id para garantir que o próximo livro ganhe um novo id.

Mas o grande “pulo do gato” do uso de PDA vem no client-side, ou neste caso, em nossos unit tests.

#3 – Testando PDAs

Quando vamos nos comunicar com programas que precisem de accounts para guardar dados, precisamos carregar as mesmas e passá-las junto às chamadas, certo? Mas e no caso de PDAs, ou seja, de accounts geradas indefinidamente e deterministicamente?  Neste caso precisamos replicar o mesmo algoritmo de geração dos endereços no lado do client-side, para garantir que consigamos carregar as accounts corretas.

Veja abaixo um exemplo de função TS que usaremos em nossos testes, que gera o PDA da account de um livro arbitrário.

A função findProgramAddressSync permite que a gente passe um array de seeds binárias e o id do programa para geração de um PDA. Como nossas seeds no programa são a palavra book, o endereço da library e o id do livro, aqui fazemos exatamente a mesma coisa, mas usando TS. Logo, se você passar o endereço da account de library x e o id do livro y, você receberá como retorno o PDA z.

Veja abaixo um exemplo de função TS que cadastra um livro, usando um endereço PDA gerado com a função anterior.

Começamos carregando a account de library usando o endereço PDA dela que deixamos preparado no nosso setup inicial do tutorial, lembra? Com essa account a gente consegue descobrir qual será o id que nosso novo livro vai receber e que consequentemente vai influenciar seu PDA, como definido na instrução seguinte, que chama a getBookPda. A variável bookPda agora possui o endereço da account do novo livro que VAI SER cadastrado, ela não existe ainda.

Na linha seguinte chamamos a addBook (variação TS da add_book do Rust), passando os campos do livro e os endereços das accounts envolvidas: library e book, bem como o payer (user) e o system program.

Agora o teste em si dessa adição de livro pode ser visto abaixo:

Cadastramos o livro, depois geramos o PDA do livro de id 1, carregamos a account a partir do PDA e vemos se ela foi cadastrada com o id certo, se a quantidade total de livros está correta, etc.

#4 – Limpando os Testes

O problema com a abordagem PDA Singleton é que como o Anchor sobe apenas um validador de Solana para os testes, ele acaba gerando dependência estrutural entre os testes, o que não é algo desejável na maioria das vezes. Assim, quando rodo o teste de addBook, ao término dele temos um livro cadastrado na blockchain que pode afetar o teste seguinte. E não, não adianta o initialize no beforeEach porque ele vai dar erro na segunda execução uma vez que o endereço do PDA library é singleton e já estará ocupado.

Enfim, é necessário nesse tipo de cenário que a gente tenha uma função para limpeza entre os testes, que é útil também para o cenário em que eu queira “destruir” os dados do programa ou resetá-lo completamente. Para isso, volte ao lib.rs e crie os seguintes contextos.

O primeiro é o contexto de fechamento da account library, que necessita da constraint seed para saber o endereço certo e o usuário que fará o fechamento e receberá de volta o rent pago na inicialização. A instrução close na macro é especial para fazer isso, ela indica que a função desse contexto irá fechar a account associada e vai devolver o rent ao user informado.

Já o segundo faz o mesmo, mas para uma account de book qualquer e sem constraint seeds, o que vai permitir que a gente tenha de confiar no endereço passado pelo client-side. Infelizmente como nossos PDAs de book possuem o id deles na seed, não temos verificar isso em tempo de compilação (e as macros rodam em tempo de compilação, lembra?).

Agora precisamos das funções que vão usar esses contextos, que não precisam fazer nada na verdade pois todo o trabalho será feito exclusivamente pelos contextos que já definimos.

Com as funções prontas, agora vamos no arquivo de testes para criar a função de limpeza que vai ser chamada após cada teste realizado, automaticamente, para fechar as accounts de book e de library, deixando o nó validador de teste “zerado”, o que permitirá um novo initialize antes do próximo teste (before each).

Aqui eu começo pegando todas as accounts de livro do programa e para cada uma delas, eu chamo a closeBook. Depois, chamo uma vez o closeLibrary e pronto, nosso validador não tem mais as accounts antigamente populadas.

Para provar que isso está funcionando, vamos escrever um segundo teste, que cobre o cenário de tentar retornar um livro com o PDA errado.

Eu mando gerar o PDA de um livro de id 2, só que não existe um livro com este id já que mandamos adicionar apenas um livro, que provavelmente vai receber id 1 (isso porque o livro do teste anterior foi excluído na limpeza). Isso vai gerar um erro que capturamos no catch e conferimos a mensagem no assert do test.

Experimente rodar com anchor test para ver tudo funcionando como deveria antes de avançar.

#5 – Editando com PDA

A edição de livros é muito mais simples, já que nela não temos a criação de accounts. Veja abaixo o lib.rs:

O contexto é bem simples já que precisamos mexer apenas na account do livro a ser alterado. Já a função em si, pega a cópia mutável de book_account e altera os campos dela que foram passados via BookInput. Nada demais na verdade.

Já o teste fica assim:

Começamos adicionando um livro, gerando seu PDA, verificando os dados dele antes da edição e depois mandando fazer a edição (repare como estou alterando apenas o título). Após a edição, fazemos nova consulta no endereço do mesmo PDA para verificar se somente o título mudou.

#6 – Excluindo com PDA

E para finalizar, temos a exclusão. Enquanto que no CRUD anterior a gente excluiu removendo elementos do array, aqui nós temos de encerrar as accounts de livros que não queremos mais, com o bônus de que quando encerramos uma account, temos a devolução do rent pago pela mesma, motivo pelo qual temos um Signer no contexto dessa função, como abaixo.

A função delete_book precisa via context do book a ser removido e do authority que vai receber o rent de volta. A função close da account faz o fechamento da mesma e transfere para o endereço passado por parâmetro os lamports restantes do rent. Atenção ao “?” no final da chamada que significa: “se der erro, pára tudo aqui”.

Note que esta é outra abordagem para o fechamento de contas, mais manual. Outra opção seria no DeleteBookContext, na macro da account book incluirmos um close=authority, assim o corpo da função delete_book poderia estar vazio como fizemos com close_book antes.

Agora o teste do delete é bem simples como abaixo, onde começo adicionando o livro e pegando o saldo do usuário antes da exclusão para conferência posterior.

Após a exclusão, além de conferir se o saldo do usuário aumentou em virtude da devolução do rent, eu tento consultar novamente aquele PDA que agora deve dar erro porque não existe mais. Roda os testes e você verá algo como abaixo.

E com isso terminamos este nosso tutorial de PDA que espero que tenha lhe ajudado a compreender esse conceito tão importante de programação para Solana.

Até a próxima!