Introduction to Overhide-Ledger and Ledger-Based Authentication

DZone 's Guide to

Introduction to Overhide-Ledger and Ledger-Based Authentication

Learn more about overhide-ledger and implementing ledger-based authentication.

· Security Zone ·
Free Resource

I'd like to introduce overhide-ledger, a centralized web 2.0 ledger of dollar transactions exposed through a minimal API.

The intent of the ledger is to enable a simple authorization workflow that's useful both today, for dollars, and tomorrow, for cryptos.

The overhide-ledger interface and APIs allow payees and payers to log their credit card transactions on a publicly visible ledger. The payees and payers appear on the ledger as Ethereum addresses: 42 character hexadecimal strings. These obscure identifiers are conjoined with dollar amounts and timestamps to complete respective entries.


The question of why such a ledger is useful needs to be considered in the context of the workflows it's improving. We will see that overhide-ledger improves software authorization workflows involving fiat money to match significant value-adds of authorization workflows possible with public key infrastructure from decentralized ledgers such as Ethereum and Bitcoin.

Before we get into discussing this "ledger-based authorization workflow" and contrast it with current web 2.0 approaches, we need to understand some concepts from the decentralized web. For this discussion, we need to understand the simple concepts of a ledger and it's respective public key infrastructure.

Some Basics From Crypto Ledgers

For our purposes, a ledger is as simple as a table with payers, payees, amounts, and timestamps.

payer payee amount timestamp
Fred Acme Co. $10 Yesterday
Mick Glopex Inc. $2 2 hours ago

For the needs of ledger-based authorization, we'll replace all the names with public addresses that those parties "own." We use Ethereum addresses.

payer payee amount timestamp
0xD32317b5651d9f9D636032aaD100D9d30F74481d 0x41340dF846177A02D5a16995E2Faf4917251d0dc $10 Yesterday
0xF00450C4cC9b46E837fb4feffE9e4FEdAAb94347 0xF60c97206C2DA2cad37B6Fd0B29BA33e043E2897 $2 2 hours ago

Fred, from the first ledger, is replaced in the second ledger by his pseudonymous Ehtereum address, the 42 character hexadecimal string: 0xD32317b5651d9f9D636032aaD100D9d30F74481d. This is Fred's public address in the ledger. It is an Ethereum compliant address, but the fact that it's generated with Ethereum libraries is immaterial. It's not limited to the Ethereum blockchain; we can use this address in other ledgers following Ethereum public key conventions — and we do, overhide-ledger uses Ethereum public key infrastructure.

Fred can prove he owns that address by having its corresponding secret key: e398cc1f41b6e00c88b7c625b81858aa89f6e1dea753203186ffa4c886497ee9. This is a 60-character hexadecimal string that is cryptographically tied to Fred's address. Fred never discloses this secret key. Fred only uses this secret key to prove he owns his address, and therefore, that it is he who made the $10 payment to whoever is 0x41340dF846177A02D5a16995E2Faf4917251d0dc (we know it's Acme Co.). To make this proof, Fred would use cryptography to "sign" some message — for example, today's date — into a "signature" with his secret key. Through cleverness of cryptography, anyone with whom Fred shares his address, this signature, and the original message can verify the signature's validity for the address; hence, Fred's possession of the secret key and ownership of the ledger address.

The significant takeaway regarding Ethereum public-key infrastructure —or that of any public blockchain ledger — is that public addresses have corresponding private secret keys for signing some message into signatures that equate possession of the secret key to ownership of the address.

Ledger-Based Authorization

Above, we introduced ledgers and the public-key infrastructure, which support a certain authorization workflow. In truth, the public-key infrastructure is the authentication portion and is nicely decoupled from authorization, which requires a ledger. This authentication is rooted solely in cryptographic algorithms and doesn't require a ledger — just appropriate software libraries.

Authorization very much requires a ledger as authorization dictates access level tiers based on money paid.

Without any further preamble, below is our preferred workflow.

