Package detail

@helium/anchor-resolvers

helium9.9kApache-2.00.10.7

Wrappers around anchor custom resolvers to make composition easier

readme

Helium Program Library

A collection of solana programs used for Helium's Solana integration

Overall Design

flowchart TD
  hotspot[[Hotspots]]
  ingest[[Packet Router]]
  s3[[S3 Storage]]
  verify[Verifier]
  rewards[Rewards]
  oracle_rds[[Oracle RDS]]
  rewards_oracle[[Rewards Oracle]]
  solana[[Solana]]
  oui[[OUI]]
  iot[[Iot Devices]]


  hotspot --> ingest
  ingest --> s3
  s3 --> verify
  verify --valid packets--> s3
  s3 --> rewards
  rewards --> oracle_rds
  oracle_rds --> rewards_oracle
  rewards_oracle --Hotspot Lifetime Rewards--> solana
  ingest --> oui
  iot --> hotspot

flowchart TD
  maker[Maker App]
  onboarding[Onboarding Server]
  crank(((Rewards Crank)))
  hnt_price_oracle[[HNT Price Oracle]]
  oracles[[DNT Rewards Oracle]]
  wallet_app[Wallet App]

  oracles --set and distribute rewards tx--> wallet_app
  wallet_app --> lazy_distributor
  subgraph Solana
    manager[Hotspot Manager]
    data_credits[Data Credits]
    dnt_rewards_escrow{{DNT Escrow}}
    hotspots{{Hotspot NFTs}}
    helium_sub_daos[Helium Sub Daos]
    lazy_distributor[Lazy Distributor]
    treasury_management[Treasury Management]
    user_wallet{{Hotspot Owner Wallet}}
    treasury{{SubDAO Treasury}}
  end

  data_credits --DC Burned--> helium_sub_daos

  onboarding --issue hotspot, assert location txs--> maker
  maker --issue hotspot, assert location--> manager

  hnt_price_oracle --HNT Price--> data_credits
  dnt_rewards_escrow --> lazy_distributor

  manager --Burn DC--> data_credits
  manager --Create--> hotspots
  manager --Device Count--> helium_sub_daos


  crank --issue rewards--> helium_sub_daos
  helium_sub_daos --DNT--> dnt_rewards_escrow
  helium_sub_daos --set expiry--> treasury_management
  helium_sub_daos --mint_hnt--> treasury
  treasury -->  treasury_management

  hotspots --> lazy_distributor
  lazy_distributor --DNT--> user_wallet

ERD

Helium Sub Daos

Helium Sub Daos manages the daos and rewards structure of the Helium ecosystem. Other programs in the ecosystem are expected to call out to helium sub daos to update rewardable actions, like issuing a new hotspot and burning data credits

Data Credits

Data credits manages the soulbound helium data credits, and how they can be burned to do several actions on the network. It also manages reading from an oracle to allow burning HNT for data credits

Helium Entity Manager

Helium Entity Manager is responsible for issuing the various types of hotspots and rewardable entities that Helium supports (wifi, iot, mobile hotspots, mobile mappers, etc)

Lazy Distributor

The lazy distributor is an oracle-powered token distributor that distributes tokens to holders of particular NFTs as specified by oracles.

Oracle Architecture

In order to facilitate setting rewards and distributing rewards in a single Solana transaction, I propose at the url specified in the oracle configuration, supporting GET and POST

GET Request

Request current rewards for the hotspot. Provide ?mint=... query param with the hotspot mint.

Which should return

{
  "currentRewards": ...
}

POST Request

Sign transaction to set rewards and distribute

{
  transaction: ... // serialized transaction
}

Which should return

{
  transaction: ... // signed transaction
}

Before signing the transaction, the oracle should validate (1) that the transaction contains only

setCurrentRewards instructions from other validators
distribute instructions

and (2) that the amount set for setCurrentRewards for itself is correct.

Client Side

The client should:

Submit requests to all oracles to get the current total rewards amount
Form instructions to set rewards from all oracles using their specified rewards amount
Submit a sign transaction request to all oracles sequentially
Submit the signed transaction to Solana

Local Setup

Make sure you're using Node 18+
Install dependencies

corepack enable
yarn set version 3.6.4
yarn

Start localnet

$: TESTING=true anchor localnet

Start watcher

$: yarn watch

Bootstrap localnet

$: . ./scripts/bootstrap-localnet.sh

Run tests against localnet

$: anchor test --provider.cluster localnet --skip-deploy --skip-local-validator --skip-build

