> ## 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.

# Transações Pré-processadas

> Fragmentos decodificados entregues via gRPC ~8 ms antes do nível de compromisso `processed`. Parte da família de produtos Shred Delivery da Helius.

<Note>
  **Beta Público.** As transações pré-processadas fazem parte da família de produtos [Shred Delivery](/docs/pt-BR/shred-delivery) da Helius. Elas estão disponíveis para qualquer assinante do plano **Professional ou superior** e são medidas em **20 créditos por 1 MB**.

  Em média, as transações pré-processadas chegam **\~8 ms mais rápido que o nível de compromisso `processed`**, ao custo de metadados de execução (veja [compromissos](#what-data-is-available) abaixo).
</Note>

As transações pré-processadas são a maneira mais rápida de receber transações Solana via gRPC. Helius decodifica fragmentos diretamente à medida que chegam ao validador e envia as transações resultantes para você, fornecendo acesso aos dados da transação milissegundos mais cedo do que qualquer assinatura pós-execução — aproximadamente **8 ms antes do nível de compromisso `processed` em média**.

Este guia explica quando usar transações pré-processadas, quais dados estão disponíveis e como se inscrever nelas usando os SDKs LaserStream (que também servem transações pré-processadas pela mesma conexão gRPC).

## Onde as transações pré-processadas se encaixam no ciclo de vida

Na arquitetura do Solana, as transações passam por várias etapas antes de serem totalmente processadas:

1. **Recepção de Fragmentos** → O validador recebe fragmentos de transação (fragmentos de dados). ← **[Fragmentos brutos (UDP)](/docs/pt-BR/shred-delivery/raw-shreds)** da Helius são entregues aqui.
2. **Decodificação de Fragmentos** → Fragmentos são decodificados em transações brutas. ← **Transações pré-processadas disponíveis aqui.**
3. **Execução de Transação** → A transação é executada pelo tempo de execução.
4. **Geração de Metadados** → Saldo pré/pós, logs e informações de erro são computados.
5. **Compromisso** → A transação atinge o estado processado/confirmado/finalizado. ← **[LaserStream gRPC](/docs/pt-BR/laserstream)** e **[LaserStream WebSocket](/docs/pt-BR/rpc/websocket)** entregam aqui.

Assinaturas pós-execução entregam dados no estágio 5 — após a execução completa e geração de metadados. Assinaturas pré-processadas entregam no estágio 2 — imediatamente após decodificar fragmentos, antes da execução ser concluída.

**O compromisso:** você recebe os dados da transação milissegundos mais cedo, mas sem metadados de execução como alterações de saldo, logs ou informações de erro.

<Warning>
  **Este é um fluxo apenas de transações.** Atualizações de estado de conta e programa não existem até que o runtime execute a transação (estágio 4). Se você precisa de atualizações de conta ou programa em tempo real — saldos de token, estado da curva de vinculação, contas de programa, qualquer coisa que não seja uma transação bruta — use **[LaserStream gRPC](/docs/pt-BR/laserstream) no compromisso `processed`**, que é a maneira mais rápida de receber mudanças de conta/programa.
</Warning>

<Tip>
  Precisa de sinais de transação ainda mais rápidos? Experimente [Pré-confirmações](/docs/pt-BR/pre-confirmations/overview) para transmitir transações agendadas e [Fragmentos Brutos (UDP)](/docs/pt-BR/shred-delivery/raw-shreds) para dados de transação não processados.
</Tip>

## Garantias de Entrega de Melhor Esforço

A entrega de transações pré-processadas é de melhor esforço, não garantida. Nosso alvo é uma taxa de entrega de 99,99%, mas algumas transações podem ser perdidas durante:

* Atualizações de infraestrutura e redistribuições
* Problemas de rede ou problemas de conectividade do validador
* Casos limites na decodificação ou processamento de fragmentos

Para aplicativos críticos que exigem entrega garantida, use [assinaturas de transação](/docs/pt-BR/laserstream/guides/decoding-transaction-data) padrão.

## Que dados estão disponíveis?

As transações pré-processadas incluem a mensagem completa da transação, mas faltam metadados de execução:

### Dados Disponíveis

* ✅ **Assinatura da transação** - Identificador único da transação
* ✅ **Chaves de conta** - Todas as contas referenciadas pela transação
* ✅ **Instruções** - Dados completos de instrução e chamadas de programa
* ✅ **Recent blockhash** - Referência de expiração da transação
* ✅ **Assinaturas** - Todas as assinaturas de transação
* ✅ **É transação de voto** - Se esta é uma transação de voto
* ✅ **Número do slot** - Qual slot continha esta transação

### Dados Ausentes

* ❌ **Metadados da transação** - Mudanças de saldos de token, saldos pré/pós, status da transação
* ❌ **Erros de transação** - Não podemos determinar se a transação falhou
* ❌ **Instruções internas** - Invocações entre programas (CPIs) não estão incluídas
* ❌ **Mensagens de log** - Logs de programa são gerados durante a execução
* ❌ **Unidades de computação consumidas** - Métricas de execução indisponíveis

Pense nas transações pré-processadas como receber a "proposta" sem o "resultado". Você vê o que o usuário tentou fazer, mas não o que realmente aconteceu.

## Suporte a SDK e Requisitos de Versão

As assinaturas de transação pré-processadas são suportadas em todos os SDKs LaserStream:

<CardGroup cols={3}>
  <Card title="JavaScript/TypeScript" icon="js" href="https://github.com/helius-labs/laserstream-sdk/tree/main/javascript">
    Versão **0.2.8** ou mais recente
  </Card>

  <Card title="Rust" icon="rust" href="https://github.com/helius-labs/laserstream-sdk/tree/main/rust">
    Versão **0.1.5** ou mais recente
  </Card>

  <Card title="Go" icon="golang" href="https://github.com/helius-labs/laserstream-sdk/tree/main/go">
    Versão **0.1.0** ou mais recente
  </Card>
</CardGroup>

***

## Exemplos de Implementação

### JavaScript/TypeScript

O SDK de JavaScript fornece uma função `subscribePreprocessed` dedicada com reconexão automática:

```typescript [expandable] theme={"system"}
import {
  subscribePreprocessed,
  CommitmentLevel,
  LaserstreamConfig,
  SubscribePreprocessedRequest,
  SubscribePreprocessedUpdate
} from 'helius-laserstream';
import bs58 from 'bs58';

async function streamPreprocessedTransactions() {
  const config: LaserstreamConfig = {
    apiKey: 'YOUR_API_KEY',
    endpoint: 'https://laserstream-mainnet-ewr.helius-rpc.com',
  };

  const request: SubscribePreprocessedRequest = {
    transactions: {
      "jupiter-swaps": {
        vote: false,
        accountInclude: ['JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4']
      }
    }
  };

  const stream = await subscribePreprocessed(
    config,
    request,
    async (update: SubscribePreprocessedUpdate) => {
      if (update.transaction) {
        const tx = update.transaction;
        const signature = bs58.encode(tx.transaction.signature);

        console.log('⚡ Preprocessed transaction received:');
        console.log(`  Signature: ${signature}`);
        console.log(`  Slot: ${tx.slot}`);
        console.log(`  Is Vote: ${tx.transaction.isVote}`);
        console.log(`  Filters: ${update.filters.join(', ')}`);
        console.log('---');
      }
    },
    async (error) => {
      console.error('Stream error:', error);
    }
  );

  console.log(`✅ Preprocessed stream started (id: ${stream.id})`);

  // Graceful shutdown
  process.on('SIGINT', () => {
    console.log('\n🛑 Shutting down stream...');
    stream.cancel();
    process.exit(0);
  });
}

streamPreprocessedTransactions().catch(console.error);
```

**Exemplo completo:** [preprocessed-transaction-sub.ts](https://github.com/helius-labs/laserstream-sdk/blob/main/javascript/examples/preprocessed-transaction-sub.ts)

### Rust

O SDK de Rust fornece desempenho nativo:

```rust [expandable] theme={"system"}
use futures::StreamExt;
use helius_laserstream::{
    grpc::{SubscribePreprocessedRequest, SubscribePreprocessedRequestFilterTransactions},
    subscribe_preprocessed, LaserstreamConfig,
};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let config = LaserstreamConfig {
        endpoint: "https://laserstream-mainnet-ewr.helius-rpc.com".to_string(),
        api_key: "YOUR_API_KEY".to_string(),
        ..Default::default()
    };

    let mut request = SubscribePreprocessedRequest::default();
    request.transactions.insert(
        "jupiter-swaps".to_string(),
        SubscribePreprocessedRequestFilterTransactions {
            vote: Some(false),
            account_include: vec![
                "JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4".to_string()
            ],
            ..Default::default()
        },
    );

    let (stream, _handle) = subscribe_preprocessed(config, request);
    tokio::pin!(stream);

    println!("✅ Preprocessed stream started");

    while let Some(result) = stream.next().await {
        match result {
            Ok(update) => {
                if let Some(tx) = update.transaction {
                    println!("⚡ Preprocessed transaction:");
                    println!("  Slot: {}", tx.slot);
                    println!("  Is Vote: {}", tx.transaction.is_vote);
                    println!("---");
                }
            }
            Err(e) => {
                eprintln!("Stream error: {:?}", e);
                break;
            }
        }
    }

    Ok(())
}
```

**Exemplo completo:** [preprocessed\_transaction\_sub.rs](https://github.com/helius-labs/laserstream-sdk/blob/main/rust/examples/preprocessed_transaction_sub.rs)

### Go

O SDK de Go fornece interfaces idiomáticas do Go:

```go [expandable] theme={"system"}
package main

import (
    "log"
    "os"
    "os/signal"
    "syscall"

    laserstream "github.com/helius-labs/laserstream-sdk/go"
    pb "github.com/helius-labs/laserstream-sdk/go/proto"
)

func main() {
    log.SetFlags(0)

    clientConfig := laserstream.LaserstreamConfig{
        Endpoint: "https://laserstream-mainnet-ewr.helius-rpc.com",
        APIKey:   "YOUR_API_KEY",
    }

    voteFilter := false
    subscriptionRequest := &pb.SubscribePreprocessedRequest{
        Transactions: map[string]*pb.SubscribePreprocessedRequestFilterTransactions{
            "jupiter-swaps": {
                Vote: &voteFilter,
                AccountInclude: []string{
                    "JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4",
                },
            },
        },
    }

    client := laserstream.NewPreprocessedClient(clientConfig)

    dataCallback := func(data *pb.SubscribePreprocessedUpdate) {
        if data.Transaction != nil {
            log.Println("⚡ Preprocessed transaction:")
            log.Printf("  Slot: %d\n", data.Transaction.Slot)
            log.Printf("  Is Vote: %t\n", data.Transaction.Transaction.IsVote)
            log.Println("---")
        }
    }

    errorCallback := func(err error) {
        log.Printf("Error: %v", err)
    }

    err := client.Subscribe(subscriptionRequest, dataCallback, errorCallback)
    if err != nil {
        log.Fatalf("Failed to subscribe: %v", err)
    }

    log.Println("✅ Preprocessed stream started")
    log.Println("Press Ctrl+C to exit")

    sigChan := make(chan os.Signal, 1)
    signal.Notify(sigChan, syscall.SIGINT, syscall.SIGTERM)
    <-sigChan

    log.Println("\nShutting down...")
    client.Close()
}
```

**Exemplo completo:** [preprocessed-transaction-sub.go](https://github.com/helius-labs/laserstream-sdk/blob/main/go/examples/preprocessed-transaction-sub.go)

***

## Estrutura de Inscrição e Filtragem

### Estrutura de Requisição

A requisição de inscrição pré-processada segue uma estrutura semelhante às inscrições padrão, mas com um conjunto focado de filtros:

```typescript theme={"system"}
interface SubscribePreprocessedRequest {
  transactions: {
    [filterName: string]: SubscribePreprocessedRequestFilterTransactions
  };
  ping?: SubscribeRequestPing;
}

interface SubscribePreprocessedRequestFilterTransactions {
  vote?: boolean;              // Include/exclude vote transactions
  signature?: string;          // Filter by specific transaction signature
  accountInclude?: string[];   // Include transactions touching these accounts
  accountExclude?: string[];   // Exclude transactions touching these accounts
  accountRequired?: string[];  // Require all these accounts to be present
}
```

### Estrutura de Resposta

As atualizações chegam com a mensagem completa da transação e metadados básicos:

```typescript theme={"system"}
interface SubscribePreprocessedUpdate {
  filters: string[];                             // Which filters matched
  transaction?: SubscribePreprocessedTransaction; // The transaction data
  ping?: SubscribeUpdatePing;                    // Keepalive ping
  pong?: SubscribeUpdatePong;                    // Ping response
  createdAt: Date;                               // When update was created
}

interface SubscribePreprocessedTransaction {
  transaction: SubscribePreprocessedTransactionInfo;
  slot: number;                                  // Slot containing transaction
}

interface SubscribePreprocessedTransactionInfo {
  signature: Uint8Array;                         // Transaction signature
  isVote: boolean;                               // Is this a vote transaction
  transaction: solana.storage.Transaction;       // Full transaction message
}
```

O campo `transaction.transaction` contém a estrutura completa da transação Solana, incluindo:

* **Mensagem** - Chaves de conta, instruções, recent blockhash
* **Assinaturas** - Todas as assinaturas de transação
* **Consultas de tabela de endereços** - Para transações versionadas

Isso é idêntico à estrutura de transação em inscrições padrão, mas sem o campo `meta` contendo os resultados de execução.