Présentation du magasin clé-valeur : modifier une liste de surveillance sans redéploiement

Quicknode

14 septembre 2026 — 6 min de lecture

Partager

Ajouter comme source préférée

Les listes de surveillance évoluent. Un outil de suivi de portefeuille enregistre une nouvelle adresse à chaque nouvelle inscription. Un processus de conformité suit une liste de sanctions dont la mise à jour dépend du calendrier d'un tiers.

Si cette liste est intégrée à votre filtre ` Streams `, chaque modification implique une modification du code. Quelqu'un modifie un tableau et met à jour le filtre. Ou bien vous stockez les données dans une base de données distincte et vous les interrogez à chaque bloc, ce qui vous oblige à gérer et à synchroniser un système supplémentaire.

Le magasin clé-valeur fait en sorte que cette modification d'état ne se produise plus au niveau du filtre.

Elle vous propose deux types de données :

• Les listes contiennent des ensembles nommés d'éléments de type chaîne de caractères, tels que des adresses de portefeuille, des listes d'autorisations ou des critères de filtrage.

• Les valeurs contiennent un élément d'état unique que vous souhaitez suivre au fil du temps, comme le dernier bloc que vous avez traité.

Streams Les filtres peuvent effectuer des opérations de lecture et d'écriture. Les modèles de webhooks pris en charge peuvent faire référence aux listes du magasin clé-valeur par leur nom. Un backend, un script ou une application « agent » peut accéder aux mêmes données via l'API REST.

Dans le cas d'une liste de surveillance, cela signifie qu'un seul appel API peut modifier les éléments correspondants à un filtre en cours d'exécution, sans avoir à modifier ni à redéployer le filtre lui-même.

Le fait de ne plus avoir à changer les filtres n'est qu'un des avantages. Plus important encore, le responsable de la liste de suivi n'a plus besoin de modifier la logique de filtrage à chaque fois que les données changent. Une interface utilisateur, un backend ou un script peut la mettre à jour directement.

Le service de stockage clé-valeur est disponible dans toutes les formules d'Quicknode .

Consultez la documentation sur le magasin clé-valeur

Mettre à jour la liste de surveillance sans modifier le filtre

Dans un filtre « Streams », vous pouvez vérifier si plusieurs éléments figurent dans une liste à l'aide de la fonction qnLib.qnContainsListItems :

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

La méthode prend un tableau d'éléments et renvoie une valeur booléenne pour chaque élément, en respectant l'ordre du tableau d'entrée. Les filtres peuvent également être écrits en Go, où la méthode équivalente est `qn.ContainsListItems` et s'exécute de manière synchrone, sans `await`.

Ce qui importe, c'est l'emplacement de `watched_wallets` : en dehors du filtre.

Ajoutez ou supprimez une adresse de la liste : le filtre en cours d'exécution utilise alors la liste de surveillance mise à jour sans qu'il soit nécessaire de le redéployer.

Ce modèle s'applique partout où la logique de filtrage reste la même tandis que les données sur lesquelles elle s'applique changent.

Les critères de filtrage peuvent également se trouver en dehors du filtre

Les listes ne doivent pas nécessairement contenir des adresses de portefeuille.

Ils peuvent également définir les critères permettant de déterminer quels événements sont pertinents. Par exemple, une application de suivi des commandes pourrait permettre aux utilisateurs de choisir les statuts de commande qu'ils souhaitent suivre.

Au lieu d'intégrer ces statuts de manière fixe dans le filtre, vous pouvez les enregistrer dans une liste. Lorsqu'un utilisateur modifie sa sélection, mettez à jour la liste et le filtre en cours d'exécution commencera à utiliser les nouveaux critères.

Ce principe s'applique également aux listes d'autorisation, aux listes de refus, aux critères de routage, aux contrats surveillés ou à tout autre ensemble de valeurs qui évoluent indépendamment de votre logique de filtrage.

Si la modification d'un élément ne nécessite pas de modifier le filtre lui-même, cet élément est un bon candidat pour un magasin clé-valeur.

Les valeurs gèrent les états qui ne sont pas des listes

Les valeurs constituent l'autre facette d'une même idée.

Par exemple, un filtre qui doit se souvenir de l'endroit où il s'est arrêté pourrait enregistrer une valeur « lastProcessedBlock » à la fin d'un cycle d'exécution et la relire lorsque le traitement reprend.

Au lieu d'intégrer l'état évolutif dans la logique de l'application, le filtre peut le lire et le mettre à jour via un magasin clé-valeur.

Avant de l'intégrer au circuit principal

Il y a quelques points à connaître avant d'utiliser Key-Value Store au sein d'un filtre.

La recherche tient compte de la casse

Les éléments du magasin clé-valeur sont sensibles à la casse.

