ERPC

Solana Geyser gRPC - Filtros

Solana Stream SDK
El Solana Stream SDK se ofrece como software de código abierto. Para más información, visita el repositorio de GitHub que aparece a continuación.
https://github.com/ValidatorsDAO/solana-stream

Descripción general de los filtros de gRPC

Solana Geyser gRPC usa filtros para obtener de forma eficiente solo los datos que te interesan, como cuentas, programas, transacciones, slots y bloques concretos.
A continuación se muestran ejemplos en TypeScript con el Solana Stream SDK, con una explicación clara del papel de cada filtro. La estructura y el significado de los filtros son idénticos si usas Rust.

Reglas actuales de filtros en el plan Shared

En el plan Shared actual, cualquier mapa blocks no vacío es exclusivo de Dedicated, incluso en una solicitud acotada con accountInclude o que excluya transacciones. Usa una suscripción de transacciones o blocksMeta cuando cubra lo que necesitas; ninguna de las dos equivale a un bloque completo. Para obtener bloques completos se necesita un stream de Geyser gRPC Dedicated.
Cada entrada de filtro de cuenta debe incluir account, owner o un filtro cuckoo compatible. Una condición memcmp o dataSize por sí sola no selecciona una forma de cuenta admitida. Acota la solicitud a uno de esos selectores o usa Geyser gRPC Dedicated cuando necesites un stream completo de cuentas.

Función y ejemplos de cada filtro

Suscribirse a una cuenta

Suscríbete a las actualizaciones en tiempo real de una cuenta concreta. El siguiente ejemplo se suscribe a la cuenta SOL-USDC de OpenBook con el nivel de commitment Confirmed:
typescript
import { CommitmentLevel } from '@validators-dao/solana-stream-sdk'

const request = {
  slots: { slots: {} },
  accounts: {
    'wsol/usdc': {
      account: ['8BnEgHoWFysVcuFFX7QztDmzuH8r5ZFvyP3sYwn1XTh6'],
    },
  },
  transactions: {},
  blocks: {},
  blocksMeta: {},
  accountsDataSlice: [],
  commitment: CommitmentLevel.CONFIRMED,
}
  • "wsol/usdc" es una etiqueta definida por el cliente.
  • Puedes combinar varios filtros de cuentas, programas, bloques y slots en una sola solicitud JSON.

Suscribirse a una cuenta con account_data_slice

Este ejemplo muestra cómo obtener solo una parte concreta de los datos de una cuenta. En lugar de obtener todos los datos (165 bytes) de una cuenta de token USDC, obtiene 40 bytes a partir del offset 32. Este rango incluye información como el propietario y el saldo en lamports.
typescript
import { CommitmentLevel } from '@validators-dao/solana-stream-sdk'

const request = {
  slots: {},
  accounts: {
    usdc: {
      owner: ['TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA'],
      filters: [
        {
          tokenAccountState: true,
        },
        {
          memcmp: {
            offset: 0,
            data: {
              base58: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v',
            },
          },
        },
      ],
    },
  },
  transactions: {},
  blocks: {},
  blocksMeta: {},
  entry: {},
  commitment: CommitmentLevel.CONFIRMED,
  accountsDataSlice: [{ offset: 32, length: 40 }],
}

Suscribirse a un programa

Este ejemplo muestra cómo suscribirse a las actualizaciones de las cuentas asociadas a un programa concreto.
A continuación, nos suscribimos a las actualizaciones de las cuentas propiedad del programa Solend, con el nivel de commitment Processed.
typescript
import { CommitmentLevel } from '@validators-dao/solana-stream-sdk'

const request = {
  slots: {
    slots: {},
  },
  accounts: {
    solend: {
      owner: ['So1endDq2YkqhipRh3WViPa8hdiSpxWy6z3Z6tMCpAo'],
    },
  },
  transactions: {},
  blocks: {},
  blocksMeta: {},
  accountsDataSlice: [],
  commitment: CommitmentLevel.PROCESSED,
}
  • "solend" es una etiqueta personalizada que el cliente puede definir libremente.
  • Para suscribirte a varios programas, consulta la siguiente sección, "Suscribirse a varios programas".

Suscribirse a varios programas

Este ejemplo muestra cómo suscribirse a la vez a las actualizaciones de las cuentas asociadas a varios programas.
El siguiente ejemplo se suscribe a las actualizaciones de las cuentas propiedad de los programas Solend y Serum.
typescript
import { CommitmentLevel } from '@validators-dao/solana-stream-sdk'

const request = {
  slots: {
    slots: {},
  },
  accounts: {
    programs: {
      owner: [
        'So1endDq2YkqhipRh3WViPa8hdiSpxWy6z3Z6tMCpAo',
        '9xQeWvG816bUx9EPjHmaT23yvVM2ZWbrrpZb9PusVFin',
      ],
    },
  },
  transactions: {},
  blocks: {},
  blocksMeta: {},
  accountsDataSlice: [],
  commitment: CommitmentLevel.PROCESSED,
}
Si prefieres asignar una etiqueta distinta a cada programa, usa el siguiente enfoque:
typescript
import { CommitmentLevel } from '@validators-dao/solana-stream-sdk'

