The Graph를 사용하여 사용자 정의 서브그래프를 생성하고 배포하는 방법

읽는 데 10분

개요

웹3의 핵심 요소 중 하나는 온체인 데이터에 효율적이고 안정적으로 접근할 수 있어야 한다는 점입니다. 널리 사용되는 스마트 계약 플랫폼인 이더리움( Ethereum)은 데이터를 JSON 형식으로 인코딩하는 원격 프로시저 호출(RPC) 프로토콜인 JSON-RPC를 통해 블록체인 데이터에 대한 접근을 제공합니다.

JSON-RPC는 Ethereum 데이터와 상호작용하는 효과적인 방법이지만, 확장 가능한 dApp을 구축하고자 하는 개발자들에게 항상 가장 효율적이거나 사용자 친화적인 방법은 아닐 수 있습니다. 바로 여기서 The Graph가 등장합니다. The Graph는 직접 쿼리하기 어려운 블록체인 데이터를 색인화하고 쿼리하기 위해 고안된 탈중앙화 프로토콜입니다.

주요 업무

The Graph에 대해 알아보기
The Graph Studio를 사용하여 사용자 지정 서브그래프를 생성하고 게시하기
The Graph Playground를 사용하여 배포된 서브그래프와 상호작용해 보세요

준비물

Ethereum 개발 및 프로그래밍 기초에 대한 기본적인 이해
ETH가 입금된 웹3 지갑(예: MetaMask, Phantom, WalletConnect 호환 지갑) Ethereum mainnet
Graph CLI 및 Node.js가 설치되었습니다.
코드 편집기 (예: VSCode, Atom)

의존성	버전
node.js	18.13.0
graph-cli	0.49.0

The Graph란 무엇인가요?

The Graph는 개발자들이 블록체인 데이터에 더 쉽게 접근할 수 있도록 설계된 탈중앙화 프로토콜입니다. 이 프로토콜은 페이스북이 개발한 오픈소스 쿼리 언어인 GraphQL을 사용하여 Ethereum, IPFS 및 기타 지원되는 네트워크에서 데이터를 조회할 수 있는 안정적이고 효율적인 방법을 제공합니다. 또한 개발자들은 블록체인에서 데이터를 색인화하고 가져오는 방식을 정의하는 맞춤형 “서브그래프(Subgraphs)”를 구축하고 공개할 수 있어, 확장성과 성능이 뛰어난 dApp을 쉽게 개발할 수 있습니다.

그래프 생태계

GraphQL이란 무엇인가요?

GraphQL은 개발자가 필요한 데이터만 요청하면서도 예측 가능한 응답을 받을 수 있도록 해주는 API용 쿼리 언어이자 런타임입니다. 개발자가 응답 데이터의 구조를 직접 지정할 수 있게 함으로써, 더 효율적이고 유연한 애플리케이션을 구축할 수 있도록 지원합니다. 이를 통해 불필요한 데이터 전송과 애플리케이션 속도 저하를 초래할 수 있는 과도한 데이터 가져오기(over-fetching)와 부족한 데이터 가져오기(under-fetching) 현상을 줄일 수 있습니다.

기존의 REST API와 비교했을 때, GraphQL은 데이터와 상호작용하는 데 있어 더 강력하고 유연한 방식을 제공하므로, Ethereum 와 같은 블록체인 플랫폼 위에서 dApp을 구축하는 데 탁월한 선택지입니다.

부분그래프란 무엇인가요?

서브그래프(Subgraph)는 해당 데이터에 대한 쿼리를 효율적으로 처리할 수 있도록 색인이 부여된 블록체인 데이터의 모음입니다. 서브그래프에 대한 쿼리는 GraphQL 프로그래밍 언어를 사용하여 수행됩니다.

퍼블리시된 서브그래프가 어떻게 작동하는지 더 잘 이해할 수 있도록 간단히 살펴보겠습니다. 이 링크로 이동하면 The Graph Playground에서 다음과 같은 쿼리를 확인할 수 있습니다:

{
  blocks(first: 5) {
    id
    숫자
    타임스탬프
    parentHash
  }
}

이 쿼리는 GraphQL 언어로 작성되었으며, Ethereum mainnet 에 있는 ‘ Ethereum ’ 블록 서브그래프를 호출합니다. 이 GraphQL 쿼리는 블록체인의 처음 5개 블록에 대한 데이터를 요청합니다. 각 블록에 대해 고유 식별자(id), 블록 번호 (숫자), 블록이 생성된 시간 (타임스탬프), 그리고 해당 블록의 상위 블록의 해시 parentHash. 재생 버튼을 클릭하면 쿼리를 실행할 수 있습니다. 잠시 시간을 내어 직접 해보세요. 다음과 유사한 결과가 표시될 것입니다:

ETH 블록 조회

이 하위 그래프에 대해 사용할 수 있는 다른 쿼리 예시는 다음과 같습니다:

예시: 응답을 gasUsed 기준 정렬하고, timestamp, gasUsed, totalDifficulty 필드를 반환하세요.

{
  blocks(orderBy: gasUsed) {
    타임스탬프
    가스 사용량
    전체 난이도
  }
}

위의 쿼리를 Playground에 복사하여 붙여넣고 요청을 보내보세요. Playground를 통해 직접 쿼리를 작성하려면 오른쪽의 폴더 아이콘을 클릭하면, 해당 서브그래프의 사전(dictionary)을 확인하고 필드를 선택하거나 선택 해제할 수 있습니다. 이 기능은 서브그래프를 쿼리할 때 사용할 수 있는 모든 필드와 형식을 보여주기 때문에 유용합니다.

그래프 아키텍처 및 제품

사용자 정의 서브그래프를 생성하기 전에, The Graph의 아키텍처를 살펴보며 그 작동 원리를 더 잘 이해해 봅시다. 또한 The Graph가 제공하는 다양한 제품들에 대해서도 알아보겠습니다.

개발자: The Graph의 맥락에서 ‘개발자’란 블록체인 데이터에 대한 접근이 필요한 탈중앙화 애플리케이션(dApp)이나 서비스를 구축하고 배포하는 개인 또는 단체를 의미합니다. 개발자들은 The Graph를 활용하여 다양한 블록체인에서 데이터를 효율적으로 조회하고 가져옴으로써, 블록체인 네트워크를 기반으로 강력한 애플리케이션을 보다 쉽게 구축할 수 있습니다.

인덱서: 인덱서는 The Graph 프로토콜에 참여하여 다양한 블록체인의 데이터를 색인화하고 정리합니다. 인덱서는 인덱스 노드를 운영 및 유지 관리하며, 인덱스 노드는 쿼리 수행에 최적화된 형식으로 데이터를 처리하고 저장하는 역할을 담당합니다.

큐레이터: 큐레이터란 가치 있는 서브그래프를 식별하고, The Graph의 탈중앙화 데이터 마켓플레이스에서 제공되는 데이터를 큐레이션하는 데 기여하는 개인 또는 단체를 말합니다.

위임자: 위임자란 자신의 그래프 토큰(GRT)을 특정 인덱서에게 위임함으로써 The Graph 프로토콜에 참여하는 개인을 말합니다. 위임자는 자체 인프라를 운영하지 않고, 대신 자신이 보유한 GRT를 인덱서에게 할당함으로써 인덱서를 지원합니다.

The Graph가 제공하는 다양한 제품에는 다음이 포함됩니다:

그래프 탐색기

그래프 익스플로러는 게시된 서브그래프와 상호작용하고, 인덱서, 큐레이터, 위임자 등 다른 시장 참여자들을 확인할 수 있는 포털입니다. 잠시 시간을 내어 이 웹페이지를 둘러보시기 바랍니다.

그래프 탐색기

또한 The Graph Explorer의 “Playground” 탭에 있는 GraphQL 플레이그라운드를 활용하여 서브그래프에 대한 쿼리를 실행할 수도 있습니다.

그래프 스튜디오

Subgraph Studio는 서브그래프를 생성 및 관리하고, 메타데이터를 통합하며, 이를 The Graph Explorer에 배포할 수 있는 전용 공간입니다.

다음 섹션에서는 Ethereum mainnet 에서 BAYC를 사용하여 사용자 지정 서브그래프를 만드는 단계를 단계별로 살펴보겠습니다.

The Graph 호스팅 서비스

The Graph 호스팅 서비스는 무료 Graph 노드 인덱서로 작동합니다. 이 서비스는 원래 The Graph의 채택을 확대하기 위해 만들어졌으나 현재는 서비스가 종료되었습니다. 다만, The Graph 분산형 네트워크에서 지원되지 않는 네트워크의 경우 여전히 이 서비스를 이용할 수 있다는 점에 유의하시기 바랍니다.

사용자 정의 하위 그래프 생성 및 배포

참고: 시작하기 전에 MetaMask나 그 외 WalletConnect와 호환되는 지갑 등, 잔액이 충전된 Web3 지갑(가스 비용을 지불할 수 있을 만큼의 ETH가 있는 지갑)을 준비해 두시기 바랍니다.

