Encoded and Unencoded Records
Use encoded records if you want the content of your records to be kept private and not be visible on the global public blockchain. Only a fingerprint will be visible on the blockchain. See the Car Dealership example.
Use unencoded* records if you want your records to be published or shared on the global public blockchain.
Note: * Unencoded records available by prior arrangement with nChain.
Encoded Records
If you specify an encoder, the records will be encoded by nChain Event
You can choose which encoder to use
You can supply an optional encoder parameter
An encoder can be specified for each write, create, update and verify command
A combination of encoders can be specified for each command
You can encode both independent and linked records
The input record will be encoded, and the output record will be the fingerprint
The location refers to the position on the blockchain where the fingerprint is written
Selecting an Encoder
The Encoding algorithms supported by nChain Event are listed in the API Schema.
These include:
SHA256 – the default used by the blockchain community
Base64 – converts binary into a human-readable format
Information about the veracity and efficacy of different algorithms is widely available on the internet and in the specialist literature.
Encoder Parameters
Some encoders, such as SHA256, accept optional parameters specified in trailing parentheses like this: encoder-name(parameters). For example: SHA256(2024-01-02T13:14:15.12345)
The optional SHA256 encoder parameter (called a "salt" by the blockchain community) makes the fingerprint more secure. For instance, encoding the input record "nChain Event" using SHA256 will always produce the same fingerprint which may not be very secure. But by simply prepending a different salt such as the current date and time each time the input record is encoded, the fingerprints will never be the same, which is far more secure. You can either do this to the input record yourself before you send it to nChain Event, or get nChain Event to prepend it for you.
Please note that you must record any encoder parameters you use in order to recreate the fingerprint for verification.
For large input records, there is a lesser need for salt because the entropy is high. For small input records, such as fixed text, there is a greater need for salt because the entropy is low making the fingerprint susceptible to brute-force attacks. Personally Identifiable Information (PII) always requires salt to keep the information hidden.
We recommend using a cryptographically secure pseudo-random password generator. But for the examples in this document, where we emit infrequent records at arbitrary times of the day, we use the date and time as salt. If we produced multiple records per second, we would use fractions of a second too.
Combined Encoders
Whenever you specify an encoder for a command, you can combine multiple encoders separated by "|" (pipe) and they will be actioned in sequence, the output from the first encoder being fed into the second etcetera.
The output from the final encoder will be written to the blockchain.
The output from each encoder will be listed in the command response. Large encoder outputs may be truncated.
An encoder can be specified more than once, for example: SHA256(salt)|SHA256|Base64.
Unencoded Records
If you do not specify an encoder, the records will be unencoded
Records will be written unencoded to the global public blockchain
You can do this for each write, create, update and verify command
You can specify both independent and linked records as unencoded
Example Encoders
In the encoder code snippets in the workflow examples below we will use these encoders and parameters:
SHA256 is the name of a well-known cryptographical fingerprint function (also called hash).
The date time shown is the SHA256 encoder parameter (the "salt").
The "|" (pipe) character indicates that the encoder output should be put through the following encoder.
Base64 is another well-known reversible conversion function, which converts its input into human-readable output.
Last updated
