Linking Assets

Linking assets

The Notardec API lets you use one of the most distinguishing features of the TEOS Platform. The cryptographic linkage between two assets. Each asset is a unique artifact and can unambiguously be identified with its Asset ID. The cryptographic linkage was originally introduced to let third parties attach information to someone else’s asset. Example: Attaching an audit report to a Token. In the world of Notarization the cryptographic linkage provides a plethora of additional options. Creating the Audit report as a digital asset on blockchain and linking it to the Token is exactly one of these use-cases. Creating a signature-artifact and using cryptographic linkage for signing documents is another. Both examples are available on the NOTRZR APP.
See further examples:

  • Link amendments of a documentation to the original asset.
  • Group multiple documents (of different authors) into a collection.
  • Add supply-chain information to a product.
  • Attach an audit trail of sensor data to a product.

Important note: A link can be visualized as an arrow, pointing FROM an asset TO another asset. The asset FROM which you point to another asset is the one that is updated with an amendment. Amendments can only be signed by the one and only author of that asset. If you don’t hold the private key of that asset you cannot point FROM this asset. But you can point TO it.

POST /assets/{assetId}/links

{
  "targetAssetIds": ["string"]
}
  • linkedAssetIds: The assets that should be linked to the parent asset defined in the URL.

Code example

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

The request needs the assetId pointing TO and the assetId pointing TO (targetAssetIds) in the payload. You can add multiple assetId’s at the same time. The request body and the response body will have the following form:

Request
{
  "targetAssetIds": ["string"]
}
Response
{
  value: {
    id: string;
    state: AssetState;
  } | null;
  meta?: MetaResponse;
  error?: ErrorResponse;
}

AssetState is enum list:

export enum AssetState {
  RECEIVED = 'Received',
  SUBMITTED = 'Submitted',
  COMMITTED = 'Committed',
  CONFIRMED = 'Confirmed',
  TX_SIGNATURE_SUBMITTED = 'TxSignatureSubmitted',
  REVOKED_BY_TX_SERVER = 'RevokedByTxServer',
  REVOKED_BY_USER = 'RevokedByUser',
  REVOKED_BY_BLOCKCHAIN = 'RevokedByBlockchain',
}

To see all the links for the asset, a request to GET /assets/{assetID}/links can be sent. The following ouput is received:

{
  "value": {
    "from": ["string"],
    "to": ["string"]
  }
}
  • from: These are all the assets, which point TO the assetID in the request.
  • to: These are the assets to which the assetID in the request points.
    Both values are returned as an array of strings.

Code example

export async function getAssetLinks(apiKey: string, token: string, assetId: string): Promise<IResponse<AssetLinks>> {
  const result = await axios.get<IResponse<AssetLinks>>(`${process.env.NOTARDEC_URL}/assets/${assetId}/links`, {
    headers: {
      'X-API-KEY': apiKey,
      Authorization: `Bearer ${token}`,
    },
  });
  return result.data;
}

Here, the first parameter we pass is the Notardec Key, the second is the token (optional parameter, the record can be created using the TEOS key), the third is the asset id. The response body will have the following form:

{
    value: {
        from: string[];
        to: string[];
    } | null;
    meta?: MetaResponse;
    error?: ErrorResponse;
}

Links can be removed. This can be useful if for example a signature should be revoked for any reason or a document amendment was faulty. However the original transaction that created the link in the first place is still available on blockchain. It is just invalidated with another transaction, but the audit trail of both actions will exist forever.

PATCH /assets/{assetId}/links

{
  "targetAssetIds": ["string"]
}