GraphTally Guide

Learn about The Graph’s new payment system, GraphTally (previously Timeline Aggregation Protocol)⁠. This system provides fast, efficient microtransactions with minimized trust.

Översikt

GraphTally is a drop-in replacement to the Scalar payment system currently in place. It provides the following key features:

• Efficiently handles micropayments.
• Adds a layer of consolidations to onchain transactions and costs.
• Allows Indexers control of receipts and payments, guaranteeing payment for queries.
• It enables decentralized, trustless gateways and improves indexer-service performance for multiple senders.

Specifics

GraphTally allows a sender to make multiple payments to a receiver, Receipts, which aggregates these payments into a single payment, a Receipt Aggregate Voucher, also known as a RAV. This aggregated payment can then be verified on the blockchain, reducing the number of transactions and simplifying the payment process.

For each query, the gateway will send you a signed receipt that is stored on your database. Then, these queries will be aggregated by a tap-agent through a request. Afterwards, you’ll receive a RAV. You can update a RAV by sending it with newer receipts and this will generate a new RAV with an increased value.

RAV Details

• It’s money that is waiting to be sent to the blockchain.

• It will continue to send requests to aggregate and ensure that the total value of non-aggregated receipts does not exceed the amount willing to lose.

• Each RAV can be redeemed once in the contracts, which is why they are sent after the allocation is closed.

Redeeming RAV

As long as you run tap-agent and indexer-agent, everything will be executed automatically. The following provides a detailed breakdown of the process:

1. An Indexer closes allocation.

2. <recently-closed-allocation-buffer> period, tap-agent takes all pending receipts for that specific allocation and requests an aggregation into a RAV, marking it as last.

3. indexer-agent takes all the last RAVS and sends redeem requests to the blockchain, which will update the value of redeem_at.

4. During the <finality-time> period, indexer-agent monitors if the blockchain has any reorganizations that revert the transaction.

   • If it was reverted, the RAV is resent to the blockchain. If it was not reverted, it gets marked as final.

Blockchain Addresses

Contracts

Gateway

Prerequisites

In addition to the typical requirements to run an indexer, you’ll need a tap-escrow-subgraph endpoint to query updates. You can use The Graph Network to query or host yourself on your graph-node.

• Graph TAP Arbitrum Sepolia Subgraph (for The Graph testnet)
• Graph TAP Arbitrum One Subgraph (for The Graph mainnet)

Migration Guide

Software versions

The required software version can be found here⁠.

Steps

1. Indexer Agent

   • Follow the same process⁠.
   • Give the new argument --tap-subgraph-endpoint to activate the new GraphTally codepaths and enable redeeming of RAVs.

2. Indexer Service

   • Fully replace your current configuration with the new Indexer Service rs⁠. It’s recommend that you use the container image⁠.
   • Like the older version, you can scale Indexer Service horizontally easily. It is still stateless.

3. TAP Agent

   • Run one single instance of TAP Agent⁠ at all times. It’s recommend that you use the container image⁠.

4. Configure Indexer Service and TAP Agent

   Configuration is a TOML file shared between indexer-service and tap-agent, supplied with the argument --config /path/to/config.toml.

   Check out the full configuration⁠ and the default values⁠

For minimal configuration, use the following template:

1# You will have to change *all* the values below to match your setup.2#3# Some of the config below are global graph network values, which you can find here:4# <https://github.com/graphprotocol/indexer/tree/main/docs/networks>5#6# Pro tip: if you need to load some values from the environment into this config, you7# can overwrite with environment variables. For example, the following can be replaced8# by [PREFIX]_DATABASE_POSTGRESURL, where PREFIX can be `INDEXER_SERVICE` or `TAP_AGENT`:9#10# [database]11# postgres_url = "postgresql://indexer:${POSTGRES_PASSWORD}@postgres:5432/indexer_components_0"1213[indexer]14indexer_address = "0x1111111111111111111111111111111111111111"15operator_mnemonic = "celery smart tip orange scare van steel radio dragon joy alarm crane"1617[database]18# The URL of the Postgres database used for the indexer components. The same database19# that is used by the `indexer-agent`. It is expected that `indexer-agent` will create20# the necessary tables.21postgres_url = "postgres://postgres@postgres:5432/postgres"2223[graph_node]24# URL to your graph-node's query endpoint25query_url = "<http://graph-node:8000>"26# URL to your graph-node's status endpoint27status_url = "<http://graph-node:8000/graphql>"2829[subgraphs.network]30# Query URL for the Graph Network Subgraph.31query_url = "<http://example.com/network-subgraph>"32# Optional, deployment to look for in the local `graph-node`, if locally indexed.33# Locally indexing the Subgraph is recommended.34# NOTE: Use `query_url` or `deployment_id` only35deployment_id = "Qmaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"3637[subgraphs.escrow]38# Query URL for the Escrow Subgraph.39query_url = "<http://example.com/network-subgraph>"40# Optional, deployment to look for in the local `graph-node`, if locally indexed.41# Locally indexing the Subgraph is recommended.42# NOTE: Use `query_url` or `deployment_id` only43deployment_id = "Qmaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"4445[blockchain]46# The chain ID of the network that the graph network is running on47chain_id = 133748# Contract address of TAP's receipt aggregate voucher (RAV) verifier.49receipts_verifier_address = "0x2222222222222222222222222222222222222222"5051########################################52# Specific configurations to tap-agent #53########################################54[tap]55# This is the amount of fees you are willing to risk at any given time. For ex.56# if the sender stops supplying RAVs for long enough and the fees exceed this57# amount, the indexer-service will stop accepting queries from the sender58# until the fees are aggregated.59# NOTE: Use strings for decimal values to prevent rounding errors60# e.g:61# max_amount_willing_to_lose_grt = "0.1"62max_amount_willing_to_lose_grt = 206364[tap.sender_aggregator_endpoints]65# Key-Value of all senders and their aggregator endpoints66# This one below is for the E&N testnet gateway for example.670xDDE4cfFd3D9052A9cb618fC05a1Cd02be1f2F467 = "https://tap-aggregator.network.thegraph.com"

Noteringar:

• Values for tap.sender_aggregator_endpoints can be found in the gateway section.
• Values for blockchain.receipts_verifier_address must be used accordingly to the Blockchain addresses section using the appropriate chain id.

Log Level

• You can set the log level by using the RUST_LOG environment variable.
• It’s recommended that you set it to RUST_LOG=indexer_tap_agent=debug,info.

Monitoring

Metrics

All components expose the port 7300 to be queried by prometheus.

Grafana Dashboard

You can download Grafana Dashboard⁠ and import.

Launchpad

Currently, there is a WIP version of indexer-rs and tap-agent that can be found here⁠