En ce qui concerne les adresses blockchain, veillez à ce que les valeurs soient enregistrées et vérifiées de manière cohérente. Sinon, les adresses utilisant des majuscules et des minuscules différentes risquent de ne pas correspondre comme prévu.

L'état actuel est accessible à l'échelle mondiale via Streams, Webhooks et l'API REST.

Le magasin clé-valeur permet à vos filtres d'accéder au contenu actuel d'une liste, ce qui en fait une solution idéale lorsque l'état actuel est déterminant, comme c'est le cas pour de nombreuses listes de suivi et règles de filtrage dynamiques.

Lorsque vous mettez à jour une liste, les filtres en cours d'exécution lisent le contenu mis à jour.

L'accès à l'API REST nécessite une clé API

Streams Les filtres peuvent accéder au magasin clé-valeur via le moteur d'exécution « Streams ».

Les requêtes effectuées directement via l'API REST, qu'il s'agisse de lecture ou d'écriture, nécessitent une clé API « Quicknode ».

Renseignez-vous sur les modalités d'utilisation avant l'expédition

Les lectures et les comparaisons effectuées dans le magasin clé-valeur au sein des filtres « Streams » ne consomment pas de crédits API. L'utilisation d'une liste du magasin clé-valeur avec un webhook est également gratuite.

Les opérations d'écriture sont différentes. L'ajout d'un élément à une liste ou la création d'une valeur consomme des crédits API, que l'écriture soit effectuée à partir d'un filtre « Streams » ou via l'API REST.

Les utilisations suivantes entraînent la consommation de crédits API :

• 20 crédits API par élément ajouté à la liste ou par valeur créée

• 10 crédits API par élément stocké et par mois

• 5 crédits API par requête adressée à l'API REST du magasin clé-valeur

Les limites de taille actuelles sont de 128 caractères par élément de liste et de 800 000 caractères par valeur.

Consultez la documentation relative au magasin de données clé-valeur pour connaître les tarifs et les limites les plus récents avant de définir la capacité nécessaire pour votre environnement de production.

Consultez les tarifs et les limites actuels du service de stockage clé-valeur

Obtenir une liste et la tenir à jour

Le transfert d'un tableau existant vers un magasin clé-valeur nécessite la modification d'un filtre.

Commencez par créer la liste et y ajouter des éléments :

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..."]}'

Vous pouvez créer la liste et la remplir en une seule requête.

Ensuite, modifiez le filtre pour qu'il utilise cette liste et mettez-le à jour une seule fois.

Par la suite, les modifications apportées à la liste de surveillance s'effectuent via le magasin clé-valeur plutôt que via le filtre.

Pour les modifications continues ou par lots, l'endpoint « Update List » permet d'ajouter et de supprimer plusieurs éléments en une seule requête PATCH. Il est ainsi très simple pour une interface utilisateur, un backend, un script ou une tâche d'intégration continue (CI) de maintenir la liste à jour sans avoir à modifier le filtre.

Consultez la documentation de l'API « Update List »

Les données du magasin clé-valeur sont associées au compte Quicknode plutôt qu'à un projet ou à une instance endpoint spécifique ; ainsi, les filtres Streams , Webhooks et les applications peuvent exploiter les mêmes données sous-jacentes.

Deux applications que vous pouvez cloner

La fonctionnalité « Wallet Tracking » affiche les tendances grâce à des listes de suivi de portefeuilles en temps réel sur Solana et Ethereum. Les adresses sont gérées en dehors du filtre et peuvent être mises à jour via l'interface utilisateur de l'application sans avoir à redéployer le Stream.

Exemple d'application « Wallet Tracking », présenté ici dans l'interface utilisateur de démonstration UserStream.

Consultez l'application d'exemple « Wallet Tracking »

HyperCore Order Monitor applique le même principe aux commandes « Core » d’ Hyperliquid , en utilisant des listes de stockage clé-valeur pour le filtrage dynamique des adresses et de l’état des commandes.

Consultez l'application d'exemple « HyperCore Order Monitor »

Ces deux éléments constituent des points de départ utiles si vous souhaitez voir ce modèle à l'œuvre dans une application complète.

Qu'est-ce qui est déjà considéré comme des données ?

Tout ce qui change parce qu'un utilisateur a changé d'avis ou parce qu'un autre système a publié quelque chose de nouveau mérite qu'on s'y attarde.

Les adresses de portefeuille en sont l'exemple le plus évident. Mais les listes d'autorisation, les listes de blocage, les contrats surveillés, les critères de routage, les types d'événements sélectionnés par l'utilisateur et d'autres paramètres de configuration similaires peuvent suivre le même schéma.

La distinction est simple :

Si la logique change, modifiez le filtre.

Si seules les données changent, envisagez de les conserver dans un magasin clé-valeur.

Exportez ces données une seule fois, mettez à jour le filtre, puis laissez-le évoluer de manière autonome par la suite.

Premiers pas avec le magasin clé-valeur