Einführung in den Schlüssel-Wert-Speicher: Eine Beobachtungsliste ändern, ohne die Anwendung neu bereitzustellen

Quicknode

14. September 2026 – 6 Minuten Lesezeit

Teilen

Als bevorzugte Quelle hinzufügen

Beobachtungslisten ändern sich. Ein Portfolio-Tracker erhält jedes Mal eine neue Adresse, wenn sich jemand anmeldet. Eine Compliance-Pipeline orientiert sich an einer Sanktionsliste, die nach dem Zeitplan eines anderen aktualisiert wird.

Wenn sich diese Liste in Ihrem „ Streams “-Filter befindet, wird jede Änderung zu einer Codeänderung. Jemand bearbeitet ein Array und aktualisiert den Filter. Oder Sie speichern die Daten in einer separaten Datenbank und fragen sie bei jedem Block ab, wodurch Sie ein weiteres System betreiben und abgleichen müssen.

Der Key-Value-Store verlagert diese Zustandsänderung aus dem Filter heraus.

Es stellt Ihnen zwei Datentypen zur Verfügung:

• Listen enthalten benannte Sammlungen von Zeichenfolgenelementen, wie beispielsweise Wallet-Adressen, Zulassungslisten oder Filterkriterien.

• Werte enthalten einen einzelnen Zustand, den Sie im Laufe der Zeit verfolgen möchten, beispielsweise den zuletzt verarbeiteten Block.

Streams Filter können sowohl lesen als auch schreiben. Unterstützte Webhook-Vorlagen können über den Namen auf Listen im Schlüssel-Wert-Speicher verweisen. Ein Backend, ein Skript oder ein „ agent “ kann über die REST-API auf dieselben Daten zugreifen.

Für eine Beobachtungsliste bedeutet dies, dass ein einziger API-Aufruf die Treffer eines laufenden Filters ändern kann, ohne dass der Filter selbst geändert oder neu bereitgestellt werden muss.

Der Verzicht auf Filterwechsel ist nur ein Teil des Vorteils. Noch wichtiger ist, dass der Verantwortliche für die Beobachtungsliste die Filterlogik nicht mehr jedes Mal anpassen muss, wenn sich die Daten ändern. Eine Benutzeroberfläche, das Backend oder ein Skript können die Filterlogik direkt aktualisieren.

Der Key-Value-Store ist in jedem „ Quicknode “-Tarif enthalten.

Lesen Sie die Dokumentation zum Key-Value-Store

Die Beobachtungsliste aktualisieren, ohne den Filter zu verändern

Innerhalb eines „ Streams “-Filters können Sie mit qnLib.qnContainsListItems mehrere Elemente anhand einer Liste überprüfen:

async function main(payload) {
  const addresses = payload.data.flatMap(block =>
    block.transactions.flatMap(tx => [tx.from, tx.to])
  );
  const hits = await qnLib.qnContainsListItems(
    "watched_wallets",
    addresses
  );
  return hits.some(Boolean) ? payload.data : null;
}

Die Methode nimmt ein Array von Elementen entgegen und gibt für jedes Element einen booleschen Wert zurück, der auf das Eingabe-Array abgestimmt ist. Filter können auch in Go geschrieben werden; dort lautet die entsprechende Methode „qn.ContainsListItems“ und wird synchron ohne „await“ ausgeführt.

Das Wichtigste ist, wo sich „watched_wallets“ befindet: außerhalb des Filters.

Fügen Sie eine Adresse zur Liste hinzu oder entfernen Sie sie daraus – der laufende Filter verwendet die aktualisierte Beobachtungsliste, ohne dass eine erneute Bereitstellung erforderlich ist.

Dieses Muster funktioniert überall dort, wo die Filterlogik gleich bleibt, während sich die Daten, auf die sie angewendet wird, ändern.

Filterkriterien können auch außerhalb des Filters stehen

Listen müssen keine Wallet-Adressen enthalten.

