SOL, Lamports e Unidades

A Solana armazena toda moeda nativa como lamports - inteiros sem sinal de 64 bits. Entender denominações previne bugs de arredondamento, transações com falha e cálculos incorretos de taxa.

Receita

Cartão de receita de referência rápida - pronto para copiar.

import { lamports } from "@solana/kit";
 
const ONE_SOL = 1_000_000_000n;
const halfSol = lamports(500_000_000n);
 
function solToLamports(sol: number): bigint {
  return BigInt(Math.round(sol * 1e9));
}
 
function lamportsToSol(lps: bigint): string {
  return (Number(lps) / 1e9).toFixed(9);
}

Quando usar:

• Converter valores de SOL voltados ao usuário em lamports on-chain antes de montar instruções
• Exibir saldos buscados via RPC sem perda de precisão
• Calcular depósitos mínimos isentos de rent para novas contas
• Comparar priority fees (microlamports por CU) com taxas base (lamports por signature)
• Validar valores de token SPL contra decimals do mint (separado de SOL nativo)

Exemplo Prático

import { createSolanaRpc, address, lamports } from "@solana/kit";
import { getTransferSolInstruction } from "@solana-program/system";
import {
  createTransactionMessage,
  setTransactionMessageFeePayer,
  setTransactionMessageLifetimeUsingBlockhash,
  appendTransactionMessageInstruction,
  pipe,
} from "@solana/kit";
 
const rpc = createSolanaRpc("https://api.devnet.solana.com");
const sender = address("SENDER_PUBKEY");
const recipient = address("RECIPIENT_PUBKEY");
 
// Usuário digita "0.25" SOL em formulário da UI
const userInputSol = 0.25;
const amountLamports = BigInt(Math.round(userInputSol * 1_000_000_000));
 
const { value: balance } = await rpc.getBalance(sender).send();
if (balance < amountLamports) {
  throw new Error(
    `Insufficient: have ${Number(lamports(balance)) / 1e9} SOL, need ${userInputSol}`,
  );
}
 
const { value: blockhash } = await rpc.getLatestBlockhash().send();
const transferIx = getTransferSolInstruction({
  source: sender,
  destination: recipient,
  amount: amountLamports,
});
 
const message = pipe(
  createTransactionMessage({ version: 0 }),
  (m) => setTransactionMessageFeePayer(sender, m),
  (m) => setTransactionMessageLifetimeUsingBlockhash(blockhash, m),
  (m) => appendTransactionMessageInstruction(transferIx, m),
);
 
console.log("Transfer message built for", amountLamports, "lamports");

O que isso demonstra:

• Input do usuário é convertido para lamports bigint antes de qualquer comparação on-chain
• getBalance retorna lamports - compare inteiros, não floats
• Helper lamports() do Kit envolve valores brutos para clareza de tipo
• Valores de transação são sempre inteiros de lamport

Aprofundamento

Como Funciona

• O genesis e toda contabilidade de runtime usam lamports como unidade atômica
• 1 SOL = 10^9 lamports - mesma relação que wei para ETH, mas com 9 decimals
• Saldos de conta, transferências, rent e taxas são valores u64 em lamports
• Tipos de ponto flutuante não representam todos os valores de lamport com exatidão em escala

Denominações em Resumo

Notas Rust

use anchor_lang::prelude::*;
 
const LAMPORTS_PER_SOL: u64 = 1_000_000_000;
 
pub fn transfer_amount(ctx: Context<Transfer>, sol: f64) -> Result<()> {
    let lamports = (sol * LAMPORTS_PER_SOL as f64) as u64; // evite em produção
    // Prefira: usuário fornece lamports diretamente, ou use crate fixed-point
    require!(lamports > 0, ErrorCode::ZeroAmount);
    Ok(())
}

• Nunca faça cast f64 para u64 em código financeiro de produção - use input inteiro
• anchor_lang fornece alias de tipo Lamports em alguns contextos
• Use checked_add, checked_sub para aritmética de saldo em programas

Erros Comuns

• Arredondamento float JavaScript - 0.1 + 0.2 !== 0.3 pode produzir lamports errados. Correção: parse strings de usuário para bigint via matemática inteira ou biblioteca decimal.
• Exibir u64 em JS - valores acima de Number.MAX_SAFE_INTEGER perdem precisão. Correção: formate lamports como bigint ou use formatador baseado em string.
• Misturar SOL e lamports em APIs - algumas flags CLI usam SOL, RPC retorna lamports. Correção: leia docs de cada API e normalize na borda do app.
• Decimals SPL diferem - USDC usa 6 decimals, SOL usa 9. Correção: sempre leia mint.decimals antes de converter valores de token.
• Cálculo de rent em SOL - desenvolvedores às vezes arredondam rent para 0. Correção: use RPC getMinimumBalanceForRentExemption e armazene valor exato em lamports.
• Unidades de priority fee - microlamports por CU não é o mesmo que lamports por signature. Correção: defina ambos via instruções Compute Budget separadamente.

Alternativas

FAQs

function parseSolToLamports(input: string): bigint {
  const [whole, frac = ""] = input.split(".");
  const padded = (frac + "000000000").slice(0, 9);
  return BigInt(whole) * 1_000_000_000n + BigInt(padded);
}

Relacionado

• Noções Básicas de Solana - orientação a contas e transações
• Keypairs e Endereços - quem detém os lamports
• Clusters e Redes - valores de airdrop devnet

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.