A Quick Guide: How to Use a SOFIE Federation Adapter in a Datahub

Written by Mait Märdin, Margus Haavala, Priit Anton, Guardtime

Guardtime has discussed the challenges and opportunities of more accessible consumer metering data in a previous blog post. We still see that cross-border open data exchange remains a dream to pursue and with our decentralized energy data exchange (DEDE) pilot, developed in the SOFIE project, we have implemented a novel approach to make this dream come true. In this blog we will describe the design decision behind the DEDE adapter and present hand-on instructions for offering and connecting services.

While designing the system for DEDE, we focused on decentralized governance and operational mode, because running cross-border data exchange through centralized entities would limit the transparency and platform dynamics. In our solution, the peer-to-peer nature of data exchange provides possibilities for large scale and diverse communication options, providing wider implementation and extensibility details.

The communication protocol of DEDE is designed to provide and consume arbitrary services. All of the communication is secured by default. Most importantly, the protocol solves the problem of identifying, authenticating and authorizing nodes that provide and consume services. By default, Hyperledger Indy is used as the trust anchor for node identity. It’s a digital identity solution based on distributed ledger technology and offers an authentication and authorization mechanism by utilizing verifiable credentials. Decentralized Identifiers (DID) enable verifiable and decentralized identity. A verifiable credential (VC) is a tamper-proof credential, which is digitally signed by the issuer. Entities that use the DEDE adapter are identified by DID-s, which form the base layer for verifiable credentials that are used to make authorization decisions in the Federation Adapter (FA). Through verifiable credentials end users are put in the control of their energy consumption data.

Figure 1. Federation adapter interaction with entities

FA is a software component that handles interoperability and provides secure communication between other entities that use DEDE adapters (Figure 1). It acts as a forward proxy for the data consumer and as a reverse proxy for the data provider, but it can also be in both roles at the same time, enabling entities that are both data consumers and data providers.  

Data access with DEDE

The energy metering data is gathered together by utility providers that control the smart meter infrastructure. Whether the data remains under local region control or is collected nationally to centralised datahubs, the challenge remains the same - how to share the data to a vast variety of energy service providers that enable efficient energy consumption, automation of your smart home devices and control your solar panels and battery storage? This challenge is world-wide. One example of an approach to solve this is the green button initiative by the Green Button Alliance (GBA) in the US, where they are working to unlock the access to utility interval usage and billing data in an easy and secure way. Taking into account the specific demand for data privacy, the DEDE adapters are addressing the data access challenge similarly to GBA in Europe.

Example implementation and hands-on instructions

Let's take an example where smart meter infrastructure is set up and provides data to a regional datahub, operated by the France EDF energy company. Let’s imagine that there are four new energy retailers entering the region, who require energy consumption data from the operator. The datahub operator has the 30-minute interval data available via RESTful APIs (Open API for data services used) to 3rd parties. Now the system administration has the task to connect the four energy retailers to get access to customer data.

The problem arises from dealing with the access control of each single smart meter data point. As the customer data, communication and consents are divided between each retailer's Customer Relationship Management (CRM) and the Datahub CRM, there is a need for separate integration to each system. In addition to the initial integration challenge, maintaining the systems during the operation, development and upgrades, is also problematic. These obstacles are easily tackled by using the DEDE adapters as a means for data access and governance. After a discussion between Guardtime and aforenamed Datahub operator the following steps can be undertaken to use DEDE adapters for providing data access to energy retailers:

  • Guardtime provides the DEDE adapter software and support during the pilot.

  • Guardtime provides initial test scenarios that can be executed.

  • Data operator sets up a test environment

After these preliminary steps are concluded, the demonstration from the sysadmin side can start.

Firstly, the sysadmin receives the DEDE adapter and its installation guide. Using the installation package from Guardtime the adapters are installed and preliminary setup of the DEDE adapter is done.

When the adapter is installed and running, the sysadmin, operating the datahub for energy metering data, creates a simple service and describes it according to the OpenAPI 3.0 specification:

  openapi: '3.0.3',
  servers: [
      url: 'http://localhost:8888/'
  paths: {
    '/hello': {
      get: {
        operationId: 'sayHello'

After that this service (metering data feed) is introduced to the new DEDE adapter. From the test environment side there is a server at http://localhost:8888 that provides data service, and the above service description available at http://localhost:8888/open-api-docs. To import, sysadmin chooses a DID that is going to provide data service. By default, there is just one DID generated for each Federation Adapter and this will be used:

Next, the sysadmin will set up a possible client side (one of the four energy retailers), who is also running the Federation Adapter. In the current demonstration the sysadmin from the energy datahub’s side will set up and execute both sides: the datahub adapter and the retailer adapter (client to access energy data). This retailer’s side adapter has learned the DID of the service provider (datahub) and wants to see what services it offers. The sysadmin sets the the retailers adapter side up from the Federation Adapter UI:

Now the client (retailer accessing the data) knows that there is a service provider with DID Wom7aZLyX366W9oTrX34tA who offers a service at path /hello. Retailer side can execute the service by sending a request to his own Federation Adapter (at http://localhost:8001) as follows:

$ curl http://localhost:8001/proxy/Wom7aZLyX366W9oTrX34tA/hello
  "code" : "server:proxy",
  "message" : "Internal error: Request not allowed"

The response is an error message from the service provider Federation Adapter, telling sysadmin, that the request was not allowed. The service provider (datahub) forgot to configure the permissions for this service, so the retailer side cannot get access. The scenario is that sysadmin just wants to allow access to this single retailer with DID 2oVmBfCM5yG7mkcLFwepFD. He can do this from his Federation Adapter UI by allowing that specific source DID for the only service provided by the datahub:

The retailer adapter side can now try to execute the service again:

$ curl http://localhost:8001/proxy/Wom7aZLyX366W9oTrX34tA/hello
Hello, World!

This time accessing the service worked. From the sysadmin side, as a datahub service provider can check the log to see who has used his service and to download the requests signed by the client:

From the log sysadmin can see that the client has also sent requests for GET /services. This is a meta-service to get the service description and is implemented by the Federation Adapter itself.

Evaluation of using DEDE

From the sysadmin perspective, the specific tasks of granting, denying, revoking access and providing backlog as evidence was a success. DEDE adapters can be used for governance control. From the retailer’s perspective DEDE adapters enabled the access to data service, after the first attempt was unsuccessful. Our EDFs energy company example use-case shows that SOFIE DEDE adapter can play the role of gatekeepers using dedicated identifiers and credentials to be applied in an energy data sharing environment. The adapter installation was a success and using the OpenAPI 3.0 data access DEDE adapters together, worked. As a result, the sysadmin also acquired the possibility to share the smart meter data to different service providers when they all use DEDE adapters.

This was one example to showcase how SOFIE federation adapters could offer data access and governance control to the datahubs from a sysadmin’s perspective. We are eager to provide you with more examples in the near future. If you would like to participate in this kind of experiment yourself or have additional questions about the pilot, please contact us.

Contact us: Priit Anton,, Guardtime
Illustrations by Guardtime