v0.20.16

Table of Contents

1. Intro
2. Network
3. Introducing the Action Queue
   1. New Allocation Management modes
      1. Manual Mode
      2. Oversight Mode
   2. Batching Options in auto Mode
   3. CLI improvements
   4. Safety improvements
4. Rules
5. Cost model
6. Vouchers and Receipts
7. Configuration
8. Subgraph Deployments Handling
9. Observability & Monitoring
10. Interfacing

Intro

The v0.20.3 mainnet release includes a wide range of new features and a significant overhaul of the internal code structure.

It's the first mainnet release since v0.18.6.

Check out the full changelog for the complete list of changes.

The following packages are part of this release:

• indexer-agent v0.20.13
• indexer-service v0.20.13
• indexer-cli v0.20.13
• indexer-common v0.20.13
• indexer-native v0.20.13

Network

The latest release includes several Network updates:

Thanks to the Epoch Subgraph, indexers can now connect to any protocol network and claim rewards for indexing sugraphs form the new supported networks:

• Gnosis (eip155:100)
• Avalanche (eip155:43114)
• Celo (eip155:42220)
• Arbitrum One (eip155:42161)

Our testnet is also live on Goerli, where the following networks are also available for indexing:

• Goerli (eip155:5)
• Fantom (eip155:250)
• Polygon (eip155:137)
• Optimism (eip155:10)

We are also on L2! Arbitrum-One and Arbitrum-Goerli (testnet) are now live protocol chains.

For more details on the Networking improvements, check out the relevant PRs:

• Integrate Epoch Block Oracle by @hopeyen in #479
• Support connecting to any protocol network by @fordN in #513
• Add support L2 protocol chains (i.e Arbitrum-Goerli and Arbitrum-One) by using EpochSubgraph to fetch block numbers instead of EpochManager by @tilacog in #573
• Add support for Hardhat, Avalanche, Polygon, Celo, & Optimism to chain alias lookups by @fordN in #577
• Add option to allocate on network subgraph by @Theodus in #339
• Allow 0 staked allocations by @hopeyen in #471
• Remove max signal check, towards deprecating max signal by @fordN in #482

Introducing the Action Queue

The Action Queue is a new sub-component responsible for managing a set of Actions (allocate, unallocate, and reallocate) for an Indexer in a predictable and efficient way. Those Actions can be generated both by the Indexer's rules and by direct input, and are sent to a dedicated worker process to be executed.

A new startup parameter, --allocation-management, has been introduced to let Indexers choose betweeen different allocation management modes:

• The auto mode, which is similar to the agent's behavior in the past, continuously monitors the network and uses the indexing rules to determine and execute allocation management actions. Actions are added to the queue with the approved status.
• In oversight mode, the indexer-agent runs its reconciliation loop to make allocation decisions and propose new Actions by adding them to the Action Queue with a status of queued. These actions will then require explicit approval before they will be executed.
• In manual allocation management mode, the agent will not take any allocation management Actions on its own (meaning it doesn't use the Action Queue at all), and indexers can take all allocation management actions manually using the GraphQL or indexer-cli interfaces.

In summary:

Allocation Mode	Propose Actions?	Action initial state
auto	Yes	approved
oversight	Yes	queued
manual	No	(manual mode doesn't use the Action Queue)

New Allocation Management modes

Manual Mode

Indexers can now manage allocations manually via the GraphQL interface and indexer-cli, allowing indexers and external tools to have more granular and direct control over allocation strategy.

This feature allows for direct requests to be sent to create, close, or reallocate allocations, which will send a transaction to the Protocol Contracts and update the indexing rules at the same time. For example: when closing an allocation manually the agent will update existing rules for that deployment to be decisionBasis = offchain so the agent will not attempt to reopen that allocation.

For more, check out the original PRs:

• Manual Allocation Management by @fordN in #403
• Actions queue by @fordN in #419

Oversight Mode

The oversight mode is very similar to the auto mode, with the distinction of not auto-approving the Actions proposed in the reconciliation loop.

Here's a quick summary of how Actions flow through the Action Queue in oversight mode:

1. A user initiates an action through either a manual interaction or via 3rd party tools integrated with the indexer-management server.
2. The action is added to the Action Queue with the queued status.
3. In the meantime, the indexer-agent runs its reconciliation loop to make allocation decisions and propose actions to the Action Queue, also with a status of queued.
4. An approver (a human or automated system) reviews the proposed actions in the Action Queue and approves them for execution by changing their status to approved.
5. The action-queue worker, which runs as a separate process, polls the Action Queue for items with a status of approved and executes them on-chain.
6. The action status is updated to success in the Action Queue, and the process is complete.
   (Actions can also be finalized with failed and canceled status.)

Batching Options in auto Mode

With auto management mode, the agent automatically proposes and approves Actions for the worker to execute. But to give indexers more control over how these Actions are batched in transactions for execution, we've added two optional startup parameters:

• --auto-min-batch-size: Specify a minimum batch size to wait for before singing a transaction with the batched Actions.
• --auto-max-wait-time: Set a maximum time to wait after the first approved Action before executing the batched Actions transaction.

These parameters are particularly useful for indexers who want to save on gas costs by allowing the agent to perform automatic batched transactions, while still having the flexibility to modify actions if needed.

For more, check out the original PR:

• Add auto batch options and conditions by @hopeyen in #431

CLI improvements

New Action query commands are available to inspect and manage the Action Queue using the indexer-cli:

• Action commands:
  • Delete #491, #549
  • Update #551
  • Batch Approve #463
• Actions Query:
  • Ordering Actions #457
  • Display specific fields with --fields option #547

Safety improvements

• Avoid recreating recently failed Actions #506
• Implement a stake feasibility check before executing batched Actions transactions #579

Rules

Indexing rues can now be:

• defined by subgraph ID (rather than deployment ID) #329
• automatically renewed when the allocation expires (this is now the default behavior) #366
• set to not skip allocations when the previous one has been closed with a 0x0 POI (this is now the default behavior) #542

Cost model

After PR #484, indexers will be able to set a global default cost model through the indexer-cli using the command:

$ graph indexer cost set model global [path]/basic.agora

Vouchers and Receipts

Indexers were hitting the limit of Gateway's maximum body size on /collect-receipts endpoint when they had accumulated a large number of receipts for a particular allocation.

To address this issue, the Gateway has implemented support for incremental voucher redemption via the /partial-vouchers and /vouchers endpoints. After #486, the agent collects receipts incrementally for a single voucher, thus, avoiding the maximum
body size limitations.

Also, after #487, receipts with zero fees will be persisted, as they are useful for tests and development environments.

Configuration

indexer-agent and indexer-service can be configured via a file in addition to CLI arguments. #396, #572

We've also added a --network-subgraph-deployment CLI argument indexer-service, enabling users to use a local, synced Network Subgraph instead of an external endpoint. #572

Subgraph Deployments Handling

Subgraph Deployment Management has three key improvements:

• Users can now define indexing rules using the Subgraph ID. #329
• Unsupported subgraphs are now rejected by default. However, users can bypass this default behavior by using a specific CLI flag. #362

Observability & Monitoring

Observability and Monitoring have been improved with the following:

• A new /subgraphs/health/:deployment route for checking the health of a subgraph deployment. #348
• New Prometheus live metrics including:
  • Operator ETH balance. #354
  • Query fee metrics. #597
• Detailed query logs. #428

Interfacing

Those indexer-service endpoints are now rate-limited: #336

• /cost - 5 req/s
• /operator - 5 req/s
• /network - 50 req/s (used frequently by indexer components)
• /status - 50 req/s (used frequently by the decentralized Explorer UI application)

In addition, the configured JSON RPC provider is now used for resolving protocol network blocks instead of the Graph Node, lifting the requirement of indexing subgraphs for the protocol chain. #591