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"
    }
}

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"
    }
}

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"
    }
}

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

Last updated