const request = {
  slots: {
    slots: {},
  },
  accounts: {
    solend: {
      owner: ['So1endDq2YkqhipRh3WViPa8hdiSpxWy6z3Z6tMCpAo'],
    },
    serum: {
      owner: ['9xQeWvG816bUx9EPjHmaT23yvVM2ZWbrrpZb9PusVFin'],
    },
  },
  transactions: {},
  blocks: {},
  blocksMeta: {},
  accountsDataSlice: [],
  commitment: CommitmentLevel.PROCESSED,
}

Suscribirse a todas las transacciones finalizadas que no son de voto ni fallidas

Este ejemplo muestra cómo suscribirse a todas las transacciones con el nivel de commitment Finalized, excluyendo las transacciones de voto y las fallidas.
typescript
import { CommitmentLevel } from '@validators-dao/solana-stream-sdk'

const request = {
  slots: {
    slots: {},
  },
  accounts: {},
  transactions: {
    alltxs: {
      vote: false,
      failed: false,
    },
  },
  blocks: {},
  blocksMeta: {},
  accountsDataSlice: [],
  commitment: CommitmentLevel.FINALIZED,
}
  • vote: false excluye las transacciones de voto.
  • failed: false excluye las transacciones fallidas.
  • Si dejas los campos vacíos, se obtienen todas las transacciones.
  • Si especificas varios campos, se combinan con una condición AND.

Suscribirse a transacciones que no son de voto y que mencionan una cuenta

Este ejemplo muestra cómo suscribirse a las transacciones que involucran una cuenta concreta, excluyendo las transacciones de voto.
El siguiente ejemplo se suscribe a las transacciones que no son de voto y que mencionan cuentas asociadas al programa Serum.
typescript
import { CommitmentLevel } from '@validators-dao/solana-stream-sdk'

const request = {
  slots: {
    slots: {},
  },
  accounts: {},
  transactions: {
    serum: {
      vote: false,
      accountInclude: ['9xQeWvG816bUx9EPjHmaT23yvVM2ZWbrrpZb9PusVFin'],
    },
  },
  blocks: {},
  blocksMeta: {},
  accountsDataSlice: [],
  commitment: CommitmentLevel.PROCESSED,
}

Suscribirse a transacciones excluyendo cuentas

Este ejemplo muestra cómo suscribirse a transacciones excluyendo las que involucran cuentas concretas.
El siguiente ejemplo obtiene las transacciones excluyendo cualquier cuenta propiedad de los programas Serum y Tokenkeg.
typescript
import { CommitmentLevel } from '@validators-dao/solana-stream-sdk'

const request = {
  slots: {
    slots: {},
  },
  accounts: {},
  transactions: {
    serum: {
      accountExclude: [
        '9xQeWvG816bUx9EPjHmaT23yvVM2ZWbrrpZb9PusVFin',
        'TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA',
      ],
    },
  },
  blocks: {},
  blocksMeta: {},
  accountsDataSlice: [],
  commitment: CommitmentLevel.PROCESSED,
}

Suscribirse a transacciones que mencionan unas cuentas y excluyen otras

Este ejemplo muestra cómo suscribirse a las transacciones que involucran determinadas cuentas y, a la vez, excluir explícitamente otras cuentas especificadas.
El siguiente ejemplo se suscribe a las transacciones que mencionan la cuenta de Serum, pero excluye una cuenta especificada:
typescript
import { CommitmentLevel } from '@validators-dao/solana-stream-sdk'

const request = {
  slots: {
    slots: {},
  },
  accounts: {},
  transactions: {
    serum: {
      accountInclude: ['9xQeWvG816bUx9EPjHmaT23yvVM2ZWbrrpZb9PusVFin'],
      accountExclude: ['9wFFyRfZBsuAha4YcuxcXLKwMxJR43S7fPfQLusDBzvT'],
    },
  },
  blocks: {},
  blocksMeta: {},
  accountsDataSlice: [],
  commitment: CommitmentLevel.PROCESSED,
}

Suscribirse a una firma de transacción

Este ejemplo muestra cómo suscribirse a las actualizaciones en tiempo real de una firma de transacción concreta hasta que alcance el estado Confirmed o Finalized.
typescript
import { CommitmentLevel } from '@validators-dao/solana-stream-sdk'

const request = {
  slots: {},
  accounts: {},
  transactions: {
    sign: {
      signature:
        '5rp2hL9b6kexex11Mugfs3vfU9GhieKruj4CkFFSnu52WLxiGn4VcLLwsB62XURhMmT1j4CZiXT6FFtYbXsLq2Zs',
    },
  },
  blocks: {},
  blocksMeta: {},
  accountsDataSlice: [],
  commitment: CommitmentLevel.PROCESSED,
}

