キーバリューストアのご紹介：再デプロイせずにウォッチリストを変更する

Quicknode

2026年9月14日 — 読了時間6分

シェア

「お気に入り」として追加

ウォッチリストは変動する。ポートフォリオ追跡ツールは、誰かが登録するたびにアドレスが1つ追加される。コンプライアンスのパイプラインは、他者が設定したスケジュールに従って更新される制裁リストに基づいて処理が行われる。

そのリストがStreams フィルター内に存在する場合、変更のたびにコードの変更が必要になります。誰かが配列を編集してフィルターを更新したり、データを別のデータベースに保存して各ブロックごとにクエリを実行したりすることになり、運用や整合性の確保が必要なシステムがさらに一つ増えてしまいます。

キーバリューストアは、その状態の変化をフィルタの外側に移します。

2つのデータ型が提供されます：

• リストには、ウォレットアドレス、許可リスト、フィルタリング条件など、名前が付けられた文字列項目の集合が格納されます。

• 値には、処理した最後のブロックなど、時間の経過とともに追跡したい単一の状態情報が格納されます。

Streams フィルターは読み取りと書き込みの両方が可能です。サポートされているWebhookテンプレートでは、キーバリューストアのリストby nameを参照できます。バックエンド、スクリプト、または エージェント は、REST API を通じて同じデータにアクセスできます。

ウォッチリストの場合、これは、1回のAPI呼び出しだけで、フィルター自体を変更したり再デプロイしたりすることなく、実行中のフィルターが一致する対象を変更できることを意味します。

フィルタの変更を回避できるのは、メリットの一部に過ぎません。さらに重要なのは、ウォッチリストの管理者が、データが変更されるたびにフィルタリングロジックを変更する必要がなくなることです。UI、バックエンド、またはスクリプトから直接更新することができます。

キーバリューストアは、すべてのQuicknode プランで利用可能です。

キーバリューストアのドキュメントを読む

フィルタを変更せずにウォッチリストを更新する

Streams フィルター内では、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;
}

このメソッドは項目の配列を受け取り、入力配列と対応する各項目についてブール値を返します。フィルタはGo言語でも記述可能で、同等のメソッドはqn.ContainsListItemsであり、awaitを使用せずに同期的に実行されます。

重要なのは、`watched_wallets`がどこにあるかという点です。つまり、フィルターの外側にあるということです。

リストにアドレスを追加または削除すると、実行中のフィルターは再デプロイを行わなくても、更新されたウォッチリストを使用します。

このパターンは、フィルタリングのロジックが同じままで、処理対象となるデータが変わるあらゆる場面で有効です。

フィルタリング条件は、フィルタの外に設定することも可能です

リストにはウォレットアドレスを含める必要はありません。

また、どのイベントが重要かを決定する基準を保持することもできます。たとえば、注文管理アプリケーションでは、ユーザー が追跡したい注文ステータスを選択できるようにする場合があります。

これらのステータスをフィルタにハードコーディングする代わりに、リストに格納することができます。ユーザー が選択を変更した際には、リストを更新すると、実行中のフィルタが新しい条件に基づいて動作するようになります。

この考え方は、許可リスト、拒否リスト、ルーティング基準、監視対象の契約、あるいはフィルタリングロジックとは独立して変更されるその他の値のセットにも当てはまります。

何かを変更する際にフィルター自体を変更する必要がないのであれば、それはキーバリューストアに適した候補と言えます。

Valuesは、リストではない状態を処理します

価値観とは、同じ考え方のもう一方の側面を指します。

たとえば、処理を中断した箇所を記憶しておく必要があるフィルタの場合、実行終了時に「lastProcessedBlock」という値を書き込み、処理を再開する際にその値を再度読み込むことができます。

アプリケーションロジックに状態の変化を組み込む代わりに、フィルターはキーバリューストアを通じてその状態を読み取り、更新することができます。

ホットパスに入れる前に

フィルター内でキーバリューストアを使用する前に、知っておくべき点がいくつかあります。

マッチングでは大文字と小文字が区別されます

キーバリューストアの項目は、大文字と小文字が区別されます。

ブロックチェーン のアドレスについては、値の一貫した保存と確認を行ってください。そうしないと、大文字・小文字が異なるアドレス同士が、期待どおりに一致しない可能性があります。

