It would be awesome if the lat/lon of all 16 consensus group hotspots were included in the API response for a txn of type consensus_group_v1. I'm trying to plot them all, but I think right now the only way to do it is to make 16 separate requests of hotspot IDs to get their lat/lons

Right now that transaction type returns an array members of each hotspot's address in string format. It would be awesome if each element in members had at least:

• latitude
• longitude
• hotspot address

instead of just the hotspot address string

Now that score is no longer used for PoC or for CG selection, remove the PoC based score from the API.

Like with hotspots: Remove the requirement that all accounts are retrieved before the next invalidating block arrives. While it enables a consistent snapshot of all accounts at the reported height, most client interactions can't complete the paged account list fast enough.

Decoupling like with hotspots means reporting the block height for each account as it is returned which allows clients to determine what height the account data is valid at. The returned account list will have a mix of block heights.

• Update API docs to match

It would be useful to have access to the unix timestamp of the block when a hotspot was added to the chain. We currently expose block_added: https://api.helium.io/v1/hotspots

After postings these transactions stake_validator, transfer_stake and unstake_validator:

https://testnet-api.helium.wtf/v1/transactions/2KAbUr3VZx72gHkW1txXrY6ato_zwNpO-9nzmHtRgL0 stake_validator_v1
https://testnet-api.helium.wtf/v1/transactions/z0vG68QWOPBJEMdCtZrPrAQuHiRBCyTTOMHtQ2ZWVAQ transfer_validator_stake_v1
https://testnet-api.helium.wtf/v1/transactions/ymIOPfjZKPzmcuwjTx-Bbrb6n-azbD3b5rQ9krNv1MM unstake_validator_v1

However we found that these transactions can't be fetched using address activity https://testnet-api.helium.wtf/v1/accounts/1bRhA87goDzWGMoV17syZoK9nhtE8EjngRJ5LqE6JSsukj5Mh2M/activity?cursor=eyJibG9jayI6MTEwMCwiYW5jaG9yX2Jsb2NrIjoxMTAwfQ

Need apis for validator metrics for both testnet and mainnet:

• provide total # of validator counts broken down by stake status (staked, cooldown, in consensus, online, offline)
• amount of HNT staked (individual nodes and total)
• HNT paid out to validator (individual nodes and total)
• consensus group members and size
• state of validator node (online, offline, in consensus, cooldown)
• date of initial stake
• amount of HNT in cooldown
• total staked vs total supply vs total circulating supply

We'd leverage mainnet apis to provide a visuals on a validator section of explorer.

I'm not sure what the correct default value should be, but there are some cases where a hotspot doesn't have a reward_scale value. It's probably better if the field is always there with a default value than if it sometimes doesn't show up. Either 0 or 1 would probably make sense as a default value, or possibly null?

The two cases I've noticed where a hotspot doesn't have the field:

• when a hotspot was just added and has started syncing, there is a brief time period where the API won't return a reward_scale field for that hotspot
• I'm not sure what causes it, but Exotic Orange Chicken seems to not have a reward scale value, even though it appears to be online and syncing: https://explorer.helium.com/hotspots/112n3pxKf1X8ZEuag81LuVust76ciGSgMjB5roxXJ8P7pN3C5GaY

/accounts/14cWRnJk7oZDeRSfo9yS3jpWfQmqZxNEzxQoygkoPBixLVSQaTg/rewards?min_time=2020-06-05T00:00:00.000000&max_time=2020-06-16T07:00:00.000000 returns one page of 100 results and second page with 2 results where the first result from the second page duplicates the last result from the first page. Modifying the end date range to 2020-06-16T00:00:00.000000 returns 1 page with 1 result and second page with 99 results and no duplicates.

This was inspired by https://api.helium.io/v1/hotspots/:addr/rewards/sum?min_time=:min&max_time=:max
sum doesn't really make sense for Oracle prices. I'm imagining something like
I'm imagining something like: https://api.helium.io/v1/oracle/prices/stats?min_time=:min&max_time=:max
The key stats to get would be min, max, avg. Maybe median and std dev too?

It would be really handy to be able to get a count of a given transaction type for a given account.

I don't know if this would be the right way to do it, but I'm picturing something like:

https://api.helium.io/v1/accounts/:address/activity/add_gateway_v1/sum
https://api.helium.io/v1/accounts/:address/activity/assert_location_v1/sum

My specific request is so I can make a "maker dashboard" which shows how many hotspots each official maker account address has paid for (add_gateway_v1 & assert_location_v1 transactions):

