From 19b5c6c8b2c6054870c5c18e7ec41558c72af82d Mon Sep 17 00:00:00 2001 From: Enol <51820585+enoldev@users.noreply.github.com> Date: Mon, 21 Oct 2024 18:44:00 +0200 Subject: [PATCH] Vara How-To-Guide (#551) --- docs/SUMMARY.md | 1 + docs/new/consume/subgraph/triggers.md | 161 +------------------------- docs/new/how-to-guides/vara.md | 56 +++++++++ 3 files changed, 58 insertions(+), 160 deletions(-) create mode 100644 docs/new/how-to-guides/vara.md diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index 627a7467..e08f061a 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -9,6 +9,7 @@ * [Initialize a Solana Substreams Project](new/how-to-guides/solana.md) * [Initialize a Starknet Substreams Project](new/how-to-guides/starknet.md) * [Initialize an Injective Substreams Project](new/how-to-guides/injective.md) + * [Initialize a Vara Substreams Project](new/how-to-guides/vara.md) * [Consume Substreams](new/consume/consume.md) * [Install the CLI](new/common/installing-the-cli.md) * [Authentication](new/common/authentication.md) diff --git a/docs/new/consume/subgraph/triggers.md b/docs/new/consume/subgraph/triggers.md index 12bdc05c..86663de8 100644 --- a/docs/new/consume/subgraph/triggers.md +++ b/docs/new/consume/subgraph/triggers.md @@ -1,162 +1,3 @@ **Substreams triggers allow you to embed Substreams data directly in your subgraph**. Essentially, you **import the Protobufs emitted by your Substreams module** and you receive the data in the handler of your subgraph. -For example, consider that you want to consume the transactions emitted by the [map_filter_transactions module](https://github.com/streamingfast/substreams-explorers/blob/main/ethereum-explorer/src/map_filter_transactions.rs) of the Ethereum Explorer Substreams. With Substreams triggers, you can define a special subgraph handler that imports the Protobuf object and lets you manipulate the data just like a usual AssemblyScript object. - -The Protobuf used in the `map_filter_transactions` module is the following: - -```protobuf -syntax = "proto3"; - -package eth.transaction.v1; - -message Transactions { - repeated Transaction transactions = 1; -} - -message Transaction { - string from = 1; - string to = 2; - string hash = 3; -} -``` - -You can generate the previous Protobuf in AssemblyScript and import it as part of your subgraph in a special handler: - -```ts -export function handleTransactions(bytes: Uint8Array): void { - let transactions = assembly.eth.transaction.v1.Transactions.decode(bytes.buffer).trasanctions; // 1. - if (transactions.length == 0) { - log.info("No transactions found", []); - return; - } - - for (let i = 0; i < transactions.length; i++) { // 2. - let transaction = transactions[i]; - - let entity = new Transaction(transaction.hash); // 3. - entity.from = transaction.from; - entity.to = transaction.to; - entity.save(); - } -} -``` -1. You decode the bytes (which contains the Substreams data) into the generated object, `Transactions`. -Now you can use the object like any other AssemblyScript object. -2. Loop over the transactions -3. Create a new subgraph entity for every transaction. - -## Tutorial: Import the Substreams Explorer package transactions into a subgraph - -Following the previous example, the [Substreams Sink Examples](https://github.com/streamingfast/substreams-sink-examples) repository, contains a subgraph importing the transactions through Substreams triggers. Clone the repository and move to the `subgraph-triggers-transactions`. To run this tutorial you will need: - -- The Graph CLI, to build and deploy the subgraph. -- Node (>17) and NPM installed. -- The `buf` command installed, to generate the Protobuf schemas. - -### Install the Dependencies - -If you are familiar with subgraphs, then the structure of the project should be easy to understand: - -// image - -1. The `proto` folder contains the Protobuf definitions of your Substreams (i.e. the definitions you want to import into the subgraph). -2. The `src` folder contains the source code. Mainly, the `mapping.ts` file with the handlers and the `pb` folder with the generated TS code for the Protobuf. -3. Currently, it is necessary to have the Substreams package (`spkg`) that you want to import in your filesystem, so that you subgraph can read it. - - -- To get started, install the dependencies of the project: - -```bash -npm install -``` - -- Generate the Substreams Protobufs: - -```bash -buf generate --exclude-path="sf/substreams" --type="eth.transaction.v1.Transactions" ethereum-explorer-v0.1.2.spkg#format=bin -``` - -The previous command generates the Substreams Protobuf contained in the `ethereum-explorer-v0.1.2.spkg` package. -In this example, you only want to import the `eth.transaction.v1.Transactions` object. - -The Protobuf object is generated in AssemblyScript, so you can import it in the subgraph code. - -- Generate the subgraph schema: - -```bash -graph codegen -``` - -### Inspect the Code - -- The `subgraph.yaml` file defines the Substreams triggers as a data source. -The subgraph will be deploy on Ethereum Mainnet (`mainnet`). - -```yaml -specVersion: 1.0.0 -indexerHints: - prune: auto -schema: - file: ./schema.graphql -dataSources: - - kind: substreams - name: Transaction - network: mainnet # Ethereum mainnet - source: - startBlock: 17239000 - package: - moduleName: map_filter_transactions # Module name - file: ethereum-explorer-v0.1.2.spkg # Package - mapping: - apiVersion: 0.0.7 - kind: substreams/graph-entities - file: ./src/mapping.ts # Path of the mapping file. - handler: handleTransactions # Name of the handler function of the trigger -``` - -- The `src/mapping.ts` contains the handler of the trigger, `handleTransactions`: - -```ts -import { log } from "@graphprotocol/graph-ts"; -import * as assembly from "./pb/assembly"; // 1. -import { Transaction } from "../generated/schema"; // 2. - -export function handleTransactions(bytes: Uint8Array): void { - let transactions = assembly.eth.transaction.v1.Transactions.decode(bytes.buffer).transactions; - if (transactions.length == 0) { - log.info("No transactions found", []); - return; - } - - for (let i = 0; i < transactions.length; i++) { - let transaction = transactions[i]; - - let entity = new Transaction(transaction.hash); - entity.from = transaction.from; - entity.to = transaction.to; - entity.save(); - } -} -``` -1. Import the generated Substreams Protobuf. -2. Import the generated GraphQL schema. -3. Decode the Substreams Protobuf. -4. Create and save the subgraph entity. - -### Build and Deploy the Subgraph - -To test the application, you can deploy the subgraph to [The Graph Studio](https://thegraph.com/studio/). You must create an account and authentication your computer first. The [official documentation](https://thegraph.com/docs/en/deploying/subgraph-studio/) covers the steps needed to deploy a subgraph to the Studio. - -- Build the subgraph: - -```bash -graph build -``` - -- Deploy the subgraph: - -```bash -graph deploy -``` - -Now, you can access and query the subgraph in the Studio. +You can find all the information related to triggers in [The Graph documentation](https://thegraph.com/docs/en/sps/triggers/). \ No newline at end of file diff --git a/docs/new/how-to-guides/vara.md b/docs/new/how-to-guides/vara.md new file mode 100644 index 00000000..20a36eb0 --- /dev/null +++ b/docs/new/how-to-guides/vara.md @@ -0,0 +1,56 @@ +In this guide, you'll learn how to initialize a Vara-based Substreams project. You’ll learn how to set up a simple project to extract raw data or filter events from a smart contract. + +## Prerequisites + +- Docker and VS Code installed and up-to-date. +- Visit the [Getting Started Guide](https://github.com/streamingfast/substreams-starter) to initialize your development environment. + +## Step 1: Initialize Your Vara Substreams Project + +1. Open your development environment and run the following command to initialize your project: + + ```bash + substreams init + ``` + +2. You will be given the option to choose between two Vara project options. Select the one that best fits your requirements: + - **vara-minimal**: Creates a simple Substreams that extracts raw data from the block and generates Rust code. + - **vara-extrinsics**: Creates a Substreams that extracts Vara transactions filtered specific extrinsics using the cached [Vara Foundational Module](https://substreams.dev/streamingfast/vara-common/v0.1.6). + +## Step 2: Visualize the Data + +1. Create your account [here](https://thegraph.market/) to generate an authentification token (JWT) and pass it as input to: + + ```bash + substreams auth + ``` + +2. Run the following command to visualize and itterate on your filtered data model: + + ```bash + substreams gui + ```` + +## Step 3: Customize your Project + +After initialization, you can: + +- Modify your Substreams manifest to include additional filters or configurations. +- Implement custom processing logic in Rust based on the filtered data retrieved by the foundational module. + +## Additional Resources + +You may find these additional resources helpful for developing your first EVM application. + +### Development Container Reference + +The [Development Container Reference](../references/devcontainer-ref.md) helps you navigate the complete container and its common errors. + +### GUI Reference + +The [GUI reference](../references/gui.md) lets you explore all the tools available in the Substreams GUI. + +### Manifests Reference + +The [Manifests Reference](../references/manifests.md) helps you with editing the `substreams.yaml`. +