diff --git a/pages/ar/about/introduction.mdx b/pages/ar/about/introduction.mdx new file mode 100644 index 000000000000..5f840c040400 --- /dev/null +++ b/pages/ar/about/introduction.mdx @@ -0,0 +1,47 @@ +--- +title: Introduction +--- + +This page will explain what The Graph is and how you can get started. + +## What The Graph Is + +The Graph is a decentralized protocol for indexing and querying data from blockchains, starting with Ethereum. It makes it possible to query data that is difficult to query directly. + +Projects with complex smart contracts like [Uniswap](https://uniswap.org/) and NFTs initiatives like [Bored Ape Yacht Club](https://boredapeyachtclub.com/) store data on the Ethereum blockchain, making it really difficult to read anything other than basic data directly from the blockchain. + +In the case of Bored Ape Yacht Club, we can perform basic read operations on [the contract](https://etherscan.io/address/0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d#code) like getting the owner of a certain Ape, getting the content URI of an Ape based on their ID, or the total supply, as these read operations are programmed directly into the smart contract, but more advanced real-world queries and operations like aggregation, search, relationships, and non-trivial filtering are not possible. For example, if we wanted to query for apes that are owned by a certain address, and filter by one of its characteristics, we would not be able to get that information by interacting directly with the contract itself. + +To get this data, you would have to process every single [`transfer`](https://etherscan.io/address/0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d#code#L1746) event ever emitted, read the metadata from IPFS using the Token ID and IPFS hash, and then aggregate it. Even for these types of relatively simple questions, it would take **hours or even days** for a decentralized application (dapp) running in a browser to get an answer. + +You could also build out your own server, process the transactions there, save them to a database, and build an API endpoint on top of it all in order to query the data. However, this option is resource intensive, needs maintenance, presents a single point of failure, and breaks important security properties required for decentralization. + +**Indexing blockchain data is really, really hard.** + +Blockchain properties like finality, chain reorganizations, or uncled blocks complicate this process further, and make it not just time consuming but conceptually hard to retrieve correct query results from blockchain data. + +The Graph solves this with a decentralized protocol that indexes and enables the performant and efficient querying of blockchain data. These APIs (indexed "subgraphs") can then be queried with a standard GraphQL API. Today, there is a hosted service as well as a decentralized protocol with the same capabilities. Both are backed by the open source implementation of [Graph Node](https://github.com/graphprotocol/graph-node). + +## How The Graph Works + +The Graph learns what and how to index Ethereum data based on subgraph descriptions, known as the subgraph manifest. The subgraph description defines the smart contracts of interest for a subgraph, the events in those contracts to pay attention to, and how to map event data to data that The Graph will store in its database. + +Once you have written a `subgraph manifest`, you use the Graph CLI to store the definition in IPFS and tell the indexer to start indexing data for that subgraph. + +This diagram gives more detail about the flow of data once a subgraph manifest has been deployed, dealing with Ethereum transactions: + +![](/img/graph-dataflow.png) + +The flow follows these steps: + +1. A decentralized application adds data to Ethereum through a transaction on a smart contract. +2. The smart contract emits one or more events while processing the transaction. +3. Graph Node continually scans Ethereum for new blocks and the data for your subgraph they may contain. +4. Graph Node finds Ethereum events for your subgraph in these blocks and runs the mapping handlers you provided. The mapping is a WASM module that creates or updates the data entities that Graph Node stores in response to Ethereum events. +5. The decentralized application queries the Graph Node for data indexed from the blockchain, using the node's [GraphQL endpoint](https://graphql.org/learn/). The Graph Node in turn translates the GraphQL queries into queries for its underlying data store in order to fetch this data, making use of the store's indexing capabilities. The decentralized application displays this data in a rich UI for end-users, which they use to issue new transactions on Ethereum. The cycle repeats. + +## Next Steps + +In the following sections we will go into more detail on how to define subgraphs, how to deploy them, and how to query data from the indexes that Graph Node builds. + +Before you start writing your own subgraph, you might want to have a look at the Graph Explorer and explore some of the subgraphs that have already been deployed. The page for each subgraph contains a playground that lets you query that subgraph's data with GraphQL. diff --git a/pages/ar/about/network.mdx b/pages/ar/about/network.mdx new file mode 100644 index 000000000000..b19f08d12bc7 --- /dev/null +++ b/pages/ar/about/network.mdx @@ -0,0 +1,15 @@ +--- +title: Network Overview +--- + +The Graph Network is a decentralized indexing protocol for organizing blockchain data. Applications use GraphQL to query open APIs called subgraphs, to retrieve data that is indexed on the network. With The Graph, developers can build serverless applications that run entirely on public infrastructure. + +> GRT Token Address: [0xc944e90c64b2c07662a292be6244bdf05cda44a7](https://etherscan.io/token/0xc944e90c64b2c07662a292be6244bdf05cda44a7) + +## Overview + +The Graph Network consists of Indexers, Curators and Delegators that provide services to the network, and serve data to Web3 applications. Consumers use the applications and consume the data. + +![Token Economics](/img/Network-roles@2x.png) + +To ensure economic security of The Graph Network and the integrity of data being queried, participants stake and use Graph Tokens (GRT). GRT is a work token that is an ERC-20 on the Ethereum blockchain, used to allocate resources in the network. Active Indexers, Curators and Delegators can provide services and earn income from the network, proportional to the amount of work they perform and their GRT stake. diff --git a/pages/ar/curating.mdx b/pages/ar/curating.mdx index b13e20525f2f..6e37a8776a6f 100644 --- a/pages/ar/curating.mdx +++ b/pages/ar/curating.mdx @@ -100,5 +100,5 @@ title: (التنسيق) curating title="مشغل فيديو يوتيوب" frameBorder="0" allowFullScreen - > +> diff --git a/pages/ar/delegating.mdx b/pages/ar/delegating.mdx index 3a0d55f8363d..207be3e2a948 100644 --- a/pages/ar/delegating.mdx +++ b/pages/ar/delegating.mdx @@ -28,7 +28,9 @@ This guide will explain how to be an effective delegator in the Graph Network. D يجب اختيار المفهرس بحكمة. إذا اخترت مفهرسا ليس جديرا بالثقة ، أو لا يقوم بعمل جيد ، فستحتاج إلى إلغاء التفويض ، مما يعني أنك ستفقد الكثير من الفرص لكسب المكافآت والتي يمكن أن تكون سيئة مثل حرق GRT. -
لاحظ 0.5٪ رسوم التفويض ، بالإضافة إلى فترة 28 يوما لإلغاء التفويض.
+
+ لاحظ 0.5٪ رسوم التفويض ، بالإضافة إلى فترة 28 يوما لإلغاء التفويض. +
### اختيار مفهرس جدير بالثقة مع عائد جيد للمفوضين @@ -86,5 +88,5 @@ Using this formula, we can see that it is actually possible for an indexer who i title="مشغل فيديو يوتيوب" frameBorder="0" allowFullScreen - > +> diff --git a/pages/ar/developer/assemblyscript-api.mdx b/pages/ar/developer/assemblyscript-api.mdx new file mode 100644 index 000000000000..a609e6cd657f --- /dev/null +++ b/pages/ar/developer/assemblyscript-api.mdx @@ -0,0 +1,714 @@ +--- +title: AssemblyScript API +--- + +> Note: if you created a subgraph prior to `graph-cli`/`graph-ts` version `0.22.0`, you're using an older version of AssemblyScript, we recommend taking a look at the [`Migration Guide`](/developer/assemblyscript-migration-guide) + +This page documents what built-in APIs can be used when writing subgraph mappings. Two kinds of APIs are available out of the box: + +- the [Graph TypeScript library](https://github.com/graphprotocol/graph-ts) (`graph-ts`) and +- code generated from subgraph files by `graph codegen`. + +It is also possible to add other libraries as dependencies, as long as they are compatible with [AssemblyScript](https://github.com/AssemblyScript/assemblyscript). Since this is the language mappings are written in, the [AssemblyScript wiki](https://github.com/AssemblyScript/assemblyscript/wiki) is a good source for language and standard library features. + +## Installation + +Subgraphs created with [`graph init`](/developer/create-subgraph-hosted) come with preconfigured dependencies. All that is required to install these dependencies is to run one of the following commands: + +```sh +yarn install # Yarn +npm install # NPM +``` + +If the subgraph was created from scratch, one of the following two commands will install the Graph TypeScript library as a dependency: + +```sh +yarn add --dev @graphprotocol/graph-ts # Yarn +npm install --save-dev @graphprotocol/graph-ts # NPM +``` + +## API Reference + +The `@graphprotocol/graph-ts` library provides the following APIs: + +- An `ethereum` API for working with Ethereum smart contracts, events, blocks, transactions, and Ethereum values. +- A `store` API to load and save entities from and to the Graph Node store. +- A `log` API to log messages to the Graph Node output and the Graph Explorer. +- An `ipfs` API to load files from IPFS. +- A `json` API to parse JSON data. +- A `crypto` API to use cryptographic functions. +- Low-level primitives to translate between different type systems such as Ethereum, JSON, GraphQL and AssemblyScript. + +### Versions + +The `apiVersion` in the subgraph manifest specifies the mapping API version which is run by Graph Node for a given subgraph. The current mapping API version is 0.0.6. + +| Version | Release notes | +|:-------:| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 0.0.6 | Added `nonce` field to the Ethereum Transaction object
Added `baseFeePerGas` to the Ethereum Block object | +| 0.0.5 | AssemblyScript upgraded to version 0.19.10 (this includes breaking changes, please see the [`Migration Guide`](/developer/assemblyscript-migration-guide))
`ethereum.transaction.gasUsed` renamed to `ethereum.transaction.gasLimit` | +| 0.0.4 | Added `functionSignature` field to the Ethereum SmartContractCall object | +| 0.0.3 | Added `from` field to the Ethereum Call object
`etherem.call.address` renamed to `ethereum.call.to` | +| 0.0.2 | Added `input` field to the Ethereum Transaction object | + +### Built-in Types + +Documentation on the base types built into AssemblyScript can be found in the [AssemblyScript wiki](https://github.com/AssemblyScript/assemblyscript/wiki/Types). + +The following additional types are provided by `@graphprotocol/graph-ts`. + +#### ByteArray + +```typescript +import { ByteArray } from '@graphprotocol/graph-ts' +``` + +`ByteArray` represents an array of `u8`. + +_Construction_ + +- `fromI32(x: i32): ByteArray` - Decomposes `x` into bytes. +- `fromHexString(hex: string): ByteArray` - Input length must be even. Prefixing with `0x` is optional. + +_Type conversions_ + +- `toHexString(): string` - Converts to a hex string prefixed with `0x`. +- `toString(): string` - Interprets the bytes as a UTF-8 string. +- `toBase58(): string` - Encodes the bytes into a base58 string. +- `toU32(): u32` - Interprets the bytes as a little-endian `u32`. Throws in case of overflow. +- `toI32(): i32` - Interprets the byte array as a little-endian `i32`. Throws in case of overflow. + +_Operators_ + +- `equals(y: ByteArray): bool` – can be written as `x == y`. + +#### BigDecimal + +```typescript +import { BigDecimal } from '@graphprotocol/graph-ts' +``` + +`BigDecimal` is used to represent arbitrary precision decimals. + +_Construction_ + +- `constructor(bigInt: BigInt)` – creates a `BigDecimal` from an `BigInt`. +- `static fromString(s: string): BigDecimal` – parses from a decimal string. + +_Type conversions_ + +- `toString(): string` – prints to a decimal string. + +_Math_ + +- `plus(y: BigDecimal): BigDecimal` – can be written as `x + y`. +- `minus(y: BigDecimal): BigDecimal` – can be written as `x - y`. +- `times(y: BigDecimal): BigDecimal` – can be written as `x * y`. +- `dividedBy(y: BigDecimal): BigDecimal` – can be written as `x / y`. +- `equals(y: BigDecimal): bool` – can be written as `x == y`. +- `notEqual(y: BigDecimal): bool` – can be written as `x != y`. +- `lt(y: BigDecimal): bool` – can be written as `x < y`. +- `le(y: BigDecimal): bool` – can be written as `x <= y`. +- `gt(y: BigDecimal): bool` – can be written as `x > y`. +- `ge(y: BigDecimal): bool` – can be written as `x >= y`. +- `neg(): BigDecimal` - can be written as `-x`. + +#### BigInt + +```typescript +import { BigInt } from '@graphprotocol/graph-ts' +``` + +`BigInt` is used to represent big integers. This includes Ethereum values of type `uint32` to `uint256` and `int64` to `int256`. Everything below `uint32`, such as `int32`, `uint24` or `int8` is represented as `i32`. + +The `BigInt` class has the following API: + +_Construction_ + +- `BigInt.fromI32(x: i32): BigInt` – creates a `BigInt` from an `i32`. +- `BigInt.fromString(s: string): BigInt`– Parses a `BigInt` from a string. +- `BigInt.fromUnsignedBytes(x: Bytes): BigInt` – Interprets `bytes` as an unsigned, little-endian integer. If your input is big-endian, call `.reverse()` first. +- `BigInt.fromSignedBytes(x: Bytes): BigInt` – Interprets `bytes` as a signed, little-endian integer. If your input is big-endian, call `.reverse()` first. + + _Type conversions_ + +- `x.toHex(): string` – turns `BigInt` into a string of hexadecimal characters. +- `x.toString(): string` – turns `BigInt` into a decimal number string. +- `x.toI32(): i32` – returns the `BigInt` as an `i32`; fails if it the value does not fit into `i32`. It's a good idea to first check `x.isI32()`. +- `x.toBigDecimal(): BigDecimal` - converts into a decimal with no fractional part. + +_Math_ + +- `x.plus(y: BigInt): BigInt` – can be written as `x + y`. +- `x.minus(y: BigInt): BigInt` – can be written as `x - y`. +- `x.times(y: BigInt): BigInt` – can be written as `x * y`. +- `x.dividedBy(y: BigInt): BigInt` – can be written as `x / y`. +- `x.mod(y: BigInt): BigInt` – can be written as `x % y`. +- `x.equals(y: BigInt): bool` – can be written as `x == y`. +- `x.notEqual(y: BigInt): bool` – can be written as `x != y`. +- `x.lt(y: BigInt): bool` – can be written as `x < y`. +- `x.le(y: BigInt): bool` – can be written as `x <= y`. +- `x.gt(y: BigInt): bool` – can be written as `x > y`. +- `x.ge(y: BigInt): bool` – can be written as `x >= y`. +- `x.neg(): BigInt` – can be written as `-x`. +- `x.divDecimal(y: BigDecimal): BigDecimal` – divides by a decimal, giving a decimal result. +- `x.isZero(): bool` – Convenience for checking if the number is zero. +- `x.isI32(): bool` – Check if the number fits in an `i32`. +- `x.abs(): BigInt` – Absolute value. +- `x.pow(exp: u8): BigInt` – Exponentiation. +- `bitOr(x: BigInt, y: BigInt): BigInt` – can be written as `x | y`. +- `bitAnd(x: BigInt, y: BigInt): BigInt` – can be written as `x & y`. +- `leftShift(x: BigInt, bits: u8): BigInt` – can be written as `x << y`. +- `rightShift(x: BigInt, bits: u8): BigInt` – can be written as `x >> y`. + +#### TypedMap + +```typescript +import { TypedMap } from '@graphprotocol/graph-ts' +``` + +`TypedMap` can be used to stored key-value pairs. See [this example](https://github.com/graphprotocol/aragon-subgraph/blob/29dd38680c5e5104d9fdc2f90e740298c67e4a31/individual-dao-subgraph/mappings/constants.ts#L51). + +The `TypedMap` class has the following API: + +- `new TypedMap()` – creates an empty map with keys of type `K` and values of type `T` +- `map.set(key: K, value: V): void` – sets the value of `key` to `value` +- `map.getEntry(key: K): TypedMapEntry | null` – returns the key-value pair for a `key` or `null` if the `key` does not exist in the map +- `map.get(key: K): V | null` – returns the value for a `key` or `null` if the `key` does not exist in the map +- `map.isSet(key: K): bool` – returns `true` if the `key` exists in the map and `false` if it does not + +#### Bytes + +```typescript +import { Bytes } from '@graphprotocol/graph-ts' +``` + +`Bytes` is used to represent arbitrary-length arrays of bytes. This includes Ethereum values of type `bytes`, `bytes32` etc. + +The `Bytes` class extends AssemblyScript's [Uint8Array](https://github.com/AssemblyScript/assemblyscript/blob/3b1852bc376ae799d9ebca888e6413afac7b572f/std/assembly/typedarray.ts#L64) and this supports all the `Uint8Array` functionality, plus the following new methods: + +- `b.toHex()` – returns a hexadecimal string representing the bytes in the array +- `b.toString()` – converts the bytes in the array to a string of unicode characters +- `b.toBase58()` – turns an Ethereum Bytes value to base58 encoding (used for IPFS hashes) + +#### Address + +```typescript +import { Address } from '@graphprotocol/graph-ts' +``` + +`Address` extends `Bytes` to represent Ethereum `address` values. + +It adds the following method on top of the `Bytes` API: + +- `Address.fromString(s: string): Address` – creates an `Address` from a hexadecimal string + +### Store API + +```typescript +import { store } from '@graphprotocol/graph-ts' +``` + +The `store` API allows to load, save and remove entities from and to the Graph Node store. + +Entities written to the store map one-to-one to the `@entity` types defined in the subgraph's GraphQL schema. To make working with these entities convenient, the `graph codegen` command provided by the [Graph CLI](https://github.com/graphprotocol/graph-cli) generates entity classes, which are subclasses of the built-in `Entity` type, with property getters and setters for the fields in the schema as well as methods to load and save these entities. + +#### Creating entities + +The following is a common pattern for creating entities from Ethereum events. + +```typescript +// Import the Transfer event class generated from the ERC20 ABI +import { Transfer as TransferEvent } from '../generated/ERC20/ERC20' + +// Import the Transfer entity type generated from the GraphQL schema +import { Transfer } from '../generated/schema' + +// Transfer event handler +export function handleTransfer(event: TransferEvent): void { + // Create a Transfer entity, using the hexadecimal string representation + // of the transaction hash as the entity ID + let id = event.transaction.hash.toHex() + let transfer = new Transfer(id) + + // Set properties on the entity, using the event parameters + transfer.from = event.params.from + transfer.to = event.params.to + transfer.amount = event.params.amount + + // Save the entity to the store + transfer.save() +} +``` + +When a `Transfer` event is encountered while processing the chain, it is passed to the `handleTransfer` event handler using the generated `Transfer` type (aliased to `TransferEvent` here to avoid a naming conflict with the entity type). This type allows accessing data such as the event's parent transaction and its parameters. + +Each entity must have a unique ID to avoid collisions with other entities. It is fairly common for event parameters to include a unique identifier that can be used. Note: Using the transaction hash as the ID assumes that no other events in the same transaction create entities with this hash as the ID. + +#### Loading entities from the store + +If an entity already exists, it can be loaded from the store with the following: + +```typescript +let id = event.transaction.hash.toHex() // or however the ID is constructed +let transfer = Transfer.load(id) +if (transfer == null) { + transfer = new Transfer(id) +} + +// Use the Transfer entity as before +``` + +As the entity may not exist in the store yet, the `load` method returns a value of type `Transfer | null`. It may thus be necessary to check for the `null` case before using the value. + +> **Note:** Loading entities is only necessary if the changes made in the mapping depend on the previous data of an entity. See the next section for the two ways of updating existing entities. + +#### Updating existing entities + +There are two ways to update an existing entity: + +1. Load the entity with e.g. `Transfer.load(id)`, set properties on the entity, then `.save()` it back to the store. +2. Simply create the entity with e.g. `new Transfer(id)`, set properties on the entity, then `.save()` it to the store. If the entity already exists, the changes are merged into it. + +Changing properties is straight forward in most cases, thanks to the generated property setters: + +```typescript +let transfer = new Transfer(id) +transfer.from = ... +transfer.to = ... +transfer.amount = ... +``` + +It is also possible to unset properties with one of the following two instructions: + +```typescript +transfer.from.unset() +transfer.from = null +``` + +This only works with optional properties, i.e. properties that are declared without a `!` in GraphQL. Two examples would be `owner: Bytes` or `amount: BigInt`. + +Updating array properties is a little more involved, as the getting an array from an entity creates a copy of that array. This means array properties have to be set again explicitly after changing the array. The following assumes `entity` has a `numbers: [BigInt!]!` field. + +```typescript +// This won't work +entity.numbers.push(BigInt.fromI32(1)) +entity.save() + +// This will work +let numbers = entity.numbers +numbers.push(BigInt.fromI32(1)) +entity.numbers = numbers +entity.save() +``` + +#### Removing entities from the store + +There is currently no way to remove an entity via the generated types. Instead, removing an entity requires passing the name of the entity type and the entity ID to `store.remove`: + +```typescript +import { store } from '@graphprotocol/graph-ts' +... +let id = event.transaction.hash.toHex() +store.remove('Transfer', id) +``` + +### Ethereum API + +The Ethereum API provides access to smart contracts, public state variables, contract functions, events, transactions, blocks and the encoding/decoding Ethereum data. + +#### Support for Ethereum Types + +As with entities, `graph codegen` generates classes for all smart contracts and events used in a subgraph. For this, the contract ABIs need to be part of the data source in the subgraph manifest. Typically, the ABI files are stored in an `abis/` folder. + +With the generated classes, conversions between Ethereum types and the [built-in types](#built-in-types) take place behind the scenes so that subgraph authors do not have to worry about them. + +The following example illustrates this. Given a subgraph schema like + +```graphql +type Transfer @entity { + from: Bytes! + to: Bytes! + amount: BigInt! +} +``` + +and a `Transfer(address,address,uint256)` event signature on Ethereum, the `from`, `to` and `amount` values of type `address`, `address` and `uint256` are converted to `Address` and `BigInt`, allowing them to be passed on to the `Bytes!` and `BigInt!` properties of the `Transfer` entity: + +```typescript +let id = event.transaction.hash.toHex() +let transfer = new Transfer(id) +transfer.from = event.params.from +transfer.to = event.params.to +transfer.amount = event.params.amount +transfer.save() +``` + +#### Events and Block/Transaction Data + +Ethereum events passed to event handlers, such as the `Transfer` event in the previous examples, not only provide access to the event parameters but also to their parent transaction and the block they are part of. The following data can be obtained from `event` instances (these classes are a part of the `ethereum` module in `graph-ts`): + +```typescript +class Event { + address: Address + logIndex: BigInt + transactionLogIndex: BigInt + logType: string | null + block: Block + transaction: Transaction + parameters: Array +} + +class Block { + hash: Bytes + parentHash: Bytes + unclesHash: Bytes + author: Address + stateRoot: Bytes + transactionsRoot: Bytes + receiptsRoot: Bytes + number: BigInt + gasUsed: BigInt + gasLimit: BigInt + timestamp: BigInt + difficulty: BigInt + totalDifficulty: BigInt + size: BigInt | null + baseFeePerGas: BigInt | null +} + +class Transaction { + hash: Bytes + index: BigInt + from: Address + to: Address | null + value: BigInt + gasLimit: BigInt + gasPrice: BigInt + input: Bytes + nonce: BigInt +} +``` + +#### Access to Smart Contract State + +The code generated by `graph codegen` also includes classes for the smart contracts used in the subgraph. These can be used to access public state variables and call functions of the contract at the current block. + +A common pattern is to access the contract from which an event originates. This is achieved with the following code: + +```typescript +// Import the generated contract class +import { ERC20Contract } from '../generated/ERC20Contract/ERC20Contract' +// Import the generated entity class +import { Transfer } from '../generated/schema' + +export function handleTransfer(event: Transfer) { + // Bind the contract to the address that emitted the event + let contract = ERC20Contract.bind(event.address) + + // Access state variables and functions by calling them + let erc20Symbol = contract.symbol() +} +``` + +As long as the `ERC20Contract` on Ethereum has a public read-only function called `symbol`, it can be called with `.symbol()`. For public state variables a method with the same name is created automatically. + +Any other contract that is part of the subgraph can be imported from the generated code and can be bound to a valid address. + +#### Handling Reverted Calls + +If the read-only methods of your contract may revert, then you should handle that by calling the generated contract method prefixed with `try_`. For example, the Gravity contract exposes the `gravatarToOwner` method. This code would be able to handle a revert in that method: + +```typescript +let gravity = Gravity.bind(event.address) +let callResult = gravity.try_gravatarToOwner(gravatar) +if (callResult.reverted) { + log.info('getGravatar reverted', []) +} else { + let owner = callResult.value +} +``` + +Note that a Graph node connected to a Geth or Infura client may not detect all reverts, if you rely on this we recommend using a Graph node connected to a Parity client. + +#### Encoding/Decoding ABI + +Data can be encoded and decoded according to Ethereum's ABI encoding format using the `encode` and `decode` functions in the `ethereum` module. + +```typescript +import { Address, BigInt, ethereum } from '@graphprotocol/graph-ts' + +let tupleArray: Array = [ + ethereum.Value.fromAddress(Address.fromString('0x0000000000000000000000000000000000000420')), + ethereum.Value.fromUnsignedBigInt(BigInt.fromI32(62)), +] + +let tuple = tupleArray as ethereum.Tuple + +let encoded = ethereum.encode(ethereum.Value.fromTuple(tuple))! + +let decoded = ethereum.decode('(address,uint256)', encoded) +``` + +For more information: + +- [ABI Spec](https://docs.soliditylang.org/en/v0.7.4/abi-spec.html#types) +- Encoding/decoding [Rust library/CLI](https://github.com/rust-ethereum/ethabi) +- More [complex example](https://github.com/graphprotocol/graph-node/blob/6a7806cc465949ebb9e5b8269eeb763857797efc/tests/integration-tests/host-exports/src/mapping.ts#L72). + +### Logging API + +```typescript +import { log } from '@graphprotocol/graph-ts' +``` + +The `log` API allows subgraphs to log information to the Graph Node standard output as well as the Graph Explorer. Messages can be logged using different log levels. A basic format string syntax is provided to compose log messages from argument. + +The `log` API includes the following functions: + +- `log.debug(fmt: string, args: Array): void` - logs a debug message. +- `log.info(fmt: string, args: Array): void` - logs an informational message. +- `log.warning(fmt: string, args: Array): void` - logs a warning. +- `log.error(fmt: string, args: Array): void` - logs an error message. +- `log.critical(fmt: string, args: Array): void` – logs a critical message _and_ terminates the subgraph. + +The `log` API takes a format string and an array of string values. It then replaces placeholders with the string values from the array. The first `{}` placeholder gets replaced by the first value in the array, the second `{}` placeholder gets replaced by the second value and so on. + +```typescript +log.info('Message to be displayed: {}, {}, {}', [value.toString(), anotherValue.toString(), 'already a string']) +``` + +#### Logging one or more values + +##### Logging a single value + +In the example below, the string value "A" is passed into an array to become`['A']` before being logged: + +```typescript +let myValue = 'A' + +export function handleSomeEvent(event: SomeEvent): void { + // Displays : "My value is: A" + log.info('My value is: {}', [myValue]) +} +``` + +##### Logging a single entry from an existing array + +In the example below, only the first value of the argument array is logged, despite the array containing three values. + +```typescript +let myArray = ['A', 'B', 'C'] + +export function handleSomeEvent(event: SomeEvent): void { + // Displays : "My value is: A" (Even though three values are passed to `log.info`) + log.info('My value is: {}', myArray) +} +``` + +#### Logging multiple entries from an existing array + +Each entry in the arguments array requires its own placeholder `{}` in the log message string. The below example contains three placeholders `{}` in the log message. Because of this, all three values in `myArray` are logged. + +```typescript +let myArray = ['A', 'B', 'C'] + +export function handleSomeEvent(event: SomeEvent): void { + // Displays : "My first value is: A, second value is: B, third value is: C" + log.info('My first value is: {}, second value is: {}, third value is: {}', myArray) +} +``` + +##### Logging a specific entry from an existing array + +To display a specific value in the array, the indexed value must be provided. + +```typescript +export function handleSomeEvent(event: SomeEvent): void { + // Displays : "My third value is C" + log.info('My third value is: {}', [myArray[2]]) +} +``` + +##### Logging event information + +The example below logs the block number, block hash and transaction hash from an event: + +```typescript +import { log } from '@graphprotocol/graph-ts' + +export function handleSomeEvent(event: SomeEvent): void { + log.debug('Block number: {}, block hash: {}, transaction hash: {}', [ + event.block.number.toString(), // "47596000" + event.block.hash.toHexString(), // "0x..." + event.transaction.hash.toHexString(), // "0x..." + ]) +} +``` + +### IPFS API + +```typescript +import { ipfs } from '@graphprotocol/graph-ts' +``` + +Smart contracts occasionally anchor IPFS files on chain. This allows mappings to obtain the IPFS hashes from the contract and read the corresponding files from IPFS. The file data will be returned as `Bytes`, which usually requires further processing, e.g. with the `json` API documented later on this page. + +Given an IPFS hash or path, reading a file from IPFS is done as follows: + +```typescript +// Put this inside an event handler in the mapping +let hash = 'QmTkzDwWqPbnAh5YiV5VwcTLnGdwSNsNTn2aDxdXBFca7D' +let data = ipfs.cat(hash) + +// Paths like `QmTkzDwWqPbnAh5YiV5VwcTLnGdwSNsNTn2aDxdXBFca7D/Makefile` +// that include files in directories are also supported +let path = 'QmTkzDwWqPbnAh5YiV5VwcTLnGdwSNsNTn2aDxdXBFca7D/Makefile' +let data = ipfs.cat(path) +``` + +**Note:** `ipfs.cat` is not deterministic at the moment. If the file cannot be retrieved over the IPFS network before the request times out, it will return `null`. Due to this, it's always worth checking the result for `null`. To ensure that files can be retrieved, they have to be pinned to the IPFS node that Graph Node connects to. On the [hosted service](https://thegraph.com/hosted-service), this is [https://api.thegraph.com/ipfs/](https://api.thegraph.com/ipfs). See the [IPFS pinning](/developer/create-subgraph-hosted#ipfs-pinning) section for more information. + +It is also possible to process larger files in a streaming fashion with `ipfs.map`. The function expects the hash or path for an IPFS file, the name of a callback, and flags to modify its behavior: + +```typescript +import { JSONValue, Value } from '@graphprotocol/graph-ts' + +export function processItem(value: JSONValue, userData: Value): void { + // See the JSONValue documentation for details on dealing + // with JSON values + let obj = value.toObject() + let id = obj.get('id') + let title = obj.get('title') + + if (!id || !title) { + return + } + + // Callbacks can also created entities + let newItem = new Item(id.toString()) + newItem.title = title.toString() + newitem.parent = userData.toString() // Set parent to "parentId" + newitem.save() +} + +// Put this inside an event handler in the mapping +ipfs.map('Qm...', 'processItem', Value.fromString('parentId'), ['json']) + +// Alternatively, use `ipfs.mapJSON` +ipfs.mapJSON('Qm...', 'processItem', Value.fromString('parentId')) +``` + +The only flag currently supported is `json`, which must be passed to `ipfs.map`. With the `json` flag, the IPFS file must consist of a series of JSON values, one value per line. The call to `ipfs.map` will read each line in the file, deserialize it into a `JSONValue` and call the callback for each of them. The callback can then use entity operations to store data from the `JSONValue`. Entity changes are stored only when the handler that called `ipfs.map` finishes successfully; in the meantime, they are kept in memory, and the size of the file that `ipfs.map` can process is therefore limited. + +On success, `ipfs.map` returns `void`. If any invocation of the callback causes an error, the handler that invoked `ipfs.map` is aborted, and the subgraph is marked as failed. + +### Crypto API + +```typescript +import { crypto } from '@graphprotocol/graph-ts' +``` + +The `crypto` API makes a cryptographic functions available for use in mappings. Right now, there is only one: + +- `crypto.keccak256(input: ByteArray): ByteArray` + +### JSON API + +```typescript +import { json, JSONValueKind } from '@graphprotocol/graph-ts' +``` + +JSON data can be parsed using the `json` API: + +- `json.fromBytes(data: Bytes): JSONValue` – parses JSON data from a `Bytes` array +- `json.try_fromBytes(data: Bytes): Result` – safe version of `json.fromBytes`, it returns an error variant if the parsing failed +- `json.fromString(data: Bytes): JSONValue` – parses JSON data from a valid UTF-8 `String` +- `json.try_fromString(data: Bytes): Result` – safe version of `json.fromString`, it returns an error variant if the parsing failed + +The `JSONValue` class provides a way to pull values out of an arbitrary JSON document. Since JSON values can be booleans, numbers, arrays and more, `JSONValue` comes with a `kind` property to check the type of a value: + +```typescript +let value = json.fromBytes(...) +if (value.kind == JSONValueKind.BOOL) { + ... +} +``` + +In addition, there is a method to check if the value is `null`: + +- `value.isNull(): boolean` + +When the type of a value is certain, it can be converted to a [built-in type](#built-in-types) using one of the following methods: + +- `value.toBool(): boolean` +- `value.toI64(): i64` +- `value.toF64(): f64` +- `value.toBigInt(): BigInt` +- `value.toString(): string` +- `value.toArray(): Array` - (and then convert `JSONValue` with one of the 5 methods above) + +### Type Conversions Reference + +| Source(s) | Destination | Conversion function | +| -------------------- | -------------------- | ---------------------------- | +| Address | Bytes | none | +| Address | ID | s.toHexString() | +| Address | String | s.toHexString() | +| BigDecimal | String | s.toString() | +| BigInt | BigDecimal | s.toBigDecimal() | +| BigInt | String (hexadecimal) | s.toHexString() or s.toHex() | +| BigInt | String (unicode) | s.toString() | +| BigInt | i32 | s.toI32() | +| Boolean | Boolean | none | +| Bytes (signed) | BigInt | BigInt.fromSignedBytes(s) | +| Bytes (unsigned) | BigInt | BigInt.fromUnsignedBytes(s) | +| Bytes | String (hexadecimal) | s.toHexString() or s.toHex() | +| Bytes | String (unicode) | s.toString() | +| Bytes | String (base58) | s.toBase58() | +| Bytes | i32 | s.toI32() | +| Bytes | u32 | s.toU32() | +| Bytes | JSON | json.fromBytes(s) | +| int8 | i32 | none | +| int32 | i32 | none | +| int32 | BigInt | Bigint.fromI32(s) | +| uint24 | i32 | none | +| int64 - int256 | BigInt | none | +| uint32 - uint256 | BigInt | none | +| JSON | boolean | s.toBool() | +| JSON | i64 | s.toI64() | +| JSON | u64 | s.toU64() | +| JSON | f64 | s.toF64() | +| JSON | BigInt | s.toBigInt() | +| JSON | string | s.toString() | +| JSON | Array | s.toArray() | +| JSON | Object | s.toObject() | +| String | Address | Address.fromString(s) | +| String | BigDecimal | BigDecimal.fromString(s) | +| String (hexadecimal) | Bytes | ByteArray.fromHexString(s) | +| String (UTF-8) | Bytes | ByteArray.fromUTF8(s) | + +### Data Source Metadata + +You can inspect the contract address, network and context of the data source that invoked the handler through the `dataSource` namespace: + +- `dataSource.address(): Address` +- `dataSource.network(): string` +- `dataSource.context(): DataSourceContext` + +### Entity and DataSourceContext + +The base `Entity` class and the child `DataSourceContext` class have helpers to dynamically set and get fields: + +- `setString(key: string, value: string): void` +- `setI32(key: string, value: i32): void` +- `setBigInt(key: string, value: BigInt): void` +- `setBytes(key: string, value: Bytes): void` +- `setBoolean(key: string, value: bool): void` +- `setBigDecimal(key, value: BigDecimal): void` +- `getString(key: string): string` +- `getI32(key: string): i32` +- `getBigInt(key: string): BigInt` +- `getBytes(key: string): Bytes` +- `getBoolean(key: string): boolean` +- `getBigDecimal(key: string): BigDecimal` diff --git a/pages/ar/developer/assemblyscript-migration-guide.mdx b/pages/ar/developer/assemblyscript-migration-guide.mdx new file mode 100644 index 000000000000..2db90a608110 --- /dev/null +++ b/pages/ar/developer/assemblyscript-migration-guide.mdx @@ -0,0 +1,484 @@ +--- +title: AssemblyScript Migration Guide +--- + +Up until now, subgraphs have been using one of the [first versions of AssemblyScript](https://github.com/AssemblyScript/assemblyscript/tree/v0.6) (v0.6). Finally we've added support for the [newest one available](https://github.com/AssemblyScript/assemblyscript/tree/v0.19.10) (v0.19.10)! 🎉 + +That will enable subgraph developers to use newer features of the AS language and standard library. + +This guide is applicable for anyone using `graph-cli`/`graph-ts` below version `0.22.0`. If you're already at a higher than (or equal) version to that, you've already been using version `0.19.10` of AssemblyScript 🙂 + +> Note: As of `0.24.0`, `graph-node` can support both versions, depending on the `apiVersion` specified in the subgraph manifest. + +## Features + +### New functionality + +- `TypedArray`s can now be built from `ArrayBuffer`s by using the [new `wrap` static method](https://www.assemblyscript.org/stdlib/typedarray.html#static-members) ([v0.8.1](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.8.1)) +- New standard library functions: `String#toUpperCase`, `String#toLowerCase`, `String#localeCompare`and `TypedArray#set` ([v0.9.0](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.9.0)) +- Added support for x instanceof GenericClass ([v0.9.2](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.9.2)) +- Added `StaticArray`, a more efficient array variant ([v0.9.3](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.9.3)) +- Added `Array#flat` ([v0.10.0](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.10.0)) +- Implemented `radix` argument on `Number#toString` ([v0.10.1](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.10.1)) +- Added support for separators in floating point literals ([v0.13.7](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.13.7)) +- Added support for first class functions ([v0.14.0](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.14.0)) +- Add builtins: `i32/i64/f32/f64.add/sub/mul` ([v0.14.13](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.14.13)) +- Implement `Array/TypedArray/String#at` ([v0.18.2](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.18.2)) +- Added support for template literal strings ([v0.18.17](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.18.17)) +- Add `encodeURI(Component)` and `decodeURI(Component)` ([v0.18.27](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.18.27)) +- Add `toString`, `toDateString` and `toTimeString` to `Date` ([v0.18.29](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.18.29)) +- Add `toUTCString` for `Date` ([v0.18.30](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.18.30)) +- Add `nonnull/NonNullable` builtin type ([v0.19.2](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.19.2)) + +### Optimizations + +- `Math` functions such as `exp`, `exp2`, `log`, `log2` and `pow` have been replaced by faster variants ([v0.9.0](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.9.0)) +- Slightly optimize `Math.mod` ([v0.17.1](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.17.1)) +- Cache more field accesses in std Map and Set ([v0.17.8](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.17.8)) +- Optimize for powers of two in `ipow32/64` ([v0.18.2](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.18.2)) + +### Other + +- The type of an array literal can now be inferred from its contents ([v0.9.0](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.9.0)) +- Updated stdlib to Unicode 13.0.0 ([v0.10.0](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.10.0)) + +## How to upgrade? + +1. Change your mappings `apiVersion` in `subgraph.yaml` to `0.0.6`: + +```yaml +... +dataSources: + ... + mapping: + ... + apiVersion: 0.0.6 + ... +``` + +2. Update the `graph-cli` you're using to the `latest` version by running: + +```bash +# if you have it globally installed +npm install --global @graphprotocol/graph-cli@latest + +# or in your subgraph if you have it as a dev dependency +npm install --save-dev @graphprotocol/graph-cli@latest +``` + +3. Do the same for `graph-ts`, but instead of installing globally, save it in your main dependencies: + +```bash +npm install --save @graphprotocol/graph-ts@latest +``` + +4. Follow the rest of the guide to fix the language breaking changes. +5. Run `codegen` and `deploy` again. + +## Breaking changes + +### Nullability + +On the older version of AssemblyScript, you could create code like this: + +```typescript +function load(): Value | null { ... } + +let maybeValue = load(); +maybeValue.aMethod(); +``` + +However on the newer version, because the value is nullable, it requires you to check, like this: + +```typescript +let maybeValue = load() + +if (maybeValue) { + maybeValue.aMethod() // `maybeValue` is not null anymore +} +``` + +Or force it like this: + +```typescript +let maybeValue = load()! // breaks in runtime if value is null + +maybeValue.aMethod() +``` + +If you are unsure which to choose, we recommend always using the safe version. If the value doesn't exist you might want to just do an early if statement with a return in you subgraph handler. + +### Variable Shadowing + +Before you could do [variable shadowing](https://en.wikipedia.org/wiki/Variable_shadowing) and code like this would work: + +```typescript +let a = 10 +let b = 20 +let a = a + b +``` + +However now this isn't possible anymore, and the compiler returns this error: + +```typescript +ERROR TS2451: Cannot redeclare block-scoped variable 'a' + + let a = a + b; + ~~~~~~~~~~~~~ +in assembly/index.ts(4,3) +``` +You'll need to rename your duplicate variables if you had variable shadowing. +### Null Comparisons +By doing the upgrade on your subgraph, sometimes you might get errors like these: + +```typescript +ERROR TS2322: Type '~lib/@graphprotocol/graph-ts/common/numbers/BigInt | null' is not assignable to type '~lib/@graphprotocol/graph-ts/common/numbers/BigInt'. + if (decimals == null) { + ~~~~ + in src/mappings/file.ts(41,21) +``` +To solve you can simply change the `if` statement to something like this: + +```typescript + if (!decimals) { + + // or + + if (decimals === null) { +``` + +The same applies if you're doing != instead of ==. + +### Casting + +The common way to do casting before was to just use the `as` keyword, like this: + +```typescript +let byteArray = new ByteArray(10) +let uint8Array = byteArray as Uint8Array // equivalent to: byteArray +``` + +However this only works in two scenarios: + +- Primitive casting (between types such as `u8`, `i32`, `bool`; eg: `let b: isize = 10; b as usize`); +- Upcasting on class inheritance (subclass → superclass) + +Examples: + +```typescript +// primitive casting +let a: usize = 10 +let b: isize = 5 +let c: usize = a + (b as usize) +``` + +```typescript +// upcasting on class inheritance +class Bytes extends Uint8Array {} + +let bytes = new Bytes(2) < Uint8Array > bytes // same as: bytes as Uint8Array +``` + +There are two scenarios where you may want to cast, but using `as`/`var` **isn't safe**: + +- Downcasting on class inheritance (superclass → subclass) +- Between two types that share a superclass + +```typescript +// downcasting on class inheritance +class Bytes extends Uint8Array {} + +let uint8Array = new Uint8Array(2) < Bytes > uint8Array // breaks in runtime :( +``` + +```typescript +// between two types that share a superclass +class Bytes extends Uint8Array {} +class ByteArray extends Uint8Array {} + +let bytes = new Bytes(2) < ByteArray > bytes // breaks in runtime :( +``` + +For those cases, you can use the `changetype` function: + +```typescript +// downcasting on class inheritance +class Bytes extends Uint8Array {} + +let uint8Array = new Uint8Array(2) +changetype(uint8Array) // works :) +``` + +```typescript +// between two types that share a superclass +class Bytes extends Uint8Array {} +class ByteArray extends Uint8Array {} + +let bytes = new Bytes(2) +changetype(bytes) // works :) +``` + +If you just want to remove nullability, you can keep using the `as` operator (or `variable`), but make sure you know that value can't be null, otherwise it will break. + +```typescript +// remove nullability +let previousBalance = AccountBalance.load(balanceId) // AccountBalance | null + +if (previousBalance != null) { + return previousBalance as AccountBalance // safe remove null +} + +let newBalance = new AccountBalance(balanceId) +``` + +For the nullability case we recommend taking a look at the [nullability check feature](https://www.assemblyscript.org/basics.html#nullability-checks), it will make your code cleaner 🙂 + +Also we've added a few more static methods in some types to ease casting, they are: + +- Bytes.fromByteArray +- Bytes.fromUint8Array +- BigInt.fromByteArray +- ByteArray.fromBigInt + +### Nullability check with property access + +To use the [nullability check feature](https://www.assemblyscript.org/basics.html#nullability-checks) you can use either `if` statements or the ternary operator (`?` and `:`) like this: + +```typescript +let something: string | null = 'data' + +let somethingOrElse = something ? something : 'else' + +// or + +let somethingOrElse + +if (something) { + somethingOrElse = something +} else { + somethingOrElse = 'else' +} +``` + +However that only works when you're doing the `if` / ternary on a variable, not on a property access, like this: + +```typescript +class Container { + data: string | null +} + +let container = new Container() +container.data = 'data' + +let somethingOrElse: string = container.data ? container.data : 'else' // doesn't compile +``` + +Which outputs this error: + +```typescript +ERROR TS2322: Type '~lib/string/String | null' is not assignable to type '~lib/string/String'. + + let somethingOrElse: string = container.data ? container.data : "else"; + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +``` +To fix this issue, you can create a variable for that property access so that the compiler can do the nullability check magic: + +```typescript +class Container { + data: string | null +} + +let container = new Container() +container.data = 'data' + +let data = container.data + +let somethingOrElse: string = data ? data : 'else' // compiles just fine :) +``` + +### Operator overloading with property access + +If you try to sum (for example) a nullable type (from a property access) with a non nullable one, the AssemblyScript compiler instead of giving a compile time error warning that one of the values is nullable, it just compiles silently, giving chance for the code to break at runtime. + +```typescript +class BigInt extends Uint8Array { + @operator('+') + plus(other: BigInt): BigInt { + // ... + } +} + +class Wrapper { + public constructor(public n: BigInt | null) {} +} + +let x = BigInt.fromI32(2) +let y: BigInt | null = null + +x + y // give compile time error about nullability + +let wrapper = new Wrapper(y) + +wrapper.n = wrapper.n + x // doesn't give compile time errors as it should +``` + +We've opened a issue on the AssemblyScript compiler for this, but for now if you do these kind of operations in your subgraph mappings, you should change them to do a null check before it. + +```typescript +let wrapper = new Wrapper(y) + +if (!wrapper.n) { + wrapper.n = BigInt.fromI32(0) +} + +wrapper.n = wrapper.n + x // now `n` is guaranteed to be a BigInt +``` + +### Value initialization + +If you have any code like this: + +```typescript +var value: Type // null +value.x = 10 +value.y = 'content' +``` + +It will compile but break at runtime, that happens because the value hasn't been initialized, so make sure your subgraph has initialized their values, like this: + +```typescript +var value = new Type() // initialized +value.x = 10 +value.y = 'content' +``` + +Also if you have nullable properties in a GraphQL entity, like this: + +```graphql +type Total @entity { + id: ID! + amount: BigInt +} +``` + +And you have code similar to this: + +```typescript +let total = Total.load('latest') + +if (total === null) { + total = new Total('latest') +} + +total.amount = total.amount + BigInt.fromI32(1) +``` + +You'll need to make sure to initialize the `total.amount` value, because if you try to access like in the last line for the sum, it will crash. So you either initialize it first: + +```typescript +let total = Total.load('latest') + +if (total === null) { + total = new Total('latest') + total.amount = BigInt.fromI32(0) +} + +total.tokens = total.tokens + BigInt.fromI32(1) +``` + +Or you can just change your GraphQL schema to not use a nullable type for this property, then we'll initialize it as zero on the `codegen` step 😉 + +```graphql +type Total @entity { + id: ID! + amount: BigInt! +} +``` + +```typescript +let total = Total.load('latest') + +if (total === null) { + total = new Total('latest') // already initializes non-nullable properties +} + +total.amount = total.amount + BigInt.fromI32(1) +``` + +### Class property initialization + +If you export any classes with properties that are other classes (declared by you or by the standard library) like this: + +```typescript +class Thing {} + +export class Something { + value: Thing +} +``` + +The compiler will error because you either need to add an initializer for the properties that are classes, or add the `!` operator: + +```typescript +export class Something { + constructor(public value: Thing) {} +} + +// or + +export class Something { + value: Thing + + constructor(value: Thing) { + this.value = value + } +} + +// or + +export class Something { + value!: Thing +} +``` + +### GraphQL schema + +This is not a direct AssemblyScript change, but you may have to update your `schema.graphql` file. + +Now you no longer can define fields in your types that are Non-Nullable Lists. If you have a schema like this: + +```graphql +type Something @entity { + id: ID! +} + +type MyEntity @entity { + id: ID! + invalidField: [Something]! # no longer valid +} +``` + +You'll have to add an `!` to the member of the List type, like this: + +```graphql +type Something @entity { + id: ID! +} + +type MyEntity @entity { + id: ID! + invalidField: [Something!]! # valid +} +``` + +This changed because of nullability differences between AssemblyScript versions, and it's related to the `src/generated/schema.ts` file (default path, you might have changed this). + +### Other + +- Aligned `Map#set` and `Set#add` with the spec, returning `this` ([v0.9.2](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.9.2)) +- Arrays no longer inherit from ArrayBufferView, but are now distinct ([v0.10.0](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.10.0)) +- Classes initialized from object literals can no longer define a constructor ([v0.10.0](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.10.0)) +- The result of a `**` binary operation is now the common denominator integer if both operands are integers. Previously, the result was a float as if calling `Math/f.pow` ([v0.11.0](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.11.0)) +- Coerce `NaN` to `false` when casting to `bool` ([v0.14.9](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.14.9)) +- When shifting a small integer value of type `i8`/`u8` or `i16`/`u16`, only the 3 respectively 4 least significant bits of the RHS value affect the result, analogous to the result of an `i32.shl` only being affected by the 5 least significant bits of the RHS value. Example: `someI8 << 8` previously produced the value `0`, but now produces `someI8` due to masking the RHS as `8 & 7 = 0` (3 bits) ([v0.17.0](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.17.0)) +- Bug fix of relational string comparisons when sizes differ ([v0.17.8](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.17.8)) diff --git a/pages/ar/developer/create-subgraph-hosted.mdx b/pages/ar/developer/create-subgraph-hosted.mdx new file mode 100644 index 000000000000..6b235e379634 --- /dev/null +++ b/pages/ar/developer/create-subgraph-hosted.mdx @@ -0,0 +1,928 @@ +--- +title: Create a Subgraph +--- + +Before being able to use the Graph CLI, you need to create your subgraph in [Subgraph Studio](https://thegraph.com/studio). You will then be able to setup your subgraph project and deploy it to the platform of your choice. Note that **subgraphs that do not index Ethereum mainnet will not be published to The Graph Network**. + +The `graph init` command can be used to set up a new subgraph project, either from an existing contract on any of the public Ethereum networks, or from an example subgraph. This command can be used to create a subgraph on the Subgraph Studio by passing in `graph init --product subgraph-studio`. If you already have a smart contract deployed to Ethereum mainnet or one of the testnets, bootstrapping a new subgraph from that contract can be a good way to get started. But first, a little about the networks The Graph supports. + +## Supported Networks + +The Graph Network supports subgraphs indexing mainnet Ethereum: + +- `mainnet` + +**Additional Networks are supported in beta on the Hosted Service**: + +- `mainnet` +- `kovan` +- `rinkeby` +- `ropsten` +- `goerli` +- `poa-core` +- `poa-sokol` +- `xdai` +- `near-mainnet` +- `near-testnet` +- `matic` +- `mumbai` +- `fantom` +- `bsc` +- `chapel` +- `clover` +- `avalanche` +- `fuji` +- `celo` +- `celo-alfajores` +- `fuse` +- `moonriver` +- `mbase` +- `arbitrum-one` +- `arbitrum-rinkeby` +- `optimism` +- `optimism-kovan` +- `aurora` +- `aurora-testnet` + +The Graph's Hosted Service relies on the stability and reliability of the underlying technologies, namely the provided JSON RPC endpoints. Newer networks will be marked as being in beta until the network has proven itself in terms of stability, reliability, and scalability. During this beta period, there is risk of downtime and unexpected behaviour. + +Remember that you will **not be able** to publish a subgraph that indexes a non-mainnet network to the decentralized Graph Network in [Subgraph Studio](/studio/subgraph-studio). + +## From An Existing Contract + +The following command creates a subgraph that indexes all events of an existing contract. It attempts to fetch the contract ABI from Etherscan and falls back to requesting a local file path. If any of the optional arguments are missing, it takes you through an interactive form. + +```sh +graph init \ + --product subgraph-studio + --from-contract \ + [--network ] \ + [--abi ] \ + [] +``` + +The `` is the ID of your subgraph in Subgraph Studio, it can be found on your subgraph details page. + +## From An Example Subgraph + +The second mode `graph init` supports is creating a new project from an example subgraph. The following command does this: + +``` +graph init --studio +``` + +The example subgraph is based on the Gravity contract by Dani Grant that manages user avatars and emits `NewGravatar` or `UpdateGravatar` events whenever avatars are created or updated. The subgraph handles these events by writing `Gravatar` entities to the Graph Node store and ensuring these are updated according to the events. The following sections will go over the files that make up the subgraph manifest for this example. + +## The Subgraph Manifest + +The subgraph manifest `subgraph.yaml` defines the smart contracts your subgraph indexes, which 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 full specification for subgraph manifests can be found [here](https://github.com/graphprotocol/graph-node/blob/master/docs/subgraph-manifest.md). + +For the example subgraph, `subgraph.yaml` is: + +```yaml +specVersion: 0.0.4 +description: Gravatar for Ethereum +repository: https://github.com/graphprotocol/example-subgraph +schema: + file: ./schema.graphql +dataSources: + - kind: ethereum/contract + name: Gravity + network: mainnet + source: + address: '0x2E645469f354BB4F5c8a05B3b30A929361cf77eC' + abi: Gravity + startBlock: 6175244 + mapping: + kind: ethereum/events + apiVersion: 0.0.6 + language: wasm/assemblyscript + entities: + - Gravatar + abis: + - name: Gravity + file: ./abis/Gravity.json + eventHandlers: + - event: NewGravatar(uint256,address,string,string) + handler: handleNewGravatar + - event: UpdatedGravatar(uint256,address,string,string) + handler: handleUpdatedGravatar + callHandlers: + - function: createGravatar(string,string) + handler: handleCreateGravatar + blockHandlers: + - function: handleBlock + - function: handleBlockWithCall + filter: + kind: call + file: ./src/mapping.ts +``` + +The important entries to update for the manifest are: + +- `description`: a human-readable description of what the subgraph is. This description is displayed by the Graph Explorer when the subgraph is deployed to the Hosted Service. + +- `repository`: the URL of the repository where the subgraph manifest can be found. This is also displayed by the Graph Explorer. + +- `features`: a list of all used [feature](#experimental-features) names. + +- `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.mapping.entities`: the entities that the data source writes to the store. The schema for each entity is defined in the 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 filter can be provided with the following kinds: call`. A`call` filter will 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. + +The triggers for a data source within a block are ordered using the following process: + +1. Event and call triggers are first ordered by transaction index within the block. +2. Event and call triggers with in the same transaction are ordered using a convention: event triggers first then call triggers, each type respecting the order they are defined in the manifest. +3. Block triggers are run after event and call triggers, in the order they are defined in the manifest. + +These ordering rules are subject to change. + +### Getting The ABIs + +The ABI file(s) must match your contract(s). There are a few ways to obtain ABI files: + +- If you are building your own project, you will likely have access to your most current ABIs. +- If you are building a subgraph for a public project, you can download that project to your computer and get the ABI by using [`truffle compile`](https://truffleframework.com/docs/truffle/overview) or using solc to compile. +- You can also find the ABI on [Etherscan](https://etherscan.io/), but this isn't always reliable, as the ABI that is uploaded there may be out of date. Make sure you have the right ABI, otherwise running your subgraph will fail. + +## The GraphQL Schema + +The schema for your subgraph is in the file `schema.graphql`. GraphQL schemas are defined using the GraphQL interface definition language. If you've never written a GraphQL schema, it is recommended that you check out this primer on the GraphQL type system. Reference documentation for GraphQL schemas can be found in the [GraphQL API](/developer/graphql-api) section. + +## Defining Entities + +Before defining entities, it is important to take a step back and think about how your data is structured and linked. All queries will be made against the data model defined in the subgraph schema and the entities indexed by the subgraph. Because of this, it is good to define the subgraph schema in a way that matches the needs of your dapp. It may be useful to imagine entities as "objects containing data", rather than as events or functions. + +With The Graph, you simply define entity types in `schema.graphql`, and Graph Node will generate top level fields for querying single instances and collections of that entity type. Each type that should be an entity is required to be annotated with an `@entity` directive. + +### Good Example + +The `Gravatar` entity below is structured around a Gravatar object and is a good example of how an entity could be defined. + +```graphql +type Gravatar @entity { + id: ID! + owner: Bytes + displayName: String + imageUrl: String + accepted: Boolean +} +``` + +### Bad Example + +The example `GravatarAccepted` and `GravatarDeclined` entities below are based around events. It is not recommended to map events or function calls to entities 1:1. + +```graphql +type GravatarAccepted @entity { + id: ID! + owner: Bytes + displayName: String + imageUrl: String +} + +type GravatarDeclined @entity { + id: ID! + owner: Bytes + displayName: String + imageUrl: String +} +``` + +### Optional and Required Fields + +Entity fields can be defined as required or optional. Required fields are indicated by the `!` in the schema. If a required field is not set in the mapping, you will receive this error when querying the field: + +``` +Null value resolved for non-null field 'name' +``` + +Each entity must have an `id` field, which is of type `ID!` (string). The `id` field serves as the primary key, and needs to be unique among all entities of the same type. + +### Built-In Scalar Types + +#### GraphQL Supported Scalars + +We support the following scalars in our GraphQL API: + +| Type | Description | +| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `Bytes` | Byte array, represented as a hexadecimal string. Commonly used for Ethereum hashes and addresses. | +| `ID` | Stored as a `string`. | +| `String` | Scalar for `string` values. Null characters are not supported and are automatically removed. | +| `Boolean` | Scalar for `boolean` values. | +| `Int` | The GraphQL spec defines `Int` to have size of 32 bytes. | +| `BigInt` | Large integers. Used for Ethereum's `uint32`, `int64`, `uint64`, ..., `uint256` types. Note: Everything below `uint32`, such as `int32`, `uint24` or `int8` is represented as `i32`. | +| `BigDecimal` | `BigDecimal` High precision decimals represented as a signficand and an exponent. The exponent range is from −6143 to +6144. Rounded to 34 significant digits. | + +#### Enums + +You can also create enums within a schema. Enums have the following syntax: + +```graphql +enum TokenStatus { + OriginalOwner + SecondOwner + ThirdOwner +} +``` + +Once the enum is defined in the schema, you can use the string representation of the enum value to set an enum field on an entity. For example, you can set the `tokenStatus` to `SecondOwner` by first defining your entity and subsequently setting the field with `entity.tokenStatus = "SecondOwner`. The example below demonstrates what the Token entity would look like with an enum field: + +More detail on writing enums can be found in the [GraphQL documentation](https://graphql.org/learn/schema/). + +#### Entity Relationships + +An entity may have a relationship to one or more other entities in your schema. These relationships may be traversed in your queries. Relationships in The Graph are unidirectional. It is possible to simulate bidirectional relationships by defining a unidirectional relationship on either "end" of the relationship. + +Relationships are defined on entities just like any other field except that the type specified is that of another entity. + +#### One-To-One Relationships + +Define a `Transaction` entity type with an optional one-to-one relationship with a `TransactionReceipt` entity type: + +```graphql +type Transaction @entity { + id: ID! + transactionReceipt: TransactionReceipt +} + +type TransactionReceipt @entity { + id: ID! + transaction: Transaction +} +``` + +#### One-To-Many Relationships + +Define a `TokenBalance` entity type with a required one-to-many relationship with a Token entity type: + +```graphql +type Token @entity { + id: ID! +} + +type TokenBalance @entity { + id: ID! + amount: Int! + token: Token! +} +``` + +#### Reverse Lookups + +Reverse lookups can be defined on an entity through the `@derivedFrom` field. This creates a virtual field on the entity that may be queried but cannot be set manually through the mappings API. Rather, it is derived from the relationship defined on the other entity. For such relationships, it rarely makes sense to store both sides of the relationship, and both indexing and query performance will be better when only one side is stored and the other is derived. + +For one-to-many relationships, the relationship should always be stored on the 'one' side, and the 'many' side should always be derived. Storing the relationship this way, rather than storing an array of entities on the 'many' side, will result in dramatically better performance for both indexing and querying the subgraph. In general, storing arrays of entities should be avoided as much as is practical. + +#### Example + +We can make the balances for a token accessible from the token by deriving a `tokenBalances` field: + +```graphql +type Token @entity { + id: ID! + tokenBalances: [TokenBalance!]! @derivedFrom(field: "token") +} + +type TokenBalance @entity { + id: ID! + amount: Int! + token: Token! +} +``` + +#### Many-To-Many Relationships + +For many-to-many relationships, such as users that each may belong to any number of organizations, the most straightforward, but generally not the most performant, way to model the relationship is as an array in each of the two entities involved. If the relationship is symmetric, only one side of the relationship needs to be stored and the other side can be derived. + +#### Example + +Define a reverse lookup from a `User` entity type to an `Organization` entity type. In the example below, this is achieved by looking up the `members` attribute from within the `Organization` entity. In queries, the `organizations` field on `User` will be resolved by finding all `Organization` entities that include the user's ID. + +```graphql +type Organization @entity { + id: ID! + name: String! + members: [User!]! +} + +type User @entity { + id: ID! + name: String! + organizations: [Organization!]! @derivedFrom(field: "members") +} +``` + +A more performant way to store this relationship is through a mapping table that has one entry for each `User` / `Organization` pair with a schema like + +```graphql +type Organization @entity { + id: ID! + name: String! + members: [UserOrganization]! @derivedFrom(field: "user") +} + +type User @entity { + id: ID! + name: String! + organizations: [UserOrganization!] @derivedFrom(field: "organization") +} + +type UserOrganization @entity { + id: ID! # Set to `${user.id}-${organization.id}` + user: User! + organization: Organization! +} +``` + +This approach requires that queries descend into one additional level to retrieve, for example, the organizations for users: + +```graphql +query usersWithOrganizations { + users { + organizations { + # this is a UserOrganization entity + organization { + name + } + } + } +} +``` + +This more elaborate way of storing many-to-many relationships will result in less data stored for the subgraph, and therefore to a subgraph that is often dramatically faster to index and to query. + +#### Adding comments to the schema + +As per GraphQL spec, comments can be added above schema entity attributes using double quotations `""`. This is illustrated in the example below: + +```graphql +type MyFirstEntity @entity { + "unique identifier and primary key of the entity" + id: ID! + address: Bytes! +} +``` + +## Defining Fulltext Search Fields + +Fulltext search queries filter and rank entities based on a text search input. Fulltext queries are able to return matches for similar words by processing the query text input into stems before comparing to the indexed text data. + +A fulltext query definition includes the query name, the language dictionary used to process the text fields, the ranking algorithm used to order the results, and the fields included in the search. Each fulltext query may span multiple fields, but all included fields must be from a single entity type. + +To add a fulltext query, include a `_Schema_` type with a fulltext directive in the GraphQL schema. + +```graphql +type _Schema_ + @fulltext( + name: "bandSearch" + language: en + algorithm: rank + include: [{ entity: "Band", fields: [{ name: "name" }, { name: "description" }, { name: "bio" }] }] + ) + +type Band @entity { + id: ID! + name: String! + description: String! + bio: String + wallet: Address + labels: [Label!]! + discography: [Album!]! + members: [Musician!]! +} +``` + +The example `bandSearch` field can be used in queries to filter `Band` entities based on the text documents in the `name`, `description`, and `bio` fields. Jump to [GraphQL API - Queries](/developer/graphql-api#queries) for a description of the Fulltext search API and for more example usage. + +```graphql +query { + bandSearch(text: "breaks & electro & detroit") { + id + name + description + wallet + } +} +``` + +> **[Feature Management](#experimental-features):** From `specVersion` `0.0.4` and onwards, `fullTextSearch` must be declared under the `features` section in the subgraph manifest. + +### Languages supported + +Choosing a different language will have a definitive, though sometimes subtle, effect on the fulltext search API. Fields covered by a fulltext query field are examined in the context of the chosen language, so the lexemes produced by analysis and search queries vary language to language. For example: when using the supported Turkish dictionary "token" is stemmed to "toke" while, of course, the English dictionary will stem it to "token". + +Supported language dictionaries: + +| Code | Dictionary | +| ------ | ---------- | +| simple | General | +| da | Danish | +| nl | Dutch | +| en | English | +| fi | Finnish | +| fr | French | +| de | German | +| hu | Hungarian | +| it | Italian | +| no | Norwegian | +| pt | Portugese | +| ro | Romanian | +| ru | Russian | +| es | Spanish | +| sv | Swedish | +| tr | Turkish | + +### Ranking Algorithms + +Supported algorithms for ordering results: + +| Algorithm | Description | +| ------------- | ----------------------------------------------------------------------- | +| rank | Use the match quality (0-1) of the fulltext query to order the results. | +| proximityRank | Similar to rank but also includes the proximity of the matches. | + +## Writing Mappings + +The mappings transform the Ethereum data your mappings are sourcing into entities defined in your schema. Mappings are written in a subset of [TypeScript](https://www.typescriptlang.org/docs/handbook/typescript-in-5-minutes.html) called [AssemblyScript](https://github.com/AssemblyScript/assemblyscript/wiki) which can be compiled to WASM ([WebAssembly](https://webassembly.org/)). AssemblyScript is stricter than normal TypeScript, yet provides a familiar syntax. + +For each event handler that is defined in `subgraph.yaml` under `mapping.eventHandlers`, create an exported function of the same name. Each handler must accept a single parameter called `event` with a type corresponding to the name of the event which is being handled. + +In the example subgraph, `src/mapping.ts` contains handlers for the `NewGravatar` and `UpdatedGravatar` events: + +```javascript +import { NewGravatar, UpdatedGravatar } from '../generated/Gravity/Gravity' +import { Gravatar } from '../generated/schema' + +export function handleNewGravatar(event: NewGravatar): void { + let gravatar = new Gravatar(event.params.id.toHex()) + gravatar.owner = event.params.owner + gravatar.displayName = event.params.displayName + gravatar.imageUrl = event.params.imageUrl + gravatar.save() +} + +export function handleUpdatedGravatar(event: UpdatedGravatar): void { + let id = event.params.id.toHex() + let gravatar = Gravatar.load(id) + if (gravatar == null) { + gravatar = new Gravatar(id) + } + gravatar.owner = event.params.owner + gravatar.displayName = event.params.displayName + gravatar.imageUrl = event.params.imageUrl + gravatar.save() +} +``` + +The first handler takes a `NewGravatar` event and creates a new `Gravatar` entity with `new Gravatar(event.params.id.toHex())`, populating the entity fields using the corresponding event parameters. This entity instance is represented by the variable `gravatar`, with an id value of `event.params.id.toHex()`. + +The second handler tries to load the existing `Gravatar` from the Graph Node store. If it does not exist yet, it is created on demand. The entity is then updated to match the new event parameters, before it is saved back to the store using `gravatar.save()`. + +### Recommended IDs for Creating New Entities + +Every entity has to have an `id` that is unique among all entities of the same type. An entity's `id` value is set when the entity is created. Below are some recommended `id` values to consider when creating new entities. NOTE: The value of `id` must be a `string`. + +- `event.params.id.toHex()` +- `event.transaction.from.toHex()` +- `event.transaction.hash.toHex() + "-" + event.logIndex.toString()` + +We provide the [Graph Typescript Library](https://github.com/graphprotocol/graph-ts) which contains utilies for interacting with the Graph Node store and conveniences for handling smart contract data and entities. You can use this library in your mappings by importing `@graphprotocol/graph-ts` in `mapping.ts`. + +## Code Generation + +In order to make working smart contracts, events and entities easy and type-safe, the Graph CLI can generate AssemblyScript types from the subgraph's GraphQL schema and the contract ABIs included in the data sources. + +This is done with + +```sh +graph codegen [--output-dir ] [] +``` + +but in most cases, subgraphs are already preconfigured via `package.json` to allow you to simply run one of the following to achieve the same: + +```sh +# Yarn +yarn codegen + +# NPM +npm run codegen +``` + +This will generate an AssemblyScript class for every smart contract in the ABI files mentioned in `subgraph.yaml`, allowing you to bind these contracts to specific addresses in the mappings and call read-only contract methods against the block being processed. It will also generate a class for every contract event to provide easy access to event parameters as well as the block and transaction the event originated from. All of these types are written to `//.ts`. In the example subgraph, this would be `generated/Gravity/Gravity.ts`, allowing mappings to import these types with + +```javascript +import { + // The contract class: + Gravity, + // The events classes: + NewGravatar, + UpdatedGravatar, +} from '../generated/Gravity/Gravity' +``` + +In addition to this, one class is generated for each entity type in the subgraph's GraphQL schema. These classes provide type-safe entity loading, read and write access to entity fields as well as a `save()` method to write entities to store. All entity classes are written to `/schema.ts`, allowing mappings to import them with + +```javascript +import { Gravatar } from '../generated/schema' +``` + +> **Note:** The code generation must be performed again after every change to the GraphQL schema or the ABIs included in the manifest. It must also be performed at least once before building or deploying the subgraph. + +Code generation does not check your mapping code in `src/mapping.ts`. If you want to check that before trying to deploy your subgraph to the Graph Explorer, you can run `yarn build` and fix any syntax errors that the TypeScript compiler might find. + +## Data Source Templates + +A common pattern in Ethereum smart contracts is the use of registry or factory contracts, where one contract creates, manages or references an arbitrary number of other contracts that each have their own state and events. 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_. + +### Data Source for the Main Contract + +First, you define a regular data source for the main contract. The snippet below shows a simplified example data source for the [Uniswap](https://uniswap.io) exchange factory contract. Note the `NewExchange(address,address)` event handler. This is emitted when a new exchange contract is created on chain by the factory contract. + +```yaml +dataSources: + - kind: ethereum/contract + name: Factory + network: mainnet + source: + address: '0xc0a47dFe034B400B47bDaD5FecDa2621de6c4d95' + abi: Factory + mapping: + kind: ethereum/events + apiVersion: 0.0.6 + language: wasm/assemblyscript + file: ./src/mappings/factory.ts + entities: + - Directory + abis: + - name: Factory + file: ./abis/factory.json + eventHandlers: + - event: NewExchange(address,address) + handler: handleNewExchange +``` + +### Data Source Templates for Dynamically Created Contracts + +Then, you add _data source templates_ to the manifest. These are identical to regular data sources, except that they lack a predefined contract address under `source`. Typically, you would define one template for each type of sub-contract managed or referenced by the parent contract. + +```yaml +dataSources: + - kind: ethereum/contract + name: Factory + # ... other source fields for the main contract ... +templates: + - name: Exchange + kind: ethereum/contract + network: mainnet + source: + abi: Exchange + mapping: + kind: ethereum/events + apiVersion: 0.0.6 + language: wasm/assemblyscript + file: ./src/mappings/exchange.ts + entities: + - Exchange + abis: + - name: Exchange + file: ./abis/exchange.json + eventHandlers: + - event: TokenPurchase(address,uint256,uint256) + handler: handleTokenPurchase + - event: EthPurchase(address,uint256,uint256) + handler: handleEthPurchase + - event: AddLiquidity(address,uint256,uint256) + handler: handleAddLiquidity + - event: RemoveLiquidity(address,uint256,uint256) + handler: handleRemoveLiquidity +``` + +### Instantiating a Data Source Template + +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. + +```typescript +import { Exchange } from '../generated/templates' + +export function handleNewExchange(event: NewExchange): void { + // Start indexing the exchange; `event.params.exchange` is the + // address of the new exchange contract + Exchange.create(event.params.exchange) +} +``` + +> **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. +> +> If prior blocks contain data relevant to the new data source, it is best to index that data by reading the current state of the contract and creating entities representing that state at the time the new data source is created. + +### Data Source Context + +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: + +```typescript +import { Exchange } from '../generated/templates' + +export function handleNewExchange(event: NewExchange): void { + let context = new DataSourceContext() + context.setString('tradingPair', event.params.tradingPair) + Exchange.createWithContext(event.params.exchange, context) +} +``` + +Inside a mapping of the `Exchange` template, the context can then be accessed: + +```typescript +import { dataSource } from '@graphprotocol/graph-ts' + +let context = dataSource.context() +let tradingPair = context.getString('tradingPair') +``` + +There are setters and getters like `setString` and `getString` for all value types. + +## Start Blocks + +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. + +```yaml +dataSources: + - kind: ethereum/contract + name: ExampleSource + network: mainnet + source: + address: '0xc0a47dFe034B400B47bDaD5FecDa2621de6c4d95' + abi: ExampleContract + startBlock: 6627917 + mapping: + kind: ethereum/events + apiVersion: 0.0.6 + language: wasm/assemblyscript + file: ./src/mappings/factory.ts + entities: + - User + abis: + - name: ExampleContract + file: ./abis/ExampleContract.json + eventHandlers: + - event: NewEvent(address,address) + handler: handleNewEvent +``` + +> **Note:** The contract creation block can be quickly looked up on Etherscan: +> +> 1. Search for the contract by entering its address in the search bar. +> 2. Click on the creation transaction hash in the `Contract Creator` section. +> 3. Load the transaction details page where you'll find the start block for that contract. + +## Call Handlers + +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. + +Call handlers will only trigger in one of two cases: when the function specified is called by an account other than the contract itself or when it is marked as external in Solidity and called as part of another function in the same contract. + +> **Note:** Call handlers are not supported on Rinkeby, Goerli or Ganache. Call handlers currently depend on the Parity tracing API and these networks do not support it. + +### Defining a Call Handler + +To define a call handler in your manifest simply add a `callHandlers` array under the data source you would like to subscribe to. + +```yaml +dataSources: + - kind: ethereum/contract + name: Gravity + network: mainnet + source: + address: '0x731a10897d267e19b34503ad902d0a29173ba4b1' + abi: Gravity + mapping: + kind: ethereum/events + apiVersion: 0.0.6 + language: wasm/assemblyscript + entities: + - Gravatar + - Transaction + abis: + - name: Gravity + file: ./abis/Gravity.json + callHandlers: + - function: createGravatar(string,string) + 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. + +### Mapping Function + +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: + +```typescript +import { CreateGravatarCall } from '../generated/Gravity/Gravity' +import { Transaction } from '../generated/schema' + +export function handleCreateGravatar(call: CreateGravatarCall): void { + let id = call.transaction.hash.toHex() + let transaction = new Transaction(id) + transaction.displayName = call.inputs._displayName + transaction.imageUrl = call.inputs._imageUrl + transaction.save() +} +``` + +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`. + +## Block Handlers + +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 predefined filter. + +### Supported Filters + +```yaml +filter: + 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._ + +The absense of a filter for a block handler will ensure that the handler is called every block. A data source can only contain one block handler for each filter type. + +```yaml +dataSources: + - kind: ethereum/contract + name: Gravity + network: dev + source: + address: '0x731a10897d267e19b34503ad902d0a29173ba4b1' + abi: Gravity + mapping: + kind: ethereum/events + apiVersion: 0.0.6 + language: wasm/assemblyscript + entities: + - Gravatar + - Transaction + abis: + - name: Gravity + file: ./abis/Gravity.json + blockHandlers: + - handler: handleBlock + - handler: handleBlockWithCallToContract + filter: + kind: call +``` + +### Mapping Function + +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. + +```typescript +import { ethereum } from '@graphprotocol/graph-ts' + +export function handleBlock(block: ethereum.Block): void { + let id = block.hash.toHex() + let entity = new Block(id) + entity.save() +} +``` + +## Anonymous Events + +If you need to process anonymous events in Solidity, that can be achieved by providing the topic 0 of the event, as in the example: + +```yaml +eventHandlers: + - event: LogNote(bytes4,address,bytes32,bytes32,uint256,bytes) + topic0: '0xbaa8529c00000000000000000000000000000000000000000000000000000000' + 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. + +## Experimental features + +Starting from `specVersion` `0.0.4`, subgraph features must be explicitly declared in the `features` section at the top level of the manifest file, using their `camelCase` name, as listed in the table below: + +| Feature | Name | +| --------------------------------------------------------- | ------------------------- | +| [Non-fatal errors](#non-fatal-errors) | `nonFatalErrors` | +| [Full-text Search](#defining-fulltext-search-fields) | `fullTextSearch` | +| [Grafting](#grafting-onto-existing-subgraphs) | `grafting` | +| [IPFS on Ethereum Contracts](#ipfs-on-ethereum-contracts) | `ipfsOnEthereumContracts` | + +For instance, if a subgraph uses the **Full-Text Search** and the **Non-fatal Errors** features, the `features` field in the manifest should be: + +```yaml +specVersion: 0.0.4 +description: Gravatar for Ethereum +features: + - fullTextSearch + - nonFatalErrors +dataSources: ... +``` + +Note that using a feature without declaring it will incur in a **validation error** during subgraph deployment, but no errors will occur if a feature is declared but not used. + +### IPFS on Ethereum Contracts + +A common use case for combining IPFS with Ethereum is to store data on IPFS that would be too expensive to maintain on chain, and reference the IPFS hash in Ethereum contracts. + +Given such IPFS hashes, subgraphs can read the corresponding files from IPFS using `ipfs.cat` and `ipfs.map`. To do this reliably, however, it is required that these files are pinned on the IPFS node that the Graph Node indexing the subgraph connects to. In the case of the [hosted service](https://thegraph.com/hosted-service), this is [https://api.thegraph.com/ipfs/](https://api.thegraph.com/ipfs/). + +> **Note:** The Graph Network does not yet support `ipfs.cat` and `ipfs.map`, and developers should not deploy subgraphs using that functionality to the network via the Studio. + +In order to make this easy for subgraph developers, The Graph team wrote a tool for transfering files from one IPFS node to another, called [ipfs-sync](https://github.com/graphprotocol/ipfs-sync). + +> **[Feature Management](#experimental-features):** `ipfsOnEthereumContracts` must be declared under `features` in the subgraph manifest. + +### Non-fatal errors + +Indexing errors on already synced subgraphs will, by default, cause the subgraph to fail and stop syncing. Subgraphs can alternatively be configured to continue syncing in the presence of errors, by ignoring the changes made by the handler which provoked the error. This gives subgraph authors time to correct their subgraphs while queries continue to be served against the latest block, though the results will possibly be inconsistent due to the bug that caused the error. Note that some errors are still always fatal, to be non-fatal the error must be known to be deterministic. + +> **Note:** The Graph Network does not yet support non-fatal errors, and developers should not deploy subgraphs using that functionality to the network via the Studio. + +Enabling non-fatal errors requires setting the following feature flag on the subgraph manifest: + +```yaml +specVersion: 0.0.4 +description: Gravatar for Ethereum +features: + - fullTextSearch + ... +``` + +The query must also opt-in to querying data with potential inconsistencies through the `subgraphError` argument. It is also recommended to query `_meta` to check if the subgraph has skipped over errors, as in the example: + +```graphql +foos(first: 100, subgraphError: allow) { + id +} + +_meta { + hasIndexingErrors +} +``` + +If the subgraph encounters an error that query will return both the data and a graphql error with the message `"indexing_error"`, as in this example response: + +```graphql +"data": { + "foos": [ + { + "id": "fooId" + } + ], + "_meta": { + "hasIndexingErrors": true + } +}, +"errors": [ + { + "message": "indexing_error" + } +] +``` + +### Grafting onto Existing Subgraphs + +When a subgraph is first deployed, it starts indexing events at the genesis block of the corresponding chain (or at the `startBlock` defined with each data source) In some circumstances, it is beneficial to reuse the data from an existing subgraph and start indexing at a much later block. This mode of indexing is called _Grafting_. Grafting is, for example, useful during development to get past simple errors in the mappings quickly, or to temporarily get an existing subgraph working again after it has failed. + +> **Note:** Grafting requires that the Indexer has indexed the base subgraph. It is not recommended on The Graph Network at this time, and developers should not deploy subgraphs using that functionality to the network via the Studio. + +A subgraph is grafted onto a base subgraph when the subgraph manifest in `subgraph.yaml` contains a `graft` block at the toplevel: + +```yaml +description: ... +graft: + base: Qm... # Subgraph ID of base subgraph + block: 7345624 # Block number +``` + +When a subgraph whose manifest contains a `graft` block is deployed, Graph Node will copy the data of the `base` subgraph up to and including the given `block` and then continue indexing the new subgraph from that block on. The base subgraph must exist on the target Graph Node instance and must have indexed up to at least the given block. Because of this restriction, grafting should only be used during development or during an emergency to speed up producing an equivalent non-grafted subgraph. + +Because grafting copies rather than indexes base data it is much quicker in getting the subgraph to the desired block than indexing from scratch, though the initial data copy can still take several hours for very large subgraphs. While the grafted subgraph is being initialized, the Graph Node will log information about the entity types that have already been copied. + +The grafted subgraph can use a GraphQL schema that is not identical to the one of the base subgraph, but merely compatible with it. It has to be a valid subgraph schema in its own right but may deviate from the base subgraph's schema in the following ways: + +- It adds or removes entity types +- It removes attributes from entity types +- It adds nullable attributes to entity types +- It turns non-nullable attributes into nullable attributes +- It adds values to enums +- It adds or removes interfaces +- It changes for which entity types an interface is implemented + +> **[Feature Management](#experimental-features):** `grafting` must be declared under `features` in the subgraph manifest. diff --git a/pages/ar/developer/define-subgraph-hosted.mdx b/pages/ar/developer/define-subgraph-hosted.mdx new file mode 100644 index 000000000000..92bf5bd8cd2f --- /dev/null +++ b/pages/ar/developer/define-subgraph-hosted.mdx @@ -0,0 +1,35 @@ +--- +title: Define a Subgraph +--- + +A subgraph defines which data The Graph will index from Ethereum, and how it will store it. Once deployed, it will form a part of a global graph of blockchain data. + +![Define a Subgraph](/img/define-subgraph.png) + +The subgraph definition consists of a few files: + +- `subgraph.yaml`: a YAML file containing the subgraph manifest + +- `schema.graphql`: a GraphQL schema that defines what data is stored for your subgraph, and how to query it via GraphQL + +- `AssemblyScript Mappings`: [AssemblyScript](https://github.com/AssemblyScript/assemblyscript) code that translates from the event data to the entities defined in your schema (e.g. `mapping.ts` in this tutorial) + +Before you go into detail about the contents of the manifest file, you need to install the [Graph CLI](https://github.com/graphprotocol/graph-cli) which you will need to build and deploy a subgraph. + +## Install the Graph CLI + +The Graph CLI is written in JavaScript, and you will need to install either `yarn` or `npm` to use it; it is assumed that you have yarn in what follows. + +Once you have `yarn`, install the Graph CLI by running + +**Install with yarn:** + +```bash +yarn global add @graphprotocol/graph-cli +``` + +**Install with npm:** + +```bash +npm install -g @graphprotocol/graph-cli +``` diff --git a/pages/ar/developer/deprecating-a-subgraph.mdx b/pages/ar/developer/deprecating-a-subgraph.mdx new file mode 100644 index 000000000000..f8966e025c13 --- /dev/null +++ b/pages/ar/developer/deprecating-a-subgraph.mdx @@ -0,0 +1,17 @@ +--- +title: Deprecating a Subgraph +--- + +So you'd like to deprecate your subgraph on The Graph Explorer. You've come to the right place! Follow the steps below: + +1. Visit the contract address [here](https://etherscan.io/address/0xadca0dd4729c8ba3acf3e99f3a9f471ef37b6825#writeProxyContract) +2. Call 'deprecateSubgraph' with your own address as the first parameter +3. In the 'subgraphNumber' field, list 0 if it's the first subgraph you're publishing, 1 if it's your second, 2 if it's your third, etc. +4. Inputs for #2 and #3 can be found in your `` which is composed of the `{graphAccount}-{subgraphNumber}`. For example, the [Sushi Subgraph's](https://thegraph.com/explorer/subgraph?id=0x4bb4c1b0745ef7b4642feeccd0740dec417ca0a0-0&version=0x4bb4c1b0745ef7b4642feeccd0740dec417ca0a0-0-0&view=Overview) ID is `<0x4bb4c1b0745ef7b4642feeccd0740dec417ca0a0-0>`, which is a combination of `graphAccount` = `<0x4bb4c1b0745ef7b4642feeccd0740dec417ca0a0>` and `subgraphNumber` = `<0>` +5. Voila! Your subgraph will no longer show up on searches on The Graph Explorer. Please note the following: + +- Curators will not be able to signal on the subgraph anymore +- Curators that already signaled on the subgraph will be able to withdraw their signal at an average share price +- Deprecated subgraphs will be indicated with an error message. + +If you interacted with the now deprecated subgraph, you'll be able to find it in your user profile under the "Subgraphs", "Indexing", or "Curating" tab respectively. diff --git a/pages/ar/developer/developer-faq.mdx b/pages/ar/developer/developer-faq.mdx new file mode 100644 index 000000000000..41449c60e5ab --- /dev/null +++ b/pages/ar/developer/developer-faq.mdx @@ -0,0 +1,172 @@ +--- +title: Developer FAQs +--- + +### 1. Can I delete my subgraph? + +It is not possible to delete subgraphs once they are created. + +### 2. Can I change my subgraph name? + +No. Once a subgraph is created, the name cannot be changed. Make sure to think of this carefully before you create your subgraph so it is easily searchable and identifiable by other dapps. + +### 3. Can I change the GitHub account associated with my subgraph? + +No. Once a subgraph is created, the associated GitHub account cannot be changed. Make sure to think of this carefully before you create your subgraph. + +### 4. Am I still able to create a subgraph if my smart contracts don't have events? + +It is highly recommended that you structure your smart contracts to have events associated with data you are interested in querying. Event handlers in the subgraph are triggered by contract events, and are by far the fastest way to retrieve useful data. + +If the contracts you are working with do not contain events, your subgraph can use call and block handlers to trigger indexing. Although this is not recommended as performance will be significantly slower. + +### 5. Is it possible to deploy one subgraph with the same name for multiple networks? + +You will need separate names for multiple networks. While you can't have different subgraphs under the same name, there are convenient ways of having a single codebase for multiple networks. Find more on this in our documentation: [Redeploying a Subgraph](/hosted-service/deploy-subgraph-hosted#redeploying-a-subgraph) + +### 6. How are templates different from data sources? + +Templates allow you to create data sources on the fly, while your subgraph is indexing. It might be the case that your contract will spawn new contracts as people interact with it, and since you know the shape of those contracts (ABI, events, etc) up front you can define how you want to index them in a template and when they are spawned your subgraph will create a dynamic data source by supplying the contract address. + +Check out the "Instantiating a data source template" section on: [Data Source Templates](/developer/create-subgraph-hosted#data-source-templates). + +### 7. How do I make sure I'm using the latest version of graph-node for my local deployments? + +You can run the following command: + +```sh +docker pull graphprotocol/graph-node:latest +``` + +**NOTE:** docker / docker-compose will always use whatever graph-node version was pulled the first time you ran it, so it is important to do this to make sure you are up to date with the latest version of graph-node. + +### 8. How do I call a contract function or access a public state variable from my subgraph mappings? + +Take a look at `Access to smart contract` state inside the section [AssemblyScript API](/developer/assemblyscript-api). + +### 9. Is it possible to set up a subgraph using `graph init` from `graph-cli` with two contracts? Or should I manually add another datasource in `subgraph.yaml` after running `graph init`? + +Unfortunately this is currently not possible. `graph init` is intended as a basic starting point, from which you can then add more data sources manually. + +### 10. I want to contribute or add a GitHub issue, where can I find the open source repositories? + +- [graph-node](https://github.com/graphprotocol/graph-node) +- [graph-cli](https://github.com/graphprotocol/graph-cli) +- [graph-ts](https://github.com/graphprotocol/graph-ts) + +### 11. What is the recommended way to build "autogenerated" ids for an entity when handling events? + +If only one entity is created during the event and if there's nothing better available, then the transaction hash + log index would be unique. You can obfuscate these by converting that to Bytes and then piping it through `crypto.keccak256` but this won't make it more unique. + +### 12. When listening to multiple contracts, is it possible to select the contract order to listen to events? + +Within a subgraph, the events are always processed in the order they appear in the blocks, regardless of whether that is across multiple contracts or not. + +### 13. Is it possible to differentiate between networks (mainnet, Kovan, Ropsten, local) from within event handlers? + +Yes. You can do this by importing `graph-ts` as per the example below: + +```javascript +import { dataSource } from '@graphprotocol/graph-ts' + +dataSource.network() +dataSource.address() +``` + +### 14. Do you support block and call handlers on Rinkeby? + +On Rinkeby we support block handlers, but without `filter: call`. Call handlers are not supported for the time being. + +### 15. Can I import ethers.js or other JS libraries into my subgraph mappings? + +Not currently, as mappings are written in AssemblyScript. One possible alternative solution to this is to store raw data in entities and perform logic that requires JS libraries on the client. + +### 16. Is it possible to specifying what block to start indexing on? + +Yes. `dataSources.source.startBlock` in the `subgraph.yaml` file specifies the 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: Start blocks + +### 17. Are there some tips to increase performance of indexing? My subgraph is taking a very long time to sync. + +Yes, you should take a look at the optional start block feature to start indexing from the block that the contract was deployed: [Start blocks](/developer/create-subgraph-hosted#start-blocks) + +### 18. Is there a way to query the subgraph directly to determine what the latest block number it has indexed? + +Yes! Try the following command, substituting "organization/subgraphName" with the organization under it is published and the name of your subgraph: + +```sh +curl -X POST -d '{ "query": "{indexingStatusForCurrentVersion(subgraphName: \"organization/subgraphName\") { chains { latestBlock { hash number }}}}"}' https://api.thegraph.com/index-node/graphql +``` + +### 19. What networks are supported by The Graph? + +The graph-node supports any EVM-compatible JSON RPC API chain. + +The Graph Network supports subgraphs indexing mainnet Ethereum: + +- `mainnet` + +In the Hosted Service, the following networks are supported: + +- Ethereum mainnet +- Kovan +- Rinkeby +- Ropsten +- Goerli +- PoA-Core +- PoA-Sokol +- xDAI +- NEAR +- NEAR testnet +- Matic +- Mumbai +- Fantom +- Binance Smart Chain +- Clover +- Avalanche +- Fuji +- Celo +- Celo-Alfajores +- Fuse +- Moonbeam +- Arbitrum One +- Arbitrum Testnet (on Rinkeby) +- Optimism +- Optimism Testnet (on Kovan) + +There is work in progress towards integrating other blockchains, you can read more in our repo: [RFC-0003: Multi-Blockchain Support](https://github.com/graphprotocol/rfcs/pull/8/files). + +### 20. Is it possible to duplicate a subgraph to another account or endpoint without redeploying? + +You have to redeploy the subgraph, but if the subgraph ID (IPFS hash) doesn't change, it won't have to sync from the beginning. + +### 21. Is this possible to use Apollo Federation on top of graph-node? + +Federation is not supported yet, although we do want to support it in the future. At the moment, something you can do is use schema stitching, either on the client or via a proxy service. + +### 22. Is there a limit to how many objects The Graph can return per query? + +By default query responses are limited to 100 items per collection. If you want to receive more, you can go up to 1000 items per collection and beyond that you can paginate with: + +```graphql +someCollection(first: 1000, skip: ) { ... } +``` + +### 23. If my dapp frontend uses The Graph for querying, do I need to write my query key into the frontend directly? What if we pay query fees for users – will malicious users cause our query fees to be very high? + +Currently, the recommended approach for a dapp is to add the key to the frontend and expose it to end users. That said, you can limit that key to a host name, like _yourdapp.io_ and subgraph. The gateway is currently being run by Edge & Node. Part of the responsibility of a gateway is to monitor for abusive behavior and block traffic from malicious clients. + +### 24. Where do I go to find my current subgraph on the Hosted Service? + +Head over to the Hosted Service in order to find subgraphs that you or others deployed to the Hosted Service. You can find it [here.](https://thegraph.com/hosted-service) + +### 25. Will the Hosted Service start charging query fees? + +The Graph will never charge for the Hosted Service. The Graph is a decentralized protocol, and charging for a centralized service is not aligned with The Graph’s values. The Hosted Service was always a temporary step to help get to the decentralized network. Developers will have a sufficient amount of time to migrate to the decentralized network as they are comfortable. + +### 26. When will the Hosted Service be shut down? + +If and when there are plans to do this, the community will be notified well ahead of time with considerations made for any subgraphs built on the Hosted Service. + +### 27. How do I upgrade a subgraph on mainnet? + +If you’re a subgraph developer, you can upgrade a new version of your subgraph to the Studio using the CLI. It’ll be private at that point but if you’re happy with it, you can publish to the decentralized Graph Explorer. This will create a new version of your subgraph that Curators can start signaling on. diff --git a/pages/ar/developer/distributed-systems.mdx b/pages/ar/developer/distributed-systems.mdx new file mode 100644 index 000000000000..894fcbe2e18b --- /dev/null +++ b/pages/ar/developer/distributed-systems.mdx @@ -0,0 +1,132 @@ +--- +title: Distributed Systems +--- + +The Graph is a protocol implemented as a distributed system. + +Connections fail. Requests arrive out of order. Different computers with out-of-sync clocks and states process related requests. Servers restart. Re-orgs happen between requests. These problems are inherent to all distributed systems but are exacerbated in systems operating at a global scale. + +Consider this example of what may occur if a client polls an Indexer for the latest data during a re-org. + +1. Indexer ingests block 8 +2. Request served to the client for block 8 +3. Indexer ingests block 9 +4. Indexer ingests block 10A +5. Request served to the client for block 10A +6. Indexer detects reorg to 10B and rolls back 10A +7. Request served to the client for block 9 +8. Indexer ingests block 10B +9. Indexer ingests block 11 +10. Request served to the client for block 11 + +From the point of view of the Indexer, things are progressing forward logically. Time is moving forward, though we did have to roll back an uncle block and play the block under consensus forward on top of it. Along the way, the Indexer serves requests using the latest state it knows about at that time. + +From the point of view of the client, however, things appear chaotic. The client observes that the responses were for blocks 8, 10, 9, and 11 in that order. We call this the "block wobble" problem. When a client experiences block wobble, data may appear to contradict itself over time. The situation worsens when we consider that Indexers do not all ingest the latest blocks simultaneously, and your requests may be routed to multiple Indexers. + +It is the responsibility of the client and server to work together to provide consistent data to the user. Different approaches must be used depending on the desired consistency as there is no one right program for every problem. + +Reasoning through the implications of distributed systems is hard, but the fix may not be! We've established APIs and patterns to help you navigate some common use-cases. The following examples illustrate those patterns but still elide details required by production code (like error handling and cancellation) to not obfuscate the main ideas. + +## Polling for updated data + +The Graph provides the `block: { number_gte: $minBlock }` API, which ensures that the response is for a single block equal or higher to `$minBlock`. If the request is made to a `graph-node` instance and the min block is not yet synced, `graph-node` will return an error. If `graph-node` has synced min block, it will run the response for the latest block. If the request is made to an Edge & Node Gateway, the Gateway will filter out any Indexers that have not yet synced min block and make the request for the latest block the Indexer has synced. + +We can use `number_gte` to ensure that time never travels backward when polling for data in a loop. Here is an example: + +```javascript +/// Updates the protocol.paused variable to the latest +/// known value in a loop by fetching it using The Graph. +async function updateProtocolPaused() { + // It's ok to start with minBlock at 0. The query will be served + // using the latest block available. Setting minBlock to 0 is the + // same as leaving out that argument. + let minBlock = 0 + + for (;;) { + // Schedule a promise that will be ready once + // the next Ethereum block will likely be available. + const nextBlock = new Promise((f) => { + setTimeout(f, 14000) + }) + + const query = ` + { + protocol(block: { number_gte: ${minBlock} } id: "0") { + paused + } + _meta { + block { + number + } + } + }` + + const response = await graphql(query) + minBlock = response._meta.block.number + + // TODO: Do something with the response data here instead of logging it. + console.log(response.protocol.paused) + + // Sleep to wait for the next block + await nextBlock + } +} +``` + +## Fetching a set of related items + +Another use-case is retrieving a large set or, more generally, retrieving related items across multiple requests. Unlike the polling case (where the desired consistency was to move forward in time), the desired consistency is for a single point in time. + +Here we will use the `block: { hash: $blockHash }` argument to pin all of our results to the same block. + +```javascript +/// Gets a list of domain names from a single block using pagination +async function getDomainNames() { + // Set a cap on the maximum number of items to pull. + let pages = 5 + const perPage = 1000 + + // The first query will get the first page of results and also get the block + // hash so that the remainder of the queries are consistent with the first. + let query = ` + { + domains(first: ${perPage}) { + name + id + } + _meta { + block { + hash + } + } + }` + + let data = await graphql(query) + let result = data.domains.map((d) => d.name) + let blockHash = data._meta.block.hash + + // Continue fetching additional pages until either we run into the limit of + // 5 pages total (specified above) or we know we have reached the last page + // because the page has fewer entities than a full page. + while (data.domains.length == perPage && --pages) { + let lastID = data.domains[data.domains.length - 1].id + query = ` + { + domains(first: ${perPage}, where: { id_gt: "${lastID}" }, block: { hash: "${blockHash}" }) { + name + id + } + }` + + data = await graphql(query) + + // Accumulate domain names into the result + for (domain of data.domains) { + result.push(domain.name) + } + } + return result +} +``` + +Note that in case of a re-org, the client will need to retry from the first request to update the block hash to a non-uncle block. diff --git a/pages/ar/developer/graphql-api.mdx b/pages/ar/developer/graphql-api.mdx new file mode 100644 index 000000000000..f9cb6214fcd9 --- /dev/null +++ b/pages/ar/developer/graphql-api.mdx @@ -0,0 +1,267 @@ +--- +title: GraphQL API +--- + +This guide explains the GraphQL Query API that is used for the Graph Protocol. + +## Queries + +In your subgraph schema you define types called `Entities`. For each `Entity` type, an `entity` and `entities` field will be generated on the top-level `Query` type. Note that `query` does not need to be included at the top of the `graphql` query when using The Graph. + +#### Examples + +Query for a single `Token` entity defined in your schema: + +```graphql +{ + token(id: "1") { + id + owner + } +} +``` + +**Note:** When querying for a single entity, the `id` field is required and it must be a string. + +Query all `Token` entities: + +```graphql +{ + tokens { + id + owner + } +} +``` + +### Sorting + +When querying a collection, the `orderBy` parameter may be used to sort by a specific attribute. Additionally, the `orderDirection` can be used to specify the sort direction, `asc` for ascending or `desc` for descending. + +#### Example + +```graphql +{ + tokens(orderBy: price, orderDirection: asc) { + id + owner + } +} +``` + +### Pagination + +When querying a collection, the `first` parameter can be used to paginate from the beginning of the collection. It is worth noting that the default sort order is by ID in ascending alphanumeric order, not by creation time. + +Further, the `skip` parameter can be used to skip entities and paginate. e.g. `first:100` shows the first 100 entities and `first:100, skip:100` shows the next 100 entities. + +Queries should avoid using very large `skip` values since they generally perform poorly. For retrieving a large number of items, it is much better to page through entities based on an attribute as shown in the last example. + +#### Example + +Query the first 10 tokens: + +```graphql +{ + tokens(first: 10) { + id + owner + } +} +``` + +To query for groups of entities in the middle of a collection, the `skip` parameter may be used in conjunction with the `first` parameter to skip a specified number of entities starting at the beginning of the collection. + +#### Example + +Query 10 `Token` entities, offset by 10 places from the beginning of the collection: + +```graphql +{ + tokens(first: 10, skip: 10) { + id + owner + } +} +``` + +#### Example + +If a client needs to retrieve a large number of entities, it is much more performant to base queries on an attribute and filter by that attribute. For example, a client would retrieve a large number of tokens using this query: + +```graphql +{ + query manyTokens($lastID: String) { + tokens(first: 1000, where: { id_gt: $lastID }) { + id + owner + } + } +} +``` + +The first time, it would send the query with `lastID = ""`, and for subsequent requests would set `lastID` to the `id` attribute of the last entity in the previous request. This approach will perform significantly better than using increasing `skip` values. + +### Filtering + +You can use the `where` parameter in your queries to filter for different properties. You can filter on mulltiple values within the `where` parameter. + +#### Example + +Query challenges with `failed` outcome: + +```graphql +{ + challenges(where: { outcome: "failed" }) { + challenger + outcome + application { + id + } + } +} +``` + +You can use suffixes like `_gt`, `_lte` for value comparison: + +#### Example + +```graphql +{ + applications(where: { deposit_gt: "10000000000" }) { + id + whitelisted + deposit + } +} +``` + +Full list of parameter suffixes: + +```graphql +_not +_gt +_lt +_gte +_lte +_in +_not_in +_contains +_not_contains +_starts_with +_ends_with +_not_starts_with +_not_ends_with +``` + +Please note that some suffixes are only supported for specific types. For example, `Boolean` only supports `_not`, `_in`, and `_not_in`. + +### Time-travel queries + +You can query the state of your entities not just for the latest block, which is the by default, but also for an arbitrary block in the past. The block at which a query should happen can be specified either by its block number or its block hash by including a `block` argument in the toplevel fields of queries. + +The result of such a query will not change over time, i.e., querying at a certain past block will return the same result no matter when it is executed, with the exception that if you query at a block very close to the head of the Ethereum chain, the result might change if that block turns out to not be on the main chain and the chain gets reorganized. Once a block can be considered final, the result of the query will not change. + +Note that the current implementation is still subject to certain limitations that might violate these gurantees. The implementation can not always tell that a given block hash is not on the main chain at all, or that the result of a query by block hash for a block that can not be considered final yet might be influenced by a block reorganization running concurrently with the query. They do not affect the results of queries by block hash when the block is final and known to be on the main chain. [This issue](https://github.com/graphprotocol/graph-node/issues/1405) explains what these limitations are in detail. + +#### Example + +```graphql +{ + challenges(block: { number: 8000000 }) { + challenger + outcome + application { + id + } + } +} +``` + +This query will return `Challenge` entities, and their associated `Application` entities, as they existed directly after processing block number 8,000,000. + +#### Example + +```graphql +{ + challenges(block: { hash: "0x5a0b54d5dc17e0aadc383d2db43b0a0d3e029c4c" }) { + challenger + outcome + application { + id + } + } +} +``` + +This query will return `Challenge` entities, and their associated `Application` entities, as they existed directly after processing the block with the given hash. + +### Fulltext Search Queries + +Fulltext search query fields provide an expressive text search API that can be added to the subgraph schema and customized. Refer to [Defining Fulltext Search Fields](/developer/create-subgraph-hosted#defining-fulltext-search-fields) to add fulltext search to your subgraph. + +Fulltext search queries have one required field, `text`, for supplying search terms. Several special fulltext operators are available to be used in this `text` search field. + +Fulltext search operators: + +| Symbol | Operator | Description | +| ----------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------ | +| `&` | `And` | For combining multiple search terms into a filter for entities that include all of the provided terms | +| | | `Or` | Queries with multiple search terms separated by the or operator will return all entities with a match from any of the provided terms | +| `<->` | `Follow by` | Specify the distance between two words. | +| `:*` | `Prefix` | Use the prefix search term to find words whose prefix match (2 characters required.) | + +#### Examples + +Using the `or` operator, this query will filter to blog entities with variations of either "anarchism" or "crumpet" in their fulltext fields. + +```graphql +{ + blogSearch(text: "anarchism | crumpets") { + id + title + body + author + } +} +``` + +The `follow by` operator specifies a words a specific distance apart in the fulltext documents. The following query will return all blogs with variations of "decentralize" followed by "philosophy" + +```graphql +{ + blogSearch(text: "decentralized <-> philosophy") { + id + title + body + author + } +} +``` + +Combine fulltext operators to make more complex filters. With a pretext search operator combined with a follow by this example query will match all blog entities with words that start with "lou" followed by "music". + +```graphql +{ + blogSearch(text: "lou:* <-> music") { + id + title + body + author + } +} +``` + +## Schema + +The schema of your data source--that is, the entity types, values, and relationships that are available to query--are defined through the [GraphQL Interface Definition Langauge (IDL)](https://facebook.github.io/graphql/draft/#sec-Type-System). + +GraphQL schemas generally define root types for `queries`, `subscriptions` and `mutations`. The Graph only supports `queries`. The root `Query` type for your subgraph is automatically generated from the GraphQL schema that's included in your subgraph manifest. + +> **Note:** Our API does not expose mutations because developers are expected to issue transactions directly against the underlying blockchain from their applications. + +### Entities + +All GraphQL types with `@entity` directives in your schema will be treated as entities and must have an `ID` field. + +> **Note:** Currently, all types in your schema must have an `@entity` directive. In the future, we will treat types without an `@entity` directive as value objects, but this is not yet supported. diff --git a/pages/ar/developer/matchstick.mdx b/pages/ar/developer/matchstick.mdx new file mode 100644 index 000000000000..3cf1ec761bb9 --- /dev/null +++ b/pages/ar/developer/matchstick.mdx @@ -0,0 +1,267 @@ +--- +title: Unit Testing Framework +--- + +Matchstick is a unit testing framework, developed by [LimeChain](https://limechain.tech/), that enables subgraph developers to test their mapping logic in a sandboxed environment and deploy their subgraphs with confidence! + +Follow the [Matchstick installation guide](https://github.com/LimeChain/matchstick/blob/main/README.md#quick-start-) to install. Now, you can move on to writing your first unit test. + +## Write a Unit Test + +Let's see how a simple unit test would look like, using the Gravatar [Example Subgraph](https://github.com/graphprotocol/example-subgraph). + +Assuming we have the following handler function (along with two helper functions to make our life easier): + +```javascript +export function handleNewGravatar(event: NewGravatar): void { + let gravatar = new Gravatar(event.params.id.toHex()) + gravatar.owner = event.params.owner + gravatar.displayName = event.params.displayName + gravatar.imageUrl = event.params.imageUrl + gravatar.save() +} + +export function handleNewGravatars(events: NewGravatar[]): void { + events.forEach((event) => { + handleNewGravatar(event) + }) +} + +export function createNewGravatarEvent( + id: i32, + ownerAddress: string, + displayName: string, + imageUrl: string +): NewGravatar { + let mockEvent = newMockEvent() + let newGravatarEvent = new NewGravatar( + mockEvent.address, + mockEvent.logIndex, + mockEvent.transactionLogIndex, + mockEvent.logType, + mockEvent.block, + mockEvent.transaction, + mockEvent.parameters + ) + newGravatarEvent.parameters = new Array() + let idParam = new ethereum.EventParam('id', ethereum.Value.fromI32(id)) + let addressParam = new ethereum.EventParam( + 'ownderAddress', + ethereum.Value.fromAddress(Address.fromString(ownerAddress)) + ) + let displayNameParam = new ethereum.EventParam('displayName', ethereum.Value.fromString(displayName)) + let imageUrlParam = new ethereum.EventParam('imageUrl', ethereum.Value.fromString(imageUrl)) + + newGravatarEvent.parameters.push(idParam) + newGravatarEvent.parameters.push(addressParam) + newGravatarEvent.parameters.push(displayNameParam) + newGravatarEvent.parameters.push(imageUrlParam) + + return newGravatarEvent +} +``` + +We first have to create a test file in our project. We have chosen the name `gravity.test.ts`. In the newly created file we need to define a function named `runTests()`. It is important that the function has that exact name. This is an example of how our tests might look like: + +```typescript +import { clearStore, test, assert } from 'matchstick-as/assembly/index' +import { Gravatar } from '../../generated/schema' +import { NewGravatar } from '../../generated/Gravity/Gravity' +import { createNewGravatarEvent, handleNewGravatars } from '../mappings/gravity' + +export function runTests(): void { + test('Can call mappings with custom events', () => { + // Initialise + let gravatar = new Gravatar('gravatarId0') + gravatar.save() + + // Call mappings + let newGravatarEvent = createNewGravatarEvent(12345, '0x89205A3A3b2A69De6Dbf7f01ED13B2108B2c43e7', 'cap', 'pac') + + let anotherGravatarEvent = createNewGravatarEvent(3546, '0x89205A3A3b2A69De6Dbf7f01ED13B2108B2c43e7', 'cap', 'pac') + + handleNewGravatars([newGravatarEvent, anotherGravatarEvent]) + + assert.fieldEquals('Gravatar', 'gravatarId0', 'id', 'gravatarId0') + assert.fieldEquals('Gravatar', '12345', 'owner', '0x89205A3A3b2A69De6Dbf7f01ED13B2108B2c43e7') + assert.fieldEquals('Gravatar', '3546', 'displayName', 'cap') + + clearStore() + }) + + test('Next test', () => { + //... + }) +} +``` + +That's a lot to unpack! First off, an important thing to notice is that we're importing things from `matchstick-as`, our AssemblyScript helper library (distributed as an npm module). You can find the repository [here](https://github.com/LimeChain/matchstick-as). `matchstick-as` provides us with useful testing methods and also defines the `test()` function which we will use to build our test blocks. The rest of it is pretty straightforward - here's what happens: + +- We're setting up our initial state and adding one custom Gravatar entity; +- We define two `NewGravatar` event objects along with their data, using the `createNewGravatarEvent()` function; +- We're calling out handler methods for those events - `handleNewGravatars()` and passing in the list of our custom events; +- We assert the state of the store. How does that work? - We're passing a unique combination of Entity type and id. Then we check a specific field on that Entity and assert that it has the value we expect it to have. We're doing this both for the initial Gravatar Entity we added to the store, as well as the two Gravatar entities that gets added when the handler function is called; +- And lastly - we're cleaning the store using `clearStore()` so that our next test can start with a fresh and empty store object. We can define as many test blocks as we want. + +There we go - we've created our first test! 👏 + +❗ **IMPORTANT:** _In order for the tests to work, we need to export the `runTests()` function in our mappings file. It won't be used there, but the export statement has to be there so that it can get picked up by Rust later when running the tests._ + +You can export the tests wrapper function in your mappings file like this: + +``` +export { runTests } from "../tests/gravity.test.ts"; +``` + +❗ **IMPORTANT:** _Currently there's an issue with using Matchstick when deploying your subgraph. Please only use Matchstick for local testing, and remove/comment out this line (`export { runTests } from "../tests/gravity.test.ts"`) once you're done. We expect to resolve this issue shortly, sorry for the inconvenience!_ + +_If you don't remove that line, you will get the following error message when attempting to deploy your subgraph:_ + +``` +/... +Mapping terminated before handling trigger: oneshot canceled +.../ +``` + +Now in order to run our tests you simply need to run the following in your subgraph root folder: + +`graph test Gravity` + +And if all goes well you should be greeted with the following: + +![Matchstick saying “All tests passed!”](/img/matchstick-tests-passed.png) + +## Common test scenarios + +### Hydrating the store with a certain state + +Users are able to hydrate the store with a known set of entities. Here's an example to initialise the store with a Gravatar entity: + +```typescript +let gravatar = new Gravatar('entryId') +gravatar.save() +``` + +### Calling a mapping function with an event + +A user can create a custom event and pass it to a mapping function that is bound to the store: + +```typescript +import { store } from 'matchstick-as/assembly/store' +import { NewGravatar } from '../../generated/Gravity/Gravity' +import { handleNewGravatars, createNewGravatarEvent } from './mapping' + +let newGravatarEvent = createNewGravatarEvent(12345, '0x89205A3A3b2A69De6Dbf7f01ED13B2108B2c43e7', 'cap', 'pac') + +handleNewGravatar(newGravatarEvent) +``` + +### Calling all of the mappings with event fixtures + +Users can call the mappings with test fixtures. + +```typescript +import { NewGravatar } from '../../generated/Gravity/Gravity' +import { store } from 'matchstick-as/assembly/store' +import { handleNewGravatars, createNewGravatarEvent } from './mapping' + +let newGravatarEvent = createNewGravatarEvent(12345, '0x89205A3A3b2A69De6Dbf7f01ED13B2108B2c43e7', 'cap', 'pac') + +let anotherGravatarEvent = createNewGravatarEvent(3546, '0x89205A3A3b2A69De6Dbf7f01ED13B2108B2c43e7', 'cap', 'pac') + +handleNewGravatars([newGravatarEvent, anotherGravatarEvent]) +``` + +``` +export function handleNewGravatars(events: NewGravatar[]): void { + events.forEach(event => { + handleNewGravatar(event); + }); +} +``` + +### Mocking contract calls + +Users can mock contract calls: + +```typescript +import { addMetadata, assert, createMockedFunction, clearStore, test } from 'matchstick-as/assembly/index' +import { Gravity } from '../../generated/Gravity/Gravity' +import { Address, BigInt, ethereum } from '@graphprotocol/graph-ts' + +let contractAddress = Address.fromString('0x89205A3A3b2A69De6Dbf7f01ED13B2108B2c43e7') +let expectedResult = Address.fromString('0x90cBa2Bbb19ecc291A12066Fd8329D65FA1f1947') +let bigIntParam = BigInt.fromString('1234') +createMockedFunction(contractAddress, 'gravatarToOwner', 'gravatarToOwner(uint256):(address)') + .withArgs([ethereum.Value.fromSignedBigInt(bigIntParam)]) + .returns([ethereum.Value.fromAddress(Address.fromString('0x90cBa2Bbb19ecc291A12066Fd8329D65FA1f1947'))]) + +let gravity = Gravity.bind(contractAddress) +let result = gravity.gravatarToOwner(bigIntParam) + +assert.equals(ethereum.Value.fromAddress(expectedResult), ethereum.Value.fromAddress(result)) +``` + +As demonstrated, in order to mock a contract call and hardcore a return value, the user must provide a contract address, function name, function signature, an array of arguments, and of course - the return value. + +Users can also mock function reverts: + +```typescript +let contractAddress = Address.fromString('0x89205A3A3b2A69De6Dbf7f01ED13B2108B2c43e7') +createMockedFunction(contractAddress, 'getGravatar', 'getGravatar(address):(string,string)') + .withArgs([ethereum.Value.fromAddress(contractAddress)]) + .reverts() +``` + +### Asserting the state of the store + +Users are able to assert the final (or midway) state of the store through asserting entities. In order to do this, the user has to supply an Entity type, the specific ID of an Entity, a name of a field on that Entity, and the expected value of the field. Here's a quick example: + +```typescript +import { assert } from 'matchstick-as/assembly/index' +import { Gravatar } from '../generated/schema' + +let gravatar = new Gravatar('gravatarId0') +gravatar.save() + +assert.fieldEquals('Gravatar', 'gravatarId0', 'id', 'gravatarId0') +``` + +Running the assert.fieldEquals() function will check for equality of the given field against the given expected value. The test will fail and an error message will be outputted if the values are **NOT** equal. Otherwise the test will pass successfully. + +### Interacting with Event metadata + +Users can use default transaction metadata, which could be returned as an ethereum.Event by using the `newMockEvent()` function. The following example shows how you can read/write to those fields on the Event object: + +```typescript +// Read +let logType = newGravatarEvent.logType + +// Write +let UPDATED_ADDRESS = '0xB16081F360e3847006dB660bae1c6d1b2e17eC2A' +newGravatarEvent.address = Address.fromString(UPDATED_ADDRESS) +``` + +### Asserting variable equality + +```typescript +assert.equals(ethereum.Value.fromString("hello"); ethereum.Value.fromString("hello")); +``` + +### Asserting that an Entity is **not** in the store + +Users can assert that an entity does not exist in the store. The function takes an entity type and an id. If the entity is in fact in the store, the test will fail with a relevant error message. Here's a quick example of how to use this functionality: + +```typescript +assert.notInStore('Gravatar', '23') +``` + +### Test run time duration in the log output + +The log output includes the test run duration. Here's an example: + +`Jul 09 14:54:42.420 INFO Program execution time: 10.06022ms` + +## Feedback + +If you have any questions, feedback, feature requests or just want to reach out, the best place would be The Graph Discord where we have a dedicated channel for Matchstick, called 🔥| unit-testing. diff --git a/pages/ar/developer/publish-subgraph.mdx b/pages/ar/developer/publish-subgraph.mdx new file mode 100644 index 000000000000..2f35f5eb1bae --- /dev/null +++ b/pages/ar/developer/publish-subgraph.mdx @@ -0,0 +1,27 @@ +--- +title: Publish a Subgraph to the Decentralized Network +--- + +Once your subgraph has been [deployed to the Subgraph Studio](/studio/deploy-subgraph-studio), you have tested it out, and are ready to put it into production, you can then publish it to the decentralized network. + +Publishing a Subgraph to the decentralized network makes it available for [curators](/curating) to begin curating on it, and [indexers](/indexing) to begin indexing it. + +For a walkthrough of how to publish a subgraph to the decentralized network, see [this video](https://youtu.be/HfDgC2oNnwo?t=580). + +### Networks + +The decentralized network currently supports both Rinkeby and Ethereum Mainnet. + +### Publishing a subgraph + +Subgraphs can be published to the decentralized network directly from the Subgraph Studio dashboard by clicking on the **Publish** button. Once a subgraph is published, it will be available to view in the [Graph Explorer](https://thegraph.com/explorer/). + +- Subgraphs published to Rinkeby can index and query data from either the Rinkeby network or Ethereum Mainnet. + +- Subgraphs published to Ethereum Mainnet can only index and query data from Ethereum Mainnet, meaning that you cannot publish subgraphs to the main decentralized network that index and query testnet data. + +- When publishing a new version for an existing subgraph the same rules apply as above. + +### Updating metadata for a published subgraph + +Once your subgraph has been published to the decentralized network, you can modify the metadata at any time by making the update in the Subgraph Studio dashboard of the subgraph. After saving the changes and publishing your updates to the network, they will be reflected in the Graph Explorer. This won’t create a new version, as your deployment hasn’t changed. diff --git a/pages/ar/developer/query-the-graph.mdx b/pages/ar/developer/query-the-graph.mdx new file mode 100644 index 000000000000..ae480b1e6883 --- /dev/null +++ b/pages/ar/developer/query-the-graph.mdx @@ -0,0 +1,32 @@ +--- +title: Query The Graph +--- + +With the subgraph deployed, visit the [Graph Explorer](https://thegraph.com/explorer) to open up a [GraphiQL](https://github.com/graphql/graphiql) interface where you can explore the deployed GraphQL API for the subgraph by issuing queries and viewing the schema. + +An example is provided below, but please see the [Query API](/developer/graphql-api) for a complete reference on how to query the subgraph's entities. + +#### Example + +This query lists all the counters our mapping has created. Since we only create one, the result will only contain our one `default-counter`: + +```graphql +{ + counters { + id + value + } +} +``` + +## Using The Graph Explorer + +Each subgraph published to the decentralized Graph Explorer has a unique query URL that you can find by navigating to the subgraph details page and clicking on the "Query" button on the top right corner. This will open a side pane that will give you the unique query URL of the subgraph as well as some instructions about how to query it. + +![Query Subgraph Pane](/img/query-subgraph-pane.png) + +As you can notice, this query URL must use a unique API key. You can create and manage your API keys in the [Subgraph Studio](https://thegraph.com/studio) in the "API Keys" section. Learn more about how to use Subgraph Studio [here](/studio/subgraph-studio). + +Querying subgraphs using your API keys will generate query fees that will be paid in GRT. You can learn more about billing [here](/studio/billing). + +You can also use the GraphQL playground in the "Playground" tab to query a subgraph within The Graph Explorer. diff --git a/pages/ar/developer/querying-from-your-app.mdx b/pages/ar/developer/querying-from-your-app.mdx new file mode 100644 index 000000000000..c09c44efee72 --- /dev/null +++ b/pages/ar/developer/querying-from-your-app.mdx @@ -0,0 +1,136 @@ +--- +title: Querying from an Application +--- + +Once a subgraph is deployed to the Subgraph Studio or to the Graph Explorer, you will be given the endpoint for your GraphQL API that should look something like this: + +**Subgraph Studio (testing endpoint)** + +```sh +Queries (HTTP) +https://api.studio.thegraph.com/query/// +``` + +**Graph Explorer** + +```sh +Queries (HTTP) +https://gateway.thegraph.com/api//subgraphs/id/ +``` + +Using the GraphQL endpoint, you can use various GraphQL Client libraries to query the subgraph and populate your app with the data indexed by the subgraph. + +Here are a couple of the more popular GraphQL clients in the ecosystem and how to use them: + +### Apollo client + +[Apollo client](https://www.apollographql.com/docs/) supports web projects including frameworks like React and Vue, as well as mobile clients like iOS, Android, and React Native. + +Let's look at how fetch data from a subgraph with Apollo client in a web project. + +First, install `@apollo/client` and `graphql`: + +```sh +npm install @apollo/client graphql +``` + +Then you can query the API with the following code: + +```javascript +import { ApolloClient, InMemoryCache, gql } from '@apollo/client' + +const APIURL = 'https://api.studio.thegraph.com/query///' + +const tokensQuery = ` + query { + tokens { + id + tokenID + contentURI + metadataURI + } + } +` + +const client = new ApolloClient({ + uri: APIURL, + cache: new InMemoryCache(), +}) + +client + .query({ + query: gql(tokensQuery), + }) + .then((data) => console.log('Subgraph data: ', data)) + .catch((err) => { + console.log('Error fetching data: ', err) + }) +``` + +To use variables, you can pass in a `variables` argument to the query: + +```javascript +const tokensQuery = ` + query($first: Int, $orderBy: BigInt, $orderDirection: String) { + tokens( + first: $first, orderBy: $orderBy, orderDirection: $orderDirection + ) { + id + tokenID + contentURI + metadataURI + } + } +` + +client + .query({ + query: gql(tokensQuery), + variables: { + first: 10, + orderBy: 'createdAtTimestamp', + orderDirection: 'desc', + }, + }) + .then((data) => console.log('Subgraph data: ', data)) + .catch((err) => { + console.log('Error fetching data: ', err) + }) +``` + +### URQL + +Another option is [URQL](https://formidable.com/open-source/urql/), a somewhat lighter weight GraphQL client library. + +Let's look at how fetch data from a subgraph with URQL in a web project. + +First, install `urql` and `graphql`: + +```sh +npm install urql graphql +``` + +Then you can query the API with the following code: + +```javascript +import { createClient } from 'urql' + +const APIURL = 'https://api.thegraph.com/subgraphs/name/username/subgraphname' + +const tokensQuery = ` + query { + tokens { + id + tokenID + contentURI + metadataURI + } + } +` + +const client = createClient({ + url: APIURL, +}) + +const data = await client.query(tokensQuery).toPromise() +``` diff --git a/pages/ar/developer/quick-start.mdx b/pages/ar/developer/quick-start.mdx new file mode 100644 index 000000000000..6893d424ddc2 --- /dev/null +++ b/pages/ar/developer/quick-start.mdx @@ -0,0 +1,227 @@ +--- +title: Quick Start +--- + +This guide will quickly take you through how to initialize, create, and deploy your subgraph on: + +- **Subgraph Studio** - used only for subgraphs that index **Ethereum mainnet** +- **Hosted Service** - used for subgraphs that index **other networks** outside of Ethereum mainnnet (e.g. Binance, Matic, etc) + +## Subgraph Studio + +### 1. Install the Graph CLI + +The Graph CLI is written in JavaScript and you will need to have either `npm` or `yarn` installed to use it. + +```sh +# NPM +$ npm install -g @graphprotocol/graph-cli + +# Yarn +$ yarn global add @graphprotocol/graph-cli +``` + +### 2. Initialize your Subgraph + +- Initialize your subgraph from an existing contract. + +```sh +graph init --studio +``` + +- Your subgraph slug is an identifier for your subgraph. The CLI tool will walk you through the steps for creating a subgraph, such as contract address, network, etc as you can see in the screenshot below. + +![Subgraph command](/img/Subgraph-Slug.png) + +### 3. Write your Subgraph + +The previous commands creates a scaffold subgraph that you can use as a starting point for building your subgraph. When making changes to the subgraph, you will mainly work with three files: + +- Manifest (subgraph.yaml) - The manifest defines what datasources your subgraphs will index. +- Schema (schema.graphql) - The GraphQL schema defines what data you wish to retreive from the subgraph. +- AssemblyScript Mappings (mapping.ts) - This is the code that translates data from your datasources to the entities defined in the schema. + +For more information on how to write your subgraph, see [Create a Subgraph](/developer/create-subgraph-hosted). + +### 4. Deploy to the Subgraph Studio + +- Go to the Subgraph Studio [https://thegraph.com/studio/](https://thegraph.com/studio/) and connect your wallet. +- Click "Create" and enter the subgraph slug you used in step 2. +- Run these commands in the subgraph folder + +```sh +$ graph codegen +$ graph build +``` + +- Authenticate and deploy your subgraph. The deploy key can be found on the Subgraph page in Subgraph Studio. + +```sh +$ graph auth --studio +$ graph deploy --studio +``` + +- You will be asked for a version label. It's strongly recommended to use the following conventions for naming your versions. Example: `0.0.1`, `v1`, `version1` + +### 5. Check your logs + +The logs should tell you if there are any errors. If your subgraph is failing, you can query the subgraph health by using the [GraphiQL Playground](https://graphiql-online.com/). Use [this endpoint](https://api.thegraph.com/index-node/graphql). Note that you can leverage the query below and input your deployment ID for your subgraph. In this case, `Qm...` is the deployment ID (which can be located on the Subgraph page under **Details**). The query below will tell you when a subgraph fails so you can debug accordingly: + +```sh +{ + indexingStatuses(subgraphs: ["Qm..."]) { + node + synced + health + fatalError { + message + block { + number + hash + } + handler + } + nonFatalErrors { + message + block { + number + hash + } + handler + } + chains { + network + chainHeadBlock { + number + } + earliestBlock { + number + } + latestBlock { + number + } + lastHealthyBlock { + number + } + } + entityCount + } +} +``` + +### 6. Query your Subgraph + +You can now query your subgraph by following [these instructions](/developer/query-the-graph). You can query from your dapp if you don't have your API key via the free, rate limited temporary query URL that can be used for development and staging. You can read the additional instructions for how to query a subgraph from a frontend application [here](/developer/querying-from-your-app). + +## Hosted Service + +### 1. Install the Graph CLI + +"The Graph CLI is an npm package and you will need `npm` or `yarn` installed to use it. + +```sh +# NPM +$ npm install -g @graphprotocol/graph-cli + +# Yarn +$ yarn global add @graphprotocol/graph-cli +``` + +### 2. Initialize your Subgraph + +- Initialize your subgraph from an existing contract. + +```sh +$ graph init --product hosted-service --from-contract
+``` + +- You will be asked for a subgraph name. The format is `/`. Ex: `graphprotocol/examplesubgraph` + +- If you'd like to initialize from an example, run the command below: + +```sh +$ graph init --product hosted-service --from-example +``` + +- In the case of the example, the subgraph is based on the Gravity contract by Dani Grant that manages user avatars and emits `NewGravatar` or `UpdateGravatar` events whenever avatars are created or updated. + +### 3. Write your Subgraph + +The previous command will have created a scaffold from where you can build your subgraph. When making changes to the subgraph, you will mainly work with three files: + +- Manifest (subgraph.yaml) - The manifest defines what datasources your subgraph will index +- Schema (schema.graphql) - The GraphQL schema define what data you wish to retrieve from the subgraph +- AssemblyScript Mappings (mapping.ts) - This is the code that translates data from your datasources to the entities defined in the schema + +For more information on how to write your subgraph, see [Create a Subgraph](/developer/create-subgraph-hosted). + +### 4. Deploy your Subgraph + +- Sign into the [Hosted Service](https://thegraph.com/hosted-service/) using your github account +- Click Add Subgraph and fill out the required information. Use the same subgraph name as in step 2. +- Run codegen in the subgraph folder + +```sh + # NPM +$ npm run codegen + +# Yarn +$ yarn codegen +``` + +- Add your Access token and deploy your subgraph. The access token is found on your dashboard in the Hosted Service. + +```sh +$ graph auth --product hosted-service +$ graph deploy --product hosted-service / +``` + +### 5. Check your logs + +The logs should tell you if there are any errors. If your subgraph is failing, you can query the subgraph health by using the [GraphiQL Playground](https://graphiql-online.com/). Use [this endpoint](https://api.thegraph.com/index-node/graphql). Note that you can leverage the query below and input your deployment ID for your subgraph. In this case, `Qm...` is the deployment ID (which can be located on the Subgraph page under **Details**). The query below will tell you when a subgraph fails so you can debug accordingly: + +```sh +{ + indexingStatuses(subgraphs: ["Qm..."]) { + node + synced + health + fatalError { + message + block { + number + hash + } + handler + } + nonFatalErrors { + message + block { + number + hash + } + handler + } + chains { + network + chainHeadBlock { + number + } + earliestBlock { + number + } + latestBlock { + number + } + lastHealthyBlock { + number + } + } + entityCount + } +} +``` + +### 6. Query your Subgraph + +Follow [these instructions](/hosted-service/query-hosted-service) to query your subgraph on the Hosted Service. diff --git a/pages/ar/explorer.mdx b/pages/ar/explorer.mdx index c12ecf1ce809..ae31b016d8a4 100644 --- a/pages/ar/explorer.mdx +++ b/pages/ar/explorer.mdx @@ -11,7 +11,7 @@ title: مستكشف title="مشغل فيديو يوتيوب" frameBorder="0" allowFullScreen - > +> ## Subgraphs diff --git a/pages/ar/hosted-service/deploy-subgraph-hosted.mdx b/pages/ar/hosted-service/deploy-subgraph-hosted.mdx new file mode 100644 index 000000000000..bdc532e205e4 --- /dev/null +++ b/pages/ar/hosted-service/deploy-subgraph-hosted.mdx @@ -0,0 +1,160 @@ +--- +title: Deploy a Subgraph to the Hosted Service +--- + +If you have not checked out already, check out how to write the files that make up a [subgraph manifest](/developer/create-subgraph-hosted#the-subgraph-manifest) and how to install the [Graph CLI](https://github.com/graphprotocol/graph-cli) to generate code for your subgraph. Now, it's time to deploy your subgraph to the Hosted Service, also known as the Hosted Service. + +## Create a Hosted Service account + +Before using the Hosted Service, create an account in our Hosted Service. You will need a [Github](https://github.com/) account for that; if you don't have one, you need to create that first. Then, navigate to the [Hosted Service](https://thegraph.com/hosted-service/), click on the _'Sign up with Github'_ button and complete Github's authorization flow. + +## Store the Access Token + +After creating an account, navigate to your [dashboard](https://thegraph.com/hosted-service/dashboard). Copy the access token displayed on the dashboard and run `graph auth --product hosted-service `. This will store the access token on your computer. You only need to do this once, or if you ever regenerate the access token. + +## Create a Subgraph on the Hosted Service + +Before deploying the subgraph, you need to create it in The Graph Explorer. Go to the [dashboard](https://thegraph.com/hosted-service/dashboard) and click on the _'Add Subgraph'_ button and fill in the information below as appropriate: + +**Image** - Select an image to be used as a preview image and thumbnail for the subgraph. + +**Subgraph Name** - Together with the account name that the subgraph is created under, this will also define the `account-name/subgraph-name`-style name used for deployments and GraphQL endpoints. _This field cannot be changed later._ + +**Account** - The account that the subgraph is created under. This can be the account of an individual or organization. _Subgraphs cannot be moved between accounts later._ + +**Subtitle** - Text that will appear in subgraph cards. + +**Description** - Description of the subgraph, visible on the subgraph details page. + +**GitHub URL** - Link to the subgraph repository on GitHub. + +**Hide** - Switching this on hides the subgraph in the 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 [Define a Subgraph section](/developer/define-subgraph-hosted). + +## Deploy a Subgraph on the Hosted Service + +Deploying your subgraph will upload the subgraph files that you've built with `yarn build` to IPFS and tell the Graph Explorer to start indexing your subgraph using these files. + +You deploy the subgraph by running `yarn deploy` + +After deploying the subgraph, the 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 Ethereum blocks, starting with the genesis block, syncing can take from a few minutes to several hours. The subgraph status switches to `Synced` once the Graph Node has extracted all data from historical blocks. The Graph Node will continue inspecting Ethereum blocks for your subgraph as these blocks are mined. + +## Redeploying a Subgraph + +When making changes to your subgraph definition, for example to fix a problem in the entity mappings, run the `yarn deploy` command above again to deploy the updated version of your subgraph. Any update of a subgraph requires that Graph Node reindexes your entire subgraph, again starting with the genesis block. + +If your previously deployed subgraph is still in status `Syncing`, it will be immediately replaced with the newly deployed version. If the previously deployed subgraph is already fully synced, Graph Node will mark the newly deployed version as the `Pending Version`, sync it in the background, and only replace the currently deployed version with the new one once syncing the new version has finished. This ensures that you have a subgraph to work with while the new version is syncing. + +### Deploying the subgraph to multiple Ethereum networks + +In some cases, you will want to deploy the same subgraph to multiple Ethereum networks without duplicating all of its code. The main challenge that comes with this is that the contract addresses on these networks are different. One solution that allows to parameterize aspects like contract addresses is to generate parts of it using a templating system like [Mustache](https://mustache.github.io/) or [Handlebars](https://handlebarsjs.com/). + +To illustrate this approach, let's assume a subgraph should be deployed to mainnet and Ropsten using different contract addresses. You could then define two config files providing the addresses for each network: + +```json +{ + "network": "mainnet", + "address": "0x123..." +} +``` + +and + +```json +{ + "network": "ropsten", + "address": "0xabc..." +} +``` + +Along with that, you would substitute the network name and addresses in the manifest with variable placeholders `{{network}}` and `{{address}}` and rename the manifest to e.g. `subgraph.template.yaml`: + +```yaml +# ... +dataSources: + - kind: ethereum/contract + name: Gravity + network: mainnet + network: {{network}} + source: + address: '0x2E645469f354BB4F5c8a05B3b30A929361cf77eC' + address: '{{address}}' + abi: Gravity + mapping: + kind: ethereum/events +``` + +In order generate a manifest to either network, you could add two additional commands to `package.json` along with a dependency on `mustache`: + +```json +{ + ... + "scripts": { + ... + "prepare:mainnet": "mustache config/mainnet.json subgraph.template.yaml > subgraph.yaml", + "prepare:ropsten": "mustache config/ropsten.json subgraph.template.yaml > subgraph.yaml" + }, + "devDependencies": { + ... + "mustache": "^3.1.0" + } +} +``` + +To deploy this subgraph for mainnet or Ropsten you would now simply run one of the two following commands: + +```sh +# Mainnet: +yarn prepare:mainnet && yarn deploy + +# Ropsten: +yarn prepare:ropsten && yarn deploy +``` + +A working example of this can be found [here](https://github.com/graphprotocol/example-subgraph/tree/371232cf68e6d814facf5e5413ad0fef65144759). + +**Note:** This approach can also be applied more complex situations, where it is necessary to substitute more than contract addresses and network names or where generating mappings or ABIs from templates as well. + +## Checking subgraph health + +If a subgraph syncs successfully, that is a good sign that it will continue to run well forever. However, new triggers on the chain might cause your subgraph to hit an untested error condition or it may start to fall behind due to performance issues or issues with the node operators. + +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](https://github.com/graphprotocol/graph-node/blob/master/server/index-node/src/schema.graphql). Here is an example query that checks the status of the current version of a subgraph: + +```graphql +{ + indexingStatusForCurrentVersion(subgraphName: "org/subgraph") { + synced + health + fatalError { + message + block { + number + hash + } + handler + } + chains { + chainHeadBlock { + number + } + latestBlock { + number + } + } + } +} +``` + +This will give you the `chainHeadBlock` which you can compare with the `latestBlock` on your subgraph to check if it is running behind. `synced` informs if the subgraph has ever caught up to the chain. `health` can currently take the values of `healthy` if no errors ocurred, or `failed` if there was an error which halted the progress of the subgraph. In this case you can check the `fatalError` field for details on this error. + +## Subgraph archive policy + +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 which 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 30 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. diff --git a/pages/ar/hosted-service/migrating-subgraph.mdx b/pages/ar/hosted-service/migrating-subgraph.mdx new file mode 100644 index 000000000000..e6abe9dd1895 --- /dev/null +++ b/pages/ar/hosted-service/migrating-subgraph.mdx @@ -0,0 +1,151 @@ +--- +title: Migrating an Existing Subgraph to The Graph Network +--- + +## Introduction + +This is a guide for the migration of subgraphs from the Hosted Service (also known as the Hosted Service) to The Graph Network. The migration to The Graph Network has been successful for projects like Opyn, UMA, mStable, Audius, PoolTogether, Livepeer, RAI, Enzyme, DODO, Opyn, Pickle, and BadgerDAO all of which are relying on data served by Indexers on the network. There are now over 200 subgraphs live on The Graph Network, generating query fees and actively indexing web3 data. + +This will tell you everything you need to know about how to migrate to the decentralized network and manage your subgraphs moving forward. The process is quick and your subgraphs will forever benefit from the reliability and performance that you can only get on The Graph Network. + +### Migrating An Existing Subgraph to The Graph Network + +1. Get the latest version of the graph-cli installed: + +```sh +npm install -g @graphprotocol/graph-cli +``` + +```sh +yarn global add @graphprotocol/graph-cli +``` + +2. Create a subgraph on the [Subgraph Studio](https://thegraph.com/studio/). Guides on how to do that can be found in the [Subgraph Studio docs](/studio/subgraph-studio) and in [this video tutorial](https://www.youtube.com/watch?v=HfDgC2oNnwo). +3. Inside the main project subgraph repository, authenticate the subgraph to deploy and build on the studio: + +```sh +graph auth --studio +``` + +4. Generate files and build the subgraph: + +```sh +graph codegen && graph build +``` + +5. Deploy the subgraph to the Studio. You can find your `` in the Studio UI, which is based on the name of your subgraph. + +```sh + graph deploy --studio +``` + +6. Test queries on the Studio's playground. Here are some examples for the [Sushi - Mainnet Exchange Subgraph](https://thegraph.com/explorer/subgraph?id=0x4bb4c1b0745ef7b4642feeccd0740dec417ca0a0-0&view=Playground): + +```sh +{ + users(first: 5) { + id + liquidityPositions { + id + } + } + bundles(first: 5) { + id + ethPrice + } +} +``` + +7. Fill in the description and the details of your subgraph and choose up to 3 categories. Upload a project image in the Studio if you'd like as well. +8. Publish the subgraph on The Graph's Network by hitting the "Publish" button. + +- Remember that publishing is an on-chain action and will require gas to be paid for in Ethereum - see an example transaction [here](https://etherscan.io/tx/0xd0c3fa0bc035703c9ba1ce40c1862559b9c5b6ea1198b3320871d535aa0de87b). Prices are roughly around 0.0425 ETH at 100 gwei. +- Any time you need to upgrade your subgraph, you will be charged an upgrade fee. Remember, upgrading is just publishing another version of your existing subgraph on-chain. Because this incurs a cost, it is highly recommended to deploy and test your subgraph on Rinkeby before deploying to mainnet. It can, in some cases, also require some GRT if there is no signal on that subgraph. In the case there is signal/curation on that subgraph version (using auto-migrate), the taxes will be split. + +And that's it! After you are done publishing, you'll be able to view your subgraphs live on the network via [The Graph Explorer](https://thegraph.com/explorer). + +### Upgrading a Subgraph on the Network + +If you would like to upgrade an existing subgraph on the network, you can do this by deploying a new version of your subgraph to the Subgraph Studio using the Graph CLI. + +1. Make changes to your current subgraph. A good idea is to test small fixes on the Subgraph Studio by publishing to Rinkeby. +2. Deploy the following and specify the new version in the command (eg. v0.0.1, v0.0.2, etc): + +```sh +graph deploy --studio +``` + +3. Test the new version in the Subgraph Studio by querying in the playground +4. Publish the new version on The Graph Network. Remember that this requires gas (as described in the section above). + +### Owner Upgrade Fee: Deep Dive + +An upgrade requires GRT to be migrated from the old version of the subgraph to the new version. This means that for every upgrade, a new bonding curve will be created (more on bonding curves [here](/curating#bonding-curve-101)). + +The new bonding curve charges the 2.5% curation tax on all GRT being migrated to the new version. The owner must pay 50% of this, or 1.25%. The other 1.25% is absorbed by all the curators as a fee. This incentive design is in place to prevent an owner of a subgraph from being able to drain all their curator's funds with recursive upgrade calls. The example below is only the case if your subgraph is being actively curated on. If there is no curation activity, you will have to pay a minimum of 100 GRT in order to signal yourself on your own subgraph. + +- 100,000 GRT is signaled using auto-migrate on v1 of a subgraph +- Owner upgrades to v2. 100,000 GRT is migrated to a new bonding curve, where 97,500 GRT get put into the new curve and 2,500 GRT is burned +- The owner then has 1250 GRT burned to pay for half the fee. The owner must have this in their wallet before the upgrade, otherwise the upgrade will not succeed. This happens in the same transaction as the upgrade. + +_While this mechanism is currently live on the network, the community is currently discussing ways to reduce the cost of upgrades for subgraph developers._ + +### Maintaining a Stable Version of a Subgraph + +If you're making a lot of changes to your subgraph, it is not a good idea to continually upgrade it and front the upgrade costs. Maintaining a stable and consistent version of your subgraph is critical, not only from the cost perspective, but also so that Indexers can feel confident in their syncing times. Indexers should be flagged when you plan for an upgrade so that Indexer syncing times do not get impacted. Feel free to leverage the [#Indexers channel](https://discord.gg/8tgJ7rKW) on Discord to let Indexers know when you're versioning your subgraphs. + +Subgraphs are open API that external developers are leveraging. Open APIs need to follow strict standards so that they do not break external developers' applications. In The Graph Network, a subgraph developer must consider Indexers and how long it takes them to sync a new subgraph **as well as** other developers who are using their subgraphs. + +### Updating the Metadata of a Subgraph + +You can update the metadata of your subgraphs without having to publish a new version. The metadata includes the subgraph name, image, description, website URL, source code URL, and categories. Developers can do this by updating their subgraph details in the Subgraph Studio where you can edit all applicable fields. + +Make sure **Update Subgraph Details in Explorer** is checked and click on **Save**. If this is checked, an an on-chain transaction will be generated that updates subgraph details in the Explorer without having to publish a new version with a new deployment. + +## Best Practices for Deploying a Subgraph to The Graph Network + +1. Leveraging an ENS name for Subgraph Development + +- Set up your ENS: [https://app.ens.domains/](https://app.ens.domains/) +- Add your ENS name to your settings [here](https://thegraph.com/explorer/settings?view=display-name). + +The more filled out your profiles are, the better the chances for your subgraphs to be indexed and curated. + +## Deprecating a Subgraph on The Graph Network + +Follow the steps [here](/developer/deprecating-a-subgraph) to deprecate your subgraph and remove it from The Graph Network. + +## Querying a Subgraph + Billing on The Graph Network + +The Hosted Service was set up to allow developers to deploy their subgraphs without any restrictions. + +In order for The Graph Network to truly be decentralized, query fees have to be paid as a core part of the protocol's incentives. For more information on subscribing to APIs and paying the query fees, check out billing documentation [here](/studio/billing). + +### Estimate Query Fees on the Network + +While this is not a live feature in the product UI, you can set your maximum budget per query by taking the amount you're willing to pay per month and divide it by your expected query volume. + +While you get to decide on your query budget, there is no guarantee that an Indexer will be willing to serve queries at that price. If a Gateway can match you to an Indexer willing to serve a query at, or lower than, the price you are willing to pay, you will pay the delta/difference of your budget **and** their price. As a consequence of that, a lower query price reduces the pool of Indexers available to you, which may affect the quality of service you receive. It's beneficial to have high query fees, as that may attract curation and big name Indexers to your subgraph. + +Remember that it's a dynamic and growing market, but how you interact with it is in your control. There is no maximum or minimum price specified in the protocol or in the Gateways. For example, you can look at the price paid by a few of the dapps on the network (on a per week basis), below. See the last column which shows query fees in GRT. For example, [Pickle Finance](https://www.pickle.finance/) has 8 requests per second and paid 2.4 GRT for one week. + +![QueryFee](/img/QueryFee.png) + +## Additional Resources + +If you're still confused, fear not! Check out the following resources or watch our video guide on migrating subgraphs to the decentralized network below: + +
+ +
+ +- [The Graph Network Contracts](https://github.com/graphprotocol/contracts) +- [Curation Contract](https://github.com/graphprotocol/contracts/blob/dev/contracts/curation/Curation.sol) - the underlying contract that the GNS wraps around + - Address - `0x8fe00a685bcb3b2cc296ff6ffeab10aca4ce1538` +- [Subgraph Studio documentation](/studio/subgraph-studio) diff --git a/pages/ar/hosted-service/query-hosted-service.mdx b/pages/ar/hosted-service/query-hosted-service.mdx new file mode 100644 index 000000000000..731e3a3120b2 --- /dev/null +++ b/pages/ar/hosted-service/query-hosted-service.mdx @@ -0,0 +1,28 @@ +--- +title: Query the Hosted Service +--- + +With the subgraph deployed, visit the [Hosted Service](https://thegraph.com/hosted-service/) to open up a [GraphiQL](https://github.com/graphql/graphiql) interface where you can explore the deployed GraphQL API for the subgraph by issuing queries and viewing the schema. + +An example is provided below, but please see the [Query API](/developer/graphql-api) for a complete reference on how to query the subgraph's entities. + +#### Example + +This query lists all the counters our mapping has created. Since we only create one, the result will only contain our one `default-counter`: + +```graphql +{ + counters { + id + value + } +} +``` + +## Using The Hosted Service + +The Graph Explorer and its GraphQL playground is a useful way to explore and query deployed subgraphs on the Hosted Service. + +Some of the main features are detailed below: + +![Explorer Playground](/img/explorer-playground.png) diff --git a/pages/ar/hosted-service/what-is-hosted-service.mdx b/pages/ar/hosted-service/what-is-hosted-service.mdx new file mode 100644 index 000000000000..7f604c8dc31a --- /dev/null +++ b/pages/ar/hosted-service/what-is-hosted-service.mdx @@ -0,0 +1,77 @@ +--- +title: What is the Hosted Service? +--- + +This section will walk you through deploying a subgraph to the Hosted Service, otherwise known as the [Hosted Service.](https://thegraph.com/hosted-service/) As a reminder, the Hosted Service will not be shut down soon. We will gradually sunset the Hosted Service once we reach feature parity with the decentralized network. Your subgraphs deployed on the Hosted Service are still available [here.](https://thegraph.com/hosted-service/) + +If you don't have an account on the Hosted Service, you can signup with your Github account. Once you authenticate, you can start creating subgraphs through the UI and deploying them from your terminal. Graph Node supports a number of Ethereum testnets (Rinkeby, Ropsten, Kovan) in addition to mainnet. + +## Create a Subgraph + +First follow the instructions [here](/developer/define-subgraph-hosted) to install the Graph CLI. Create a subgraph by passing in `graph init --product hosted service` + +### From an Existing Contract + +If you already have a smart contract deployed to Ethereum mainnet or one of the testnets, bootstrapping a new subgraph from this contract can be a good way to get started on the Hosted Service. + +You can use this command to create a subgraph that indexes all events from an existing contract. This will attempt to fetch the contract ABI from [Etherscan](https://etherscan.io/). + +```sh +graph init \ + --product hosted-service + --from-contract \ + / [] +``` + +Additionally, you can use the following optional arguments. If the ABI cannot be fetched from Etherscan, it falls back to requesting a local file path. If any optional arguments are missing from the command, it takes you through an interactive form. + +```sh +--network \ +--abi \ +``` + +The `` in this case is your github user or organization name, `` is the name for your subgraph, and `` is the optional name of the directory where graph init will put the example subgraph manifest. The `` is the address of your existing contract. `` is the name of the Ethereum network that the contract lives on. `` is a local path to a contract ABI file. **Both --network and --abi are optional.** + +### From an Example Subgraph + +The second mode `graph init` supports is creating a new project from an example subgraph. The following command does this: + +``` +graph init --from-example --product hosted-service / [] +``` + +The example subgraph is based on the Gravity contract by Dani Grant that manages user avatars and emits `NewGravatar` or `UpdateGravatar` events whenever avatars are created or updated. The subgraph handles these events by writing `Gravatar` entities to the Graph Node store and ensuring these are updated according to the events. Continue on to the [subgraph manifest](/developer/create-subgraph-hosted#the-subgraph-manifest) to better understand which events from your smart contracts to pay attention to, mappings, and more. + +## Supported Networks on the Hosted Service + +Please note that the following networks are supported on the Hosted Service. Networks outside of Ethereum mainnet ('mainnet') are not currently supported on [The Graph Explorer.](https://thegraph.com/explorer) + +- `mainnet` +- `kovan` +- `rinkeby` +- `ropsten` +- `goerli` +- `poa-core` +- `poa-sokol` +- `xdai` +- `near-mainnet` +- `near-testnet` +- `matic` +- `mumbai` +- `fantom` +- `bsc` +- `chapel` +- `clover` +- `avalanche` +- `fuji` +- `celo` +- `celo-alfajores` +- `fuse` +- `moonriver` +- `mbase` +- `arbitrum-one` +- `arbitrum-rinkeby` +- `optimism` +- `optimism-kovan` +- `aurora` +- `aurora-testnet` diff --git a/pages/ar/indexing.mdx b/pages/ar/indexing.mdx index 3c05105e8ce0..23625e978032 100644 --- a/pages/ar/indexing.mdx +++ b/pages/ar/indexing.mdx @@ -115,7 +115,7 @@ Disputes can be viewed in the UI in an Indexer's profile page under the `Dispute - **كبيرة** - مُعدة لفهرسة جميع ال subgraphs المستخدمة حاليا وأيضا لخدمة طلبات حركة المرور البيانات ذات الصلة. | Setup | (CPUs) | (memory in GB) | (disk in TBs) | (CPUs) | (memory in GB) | -| ----- | :----: | :------------: | :-----------: | :----: | :------------: | +| ----- |:------:|:--------------:|:-------------:|:------:|:--------------:| | صغير | 4 | 8 | 1 | 4 | 16 | | قياسي | 8 | 30 | 1 | 12 | 48 | | متوسط | 16 | 64 | 2 | 32 | 64 | @@ -149,20 +149,20 @@ Disputes can be viewed in the UI in an Indexer's profile page under the `Dispute #### Graph Node -| Port | Purpose | Routes | CLI Argument | Environment Variable | -| --- | --- | --- | --- | --- | -| 8000 | GraphQL HTTP server
(for subgraph queries) | /subgraphs/id/...

/subgraphs/name/.../... | --http-port | - | -| 8001 | GraphQL WS
(for subgraph subscriptions) | /subgraphs/id/...

/subgraphs/name/.../... | --ws-port | - | -| 8020 | JSON-RPC
(for managing deployments) | / | --admin-port | - | -| 8030 | Subgraph indexing status API | /graphql | --index-node-port | - | -| 8040 | Prometheus metrics | /metrics | --metrics-port | - | +| Port | Purpose | Routes | CLI Argument | Environment Variable | +| ---- | ------------------------------------------------------- | ------------------------------------------------------------------- | ----------------- | -------------------- | +| 8000 | GraphQL HTTP server
(for subgraph queries) | /subgraphs/id/...

/subgraphs/name/.../... | --http-port | - | +| 8001 | GraphQL WS
(for subgraph subscriptions) | /subgraphs/id/...

/subgraphs/name/.../... | --ws-port | - | +| 8020 | JSON-RPC
(for managing deployments) | / | --admin-port | - | +| 8030 | Subgraph indexing status API | /graphql | --index-node-port | - | +| 8040 | Prometheus metrics | /metrics | --metrics-port | - | #### خدمة المفهرس -| Port | Purpose | Routes | CLI Argument | Environment Variable | -| --- | --- | --- | --- | --- | -| 7600 | GraphQL HTTP server
(for paid subgraph queries) | /subgraphs/id/...
/status
/channel-messages-inbox | --port | `INDEXER_SERVICE_PORT` | -| 7300 | Prometheus metrics | /metrics | --metrics-port | - | +| Port | Purpose | Routes | CLI Argument | Environment Variable | +| ---- | ------------------------------------------------------------ | --------------------------------------------------------------------------- | -------------- | ---------------------- | +| 7600 | GraphQL HTTP server
(for paid subgraph queries) | /subgraphs/id/...
/status
/channel-messages-inbox | --port | `INDEXER_SERVICE_PORT` | +| 7300 | Prometheus metrics | /metrics | --metrics-port | - | #### Indexer Agent diff --git a/pages/ar/studio/billing.mdx b/pages/ar/studio/billing.mdx new file mode 100644 index 000000000000..739b216bc86e --- /dev/null +++ b/pages/ar/studio/billing.mdx @@ -0,0 +1,68 @@ +--- +title: Billing on the Subgraph Studio +--- + +### Overview + +Invoices are statements of payment amounts owed by a customer and are typically generated on a weekly basis in the system. You’ll be required to pay fees based on the query fees you generate using your API keys. The billing contract lives on the [Polygon](https://polygon.technology/) network. It’ll allow you to: + +- Add and remove GRT +- Keep track of your balances based on how much GRT you have added to your account, how much you have removed, and your invoices +- Automatically clear payments based on query fees generated + +In order to add GRT to your account, you will need to go through the following steps: + +1. Purchase GRT and ETH on an exchange of your choice +2. Send the GRT and ETH to your wallet +3. Bridge GRT to Polygon using the UI + + a) You will receive 0.001 Matic in a few minutes after you send any amount of GRT to the Polygon bridge. You can track the transaction on [Polygonscan](https://polygonscan.com/) by inputting your address into the search bar. + +4. Add bridged GRT to the billing contract on Polygon. The billing contract address is: [0x10829DB618E6F520Fa3A01c75bC6dDf8722fA9fE](https://polygonscan.com/address/0x10829DB618E6F520Fa3A01c75bC6dDf8722fA9fE). + + a) In order to complete step #4, you'll need to switch your network in your wallet to Polygon. You can add Polygon's network by connecting your wallet and clicking on "Choose Matic (Polygon) Mainnet" [here.](https://chainlist.org/) Once you've added the network, switch it over in your wallet by navigating to the network pill on the top right hand side corner. In Metamask, the network is called **Matic Mainnnet.** + +At the end of each week, if you used your API keys, you will receive an invoice based on the query fees you have generated during this period. This invoice will be paid using GRT available in your balance. Query volume is evaluated by the API keys you own. Your balance will be updated after fees are withdrawn. + +#### Here’s how you go through the invoicing process: + +There are 4 states your invoice can be in: + +1. Created - your invoice has just been created and not been paid yet +2. Paid - your invoice has been successfully paid +3. Unpaid - there is not enough GRT in your balance on the billing contract +4. Error - there is an error processing the payment + +**See the diagram below for more information:** + +![Billing Flow](/img/billing-flow.png) + +For a quick demo of how billing works on the Subgraph Studio, check out the video below: + +
+ +
+ +### Multisig Users + +Multisigs are smart-contracts that can exist only on the network they have been created, so if you created one on Ethereum Mainnet - it will only exist on Mainnet. Since our billing uses Polygon, if you were to bridge GRT to the multisig address on Polygon the funds would be lost. + +To overcome this issue, we created [a dedicated tool](https://multisig-billing.thegraph.com/) that will help you deposit GRT on our billing contract (on behalf of the multisig) with a standard wallet / EOA (an account controlled by a private key). + +You can access our Multisig Billing Tool here: https://multisig-billing.thegraph.com/ + +This tool will guide you to go through the following steps: + +1. Connect your standard wallet / EOA (this wallet needs to own some ETH as well as the GRT you want to deposit) +2. Bridge GRT to Polygon. You will have to wait 7-8 minutes after the transaction is complete for the bridge transfer to be finalized. +3. Once your GRT is available on your Polygon balance you can deposit them to the billing contract while specifying the multisig address you are funding in the `Multisig Address` field. + +Once the deposit transaction has been confirmed you can go back to [Subgraph Studio](https://thegraph.com/studio/) and connect with your Gnosis Safe Multisig to create API keys and use them to generate queries. + +Those queries will generate invoices that will be paid automatically using the multisig’s billing balance. diff --git a/pages/ar/studio/deploy-subgraph-studio.mdx b/pages/ar/studio/deploy-subgraph-studio.mdx new file mode 100644 index 000000000000..2155d8fe8976 --- /dev/null +++ b/pages/ar/studio/deploy-subgraph-studio.mdx @@ -0,0 +1,68 @@ +--- +title: Deploy a Subgraph to the Subgraph Studio +--- + +Deploying a Subgraph to the Subgraph Studio is quite simple. This will take you through the steps to: + +- Install The Graph CLI (with both yarn and npm) +- Create your Subgraph in the Subgraph Studio +- Authenticate your account from the CLI +- Deploying a Subgraph to the Subgraph Studio + +## Installing Graph CLI + +We are using the same CLI to deploy subgraphs to our [hosted service](https://thegraph.com/hosted-service/) and to the [Subgraph Studio](https://thegraph.com/studio/). Here are the commands to install graph-cli. This can be done using npm or yarn. + +**Install with yarn:** + +```bash +yarn global add @graphprotocol/graph-cli +``` + +**Install with npm:** + +```bash +npm install -g @graphprotocol/graph-cli +``` + +## Create your Subgraph in Subgraph Studio + +Before deploying your actual subgraph you need to create a subgraph in [Subgraph Studio](https://thegraph.com/studio/). We recommend you read our [Studio documentation](/studio/subgraph-studio) to learn more about this. + +## Initialize your Subgraph + +Once your subgraph has been created in Subgraph Studio you can initialize the subgraph code using this command: + +```bash +graph init --studio +``` + +The `` value can be found on your subgraph details page in Subgraph Studio: + +![Subgraph Studio - Slug](/img/doc-subgraph-slug.png) + +After running `graph init`, you will be asked to input the contract address, network and abi that you want to query. Doing this will generate a new folder on your local machine with some basic code to start working on your subgraph. You can then finalize your subgraph to make sure it works as expected. + +## Graph Auth + +Before being able to deploy your subgraph to Subgraph Studio, you need to login to your account within the CLI. To do this, you will need your deploy key that you can find on your "My Subgraphs" page or on your subgraph details page. + +Here is the command that you need to use to authenticate from the CLI: + +```bash +graph auth --studio +``` + +## Deploying a Subgraph to Subgraph Studio + +Once you are ready, you can deploy your subgraph to Subgraph Studio. Doing this won't publish your subgraph to the decentralized network, it will only deploy it to your Studio account where you will be able to test it and update the metadata. + +Here is the CLI command that you need to use to deploy your subgraph. + +```bash +graph deploy --studio +``` + +After running this command, the CLI will ask for a version label, you can name it however you want, you can use labels such as `0.1` and `0.2` or use letters as well such as `uniswap-v2-0.1` . Those labels will be visible in Graph Explorer and can be used by curators to decide if they want to signal on this version or not, so choose them wisely. + +Once deployed, you can test your subgraph in Subgraph Studio using the playground, deploy another version if needed, update the metadata, and when you are ready, publish your subgraph to Graph Explorer. diff --git a/pages/ar/studio/multisig.mdx b/pages/ar/studio/multisig.mdx new file mode 100644 index 000000000000..164835bdb8a4 --- /dev/null +++ b/pages/ar/studio/multisig.mdx @@ -0,0 +1,82 @@ +--- +title: Using a Multisig Wallet +--- + +Subgraph Studio currently doesn't support signing with multisig wallets. Until then, you can follow this guide on how to publish your subgraph by invoking the [GNS contract](https://github.com/graphprotocol/contracts/blob/dev/contracts/discovery/GNS.sol) functions. + +### Create a Subgraph + +Similary to using a regular wallet, you can create a subgraph by connecting your non-multisig wallet in Subgraph Studio. Once you connect the wallet, simply create a new subgraph. Make sure you fill out all the details, such as subgraph name, description, image, website, and source code url if applicable. + +For initializing a starter subgraph, you can follow the commands shown in the UI, or simply run + +``` +graph init --studio +``` + +`SUBGRAPH_SLUG` is the name of your subgraph that you can copy from the UI, or from the URL in the browser. This command should create a folder in your file system with all the necessary files to start developing a subgraph. + +### Deploy a Subgraph + +Once your subgraph is ready to be deployed to the graph node, simply follow the commands shown in the UI, or run the following command: + +``` +graph deploy --studio +``` + +**Note**: Make sure that you are inside of the subgraph folder before running the command. + +### Publish a Subgraph or a Version + +You can either publish a new subgraph to the decentralized network or publish a new version of the previously published subgraph. + +#### Publish a New Subgraph + +There are a couple of ways to publish a subgraph using multisig wallets. Here we'll describe invoking the [`publishNewSubgraph`](https://github.com/graphprotocol/contracts/blob/dev/contracts/discovery/GNS.sol#L231) function in the [GNS contract](https://etherscan.io/address/0xaDcA0dd4729c8BA3aCf3E99F3A9f471EF37b6825) using Etherscan. + +Before we use that function, we need to generate input arguments for it. Access [this page](https://thegraph.com/studio/multisig) in Subgraph Studio and provide the following: + +- Ethereum address of your multisig wallet +- Subgraph that you want to publish +- Version that you want to publish + +After clicking on "Get Arguments", we'll generate all the contract arguments for you! + +There should be 4 arguments: + +- `graphAccount`: which is your multisig account address +- `subgraphDeploymentID`: the hex hash of the deployment ID for that subgraph +- `versionMetadata`: version metadata (label and description) that gets uploaded to IPFS. The hex hash value for that JSON file will be provided. +- `subgraphMetadata`: simlar to version metadata, subgraph metadata (name, image, description, website and source code url) gets uploaded to IPFS, and we provide the hex hash value for that JSON file + +With those 4 arguments, you should be able to: + +- Visit [our GraphProxy](https://etherscan.io/address/0xaDcA0dd4729c8BA3aCf3E99F3A9f471EF37b6825#writeProxyContract) contract on Etherscan +- Connect to Etherscan using WalletConnect via the WalletConnect Safe app of your multisig +- Call the `publishNewSubgraph` method with the paramaters that were generated by our tool + +#### Publish a New Version + +To publish a new version of an existing subgraph we first need to generate input arguments for it. Access [this page](https://thegraph.com/studio/multisig) in Subgraph Studio and provide: + +- Ethereum address of your multisig wallet +- Subgraph that you want to publish +- Version that you want to publish +- The ID of the subgraph you want to update in Graph Explorer + +After clicking on "Get Arguments" we'll generate all the contract arguments for you! + +On the right side of the UI under the `Publish New Version` title, there should be 4 arguments: + +- `graphAccount`: which is your Multisig account address +- `subgraphNumber`: is the number of your already published subgraph. It is a part of the subgraph id for a published subgraph queried through The Graph Network subgraph. +- `subgraphDeploymentID`: which is the hex hash of the deployment ID for that subgraph +- `versionMetadata`: version metadata (label and description) gets uploaded to IPFS, and we provide the hex hash value for that JSON file + +Now that we generated all the arguments you are ready to proceed and call the `publishNewVersion` method. In order to do so, you should: + +- Visit [the GraphProxy](https://etherscan.io/address/0xaDcA0dd4729c8BA3aCf3E99F3A9f471EF37b6825#writeProxyContract) contract on Etherscan +- Connect to Etherscan using WalletConnect via the WalletConnect Safe app of your Multisig +- Call the `publishNewVersion` method with the paramaters that were generated by our tool + +Once the transaction is successful, your subgraph should have a new version of your subgraph in Graph Explorer which means that curators can start signaling on it and indexers can start indexing it. diff --git a/pages/ar/studio/studio-faq.mdx b/pages/ar/studio/studio-faq.mdx new file mode 100644 index 000000000000..4db4d7ccddaa --- /dev/null +++ b/pages/ar/studio/studio-faq.mdx @@ -0,0 +1,21 @@ +--- +title: Subgraph Studio FAQs +--- + +### 1. How do I create an API Key? + +In the Subgraph Studio, you can create API Keys as needed and add security settings to each of them. + +### 2. Can I create multiple API Keys? + +A: Yes! You can create multiple API Keys to use in different projects. Check out the link [here](https://thegraph.com/studio/apikeys/). + +### 3. How do I restrict a domain for an API Key? + +After creating an API Key, in the Security section you can define the domains that can query a specific API Key. + +### 4. How do I find query URLs for subgraphs if I’m not the developer of the subgraph I want to use? + +You can find the query URL of each subgraph in the Subgraph Details section of The Graph Explorer. When you click on the “Query” button, you will be directed to a pane wherein you can view the query URL of the subgraph you’re interested in. You can then replace the `` placeholder with the API key you wish to leverage in the Subgraph Studio. + +Remember that you can create an API key and query any subgraph published to the network, even if you build a subgraph yourself. These queries via the new API key, are paid queries as any other on the network. diff --git a/pages/ar/studio/subgraph-studio.mdx b/pages/ar/studio/subgraph-studio.mdx new file mode 100644 index 000000000000..60e01374fc04 --- /dev/null +++ b/pages/ar/studio/subgraph-studio.mdx @@ -0,0 +1,122 @@ +--- +title: How to Use the Subgraph Studio +--- + +Welcome to your new launchpad 👩🏽‍🚀 + +The Subgraph Studio is your place to build and create subgraphs, add metadata, and publish them to the new decentralized Explorer (more on that [here](/explorer)). + +What you can do in the Subgraph Studio: + +- Create a subgraph through the Studio UI +- Deploy a subgraph using the CLI +- Publish a subgraph with the Studio UI +- Test it in the playground +- Integrate it in staging using the query URL +- Create and manage your API keys for specific subgraphs + +Here in the Subgraph Studio, you have full control over your subgraphs. Not only can you test your subgraphs before you publish them, but you can also restrict your API keys to specific domains and only allow certain indexers to query from their API keys. + +Querying subgraphs generates query fees, used to reward [indexers](/indexing) on the Graph network. If you’re a dapp developer or subgraph developer, the Studio will empower you to build better subgraphs to power your or your community’s queries. The Studio is comprised of 5 main parts: + +- Your user account controls +- A list of subgraphs that you’ve created +- A section to manage, view details, and visualize the status of a specific subgraph +- A section to manage your API keys that you will need to query a subgraph +- A section to manage your billing + +## How to Create Your Account + +1. Sign in with your wallet - you can do this via MetaMask or WalletConnect +1. Once you sign in, you will see your unique deploy key in your account home page. This will allow you to either publish your subgraphs or manage your API keys + billing. You will have a unique deploy key that can be re-generated if you think it has been compromised. + +## How to Create your Subgraph in Subgraph Studio + +The best part! When you first create a subgraph, you’ll be directed to fill out: + +- Your Subgraph Name +- Image +- Description +- Categories +- Website + +## Subgraph Compatibility with The Graph Network + +The Graph Network is not yet able to support all of the data-sources & features available on the Hosted Service. In order to be supported by indexers on the network, subgraphs must: + +- Index mainnet Ethereum +- Must not use any of the following features: + - ipfs.cat & ipfs.map + - Non-fatal errors + - Grafting + +More features & networks will be added to The Graph Network incrementally. + +### Subgraph lifecycle flow + +![Subgraph Lifecycle](/img/subgraph-lifecycle.png) + +After you have created your subgraph, you will be able to deploy it using the [CLI](https://github.com/graphprotocol/graph-cli), or command line interface. Deploying a subgraph with the CLI will push the subgraph to the Studio where you’ll be able to test subgraphs using the playground. This will eventually allow you to publish to the Graph Network. For more information on CLI setup, [check this out](/developer/define-subgraph-hosted#install-the-graph-cli) (pst, make sure you have your deploy key on hand). Remember, deploying is **not the same as** publishing. When you deploy a subgraph, you just push it to the Studio where you’re able to test it. Versus, when you publish a subgraph, you are publishing it on-chain. + +## Testing your Subgraph in Subgraph Studio + +If you’d like to test your subgraph before publishing it to the network, you can do this in the Subgraph **Playground** or look at your logs. The Subgraph logs will tell you **where** your subgraph fails in the case that it does. + +## Publish your Subgraph in Subgraph Studio + +You’ve made it this far - congrats! Publishing your subgraph means that an IPFS hash was generated when you deployed the subgraph within the CLI and is stored in the network’s Ethereum smart contracts. In order to publish your subgraph successfully, you’ll need to go through the following steps outlined in this [blog](https://thegraph.com/blog/building-with-subgraph-studio). Check out the video overview below as well: + +
+ +
+ +Remember, while you’re going through your publishing flow, you’ll be able to push to either mainnet or Rinkeby, the testnet we support. If you’re a first time subgraph developer, we highly suggest you start with publishing to Rinkeby, which is free to do. This will allow you to see how the subgraph will work in The Graph Explorer and will allow you to test curation elements. + +You’ll only be able to index data from mainnet (even if your subgraph was published to a testnet) because only subgraphs that are indexing mainnet data can be published to the network. This is because indexers need to submit mandatory Proof of Indexing records as of a specific block hash. Because publishing a subgraph is an action taken on-chain, remember that the transaction can take up to a few minutes to go through. Any address you use to publish the contract will be the only one able to publish future versions. Choose wisely! + +Subgraphs with curation signal are shown to Indexers so that they can be indexed on the decentralized network. You can publish subgraphs and signal in one transaction, which allows you to mint the first curation signal on the subgraph and saves on gas costs. By adding your signal to the signal later provided by Curators, your subgraph will also have a higher chance of ultimately serving queries. + +**Now that you’ve published your subgraph, let’s get into how you’ll manage them on a regular basis.** Note that you cannot publish your subgraph to the network if it has failed syncing. This is usually because the subgraph has bugs - the logs will tell you where those issues exist! + +## Versioning your Subgraph with the CLI + +Developers might want to update their subgraph, for a variety of reasons. When this is the case, you can deploy a new version of your subgraph to the Studio using the CLI (it will only be private at this point) and if you are happy with it, you can publish this new deployment to The Graph Explorer. This will create a new version of your subgraph that curators can start signaling on and indexers will be able to index this new version. + +Up until recently, developers were forced to deploy and publish a new version of their subgraph to the Explorer to update the metadata of their subgraphs. Now, developers can update the metadata of their subgraphs **without having to publish a new version**. Developers can update their subgraph details in the Studio (under profile picture, name, description, etc) by checking an option called **Update Details** in The Graph Explorer. If this is checked, an on-chain transaction will be generated that updates subgraph details in the Explorer without having to publish a new version with a new deployment. + +Please note that there are costs associated with publishing a new version of a subgraph to the network. In addition to the transaction fees, developers must also fund a part of the curation tax on auto-migrating signal. You cannot publish a new version of your subgraph if curators have not signaled on it. For more information on the risks of curation, please read more [here](/curating). + +### Automatic Archiving of Subgraph Versions + +Whenever you deploy a new subgraph version in the Subgraph Studio, the previous version will be archived. Archived versions won't be indexed/synced and therefore cannot be queried. You can unarchive an archived version of your subgraph in the Studio UI. Please note that previous versions of non-published subgraphs deployed to the Studio will be automatically archived. + +![Subgraph Studio - Unarchive](/img/Unarchive.png) + +## Managing your API Keys + +Regardless of whether you’re a dapp developer or a subgraph developer, you’ll need to manage your API keys. This is important for you to be able to query subgraphs because API keys make sure the connections between application services are valid and authorized. This includes authenticating the end user and the device using the application. + +The Studio will list out existing API keys, which will give you the ability to manage or delete them. + +1. The **Overview** section will allow you to: + - Edit your key name + - Regenerate API keys + - View the current usage of the API key with stats: + - Number of queries + - Amount of GRT spent +2. Under **Manage Security Settings**, you’ll be able to opt into security settings depending on the level of control you’d like to have over your API keys. In this section, you can: + - View and manage the domain names authorized to use your API key + - Assign subgraphs that can be queried with your API key + +## How to Manage your Subgraph + +API keys aside, you’ll have many tools at your disposal to manage your subgraphs. You can organize your subgraphs by their **status** and **category**. + +- The **Status** tag allows you to pick between a variety of tags including ``, ``, ``, ``, etc. +- Meanwhile, **Category** allows you to designate what category your subgraph falls into. Options include ``, ``, ``, etc. diff --git a/pages/ar/supported-networks/near.mdx b/pages/ar/supported-networks/near.mdx new file mode 100644 index 000000000000..c364fd4ecf89 --- /dev/null +++ b/pages/ar/supported-networks/near.mdx @@ -0,0 +1,265 @@ +--- +title: Building Subgraphs on NEAR +--- + +> NEAR support in Graph Node and on the Hosted Service is in beta: please contact near@thegraph.com with any questions about building NEAR subgraphs! + +This guide is an introduction to building subgraphs indexing smart contracts on the [NEAR blockchain](https://docs.near.org/). + +## What is NEAR? + +[NEAR](https://near.org/) is a smart contract platform for building decentralised applications. Visit the [official documentation](https://docs.near.org/docs/concepts/new-to-near) for more information. + +## What are NEAR subgraphs? + +The Graph gives developers tools to process blockchain events and make the resulting data easily available via a GraphQL API, known individually as a subgraph. [Graph Node](https://github.com/graphprotocol/graph-node) is now able to process NEAR events, which means that NEAR developers can now build subgraphs to index their smart contracts. + +Subgraphs are event-based, which means that they listen for and then process on-chain events. There are currently two types of handlers supported for NEAR subgraphs: + +- Block handlers: these are run on every new block +- Receipt handlers: run every time a message is executed at a specified account + +[From the NEAR documentation](https://docs.near.org/docs/concepts/transaction#receipt): + +> A Receipt is the only actionable object in the system. When we talk about "processing a transaction" on the NEAR platform, this eventually means "applying receipts" at some point. + +## Building a NEAR Subgraph + +`@graphprotocol/graph-cli` is a command line tool for building and deploying subgraphs. + +`@graphprotocol/graph-ts` is a library of subgraph-specific types. + +NEAR subgraph development requires `graph-cli` above version `0.23.0`, and `graph-ts` above version `0.23.0`. + +> Building a NEAR subgraph is very similar to building a subgraph which indexes Ethereum. + +There are three aspects of subgraph definition: + +**subgraph.yaml:** the subgraph manifest, defining the data sources of interest, and how they should be processed. NEAR is a new `kind` of data source. + +**schema.graphql:** a schema file that defines what data is stored for your subgraph, and how to query it via GraphQL. The requirements for NEAR subgraphs are covered by [the existing documentation](/developer/create-subgraph-hosted#the-graphql-schema). + +**AssemblyScript Mappings:** [AssemblyScript code](/developer/assemblyscript-api) 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. + +During subgraph development there are two key commands: + +```bash +$ graph codegen # generates types from the schema file identified in the manifest +$ graph build # generates Web Assembly from the AssemblyScript files, and prepares all the subgraph files in a /build folder +``` + +### Subgraph Manifest Definition + +The subgraph manifest (`subgraph.yaml`) identifies the data sources for the subgraph, the triggers of interest, and the functions that should be run in response to those triggers. See below for an example subgraph manifest for a NEAR subgraph:: + +```yaml +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 subgraphs introduce a new `kind` of data source (`near`) +- The `network` should correspond to a network on the hosting Graph Node. On the Hosted Service, 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](https://docs.near.org/docs/concepts/account). This can be an account, or a sub account. + +NEAR data sources support two types of handlers: + +- `blockHandlers`: run on every new NEAR block. No `source.account` is required. +- `receiptHandlers`: run on every receipt where the data source's `source.account` is the recipient. Note that only exact matches are processed ([subaccounts](https://docs.near.org/docs/concepts/account#subaccounts) must be added as independent data sources). + +### Schema Definition + +Schema definition describes the structure of the resulting subgraph database, and the relationships between entities. This is agnostic of the original data source. There are more details on subgraph schema definition [here](/developer/create-subgraph-hosted#the-graphql-schema). + +### AssemblyScript Mappings + +The handlers for processing events are written in [AssemblyScript](https://www.assemblyscript.org/). + +NEAR indexing introduces NEAR-specific data types to the [AssemblyScript API](/developer/assemblyscript-api). + +```typescript + +class ExecutionOutcome { + gasBurnt: u64, + blockHash: Bytes, + id: Bytes, + logs: Array, + receiptIds: Array, + tokensBurnt: BigInt, + executorId: string, + } + +class ActionReceipt { + predecessorId: string, + receiverId: string, + id: CryptoHash, + signerId: string, + gasPrice: BigInt, + outputDataReceivers: Array, + inputDataIds: Array, + actions: Array, + } + +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, + } + +class ReceiptWithOutcome { + outcome: ExecutionOutcome, + receipt: ActionReceipt, + block: Block, + } +``` + +These types are passed to block & receipt handlers: + +- Block handlers will receive a `Block` +- Receipt handlers will receive a `ReceiptWithOutcome` + +Otherwise the rest of the [AssemblyScript API](/developer/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](/developer/assemblyscript-api#json-api) to allow developers to easily process these logs. + +## Deploying a NEAR Subgraph + +Once you have a built subgraph, it is time to deploy it to Graph Node for indexing. NEAR subgraphs can be deployed to any Graph Node `>=v0.26.x` (this version has not yet been tagged & released). + +The Graph's Hosted Service 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 the Hosted Service can be found [here](/hosted-service/deploy-subgraph-hosted). + +As a quick primer - the first step is to "create" your subgraph - this only needs to be done once. On the Hosted Service, this can be done from [your Dashboard](https://thegraph.com/hosted-service/dashboard): "Add Subgraph". + +Once your subgraph has been created, you can deploy your subgraph by using the `graph deploy` CLI command: + +``` +$ graph create --node subgraph/name # creates a subgraph on a local Graph Node (on the Hosted Service, this is done via the UI) +$ graph deploy --node --ipfs https://api.thegraph.com/ipfs/ # 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 +``` + +The node configuration will depend where the subgraph is being deployed. + +#### Hosted Service: + +``` +graph deploy --node https://api.thegraph.com/deploy/ --ipfs https://api.thegraph.com/ipfs/ --access-token +``` + +#### Local Graph Node (based on default configuration): + +``` +graph deploy --node http://localhost:8020/ --ipfs http://localhost:5001 +``` + +Once your subgraph has been deployed, it will be indexed by Graph Node. You can check its progress by querying the subgraph itself: + +``` +{ + _meta { + block { number } + } +} +``` + +### Indexing NEAR with a Local Graph Node + +Running a Graph Node that indexes NEAR has the following operational requirements: + +- NEAR Indexer Framework with Firehose instrumentation +- NEAR Firehose Component(s) +- Graph Node with Firehose endpoint configured + +We will provide more information on running the above components soon. + +## Querying a NEAR Subgraph + +The GraphQL endpoint for NEAR subgraphs is determined by the schema definition, with the existing API interface. Please visit the [GraphQL API documentation](/developer/graphql-api) for more information. + +## Example Subgraphs + +Here are some example subgraphs for reference: + +[NEAR Blocks](https://github.com/graphprotocol/example-subgraph/tree/near-blocks-example) + +[NEAR Receipts](https://github.com/graphprotocol/example-subgraph/tree/near-receipts-example) + +## الأسئلة الشائعة + +### How does the beta work? + +NEAR support is in beta, which means that there may be changes to the API as we continue to work on improving the integration. Please email near@thegraph.com so that we can support you in building NEAR subgraphs, and keep you up to date on the latest developments! + +### Can a subgraph index both NEAR and EVM chains? + +No, a subgraph can only support data sources from one chain / network. + +### Can subgraphs react to more specific triggers? + +Currently, only Block and Receipt triggers are supported. We are investigating triggers for function calls to a specified account. We are also interested in supporting event triggers, once NEAR has native event support. + +### Will receipt handlers trigger for accounts and their sub accounts? + +Receipt handlers will only be triggered for the exact-match of the named account. More flexibility may be added in future. + +### Can NEAR subgraphs make view calls to NEAR accounts during mappings? + +This is not supported. We are evaluating whether this functionality is required for indexing. + +### Can I use data source templates in my NEAR subgraph? + +This is not currently supported. We are evaluating whether this functionality is required for indexing. + +### Ethereum subgraphs support "pending" and "current" versions, how can I deploy a "pending" version of a NEAR subgraph? + +Pending functionality is not yet supported for NEAR subgraphs. In the interim, you can deploy a new version to a different "named" subgraph, and then when that is synced with the chain head, you can redeploy to your primary "named" subgraph, which will use the same underlying deployment ID, so the main subgraph will be instantly synced. + +### My question hasn't been answered, where can I get more help building NEAR subgraphs? + +If it is a general question about subgraph development, there is a lot more information in the rest of the [Developer documentation](/developer/quick-start). Otherwise please join [The Graph Protocol Discord](https://discord.gg/vtvv7FP) and ask in the #near channel, or email near@thegraph.com. + +## References + +- [NEAR developer documentation](https://docs.near.org/docs/develop/basics/getting-started) diff --git a/pages/es/about/introduction.mdx b/pages/es/about/introduction.mdx new file mode 100644 index 000000000000..baa0e542240a --- /dev/null +++ b/pages/es/about/introduction.mdx @@ -0,0 +1,47 @@ +--- +title: Introducción +--- + +En esta página se explica qué es The Graph y cómo puedes empezar a utilizarlo. + +## Qué es The Graph + +The Graph es un protocolo descentralizado para indexar y consultar los datos de las blockchains, empezando por Ethereum. Permite consultar datos que son difíciles de consultar directamente. + +Los proyectos con contratos inteligentes complejos como [Uniswap](https://uniswap.org/) y las iniciativas de NFTs como [Bored Ape Yacht Club](https://boredapeyachtclub.com/) almacenan los datos en la blockchain de Ethereum, lo que hace realmente difícil leer algo más que los datos básicos directamente desde la blockchain. + +En el caso de Bored Ape Yacht Club, podemos realizar operaciones de lectura básicas en [the contract](https://etherscan.io/address/0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d#code) como obtener el propietario de un determinado Ape, obtener el URI de contenido de un Ape con base en su ID, o el supply total, ya que estas operaciones de lectura están programadas directamente en el contrato inteligente, pero no son posibles las consultas y operaciones más avanzadas del mundo real como la agregación, la búsqueda, las relaciones y el filtrado no trivial. Por ejemplo, si quisiéramos consultar los apes que son propiedad de una determinada dirección, y filtrar por una de sus características, no podríamos obtener esa información interactuando directamente con el propio contrato. + +Para obtener estos datos, tendríamos que procesar cada uno de los eventos de [`transfer`](https://etherscan.io/address/0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d#code#L1746) emitidos, leer los metadatos de IPFS utilizando el ID del Token y el hash de IPFS, y luego agregarlos. Incluso para este tipo de preguntas relativamente sencillas, una aplicación descentralizada (dapp) que se ejecutara en un navegador tardaría **horas o incluso días** en obtener una respuesta. + +También podrías construir tu propio servidor, procesar las transacciones allí, guardarlas en una base de datos y construir un endpoint de la API sobre todo ello para consultar los datos. Sin embargo, esta opción requiere recursos intensivos, necesita mantenimiento, presenta un único punto de fallo y rompe importantes propiedades de seguridad necesarias para la descentralización. + +**Indexar los datos de la blockchain es muy, muy difícil.** + +Las propiedades de la blockchain, como la finalidad, las reorganizaciones de la cadena o los bloques sin cerrar, complican aún más este proceso y hacen que no sólo se consuma tiempo, sino que sea conceptualmente difícil recuperar los resultados correctos de las consultas de los datos de la blockchain. + +The Graph resuelve esto con un protocolo descentralizado que indexa y permite la consulta eficiente y de alto rendimiento de los datos de la blockchain. Estas APIs ("subgrafos" indexados) pueden consultarse después con una API GraphQL estándar. Actualmente, existe un servicio alojado (hosted) y un protocolo descentralizado con las mismas capacidades. Ambos están respaldados por la implementación de código abierto de [Graph Node](https://github.com/graphprotocol/graph-node). + +## Cómo Funciona The Graph + +The Graph aprende qué y cómo indexar los datos de Ethereum basándose en las descripciones de los subgrafos, conocidas como el manifiesto de los subgrafos. La descripción del subgrafo define los contratos inteligentes de interés para un subgrafo, los eventos en esos contratos a los que prestar atención, y cómo mapear los datos de los eventos a los datos que The Graph almacenará en su base de datos. + +Una vez que has escrito el `subgraph manifest`, utilizas la CLI de The Graph para almacenar la definición en IPFS y decirle al indexador que empiece a indexar los datos de ese subgrafo. + +Este diagrama ofrece más detalles sobre el flujo de datos una vez que se ha desplegado un manifiesto de subgrafo, que trata de las transacciones de Ethereum: + +![](/img/graph-dataflow.png) + +El flujo sigue estos pasos: + +1. Una aplicación descentralizada añade datos a Ethereum a través de una transacción en un contrato inteligente. +2. El contrato inteligente emite uno o más eventos mientras procesa la transacción. +3. Graph Node escanea continuamente Ethereum en busca de nuevos bloques y los datos de su subgrafo que puedan contener. +4. Graph Node encuentra los eventos de Ethereum para tu subgrafo en estos bloques y ejecuta los mapping handlers que proporcionaste. El mapeo (mapping) es un módulo WASM que crea o actualiza las entidades de datos que Graph Node almacena en respuesta a los eventos de Ethereum. +5. La aplicación descentralizada consulta a Graph Node los datos indexados de la blockchain, utilizando el [GraphQL endpoint](https://graphql.org/learn/) del nodo. El Nodo The Graph, a su vez, traduce las consultas GraphQL en consultas para su almacén de datos subyacente con el fin de obtener estos datos, haciendo uso de las capacidades de indexación del almacén. La aplicación descentralizada muestra estos datos en una rica interfaz de usuario para los usuarios finales, que utilizan para emitir nuevas transacciones en Ethereum. El ciclo se repite. + +## Próximos Pasos + +En las siguientes secciones entraremos en más detalles sobre cómo definir subgrafos, cómo desplegarlos y cómo consultar los datos de los índices que construye Graph Node. + +Antes de que empieces a escribir tu propio subgrafo, puede que quieras echar un vistazo a The Graph Explorer y explorar algunos de los subgrafos que ya han sido desplegados. La página de cada subgrafo contiene un playground que te permite consultar los datos de ese subgrafo con GraphQL. diff --git a/pages/es/about/network.mdx b/pages/es/about/network.mdx new file mode 100644 index 000000000000..316fd3e082f9 --- /dev/null +++ b/pages/es/about/network.mdx @@ -0,0 +1,15 @@ +--- +title: Visión General de la Red +--- + +The Graph Network es un protocolo de indexación descentralizado para organizar los datos de la blockchain. Las aplicaciones utilizan GraphQL para consultar APIs abiertas llamadas subgrafos, para recuperar los datos que están indexados en la red. Con The Graph, los desarrolladores pueden construir aplicaciones sin servidor que se ejecutan completamente en la infraestructura pública. + +> Dirección del token GRT [0xc944e90c64b2c07662a292be6244bdf05cda44a7](https://etherscan.io/token/0xc944e90c64b2c07662a292be6244bdf05cda44a7) + +## Descripción + +The Graph Network está formada por Indexadores, Curadores y Delegadores que proporcionan servicios a la red y sirven datos a las aplicaciones Web3. Los consumidores utilizan las aplicaciones y consumen los datos. + +![Economía de los Tokens](/img/Network-roles@2x.png) + +Para garantizar la seguridad económica de The Graph Network y la integridad de los datos que se consultan, los participantes ponen en staking y utilizan Graph Tokens (GRT). GRT es un token de trabajo que es un ERC-20 en la blockchain de Ethereum, utilizado para asignar recursos en la red. Los Indexadores, Curadores y Delegadores activos pueden prestar servicios y obtener ingresos de la red, proporcionales a la cantidad de trabajo que realizan y a su participación en GRT. diff --git a/pages/es/curating.mdx b/pages/es/curating.mdx index e300cbde2d2a..af50b41b1f19 100644 --- a/pages/es/curating.mdx +++ b/pages/es/curating.mdx @@ -91,7 +91,7 @@ Se sugiere que no actualices tus subgrafos con demasiada frecuencia. Consulta la Las participaciones de un curador no se pueden "comprar" o "vender" como otros tokens ERC20 con los que seguramente estás familiarizado. Solo pueden anclar (crearse) o quemarse (destruirse) a lo largo de la curva de vinculación de un subgrafo en particular. La cantidad de GRT necesaria para generar una nueva señal y la cantidad de GRT que recibes cuando quemas tu señal existente, está determinada por esa curva de vinculación. Como curador, debes saber que cuando quemas tus acciones de curación para retirar GRT, puedes terminar con más o incluso con menos GRT de los que depositaste en un inicio. -Still confused? Check out our Curation video guide below: +Still confused? Still confused? Check out our Curation video guide below:
+>
diff --git a/pages/es/delegating.mdx b/pages/es/delegating.mdx index e92e8cb8a7d0..e4fd24e9169d 100644 --- a/pages/es/delegating.mdx +++ b/pages/es/delegating.mdx @@ -90,5 +90,5 @@ Utilizando está formula, podemos discernir qué un Indexer el cual está ofreci title="Reproductor de video de YouTube" frameBorder="0" allowFullScreen - > +> diff --git a/pages/es/developer/assemblyscript-api.mdx b/pages/es/developer/assemblyscript-api.mdx new file mode 100644 index 000000000000..a609e6cd657f --- /dev/null +++ b/pages/es/developer/assemblyscript-api.mdx @@ -0,0 +1,714 @@ +--- +title: AssemblyScript API +--- + +> Note: if you created a subgraph prior to `graph-cli`/`graph-ts` version `0.22.0`, you're using an older version of AssemblyScript, we recommend taking a look at the [`Migration Guide`](/developer/assemblyscript-migration-guide) + +This page documents what built-in APIs can be used when writing subgraph mappings. Two kinds of APIs are available out of the box: + +- the [Graph TypeScript library](https://github.com/graphprotocol/graph-ts) (`graph-ts`) and +- code generated from subgraph files by `graph codegen`. + +It is also possible to add other libraries as dependencies, as long as they are compatible with [AssemblyScript](https://github.com/AssemblyScript/assemblyscript). Since this is the language mappings are written in, the [AssemblyScript wiki](https://github.com/AssemblyScript/assemblyscript/wiki) is a good source for language and standard library features. + +## Installation + +Subgraphs created with [`graph init`](/developer/create-subgraph-hosted) come with preconfigured dependencies. All that is required to install these dependencies is to run one of the following commands: + +```sh +yarn install # Yarn +npm install # NPM +``` + +If the subgraph was created from scratch, one of the following two commands will install the Graph TypeScript library as a dependency: + +```sh +yarn add --dev @graphprotocol/graph-ts # Yarn +npm install --save-dev @graphprotocol/graph-ts # NPM +``` + +## API Reference + +The `@graphprotocol/graph-ts` library provides the following APIs: + +- An `ethereum` API for working with Ethereum smart contracts, events, blocks, transactions, and Ethereum values. +- A `store` API to load and save entities from and to the Graph Node store. +- A `log` API to log messages to the Graph Node output and the Graph Explorer. +- An `ipfs` API to load files from IPFS. +- A `json` API to parse JSON data. +- A `crypto` API to use cryptographic functions. +- Low-level primitives to translate between different type systems such as Ethereum, JSON, GraphQL and AssemblyScript. + +### Versions + +The `apiVersion` in the subgraph manifest specifies the mapping API version which is run by Graph Node for a given subgraph. The current mapping API version is 0.0.6. + +| Version | Release notes | +|:-------:| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 0.0.6 | Added `nonce` field to the Ethereum Transaction object
Added `baseFeePerGas` to the Ethereum Block object | +| 0.0.5 | AssemblyScript upgraded to version 0.19.10 (this includes breaking changes, please see the [`Migration Guide`](/developer/assemblyscript-migration-guide))
`ethereum.transaction.gasUsed` renamed to `ethereum.transaction.gasLimit` | +| 0.0.4 | Added `functionSignature` field to the Ethereum SmartContractCall object | +| 0.0.3 | Added `from` field to the Ethereum Call object
`etherem.call.address` renamed to `ethereum.call.to` | +| 0.0.2 | Added `input` field to the Ethereum Transaction object | + +### Built-in Types + +Documentation on the base types built into AssemblyScript can be found in the [AssemblyScript wiki](https://github.com/AssemblyScript/assemblyscript/wiki/Types). + +The following additional types are provided by `@graphprotocol/graph-ts`. + +#### ByteArray + +```typescript +import { ByteArray } from '@graphprotocol/graph-ts' +``` + +`ByteArray` represents an array of `u8`. + +_Construction_ + +- `fromI32(x: i32): ByteArray` - Decomposes `x` into bytes. +- `fromHexString(hex: string): ByteArray` - Input length must be even. Prefixing with `0x` is optional. + +_Type conversions_ + +- `toHexString(): string` - Converts to a hex string prefixed with `0x`. +- `toString(): string` - Interprets the bytes as a UTF-8 string. +- `toBase58(): string` - Encodes the bytes into a base58 string. +- `toU32(): u32` - Interprets the bytes as a little-endian `u32`. Throws in case of overflow. +- `toI32(): i32` - Interprets the byte array as a little-endian `i32`. Throws in case of overflow. + +_Operators_ + +- `equals(y: ByteArray): bool` – can be written as `x == y`. + +#### BigDecimal + +```typescript +import { BigDecimal } from '@graphprotocol/graph-ts' +``` + +`BigDecimal` is used to represent arbitrary precision decimals. + +_Construction_ + +- `constructor(bigInt: BigInt)` – creates a `BigDecimal` from an `BigInt`. +- `static fromString(s: string): BigDecimal` – parses from a decimal string. + +_Type conversions_ + +- `toString(): string` – prints to a decimal string. + +_Math_ + +- `plus(y: BigDecimal): BigDecimal` – can be written as `x + y`. +- `minus(y: BigDecimal): BigDecimal` – can be written as `x - y`. +- `times(y: BigDecimal): BigDecimal` – can be written as `x * y`. +- `dividedBy(y: BigDecimal): BigDecimal` – can be written as `x / y`. +- `equals(y: BigDecimal): bool` – can be written as `x == y`. +- `notEqual(y: BigDecimal): bool` – can be written as `x != y`. +- `lt(y: BigDecimal): bool` – can be written as `x < y`. +- `le(y: BigDecimal): bool` – can be written as `x <= y`. +- `gt(y: BigDecimal): bool` – can be written as `x > y`. +- `ge(y: BigDecimal): bool` – can be written as `x >= y`. +- `neg(): BigDecimal` - can be written as `-x`. + +#### BigInt + +```typescript +import { BigInt } from '@graphprotocol/graph-ts' +``` + +`BigInt` is used to represent big integers. This includes Ethereum values of type `uint32` to `uint256` and `int64` to `int256`. Everything below `uint32`, such as `int32`, `uint24` or `int8` is represented as `i32`. + +The `BigInt` class has the following API: + +_Construction_ + +- `BigInt.fromI32(x: i32): BigInt` – creates a `BigInt` from an `i32`. +- `BigInt.fromString(s: string): BigInt`– Parses a `BigInt` from a string. +- `BigInt.fromUnsignedBytes(x: Bytes): BigInt` – Interprets `bytes` as an unsigned, little-endian integer. If your input is big-endian, call `.reverse()` first. +- `BigInt.fromSignedBytes(x: Bytes): BigInt` – Interprets `bytes` as a signed, little-endian integer. If your input is big-endian, call `.reverse()` first. + + _Type conversions_ + +- `x.toHex(): string` – turns `BigInt` into a string of hexadecimal characters. +- `x.toString(): string` – turns `BigInt` into a decimal number string. +- `x.toI32(): i32` – returns the `BigInt` as an `i32`; fails if it the value does not fit into `i32`. It's a good idea to first check `x.isI32()`. +- `x.toBigDecimal(): BigDecimal` - converts into a decimal with no fractional part. + +_Math_ + +- `x.plus(y: BigInt): BigInt` – can be written as `x + y`. +- `x.minus(y: BigInt): BigInt` – can be written as `x - y`. +- `x.times(y: BigInt): BigInt` – can be written as `x * y`. +- `x.dividedBy(y: BigInt): BigInt` – can be written as `x / y`. +- `x.mod(y: BigInt): BigInt` – can be written as `x % y`. +- `x.equals(y: BigInt): bool` – can be written as `x == y`. +- `x.notEqual(y: BigInt): bool` – can be written as `x != y`. +- `x.lt(y: BigInt): bool` – can be written as `x < y`. +- `x.le(y: BigInt): bool` – can be written as `x <= y`. +- `x.gt(y: BigInt): bool` – can be written as `x > y`. +- `x.ge(y: BigInt): bool` – can be written as `x >= y`. +- `x.neg(): BigInt` – can be written as `-x`. +- `x.divDecimal(y: BigDecimal): BigDecimal` – divides by a decimal, giving a decimal result. +- `x.isZero(): bool` – Convenience for checking if the number is zero. +- `x.isI32(): bool` – Check if the number fits in an `i32`. +- `x.abs(): BigInt` – Absolute value. +- `x.pow(exp: u8): BigInt` – Exponentiation. +- `bitOr(x: BigInt, y: BigInt): BigInt` – can be written as `x | y`. +- `bitAnd(x: BigInt, y: BigInt): BigInt` – can be written as `x & y`. +- `leftShift(x: BigInt, bits: u8): BigInt` – can be written as `x << y`. +- `rightShift(x: BigInt, bits: u8): BigInt` – can be written as `x >> y`. + +#### TypedMap + +```typescript +import { TypedMap } from '@graphprotocol/graph-ts' +``` + +`TypedMap` can be used to stored key-value pairs. See [this example](https://github.com/graphprotocol/aragon-subgraph/blob/29dd38680c5e5104d9fdc2f90e740298c67e4a31/individual-dao-subgraph/mappings/constants.ts#L51). + +The `TypedMap` class has the following API: + +- `new TypedMap()` – creates an empty map with keys of type `K` and values of type `T` +- `map.set(key: K, value: V): void` – sets the value of `key` to `value` +- `map.getEntry(key: K): TypedMapEntry | null` – returns the key-value pair for a `key` or `null` if the `key` does not exist in the map +- `map.get(key: K): V | null` – returns the value for a `key` or `null` if the `key` does not exist in the map +- `map.isSet(key: K): bool` – returns `true` if the `key` exists in the map and `false` if it does not + +#### Bytes + +```typescript +import { Bytes } from '@graphprotocol/graph-ts' +``` + +`Bytes` is used to represent arbitrary-length arrays of bytes. This includes Ethereum values of type `bytes`, `bytes32` etc. + +The `Bytes` class extends AssemblyScript's [Uint8Array](https://github.com/AssemblyScript/assemblyscript/blob/3b1852bc376ae799d9ebca888e6413afac7b572f/std/assembly/typedarray.ts#L64) and this supports all the `Uint8Array` functionality, plus the following new methods: + +- `b.toHex()` – returns a hexadecimal string representing the bytes in the array +- `b.toString()` – converts the bytes in the array to a string of unicode characters +- `b.toBase58()` – turns an Ethereum Bytes value to base58 encoding (used for IPFS hashes) + +#### Address + +```typescript +import { Address } from '@graphprotocol/graph-ts' +``` + +`Address` extends `Bytes` to represent Ethereum `address` values. + +It adds the following method on top of the `Bytes` API: + +- `Address.fromString(s: string): Address` – creates an `Address` from a hexadecimal string + +### Store API + +```typescript +import { store } from '@graphprotocol/graph-ts' +``` + +The `store` API allows to load, save and remove entities from and to the Graph Node store. + +Entities written to the store map one-to-one to the `@entity` types defined in the subgraph's GraphQL schema. To make working with these entities convenient, the `graph codegen` command provided by the [Graph CLI](https://github.com/graphprotocol/graph-cli) generates entity classes, which are subclasses of the built-in `Entity` type, with property getters and setters for the fields in the schema as well as methods to load and save these entities. + +#### Creating entities + +The following is a common pattern for creating entities from Ethereum events. + +```typescript +// Import the Transfer event class generated from the ERC20 ABI +import { Transfer as TransferEvent } from '../generated/ERC20/ERC20' + +// Import the Transfer entity type generated from the GraphQL schema +import { Transfer } from '../generated/schema' + +// Transfer event handler +export function handleTransfer(event: TransferEvent): void { + // Create a Transfer entity, using the hexadecimal string representation + // of the transaction hash as the entity ID + let id = event.transaction.hash.toHex() + let transfer = new Transfer(id) + + // Set properties on the entity, using the event parameters + transfer.from = event.params.from + transfer.to = event.params.to + transfer.amount = event.params.amount + + // Save the entity to the store + transfer.save() +} +``` + +When a `Transfer` event is encountered while processing the chain, it is passed to the `handleTransfer` event handler using the generated `Transfer` type (aliased to `TransferEvent` here to avoid a naming conflict with the entity type). This type allows accessing data such as the event's parent transaction and its parameters. + +Each entity must have a unique ID to avoid collisions with other entities. It is fairly common for event parameters to include a unique identifier that can be used. Note: Using the transaction hash as the ID assumes that no other events in the same transaction create entities with this hash as the ID. + +#### Loading entities from the store + +If an entity already exists, it can be loaded from the store with the following: + +```typescript +let id = event.transaction.hash.toHex() // or however the ID is constructed +let transfer = Transfer.load(id) +if (transfer == null) { + transfer = new Transfer(id) +} + +// Use the Transfer entity as before +``` + +As the entity may not exist in the store yet, the `load` method returns a value of type `Transfer | null`. It may thus be necessary to check for the `null` case before using the value. + +> **Note:** Loading entities is only necessary if the changes made in the mapping depend on the previous data of an entity. See the next section for the two ways of updating existing entities. + +#### Updating existing entities + +There are two ways to update an existing entity: + +1. Load the entity with e.g. `Transfer.load(id)`, set properties on the entity, then `.save()` it back to the store. +2. Simply create the entity with e.g. `new Transfer(id)`, set properties on the entity, then `.save()` it to the store. If the entity already exists, the changes are merged into it. + +Changing properties is straight forward in most cases, thanks to the generated property setters: + +```typescript +let transfer = new Transfer(id) +transfer.from = ... +transfer.to = ... +transfer.amount = ... +``` + +It is also possible to unset properties with one of the following two instructions: + +```typescript +transfer.from.unset() +transfer.from = null +``` + +This only works with optional properties, i.e. properties that are declared without a `!` in GraphQL. Two examples would be `owner: Bytes` or `amount: BigInt`. + +Updating array properties is a little more involved, as the getting an array from an entity creates a copy of that array. This means array properties have to be set again explicitly after changing the array. The following assumes `entity` has a `numbers: [BigInt!]!` field. + +```typescript +// This won't work +entity.numbers.push(BigInt.fromI32(1)) +entity.save() + +// This will work +let numbers = entity.numbers +numbers.push(BigInt.fromI32(1)) +entity.numbers = numbers +entity.save() +``` + +#### Removing entities from the store + +There is currently no way to remove an entity via the generated types. Instead, removing an entity requires passing the name of the entity type and the entity ID to `store.remove`: + +```typescript +import { store } from '@graphprotocol/graph-ts' +... +let id = event.transaction.hash.toHex() +store.remove('Transfer', id) +``` + +### Ethereum API + +The Ethereum API provides access to smart contracts, public state variables, contract functions, events, transactions, blocks and the encoding/decoding Ethereum data. + +#### Support for Ethereum Types + +As with entities, `graph codegen` generates classes for all smart contracts and events used in a subgraph. For this, the contract ABIs need to be part of the data source in the subgraph manifest. Typically, the ABI files are stored in an `abis/` folder. + +With the generated classes, conversions between Ethereum types and the [built-in types](#built-in-types) take place behind the scenes so that subgraph authors do not have to worry about them. + +The following example illustrates this. Given a subgraph schema like + +```graphql +type Transfer @entity { + from: Bytes! + to: Bytes! + amount: BigInt! +} +``` + +and a `Transfer(address,address,uint256)` event signature on Ethereum, the `from`, `to` and `amount` values of type `address`, `address` and `uint256` are converted to `Address` and `BigInt`, allowing them to be passed on to the `Bytes!` and `BigInt!` properties of the `Transfer` entity: + +```typescript +let id = event.transaction.hash.toHex() +let transfer = new Transfer(id) +transfer.from = event.params.from +transfer.to = event.params.to +transfer.amount = event.params.amount +transfer.save() +``` + +#### Events and Block/Transaction Data + +Ethereum events passed to event handlers, such as the `Transfer` event in the previous examples, not only provide access to the event parameters but also to their parent transaction and the block they are part of. The following data can be obtained from `event` instances (these classes are a part of the `ethereum` module in `graph-ts`): + +```typescript +class Event { + address: Address + logIndex: BigInt + transactionLogIndex: BigInt + logType: string | null + block: Block + transaction: Transaction + parameters: Array +} + +class Block { + hash: Bytes + parentHash: Bytes + unclesHash: Bytes + author: Address + stateRoot: Bytes + transactionsRoot: Bytes + receiptsRoot: Bytes + number: BigInt + gasUsed: BigInt + gasLimit: BigInt + timestamp: BigInt + difficulty: BigInt + totalDifficulty: BigInt + size: BigInt | null + baseFeePerGas: BigInt | null +} + +class Transaction { + hash: Bytes + index: BigInt + from: Address + to: Address | null + value: BigInt + gasLimit: BigInt + gasPrice: BigInt + input: Bytes + nonce: BigInt +} +``` + +#### Access to Smart Contract State + +The code generated by `graph codegen` also includes classes for the smart contracts used in the subgraph. These can be used to access public state variables and call functions of the contract at the current block. + +A common pattern is to access the contract from which an event originates. This is achieved with the following code: + +```typescript +// Import the generated contract class +import { ERC20Contract } from '../generated/ERC20Contract/ERC20Contract' +// Import the generated entity class +import { Transfer } from '../generated/schema' + +export function handleTransfer(event: Transfer) { + // Bind the contract to the address that emitted the event + let contract = ERC20Contract.bind(event.address) + + // Access state variables and functions by calling them + let erc20Symbol = contract.symbol() +} +``` + +As long as the `ERC20Contract` on Ethereum has a public read-only function called `symbol`, it can be called with `.symbol()`. For public state variables a method with the same name is created automatically. + +Any other contract that is part of the subgraph can be imported from the generated code and can be bound to a valid address. + +#### Handling Reverted Calls + +If the read-only methods of your contract may revert, then you should handle that by calling the generated contract method prefixed with `try_`. For example, the Gravity contract exposes the `gravatarToOwner` method. This code would be able to handle a revert in that method: + +```typescript +let gravity = Gravity.bind(event.address) +let callResult = gravity.try_gravatarToOwner(gravatar) +if (callResult.reverted) { + log.info('getGravatar reverted', []) +} else { + let owner = callResult.value +} +``` + +Note that a Graph node connected to a Geth or Infura client may not detect all reverts, if you rely on this we recommend using a Graph node connected to a Parity client. + +#### Encoding/Decoding ABI + +Data can be encoded and decoded according to Ethereum's ABI encoding format using the `encode` and `decode` functions in the `ethereum` module. + +```typescript +import { Address, BigInt, ethereum } from '@graphprotocol/graph-ts' + +let tupleArray: Array = [ + ethereum.Value.fromAddress(Address.fromString('0x0000000000000000000000000000000000000420')), + ethereum.Value.fromUnsignedBigInt(BigInt.fromI32(62)), +] + +let tuple = tupleArray as ethereum.Tuple + +let encoded = ethereum.encode(ethereum.Value.fromTuple(tuple))! + +let decoded = ethereum.decode('(address,uint256)', encoded) +``` + +For more information: + +- [ABI Spec](https://docs.soliditylang.org/en/v0.7.4/abi-spec.html#types) +- Encoding/decoding [Rust library/CLI](https://github.com/rust-ethereum/ethabi) +- More [complex example](https://github.com/graphprotocol/graph-node/blob/6a7806cc465949ebb9e5b8269eeb763857797efc/tests/integration-tests/host-exports/src/mapping.ts#L72). + +### Logging API + +```typescript +import { log } from '@graphprotocol/graph-ts' +``` + +The `log` API allows subgraphs to log information to the Graph Node standard output as well as the Graph Explorer. Messages can be logged using different log levels. A basic format string syntax is provided to compose log messages from argument. + +The `log` API includes the following functions: + +- `log.debug(fmt: string, args: Array): void` - logs a debug message. +- `log.info(fmt: string, args: Array): void` - logs an informational message. +- `log.warning(fmt: string, args: Array): void` - logs a warning. +- `log.error(fmt: string, args: Array): void` - logs an error message. +- `log.critical(fmt: string, args: Array): void` – logs a critical message _and_ terminates the subgraph. + +The `log` API takes a format string and an array of string values. It then replaces placeholders with the string values from the array. The first `{}` placeholder gets replaced by the first value in the array, the second `{}` placeholder gets replaced by the second value and so on. + +```typescript +log.info('Message to be displayed: {}, {}, {}', [value.toString(), anotherValue.toString(), 'already a string']) +``` + +#### Logging one or more values + +##### Logging a single value + +In the example below, the string value "A" is passed into an array to become`['A']` before being logged: + +```typescript +let myValue = 'A' + +export function handleSomeEvent(event: SomeEvent): void { + // Displays : "My value is: A" + log.info('My value is: {}', [myValue]) +} +``` + +##### Logging a single entry from an existing array + +In the example below, only the first value of the argument array is logged, despite the array containing three values. + +```typescript +let myArray = ['A', 'B', 'C'] + +export function handleSomeEvent(event: SomeEvent): void { + // Displays : "My value is: A" (Even though three values are passed to `log.info`) + log.info('My value is: {}', myArray) +} +``` + +#### Logging multiple entries from an existing array + +Each entry in the arguments array requires its own placeholder `{}` in the log message string. The below example contains three placeholders `{}` in the log message. Because of this, all three values in `myArray` are logged. + +```typescript +let myArray = ['A', 'B', 'C'] + +export function handleSomeEvent(event: SomeEvent): void { + // Displays : "My first value is: A, second value is: B, third value is: C" + log.info('My first value is: {}, second value is: {}, third value is: {}', myArray) +} +``` + +##### Logging a specific entry from an existing array + +To display a specific value in the array, the indexed value must be provided. + +```typescript +export function handleSomeEvent(event: SomeEvent): void { + // Displays : "My third value is C" + log.info('My third value is: {}', [myArray[2]]) +} +``` + +##### Logging event information + +The example below logs the block number, block hash and transaction hash from an event: + +```typescript +import { log } from '@graphprotocol/graph-ts' + +export function handleSomeEvent(event: SomeEvent): void { + log.debug('Block number: {}, block hash: {}, transaction hash: {}', [ + event.block.number.toString(), // "47596000" + event.block.hash.toHexString(), // "0x..." + event.transaction.hash.toHexString(), // "0x..." + ]) +} +``` + +### IPFS API + +```typescript +import { ipfs } from '@graphprotocol/graph-ts' +``` + +Smart contracts occasionally anchor IPFS files on chain. This allows mappings to obtain the IPFS hashes from the contract and read the corresponding files from IPFS. The file data will be returned as `Bytes`, which usually requires further processing, e.g. with the `json` API documented later on this page. + +Given an IPFS hash or path, reading a file from IPFS is done as follows: + +```typescript +// Put this inside an event handler in the mapping +let hash = 'QmTkzDwWqPbnAh5YiV5VwcTLnGdwSNsNTn2aDxdXBFca7D' +let data = ipfs.cat(hash) + +// Paths like `QmTkzDwWqPbnAh5YiV5VwcTLnGdwSNsNTn2aDxdXBFca7D/Makefile` +// that include files in directories are also supported +let path = 'QmTkzDwWqPbnAh5YiV5VwcTLnGdwSNsNTn2aDxdXBFca7D/Makefile' +let data = ipfs.cat(path) +``` + +**Note:** `ipfs.cat` is not deterministic at the moment. If the file cannot be retrieved over the IPFS network before the request times out, it will return `null`. Due to this, it's always worth checking the result for `null`. To ensure that files can be retrieved, they have to be pinned to the IPFS node that Graph Node connects to. On the [hosted service](https://thegraph.com/hosted-service), this is [https://api.thegraph.com/ipfs/](https://api.thegraph.com/ipfs). See the [IPFS pinning](/developer/create-subgraph-hosted#ipfs-pinning) section for more information. + +It is also possible to process larger files in a streaming fashion with `ipfs.map`. The function expects the hash or path for an IPFS file, the name of a callback, and flags to modify its behavior: + +```typescript +import { JSONValue, Value } from '@graphprotocol/graph-ts' + +export function processItem(value: JSONValue, userData: Value): void { + // See the JSONValue documentation for details on dealing + // with JSON values + let obj = value.toObject() + let id = obj.get('id') + let title = obj.get('title') + + if (!id || !title) { + return + } + + // Callbacks can also created entities + let newItem = new Item(id.toString()) + newItem.title = title.toString() + newitem.parent = userData.toString() // Set parent to "parentId" + newitem.save() +} + +// Put this inside an event handler in the mapping +ipfs.map('Qm...', 'processItem', Value.fromString('parentId'), ['json']) + +// Alternatively, use `ipfs.mapJSON` +ipfs.mapJSON('Qm...', 'processItem', Value.fromString('parentId')) +``` + +The only flag currently supported is `json`, which must be passed to `ipfs.map`. With the `json` flag, the IPFS file must consist of a series of JSON values, one value per line. The call to `ipfs.map` will read each line in the file, deserialize it into a `JSONValue` and call the callback for each of them. The callback can then use entity operations to store data from the `JSONValue`. Entity changes are stored only when the handler that called `ipfs.map` finishes successfully; in the meantime, they are kept in memory, and the size of the file that `ipfs.map` can process is therefore limited. + +On success, `ipfs.map` returns `void`. If any invocation of the callback causes an error, the handler that invoked `ipfs.map` is aborted, and the subgraph is marked as failed. + +### Crypto API + +```typescript +import { crypto } from '@graphprotocol/graph-ts' +``` + +The `crypto` API makes a cryptographic functions available for use in mappings. Right now, there is only one: + +- `crypto.keccak256(input: ByteArray): ByteArray` + +### JSON API + +```typescript +import { json, JSONValueKind } from '@graphprotocol/graph-ts' +``` + +JSON data can be parsed using the `json` API: + +- `json.fromBytes(data: Bytes): JSONValue` – parses JSON data from a `Bytes` array +- `json.try_fromBytes(data: Bytes): Result` – safe version of `json.fromBytes`, it returns an error variant if the parsing failed +- `json.fromString(data: Bytes): JSONValue` – parses JSON data from a valid UTF-8 `String` +- `json.try_fromString(data: Bytes): Result` – safe version of `json.fromString`, it returns an error variant if the parsing failed + +The `JSONValue` class provides a way to pull values out of an arbitrary JSON document. Since JSON values can be booleans, numbers, arrays and more, `JSONValue` comes with a `kind` property to check the type of a value: + +```typescript +let value = json.fromBytes(...) +if (value.kind == JSONValueKind.BOOL) { + ... +} +``` + +In addition, there is a method to check if the value is `null`: + +- `value.isNull(): boolean` + +When the type of a value is certain, it can be converted to a [built-in type](#built-in-types) using one of the following methods: + +- `value.toBool(): boolean` +- `value.toI64(): i64` +- `value.toF64(): f64` +- `value.toBigInt(): BigInt` +- `value.toString(): string` +- `value.toArray(): Array` - (and then convert `JSONValue` with one of the 5 methods above) + +### Type Conversions Reference + +| Source(s) | Destination | Conversion function | +| -------------------- | -------------------- | ---------------------------- | +| Address | Bytes | none | +| Address | ID | s.toHexString() | +| Address | String | s.toHexString() | +| BigDecimal | String | s.toString() | +| BigInt | BigDecimal | s.toBigDecimal() | +| BigInt | String (hexadecimal) | s.toHexString() or s.toHex() | +| BigInt | String (unicode) | s.toString() | +| BigInt | i32 | s.toI32() | +| Boolean | Boolean | none | +| Bytes (signed) | BigInt | BigInt.fromSignedBytes(s) | +| Bytes (unsigned) | BigInt | BigInt.fromUnsignedBytes(s) | +| Bytes | String (hexadecimal) | s.toHexString() or s.toHex() | +| Bytes | String (unicode) | s.toString() | +| Bytes | String (base58) | s.toBase58() | +| Bytes | i32 | s.toI32() | +| Bytes | u32 | s.toU32() | +| Bytes | JSON | json.fromBytes(s) | +| int8 | i32 | none | +| int32 | i32 | none | +| int32 | BigInt | Bigint.fromI32(s) | +| uint24 | i32 | none | +| int64 - int256 | BigInt | none | +| uint32 - uint256 | BigInt | none | +| JSON | boolean | s.toBool() | +| JSON | i64 | s.toI64() | +| JSON | u64 | s.toU64() | +| JSON | f64 | s.toF64() | +| JSON | BigInt | s.toBigInt() | +| JSON | string | s.toString() | +| JSON | Array | s.toArray() | +| JSON | Object | s.toObject() | +| String | Address | Address.fromString(s) | +| String | BigDecimal | BigDecimal.fromString(s) | +| String (hexadecimal) | Bytes | ByteArray.fromHexString(s) | +| String (UTF-8) | Bytes | ByteArray.fromUTF8(s) | + +### Data Source Metadata + +You can inspect the contract address, network and context of the data source that invoked the handler through the `dataSource` namespace: + +- `dataSource.address(): Address` +- `dataSource.network(): string` +- `dataSource.context(): DataSourceContext` + +### Entity and DataSourceContext + +The base `Entity` class and the child `DataSourceContext` class have helpers to dynamically set and get fields: + +- `setString(key: string, value: string): void` +- `setI32(key: string, value: i32): void` +- `setBigInt(key: string, value: BigInt): void` +- `setBytes(key: string, value: Bytes): void` +- `setBoolean(key: string, value: bool): void` +- `setBigDecimal(key, value: BigDecimal): void` +- `getString(key: string): string` +- `getI32(key: string): i32` +- `getBigInt(key: string): BigInt` +- `getBytes(key: string): Bytes` +- `getBoolean(key: string): boolean` +- `getBigDecimal(key: string): BigDecimal` diff --git a/pages/es/developer/assemblyscript-migration-guide.mdx b/pages/es/developer/assemblyscript-migration-guide.mdx new file mode 100644 index 000000000000..2db90a608110 --- /dev/null +++ b/pages/es/developer/assemblyscript-migration-guide.mdx @@ -0,0 +1,484 @@ +--- +title: AssemblyScript Migration Guide +--- + +Up until now, subgraphs have been using one of the [first versions of AssemblyScript](https://github.com/AssemblyScript/assemblyscript/tree/v0.6) (v0.6). Finally we've added support for the [newest one available](https://github.com/AssemblyScript/assemblyscript/tree/v0.19.10) (v0.19.10)! 🎉 + +That will enable subgraph developers to use newer features of the AS language and standard library. + +This guide is applicable for anyone using `graph-cli`/`graph-ts` below version `0.22.0`. If you're already at a higher than (or equal) version to that, you've already been using version `0.19.10` of AssemblyScript 🙂 + +> Note: As of `0.24.0`, `graph-node` can support both versions, depending on the `apiVersion` specified in the subgraph manifest. + +## Features + +### New functionality + +- `TypedArray`s can now be built from `ArrayBuffer`s by using the [new `wrap` static method](https://www.assemblyscript.org/stdlib/typedarray.html#static-members) ([v0.8.1](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.8.1)) +- New standard library functions: `String#toUpperCase`, `String#toLowerCase`, `String#localeCompare`and `TypedArray#set` ([v0.9.0](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.9.0)) +- Added support for x instanceof GenericClass ([v0.9.2](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.9.2)) +- Added `StaticArray`, a more efficient array variant ([v0.9.3](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.9.3)) +- Added `Array#flat` ([v0.10.0](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.10.0)) +- Implemented `radix` argument on `Number#toString` ([v0.10.1](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.10.1)) +- Added support for separators in floating point literals ([v0.13.7](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.13.7)) +- Added support for first class functions ([v0.14.0](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.14.0)) +- Add builtins: `i32/i64/f32/f64.add/sub/mul` ([v0.14.13](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.14.13)) +- Implement `Array/TypedArray/String#at` ([v0.18.2](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.18.2)) +- Added support for template literal strings ([v0.18.17](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.18.17)) +- Add `encodeURI(Component)` and `decodeURI(Component)` ([v0.18.27](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.18.27)) +- Add `toString`, `toDateString` and `toTimeString` to `Date` ([v0.18.29](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.18.29)) +- Add `toUTCString` for `Date` ([v0.18.30](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.18.30)) +- Add `nonnull/NonNullable` builtin type ([v0.19.2](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.19.2)) + +### Optimizations + +- `Math` functions such as `exp`, `exp2`, `log`, `log2` and `pow` have been replaced by faster variants ([v0.9.0](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.9.0)) +- Slightly optimize `Math.mod` ([v0.17.1](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.17.1)) +- Cache more field accesses in std Map and Set ([v0.17.8](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.17.8)) +- Optimize for powers of two in `ipow32/64` ([v0.18.2](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.18.2)) + +### Other + +- The type of an array literal can now be inferred from its contents ([v0.9.0](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.9.0)) +- Updated stdlib to Unicode 13.0.0 ([v0.10.0](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.10.0)) + +## How to upgrade? + +1. Change your mappings `apiVersion` in `subgraph.yaml` to `0.0.6`: + +```yaml +... +dataSources: + ... + mapping: + ... + apiVersion: 0.0.6 + ... +``` + +2. Update the `graph-cli` you're using to the `latest` version by running: + +```bash +# if you have it globally installed +npm install --global @graphprotocol/graph-cli@latest + +# or in your subgraph if you have it as a dev dependency +npm install --save-dev @graphprotocol/graph-cli@latest +``` + +3. Do the same for `graph-ts`, but instead of installing globally, save it in your main dependencies: + +```bash +npm install --save @graphprotocol/graph-ts@latest +``` + +4. Follow the rest of the guide to fix the language breaking changes. +5. Run `codegen` and `deploy` again. + +## Breaking changes + +### Nullability + +On the older version of AssemblyScript, you could create code like this: + +```typescript +function load(): Value | null { ... } + +let maybeValue = load(); +maybeValue.aMethod(); +``` + +However on the newer version, because the value is nullable, it requires you to check, like this: + +```typescript +let maybeValue = load() + +if (maybeValue) { + maybeValue.aMethod() // `maybeValue` is not null anymore +} +``` + +Or force it like this: + +```typescript +let maybeValue = load()! // breaks in runtime if value is null + +maybeValue.aMethod() +``` + +If you are unsure which to choose, we recommend always using the safe version. If the value doesn't exist you might want to just do an early if statement with a return in you subgraph handler. + +### Variable Shadowing + +Before you could do [variable shadowing](https://en.wikipedia.org/wiki/Variable_shadowing) and code like this would work: + +```typescript +let a = 10 +let b = 20 +let a = a + b +``` + +However now this isn't possible anymore, and the compiler returns this error: + +```typescript +ERROR TS2451: Cannot redeclare block-scoped variable 'a' + + let a = a + b; + ~~~~~~~~~~~~~ +in assembly/index.ts(4,3) +``` +You'll need to rename your duplicate variables if you had variable shadowing. +### Null Comparisons +By doing the upgrade on your subgraph, sometimes you might get errors like these: + +```typescript +ERROR TS2322: Type '~lib/@graphprotocol/graph-ts/common/numbers/BigInt | null' is not assignable to type '~lib/@graphprotocol/graph-ts/common/numbers/BigInt'. + if (decimals == null) { + ~~~~ + in src/mappings/file.ts(41,21) +``` +To solve you can simply change the `if` statement to something like this: + +```typescript + if (!decimals) { + + // or + + if (decimals === null) { +``` + +The same applies if you're doing != instead of ==. + +### Casting + +The common way to do casting before was to just use the `as` keyword, like this: + +```typescript +let byteArray = new ByteArray(10) +let uint8Array = byteArray as Uint8Array // equivalent to: byteArray +``` + +However this only works in two scenarios: + +- Primitive casting (between types such as `u8`, `i32`, `bool`; eg: `let b: isize = 10; b as usize`); +- Upcasting on class inheritance (subclass → superclass) + +Examples: + +```typescript +// primitive casting +let a: usize = 10 +let b: isize = 5 +let c: usize = a + (b as usize) +``` + +```typescript +// upcasting on class inheritance +class Bytes extends Uint8Array {} + +let bytes = new Bytes(2) < Uint8Array > bytes // same as: bytes as Uint8Array +``` + +There are two scenarios where you may want to cast, but using `as`/`var` **isn't safe**: + +- Downcasting on class inheritance (superclass → subclass) +- Between two types that share a superclass + +```typescript +// downcasting on class inheritance +class Bytes extends Uint8Array {} + +let uint8Array = new Uint8Array(2) < Bytes > uint8Array // breaks in runtime :( +``` + +```typescript +// between two types that share a superclass +class Bytes extends Uint8Array {} +class ByteArray extends Uint8Array {} + +let bytes = new Bytes(2) < ByteArray > bytes // breaks in runtime :( +``` + +For those cases, you can use the `changetype` function: + +```typescript +// downcasting on class inheritance +class Bytes extends Uint8Array {} + +let uint8Array = new Uint8Array(2) +changetype(uint8Array) // works :) +``` + +```typescript +// between two types that share a superclass +class Bytes extends Uint8Array {} +class ByteArray extends Uint8Array {} + +let bytes = new Bytes(2) +changetype(bytes) // works :) +``` + +If you just want to remove nullability, you can keep using the `as` operator (or `variable`), but make sure you know that value can't be null, otherwise it will break. + +```typescript +// remove nullability +let previousBalance = AccountBalance.load(balanceId) // AccountBalance | null + +if (previousBalance != null) { + return previousBalance as AccountBalance // safe remove null +} + +let newBalance = new AccountBalance(balanceId) +``` + +For the nullability case we recommend taking a look at the [nullability check feature](https://www.assemblyscript.org/basics.html#nullability-checks), it will make your code cleaner 🙂 + +Also we've added a few more static methods in some types to ease casting, they are: + +- Bytes.fromByteArray +- Bytes.fromUint8Array +- BigInt.fromByteArray +- ByteArray.fromBigInt + +### Nullability check with property access + +To use the [nullability check feature](https://www.assemblyscript.org/basics.html#nullability-checks) you can use either `if` statements or the ternary operator (`?` and `:`) like this: + +```typescript +let something: string | null = 'data' + +let somethingOrElse = something ? something : 'else' + +// or + +let somethingOrElse + +if (something) { + somethingOrElse = something +} else { + somethingOrElse = 'else' +} +``` + +However that only works when you're doing the `if` / ternary on a variable, not on a property access, like this: + +```typescript +class Container { + data: string | null +} + +let container = new Container() +container.data = 'data' + +let somethingOrElse: string = container.data ? container.data : 'else' // doesn't compile +``` + +Which outputs this error: + +```typescript +ERROR TS2322: Type '~lib/string/String | null' is not assignable to type '~lib/string/String'. + + let somethingOrElse: string = container.data ? container.data : "else"; + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +``` +To fix this issue, you can create a variable for that property access so that the compiler can do the nullability check magic: + +```typescript +class Container { + data: string | null +} + +let container = new Container() +container.data = 'data' + +let data = container.data + +let somethingOrElse: string = data ? data : 'else' // compiles just fine :) +``` + +### Operator overloading with property access + +If you try to sum (for example) a nullable type (from a property access) with a non nullable one, the AssemblyScript compiler instead of giving a compile time error warning that one of the values is nullable, it just compiles silently, giving chance for the code to break at runtime. + +```typescript +class BigInt extends Uint8Array { + @operator('+') + plus(other: BigInt): BigInt { + // ... + } +} + +class Wrapper { + public constructor(public n: BigInt | null) {} +} + +let x = BigInt.fromI32(2) +let y: BigInt | null = null + +x + y // give compile time error about nullability + +let wrapper = new Wrapper(y) + +wrapper.n = wrapper.n + x // doesn't give compile time errors as it should +``` + +We've opened a issue on the AssemblyScript compiler for this, but for now if you do these kind of operations in your subgraph mappings, you should change them to do a null check before it. + +```typescript +let wrapper = new Wrapper(y) + +if (!wrapper.n) { + wrapper.n = BigInt.fromI32(0) +} + +wrapper.n = wrapper.n + x // now `n` is guaranteed to be a BigInt +``` + +### Value initialization + +If you have any code like this: + +```typescript +var value: Type // null +value.x = 10 +value.y = 'content' +``` + +It will compile but break at runtime, that happens because the value hasn't been initialized, so make sure your subgraph has initialized their values, like this: + +```typescript +var value = new Type() // initialized +value.x = 10 +value.y = 'content' +``` + +Also if you have nullable properties in a GraphQL entity, like this: + +```graphql +type Total @entity { + id: ID! + amount: BigInt +} +``` + +And you have code similar to this: + +```typescript +let total = Total.load('latest') + +if (total === null) { + total = new Total('latest') +} + +total.amount = total.amount + BigInt.fromI32(1) +``` + +You'll need to make sure to initialize the `total.amount` value, because if you try to access like in the last line for the sum, it will crash. So you either initialize it first: + +```typescript +let total = Total.load('latest') + +if (total === null) { + total = new Total('latest') + total.amount = BigInt.fromI32(0) +} + +total.tokens = total.tokens + BigInt.fromI32(1) +``` + +Or you can just change your GraphQL schema to not use a nullable type for this property, then we'll initialize it as zero on the `codegen` step 😉 + +```graphql +type Total @entity { + id: ID! + amount: BigInt! +} +``` + +```typescript +let total = Total.load('latest') + +if (total === null) { + total = new Total('latest') // already initializes non-nullable properties +} + +total.amount = total.amount + BigInt.fromI32(1) +``` + +### Class property initialization + +If you export any classes with properties that are other classes (declared by you or by the standard library) like this: + +```typescript +class Thing {} + +export class Something { + value: Thing +} +``` + +The compiler will error because you either need to add an initializer for the properties that are classes, or add the `!` operator: + +```typescript +export class Something { + constructor(public value: Thing) {} +} + +// or + +export class Something { + value: Thing + + constructor(value: Thing) { + this.value = value + } +} + +// or + +export class Something { + value!: Thing +} +``` + +### GraphQL schema + +This is not a direct AssemblyScript change, but you may have to update your `schema.graphql` file. + +Now you no longer can define fields in your types that are Non-Nullable Lists. If you have a schema like this: + +```graphql +type Something @entity { + id: ID! +} + +type MyEntity @entity { + id: ID! + invalidField: [Something]! # no longer valid +} +``` + +You'll have to add an `!` to the member of the List type, like this: + +```graphql +type Something @entity { + id: ID! +} + +type MyEntity @entity { + id: ID! + invalidField: [Something!]! # valid +} +``` + +This changed because of nullability differences between AssemblyScript versions, and it's related to the `src/generated/schema.ts` file (default path, you might have changed this). + +### Other + +- Aligned `Map#set` and `Set#add` with the spec, returning `this` ([v0.9.2](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.9.2)) +- Arrays no longer inherit from ArrayBufferView, but are now distinct ([v0.10.0](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.10.0)) +- Classes initialized from object literals can no longer define a constructor ([v0.10.0](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.10.0)) +- The result of a `**` binary operation is now the common denominator integer if both operands are integers. Previously, the result was a float as if calling `Math/f.pow` ([v0.11.0](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.11.0)) +- Coerce `NaN` to `false` when casting to `bool` ([v0.14.9](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.14.9)) +- When shifting a small integer value of type `i8`/`u8` or `i16`/`u16`, only the 3 respectively 4 least significant bits of the RHS value affect the result, analogous to the result of an `i32.shl` only being affected by the 5 least significant bits of the RHS value. Example: `someI8 << 8` previously produced the value `0`, but now produces `someI8` due to masking the RHS as `8 & 7 = 0` (3 bits) ([v0.17.0](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.17.0)) +- Bug fix of relational string comparisons when sizes differ ([v0.17.8](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.17.8)) diff --git a/pages/es/developer/create-subgraph-hosted.mdx b/pages/es/developer/create-subgraph-hosted.mdx new file mode 100644 index 000000000000..6b235e379634 --- /dev/null +++ b/pages/es/developer/create-subgraph-hosted.mdx @@ -0,0 +1,928 @@ +--- +title: Create a Subgraph +--- + +Before being able to use the Graph CLI, you need to create your subgraph in [Subgraph Studio](https://thegraph.com/studio). You will then be able to setup your subgraph project and deploy it to the platform of your choice. Note that **subgraphs that do not index Ethereum mainnet will not be published to The Graph Network**. + +The `graph init` command can be used to set up a new subgraph project, either from an existing contract on any of the public Ethereum networks, or from an example subgraph. This command can be used to create a subgraph on the Subgraph Studio by passing in `graph init --product subgraph-studio`. If you already have a smart contract deployed to Ethereum mainnet or one of the testnets, bootstrapping a new subgraph from that contract can be a good way to get started. But first, a little about the networks The Graph supports. + +## Supported Networks + +The Graph Network supports subgraphs indexing mainnet Ethereum: + +- `mainnet` + +**Additional Networks are supported in beta on the Hosted Service**: + +- `mainnet` +- `kovan` +- `rinkeby` +- `ropsten` +- `goerli` +- `poa-core` +- `poa-sokol` +- `xdai` +- `near-mainnet` +- `near-testnet` +- `matic` +- `mumbai` +- `fantom` +- `bsc` +- `chapel` +- `clover` +- `avalanche` +- `fuji` +- `celo` +- `celo-alfajores` +- `fuse` +- `moonriver` +- `mbase` +- `arbitrum-one` +- `arbitrum-rinkeby` +- `optimism` +- `optimism-kovan` +- `aurora` +- `aurora-testnet` + +The Graph's Hosted Service relies on the stability and reliability of the underlying technologies, namely the provided JSON RPC endpoints. Newer networks will be marked as being in beta until the network has proven itself in terms of stability, reliability, and scalability. During this beta period, there is risk of downtime and unexpected behaviour. + +Remember that you will **not be able** to publish a subgraph that indexes a non-mainnet network to the decentralized Graph Network in [Subgraph Studio](/studio/subgraph-studio). + +## From An Existing Contract + +The following command creates a subgraph that indexes all events of an existing contract. It attempts to fetch the contract ABI from Etherscan and falls back to requesting a local file path. If any of the optional arguments are missing, it takes you through an interactive form. + +```sh +graph init \ + --product subgraph-studio + --from-contract \ + [--network ] \ + [--abi ] \ + [] +``` + +The `` is the ID of your subgraph in Subgraph Studio, it can be found on your subgraph details page. + +## From An Example Subgraph + +The second mode `graph init` supports is creating a new project from an example subgraph. The following command does this: + +``` +graph init --studio +``` + +The example subgraph is based on the Gravity contract by Dani Grant that manages user avatars and emits `NewGravatar` or `UpdateGravatar` events whenever avatars are created or updated. The subgraph handles these events by writing `Gravatar` entities to the Graph Node store and ensuring these are updated according to the events. The following sections will go over the files that make up the subgraph manifest for this example. + +## The Subgraph Manifest + +The subgraph manifest `subgraph.yaml` defines the smart contracts your subgraph indexes, which 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 full specification for subgraph manifests can be found [here](https://github.com/graphprotocol/graph-node/blob/master/docs/subgraph-manifest.md). + +For the example subgraph, `subgraph.yaml` is: + +```yaml +specVersion: 0.0.4 +description: Gravatar for Ethereum +repository: https://github.com/graphprotocol/example-subgraph +schema: + file: ./schema.graphql +dataSources: + - kind: ethereum/contract + name: Gravity + network: mainnet + source: + address: '0x2E645469f354BB4F5c8a05B3b30A929361cf77eC' + abi: Gravity + startBlock: 6175244 + mapping: + kind: ethereum/events + apiVersion: 0.0.6 + language: wasm/assemblyscript + entities: + - Gravatar + abis: + - name: Gravity + file: ./abis/Gravity.json + eventHandlers: + - event: NewGravatar(uint256,address,string,string) + handler: handleNewGravatar + - event: UpdatedGravatar(uint256,address,string,string) + handler: handleUpdatedGravatar + callHandlers: + - function: createGravatar(string,string) + handler: handleCreateGravatar + blockHandlers: + - function: handleBlock + - function: handleBlockWithCall + filter: + kind: call + file: ./src/mapping.ts +``` + +The important entries to update for the manifest are: + +- `description`: a human-readable description of what the subgraph is. This description is displayed by the Graph Explorer when the subgraph is deployed to the Hosted Service. + +- `repository`: the URL of the repository where the subgraph manifest can be found. This is also displayed by the Graph Explorer. + +- `features`: a list of all used [feature](#experimental-features) names. + +- `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.mapping.entities`: the entities that the data source writes to the store. The schema for each entity is defined in the 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 filter can be provided with the following kinds: call`. A`call` filter will 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. + +The triggers for a data source within a block are ordered using the following process: + +1. Event and call triggers are first ordered by transaction index within the block. +2. Event and call triggers with in the same transaction are ordered using a convention: event triggers first then call triggers, each type respecting the order they are defined in the manifest. +3. Block triggers are run after event and call triggers, in the order they are defined in the manifest. + +These ordering rules are subject to change. + +### Getting The ABIs + +The ABI file(s) must match your contract(s). There are a few ways to obtain ABI files: + +- If you are building your own project, you will likely have access to your most current ABIs. +- If you are building a subgraph for a public project, you can download that project to your computer and get the ABI by using [`truffle compile`](https://truffleframework.com/docs/truffle/overview) or using solc to compile. +- You can also find the ABI on [Etherscan](https://etherscan.io/), but this isn't always reliable, as the ABI that is uploaded there may be out of date. Make sure you have the right ABI, otherwise running your subgraph will fail. + +## The GraphQL Schema + +The schema for your subgraph is in the file `schema.graphql`. GraphQL schemas are defined using the GraphQL interface definition language. If you've never written a GraphQL schema, it is recommended that you check out this primer on the GraphQL type system. Reference documentation for GraphQL schemas can be found in the [GraphQL API](/developer/graphql-api) section. + +## Defining Entities + +Before defining entities, it is important to take a step back and think about how your data is structured and linked. All queries will be made against the data model defined in the subgraph schema and the entities indexed by the subgraph. Because of this, it is good to define the subgraph schema in a way that matches the needs of your dapp. It may be useful to imagine entities as "objects containing data", rather than as events or functions. + +With The Graph, you simply define entity types in `schema.graphql`, and Graph Node will generate top level fields for querying single instances and collections of that entity type. Each type that should be an entity is required to be annotated with an `@entity` directive. + +### Good Example + +The `Gravatar` entity below is structured around a Gravatar object and is a good example of how an entity could be defined. + +```graphql +type Gravatar @entity { + id: ID! + owner: Bytes + displayName: String + imageUrl: String + accepted: Boolean +} +``` + +### Bad Example + +The example `GravatarAccepted` and `GravatarDeclined` entities below are based around events. It is not recommended to map events or function calls to entities 1:1. + +```graphql +type GravatarAccepted @entity { + id: ID! + owner: Bytes + displayName: String + imageUrl: String +} + +type GravatarDeclined @entity { + id: ID! + owner: Bytes + displayName: String + imageUrl: String +} +``` + +### Optional and Required Fields + +Entity fields can be defined as required or optional. Required fields are indicated by the `!` in the schema. If a required field is not set in the mapping, you will receive this error when querying the field: + +``` +Null value resolved for non-null field 'name' +``` + +Each entity must have an `id` field, which is of type `ID!` (string). The `id` field serves as the primary key, and needs to be unique among all entities of the same type. + +### Built-In Scalar Types + +#### GraphQL Supported Scalars + +We support the following scalars in our GraphQL API: + +| Type | Description | +| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `Bytes` | Byte array, represented as a hexadecimal string. Commonly used for Ethereum hashes and addresses. | +| `ID` | Stored as a `string`. | +| `String` | Scalar for `string` values. Null characters are not supported and are automatically removed. | +| `Boolean` | Scalar for `boolean` values. | +| `Int` | The GraphQL spec defines `Int` to have size of 32 bytes. | +| `BigInt` | Large integers. Used for Ethereum's `uint32`, `int64`, `uint64`, ..., `uint256` types. Note: Everything below `uint32`, such as `int32`, `uint24` or `int8` is represented as `i32`. | +| `BigDecimal` | `BigDecimal` High precision decimals represented as a signficand and an exponent. The exponent range is from −6143 to +6144. Rounded to 34 significant digits. | + +#### Enums + +You can also create enums within a schema. Enums have the following syntax: + +```graphql +enum TokenStatus { + OriginalOwner + SecondOwner + ThirdOwner +} +``` + +Once the enum is defined in the schema, you can use the string representation of the enum value to set an enum field on an entity. For example, you can set the `tokenStatus` to `SecondOwner` by first defining your entity and subsequently setting the field with `entity.tokenStatus = "SecondOwner`. The example below demonstrates what the Token entity would look like with an enum field: + +More detail on writing enums can be found in the [GraphQL documentation](https://graphql.org/learn/schema/). + +#### Entity Relationships + +An entity may have a relationship to one or more other entities in your schema. These relationships may be traversed in your queries. Relationships in The Graph are unidirectional. It is possible to simulate bidirectional relationships by defining a unidirectional relationship on either "end" of the relationship. + +Relationships are defined on entities just like any other field except that the type specified is that of another entity. + +#### One-To-One Relationships + +Define a `Transaction` entity type with an optional one-to-one relationship with a `TransactionReceipt` entity type: + +```graphql +type Transaction @entity { + id: ID! + transactionReceipt: TransactionReceipt +} + +type TransactionReceipt @entity { + id: ID! + transaction: Transaction +} +``` + +#### One-To-Many Relationships + +Define a `TokenBalance` entity type with a required one-to-many relationship with a Token entity type: + +```graphql +type Token @entity { + id: ID! +} + +type TokenBalance @entity { + id: ID! + amount: Int! + token: Token! +} +``` + +#### Reverse Lookups + +Reverse lookups can be defined on an entity through the `@derivedFrom` field. This creates a virtual field on the entity that may be queried but cannot be set manually through the mappings API. Rather, it is derived from the relationship defined on the other entity. For such relationships, it rarely makes sense to store both sides of the relationship, and both indexing and query performance will be better when only one side is stored and the other is derived. + +For one-to-many relationships, the relationship should always be stored on the 'one' side, and the 'many' side should always be derived. Storing the relationship this way, rather than storing an array of entities on the 'many' side, will result in dramatically better performance for both indexing and querying the subgraph. In general, storing arrays of entities should be avoided as much as is practical. + +#### Example + +We can make the balances for a token accessible from the token by deriving a `tokenBalances` field: + +```graphql +type Token @entity { + id: ID! + tokenBalances: [TokenBalance!]! @derivedFrom(field: "token") +} + +type TokenBalance @entity { + id: ID! + amount: Int! + token: Token! +} +``` + +#### Many-To-Many Relationships + +For many-to-many relationships, such as users that each may belong to any number of organizations, the most straightforward, but generally not the most performant, way to model the relationship is as an array in each of the two entities involved. If the relationship is symmetric, only one side of the relationship needs to be stored and the other side can be derived. + +#### Example + +Define a reverse lookup from a `User` entity type to an `Organization` entity type. In the example below, this is achieved by looking up the `members` attribute from within the `Organization` entity. In queries, the `organizations` field on `User` will be resolved by finding all `Organization` entities that include the user's ID. + +```graphql +type Organization @entity { + id: ID! + name: String! + members: [User!]! +} + +type User @entity { + id: ID! + name: String! + organizations: [Organization!]! @derivedFrom(field: "members") +} +``` + +A more performant way to store this relationship is through a mapping table that has one entry for each `User` / `Organization` pair with a schema like + +```graphql +type Organization @entity { + id: ID! + name: String! + members: [UserOrganization]! @derivedFrom(field: "user") +} + +type User @entity { + id: ID! + name: String! + organizations: [UserOrganization!] @derivedFrom(field: "organization") +} + +type UserOrganization @entity { + id: ID! # Set to `${user.id}-${organization.id}` + user: User! + organization: Organization! +} +``` + +This approach requires that queries descend into one additional level to retrieve, for example, the organizations for users: + +```graphql +query usersWithOrganizations { + users { + organizations { + # this is a UserOrganization entity + organization { + name + } + } + } +} +``` + +This more elaborate way of storing many-to-many relationships will result in less data stored for the subgraph, and therefore to a subgraph that is often dramatically faster to index and to query. + +#### Adding comments to the schema + +As per GraphQL spec, comments can be added above schema entity attributes using double quotations `""`. This is illustrated in the example below: + +```graphql +type MyFirstEntity @entity { + "unique identifier and primary key of the entity" + id: ID! + address: Bytes! +} +``` + +## Defining Fulltext Search Fields + +Fulltext search queries filter and rank entities based on a text search input. Fulltext queries are able to return matches for similar words by processing the query text input into stems before comparing to the indexed text data. + +A fulltext query definition includes the query name, the language dictionary used to process the text fields, the ranking algorithm used to order the results, and the fields included in the search. Each fulltext query may span multiple fields, but all included fields must be from a single entity type. + +To add a fulltext query, include a `_Schema_` type with a fulltext directive in the GraphQL schema. + +```graphql +type _Schema_ + @fulltext( + name: "bandSearch" + language: en + algorithm: rank + include: [{ entity: "Band", fields: [{ name: "name" }, { name: "description" }, { name: "bio" }] }] + ) + +type Band @entity { + id: ID! + name: String! + description: String! + bio: String + wallet: Address + labels: [Label!]! + discography: [Album!]! + members: [Musician!]! +} +``` + +The example `bandSearch` field can be used in queries to filter `Band` entities based on the text documents in the `name`, `description`, and `bio` fields. Jump to [GraphQL API - Queries](/developer/graphql-api#queries) for a description of the Fulltext search API and for more example usage. + +```graphql +query { + bandSearch(text: "breaks & electro & detroit") { + id + name + description + wallet + } +} +``` + +> **[Feature Management](#experimental-features):** From `specVersion` `0.0.4` and onwards, `fullTextSearch` must be declared under the `features` section in the subgraph manifest. + +### Languages supported + +Choosing a different language will have a definitive, though sometimes subtle, effect on the fulltext search API. Fields covered by a fulltext query field are examined in the context of the chosen language, so the lexemes produced by analysis and search queries vary language to language. For example: when using the supported Turkish dictionary "token" is stemmed to "toke" while, of course, the English dictionary will stem it to "token". + +Supported language dictionaries: + +| Code | Dictionary | +| ------ | ---------- | +| simple | General | +| da | Danish | +| nl | Dutch | +| en | English | +| fi | Finnish | +| fr | French | +| de | German | +| hu | Hungarian | +| it | Italian | +| no | Norwegian | +| pt | Portugese | +| ro | Romanian | +| ru | Russian | +| es | Spanish | +| sv | Swedish | +| tr | Turkish | + +### Ranking Algorithms + +Supported algorithms for ordering results: + +| Algorithm | Description | +| ------------- | ----------------------------------------------------------------------- | +| rank | Use the match quality (0-1) of the fulltext query to order the results. | +| proximityRank | Similar to rank but also includes the proximity of the matches. | + +## Writing Mappings + +The mappings transform the Ethereum data your mappings are sourcing into entities defined in your schema. Mappings are written in a subset of [TypeScript](https://www.typescriptlang.org/docs/handbook/typescript-in-5-minutes.html) called [AssemblyScript](https://github.com/AssemblyScript/assemblyscript/wiki) which can be compiled to WASM ([WebAssembly](https://webassembly.org/)). AssemblyScript is stricter than normal TypeScript, yet provides a familiar syntax. + +For each event handler that is defined in `subgraph.yaml` under `mapping.eventHandlers`, create an exported function of the same name. Each handler must accept a single parameter called `event` with a type corresponding to the name of the event which is being handled. + +In the example subgraph, `src/mapping.ts` contains handlers for the `NewGravatar` and `UpdatedGravatar` events: + +```javascript +import { NewGravatar, UpdatedGravatar } from '../generated/Gravity/Gravity' +import { Gravatar } from '../generated/schema' + +export function handleNewGravatar(event: NewGravatar): void { + let gravatar = new Gravatar(event.params.id.toHex()) + gravatar.owner = event.params.owner + gravatar.displayName = event.params.displayName + gravatar.imageUrl = event.params.imageUrl + gravatar.save() +} + +export function handleUpdatedGravatar(event: UpdatedGravatar): void { + let id = event.params.id.toHex() + let gravatar = Gravatar.load(id) + if (gravatar == null) { + gravatar = new Gravatar(id) + } + gravatar.owner = event.params.owner + gravatar.displayName = event.params.displayName + gravatar.imageUrl = event.params.imageUrl + gravatar.save() +} +``` + +The first handler takes a `NewGravatar` event and creates a new `Gravatar` entity with `new Gravatar(event.params.id.toHex())`, populating the entity fields using the corresponding event parameters. This entity instance is represented by the variable `gravatar`, with an id value of `event.params.id.toHex()`. + +The second handler tries to load the existing `Gravatar` from the Graph Node store. If it does not exist yet, it is created on demand. The entity is then updated to match the new event parameters, before it is saved back to the store using `gravatar.save()`. + +### Recommended IDs for Creating New Entities + +Every entity has to have an `id` that is unique among all entities of the same type. An entity's `id` value is set when the entity is created. Below are some recommended `id` values to consider when creating new entities. NOTE: The value of `id` must be a `string`. + +- `event.params.id.toHex()` +- `event.transaction.from.toHex()` +- `event.transaction.hash.toHex() + "-" + event.logIndex.toString()` + +We provide the [Graph Typescript Library](https://github.com/graphprotocol/graph-ts) which contains utilies for interacting with the Graph Node store and conveniences for handling smart contract data and entities. You can use this library in your mappings by importing `@graphprotocol/graph-ts` in `mapping.ts`. + +## Code Generation + +In order to make working smart contracts, events and entities easy and type-safe, the Graph CLI can generate AssemblyScript types from the subgraph's GraphQL schema and the contract ABIs included in the data sources. + +This is done with + +```sh +graph codegen [--output-dir ] [] +``` + +but in most cases, subgraphs are already preconfigured via `package.json` to allow you to simply run one of the following to achieve the same: + +```sh +# Yarn +yarn codegen + +# NPM +npm run codegen +``` + +This will generate an AssemblyScript class for every smart contract in the ABI files mentioned in `subgraph.yaml`, allowing you to bind these contracts to specific addresses in the mappings and call read-only contract methods against the block being processed. It will also generate a class for every contract event to provide easy access to event parameters as well as the block and transaction the event originated from. All of these types are written to `//.ts`. In the example subgraph, this would be `generated/Gravity/Gravity.ts`, allowing mappings to import these types with + +```javascript +import { + // The contract class: + Gravity, + // The events classes: + NewGravatar, + UpdatedGravatar, +} from '../generated/Gravity/Gravity' +``` + +In addition to this, one class is generated for each entity type in the subgraph's GraphQL schema. These classes provide type-safe entity loading, read and write access to entity fields as well as a `save()` method to write entities to store. All entity classes are written to `/schema.ts`, allowing mappings to import them with + +```javascript +import { Gravatar } from '../generated/schema' +``` + +> **Note:** The code generation must be performed again after every change to the GraphQL schema or the ABIs included in the manifest. It must also be performed at least once before building or deploying the subgraph. + +Code generation does not check your mapping code in `src/mapping.ts`. If you want to check that before trying to deploy your subgraph to the Graph Explorer, you can run `yarn build` and fix any syntax errors that the TypeScript compiler might find. + +## Data Source Templates + +A common pattern in Ethereum smart contracts is the use of registry or factory contracts, where one contract creates, manages or references an arbitrary number of other contracts that each have their own state and events. 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_. + +### Data Source for the Main Contract + +First, you define a regular data source for the main contract. The snippet below shows a simplified example data source for the [Uniswap](https://uniswap.io) exchange factory contract. Note the `NewExchange(address,address)` event handler. This is emitted when a new exchange contract is created on chain by the factory contract. + +```yaml +dataSources: + - kind: ethereum/contract + name: Factory + network: mainnet + source: + address: '0xc0a47dFe034B400B47bDaD5FecDa2621de6c4d95' + abi: Factory + mapping: + kind: ethereum/events + apiVersion: 0.0.6 + language: wasm/assemblyscript + file: ./src/mappings/factory.ts + entities: + - Directory + abis: + - name: Factory + file: ./abis/factory.json + eventHandlers: + - event: NewExchange(address,address) + handler: handleNewExchange +``` + +### Data Source Templates for Dynamically Created Contracts + +Then, you add _data source templates_ to the manifest. These are identical to regular data sources, except that they lack a predefined contract address under `source`. Typically, you would define one template for each type of sub-contract managed or referenced by the parent contract. + +```yaml +dataSources: + - kind: ethereum/contract + name: Factory + # ... other source fields for the main contract ... +templates: + - name: Exchange + kind: ethereum/contract + network: mainnet + source: + abi: Exchange + mapping: + kind: ethereum/events + apiVersion: 0.0.6 + language: wasm/assemblyscript + file: ./src/mappings/exchange.ts + entities: + - Exchange + abis: + - name: Exchange + file: ./abis/exchange.json + eventHandlers: + - event: TokenPurchase(address,uint256,uint256) + handler: handleTokenPurchase + - event: EthPurchase(address,uint256,uint256) + handler: handleEthPurchase + - event: AddLiquidity(address,uint256,uint256) + handler: handleAddLiquidity + - event: RemoveLiquidity(address,uint256,uint256) + handler: handleRemoveLiquidity +``` + +### Instantiating a Data Source Template + +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. + +```typescript +import { Exchange } from '../generated/templates' + +export function handleNewExchange(event: NewExchange): void { + // Start indexing the exchange; `event.params.exchange` is the + // address of the new exchange contract + Exchange.create(event.params.exchange) +} +``` + +> **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. +> +> If prior blocks contain data relevant to the new data source, it is best to index that data by reading the current state of the contract and creating entities representing that state at the time the new data source is created. + +### Data Source Context + +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: + +```typescript +import { Exchange } from '../generated/templates' + +export function handleNewExchange(event: NewExchange): void { + let context = new DataSourceContext() + context.setString('tradingPair', event.params.tradingPair) + Exchange.createWithContext(event.params.exchange, context) +} +``` + +Inside a mapping of the `Exchange` template, the context can then be accessed: + +```typescript +import { dataSource } from '@graphprotocol/graph-ts' + +let context = dataSource.context() +let tradingPair = context.getString('tradingPair') +``` + +There are setters and getters like `setString` and `getString` for all value types. + +## Start Blocks + +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. + +```yaml +dataSources: + - kind: ethereum/contract + name: ExampleSource + network: mainnet + source: + address: '0xc0a47dFe034B400B47bDaD5FecDa2621de6c4d95' + abi: ExampleContract + startBlock: 6627917 + mapping: + kind: ethereum/events + apiVersion: 0.0.6 + language: wasm/assemblyscript + file: ./src/mappings/factory.ts + entities: + - User + abis: + - name: ExampleContract + file: ./abis/ExampleContract.json + eventHandlers: + - event: NewEvent(address,address) + handler: handleNewEvent +``` + +> **Note:** The contract creation block can be quickly looked up on Etherscan: +> +> 1. Search for the contract by entering its address in the search bar. +> 2. Click on the creation transaction hash in the `Contract Creator` section. +> 3. Load the transaction details page where you'll find the start block for that contract. + +## Call Handlers + +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. + +Call handlers will only trigger in one of two cases: when the function specified is called by an account other than the contract itself or when it is marked as external in Solidity and called as part of another function in the same contract. + +> **Note:** Call handlers are not supported on Rinkeby, Goerli or Ganache. Call handlers currently depend on the Parity tracing API and these networks do not support it. + +### Defining a Call Handler + +To define a call handler in your manifest simply add a `callHandlers` array under the data source you would like to subscribe to. + +```yaml +dataSources: + - kind: ethereum/contract + name: Gravity + network: mainnet + source: + address: '0x731a10897d267e19b34503ad902d0a29173ba4b1' + abi: Gravity + mapping: + kind: ethereum/events + apiVersion: 0.0.6 + language: wasm/assemblyscript + entities: + - Gravatar + - Transaction + abis: + - name: Gravity + file: ./abis/Gravity.json + callHandlers: + - function: createGravatar(string,string) + 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. + +### Mapping Function + +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: + +```typescript +import { CreateGravatarCall } from '../generated/Gravity/Gravity' +import { Transaction } from '../generated/schema' + +export function handleCreateGravatar(call: CreateGravatarCall): void { + let id = call.transaction.hash.toHex() + let transaction = new Transaction(id) + transaction.displayName = call.inputs._displayName + transaction.imageUrl = call.inputs._imageUrl + transaction.save() +} +``` + +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`. + +## Block Handlers + +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 predefined filter. + +### Supported Filters + +```yaml +filter: + 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._ + +The absense of a filter for a block handler will ensure that the handler is called every block. A data source can only contain one block handler for each filter type. + +```yaml +dataSources: + - kind: ethereum/contract + name: Gravity + network: dev + source: + address: '0x731a10897d267e19b34503ad902d0a29173ba4b1' + abi: Gravity + mapping: + kind: ethereum/events + apiVersion: 0.0.6 + language: wasm/assemblyscript + entities: + - Gravatar + - Transaction + abis: + - name: Gravity + file: ./abis/Gravity.json + blockHandlers: + - handler: handleBlock + - handler: handleBlockWithCallToContract + filter: + kind: call +``` + +### Mapping Function + +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. + +```typescript +import { ethereum } from '@graphprotocol/graph-ts' + +export function handleBlock(block: ethereum.Block): void { + let id = block.hash.toHex() + let entity = new Block(id) + entity.save() +} +``` + +## Anonymous Events + +If you need to process anonymous events in Solidity, that can be achieved by providing the topic 0 of the event, as in the example: + +```yaml +eventHandlers: + - event: LogNote(bytes4,address,bytes32,bytes32,uint256,bytes) + topic0: '0xbaa8529c00000000000000000000000000000000000000000000000000000000' + 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. + +## Experimental features + +Starting from `specVersion` `0.0.4`, subgraph features must be explicitly declared in the `features` section at the top level of the manifest file, using their `camelCase` name, as listed in the table below: + +| Feature | Name | +| --------------------------------------------------------- | ------------------------- | +| [Non-fatal errors](#non-fatal-errors) | `nonFatalErrors` | +| [Full-text Search](#defining-fulltext-search-fields) | `fullTextSearch` | +| [Grafting](#grafting-onto-existing-subgraphs) | `grafting` | +| [IPFS on Ethereum Contracts](#ipfs-on-ethereum-contracts) | `ipfsOnEthereumContracts` | + +For instance, if a subgraph uses the **Full-Text Search** and the **Non-fatal Errors** features, the `features` field in the manifest should be: + +```yaml +specVersion: 0.0.4 +description: Gravatar for Ethereum +features: + - fullTextSearch + - nonFatalErrors +dataSources: ... +``` + +Note that using a feature without declaring it will incur in a **validation error** during subgraph deployment, but no errors will occur if a feature is declared but not used. + +### IPFS on Ethereum Contracts + +A common use case for combining IPFS with Ethereum is to store data on IPFS that would be too expensive to maintain on chain, and reference the IPFS hash in Ethereum contracts. + +Given such IPFS hashes, subgraphs can read the corresponding files from IPFS using `ipfs.cat` and `ipfs.map`. To do this reliably, however, it is required that these files are pinned on the IPFS node that the Graph Node indexing the subgraph connects to. In the case of the [hosted service](https://thegraph.com/hosted-service), this is [https://api.thegraph.com/ipfs/](https://api.thegraph.com/ipfs/). + +> **Note:** The Graph Network does not yet support `ipfs.cat` and `ipfs.map`, and developers should not deploy subgraphs using that functionality to the network via the Studio. + +In order to make this easy for subgraph developers, The Graph team wrote a tool for transfering files from one IPFS node to another, called [ipfs-sync](https://github.com/graphprotocol/ipfs-sync). + +> **[Feature Management](#experimental-features):** `ipfsOnEthereumContracts` must be declared under `features` in the subgraph manifest. + +### Non-fatal errors + +Indexing errors on already synced subgraphs will, by default, cause the subgraph to fail and stop syncing. Subgraphs can alternatively be configured to continue syncing in the presence of errors, by ignoring the changes made by the handler which provoked the error. This gives subgraph authors time to correct their subgraphs while queries continue to be served against the latest block, though the results will possibly be inconsistent due to the bug that caused the error. Note that some errors are still always fatal, to be non-fatal the error must be known to be deterministic. + +> **Note:** The Graph Network does not yet support non-fatal errors, and developers should not deploy subgraphs using that functionality to the network via the Studio. + +Enabling non-fatal errors requires setting the following feature flag on the subgraph manifest: + +```yaml +specVersion: 0.0.4 +description: Gravatar for Ethereum +features: + - fullTextSearch + ... +``` + +The query must also opt-in to querying data with potential inconsistencies through the `subgraphError` argument. It is also recommended to query `_meta` to check if the subgraph has skipped over errors, as in the example: + +```graphql +foos(first: 100, subgraphError: allow) { + id +} + +_meta { + hasIndexingErrors +} +``` + +If the subgraph encounters an error that query will return both the data and a graphql error with the message `"indexing_error"`, as in this example response: + +```graphql +"data": { + "foos": [ + { + "id": "fooId" + } + ], + "_meta": { + "hasIndexingErrors": true + } +}, +"errors": [ + { + "message": "indexing_error" + } +] +``` + +### Grafting onto Existing Subgraphs + +When a subgraph is first deployed, it starts indexing events at the genesis block of the corresponding chain (or at the `startBlock` defined with each data source) In some circumstances, it is beneficial to reuse the data from an existing subgraph and start indexing at a much later block. This mode of indexing is called _Grafting_. Grafting is, for example, useful during development to get past simple errors in the mappings quickly, or to temporarily get an existing subgraph working again after it has failed. + +> **Note:** Grafting requires that the Indexer has indexed the base subgraph. It is not recommended on The Graph Network at this time, and developers should not deploy subgraphs using that functionality to the network via the Studio. + +A subgraph is grafted onto a base subgraph when the subgraph manifest in `subgraph.yaml` contains a `graft` block at the toplevel: + +```yaml +description: ... +graft: + base: Qm... # Subgraph ID of base subgraph + block: 7345624 # Block number +``` + +When a subgraph whose manifest contains a `graft` block is deployed, Graph Node will copy the data of the `base` subgraph up to and including the given `block` and then continue indexing the new subgraph from that block on. The base subgraph must exist on the target Graph Node instance and must have indexed up to at least the given block. Because of this restriction, grafting should only be used during development or during an emergency to speed up producing an equivalent non-grafted subgraph. + +Because grafting copies rather than indexes base data it is much quicker in getting the subgraph to the desired block than indexing from scratch, though the initial data copy can still take several hours for very large subgraphs. While the grafted subgraph is being initialized, the Graph Node will log information about the entity types that have already been copied. + +The grafted subgraph can use a GraphQL schema that is not identical to the one of the base subgraph, but merely compatible with it. It has to be a valid subgraph schema in its own right but may deviate from the base subgraph's schema in the following ways: + +- It adds or removes entity types +- It removes attributes from entity types +- It adds nullable attributes to entity types +- It turns non-nullable attributes into nullable attributes +- It adds values to enums +- It adds or removes interfaces +- It changes for which entity types an interface is implemented + +> **[Feature Management](#experimental-features):** `grafting` must be declared under `features` in the subgraph manifest. diff --git a/pages/es/developer/define-subgraph-hosted.mdx b/pages/es/developer/define-subgraph-hosted.mdx new file mode 100644 index 000000000000..92bf5bd8cd2f --- /dev/null +++ b/pages/es/developer/define-subgraph-hosted.mdx @@ -0,0 +1,35 @@ +--- +title: Define a Subgraph +--- + +A subgraph defines which data The Graph will index from Ethereum, and how it will store it. Once deployed, it will form a part of a global graph of blockchain data. + +![Define a Subgraph](/img/define-subgraph.png) + +The subgraph definition consists of a few files: + +- `subgraph.yaml`: a YAML file containing the subgraph manifest + +- `schema.graphql`: a GraphQL schema that defines what data is stored for your subgraph, and how to query it via GraphQL + +- `AssemblyScript Mappings`: [AssemblyScript](https://github.com/AssemblyScript/assemblyscript) code that translates from the event data to the entities defined in your schema (e.g. `mapping.ts` in this tutorial) + +Before you go into detail about the contents of the manifest file, you need to install the [Graph CLI](https://github.com/graphprotocol/graph-cli) which you will need to build and deploy a subgraph. + +## Install the Graph CLI + +The Graph CLI is written in JavaScript, and you will need to install either `yarn` or `npm` to use it; it is assumed that you have yarn in what follows. + +Once you have `yarn`, install the Graph CLI by running + +**Install with yarn:** + +```bash +yarn global add @graphprotocol/graph-cli +``` + +**Install with npm:** + +```bash +npm install -g @graphprotocol/graph-cli +``` diff --git a/pages/es/developer/deprecating-a-subgraph.mdx b/pages/es/developer/deprecating-a-subgraph.mdx new file mode 100644 index 000000000000..f8966e025c13 --- /dev/null +++ b/pages/es/developer/deprecating-a-subgraph.mdx @@ -0,0 +1,17 @@ +--- +title: Deprecating a Subgraph +--- + +So you'd like to deprecate your subgraph on The Graph Explorer. You've come to the right place! Follow the steps below: + +1. Visit the contract address [here](https://etherscan.io/address/0xadca0dd4729c8ba3acf3e99f3a9f471ef37b6825#writeProxyContract) +2. Call 'deprecateSubgraph' with your own address as the first parameter +3. In the 'subgraphNumber' field, list 0 if it's the first subgraph you're publishing, 1 if it's your second, 2 if it's your third, etc. +4. Inputs for #2 and #3 can be found in your `` which is composed of the `{graphAccount}-{subgraphNumber}`. For example, the [Sushi Subgraph's](https://thegraph.com/explorer/subgraph?id=0x4bb4c1b0745ef7b4642feeccd0740dec417ca0a0-0&version=0x4bb4c1b0745ef7b4642feeccd0740dec417ca0a0-0-0&view=Overview) ID is `<0x4bb4c1b0745ef7b4642feeccd0740dec417ca0a0-0>`, which is a combination of `graphAccount` = `<0x4bb4c1b0745ef7b4642feeccd0740dec417ca0a0>` and `subgraphNumber` = `<0>` +5. Voila! Your subgraph will no longer show up on searches on The Graph Explorer. Please note the following: + +- Curators will not be able to signal on the subgraph anymore +- Curators that already signaled on the subgraph will be able to withdraw their signal at an average share price +- Deprecated subgraphs will be indicated with an error message. + +If you interacted with the now deprecated subgraph, you'll be able to find it in your user profile under the "Subgraphs", "Indexing", or "Curating" tab respectively. diff --git a/pages/es/developer/developer-faq.mdx b/pages/es/developer/developer-faq.mdx new file mode 100644 index 000000000000..41449c60e5ab --- /dev/null +++ b/pages/es/developer/developer-faq.mdx @@ -0,0 +1,172 @@ +--- +title: Developer FAQs +--- + +### 1. Can I delete my subgraph? + +It is not possible to delete subgraphs once they are created. + +### 2. Can I change my subgraph name? + +No. Once a subgraph is created, the name cannot be changed. Make sure to think of this carefully before you create your subgraph so it is easily searchable and identifiable by other dapps. + +### 3. Can I change the GitHub account associated with my subgraph? + +No. Once a subgraph is created, the associated GitHub account cannot be changed. Make sure to think of this carefully before you create your subgraph. + +### 4. Am I still able to create a subgraph if my smart contracts don't have events? + +It is highly recommended that you structure your smart contracts to have events associated with data you are interested in querying. Event handlers in the subgraph are triggered by contract events, and are by far the fastest way to retrieve useful data. + +If the contracts you are working with do not contain events, your subgraph can use call and block handlers to trigger indexing. Although this is not recommended as performance will be significantly slower. + +### 5. Is it possible to deploy one subgraph with the same name for multiple networks? + +You will need separate names for multiple networks. While you can't have different subgraphs under the same name, there are convenient ways of having a single codebase for multiple networks. Find more on this in our documentation: [Redeploying a Subgraph](/hosted-service/deploy-subgraph-hosted#redeploying-a-subgraph) + +### 6. How are templates different from data sources? + +Templates allow you to create data sources on the fly, while your subgraph is indexing. It might be the case that your contract will spawn new contracts as people interact with it, and since you know the shape of those contracts (ABI, events, etc) up front you can define how you want to index them in a template and when they are spawned your subgraph will create a dynamic data source by supplying the contract address. + +Check out the "Instantiating a data source template" section on: [Data Source Templates](/developer/create-subgraph-hosted#data-source-templates). + +### 7. How do I make sure I'm using the latest version of graph-node for my local deployments? + +You can run the following command: + +```sh +docker pull graphprotocol/graph-node:latest +``` + +**NOTE:** docker / docker-compose will always use whatever graph-node version was pulled the first time you ran it, so it is important to do this to make sure you are up to date with the latest version of graph-node. + +### 8. How do I call a contract function or access a public state variable from my subgraph mappings? + +Take a look at `Access to smart contract` state inside the section [AssemblyScript API](/developer/assemblyscript-api). + +### 9. Is it possible to set up a subgraph using `graph init` from `graph-cli` with two contracts? Or should I manually add another datasource in `subgraph.yaml` after running `graph init`? + +Unfortunately this is currently not possible. `graph init` is intended as a basic starting point, from which you can then add more data sources manually. + +### 10. I want to contribute or add a GitHub issue, where can I find the open source repositories? + +- [graph-node](https://github.com/graphprotocol/graph-node) +- [graph-cli](https://github.com/graphprotocol/graph-cli) +- [graph-ts](https://github.com/graphprotocol/graph-ts) + +### 11. What is the recommended way to build "autogenerated" ids for an entity when handling events? + +If only one entity is created during the event and if there's nothing better available, then the transaction hash + log index would be unique. You can obfuscate these by converting that to Bytes and then piping it through `crypto.keccak256` but this won't make it more unique. + +### 12. When listening to multiple contracts, is it possible to select the contract order to listen to events? + +Within a subgraph, the events are always processed in the order they appear in the blocks, regardless of whether that is across multiple contracts or not. + +### 13. Is it possible to differentiate between networks (mainnet, Kovan, Ropsten, local) from within event handlers? + +Yes. You can do this by importing `graph-ts` as per the example below: + +```javascript +import { dataSource } from '@graphprotocol/graph-ts' + +dataSource.network() +dataSource.address() +``` + +### 14. Do you support block and call handlers on Rinkeby? + +On Rinkeby we support block handlers, but without `filter: call`. Call handlers are not supported for the time being. + +### 15. Can I import ethers.js or other JS libraries into my subgraph mappings? + +Not currently, as mappings are written in AssemblyScript. One possible alternative solution to this is to store raw data in entities and perform logic that requires JS libraries on the client. + +### 16. Is it possible to specifying what block to start indexing on? + +Yes. `dataSources.source.startBlock` in the `subgraph.yaml` file specifies the 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: Start blocks + +### 17. Are there some tips to increase performance of indexing? My subgraph is taking a very long time to sync. + +Yes, you should take a look at the optional start block feature to start indexing from the block that the contract was deployed: [Start blocks](/developer/create-subgraph-hosted#start-blocks) + +### 18. Is there a way to query the subgraph directly to determine what the latest block number it has indexed? + +Yes! Try the following command, substituting "organization/subgraphName" with the organization under it is published and the name of your subgraph: + +```sh +curl -X POST -d '{ "query": "{indexingStatusForCurrentVersion(subgraphName: \"organization/subgraphName\") { chains { latestBlock { hash number }}}}"}' https://api.thegraph.com/index-node/graphql +``` + +### 19. What networks are supported by The Graph? + +The graph-node supports any EVM-compatible JSON RPC API chain. + +The Graph Network supports subgraphs indexing mainnet Ethereum: + +- `mainnet` + +In the Hosted Service, the following networks are supported: + +- Ethereum mainnet +- Kovan +- Rinkeby +- Ropsten +- Goerli +- PoA-Core +- PoA-Sokol +- xDAI +- NEAR +- NEAR testnet +- Matic +- Mumbai +- Fantom +- Binance Smart Chain +- Clover +- Avalanche +- Fuji +- Celo +- Celo-Alfajores +- Fuse +- Moonbeam +- Arbitrum One +- Arbitrum Testnet (on Rinkeby) +- Optimism +- Optimism Testnet (on Kovan) + +There is work in progress towards integrating other blockchains, you can read more in our repo: [RFC-0003: Multi-Blockchain Support](https://github.com/graphprotocol/rfcs/pull/8/files). + +### 20. Is it possible to duplicate a subgraph to another account or endpoint without redeploying? + +You have to redeploy the subgraph, but if the subgraph ID (IPFS hash) doesn't change, it won't have to sync from the beginning. + +### 21. Is this possible to use Apollo Federation on top of graph-node? + +Federation is not supported yet, although we do want to support it in the future. At the moment, something you can do is use schema stitching, either on the client or via a proxy service. + +### 22. Is there a limit to how many objects The Graph can return per query? + +By default query responses are limited to 100 items per collection. If you want to receive more, you can go up to 1000 items per collection and beyond that you can paginate with: + +```graphql +someCollection(first: 1000, skip: ) { ... } +``` + +### 23. If my dapp frontend uses The Graph for querying, do I need to write my query key into the frontend directly? What if we pay query fees for users – will malicious users cause our query fees to be very high? + +Currently, the recommended approach for a dapp is to add the key to the frontend and expose it to end users. That said, you can limit that key to a host name, like _yourdapp.io_ and subgraph. The gateway is currently being run by Edge & Node. Part of the responsibility of a gateway is to monitor for abusive behavior and block traffic from malicious clients. + +### 24. Where do I go to find my current subgraph on the Hosted Service? + +Head over to the Hosted Service in order to find subgraphs that you or others deployed to the Hosted Service. You can find it [here.](https://thegraph.com/hosted-service) + +### 25. Will the Hosted Service start charging query fees? + +The Graph will never charge for the Hosted Service. The Graph is a decentralized protocol, and charging for a centralized service is not aligned with The Graph’s values. The Hosted Service was always a temporary step to help get to the decentralized network. Developers will have a sufficient amount of time to migrate to the decentralized network as they are comfortable. + +### 26. When will the Hosted Service be shut down? + +If and when there are plans to do this, the community will be notified well ahead of time with considerations made for any subgraphs built on the Hosted Service. + +### 27. How do I upgrade a subgraph on mainnet? + +If you’re a subgraph developer, you can upgrade a new version of your subgraph to the Studio using the CLI. It’ll be private at that point but if you’re happy with it, you can publish to the decentralized Graph Explorer. This will create a new version of your subgraph that Curators can start signaling on. diff --git a/pages/es/developer/distributed-systems.mdx b/pages/es/developer/distributed-systems.mdx new file mode 100644 index 000000000000..894fcbe2e18b --- /dev/null +++ b/pages/es/developer/distributed-systems.mdx @@ -0,0 +1,132 @@ +--- +title: Distributed Systems +--- + +The Graph is a protocol implemented as a distributed system. + +Connections fail. Requests arrive out of order. Different computers with out-of-sync clocks and states process related requests. Servers restart. Re-orgs happen between requests. These problems are inherent to all distributed systems but are exacerbated in systems operating at a global scale. + +Consider this example of what may occur if a client polls an Indexer for the latest data during a re-org. + +1. Indexer ingests block 8 +2. Request served to the client for block 8 +3. Indexer ingests block 9 +4. Indexer ingests block 10A +5. Request served to the client for block 10A +6. Indexer detects reorg to 10B and rolls back 10A +7. Request served to the client for block 9 +8. Indexer ingests block 10B +9. Indexer ingests block 11 +10. Request served to the client for block 11 + +From the point of view of the Indexer, things are progressing forward logically. Time is moving forward, though we did have to roll back an uncle block and play the block under consensus forward on top of it. Along the way, the Indexer serves requests using the latest state it knows about at that time. + +From the point of view of the client, however, things appear chaotic. The client observes that the responses were for blocks 8, 10, 9, and 11 in that order. We call this the "block wobble" problem. When a client experiences block wobble, data may appear to contradict itself over time. The situation worsens when we consider that Indexers do not all ingest the latest blocks simultaneously, and your requests may be routed to multiple Indexers. + +It is the responsibility of the client and server to work together to provide consistent data to the user. Different approaches must be used depending on the desired consistency as there is no one right program for every problem. + +Reasoning through the implications of distributed systems is hard, but the fix may not be! We've established APIs and patterns to help you navigate some common use-cases. The following examples illustrate those patterns but still elide details required by production code (like error handling and cancellation) to not obfuscate the main ideas. + +## Polling for updated data + +The Graph provides the `block: { number_gte: $minBlock }` API, which ensures that the response is for a single block equal or higher to `$minBlock`. If the request is made to a `graph-node` instance and the min block is not yet synced, `graph-node` will return an error. If `graph-node` has synced min block, it will run the response for the latest block. If the request is made to an Edge & Node Gateway, the Gateway will filter out any Indexers that have not yet synced min block and make the request for the latest block the Indexer has synced. + +We can use `number_gte` to ensure that time never travels backward when polling for data in a loop. Here is an example: + +```javascript +/// Updates the protocol.paused variable to the latest +/// known value in a loop by fetching it using The Graph. +async function updateProtocolPaused() { + // It's ok to start with minBlock at 0. The query will be served + // using the latest block available. Setting minBlock to 0 is the + // same as leaving out that argument. + let minBlock = 0 + + for (;;) { + // Schedule a promise that will be ready once + // the next Ethereum block will likely be available. + const nextBlock = new Promise((f) => { + setTimeout(f, 14000) + }) + + const query = ` + { + protocol(block: { number_gte: ${minBlock} } id: "0") { + paused + } + _meta { + block { + number + } + } + }` + + const response = await graphql(query) + minBlock = response._meta.block.number + + // TODO: Do something with the response data here instead of logging it. + console.log(response.protocol.paused) + + // Sleep to wait for the next block + await nextBlock + } +} +``` + +## Fetching a set of related items + +Another use-case is retrieving a large set or, more generally, retrieving related items across multiple requests. Unlike the polling case (where the desired consistency was to move forward in time), the desired consistency is for a single point in time. + +Here we will use the `block: { hash: $blockHash }` argument to pin all of our results to the same block. + +```javascript +/// Gets a list of domain names from a single block using pagination +async function getDomainNames() { + // Set a cap on the maximum number of items to pull. + let pages = 5 + const perPage = 1000 + + // The first query will get the first page of results and also get the block + // hash so that the remainder of the queries are consistent with the first. + let query = ` + { + domains(first: ${perPage}) { + name + id + } + _meta { + block { + hash + } + } + }` + + let data = await graphql(query) + let result = data.domains.map((d) => d.name) + let blockHash = data._meta.block.hash + + // Continue fetching additional pages until either we run into the limit of + // 5 pages total (specified above) or we know we have reached the last page + // because the page has fewer entities than a full page. + while (data.domains.length == perPage && --pages) { + let lastID = data.domains[data.domains.length - 1].id + query = ` + { + domains(first: ${perPage}, where: { id_gt: "${lastID}" }, block: { hash: "${blockHash}" }) { + name + id + } + }` + + data = await graphql(query) + + // Accumulate domain names into the result + for (domain of data.domains) { + result.push(domain.name) + } + } + return result +} +``` + +Note that in case of a re-org, the client will need to retry from the first request to update the block hash to a non-uncle block. diff --git a/pages/es/developer/graphql-api.mdx b/pages/es/developer/graphql-api.mdx new file mode 100644 index 000000000000..f9cb6214fcd9 --- /dev/null +++ b/pages/es/developer/graphql-api.mdx @@ -0,0 +1,267 @@ +--- +title: GraphQL API +--- + +This guide explains the GraphQL Query API that is used for the Graph Protocol. + +## Queries + +In your subgraph schema you define types called `Entities`. For each `Entity` type, an `entity` and `entities` field will be generated on the top-level `Query` type. Note that `query` does not need to be included at the top of the `graphql` query when using The Graph. + +#### Examples + +Query for a single `Token` entity defined in your schema: + +```graphql +{ + token(id: "1") { + id + owner + } +} +``` + +**Note:** When querying for a single entity, the `id` field is required and it must be a string. + +Query all `Token` entities: + +```graphql +{ + tokens { + id + owner + } +} +``` + +### Sorting + +When querying a collection, the `orderBy` parameter may be used to sort by a specific attribute. Additionally, the `orderDirection` can be used to specify the sort direction, `asc` for ascending or `desc` for descending. + +#### Example + +```graphql +{ + tokens(orderBy: price, orderDirection: asc) { + id + owner + } +} +``` + +### Pagination + +When querying a collection, the `first` parameter can be used to paginate from the beginning of the collection. It is worth noting that the default sort order is by ID in ascending alphanumeric order, not by creation time. + +Further, the `skip` parameter can be used to skip entities and paginate. e.g. `first:100` shows the first 100 entities and `first:100, skip:100` shows the next 100 entities. + +Queries should avoid using very large `skip` values since they generally perform poorly. For retrieving a large number of items, it is much better to page through entities based on an attribute as shown in the last example. + +#### Example + +Query the first 10 tokens: + +```graphql +{ + tokens(first: 10) { + id + owner + } +} +``` + +To query for groups of entities in the middle of a collection, the `skip` parameter may be used in conjunction with the `first` parameter to skip a specified number of entities starting at the beginning of the collection. + +#### Example + +Query 10 `Token` entities, offset by 10 places from the beginning of the collection: + +```graphql +{ + tokens(first: 10, skip: 10) { + id + owner + } +} +``` + +#### Example + +If a client needs to retrieve a large number of entities, it is much more performant to base queries on an attribute and filter by that attribute. For example, a client would retrieve a large number of tokens using this query: + +```graphql +{ + query manyTokens($lastID: String) { + tokens(first: 1000, where: { id_gt: $lastID }) { + id + owner + } + } +} +``` + +The first time, it would send the query with `lastID = ""`, and for subsequent requests would set `lastID` to the `id` attribute of the last entity in the previous request. This approach will perform significantly better than using increasing `skip` values. + +### Filtering + +You can use the `where` parameter in your queries to filter for different properties. You can filter on mulltiple values within the `where` parameter. + +#### Example + +Query challenges with `failed` outcome: + +```graphql +{ + challenges(where: { outcome: "failed" }) { + challenger + outcome + application { + id + } + } +} +``` + +You can use suffixes like `_gt`, `_lte` for value comparison: + +#### Example + +```graphql +{ + applications(where: { deposit_gt: "10000000000" }) { + id + whitelisted + deposit + } +} +``` + +Full list of parameter suffixes: + +```graphql +_not +_gt +_lt +_gte +_lte +_in +_not_in +_contains +_not_contains +_starts_with +_ends_with +_not_starts_with +_not_ends_with +``` + +Please note that some suffixes are only supported for specific types. For example, `Boolean` only supports `_not`, `_in`, and `_not_in`. + +### Time-travel queries + +You can query the state of your entities not just for the latest block, which is the by default, but also for an arbitrary block in the past. The block at which a query should happen can be specified either by its block number or its block hash by including a `block` argument in the toplevel fields of queries. + +The result of such a query will not change over time, i.e., querying at a certain past block will return the same result no matter when it is executed, with the exception that if you query at a block very close to the head of the Ethereum chain, the result might change if that block turns out to not be on the main chain and the chain gets reorganized. Once a block can be considered final, the result of the query will not change. + +Note that the current implementation is still subject to certain limitations that might violate these gurantees. The implementation can not always tell that a given block hash is not on the main chain at all, or that the result of a query by block hash for a block that can not be considered final yet might be influenced by a block reorganization running concurrently with the query. They do not affect the results of queries by block hash when the block is final and known to be on the main chain. [This issue](https://github.com/graphprotocol/graph-node/issues/1405) explains what these limitations are in detail. + +#### Example + +```graphql +{ + challenges(block: { number: 8000000 }) { + challenger + outcome + application { + id + } + } +} +``` + +This query will return `Challenge` entities, and their associated `Application` entities, as they existed directly after processing block number 8,000,000. + +#### Example + +```graphql +{ + challenges(block: { hash: "0x5a0b54d5dc17e0aadc383d2db43b0a0d3e029c4c" }) { + challenger + outcome + application { + id + } + } +} +``` + +This query will return `Challenge` entities, and their associated `Application` entities, as they existed directly after processing the block with the given hash. + +### Fulltext Search Queries + +Fulltext search query fields provide an expressive text search API that can be added to the subgraph schema and customized. Refer to [Defining Fulltext Search Fields](/developer/create-subgraph-hosted#defining-fulltext-search-fields) to add fulltext search to your subgraph. + +Fulltext search queries have one required field, `text`, for supplying search terms. Several special fulltext operators are available to be used in this `text` search field. + +Fulltext search operators: + +| Symbol | Operator | Description | +| ----------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------ | +| `&` | `And` | For combining multiple search terms into a filter for entities that include all of the provided terms | +| | | `Or` | Queries with multiple search terms separated by the or operator will return all entities with a match from any of the provided terms | +| `<->` | `Follow by` | Specify the distance between two words. | +| `:*` | `Prefix` | Use the prefix search term to find words whose prefix match (2 characters required.) | + +#### Examples + +Using the `or` operator, this query will filter to blog entities with variations of either "anarchism" or "crumpet" in their fulltext fields. + +```graphql +{ + blogSearch(text: "anarchism | crumpets") { + id + title + body + author + } +} +``` + +The `follow by` operator specifies a words a specific distance apart in the fulltext documents. The following query will return all blogs with variations of "decentralize" followed by "philosophy" + +```graphql +{ + blogSearch(text: "decentralized <-> philosophy") { + id + title + body + author + } +} +``` + +Combine fulltext operators to make more complex filters. With a pretext search operator combined with a follow by this example query will match all blog entities with words that start with "lou" followed by "music". + +```graphql +{ + blogSearch(text: "lou:* <-> music") { + id + title + body + author + } +} +``` + +## Schema + +The schema of your data source--that is, the entity types, values, and relationships that are available to query--are defined through the [GraphQL Interface Definition Langauge (IDL)](https://facebook.github.io/graphql/draft/#sec-Type-System). + +GraphQL schemas generally define root types for `queries`, `subscriptions` and `mutations`. The Graph only supports `queries`. The root `Query` type for your subgraph is automatically generated from the GraphQL schema that's included in your subgraph manifest. + +> **Note:** Our API does not expose mutations because developers are expected to issue transactions directly against the underlying blockchain from their applications. + +### Entities + +All GraphQL types with `@entity` directives in your schema will be treated as entities and must have an `ID` field. + +> **Note:** Currently, all types in your schema must have an `@entity` directive. In the future, we will treat types without an `@entity` directive as value objects, but this is not yet supported. diff --git a/pages/es/developer/matchstick.mdx b/pages/es/developer/matchstick.mdx new file mode 100644 index 000000000000..3cf1ec761bb9 --- /dev/null +++ b/pages/es/developer/matchstick.mdx @@ -0,0 +1,267 @@ +--- +title: Unit Testing Framework +--- + +Matchstick is a unit testing framework, developed by [LimeChain](https://limechain.tech/), that enables subgraph developers to test their mapping logic in a sandboxed environment and deploy their subgraphs with confidence! + +Follow the [Matchstick installation guide](https://github.com/LimeChain/matchstick/blob/main/README.md#quick-start-) to install. Now, you can move on to writing your first unit test. + +## Write a Unit Test + +Let's see how a simple unit test would look like, using the Gravatar [Example Subgraph](https://github.com/graphprotocol/example-subgraph). + +Assuming we have the following handler function (along with two helper functions to make our life easier): + +```javascript +export function handleNewGravatar(event: NewGravatar): void { + let gravatar = new Gravatar(event.params.id.toHex()) + gravatar.owner = event.params.owner + gravatar.displayName = event.params.displayName + gravatar.imageUrl = event.params.imageUrl + gravatar.save() +} + +export function handleNewGravatars(events: NewGravatar[]): void { + events.forEach((event) => { + handleNewGravatar(event) + }) +} + +export function createNewGravatarEvent( + id: i32, + ownerAddress: string, + displayName: string, + imageUrl: string +): NewGravatar { + let mockEvent = newMockEvent() + let newGravatarEvent = new NewGravatar( + mockEvent.address, + mockEvent.logIndex, + mockEvent.transactionLogIndex, + mockEvent.logType, + mockEvent.block, + mockEvent.transaction, + mockEvent.parameters + ) + newGravatarEvent.parameters = new Array() + let idParam = new ethereum.EventParam('id', ethereum.Value.fromI32(id)) + let addressParam = new ethereum.EventParam( + 'ownderAddress', + ethereum.Value.fromAddress(Address.fromString(ownerAddress)) + ) + let displayNameParam = new ethereum.EventParam('displayName', ethereum.Value.fromString(displayName)) + let imageUrlParam = new ethereum.EventParam('imageUrl', ethereum.Value.fromString(imageUrl)) + + newGravatarEvent.parameters.push(idParam) + newGravatarEvent.parameters.push(addressParam) + newGravatarEvent.parameters.push(displayNameParam) + newGravatarEvent.parameters.push(imageUrlParam) + + return newGravatarEvent +} +``` + +We first have to create a test file in our project. We have chosen the name `gravity.test.ts`. In the newly created file we need to define a function named `runTests()`. It is important that the function has that exact name. This is an example of how our tests might look like: + +```typescript +import { clearStore, test, assert } from 'matchstick-as/assembly/index' +import { Gravatar } from '../../generated/schema' +import { NewGravatar } from '../../generated/Gravity/Gravity' +import { createNewGravatarEvent, handleNewGravatars } from '../mappings/gravity' + +export function runTests(): void { + test('Can call mappings with custom events', () => { + // Initialise + let gravatar = new Gravatar('gravatarId0') + gravatar.save() + + // Call mappings + let newGravatarEvent = createNewGravatarEvent(12345, '0x89205A3A3b2A69De6Dbf7f01ED13B2108B2c43e7', 'cap', 'pac') + + let anotherGravatarEvent = createNewGravatarEvent(3546, '0x89205A3A3b2A69De6Dbf7f01ED13B2108B2c43e7', 'cap', 'pac') + + handleNewGravatars([newGravatarEvent, anotherGravatarEvent]) + + assert.fieldEquals('Gravatar', 'gravatarId0', 'id', 'gravatarId0') + assert.fieldEquals('Gravatar', '12345', 'owner', '0x89205A3A3b2A69De6Dbf7f01ED13B2108B2c43e7') + assert.fieldEquals('Gravatar', '3546', 'displayName', 'cap') + + clearStore() + }) + + test('Next test', () => { + //... + }) +} +``` + +That's a lot to unpack! First off, an important thing to notice is that we're importing things from `matchstick-as`, our AssemblyScript helper library (distributed as an npm module). You can find the repository [here](https://github.com/LimeChain/matchstick-as). `matchstick-as` provides us with useful testing methods and also defines the `test()` function which we will use to build our test blocks. The rest of it is pretty straightforward - here's what happens: + +- We're setting up our initial state and adding one custom Gravatar entity; +- We define two `NewGravatar` event objects along with their data, using the `createNewGravatarEvent()` function; +- We're calling out handler methods for those events - `handleNewGravatars()` and passing in the list of our custom events; +- We assert the state of the store. How does that work? - We're passing a unique combination of Entity type and id. Then we check a specific field on that Entity and assert that it has the value we expect it to have. We're doing this both for the initial Gravatar Entity we added to the store, as well as the two Gravatar entities that gets added when the handler function is called; +- And lastly - we're cleaning the store using `clearStore()` so that our next test can start with a fresh and empty store object. We can define as many test blocks as we want. + +There we go - we've created our first test! 👏 + +❗ **IMPORTANT:** _In order for the tests to work, we need to export the `runTests()` function in our mappings file. It won't be used there, but the export statement has to be there so that it can get picked up by Rust later when running the tests._ + +You can export the tests wrapper function in your mappings file like this: + +``` +export { runTests } from "../tests/gravity.test.ts"; +``` + +❗ **IMPORTANT:** _Currently there's an issue with using Matchstick when deploying your subgraph. Please only use Matchstick for local testing, and remove/comment out this line (`export { runTests } from "../tests/gravity.test.ts"`) once you're done. We expect to resolve this issue shortly, sorry for the inconvenience!_ + +_If you don't remove that line, you will get the following error message when attempting to deploy your subgraph:_ + +``` +/... +Mapping terminated before handling trigger: oneshot canceled +.../ +``` + +Now in order to run our tests you simply need to run the following in your subgraph root folder: + +`graph test Gravity` + +And if all goes well you should be greeted with the following: + +![Matchstick saying “All tests passed!”](/img/matchstick-tests-passed.png) + +## Common test scenarios + +### Hydrating the store with a certain state + +Users are able to hydrate the store with a known set of entities. Here's an example to initialise the store with a Gravatar entity: + +```typescript +let gravatar = new Gravatar('entryId') +gravatar.save() +``` + +### Calling a mapping function with an event + +A user can create a custom event and pass it to a mapping function that is bound to the store: + +```typescript +import { store } from 'matchstick-as/assembly/store' +import { NewGravatar } from '../../generated/Gravity/Gravity' +import { handleNewGravatars, createNewGravatarEvent } from './mapping' + +let newGravatarEvent = createNewGravatarEvent(12345, '0x89205A3A3b2A69De6Dbf7f01ED13B2108B2c43e7', 'cap', 'pac') + +handleNewGravatar(newGravatarEvent) +``` + +### Calling all of the mappings with event fixtures + +Users can call the mappings with test fixtures. + +```typescript +import { NewGravatar } from '../../generated/Gravity/Gravity' +import { store } from 'matchstick-as/assembly/store' +import { handleNewGravatars, createNewGravatarEvent } from './mapping' + +let newGravatarEvent = createNewGravatarEvent(12345, '0x89205A3A3b2A69De6Dbf7f01ED13B2108B2c43e7', 'cap', 'pac') + +let anotherGravatarEvent = createNewGravatarEvent(3546, '0x89205A3A3b2A69De6Dbf7f01ED13B2108B2c43e7', 'cap', 'pac') + +handleNewGravatars([newGravatarEvent, anotherGravatarEvent]) +``` + +``` +export function handleNewGravatars(events: NewGravatar[]): void { + events.forEach(event => { + handleNewGravatar(event); + }); +} +``` + +### Mocking contract calls + +Users can mock contract calls: + +```typescript +import { addMetadata, assert, createMockedFunction, clearStore, test } from 'matchstick-as/assembly/index' +import { Gravity } from '../../generated/Gravity/Gravity' +import { Address, BigInt, ethereum } from '@graphprotocol/graph-ts' + +let contractAddress = Address.fromString('0x89205A3A3b2A69De6Dbf7f01ED13B2108B2c43e7') +let expectedResult = Address.fromString('0x90cBa2Bbb19ecc291A12066Fd8329D65FA1f1947') +let bigIntParam = BigInt.fromString('1234') +createMockedFunction(contractAddress, 'gravatarToOwner', 'gravatarToOwner(uint256):(address)') + .withArgs([ethereum.Value.fromSignedBigInt(bigIntParam)]) + .returns([ethereum.Value.fromAddress(Address.fromString('0x90cBa2Bbb19ecc291A12066Fd8329D65FA1f1947'))]) + +let gravity = Gravity.bind(contractAddress) +let result = gravity.gravatarToOwner(bigIntParam) + +assert.equals(ethereum.Value.fromAddress(expectedResult), ethereum.Value.fromAddress(result)) +``` + +As demonstrated, in order to mock a contract call and hardcore a return value, the user must provide a contract address, function name, function signature, an array of arguments, and of course - the return value. + +Users can also mock function reverts: + +```typescript +let contractAddress = Address.fromString('0x89205A3A3b2A69De6Dbf7f01ED13B2108B2c43e7') +createMockedFunction(contractAddress, 'getGravatar', 'getGravatar(address):(string,string)') + .withArgs([ethereum.Value.fromAddress(contractAddress)]) + .reverts() +``` + +### Asserting the state of the store + +Users are able to assert the final (or midway) state of the store through asserting entities. In order to do this, the user has to supply an Entity type, the specific ID of an Entity, a name of a field on that Entity, and the expected value of the field. Here's a quick example: + +```typescript +import { assert } from 'matchstick-as/assembly/index' +import { Gravatar } from '../generated/schema' + +let gravatar = new Gravatar('gravatarId0') +gravatar.save() + +assert.fieldEquals('Gravatar', 'gravatarId0', 'id', 'gravatarId0') +``` + +Running the assert.fieldEquals() function will check for equality of the given field against the given expected value. The test will fail and an error message will be outputted if the values are **NOT** equal. Otherwise the test will pass successfully. + +### Interacting with Event metadata + +Users can use default transaction metadata, which could be returned as an ethereum.Event by using the `newMockEvent()` function. The following example shows how you can read/write to those fields on the Event object: + +```typescript +// Read +let logType = newGravatarEvent.logType + +// Write +let UPDATED_ADDRESS = '0xB16081F360e3847006dB660bae1c6d1b2e17eC2A' +newGravatarEvent.address = Address.fromString(UPDATED_ADDRESS) +``` + +### Asserting variable equality + +```typescript +assert.equals(ethereum.Value.fromString("hello"); ethereum.Value.fromString("hello")); +``` + +### Asserting that an Entity is **not** in the store + +Users can assert that an entity does not exist in the store. The function takes an entity type and an id. If the entity is in fact in the store, the test will fail with a relevant error message. Here's a quick example of how to use this functionality: + +```typescript +assert.notInStore('Gravatar', '23') +``` + +### Test run time duration in the log output + +The log output includes the test run duration. Here's an example: + +`Jul 09 14:54:42.420 INFO Program execution time: 10.06022ms` + +## Feedback + +If you have any questions, feedback, feature requests or just want to reach out, the best place would be The Graph Discord where we have a dedicated channel for Matchstick, called 🔥| unit-testing. diff --git a/pages/es/developer/publish-subgraph.mdx b/pages/es/developer/publish-subgraph.mdx new file mode 100644 index 000000000000..2f35f5eb1bae --- /dev/null +++ b/pages/es/developer/publish-subgraph.mdx @@ -0,0 +1,27 @@ +--- +title: Publish a Subgraph to the Decentralized Network +--- + +Once your subgraph has been [deployed to the Subgraph Studio](/studio/deploy-subgraph-studio), you have tested it out, and are ready to put it into production, you can then publish it to the decentralized network. + +Publishing a Subgraph to the decentralized network makes it available for [curators](/curating) to begin curating on it, and [indexers](/indexing) to begin indexing it. + +For a walkthrough of how to publish a subgraph to the decentralized network, see [this video](https://youtu.be/HfDgC2oNnwo?t=580). + +### Networks + +The decentralized network currently supports both Rinkeby and Ethereum Mainnet. + +### Publishing a subgraph + +Subgraphs can be published to the decentralized network directly from the Subgraph Studio dashboard by clicking on the **Publish** button. Once a subgraph is published, it will be available to view in the [Graph Explorer](https://thegraph.com/explorer/). + +- Subgraphs published to Rinkeby can index and query data from either the Rinkeby network or Ethereum Mainnet. + +- Subgraphs published to Ethereum Mainnet can only index and query data from Ethereum Mainnet, meaning that you cannot publish subgraphs to the main decentralized network that index and query testnet data. + +- When publishing a new version for an existing subgraph the same rules apply as above. + +### Updating metadata for a published subgraph + +Once your subgraph has been published to the decentralized network, you can modify the metadata at any time by making the update in the Subgraph Studio dashboard of the subgraph. After saving the changes and publishing your updates to the network, they will be reflected in the Graph Explorer. This won’t create a new version, as your deployment hasn’t changed. diff --git a/pages/es/developer/query-the-graph.mdx b/pages/es/developer/query-the-graph.mdx new file mode 100644 index 000000000000..ae480b1e6883 --- /dev/null +++ b/pages/es/developer/query-the-graph.mdx @@ -0,0 +1,32 @@ +--- +title: Query The Graph +--- + +With the subgraph deployed, visit the [Graph Explorer](https://thegraph.com/explorer) to open up a [GraphiQL](https://github.com/graphql/graphiql) interface where you can explore the deployed GraphQL API for the subgraph by issuing queries and viewing the schema. + +An example is provided below, but please see the [Query API](/developer/graphql-api) for a complete reference on how to query the subgraph's entities. + +#### Example + +This query lists all the counters our mapping has created. Since we only create one, the result will only contain our one `default-counter`: + +```graphql +{ + counters { + id + value + } +} +``` + +## Using The Graph Explorer + +Each subgraph published to the decentralized Graph Explorer has a unique query URL that you can find by navigating to the subgraph details page and clicking on the "Query" button on the top right corner. This will open a side pane that will give you the unique query URL of the subgraph as well as some instructions about how to query it. + +![Query Subgraph Pane](/img/query-subgraph-pane.png) + +As you can notice, this query URL must use a unique API key. You can create and manage your API keys in the [Subgraph Studio](https://thegraph.com/studio) in the "API Keys" section. Learn more about how to use Subgraph Studio [here](/studio/subgraph-studio). + +Querying subgraphs using your API keys will generate query fees that will be paid in GRT. You can learn more about billing [here](/studio/billing). + +You can also use the GraphQL playground in the "Playground" tab to query a subgraph within The Graph Explorer. diff --git a/pages/es/developer/querying-from-your-app.mdx b/pages/es/developer/querying-from-your-app.mdx new file mode 100644 index 000000000000..c09c44efee72 --- /dev/null +++ b/pages/es/developer/querying-from-your-app.mdx @@ -0,0 +1,136 @@ +--- +title: Querying from an Application +--- + +Once a subgraph is deployed to the Subgraph Studio or to the Graph Explorer, you will be given the endpoint for your GraphQL API that should look something like this: + +**Subgraph Studio (testing endpoint)** + +```sh +Queries (HTTP) +https://api.studio.thegraph.com/query/// +``` + +**Graph Explorer** + +```sh +Queries (HTTP) +https://gateway.thegraph.com/api//subgraphs/id/ +``` + +Using the GraphQL endpoint, you can use various GraphQL Client libraries to query the subgraph and populate your app with the data indexed by the subgraph. + +Here are a couple of the more popular GraphQL clients in the ecosystem and how to use them: + +### Apollo client + +[Apollo client](https://www.apollographql.com/docs/) supports web projects including frameworks like React and Vue, as well as mobile clients like iOS, Android, and React Native. + +Let's look at how fetch data from a subgraph with Apollo client in a web project. + +First, install `@apollo/client` and `graphql`: + +```sh +npm install @apollo/client graphql +``` + +Then you can query the API with the following code: + +```javascript +import { ApolloClient, InMemoryCache, gql } from '@apollo/client' + +const APIURL = 'https://api.studio.thegraph.com/query///' + +const tokensQuery = ` + query { + tokens { + id + tokenID + contentURI + metadataURI + } + } +` + +const client = new ApolloClient({ + uri: APIURL, + cache: new InMemoryCache(), +}) + +client + .query({ + query: gql(tokensQuery), + }) + .then((data) => console.log('Subgraph data: ', data)) + .catch((err) => { + console.log('Error fetching data: ', err) + }) +``` + +To use variables, you can pass in a `variables` argument to the query: + +```javascript +const tokensQuery = ` + query($first: Int, $orderBy: BigInt, $orderDirection: String) { + tokens( + first: $first, orderBy: $orderBy, orderDirection: $orderDirection + ) { + id + tokenID + contentURI + metadataURI + } + } +` + +client + .query({ + query: gql(tokensQuery), + variables: { + first: 10, + orderBy: 'createdAtTimestamp', + orderDirection: 'desc', + }, + }) + .then((data) => console.log('Subgraph data: ', data)) + .catch((err) => { + console.log('Error fetching data: ', err) + }) +``` + +### URQL + +Another option is [URQL](https://formidable.com/open-source/urql/), a somewhat lighter weight GraphQL client library. + +Let's look at how fetch data from a subgraph with URQL in a web project. + +First, install `urql` and `graphql`: + +```sh +npm install urql graphql +``` + +Then you can query the API with the following code: + +```javascript +import { createClient } from 'urql' + +const APIURL = 'https://api.thegraph.com/subgraphs/name/username/subgraphname' + +const tokensQuery = ` + query { + tokens { + id + tokenID + contentURI + metadataURI + } + } +` + +const client = createClient({ + url: APIURL, +}) + +const data = await client.query(tokensQuery).toPromise() +``` diff --git a/pages/es/developer/quick-start.mdx b/pages/es/developer/quick-start.mdx new file mode 100644 index 000000000000..6893d424ddc2 --- /dev/null +++ b/pages/es/developer/quick-start.mdx @@ -0,0 +1,227 @@ +--- +title: Quick Start +--- + +This guide will quickly take you through how to initialize, create, and deploy your subgraph on: + +- **Subgraph Studio** - used only for subgraphs that index **Ethereum mainnet** +- **Hosted Service** - used for subgraphs that index **other networks** outside of Ethereum mainnnet (e.g. Binance, Matic, etc) + +## Subgraph Studio + +### 1. Install the Graph CLI + +The Graph CLI is written in JavaScript and you will need to have either `npm` or `yarn` installed to use it. + +```sh +# NPM +$ npm install -g @graphprotocol/graph-cli + +# Yarn +$ yarn global add @graphprotocol/graph-cli +``` + +### 2. Initialize your Subgraph + +- Initialize your subgraph from an existing contract. + +```sh +graph init --studio +``` + +- Your subgraph slug is an identifier for your subgraph. The CLI tool will walk you through the steps for creating a subgraph, such as contract address, network, etc as you can see in the screenshot below. + +![Subgraph command](/img/Subgraph-Slug.png) + +### 3. Write your Subgraph + +The previous commands creates a scaffold subgraph that you can use as a starting point for building your subgraph. When making changes to the subgraph, you will mainly work with three files: + +- Manifest (subgraph.yaml) - The manifest defines what datasources your subgraphs will index. +- Schema (schema.graphql) - The GraphQL schema defines what data you wish to retreive from the subgraph. +- AssemblyScript Mappings (mapping.ts) - This is the code that translates data from your datasources to the entities defined in the schema. + +For more information on how to write your subgraph, see [Create a Subgraph](/developer/create-subgraph-hosted). + +### 4. Deploy to the Subgraph Studio + +- Go to the Subgraph Studio [https://thegraph.com/studio/](https://thegraph.com/studio/) and connect your wallet. +- Click "Create" and enter the subgraph slug you used in step 2. +- Run these commands in the subgraph folder + +```sh +$ graph codegen +$ graph build +``` + +- Authenticate and deploy your subgraph. The deploy key can be found on the Subgraph page in Subgraph Studio. + +```sh +$ graph auth --studio +$ graph deploy --studio +``` + +- You will be asked for a version label. It's strongly recommended to use the following conventions for naming your versions. Example: `0.0.1`, `v1`, `version1` + +### 5. Check your logs + +The logs should tell you if there are any errors. If your subgraph is failing, you can query the subgraph health by using the [GraphiQL Playground](https://graphiql-online.com/). Use [this endpoint](https://api.thegraph.com/index-node/graphql). Note that you can leverage the query below and input your deployment ID for your subgraph. In this case, `Qm...` is the deployment ID (which can be located on the Subgraph page under **Details**). The query below will tell you when a subgraph fails so you can debug accordingly: + +```sh +{ + indexingStatuses(subgraphs: ["Qm..."]) { + node + synced + health + fatalError { + message + block { + number + hash + } + handler + } + nonFatalErrors { + message + block { + number + hash + } + handler + } + chains { + network + chainHeadBlock { + number + } + earliestBlock { + number + } + latestBlock { + number + } + lastHealthyBlock { + number + } + } + entityCount + } +} +``` + +### 6. Query your Subgraph + +You can now query your subgraph by following [these instructions](/developer/query-the-graph). You can query from your dapp if you don't have your API key via the free, rate limited temporary query URL that can be used for development and staging. You can read the additional instructions for how to query a subgraph from a frontend application [here](/developer/querying-from-your-app). + +## Hosted Service + +### 1. Install the Graph CLI + +"The Graph CLI is an npm package and you will need `npm` or `yarn` installed to use it. + +```sh +# NPM +$ npm install -g @graphprotocol/graph-cli + +# Yarn +$ yarn global add @graphprotocol/graph-cli +``` + +### 2. Initialize your Subgraph + +- Initialize your subgraph from an existing contract. + +```sh +$ graph init --product hosted-service --from-contract
+``` + +- You will be asked for a subgraph name. The format is `/`. Ex: `graphprotocol/examplesubgraph` + +- If you'd like to initialize from an example, run the command below: + +```sh +$ graph init --product hosted-service --from-example +``` + +- In the case of the example, the subgraph is based on the Gravity contract by Dani Grant that manages user avatars and emits `NewGravatar` or `UpdateGravatar` events whenever avatars are created or updated. + +### 3. Write your Subgraph + +The previous command will have created a scaffold from where you can build your subgraph. When making changes to the subgraph, you will mainly work with three files: + +- Manifest (subgraph.yaml) - The manifest defines what datasources your subgraph will index +- Schema (schema.graphql) - The GraphQL schema define what data you wish to retrieve from the subgraph +- AssemblyScript Mappings (mapping.ts) - This is the code that translates data from your datasources to the entities defined in the schema + +For more information on how to write your subgraph, see [Create a Subgraph](/developer/create-subgraph-hosted). + +### 4. Deploy your Subgraph + +- Sign into the [Hosted Service](https://thegraph.com/hosted-service/) using your github account +- Click Add Subgraph and fill out the required information. Use the same subgraph name as in step 2. +- Run codegen in the subgraph folder + +```sh + # NPM +$ npm run codegen + +# Yarn +$ yarn codegen +``` + +- Add your Access token and deploy your subgraph. The access token is found on your dashboard in the Hosted Service. + +```sh +$ graph auth --product hosted-service +$ graph deploy --product hosted-service / +``` + +### 5. Check your logs + +The logs should tell you if there are any errors. If your subgraph is failing, you can query the subgraph health by using the [GraphiQL Playground](https://graphiql-online.com/). Use [this endpoint](https://api.thegraph.com/index-node/graphql). Note that you can leverage the query below and input your deployment ID for your subgraph. In this case, `Qm...` is the deployment ID (which can be located on the Subgraph page under **Details**). The query below will tell you when a subgraph fails so you can debug accordingly: + +```sh +{ + indexingStatuses(subgraphs: ["Qm..."]) { + node + synced + health + fatalError { + message + block { + number + hash + } + handler + } + nonFatalErrors { + message + block { + number + hash + } + handler + } + chains { + network + chainHeadBlock { + number + } + earliestBlock { + number + } + latestBlock { + number + } + lastHealthyBlock { + number + } + } + entityCount + } +} +``` + +### 6. Query your Subgraph + +Follow [these instructions](/hosted-service/query-hosted-service) to query your subgraph on the Hosted Service. diff --git a/pages/es/explorer.mdx b/pages/es/explorer.mdx index 72bd427987c2..eee9dce5ade9 100644 --- a/pages/es/explorer.mdx +++ b/pages/es/explorer.mdx @@ -11,7 +11,7 @@ Bienvenido al explorador de The Graph, o como nos gusta llamarlo, tu portal desc title="Reproductor de video de YouTube" frameBorder="0" allowFullScreen - > +> ## Subgrafos diff --git a/pages/es/hosted-service/deploy-subgraph-hosted.mdx b/pages/es/hosted-service/deploy-subgraph-hosted.mdx new file mode 100644 index 000000000000..bdc532e205e4 --- /dev/null +++ b/pages/es/hosted-service/deploy-subgraph-hosted.mdx @@ -0,0 +1,160 @@ +--- +title: Deploy a Subgraph to the Hosted Service +--- + +If you have not checked out already, check out how to write the files that make up a [subgraph manifest](/developer/create-subgraph-hosted#the-subgraph-manifest) and how to install the [Graph CLI](https://github.com/graphprotocol/graph-cli) to generate code for your subgraph. Now, it's time to deploy your subgraph to the Hosted Service, also known as the Hosted Service. + +## Create a Hosted Service account + +Before using the Hosted Service, create an account in our Hosted Service. You will need a [Github](https://github.com/) account for that; if you don't have one, you need to create that first. Then, navigate to the [Hosted Service](https://thegraph.com/hosted-service/), click on the _'Sign up with Github'_ button and complete Github's authorization flow. + +## Store the Access Token + +After creating an account, navigate to your [dashboard](https://thegraph.com/hosted-service/dashboard). Copy the access token displayed on the dashboard and run `graph auth --product hosted-service `. This will store the access token on your computer. You only need to do this once, or if you ever regenerate the access token. + +## Create a Subgraph on the Hosted Service + +Before deploying the subgraph, you need to create it in The Graph Explorer. Go to the [dashboard](https://thegraph.com/hosted-service/dashboard) and click on the _'Add Subgraph'_ button and fill in the information below as appropriate: + +**Image** - Select an image to be used as a preview image and thumbnail for the subgraph. + +**Subgraph Name** - Together with the account name that the subgraph is created under, this will also define the `account-name/subgraph-name`-style name used for deployments and GraphQL endpoints. _This field cannot be changed later._ + +**Account** - The account that the subgraph is created under. This can be the account of an individual or organization. _Subgraphs cannot be moved between accounts later._ + +**Subtitle** - Text that will appear in subgraph cards. + +**Description** - Description of the subgraph, visible on the subgraph details page. + +**GitHub URL** - Link to the subgraph repository on GitHub. + +**Hide** - Switching this on hides the subgraph in the 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 [Define a Subgraph section](/developer/define-subgraph-hosted). + +## Deploy a Subgraph on the Hosted Service + +Deploying your subgraph will upload the subgraph files that you've built with `yarn build` to IPFS and tell the Graph Explorer to start indexing your subgraph using these files. + +You deploy the subgraph by running `yarn deploy` + +After deploying the subgraph, the 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 Ethereum blocks, starting with the genesis block, syncing can take from a few minutes to several hours. The subgraph status switches to `Synced` once the Graph Node has extracted all data from historical blocks. The Graph Node will continue inspecting Ethereum blocks for your subgraph as these blocks are mined. + +## Redeploying a Subgraph + +When making changes to your subgraph definition, for example to fix a problem in the entity mappings, run the `yarn deploy` command above again to deploy the updated version of your subgraph. Any update of a subgraph requires that Graph Node reindexes your entire subgraph, again starting with the genesis block. + +If your previously deployed subgraph is still in status `Syncing`, it will be immediately replaced with the newly deployed version. If the previously deployed subgraph is already fully synced, Graph Node will mark the newly deployed version as the `Pending Version`, sync it in the background, and only replace the currently deployed version with the new one once syncing the new version has finished. This ensures that you have a subgraph to work with while the new version is syncing. + +### Deploying the subgraph to multiple Ethereum networks + +In some cases, you will want to deploy the same subgraph to multiple Ethereum networks without duplicating all of its code. The main challenge that comes with this is that the contract addresses on these networks are different. One solution that allows to parameterize aspects like contract addresses is to generate parts of it using a templating system like [Mustache](https://mustache.github.io/) or [Handlebars](https://handlebarsjs.com/). + +To illustrate this approach, let's assume a subgraph should be deployed to mainnet and Ropsten using different contract addresses. You could then define two config files providing the addresses for each network: + +```json +{ + "network": "mainnet", + "address": "0x123..." +} +``` + +and + +```json +{ + "network": "ropsten", + "address": "0xabc..." +} +``` + +Along with that, you would substitute the network name and addresses in the manifest with variable placeholders `{{network}}` and `{{address}}` and rename the manifest to e.g. `subgraph.template.yaml`: + +```yaml +# ... +dataSources: + - kind: ethereum/contract + name: Gravity + network: mainnet + network: {{network}} + source: + address: '0x2E645469f354BB4F5c8a05B3b30A929361cf77eC' + address: '{{address}}' + abi: Gravity + mapping: + kind: ethereum/events +``` + +In order generate a manifest to either network, you could add two additional commands to `package.json` along with a dependency on `mustache`: + +```json +{ + ... + "scripts": { + ... + "prepare:mainnet": "mustache config/mainnet.json subgraph.template.yaml > subgraph.yaml", + "prepare:ropsten": "mustache config/ropsten.json subgraph.template.yaml > subgraph.yaml" + }, + "devDependencies": { + ... + "mustache": "^3.1.0" + } +} +``` + +To deploy this subgraph for mainnet or Ropsten you would now simply run one of the two following commands: + +```sh +# Mainnet: +yarn prepare:mainnet && yarn deploy + +# Ropsten: +yarn prepare:ropsten && yarn deploy +``` + +A working example of this can be found [here](https://github.com/graphprotocol/example-subgraph/tree/371232cf68e6d814facf5e5413ad0fef65144759). + +**Note:** This approach can also be applied more complex situations, where it is necessary to substitute more than contract addresses and network names or where generating mappings or ABIs from templates as well. + +## Checking subgraph health + +If a subgraph syncs successfully, that is a good sign that it will continue to run well forever. However, new triggers on the chain might cause your subgraph to hit an untested error condition or it may start to fall behind due to performance issues or issues with the node operators. + +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](https://github.com/graphprotocol/graph-node/blob/master/server/index-node/src/schema.graphql). Here is an example query that checks the status of the current version of a subgraph: + +```graphql +{ + indexingStatusForCurrentVersion(subgraphName: "org/subgraph") { + synced + health + fatalError { + message + block { + number + hash + } + handler + } + chains { + chainHeadBlock { + number + } + latestBlock { + number + } + } + } +} +``` + +This will give you the `chainHeadBlock` which you can compare with the `latestBlock` on your subgraph to check if it is running behind. `synced` informs if the subgraph has ever caught up to the chain. `health` can currently take the values of `healthy` if no errors ocurred, or `failed` if there was an error which halted the progress of the subgraph. In this case you can check the `fatalError` field for details on this error. + +## Subgraph archive policy + +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 which 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 30 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. diff --git a/pages/es/hosted-service/migrating-subgraph.mdx b/pages/es/hosted-service/migrating-subgraph.mdx new file mode 100644 index 000000000000..eda54d1931ed --- /dev/null +++ b/pages/es/hosted-service/migrating-subgraph.mdx @@ -0,0 +1,151 @@ +--- +title: Migrating an Existing Subgraph to The Graph Network +--- + +## Introducción + +This is a guide for the migration of subgraphs from the Hosted Service (also known as the Hosted Service) to The Graph Network. The migration to The Graph Network has been successful for projects like Opyn, UMA, mStable, Audius, PoolTogether, Livepeer, RAI, Enzyme, DODO, Opyn, Pickle, and BadgerDAO all of which are relying on data served by Indexers on the network. There are now over 200 subgraphs live on The Graph Network, generating query fees and actively indexing web3 data. + +This will tell you everything you need to know about how to migrate to the decentralized network and manage your subgraphs moving forward. The process is quick and your subgraphs will forever benefit from the reliability and performance that you can only get on The Graph Network. + +### Migrating An Existing Subgraph to The Graph Network + +1. Get the latest version of the graph-cli installed: + +```sh +npm install -g @graphprotocol/graph-cli +``` + +```sh +yarn global add @graphprotocol/graph-cli +``` + +2. Create a subgraph on the [Subgraph Studio](https://thegraph.com/studio/). Guides on how to do that can be found in the [Subgraph Studio docs](/studio/subgraph-studio) and in [this video tutorial](https://www.youtube.com/watch?v=HfDgC2oNnwo). +3. Inside the main project subgraph repository, authenticate the subgraph to deploy and build on the studio: + +```sh +graph auth --studio +``` + +4. Generate files and build the subgraph: + +```sh +graph codegen && graph build +``` + +5. Deploy the subgraph to the Studio. You can find your `` in the Studio UI, which is based on the name of your subgraph. + +```sh + graph deploy --studio +``` + +6. Test queries on the Studio's playground. Here are some examples for the [Sushi - Mainnet Exchange Subgraph](https://thegraph.com/explorer/subgraph?id=0x4bb4c1b0745ef7b4642feeccd0740dec417ca0a0-0&view=Playground): + +```sh +{ + users(first: 5) { + id + liquidityPositions { + id + } + } + bundles(first: 5) { + id + ethPrice + } +} +``` + +7. Fill in the description and the details of your subgraph and choose up to 3 categories. Upload a project image in the Studio if you'd like as well. +8. Publish the subgraph on The Graph's Network by hitting the "Publish" button. + +- Remember that publishing is an on-chain action and will require gas to be paid for in Ethereum - see an example transaction [here](https://etherscan.io/tx/0xd0c3fa0bc035703c9ba1ce40c1862559b9c5b6ea1198b3320871d535aa0de87b). Prices are roughly around 0.0425 ETH at 100 gwei. +- Any time you need to upgrade your subgraph, you will be charged an upgrade fee. Remember, upgrading is just publishing another version of your existing subgraph on-chain. Because this incurs a cost, it is highly recommended to deploy and test your subgraph on Rinkeby before deploying to mainnet. It can, in some cases, also require some GRT if there is no signal on that subgraph. In the case there is signal/curation on that subgraph version (using auto-migrate), the taxes will be split. + +And that's it! After you are done publishing, you'll be able to view your subgraphs live on the network via [The Graph Explorer](https://thegraph.com/explorer). + +### Upgrading a Subgraph on the Network + +If you would like to upgrade an existing subgraph on the network, you can do this by deploying a new version of your subgraph to the Subgraph Studio using the Graph CLI. + +1. Make changes to your current subgraph. A good idea is to test small fixes on the Subgraph Studio by publishing to Rinkeby. +2. Deploy the following and specify the new version in the command (eg. v0.0.1, v0.0.2, etc): + +```sh +graph deploy --studio +``` + +3. Test the new version in the Subgraph Studio by querying in the playground +4. Publish the new version on The Graph Network. Remember that this requires gas (as described in the section above). + +### Owner Upgrade Fee: Deep Dive + +An upgrade requires GRT to be migrated from the old version of the subgraph to the new version. This means that for every upgrade, a new bonding curve will be created (more on bonding curves [here](/curating#bonding-curve-101)). + +The new bonding curve charges the 2.5% curation tax on all GRT being migrated to the new version. The owner must pay 50% of this, or 1.25%. The other 1.25% is absorbed by all the curators as a fee. This incentive design is in place to prevent an owner of a subgraph from being able to drain all their curator's funds with recursive upgrade calls. The example below is only the case if your subgraph is being actively curated on. If there is no curation activity, you will have to pay a minimum of 100 GRT in order to signal yourself on your own subgraph. + +- 100,000 GRT is signaled using auto-migrate on v1 of a subgraph +- Owner upgrades to v2. 100,000 GRT is migrated to a new bonding curve, where 97,500 GRT get put into the new curve and 2,500 GRT is burned +- The owner then has 1250 GRT burned to pay for half the fee. The owner must have this in their wallet before the upgrade, otherwise the upgrade will not succeed. This happens in the same transaction as the upgrade. + +_While this mechanism is currently live on the network, the community is currently discussing ways to reduce the cost of upgrades for subgraph developers._ + +### Maintaining a Stable Version of a Subgraph + +If you're making a lot of changes to your subgraph, it is not a good idea to continually upgrade it and front the upgrade costs. Maintaining a stable and consistent version of your subgraph is critical, not only from the cost perspective, but also so that Indexers can feel confident in their syncing times. Indexers should be flagged when you plan for an upgrade so that Indexer syncing times do not get impacted. Feel free to leverage the [#Indexers channel](https://discord.gg/8tgJ7rKW) on Discord to let Indexers know when you're versioning your subgraphs. + +Subgraphs are open API that external developers are leveraging. Open APIs need to follow strict standards so that they do not break external developers' applications. In The Graph Network, a subgraph developer must consider Indexers and how long it takes them to sync a new subgraph **as well as** other developers who are using their subgraphs. + +### Updating the Metadata of a Subgraph + +You can update the metadata of your subgraphs without having to publish a new version. The metadata includes the subgraph name, image, description, website URL, source code URL, and categories. Developers can do this by updating their subgraph details in the Subgraph Studio where you can edit all applicable fields. + +Make sure **Update Subgraph Details in Explorer** is checked and click on **Save**. If this is checked, an an on-chain transaction will be generated that updates subgraph details in the Explorer without having to publish a new version with a new deployment. + +## Best Practices for Deploying a Subgraph to The Graph Network + +1. Leveraging an ENS name for Subgraph Development + +- Set up your ENS: [https://app.ens.domains/](https://app.ens.domains/) +- Add your ENS name to your settings [here](https://thegraph.com/explorer/settings?view=display-name). + +The more filled out your profiles are, the better the chances for your subgraphs to be indexed and curated. + +## Deprecating a Subgraph on The Graph Network + +Follow the steps [here](/developer/deprecating-a-subgraph) to deprecate your subgraph and remove it from The Graph Network. + +## Querying a Subgraph + Billing on The Graph Network + +The Hosted Service was set up to allow developers to deploy their subgraphs without any restrictions. + +In order for The Graph Network to truly be decentralized, query fees have to be paid as a core part of the protocol's incentives. For more information on subscribing to APIs and paying the query fees, check out billing documentation [here](/studio/billing). + +### Estimate Query Fees on the Network + +While this is not a live feature in the product UI, you can set your maximum budget per query by taking the amount you're willing to pay per month and divide it by your expected query volume. + +While you get to decide on your query budget, there is no guarantee that an Indexer will be willing to serve queries at that price. If a Gateway can match you to an Indexer willing to serve a query at, or lower than, the price you are willing to pay, you will pay the delta/difference of your budget **and** their price. As a consequence of that, a lower query price reduces the pool of Indexers available to you, which may affect the quality of service you receive. It's beneficial to have high query fees, as that may attract curation and big name Indexers to your subgraph. + +Remember that it's a dynamic and growing market, but how you interact with it is in your control. There is no maximum or minimum price specified in the protocol or in the Gateways. For example, you can look at the price paid by a few of the dapps on the network (on a per week basis), below. See the last column which shows query fees in GRT. For example, [Pickle Finance](https://www.pickle.finance/) has 8 requests per second and paid 2.4 GRT for one week. + +![QueryFee](/img/QueryFee.png) + +## Additional Resources + +If you're still confused, fear not! Check out the following resources or watch our video guide on migrating subgraphs to the decentralized network below: + +
+ +
+ +- [The Graph Network Contracts](https://github.com/graphprotocol/contracts) +- [Curation Contract](https://github.com/graphprotocol/contracts/blob/dev/contracts/curation/Curation.sol) - the underlying contract that the GNS wraps around + - Address - `0x8fe00a685bcb3b2cc296ff6ffeab10aca4ce1538` +- [Subgraph Studio documentation](/studio/subgraph-studio) diff --git a/pages/es/hosted-service/query-hosted-service.mdx b/pages/es/hosted-service/query-hosted-service.mdx new file mode 100644 index 000000000000..731e3a3120b2 --- /dev/null +++ b/pages/es/hosted-service/query-hosted-service.mdx @@ -0,0 +1,28 @@ +--- +title: Query the Hosted Service +--- + +With the subgraph deployed, visit the [Hosted Service](https://thegraph.com/hosted-service/) to open up a [GraphiQL](https://github.com/graphql/graphiql) interface where you can explore the deployed GraphQL API for the subgraph by issuing queries and viewing the schema. + +An example is provided below, but please see the [Query API](/developer/graphql-api) for a complete reference on how to query the subgraph's entities. + +#### Example + +This query lists all the counters our mapping has created. Since we only create one, the result will only contain our one `default-counter`: + +```graphql +{ + counters { + id + value + } +} +``` + +## Using The Hosted Service + +The Graph Explorer and its GraphQL playground is a useful way to explore and query deployed subgraphs on the Hosted Service. + +Some of the main features are detailed below: + +![Explorer Playground](/img/explorer-playground.png) diff --git a/pages/es/hosted-service/what-is-hosted-service.mdx b/pages/es/hosted-service/what-is-hosted-service.mdx new file mode 100644 index 000000000000..7f604c8dc31a --- /dev/null +++ b/pages/es/hosted-service/what-is-hosted-service.mdx @@ -0,0 +1,77 @@ +--- +title: What is the Hosted Service? +--- + +This section will walk you through deploying a subgraph to the Hosted Service, otherwise known as the [Hosted Service.](https://thegraph.com/hosted-service/) As a reminder, the Hosted Service will not be shut down soon. We will gradually sunset the Hosted Service once we reach feature parity with the decentralized network. Your subgraphs deployed on the Hosted Service are still available [here.](https://thegraph.com/hosted-service/) + +If you don't have an account on the Hosted Service, you can signup with your Github account. Once you authenticate, you can start creating subgraphs through the UI and deploying them from your terminal. Graph Node supports a number of Ethereum testnets (Rinkeby, Ropsten, Kovan) in addition to mainnet. + +## Create a Subgraph + +First follow the instructions [here](/developer/define-subgraph-hosted) to install the Graph CLI. Create a subgraph by passing in `graph init --product hosted service` + +### From an Existing Contract + +If you already have a smart contract deployed to Ethereum mainnet or one of the testnets, bootstrapping a new subgraph from this contract can be a good way to get started on the Hosted Service. + +You can use this command to create a subgraph that indexes all events from an existing contract. This will attempt to fetch the contract ABI from [Etherscan](https://etherscan.io/). + +```sh +graph init \ + --product hosted-service + --from-contract \ + / [] +``` + +Additionally, you can use the following optional arguments. If the ABI cannot be fetched from Etherscan, it falls back to requesting a local file path. If any optional arguments are missing from the command, it takes you through an interactive form. + +```sh +--network \ +--abi \ +``` + +The `` in this case is your github user or organization name, `` is the name for your subgraph, and `` is the optional name of the directory where graph init will put the example subgraph manifest. The `` is the address of your existing contract. `` is the name of the Ethereum network that the contract lives on. `` is a local path to a contract ABI file. **Both --network and --abi are optional.** + +### From an Example Subgraph + +The second mode `graph init` supports is creating a new project from an example subgraph. The following command does this: + +``` +graph init --from-example --product hosted-service / [] +``` + +The example subgraph is based on the Gravity contract by Dani Grant that manages user avatars and emits `NewGravatar` or `UpdateGravatar` events whenever avatars are created or updated. The subgraph handles these events by writing `Gravatar` entities to the Graph Node store and ensuring these are updated according to the events. Continue on to the [subgraph manifest](/developer/create-subgraph-hosted#the-subgraph-manifest) to better understand which events from your smart contracts to pay attention to, mappings, and more. + +## Supported Networks on the Hosted Service + +Please note that the following networks are supported on the Hosted Service. Networks outside of Ethereum mainnet ('mainnet') are not currently supported on [The Graph Explorer.](https://thegraph.com/explorer) + +- `mainnet` +- `kovan` +- `rinkeby` +- `ropsten` +- `goerli` +- `poa-core` +- `poa-sokol` +- `xdai` +- `near-mainnet` +- `near-testnet` +- `matic` +- `mumbai` +- `fantom` +- `bsc` +- `chapel` +- `clover` +- `avalanche` +- `fuji` +- `celo` +- `celo-alfajores` +- `fuse` +- `moonriver` +- `mbase` +- `arbitrum-one` +- `arbitrum-rinkeby` +- `optimism` +- `optimism-kovan` +- `aurora` +- `aurora-testnet` diff --git a/pages/es/indexing.mdx b/pages/es/indexing.mdx index 241841b2e01a..5c0c95375e96 100644 --- a/pages/es/indexing.mdx +++ b/pages/es/indexing.mdx @@ -115,7 +115,7 @@ Los indexadores pueden diferenciarse aplicando técnicas avanzadas para tomar de - **Grande**: Preparado para indexar todos los subgrafos utilizados actualmente y atender solicitudes para el tráfico relacionado. | Configuración | (CPUs) | (memoria en GB) | (disco en TB) | (CPUs) | (memoria en GB) | -| ------------- | :----: | :-------------: | :-----------: | :----: | :-------------: | +| ------------- |:------:|:---------------:|:-------------:|:------:|:---------------:| | Pequeño | 4 | 8 | 1 | 4 | 16 | | Estándar | 8 | 30 | 1 | 12 | 48 | | Medio | 16 | 64 | 2 | 32 | 64 | @@ -149,24 +149,24 @@ Nota: Para admitir el escalado ágil, se recomienda que las inquietudes de consu #### Graph Node -| Puerto | Objeto | Rutas | Argumento CLI | Variable de Entorno | -| --- | --- | --- | --- | --- | -| 8000 | Servidor HTTP GraphQL
(para consultas de subgrafos) | /subgraphs/id/...

/subgraphs/name/.../... | --http-port | - | -| 8001 | GraphQL WS
(para suscripciones a subgrafos) | /subgraphs/id/...

/subgraphs/name/.../... | --ws-port | - | -| 8020 | JSON-RPC
(para administrar implementaciones) | / | --admin-port | - | -| 8030 | API de estado de indexación de subgrafos | /graphql | --index-node-port | - | -| 8040 | Métricas de Prometheus | /metrics | --metrics-port | - | +| Puerto | Objeto | Rutas | Argumento CLI | Variable de Entorno | +| ------ | ---------------------------------------------------------------- | ------------------------------------------------------------------- | ----------------- | ------------------- | +| 8000 | Servidor HTTP GraphQL
(para consultas de subgrafos) | /subgraphs/id/...

/subgraphs/name/.../... | --http-port | - | +| 8001 | GraphQL WS
(para suscripciones a subgrafos) | /subgraphs/id/...

/subgraphs/name/.../... | --ws-port | - | +| 8020 | JSON-RPC
(para administrar implementaciones) | / | --admin-port | - | +| 8030 | API de estado de indexación de subgrafos | /graphql | --index-node-port | - | +| 8040 | Métricas de Prometheus | /metrics | --metrics-port | - | #### Servicio de Indexador -| Puerto | Objeto | Rutas | Argumento CLI | Variable de Entorno | -| --- | --- | --- | --- | --- | -| 7600 | Servidor HTTP GraphQL
(para consultas de subgrafo pagadas) | /subgraphs/id/...
/status
/channel-messages-inbox | --port | `INDEXER_SERVICE_PORT` | -| 7300 | Métricas de Prometheus | /metrics | --metrics-port | - | +| Puerto | Objeto | Rutas | Argumento CLI | Variable de Entorno | +| ------ | ----------------------------------------------------------------------- | --------------------------------------------------------------------------- | -------------- | ---------------------- | +| 7600 | Servidor HTTP GraphQL
(para consultas de subgrafo pagadas) | /subgraphs/id/...
/status
/channel-messages-inbox | --port | `INDEXER_SERVICE_PORT` | +| 7300 | Métricas de Prometheus | /metrics | --metrics-port | - | #### Agente Indexador -| Puerto | Objeto | Rutas | Argumento CLI | Variable de
Entorno | +| Puerto | Objeto | Rutas | Argumento CLI | Variable de
Entorno | | ------ | ----------------------------- | ----- | ------------------------- | --------------------------------------- | | 8000 | API de gestión de indexadores | / | --indexer-management-port | `INDEXER_AGENT_INDEXER_MANAGEMENT_PORT` | diff --git a/pages/es/studio/billing.mdx b/pages/es/studio/billing.mdx new file mode 100644 index 000000000000..9a9d4593cced --- /dev/null +++ b/pages/es/studio/billing.mdx @@ -0,0 +1,68 @@ +--- +title: Billing on the Subgraph Studio +--- + +### Descripción + +Invoices are statements of payment amounts owed by a customer and are typically generated on a weekly basis in the system. You’ll be required to pay fees based on the query fees you generate using your API keys. The billing contract lives on the [Polygon](https://polygon.technology/) network. It’ll allow you to: + +- Add and remove GRT +- Keep track of your balances based on how much GRT you have added to your account, how much you have removed, and your invoices +- Automatically clear payments based on query fees generated + +In order to add GRT to your account, you will need to go through the following steps: + +1. Purchase GRT and ETH on an exchange of your choice +2. Send the GRT and ETH to your wallet +3. Bridge GRT to Polygon using the UI + + a) You will receive 0.001 Matic in a few minutes after you send any amount of GRT to the Polygon bridge. You can track the transaction on [Polygonscan](https://polygonscan.com/) by inputting your address into the search bar. + +4. Add bridged GRT to the billing contract on Polygon. The billing contract address is: [0x10829DB618E6F520Fa3A01c75bC6dDf8722fA9fE](https://polygonscan.com/address/0x10829DB618E6F520Fa3A01c75bC6dDf8722fA9fE). + + a) In order to complete step #4, you'll need to switch your network in your wallet to Polygon. You can add Polygon's network by connecting your wallet and clicking on "Choose Matic (Polygon) Mainnet" [here.](https://chainlist.org/) Once you've added the network, switch it over in your wallet by navigating to the network pill on the top right hand side corner. In Metamask, the network is called **Matic Mainnnet.** + +At the end of each week, if you used your API keys, you will receive an invoice based on the query fees you have generated during this period. This invoice will be paid using GRT available in your balance. Query volume is evaluated by the API keys you own. Your balance will be updated after fees are withdrawn. + +#### Here’s how you go through the invoicing process: + +There are 4 states your invoice can be in: + +1. Created - your invoice has just been created and not been paid yet +2. Paid - your invoice has been successfully paid +3. Unpaid - there is not enough GRT in your balance on the billing contract +4. Error - there is an error processing the payment + +**See the diagram below for more information:** + +![Billing Flow](/img/billing-flow.png) + +For a quick demo of how billing works on the Subgraph Studio, check out the video below: + +
+ +
+ +### Multisig Users + +Multisigs are smart-contracts that can exist only on the network they have been created, so if you created one on Ethereum Mainnet - it will only exist on Mainnet. Since our billing uses Polygon, if you were to bridge GRT to the multisig address on Polygon the funds would be lost. + +To overcome this issue, we created [a dedicated tool](https://multisig-billing.thegraph.com/) that will help you deposit GRT on our billing contract (on behalf of the multisig) with a standard wallet / EOA (an account controlled by a private key). + +You can access our Multisig Billing Tool here: https://multisig-billing.thegraph.com/ + +This tool will guide you to go through the following steps: + +1. Connect your standard wallet / EOA (this wallet needs to own some ETH as well as the GRT you want to deposit) +2. Bridge GRT to Polygon. You will have to wait 7-8 minutes after the transaction is complete for the bridge transfer to be finalized. +3. Once your GRT is available on your Polygon balance you can deposit them to the billing contract while specifying the multisig address you are funding in the `Multisig Address` field. + +Once the deposit transaction has been confirmed you can go back to [Subgraph Studio](https://thegraph.com/studio/) and connect with your Gnosis Safe Multisig to create API keys and use them to generate queries. + +Those queries will generate invoices that will be paid automatically using the multisig’s billing balance. diff --git a/pages/es/studio/deploy-subgraph-studio.mdx b/pages/es/studio/deploy-subgraph-studio.mdx new file mode 100644 index 000000000000..2155d8fe8976 --- /dev/null +++ b/pages/es/studio/deploy-subgraph-studio.mdx @@ -0,0 +1,68 @@ +--- +title: Deploy a Subgraph to the Subgraph Studio +--- + +Deploying a Subgraph to the Subgraph Studio is quite simple. This will take you through the steps to: + +- Install The Graph CLI (with both yarn and npm) +- Create your Subgraph in the Subgraph Studio +- Authenticate your account from the CLI +- Deploying a Subgraph to the Subgraph Studio + +## Installing Graph CLI + +We are using the same CLI to deploy subgraphs to our [hosted service](https://thegraph.com/hosted-service/) and to the [Subgraph Studio](https://thegraph.com/studio/). Here are the commands to install graph-cli. This can be done using npm or yarn. + +**Install with yarn:** + +```bash +yarn global add @graphprotocol/graph-cli +``` + +**Install with npm:** + +```bash +npm install -g @graphprotocol/graph-cli +``` + +## Create your Subgraph in Subgraph Studio + +Before deploying your actual subgraph you need to create a subgraph in [Subgraph Studio](https://thegraph.com/studio/). We recommend you read our [Studio documentation](/studio/subgraph-studio) to learn more about this. + +## Initialize your Subgraph + +Once your subgraph has been created in Subgraph Studio you can initialize the subgraph code using this command: + +```bash +graph init --studio +``` + +The `` value can be found on your subgraph details page in Subgraph Studio: + +![Subgraph Studio - Slug](/img/doc-subgraph-slug.png) + +After running `graph init`, you will be asked to input the contract address, network and abi that you want to query. Doing this will generate a new folder on your local machine with some basic code to start working on your subgraph. You can then finalize your subgraph to make sure it works as expected. + +## Graph Auth + +Before being able to deploy your subgraph to Subgraph Studio, you need to login to your account within the CLI. To do this, you will need your deploy key that you can find on your "My Subgraphs" page or on your subgraph details page. + +Here is the command that you need to use to authenticate from the CLI: + +```bash +graph auth --studio +``` + +## Deploying a Subgraph to Subgraph Studio + +Once you are ready, you can deploy your subgraph to Subgraph Studio. Doing this won't publish your subgraph to the decentralized network, it will only deploy it to your Studio account where you will be able to test it and update the metadata. + +Here is the CLI command that you need to use to deploy your subgraph. + +```bash +graph deploy --studio +``` + +After running this command, the CLI will ask for a version label, you can name it however you want, you can use labels such as `0.1` and `0.2` or use letters as well such as `uniswap-v2-0.1` . Those labels will be visible in Graph Explorer and can be used by curators to decide if they want to signal on this version or not, so choose them wisely. + +Once deployed, you can test your subgraph in Subgraph Studio using the playground, deploy another version if needed, update the metadata, and when you are ready, publish your subgraph to Graph Explorer. diff --git a/pages/es/studio/multisig.mdx b/pages/es/studio/multisig.mdx new file mode 100644 index 000000000000..164835bdb8a4 --- /dev/null +++ b/pages/es/studio/multisig.mdx @@ -0,0 +1,82 @@ +--- +title: Using a Multisig Wallet +--- + +Subgraph Studio currently doesn't support signing with multisig wallets. Until then, you can follow this guide on how to publish your subgraph by invoking the [GNS contract](https://github.com/graphprotocol/contracts/blob/dev/contracts/discovery/GNS.sol) functions. + +### Create a Subgraph + +Similary to using a regular wallet, you can create a subgraph by connecting your non-multisig wallet in Subgraph Studio. Once you connect the wallet, simply create a new subgraph. Make sure you fill out all the details, such as subgraph name, description, image, website, and source code url if applicable. + +For initializing a starter subgraph, you can follow the commands shown in the UI, or simply run + +``` +graph init --studio +``` + +`SUBGRAPH_SLUG` is the name of your subgraph that you can copy from the UI, or from the URL in the browser. This command should create a folder in your file system with all the necessary files to start developing a subgraph. + +### Deploy a Subgraph + +Once your subgraph is ready to be deployed to the graph node, simply follow the commands shown in the UI, or run the following command: + +``` +graph deploy --studio +``` + +**Note**: Make sure that you are inside of the subgraph folder before running the command. + +### Publish a Subgraph or a Version + +You can either publish a new subgraph to the decentralized network or publish a new version of the previously published subgraph. + +#### Publish a New Subgraph + +There are a couple of ways to publish a subgraph using multisig wallets. Here we'll describe invoking the [`publishNewSubgraph`](https://github.com/graphprotocol/contracts/blob/dev/contracts/discovery/GNS.sol#L231) function in the [GNS contract](https://etherscan.io/address/0xaDcA0dd4729c8BA3aCf3E99F3A9f471EF37b6825) using Etherscan. + +Before we use that function, we need to generate input arguments for it. Access [this page](https://thegraph.com/studio/multisig) in Subgraph Studio and provide the following: + +- Ethereum address of your multisig wallet +- Subgraph that you want to publish +- Version that you want to publish + +After clicking on "Get Arguments", we'll generate all the contract arguments for you! + +There should be 4 arguments: + +- `graphAccount`: which is your multisig account address +- `subgraphDeploymentID`: the hex hash of the deployment ID for that subgraph +- `versionMetadata`: version metadata (label and description) that gets uploaded to IPFS. The hex hash value for that JSON file will be provided. +- `subgraphMetadata`: simlar to version metadata, subgraph metadata (name, image, description, website and source code url) gets uploaded to IPFS, and we provide the hex hash value for that JSON file + +With those 4 arguments, you should be able to: + +- Visit [our GraphProxy](https://etherscan.io/address/0xaDcA0dd4729c8BA3aCf3E99F3A9f471EF37b6825#writeProxyContract) contract on Etherscan +- Connect to Etherscan using WalletConnect via the WalletConnect Safe app of your multisig +- Call the `publishNewSubgraph` method with the paramaters that were generated by our tool + +#### Publish a New Version + +To publish a new version of an existing subgraph we first need to generate input arguments for it. Access [this page](https://thegraph.com/studio/multisig) in Subgraph Studio and provide: + +- Ethereum address of your multisig wallet +- Subgraph that you want to publish +- Version that you want to publish +- The ID of the subgraph you want to update in Graph Explorer + +After clicking on "Get Arguments" we'll generate all the contract arguments for you! + +On the right side of the UI under the `Publish New Version` title, there should be 4 arguments: + +- `graphAccount`: which is your Multisig account address +- `subgraphNumber`: is the number of your already published subgraph. It is a part of the subgraph id for a published subgraph queried through The Graph Network subgraph. +- `subgraphDeploymentID`: which is the hex hash of the deployment ID for that subgraph +- `versionMetadata`: version metadata (label and description) gets uploaded to IPFS, and we provide the hex hash value for that JSON file + +Now that we generated all the arguments you are ready to proceed and call the `publishNewVersion` method. In order to do so, you should: + +- Visit [the GraphProxy](https://etherscan.io/address/0xaDcA0dd4729c8BA3aCf3E99F3A9f471EF37b6825#writeProxyContract) contract on Etherscan +- Connect to Etherscan using WalletConnect via the WalletConnect Safe app of your Multisig +- Call the `publishNewVersion` method with the paramaters that were generated by our tool + +Once the transaction is successful, your subgraph should have a new version of your subgraph in Graph Explorer which means that curators can start signaling on it and indexers can start indexing it. diff --git a/pages/es/studio/studio-faq.mdx b/pages/es/studio/studio-faq.mdx new file mode 100644 index 000000000000..4db4d7ccddaa --- /dev/null +++ b/pages/es/studio/studio-faq.mdx @@ -0,0 +1,21 @@ +--- +title: Subgraph Studio FAQs +--- + +### 1. How do I create an API Key? + +In the Subgraph Studio, you can create API Keys as needed and add security settings to each of them. + +### 2. Can I create multiple API Keys? + +A: Yes! You can create multiple API Keys to use in different projects. Check out the link [here](https://thegraph.com/studio/apikeys/). + +### 3. How do I restrict a domain for an API Key? + +After creating an API Key, in the Security section you can define the domains that can query a specific API Key. + +### 4. How do I find query URLs for subgraphs if I’m not the developer of the subgraph I want to use? + +You can find the query URL of each subgraph in the Subgraph Details section of The Graph Explorer. When you click on the “Query” button, you will be directed to a pane wherein you can view the query URL of the subgraph you’re interested in. You can then replace the `` placeholder with the API key you wish to leverage in the Subgraph Studio. + +Remember that you can create an API key and query any subgraph published to the network, even if you build a subgraph yourself. These queries via the new API key, are paid queries as any other on the network. diff --git a/pages/es/studio/subgraph-studio.mdx b/pages/es/studio/subgraph-studio.mdx new file mode 100644 index 000000000000..651fa1c96e67 --- /dev/null +++ b/pages/es/studio/subgraph-studio.mdx @@ -0,0 +1,122 @@ +--- +title: How to Use the Subgraph Studio +--- + +Welcome to your new launchpad 👩🏽‍🚀 + +The Subgraph Studio is your place to build and create subgraphs, add metadata, and publish them to the new decentralized Explorer (more on that [here](/explorer)). + +What you can do in the Subgraph Studio: + +- Create a subgraph through the Studio UI +- Deploy a subgraph using the CLI +- Publish a subgraph with the Studio UI +- Test it in the playground +- Integrate it in staging using the query URL +- Create and manage your API keys for specific subgraphs + +Here in the Subgraph Studio, you have full control over your subgraphs. Not only can you test your subgraphs before you publish them, but you can also restrict your API keys to specific domains and only allow certain indexers to query from their API keys. + +Querying subgraphs generates query fees, used to reward [indexers](/indexing) on the Graph network. If you’re a dapp developer or subgraph developer, the Studio will empower you to build better subgraphs to power your or your community’s queries. The Studio is comprised of 5 main parts: + +- Your user account controls +- A list of subgraphs that you’ve created +- A section to manage, view details, and visualize the status of a specific subgraph +- A section to manage your API keys that you will need to query a subgraph +- A section to manage your billing + +## How to Create Your Account + +1. Sign in with your wallet - you can do this via MetaMask or WalletConnect +1. Once you sign in, you will see your unique deploy key in your account home page. This will allow you to either publish your subgraphs or manage your API keys + billing. You will have a unique deploy key that can be re-generated if you think it has been compromised. + +## How to Create your Subgraph in Subgraph Studio + +The best part! When you first create a subgraph, you’ll be directed to fill out: + +- Your Subgraph Name +- Image +- Description +- Categories +- Website + +## Subgraph Compatibility with The Graph Network + +The Graph Network is not yet able to support all of the data-sources & features available on the Hosted Service. In order to be supported by indexers on the network, subgraphs must: + +- Index mainnet Ethereum +- Must not use any of the following features: + - ipfs.cat & ipfs.map + - Non-fatal errors + - Grafting + +More features & networks will be added to The Graph Network incrementally. + +### Subgraph lifecycle flow + +![Subgraph Lifecycle](/img/subgraph-lifecycle.png) + +After you have created your subgraph, you will be able to deploy it using the [CLI](https://github.com/graphprotocol/graph-cli), or command line interface. Deploying a subgraph with the CLI will push the subgraph to the Studio where you’ll be able to test subgraphs using the playground. This will eventually allow you to publish to the Graph Network. For more information on CLI setup, [check this out](/developer/define-subgraph-hosted#install-the-graph-cli) (pst, make sure you have your deploy key on hand). Remember, deploying is **not the same as** publishing. When you deploy a subgraph, you just push it to the Studio where you’re able to test it. Versus, when you publish a subgraph, you are publishing it on-chain. + +## Testing your Subgraph in Subgraph Studio + +If you’d like to test your subgraph before publishing it to the network, you can do this in the Subgraph **Playground** or look at your logs. The Subgraph logs will tell you **where** your subgraph fails in the case that it does. + +## Publish your Subgraph in Subgraph Studio + +You’ve made it this far - congrats! Publishing your subgraph means that an IPFS hash was generated when you deployed the subgraph within the CLI and is stored in the network’s Ethereum smart contracts. In order to publish your subgraph successfully, you’ll need to go through the following steps outlined in this [blog](https://thegraph.com/blog/building-with-subgraph-studio). Check out the video overview below as well: + +
+ +
+ +Remember, while you’re going through your publishing flow, you’ll be able to push to either mainnet or Rinkeby, the testnet we support. If you’re a first time subgraph developer, we highly suggest you start with publishing to Rinkeby, which is free to do. This will allow you to see how the subgraph will work in The Graph Explorer and will allow you to test curation elements. + +You’ll only be able to index data from mainnet (even if your subgraph was published to a testnet) because only subgraphs that are indexing mainnet data can be published to the network. This is because indexers need to submit mandatory Proof of Indexing records as of a specific block hash. Because publishing a subgraph is an action taken on-chain, remember that the transaction can take up to a few minutes to go through. Any address you use to publish the contract will be the only one able to publish future versions. Choose wisely! + +Subgraphs with curation signal are shown to Indexers so that they can be indexed on the decentralized network. You can publish subgraphs and signal in one transaction, which allows you to mint the first curation signal on the subgraph and saves on gas costs. By adding your signal to the signal later provided by Curators, your subgraph will also have a higher chance of ultimately serving queries. + +**Now that you’ve published your subgraph, let’s get into how you’ll manage them on a regular basis.** Note that you cannot publish your subgraph to the network if it has failed syncing. This is usually because the subgraph has bugs - the logs will tell you where those issues exist! + +## Versioning your Subgraph with the CLI + +Developers might want to update their subgraph, for a variety of reasons. When this is the case, you can deploy a new version of your subgraph to the Studio using the CLI (it will only be private at this point) and if you are happy with it, you can publish this new deployment to The Graph Explorer. This will create a new version of your subgraph that curators can start signaling on and indexers will be able to index this new version. + +Up until recently, developers were forced to deploy and publish a new version of their subgraph to the Explorer to update the metadata of their subgraphs. Now, developers can update the metadata of their subgraphs **without having to publish a new version**. Developers can update their subgraph details in the Studio (under profile picture, name, description, etc) by checking an option called **Update Details** in The Graph Explorer. If this is checked, an on-chain transaction will be generated that updates subgraph details in the Explorer without having to publish a new version with a new deployment. + +Please note that there are costs associated with publishing a new version of a subgraph to the network. In addition to the transaction fees, developers must also fund a part of the curation tax on auto-migrating signal. You cannot publish a new version of your subgraph if curators have not signaled on it. For more information on the risks of curation, please read more [here](/curating). + +### Automatic Archiving of Subgraph Versions + +Whenever you deploy a new subgraph version in the Subgraph Studio, the previous version will be archived. Archived versions won't be indexed/synced and therefore cannot be queried. You can unarchive an archived version of your subgraph in the Studio UI. Please note that previous versions of non-published subgraphs deployed to the Studio will be automatically archived. + +![Subgraph Studio - Unarchive](/img/Unarchive.png) + +## Managing your API Keys + +Regardless of whether you’re a dapp developer or a subgraph developer, you’ll need to manage your API keys. This is important for you to be able to query subgraphs because API keys make sure the connections between application services are valid and authorized. This includes authenticating the end user and the device using the application. + +The Studio will list out existing API keys, which will give you the ability to manage or delete them. + +1. The **Overview** section will allow you to: + - Edit your key name + - Regenerate API keys + - View the current usage of the API key with stats: + - Number of queries + - Amount of GRT spent +2. Under **Manage Security Settings**, you’ll be able to opt into security settings depending on the level of control you’d like to have over your API keys. In this section, you can: + - View and manage the domain names authorized to use your API key + - Assign subgraphs that can be queried with your API key + +## How to Manage your Subgraph + +API keys aside, you’ll have many tools at your disposal to manage your subgraphs. You can organize your subgraphs by their **status** and **category**. + +- The **Status** tag allows you to pick between a variety of tags including ``, ``, ``, ``, etc. +- Meanwhile, **Category** allows you to designate what category your subgraph falls into. Options include ``, ``, ``, etc. diff --git a/pages/es/supported-networks/near.mdx b/pages/es/supported-networks/near.mdx new file mode 100644 index 000000000000..f86cb2b89c0d --- /dev/null +++ b/pages/es/supported-networks/near.mdx @@ -0,0 +1,265 @@ +--- +title: Building Subgraphs on NEAR +--- + +> NEAR support in Graph Node and on the Hosted Service is in beta: please contact near@thegraph.com with any questions about building NEAR subgraphs! + +This guide is an introduction to building subgraphs indexing smart contracts on the [NEAR blockchain](https://docs.near.org/). + +## What is NEAR? + +[NEAR](https://near.org/) is a smart contract platform for building decentralised applications. Visit the [official documentation](https://docs.near.org/docs/concepts/new-to-near) for more information. + +## What are NEAR subgraphs? + +The Graph gives developers tools to process blockchain events and make the resulting data easily available via a GraphQL API, known individually as a subgraph. [Graph Node](https://github.com/graphprotocol/graph-node) is now able to process NEAR events, which means that NEAR developers can now build subgraphs to index their smart contracts. + +Subgraphs are event-based, which means that they listen for and then process on-chain events. There are currently two types of handlers supported for NEAR subgraphs: + +- Block handlers: these are run on every new block +- Receipt handlers: run every time a message is executed at a specified account + +[From the NEAR documentation](https://docs.near.org/docs/concepts/transaction#receipt): + +> A Receipt is the only actionable object in the system. When we talk about "processing a transaction" on the NEAR platform, this eventually means "applying receipts" at some point. + +## Building a NEAR Subgraph + +`@graphprotocol/graph-cli` is a command line tool for building and deploying subgraphs. + +`@graphprotocol/graph-ts` is a library of subgraph-specific types. + +NEAR subgraph development requires `graph-cli` above version `0.23.0`, and `graph-ts` above version `0.23.0`. + +> Building a NEAR subgraph is very similar to building a subgraph which indexes Ethereum. + +There are three aspects of subgraph definition: + +**subgraph.yaml:** the subgraph manifest, defining the data sources of interest, and how they should be processed. NEAR is a new `kind` of data source. + +**schema.graphql:** a schema file that defines what data is stored for your subgraph, and how to query it via GraphQL. The requirements for NEAR subgraphs are covered by [the existing documentation](/developer/create-subgraph-hosted#the-graphql-schema). + +**AssemblyScript Mappings:** [AssemblyScript code](/developer/assemblyscript-api) 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. + +During subgraph development there are two key commands: + +```bash +$ graph codegen # generates types from the schema file identified in the manifest +$ graph build # generates Web Assembly from the AssemblyScript files, and prepares all the subgraph files in a /build folder +``` + +### Subgraph Manifest Definition + +The subgraph manifest (`subgraph.yaml`) identifies the data sources for the subgraph, the triggers of interest, and the functions that should be run in response to those triggers. See below for an example subgraph manifest for a NEAR subgraph:: + +```yaml +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 subgraphs introduce a new `kind` of data source (`near`) +- The `network` should correspond to a network on the hosting Graph Node. On the Hosted Service, 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](https://docs.near.org/docs/concepts/account). This can be an account, or a sub account. + +NEAR data sources support two types of handlers: + +- `blockHandlers`: run on every new NEAR block. No `source.account` is required. +- `receiptHandlers`: run on every receipt where the data source's `source.account` is the recipient. Note that only exact matches are processed ([subaccounts](https://docs.near.org/docs/concepts/account#subaccounts) must be added as independent data sources). + +### Schema Definition + +Schema definition describes the structure of the resulting subgraph database, and the relationships between entities. This is agnostic of the original data source. There are more details on subgraph schema definition [here](/developer/create-subgraph-hosted#the-graphql-schema). + +### AssemblyScript Mappings + +The handlers for processing events are written in [AssemblyScript](https://www.assemblyscript.org/). + +NEAR indexing introduces NEAR-specific data types to the [AssemblyScript API](/developer/assemblyscript-api). + +```typescript + +class ExecutionOutcome { + gasBurnt: u64, + blockHash: Bytes, + id: Bytes, + logs: Array, + receiptIds: Array, + tokensBurnt: BigInt, + executorId: string, + } + +class ActionReceipt { + predecessorId: string, + receiverId: string, + id: CryptoHash, + signerId: string, + gasPrice: BigInt, + outputDataReceivers: Array, + inputDataIds: Array, + actions: Array, + } + +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, + } + +class ReceiptWithOutcome { + outcome: ExecutionOutcome, + receipt: ActionReceipt, + block: Block, + } +``` + +These types are passed to block & receipt handlers: + +- Block handlers will receive a `Block` +- Receipt handlers will receive a `ReceiptWithOutcome` + +Otherwise the rest of the [AssemblyScript API](/developer/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](/developer/assemblyscript-api#json-api) to allow developers to easily process these logs. + +## Deploying a NEAR Subgraph + +Once you have a built subgraph, it is time to deploy it to Graph Node for indexing. NEAR subgraphs can be deployed to any Graph Node `>=v0.26.x` (this version has not yet been tagged & released). + +The Graph's Hosted Service 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 the Hosted Service can be found [here](/hosted-service/deploy-subgraph-hosted). + +As a quick primer - the first step is to "create" your subgraph - this only needs to be done once. On the Hosted Service, this can be done from [your Dashboard](https://thegraph.com/hosted-service/dashboard): "Add Subgraph". + +Once your subgraph has been created, you can deploy your subgraph by using the `graph deploy` CLI command: + +``` +$ graph create --node subgraph/name # creates a subgraph on a local Graph Node (on the Hosted Service, this is done via the UI) +$ graph deploy --node --ipfs https://api.thegraph.com/ipfs/ # 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 +``` + +The node configuration will depend where the subgraph is being deployed. + +#### Hosted Service: + +``` +graph deploy --node https://api.thegraph.com/deploy/ --ipfs https://api.thegraph.com/ipfs/ --access-token +``` + +#### Local Graph Node (based on default configuration): + +``` +graph deploy --node http://localhost:8020/ --ipfs http://localhost:5001 +``` + +Once your subgraph has been deployed, it will be indexed by Graph Node. You can check its progress by querying the subgraph itself: + +``` +{ + _meta { + block { number } + } +} +``` + +### Indexing NEAR with a Local Graph Node + +Running a Graph Node that indexes NEAR has the following operational requirements: + +- NEAR Indexer Framework with Firehose instrumentation +- NEAR Firehose Component(s) +- Graph Node with Firehose endpoint configured + +We will provide more information on running the above components soon. + +## Querying a NEAR Subgraph + +The GraphQL endpoint for NEAR subgraphs is determined by the schema definition, with the existing API interface. Please visit the [GraphQL API documentation](/developer/graphql-api) for more information. + +## Example Subgraphs + +Here are some example subgraphs for reference: + +[NEAR Blocks](https://github.com/graphprotocol/example-subgraph/tree/near-blocks-example) + +[NEAR Receipts](https://github.com/graphprotocol/example-subgraph/tree/near-receipts-example) + +## Preguntas frecuentes + +### How does the beta work? + +NEAR support is in beta, which means that there may be changes to the API as we continue to work on improving the integration. Please email near@thegraph.com so that we can support you in building NEAR subgraphs, and keep you up to date on the latest developments! + +### Can a subgraph index both NEAR and EVM chains? + +No, a subgraph can only support data sources from one chain / network. + +### Can subgraphs react to more specific triggers? + +Currently, only Block and Receipt triggers are supported. We are investigating triggers for function calls to a specified account. We are also interested in supporting event triggers, once NEAR has native event support. + +### Will receipt handlers trigger for accounts and their sub accounts? + +Receipt handlers will only be triggered for the exact-match of the named account. More flexibility may be added in future. + +### Can NEAR subgraphs make view calls to NEAR accounts during mappings? + +This is not supported. We are evaluating whether this functionality is required for indexing. + +### Can I use data source templates in my NEAR subgraph? + +This is not currently supported. We are evaluating whether this functionality is required for indexing. + +### Ethereum subgraphs support "pending" and "current" versions, how can I deploy a "pending" version of a NEAR subgraph? + +Pending functionality is not yet supported for NEAR subgraphs. In the interim, you can deploy a new version to a different "named" subgraph, and then when that is synced with the chain head, you can redeploy to your primary "named" subgraph, which will use the same underlying deployment ID, so the main subgraph will be instantly synced. + +### My question hasn't been answered, where can I get more help building NEAR subgraphs? + +If it is a general question about subgraph development, there is a lot more information in the rest of the [Developer documentation](/developer/quick-start). Otherwise please join [The Graph Protocol Discord](https://discord.gg/vtvv7FP) and ask in the #near channel, or email near@thegraph.com. + +## References + +- [NEAR developer documentation](https://docs.near.org/docs/develop/basics/getting-started) diff --git a/pages/ja/about/introduction.mdx b/pages/ja/about/introduction.mdx new file mode 100644 index 000000000000..5f840c040400 --- /dev/null +++ b/pages/ja/about/introduction.mdx @@ -0,0 +1,47 @@ +--- +title: Introduction +--- + +This page will explain what The Graph is and how you can get started. + +## What The Graph Is + +The Graph is a decentralized protocol for indexing and querying data from blockchains, starting with Ethereum. It makes it possible to query data that is difficult to query directly. + +Projects with complex smart contracts like [Uniswap](https://uniswap.org/) and NFTs initiatives like [Bored Ape Yacht Club](https://boredapeyachtclub.com/) store data on the Ethereum blockchain, making it really difficult to read anything other than basic data directly from the blockchain. + +In the case of Bored Ape Yacht Club, we can perform basic read operations on [the contract](https://etherscan.io/address/0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d#code) like getting the owner of a certain Ape, getting the content URI of an Ape based on their ID, or the total supply, as these read operations are programmed directly into the smart contract, but more advanced real-world queries and operations like aggregation, search, relationships, and non-trivial filtering are not possible. For example, if we wanted to query for apes that are owned by a certain address, and filter by one of its characteristics, we would not be able to get that information by interacting directly with the contract itself. + +To get this data, you would have to process every single [`transfer`](https://etherscan.io/address/0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d#code#L1746) event ever emitted, read the metadata from IPFS using the Token ID and IPFS hash, and then aggregate it. Even for these types of relatively simple questions, it would take **hours or even days** for a decentralized application (dapp) running in a browser to get an answer. + +You could also build out your own server, process the transactions there, save them to a database, and build an API endpoint on top of it all in order to query the data. However, this option is resource intensive, needs maintenance, presents a single point of failure, and breaks important security properties required for decentralization. + +**Indexing blockchain data is really, really hard.** + +Blockchain properties like finality, chain reorganizations, or uncled blocks complicate this process further, and make it not just time consuming but conceptually hard to retrieve correct query results from blockchain data. + +The Graph solves this with a decentralized protocol that indexes and enables the performant and efficient querying of blockchain data. These APIs (indexed "subgraphs") can then be queried with a standard GraphQL API. Today, there is a hosted service as well as a decentralized protocol with the same capabilities. Both are backed by the open source implementation of [Graph Node](https://github.com/graphprotocol/graph-node). + +## How The Graph Works + +The Graph learns what and how to index Ethereum data based on subgraph descriptions, known as the subgraph manifest. The subgraph description defines the smart contracts of interest for a subgraph, the events in those contracts to pay attention to, and how to map event data to data that The Graph will store in its database. + +Once you have written a `subgraph manifest`, you use the Graph CLI to store the definition in IPFS and tell the indexer to start indexing data for that subgraph. + +This diagram gives more detail about the flow of data once a subgraph manifest has been deployed, dealing with Ethereum transactions: + +![](/img/graph-dataflow.png) + +The flow follows these steps: + +1. A decentralized application adds data to Ethereum through a transaction on a smart contract. +2. The smart contract emits one or more events while processing the transaction. +3. Graph Node continually scans Ethereum for new blocks and the data for your subgraph they may contain. +4. Graph Node finds Ethereum events for your subgraph in these blocks and runs the mapping handlers you provided. The mapping is a WASM module that creates or updates the data entities that Graph Node stores in response to Ethereum events. +5. The decentralized application queries the Graph Node for data indexed from the blockchain, using the node's [GraphQL endpoint](https://graphql.org/learn/). The Graph Node in turn translates the GraphQL queries into queries for its underlying data store in order to fetch this data, making use of the store's indexing capabilities. The decentralized application displays this data in a rich UI for end-users, which they use to issue new transactions on Ethereum. The cycle repeats. + +## Next Steps + +In the following sections we will go into more detail on how to define subgraphs, how to deploy them, and how to query data from the indexes that Graph Node builds. + +Before you start writing your own subgraph, you might want to have a look at the Graph Explorer and explore some of the subgraphs that have already been deployed. The page for each subgraph contains a playground that lets you query that subgraph's data with GraphQL. diff --git a/pages/ja/about/network.mdx b/pages/ja/about/network.mdx new file mode 100644 index 000000000000..b19f08d12bc7 --- /dev/null +++ b/pages/ja/about/network.mdx @@ -0,0 +1,15 @@ +--- +title: Network Overview +--- + +The Graph Network is a decentralized indexing protocol for organizing blockchain data. Applications use GraphQL to query open APIs called subgraphs, to retrieve data that is indexed on the network. With The Graph, developers can build serverless applications that run entirely on public infrastructure. + +> GRT Token Address: [0xc944e90c64b2c07662a292be6244bdf05cda44a7](https://etherscan.io/token/0xc944e90c64b2c07662a292be6244bdf05cda44a7) + +## Overview + +The Graph Network consists of Indexers, Curators and Delegators that provide services to the network, and serve data to Web3 applications. Consumers use the applications and consume the data. + +![Token Economics](/img/Network-roles@2x.png) + +To ensure economic security of The Graph Network and the integrity of data being queried, participants stake and use Graph Tokens (GRT). GRT is a work token that is an ERC-20 on the Ethereum blockchain, used to allocate resources in the network. Active Indexers, Curators and Delegators can provide services and earn income from the network, proportional to the amount of work they perform and their GRT stake. diff --git a/pages/ja/curating.mdx b/pages/ja/curating.mdx index 21d71223169c..1748d663907a 100644 --- a/pages/ja/curating.mdx +++ b/pages/ja/curating.mdx @@ -81,7 +81,7 @@ The Graph の場合は、 [Bancor が実装しているボンディングカー ### 3. サブグラフのアップグレードにかかるコストは？ -Migrating your curation shares to a new subgraph version incurs a curation tax of 1%. Curators can choose to subscribe to the newest version of a subgraph. キュレーターのシェアが新バージョンに自動移行されると、キュレーターはキュレーション税の半分、つまり 0.5％を支払うことになります。 なぜなら、サブグラフのアップグレードはオンチェーンアクションとしてガスを消費するからです。 +Migrating your curation shares to a new subgraph version incurs a curation tax of 1%. Curators can choose to subscribe to the newest version of a subgraph. When curator shares get auto-migrated to a new version, Curators will also pay half curation tax, ie. 0.5%, because upgrading subgraphs is an on-chain action which costs gas. ### 4. どのくらいの頻度でサブグラフをアップグレードできますか？ @@ -100,5 +100,5 @@ Still confused? その他の不明点に関しては、 以下のキュレーシ title="YouTubeビデオプレーヤー" frameBorder="0" allowFullScreen - > +> diff --git a/pages/ja/delegating.mdx b/pages/ja/delegating.mdx index c397fe8a8669..a184aefd3b63 100644 --- a/pages/ja/delegating.mdx +++ b/pages/ja/delegating.mdx @@ -39,8 +39,8 @@ This guide will explain how to be an effective delegator in the Graph Network. D インデキシング報酬カット - インデキシング報酬カットは、インデクサーが自分のために保持する報酬の部分です。 つまり、これが 100%に設定されていると、デリゲーターであるあなたは 0 のインデキシング報酬を得ることになります。 UI に 80%と表示されている場合は、デリゲーターとして 20%を受け取ることになります。 重要な注意点として、ネットワークの初期段階では、インデキシング報酬が報酬の大半を占めます。
- トップのインデクサーは、デリゲーターに90％の報酬を与えています。 中間層では、デリゲーターに20％を与えています。 - 一番下のものは、デリゲーターに～83％を与えています。 + トップのインデクサーは、デリゲーターに90％の報酬を与えています。 The + middle one is giving delegators 20%. The bottom one is giving delegators ~83%.*
- クエリーフィーカット - これはインデキシングリワードカットと全く同じ働きをします。 しかし、これは特に、インデクサーが収集したクエリフィーに対するリターンを対象としています。 ネットワークの初期段階では、クエリフィーからのリターンは、インデキシング報酬に比べて非常に小さいことに注意する必要があります。 ネットワーク内のクエリフィーがいつから大きくなり始めるのかを判断するために、ネットワークに注意を払うことをお勧めします。 @@ -89,5 +89,5 @@ A delegator can therefore do the math to determine that the Indexer offering 20% title="YouTubeビデオプレーヤー" frameBorder="0" allowFullScreen - > +> diff --git a/pages/ja/developer/assemblyscript-api.mdx b/pages/ja/developer/assemblyscript-api.mdx new file mode 100644 index 000000000000..a609e6cd657f --- /dev/null +++ b/pages/ja/developer/assemblyscript-api.mdx @@ -0,0 +1,714 @@ +--- +title: AssemblyScript API +--- + +> Note: if you created a subgraph prior to `graph-cli`/`graph-ts` version `0.22.0`, you're using an older version of AssemblyScript, we recommend taking a look at the [`Migration Guide`](/developer/assemblyscript-migration-guide) + +This page documents what built-in APIs can be used when writing subgraph mappings. Two kinds of APIs are available out of the box: + +- the [Graph TypeScript library](https://github.com/graphprotocol/graph-ts) (`graph-ts`) and +- code generated from subgraph files by `graph codegen`. + +It is also possible to add other libraries as dependencies, as long as they are compatible with [AssemblyScript](https://github.com/AssemblyScript/assemblyscript). Since this is the language mappings are written in, the [AssemblyScript wiki](https://github.com/AssemblyScript/assemblyscript/wiki) is a good source for language and standard library features. + +## Installation + +Subgraphs created with [`graph init`](/developer/create-subgraph-hosted) come with preconfigured dependencies. All that is required to install these dependencies is to run one of the following commands: + +```sh +yarn install # Yarn +npm install # NPM +``` + +If the subgraph was created from scratch, one of the following two commands will install the Graph TypeScript library as a dependency: + +```sh +yarn add --dev @graphprotocol/graph-ts # Yarn +npm install --save-dev @graphprotocol/graph-ts # NPM +``` + +## API Reference + +The `@graphprotocol/graph-ts` library provides the following APIs: + +- An `ethereum` API for working with Ethereum smart contracts, events, blocks, transactions, and Ethereum values. +- A `store` API to load and save entities from and to the Graph Node store. +- A `log` API to log messages to the Graph Node output and the Graph Explorer. +- An `ipfs` API to load files from IPFS. +- A `json` API to parse JSON data. +- A `crypto` API to use cryptographic functions. +- Low-level primitives to translate between different type systems such as Ethereum, JSON, GraphQL and AssemblyScript. + +### Versions + +The `apiVersion` in the subgraph manifest specifies the mapping API version which is run by Graph Node for a given subgraph. The current mapping API version is 0.0.6. + +| Version | Release notes | +|:-------:| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 0.0.6 | Added `nonce` field to the Ethereum Transaction object
Added `baseFeePerGas` to the Ethereum Block object | +| 0.0.5 | AssemblyScript upgraded to version 0.19.10 (this includes breaking changes, please see the [`Migration Guide`](/developer/assemblyscript-migration-guide))
`ethereum.transaction.gasUsed` renamed to `ethereum.transaction.gasLimit` | +| 0.0.4 | Added `functionSignature` field to the Ethereum SmartContractCall object | +| 0.0.3 | Added `from` field to the Ethereum Call object
`etherem.call.address` renamed to `ethereum.call.to` | +| 0.0.2 | Added `input` field to the Ethereum Transaction object | + +### Built-in Types + +Documentation on the base types built into AssemblyScript can be found in the [AssemblyScript wiki](https://github.com/AssemblyScript/assemblyscript/wiki/Types). + +The following additional types are provided by `@graphprotocol/graph-ts`. + +#### ByteArray + +```typescript +import { ByteArray } from '@graphprotocol/graph-ts' +``` + +`ByteArray` represents an array of `u8`. + +_Construction_ + +- `fromI32(x: i32): ByteArray` - Decomposes `x` into bytes. +- `fromHexString(hex: string): ByteArray` - Input length must be even. Prefixing with `0x` is optional. + +_Type conversions_ + +- `toHexString(): string` - Converts to a hex string prefixed with `0x`. +- `toString(): string` - Interprets the bytes as a UTF-8 string. +- `toBase58(): string` - Encodes the bytes into a base58 string. +- `toU32(): u32` - Interprets the bytes as a little-endian `u32`. Throws in case of overflow. +- `toI32(): i32` - Interprets the byte array as a little-endian `i32`. Throws in case of overflow. + +_Operators_ + +- `equals(y: ByteArray): bool` – can be written as `x == y`. + +#### BigDecimal + +```typescript +import { BigDecimal } from '@graphprotocol/graph-ts' +``` + +`BigDecimal` is used to represent arbitrary precision decimals. + +_Construction_ + +- `constructor(bigInt: BigInt)` – creates a `BigDecimal` from an `BigInt`. +- `static fromString(s: string): BigDecimal` – parses from a decimal string. + +_Type conversions_ + +- `toString(): string` – prints to a decimal string. + +_Math_ + +- `plus(y: BigDecimal): BigDecimal` – can be written as `x + y`. +- `minus(y: BigDecimal): BigDecimal` – can be written as `x - y`. +- `times(y: BigDecimal): BigDecimal` – can be written as `x * y`. +- `dividedBy(y: BigDecimal): BigDecimal` – can be written as `x / y`. +- `equals(y: BigDecimal): bool` – can be written as `x == y`. +- `notEqual(y: BigDecimal): bool` – can be written as `x != y`. +- `lt(y: BigDecimal): bool` – can be written as `x < y`. +- `le(y: BigDecimal): bool` – can be written as `x <= y`. +- `gt(y: BigDecimal): bool` – can be written as `x > y`. +- `ge(y: BigDecimal): bool` – can be written as `x >= y`. +- `neg(): BigDecimal` - can be written as `-x`. + +#### BigInt + +```typescript +import { BigInt } from '@graphprotocol/graph-ts' +``` + +`BigInt` is used to represent big integers. This includes Ethereum values of type `uint32` to `uint256` and `int64` to `int256`. Everything below `uint32`, such as `int32`, `uint24` or `int8` is represented as `i32`. + +The `BigInt` class has the following API: + +_Construction_ + +- `BigInt.fromI32(x: i32): BigInt` – creates a `BigInt` from an `i32`. +- `BigInt.fromString(s: string): BigInt`– Parses a `BigInt` from a string. +- `BigInt.fromUnsignedBytes(x: Bytes): BigInt` – Interprets `bytes` as an unsigned, little-endian integer. If your input is big-endian, call `.reverse()` first. +- `BigInt.fromSignedBytes(x: Bytes): BigInt` – Interprets `bytes` as a signed, little-endian integer. If your input is big-endian, call `.reverse()` first. + + _Type conversions_ + +- `x.toHex(): string` – turns `BigInt` into a string of hexadecimal characters. +- `x.toString(): string` – turns `BigInt` into a decimal number string. +- `x.toI32(): i32` – returns the `BigInt` as an `i32`; fails if it the value does not fit into `i32`. It's a good idea to first check `x.isI32()`. +- `x.toBigDecimal(): BigDecimal` - converts into a decimal with no fractional part. + +_Math_ + +- `x.plus(y: BigInt): BigInt` – can be written as `x + y`. +- `x.minus(y: BigInt): BigInt` – can be written as `x - y`. +- `x.times(y: BigInt): BigInt` – can be written as `x * y`. +- `x.dividedBy(y: BigInt): BigInt` – can be written as `x / y`. +- `x.mod(y: BigInt): BigInt` – can be written as `x % y`. +- `x.equals(y: BigInt): bool` – can be written as `x == y`. +- `x.notEqual(y: BigInt): bool` – can be written as `x != y`. +- `x.lt(y: BigInt): bool` – can be written as `x < y`. +- `x.le(y: BigInt): bool` – can be written as `x <= y`. +- `x.gt(y: BigInt): bool` – can be written as `x > y`. +- `x.ge(y: BigInt): bool` – can be written as `x >= y`. +- `x.neg(): BigInt` – can be written as `-x`. +- `x.divDecimal(y: BigDecimal): BigDecimal` – divides by a decimal, giving a decimal result. +- `x.isZero(): bool` – Convenience for checking if the number is zero. +- `x.isI32(): bool` – Check if the number fits in an `i32`. +- `x.abs(): BigInt` – Absolute value. +- `x.pow(exp: u8): BigInt` – Exponentiation. +- `bitOr(x: BigInt, y: BigInt): BigInt` – can be written as `x | y`. +- `bitAnd(x: BigInt, y: BigInt): BigInt` – can be written as `x & y`. +- `leftShift(x: BigInt, bits: u8): BigInt` – can be written as `x << y`. +- `rightShift(x: BigInt, bits: u8): BigInt` – can be written as `x >> y`. + +#### TypedMap + +```typescript +import { TypedMap } from '@graphprotocol/graph-ts' +``` + +`TypedMap` can be used to stored key-value pairs. See [this example](https://github.com/graphprotocol/aragon-subgraph/blob/29dd38680c5e5104d9fdc2f90e740298c67e4a31/individual-dao-subgraph/mappings/constants.ts#L51). + +The `TypedMap` class has the following API: + +- `new TypedMap()` – creates an empty map with keys of type `K` and values of type `T` +- `map.set(key: K, value: V): void` – sets the value of `key` to `value` +- `map.getEntry(key: K): TypedMapEntry | null` – returns the key-value pair for a `key` or `null` if the `key` does not exist in the map +- `map.get(key: K): V | null` – returns the value for a `key` or `null` if the `key` does not exist in the map +- `map.isSet(key: K): bool` – returns `true` if the `key` exists in the map and `false` if it does not + +#### Bytes + +```typescript +import { Bytes } from '@graphprotocol/graph-ts' +``` + +`Bytes` is used to represent arbitrary-length arrays of bytes. This includes Ethereum values of type `bytes`, `bytes32` etc. + +The `Bytes` class extends AssemblyScript's [Uint8Array](https://github.com/AssemblyScript/assemblyscript/blob/3b1852bc376ae799d9ebca888e6413afac7b572f/std/assembly/typedarray.ts#L64) and this supports all the `Uint8Array` functionality, plus the following new methods: + +- `b.toHex()` – returns a hexadecimal string representing the bytes in the array +- `b.toString()` – converts the bytes in the array to a string of unicode characters +- `b.toBase58()` – turns an Ethereum Bytes value to base58 encoding (used for IPFS hashes) + +#### Address + +```typescript +import { Address } from '@graphprotocol/graph-ts' +``` + +`Address` extends `Bytes` to represent Ethereum `address` values. + +It adds the following method on top of the `Bytes` API: + +- `Address.fromString(s: string): Address` – creates an `Address` from a hexadecimal string + +### Store API + +```typescript +import { store } from '@graphprotocol/graph-ts' +``` + +The `store` API allows to load, save and remove entities from and to the Graph Node store. + +Entities written to the store map one-to-one to the `@entity` types defined in the subgraph's GraphQL schema. To make working with these entities convenient, the `graph codegen` command provided by the [Graph CLI](https://github.com/graphprotocol/graph-cli) generates entity classes, which are subclasses of the built-in `Entity` type, with property getters and setters for the fields in the schema as well as methods to load and save these entities. + +#### Creating entities + +The following is a common pattern for creating entities from Ethereum events. + +```typescript +// Import the Transfer event class generated from the ERC20 ABI +import { Transfer as TransferEvent } from '../generated/ERC20/ERC20' + +// Import the Transfer entity type generated from the GraphQL schema +import { Transfer } from '../generated/schema' + +// Transfer event handler +export function handleTransfer(event: TransferEvent): void { + // Create a Transfer entity, using the hexadecimal string representation + // of the transaction hash as the entity ID + let id = event.transaction.hash.toHex() + let transfer = new Transfer(id) + + // Set properties on the entity, using the event parameters + transfer.from = event.params.from + transfer.to = event.params.to + transfer.amount = event.params.amount + + // Save the entity to the store + transfer.save() +} +``` + +When a `Transfer` event is encountered while processing the chain, it is passed to the `handleTransfer` event handler using the generated `Transfer` type (aliased to `TransferEvent` here to avoid a naming conflict with the entity type). This type allows accessing data such as the event's parent transaction and its parameters. + +Each entity must have a unique ID to avoid collisions with other entities. It is fairly common for event parameters to include a unique identifier that can be used. Note: Using the transaction hash as the ID assumes that no other events in the same transaction create entities with this hash as the ID. + +#### Loading entities from the store + +If an entity already exists, it can be loaded from the store with the following: + +```typescript +let id = event.transaction.hash.toHex() // or however the ID is constructed +let transfer = Transfer.load(id) +if (transfer == null) { + transfer = new Transfer(id) +} + +// Use the Transfer entity as before +``` + +As the entity may not exist in the store yet, the `load` method returns a value of type `Transfer | null`. It may thus be necessary to check for the `null` case before using the value. + +> **Note:** Loading entities is only necessary if the changes made in the mapping depend on the previous data of an entity. See the next section for the two ways of updating existing entities. + +#### Updating existing entities + +There are two ways to update an existing entity: + +1. Load the entity with e.g. `Transfer.load(id)`, set properties on the entity, then `.save()` it back to the store. +2. Simply create the entity with e.g. `new Transfer(id)`, set properties on the entity, then `.save()` it to the store. If the entity already exists, the changes are merged into it. + +Changing properties is straight forward in most cases, thanks to the generated property setters: + +```typescript +let transfer = new Transfer(id) +transfer.from = ... +transfer.to = ... +transfer.amount = ... +``` + +It is also possible to unset properties with one of the following two instructions: + +```typescript +transfer.from.unset() +transfer.from = null +``` + +This only works with optional properties, i.e. properties that are declared without a `!` in GraphQL. Two examples would be `owner: Bytes` or `amount: BigInt`. + +Updating array properties is a little more involved, as the getting an array from an entity creates a copy of that array. This means array properties have to be set again explicitly after changing the array. The following assumes `entity` has a `numbers: [BigInt!]!` field. + +```typescript +// This won't work +entity.numbers.push(BigInt.fromI32(1)) +entity.save() + +// This will work +let numbers = entity.numbers +numbers.push(BigInt.fromI32(1)) +entity.numbers = numbers +entity.save() +``` + +#### Removing entities from the store + +There is currently no way to remove an entity via the generated types. Instead, removing an entity requires passing the name of the entity type and the entity ID to `store.remove`: + +```typescript +import { store } from '@graphprotocol/graph-ts' +... +let id = event.transaction.hash.toHex() +store.remove('Transfer', id) +``` + +### Ethereum API + +The Ethereum API provides access to smart contracts, public state variables, contract functions, events, transactions, blocks and the encoding/decoding Ethereum data. + +#### Support for Ethereum Types + +As with entities, `graph codegen` generates classes for all smart contracts and events used in a subgraph. For this, the contract ABIs need to be part of the data source in the subgraph manifest. Typically, the ABI files are stored in an `abis/` folder. + +With the generated classes, conversions between Ethereum types and the [built-in types](#built-in-types) take place behind the scenes so that subgraph authors do not have to worry about them. + +The following example illustrates this. Given a subgraph schema like + +```graphql +type Transfer @entity { + from: Bytes! + to: Bytes! + amount: BigInt! +} +``` + +and a `Transfer(address,address,uint256)` event signature on Ethereum, the `from`, `to` and `amount` values of type `address`, `address` and `uint256` are converted to `Address` and `BigInt`, allowing them to be passed on to the `Bytes!` and `BigInt!` properties of the `Transfer` entity: + +```typescript +let id = event.transaction.hash.toHex() +let transfer = new Transfer(id) +transfer.from = event.params.from +transfer.to = event.params.to +transfer.amount = event.params.amount +transfer.save() +``` + +#### Events and Block/Transaction Data + +Ethereum events passed to event handlers, such as the `Transfer` event in the previous examples, not only provide access to the event parameters but also to their parent transaction and the block they are part of. The following data can be obtained from `event` instances (these classes are a part of the `ethereum` module in `graph-ts`): + +```typescript +class Event { + address: Address + logIndex: BigInt + transactionLogIndex: BigInt + logType: string | null + block: Block + transaction: Transaction + parameters: Array +} + +class Block { + hash: Bytes + parentHash: Bytes + unclesHash: Bytes + author: Address + stateRoot: Bytes + transactionsRoot: Bytes + receiptsRoot: Bytes + number: BigInt + gasUsed: BigInt + gasLimit: BigInt + timestamp: BigInt + difficulty: BigInt + totalDifficulty: BigInt + size: BigInt | null + baseFeePerGas: BigInt | null +} + +class Transaction { + hash: Bytes + index: BigInt + from: Address + to: Address | null + value: BigInt + gasLimit: BigInt + gasPrice: BigInt + input: Bytes + nonce: BigInt +} +``` + +#### Access to Smart Contract State + +The code generated by `graph codegen` also includes classes for the smart contracts used in the subgraph. These can be used to access public state variables and call functions of the contract at the current block. + +A common pattern is to access the contract from which an event originates. This is achieved with the following code: + +```typescript +// Import the generated contract class +import { ERC20Contract } from '../generated/ERC20Contract/ERC20Contract' +// Import the generated entity class +import { Transfer } from '../generated/schema' + +export function handleTransfer(event: Transfer) { + // Bind the contract to the address that emitted the event + let contract = ERC20Contract.bind(event.address) + + // Access state variables and functions by calling them + let erc20Symbol = contract.symbol() +} +``` + +As long as the `ERC20Contract` on Ethereum has a public read-only function called `symbol`, it can be called with `.symbol()`. For public state variables a method with the same name is created automatically. + +Any other contract that is part of the subgraph can be imported from the generated code and can be bound to a valid address. + +#### Handling Reverted Calls + +If the read-only methods of your contract may revert, then you should handle that by calling the generated contract method prefixed with `try_`. For example, the Gravity contract exposes the `gravatarToOwner` method. This code would be able to handle a revert in that method: + +```typescript +let gravity = Gravity.bind(event.address) +let callResult = gravity.try_gravatarToOwner(gravatar) +if (callResult.reverted) { + log.info('getGravatar reverted', []) +} else { + let owner = callResult.value +} +``` + +Note that a Graph node connected to a Geth or Infura client may not detect all reverts, if you rely on this we recommend using a Graph node connected to a Parity client. + +#### Encoding/Decoding ABI + +Data can be encoded and decoded according to Ethereum's ABI encoding format using the `encode` and `decode` functions in the `ethereum` module. + +```typescript +import { Address, BigInt, ethereum } from '@graphprotocol/graph-ts' + +let tupleArray: Array = [ + ethereum.Value.fromAddress(Address.fromString('0x0000000000000000000000000000000000000420')), + ethereum.Value.fromUnsignedBigInt(BigInt.fromI32(62)), +] + +let tuple = tupleArray as ethereum.Tuple + +let encoded = ethereum.encode(ethereum.Value.fromTuple(tuple))! + +let decoded = ethereum.decode('(address,uint256)', encoded) +``` + +For more information: + +- [ABI Spec](https://docs.soliditylang.org/en/v0.7.4/abi-spec.html#types) +- Encoding/decoding [Rust library/CLI](https://github.com/rust-ethereum/ethabi) +- More [complex example](https://github.com/graphprotocol/graph-node/blob/6a7806cc465949ebb9e5b8269eeb763857797efc/tests/integration-tests/host-exports/src/mapping.ts#L72). + +### Logging API + +```typescript +import { log } from '@graphprotocol/graph-ts' +``` + +The `log` API allows subgraphs to log information to the Graph Node standard output as well as the Graph Explorer. Messages can be logged using different log levels. A basic format string syntax is provided to compose log messages from argument. + +The `log` API includes the following functions: + +- `log.debug(fmt: string, args: Array): void` - logs a debug message. +- `log.info(fmt: string, args: Array): void` - logs an informational message. +- `log.warning(fmt: string, args: Array): void` - logs a warning. +- `log.error(fmt: string, args: Array): void` - logs an error message. +- `log.critical(fmt: string, args: Array): void` – logs a critical message _and_ terminates the subgraph. + +The `log` API takes a format string and an array of string values. It then replaces placeholders with the string values from the array. The first `{}` placeholder gets replaced by the first value in the array, the second `{}` placeholder gets replaced by the second value and so on. + +```typescript +log.info('Message to be displayed: {}, {}, {}', [value.toString(), anotherValue.toString(), 'already a string']) +``` + +#### Logging one or more values + +##### Logging a single value + +In the example below, the string value "A" is passed into an array to become`['A']` before being logged: + +```typescript +let myValue = 'A' + +export function handleSomeEvent(event: SomeEvent): void { + // Displays : "My value is: A" + log.info('My value is: {}', [myValue]) +} +``` + +##### Logging a single entry from an existing array + +In the example below, only the first value of the argument array is logged, despite the array containing three values. + +```typescript +let myArray = ['A', 'B', 'C'] + +export function handleSomeEvent(event: SomeEvent): void { + // Displays : "My value is: A" (Even though three values are passed to `log.info`) + log.info('My value is: {}', myArray) +} +``` + +#### Logging multiple entries from an existing array + +Each entry in the arguments array requires its own placeholder `{}` in the log message string. The below example contains three placeholders `{}` in the log message. Because of this, all three values in `myArray` are logged. + +```typescript +let myArray = ['A', 'B', 'C'] + +export function handleSomeEvent(event: SomeEvent): void { + // Displays : "My first value is: A, second value is: B, third value is: C" + log.info('My first value is: {}, second value is: {}, third value is: {}', myArray) +} +``` + +##### Logging a specific entry from an existing array + +To display a specific value in the array, the indexed value must be provided. + +```typescript +export function handleSomeEvent(event: SomeEvent): void { + // Displays : "My third value is C" + log.info('My third value is: {}', [myArray[2]]) +} +``` + +##### Logging event information + +The example below logs the block number, block hash and transaction hash from an event: + +```typescript +import { log } from '@graphprotocol/graph-ts' + +export function handleSomeEvent(event: SomeEvent): void { + log.debug('Block number: {}, block hash: {}, transaction hash: {}', [ + event.block.number.toString(), // "47596000" + event.block.hash.toHexString(), // "0x..." + event.transaction.hash.toHexString(), // "0x..." + ]) +} +``` + +### IPFS API + +```typescript +import { ipfs } from '@graphprotocol/graph-ts' +``` + +Smart contracts occasionally anchor IPFS files on chain. This allows mappings to obtain the IPFS hashes from the contract and read the corresponding files from IPFS. The file data will be returned as `Bytes`, which usually requires further processing, e.g. with the `json` API documented later on this page. + +Given an IPFS hash or path, reading a file from IPFS is done as follows: + +```typescript +// Put this inside an event handler in the mapping +let hash = 'QmTkzDwWqPbnAh5YiV5VwcTLnGdwSNsNTn2aDxdXBFca7D' +let data = ipfs.cat(hash) + +// Paths like `QmTkzDwWqPbnAh5YiV5VwcTLnGdwSNsNTn2aDxdXBFca7D/Makefile` +// that include files in directories are also supported +let path = 'QmTkzDwWqPbnAh5YiV5VwcTLnGdwSNsNTn2aDxdXBFca7D/Makefile' +let data = ipfs.cat(path) +``` + +**Note:** `ipfs.cat` is not deterministic at the moment. If the file cannot be retrieved over the IPFS network before the request times out, it will return `null`. Due to this, it's always worth checking the result for `null`. To ensure that files can be retrieved, they have to be pinned to the IPFS node that Graph Node connects to. On the [hosted service](https://thegraph.com/hosted-service), this is [https://api.thegraph.com/ipfs/](https://api.thegraph.com/ipfs). See the [IPFS pinning](/developer/create-subgraph-hosted#ipfs-pinning) section for more information. + +It is also possible to process larger files in a streaming fashion with `ipfs.map`. The function expects the hash or path for an IPFS file, the name of a callback, and flags to modify its behavior: + +```typescript +import { JSONValue, Value } from '@graphprotocol/graph-ts' + +export function processItem(value: JSONValue, userData: Value): void { + // See the JSONValue documentation for details on dealing + // with JSON values + let obj = value.toObject() + let id = obj.get('id') + let title = obj.get('title') + + if (!id || !title) { + return + } + + // Callbacks can also created entities + let newItem = new Item(id.toString()) + newItem.title = title.toString() + newitem.parent = userData.toString() // Set parent to "parentId" + newitem.save() +} + +// Put this inside an event handler in the mapping +ipfs.map('Qm...', 'processItem', Value.fromString('parentId'), ['json']) + +// Alternatively, use `ipfs.mapJSON` +ipfs.mapJSON('Qm...', 'processItem', Value.fromString('parentId')) +``` + +The only flag currently supported is `json`, which must be passed to `ipfs.map`. With the `json` flag, the IPFS file must consist of a series of JSON values, one value per line. The call to `ipfs.map` will read each line in the file, deserialize it into a `JSONValue` and call the callback for each of them. The callback can then use entity operations to store data from the `JSONValue`. Entity changes are stored only when the handler that called `ipfs.map` finishes successfully; in the meantime, they are kept in memory, and the size of the file that `ipfs.map` can process is therefore limited. + +On success, `ipfs.map` returns `void`. If any invocation of the callback causes an error, the handler that invoked `ipfs.map` is aborted, and the subgraph is marked as failed. + +### Crypto API + +```typescript +import { crypto } from '@graphprotocol/graph-ts' +``` + +The `crypto` API makes a cryptographic functions available for use in mappings. Right now, there is only one: + +- `crypto.keccak256(input: ByteArray): ByteArray` + +### JSON API + +```typescript +import { json, JSONValueKind } from '@graphprotocol/graph-ts' +``` + +JSON data can be parsed using the `json` API: + +- `json.fromBytes(data: Bytes): JSONValue` – parses JSON data from a `Bytes` array +- `json.try_fromBytes(data: Bytes): Result` – safe version of `json.fromBytes`, it returns an error variant if the parsing failed +- `json.fromString(data: Bytes): JSONValue` – parses JSON data from a valid UTF-8 `String` +- `json.try_fromString(data: Bytes): Result` – safe version of `json.fromString`, it returns an error variant if the parsing failed + +The `JSONValue` class provides a way to pull values out of an arbitrary JSON document. Since JSON values can be booleans, numbers, arrays and more, `JSONValue` comes with a `kind` property to check the type of a value: + +```typescript +let value = json.fromBytes(...) +if (value.kind == JSONValueKind.BOOL) { + ... +} +``` + +In addition, there is a method to check if the value is `null`: + +- `value.isNull(): boolean` + +When the type of a value is certain, it can be converted to a [built-in type](#built-in-types) using one of the following methods: + +- `value.toBool(): boolean` +- `value.toI64(): i64` +- `value.toF64(): f64` +- `value.toBigInt(): BigInt` +- `value.toString(): string` +- `value.toArray(): Array` - (and then convert `JSONValue` with one of the 5 methods above) + +### Type Conversions Reference + +| Source(s) | Destination | Conversion function | +| -------------------- | -------------------- | ---------------------------- | +| Address | Bytes | none | +| Address | ID | s.toHexString() | +| Address | String | s.toHexString() | +| BigDecimal | String | s.toString() | +| BigInt | BigDecimal | s.toBigDecimal() | +| BigInt | String (hexadecimal) | s.toHexString() or s.toHex() | +| BigInt | String (unicode) | s.toString() | +| BigInt | i32 | s.toI32() | +| Boolean | Boolean | none | +| Bytes (signed) | BigInt | BigInt.fromSignedBytes(s) | +| Bytes (unsigned) | BigInt | BigInt.fromUnsignedBytes(s) | +| Bytes | String (hexadecimal) | s.toHexString() or s.toHex() | +| Bytes | String (unicode) | s.toString() | +| Bytes | String (base58) | s.toBase58() | +| Bytes | i32 | s.toI32() | +| Bytes | u32 | s.toU32() | +| Bytes | JSON | json.fromBytes(s) | +| int8 | i32 | none | +| int32 | i32 | none | +| int32 | BigInt | Bigint.fromI32(s) | +| uint24 | i32 | none | +| int64 - int256 | BigInt | none | +| uint32 - uint256 | BigInt | none | +| JSON | boolean | s.toBool() | +| JSON | i64 | s.toI64() | +| JSON | u64 | s.toU64() | +| JSON | f64 | s.toF64() | +| JSON | BigInt | s.toBigInt() | +| JSON | string | s.toString() | +| JSON | Array | s.toArray() | +| JSON | Object | s.toObject() | +| String | Address | Address.fromString(s) | +| String | BigDecimal | BigDecimal.fromString(s) | +| String (hexadecimal) | Bytes | ByteArray.fromHexString(s) | +| String (UTF-8) | Bytes | ByteArray.fromUTF8(s) | + +### Data Source Metadata + +You can inspect the contract address, network and context of the data source that invoked the handler through the `dataSource` namespace: + +- `dataSource.address(): Address` +- `dataSource.network(): string` +- `dataSource.context(): DataSourceContext` + +### Entity and DataSourceContext + +The base `Entity` class and the child `DataSourceContext` class have helpers to dynamically set and get fields: + +- `setString(key: string, value: string): void` +- `setI32(key: string, value: i32): void` +- `setBigInt(key: string, value: BigInt): void` +- `setBytes(key: string, value: Bytes): void` +- `setBoolean(key: string, value: bool): void` +- `setBigDecimal(key, value: BigDecimal): void` +- `getString(key: string): string` +- `getI32(key: string): i32` +- `getBigInt(key: string): BigInt` +- `getBytes(key: string): Bytes` +- `getBoolean(key: string): boolean` +- `getBigDecimal(key: string): BigDecimal` diff --git a/pages/ja/developer/assemblyscript-migration-guide.mdx b/pages/ja/developer/assemblyscript-migration-guide.mdx new file mode 100644 index 000000000000..2db90a608110 --- /dev/null +++ b/pages/ja/developer/assemblyscript-migration-guide.mdx @@ -0,0 +1,484 @@ +--- +title: AssemblyScript Migration Guide +--- + +Up until now, subgraphs have been using one of the [first versions of AssemblyScript](https://github.com/AssemblyScript/assemblyscript/tree/v0.6) (v0.6). Finally we've added support for the [newest one available](https://github.com/AssemblyScript/assemblyscript/tree/v0.19.10) (v0.19.10)! 🎉 + +That will enable subgraph developers to use newer features of the AS language and standard library. + +This guide is applicable for anyone using `graph-cli`/`graph-ts` below version `0.22.0`. If you're already at a higher than (or equal) version to that, you've already been using version `0.19.10` of AssemblyScript 🙂 + +> Note: As of `0.24.0`, `graph-node` can support both versions, depending on the `apiVersion` specified in the subgraph manifest. + +## Features + +### New functionality + +- `TypedArray`s can now be built from `ArrayBuffer`s by using the [new `wrap` static method](https://www.assemblyscript.org/stdlib/typedarray.html#static-members) ([v0.8.1](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.8.1)) +- New standard library functions: `String#toUpperCase`, `String#toLowerCase`, `String#localeCompare`and `TypedArray#set` ([v0.9.0](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.9.0)) +- Added support for x instanceof GenericClass ([v0.9.2](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.9.2)) +- Added `StaticArray`, a more efficient array variant ([v0.9.3](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.9.3)) +- Added `Array#flat` ([v0.10.0](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.10.0)) +- Implemented `radix` argument on `Number#toString` ([v0.10.1](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.10.1)) +- Added support for separators in floating point literals ([v0.13.7](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.13.7)) +- Added support for first class functions ([v0.14.0](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.14.0)) +- Add builtins: `i32/i64/f32/f64.add/sub/mul` ([v0.14.13](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.14.13)) +- Implement `Array/TypedArray/String#at` ([v0.18.2](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.18.2)) +- Added support for template literal strings ([v0.18.17](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.18.17)) +- Add `encodeURI(Component)` and `decodeURI(Component)` ([v0.18.27](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.18.27)) +- Add `toString`, `toDateString` and `toTimeString` to `Date` ([v0.18.29](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.18.29)) +- Add `toUTCString` for `Date` ([v0.18.30](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.18.30)) +- Add `nonnull/NonNullable` builtin type ([v0.19.2](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.19.2)) + +### Optimizations + +- `Math` functions such as `exp`, `exp2`, `log`, `log2` and `pow` have been replaced by faster variants ([v0.9.0](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.9.0)) +- Slightly optimize `Math.mod` ([v0.17.1](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.17.1)) +- Cache more field accesses in std Map and Set ([v0.17.8](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.17.8)) +- Optimize for powers of two in `ipow32/64` ([v0.18.2](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.18.2)) + +### Other + +- The type of an array literal can now be inferred from its contents ([v0.9.0](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.9.0)) +- Updated stdlib to Unicode 13.0.0 ([v0.10.0](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.10.0)) + +## How to upgrade? + +1. Change your mappings `apiVersion` in `subgraph.yaml` to `0.0.6`: + +```yaml +... +dataSources: + ... + mapping: + ... + apiVersion: 0.0.6 + ... +``` + +2. Update the `graph-cli` you're using to the `latest` version by running: + +```bash +# if you have it globally installed +npm install --global @graphprotocol/graph-cli@latest + +# or in your subgraph if you have it as a dev dependency +npm install --save-dev @graphprotocol/graph-cli@latest +``` + +3. Do the same for `graph-ts`, but instead of installing globally, save it in your main dependencies: + +```bash +npm install --save @graphprotocol/graph-ts@latest +``` + +4. Follow the rest of the guide to fix the language breaking changes. +5. Run `codegen` and `deploy` again. + +## Breaking changes + +### Nullability + +On the older version of AssemblyScript, you could create code like this: + +```typescript +function load(): Value | null { ... } + +let maybeValue = load(); +maybeValue.aMethod(); +``` + +However on the newer version, because the value is nullable, it requires you to check, like this: + +```typescript +let maybeValue = load() + +if (maybeValue) { + maybeValue.aMethod() // `maybeValue` is not null anymore +} +``` + +Or force it like this: + +```typescript +let maybeValue = load()! // breaks in runtime if value is null + +maybeValue.aMethod() +``` + +If you are unsure which to choose, we recommend always using the safe version. If the value doesn't exist you might want to just do an early if statement with a return in you subgraph handler. + +### Variable Shadowing + +Before you could do [variable shadowing](https://en.wikipedia.org/wiki/Variable_shadowing) and code like this would work: + +```typescript +let a = 10 +let b = 20 +let a = a + b +``` + +However now this isn't possible anymore, and the compiler returns this error: + +```typescript +ERROR TS2451: Cannot redeclare block-scoped variable 'a' + + let a = a + b; + ~~~~~~~~~~~~~ +in assembly/index.ts(4,3) +``` +You'll need to rename your duplicate variables if you had variable shadowing. +### Null Comparisons +By doing the upgrade on your subgraph, sometimes you might get errors like these: + +```typescript +ERROR TS2322: Type '~lib/@graphprotocol/graph-ts/common/numbers/BigInt | null' is not assignable to type '~lib/@graphprotocol/graph-ts/common/numbers/BigInt'. + if (decimals == null) { + ~~~~ + in src/mappings/file.ts(41,21) +``` +To solve you can simply change the `if` statement to something like this: + +```typescript + if (!decimals) { + + // or + + if (decimals === null) { +``` + +The same applies if you're doing != instead of ==. + +### Casting + +The common way to do casting before was to just use the `as` keyword, like this: + +```typescript +let byteArray = new ByteArray(10) +let uint8Array = byteArray as Uint8Array // equivalent to: byteArray +``` + +However this only works in two scenarios: + +- Primitive casting (between types such as `u8`, `i32`, `bool`; eg: `let b: isize = 10; b as usize`); +- Upcasting on class inheritance (subclass → superclass) + +Examples: + +```typescript +// primitive casting +let a: usize = 10 +let b: isize = 5 +let c: usize = a + (b as usize) +``` + +```typescript +// upcasting on class inheritance +class Bytes extends Uint8Array {} + +let bytes = new Bytes(2) < Uint8Array > bytes // same as: bytes as Uint8Array +``` + +There are two scenarios where you may want to cast, but using `as`/`var` **isn't safe**: + +- Downcasting on class inheritance (superclass → subclass) +- Between two types that share a superclass + +```typescript +// downcasting on class inheritance +class Bytes extends Uint8Array {} + +let uint8Array = new Uint8Array(2) < Bytes > uint8Array // breaks in runtime :( +``` + +```typescript +// between two types that share a superclass +class Bytes extends Uint8Array {} +class ByteArray extends Uint8Array {} + +let bytes = new Bytes(2) < ByteArray > bytes // breaks in runtime :( +``` + +For those cases, you can use the `changetype` function: + +```typescript +// downcasting on class inheritance +class Bytes extends Uint8Array {} + +let uint8Array = new Uint8Array(2) +changetype(uint8Array) // works :) +``` + +```typescript +// between two types that share a superclass +class Bytes extends Uint8Array {} +class ByteArray extends Uint8Array {} + +let bytes = new Bytes(2) +changetype(bytes) // works :) +``` + +If you just want to remove nullability, you can keep using the `as` operator (or `variable`), but make sure you know that value can't be null, otherwise it will break. + +```typescript +// remove nullability +let previousBalance = AccountBalance.load(balanceId) // AccountBalance | null + +if (previousBalance != null) { + return previousBalance as AccountBalance // safe remove null +} + +let newBalance = new AccountBalance(balanceId) +``` + +For the nullability case we recommend taking a look at the [nullability check feature](https://www.assemblyscript.org/basics.html#nullability-checks), it will make your code cleaner 🙂 + +Also we've added a few more static methods in some types to ease casting, they are: + +- Bytes.fromByteArray +- Bytes.fromUint8Array +- BigInt.fromByteArray +- ByteArray.fromBigInt + +### Nullability check with property access + +To use the [nullability check feature](https://www.assemblyscript.org/basics.html#nullability-checks) you can use either `if` statements or the ternary operator (`?` and `:`) like this: + +```typescript +let something: string | null = 'data' + +let somethingOrElse = something ? something : 'else' + +// or + +let somethingOrElse + +if (something) { + somethingOrElse = something +} else { + somethingOrElse = 'else' +} +``` + +However that only works when you're doing the `if` / ternary on a variable, not on a property access, like this: + +```typescript +class Container { + data: string | null +} + +let container = new Container() +container.data = 'data' + +let somethingOrElse: string = container.data ? container.data : 'else' // doesn't compile +``` + +Which outputs this error: + +```typescript +ERROR TS2322: Type '~lib/string/String | null' is not assignable to type '~lib/string/String'. + + let somethingOrElse: string = container.data ? container.data : "else"; + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +``` +To fix this issue, you can create a variable for that property access so that the compiler can do the nullability check magic: + +```typescript +class Container { + data: string | null +} + +let container = new Container() +container.data = 'data' + +let data = container.data + +let somethingOrElse: string = data ? data : 'else' // compiles just fine :) +``` + +### Operator overloading with property access + +If you try to sum (for example) a nullable type (from a property access) with a non nullable one, the AssemblyScript compiler instead of giving a compile time error warning that one of the values is nullable, it just compiles silently, giving chance for the code to break at runtime. + +```typescript +class BigInt extends Uint8Array { + @operator('+') + plus(other: BigInt): BigInt { + // ... + } +} + +class Wrapper { + public constructor(public n: BigInt | null) {} +} + +let x = BigInt.fromI32(2) +let y: BigInt | null = null + +x + y // give compile time error about nullability + +let wrapper = new Wrapper(y) + +wrapper.n = wrapper.n + x // doesn't give compile time errors as it should +``` + +We've opened a issue on the AssemblyScript compiler for this, but for now if you do these kind of operations in your subgraph mappings, you should change them to do a null check before it. + +```typescript +let wrapper = new Wrapper(y) + +if (!wrapper.n) { + wrapper.n = BigInt.fromI32(0) +} + +wrapper.n = wrapper.n + x // now `n` is guaranteed to be a BigInt +``` + +### Value initialization + +If you have any code like this: + +```typescript +var value: Type // null +value.x = 10 +value.y = 'content' +``` + +It will compile but break at runtime, that happens because the value hasn't been initialized, so make sure your subgraph has initialized their values, like this: + +```typescript +var value = new Type() // initialized +value.x = 10 +value.y = 'content' +``` + +Also if you have nullable properties in a GraphQL entity, like this: + +```graphql +type Total @entity { + id: ID! + amount: BigInt +} +``` + +And you have code similar to this: + +```typescript +let total = Total.load('latest') + +if (total === null) { + total = new Total('latest') +} + +total.amount = total.amount + BigInt.fromI32(1) +``` + +You'll need to make sure to initialize the `total.amount` value, because if you try to access like in the last line for the sum, it will crash. So you either initialize it first: + +```typescript +let total = Total.load('latest') + +if (total === null) { + total = new Total('latest') + total.amount = BigInt.fromI32(0) +} + +total.tokens = total.tokens + BigInt.fromI32(1) +``` + +Or you can just change your GraphQL schema to not use a nullable type for this property, then we'll initialize it as zero on the `codegen` step 😉 + +```graphql +type Total @entity { + id: ID! + amount: BigInt! +} +``` + +```typescript +let total = Total.load('latest') + +if (total === null) { + total = new Total('latest') // already initializes non-nullable properties +} + +total.amount = total.amount + BigInt.fromI32(1) +``` + +### Class property initialization + +If you export any classes with properties that are other classes (declared by you or by the standard library) like this: + +```typescript +class Thing {} + +export class Something { + value: Thing +} +``` + +The compiler will error because you either need to add an initializer for the properties that are classes, or add the `!` operator: + +```typescript +export class Something { + constructor(public value: Thing) {} +} + +// or + +export class Something { + value: Thing + + constructor(value: Thing) { + this.value = value + } +} + +// or + +export class Something { + value!: Thing +} +``` + +### GraphQL schema + +This is not a direct AssemblyScript change, but you may have to update your `schema.graphql` file. + +Now you no longer can define fields in your types that are Non-Nullable Lists. If you have a schema like this: + +```graphql +type Something @entity { + id: ID! +} + +type MyEntity @entity { + id: ID! + invalidField: [Something]! # no longer valid +} +``` + +You'll have to add an `!` to the member of the List type, like this: + +```graphql +type Something @entity { + id: ID! +} + +type MyEntity @entity { + id: ID! + invalidField: [Something!]! # valid +} +``` + +This changed because of nullability differences between AssemblyScript versions, and it's related to the `src/generated/schema.ts` file (default path, you might have changed this). + +### Other + +- Aligned `Map#set` and `Set#add` with the spec, returning `this` ([v0.9.2](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.9.2)) +- Arrays no longer inherit from ArrayBufferView, but are now distinct ([v0.10.0](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.10.0)) +- Classes initialized from object literals can no longer define a constructor ([v0.10.0](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.10.0)) +- The result of a `**` binary operation is now the common denominator integer if both operands are integers. Previously, the result was a float as if calling `Math/f.pow` ([v0.11.0](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.11.0)) +- Coerce `NaN` to `false` when casting to `bool` ([v0.14.9](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.14.9)) +- When shifting a small integer value of type `i8`/`u8` or `i16`/`u16`, only the 3 respectively 4 least significant bits of the RHS value affect the result, analogous to the result of an `i32.shl` only being affected by the 5 least significant bits of the RHS value. Example: `someI8 << 8` previously produced the value `0`, but now produces `someI8` due to masking the RHS as `8 & 7 = 0` (3 bits) ([v0.17.0](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.17.0)) +- Bug fix of relational string comparisons when sizes differ ([v0.17.8](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.17.8)) diff --git a/pages/ja/developer/create-subgraph-hosted.mdx b/pages/ja/developer/create-subgraph-hosted.mdx new file mode 100644 index 000000000000..6b235e379634 --- /dev/null +++ b/pages/ja/developer/create-subgraph-hosted.mdx @@ -0,0 +1,928 @@ +--- +title: Create a Subgraph +--- + +Before being able to use the Graph CLI, you need to create your subgraph in [Subgraph Studio](https://thegraph.com/studio). You will then be able to setup your subgraph project and deploy it to the platform of your choice. Note that **subgraphs that do not index Ethereum mainnet will not be published to The Graph Network**. + +The `graph init` command can be used to set up a new subgraph project, either from an existing contract on any of the public Ethereum networks, or from an example subgraph. This command can be used to create a subgraph on the Subgraph Studio by passing in `graph init --product subgraph-studio`. If you already have a smart contract deployed to Ethereum mainnet or one of the testnets, bootstrapping a new subgraph from that contract can be a good way to get started. But first, a little about the networks The Graph supports. + +## Supported Networks + +The Graph Network supports subgraphs indexing mainnet Ethereum: + +- `mainnet` + +**Additional Networks are supported in beta on the Hosted Service**: + +- `mainnet` +- `kovan` +- `rinkeby` +- `ropsten` +- `goerli` +- `poa-core` +- `poa-sokol` +- `xdai` +- `near-mainnet` +- `near-testnet` +- `matic` +- `mumbai` +- `fantom` +- `bsc` +- `chapel` +- `clover` +- `avalanche` +- `fuji` +- `celo` +- `celo-alfajores` +- `fuse` +- `moonriver` +- `mbase` +- `arbitrum-one` +- `arbitrum-rinkeby` +- `optimism` +- `optimism-kovan` +- `aurora` +- `aurora-testnet` + +The Graph's Hosted Service relies on the stability and reliability of the underlying technologies, namely the provided JSON RPC endpoints. Newer networks will be marked as being in beta until the network has proven itself in terms of stability, reliability, and scalability. During this beta period, there is risk of downtime and unexpected behaviour. + +Remember that you will **not be able** to publish a subgraph that indexes a non-mainnet network to the decentralized Graph Network in [Subgraph Studio](/studio/subgraph-studio). + +## From An Existing Contract + +The following command creates a subgraph that indexes all events of an existing contract. It attempts to fetch the contract ABI from Etherscan and falls back to requesting a local file path. If any of the optional arguments are missing, it takes you through an interactive form. + +```sh +graph init \ + --product subgraph-studio + --from-contract \ + [--network ] \ + [--abi ] \ + [] +``` + +The `` is the ID of your subgraph in Subgraph Studio, it can be found on your subgraph details page. + +## From An Example Subgraph + +The second mode `graph init` supports is creating a new project from an example subgraph. The following command does this: + +``` +graph init --studio +``` + +The example subgraph is based on the Gravity contract by Dani Grant that manages user avatars and emits `NewGravatar` or `UpdateGravatar` events whenever avatars are created or updated. The subgraph handles these events by writing `Gravatar` entities to the Graph Node store and ensuring these are updated according to the events. The following sections will go over the files that make up the subgraph manifest for this example. + +## The Subgraph Manifest + +The subgraph manifest `subgraph.yaml` defines the smart contracts your subgraph indexes, which 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 full specification for subgraph manifests can be found [here](https://github.com/graphprotocol/graph-node/blob/master/docs/subgraph-manifest.md). + +For the example subgraph, `subgraph.yaml` is: + +```yaml +specVersion: 0.0.4 +description: Gravatar for Ethereum +repository: https://github.com/graphprotocol/example-subgraph +schema: + file: ./schema.graphql +dataSources: + - kind: ethereum/contract + name: Gravity + network: mainnet + source: + address: '0x2E645469f354BB4F5c8a05B3b30A929361cf77eC' + abi: Gravity + startBlock: 6175244 + mapping: + kind: ethereum/events + apiVersion: 0.0.6 + language: wasm/assemblyscript + entities: + - Gravatar + abis: + - name: Gravity + file: ./abis/Gravity.json + eventHandlers: + - event: NewGravatar(uint256,address,string,string) + handler: handleNewGravatar + - event: UpdatedGravatar(uint256,address,string,string) + handler: handleUpdatedGravatar + callHandlers: + - function: createGravatar(string,string) + handler: handleCreateGravatar + blockHandlers: + - function: handleBlock + - function: handleBlockWithCall + filter: + kind: call + file: ./src/mapping.ts +``` + +The important entries to update for the manifest are: + +- `description`: a human-readable description of what the subgraph is. This description is displayed by the Graph Explorer when the subgraph is deployed to the Hosted Service. + +- `repository`: the URL of the repository where the subgraph manifest can be found. This is also displayed by the Graph Explorer. + +- `features`: a list of all used [feature](#experimental-features) names. + +- `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.mapping.entities`: the entities that the data source writes to the store. The schema for each entity is defined in the 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 filter can be provided with the following kinds: call`. A`call` filter will 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. + +The triggers for a data source within a block are ordered using the following process: + +1. Event and call triggers are first ordered by transaction index within the block. +2. Event and call triggers with in the same transaction are ordered using a convention: event triggers first then call triggers, each type respecting the order they are defined in the manifest. +3. Block triggers are run after event and call triggers, in the order they are defined in the manifest. + +These ordering rules are subject to change. + +### Getting The ABIs + +The ABI file(s) must match your contract(s). There are a few ways to obtain ABI files: + +- If you are building your own project, you will likely have access to your most current ABIs. +- If you are building a subgraph for a public project, you can download that project to your computer and get the ABI by using [`truffle compile`](https://truffleframework.com/docs/truffle/overview) or using solc to compile. +- You can also find the ABI on [Etherscan](https://etherscan.io/), but this isn't always reliable, as the ABI that is uploaded there may be out of date. Make sure you have the right ABI, otherwise running your subgraph will fail. + +## The GraphQL Schema + +The schema for your subgraph is in the file `schema.graphql`. GraphQL schemas are defined using the GraphQL interface definition language. If you've never written a GraphQL schema, it is recommended that you check out this primer on the GraphQL type system. Reference documentation for GraphQL schemas can be found in the [GraphQL API](/developer/graphql-api) section. + +## Defining Entities + +Before defining entities, it is important to take a step back and think about how your data is structured and linked. All queries will be made against the data model defined in the subgraph schema and the entities indexed by the subgraph. Because of this, it is good to define the subgraph schema in a way that matches the needs of your dapp. It may be useful to imagine entities as "objects containing data", rather than as events or functions. + +With The Graph, you simply define entity types in `schema.graphql`, and Graph Node will generate top level fields for querying single instances and collections of that entity type. Each type that should be an entity is required to be annotated with an `@entity` directive. + +### Good Example + +The `Gravatar` entity below is structured around a Gravatar object and is a good example of how an entity could be defined. + +```graphql +type Gravatar @entity { + id: ID! + owner: Bytes + displayName: String + imageUrl: String + accepted: Boolean +} +``` + +### Bad Example + +The example `GravatarAccepted` and `GravatarDeclined` entities below are based around events. It is not recommended to map events or function calls to entities 1:1. + +```graphql +type GravatarAccepted @entity { + id: ID! + owner: Bytes + displayName: String + imageUrl: String +} + +type GravatarDeclined @entity { + id: ID! + owner: Bytes + displayName: String + imageUrl: String +} +``` + +### Optional and Required Fields + +Entity fields can be defined as required or optional. Required fields are indicated by the `!` in the schema. If a required field is not set in the mapping, you will receive this error when querying the field: + +``` +Null value resolved for non-null field 'name' +``` + +Each entity must have an `id` field, which is of type `ID!` (string). The `id` field serves as the primary key, and needs to be unique among all entities of the same type. + +### Built-In Scalar Types + +#### GraphQL Supported Scalars + +We support the following scalars in our GraphQL API: + +| Type | Description | +| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `Bytes` | Byte array, represented as a hexadecimal string. Commonly used for Ethereum hashes and addresses. | +| `ID` | Stored as a `string`. | +| `String` | Scalar for `string` values. Null characters are not supported and are automatically removed. | +| `Boolean` | Scalar for `boolean` values. | +| `Int` | The GraphQL spec defines `Int` to have size of 32 bytes. | +| `BigInt` | Large integers. Used for Ethereum's `uint32`, `int64`, `uint64`, ..., `uint256` types. Note: Everything below `uint32`, such as `int32`, `uint24` or `int8` is represented as `i32`. | +| `BigDecimal` | `BigDecimal` High precision decimals represented as a signficand and an exponent. The exponent range is from −6143 to +6144. Rounded to 34 significant digits. | + +#### Enums + +You can also create enums within a schema. Enums have the following syntax: + +```graphql +enum TokenStatus { + OriginalOwner + SecondOwner + ThirdOwner +} +``` + +Once the enum is defined in the schema, you can use the string representation of the enum value to set an enum field on an entity. For example, you can set the `tokenStatus` to `SecondOwner` by first defining your entity and subsequently setting the field with `entity.tokenStatus = "SecondOwner`. The example below demonstrates what the Token entity would look like with an enum field: + +More detail on writing enums can be found in the [GraphQL documentation](https://graphql.org/learn/schema/). + +#### Entity Relationships + +An entity may have a relationship to one or more other entities in your schema. These relationships may be traversed in your queries. Relationships in The Graph are unidirectional. It is possible to simulate bidirectional relationships by defining a unidirectional relationship on either "end" of the relationship. + +Relationships are defined on entities just like any other field except that the type specified is that of another entity. + +#### One-To-One Relationships + +Define a `Transaction` entity type with an optional one-to-one relationship with a `TransactionReceipt` entity type: + +```graphql +type Transaction @entity { + id: ID! + transactionReceipt: TransactionReceipt +} + +type TransactionReceipt @entity { + id: ID! + transaction: Transaction +} +``` + +#### One-To-Many Relationships + +Define a `TokenBalance` entity type with a required one-to-many relationship with a Token entity type: + +```graphql +type Token @entity { + id: ID! +} + +type TokenBalance @entity { + id: ID! + amount: Int! + token: Token! +} +``` + +#### Reverse Lookups + +Reverse lookups can be defined on an entity through the `@derivedFrom` field. This creates a virtual field on the entity that may be queried but cannot be set manually through the mappings API. Rather, it is derived from the relationship defined on the other entity. For such relationships, it rarely makes sense to store both sides of the relationship, and both indexing and query performance will be better when only one side is stored and the other is derived. + +For one-to-many relationships, the relationship should always be stored on the 'one' side, and the 'many' side should always be derived. Storing the relationship this way, rather than storing an array of entities on the 'many' side, will result in dramatically better performance for both indexing and querying the subgraph. In general, storing arrays of entities should be avoided as much as is practical. + +#### Example + +We can make the balances for a token accessible from the token by deriving a `tokenBalances` field: + +```graphql +type Token @entity { + id: ID! + tokenBalances: [TokenBalance!]! @derivedFrom(field: "token") +} + +type TokenBalance @entity { + id: ID! + amount: Int! + token: Token! +} +``` + +#### Many-To-Many Relationships + +For many-to-many relationships, such as users that each may belong to any number of organizations, the most straightforward, but generally not the most performant, way to model the relationship is as an array in each of the two entities involved. If the relationship is symmetric, only one side of the relationship needs to be stored and the other side can be derived. + +#### Example + +Define a reverse lookup from a `User` entity type to an `Organization` entity type. In the example below, this is achieved by looking up the `members` attribute from within the `Organization` entity. In queries, the `organizations` field on `User` will be resolved by finding all `Organization` entities that include the user's ID. + +```graphql +type Organization @entity { + id: ID! + name: String! + members: [User!]! +} + +type User @entity { + id: ID! + name: String! + organizations: [Organization!]! @derivedFrom(field: "members") +} +``` + +A more performant way to store this relationship is through a mapping table that has one entry for each `User` / `Organization` pair with a schema like + +```graphql +type Organization @entity { + id: ID! + name: String! + members: [UserOrganization]! @derivedFrom(field: "user") +} + +type User @entity { + id: ID! + name: String! + organizations: [UserOrganization!] @derivedFrom(field: "organization") +} + +type UserOrganization @entity { + id: ID! # Set to `${user.id}-${organization.id}` + user: User! + organization: Organization! +} +``` + +This approach requires that queries descend into one additional level to retrieve, for example, the organizations for users: + +```graphql +query usersWithOrganizations { + users { + organizations { + # this is a UserOrganization entity + organization { + name + } + } + } +} +``` + +This more elaborate way of storing many-to-many relationships will result in less data stored for the subgraph, and therefore to a subgraph that is often dramatically faster to index and to query. + +#### Adding comments to the schema + +As per GraphQL spec, comments can be added above schema entity attributes using double quotations `""`. This is illustrated in the example below: + +```graphql +type MyFirstEntity @entity { + "unique identifier and primary key of the entity" + id: ID! + address: Bytes! +} +``` + +## Defining Fulltext Search Fields + +Fulltext search queries filter and rank entities based on a text search input. Fulltext queries are able to return matches for similar words by processing the query text input into stems before comparing to the indexed text data. + +A fulltext query definition includes the query name, the language dictionary used to process the text fields, the ranking algorithm used to order the results, and the fields included in the search. Each fulltext query may span multiple fields, but all included fields must be from a single entity type. + +To add a fulltext query, include a `_Schema_` type with a fulltext directive in the GraphQL schema. + +```graphql +type _Schema_ + @fulltext( + name: "bandSearch" + language: en + algorithm: rank + include: [{ entity: "Band", fields: [{ name: "name" }, { name: "description" }, { name: "bio" }] }] + ) + +type Band @entity { + id: ID! + name: String! + description: String! + bio: String + wallet: Address + labels: [Label!]! + discography: [Album!]! + members: [Musician!]! +} +``` + +The example `bandSearch` field can be used in queries to filter `Band` entities based on the text documents in the `name`, `description`, and `bio` fields. Jump to [GraphQL API - Queries](/developer/graphql-api#queries) for a description of the Fulltext search API and for more example usage. + +```graphql +query { + bandSearch(text: "breaks & electro & detroit") { + id + name + description + wallet + } +} +``` + +> **[Feature Management](#experimental-features):** From `specVersion` `0.0.4` and onwards, `fullTextSearch` must be declared under the `features` section in the subgraph manifest. + +### Languages supported + +Choosing a different language will have a definitive, though sometimes subtle, effect on the fulltext search API. Fields covered by a fulltext query field are examined in the context of the chosen language, so the lexemes produced by analysis and search queries vary language to language. For example: when using the supported Turkish dictionary "token" is stemmed to "toke" while, of course, the English dictionary will stem it to "token". + +Supported language dictionaries: + +| Code | Dictionary | +| ------ | ---------- | +| simple | General | +| da | Danish | +| nl | Dutch | +| en | English | +| fi | Finnish | +| fr | French | +| de | German | +| hu | Hungarian | +| it | Italian | +| no | Norwegian | +| pt | Portugese | +| ro | Romanian | +| ru | Russian | +| es | Spanish | +| sv | Swedish | +| tr | Turkish | + +### Ranking Algorithms + +Supported algorithms for ordering results: + +| Algorithm | Description | +| ------------- | ----------------------------------------------------------------------- | +| rank | Use the match quality (0-1) of the fulltext query to order the results. | +| proximityRank | Similar to rank but also includes the proximity of the matches. | + +## Writing Mappings + +The mappings transform the Ethereum data your mappings are sourcing into entities defined in your schema. Mappings are written in a subset of [TypeScript](https://www.typescriptlang.org/docs/handbook/typescript-in-5-minutes.html) called [AssemblyScript](https://github.com/AssemblyScript/assemblyscript/wiki) which can be compiled to WASM ([WebAssembly](https://webassembly.org/)). AssemblyScript is stricter than normal TypeScript, yet provides a familiar syntax. + +For each event handler that is defined in `subgraph.yaml` under `mapping.eventHandlers`, create an exported function of the same name. Each handler must accept a single parameter called `event` with a type corresponding to the name of the event which is being handled. + +In the example subgraph, `src/mapping.ts` contains handlers for the `NewGravatar` and `UpdatedGravatar` events: + +```javascript +import { NewGravatar, UpdatedGravatar } from '../generated/Gravity/Gravity' +import { Gravatar } from '../generated/schema' + +export function handleNewGravatar(event: NewGravatar): void { + let gravatar = new Gravatar(event.params.id.toHex()) + gravatar.owner = event.params.owner + gravatar.displayName = event.params.displayName + gravatar.imageUrl = event.params.imageUrl + gravatar.save() +} + +export function handleUpdatedGravatar(event: UpdatedGravatar): void { + let id = event.params.id.toHex() + let gravatar = Gravatar.load(id) + if (gravatar == null) { + gravatar = new Gravatar(id) + } + gravatar.owner = event.params.owner + gravatar.displayName = event.params.displayName + gravatar.imageUrl = event.params.imageUrl + gravatar.save() +} +``` + +The first handler takes a `NewGravatar` event and creates a new `Gravatar` entity with `new Gravatar(event.params.id.toHex())`, populating the entity fields using the corresponding event parameters. This entity instance is represented by the variable `gravatar`, with an id value of `event.params.id.toHex()`. + +The second handler tries to load the existing `Gravatar` from the Graph Node store. If it does not exist yet, it is created on demand. The entity is then updated to match the new event parameters, before it is saved back to the store using `gravatar.save()`. + +### Recommended IDs for Creating New Entities + +Every entity has to have an `id` that is unique among all entities of the same type. An entity's `id` value is set when the entity is created. Below are some recommended `id` values to consider when creating new entities. NOTE: The value of `id` must be a `string`. + +- `event.params.id.toHex()` +- `event.transaction.from.toHex()` +- `event.transaction.hash.toHex() + "-" + event.logIndex.toString()` + +We provide the [Graph Typescript Library](https://github.com/graphprotocol/graph-ts) which contains utilies for interacting with the Graph Node store and conveniences for handling smart contract data and entities. You can use this library in your mappings by importing `@graphprotocol/graph-ts` in `mapping.ts`. + +## Code Generation + +In order to make working smart contracts, events and entities easy and type-safe, the Graph CLI can generate AssemblyScript types from the subgraph's GraphQL schema and the contract ABIs included in the data sources. + +This is done with + +```sh +graph codegen [--output-dir ] [] +``` + +but in most cases, subgraphs are already preconfigured via `package.json` to allow you to simply run one of the following to achieve the same: + +```sh +# Yarn +yarn codegen + +# NPM +npm run codegen +``` + +This will generate an AssemblyScript class for every smart contract in the ABI files mentioned in `subgraph.yaml`, allowing you to bind these contracts to specific addresses in the mappings and call read-only contract methods against the block being processed. It will also generate a class for every contract event to provide easy access to event parameters as well as the block and transaction the event originated from. All of these types are written to `//.ts`. In the example subgraph, this would be `generated/Gravity/Gravity.ts`, allowing mappings to import these types with + +```javascript +import { + // The contract class: + Gravity, + // The events classes: + NewGravatar, + UpdatedGravatar, +} from '../generated/Gravity/Gravity' +``` + +In addition to this, one class is generated for each entity type in the subgraph's GraphQL schema. These classes provide type-safe entity loading, read and write access to entity fields as well as a `save()` method to write entities to store. All entity classes are written to `/schema.ts`, allowing mappings to import them with + +```javascript +import { Gravatar } from '../generated/schema' +``` + +> **Note:** The code generation must be performed again after every change to the GraphQL schema or the ABIs included in the manifest. It must also be performed at least once before building or deploying the subgraph. + +Code generation does not check your mapping code in `src/mapping.ts`. If you want to check that before trying to deploy your subgraph to the Graph Explorer, you can run `yarn build` and fix any syntax errors that the TypeScript compiler might find. + +## Data Source Templates + +A common pattern in Ethereum smart contracts is the use of registry or factory contracts, where one contract creates, manages or references an arbitrary number of other contracts that each have their own state and events. 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_. + +### Data Source for the Main Contract + +First, you define a regular data source for the main contract. The snippet below shows a simplified example data source for the [Uniswap](https://uniswap.io) exchange factory contract. Note the `NewExchange(address,address)` event handler. This is emitted when a new exchange contract is created on chain by the factory contract. + +```yaml +dataSources: + - kind: ethereum/contract + name: Factory + network: mainnet + source: + address: '0xc0a47dFe034B400B47bDaD5FecDa2621de6c4d95' + abi: Factory + mapping: + kind: ethereum/events + apiVersion: 0.0.6 + language: wasm/assemblyscript + file: ./src/mappings/factory.ts + entities: + - Directory + abis: + - name: Factory + file: ./abis/factory.json + eventHandlers: + - event: NewExchange(address,address) + handler: handleNewExchange +``` + +### Data Source Templates for Dynamically Created Contracts + +Then, you add _data source templates_ to the manifest. These are identical to regular data sources, except that they lack a predefined contract address under `source`. Typically, you would define one template for each type of sub-contract managed or referenced by the parent contract. + +```yaml +dataSources: + - kind: ethereum/contract + name: Factory + # ... other source fields for the main contract ... +templates: + - name: Exchange + kind: ethereum/contract + network: mainnet + source: + abi: Exchange + mapping: + kind: ethereum/events + apiVersion: 0.0.6 + language: wasm/assemblyscript + file: ./src/mappings/exchange.ts + entities: + - Exchange + abis: + - name: Exchange + file: ./abis/exchange.json + eventHandlers: + - event: TokenPurchase(address,uint256,uint256) + handler: handleTokenPurchase + - event: EthPurchase(address,uint256,uint256) + handler: handleEthPurchase + - event: AddLiquidity(address,uint256,uint256) + handler: handleAddLiquidity + - event: RemoveLiquidity(address,uint256,uint256) + handler: handleRemoveLiquidity +``` + +### Instantiating a Data Source Template + +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. + +```typescript +import { Exchange } from '../generated/templates' + +export function handleNewExchange(event: NewExchange): void { + // Start indexing the exchange; `event.params.exchange` is the + // address of the new exchange contract + Exchange.create(event.params.exchange) +} +``` + +> **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. +> +> If prior blocks contain data relevant to the new data source, it is best to index that data by reading the current state of the contract and creating entities representing that state at the time the new data source is created. + +### Data Source Context + +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: + +```typescript +import { Exchange } from '../generated/templates' + +export function handleNewExchange(event: NewExchange): void { + let context = new DataSourceContext() + context.setString('tradingPair', event.params.tradingPair) + Exchange.createWithContext(event.params.exchange, context) +} +``` + +Inside a mapping of the `Exchange` template, the context can then be accessed: + +```typescript +import { dataSource } from '@graphprotocol/graph-ts' + +let context = dataSource.context() +let tradingPair = context.getString('tradingPair') +``` + +There are setters and getters like `setString` and `getString` for all value types. + +## Start Blocks + +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. + +```yaml +dataSources: + - kind: ethereum/contract + name: ExampleSource + network: mainnet + source: + address: '0xc0a47dFe034B400B47bDaD5FecDa2621de6c4d95' + abi: ExampleContract + startBlock: 6627917 + mapping: + kind: ethereum/events + apiVersion: 0.0.6 + language: wasm/assemblyscript + file: ./src/mappings/factory.ts + entities: + - User + abis: + - name: ExampleContract + file: ./abis/ExampleContract.json + eventHandlers: + - event: NewEvent(address,address) + handler: handleNewEvent +``` + +> **Note:** The contract creation block can be quickly looked up on Etherscan: +> +> 1. Search for the contract by entering its address in the search bar. +> 2. Click on the creation transaction hash in the `Contract Creator` section. +> 3. Load the transaction details page where you'll find the start block for that contract. + +## Call Handlers + +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. + +Call handlers will only trigger in one of two cases: when the function specified is called by an account other than the contract itself or when it is marked as external in Solidity and called as part of another function in the same contract. + +> **Note:** Call handlers are not supported on Rinkeby, Goerli or Ganache. Call handlers currently depend on the Parity tracing API and these networks do not support it. + +### Defining a Call Handler + +To define a call handler in your manifest simply add a `callHandlers` array under the data source you would like to subscribe to. + +```yaml +dataSources: + - kind: ethereum/contract + name: Gravity + network: mainnet + source: + address: '0x731a10897d267e19b34503ad902d0a29173ba4b1' + abi: Gravity + mapping: + kind: ethereum/events + apiVersion: 0.0.6 + language: wasm/assemblyscript + entities: + - Gravatar + - Transaction + abis: + - name: Gravity + file: ./abis/Gravity.json + callHandlers: + - function: createGravatar(string,string) + 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. + +### Mapping Function + +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: + +```typescript +import { CreateGravatarCall } from '../generated/Gravity/Gravity' +import { Transaction } from '../generated/schema' + +export function handleCreateGravatar(call: CreateGravatarCall): void { + let id = call.transaction.hash.toHex() + let transaction = new Transaction(id) + transaction.displayName = call.inputs._displayName + transaction.imageUrl = call.inputs._imageUrl + transaction.save() +} +``` + +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`. + +## Block Handlers + +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 predefined filter. + +### Supported Filters + +```yaml +filter: + 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._ + +The absense of a filter for a block handler will ensure that the handler is called every block. A data source can only contain one block handler for each filter type. + +```yaml +dataSources: + - kind: ethereum/contract + name: Gravity + network: dev + source: + address: '0x731a10897d267e19b34503ad902d0a29173ba4b1' + abi: Gravity + mapping: + kind: ethereum/events + apiVersion: 0.0.6 + language: wasm/assemblyscript + entities: + - Gravatar + - Transaction + abis: + - name: Gravity + file: ./abis/Gravity.json + blockHandlers: + - handler: handleBlock + - handler: handleBlockWithCallToContract + filter: + kind: call +``` + +### Mapping Function + +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. + +```typescript +import { ethereum } from '@graphprotocol/graph-ts' + +export function handleBlock(block: ethereum.Block): void { + let id = block.hash.toHex() + let entity = new Block(id) + entity.save() +} +``` + +## Anonymous Events + +If you need to process anonymous events in Solidity, that can be achieved by providing the topic 0 of the event, as in the example: + +```yaml +eventHandlers: + - event: LogNote(bytes4,address,bytes32,bytes32,uint256,bytes) + topic0: '0xbaa8529c00000000000000000000000000000000000000000000000000000000' + 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. + +## Experimental features + +Starting from `specVersion` `0.0.4`, subgraph features must be explicitly declared in the `features` section at the top level of the manifest file, using their `camelCase` name, as listed in the table below: + +| Feature | Name | +| --------------------------------------------------------- | ------------------------- | +| [Non-fatal errors](#non-fatal-errors) | `nonFatalErrors` | +| [Full-text Search](#defining-fulltext-search-fields) | `fullTextSearch` | +| [Grafting](#grafting-onto-existing-subgraphs) | `grafting` | +| [IPFS on Ethereum Contracts](#ipfs-on-ethereum-contracts) | `ipfsOnEthereumContracts` | + +For instance, if a subgraph uses the **Full-Text Search** and the **Non-fatal Errors** features, the `features` field in the manifest should be: + +```yaml +specVersion: 0.0.4 +description: Gravatar for Ethereum +features: + - fullTextSearch + - nonFatalErrors +dataSources: ... +``` + +Note that using a feature without declaring it will incur in a **validation error** during subgraph deployment, but no errors will occur if a feature is declared but not used. + +### IPFS on Ethereum Contracts + +A common use case for combining IPFS with Ethereum is to store data on IPFS that would be too expensive to maintain on chain, and reference the IPFS hash in Ethereum contracts. + +Given such IPFS hashes, subgraphs can read the corresponding files from IPFS using `ipfs.cat` and `ipfs.map`. To do this reliably, however, it is required that these files are pinned on the IPFS node that the Graph Node indexing the subgraph connects to. In the case of the [hosted service](https://thegraph.com/hosted-service), this is [https://api.thegraph.com/ipfs/](https://api.thegraph.com/ipfs/). + +> **Note:** The Graph Network does not yet support `ipfs.cat` and `ipfs.map`, and developers should not deploy subgraphs using that functionality to the network via the Studio. + +In order to make this easy for subgraph developers, The Graph team wrote a tool for transfering files from one IPFS node to another, called [ipfs-sync](https://github.com/graphprotocol/ipfs-sync). + +> **[Feature Management](#experimental-features):** `ipfsOnEthereumContracts` must be declared under `features` in the subgraph manifest. + +### Non-fatal errors + +Indexing errors on already synced subgraphs will, by default, cause the subgraph to fail and stop syncing. Subgraphs can alternatively be configured to continue syncing in the presence of errors, by ignoring the changes made by the handler which provoked the error. This gives subgraph authors time to correct their subgraphs while queries continue to be served against the latest block, though the results will possibly be inconsistent due to the bug that caused the error. Note that some errors are still always fatal, to be non-fatal the error must be known to be deterministic. + +> **Note:** The Graph Network does not yet support non-fatal errors, and developers should not deploy subgraphs using that functionality to the network via the Studio. + +Enabling non-fatal errors requires setting the following feature flag on the subgraph manifest: + +```yaml +specVersion: 0.0.4 +description: Gravatar for Ethereum +features: + - fullTextSearch + ... +``` + +The query must also opt-in to querying data with potential inconsistencies through the `subgraphError` argument. It is also recommended to query `_meta` to check if the subgraph has skipped over errors, as in the example: + +```graphql +foos(first: 100, subgraphError: allow) { + id +} + +_meta { + hasIndexingErrors +} +``` + +If the subgraph encounters an error that query will return both the data and a graphql error with the message `"indexing_error"`, as in this example response: + +```graphql +"data": { + "foos": [ + { + "id": "fooId" + } + ], + "_meta": { + "hasIndexingErrors": true + } +}, +"errors": [ + { + "message": "indexing_error" + } +] +``` + +### Grafting onto Existing Subgraphs + +When a subgraph is first deployed, it starts indexing events at the genesis block of the corresponding chain (or at the `startBlock` defined with each data source) In some circumstances, it is beneficial to reuse the data from an existing subgraph and start indexing at a much later block. This mode of indexing is called _Grafting_. Grafting is, for example, useful during development to get past simple errors in the mappings quickly, or to temporarily get an existing subgraph working again after it has failed. + +> **Note:** Grafting requires that the Indexer has indexed the base subgraph. It is not recommended on The Graph Network at this time, and developers should not deploy subgraphs using that functionality to the network via the Studio. + +A subgraph is grafted onto a base subgraph when the subgraph manifest in `subgraph.yaml` contains a `graft` block at the toplevel: + +```yaml +description: ... +graft: + base: Qm... # Subgraph ID of base subgraph + block: 7345624 # Block number +``` + +When a subgraph whose manifest contains a `graft` block is deployed, Graph Node will copy the data of the `base` subgraph up to and including the given `block` and then continue indexing the new subgraph from that block on. The base subgraph must exist on the target Graph Node instance and must have indexed up to at least the given block. Because of this restriction, grafting should only be used during development or during an emergency to speed up producing an equivalent non-grafted subgraph. + +Because grafting copies rather than indexes base data it is much quicker in getting the subgraph to the desired block than indexing from scratch, though the initial data copy can still take several hours for very large subgraphs. While the grafted subgraph is being initialized, the Graph Node will log information about the entity types that have already been copied. + +The grafted subgraph can use a GraphQL schema that is not identical to the one of the base subgraph, but merely compatible with it. It has to be a valid subgraph schema in its own right but may deviate from the base subgraph's schema in the following ways: + +- It adds or removes entity types +- It removes attributes from entity types +- It adds nullable attributes to entity types +- It turns non-nullable attributes into nullable attributes +- It adds values to enums +- It adds or removes interfaces +- It changes for which entity types an interface is implemented + +> **[Feature Management](#experimental-features):** `grafting` must be declared under `features` in the subgraph manifest. diff --git a/pages/ja/developer/define-subgraph-hosted.mdx b/pages/ja/developer/define-subgraph-hosted.mdx new file mode 100644 index 000000000000..92bf5bd8cd2f --- /dev/null +++ b/pages/ja/developer/define-subgraph-hosted.mdx @@ -0,0 +1,35 @@ +--- +title: Define a Subgraph +--- + +A subgraph defines which data The Graph will index from Ethereum, and how it will store it. Once deployed, it will form a part of a global graph of blockchain data. + +![Define a Subgraph](/img/define-subgraph.png) + +The subgraph definition consists of a few files: + +- `subgraph.yaml`: a YAML file containing the subgraph manifest + +- `schema.graphql`: a GraphQL schema that defines what data is stored for your subgraph, and how to query it via GraphQL + +- `AssemblyScript Mappings`: [AssemblyScript](https://github.com/AssemblyScript/assemblyscript) code that translates from the event data to the entities defined in your schema (e.g. `mapping.ts` in this tutorial) + +Before you go into detail about the contents of the manifest file, you need to install the [Graph CLI](https://github.com/graphprotocol/graph-cli) which you will need to build and deploy a subgraph. + +## Install the Graph CLI + +The Graph CLI is written in JavaScript, and you will need to install either `yarn` or `npm` to use it; it is assumed that you have yarn in what follows. + +Once you have `yarn`, install the Graph CLI by running + +**Install with yarn:** + +```bash +yarn global add @graphprotocol/graph-cli +``` + +**Install with npm:** + +```bash +npm install -g @graphprotocol/graph-cli +``` diff --git a/pages/ja/developer/deprecating-a-subgraph.mdx b/pages/ja/developer/deprecating-a-subgraph.mdx new file mode 100644 index 000000000000..f8966e025c13 --- /dev/null +++ b/pages/ja/developer/deprecating-a-subgraph.mdx @@ -0,0 +1,17 @@ +--- +title: Deprecating a Subgraph +--- + +So you'd like to deprecate your subgraph on The Graph Explorer. You've come to the right place! Follow the steps below: + +1. Visit the contract address [here](https://etherscan.io/address/0xadca0dd4729c8ba3acf3e99f3a9f471ef37b6825#writeProxyContract) +2. Call 'deprecateSubgraph' with your own address as the first parameter +3. In the 'subgraphNumber' field, list 0 if it's the first subgraph you're publishing, 1 if it's your second, 2 if it's your third, etc. +4. Inputs for #2 and #3 can be found in your `` which is composed of the `{graphAccount}-{subgraphNumber}`. For example, the [Sushi Subgraph's](https://thegraph.com/explorer/subgraph?id=0x4bb4c1b0745ef7b4642feeccd0740dec417ca0a0-0&version=0x4bb4c1b0745ef7b4642feeccd0740dec417ca0a0-0-0&view=Overview) ID is `<0x4bb4c1b0745ef7b4642feeccd0740dec417ca0a0-0>`, which is a combination of `graphAccount` = `<0x4bb4c1b0745ef7b4642feeccd0740dec417ca0a0>` and `subgraphNumber` = `<0>` +5. Voila! Your subgraph will no longer show up on searches on The Graph Explorer. Please note the following: + +- Curators will not be able to signal on the subgraph anymore +- Curators that already signaled on the subgraph will be able to withdraw their signal at an average share price +- Deprecated subgraphs will be indicated with an error message. + +If you interacted with the now deprecated subgraph, you'll be able to find it in your user profile under the "Subgraphs", "Indexing", or "Curating" tab respectively. diff --git a/pages/ja/developer/developer-faq.mdx b/pages/ja/developer/developer-faq.mdx new file mode 100644 index 000000000000..41449c60e5ab --- /dev/null +++ b/pages/ja/developer/developer-faq.mdx @@ -0,0 +1,172 @@ +--- +title: Developer FAQs +--- + +### 1. Can I delete my subgraph? + +It is not possible to delete subgraphs once they are created. + +### 2. Can I change my subgraph name? + +No. Once a subgraph is created, the name cannot be changed. Make sure to think of this carefully before you create your subgraph so it is easily searchable and identifiable by other dapps. + +### 3. Can I change the GitHub account associated with my subgraph? + +No. Once a subgraph is created, the associated GitHub account cannot be changed. Make sure to think of this carefully before you create your subgraph. + +### 4. Am I still able to create a subgraph if my smart contracts don't have events? + +It is highly recommended that you structure your smart contracts to have events associated with data you are interested in querying. Event handlers in the subgraph are triggered by contract events, and are by far the fastest way to retrieve useful data. + +If the contracts you are working with do not contain events, your subgraph can use call and block handlers to trigger indexing. Although this is not recommended as performance will be significantly slower. + +### 5. Is it possible to deploy one subgraph with the same name for multiple networks? + +You will need separate names for multiple networks. While you can't have different subgraphs under the same name, there are convenient ways of having a single codebase for multiple networks. Find more on this in our documentation: [Redeploying a Subgraph](/hosted-service/deploy-subgraph-hosted#redeploying-a-subgraph) + +### 6. How are templates different from data sources? + +Templates allow you to create data sources on the fly, while your subgraph is indexing. It might be the case that your contract will spawn new contracts as people interact with it, and since you know the shape of those contracts (ABI, events, etc) up front you can define how you want to index them in a template and when they are spawned your subgraph will create a dynamic data source by supplying the contract address. + +Check out the "Instantiating a data source template" section on: [Data Source Templates](/developer/create-subgraph-hosted#data-source-templates). + +### 7. How do I make sure I'm using the latest version of graph-node for my local deployments? + +You can run the following command: + +```sh +docker pull graphprotocol/graph-node:latest +``` + +**NOTE:** docker / docker-compose will always use whatever graph-node version was pulled the first time you ran it, so it is important to do this to make sure you are up to date with the latest version of graph-node. + +### 8. How do I call a contract function or access a public state variable from my subgraph mappings? + +Take a look at `Access to smart contract` state inside the section [AssemblyScript API](/developer/assemblyscript-api). + +### 9. Is it possible to set up a subgraph using `graph init` from `graph-cli` with two contracts? Or should I manually add another datasource in `subgraph.yaml` after running `graph init`? + +Unfortunately this is currently not possible. `graph init` is intended as a basic starting point, from which you can then add more data sources manually. + +### 10. I want to contribute or add a GitHub issue, where can I find the open source repositories? + +- [graph-node](https://github.com/graphprotocol/graph-node) +- [graph-cli](https://github.com/graphprotocol/graph-cli) +- [graph-ts](https://github.com/graphprotocol/graph-ts) + +### 11. What is the recommended way to build "autogenerated" ids for an entity when handling events? + +If only one entity is created during the event and if there's nothing better available, then the transaction hash + log index would be unique. You can obfuscate these by converting that to Bytes and then piping it through `crypto.keccak256` but this won't make it more unique. + +### 12. When listening to multiple contracts, is it possible to select the contract order to listen to events? + +Within a subgraph, the events are always processed in the order they appear in the blocks, regardless of whether that is across multiple contracts or not. + +### 13. Is it possible to differentiate between networks (mainnet, Kovan, Ropsten, local) from within event handlers? + +Yes. You can do this by importing `graph-ts` as per the example below: + +```javascript +import { dataSource } from '@graphprotocol/graph-ts' + +dataSource.network() +dataSource.address() +``` + +### 14. Do you support block and call handlers on Rinkeby? + +On Rinkeby we support block handlers, but without `filter: call`. Call handlers are not supported for the time being. + +### 15. Can I import ethers.js or other JS libraries into my subgraph mappings? + +Not currently, as mappings are written in AssemblyScript. One possible alternative solution to this is to store raw data in entities and perform logic that requires JS libraries on the client. + +### 16. Is it possible to specifying what block to start indexing on? + +Yes. `dataSources.source.startBlock` in the `subgraph.yaml` file specifies the 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: Start blocks + +### 17. Are there some tips to increase performance of indexing? My subgraph is taking a very long time to sync. + +Yes, you should take a look at the optional start block feature to start indexing from the block that the contract was deployed: [Start blocks](/developer/create-subgraph-hosted#start-blocks) + +### 18. Is there a way to query the subgraph directly to determine what the latest block number it has indexed? + +Yes! Try the following command, substituting "organization/subgraphName" with the organization under it is published and the name of your subgraph: + +```sh +curl -X POST -d '{ "query": "{indexingStatusForCurrentVersion(subgraphName: \"organization/subgraphName\") { chains { latestBlock { hash number }}}}"}' https://api.thegraph.com/index-node/graphql +``` + +### 19. What networks are supported by The Graph? + +The graph-node supports any EVM-compatible JSON RPC API chain. + +The Graph Network supports subgraphs indexing mainnet Ethereum: + +- `mainnet` + +In the Hosted Service, the following networks are supported: + +- Ethereum mainnet +- Kovan +- Rinkeby +- Ropsten +- Goerli +- PoA-Core +- PoA-Sokol +- xDAI +- NEAR +- NEAR testnet +- Matic +- Mumbai +- Fantom +- Binance Smart Chain +- Clover +- Avalanche +- Fuji +- Celo +- Celo-Alfajores +- Fuse +- Moonbeam +- Arbitrum One +- Arbitrum Testnet (on Rinkeby) +- Optimism +- Optimism Testnet (on Kovan) + +There is work in progress towards integrating other blockchains, you can read more in our repo: [RFC-0003: Multi-Blockchain Support](https://github.com/graphprotocol/rfcs/pull/8/files). + +### 20. Is it possible to duplicate a subgraph to another account or endpoint without redeploying? + +You have to redeploy the subgraph, but if the subgraph ID (IPFS hash) doesn't change, it won't have to sync from the beginning. + +### 21. Is this possible to use Apollo Federation on top of graph-node? + +Federation is not supported yet, although we do want to support it in the future. At the moment, something you can do is use schema stitching, either on the client or via a proxy service. + +### 22. Is there a limit to how many objects The Graph can return per query? + +By default query responses are limited to 100 items per collection. If you want to receive more, you can go up to 1000 items per collection and beyond that you can paginate with: + +```graphql +someCollection(first: 1000, skip: ) { ... } +``` + +### 23. If my dapp frontend uses The Graph for querying, do I need to write my query key into the frontend directly? What if we pay query fees for users – will malicious users cause our query fees to be very high? + +Currently, the recommended approach for a dapp is to add the key to the frontend and expose it to end users. That said, you can limit that key to a host name, like _yourdapp.io_ and subgraph. The gateway is currently being run by Edge & Node. Part of the responsibility of a gateway is to monitor for abusive behavior and block traffic from malicious clients. + +### 24. Where do I go to find my current subgraph on the Hosted Service? + +Head over to the Hosted Service in order to find subgraphs that you or others deployed to the Hosted Service. You can find it [here.](https://thegraph.com/hosted-service) + +### 25. Will the Hosted Service start charging query fees? + +The Graph will never charge for the Hosted Service. The Graph is a decentralized protocol, and charging for a centralized service is not aligned with The Graph’s values. The Hosted Service was always a temporary step to help get to the decentralized network. Developers will have a sufficient amount of time to migrate to the decentralized network as they are comfortable. + +### 26. When will the Hosted Service be shut down? + +If and when there are plans to do this, the community will be notified well ahead of time with considerations made for any subgraphs built on the Hosted Service. + +### 27. How do I upgrade a subgraph on mainnet? + +If you’re a subgraph developer, you can upgrade a new version of your subgraph to the Studio using the CLI. It’ll be private at that point but if you’re happy with it, you can publish to the decentralized Graph Explorer. This will create a new version of your subgraph that Curators can start signaling on. diff --git a/pages/ja/developer/distributed-systems.mdx b/pages/ja/developer/distributed-systems.mdx new file mode 100644 index 000000000000..894fcbe2e18b --- /dev/null +++ b/pages/ja/developer/distributed-systems.mdx @@ -0,0 +1,132 @@ +--- +title: Distributed Systems +--- + +The Graph is a protocol implemented as a distributed system. + +Connections fail. Requests arrive out of order. Different computers with out-of-sync clocks and states process related requests. Servers restart. Re-orgs happen between requests. These problems are inherent to all distributed systems but are exacerbated in systems operating at a global scale. + +Consider this example of what may occur if a client polls an Indexer for the latest data during a re-org. + +1. Indexer ingests block 8 +2. Request served to the client for block 8 +3. Indexer ingests block 9 +4. Indexer ingests block 10A +5. Request served to the client for block 10A +6. Indexer detects reorg to 10B and rolls back 10A +7. Request served to the client for block 9 +8. Indexer ingests block 10B +9. Indexer ingests block 11 +10. Request served to the client for block 11 + +From the point of view of the Indexer, things are progressing forward logically. Time is moving forward, though we did have to roll back an uncle block and play the block under consensus forward on top of it. Along the way, the Indexer serves requests using the latest state it knows about at that time. + +From the point of view of the client, however, things appear chaotic. The client observes that the responses were for blocks 8, 10, 9, and 11 in that order. We call this the "block wobble" problem. When a client experiences block wobble, data may appear to contradict itself over time. The situation worsens when we consider that Indexers do not all ingest the latest blocks simultaneously, and your requests may be routed to multiple Indexers. + +It is the responsibility of the client and server to work together to provide consistent data to the user. Different approaches must be used depending on the desired consistency as there is no one right program for every problem. + +Reasoning through the implications of distributed systems is hard, but the fix may not be! We've established APIs and patterns to help you navigate some common use-cases. The following examples illustrate those patterns but still elide details required by production code (like error handling and cancellation) to not obfuscate the main ideas. + +## Polling for updated data + +The Graph provides the `block: { number_gte: $minBlock }` API, which ensures that the response is for a single block equal or higher to `$minBlock`. If the request is made to a `graph-node` instance and the min block is not yet synced, `graph-node` will return an error. If `graph-node` has synced min block, it will run the response for the latest block. If the request is made to an Edge & Node Gateway, the Gateway will filter out any Indexers that have not yet synced min block and make the request for the latest block the Indexer has synced. + +We can use `number_gte` to ensure that time never travels backward when polling for data in a loop. Here is an example: + +```javascript +/// Updates the protocol.paused variable to the latest +/// known value in a loop by fetching it using The Graph. +async function updateProtocolPaused() { + // It's ok to start with minBlock at 0. The query will be served + // using the latest block available. Setting minBlock to 0 is the + // same as leaving out that argument. + let minBlock = 0 + + for (;;) { + // Schedule a promise that will be ready once + // the next Ethereum block will likely be available. + const nextBlock = new Promise((f) => { + setTimeout(f, 14000) + }) + + const query = ` + { + protocol(block: { number_gte: ${minBlock} } id: "0") { + paused + } + _meta { + block { + number + } + } + }` + + const response = await graphql(query) + minBlock = response._meta.block.number + + // TODO: Do something with the response data here instead of logging it. + console.log(response.protocol.paused) + + // Sleep to wait for the next block + await nextBlock + } +} +``` + +## Fetching a set of related items + +Another use-case is retrieving a large set or, more generally, retrieving related items across multiple requests. Unlike the polling case (where the desired consistency was to move forward in time), the desired consistency is for a single point in time. + +Here we will use the `block: { hash: $blockHash }` argument to pin all of our results to the same block. + +```javascript +/// Gets a list of domain names from a single block using pagination +async function getDomainNames() { + // Set a cap on the maximum number of items to pull. + let pages = 5 + const perPage = 1000 + + // The first query will get the first page of results and also get the block + // hash so that the remainder of the queries are consistent with the first. + let query = ` + { + domains(first: ${perPage}) { + name + id + } + _meta { + block { + hash + } + } + }` + + let data = await graphql(query) + let result = data.domains.map((d) => d.name) + let blockHash = data._meta.block.hash + + // Continue fetching additional pages until either we run into the limit of + // 5 pages total (specified above) or we know we have reached the last page + // because the page has fewer entities than a full page. + while (data.domains.length == perPage && --pages) { + let lastID = data.domains[data.domains.length - 1].id + query = ` + { + domains(first: ${perPage}, where: { id_gt: "${lastID}" }, block: { hash: "${blockHash}" }) { + name + id + } + }` + + data = await graphql(query) + + // Accumulate domain names into the result + for (domain of data.domains) { + result.push(domain.name) + } + } + return result +} +``` + +Note that in case of a re-org, the client will need to retry from the first request to update the block hash to a non-uncle block. diff --git a/pages/ja/developer/graphql-api.mdx b/pages/ja/developer/graphql-api.mdx new file mode 100644 index 000000000000..f9cb6214fcd9 --- /dev/null +++ b/pages/ja/developer/graphql-api.mdx @@ -0,0 +1,267 @@ +--- +title: GraphQL API +--- + +This guide explains the GraphQL Query API that is used for the Graph Protocol. + +## Queries + +In your subgraph schema you define types called `Entities`. For each `Entity` type, an `entity` and `entities` field will be generated on the top-level `Query` type. Note that `query` does not need to be included at the top of the `graphql` query when using The Graph. + +#### Examples + +Query for a single `Token` entity defined in your schema: + +```graphql +{ + token(id: "1") { + id + owner + } +} +``` + +**Note:** When querying for a single entity, the `id` field is required and it must be a string. + +Query all `Token` entities: + +```graphql +{ + tokens { + id + owner + } +} +``` + +### Sorting + +When querying a collection, the `orderBy` parameter may be used to sort by a specific attribute. Additionally, the `orderDirection` can be used to specify the sort direction, `asc` for ascending or `desc` for descending. + +#### Example + +```graphql +{ + tokens(orderBy: price, orderDirection: asc) { + id + owner + } +} +``` + +### Pagination + +When querying a collection, the `first` parameter can be used to paginate from the beginning of the collection. It is worth noting that the default sort order is by ID in ascending alphanumeric order, not by creation time. + +Further, the `skip` parameter can be used to skip entities and paginate. e.g. `first:100` shows the first 100 entities and `first:100, skip:100` shows the next 100 entities. + +Queries should avoid using very large `skip` values since they generally perform poorly. For retrieving a large number of items, it is much better to page through entities based on an attribute as shown in the last example. + +#### Example + +Query the first 10 tokens: + +```graphql +{ + tokens(first: 10) { + id + owner + } +} +``` + +To query for groups of entities in the middle of a collection, the `skip` parameter may be used in conjunction with the `first` parameter to skip a specified number of entities starting at the beginning of the collection. + +#### Example + +Query 10 `Token` entities, offset by 10 places from the beginning of the collection: + +```graphql +{ + tokens(first: 10, skip: 10) { + id + owner + } +} +``` + +#### Example + +If a client needs to retrieve a large number of entities, it is much more performant to base queries on an attribute and filter by that attribute. For example, a client would retrieve a large number of tokens using this query: + +```graphql +{ + query manyTokens($lastID: String) { + tokens(first: 1000, where: { id_gt: $lastID }) { + id + owner + } + } +} +``` + +The first time, it would send the query with `lastID = ""`, and for subsequent requests would set `lastID` to the `id` attribute of the last entity in the previous request. This approach will perform significantly better than using increasing `skip` values. + +### Filtering + +You can use the `where` parameter in your queries to filter for different properties. You can filter on mulltiple values within the `where` parameter. + +#### Example + +Query challenges with `failed` outcome: + +```graphql +{ + challenges(where: { outcome: "failed" }) { + challenger + outcome + application { + id + } + } +} +``` + +You can use suffixes like `_gt`, `_lte` for value comparison: + +#### Example + +```graphql +{ + applications(where: { deposit_gt: "10000000000" }) { + id + whitelisted + deposit + } +} +``` + +Full list of parameter suffixes: + +```graphql +_not +_gt +_lt +_gte +_lte +_in +_not_in +_contains +_not_contains +_starts_with +_ends_with +_not_starts_with +_not_ends_with +``` + +Please note that some suffixes are only supported for specific types. For example, `Boolean` only supports `_not`, `_in`, and `_not_in`. + +### Time-travel queries + +You can query the state of your entities not just for the latest block, which is the by default, but also for an arbitrary block in the past. The block at which a query should happen can be specified either by its block number or its block hash by including a `block` argument in the toplevel fields of queries. + +The result of such a query will not change over time, i.e., querying at a certain past block will return the same result no matter when it is executed, with the exception that if you query at a block very close to the head of the Ethereum chain, the result might change if that block turns out to not be on the main chain and the chain gets reorganized. Once a block can be considered final, the result of the query will not change. + +Note that the current implementation is still subject to certain limitations that might violate these gurantees. The implementation can not always tell that a given block hash is not on the main chain at all, or that the result of a query by block hash for a block that can not be considered final yet might be influenced by a block reorganization running concurrently with the query. They do not affect the results of queries by block hash when the block is final and known to be on the main chain. [This issue](https://github.com/graphprotocol/graph-node/issues/1405) explains what these limitations are in detail. + +#### Example + +```graphql +{ + challenges(block: { number: 8000000 }) { + challenger + outcome + application { + id + } + } +} +``` + +This query will return `Challenge` entities, and their associated `Application` entities, as they existed directly after processing block number 8,000,000. + +#### Example + +```graphql +{ + challenges(block: { hash: "0x5a0b54d5dc17e0aadc383d2db43b0a0d3e029c4c" }) { + challenger + outcome + application { + id + } + } +} +``` + +This query will return `Challenge` entities, and their associated `Application` entities, as they existed directly after processing the block with the given hash. + +### Fulltext Search Queries + +Fulltext search query fields provide an expressive text search API that can be added to the subgraph schema and customized. Refer to [Defining Fulltext Search Fields](/developer/create-subgraph-hosted#defining-fulltext-search-fields) to add fulltext search to your subgraph. + +Fulltext search queries have one required field, `text`, for supplying search terms. Several special fulltext operators are available to be used in this `text` search field. + +Fulltext search operators: + +| Symbol | Operator | Description | +| ----------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------ | +| `&` | `And` | For combining multiple search terms into a filter for entities that include all of the provided terms | +| | | `Or` | Queries with multiple search terms separated by the or operator will return all entities with a match from any of the provided terms | +| `<->` | `Follow by` | Specify the distance between two words. | +| `:*` | `Prefix` | Use the prefix search term to find words whose prefix match (2 characters required.) | + +#### Examples + +Using the `or` operator, this query will filter to blog entities with variations of either "anarchism" or "crumpet" in their fulltext fields. + +```graphql +{ + blogSearch(text: "anarchism | crumpets") { + id + title + body + author + } +} +``` + +The `follow by` operator specifies a words a specific distance apart in the fulltext documents. The following query will return all blogs with variations of "decentralize" followed by "philosophy" + +```graphql +{ + blogSearch(text: "decentralized <-> philosophy") { + id + title + body + author + } +} +``` + +Combine fulltext operators to make more complex filters. With a pretext search operator combined with a follow by this example query will match all blog entities with words that start with "lou" followed by "music". + +```graphql +{ + blogSearch(text: "lou:* <-> music") { + id + title + body + author + } +} +``` + +## Schema + +The schema of your data source--that is, the entity types, values, and relationships that are available to query--are defined through the [GraphQL Interface Definition Langauge (IDL)](https://facebook.github.io/graphql/draft/#sec-Type-System). + +GraphQL schemas generally define root types for `queries`, `subscriptions` and `mutations`. The Graph only supports `queries`. The root `Query` type for your subgraph is automatically generated from the GraphQL schema that's included in your subgraph manifest. + +> **Note:** Our API does not expose mutations because developers are expected to issue transactions directly against the underlying blockchain from their applications. + +### Entities + +All GraphQL types with `@entity` directives in your schema will be treated as entities and must have an `ID` field. + +> **Note:** Currently, all types in your schema must have an `@entity` directive. In the future, we will treat types without an `@entity` directive as value objects, but this is not yet supported. diff --git a/pages/ja/developer/matchstick.mdx b/pages/ja/developer/matchstick.mdx new file mode 100644 index 000000000000..3cf1ec761bb9 --- /dev/null +++ b/pages/ja/developer/matchstick.mdx @@ -0,0 +1,267 @@ +--- +title: Unit Testing Framework +--- + +Matchstick is a unit testing framework, developed by [LimeChain](https://limechain.tech/), that enables subgraph developers to test their mapping logic in a sandboxed environment and deploy their subgraphs with confidence! + +Follow the [Matchstick installation guide](https://github.com/LimeChain/matchstick/blob/main/README.md#quick-start-) to install. Now, you can move on to writing your first unit test. + +## Write a Unit Test + +Let's see how a simple unit test would look like, using the Gravatar [Example Subgraph](https://github.com/graphprotocol/example-subgraph). + +Assuming we have the following handler function (along with two helper functions to make our life easier): + +```javascript +export function handleNewGravatar(event: NewGravatar): void { + let gravatar = new Gravatar(event.params.id.toHex()) + gravatar.owner = event.params.owner + gravatar.displayName = event.params.displayName + gravatar.imageUrl = event.params.imageUrl + gravatar.save() +} + +export function handleNewGravatars(events: NewGravatar[]): void { + events.forEach((event) => { + handleNewGravatar(event) + }) +} + +export function createNewGravatarEvent( + id: i32, + ownerAddress: string, + displayName: string, + imageUrl: string +): NewGravatar { + let mockEvent = newMockEvent() + let newGravatarEvent = new NewGravatar( + mockEvent.address, + mockEvent.logIndex, + mockEvent.transactionLogIndex, + mockEvent.logType, + mockEvent.block, + mockEvent.transaction, + mockEvent.parameters + ) + newGravatarEvent.parameters = new Array() + let idParam = new ethereum.EventParam('id', ethereum.Value.fromI32(id)) + let addressParam = new ethereum.EventParam( + 'ownderAddress', + ethereum.Value.fromAddress(Address.fromString(ownerAddress)) + ) + let displayNameParam = new ethereum.EventParam('displayName', ethereum.Value.fromString(displayName)) + let imageUrlParam = new ethereum.EventParam('imageUrl', ethereum.Value.fromString(imageUrl)) + + newGravatarEvent.parameters.push(idParam) + newGravatarEvent.parameters.push(addressParam) + newGravatarEvent.parameters.push(displayNameParam) + newGravatarEvent.parameters.push(imageUrlParam) + + return newGravatarEvent +} +``` + +We first have to create a test file in our project. We have chosen the name `gravity.test.ts`. In the newly created file we need to define a function named `runTests()`. It is important that the function has that exact name. This is an example of how our tests might look like: + +```typescript +import { clearStore, test, assert } from 'matchstick-as/assembly/index' +import { Gravatar } from '../../generated/schema' +import { NewGravatar } from '../../generated/Gravity/Gravity' +import { createNewGravatarEvent, handleNewGravatars } from '../mappings/gravity' + +export function runTests(): void { + test('Can call mappings with custom events', () => { + // Initialise + let gravatar = new Gravatar('gravatarId0') + gravatar.save() + + // Call mappings + let newGravatarEvent = createNewGravatarEvent(12345, '0x89205A3A3b2A69De6Dbf7f01ED13B2108B2c43e7', 'cap', 'pac') + + let anotherGravatarEvent = createNewGravatarEvent(3546, '0x89205A3A3b2A69De6Dbf7f01ED13B2108B2c43e7', 'cap', 'pac') + + handleNewGravatars([newGravatarEvent, anotherGravatarEvent]) + + assert.fieldEquals('Gravatar', 'gravatarId0', 'id', 'gravatarId0') + assert.fieldEquals('Gravatar', '12345', 'owner', '0x89205A3A3b2A69De6Dbf7f01ED13B2108B2c43e7') + assert.fieldEquals('Gravatar', '3546', 'displayName', 'cap') + + clearStore() + }) + + test('Next test', () => { + //... + }) +} +``` + +That's a lot to unpack! First off, an important thing to notice is that we're importing things from `matchstick-as`, our AssemblyScript helper library (distributed as an npm module). You can find the repository [here](https://github.com/LimeChain/matchstick-as). `matchstick-as` provides us with useful testing methods and also defines the `test()` function which we will use to build our test blocks. The rest of it is pretty straightforward - here's what happens: + +- We're setting up our initial state and adding one custom Gravatar entity; +- We define two `NewGravatar` event objects along with their data, using the `createNewGravatarEvent()` function; +- We're calling out handler methods for those events - `handleNewGravatars()` and passing in the list of our custom events; +- We assert the state of the store. How does that work? - We're passing a unique combination of Entity type and id. Then we check a specific field on that Entity and assert that it has the value we expect it to have. We're doing this both for the initial Gravatar Entity we added to the store, as well as the two Gravatar entities that gets added when the handler function is called; +- And lastly - we're cleaning the store using `clearStore()` so that our next test can start with a fresh and empty store object. We can define as many test blocks as we want. + +There we go - we've created our first test! 👏 + +❗ **IMPORTANT:** _In order for the tests to work, we need to export the `runTests()` function in our mappings file. It won't be used there, but the export statement has to be there so that it can get picked up by Rust later when running the tests._ + +You can export the tests wrapper function in your mappings file like this: + +``` +export { runTests } from "../tests/gravity.test.ts"; +``` + +❗ **IMPORTANT:** _Currently there's an issue with using Matchstick when deploying your subgraph. Please only use Matchstick for local testing, and remove/comment out this line (`export { runTests } from "../tests/gravity.test.ts"`) once you're done. We expect to resolve this issue shortly, sorry for the inconvenience!_ + +_If you don't remove that line, you will get the following error message when attempting to deploy your subgraph:_ + +``` +/... +Mapping terminated before handling trigger: oneshot canceled +.../ +``` + +Now in order to run our tests you simply need to run the following in your subgraph root folder: + +`graph test Gravity` + +And if all goes well you should be greeted with the following: + +![Matchstick saying “All tests passed!”](/img/matchstick-tests-passed.png) + +## Common test scenarios + +### Hydrating the store with a certain state + +Users are able to hydrate the store with a known set of entities. Here's an example to initialise the store with a Gravatar entity: + +```typescript +let gravatar = new Gravatar('entryId') +gravatar.save() +``` + +### Calling a mapping function with an event + +A user can create a custom event and pass it to a mapping function that is bound to the store: + +```typescript +import { store } from 'matchstick-as/assembly/store' +import { NewGravatar } from '../../generated/Gravity/Gravity' +import { handleNewGravatars, createNewGravatarEvent } from './mapping' + +let newGravatarEvent = createNewGravatarEvent(12345, '0x89205A3A3b2A69De6Dbf7f01ED13B2108B2c43e7', 'cap', 'pac') + +handleNewGravatar(newGravatarEvent) +``` + +### Calling all of the mappings with event fixtures + +Users can call the mappings with test fixtures. + +```typescript +import { NewGravatar } from '../../generated/Gravity/Gravity' +import { store } from 'matchstick-as/assembly/store' +import { handleNewGravatars, createNewGravatarEvent } from './mapping' + +let newGravatarEvent = createNewGravatarEvent(12345, '0x89205A3A3b2A69De6Dbf7f01ED13B2108B2c43e7', 'cap', 'pac') + +let anotherGravatarEvent = createNewGravatarEvent(3546, '0x89205A3A3b2A69De6Dbf7f01ED13B2108B2c43e7', 'cap', 'pac') + +handleNewGravatars([newGravatarEvent, anotherGravatarEvent]) +``` + +``` +export function handleNewGravatars(events: NewGravatar[]): void { + events.forEach(event => { + handleNewGravatar(event); + }); +} +``` + +### Mocking contract calls + +Users can mock contract calls: + +```typescript +import { addMetadata, assert, createMockedFunction, clearStore, test } from 'matchstick-as/assembly/index' +import { Gravity } from '../../generated/Gravity/Gravity' +import { Address, BigInt, ethereum } from '@graphprotocol/graph-ts' + +let contractAddress = Address.fromString('0x89205A3A3b2A69De6Dbf7f01ED13B2108B2c43e7') +let expectedResult = Address.fromString('0x90cBa2Bbb19ecc291A12066Fd8329D65FA1f1947') +let bigIntParam = BigInt.fromString('1234') +createMockedFunction(contractAddress, 'gravatarToOwner', 'gravatarToOwner(uint256):(address)') + .withArgs([ethereum.Value.fromSignedBigInt(bigIntParam)]) + .returns([ethereum.Value.fromAddress(Address.fromString('0x90cBa2Bbb19ecc291A12066Fd8329D65FA1f1947'))]) + +let gravity = Gravity.bind(contractAddress) +let result = gravity.gravatarToOwner(bigIntParam) + +assert.equals(ethereum.Value.fromAddress(expectedResult), ethereum.Value.fromAddress(result)) +``` + +As demonstrated, in order to mock a contract call and hardcore a return value, the user must provide a contract address, function name, function signature, an array of arguments, and of course - the return value. + +Users can also mock function reverts: + +```typescript +let contractAddress = Address.fromString('0x89205A3A3b2A69De6Dbf7f01ED13B2108B2c43e7') +createMockedFunction(contractAddress, 'getGravatar', 'getGravatar(address):(string,string)') + .withArgs([ethereum.Value.fromAddress(contractAddress)]) + .reverts() +``` + +### Asserting the state of the store + +Users are able to assert the final (or midway) state of the store through asserting entities. In order to do this, the user has to supply an Entity type, the specific ID of an Entity, a name of a field on that Entity, and the expected value of the field. Here's a quick example: + +```typescript +import { assert } from 'matchstick-as/assembly/index' +import { Gravatar } from '../generated/schema' + +let gravatar = new Gravatar('gravatarId0') +gravatar.save() + +assert.fieldEquals('Gravatar', 'gravatarId0', 'id', 'gravatarId0') +``` + +Running the assert.fieldEquals() function will check for equality of the given field against the given expected value. The test will fail and an error message will be outputted if the values are **NOT** equal. Otherwise the test will pass successfully. + +### Interacting with Event metadata + +Users can use default transaction metadata, which could be returned as an ethereum.Event by using the `newMockEvent()` function. The following example shows how you can read/write to those fields on the Event object: + +```typescript +// Read +let logType = newGravatarEvent.logType + +// Write +let UPDATED_ADDRESS = '0xB16081F360e3847006dB660bae1c6d1b2e17eC2A' +newGravatarEvent.address = Address.fromString(UPDATED_ADDRESS) +``` + +### Asserting variable equality + +```typescript +assert.equals(ethereum.Value.fromString("hello"); ethereum.Value.fromString("hello")); +``` + +### Asserting that an Entity is **not** in the store + +Users can assert that an entity does not exist in the store. The function takes an entity type and an id. If the entity is in fact in the store, the test will fail with a relevant error message. Here's a quick example of how to use this functionality: + +```typescript +assert.notInStore('Gravatar', '23') +``` + +### Test run time duration in the log output + +The log output includes the test run duration. Here's an example: + +`Jul 09 14:54:42.420 INFO Program execution time: 10.06022ms` + +## Feedback + +If you have any questions, feedback, feature requests or just want to reach out, the best place would be The Graph Discord where we have a dedicated channel for Matchstick, called 🔥| unit-testing. diff --git a/pages/ja/developer/publish-subgraph.mdx b/pages/ja/developer/publish-subgraph.mdx new file mode 100644 index 000000000000..2f35f5eb1bae --- /dev/null +++ b/pages/ja/developer/publish-subgraph.mdx @@ -0,0 +1,27 @@ +--- +title: Publish a Subgraph to the Decentralized Network +--- + +Once your subgraph has been [deployed to the Subgraph Studio](/studio/deploy-subgraph-studio), you have tested it out, and are ready to put it into production, you can then publish it to the decentralized network. + +Publishing a Subgraph to the decentralized network makes it available for [curators](/curating) to begin curating on it, and [indexers](/indexing) to begin indexing it. + +For a walkthrough of how to publish a subgraph to the decentralized network, see [this video](https://youtu.be/HfDgC2oNnwo?t=580). + +### Networks + +The decentralized network currently supports both Rinkeby and Ethereum Mainnet. + +### Publishing a subgraph + +Subgraphs can be published to the decentralized network directly from the Subgraph Studio dashboard by clicking on the **Publish** button. Once a subgraph is published, it will be available to view in the [Graph Explorer](https://thegraph.com/explorer/). + +- Subgraphs published to Rinkeby can index and query data from either the Rinkeby network or Ethereum Mainnet. + +- Subgraphs published to Ethereum Mainnet can only index and query data from Ethereum Mainnet, meaning that you cannot publish subgraphs to the main decentralized network that index and query testnet data. + +- When publishing a new version for an existing subgraph the same rules apply as above. + +### Updating metadata for a published subgraph + +Once your subgraph has been published to the decentralized network, you can modify the metadata at any time by making the update in the Subgraph Studio dashboard of the subgraph. After saving the changes and publishing your updates to the network, they will be reflected in the Graph Explorer. This won’t create a new version, as your deployment hasn’t changed. diff --git a/pages/ja/developer/query-the-graph.mdx b/pages/ja/developer/query-the-graph.mdx new file mode 100644 index 000000000000..ae480b1e6883 --- /dev/null +++ b/pages/ja/developer/query-the-graph.mdx @@ -0,0 +1,32 @@ +--- +title: Query The Graph +--- + +With the subgraph deployed, visit the [Graph Explorer](https://thegraph.com/explorer) to open up a [GraphiQL](https://github.com/graphql/graphiql) interface where you can explore the deployed GraphQL API for the subgraph by issuing queries and viewing the schema. + +An example is provided below, but please see the [Query API](/developer/graphql-api) for a complete reference on how to query the subgraph's entities. + +#### Example + +This query lists all the counters our mapping has created. Since we only create one, the result will only contain our one `default-counter`: + +```graphql +{ + counters { + id + value + } +} +``` + +## Using The Graph Explorer + +Each subgraph published to the decentralized Graph Explorer has a unique query URL that you can find by navigating to the subgraph details page and clicking on the "Query" button on the top right corner. This will open a side pane that will give you the unique query URL of the subgraph as well as some instructions about how to query it. + +![Query Subgraph Pane](/img/query-subgraph-pane.png) + +As you can notice, this query URL must use a unique API key. You can create and manage your API keys in the [Subgraph Studio](https://thegraph.com/studio) in the "API Keys" section. Learn more about how to use Subgraph Studio [here](/studio/subgraph-studio). + +Querying subgraphs using your API keys will generate query fees that will be paid in GRT. You can learn more about billing [here](/studio/billing). + +You can also use the GraphQL playground in the "Playground" tab to query a subgraph within The Graph Explorer. diff --git a/pages/ja/developer/querying-from-your-app.mdx b/pages/ja/developer/querying-from-your-app.mdx new file mode 100644 index 000000000000..c09c44efee72 --- /dev/null +++ b/pages/ja/developer/querying-from-your-app.mdx @@ -0,0 +1,136 @@ +--- +title: Querying from an Application +--- + +Once a subgraph is deployed to the Subgraph Studio or to the Graph Explorer, you will be given the endpoint for your GraphQL API that should look something like this: + +**Subgraph Studio (testing endpoint)** + +```sh +Queries (HTTP) +https://api.studio.thegraph.com/query/// +``` + +**Graph Explorer** + +```sh +Queries (HTTP) +https://gateway.thegraph.com/api//subgraphs/id/ +``` + +Using the GraphQL endpoint, you can use various GraphQL Client libraries to query the subgraph and populate your app with the data indexed by the subgraph. + +Here are a couple of the more popular GraphQL clients in the ecosystem and how to use them: + +### Apollo client + +[Apollo client](https://www.apollographql.com/docs/) supports web projects including frameworks like React and Vue, as well as mobile clients like iOS, Android, and React Native. + +Let's look at how fetch data from a subgraph with Apollo client in a web project. + +First, install `@apollo/client` and `graphql`: + +```sh +npm install @apollo/client graphql +``` + +Then you can query the API with the following code: + +```javascript +import { ApolloClient, InMemoryCache, gql } from '@apollo/client' + +const APIURL = 'https://api.studio.thegraph.com/query///' + +const tokensQuery = ` + query { + tokens { + id + tokenID + contentURI + metadataURI + } + } +` + +const client = new ApolloClient({ + uri: APIURL, + cache: new InMemoryCache(), +}) + +client + .query({ + query: gql(tokensQuery), + }) + .then((data) => console.log('Subgraph data: ', data)) + .catch((err) => { + console.log('Error fetching data: ', err) + }) +``` + +To use variables, you can pass in a `variables` argument to the query: + +```javascript +const tokensQuery = ` + query($first: Int, $orderBy: BigInt, $orderDirection: String) { + tokens( + first: $first, orderBy: $orderBy, orderDirection: $orderDirection + ) { + id + tokenID + contentURI + metadataURI + } + } +` + +client + .query({ + query: gql(tokensQuery), + variables: { + first: 10, + orderBy: 'createdAtTimestamp', + orderDirection: 'desc', + }, + }) + .then((data) => console.log('Subgraph data: ', data)) + .catch((err) => { + console.log('Error fetching data: ', err) + }) +``` + +### URQL + +Another option is [URQL](https://formidable.com/open-source/urql/), a somewhat lighter weight GraphQL client library. + +Let's look at how fetch data from a subgraph with URQL in a web project. + +First, install `urql` and `graphql`: + +```sh +npm install urql graphql +``` + +Then you can query the API with the following code: + +```javascript +import { createClient } from 'urql' + +const APIURL = 'https://api.thegraph.com/subgraphs/name/username/subgraphname' + +const tokensQuery = ` + query { + tokens { + id + tokenID + contentURI + metadataURI + } + } +` + +const client = createClient({ + url: APIURL, +}) + +const data = await client.query(tokensQuery).toPromise() +``` diff --git a/pages/ja/developer/quick-start.mdx b/pages/ja/developer/quick-start.mdx new file mode 100644 index 000000000000..6893d424ddc2 --- /dev/null +++ b/pages/ja/developer/quick-start.mdx @@ -0,0 +1,227 @@ +--- +title: Quick Start +--- + +This guide will quickly take you through how to initialize, create, and deploy your subgraph on: + +- **Subgraph Studio** - used only for subgraphs that index **Ethereum mainnet** +- **Hosted Service** - used for subgraphs that index **other networks** outside of Ethereum mainnnet (e.g. Binance, Matic, etc) + +## Subgraph Studio + +### 1. Install the Graph CLI + +The Graph CLI is written in JavaScript and you will need to have either `npm` or `yarn` installed to use it. + +```sh +# NPM +$ npm install -g @graphprotocol/graph-cli + +# Yarn +$ yarn global add @graphprotocol/graph-cli +``` + +### 2. Initialize your Subgraph + +- Initialize your subgraph from an existing contract. + +```sh +graph init --studio +``` + +- Your subgraph slug is an identifier for your subgraph. The CLI tool will walk you through the steps for creating a subgraph, such as contract address, network, etc as you can see in the screenshot below. + +![Subgraph command](/img/Subgraph-Slug.png) + +### 3. Write your Subgraph + +The previous commands creates a scaffold subgraph that you can use as a starting point for building your subgraph. When making changes to the subgraph, you will mainly work with three files: + +- Manifest (subgraph.yaml) - The manifest defines what datasources your subgraphs will index. +- Schema (schema.graphql) - The GraphQL schema defines what data you wish to retreive from the subgraph. +- AssemblyScript Mappings (mapping.ts) - This is the code that translates data from your datasources to the entities defined in the schema. + +For more information on how to write your subgraph, see [Create a Subgraph](/developer/create-subgraph-hosted). + +### 4. Deploy to the Subgraph Studio + +- Go to the Subgraph Studio [https://thegraph.com/studio/](https://thegraph.com/studio/) and connect your wallet. +- Click "Create" and enter the subgraph slug you used in step 2. +- Run these commands in the subgraph folder + +```sh +$ graph codegen +$ graph build +``` + +- Authenticate and deploy your subgraph. The deploy key can be found on the Subgraph page in Subgraph Studio. + +```sh +$ graph auth --studio +$ graph deploy --studio +``` + +- You will be asked for a version label. It's strongly recommended to use the following conventions for naming your versions. Example: `0.0.1`, `v1`, `version1` + +### 5. Check your logs + +The logs should tell you if there are any errors. If your subgraph is failing, you can query the subgraph health by using the [GraphiQL Playground](https://graphiql-online.com/). Use [this endpoint](https://api.thegraph.com/index-node/graphql). Note that you can leverage the query below and input your deployment ID for your subgraph. In this case, `Qm...` is the deployment ID (which can be located on the Subgraph page under **Details**). The query below will tell you when a subgraph fails so you can debug accordingly: + +```sh +{ + indexingStatuses(subgraphs: ["Qm..."]) { + node + synced + health + fatalError { + message + block { + number + hash + } + handler + } + nonFatalErrors { + message + block { + number + hash + } + handler + } + chains { + network + chainHeadBlock { + number + } + earliestBlock { + number + } + latestBlock { + number + } + lastHealthyBlock { + number + } + } + entityCount + } +} +``` + +### 6. Query your Subgraph + +You can now query your subgraph by following [these instructions](/developer/query-the-graph). You can query from your dapp if you don't have your API key via the free, rate limited temporary query URL that can be used for development and staging. You can read the additional instructions for how to query a subgraph from a frontend application [here](/developer/querying-from-your-app). + +## Hosted Service + +### 1. Install the Graph CLI + +"The Graph CLI is an npm package and you will need `npm` or `yarn` installed to use it. + +```sh +# NPM +$ npm install -g @graphprotocol/graph-cli + +# Yarn +$ yarn global add @graphprotocol/graph-cli +``` + +### 2. Initialize your Subgraph + +- Initialize your subgraph from an existing contract. + +```sh +$ graph init --product hosted-service --from-contract
+``` + +- You will be asked for a subgraph name. The format is `/`. Ex: `graphprotocol/examplesubgraph` + +- If you'd like to initialize from an example, run the command below: + +```sh +$ graph init --product hosted-service --from-example +``` + +- In the case of the example, the subgraph is based on the Gravity contract by Dani Grant that manages user avatars and emits `NewGravatar` or `UpdateGravatar` events whenever avatars are created or updated. + +### 3. Write your Subgraph + +The previous command will have created a scaffold from where you can build your subgraph. When making changes to the subgraph, you will mainly work with three files: + +- Manifest (subgraph.yaml) - The manifest defines what datasources your subgraph will index +- Schema (schema.graphql) - The GraphQL schema define what data you wish to retrieve from the subgraph +- AssemblyScript Mappings (mapping.ts) - This is the code that translates data from your datasources to the entities defined in the schema + +For more information on how to write your subgraph, see [Create a Subgraph](/developer/create-subgraph-hosted). + +### 4. Deploy your Subgraph + +- Sign into the [Hosted Service](https://thegraph.com/hosted-service/) using your github account +- Click Add Subgraph and fill out the required information. Use the same subgraph name as in step 2. +- Run codegen in the subgraph folder + +```sh + # NPM +$ npm run codegen + +# Yarn +$ yarn codegen +``` + +- Add your Access token and deploy your subgraph. The access token is found on your dashboard in the Hosted Service. + +```sh +$ graph auth --product hosted-service +$ graph deploy --product hosted-service / +``` + +### 5. Check your logs + +The logs should tell you if there are any errors. If your subgraph is failing, you can query the subgraph health by using the [GraphiQL Playground](https://graphiql-online.com/). Use [this endpoint](https://api.thegraph.com/index-node/graphql). Note that you can leverage the query below and input your deployment ID for your subgraph. In this case, `Qm...` is the deployment ID (which can be located on the Subgraph page under **Details**). The query below will tell you when a subgraph fails so you can debug accordingly: + +```sh +{ + indexingStatuses(subgraphs: ["Qm..."]) { + node + synced + health + fatalError { + message + block { + number + hash + } + handler + } + nonFatalErrors { + message + block { + number + hash + } + handler + } + chains { + network + chainHeadBlock { + number + } + earliestBlock { + number + } + latestBlock { + number + } + lastHealthyBlock { + number + } + } + entityCount + } +} +``` + +### 6. Query your Subgraph + +Follow [these instructions](/hosted-service/query-hosted-service) to query your subgraph on the Hosted Service. diff --git a/pages/ja/explorer.mdx b/pages/ja/explorer.mdx index ce274725477c..cbe4fa6e03c0 100644 --- a/pages/ja/explorer.mdx +++ b/pages/ja/explorer.mdx @@ -11,7 +11,7 @@ Welcome to the Graph Explorer, or as we like to call it, your decentralized port title="YouTube ビデオプレイヤー" frameBorder="0" allowFullScreen - > +> ## サブグラフ @@ -115,7 +115,7 @@ Welcome to the Graph Explorer, or as we like to call it, your decentralized port 特筆すべき重要な詳細をいくつか挙げます： - **クエリフィーは消費者によって生成された報酬を表し**、サブグラフへの割り当てが終了し、提供したデータが消費者によって検証された後、少なくとも 7 エポック（下記参照）の期間後にインデクサが請求することができます（または請求しないこともできます）。 -- **I インデクシング報酬は、インデクサーがエポック期間中にネットワーク発行から請求した報酬の量を表します。 **プロトコルの発行は固定されていますが、報酬は、インデクサーがインデックスを作成したサブグラフに対する割り当てを終了したときにのみミントされます。 Thus the per-epoch number of rewards varies (ie. during some epochs, Indexers might’ve collectively closed allocations that have been open for many days). +- **Indexing rewards represent the amount of rewards the Indexers claimed from the network issuance during the epoch.** Although the protocol issuance is fixed, the rewards only get minted once the Indexers close their allocations towards the subgraphs they’ve been indexing. Thus the per-epoch number of rewards varies (ie. during some epochs, Indexers might’ve collectively closed allocations that have been open for many days). ![エクスプローラーイメージ ８](/img/Network-Stats.png) diff --git a/pages/ja/hosted-service/deploy-subgraph-hosted.mdx b/pages/ja/hosted-service/deploy-subgraph-hosted.mdx new file mode 100644 index 000000000000..bdc532e205e4 --- /dev/null +++ b/pages/ja/hosted-service/deploy-subgraph-hosted.mdx @@ -0,0 +1,160 @@ +--- +title: Deploy a Subgraph to the Hosted Service +--- + +If you have not checked out already, check out how to write the files that make up a [subgraph manifest](/developer/create-subgraph-hosted#the-subgraph-manifest) and how to install the [Graph CLI](https://github.com/graphprotocol/graph-cli) to generate code for your subgraph. Now, it's time to deploy your subgraph to the Hosted Service, also known as the Hosted Service. + +## Create a Hosted Service account + +Before using the Hosted Service, create an account in our Hosted Service. You will need a [Github](https://github.com/) account for that; if you don't have one, you need to create that first. Then, navigate to the [Hosted Service](https://thegraph.com/hosted-service/), click on the _'Sign up with Github'_ button and complete Github's authorization flow. + +## Store the Access Token + +After creating an account, navigate to your [dashboard](https://thegraph.com/hosted-service/dashboard). Copy the access token displayed on the dashboard and run `graph auth --product hosted-service `. This will store the access token on your computer. You only need to do this once, or if you ever regenerate the access token. + +## Create a Subgraph on the Hosted Service + +Before deploying the subgraph, you need to create it in The Graph Explorer. Go to the [dashboard](https://thegraph.com/hosted-service/dashboard) and click on the _'Add Subgraph'_ button and fill in the information below as appropriate: + +**Image** - Select an image to be used as a preview image and thumbnail for the subgraph. + +**Subgraph Name** - Together with the account name that the subgraph is created under, this will also define the `account-name/subgraph-name`-style name used for deployments and GraphQL endpoints. _This field cannot be changed later._ + +**Account** - The account that the subgraph is created under. This can be the account of an individual or organization. _Subgraphs cannot be moved between accounts later._ + +**Subtitle** - Text that will appear in subgraph cards. + +**Description** - Description of the subgraph, visible on the subgraph details page. + +**GitHub URL** - Link to the subgraph repository on GitHub. + +**Hide** - Switching this on hides the subgraph in the 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 [Define a Subgraph section](/developer/define-subgraph-hosted). + +## Deploy a Subgraph on the Hosted Service + +Deploying your subgraph will upload the subgraph files that you've built with `yarn build` to IPFS and tell the Graph Explorer to start indexing your subgraph using these files. + +You deploy the subgraph by running `yarn deploy` + +After deploying the subgraph, the 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 Ethereum blocks, starting with the genesis block, syncing can take from a few minutes to several hours. The subgraph status switches to `Synced` once the Graph Node has extracted all data from historical blocks. The Graph Node will continue inspecting Ethereum blocks for your subgraph as these blocks are mined. + +## Redeploying a Subgraph + +When making changes to your subgraph definition, for example to fix a problem in the entity mappings, run the `yarn deploy` command above again to deploy the updated version of your subgraph. Any update of a subgraph requires that Graph Node reindexes your entire subgraph, again starting with the genesis block. + +If your previously deployed subgraph is still in status `Syncing`, it will be immediately replaced with the newly deployed version. If the previously deployed subgraph is already fully synced, Graph Node will mark the newly deployed version as the `Pending Version`, sync it in the background, and only replace the currently deployed version with the new one once syncing the new version has finished. This ensures that you have a subgraph to work with while the new version is syncing. + +### Deploying the subgraph to multiple Ethereum networks + +In some cases, you will want to deploy the same subgraph to multiple Ethereum networks without duplicating all of its code. The main challenge that comes with this is that the contract addresses on these networks are different. One solution that allows to parameterize aspects like contract addresses is to generate parts of it using a templating system like [Mustache](https://mustache.github.io/) or [Handlebars](https://handlebarsjs.com/). + +To illustrate this approach, let's assume a subgraph should be deployed to mainnet and Ropsten using different contract addresses. You could then define two config files providing the addresses for each network: + +```json +{ + "network": "mainnet", + "address": "0x123..." +} +``` + +and + +```json +{ + "network": "ropsten", + "address": "0xabc..." +} +``` + +Along with that, you would substitute the network name and addresses in the manifest with variable placeholders `{{network}}` and `{{address}}` and rename the manifest to e.g. `subgraph.template.yaml`: + +```yaml +# ... +dataSources: + - kind: ethereum/contract + name: Gravity + network: mainnet + network: {{network}} + source: + address: '0x2E645469f354BB4F5c8a05B3b30A929361cf77eC' + address: '{{address}}' + abi: Gravity + mapping: + kind: ethereum/events +``` + +In order generate a manifest to either network, you could add two additional commands to `package.json` along with a dependency on `mustache`: + +```json +{ + ... + "scripts": { + ... + "prepare:mainnet": "mustache config/mainnet.json subgraph.template.yaml > subgraph.yaml", + "prepare:ropsten": "mustache config/ropsten.json subgraph.template.yaml > subgraph.yaml" + }, + "devDependencies": { + ... + "mustache": "^3.1.0" + } +} +``` + +To deploy this subgraph for mainnet or Ropsten you would now simply run one of the two following commands: + +```sh +# Mainnet: +yarn prepare:mainnet && yarn deploy + +# Ropsten: +yarn prepare:ropsten && yarn deploy +``` + +A working example of this can be found [here](https://github.com/graphprotocol/example-subgraph/tree/371232cf68e6d814facf5e5413ad0fef65144759). + +**Note:** This approach can also be applied more complex situations, where it is necessary to substitute more than contract addresses and network names or where generating mappings or ABIs from templates as well. + +## Checking subgraph health + +If a subgraph syncs successfully, that is a good sign that it will continue to run well forever. However, new triggers on the chain might cause your subgraph to hit an untested error condition or it may start to fall behind due to performance issues or issues with the node operators. + +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](https://github.com/graphprotocol/graph-node/blob/master/server/index-node/src/schema.graphql). Here is an example query that checks the status of the current version of a subgraph: + +```graphql +{ + indexingStatusForCurrentVersion(subgraphName: "org/subgraph") { + synced + health + fatalError { + message + block { + number + hash + } + handler + } + chains { + chainHeadBlock { + number + } + latestBlock { + number + } + } + } +} +``` + +This will give you the `chainHeadBlock` which you can compare with the `latestBlock` on your subgraph to check if it is running behind. `synced` informs if the subgraph has ever caught up to the chain. `health` can currently take the values of `healthy` if no errors ocurred, or `failed` if there was an error which halted the progress of the subgraph. In this case you can check the `fatalError` field for details on this error. + +## Subgraph archive policy + +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 which 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 30 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. diff --git a/pages/ja/hosted-service/migrating-subgraph.mdx b/pages/ja/hosted-service/migrating-subgraph.mdx new file mode 100644 index 000000000000..5ac96ad86eec --- /dev/null +++ b/pages/ja/hosted-service/migrating-subgraph.mdx @@ -0,0 +1,151 @@ +--- +title: Migrating an Existing Subgraph to The Graph Network +--- + +## Introduction + +This is a guide for the migration of subgraphs from the Hosted Service (also known as the Hosted Service) to The Graph Network. The migration to The Graph Network has been successful for projects like Opyn, UMA, mStable, Audius, PoolTogether, Livepeer, RAI, Enzyme, DODO, Opyn, Pickle, and BadgerDAO all of which are relying on data served by Indexers on the network. There are now over 200 subgraphs live on The Graph Network, generating query fees and actively indexing web3 data. + +This will tell you everything you need to know about how to migrate to the decentralized network and manage your subgraphs moving forward. The process is quick and your subgraphs will forever benefit from the reliability and performance that you can only get on The Graph Network. + +### Migrating An Existing Subgraph to The Graph Network + +1. Get the latest version of the graph-cli installed: + +```sh +npm install -g @graphprotocol/graph-cli +``` + +```sh +yarn global add @graphprotocol/graph-cli +``` + +2. Create a subgraph on the [Subgraph Studio](https://thegraph.com/studio/). Guides on how to do that can be found in the [Subgraph Studio docs](/studio/subgraph-studio) and in [this video tutorial](https://www.youtube.com/watch?v=HfDgC2oNnwo). +3. Inside the main project subgraph repository, authenticate the subgraph to deploy and build on the studio: + +```sh +graph auth --studio +``` + +4. Generate files and build the subgraph: + +```sh +graph codegen && graph build +``` + +5. Deploy the subgraph to the Studio. You can find your `` in the Studio UI, which is based on the name of your subgraph. + +```sh + graph deploy --studio +``` + +6. Test queries on the Studio's playground. Here are some examples for the [Sushi - Mainnet Exchange Subgraph](https://thegraph.com/explorer/subgraph?id=0x4bb4c1b0745ef7b4642feeccd0740dec417ca0a0-0&view=Playground): + +```sh +{ + users(first: 5) { + id + liquidityPositions { + id + } + } + bundles(first: 5) { + id + ethPrice + } +} +``` + +7. Fill in the description and the details of your subgraph and choose up to 3 categories. Upload a project image in the Studio if you'd like as well. +8. Publish the subgraph on The Graph's Network by hitting the "Publish" button. + +- Remember that publishing is an on-chain action and will require gas to be paid for in Ethereum - see an example transaction [here](https://etherscan.io/tx/0xd0c3fa0bc035703c9ba1ce40c1862559b9c5b6ea1198b3320871d535aa0de87b). Prices are roughly around 0.0425 ETH at 100 gwei. +- Any time you need to upgrade your subgraph, you will be charged an upgrade fee. Remember, upgrading is just publishing another version of your existing subgraph on-chain. Because this incurs a cost, it is highly recommended to deploy and test your subgraph on Rinkeby before deploying to mainnet. It can, in some cases, also require some GRT if there is no signal on that subgraph. In the case there is signal/curation on that subgraph version (using auto-migrate), the taxes will be split. + +And that's it! After you are done publishing, you'll be able to view your subgraphs live on the network via [The Graph Explorer](https://thegraph.com/explorer). + +### Upgrading a Subgraph on the Network + +If you would like to upgrade an existing subgraph on the network, you can do this by deploying a new version of your subgraph to the Subgraph Studio using the Graph CLI. + +1. Make changes to your current subgraph. A good idea is to test small fixes on the Subgraph Studio by publishing to Rinkeby. +2. Deploy the following and specify the new version in the command (eg. v0.0.1, v0.0.2, etc): + +```sh +graph deploy --studio +``` + +3. Test the new version in the Subgraph Studio by querying in the playground +4. Publish the new version on The Graph Network. Remember that this requires gas (as described in the section above). + +### Owner Upgrade Fee: Deep Dive + +An upgrade requires GRT to be migrated from the old version of the subgraph to the new version. This means that for every upgrade, a new bonding curve will be created (more on bonding curves [here](/curating#bonding-curve-101)). + +The new bonding curve charges the 2.5% curation tax on all GRT being migrated to the new version. The owner must pay 50% of this, or 1.25%. The other 1.25% is absorbed by all the curators as a fee. This incentive design is in place to prevent an owner of a subgraph from being able to drain all their curator's funds with recursive upgrade calls. The example below is only the case if your subgraph is being actively curated on. If there is no curation activity, you will have to pay a minimum of 100 GRT in order to signal yourself on your own subgraph. + +- 100,000 GRT is signaled using auto-migrate on v1 of a subgraph +- Owner upgrades to v2. 100,000 GRT is migrated to a new bonding curve, where 97,500 GRT get put into the new curve and 2,500 GRT is burned +- The owner then has 1250 GRT burned to pay for half the fee. The owner must have this in their wallet before the upgrade, otherwise the upgrade will not succeed. This happens in the same transaction as the upgrade. + +_While this mechanism is currently live on the network, the community is currently discussing ways to reduce the cost of upgrades for subgraph developers._ + +### Maintaining a Stable Version of a Subgraph + +If you're making a lot of changes to your subgraph, it is not a good idea to continually upgrade it and front the upgrade costs. Maintaining a stable and consistent version of your subgraph is critical, not only from the cost perspective, but also so that Indexers can feel confident in their syncing times. Indexers should be flagged when you plan for an upgrade so that Indexer syncing times do not get impacted. Feel free to leverage the [#Indexers channel](https://discord.gg/8tgJ7rKW) on Discord to let Indexers know when you're versioning your subgraphs. + +Subgraphs are open API that external developers are leveraging. Open APIs need to follow strict standards so that they do not break external developers' applications. In The Graph Network, a subgraph developer must consider Indexers and how long it takes them to sync a new subgraph **as well as** other developers who are using their subgraphs. + +### Updating the Metadata of a Subgraph + +You can update the metadata of your subgraphs without having to publish a new version. The metadata includes the subgraph name, image, description, website URL, source code URL, and categories. Developers can do this by updating their subgraph details in the Subgraph Studio where you can edit all applicable fields. + +Make sure **Update Subgraph Details in Explorer** is checked and click on **Save**. If this is checked, an an on-chain transaction will be generated that updates subgraph details in the Explorer without having to publish a new version with a new deployment. + +## Best Practices for Deploying a Subgraph to The Graph Network + +1. Leveraging an ENS name for Subgraph Development + +- Set up your ENS: [https://app.ens.domains/](https://app.ens.domains/) +- Add your ENS name to your settings [here](https://thegraph.com/explorer/settings?view=display-name). + +The more filled out your profiles are, the better the chances for your subgraphs to be indexed and curated. + +## Deprecating a Subgraph on The Graph Network + +Follow the steps [here](/developer/deprecating-a-subgraph) to deprecate your subgraph and remove it from The Graph Network. + +## Querying a Subgraph + Billing on The Graph Network + +The Hosted Service was set up to allow developers to deploy their subgraphs without any restrictions. + +In order for The Graph Network to truly be decentralized, query fees have to be paid as a core part of the protocol's incentives. For more information on subscribing to APIs and paying the query fees, check out billing documentation [here](/studio/billing). + +### Estimate Query Fees on the Network + +While this is not a live feature in the product UI, you can set your maximum budget per query by taking the amount you're willing to pay per month and divide it by your expected query volume. + +While you get to decide on your query budget, there is no guarantee that an Indexer will be willing to serve queries at that price. If a Gateway can match you to an Indexer willing to serve a query at, or lower than, the price you are willing to pay, you will pay the delta/difference of your budget **and** their price. As a consequence of that, a lower query price reduces the pool of Indexers available to you, which may affect the quality of service you receive. It's beneficial to have high query fees, as that may attract curation and big name Indexers to your subgraph. + +Remember that it's a dynamic and growing market, but how you interact with it is in your control. There is no maximum or minimum price specified in the protocol or in the Gateways. For example, you can look at the price paid by a few of the dapps on the network (on a per week basis), below. See the last column which shows query fees in GRT. For example, [Pickle Finance](https://www.pickle.finance/) has 8 requests per second and paid 2.4 GRT for one week. + +![QueryFee](/img/QueryFee.png) + +## Additional Resources + +If you're still confused, fear not! Check out the following resources or watch our video guide on migrating subgraphs to the decentralized network below: + +
+ +
+ +- [The Graph Network Contracts](https://github.com/graphprotocol/contracts) +- [Curation Contract](https://github.com/graphprotocol/contracts/blob/dev/contracts/curation/Curation.sol) - the underlying contract that the GNS wraps around + - Address - `0x8fe00a685bcb3b2cc296ff6ffeab10aca4ce1538` +- [Subgraph Studio documentation](/studio/subgraph-studio) diff --git a/pages/ja/hosted-service/query-hosted-service.mdx b/pages/ja/hosted-service/query-hosted-service.mdx new file mode 100644 index 000000000000..731e3a3120b2 --- /dev/null +++ b/pages/ja/hosted-service/query-hosted-service.mdx @@ -0,0 +1,28 @@ +--- +title: Query the Hosted Service +--- + +With the subgraph deployed, visit the [Hosted Service](https://thegraph.com/hosted-service/) to open up a [GraphiQL](https://github.com/graphql/graphiql) interface where you can explore the deployed GraphQL API for the subgraph by issuing queries and viewing the schema. + +An example is provided below, but please see the [Query API](/developer/graphql-api) for a complete reference on how to query the subgraph's entities. + +#### Example + +This query lists all the counters our mapping has created. Since we only create one, the result will only contain our one `default-counter`: + +```graphql +{ + counters { + id + value + } +} +``` + +## Using The Hosted Service + +The Graph Explorer and its GraphQL playground is a useful way to explore and query deployed subgraphs on the Hosted Service. + +Some of the main features are detailed below: + +![Explorer Playground](/img/explorer-playground.png) diff --git a/pages/ja/hosted-service/what-is-hosted-service.mdx b/pages/ja/hosted-service/what-is-hosted-service.mdx new file mode 100644 index 000000000000..7f604c8dc31a --- /dev/null +++ b/pages/ja/hosted-service/what-is-hosted-service.mdx @@ -0,0 +1,77 @@ +--- +title: What is the Hosted Service? +--- + +This section will walk you through deploying a subgraph to the Hosted Service, otherwise known as the [Hosted Service.](https://thegraph.com/hosted-service/) As a reminder, the Hosted Service will not be shut down soon. We will gradually sunset the Hosted Service once we reach feature parity with the decentralized network. Your subgraphs deployed on the Hosted Service are still available [here.](https://thegraph.com/hosted-service/) + +If you don't have an account on the Hosted Service, you can signup with your Github account. Once you authenticate, you can start creating subgraphs through the UI and deploying them from your terminal. Graph Node supports a number of Ethereum testnets (Rinkeby, Ropsten, Kovan) in addition to mainnet. + +## Create a Subgraph + +First follow the instructions [here](/developer/define-subgraph-hosted) to install the Graph CLI. Create a subgraph by passing in `graph init --product hosted service` + +### From an Existing Contract + +If you already have a smart contract deployed to Ethereum mainnet or one of the testnets, bootstrapping a new subgraph from this contract can be a good way to get started on the Hosted Service. + +You can use this command to create a subgraph that indexes all events from an existing contract. This will attempt to fetch the contract ABI from [Etherscan](https://etherscan.io/). + +```sh +graph init \ + --product hosted-service + --from-contract \ + / [] +``` + +Additionally, you can use the following optional arguments. If the ABI cannot be fetched from Etherscan, it falls back to requesting a local file path. If any optional arguments are missing from the command, it takes you through an interactive form. + +```sh +--network \ +--abi \ +``` + +The `` in this case is your github user or organization name, `` is the name for your subgraph, and `` is the optional name of the directory where graph init will put the example subgraph manifest. The `` is the address of your existing contract. `` is the name of the Ethereum network that the contract lives on. `` is a local path to a contract ABI file. **Both --network and --abi are optional.** + +### From an Example Subgraph + +The second mode `graph init` supports is creating a new project from an example subgraph. The following command does this: + +``` +graph init --from-example --product hosted-service / [] +``` + +The example subgraph is based on the Gravity contract by Dani Grant that manages user avatars and emits `NewGravatar` or `UpdateGravatar` events whenever avatars are created or updated. The subgraph handles these events by writing `Gravatar` entities to the Graph Node store and ensuring these are updated according to the events. Continue on to the [subgraph manifest](/developer/create-subgraph-hosted#the-subgraph-manifest) to better understand which events from your smart contracts to pay attention to, mappings, and more. + +## Supported Networks on the Hosted Service + +Please note that the following networks are supported on the Hosted Service. Networks outside of Ethereum mainnet ('mainnet') are not currently supported on [The Graph Explorer.](https://thegraph.com/explorer) + +- `mainnet` +- `kovan` +- `rinkeby` +- `ropsten` +- `goerli` +- `poa-core` +- `poa-sokol` +- `xdai` +- `near-mainnet` +- `near-testnet` +- `matic` +- `mumbai` +- `fantom` +- `bsc` +- `chapel` +- `clover` +- `avalanche` +- `fuji` +- `celo` +- `celo-alfajores` +- `fuse` +- `moonriver` +- `mbase` +- `arbitrum-one` +- `arbitrum-rinkeby` +- `optimism` +- `optimism-kovan` +- `aurora` +- `aurora-testnet` diff --git a/pages/ja/indexing.mdx b/pages/ja/indexing.mdx index 2fa0e4248771..c6c9dd55cc6d 100644 --- a/pages/ja/indexing.mdx +++ b/pages/ja/indexing.mdx @@ -26,7 +26,7 @@ import { Difficulty } from '@/components' ### 報酬の分配方法は？ -インデキシング報酬は、年間 3％の発行量に設定されているプロトコル・インフレから得られます。 報酬は、それぞれのサブグラフにおけるすべてのキュレーション・シグナルの割合に基づいてサブグラフに分配され、そのサブグラフに割り当てられたステークに基づいてインデクサーに分配されます。 **報酬の獲得には、アービトレーション・チャーターで定められた基準を満たす有効なインデックス証明（POI）を使用して割り当てを終了する必要があります。 ** +インデキシング報酬は、年間 3％の発行量に設定されているプロトコル・インフレから得られます。 報酬は、それぞれのサブグラフにおけるすべてのキュレーション・シグナルの割合に基づいてサブグラフに分配され、そのサブグラフに割り当てられたステークに基づいてインデクサーに分配されます。 **An allocation must be closed with a valid proof of indexing (POI) that meets the standards set by the arbitration charter in order to be eligible for rewards.** コミュニティでは、報酬を計算するための数多くのツールが作成されており、それらは[コミュニティガイドコレクション](https://www.notion.so/Community-Guides-abbb10f4dba040d5ba81648ca093e70c)にまとめられています。 また、[Discord サーバー](https://discord.gg/vtvv7FP)の#delegators チャンネルや#indexers チャンネルでも、最新のツールリストを見ることができます。 @@ -115,7 +115,7 @@ Disputes can be viewed in the UI in an Indexer's profile page under the `Dispute - **Large** - 現在使用されているすべてのサブグラフのインデックスを作成し、関連するトラフィックのリクエストに対応します | Setup | (CPUs) | (memory in GB) | (disk in TBs) | (CPUs) | (memory in GB) | -| -------- | :----: | :------------: | :-----------: | :----: | :------------: | +| -------- |:------:|:--------------:|:-------------:|:------:|:--------------:| | Small | 4 | 8 | 1 | 4 | 16 | | Standard | 8 | 30 | 1 | 12 | 48 | | Medium | 16 | 64 | 2 | 32 | 64 | @@ -149,20 +149,20 @@ Disputes can be viewed in the UI in an Indexer's profile page under the `Dispute #### グラフノード -| Port | Purpose | Routes | CLI Argument | Environment Variable | -| --- | --- | --- | --- | --- | -| 8000 | GraphQL HTTP server
(for subgraph queries) | /subgraphs/id/...

/subgraphs/name/.../... | --http-port | - | -| 8001 | GraphQL WS
(for subgraph subscriptions) | /subgraphs/id/...

/subgraphs/name/.../... | --ws-port | - | -| 8020 | JSON-RPC
(for managing deployments) | / | --admin-port | - | -| 8030 | Subgraph indexing status API | /graphql | --index-node-port | - | -| 8040 | Prometheus metrics | /metrics | --metrics-port | - | +| Port | Purpose | Routes | CLI Argument | Environment Variable | +| ---- | ------------------------------------------------------- | ------------------------------------------------------------------- | ----------------- | -------------------- | +| 8000 | GraphQL HTTP server
(for subgraph queries) | /subgraphs/id/...

/subgraphs/name/.../... | --http-port | - | +| 8001 | GraphQL WS
(for subgraph subscriptions) | /subgraphs/id/...

/subgraphs/name/.../... | --ws-port | - | +| 8020 | JSON-RPC
(for managing deployments) | / | --admin-port | - | +| 8030 | Subgraph indexing status API | /graphql | --index-node-port | - | +| 8040 | Prometheus metrics | /metrics | --metrics-port | - | #### Indexer Service -| Port | Purpose | Routes | CLI Argument | Environment Variable | -| --- | --- | --- | --- | --- | -| 7600 | GraphQL HTTP server
(for paid subgraph queries) | /subgraphs/id/...
/status
/channel-messages-inbox | --port | `INDEXER_SERVICE_PORT` | -| 7300 | Prometheus metrics | /metrics | --metrics-port | - | +| Port | Purpose | Routes | CLI Argument | Environment Variable | +| ---- | ------------------------------------------------------------ | --------------------------------------------------------------------------- | -------------- | ---------------------- | +| 7600 | GraphQL HTTP server
(for paid subgraph queries) | /subgraphs/id/...
/status
/channel-messages-inbox | --port | `INDEXER_SERVICE_PORT` | +| 7300 | Prometheus metrics | /metrics | --metrics-port | - | #### Indexer Agent diff --git a/pages/ja/studio/billing.mdx b/pages/ja/studio/billing.mdx new file mode 100644 index 000000000000..f7b6ef7e4765 --- /dev/null +++ b/pages/ja/studio/billing.mdx @@ -0,0 +1,68 @@ +--- +title: Billing on the Subgraph Studio +--- + +### Overview + +Invoices are statements of payment amounts owed by a customer and are typically generated on a weekly basis in the system. You’ll be required to pay fees based on the query fees you generate using your API keys. The billing contract lives on the [Polygon](https://polygon.technology/) network. It’ll allow you to: + +- Add and remove GRT +- Keep track of your balances based on how much GRT you have added to your account, how much you have removed, and your invoices +- Automatically clear payments based on query fees generated + +In order to add GRT to your account, you will need to go through the following steps: + +1. Purchase GRT and ETH on an exchange of your choice +2. Send the GRT and ETH to your wallet +3. Bridge GRT to Polygon using the UI + + a) You will receive 0.001 Matic in a few minutes after you send any amount of GRT to the Polygon bridge. You can track the transaction on [Polygonscan](https://polygonscan.com/) by inputting your address into the search bar. + +4. Add bridged GRT to the billing contract on Polygon. The billing contract address is: [0x10829DB618E6F520Fa3A01c75bC6dDf8722fA9fE](https://polygonscan.com/address/0x10829DB618E6F520Fa3A01c75bC6dDf8722fA9fE). + + a) In order to complete step #4, you'll need to switch your network in your wallet to Polygon. You can add Polygon's network by connecting your wallet and clicking on "Choose Matic (Polygon) Mainnet" [here.](https://chainlist.org/) Once you've added the network, switch it over in your wallet by navigating to the network pill on the top right hand side corner. In Metamask, the network is called **Matic Mainnnet.** + +At the end of each week, if you used your API keys, you will receive an invoice based on the query fees you have generated during this period. This invoice will be paid using GRT available in your balance. Query volume is evaluated by the API keys you own. Your balance will be updated after fees are withdrawn. + +#### Here’s how you go through the invoicing process: + +There are 4 states your invoice can be in: + +1. Created - your invoice has just been created and not been paid yet +2. Paid - your invoice has been successfully paid +3. Unpaid - there is not enough GRT in your balance on the billing contract +4. Error - there is an error processing the payment + +**See the diagram below for more information:** + +![Billing Flow](/img/billing-flow.png) + +For a quick demo of how billing works on the Subgraph Studio, check out the video below: + +
+ +
+ +### Multisig Users + +Multisigs are smart-contracts that can exist only on the network they have been created, so if you created one on Ethereum Mainnet - it will only exist on Mainnet. Since our billing uses Polygon, if you were to bridge GRT to the multisig address on Polygon the funds would be lost. + +To overcome this issue, we created [a dedicated tool](https://multisig-billing.thegraph.com/) that will help you deposit GRT on our billing contract (on behalf of the multisig) with a standard wallet / EOA (an account controlled by a private key). + +You can access our Multisig Billing Tool here: https://multisig-billing.thegraph.com/ + +This tool will guide you to go through the following steps: + +1. Connect your standard wallet / EOA (this wallet needs to own some ETH as well as the GRT you want to deposit) +2. Bridge GRT to Polygon. You will have to wait 7-8 minutes after the transaction is complete for the bridge transfer to be finalized. +3. Once your GRT is available on your Polygon balance you can deposit them to the billing contract while specifying the multisig address you are funding in the `Multisig Address` field. + +Once the deposit transaction has been confirmed you can go back to [Subgraph Studio](https://thegraph.com/studio/) and connect with your Gnosis Safe Multisig to create API keys and use them to generate queries. + +Those queries will generate invoices that will be paid automatically using the multisig’s billing balance. diff --git a/pages/ja/studio/deploy-subgraph-studio.mdx b/pages/ja/studio/deploy-subgraph-studio.mdx new file mode 100644 index 000000000000..2155d8fe8976 --- /dev/null +++ b/pages/ja/studio/deploy-subgraph-studio.mdx @@ -0,0 +1,68 @@ +--- +title: Deploy a Subgraph to the Subgraph Studio +--- + +Deploying a Subgraph to the Subgraph Studio is quite simple. This will take you through the steps to: + +- Install The Graph CLI (with both yarn and npm) +- Create your Subgraph in the Subgraph Studio +- Authenticate your account from the CLI +- Deploying a Subgraph to the Subgraph Studio + +## Installing Graph CLI + +We are using the same CLI to deploy subgraphs to our [hosted service](https://thegraph.com/hosted-service/) and to the [Subgraph Studio](https://thegraph.com/studio/). Here are the commands to install graph-cli. This can be done using npm or yarn. + +**Install with yarn:** + +```bash +yarn global add @graphprotocol/graph-cli +``` + +**Install with npm:** + +```bash +npm install -g @graphprotocol/graph-cli +``` + +## Create your Subgraph in Subgraph Studio + +Before deploying your actual subgraph you need to create a subgraph in [Subgraph Studio](https://thegraph.com/studio/). We recommend you read our [Studio documentation](/studio/subgraph-studio) to learn more about this. + +## Initialize your Subgraph + +Once your subgraph has been created in Subgraph Studio you can initialize the subgraph code using this command: + +```bash +graph init --studio +``` + +The `` value can be found on your subgraph details page in Subgraph Studio: + +![Subgraph Studio - Slug](/img/doc-subgraph-slug.png) + +After running `graph init`, you will be asked to input the contract address, network and abi that you want to query. Doing this will generate a new folder on your local machine with some basic code to start working on your subgraph. You can then finalize your subgraph to make sure it works as expected. + +## Graph Auth + +Before being able to deploy your subgraph to Subgraph Studio, you need to login to your account within the CLI. To do this, you will need your deploy key that you can find on your "My Subgraphs" page or on your subgraph details page. + +Here is the command that you need to use to authenticate from the CLI: + +```bash +graph auth --studio +``` + +## Deploying a Subgraph to Subgraph Studio + +Once you are ready, you can deploy your subgraph to Subgraph Studio. Doing this won't publish your subgraph to the decentralized network, it will only deploy it to your Studio account where you will be able to test it and update the metadata. + +Here is the CLI command that you need to use to deploy your subgraph. + +```bash +graph deploy --studio +``` + +After running this command, the CLI will ask for a version label, you can name it however you want, you can use labels such as `0.1` and `0.2` or use letters as well such as `uniswap-v2-0.1` . Those labels will be visible in Graph Explorer and can be used by curators to decide if they want to signal on this version or not, so choose them wisely. + +Once deployed, you can test your subgraph in Subgraph Studio using the playground, deploy another version if needed, update the metadata, and when you are ready, publish your subgraph to Graph Explorer. diff --git a/pages/ja/studio/multisig.mdx b/pages/ja/studio/multisig.mdx new file mode 100644 index 000000000000..164835bdb8a4 --- /dev/null +++ b/pages/ja/studio/multisig.mdx @@ -0,0 +1,82 @@ +--- +title: Using a Multisig Wallet +--- + +Subgraph Studio currently doesn't support signing with multisig wallets. Until then, you can follow this guide on how to publish your subgraph by invoking the [GNS contract](https://github.com/graphprotocol/contracts/blob/dev/contracts/discovery/GNS.sol) functions. + +### Create a Subgraph + +Similary to using a regular wallet, you can create a subgraph by connecting your non-multisig wallet in Subgraph Studio. Once you connect the wallet, simply create a new subgraph. Make sure you fill out all the details, such as subgraph name, description, image, website, and source code url if applicable. + +For initializing a starter subgraph, you can follow the commands shown in the UI, or simply run + +``` +graph init --studio +``` + +`SUBGRAPH_SLUG` is the name of your subgraph that you can copy from the UI, or from the URL in the browser. This command should create a folder in your file system with all the necessary files to start developing a subgraph. + +### Deploy a Subgraph + +Once your subgraph is ready to be deployed to the graph node, simply follow the commands shown in the UI, or run the following command: + +``` +graph deploy --studio +``` + +**Note**: Make sure that you are inside of the subgraph folder before running the command. + +### Publish a Subgraph or a Version + +You can either publish a new subgraph to the decentralized network or publish a new version of the previously published subgraph. + +#### Publish a New Subgraph + +There are a couple of ways to publish a subgraph using multisig wallets. Here we'll describe invoking the [`publishNewSubgraph`](https://github.com/graphprotocol/contracts/blob/dev/contracts/discovery/GNS.sol#L231) function in the [GNS contract](https://etherscan.io/address/0xaDcA0dd4729c8BA3aCf3E99F3A9f471EF37b6825) using Etherscan. + +Before we use that function, we need to generate input arguments for it. Access [this page](https://thegraph.com/studio/multisig) in Subgraph Studio and provide the following: + +- Ethereum address of your multisig wallet +- Subgraph that you want to publish +- Version that you want to publish + +After clicking on "Get Arguments", we'll generate all the contract arguments for you! + +There should be 4 arguments: + +- `graphAccount`: which is your multisig account address +- `subgraphDeploymentID`: the hex hash of the deployment ID for that subgraph +- `versionMetadata`: version metadata (label and description) that gets uploaded to IPFS. The hex hash value for that JSON file will be provided. +- `subgraphMetadata`: simlar to version metadata, subgraph metadata (name, image, description, website and source code url) gets uploaded to IPFS, and we provide the hex hash value for that JSON file + +With those 4 arguments, you should be able to: + +- Visit [our GraphProxy](https://etherscan.io/address/0xaDcA0dd4729c8BA3aCf3E99F3A9f471EF37b6825#writeProxyContract) contract on Etherscan +- Connect to Etherscan using WalletConnect via the WalletConnect Safe app of your multisig +- Call the `publishNewSubgraph` method with the paramaters that were generated by our tool + +#### Publish a New Version + +To publish a new version of an existing subgraph we first need to generate input arguments for it. Access [this page](https://thegraph.com/studio/multisig) in Subgraph Studio and provide: + +- Ethereum address of your multisig wallet +- Subgraph that you want to publish +- Version that you want to publish +- The ID of the subgraph you want to update in Graph Explorer + +After clicking on "Get Arguments" we'll generate all the contract arguments for you! + +On the right side of the UI under the `Publish New Version` title, there should be 4 arguments: + +- `graphAccount`: which is your Multisig account address +- `subgraphNumber`: is the number of your already published subgraph. It is a part of the subgraph id for a published subgraph queried through The Graph Network subgraph. +- `subgraphDeploymentID`: which is the hex hash of the deployment ID for that subgraph +- `versionMetadata`: version metadata (label and description) gets uploaded to IPFS, and we provide the hex hash value for that JSON file + +Now that we generated all the arguments you are ready to proceed and call the `publishNewVersion` method. In order to do so, you should: + +- Visit [the GraphProxy](https://etherscan.io/address/0xaDcA0dd4729c8BA3aCf3E99F3A9f471EF37b6825#writeProxyContract) contract on Etherscan +- Connect to Etherscan using WalletConnect via the WalletConnect Safe app of your Multisig +- Call the `publishNewVersion` method with the paramaters that were generated by our tool + +Once the transaction is successful, your subgraph should have a new version of your subgraph in Graph Explorer which means that curators can start signaling on it and indexers can start indexing it. diff --git a/pages/ja/studio/studio-faq.mdx b/pages/ja/studio/studio-faq.mdx new file mode 100644 index 000000000000..4db4d7ccddaa --- /dev/null +++ b/pages/ja/studio/studio-faq.mdx @@ -0,0 +1,21 @@ +--- +title: Subgraph Studio FAQs +--- + +### 1. How do I create an API Key? + +In the Subgraph Studio, you can create API Keys as needed and add security settings to each of them. + +### 2. Can I create multiple API Keys? + +A: Yes! You can create multiple API Keys to use in different projects. Check out the link [here](https://thegraph.com/studio/apikeys/). + +### 3. How do I restrict a domain for an API Key? + +After creating an API Key, in the Security section you can define the domains that can query a specific API Key. + +### 4. How do I find query URLs for subgraphs if I’m not the developer of the subgraph I want to use? + +You can find the query URL of each subgraph in the Subgraph Details section of The Graph Explorer. When you click on the “Query” button, you will be directed to a pane wherein you can view the query URL of the subgraph you’re interested in. You can then replace the `` placeholder with the API key you wish to leverage in the Subgraph Studio. + +Remember that you can create an API key and query any subgraph published to the network, even if you build a subgraph yourself. These queries via the new API key, are paid queries as any other on the network. diff --git a/pages/ja/studio/subgraph-studio.mdx b/pages/ja/studio/subgraph-studio.mdx new file mode 100644 index 000000000000..1f5ecf6a7011 --- /dev/null +++ b/pages/ja/studio/subgraph-studio.mdx @@ -0,0 +1,122 @@ +--- +title: How to Use the Subgraph Studio +--- + +Welcome to your new launchpad 👩🏽‍🚀 + +The Subgraph Studio is your place to build and create subgraphs, add metadata, and publish them to the new decentralized Explorer (more on that [here](/explorer)). + +What you can do in the Subgraph Studio: + +- Create a subgraph through the Studio UI +- Deploy a subgraph using the CLI +- Publish a subgraph with the Studio UI +- Test it in the playground +- Integrate it in staging using the query URL +- Create and manage your API keys for specific subgraphs + +Here in the Subgraph Studio, you have full control over your subgraphs. Not only can you test your subgraphs before you publish them, but you can also restrict your API keys to specific domains and only allow certain indexers to query from their API keys. + +Querying subgraphs generates query fees, used to reward [indexers](/indexing) on the Graph network. If you’re a dapp developer or subgraph developer, the Studio will empower you to build better subgraphs to power your or your community’s queries. The Studio is comprised of 5 main parts: + +- Your user account controls +- A list of subgraphs that you’ve created +- A section to manage, view details, and visualize the status of a specific subgraph +- A section to manage your API keys that you will need to query a subgraph +- A section to manage your billing + +## How to Create Your Account + +1. Sign in with your wallet - you can do this via MetaMask or WalletConnect +1. Once you sign in, you will see your unique deploy key in your account home page. This will allow you to either publish your subgraphs or manage your API keys + billing. You will have a unique deploy key that can be re-generated if you think it has been compromised. + +## How to Create your Subgraph in Subgraph Studio + +The best part! When you first create a subgraph, you’ll be directed to fill out: + +- Your Subgraph Name +- Image +- Description +- Categories +- Website + +## Subgraph Compatibility with The Graph Network + +The Graph Network is not yet able to support all of the data-sources & features available on the Hosted Service. In order to be supported by indexers on the network, subgraphs must: + +- Index mainnet Ethereum +- Must not use any of the following features: + - ipfs.cat & ipfs.map + - Non-fatal errors + - Grafting + +More features & networks will be added to The Graph Network incrementally. + +### Subgraph lifecycle flow + +![Subgraph Lifecycle](/img/subgraph-lifecycle.png) + +After you have created your subgraph, you will be able to deploy it using the [CLI](https://github.com/graphprotocol/graph-cli), or command line interface. Deploying a subgraph with the CLI will push the subgraph to the Studio where you’ll be able to test subgraphs using the playground. This will eventually allow you to publish to the Graph Network. For more information on CLI setup, [check this out](/developer/define-subgraph-hosted#install-the-graph-cli) (pst, make sure you have your deploy key on hand). Remember, deploying is **not the same as** publishing. When you deploy a subgraph, you just push it to the Studio where you’re able to test it. Versus, when you publish a subgraph, you are publishing it on-chain. + +## Testing your Subgraph in Subgraph Studio + +If you’d like to test your subgraph before publishing it to the network, you can do this in the Subgraph **Playground** or look at your logs. The Subgraph logs will tell you **where** your subgraph fails in the case that it does. + +## Publish your Subgraph in Subgraph Studio + +You’ve made it this far - congrats! Publishing your subgraph means that an IPFS hash was generated when you deployed the subgraph within the CLI and is stored in the network’s Ethereum smart contracts. In order to publish your subgraph successfully, you’ll need to go through the following steps outlined in this [blog](https://thegraph.com/blog/building-with-subgraph-studio). Check out the video overview below as well: + +
+ +
+ +Remember, while you’re going through your publishing flow, you’ll be able to push to either mainnet or Rinkeby, the testnet we support. If you’re a first time subgraph developer, we highly suggest you start with publishing to Rinkeby, which is free to do. This will allow you to see how the subgraph will work in The Graph Explorer and will allow you to test curation elements. + +You’ll only be able to index data from mainnet (even if your subgraph was published to a testnet) because only subgraphs that are indexing mainnet data can be published to the network. This is because indexers need to submit mandatory Proof of Indexing records as of a specific block hash. Because publishing a subgraph is an action taken on-chain, remember that the transaction can take up to a few minutes to go through. Any address you use to publish the contract will be the only one able to publish future versions. Choose wisely! + +Subgraphs with curation signal are shown to Indexers so that they can be indexed on the decentralized network. You can publish subgraphs and signal in one transaction, which allows you to mint the first curation signal on the subgraph and saves on gas costs. By adding your signal to the signal later provided by Curators, your subgraph will also have a higher chance of ultimately serving queries. + +**Now that you’ve published your subgraph, let’s get into how you’ll manage them on a regular basis.** Note that you cannot publish your subgraph to the network if it has failed syncing. This is usually because the subgraph has bugs - the logs will tell you where those issues exist! + +## Versioning your Subgraph with the CLI + +Developers might want to update their subgraph, for a variety of reasons. When this is the case, you can deploy a new version of your subgraph to the Studio using the CLI (it will only be private at this point) and if you are happy with it, you can publish this new deployment to The Graph Explorer. This will create a new version of your subgraph that curators can start signaling on and indexers will be able to index this new version. + +Up until recently, developers were forced to deploy and publish a new version of their subgraph to the Explorer to update the metadata of their subgraphs. Now, developers can update the metadata of their subgraphs **without having to publish a new version**. Developers can update their subgraph details in the Studio (under profile picture, name, description, etc) by checking an option called **Update Details** in The Graph Explorer. If this is checked, an on-chain transaction will be generated that updates subgraph details in the Explorer without having to publish a new version with a new deployment. + +Please note that there are costs associated with publishing a new version of a subgraph to the network. In addition to the transaction fees, developers must also fund a part of the curation tax on auto-migrating signal. You cannot publish a new version of your subgraph if curators have not signaled on it. For more information on the risks of curation, please read more [here](/curating). + +### Automatic Archiving of Subgraph Versions + +Whenever you deploy a new subgraph version in the Subgraph Studio, the previous version will be archived. Archived versions won't be indexed/synced and therefore cannot be queried. You can unarchive an archived version of your subgraph in the Studio UI. Please note that previous versions of non-published subgraphs deployed to the Studio will be automatically archived. + +![Subgraph Studio - Unarchive](/img/Unarchive.png) + +## Managing your API Keys + +Regardless of whether you’re a dapp developer or a subgraph developer, you’ll need to manage your API keys. This is important for you to be able to query subgraphs because API keys make sure the connections between application services are valid and authorized. This includes authenticating the end user and the device using the application. + +The Studio will list out existing API keys, which will give you the ability to manage or delete them. + +1. The **Overview** section will allow you to: + - Edit your key name + - Regenerate API keys + - View the current usage of the API key with stats: + - Number of queries + - Amount of GRT spent +2. Under **Manage Security Settings**, you’ll be able to opt into security settings depending on the level of control you’d like to have over your API keys. In this section, you can: + - View and manage the domain names authorized to use your API key + - Assign subgraphs that can be queried with your API key + +## How to Manage your Subgraph + +API keys aside, you’ll have many tools at your disposal to manage your subgraphs. You can organize your subgraphs by their **status** and **category**. + +- The **Status** tag allows you to pick between a variety of tags including ``, ``, ``, ``, etc. +- Meanwhile, **Category** allows you to designate what category your subgraph falls into. Options include ``, ``, ``, etc. diff --git a/pages/ja/supported-networks/near.mdx b/pages/ja/supported-networks/near.mdx new file mode 100644 index 000000000000..0965bdee1675 --- /dev/null +++ b/pages/ja/supported-networks/near.mdx @@ -0,0 +1,265 @@ +--- +title: Building Subgraphs on NEAR +--- + +> NEAR support in Graph Node and on the Hosted Service is in beta: please contact near@thegraph.com with any questions about building NEAR subgraphs! + +This guide is an introduction to building subgraphs indexing smart contracts on the [NEAR blockchain](https://docs.near.org/). + +## What is NEAR? + +[NEAR](https://near.org/) is a smart contract platform for building decentralised applications. Visit the [official documentation](https://docs.near.org/docs/concepts/new-to-near) for more information. + +## What are NEAR subgraphs? + +The Graph gives developers tools to process blockchain events and make the resulting data easily available via a GraphQL API, known individually as a subgraph. [Graph Node](https://github.com/graphprotocol/graph-node) is now able to process NEAR events, which means that NEAR developers can now build subgraphs to index their smart contracts. + +Subgraphs are event-based, which means that they listen for and then process on-chain events. There are currently two types of handlers supported for NEAR subgraphs: + +- Block handlers: these are run on every new block +- Receipt handlers: run every time a message is executed at a specified account + +[From the NEAR documentation](https://docs.near.org/docs/concepts/transaction#receipt): + +> A Receipt is the only actionable object in the system. When we talk about "processing a transaction" on the NEAR platform, this eventually means "applying receipts" at some point. + +## Building a NEAR Subgraph + +`@graphprotocol/graph-cli` is a command line tool for building and deploying subgraphs. + +`@graphprotocol/graph-ts` is a library of subgraph-specific types. + +NEAR subgraph development requires `graph-cli` above version `0.23.0`, and `graph-ts` above version `0.23.0`. + +> Building a NEAR subgraph is very similar to building a subgraph which indexes Ethereum. + +There are three aspects of subgraph definition: + +**subgraph.yaml:** the subgraph manifest, defining the data sources of interest, and how they should be processed. NEAR is a new `kind` of data source. + +**schema.graphql:** a schema file that defines what data is stored for your subgraph, and how to query it via GraphQL. The requirements for NEAR subgraphs are covered by [the existing documentation](/developer/create-subgraph-hosted#the-graphql-schema). + +**AssemblyScript Mappings:** [AssemblyScript code](/developer/assemblyscript-api) 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. + +During subgraph development there are two key commands: + +```bash +$ graph codegen # generates types from the schema file identified in the manifest +$ graph build # generates Web Assembly from the AssemblyScript files, and prepares all the subgraph files in a /build folder +``` + +### Subgraph Manifest Definition + +The subgraph manifest (`subgraph.yaml`) identifies the data sources for the subgraph, the triggers of interest, and the functions that should be run in response to those triggers. See below for an example subgraph manifest for a NEAR subgraph:: + +```yaml +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 subgraphs introduce a new `kind` of data source (`near`) +- The `network` should correspond to a network on the hosting Graph Node. On the Hosted Service, 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](https://docs.near.org/docs/concepts/account). This can be an account, or a sub account. + +NEAR data sources support two types of handlers: + +- `blockHandlers`: run on every new NEAR block. No `source.account` is required. +- `receiptHandlers`: run on every receipt where the data source's `source.account` is the recipient. Note that only exact matches are processed ([subaccounts](https://docs.near.org/docs/concepts/account#subaccounts) must be added as independent data sources). + +### Schema Definition + +Schema definition describes the structure of the resulting subgraph database, and the relationships between entities. This is agnostic of the original data source. There are more details on subgraph schema definition [here](/developer/create-subgraph-hosted#the-graphql-schema). + +### AssemblyScript Mappings + +The handlers for processing events are written in [AssemblyScript](https://www.assemblyscript.org/). + +NEAR indexing introduces NEAR-specific data types to the [AssemblyScript API](/developer/assemblyscript-api). + +```typescript + +class ExecutionOutcome { + gasBurnt: u64, + blockHash: Bytes, + id: Bytes, + logs: Array, + receiptIds: Array, + tokensBurnt: BigInt, + executorId: string, + } + +class ActionReceipt { + predecessorId: string, + receiverId: string, + id: CryptoHash, + signerId: string, + gasPrice: BigInt, + outputDataReceivers: Array, + inputDataIds: Array, + actions: Array, + } + +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, + } + +class ReceiptWithOutcome { + outcome: ExecutionOutcome, + receipt: ActionReceipt, + block: Block, + } +``` + +These types are passed to block & receipt handlers: + +- Block handlers will receive a `Block` +- Receipt handlers will receive a `ReceiptWithOutcome` + +Otherwise the rest of the [AssemblyScript API](/developer/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](/developer/assemblyscript-api#json-api) to allow developers to easily process these logs. + +## Deploying a NEAR Subgraph + +Once you have a built subgraph, it is time to deploy it to Graph Node for indexing. NEAR subgraphs can be deployed to any Graph Node `>=v0.26.x` (this version has not yet been tagged & released). + +The Graph's Hosted Service 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 the Hosted Service can be found [here](/hosted-service/deploy-subgraph-hosted). + +As a quick primer - the first step is to "create" your subgraph - this only needs to be done once. On the Hosted Service, this can be done from [your Dashboard](https://thegraph.com/hosted-service/dashboard): "Add Subgraph". + +Once your subgraph has been created, you can deploy your subgraph by using the `graph deploy` CLI command: + +``` +$ graph create --node subgraph/name # creates a subgraph on a local Graph Node (on the Hosted Service, this is done via the UI) +$ graph deploy --node --ipfs https://api.thegraph.com/ipfs/ # 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 +``` + +The node configuration will depend where the subgraph is being deployed. + +#### Hosted Service: + +``` +graph deploy --node https://api.thegraph.com/deploy/ --ipfs https://api.thegraph.com/ipfs/ --access-token +``` + +#### Local Graph Node (based on default configuration): + +``` +graph deploy --node http://localhost:8020/ --ipfs http://localhost:5001 +``` + +Once your subgraph has been deployed, it will be indexed by Graph Node. You can check its progress by querying the subgraph itself: + +``` +{ + _meta { + block { number } + } +} +``` + +### Indexing NEAR with a Local Graph Node + +Running a Graph Node that indexes NEAR has the following operational requirements: + +- NEAR Indexer Framework with Firehose instrumentation +- NEAR Firehose Component(s) +- Graph Node with Firehose endpoint configured + +We will provide more information on running the above components soon. + +## Querying a NEAR Subgraph + +The GraphQL endpoint for NEAR subgraphs is determined by the schema definition, with the existing API interface. Please visit the [GraphQL API documentation](/developer/graphql-api) for more information. + +## Example Subgraphs + +Here are some example subgraphs for reference: + +[NEAR Blocks](https://github.com/graphprotocol/example-subgraph/tree/near-blocks-example) + +[NEAR Receipts](https://github.com/graphprotocol/example-subgraph/tree/near-receipts-example) + +## よくある質問 + +### How does the beta work? + +NEAR support is in beta, which means that there may be changes to the API as we continue to work on improving the integration. Please email near@thegraph.com so that we can support you in building NEAR subgraphs, and keep you up to date on the latest developments! + +### Can a subgraph index both NEAR and EVM chains? + +No, a subgraph can only support data sources from one chain / network. + +### Can subgraphs react to more specific triggers? + +Currently, only Block and Receipt triggers are supported. We are investigating triggers for function calls to a specified account. We are also interested in supporting event triggers, once NEAR has native event support. + +### Will receipt handlers trigger for accounts and their sub accounts? + +Receipt handlers will only be triggered for the exact-match of the named account. More flexibility may be added in future. + +### Can NEAR subgraphs make view calls to NEAR accounts during mappings? + +This is not supported. We are evaluating whether this functionality is required for indexing. + +### Can I use data source templates in my NEAR subgraph? + +This is not currently supported. We are evaluating whether this functionality is required for indexing. + +### Ethereum subgraphs support "pending" and "current" versions, how can I deploy a "pending" version of a NEAR subgraph? + +Pending functionality is not yet supported for NEAR subgraphs. In the interim, you can deploy a new version to a different "named" subgraph, and then when that is synced with the chain head, you can redeploy to your primary "named" subgraph, which will use the same underlying deployment ID, so the main subgraph will be instantly synced. + +### My question hasn't been answered, where can I get more help building NEAR subgraphs? + +If it is a general question about subgraph development, there is a lot more information in the rest of the [Developer documentation](/developer/quick-start). Otherwise please join [The Graph Protocol Discord](https://discord.gg/vtvv7FP) and ask in the #near channel, or email near@thegraph.com. + +## References + +- [NEAR developer documentation](https://docs.near.org/docs/develop/basics/getting-started) diff --git a/pages/ko/about/introduction.mdx b/pages/ko/about/introduction.mdx new file mode 100644 index 000000000000..5f840c040400 --- /dev/null +++ b/pages/ko/about/introduction.mdx @@ -0,0 +1,47 @@ +--- +title: Introduction +--- + +This page will explain what The Graph is and how you can get started. + +## What The Graph Is + +The Graph is a decentralized protocol for indexing and querying data from blockchains, starting with Ethereum. It makes it possible to query data that is difficult to query directly. + +Projects with complex smart contracts like [Uniswap](https://uniswap.org/) and NFTs initiatives like [Bored Ape Yacht Club](https://boredapeyachtclub.com/) store data on the Ethereum blockchain, making it really difficult to read anything other than basic data directly from the blockchain. + +In the case of Bored Ape Yacht Club, we can perform basic read operations on [the contract](https://etherscan.io/address/0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d#code) like getting the owner of a certain Ape, getting the content URI of an Ape based on their ID, or the total supply, as these read operations are programmed directly into the smart contract, but more advanced real-world queries and operations like aggregation, search, relationships, and non-trivial filtering are not possible. For example, if we wanted to query for apes that are owned by a certain address, and filter by one of its characteristics, we would not be able to get that information by interacting directly with the contract itself. + +To get this data, you would have to process every single [`transfer`](https://etherscan.io/address/0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d#code#L1746) event ever emitted, read the metadata from IPFS using the Token ID and IPFS hash, and then aggregate it. Even for these types of relatively simple questions, it would take **hours or even days** for a decentralized application (dapp) running in a browser to get an answer. + +You could also build out your own server, process the transactions there, save them to a database, and build an API endpoint on top of it all in order to query the data. However, this option is resource intensive, needs maintenance, presents a single point of failure, and breaks important security properties required for decentralization. + +**Indexing blockchain data is really, really hard.** + +Blockchain properties like finality, chain reorganizations, or uncled blocks complicate this process further, and make it not just time consuming but conceptually hard to retrieve correct query results from blockchain data. + +The Graph solves this with a decentralized protocol that indexes and enables the performant and efficient querying of blockchain data. These APIs (indexed "subgraphs") can then be queried with a standard GraphQL API. Today, there is a hosted service as well as a decentralized protocol with the same capabilities. Both are backed by the open source implementation of [Graph Node](https://github.com/graphprotocol/graph-node). + +## How The Graph Works + +The Graph learns what and how to index Ethereum data based on subgraph descriptions, known as the subgraph manifest. The subgraph description defines the smart contracts of interest for a subgraph, the events in those contracts to pay attention to, and how to map event data to data that The Graph will store in its database. + +Once you have written a `subgraph manifest`, you use the Graph CLI to store the definition in IPFS and tell the indexer to start indexing data for that subgraph. + +This diagram gives more detail about the flow of data once a subgraph manifest has been deployed, dealing with Ethereum transactions: + +![](/img/graph-dataflow.png) + +The flow follows these steps: + +1. A decentralized application adds data to Ethereum through a transaction on a smart contract. +2. The smart contract emits one or more events while processing the transaction. +3. Graph Node continually scans Ethereum for new blocks and the data for your subgraph they may contain. +4. Graph Node finds Ethereum events for your subgraph in these blocks and runs the mapping handlers you provided. The mapping is a WASM module that creates or updates the data entities that Graph Node stores in response to Ethereum events. +5. The decentralized application queries the Graph Node for data indexed from the blockchain, using the node's [GraphQL endpoint](https://graphql.org/learn/). The Graph Node in turn translates the GraphQL queries into queries for its underlying data store in order to fetch this data, making use of the store's indexing capabilities. The decentralized application displays this data in a rich UI for end-users, which they use to issue new transactions on Ethereum. The cycle repeats. + +## Next Steps + +In the following sections we will go into more detail on how to define subgraphs, how to deploy them, and how to query data from the indexes that Graph Node builds. + +Before you start writing your own subgraph, you might want to have a look at the Graph Explorer and explore some of the subgraphs that have already been deployed. The page for each subgraph contains a playground that lets you query that subgraph's data with GraphQL. diff --git a/pages/ko/about/network.mdx b/pages/ko/about/network.mdx new file mode 100644 index 000000000000..b19f08d12bc7 --- /dev/null +++ b/pages/ko/about/network.mdx @@ -0,0 +1,15 @@ +--- +title: Network Overview +--- + +The Graph Network is a decentralized indexing protocol for organizing blockchain data. Applications use GraphQL to query open APIs called subgraphs, to retrieve data that is indexed on the network. With The Graph, developers can build serverless applications that run entirely on public infrastructure. + +> GRT Token Address: [0xc944e90c64b2c07662a292be6244bdf05cda44a7](https://etherscan.io/token/0xc944e90c64b2c07662a292be6244bdf05cda44a7) + +## Overview + +The Graph Network consists of Indexers, Curators and Delegators that provide services to the network, and serve data to Web3 applications. Consumers use the applications and consume the data. + +![Token Economics](/img/Network-roles@2x.png) + +To ensure economic security of The Graph Network and the integrity of data being queried, participants stake and use Graph Tokens (GRT). GRT is a work token that is an ERC-20 on the Ethereum blockchain, used to allocate resources in the network. Active Indexers, Curators and Delegators can provide services and earn income from the network, proportional to the amount of work they perform and their GRT stake. diff --git a/pages/ko/curating.mdx b/pages/ko/curating.mdx index dcb329288947..456deec666f7 100644 --- a/pages/ko/curating.mdx +++ b/pages/ko/curating.mdx @@ -100,5 +100,5 @@ title: 큐레이팅 title="YouTubeビデオプレーヤー" frameBorder="0" allowFullScreen - > +> diff --git a/pages/ko/delegating.mdx b/pages/ko/delegating.mdx index 22b1e8c5bfd4..20cd2496fa04 100644 --- a/pages/ko/delegating.mdx +++ b/pages/ko/delegating.mdx @@ -28,7 +28,9 @@ This guide will explain how to be an effective delegator in the Graph Network. D 또한 고려해야 할 한 가지는 위임을 위한 인덱서를 현명하게 선택하는 것입니다. 만약 여러분들이 신뢰할 수 없거나 작업을 제대로 수행하지 않는 인덱서를 선택하면 여러분들은 해당 위임의 취소를 원할 것입니다. 이 경우, 보상을 받는 기회를 잃음과 더불어, 단지 여러분의 GRT를 소각하기만 한 결과를 초래할 것입니다. -
위임 UI에는 0.5%의 수수료 및 28일의 위임 해지 기간이 명시되어있습니다.
+
+ 위임 UI에는 0.5%의 수수료 및 28일의 위임 해지 기간이 명시되어있습니다. +
### 위임자들에 대한 공정한 보상 지급 규칙을 지닌 신뢰할 수 있는 인덱서 선택 @@ -87,5 +89,5 @@ A delegator can therefore do the math to determine that the Indexer offering 20% title="YouTubeビデオプレーヤー" frameBorder="0" allowFullScreen - > +> diff --git a/pages/ko/developer/assemblyscript-api.mdx b/pages/ko/developer/assemblyscript-api.mdx new file mode 100644 index 000000000000..a609e6cd657f --- /dev/null +++ b/pages/ko/developer/assemblyscript-api.mdx @@ -0,0 +1,714 @@ +--- +title: AssemblyScript API +--- + +> Note: if you created a subgraph prior to `graph-cli`/`graph-ts` version `0.22.0`, you're using an older version of AssemblyScript, we recommend taking a look at the [`Migration Guide`](/developer/assemblyscript-migration-guide) + +This page documents what built-in APIs can be used when writing subgraph mappings. Two kinds of APIs are available out of the box: + +- the [Graph TypeScript library](https://github.com/graphprotocol/graph-ts) (`graph-ts`) and +- code generated from subgraph files by `graph codegen`. + +It is also possible to add other libraries as dependencies, as long as they are compatible with [AssemblyScript](https://github.com/AssemblyScript/assemblyscript). Since this is the language mappings are written in, the [AssemblyScript wiki](https://github.com/AssemblyScript/assemblyscript/wiki) is a good source for language and standard library features. + +## Installation + +Subgraphs created with [`graph init`](/developer/create-subgraph-hosted) come with preconfigured dependencies. All that is required to install these dependencies is to run one of the following commands: + +```sh +yarn install # Yarn +npm install # NPM +``` + +If the subgraph was created from scratch, one of the following two commands will install the Graph TypeScript library as a dependency: + +```sh +yarn add --dev @graphprotocol/graph-ts # Yarn +npm install --save-dev @graphprotocol/graph-ts # NPM +``` + +## API Reference + +The `@graphprotocol/graph-ts` library provides the following APIs: + +- An `ethereum` API for working with Ethereum smart contracts, events, blocks, transactions, and Ethereum values. +- A `store` API to load and save entities from and to the Graph Node store. +- A `log` API to log messages to the Graph Node output and the Graph Explorer. +- An `ipfs` API to load files from IPFS. +- A `json` API to parse JSON data. +- A `crypto` API to use cryptographic functions. +- Low-level primitives to translate between different type systems such as Ethereum, JSON, GraphQL and AssemblyScript. + +### Versions + +The `apiVersion` in the subgraph manifest specifies the mapping API version which is run by Graph Node for a given subgraph. The current mapping API version is 0.0.6. + +| Version | Release notes | +|:-------:| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 0.0.6 | Added `nonce` field to the Ethereum Transaction object
Added `baseFeePerGas` to the Ethereum Block object | +| 0.0.5 | AssemblyScript upgraded to version 0.19.10 (this includes breaking changes, please see the [`Migration Guide`](/developer/assemblyscript-migration-guide))
`ethereum.transaction.gasUsed` renamed to `ethereum.transaction.gasLimit` | +| 0.0.4 | Added `functionSignature` field to the Ethereum SmartContractCall object | +| 0.0.3 | Added `from` field to the Ethereum Call object
`etherem.call.address` renamed to `ethereum.call.to` | +| 0.0.2 | Added `input` field to the Ethereum Transaction object | + +### Built-in Types + +Documentation on the base types built into AssemblyScript can be found in the [AssemblyScript wiki](https://github.com/AssemblyScript/assemblyscript/wiki/Types). + +The following additional types are provided by `@graphprotocol/graph-ts`. + +#### ByteArray + +```typescript +import { ByteArray } from '@graphprotocol/graph-ts' +``` + +`ByteArray` represents an array of `u8`. + +_Construction_ + +- `fromI32(x: i32): ByteArray` - Decomposes `x` into bytes. +- `fromHexString(hex: string): ByteArray` - Input length must be even. Prefixing with `0x` is optional. + +_Type conversions_ + +- `toHexString(): string` - Converts to a hex string prefixed with `0x`. +- `toString(): string` - Interprets the bytes as a UTF-8 string. +- `toBase58(): string` - Encodes the bytes into a base58 string. +- `toU32(): u32` - Interprets the bytes as a little-endian `u32`. Throws in case of overflow. +- `toI32(): i32` - Interprets the byte array as a little-endian `i32`. Throws in case of overflow. + +_Operators_ + +- `equals(y: ByteArray): bool` – can be written as `x == y`. + +#### BigDecimal + +```typescript +import { BigDecimal } from '@graphprotocol/graph-ts' +``` + +`BigDecimal` is used to represent arbitrary precision decimals. + +_Construction_ + +- `constructor(bigInt: BigInt)` – creates a `BigDecimal` from an `BigInt`. +- `static fromString(s: string): BigDecimal` – parses from a decimal string. + +_Type conversions_ + +- `toString(): string` – prints to a decimal string. + +_Math_ + +- `plus(y: BigDecimal): BigDecimal` – can be written as `x + y`. +- `minus(y: BigDecimal): BigDecimal` – can be written as `x - y`. +- `times(y: BigDecimal): BigDecimal` – can be written as `x * y`. +- `dividedBy(y: BigDecimal): BigDecimal` – can be written as `x / y`. +- `equals(y: BigDecimal): bool` – can be written as `x == y`. +- `notEqual(y: BigDecimal): bool` – can be written as `x != y`. +- `lt(y: BigDecimal): bool` – can be written as `x < y`. +- `le(y: BigDecimal): bool` – can be written as `x <= y`. +- `gt(y: BigDecimal): bool` – can be written as `x > y`. +- `ge(y: BigDecimal): bool` – can be written as `x >= y`. +- `neg(): BigDecimal` - can be written as `-x`. + +#### BigInt + +```typescript +import { BigInt } from '@graphprotocol/graph-ts' +``` + +`BigInt` is used to represent big integers. This includes Ethereum values of type `uint32` to `uint256` and `int64` to `int256`. Everything below `uint32`, such as `int32`, `uint24` or `int8` is represented as `i32`. + +The `BigInt` class has the following API: + +_Construction_ + +- `BigInt.fromI32(x: i32): BigInt` – creates a `BigInt` from an `i32`. +- `BigInt.fromString(s: string): BigInt`– Parses a `BigInt` from a string. +- `BigInt.fromUnsignedBytes(x: Bytes): BigInt` – Interprets `bytes` as an unsigned, little-endian integer. If your input is big-endian, call `.reverse()` first. +- `BigInt.fromSignedBytes(x: Bytes): BigInt` – Interprets `bytes` as a signed, little-endian integer. If your input is big-endian, call `.reverse()` first. + + _Type conversions_ + +- `x.toHex(): string` – turns `BigInt` into a string of hexadecimal characters. +- `x.toString(): string` – turns `BigInt` into a decimal number string. +- `x.toI32(): i32` – returns the `BigInt` as an `i32`; fails if it the value does not fit into `i32`. It's a good idea to first check `x.isI32()`. +- `x.toBigDecimal(): BigDecimal` - converts into a decimal with no fractional part. + +_Math_ + +- `x.plus(y: BigInt): BigInt` – can be written as `x + y`. +- `x.minus(y: BigInt): BigInt` – can be written as `x - y`. +- `x.times(y: BigInt): BigInt` – can be written as `x * y`. +- `x.dividedBy(y: BigInt): BigInt` – can be written as `x / y`. +- `x.mod(y: BigInt): BigInt` – can be written as `x % y`. +- `x.equals(y: BigInt): bool` – can be written as `x == y`. +- `x.notEqual(y: BigInt): bool` – can be written as `x != y`. +- `x.lt(y: BigInt): bool` – can be written as `x < y`. +- `x.le(y: BigInt): bool` – can be written as `x <= y`. +- `x.gt(y: BigInt): bool` – can be written as `x > y`. +- `x.ge(y: BigInt): bool` – can be written as `x >= y`. +- `x.neg(): BigInt` – can be written as `-x`. +- `x.divDecimal(y: BigDecimal): BigDecimal` – divides by a decimal, giving a decimal result. +- `x.isZero(): bool` – Convenience for checking if the number is zero. +- `x.isI32(): bool` – Check if the number fits in an `i32`. +- `x.abs(): BigInt` – Absolute value. +- `x.pow(exp: u8): BigInt` – Exponentiation. +- `bitOr(x: BigInt, y: BigInt): BigInt` – can be written as `x | y`. +- `bitAnd(x: BigInt, y: BigInt): BigInt` – can be written as `x & y`. +- `leftShift(x: BigInt, bits: u8): BigInt` – can be written as `x << y`. +- `rightShift(x: BigInt, bits: u8): BigInt` – can be written as `x >> y`. + +#### TypedMap + +```typescript +import { TypedMap } from '@graphprotocol/graph-ts' +``` + +`TypedMap` can be used to stored key-value pairs. See [this example](https://github.com/graphprotocol/aragon-subgraph/blob/29dd38680c5e5104d9fdc2f90e740298c67e4a31/individual-dao-subgraph/mappings/constants.ts#L51). + +The `TypedMap` class has the following API: + +- `new TypedMap()` – creates an empty map with keys of type `K` and values of type `T` +- `map.set(key: K, value: V): void` – sets the value of `key` to `value` +- `map.getEntry(key: K): TypedMapEntry | null` – returns the key-value pair for a `key` or `null` if the `key` does not exist in the map +- `map.get(key: K): V | null` – returns the value for a `key` or `null` if the `key` does not exist in the map +- `map.isSet(key: K): bool` – returns `true` if the `key` exists in the map and `false` if it does not + +#### Bytes + +```typescript +import { Bytes } from '@graphprotocol/graph-ts' +``` + +`Bytes` is used to represent arbitrary-length arrays of bytes. This includes Ethereum values of type `bytes`, `bytes32` etc. + +The `Bytes` class extends AssemblyScript's [Uint8Array](https://github.com/AssemblyScript/assemblyscript/blob/3b1852bc376ae799d9ebca888e6413afac7b572f/std/assembly/typedarray.ts#L64) and this supports all the `Uint8Array` functionality, plus the following new methods: + +- `b.toHex()` – returns a hexadecimal string representing the bytes in the array +- `b.toString()` – converts the bytes in the array to a string of unicode characters +- `b.toBase58()` – turns an Ethereum Bytes value to base58 encoding (used for IPFS hashes) + +#### Address + +```typescript +import { Address } from '@graphprotocol/graph-ts' +``` + +`Address` extends `Bytes` to represent Ethereum `address` values. + +It adds the following method on top of the `Bytes` API: + +- `Address.fromString(s: string): Address` – creates an `Address` from a hexadecimal string + +### Store API + +```typescript +import { store } from '@graphprotocol/graph-ts' +``` + +The `store` API allows to load, save and remove entities from and to the Graph Node store. + +Entities written to the store map one-to-one to the `@entity` types defined in the subgraph's GraphQL schema. To make working with these entities convenient, the `graph codegen` command provided by the [Graph CLI](https://github.com/graphprotocol/graph-cli) generates entity classes, which are subclasses of the built-in `Entity` type, with property getters and setters for the fields in the schema as well as methods to load and save these entities. + +#### Creating entities + +The following is a common pattern for creating entities from Ethereum events. + +```typescript +// Import the Transfer event class generated from the ERC20 ABI +import { Transfer as TransferEvent } from '../generated/ERC20/ERC20' + +// Import the Transfer entity type generated from the GraphQL schema +import { Transfer } from '../generated/schema' + +// Transfer event handler +export function handleTransfer(event: TransferEvent): void { + // Create a Transfer entity, using the hexadecimal string representation + // of the transaction hash as the entity ID + let id = event.transaction.hash.toHex() + let transfer = new Transfer(id) + + // Set properties on the entity, using the event parameters + transfer.from = event.params.from + transfer.to = event.params.to + transfer.amount = event.params.amount + + // Save the entity to the store + transfer.save() +} +``` + +When a `Transfer` event is encountered while processing the chain, it is passed to the `handleTransfer` event handler using the generated `Transfer` type (aliased to `TransferEvent` here to avoid a naming conflict with the entity type). This type allows accessing data such as the event's parent transaction and its parameters. + +Each entity must have a unique ID to avoid collisions with other entities. It is fairly common for event parameters to include a unique identifier that can be used. Note: Using the transaction hash as the ID assumes that no other events in the same transaction create entities with this hash as the ID. + +#### Loading entities from the store + +If an entity already exists, it can be loaded from the store with the following: + +```typescript +let id = event.transaction.hash.toHex() // or however the ID is constructed +let transfer = Transfer.load(id) +if (transfer == null) { + transfer = new Transfer(id) +} + +// Use the Transfer entity as before +``` + +As the entity may not exist in the store yet, the `load` method returns a value of type `Transfer | null`. It may thus be necessary to check for the `null` case before using the value. + +> **Note:** Loading entities is only necessary if the changes made in the mapping depend on the previous data of an entity. See the next section for the two ways of updating existing entities. + +#### Updating existing entities + +There are two ways to update an existing entity: + +1. Load the entity with e.g. `Transfer.load(id)`, set properties on the entity, then `.save()` it back to the store. +2. Simply create the entity with e.g. `new Transfer(id)`, set properties on the entity, then `.save()` it to the store. If the entity already exists, the changes are merged into it. + +Changing properties is straight forward in most cases, thanks to the generated property setters: + +```typescript +let transfer = new Transfer(id) +transfer.from = ... +transfer.to = ... +transfer.amount = ... +``` + +It is also possible to unset properties with one of the following two instructions: + +```typescript +transfer.from.unset() +transfer.from = null +``` + +This only works with optional properties, i.e. properties that are declared without a `!` in GraphQL. Two examples would be `owner: Bytes` or `amount: BigInt`. + +Updating array properties is a little more involved, as the getting an array from an entity creates a copy of that array. This means array properties have to be set again explicitly after changing the array. The following assumes `entity` has a `numbers: [BigInt!]!` field. + +```typescript +// This won't work +entity.numbers.push(BigInt.fromI32(1)) +entity.save() + +// This will work +let numbers = entity.numbers +numbers.push(BigInt.fromI32(1)) +entity.numbers = numbers +entity.save() +``` + +#### Removing entities from the store + +There is currently no way to remove an entity via the generated types. Instead, removing an entity requires passing the name of the entity type and the entity ID to `store.remove`: + +```typescript +import { store } from '@graphprotocol/graph-ts' +... +let id = event.transaction.hash.toHex() +store.remove('Transfer', id) +``` + +### Ethereum API + +The Ethereum API provides access to smart contracts, public state variables, contract functions, events, transactions, blocks and the encoding/decoding Ethereum data. + +#### Support for Ethereum Types + +As with entities, `graph codegen` generates classes for all smart contracts and events used in a subgraph. For this, the contract ABIs need to be part of the data source in the subgraph manifest. Typically, the ABI files are stored in an `abis/` folder. + +With the generated classes, conversions between Ethereum types and the [built-in types](#built-in-types) take place behind the scenes so that subgraph authors do not have to worry about them. + +The following example illustrates this. Given a subgraph schema like + +```graphql +type Transfer @entity { + from: Bytes! + to: Bytes! + amount: BigInt! +} +``` + +and a `Transfer(address,address,uint256)` event signature on Ethereum, the `from`, `to` and `amount` values of type `address`, `address` and `uint256` are converted to `Address` and `BigInt`, allowing them to be passed on to the `Bytes!` and `BigInt!` properties of the `Transfer` entity: + +```typescript +let id = event.transaction.hash.toHex() +let transfer = new Transfer(id) +transfer.from = event.params.from +transfer.to = event.params.to +transfer.amount = event.params.amount +transfer.save() +``` + +#### Events and Block/Transaction Data + +Ethereum events passed to event handlers, such as the `Transfer` event in the previous examples, not only provide access to the event parameters but also to their parent transaction and the block they are part of. The following data can be obtained from `event` instances (these classes are a part of the `ethereum` module in `graph-ts`): + +```typescript +class Event { + address: Address + logIndex: BigInt + transactionLogIndex: BigInt + logType: string | null + block: Block + transaction: Transaction + parameters: Array +} + +class Block { + hash: Bytes + parentHash: Bytes + unclesHash: Bytes + author: Address + stateRoot: Bytes + transactionsRoot: Bytes + receiptsRoot: Bytes + number: BigInt + gasUsed: BigInt + gasLimit: BigInt + timestamp: BigInt + difficulty: BigInt + totalDifficulty: BigInt + size: BigInt | null + baseFeePerGas: BigInt | null +} + +class Transaction { + hash: Bytes + index: BigInt + from: Address + to: Address | null + value: BigInt + gasLimit: BigInt + gasPrice: BigInt + input: Bytes + nonce: BigInt +} +``` + +#### Access to Smart Contract State + +The code generated by `graph codegen` also includes classes for the smart contracts used in the subgraph. These can be used to access public state variables and call functions of the contract at the current block. + +A common pattern is to access the contract from which an event originates. This is achieved with the following code: + +```typescript +// Import the generated contract class +import { ERC20Contract } from '../generated/ERC20Contract/ERC20Contract' +// Import the generated entity class +import { Transfer } from '../generated/schema' + +export function handleTransfer(event: Transfer) { + // Bind the contract to the address that emitted the event + let contract = ERC20Contract.bind(event.address) + + // Access state variables and functions by calling them + let erc20Symbol = contract.symbol() +} +``` + +As long as the `ERC20Contract` on Ethereum has a public read-only function called `symbol`, it can be called with `.symbol()`. For public state variables a method with the same name is created automatically. + +Any other contract that is part of the subgraph can be imported from the generated code and can be bound to a valid address. + +#### Handling Reverted Calls + +If the read-only methods of your contract may revert, then you should handle that by calling the generated contract method prefixed with `try_`. For example, the Gravity contract exposes the `gravatarToOwner` method. This code would be able to handle a revert in that method: + +```typescript +let gravity = Gravity.bind(event.address) +let callResult = gravity.try_gravatarToOwner(gravatar) +if (callResult.reverted) { + log.info('getGravatar reverted', []) +} else { + let owner = callResult.value +} +``` + +Note that a Graph node connected to a Geth or Infura client may not detect all reverts, if you rely on this we recommend using a Graph node connected to a Parity client. + +#### Encoding/Decoding ABI + +Data can be encoded and decoded according to Ethereum's ABI encoding format using the `encode` and `decode` functions in the `ethereum` module. + +```typescript +import { Address, BigInt, ethereum } from '@graphprotocol/graph-ts' + +let tupleArray: Array = [ + ethereum.Value.fromAddress(Address.fromString('0x0000000000000000000000000000000000000420')), + ethereum.Value.fromUnsignedBigInt(BigInt.fromI32(62)), +] + +let tuple = tupleArray as ethereum.Tuple + +let encoded = ethereum.encode(ethereum.Value.fromTuple(tuple))! + +let decoded = ethereum.decode('(address,uint256)', encoded) +``` + +For more information: + +- [ABI Spec](https://docs.soliditylang.org/en/v0.7.4/abi-spec.html#types) +- Encoding/decoding [Rust library/CLI](https://github.com/rust-ethereum/ethabi) +- More [complex example](https://github.com/graphprotocol/graph-node/blob/6a7806cc465949ebb9e5b8269eeb763857797efc/tests/integration-tests/host-exports/src/mapping.ts#L72). + +### Logging API + +```typescript +import { log } from '@graphprotocol/graph-ts' +``` + +The `log` API allows subgraphs to log information to the Graph Node standard output as well as the Graph Explorer. Messages can be logged using different log levels. A basic format string syntax is provided to compose log messages from argument. + +The `log` API includes the following functions: + +- `log.debug(fmt: string, args: Array): void` - logs a debug message. +- `log.info(fmt: string, args: Array): void` - logs an informational message. +- `log.warning(fmt: string, args: Array): void` - logs a warning. +- `log.error(fmt: string, args: Array): void` - logs an error message. +- `log.critical(fmt: string, args: Array): void` – logs a critical message _and_ terminates the subgraph. + +The `log` API takes a format string and an array of string values. It then replaces placeholders with the string values from the array. The first `{}` placeholder gets replaced by the first value in the array, the second `{}` placeholder gets replaced by the second value and so on. + +```typescript +log.info('Message to be displayed: {}, {}, {}', [value.toString(), anotherValue.toString(), 'already a string']) +``` + +#### Logging one or more values + +##### Logging a single value + +In the example below, the string value "A" is passed into an array to become`['A']` before being logged: + +```typescript +let myValue = 'A' + +export function handleSomeEvent(event: SomeEvent): void { + // Displays : "My value is: A" + log.info('My value is: {}', [myValue]) +} +``` + +##### Logging a single entry from an existing array + +In the example below, only the first value of the argument array is logged, despite the array containing three values. + +```typescript +let myArray = ['A', 'B', 'C'] + +export function handleSomeEvent(event: SomeEvent): void { + // Displays : "My value is: A" (Even though three values are passed to `log.info`) + log.info('My value is: {}', myArray) +} +``` + +#### Logging multiple entries from an existing array + +Each entry in the arguments array requires its own placeholder `{}` in the log message string. The below example contains three placeholders `{}` in the log message. Because of this, all three values in `myArray` are logged. + +```typescript +let myArray = ['A', 'B', 'C'] + +export function handleSomeEvent(event: SomeEvent): void { + // Displays : "My first value is: A, second value is: B, third value is: C" + log.info('My first value is: {}, second value is: {}, third value is: {}', myArray) +} +``` + +##### Logging a specific entry from an existing array + +To display a specific value in the array, the indexed value must be provided. + +```typescript +export function handleSomeEvent(event: SomeEvent): void { + // Displays : "My third value is C" + log.info('My third value is: {}', [myArray[2]]) +} +``` + +##### Logging event information + +The example below logs the block number, block hash and transaction hash from an event: + +```typescript +import { log } from '@graphprotocol/graph-ts' + +export function handleSomeEvent(event: SomeEvent): void { + log.debug('Block number: {}, block hash: {}, transaction hash: {}', [ + event.block.number.toString(), // "47596000" + event.block.hash.toHexString(), // "0x..." + event.transaction.hash.toHexString(), // "0x..." + ]) +} +``` + +### IPFS API + +```typescript +import { ipfs } from '@graphprotocol/graph-ts' +``` + +Smart contracts occasionally anchor IPFS files on chain. This allows mappings to obtain the IPFS hashes from the contract and read the corresponding files from IPFS. The file data will be returned as `Bytes`, which usually requires further processing, e.g. with the `json` API documented later on this page. + +Given an IPFS hash or path, reading a file from IPFS is done as follows: + +```typescript +// Put this inside an event handler in the mapping +let hash = 'QmTkzDwWqPbnAh5YiV5VwcTLnGdwSNsNTn2aDxdXBFca7D' +let data = ipfs.cat(hash) + +// Paths like `QmTkzDwWqPbnAh5YiV5VwcTLnGdwSNsNTn2aDxdXBFca7D/Makefile` +// that include files in directories are also supported +let path = 'QmTkzDwWqPbnAh5YiV5VwcTLnGdwSNsNTn2aDxdXBFca7D/Makefile' +let data = ipfs.cat(path) +``` + +**Note:** `ipfs.cat` is not deterministic at the moment. If the file cannot be retrieved over the IPFS network before the request times out, it will return `null`. Due to this, it's always worth checking the result for `null`. To ensure that files can be retrieved, they have to be pinned to the IPFS node that Graph Node connects to. On the [hosted service](https://thegraph.com/hosted-service), this is [https://api.thegraph.com/ipfs/](https://api.thegraph.com/ipfs). See the [IPFS pinning](/developer/create-subgraph-hosted#ipfs-pinning) section for more information. + +It is also possible to process larger files in a streaming fashion with `ipfs.map`. The function expects the hash or path for an IPFS file, the name of a callback, and flags to modify its behavior: + +```typescript +import { JSONValue, Value } from '@graphprotocol/graph-ts' + +export function processItem(value: JSONValue, userData: Value): void { + // See the JSONValue documentation for details on dealing + // with JSON values + let obj = value.toObject() + let id = obj.get('id') + let title = obj.get('title') + + if (!id || !title) { + return + } + + // Callbacks can also created entities + let newItem = new Item(id.toString()) + newItem.title = title.toString() + newitem.parent = userData.toString() // Set parent to "parentId" + newitem.save() +} + +// Put this inside an event handler in the mapping +ipfs.map('Qm...', 'processItem', Value.fromString('parentId'), ['json']) + +// Alternatively, use `ipfs.mapJSON` +ipfs.mapJSON('Qm...', 'processItem', Value.fromString('parentId')) +``` + +The only flag currently supported is `json`, which must be passed to `ipfs.map`. With the `json` flag, the IPFS file must consist of a series of JSON values, one value per line. The call to `ipfs.map` will read each line in the file, deserialize it into a `JSONValue` and call the callback for each of them. The callback can then use entity operations to store data from the `JSONValue`. Entity changes are stored only when the handler that called `ipfs.map` finishes successfully; in the meantime, they are kept in memory, and the size of the file that `ipfs.map` can process is therefore limited. + +On success, `ipfs.map` returns `void`. If any invocation of the callback causes an error, the handler that invoked `ipfs.map` is aborted, and the subgraph is marked as failed. + +### Crypto API + +```typescript +import { crypto } from '@graphprotocol/graph-ts' +``` + +The `crypto` API makes a cryptographic functions available for use in mappings. Right now, there is only one: + +- `crypto.keccak256(input: ByteArray): ByteArray` + +### JSON API + +```typescript +import { json, JSONValueKind } from '@graphprotocol/graph-ts' +``` + +JSON data can be parsed using the `json` API: + +- `json.fromBytes(data: Bytes): JSONValue` – parses JSON data from a `Bytes` array +- `json.try_fromBytes(data: Bytes): Result` – safe version of `json.fromBytes`, it returns an error variant if the parsing failed +- `json.fromString(data: Bytes): JSONValue` – parses JSON data from a valid UTF-8 `String` +- `json.try_fromString(data: Bytes): Result` – safe version of `json.fromString`, it returns an error variant if the parsing failed + +The `JSONValue` class provides a way to pull values out of an arbitrary JSON document. Since JSON values can be booleans, numbers, arrays and more, `JSONValue` comes with a `kind` property to check the type of a value: + +```typescript +let value = json.fromBytes(...) +if (value.kind == JSONValueKind.BOOL) { + ... +} +``` + +In addition, there is a method to check if the value is `null`: + +- `value.isNull(): boolean` + +When the type of a value is certain, it can be converted to a [built-in type](#built-in-types) using one of the following methods: + +- `value.toBool(): boolean` +- `value.toI64(): i64` +- `value.toF64(): f64` +- `value.toBigInt(): BigInt` +- `value.toString(): string` +- `value.toArray(): Array` - (and then convert `JSONValue` with one of the 5 methods above) + +### Type Conversions Reference + +| Source(s) | Destination | Conversion function | +| -------------------- | -------------------- | ---------------------------- | +| Address | Bytes | none | +| Address | ID | s.toHexString() | +| Address | String | s.toHexString() | +| BigDecimal | String | s.toString() | +| BigInt | BigDecimal | s.toBigDecimal() | +| BigInt | String (hexadecimal) | s.toHexString() or s.toHex() | +| BigInt | String (unicode) | s.toString() | +| BigInt | i32 | s.toI32() | +| Boolean | Boolean | none | +| Bytes (signed) | BigInt | BigInt.fromSignedBytes(s) | +| Bytes (unsigned) | BigInt | BigInt.fromUnsignedBytes(s) | +| Bytes | String (hexadecimal) | s.toHexString() or s.toHex() | +| Bytes | String (unicode) | s.toString() | +| Bytes | String (base58) | s.toBase58() | +| Bytes | i32 | s.toI32() | +| Bytes | u32 | s.toU32() | +| Bytes | JSON | json.fromBytes(s) | +| int8 | i32 | none | +| int32 | i32 | none | +| int32 | BigInt | Bigint.fromI32(s) | +| uint24 | i32 | none | +| int64 - int256 | BigInt | none | +| uint32 - uint256 | BigInt | none | +| JSON | boolean | s.toBool() | +| JSON | i64 | s.toI64() | +| JSON | u64 | s.toU64() | +| JSON | f64 | s.toF64() | +| JSON | BigInt | s.toBigInt() | +| JSON | string | s.toString() | +| JSON | Array | s.toArray() | +| JSON | Object | s.toObject() | +| String | Address | Address.fromString(s) | +| String | BigDecimal | BigDecimal.fromString(s) | +| String (hexadecimal) | Bytes | ByteArray.fromHexString(s) | +| String (UTF-8) | Bytes | ByteArray.fromUTF8(s) | + +### Data Source Metadata + +You can inspect the contract address, network and context of the data source that invoked the handler through the `dataSource` namespace: + +- `dataSource.address(): Address` +- `dataSource.network(): string` +- `dataSource.context(): DataSourceContext` + +### Entity and DataSourceContext + +The base `Entity` class and the child `DataSourceContext` class have helpers to dynamically set and get fields: + +- `setString(key: string, value: string): void` +- `setI32(key: string, value: i32): void` +- `setBigInt(key: string, value: BigInt): void` +- `setBytes(key: string, value: Bytes): void` +- `setBoolean(key: string, value: bool): void` +- `setBigDecimal(key, value: BigDecimal): void` +- `getString(key: string): string` +- `getI32(key: string): i32` +- `getBigInt(key: string): BigInt` +- `getBytes(key: string): Bytes` +- `getBoolean(key: string): boolean` +- `getBigDecimal(key: string): BigDecimal` diff --git a/pages/ko/developer/assemblyscript-migration-guide.mdx b/pages/ko/developer/assemblyscript-migration-guide.mdx new file mode 100644 index 000000000000..2db90a608110 --- /dev/null +++ b/pages/ko/developer/assemblyscript-migration-guide.mdx @@ -0,0 +1,484 @@ +--- +title: AssemblyScript Migration Guide +--- + +Up until now, subgraphs have been using one of the [first versions of AssemblyScript](https://github.com/AssemblyScript/assemblyscript/tree/v0.6) (v0.6). Finally we've added support for the [newest one available](https://github.com/AssemblyScript/assemblyscript/tree/v0.19.10) (v0.19.10)! 🎉 + +That will enable subgraph developers to use newer features of the AS language and standard library. + +This guide is applicable for anyone using `graph-cli`/`graph-ts` below version `0.22.0`. If you're already at a higher than (or equal) version to that, you've already been using version `0.19.10` of AssemblyScript 🙂 + +> Note: As of `0.24.0`, `graph-node` can support both versions, depending on the `apiVersion` specified in the subgraph manifest. + +## Features + +### New functionality + +- `TypedArray`s can now be built from `ArrayBuffer`s by using the [new `wrap` static method](https://www.assemblyscript.org/stdlib/typedarray.html#static-members) ([v0.8.1](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.8.1)) +- New standard library functions: `String#toUpperCase`, `String#toLowerCase`, `String#localeCompare`and `TypedArray#set` ([v0.9.0](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.9.0)) +- Added support for x instanceof GenericClass ([v0.9.2](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.9.2)) +- Added `StaticArray`, a more efficient array variant ([v0.9.3](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.9.3)) +- Added `Array#flat` ([v0.10.0](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.10.0)) +- Implemented `radix` argument on `Number#toString` ([v0.10.1](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.10.1)) +- Added support for separators in floating point literals ([v0.13.7](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.13.7)) +- Added support for first class functions ([v0.14.0](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.14.0)) +- Add builtins: `i32/i64/f32/f64.add/sub/mul` ([v0.14.13](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.14.13)) +- Implement `Array/TypedArray/String#at` ([v0.18.2](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.18.2)) +- Added support for template literal strings ([v0.18.17](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.18.17)) +- Add `encodeURI(Component)` and `decodeURI(Component)` ([v0.18.27](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.18.27)) +- Add `toString`, `toDateString` and `toTimeString` to `Date` ([v0.18.29](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.18.29)) +- Add `toUTCString` for `Date` ([v0.18.30](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.18.30)) +- Add `nonnull/NonNullable` builtin type ([v0.19.2](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.19.2)) + +### Optimizations + +- `Math` functions such as `exp`, `exp2`, `log`, `log2` and `pow` have been replaced by faster variants ([v0.9.0](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.9.0)) +- Slightly optimize `Math.mod` ([v0.17.1](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.17.1)) +- Cache more field accesses in std Map and Set ([v0.17.8](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.17.8)) +- Optimize for powers of two in `ipow32/64` ([v0.18.2](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.18.2)) + +### Other + +- The type of an array literal can now be inferred from its contents ([v0.9.0](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.9.0)) +- Updated stdlib to Unicode 13.0.0 ([v0.10.0](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.10.0)) + +## How to upgrade? + +1. Change your mappings `apiVersion` in `subgraph.yaml` to `0.0.6`: + +```yaml +... +dataSources: + ... + mapping: + ... + apiVersion: 0.0.6 + ... +``` + +2. Update the `graph-cli` you're using to the `latest` version by running: + +```bash +# if you have it globally installed +npm install --global @graphprotocol/graph-cli@latest + +# or in your subgraph if you have it as a dev dependency +npm install --save-dev @graphprotocol/graph-cli@latest +``` + +3. Do the same for `graph-ts`, but instead of installing globally, save it in your main dependencies: + +```bash +npm install --save @graphprotocol/graph-ts@latest +``` + +4. Follow the rest of the guide to fix the language breaking changes. +5. Run `codegen` and `deploy` again. + +## Breaking changes + +### Nullability + +On the older version of AssemblyScript, you could create code like this: + +```typescript +function load(): Value | null { ... } + +let maybeValue = load(); +maybeValue.aMethod(); +``` + +However on the newer version, because the value is nullable, it requires you to check, like this: + +```typescript +let maybeValue = load() + +if (maybeValue) { + maybeValue.aMethod() // `maybeValue` is not null anymore +} +``` + +Or force it like this: + +```typescript +let maybeValue = load()! // breaks in runtime if value is null + +maybeValue.aMethod() +``` + +If you are unsure which to choose, we recommend always using the safe version. If the value doesn't exist you might want to just do an early if statement with a return in you subgraph handler. + +### Variable Shadowing + +Before you could do [variable shadowing](https://en.wikipedia.org/wiki/Variable_shadowing) and code like this would work: + +```typescript +let a = 10 +let b = 20 +let a = a + b +``` + +However now this isn't possible anymore, and the compiler returns this error: + +```typescript +ERROR TS2451: Cannot redeclare block-scoped variable 'a' + + let a = a + b; + ~~~~~~~~~~~~~ +in assembly/index.ts(4,3) +``` +You'll need to rename your duplicate variables if you had variable shadowing. +### Null Comparisons +By doing the upgrade on your subgraph, sometimes you might get errors like these: + +```typescript +ERROR TS2322: Type '~lib/@graphprotocol/graph-ts/common/numbers/BigInt | null' is not assignable to type '~lib/@graphprotocol/graph-ts/common/numbers/BigInt'. + if (decimals == null) { + ~~~~ + in src/mappings/file.ts(41,21) +``` +To solve you can simply change the `if` statement to something like this: + +```typescript + if (!decimals) { + + // or + + if (decimals === null) { +``` + +The same applies if you're doing != instead of ==. + +### Casting + +The common way to do casting before was to just use the `as` keyword, like this: + +```typescript +let byteArray = new ByteArray(10) +let uint8Array = byteArray as Uint8Array // equivalent to: byteArray +``` + +However this only works in two scenarios: + +- Primitive casting (between types such as `u8`, `i32`, `bool`; eg: `let b: isize = 10; b as usize`); +- Upcasting on class inheritance (subclass → superclass) + +Examples: + +```typescript +// primitive casting +let a: usize = 10 +let b: isize = 5 +let c: usize = a + (b as usize) +``` + +```typescript +// upcasting on class inheritance +class Bytes extends Uint8Array {} + +let bytes = new Bytes(2) < Uint8Array > bytes // same as: bytes as Uint8Array +``` + +There are two scenarios where you may want to cast, but using `as`/`var` **isn't safe**: + +- Downcasting on class inheritance (superclass → subclass) +- Between two types that share a superclass + +```typescript +// downcasting on class inheritance +class Bytes extends Uint8Array {} + +let uint8Array = new Uint8Array(2) < Bytes > uint8Array // breaks in runtime :( +``` + +```typescript +// between two types that share a superclass +class Bytes extends Uint8Array {} +class ByteArray extends Uint8Array {} + +let bytes = new Bytes(2) < ByteArray > bytes // breaks in runtime :( +``` + +For those cases, you can use the `changetype` function: + +```typescript +// downcasting on class inheritance +class Bytes extends Uint8Array {} + +let uint8Array = new Uint8Array(2) +changetype(uint8Array) // works :) +``` + +```typescript +// between two types that share a superclass +class Bytes extends Uint8Array {} +class ByteArray extends Uint8Array {} + +let bytes = new Bytes(2) +changetype(bytes) // works :) +``` + +If you just want to remove nullability, you can keep using the `as` operator (or `variable`), but make sure you know that value can't be null, otherwise it will break. + +```typescript +// remove nullability +let previousBalance = AccountBalance.load(balanceId) // AccountBalance | null + +if (previousBalance != null) { + return previousBalance as AccountBalance // safe remove null +} + +let newBalance = new AccountBalance(balanceId) +``` + +For the nullability case we recommend taking a look at the [nullability check feature](https://www.assemblyscript.org/basics.html#nullability-checks), it will make your code cleaner 🙂 + +Also we've added a few more static methods in some types to ease casting, they are: + +- Bytes.fromByteArray +- Bytes.fromUint8Array +- BigInt.fromByteArray +- ByteArray.fromBigInt + +### Nullability check with property access + +To use the [nullability check feature](https://www.assemblyscript.org/basics.html#nullability-checks) you can use either `if` statements or the ternary operator (`?` and `:`) like this: + +```typescript +let something: string | null = 'data' + +let somethingOrElse = something ? something : 'else' + +// or + +let somethingOrElse + +if (something) { + somethingOrElse = something +} else { + somethingOrElse = 'else' +} +``` + +However that only works when you're doing the `if` / ternary on a variable, not on a property access, like this: + +```typescript +class Container { + data: string | null +} + +let container = new Container() +container.data = 'data' + +let somethingOrElse: string = container.data ? container.data : 'else' // doesn't compile +``` + +Which outputs this error: + +```typescript +ERROR TS2322: Type '~lib/string/String | null' is not assignable to type '~lib/string/String'. + + let somethingOrElse: string = container.data ? container.data : "else"; + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +``` +To fix this issue, you can create a variable for that property access so that the compiler can do the nullability check magic: + +```typescript +class Container { + data: string | null +} + +let container = new Container() +container.data = 'data' + +let data = container.data + +let somethingOrElse: string = data ? data : 'else' // compiles just fine :) +``` + +### Operator overloading with property access + +If you try to sum (for example) a nullable type (from a property access) with a non nullable one, the AssemblyScript compiler instead of giving a compile time error warning that one of the values is nullable, it just compiles silently, giving chance for the code to break at runtime. + +```typescript +class BigInt extends Uint8Array { + @operator('+') + plus(other: BigInt): BigInt { + // ... + } +} + +class Wrapper { + public constructor(public n: BigInt | null) {} +} + +let x = BigInt.fromI32(2) +let y: BigInt | null = null + +x + y // give compile time error about nullability + +let wrapper = new Wrapper(y) + +wrapper.n = wrapper.n + x // doesn't give compile time errors as it should +``` + +We've opened a issue on the AssemblyScript compiler for this, but for now if you do these kind of operations in your subgraph mappings, you should change them to do a null check before it. + +```typescript +let wrapper = new Wrapper(y) + +if (!wrapper.n) { + wrapper.n = BigInt.fromI32(0) +} + +wrapper.n = wrapper.n + x // now `n` is guaranteed to be a BigInt +``` + +### Value initialization + +If you have any code like this: + +```typescript +var value: Type // null +value.x = 10 +value.y = 'content' +``` + +It will compile but break at runtime, that happens because the value hasn't been initialized, so make sure your subgraph has initialized their values, like this: + +```typescript +var value = new Type() // initialized +value.x = 10 +value.y = 'content' +``` + +Also if you have nullable properties in a GraphQL entity, like this: + +```graphql +type Total @entity { + id: ID! + amount: BigInt +} +``` + +And you have code similar to this: + +```typescript +let total = Total.load('latest') + +if (total === null) { + total = new Total('latest') +} + +total.amount = total.amount + BigInt.fromI32(1) +``` + +You'll need to make sure to initialize the `total.amount` value, because if you try to access like in the last line for the sum, it will crash. So you either initialize it first: + +```typescript +let total = Total.load('latest') + +if (total === null) { + total = new Total('latest') + total.amount = BigInt.fromI32(0) +} + +total.tokens = total.tokens + BigInt.fromI32(1) +``` + +Or you can just change your GraphQL schema to not use a nullable type for this property, then we'll initialize it as zero on the `codegen` step 😉 + +```graphql +type Total @entity { + id: ID! + amount: BigInt! +} +``` + +```typescript +let total = Total.load('latest') + +if (total === null) { + total = new Total('latest') // already initializes non-nullable properties +} + +total.amount = total.amount + BigInt.fromI32(1) +``` + +### Class property initialization + +If you export any classes with properties that are other classes (declared by you or by the standard library) like this: + +```typescript +class Thing {} + +export class Something { + value: Thing +} +``` + +The compiler will error because you either need to add an initializer for the properties that are classes, or add the `!` operator: + +```typescript +export class Something { + constructor(public value: Thing) {} +} + +// or + +export class Something { + value: Thing + + constructor(value: Thing) { + this.value = value + } +} + +// or + +export class Something { + value!: Thing +} +``` + +### GraphQL schema + +This is not a direct AssemblyScript change, but you may have to update your `schema.graphql` file. + +Now you no longer can define fields in your types that are Non-Nullable Lists. If you have a schema like this: + +```graphql +type Something @entity { + id: ID! +} + +type MyEntity @entity { + id: ID! + invalidField: [Something]! # no longer valid +} +``` + +You'll have to add an `!` to the member of the List type, like this: + +```graphql +type Something @entity { + id: ID! +} + +type MyEntity @entity { + id: ID! + invalidField: [Something!]! # valid +} +``` + +This changed because of nullability differences between AssemblyScript versions, and it's related to the `src/generated/schema.ts` file (default path, you might have changed this). + +### Other + +- Aligned `Map#set` and `Set#add` with the spec, returning `this` ([v0.9.2](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.9.2)) +- Arrays no longer inherit from ArrayBufferView, but are now distinct ([v0.10.0](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.10.0)) +- Classes initialized from object literals can no longer define a constructor ([v0.10.0](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.10.0)) +- The result of a `**` binary operation is now the common denominator integer if both operands are integers. Previously, the result was a float as if calling `Math/f.pow` ([v0.11.0](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.11.0)) +- Coerce `NaN` to `false` when casting to `bool` ([v0.14.9](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.14.9)) +- When shifting a small integer value of type `i8`/`u8` or `i16`/`u16`, only the 3 respectively 4 least significant bits of the RHS value affect the result, analogous to the result of an `i32.shl` only being affected by the 5 least significant bits of the RHS value. Example: `someI8 << 8` previously produced the value `0`, but now produces `someI8` due to masking the RHS as `8 & 7 = 0` (3 bits) ([v0.17.0](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.17.0)) +- Bug fix of relational string comparisons when sizes differ ([v0.17.8](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.17.8)) diff --git a/pages/ko/developer/create-subgraph-hosted.mdx b/pages/ko/developer/create-subgraph-hosted.mdx new file mode 100644 index 000000000000..6b235e379634 --- /dev/null +++ b/pages/ko/developer/create-subgraph-hosted.mdx @@ -0,0 +1,928 @@ +--- +title: Create a Subgraph +--- + +Before being able to use the Graph CLI, you need to create your subgraph in [Subgraph Studio](https://thegraph.com/studio). You will then be able to setup your subgraph project and deploy it to the platform of your choice. Note that **subgraphs that do not index Ethereum mainnet will not be published to The Graph Network**. + +The `graph init` command can be used to set up a new subgraph project, either from an existing contract on any of the public Ethereum networks, or from an example subgraph. This command can be used to create a subgraph on the Subgraph Studio by passing in `graph init --product subgraph-studio`. If you already have a smart contract deployed to Ethereum mainnet or one of the testnets, bootstrapping a new subgraph from that contract can be a good way to get started. But first, a little about the networks The Graph supports. + +## Supported Networks + +The Graph Network supports subgraphs indexing mainnet Ethereum: + +- `mainnet` + +**Additional Networks are supported in beta on the Hosted Service**: + +- `mainnet` +- `kovan` +- `rinkeby` +- `ropsten` +- `goerli` +- `poa-core` +- `poa-sokol` +- `xdai` +- `near-mainnet` +- `near-testnet` +- `matic` +- `mumbai` +- `fantom` +- `bsc` +- `chapel` +- `clover` +- `avalanche` +- `fuji` +- `celo` +- `celo-alfajores` +- `fuse` +- `moonriver` +- `mbase` +- `arbitrum-one` +- `arbitrum-rinkeby` +- `optimism` +- `optimism-kovan` +- `aurora` +- `aurora-testnet` + +The Graph's Hosted Service relies on the stability and reliability of the underlying technologies, namely the provided JSON RPC endpoints. Newer networks will be marked as being in beta until the network has proven itself in terms of stability, reliability, and scalability. During this beta period, there is risk of downtime and unexpected behaviour. + +Remember that you will **not be able** to publish a subgraph that indexes a non-mainnet network to the decentralized Graph Network in [Subgraph Studio](/studio/subgraph-studio). + +## From An Existing Contract + +The following command creates a subgraph that indexes all events of an existing contract. It attempts to fetch the contract ABI from Etherscan and falls back to requesting a local file path. If any of the optional arguments are missing, it takes you through an interactive form. + +```sh +graph init \ + --product subgraph-studio + --from-contract \ + [--network ] \ + [--abi ] \ + [] +``` + +The `` is the ID of your subgraph in Subgraph Studio, it can be found on your subgraph details page. + +## From An Example Subgraph + +The second mode `graph init` supports is creating a new project from an example subgraph. The following command does this: + +``` +graph init --studio +``` + +The example subgraph is based on the Gravity contract by Dani Grant that manages user avatars and emits `NewGravatar` or `UpdateGravatar` events whenever avatars are created or updated. The subgraph handles these events by writing `Gravatar` entities to the Graph Node store and ensuring these are updated according to the events. The following sections will go over the files that make up the subgraph manifest for this example. + +## The Subgraph Manifest + +The subgraph manifest `subgraph.yaml` defines the smart contracts your subgraph indexes, which 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 full specification for subgraph manifests can be found [here](https://github.com/graphprotocol/graph-node/blob/master/docs/subgraph-manifest.md). + +For the example subgraph, `subgraph.yaml` is: + +```yaml +specVersion: 0.0.4 +description: Gravatar for Ethereum +repository: https://github.com/graphprotocol/example-subgraph +schema: + file: ./schema.graphql +dataSources: + - kind: ethereum/contract + name: Gravity + network: mainnet + source: + address: '0x2E645469f354BB4F5c8a05B3b30A929361cf77eC' + abi: Gravity + startBlock: 6175244 + mapping: + kind: ethereum/events + apiVersion: 0.0.6 + language: wasm/assemblyscript + entities: + - Gravatar + abis: + - name: Gravity + file: ./abis/Gravity.json + eventHandlers: + - event: NewGravatar(uint256,address,string,string) + handler: handleNewGravatar + - event: UpdatedGravatar(uint256,address,string,string) + handler: handleUpdatedGravatar + callHandlers: + - function: createGravatar(string,string) + handler: handleCreateGravatar + blockHandlers: + - function: handleBlock + - function: handleBlockWithCall + filter: + kind: call + file: ./src/mapping.ts +``` + +The important entries to update for the manifest are: + +- `description`: a human-readable description of what the subgraph is. This description is displayed by the Graph Explorer when the subgraph is deployed to the Hosted Service. + +- `repository`: the URL of the repository where the subgraph manifest can be found. This is also displayed by the Graph Explorer. + +- `features`: a list of all used [feature](#experimental-features) names. + +- `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.mapping.entities`: the entities that the data source writes to the store. The schema for each entity is defined in the 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 filter can be provided with the following kinds: call`. A`call` filter will 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. + +The triggers for a data source within a block are ordered using the following process: + +1. Event and call triggers are first ordered by transaction index within the block. +2. Event and call triggers with in the same transaction are ordered using a convention: event triggers first then call triggers, each type respecting the order they are defined in the manifest. +3. Block triggers are run after event and call triggers, in the order they are defined in the manifest. + +These ordering rules are subject to change. + +### Getting The ABIs + +The ABI file(s) must match your contract(s). There are a few ways to obtain ABI files: + +- If you are building your own project, you will likely have access to your most current ABIs. +- If you are building a subgraph for a public project, you can download that project to your computer and get the ABI by using [`truffle compile`](https://truffleframework.com/docs/truffle/overview) or using solc to compile. +- You can also find the ABI on [Etherscan](https://etherscan.io/), but this isn't always reliable, as the ABI that is uploaded there may be out of date. Make sure you have the right ABI, otherwise running your subgraph will fail. + +## The GraphQL Schema + +The schema for your subgraph is in the file `schema.graphql`. GraphQL schemas are defined using the GraphQL interface definition language. If you've never written a GraphQL schema, it is recommended that you check out this primer on the GraphQL type system. Reference documentation for GraphQL schemas can be found in the [GraphQL API](/developer/graphql-api) section. + +## Defining Entities + +Before defining entities, it is important to take a step back and think about how your data is structured and linked. All queries will be made against the data model defined in the subgraph schema and the entities indexed by the subgraph. Because of this, it is good to define the subgraph schema in a way that matches the needs of your dapp. It may be useful to imagine entities as "objects containing data", rather than as events or functions. + +With The Graph, you simply define entity types in `schema.graphql`, and Graph Node will generate top level fields for querying single instances and collections of that entity type. Each type that should be an entity is required to be annotated with an `@entity` directive. + +### Good Example + +The `Gravatar` entity below is structured around a Gravatar object and is a good example of how an entity could be defined. + +```graphql +type Gravatar @entity { + id: ID! + owner: Bytes + displayName: String + imageUrl: String + accepted: Boolean +} +``` + +### Bad Example + +The example `GravatarAccepted` and `GravatarDeclined` entities below are based around events. It is not recommended to map events or function calls to entities 1:1. + +```graphql +type GravatarAccepted @entity { + id: ID! + owner: Bytes + displayName: String + imageUrl: String +} + +type GravatarDeclined @entity { + id: ID! + owner: Bytes + displayName: String + imageUrl: String +} +``` + +### Optional and Required Fields + +Entity fields can be defined as required or optional. Required fields are indicated by the `!` in the schema. If a required field is not set in the mapping, you will receive this error when querying the field: + +``` +Null value resolved for non-null field 'name' +``` + +Each entity must have an `id` field, which is of type `ID!` (string). The `id` field serves as the primary key, and needs to be unique among all entities of the same type. + +### Built-In Scalar Types + +#### GraphQL Supported Scalars + +We support the following scalars in our GraphQL API: + +| Type | Description | +| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `Bytes` | Byte array, represented as a hexadecimal string. Commonly used for Ethereum hashes and addresses. | +| `ID` | Stored as a `string`. | +| `String` | Scalar for `string` values. Null characters are not supported and are automatically removed. | +| `Boolean` | Scalar for `boolean` values. | +| `Int` | The GraphQL spec defines `Int` to have size of 32 bytes. | +| `BigInt` | Large integers. Used for Ethereum's `uint32`, `int64`, `uint64`, ..., `uint256` types. Note: Everything below `uint32`, such as `int32`, `uint24` or `int8` is represented as `i32`. | +| `BigDecimal` | `BigDecimal` High precision decimals represented as a signficand and an exponent. The exponent range is from −6143 to +6144. Rounded to 34 significant digits. | + +#### Enums + +You can also create enums within a schema. Enums have the following syntax: + +```graphql +enum TokenStatus { + OriginalOwner + SecondOwner + ThirdOwner +} +``` + +Once the enum is defined in the schema, you can use the string representation of the enum value to set an enum field on an entity. For example, you can set the `tokenStatus` to `SecondOwner` by first defining your entity and subsequently setting the field with `entity.tokenStatus = "SecondOwner`. The example below demonstrates what the Token entity would look like with an enum field: + +More detail on writing enums can be found in the [GraphQL documentation](https://graphql.org/learn/schema/). + +#### Entity Relationships + +An entity may have a relationship to one or more other entities in your schema. These relationships may be traversed in your queries. Relationships in The Graph are unidirectional. It is possible to simulate bidirectional relationships by defining a unidirectional relationship on either "end" of the relationship. + +Relationships are defined on entities just like any other field except that the type specified is that of another entity. + +#### One-To-One Relationships + +Define a `Transaction` entity type with an optional one-to-one relationship with a `TransactionReceipt` entity type: + +```graphql +type Transaction @entity { + id: ID! + transactionReceipt: TransactionReceipt +} + +type TransactionReceipt @entity { + id: ID! + transaction: Transaction +} +``` + +#### One-To-Many Relationships + +Define a `TokenBalance` entity type with a required one-to-many relationship with a Token entity type: + +```graphql +type Token @entity { + id: ID! +} + +type TokenBalance @entity { + id: ID! + amount: Int! + token: Token! +} +``` + +#### Reverse Lookups + +Reverse lookups can be defined on an entity through the `@derivedFrom` field. This creates a virtual field on the entity that may be queried but cannot be set manually through the mappings API. Rather, it is derived from the relationship defined on the other entity. For such relationships, it rarely makes sense to store both sides of the relationship, and both indexing and query performance will be better when only one side is stored and the other is derived. + +For one-to-many relationships, the relationship should always be stored on the 'one' side, and the 'many' side should always be derived. Storing the relationship this way, rather than storing an array of entities on the 'many' side, will result in dramatically better performance for both indexing and querying the subgraph. In general, storing arrays of entities should be avoided as much as is practical. + +#### Example + +We can make the balances for a token accessible from the token by deriving a `tokenBalances` field: + +```graphql +type Token @entity { + id: ID! + tokenBalances: [TokenBalance!]! @derivedFrom(field: "token") +} + +type TokenBalance @entity { + id: ID! + amount: Int! + token: Token! +} +``` + +#### Many-To-Many Relationships + +For many-to-many relationships, such as users that each may belong to any number of organizations, the most straightforward, but generally not the most performant, way to model the relationship is as an array in each of the two entities involved. If the relationship is symmetric, only one side of the relationship needs to be stored and the other side can be derived. + +#### Example + +Define a reverse lookup from a `User` entity type to an `Organization` entity type. In the example below, this is achieved by looking up the `members` attribute from within the `Organization` entity. In queries, the `organizations` field on `User` will be resolved by finding all `Organization` entities that include the user's ID. + +```graphql +type Organization @entity { + id: ID! + name: String! + members: [User!]! +} + +type User @entity { + id: ID! + name: String! + organizations: [Organization!]! @derivedFrom(field: "members") +} +``` + +A more performant way to store this relationship is through a mapping table that has one entry for each `User` / `Organization` pair with a schema like + +```graphql +type Organization @entity { + id: ID! + name: String! + members: [UserOrganization]! @derivedFrom(field: "user") +} + +type User @entity { + id: ID! + name: String! + organizations: [UserOrganization!] @derivedFrom(field: "organization") +} + +type UserOrganization @entity { + id: ID! # Set to `${user.id}-${organization.id}` + user: User! + organization: Organization! +} +``` + +This approach requires that queries descend into one additional level to retrieve, for example, the organizations for users: + +```graphql +query usersWithOrganizations { + users { + organizations { + # this is a UserOrganization entity + organization { + name + } + } + } +} +``` + +This more elaborate way of storing many-to-many relationships will result in less data stored for the subgraph, and therefore to a subgraph that is often dramatically faster to index and to query. + +#### Adding comments to the schema + +As per GraphQL spec, comments can be added above schema entity attributes using double quotations `""`. This is illustrated in the example below: + +```graphql +type MyFirstEntity @entity { + "unique identifier and primary key of the entity" + id: ID! + address: Bytes! +} +``` + +## Defining Fulltext Search Fields + +Fulltext search queries filter and rank entities based on a text search input. Fulltext queries are able to return matches for similar words by processing the query text input into stems before comparing to the indexed text data. + +A fulltext query definition includes the query name, the language dictionary used to process the text fields, the ranking algorithm used to order the results, and the fields included in the search. Each fulltext query may span multiple fields, but all included fields must be from a single entity type. + +To add a fulltext query, include a `_Schema_` type with a fulltext directive in the GraphQL schema. + +```graphql +type _Schema_ + @fulltext( + name: "bandSearch" + language: en + algorithm: rank + include: [{ entity: "Band", fields: [{ name: "name" }, { name: "description" }, { name: "bio" }] }] + ) + +type Band @entity { + id: ID! + name: String! + description: String! + bio: String + wallet: Address + labels: [Label!]! + discography: [Album!]! + members: [Musician!]! +} +``` + +The example `bandSearch` field can be used in queries to filter `Band` entities based on the text documents in the `name`, `description`, and `bio` fields. Jump to [GraphQL API - Queries](/developer/graphql-api#queries) for a description of the Fulltext search API and for more example usage. + +```graphql +query { + bandSearch(text: "breaks & electro & detroit") { + id + name + description + wallet + } +} +``` + +> **[Feature Management](#experimental-features):** From `specVersion` `0.0.4` and onwards, `fullTextSearch` must be declared under the `features` section in the subgraph manifest. + +### Languages supported + +Choosing a different language will have a definitive, though sometimes subtle, effect on the fulltext search API. Fields covered by a fulltext query field are examined in the context of the chosen language, so the lexemes produced by analysis and search queries vary language to language. For example: when using the supported Turkish dictionary "token" is stemmed to "toke" while, of course, the English dictionary will stem it to "token". + +Supported language dictionaries: + +| Code | Dictionary | +| ------ | ---------- | +| simple | General | +| da | Danish | +| nl | Dutch | +| en | English | +| fi | Finnish | +| fr | French | +| de | German | +| hu | Hungarian | +| it | Italian | +| no | Norwegian | +| pt | Portugese | +| ro | Romanian | +| ru | Russian | +| es | Spanish | +| sv | Swedish | +| tr | Turkish | + +### Ranking Algorithms + +Supported algorithms for ordering results: + +| Algorithm | Description | +| ------------- | ----------------------------------------------------------------------- | +| rank | Use the match quality (0-1) of the fulltext query to order the results. | +| proximityRank | Similar to rank but also includes the proximity of the matches. | + +## Writing Mappings + +The mappings transform the Ethereum data your mappings are sourcing into entities defined in your schema. Mappings are written in a subset of [TypeScript](https://www.typescriptlang.org/docs/handbook/typescript-in-5-minutes.html) called [AssemblyScript](https://github.com/AssemblyScript/assemblyscript/wiki) which can be compiled to WASM ([WebAssembly](https://webassembly.org/)). AssemblyScript is stricter than normal TypeScript, yet provides a familiar syntax. + +For each event handler that is defined in `subgraph.yaml` under `mapping.eventHandlers`, create an exported function of the same name. Each handler must accept a single parameter called `event` with a type corresponding to the name of the event which is being handled. + +In the example subgraph, `src/mapping.ts` contains handlers for the `NewGravatar` and `UpdatedGravatar` events: + +```javascript +import { NewGravatar, UpdatedGravatar } from '../generated/Gravity/Gravity' +import { Gravatar } from '../generated/schema' + +export function handleNewGravatar(event: NewGravatar): void { + let gravatar = new Gravatar(event.params.id.toHex()) + gravatar.owner = event.params.owner + gravatar.displayName = event.params.displayName + gravatar.imageUrl = event.params.imageUrl + gravatar.save() +} + +export function handleUpdatedGravatar(event: UpdatedGravatar): void { + let id = event.params.id.toHex() + let gravatar = Gravatar.load(id) + if (gravatar == null) { + gravatar = new Gravatar(id) + } + gravatar.owner = event.params.owner + gravatar.displayName = event.params.displayName + gravatar.imageUrl = event.params.imageUrl + gravatar.save() +} +``` + +The first handler takes a `NewGravatar` event and creates a new `Gravatar` entity with `new Gravatar(event.params.id.toHex())`, populating the entity fields using the corresponding event parameters. This entity instance is represented by the variable `gravatar`, with an id value of `event.params.id.toHex()`. + +The second handler tries to load the existing `Gravatar` from the Graph Node store. If it does not exist yet, it is created on demand. The entity is then updated to match the new event parameters, before it is saved back to the store using `gravatar.save()`. + +### Recommended IDs for Creating New Entities + +Every entity has to have an `id` that is unique among all entities of the same type. An entity's `id` value is set when the entity is created. Below are some recommended `id` values to consider when creating new entities. NOTE: The value of `id` must be a `string`. + +- `event.params.id.toHex()` +- `event.transaction.from.toHex()` +- `event.transaction.hash.toHex() + "-" + event.logIndex.toString()` + +We provide the [Graph Typescript Library](https://github.com/graphprotocol/graph-ts) which contains utilies for interacting with the Graph Node store and conveniences for handling smart contract data and entities. You can use this library in your mappings by importing `@graphprotocol/graph-ts` in `mapping.ts`. + +## Code Generation + +In order to make working smart contracts, events and entities easy and type-safe, the Graph CLI can generate AssemblyScript types from the subgraph's GraphQL schema and the contract ABIs included in the data sources. + +This is done with + +```sh +graph codegen [--output-dir ] [] +``` + +but in most cases, subgraphs are already preconfigured via `package.json` to allow you to simply run one of the following to achieve the same: + +```sh +# Yarn +yarn codegen + +# NPM +npm run codegen +``` + +This will generate an AssemblyScript class for every smart contract in the ABI files mentioned in `subgraph.yaml`, allowing you to bind these contracts to specific addresses in the mappings and call read-only contract methods against the block being processed. It will also generate a class for every contract event to provide easy access to event parameters as well as the block and transaction the event originated from. All of these types are written to `//.ts`. In the example subgraph, this would be `generated/Gravity/Gravity.ts`, allowing mappings to import these types with + +```javascript +import { + // The contract class: + Gravity, + // The events classes: + NewGravatar, + UpdatedGravatar, +} from '../generated/Gravity/Gravity' +``` + +In addition to this, one class is generated for each entity type in the subgraph's GraphQL schema. These classes provide type-safe entity loading, read and write access to entity fields as well as a `save()` method to write entities to store. All entity classes are written to `/schema.ts`, allowing mappings to import them with + +```javascript +import { Gravatar } from '../generated/schema' +``` + +> **Note:** The code generation must be performed again after every change to the GraphQL schema or the ABIs included in the manifest. It must also be performed at least once before building or deploying the subgraph. + +Code generation does not check your mapping code in `src/mapping.ts`. If you want to check that before trying to deploy your subgraph to the Graph Explorer, you can run `yarn build` and fix any syntax errors that the TypeScript compiler might find. + +## Data Source Templates + +A common pattern in Ethereum smart contracts is the use of registry or factory contracts, where one contract creates, manages or references an arbitrary number of other contracts that each have their own state and events. 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_. + +### Data Source for the Main Contract + +First, you define a regular data source for the main contract. The snippet below shows a simplified example data source for the [Uniswap](https://uniswap.io) exchange factory contract. Note the `NewExchange(address,address)` event handler. This is emitted when a new exchange contract is created on chain by the factory contract. + +```yaml +dataSources: + - kind: ethereum/contract + name: Factory + network: mainnet + source: + address: '0xc0a47dFe034B400B47bDaD5FecDa2621de6c4d95' + abi: Factory + mapping: + kind: ethereum/events + apiVersion: 0.0.6 + language: wasm/assemblyscript + file: ./src/mappings/factory.ts + entities: + - Directory + abis: + - name: Factory + file: ./abis/factory.json + eventHandlers: + - event: NewExchange(address,address) + handler: handleNewExchange +``` + +### Data Source Templates for Dynamically Created Contracts + +Then, you add _data source templates_ to the manifest. These are identical to regular data sources, except that they lack a predefined contract address under `source`. Typically, you would define one template for each type of sub-contract managed or referenced by the parent contract. + +```yaml +dataSources: + - kind: ethereum/contract + name: Factory + # ... other source fields for the main contract ... +templates: + - name: Exchange + kind: ethereum/contract + network: mainnet + source: + abi: Exchange + mapping: + kind: ethereum/events + apiVersion: 0.0.6 + language: wasm/assemblyscript + file: ./src/mappings/exchange.ts + entities: + - Exchange + abis: + - name: Exchange + file: ./abis/exchange.json + eventHandlers: + - event: TokenPurchase(address,uint256,uint256) + handler: handleTokenPurchase + - event: EthPurchase(address,uint256,uint256) + handler: handleEthPurchase + - event: AddLiquidity(address,uint256,uint256) + handler: handleAddLiquidity + - event: RemoveLiquidity(address,uint256,uint256) + handler: handleRemoveLiquidity +``` + +### Instantiating a Data Source Template + +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. + +```typescript +import { Exchange } from '../generated/templates' + +export function handleNewExchange(event: NewExchange): void { + // Start indexing the exchange; `event.params.exchange` is the + // address of the new exchange contract + Exchange.create(event.params.exchange) +} +``` + +> **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. +> +> If prior blocks contain data relevant to the new data source, it is best to index that data by reading the current state of the contract and creating entities representing that state at the time the new data source is created. + +### Data Source Context + +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: + +```typescript +import { Exchange } from '../generated/templates' + +export function handleNewExchange(event: NewExchange): void { + let context = new DataSourceContext() + context.setString('tradingPair', event.params.tradingPair) + Exchange.createWithContext(event.params.exchange, context) +} +``` + +Inside a mapping of the `Exchange` template, the context can then be accessed: + +```typescript +import { dataSource } from '@graphprotocol/graph-ts' + +let context = dataSource.context() +let tradingPair = context.getString('tradingPair') +``` + +There are setters and getters like `setString` and `getString` for all value types. + +## Start Blocks + +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. + +```yaml +dataSources: + - kind: ethereum/contract + name: ExampleSource + network: mainnet + source: + address: '0xc0a47dFe034B400B47bDaD5FecDa2621de6c4d95' + abi: ExampleContract + startBlock: 6627917 + mapping: + kind: ethereum/events + apiVersion: 0.0.6 + language: wasm/assemblyscript + file: ./src/mappings/factory.ts + entities: + - User + abis: + - name: ExampleContract + file: ./abis/ExampleContract.json + eventHandlers: + - event: NewEvent(address,address) + handler: handleNewEvent +``` + +> **Note:** The contract creation block can be quickly looked up on Etherscan: +> +> 1. Search for the contract by entering its address in the search bar. +> 2. Click on the creation transaction hash in the `Contract Creator` section. +> 3. Load the transaction details page where you'll find the start block for that contract. + +## Call Handlers + +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. + +Call handlers will only trigger in one of two cases: when the function specified is called by an account other than the contract itself or when it is marked as external in Solidity and called as part of another function in the same contract. + +> **Note:** Call handlers are not supported on Rinkeby, Goerli or Ganache. Call handlers currently depend on the Parity tracing API and these networks do not support it. + +### Defining a Call Handler + +To define a call handler in your manifest simply add a `callHandlers` array under the data source you would like to subscribe to. + +```yaml +dataSources: + - kind: ethereum/contract + name: Gravity + network: mainnet + source: + address: '0x731a10897d267e19b34503ad902d0a29173ba4b1' + abi: Gravity + mapping: + kind: ethereum/events + apiVersion: 0.0.6 + language: wasm/assemblyscript + entities: + - Gravatar + - Transaction + abis: + - name: Gravity + file: ./abis/Gravity.json + callHandlers: + - function: createGravatar(string,string) + 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. + +### Mapping Function + +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: + +```typescript +import { CreateGravatarCall } from '../generated/Gravity/Gravity' +import { Transaction } from '../generated/schema' + +export function handleCreateGravatar(call: CreateGravatarCall): void { + let id = call.transaction.hash.toHex() + let transaction = new Transaction(id) + transaction.displayName = call.inputs._displayName + transaction.imageUrl = call.inputs._imageUrl + transaction.save() +} +``` + +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`. + +## Block Handlers + +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 predefined filter. + +### Supported Filters + +```yaml +filter: + 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._ + +The absense of a filter for a block handler will ensure that the handler is called every block. A data source can only contain one block handler for each filter type. + +```yaml +dataSources: + - kind: ethereum/contract + name: Gravity + network: dev + source: + address: '0x731a10897d267e19b34503ad902d0a29173ba4b1' + abi: Gravity + mapping: + kind: ethereum/events + apiVersion: 0.0.6 + language: wasm/assemblyscript + entities: + - Gravatar + - Transaction + abis: + - name: Gravity + file: ./abis/Gravity.json + blockHandlers: + - handler: handleBlock + - handler: handleBlockWithCallToContract + filter: + kind: call +``` + +### Mapping Function + +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. + +```typescript +import { ethereum } from '@graphprotocol/graph-ts' + +export function handleBlock(block: ethereum.Block): void { + let id = block.hash.toHex() + let entity = new Block(id) + entity.save() +} +``` + +## Anonymous Events + +If you need to process anonymous events in Solidity, that can be achieved by providing the topic 0 of the event, as in the example: + +```yaml +eventHandlers: + - event: LogNote(bytes4,address,bytes32,bytes32,uint256,bytes) + topic0: '0xbaa8529c00000000000000000000000000000000000000000000000000000000' + 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. + +## Experimental features + +Starting from `specVersion` `0.0.4`, subgraph features must be explicitly declared in the `features` section at the top level of the manifest file, using their `camelCase` name, as listed in the table below: + +| Feature | Name | +| --------------------------------------------------------- | ------------------------- | +| [Non-fatal errors](#non-fatal-errors) | `nonFatalErrors` | +| [Full-text Search](#defining-fulltext-search-fields) | `fullTextSearch` | +| [Grafting](#grafting-onto-existing-subgraphs) | `grafting` | +| [IPFS on Ethereum Contracts](#ipfs-on-ethereum-contracts) | `ipfsOnEthereumContracts` | + +For instance, if a subgraph uses the **Full-Text Search** and the **Non-fatal Errors** features, the `features` field in the manifest should be: + +```yaml +specVersion: 0.0.4 +description: Gravatar for Ethereum +features: + - fullTextSearch + - nonFatalErrors +dataSources: ... +``` + +Note that using a feature without declaring it will incur in a **validation error** during subgraph deployment, but no errors will occur if a feature is declared but not used. + +### IPFS on Ethereum Contracts + +A common use case for combining IPFS with Ethereum is to store data on IPFS that would be too expensive to maintain on chain, and reference the IPFS hash in Ethereum contracts. + +Given such IPFS hashes, subgraphs can read the corresponding files from IPFS using `ipfs.cat` and `ipfs.map`. To do this reliably, however, it is required that these files are pinned on the IPFS node that the Graph Node indexing the subgraph connects to. In the case of the [hosted service](https://thegraph.com/hosted-service), this is [https://api.thegraph.com/ipfs/](https://api.thegraph.com/ipfs/). + +> **Note:** The Graph Network does not yet support `ipfs.cat` and `ipfs.map`, and developers should not deploy subgraphs using that functionality to the network via the Studio. + +In order to make this easy for subgraph developers, The Graph team wrote a tool for transfering files from one IPFS node to another, called [ipfs-sync](https://github.com/graphprotocol/ipfs-sync). + +> **[Feature Management](#experimental-features):** `ipfsOnEthereumContracts` must be declared under `features` in the subgraph manifest. + +### Non-fatal errors + +Indexing errors on already synced subgraphs will, by default, cause the subgraph to fail and stop syncing. Subgraphs can alternatively be configured to continue syncing in the presence of errors, by ignoring the changes made by the handler which provoked the error. This gives subgraph authors time to correct their subgraphs while queries continue to be served against the latest block, though the results will possibly be inconsistent due to the bug that caused the error. Note that some errors are still always fatal, to be non-fatal the error must be known to be deterministic. + +> **Note:** The Graph Network does not yet support non-fatal errors, and developers should not deploy subgraphs using that functionality to the network via the Studio. + +Enabling non-fatal errors requires setting the following feature flag on the subgraph manifest: + +```yaml +specVersion: 0.0.4 +description: Gravatar for Ethereum +features: + - fullTextSearch + ... +``` + +The query must also opt-in to querying data with potential inconsistencies through the `subgraphError` argument. It is also recommended to query `_meta` to check if the subgraph has skipped over errors, as in the example: + +```graphql +foos(first: 100, subgraphError: allow) { + id +} + +_meta { + hasIndexingErrors +} +``` + +If the subgraph encounters an error that query will return both the data and a graphql error with the message `"indexing_error"`, as in this example response: + +```graphql +"data": { + "foos": [ + { + "id": "fooId" + } + ], + "_meta": { + "hasIndexingErrors": true + } +}, +"errors": [ + { + "message": "indexing_error" + } +] +``` + +### Grafting onto Existing Subgraphs + +When a subgraph is first deployed, it starts indexing events at the genesis block of the corresponding chain (or at the `startBlock` defined with each data source) In some circumstances, it is beneficial to reuse the data from an existing subgraph and start indexing at a much later block. This mode of indexing is called _Grafting_. Grafting is, for example, useful during development to get past simple errors in the mappings quickly, or to temporarily get an existing subgraph working again after it has failed. + +> **Note:** Grafting requires that the Indexer has indexed the base subgraph. It is not recommended on The Graph Network at this time, and developers should not deploy subgraphs using that functionality to the network via the Studio. + +A subgraph is grafted onto a base subgraph when the subgraph manifest in `subgraph.yaml` contains a `graft` block at the toplevel: + +```yaml +description: ... +graft: + base: Qm... # Subgraph ID of base subgraph + block: 7345624 # Block number +``` + +When a subgraph whose manifest contains a `graft` block is deployed, Graph Node will copy the data of the `base` subgraph up to and including the given `block` and then continue indexing the new subgraph from that block on. The base subgraph must exist on the target Graph Node instance and must have indexed up to at least the given block. Because of this restriction, grafting should only be used during development or during an emergency to speed up producing an equivalent non-grafted subgraph. + +Because grafting copies rather than indexes base data it is much quicker in getting the subgraph to the desired block than indexing from scratch, though the initial data copy can still take several hours for very large subgraphs. While the grafted subgraph is being initialized, the Graph Node will log information about the entity types that have already been copied. + +The grafted subgraph can use a GraphQL schema that is not identical to the one of the base subgraph, but merely compatible with it. It has to be a valid subgraph schema in its own right but may deviate from the base subgraph's schema in the following ways: + +- It adds or removes entity types +- It removes attributes from entity types +- It adds nullable attributes to entity types +- It turns non-nullable attributes into nullable attributes +- It adds values to enums +- It adds or removes interfaces +- It changes for which entity types an interface is implemented + +> **[Feature Management](#experimental-features):** `grafting` must be declared under `features` in the subgraph manifest. diff --git a/pages/ko/developer/define-subgraph-hosted.mdx b/pages/ko/developer/define-subgraph-hosted.mdx new file mode 100644 index 000000000000..92bf5bd8cd2f --- /dev/null +++ b/pages/ko/developer/define-subgraph-hosted.mdx @@ -0,0 +1,35 @@ +--- +title: Define a Subgraph +--- + +A subgraph defines which data The Graph will index from Ethereum, and how it will store it. Once deployed, it will form a part of a global graph of blockchain data. + +![Define a Subgraph](/img/define-subgraph.png) + +The subgraph definition consists of a few files: + +- `subgraph.yaml`: a YAML file containing the subgraph manifest + +- `schema.graphql`: a GraphQL schema that defines what data is stored for your subgraph, and how to query it via GraphQL + +- `AssemblyScript Mappings`: [AssemblyScript](https://github.com/AssemblyScript/assemblyscript) code that translates from the event data to the entities defined in your schema (e.g. `mapping.ts` in this tutorial) + +Before you go into detail about the contents of the manifest file, you need to install the [Graph CLI](https://github.com/graphprotocol/graph-cli) which you will need to build and deploy a subgraph. + +## Install the Graph CLI + +The Graph CLI is written in JavaScript, and you will need to install either `yarn` or `npm` to use it; it is assumed that you have yarn in what follows. + +Once you have `yarn`, install the Graph CLI by running + +**Install with yarn:** + +```bash +yarn global add @graphprotocol/graph-cli +``` + +**Install with npm:** + +```bash +npm install -g @graphprotocol/graph-cli +``` diff --git a/pages/ko/developer/deprecating-a-subgraph.mdx b/pages/ko/developer/deprecating-a-subgraph.mdx new file mode 100644 index 000000000000..f8966e025c13 --- /dev/null +++ b/pages/ko/developer/deprecating-a-subgraph.mdx @@ -0,0 +1,17 @@ +--- +title: Deprecating a Subgraph +--- + +So you'd like to deprecate your subgraph on The Graph Explorer. You've come to the right place! Follow the steps below: + +1. Visit the contract address [here](https://etherscan.io/address/0xadca0dd4729c8ba3acf3e99f3a9f471ef37b6825#writeProxyContract) +2. Call 'deprecateSubgraph' with your own address as the first parameter +3. In the 'subgraphNumber' field, list 0 if it's the first subgraph you're publishing, 1 if it's your second, 2 if it's your third, etc. +4. Inputs for #2 and #3 can be found in your `` which is composed of the `{graphAccount}-{subgraphNumber}`. For example, the [Sushi Subgraph's](https://thegraph.com/explorer/subgraph?id=0x4bb4c1b0745ef7b4642feeccd0740dec417ca0a0-0&version=0x4bb4c1b0745ef7b4642feeccd0740dec417ca0a0-0-0&view=Overview) ID is `<0x4bb4c1b0745ef7b4642feeccd0740dec417ca0a0-0>`, which is a combination of `graphAccount` = `<0x4bb4c1b0745ef7b4642feeccd0740dec417ca0a0>` and `subgraphNumber` = `<0>` +5. Voila! Your subgraph will no longer show up on searches on The Graph Explorer. Please note the following: + +- Curators will not be able to signal on the subgraph anymore +- Curators that already signaled on the subgraph will be able to withdraw their signal at an average share price +- Deprecated subgraphs will be indicated with an error message. + +If you interacted with the now deprecated subgraph, you'll be able to find it in your user profile under the "Subgraphs", "Indexing", or "Curating" tab respectively. diff --git a/pages/ko/developer/developer-faq.mdx b/pages/ko/developer/developer-faq.mdx new file mode 100644 index 000000000000..41449c60e5ab --- /dev/null +++ b/pages/ko/developer/developer-faq.mdx @@ -0,0 +1,172 @@ +--- +title: Developer FAQs +--- + +### 1. Can I delete my subgraph? + +It is not possible to delete subgraphs once they are created. + +### 2. Can I change my subgraph name? + +No. Once a subgraph is created, the name cannot be changed. Make sure to think of this carefully before you create your subgraph so it is easily searchable and identifiable by other dapps. + +### 3. Can I change the GitHub account associated with my subgraph? + +No. Once a subgraph is created, the associated GitHub account cannot be changed. Make sure to think of this carefully before you create your subgraph. + +### 4. Am I still able to create a subgraph if my smart contracts don't have events? + +It is highly recommended that you structure your smart contracts to have events associated with data you are interested in querying. Event handlers in the subgraph are triggered by contract events, and are by far the fastest way to retrieve useful data. + +If the contracts you are working with do not contain events, your subgraph can use call and block handlers to trigger indexing. Although this is not recommended as performance will be significantly slower. + +### 5. Is it possible to deploy one subgraph with the same name for multiple networks? + +You will need separate names for multiple networks. While you can't have different subgraphs under the same name, there are convenient ways of having a single codebase for multiple networks. Find more on this in our documentation: [Redeploying a Subgraph](/hosted-service/deploy-subgraph-hosted#redeploying-a-subgraph) + +### 6. How are templates different from data sources? + +Templates allow you to create data sources on the fly, while your subgraph is indexing. It might be the case that your contract will spawn new contracts as people interact with it, and since you know the shape of those contracts (ABI, events, etc) up front you can define how you want to index them in a template and when they are spawned your subgraph will create a dynamic data source by supplying the contract address. + +Check out the "Instantiating a data source template" section on: [Data Source Templates](/developer/create-subgraph-hosted#data-source-templates). + +### 7. How do I make sure I'm using the latest version of graph-node for my local deployments? + +You can run the following command: + +```sh +docker pull graphprotocol/graph-node:latest +``` + +**NOTE:** docker / docker-compose will always use whatever graph-node version was pulled the first time you ran it, so it is important to do this to make sure you are up to date with the latest version of graph-node. + +### 8. How do I call a contract function or access a public state variable from my subgraph mappings? + +Take a look at `Access to smart contract` state inside the section [AssemblyScript API](/developer/assemblyscript-api). + +### 9. Is it possible to set up a subgraph using `graph init` from `graph-cli` with two contracts? Or should I manually add another datasource in `subgraph.yaml` after running `graph init`? + +Unfortunately this is currently not possible. `graph init` is intended as a basic starting point, from which you can then add more data sources manually. + +### 10. I want to contribute or add a GitHub issue, where can I find the open source repositories? + +- [graph-node](https://github.com/graphprotocol/graph-node) +- [graph-cli](https://github.com/graphprotocol/graph-cli) +- [graph-ts](https://github.com/graphprotocol/graph-ts) + +### 11. What is the recommended way to build "autogenerated" ids for an entity when handling events? + +If only one entity is created during the event and if there's nothing better available, then the transaction hash + log index would be unique. You can obfuscate these by converting that to Bytes and then piping it through `crypto.keccak256` but this won't make it more unique. + +### 12. When listening to multiple contracts, is it possible to select the contract order to listen to events? + +Within a subgraph, the events are always processed in the order they appear in the blocks, regardless of whether that is across multiple contracts or not. + +### 13. Is it possible to differentiate between networks (mainnet, Kovan, Ropsten, local) from within event handlers? + +Yes. You can do this by importing `graph-ts` as per the example below: + +```javascript +import { dataSource } from '@graphprotocol/graph-ts' + +dataSource.network() +dataSource.address() +``` + +### 14. Do you support block and call handlers on Rinkeby? + +On Rinkeby we support block handlers, but without `filter: call`. Call handlers are not supported for the time being. + +### 15. Can I import ethers.js or other JS libraries into my subgraph mappings? + +Not currently, as mappings are written in AssemblyScript. One possible alternative solution to this is to store raw data in entities and perform logic that requires JS libraries on the client. + +### 16. Is it possible to specifying what block to start indexing on? + +Yes. `dataSources.source.startBlock` in the `subgraph.yaml` file specifies the 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: Start blocks + +### 17. Are there some tips to increase performance of indexing? My subgraph is taking a very long time to sync. + +Yes, you should take a look at the optional start block feature to start indexing from the block that the contract was deployed: [Start blocks](/developer/create-subgraph-hosted#start-blocks) + +### 18. Is there a way to query the subgraph directly to determine what the latest block number it has indexed? + +Yes! Try the following command, substituting "organization/subgraphName" with the organization under it is published and the name of your subgraph: + +```sh +curl -X POST -d '{ "query": "{indexingStatusForCurrentVersion(subgraphName: \"organization/subgraphName\") { chains { latestBlock { hash number }}}}"}' https://api.thegraph.com/index-node/graphql +``` + +### 19. What networks are supported by The Graph? + +The graph-node supports any EVM-compatible JSON RPC API chain. + +The Graph Network supports subgraphs indexing mainnet Ethereum: + +- `mainnet` + +In the Hosted Service, the following networks are supported: + +- Ethereum mainnet +- Kovan +- Rinkeby +- Ropsten +- Goerli +- PoA-Core +- PoA-Sokol +- xDAI +- NEAR +- NEAR testnet +- Matic +- Mumbai +- Fantom +- Binance Smart Chain +- Clover +- Avalanche +- Fuji +- Celo +- Celo-Alfajores +- Fuse +- Moonbeam +- Arbitrum One +- Arbitrum Testnet (on Rinkeby) +- Optimism +- Optimism Testnet (on Kovan) + +There is work in progress towards integrating other blockchains, you can read more in our repo: [RFC-0003: Multi-Blockchain Support](https://github.com/graphprotocol/rfcs/pull/8/files). + +### 20. Is it possible to duplicate a subgraph to another account or endpoint without redeploying? + +You have to redeploy the subgraph, but if the subgraph ID (IPFS hash) doesn't change, it won't have to sync from the beginning. + +### 21. Is this possible to use Apollo Federation on top of graph-node? + +Federation is not supported yet, although we do want to support it in the future. At the moment, something you can do is use schema stitching, either on the client or via a proxy service. + +### 22. Is there a limit to how many objects The Graph can return per query? + +By default query responses are limited to 100 items per collection. If you want to receive more, you can go up to 1000 items per collection and beyond that you can paginate with: + +```graphql +someCollection(first: 1000, skip: ) { ... } +``` + +### 23. If my dapp frontend uses The Graph for querying, do I need to write my query key into the frontend directly? What if we pay query fees for users – will malicious users cause our query fees to be very high? + +Currently, the recommended approach for a dapp is to add the key to the frontend and expose it to end users. That said, you can limit that key to a host name, like _yourdapp.io_ and subgraph. The gateway is currently being run by Edge & Node. Part of the responsibility of a gateway is to monitor for abusive behavior and block traffic from malicious clients. + +### 24. Where do I go to find my current subgraph on the Hosted Service? + +Head over to the Hosted Service in order to find subgraphs that you or others deployed to the Hosted Service. You can find it [here.](https://thegraph.com/hosted-service) + +### 25. Will the Hosted Service start charging query fees? + +The Graph will never charge for the Hosted Service. The Graph is a decentralized protocol, and charging for a centralized service is not aligned with The Graph’s values. The Hosted Service was always a temporary step to help get to the decentralized network. Developers will have a sufficient amount of time to migrate to the decentralized network as they are comfortable. + +### 26. When will the Hosted Service be shut down? + +If and when there are plans to do this, the community will be notified well ahead of time with considerations made for any subgraphs built on the Hosted Service. + +### 27. How do I upgrade a subgraph on mainnet? + +If you’re a subgraph developer, you can upgrade a new version of your subgraph to the Studio using the CLI. It’ll be private at that point but if you’re happy with it, you can publish to the decentralized Graph Explorer. This will create a new version of your subgraph that Curators can start signaling on. diff --git a/pages/ko/developer/distributed-systems.mdx b/pages/ko/developer/distributed-systems.mdx new file mode 100644 index 000000000000..894fcbe2e18b --- /dev/null +++ b/pages/ko/developer/distributed-systems.mdx @@ -0,0 +1,132 @@ +--- +title: Distributed Systems +--- + +The Graph is a protocol implemented as a distributed system. + +Connections fail. Requests arrive out of order. Different computers with out-of-sync clocks and states process related requests. Servers restart. Re-orgs happen between requests. These problems are inherent to all distributed systems but are exacerbated in systems operating at a global scale. + +Consider this example of what may occur if a client polls an Indexer for the latest data during a re-org. + +1. Indexer ingests block 8 +2. Request served to the client for block 8 +3. Indexer ingests block 9 +4. Indexer ingests block 10A +5. Request served to the client for block 10A +6. Indexer detects reorg to 10B and rolls back 10A +7. Request served to the client for block 9 +8. Indexer ingests block 10B +9. Indexer ingests block 11 +10. Request served to the client for block 11 + +From the point of view of the Indexer, things are progressing forward logically. Time is moving forward, though we did have to roll back an uncle block and play the block under consensus forward on top of it. Along the way, the Indexer serves requests using the latest state it knows about at that time. + +From the point of view of the client, however, things appear chaotic. The client observes that the responses were for blocks 8, 10, 9, and 11 in that order. We call this the "block wobble" problem. When a client experiences block wobble, data may appear to contradict itself over time. The situation worsens when we consider that Indexers do not all ingest the latest blocks simultaneously, and your requests may be routed to multiple Indexers. + +It is the responsibility of the client and server to work together to provide consistent data to the user. Different approaches must be used depending on the desired consistency as there is no one right program for every problem. + +Reasoning through the implications of distributed systems is hard, but the fix may not be! We've established APIs and patterns to help you navigate some common use-cases. The following examples illustrate those patterns but still elide details required by production code (like error handling and cancellation) to not obfuscate the main ideas. + +## Polling for updated data + +The Graph provides the `block: { number_gte: $minBlock }` API, which ensures that the response is for a single block equal or higher to `$minBlock`. If the request is made to a `graph-node` instance and the min block is not yet synced, `graph-node` will return an error. If `graph-node` has synced min block, it will run the response for the latest block. If the request is made to an Edge & Node Gateway, the Gateway will filter out any Indexers that have not yet synced min block and make the request for the latest block the Indexer has synced. + +We can use `number_gte` to ensure that time never travels backward when polling for data in a loop. Here is an example: + +```javascript +/// Updates the protocol.paused variable to the latest +/// known value in a loop by fetching it using The Graph. +async function updateProtocolPaused() { + // It's ok to start with minBlock at 0. The query will be served + // using the latest block available. Setting minBlock to 0 is the + // same as leaving out that argument. + let minBlock = 0 + + for (;;) { + // Schedule a promise that will be ready once + // the next Ethereum block will likely be available. + const nextBlock = new Promise((f) => { + setTimeout(f, 14000) + }) + + const query = ` + { + protocol(block: { number_gte: ${minBlock} } id: "0") { + paused + } + _meta { + block { + number + } + } + }` + + const response = await graphql(query) + minBlock = response._meta.block.number + + // TODO: Do something with the response data here instead of logging it. + console.log(response.protocol.paused) + + // Sleep to wait for the next block + await nextBlock + } +} +``` + +## Fetching a set of related items + +Another use-case is retrieving a large set or, more generally, retrieving related items across multiple requests. Unlike the polling case (where the desired consistency was to move forward in time), the desired consistency is for a single point in time. + +Here we will use the `block: { hash: $blockHash }` argument to pin all of our results to the same block. + +```javascript +/// Gets a list of domain names from a single block using pagination +async function getDomainNames() { + // Set a cap on the maximum number of items to pull. + let pages = 5 + const perPage = 1000 + + // The first query will get the first page of results and also get the block + // hash so that the remainder of the queries are consistent with the first. + let query = ` + { + domains(first: ${perPage}) { + name + id + } + _meta { + block { + hash + } + } + }` + + let data = await graphql(query) + let result = data.domains.map((d) => d.name) + let blockHash = data._meta.block.hash + + // Continue fetching additional pages until either we run into the limit of + // 5 pages total (specified above) or we know we have reached the last page + // because the page has fewer entities than a full page. + while (data.domains.length == perPage && --pages) { + let lastID = data.domains[data.domains.length - 1].id + query = ` + { + domains(first: ${perPage}, where: { id_gt: "${lastID}" }, block: { hash: "${blockHash}" }) { + name + id + } + }` + + data = await graphql(query) + + // Accumulate domain names into the result + for (domain of data.domains) { + result.push(domain.name) + } + } + return result +} +``` + +Note that in case of a re-org, the client will need to retry from the first request to update the block hash to a non-uncle block. diff --git a/pages/ko/developer/graphql-api.mdx b/pages/ko/developer/graphql-api.mdx new file mode 100644 index 000000000000..f9cb6214fcd9 --- /dev/null +++ b/pages/ko/developer/graphql-api.mdx @@ -0,0 +1,267 @@ +--- +title: GraphQL API +--- + +This guide explains the GraphQL Query API that is used for the Graph Protocol. + +## Queries + +In your subgraph schema you define types called `Entities`. For each `Entity` type, an `entity` and `entities` field will be generated on the top-level `Query` type. Note that `query` does not need to be included at the top of the `graphql` query when using The Graph. + +#### Examples + +Query for a single `Token` entity defined in your schema: + +```graphql +{ + token(id: "1") { + id + owner + } +} +``` + +**Note:** When querying for a single entity, the `id` field is required and it must be a string. + +Query all `Token` entities: + +```graphql +{ + tokens { + id + owner + } +} +``` + +### Sorting + +When querying a collection, the `orderBy` parameter may be used to sort by a specific attribute. Additionally, the `orderDirection` can be used to specify the sort direction, `asc` for ascending or `desc` for descending. + +#### Example + +```graphql +{ + tokens(orderBy: price, orderDirection: asc) { + id + owner + } +} +``` + +### Pagination + +When querying a collection, the `first` parameter can be used to paginate from the beginning of the collection. It is worth noting that the default sort order is by ID in ascending alphanumeric order, not by creation time. + +Further, the `skip` parameter can be used to skip entities and paginate. e.g. `first:100` shows the first 100 entities and `first:100, skip:100` shows the next 100 entities. + +Queries should avoid using very large `skip` values since they generally perform poorly. For retrieving a large number of items, it is much better to page through entities based on an attribute as shown in the last example. + +#### Example + +Query the first 10 tokens: + +```graphql +{ + tokens(first: 10) { + id + owner + } +} +``` + +To query for groups of entities in the middle of a collection, the `skip` parameter may be used in conjunction with the `first` parameter to skip a specified number of entities starting at the beginning of the collection. + +#### Example + +Query 10 `Token` entities, offset by 10 places from the beginning of the collection: + +```graphql +{ + tokens(first: 10, skip: 10) { + id + owner + } +} +``` + +#### Example + +If a client needs to retrieve a large number of entities, it is much more performant to base queries on an attribute and filter by that attribute. For example, a client would retrieve a large number of tokens using this query: + +```graphql +{ + query manyTokens($lastID: String) { + tokens(first: 1000, where: { id_gt: $lastID }) { + id + owner + } + } +} +``` + +The first time, it would send the query with `lastID = ""`, and for subsequent requests would set `lastID` to the `id` attribute of the last entity in the previous request. This approach will perform significantly better than using increasing `skip` values. + +### Filtering + +You can use the `where` parameter in your queries to filter for different properties. You can filter on mulltiple values within the `where` parameter. + +#### Example + +Query challenges with `failed` outcome: + +```graphql +{ + challenges(where: { outcome: "failed" }) { + challenger + outcome + application { + id + } + } +} +``` + +You can use suffixes like `_gt`, `_lte` for value comparison: + +#### Example + +```graphql +{ + applications(where: { deposit_gt: "10000000000" }) { + id + whitelisted + deposit + } +} +``` + +Full list of parameter suffixes: + +```graphql +_not +_gt +_lt +_gte +_lte +_in +_not_in +_contains +_not_contains +_starts_with +_ends_with +_not_starts_with +_not_ends_with +``` + +Please note that some suffixes are only supported for specific types. For example, `Boolean` only supports `_not`, `_in`, and `_not_in`. + +### Time-travel queries + +You can query the state of your entities not just for the latest block, which is the by default, but also for an arbitrary block in the past. The block at which a query should happen can be specified either by its block number or its block hash by including a `block` argument in the toplevel fields of queries. + +The result of such a query will not change over time, i.e., querying at a certain past block will return the same result no matter when it is executed, with the exception that if you query at a block very close to the head of the Ethereum chain, the result might change if that block turns out to not be on the main chain and the chain gets reorganized. Once a block can be considered final, the result of the query will not change. + +Note that the current implementation is still subject to certain limitations that might violate these gurantees. The implementation can not always tell that a given block hash is not on the main chain at all, or that the result of a query by block hash for a block that can not be considered final yet might be influenced by a block reorganization running concurrently with the query. They do not affect the results of queries by block hash when the block is final and known to be on the main chain. [This issue](https://github.com/graphprotocol/graph-node/issues/1405) explains what these limitations are in detail. + +#### Example + +```graphql +{ + challenges(block: { number: 8000000 }) { + challenger + outcome + application { + id + } + } +} +``` + +This query will return `Challenge` entities, and their associated `Application` entities, as they existed directly after processing block number 8,000,000. + +#### Example + +```graphql +{ + challenges(block: { hash: "0x5a0b54d5dc17e0aadc383d2db43b0a0d3e029c4c" }) { + challenger + outcome + application { + id + } + } +} +``` + +This query will return `Challenge` entities, and their associated `Application` entities, as they existed directly after processing the block with the given hash. + +### Fulltext Search Queries + +Fulltext search query fields provide an expressive text search API that can be added to the subgraph schema and customized. Refer to [Defining Fulltext Search Fields](/developer/create-subgraph-hosted#defining-fulltext-search-fields) to add fulltext search to your subgraph. + +Fulltext search queries have one required field, `text`, for supplying search terms. Several special fulltext operators are available to be used in this `text` search field. + +Fulltext search operators: + +| Symbol | Operator | Description | +| ----------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------ | +| `&` | `And` | For combining multiple search terms into a filter for entities that include all of the provided terms | +| | | `Or` | Queries with multiple search terms separated by the or operator will return all entities with a match from any of the provided terms | +| `<->` | `Follow by` | Specify the distance between two words. | +| `:*` | `Prefix` | Use the prefix search term to find words whose prefix match (2 characters required.) | + +#### Examples + +Using the `or` operator, this query will filter to blog entities with variations of either "anarchism" or "crumpet" in their fulltext fields. + +```graphql +{ + blogSearch(text: "anarchism | crumpets") { + id + title + body + author + } +} +``` + +The `follow by` operator specifies a words a specific distance apart in the fulltext documents. The following query will return all blogs with variations of "decentralize" followed by "philosophy" + +```graphql +{ + blogSearch(text: "decentralized <-> philosophy") { + id + title + body + author + } +} +``` + +Combine fulltext operators to make more complex filters. With a pretext search operator combined with a follow by this example query will match all blog entities with words that start with "lou" followed by "music". + +```graphql +{ + blogSearch(text: "lou:* <-> music") { + id + title + body + author + } +} +``` + +## Schema + +The schema of your data source--that is, the entity types, values, and relationships that are available to query--are defined through the [GraphQL Interface Definition Langauge (IDL)](https://facebook.github.io/graphql/draft/#sec-Type-System). + +GraphQL schemas generally define root types for `queries`, `subscriptions` and `mutations`. The Graph only supports `queries`. The root `Query` type for your subgraph is automatically generated from the GraphQL schema that's included in your subgraph manifest. + +> **Note:** Our API does not expose mutations because developers are expected to issue transactions directly against the underlying blockchain from their applications. + +### Entities + +All GraphQL types with `@entity` directives in your schema will be treated as entities and must have an `ID` field. + +> **Note:** Currently, all types in your schema must have an `@entity` directive. In the future, we will treat types without an `@entity` directive as value objects, but this is not yet supported. diff --git a/pages/ko/developer/matchstick.mdx b/pages/ko/developer/matchstick.mdx new file mode 100644 index 000000000000..3cf1ec761bb9 --- /dev/null +++ b/pages/ko/developer/matchstick.mdx @@ -0,0 +1,267 @@ +--- +title: Unit Testing Framework +--- + +Matchstick is a unit testing framework, developed by [LimeChain](https://limechain.tech/), that enables subgraph developers to test their mapping logic in a sandboxed environment and deploy their subgraphs with confidence! + +Follow the [Matchstick installation guide](https://github.com/LimeChain/matchstick/blob/main/README.md#quick-start-) to install. Now, you can move on to writing your first unit test. + +## Write a Unit Test + +Let's see how a simple unit test would look like, using the Gravatar [Example Subgraph](https://github.com/graphprotocol/example-subgraph). + +Assuming we have the following handler function (along with two helper functions to make our life easier): + +```javascript +export function handleNewGravatar(event: NewGravatar): void { + let gravatar = new Gravatar(event.params.id.toHex()) + gravatar.owner = event.params.owner + gravatar.displayName = event.params.displayName + gravatar.imageUrl = event.params.imageUrl + gravatar.save() +} + +export function handleNewGravatars(events: NewGravatar[]): void { + events.forEach((event) => { + handleNewGravatar(event) + }) +} + +export function createNewGravatarEvent( + id: i32, + ownerAddress: string, + displayName: string, + imageUrl: string +): NewGravatar { + let mockEvent = newMockEvent() + let newGravatarEvent = new NewGravatar( + mockEvent.address, + mockEvent.logIndex, + mockEvent.transactionLogIndex, + mockEvent.logType, + mockEvent.block, + mockEvent.transaction, + mockEvent.parameters + ) + newGravatarEvent.parameters = new Array() + let idParam = new ethereum.EventParam('id', ethereum.Value.fromI32(id)) + let addressParam = new ethereum.EventParam( + 'ownderAddress', + ethereum.Value.fromAddress(Address.fromString(ownerAddress)) + ) + let displayNameParam = new ethereum.EventParam('displayName', ethereum.Value.fromString(displayName)) + let imageUrlParam = new ethereum.EventParam('imageUrl', ethereum.Value.fromString(imageUrl)) + + newGravatarEvent.parameters.push(idParam) + newGravatarEvent.parameters.push(addressParam) + newGravatarEvent.parameters.push(displayNameParam) + newGravatarEvent.parameters.push(imageUrlParam) + + return newGravatarEvent +} +``` + +We first have to create a test file in our project. We have chosen the name `gravity.test.ts`. In the newly created file we need to define a function named `runTests()`. It is important that the function has that exact name. This is an example of how our tests might look like: + +```typescript +import { clearStore, test, assert } from 'matchstick-as/assembly/index' +import { Gravatar } from '../../generated/schema' +import { NewGravatar } from '../../generated/Gravity/Gravity' +import { createNewGravatarEvent, handleNewGravatars } from '../mappings/gravity' + +export function runTests(): void { + test('Can call mappings with custom events', () => { + // Initialise + let gravatar = new Gravatar('gravatarId0') + gravatar.save() + + // Call mappings + let newGravatarEvent = createNewGravatarEvent(12345, '0x89205A3A3b2A69De6Dbf7f01ED13B2108B2c43e7', 'cap', 'pac') + + let anotherGravatarEvent = createNewGravatarEvent(3546, '0x89205A3A3b2A69De6Dbf7f01ED13B2108B2c43e7', 'cap', 'pac') + + handleNewGravatars([newGravatarEvent, anotherGravatarEvent]) + + assert.fieldEquals('Gravatar', 'gravatarId0', 'id', 'gravatarId0') + assert.fieldEquals('Gravatar', '12345', 'owner', '0x89205A3A3b2A69De6Dbf7f01ED13B2108B2c43e7') + assert.fieldEquals('Gravatar', '3546', 'displayName', 'cap') + + clearStore() + }) + + test('Next test', () => { + //... + }) +} +``` + +That's a lot to unpack! First off, an important thing to notice is that we're importing things from `matchstick-as`, our AssemblyScript helper library (distributed as an npm module). You can find the repository [here](https://github.com/LimeChain/matchstick-as). `matchstick-as` provides us with useful testing methods and also defines the `test()` function which we will use to build our test blocks. The rest of it is pretty straightforward - here's what happens: + +- We're setting up our initial state and adding one custom Gravatar entity; +- We define two `NewGravatar` event objects along with their data, using the `createNewGravatarEvent()` function; +- We're calling out handler methods for those events - `handleNewGravatars()` and passing in the list of our custom events; +- We assert the state of the store. How does that work? - We're passing a unique combination of Entity type and id. Then we check a specific field on that Entity and assert that it has the value we expect it to have. We're doing this both for the initial Gravatar Entity we added to the store, as well as the two Gravatar entities that gets added when the handler function is called; +- And lastly - we're cleaning the store using `clearStore()` so that our next test can start with a fresh and empty store object. We can define as many test blocks as we want. + +There we go - we've created our first test! 👏 + +❗ **IMPORTANT:** _In order for the tests to work, we need to export the `runTests()` function in our mappings file. It won't be used there, but the export statement has to be there so that it can get picked up by Rust later when running the tests._ + +You can export the tests wrapper function in your mappings file like this: + +``` +export { runTests } from "../tests/gravity.test.ts"; +``` + +❗ **IMPORTANT:** _Currently there's an issue with using Matchstick when deploying your subgraph. Please only use Matchstick for local testing, and remove/comment out this line (`export { runTests } from "../tests/gravity.test.ts"`) once you're done. We expect to resolve this issue shortly, sorry for the inconvenience!_ + +_If you don't remove that line, you will get the following error message when attempting to deploy your subgraph:_ + +``` +/... +Mapping terminated before handling trigger: oneshot canceled +.../ +``` + +Now in order to run our tests you simply need to run the following in your subgraph root folder: + +`graph test Gravity` + +And if all goes well you should be greeted with the following: + +![Matchstick saying “All tests passed!”](/img/matchstick-tests-passed.png) + +## Common test scenarios + +### Hydrating the store with a certain state + +Users are able to hydrate the store with a known set of entities. Here's an example to initialise the store with a Gravatar entity: + +```typescript +let gravatar = new Gravatar('entryId') +gravatar.save() +``` + +### Calling a mapping function with an event + +A user can create a custom event and pass it to a mapping function that is bound to the store: + +```typescript +import { store } from 'matchstick-as/assembly/store' +import { NewGravatar } from '../../generated/Gravity/Gravity' +import { handleNewGravatars, createNewGravatarEvent } from './mapping' + +let newGravatarEvent = createNewGravatarEvent(12345, '0x89205A3A3b2A69De6Dbf7f01ED13B2108B2c43e7', 'cap', 'pac') + +handleNewGravatar(newGravatarEvent) +``` + +### Calling all of the mappings with event fixtures + +Users can call the mappings with test fixtures. + +```typescript +import { NewGravatar } from '../../generated/Gravity/Gravity' +import { store } from 'matchstick-as/assembly/store' +import { handleNewGravatars, createNewGravatarEvent } from './mapping' + +let newGravatarEvent = createNewGravatarEvent(12345, '0x89205A3A3b2A69De6Dbf7f01ED13B2108B2c43e7', 'cap', 'pac') + +let anotherGravatarEvent = createNewGravatarEvent(3546, '0x89205A3A3b2A69De6Dbf7f01ED13B2108B2c43e7', 'cap', 'pac') + +handleNewGravatars([newGravatarEvent, anotherGravatarEvent]) +``` + +``` +export function handleNewGravatars(events: NewGravatar[]): void { + events.forEach(event => { + handleNewGravatar(event); + }); +} +``` + +### Mocking contract calls + +Users can mock contract calls: + +```typescript +import { addMetadata, assert, createMockedFunction, clearStore, test } from 'matchstick-as/assembly/index' +import { Gravity } from '../../generated/Gravity/Gravity' +import { Address, BigInt, ethereum } from '@graphprotocol/graph-ts' + +let contractAddress = Address.fromString('0x89205A3A3b2A69De6Dbf7f01ED13B2108B2c43e7') +let expectedResult = Address.fromString('0x90cBa2Bbb19ecc291A12066Fd8329D65FA1f1947') +let bigIntParam = BigInt.fromString('1234') +createMockedFunction(contractAddress, 'gravatarToOwner', 'gravatarToOwner(uint256):(address)') + .withArgs([ethereum.Value.fromSignedBigInt(bigIntParam)]) + .returns([ethereum.Value.fromAddress(Address.fromString('0x90cBa2Bbb19ecc291A12066Fd8329D65FA1f1947'))]) + +let gravity = Gravity.bind(contractAddress) +let result = gravity.gravatarToOwner(bigIntParam) + +assert.equals(ethereum.Value.fromAddress(expectedResult), ethereum.Value.fromAddress(result)) +``` + +As demonstrated, in order to mock a contract call and hardcore a return value, the user must provide a contract address, function name, function signature, an array of arguments, and of course - the return value. + +Users can also mock function reverts: + +```typescript +let contractAddress = Address.fromString('0x89205A3A3b2A69De6Dbf7f01ED13B2108B2c43e7') +createMockedFunction(contractAddress, 'getGravatar', 'getGravatar(address):(string,string)') + .withArgs([ethereum.Value.fromAddress(contractAddress)]) + .reverts() +``` + +### Asserting the state of the store + +Users are able to assert the final (or midway) state of the store through asserting entities. In order to do this, the user has to supply an Entity type, the specific ID of an Entity, a name of a field on that Entity, and the expected value of the field. Here's a quick example: + +```typescript +import { assert } from 'matchstick-as/assembly/index' +import { Gravatar } from '../generated/schema' + +let gravatar = new Gravatar('gravatarId0') +gravatar.save() + +assert.fieldEquals('Gravatar', 'gravatarId0', 'id', 'gravatarId0') +``` + +Running the assert.fieldEquals() function will check for equality of the given field against the given expected value. The test will fail and an error message will be outputted if the values are **NOT** equal. Otherwise the test will pass successfully. + +### Interacting with Event metadata + +Users can use default transaction metadata, which could be returned as an ethereum.Event by using the `newMockEvent()` function. The following example shows how you can read/write to those fields on the Event object: + +```typescript +// Read +let logType = newGravatarEvent.logType + +// Write +let UPDATED_ADDRESS = '0xB16081F360e3847006dB660bae1c6d1b2e17eC2A' +newGravatarEvent.address = Address.fromString(UPDATED_ADDRESS) +``` + +### Asserting variable equality + +```typescript +assert.equals(ethereum.Value.fromString("hello"); ethereum.Value.fromString("hello")); +``` + +### Asserting that an Entity is **not** in the store + +Users can assert that an entity does not exist in the store. The function takes an entity type and an id. If the entity is in fact in the store, the test will fail with a relevant error message. Here's a quick example of how to use this functionality: + +```typescript +assert.notInStore('Gravatar', '23') +``` + +### Test run time duration in the log output + +The log output includes the test run duration. Here's an example: + +`Jul 09 14:54:42.420 INFO Program execution time: 10.06022ms` + +## Feedback + +If you have any questions, feedback, feature requests or just want to reach out, the best place would be The Graph Discord where we have a dedicated channel for Matchstick, called 🔥| unit-testing. diff --git a/pages/ko/developer/publish-subgraph.mdx b/pages/ko/developer/publish-subgraph.mdx new file mode 100644 index 000000000000..2f35f5eb1bae --- /dev/null +++ b/pages/ko/developer/publish-subgraph.mdx @@ -0,0 +1,27 @@ +--- +title: Publish a Subgraph to the Decentralized Network +--- + +Once your subgraph has been [deployed to the Subgraph Studio](/studio/deploy-subgraph-studio), you have tested it out, and are ready to put it into production, you can then publish it to the decentralized network. + +Publishing a Subgraph to the decentralized network makes it available for [curators](/curating) to begin curating on it, and [indexers](/indexing) to begin indexing it. + +For a walkthrough of how to publish a subgraph to the decentralized network, see [this video](https://youtu.be/HfDgC2oNnwo?t=580). + +### Networks + +The decentralized network currently supports both Rinkeby and Ethereum Mainnet. + +### Publishing a subgraph + +Subgraphs can be published to the decentralized network directly from the Subgraph Studio dashboard by clicking on the **Publish** button. Once a subgraph is published, it will be available to view in the [Graph Explorer](https://thegraph.com/explorer/). + +- Subgraphs published to Rinkeby can index and query data from either the Rinkeby network or Ethereum Mainnet. + +- Subgraphs published to Ethereum Mainnet can only index and query data from Ethereum Mainnet, meaning that you cannot publish subgraphs to the main decentralized network that index and query testnet data. + +- When publishing a new version for an existing subgraph the same rules apply as above. + +### Updating metadata for a published subgraph + +Once your subgraph has been published to the decentralized network, you can modify the metadata at any time by making the update in the Subgraph Studio dashboard of the subgraph. After saving the changes and publishing your updates to the network, they will be reflected in the Graph Explorer. This won’t create a new version, as your deployment hasn’t changed. diff --git a/pages/ko/developer/query-the-graph.mdx b/pages/ko/developer/query-the-graph.mdx new file mode 100644 index 000000000000..ae480b1e6883 --- /dev/null +++ b/pages/ko/developer/query-the-graph.mdx @@ -0,0 +1,32 @@ +--- +title: Query The Graph +--- + +With the subgraph deployed, visit the [Graph Explorer](https://thegraph.com/explorer) to open up a [GraphiQL](https://github.com/graphql/graphiql) interface where you can explore the deployed GraphQL API for the subgraph by issuing queries and viewing the schema. + +An example is provided below, but please see the [Query API](/developer/graphql-api) for a complete reference on how to query the subgraph's entities. + +#### Example + +This query lists all the counters our mapping has created. Since we only create one, the result will only contain our one `default-counter`: + +```graphql +{ + counters { + id + value + } +} +``` + +## Using The Graph Explorer + +Each subgraph published to the decentralized Graph Explorer has a unique query URL that you can find by navigating to the subgraph details page and clicking on the "Query" button on the top right corner. This will open a side pane that will give you the unique query URL of the subgraph as well as some instructions about how to query it. + +![Query Subgraph Pane](/img/query-subgraph-pane.png) + +As you can notice, this query URL must use a unique API key. You can create and manage your API keys in the [Subgraph Studio](https://thegraph.com/studio) in the "API Keys" section. Learn more about how to use Subgraph Studio [here](/studio/subgraph-studio). + +Querying subgraphs using your API keys will generate query fees that will be paid in GRT. You can learn more about billing [here](/studio/billing). + +You can also use the GraphQL playground in the "Playground" tab to query a subgraph within The Graph Explorer. diff --git a/pages/ko/developer/querying-from-your-app.mdx b/pages/ko/developer/querying-from-your-app.mdx new file mode 100644 index 000000000000..c09c44efee72 --- /dev/null +++ b/pages/ko/developer/querying-from-your-app.mdx @@ -0,0 +1,136 @@ +--- +title: Querying from an Application +--- + +Once a subgraph is deployed to the Subgraph Studio or to the Graph Explorer, you will be given the endpoint for your GraphQL API that should look something like this: + +**Subgraph Studio (testing endpoint)** + +```sh +Queries (HTTP) +https://api.studio.thegraph.com/query/// +``` + +**Graph Explorer** + +```sh +Queries (HTTP) +https://gateway.thegraph.com/api//subgraphs/id/ +``` + +Using the GraphQL endpoint, you can use various GraphQL Client libraries to query the subgraph and populate your app with the data indexed by the subgraph. + +Here are a couple of the more popular GraphQL clients in the ecosystem and how to use them: + +### Apollo client + +[Apollo client](https://www.apollographql.com/docs/) supports web projects including frameworks like React and Vue, as well as mobile clients like iOS, Android, and React Native. + +Let's look at how fetch data from a subgraph with Apollo client in a web project. + +First, install `@apollo/client` and `graphql`: + +```sh +npm install @apollo/client graphql +``` + +Then you can query the API with the following code: + +```javascript +import { ApolloClient, InMemoryCache, gql } from '@apollo/client' + +const APIURL = 'https://api.studio.thegraph.com/query///' + +const tokensQuery = ` + query { + tokens { + id + tokenID + contentURI + metadataURI + } + } +` + +const client = new ApolloClient({ + uri: APIURL, + cache: new InMemoryCache(), +}) + +client + .query({ + query: gql(tokensQuery), + }) + .then((data) => console.log('Subgraph data: ', data)) + .catch((err) => { + console.log('Error fetching data: ', err) + }) +``` + +To use variables, you can pass in a `variables` argument to the query: + +```javascript +const tokensQuery = ` + query($first: Int, $orderBy: BigInt, $orderDirection: String) { + tokens( + first: $first, orderBy: $orderBy, orderDirection: $orderDirection + ) { + id + tokenID + contentURI + metadataURI + } + } +` + +client + .query({ + query: gql(tokensQuery), + variables: { + first: 10, + orderBy: 'createdAtTimestamp', + orderDirection: 'desc', + }, + }) + .then((data) => console.log('Subgraph data: ', data)) + .catch((err) => { + console.log('Error fetching data: ', err) + }) +``` + +### URQL + +Another option is [URQL](https://formidable.com/open-source/urql/), a somewhat lighter weight GraphQL client library. + +Let's look at how fetch data from a subgraph with URQL in a web project. + +First, install `urql` and `graphql`: + +```sh +npm install urql graphql +``` + +Then you can query the API with the following code: + +```javascript +import { createClient } from 'urql' + +const APIURL = 'https://api.thegraph.com/subgraphs/name/username/subgraphname' + +const tokensQuery = ` + query { + tokens { + id + tokenID + contentURI + metadataURI + } + } +` + +const client = createClient({ + url: APIURL, +}) + +const data = await client.query(tokensQuery).toPromise() +``` diff --git a/pages/ko/developer/quick-start.mdx b/pages/ko/developer/quick-start.mdx new file mode 100644 index 000000000000..6893d424ddc2 --- /dev/null +++ b/pages/ko/developer/quick-start.mdx @@ -0,0 +1,227 @@ +--- +title: Quick Start +--- + +This guide will quickly take you through how to initialize, create, and deploy your subgraph on: + +- **Subgraph Studio** - used only for subgraphs that index **Ethereum mainnet** +- **Hosted Service** - used for subgraphs that index **other networks** outside of Ethereum mainnnet (e.g. Binance, Matic, etc) + +## Subgraph Studio + +### 1. Install the Graph CLI + +The Graph CLI is written in JavaScript and you will need to have either `npm` or `yarn` installed to use it. + +```sh +# NPM +$ npm install -g @graphprotocol/graph-cli + +# Yarn +$ yarn global add @graphprotocol/graph-cli +``` + +### 2. Initialize your Subgraph + +- Initialize your subgraph from an existing contract. + +```sh +graph init --studio +``` + +- Your subgraph slug is an identifier for your subgraph. The CLI tool will walk you through the steps for creating a subgraph, such as contract address, network, etc as you can see in the screenshot below. + +![Subgraph command](/img/Subgraph-Slug.png) + +### 3. Write your Subgraph + +The previous commands creates a scaffold subgraph that you can use as a starting point for building your subgraph. When making changes to the subgraph, you will mainly work with three files: + +- Manifest (subgraph.yaml) - The manifest defines what datasources your subgraphs will index. +- Schema (schema.graphql) - The GraphQL schema defines what data you wish to retreive from the subgraph. +- AssemblyScript Mappings (mapping.ts) - This is the code that translates data from your datasources to the entities defined in the schema. + +For more information on how to write your subgraph, see [Create a Subgraph](/developer/create-subgraph-hosted). + +### 4. Deploy to the Subgraph Studio + +- Go to the Subgraph Studio [https://thegraph.com/studio/](https://thegraph.com/studio/) and connect your wallet. +- Click "Create" and enter the subgraph slug you used in step 2. +- Run these commands in the subgraph folder + +```sh +$ graph codegen +$ graph build +``` + +- Authenticate and deploy your subgraph. The deploy key can be found on the Subgraph page in Subgraph Studio. + +```sh +$ graph auth --studio +$ graph deploy --studio +``` + +- You will be asked for a version label. It's strongly recommended to use the following conventions for naming your versions. Example: `0.0.1`, `v1`, `version1` + +### 5. Check your logs + +The logs should tell you if there are any errors. If your subgraph is failing, you can query the subgraph health by using the [GraphiQL Playground](https://graphiql-online.com/). Use [this endpoint](https://api.thegraph.com/index-node/graphql). Note that you can leverage the query below and input your deployment ID for your subgraph. In this case, `Qm...` is the deployment ID (which can be located on the Subgraph page under **Details**). The query below will tell you when a subgraph fails so you can debug accordingly: + +```sh +{ + indexingStatuses(subgraphs: ["Qm..."]) { + node + synced + health + fatalError { + message + block { + number + hash + } + handler + } + nonFatalErrors { + message + block { + number + hash + } + handler + } + chains { + network + chainHeadBlock { + number + } + earliestBlock { + number + } + latestBlock { + number + } + lastHealthyBlock { + number + } + } + entityCount + } +} +``` + +### 6. Query your Subgraph + +You can now query your subgraph by following [these instructions](/developer/query-the-graph). You can query from your dapp if you don't have your API key via the free, rate limited temporary query URL that can be used for development and staging. You can read the additional instructions for how to query a subgraph from a frontend application [here](/developer/querying-from-your-app). + +## Hosted Service + +### 1. Install the Graph CLI + +"The Graph CLI is an npm package and you will need `npm` or `yarn` installed to use it. + +```sh +# NPM +$ npm install -g @graphprotocol/graph-cli + +# Yarn +$ yarn global add @graphprotocol/graph-cli +``` + +### 2. Initialize your Subgraph + +- Initialize your subgraph from an existing contract. + +```sh +$ graph init --product hosted-service --from-contract
+``` + +- You will be asked for a subgraph name. The format is `/`. Ex: `graphprotocol/examplesubgraph` + +- If you'd like to initialize from an example, run the command below: + +```sh +$ graph init --product hosted-service --from-example +``` + +- In the case of the example, the subgraph is based on the Gravity contract by Dani Grant that manages user avatars and emits `NewGravatar` or `UpdateGravatar` events whenever avatars are created or updated. + +### 3. Write your Subgraph + +The previous command will have created a scaffold from where you can build your subgraph. When making changes to the subgraph, you will mainly work with three files: + +- Manifest (subgraph.yaml) - The manifest defines what datasources your subgraph will index +- Schema (schema.graphql) - The GraphQL schema define what data you wish to retrieve from the subgraph +- AssemblyScript Mappings (mapping.ts) - This is the code that translates data from your datasources to the entities defined in the schema + +For more information on how to write your subgraph, see [Create a Subgraph](/developer/create-subgraph-hosted). + +### 4. Deploy your Subgraph + +- Sign into the [Hosted Service](https://thegraph.com/hosted-service/) using your github account +- Click Add Subgraph and fill out the required information. Use the same subgraph name as in step 2. +- Run codegen in the subgraph folder + +```sh + # NPM +$ npm run codegen + +# Yarn +$ yarn codegen +``` + +- Add your Access token and deploy your subgraph. The access token is found on your dashboard in the Hosted Service. + +```sh +$ graph auth --product hosted-service +$ graph deploy --product hosted-service / +``` + +### 5. Check your logs + +The logs should tell you if there are any errors. If your subgraph is failing, you can query the subgraph health by using the [GraphiQL Playground](https://graphiql-online.com/). Use [this endpoint](https://api.thegraph.com/index-node/graphql). Note that you can leverage the query below and input your deployment ID for your subgraph. In this case, `Qm...` is the deployment ID (which can be located on the Subgraph page under **Details**). The query below will tell you when a subgraph fails so you can debug accordingly: + +```sh +{ + indexingStatuses(subgraphs: ["Qm..."]) { + node + synced + health + fatalError { + message + block { + number + hash + } + handler + } + nonFatalErrors { + message + block { + number + hash + } + handler + } + chains { + network + chainHeadBlock { + number + } + earliestBlock { + number + } + latestBlock { + number + } + lastHealthyBlock { + number + } + } + entityCount + } +} +``` + +### 6. Query your Subgraph + +Follow [these instructions](/hosted-service/query-hosted-service) to query your subgraph on the Hosted Service. diff --git a/pages/ko/explorer.mdx b/pages/ko/explorer.mdx index 7132fa01731d..816139ae9a58 100644 --- a/pages/ko/explorer.mdx +++ b/pages/ko/explorer.mdx @@ -11,7 +11,7 @@ title: 탐색기 title="YouTubeビデオプレーヤー" frameBorder="0" allowFullScreen - > +> ## 서브그래프 diff --git a/pages/ko/hosted-service/deploy-subgraph-hosted.mdx b/pages/ko/hosted-service/deploy-subgraph-hosted.mdx new file mode 100644 index 000000000000..bdc532e205e4 --- /dev/null +++ b/pages/ko/hosted-service/deploy-subgraph-hosted.mdx @@ -0,0 +1,160 @@ +--- +title: Deploy a Subgraph to the Hosted Service +--- + +If you have not checked out already, check out how to write the files that make up a [subgraph manifest](/developer/create-subgraph-hosted#the-subgraph-manifest) and how to install the [Graph CLI](https://github.com/graphprotocol/graph-cli) to generate code for your subgraph. Now, it's time to deploy your subgraph to the Hosted Service, also known as the Hosted Service. + +## Create a Hosted Service account + +Before using the Hosted Service, create an account in our Hosted Service. You will need a [Github](https://github.com/) account for that; if you don't have one, you need to create that first. Then, navigate to the [Hosted Service](https://thegraph.com/hosted-service/), click on the _'Sign up with Github'_ button and complete Github's authorization flow. + +## Store the Access Token + +After creating an account, navigate to your [dashboard](https://thegraph.com/hosted-service/dashboard). Copy the access token displayed on the dashboard and run `graph auth --product hosted-service `. This will store the access token on your computer. You only need to do this once, or if you ever regenerate the access token. + +## Create a Subgraph on the Hosted Service + +Before deploying the subgraph, you need to create it in The Graph Explorer. Go to the [dashboard](https://thegraph.com/hosted-service/dashboard) and click on the _'Add Subgraph'_ button and fill in the information below as appropriate: + +**Image** - Select an image to be used as a preview image and thumbnail for the subgraph. + +**Subgraph Name** - Together with the account name that the subgraph is created under, this will also define the `account-name/subgraph-name`-style name used for deployments and GraphQL endpoints. _This field cannot be changed later._ + +**Account** - The account that the subgraph is created under. This can be the account of an individual or organization. _Subgraphs cannot be moved between accounts later._ + +**Subtitle** - Text that will appear in subgraph cards. + +**Description** - Description of the subgraph, visible on the subgraph details page. + +**GitHub URL** - Link to the subgraph repository on GitHub. + +**Hide** - Switching this on hides the subgraph in the 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 [Define a Subgraph section](/developer/define-subgraph-hosted). + +## Deploy a Subgraph on the Hosted Service + +Deploying your subgraph will upload the subgraph files that you've built with `yarn build` to IPFS and tell the Graph Explorer to start indexing your subgraph using these files. + +You deploy the subgraph by running `yarn deploy` + +After deploying the subgraph, the 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 Ethereum blocks, starting with the genesis block, syncing can take from a few minutes to several hours. The subgraph status switches to `Synced` once the Graph Node has extracted all data from historical blocks. The Graph Node will continue inspecting Ethereum blocks for your subgraph as these blocks are mined. + +## Redeploying a Subgraph + +When making changes to your subgraph definition, for example to fix a problem in the entity mappings, run the `yarn deploy` command above again to deploy the updated version of your subgraph. Any update of a subgraph requires that Graph Node reindexes your entire subgraph, again starting with the genesis block. + +If your previously deployed subgraph is still in status `Syncing`, it will be immediately replaced with the newly deployed version. If the previously deployed subgraph is already fully synced, Graph Node will mark the newly deployed version as the `Pending Version`, sync it in the background, and only replace the currently deployed version with the new one once syncing the new version has finished. This ensures that you have a subgraph to work with while the new version is syncing. + +### Deploying the subgraph to multiple Ethereum networks + +In some cases, you will want to deploy the same subgraph to multiple Ethereum networks without duplicating all of its code. The main challenge that comes with this is that the contract addresses on these networks are different. One solution that allows to parameterize aspects like contract addresses is to generate parts of it using a templating system like [Mustache](https://mustache.github.io/) or [Handlebars](https://handlebarsjs.com/). + +To illustrate this approach, let's assume a subgraph should be deployed to mainnet and Ropsten using different contract addresses. You could then define two config files providing the addresses for each network: + +```json +{ + "network": "mainnet", + "address": "0x123..." +} +``` + +and + +```json +{ + "network": "ropsten", + "address": "0xabc..." +} +``` + +Along with that, you would substitute the network name and addresses in the manifest with variable placeholders `{{network}}` and `{{address}}` and rename the manifest to e.g. `subgraph.template.yaml`: + +```yaml +# ... +dataSources: + - kind: ethereum/contract + name: Gravity + network: mainnet + network: {{network}} + source: + address: '0x2E645469f354BB4F5c8a05B3b30A929361cf77eC' + address: '{{address}}' + abi: Gravity + mapping: + kind: ethereum/events +``` + +In order generate a manifest to either network, you could add two additional commands to `package.json` along with a dependency on `mustache`: + +```json +{ + ... + "scripts": { + ... + "prepare:mainnet": "mustache config/mainnet.json subgraph.template.yaml > subgraph.yaml", + "prepare:ropsten": "mustache config/ropsten.json subgraph.template.yaml > subgraph.yaml" + }, + "devDependencies": { + ... + "mustache": "^3.1.0" + } +} +``` + +To deploy this subgraph for mainnet or Ropsten you would now simply run one of the two following commands: + +```sh +# Mainnet: +yarn prepare:mainnet && yarn deploy + +# Ropsten: +yarn prepare:ropsten && yarn deploy +``` + +A working example of this can be found [here](https://github.com/graphprotocol/example-subgraph/tree/371232cf68e6d814facf5e5413ad0fef65144759). + +**Note:** This approach can also be applied more complex situations, where it is necessary to substitute more than contract addresses and network names or where generating mappings or ABIs from templates as well. + +## Checking subgraph health + +If a subgraph syncs successfully, that is a good sign that it will continue to run well forever. However, new triggers on the chain might cause your subgraph to hit an untested error condition or it may start to fall behind due to performance issues or issues with the node operators. + +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](https://github.com/graphprotocol/graph-node/blob/master/server/index-node/src/schema.graphql). Here is an example query that checks the status of the current version of a subgraph: + +```graphql +{ + indexingStatusForCurrentVersion(subgraphName: "org/subgraph") { + synced + health + fatalError { + message + block { + number + hash + } + handler + } + chains { + chainHeadBlock { + number + } + latestBlock { + number + } + } + } +} +``` + +This will give you the `chainHeadBlock` which you can compare with the `latestBlock` on your subgraph to check if it is running behind. `synced` informs if the subgraph has ever caught up to the chain. `health` can currently take the values of `healthy` if no errors ocurred, or `failed` if there was an error which halted the progress of the subgraph. In this case you can check the `fatalError` field for details on this error. + +## Subgraph archive policy + +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 which 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 30 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. diff --git a/pages/ko/hosted-service/migrating-subgraph.mdx b/pages/ko/hosted-service/migrating-subgraph.mdx new file mode 100644 index 000000000000..2a184afcb50e --- /dev/null +++ b/pages/ko/hosted-service/migrating-subgraph.mdx @@ -0,0 +1,151 @@ +--- +title: Migrating an Existing Subgraph to The Graph Network +--- + +## Introduction + +This is a guide for the migration of subgraphs from the Hosted Service (also known as the Hosted Service) to The Graph Network. The migration to The Graph Network has been successful for projects like Opyn, UMA, mStable, Audius, PoolTogether, Livepeer, RAI, Enzyme, DODO, Opyn, Pickle, and BadgerDAO all of which are relying on data served by Indexers on the network. There are now over 200 subgraphs live on The Graph Network, generating query fees and actively indexing web3 data. + +This will tell you everything you need to know about how to migrate to the decentralized network and manage your subgraphs moving forward. The process is quick and your subgraphs will forever benefit from the reliability and performance that you can only get on The Graph Network. + +### Migrating An Existing Subgraph to The Graph Network + +1. Get the latest version of the graph-cli installed: + +```sh +npm install -g @graphprotocol/graph-cli +``` + +```sh +yarn global add @graphprotocol/graph-cli +``` + +2. Create a subgraph on the [Subgraph Studio](https://thegraph.com/studio/). Guides on how to do that can be found in the [Subgraph Studio docs](/studio/subgraph-studio) and in [this video tutorial](https://www.youtube.com/watch?v=HfDgC2oNnwo). +3. Inside the main project subgraph repository, authenticate the subgraph to deploy and build on the studio: + +```sh +graph auth --studio +``` + +4. Generate files and build the subgraph: + +```sh +graph codegen && graph build +``` + +5. Deploy the subgraph to the Studio. You can find your `` in the Studio UI, which is based on the name of your subgraph. + +```sh + graph deploy --studio +``` + +6. Test queries on the Studio's playground. Here are some examples for the [Sushi - Mainnet Exchange Subgraph](https://thegraph.com/explorer/subgraph?id=0x4bb4c1b0745ef7b4642feeccd0740dec417ca0a0-0&view=Playground): + +```sh +{ + users(first: 5) { + id + liquidityPositions { + id + } + } + bundles(first: 5) { + id + ethPrice + } +} +``` + +7. Fill in the description and the details of your subgraph and choose up to 3 categories. Upload a project image in the Studio if you'd like as well. +8. Publish the subgraph on The Graph's Network by hitting the "Publish" button. + +- Remember that publishing is an on-chain action and will require gas to be paid for in Ethereum - see an example transaction [here](https://etherscan.io/tx/0xd0c3fa0bc035703c9ba1ce40c1862559b9c5b6ea1198b3320871d535aa0de87b). Prices are roughly around 0.0425 ETH at 100 gwei. +- Any time you need to upgrade your subgraph, you will be charged an upgrade fee. Remember, upgrading is just publishing another version of your existing subgraph on-chain. Because this incurs a cost, it is highly recommended to deploy and test your subgraph on Rinkeby before deploying to mainnet. It can, in some cases, also require some GRT if there is no signal on that subgraph. In the case there is signal/curation on that subgraph version (using auto-migrate), the taxes will be split. + +And that's it! After you are done publishing, you'll be able to view your subgraphs live on the network via [The Graph Explorer](https://thegraph.com/explorer). + +### Upgrading a Subgraph on the Network + +If you would like to upgrade an existing subgraph on the network, you can do this by deploying a new version of your subgraph to the Subgraph Studio using the Graph CLI. + +1. Make changes to your current subgraph. A good idea is to test small fixes on the Subgraph Studio by publishing to Rinkeby. +2. Deploy the following and specify the new version in the command (eg. v0.0.1, v0.0.2, etc): + +```sh +graph deploy --studio +``` + +3. Test the new version in the Subgraph Studio by querying in the playground +4. Publish the new version on The Graph Network. Remember that this requires gas (as described in the section above). + +### Owner Upgrade Fee: Deep Dive + +An upgrade requires GRT to be migrated from the old version of the subgraph to the new version. This means that for every upgrade, a new bonding curve will be created (more on bonding curves [here](/curating#bonding-curve-101)). + +The new bonding curve charges the 2.5% curation tax on all GRT being migrated to the new version. The owner must pay 50% of this, or 1.25%. The other 1.25% is absorbed by all the curators as a fee. This incentive design is in place to prevent an owner of a subgraph from being able to drain all their curator's funds with recursive upgrade calls. The example below is only the case if your subgraph is being actively curated on. If there is no curation activity, you will have to pay a minimum of 100 GRT in order to signal yourself on your own subgraph. + +- 100,000 GRT is signaled using auto-migrate on v1 of a subgraph +- Owner upgrades to v2. 100,000 GRT is migrated to a new bonding curve, where 97,500 GRT get put into the new curve and 2,500 GRT is burned +- The owner then has 1250 GRT burned to pay for half the fee. The owner must have this in their wallet before the upgrade, otherwise the upgrade will not succeed. This happens in the same transaction as the upgrade. + +_While this mechanism is currently live on the network, the community is currently discussing ways to reduce the cost of upgrades for subgraph developers._ + +### Maintaining a Stable Version of a Subgraph + +If you're making a lot of changes to your subgraph, it is not a good idea to continually upgrade it and front the upgrade costs. Maintaining a stable and consistent version of your subgraph is critical, not only from the cost perspective, but also so that Indexers can feel confident in their syncing times. Indexers should be flagged when you plan for an upgrade so that Indexer syncing times do not get impacted. Feel free to leverage the [#Indexers channel](https://discord.gg/8tgJ7rKW) on Discord to let Indexers know when you're versioning your subgraphs. + +Subgraphs are open API that external developers are leveraging. Open APIs need to follow strict standards so that they do not break external developers' applications. In The Graph Network, a subgraph developer must consider Indexers and how long it takes them to sync a new subgraph **as well as** other developers who are using their subgraphs. + +### Updating the Metadata of a Subgraph + +You can update the metadata of your subgraphs without having to publish a new version. The metadata includes the subgraph name, image, description, website URL, source code URL, and categories. Developers can do this by updating their subgraph details in the Subgraph Studio where you can edit all applicable fields. + +Make sure **Update Subgraph Details in Explorer** is checked and click on **Save**. If this is checked, an an on-chain transaction will be generated that updates subgraph details in the Explorer without having to publish a new version with a new deployment. + +## Best Practices for Deploying a Subgraph to The Graph Network + +1. Leveraging an ENS name for Subgraph Development + +- Set up your ENS: [https://app.ens.domains/](https://app.ens.domains/) +- Add your ENS name to your settings [here](https://thegraph.com/explorer/settings?view=display-name). + +The more filled out your profiles are, the better the chances for your subgraphs to be indexed and curated. + +## Deprecating a Subgraph on The Graph Network + +Follow the steps [here](/developer/deprecating-a-subgraph) to deprecate your subgraph and remove it from The Graph Network. + +## Querying a Subgraph + Billing on The Graph Network + +The Hosted Service was set up to allow developers to deploy their subgraphs without any restrictions. + +In order for The Graph Network to truly be decentralized, query fees have to be paid as a core part of the protocol's incentives. For more information on subscribing to APIs and paying the query fees, check out billing documentation [here](/studio/billing). + +### Estimate Query Fees on the Network + +While this is not a live feature in the product UI, you can set your maximum budget per query by taking the amount you're willing to pay per month and divide it by your expected query volume. + +While you get to decide on your query budget, there is no guarantee that an Indexer will be willing to serve queries at that price. If a Gateway can match you to an Indexer willing to serve a query at, or lower than, the price you are willing to pay, you will pay the delta/difference of your budget **and** their price. As a consequence of that, a lower query price reduces the pool of Indexers available to you, which may affect the quality of service you receive. It's beneficial to have high query fees, as that may attract curation and big name Indexers to your subgraph. + +Remember that it's a dynamic and growing market, but how you interact with it is in your control. There is no maximum or minimum price specified in the protocol or in the Gateways. For example, you can look at the price paid by a few of the dapps on the network (on a per week basis), below. See the last column which shows query fees in GRT. For example, [Pickle Finance](https://www.pickle.finance/) has 8 requests per second and paid 2.4 GRT for one week. + +![QueryFee](/img/QueryFee.png) + +## Additional Resources + +If you're still confused, fear not! Check out the following resources or watch our video guide on migrating subgraphs to the decentralized network below: + +
+ +
+ +- [The Graph Network Contracts](https://github.com/graphprotocol/contracts) +- [Curation Contract](https://github.com/graphprotocol/contracts/blob/dev/contracts/curation/Curation.sol) - the underlying contract that the GNS wraps around + - Address - `0x8fe00a685bcb3b2cc296ff6ffeab10aca4ce1538` +- [Subgraph Studio documentation](/studio/subgraph-studio) diff --git a/pages/ko/hosted-service/query-hosted-service.mdx b/pages/ko/hosted-service/query-hosted-service.mdx new file mode 100644 index 000000000000..731e3a3120b2 --- /dev/null +++ b/pages/ko/hosted-service/query-hosted-service.mdx @@ -0,0 +1,28 @@ +--- +title: Query the Hosted Service +--- + +With the subgraph deployed, visit the [Hosted Service](https://thegraph.com/hosted-service/) to open up a [GraphiQL](https://github.com/graphql/graphiql) interface where you can explore the deployed GraphQL API for the subgraph by issuing queries and viewing the schema. + +An example is provided below, but please see the [Query API](/developer/graphql-api) for a complete reference on how to query the subgraph's entities. + +#### Example + +This query lists all the counters our mapping has created. Since we only create one, the result will only contain our one `default-counter`: + +```graphql +{ + counters { + id + value + } +} +``` + +## Using The Hosted Service + +The Graph Explorer and its GraphQL playground is a useful way to explore and query deployed subgraphs on the Hosted Service. + +Some of the main features are detailed below: + +![Explorer Playground](/img/explorer-playground.png) diff --git a/pages/ko/hosted-service/what-is-hosted-service.mdx b/pages/ko/hosted-service/what-is-hosted-service.mdx new file mode 100644 index 000000000000..7f604c8dc31a --- /dev/null +++ b/pages/ko/hosted-service/what-is-hosted-service.mdx @@ -0,0 +1,77 @@ +--- +title: What is the Hosted Service? +--- + +This section will walk you through deploying a subgraph to the Hosted Service, otherwise known as the [Hosted Service.](https://thegraph.com/hosted-service/) As a reminder, the Hosted Service will not be shut down soon. We will gradually sunset the Hosted Service once we reach feature parity with the decentralized network. Your subgraphs deployed on the Hosted Service are still available [here.](https://thegraph.com/hosted-service/) + +If you don't have an account on the Hosted Service, you can signup with your Github account. Once you authenticate, you can start creating subgraphs through the UI and deploying them from your terminal. Graph Node supports a number of Ethereum testnets (Rinkeby, Ropsten, Kovan) in addition to mainnet. + +## Create a Subgraph + +First follow the instructions [here](/developer/define-subgraph-hosted) to install the Graph CLI. Create a subgraph by passing in `graph init --product hosted service` + +### From an Existing Contract + +If you already have a smart contract deployed to Ethereum mainnet or one of the testnets, bootstrapping a new subgraph from this contract can be a good way to get started on the Hosted Service. + +You can use this command to create a subgraph that indexes all events from an existing contract. This will attempt to fetch the contract ABI from [Etherscan](https://etherscan.io/). + +```sh +graph init \ + --product hosted-service + --from-contract \ + / [] +``` + +Additionally, you can use the following optional arguments. If the ABI cannot be fetched from Etherscan, it falls back to requesting a local file path. If any optional arguments are missing from the command, it takes you through an interactive form. + +```sh +--network \ +--abi \ +``` + +The `` in this case is your github user or organization name, `` is the name for your subgraph, and `` is the optional name of the directory where graph init will put the example subgraph manifest. The `` is the address of your existing contract. `` is the name of the Ethereum network that the contract lives on. `` is a local path to a contract ABI file. **Both --network and --abi are optional.** + +### From an Example Subgraph + +The second mode `graph init` supports is creating a new project from an example subgraph. The following command does this: + +``` +graph init --from-example --product hosted-service / [] +``` + +The example subgraph is based on the Gravity contract by Dani Grant that manages user avatars and emits `NewGravatar` or `UpdateGravatar` events whenever avatars are created or updated. The subgraph handles these events by writing `Gravatar` entities to the Graph Node store and ensuring these are updated according to the events. Continue on to the [subgraph manifest](/developer/create-subgraph-hosted#the-subgraph-manifest) to better understand which events from your smart contracts to pay attention to, mappings, and more. + +## Supported Networks on the Hosted Service + +Please note that the following networks are supported on the Hosted Service. Networks outside of Ethereum mainnet ('mainnet') are not currently supported on [The Graph Explorer.](https://thegraph.com/explorer) + +- `mainnet` +- `kovan` +- `rinkeby` +- `ropsten` +- `goerli` +- `poa-core` +- `poa-sokol` +- `xdai` +- `near-mainnet` +- `near-testnet` +- `matic` +- `mumbai` +- `fantom` +- `bsc` +- `chapel` +- `clover` +- `avalanche` +- `fuji` +- `celo` +- `celo-alfajores` +- `fuse` +- `moonriver` +- `mbase` +- `arbitrum-one` +- `arbitrum-rinkeby` +- `optimism` +- `optimism-kovan` +- `aurora` +- `aurora-testnet` diff --git a/pages/ko/indexing.mdx b/pages/ko/indexing.mdx index 1f6508d99ced..b9100d86a58b 100644 --- a/pages/ko/indexing.mdx +++ b/pages/ko/indexing.mdx @@ -115,7 +115,7 @@ Disputes can be viewed in the UI in an Indexer's profile page under the `Dispute - **Large** - 현재 사용되는 모든 서브그래프들 및 관련 트레픽 요청의 처리에 대한 요건을 충족합니다. | Setup | (CPUs) | (memory in GB) | (disk in TBs) | (CPUs) | (memory in GB) | -| -------- | :----: | :------------: | :-----------: | :----: | :------------: | +| -------- |:------:|:--------------:|:-------------:|:------:|:--------------:| | Small | 4 | 8 | 1 | 4 | 16 | | Standard | 8 | 30 | 1 | 12 | 48 | | Medium | 16 | 64 | 2 | 32 | 64 | @@ -149,20 +149,20 @@ Disputes can be viewed in the UI in an Indexer's profile page under the `Dispute #### 그래프 노드 -| Port | Purpose | Routes | CLI Argument | Environment Variable | -| --- | --- | --- | --- | --- | -| 8000 | GraphQL HTTP server
(for subgraph queries) | /subgraphs/id/...

/subgraphs/name/.../... | --http-port | - | -| 8001 | GraphQL WS
(for subgraph subscriptions) | /subgraphs/id/...

/subgraphs/name/.../... | --ws-port | - | -| 8020 | JSON-RPC
(for managing deployments) | / | --admin-port | - | -| 8030 | Subgraph indexing status API | /graphql | --index-node-port | - | -| 8040 | Prometheus metrics | /metrics | --metrics-port | - | +| Port | Purpose | Routes | CLI Argument | Environment Variable | +| ---- | ------------------------------------------------------- | ------------------------------------------------------------------- | ----------------- | -------------------- | +| 8000 | GraphQL HTTP server
(for subgraph queries) | /subgraphs/id/...

/subgraphs/name/.../... | --http-port | - | +| 8001 | GraphQL WS
(for subgraph subscriptions) | /subgraphs/id/...

/subgraphs/name/.../... | --ws-port | - | +| 8020 | JSON-RPC
(for managing deployments) | / | --admin-port | - | +| 8030 | Subgraph indexing status API | /graphql | --index-node-port | - | +| 8040 | Prometheus metrics | /metrics | --metrics-port | - | #### Indexer Service -| Port | Purpose | Routes | CLI Argument | Environment Variable | -| --- | --- | --- | --- | --- | -| 7600 | GraphQL HTTP server
(for paid subgraph queries) | /subgraphs/id/...
/status
/channel-messages-inbox | --port | `INDEXER_SERVICE_PORT` | -| 7300 | Prometheus metrics | /metrics | --metrics-port | - | +| Port | Purpose | Routes | CLI Argument | Environment Variable | +| ---- | ------------------------------------------------------------ | --------------------------------------------------------------------------- | -------------- | ---------------------- | +| 7600 | GraphQL HTTP server
(for paid subgraph queries) | /subgraphs/id/...
/status
/channel-messages-inbox | --port | `INDEXER_SERVICE_PORT` | +| 7300 | Prometheus metrics | /metrics | --metrics-port | - | #### Indexer Agent diff --git a/pages/ko/studio/billing.mdx b/pages/ko/studio/billing.mdx new file mode 100644 index 000000000000..a88e6c4ab236 --- /dev/null +++ b/pages/ko/studio/billing.mdx @@ -0,0 +1,68 @@ +--- +title: Billing on the Subgraph Studio +--- + +### Overview + +Invoices are statements of payment amounts owed by a customer and are typically generated on a weekly basis in the system. You’ll be required to pay fees based on the query fees you generate using your API keys. The billing contract lives on the [Polygon](https://polygon.technology/) network. It’ll allow you to: + +- Add and remove GRT +- Keep track of your balances based on how much GRT you have added to your account, how much you have removed, and your invoices +- Automatically clear payments based on query fees generated + +In order to add GRT to your account, you will need to go through the following steps: + +1. Purchase GRT and ETH on an exchange of your choice +2. Send the GRT and ETH to your wallet +3. Bridge GRT to Polygon using the UI + + a) You will receive 0.001 Matic in a few minutes after you send any amount of GRT to the Polygon bridge. You can track the transaction on [Polygonscan](https://polygonscan.com/) by inputting your address into the search bar. + +4. Add bridged GRT to the billing contract on Polygon. The billing contract address is: [0x10829DB618E6F520Fa3A01c75bC6dDf8722fA9fE](https://polygonscan.com/address/0x10829DB618E6F520Fa3A01c75bC6dDf8722fA9fE). + + a) In order to complete step #4, you'll need to switch your network in your wallet to Polygon. You can add Polygon's network by connecting your wallet and clicking on "Choose Matic (Polygon) Mainnet" [here.](https://chainlist.org/) Once you've added the network, switch it over in your wallet by navigating to the network pill on the top right hand side corner. In Metamask, the network is called **Matic Mainnnet.** + +At the end of each week, if you used your API keys, you will receive an invoice based on the query fees you have generated during this period. This invoice will be paid using GRT available in your balance. Query volume is evaluated by the API keys you own. Your balance will be updated after fees are withdrawn. + +#### Here’s how you go through the invoicing process: + +There are 4 states your invoice can be in: + +1. Created - your invoice has just been created and not been paid yet +2. Paid - your invoice has been successfully paid +3. Unpaid - there is not enough GRT in your balance on the billing contract +4. Error - there is an error processing the payment + +**See the diagram below for more information:** + +![Billing Flow](/img/billing-flow.png) + +For a quick demo of how billing works on the Subgraph Studio, check out the video below: + +
+ +
+ +### Multisig Users + +Multisigs are smart-contracts that can exist only on the network they have been created, so if you created one on Ethereum Mainnet - it will only exist on Mainnet. Since our billing uses Polygon, if you were to bridge GRT to the multisig address on Polygon the funds would be lost. + +To overcome this issue, we created [a dedicated tool](https://multisig-billing.thegraph.com/) that will help you deposit GRT on our billing contract (on behalf of the multisig) with a standard wallet / EOA (an account controlled by a private key). + +You can access our Multisig Billing Tool here: https://multisig-billing.thegraph.com/ + +This tool will guide you to go through the following steps: + +1. Connect your standard wallet / EOA (this wallet needs to own some ETH as well as the GRT you want to deposit) +2. Bridge GRT to Polygon. You will have to wait 7-8 minutes after the transaction is complete for the bridge transfer to be finalized. +3. Once your GRT is available on your Polygon balance you can deposit them to the billing contract while specifying the multisig address you are funding in the `Multisig Address` field. + +Once the deposit transaction has been confirmed you can go back to [Subgraph Studio](https://thegraph.com/studio/) and connect with your Gnosis Safe Multisig to create API keys and use them to generate queries. + +Those queries will generate invoices that will be paid automatically using the multisig’s billing balance. diff --git a/pages/ko/studio/deploy-subgraph-studio.mdx b/pages/ko/studio/deploy-subgraph-studio.mdx new file mode 100644 index 000000000000..2155d8fe8976 --- /dev/null +++ b/pages/ko/studio/deploy-subgraph-studio.mdx @@ -0,0 +1,68 @@ +--- +title: Deploy a Subgraph to the Subgraph Studio +--- + +Deploying a Subgraph to the Subgraph Studio is quite simple. This will take you through the steps to: + +- Install The Graph CLI (with both yarn and npm) +- Create your Subgraph in the Subgraph Studio +- Authenticate your account from the CLI +- Deploying a Subgraph to the Subgraph Studio + +## Installing Graph CLI + +We are using the same CLI to deploy subgraphs to our [hosted service](https://thegraph.com/hosted-service/) and to the [Subgraph Studio](https://thegraph.com/studio/). Here are the commands to install graph-cli. This can be done using npm or yarn. + +**Install with yarn:** + +```bash +yarn global add @graphprotocol/graph-cli +``` + +**Install with npm:** + +```bash +npm install -g @graphprotocol/graph-cli +``` + +## Create your Subgraph in Subgraph Studio + +Before deploying your actual subgraph you need to create a subgraph in [Subgraph Studio](https://thegraph.com/studio/). We recommend you read our [Studio documentation](/studio/subgraph-studio) to learn more about this. + +## Initialize your Subgraph + +Once your subgraph has been created in Subgraph Studio you can initialize the subgraph code using this command: + +```bash +graph init --studio +``` + +The `` value can be found on your subgraph details page in Subgraph Studio: + +![Subgraph Studio - Slug](/img/doc-subgraph-slug.png) + +After running `graph init`, you will be asked to input the contract address, network and abi that you want to query. Doing this will generate a new folder on your local machine with some basic code to start working on your subgraph. You can then finalize your subgraph to make sure it works as expected. + +## Graph Auth + +Before being able to deploy your subgraph to Subgraph Studio, you need to login to your account within the CLI. To do this, you will need your deploy key that you can find on your "My Subgraphs" page or on your subgraph details page. + +Here is the command that you need to use to authenticate from the CLI: + +```bash +graph auth --studio +``` + +## Deploying a Subgraph to Subgraph Studio + +Once you are ready, you can deploy your subgraph to Subgraph Studio. Doing this won't publish your subgraph to the decentralized network, it will only deploy it to your Studio account where you will be able to test it and update the metadata. + +Here is the CLI command that you need to use to deploy your subgraph. + +```bash +graph deploy --studio +``` + +After running this command, the CLI will ask for a version label, you can name it however you want, you can use labels such as `0.1` and `0.2` or use letters as well such as `uniswap-v2-0.1` . Those labels will be visible in Graph Explorer and can be used by curators to decide if they want to signal on this version or not, so choose them wisely. + +Once deployed, you can test your subgraph in Subgraph Studio using the playground, deploy another version if needed, update the metadata, and when you are ready, publish your subgraph to Graph Explorer. diff --git a/pages/ko/studio/multisig.mdx b/pages/ko/studio/multisig.mdx new file mode 100644 index 000000000000..164835bdb8a4 --- /dev/null +++ b/pages/ko/studio/multisig.mdx @@ -0,0 +1,82 @@ +--- +title: Using a Multisig Wallet +--- + +Subgraph Studio currently doesn't support signing with multisig wallets. Until then, you can follow this guide on how to publish your subgraph by invoking the [GNS contract](https://github.com/graphprotocol/contracts/blob/dev/contracts/discovery/GNS.sol) functions. + +### Create a Subgraph + +Similary to using a regular wallet, you can create a subgraph by connecting your non-multisig wallet in Subgraph Studio. Once you connect the wallet, simply create a new subgraph. Make sure you fill out all the details, such as subgraph name, description, image, website, and source code url if applicable. + +For initializing a starter subgraph, you can follow the commands shown in the UI, or simply run + +``` +graph init --studio +``` + +`SUBGRAPH_SLUG` is the name of your subgraph that you can copy from the UI, or from the URL in the browser. This command should create a folder in your file system with all the necessary files to start developing a subgraph. + +### Deploy a Subgraph + +Once your subgraph is ready to be deployed to the graph node, simply follow the commands shown in the UI, or run the following command: + +``` +graph deploy --studio +``` + +**Note**: Make sure that you are inside of the subgraph folder before running the command. + +### Publish a Subgraph or a Version + +You can either publish a new subgraph to the decentralized network or publish a new version of the previously published subgraph. + +#### Publish a New Subgraph + +There are a couple of ways to publish a subgraph using multisig wallets. Here we'll describe invoking the [`publishNewSubgraph`](https://github.com/graphprotocol/contracts/blob/dev/contracts/discovery/GNS.sol#L231) function in the [GNS contract](https://etherscan.io/address/0xaDcA0dd4729c8BA3aCf3E99F3A9f471EF37b6825) using Etherscan. + +Before we use that function, we need to generate input arguments for it. Access [this page](https://thegraph.com/studio/multisig) in Subgraph Studio and provide the following: + +- Ethereum address of your multisig wallet +- Subgraph that you want to publish +- Version that you want to publish + +After clicking on "Get Arguments", we'll generate all the contract arguments for you! + +There should be 4 arguments: + +- `graphAccount`: which is your multisig account address +- `subgraphDeploymentID`: the hex hash of the deployment ID for that subgraph +- `versionMetadata`: version metadata (label and description) that gets uploaded to IPFS. The hex hash value for that JSON file will be provided. +- `subgraphMetadata`: simlar to version metadata, subgraph metadata (name, image, description, website and source code url) gets uploaded to IPFS, and we provide the hex hash value for that JSON file + +With those 4 arguments, you should be able to: + +- Visit [our GraphProxy](https://etherscan.io/address/0xaDcA0dd4729c8BA3aCf3E99F3A9f471EF37b6825#writeProxyContract) contract on Etherscan +- Connect to Etherscan using WalletConnect via the WalletConnect Safe app of your multisig +- Call the `publishNewSubgraph` method with the paramaters that were generated by our tool + +#### Publish a New Version + +To publish a new version of an existing subgraph we first need to generate input arguments for it. Access [this page](https://thegraph.com/studio/multisig) in Subgraph Studio and provide: + +- Ethereum address of your multisig wallet +- Subgraph that you want to publish +- Version that you want to publish +- The ID of the subgraph you want to update in Graph Explorer + +After clicking on "Get Arguments" we'll generate all the contract arguments for you! + +On the right side of the UI under the `Publish New Version` title, there should be 4 arguments: + +- `graphAccount`: which is your Multisig account address +- `subgraphNumber`: is the number of your already published subgraph. It is a part of the subgraph id for a published subgraph queried through The Graph Network subgraph. +- `subgraphDeploymentID`: which is the hex hash of the deployment ID for that subgraph +- `versionMetadata`: version metadata (label and description) gets uploaded to IPFS, and we provide the hex hash value for that JSON file + +Now that we generated all the arguments you are ready to proceed and call the `publishNewVersion` method. In order to do so, you should: + +- Visit [the GraphProxy](https://etherscan.io/address/0xaDcA0dd4729c8BA3aCf3E99F3A9f471EF37b6825#writeProxyContract) contract on Etherscan +- Connect to Etherscan using WalletConnect via the WalletConnect Safe app of your Multisig +- Call the `publishNewVersion` method with the paramaters that were generated by our tool + +Once the transaction is successful, your subgraph should have a new version of your subgraph in Graph Explorer which means that curators can start signaling on it and indexers can start indexing it. diff --git a/pages/ko/studio/studio-faq.mdx b/pages/ko/studio/studio-faq.mdx new file mode 100644 index 000000000000..4db4d7ccddaa --- /dev/null +++ b/pages/ko/studio/studio-faq.mdx @@ -0,0 +1,21 @@ +--- +title: Subgraph Studio FAQs +--- + +### 1. How do I create an API Key? + +In the Subgraph Studio, you can create API Keys as needed and add security settings to each of them. + +### 2. Can I create multiple API Keys? + +A: Yes! You can create multiple API Keys to use in different projects. Check out the link [here](https://thegraph.com/studio/apikeys/). + +### 3. How do I restrict a domain for an API Key? + +After creating an API Key, in the Security section you can define the domains that can query a specific API Key. + +### 4. How do I find query URLs for subgraphs if I’m not the developer of the subgraph I want to use? + +You can find the query URL of each subgraph in the Subgraph Details section of The Graph Explorer. When you click on the “Query” button, you will be directed to a pane wherein you can view the query URL of the subgraph you’re interested in. You can then replace the `` placeholder with the API key you wish to leverage in the Subgraph Studio. + +Remember that you can create an API key and query any subgraph published to the network, even if you build a subgraph yourself. These queries via the new API key, are paid queries as any other on the network. diff --git a/pages/ko/studio/subgraph-studio.mdx b/pages/ko/studio/subgraph-studio.mdx new file mode 100644 index 000000000000..562d588ef26d --- /dev/null +++ b/pages/ko/studio/subgraph-studio.mdx @@ -0,0 +1,122 @@ +--- +title: How to Use the Subgraph Studio +--- + +Welcome to your new launchpad 👩🏽‍🚀 + +The Subgraph Studio is your place to build and create subgraphs, add metadata, and publish them to the new decentralized Explorer (more on that [here](/explorer)). + +What you can do in the Subgraph Studio: + +- Create a subgraph through the Studio UI +- Deploy a subgraph using the CLI +- Publish a subgraph with the Studio UI +- Test it in the playground +- Integrate it in staging using the query URL +- Create and manage your API keys for specific subgraphs + +Here in the Subgraph Studio, you have full control over your subgraphs. Not only can you test your subgraphs before you publish them, but you can also restrict your API keys to specific domains and only allow certain indexers to query from their API keys. + +Querying subgraphs generates query fees, used to reward [indexers](/indexing) on the Graph network. If you’re a dapp developer or subgraph developer, the Studio will empower you to build better subgraphs to power your or your community’s queries. The Studio is comprised of 5 main parts: + +- Your user account controls +- A list of subgraphs that you’ve created +- A section to manage, view details, and visualize the status of a specific subgraph +- A section to manage your API keys that you will need to query a subgraph +- A section to manage your billing + +## How to Create Your Account + +1. Sign in with your wallet - you can do this via MetaMask or WalletConnect +1. Once you sign in, you will see your unique deploy key in your account home page. This will allow you to either publish your subgraphs or manage your API keys + billing. You will have a unique deploy key that can be re-generated if you think it has been compromised. + +## How to Create your Subgraph in Subgraph Studio + +The best part! When you first create a subgraph, you’ll be directed to fill out: + +- Your Subgraph Name +- Image +- Description +- Categories +- Website + +## Subgraph Compatibility with The Graph Network + +The Graph Network is not yet able to support all of the data-sources & features available on the Hosted Service. In order to be supported by indexers on the network, subgraphs must: + +- Index mainnet Ethereum +- Must not use any of the following features: + - ipfs.cat & ipfs.map + - Non-fatal errors + - Grafting + +More features & networks will be added to The Graph Network incrementally. + +### Subgraph lifecycle flow + +![Subgraph Lifecycle](/img/subgraph-lifecycle.png) + +After you have created your subgraph, you will be able to deploy it using the [CLI](https://github.com/graphprotocol/graph-cli), or command line interface. Deploying a subgraph with the CLI will push the subgraph to the Studio where you’ll be able to test subgraphs using the playground. This will eventually allow you to publish to the Graph Network. For more information on CLI setup, [check this out](/developer/define-subgraph-hosted#install-the-graph-cli) (pst, make sure you have your deploy key on hand). Remember, deploying is **not the same as** publishing. When you deploy a subgraph, you just push it to the Studio where you’re able to test it. Versus, when you publish a subgraph, you are publishing it on-chain. + +## Testing your Subgraph in Subgraph Studio + +If you’d like to test your subgraph before publishing it to the network, you can do this in the Subgraph **Playground** or look at your logs. The Subgraph logs will tell you **where** your subgraph fails in the case that it does. + +## Publish your Subgraph in Subgraph Studio + +You’ve made it this far - congrats! Publishing your subgraph means that an IPFS hash was generated when you deployed the subgraph within the CLI and is stored in the network’s Ethereum smart contracts. In order to publish your subgraph successfully, you’ll need to go through the following steps outlined in this [blog](https://thegraph.com/blog/building-with-subgraph-studio). Check out the video overview below as well: + +
+ +
+ +Remember, while you’re going through your publishing flow, you’ll be able to push to either mainnet or Rinkeby, the testnet we support. If you’re a first time subgraph developer, we highly suggest you start with publishing to Rinkeby, which is free to do. This will allow you to see how the subgraph will work in The Graph Explorer and will allow you to test curation elements. + +You’ll only be able to index data from mainnet (even if your subgraph was published to a testnet) because only subgraphs that are indexing mainnet data can be published to the network. This is because indexers need to submit mandatory Proof of Indexing records as of a specific block hash. Because publishing a subgraph is an action taken on-chain, remember that the transaction can take up to a few minutes to go through. Any address you use to publish the contract will be the only one able to publish future versions. Choose wisely! + +Subgraphs with curation signal are shown to Indexers so that they can be indexed on the decentralized network. You can publish subgraphs and signal in one transaction, which allows you to mint the first curation signal on the subgraph and saves on gas costs. By adding your signal to the signal later provided by Curators, your subgraph will also have a higher chance of ultimately serving queries. + +**Now that you’ve published your subgraph, let’s get into how you’ll manage them on a regular basis.** Note that you cannot publish your subgraph to the network if it has failed syncing. This is usually because the subgraph has bugs - the logs will tell you where those issues exist! + +## Versioning your Subgraph with the CLI + +Developers might want to update their subgraph, for a variety of reasons. When this is the case, you can deploy a new version of your subgraph to the Studio using the CLI (it will only be private at this point) and if you are happy with it, you can publish this new deployment to The Graph Explorer. This will create a new version of your subgraph that curators can start signaling on and indexers will be able to index this new version. + +Up until recently, developers were forced to deploy and publish a new version of their subgraph to the Explorer to update the metadata of their subgraphs. Now, developers can update the metadata of their subgraphs **without having to publish a new version**. Developers can update their subgraph details in the Studio (under profile picture, name, description, etc) by checking an option called **Update Details** in The Graph Explorer. If this is checked, an on-chain transaction will be generated that updates subgraph details in the Explorer without having to publish a new version with a new deployment. + +Please note that there are costs associated with publishing a new version of a subgraph to the network. In addition to the transaction fees, developers must also fund a part of the curation tax on auto-migrating signal. You cannot publish a new version of your subgraph if curators have not signaled on it. For more information on the risks of curation, please read more [here](/curating). + +### Automatic Archiving of Subgraph Versions + +Whenever you deploy a new subgraph version in the Subgraph Studio, the previous version will be archived. Archived versions won't be indexed/synced and therefore cannot be queried. You can unarchive an archived version of your subgraph in the Studio UI. Please note that previous versions of non-published subgraphs deployed to the Studio will be automatically archived. + +![Subgraph Studio - Unarchive](/img/Unarchive.png) + +## Managing your API Keys + +Regardless of whether you’re a dapp developer or a subgraph developer, you’ll need to manage your API keys. This is important for you to be able to query subgraphs because API keys make sure the connections between application services are valid and authorized. This includes authenticating the end user and the device using the application. + +The Studio will list out existing API keys, which will give you the ability to manage or delete them. + +1. The **Overview** section will allow you to: + - Edit your key name + - Regenerate API keys + - View the current usage of the API key with stats: + - Number of queries + - Amount of GRT spent +2. Under **Manage Security Settings**, you’ll be able to opt into security settings depending on the level of control you’d like to have over your API keys. In this section, you can: + - View and manage the domain names authorized to use your API key + - Assign subgraphs that can be queried with your API key + +## How to Manage your Subgraph + +API keys aside, you’ll have many tools at your disposal to manage your subgraphs. You can organize your subgraphs by their **status** and **category**. + +- The **Status** tag allows you to pick between a variety of tags including ``, ``, ``, ``, etc. +- Meanwhile, **Category** allows you to designate what category your subgraph falls into. Options include ``, ``, ``, etc. diff --git a/pages/ko/supported-networks/near.mdx b/pages/ko/supported-networks/near.mdx new file mode 100644 index 000000000000..288ac380494c --- /dev/null +++ b/pages/ko/supported-networks/near.mdx @@ -0,0 +1,265 @@ +--- +title: Building Subgraphs on NEAR +--- + +> NEAR support in Graph Node and on the Hosted Service is in beta: please contact near@thegraph.com with any questions about building NEAR subgraphs! + +This guide is an introduction to building subgraphs indexing smart contracts on the [NEAR blockchain](https://docs.near.org/). + +## What is NEAR? + +[NEAR](https://near.org/) is a smart contract platform for building decentralised applications. Visit the [official documentation](https://docs.near.org/docs/concepts/new-to-near) for more information. + +## What are NEAR subgraphs? + +The Graph gives developers tools to process blockchain events and make the resulting data easily available via a GraphQL API, known individually as a subgraph. [Graph Node](https://github.com/graphprotocol/graph-node) is now able to process NEAR events, which means that NEAR developers can now build subgraphs to index their smart contracts. + +Subgraphs are event-based, which means that they listen for and then process on-chain events. There are currently two types of handlers supported for NEAR subgraphs: + +- Block handlers: these are run on every new block +- Receipt handlers: run every time a message is executed at a specified account + +[From the NEAR documentation](https://docs.near.org/docs/concepts/transaction#receipt): + +> A Receipt is the only actionable object in the system. When we talk about "processing a transaction" on the NEAR platform, this eventually means "applying receipts" at some point. + +## Building a NEAR Subgraph + +`@graphprotocol/graph-cli` is a command line tool for building and deploying subgraphs. + +`@graphprotocol/graph-ts` is a library of subgraph-specific types. + +NEAR subgraph development requires `graph-cli` above version `0.23.0`, and `graph-ts` above version `0.23.0`. + +> Building a NEAR subgraph is very similar to building a subgraph which indexes Ethereum. + +There are three aspects of subgraph definition: + +**subgraph.yaml:** the subgraph manifest, defining the data sources of interest, and how they should be processed. NEAR is a new `kind` of data source. + +**schema.graphql:** a schema file that defines what data is stored for your subgraph, and how to query it via GraphQL. The requirements for NEAR subgraphs are covered by [the existing documentation](/developer/create-subgraph-hosted#the-graphql-schema). + +**AssemblyScript Mappings:** [AssemblyScript code](/developer/assemblyscript-api) 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. + +During subgraph development there are two key commands: + +```bash +$ graph codegen # generates types from the schema file identified in the manifest +$ graph build # generates Web Assembly from the AssemblyScript files, and prepares all the subgraph files in a /build folder +``` + +### Subgraph Manifest Definition + +The subgraph manifest (`subgraph.yaml`) identifies the data sources for the subgraph, the triggers of interest, and the functions that should be run in response to those triggers. See below for an example subgraph manifest for a NEAR subgraph:: + +```yaml +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 subgraphs introduce a new `kind` of data source (`near`) +- The `network` should correspond to a network on the hosting Graph Node. On the Hosted Service, 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](https://docs.near.org/docs/concepts/account). This can be an account, or a sub account. + +NEAR data sources support two types of handlers: + +- `blockHandlers`: run on every new NEAR block. No `source.account` is required. +- `receiptHandlers`: run on every receipt where the data source's `source.account` is the recipient. Note that only exact matches are processed ([subaccounts](https://docs.near.org/docs/concepts/account#subaccounts) must be added as independent data sources). + +### Schema Definition + +Schema definition describes the structure of the resulting subgraph database, and the relationships between entities. This is agnostic of the original data source. There are more details on subgraph schema definition [here](/developer/create-subgraph-hosted#the-graphql-schema). + +### AssemblyScript Mappings + +The handlers for processing events are written in [AssemblyScript](https://www.assemblyscript.org/). + +NEAR indexing introduces NEAR-specific data types to the [AssemblyScript API](/developer/assemblyscript-api). + +```typescript + +class ExecutionOutcome { + gasBurnt: u64, + blockHash: Bytes, + id: Bytes, + logs: Array, + receiptIds: Array, + tokensBurnt: BigInt, + executorId: string, + } + +class ActionReceipt { + predecessorId: string, + receiverId: string, + id: CryptoHash, + signerId: string, + gasPrice: BigInt, + outputDataReceivers: Array, + inputDataIds: Array, + actions: Array, + } + +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, + } + +class ReceiptWithOutcome { + outcome: ExecutionOutcome, + receipt: ActionReceipt, + block: Block, + } +``` + +These types are passed to block & receipt handlers: + +- Block handlers will receive a `Block` +- Receipt handlers will receive a `ReceiptWithOutcome` + +Otherwise the rest of the [AssemblyScript API](/developer/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](/developer/assemblyscript-api#json-api) to allow developers to easily process these logs. + +## Deploying a NEAR Subgraph + +Once you have a built subgraph, it is time to deploy it to Graph Node for indexing. NEAR subgraphs can be deployed to any Graph Node `>=v0.26.x` (this version has not yet been tagged & released). + +The Graph's Hosted Service 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 the Hosted Service can be found [here](/hosted-service/deploy-subgraph-hosted). + +As a quick primer - the first step is to "create" your subgraph - this only needs to be done once. On the Hosted Service, this can be done from [your Dashboard](https://thegraph.com/hosted-service/dashboard): "Add Subgraph". + +Once your subgraph has been created, you can deploy your subgraph by using the `graph deploy` CLI command: + +``` +$ graph create --node subgraph/name # creates a subgraph on a local Graph Node (on the Hosted Service, this is done via the UI) +$ graph deploy --node --ipfs https://api.thegraph.com/ipfs/ # 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 +``` + +The node configuration will depend where the subgraph is being deployed. + +#### Hosted Service: + +``` +graph deploy --node https://api.thegraph.com/deploy/ --ipfs https://api.thegraph.com/ipfs/ --access-token +``` + +#### Local Graph Node (based on default configuration): + +``` +graph deploy --node http://localhost:8020/ --ipfs http://localhost:5001 +``` + +Once your subgraph has been deployed, it will be indexed by Graph Node. You can check its progress by querying the subgraph itself: + +``` +{ + _meta { + block { number } + } +} +``` + +### Indexing NEAR with a Local Graph Node + +Running a Graph Node that indexes NEAR has the following operational requirements: + +- NEAR Indexer Framework with Firehose instrumentation +- NEAR Firehose Component(s) +- Graph Node with Firehose endpoint configured + +We will provide more information on running the above components soon. + +## Querying a NEAR Subgraph + +The GraphQL endpoint for NEAR subgraphs is determined by the schema definition, with the existing API interface. Please visit the [GraphQL API documentation](/developer/graphql-api) for more information. + +## Example Subgraphs + +Here are some example subgraphs for reference: + +[NEAR Blocks](https://github.com/graphprotocol/example-subgraph/tree/near-blocks-example) + +[NEAR Receipts](https://github.com/graphprotocol/example-subgraph/tree/near-receipts-example) + +## FAQ + +### How does the beta work? + +NEAR support is in beta, which means that there may be changes to the API as we continue to work on improving the integration. Please email near@thegraph.com so that we can support you in building NEAR subgraphs, and keep you up to date on the latest developments! + +### Can a subgraph index both NEAR and EVM chains? + +No, a subgraph can only support data sources from one chain / network. + +### Can subgraphs react to more specific triggers? + +Currently, only Block and Receipt triggers are supported. We are investigating triggers for function calls to a specified account. We are also interested in supporting event triggers, once NEAR has native event support. + +### Will receipt handlers trigger for accounts and their sub accounts? + +Receipt handlers will only be triggered for the exact-match of the named account. More flexibility may be added in future. + +### Can NEAR subgraphs make view calls to NEAR accounts during mappings? + +This is not supported. We are evaluating whether this functionality is required for indexing. + +### Can I use data source templates in my NEAR subgraph? + +This is not currently supported. We are evaluating whether this functionality is required for indexing. + +### Ethereum subgraphs support "pending" and "current" versions, how can I deploy a "pending" version of a NEAR subgraph? + +Pending functionality is not yet supported for NEAR subgraphs. In the interim, you can deploy a new version to a different "named" subgraph, and then when that is synced with the chain head, you can redeploy to your primary "named" subgraph, which will use the same underlying deployment ID, so the main subgraph will be instantly synced. + +### My question hasn't been answered, where can I get more help building NEAR subgraphs? + +If it is a general question about subgraph development, there is a lot more information in the rest of the [Developer documentation](/developer/quick-start). Otherwise please join [The Graph Protocol Discord](https://discord.gg/vtvv7FP) and ask in the #near channel, or email near@thegraph.com. + +## References + +- [NEAR developer documentation](https://docs.near.org/docs/develop/basics/getting-started) diff --git a/pages/zh/about/introduction.mdx b/pages/zh/about/introduction.mdx new file mode 100644 index 000000000000..5f840c040400 --- /dev/null +++ b/pages/zh/about/introduction.mdx @@ -0,0 +1,47 @@ +--- +title: Introduction +--- + +This page will explain what The Graph is and how you can get started. + +## What The Graph Is + +The Graph is a decentralized protocol for indexing and querying data from blockchains, starting with Ethereum. It makes it possible to query data that is difficult to query directly. + +Projects with complex smart contracts like [Uniswap](https://uniswap.org/) and NFTs initiatives like [Bored Ape Yacht Club](https://boredapeyachtclub.com/) store data on the Ethereum blockchain, making it really difficult to read anything other than basic data directly from the blockchain. + +In the case of Bored Ape Yacht Club, we can perform basic read operations on [the contract](https://etherscan.io/address/0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d#code) like getting the owner of a certain Ape, getting the content URI of an Ape based on their ID, or the total supply, as these read operations are programmed directly into the smart contract, but more advanced real-world queries and operations like aggregation, search, relationships, and non-trivial filtering are not possible. For example, if we wanted to query for apes that are owned by a certain address, and filter by one of its characteristics, we would not be able to get that information by interacting directly with the contract itself. + +To get this data, you would have to process every single [`transfer`](https://etherscan.io/address/0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d#code#L1746) event ever emitted, read the metadata from IPFS using the Token ID and IPFS hash, and then aggregate it. Even for these types of relatively simple questions, it would take **hours or even days** for a decentralized application (dapp) running in a browser to get an answer. + +You could also build out your own server, process the transactions there, save them to a database, and build an API endpoint on top of it all in order to query the data. However, this option is resource intensive, needs maintenance, presents a single point of failure, and breaks important security properties required for decentralization. + +**Indexing blockchain data is really, really hard.** + +Blockchain properties like finality, chain reorganizations, or uncled blocks complicate this process further, and make it not just time consuming but conceptually hard to retrieve correct query results from blockchain data. + +The Graph solves this with a decentralized protocol that indexes and enables the performant and efficient querying of blockchain data. These APIs (indexed "subgraphs") can then be queried with a standard GraphQL API. Today, there is a hosted service as well as a decentralized protocol with the same capabilities. Both are backed by the open source implementation of [Graph Node](https://github.com/graphprotocol/graph-node). + +## How The Graph Works + +The Graph learns what and how to index Ethereum data based on subgraph descriptions, known as the subgraph manifest. The subgraph description defines the smart contracts of interest for a subgraph, the events in those contracts to pay attention to, and how to map event data to data that The Graph will store in its database. + +Once you have written a `subgraph manifest`, you use the Graph CLI to store the definition in IPFS and tell the indexer to start indexing data for that subgraph. + +This diagram gives more detail about the flow of data once a subgraph manifest has been deployed, dealing with Ethereum transactions: + +![](/img/graph-dataflow.png) + +The flow follows these steps: + +1. A decentralized application adds data to Ethereum through a transaction on a smart contract. +2. The smart contract emits one or more events while processing the transaction. +3. Graph Node continually scans Ethereum for new blocks and the data for your subgraph they may contain. +4. Graph Node finds Ethereum events for your subgraph in these blocks and runs the mapping handlers you provided. The mapping is a WASM module that creates or updates the data entities that Graph Node stores in response to Ethereum events. +5. The decentralized application queries the Graph Node for data indexed from the blockchain, using the node's [GraphQL endpoint](https://graphql.org/learn/). The Graph Node in turn translates the GraphQL queries into queries for its underlying data store in order to fetch this data, making use of the store's indexing capabilities. The decentralized application displays this data in a rich UI for end-users, which they use to issue new transactions on Ethereum. The cycle repeats. + +## Next Steps + +In the following sections we will go into more detail on how to define subgraphs, how to deploy them, and how to query data from the indexes that Graph Node builds. + +Before you start writing your own subgraph, you might want to have a look at the Graph Explorer and explore some of the subgraphs that have already been deployed. The page for each subgraph contains a playground that lets you query that subgraph's data with GraphQL. diff --git a/pages/zh/about/network.mdx b/pages/zh/about/network.mdx new file mode 100644 index 000000000000..b19f08d12bc7 --- /dev/null +++ b/pages/zh/about/network.mdx @@ -0,0 +1,15 @@ +--- +title: Network Overview +--- + +The Graph Network is a decentralized indexing protocol for organizing blockchain data. Applications use GraphQL to query open APIs called subgraphs, to retrieve data that is indexed on the network. With The Graph, developers can build serverless applications that run entirely on public infrastructure. + +> GRT Token Address: [0xc944e90c64b2c07662a292be6244bdf05cda44a7](https://etherscan.io/token/0xc944e90c64b2c07662a292be6244bdf05cda44a7) + +## Overview + +The Graph Network consists of Indexers, Curators and Delegators that provide services to the network, and serve data to Web3 applications. Consumers use the applications and consume the data. + +![Token Economics](/img/Network-roles@2x.png) + +To ensure economic security of The Graph Network and the integrity of data being queried, participants stake and use Graph Tokens (GRT). GRT is a work token that is an ERC-20 on the Ethereum blockchain, used to allocate resources in the network. Active Indexers, Curators and Delegators can provide services and earn income from the network, proportional to the amount of work they perform and their GRT stake. diff --git a/pages/zh/curating.mdx b/pages/zh/curating.mdx index b3591a753ebb..f56dd059938c 100644 --- a/pages/zh/curating.mdx +++ b/pages/zh/curating.mdx @@ -49,7 +49,7 @@ Remember that curation is risky. 请做好你的工作，确保你在你信任 因此，如果索引人不得不猜测他们应该索引哪些子图，那么他们赚取强大的查询费用的机会就会很低，因为他们没有办法验证哪些子图是高质量的。 进入策展阶段。 -策展人使 The Graph 网络变得高效，信号是策展人用来让索引人知道一个子图是好的索引的过程，其中 GRT 被存入子图的粘合曲线。 索引人可以从本质上信任策展人的信号，因为一旦发出信号，策展人就会为该子图铸造一个策展份额，使他们有权获得该子图所带来的部分未来查询费用。 策展人通过存入他们的 GRT 来换取子图特定的 ERC20 代币，被称为图谱策划股份（GCS）。 想赚取更多查询费的策展人应该向他们预测会给网络带来大量费用的子图发出他们的 GRT 信号。 策展人不能因为不良行为而被砍掉，但有一个对策展人的存款税，以抑制可能损害网络完整性的不良决策。 如果策展人选择在一个低质量的子图上进行策展，他们也会赚取较少的查询费，因为有较少的查询需要处理，或者有较少的索引人处理这些查询。 请看下面的图! +策展人使 The Graph 网络变得高效，信号是策展人用来让索引人知道一个子图是好的索引的过程，其中 GRT 被存入子图的粘合曲线。 索引人可以从本质上信任策展人的信号，因为一旦发出信号，策展人就会为该子图铸造一个策展份额，使他们有权获得该子图所带来的部分未来查询费用。 Curator signal is represented as ERC20 tokens called Graph Curation Shares (GCS). 想赚取更多查询费的策展人应该向他们预测会给网络带来大量费用的子图发出他们的 GRT 信号。 策展人不能因为不良行为而被砍掉，但有一个对策展人的存款税，以抑制可能损害网络完整性的不良决策。 如果策展人选择在一个低质量的子图上进行策展，他们也会赚取较少的查询费，因为有较少的查询需要处理，或者有较少的索引人处理这些查询。 请看下面的图! ![Signaling diagram](/img/curator-signaling.png) @@ -100,5 +100,5 @@ Remember that curation is risky. 请做好你的工作，确保你在你信任 title="YouTube video player" frameBorder="0" allowFullScreen - > +> diff --git a/pages/zh/delegating.mdx b/pages/zh/delegating.mdx index 7811979f16a6..4702217d5711 100644 --- a/pages/zh/delegating.mdx +++ b/pages/zh/delegating.mdx @@ -2,7 +2,7 @@ title: 委托 --- -This guide will explain how to be an effective delegator in the Graph Network. Delegators share earnings of the protocol alongside all indexers on their delegated stake. A Delegator must use their best judgement to choose Indexers based on multiple factors. Please note this guide will not go over steps such as setting up Metamask properly, as that information is widely available on the internet. There are three sections in this guide: +Delegators cannot be slashed for bad behavior, but there is a deposit tax on Delegators to disincentivize poor decision making that could harm the integrity of the network. ## 委托人指南 @@ -14,7 +14,7 @@ This guide will explain how to be an effective delegator in the Graph Network. D ## 委托风险 -This guide will explain how to be an effective delegator in the Graph Network. Delegators share earnings of the protocol alongside all indexers on their delegated stake. A Delegator must use their best judgement to choose Indexers based on multiple factors. Please note this guide will not go over steps such as setting up Metamask properly, as that information is widely available on the internet. There are three sections in this guide: +Listed below are the main risks of being a delegator in the protocol. ### 委托费用 @@ -28,7 +28,9 @@ This guide will explain how to be an effective delegator in the Graph Network. D 还需要考虑的一件事是明智地选择索引人。 如果您选择了一个不值得信赖的 索引人，或者没有做好工作，您将想要取消委托，这意味着您将失去很多获得奖励的机会，这可能与燃烧 GRT 一样糟糕。 -
请注意委托用户界面中的0.5%费用，以及28天的解约期。
+
+ 请注意委托用户界面中的0.5%费用，以及28天的解约期。 +
### 选择一个为委托人提供公平的奖励分配的值得信赖的索引人 @@ -86,5 +88,5 @@ A delegator can therefore do the math to determine that the Indexer offering 20% title="YouTube video player" frameBorder="0" allowFullScreen - > +> diff --git a/pages/zh/developer/assemblyscript-api.mdx b/pages/zh/developer/assemblyscript-api.mdx new file mode 100644 index 000000000000..a609e6cd657f --- /dev/null +++ b/pages/zh/developer/assemblyscript-api.mdx @@ -0,0 +1,714 @@ +--- +title: AssemblyScript API +--- + +> Note: if you created a subgraph prior to `graph-cli`/`graph-ts` version `0.22.0`, you're using an older version of AssemblyScript, we recommend taking a look at the [`Migration Guide`](/developer/assemblyscript-migration-guide) + +This page documents what built-in APIs can be used when writing subgraph mappings. Two kinds of APIs are available out of the box: + +- the [Graph TypeScript library](https://github.com/graphprotocol/graph-ts) (`graph-ts`) and +- code generated from subgraph files by `graph codegen`. + +It is also possible to add other libraries as dependencies, as long as they are compatible with [AssemblyScript](https://github.com/AssemblyScript/assemblyscript). Since this is the language mappings are written in, the [AssemblyScript wiki](https://github.com/AssemblyScript/assemblyscript/wiki) is a good source for language and standard library features. + +## Installation + +Subgraphs created with [`graph init`](/developer/create-subgraph-hosted) come with preconfigured dependencies. All that is required to install these dependencies is to run one of the following commands: + +```sh +yarn install # Yarn +npm install # NPM +``` + +If the subgraph was created from scratch, one of the following two commands will install the Graph TypeScript library as a dependency: + +```sh +yarn add --dev @graphprotocol/graph-ts # Yarn +npm install --save-dev @graphprotocol/graph-ts # NPM +``` + +## API Reference + +The `@graphprotocol/graph-ts` library provides the following APIs: + +- An `ethereum` API for working with Ethereum smart contracts, events, blocks, transactions, and Ethereum values. +- A `store` API to load and save entities from and to the Graph Node store. +- A `log` API to log messages to the Graph Node output and the Graph Explorer. +- An `ipfs` API to load files from IPFS. +- A `json` API to parse JSON data. +- A `crypto` API to use cryptographic functions. +- Low-level primitives to translate between different type systems such as Ethereum, JSON, GraphQL and AssemblyScript. + +### Versions + +The `apiVersion` in the subgraph manifest specifies the mapping API version which is run by Graph Node for a given subgraph. The current mapping API version is 0.0.6. + +| Version | Release notes | +|:-------:| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 0.0.6 | Added `nonce` field to the Ethereum Transaction object
Added `baseFeePerGas` to the Ethereum Block object | +| 0.0.5 | AssemblyScript upgraded to version 0.19.10 (this includes breaking changes, please see the [`Migration Guide`](/developer/assemblyscript-migration-guide))
`ethereum.transaction.gasUsed` renamed to `ethereum.transaction.gasLimit` | +| 0.0.4 | Added `functionSignature` field to the Ethereum SmartContractCall object | +| 0.0.3 | Added `from` field to the Ethereum Call object
`etherem.call.address` renamed to `ethereum.call.to` | +| 0.0.2 | Added `input` field to the Ethereum Transaction object | + +### Built-in Types + +Documentation on the base types built into AssemblyScript can be found in the [AssemblyScript wiki](https://github.com/AssemblyScript/assemblyscript/wiki/Types). + +The following additional types are provided by `@graphprotocol/graph-ts`. + +#### ByteArray + +```typescript +import { ByteArray } from '@graphprotocol/graph-ts' +``` + +`ByteArray` represents an array of `u8`. + +_Construction_ + +- `fromI32(x: i32): ByteArray` - Decomposes `x` into bytes. +- `fromHexString(hex: string): ByteArray` - Input length must be even. Prefixing with `0x` is optional. + +_Type conversions_ + +- `toHexString(): string` - Converts to a hex string prefixed with `0x`. +- `toString(): string` - Interprets the bytes as a UTF-8 string. +- `toBase58(): string` - Encodes the bytes into a base58 string. +- `toU32(): u32` - Interprets the bytes as a little-endian `u32`. Throws in case of overflow. +- `toI32(): i32` - Interprets the byte array as a little-endian `i32`. Throws in case of overflow. + +_Operators_ + +- `equals(y: ByteArray): bool` – can be written as `x == y`. + +#### BigDecimal + +```typescript +import { BigDecimal } from '@graphprotocol/graph-ts' +``` + +`BigDecimal` is used to represent arbitrary precision decimals. + +_Construction_ + +- `constructor(bigInt: BigInt)` – creates a `BigDecimal` from an `BigInt`. +- `static fromString(s: string): BigDecimal` – parses from a decimal string. + +_Type conversions_ + +- `toString(): string` – prints to a decimal string. + +_Math_ + +- `plus(y: BigDecimal): BigDecimal` – can be written as `x + y`. +- `minus(y: BigDecimal): BigDecimal` – can be written as `x - y`. +- `times(y: BigDecimal): BigDecimal` – can be written as `x * y`. +- `dividedBy(y: BigDecimal): BigDecimal` – can be written as `x / y`. +- `equals(y: BigDecimal): bool` – can be written as `x == y`. +- `notEqual(y: BigDecimal): bool` – can be written as `x != y`. +- `lt(y: BigDecimal): bool` – can be written as `x < y`. +- `le(y: BigDecimal): bool` – can be written as `x <= y`. +- `gt(y: BigDecimal): bool` – can be written as `x > y`. +- `ge(y: BigDecimal): bool` – can be written as `x >= y`. +- `neg(): BigDecimal` - can be written as `-x`. + +#### BigInt + +```typescript +import { BigInt } from '@graphprotocol/graph-ts' +``` + +`BigInt` is used to represent big integers. This includes Ethereum values of type `uint32` to `uint256` and `int64` to `int256`. Everything below `uint32`, such as `int32`, `uint24` or `int8` is represented as `i32`. + +The `BigInt` class has the following API: + +_Construction_ + +- `BigInt.fromI32(x: i32): BigInt` – creates a `BigInt` from an `i32`. +- `BigInt.fromString(s: string): BigInt`– Parses a `BigInt` from a string. +- `BigInt.fromUnsignedBytes(x: Bytes): BigInt` – Interprets `bytes` as an unsigned, little-endian integer. If your input is big-endian, call `.reverse()` first. +- `BigInt.fromSignedBytes(x: Bytes): BigInt` – Interprets `bytes` as a signed, little-endian integer. If your input is big-endian, call `.reverse()` first. + + _Type conversions_ + +- `x.toHex(): string` – turns `BigInt` into a string of hexadecimal characters. +- `x.toString(): string` – turns `BigInt` into a decimal number string. +- `x.toI32(): i32` – returns the `BigInt` as an `i32`; fails if it the value does not fit into `i32`. It's a good idea to first check `x.isI32()`. +- `x.toBigDecimal(): BigDecimal` - converts into a decimal with no fractional part. + +_Math_ + +- `x.plus(y: BigInt): BigInt` – can be written as `x + y`. +- `x.minus(y: BigInt): BigInt` – can be written as `x - y`. +- `x.times(y: BigInt): BigInt` – can be written as `x * y`. +- `x.dividedBy(y: BigInt): BigInt` – can be written as `x / y`. +- `x.mod(y: BigInt): BigInt` – can be written as `x % y`. +- `x.equals(y: BigInt): bool` – can be written as `x == y`. +- `x.notEqual(y: BigInt): bool` – can be written as `x != y`. +- `x.lt(y: BigInt): bool` – can be written as `x < y`. +- `x.le(y: BigInt): bool` – can be written as `x <= y`. +- `x.gt(y: BigInt): bool` – can be written as `x > y`. +- `x.ge(y: BigInt): bool` – can be written as `x >= y`. +- `x.neg(): BigInt` – can be written as `-x`. +- `x.divDecimal(y: BigDecimal): BigDecimal` – divides by a decimal, giving a decimal result. +- `x.isZero(): bool` – Convenience for checking if the number is zero. +- `x.isI32(): bool` – Check if the number fits in an `i32`. +- `x.abs(): BigInt` – Absolute value. +- `x.pow(exp: u8): BigInt` – Exponentiation. +- `bitOr(x: BigInt, y: BigInt): BigInt` – can be written as `x | y`. +- `bitAnd(x: BigInt, y: BigInt): BigInt` – can be written as `x & y`. +- `leftShift(x: BigInt, bits: u8): BigInt` – can be written as `x << y`. +- `rightShift(x: BigInt, bits: u8): BigInt` – can be written as `x >> y`. + +#### TypedMap + +```typescript +import { TypedMap } from '@graphprotocol/graph-ts' +``` + +`TypedMap` can be used to stored key-value pairs. See [this example](https://github.com/graphprotocol/aragon-subgraph/blob/29dd38680c5e5104d9fdc2f90e740298c67e4a31/individual-dao-subgraph/mappings/constants.ts#L51). + +The `TypedMap` class has the following API: + +- `new TypedMap()` – creates an empty map with keys of type `K` and values of type `T` +- `map.set(key: K, value: V): void` – sets the value of `key` to `value` +- `map.getEntry(key: K): TypedMapEntry | null` – returns the key-value pair for a `key` or `null` if the `key` does not exist in the map +- `map.get(key: K): V | null` – returns the value for a `key` or `null` if the `key` does not exist in the map +- `map.isSet(key: K): bool` – returns `true` if the `key` exists in the map and `false` if it does not + +#### Bytes + +```typescript +import { Bytes } from '@graphprotocol/graph-ts' +``` + +`Bytes` is used to represent arbitrary-length arrays of bytes. This includes Ethereum values of type `bytes`, `bytes32` etc. + +The `Bytes` class extends AssemblyScript's [Uint8Array](https://github.com/AssemblyScript/assemblyscript/blob/3b1852bc376ae799d9ebca888e6413afac7b572f/std/assembly/typedarray.ts#L64) and this supports all the `Uint8Array` functionality, plus the following new methods: + +- `b.toHex()` – returns a hexadecimal string representing the bytes in the array +- `b.toString()` – converts the bytes in the array to a string of unicode characters +- `b.toBase58()` – turns an Ethereum Bytes value to base58 encoding (used for IPFS hashes) + +#### Address + +```typescript +import { Address } from '@graphprotocol/graph-ts' +``` + +`Address` extends `Bytes` to represent Ethereum `address` values. + +It adds the following method on top of the `Bytes` API: + +- `Address.fromString(s: string): Address` – creates an `Address` from a hexadecimal string + +### Store API + +```typescript +import { store } from '@graphprotocol/graph-ts' +``` + +The `store` API allows to load, save and remove entities from and to the Graph Node store. + +Entities written to the store map one-to-one to the `@entity` types defined in the subgraph's GraphQL schema. To make working with these entities convenient, the `graph codegen` command provided by the [Graph CLI](https://github.com/graphprotocol/graph-cli) generates entity classes, which are subclasses of the built-in `Entity` type, with property getters and setters for the fields in the schema as well as methods to load and save these entities. + +#### Creating entities + +The following is a common pattern for creating entities from Ethereum events. + +```typescript +// Import the Transfer event class generated from the ERC20 ABI +import { Transfer as TransferEvent } from '../generated/ERC20/ERC20' + +// Import the Transfer entity type generated from the GraphQL schema +import { Transfer } from '../generated/schema' + +// Transfer event handler +export function handleTransfer(event: TransferEvent): void { + // Create a Transfer entity, using the hexadecimal string representation + // of the transaction hash as the entity ID + let id = event.transaction.hash.toHex() + let transfer = new Transfer(id) + + // Set properties on the entity, using the event parameters + transfer.from = event.params.from + transfer.to = event.params.to + transfer.amount = event.params.amount + + // Save the entity to the store + transfer.save() +} +``` + +When a `Transfer` event is encountered while processing the chain, it is passed to the `handleTransfer` event handler using the generated `Transfer` type (aliased to `TransferEvent` here to avoid a naming conflict with the entity type). This type allows accessing data such as the event's parent transaction and its parameters. + +Each entity must have a unique ID to avoid collisions with other entities. It is fairly common for event parameters to include a unique identifier that can be used. Note: Using the transaction hash as the ID assumes that no other events in the same transaction create entities with this hash as the ID. + +#### Loading entities from the store + +If an entity already exists, it can be loaded from the store with the following: + +```typescript +let id = event.transaction.hash.toHex() // or however the ID is constructed +let transfer = Transfer.load(id) +if (transfer == null) { + transfer = new Transfer(id) +} + +// Use the Transfer entity as before +``` + +As the entity may not exist in the store yet, the `load` method returns a value of type `Transfer | null`. It may thus be necessary to check for the `null` case before using the value. + +> **Note:** Loading entities is only necessary if the changes made in the mapping depend on the previous data of an entity. See the next section for the two ways of updating existing entities. + +#### Updating existing entities + +There are two ways to update an existing entity: + +1. Load the entity with e.g. `Transfer.load(id)`, set properties on the entity, then `.save()` it back to the store. +2. Simply create the entity with e.g. `new Transfer(id)`, set properties on the entity, then `.save()` it to the store. If the entity already exists, the changes are merged into it. + +Changing properties is straight forward in most cases, thanks to the generated property setters: + +```typescript +let transfer = new Transfer(id) +transfer.from = ... +transfer.to = ... +transfer.amount = ... +``` + +It is also possible to unset properties with one of the following two instructions: + +```typescript +transfer.from.unset() +transfer.from = null +``` + +This only works with optional properties, i.e. properties that are declared without a `!` in GraphQL. Two examples would be `owner: Bytes` or `amount: BigInt`. + +Updating array properties is a little more involved, as the getting an array from an entity creates a copy of that array. This means array properties have to be set again explicitly after changing the array. The following assumes `entity` has a `numbers: [BigInt!]!` field. + +```typescript +// This won't work +entity.numbers.push(BigInt.fromI32(1)) +entity.save() + +// This will work +let numbers = entity.numbers +numbers.push(BigInt.fromI32(1)) +entity.numbers = numbers +entity.save() +``` + +#### Removing entities from the store + +There is currently no way to remove an entity via the generated types. Instead, removing an entity requires passing the name of the entity type and the entity ID to `store.remove`: + +```typescript +import { store } from '@graphprotocol/graph-ts' +... +let id = event.transaction.hash.toHex() +store.remove('Transfer', id) +``` + +### Ethereum API + +The Ethereum API provides access to smart contracts, public state variables, contract functions, events, transactions, blocks and the encoding/decoding Ethereum data. + +#### Support for Ethereum Types + +As with entities, `graph codegen` generates classes for all smart contracts and events used in a subgraph. For this, the contract ABIs need to be part of the data source in the subgraph manifest. Typically, the ABI files are stored in an `abis/` folder. + +With the generated classes, conversions between Ethereum types and the [built-in types](#built-in-types) take place behind the scenes so that subgraph authors do not have to worry about them. + +The following example illustrates this. Given a subgraph schema like + +```graphql +type Transfer @entity { + from: Bytes! + to: Bytes! + amount: BigInt! +} +``` + +and a `Transfer(address,address,uint256)` event signature on Ethereum, the `from`, `to` and `amount` values of type `address`, `address` and `uint256` are converted to `Address` and `BigInt`, allowing them to be passed on to the `Bytes!` and `BigInt!` properties of the `Transfer` entity: + +```typescript +let id = event.transaction.hash.toHex() +let transfer = new Transfer(id) +transfer.from = event.params.from +transfer.to = event.params.to +transfer.amount = event.params.amount +transfer.save() +``` + +#### Events and Block/Transaction Data + +Ethereum events passed to event handlers, such as the `Transfer` event in the previous examples, not only provide access to the event parameters but also to their parent transaction and the block they are part of. The following data can be obtained from `event` instances (these classes are a part of the `ethereum` module in `graph-ts`): + +```typescript +class Event { + address: Address + logIndex: BigInt + transactionLogIndex: BigInt + logType: string | null + block: Block + transaction: Transaction + parameters: Array +} + +class Block { + hash: Bytes + parentHash: Bytes + unclesHash: Bytes + author: Address + stateRoot: Bytes + transactionsRoot: Bytes + receiptsRoot: Bytes + number: BigInt + gasUsed: BigInt + gasLimit: BigInt + timestamp: BigInt + difficulty: BigInt + totalDifficulty: BigInt + size: BigInt | null + baseFeePerGas: BigInt | null +} + +class Transaction { + hash: Bytes + index: BigInt + from: Address + to: Address | null + value: BigInt + gasLimit: BigInt + gasPrice: BigInt + input: Bytes + nonce: BigInt +} +``` + +#### Access to Smart Contract State + +The code generated by `graph codegen` also includes classes for the smart contracts used in the subgraph. These can be used to access public state variables and call functions of the contract at the current block. + +A common pattern is to access the contract from which an event originates. This is achieved with the following code: + +```typescript +// Import the generated contract class +import { ERC20Contract } from '../generated/ERC20Contract/ERC20Contract' +// Import the generated entity class +import { Transfer } from '../generated/schema' + +export function handleTransfer(event: Transfer) { + // Bind the contract to the address that emitted the event + let contract = ERC20Contract.bind(event.address) + + // Access state variables and functions by calling them + let erc20Symbol = contract.symbol() +} +``` + +As long as the `ERC20Contract` on Ethereum has a public read-only function called `symbol`, it can be called with `.symbol()`. For public state variables a method with the same name is created automatically. + +Any other contract that is part of the subgraph can be imported from the generated code and can be bound to a valid address. + +#### Handling Reverted Calls + +If the read-only methods of your contract may revert, then you should handle that by calling the generated contract method prefixed with `try_`. For example, the Gravity contract exposes the `gravatarToOwner` method. This code would be able to handle a revert in that method: + +```typescript +let gravity = Gravity.bind(event.address) +let callResult = gravity.try_gravatarToOwner(gravatar) +if (callResult.reverted) { + log.info('getGravatar reverted', []) +} else { + let owner = callResult.value +} +``` + +Note that a Graph node connected to a Geth or Infura client may not detect all reverts, if you rely on this we recommend using a Graph node connected to a Parity client. + +#### Encoding/Decoding ABI + +Data can be encoded and decoded according to Ethereum's ABI encoding format using the `encode` and `decode` functions in the `ethereum` module. + +```typescript +import { Address, BigInt, ethereum } from '@graphprotocol/graph-ts' + +let tupleArray: Array = [ + ethereum.Value.fromAddress(Address.fromString('0x0000000000000000000000000000000000000420')), + ethereum.Value.fromUnsignedBigInt(BigInt.fromI32(62)), +] + +let tuple = tupleArray as ethereum.Tuple + +let encoded = ethereum.encode(ethereum.Value.fromTuple(tuple))! + +let decoded = ethereum.decode('(address,uint256)', encoded) +``` + +For more information: + +- [ABI Spec](https://docs.soliditylang.org/en/v0.7.4/abi-spec.html#types) +- Encoding/decoding [Rust library/CLI](https://github.com/rust-ethereum/ethabi) +- More [complex example](https://github.com/graphprotocol/graph-node/blob/6a7806cc465949ebb9e5b8269eeb763857797efc/tests/integration-tests/host-exports/src/mapping.ts#L72). + +### Logging API + +```typescript +import { log } from '@graphprotocol/graph-ts' +``` + +The `log` API allows subgraphs to log information to the Graph Node standard output as well as the Graph Explorer. Messages can be logged using different log levels. A basic format string syntax is provided to compose log messages from argument. + +The `log` API includes the following functions: + +- `log.debug(fmt: string, args: Array): void` - logs a debug message. +- `log.info(fmt: string, args: Array): void` - logs an informational message. +- `log.warning(fmt: string, args: Array): void` - logs a warning. +- `log.error(fmt: string, args: Array): void` - logs an error message. +- `log.critical(fmt: string, args: Array): void` – logs a critical message _and_ terminates the subgraph. + +The `log` API takes a format string and an array of string values. It then replaces placeholders with the string values from the array. The first `{}` placeholder gets replaced by the first value in the array, the second `{}` placeholder gets replaced by the second value and so on. + +```typescript +log.info('Message to be displayed: {}, {}, {}', [value.toString(), anotherValue.toString(), 'already a string']) +``` + +#### Logging one or more values + +##### Logging a single value + +In the example below, the string value "A" is passed into an array to become`['A']` before being logged: + +```typescript +let myValue = 'A' + +export function handleSomeEvent(event: SomeEvent): void { + // Displays : "My value is: A" + log.info('My value is: {}', [myValue]) +} +``` + +##### Logging a single entry from an existing array + +In the example below, only the first value of the argument array is logged, despite the array containing three values. + +```typescript +let myArray = ['A', 'B', 'C'] + +export function handleSomeEvent(event: SomeEvent): void { + // Displays : "My value is: A" (Even though three values are passed to `log.info`) + log.info('My value is: {}', myArray) +} +``` + +#### Logging multiple entries from an existing array + +Each entry in the arguments array requires its own placeholder `{}` in the log message string. The below example contains three placeholders `{}` in the log message. Because of this, all three values in `myArray` are logged. + +```typescript +let myArray = ['A', 'B', 'C'] + +export function handleSomeEvent(event: SomeEvent): void { + // Displays : "My first value is: A, second value is: B, third value is: C" + log.info('My first value is: {}, second value is: {}, third value is: {}', myArray) +} +``` + +##### Logging a specific entry from an existing array + +To display a specific value in the array, the indexed value must be provided. + +```typescript +export function handleSomeEvent(event: SomeEvent): void { + // Displays : "My third value is C" + log.info('My third value is: {}', [myArray[2]]) +} +``` + +##### Logging event information + +The example below logs the block number, block hash and transaction hash from an event: + +```typescript +import { log } from '@graphprotocol/graph-ts' + +export function handleSomeEvent(event: SomeEvent): void { + log.debug('Block number: {}, block hash: {}, transaction hash: {}', [ + event.block.number.toString(), // "47596000" + event.block.hash.toHexString(), // "0x..." + event.transaction.hash.toHexString(), // "0x..." + ]) +} +``` + +### IPFS API + +```typescript +import { ipfs } from '@graphprotocol/graph-ts' +``` + +Smart contracts occasionally anchor IPFS files on chain. This allows mappings to obtain the IPFS hashes from the contract and read the corresponding files from IPFS. The file data will be returned as `Bytes`, which usually requires further processing, e.g. with the `json` API documented later on this page. + +Given an IPFS hash or path, reading a file from IPFS is done as follows: + +```typescript +// Put this inside an event handler in the mapping +let hash = 'QmTkzDwWqPbnAh5YiV5VwcTLnGdwSNsNTn2aDxdXBFca7D' +let data = ipfs.cat(hash) + +// Paths like `QmTkzDwWqPbnAh5YiV5VwcTLnGdwSNsNTn2aDxdXBFca7D/Makefile` +// that include files in directories are also supported +let path = 'QmTkzDwWqPbnAh5YiV5VwcTLnGdwSNsNTn2aDxdXBFca7D/Makefile' +let data = ipfs.cat(path) +``` + +**Note:** `ipfs.cat` is not deterministic at the moment. If the file cannot be retrieved over the IPFS network before the request times out, it will return `null`. Due to this, it's always worth checking the result for `null`. To ensure that files can be retrieved, they have to be pinned to the IPFS node that Graph Node connects to. On the [hosted service](https://thegraph.com/hosted-service), this is [https://api.thegraph.com/ipfs/](https://api.thegraph.com/ipfs). See the [IPFS pinning](/developer/create-subgraph-hosted#ipfs-pinning) section for more information. + +It is also possible to process larger files in a streaming fashion with `ipfs.map`. The function expects the hash or path for an IPFS file, the name of a callback, and flags to modify its behavior: + +```typescript +import { JSONValue, Value } from '@graphprotocol/graph-ts' + +export function processItem(value: JSONValue, userData: Value): void { + // See the JSONValue documentation for details on dealing + // with JSON values + let obj = value.toObject() + let id = obj.get('id') + let title = obj.get('title') + + if (!id || !title) { + return + } + + // Callbacks can also created entities + let newItem = new Item(id.toString()) + newItem.title = title.toString() + newitem.parent = userData.toString() // Set parent to "parentId" + newitem.save() +} + +// Put this inside an event handler in the mapping +ipfs.map('Qm...', 'processItem', Value.fromString('parentId'), ['json']) + +// Alternatively, use `ipfs.mapJSON` +ipfs.mapJSON('Qm...', 'processItem', Value.fromString('parentId')) +``` + +The only flag currently supported is `json`, which must be passed to `ipfs.map`. With the `json` flag, the IPFS file must consist of a series of JSON values, one value per line. The call to `ipfs.map` will read each line in the file, deserialize it into a `JSONValue` and call the callback for each of them. The callback can then use entity operations to store data from the `JSONValue`. Entity changes are stored only when the handler that called `ipfs.map` finishes successfully; in the meantime, they are kept in memory, and the size of the file that `ipfs.map` can process is therefore limited. + +On success, `ipfs.map` returns `void`. If any invocation of the callback causes an error, the handler that invoked `ipfs.map` is aborted, and the subgraph is marked as failed. + +### Crypto API + +```typescript +import { crypto } from '@graphprotocol/graph-ts' +``` + +The `crypto` API makes a cryptographic functions available for use in mappings. Right now, there is only one: + +- `crypto.keccak256(input: ByteArray): ByteArray` + +### JSON API + +```typescript +import { json, JSONValueKind } from '@graphprotocol/graph-ts' +``` + +JSON data can be parsed using the `json` API: + +- `json.fromBytes(data: Bytes): JSONValue` – parses JSON data from a `Bytes` array +- `json.try_fromBytes(data: Bytes): Result` – safe version of `json.fromBytes`, it returns an error variant if the parsing failed +- `json.fromString(data: Bytes): JSONValue` – parses JSON data from a valid UTF-8 `String` +- `json.try_fromString(data: Bytes): Result` – safe version of `json.fromString`, it returns an error variant if the parsing failed + +The `JSONValue` class provides a way to pull values out of an arbitrary JSON document. Since JSON values can be booleans, numbers, arrays and more, `JSONValue` comes with a `kind` property to check the type of a value: + +```typescript +let value = json.fromBytes(...) +if (value.kind == JSONValueKind.BOOL) { + ... +} +``` + +In addition, there is a method to check if the value is `null`: + +- `value.isNull(): boolean` + +When the type of a value is certain, it can be converted to a [built-in type](#built-in-types) using one of the following methods: + +- `value.toBool(): boolean` +- `value.toI64(): i64` +- `value.toF64(): f64` +- `value.toBigInt(): BigInt` +- `value.toString(): string` +- `value.toArray(): Array` - (and then convert `JSONValue` with one of the 5 methods above) + +### Type Conversions Reference + +| Source(s) | Destination | Conversion function | +| -------------------- | -------------------- | ---------------------------- | +| Address | Bytes | none | +| Address | ID | s.toHexString() | +| Address | String | s.toHexString() | +| BigDecimal | String | s.toString() | +| BigInt | BigDecimal | s.toBigDecimal() | +| BigInt | String (hexadecimal) | s.toHexString() or s.toHex() | +| BigInt | String (unicode) | s.toString() | +| BigInt | i32 | s.toI32() | +| Boolean | Boolean | none | +| Bytes (signed) | BigInt | BigInt.fromSignedBytes(s) | +| Bytes (unsigned) | BigInt | BigInt.fromUnsignedBytes(s) | +| Bytes | String (hexadecimal) | s.toHexString() or s.toHex() | +| Bytes | String (unicode) | s.toString() | +| Bytes | String (base58) | s.toBase58() | +| Bytes | i32 | s.toI32() | +| Bytes | u32 | s.toU32() | +| Bytes | JSON | json.fromBytes(s) | +| int8 | i32 | none | +| int32 | i32 | none | +| int32 | BigInt | Bigint.fromI32(s) | +| uint24 | i32 | none | +| int64 - int256 | BigInt | none | +| uint32 - uint256 | BigInt | none | +| JSON | boolean | s.toBool() | +| JSON | i64 | s.toI64() | +| JSON | u64 | s.toU64() | +| JSON | f64 | s.toF64() | +| JSON | BigInt | s.toBigInt() | +| JSON | string | s.toString() | +| JSON | Array | s.toArray() | +| JSON | Object | s.toObject() | +| String | Address | Address.fromString(s) | +| String | BigDecimal | BigDecimal.fromString(s) | +| String (hexadecimal) | Bytes | ByteArray.fromHexString(s) | +| String (UTF-8) | Bytes | ByteArray.fromUTF8(s) | + +### Data Source Metadata + +You can inspect the contract address, network and context of the data source that invoked the handler through the `dataSource` namespace: + +- `dataSource.address(): Address` +- `dataSource.network(): string` +- `dataSource.context(): DataSourceContext` + +### Entity and DataSourceContext + +The base `Entity` class and the child `DataSourceContext` class have helpers to dynamically set and get fields: + +- `setString(key: string, value: string): void` +- `setI32(key: string, value: i32): void` +- `setBigInt(key: string, value: BigInt): void` +- `setBytes(key: string, value: Bytes): void` +- `setBoolean(key: string, value: bool): void` +- `setBigDecimal(key, value: BigDecimal): void` +- `getString(key: string): string` +- `getI32(key: string): i32` +- `getBigInt(key: string): BigInt` +- `getBytes(key: string): Bytes` +- `getBoolean(key: string): boolean` +- `getBigDecimal(key: string): BigDecimal` diff --git a/pages/zh/developer/assemblyscript-migration-guide.mdx b/pages/zh/developer/assemblyscript-migration-guide.mdx new file mode 100644 index 000000000000..2db90a608110 --- /dev/null +++ b/pages/zh/developer/assemblyscript-migration-guide.mdx @@ -0,0 +1,484 @@ +--- +title: AssemblyScript Migration Guide +--- + +Up until now, subgraphs have been using one of the [first versions of AssemblyScript](https://github.com/AssemblyScript/assemblyscript/tree/v0.6) (v0.6). Finally we've added support for the [newest one available](https://github.com/AssemblyScript/assemblyscript/tree/v0.19.10) (v0.19.10)! 🎉 + +That will enable subgraph developers to use newer features of the AS language and standard library. + +This guide is applicable for anyone using `graph-cli`/`graph-ts` below version `0.22.0`. If you're already at a higher than (or equal) version to that, you've already been using version `0.19.10` of AssemblyScript 🙂 + +> Note: As of `0.24.0`, `graph-node` can support both versions, depending on the `apiVersion` specified in the subgraph manifest. + +## Features + +### New functionality + +- `TypedArray`s can now be built from `ArrayBuffer`s by using the [new `wrap` static method](https://www.assemblyscript.org/stdlib/typedarray.html#static-members) ([v0.8.1](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.8.1)) +- New standard library functions: `String#toUpperCase`, `String#toLowerCase`, `String#localeCompare`and `TypedArray#set` ([v0.9.0](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.9.0)) +- Added support for x instanceof GenericClass ([v0.9.2](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.9.2)) +- Added `StaticArray`, a more efficient array variant ([v0.9.3](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.9.3)) +- Added `Array#flat` ([v0.10.0](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.10.0)) +- Implemented `radix` argument on `Number#toString` ([v0.10.1](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.10.1)) +- Added support for separators in floating point literals ([v0.13.7](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.13.7)) +- Added support for first class functions ([v0.14.0](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.14.0)) +- Add builtins: `i32/i64/f32/f64.add/sub/mul` ([v0.14.13](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.14.13)) +- Implement `Array/TypedArray/String#at` ([v0.18.2](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.18.2)) +- Added support for template literal strings ([v0.18.17](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.18.17)) +- Add `encodeURI(Component)` and `decodeURI(Component)` ([v0.18.27](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.18.27)) +- Add `toString`, `toDateString` and `toTimeString` to `Date` ([v0.18.29](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.18.29)) +- Add `toUTCString` for `Date` ([v0.18.30](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.18.30)) +- Add `nonnull/NonNullable` builtin type ([v0.19.2](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.19.2)) + +### Optimizations + +- `Math` functions such as `exp`, `exp2`, `log`, `log2` and `pow` have been replaced by faster variants ([v0.9.0](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.9.0)) +- Slightly optimize `Math.mod` ([v0.17.1](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.17.1)) +- Cache more field accesses in std Map and Set ([v0.17.8](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.17.8)) +- Optimize for powers of two in `ipow32/64` ([v0.18.2](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.18.2)) + +### Other + +- The type of an array literal can now be inferred from its contents ([v0.9.0](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.9.0)) +- Updated stdlib to Unicode 13.0.0 ([v0.10.0](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.10.0)) + +## How to upgrade? + +1. Change your mappings `apiVersion` in `subgraph.yaml` to `0.0.6`: + +```yaml +... +dataSources: + ... + mapping: + ... + apiVersion: 0.0.6 + ... +``` + +2. Update the `graph-cli` you're using to the `latest` version by running: + +```bash +# if you have it globally installed +npm install --global @graphprotocol/graph-cli@latest + +# or in your subgraph if you have it as a dev dependency +npm install --save-dev @graphprotocol/graph-cli@latest +``` + +3. Do the same for `graph-ts`, but instead of installing globally, save it in your main dependencies: + +```bash +npm install --save @graphprotocol/graph-ts@latest +``` + +4. Follow the rest of the guide to fix the language breaking changes. +5. Run `codegen` and `deploy` again. + +## Breaking changes + +### Nullability + +On the older version of AssemblyScript, you could create code like this: + +```typescript +function load(): Value | null { ... } + +let maybeValue = load(); +maybeValue.aMethod(); +``` + +However on the newer version, because the value is nullable, it requires you to check, like this: + +```typescript +let maybeValue = load() + +if (maybeValue) { + maybeValue.aMethod() // `maybeValue` is not null anymore +} +``` + +Or force it like this: + +```typescript +let maybeValue = load()! // breaks in runtime if value is null + +maybeValue.aMethod() +``` + +If you are unsure which to choose, we recommend always using the safe version. If the value doesn't exist you might want to just do an early if statement with a return in you subgraph handler. + +### Variable Shadowing + +Before you could do [variable shadowing](https://en.wikipedia.org/wiki/Variable_shadowing) and code like this would work: + +```typescript +let a = 10 +let b = 20 +let a = a + b +``` + +However now this isn't possible anymore, and the compiler returns this error: + +```typescript +ERROR TS2451: Cannot redeclare block-scoped variable 'a' + + let a = a + b; + ~~~~~~~~~~~~~ +in assembly/index.ts(4,3) +``` +You'll need to rename your duplicate variables if you had variable shadowing. +### Null Comparisons +By doing the upgrade on your subgraph, sometimes you might get errors like these: + +```typescript +ERROR TS2322: Type '~lib/@graphprotocol/graph-ts/common/numbers/BigInt | null' is not assignable to type '~lib/@graphprotocol/graph-ts/common/numbers/BigInt'. + if (decimals == null) { + ~~~~ + in src/mappings/file.ts(41,21) +``` +To solve you can simply change the `if` statement to something like this: + +```typescript + if (!decimals) { + + // or + + if (decimals === null) { +``` + +The same applies if you're doing != instead of ==. + +### Casting + +The common way to do casting before was to just use the `as` keyword, like this: + +```typescript +let byteArray = new ByteArray(10) +let uint8Array = byteArray as Uint8Array // equivalent to: byteArray +``` + +However this only works in two scenarios: + +- Primitive casting (between types such as `u8`, `i32`, `bool`; eg: `let b: isize = 10; b as usize`); +- Upcasting on class inheritance (subclass → superclass) + +Examples: + +```typescript +// primitive casting +let a: usize = 10 +let b: isize = 5 +let c: usize = a + (b as usize) +``` + +```typescript +// upcasting on class inheritance +class Bytes extends Uint8Array {} + +let bytes = new Bytes(2) < Uint8Array > bytes // same as: bytes as Uint8Array +``` + +There are two scenarios where you may want to cast, but using `as`/`var` **isn't safe**: + +- Downcasting on class inheritance (superclass → subclass) +- Between two types that share a superclass + +```typescript +// downcasting on class inheritance +class Bytes extends Uint8Array {} + +let uint8Array = new Uint8Array(2) < Bytes > uint8Array // breaks in runtime :( +``` + +```typescript +// between two types that share a superclass +class Bytes extends Uint8Array {} +class ByteArray extends Uint8Array {} + +let bytes = new Bytes(2) < ByteArray > bytes // breaks in runtime :( +``` + +For those cases, you can use the `changetype` function: + +```typescript +// downcasting on class inheritance +class Bytes extends Uint8Array {} + +let uint8Array = new Uint8Array(2) +changetype(uint8Array) // works :) +``` + +```typescript +// between two types that share a superclass +class Bytes extends Uint8Array {} +class ByteArray extends Uint8Array {} + +let bytes = new Bytes(2) +changetype(bytes) // works :) +``` + +If you just want to remove nullability, you can keep using the `as` operator (or `variable`), but make sure you know that value can't be null, otherwise it will break. + +```typescript +// remove nullability +let previousBalance = AccountBalance.load(balanceId) // AccountBalance | null + +if (previousBalance != null) { + return previousBalance as AccountBalance // safe remove null +} + +let newBalance = new AccountBalance(balanceId) +``` + +For the nullability case we recommend taking a look at the [nullability check feature](https://www.assemblyscript.org/basics.html#nullability-checks), it will make your code cleaner 🙂 + +Also we've added a few more static methods in some types to ease casting, they are: + +- Bytes.fromByteArray +- Bytes.fromUint8Array +- BigInt.fromByteArray +- ByteArray.fromBigInt + +### Nullability check with property access + +To use the [nullability check feature](https://www.assemblyscript.org/basics.html#nullability-checks) you can use either `if` statements or the ternary operator (`?` and `:`) like this: + +```typescript +let something: string | null = 'data' + +let somethingOrElse = something ? something : 'else' + +// or + +let somethingOrElse + +if (something) { + somethingOrElse = something +} else { + somethingOrElse = 'else' +} +``` + +However that only works when you're doing the `if` / ternary on a variable, not on a property access, like this: + +```typescript +class Container { + data: string | null +} + +let container = new Container() +container.data = 'data' + +let somethingOrElse: string = container.data ? container.data : 'else' // doesn't compile +``` + +Which outputs this error: + +```typescript +ERROR TS2322: Type '~lib/string/String | null' is not assignable to type '~lib/string/String'. + + let somethingOrElse: string = container.data ? container.data : "else"; + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +``` +To fix this issue, you can create a variable for that property access so that the compiler can do the nullability check magic: + +```typescript +class Container { + data: string | null +} + +let container = new Container() +container.data = 'data' + +let data = container.data + +let somethingOrElse: string = data ? data : 'else' // compiles just fine :) +``` + +### Operator overloading with property access + +If you try to sum (for example) a nullable type (from a property access) with a non nullable one, the AssemblyScript compiler instead of giving a compile time error warning that one of the values is nullable, it just compiles silently, giving chance for the code to break at runtime. + +```typescript +class BigInt extends Uint8Array { + @operator('+') + plus(other: BigInt): BigInt { + // ... + } +} + +class Wrapper { + public constructor(public n: BigInt | null) {} +} + +let x = BigInt.fromI32(2) +let y: BigInt | null = null + +x + y // give compile time error about nullability + +let wrapper = new Wrapper(y) + +wrapper.n = wrapper.n + x // doesn't give compile time errors as it should +``` + +We've opened a issue on the AssemblyScript compiler for this, but for now if you do these kind of operations in your subgraph mappings, you should change them to do a null check before it. + +```typescript +let wrapper = new Wrapper(y) + +if (!wrapper.n) { + wrapper.n = BigInt.fromI32(0) +} + +wrapper.n = wrapper.n + x // now `n` is guaranteed to be a BigInt +``` + +### Value initialization + +If you have any code like this: + +```typescript +var value: Type // null +value.x = 10 +value.y = 'content' +``` + +It will compile but break at runtime, that happens because the value hasn't been initialized, so make sure your subgraph has initialized their values, like this: + +```typescript +var value = new Type() // initialized +value.x = 10 +value.y = 'content' +``` + +Also if you have nullable properties in a GraphQL entity, like this: + +```graphql +type Total @entity { + id: ID! + amount: BigInt +} +``` + +And you have code similar to this: + +```typescript +let total = Total.load('latest') + +if (total === null) { + total = new Total('latest') +} + +total.amount = total.amount + BigInt.fromI32(1) +``` + +You'll need to make sure to initialize the `total.amount` value, because if you try to access like in the last line for the sum, it will crash. So you either initialize it first: + +```typescript +let total = Total.load('latest') + +if (total === null) { + total = new Total('latest') + total.amount = BigInt.fromI32(0) +} + +total.tokens = total.tokens + BigInt.fromI32(1) +``` + +Or you can just change your GraphQL schema to not use a nullable type for this property, then we'll initialize it as zero on the `codegen` step 😉 + +```graphql +type Total @entity { + id: ID! + amount: BigInt! +} +``` + +```typescript +let total = Total.load('latest') + +if (total === null) { + total = new Total('latest') // already initializes non-nullable properties +} + +total.amount = total.amount + BigInt.fromI32(1) +``` + +### Class property initialization + +If you export any classes with properties that are other classes (declared by you or by the standard library) like this: + +```typescript +class Thing {} + +export class Something { + value: Thing +} +``` + +The compiler will error because you either need to add an initializer for the properties that are classes, or add the `!` operator: + +```typescript +export class Something { + constructor(public value: Thing) {} +} + +// or + +export class Something { + value: Thing + + constructor(value: Thing) { + this.value = value + } +} + +// or + +export class Something { + value!: Thing +} +``` + +### GraphQL schema + +This is not a direct AssemblyScript change, but you may have to update your `schema.graphql` file. + +Now you no longer can define fields in your types that are Non-Nullable Lists. If you have a schema like this: + +```graphql +type Something @entity { + id: ID! +} + +type MyEntity @entity { + id: ID! + invalidField: [Something]! # no longer valid +} +``` + +You'll have to add an `!` to the member of the List type, like this: + +```graphql +type Something @entity { + id: ID! +} + +type MyEntity @entity { + id: ID! + invalidField: [Something!]! # valid +} +``` + +This changed because of nullability differences between AssemblyScript versions, and it's related to the `src/generated/schema.ts` file (default path, you might have changed this). + +### Other + +- Aligned `Map#set` and `Set#add` with the spec, returning `this` ([v0.9.2](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.9.2)) +- Arrays no longer inherit from ArrayBufferView, but are now distinct ([v0.10.0](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.10.0)) +- Classes initialized from object literals can no longer define a constructor ([v0.10.0](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.10.0)) +- The result of a `**` binary operation is now the common denominator integer if both operands are integers. Previously, the result was a float as if calling `Math/f.pow` ([v0.11.0](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.11.0)) +- Coerce `NaN` to `false` when casting to `bool` ([v0.14.9](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.14.9)) +- When shifting a small integer value of type `i8`/`u8` or `i16`/`u16`, only the 3 respectively 4 least significant bits of the RHS value affect the result, analogous to the result of an `i32.shl` only being affected by the 5 least significant bits of the RHS value. Example: `someI8 << 8` previously produced the value `0`, but now produces `someI8` due to masking the RHS as `8 & 7 = 0` (3 bits) ([v0.17.0](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.17.0)) +- Bug fix of relational string comparisons when sizes differ ([v0.17.8](https://github.com/AssemblyScript/assemblyscript/releases/tag/v0.17.8)) diff --git a/pages/zh/developer/create-subgraph-hosted.mdx b/pages/zh/developer/create-subgraph-hosted.mdx new file mode 100644 index 000000000000..6b235e379634 --- /dev/null +++ b/pages/zh/developer/create-subgraph-hosted.mdx @@ -0,0 +1,928 @@ +--- +title: Create a Subgraph +--- + +Before being able to use the Graph CLI, you need to create your subgraph in [Subgraph Studio](https://thegraph.com/studio). You will then be able to setup your subgraph project and deploy it to the platform of your choice. Note that **subgraphs that do not index Ethereum mainnet will not be published to The Graph Network**. + +The `graph init` command can be used to set up a new subgraph project, either from an existing contract on any of the public Ethereum networks, or from an example subgraph. This command can be used to create a subgraph on the Subgraph Studio by passing in `graph init --product subgraph-studio`. If you already have a smart contract deployed to Ethereum mainnet or one of the testnets, bootstrapping a new subgraph from that contract can be a good way to get started. But first, a little about the networks The Graph supports. + +## Supported Networks + +The Graph Network supports subgraphs indexing mainnet Ethereum: + +- `mainnet` + +**Additional Networks are supported in beta on the Hosted Service**: + +- `mainnet` +- `kovan` +- `rinkeby` +- `ropsten` +- `goerli` +- `poa-core` +- `poa-sokol` +- `xdai` +- `near-mainnet` +- `near-testnet` +- `matic` +- `mumbai` +- `fantom` +- `bsc` +- `chapel` +- `clover` +- `avalanche` +- `fuji` +- `celo` +- `celo-alfajores` +- `fuse` +- `moonriver` +- `mbase` +- `arbitrum-one` +- `arbitrum-rinkeby` +- `optimism` +- `optimism-kovan` +- `aurora` +- `aurora-testnet` + +The Graph's Hosted Service relies on the stability and reliability of the underlying technologies, namely the provided JSON RPC endpoints. Newer networks will be marked as being in beta until the network has proven itself in terms of stability, reliability, and scalability. During this beta period, there is risk of downtime and unexpected behaviour. + +Remember that you will **not be able** to publish a subgraph that indexes a non-mainnet network to the decentralized Graph Network in [Subgraph Studio](/studio/subgraph-studio). + +## From An Existing Contract + +The following command creates a subgraph that indexes all events of an existing contract. It attempts to fetch the contract ABI from Etherscan and falls back to requesting a local file path. If any of the optional arguments are missing, it takes you through an interactive form. + +```sh +graph init \ + --product subgraph-studio + --from-contract \ + [--network ] \ + [--abi ] \ + [] +``` + +The `` is the ID of your subgraph in Subgraph Studio, it can be found on your subgraph details page. + +## From An Example Subgraph + +The second mode `graph init` supports is creating a new project from an example subgraph. The following command does this: + +``` +graph init --studio +``` + +The example subgraph is based on the Gravity contract by Dani Grant that manages user avatars and emits `NewGravatar` or `UpdateGravatar` events whenever avatars are created or updated. The subgraph handles these events by writing `Gravatar` entities to the Graph Node store and ensuring these are updated according to the events. The following sections will go over the files that make up the subgraph manifest for this example. + +## The Subgraph Manifest + +The subgraph manifest `subgraph.yaml` defines the smart contracts your subgraph indexes, which 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 full specification for subgraph manifests can be found [here](https://github.com/graphprotocol/graph-node/blob/master/docs/subgraph-manifest.md). + +For the example subgraph, `subgraph.yaml` is: + +```yaml +specVersion: 0.0.4 +description: Gravatar for Ethereum +repository: https://github.com/graphprotocol/example-subgraph +schema: + file: ./schema.graphql +dataSources: + - kind: ethereum/contract + name: Gravity + network: mainnet + source: + address: '0x2E645469f354BB4F5c8a05B3b30A929361cf77eC' + abi: Gravity + startBlock: 6175244 + mapping: + kind: ethereum/events + apiVersion: 0.0.6 + language: wasm/assemblyscript + entities: + - Gravatar + abis: + - name: Gravity + file: ./abis/Gravity.json + eventHandlers: + - event: NewGravatar(uint256,address,string,string) + handler: handleNewGravatar + - event: UpdatedGravatar(uint256,address,string,string) + handler: handleUpdatedGravatar + callHandlers: + - function: createGravatar(string,string) + handler: handleCreateGravatar + blockHandlers: + - function: handleBlock + - function: handleBlockWithCall + filter: + kind: call + file: ./src/mapping.ts +``` + +The important entries to update for the manifest are: + +- `description`: a human-readable description of what the subgraph is. This description is displayed by the Graph Explorer when the subgraph is deployed to the Hosted Service. + +- `repository`: the URL of the repository where the subgraph manifest can be found. This is also displayed by the Graph Explorer. + +- `features`: a list of all used [feature](#experimental-features) names. + +- `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.mapping.entities`: the entities that the data source writes to the store. The schema for each entity is defined in the 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 filter can be provided with the following kinds: call`. A`call` filter will 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. + +The triggers for a data source within a block are ordered using the following process: + +1. Event and call triggers are first ordered by transaction index within the block. +2. Event and call triggers with in the same transaction are ordered using a convention: event triggers first then call triggers, each type respecting the order they are defined in the manifest. +3. Block triggers are run after event and call triggers, in the order they are defined in the manifest. + +These ordering rules are subject to change. + +### Getting The ABIs + +The ABI file(s) must match your contract(s). There are a few ways to obtain ABI files: + +- If you are building your own project, you will likely have access to your most current ABIs. +- If you are building a subgraph for a public project, you can download that project to your computer and get the ABI by using [`truffle compile`](https://truffleframework.com/docs/truffle/overview) or using solc to compile. +- You can also find the ABI on [Etherscan](https://etherscan.io/), but this isn't always reliable, as the ABI that is uploaded there may be out of date. Make sure you have the right ABI, otherwise running your subgraph will fail. + +## The GraphQL Schema + +The schema for your subgraph is in the file `schema.graphql`. GraphQL schemas are defined using the GraphQL interface definition language. If you've never written a GraphQL schema, it is recommended that you check out this primer on the GraphQL type system. Reference documentation for GraphQL schemas can be found in the [GraphQL API](/developer/graphql-api) section. + +## Defining Entities + +Before defining entities, it is important to take a step back and think about how your data is structured and linked. All queries will be made against the data model defined in the subgraph schema and the entities indexed by the subgraph. Because of this, it is good to define the subgraph schema in a way that matches the needs of your dapp. It may be useful to imagine entities as "objects containing data", rather than as events or functions. + +With The Graph, you simply define entity types in `schema.graphql`, and Graph Node will generate top level fields for querying single instances and collections of that entity type. Each type that should be an entity is required to be annotated with an `@entity` directive. + +### Good Example + +The `Gravatar` entity below is structured around a Gravatar object and is a good example of how an entity could be defined. + +```graphql +type Gravatar @entity { + id: ID! + owner: Bytes + displayName: String + imageUrl: String + accepted: Boolean +} +``` + +### Bad Example + +The example `GravatarAccepted` and `GravatarDeclined` entities below are based around events. It is not recommended to map events or function calls to entities 1:1. + +```graphql +type GravatarAccepted @entity { + id: ID! + owner: Bytes + displayName: String + imageUrl: String +} + +type GravatarDeclined @entity { + id: ID! + owner: Bytes + displayName: String + imageUrl: String +} +``` + +### Optional and Required Fields + +Entity fields can be defined as required or optional. Required fields are indicated by the `!` in the schema. If a required field is not set in the mapping, you will receive this error when querying the field: + +``` +Null value resolved for non-null field 'name' +``` + +Each entity must have an `id` field, which is of type `ID!` (string). The `id` field serves as the primary key, and needs to be unique among all entities of the same type. + +### Built-In Scalar Types + +#### GraphQL Supported Scalars + +We support the following scalars in our GraphQL API: + +| Type | Description | +| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `Bytes` | Byte array, represented as a hexadecimal string. Commonly used for Ethereum hashes and addresses. | +| `ID` | Stored as a `string`. | +| `String` | Scalar for `string` values. Null characters are not supported and are automatically removed. | +| `Boolean` | Scalar for `boolean` values. | +| `Int` | The GraphQL spec defines `Int` to have size of 32 bytes. | +| `BigInt` | Large integers. Used for Ethereum's `uint32`, `int64`, `uint64`, ..., `uint256` types. Note: Everything below `uint32`, such as `int32`, `uint24` or `int8` is represented as `i32`. | +| `BigDecimal` | `BigDecimal` High precision decimals represented as a signficand and an exponent. The exponent range is from −6143 to +6144. Rounded to 34 significant digits. | + +#### Enums + +You can also create enums within a schema. Enums have the following syntax: + +```graphql +enum TokenStatus { + OriginalOwner + SecondOwner + ThirdOwner +} +``` + +Once the enum is defined in the schema, you can use the string representation of the enum value to set an enum field on an entity. For example, you can set the `tokenStatus` to `SecondOwner` by first defining your entity and subsequently setting the field with `entity.tokenStatus = "SecondOwner`. The example below demonstrates what the Token entity would look like with an enum field: + +More detail on writing enums can be found in the [GraphQL documentation](https://graphql.org/learn/schema/). + +#### Entity Relationships + +An entity may have a relationship to one or more other entities in your schema. These relationships may be traversed in your queries. Relationships in The Graph are unidirectional. It is possible to simulate bidirectional relationships by defining a unidirectional relationship on either "end" of the relationship. + +Relationships are defined on entities just like any other field except that the type specified is that of another entity. + +#### One-To-One Relationships + +Define a `Transaction` entity type with an optional one-to-one relationship with a `TransactionReceipt` entity type: + +```graphql +type Transaction @entity { + id: ID! + transactionReceipt: TransactionReceipt +} + +type TransactionReceipt @entity { + id: ID! + transaction: Transaction +} +``` + +#### One-To-Many Relationships + +Define a `TokenBalance` entity type with a required one-to-many relationship with a Token entity type: + +```graphql +type Token @entity { + id: ID! +} + +type TokenBalance @entity { + id: ID! + amount: Int! + token: Token! +} +``` + +#### Reverse Lookups + +Reverse lookups can be defined on an entity through the `@derivedFrom` field. This creates a virtual field on the entity that may be queried but cannot be set manually through the mappings API. Rather, it is derived from the relationship defined on the other entity. For such relationships, it rarely makes sense to store both sides of the relationship, and both indexing and query performance will be better when only one side is stored and the other is derived. + +For one-to-many relationships, the relationship should always be stored on the 'one' side, and the 'many' side should always be derived. Storing the relationship this way, rather than storing an array of entities on the 'many' side, will result in dramatically better performance for both indexing and querying the subgraph. In general, storing arrays of entities should be avoided as much as is practical. + +#### Example + +We can make the balances for a token accessible from the token by deriving a `tokenBalances` field: + +```graphql +type Token @entity { + id: ID! + tokenBalances: [TokenBalance!]! @derivedFrom(field: "token") +} + +type TokenBalance @entity { + id: ID! + amount: Int! + token: Token! +} +``` + +#### Many-To-Many Relationships + +For many-to-many relationships, such as users that each may belong to any number of organizations, the most straightforward, but generally not the most performant, way to model the relationship is as an array in each of the two entities involved. If the relationship is symmetric, only one side of the relationship needs to be stored and the other side can be derived. + +#### Example + +Define a reverse lookup from a `User` entity type to an `Organization` entity type. In the example below, this is achieved by looking up the `members` attribute from within the `Organization` entity. In queries, the `organizations` field on `User` will be resolved by finding all `Organization` entities that include the user's ID. + +```graphql +type Organization @entity { + id: ID! + name: String! + members: [User!]! +} + +type User @entity { + id: ID! + name: String! + organizations: [Organization!]! @derivedFrom(field: "members") +} +``` + +A more performant way to store this relationship is through a mapping table that has one entry for each `User` / `Organization` pair with a schema like + +```graphql +type Organization @entity { + id: ID! + name: String! + members: [UserOrganization]! @derivedFrom(field: "user") +} + +type User @entity { + id: ID! + name: String! + organizations: [UserOrganization!] @derivedFrom(field: "organization") +} + +type UserOrganization @entity { + id: ID! # Set to `${user.id}-${organization.id}` + user: User! + organization: Organization! +} +``` + +This approach requires that queries descend into one additional level to retrieve, for example, the organizations for users: + +```graphql +query usersWithOrganizations { + users { + organizations { + # this is a UserOrganization entity + organization { + name + } + } + } +} +``` + +This more elaborate way of storing many-to-many relationships will result in less data stored for the subgraph, and therefore to a subgraph that is often dramatically faster to index and to query. + +#### Adding comments to the schema + +As per GraphQL spec, comments can be added above schema entity attributes using double quotations `""`. This is illustrated in the example below: + +```graphql +type MyFirstEntity @entity { + "unique identifier and primary key of the entity" + id: ID! + address: Bytes! +} +``` + +## Defining Fulltext Search Fields + +Fulltext search queries filter and rank entities based on a text search input. Fulltext queries are able to return matches for similar words by processing the query text input into stems before comparing to the indexed text data. + +A fulltext query definition includes the query name, the language dictionary used to process the text fields, the ranking algorithm used to order the results, and the fields included in the search. Each fulltext query may span multiple fields, but all included fields must be from a single entity type. + +To add a fulltext query, include a `_Schema_` type with a fulltext directive in the GraphQL schema. + +```graphql +type _Schema_ + @fulltext( + name: "bandSearch" + language: en + algorithm: rank + include: [{ entity: "Band", fields: [{ name: "name" }, { name: "description" }, { name: "bio" }] }] + ) + +type Band @entity { + id: ID! + name: String! + description: String! + bio: String + wallet: Address + labels: [Label!]! + discography: [Album!]! + members: [Musician!]! +} +``` + +The example `bandSearch` field can be used in queries to filter `Band` entities based on the text documents in the `name`, `description`, and `bio` fields. Jump to [GraphQL API - Queries](/developer/graphql-api#queries) for a description of the Fulltext search API and for more example usage. + +```graphql +query { + bandSearch(text: "breaks & electro & detroit") { + id + name + description + wallet + } +} +``` + +> **[Feature Management](#experimental-features):** From `specVersion` `0.0.4` and onwards, `fullTextSearch` must be declared under the `features` section in the subgraph manifest. + +### Languages supported + +Choosing a different language will have a definitive, though sometimes subtle, effect on the fulltext search API. Fields covered by a fulltext query field are examined in the context of the chosen language, so the lexemes produced by analysis and search queries vary language to language. For example: when using the supported Turkish dictionary "token" is stemmed to "toke" while, of course, the English dictionary will stem it to "token". + +Supported language dictionaries: + +| Code | Dictionary | +| ------ | ---------- | +| simple | General | +| da | Danish | +| nl | Dutch | +| en | English | +| fi | Finnish | +| fr | French | +| de | German | +| hu | Hungarian | +| it | Italian | +| no | Norwegian | +| pt | Portugese | +| ro | Romanian | +| ru | Russian | +| es | Spanish | +| sv | Swedish | +| tr | Turkish | + +### Ranking Algorithms + +Supported algorithms for ordering results: + +| Algorithm | Description | +| ------------- | ----------------------------------------------------------------------- | +| rank | Use the match quality (0-1) of the fulltext query to order the results. | +| proximityRank | Similar to rank but also includes the proximity of the matches. | + +## Writing Mappings + +The mappings transform the Ethereum data your mappings are sourcing into entities defined in your schema. Mappings are written in a subset of [TypeScript](https://www.typescriptlang.org/docs/handbook/typescript-in-5-minutes.html) called [AssemblyScript](https://github.com/AssemblyScript/assemblyscript/wiki) which can be compiled to WASM ([WebAssembly](https://webassembly.org/)). AssemblyScript is stricter than normal TypeScript, yet provides a familiar syntax. + +For each event handler that is defined in `subgraph.yaml` under `mapping.eventHandlers`, create an exported function of the same name. Each handler must accept a single parameter called `event` with a type corresponding to the name of the event which is being handled. + +In the example subgraph, `src/mapping.ts` contains handlers for the `NewGravatar` and `UpdatedGravatar` events: + +```javascript +import { NewGravatar, UpdatedGravatar } from '../generated/Gravity/Gravity' +import { Gravatar } from '../generated/schema' + +export function handleNewGravatar(event: NewGravatar): void { + let gravatar = new Gravatar(event.params.id.toHex()) + gravatar.owner = event.params.owner + gravatar.displayName = event.params.displayName + gravatar.imageUrl = event.params.imageUrl + gravatar.save() +} + +export function handleUpdatedGravatar(event: UpdatedGravatar): void { + let id = event.params.id.toHex() + let gravatar = Gravatar.load(id) + if (gravatar == null) { + gravatar = new Gravatar(id) + } + gravatar.owner = event.params.owner + gravatar.displayName = event.params.displayName + gravatar.imageUrl = event.params.imageUrl + gravatar.save() +} +``` + +The first handler takes a `NewGravatar` event and creates a new `Gravatar` entity with `new Gravatar(event.params.id.toHex())`, populating the entity fields using the corresponding event parameters. This entity instance is represented by the variable `gravatar`, with an id value of `event.params.id.toHex()`. + +The second handler tries to load the existing `Gravatar` from the Graph Node store. If it does not exist yet, it is created on demand. The entity is then updated to match the new event parameters, before it is saved back to the store using `gravatar.save()`. + +### Recommended IDs for Creating New Entities + +Every entity has to have an `id` that is unique among all entities of the same type. An entity's `id` value is set when the entity is created. Below are some recommended `id` values to consider when creating new entities. NOTE: The value of `id` must be a `string`. + +- `event.params.id.toHex()` +- `event.transaction.from.toHex()` +- `event.transaction.hash.toHex() + "-" + event.logIndex.toString()` + +We provide the [Graph Typescript Library](https://github.com/graphprotocol/graph-ts) which contains utilies for interacting with the Graph Node store and conveniences for handling smart contract data and entities. You can use this library in your mappings by importing `@graphprotocol/graph-ts` in `mapping.ts`. + +## Code Generation + +In order to make working smart contracts, events and entities easy and type-safe, the Graph CLI can generate AssemblyScript types from the subgraph's GraphQL schema and the contract ABIs included in the data sources. + +This is done with + +```sh +graph codegen [--output-dir ] [] +``` + +but in most cases, subgraphs are already preconfigured via `package.json` to allow you to simply run one of the following to achieve the same: + +```sh +# Yarn +yarn codegen + +# NPM +npm run codegen +``` + +This will generate an AssemblyScript class for every smart contract in the ABI files mentioned in `subgraph.yaml`, allowing you to bind these contracts to specific addresses in the mappings and call read-only contract methods against the block being processed. It will also generate a class for every contract event to provide easy access to event parameters as well as the block and transaction the event originated from. All of these types are written to `//.ts`. In the example subgraph, this would be `generated/Gravity/Gravity.ts`, allowing mappings to import these types with + +```javascript +import { + // The contract class: + Gravity, + // The events classes: + NewGravatar, + UpdatedGravatar, +} from '../generated/Gravity/Gravity' +``` + +In addition to this, one class is generated for each entity type in the subgraph's GraphQL schema. These classes provide type-safe entity loading, read and write access to entity fields as well as a `save()` method to write entities to store. All entity classes are written to `/schema.ts`, allowing mappings to import them with + +```javascript +import { Gravatar } from '../generated/schema' +``` + +> **Note:** The code generation must be performed again after every change to the GraphQL schema or the ABIs included in the manifest. It must also be performed at least once before building or deploying the subgraph. + +Code generation does not check your mapping code in `src/mapping.ts`. If you want to check that before trying to deploy your subgraph to the Graph Explorer, you can run `yarn build` and fix any syntax errors that the TypeScript compiler might find. + +## Data Source Templates + +A common pattern in Ethereum smart contracts is the use of registry or factory contracts, where one contract creates, manages or references an arbitrary number of other contracts that each have their own state and events. 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_. + +### Data Source for the Main Contract + +First, you define a regular data source for the main contract. The snippet below shows a simplified example data source for the [Uniswap](https://uniswap.io) exchange factory contract. Note the `NewExchange(address,address)` event handler. This is emitted when a new exchange contract is created on chain by the factory contract. + +```yaml +dataSources: + - kind: ethereum/contract + name: Factory + network: mainnet + source: + address: '0xc0a47dFe034B400B47bDaD5FecDa2621de6c4d95' + abi: Factory + mapping: + kind: ethereum/events + apiVersion: 0.0.6 + language: wasm/assemblyscript + file: ./src/mappings/factory.ts + entities: + - Directory + abis: + - name: Factory + file: ./abis/factory.json + eventHandlers: + - event: NewExchange(address,address) + handler: handleNewExchange +``` + +### Data Source Templates for Dynamically Created Contracts + +Then, you add _data source templates_ to the manifest. These are identical to regular data sources, except that they lack a predefined contract address under `source`. Typically, you would define one template for each type of sub-contract managed or referenced by the parent contract. + +```yaml +dataSources: + - kind: ethereum/contract + name: Factory + # ... other source fields for the main contract ... +templates: + - name: Exchange + kind: ethereum/contract + network: mainnet + source: + abi: Exchange + mapping: + kind: ethereum/events + apiVersion: 0.0.6 + language: wasm/assemblyscript + file: ./src/mappings/exchange.ts + entities: + - Exchange + abis: + - name: Exchange + file: ./abis/exchange.json + eventHandlers: + - event: TokenPurchase(address,uint256,uint256) + handler: handleTokenPurchase + - event: EthPurchase(address,uint256,uint256) + handler: handleEthPurchase + - event: AddLiquidity(address,uint256,uint256) + handler: handleAddLiquidity + - event: RemoveLiquidity(address,uint256,uint256) + handler: handleRemoveLiquidity +``` + +### Instantiating a Data Source Template + +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. + +```typescript +import { Exchange } from '../generated/templates' + +export function handleNewExchange(event: NewExchange): void { + // Start indexing the exchange; `event.params.exchange` is the + // address of the new exchange contract + Exchange.create(event.params.exchange) +} +``` + +> **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. +> +> If prior blocks contain data relevant to the new data source, it is best to index that data by reading the current state of the contract and creating entities representing that state at the time the new data source is created. + +### Data Source Context + +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: + +```typescript +import { Exchange } from '../generated/templates' + +export function handleNewExchange(event: NewExchange): void { + let context = new DataSourceContext() + context.setString('tradingPair', event.params.tradingPair) + Exchange.createWithContext(event.params.exchange, context) +} +``` + +Inside a mapping of the `Exchange` template, the context can then be accessed: + +```typescript +import { dataSource } from '@graphprotocol/graph-ts' + +let context = dataSource.context() +let tradingPair = context.getString('tradingPair') +``` + +There are setters and getters like `setString` and `getString` for all value types. + +## Start Blocks + +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. + +```yaml +dataSources: + - kind: ethereum/contract + name: ExampleSource + network: mainnet + source: + address: '0xc0a47dFe034B400B47bDaD5FecDa2621de6c4d95' + abi: ExampleContract + startBlock: 6627917 + mapping: + kind: ethereum/events + apiVersion: 0.0.6 + language: wasm/assemblyscript + file: ./src/mappings/factory.ts + entities: + - User + abis: + - name: ExampleContract + file: ./abis/ExampleContract.json + eventHandlers: + - event: NewEvent(address,address) + handler: handleNewEvent +``` + +> **Note:** The contract creation block can be quickly looked up on Etherscan: +> +> 1. Search for the contract by entering its address in the search bar. +> 2. Click on the creation transaction hash in the `Contract Creator` section. +> 3. Load the transaction details page where you'll find the start block for that contract. + +## Call Handlers + +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. + +Call handlers will only trigger in one of two cases: when the function specified is called by an account other than the contract itself or when it is marked as external in Solidity and called as part of another function in the same contract. + +> **Note:** Call handlers are not supported on Rinkeby, Goerli or Ganache. Call handlers currently depend on the Parity tracing API and these networks do not support it. + +### Defining a Call Handler + +To define a call handler in your manifest simply add a `callHandlers` array under the data source you would like to subscribe to. + +```yaml +dataSources: + - kind: ethereum/contract + name: Gravity + network: mainnet + source: + address: '0x731a10897d267e19b34503ad902d0a29173ba4b1' + abi: Gravity + mapping: + kind: ethereum/events + apiVersion: 0.0.6 + language: wasm/assemblyscript + entities: + - Gravatar + - Transaction + abis: + - name: Gravity + file: ./abis/Gravity.json + callHandlers: + - function: createGravatar(string,string) + 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. + +### Mapping Function + +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: + +```typescript +import { CreateGravatarCall } from '../generated/Gravity/Gravity' +import { Transaction } from '../generated/schema' + +export function handleCreateGravatar(call: CreateGravatarCall): void { + let id = call.transaction.hash.toHex() + let transaction = new Transaction(id) + transaction.displayName = call.inputs._displayName + transaction.imageUrl = call.inputs._imageUrl + transaction.save() +} +``` + +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`. + +## Block Handlers + +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 predefined filter. + +### Supported Filters + +```yaml +filter: + 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._ + +The absense of a filter for a block handler will ensure that the handler is called every block. A data source can only contain one block handler for each filter type. + +```yaml +dataSources: + - kind: ethereum/contract + name: Gravity + network: dev + source: + address: '0x731a10897d267e19b34503ad902d0a29173ba4b1' + abi: Gravity + mapping: + kind: ethereum/events + apiVersion: 0.0.6 + language: wasm/assemblyscript + entities: + - Gravatar + - Transaction + abis: + - name: Gravity + file: ./abis/Gravity.json + blockHandlers: + - handler: handleBlock + - handler: handleBlockWithCallToContract + filter: + kind: call +``` + +### Mapping Function + +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. + +```typescript +import { ethereum } from '@graphprotocol/graph-ts' + +export function handleBlock(block: ethereum.Block): void { + let id = block.hash.toHex() + let entity = new Block(id) + entity.save() +} +``` + +## Anonymous Events + +If you need to process anonymous events in Solidity, that can be achieved by providing the topic 0 of the event, as in the example: + +```yaml +eventHandlers: + - event: LogNote(bytes4,address,bytes32,bytes32,uint256,bytes) + topic0: '0xbaa8529c00000000000000000000000000000000000000000000000000000000' + 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. + +## Experimental features + +Starting from `specVersion` `0.0.4`, subgraph features must be explicitly declared in the `features` section at the top level of the manifest file, using their `camelCase` name, as listed in the table below: + +| Feature | Name | +| --------------------------------------------------------- | ------------------------- | +| [Non-fatal errors](#non-fatal-errors) | `nonFatalErrors` | +| [Full-text Search](#defining-fulltext-search-fields) | `fullTextSearch` | +| [Grafting](#grafting-onto-existing-subgraphs) | `grafting` | +| [IPFS on Ethereum Contracts](#ipfs-on-ethereum-contracts) | `ipfsOnEthereumContracts` | + +For instance, if a subgraph uses the **Full-Text Search** and the **Non-fatal Errors** features, the `features` field in the manifest should be: + +```yaml +specVersion: 0.0.4 +description: Gravatar for Ethereum +features: + - fullTextSearch + - nonFatalErrors +dataSources: ... +``` + +Note that using a feature without declaring it will incur in a **validation error** during subgraph deployment, but no errors will occur if a feature is declared but not used. + +### IPFS on Ethereum Contracts + +A common use case for combining IPFS with Ethereum is to store data on IPFS that would be too expensive to maintain on chain, and reference the IPFS hash in Ethereum contracts. + +Given such IPFS hashes, subgraphs can read the corresponding files from IPFS using `ipfs.cat` and `ipfs.map`. To do this reliably, however, it is required that these files are pinned on the IPFS node that the Graph Node indexing the subgraph connects to. In the case of the [hosted service](https://thegraph.com/hosted-service), this is [https://api.thegraph.com/ipfs/](https://api.thegraph.com/ipfs/). + +> **Note:** The Graph Network does not yet support `ipfs.cat` and `ipfs.map`, and developers should not deploy subgraphs using that functionality to the network via the Studio. + +In order to make this easy for subgraph developers, The Graph team wrote a tool for transfering files from one IPFS node to another, called [ipfs-sync](https://github.com/graphprotocol/ipfs-sync). + +> **[Feature Management](#experimental-features):** `ipfsOnEthereumContracts` must be declared under `features` in the subgraph manifest. + +### Non-fatal errors + +Indexing errors on already synced subgraphs will, by default, cause the subgraph to fail and stop syncing. Subgraphs can alternatively be configured to continue syncing in the presence of errors, by ignoring the changes made by the handler which provoked the error. This gives subgraph authors time to correct their subgraphs while queries continue to be served against the latest block, though the results will possibly be inconsistent due to the bug that caused the error. Note that some errors are still always fatal, to be non-fatal the error must be known to be deterministic. + +> **Note:** The Graph Network does not yet support non-fatal errors, and developers should not deploy subgraphs using that functionality to the network via the Studio. + +Enabling non-fatal errors requires setting the following feature flag on the subgraph manifest: + +```yaml +specVersion: 0.0.4 +description: Gravatar for Ethereum +features: + - fullTextSearch + ... +``` + +The query must also opt-in to querying data with potential inconsistencies through the `subgraphError` argument. It is also recommended to query `_meta` to check if the subgraph has skipped over errors, as in the example: + +```graphql +foos(first: 100, subgraphError: allow) { + id +} + +_meta { + hasIndexingErrors +} +``` + +If the subgraph encounters an error that query will return both the data and a graphql error with the message `"indexing_error"`, as in this example response: + +```graphql +"data": { + "foos": [ + { + "id": "fooId" + } + ], + "_meta": { + "hasIndexingErrors": true + } +}, +"errors": [ + { + "message": "indexing_error" + } +] +``` + +### Grafting onto Existing Subgraphs + +When a subgraph is first deployed, it starts indexing events at the genesis block of the corresponding chain (or at the `startBlock` defined with each data source) In some circumstances, it is beneficial to reuse the data from an existing subgraph and start indexing at a much later block. This mode of indexing is called _Grafting_. Grafting is, for example, useful during development to get past simple errors in the mappings quickly, or to temporarily get an existing subgraph working again after it has failed. + +> **Note:** Grafting requires that the Indexer has indexed the base subgraph. It is not recommended on The Graph Network at this time, and developers should not deploy subgraphs using that functionality to the network via the Studio. + +A subgraph is grafted onto a base subgraph when the subgraph manifest in `subgraph.yaml` contains a `graft` block at the toplevel: + +```yaml +description: ... +graft: + base: Qm... # Subgraph ID of base subgraph + block: 7345624 # Block number +``` + +When a subgraph whose manifest contains a `graft` block is deployed, Graph Node will copy the data of the `base` subgraph up to and including the given `block` and then continue indexing the new subgraph from that block on. The base subgraph must exist on the target Graph Node instance and must have indexed up to at least the given block. Because of this restriction, grafting should only be used during development or during an emergency to speed up producing an equivalent non-grafted subgraph. + +Because grafting copies rather than indexes base data it is much quicker in getting the subgraph to the desired block than indexing from scratch, though the initial data copy can still take several hours for very large subgraphs. While the grafted subgraph is being initialized, the Graph Node will log information about the entity types that have already been copied. + +The grafted subgraph can use a GraphQL schema that is not identical to the one of the base subgraph, but merely compatible with it. It has to be a valid subgraph schema in its own right but may deviate from the base subgraph's schema in the following ways: + +- It adds or removes entity types +- It removes attributes from entity types +- It adds nullable attributes to entity types +- It turns non-nullable attributes into nullable attributes +- It adds values to enums +- It adds or removes interfaces +- It changes for which entity types an interface is implemented + +> **[Feature Management](#experimental-features):** `grafting` must be declared under `features` in the subgraph manifest. diff --git a/pages/zh/developer/define-subgraph-hosted.mdx b/pages/zh/developer/define-subgraph-hosted.mdx new file mode 100644 index 000000000000..92bf5bd8cd2f --- /dev/null +++ b/pages/zh/developer/define-subgraph-hosted.mdx @@ -0,0 +1,35 @@ +--- +title: Define a Subgraph +--- + +A subgraph defines which data The Graph will index from Ethereum, and how it will store it. Once deployed, it will form a part of a global graph of blockchain data. + +![Define a Subgraph](/img/define-subgraph.png) + +The subgraph definition consists of a few files: + +- `subgraph.yaml`: a YAML file containing the subgraph manifest + +- `schema.graphql`: a GraphQL schema that defines what data is stored for your subgraph, and how to query it via GraphQL + +- `AssemblyScript Mappings`: [AssemblyScript](https://github.com/AssemblyScript/assemblyscript) code that translates from the event data to the entities defined in your schema (e.g. `mapping.ts` in this tutorial) + +Before you go into detail about the contents of the manifest file, you need to install the [Graph CLI](https://github.com/graphprotocol/graph-cli) which you will need to build and deploy a subgraph. + +## Install the Graph CLI + +The Graph CLI is written in JavaScript, and you will need to install either `yarn` or `npm` to use it; it is assumed that you have yarn in what follows. + +Once you have `yarn`, install the Graph CLI by running + +**Install with yarn:** + +```bash +yarn global add @graphprotocol/graph-cli +``` + +**Install with npm:** + +```bash +npm install -g @graphprotocol/graph-cli +``` diff --git a/pages/zh/developer/deprecating-a-subgraph.mdx b/pages/zh/developer/deprecating-a-subgraph.mdx new file mode 100644 index 000000000000..f8966e025c13 --- /dev/null +++ b/pages/zh/developer/deprecating-a-subgraph.mdx @@ -0,0 +1,17 @@ +--- +title: Deprecating a Subgraph +--- + +So you'd like to deprecate your subgraph on The Graph Explorer. You've come to the right place! Follow the steps below: + +1. Visit the contract address [here](https://etherscan.io/address/0xadca0dd4729c8ba3acf3e99f3a9f471ef37b6825#writeProxyContract) +2. Call 'deprecateSubgraph' with your own address as the first parameter +3. In the 'subgraphNumber' field, list 0 if it's the first subgraph you're publishing, 1 if it's your second, 2 if it's your third, etc. +4. Inputs for #2 and #3 can be found in your `` which is composed of the `{graphAccount}-{subgraphNumber}`. For example, the [Sushi Subgraph's](https://thegraph.com/explorer/subgraph?id=0x4bb4c1b0745ef7b4642feeccd0740dec417ca0a0-0&version=0x4bb4c1b0745ef7b4642feeccd0740dec417ca0a0-0-0&view=Overview) ID is `<0x4bb4c1b0745ef7b4642feeccd0740dec417ca0a0-0>`, which is a combination of `graphAccount` = `<0x4bb4c1b0745ef7b4642feeccd0740dec417ca0a0>` and `subgraphNumber` = `<0>` +5. Voila! Your subgraph will no longer show up on searches on The Graph Explorer. Please note the following: + +- Curators will not be able to signal on the subgraph anymore +- Curators that already signaled on the subgraph will be able to withdraw their signal at an average share price +- Deprecated subgraphs will be indicated with an error message. + +If you interacted with the now deprecated subgraph, you'll be able to find it in your user profile under the "Subgraphs", "Indexing", or "Curating" tab respectively. diff --git a/pages/zh/developer/developer-faq.mdx b/pages/zh/developer/developer-faq.mdx new file mode 100644 index 000000000000..41449c60e5ab --- /dev/null +++ b/pages/zh/developer/developer-faq.mdx @@ -0,0 +1,172 @@ +--- +title: Developer FAQs +--- + +### 1. Can I delete my subgraph? + +It is not possible to delete subgraphs once they are created. + +### 2. Can I change my subgraph name? + +No. Once a subgraph is created, the name cannot be changed. Make sure to think of this carefully before you create your subgraph so it is easily searchable and identifiable by other dapps. + +### 3. Can I change the GitHub account associated with my subgraph? + +No. Once a subgraph is created, the associated GitHub account cannot be changed. Make sure to think of this carefully before you create your subgraph. + +### 4. Am I still able to create a subgraph if my smart contracts don't have events? + +It is highly recommended that you structure your smart contracts to have events associated with data you are interested in querying. Event handlers in the subgraph are triggered by contract events, and are by far the fastest way to retrieve useful data. + +If the contracts you are working with do not contain events, your subgraph can use call and block handlers to trigger indexing. Although this is not recommended as performance will be significantly slower. + +### 5. Is it possible to deploy one subgraph with the same name for multiple networks? + +You will need separate names for multiple networks. While you can't have different subgraphs under the same name, there are convenient ways of having a single codebase for multiple networks. Find more on this in our documentation: [Redeploying a Subgraph](/hosted-service/deploy-subgraph-hosted#redeploying-a-subgraph) + +### 6. How are templates different from data sources? + +Templates allow you to create data sources on the fly, while your subgraph is indexing. It might be the case that your contract will spawn new contracts as people interact with it, and since you know the shape of those contracts (ABI, events, etc) up front you can define how you want to index them in a template and when they are spawned your subgraph will create a dynamic data source by supplying the contract address. + +Check out the "Instantiating a data source template" section on: [Data Source Templates](/developer/create-subgraph-hosted#data-source-templates). + +### 7. How do I make sure I'm using the latest version of graph-node for my local deployments? + +You can run the following command: + +```sh +docker pull graphprotocol/graph-node:latest +``` + +**NOTE:** docker / docker-compose will always use whatever graph-node version was pulled the first time you ran it, so it is important to do this to make sure you are up to date with the latest version of graph-node. + +### 8. How do I call a contract function or access a public state variable from my subgraph mappings? + +Take a look at `Access to smart contract` state inside the section [AssemblyScript API](/developer/assemblyscript-api). + +### 9. Is it possible to set up a subgraph using `graph init` from `graph-cli` with two contracts? Or should I manually add another datasource in `subgraph.yaml` after running `graph init`? + +Unfortunately this is currently not possible. `graph init` is intended as a basic starting point, from which you can then add more data sources manually. + +### 10. I want to contribute or add a GitHub issue, where can I find the open source repositories? + +- [graph-node](https://github.com/graphprotocol/graph-node) +- [graph-cli](https://github.com/graphprotocol/graph-cli) +- [graph-ts](https://github.com/graphprotocol/graph-ts) + +### 11. What is the recommended way to build "autogenerated" ids for an entity when handling events? + +If only one entity is created during the event and if there's nothing better available, then the transaction hash + log index would be unique. You can obfuscate these by converting that to Bytes and then piping it through `crypto.keccak256` but this won't make it more unique. + +### 12. When listening to multiple contracts, is it possible to select the contract order to listen to events? + +Within a subgraph, the events are always processed in the order they appear in the blocks, regardless of whether that is across multiple contracts or not. + +### 13. Is it possible to differentiate between networks (mainnet, Kovan, Ropsten, local) from within event handlers? + +Yes. You can do this by importing `graph-ts` as per the example below: + +```javascript +import { dataSource } from '@graphprotocol/graph-ts' + +dataSource.network() +dataSource.address() +``` + +### 14. Do you support block and call handlers on Rinkeby? + +On Rinkeby we support block handlers, but without `filter: call`. Call handlers are not supported for the time being. + +### 15. Can I import ethers.js or other JS libraries into my subgraph mappings? + +Not currently, as mappings are written in AssemblyScript. One possible alternative solution to this is to store raw data in entities and perform logic that requires JS libraries on the client. + +### 16. Is it possible to specifying what block to start indexing on? + +Yes. `dataSources.source.startBlock` in the `subgraph.yaml` file specifies the 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: Start blocks + +### 17. Are there some tips to increase performance of indexing? My subgraph is taking a very long time to sync. + +Yes, you should take a look at the optional start block feature to start indexing from the block that the contract was deployed: [Start blocks](/developer/create-subgraph-hosted#start-blocks) + +### 18. Is there a way to query the subgraph directly to determine what the latest block number it has indexed? + +Yes! Try the following command, substituting "organization/subgraphName" with the organization under it is published and the name of your subgraph: + +```sh +curl -X POST -d '{ "query": "{indexingStatusForCurrentVersion(subgraphName: \"organization/subgraphName\") { chains { latestBlock { hash number }}}}"}' https://api.thegraph.com/index-node/graphql +``` + +### 19. What networks are supported by The Graph? + +The graph-node supports any EVM-compatible JSON RPC API chain. + +The Graph Network supports subgraphs indexing mainnet Ethereum: + +- `mainnet` + +In the Hosted Service, the following networks are supported: + +- Ethereum mainnet +- Kovan +- Rinkeby +- Ropsten +- Goerli +- PoA-Core +- PoA-Sokol +- xDAI +- NEAR +- NEAR testnet +- Matic +- Mumbai +- Fantom +- Binance Smart Chain +- Clover +- Avalanche +- Fuji +- Celo +- Celo-Alfajores +- Fuse +- Moonbeam +- Arbitrum One +- Arbitrum Testnet (on Rinkeby) +- Optimism +- Optimism Testnet (on Kovan) + +There is work in progress towards integrating other blockchains, you can read more in our repo: [RFC-0003: Multi-Blockchain Support](https://github.com/graphprotocol/rfcs/pull/8/files). + +### 20. Is it possible to duplicate a subgraph to another account or endpoint without redeploying? + +You have to redeploy the subgraph, but if the subgraph ID (IPFS hash) doesn't change, it won't have to sync from the beginning. + +### 21. Is this possible to use Apollo Federation on top of graph-node? + +Federation is not supported yet, although we do want to support it in the future. At the moment, something you can do is use schema stitching, either on the client or via a proxy service. + +### 22. Is there a limit to how many objects The Graph can return per query? + +By default query responses are limited to 100 items per collection. If you want to receive more, you can go up to 1000 items per collection and beyond that you can paginate with: + +```graphql +someCollection(first: 1000, skip: ) { ... } +``` + +### 23. If my dapp frontend uses The Graph for querying, do I need to write my query key into the frontend directly? What if we pay query fees for users – will malicious users cause our query fees to be very high? + +Currently, the recommended approach for a dapp is to add the key to the frontend and expose it to end users. That said, you can limit that key to a host name, like _yourdapp.io_ and subgraph. The gateway is currently being run by Edge & Node. Part of the responsibility of a gateway is to monitor for abusive behavior and block traffic from malicious clients. + +### 24. Where do I go to find my current subgraph on the Hosted Service? + +Head over to the Hosted Service in order to find subgraphs that you or others deployed to the Hosted Service. You can find it [here.](https://thegraph.com/hosted-service) + +### 25. Will the Hosted Service start charging query fees? + +The Graph will never charge for the Hosted Service. The Graph is a decentralized protocol, and charging for a centralized service is not aligned with The Graph’s values. The Hosted Service was always a temporary step to help get to the decentralized network. Developers will have a sufficient amount of time to migrate to the decentralized network as they are comfortable. + +### 26. When will the Hosted Service be shut down? + +If and when there are plans to do this, the community will be notified well ahead of time with considerations made for any subgraphs built on the Hosted Service. + +### 27. How do I upgrade a subgraph on mainnet? + +If you’re a subgraph developer, you can upgrade a new version of your subgraph to the Studio using the CLI. It’ll be private at that point but if you’re happy with it, you can publish to the decentralized Graph Explorer. This will create a new version of your subgraph that Curators can start signaling on. diff --git a/pages/zh/developer/distributed-systems.mdx b/pages/zh/developer/distributed-systems.mdx new file mode 100644 index 000000000000..894fcbe2e18b --- /dev/null +++ b/pages/zh/developer/distributed-systems.mdx @@ -0,0 +1,132 @@ +--- +title: Distributed Systems +--- + +The Graph is a protocol implemented as a distributed system. + +Connections fail. Requests arrive out of order. Different computers with out-of-sync clocks and states process related requests. Servers restart. Re-orgs happen between requests. These problems are inherent to all distributed systems but are exacerbated in systems operating at a global scale. + +Consider this example of what may occur if a client polls an Indexer for the latest data during a re-org. + +1. Indexer ingests block 8 +2. Request served to the client for block 8 +3. Indexer ingests block 9 +4. Indexer ingests block 10A +5. Request served to the client for block 10A +6. Indexer detects reorg to 10B and rolls back 10A +7. Request served to the client for block 9 +8. Indexer ingests block 10B +9. Indexer ingests block 11 +10. Request served to the client for block 11 + +From the point of view of the Indexer, things are progressing forward logically. Time is moving forward, though we did have to roll back an uncle block and play the block under consensus forward on top of it. Along the way, the Indexer serves requests using the latest state it knows about at that time. + +From the point of view of the client, however, things appear chaotic. The client observes that the responses were for blocks 8, 10, 9, and 11 in that order. We call this the "block wobble" problem. When a client experiences block wobble, data may appear to contradict itself over time. The situation worsens when we consider that Indexers do not all ingest the latest blocks simultaneously, and your requests may be routed to multiple Indexers. + +It is the responsibility of the client and server to work together to provide consistent data to the user. Different approaches must be used depending on the desired consistency as there is no one right program for every problem. + +Reasoning through the implications of distributed systems is hard, but the fix may not be! We've established APIs and patterns to help you navigate some common use-cases. The following examples illustrate those patterns but still elide details required by production code (like error handling and cancellation) to not obfuscate the main ideas. + +## Polling for updated data + +The Graph provides the `block: { number_gte: $minBlock }` API, which ensures that the response is for a single block equal or higher to `$minBlock`. If the request is made to a `graph-node` instance and the min block is not yet synced, `graph-node` will return an error. If `graph-node` has synced min block, it will run the response for the latest block. If the request is made to an Edge & Node Gateway, the Gateway will filter out any Indexers that have not yet synced min block and make the request for the latest block the Indexer has synced. + +We can use `number_gte` to ensure that time never travels backward when polling for data in a loop. Here is an example: + +```javascript +/// Updates the protocol.paused variable to the latest +/// known value in a loop by fetching it using The Graph. +async function updateProtocolPaused() { + // It's ok to start with minBlock at 0. The query will be served + // using the latest block available. Setting minBlock to 0 is the + // same as leaving out that argument. + let minBlock = 0 + + for (;;) { + // Schedule a promise that will be ready once + // the next Ethereum block will likely be available. + const nextBlock = new Promise((f) => { + setTimeout(f, 14000) + }) + + const query = ` + { + protocol(block: { number_gte: ${minBlock} } id: "0") { + paused + } + _meta { + block { + number + } + } + }` + + const response = await graphql(query) + minBlock = response._meta.block.number + + // TODO: Do something with the response data here instead of logging it. + console.log(response.protocol.paused) + + // Sleep to wait for the next block + await nextBlock + } +} +``` + +## Fetching a set of related items + +Another use-case is retrieving a large set or, more generally, retrieving related items across multiple requests. Unlike the polling case (where the desired consistency was to move forward in time), the desired consistency is for a single point in time. + +Here we will use the `block: { hash: $blockHash }` argument to pin all of our results to the same block. + +```javascript +/// Gets a list of domain names from a single block using pagination +async function getDomainNames() { + // Set a cap on the maximum number of items to pull. + let pages = 5 + const perPage = 1000 + + // The first query will get the first page of results and also get the block + // hash so that the remainder of the queries are consistent with the first. + let query = ` + { + domains(first: ${perPage}) { + name + id + } + _meta { + block { + hash + } + } + }` + + let data = await graphql(query) + let result = data.domains.map((d) => d.name) + let blockHash = data._meta.block.hash + + // Continue fetching additional pages until either we run into the limit of + // 5 pages total (specified above) or we know we have reached the last page + // because the page has fewer entities than a full page. + while (data.domains.length == perPage && --pages) { + let lastID = data.domains[data.domains.length - 1].id + query = ` + { + domains(first: ${perPage}, where: { id_gt: "${lastID}" }, block: { hash: "${blockHash}" }) { + name + id + } + }` + + data = await graphql(query) + + // Accumulate domain names into the result + for (domain of data.domains) { + result.push(domain.name) + } + } + return result +} +``` + +Note that in case of a re-org, the client will need to retry from the first request to update the block hash to a non-uncle block. diff --git a/pages/zh/developer/graphql-api.mdx b/pages/zh/developer/graphql-api.mdx new file mode 100644 index 000000000000..f9cb6214fcd9 --- /dev/null +++ b/pages/zh/developer/graphql-api.mdx @@ -0,0 +1,267 @@ +--- +title: GraphQL API +--- + +This guide explains the GraphQL Query API that is used for the Graph Protocol. + +## Queries + +In your subgraph schema you define types called `Entities`. For each `Entity` type, an `entity` and `entities` field will be generated on the top-level `Query` type. Note that `query` does not need to be included at the top of the `graphql` query when using The Graph. + +#### Examples + +Query for a single `Token` entity defined in your schema: + +```graphql +{ + token(id: "1") { + id + owner + } +} +``` + +**Note:** When querying for a single entity, the `id` field is required and it must be a string. + +Query all `Token` entities: + +```graphql +{ + tokens { + id + owner + } +} +``` + +### Sorting + +When querying a collection, the `orderBy` parameter may be used to sort by a specific attribute. Additionally, the `orderDirection` can be used to specify the sort direction, `asc` for ascending or `desc` for descending. + +#### Example + +```graphql +{ + tokens(orderBy: price, orderDirection: asc) { + id + owner + } +} +``` + +### Pagination + +When querying a collection, the `first` parameter can be used to paginate from the beginning of the collection. It is worth noting that the default sort order is by ID in ascending alphanumeric order, not by creation time. + +Further, the `skip` parameter can be used to skip entities and paginate. e.g. `first:100` shows the first 100 entities and `first:100, skip:100` shows the next 100 entities. + +Queries should avoid using very large `skip` values since they generally perform poorly. For retrieving a large number of items, it is much better to page through entities based on an attribute as shown in the last example. + +#### Example + +Query the first 10 tokens: + +```graphql +{ + tokens(first: 10) { + id + owner + } +} +``` + +To query for groups of entities in the middle of a collection, the `skip` parameter may be used in conjunction with the `first` parameter to skip a specified number of entities starting at the beginning of the collection. + +#### Example + +Query 10 `Token` entities, offset by 10 places from the beginning of the collection: + +```graphql +{ + tokens(first: 10, skip: 10) { + id + owner + } +} +``` + +#### Example + +If a client needs to retrieve a large number of entities, it is much more performant to base queries on an attribute and filter by that attribute. For example, a client would retrieve a large number of tokens using this query: + +```graphql +{ + query manyTokens($lastID: String) { + tokens(first: 1000, where: { id_gt: $lastID }) { + id + owner + } + } +} +``` + +The first time, it would send the query with `lastID = ""`, and for subsequent requests would set `lastID` to the `id` attribute of the last entity in the previous request. This approach will perform significantly better than using increasing `skip` values. + +### Filtering + +You can use the `where` parameter in your queries to filter for different properties. You can filter on mulltiple values within the `where` parameter. + +#### Example + +Query challenges with `failed` outcome: + +```graphql +{ + challenges(where: { outcome: "failed" }) { + challenger + outcome + application { + id + } + } +} +``` + +You can use suffixes like `_gt`, `_lte` for value comparison: + +#### Example + +```graphql +{ + applications(where: { deposit_gt: "10000000000" }) { + id + whitelisted + deposit + } +} +``` + +Full list of parameter suffixes: + +```graphql +_not +_gt +_lt +_gte +_lte +_in +_not_in +_contains +_not_contains +_starts_with +_ends_with +_not_starts_with +_not_ends_with +``` + +Please note that some suffixes are only supported for specific types. For example, `Boolean` only supports `_not`, `_in`, and `_not_in`. + +### Time-travel queries + +You can query the state of your entities not just for the latest block, which is the by default, but also for an arbitrary block in the past. The block at which a query should happen can be specified either by its block number or its block hash by including a `block` argument in the toplevel fields of queries. + +The result of such a query will not change over time, i.e., querying at a certain past block will return the same result no matter when it is executed, with the exception that if you query at a block very close to the head of the Ethereum chain, the result might change if that block turns out to not be on the main chain and the chain gets reorganized. Once a block can be considered final, the result of the query will not change. + +Note that the current implementation is still subject to certain limitations that might violate these gurantees. The implementation can not always tell that a given block hash is not on the main chain at all, or that the result of a query by block hash for a block that can not be considered final yet might be influenced by a block reorganization running concurrently with the query. They do not affect the results of queries by block hash when the block is final and known to be on the main chain. [This issue](https://github.com/graphprotocol/graph-node/issues/1405) explains what these limitations are in detail. + +#### Example + +```graphql +{ + challenges(block: { number: 8000000 }) { + challenger + outcome + application { + id + } + } +} +``` + +This query will return `Challenge` entities, and their associated `Application` entities, as they existed directly after processing block number 8,000,000. + +#### Example + +```graphql +{ + challenges(block: { hash: "0x5a0b54d5dc17e0aadc383d2db43b0a0d3e029c4c" }) { + challenger + outcome + application { + id + } + } +} +``` + +This query will return `Challenge` entities, and their associated `Application` entities, as they existed directly after processing the block with the given hash. + +### Fulltext Search Queries + +Fulltext search query fields provide an expressive text search API that can be added to the subgraph schema and customized. Refer to [Defining Fulltext Search Fields](/developer/create-subgraph-hosted#defining-fulltext-search-fields) to add fulltext search to your subgraph. + +Fulltext search queries have one required field, `text`, for supplying search terms. Several special fulltext operators are available to be used in this `text` search field. + +Fulltext search operators: + +| Symbol | Operator | Description | +| ----------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------ | +| `&` | `And` | For combining multiple search terms into a filter for entities that include all of the provided terms | +| | | `Or` | Queries with multiple search terms separated by the or operator will return all entities with a match from any of the provided terms | +| `<->` | `Follow by` | Specify the distance between two words. | +| `:*` | `Prefix` | Use the prefix search term to find words whose prefix match (2 characters required.) | + +#### Examples + +Using the `or` operator, this query will filter to blog entities with variations of either "anarchism" or "crumpet" in their fulltext fields. + +```graphql +{ + blogSearch(text: "anarchism | crumpets") { + id + title + body + author + } +} +``` + +The `follow by` operator specifies a words a specific distance apart in the fulltext documents. The following query will return all blogs with variations of "decentralize" followed by "philosophy" + +```graphql +{ + blogSearch(text: "decentralized <-> philosophy") { + id + title + body + author + } +} +``` + +Combine fulltext operators to make more complex filters. With a pretext search operator combined with a follow by this example query will match all blog entities with words that start with "lou" followed by "music". + +```graphql +{ + blogSearch(text: "lou:* <-> music") { + id + title + body + author + } +} +``` + +## Schema + +The schema of your data source--that is, the entity types, values, and relationships that are available to query--are defined through the [GraphQL Interface Definition Langauge (IDL)](https://facebook.github.io/graphql/draft/#sec-Type-System). + +GraphQL schemas generally define root types for `queries`, `subscriptions` and `mutations`. The Graph only supports `queries`. The root `Query` type for your subgraph is automatically generated from the GraphQL schema that's included in your subgraph manifest. + +> **Note:** Our API does not expose mutations because developers are expected to issue transactions directly against the underlying blockchain from their applications. + +### Entities + +All GraphQL types with `@entity` directives in your schema will be treated as entities and must have an `ID` field. + +> **Note:** Currently, all types in your schema must have an `@entity` directive. In the future, we will treat types without an `@entity` directive as value objects, but this is not yet supported. diff --git a/pages/zh/developer/matchstick.mdx b/pages/zh/developer/matchstick.mdx new file mode 100644 index 000000000000..3cf1ec761bb9 --- /dev/null +++ b/pages/zh/developer/matchstick.mdx @@ -0,0 +1,267 @@ +--- +title: Unit Testing Framework +--- + +Matchstick is a unit testing framework, developed by [LimeChain](https://limechain.tech/), that enables subgraph developers to test their mapping logic in a sandboxed environment and deploy their subgraphs with confidence! + +Follow the [Matchstick installation guide](https://github.com/LimeChain/matchstick/blob/main/README.md#quick-start-) to install. Now, you can move on to writing your first unit test. + +## Write a Unit Test + +Let's see how a simple unit test would look like, using the Gravatar [Example Subgraph](https://github.com/graphprotocol/example-subgraph). + +Assuming we have the following handler function (along with two helper functions to make our life easier): + +```javascript +export function handleNewGravatar(event: NewGravatar): void { + let gravatar = new Gravatar(event.params.id.toHex()) + gravatar.owner = event.params.owner + gravatar.displayName = event.params.displayName + gravatar.imageUrl = event.params.imageUrl + gravatar.save() +} + +export function handleNewGravatars(events: NewGravatar[]): void { + events.forEach((event) => { + handleNewGravatar(event) + }) +} + +export function createNewGravatarEvent( + id: i32, + ownerAddress: string, + displayName: string, + imageUrl: string +): NewGravatar { + let mockEvent = newMockEvent() + let newGravatarEvent = new NewGravatar( + mockEvent.address, + mockEvent.logIndex, + mockEvent.transactionLogIndex, + mockEvent.logType, + mockEvent.block, + mockEvent.transaction, + mockEvent.parameters + ) + newGravatarEvent.parameters = new Array() + let idParam = new ethereum.EventParam('id', ethereum.Value.fromI32(id)) + let addressParam = new ethereum.EventParam( + 'ownderAddress', + ethereum.Value.fromAddress(Address.fromString(ownerAddress)) + ) + let displayNameParam = new ethereum.EventParam('displayName', ethereum.Value.fromString(displayName)) + let imageUrlParam = new ethereum.EventParam('imageUrl', ethereum.Value.fromString(imageUrl)) + + newGravatarEvent.parameters.push(idParam) + newGravatarEvent.parameters.push(addressParam) + newGravatarEvent.parameters.push(displayNameParam) + newGravatarEvent.parameters.push(imageUrlParam) + + return newGravatarEvent +} +``` + +We first have to create a test file in our project. We have chosen the name `gravity.test.ts`. In the newly created file we need to define a function named `runTests()`. It is important that the function has that exact name. This is an example of how our tests might look like: + +```typescript +import { clearStore, test, assert } from 'matchstick-as/assembly/index' +import { Gravatar } from '../../generated/schema' +import { NewGravatar } from '../../generated/Gravity/Gravity' +import { createNewGravatarEvent, handleNewGravatars } from '../mappings/gravity' + +export function runTests(): void { + test('Can call mappings with custom events', () => { + // Initialise + let gravatar = new Gravatar('gravatarId0') + gravatar.save() + + // Call mappings + let newGravatarEvent = createNewGravatarEvent(12345, '0x89205A3A3b2A69De6Dbf7f01ED13B2108B2c43e7', 'cap', 'pac') + + let anotherGravatarEvent = createNewGravatarEvent(3546, '0x89205A3A3b2A69De6Dbf7f01ED13B2108B2c43e7', 'cap', 'pac') + + handleNewGravatars([newGravatarEvent, anotherGravatarEvent]) + + assert.fieldEquals('Gravatar', 'gravatarId0', 'id', 'gravatarId0') + assert.fieldEquals('Gravatar', '12345', 'owner', '0x89205A3A3b2A69De6Dbf7f01ED13B2108B2c43e7') + assert.fieldEquals('Gravatar', '3546', 'displayName', 'cap') + + clearStore() + }) + + test('Next test', () => { + //... + }) +} +``` + +That's a lot to unpack! First off, an important thing to notice is that we're importing things from `matchstick-as`, our AssemblyScript helper library (distributed as an npm module). You can find the repository [here](https://github.com/LimeChain/matchstick-as). `matchstick-as` provides us with useful testing methods and also defines the `test()` function which we will use to build our test blocks. The rest of it is pretty straightforward - here's what happens: + +- We're setting up our initial state and adding one custom Gravatar entity; +- We define two `NewGravatar` event objects along with their data, using the `createNewGravatarEvent()` function; +- We're calling out handler methods for those events - `handleNewGravatars()` and passing in the list of our custom events; +- We assert the state of the store. How does that work? - We're passing a unique combination of Entity type and id. Then we check a specific field on that Entity and assert that it has the value we expect it to have. We're doing this both for the initial Gravatar Entity we added to the store, as well as the two Gravatar entities that gets added when the handler function is called; +- And lastly - we're cleaning the store using `clearStore()` so that our next test can start with a fresh and empty store object. We can define as many test blocks as we want. + +There we go - we've created our first test! 👏 + +❗ **IMPORTANT:** _In order for the tests to work, we need to export the `runTests()` function in our mappings file. It won't be used there, but the export statement has to be there so that it can get picked up by Rust later when running the tests._ + +You can export the tests wrapper function in your mappings file like this: + +``` +export { runTests } from "../tests/gravity.test.ts"; +``` + +❗ **IMPORTANT:** _Currently there's an issue with using Matchstick when deploying your subgraph. Please only use Matchstick for local testing, and remove/comment out this line (`export { runTests } from "../tests/gravity.test.ts"`) once you're done. We expect to resolve this issue shortly, sorry for the inconvenience!_ + +_If you don't remove that line, you will get the following error message when attempting to deploy your subgraph:_ + +``` +/... +Mapping terminated before handling trigger: oneshot canceled +.../ +``` + +Now in order to run our tests you simply need to run the following in your subgraph root folder: + +`graph test Gravity` + +And if all goes well you should be greeted with the following: + +![Matchstick saying “All tests passed!”](/img/matchstick-tests-passed.png) + +## Common test scenarios + +### Hydrating the store with a certain state + +Users are able to hydrate the store with a known set of entities. Here's an example to initialise the store with a Gravatar entity: + +```typescript +let gravatar = new Gravatar('entryId') +gravatar.save() +``` + +### Calling a mapping function with an event + +A user can create a custom event and pass it to a mapping function that is bound to the store: + +```typescript +import { store } from 'matchstick-as/assembly/store' +import { NewGravatar } from '../../generated/Gravity/Gravity' +import { handleNewGravatars, createNewGravatarEvent } from './mapping' + +let newGravatarEvent = createNewGravatarEvent(12345, '0x89205A3A3b2A69De6Dbf7f01ED13B2108B2c43e7', 'cap', 'pac') + +handleNewGravatar(newGravatarEvent) +``` + +### Calling all of the mappings with event fixtures + +Users can call the mappings with test fixtures. + +```typescript +import { NewGravatar } from '../../generated/Gravity/Gravity' +import { store } from 'matchstick-as/assembly/store' +import { handleNewGravatars, createNewGravatarEvent } from './mapping' + +let newGravatarEvent = createNewGravatarEvent(12345, '0x89205A3A3b2A69De6Dbf7f01ED13B2108B2c43e7', 'cap', 'pac') + +let anotherGravatarEvent = createNewGravatarEvent(3546, '0x89205A3A3b2A69De6Dbf7f01ED13B2108B2c43e7', 'cap', 'pac') + +handleNewGravatars([newGravatarEvent, anotherGravatarEvent]) +``` + +``` +export function handleNewGravatars(events: NewGravatar[]): void { + events.forEach(event => { + handleNewGravatar(event); + }); +} +``` + +### Mocking contract calls + +Users can mock contract calls: + +```typescript +import { addMetadata, assert, createMockedFunction, clearStore, test } from 'matchstick-as/assembly/index' +import { Gravity } from '../../generated/Gravity/Gravity' +import { Address, BigInt, ethereum } from '@graphprotocol/graph-ts' + +let contractAddress = Address.fromString('0x89205A3A3b2A69De6Dbf7f01ED13B2108B2c43e7') +let expectedResult = Address.fromString('0x90cBa2Bbb19ecc291A12066Fd8329D65FA1f1947') +let bigIntParam = BigInt.fromString('1234') +createMockedFunction(contractAddress, 'gravatarToOwner', 'gravatarToOwner(uint256):(address)') + .withArgs([ethereum.Value.fromSignedBigInt(bigIntParam)]) + .returns([ethereum.Value.fromAddress(Address.fromString('0x90cBa2Bbb19ecc291A12066Fd8329D65FA1f1947'))]) + +let gravity = Gravity.bind(contractAddress) +let result = gravity.gravatarToOwner(bigIntParam) + +assert.equals(ethereum.Value.fromAddress(expectedResult), ethereum.Value.fromAddress(result)) +``` + +As demonstrated, in order to mock a contract call and hardcore a return value, the user must provide a contract address, function name, function signature, an array of arguments, and of course - the return value. + +Users can also mock function reverts: + +```typescript +let contractAddress = Address.fromString('0x89205A3A3b2A69De6Dbf7f01ED13B2108B2c43e7') +createMockedFunction(contractAddress, 'getGravatar', 'getGravatar(address):(string,string)') + .withArgs([ethereum.Value.fromAddress(contractAddress)]) + .reverts() +``` + +### Asserting the state of the store + +Users are able to assert the final (or midway) state of the store through asserting entities. In order to do this, the user has to supply an Entity type, the specific ID of an Entity, a name of a field on that Entity, and the expected value of the field. Here's a quick example: + +```typescript +import { assert } from 'matchstick-as/assembly/index' +import { Gravatar } from '../generated/schema' + +let gravatar = new Gravatar('gravatarId0') +gravatar.save() + +assert.fieldEquals('Gravatar', 'gravatarId0', 'id', 'gravatarId0') +``` + +Running the assert.fieldEquals() function will check for equality of the given field against the given expected value. The test will fail and an error message will be outputted if the values are **NOT** equal. Otherwise the test will pass successfully. + +### Interacting with Event metadata + +Users can use default transaction metadata, which could be returned as an ethereum.Event by using the `newMockEvent()` function. The following example shows how you can read/write to those fields on the Event object: + +```typescript +// Read +let logType = newGravatarEvent.logType + +// Write +let UPDATED_ADDRESS = '0xB16081F360e3847006dB660bae1c6d1b2e17eC2A' +newGravatarEvent.address = Address.fromString(UPDATED_ADDRESS) +``` + +### Asserting variable equality + +```typescript +assert.equals(ethereum.Value.fromString("hello"); ethereum.Value.fromString("hello")); +``` + +### Asserting that an Entity is **not** in the store + +Users can assert that an entity does not exist in the store. The function takes an entity type and an id. If the entity is in fact in the store, the test will fail with a relevant error message. Here's a quick example of how to use this functionality: + +```typescript +assert.notInStore('Gravatar', '23') +``` + +### Test run time duration in the log output + +The log output includes the test run duration. Here's an example: + +`Jul 09 14:54:42.420 INFO Program execution time: 10.06022ms` + +## Feedback + +If you have any questions, feedback, feature requests or just want to reach out, the best place would be The Graph Discord where we have a dedicated channel for Matchstick, called 🔥| unit-testing. diff --git a/pages/zh/developer/publish-subgraph.mdx b/pages/zh/developer/publish-subgraph.mdx new file mode 100644 index 000000000000..2f35f5eb1bae --- /dev/null +++ b/pages/zh/developer/publish-subgraph.mdx @@ -0,0 +1,27 @@ +--- +title: Publish a Subgraph to the Decentralized Network +--- + +Once your subgraph has been [deployed to the Subgraph Studio](/studio/deploy-subgraph-studio), you have tested it out, and are ready to put it into production, you can then publish it to the decentralized network. + +Publishing a Subgraph to the decentralized network makes it available for [curators](/curating) to begin curating on it, and [indexers](/indexing) to begin indexing it. + +For a walkthrough of how to publish a subgraph to the decentralized network, see [this video](https://youtu.be/HfDgC2oNnwo?t=580). + +### Networks + +The decentralized network currently supports both Rinkeby and Ethereum Mainnet. + +### Publishing a subgraph + +Subgraphs can be published to the decentralized network directly from the Subgraph Studio dashboard by clicking on the **Publish** button. Once a subgraph is published, it will be available to view in the [Graph Explorer](https://thegraph.com/explorer/). + +- Subgraphs published to Rinkeby can index and query data from either the Rinkeby network or Ethereum Mainnet. + +- Subgraphs published to Ethereum Mainnet can only index and query data from Ethereum Mainnet, meaning that you cannot publish subgraphs to the main decentralized network that index and query testnet data. + +- When publishing a new version for an existing subgraph the same rules apply as above. + +### Updating metadata for a published subgraph + +Once your subgraph has been published to the decentralized network, you can modify the metadata at any time by making the update in the Subgraph Studio dashboard of the subgraph. After saving the changes and publishing your updates to the network, they will be reflected in the Graph Explorer. This won’t create a new version, as your deployment hasn’t changed. diff --git a/pages/zh/developer/query-the-graph.mdx b/pages/zh/developer/query-the-graph.mdx new file mode 100644 index 000000000000..ae480b1e6883 --- /dev/null +++ b/pages/zh/developer/query-the-graph.mdx @@ -0,0 +1,32 @@ +--- +title: Query The Graph +--- + +With the subgraph deployed, visit the [Graph Explorer](https://thegraph.com/explorer) to open up a [GraphiQL](https://github.com/graphql/graphiql) interface where you can explore the deployed GraphQL API for the subgraph by issuing queries and viewing the schema. + +An example is provided below, but please see the [Query API](/developer/graphql-api) for a complete reference on how to query the subgraph's entities. + +#### Example + +This query lists all the counters our mapping has created. Since we only create one, the result will only contain our one `default-counter`: + +```graphql +{ + counters { + id + value + } +} +``` + +## Using The Graph Explorer + +Each subgraph published to the decentralized Graph Explorer has a unique query URL that you can find by navigating to the subgraph details page and clicking on the "Query" button on the top right corner. This will open a side pane that will give you the unique query URL of the subgraph as well as some instructions about how to query it. + +![Query Subgraph Pane](/img/query-subgraph-pane.png) + +As you can notice, this query URL must use a unique API key. You can create and manage your API keys in the [Subgraph Studio](https://thegraph.com/studio) in the "API Keys" section. Learn more about how to use Subgraph Studio [here](/studio/subgraph-studio). + +Querying subgraphs using your API keys will generate query fees that will be paid in GRT. You can learn more about billing [here](/studio/billing). + +You can also use the GraphQL playground in the "Playground" tab to query a subgraph within The Graph Explorer. diff --git a/pages/zh/developer/querying-from-your-app.mdx b/pages/zh/developer/querying-from-your-app.mdx new file mode 100644 index 000000000000..c09c44efee72 --- /dev/null +++ b/pages/zh/developer/querying-from-your-app.mdx @@ -0,0 +1,136 @@ +--- +title: Querying from an Application +--- + +Once a subgraph is deployed to the Subgraph Studio or to the Graph Explorer, you will be given the endpoint for your GraphQL API that should look something like this: + +**Subgraph Studio (testing endpoint)** + +```sh +Queries (HTTP) +https://api.studio.thegraph.com/query/// +``` + +**Graph Explorer** + +```sh +Queries (HTTP) +https://gateway.thegraph.com/api//subgraphs/id/ +``` + +Using the GraphQL endpoint, you can use various GraphQL Client libraries to query the subgraph and populate your app with the data indexed by the subgraph. + +Here are a couple of the more popular GraphQL clients in the ecosystem and how to use them: + +### Apollo client + +[Apollo client](https://www.apollographql.com/docs/) supports web projects including frameworks like React and Vue, as well as mobile clients like iOS, Android, and React Native. + +Let's look at how fetch data from a subgraph with Apollo client in a web project. + +First, install `@apollo/client` and `graphql`: + +```sh +npm install @apollo/client graphql +``` + +Then you can query the API with the following code: + +```javascript +import { ApolloClient, InMemoryCache, gql } from '@apollo/client' + +const APIURL = 'https://api.studio.thegraph.com/query///' + +const tokensQuery = ` + query { + tokens { + id + tokenID + contentURI + metadataURI + } + } +` + +const client = new ApolloClient({ + uri: APIURL, + cache: new InMemoryCache(), +}) + +client + .query({ + query: gql(tokensQuery), + }) + .then((data) => console.log('Subgraph data: ', data)) + .catch((err) => { + console.log('Error fetching data: ', err) + }) +``` + +To use variables, you can pass in a `variables` argument to the query: + +```javascript +const tokensQuery = ` + query($first: Int, $orderBy: BigInt, $orderDirection: String) { + tokens( + first: $first, orderBy: $orderBy, orderDirection: $orderDirection + ) { + id + tokenID + contentURI + metadataURI + } + } +` + +client + .query({ + query: gql(tokensQuery), + variables: { + first: 10, + orderBy: 'createdAtTimestamp', + orderDirection: 'desc', + }, + }) + .then((data) => console.log('Subgraph data: ', data)) + .catch((err) => { + console.log('Error fetching data: ', err) + }) +``` + +### URQL + +Another option is [URQL](https://formidable.com/open-source/urql/), a somewhat lighter weight GraphQL client library. + +Let's look at how fetch data from a subgraph with URQL in a web project. + +First, install `urql` and `graphql`: + +```sh +npm install urql graphql +``` + +Then you can query the API with the following code: + +```javascript +import { createClient } from 'urql' + +const APIURL = 'https://api.thegraph.com/subgraphs/name/username/subgraphname' + +const tokensQuery = ` + query { + tokens { + id + tokenID + contentURI + metadataURI + } + } +` + +const client = createClient({ + url: APIURL, +}) + +const data = await client.query(tokensQuery).toPromise() +``` diff --git a/pages/zh/developer/quick-start.mdx b/pages/zh/developer/quick-start.mdx new file mode 100644 index 000000000000..6893d424ddc2 --- /dev/null +++ b/pages/zh/developer/quick-start.mdx @@ -0,0 +1,227 @@ +--- +title: Quick Start +--- + +This guide will quickly take you through how to initialize, create, and deploy your subgraph on: + +- **Subgraph Studio** - used only for subgraphs that index **Ethereum mainnet** +- **Hosted Service** - used for subgraphs that index **other networks** outside of Ethereum mainnnet (e.g. Binance, Matic, etc) + +## Subgraph Studio + +### 1. Install the Graph CLI + +The Graph CLI is written in JavaScript and you will need to have either `npm` or `yarn` installed to use it. + +```sh +# NPM +$ npm install -g @graphprotocol/graph-cli + +# Yarn +$ yarn global add @graphprotocol/graph-cli +``` + +### 2. Initialize your Subgraph + +- Initialize your subgraph from an existing contract. + +```sh +graph init --studio +``` + +- Your subgraph slug is an identifier for your subgraph. The CLI tool will walk you through the steps for creating a subgraph, such as contract address, network, etc as you can see in the screenshot below. + +![Subgraph command](/img/Subgraph-Slug.png) + +### 3. Write your Subgraph + +The previous commands creates a scaffold subgraph that you can use as a starting point for building your subgraph. When making changes to the subgraph, you will mainly work with three files: + +- Manifest (subgraph.yaml) - The manifest defines what datasources your subgraphs will index. +- Schema (schema.graphql) - The GraphQL schema defines what data you wish to retreive from the subgraph. +- AssemblyScript Mappings (mapping.ts) - This is the code that translates data from your datasources to the entities defined in the schema. + +For more information on how to write your subgraph, see [Create a Subgraph](/developer/create-subgraph-hosted). + +### 4. Deploy to the Subgraph Studio + +- Go to the Subgraph Studio [https://thegraph.com/studio/](https://thegraph.com/studio/) and connect your wallet. +- Click "Create" and enter the subgraph slug you used in step 2. +- Run these commands in the subgraph folder + +```sh +$ graph codegen +$ graph build +``` + +- Authenticate and deploy your subgraph. The deploy key can be found on the Subgraph page in Subgraph Studio. + +```sh +$ graph auth --studio +$ graph deploy --studio +``` + +- You will be asked for a version label. It's strongly recommended to use the following conventions for naming your versions. Example: `0.0.1`, `v1`, `version1` + +### 5. Check your logs + +The logs should tell you if there are any errors. If your subgraph is failing, you can query the subgraph health by using the [GraphiQL Playground](https://graphiql-online.com/). Use [this endpoint](https://api.thegraph.com/index-node/graphql). Note that you can leverage the query below and input your deployment ID for your subgraph. In this case, `Qm...` is the deployment ID (which can be located on the Subgraph page under **Details**). The query below will tell you when a subgraph fails so you can debug accordingly: + +```sh +{ + indexingStatuses(subgraphs: ["Qm..."]) { + node + synced + health + fatalError { + message + block { + number + hash + } + handler + } + nonFatalErrors { + message + block { + number + hash + } + handler + } + chains { + network + chainHeadBlock { + number + } + earliestBlock { + number + } + latestBlock { + number + } + lastHealthyBlock { + number + } + } + entityCount + } +} +``` + +### 6. Query your Subgraph + +You can now query your subgraph by following [these instructions](/developer/query-the-graph). You can query from your dapp if you don't have your API key via the free, rate limited temporary query URL that can be used for development and staging. You can read the additional instructions for how to query a subgraph from a frontend application [here](/developer/querying-from-your-app). + +## Hosted Service + +### 1. Install the Graph CLI + +"The Graph CLI is an npm package and you will need `npm` or `yarn` installed to use it. + +```sh +# NPM +$ npm install -g @graphprotocol/graph-cli + +# Yarn +$ yarn global add @graphprotocol/graph-cli +``` + +### 2. Initialize your Subgraph + +- Initialize your subgraph from an existing contract. + +```sh +$ graph init --product hosted-service --from-contract
+``` + +- You will be asked for a subgraph name. The format is `/`. Ex: `graphprotocol/examplesubgraph` + +- If you'd like to initialize from an example, run the command below: + +```sh +$ graph init --product hosted-service --from-example +``` + +- In the case of the example, the subgraph is based on the Gravity contract by Dani Grant that manages user avatars and emits `NewGravatar` or `UpdateGravatar` events whenever avatars are created or updated. + +### 3. Write your Subgraph + +The previous command will have created a scaffold from where you can build your subgraph. When making changes to the subgraph, you will mainly work with three files: + +- Manifest (subgraph.yaml) - The manifest defines what datasources your subgraph will index +- Schema (schema.graphql) - The GraphQL schema define what data you wish to retrieve from the subgraph +- AssemblyScript Mappings (mapping.ts) - This is the code that translates data from your datasources to the entities defined in the schema + +For more information on how to write your subgraph, see [Create a Subgraph](/developer/create-subgraph-hosted). + +### 4. Deploy your Subgraph + +- Sign into the [Hosted Service](https://thegraph.com/hosted-service/) using your github account +- Click Add Subgraph and fill out the required information. Use the same subgraph name as in step 2. +- Run codegen in the subgraph folder + +```sh + # NPM +$ npm run codegen + +# Yarn +$ yarn codegen +``` + +- Add your Access token and deploy your subgraph. The access token is found on your dashboard in the Hosted Service. + +```sh +$ graph auth --product hosted-service +$ graph deploy --product hosted-service / +``` + +### 5. Check your logs + +The logs should tell you if there are any errors. If your subgraph is failing, you can query the subgraph health by using the [GraphiQL Playground](https://graphiql-online.com/). Use [this endpoint](https://api.thegraph.com/index-node/graphql). Note that you can leverage the query below and input your deployment ID for your subgraph. In this case, `Qm...` is the deployment ID (which can be located on the Subgraph page under **Details**). The query below will tell you when a subgraph fails so you can debug accordingly: + +```sh +{ + indexingStatuses(subgraphs: ["Qm..."]) { + node + synced + health + fatalError { + message + block { + number + hash + } + handler + } + nonFatalErrors { + message + block { + number + hash + } + handler + } + chains { + network + chainHeadBlock { + number + } + earliestBlock { + number + } + latestBlock { + number + } + lastHealthyBlock { + number + } + } + entityCount + } +} +``` + +### 6. Query your Subgraph + +Follow [these instructions](/hosted-service/query-hosted-service) to query your subgraph on the Hosted Service. diff --git a/pages/zh/explorer.mdx b/pages/zh/explorer.mdx index 7e68053f4b44..c9a0635fdc75 100644 --- a/pages/zh/explorer.mdx +++ b/pages/zh/explorer.mdx @@ -11,7 +11,7 @@ title: 浏览器 title="YouTube video player" frameBorder="0" allowFullScreen - > +> ## 子图 diff --git a/pages/zh/hosted-service/deploy-subgraph-hosted.mdx b/pages/zh/hosted-service/deploy-subgraph-hosted.mdx new file mode 100644 index 000000000000..bdc532e205e4 --- /dev/null +++ b/pages/zh/hosted-service/deploy-subgraph-hosted.mdx @@ -0,0 +1,160 @@ +--- +title: Deploy a Subgraph to the Hosted Service +--- + +If you have not checked out already, check out how to write the files that make up a [subgraph manifest](/developer/create-subgraph-hosted#the-subgraph-manifest) and how to install the [Graph CLI](https://github.com/graphprotocol/graph-cli) to generate code for your subgraph. Now, it's time to deploy your subgraph to the Hosted Service, also known as the Hosted Service. + +## Create a Hosted Service account + +Before using the Hosted Service, create an account in our Hosted Service. You will need a [Github](https://github.com/) account for that; if you don't have one, you need to create that first. Then, navigate to the [Hosted Service](https://thegraph.com/hosted-service/), click on the _'Sign up with Github'_ button and complete Github's authorization flow. + +## Store the Access Token + +After creating an account, navigate to your [dashboard](https://thegraph.com/hosted-service/dashboard). Copy the access token displayed on the dashboard and run `graph auth --product hosted-service `. This will store the access token on your computer. You only need to do this once, or if you ever regenerate the access token. + +## Create a Subgraph on the Hosted Service + +Before deploying the subgraph, you need to create it in The Graph Explorer. Go to the [dashboard](https://thegraph.com/hosted-service/dashboard) and click on the _'Add Subgraph'_ button and fill in the information below as appropriate: + +**Image** - Select an image to be used as a preview image and thumbnail for the subgraph. + +**Subgraph Name** - Together with the account name that the subgraph is created under, this will also define the `account-name/subgraph-name`-style name used for deployments and GraphQL endpoints. _This field cannot be changed later._ + +**Account** - The account that the subgraph is created under. This can be the account of an individual or organization. _Subgraphs cannot be moved between accounts later._ + +**Subtitle** - Text that will appear in subgraph cards. + +**Description** - Description of the subgraph, visible on the subgraph details page. + +**GitHub URL** - Link to the subgraph repository on GitHub. + +**Hide** - Switching this on hides the subgraph in the 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 [Define a Subgraph section](/developer/define-subgraph-hosted). + +## Deploy a Subgraph on the Hosted Service + +Deploying your subgraph will upload the subgraph files that you've built with `yarn build` to IPFS and tell the Graph Explorer to start indexing your subgraph using these files. + +You deploy the subgraph by running `yarn deploy` + +After deploying the subgraph, the 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 Ethereum blocks, starting with the genesis block, syncing can take from a few minutes to several hours. The subgraph status switches to `Synced` once the Graph Node has extracted all data from historical blocks. The Graph Node will continue inspecting Ethereum blocks for your subgraph as these blocks are mined. + +## Redeploying a Subgraph + +When making changes to your subgraph definition, for example to fix a problem in the entity mappings, run the `yarn deploy` command above again to deploy the updated version of your subgraph. Any update of a subgraph requires that Graph Node reindexes your entire subgraph, again starting with the genesis block. + +If your previously deployed subgraph is still in status `Syncing`, it will be immediately replaced with the newly deployed version. If the previously deployed subgraph is already fully synced, Graph Node will mark the newly deployed version as the `Pending Version`, sync it in the background, and only replace the currently deployed version with the new one once syncing the new version has finished. This ensures that you have a subgraph to work with while the new version is syncing. + +### Deploying the subgraph to multiple Ethereum networks + +In some cases, you will want to deploy the same subgraph to multiple Ethereum networks without duplicating all of its code. The main challenge that comes with this is that the contract addresses on these networks are different. One solution that allows to parameterize aspects like contract addresses is to generate parts of it using a templating system like [Mustache](https://mustache.github.io/) or [Handlebars](https://handlebarsjs.com/). + +To illustrate this approach, let's assume a subgraph should be deployed to mainnet and Ropsten using different contract addresses. You could then define two config files providing the addresses for each network: + +```json +{ + "network": "mainnet", + "address": "0x123..." +} +``` + +and + +```json +{ + "network": "ropsten", + "address": "0xabc..." +} +``` + +Along with that, you would substitute the network name and addresses in the manifest with variable placeholders `{{network}}` and `{{address}}` and rename the manifest to e.g. `subgraph.template.yaml`: + +```yaml +# ... +dataSources: + - kind: ethereum/contract + name: Gravity + network: mainnet + network: {{network}} + source: + address: '0x2E645469f354BB4F5c8a05B3b30A929361cf77eC' + address: '{{address}}' + abi: Gravity + mapping: + kind: ethereum/events +``` + +In order generate a manifest to either network, you could add two additional commands to `package.json` along with a dependency on `mustache`: + +```json +{ + ... + "scripts": { + ... + "prepare:mainnet": "mustache config/mainnet.json subgraph.template.yaml > subgraph.yaml", + "prepare:ropsten": "mustache config/ropsten.json subgraph.template.yaml > subgraph.yaml" + }, + "devDependencies": { + ... + "mustache": "^3.1.0" + } +} +``` + +To deploy this subgraph for mainnet or Ropsten you would now simply run one of the two following commands: + +```sh +# Mainnet: +yarn prepare:mainnet && yarn deploy + +# Ropsten: +yarn prepare:ropsten && yarn deploy +``` + +A working example of this can be found [here](https://github.com/graphprotocol/example-subgraph/tree/371232cf68e6d814facf5e5413ad0fef65144759). + +**Note:** This approach can also be applied more complex situations, where it is necessary to substitute more than contract addresses and network names or where generating mappings or ABIs from templates as well. + +## Checking subgraph health + +If a subgraph syncs successfully, that is a good sign that it will continue to run well forever. However, new triggers on the chain might cause your subgraph to hit an untested error condition or it may start to fall behind due to performance issues or issues with the node operators. + +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](https://github.com/graphprotocol/graph-node/blob/master/server/index-node/src/schema.graphql). Here is an example query that checks the status of the current version of a subgraph: + +```graphql +{ + indexingStatusForCurrentVersion(subgraphName: "org/subgraph") { + synced + health + fatalError { + message + block { + number + hash + } + handler + } + chains { + chainHeadBlock { + number + } + latestBlock { + number + } + } + } +} +``` + +This will give you the `chainHeadBlock` which you can compare with the `latestBlock` on your subgraph to check if it is running behind. `synced` informs if the subgraph has ever caught up to the chain. `health` can currently take the values of `healthy` if no errors ocurred, or `failed` if there was an error which halted the progress of the subgraph. In this case you can check the `fatalError` field for details on this error. + +## Subgraph archive policy + +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 which 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 30 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. diff --git a/pages/zh/hosted-service/migrating-subgraph.mdx b/pages/zh/hosted-service/migrating-subgraph.mdx new file mode 100644 index 000000000000..85f72f053b30 --- /dev/null +++ b/pages/zh/hosted-service/migrating-subgraph.mdx @@ -0,0 +1,151 @@ +--- +title: Migrating an Existing Subgraph to The Graph Network +--- + +## Introduction + +This is a guide for the migration of subgraphs from the Hosted Service (also known as the Hosted Service) to The Graph Network. The migration to The Graph Network has been successful for projects like Opyn, UMA, mStable, Audius, PoolTogether, Livepeer, RAI, Enzyme, DODO, Opyn, Pickle, and BadgerDAO all of which are relying on data served by Indexers on the network. There are now over 200 subgraphs live on The Graph Network, generating query fees and actively indexing web3 data. + +This will tell you everything you need to know about how to migrate to the decentralized network and manage your subgraphs moving forward. The process is quick and your subgraphs will forever benefit from the reliability and performance that you can only get on The Graph Network. + +### Migrating An Existing Subgraph to The Graph Network + +1. Get the latest version of the graph-cli installed: + +```sh +npm install -g @graphprotocol/graph-cli +``` + +```sh +yarn global add @graphprotocol/graph-cli +``` + +2. Create a subgraph on the [Subgraph Studio](https://thegraph.com/studio/). Guides on how to do that can be found in the [Subgraph Studio docs](/studio/subgraph-studio) and in [this video tutorial](https://www.youtube.com/watch?v=HfDgC2oNnwo). +3. Inside the main project subgraph repository, authenticate the subgraph to deploy and build on the studio: + +```sh +graph auth --studio +``` + +4. Generate files and build the subgraph: + +```sh +graph codegen && graph build +``` + +5. Deploy the subgraph to the Studio. You can find your `` in the Studio UI, which is based on the name of your subgraph. + +```sh + graph deploy --studio +``` + +6. Test queries on the Studio's playground. Here are some examples for the [Sushi - Mainnet Exchange Subgraph](https://thegraph.com/explorer/subgraph?id=0x4bb4c1b0745ef7b4642feeccd0740dec417ca0a0-0&view=Playground): + +```sh +{ + users(first: 5) { + id + liquidityPositions { + id + } + } + bundles(first: 5) { + id + ethPrice + } +} +``` + +7. Fill in the description and the details of your subgraph and choose up to 3 categories. Upload a project image in the Studio if you'd like as well. +8. Publish the subgraph on The Graph's Network by hitting the "Publish" button. + +- Remember that publishing is an on-chain action and will require gas to be paid for in Ethereum - see an example transaction [here](https://etherscan.io/tx/0xd0c3fa0bc035703c9ba1ce40c1862559b9c5b6ea1198b3320871d535aa0de87b). Prices are roughly around 0.0425 ETH at 100 gwei. +- Any time you need to upgrade your subgraph, you will be charged an upgrade fee. Remember, upgrading is just publishing another version of your existing subgraph on-chain. Because this incurs a cost, it is highly recommended to deploy and test your subgraph on Rinkeby before deploying to mainnet. It can, in some cases, also require some GRT if there is no signal on that subgraph. In the case there is signal/curation on that subgraph version (using auto-migrate), the taxes will be split. + +And that's it! After you are done publishing, you'll be able to view your subgraphs live on the network via [The Graph Explorer](https://thegraph.com/explorer). + +### Upgrading a Subgraph on the Network + +If you would like to upgrade an existing subgraph on the network, you can do this by deploying a new version of your subgraph to the Subgraph Studio using the Graph CLI. + +1. Make changes to your current subgraph. A good idea is to test small fixes on the Subgraph Studio by publishing to Rinkeby. +2. Deploy the following and specify the new version in the command (eg. v0.0.1, v0.0.2, etc): + +```sh +graph deploy --studio +``` + +3. Test the new version in the Subgraph Studio by querying in the playground +4. Publish the new version on The Graph Network. Remember that this requires gas (as described in the section above). + +### Owner Upgrade Fee: Deep Dive + +An upgrade requires GRT to be migrated from the old version of the subgraph to the new version. This means that for every upgrade, a new bonding curve will be created (more on bonding curves [here](/curating#bonding-curve-101)). + +The new bonding curve charges the 2.5% curation tax on all GRT being migrated to the new version. The owner must pay 50% of this, or 1.25%. The other 1.25% is absorbed by all the curators as a fee. This incentive design is in place to prevent an owner of a subgraph from being able to drain all their curator's funds with recursive upgrade calls. The example below is only the case if your subgraph is being actively curated on. If there is no curation activity, you will have to pay a minimum of 100 GRT in order to signal yourself on your own subgraph. + +- 100,000 GRT is signaled using auto-migrate on v1 of a subgraph +- Owner upgrades to v2. 100,000 GRT is migrated to a new bonding curve, where 97,500 GRT get put into the new curve and 2,500 GRT is burned +- The owner then has 1250 GRT burned to pay for half the fee. The owner must have this in their wallet before the upgrade, otherwise the upgrade will not succeed. This happens in the same transaction as the upgrade. + +_While this mechanism is currently live on the network, the community is currently discussing ways to reduce the cost of upgrades for subgraph developers._ + +### Maintaining a Stable Version of a Subgraph + +If you're making a lot of changes to your subgraph, it is not a good idea to continually upgrade it and front the upgrade costs. Maintaining a stable and consistent version of your subgraph is critical, not only from the cost perspective, but also so that Indexers can feel confident in their syncing times. Indexers should be flagged when you plan for an upgrade so that Indexer syncing times do not get impacted. Feel free to leverage the [#Indexers channel](https://discord.gg/8tgJ7rKW) on Discord to let Indexers know when you're versioning your subgraphs. + +Subgraphs are open API that external developers are leveraging. Open APIs need to follow strict standards so that they do not break external developers' applications. In The Graph Network, a subgraph developer must consider Indexers and how long it takes them to sync a new subgraph **as well as** other developers who are using their subgraphs. + +### Updating the Metadata of a Subgraph + +You can update the metadata of your subgraphs without having to publish a new version. The metadata includes the subgraph name, image, description, website URL, source code URL, and categories. Developers can do this by updating their subgraph details in the Subgraph Studio where you can edit all applicable fields. + +Make sure **Update Subgraph Details in Explorer** is checked and click on **Save**. If this is checked, an an on-chain transaction will be generated that updates subgraph details in the Explorer without having to publish a new version with a new deployment. + +## Best Practices for Deploying a Subgraph to The Graph Network + +1. Leveraging an ENS name for Subgraph Development + +- Set up your ENS: [https://app.ens.domains/](https://app.ens.domains/) +- Add your ENS name to your settings [here](https://thegraph.com/explorer/settings?view=display-name). + +The more filled out your profiles are, the better the chances for your subgraphs to be indexed and curated. + +## Deprecating a Subgraph on The Graph Network + +Follow the steps [here](/developer/deprecating-a-subgraph) to deprecate your subgraph and remove it from The Graph Network. + +## Querying a Subgraph + Billing on The Graph Network + +The Hosted Service was set up to allow developers to deploy their subgraphs without any restrictions. + +In order for The Graph Network to truly be decentralized, query fees have to be paid as a core part of the protocol's incentives. For more information on subscribing to APIs and paying the query fees, check out billing documentation [here](/studio/billing). + +### Estimate Query Fees on the Network + +While this is not a live feature in the product UI, you can set your maximum budget per query by taking the amount you're willing to pay per month and divide it by your expected query volume. + +While you get to decide on your query budget, there is no guarantee that an Indexer will be willing to serve queries at that price. If a Gateway can match you to an Indexer willing to serve a query at, or lower than, the price you are willing to pay, you will pay the delta/difference of your budget **and** their price. As a consequence of that, a lower query price reduces the pool of Indexers available to you, which may affect the quality of service you receive. It's beneficial to have high query fees, as that may attract curation and big name Indexers to your subgraph. + +Remember that it's a dynamic and growing market, but how you interact with it is in your control. There is no maximum or minimum price specified in the protocol or in the Gateways. For example, you can look at the price paid by a few of the dapps on the network (on a per week basis), below. See the last column which shows query fees in GRT. For example, [Pickle Finance](https://www.pickle.finance/) has 8 requests per second and paid 2.4 GRT for one week. + +![QueryFee](/img/QueryFee.png) + +## Additional Resources + +If you're still confused, fear not! Check out the following resources or watch our video guide on migrating subgraphs to the decentralized network below: + +
+ +
+ +- [The Graph Network Contracts](https://github.com/graphprotocol/contracts) +- [Curation Contract](https://github.com/graphprotocol/contracts/blob/dev/contracts/curation/Curation.sol) - the underlying contract that the GNS wraps around + - Address - `0x8fe00a685bcb3b2cc296ff6ffeab10aca4ce1538` +- [Subgraph Studio documentation](/studio/subgraph-studio) diff --git a/pages/zh/hosted-service/query-hosted-service.mdx b/pages/zh/hosted-service/query-hosted-service.mdx new file mode 100644 index 000000000000..731e3a3120b2 --- /dev/null +++ b/pages/zh/hosted-service/query-hosted-service.mdx @@ -0,0 +1,28 @@ +--- +title: Query the Hosted Service +--- + +With the subgraph deployed, visit the [Hosted Service](https://thegraph.com/hosted-service/) to open up a [GraphiQL](https://github.com/graphql/graphiql) interface where you can explore the deployed GraphQL API for the subgraph by issuing queries and viewing the schema. + +An example is provided below, but please see the [Query API](/developer/graphql-api) for a complete reference on how to query the subgraph's entities. + +#### Example + +This query lists all the counters our mapping has created. Since we only create one, the result will only contain our one `default-counter`: + +```graphql +{ + counters { + id + value + } +} +``` + +## Using The Hosted Service + +The Graph Explorer and its GraphQL playground is a useful way to explore and query deployed subgraphs on the Hosted Service. + +Some of the main features are detailed below: + +![Explorer Playground](/img/explorer-playground.png) diff --git a/pages/zh/hosted-service/what-is-hosted-service.mdx b/pages/zh/hosted-service/what-is-hosted-service.mdx new file mode 100644 index 000000000000..7f604c8dc31a --- /dev/null +++ b/pages/zh/hosted-service/what-is-hosted-service.mdx @@ -0,0 +1,77 @@ +--- +title: What is the Hosted Service? +--- + +This section will walk you through deploying a subgraph to the Hosted Service, otherwise known as the [Hosted Service.](https://thegraph.com/hosted-service/) As a reminder, the Hosted Service will not be shut down soon. We will gradually sunset the Hosted Service once we reach feature parity with the decentralized network. Your subgraphs deployed on the Hosted Service are still available [here.](https://thegraph.com/hosted-service/) + +If you don't have an account on the Hosted Service, you can signup with your Github account. Once you authenticate, you can start creating subgraphs through the UI and deploying them from your terminal. Graph Node supports a number of Ethereum testnets (Rinkeby, Ropsten, Kovan) in addition to mainnet. + +## Create a Subgraph + +First follow the instructions [here](/developer/define-subgraph-hosted) to install the Graph CLI. Create a subgraph by passing in `graph init --product hosted service` + +### From an Existing Contract + +If you already have a smart contract deployed to Ethereum mainnet or one of the testnets, bootstrapping a new subgraph from this contract can be a good way to get started on the Hosted Service. + +You can use this command to create a subgraph that indexes all events from an existing contract. This will attempt to fetch the contract ABI from [Etherscan](https://etherscan.io/). + +```sh +graph init \ + --product hosted-service + --from-contract \ + / [] +``` + +Additionally, you can use the following optional arguments. If the ABI cannot be fetched from Etherscan, it falls back to requesting a local file path. If any optional arguments are missing from the command, it takes you through an interactive form. + +```sh +--network \ +--abi \ +``` + +The `` in this case is your github user or organization name, `` is the name for your subgraph, and `` is the optional name of the directory where graph init will put the example subgraph manifest. The `` is the address of your existing contract. `` is the name of the Ethereum network that the contract lives on. `` is a local path to a contract ABI file. **Both --network and --abi are optional.** + +### From an Example Subgraph + +The second mode `graph init` supports is creating a new project from an example subgraph. The following command does this: + +``` +graph init --from-example --product hosted-service / [] +``` + +The example subgraph is based on the Gravity contract by Dani Grant that manages user avatars and emits `NewGravatar` or `UpdateGravatar` events whenever avatars are created or updated. The subgraph handles these events by writing `Gravatar` entities to the Graph Node store and ensuring these are updated according to the events. Continue on to the [subgraph manifest](/developer/create-subgraph-hosted#the-subgraph-manifest) to better understand which events from your smart contracts to pay attention to, mappings, and more. + +## Supported Networks on the Hosted Service + +Please note that the following networks are supported on the Hosted Service. Networks outside of Ethereum mainnet ('mainnet') are not currently supported on [The Graph Explorer.](https://thegraph.com/explorer) + +- `mainnet` +- `kovan` +- `rinkeby` +- `ropsten` +- `goerli` +- `poa-core` +- `poa-sokol` +- `xdai` +- `near-mainnet` +- `near-testnet` +- `matic` +- `mumbai` +- `fantom` +- `bsc` +- `chapel` +- `clover` +- `avalanche` +- `fuji` +- `celo` +- `celo-alfajores` +- `fuse` +- `moonriver` +- `mbase` +- `arbitrum-one` +- `arbitrum-rinkeby` +- `optimism` +- `optimism-kovan` +- `aurora` +- `aurora-testnet` diff --git a/pages/zh/indexing.mdx b/pages/zh/indexing.mdx index 7fd83d4d5333..f4c2f6f49ef4 100644 --- a/pages/zh/indexing.mdx +++ b/pages/zh/indexing.mdx @@ -26,7 +26,7 @@ import { Difficulty } from '@/components' ### 奖励如何分配？ -索引奖励来自协议通胀，每年发行量设定为 3%。 它们根据每个子图上所有策展信号的比例分布在子图上，然后根据他们在该子图上分配的股份按比例分配给索引人。 **分配必须以符合仲裁章程规定标准的有效索引证明（POI）结清，才有资格获得奖励。 ** +索引奖励来自协议通胀，每年发行量设定为 3%。 它们根据每个子图上所有策展信号的比例分布在子图上，然后根据他们在该子图上分配的股份按比例分配给索引人。 **An allocation must be closed with a valid proof of indexing (POI) that meets the standards set by the arbitration charter in order to be eligible for rewards.** 社区创建了许多用于计算奖励的工具，您会在 [“社区指南”集合](https://www.notion.so/Community-Guides-abbb10f4dba040d5ba81648ca093e70c)中找到它们。 您还可以在 [Discord 服务器](https://discord.gg/vtvv7FP)上的 #delegators 和 #indexers 频道 ​​ 中找到最新的工具列表。 @@ -115,11 +115,11 @@ Disputes can be viewed in the UI in an Indexer's profile page under the `Dispute - **大型** -准备对当前使用的所有子图进行索引，并为相关流量的请求提供服务 | Setup | (CPU 数量) | (内存 GB) | (硬盘 TB) | (CPU 数量) | (内存 GB) | -| ----- | :--------: | :-------: | :-------: | :--------: | :-------: | -| 小型 | 4 | 8 | 1 | 4 | 16 | -| 标准 | 8 | 30 | 1 | 12 | 48 | -| 中型 | 16 | 64 | 2 | 32 | 64 | -| 大型 | 72 | 468 | 3.5 | 48 | 184 | +| ----- |:--------:|:-------:|:-------:|:--------:|:-------:| +| 小型 | 4 | 8 | 1 | 4 | 16 | +| 标准 | 8 | 30 | 1 | 12 | 48 | +| 中型 | 16 | 64 | 2 | 32 | 64 | +| 大型 | 72 | 468 | 3.5 | 48 | 184 | ### 索引人应该采取哪些基本的安全防范措施？ @@ -129,13 +129,13 @@ Disputes can be viewed in the UI in an Indexer's profile page under the `Dispute ## 基础设施 -At the center of an indexer's infrastructure is the Graph Node which monitors Ethereum, extracts and loads data per a subgraph definition and serves it as a [GraphQL API](/about/introduction#how-the-graph-works). The Graph Node needs to be connected to Ethereum EVM node endpoints, and IPFS node for sourcing data; a PostgreSQL database for its store; and indexer components which facilitate its interactions with the network. The Graph Node needs to be connected to Ethereum EVM node endpoints, and IPFS node for sourcing data; a PostgreSQL database for its store; and indexer components which facilitate its interactions with the network. +At the center of an indexer's infrastructure is the Graph Node which monitors Ethereum, extracts and loads data per a subgraph definition and serves it as a [GraphQL API](/about/introduction#how-the-graph-works). The Graph Node needs to be connected to Ethereum EVM node endpoints, and IPFS node for sourcing data; a PostgreSQL database for its store; and indexer components which facilitate its interactions with the network. - **PostgreSQL 数据库** - Graph 节点的主要存储，这是存储子图数据的地方。 索引人服务和代理也使用数据库来存储状态通道数据、成本模型和索引规则。 - **Ethereum endpoint** -公开 Ethereum JSON-RPC API 的端点。 这可能采取单个 Ethereum 客户端的形式，也可能是一个更复杂的设置，在多个客户端之间进行负载平衡。 需要注意的是，某些子图将需要特定的 Ethereum 客户端功能，如存档模式和跟踪 API。 -- ** IPFS 节点（版本小于 5）** - 子图部署元数据存储在 IPFS 网络上。 The Graph Node primarily accesses the IPFS node during subgraph deployment to fetch the subgraph manifest and all linked files. The Graph Node primarily accesses the IPFS node during subgraph deployment to fetch the subgraph manifest and all linked files. Network indexers do not need to host their own IPFS node, an IPFS node for the network is hosted at https://ipfs.network.thegraph.com. +- ** IPFS 节点（版本小于 5）** - 子图部署元数据存储在 IPFS 网络上。 The Graph Node primarily accesses the IPFS node during subgraph deployment to fetch the subgraph manifest and all linked files. Network indexers do not need to host their own IPFS node, an IPFS node for the network is hosted at https://ipfs.network.thegraph.com. - **索引人服务** -处理与网络的所有必要的外部通信。 共享成本模型和索引状态，将来自网关的查询请求传递给一个 Graph 节点，并通过状态通道与网关管理查询支付。 @@ -149,26 +149,26 @@ At the center of an indexer's infrastructure is the Graph Node which monitors Et #### Graph 节点 -| 端口 | Purpose | 路径 | CLI Argument | 环境 变量 | -| --- | --- | --- | --- | --- | -| 8000 | GraphQL HTTP 服务
（用于子图查询） | /subgraphs/id/...

/subgraphs/name/.../... | --http-port | - | -| 8001 | GraphQL WS
（用于子图订阅） | /subgraphs/id/...

/subgraphs/name/.../... | --ws-port | - | -| 8020 | JSON-RPC
（用于管理部署） | / | --admin-port | - | -| 8030 | 子图索引状态 API | /graphql | --index-node-port | - | -| 8040 | Prometheus 指标 | /metrics | --metrics-port | - | +| 端口 | Purpose | 路径 | CLI Argument | 环境 变量 | +| ---- | ------------------------------------ | ------------------------------------------------------------------- | ----------------- | ----- | +| 8000 | GraphQL HTTP 服务
（用于子图查询） | /subgraphs/id/...

/subgraphs/name/.../... | --http-port | - | +| 8001 | GraphQL WS
（用于子图订阅） | /subgraphs/id/...

/subgraphs/name/.../... | --ws-port | - | +| 8020 | JSON-RPC
（用于管理部署） | / | --admin-port | - | +| 8030 | 子图索引状态 API | /graphql | --index-node-port | - | +| 8040 | Prometheus 指标 | /metrics | --metrics-port | - | #### 索引人服务 -| 端口 | Purpose | 路径 | CLI Argument | 环境 变量 | -| --- | --- | --- | --- | --- | -| 7600 | GraphQL HTTP 服务
（用于付费子图查询） | /subgraphs/id/...
/status
/channel-messages-inbox | --port | `INDEXER_SERVICE_PORT` | -| 7300 | Prometheus 指标 | /metrics | --metrics-port | - | +| 端口 | Purpose | 路径 | CLI Argument | 环境 变量 | +| ---- | -------------------------------------- | --------------------------------------------------------------------------- | -------------- | ---------------------- | +| 7600 | GraphQL HTTP 服务
（用于付费子图查询） | /subgraphs/id/...
/status
/channel-messages-inbox | --port | `INDEXER_SERVICE_PORT` | +| 7300 | Prometheus 指标 | /metrics | --metrics-port | - | #### 索引人代理 -| 端口 | Purpose | 路径 | CLI Argument | 环境
变量 | -| ---- | -------------- | ---- | ------------------------- | --------------------------------------- | -| 8000 | 索引人管理 API | / | --indexer-management-port | `INDEXER_AGENT_INDEXER_MANAGEMENT_PORT` | +| 端口 | Purpose | 路径 | CLI Argument | 环境
变量 | +| ---- | --------- | -- | ------------------------- | --------------------------------------- | +| 8000 | 索引人管理 API | / | --indexer-management-port | `INDEXER_AGENT_INDEXER_MANAGEMENT_PORT` | ### Google Cloud 上使用 Terraform 建立基础架构 @@ -313,7 +313,7 @@ Deploy all resources with `kubectl apply -k $dir`. sudo apt-get install -y clang libpg-dev libssl-dev pkg-config ``` -#### 设置 +#### Setup 1. 启动 PostgreSQL 数据库服务器 @@ -340,7 +340,7 @@ cargo run -p graph-node --release -- \ - **Ethereum 节点** - 默认情况下，docker 编译设置将使用 mainnet:[http://host.docker.internal:8545](http://host.docker.internal:8545) 连接到主机上的 Ethereum 节点。 你可以通过更新 `docker-compose.yaml`来替换这个网络名和 url。 -#### 设置 +#### Setup 1. 克隆 Graph 节点并导航到 Docker 目录。 @@ -373,7 +373,7 @@ docker-compose up #### 开始 -索引人代理和索引人服务应该与你的 Graph 节点基础架构共同定位。 有很多方法可以为你的索引人组件设置虚拟执行环境，这里我们将解释如何使用 NPM 包或源码在裸机上运行它们，或者通过谷歌云 Kubernetes 引擎上的 kubernetes 和 docker 运行。 如果这些设置示例不能很好地翻译到你的基础架构上，很可能会有一个社区指南可以参考，快来 [Discord](https://thegraph.com/discord)上打招呼吧!! 记得在启动你的索引人组件之前，要先在 [协议中打委托!](/indexing#stake-in-the-protocol)! Remember to [stake in the protocol](/indexing#stake-in-the-protocol) before starting up your indexer components! Remember to [stake in the protocol](/indexing#stake-in-the-protocol) before starting up your indexer components! +索引人代理和索引人服务应该与你的 Graph 节点基础架构共同定位。 有很多方法可以为你的索引人组件设置虚拟执行环境，这里我们将解释如何使用 NPM 包或源码在裸机上运行它们，或者通过谷歌云 Kubernetes 引擎上的 kubernetes 和 docker 运行。 If these setup examples do not translate well to your infrastructure there will likely be a community guide to reference, come say hi on [Discord](https://thegraph.com/discord)! Remember to [stake in the protocol](/indexing#stake-in-the-protocol) before starting up your indexer components! #### 来自 NPM 包 @@ -400,6 +400,15 @@ graph indexer ... # Indexer agent graph-indexer-agent start ... +# Indexer CLI +#Forward the port of your agent pod if using Kubernetes +kubectl port-forward pod/POD_ID 18000:8000 +graph indexer connect http://localhost:18000/ +graph indexer ... + +# Indexer agent +graph-indexer-agent start ... + # Indexer CLI #Forward the port of your agent pod if using Kubernetes kubectl port-forward pod/POD_ID 18000:8000 @@ -421,6 +430,17 @@ cd packages/indexer-service cd packages/indexer-agent ./bin/graph-indexer-service start ... +# From Repo root directory +yarn + +# Indexer Service +cd packages/indexer-service +./bin/graph-indexer-service start ... + +# Indexer agent +cd packages/indexer-agent +./bin/graph-indexer-service start ... + # Indexer CLI cd packages/indexer-cli ./bin/graph-indexer-cli indexer connect http://localhost:18000/ @@ -487,6 +507,7 @@ docker run -p 7600:7600 -it indexer-service:latest ... docker run -p 18000:8000 -it indexer-agent:latest ... docker run -p 18000:8000 -it indexer-agent:latest ... docker run -p 18000:8000 -it indexer-agent:latest ... +docker run -p 18000:8000 -it indexer-agent:latest ... ``` 请参阅 [在 Google Cloud 上使用 Terraform 设置服务器基础架构](/indexing#setup-server-infrastructure-using-terraform-on-google-cloud) 一节。 @@ -555,7 +576,7 @@ graph-indexer-service start \ #### 索引人 CLI -npm install -g @graphprotocol/indexer-service npm install -g @graphprotocol/indexer-agent # Indexer CLI is a plugin for Graph CLI, so both need to be installed: npm install -g @graphprotocol/graph-cli npm install -g @graphprotocol/indexer-cli # Indexer service graph-indexer-service start ... # Indexer agent graph-indexer-agent start ... # Indexer CLI #Forward the port of your agent pod if using Kubernetes kubectl port-forward pod/POD_ID 18000:8000 graph indexer connect http://localhost:18000/ graph indexer ... +The Indexer CLI is a plugin for [`@graphprotocol/graph-cli`](https://www.npmjs.com/package/@graphprotocol/graph-cli) accessible in the terminal at `graph indexer`. ```sh graph indexer connect http://localhost:18000 @@ -634,15 +655,11 @@ query { pairs(skip: $skip) { id } } when $skip > 2000 => 0.0001 * $skip * $SYSTE # This default will match any GraphQL expression. # It uses a Global substituted into the expression to calculate cost default => 0.1 * $SYSTEM_LOAD; -# It uses a Global substituted into the expression to calculate cost -default => 0.1 * $SYSTEM_LOAD; -# It uses a Global substituted into the expression to calculate cost -default => 0.1 * $SYSTEM_LOAD; ``` 成本模型示例： -| 询问 | 价格 | +| 询问 | 价格 | | ---------------------------------------------------------------------------- | ------- | | { pairs(skip: 5000) { id } } | 0.5 GRT | | { tokens { symbol } } | 0.1 GRT | diff --git a/pages/zh/studio/billing.mdx b/pages/zh/studio/billing.mdx new file mode 100644 index 000000000000..588cd2ed2f40 --- /dev/null +++ b/pages/zh/studio/billing.mdx @@ -0,0 +1,68 @@ +--- +title: Billing on the Subgraph Studio +--- + +### Overview + +Invoices are statements of payment amounts owed by a customer and are typically generated on a weekly basis in the system. You’ll be required to pay fees based on the query fees you generate using your API keys. The billing contract lives on the [Polygon](https://polygon.technology/) network. It’ll allow you to: + +- Add and remove GRT +- Keep track of your balances based on how much GRT you have added to your account, how much you have removed, and your invoices +- Automatically clear payments based on query fees generated + +In order to add GRT to your account, you will need to go through the following steps: + +1. Purchase GRT and ETH on an exchange of your choice +2. Send the GRT and ETH to your wallet +3. Bridge GRT to Polygon using the UI + + a) You will receive 0.001 Matic in a few minutes after you send any amount of GRT to the Polygon bridge. You can track the transaction on [Polygonscan](https://polygonscan.com/) by inputting your address into the search bar. + +4. Add bridged GRT to the billing contract on Polygon. The billing contract address is: [0x10829DB618E6F520Fa3A01c75bC6dDf8722fA9fE](https://polygonscan.com/address/0x10829DB618E6F520Fa3A01c75bC6dDf8722fA9fE). + + a) In order to complete step #4, you'll need to switch your network in your wallet to Polygon. You can add Polygon's network by connecting your wallet and clicking on "Choose Matic (Polygon) Mainnet" [here.](https://chainlist.org/) Once you've added the network, switch it over in your wallet by navigating to the network pill on the top right hand side corner. In Metamask, the network is called **Matic Mainnnet.** + +At the end of each week, if you used your API keys, you will receive an invoice based on the query fees you have generated during this period. This invoice will be paid using GRT available in your balance. Query volume is evaluated by the API keys you own. Your balance will be updated after fees are withdrawn. + +#### Here’s how you go through the invoicing process: + +There are 4 states your invoice can be in: + +1. Created - your invoice has just been created and not been paid yet +2. Paid - your invoice has been successfully paid +3. Unpaid - there is not enough GRT in your balance on the billing contract +4. Error - there is an error processing the payment + +**See the diagram below for more information:** + +![Billing Flow](/img/billing-flow.png) + +For a quick demo of how billing works on the Subgraph Studio, check out the video below: + +
+ +
+ +### Multisig Users + +Multisigs are smart-contracts that can exist only on the network they have been created, so if you created one on Ethereum Mainnet - it will only exist on Mainnet. Since our billing uses Polygon, if you were to bridge GRT to the multisig address on Polygon the funds would be lost. + +To overcome this issue, we created [a dedicated tool](https://multisig-billing.thegraph.com/) that will help you deposit GRT on our billing contract (on behalf of the multisig) with a standard wallet / EOA (an account controlled by a private key). + +You can access our Multisig Billing Tool here: https://multisig-billing.thegraph.com/ + +This tool will guide you to go through the following steps: + +1. Connect your standard wallet / EOA (this wallet needs to own some ETH as well as the GRT you want to deposit) +2. Bridge GRT to Polygon. You will have to wait 7-8 minutes after the transaction is complete for the bridge transfer to be finalized. +3. Once your GRT is available on your Polygon balance you can deposit them to the billing contract while specifying the multisig address you are funding in the `Multisig Address` field. + +Once the deposit transaction has been confirmed you can go back to [Subgraph Studio](https://thegraph.com/studio/) and connect with your Gnosis Safe Multisig to create API keys and use them to generate queries. + +Those queries will generate invoices that will be paid automatically using the multisig’s billing balance. diff --git a/pages/zh/studio/deploy-subgraph-studio.mdx b/pages/zh/studio/deploy-subgraph-studio.mdx new file mode 100644 index 000000000000..2155d8fe8976 --- /dev/null +++ b/pages/zh/studio/deploy-subgraph-studio.mdx @@ -0,0 +1,68 @@ +--- +title: Deploy a Subgraph to the Subgraph Studio +--- + +Deploying a Subgraph to the Subgraph Studio is quite simple. This will take you through the steps to: + +- Install The Graph CLI (with both yarn and npm) +- Create your Subgraph in the Subgraph Studio +- Authenticate your account from the CLI +- Deploying a Subgraph to the Subgraph Studio + +## Installing Graph CLI + +We are using the same CLI to deploy subgraphs to our [hosted service](https://thegraph.com/hosted-service/) and to the [Subgraph Studio](https://thegraph.com/studio/). Here are the commands to install graph-cli. This can be done using npm or yarn. + +**Install with yarn:** + +```bash +yarn global add @graphprotocol/graph-cli +``` + +**Install with npm:** + +```bash +npm install -g @graphprotocol/graph-cli +``` + +## Create your Subgraph in Subgraph Studio + +Before deploying your actual subgraph you need to create a subgraph in [Subgraph Studio](https://thegraph.com/studio/). We recommend you read our [Studio documentation](/studio/subgraph-studio) to learn more about this. + +## Initialize your Subgraph + +Once your subgraph has been created in Subgraph Studio you can initialize the subgraph code using this command: + +```bash +graph init --studio +``` + +The `` value can be found on your subgraph details page in Subgraph Studio: + +![Subgraph Studio - Slug](/img/doc-subgraph-slug.png) + +After running `graph init`, you will be asked to input the contract address, network and abi that you want to query. Doing this will generate a new folder on your local machine with some basic code to start working on your subgraph. You can then finalize your subgraph to make sure it works as expected. + +## Graph Auth + +Before being able to deploy your subgraph to Subgraph Studio, you need to login to your account within the CLI. To do this, you will need your deploy key that you can find on your "My Subgraphs" page or on your subgraph details page. + +Here is the command that you need to use to authenticate from the CLI: + +```bash +graph auth --studio +``` + +## Deploying a Subgraph to Subgraph Studio + +Once you are ready, you can deploy your subgraph to Subgraph Studio. Doing this won't publish your subgraph to the decentralized network, it will only deploy it to your Studio account where you will be able to test it and update the metadata. + +Here is the CLI command that you need to use to deploy your subgraph. + +```bash +graph deploy --studio +``` + +After running this command, the CLI will ask for a version label, you can name it however you want, you can use labels such as `0.1` and `0.2` or use letters as well such as `uniswap-v2-0.1` . Those labels will be visible in Graph Explorer and can be used by curators to decide if they want to signal on this version or not, so choose them wisely. + +Once deployed, you can test your subgraph in Subgraph Studio using the playground, deploy another version if needed, update the metadata, and when you are ready, publish your subgraph to Graph Explorer. diff --git a/pages/zh/studio/multisig.mdx b/pages/zh/studio/multisig.mdx new file mode 100644 index 000000000000..164835bdb8a4 --- /dev/null +++ b/pages/zh/studio/multisig.mdx @@ -0,0 +1,82 @@ +--- +title: Using a Multisig Wallet +--- + +Subgraph Studio currently doesn't support signing with multisig wallets. Until then, you can follow this guide on how to publish your subgraph by invoking the [GNS contract](https://github.com/graphprotocol/contracts/blob/dev/contracts/discovery/GNS.sol) functions. + +### Create a Subgraph + +Similary to using a regular wallet, you can create a subgraph by connecting your non-multisig wallet in Subgraph Studio. Once you connect the wallet, simply create a new subgraph. Make sure you fill out all the details, such as subgraph name, description, image, website, and source code url if applicable. + +For initializing a starter subgraph, you can follow the commands shown in the UI, or simply run + +``` +graph init --studio +``` + +`SUBGRAPH_SLUG` is the name of your subgraph that you can copy from the UI, or from the URL in the browser. This command should create a folder in your file system with all the necessary files to start developing a subgraph. + +### Deploy a Subgraph + +Once your subgraph is ready to be deployed to the graph node, simply follow the commands shown in the UI, or run the following command: + +``` +graph deploy --studio +``` + +**Note**: Make sure that you are inside of the subgraph folder before running the command. + +### Publish a Subgraph or a Version + +You can either publish a new subgraph to the decentralized network or publish a new version of the previously published subgraph. + +#### Publish a New Subgraph + +There are a couple of ways to publish a subgraph using multisig wallets. Here we'll describe invoking the [`publishNewSubgraph`](https://github.com/graphprotocol/contracts/blob/dev/contracts/discovery/GNS.sol#L231) function in the [GNS contract](https://etherscan.io/address/0xaDcA0dd4729c8BA3aCf3E99F3A9f471EF37b6825) using Etherscan. + +Before we use that function, we need to generate input arguments for it. Access [this page](https://thegraph.com/studio/multisig) in Subgraph Studio and provide the following: + +- Ethereum address of your multisig wallet +- Subgraph that you want to publish +- Version that you want to publish + +After clicking on "Get Arguments", we'll generate all the contract arguments for you! + +There should be 4 arguments: + +- `graphAccount`: which is your multisig account address +- `subgraphDeploymentID`: the hex hash of the deployment ID for that subgraph +- `versionMetadata`: version metadata (label and description) that gets uploaded to IPFS. The hex hash value for that JSON file will be provided. +- `subgraphMetadata`: simlar to version metadata, subgraph metadata (name, image, description, website and source code url) gets uploaded to IPFS, and we provide the hex hash value for that JSON file + +With those 4 arguments, you should be able to: + +- Visit [our GraphProxy](https://etherscan.io/address/0xaDcA0dd4729c8BA3aCf3E99F3A9f471EF37b6825#writeProxyContract) contract on Etherscan +- Connect to Etherscan using WalletConnect via the WalletConnect Safe app of your multisig +- Call the `publishNewSubgraph` method with the paramaters that were generated by our tool + +#### Publish a New Version + +To publish a new version of an existing subgraph we first need to generate input arguments for it. Access [this page](https://thegraph.com/studio/multisig) in Subgraph Studio and provide: + +- Ethereum address of your multisig wallet +- Subgraph that you want to publish +- Version that you want to publish +- The ID of the subgraph you want to update in Graph Explorer + +After clicking on "Get Arguments" we'll generate all the contract arguments for you! + +On the right side of the UI under the `Publish New Version` title, there should be 4 arguments: + +- `graphAccount`: which is your Multisig account address +- `subgraphNumber`: is the number of your already published subgraph. It is a part of the subgraph id for a published subgraph queried through The Graph Network subgraph. +- `subgraphDeploymentID`: which is the hex hash of the deployment ID for that subgraph +- `versionMetadata`: version metadata (label and description) gets uploaded to IPFS, and we provide the hex hash value for that JSON file + +Now that we generated all the arguments you are ready to proceed and call the `publishNewVersion` method. In order to do so, you should: + +- Visit [the GraphProxy](https://etherscan.io/address/0xaDcA0dd4729c8BA3aCf3E99F3A9f471EF37b6825#writeProxyContract) contract on Etherscan +- Connect to Etherscan using WalletConnect via the WalletConnect Safe app of your Multisig +- Call the `publishNewVersion` method with the paramaters that were generated by our tool + +Once the transaction is successful, your subgraph should have a new version of your subgraph in Graph Explorer which means that curators can start signaling on it and indexers can start indexing it. diff --git a/pages/zh/studio/studio-faq.mdx b/pages/zh/studio/studio-faq.mdx new file mode 100644 index 000000000000..4db4d7ccddaa --- /dev/null +++ b/pages/zh/studio/studio-faq.mdx @@ -0,0 +1,21 @@ +--- +title: Subgraph Studio FAQs +--- + +### 1. How do I create an API Key? + +In the Subgraph Studio, you can create API Keys as needed and add security settings to each of them. + +### 2. Can I create multiple API Keys? + +A: Yes! You can create multiple API Keys to use in different projects. Check out the link [here](https://thegraph.com/studio/apikeys/). + +### 3. How do I restrict a domain for an API Key? + +After creating an API Key, in the Security section you can define the domains that can query a specific API Key. + +### 4. How do I find query URLs for subgraphs if I’m not the developer of the subgraph I want to use? + +You can find the query URL of each subgraph in the Subgraph Details section of The Graph Explorer. When you click on the “Query” button, you will be directed to a pane wherein you can view the query URL of the subgraph you’re interested in. You can then replace the `` placeholder with the API key you wish to leverage in the Subgraph Studio. + +Remember that you can create an API key and query any subgraph published to the network, even if you build a subgraph yourself. These queries via the new API key, are paid queries as any other on the network. diff --git a/pages/zh/studio/subgraph-studio.mdx b/pages/zh/studio/subgraph-studio.mdx new file mode 100644 index 000000000000..9af3926db3df --- /dev/null +++ b/pages/zh/studio/subgraph-studio.mdx @@ -0,0 +1,122 @@ +--- +title: How to Use the Subgraph Studio +--- + +Welcome to your new launchpad 👩🏽‍🚀 + +The Subgraph Studio is your place to build and create subgraphs, add metadata, and publish them to the new decentralized Explorer (more on that [here](/explorer)). + +What you can do in the Subgraph Studio: + +- Create a subgraph through the Studio UI +- Deploy a subgraph using the CLI +- Publish a subgraph with the Studio UI +- Test it in the playground +- Integrate it in staging using the query URL +- Create and manage your API keys for specific subgraphs + +Here in the Subgraph Studio, you have full control over your subgraphs. Not only can you test your subgraphs before you publish them, but you can also restrict your API keys to specific domains and only allow certain indexers to query from their API keys. + +Querying subgraphs generates query fees, used to reward [indexers](/indexing) on the Graph network. If you’re a dapp developer or subgraph developer, the Studio will empower you to build better subgraphs to power your or your community’s queries. The Studio is comprised of 5 main parts: + +- Your user account controls +- A list of subgraphs that you’ve created +- A section to manage, view details, and visualize the status of a specific subgraph +- A section to manage your API keys that you will need to query a subgraph +- A section to manage your billing + +## How to Create Your Account + +1. Sign in with your wallet - you can do this via MetaMask or WalletConnect +1. Once you sign in, you will see your unique deploy key in your account home page. This will allow you to either publish your subgraphs or manage your API keys + billing. You will have a unique deploy key that can be re-generated if you think it has been compromised. + +## How to Create your Subgraph in Subgraph Studio + +The best part! When you first create a subgraph, you’ll be directed to fill out: + +- Your Subgraph Name +- Image +- Description +- Categories +- Website + +## Subgraph Compatibility with The Graph Network + +The Graph Network is not yet able to support all of the data-sources & features available on the Hosted Service. In order to be supported by indexers on the network, subgraphs must: + +- Index mainnet Ethereum +- Must not use any of the following features: + - ipfs.cat & ipfs.map + - Non-fatal errors + - Grafting + +More features & networks will be added to The Graph Network incrementally. + +### Subgraph lifecycle flow + +![Subgraph Lifecycle](/img/subgraph-lifecycle.png) + +After you have created your subgraph, you will be able to deploy it using the [CLI](https://github.com/graphprotocol/graph-cli), or command line interface. Deploying a subgraph with the CLI will push the subgraph to the Studio where you’ll be able to test subgraphs using the playground. This will eventually allow you to publish to the Graph Network. For more information on CLI setup, [check this out](/developer/define-subgraph-hosted#install-the-graph-cli) (pst, make sure you have your deploy key on hand). Remember, deploying is **not the same as** publishing. When you deploy a subgraph, you just push it to the Studio where you’re able to test it. Versus, when you publish a subgraph, you are publishing it on-chain. + +## Testing your Subgraph in Subgraph Studio + +If you’d like to test your subgraph before publishing it to the network, you can do this in the Subgraph **Playground** or look at your logs. The Subgraph logs will tell you **where** your subgraph fails in the case that it does. + +## Publish your Subgraph in Subgraph Studio + +You’ve made it this far - congrats! Publishing your subgraph means that an IPFS hash was generated when you deployed the subgraph within the CLI and is stored in the network’s Ethereum smart contracts. In order to publish your subgraph successfully, you’ll need to go through the following steps outlined in this [blog](https://thegraph.com/blog/building-with-subgraph-studio). Check out the video overview below as well: + +
+ +
+ +Remember, while you’re going through your publishing flow, you’ll be able to push to either mainnet or Rinkeby, the testnet we support. If you’re a first time subgraph developer, we highly suggest you start with publishing to Rinkeby, which is free to do. This will allow you to see how the subgraph will work in The Graph Explorer and will allow you to test curation elements. + +You’ll only be able to index data from mainnet (even if your subgraph was published to a testnet) because only subgraphs that are indexing mainnet data can be published to the network. This is because indexers need to submit mandatory Proof of Indexing records as of a specific block hash. Because publishing a subgraph is an action taken on-chain, remember that the transaction can take up to a few minutes to go through. Any address you use to publish the contract will be the only one able to publish future versions. Choose wisely! + +Subgraphs with curation signal are shown to Indexers so that they can be indexed on the decentralized network. You can publish subgraphs and signal in one transaction, which allows you to mint the first curation signal on the subgraph and saves on gas costs. By adding your signal to the signal later provided by Curators, your subgraph will also have a higher chance of ultimately serving queries. + +**Now that you’ve published your subgraph, let’s get into how you’ll manage them on a regular basis.** Note that you cannot publish your subgraph to the network if it has failed syncing. This is usually because the subgraph has bugs - the logs will tell you where those issues exist! + +## Versioning your Subgraph with the CLI + +Developers might want to update their subgraph, for a variety of reasons. When this is the case, you can deploy a new version of your subgraph to the Studio using the CLI (it will only be private at this point) and if you are happy with it, you can publish this new deployment to The Graph Explorer. This will create a new version of your subgraph that curators can start signaling on and indexers will be able to index this new version. + +Up until recently, developers were forced to deploy and publish a new version of their subgraph to the Explorer to update the metadata of their subgraphs. Now, developers can update the metadata of their subgraphs **without having to publish a new version**. Developers can update their subgraph details in the Studio (under profile picture, name, description, etc) by checking an option called **Update Details** in The Graph Explorer. If this is checked, an on-chain transaction will be generated that updates subgraph details in the Explorer without having to publish a new version with a new deployment. + +Please note that there are costs associated with publishing a new version of a subgraph to the network. In addition to the transaction fees, developers must also fund a part of the curation tax on auto-migrating signal. You cannot publish a new version of your subgraph if curators have not signaled on it. For more information on the risks of curation, please read more [here](/curating). + +### Automatic Archiving of Subgraph Versions + +Whenever you deploy a new subgraph version in the Subgraph Studio, the previous version will be archived. Archived versions won't be indexed/synced and therefore cannot be queried. You can unarchive an archived version of your subgraph in the Studio UI. Please note that previous versions of non-published subgraphs deployed to the Studio will be automatically archived. + +![Subgraph Studio - Unarchive](/img/Unarchive.png) + +## Managing your API Keys + +Regardless of whether you’re a dapp developer or a subgraph developer, you’ll need to manage your API keys. This is important for you to be able to query subgraphs because API keys make sure the connections between application services are valid and authorized. This includes authenticating the end user and the device using the application. + +The Studio will list out existing API keys, which will give you the ability to manage or delete them. + +1. The **Overview** section will allow you to: + - Edit your key name + - Regenerate API keys + - View the current usage of the API key with stats: + - Number of queries + - Amount of GRT spent +2. Under **Manage Security Settings**, you’ll be able to opt into security settings depending on the level of control you’d like to have over your API keys. In this section, you can: + - View and manage the domain names authorized to use your API key + - Assign subgraphs that can be queried with your API key + +## How to Manage your Subgraph + +API keys aside, you’ll have many tools at your disposal to manage your subgraphs. You can organize your subgraphs by their **status** and **category**. + +- The **Status** tag allows you to pick between a variety of tags including ``, ``, ``, ``, etc. +- Meanwhile, **Category** allows you to designate what category your subgraph falls into. Options include ``, ``, ``, etc. diff --git a/pages/zh/supported-networks/near.mdx b/pages/zh/supported-networks/near.mdx new file mode 100644 index 000000000000..bff2f82364d9 --- /dev/null +++ b/pages/zh/supported-networks/near.mdx @@ -0,0 +1,265 @@ +--- +title: Building Subgraphs on NEAR +--- + +> NEAR support in Graph Node and on the Hosted Service is in beta: please contact near@thegraph.com with any questions about building NEAR subgraphs! + +This guide is an introduction to building subgraphs indexing smart contracts on the [NEAR blockchain](https://docs.near.org/). + +## What is NEAR? + +[NEAR](https://near.org/) is a smart contract platform for building decentralised applications. Visit the [official documentation](https://docs.near.org/docs/concepts/new-to-near) for more information. + +## What are NEAR subgraphs? + +The Graph gives developers tools to process blockchain events and make the resulting data easily available via a GraphQL API, known individually as a subgraph. [Graph Node](https://github.com/graphprotocol/graph-node) is now able to process NEAR events, which means that NEAR developers can now build subgraphs to index their smart contracts. + +Subgraphs are event-based, which means that they listen for and then process on-chain events. There are currently two types of handlers supported for NEAR subgraphs: + +- Block handlers: these are run on every new block +- Receipt handlers: run every time a message is executed at a specified account + +[From the NEAR documentation](https://docs.near.org/docs/concepts/transaction#receipt): + +> A Receipt is the only actionable object in the system. When we talk about "processing a transaction" on the NEAR platform, this eventually means "applying receipts" at some point. + +## Building a NEAR Subgraph + +`@graphprotocol/graph-cli` is a command line tool for building and deploying subgraphs. + +`@graphprotocol/graph-ts` is a library of subgraph-specific types. + +NEAR subgraph development requires `graph-cli` above version `0.23.0`, and `graph-ts` above version `0.23.0`. + +> Building a NEAR subgraph is very similar to building a subgraph which indexes Ethereum. + +There are three aspects of subgraph definition: + +**subgraph.yaml:** the subgraph manifest, defining the data sources of interest, and how they should be processed. NEAR is a new `kind` of data source. + +**schema.graphql:** a schema file that defines what data is stored for your subgraph, and how to query it via GraphQL. The requirements for NEAR subgraphs are covered by [the existing documentation](/developer/create-subgraph-hosted#the-graphql-schema). + +**AssemblyScript Mappings:** [AssemblyScript code](/developer/assemblyscript-api) 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. + +During subgraph development there are two key commands: + +```bash +$ graph codegen # generates types from the schema file identified in the manifest +$ graph build # generates Web Assembly from the AssemblyScript files, and prepares all the subgraph files in a /build folder +``` + +### Subgraph Manifest Definition + +The subgraph manifest (`subgraph.yaml`) identifies the data sources for the subgraph, the triggers of interest, and the functions that should be run in response to those triggers. See below for an example subgraph manifest for a NEAR subgraph:: + +```yaml +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 subgraphs introduce a new `kind` of data source (`near`) +- The `network` should correspond to a network on the hosting Graph Node. On the Hosted Service, 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](https://docs.near.org/docs/concepts/account). This can be an account, or a sub account. + +NEAR data sources support two types of handlers: + +- `blockHandlers`: run on every new NEAR block. No `source.account` is required. +- `receiptHandlers`: run on every receipt where the data source's `source.account` is the recipient. Note that only exact matches are processed ([subaccounts](https://docs.near.org/docs/concepts/account#subaccounts) must be added as independent data sources). + +### Schema Definition + +Schema definition describes the structure of the resulting subgraph database, and the relationships between entities. This is agnostic of the original data source. There are more details on subgraph schema definition [here](/developer/create-subgraph-hosted#the-graphql-schema). + +### AssemblyScript Mappings + +The handlers for processing events are written in [AssemblyScript](https://www.assemblyscript.org/). + +NEAR indexing introduces NEAR-specific data types to the [AssemblyScript API](/developer/assemblyscript-api). + +```typescript + +class ExecutionOutcome { + gasBurnt: u64, + blockHash: Bytes, + id: Bytes, + logs: Array, + receiptIds: Array, + tokensBurnt: BigInt, + executorId: string, + } + +class ActionReceipt { + predecessorId: string, + receiverId: string, + id: CryptoHash, + signerId: string, + gasPrice: BigInt, + outputDataReceivers: Array, + inputDataIds: Array, + actions: Array, + } + +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, + } + +class ReceiptWithOutcome { + outcome: ExecutionOutcome, + receipt: ActionReceipt, + block: Block, + } +``` + +These types are passed to block & receipt handlers: + +- Block handlers will receive a `Block` +- Receipt handlers will receive a `ReceiptWithOutcome` + +Otherwise the rest of the [AssemblyScript API](/developer/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](/developer/assemblyscript-api#json-api) to allow developers to easily process these logs. + +## Deploying a NEAR Subgraph + +Once you have a built subgraph, it is time to deploy it to Graph Node for indexing. NEAR subgraphs can be deployed to any Graph Node `>=v0.26.x` (this version has not yet been tagged & released). + +The Graph's Hosted Service 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 the Hosted Service can be found [here](/hosted-service/deploy-subgraph-hosted). + +As a quick primer - the first step is to "create" your subgraph - this only needs to be done once. On the Hosted Service, this can be done from [your Dashboard](https://thegraph.com/hosted-service/dashboard): "Add Subgraph". + +Once your subgraph has been created, you can deploy your subgraph by using the `graph deploy` CLI command: + +``` +$ graph create --node subgraph/name # creates a subgraph on a local Graph Node (on the Hosted Service, this is done via the UI) +$ graph deploy --node --ipfs https://api.thegraph.com/ipfs/ # 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 +``` + +The node configuration will depend where the subgraph is being deployed. + +#### Hosted Service: + +``` +graph deploy --node https://api.thegraph.com/deploy/ --ipfs https://api.thegraph.com/ipfs/ --access-token +``` + +#### Local Graph Node (based on default configuration): + +``` +graph deploy --node http://localhost:8020/ --ipfs http://localhost:5001 +``` + +Once your subgraph has been deployed, it will be indexed by Graph Node. You can check its progress by querying the subgraph itself: + +``` +{ + _meta { + block { number } + } +} +``` + +### Indexing NEAR with a Local Graph Node + +Running a Graph Node that indexes NEAR has the following operational requirements: + +- NEAR Indexer Framework with Firehose instrumentation +- NEAR Firehose Component(s) +- Graph Node with Firehose endpoint configured + +We will provide more information on running the above components soon. + +## Querying a NEAR Subgraph + +The GraphQL endpoint for NEAR subgraphs is determined by the schema definition, with the existing API interface. Please visit the [GraphQL API documentation](/developer/graphql-api) for more information. + +## Example Subgraphs + +Here are some example subgraphs for reference: + +[NEAR Blocks](https://github.com/graphprotocol/example-subgraph/tree/near-blocks-example) + +[NEAR Receipts](https://github.com/graphprotocol/example-subgraph/tree/near-receipts-example) + +## 常见问题 + +### How does the beta work? + +NEAR support is in beta, which means that there may be changes to the API as we continue to work on improving the integration. Please email near@thegraph.com so that we can support you in building NEAR subgraphs, and keep you up to date on the latest developments! + +### Can a subgraph index both NEAR and EVM chains? + +No, a subgraph can only support data sources from one chain / network. + +### Can subgraphs react to more specific triggers? + +Currently, only Block and Receipt triggers are supported. We are investigating triggers for function calls to a specified account. We are also interested in supporting event triggers, once NEAR has native event support. + +### Will receipt handlers trigger for accounts and their sub accounts? + +Receipt handlers will only be triggered for the exact-match of the named account. More flexibility may be added in future. + +### Can NEAR subgraphs make view calls to NEAR accounts during mappings? + +This is not supported. We are evaluating whether this functionality is required for indexing. + +### Can I use data source templates in my NEAR subgraph? + +This is not currently supported. We are evaluating whether this functionality is required for indexing. + +### Ethereum subgraphs support "pending" and "current" versions, how can I deploy a "pending" version of a NEAR subgraph? + +Pending functionality is not yet supported for NEAR subgraphs. In the interim, you can deploy a new version to a different "named" subgraph, and then when that is synced with the chain head, you can redeploy to your primary "named" subgraph, which will use the same underlying deployment ID, so the main subgraph will be instantly synced. + +### My question hasn't been answered, where can I get more help building NEAR subgraphs? + +If it is a general question about subgraph development, there is a lot more information in the rest of the [Developer documentation](/developer/quick-start). Otherwise please join [The Graph Protocol Discord](https://discord.gg/vtvv7FP) and ask in the #near channel, or email near@thegraph.com. + +## References + +- [NEAR developer documentation](https://docs.near.org/docs/develop/basics/getting-started)