Noções Básicas de Solana

9 exemplos para você começar com fundamentos de Solana - 6 básicos e 3 intermediários. Cobre contas, programas, transações, SOL, clusters e o fluxo de trabalho do desenvolvedor no Agave 4.1.1.

Pré-requisitos

Instale o Solana CLI 3.0.10 e crie um keypair padrão na devnet.

sh -c "$(curl -sSfL https://release.anza.xyz/v3.0.10/install)"
solana --version
solana config set --url devnet
solana-keygen new --no-bip39-passphrase -o ~/.config/solana/id.json
solana airdrop 2

Para exemplos de clientes TypeScript, use @solana/kit 7.0.0:

npm install @solana/kit@7.0.0

Exemplos Básicos

1. Ler o Saldo de uma Conta

Todo endereço na Solana mapeia para uma conta - mesmo que tenha zero lamports.

import { createSolanaRpc, address, lamports } from "@solana/kit";
 
const rpc = createSolanaRpc("https://api.devnet.solana.com");
const pubkey = address("11111111111111111111111111111111");
 
const { value } = await rpc.getBalance(pubkey).send();
console.log(`Balance: ${Number(lamports(value)) / 1e9} SOL`);

Saldos são armazenados em lamports (u64), não em floats de SOL
getBalance retorna lamports diretamente do campo de lamports da conta
Endereços não inicializados retornam 0 - nenhuma conta existe até ser financiada

Relacionado: SOL, Lamports e Unidades - precisão e conversões

2. Entender o Modelo de Contas

Contas são a abstração única para todo o estado on-chain.

// Layout conceitual - toda conta tem estes campos
pub struct Account {
    pub lamports: u64,      // saldo SOL em lamports
    pub data: Vec<u8>,      // buffer de bytes arbitrário
    pub owner: Pubkey,      // programa autorizado a escrever dados
    pub executable: bool,   // true para programas implantados
    pub rent_epoch: u64,    // rastreamento de rent (campo legado)
}

Programas são contas com executable = true e código em data
Contas de dados guardam o estado do programa - pertencem ao programa que as interpreta
Apenas o programa proprietário pode mutar os dados de uma conta (com exceções de signatário)

Relacionado: O Modelo Mental da Solana vs. EVM - contas vs contratos

3. Enviar uma Transferência Simples

Uma transação com uma instrução do System Program move SOL entre contas.

solana transfer <RECIPIENT_PUBKEY> 0.1 --allow-unfunded-recipient

A CLI monta uma transação com a instrução Transfer do System Program
O keypair do remetente assina como pagador de taxa e como autoridade da conta de origem
--allow-unfunded-recipient cria o destino se ainda não houver conta

Relacionado: Como uma Transação Flui - do cliente à confirmação

4. Inspecionar uma Transação

Use a CLI ou RPC para ver instruções, signatários e compute units consumidas.

solana confirm -v <SIGNATURE>

-v imprime o program ID, contas e dados de cada instrução
Logs mostram compute units (CU) consumidas por instrução
Transações com falha ainda aparecem on-chain com códigos de erro nos logs

Relacionado: Keypairs e Endereços - quem assina o quê

5. Escolher o Cluster Certo

A Solana executa vários clusters independentes com propósitos diferentes.

solana config set --url devnet      # SOL de teste grátis, RPC público
solana config set --url testnet     # testes de validador, menos estável
solana config set --url mainnet-beta # produção - SOL real
solana-test-validator               # nó local Agave 4.1.1

Devnet é o padrão para desenvolvimento de aplicativos
Validador local oferece controle total e latência zero de rede
Mainnet-beta exige SOL real e priority fees durante congestionamento

Relacionado: Clusters e Redes - quando usar cada um

6. Entender Slots e Temporização

A Solana visa slots de ~400 ms; líderes produzem blocos por slot.

solana slot
solana block-time $(solana slot)

Um slot é uma janela de tempo em que um validador é o produtor de blocos
Uma epoch é um número fixo de slots (~432.000 slots, ~2 dias)
Slots pulados ocorrem quando o líder designado está offline ou lento

Relacionado: Slots, Blocos e Epochs - detalhes do cronograma de epochs

Exemplos Intermediários

7. Montar uma Transação com @solana/kit

O Kit usa um pipe funcional para montar transações versionadas.

import {
  createSolanaRpc,
  createTransactionMessage,
  setTransactionMessageFeePayer,
  setTransactionMessageLifetimeUsingBlockhash,
  appendTransactionMessageInstruction,
  pipe,
  address,
  getSignatureFromTransaction,
  signTransactionMessageWithSigners,
} from "@solana/kit";
import { getTransferSolInstruction } from "@solana-program/system";
 
const rpc = createSolanaRpc("https://api.devnet.solana.com");
const feePayer = address("YOUR_FEE_PAYER_PUBKEY");
const recipient = address("RECIPIENT_PUBKEY");
 
const { value: blockhash } = await rpc.getLatestBlockhash().send();
 
