Os programas Solana são algoritmos que rodam em cima da blokchain da Solana e compatíveis, o equivalente ao que chamamos de smart contracts em outras redes. Através de programação usando a linguagem Rust é possível fazer pagamentos usando cripto, criar protocolos DeFi, salvar dados na blockchain, transferir a propriedade de NFTs e muito mais. Explorei a linguagem Rust e a criação de programas Solana neste outro tutorial aqui do blog.
No entanto, programas Solana são como se fossem o backend da Web3: eles não possuem qualquer interface gráfica para que os usuários possam interagir com eles, como se fossem web APIs, entende?
Se você quer que usuários comuns consigam usar dos recursos da sua aplicação é necessário que você forneça alguma maneira simples e visual deles interagirem com o mesmo, criar uma aplicação de fato e não apenas uma página do block explorer. A estas aplicações que se conectam aos programas Solana nós chamamos de dapps, ou decentralized applications (aplicações descentralizadas).
Você pode criar um dapp com qualquer tecnologia, mas quando o assunto é dapps web não vai conseguir fugir de JavaScript. E ainda no espectro do JavaScript existem muitas opções de tecnologias, sendo que a que recomendo utilizar é a ReactJS, que já apresentei em mais detalhes em outros tutoriais aqui do blog.
Então neste tutorial eu vou te mostrar como você pode criar uma aplicação ReactJS muito simples que servirá de interface para um smart contract bem simples também, que eu já publiquei na blockchain da Solana DevNet em outra oportunidade.
Vamos lá!
#1 – Estruturando o Projeto
O link do programa que vamos usar é este aqui e ele está publicado na DevNet. Ele é essencialmente um CRUD de livros, ou seja, permite cadastro, edição, listagem e atualização de livros, que são registrados cada um na sua PDA Account. Não esqueça que se seu programa tiver uma função initialize, que ela deve ser chamada antes da aplicação, o que pode ser feito pela aba Interact do Solana Explorer.
Para fazer as operações de leitura você não precisará de nenhum tipo de autenticação, mas para conseguir fazer as operações de escrita você precisará pagar as taxas da rede (mesmo sendo rede de teste) e portanto estar conectado na Solana DevNet com uma carteira de criptomoedas, sendo que as que recomendo são a Brave Wallet e a Phantom, sendo que a primeira eu ensino a criar e configurar para testes neste tutorial.
Ainda falando do programa Solana, no link que passei antes, se você for na aba Program IDL, encontrará o botão para download do IDL. IDL é uma sigla para Interface Definition Language, algo como uma especificação de como este programa deve ser invocado, caso queira consumir suas funções. Faço o download deste IDL e renomeie para idl.json, vamos precisar dele mais tarde. No caso de estar usando um programa seu, o IDL fica dentro de target/idl no seu projeto Anchor, após compilação.
Agora que temos o programa que vamos usar, pegamos o IDL dele e estamos com a Brave Wallet instalada e configurada para a mesma rede (Solana DevNet), é hora de criarmos nossa aplicação React. Para isso vamos usar o toolkit Vite, como abaixo, que cria um projeto React + TypeScript utilizando com o nome de react-solana-dapp.
|
1 2 3 |
npm create vite@latest |
Após o projeto ser criado, entre na pasta do mesmo e para se certificar de que foi criado corretamente, rode o projeto com npm run dev antes de avançar e veja se funciona.
Agora na pasta src guarde o seu arquivo idl.json nela, instalando também as dependências que vamos usar para comunicação com nosso programa Solana na blockchain através da carteira cripto.
|
1 2 3 |
npm install @coral-xyz/anchor @solana/wallet-adapter-base @solana/wallet-adapter-react @solana/wallet-adapter-react-ui buffer |
A saber:
- @coral-xyz/anchor: biblioteca do Anchor que facilita muito as chamadas a programas criados com este framework;
- @solana/wallet-adapter-base, @solana/wallet-adapter-react e @solana/wallet-adapter-react-ui: bibliotecas para comunicação React com Solana;
- buffer: biblioteca para buffers de bytes no frontend (por padrão, Buffer existe apenas no backend);
O pacote @solana/wallet-adapter-react provê hooks e contexts para facilitar a integração e gestão de estado das carteiras de browser compatíveis com Solana. No entanto, para que isso funcione, você deve envolver toda sua aplicação com os context providers fornecidos por ela: ConnectionProvider e WalletProvider, para isso vamos ajustar nosso main.tsx para que fique como abaixo.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 |
import { StrictMode } from 'react' import { createRoot } from 'react-dom/client' import { Buffer } from 'buffer' import type { Adapter } from '@solana/wallet-adapter-base' import { ConnectionProvider, WalletProvider } from '@solana/wallet-adapter-react' import { WalletModalProvider } from '@solana/wallet-adapter-react-ui' import '@solana/wallet-adapter-react-ui/styles.css' import { clusterApiUrl } from '@solana/web3.js' import App from './App.tsx' if (!globalThis.Buffer) { globalThis.Buffer = Buffer } const endpoint = clusterApiUrl('devnet') const wallets: Adapter[] = [] createRoot(document.getElementById('root')!).render( <StrictMode> <ConnectionProvider endpoint={endpoint}> <WalletProvider wallets={wallets}> <WalletModalProvider> <App /> </WalletModalProvider> </WalletProvider> </ConnectionProvider> </StrictMode>, ) |
Note que o ConnectionProvider requer um endpoint, para que ele saiba onde se conectar. Usaremos aqui a Solana DevNet cuja URL do cluster pegamos através da função clusterApiUrl. Lembre-se que você deve fazer os testes no mesmo browser onde está a sua carteira Solana, também configurada para DevNet. No entanto, se testar agora, não verá nada funcionando ainda, pois só fizemos um setup inicial.
Vamos começar adicionando um botão que, quando clicado, solicita a permissão para conexão com a carteira do navegador. Para isso usaremos um componente da biblioteca wallet-adapter-react-ui, o WalletMultiButton, responsável pelo botão de “login” que já tem embutido o comportamento de exibir a carteira conectada depois que o usuário autorizar a mesma.
Abra o App.tsx e altere o seu conteúdo para que inclua as dependências novas e o componente novo.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
import { WalletMultiButton } from "@solana/wallet-adapter-react-ui"; function App() { return ( <> <div style={{ margin: 20 }}> <WalletMultiButton /> </div> </> ); } export default App; |
Agora sim, se abrir no seu navegador com uma carteira Solana verá que o botão sugere ao usuário que se conecte na sua carteira e, uma vez que ele clique e autorize a mesma (no meu exemplo a Brave Wallet), o botão exibe a carteira conectada, como na imagem abaixo.
Agora que temos a funcionalidade de conexão da carteira, podemos fazer coisas mais legais em nosso projeto, usando o programa que está nos esperando na blockchain.
#2 – Setup do Web3Service
A programação dos componentes web3 exige ao menos duas etapas, uma de integração com a blockchain e outra de interação com o usuário. Para as funcionalidades que interagem com a blockchain nós vamos criar um módulo na pasta src chamado Web3Service.ts. Vamor começar este arquivo com TODOS os imports que vamos usar ao longo deste tutorial.
|
1 2 3 4 5 6 7 |
import { Connection, PublicKey, SystemProgram, Transaction, TransactionInstruction } from "@solana/web3.js"; import { BorshAccountsCoder, BorshInstructionCoder, type Idl, BN } from "@coral-xyz/anchor"; import type { WalletContextState } from "@solana/wallet-adapter-react"; import { Buffer } from "buffer"; import IDL from "./idl.json"; |
A saber:
- da biblioteca @solana/web3.js nós vamos pegar as primitivas de integração como Connection, Transaction e outras;
- da biblioteca @coral-xyz/anchor, vamos pegar alguns utilitários que facilitam MUITO o desenvolvimento de integração com programas Anchor;
- da @solana/wallet-adapter-react vamos precisar do type de carteira;
- a Buffer é necessária para lidar com os bytes;
- e por fim o IDL do programa com o qual vamos nos integrar, que deve estar na mesma pasta;
Depois, vamos declarar alguns objetos que vão ser úteis em diversas funções.
|
1 2 3 4 5 6 |
const programId = new PublicKey(import.meta.env.VITE_PROGRAM_ID); const encoder = new TextEncoder(); const accountsCoder = new BorshAccountsCoder(IDL as Idl); const instructionCoder = new BorshInstructionCoder(IDL as Idl); |
A saber:
- programId: o ID do nosso programa na blockchain, que você deve configurar em um .env na raiz da aplicação com a variável VITE_PROGRAM_ID;
- encoder: objeto de codificação de texto para binário, necessário para as seeds dos PDAs;
- accountsCoder: objeto de codificação de Accounts do Anchor;
- instructionCoder: objeto de codificação de Instructions do Anchor (instructions fazem parte de transactions);
E por fim, os types das accounts do nosso programa. Aqui, o meu exemplo é em cima de um programa que faz gestão de livros em uma biblioteca, então ajuste conforme o seu programa:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 |
type DecodedLibraryAccount = { nextId: number; authority: string; }; export type DecodedBookAccount = { id: number; title: string; author: string; year: number; }; type Account = { pubkey: PublicKey; isSigner: boolean; isWritable: boolean }; |
Sendo eles:
- DecodedLibraryAccount: type para os dados da account de library;
- DecodedBookAccount: type para os dados da account de book, estou exportando ele pois usaremos na UI também;
- Account: type para os dados genéricos de accounts;
Como meu programa, e possivelmente o seu também, lida com PDAs, precisamos ter uma função para derivar eles, como abaixo.
|
1 2 3 4 5 |
function getPda(seeds: (Uint8Array<ArrayBufferLike> | Buffer<ArrayBufferLike>)[]) { return PublicKey.findProgramAddressSync(seeds, programId)[0]; } |
Nessa função, recebemos o array de seeds binárias e usamos ele, junto do programId, para derivar o PDA que é retornado. Essa função será usada mais tarde para derivar diversos PDAs diferentes, o que faremos com funções específicas.
Vamos precisar também de uma função para enviar transações para blockchain, como abaixo.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 |
async function sendTransaction(fnName: string, ix: any, wallet: WalletContextState, connection: Connection, accounts: Account[]) { const instructionData = instructionCoder.encode(fnName, ix); const tx = new Transaction().add( new TransactionInstruction({ programId, keys: accounts, data: instructionData, }) ); try { const signature = await wallet.sendTransaction(tx, connection); console.log("Transaction sent with signature:", signature); return signature; } catch (error) { console.error("Transaction failed:", error); } } |
Essa função espera o nome da função do programa Solana, os parâmetros da instrução (ix), a wallet, a conexão e as accounts para o contexto. A construção de uma transação Solana envolve criar um objeto Transaction e adicionar nele as instruções a serem executadas, com o programId, as accounts do contexto e os dados de instrução. Com tudo isso configurado, é só usar a wallet para enviar a transação através da conexão e pegar o hash de transação.
Opcionalmente, para fins de debugging, eu super recomendo ter uma função de simulação de transação também, como abaixo.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 |
async function simulateAndLogTransaction( connection: Connection, tx: Transaction, feePayer: PublicKey, throwOnSimulationError = false, ) { const { blockhash } = await connection.getLatestBlockhash(); tx.recentBlockhash = blockhash; tx.feePayer = feePayer; const simulation = await connection.simulateTransaction(tx); console.log("Simulation result:", simulation); if (simulation.value.logs) console.log("Transaction logs:", simulation.value.logs); if (throwOnSimulationError && simulation.value.err) { console.error("Transaction simulation failed:", simulation.value.err); const errorMessage = JSON.stringify(simulation.value.err); throw new Error(`Simulation error: ${errorMessage}`); } } |
Sempre que você estiver investigando algo, pode chamar essa simulateAndLogTransaction ANTES de chamar wallet.sendTransaction na nossa função sendTransaction para ter detalhes do que está acontecendo. Isso porque os componentes React acabam ocultando os detalhes e lançam apenas erros genéricos quando algo dá errado. E as coisas sempre dão errado quando estamos começando com Solana.
Com esse setup inicial do Web3Service.ts preparado, podemos implementar a primeira funcionalidade que vai ser a de inicialização do programa.
#3 – Inicialização do Programa
Muitos programas Solana exigem inicialização antes de poderem ser utilizados. Você pode fazer isso através da aba Interact do Solana Explorer, mas vamos criar um componente para isso na nossa aplicação. Já que estávamos mexendo no Web3Service, vamos começar por ele pois todo componente web3 que construirmos vai precisar usá-lo também.
A inicialização do nosso programa para gestão de biblioteca envolve a inicialização da account singleton de biblioteca. Nós já temos uma função genérica de derivação PDA, vamos agora criar a específica que aplica a única seed da account library, como abaixo.
|
1 2 3 4 5 |
function getLibraryPda() { return getPda([encoder.encode("library")]); } |
Agora a função de inicialização em si fica como abaixo, usando muitas coisas que criamos anteriormente.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 |
export async function initializeProgram(wallet: WalletContextState, connection: Connection) { if (!wallet.publicKey) throw new Error("Wallet not connected"); const libraryPda = getLibraryPda(); console.log("Initializing program with Library PDA:", libraryPda.toBase58()); // Check if library account already exists const existingAccount = await connection.getAccountInfo(libraryPda); if (existingAccount) { console.log("Library account already initialized. Skipping."); return "already-initialized"; } return sendTransaction("initialize", {}, wallet, connection, [ { pubkey: libraryPda, isSigner: false, isWritable: true }, { pubkey: wallet.publicKey, isSigner: true, isWritable: true }, { pubkey: SystemProgram.programId, isSigner: false, isWritable: false }, ]); } |
A primeira coisa é verificar se a wallet está devidamente carregada. Depois, pegamos o PDA singleton de library com a função de derivação. Se ele já existir, a gente retorna com esta mensagem, mas caso contrário, é hora de enviar uma transação chamando a função do programa chamada “initialize”, que não possui parâmetros ({}), com wallet, connection e o array de accounts para o contexto, onde cada account possui seu endereço (pubkey), se vai assinar ou não a transação e se é ou não mutable/writable.
Essa chamada de envio de transação depende muito do que faz a sua função initialize, então ajuste de acordo.
Agora o componente em si, a UI. Crie um componente LibraryInitializer.tsx na pasta src, iniciando pelos imports.
|
1 2 3 4 5 |
import { useState } from "react"; import { useConnection, useWallet } from "@solana/wallet-adapter-react"; import { initializeProgram } from "./Web3Service"; |
Aqui importamos os hooks que vamos precisar, mas também a função initializeProgram que criamos há pouco. Agora vamos precisar de alguns states e chamar os hooks, como abaixo.
|
1 2 3 4 5 6 7 8 9 |
export default function LibraryInitialize() { const { connection } = useConnection(); const wallet = useWallet(); const [error, setError] = useState(""); const [isLoading, setIsLoading] = useState(false); |
O useConnection nos dá a conexão com o nó Solana da nossa carteira de browser, enquanto que useWallet nos dá acesso à carteira em si. Já os states de error e isLoading são elementos de UX para informar o usuário.
A UI em si do componente é bem simples: apenas um botão e um campo para mensagens de retorno.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 |
return ( <div style={{ margin: 20 }}> <h2>Initialize</h2> <p> <button type="button" onClick={onInitializeClick} disabled={isLoading}> {isLoading ? "Loading..." : "Initialize Program"} </button> <span style={{ marginLeft: 10, fontSize: 12, color: "gray" }}> Click this first if you see "Library account not found" </span> </p> <p style={{ color: error.includes("successfully") ? "green" : "red" }}> {error} </p> <hr /> </div> ) |
A função que o botão dispara, onInitializeClick, deve chamar o Web3Service.ts, como abaixo, passando wallet e connection.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 |
async function onInitializeClick() { if (!wallet.publicKey) { setError("Wallet not connected"); return; } setError(""); setIsLoading(true); console.log("Initializing program..."); try { await initializeProgram(wallet, connection); setError("Program initialized successfully!"); } catch (err) { setError("Initialization failed: " + (err as Error).message); } finally { setIsLoading(false); } } |
Importe este componente e posicione-o no App.tsx e a aparência deve ficar como abaixo e, ao clicar, deve inicializar seu programa se ele ainda não foi inicializado. Não esqueça de conectar a sua carteira antes de clicar no botão de inicializar.
E com isso finalizamos a primeira etapa deste tutorial. Na segunda parte vamos implementar as funcionalidades para o CRUD de livros funcionar.
Até a próxima!
Olá, tudo bem?
O que você achou deste conteúdo? Conte nos comentários.