@helium/currency
v4.12.1-alpha.0
Published
Utilities for handling different currency types on the Helium blockchain
Downloads
872
Readme
@helium/currency
Utilities for handling the different currency types on the Helium blockchain. For more details see the following resources:
- https://www.helium.com/tokens
- https://developer.helium.com/blockchain/mining-token-rewards
- https://developer.helium.com/blockchain/tokens
Installation
$ yarn add @helium/currency
# or
$ npm install @helium/currency
Usage
@helium/currency
has two main concepts:
Balance
CurrencyType
A Balance
represents an amount of one of the supported CurrencyType
s. The following currency types are supported:
- Network Tokens (HNT) (
CurrencyType.networkToken
) - Data Credits (DC) (
CurrencyType.dataCredit
) - Security Tokens (HST) (
CurrencyType.security
) - US Dollars (USD) (
CurrencyType.usd
)
Basic Usage
Balances are constructed with their integer value representation, since this is how the API returns them.
import { Balance, CurrencyType } from '@helium/currency'
const hntBalance = new Balance(100000000, CurrencyType.networkToken)
hntBalance.toString() // 1 HNT
const dcBalance = new Balance(10, CurrencyType.dataCredit)
dcBalance.toString() // 10 DC
const hstBalance = new Balance(100000000, CurrencyType.security)
hstBalance.toString() // 1 HST
const usdBalance = new Balance(100000000, CurrencyType.usd)
usdBalance.toString() // 1 USD
:point_up: note that the Helium blockchain represents USD with 8 decimal places, when displaying oracle prices for example.
Arithmetic Operations
Balances can be added or subtracted from each other, and a balance can be multiplied by or divided by a number. This takes advantage of the underlying bignumber.js
library for handling large numbers accurately without running into floating point errors.
import { Balance, CurrencyType } from '@helium/currency'
const hntBalanceA = new Balance(100000000, CurrencyType.networkToken)
const hntBalanceB = new Balance(600000000, CurrencyType.networkToken)
hntBalanceA.plus(hntBalanceB).toString() // 7 HNT
hntBalanceB.minus(hntBalanceA).toString() // 5 HNT
hntBalanceB.times(2).toString() // 12 HNT
hntBalanceB.dividedBy(2).toString() // 3 HNT
Conversions
Balances can be converted between HNT, DC and USD. Some of these conversions require the consultation of a price oracle. A price oracle is the current value of HNT in USD as understood by the Helium blockchain for the purpose of burning HNT to DC. The current price oracle value can be retrived using @helium/http
import { Client } from '@helium/http'
import { Balance, CurrencyType } from '@helium/currency'
const client = new Client()
const oraclePrice = await client.oracle.getCurrentPrice().price
// OR
const oraclePrice = new Balance(0.45 * 100000000, CurrencyType.usd)
const hntBalance = new Balance(10 * 100000000, CurrencyType.networkToken)
hntBalance.toUsd(oraclePrice).toString(2) // 4.50 USD
hntBalance.toDataCredits(oraclePrice).toString() // 450,000 DC
const dcBalance = new Balance(10 * 100000, CurrencyType.dataCredit)
dcbalance.toNetworkTokens(oraclePrice).toString(2) // 22.22 HNT
dcbalance.toUsd().toString(2) // 10 USD
const usdBalance = new Balance(10 * 10000000, CurrencyType.usd)
usdBalance.toNetworkTokens(oraclePrice).toString(2) // 22.22 HNT
usdBalance.toDataCredits().toString() // 1,000,000 DC