const transferIx = getTransferSolInstruction({
  source: feePayer,
  destination: recipient,
  amount: 100_000_000n, // 0.1 SOL em lamports
});
 
const txMessage = pipe(
  createTransactionMessage({ version: 0 }),
  (m) => setTransactionMessageFeePayer(feePayer, m),
  (m) => setTransactionMessageLifetimeUsingBlockhash(blockhash, m),
  (m) => appendTransactionMessageInstruction(transferIx, m),
);
 
// Assine com seu keypair signer e envie via sendTransaction

O Kit separa montagem da mensagem de assinatura e envio
Valores são sempre bigint em lamports - nunca floats JavaScript
Transações versão 0 suportam address lookup tables para mais contas

Relacionado: Carteiras e Explorers - fluxo de trabalho na devnet

8. Gerar e Usar um Keypair

Keypairs Ed25519 são a raiz da identidade e assinatura na Solana.

solana-keygen new --outfile ./dev-wallet.json --no-bip39-passphrase
solana-keygen pubkey ./dev-wallet.json

import { createKeyPairSignerFromBytes } from "@solana/kit";
import { readFileSync } from "node:fs";
 
const secret = JSON.parse(readFileSync("./dev-wallet.json", "utf8"));
const signer = await createKeyPairSignerFromBytes(Uint8Array.from(secret));
console.log(signer.address);

O arquivo JSON é um array de 64 bytes de chave secreta - trate como senha
Chaves públicas (endereços) são pontos Ed25519 de 32 bytes, codificados em base58
Nunca faça commit de arquivos de keypair no controle de versão

Relacionado: Keypairs e Endereços - modelo de assinatura

9. Rastrear uma Transação de Ponta a Ponta

Acompanhe uma transferência do envio pelo cliente até a confirmação finalizada.

# 1. Enviar
SIG=$(solana transfer <RECIPIENT> 0.01 --output json | jq -r .signature)
 
# 2. Verificar confirmação
solana confirm $SIG --commitment confirmed
 
# 3. Inspecionar no explorer
echo "https://explorer.solana.com/tx/$SIG?cluster=devnet"

Processed - o nó viu a transação; ainda pode ser descartada
Confirmed - supermaioria votou no bloco que a contém
Finalized - o bloco está enraizado e não pode ser revertido

Relacionado: Como uma Transação Flui - pipeline completo

Versões da stack: Esta página foi escrita para Agave 4.1.1, Solana CLI 3.0.10, Anchor 0.32.1, anchor-lang 0.32.1, Rust 1.91.1, @solana/kit 7.0.0, Surfpool 0.12.0 e LiteSVM 0.6.x.

Pré-requisitos

Instale o Solana CLI 3.0.10 e crie um keypair padrão na devnet.

sh -c "$(curl -sSfL https://release.anza.xyz/v3.0.10/install)"
solana --version
solana config set --url devnet
solana-keygen new --no-bip39-passphrase -o ~/.config/solana/id.json
solana airdrop 2

Para exemplos de clientes TypeScript, use @solana/kit 7.0.0:

npm install @solana/kit@7.0.0

Exemplos Básicos

1. Ler o Saldo de uma Conta

Todo endereço na Solana mapeia para uma conta - mesmo que tenha zero lamports.

import { createSolanaRpc, address, lamports } from "@solana/kit";
 
const rpc = createSolanaRpc("https://api.devnet.solana.com");
const pubkey = address("11111111111111111111111111111111");
 
const { value } = await rpc.getBalance(pubkey).send();
console.log(`Balance: ${Number(lamports(value)) / 1e9} SOL`);

Saldos são armazenados em lamports (u64), não em floats de SOL
getBalance retorna lamports diretamente do campo de lamports da conta
Endereços não inicializados retornam 0 - nenhuma conta existe até ser financiada

Relacionado: SOL, Lamports e Unidades - precisão e conversões

2. Entender o Modelo de Contas

Contas são a abstração única para todo o estado on-chain.

// Layout conceitual - toda conta tem estes campos
pub struct Account {
    pub lamports: u64,      // saldo SOL em lamports
    pub data: Vec<u8>,      // buffer de bytes arbitrário
    pub owner: Pubkey,      // programa autorizado a escrever dados
    pub executable: bool,   // true para programas implantados
    pub rent_epoch: u64,    // rastreamento de rent (campo legado)
}

Programas são contas com executable = true e código em data
Contas de dados guardam o estado do programa - pertencem ao programa que as interpreta
Apenas o programa proprietário pode mutar os dados de uma conta (com exceções de signatário)

Relacionado: O Modelo Mental da Solana vs. EVM - contas vs contratos

3. Enviar uma Transferência Simples

Uma transação com uma instrução do System Program move SOL entre contas.

solana transfer <RECIPIENT_PUBKEY> 0.1 --allow-unfunded-recipient

A CLI monta uma transação com a instrução Transfer do System Program
O keypair do remetente assina como pagador de taxa e como autoridade da conta de origem
--allow-unfunded-recipient cria o destino se ainda não houver conta