자, 이제 나만의 사용자 정의 하위 그래프를 만들기 시작하려면 다음 단계를 따라야 합니다:

1단계: Graph CLI 설치

먼저, 터미널에서 다음 명령어 중 하나를 실행하여 Graph CLI를 설치하세요:

npm:

npm install -g @graphprotocol/graph-cli

또는 yarn을 통해:

실 전역 추가 @graphprotocol/graph-cli

2단계: 새로운 하위 그래프 초기화

다음으로, 새로운 서브그래프를 생성해 보겠습니다. The Graph Studio로 이동하여 지갑을 연결한 후, ‘Create a subgraph’를 클릭하세요. 이 튜토리얼에서는 Ethereum mainnet 에 배포된 BAYC NFT 계약을 분석할 예정이므로, 서브그래프 이름을 ‘bayc’로 지정하겠습니다. 나머지 필드는 원하는 대로 입력할 수 있지만, 진행에 필수적인 사항은 아닙니다. 마지막으로 ‘Save’를 클릭하세요.

이제 터미널에서 다음 명령어를 실행하세요:

그래프 초기화 bayc

몇 가지 질문이 표시될 것입니다. 아래의 답변 형식을 참고하여 작성해 주세요:

그래프 문제 지침

이 과정에서 (위와 같이) ABI 가져오기가 실패할 수 있다는 점에 유의하십시오. 이 경우, Etherscan에 접속하여 해당 계약이 어떤 블록에 배포되었는지 확인해야 합니다. 이를 확인하려면 ‘Transfers’ 탭으로 이동한 후 마지막 페이지로 가면 되는데, 거의 항상 그곳에 계약 생성 트랜잭션이 표시됩니다.

Etherscan의 ‘이체’ 탭

Etherscan 계약 생성 페이지

mainnet 에서 동일한 BAYC 스마트 계약을 따라 하고 계신다면, 블록 번호 12287507을 사용하세요. 최종적으로 다음과 같은 형식의 프로젝트 디렉터리가 생성됩니다:

디렉터리 트리

이제 프로젝트 폴더(예: bayc)에 있는 각 중요한 파일을 자세히 살펴보겠습니다.

3단계: 하위 그래프 스키마 정의하기

그 schema.graphql 이는 마치 건물의 설계도와 같습니다. 이 스키마는 The Graph가 색인을 생성하고 쿼리 가능하게 만들 데이터 구조를 정의합니다. 이 스키마는 데이터의 구조를 설명하기 위해 사람이 읽기 쉬운 구문인 GraphQL 스키마 정의 언어(SDL)를 사용합니다. 우리의 경우, 이 스키마는 Subgraph가 블록체인에서 처리할 데이터의 유형과 이들 데이터가 서로 어떻게 연관되는지를 설명합니다.

4단계: 데이터 소스 정의하기

그 subgraph.yaml 파일은 설계도와 시공팀 사이의 조율을 담당하는 프로젝트 매니저와 같습니다. 이 파일은 schema.graphql 그리고 src/mappings 어떤 블록체인 이벤트가 어떤 핸들러 함수를 호출해야 하는지 지정함으로써.

이 파일에서는 블록체인에서 추적할 스마트 계약, 해당 계약 내에서 관심 있는 이벤트, 그리고 해당 이벤트가 발생했을 때 호출되어야 할 핸들러 함수를 정의합니다. 또한 서브그래프의 시작 블록, 즉 데이터 처리를 시작해야 할 블록을 지정합니다. 요컨대, subgraph.yaml Graph 노드가 어떤 데이터를 찾아야 하는지, 그 데이터를 어디서 찾을 수 있는지, 그리고 어떻게 처리해야 하는지에 대한 지침을 제공하는 구성 파일 역할을 합니다.

5단계: 매핑 함수 구현하기

만약 schema.graphql 바로 그 청사진, 그 src/mappings 디렉터리는 설계도를 따라 구조물을 짓는 건설 팀과 같습니다. 이 디렉터리에는 블록체인 데이터를 처리하여 다음에서 정의한 구조화된 데이터로 변환하는 로직이 포함되어 있습니다. schema.graphql.

이 로직은 AssemblyScript(TypeScript의 변형)로 작성되었으며, 블록체인 이벤트에 반응합니다. 추적하고자 하는 각 이벤트마다 이 디렉터리에 해당 핸들러 함수가 있습니다. 예를 들어, 블록체인에서 새로운 “Transaction”이 발생하면, 핸들러 함수는 원시 트랜잭션 데이터를 처리하고, schema.graphql, 그리고 이를 그래프의 데이터베이스에 저장합니다.

