Managing on-chain data

On-chain historical reputation data is handled by the Coreto DRT smart contract, deployed on the NEAR Protocol mainnet.

The smart contract receives and stores new Trust and Performance points variations for all connected accounts, and represents the data layer of the Coreto DRS.

The final Trust and Performance scores calculated by the Coreto Reputation Scoring Service algorithms are based on the Trust and Performance points variations stored by the Coreto DRT smart contract.

At the time of writing, there are two available options for interacting with the Coreto DRT smart contract:

• directly calling the available smart contract functions (requires an understanding of blockchain technology and smart contracts)

• using the Coreto DRT API as a web2 compatibility layer (requires an understanding of REST APIs)

The Coreto DRT API facilitates the interaction with the Coreto DRT smart contract, offering a simple REST API that maps to the smart contract methods.

Coreto DRT smart contract

The Coreto DRT smart contract is available on the NEAR mainnet and is used to record, store and access historical reputation data.

Coreto DRT smart contract address: drt1-service.coretois.near

Code: https://github.com/coreto-io/coreto-drt-smart-contract

Explorer: https://explorer.near.org/accounts/drt1-service.coretois.near

NEAR Protocol documentation: https://docs.near.org/

Coreto DRT API

The Coreto DRT API is accessible using standard HTTP calls and acts as a web2 compatibility layer on top of the Coreto DRT smart contract.

The hosted version of the API provided by the Coreto team is available at https://drt.coreto.io/.

Full API documentation can be found here: https://docs.coreto.io/api/

The API is built using the HAPI Framework. The API code is available as Open Source, and can also be self-hosted.

GitHub repository: https://github.com/coreto-io/coreto-drt-api

Storing reputation data on-chain

In order to store new reputation data on the Coreto DRT smart contract, you will need a dedicated NEAR wallet.

The platform's NEAR wallet acts as an access key for writing new data to the system. Access is granted by having the wallet approved as a data source, and will consume NEAR tokens as GAS (required by the NEAR Protocol) in order to record new data.

Learn more about GAS on NEAR Protocol: https://docs.near.org/concepts/basics/transactions/gas

Both the API and the direct smart contract options provide the same end results, and require the use of a dedicated NEAR wallet in order to write new data to the system.

New data records are sent as blockchain transactions to the smart contract, calling the respective functions with the new data payload sent as arguments.

Each new data record will be called an "action" moving forward.

Data structures

All recorded actions are stored based on the same base data structure described below:

{
  "caller_account_id": "string",   // string - The NEAR account ID of the caller
  "caller_private_key": "string",  // string - The NEAR private key of the caller
  "account_did": "string",         // string - The DID of the user account
  "action_date": "string",         // string($date) - The unix timestamp of the action (miliseconds)
  "action_type": "string",         // string - The type of the action
  "trust": 0,                      // number - The trust variation value of the action
  "performance": 0,                // number - The performance variation value of the action
  "identifier": "string"           // string - (Optional) Unique identifier of the related action found on the source platform
}

*All fields are required except the identifier field. Data should be sent as a valid JSON object.

The trust and performance fields represent the numerical value of Trust and Performance points added or substracted from the targeted account_did (decentralized ID) based on the results of the activity corresponding to the recorded action.

The action_date field represents the UNIX timestamp (in miliseconds) of the moment the action has been completed on the source platform's system, and can differ from the exact moment the action is recorded on-chain by the DRT smart contract.

The action_type field represents the type or category of actions that the recorded action should be stored under, and acts as a top-level taxonomy tag.

The caller_account_id and caller_private_key represent the platform's NEAR wallet account name and private key, and are used in order to authenticate the request.

Available methods

Actions can be recorded individually by calling the save_action method with the above payload data structure, or by batching together multiple actions.

API reference for the save_action method: https://docs.coreto.io/api/#/drt/postDrtSave_action

Recording actions in batches can be done by calling the save_actions_batch method with the following the data structure:

{
  "caller_account_id": "string",
  "caller_private_key": "string",
  "batch": [
    {
      "account_did": "string",
      "action_date": "string",
      "action_type": "string",
      "trust": 0,
      "performance": 0,
      "identifier": "string"
    }
  ]
}

All fields keep their respective definitions and types.

API reference for the save_actions_batch method: https://docs.coreto.io/api/#/drt/postDrtSave_actions_batch

IMPORTANT

There is a limit of 300Tgas that can be allocated for each transaction on NEAR.

When recording actions on-chain, the more actions are added as part of a batch, the more Tgas will be needed to execute the transaction.

This means that if there are too many actions added to a single batch, the transaction can fail due to hitting the Tgas limit, and the actions will not be recorded on-chain by the DRT smart contract.

In our tests so far, around 7-10 Tgas are needed in order to record a single action.

Remember that this is a rough estimate, and the actual Tgas used for each transaction will depend on the actual payload data and can be greater than our estimates.

Reading on-chain data

Reading historical reputation data from the Coreto DRT smart contract does not require any special permissions (no prior approval is necessary), and does not consume NEAR or any other tokens as GAS (reading data is free on the NEAR Protocol blockchain).

Historical data managed by the Coreto DRT is catalogued by source and type and can be filtered based on the source's label and the actions' action_type field.

Every source will have different specific action types depending on the type of platform it serves and the multiple diferent use cases it handles.

In order to read historical reputation data for an account, you can call the get_user_actions method. This will return all recorded actions for that account for a specific source.

If you only need the recorded actions that have modified the Trust or the Performance of the account, you can use the get_user_trust_actions or get_user_performance_actions respectively.

All methods require two parameters:

{
  "source_label": "string",
  "account_did": "string"
}

• source_label - the label associated with the approved source that has recorded those actions

• account_did - the DID key that is associated to the account you want to get the data for

API reference for the available methods:

• get_user_actions - https://docs.coreto.io/api/#/drt/postDrtGet_user_actions

• get_user_trust_actions - https://docs.coreto.io/api/#/drt/postDrtGet_user_trust_actions

• get_user_performance_actions - https://docs.coreto.io/api/#/drt/postDrtGet_user_performance_actions

The historical reputation data stored by the Coreto DRT can provide valuable insight into what influences each participating account's reputation, and can be a great source for raw statistical and research data.