Relacionado: Como uma Transação Flui - do cliente à confirmação

4. Inspecionar uma Transação

Use a CLI ou RPC para ver instruções, signatários e compute units consumidas.

solana confirm -v <SIGNATURE>

-v imprime o program ID, contas e dados de cada instrução
Logs mostram compute units (CU) consumidas por instrução
Transações com falha ainda aparecem on-chain com códigos de erro nos logs

Relacionado: Keypairs e Endereços - quem assina o quê

5. Escolher o Cluster Certo

A Solana executa vários clusters independentes com propósitos diferentes.

solana config set --url devnet      # SOL de teste grátis, RPC público
solana config set --url testnet     # testes de validador, menos estável
solana config set --url mainnet-beta # produção - SOL real
solana-test-validator               # nó local Agave 4.1.1

Devnet é o padrão para desenvolvimento de aplicativos
Validador local oferece controle total e latência zero de rede
Mainnet-beta exige SOL real e priority fees durante congestionamento

Relacionado: Clusters e Redes - quando usar cada um

6. Entender Slots e Temporização

A Solana visa slots de ~400 ms; líderes produzem blocos por slot.

solana slot
solana block-time $(solana slot)

Um slot é uma janela de tempo em que um validador é o produtor de blocos
Uma epoch é um número fixo de slots (~432.000 slots, ~2 dias)
Slots pulados ocorrem quando o líder designado está offline ou lento

Relacionado: Slots, Blocos e Epochs - detalhes do cronograma de epochs

Exemplos Intermediários

7. Montar uma Transação com @solana/kit

O Kit usa um pipe funcional para montar transações versionadas.

import {
  createSolanaRpc,
  createTransactionMessage,
  setTransactionMessageFeePayer,
  setTransactionMessageLifetimeUsingBlockhash,
  appendTransactionMessageInstruction,
  pipe,
  address,
  getSignatureFromTransaction,
  signTransactionMessageWithSigners,
} from "@solana/kit";
import { getTransferSolInstruction } from "@solana-program/system";
 
const rpc = createSolanaRpc("https://api.devnet.solana.com");
const feePayer = address("YOUR_FEE_PAYER_PUBKEY");
const recipient = address("RECIPIENT_PUBKEY");
 
const { value: blockhash } = await rpc.getLatestBlockhash().send();
 
const transferIx = getTransferSolInstruction({
  source: feePayer,
  destination: recipient,
  amount: 100_000_000n, // 0.1 SOL em lamports
});
 
const txMessage = pipe(
  createTransactionMessage({ version: 0 }),
  (m) => setTransactionMessageFeePayer(feePayer, m),
  (m) => setTransactionMessageLifetimeUsingBlockhash(blockhash, m),
  (m) => appendTransactionMessageInstruction(transferIx, m),
);
 
// Assine com seu keypair signer e envie via sendTransaction

O Kit separa montagem da mensagem de assinatura e envio
Valores são sempre bigint em lamports - nunca floats JavaScript
Transações versão 0 suportam address lookup tables para mais contas

Relacionado: Carteiras e Explorers - fluxo de trabalho na devnet

8. Gerar e Usar um Keypair

Keypairs Ed25519 são a raiz da identidade e assinatura na Solana.

solana-keygen new --outfile ./dev-wallet.json --no-bip39-passphrase
solana-keygen pubkey ./dev-wallet.json

import { createKeyPairSignerFromBytes } from "@solana/kit";
import { readFileSync } from "node:fs";
 
const secret = JSON.parse(readFileSync("./dev-wallet.json", "utf8"));
const signer = await createKeyPairSignerFromBytes(Uint8Array.from(secret));
console.log(signer.address);

O arquivo JSON é um array de 64 bytes de chave secreta - trate como senha
Chaves públicas (endereços) são pontos Ed25519 de 32 bytes, codificados em base58
Nunca faça commit de arquivos de keypair no controle de versão

Relacionado: Keypairs e Endereços - modelo de assinatura

9. Rastrear uma Transação de Ponta a Ponta

Acompanhe uma transferência do envio pelo cliente até a confirmação finalizada.

# 1. Enviar
SIG=$(solana transfer <RECIPIENT> 0.01 --output json | jq -r .signature)
 
# 2. Verificar confirmação
solana confirm $SIG --commitment confirmed
 
# 3. Inspecionar no explorer
echo "https://explorer.solana.com/tx/$SIG?cluster=devnet"

Processed - o nó viu a transação; ainda pode ser descartada
Confirmed - supermaioria votou no bloco que a contém
Finalized - o bloco está enraizado e não pode ser revertido

Relacionado: Como uma Transação Flui - pipeline completo

Versões da stack: Esta página foi escrita para Agave 4.1.1, Solana CLI 3.0.10, Anchor 0.32.1, anchor-lang 0.32.1, Rust 1.91.1, @solana/kit 7.0.0, Surfpool 0.12.0 e LiteSVM 0.6.x.

Noções Básicas de Solana

Buscar na documentação

Noções Básicas de Solana