Instale o Solana CLI e Anchor

Esta seção aborda os passos para configurar seu ambiente local para o desenvolvimento Solana.

Instalação rápida

No Mac e Linux, execute este único comando para instalar todas as dependências.

Terminal

$ curl --proto '=https' --tlsv1.2 -sSfL https://solana-install.solana.workers.dev | bash

Usuários Windows: você deve primeiro instalar o WSL (veja Instalar Dependências). Em seguida, execute o comando anterior no terminal Ubuntu (Linux).

Após a instalação, você deverá ver uma saída como a seguinte:

Installed Versions:
Rust: rustc 1.86.0 (05f9846f8 2025-03-31)
Solana CLI: solana-cli 2.2.12 (src:0315eb6a; feat:1522022101, client:Agave)
Anchor CLI: anchor-cli 0.31.1
Node.js: v23.11.0
Yarn: 1.22.1

Se o comando de instalação rápida não funcionar, consulte a seção Instalar Dependências abaixo para instruções sobre como instalar cada dependência individualmente.

Se o comando de instalação rápida for executado com sucesso, pule para as seções Fundamentos do Solana CLI e Fundamentos do Anchor CLI abaixo.

Instalar dependências

As instruções abaixo orientam você na instalação de cada dependência individualmente.

Usuários Windows devem primeiro instalar o WSL (Subsistema Windows para Linux) e depois instalar as dependências especificadas na seção Linux abaixo.
Usuários Linux devem primeiro instalar as dependências especificadas na seção Linux abaixo.
Usuários Mac devem começar com as instruções de instalação do Rust abaixo.

Instalar Rust

Os desenvolvedores constroem programas Solana usando a linguagem de programação Rust.

Instale o Rust com rustup.

Execute o seguinte comando para instalar o Rust:

Terminal

$ curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y

Você deverá ver a seguinte mensagem após a conclusão da instalação:

Execute o seguinte comando para recarregar sua variável de ambiente PATH para incluir o diretório bin do Cargo:

Terminal

$ . "$HOME/.cargo/env"

Para verificar se a instalação foi bem-sucedida, verifique a versão do Rust:

Terminal

$ rustc --version

Você deverá ver uma saída como a seguinte:

rustc 1.86.0 (05f9846f8 2025-03-31)

Instalar a CLI da Solana

A CLI da Solana fornece todas as ferramentas necessárias para construir e implantar programas Solana.

Instale o conjunto de ferramentas da CLI da Solana usando o comando de instalação oficial:

Terminal

$ sh -c "$(curl -sSfL https://release.anza.xyz/stable/install)"

Você pode substituir stable pela tag de lançamento correspondente à versão do software da sua versão desejada (por exemplo, v2.0.3), ou usar um dos três nomes simbólicos de canal: stable, beta ou edge.

Para uma primeira instalação da CLI da Solana, você pode ver a seguinte mensagem solicitando que adicione uma variável de ambiente PATH:

Close and reopen your terminal to apply the PATH changes or run the following in your existing shell:

export PATH="/Users/test/.local/share/solana/install/active_release/bin:$PATH"

Se você estiver usando Linux ou WSL, precisa adicionar o binário da CLI da Solana ao seu PATH para que o comando esteja disponível no seu terminal.

Primeiro, execute o seguinte comando para verificar qual shell você está usando:

Terminal

$ echo $SHELL

Se a saída contiver /bash, use .bashrc.
Se a saída contiver /zsh, use .zshrc.

Dependendo do seu shell, execute o comando apropriado.

Para Bash (bashrc):

Terminal

$ echo 'export PATH="$HOME/.local/share/solana/install/active_release/bin:$PATH"' >> ~/.bashrc
$ source ~/.bashrc

Para Zsh (zshrc):

Terminal

$ echo 'export PATH="$HOME/.local/share/solana/install/active_release/bin:$PATH"' >> ~/.zshrc
$ source ~/.zshrc

Em seguida, execute o seguinte comando para atualizar a sessão do terminal ou reinicie seu terminal.

Terminal

$ source ~/.bashrc # If using Bash
$ source ~/.zshrc # If using Zsh

Para verificar se a instalação foi bem-sucedida, verifique a versão da CLI Solana:

Terminal

$ solana --version

Você deverá ver uma saída como a seguinte:

solana-cli 2.2.12 (src:0315eb6a; feat:1522022101, client:Agave)

Você pode ver todas as versões disponíveis no repositório Github do Agave.

Agave é o cliente validator da Anza, anteriormente conhecido como cliente validator Solana Labs.

Para atualizar posteriormente a CLI Solana para a versão mais recente, você pode usar o seguinte comando:

Terminal

$ agave-install update

Instalar Anchor CLI

Anchor é um framework para desenvolver programas Solana. O framework Anchor utiliza macros Rust para simplificar o processo de escrever programas Solana.

Você pode instalar a CLI e ferramentas do Anchor de duas maneiras:

Anchor Version Manager (AVM) - Método de instalação recomendado
Sem AVM - Instalar diretamente do GitHub

O gerenciador de versões do Anchor (AVM) permite que você instale e gerencie diferentes versões do Anchor em seu sistema e atualize facilmente as versões do Anchor no futuro.

Instale o AVM com o seguinte comando:

Terminal

$ cargo install --git https://github.com/coral-xyz/anchor avm --force

Confirme que o AVM foi instalado com sucesso:

Terminal

$ avm --version

Instale a versão mais recente do Anchor CLI usando o AVM:

Terminal

$ avm install latest
$ avm use latest

Você pode instalar uma versão específica do Anchor CLI especificando o número da versão:

Terminal

$ avm install 0.30.1
$ avm use 0.30.1

Não se esqueça de executar o comando avm use para declarar a versão do Anchor CLI a ser executada no seu sistema.

Se você instalou a versão latest, execute avm use latest.
Se você instalou a versão 0.30.1, execute avm use 0.30.1.

Para verificar se a instalação foi bem-sucedida, verifique a versão do Anchor CLI:

Terminal

$ anchor --version

Você deverá ver uma saída como a seguinte:

anchor-cli 0.31.1

Ao instalar o Anchor CLI no Linux ou WSL, você pode encontrar este erro:

error: could not exec the linker cc = note: Permission denied (os error 13)

Se você vir esta mensagem de erro:

Instale as dependências listadas na seção Linux no topo desta página.
Tente instalar o Anchor CLI novamente.

Node.js e Yarn

O arquivo de teste padrão do projeto Anchor (TypeScript) criado com o comando anchor init requer Node.js e Yarn. (O modelo de teste em Rust está disponível usando anchor init --test-template rust)

Ao executar anchor build, se você encontrar os seguintes erros:

Depois de aplicar a solução anterior, tente executar anchor build novamente.

Ao executar anchor test após criar um novo projeto Anchor no Linux ou WSL, você pode encontrar os seguintes erros se não tiver o Node.js ou Yarn instalados:

Permission denied (os error 13)

No such file or directory (os error 2)

Configurando ferramentas de IA para desenvolvimento Solana

Esta seção detalha a configuração opcional de ferramentas de IA que você pode usar para acelerar seu desenvolvimento na Solana.

Ferramenta	Descrição	Link
MCP	Servidor MCP que você pode conectar ao cursor para melhorar o desenvolvimento assistido por IA na Solana.	https://mcp.solana.com/
LLMs.txt	Documentação otimizada para LLM que você pode usar para treinar LLMs na documentação da Solana.	https://solana.com/llms.txt

Fundamentos da CLI Solana

Esta seção apresenta alguns comandos comuns da CLI Solana para ajudá-lo a começar.

Configuração da Solana

Para ver sua configuração atual:

Terminal

$ solana config get

Você deverá ver uma saída como a seguinte:

Config File: /Users/test/.config/solana/cli/config.yml
RPC URL: https://api.mainnet-beta.solana.com
WebSocket URL: wss://api.mainnet-beta.solana.com/ (computed)
Keypair Path: /Users/test/.config/solana/id.json
Commitment: confirmed

A URL RPC e a URL Websocket especificam o cluster Solana para o qual a CLI envia solicitações.

Você pode atualizar o cluster da CLI Solana usando os seguintes comandos:

Terminal

$ solana config set --url mainnet-beta
$ solana config set --url devnet
$ solana config set --url localhost
$ solana config set --url testnet