Figure 1: Ledger-based authorization workflow.

The workflow starts at the top in the login client where a user logs in with their ledger address. This is where authentication happens without any need to actually contact the ledger. Usually, this authentication happens with the help of an in-browser wallet: The wallet helps furnish signatures for the address.

Although it's not strictly necessary to contact the ledger at this point, it's worthwhile if the user needs to transact with the ledger to make payments. Later down in the flow, we'll check for monies paid to authorize access tiers. There is no opportunity to pay money later on in the flow. Usually, transacting with the ledger is done through a wallet that is only available at this layer, in the browser, and in the login client.

Exiting the login client we pass the user's address, a signed message, and signature, to the service proper. The service prudently verifies the address against the signature and message. To prevent replay attacks it'd be additionally prudent for the service to issue the message in the first place--to be signed and returned--but we don't show such enhancements for simplicity.

Subsequently, the service authorizes the passed in address for some access tier. It contacts the ledger to retrieve a tally of transactions from the address to the service provider. The tally can take many forms; perhaps it's all payments in the last week. We could have different fee schedules for different tiers. It's simple and flexible.

There are several benefits to this flow.

The service doesn't need to know anything about the user or store any credentials, payment details, personal information.

There is a reduction of coupling between the service and its login client.

It can be reasoned about simply at a high level: if you have an address on ledger, you can authenticate; if you have the money paid on the ledger, you can authorize for higher access tiers.

But the main benefit is suggested with the green blurb on the right of the diagram: the mention of how overhide remuneration APIs can abstract any ledger to enable this authorization flow. The significance here: a single implementation in code can leverage any currency. Any cryptocurrency — and with overhide-ledger — dollars.

And regarding fiat currencies? The overhide remuneration API is covered in detail in a section below. We'll get to that after we have a brief look at a typical Web 2.0 fiat authorization workflow, to contrast with what we just saw.

Typical Web 2.0 Authorization

To contrast the preferred authorization flow in the previous section, we model a typical Web 2.0 auth flow below.

Figure 2: Web 2.0 authorization flow

We again start at the top. This time the login client uses some form of social login: Twitter, Facebook, LinkedIn, and Google.

The social login provider vets user authentication credentials on behalf of the service they're trying to use. Not only does this mean the social login provider gets to learn a lot about the users logging in, but this login provider is now very much in the critical-path of users' access to the unrelated service they're trying to use. The users expect the login provider to outlive the service's usefulness to them.

Beyond login ownership, the login provider doesn't deal with authorizations. If the service is to support authorization tiers based on monies received, it necessarily needs to hold and be privy to personal information of its users.

The service provider has to get into the business of collecting information about its users if it desires remuneration. This, whether it needs the information for the service's value-add or not.

We do recognize that this collection of information is in-fact desirable to many service providers. We operate in a milieu where hoarding information about users is a boon. But increasingly, month to month, it's a burden. The software developer has to decide where they want to derive value and how much responsibility they want to shoulder.

Remuneration APIs

As seen in a previous section the ledger-based authorization flow is attractive and we would like to use the same libraries and the same code flow for multiple currencies. The green blurb in figure 1 indicated that this is where the overhide remuneration API shines.

The model below shows where the overhide remuneration API sits in reference to ledgers, wallets used by login, and the service code.

Figure 3: Currencies abstracted by overhide remuneration API

As the note on the service code suggests, only availability of HTTP is necessary to provide our preferred authorization flow for the service.

Each ledger — Bitcoin, Ethereum, or overhide-ledger for dollars — expose their own identical API: They have a proxy implementing the same identical interface. The login page need merely indicate the user's address from one of the supported ledgers and the corresponding API URL. The service code needs to look up different fees scheduled for each currency supported, but other than that, these are the only variables in an otherwise common flow.

There are only two methods in this API:

  • Get transactions/tallies
  • Verify identity

The APIs for Ethereum are made available by the overhide-ethereum remuneration provider.

