Skip to content

JavaScript library for ledger-based authorizations :: abstracting different ledgers to be used in an application's authentication and authorization workflows.

License

Notifications You must be signed in to change notification settings

overhide/ledgers.js

Folders and files

NameName
Last commit message
Last commit date
Jan 18, 2021
Mar 22, 2019
May 15, 2019
Apr 25, 2021
Apr 25, 2021
Apr 19, 2021
Apr 25, 2021
Mar 21, 2021
Apr 24, 2019
May 7, 2019
Mar 22, 2019
Sep 24, 2019
May 6, 2019
Apr 12, 2021
Jan 19, 2021
Jan 19, 2021
Apr 18, 2021
Apr 25, 2021
Mar 23, 2021

Repository files navigation

overhide.io

A free and open-sourced (mostly) ecosystem of widgets, a front-end library, and back-end services — to make addition of "logins" and "in-app-purchases" (IAP) to your app as banal as possible.


ledgers.js

npm version CircleCI

This repository is the distribution of the ledgers.js library (source)(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.

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:

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

Distributable

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/ledgers.js@2.1.4/dist/ledgers.min.js

The library depends on web3.js, as such you must include the dependency (see first line in example below).

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

<script src="https://cdnjs.cloudflare.com/ajax/libs/web3/1.3.4/web3.min.js" integrity="sha512-TTGImODeszogiro9DUvleC9NJVnxO6M0+69nbM3YE9SYcVe4wZp2XYpELtcikuFZO9vjXNPyeoHAhS5DHzX1ZQ==" crossorigin="anonymous"></script>

<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:

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

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

Production Environment APIs

To interact with the Ethereum mainnet, user your wallet.

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

For production instances of both APIs see:

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