How to Use dAPI
<h1 align="center">How to Use dAPI</h1>
<p align="center" class="version">Version 0.1</p>
1. What is dAPI
DAPI is API for dApps on Ontology blockchain. This is an implementation of dAPI from OEP-6 communication protocol. dApp developers can call the dAPI interface to interact with the Ontology blockchain and Chrome plug-in wallet, supporting query chain information, assets, digital identities, smart contracts, and more.
The library is written in TypeScript, so all the methods and objects are typed. It is therefore usable in TypeScript projects as well as JavaScript projects.
Features:
- The security issue of dApps is transferred to the dAPI provider. Users do not have to worry about security issues such as assets when they are in dApps.
- The interface is easy to integrate.
Note: It is necessary to have installed suitable dAPI provider . Reference implementation is How to Use Cyano Wallet.
2. OEP6 architecture
The interaction between dApp and Ontology network can be described with this diagram:
architecture
Yellow colored components are external to OEP-6 proposal.
Green colored components represent dAPI.js. It is universal implementation of communication channel for direct use by dApp developers in web browsers.
Blue colored components belong to specific implementation of dAPI provider. The implementation is out of scope of this proposal, but the implementator must adhere to the protocol used by dAPI.js.
The communication protocol has RPC style of communication. The RPC is modeled on top of standard WebExtension message passing using runtime.sendMessage and runtime.onMessage.addListener. All the complications of WebExtension is hidden for both the dApp and dAPI provider when using dAPI.js.
dAPI providers might use dAPI.js as the communication protocol, but they can also implement different protocols suitable for the specific environment (e.g: iOS, Android, Desktop).
3. How to install and use dAPI
3.1 Setting up the development environment
Please ensure you have the following installation and configuration in order to setup the development environment.
3.2 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
3.3 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({});
3.4 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.
4. 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
cd ontology-dapi-demo
npm install
npm run start
The code will start the demo which can be accessed using the Google Chrome browser at http://localhost:3000.
By selecting Provider->GetProvider, you can get the info of dAPI provider.
dApp Demo Provider
dApp Demo Get Provider
The function of the network allows us to communicate with the Ontology Blockchain and make API calls. For example, We can get the following result by selecting Network->Get Block.
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
