Smart contracts, Wallets & Accounting – System Specifications

Figure 1 – i3-MARKET building blocks and main tasks dealing with them

As depicted in the grant agreement, and more clearly in Figure 1: i3-MARKET building blocks and main tasks dealing with them, the subsystem are:

  • Smart Wallet
    • I3M-Wallet App. The i3-M Wallet App is a desktop application that will be operated by the end-user of the i3-MARKET federation. It handles the interaction of the end-user with the different backplane services, including but not limited to the identity and access management system. The wallet stores cryptographic material and verifiable claims. Two implementations will be provided for the end of the project.
      • HW Wallet. Hardware wallets are key wallets in charge of storing the user’s private keys using a physical device as storage. HW wallets satisfy the highest security policies since the key are safely stored and not accessible without holding the hardware.
      • SW Wallet. Software wallets store and manage user’s private keys on the storage of a general-purpose device (e.g. computer or smartphone). It is a good option for a less strict security policy that could be more convenient for daily usage.
      • Wallet Vault Server. Since wallets are key components that store necessary elements (keys and verifiable claims) for interacting with the i3-MARKET ecosystem, a Wallet Vault Server will be created to store on the cloud a backup (or a recovery process) for the verifiable credentials and/or cryptographic material. This fact indeed makes the i3M-Wallet a convenient “Cloud Wallet” that is easily accessible from any end-user location.

  • Smart Contracts Manager. The Smart Contracts Manager provides a gateway to access the smart contracts of a blockchain which it is used by many other subsystems to integrate their functionalities. The smart contract manager should be able to read the semantic description of the SLAs in order to invoke the necessary smart contracts (identity, payments, accounting, conflict resolution).

  • Explicit-user consent. Using smart contracts, the data owner is able to grant permission to providers to distribute its own data. That procedure guarantees that the GDPR regulation is properly applied.

  • Auditable accounting. Auditable accounting relies on the Blockchain capability of auditing to keep registries of any important operation. This includes implementing the ‘Know Your Customer’ (KYC) regulations.

  • Conflict resolution. Decentralized applications allow logging and audit interactions with blockchains reliably. This fact makes operations traceable and facilitates to identify fraudulent behaviours and to resolve issues or disputes. Smart contracts can assist the conflict resolution process and totally or partially automate it.

i3-MARKET Wallet

i3-M Wallet is a set of technologies that facilitate the management of their identity to all the actors of the i3-MARKET environment (provider, consumer, data owner, etc).

Technical Requirements

NameDescription
DID ManagementA decentralized system which enables several key actions by three distinct entities: the Controller, the Relying Party, and the Subject.
Controllers create and control DIDs, while Relying Parties rely on DIDs as an identifier for interactions related to the DID Subject.
The Subject is the entity referred to by the DID, which can be anything: a person, an organization, a device, a location, even a concept. Typically, the Subject is also the Controller.
Verifiable Credentials ManagementVerifiable Credential is a tamper-evident credential that has authorship that can be cryptographically verified though a proof.
It can be used to share and prove something about the identity of a User.
Table 1 – i3-MARKET Wallet Epics

NameDescription
Create DIDAs Subject I want to create a DID so I can manage my identity
Subject: Data Consumer, Data Provider, Data Owner
Present DIDAs a User I want to present my DID to a Relying Party so that I can identify myself
User: Data Consumer, Data Provider, data Owner
Relying Party: Data Marketplace, Data Provider
Rotate DIDAs a User I want to change the ownership of my DID so that I can maintain my Identity if I change Identity Provider
Delegate DIDAs a User I want to delegate my DID so that I can make other DID able to act on behalf of me
Recover DIDAs a User I want to recover my DID so that I can maintain my Identity even if I lose my proof of control
User: Data Consumer, Data Provider, Data Owner
Sign AssetsAs a User I want to sign my assets so that I can demonstrate the authenticity of the asset
User: Data Consumer, Data Provider, Data Owner
Verify Asset SignatureAs a User I want to verify asset signature so that I can authenticate the asset
User: Data Consumer
Deactivate DIDAs a User I want to deactivate my DID so that I can delete my Identity
User: Data Consumer, Data Provider, Data Owner
Resolve DIDAs a Data Marketplace I want to resolve DID so I can retrieve from DID Document the information to authenticate DID Subject and verify data asset signature
Authenticate DIDAs a Relying Party I want to authenticate DID so I can verify DID ownership
Relying Party: Data Marketplace/Data Provider
Table 2 – DID Management

