This section aims at assisting the developer with integrating the QR code protocol dAPI into a dApp. This would allow the user to carry out services like login, invoke smart contracts, and more by scanning QR codes.
The parties involved in the 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
The following charts illustrate the login and smart contract invocation process.
Login
dApp submits the QR code
The dApp server executes the login method
The dApp back end verifies the signature
Smart Contract Invocation
dApp submits the QR code
Provider initiates the transaction, the user authenticates and signs, the contract is pre-executed, the user confirms, the process is transmitted onto the chain, and at the end the transaction hash is returned to the dApp back end
dApp back end confirms whether the transaction event was a success or failure by querying the chain
dAPI protocol usage
The dAPI protocol currently supports login and smart contract deployment actions.
1. Login
The standard for supported QR codes:
{"action":"login","version":"v1.0.0","id":"10ba038e-48da-487b-96e8-8d3b99b6d18a","params": {"type":"ontid or account","dappName":"dapp Name","dappIcon":"link","message":"helloworld","expire":1546415363,// QR Code expire time"callback":"http://101.132.193.149:4027/blockchain/v1/common/test-onto-login" }}
Specification for the above fields-
dApp server side login interface
This interface is invoked after the wallet is done handling callback procedure. The server address must be an external IP address
method:post{"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"
}}
This process is analogous to the login protocol in every aspect, with the difference being when the dApp requests data signature the dApp name and icon are not required.
The QR code data of the data signature request looks like:
{"action":"signMessage","version":"v1.0.0","id":"10ba038e-48da-487b-96e8-8d3b99b6d18a","params": {"type":"ontid or address","message":"helloworld","ishex":false"callback": "http://101.132.193.149:4027/blockchain/v1/common/test-onto-login" }}
Multi-signature data model:
{"action":"signMultiMessage","version":"v1.0.0","id":"10ba038e-48da-487b-96e8-8d3b99b6d18a","params": {"type":"ontid or address","message": ["aabbccdd"],"ishex":true"callback": "http://101.132.193.149:4027/blockchain/v1/common/test-onto-login" }}
After the wallet's response is decoded by the URI decoder and the Base64 decoder, the resultant data follows the format illustrated below.
The success response returned to the callback address is of the form:
method:post{"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"
}}If the action is signMultiMessage, the result is an array
3. Smart Contract Invocation
Transactions are also a feature of smart contracts. Here's the standard for smart contract invocation QR code:
{"action":"invoke","version":"v1.0.0","id":"10ba038e-48da-487b-96e8-8d3b99b6d18a","params": {"login":true,"callback":"http://101.132.193.149:4027/invoke/callback","expire":1546415363,// QR code expiry"qrcodeUrl":"http://101.132.193.149:4027/qrcode/AUr5QUfeBADq6BMY6Tp5yuMsUNGpsD7nLZ" }}
The GET request content based on QR code's qrcodeUrl is as follows:
{"action":"invoke","version":"v1.0.0","id":"10ba038e-48da-487b-96e8-8d3b99b6d18a","params": {"invokeConfig": {"contractHash":"16edbe366d1337eb510c2ff61099424c94aeef02",//contract address"functions": [{"operation":"method name",//name of the method in the invoked smart contract"args": [{ //contract invocation arguments"name":"arg0-list",//argument index 1's value is an array "value": [true, 100, "Long:100000000000", "Address:AUr5QUfeBADq6BMY6Tp5yuMsUNGpsD7nLZ", "ByteArray:aabb", "String:hello", [true, 100], {
"key":6 }] }, {"name":"arg1-map",//argument index 2's value is a map"value": {"key":"String:hello","key1":"ByteArray:aabb","key2":"Long:100000000000","key3":true,"key4":100,"key5": [100],"key6": {"key":6 } } },{"name":"arg2-ByteArray",//argument index 3's value is a ByteArray"value":"ByteArray:aabbcc" },{"name":"arg3-int",//arguement index 4's value is int/long"value":100 },{"name":"arg4-str",//argument index 5's value is string"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.
When a smart contract is deployed, if the payer is not specified in the QR code, it is taken from the wallet. If the payer has been explicitly specified, the wallet verifies if the payer specified is identical with the wallet's asset address.
The provider initiates transactions, carries out user authentication and signature, pre-executes the contract, and finally passes the transaction has to the callback URL via POST method.
If the transaction succeeds, the wallet returns the following to callback:
