Wake call mechanism

Applications wake the wallet service

This section aims at providing a guide to how the wallet uses the wake up service to support login and contract invocation functionality.

For wallet implementation, please refer to the Cyano open source wallet Github repository. For application wake up call implementation, refer to this demo.

The two parties involved in this 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.

Interaction process

dApp data request URI scheme:

ontprovider://ont.io?param=Base64.encode(Uri.encode({the json data}.toString()))

dApp sends a login request

1. dApp sends the wake up call to the wallet.

2. Wallet receives the callback URL the information to be verified. The user authenticates and signs, and the wallet invokes the dApp back end's callback method.

3. dApp back end verifies the signature.

dApp sends out the contract invocation request

1. dApp wakes the wallet

2. The wallet initiates a transaction, the user authenticates and signs, the wallet pre-executes the transaction, it is transmitted to the chain and finally the transaction hash is returned to the callback address.

3. dApp back end can query the results of the transaction event using the transaction hash.

dAPI protocol introduction

The requests sent by the dApp to the wallet to perform login and contract invocation functions are illustrated below.

Login

After URI and Base64 encoding, the structure of the request is as follows:

{
    "action": "login",
    "version": "v1.0.0",
    "id": "10ba038e-48da-487b-96e8-8d3b99b6d18a",    
    "params": {
        "type": "ontid or address",
        "dappName": "dapp Name",
        "dappIcon": "dapp Icon",
        "message": "helloworld",
        "callback": "http://127.0.0.1:80/login/callback"
    }
}

Field	Data type	Description
action	string	Operation type
type	string	Login method used, "ontid" if ONT ID is used to login and "address" when the wallet address is used to login
dappName	string	Name of the dApp
dappIcon	string	dApp icon resource link
message	string	Randomly generated message for identity verification
callback	string	Callback URL to send information to after the user carries out signature

Wallet carries out the login process, URI and Base 64 encoding, signs the message, and sends the following message to the callback address using POST method:

{
    "action": "login",
    "version": "v1.0.0",
    "id": "10ba038e-48da-487b-96e8-8d3b99b6d18a",    
    "params": {
        "type": "ontid or account",
        "user": "did:ont:AUEKhXNsoAT27HJwwqFGbpRy8QLHUMBMPz",
        "message": "helloworld",
        "publickey": "0205c8fff4b1d21f4b2ec3b48cf88004e38402933d7e914b2a0eda0de15e73ba61",
        "signature": "01abd7ea9d79c857cd838cabbbaad3efb44a6fc4f5a5ef52ea8461d6c055b8a7cf324d1a58962988709705cefe40df5b26e88af3ca387ec5036ec7f5e6640a1754"
    }
}

Fields	Data type	Description
action	string	Operation type
params	string	The parameters needed by methods
type	string	Login method used, "ontid" if ONT ID is used to login and "account" when the wallet address is used to login
user	string	Identifier of the account that is used for signature, say a wallet address or ONT ID
message	string	Randomly generated message for identity verification
publickey	string	Account public key
signature	string	Account digital signature

dApp server callback interface

Success response after signature verification-

{
  "action": "login",
  "version": "v1.0.0",  
  "id": "10ba038e-48da-487b-96e8-8d3b99b6d18a",  
  "error": 0,
  "desc": "SUCCESS",
  "result": true
}

Failure response after signature verification-

{
  "action": "login",
  "version": "v1.0.0",  
  "error": 80001,
  "desc": "PARAMS ERROR",
  "result": 1
}

Message signature

The signature protocol is essentially the same as login, only that the dApp name and icon need not be passed. The dApp sends a request with the following data, after URI and Base64 encoding：

{
    "action": "signMessage",
    "version": "v1.0.0",
    "id": "10ba038e-48da-487b-96e8-8d3b99b6d18a",
    "params": {
        "type": "ontid or address",
        "message": "helloworld"
    }
}

Field	Data type	Description
action	string	Operation type
type	string	Set to "ontid" if the login method is ONT ID, and "address" if the wallet address is used, set to "address" by default if nothing is specified
message	string	Generated randomly, used for identity verification

The wallet's response to the login request, sent after URI and Base64 encoding is of the following form-

Success response

{
    "action": "signMessage",
    "version": "v1.0.0",
    "id": "10ba038e-48da-487b-96e8-8d3b99b6d18a",
    "error": 0,
    "desc": "SUCCESS",
    "result": {
        "type": "ontid or address",
        "user": "did:ont:AUEKhXNsoAT27HJwwqFGbpRy8QLHUMBMPz or AUEKhXNsoAT27HJwwqFGbpRy8QLHUMBMPz",
        "message": "helloworld",
        "publickey": "0205c8fff4b1d21f4b2ec3b48cf88004e38402933d7e914b2a0eda0de15e73ba61",
        "signature": "01abd7ea9d79c857cd838cabbbaad3efb44a6fc4f5a5ef52ea8461d6c055b8a7cf324d1a58962988709705cefe40df5b26e88af3ca387ec5036ec7f5e6640a1754"
    }
}

Contract invocation

The data structure of the wake call that is sent to the wallet after URI and Base64 encoding is as follows:

{
    "action": "invoke",
    "version": "v1.0.0",
    "id": "10ba038e-48da-487b-96e8-8d3b99b6d18a",
    "params": {
        "login": true,
        "callback": "http://101.132.193.149:4027/invoke/callback",        
        "invokeConfig": {
            "contractHash": "16edbe366d1337eb510c2ff61099424c94aeef02",
            "functions": [{
                "operation": "method name",
                "args": [{
                    "name": "arg0-list",
                    "value": [true, 100, "Long:100000000000", "Address:AUr5QUfeBADq6BMY6Tp5yuMsUNGpsD7nLZ", "ByteArray:aabb", "String:hello", [true, 100], {
                        "key": 6
                    }]
                }, {
                    "name": "arg1-map",
                    "value": {
                        "key": "String:hello",
                        "key1": "ByteArray:aabb",
                        "key2": "Long:100000000000",
                        "key3": true,
                        "key4": 100,
                        "key5": [100],
                        "key6": {
                            "key": 6
                        }
                    }
                }, {
                    "name": "arg2-str",
                    "value": "String:test"
                }]
            }],
            "payer": "AUr5QUfeBADq6BMY6Tp5yuMsUNGpsD7nLZ",
            "gasLimit": 20000,
            "gasPrice": 500
        }
    }
}

A Base58 address, for e.g., AUr5QUfeBADq6BMY6Tp5yuMsUNGpsD7nLZ __can be used to fill the %address parameter. The wallet converts the %address to the wallet's asset address. If the argument contains the %ontid, the wallet converts it to the wallet's ontid address.

Pre-executing transactions

The notify result returned after pre-execution can be used to find out the token expended by the user in the particular transaction. (ONT/ONG)

The Notify message needs to be parsed to make a judgement, because a transaction may have multiple transfer or smart contract events. If the other contract events don't need to handled, then the nature of transferred tokens can be judged from the address i.e. ONT/ONG and the transfer method along with the sender.

{
    "Notify": [{
        "States": ["transfer", "AUr5QUfeBADq6BMY6Tp5yuMsUNGpsD7nLZ", "AecaeSEBkt5GcBCxwz1F41TvdjX3dnKBkJ", 1],
        "ContractAddress": "0100000000000000000000000000000000000000"
    }],
    "State": 1,
    "Gas": 20000,
    "Result": "01"
}

Code for reference

Signature verification methods	Transaction event query methods	Cyano Wallet	dAPI - Mobile provider SDK	dAPI - Mobile client SDK
Java SDK	Java SDK	Cyano - Android	Cyano - Android SDK	Cyano Bridge
TypeScript SDK	TypeScript SDK	Cyano - iOS	Cyano - iOS SDK