NameDescription
Receive Verifiable CredentialAs User I want to receive a Verifiable Credential so I can access Data Marketplace
Verify Verifiable CredentialAs User I want to receive a Verifiable Credential so I can access Data Marketplace
Share Verifiable CredentialAs User I want to share a Verifiable Credential so I can attest something towards Relying Party
Store Verifiable CredentialAs User I want to store a Verifiable Credential so I use keep it and use it towards any Relying Party
Keep track of issued Verifiable CredentialsAs a Issuer I want to keep track of issued verifiable Credentials so that I can monitor and revoke them
Revoke Verifiable CredentialAs an Issuer I want to revoke a Verifiable Credentials so that it cannot be used
Table 3 – Verifiable Credentials Management

Architecture

The i3M-Wallet consists of a set of packages that enable a user to manage his/her accounts and use them to authenticate.

Wallet Desktop

Wallet Desktop is a cross-platform facility tool that eases the communication between a wallet (software or hardware) and the i3-MARKET SDK via an HTTP API. Furthermore, it provides some features like wallet synchronization using a secure cloud vault. It also has a user interface (UI) to display the information of the selected wallet and ask for user consent if any wallet operation needs it. An initial design of the main window can be seen in Figure 2 – Wallet desktop initial UI design.

Figure 2 – Wallet desktop initial UI design

The HTTP API launched by the wallet desktop is not accessible from the cloud so to use it the i3-MARKET SDK must in the same machine. This API is specified using OpenAPI Specification (OAS) within the package Wallet desktop OpenAPI (see Section Wallet Desktop OpenAPI).

To ease the development of a cross-platform UI, wallet desktop uses Electron, a framework that relies on Chromium web browser to create native applications using HTML, CSS and JavaScript.

Wallet Desktop OpenAPI

The Wallet Desktop OpenAPI (source code on GitLab) defines the HTTP API of Wallet Desktop (see Section Wallet Desktop). For more information on the OpenApi Interface go to de section Interface Description.

Base Wallet

This package defines how to interact with wallets by means of a typescript interface. Furthermore, it provides a default implementation called BaseWallet (source code on GitLab). It uses an interface walled KeyWallet to delegate the complexity of key management to other packages like SW Wallet (see Section SW Wallet). Both interfaces are listed below.

export interface Wallet {

/**

* @throws Error

*/

wipe: () => Promise<void>

// Api methods

accountList: (queryParameters: WalletPaths.AccountList.QueryParameters) => Promise<WalletPaths.AccountList.Responses.$200>

accountCreate: (requestBody: WalletPaths.AccountCreate.RequestBody) => Promise<WalletPaths.AccountCreate.Responses.$201>

accountSign: (requestBody: WalletPaths.AccountSign.RequestBody) => Promise<WalletPaths.AccountSign.Responses.$200>

accountVerify: (requestBody: WalletPaths.AccountVerify.RequestBody) => Promise<WalletPaths.AccountVerify.Responses.$200>

accountEncrypt: (requestBody: WalletPaths.AccountEncrypt.RequestBody) => Promise<WalletPaths.AccountEncrypt.Responses.$200>

accountDecrypt: (requestBody: WalletPaths.AccountDecrypt.RequestBody) => Promise<WalletPaths.AccountDecrypt.Responses.$200>

resourceList: (queryParameters: WalletPaths.ResourceList.QueryParameters) => Promise<WalletPaths.ResourceList.Responses.$200>

resourceCreate: (requestBody: WalletPaths.ResourceCreate.RequestBody) => Promise<WalletPaths.ResourceCreate.Responses.$201>

resourceRead: (queryParameters: WalletPaths.ResourceRead.QueryParameters) => Promise<WalletPaths.ResourceRead.Responses.$200>

resourceUpdate: (queryParameters: WalletPaths.ResourceUpdate.QueryParameters, requestBody: WalletPaths.ResourceUpdate.RequestBody) => Promise<WalletPaths.ResourceUpdate.Responses.$200>

resourceDelete: (queryParameters: WalletPaths.ResourceDelete.QueryParameters) => Promise<WalletPaths.ResourceDelete.Responses.$200>

}

export interface CryptoWallet<T extends TypedArray = Uint8Array> {

initialize: () => Promise<void>

/**

* Creates a key pair

*

* @returns a promise that resolves to the key id.

*/

createAccountKeyPair: () => Promise<string>

/**

* Gets a public key

*

* @returns a promise that resolves to a public key

*/

getPublicKey: (id: string) => Promise<KeyLike>

/**

* Signs input message and returns DER encoded typed array

*/

sign: (id: string, message: T) => Promise<T>

/**

* @throws Error – Any error

*/

wipe: () => Promise<void>

}

