From 64152d91fe4c2f40f2c707139042dd9dc86acadd Mon Sep 17 00:00:00 2001 From: Shubhendu Shekhar Date: Wed, 22 May 2019 09:46:52 +0200 Subject: [PATCH 1/3] fixed formatting. removed json wherever possible. --- AEXS/aex-2.md | 392 +++++++++++++++++++------------------------------- 1 file changed, 149 insertions(+), 243 deletions(-) diff --git a/AEXS/aex-2.md b/AEXS/aex-2.md index 206adbe..b60431c 100644 --- a/AEXS/aex-2.md +++ b/AEXS/aex-2.md @@ -14,291 +14,197 @@ Created: 2019-03-04 ## Simple Summary -The document approaches the technical specification about how a wallet provider (ex. BaseApp, MetaMask) can interact with Aeternity enabled applications. +The document approaches the technical specification about how a wallet provider (ex. Base æpp, MetaMask) can interact with Aeternity enabled applications. ## Motivation -Currently, there exist no one standard way for wallets and SDK to communicate and everything developed on the SDK side is developed only keeping base-aepp in mind and rest of the wallet providers need to follow the same path. -By defining the standard way of communication between SDK(aepps) and Wallet we will not only reduce the dependency that other wallet providers have on base-aepp as well as we'll have a clear standard method of communication on the SDK side that can be further extended whenever required. +Currently, there exist no one standard way for wallets and SDK to communicate and everything developed on the SDK side is developed only keeping the Base æpp in mind and rest of the wallet providers need to follow the same path. +By defining the standard way of communication between SDK(aepps) and Wallet we will not only reduce the dependency that other wallet providers have on the Base æpp as well as we'll have a clear standard method of communication on the SDK side that can be further extended whenever required. ## Specification -### Protocol Messages +### Methods #### General -- `error`: used to communicate any error occurred. Each error object will contain the `request` that triggered it. - - json-rpc 2.0 structure: - - ```jsonc - { - "error": { - "code": 1, - "data": { - "request": {} - }, - "message": "" - }, - "id": null, - "jsonrpc": "2.0", - "version": 1 - } - ``` +- `ping/pong`: general ping/pong messages to check liveness. Implementation of this method is not mandatory for wallets communicating over a transport layer that have native support for liveness check. + + ##### Parameters + + `Object` + + - `id` - The unique identifier, must conform to the [UUID v4 standards](https://tools.ietf.org/html/rfc4122#page-14) + + ##### Returns + + Object` + + - `id` - The unique identifier as in request + - `data` - Value will always be equal to `pong` - ##### Types of errors - - **Code**|**Message**|**Meaning** - :-----:|:-----:|:-----: - 1|Transaction verification failed|returned when verification of signed transaction fails. - 2|Invalid transaction|returned by node for an invalid transaction. - 3|Broadcast Failed| returned when Aepp/SDK loses connection to the node and is unable to broadcast the transaction. - 4|Signature request denied|returned when wallet denies the signature request by Aepp/SDK. - 5|Get address request denied|returned when wallet denies the address request by Aepp/SDK. - 6|Invalid Address|returned by aepp when the address (or any address in a list) provided by wallet is invalid. - 7|Unknown Identifier| returned by aepp or wallet when the enclosing `id` is unknown to the receiving party or is missing entirely. - 8|Malformed Identifier| returned by aepp or wallet when the enclosing `id` does not conform to UUID v4 standards. - -- `ping/pong`: general ping/pong messages to check liveness. - - json-rpc 2.0 structure: - - ```jsonc - Ping: - { - "jsonrpc": "2.0", - "method": "ping", - "params": { - "id": "" - }, - "id": 1, - "version": 1 - } - - Pong: - { - "jsonrpc": "2.0", - "result": { - "id": "", - "data": "pong" - }, - "id": 1, - "version": 1 - } +- `error`: used to communicate any error occurred. Embedded `data` field in each error object MUST contain the `request` that triggered it. + + ##### JSON-RPC 2.0 Error Example: + + ```json + { + "error": { + "code": 1, + "data": { + "request": {} + }, + "message": "Transaction verification failed" + }, + "id": null, + "jsonrpc": "2.0" + } ``` + ##### Types of errors + + |**Code**|**Message**|**Meaning**| + |:-----:|:-----:|:-----:| + |1|Transaction verification failed|returned when verification of signed transaction fails.| + |2|Invalid transaction|returned by node for an invalid transaction.| + |3|Broadcast Failed| returned when Aepp/SDK loses connection to the node and is unable to broadcast the transaction.| + |4|Signature request denied|returned when wallet denies the signature request by Aepp/SDK.| + |5|Get address request denied|returned when wallet denies the address request by Aepp/SDK.| + |6|Invalid Address|returned by aepp when the address (or any address in a list) provided by wallet is invalid.| + |7|Unknown Identifier| returned by aepp or wallet when the enclosing `id` is unknown to the receiving party or is missing entirely.| + |8|Malformed Identifier| returned by aepp or wallet when the enclosing `id` does not conform to UUID v4 standards.| + |9|Unsupported Protocol Version| returned by aepp when it does not support protocol version the wallet wants to connect through. + #### SDK/Aepp -- `aepp.get.address`: request for current address. +- `aepp.get.address`: request for address from wallet. - json-rpc 2.0 structure: + ##### Parameters - ```jsonc - { - "jsonrpc": "2.0", - "method": "aepp.get.address", - "params": { - "id": "" - }, - "id": 1, - "version": 1 - } - ``` + `Object` + + - `id` - The unique identifier, must conform to the [UUID v4 standards](https://tools.ietf.org/html/rfc4122#page-14) - `aepp.request.sign`: request wallet for signature - json-rpc 2.0 structure: - - ```jsonc - Request: - { - "jsonrpc": "2.0", - "method": "aepp.request.sign", - "params": { - "id": "", - "tx": "" - }, - "id": 1, - "version": 1 - } - - Response: - { - "jsonrpc": "2.0", - "result": { - "id": "", - "tx": "" - }, - "id": 1, - "version": 1 - } - ``` + ##### Parameters + + `Object` + + - `id` - The unique identifier, must conform to the [UUID v4 standards](https://tools.ietf.org/html/rfc4122#page-14) + - `tx` - raw unsigned transaction + + ##### Returns + + `Object` + + - `id` - The unique identifier as in request + - `tx` - signed tx returned by the wallet - `aepp.update.network`: Message sent by Aepp/SDK asking wallet to update the network details. - json-rpc 2.0 structure: - - ```jsonc - { - "jsonrpc": "2.0", - "method": "aepp.update.network", - "params": { - "id": "", - "network": "" - }, - "version": 1 - } - ``` + ##### Parameters + + `Object` + + - `id` - The unique identifier, must conform to the [UUID v4 standards](https://tools.ietf.org/html/rfc4122#page-14) + + - `network` - Current network id used by the Aepp/SDK. #### Wallet -- `wallet.request.connect`: connection request sent by wallet containing an identifier that it wants to assign to the aepp/sdk. The generated identifier must be unique and must conform to the [UUID v4 standards](https://tools.ietf.org/html/rfc4122#page-14). - - json-rpc 2.0 structure: - - ```jsonc - Request: - { - "jsonrpc": "2.0", - "method": "wallet.request.connect", - "params": { - "id": "" - }, - "version": 1 - } - - Response: - { - "jsonrpc": "2.0", - "result": { - "id": "", - "name": "" - }, - "id": 1, - "version": 1 - } - ``` +- `wallet.request.connect`: connection request sent by the wallet containing an identifier that it wants to assign to the aepp/sdk. The provided identifier should be used for all the further communication between the aepp and wallet. + + ##### Parameters + + `Object` + + - `id` - The unique identifier, must conform to the [UUID v4 standards](https://tools.ietf.org/html/rfc4122#page-14) + - `name` - human readable wallet name + - `version` - protocol version. Currently defaults to `1`. + + ##### Returns + + `Object` + + - `id` - The unique identifier as in request + - `name` - human readable aepp name - `wallet.get.network`: get network details from sdk - json-rpc 2.0 structure: - - ```jsonc - { - "jsonrpc": "2.0", - "method": "wallet.get.network", - "params": { - "id": "" - }, - "version": 1 - } - ``` + ##### Parameters + + `Object` + + - `id` - The unique identifier, must conform to the [UUID v4 standards](https://tools.ietf.org/html/rfc4122#page-14) - `wallet.update.address`: used by wallet for sending requested address. wallet can also send the list of address of the wallets it is further connected to. - json-rpc 2.0 structure: - - ```jsonc - { - "jsonrpc": "2.0", - "method": "wallet.update.address", - "params": { - "id": "", - "address": { - "current": { - "
": { - // object with related metadata(optional) - } - }, - "connected": { - "": { - // object with related metadata(optional) - }, - "": { - // object with related metadata(optional) - } - } - } - }, - "version": 1 - } - ``` + ##### Parameters + + `Object` + + - `id` - The unique identifier, must conform to the [UUID v4 standards](https://tools.ietf.org/html/rfc4122#page-14) + - `address` - Object containing two objects named `current` and `connected`. + + - `current` - Object containing only a single account currently in use by the wallet. + + - `connected`(optional) - Object containing multiple connected accounts. + + ###### Example Account Format + + ```json + { + "current": { + "ak_2iBPH7HUz3cSDVEUWiHg76MZJ6tZooVNBmmxcgVK6VV8KAE688": { + "name": "this property is optional" + } + } + } + ``` - `wallet.broadcast.tx`: Ask Aepp/SDK to broadcast the transaction. If the Aepp/SDK is unable to broadcast it returns the `error` with code `3`. - json-rpc 2.0 structure: - - ```jsonc - Request: - { - "jsonrpc": "2.0", - "method": "wallet.broadcast.tx", - "params": { - "id": "", - "tx": "", - "verify": true/false - }, - "version": 1 - } - - Response: - { - "jsonrpc": "2.0", - "result": { - "id": "", - "tx_id": "" - }, - "id": 1, - "version": 1 - } - ``` + ##### Parameters + + `Object` + + - `id` - The unique identifier, must conform to the [UUID v4 standards](https://tools.ietf.org/html/rfc4122#page-14) + - `tx` - signed transaction to be broadcasted + - `verify` - Boolean. Perform verification before broadcasting or not. + + ##### Returns + + `Object` + + - `id` - The unique identifier as in request + - `tx_id` - transaction id of the broadcasted transaction - `wallet.verify.tx`: verify the tx from the SDK. On verification success, a response object is returned else with `status` field with a value `ok` else error with `code 1` is returned. - json-rpc 2.0 structure: - - ```jsonc - Request: - { - "jsonrpc": "2.0", - "method": "wallet.verify.tx", - "params": { - "id": "", - "tx": "" - }, - "id": 1, - "version": 1 - } - - Response: - { - "jsonrpc": "2.0", - "result": { - "id": "", - "status": "ok" - }, - "id": 1, - "version": 1 - } - ``` + ##### Parameters + + `Object` + + - `id` - The unique identifier, must conform to the [UUID v4 standards](https://tools.ietf.org/html/rfc4122#page-14) + - `tx` - signed transaction to be verified + + ##### Returns + + `Object` + + - `id` - The unique identifier as in request + - `status` - Value will always be equal to `ok` - `wallet.disconnect.aepp`: wallet lets the aepp know that it will disconnect. no further acknowledgement required. - json-rpc 2.0 structure: - - ```jsonc - { - "jsonrpc": "2.0", - "method": "wallet.disconnect.aepp", - "params": { - "id": "" - }, - "version": 1 - } - ``` + ##### Parameters + + `Object` + + - `id` - The unique identifier, must conform to the [UUID v4 standards](https://tools.ietf.org/html/rfc4122#page-14) ## Example Flow