이 튜토리얼에서는 해당 파일을 수정하지는 않겠지만, 다음 단계로 넘어가기 전에 잠시 시간을 내어 코드를 살펴보시기 바랍니다.

다음으로, 배포 과정을 살펴보겠습니다.

6단계: 서브그래프 배포

서브그래프를 배포하려면 Ethereum 에 직접 게시해야 하므로 (이 과정에서 트랜잭션이 필요하기 때문에) 약간의 ETH 비용이 발생합니다. Ethereum mainnet 에 배포하는 것이므로, 테스트용 ETH만 있으면 됩니다. 자, 그럼 서브그래프를 호스팅하는 비용은 누가 부담할까요? 좋은 질문입니다. The Graph는 현재 중앙 집중식 호스팅 서비스를 운영 중이며, 이는 초기에는 더 많은 채택을 유도하기 위해 구축되었으나 (향후 단계적으로 중단될 예정입니다). 저희는 이 호스팅 서비스를 사용할 예정이므로, 서브그래프를 표시하기 위해 GRT를 스테이킹할 걱정은 하지 않아도 됩니다.

배포를 진행하려면 Subgraph Studio에 있는 귀하의 서브그래프 초안에 표시된 배포자 키(예: https://thegraph.com/studio/subgraph/bayc; 여기서 bayc는 귀하의 서브그래프 이름으로 대체하세요)가 필요합니다.

키를 확보했다면 터미널에서 다음 명령어를 실행하세요:

액세스 토큰으로 인증하세요:

graph auth --studio <DEPLOY_KEY>

그런 다음, bayc 디렉토리로 이동하여 서브그래프를 컴파일합니다:

cd bayc
그래프 코드 생성 && 그래프 빌드

서브그래프 배포:

그래프 배포 --studio bayc

기본 버전을 선택하거나 직접 지정한 버전을 선택하세요.

다음과 유사한 결과가 표시됩니다:

출력 배포

배포 중에 다음과 같은 문제가 발생하면 - 오류: Graph 노드 https://api.studio.thegraph.com/deploy/에 배포에 실패했습니다: graph-node에 서브그래프를 배포할 수 없습니다: 서브그래프 유효성 검사 오류: [지정된 블록은 Ethereum 네트워크에 존재해야 합니다] - 배포 명령을 다시 실행해 보십시오.

배포된 서브그래프와 상호작용하기

서브그래프를 배포하면 데이터 인덱싱이 시작되며, The Graph의 호스팅 서비스나 그래프 노드 운영자들로 구성된 탈중앙화 네트워크를 통해 쿼리를 실행할 수 있게 됩니다. 서브그래프의 규모에 따라 이 과정은 몇 분에서 며칠까지 걸릴 수 있습니다. 이 예시의 경우 약 1시간이 소요될 수 있습니다. 동기화가 완료되면 서브그래프의 ‘Playground’ 탭으로 이동하여 ‘Play’ 버튼을 클릭해 쿼리를 실행해 보세요. 다음은 몇 가지 쿼리 예시입니다:

다음 값을 반환합니다. 출처:, ~에, 그리고 tokenId 이적과 관련된 항목에서 출처: field는 특정 주소입니다:

MyQuery 쿼리 {
  transfers(where: {from: "0x00774750C8017f3cF313BDA8a0780e98781f4330"}) {
    출처:
    ~에
    id
  }
}

다음 값을 반환합니다. 트랜잭션 해시, 출처:, ~에, 그리고 tokenId 블록 번호가 9020247인 이체 내역 필드에서, 다음 조건으로 정렬합니다. tokenId.

MyQuery 쿼리 {
  transfers(where: {blockNumber: "18536882"}, orderBy: tokenId) {
    트랜잭션 해시
    출처:
    ~에
    tokenId
  }
}

놀이터 관련 문의

위의 스크린샷은 특정 지갑 주소의 송금 내역을 조회하여 다음 결과를 반환합니다. 출처:, ~에 그리고 tokenId 가치.

The Graph에 서브그래프 게시하기

서브그래프를 Subgraph Studio에 배포하고 철저히 테스트한 후, The Graph의 탈중앙화 네트워크에 이를 게시하여 프로덕션 환경에 출시할 수 있습니다. 이 작업을 통해 큐레이터는 큐레이션 활동을 시작하고, 인덱서는 인덱싱 프로세스를 시작할 수 있게 됩니다.

이를 위해 ‘게시(Publish) ’ 버튼을 클릭하고, 네트워크를 선택합니다(이 예시에서는 Ethereum mainnet 입니다). 그런 다음 Web3 지갑에서 트랜잭션을 제출하세요.

그래프의 하위 그래프 게시

게시되면 본인이나 다른 사용자가 해당 서브그래프에 쿼리를 실행할 수 있습니다. 또한 본딩 커브에 GRT를 예치하여 서브그래프에 인덱싱 신호를 보낼 수 있으며, 이를 통해 인덱서에게 해당 서브그래프를 인덱싱해야 함을 알릴 수 있습니다.

이것으로 끝입니다! 이제 The Graph에서 나만의 커스텀 서브그래프를 생성하고, 배포하고, 상호작용하며, 공개하는 방법을 알게 되었습니다.

또한, 이 가이드를 바탕으로 더 깊이 알아보고 싶다면 다음 아이디어들을 고려해 보세요:

소유 이력: 컬렉션 내 각 NFT의 소유 이력을 추적할 수 있습니다. 여기에는 NFT가 양도되거나 판매된 각 건에 대한 정보(관련 당사자, 판매 가격(해당하는 경우), 거래 날짜 등)가 포함될 수 있습니다.
가격 이력: 소유 이력과 마찬가지로, 각 NFT의 가격 이력을 추적할 수 있습니다. 이는 NFT가 빈번하게 거래되는 컬렉션의 경우 특히 흥미로울 수 있는데, 시간이 지남에 따라 NFT 가치의 추이를 파악하는 데 도움이 될 수 있기 때문입니다.
메타데이터 분석: 많은 NFT에는 작가 이름, 제작 날짜 등 작품에 대한 메타데이터가 포함되어 있으며, 때로는 색상 구성이나 테마와 같은 더 복잡한 정보도 포함되기도 합니다. 이러한 메타데이터를 색인화하여 검색이 가능하게 만들면, 사용자가 이러한 속성을 기반으로 NFT를 찾을 수 있게 됩니다.
가장 활발한 거래자: NFT를 매수 및 매도하는 사람을 추적함으로써, 해당 컬렉션에서 가장 활발하게 거래하는 사람들을 파악할 수 있습니다. 이는 해당 NFT 시장의 주요 참여자가 누구인지 알고 싶어 하는 잠재적 매수자나 매도자에게 유용한 정보가 될 수 있습니다.

추가 자료

더 자세히 알고 싶으신가요? 다음 자료 목록을 확인해 보세요:

마무리 말

The Graph는 GraphQL을 활용해 블록체인 데이터에 접근할 수 있는 강력하고 탈중앙화되며 효율적인 방법을 제공합니다. 개발자는 맞춤형 서브그래프를 생성함으로써 Ethereum 및 기타 지원되는 네트워크에서 확장성이 뛰어나고 고성능의 dApp을 손쉽게 구축할 수 있습니다.

여러분이 어떤 프로젝트를 진행 중인지 더 자세히 듣고 싶습니다. Discord에서 메시지를 남겨 주시거나, Twitter에서 저희를 팔로우하여 최신 소식을 놓치지 마세요!

The Graph를 사용하여 사용자 정의 서브그래프를 생성하고 배포하는 방법

개요​

주요 업무​

준비물​

The Graph란 무엇인가요?​

GraphQL이란 무엇인가요?​

부분그래프란 무엇인가요?​

그래프 아키텍처 및 제품​

그래프 탐색기​

그래프 스튜디오​

The Graph 호스팅 서비스​

사용자 정의 하위 그래프 생성 및 배포​

1단계: Graph CLI 설치​

2단계: 새로운 하위 그래프 초기화​

3단계: 하위 그래프 스키마 정의하기​

4단계: 데이터 소스 정의하기​

5단계: 매핑 함수 구현하기​

6단계: 서브그래프 배포​

배포된 서브그래프와 상호작용하기​

The Graph에 서브그래프 게시하기​

추가 자료​

마무리 말​

개요

주요 업무

준비물

The Graph란 무엇인가요?

GraphQL이란 무엇인가요?

부분그래프란 무엇인가요?

그래프 아키텍처 및 제품

그래프 탐색기

그래프 스튜디오

The Graph 호스팅 서비스

사용자 정의 하위 그래프 생성 및 배포

1단계: Graph CLI 설치

2단계: 새로운 하위 그래프 초기화

3단계: 하위 그래프 스키마 정의하기

4단계: 데이터 소스 정의하기

5단계: 매핑 함수 구현하기

6단계: 서브그래프 배포

배포된 서브그래프와 상호작용하기

The Graph에 서브그래프 게시하기

추가 자료

마무리 말