The APIs for dollars are made available by the overhide-ledger remuneration provider.

Bitcoin, tether, EOS, and others are yet to be implemented, hopefully, more with community help: These APIs can be implemented for any cryptocurrency.

Similarly, overhide-ledger could be stood up for other fiat currencies other than dollars.

Making this API abstraction available for fiat currencies and enabling ledger-based authorization with either type of currency is the whole purpose of overhide-ledger.

Making this API abstraction available for fiat currencies and enabling ledger-based authorization with either type of currency is the whole purpose of overhide-ledger.

From Login Client to Service Business End

With reference to figure 3 above, note that:

  • The login page is decoupled from the business logic service
  • Login page interacts with ledgers to view transactions and create payments on the ledger
  • Payments to ledgers are through wallets
  • Authentication occurs at the login phase without necessarily using any ledger, by simply signing a public address
  • This layer is likely in the browser while the business end is in native code or some back-end
    • Consider that even video games — beautifully rendered with 3D engines — often use the browser for account management
    • You're not hurting yourself creating ledger transactions using a browser in the near future, as it supports a plethora of wallets
  • The service can be on any software stack as long as supports HTTP calls
  • Authentication and authorization don't need a browser: simple HTTP API can be called from any software stack
  • Authentication and authorization can be abstracted for most ledgers, keeping the core app code the same despite ledger in use


Before diving any deeper into describing overhide-ledger, the concepts just described may become more tangible through a demo meant to help developers see the approach in a "real" application.

We have a functioning demo "game" with a sample login page. The login page allows either a free account login or value-add, pay-for tiers. Payments in this game can be made using either ether or dollars.


We've motivated the ledger-based authorization flow and mentioned that overhide-ledger enables it for dollars.

Figure 4: Overhide-ledger for fiat dollar transactions

The ledger sits in the cloud, as indicated by the bold arrows.

The ledgers.js library sits in the browser. It is used by your browser's JavaScript in the same abstracted fashion, regardless of remuneration provider. The linked demo shows this in action.

ledgers.js and overhide-ledger comprise a tool-set to aid developers in leveraging ledgers for authorization, while providing a "lubricant" to app users' transition from paying for services in dollars to paying in cryptos. This further showcases the benefits of cryptos, such as pseudonymity and lower transaction cost.

By using ledgers.js and overhide-ledger; developers future-proof their code.

What Does overhide-ledger Do?

We have covered enough about the why; let's get into the how.

To understand what overhide-ledger does, let's compare how transactions are added using a dollar payment, specifically a gateway versus a decentralized ledger like Ethereum. The overhide-ledger approach borrows from both.

Figure 5: Payment-gateway transaction in dollars

Figure 5 shows two related flows. The top flow is a service provider registering to receive payments. Since we're dealing with a payment gateway, such as PayPal or Stripe, the service provider goes through several layers of forms and verification. At the end of this process, the service provider has an account with the payment gateway that can receive funds using any number of methods such as credit cards.

The bottom flow in figure 5 is a user making a payment. The payment process uses the service provider's account ID to receive a requested amount. The payment gateway is a black-box, taking care of a lot of the heavy lifting with card issuers and banks. After a little data entry on the user's side, the service provider receives their fee and the user gets a confirmation.

All the steps in figure 5 are abstracted by overhide-ledger and furnished by ledgers.js so that the developer doesn't need to implement them. The overhide-ledger necessarily handles these bits as it needs to inject itself into the process so as to capture the values in green:

  • account ID
  • amount

The values in green — account ID and amount — are retrieved from the payment gateway workflow and used with additional cryptographic bits from a blockchain, like transaction workflow to comprise a complete overhide-ledger entry.

Figure 6: Transaction in on a decentralized ledger like Ethreum

Before we get too deep into this workflow, consider that the account ID and amount from figure 5 are shown being injected from the upper right corner.

