키-값 저장소 소개: 재배포 없이 관심 목록 변경하기

Quicknode

2026년 9월 14일 — 읽는 데 6분 소요

공유하기

선호하는 소스로 추가

감시 목록은 변동됩니다. 포트폴리오 추적 도구는 누군가 가입할 때마다 주소를 하나씩 추가합니다. 규정 준수 파이프라인은 다른 누군가의 일정에 따라 업데이트되는 제재 목록을 따릅니다.

해당 목록이 ` Streams ` 필터 내에 포함되어 있다면, 모든 변경 사항이 코드 변경으로 이어집니다. 누군가가 배열을 편집하고 필터를 업데이트하기도 하고, 데이터를 별도의 데이터베이스에 저장해 두고 매 블록마다 쿼리를 실행하는 경우도 있는데, 이 경우 운영 및 동기화해야 할 시스템이 하나 더 늘어나게 됩니다.

키-값 저장소는 상태 변경을 필터 밖으로 옮깁니다.

다음과 같은 두 가지 데이터 유형을 제공합니다:

• 리스트는 지갑 주소, 허용 목록, 필터링 기준 등과 같은 문자열 항목들로 구성된 이름이 지정된 모음을 포함합니다.

• 값은 시간이 지남에 따라 추적하고자 하는 단일 상태 정보를 포함하며, 예를 들어 마지막으로 처리한 블록 등이 이에 해당합니다.

Streams 필터는 읽기와 쓰기 모두 가능합니다. 지원되는 웹훅 템플릿은 이름으로 키-값 저장소 목록을 참조할 수 있습니다. 백엔드, 스크립트 또는 agent 은 REST API를 통해 동일한 데이터에 접근할 수 있습니다.

감시 목록의 경우, 이는 단 한 번의 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 언어로도 작성할 수 있으며, Go에서 이에 상응하는 메서드는 qn.ContainsListItems이며, await 없이 동기식으로 실행됩니다.

중요한 점은 watched_wallets가 필터 외부에 위치한다는 것입니다.

목록에 주소를 추가하거나 삭제하면, 실행 중인 필터는 재배포 없이도 업데이트된 감시 목록을 사용합니다.

이 패턴은 처리 대상 데이터는 달라지더라도 필터링 로직이 동일하게 유지되는 모든 상황에서 적용됩니다.

필터링 기준은 필터 외부에도 정의될 수 있습니다

목록에 반드시 지갑 주소가 포함되어 있을 필요는 없습니다.

또한 어떤 이벤트가 중요한지를 결정하는 기준을 포함할 수도 있습니다. 예를 들어, 주문 모니터링 애플리케이션은 사용자가 추적하고자 하는 주문 상태를 선택할 수 있도록 할 수 있습니다.

이러한 상태를 필터에 직접 하드코딩하는 대신, 목록에 저장할 수 있습니다. 사용자가 선택 사항을 변경하면 목록을 업데이트하면, 실행 중인 필터가 새로운 기준을 적용하기 시작합니다.

이 같은 원리는 허용 목록, 차단 목록, 라우팅 기준, 모니터링 대상 계약 또는 필터링 로직과 별개로 변경되는 기타 값 집합에도 적용됩니다.

무언가를 변경할 때 필터 자체를 변경할 필요가 없다면, 이는 키-값 저장소(Key-Value Store)에 적합한 후보입니다.

값은 리스트가 아닌 상태를 처리합니다.

가치는 같은 개념의 또 다른 측면을 다룹니다.

예를 들어, 중단된 지점을 기억해야 하는 필터의 경우, 처리 작업이 끝날 때 ‘lastProcessedBlock’ 값을 기록해 두었다가 처리가 재개될 때 이를 다시 읽어올 수 있습니다.

필터는 변화하는 상태를 애플리케이션 로직에 내장하는 대신, 키-값 저장소를 통해 이를 읽고 업데이트할 수 있습니다.

핫 패스에 넣기 전에

필터 내에서 키-값 저장소를 사용하기 전에 알아두면 좋은 몇 가지 사항이 있습니다.

일치 여부는 대소문자를 구분합니다.

키-값 저장소의 항목은 대소문자를 구분합니다.

블록체인 주소의 경우, 값이 일관되게 저장되고 확인되도록 해야 합니다. 그렇지 않으면 대소문자 구분이 다른 주소들이 예상대로 일치하지 않을 수 있습니다.

현재 상태는 Streams, Webhooks 및 REST API를 통해 전 세계적으로 확인할 수 있습니다.

키-값 저장소(Key-Value Store)는 필터가 목록의 현재 내용에 접근할 수 있게 해주므로, 현재 상태가 중요한 경우에 매우 적합하며, 이는 많은 관심 목록과 동적 필터링 규칙에 해당합니다.

목록을 업데이트하면 실행 중인 필터가 업데이트된 내용을 읽어옵니다.

REST API에 액세스하려면 API 키가 필요합니다.

Streams 필터는 ‘ Streams ’ 런타임을 통해 키-값 저장소에 접근할 수 있습니다.

REST API를 통해 직접 수행되는 요청(읽기 또는 쓰기 모두)에는 Quicknode API 키가 필요합니다.

발송하기 전에 사용법을 숙지하세요

Streams 필터 내부의 키-값 저장소 읽기 및 비교 작업은 API 크레딧을 소모하지 않습니다. 웹훅과 함께 키-값 저장소 목록을 사용하는 것도 무료입니다.

쓰기 작업은 사정이 다릅니다. 목록 항목을 추가하거나 값을 생성할 때는, 해당 쓰기 작업이 Streams 필터를 통해 이루어지든 REST API를 통해 이루어지든 상관없이 API 크레딧이 소모됩니다.

다음과 같은 사용 시 API 크레딧이 소모됩니다:

• 목록 항목을 하나 추가하거나 가치를 창출할 때마다 API 크레딧 20점

• 저장된 항목당 매월 10 API 크레딧

• 키-값 저장소 REST API 요청 1건당 5 API 크레딧

현재 크기 제한은 목록 항목당 128자, 값당 800,000자입니다.

프로덕션 환경의 사용 규모를 결정하기 전에 키-값 스토어 문서를 확인하여 최신 요금 및 사용 한도를 확인하십시오.

현재 키-값 저장소의 요금 및 사용 한도 확인하기

목록을 확보하고 최신 상태로 유지하기

기존 배열을 키-값 저장소로 옮기려면 필터 하나를 변경해야 합니다.

먼저, 목록을 생성하고 초기값을 설정합니다:

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

단 한 번의 요청으로 목록을 생성하고 초기 데이터를 채울 수 있습니다.

그런 다음 필터를 해당 목록에서 데이터를 읽어오도록 변경하고, 목록을 한 번 업데이트하세요.

그 후, 관심 목록의 변경 사항은 필터가 아닌 키-값 저장소를 통해 이루어집니다.

지속적인 변경이나 일괄 변경의 경우, ‘목록 업데이트 ( Update List )’ endpoint 를 사용하면 단일 PATCH 요청으로 여러 항목을 추가하거나 제거할 수 있습니다. 이를 통해 UI, 백엔드, 스크립트 또는 CI 작업에서 필터를 건드리지 않고도 목록을 최신 상태로 유지하기가 간편해집니다.

업데이트 목록 API 문서를 읽어보세요

키-값 저장소(Key-Value Store) 데이터는 개별 프로젝트나 애플리케이션( endpoint)이 아닌 Google Cloud 프로젝트( Quicknode ) 계정을 단위로 관리되므로, Google Cloud 플랫폼( Streams ) 필터, Google Cloud 플랫폼( Webhooks) 및 애플리케이션이 동일한 기본 데이터를 기반으로 작동할 수 있습니다.

복제할 수 있는 두 가지 앱

‘지갑 추적’ 기능은 Solana 및 Ethereum 에서 실시간 지갑 감시 목록을 통해 패턴을 보여줍니다. 주소는 필터 외부에서 관리되며, 스트림을 다시 배포하지 않고도 애플리케이션 UI를 통해 업데이트할 수 있습니다.

UserStream 데모 UI에 표시된 Wallet Tracking 샘플 앱.

‘지갑 추적’ 샘플 앱 보기

HyperCore Order Monitor는 키-값 저장소(Key-Value Store) 목록을 활용하여 주소 및 주문 상태에 대한 동적 필터링을 수행함으로써, 이 같은 개념을 Hyperliquid 의 코어 주문에도 적용합니다.

HyperCore 주문 모니터링 샘플 앱 보기

완성된 애플리케이션에서 해당 패턴이 어떻게 작동하는지 확인하고 싶다면, 이 두 가지 모두 유용한 출발점이 될 것입니다.

그 밖에도 이미 데이터로 간주되는 것은 무엇이 있을까요?

사용자가 마음을 바꿨거나 다른 시스템에서 새로운 내용을 게시한 탓에 변경된 사항은 무엇이든 살펴볼 가치가 있습니다.

지갑 주소가 가장 대표적인 예입니다. 하지만 허용 목록, 차단 목록, 모니터링 대상 계약, 라우팅 기준, 사용자가 선택한 이벤트 유형 및 이와 유사한 구성 요소들도 동일한 패턴을 따를 수 있습니다.

그 차이점은 간단합니다:

논리가 변경되면 필터를 변경하십시오.

데이터만 변경된다면, 키-값 저장소에 데이터를 보관하는 것을 고려해 보세요.

해당 데이터를 한 번만 옮기고, 필터를 업데이트한 다음, 그 후에는 데이터가 독립적으로 변경되도록 하세요.

키-값 저장소 시작하기