Using Mist with Health Nexus

In this article I’m going to explain how to access the phase one utility of our Health Nexus project using the Mist Ethereum browser. Most of the utility provided by our smart contracts are for creating, permissioning, and managing a decentralized record service (DRS) of your own. This article is intended for more technical users interested in getting started testing, developing, and using our smart contracts.

Before we get started, you’re going to need the Mist Client and access to the Rinkeby test network. Getting these installed and configured are beyond the scope of this article, but instructions can be found here and here. Once you have these up and running you are ready to begin.

Table of Contents

1. Overview
   High-level overview of the Health Nexus DRS smart contract and the basic terminology used in this article.
2. Setting up Health Nexus DRS in Mist
   How to add the Rinkeby Health Nexus DRS contract to your Mist client
3. Services
   Overview of the service struct in Health Nexus DRS
4. Create a Service
   Create a service using a data access endpoint
5. Sharing a Service
   You can share a service to have different accounts using the same service, or to delegate responsibility.
6. Recovering a Service
   If you lose your service hash here’s how to recover it.
7. Service Related Functions
   Functions to get the service endpoint or update the service endpoint.
8. Keys
   An overview of keys in Health Nexus DRS.
9. Creating & Issuing
   Create keys to permission, sell or issue them directly to accounts.
10. Permissions
    Service owners can enable share, trade, and sell permissions on keys.
11. Sharing
    Keys enabled for sharing can be shared with multiple accounts.
12. Selling
    Key owners can offer keys for sale if selling is enabled.
13. Trading
    Keys enabled for trading can be offered for specific trades.
14. Recovering a Key
    Learn how to recover your key hash if you lost it.
15. Key Related Functions
    Get the service endpoint from the key hash.
16. Logging & Messaging
    Service and key owners can create auditable messages on the blockchain.
17. Using Health Cash (HLTH)
    You have to explicitly approve the Health Nexus DRS contract to use your health cash.

Overview

The first phase of Health Nexus is designed to give early access to the key/pair protocol change we are implementing on the Health Nexus blockchain. These keys are used to secure, blockchain-based identities and system of on-chain permissions to enable collaborative access to off-chain data.

The Health Nexus DRS contract is designed to support a variety of DRS implementations concurrently. This is accomplished, in part, by a simplified on-chain service structure which enables the registration of endpoint urls and creates an immutable record of that service and associated owner. Service owners can then create and issue keys for that service.

Keys are unique, ownable records that can be used to establish the identity of valid off-chain service consumers through a side-channel process that requires verifying messages signed by the key owner. Services can permission keys to extend the default functionality to enable trading, sharing, and selling.

A service owner can allow keys to be purchased using Health Cash (HLTH).

Setting up Health Nexus DRS in Mist

From the Contracts tab, click Watch Contract

To start using the Health Nexus DRS you will need to add the contract to your Mist client. This is done by clicking “Watch Contract”, and adding the Rinkeby DRS contract.

Enter the following information to correctly add the Rinkeby Health Nexus DRS contract:

Contract Address: 0xF54a6dE3F1FE973c73BfBb9a5B35D3695Ea277D2

Contract Name: Rinkeby Health Nexus DRS (You can put whatever here, and change it later. I shortened it to Rinkeby DRS to keep the name on one line)

JSON Interface: Copy and paste the full developer.abi into this field.

Once you complete this process you should see the contract in your contracts list. Clicking on it will give you access to all the functions you need to read and write to the contract.

On the left side of the interface are all the READ operations. These can be used freely as reading from the Ethereum blockchain does not cost any Ether.

On the right site of the contract interface are all the WRITE functions. These will modify the state of the contract in some way and will require a transaction and cost Ether.

Using READ and WRITE functions together will give you access to all the utility you need to create and manage your own data gateway service.

Services

At the core of the Health Nexus DRS is the immutable record of registered services, the ownership, and the authority service-owners have over the keys they create and issue. Any account is free to create services and issue keys using the Health Nexus DRS contract.

On the blockchain, a service is represented by the cryptographic hash of its endpoint and creator and stored as a struct containing the endpoint and the primary owner in the services mapping.

Create a Service

Services are uniquely identified by the cryptographic hash of their endpoint URL and owner. To create a service, pass the Create Service function a URL. If that service has not already been created a new one will be added.

Note: You will need the service hash to create or manage keys, so you must store it for future use. To get the service hash, first check the service count after you create a service. Then use the count to retrieve the service hash.

1. Creating a service writes to the blockchain and will require an Ether transaction.

2. First get the service count

3. Subtract 1 to get the location it falls in the list (arrays are indexed starting at 0).

4. Copy and paste the service hash into the Services field to read and verify your service endpoint and owner.

Sharing a Service

You may want to decentralize control over your service’s keys. To share a service, use the “Share Service” function to pass your service id and the account address you wish to share. Only owners can share a service, so make sure you use the service owner’s account to call Share Service.

You can add and remove Shared owners. Shared owners can be added and removed by any service owner. However the primary owner is immutable. It resides in the service struct.

Recovering a Service

If you lose your service id, there are multiple ways to recover it.

• Recreate it by calculating the cryptographic hash of the original url and original account address used to create the service.
• Lookup the _service key from the ServiceCreated event, using your account’s address for _owner.
• Iterate through the serviceList, calling getService for each key until you find one that matches your original url or account address.

Iterate through the service list to get the service hash.

