Distribuera en subgraf till värdtjänsten

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.

När du har skapat ett konto navigerar du till din instrumentpanel. Kopiera åtkomsttoken som visas på instrumentpanelen och kör graph auth --product hosted-service <ACCESS_TOKEN>. Detta kommer att lagra åtkomsttoken på din dator. Du behöver bara göra detta en gång, eller om du någonsin återskapar åtkomsttoken.

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:

Bild – Välj en bild som ska användas som förhandsgranskningsbild och miniatyrbild för subgrafen.

Subgraf namn - Tillsammans med kontonamnet som subgrafen skapas under kommer detta också att definiera kontonamn/undergrafnamn-stilen namn som används för distributioner och GraphQL slutpunkter. Det här fältet kan inte ändras senare.

Konto - Kontot som subgrafen skapas under. Detta kan vara kontot för en individ eller organisation. Subgrafer kan inte flyttas mellan konton senare.

Underrubrik – Text som kommer att visas på kort för delgrafer.

Beskrivning – Beskrivning av subgrafen, synlig på sidan med subgraf detaljer.

GitHub URL – Länk till subgraf förrådet på 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.

Du distribuerar subgrafen genom att köra 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.

Undergrafens status växlar till Synced när Graph Node har extraherat alla data från historiska block. Graph Node fortsätter att inspektera block för din undergraf när dessa block minas.

När du gör ändringar i din subgrafdefinition, t. ex. för att åtgärda ett problem i entitetsmappningarna, kör du kommandot yarn deploy ovan igen för att distribuera den uppdaterade versionen av din subgraf. Varje uppdatering av en subgraf kräver att Graph Node indexerar om hela subgrafen, återigen med början i genesis-blocket.

Om din tidigare distribuerade subgraf fortfarande har status Syncing, kommer den omedelbart att ersättas med den nyligen distribuerade versionen. Om den tidigare distribuerade subgrafen redan är helt synkroniserad, kommer Graph Node att markera den nyligen distribuerade versionen som Pending version, synkronisera den i bakgrunden och bara ersätta den för närvarande distribuerade versionen med den nya när den synkroniseras nya versionen är klar. Detta säkerställer att du har en subgraf att arbeta med medan den nya versionen synkroniseras.

I vissa fall vill du distribuera samma undergraf till flera nätverk utan att duplicera all dess kod. Den största utmaningen med detta är att kontraktsadresserna på dessa nätverk är olika.

Både graph build (sedan v0.29.0) och graph deploy (eftersom v0.32.0) accepterar två nya alternativ:

Alternativ:

      ...
      --network <name>          Nätverkskonfiguration som ska användas från filen nätverk config
      --network-file <path>     Sökväg till konfigurationsfil för nätverk (standard: "./networks.json")

Du kan använda alternativet --network för att ange en nätverkskonfiguration från en json standardfil (standard till networks.json) för att enkelt uppdatera din subgraf under utvecklingen.

Obs! Kommandot init kommer nu att automatiskt generera en networks.json baserat på den tillhandahållna informationen. Du kommer då att kunna uppdatera befintliga eller lägga till ytterligare nätverk.

Om du inte har en networks.json-fil måste du skapa en manuellt med följande struktur:

{
    "network1": { // nätverkets namn
        "dataSource1": { // namn på datakällan
            "address": "0xabc...", // Avtalets adress (frivillig uppgift)
            "startBlock": 123456 // startBlock (valfritt)
        },
        "dataSource2": {
            "address": "0x123...",
            "startBlock": 123444
        }
    },
    "network2": {
        "dataSource1": {
            "address": "0x987...",
            "startBlock": 123
        },
        "dataSource2": {
            "address": "0xxyz..",
            "startBlock": 456
        }
    },
    ...
}

Obs! Du behöver inte ange någon av templates (om du har några) i konfigurationsfilen, bara dataSources. Om det finns några templates deklarerade i filen subgraph.yaml, kommer deras nätverk automatiskt att uppdateras till det som anges med alternativet --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

Så här ska nätverkets konfigurationsfil se ut:

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

Nu kan vi köra något av följande kommandon:

# 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

Nu är du redo att yarn deploy.

Obs: Som nämnts tidigare, sedan graph-cli 0.32.0 kan du direkt köra yarn deploy med --nätverk alternativ:

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

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

En lösning för äldre graph-cli versioner som tillåter parameterisering av aspekter som kontraktsadresser är att generera delar av den med hjälp av ett mallsystem som Mustache eller 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..."
}

och

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

Tillsammans med det skulle du ersätta nätverksnamnet och adresserna i manifestet med variabla platshållare {{network}} och {{address}} och byta namn på manifestet till t.ex. subgraph.template.yaml:

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

För att generera ett manifest till något av nätverken kan du lägga till ytterligare två kommandon till package.json tillsammans med ett beroende av 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

Ett fungerande exempel på detta hittar du här.

Obs: Detta tillvägagångssätt kan också tillämpas i mer komplexa situationer, där det är nödvändigt att ersätta mer än kontraktsadresser och nätverksnamn eller där mappningar eller ABI: er genereras från mallar.

Om en subgraf synkroniseras framgångsrikt är det ett gott tecken på att den kommer att fortsätta att fungera bra för alltid. Nya triggers i nätverket kan dock göra att din subgraf stöter på ett otestat feltillstånd eller så kan den börja halka efter på grund av prestandaproblem eller problem med nodoperatörerna.

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

Detta kommer att ge dig chainHeadBlock som du kan jämföra med latestBlock på din subgraf för att kontrollera om den körs efter. synced informerar om subgrafen någonsin har kommit ikapp kedjan. health kan för närvarande ta värdena healthy om inga fel inträffade, eller failed om det fanns ett fel som stoppade subgrafens framsteg. I det här fallet kan du kontrollera fältet fatalError för detaljer om detta fel.

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.

Varje subgraf som påverkas av denna policy har en möjlighet att ta tillbaka versionen i fråga.