SW Wallet

SW Wallet provides an implementation of a software hierarchical deterministic wallet using the BaseWallet class defined in Base Wallet (see Section Base Wallet) package. The code can be found in GitLab.

Auditable Accounting

The Auditable Accounting component is responsible of registering auditable logs. As such, this component is one of the main tools to enhance the trust in the ecosystem of data marketplaces. Our solution must enforce the Data Services Agreement (DSA) terms, agreed upon all involved parties, by recording them in an auditable, transparent, and immutable way. Smart Contracts are the key part of the proposed solution for auditable accounting. The auditable accounting component is an abstraction layer to access the Smart Contracts and to allow the integration with the rest of the platform. The auditable accounting component is a service which includes an API to automate the process of logging and auditing interactions between components and record the registries in the Blockchain.

Technical Requirements

NameDescription
Auditable Logi3Market needs to be able to log data and events in blockchain. It is a key component for accounting, billing and conflict resolution. It is also important to control access to sensitive information, and to detect potential data breaches.
A public distributed ledger will be used to store non-repudiable and reliable proofs of the required actions.
Table 4 – Auditable Accounting Epics

Architecture

The solution must be scalable and cost-efficient. In this regard, transaction costs can be a considerable problem if, as it is expected, the number of auditable registries that need to be stored in the blockchain are high. To overcome this problem, it is a requirement to implement a transaction optimizer to efficiently register substantial amounts of data in the Blockchain without incurring in excessive costs. To achieve this, we first store registries in an internal database of the component, then aggregate the registries with a Merkle tree to minimize the number of Blockchain transactions and provide the appropriate data for proving each individual registry.

The Smart Contract managed by the auditable accounting component is used to store the necessary evidence of the aggregated registries from the DSA. Once the registration process is complete, the auditable accounting component will save a copy of all the information needed to verify that the registration was successful in the Blockchain. This information can be consulted and obtained later by the marketplace users. The auditable accounting component provides the functionality to trace registries and obtain “certificates” of them that can be publicly or privately used to prove that a certain registry was performed. Users must be able to download these certificates and validate the registry without further interaction with the auditable accounting component having a proof that can be universally validated without the intervention of any other entity or software component. The certificate of a DSA will provide: the Blockchain that has been used to create the auditable data registration, the address of the Smart Contract used, and the “proof of registry” of the associated data.

Figure 3 – Auditable Accounting Architecture

The auditable accounting component is a service which includes an API to automate the process of logging and auditing interactions between components and record the registries in the Blockchain. As shown in Figure 8: Auditable Accounting architecture, in general, the API of the AA module is accessed through the Backplane API Gateway. Additionally, the auditable accounting component can be accessed directly from any internal component of the platform.

On the other hand, to allow external parties to check that logs have been properly registered in the blockchain, interested parties need to obtain certain data from the distributed ledger as well as some off-chain data provided by the Auditable Accounting module via an API. This off-chain data are essentially Merkle proofs for each individual record. It is important that the off-chain data is provided with high availability. For this reason, the Auditable Accounting module uses the distributed storage component. In this way, high availability and data replication is provided to the relevant off-chain data required to store the registries and verify auditable logs.

Database model

The database model proposed for this component is based on two SQL tables. The first one is the related one with the blockchain. It contains the transactions prepared or sent to the blockchain.

It contains the following columns:

  • Id: Primary key to link with the other table.
  • Nonce: Nonce from the account to build the transaction
  • Txhash: Hash of the transaction.
  • Timestamp: Exact date of the creation of the transaction.
  • Registrationstate: Status of the transaction.
    • Unregistered: Transaction not created.
    • Pending: Transaction created but not sent to the blockchain.
    • Mined: Transaction sent with less than 12 block confirmations.
    • Confirmed: Transaction sent with more that 12 block confirmations.

On the other hand, the registry table is responsible to store the proofs of the data hashes that wants to be validated against the blockchain.

It contains the following columns:

  • Id: Primary key to link with the other table.
  • Dateofreception: Date when the data is received.
  • Datahash: Cryptographic hash function of the data. It is one of the leafs of the Merkle Tree.
  • Merkleroot: Root of the Merkle tree.
  • Merkleproof: Concatenated hashes that allows to validate the datahash to the root of the tree.
  • Readyforregistration: Boolean to indicate if the tree is built and ready to be deployed in the blockchain.

