Win $20,000. Help build the future of education. Answer the call. Learn more

Oracles: Common architectural patterns for Hyperledger Fabric

In a previous article, we showed you two mechanisms for implementing off-chain logic that maintain trust, visibility, and transparency as qualities of service for a blockchain network. The first approached extended smart contracts by having peers in the blockchain network invoke third-party services collocated with them, while the second approach extended smart contacts by having these invoke a third-party trusted service that resides outside of the blockchain network. These third-party trusted services are commonly referred to as oracles. In this article, we explore the second approach further by presenting three common architectural patterns that can be used in the context of a Hyperledger Fabric network.


To get the most out of this article, you should be familiar with blockchain technology, specifically the Hyperledger Fabric platform. If you are not familiar with Hyperledger Fabric and blockchain concepts, there are lots of other great online resources that can help you to take advantage of this material (see the Resources in the right nav).

Estimated time

You should probably allocate about 10-15 minutes to read this article.

Origins of the oracle

The word “oracle” originates with the Latin word “oraculum,” which means divine announcement. In ancient times, such announcements were delivered by these so-called oracles, and because they were considered divine everyone tended to trust them. No matter how events turned out, people did not usually doubt oracles, preferring instead to assume that their own interpretation may have been faulty. Oracles were clever people who always made sure that their prophecies had enough room for interpretation. What makes the oracle concept interesting and applicable to blockchain is that the trust people placed in their oracle stemmed from the fact that once the oracle made a prophecy, they could not easily change it. Changing a prophecy after the fact would essentially render an oracle as a fraud.

From a blockchain perspective, an oracle can be expressed as a function, which given a tick value will always return the same fact along with a proof of the fact:

Figure 1. Expressing an oracle as a function

Expressing an oracle as a function

Returning the same value for the same input is great from a blockchain perspective! This means you get a deterministic function that can be safely called from a smart contract (at least in theory).

It’s worth noting that while the remainder of this article is focused on architectural patterns that support the integration of oracles, there can be serious business and legal ramifications to the use of oracles. Will every party truly trust the oracle? What about situations where parties disagree on the value? As such, the inclusion of an oracle in a blockchain network should be addressed and reflected when defining the trust framework. Terms and conditions should clearly spell out that members of the network recognize the validity of the external system, and should also cover the dispute process.

Looking at the oracle patterns

Now that we have a basic understanding of the concept of an oracle, and understand that this is not only about technology but it needs to also encompass business and legal aspects, let’s turn our attention to three architecture patterns that can be implemented on top of Hyperledger Fabric.

Hosting an oracle on a global channel

This is probably the most natural way to implement the concept of an oracle within Hyperledger Fabric. Essentially, this approach relies on the concept of having an organization (the data source org) in the network be responsible for maintaining a ledger of “facts” that other organizations can query to retrieve a point-in-time value. Figure 2 depicts a smart contract that is deployed on a global channel and provides an update and a query transaction. In this model, only the data source org is authorized to invoke the update, and the other organizations are allowed to invoke the query.

When invoking the smart contract on a separate channel, the smart contract can leverage the cross-channel query capability to retrieve the latest value. The fact that the value is recorded on the ledger provides an auditable trace of the fact.

Figure 2. Smart contract deployed on a global channel

Smart contract deployed on a global channel

The tick parameter is stored as the key within the ledger and the facts are the value part of the key-value. The proof of the fact is essentially the transaction that is stored on the ledger containing the data source organization signature.

In this model, there is a risk that not all possible tick values are stored on the ledger. For example, when dealing with stock price, it might not be realistic to store all data points on the ledger. There are two possible approaches to dealing with this situation:

  1. The data source organization updates the ledger at a predefined frequency that’s agreed upon through the network governance model.
  2. Organizations send a direct (REST-like) request to the data source organization to update the ledger for a specific tick value. The data source organization then retrieves the correct and corresponding fact and stores it on the ledger.

Smart contract invokes external, trusted data source as the oracle

In this architectural pattern, the data flow starts with the client application submitting a transaction proposal to the blockchain network as shown in Figure 3. As with any transaction proposal in a Hyperledger Fabric network, this results in the invocation of a smart contract. As you may know, it is the responsibility of the client application to ensure that the transaction proposal is sent to the necessary organizations/membership service providers (MSPs) as specified in the endorsement policy. In addition, an endorsement policy may require peers from several organizations to execute the smart contract in order to achieve consensus.

As a side note, with the release of Hyperledger Fabric v1.2, client applications will no longer need to hard code the organizations/MSPs to which transaction proposals must be sent. Instead, they can leverage a discovery service to compute such information at run time. (For more details, see the Fabric docs.)

Regardless of which mechanism the client application uses to submit a transaction proposal, it is unaware that the smart contract may invoke an oracle service during its execution.

Figure 3. External system call

External system call

In Figure 3, the oracle service is depicted by the data source org component, which resides outside of the blockchain network. During the execution of the smart contract (which, as mentioned earlier, occurs during the transaction proposal phase), all endorsing peers invoke the data source org service in order to obtain the necessary data before consensus can be achieved. The data source org service has access to any data repositories and/or additional services it may need to engage in order to provide a deterministic answer to each smart contract invocation from the blockchain network. There are two possibilities:

  1. The tick value is discrete enough to allow the data source organization to return a deterministic value.
  2. There can be multiple valid responses for a specific tick (such as using a time value that’s precise to the minute to only retrieve a stock value).

In the second case, to guarantee determinism across all invocations that occur within the boundaries of a same transaction, a unique representation of the specific transaction is provided as input to the oracle service from the smart contract. This identifier allows the data source org service to correlate requests that are bound to the same transactional context, and thus ensure consistency in its response to the smart contract.