Suscribirse a slots

Este ejemplo muestra cómo suscribirse a las notificaciones de los slots entrantes. No hace falta ningún detalle adicional aparte de asignar un nombre de etiqueta personalizado:
typescript
import { CommitmentLevel } from '@validators-dao/solana-stream-sdk'

const request = {
  slots: {
    incoming_slots: {},
  },
  accounts: {},
  transactions: {},
  blocks: {},
  blocksMeta: {},
  accountsDataSlice: [],
  commitment: CommitmentLevel.PROCESSED,
}

Suscribirse a bloques (solo Dedicated en el plan Shared actual)

Suscríbete a las actualizaciones en tiempo real de todos los bloques generados. De forma predeterminada, se obtienen todas las transacciones de cada bloque:
typescript
import { CommitmentLevel } from '@validators-dao/solana-stream-sdk'

const request = {
  slots: {},
  accounts: {},
  transactions: {},
  blocks: {
    blocks: {},
  },
  blocksMeta: {},
  accountsDataSlice: [],
  commitment: CommitmentLevel.PROCESSED,
}

Para excluir las transacciones y obtener solo la información actualizada de las cuentas (solo Dedicated en el plan Shared actual):

typescript
import { CommitmentLevel } from '@validators-dao/solana-stream-sdk'

const request = {
  slots: {},
  accounts: {},
  transactions: {},
  blocks: {
    blocks: {
      includeTransactions: false,
      includeAccounts: true,
    },
  },
  blocksMeta: {},
  accountsDataSlice: [],
  commitment: CommitmentLevel.PROCESSED,
}

Para obtener solo las transacciones/cuentas que involucran cuentas concretas (solo Dedicated en el plan Shared actual):

typescript
import { CommitmentLevel } from '@validators-dao/solana-stream-sdk'

const request = {
  slots: {},
  accounts: {},
  transactions: {},
  blocks: {
    blocks: {
      accountInclude: ['So1endDq2YkqhipRh3WViPa8hdiSpxWy6z3Z6tMCpAo'],
    },
  },
  blocksMeta: {},
  accountsDataSlice: [],
  commitment: CommitmentLevel.PROCESSED,
}

Suscribirse a los metadatos de bloque

Suscríbete solo a las notificaciones de metadatos de bloque cuando se procesan los bloques. No incluye los datos detallados de las transacciones.
typescript
import { CommitmentLevel } from '@validators-dao/solana-stream-sdk'

const request = {
  slots: {},
  accounts: {},
  transactions: {},
  blocks: {},
  blocksMeta: {
    blockmetadata: {},
  },
  accountsDataSlice: [],
  commitment: CommitmentLevel.PROCESSED,
}

Gestión de los niveles de commitment

El stream de Solana Geyser gRPC usa de forma predeterminada el nivel de commitment Processed.
Puedes especificar niveles de commitment más altos, como Confirmed o Finalized. En esos casos, Geyser almacena los datos en un búfer y envía las notificaciones cuando se alcanza el nivel de commitment especificado.
Para obtener el máximo rendimiento, se recomienda gestionar los niveles de commitment en el lado del cliente.
Así se especifican los niveles de commitment:
typescript
import { CommitmentLevel } from '@validators-dao/solana-stream-sdk'

enum CommitmentLevel {
  PROCESSED = 0,
  CONFIRMED = 1,
  FINALIZED = 2,
}
  • PROCESSED: Datos inmediatos tras el procesamiento. Se obtienen rápido, pero todavía no están confirmados.
  • CONFIRMED: Datos confirmados por el clúster, con mayor certeza.
  • FINALIZED: Datos totalmente finalizados, sin riesgo de reorganización.

Ventajas de trabajar con Processed

La principal ventaja del nivel de commitment Processed es que las transacciones se obtienen de inmediato, lo que permite procesarlas rápidamente en el lado del cliente. Después, los clientes pueden detectar las transiciones a Confirmed o Finalized, con una respuesta rápida.

Cómo gestionar Confirmed y Finalized

Cuando uses los niveles Confirmed o Finalized, los eventos (transacciones o actualizaciones de cuentas) deben almacenarse en un búfer por slot.
Almacena los eventos en un búfer slot por slot, suscríbete a las notificaciones de slots y libera los eventos del búfer cuando un slot concreto alcance el commitment deseado (Confirmed o Finalized).
Al principio, los eventos se recibirán antes de que el slot alcance Confirmed o Finalized.

La particularidad de Finalized

Debido a las especificaciones de Solana Geyser, no todos los slots reciben una notificación explícita de finalización. Por eso, cuando recibas una notificación de finalización para un slot, debes tratar todos sus slots antecesores como finalizados, aunque no hayas recibido notificaciones explícitas para ellos.
En concreto, al recibir una notificación de finalización, trata de forma retroactiva todos los slots antecesores como finalizados.
AnteriorComparación de velocidadSiguienteEjemplos de código