# Wake call mechanism 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](https://github.com/ontio-cyano). For application wake up call implementation, refer to this [demo](https://github.com/ontio-cyano/android-app-demo). The two parties involved in this process are: * The `dApp` : Blanket term that represents`dApps` 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`: ```javascript ontprovider://ont.io?param=Base64.encode(Uri.encode({the json data}.toString())) ``` ### dApp sends a login request ![](https://1077617372-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LvPXC4l2V4Z8gRDNIoZ%2F-LwHGzRX_2DAzQBtscV6%2F-LwHH0_-2UKqbwoZPJvI%2Fdappintegration-wake-login-1%20\(1\).jpg?generation=1576559724365884\&alt=media) 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 ![](https://1077617372-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LvPXC4l2V4Z8gRDNIoZ%2F-LwHGzRX_2DAzQBtscV6%2F-LwHH0_1osmYIllh2KZy%2Fdappintegration-wake-transaction-1%20\(1\).jpg?generation=1576559721038058\&alt=media) 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: ```yaml { "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: ```yaml { "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- ```yaml { "action": "login", "version": "v1.0.0", "id": "10ba038e-48da-487b-96e8-8d3b99b6d18a", "error": 0, "desc": "SUCCESS", "result": true } ``` Failure response after signature verification- ```yaml { "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ļ¼š ```yaml { "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 ```yaml { "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: ```yaml { "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 } } } ``` {% hint style="info" %} 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. {% endhint %} #### 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) {% hint style="info" %} 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. {% endhint %} ```yaml { "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](https://github.com/ontio/ontology-java-sdk/blob/master/docs/cn/interface.md#%E7%AD%BE%E5%90%8D%E9%AA%8C%E7%AD%BE) | [Java SDK](https://github.com/ontio/ontology-java-sdk/blob/master/docs/cn/basic.md#%E4%B8%8E%E9%93%BE%E4%BA%A4%E4%BA%92%E6%8E%A5%E5%8F%A3) | [Cyano - Android](https://github.com/ontio-cyano/cyano-android) | [Cyano - Android SDK](https://github.com/ontio-cyano/cyano-android-sdk) | [Cyano Bridge](https://github.com/ontio-cyano/cyano-bridge) | | [TypeScript SDK](https://github.com/ontio/ontology-ts-sdk/blob/master/test/ecdsa.crypto.test.ts) | [TypeScript SDK](https://github.com/ontio/ontology-ts-sdk/blob/master/test/websocket.test.ts) | [Cyano - iOS](https://github.com/ontio-cyano/cyano-ios) | [Cyano - iOS SDK](https://github.com/ontio-cyano/cyano-ios-sdk) | |