NEAR Üzerinde Subgraphlar Oluşturma

Reading time: 7 min

Bu rehber, NEAR blok zincirinde akıllı sözleşmeleri indeksleyen subgraphlar oluşturmaya giriş niteliğindedir.

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

Graph, geliştiricilere blok zinciri olaylarını işlemek ve elde edilen verileri tek tek subgraph olarak bilinen bir GraphQL API aracılığıyla kolayca erişilebilir hale getirmek için araçlar sunar. Graph Düğümü artık NEAR olaylarını işleyebiliyor, bu da NEAR geliştiricilerinin artık akıllı sözleşmelerini indekslemek için subgraphlar oluşturabilecekleri anlamına geliyor.

Subgraphlar olay tabanlıdır, yani zincir üzerindeki olayların etkinliklerini gözler ve ardından işlerler. Şu anda NEAR subgraphları için desteklenen iki tür işleyici vardır:

• Blok işleyicileri: Bunlar her yeni blokta çalışır
• Makbuz işleyicileri: Belirli bir hesapta her mesaj yürütüldüğünde çalışır

From the NEAR documentation:

@graphprotocol/graph-cli, subgraphları oluşturmak ve dağıtmak için kullanılan bir komut satırı aracıdır.

@graphprotocol/graph-ts, bir subgraph özel türler kütüphanesidir.

NEAR subgraph'ı geliştirmek, 0.23.0 sürümünden yüksek graph-cli ve 0.23.0 sürümünden yüksek graph-ts gerektirir.

Subgraph tanımının üç yönü vardır:

subgraph.yaml: Veri kaynaklarını ve bunların nasıl işleneceğini tanımlayan subgraph manifestidir. NEAR, yeni bir veri kaynağı türüdür(kind).

schema.graphql: Subgraph'ınız için hangi verilerin depolandığını ve bunlara GraphQL aracılığıyla nasıl sorgu yapılacağını tanımlayan bir şema dosyası. NEAR subgraph gereksinimleri mevcut belgelendirmede ele alınmıştır.

AssemblyScript Mappings: AssemblyScript code that translates from the event data to the entities defined in your schema. NEAR support introduces NEAR-specific data types and new JSON parsing functionality.

Subgraph geliştirme sırasında iki temel komut bulunmaktadır:

$ graph codegen # manifest'de tanımlanan şema dosyasından tipleri üretir
$ graph build # AssemblyScript dosyalarından Web Assembly oluşturur ve tüm subgraph dosyalarını bir /build klasöründe hazırlar

Subgraph manifesti (subgraph.yaml), subgraph için veri kaynaklarını, ilgili tetikleyicileri ve bu tetikleyicilere yanıt olarak çalıştırılması gereken fonksiyonları tanımlar. Bir NEAR subgraph'ı özelinde örnek bir subgraph manifesti için aşağıya bakınız:

specVersion: 0.0.2
schema:
  file: ./src/schema.graphql # şema dosyasına bağlantı
dataSources:
  - kind: near
    network: near-mainnet
    source:
      account: app.good-morning.near # Bu veri kaynağı bu hesabı izleyecektir
      startBlock: 10662188 # NEAR için gereklidir
    mapping:
      apiVersion: 0.0.5
      language: wasm/assemblyscript
      blockHandlers:
        - handler: handleNewBlock # eşleştirme dosyasındaki fonksiyon adı
      receiptHandlers:
        - handler: handleReceipt # eşleştirme dosyasındaki fonksiyon adı
      file: ./src/mapping.ts # Assemblyscript eşleştirmelerinin bulunduğu dosyaya bağlantı

• NEAR subgraphları yeni bir veri kaynağı türü(kind) olan near'ı sunar
• 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 veri kaynakları, opsiyonel son ekler ve ön ekler içeren alternatif bir opsiyonel source.accounts alanı sunar. En azından ön ek veya son ek belirtilmelidir, bunlar sırasıyla değer listesiyle başlayan veya biten herhangi bir hesapla eşleşecektir. Aşağıdaki örnek eşleşecektir: [app|good].*[morning.near|morning.testnet]. Yalnızca bir ön ek veya son ek listesi gerekliyse, diğer alan atlanabilir.

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

NEAR veri kaynakları iki tür işleyiciyi destekler:

• blockHandlers: Her yeni NEAR bloğunda çalıştırılır. source.account gerekli değildir.
• 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).

Şema tanımı, ortaya çıkan subgraph veritabanının yapısını ve varlıklar arasındaki ilişkileri tanımlar. Bu, orijinal veri kaynağından bağımsızdır. Subgraph şema tanımı hakkında daha fazla ayrıntı burada bulunmaktadır.

