ledgers.js

This repository (git|npm) is the distribution of the ledgers.js library (API) in support of ledger-based authorization.

It's a suite of tools to make the authorization workflows part of your application.

Figure 1: Where ledgers.js fits in.

The ledgers.js library sits between the login page and the ledgers it abstracts.

The library interacts with in-browser wallets for signing (authentication)--if available.

The library makes sums of ledger transaction available to the login page for authorization criteria checks. Topping up payments requires transacting with ledgers which is done via linked Web sites and available in-browser wallets.

The business logic does not leverage ledgers.js--the library is intended for login pages not service code. The business logic code interacts directly with remuneration APIs--discussed below.

More Information

For more information, videos, write-ups, please visit https://overhide.io.

For help, reach out on r/overhide.

Getting a Taste

You can see ledgers.js live as embedded in this live API playground learning tool.

This playground is hosted by this repo: it's available in this repo in the ./play folder. You can run your own local instance with npm run play and by directing your browser at http://localhost:8080/play/index.html.

The playground showcases all library APIs as available to be used against ledgers.js test networks.

You can use the playground with your web3.js enabled browser wallet such as https://metamask.io/. If testing with Ethereum, just ensure to use the Rinkeby testnet.

You can also see ledgers.js embedded in one of these "demo" tools:

• the ledgers.js-demo
  • a sample login page made with ledger.js
  • a sample backend using the two remuneration APIs
• a demo of ledgers.js in a serverless dApp
  • ledgers.js used for fiat and crypto payments into an Ethereum smart contract
  • remuneration APIs called from Azure serverless as Logic Apps

Getting Started

Onboard

This ledgers.js library is client-side and abstracts ledgers (see figure above). Before using ledgers.js in your product, ensure to onboard with the ledgers.

overhide-ledger (dollars)

• register through live app for production
• register through test app for development and testing

Ethereum (ethers)

• generate a PKI pair on mainnet for production
• generate a PKI pair on Rinkeby testnet for development and testing

Bitcoin (bitcoins)

• generate a PKI pair on mainnet for production
• generate a PKI pair on testnet for development and testing

Distributable

⚠ Why is it so big?

We depend on web3.js which has bloat issues:

https://github.com/ChainSafe/web3.js/issues/1178

As soon as that gets resolved, this distro will be smaller.

The ledgers.js library 'dist' folder contains the distributable artifact.

You'll likely want to import the library along with its dependencies (web3.js).

Within your front-end projects; using npm simply: npm install ledgers.js --save-prod.

The ledgers.js library exports the oh$ object--it also sets a global oh$ object on window.

To bring in the oh$ object into your code using import:

import oh$ from "ledgers.js";
oh$.enable(token);
oh$.onWalletChange = ...

Enabling with Token

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.

CDN

You can include ledgers.js via CDN:

• https://cdn.jsdelivr.net/npm/ledgers.js/dist/ledgers.js
• https://cdn.jsdelivr.net/npm/ledgers.js/dist/ledgers.min.js

For a specific version, e.g. version 2.1.4: https://cdn.jsdelivr.net/npm/[email protected]/dist/ledgers.min.js

The library can be loaded straight into your HTML and accessed by its oh$ property in the globals:

<script src="`https://cdn.jsdelivr.net/npm/ledgers.js/dist/ledgers.min.js`"></script>

<script>
  oh$.enable(token); 
  oh$.addEventListener('onWalletChange', ...);
</script>

Keep in mind ledgers.js is meant to run with a DOM present--in a browser (not Node.js).

Ecosystem

ledger.js (source)(API) is part of a larger envisioned ecosystem called overhide. It works in tandem with the overhide Remuneration API.

The overhide remuneration API is meant to enable "ledger-based authorization" with fiat currencies and cryptos.

The ledgers.js library (source)(API) is an integral partner to the overhide Remuneration API, providing utilities and abstractions for for the browser-centric authentication and payment portions; to enable ledger-based authorization later in the service-code or backend.

The figure shows the overhide Remuneration API landscape and highlights ledger.js (source)(API) helping a Web app orchestrate a login from within a browser--the red outgoing arrows--as it interacts with the service code and APIs in the cloud.

Figure 2: Shows where ledgers.js fits within the overhide Remuneration API landscape.

Remuneration API

The overhide remuneration API is an API of two HTTP methods exposed by various ledgers (blockchain and otherwise):

• /get-transactions/{from-address}/{to-address}
• /is-signature-valid

These API methods are used by the ledgers.js library and explicitly called by the Service Code.

Test Environment APIs

For testing the library interacts with the Rinkeby Ethereum testnet and the overhide-ledger test environment.

The respective API instances used are the following test network nodes:

• ethers: overhide Remuneration API for Ethereum
• dollars: overhide-ledger--the renmuneration provider for US dollars
• bitcoins: overhide Remuneration API for Bitcoin

Use a Rinkeby faucet to get "test" Ether for playing around with the ethers portion of the library.

Use Stripe's "test" credit cards to play around with dollar transactions in the library.

Use a Bitcoin testnet faucet to get "test" bitcoins for playing around with the bitcoins imparter in the library. You'll need to use a wallet and — for best results — configure it to not use "change" addresses.

Production Environment APIs

To interact with the Ethereum mainnet, user your wallet.

To interact with the production overhide-ledger, visit https://ledger.overhide.io.

To interact with the production Bitcoin mainnet, use the Electrum wallet and configure it not to use "change" addresses (works best for ledger-based authorizations).

For production instances of all APIs see:

• mainnet Ethereum APIs
• Production overhide-ledger
• mainnet Bitcoin APIs

Additional Notes on APIs

The overhide-ledger Swagger documentation discusses some additional HTML/js getter endpoints particular to overhide-ledger and not part of the generic remuneration API. The ledger.js (source)(API) leverages these additional endpoints when it calls on overhide-ledger functionality. This is similar to how ledger.js (source)(API) leverages the web3.js library when working with ether.

build notes: see ./build.txt