- +

\ No newline at end of file From 6dc4956b8348e449341022c00070fb00dc16893b Mon Sep 17 00:00:00 2001 From: Shubhendu Shekhar Date: Thu, 23 May 2019 11:16:16 +0200 Subject: [PATCH 2/3] update heading --- AEXS/aex-2.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AEXS/aex-2.md b/AEXS/aex-2.md index b60431c..3830459 100644 --- a/AEXS/aex-2.md +++ b/AEXS/aex-2.md @@ -23,7 +23,7 @@ By defining the standard way of communication between SDK(aepps) and Wallet we w ## Specification -### Methods +### JSON-RPC 2.0 Methods #### General From 21da1b094320171999efcfd2f9d23925d58330c6 Mon Sep 17 00:00:00 2001 From: Shubhendu Shekhar Date: Fri, 24 May 2019 11:43:16 +0200 Subject: [PATCH 3/3] update language as suggested --- AEXS/aex-2.md | 32 ++++++++++++++++---------------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/AEXS/aex-2.md b/AEXS/aex-2.md index 3830459..9084b4a 100644 --- a/AEXS/aex-2.md +++ b/AEXS/aex-2.md @@ -33,13 +33,13 @@ By defining the standard way of communication between SDK(aepps) and Wallet we w `Object` - - `id` - The unique identifier, must conform to the [UUID v4 standards](https://tools.ietf.org/html/rfc4122#page-14) + - `id` - A unique identifier, must conform to the [UUID v4 standards](https://tools.ietf.org/html/rfc4122#page-14) ##### Returns Object` - - `id` - The unique identifier as in request + - `id` - same id as in the corresponding request - `data` - Value will always be equal to `pong` - `error`: used to communicate any error occurred. Embedded `data` field in each error object MUST contain the `request` that triggered it. @@ -82,7 +82,7 @@ By defining the standard way of communication between SDK(aepps) and Wallet we w `Object` - - `id` - The unique identifier, must conform to the [UUID v4 standards](https://tools.ietf.org/html/rfc4122#page-14) + - `id` - A unique identifier, must conform to the [UUID v4 standards](https://tools.ietf.org/html/rfc4122#page-14) - `aepp.request.sign`: request wallet for signature @@ -90,14 +90,14 @@ By defining the standard way of communication between SDK(aepps) and Wallet we w `Object` - - `id` - The unique identifier, must conform to the [UUID v4 standards](https://tools.ietf.org/html/rfc4122#page-14) + - `id` - A unique identifier, must conform to the [UUID v4 standards](https://tools.ietf.org/html/rfc4122#page-14) - `tx` - raw unsigned transaction ##### Returns `Object` - - `id` - The unique identifier as in request + - `id` - same id as in the corresponding request - `tx` - signed tx returned by the wallet - `aepp.update.network`: Message sent by Aepp/SDK asking wallet to update the network details. @@ -106,7 +106,7 @@ By defining the standard way of communication between SDK(aepps) and Wallet we w `Object` - - `id` - The unique identifier, must conform to the [UUID v4 standards](https://tools.ietf.org/html/rfc4122#page-14) + - `id` - A unique identifier, must conform to the [UUID v4 standards](https://tools.ietf.org/html/rfc4122#page-14) - `network` - Current network id used by the Aepp/SDK. @@ -118,7 +118,7 @@ By defining the standard way of communication between SDK(aepps) and Wallet we w `Object` - - `id` - The unique identifier, must conform to the [UUID v4 standards](https://tools.ietf.org/html/rfc4122#page-14) + - `id` - A unique identifier, must conform to the [UUID v4 standards](https://tools.ietf.org/html/rfc4122#page-14) - `name` - human readable wallet name - `version` - protocol version. Currently defaults to `1`. @@ -126,7 +126,7 @@ By defining the standard way of communication between SDK(aepps) and Wallet we w `Object` - - `id` - The unique identifier as in request + - `id` - same id as in the corresponding request - `name` - human readable aepp name - `wallet.get.network`: get network details from sdk @@ -135,7 +135,7 @@ By defining the standard way of communication between SDK(aepps) and Wallet we w `Object` - - `id` - The unique identifier, must conform to the [UUID v4 standards](https://tools.ietf.org/html/rfc4122#page-14) + - `id` - A unique identifier, must conform to the [UUID v4 standards](https://tools.ietf.org/html/rfc4122#page-14) - `wallet.update.address`: used by wallet for sending requested address. wallet can also send the list of address of the wallets it is further connected to. @@ -143,7 +143,7 @@ By defining the standard way of communication between SDK(aepps) and Wallet we w `Object` - - `id` - The unique identifier, must conform to the [UUID v4 standards](https://tools.ietf.org/html/rfc4122#page-14) + - `id` - A unique identifier, must conform to the [UUID v4 standards](https://tools.ietf.org/html/rfc4122#page-14) - `address` - Object containing two objects named `current` and `connected`. - `current` - Object containing only a single account currently in use by the wallet. @@ -168,7 +168,7 @@ By defining the standard way of communication between SDK(aepps) and Wallet we w `Object` - - `id` - The unique identifier, must conform to the [UUID v4 standards](https://tools.ietf.org/html/rfc4122#page-14) + - `id` - A unique identifier, must conform to the [UUID v4 standards](https://tools.ietf.org/html/rfc4122#page-14) - `tx` - signed transaction to be broadcasted - `verify` - Boolean. Perform verification before broadcasting or not. @@ -176,7 +176,7 @@ By defining the standard way of communication between SDK(aepps) and Wallet we w `Object` - - `id` - The unique identifier as in request + - `id` - same id as in the corresponding request - `tx_id` - transaction id of the broadcasted transaction - `wallet.verify.tx`: verify the tx from the SDK. On verification success, a response object is returned else with `status` field with a value `ok` else error with `code 1` is returned. @@ -185,15 +185,15 @@ By defining the standard way of communication between SDK(aepps) and Wallet we w `Object` - - `id` - The unique identifier, must conform to the [UUID v4 standards](https://tools.ietf.org/html/rfc4122#page-14) + - `id` - A unique identifier, must conform to the [UUID v4 standards](https://tools.ietf.org/html/rfc4122#page-14) - `tx` - signed transaction to be verified ##### Returns `Object` - - `id` - The unique identifier as in request - - `status` - Value will always be equal to `ok` + - `id` - same id as in the corresponding request + - `status` - Value will always be equal to `ok` - `wallet.disconnect.aepp`: wallet lets the aepp know that it will disconnect. no further acknowledgement required. @@ -201,7 +201,7 @@ By defining the standard way of communication between SDK(aepps) and Wallet we w `Object` - - `id` - The unique identifier, must conform to the [UUID v4 standards](https://tools.ietf.org/html/rfc4122#page-14) + - `id` - A unique identifier, must conform to the [UUID v4 standards](https://tools.ietf.org/html/rfc4122#page-14) ## Example Flow