The `tsrct doc` specification

The tsrct doc is the foundational construct of tsrct, it is the means by which all information is transacted on the platform.

The tsrct doc is a plain text document that encodes information in base64 and has 3 sections separated by a .

The format of a tsrct doc is header.body.signature

The header is a base64 encoded JSON object with defined fields
The body is base64 encoded content which is the actual content being digitally signed; it can be of any type (binary or text), and the base64 encoding is used to manage it as text
The signature is a base64 encoded byte string that represents the private key signed signature of the header.body combination

example

a bit of information is represented as an immutable url:

https://tsrct.io/b/8P7D8JWQK2LSD189.gxosu7wr65dpj6l7ij3rdkep4dmyn7tc

the above is an example of a tsrct doc used to transmit a bit of signed plain text is as follows:

eyJ0eXAiOiJ0ZXh0IiwiY3R5IjoidGV4dC9wbGFpbiIsImNscyI6ImJpdCIsImF0bSI6IjhQ
N0Q4SldRSzJMU0QxODkiLCJpdHMiOiIyMDIxLTA0LTA2VDEyOjQ0OjEyWiIsInJpZCI6ImJp
dC0xIiwia2V5IjoiOFA3RDhKV1FLMkxTRDE4OS9jb2xzYzV6YzZnenF0eDRxZGJtYmVnZnZ6
ZHU0cHl5biIsInNpZyI6IlNkNkFUdktqMlJXTjJ2ZTJESURuaFM1UzV5VnI5ZjNkVWJOVWxN
QVNQRndIc3NoQ0I0b1FHcHRMcG1xMG81cXBBSFptZFBzUDhEUUV4b0czOEIzeUVpYkZ1cE9s
ZGZwUVRMc0JVRmRfQklsend6SkJjb1NSalprWUY4Y29Obk9kREVaV0VlMHRRQk5EaTM4Z0xK
dUd5QlRpM3ZDTkZ0LW9pZ01uZS12YjRaUnYwV1BiUUZsZEdXLU43NUp5a2R6UnFTM0JkN0VU
bFREN0JHckwzZzVfMGp2N3VSRXhzYk1TVGptLVFMaTNSc25LRTJTc181by1vVVliZGpBZl9t
TUlJUU9MdEtCdFlEQmNiMEM3STZqOWtWVVpFbkdiN09UTldMbG4xUllmRS1sOGJRSnN2T0NJ
YnY5VTZYMk9wS01GUTRBTFp1Q3g3M0FqOGlqLWw5MGpOUVx1MDAzZFx1MDAzZCIsIm5jZSI6
MTYxNzcxMzA1MiwiZHNjIjoidGhlIGZpcnN0IGJpdCIsImFsZyI6IlNIQTI1NndpdGhSU0Ei
LCJzaGEiOiJnRFpzLUxYemRQOFFCX29UZk1NUEN0REl2OGNSWjJ4aXgwR2N3eUR0SDhjIn0.
dGhpcyBpcyB0aGUgZmlyc3QgdHNyY3QgbWVzc2FnZS4.efn6Tg_aJ2qnl1ug9teR912H0W4B
XiOKGLkylmSEhhApEXqigaXgELjTqXtWwZ7wATy_cMMYSl3ofcR3HQOTVsTK6bqtkawT5o4G
ymziG3xOF_l3l48cYGbgNgni5yjiGkASm1JlEAgp2JZSFdQe0FC8EhBYkBueDUxfCSjZ0MLx
rxPsFM-7J2Z2NCgdI8Fse-KUXsnQC9JCOJpzYx9_JKBs6swCE_5Oh82kmpb_lgM-1Coo8BUs
wGLDKiu4cUvrODm5OhKvwoXgf9z3qN4XSqzvO_-UpKqt3IOK7RodyOcfXBB8o6BvyZZxpiJc
pyPkqW4d7yoMC0cJ4ir-NfwzYw

note: the example above has a 72 column width only for readability; actual tsrct docs do not have line breaks and will throw and error if line breaks are included

The header in the above sample is:

eyJ0eXAiOiJ0ZXh0IiwiY3R5IjoidGV4dC9wbGFpbiIsImNscyI6ImJpdCIsImF0bSI6IjhQ
N0Q4SldRSzJMU0QxODkiLCJpdHMiOiIyMDIxLTA0LTA2VDEyOjQ0OjEyWiIsInJpZCI6ImJp
dC0xIiwia2V5IjoiOFA3RDhKV1FLMkxTRDE4OS9jb2xzYzV6YzZnenF0eDRxZGJtYmVnZnZ6
ZHU0cHl5biIsInNpZyI6IlNkNkFUdktqMlJXTjJ2ZTJESURuaFM1UzV5VnI5ZjNkVWJOVWxN
QVNQRndIc3NoQ0I0b1FHcHRMcG1xMG81cXBBSFptZFBzUDhEUUV4b0czOEIzeUVpYkZ1cE9s
ZGZwUVRMc0JVRmRfQklsend6SkJjb1NSalprWUY4Y29Obk9kREVaV0VlMHRRQk5EaTM4Z0xK
dUd5QlRpM3ZDTkZ0LW9pZ01uZS12YjRaUnYwV1BiUUZsZEdXLU43NUp5a2R6UnFTM0JkN0VU
bFREN0JHckwzZzVfMGp2N3VSRXhzYk1TVGptLVFMaTNSc25LRTJTc181by1vVVliZGpBZl9t
TUlJUU9MdEtCdFlEQmNiMEM3STZqOWtWVVpFbkdiN09UTldMbG4xUllmRS1sOGJRSnN2T0NJ
YnY5VTZYMk9wS01GUTRBTFp1Q3g3M0FqOGlqLWw5MGpOUVx1MDAzZFx1MDAzZCIsIm5jZSI6
MTYxNzcxMzA1MiwiZHNjIjoidGhlIGZpcnN0IGJpdCIsImFsZyI6IlNIQTI1NndpdGhSU0Ei
LCJzaGEiOiJnRFpzLUxYemRQOFFCX29UZk1NUEN0REl2OGNSWjJ4aXgwR2N3eUR0SDhjIn0

