SmesherService.SmeshingStatus API Endpoint Proposal

[brusherru]

Rationale

We want to make clear to Smeshers what is going on at every moment in the time:

• does his Node smeshes properly
• does he eligible for rewards in the current/next epoch
• if not — then why

Let's refresh our memory on how it works, assign some statuses to each "step" and clarify which additional data we may require.

1. Not smeshing yet
   Status: Not smeshing
2. Smesher set up smeshing: define PoS directory, data units amount, coinbase. The node starts creating PoS data.
   Status: Generating PoS data
3. When it is done, the Node waits for PoET
   Status: Waiting for PoET challenge
   Extra: estimated time / layer
4. Node generates proof-of-space
   Status: Generating Proof-of-Space
   Extra: time estimation
5. Node publishes ATX and starts waiting for the next epoch
   Status: Waiting for the next epoch
   Extra: time estimation
6. If there were no errors and timing issues — Smesher is eligible for rewards in the started epoch
   Status: Smeshing on epoch 23 (current)
7. If Smesher is eligible for rewards, then he will start receiving them within this epoch
   Status: Smeshing on epoch 23 (current)
8. Meanwhile, Node starts waiting for PoET challenge for the next epoch (goto 3)

Here is a good illustration by @noamnelke:

We already had some related discussion, so you can check it out: spacemeshos/smapp#721

Problem

Some of the steps, mentioned above, take a long time.
Some of them may finish with failure, which means that time from the 2nd step to the 6th (getting rewards) may take much more time. So we need to notify Smesher about the current status.

We already have some API endpoints, but they have a narrow scope and do not cover all the steps from the list above:

• SmesherService.IsSmeshing -> bool — true if PoS creation complete and "ready to send ATXs". But actually, if the node does not sync, it is still true. So from my point of view, it seems almost useless (the same as PostSetupStatus === complete). Fix me if I miss something.
• SmesherService.PostSetupStatus — enum (not_started | in_progress | complete | error). Related only to the PoS creating process.

So we need some API endpoints that will provide other statuses. Or, I think it will be much better, one API endpoint that will answer all these questions.

Proposal

Let's make a brand-new SmesherService.SmeshingStatus endpoint, that will return any of the statuses mentioned above with required extra data.
Such a solution will encapsulate some logic on the Node side, like requesting/listening for ATXs, rewards, PoET, etc.
Actually, I've already created one issue for it some time ago: #3222

So I think it might be a nullary endpoint, which returns something like:

SmeshingStatusResponse =
  | { status: 'not_started' }
  | {
       status: 'generating_pos_data' | 'generating_pos_proof' | ...
       estimatedTime: number;
    }
  | ...
  | {
       status: 'waiting_for_poet',
       epoch: number;
       estimatedTime/Layer: number;
    }
  | {
       status: 'smeshing', 
       epoch: number;
    }
  | {
       status: 'not_eligible',
       epoch: uint64;
       reason: string;
    };

Multiple statuses at once

Actually, Smesher can have more than one status at a time, regarding different epochs.

For example:

• Epoch 23: smeshing
• Epoch 24: waiting for PoET

Or even:

• Epoch 23: smeshing finished
• Epoch 24: Not eligible, missed timeframe
• Epoch 25: Waiting for PoET

So probably this endpoint should return a list of SmeshingStatusResponse.
But in this case, we have an open question, which epochs should be on the list. Putting all previous epochs is a bad idea.

Can we implement only streaming API endpoint, but with one requirement: can it send "current status" to the new client on connection?

What's next

Please, share your thoughts about the problem and my proposal.
If you found that such implementation will be complicated / not optimal / etc — tell us about it, please.
If I miss something — feel free to fix me. If you have other ideas — share them.

---

P.S.
We also had a discussion about API for retrieving ATXs. But from my point of view, it is not required for Smapp/Smrepl, in case all this "smeshing status logic" will be encapsulated on the Node side, as proposed above.
However, most likely we will require such an API for Explorer. And I think we should not make Smapp/Smrepl more complicated, and just put a link to explorer where it is needed (aka on Smesher screen).

So I propose to leave API for retrieving ATXs is out of scope, and open another discussion/issue in the context of Explorer.

---

cc: @oriya @lrettig @noamnelke @dshulyak @countvonzero

[oriya]

Thank you @brusherru for the immense clarity of purpose and proposal here.
Yes, originally, this project started as Display Activations
However as we took a deep dive into this, especially with @noamnelke 's guidance we have come up with a pre-genesis requirements which includes updating the smeshing screen, phase 1 (already waiting to be published)
and this next phase which will requires the propose API endpoints - so we can display relevant data for SMAPP users, to increase transparency and usability at Genesis.
I fully agree that we should not make SMAPP/SMREPL more complicated and make drill-downs available in explorer. During this phase - only display the minimum amount of information on SMAPP, which is why we are merely "updating" the Smesher screen right now, as opposed to coming up with an entirely new "rewards" screen ( - we can always do that later with some real experience with the new data-points and usability).