Você também pode usar as seguintes opções abreviadas:

Terminal

$ solana config set -um    # For mainnet-beta
$ solana config set -ud    # For devnet
$ solana config set -ul    # For localhost
$ solana config set -ut    # For testnet

O Caminho do Keypair aponta para a carteira Solana padrão (keypair) usada pela CLI Solana para pagar taxas de transação e implantar programas. Por padrão, este arquivo é armazenado em ~/.config/solana/id.json.

Criar Carteira

Para enviar transações usando a CLI Solana, você precisa de uma carteira Solana com SOL.

Para gerar um keypair no Caminho do Keypair padrão, execute o seguinte comando:

Terminal

$ solana-keygen new

Você deverá ver uma saída como a seguinte:

Generating a new keypair

For added security, enter a BIP39 passphrase

NOTE! This passphrase improves security of the recovery seed phrase NOT the
keypair file itself, which is stored as insecure plain text

BIP39 Passphrase (empty for none):

Wrote new keypair to /Users/test/.config/solana/id.json
===========================================================================
pubkey: 8dBTPrjnkXyuQK3KDt9wrZBfizEZijmmUQXVHpFbVwGT
===========================================================================
Save this seed phrase and your BIP39 passphrase to recover your new keypair:
cream bleak tortoise ocean nasty game gift forget fancy salon mimic amazing
===========================================================================

Se você já tem uma carteira no sistema de arquivos salva no local padrão, este comando não a substituirá, a menos que você force explicitamente a substituição usando a flag --force.

Para visualizar o endereço da sua carteira (chave pública), execute:

Terminal

$ solana address

Airdrop de SOL

Solicite um airdrop de SOL para sua carteira para pagar por transações e implantações de programas.

Configure seu cluster para a devnet:

Terminal

$ solana config set -ud

Em seguida, solicite um airdrop de SOL na devnet:

Terminal

$ solana airdrop 2

Os airdrops na devnet limitam as solicitações a 5 SOL por pedido. Se você atingir limites de taxa ou encontrar erros, tente usar o Web Faucet como alternativa.

Para verificar o saldo de SOL da sua carteira, execute o seguinte comando:

Terminal

$ solana balance

Executar o validador local

A CLI da Solana inclui um validador de teste integrado para desenvolvimento local.

Em um terminal separado, execute o seguinte comando para iniciar um validador local:

Terminal

$ solana-test-validator

Lembre-se também de atualizar sua CLI para usar localhost antes de executar comandos da CLI Solana:

Terminal

$ solana config set -ul

Conceitos básicos da CLI Anchor

Esta seção apresenta alguns comandos comuns da CLI Anchor para você começar. Para mais informações sobre a CLI Anchor, consulte a documentação do Anchor.

Inicializar projeto

Para criar um novo projeto Anchor, execute o seguinte comando:

Terminal

$ anchor init <project-name>

Por exemplo, para criar um projeto chamado my-project, execute:

Terminal

$ anchor init my-project

Este comando cria um novo diretório com o nome do projeto e inicializa um novo projeto Anchor com um programa básico em Rust e um modelo de teste em TypeScript.

Navegue até o diretório do projeto:

Terminal

$ cd <project-name>

Veja a estrutura de arquivos do projeto Anchor.

Compilar programa

Para compilar seu projeto, execute o seguinte comando:

Terminal

$ anchor build

Você pode encontrar o programa compilado no diretório /target/deploy.

Implantar programa

Para implantar seu projeto, execute o seguinte comando:

Terminal

$ anchor deploy

Este comando implanta seu programa no cluster especificado no arquivo Anchor.toml.

Testar programa

Para testar seu projeto, execute o seguinte comando:

Terminal

$ anchor test

Este comando compila, implanta e executa os testes para o seu projeto.

Quando usar localnet como o cluster no Anchor.toml, o Anchor automaticamente inicia um validator local, implanta seu programa, executa testes e depois para o validator.

Subsistema Windows para Linux (WSL)

Linux

Mensagem de instalação bem-sucedida do Rust

Instalação do Node

Instalação do Yarn

erro: não é um diretório

versão 4 do arquivo de bloqueio requer `-Znext-lockfile-bump

Índice