Wiki for jDoc's Blockchain EHR (ETH dApp)

Full-Version URL:
Updated 20180513


First, what IS blockchain?
Well ... it is a 'chain' of data 'blocks'. I know. That doesn't really help. So let's get wordy. For data to be useful it must be stored in a manner that allows for retrieval. This storage has evolved over time from 'flat-files' into relational databases. Blockchain is a different kind of database. In blockchains, an application looking to store data will submit the data as a transaction to the blockchain's database software (commonly referred to as a wallet, or node). An account, created by the node, gives the user ownership credentials which will sign (cryptographically) the transaction, thus verifying it's authenticity. This signature provides proof that this account has approved this transaction and it assigns traceable ownership for the transaction. Next, the node exchanges messages with MANY other nodes (a process known as 'consensus') and requests the transaction get added to an upcoming block (a group of transactions). Think of these transactions like SQL Insert statements. There are NO SQL Delete or Update statements in blockchain land since once a block is generated it can *NEVER* be changed. Every next block uses a 'hash' function to verify itself based upon the previous block, then stores that hash and adds itself onto the stack of blocks. So ... once data is added via a transaction into a block it will be there until we destroy our own planet.
  The relational database model of data storage works great for many use cases requiring enterprise/centralized ownership and management (i.e. data contributed to the database is at the mercy of the administrator, the enterprise, and said administrator has exclusive authority to modify this data). They are efficient, fast, and generally reliable (the code is). The problem here however is that anyone using this database must trust that the enterprise administering it does so responsibly (i.e. the admin ... or a hacker ... could delete, smudge, or create erroneous data with no true ability for an outsider to verify accuracy). Up until blockchain databases (like Ethereum) were birthed this problem was unsolvable. But NOW we have a solution. A user can fully control what data is placed into the blockchain database and rest-easy knowing it can never be modified. If the user needs to update this data, ONLY SHE can sign new transactions (i.e. updates) for the data in her account. Interestingly, this data can also be computing code to run (big topic. leaving it alone. google: 'ethereum smart-contracts'). Some good news about using blockchain storage: fees are only charged to insert a new transaction. This means there is no recurring cost to store the data! Some great news: the data will exist forever and can never be altered. Some bad news: the data will exist forever and can never be altered. Thus, any information stored on a blockchain which is private in nature MUST be strongly encrypted prior to storage. And I mean STRONGLY. Like AES-256 with alpha-numeric-specials passcode length > 30 characters and a random initialization vector. Why? Because since the data is public, it must be encrypted to such a strength that brute-force attacks to decrypt the original data would take millennia.

But why do health records NEED blockchain?
'Control your own data or someone else will' ~Jack Welch
  1. Data Silos:
    Have you heard of 'data-silos'? This term refers to data owned by an entity which is unwilling, or unable, to allow outside access. If you were on a safari in sub-saharan Africa and were gored unconscious by a water buffalo how would the hospital treating your injuries find out you are deathly allergic to cephalosporins or that nitroglycerin will react with your Viagra and kill you cold? Currently, they cannot. And you would be dead. Yep. That's it. Your life toast due to data-silos (and water-buffaloes). Most historical solutions to this problem (including cloud-based medical records) still suffer from the same issues of centralized ownership despite having solved the problem of centralized storage. With blockchain, however, anyone with the passcode can decrypt the stored data and access your record. No entity can prevent or limit this access. YOU are in complete control.
  2. Health Record Terrorism:
    OK. So this is a little scary to think about ... put on your big-boy/girl pants. How could someone destroy thousands of lives without ever stepping out of their basement? If Reason 1 above (data silos) is solved but is solved using traditional data-storage methods, Reason 2 becomes crap-in-your-britches scary. Consider this very real, absolutely will happen someday scenario. An attacker (i.e. hacker, disgruntled employee, etc) decides she hates humanity and wants to injure/kill a few thousand people. There are many old-school ways to do this but they are hard and he might get killed during the process. So, being of brilliant mind, she decides to write a little script (aka computer program) that will modify many health records ... very subtly. Not enough to draw attention. He does a little medical research and learns of sneaky changes that when made to certain patients will lead to significant morbidity and a HIGH likelihood of death. Her script only changes a few patient records at each facility as to not raise alarm. He removes anaphylaxis allergies from freshly admitted patients. He then places an order for the nurse to give that drug at 0100 while the patient sleeps. He's not done. He now finds patients with a diagnosis of dementia. He changes their medical histories to include a diagnosis of diabetes mellitus and changes their home medications to indicate they take 40 units of insulin at bedtime. He now orders this insulin to be given ... leading to coma, if not death. Still, he's not done. He changes the weight on a few NICU babies to 5x their actual weight. He then orders weight-base dosing for heparin (a blood thinner) which will likely go undetected ... leading to internal/external hemorrhage.
    While it is possible that an astute RN will notice these modifications, if done cleverly (only a few per hospital, during care transitions, at nighttime, just after admission, patients unable to dispute the error, etc) most will slip through via what's known as the 'Swiss cheese model' of accident causation. Care-providers will inadvertently cause severe damage or death to the patients they are intending to provide care. Luckily, this type of attack has yet to be performed on a large scale. If we don't address this attack vector, however, this type of attack is likely imminent. With blockchain (or other forms of distributed ledger technology), record modifications require a 'private key'. These are unique and cryptographically secure, meaning that unless an attacker gains physical access to a record's private key, he cannot modify the record. Furthermore, any such attack would be on a one-at-a-time scale. There is no database administrator account in blockchain ... thus, there is no possibility of an attacker gaining access to said account and mass-modifying records. Any record update being requested in a health-record database can immediately be validated against a patient's blockchain-record, and any conflicting information can be flagged for manual or artificially intelligent review. YOU are in complete control.