If you run into trouble with your installation, run the following command to rebuild everything from scratch.

$: yarn clean && yarn && TESTING=true anchor build && yarn build

Running packages

There's several packages that can be run as servers or applications. The individual instructions for them are included below.

Start monitor

$: cd packages/monitor-service && yarn dev
$: cd packages/monitor-service/docker-compose && docker-compose up -d

Start breakpoint demo ui

$: cd packages/breakpoint-demo-ui && yarn start

Start oracle server

$: cd packages/distributor-oracle && yarn start

Start xNFT

$: cd packages/xnft-hotspot && yarn dev

Important urls:

localhost:3000 // demo ui
localhost:3001 // grafana

changelog

Change Log

All notable changes to this project will be documented in this file. See Conventional Commits for commit guidelines.

0.10.7 (2025-04-22)

Note: Version bump only for package helium-program-library

0.10.6 (2025-04-08)

Note: Version bump only for package helium-program-library

0.10.5 (2025-04-07)

0.9.34 (2025-04-03)

0.9.33 (2025-03-28)

0.9.32 (2025-03-28)

0.9.31 (2025-03-13)

Note: Version bump only for package helium-program-library

0.10.4 (2025-04-07)

Note: Version bump only for package helium-program-library

0.10.3 (2025-03-25)

Note: Version bump only for package helium-program-library

0.10.2 (2025-03-24)

Note: Version bump only for package helium-program-library

0.10.1 (2025-03-21)

Note: Version bump only for package helium-program-library

0.10.0 (2025-03-20)

Note: Version bump only for package helium-program-library

0.9.31 (2025-03-13)

Note: Version bump only for package helium-program-library

0.9.30 (2025-03-06)

Note: Version bump only for package helium-program-library

0.9.29 (2025-03-05)

Note: Version bump only for package helium-program-library

0.9.28 (2025-03-05)

Note: Version bump only for package helium-program-library

0.9.27 (2025-03-04)

Note: Version bump only for package helium-program-library

0.9.26 (2025-03-03)

Note: Version bump only for package helium-program-library

0.9.25 (2025-02-28)

Note: Version bump only for package helium-program-library

0.9.24 (2025-02-26)

Note: Version bump only for package helium-program-library

0.9.24-alpha.0 (2025-02-03)

Note: Version bump only for package helium-program-library

0.9.23 (2025-01-31)

Note: Version bump only for package helium-program-library

0.9.22 (2025-01-30)

Note: Version bump only for package helium-program-library

0.9.21 (2025-01-30)

Note: Version bump only for package helium-program-library

0.9.20 (2025-01-30)

Note: Version bump only for package helium-program-library

0.9.19 (2025-01-07)

Note: Version bump only for package helium-program-library

Upgrades Solana web3.js to 1.91.1

0.9.18 (2024-12-10)

Note: Version bump only for package helium-program-library

0.9.17 (2024-12-10)

Note: Version bump only for package helium-program-library

0.9.16 (2024-12-09)

Note: Version bump only for package helium-program-library

0.9.15 (2024-11-20)

Note: Version bump only for package helium-program-library

0.9.14 (2024-11-20)

Note: Version bump only for package helium-program-library

0.9.13 (2024-11-18)

Note: Version bump only for package helium-program-library

0.9.12 (2024-10-29)

Reverts

