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'|'rinkeby'|'kovan')..,mode:('prod'|'test'), uri:..}
ohledger {imparterTag:..,currency:'USD',mode:('prod'|'test'), uri:..}
ohledger-web3 {imparterTag:..,currency:'USD',mode:('prod'|'test'), uri:..}
btc-manual {imparterTag:..,mode:('prod'|'test'), uri:..}

imparterTag - causing the event

name - of network

currency - represented by network

mode - production or test network

uri - remuneration API URI for network

enable

Enable 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
  • 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
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
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 -- to tally without signing
btc-manual {address:..}
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'}
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'|'rinkeby'|'kovan').., mode:('prod'|'test'), uri:..}
ohledger {currency:'USD',mode:('prod'|'test'), uri:..}
ohledger-web3 {currency:'USD',mode:('prod'|'test'), uri:..}
btc-manual {mode:('prod'|'test'), uri:..}

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, recepient: Object, since: Date): Promise
Parameters
imparterTag (string)
recepient (Object) imparter specific object describing recipient of transactions to tally for.

Recipient objects are as per:

imparter tag recipient object
eth-web3 {address:..}
ohledger {address:..}
ohledger-web3 {address:..}
btc-manual {address:..}
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, recepient: Object, since: Date): Promise
Parameters
imparterTag (string)
recepient (Object) imparter specific object describing recipient of transactions to tally for.

Recipient objects are as per:

imparter tag recipient object
eth-web3 {address:..}
ohledger {address:..}
ohledger-web3 {address:..}
btc-manual {address:..}
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, since: Date, recepient: Object): Promise
Parameters
imparterTag (string)
since (Date) date to start tally since: date of oldest transaction to include. No restriction if 'null'.
recepient (Object) imparter specific object describing recipient of transactions to tally for.

Recipient objects are as per:

imparter tag recipient object
eth-web3 {address:..}
ohledger {address:..}
ohledger-web3 {address:..}
btc-manual {address:..}
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 credentials 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) to sign
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:..}
ohledger-web3 {message:.., signature:..}
ohledger-social {message:.., signature:..}
btc-manual null

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

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