> ## Documentation Index
> Fetch the complete documentation index at: https://www.helius.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Como Usar getBlockCommitment

> Aprenda sobre casos de uso do getBlockCommitment, exemplos de código, parâmetros de requisição, estrutura de resposta e dicas.

O método RPC [getBlockCommitment](https://www.helius.dev/docs/api-reference/rpc/http/getblockcommitment) fornece informações sobre o status de [commitment](https://www.helius.dev/blog/solana-commitment-levels) de um bloco específico no ledger do Solana. Isso é útil para entender quão finalizado um bloco está, com base no stake que votou nele.

## Casos de Uso Comuns

* **Avaliação da Finalidade do Bloco:** Determine o nível de consenso que um bloco alcançou examinando os votos ponderados por stake em diferentes profundidades de confirmação.
* **Entendendo a Saúde do Cluster:** O getBlockCommitment fornece informações sobre o total de stake ativo no cluster no momento em que o bloco foi processado.
* **Lógica Avançada de Confirmação:** Para aplicações que requerem garantias muito específicas sobre a finalidade do bloco além dos níveis de commitment padrão (processed, confirmed).

## Parâmetros

1. slot (número, obrigatório): O número do slot (u64) do bloco para o qual se busca informações de commitment.

## Resposta

O campo commitment da resposta JSON-RPC será um objeto contendo:

* commitment (array de inteiros u64 | null):
  * Um array de inteiros u64, onde cada inteiro representa a quantidade de stake do cluster (em lamports) que votou no bloco em uma profundidade de confirmação específica.
  * O array geralmente tem 32 elementos (representando profundidades de 0 a 31).
  * O índice commitment do array mostra o stake que votou no bloco, considerando votos no próprio bloco e seus descendentes até commitment níveis de profundidade.
  * Se o bloco não for encontrado ou suas informações de commitment não estiverem disponíveis (por exemplo, é muito antigo e foi removido do rastreamento de commitment), este campo será null.
* totalStake (número):
  * O total de stake ativo no cluster (em lamports) no slot em que este bloco foi processado. Este valor é usado para calcular a porcentagem de stake que se comprometeu com o bloco.

## Dicas para Desenvolvedores

* **Interpretando o Array commitment:**
  * O array commitment mostra o stake (em lamports) que votou no bloco em diferentes profundidades de confirmação. Valores mais altos em índices mais profundos significam maior finalidade.
  * Um array commitment null geralmente significa que o nó não possui dados para o slot, possivelmente porque é muito antigo ou foi pulado.
  * Você pode avaliar a finalidade na profundidade commitment se houver maioria qualificada (supermajority).
* **Casos de Uso Avançados:** O getBlockCommitment é para análise de finalidade detalhada. Para a maioria dos cenários comuns, confiar nos níveis padrão de commitment (processed, confirmed ou finalized) com outros métodos RPC (como getBlock e getBlockTime) é mais simples e suficiente.
* **Entendendo Commitment:** Para aproveitar ao máximo o getBlockCommitment, é essencial entender bem os níveis de commitment do Solana. Veja [Níveis de Commitment do Solana](https://www.helius.dev/blog/solana-commitment-levels) para informações detalhadas.
* **Podas:** Esteja ciente de que os nós RPC podem remover informações antigas de commitment, resultando em resultados null para slots mais antigos.

## Exemplo: Buscando Informações de Commitment de Bloco

Vamos tentar buscar informações de commitment para um número de slot ilustrativo na Devnet.
**Importante:** Os números de slot são processados rapidamente. O número de slot usado abaixo (placeholderSlot) é um espaço reservado. Você deve substituí-lo por um slot recente e confirmado que você saiba que existe na sua rede de destino (por exemplo, Devnet ou Mainnet) quando executar o exemplo. Você pode encontrar números de slot recentes usando um explorador de blocos Solana.

**Nota:** Substitua yourAPIKey pelo seu real Helius API key nos exemplos abaixo.

<CodeGroup>
  ```bash curl theme={"system"}
  # Replace 250000000 with a valid, recent slot number on Devnet/Mainnet
  curl https://mainnet.helius-rpc.com/?api-key=YOUR_API_KEY -X POST -H "Content-Type: application/json" -d \
  '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "getBlockCommitment",
    "params": [
      250000000 
    ]
  }'
  ```

  ```javascript JavaScript (using @solana/web3.js) theme={"system"}
  const { Connection } = require('@solana/web3.js');

  async function getBlockCommitmentDetails() {
    const rpcUrl = 'https://mainnet.helius-rpc.com/?api-key=YOUR_API_KEY'; // Replace YOUR_API_KEY
    const connection = new Connection(rpcUrl, 'confirmed');
    
    // Replace with a valid, recent slot number on your target network
    const slotToQuery = 250000000; 

    try {
      // Note: getBlockCommitment is not directly available in @solana/web3.js Connection object.
      // You typically need to make a direct RPC call for this method.
      // The example below shows how to construct and send such a raw request.
      const response = await fetch(rpcUrl, {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({
          jsonrpc: '2.0',
          id: 1,
          method: 'getBlockCommitment',
          params: [slotToQuery],
        }),
      });
      const result = await response.json();

      if (result.error) {
        console.error(`Error fetching block commitment for slot ${slotToQuery}:`, result.error.message);
        return;
      }

      const blockCommitment = result.result;

      if (blockCommitment) {
        console.log(`Block Commitment for Slot ${slotToQuery}:`);
        console.log(`   Total Stake (Lamports): ${blockCommitment.totalStake}`);
        console.log(`   Commitment Array:`, blockCommitment.commitment ? blockCommitment.commitment : 'Not available/Unknown block');
        // The commitment array shows lamports committed at different depths.
        // A null commitment array usually means the block is not found or too old.
        // A non-null array where later entries are higher indicates increasing finality.
      } else {
        console.log(`Block commitment data for slot ${slotToQuery} not found.`);
      }
    } catch (error) {
      console.error(`Error fetching block commitment for slot ${slotToQuery}:`, error);
    }
  }

  getBlockCommitmentDetails();
  ```

  ```typescript Kit theme={"system"}
  import { createSolanaRpc } from "@solana/kit";

  const rpc_url = "https://mainnet.helius-rpc.com/?api-key=YOUR_API_KEY";
  const rpc = createSolanaRpc(rpc_url);

  const slot_number = BigInt(5);

  let blockCommitment = await rpc.getBlockCommitment(slot_number).send();

  console.log("block commitment:", blockCommitment);
  ```
</CodeGroup>