when decoded, it provides the following JSON:

{
  "typ": "text",
  "cty": "text/plain",
  "cls": "bit",
  "atm": "8P7D8JWQK2LSD189",
  "its": "2021-04-06T12:44:12Z",
  "rid": "bit-1",
  "key": "8P7D8JWQK2LSD189/colsc5zc6gzqtx4qdbmbegfvzdu4pyyn",
  "sig": "Sd6ATvKj2RWN2ve2DIDnhS5S5yVr9f3dUbNUlMASPFwHsshCB4oQGptLpmq0o5qpAHZmdPsP8DQExoG38B3yEibFupOldfpQTLsBUFd_BIlzwzJBcoSRjZkYF8coNnOdDEZWEe0tQBNDi38gLJuGyBTi3vCNFt-oigMne-vb4ZRv0WPbQFldGW-N75JykdzRqS3Bd7ETlTD7BGrL3g5_0jv7uRExsbMSTjm-QLi3RsnKE2Ss_5o-oUYbdjAf_mMIIQOLtKBtYDBcb0C7I6j9kVUZEnGb7OTNWLln1RYfE-l8bQJsvOCIbv9U6X2OpKMFQ4ALZuCx73Aj8ij-l90jNQ==",
  "nce": 1617713052,
  "dsc": "the first bit",
  "alg": "SHA256withRSA",
  "sha": "gDZs-LXzdP8QB_oTfMMPCtDIv8cRZ2xix0GcwyDtH8c"
}

note: the above JSON is pretty printed; the actual JSON does not have any line breaks or non-significant spaces

The header is a JSON document with a set of defined fields that have a specific purpose. Headers vary by the type of artifact being represented (atom, bit, key, or grant).

common header fields

The common header fields across all header types are:

cls: (required, unindexed) the ‘class’ of the document, legal values are: atm for atom, bit for bit, key for key
atm: (required, indexed) the id of the atom that has issued this document
its: (required, indexed) the issue timestamp of the document
key: (required, unindexed) the key id that has been used to sign this document
sig: (required, unindexed) the private key signature of the base64 encoded body of the document
nce: (required, unindexed) the nonce of this document, which is the unix seconds since epoch, especially important if the document is to be presented to the tsrct cloud to record as a bit, or as part of a grant process
alg: (required, unindexed) the algorithm of the hash and signature, currently always set to exactly SHA256withRSA
sha: (required, unindexed) the sha256 hash of the base64 encoded body of the tsrct document

Only indexed fields can be queried. Depending on the value of the cls field, various other fields can be populated, shown below

atom header extra fields

If cls is atm (i.e. the header is for a tsrct doc indicating an atom), the following extra fields are allowed in addition to the common fields above:

bit header extra fields

If cls is bit (i.e. the header is for a tsrct doc indicating a bit), the following extra fields are allowed in addition to the common fields above:

cid: (optional, indexed) correlation id
typ: (required, indexed) when a document is of cls bit, the type of bit is indicated by this field, legal values are:
- blob: the body is a binary object like an image or a pdf document
- data: the body is text (like a csv) but represents a structured set of data conforming to a schema
- json: the body is a json document
- link: the body is a json document that points to a web link; this json document must conform to a specific schema shown here (todo: show json schema)
- text: the body is plain text, like xml, or json, or yaml
geo: (optional, unindexed) geo point with the following format:
cty: (required, unindexed) the content type of the body is indicated by this field
scm: (optional, unindexed) schema of the content, if applicable; this a url pointing to a schema definition, such as a schema.org schema link
mtd: (optional, unindexed) any arbitrary metadata in key value pairs in a JSON object

key header extra fields

If cls is key (i.e. the header is for a tsrct doc indicating a public key), the following extra fields are allowed in addition to the common fields above:

body

The body in the above example is:

dGhpcyBpcyBhIHNpZ25lZCBtZXNzYWdl

when decoded, the body translates to:

this is a signed message

signature

The signature in the above ea

Other examples

//todo: links from the site with various atoms, bits and keys

tsrct doc creation

tsrct doc validation

Thinking about the document

see more in the different use cases

The tsrct doc specification