The Graph Client - Written Tutorial

Source - link

Ласкаво прошу до цього туторіалу. Мене звуть Mel, і в цьому відео/інструкції ви дізнаєтеся, як інтегрувати запити The Graph безпосередньо у ваш React-додаток, використовуючи Graph Client The Graph як інструмент для створення graphql-запитів на JavaScript.

Ви зможете створювати запити для різних підграфів і навіть встановлювати так звані “live запити”, схожі на підписки, для отримання потокових даних у реальному часі у вашому додатку. Це чудова відправна точка для використання The Graph і API-підходу для отримання даних з мережі у ваш додаток.

Наш заключний додаток матиме наступну функціональність:

На вкладці ENS ми зможемо робити запити до доменів ENS, використовуючи різні запити до підграфа, розміщеного на ENS. Ми можемо надсилати запиту у багато доменів, окремі домени за їхнім доменним ім'ям, а також фільтруючий запит для отримання доменів на основі їхньої кількості піддоменів.

Якщо ми натиснемо на домен, він перенаправить нас на сторінку etherscan власника вибраного домену, або, краще сказати, на адресу, яка "володіє" доменом ENS.

На вкладці Swaps Live Query ми отримаємо прямий потік даних з Uniswap підграфа на хостинговому сервісі. Ми будемо оновлювати дані кожні 5 секунд, пам'ятаючи, що майнінг та підтвердження блоків Ethereum зазвичай займає приблизно 12 секунд (якщо я не помиляюся). Іноді ми отримуємо ті ж самі дані з потоку даних, але ми отримуємо дані з підграфа кожні 5 секунд.

Я також додав ресурси: репозиторій The Graph на Github, де ви можете дослідити приклади, а також репозиторій цього туторіалу, де ви можете клонувати проект і почати вивчати його.

Отже, як працює The Graph?

Звичайний процес роботи децентралізованого додатку, інтегрованого з The Graph, виглядає наступним чином:

Користувач взаємодіє з децентралізованим додатком, який додає дані в Ethereum через транзакцію на смарт-контракті
Смарт-контракт видає один або декілька events під час обробки транзакції .
Graph Node, яку можна уявити як сервер, постійно сканує Ethereum на наявність нових блоків і даних для вашого підграфа, які вони можуть містити.
Graph Node знаходить у цих блоках події Ethereum для вашого підграфа і, фактично, створює або оновлює об’єкти даних в своєму сховищі відповідно до подій Ethereum. Це трохи більш технічно, але це ж загальний огляд на високому рівні.
Децентралізований додаток запитує у Graph Node дані, проіндексовані в блокчейні, використовуючи кінцеву точку ноди GraphQL .
Децентралізований додаток відображає ці дані в багатому на дані інтерфейсі для кінцевих користувачів, який вони використовують для створення нових транзакцій в Ethereum.
Цикл повторюється.

Крок 1: Налаштування проекту

Ми клонуємо репозиторій проекту з Github. Запустіть одну з цих команд з вашого термінала у вибраній теці:

# https
git clone https://github.com/angelmc32/the-graph-client-react-tutorial.git

# ssh
git clone git@github.com:angelmc32/the-graph-client-react-tutorial.git

Наш проект має бути завантажений в папку з назвою /the-graph-client-react-tutorial або з іншою назвою, яку ви оберете.

Якщо ви хочете слідувати цьому туторіалу і працювати за інструкцією, ви можете скористатися розділом проекту tutorial/start . В іншому випадку, ви можете дослідити повністю функціонуючий додаток в основному розділі.

Для кодування за інструкцією використовуйте команду git switch для переходу в розділ tutorial/start:

git switch tutorial/start

Опинившись у цьому розділі, встановіть залежності проекту за допомогою npm install. Після успішної установки, ми запустимо сервер розробки:

# For this tutorial, we will use npm

# Install project dependencies, defined inside package.json file
npm install

# ... wait for dependencies to be installed 🤓

# Start development server
npm run dev

