ledgers.js :: overhide remuneration library for browser use

$npm_package_version
Need help reading this?

oh$

REFERENCES

Library code: https://github.com/overhide/ledgers.js/blob/master/dist/ledgers.js.

Repository for this library is https://github.com/overhide/ledgers.js.

The above repository contains a demo app of this library working in conjunction with:

ABOUT

JavaScript library to be used in-browser and interrogate overhide remuneration providers as to validity of ledger credentials and transactions involving these credentials.

The goal of the library and the overhide remuneration providers is to ease using of all types of ledgers for authentication (I am who I say) and authorization (paid access tiers).

The library leverages injected currency wallets where it can, and exposes functions to work with loose currencies (without wallets) where it cannot.

The library exports the oh$ object for use as a module when bundling.

import oh$ from "ledgers.js";
oh$.enable(token);
oh$.addEventListener('onWalletChange', (e) => {...});

APIs abstracted by ledgers.js require a bearer-token. The token (above) is passed in to enable the rest of the library's functionality. oh$.enable(..) can be called every so often with a refreshed token.

A token can be retrieved with a GET /token call (see https://token.overhide.io/swagger.html).

To retrieve tokens please first register for your own API key at https://token.overhide.io/register.

The library can be loaded straight into your HTML (along with pre-requisite web3.min.js) and accessed by its oh$ property from the browser's window object:

<script 
   src="https://cdnjs.cloudflare.com/ajax/libs/web3/1.3.4/web3.min.js" 
   integrity="sha512-TTGImODeszogiro9DUvleC9NJVnxO6M0+69nbM3YE9SYcVe4wZp2XYpELtcikuFZO9vjXNPyeoHAhS5DHzX1ZQ==" 
   crossorigin="anonymous"></script>
<script src="./dist/ledgers.js"></script>
<script>
  oh$.enable(token);
  oh$.addEventListener('onWalletChange', (e) => {...});
</script>

IMPARTERS

The library works with a concept of imprater tags. Wallets impart credentials, signatures, and transactions. For loose change--where no wallet exists--the library can be interrogated as to which entities should be set by the user (can* functions); causing the entities to be imparted back to the user in a common code flow.

The imparter tags are a simple naming convention. For example if multiple Ethereum wallet APIs were imparting data they would be individually tagged with a prefix "eth" and a dashed suffix. No suffix indicates a loose change imparter:

  • eth-web3
  • eth-?

Similarly for overhide-ledger, the prefix is "ohledger", the suffix won't be attached on the loose change version and will be suffixed on the web3 walleted version:

  • ohledger
  • ohledger-web3
  • ohledger-social

The ohledger-social imparter is to use the overhide-ledger with credentials stored online behind a Microsoft or Google social login. The overhide-ledger credentials are not transferred to the client. They sit in the cloud and are used once a social provider allows it.

Thus far Bitcoin is only supported in manual mode (no Bitcoin wallet injection into target site):

  • btc-manual

The following sections cover special notes on each imparter. The library adheres to these notes.

eth-web3

Ethereum addresses are 20 bytes: 42 character 'hex' strings prefixed with '0x'.

Ethereum secret keys for signing addresses are 32 bytes: 66 character 'hex' strings prefixed with '0x'.

Ethereum networks names/modes are:

name mode notes
main prod
rinkeyby test
kovan test not supported
ropsten test not supported
goerli test not supported

The denomination for amounts is the Wei

ohledger, ohledger-web3, ohledger-social

Addresses and secret keys use Ethereum format.

Addresses are 20 bytes: 42 character 'hex' strings prefixed with '0x'.

Secret keys for signing addresses are 32 bytes: 66 character 'hex' strings prefixed with '0x'.

Network tuples consist of a 'currency' as a three letter ISO fiat currency code and a 'mode'. The supported 'currency' names are:

  • 'USD'

The denominations are:

Currency denomination
USD cents

Note: at this point only USD are supported. If there is a need, and overhide-ledger instances in currencies other than USD come online, we'll revisit this.

An 'ohledger' mode is one of 'prod' or 'test'

btc-manual

Addresses use Bitcoin format.

Bitcoin network modes are:

  • prod -- for mainnet
  • test -- for testnet

The denomination for amounts is the Satoshi.

oh$

onWalletChange

Event called when wallets' state changes.

In user code:

oh$.addEventListener('onWalletChange', (e) => console.log(`wallet for ${e.imparterTag} is available:${e.isPresent}`));
onWalletChange
Parameters
event (Object) object - the event object passed in will have additional attributes

The new event object will conform to the following:

imparter tag event object attributes
* {imparterTag:..,isPresent:..}

imparterTag - causing the event

isPresent - if wallet is present for imparter

onWalletPopup

Event called when wallet is expected to popup. Useful in case user wants to react to popup in UI.

In user code:

oh$.addEventListener('onWalletPopup', (e) => console.log(`wallet for ${e.imparterTag} popped`));
onWalletPopup
Parameters
event (Object) object - the event object passed in will have additional attributes

The new event object will conform to the following:

imparter tag event object attributes
* {imparterTag:..}

imparterTag - causing the pop-up

onCredentialsUpdate

Event called when an credentials change for one of the tracked imparters.

Only called when credentials are valid as per imparter: ready to be used for signing, transacting.

In user code:

oh$.addEventListener('onCredentialsUpdate', (e) => {
  console.log(`new address for ${e.imparterTag} is:${e.address}`);
  return;
});
onCredentialsUpdate
Parameters
event (Object) object - the event object passed in will have additional attributes

The new event object will conform to the following:

imparter tag event object attributes
eth-web3 {imparterTag:..,address:..}
ohledger {imparterTag:..,address:..,secret:..}
ohledger-web3 {imparterTag:..,address:..}
ohledger-social {imparterTag:..,address:..}
btc-manual {imparterTag:..,address:..}

imparterTag - causing the event

address - ledger public address of credential set for imparter

secret - ledger PKI private secret for credential set for imparter

onNetworkChange

Event called when the network changes for a particular imparter tag.

For example for "eth" the network could changed from "main" to "rinkeby".

In user code:

oh$.addEventListener('onNetworkChange', (e) => {
  if (e.imparterTag === 'eth-web3') console.log(`new network selected for ${e.imparterTag} is:${e.name}`);
  if (e.imparterTag === /ohledger/.test(e.imparterTag)) console.log(`working in currency: ${e.currency}`);
  if (e.imparterTag === 'btc-manual') console.log(`new network mode selected for ${e.imparterTag} is:${e.name}`);
  return;
});
onNetworkChange
Parameters
event (Object) object - the event object passed in will have additional attributes

The new credentials object will conform to the following:

imparter tag event object attributes
eth-web3 `{imparterTag:..,name:('main'
ohledger `{imparterTag:..,currency:'USD',mode:('prod'
ohledger-web3 `{imparterTag:..,currency:'USD',mode:('prod'
btc-manual `{imparterTag:..,mode:('prod'

imparterTag - causing the event

name - of network

currency - represented by network

mode - production or test network

uri - remuneration API URI for network

enable

Enable (initialize) oh$ by instrumenting with token for ledger access.

oh$ calls may stall while waiting for this call to complete successfully.

A token can be retrieved with a GET /token call (see https://token.overhide.io/swagger.html).

To retrieve tokens please first register for your own API key at https://token.overhide.io/register.

enable(token: string)
Parameters
token (string)

getImparterTags

Retrieves all imparter tags injected by wallets and statically available from the library.

getImparterTags(): Array
Returns
Array: of strings: the imparter tags available

canSetCredentials

Interrogate whether the imparter tag can have credentials set by the user: or does the wallet control it exclusively.

Only the following imparter(s) will return 'true':

  • ohledger
  • ohledger-social
  • btc-manual
canSetCredentials(imparterTag: string): boolean
Parameters
imparterTag (string)
Returns
boolean: 'true' if particular imparter tag can have credentials set.

canGenerateCredentials

Interrogate whether the imparter tag can have credentials generated by the user: or does the wallet control it exclusively.

Only the following imparter(s) will return 'true':

  • ohledger
canGenerateCredentials(imparterTag: string): boolean
Parameters
imparterTag (string)
Returns
boolean: 'true' if particular imparter tag can have credentials generated.

canChangeNetwork

Interrogate whether the imparter tag can have network changed by the user via oh$: or does the wallet control it exclusively.

Only the following imparter(s) will return 'true':

  • ohledger
  • ohledger-web3
  • ohledger-social
  • btc-manual
canChangeNetwork(imparterTag: string): boolean
Parameters
imparterTag (string)
Returns
boolean: 'true' if particular imparter tag can have networks changed via oh$.

generateCredentials

For imparters that can have credentials generated, generates them.

Fires onCredentialsUpdate event against oh$

generateCredentials(imparterTag: string, options: Object): Promise
Parameters
imparterTag (string)
options (Object) imparter specific generation options, if any.

The options objects are as follows:

imparter tag credentials object comments
eth-web3 N/A not supported
ohledger null
ohledger-web3 N/A not supported
ohledger-social N/A not supported
btc-manual N/A not supported
Returns
Promise: representing a 'true' if success else 'false'; also fires onCredentialsUpdate event against oh$

setCredentials

For imparters that can have credentials set, sets them.

Fires onCredentialsUpdate event against oh$.

setCredentials(imparterTag: string, credentials: Object): Promise
Parameters
imparterTag (string)
credentials (Object) credentials object of imparter specific parameters to set

The credentials objects are as follows:

imparter tag credentials object comments
eth-web3 N/A not suppoted
ohledger {address:..,secret:..} address is optional, if not set will be extracted from secret; secret is optional, if not set, address must be set, and this imparter will not be used to sign: will be used to check isOnLedger, getTransactions, getTally, and getTallyDollars, with explicitly provided signature in those calls' options objects.
ohledger-web3 N/A not supported
ohledger-social {provider:..[, address:..]} null to log-out; provider is one of 'google' or 'microsoft'; optionally provide address if known. provider can be set to 'any' if this imparter will not be used to sign: will be used to check isOnLedger, getTransactions, getTally, and getTallyDollars, with explicitly provided signature in those calls' options objects.
btc-manual {address:..}

For ohledger-social the actual address will be retruned (via onCredentialsUpdate event) when calling sign or any other call that needs a signature.

Returns
Promise: representing a 'true' if success else 'false'; also fires onCredentialsUpdate event against oh$

setNetwork

For imparters that can have networks changed via oh$, changes it.

Fires onNetworkChange event against oh$.

setNetwork(imparterTag: string, details: Object): Promise
Parameters
imparterTag (string)
details (Object) network details object of imparter specific parameters to set.

The network details objects are as follows:

imparter tag network details object comments
eth-web3 N/A not supported, change in wallet
ohledger `{currency:'USD', mode:'prod' 'test'}`
ohledger-web3 `{currency:'USD', mode:'prod' 'test'}`
ohledger-social `{currency:'USD', mode:'prod' 'test'}`
btc-manual `{mode:'prod' 'test'}`
Returns
Promise: representing a 'true' if success else 'false'; also fires onNetworkChange event against oh$

getOverhideRemunerationAPIUri

Based on current network set returns the overhide remuneration API URI configured in the library.

getOverhideRemunerationAPIUri(imparterTag: string): string
Parameters
imparterTag (string)
Returns
string: the URI.

getCredentials

Retrieves current credentials for an imparterTag.

getCredentials(imparterTag: string): Object
Parameters
imparterTag (string)
Returns
Object: details - an object describing current credentials, imparterTag dependant:
imparter tag credentials object
eth-web3 {address:..}
ohledger {address:..,secret:..}
ohledger-web3 {address:..}
ohledger-social {address:..}
btc-manual {address:..}

getNetwork

Retrieves current network for an imparterTag.

getNetwork(imparterTag: string): Object
Parameters
imparterTag (string)
Returns
Object: details - an object describing current network, imparterTag dependant:
imparter tag network details object
eth-web3 `{name:('main'
ohledger `{currency:'USD',mode:('prod'
ohledger-web3 `{currency:'USD',mode:('prod'
ohledger-social `{currency:'USD',mode:('prod'
btc-manual `{mode:('prod'

getFromDollars

Retrieve a (highest) converted amount in imparter specific denomination from a provided dollar amount at a very recent exchange rate.

getFromDollars(imparterTag: string, dollarAmount: number): Promise
Parameters
imparterTag (string)
dollarAmount (number) the dollar amount.
Returns
Promise: with the value in imparter specific currency at the present time (based on recent exchange rate).

getTallyDollars

Retrieve a tally of all transactions on the imparter's ledger--perhaps within a date range--converted to a US dollar amount.

getTallyDollars(imparterTag: string, options: Object, since: Date): Promise
Parameters
imparterTag (string)
options (Object) imparter specific object describing options for the operation.

Recipient objects are as per:

imparter tag options object
eth-web3 {address:..}
ohledger {address:.., token:.., signature:..}
ohledger-web3 {address:.., token:.., signature:..}
ohledger-social {address:.., token:.., signature:..}
btc-manual {address:..}

To retrieve private transactions from overhide ledger ensure to sign the token (passed into enable) before calling this method.

Alternatively you may provide a previous token as token and corresponding signature signed by the from-address, the imparter's credentials.

Without a properly signed token available to this call, only public transactions -- those created using createTransaction without isPrivate flag -- are retruned. All Ethereum and Bitcoin transactions are public.

since (Date) date to start tally since: date of oldest transaction to include. No restriction if 'null'.
Returns
Promise: with the {'tally':.., 'as-of':..} object, whereby the 'tally' value is in US dollars: all transactions are exchanged to USD at an approximate (highest) exchange rate close to the transactions' time. The 'as-of' timestamp is that of the call (pass this to back-end to retrieve cached values at better API call rates).

getTally

Retrieve a tally of all transactions on the imparter's ledger--perhaps within a date range.

getTally(imparterTag: string, options: Object, since: Date): Promise
Parameters
imparterTag (string)
options (Object) imparter specific object describing options for the operation.

Recipient objects are as per:

imparter tag options object
eth-web3 {address:..}
ohledger {address:.., token:.., signature:..}
ohledger-web3 {address:.., token:.., signature:..}
ohledger-social {address:.., token:.., signature:..}
btc-manual {address:..}

To retrieve private transactions from overhide ledger ensure to sign the token (passed into enable) before calling this method.

Alternatively you may provide a previous token as token and corresponding signature signed by the from-address, the imparter's credentials.

Without a properly signed token available to this call, only public transactions -- those created using createTransaction without isPrivate flag -- are retruned. All Ethereum and Bitcoin transactions are public.

since (Date) date to start tally since: date of oldest transaction to include. No restriction if 'null'.
Returns
Promise: with the {'tally':.., 'as-of':..} object, whereby the tally value is in imparter specific currency. The 'as-of' timestamp is that of the call (pass this to back-end to retrieve cached values at better API call rates).

getTransactions

Retrieve transactions on the imparter's ledger, perhaps within a date range, from credentials set against imparter to a recipient

getTransactions(imparterTag: string, options: Object, since: Date): Promise
Parameters
imparterTag (string)
options (Object) imparter specific object describing options for the operation.

Recipient objects are as per:

imparter tag options object
eth-web3 {address:..}
ohledger {address:.., token:.., signature:..}
ohledger-web3 {address:.., token:.., signature:..}
ohledger-social {address:.., token:.., signature:..}
btc-manual {address:..}

To retrieve private transactions from overhide ledger ensure to sign the token (passed into enable) before calling this method.

Alternatively you may provide a previous token as token and corresponding signature signed by the from-address, the imparter's credentials.

Without a properly signed token available to this call, only public transactions -- those created using createTransaction without isPrivate flag -- are retruned. All Ethereum and Bitcoin transactions are public.

since (Date) date to start tally since: date of oldest transaction to include. No restriction if 'null'.
Returns
Promise: with the {'transactions': [{"transaction-value":..,"transaction-date":..},..], 'as-of':..} object, whereby 'transactions' is the list of transactions and 'as-of' is the timestamp of the call.

isOnLedger

Determine if current credentials have some transaction on the imparter's ledger: transaction can be to anyone.

Intent is to validate beyond just a valid address. To validate the address has been used.

May fire onWalletPopup event against oh$.

isOnLedger(imparterTag: string, options: Object): Promise
Parameters
imparterTag (string)
options (Object) options for the specific imparter.

The options objects are as follows:

imparter tag options object
eth-web3 {message:.., signature:..}
ohledger {message:.., signature:..}
ohledger-web3 {message:.., signature:..}
ohledger-social {message:.., signature:..}
btc-manual {message:.., signature:..}

If message and signature are provided they are used instead of oh$ asking for wallet to resign message.

Returns
Promise: with 'true' or 'false'; may fire onWalletPopup event against oh$

sign

Sign using the provided message using the credentials set against the specific imparter.

Note: wallet might pop up a dialog upon this call, consider that in your UX flow.

May fire onWalletPopup event against oh$.

sign(imparterTag: string, message: string): Promise
Parameters
imparterTag (string)
message (string) optional message to sign, if not provided, token value (from enable function) is signed. Last signature is remembered for use with other functions such as createTransaction , getTransactions .
Returns
Promise: with the signature; may fire onWalletPopup event against oh$

createTransaction

Create a transaction on the imparter's ledger.

May fire onWalletPopup event against oh$; wallet might pop up a dialog upon this call, consider that in your UX flow.

createTransaction(imparterTag: string, amount: number, to: string, options: Object): Promise
Parameters
imparterTag (string)
amount (number)
to (string) address of recipient

$0 (amount) transactions against ohledger or ohledger-web imparters use the current credential as the to address, not the specified to address.

options (Object) other options required for the specific imparter.

The options objects are as follows:

imparter tag credentials object
eth-web3 null
ohledger {message:.., signature:.., isPrivate:..}
ohledger-web3 {message:.., signature:.., isPrivate:..}
ohledger-social {message:.., signature:.., isPrivate:..}
btc-manual null

If message and signature are provided they are used. If either is not provided, the overhide token value (as passed into enable) is used for signing and remembered for other operations suich as getTransactions.

To create a private transaction, where possible, ensure to set isPrivate to true.

For overhide ledger message must be a valid overhide token value such as passed into enable.

Returns
Promise: of a 'true' for success or an Error; may fire onWalletPopup event against oh$

fire

Function to fire events.

fire(which: string, params: Object)
Parameters
which (string) event name to fire
params (Object) to copy to event

addTag

addTag(tag: string)
Parameters
tag (string) -- to add to imparterTags if not in imparterTags

removeTag

removeTag(tag: string)
Parameters
tag (string) -- to remove from imparterTags if in imparterTags