Use the service hash and Get Service to verify service owner and endpoint.

Service Related Functions

Get the URL

You can retrieve a service’s url, using the Get url function, passing the service hash. This function returns a string of variable length making it unsuitable for cross-contract use.

Return service URL using a service hash.

Update the URL

A service owner can update the service’s url.

You can change your service endpoint, but doing so will reduce the recover options should you misplace your service hash.

Keys

A key establishes a relationship between accounts and services. Only a service owner can create a key, and only for a service they own. A key’s service is immutable, granting irrevocable rights to the related service owners. Additionally, a key also records the owner and if it can be sold, shared, or traded. When created, a key is unable to be sold, shared, or traded. A service owner must explicitly enable these permissions for a key.

Creating & Issuing Keys

Keys are identified by the cryptographic hash of: the service id, the time the key is created, and the address the key is issued to. This makes them impractical to regenerate, so the key should be stored.

Create a key for your service

A service owner can create a key by passing a service to the Create Key function. This creates a new key for that service and issues it to the service owner’s account. A transaction will be returned with a log containing a KeyCreated event denoting the _owner, and the new _key. In Mist, you need to track the key count, like so:

Note the key count before you create a key

Similar to getting your service hash, subtract 1 from the count to get your position in the key list. This is your key hash. You should store it somewhere as you will need it to permission or share your key.

Using the key hash you can see the primary key owner and the key permissions (share, trade, sell).

Alternatively you can pass an account address and service to the Issue Key function to directly issue a key to any account address.

You can create and issue a new key directly to an Ethereum Account.

Permissions

You are unable to sell, trade, or share newly created keys. The service owners can selectively enable or disable these permissions using the Set Key Permissions function.

When disabling these permission, any active trade offers, sales offers, or shared owners will be removed for that key.

Sharing

A key with permission to share can be shared by the owner by passing the key and account address to the Share Key function. Shared owners have identical permissions as the primary owner.

After sharing is enabled on keys the key owner can share it.

Any owner can also unshare a key by passing the key and account address to remove. Primary key owners can not be removed, only shared owners.

Selling

Keys can only be sold if the service owner assigns canSell permissions. If enabled, a key owner can then sell a key by creating a sales offer for a specific buyer. To create a sales offer, pass the key, the buyer’s account address, the price (in HLTH), and after-sale permissions to the Create Sales Offer function.

When creating a sales offer with a _can sell value of false, future sales of the key will be disabled at the point of sale. The key owner can cancel a sales offer by passing the key to the Cancel Sales Offer function.

To purchase a key that’s been offered to you, pass the key to the Purchase Key function. Note: This requires that you have previously authorized the Health Nexus DRS contract to spend a sufficient amount of HLTH to cover the purchase price.

The Health Nexus DRS contract cannot spend your HLTH tokens without your explicit authorization.

A successful sale will return a transaction with a logged KeySold event.

Trading

To trade keys, both keys have to be authorized to trade by their respective services. To make a trade offer, pass the key you have and the key you want to the Create Trade Offer function. If a matching trade offer exists, the trade will complete. Otherwise a trade offer will be created to potentially be filled at a later time.

You can cancel a trade offer using the Cancel Trade Offer function.

Completing a trade offer returns a transaction with a logged KeysTraded event and cancels any related sales offer.

Recovering a Key

If you lose your key, there are two ways to recover it.

• Lookup the key from the appropriate event, depending on how you acquired the key. For example, if you created the key, you can filter the KeyCreated events by _owner to retrieve the _key. Other events include: KeySold, KeysTraded, and Log.
• Iterate through the keyList, calling getKey for each key until you find the key.

Iterate through the key list.

Use the keys returned above to find your owned keys.

Key Related Functions

Get url from key

You can retrieve a key’s service’s url using the “Get url from key” function, passing the key. This function returns a string of variable length making it unsuitable for cross-contract use.

Logging & Messaging

This contract provides two general purpose events, Message and Log, that a decentralized app or gatekeeper service can use. A third event, Access, can only be created by a service owner and only for their service’s keys. This is to provide an immutable access record that can be audited.

Logs can be created to provide a history of actions.

You can use the Message function to create a history between a key and service.

The Log Access event only be created by a service for one of their keys.

Using Health Cash (HLTH)

The Health Nexus DRS contract allows for the purchase of keys using Health Cash (HLTH). To purchase a key with HLTH, you must approve the contract to spend your HLTH using the standard EIP 20 approve function.

A dapp or service that uses this functionality will have to provide the two stage interface to pre-approve the necessary HLTH. You can manually add this functionality to the Mist client by adding the Rinkeby Health Cash Token contract (0x8a1eD83DfB3ea079ee7F057e1E7eCE964A1c6259) and requesting Rinkeby HLTH as a developing partner. Contact info@simplyvitalhealth.com for how to apply as a developing partner.

Summary

Using the Mist client, you are able to create services, create and issue keys, and permission keys for use in a decentralized record service. This covers all the on-chain utility needed to create and manage a data gateway service that uses the Health Nexus smart contract for cryptographic identity management.

For a more technical overview, check out out the project wiki on github. Our smart contract code and security audit can be found in our github repo.

If you have questions about this, Health Nexus, or our token, find us in our telegram group.

About SimplyVital Health

SimplyVital Health is making decentralized technology accessible to the healthcare industry by creating Health Nexus, a healthcare-safe opensource blockchain.

https://www.simplyvitalhealth.com/