Olayları işlemek için işleyiciler AssemblyScript içinde yazılmıştır.

NEAR indexing introduces NEAR-specific data types to the 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,
  }

Bu türler blok & makbuz işleyicilerine aktarılır:

• Blok işleyicileri bir Block alır
• Makbuz işleyicileri bir ReceiptWithOutcome alır

Otherwise, the rest of the AssemblyScript API is available to NEAR subgraph developers during mapping execution.

This includes a new JSON parsing function - logs on NEAR are frequently emitted as stringified JSONs. A new json.fromString(...) function is available as part of the JSON API to allow developers to easily process these logs.

Bir subgraph oluşturduktan sonra, artık indeksleme için Graph Düğümü'ne dağıtma zamanı gelmiştir. NEAR subgraphları sürümü >=v0.26.x (bu sürüm henüz etiketlenmemiş & yayınlanmamıştır) olan herhangi bir Graph Düğümü'ne dağıtılabilir.

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".

Subgraph'ınız oluşturulduktan sonra, graph deploy CLI komutunu kullanarak subgraph'ınızı dağıtabilirsiniz:

$ 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

Düğüm yapılandırması, subgraph'ın nerede dağıtıldığına bağlı olacaktır.

graph auth
graph deploy <subgraph-name>

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

Subgraph'ınız dağıtıldıktan sonra Graph Düğüme tarafından indekslenecektir. Subgraph'ın kendisini sorgulayarak ilerlemesini kontrol edebilirsiniz:

{
  _meta {
    block {
      number
    }
  }
}

NEAR'ı indeksleyen bir Graph Düğümü çalıştırmanın aşağıdaki operasyonel gereksinimleri vardır:

• Firehose enstrümantasyonu ile NEAR İndeksleyici Çerçevesi
• NEAR Firehose Bileşen(ler)i
• Firehose uç noktası yapılandırılmış Graph Düğümü

Yukarıdaki bileşenlerin çalıştırılması hakkında yakında daha fazla bilgi vereceğiz.

NEAR subgraphları için GraphQL uç noktası, mevcut API arayüzü ile şema tanımı tarafından belirlenir. Daha fazla bilgi için lütfen GraphQL API dökümantasyonunu ziyaret edin.

Here are some example subgraphs for reference:

NEAR Blokları

NEAR Makbuzları

NEAR desteği beta aşamasındadır, bu da entegrasyonu geliştirmek için çalışmaya devam ederken API'de değişiklikler olabileceği anlamına gelir. NEAR subgraphları oluştururken size destek olabilmemiz ve en son gelişmelerden sizi haberdar edebilmemiz için lütfen [email protected] adresine e-posta gönderin!

Hayır, bir subgraph yalnızca bir zincirden/ağdan veri kaynaklarını destekleyebilir.

Şu anda yalnızca Blok ve Makbuz tetikleyicileri desteklenmektedir. Belirli bir hesaba yapılan fonksiyon çağrıları için tetikleyicileri araştırma aşamasındayız. NEAR yerel olay desteğine sahip oldu takdirde, olay tetikleyicilerini desteklemekle de ilgileneceğiz.

Bir account belirtilirse, bu yalnızca tam hesap adıyla eşleşecektir. Hesapları ve alt hesapları eşleştirmek için suffixes ve prefixes ile birlikte bir accounts alanı belirterek alt hesapları eşleştirmek mümkündür, örneğin aşağıdaki tüm mintbase1.near alt hesaplarıyla eşleşir:

accounts:
  suffixes:
    - mintbase1.near

Bu desteklenmemektedir. Bu fonksiyonelliğin indeksleme için gerekli olup olmadığını değerlendiriyoruz.

Bu şu anda desteklenmemektedir. Bu fonksiyonelliğin indeksleme için gerekli olup olmadığını değerlendiriyoruz.

Bekleme fonksiyonelliği henüz NEAR subgraphları için desteklenmemektedir. Bu arada, farklı "adlandırılmış" bir subgraph'a yeni bir sürüm dağıtabilir ve daha sonra bu zincir başı ile senkronize edildiğinde, aynı temel dağıtım ID'sini kullanacak olan birincil "adlandırılmış" subgraph'ınıza yeniden dağıtabilirsiniz. Böylece ana subgraph anında senkronize olur.

Subgraph geliştirme hakkında genel bir soruysa, Geliştirici dökümantasyonu'nun geri kalanında çok daha fazla bilgi bulunmaktadır. Aksi durumda lütfen The Graph Protocol Discord sunucusuna katılın ve #near kanalında sorunuzu sorun veya [email protected] adresine e-posta gönderin.

• NEAR geliştirici dökümantasyonu