The following section serves to guide developers on how to enable wallets to support Ontology's dAPI, along with Provider SDK integration into mobile wallet apps. It may be worth referring to the respective open source Android and iOS wallet .
The two parties involved in the integration process are:
The dApp : Blanket term that representsdApps developed for the users of Ontology ecosystem.
The Provider: Wallets that support dAPI , and adhere to it's specifications.
Wallets that currently support the dAPI protocol:
Interaction process
The URI scheme that the dApp uses when sending requests:
The process can be broadly divided in the following manner:
Step 1：Wallet uses Webview to open dApps (H5 design)
Wallet uses Webview to open H5 dApps in the dApp store page layout
Step 2：dApp sends a request to fetch wallet's address
There are two ways to retrieve account information-
Using the getAccount method
Using the login method
Step 3：dApp sends a contract invocation request
The steps involved-
dApp sends invocation request
The wallet initiates transaction, carries out user authentication and signature
Wallet pre-executes the transaction
Transaction is transmitted to the blockchain
Wallet returns transaction hash to the dApp
dAPI protocol usage
The dAPI protocol is extensible in nature. It's core features can be laid out in terms of the following functions.
Querying Provider information
Querying wallet or account/identity related information
Authentication and login
Message signature
Smart contract invocation
Querying provider information
The query request that the dApp sends to the wallet to fetch the provider information is first encoded in URI and Base64, and then sent. The data is structured in the following manner:
Querying the wallet account or identity information
The query request that the dApp sends to the wallet to fetch the account or identity information is first encoded in URI and Base64, and then sent. The data is structured in the following manner:
Data specification for the fields mentioned above-
Field
Data type
Description
action
string
Operation type
result
string
The result to be returned
type
string
Specifying the login method. ONT ID login is specified using "ontid", and wallet address login is specified as "address"
user
string
The account used for signature, ONT ID or wallet address
message
string
Randomly generated, used for identity verification
publickey
string
Account's public key
signature
string
User's signature
Message signature
The structure remains the same as the login request, with the difference being that dApp name and icon are not needed. The request is encoded in URI and Base64, and then sent to the wallet.
Different invocation methods can be chosen using the action parameter. The available options are:
Parameter value
Function
invoke
Normal process
invokeRead
Pre-execute the contract, the user does not need to sign, the result is returned to the dApp
invokePasswordFree
Invoke without the need of authentication, user does not need to enter password
The invokePasswordFree function can be used for scenarios a contract needs to be invoked without prompting the user to enter their password. For example, games that stake money at regular intervals. Though, the use still needs to enter password once.
The platform only trusts fixed methods and parameters, and not all the methods that are part of the contract. After authentication, the transaction parameters are saved as ((InvokeCode)txs[0]).code
If another request that requires the same data is submitted, the user does not need to enter the password again, and the smart contract does not need to be pre-executed on more time.
When the user exits the dApp, please ensure that the parameters and the private key data are cleared from the memory.
dApp sends an invocation request
The data set of the request is encoded in URI and Base64 and sent out. The structure is:
Base58 addresses such as AUr5QUfeBADq6BMY6Tp5yuMsUNGpsD7nLZ can be assigned to the %address parameter, and the wallet will automatically assign it as the wallet's asset address. If the parameters contain an %ontid, the wallet will also automatically assign it to the wallet's ONT ID address.
Wallet responds to the invocation request
First the wallet carries out URI and Base64 decoding. And then,
Wallet initiates a transaction
Wallet carries out user authentication and signature
The amount of ONT and ONG that the user is going to expend in the transaction can be determined from the notify response, which is a result of the pre-execution.
A connection must be established with the following nodes:
It is advised to first completely analyze the notify response before making a judgement pertaining to a transaction, as there may be multiple transfers or events taking place. The nature of the token (ONT or ONG) can be determined from the contract address, while the transfer method and recipient can be determined later.
//init
CyanoWebView cyanoWebView=new CyanoWebView(context);
cyanoWebView.loadUrl(url);
//Action handle
cyanoWebView.getNativeJsBridge().setHandleGetAccount(new NativeJsBridge.HandleGetAccount() {
@Override
public void handleAction(String data) {
/* TODO
* 1.Send wallet address to webView
* com.alibaba.fastjson.JSONObject reqJson = JSON.parseObject(data);
* String action=reqJson.getString("action");
* String version=reqJson.getString("version");
* String id=reqJson.getString("id");
* cyanoWebView.sendSuccessToWeb(action,version, id, *wallet address*);
*/
}
});
cyanoWebView.getNativeJsBridge().setHandleInvoke(new NativeJsBridge.HandleInvoke() {
@Override
public void handleAction(String data) {
/* TODO
* 1. Password input prompt, resolve wallet account, build transaction using the data, carry out signature, pre-execute, note the processing time
*
* 2. Analyze the pre-execution notify reseponse, display transaction fees, if the result contains the contract address determine ONT/ONT, display recipient address and transfer amount
*
* 3. Transmit the transaction onto the chain after user confirmation
*
* 4. Send the transaction hash to webview
*
* com.alibaba.fastjson.JSONObject reqJson = JSON.parseObject(data);
* String action=reqJson.getString("action");
* String version=reqJson.getString("version");
* String id=reqJson.getString("id");
* cyanoWebView.sendSuccessToWeb(action,version, id, 交易 hash);
*/
}
});
cyanoWebView.getNativeJsBridge().setHandleInvokeRead(new NativeJsBridge.HandleInvokeRead() {
@Override
public void handleAction(String data) {
/* TODO
* 1. Build transaction using the data, note the processing time
*
* 2 Send the pre-execution results to webview
* com.alibaba.fastjson.JSONObject reqJson = JSON.parseObject(data);
* String action=reqJson.getString("action");
* String version=reqJson.getString("version");
* String id=reqJson.getString("id");
* cyanoWebView.sendSuccessToWeb(action,version, id, 预知行结果);
*/
}
});
cyanoWebView.getNativeJsBridge().setHandleInvokePasswordFree(new NativeJsBridge.HandleInvokePasswordFree() {
@Override
public void handleAction(String data, String message) {
/* TODO
* 1. Executing for the first time is the same as action : invoke, both the password and the message are saved
*
* 2. When the same request arrives for the second time, use the saved password for signature and fetch pre-execution result
*
* 3. The pre-execution results need not display for the user to confirmation
*
* 4. Send the transaction hash to the webview
* com.alibaba.fastjson.JSONObject reqJson = JSON.parseObject(data);
* String action=reqJson.getString("action");
* String version=reqJson.getString("version");
* String id=reqJson.getString("id");
* cyanoWebView.sendSuccessToWeb(action,version, id, 交易hash);
*/
}
});
//response
Map map = new HashMap<>();
map.put("action", "");
map.put("error", 0);
map.put("desc", "SUCCESS");
map.put("result", message);
cyanoWebView.sendBack(Base64.encodeToString(Uri.encode(JSON.toJSONString(map)).getBytes(), Base64.NO_WRAP));
dAPI provider SDK aids communication between Android webview and a web based dApp. It encapsulates a few methods for webview. Separate details with respect to and platforms are available for reference.
