TAP Migration Guide

Reading time: 5 min

Learn about The Graph’s new payment system, Timeline Aggregation Protocol, TAP. This system provides fast, efficient microtransactions with minimized trust.

TAP 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 on-chain 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.

TAP allows a sender to make multiple payments to a receiver, TAP 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.

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

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.

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

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

The required software version can be found here.

1. Indexer Agent

   • Follow the same process.
   • Give the new argument --tap-subgraph-endpoint to activate the new TAP codepaths and enable redeeming of TAP 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:

# You will have to change *all* the values below to match your setup.
#
# Some of the config below are global graph network values, which you can find here:
# <https://github.com/graphprotocol/indexer/tree/main/docs/networks>
#
# Pro tip: if you need to load some values from the environment into this config, you
# can overwrite with environment variables. For example, the following can be replaced
# by [PREFIX]_DATABASE_POSTGRESURL, where PREFIX can be `INDEXER_SERVICE` or `TAP_AGENT`:
#
# [database]
# postgres_url = "postgresql://indexer:${POSTGRES_PASSWORD}@postgres:5432/indexer_components_0"

[indexer]
indexer_address = "0x1111111111111111111111111111111111111111"
operator_mnemonic = "celery smart tip orange scare van steel radio dragon joy alarm crane"

[database]
# The URL of the Postgres database used for the indexer components. The same database
# that is used by the `indexer-agent`. It is expected that `indexer-agent` will create
# the necessary tables.
postgres_url = "postgres://postgres@postgres:5432/postgres"

[graph_node]
# URL to your graph-node's query endpoint
query_url = "<http://graph-node:8000>"
# URL to your graph-node's status endpoint
status_url = "<http://graph-node:8000/graphql>"

[subgraphs.network]
# Query URL for the Graph Network subgraph.
query_url = "<http://example.com/network-subgraph>"
# Optional, deployment to look for in the local `graph-node`, if locally indexed.
# Locally indexing the subgraph is recommended.
# NOTE: Use `query_url` or `deployment_id` only
deployment_id = "Qmaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"

[subgraphs.escrow]
# Query URL for the Escrow subgraph.
query_url = "<http://example.com/network-subgraph>"
# Optional, deployment to look for in the local `graph-node`, if locally indexed.
# Locally indexing the subgraph is recommended.
# NOTE: Use `query_url` or `deployment_id` only
deployment_id = "Qmaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"

[blockchain]
# The chain ID of the network that the graph network is running on
chain_id = 1337
# Contract address of TAP's receipt aggregate voucher (RAV) verifier.
receipts_verifier_address = "0x2222222222222222222222222222222222222222"

########################################
# Specific configurations to tap-agent #
########################################
[tap]
# This is the amount of fees you are willing to risk at any given time. For ex.
# if the sender stops supplying RAVs for long enough and the fees exceed this
# amount, the indexer-service will stop accepting queries from the sender
# until the fees are aggregated.
# NOTE: Use strings for decimal values to prevent rounding errors
# e.g:
# max_amount_willing_to_lose_grt = "0.1"
max_amount_willing_to_lose_grt = 20

[tap.sender_aggregator_endpoints]
# Key-Value of all senders and their aggregator endpoints
# This one below is for the E&N testnet gateway for example.
0xDDE4cfFd3D9052A9cb618fC05a1Cd02be1f2F467 = "https://tap-aggregator.network.thegraph.com"

Notes:

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

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

You can download Grafana Dashboard and import.

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