現在の状態は、Streams 、Webhooks 、およびREST APIを通じてグローバルに利用可能です。

キーバリューストアを使用すると、フィルターからリストの現在の内容にアクセスできるようになるため、現在の状態が重要な場合に最適です。これは、多くのウォッチリストや動的なフィルタリングルールに当てはまります。

リストを更新すると、実行中のフィルターは更新された内容を読み取ります。

REST APIにアクセスするには、APIキーが必要です

Streams フィルターは、Streams ランタイムを通じてキーバリューストアにアクセスできます。

REST APIを介して直接行われるリクエスト（読み取り・書き込みを問わず）には、Quicknode のAPIキーが必要です。

発送する前に使用方法をよく理解してください

Streams のフィルター内でのキーバリューストアの読み取りおよび比較処理には、APIクレジットは消費されません。また、Webhookと組み合わせてキーバリューストアのリストを使用する場合も無料です。

書き込み処理は異なります。リスト項目の追加や値の作成は、Streams フィルターから行われる場合でも、REST APIを通じて行われる場合でも、APIクレジットが消費されます。

以下の使用方法では、APIクレジットが消費されます：

• リスト項目1件の追加または価値の創出につき、20 APIクレジットが付与されます

• 保存されたアイテム1件につき、毎月10 APIクレジット

• キーバリューストアのREST APIリクエスト1件につき、APIクレジット5クレジット

現在のサイズ制限は、リスト項目あたり128文字、値あたり800,000文字となっています。

本番環境での利用規模を決定する前に、キーバリューストアのドキュメントで最新の料金体系と利用制限を確認してください。

キーバリューストアの現在の料金と利用制限を確認する

リストを入手し、常に最新の状態に保つ

既存のアレイをキーバリューストアに移行するには、フィルタを1つ変更する必要があります。

まず、リストを作成して初期データを設定します：

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

1回のリクエストでリストを作成し、データを初期設定することができます。

次に、そのリストから読み込むようにフィルタを変更し、一度更新してください。

その後、ウォッチリストへの変更は、フィルターを経由するのではなく、キーバリューストアを通じて行われます。

継続的な変更や一括変更の場合、Update Listエンドポイント を使用すれば、1回のPATCHリクエストで複数の項目を追加・削除できます。これにより、UI、バックエンド、スクリプト、またはCIジョブにおいて、フィルタを変更することなくリストを最新の状態に保つことが容易になります。

「Update List API」のドキュメントを参照してください

Quicknode キーバリューストアのデータは、単一のプロジェクトや エンドポイント。そのため、Streams のフィルター、Webhooks 、およびアプリケーションは、同じ基盤となるデータに基づいて動作することができます。

クローンできる「アプリ 」が2つ

「Wallet Tracking」は、Solana およびEthereum 上のリアルタイムウォレットウォッチリストを用いて、その傾向を表示します。アドレスはフィルターの外で管理されており、Streamを再デプロイすることなく、アプリケーションのUIを通じて更新することができます。

「Wallet Tracking」のサンプルアプリ。ここでは、UserStreamのデモUI上で表示されています。

「Wallet Tracking」サンプルアプリを表示する

HyperCore Order Monitorは、Hyperliquid のコア注文に対しても同様の考え方を適用し、キーバリューストアのリストを用いて、アドレスや注文ステータスに基づく動的なフィルタリングを行っています。

HyperCore Order Monitor サンプルアプリを表示する

完全なアプリケーション内でこのパターンがどのように動作するかを確認したい場合、どちらも有用な出発点となります。

他に、すでにデータとなっているものは何があるでしょうか？

ユーザー が考えを変えたことや、別のシステムが新しい情報を公開したことによって変更されたものは、すべて注目に値する。

ウォレットアドレスはその代表的な例です。しかし、許可リスト、拒否リスト、監視対象のコントラクト、ルーティング基準、ユーザー で指定されたイベントタイプ、およびこれらに類する設定も、同様のパターンに従うことができます。

その違いは単純です：

ロジックが変わった場合は、フィルターを変更してください。

データのみが変更される場合は、キーバリューストアに保存することを検討してください。

そのデータを一度だけ移動させ、フィルタを更新すれば、その後は自動的に変更されるようになります。

キーバリューストアの始め方