Развертывание подграфа Arweave в Hosted Service

Reading time: 8 min

This page explains how to deploy a subgraph to the hosted service. To deploy a subgraph you need to first install the Graph CLI. If you have not created a subgraph already, see creating a subgraph.

Before using the hosted service, create an account in our hosted service. You will need a Github account for that; if you don't have one, you need to create that first. Then, navigate to the hosted service, click on the 'Sign up with Github' button, and complete Github's authorization flow.

После создания учетной записи перейдите к своему дашборду. Скопируйте идентификатор доступа, отображаемый на панели, и запустите graph auth --product hosted-service <ACCESS_TOKEN>. Это сохранит идентификатор на вашем компьютере. Вам нужно сделать это только один раз, или если вы когда-либо повторно создадите идентификатор доступа.

Before deploying the subgraph, you need to create it in Graph Explorer. Go to the dashboard and click on the Add Subgraph button and fill in the information below as appropriate:

Image - Выберите изображение, которое будет использоваться в качестве изображения предварительного просмотра и миниатюры для подграфа.

Subgraph Name - Вместе с именем учетной записи, под которым создается подграф, это также определит account-name/subgraph-name-имя стиля, используемого для развертываний и эндпоинтов GraphQL. Это поле не может быть изменено позже.

** Account ** - учетная запись, под которой создается подграф. Это может быть учетная запись физического лица или организации. Подграфы позже нельзя будет перемещать между учетными записями.

Subtitle - текст, который будет отображаться в виде карт подграфа.

** Description ** - Описание подграфа, видимое на странице сведений о подграфе.

URL GitHub - ссылка на subgraph репозиторий на GitHub.

Hide - Switching this on hides the subgraph in Graph Explorer.

After saving the new subgraph, you are shown a screen with help on how to install the Graph CLI, how to generate the scaffolding for a new subgraph, and how to deploy your subgraph. The first two steps were covered in the Creating a Subgraph section.

Deploying your subgraph will upload the subgraph files that you've built with yarn build to IPFS and tell Graph Explorer to start indexing your subgraph using these files.

Для развертывания подграфа выполните команду yarn deploy

After deploying the subgraph, Graph Explorer will switch to showing the synchronization status of your subgraph. Depending on the amount of data and the number of events that need to be extracted from historical blocks, starting with the genesis block, syncing can take from a few minutes to several hours.

Статус подграфа переключается на Synced, как только Graph Node извлечет все данные из исторических блоков. The Graph Node будет продолжать проверять блоки для вашего подграфа по мере добывания этих блоков.

При внесении изменений в определение подграфа, например, для устранения проблемы в сопоставлении объектов, выполните команду yarn deploy выше, чтобы снова установить обновленную версию подграфа. Любое обновление подграфа требует, чтобы Graph Node заново проиндексировал весь ваш подграф, снова начиная с genesis блока.

Если ваш ранее развернутый подграф все еще находится в статусе Syncing, он будет немедленно заменен на недавно развернутую версию. Если ранее развернутый подграф уже полностью синхронизирован, нода Graph пометит вновь развернутую версию как Pending Version, синхронизирует ее в фоновом режиме и заменит текущую развернутую версию новой только после завершения синхронизации новой версии. Это гарантирует, что у вас есть подграф для работы во время синхронизации новой версии.

В некоторых случаях вы захотите развернуть один и тот же подграф в нескольких сетях, не дублируя весь его код. Основная проблема, возникающая при этом, заключается в том, что адреса контрактов в этих сетях разные.

Как graph build (начиная с v0.29.0), так и graph deploy (начиная с v0.32.0) допускают две новые опции:

...
      --network <name> Конфигурация сети для использования из файла конфигурации сетей
      --network-file <path> Путь к файлу конфигурации сетей (по умолчанию: "./networks.json")

Вы можете использовать опцию --network, чтобы указать конфигурацию сети из стандартного файла json (по умолчанию используется networks.json), чтобы легко обновлять свой подграф во время разработки.

Примечание: Команда init теперь автоматически сгенерирует networks.json на основе предоставленной информации. Затем вы сможете обновить существующие или добавить дополнительные сети.

Если у вас нет файла networks.json, вам нужно будет вручную создать его со следующей структурой:

{
    "network1": { // the network name
        "dataSource1": { // the dataSource name
            "address": "0xabc...", // the contract address (optional)
            "startBlock": 123456 // the startBlock (optional)
        },
        "dataSource2": {
            "address": "0x123...",
            "startBlock": 123444
        }
    },
    "network2": {
        "dataSource1": {
            "address": "0x987...",
            "startBlock": 123
        },
        "dataSource2": {
            "address": "0xxyz..",
            "startBlock": 456
        }
    },
    ...
}

Примечание: Вам не нужно указывать ни один из templates (если они у вас есть) в файле конфигурации, только dataSources. Если есть какие-либо templates, объявленные в файле subgraph.yaml, их сеть будет автоматически обновлена до указанной с помощью опции --network.

Now, let's assume you want to be able to deploy your subgraph to the mainnet and sepolia networks, and this is your subgraph.yaml:

# ...
dataSources:
  - kind: ethereum/contract
    name: Gravity
    network: mainnet
    source:
      address: '0x123...'
      abi: Gravity
    mapping:
      kind: ethereum/events