Smart Contract

The smart contract deployed for this component just stores the root of the Merkle tree that summarizes all the data hashes stored in the database. It only allows to modify that value by the owner of the smart contract which shares the same account with the auditable accounting. Also, it includes the capability to subscribe to an event that notify you about a new root released. The Solidity code is the following:

Smart Contract Manager

The Smart Contract Manager provides a gateway to access the Smart Contracts and is used by other subsystems to integrate their functionalities (payments, accounting, conflict resolution).

Technical Requirements

NameDescription
Semantic description of the SLS and the subscriptionIn order to orchestrate the different smart contracts and/or subsystems, the SLS should clearly specify in a machine-readable way (semantic description):
Identity: identity attributes to prove as a consumer (age, sex, education, …). Anonymity requirements.
Explicit user consent:
legal consent of data subjects/owners required? If yes:
(a link to) a list of the explicit consents obtained by the data provider
[optional] a description of where to connect in order to check the revocation/status
(a link to) a description of provider-marketplace agreement stating GDPR obligations regarding subject consent.
Conflict resolution: whether or not an external entity can solve a dispute between a provider and a consumer, and a univocally identifier of that entity
Auditable accounting:
Description of the data that should be reliably accounted to protect the service
Payments: Description of the payment methods to use. Currently 2 approaches:
1 Provider, Consumer and Data Owner have only a relationship with their marketplaces. Providers invoice their marketplaces, marketplaces invoice their consumers, data owners invoice their marketplaces. If the stakeholders do not have a common marketplace, marketplaces invoice marketplaces
2 A provider directly invoices its consumers. Data Owners invoice the provider.
I both cases where to pay in advance (debit) or invoiced after that (credit).
Table 5 – Smart Contract Manager Epics

NameDescription
Reliability of agreementsAs a stakeholder of i3market, I want that once a data trading agreement is settled, i3market guarantee that the agreed conditions are satisfied
Table 6 – Smart Contract Manager User Stories

Architecture

After a consumer requests a data purchase, the Smart Contract Manager extracts the contractual parameters from the data offering description and returns a template with possible contractual parameters (to be displayed in the marketplace). With a potential proposal of new parameters by the consumer, the provider can create an agreement proposal. The Smart Contract Manager invokes the Data Sharing Agreement Smart Contract and creates a Data Sharing Agreement proposal with the proposed contractual parameters. As soon as the data consumer accepts the proposal, the Data Sharing Agreement object is put on the ledger, and automatically enforced by the corresponding Smart Contracts.

Figure 4 – Component diagram of the Smart Contract Manager subsystem
  • Conflict resolution: In case any violations to the contract occur, the conflict resolution component is invoked.
  • Auditable accounting: When reliable accounting of actions is needed. It can be used for logging access to very sensitive data, or when a reliable immutable accounting is needed – e.g. for billing.
  • Explicit data owner consent: To ensure an explicit consent of the data owners every time their personal data is traded, the explicit data owner consent component is triggered.
  • Payment / Invoice Management: After a successful data transfer payment and invoice management are triggered automatically.
  • Non-repudiation protocol: The non-repudiation protocol aims at preventing parties in a data exchange from falsely denying having taken part in that exchange
  • User-centric authentication: To ensure that only authorized participants (with the corresponding role) are able to trigger functionality provided by the Data Sharing Agreement Smart Contract (via the Smart Contract Manager), user-centric authentication is used.
  • Data storage: provides means to manage data discovery index, store sample data sets and data sets for sale if the data owner lacks the capacity.

Go to the beginning of the page

Other resources of interest

Home

We are a community of experienced developers who understand that it is all about changing the perception of data economy via marketplaces support.

i3-MARKET Architecture

Take a look at the main building blocks and their hierarchy.

Data Access API

The secure Data Access API enables data providers secure registration…

Data Storage

The Decentralised storage shall provide highest available security guarantees…

Identity and Access Management

The SSI & IAM subsystem is in charge of providing both “User-centric Authentication” and…

Crypto Token and Monetization System

The Data Monetization subsystem is in charge of providing “Standard Payments”…

Semantic Engine

We developed and implemented dedicated software components for Semantic Engine System as…

Specification Deployment

i3-MARKET architecture specification is based on the 4+1 architectural view model approach. One of…

Developers Quickstart SDK

Once a marketplace is part of i3-MARKET, it can issue credentials to its consumers, providers, and…