It is also the responsibility of the data source org service to sign its response so it can then be verified within the smart contract. Upon a successful invocation of the data source org and a successful validation of its signature, the smart contract resumes its execution and any necessary updates to the ledger occur.

Note that the oracle service should gather any necessary data and make any required computations for building its response without introducing significant latency to the transaction. Otherwise, the blockchain transaction proposal could timeout, which would result in a failure and, consequently, consensus wouldn’t be reached. Also, in this architectural pattern, organizations must allow their endorsing peers to establish outbound connections from the Fabric network to an external resource — in this case, the data source org service.

Verifiable credential as source of facts

Before discussing this architectural pattern, we should first go over the following concepts:

  • Verifiable credential — A tamper-proof and cryptographically signed statement made by one party about another party. A verifiable credential can be made about an individual or an entire organization. Some examples would be: the physical address of a company, the university degree a person has obtained along with their GPA score, a person’s date of birth, or the type of business a given organization runs (for example, Acme Ads is in the advertising industry and runs ad campaigns on behalf of other companies).
  • Issuer — The organization that issues credentials for a person or another organization. For instance, the Department of Motor Vehicles (DMV) agency at the state level (in the U.S.) follows a verification process for issuing driver’s licenses to residents. Each issued driver’s license contains claims about the person’s identity such as their address and date of birth. Therefore, a DMV agency is an example of a credentials issuer.
  • Holder — The organization/person who is targeted by the claim.
  • Inspector-Verifier — The organization that wants to validate the claim.

In this architectural pattern, the data flow can be split into two separate but related phases. In the first phase, the client application obtains one or more verifiable credentials from an issuer and keeps them safely stored away (think of an electronic wallet) until needed. In the second phase, the client application submits one or more transaction proposals to the blockchain network, where each one of these proposals expects to receive one or more verifiable credentials about the identity of the client as parameters. For instance, let’s assume that the client application needs to submit a transaction proposal that requires, as verifiable credentials, the physical address and the client’s line of business. In such a case, the client application can provide the verifiable credentials that it had previously obtained from the issuer as input parameters to the smart contract.

Upon receiving the credentials, the smart contract, acting as the inspector-verifier, determines whether the organization that issued them is a trusted party and validates the signature of the credentials (remember that verifiable credentials are cryptographically signed by the issuer). The smart contract either already has the public key of the issuer or has the means to find their corresponding public key by, say, performing a lookup against a decentralized key management system or a distributed storage that holds keys of registered, trusted parties. If the smart contract determines that the credentials were indeed issued by a trusted party, the smart contract continues its execution with the next set of business rules encoded in it. On the other hand, if the credentials were not issued by a trusted party, the smart contract terminates and aborts the execution of the transaction proposal.

This scenario is depicted in Figure 4.

Figure 4. Verifiable credentials

Verifying credentials

Note that in the flow described above, the smart contract validates the credentials without communicating with the issuer. But could there be a use case where the smart contract communicates with the issuer? If credentials can be revoked and there is a business requirement to ensure that verifiable credentials provided as parameters to the smart contract are still valid, then the smart contract should conduct a revocation list check.

There are a couple of ways this can be done…

1. Inspector-verifier contacts the issuer

The smart contract can contact the issuer to determine whether the verifiable credentials are included in the revocation list. If so, then the smart contract aborts the transaction since the received credentials are deemed no longer valid. If the issuer’s response confirms that the credentials are not found in the revocation list, the smart contract proceeds with its execution. It is worth mentioning that issuers should not use a revocation list check as a way to correlate verifiers (meaning, organizations validating whether credentials are valid) with the entity or party that owns the credentials. If issuers did this, it could result in information leakage that leads to a privacy violation of the organization or entity that holds the verifiable credentials.

2. Holder of the verifiable claim provides proof of non-revocation to the inspector-verifier

In this model, the holder retrieves the revocation list and uses the list to generate a proof that the verifiable claim has not been revoked. When invoking the smart contract on the Hyperledger Fabric network, the holder provides both the verifiable credential and the proof of non-revocation. The smart contract can then use the proof to validate that the verifiable credential is still valid.

The second option relies on the concept of a cryptographic accumulator and the fact that revocation lists can leverage that concept and the accumulator can be stored on the ledger. By avoiding contact with the issuers, the holder’s privacy is protected and the inspector-verifier can quickly assert the validity of the credentials. For more on the concepts behind this approach, read How credential revocation works.

Therefore, in the context of the architectural approach described in this section, a credentials issuer plays the role of an oracle by indirectly providing a verifiable credential to the smart contract.


In this article, we showed you three different architectural patterns that extend smart contacts by leveraging a third-party trusted service, which acts as an oracle. In the first approach, the trusted party service has a membership in the blockchain network and utilizes a channel to make its data available to all members of the network. In the second approach, all members of the blockchain network agree to trust and leverage a third-party service by making invocations to it from within the smart contracts. In this context, data inputs to the third-party service are used to correlate invocations that occur within the same transaction and, thus, guarantee determinism. In the third and final approach, a claims issuer serves as the oracle by issuing verifiable credentials to entities, which are then corroborated during the execution of smart contracts. Client applications provide the necessary claims as inputs to smart contracts, and these then validate the authenticity of such claims by verifying the signatures.

It is worth mentioning that given the flexibility provided in the Hyperledger Fabric platform, all the architectural patterns presented here can be used in the context of a Hyperledger Fabric network.

Finally, please be aware that the inclusion of a third-party data source into a business network is not trivial. You should consider the impact it can have on the governance model and the additional technological dependencies it can introduce to your solution.