Якщо ви завантажуєте додаток за допомогою веб-браузера, за вказаною адресою локального сервера, (https://localhost:5173) повинна з’явитись наступна сторінка:

Крок 2: Налаштування graph client

Для початку встановіть The Graph Client CLI у вашому проекті:

# npm
npm install --save-dev @graphprotocol/client-cli

# yarn
yarn add -D @graphprotocol/client-cli

Створіть конфігураційний файл (з назвою .graphclientrc.yml) у кореневій теці і вкажіть кінцеві точки GraphQL, які надані The Graph.

У цьому туторіалі ми будемо робити запити до підграфів ENS і UniswapV2 з хостингового сервісу The Graph:

# .graphclientrc.yml
sources:
  - name: ens
    handler:
      graphql:
        endpoint: https://api.thegraph.com/subgraphs/name/ensdomains/ens
  - name: uniswapv2
    handler:
      graphql:
        endpoint: https://api.thegraph.com/subgraphs/name/uniswap/uniswap-v2

plugins:
  - pollingLive:
      defaultInterval: 5000

documents:
  - src/graphql/*.graphql

Ми визначимо кінцеві точки API підграфу всередині джерел і будемо налаштовувати плагін pollingLive для запитів у режимі реального часу зі стандартним інтервалом у п'ять тисяч (5,000) мілісекунд (еквівалентно п'яти секундам). Зрештою, ми вказуємо, звідки наші файли (документи) запитів graphql будуть зчитуватися graph-client, щоб згенерувати наші запити для JavaScript.

Переконайтеся, що у назві файлу ".graphclientrc.yml" першим стоїть символ ".". В іншому випадку буде видано таку помилку:

Error: No graphclient config file found in "<your/project/folder>"!

Додайте наступний код до об'єкта scripts у вашому файлі package.json:

"scripts": {
    "dev": "vite",
    "build": "vite build",
    "preview": "vite preview",
    "build-client": "graphclient build --fileType js",
    "graphiql": "graphclient serve-dev"
  }

Це дозволить нам запустити команду graphclient, запустивши npm run build-client у терміналі. Щоразу, коли ми захочемо створити або оновити наші файли запитів, наприклад, додати нові запити або змінити існуючі, нам потрібно буде запустити цю команду, щоб згенерувати найновіші файли для нашого коду JavaScript, який ми будемо використовувати всередині React-додатку. Це також дозволить нам запустити GUI для фронтенду схожого на GraphQL studio, де ви зможете досліджувати підграфи за допомогою наданих запитів.

Тепер наш package.json повинен виглядати так:

{
  "name": "graph-client-tutorial",
  "private": true,
  "version": "0.0.0",
  "type": "module",
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "preview": "vite preview",
    "build-client": "graphclient build --fileType js",
    "graphiql": "graphclient serve-dev"
  },
  "dependencies": {
    "react": "^18.2.0",
    "react-dom": "^18.2.0"
  },
  "devDependencies": {
    "@graphprotocol/client-cli": "^2.2.20",
    "@types/react": "^18.0.28",
    "@types/react-dom": "^18.0.11",
    "@vitejs/plugin-react": "^3.1.0",
    "vite": "^4.2.0"
  }
}

Тепер ми можемо визначити наші перші запити.

Крок 3: Визначення запитів ENS

Створіть новий файл під назвою ens-queries.graphql і помістіть його до теки src/graphql/. Вкажіть запити ENS наступним чином:

# src/graphql/ens-queries.graphql

query GetManyDomains {
  domains(first: 1000) {
    id
    name
    labelName
    labelhash
    owner {
      id
    }
  }
}

query GetDomainByLabelName($labelName: String!, $name: String!) {
  domains(where: { labelName: $labelName, name: $name }) {
    name
    labelName
    subdomainCount
    id
    owner {
      id
    }
  }
}

query GetDomainBySubdomainCount($min: Int!, $max: Int!) {
  domains(where: { subdomainCount_gte: $min, subdomainCount_lte: $max }) {
    name
    labelName
    subdomainCount
    subdomains {
      labelName
    }
    id
    owner {
      id
    }
    registration {
      cost
    }
  }
}

Запустіть доданий нами скрипт, щоб згенерувати готовий до використання код JavaScript:

npm run build-client

В результаті буде створено теку .graphclient/ в кореневій теці проекту. Ця тека містить необхідний код для запиту підграфа, який ми налаштували, безпосередньо з наших фронтенд-компонентів React.

Тепер наш проект налаштований на відправку запитів до підграфів, визначених у файлі .graphclientrc.yml (кінцеві точки ENS та UniswapV2).

Ми можемо почати кодування нашого фронтенду, щоб дозволити нашим користувачам робити запити до підграфів.

Крок 4: Редагування ENSComponent для взаємодії із запитами ENS

Перейдіть до теки components/ і відкрийте файл ENSComponent.jsx. Ми відредагуємо наш ENSComponent для використання трьох (3) запитів, які ми визначили у нашому файлі ens-queries.graphql.

Спочатку імпортуємо запити у файл.

Ми створимо три (3) функції, які будуть запускати запити при виконанні, а саме:

getManyDomains
getDomainsByLabelName
getDomainsBySubdomainCount

Ми призначимо ці функції для окремих кнопок в межах форми. Всі вони матимуть однаковий шаблон:

Запобіжіть стандартній поведінці при виконанні методу onClick елемента кнопки, щоб уникнути перезавантаження сторінки.
Встановіть змінну стану isLoading на значення true, щоб вказати, що ви завантажуєте дані, для кращого користувацького досвіду.
Виконайте запит і збережіть результати в іншій змінній стану, яка буде містити всі результати запитів. Ми будемо використовувати цю змінну стану для відображення запитуваних даних користувачеві.
Встановіть змінну стану завантаження на значення false, щоб вказати, що ви більше не завантажуєте дані.

// src/components/ENSComponent.jsx

import { useState } from "react";
import logo from "../logo.svg";

// Import the query documents, as well as the execute method
import {
  GetManyDomainsDocument,
  GetDomainByLabelNameDocument,
  GetDomainBySubdomainCountDocument,
  execute,
} from "../../.graphclient/index";

const ENSForm = () => {
  const [domains, setDomains] = useState([]);
  const [labelName, setLabelName] = useState("");
  const [minSubdomains, setMinSubdomains] = useState(1);
  const [maxSubdomains, setMaxSubdomains] = useState(5);
  const [isLoading, setIsLoading] = useState(false);

  const getManyDomains = (event) => {

        // 1. Prevent page refresh on click (default behavior)
    event.preventDefault();

        // 2. Set loading variable to true: currently loading query data
    setIsLoading(true);

        // 3. Execute the query and save the data inside state variable
    execute(GetManyDomainsDocument, {}).then((result) => {
      setDomains(result.data.domains);

        // 4. Set loading variable to false: we have finished loading query data
      setIsLoading(false);
    });
  };

  const getDomainsByLabelName = (event) => {

        // 1. Prevent page refresh on click (default behavior)
    event.preventDefault();

        // 2. Set loading variable to true: currently loading query data
    setIsLoading(true);

        // 3. Execute the query and save the data inside state variable
    execute(GetDomainByLabelNameDocument, {
      labelName: labelName,
      name: `${labelName}.eth`,
    }).then((result) => {
      setDomains(result.data.domains);

        // 4. Set loading variable to false: we have finished loading query data
      setIsLoading(false);
    });
  };

  const getDomainsBySubdomainCount = (event) => {

        // 1. Prevent page refresh on click (default behavior)
    event.preventDefault();

        // 2. Set loading variable to true: currently loading query data
    setIsLoading(true);

        // 3. Execute the query and save the data inside state variable
    execute(GetDomainBySubdomainCountDocument, {
      min: parseInt(minSubdomains),
      max: parseInt(maxSubdomains),
    }).then((result) => {
      setDomains(result.data.domains);

        // 4. Set loading variable to false: we have finished loading query data
      setIsLoading(false);
    });
  };

Тепер у JSX все налаштовано. Якщо ваш сервер розробки не працює, ви можете запустити його за допомогою npm run dev, і тепер ви зможете використовувати ENS запити. Спробуйте їх! Ми зробимо запит на "Many ENS domains". Список запитуваних ENS-доменів буде показано праворуч від компонента форми.

Якщо ви натиснете на один з доменів ENS, ви потрапите на сторінку etherscan, якій належить домен ENS.

Спробуйте інші запити, щоб протестувати наш код.

Крок 5: Визначення запитів UniswapV2

Схожий процес для наших Uniswap-запитів: створіть новий файл з назвою uniswap-queries.graphql і помістіть його в теку src/graphql/. Визначимо запити Uniswap наступним чином:

# src/graphql/uniswap-queries.graphql

query GetManySwaps @live {
  swaps(orderBy: timestamp, first: 15, orderDirection: desc) {
    id
    amountUSD
    pair {
      token0 {
        name
        symbol
      }
      token0Price
      token1 {
        name
        symbol
      }
      token1Price
    }
    timestamp
  }
}

Оскільки ми хочемо отримати потік даних від API підграфа UniswapV2, ми повинні встановити директиву @live для нашого запиту. The Graph Client згенерує необхідний код, який дозволить нам отримати функціональність, подібну до підписки, отримувати дані в режимі реального часу без необхідності виконувати запит вручну.

У нашому конфігураційному файлі .graphclientrc.yml ми визначили pollingInterval в п'ять (5) секунд, що швидше, ніж видобуток блоків Ethereum, який становить дванадцять (12) секунд. Таким чином, дані можуть не оновлюватися після кожного оновлення запиту, але ми будемо бачити оновлення в режимі реального часу після видобутку кожного блоку.

Запустіть скрипт build-client. Graph-client згенерує нові запити разом з попередніми, і знову згенерує все, що знаходиться в теці .graphclient/.

npm run build-client

Ми готові інтегрувати live запит Uniswap в наш фронтенд-компонент.

Крок 6: Відредагуйте компонент App для взаємодії з live запитом UniswapV2

Перейдіть до теки src/ і відкрийте файл App.jsx. Ми відредагуємо наш компонент App, щоб використовувати live запит, який ми визначили в нашому файлі uniswap-queries.graphql.

Спершу імпортуємо запити до файлу (код нижче, для довідки). Ми також імпортуємо метод subscribe.

Ми створимо одну (1) функцію, яка створить підписку на запит і буде виконувати запит кожні 5 секунд:

- subscribeLiveQuery

Ми призначимо ці функції для завантаження при зміні стану змінної showTab. Після того, як наш користувач натисне на кнопку "show Swaps Live Query", спрацює метод subscribe.

Ми повторюємо шаблон, з важливою зміною:

Встановіть змінну стану isLoading на значення true, щоб вказати, що ми завантажуємо дані, для кращого користувацького досвіду.
Виконуємо метод subscription, передаючи в якості аргументу наш документ запиту.
Коли ми отримаємо результат subscription, ми можемо виконати метод .next(), який надає нам відповідь зі значеннями даних, які ми визначили в нашому файлі uniswap-queries.graphql. Ми зберігаємо дані у змінній стану swaps.
Проводимо перевірку, щоб перевірити, чи наш live запит все ще активний, за допомогою властивості isLive. Якщо значення true, ми застосовуємо рекурсію, щоб знову викликати функцію і отримати оновлені дані.
Якщо запит неактивний, isLive === false, ми встановлюємо змінну стану завантаження на значення false, щоб вказати, що ми більше не завантажуємо дані.

Тепер ми хочемо виконати нашу функцію subscribeLiveQuery, коли користувач натискає кнопку "Swap Live Query". Ми змінюємо функцію showComponent. Наш файл App.jsx повинен виглядати так:

// src/App.jsx

import { useState } from "react";
import "./App.css";
import Navbar from "./components/Navbar";
import ENSComponent from "./components/ENSComponent";
import SwapsComponent from "./components/SwapsComponent";

// Import the query document and the subscribe method
import { GetManySwapsDocument, subscribe } from "../.graphclient/index";

function App() {

    // Add this state variable to save the swap data
  const [swaps, setSwaps] = useState([]);

  const [isLoading, setIsLoading] = useState(false);
  const [showTab, setShowTab] = useState("ens-query");

  const subscribeLiveQuery = async () => {
    setIsLoading(true);
    subscribe(GetManySwapsDocument, {})
      .then((result) => {
        result
          .next()
          .then((res) => {
            if (res) {
              if (res.value) {
                // Leaving this to show live query on demo
                console.log(
                  ` Last registered swap value: $ ${parseFloat(
                    res.value.data.swaps[0].amountUSD
                  ).toFixed(2)}`
                );
                setSwaps(res.value.data.swaps);
              }
            }
            if (res.value.isLive) {
              setTimeout(() => {
                subscribeLiveQuery();
              }, 5000);
            } else {
              result.return();
            }
          })
          .catch((e) => console.log(e));
        if (!result) {
          return null;
        }
        setIsLoading(false);
      })
      .catch((error) => {
        console.log(error);
        setIsLoading(false);
      });
  };

    const showComponent = async (component = "ens-query") => {
    if (component === "dex-query") {
      await subscribeLiveQuery();
    }
    setShowTab(component);
  };

  //
    // Rest of component
    //

}

Переконайтеся, що додали гак useState для змінної стану swaps. Також переконайтеся, що передаєте змінну стану swaps нашому компоненту SwapsComponent як props:

function App() {
    const [swaps, setSwaps] = useState([]);
    
    //
    // Rest of code
    //

    return(
        // Rest of JSX
            {showTab === "dex-query" && (
        <SwapsComponent isLoading={isLoading} swaps={swaps} />
      )}
        // Rest of JSX
    )
}

Тепер ви повинні побачити таблицю з даними про swaps, яка автоматично оновлюється завдяки реалізації live запиту, що надається The Graph Client!

Висновок

У цьому туторіалі ми дізналися, як інтегрувати The Graph Client у фронтенд React. Цей туторіал має допомогти вам як відправна точка для інтеграції підграфів The Graph у ваш проект і відображення on-chain даних вашим користувачам, навіть у реальному часі, за допомогою підходу API.

Я сподіваюся, що цей туторіал допоможе вам стати більш досвідченим у розробці web3 додатків. Якщо вам сподобався туторіал, ви можете висловити свою вдячність, поділившись ним з друзями та колегами.

Підписуйтесь на Lens та Twitter , це також буде чудово! А якщо ви хочете підтримати мене, ви завжди можете замінтити цей туторіал на Lens. Приємного кодування!

smth0x

smth0x

No comments yet

smth0x

smth0x

No comments yet

The Graph Client - Written Tutorial

The Graph Client - Written Tutorial

No comments yet

No comments yet