In summery - the most important data for a SMAPPer is:

1. Did I setup correctly ? with Error reporting / suggestion for fix (restart / reconnect)
2. Am I eligible and/or active on the current epoch.
3. Am I eligible for the upcoming epoch and when will it start?
4. What have I already earned by smeshing?
5. Extras: estimated upcoming rewards - always nice and motivating to keep the computer on :)

[noamnelke]

Great summary!

which epochs should be on the list

IMO it should be:

• Current epoch ("active" or why not - e.g. doing initial ramp up and not done yet / missed PoET registration window / etc.)
• Next epoch
• Epoch after next

Past epochs should be specifically query-able, but not returned by default since they're not interesting for the smeshing status screen.

  | {
       status: 'generating_pos_data' | 'generating_pos_proof' | ...
       estimatedTime: number;
    }

I think we should add processedBytes. It's relevant for both of these statuses (bytes generated in the first case and bytes read in the second) and could be useful to show to the user, IMO. It can be presented raw ("Processed 176 GB of 256 GB") or as a percent ("86% completed") or even both. I think that it would be frustrating for me if I was only presented with a time estimate, especially if the estimate changes sometimes (goes up / jumps down / gets stuck). Seeing a monotonously increasing value is more reassuring.

I'm pretty sure all of this information is available to the node, so exposing this API only requires looking up data. However, it might be possible/needed to cache some data to make answering this more efficient - I'll let @dshulyak or @countvonzero answer that. Only exception to this is the estimated PoET time / layer which I don't think the node currently knows, but I guess we can live without it for v1.

[lrettig]

i don't have a way to estimate rewards amount & time if the node is too far behind in terms of data

It's a bit orthogonal to this issue, but I've noticed that a number of blockchain nodes do at least tell you how much data you've synced, and how much remains to be synced. That would be a nice feature to have, and if we have it, it could also be exposed in the API. Here's one example: https://github.com/sigp/lighthouse/blob/79db2d4deb6a47947699d8a4a39347c19ee6e5d6/beacon_node/beacon_chain/src/eth1_chain.rs#L128-L153 (which is rather simplistic as it's just number of blocks from head)

if Smapp miss something (e.g. smesher turned off his PC for a while, or move to another PC, etc) — no chance to restore it.

We don't need a history of smeshing statuses, but I do think it's important to display a history of all earned rewards (for the current coinbase). This should be pretty straightforward as the node has access to do this data, but I'm not sure if it needs to be a different API service/endpoint.

[countvonzero]

It's a bit orthogonal to this issue, but I've noticed that a number of blockchain nodes do at least tell you how much data you've synced, and how much remains to be synced. That would be a nice feature to have, and if we have it, it could also be exposed in the API.

agreed this is a nice-to-have feature. we can assume the data size per epoch is constant and linearly extrapolate the time needed to reach synced state. since the accuracy heavily depend on the network stability/throughput, my only hesitation here is that, as a user, i'd be really pissed if the prediction keeps changing to further future (while forgetting the fact that i didn't keep the node online all the time).

[brusherru]

history of all earned rewards (for the current coinbase)

Yep, already within my current feature branch ;)

[brusherru]

Regarding estimation of Node synchronisation.
I'm pretty sure that for this feature "you're eligible, but sync the node first" is enough.

@lrettig do you think we need such feature for genesis? Then mb we should start another discussion / issue?
I'm pretty sure it will be related to NodeService.
In addition, I can propose another mechanism of estimation based on statistics, but it will be super inaccurate in case if layers data size may significantly differ from each other.
E.G.

• get current timestamp when node started syncing,
• then on each update of current layer calculate average time per layer and multiply it by topLayer-currentLayer

[lrettig]

Definitely not critical for genesis. It's a nice to have. It could be added in the node, in the app, or both. It's straightforward math and there are lots of libraries we can use that will do it for us. Anyway syncing will be very fast when the network is new.

[dshulyak]

ideally queries for activations should use smesher id, as activations are already indexed by it

[brusherru]

Check out this issue please: #2064
This issue seems outdated.
The API endpoint works and filters by coinbase.

[dshulyak]

yes, it is trivial to add more indexes. but it is important to understand that indexes are not free and they will make protocol performance worse, and state larger. we need indexes for smeshers because of the specific protocol queries (i don't recall which ones, but indexes already exist), so if possible it is better to reuse existing index.

[brusherru]

I have no problems calling this API endpoint using Smesher ID instead of coinbase.
So it is up to you. If it will be more performant and we have no blockers — let's make this tweak.