New HIP 44: LoRaWAN Frequency Plan Selection (#298)

* HIP-4x LoRaWAN Frequency Plan Selection

* implement feedback from ivandigiusto

* do PRs against docs

* expand on impact

* Mark HIP-28 as deployed (#296)

* Number and merge HIP 41: Governance by Token Lock V2 (#299)

Co-authored-by: Jamie Wilkinson <jamie@jamiedubs.com>

* New HIP 42 Beacon/Witness Ratio - Witness Reward Limit (#289)

* HIP-42 initial submission
* Better aligned name to proposal
* v2
* Number and merge HIP 42

Co-authored-by: Jamie Wilkinson <jamie@jamiedubs.com>

* Update HIP 41 with latest edits (#304)

* HIP draft: guidelines for software releases (#290)

* Create 0043-update-release-guidelines.md

Add HIP to update software release guidelines

* Update 0043-update-release-guidelines.md

Update explanation to include possibility of a timeframe to implement updates (suggested by @shawaj)

* Change "update" to "software" for clarity

Co-authored-by: Jamie Dubs <jamie@jamiedubs.com>

* HIP draft: Witness Reward Decay (#292)

* initial draft

* Update xxxx-witness-decay.md

* Number as 44

Co-authored-by: Jamie Dubs <jamie@jamiedubs.com>

* Number as HIP 44

Co-authored-by: PaulVMo <paul.moceri@gmail.com>
Co-authored-by: Scott Sigel <scott@commonwealthcrypto.com>
Co-authored-by: Jamie Wilkinson <jamie@jamiedubs.com>
Co-authored-by: Anthony Anderson <fnanderson93@gmail.com>
Co-authored-by: Abhay Kumar <abhay@helium.com>
Co-authored-by: Ganey <ganey@users.noreply.github.com>

0043-witness-reward-decay.md

@@ -0,0 +1,59 @@
+# HIP 44: Witness Reward Decay
+
+* Author(s): [@abhay](https://github.com/abhay)
+* Start Date: 2021-10-07
+* Category: Technical, Economic
+* Original HIP PR: https://github.com/helium/HIP/pull/292
+* Tracking Issue: `#TODO`
+
+## Summary and Motivation
+
+As Proof-of-Coverage continues to be improved, the community has proposed several improvements to continue to incentivize wide rollout of new Helium Hotspot coverage while addressing over-rewarding due to density and or arbitrage. One effective way to address over-rewarding is create soft limits on witness earnings through decaying witness reward units.
+
+## Stakeholders
+
+All Hotspot owners are affected by this proposal. Specifically, those with extremely high witness rates per epoch would be most affected and rewards would be more evenly distributed to other Hotspots that are witnessing within those epochs. Other network participants (Validators, Routers, etc) are not affected.
+
+### Detailed Explanation
+
+Witness reward decay rates provide a soft economic limit to over-witnessing. As the number of witness events per epoch increases, a Hotspot will gain subsequently fewer reward units for each event.
+
+This decay rate can be defined as a chain variable and modified over time. The initial proposal for `witness_reward_decay_rate` is `0.08` which can be modified over time as the impact is understood. In addition, a `witness_reward_decay_exclusion` of `4`, also a chain variable, would be used to only affect witness rewards at and above the value. Practically speaking this could be seen as the following.
+
+```erl
+1> f(DecayRate), f(Exclusion), DecayRate = 0.08, Exclusion = 4, lists:sum([ case Count < Exclusion of true -> 1; _ -> math:exp((Count - Exclusion) * -1 * DecayRate) end || Count <- lists:seq(1, 20)]). 
+12.668364965907838
+2> f(DecayRate), f(Exclusion), DecayRate = 0.08, Exclusion = 4, lists:sum([ case Count < Exclusion of true -> 1; _ -> math:exp((Count - Exclusion) * -1 * DecayRate) end || Count <- lists:seq(1, 15)]).
+11.02650609098551
+3> f(DecayRate), f(Exclusion), DecayRate = 0.08, Exclusion = 4, lists:sum([ case Count < Exclusion of true -> 1; _ -> math:exp((Count - Exclusion) * -1 * DecayRate) end || Count <- lists:seq(1, 10)]).
+8.577140471334872
+4> f(DecayRate), f(Exclusion), DecayRate = 0.08, Exclusion = 4, lists:sum([ case Count < Exclusion of true -> 1; _ -> math:exp((Count - Exclusion) * -1 * DecayRate) end || Count <- lists:seq(1, 5)]). 
+4.923116346386636
+5> f(DecayRate), f(Exclusion), DecayRate = 0.08, Exclusion = 4, lists:sum([ case Count < Exclusion of true -> 1; _ -> math:exp((Count - Exclusion) * -1 * DecayRate) end || Count <- lists:seq(1, 4)]).
+4.0
+6> f(DecayRate), f(Exclusion), DecayRate = 0.08, Exclusion = 4, lists:sum([ case Count < Exclusion of true -> 1; _ -> math:exp((Count - Exclusion) * -1 * DecayRate) end || Count <- lists:seq(1, 3)]).
+3
+7> f(DecayRate), f(Exclusion), DecayRate = 0.08, Exclusion = 4, lists:sum([ case Count < Exclusion of true -> 1; _ -> math:exp((Count - Exclusion) * -1 * DecayRate) end || Count <- lists:seq(1, 2)]).
+2
+8> f(DecayRate), f(Exclusion), DecayRate = 0.08, Exclusion = 4, lists:sum([ case Count < Exclusion of true -> 1; _ -> math:exp((Count - Exclusion) * -1 * DecayRate) end || Count <- lists:seq(1, 1)]).
+1
+```
+
+At `20` witness events, the Hotspot would only be elgible for `12.66` reward units (assuming no other scaling) but at `5` witness events, the Hotspot would be eligible for almost the full amount of reward units (`4.92`). No decay occurs up to 4 events.
+
+Seen differently across the network, 5% of the network would be scaled by almost 92% on their witnesses and this would incentivize the remainder of the network to grow and expand organically. This is based on analysis of all witness receipts between blocks 1032738 and 1040915. [data](https://gist.github.com/abhay/8b75824c3b7cc27009f2a76f56fa9bc1)
+
+![population-graph](xxxx-witness-decay/focused-population-graph.png)
+![focused-population-graph](xxxx-witness-decay/focused-population-graph.png)
+
+The fortunate coincidence about this feature is that it's already built and is just two chain variable away from being activated. We are able to enable it at the same time as PoCv11 is activated (or sooner).
+
+## Open Questions
+
+* Are these proposed values the correct starting 
+* How do we verify that the proposed limits are right for the network?
+* How could these limits be adjusted in the future?
+
+## Success Metrics
+
+Success here means that a Hotspot witnessing provides sufficient data to the blockchain to reward coverage and incentives continue to be aligned to create new and wide coverage on the Helium network.

0044-lorawan-frequency-plan-selection.md

@@ -0,0 +1,110 @@
+# HIP 4x: LoRaWAN Frequency Plan Selection
+
+- Author(s): @lthiery, @ivandigiusto
+- Start Date: 2021-10-25
+- Category: Technical
+- Original HIP PR: 
+- Tracking Issue: 
+- Status: In Discussion
+
+
+# Problem Statement
+[problem_statement]: #ProblemStatement
+
+There are over a dozen of officially recognized LoRaWAN channel plans cited in 
+the [LoRaWAN Regional Specification](https://lora-alliance.org/wp-content/uploads/2021/05/RP002-1.0.3-FINAL-1.pdf):
+
+![image single-layer](0044-lorawan-frequency-plan-selection/0044-lorawan-channel-plans.png)
+
+The same document also provides guidance for eligible channel plans and 
+"LoRaWAN® Certified devices with Regulatory Type Approval":  
+
+![image single-layer](0044-lorawan-frequency-plan-selection/0044-lorawan-regional-spec-example.png)
+
+In each region, the Helium Network must select one and only one frequency plan
+(based on current design constraints). In cases where only one channel plan is
+possible (eg: Anguilla) or where only one has regulatory type approval (eg:
+American Samoa), the selection for the Helium Network may default to that one.
+
+From the snippet above, you can see a few cases where selection is not so 
+straightforward:
+* **Afghanistan, Angola, Antartica, Antigua and Barbuda, Aruba**: there is no 
+channel plan suggestion nor is there one support for regulatory type approval
+* **Aland Island, Albania, Algeria, Armenia**: there are multiple potential
+plans but not support for regulatory type approval
+* **Australia**: there are _two_ potential plans and both have regulatory
+type approval
+
+These cases each special consideration which requires deep technical expertise
+and local knowledge. This same reasoning also extends to countries that may
+not yet have ISO 3166 recognition.
+
+These configurations are currently encoded within the [`helium/miner` project](https://github.com/helium/miner/blob/master/priv/countries_reg_domains.csv);
+this encoding may sometimes have mismatches even for even the easily defined 
+and those may often be implemented quickly as "bug fixes". However, for the
+more ambiguous regions, disambiguation lacks rigor and process.
+
+# Solution
+[solution]: #solution
+
+This HIP strives to solve the problem of choosing a _single_ frequency plan
+per region. We believe this is an important assumption as while the network
+is growing rapidly, providing core coverage on a specific frequency plan and
+sub-band is critical in providing predictability for users. In other words,
+fragmenting a nascent network would leave to both confusion and difficulty
+roaming within even the same region.
+
+Upon [joining the LoRaWAN Alliance as contributing member](https://www.webwire.com/ViewPressRel.asp?aId=278878),
+DeWi also formed a LoRaWAN Technical Committee "to help steer the Helium 
+Network’s LoRaWAN infrastructure towards maximizing value for the LoRaWAN
+community at large." The membership of this committee includes many other
+contributing (and founding) members of the LoRaWAN Alliance and as such,
+includes deep technical and business knowledge of the ecosystem.
+
+**This HIP proposes that the DeWi LoRaWAN Committee may call for an initial
+assignment or change of frequency plan per region and/or country**.
+
+1. Upon doing so, the DeWi LoRaWAN Committee will open a Pull Request (PR)
+to the [`helium/docs`](https://github.com/helium/docs) repository marking the
+change and providing the reasoning for the change. The announcement should
+also be made on the local Discord channel(s) and any other standard DeWi
+announcement channels. 
+2. There will be a minimum four-week window during which a public commentary 
+will be open under the PR. During this period, anyone can propose a formal
+dissenting opinion with counter-arguments to the proposed change and must 
+provide alternate solutions if possible.
+3. Should the discussion have any _formal_ dissent, a live virtual public 
+forum will be in attempt to reach consensus. The author of the dissenting
+opinion must be ready to take the floor to represent their position.
+4. If the change remains contentious, the decision will go to on-chain
+voting. Currently, that would be implemented using [Helium Vote](https://www.heliumvote.com/)
+mechanism where 1 hotspot in the concerned region equals 1 vote. Votes
+are cast by doing a DC burn transaction towards the appropriate wallet.
+
+After steps 2 and 3, before proceeding to the next escalation, DeWi's LoRaWAN
+Committee may withdraw their proposal and reissue a new proposal at anytime.
+This would effectively restart the process at step 1.
+
+# Rationale and Alternatives
+[alternatives]: #rationale-and-alternatives
+
+An alternate approach would be to allow any hotspot operate to choose any legal
+frequency plan. For example, operators in Australia could select AU915 _or_
+AS923-1 when they assert location. We believe this to be problematic as it will
+lead to fragmentation of coverage and confusion on behalf of network users.
+Instead, we believe such mechanisms would be useful for expanding into
+additional subbands.
+
+# Deployment Impact
+[deployment-impact]: #deployment-impact
+
+A change in frequency plan could potentially cause certain devices to not be 
+eligible for operation under the new frequency plan, either due to  hardware
+or legislative constraints (ie: lack of certification to transmit on the new
+frequencies).
+
+Assuming a device is physically and legally capable of adopting the new plan,
+the adjustment will only be possible if the vendor's firmware reads the
+frequency plan indicated from the Miner or Light Gateway client and applies
+the new frequency plan to the packet forwarder utility which configures the
+SX130x front-end.