🔍Query Contracts

Explains how to read smart contract state.

To read from the contract state, you must first obtain the alias of your contract by checking the Dev3 Dashboard. If you haven't already done so, please refer to the Welcome to Dev3 to see how you can easily create your first project and create a test smart contract using the Dev3 Dashboard GUI.

Contract alias is a unique name assigned to every contract deployed from your own workspace. It is used to identify your contract and connect to the contract instance using the SDK.

You configure this alias when creating (deploying) smart contract.

Dev3 Dashboard | Contract details page

Then create the connection to the contract by providing the alias found on the dashboard (alias shown in the example above). Now you can query any smart contract function with a given name and parameters, as defined in the smart contract's function signature.

You can see the full list of supported contracts and their function signatures by reading their manifest files found on the central Dev3 contracts repository.

You can even add publish your own smart contracts and add them to the collection which is going to expose your contracts on the dashboard page and everyone will be able to deploy and interact with them. Contributing docs can be found here!

Function names can be found next to the contract's auto generated UI, when you open the contract interface on the dashboard, as shown below:

Function name, and parameters shown on the Dev3 Contract Interface.

In the example above, we want to read the 'Get allowance' function on the token contract. The function name is highlighted in the right part of the image, and you can actually copy/paste the function name from the dashboard itself. On the left part, in the two boxes, are the parameters this function is accepting, and you will provide the values for them in the SDK. This code will look like the snippet below:

const contractInstance = await sdk.getContractByAlias('<contract-alias>');

const functionName = '<contract-function-name>'; // Copy/paste from dashboard
const functionParams = [
    // function parameter values
]
const queryResult = await contractInstance.read(functionName, functionParams);
// result is returned in the queryResult object

The query result object contains the following data:

{
  deployed_contract_id?: string;    // contract id on the dev3 dashboard
  contract_address: string;         // contract address
  block_number: string;             // block height at which the data was queried
  timestamp: Date;                  // timestamp at which the data was queried
  return_values: string[];          // query result
}

As the functions can have different types of the return values, the type of this value is very generic: an array of strings (textual values). So for example, if your function returns only one integer, the return values field will look like this:

{
    // ... other query result fields
    return_values: [ '340' ] // function returned number 340
}

You can see the list of possibilities when encoding function parameters in the next section.

Live example

Run this flow on a live coding environment here