And I'm thinking this could also be useful for other things, e.g. showing a visual breakdown of a hotspot/account's transaction types.

Right now that screenshot ^ is achieved by using the filtering in helium-js to pull activity filtered by transaction type, then displaying the length of the array.

Because I don't need any of the data in the transactions themselves, it feels wasteful to pull them all when just displaying the count.

Not sure if it'd be doable or harder, but could also work nicely to have a generic route something like:
https://api.helium.io/v1/accounts/:address/activity/sum that would return an object with each transaction type and a number of how many transactions of that type there were.

We'd like to support text search for hotspots by fields like animal name and geography (city, state, country). We use algolia for this currently, but it's getting $$$. Because the contents of the columns being searched is limited, using postgres search shouldn't be terrible performance wise.

As a precursor to #136 so we can give downstream consumers time to adjust, set all scores to 1.0 on API responses.

We'd like to be able to graph DC usage over time. Maybe this could be modeled after the rewards/stats endpoint format?

We'd like to start showing HNT emissions on the explorer page to provide insight into individual earnings (i.e. network emissions down = hotspot earnings down) and whether the network keeps pace with the 5MM per month emission schedule.

Time bucket this endpoint as we do with other earnings-related endpoints.

In order to graph oracle price over time, we need block time in addition to block height on endpoints like https://api.helium.io/v1/oracle/prices/

Having a problem with hotspot rewards API calls where the rewards for a longer period doesn't equal the sum of the rewards of shorter periods within it. For example:
The API returns rewards for 10/1 to 10/27: 33108296896
The API returns rewards for 10/27 to 10/28: 849902422
sum of these: 33958199318
but the API returns rewards for 10/01 to 10/28: 34036803710, or 78604392 greater than the sum of the individual periods.

