Bygger subgrafer på NEAR

Reading time: 7 min

Den här guiden är en introduktion till att bygga subgrafer som indexerar smarta kontrakt på NEAR blockchain.

NEAR is a smart contract platform for building decentralized applications. Visit the official documentation for more information.

The Graph ger utvecklare verktyg för att bearbeta blockchain-händelser och göra den resulterande informationen lätt tillgänglig via ett GraphQL API, individuellt känt som en subgraf. Graph Node kan nu bearbeta NEAR-händelser, vilket innebär att NEAR-utvecklare nu kan bygga subgrafer för att indexera sina smarta kontrakt.

Subgrafer är händelsebaserade, vilket innebär att de lyssnar efter och sedan bearbetar händelser i kedjan. Det finns för närvarande två typer av hanterare som stöds för NEAR subgrafer:

• Blockhanterare: dessa körs på varje nytt block
• Kvittohanterare: körs varje gång ett meddelande körs på ett angivet konto

From the NEAR documentation:

@graphprotocol/graph-cli är ett kommandoradsverktyg för att bygga och distribuera subgrafer.

@graphprotocol/graph-ts är ett bibliotek med subgrafspecifika typer.

NEAR subgrafutveckling kräver graph-cli ovan version 0.23.0 och graph-ts ovan version 0.23.0.

Det finns tre aspekter av subgraf definition:

subgraph.yaml: undergraf manifestet, som definierar datakällorna av intresse och hur de ska behandlas. NEAR är en ny typ av datakälla.

schema.graphql: en schema fil som definierar vilken data som lagras för din subgraf, och hur man frågar den via GraphQL. Kraven för NEAR undergrafer täcks av den befintliga dokumentationen.

AssemblyScript Mappings:AssemblyScript kod som översätter från händelsedata till de enheter som definieras i ditt schema. NEAR stöd introducerar NEAR specifika datatyper och ny JSON parsnings funktion.

Under subgrafutveckling finns det två nyckelkommandon:

$ graph codegen # genererar typer från schema filen som identifieras i manifestet
$ graph build # genererar Web Assembly från AssemblyScript filerna och förbereder alla subgraffiler i en /build-mapp

Subgrafmanifestet (subgraph.yaml) identifierar datakällorna för subgrafen, utlösare av intresse och funktionerna som ska köras som svar på dessa utlösare. Se nedan för ett exempel på subgraf manifest för en NEAR subgraf:

specVersion: 0.0.2
schema:
  file: ./src/schema.graphql # link to the schema file
dataSources:
  - kind: near
    network: near-mainnet
    source:
      account: app.good-morning.near # This data source will monitor this account
      startBlock: 10662188 # Required for NEAR
    mapping:
      apiVersion: 0.0.5
      language: wasm/assemblyscript
      blockHandlers:
        - handler: handleNewBlock # the function name in the mapping file
      receiptHandlers:
        - handler: handleReceipt # the function name in the mapping file
      file: ./src/mapping.ts # link to the file with the Assemblyscript mappings

• NEAR undergrafer introducerar en ny typ av datakälla (near)
• The network should correspond to a network on the hosting Graph Node. On Subgraph Studio, NEAR's mainnet is near-mainnet, and NEAR's testnet is near-testnet
• NEAR data sources introduce an optional source.account field, which is a human-readable ID corresponding to a NEAR account. This can be an account or a sub-account.
• NEAR datakällor introducerar ett alternativt valfritt source.accounts-fält, som innehåller valfria suffix och prefix. Minst prefix eller suffix måste anges, de kommer att matcha alla konton som börjar eller slutar med värdelistan. Exemplet nedan skulle matcha: [app|bra].*[morning.near|morning.testnet]. Om endast en lista med prefix eller suffix är nödvändig kan det andra fältet utelämnas.

accounts:
  prefixes:
    - app
    - good
  suffixes:
    - morning.near
    - morning.testnet

NEAR datakällor stöder två typer av hanterare:

• blockHandlers: kör på varje nytt NEAR-block. Inget source.account krävs.
• receiptHandlers: run on every receipt where the data source's source.account is the recipient. Note that only exact matches are processed (subaccounts must be added as independent data sources).

Schemadefinition beskriver strukturen för den resulterande subgraf databasen och relationerna mellan enheter. Detta är agnostiskt för den ursprungliga datakällan. Det finns mer information om definition av subgraf schema här.

Hanterarna för bearbetning av händelser är skrivna i AssemblyScript.

NEAR indexering introducerar NEAR specifika datatyper till AssemblyScript API.

class ExecutionOutcome {
      gasBurnt: u64,
      blockHash: Bytes,
      id: Bytes,
      logs: Array<string>,
      receiptIds: Array<Bytes>,
      tokensBurnt: BigInt,
      executorId: string,
  }

class ActionReceipt {
      predecessorId: string,
      receiverId: string,
      id: CryptoHash,
      signerId: string,
      gasPrice: BigInt,
      outputDataReceivers: Array<DataReceiver>,
      inputDataIds: Array<CryptoHash>,
      actions: Array<ActionValue>,
  }

