Solana Geyser gRPC - Filters

Solana Stream SDK
De Solana Stream SDK wordt aangeboden als opensourcesoftware. Ga voor meer informatie naar de GitHub-repository hieronder.

Overzicht van gRPC-filters

Solana Geyser gRPC gebruikt filters om efficiënt alleen de data op te halen die je interesseert, zoals specifieke accounts, programma's, transacties, slots en blocks.
Hieronder geven we TypeScript-voorbeelden met de Solana Stream SDK en leggen we duidelijk uit welke rol elk filter precies heeft. Met Rust zijn de structuur en de betekenis van de filters identiek.

Rol en voorbeelden van elk filter

Abonneren op een account

Abonneer je op realtime updates voor een specifiek account. Het volgende voorbeeld abonneert zich op het SOL-USDC-account van OpenBook op het commitmentniveau 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" is een label dat de client zelf definieert.
  • Meerdere filters voor accounts, programma's, blocks en slots kunnen in één JSON-request worden gecombineerd.

Abonneren op een account met account_data_slice

Dit voorbeeld laat zien hoe je slechts een specifiek deel van de accountdata ophaalt. In plaats van alle data (165 bytes) van een USDC-tokenaccount op te halen, haalt het 40 bytes op vanaf offset 32. Dit bereik bevat informatie zoals de eigenaar en het saldo in 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 }],
}

Abonneren op een programma

Dit voorbeeld laat zien hoe je je abonneert op accountupdates die bij een specifiek programma horen.
Hieronder abonneren we ons op accountupdates voor accounts die eigendom zijn van het Solend-programma, op het commitmentniveau 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" is een eigen label dat de client vrij kan kiezen.
  • Wil je je op meerdere programma's abonneren, zie dan de volgende sectie, "Abonneren op meerdere programma's".

Abonneren op meerdere programma's

Dit voorbeeld laat zien hoe je je in één keer abonneert op accountupdates die bij meerdere programma's horen.
Het onderstaande voorbeeld abonneert zich op updates voor accounts die eigendom zijn van zowel het Solend- als het Serum-programma.
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,
}
Wil je liever elk programma een eigen label geven, gebruik dan de volgende aanpak:
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,
}

Abonneren op alle gefinaliseerde transacties, zonder vote- en mislukte transacties

Dit voorbeeld laat zien hoe je je abonneert op alle transacties op het commitmentniveau Finalized, met uitzondering van vote-transacties en mislukte transacties.
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 sluit vote-transacties uit.
  • failed: false sluit mislukte transacties uit.
  • Als velden leeg blijven, worden alle transacties opgehaald.
  • Als je meerdere velden opgeeft, gelden ze samen als een AND-voorwaarde.

Abonneren op niet-vote-transacties waarin een account voorkomt

Dit voorbeeld laat zien hoe je je abonneert op transacties waarbij een specifiek account betrokken is, met uitzondering van vote-transacties.
Het onderstaande voorbeeld abonneert zich op niet-vote-transacties waarin accounts voorkomen die bij het Serum-programma horen.
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,
}

Abonneren op transacties met uitsluiting van accounts

Dit voorbeeld laat zien hoe je je abonneert op transacties, met uitzondering van transacties waarbij specifieke accounts betrokken zijn.
Het onderstaande voorbeeld haalt transacties op met uitsluiting van alle accounts die eigendom zijn van de programma's Serum en 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,
}

Abonneren op transacties waarin accounts voorkomen, met uitsluiting van bepaalde accounts

Dit voorbeeld laat zien hoe je je abonneert op transacties waarbij bepaalde accounts betrokken zijn, terwijl je andere opgegeven accounts expliciet uitsluit.
Het onderstaande voorbeeld abonneert zich op transacties waarin het account van Serum voorkomt, maar sluit een opgegeven account uit:
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,
}

Abonneren op een transactiehandtekening

Dit voorbeeld laat zien hoe je je abonneert op realtime updates voor een specifieke transactiehandtekening, totdat die de status Confirmed of Finalized bereikt.
typescript
import { CommitmentLevel } from '@validators-dao/solana-stream-sdk'

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

Abonneren op slots

Dit voorbeeld laat zien hoe je je abonneert op meldingen van binnenkomende slots. Behalve het toekennen van een eigen tagnaam zijn er geen verdere gegevens nodig:
typescript
import { CommitmentLevel } from '@validators-dao/solana-stream-sdk'

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

Abonneren op blocks

Abonneer je op realtime updates van alle gegenereerde blocks. Standaard worden alle transacties binnen een block opgehaald:
typescript
import { CommitmentLevel } from '@validators-dao/solana-stream-sdk'

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

Transacties uitsluiten en alleen bijgewerkte accountinformatie ophalen:

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,
}

Alleen transacties/accounts ophalen waarbij specifieke accounts betrokken zijn:

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

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

Abonneren op blockmetadata

Abonneer je alleen op meldingen van blockmetadata wanneer blocks worden verwerkt. Gedetailleerde transactiedata wordt niet meegestuurd.
typescript
import { CommitmentLevel } from '@validators-dao/solana-stream-sdk'

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

Commitmentniveaus beheren

De Solana Geyser gRPC-stream gebruikt standaard het commitmentniveau Processed.
Je kunt hogere commitmentniveaus opgeven, zoals Confirmed of Finalized. In die gevallen buffert Geyser de data en verstuurt het meldingen zodra het opgegeven commitmentniveau is bereikt.
Voor maximale prestaties wordt aanbevolen om commitmentniveaus aan de clientzijde te beheren.
Zo geef je commitmentniveaus op:
typescript
import { CommitmentLevel } from '@validators-dao/solana-stream-sdk'

enum CommitmentLevel {
  PROCESSED = 0,
  CONFIRMED = 1,
  FINALIZED = 2,
}
  • PROCESSED: data direct na verwerking. Snel op te halen, maar nog niet bevestigd.
  • CONFIRMED: data die door het cluster is bevestigd, wat meer zekerheid biedt.
  • FINALIZED: volledig gefinaliseerde data zonder risico op reorganisatie.

Voordelen van werken op Processed

Het belangrijkste voordeel van het commitmentniveau Processed is dat transacties direct worden opgehaald, zodat de client ze snel kan verwerken. Clients kunnen daarna overgangen naar Confirmed of Finalized detecteren, wat zorgt voor een snelle reactie.

Confirmed en Finalized beheren

Als je de niveaus Confirmed of Finalized gebruikt, zouden events (transacties of accountupdates) per slot gebufferd moeten worden.
Buffer events per slot, abonneer je op slotmeldingen en geef events vrij uit de buffer zodra een bepaald slot het gewenste commitment (Confirmed of Finalized) bereikt.
Events komen in eerste instantie binnen voordat een slot Confirmed of Finalized bereikt.

Het bijzondere aan Finalized

Door de specificaties van Solana Geyser krijgen niet alle slots een expliciete finalized-melding. Wanneer je voor een slot een finalized-melding ontvangt, moet je daarom alle voorouderslots als gefinaliseerd behandelen, ook als je daarvoor niet expliciet een melding hebt ontvangen.
Concreet: behandel na ontvangst van een finalized-melding met terugwerkende kracht alle voorouderslots als gefinaliseerd.