Certificates Specification (Version 1)

Certificates allows laboratories participating on the GenoBank.io platform (“permittees”) to create blockchain-recorded laboratory results with private information. GenoBank.io markets this product as Blockchain Lab Result Certification.

If you just want to use Certificates, see our supported implementations:

Java genobankj
PHP genobank-php
JavaScript genobank-js

But if you are building an implementation, read on…

Constants

Certain constants are refered below. These vary between the test network and production network.

Constant	Test	Production
`🟡NAMESPACE_PREFIX`	`io.genobank.test`	`io.genobank`
`🟡CERTIFICATE_URL_BASE`	`https://genobank.io/test/certificates/verify-certificate-v1#`	`https://genobank.io/certificates/verify-certificate-v1#`
`🟡API_URL_BASE`	`https://api-test.genobank.io/`	`https://api.genobank.io/`
`🟡GENOBANKIO_ADDRESS`	`0x795faFFc58648e435E3bD3196C4F75F8EFc4b306`	`0x633F5500A87C3DbB9c15f4D41eD5A33DacaF4184`

Also a taxonomy of procedures and results are refereced below. These are available at: https://github.com/Genobank/genobankio-js/blob/main/src/config/laboratoryProcedureTaxonomy.json.

Permittee representations

This is the information a permittee attests is true and correct relating to a laboratory procedure.

Field	For signing	For URL
`VERSION` A constant value	`🟡NETWORK_BASE` + `.certificates.v1.permittee-certification`	`V1`
`PATIENT_NAME` (`^[A-Za-z0-9 -.ñÑ]+$`) The name of the patient, as matching a passport or other government identification	`JOHN DOE`	`JOHN DOE`
`PATIENT_PASSPORT` (`^[A-Z0-9 -/]$`) The identifier of the patient’s passport (or the empty string)*	`MX 1234`	`MX 1234`
`PROCEDURE` (`^[A-Z0-9]+$`) Which laboratory procedure was performed	`COVID-19-PCR`	`1`
`RESULT` (`^[A-Z0-9]+$`) The outcome of the procedure	`NEGATIVE`	`N`
`SERIAL` (`^[A-Z0-9 -/]$`) The model and serial number of a consumable used in the procedure (or the empty string)*
`TIME` (after 2000-01-01) When the procedure was performed	`2021-01-24T07:42.000Z` Shown as YYYY-MM-DDTHH:MM:SS.MMMMZ, always in GMT	`1611517330000` Shows as milliseconds since UNIX epoch

Only PROCEDUREs and RESULTs defined in the above taxonomy of procedures are allowed.

Permittee signature

To publish their attestation of the representations above, a permittee will serialize and sign the representations.

The permittee representation serialization is the array of FOR SIGNING fields above, separated by the pipe (|) character.

For the example above, using the test network, that is:

io.genobank.test.certificates.v1.permittee-certification|JOHN DOE|MX 1234|COVID-19-PCR|NEGATIVE|2021-01-24T07:42.000Z

The permittee representation hash is an Ethereum message hash of the permittee representation serialization.

The implementation will load the permittee’s account, typically with the permittee providing a 12-word passphrase. Use BIP-032 with the MetaMask path at account zero (m/44'/60'/x'/0/0). (Test case: “candy maple cake sugar pudding cream honey rich smooth crumble sweet treat” will load account 0x627306090abab3a6e1400e9345bc60c78a8bef57.) Your Web3 library should have an easy way to calculate that.

Then the implementation will use this account to sign the permittee representation hash to create the permittee signature.

REST server

Our Certificates product is used with a single call to our REST server.

Create a HTTP POST to the URL: 🟡CERTIFICATE_URL_BASE + certificates

Request format is:

{
  "claim": "0x2984739847...", // permittee representation hash
  "signature": "0x293487", // permittee signature
  "permitteeSerial": 47 // the permittee must provide their permitteeId  
}

Response is like:

{
  "status": 200,
  "txHash": "0x923879...", // the blockchain transaction hash
  "timestamp": "2021-01-01T01:03:05.000Z", // the platform timestamp
  "permitteeSignature", "0x234749..." // permittee signature above
  "genobankSignature": "0x293847..." // a signature from the GENOBANKIO_ADDRESS  
}

Validate the response is correct by checking that status is 200.

You can also validate that the genobankSignoture but that is outside the scope of this document.

URL format

… creating the URL