Documents Transactions

Attachments

Sometimes there is a need to send more information about a transaction than fits in the provided memo field, for example: KYC info, an invoice, a short note. Such data shouldn’t be placed in the ledger because of its size or private nature. Instead, you should create what we call an Attachment. A HC Net attachment is simply a JSON document. The sha256 hash of this attachment is included as a memo hash in the transaction. The actual attachment document can be sent to the receiver through some other channel, most likely through the receiver’s Auth server.

Attachment structure

Attachments have a flexible structure. They can include the following fields but these are optional and there can be extra information attached.

{
"nonce": "",
"transaction": {
"sender_info": {
"first_name": "",
"middle_name": "",
"last_name": "",
"address": "
",
"city": "",
"province": "",
"country": "",
"date_of_birth": "",
"company_name": ""
},
"route": "",
"note": ""
},
"operations": [
{
"sender_info": ,
"route": "",
"note": ""
},
// ...
]
}

Name	Data Type	Description
nonce	string	Nonce is a unique value. Every transaction you send should have a different value. A nonce is needed to distinguish attachments of two transactions sent with otherwise identical details. For example if you send $10 to Bob two days in a row.
transaction.sender_info	JSON	JSON containing KYC info of the sender. This JSON object can be extended with more fields if needed.
transaction.route	string	The route information returned by the receiving mapping server (memovalue). Tells the receiver how to get the transaction to the ultimate recipient.
transaction.note	string	A note attached to transaction.
operations[i]		ith operation data. Can be omitted if transaction has only one operation.
operations[i].sender_info	JSON	sender_info for ith operation in the transaction. If empty, will inherit value from transaction.
operations[i].route	string	route for ith operation in the transaction. If empty, will inherit value from transaction.
operations[i].note	string	note for ith operation in the transaction. If empty, will inherit value from transaction.

Calculating Attachment hash

To calculate the Attachment hash you need to stringify the JSON object and calculate sha-256 hash. In Node.js:

const crypto = require('crypto');
const hash = crypto.createHash('sha256');

hash.update(JSON.stringify(attachment));
var memoHashHex = hash.digest('hex');

To add the hash to your transaction use the TransactionBuilder.addMemo method.

Sending Attachments

To send an Attachment and its hash (in a transaction) to Auth server of a receiving organization read the Regulation protocol doc for more information.

Example

var crypto = require('crypto');
var nonce = crypto.randomBytes(16);
var attachment = {
"nonce": nonce.toString('hex'),
"transaction": {
"sender_info": {
"name": "Sherlock Holmes",
"address": "221B Baker Street",
"city": "London NW1 6XE",
"country": "UK",
"date_of_birth": "1854-01-06"
}
},
"operations": [
// Operation #1: Payment for Dr. Watson
{
"route": "watson",
"note": "Payment for helping to solve murder case"
},
// Operation #2: Payment for Mrs. Hudson
{
"route": "hudson",
"note": "Rent"
}
]
};

var hash = crypto.createHash('sha256');
hash.update(JSON.stringify(attachment));
var memoHashHex = hash.digest('hex');
console.log(memoHashHex);