Clipperz Registration Protocol

Version: 1.0

User Hierarchical Deterministic Wallet

Clipperz application creates and manages an HD wallet for each user. The seed of the wallet is randomly generated the first time the HD wallet is used, and then stored along with other user profile data.
The seed and all other wallet information are obviously encrypted directly in the browser and are only accessible by providing the full user credentials. This means they never reach Clipperz servers, as any other data entered by the user.

The registration transaction

When a user requires a specific card to be registered (notarized) on the Bitcoin blockchain, a multisig Bitcoin transaction with the following defining characteristics is generated:

  • the OP_RETURN code is set to “CLIPPERZ 1.0 REG”.
  • the output is a 2-of-2 bare (non-P2SH) multisig script;
  • the keys used in the output script are:
    1. card key: a subkey derived from the user HD wallet;
    2. card data key: a key derived from the actual content of the card;

Other non-defining characteristics are:

  • there is just a single input, from a Clipperz controlled wallet;
  • the input value exactly matches the output value plus fees, so the transaction has no change.

Card key

Each card gets its own ‘index’, used to derive the card own key/address; the code used looks like this:

var seed = "...";
var cardIndex = i;
var userMasterKey = new bitcoin.HDNode.fromSeedHex(seed, NETWORK);
var cardsKey = userMasterKey.derive(0);
var cardKey = cardsKey.derive(cardIndex);

Card data key

‘card data’ key is computed from the serialisation of the JSON.metadata content using the following steps (in JavaScrip pseudo code using BitcoinJS library):

var cardContent = {...}
var cardContentBuffer = new Buffer(JSON.stringify(cardContent), 'utf8');
var cardContentHash = bitcoin.crypto.hash256(cardContentBuffer);
var privateKeySeed = BigInteger.fromHex(cardContentHash.toString('hex'));
var privateKey = new bitcoin.ECPair(privateKeySeed, null, {'network':NETWORK, 'compressed':true});
var publicKey = privateKey.getPublicKeyBuffer();
var address = privateKey.getAddress();

The registration certificate

A Clipperz Registration Certificate (aka ‘certificate’) is a regular HTML file containing information related to a registration transaction. The certificate HTML file can be opened in any browser and it will show the basic information of the certificate. It also contains an hidden ‘textarea’ element with the JSON representation of the same data that are visualised.

The purpose of a certificate is to prove that the information contained in the notarized card existed at a certain date in time (existence) in that exact form (integrity).

The easiest way to check the authenticity of a certificate is to drop the certificate HTML file into the /verify application that will the JSON content from the hidden ‘textarea’ and validate its content against the information stored in the registration transaction on the blockchain.

Alternatevely a certificate may be verified following these instructions.

Certificate details

The content of the certificate is a JSON representation of a Clipperz card, with extra data about the matching Bitcoin transaction. The main JSON object keys are:

  • ‘transaction’: data used to create the Bitcoin transaction;
  • ‘metadata’: content of the Clipperz card;
  • ‘tx’: ID of the actual Bitcoin transaction in the Bitcoin blockchain;
  • ‘requestDate’: date when the certificate was requested;
  • ‘creationDate’: date when the transaction was actually registered in the Bitcoin blockchain.


The ‘transaction’ sections has the following keys:

  • ‘reference’: ID of Clipperz Card, not strictly relevant for the verification process;
  • ‘version’: “1.0”;
  • ‘card.publicKey’: card public key;
  • ‘card.address’: address derived from the card public key;
  • ‘metadata.publicKey’: card content public key, derived from the hash (sha256) of the serialised content of ‘metadata’ field;
  • ‘metadata.address’: card content address, derived form metadata.publicKey.


This section includes actual card content, arranged with these keys:

  • ‘label’: title of the card;
  • ‘fields’: list of objects with two keys (‘label’ and ‘value’);
  • ‘notes’: optional item containing card notes;
  • ‘attachments’: list of objects with the following keys:
    1. name: name of the uploaded file;
    2. contentType: MIME value of the content type of the attachment;
    3. size: size of the attachment, in bytes;
    4. hash: hex representation of the sha256 computation on attachment content.