Distribuzione di un subgraph al Hosted Service

Reading time: 9 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.

Dopo aver creato un account, accedere alla propria dashboard. Copiare il token di accesso visualizzato nella dashboard ed eseguire graph auth --product hosted-service <ACCESS_TOKEN>. In questo modo il token di accesso verrà memorizzato sul computer. È necessario farlo solo una volta, o se si rigenera il token di accesso.

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 - Selezionare un'immagine da utilizzare come anteprima e miniatura per il subgraph.

Subgraph Name - Insieme al nome dell'account con cui viene creato il subgraph, questo definirà anche il nome in stile name-account/name-subgraph usato per le distribuzioni e gli endpoint GraphQL. Questo campo non può essere modificato in seguito.

Account - Il account sotto il quale è stato creato il subgraph. Può essere l'account di un individuo o di un'organizzazione. I subgraph non possono essere spostati da un account all'altro in seguito.

Subtitle - Il testo che apparirà nelle schede dei subgraph.

Description - Descrizione del subgraph, visibile nella pagina dei dettagli del subgraph.

GitHub URL - Link al repository del subgraph su 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.

Si distribuisce il subgraph eseguendo 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.

Lo stato del subgraph passa a Synced una volta che il Graph Node ha estratto tutti i dati dai blocchi storici. Il Graph Node continuerà a ispezionare i blocchi del subgraph mentre questi blocchi vengono estratti.

Quando si apportano modifiche alla definizione del subgraph, ad esempio per risolvere un problema nelle mappature delle entità, eseguire nuovamente il comando yarn deploy di cui sopra per distribuire la versione aggiornata del subgraph. Ogni aggiornamento di un subgraph richiede che il Graph Node reindicizzi l'intero subgraph, sempre a partire dal blocco genesis.

Se il subgraph distribuito in precedenza è ancora in stato Syncing, verrà immediatamente sostituito con la nuova versione distribuita. Se il subgraph distribuito in precedenza è già completamente sincronizzato, Graph Node segnerà la nuova versione distribuita come Pending Version, sincronizzarla in background e sostituire la versione attualmente distribuita con quella nuova solo al termine della sincronizzazione della nuova versione. In questo modo si ha a disposizione un subgraph su cui lavorare durante la sincronizzazione della nuova versione.

In alcuni casi, si desidera distribuire lo stesso subgraph su più reti senza duplicare tutto il suo codice. Il problema principale è che gli indirizzi dei contratti su queste reti sono diversi.

Entrambi graph build (da v0.29.0) e graph deploy (da v0.32.0) accettano due nuove opzioni:

Opzioni:

      ...
      --network <name>          Configurazione di rete da utilizzare dal file di configurazione delle reti
      --network-file <path>     Percorso del file di configurazione della rete (predefinito: "./networks.json")

È possibile usare l'opzione --network per specificare una configurazione di rete da un file standard json (predefinito a networks.json) per aggiornare facilmente il subgraph durante lo sviluppo.

Nota: Il comando init ora genera automaticamente un networks.json basato sulle informazioni fornite. Sarà quindi possibile aggiornare le reti esistenti o aggiungerne altre.

Se non si dispone di un file networks.json, è necessario crearne uno manualmente con la seguente struttura:

{
    "network1": { // il nome della rete
        "dataSource1": { // il nome del dataSource
            "address": "0xabc...", // l'indirizzo del contratto (opzionale)
            "startBlock": 123456 // il startBlock (opzionale)
        },
        "dataSource2": {
            "address": "0x123...",
            "startBlock": 123444
        }
    },
    "network2": {
        "dataSource1": {
            "address": "0x987...",
            "startBlock": 123
        },
        "dataSource2": {
            "address": "0xxyz..",
            "startBlock": 456
        }
    },
    ...
}

Nota: Non è necessario specificare alcuno dei template (se ne esistono) nel file di configurazione, ma solo i dataSource. Se ci sono templates dichiarati nel file subgraph.yaml, la loro rete sarà automaticamente aggiornata a quella specificata con l'opzione --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

Questo è l'aspetto del file di configurazione delle reti:

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

Ora possiamo eseguire uno dei seguenti comandi:

# 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

Ora si è pronti per yarn deploy.

Nota: Come già menzionato, da graph-cli 0.32.0 è possibile eseguire direttamente yarn deploy con l'opzione --network:

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

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

Una soluzione per le vecchie versioni di graph-cli che permettono di parametrizzare aspetti come gli indirizzi dei contratti è quella di generare parti di esso utilizzando un sistema di template come Mustache oppure 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..."
}

e

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

Inoltre, si dovrebbero sostituire il nome della rete e gli indirizzi nel manifest con i segnaposto variabili {{network}} e {{address}} e rinominare il manifest, ad esempio, in subgraph.template.yaml^:

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

Per generare un manifest per entrambe le reti, si possono aggiungere due comandi supplementari a package.json insieme a una dipendenza da 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

Un esempio funzionante di questo può essere trovato qui.

Nota: Questo approccio può essere applicato anche a situazioni più complesse, in cui è necessario sostituire più indirizzi e nomi di rete del contratto o in cui si generano mappature o ABI anche da modelli.

Se un subgraph si sincronizza con successo, è un buon segno che continuerà a funzionare bene per sempre. Tuttavia, nuovi trigger sulla rete potrebbero far sì che il subgraph si trovi in una condizione di errore non testata o che inizi a rimanere indietro a causa di problemi di prestazioni o di problemi con gli operatori dei nodi.

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
      }
    }
  }
}

In questo modo si ottiene il chainHeadBlock che può essere confrontato con il latestBlock del subgraph per verificare se è in ritardo. synced informa se il subgraph ha mai raggiunto la chain. health può attualmente assumere i valori di healthy se non si sono verificati errori, o failed se si è verificato un errore che ha bloccato l'avanzamento del subgraph. In questo caso, è possibile controllare il campo fatalError per i dettagli dell'errore.

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.

Ogni subgraph colpito da questa politica ha un'opzione per recuperare la versione in questione.