[https://api.helium.io/v1/hotspots/1162fRqWoUGd8DUexz92d3ZsVaZre4wjXFTWEmLjK4WnXkmZMss/rewards/sum/?min_time=2020-10-01T00:00:00&max_time=2020-10-27T00:00:00]
{"data":{"sum":"33108296896","min_time":"2020-10-01T00:00:00Z","max_time":"2020-10-27T00:00:00Z"}}

[https://api.helium.io/v1/hotspots/1162fRqWoUGd8DUexz92d3ZsVaZre4wjXFTWEmLjK4WnXkmZMss/rewards/sum/?min_time=2020-10-27T00:00:00&max_time=2020-10-28T00:00:00]
{"data":{"sum":"849902422","min_time":"2020-10-27T00:00:00Z","max_time":"2020-10-28T00:00:00Z"}}

[https://api.helium.io/v1/hotspots/1162fRqWoUGd8DUexz92d3ZsVaZre4wjXFTWEmLjK4WnXkmZMss/rewards/sum/?min_time=2020-10-01T00:00:00&max_time=2020-10-28T00:00:00]
{"data":{"sum":"34036803710","min_time":"2020-10-01T00:00:00Z","max_time":"2020-10-28T00:00:00Z"}}

The current route shows how many witnesses a Hotspot has, but does not necessarily separate valid witnesses from invalid ones.

We know that only valid witnesses contribute to earnings, so we should only relevant data to the user.

For each wallet address, summarize how much HNT a wallet address has received (via mining, payments) and how much HNT was debited (via burn, payments, asserts, transaction fees).

We will need a daily value, weekly value, and monthly value.

Here's the UI we want to create:

Green is a credit of HNT, blue is a debit of HNT. you'll also see the top left of the chart showing the exact HNT value.

cc @allenan

It would be helpful for users of the API and app developers to see a reason for is_valid = false. Potentially add a field or change is_valid to be a tuple, although I'm not sure if the latter makes sense.

cc: @cokes518

Endpoint: https://api.helium.io/v1/vars

Returns hip17_res_4: "MSwyNTAsODAw" hip17_res_5: "MSwxMDAsNDAw" hip17_res_6: "MSwyNSwxMDA" hip17_res_7: "Miw1LDIw" hip17_res_8: "MiwxLDQ" hip17_res_9: "MiwxLDI" hip17_res_10: "MiwxLDE" for all res_x chain variables

Sometimes it could be useful to get transactions from beginning to end instead of the default most recent to beginning.

For example, I'm trying to find when a hotspot was first added, I have to go to hotspot activity and go through transactions until I get to the beginning of time. This could be part of whats returned from the hotspot list endpoint as well (/hotspots) but it doesn't appear to be that way.

Another example, if I'm trying to rederive a balance at a certain date, I'll want to look at the account transactions in reverse order.

We need to be able to query https://developer.helium.com/blockchain/api/api-hotspots#hotspot-challenges by time periods to create charts for the mobile app.

The idea is to show challenge pass rate per day for last 7, 14, 30 days and per hour for the 24 hours.

I know we have also talked about this extensively but adding it here for discussion. Does it make sense to add a successful attribute to challenges on the backend?

UI:

Summary

It would be helpful to be able to find PoC Challenge transactions on the basis of an Onion Key Hash alone. The ETL schema supposedly already has the data to serve such requests. An API endpoint for searching transactions this way would be great.

Background / Need

I am researching possible witnessing failures in the p2p network due to a possible DDOS ("The Thundering Herd") problem wherein well-heard hotspots induce so much traffic towards the challenger in a PoC that they crash the challenger, preventing the challenger from recording witness receipts, and even preventing the challenger from checking back in within the timeout interval. This almost effectively erases the fact that the challenge even happened at all!

The one piece of data that can help diagnose if this is an issue is the Onion Key Hash, which can be calculated by examining the payload of a Lora packet sent in response to the challenge.

We want to be able to answer questions like "what was the total HNT earned by all hotspots on the network between two timestamps?" and "what was the median hotspot earning between those timestamps?". We also want to be able to separate out earnings by "buckets" between those timestamps. So for a given hotspot, we could chart a bar graph for each day's earnings within the past week. Ideally the design of this API will be flexible enough to serve different use cases.

I'm not sure how feasible it is, but it would be great if transactions of type assert_location_v1 could return the same "geocode" info as /hotspots/:address returns:

so that I could use the city/state/country/street names in things like meta tags or UIs in the frontend without having to make another request.

Come to think of it, it would be great if other transaction types returned the same thing, e.g. poc_receipts_v1 and poc_request_v1 — could be useful to display city / street names when showing challenges and their participants in the app or in Explorer

To better reflect the most recent witnesses of a hotspot I would propose that witness lists not clear once every two weeks, but that an individual witness will remain visible for 7 days (~11,340) blocks after it was last witnessed. Numerous people are confused by having all witnesses drop at once, and this display that a hotspot has no witnesses is not accurate, especially even if successfully beaconed with multiple witnesses a short time before it's list clears.

I'm not sure exactly where this list is maintained, in explorer I imagine, and when it usually runs the process to delete the list, but as long as there is a way to see each witness's most recent time stamp (block#) of when it witnessed a hotspot, it could be set to delete after 11,340 or some other number of blocks. Not sure how often this would need to run to check the lists, at least once a day I'd think, or if simply every time a hotspot is c hallenged.

It would be really helpful if with API call, user is able to get challenges in certain time period, currently hotspots/:address/challenges route does not allow to filter result based on time period.

Can optional query parameter min_time and max_time be added in hotspot-challenges route similar to what is present in hotspots/:address/rewards ?

With the number of hotspots on the network growing at a fast clip, it's getting too expensive to fetch and store all hotspots in memory. And Algolia's geospatial search while fast, is pricey, only gives us a limited number of hotspots within a radius, and isn't integrated with helium-js to return Hotspot objects. Therefore it'd be great to allow our existing hotspots route to take a bounding box which would be the currently viewed map area, and return a cursor-paginated list of hotspots within that bounding box.

I'd propose a bounding box be defined as the SW + NE coordinates to be consistent with Mapbox. If indexes are added to the lat/lng columns, then it should be relatively efficient to do a BETWEEN query:

WHERE lat BETWEEN :minLat AND :maxLat AND lng BETWEEN :minLng AND :maxLng

We can choose to address the wrapping issue at 180 degrees longitude if we want, or just do the above as a first pass at a solution, given that we don't expect m/any queries to be made over the pacific in that geography.

Currently, Account-rewards-sum API (https://api.helium.io//v1/hotspots/:address/rewards/sum) only returns account earnings for given timeframe. If API could be modified to get rewards(sum) for all hotspot in an account broken at hotspot level along with Account earnings for given timeframe.

This would eliminate a need to make multiple API call at hotspot level, if account level API can breakdown hotspot earnings.

Current output:
{
"data": {
"max_time": "2020-08-29T00:00:00Z",
"min_time": "2020-08-27T00:00:00Z",
"sum": "10000"
}
}

Suggested future output:

{
"data": {
"max_time": "2020-08-29T00:00:00Z",
"min_time": "2020-08-27T00:00:00Z",
"sum": "10000"
"hotpsot": [
{"address": hotspot_address1,
"name": "name-of-hotspot1",
"sum": "3000"
},
{"address": hotspot_address2,
"name": "name-of-hotspot2",
"sum": "7000"
}
]
}
}

I would expect the transfer_hotspot_v1 transactions to show up in account activity of the buyer and seller which is currently not happening.

For example: https://api.helium.io/v1/transactions/v16UIvXaIS2kLiXKmc_Gf6WqSezCwPs9azP6C5oKN3w does not appear in the buyer or seller account/:address/activity api.

Also I would expect the to be able to filter account activity by the transfer_hotspot_v1 transaction type.

The API should parse binary chain variables and present it in a more legible way for clients.

https://api.helium.io/v1/transactions/vnEqwbKtFfFxXgYI_9L5Th0LRVkpJlsX-sQzZTh2VwY

{
  "data": {
    "version_predicate": 0,
    "vars": {
      "witness_redundancy": 4,
      "poc_witnesses_percent": 0.2124,
      "poc_reward_decay_rate": 0.8,
      "poc_path_limit": 1,
      "poc_challengees_percent": 0.0531,
      "hip17_res_9": "2,1,2",
      "hip17_res_8": "2,1,4",
      "hip17_res_7": "2,5,20",
      "hip17_res_6": "1,25,100",
      "hip17_res_5": "1,100,400",
      "hip17_res_4": "1,250,800",
      "hip17_res_3": "2,100000,100000",
      "hip17_res_2": "2,100000,100000",
      "hip17_res_12": "2,100000,100000",
      "hip17_res_11": "2,100000,100000",
      "hip17_res_10": "2,1,1",
      "hip17_res_1": "2,100000,100000",
      "hip17_res_0": "2,100000,100000",
      "hip17_interactivity_blocks": 3600,
      "density_tgt_res": 4
    },
    "unsets": [],
    "type": "vars_v1",
    "time": 1608142069,
    "proof": "MEUCIFSiomdFyceMis_PyYCExxDzn26Pl3fnbuagWHgG5ZkqAiEAyAKH6Z3eQPk8KbOZZc9S7sRrTeW1raloE4NyIFXPagg",
    "nonce": 50,
    "master_key": null,
    "key_proof": "",
    "height": 635109,
    "hash": "vnEqwbKtFfFxXgYI_9L5Th0LRVkpJlsX-sQzZTh2VwY",
    "cancels": []
  }
}

https://api.helium.io/v1/hotspots/:address/witnesses

This route returns the current witnesses for a hotspot only - we'll need to add max_time and min_time as query params for this screen to work.

In addition to the rewards endpoints for individual hotspots and accounts provided here: #129, we need an additional endpoint that exposes rewards and stats across all hotspots.

I'd imagine the route would be: /v1/hotspots/rewards/stats and would take the same params as the other endpoints with regard to max/min time and bucket.

The one potentially tricky point is that in calculating the stats, the rewards should be considered per hotspot.

For example, if there were 5 hotspots in the entire network that were producing rewards for the week of 11/22, and their earnings for that week were:

• hotspot A: 100 HNT
• hotspot B: 500 HNT
• hotspot C: 300 HNT
• hotspot D: 100 HNT
• hotspot E: 200 HNT

If we requested min_time=2020-11-22 and max_time=2020-11-29 and bucket=week, we'd expect to see:

• total = 1200 HNT
• median = 300 HNT

Note there that the median reward for the week was hotspot C's total earnings for that week as compared to each of the other hotspots' total earnings for that week.

The staked balance is currently subtracted from the balance value on an account. balance will continue to act as an account's liquid balance going forward. In addition, we should expose a staked_balance value

Following up on #179 , for each Hotspot where it is a challengee, tell me how many witnesses were valid and how many were invalid.

To add the block height that is returned from last_poc_challenge under each hotspot record for the endpoint https://api.helium.io/v1/hotspots. This will assist in filtering out non-interactive hotspots in accordance with HIP17 implementation

Need to make sure HNT circulating supply includes combination of both balance (liquid), and staked balance so explorer and third parties (e.g., CMC) are pulling correct total HNT circulation numbers.

For validator-related explorer items for mainnet need the following data:

• of active validators

• amount of HNT staked
• total HNT paid out to validators
• consensus group size
• total staked vs total supply vs total circulating supply

For each hotspot, bucketed over time, tell me how many beacons this Hotspot was a challengee.

This should unblock the app team from launch.

Eventually we'll follow this up with whether the Beacon had witnesses and valid witnesses, and the full monty: challenge pass/fail rate.

Per #171 the reward_scale is visible for the hotspot. The final reward_scale is the result of the product of all it's higher-resolutions scales. This piece of business logic is complicated as neighbouring hexes density_target also needs to be taken into account.

For more transparency it would be helpful if the Location-API could accept any h3 resolution hex which is parenting a hotspot as input, and return the scale (clipped/unclipped) as response.

• ability to track unstaking when it happens
• track the amount of HNT in unbounding period

We'd look to potentially provide a graph showing how much HNT is leaving locked up system.

This URL is giving a 503: https://api.helium.io/v1/hotspots/112L7A2Xpkh7fjKjuaTfq3WgEn9nnAXg2M7BTWsR9dYvn4eopguz/activity?cursor=eyJ0eXBlcyI6InJld2FyZHNfdjEiLCJibG9jayI6NjE2NDAwLCJhbmNob3JfYmxvY2siOjYxNjQwMH0

And making this page not work: https://explorer.helium.com/hotspots/112L7A2Xpkh7fjKjuaTfq3WgEn9nnAXg2M7BTWsR9dYvn4eopguz

Here's that hotspot in Sitebot in case it's helpful for debugging: https://www.sitebot.com/helium/hotspot/stable-pear-pangolin/

Dependency on miner issue:

helium/miner#683

Requires: helium/blockchain-etl#118

We'd like to know the total amount of DC generated over a period of time as well as how much HNT was burned to generate those data credits.

It should be a daily, weekly, monthly, and an all time summary of DC generated and HNT burned.

I've played around with the current v1 API and hit quite a few roadblocks that make developing an app quite cumbersome because it requires a lot of network requests and heavy client-side processing to get the data you want

TL;DR: An API should be designed with implementation in mind, not to deliver a big dump of data that can then be parsed on the client.

I'm a fan of designing an API so that it only delivers the minimum data needed for the current request. I don't think the hotspots API makes much sense for any application other than one that would literally display every hotspot's stats on the same page. It would make more sense to me to just have the hotspots API deliver name and address, ideally as a map (I know y'all are switching to use algolia for search, but if a community developer wanted a simple search bar, a map of hotspot names should be fine). Then, you can use the address to request more information about a given hotspot.

Same with the blocks API. There doesn't seem to be a need to have an endpoint that delivers all blocks with all block data.

It also depends what are your goals for these endpoints? Are they meant to just power explorer or are there plans to have an SDK that makes it easy for the community to build out apps for their own needs? If the latter, it should be designed in a way where the patterns are easy to understand and be able to "drill down" to get more refined data.

For example, say I want to find the last time a hotspot's witness witnessed the hotspot (say I had a hotspot page that showed its witnesses and next to each there is a "View Last Witness" button). Currently, I would need to call /hotspots/:address/challenges, loop through all of the challenges, and within each challenge, loop through all of the witnesses and keep doing so until I find the witness address I'm looking for. But ideally, all of that work should be done on the server that delivers the response. I should be able to call /hotspots/:address/witnesses/:address/challenges/offset/1 and be given the challenge in which this witness was last involved. If I change 1 to 5, it increases the offset and gives me the last 5. This allows the developer to use the Helium SDK/API to get specific data without heavy client-side processing or making multiple network requests.

Would be awesome to be able to get geo details for a given h3 index for example at /locations/:h3index, like in the response for a hotspot:

geocode:
  cityId: "c2FuIGZyYW5jaXNjb2NhbGlmb3JuaWF1bml0ZWQgc3RhdGVz"
  longCity: "San Francisco"
  longCountry: "United States"
  longState: "California"
  longStreet: "Spear Street"
  shortCity: "SF"
  shortCountry: "US"
  shortState: "CA"
  shortStreet: "Spear St"

This came up for displaying nicer city/state/country info for the assert location transaction (helium/explorer#136), and I'm sure could be used in other places as well

It would be useful to have the distinct counts of cities and countries available in the stats endpoint

I'm not sure how hard or feasible this would be, but it would be really useful if we could get the rewards sent back based on a timezone offset we pass into the request. And if one isn't specified it could return in UTC like it does now.

I think this would make it a lot easier to show users the earnings over certain time periods in a way that easily lines up with how they think about days. E.g. it can be kind of disorienting when Sitebot stops adding rewards to "Today" and it starts counting them for "Tomorrow".

So if we could for example take the user's local timezone offset and pass that as part of the request to get earnings bucketed by day at -8:00 offset, that would be great.

But maybe this wouldn't be feasible to add on the backend, or perhaps there's a client-side way we can do this even given the UTC buckets... I'm not sure. Timezone math is confusing me :)