Incentives: Add a way to lookup the blocks proposed by an address

jasonpaulos commented 2 months ago

Problem

With the upcoming release of participation incentives, users will want to track the incentives that an individual account accrues over time.

Incentives are not transferred by transactions, so existing transaction lookup endpoints can't solve this problem. Instead this information is present in the block header.

Solution

A solution is to have a new endpoint which takes an account address as an argument and returns information about all blocks proposed by that address, likely in a paginated list with the most recent blocks first.

As for the information about individual blocks being returned, the following are both possibilities:

Return the entire block header
Return only the relevant fields related to incentives as a subset of information about the block header

Depending on the expected use cases, one of these may make more sense than the other.

Dependencies

An index on block proposers would help make the suggested endpoint more efficient.

Urgency

Good to think about before incentives are live on mainnet

urtho commented 2 weeks ago

Nodely will have a PR with this soon. The implementation is live on FNet.

playground: https://nodely.io/swagger/index.html?url=/swagger/api/fnet/indexer.oas3.yml#/search/searchForBlocks

More here: https://github.com/AlgoNode/indexer-api-cdb/issues/9

emg110 commented 2 weeks ago

What a powerhouse Nodely is! Wow! Is it possible that using an argument the endpoint returns one of full block header or incentive-related fields? I mean for both return possibilities to be present and differ using an argument like "full_header"? That will be awesome @urtho

urtho commented 2 weeks ago

Do you think there are use cases where full_header would be too much and some dApp would benefit from smaller response ? What would be the bare bones fields (except for the incentives related) ?

At the moment the block header response is :

{
      "bonus": 10000000,
      "genesis-hash": "kUt08LxeVAAGHnh4JoAoAMM9ql/hBwSoiFtlnKNeOxA=",
      "genesis-id": "fnet-v1",
      "previous-block-hash": "MxEZcDvDrppd8QYrWzJgNnr4ERCaE9sxtJpluTQvzIk=",
      "proposer": "FNET43EQJGPZNQPDWZSWEPAGTVFBA5WKUB64BPWWWLD4MCJUCMQDSONATA",
      "rewards": {
        "fee-sink": "FEESINK7OJKODDB5ZB4W2SRYPUSTOTK65UDCUYZ5DB4BW3VOHDHGO6JUNE",
        "rewards-calculation-round": 500000,
        "rewards-level": 0,
        "rewards-pool": "7777777777777777777777777777777777777777777777777774MSJUVU",
        "rewards-rate": 1,
        "rewards-residue": 6
      },
      "round": 6,
      "seed": "Ssp16N2gKGL44LL7yGAtS6/6wbTUy6kMYVt4dff/uiE=",
      "state-proof-tracking": [
        {
          "next-round": 512,
          "online-total-weight": 0,
          "type": 0
        }
      ],
      "timestamp": 1724938350,
      "transactions-root": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=",
      "transactions-root-sha256": "HQn2+iMjWIFRTaDl+PeJdn5rKOch+otqMK5/Gao+puc=",
      "txn-counter": 1005,
      "upgrade-state": {
        "current-protocol": "fnet1",
        "next-protocol-approvals": 0,
        "next-protocol-switch-on": 0,
        "next-protocol-vote-before": 0
      },
      "upgrade-vote": {
        "upgrade-approve": false,
        "upgrade-delay": 0
      }
    }

I guess the with header_full=false the we should have at least:

{
      "bonus": 10000000,
      "genesis-hash": "kUt08LxeVAAGHnh4JoAoAMM9ql/hBwSoiFtlnKNeOxA=",
      "genesis-id": "fnet-v1",
      "proposer": "FNET43EQJGPZNQPDWZSWEPAGTVFBA5WKUB64BPWWWLD4MCJUCMQDSONATA",
      [... other incentives related...]
      "round": 6,
      "timestamp": 1724938350,
      "txn-counter": 1005
    }

emg110 commented 2 weeks ago

If the implementation and development resource cost on having such a _full header param is relatively affordable, I would say yes, it makes a difference and would be a very practical option for devs to use.

algorand / indexer