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.

Overview

Link to this section

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.

RAV Details

Link to this section
  • 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

Link to this section

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

Link to this section
ContractArbitrum Sepolia (421614)Arbitrum Mainnet (42161)
TAP Verifier0xfC24cE7a4428A6B89B52645243662A02BA734ECF0x33f9E93266ce0E108fc85DdE2f71dab555A0F05a
AllocationIDTracker0xAaC28a10d707bbc6e02029f1bfDAEB5084b2aD110x5B2F33d7Ca6Ec88f5586f2528f58c20843D9FE7c
Escrow0x1e4dC4f9F95E102635D8F7ED71c5CdbFa20e2d020x8f477709eF277d4A880801D01A140a9CF88bA0d3
ComponentEdge and Node Mainnet (Arbitrum Sepolia)Edge and Node Testnet (Aribtrum Mainnet)
Sender0xDDE4cfFd3D9052A9cb618fC05a1Cd02be1f2F4670xC3dDf37906724732FfD748057FEBe23379b0710D
Signers0xfF4B7A5EfD00Ff2EC3518D4F250A27e4c29A22110xFb142dE83E261e43a81e9ACEADd1c66A0DB121FE
Aggregatorhttps://tap-aggregator.network.thegraph.comhttps://tap-aggregator.testnet.thegraph.com

Requirements

Link to this section

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.

Note: indexer-agent does not currently handle the indexing of this subgraph like it does for the network subgraph deployement. As a result, you have to index it manually.

Migration Guide

Link to this section

Software versions

Link to this section
ComponentVersionImage Link
indexer-servicev1.0.0-rc.6indexer-service
indexer-agentPR #995indexer-agent
tap-agentv1.0.0-rc.6tap-agent
  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

  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.

Grafana Dashboard

Link to this section

You can download Grafana Dashboard and import.

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

Edit page

Previous
Operating Graph Node
Next
Chain Integration Process Overview
Edit page