Вот как должен выглядеть файл конфигурации ваших сетей:

{
  "mainnet": {
    "Gravity": {
      "address": "0x123..."
    }
  },
  "sepolia": {
    "Gravity": {
      "address": "0xabc..."
    }
  }
}

Теперь мы можем запустить одну из следующих команд:

# Using default networks.json file
yarn build --network sepolia

# Using custom named file
yarn build --network sepolia --network-file path/to/config

The build command will update your subgraph.yaml with the sepolia configuration and then re-compile the subgraph. Your subgraph.yaml file now should look like this:

# ...
dataSources:
  - kind: ethereum/contract
    name: Gravity
    network: sepolia
    source:
      address: '0xabc...'
      abi: Gravity
    mapping:
      kind: ethereum/events

Теперь вы готовы к yarn deploy.

Примечание: Как упоминалось ранее, поскольку graph-cli 0.32.0 вы можете напрямую запустить yarn deploy с опцией --network:

# Using default networks.json file
yarn deploy --network sepolia

# Using custom named file
yarn deploy --network sepolia --network-file path/to/config

Одним из решений для старых версий graph-cli, которое позволяет параметризовать такие аспекты, как адреса контрактов, является генерация его частей с использованием системы шаблонов, такой как Mustache или Handlebars.

To illustrate this approach, let's assume a subgraph should be deployed to mainnet and Sepolia using different contract addresses. You could then define two config files providing the addresses for each network:

{
  "network": "mainnet",
  "address": "0x123..."
}

и

{
  "network": "sepolia",
  "address": "0xabc..."
}

Наряду с этим, необходимо заменить имя сети и адреса в манифесте на variable placeholders {{network}} и {{address}} и переименовать манифест, например, subgraph.template.yaml:

# ...
dataSources:
  - kind: ethereum/contract
    name: Gravity
    network: mainnet
    network: {{network}}
    source:
      address: '0x2E645469f354BB4F5c8a05B3b30A929361cf77eC'
      address: '{{address}}'
      abi: Gravity
    mapping:
      kind: ethereum/events

Чтобы сформировать манифест для любой сети, вы можете добавить две дополнительные команды в package.json вместе с dependency от mustache:

{
  ...
  "scripts": {
    ...
    "prepare:mainnet": "mustache config/mainnet.json subgraph.template.yaml > subgraph.yaml",
    "prepare:sepolia": "mustache config/sepolia.json subgraph.template.yaml > subgraph.yaml"
  },
  "devDependencies": {
    ...
    "mustache": "^3.1.0"
  }
}

To deploy this subgraph for mainnet or Sepolia you would now simply run one of the two following commands:

# Mainnet:
yarn prepare:mainnet && yarn deploy

# Sepolia:
yarn prepare:sepolia && yarn deploy

Рабочий пример этого можно найти здесь.

Примечание: Этот подход также может быть применен к более сложным ситуациям, где необходимо заменить больше, чем адреса контрактов и сетевые имена, или где также генерируются сопоставления или ABI из шаблонов.

Если подграф успешно синхронизируется, это хороший признак того, что он будет работать надёжно. Однако новые триггеры в сети могут привести к тому, что ваш подграф попадет в состояние непроверенной ошибки, или он может начать отставать из-за проблем с производительностью или проблем с операторами нод.

Graph Node exposes a graphql endpoint which you can query to check the status of your subgraph. On the hosted service, it is available at https://api.thegraph.com/index-node/graphql. On a local node, it is available on port 8030/graphql by default. The full schema for this endpoint can be found here. Here is an example query that checks the status of the current version of a subgraph:

{
  indexingStatusForCurrentVersion(subgraphName: "org/subgraph") {
    synced
    health
    fatalError {
      message
      block {
        number
        hash
      }
      handler
    }
    chains {
      chainHeadBlock {
        number
      }
      latestBlock {
        number
      }
    }
  }
}

Это даст вам chainHeadBlock, который вы можете сравнить с latestBlock на вашем подграфе, чтобы проверить, отстает ли он. synced сообщает, попадал ли когда-либо подграф в сеть. health в настоящее время может принимать значения healthy, если ошибок не произошло, или failed, если произошла ошибка, которая остановила работу подграфа. В этом случае вы можете проверить поле FatalError для получения подробной информации об этой ошибке.

The hosted service is a free Graph Node Indexer. Developers can deploy subgraphs indexing a range of networks, which will be indexed, and made available to query via graphQL.

To improve the performance of the service for active subgraphs, the hosted service will archive subgraphs that are inactive.

A subgraph is defined as "inactive" if it was deployed to the hosted service more than 45 days ago, and if it has received 0 queries in the last 45 days.

Developers will be notified by email if one of their subgraphs has been marked as inactive 7 days before it is removed. If they wish to "activate" their subgraph, they can do so by making a query in their subgraph's hosted service graphQL playground. Developers can always redeploy an archived subgraph if it is required again.

A subgraph version in Studio is archived if and only if it meets the following criteria:

• The version is not published to the network (or pending publish)
• The version was created 45 or more days ago
• The subgraph hasn't been queried in 30 days

In addition, when a new version is deployed, if the subgraph has not been published, then the N-2 version of the subgraph is archived.

У каждого подграфа, затронутого этой политикой, есть возможность вернуть соответствующую версию обратно.