Back
dAPI tutorial
At 2018-11-05 By Panther

Note: This document from dapi-tutorial.

This tutorial is designed to give you an overview of creating a dApp using the Ontology dApp API (dAPI) and including the information on the tools required and shoulds en example dApp.

The document is broken down into the following sections:

Setting up the development environment

Ontology dAPI Overview

Running the demo project

Writing a smart contract for your dApp

Setting up the development environment

Please ensure you have the following installed and configured for use in your development environment.

Ontology dAPI Overview

dAPI Installation

The Ontology dAPI is the core API used to interface with the Ontology blockhain when creating a dApp and the repository can be found here. First you must install the npm package using: 

$ npm install ontology-dapi

dAPI Instantiation

To use the dAPI in your project, you need to import the library and then register as a client. Import and register the dAPI using:

import { client } from 'ontology-dapi';
 
client.registerClient({});

Example dAPI methods

Once imported and registered, use the provided dAPI methods in your dApp (see below).

Example blockchain methods
const network = await client.api.network.getNetwork();
const height = await client.api.network.getBlockHeight();
const block = await client.api.network.getBlock({ block: 1 });
const transaction = await client.api.network.getTransaction({txHash: '314e24e5bb0bd88852b2f13e673e5dcdfd53bdab909de8b9812644d6871bc05f'});
const balance = await client.api.network.getBalance({ address: 'AcyLq3tokVpkMBMLALVMWRdVJ83TTgBUwU' });
Example asset methods
const result = await client.api.asset.makeTransfer({ recipient, asset, amount });
Example Smart Contract methods
const result = await client.api.smartContract.invoke({contract,method,parameters,gasPrice,gasLimit,requireIdentity});
const result = await client.api.smartContract.invokeRead({ contract, method, parameters });
const result = await client.api.smartContract.deploy({code,name,version,author,email,description,needStorage,gasPrice,gasLimit});
Example Message methods
const message: string = values.message;
const signature: Signature = {
  data,
  publicKey
};
const result = await client.api.message.signMessage({ message });
const result = await client.api.message.verifyMessage({ message, signature });

A full list of methods can be found in the dAPI Specification document.


Running the demo project

Clone the dAPI demo which we will use to demonstrate functionality.

$ git clone https://github.com/OntologyCommunityDevelopers/ontology-dapi-demo.git
 
$ npm install
 
$ npm run start

This will start the demo which can be accessed using the Google Chrome browser at http://localhost:3000

Accessing this, select Provider->GetProvider.

dApp Demo Provider dApp Demo Get Provider

This will allow us to communicate with the Ontology Blockchain and make API calls. For example, selecting Network->Get Block results in the following:

dApp Demo getBlock

You can also initiate a transfer by selecting Asset->Make Transfer where you'll be automatically prompted to approve the transaction by Cyano Wallet. Click Confirm to approve the transaction.

Cyano Wallet Confirm

How to set gaslimit and gasprice

Each transaction contains a gas limit and a gas price. Gasprice will affect the time it takes for the transaction to be packaged. Currently, the minimum value of the main network and test network is 500.

The gaslimit is based on the complexity of the contract execution and can be queried by pre-execution. The Native contract calls gaslimit by default is 20000. The deployment contract is based on the contract, and the gaslimit is generally more than 20000000.

Writing a smart contract for your dApp

To support your dApp you will likely want to write a smart contract that acts as the back-end logic and storage. We use Ontology's SmartX tool for this. SmartX includes several template Smart Contracts to assist in development and further information can be found in the Smart Contract Tutorial

SmartX Login

Compiling and deploying your smart contract

SmartX uses Cyano Wallet to help with compiling, deploying and invoking the smart contract. Please make sure you have installed Cyano and created a Testnet account in it.

Compiling your smart contract

Use Smartx to Compile the smart contract.

smart contract deploy and invoke

Deploying your smart contract

Now that we have written our smart contract, the next steps are to deploy and invoke it. Deploying and Invoking requires Testnet ONG. If you dont have any already, please request testnet ONG in Discord

Deploy

Invoke

Testing your smart contract

In order to test the smart contract, you can use the smart contract automated testing framework or deploy your own Ontology privatenet running in testmode by downloading the latest Ontology release and starting it as below.

$ ./ontology --testmode