Creating Assets

Creating assets

An asset refers to an entry on blockchain - applying the general TEOS terminology. Each asset has its unique ID (referred to as the Asset ID), timestamp and additional properties. TEOS assets may or may not have a quantity (Tokens). The Notardec API creates assets without quantity. An asset without quantity is simply a “document”.
The creation of an asset needs two mandatory parameters:

POST /assets/

{
  "name": "string",
  "author": "string"
}
  • name: The primary attribute of the asset and the main display property. It shouldn’t contain any secret information, because it is stored on DocumentDB and can be researched by any TEOS user.
  • author: The blockchain address that creates this asset. A blockchain address (Ethereum) has to be provided in Hex. (starting with “0x”). The role of the author is very important. An address is a representation of the public key of an ECDSA keypair. The private key of this pair has to be stored safely on a separate device. It is needed for signing. Whether it is a smartphone App (derived from the White-Label App or built from scratch), such as the NOTRZR APP, a Hardware wallet, a tool such as the Autosigner - as long as this device can communicate with the TX.Services Infrastructure to sign and submit the asset-creation transaction it will work.

After sending a creation request, a new treansaction is generated which is submitted to the device, that holds the private key. The asset will not exist on blockchain unless the transaction has been successfully signed, submitted, committed and confirmed.
Besides the two mandatory properties there are optional properties. Such as “data”. This property is defined as multiline string and can hold any text up to 5'000 characters in size. This includes nested structures such as XML/JSON, or encoded/encrypted data such as Base64/AES.

Just append the “data” property to the input parameters:

{
  "data": "string"
}

Attaching file info to assets

Note that it is about the “file info” - the metadata - and not the file itself. The Notardec API is not a file-sharing platform. Any attachment must be stored on a separate repository, but you can add the metadata of the file and it’s identity (filehash) so that it can later be identified by comparing the filehash stored on blockchain with the filehash of the document. If the filehashes match you can be certain it is the right document as it is virtually impossible to make up a filehash. The hashing method itself is not defined by the Notardec API, you can use any. We recommend SHA2-256.

To use the file-info properties, simply provide any or all of the following elements in addition to name and author:

{
  "fileName": "string",
  "fileType": "string",
  "fileSize": "string",
  "method": "string",
  "hash": "string",
  "uri": "string"
}
  • fileName: e.g.: “sample.pdf”. In case you are referring to an entry in a database the fileName could also contain the record-ID
  • fileType: We provide this property for fast processing of content (in case the documents are accessible to the Notardec API consumer). e.g. pdf, txt, jpg, …
  • fileSize: The size in bytes.
  • method: Hashing method used.
  • hash: The hash string of the generated hash.
  • uri: The repository of the file. Can contain any string.

Code example

In the following example we demonstrate how to submit an asset creation request to Notardec.

export async function createAsset(apiKey: string, token: string | null, payload: CreateAssetRequest): Promise<IResponse<AssetResponse>> {
  const result = await axios.post<IResponse<AssetResponse>>(`${process.env.NOTARDEC_URL}/assets`, payload, {
    headers: {
      'X-API-KEY': apiKey,
      Authorization: `Bearer ${token}`,
    },
  });
  return result.data;
}

The first parameter is the Notardec Key, the second is the user-token (optional parameter. We use it, because the transaction is being signed with the NOTRZR APP), the third is the request body. The request body will have the following form:

Request: 
{
    name: string;
    data?: string;
    author: string;
    fileName?: string;
    fileType?: string;
    fileSize?: string;
    method?: string;
    hash?: string;
    uri?: string;
}

Fill any content into the request body properties. Remove those that are not applicable. The response body looks as follows. The important properties are “id” (which is the unique Asset ID), the blockchainHash (which is the hash of the entire record that is written to blockchain) - it must be equal to the documentDBHash, the off-chain data-storage and transactionId (to retrieve the transaction for signing and to obtain the transaction status).

Response: 
{
    value: {
      id: string;
      author: string;
      name: string;
      description: string;
      language: string;
      jurisdiction: string;
      unotOfMeasure: string;
      sparkFactor: string;
      sparkFactorModifier: string;
      assetClass: string;
      createdOn: Date;
      updatedOn: Date;
      blockchainHash: string;
      documentDbHash: string;
      transactionId: string;
      customDefinitionItems?:  {
          key: string;
          type: string;
          value: string;
          name: string;
          sectionsPath: string;
          sectionsPathNames: string;
      }
    } || null;
    meta ?: {
        size ?: number;
        page ?: number;
    }
    error ?: {
        code: string;
        message: string;
    }
}

After having sent the request you need to handle the transaction, retrieve, sign and submit it.

Real asset example 
{
        id: '0d80c1ea41b73a57db90a0001',
        name: 'Hello world asset 1',
        author: '0x943d7c1b12d7241598f1bf3fcc5d27a8ad2cc096',
        description: 'Notardec Asset',
        language: 'en',
        jurisdiction: 'EARTH',
        unitOfMeasure: 'token',
        sparkFactor: '1',
        sparkFactorModifier:
          '{"type":"FORMULA","start":"2021-09-21T12:11:08Z","t":"1d","f":"1"}',
        assetClass: 'A017',
        createdOn: '2021-09-21T14:27:44.7828091+02:00',
        updatedOn: '2021-09-21T14:27:44.7828091+02:00',
        blockchainHash:
          '0xa21d0889b90e745516416e13adbb9a8fbfe9fde20e92bd9ee2f728028ae50fcc',
        documentDbHash:
          'a21d0889b90e745516416e13adbb9a8fbfe9fde20e92bd9ee2f728028ae50fcc',
        customDefinitionItems: [
          {
            key: 'data',
            type: 'TEXT',
            value: 'Lorem ipsum 111',
            name: 'Data',
            sectionsPath: '[documentation]',
            sectionsPathNames: '[Documentation]',
          },
        ],
        transactionId: '03e1da13-aed0-4b46-4708-08d97cc96d25',
        assetLinkIds: ['0cf3e2e5f35b8d6cf47aa0001'],
}

Asset creation status

Blockchain operations are always asynchronous. The status can be easily looked up by sending GET /assets/{assetId}/status

← Creating Assets
Getting Assets →