Sie können auch die Kriterien enthalten, anhand derer bestimmt wird, welche Ereignisse von Bedeutung sind. Beispielsweise könnte eine Anwendung zur Auftragsüberwachung den Benutzern die Möglichkeit bieten, auszuwählen, welche Auftragsstatus sie verfolgen möchten.

Anstatt diese Status fest im Filter zu hinterlegen, können Sie sie in einer Liste speichern. Wenn ein Benutzer seine Auswahl ändert, aktualisieren Sie die Liste, und der aktive Filter wendet fortan die neuen Kriterien an.

Das Gleiche gilt für Zulassungslisten, Sperrlisten, Routing-Kriterien, überwachte Verträge oder andere Wertemengen, die sich unabhängig von Ihrer Filterlogik ändern.

Wenn eine Änderung nicht mit einer Änderung des Filters selbst einhergehen sollte, ist dies ein guter Kandidat für einen Schlüssel-Wert-Speicher.

Werte verarbeiten, deren Status keine Liste ist

Werte sind die Kehrseite desselben Gedankens.

Ein Filter, der sich beispielsweise merken muss, wo er aufgehört hat, könnte am Ende eines Durchlaufs einen Wert für „lastProcessedBlock“ schreiben und diesen bei Wiederaufnahme der Verarbeitung wieder einlesen.

Anstatt den sich ändernden Status in die Anwendungslogik einzubinden, kann der Filter ihn über einen Schlüssel-Wert-Speicher auslesen und aktualisieren.

Bevor du es in den „Hot Path“ einfügst

Bevor Sie den Schlüssel-Wert-Speicher innerhalb eines Filters verwenden, sollten Sie einige Dinge beachten.

Bei der Suche wird zwischen Groß- und Kleinschreibung unterschieden

Bei Elementen im Schlüssel-Wert-Speicher wird zwischen Groß- und Kleinschreibung unterschieden.

Stellen Sie bei Blockchain-Adressen sicher, dass die Werte einheitlich gespeichert und überprüft werden. Andernfalls stimmen Adressen mit unterschiedlicher Groß-/Kleinschreibung möglicherweise nicht wie erwartet überein.

Der aktuelle Status ist weltweit über Streams, Webhooks und die REST-API verfügbar.

Mit dem Schlüssel-Wert-Speicher haben Ihre Filter Zugriff auf den aktuellen Inhalt einer Liste. Daher eignet er sich hervorragend, wenn es auf den aktuellen Zustand ankommt – was bei vielen Beobachtungslisten und dynamischen Filterregeln der Fall ist.

Wenn Sie eine Liste aktualisieren, lesen die ausgeführten Filter den aktualisierten Inhalt ein.

Für den Zugriff auf die REST-API ist ein API-Schlüssel erforderlich

Streams Filter können über die „ Streams “-Laufzeitumgebung auf den Key-Value-Store zugreifen.

Für Anfragen, die direkt über die REST-API gestellt werden – egal ob Lese- oder Schreibzugriffe –, ist ein API-Schlüssel von Quicknode erforderlich.

Machen Sie sich vor dem Versand mit der Verwendung vertraut

Lesevorgänge und Vergleiche im Key-Value-Store innerhalb von „ Streams “-Filtern verbrauchen keine API-Credits. Die Verwendung einer Key-Value-Store-Liste mit einem Webhook ist ebenfalls kostenlos.

Schreibvorgänge sind unterschiedlich. Das Hinzufügen eines Listenelements oder das Anlegen eines Werts verbraucht API-Credits, unabhängig davon, ob der Schreibvorgang über einen „ Streams “-Filter oder über die REST-API erfolgt.

Die folgende Nutzung verbraucht API-Guthaben:

• 20 API-Gutschriften pro hinzugefügtem Listenelement oder erstellten Wert

• 10 API-Gutschriften pro gespeichertem Artikel pro Monat

• 5 API-Credits pro REST-API-Anfrage an den Key-Value-Store