class BlockHeader {
      height: u64,
      prevHeight: u64,// Always zero when version < V3
      epochId: Bytes,
      nextEpochId: Bytes,
      chunksIncluded: u64,
      hash: Bytes,
      prevHash: Bytes,
      timestampNanosec: u64,
      randomValue: Bytes,
      gasPrice: BigInt,
      totalSupply: BigInt,
      latestProtocolVersion: u32,
  }

class ChunkHeader {
      gasUsed: u64,
      gasLimit: u64,
      shardId: u64,
      chunkHash: Bytes,
      prevBlockHash: Bytes,
      balanceBurnt: BigInt,
  }

class Block {
      author: string,
      header: BlockHeader,
      chunks: Array<ChunkHeader>,
  }

class ReceiptWithOutcome {
      outcome: ExecutionOutcome,
      receipt: ActionReceipt,
      block: Block,
  }

Dessa typer skickas till block & kvittohanterare:

• Blockhanterare kommer att få ett Block
• Kvittohanterare kommer att få ett ReceiptWithOutcome

Annars är resten av AssemblyScript API tillgänglig för NEAR subgraf utvecklare under körning av mappning.

Detta inkluderar en ny JSON parsnings funktion - loggar på NEAR sänds ofta ut som strängade JSON. En ny funktion json.fromString(...) är tillgänglig som en del av JSON API för att tillåta utvecklare för att enkelt bearbeta dessa loggar.

När du har en byggd subgraf är det dags att distribuera den till Graph Node för indexering. NEAR undergrafer kan distribueras till alla Graph Node >=v0.26.x (den här versionen har ännu inte taggats & släppts).

Subgraph Studio and the upgrade Indexer on The Graph Network currently supports indexing NEAR mainnet and testnet in beta, with the following network names:

• near-mainnet
• near-testnet

More information on creating and deploying subgraphs on Subgraph Studio can be found here.

As a quick primer - the first step is to "create" your subgraph - this only needs to be done once. On Subgraph Studio, this can be done from your Dashboard: "Create a subgraph".

När din subgraf har skapats kan du distribuera din subgraf genom att använda graph deploy CLI kommandot:

$ graph create --node <graph-node-url> <subgraph-name> # creates a subgraph on a local Graph Node (on Subgraph Studio, this is done via the UI)
$ graph deploy --node <graph-node-url> --ipfs https://api.thegraph.com/ipfs/ <subgraph-name> # uploads the build files to a specified IPFS endpoint, and then deploys the subgraph to a specified Graph Node based on the manifest IPFS hash

Nodkonfigurationen beror på var subgrafen distribueras.

graph auth --studio
graph deploy --studio <subgraph-name>

graph deploy --node http://localhost:8020/ --ipfs http://localhost:5001 <subgraph-name>

När din subgraf har distribuerats kommer den att indexeras av Graph Node. Du kan kontrollera dess framsteg genom att fråga själva subgrafen:

{
  _meta {
    block {
      number
    }
  }
}

Att köra en Graph Node som indexerar NEAR har följande operativa krav:

• NEAR Indexer Framework med Firehose-instrumentering
• NEAR Brandslangskomponent(er)
• Graf Nod med Firehose ändpunkt konfigurerad

Vi kommer snart att ge mer information om hur du kör ovanstående komponenter.

GraphQL slutpunkten för NEAR undergrafer bestäms av schemadefinitionen, med det befintliga API gränssnittet. Besök GraphQL API-dokumentationen för mer information.

Här är några exempel på subgrafer som referens:

NEAR Block

NEAR kvitton

NEAR stödet är i beta, vilket innebär att det kan bli ändringar i API:t när vi fortsätter att arbeta med att förbättra integrationen. Skicka ett e-postmeddelande till [email protected] så att vi kan hjälpa dig att bygga NEAR subgrafer och hålla dig uppdaterad om den senaste utvecklingen!

Nej, en subgraf kan bara stödja datakällor från en kedja/nätverk.

För närvarande stöds endast blockerings- och kvittoutlösare. Vi undersöker utlösare för funktionsanrop till ett specificerat konto. Vi är också intresserade av att stödja eventutlösare, när NEAR har inbyggt eventsupport.

Om ett account anges kommer det bara att matcha det exakta kontonamnet. Det är möjligt att matcha underkonton genom att ange ett accounts-fält, med suffixes och prefixes angivna för att matcha konton och underkonton, till exempel följande skulle matcha alla mintbase1.near underkonton:

accounts:
  suffixes:
    - mintbase1.near

Detta stöds inte. Vi utvärderar om denna funktionalitet krävs för indexering.

Detta stöds inte för närvarande. Vi utvärderar om denna funktionalitet krävs för indexering.

Väntande funktionalitet stöds ännu inte för NEAR subgrafer. Under tiden kan du distribuera en ny version till en annan "namngiven" subgraf, och när den sedan synkroniseras med kedjehuvudet kan du distribuera om till din primära "namngivna" subgraf, som kommer att använda samma underliggande implementerings-ID, så huvudsubgrafen synkroniseras omedelbart.

Om det är en generell fråga om subgraffutveckling finns det mycket mer information i resten av Utvecklardokumentationen. Annars, var vänlig och anslut dig till The Graph Protocol Discord och ställ din fråga i kanalen #near eller skicka ett e-postmeddelande till [email protected].

• NEAR utvecklar dokumentation