Revert "Add temp endpoint to fix mobile hotspots (#683)" (#685) (3f5a4be), closes #683 #685 #683

0.9.11 (2024-10-29)

Reverts

Revert "Add temp endpoint to fix mobile hotspots (#683)" (#685) (3f5a4be), closes #683 #685 #683

0.9.10 (2024-10-28)

Note: Version bump only for package helium-program-library

0.9.9 (2024-10-28)

Note: Version bump only for package helium-program-library

0.9.8 (2024-10-23)

Note: Version bump only for package helium-program-library

0.9.7 (2024-10-04)

Note: Version bump only for package helium-program-library

0.9.6 (2024-09-16)

Reverts

Revert "Add temp endpoint to fix mobile hotspots (#683)" (#685) (3f5a4be), closes #683 #685 #683

0.9.5 (2024-09-10)

Reverts

Revert "Add temp endpoint to fix mobile hotspots (#683)" (#685) (3f5a4be), closes #683 #685 #683

0.9.4 (2024-08-09)

Note: Version bump only for package helium-program-library

0.9.3 (2024-08-09)

Note: Version bump only for package helium-program-library

0.9.2 (2024-08-01)

Note: Version bump only for package helium-program-library

0.9.1 (2024-07-30)

Note: Version bump only for package helium-program-library

0.9.0 (2024-07-30)

0.9.0-alpha.9 (2024-07-25)

0.9.0-alpha.8 (2024-07-25)

0.9.0-alpha.7 (2024-07-24)

0.9.0-alpha.6 (2024-07-24)

0.9.0-alpha.5 (2024-07-16)

0.9.0-alpha.4 (2024-07-16)

0.9.0-alpha.3 (2024-07-08)

0.9.0-alpha.2 (2024-07-03)

0.9.0-alpha.1 (2024-07-03)

0.9.0-alpha.0 (2024-06-27)

Note: Version bump only for package helium-program-library

0.9.0-alpha.9 (2024-07-25)

Note: Version bump only for package helium-program-library

0.9.0-alpha.8 (2024-07-25)

Note: Version bump only for package helium-program-library

0.9.0-alpha.7 (2024-07-24)

0.8.7 (2024-07-17)

Note: Version bump only for package helium-program-library

0.9.0-alpha.6 (2024-07-24)

Note: Version bump only for package helium-program-library

0.8.6 (2024-06-25)

Note: Version bump only for package helium-program-library

0.8.5 (2024-06-25)

Note: Version bump only for package helium-program-library

0.8.4 (2024-06-25)

Note: Version bump only for package helium-program-library

0.8.3 (2024-06-24)

Reverts

Revert "Feat/632 hip 109 (#634)" (ca0139e), closes #634

0.8.2 (2024-06-18)

Note: Version bump only for package helium-program-library

0.8.1 (2024-06-18)

Note: Version bump only for package helium-program-library

0.8.0 (2024-06-18)

Note: Version bump only for package helium-program-library

Breaking

Switch to Pyth V2 sponsored price feeds.
- This breaks @helium/currency-utils
- This changes accounts not resolved automatically for onboarding mobile hotspots

0.7.17 (2024-06-05)

Note: Version bump only for package helium-program-library

0.7.16 (2024-06-05)

Note: Version bump only for package helium-program-library

0.7.15 (2024-06-05)

Note: Version bump only for package helium-program-library

0.7.14 (2024-05-08)

Note: Version bump only for package helium-program-library

0.7.13 (2024-05-08)

Note: Version bump only for package helium-program-library

0.7.12 (2024-04-30)

Note: Version bump only for package helium-program-library

0.7.11 (2024-04-29)

Note: Version bump only for package helium-program-library

0.7.10 (2024-04-19)

Note: Version bump only for package helium-program-library

0.7.9 (2024-04-18)

Note: Version bump only for package helium-program-library

0.7.8 (2024-04-18)

Note: Version bump only for package helium-program-library

0.7.7 (2024-04-15)

Features

#629: Add configurable destination for lazy distributor (#630) (c64972f), closes #629

0.7.6 (2024-04-10)

Note: Version bump only for package helium-program-library

0.7.5 (2024-04-10)

Note: Version bump only for package helium-program-library

0.7.4 (2024-04-10)

Note: Version bump only for package helium-program-library

0.7.3 (2024-04-04)

Note: Version bump only for package helium-program-library

0.7.2 (2024-04-04)

Note: Version bump only for package helium-program-library

0.7.1 (2024-04-02)

Note: Version bump only for package helium-program-library

0.7.0 (2024-03-29)

Breaking

Interfaces in spl-utils around transactions have changed to switch to VersionedTransaction. This allows for better transaction packing with loookup tables.

0.6.42 (2024-03-19)

Note: Version bump only for package helium-program-library

0.6.41 (2024-03-18)

Note: Version bump only for package helium-program-library

0.6.40 (2024-03-18)

Note: Version bump only for package helium-program-library

0.6.39 (2024-03-13)

Note: Version bump only for package helium-program-library

0.6.38 (2024-03-11)

Note: Version bump only for package helium-program-library

0.6.37 (2024-03-11)

Note: Version bump only for package helium-program-library

0.6.36 (2024-03-08)

Features

#559: Use pyth oracle for mobile onboarding (#566) (1b751e9), closes #559
#575: Standardize all rewardable entities in url and creators (#584) (8560ad2), closes #575
#644: Add helium/sus package to preview transactions (09c4c70), closes #644

0.6.35 (2024-03-04)

Note: Version bump only for package helium-program-library

0.6.34 (2024-03-04)

Note: Version bump only for package helium-program-library

0.6.33 (2024-03-01)

Note: Version bump only for package helium-program-library

0.6.32 (2024-02-28)

Note: Version bump only for package helium-program-library

0.6.31 (2024-02-28)

Note: Version bump only for package helium-program-library

0.6.30 (2024-02-22)

Features

#575: Standardize all rewardable entities in url and creators (#584) (8560ad2), closes #575
#644: Add helium/sus package to preview transactions (09c4c70), closes #644

0.6.29 (2024-02-06)

Note: Version bump only for package helium-program-library

0.6.28 (2024-02-06)

Features

#559: Use pyth oracle for mobile onboarding (#566) (1b751e9), closes #559

0.6.27 (2024-02-01)

Note: Version bump only for package helium-program-library

0.6.26 (2024-01-31)

Bug Fixes

Do not require initialized token account if no mobile burn (#542) (a7334ed)

Features

#494: Implement HIP-96 wifi onboarding fees (#506) (50471c3), closes #494
#495: Add monitoring for claimable rewards and vehnt (#507) (efc6813), closes #495 #495
#504: Parallelize claim delegation rewards (#509) (01b5f3d), closes #504
#525: Add prom metrics for price oracles, fix distributor oracle total rewards metric (#528) (13a5cb8)
#526: Remove digit shift from VSR (#527) (651e629), closes #526
#543: Add transaction webhook capability to account-postgres-sink (#544) (a0d7bd9), closes #543
Avoid purging prices when purging oracles (#533) (622ec12)

0.6.25 (2024-01-29)

Note: Version bump only for package helium-program-library

0.6.24 (2024-01-29)

Note: Version bump only for package helium-program-library

0.6.23 (2024-01-20)

Note: Version bump only for package helium-program-library

0.6.22 (2024-01-19)

Bug Fixes

Do not require initialized token account if no mobile burn (#542) (a7334ed)

Features

#494: Implement HIP-96 wifi onboarding fees (#506) (50471c3), closes #494
#495: Add monitoring for claimable rewards and vehnt (#507) (efc6813), closes #495 #495
#504: Parallelize claim delegation rewards (#509) (01b5f3d), closes #504
#525: Add prom metrics for price oracles, fix distributor oracle total rewards metric (#528) (13a5cb8)
#526: Remove digit shift from VSR (#527) (651e629), closes #526
#543: Add transaction webhook capability to account-postgres-sink (#544) (a0d7bd9), closes #543
Avoid purging prices when purging oracles (#533) (622ec12)

0.6.21 (2024-01-19)

Note: Version bump only for package helium-program-library

0.6.20 (2024-01-19)

Features

#526: Remove digit shift from VSR (#527) (651e629), closes #526

0.6.19 (2024-01-19)

Bug Fixes

Do not require initialized token account if no mobile burn (#542) (a7334ed)

0.6.18 (2024-01-19)

Bug Fixes

Do not require initialized token account if no mobile burn (#542) (a7334ed)

0.6.17 (2024-01-19)

Note: Version bump only for package helium-program-library

0.6.16 (2024-01-16)

Features

#543: Add transaction webhook capability to account-postgres-sink (#544) (a0d7bd9), closes #543

0.6.15 (2024-01-12)

Note: Version bump only for package helium-program-library

0.6.14 (2024-01-11)

Note: Version bump only for package helium-program-library

0.6.13 (2024-01-05)

Features

Avoid purging prices when purging oracles (#533) (622ec12)

0.6.12 (2024-01-02)

Note: Version bump only for package helium-program-library

0.6.11 (2023-12-27)

Features

#525: Add prom metrics for price oracles, fix distributor oracle total rewards metric (#528) (13a5cb8)

0.6.10 (2023-12-22)

Features

#494: Implement HIP-96 wifi onboarding fees (#506) (50471c3), closes #494
#495: Add monitoring for claimable rewards and vehnt (#507) (efc6813), closes #495 #495
#504: Parallelize claim delegation rewards (#509) (01b5f3d), closes #504

0.6.9 (2023-12-21)

Features

#494: Implement HIP-96 wifi onboarding fees (#506) (50471c3), closes #494
#495: Add monitoring for claimable rewards and vehnt (#507) (efc6813), closes #495 #495
#504: Parallelize claim delegation rewards (#509) (01b5f3d), closes #504

0.6.8 (2023-12-21)

Note: Version bump only for package helium-program-library

0.6.7 (2023-12-19)

Features

#494: Implement HIP-96 wifi onboarding fees (#506) (50471c3), closes #494
#504: Parallelize claim delegation rewards (#509) (01b5f3d), closes #504

0.6.6 (2023-12-13)

Features

#495: Add monitoring for claimable rewards and vehnt (#507) (efc6813), closes #495 #495

0.6.5 (2023-12-08)

Note: Version bump only for package helium-program-library

0.6.4 (2023-12-06)

Features

#483: Create a burn rewardable entity as a sink for unused service provider reward (#487) (2b8ff5b), closes #483 #483

0.6.3 (2023-12-01)

Features

#483: Create a burn rewardable entity as a sink for unused service provider reward (#487) (2b8ff5b), closes #483 #483

0.6.2 (2023-11-17)

Features

#483: Create a burn rewardable entity as a sink for unused service provider reward (#487) (2b8ff5b), closes #483 #483

0.6.1 (2023-11-10)

0.6.0 (2023-11-10)

Breaking

Fee payer for RecipientV0 account in @helium/distributor-oracle is now the user wallet. The oracle will soon begin rejecting transactions with the oracle as the fee payer.

0.5.0 (2023-11-09)

Note: Version bump only for package helium-program-library

0.4.6 (2023-11-07)

Note: Version bump only for package helium-program-library

0.4.5 (2023-11-07)

Note: Version bump only for package helium-program-library

0.4.4 (2023-11-07)

Features

#451: Create cloudfront invalidator (#452) (e5d44a0), closes #451 #441
#464: Add metadata service endpoints for wallet, hotspots in bulk (#465) (a5d9721), closes #464 #464

0.4.3 (2023-10-26)

Note: Version bump only for package helium-program-library

0.4.2 (2023-10-19)

Features

#451: Create cloudfront invalidator (#452) (e5d44a0), closes #451 #441

0.4.1 (2023-10-12)

Reverts

Revert "Revert lazy transactions bitmap" (46b3cdf)

0.4.0 (2023-09-22)

Features

#373: replace clockwork (#388) (55033c7), closes #373
#376: Replace lazy transactions markers with a bitmap to reclaim rent (#380) (a691257), closes #376 #376
#379: Automate npm publish and fix devnet conflicting sqds txns (#386) (a4a3780)

Reverts

Revert "Add back mobile genesis fix for devnet" (93e9a2c)

0.3.2 (2023-09-16)

Features

#373: replace clockwork (#388) (55033c7), closes #373
#376: Replace lazy transactions markers with a bitmap to reclaim rent (#380) (a691257), closes #376 #376
#379: Automate npm publish and fix devnet conflicting sqds txns (#386) (a4a3780)

Reverts

Revert "Add back mobile genesis fix for devnet" (93e9a2c)

0.3.1 (2023-09-15)

Features

#373: replace clockwork (#388) (55033c7), closes #373
#376: Replace lazy transactions markers with a bitmap to reclaim rent (#380) (a691257), closes #376 #376
#379: Automate npm publish and fix devnet conflicting sqds txns (#386) (a4a3780)

Reverts

Revert "Add back mobile genesis fix for devnet" (93e9a2c)

0.3.0 (2023-09-14)

Breaking

distributor-oracle - bulkFormTransactions now takes batch functions for asset and proof fetching, instead of individual fetch functions. If you were passing custom functions, this code will need to change.

Features

#373: replace clockwork (#388) (55033c7), closes #373
#376: Replace lazy transactions markers with a bitmap to reclaim rent (#380) (a691257), closes #376 #376
#379: Automate npm publish and fix devnet conflicting sqds txns (#386) (a4a3780)

Reverts

Revert "Add back mobile genesis fix for devnet" (93e9a2c)

0.2.22 (2023-09-13)

Features

#373: replace clockwork (#388) (55033c7), closes #373
#376: Replace lazy transactions markers with a bitmap to reclaim rent (#380) (a691257), closes #376 #376
#379: Automate npm publish and fix devnet conflicting sqds txns (#386) (a4a3780)

Reverts

Revert "Add back mobile genesis fix for devnet" (93e9a2c)

0.2.15 (2023-07-31)

Note: Version bump only for package helium-program-library

0.2.7 (2023-06-29)

Note: Version bump only for package helium-program-library

0.2.3 (2023-06-16)

Reverts

Revert "Add support for data only hotspots (#246)" (1728939), closes #246

0.2.2 (2023-06-08)

Reverts

Revert "Add support for data only hotspots (#246)" (1728939), closes #246

0.2.1 (2023-06-08)

Reverts

Revert "Add support for data only hotspots (#246)" (1728939), closes #246

0.2.0 (2023-06-06)

Reverts

Revert "Add support for data only hotspots (#246)" (66247c7), closes #246