The top flow in figure 6 is, once again, part of service provider registration. When using the overhide-ledger, this top flow and the top flow in figure 5 are done behind the scenes at the same time. Here, the flow furnishes a provider address from either an Ethereum wallet or freshly minted from an Ethereum library.

The bottom flow is a user transacting on the ledger. The last green attribute results from this flow, the user address.

Consider for a moment that figure 6 actually represents a decentralized blockchain transaction. If you ignore the injection of account ID and amount from the top right, and consider the crossed-out bits in red, you actually have a model of a transaction being signed and sent to an Ethereum node.

But since this isn't a blockchain transaction, it's an overhide-ledger transaction, it's not a blockchain-node that processes a transaction from the user to the service provider, making funds available as unspent transaction outputs or ledger account balances. Instead, it's a centralized overhide-ledger that uses most of the same process until it's time to write to the ledger. At that time, it only uses the addresses and the signing from the flows in figure 6. The ledger doesn't have decentralized nodes, leaving those bits crossed out in red. The four attributes in green from figures 5 and 6, in addition to a timestamp, constitute a complete ledger entry:

  • provider address
  • user address
  • amount
  • timestamp

The account ID is not part of the entry. There is a separate mapping from provider address to corresponding account ID.

The ledger itself doesn't store user identifying information; it does store a hash of the user's email.

The ledger does necessarily store the payment-gateway account ID of the service provider.

There is no anonymity or decentralization here, but we've enabled ledger-based authorization with dollars.

Please be aware that the overhide-ledger functionality discussed above in this section is closed source and has a pending US PTO application (No. 62817820) "PSEUDONYMOUS FIAT CURRENCY TRANSACTION LOGGER SYSTEM AND METHOD FOR PAYMENT GATEWAYS".

Differences From Blockchain

For completeness, let's enumerate some obvious differences between overhide-ledger and blockchain ledgers.

First, there is no pseudonymity between the payee and the payer; they know more details about each other. The overhide-ledger doesn't get involved with those personal details; they are relegated to the payment-gateway. But the two entities do interact.

Although pseudonymity is reduced for the parties involved in a transaction, the public, at large, still just sees a ledger with hashes.

It might have been more appealing to have overhide-ledger be an abstraction between the payee and the payer and have each deal solely with overhide-ledger segregated from each-other. Although, with that approach, the ledger would know more about the entities, and the entities would be more pseudonymous to each other. Unfortunately, since we're not dealing with cryptos where a transaction is a final word, this would open the ledger to risks of chargebacks, returns, and other problems.

Further, because of the possibility of chargebacks and refunds, the service provider necessarily needs the ability to mark transactions "marked as void by provider:" flagging a transaction on the ledger as no longer valid. The transaction is not removed from the history, but it is flagged as void.

While we're at it, since we already removed quite a few value-adds of blockchains to make the ledger compatible with the world of fiat money transfers, we might as well provide a pseudo-password-reset. Since the overhide-ledger hashes email addresses of users, it can — provided said email from the said user — allow a user to rewrite a transaction to appear from a new cryptographic key-pair — a password reset, if you will.

So, at the end, who knows what is in the overhide-ledger?

  • Stripe knows both parties intimately
  • overhide-ledger knows of both parties
  • The payer can prove ownership of their public address
  • The payee can prove ownership of their private address
  • Everyone knows the pseudonymous payment was made for all time

Community Needed

At this point, as app and service developers, we have:

We want the ecosystem to grow, and for that, we need to implement more remuneration providers and more implementations of the overhide remuneration API.

Lastly, it's worth mentioning that all of this is written because of the need for authorization in a data-broker I specced out to write together with the open-source community: https://overhide.io.

All of the documentation for the data-broker can be found on GitHub. Currently, we are working towards a minimally-viable product before putting the broker reference implementation on GitHub.

authentication, authorization, crypto, dlt, dollars, ethereum, ledger authentication, ledger-based, security, stripe

Published at DZone with permission of Jakub Ner . See the original article here.

Opinions expressed by DZone contributors are their own.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}