diff --git a/AEXS/aex-2.md b/AEXS/aex-2.md index 206adbe..9084b4a 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 +### JSON-RPC 2.0 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` - A unique identifier, must conform to the [UUID v4 standards](https://tools.ietf.org/html/rfc4122#page-14) + + ##### Returns + + Object` + + - `id` - same id as in the corresponding 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` - 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 - 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` - 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` - 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. - json-rpc 2.0 structure: - - ```jsonc - { - "jsonrpc": "2.0", - "method": "aepp.update.network", - "params": { - "id": "", - "network": "" - }, - "version": 1 - } - ``` + ##### Parameters + + `Object` + + - `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. #### 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` - 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`. + + ##### Returns + + `Object` + + - `id` - same id as in the corresponding 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` - 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. - 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` - 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. + + - `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` - 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. + + ##### Returns + + `Object` + + - `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. - 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` - 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` - 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. - json-rpc 2.0 structure: - - ```jsonc - { - "jsonrpc": "2.0", - "method": "wallet.disconnect.aepp", - "params": { - "id": "" - }, - "version": 1 - } - ``` + ##### Parameters + + `Object` + + - `id` - A 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