In-wallet applications
Launching applications in the mobile wallet
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 source code.
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 supportdAPI
, 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
methodUsing the
login
method
Step 3:dApp sends a contract invocation request
The steps involved-
dApp
sends invocation requestThe 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 thedApp
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
informationQuerying 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:
Data specification for the fields mentioned above-
Field | Data type | Description |
action | string | Operation type |
id | string | Serial number |
The data set of provider information that the wallet returns, after URI
and Base64
decoding, 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 |
dappName | string | dApp name |
dappIcon | string | dApp icon resource link |
The data set that the wallet returns, after URI
and Base64
decoding, has the following structure:
Login
The login request that the dApp
sends to the wallet 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-
Fields | Data type | Description |
action | string | Operation type |
type | string | Specifying the login method. ONT ID login is specified using "ontid", and wallet address login is specified as "address" |
dappName | string | dApp name |
dappIcon | string | dApp icon resource link |
message | string | Randomly generated, used for identity verification |
The wallet's response to the login request is of the following format after decoding:
Success response
Failure response
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.
Data specification for the fields mentioned above-
Field | Data type | Description |
action | string | Operation type |
type | string | Specifying the access method. ONT ID is specified using "ontid", and wallet address is specified as "address" |
message | string | Randomly generated, used for identity verification |
The wallet's success response to the request is of the following format after decoding:
Contract invocation
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 |
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 transaction is pre-executed
Wallet receives user confirmation
The transaction is transmitted onto the chain
Transaction hash is returned to the
dApp
The success response sent to the dApp
is:
The failure response sent to the dApp
is:
Pre-executing transactions
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:
MainNet - http://dappnode3.ont.io/
TestNet - http://polaris5.ont.io/
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.
dAPI provider SDK integration
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 Android and iOS platforms are available for reference.
Android SDK sample code
iOS SDK sample code
Code base for reference
Signature verification methods | Transaction event query methods | Cyano Wallet | dAPI - Mobile provider SDK | dAPI - Mobile client SDK |
Last updated