Docs
Arama⌘ K
  • Ana sayfa
  • Graph Hakkında
  • Desteklenen Ağlar
  • Protocol Contracts
  • Subgraph'ler
    • Substream'ler
      • Token API
        • AI Suite
          • Endeksleme
            • Kaynaklar
              Subgraph'ler > Geliştirme > Oluşturma

              14 dakika

              Subgraph Manifest

              Genel Bakış

              The Subgraph manifest, subgraph.yaml, defines the smart contracts & network your Subgraph will index, the events from these contracts to pay attention to, and how to map event data to entities that Graph Node stores and allows to query.

              The Subgraph definition consists of the following files:

              • subgraph.yaml: Contains the Subgraph manifest

              • schema.graphql: A GraphQL schema defining the data stored for your Subgraph and how to query it via GraphQL

              • mapping.ts: AssemblyScript Mappings⁠ code that translates event data into entities defined in your schema (e.g. mapping.ts in this guide)

              Subgraph Capabilities

              A single Subgraph can:

              • Birden fazla akıllı sözleşmeden veri endeksleyebilir (fakat birden fazla ağdan endeksleyemez).

              • IPFS dosyalarından Dosya Veri Kaynakları kullanarak veri endeksleyebilir.

              • Add an entry for each contract that requires indexing to the dataSources array.

              The full specification for Subgraph manifests can be found here⁠.

              For the example Subgraph listed above, subgraph.yaml is:

              1specVersion: 1.3.02description: Gravatar for Ethereum3repository: https://github.com/graphprotocol/graph-tooling4schema:5  file: ./schema.graphql6indexerHints:7  prune: auto8dataSources:9  - kind: ethereum/contract10    name: Gravity11    network: mainnet12    source:13      address: '0x2E645469f354BB4F5c8a05B3b30A929361cf77eC'14      abi: Gravity15      startBlock: 617524416      endBlock: 717524517    context:18      foo:19        type: Bool20        data: true21      bar:22        type: String23        data: 'bar'24    mapping:25      kind: ethereum/events26      apiVersion: 0.0.927      language: wasm/assemblyscript28      entities:29        - Gravatar30      abis:31        - name: Gravity32          file: ./abis/Gravity.json33      eventHandlers:34        - event: NewGravatar(uint256,address,string,string)35          handler: handleNewGravatar36        - event: UpdatedGravatar(uint256,address,string,string)37          handler: handleUpdatedGravatar38      callHandlers:39        - function: createGravatar(string,string)40          handler: handleCreateGravatar41      blockHandlers:42        - handler: handleBlock43        - handler: handleBlockWithCall44          filter:45            kind: call46      file: ./src/mapping.ts

              Subgraph Entries

              Important Note: Be sure you populate your Subgraph manifest with all handlers and entities.

              Manifest için güncellenmesi gereken önemli girdiler şunlardır:

              • specVersion: a semver version that identifies the supported manifest structure and functionality for the Subgraph. The latest version is 1.3.0. See specVersion releases section to see more details on features & releases.

              • description: a human-readable description of what the Subgraph is. This description is displayed in Graph Explorer when the Subgraph is deployed to Subgraph Studio.

              • repository: the URL of the repository where the Subgraph manifest can be found. This is also displayed in Graph Explorer.

              • features: a list of all used feature names.

              • indexerHints.prune: Defines the retention of historical block data for a Subgraph. See prune in indexerHints section.

              • dataSources.source: the address of the smart contract the Subgraph sources, and the ABI of the smart contract to use. The address is optional; omitting it allows to index matching events from all contracts.

              • dataSources.source.startBlock: the optional number of the block that the data source starts indexing from. In most cases, we suggest using the block in which the contract was created.

              • dataSources.source.endBlock: The optional number of the block that the data source stops indexing at, including that block. Minimum spec version required: 0.0.9.

              • dataSources.context: key-value pairs that can be used within Subgraph mappings. Supports various data types like Bool, String, Int, Int8, BigDecimal, Bytes, List, and BigInt. Each variable needs to specify its type and data. These context variables are then accessible in the mapping files, offering more configurable options for Subgraph development.

              • dataSources.mapping.entities: the entities that the data source writes to the store. The schema for each entity is defined in the schema.graphql file.

              • dataSources.mapping.abis: one or more named ABI files for the source contract as well as any other smart contracts that you interact with from within the mappings.

              • dataSources.mapping.eventHandlers: lists the smart contract events this Subgraph reacts to and the handlers in the mapping—./src/mapping.ts in the example—that transform these events into entities in the store.

              • dataSources.mapping.callHandlers: lists the smart contract functions this Subgraph reacts to and handlers in the mapping that transform the inputs and outputs to function calls into entities in the store.

              • dataSources.mapping.blockHandlers: lists the blocks this Subgraph reacts to and handlers in the mapping to run when a block is appended to the chain. Without a filter, the block handler will be run every block. An optional call-filter can be provided by adding a filter field with kind: call to the handler. This will only run the handler if the block contains at least one call to the data source contract.

              A single Subgraph can index data from multiple smart contracts. Add an entry for each contract from which data needs to be indexed to the dataSources array.

              Olay İşleyicileri

              Event handlers in a Subgraph react to specific events emitted by smart contracts on the blockchain and trigger handlers defined in the Subgraph’s manifest. This enables Subgraphs to process and store event data according to defined logic.

              Olay İşleyici Tanımlama

              An event handler is declared within a data source in the Subgraph’s YAML configuration. It specifies which events to listen for and the corresponding function to execute when those events are detected.

              1dataSources:2  - kind: ethereum/contract3    name: Gravity4    network: dev5    source:6      address: '0x731a10897d267e19b34503ad902d0a29173ba4b1'7      abi: Gravity8    mapping:9      kind: ethereum/events10      apiVersion: 0.0.911      language: wasm/assemblyscript12      entities:13        - Gravatar14        - Transaction15      abis:16        - name: Gravity17          file: ./abis/Gravity.json18      eventHandlers:19        - event: Approval(address,address,uint256)20          handler: handleApproval21        - event: Transfer(address,address,uint256)22          handler: handleTransfer23          topic1: ['0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045', '0xc8dA6BF26964aF9D7eEd9e03E53415D37aA96325'] # Optional topic filter which filters only events with the specified topic.

              Çağrı İşleyicileri

              While events provide an effective way to collect relevant changes to the state of a contract, many contracts avoid generating logs to optimize gas costs. In these cases, a Subgraph can subscribe to calls made to the data source contract. This is achieved by defining call handlers referencing the function signature and the mapping handler that will process calls to this function. To process these calls, the mapping handler will receive an ethereum.Call as an argument with the typed inputs to and outputs from the call. Calls made at any depth in a transaction’s call chain will trigger the mapping, allowing activity with the data source contract through proxy contracts to be captured.

              Çağrı işleyicileri yalnızca iki durumdan birinde tetiklenir: belirtilen işlevin sözleşme tarafından değil, başka bir hesap tarafından çağrılması durumunda veya Solidity’de harici olarak işaretlenip aynı sözleşmenin başka bir işlevinin bir parçası olarak çağrılması durumunda yalnızca tetiklenir.

              Note: Call handlers currently depend on the Parity tracing API. Certain networks, such as BNB chain and Arbitrum, does not support this API. If a Subgraph indexing one of these networks contain one or more call handlers, it will not start syncing. Subgraph developers should instead use event handlers. These are far more performant than call handlers, and are supported on every evm network.

              Bir Çağrı İşleyici Tanımlama

              To define a call handler in your manifest, simply add a callHandlers array under the data source you would like to subscribe to.

              1dataSources:2  - kind: ethereum/contract3    name: Gravity4    network: mainnet5    source:6      address: '0x731a10897d267e19b34503ad902d0a29173ba4b1'7      abi: Gravity8    mapping:9      kind: ethereum/events10      apiVersion: 0.0.911      language: wasm/assemblyscript12      entities:13        - Gravatar14        - Transaction15      abis:16        - name: Gravity17          file: ./abis/Gravity.json18      callHandlers:19        - function: createGravatar(string,string)20          handler: handleCreateGravatar

              The function is the normalized function signature to filter calls by. The handler property is the name of the function in your mapping you would like to execute when the target function is called in the data source contract.

              Eşleştirme fonksiyonu

              Each call handler takes a single parameter that has a type corresponding to the name of the called function. In the example Subgraph above, the mapping contains a handler for when the createGravatar function is called and receives a CreateGravatarCall parameter as an argument:

              1import { CreateGravatarCall } from '../generated/Gravity/Gravity'2import { Transaction } from '../generated/schema'34export function handleCreateGravatar(call: CreateGravatarCall): void {5  let id = call.transaction.hash6  let transaction = new Transaction(id)7  transaction.displayName = call.inputs._displayName8  transaction.imageUrl = call.inputs._imageUrl9  transaction.save()10}

              The handleCreateGravatar function takes a new CreateGravatarCall which is a subclass of ethereum.Call, provided by @graphprotocol/graph-ts, that includes the typed inputs and outputs of the call. The CreateGravatarCall type is generated for you when you run graph codegen.

              Blok İşleyicileri

              In addition to subscribing to contract events or function calls, a Subgraph may want to update its data as new blocks are appended to the chain. To achieve this a Subgraph can run a function after every block or after blocks that match a pre-defined filter.

              Desteklenen Filtreler

              Çağrı Filtresi

              1filter:2  kind: call

              The defined handler will be called once for every block which contains a call to the contract (data source) the handler is defined under.

              Note: The call filter currently depend on the Parity tracing API. Certain networks, such as BNB chain and Arbitrum, does not support this API. If a Subgraph indexing one of these networks contain one or more block handlers with a call filter, it will not start syncing.

              Bir blok işleyicisi için filtre olmaması, işleyicinin her blok için çağrılacağı anlamına gelir. Bir veri kaynağı, her filtre türü için yalnızca bir blok işleyicisi içerebilir.

              1dataSources:2  - kind: ethereum/contract3    name: Gravity4    network: dev5    source:6      address: '0x731a10897d267e19b34503ad902d0a29173ba4b1'7      abi: Gravity8    mapping:9      kind: ethereum/events10      apiVersion: 0.0.911      language: wasm/assemblyscript12      entities:13        - Gravatar14        - Transaction15      abis:16        - name: Gravity17          file: ./abis/Gravity.json18      blockHandlers:19        - handler: handleBlock20        - handler: handleBlockWithCallToContract21          filter:22            kind: call

              Polling Filtresi

              Requires specVersion >= 0.0.8

              Note: Polling filters are only available on dataSources of kind: ethereum.

              1blockHandlers:2  - handler: handleBlock3    filter:4      kind: polling5      every: 10

              The defined handler will be called once for every n blocks, where n is the value provided in the every field. This configuration allows the Subgraph to perform specific operations at regular block intervals.

              Once Filtresi

              Requires specVersion >= 0.0.8

              Note: Once filters are only available on dataSources of kind: ethereum.

              1blockHandlers:2  - handler: handleOnce3    filter:4      kind: once

              The defined handler with the once filter will be called only once before all other handlers run. This configuration allows the Subgraph to use the handler as an initialization handler, performing specific tasks at the start of indexing.

              1export function handleOnce(block: ethereum.Block): void {2  let data = new InitialData(Bytes.fromUTF8('initial'))3  data.data = 'Setup data here'4  data.save()5}

              Eşleştirme fonksiyonu

              The mapping function will receive an ethereum.Block as its only argument. Like mapping functions for events, this function can access existing Subgraph entities in the store, call smart contracts and create or update entities.

              1import { ethereum } from '@graphprotocol/graph-ts'23export function handleBlock(block: ethereum.Block): void {4  let id = block.hash5  let entity = new Block(id)6  entity.save()7}

              Anonim Olaylar

              Solidity’de anonim olayları işlemek gerekiyorsa, örnekte olduğu gibi, olayın topic 0’ını sağlayarak bunu başarabilirsiniz:

              1eventHandlers:2  - event: LogNote(bytes4,address,bytes32,bytes32,uint256,bytes)3    topic0: '0x644843f351d3fba4abcd60109eaff9f54bac8fb8ccf0bab941009c21df21cf31'4    handler: handleGive

              An event will only be triggered when both the signature and topic 0 match. By default, topic0 is equal to the hash of the event signature.

              Olay İşleyicilerinde İşlem Makbuzları

              Starting from specVersion 0.0.5 and apiVersion 0.0.7, event handlers can have access to the receipt for the transaction which emitted them.

              To do so, event handlers must be declared in the Subgraph manifest with the new receipt: true key, which is optional and defaults to false.

              1eventHandlers:2  - event: NewGravatar(uint256,address,string,string)3    handler: handleNewGravatar4    receipt: true

              Inside the handler function, the receipt can be accessed in the Event.receipt field. When the receipt key is set to false or omitted in the manifest, a null value will be returned instead.

              İşleyicilerin Tetiklenme Sırası

              Bir bloktaki veri kaynağı için tetikleyiciler şu işlemlerle sıralanır:

              1. Olay ve çağrı tetikleyicileri, öncelikle bloktaki işlem indeksine göre sıralanır.
              2. Aynı işlemdeki olay ve çağrı tetikleyicileri, bir kurala göre sıralanır: önce olay tetikleyicileri, ardından çağrı tetikleyicileri olmak üzere her tür manifest’te tanımlandıkları sıraya göre sıralanır.
              3. Blok tetikleyicileri, olay ve çağrı tetikleyicilerinden sonra manifest’te tanımlandıkları sırada göre çalıştırılır.

              Bu sıralama kuralları değişebilir.

              Note: When new dynamic data source are created, the handlers defined for dynamic data sources will only start processing after all existing data source handlers are processed, and will repeat in the same sequence whenever triggered.

              Veri Kaynağı Şablonları

              EVM uyumlu akıllı sözleşmelerde yaygın bir model, kayıt (registry) veya fabrika (factory) sözleşmelerinin kullanılmasıdır. Böylece ana sözleşme, kendi durumuna ve olaylarına sahip istenilen sayıda diğer sözleşmeyi oluşturur, yönetir veya bunlara referans verir.

              The addresses of these sub-contracts may or may not be known upfront and many of these contracts may be created and/or added over time. This is why, in such cases, defining a single data source or a fixed number of data sources is impossible and a more dynamic approach is needed: data source templates.

              Ana Sözleşme için Veri Kaynağı

              First, you define a regular data source for the main contract. The snippet below shows a simplified example data source for the Uniswap⁠ exchange factory contract. Note the NewExchange(address,address) event handler. This is emitted when a new exchange contract is created onchain by the factory contract.

              1dataSources:2  - kind: ethereum/contract3    name: Factory4    network: mainnet5    source:6      address: '0xc0a47dFe034B400B47bDaD5FecDa2621de6c4d95'7      abi: Factory8    mapping:9      kind: ethereum/events10      apiVersion: 0.0.911      language: wasm/assemblyscript12      file: ./src/mappings/factory.ts13      entities:14        - Directory15      abis:16        - name: Factory17          file: ./abis/factory.json18      eventHandlers:19        - event: NewExchange(address,address)20          handler: handleNewExchange

              Dinamik Olarak Oluşturulan Sözleşmeler için Veri Kaynağı Şablonları

              Then, you add data source templates to the manifest. These are identical to regular data sources, except that they lack a pre-defined contract address under source. Typically, you would define one template for each type of sub-contract managed or referenced by the parent contract.

              1dataSources:2  - kind: ethereum/contract3    name: Factory4    # ... other source fields for the main contract ...5templates:6  - name: Exchange7    kind: ethereum/contract8    network: mainnet9    source:10      abi: Exchange11    mapping:12      kind: ethereum/events13      apiVersion: 0.0.914      language: wasm/assemblyscript15      file: ./src/mappings/exchange.ts16      entities:17        - Exchange18      abis:19        - name: Exchange20          file: ./abis/exchange.json21      eventHandlers:22        - event: TokenPurchase(address,uint256,uint256)23          handler: handleTokenPurchase24        - event: EthPurchase(address,uint256,uint256)25          handler: handleEthPurchase26        - event: AddLiquidity(address,uint256,uint256)27          handler: handleAddLiquidity28        - event: RemoveLiquidity(address,uint256,uint256)29          handler: handleRemoveLiquidity

              Bir Veri Kaynağı Şablonunun Örneklenmesi

              In the final step, you update your main contract mapping to create a dynamic data source instance from one of the templates. In this example, you would change the main contract mapping to import the Exchange template and call the Exchange.create(address) method on it to start indexing the new exchange contract.

              1import { Exchange } from '../generated/templates'23export function handleNewExchange(event: NewExchange): void {4  // Borsayı indekslemeye başlayın; "event.params.exchange"5  // yeni borsa sözleşmesinin adresi6  Exchange.create(event.params.exchange)7}

              Note: A new data source will only process the calls and events for the block in which it was created and all following blocks, but will not process historical data, i.e., data that is contained in prior blocks.

              Eğer önceki bloklar, yeni veri kaynağı için ilgili veri içeriyorsa, o veriyi indekslemek için sözleşmenin mevcut durumunu okuyarak ve yeni veri kaynağı oluşturulurken o zaman dilimindeki durumu temsil eden varlıklar oluşturarak yapmak en iyisidir.

              Veri Kaynağı Bağlamı

              Data source contexts allow passing extra configuration when instantiating a template. In our example, let’s say exchanges are associated with a particular trading pair, which is included in the NewExchange event. That information can be passed into the instantiated data source, like so:

              1import { Exchange } from '../generated/templates'23export function handleNewExchange(event: NewExchange): void {4  let context = new DataSourceContext()5  context.setString('tradingPair', event.params.tradingPair)6  Exchange.createWithContext(event.params.exchange, context)7}

              Inside a mapping of the Exchange template, the context can then be accessed:

              1import { dataSource } from '@graphprotocol/graph-ts'23let context = dataSource.context()4let tradingPair = context.getString('tradingPair')

              There are setters and getters like setString and getString for all value types.

              Başlangıç Blokları

              The startBlock is an optional setting that allows you to define from which block in the chain the data source will start indexing. Setting the start block allows the data source to skip potentially millions of blocks that are irrelevant. Typically, a Subgraph developer will set startBlock to the block in which the smart contract of the data source was created.

              1dataSources:2  - kind: ethereum/contract3    name: ExampleSource4    network: mainnet5    source:6      address: '0xc0a47dFe034B400B47bDaD5FecDa2621de6c4d95'7      abi: ExampleContract8      startBlock: 66279179    mapping:10      kind: ethereum/events11      apiVersion: 0.0.912      language: wasm/assemblyscript13      file: ./src/mappings/factory.ts14      entities:15        - User16      abis:17        - name: ExampleContract18          file: ./abis/ExampleContract.json19      eventHandlers:20        - event: NewEvent(address,address)21          handler: handleNewEvent

              Note: The contract creation block can be quickly looked up on Etherscan:

              1. Arama çubuğuna adresini girerek sözleşmeyi arayın.
              2. Click on the creation transaction hash in the Contract Creator section.
              3. İşlem detayları sayfasını yükleyin ve bu sözleşme için başlangıç bloğunu bulacaksınız.

              Endeksleyici İpuçları

              The indexerHints setting in a Subgraph’s manifest provides directives for indexers on processing and managing a Subgraph. It influences operational decisions across data handling, indexing strategies, and optimizations. Presently, it features the prune option for managing historical data retention or pruning.

              This feature is available from specVersion: 1.0.0

              Budama

              indexerHints.prune: Defines the retention of historical block data for a Subgraph. Options include:

              1. "never": No pruning of historical data; retains the entire history.
              2. "auto": Retains the minimum necessary history as set by the indexer, optimizing query performance.
              3. Belirli bir sayı: Verilen sayıyı saklanacak tarihsel blok sayısı olarak ayarlar.
              1indexerHints:2  prune: auto

              The term “history” in this context of Subgraphs is about storing data that reflects the old states of mutable entities.

              Verilen bir bloktaki geçmiş, şu durumlar için gereklidir:

              • Time travel queries, which enable querying the past states of these entities at specific blocks throughout the Subgraph’s history
              • Using the Subgraph as a graft base in another Subgraph, at that block
              • Rewinding the Subgraph back to that block

              Eğer verilen bloktaki tarihsel veri budanmışsa yukarıdaki özellikler kullanılamayacaktır.

              Using "auto" is generally recommended as it maximizes query performance and is sufficient for most users who do not require access to extensive historical data.

              For Subgraphs leveraging time travel queries, it’s advisable to either set a specific number of blocks for historical data retention or use prune: never to keep all historical entity states. Below are examples of how to configure both options in your Subgraph’s settings:

              Belirli bir miktarda tarihsel veri saklamak için:

              1indexerHints:2  prune: 1000 # Replace 1000 with the desired number of blocks to retain

              Varlık durumlarının tam geçmişini korumak için:

              1indexerHints:2  prune: never

              SpecVersion Releases

              SürümSürüm Notları
              1.3.0Added support for Subgraph Composition
              1.2.0Added support for Indexed Argument Filtering & declared eth_call
              1.1.0Supports Timeseries & Aggregations. Added support for type Int8 for id.
              1.0.0Supports indexerHints feature to prune Subgraphs
              0.0.9Supports endBlock feature
              0.0.8Added support for polling Block Handlers and Initialisation Handlers.
              0.0.7Added support for File Data Sources.
              0.0.6Supports fast Proof of Indexing calculation variant.
              0.0.5İşleyicilerin işlem makbuzlarına erişim desteği eklendi.
              0.0.4Subgraph özelliklerini yönetme desteği eklendi.
              ⁠GitHub'da Düzenle⁠

              Graph CLI'ı YükleyinThe Graph QL Schema
              Bu sayfada
              • Genel Bakış
              • Subgraph Capabilities
              • Subgraph Entries
              • Olay İşleyicileri
              • Olay İşleyici Tanımlama
              • Çağrı İşleyicileri
              • Bir Çağrı İşleyici Tanımlama
              • Eşleştirme fonksiyonu
              • Blok İşleyicileri
              • Desteklenen Filtreler
              • Eşleştirme fonksiyonu
              • Anonim Olaylar
              • Olay İşleyicilerinde İşlem Makbuzları
              • İşleyicilerin Tetiklenme Sırası
              • Veri Kaynağı Şablonları
              • Ana Sözleşme için Veri Kaynağı
              • Dinamik Olarak Oluşturulan Sözleşmeler için Veri Kaynağı Şablonları
              • Bir Veri Kaynağı Şablonunun Örneklenmesi
              • Veri Kaynağı Bağlamı
              • Başlangıç Blokları
              • Endeksleyici İpuçları
              • Budama
              • SpecVersion Releases
              The GraphStatusTestnetBrand AssetsForumSecurityPrivacy PolicyTerms of Service