Skip to content

Commit

Permalink
Merge branch 'helium:main' into ferebee-00XX-linear-lockup
Browse files Browse the repository at this point in the history
  • Loading branch information
@ferebee
ferebee authored Feb 14, 2023
2 parents e726943 + 412796c commit f1b9019
Show file tree
Hide file tree
Showing 148 changed files with 8,038 additions and 7,471 deletions.
35 changes: 35 additions & 0 deletions .github/workflows/prettier.yml
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
name: Prettier Formatter

# Controls when the workflow will run
on:
# Triggers the workflow on push or pull request events
push:

# Allows you to run this workflow manually from the Actions tab
workflow_dispatch:

jobs:
# This workflow contains a single job called "build"
build:
# The type of runner that the job will run on
runs-on: ubuntu-latest

# Steps represent a sequence of tasks that will be executed as part of the job
steps:
# Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
- name: Checkout
uses: actions/checkout@v3
with:
# Make sure the actual branch is checked out when running on pull requests
ref: ${{ github.head_ref }}
# This is important to fetch the changes to the previous commit
fetch-depth: 0

# pretter Action
- name: Prettier Action
# You may pin to the exact commit or the version.
uses: creyD/prettier_action@6602189cf8bac1ce73ffe601925f6127ab7f21ac
# uses: creyD/[email protected]
with:
prettier_options: --write **/*.{md,mdx}
only_changed: True
9 changes: 9 additions & 0 deletions .prettierrc
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
{
"printWidth": 100,
"proseWrap": "always",
"semi": false,
"trailingComma": "all",
"singleQuote": true,
"tabWidth": 2,
"useTabs": false
}
92 changes: 36 additions & 56 deletions 0000-template.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,92 +6,72 @@
- Original HIP PR: <!-- leave this empty; maintainer will fill in ID of this pull request -->
- Tracking Issue: <!-- leave this empty; maintainer will create a discussion issue -->

# Summary
## Summary

One paragraph explanation of the proposal.
<!-- Read the content requests in all sections before starting to write any section. -->

# Motivation
<!-- Read the content requests in all sections before starting to write any section. -->

Why are we doing this? What use cases does it support? What problems does it
solve? What is the expected outcome?
## Motivation

# Stakeholders
- Why are we doing this?
- What use cases does it support?
- What problems does it solve?
- What is the expected outcome?

- Who is affected by this HIP? A stakeholder is any individual, group, or party
that has an interest in an organization and the outcomes of its actions.
## Stakeholders

- How are we soliciting feedback on this HIP from these stakeholders? Note that
they may not be watching the HIPs repository or even aren't directly active in
the Helium Community Slack channels.
- Who is affected by this HIP? A stakeholder is any individual, group, or party such as network
users, Hotspot hosts, or token holders.
- How are we soliciting feedback on this HIP from these stakeholders? Note that they may not be
watching the HIP repository or even directly active in the Helium Community chat channels.

# Detailed Explanation
## Detailed Explanation

- Introduce and explain new concepts.

- It should be reasonably clear how the proposal would be implemented.

- Provide representative examples that show how this proposal would be commonly
used.

- Provide representative examples that show how this proposal would be commonly used.
- Corner cases should be dissected by example.

# Drawbacks
## Drawbacks

- Why should we *not* do this?
- Why should we _not_ do this?
- What problems could occur if we do this?

# Rationale and Alternatives
## Rationale and Alternatives

This is your chance to discuss your proposal in the context of the whole design
space. This is probably the most important section!
This is your chance to discuss your proposal in the context of the whole design space. This is
probably the most important section!

- Why is this design the best in the space of possible designs?

- What other designs have been considered and what is the rationale for not
choosing them?

- What other designs have been considered and what is the rationale for not choosing them?
- What is the impact of not doing this?

# Unresolved Questions

- What parts of the design do you expect to resolve through the HIP process
before this gets merged?
## Unresolved Questions

- What parts of the design do you expect to resolve through the implementation
of this feature?
- What parts of the design do you expect to resolve through the HIP process before this gets merged?
- What parts of the design do you expect to resolve through the implementation of this feature?
- What related issues do you consider out of scope for this HIP that could be addressed in the
future independently of the solution that comes out of this HIP?
- Are there dependencies, milestones, or dates that need to be met for this HIP to succeed?

- What related issues do you consider out of scope for this HIP that could be
addressed in the future independently of the solution that comes out of this
HIP?
## Deployment Impact

- Are there are dependencies, milestones or dates that need need to be met for
this HIP to succeed?

# Deployment Impact

Describe how this design will be deployed and any potential impact it may have on
current users of this project.
Describe how this design will be deployed and any potential impact it may have on current users of
this project.

- How will current users be impacted?
- How will existing documentation/knowledge base need to be supported? Any content to change at
<http://docs.helium.com>?
- Is this backwards compatible? Can this HIP be undone?
- If not, what is the procedure to migrate?

- How will existing documentation/knowlegebase need to be supported?
Any content to change at <http://docs.helium.com> ?

- Is this backwards compatible?
Can this HIP be undone?

- If not, what is the procedure to migrate?
## Success Metrics

# Success Metrics

What metrics can be used to measure the success of this design?
Are any new ETL reports needed to measure the success?
What metrics can be used to measure the success of this design? Are any new ETL reports needed to
measure the success?

- What should we measure to prove a performance increase?

- What should we measure to prove an improvement in stability?

- What should we measure to prove a reduction in complexity?

- What should we measure to prove an acceptance of this by its users?
96 changes: 45 additions & 51 deletions 0001-longfi-and-lorawan.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,31 +5,30 @@

# Summary

LongFi is not a full protocol from the ground up, but instead a blockchain
layer on top of LoRaWAN. This allows any off-the-shelf LoRaWAN device to
connect to the Helium network if you can update its AppKey and AppEui.
LongFi is not a full protocol from the ground up, but instead a blockchain layer on top of LoRaWAN.
This allows any off-the-shelf LoRaWAN device to connect to the Helium network if you can update its
AppKey and AppEui.

# Motivation

There are many LoRaWAN compatible devices already out there and LoRaWAN already
has many desirable protocol features (ACK, downlink, FCC certified,
international specification). In order to accelerate adoption of the Helium
network and to lower technical barriers, LongFi is no longer a distinct
protocol from LoRaWAN but instead a layering of some blockchain components on
top of LoRaWAN.
There are many LoRaWAN compatible devices already out there and LoRaWAN already has many desirable
protocol features (ACK, downlink, FCC certified, international specification). In order to
accelerate adoption of the Helium network and to lower technical barriers, LongFi is no longer a
distinct protocol from LoRaWAN but instead a layering of some blockchain components on top of
LoRaWAN.

# Stakeholders

- LoRaWAN device users

# Detailed Explanation

This initial implementation of LongFi on LoRaWAN focuses on a single method of
end-device activation: Over-the-Air Activation (OTAA). Activation by
Personalization (ABP) is currently not supported.
This initial implementation of LongFi on LoRaWAN focuses on a single method of end-device
activation: Over-the-Air Activation (OTAA). Activation by Personalization (ABP) is currently not
supported.

In the US902-928 regulatory domain, the Helium network will operate on LoRaWAN
channels 48-55 (sub-band 7):
In the US902-928 regulatory domain, the Helium network will operate on LoRaWAN channels 48-55
(sub-band 7):

```
Channel 48, 911.900 Mhz
Expand All @@ -42,8 +41,8 @@ Channel 54, 913.100 Mhz
Channel 55, 913.300 Mhz
```

In OTAA, DevEUI, AppEUI, and AppKey are all the unencrypted LoRaWAN primitives
used in the Join Request:
In OTAA, DevEUI, AppEUI, and AppKey are all the unencrypted LoRaWAN primitives used in the Join
Request:

```
___________________________________________________________
Expand All @@ -54,9 +53,8 @@ ___________________________________________________________

<sub>source: LoRaWAN Specification 6.2.4</sub>

The LongFi primitives of Organizational Unique Identifier (OUI) and DeviceId
are mapped into AppEUI. The most significant 4 octets are OUI while the least
significant 4 octets are DeviceId.
The LongFi primitives of Organizational Unique Identifier (OUI) and DeviceId are mapped into AppEUI.
The most significant 4 octets are OUI while the least significant 4 octets are DeviceId.

```
_______________________________________________
Expand All @@ -65,18 +63,17 @@ _______________________________________________
‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾
```

Thus Helium miners receiving these unencrypted Join messages are able to route
the request to the appropriate Router (ie: a NetworkServer) by deriving the OUI
from the AppEUI and then looking up the OUI route from the blockchain records.
Thus Helium miners receiving these unencrypted Join messages are able to route the request to the
appropriate Router (ie: a NetworkServer) by deriving the OUI from the AppEUI and then looking up the
OUI route from the blockchain records.

DevEUI currently plays no role in LongFi, but remains important for LoRaWAN
functions.
DevEUI currently plays no role in LongFi, but remains important for LoRaWAN functions.

Assuming the OUI is registered in the blockchain appropriately, hotspots will
route the JoinRequest packet to the appropriate Router. The Router will use
the Message Integrity Check (MIC) to authenticate the JoinRequest and, if
successful, an unencrypted JoinAccept message will be communicated down to the
hotspot which transmits to the device, providing a NetId, DevAddr, and AppNonce.
Assuming the OUI is registered in the blockchain appropriately, Hotspots will route the JoinRequest
packet to the appropriate Router. The Router will use the Message Integrity Check (MIC) to
authenticate the JoinRequest and, if successful, an unencrypted JoinAccept message will be
communicated down to the Hotspot which transmits to the device, providing a NetId, DevAddr, and
AppNonce.

```
_______________________________________________________________________________________________
Expand All @@ -87,38 +84,35 @@ ________________________________________________________________________________

<sub>source: LoRaWAN Specification 6.2.5</sub>

Thanks to the shared secret AppKey, these fields allow the Device and Router to
privately derive the same NwkSKey and AppSKey (LoRaWAN Specification 6.2.5).
Henceforth, payloads are encrypted using NwkSkey and AppSkey (LoRaWAN
Specification 4.3.3).
Thanks to the shared secret AppKey, these fields allow the Device and Router to privately derive the
same NwkSKey and AppSKey (LoRaWAN Specification 6.2.5). Henceforth, payloads are encrypted using
NwkSkey and AppSkey (LoRaWAN Specification 4.3.3).

The DevAddr is used by LongFi to indicate the OUI and this is part of the Frame
Header Structure (FHDR) of all messages after the successful Join; this enables
hotspots to continue forwarding packets to the appropriate Router.
The DevAddr is used by LongFi to indicate the OUI and this is part of the Frame Header Structure
(FHDR) of all messages after the successful Join; this enables Hotspots to continue forwarding
packets to the appropriate Router.

The Router/NetworkServer derives the DeviceId by bruteforcing the MIC against
its list of active session keys.
The Router/NetworkServer derives the DeviceId by bruteforcing the MIC against its list of active
session keys.

According to "LoRaWAN Regional Parameters 2.24: US902-928 JoinAccept CFList",
the optional CFList parameter is ignored by the device if appended to the
Join-Response. For this reason, the MAC Command (LoRaWAN Specification 5)
LinkADRReq is used to set a channel mask appropriate for the Helium Network.
MAC commands can only be piggybacked onto a MACPayload, therefore, these will
only be sent when there is a downlink message (ie: not a Join-Response).
According to "LoRaWAN Regional Parameters 2.24: US902-928 JoinAccept CFList", the optional CFList
parameter is ignored by the device if appended to the Join-Response. For this reason, the MAC
Command (LoRaWAN Specification 5) LinkADRReq is used to set a channel mask appropriate for the
Helium Network. MAC commands can only be piggybacked onto a MACPayload, therefore, these will only
be sent when there is a downlink message (ie: not a Join-Response).

# Drawbacks

- Devices are required to update their AppKey and AppEUI to join the Helium
Network
- There is no "Fingerprint" mechanism. That is to say, there no way for a
Router to validate a message before accepting it from a Hotspot; therefore,
Hotspot will forward packets without any negotiation with Routers.
- Devices are required to update their AppKey and AppEUI to join the Helium Network
- There is no "Fingerprint" mechanism. That is to say, there no way for a Router to validate a
message before accepting it from a Hotspot; therefore, Hotspot will forward packets without any
negotiation with Routers.

# Rationale and Alternatives

- A standalone LongFi protocol was taking too long
- Modifications to the LoRaWAN specification may be made later to try to
address any architectural shortcomings
- Modifications to the LoRaWAN specification may be made later to try to address any architectural
shortcomings

# Unresolved Questions

Expand Down
Loading

0 comments on commit f1b9019

Please sign in to comment.