Don't look up dApp on urban dictionary. No need. dApp is an abbreviation for 'distributed application'. Great. What does that mean? It means you are using an application (i.e. code) that runs not on a central server, but on computers around the world (including the one you're reading this on now). So why do you care? Because by doing this, the information you input does not get stored in eBay's, Facebook's, or Google's database. It gets stored, encrypted, in a database replicated many (thousands) of times on computers just like your own. Any computer running a full ethereum wallet (aka node) has a copy of this database. And on top of being a database, this wallet also runs the code that retrieves, authenticates, processes, and stores information. In other words, no company, government, or individual owns it. YOU do. This means noone other than yourself can approve changes to the information or sharing of it.


  1. Please use Chrome browser
    1. UPDATE: Full-Version now functional on MOBILE devices!
    2. Download 'Trust Wallet' from the App Store or Google Play
    3. Open the App, then create a new wallet or import one
    4. 'Settings' tab -> change network to Rinkeby
    5. 'Browser' tab -> address bar -> enter '' (no quotes)
    6. Skip down to Step 5 (and don't forget to export your private key or you'll lose access to your new ethereum account!)
  2. You need the MetaMask extension installed
  3. Choose the 'Rinkeby' network in MetaMask
    1. Click on the Orange Fox in the upper right corner of your browser toolbar
    2. In the panel that opens, click on the dropdown arrow on the left side of the title bar
    3. Click 'Rinkeby Test Network'
  4. Create a new wallet in MetaMask (or login if you already have an account)
  5. Get some testnet ether from this faucet
  6. Buy some EHR tokens using the 'buy more' link
    1. Cost for each update = 1 EHR token
    2. You must maintain a minimum balance (after update) of 1 EHR token
  7. Create your emergency health record!
    1. Choose an unused MRN (Medical Record Number)
    2. Click 'Generate Awesome Passcode' to create a STRONG passcode
      -> A strong password is very important. The encrypted data will be stored in a PUBLIC database (the ethereum blockchain)
      -> You won't have to remember this passcode. We will embed it into the QR-code card you print
      -> The password is generated client-side (i.e. on your computer) via a javascript library called jen
    3. Select items from the left column you would like to store
    4. Enter your information in the text-fields in the center column
    5. Select which items you would like to encrypt by checking the box in the far right column
    6. Click 'Submit Update', then follow the prompts, to send your record into the blockchain!
    7. NOTE: Don't forget to confirm the transaction in MetaMask
  8. Click 'Generate QRCode', then click 'Print Card'. Put it your wallet!
  9. After successfully printing your QRcode card ... Reload the dApp (to clear the form)
  10. On your mobile device, scan the QRCode you printed and open the page when prompted
    -> Newer Android/iOS versions have QR code scanning automatically built-in to the Camera app
    -> You may need to go into your mobile camera app settings and turn on 'QR Code Scanning'
    -> Alternatively, go to the App Store / Google Play Store and download a free QR Scan app
  11. Enter the 'WebClient ID' from the full-version (open on your computer) into the page on your mobile device
  12. Click 'SYNC' on your mobile device to open your decrypted record on your computer!
  13. Gimme feedback at


  1. This is not HIPAA compliant yet
  2. Records with a green background are owned by you!
  3. Record ownership is determined by the ETHEREUM ACCOUNT you are using in MetaMask (Make sure to export your private keys from metamask and store them. If you lose access to your ethereum account you won't be able to update your record in the future)
  4. The passcode for sample records is 'test' (mrns 1, 1001, 12345)
  5. If something seems broken, reload the page (we are NOT bug-free ... yet)
  6. This dApp can be white-labeled in under 1 day to any other use-case desiring custom tokens and public/private data storage


  1. Allow a proxy-user (i.e. provider/hospital/clinic) to create a record, then change ownership to a new ethereum account for a patient. Then print a scanable QR-code card with the private-key for this new account to be given to the patient. The patient keeps this card and brings it in at future visits so their record can be updated
  2. Split the solidity medical record storage contract into a service contract and a storage contract (so updates to the service contract can occur without modifying stored data)
  3. Add multi-signature requirement to the storage contract
  4. Update the storage contract, only allowing it to be called from the service contract
  5. Deploy the token contract, service contract, and storage contract onto the Ethereum Main-Net
  6. Apply for a grant to fund this emergency health record system

jDoc & udifi (2018)