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.
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.
For more information, videos, write-ups, please visit https://overhide.io.
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
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.
- generate a PKI pair on mainnet for production
- generate a PKI pair on Rinkeby testnet for development and testing
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 = ...
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.
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).
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.
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.
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:
- ether: overhide Remuneration API for Ethereum
- dollars: overhide-ledger--the renmuneration provider for US dollars
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.
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:
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