Derzeit gelten folgende Größenbeschränkungen: 128 Zeichen pro Listenelement und 800.000 Zeichen pro Wert.

Informieren Sie sich in der Dokumentation zum Key-Value-Store über die aktuellen Preise und Limits, bevor Sie die Kapazitäten für den Produktivbetrieb festlegen.

Aktuelle Preise und Limits für den Key-Value-Store anzeigen

Eine Liste erstellen und auf dem neuesten Stand halten

Um ein bestehendes Array in den Key-Value-Store zu verschieben, ist eine Filteränderung erforderlich.

Erstellen Sie zunächst die Liste und füllen Sie sie mit Anfangswerten:

curl -X POST "https://api.quicknode.com/kv/rest/v1/lists" \
 -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"key":"watched_wallets","items":["0x8f3c...","0x41be..."]}'

Sie können die Liste erstellen und mit Daten füllen – und das alles in einem einzigen Aufruf.

Ändern Sie dann den Filter so, dass er aus dieser Liste liest, und aktualisieren Sie ihn einmal.

Danach erfolgen Änderungen an der Beobachtungsliste über den Schlüssel-Wert-Speicher und nicht mehr über den Filter.

Bei fortlaufenden oder stapelweisen Änderungen können mit dem Update-List- endpoint -Aufruf mehrere Elemente in einer einzigen PATCH-Anfrage hinzugefügt oder entfernt werden. Dadurch ist es für eine Benutzeroberfläche, ein Backend, ein Skript oder einen CI-Job ganz einfach, die Liste auf dem neuesten Stand zu halten, ohne den Filter zu verändern.

Lesen Sie die Dokumentation zur Update-List-API

Die Daten im Key-Value-Store sind auf das „ Quicknode “-Konto beschränkt und nicht auf ein einzelnes Projekt oder „ endpoint “; daher können „ Streams “-Filter, „ Webhooks “ und Anwendungen auf denselben zugrunde liegenden Daten basieren.

Zwei Apps, die du klonen kannst

„Wallet Tracking“ zeigt das Muster anhand von Live-Wallet-Beobachtungslisten auf Solana und Ethereum an. Die Adressen werden außerhalb des Filters verwaltet und können über die Benutzeroberfläche der Anwendung aktualisiert werden, ohne dass der Stream neu bereitgestellt werden muss.

Beispiel-App „Wallet Tracking“, hier in der UserStream-Demo-Benutzeroberfläche dargestellt.

Beispiel-App „Wallet Tracking“ anzeigen

Der HyperCore Order Monitor wendet dasselbe Prinzip auf „ Hyperliquid “-Core-Aufträge an und nutzt dabei Key-Value-Store-Listen für die dynamische Filterung nach Adressen und Auftragsstatus.

Beispiel-App „HyperCore Order Monitor“ anzeigen

Beides sind nützliche Ausgangspunkte, wenn Sie das Muster in einer vollständigen Anwendung in Aktion sehen möchten.

Was gilt sonst noch als Daten?

Alles, was sich ändert, weil ein Nutzer seine Meinung geändert hat oder weil ein anderes System etwas Neues veröffentlicht hat, ist einen Blick wert.

Wallet-Adressen sind das naheliegendste Beispiel. Aber auch Whitelists, Blacklists, überwachte Verträge, Routing-Kriterien, vom Benutzer ausgewählte Ereignistypen und ähnliche Konfigurationen können demselben Muster folgen.

Der Unterschied ist ganz einfach:

Wenn sich die Logik ändert, passen Sie den Filter an.

Wenn sich nur die Daten ändern, sollten Sie in Erwägung ziehen, diese in einem Schlüssel-Wert-Speicher zu speichern.

Exportieren Sie diese Daten einmal, passen Sie den Filter an und lassen Sie ihn sich danach eigenständig anpassen.

Erste Schritte mit dem Schlüssel-Wert-Speicher