diff --git a/ARCs/arc-0027.md b/ARCs/arc-0027.md new file mode 100644 index 000000000..ff64343cc --- /dev/null +++ b/ARCs/arc-0027.md @@ -0,0 +1,1687 @@ +--- +arc: 27 +title: Provider Message Schema +description: A comprehensive message schema for communication between clients and providers. +author: Kieran O'Neill (@kieranroneill) +status: Review +type: Standards Track +category: Interface +created: 2023-12-24 +--- + +# Provider Message Schema + +## Abstract + +Building off of the work of the previous ARCs relating to; provider transaction signing ([ARC-0005][arc-0005]), provider address discovery ([ARC-0006][arc-0006]), provider transaction network posting ([ARC-0007][arc-0007]) and provider transaction signing & posting ([ARC-0008][arc-0008]), this proposal aims to comprehensively outline a common message schema between clients and providers. + +Furthermore, this proposal extends the aforementioned methods to encompass new functionality such as: + +* Extending the message structure to target specific networks, thereby supporting multiple AVM (Algorand Virtual Machine) chains. +* Adding a new method that disables clients on providers. +* Adding a new method to discover provider capabilities, such as what networks and methods are supported. + +This proposal serves as a formalization of the message schema and leaves the implementation details to the prerogative of the clients and providers. + +[Back to top ^][top] + +## Motivation + +The previous ARCs relating to client/provider communication ([ARC-0005](./arc-0005.md), [ARC-0006](./arc-0006.md), [ARC-0007](./arc-0007.md) and [ARC-0008](./arc-0008.md) serve as the foundation of this proposal. However, this proposal attempts to bring these previous ARCs together and extend their functionality as some of the previous formats did not allow for very much robustness when it came to targeting a specific AVM chain. + +More methods have been added in an attempt to "fill in the gaps" of the previous client/provider communication ARCS. + +[Back to top ^][top] + +## Specification + +The key words "**MUST**", "**MUST NOT**", "**REQUIRED**", "**SHALL**", "**SHALL NOT**", "**SHOULD**", "**SHOULD NOT**", "**RECOMMENDED**", "**MAY**", and "**OPTIONAL**" in this document are to be interpreted as described in RFC-2119. + +> Comments like this are non-normative. + +### Definitions + +This section is non-normative. + +* Client + - An end-user application that interacts with a provider; e.g. a dApp. +* Provider + - An application that manages private keys and performs signing operations; e.g. a wallet. + +[Back to top ^][top] + +### Message Reference Naming + +In order for each message to be identifiable, each message **MUST** contain a `reference` property. Furthermore, this `reference` property **MUST** conform to the following naming convention: + +``` +[namespace]:[method]:[type] +``` +where: +* `namespace`: + - **MUST** be `arc0027` +* `method`: + - **MUST** be in snake case + - **MUST** be one of `disable`, `discover`, `enable`, `post_transactions`, `sign_and_post_transactions`, `sign_message` or `sign_transactions` +* `type`: + - **MUST** be one of `request` or `response` + +This convention ensures that each message can be identified and handled. + +[Back to top ^][top] + +### Supported Methods + +| Name | Summary | Example | +|------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------| +| `disable` | Removes access for the clients on the provider. What this looks like is the prerogative of the provider. | [here](#disable-example) | +| `discover` | Sent by a client to discover the available provider(s). If the `params.providerId` property is supplied, only the provider with the matching ID **SHOULD** respond. This method is usually called before other methods as it allows the client to identify provider(s), the networks the provider(s) supports and the methods the provider(s) supports on each network. | [here](#discover-example) | +| `enable` | Requests that a provider allow a client access to the providers' accounts. The response **MUST** return a user-curated list of available addresses. Providers **SHOULD** create a "session" for the requesting client, what this should look like is the prerogative of the provider(s) and is beyond the scope of this proposal. | [here](#enable-example) | +| `post_transactions` | Sends a list of signed transactions to be posted to the network by the provider. | [here](#post-transactions-example) | +| `sign_and_post_transactions` | Sends a list of signed transactions to be posted to the network by the provider. | [here](#sign-and-post-transactions-example) | +| `sign_message` | Sends a UTF-8 encoded message to be signed by the provider. | [here](#sign-message-example) | +| `sign_transactions` | Sends a list of transactions to be signed by the provider. | [here](#sign-transactions-example) | + +[Back to top ^][top] + +### Request Message Schema + +```json +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "/schemas/request-message", + "title": "Request Message", + "description": "Outlines the structure of a request message", + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "A globally unique identifier for the message", + "format": "uuid" + }, + "reference": { + "description": "Identifies the purpose of the message", + "enum": [ + "arc0027:disable:request", + "arc0027:discover:request", + "arc0027:enable:request", + "arc0027:post_transactions:request", + "arc0027:sign_and_post_transactions:request", + "arc0027:sign_message:request", + "arc0027:sign_transactions:request" + ] + } + }, + "allOf": [ + { + "if": { + "properties": { + "reference": { + "const": "arc0027:disable:request" + } + }, + "required": ["id", "reference"] + }, + "then": { + "properties": { + "params": { + "$ref": "/schemas/disable-params" + } + } + } + }, + { + "if": { + "properties": { + "reference": { + "const": "arc0027:discover:request" + } + }, + "required": ["id", "reference"] + }, + "then": { + "properties": { + "params": { + "$ref": "/schemas/discover-params" + } + } + } + }, + { + "if": { + "properties": { + "reference": { + "const": "arc0027:enable:request" + } + }, + "required": ["id", "reference"] + }, + "then": { + "properties": { + "params": { + "$ref": "/schemas/enable-params" + } + } + } + }, + { + "if": { + "properties": { + "reference": { + "const": "arc0027:post_transactions:request" + } + }, + "required": ["id", "params", "reference"] + }, + "then": { + "properties": { + "params": { + "$ref": "/schemas/post-transactions-params" + } + } + } + }, + { + "if": { + "properties": { + "reference": { + "const": "arc0027:sign_and_post_transactions:request" + } + }, + "required": ["id", "params", "reference"] + }, + "then": { + "properties": { + "params": { + "$ref": "/schemas/sign-and-post-transactions-params" + } + } + } + }, + { + "if": { + "properties": { + "reference": { + "const": "arc0027:sign_message:request" + } + }, + "required": ["id", "params", "reference"] + }, + "then": { + "properties": { + "params": { + "$ref": "/schemas/sign-message-params" + } + } + } + }, + { + "if": { + "properties": { + "reference": { + "const": "arc0027:sign_transactions:request" + } + }, + "required": ["id", "params", "reference"] + }, + "then": { + "properties": { + "params": { + "$ref": "/schemas/sign-transactions-params" + } + } + } + } + ] +} +``` +where: +* `id`: + - **MUST** be a UUIDv4 compliant string +* `reference`: + - **MUST** be a string that conforms to the [message reference naming](#message-reference-naming) convention + +[Back to top ^][top] + +#### Param Definitions + +##### Disable Params + +```json +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "/schemas/disable-params", + "title": "Disable Params", + "description": "Disables a previously enabled client with any provider(s)", + "type": "object", + "properties": { + "genesisHash": { + "type": "string", + "description": "The unique identifier for the network that is the hash of the genesis block" + }, + "providerId": { + "type": "string", + "description": "A unique identifier for the provider", + "format": "uuid" + }, + "sessionIds": { + "type": "array", + "description": "A list of specific session IDs to remove", + "items": { + "type": "string" + } + } + }, + "required": ["providerId"] +} +``` +where: +* `genesisHash`: + - **OPTIONAL** if omitted, the provider **SHOULD** assume the "default" network + - **MUST** be a base64 encoded hash of the genesis block of the network +* `providerId`: + - **MUST** be a UUIDv4 compliant string +* `sessionIds`: + - **OPTIONAL** if omitted, all sessions must be removed + - **MUST** remove all sessions if the list is empty + +[Back to top ^][top] + +##### Discover Params + +```json +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "/schemas/discover-params", + "title": "Discover Params", + "description": "Gets a list of available providers", + "type": "object", + "properties": { + "providerId": { + "type": "string", + "description": "A unique identifier for the provider", + "format": "uuid" + } + } +} +``` +where: +* `providerId`: + - **OPTIONAL** if omitted, all providers **MAY** respond + - **MUST** be a UUIDv4 compliant string + +[Back to top ^][top] + +##### Enable Params + +```json +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "/schemas/enable-params", + "title": "Enable Params", + "description": "Asks provider(s) to enable the requesting client", + "type": "object", + "properties": { + "genesisHash": { + "type": "string", + "description": "The unique identifier for the network that is the hash of the genesis block" + }, + "providerId": { + "type": "string", + "description": "A unique identifier for the provider", + "format": "uuid" + } + }, + "required": ["providerId"] +} +``` +where: +* `genesisHash`: + - **OPTIONAL** if omitted, the provider **SHOULD** assume the "default" network + - **MUST** be a base64 encoded hash of the genesis block of the network +* `providerId`: + - **MUST** be a UUIDv4 compliant string + +[Back to top ^][top] + +##### Post Transactions Params + +```json +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "/schemas/post-transactions-params", + "title": "Post Transactions Params", + "description": "Sends a list of signed transactions to be posted to the network by the provider(s)", + "type": "object", + "properties": { + "providerId": { + "type": "string", + "description": "A unique identifier for the provider", + "format": "uuid" + }, + "stxns": { + "type": "array", + "description": "A list of signed transactions to be posted to the network by the provider(s)", + "items": { + "type": "string" + } + } + }, + "required": [ + "providerId", + "stxns" + ] +} +``` +where: +* `providerId`: + - **MUST** be a UUIDv4 compliant string +* `stxns`: + - **MUST** be the base64 encoding of the canonical msgpack encoding of a signed transaction as defined in [ARC-1](./arc-0001.md#interface-signedtxnstr) + - **MAY** be empty + +[Back to top ^][top] + +##### Sign And Post Transactions Params + +```json +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "/schemas/sign-and-post-transactions-params", + "title": "Sign And Post Transactions Params", + "description": "Sends a list of transactions to be signed and posted to the network by the provider(s)", + "type": "object", + "properties": { + "providerId": { + "type": "string", + "description": "A unique identifier for the provider", + "format": "uuid" + }, + "txns": { + "type": "array", + "description": "A list of transactions to be signed and posted to the network by the provider(s)", + "items": { + "type": "object", + "properties": { + "authAddr": { + "type": "string", + "description": "The auth address if the sender has rekeyed" + }, + "msig": { + "type": "object", + "description": "Extra metadata needed when sending multisig transactions", + "properties": { + "addrs": { + "type": "array", + "description": "A list of Algorand addresses representing possible signers for the multisig", + "items": { + "type": "string" + } + }, + "threshold": { + "type": "integer", + "description": "Multisig threshold value" + }, + "version": { + "type": "integer", + "description": "Multisig version" + } + } + }, + "signers": { + "type": "array", + "description": "A list of addresses to sign with", + "items": { + "type": "string" + } + }, + "stxn": { + "type": "string", + "description": "The base64 encoded signed transaction" + }, + "txn": { + "type": "string", + "description": "The base64 encoded unsigned transaction" + } + }, + "required": ["txn"] + } + } + }, + "required": [ + "providerId", + "txns" + ] +} +``` +where: +* `providerId`: + - **MUST** be a UUIDv4 compliant string +* `txns`: + - **MUST** have each item conform to the semantic of a transaction in [ARC-1](./arc-0001.md#semantic-of-wallettransaction) + - **MAY** be empty + +[Back to top ^][top] + +##### Sign Message Params + +```json +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "/schemas/sign-message-params", + "title": "Sign Message Params", + "description": "Sends a UTF-8 encoded message to be signed by the provider(s)", + "type": "object", + "properties": { + "message": { + "type": "string", + "description": "The string to be signed by the provider" + }, + "providerId": { + "type": "string", + "description": "A unique identifier for the provider", + "format": "uuid" + }, + "signer": { + "type": "string", + "description": "The address to be used to sign the message" + } + }, + "required": [ + "message", + "providerId" + ] +} +``` +where: +* `message`: + - **MUST** be a string that is compatible with the UTF-8 character set as defined in RFC-2279 +* `providerId`: + - **MUST** be a UUIDv4 compliant string +* `signer`: + - **MUST** be a base32 encoded public key with a 4 byte checksum appended as defined in keys and addresses + +[Back to top ^][top] + +##### Sign Transactions Params + +```json +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "/schemas/sign-transactions-params", + "title": "Sign Transactions Params", + "description": "Sends a list of transactions to be signed by the provider(s)", + "type": "object", + "properties": { + "providerId": { + "type": "string", + "description": "A unique identifier for the provider", + "format": "uuid" + }, + "txns": { + "type": "array", + "description": "A list of transactions to be signed by the provider(s)", + "items": { + "type": "object", + "properties": { + "authAddr": { + "type": "string", + "description": "The auth address if the sender has rekeyed" + }, + "msig": { + "type": "object", + "description": "Extra metadata needed when sending multisig transactions", + "properties": { + "addrs": { + "type": "array", + "description": "A list of Algorand addresses representing possible signers for the multisig", + "items": { + "type": "string" + } + }, + "threshold": { + "type": "integer", + "description": "Multisig threshold value" + }, + "version": { + "type": "integer", + "description": "Multisig version" + } + } + }, + "signers": { + "type": "array", + "description": "A list of addresses to sign with", + "items": { + "type": "string" + } + }, + "stxn": { + "type": "string", + "description": "The base64 encoded signed transaction" + }, + "txn": { + "type": "string", + "description": "The base64 encoded unsigned transaction" + } + }, + "required": ["txn"] + } + } + }, + "required": [ + "providerId", + "txns" + ] +} +``` +where: +* `providerId`: + - **MUST** be a UUIDv4 compliant string +* `txns`: + - **MUST** have each item conform to the semantic of a transaction in [ARC-1](./arc-0001.md#semantic-of-wallettransaction) + - **MAY** be empty + +[Back to top ^][top] + +### Response Message Schema + +```json +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "/schemas/response-message", + "title": "Response Message", + "description": "Outlines the structure of a response message", + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "A globally unique identifier for the message", + "format": "uuid" + }, + "reference": { + "description": "Identifies the purpose of the message", + "enum": [ + "arc0027:disable:response", + "arc0027:discover:response", + "arc0027:enable:response", + "arc0027:post_transactions:response", + "arc0027:sign_and_post_transactions:response", + "arc0027:sign_message:response", + "arc0027:sign_transactions:response" + ] + }, + "requestId": { + "type": "string", + "description": "The ID of the request message", + "format": "uuid" + } + }, + "allOf": [ + { + "if": { + "properties": { + "reference": { + "const": "arc0027:disable:response" + } + }, + "required": ["id", "reference", "requestId"] + }, + "then": { + "oneOf": [ + { + "properties": { + "result": { + "$ref": "/schemas/disable-result" + } + } + }, + { + "properties": { + "error": { + "$ref": "/schemas/error" + } + } + } + ] + } + }, + { + "if": { + "properties": { + "reference": { + "const": "arc0027:discover:response" + } + }, + "required": ["id", "reference", "requestId"] + }, + "then": { + "oneOf": [ + { + "properties": { + "result": { + "$ref": "/schemas/discover-result" + } + } + }, + { + "properties": { + "error": { + "$ref": "/schemas/error" + } + } + } + ] + } + }, + { + "if": { + "properties": { + "reference": { + "const": "arc0027:enable:response" + } + }, + "required": ["id", "reference", "requestId"] + }, + "then": { + "oneOf": [ + { + "properties": { + "result": { + "$ref": "/schemas/enable-result" + } + } + }, + { + "properties": { + "error": { + "$ref": "/schemas/error" + } + } + } + ] + } + }, + { + "if": { + "properties": { + "reference": { + "const": "arc0027:post_transactions:response" + } + }, + "required": ["id", "reference", "requestId"] + }, + "then": { + "oneOf": [ + { + "properties": { + "result": { + "$ref": "/schemas/post-transactions-result" + } + } + }, + { + "properties": { + "error": { + "$ref": "/schemas/error" + } + } + } + ] + } + }, + { + "if": { + "properties": { + "reference": { + "const": "arc0027:sign_and_post_transactions:response" + } + }, + "required": ["id", "reference", "requestId"] + }, + "then": { + "oneOf": [ + { + "properties": { + "result": { + "$ref": "/schemas/sign-and-post-transactions-result" + } + } + }, + { + "properties": { + "error": { + "$ref": "/schemas/error" + } + } + } + ] + } + }, + { + "if": { + "properties": { + "reference": { + "const": "arc0027:sign_message:response" + } + }, + "required": ["id", "reference", "requestId"] + }, + "then": { + "oneOf": [ + { + "properties": { + "result": { + "$ref": "/schemas/sign-message-result" + } + } + }, + { + "properties": { + "error": { + "$ref": "/schemas/error" + } + } + } + ] + } + }, + { + "if": { + "properties": { + "reference": { + "const": "arc0027:sign_transactions:response" + } + }, + "required": ["id", "reference", "requestId"] + }, + "then": { + "oneOf": [ + { + "properties": { + "result": { + "$ref": "/schemas/sign-transactions-result" + } + } + }, + { + "properties": { + "error": { + "$ref": "/schemas/error" + } + } + } + ] + } + } + ] +} +``` +* `id`: + - **MUST** be a UUIDv4 compliant string +* `reference`: + - **MUST** be a string that conforms to the [message reference naming](#message-reference-naming) convention +* `requestId`: + - **MUST** be the ID of the origin request message + +[Back to top ^][top] + +#### Result Definitions + +##### Disable Result + +```json +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "/schemas/disable-result", + "title": "Disable Result", + "description": "The response from a disable request", + "type": "object", + "properties": { + "genesisHash": { + "type": "string", + "description": "The unique identifier for the network that is the hash of the genesis block" + }, + "genesisId": { + "type": "string", + "description": "A human-readable identifier for the network" + }, + "providerId": { + "type": "number", + "description": "A unique identifier for the provider", + "format": "uuid" + }, + "sessionIds": { + "type": "array", + "description": "A list of specific session IDs that have been removed", + "items": { + "type": "string" + } + } + }, + "required": [ + "genesisHash", + "genesisId", + "providerId" + ] +} +``` +where: +* `genesisHash`: + - **MUST** be a base64 encoded hash of the genesis block of the network +* `providerId`: + - **MUST** be a UUIDv4 compliant string + - **MUST** uniquely identify the provider + +[Back to top ^][top] + +##### Discover Result + +```json +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "/schemas/discover-result", + "title": "Discover Result", + "description": "The response from a discover request", + "type": "object", + "properties": { + "host": { + "type": "string", + "description": "A domain name of the provider" + }, + "icon": { + "type": "string", + "description": "A URI pointing to an image" + }, + "name": { + "type": "string", + "description": "A human-readable canonical name of the provider" + }, + "networks": { + "type": "array", + "description": "A list of networks available for the provider", + "items": { + "type": "object", + "properties": { + "genesisHash": { + "type": "string", + "description": "The unique identifier for the network that is the hash of the genesis block" + }, + "genesisId": { + "type": "string", + "description": "A human-readable identifier for the network" + }, + "methods": { + "type": "array", + "description": "A list of methods available from the provider for the chain", + "items": { + "enum": [ + "disable", + "enable", + "post_transactions", + "sign_and_post_transactions", + "sign_message", + "sign_transactions" + ] + } + } + }, + "required": [ + "genesisHash", + "genesisId", + "methods" + ] + } + }, + "providerId": { + "type": "string", + "description": "A globally unique identifier for the provider", + "format": "uuid" + } + }, + "required": [ + "name", + "networks", + "providerId" + ] +} +``` +where: +* `host`: + - **RECOMMENDED** a URL that points to a live website +* `icon`: + - **RECOMMENDED** be a URI that conforms to [RFC-2397] + - **SHOULD** be a URI that points to a square image with a 96x96px minimum resolution + - **RECOMMENDED** image format to be either lossless or vector based such as PNG, WebP or SVG +* `name`: + - **SHOULD** be human-readable to allow for display to a user +* `networks`: + - **MAY** be empty +* `networks.genesisHash`: + - **MUST** be a base64 encoded hash of the genesis block of the network +* `networks.methods`: + - **SHOULD** be one or all of `disable`, `enable`, `post_transactions`, `sign_and_post_transactions`, `sign_message` or `sign_transactions` + - **MAY** be empty +* `providerId`: + - **MUST** be a UUIDv4 compliant string + - **MUST** uniquely identify the provider + +[Back to top ^][top] + +##### Enable Result + +```json +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "/schemas/enable-result", + "title": "Enable Result", + "description": "The response from an enable request", + "type": "object", + "properties": { + "accounts": { + "type": "array", + "description": "A list of accounts available for the provider", + "items": { + "type": "object", + "properties": { + "address": { + "type": "string", + "description": "The address of the account" + }, + "name": { + "type": "string", + "description": "A human-readable name for this account" + } + }, + "required": ["address"] + } + }, + "genesisHash": { + "type": "string", + "description": "The unique identifier for the network that is the hash of the genesis block" + }, + "genesisId": { + "type": "string", + "description": "A human-readable identifier for the network" + }, + "providerId": { + "type": "string", + "description": "A unique identifier for the provider", + "format": "uuid" + }, + "sessionId": { + "type": "string", + "description": "A globally unique identifier for the session as defined by the provider" + } + }, + "required": [ + "accounts", + "genesisHash", + "genesisId", + "providerId" + ] +} +``` +where: +* `accounts`: + - **MAY** be empty +* `accounts.address`: + - **MUST** be a base32 encoded public key with a 4 byte checksum appended as defined in keys and addresses +* `genesisHash`: + - **MUST** be a base64 encoded hash of the genesis block of the network +* `providerId`: + - **MUST** be a UUIDv4 compliant string + - **MUST** uniquely identify the provider +* `sessionId`: + - **RECOMMENDED** to be a UUIDv4 compliant string + +[Back to top ^][top] + +##### Post Transactions Result + +```json +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "/schemas/post-transactions-result", + "title": "Post Transactions Result", + "description": "The response from a post transactions request", + "type": "object", + "properties": { + "providerId": { + "type": "string", + "description": "A unique identifier for the provider", + "format": "uuid" + }, + "txnIDs": { + "type": "array", + "description": "A list of IDs for all of the transactions posted to the network", + "items": { + "type": "string" + } + } + }, + "required": [ + "providerId", + "txnIDs" + ] +} +``` +where: +* `providerId`: + - **MUST** be a UUIDv4 compliant string + - **MUST** uniquely identify the provider +* `txnIDs`: + - **MUST** contain items that are a 52-character base32 string (without padding) corresponding to a 32-byte string transaction ID + - **MAY** be empty + +[Back to top ^][top] + +##### Sign And Post Transactions Result + +```json +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "/schemas/sign-and-post-transactions-result", + "title": "Sign And Post Transactions Result", + "description": "The response from a sign and post transactions request", + "type": "object", + "properties": { + "providerId": { + "type": "string", + "description": "A unique identifier for the provider", + "format": "uuid" + }, + "txnIDs": { + "type": "array", + "description": "A list of IDs for all of the transactions posted to the network", + "items": { + "type": "string" + } + } + }, + "required": [ + "providerId", + "txnIDs" + ] +} +``` +where: +* `providerId`: + - **MUST** be a UUIDv4 compliant string + - **MUST** uniquely identify the provider +* `txnIDs`: + - **MUST** contain items that are a 52-character base32 string (without padding) corresponding to a 32-byte string transaction ID + - **MAY** be empty + +[Back to top ^][top] + +##### Sign Message Result + +```json +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "/schemas/sign-message-result", + "title": "Sign Message Result", + "description": "The response from a sign message request", + "type": "object", + "properties": { + "providerId": { + "type": "string", + "description": "A unique identifier for the provider", + "format": "uuid" + }, + "signature": { + "type": "string", + "description": "The signature of the signed message signed by the private key of the intended signer" + }, + "signer": { + "type": "string", + "description": "The address of the signer used to sign the message" + } + }, + "required": ["providerId", "signature", "signer"] +} +``` +where: +* `providerId`: + - **MUST** be a UUIDv4 compliant string + - **MUST** uniquely identify the provider +* `signature`: + - **MUST** be a base64 encoded string +* `signer`: + - **MUST** be a base32 encoded public key with a 4 byte checksum appended as defined in keys and addresses + +[Back to top ^][top] + +##### Sign Transactions Result + +```json +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "/schemas/sign-transactions-result", + "title": "Sign Transactions Result", + "description": "The response from a sign transactions request", + "type": "object", + "properties": { + "providerId": { + "type": "string", + "description": "A unique identifier for the provider", + "format": "uuid" + }, + "stxns": { + "type": "array", + "description": "A list of signed transactions that is ready to be posted to the network", + "items": { + "type": "string" + } + } + }, + "required": ["providerId", "stxns"] +} +``` +where: +* `providerId`: + - **MUST** be a UUIDv4 compliant string + - **MUST** uniquely identify the provider +* `stxns`: + - **MUST** be the base64 encoding of the canonical msgpack encoding of a signed transaction as defined in [ARC-1](./arc-0001.md#interface-signedtxnstr) + - **MAY** be empty + +[Back to top ^][top] + +#### Error Definition + +```json +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "/schemas/error", + "title": "Error", + "description": "Details the type of error and a human-readable message that can be displayed to the user", + "type": "object", + "properties": { + "code": { + "description": "An integer that defines the type of error", + "enum": [ + 4000, + 4001, + 4002, + 4003, + 4004, + 4100, + 4200, + 4201, + 4300 + ] + }, + "data": { + "type": "object", + "description": "Additional information about the error" + }, + "message": { + "type": "string", + "description": "A human-readable message about the error" + }, + "providerId": { + "type": "number", + "description": "A unique identifier for the provider", + "format": "uuid" + } + }, + "required": [ + "code", + "message" + ] +} +``` +where: +* `code`: + - **MUST** be a code of one of the [errors](#errors) +* `message`: + - **SHOULD** be human-readable to allow for display to a user +* `providerId`: + - **MUST** be a UUIDv4 compliant string + - **MUST** be present if the error originates from the provider + +[Back to top ^][top] + +### Errors + +#### Summary + +| Code | Name | Summary | +|------|--------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------| +| 4000 | [`UnknownError`](#4000-unknownerror) | The default error response, usually indicates something is not quite right. | +| 4001 | [`MethodCanceledError`](#4001-methodcancelederror) | When a user has rejected the method. | +| 4002 | [`MethodTimedOutError`](#4002-methodtimedouterror) | The requested method has timed out. | +| 4003 | [`MethodNotSupportedError`](#4003-methodnotsupportederror) | The provider does not support this method. | +| 4004 | [`NetworkNotSupportedError`](#4004-networknotsupportederror) | Network is not supported. | +| 4100 | [`UnauthorizedSignerError`](#4100-unauthorizedsignererror) | The provider has not given permission to use a specified signer. | +| 4200 | [`InvalidInputError`](#4200-invalidinputerror) | The input for signing transactions is malformed. | +| 4201 | [`InvalidGroupIdError`](#4201-invalidgroupiderror) | The computed group ID of the atomic transactions is different from the assigned group ID. | +| 4300 | [`FailedToPostSomeTransactionsError`](#4300-failedtopostsometransactionserror) | When some transactions were not sent properly. | + +[Back to top ^][top] + +#### 4000 `UnknownError` + +This error is the default error and serves as the "catch all" error. This usually occurs when something has happened that is outside the bounds of graceful handling. You can check the `UnknownError.message` string for more information. + +The code **MUST** be 4000. + +[Back to top ^][top] + +#### 4001 `MethodCanceledError` + +This error is thrown when a user has rejected or canceled the requested method on the provider. For example, the user decides to cancel the signing of a transaction. + +**Additional Data** + +| Name | Type | Value | Description | +|------------|----------|-------|-------------------------------------------| +| method | `string` | - | The name of the method that was canceled. | + +The code **MUST** be 4001. + +[Back to top ^][top] + +#### 4002 `MethodTimedOutError` + +This can be thrown by most methods and indicates that the method has timed out. + +**Additional Data** + +| Name | Type | Value | Description | +|------------|----------|-------|----------------------------------------| +| method | `string` | - | The name of the method that timed out. | + +The code **MUST** be 4002. + +[Back to top ^][top] + +#### 4003 `MethodNotSupportedError` + +This can be thrown by most methods and indicates that the provider does not support the method you are trying to perform. + +The code **MUST** be 4003. + +**Additional Data** + +| Name | Type | Value | Description | +|------------|----------|-------|-----------------------------------------------| +| method | `string` | - | The name of the method that is not supported. | + +[Back to top ^][top] + +#### 4004 `NetworkNotSupportedError` + +This error is thrown when the requested genesis hash is not supported by the provider. + +The code **MUST** be 4004. + +**Additional Data** + +| Name | Type | Value | Description | +|-------------|----------|-------|--------------------------------------------------------| +| genesisHash | `string` | - | The genesis hash of the network that is not supported. | + +[Back to top ^][top] + +#### 4100 `UnauthorizedSignerError` + +This error is thrown when a provided account has been specified, but the provider has not given permission to use that account as a signer. + +The code **MUST** be 4100. + +**Additional Data** + +| Name | Type | Value | Description | +|---------|----------|-------|---------------------------------------------------------------| +| signer | `string` | - | The address of the signer that is not authorized. | + +[Back to top ^][top] + +#### 4200 `InvalidInputError` + +This error is thrown when the provider attempts to sign transaction(s), but the input is malformed. + +The code **MUST** be 4200. + +[Back to top ^][top] + +#### 4201 `InvalidGroupIdError` + +This error is thrown when the provider attempts to sign atomic transactions in which the computed group ID is different from the assigned group ID. + +The code **MUST** be 4301. + +**Additional Data** + +| Name | Type | Value | Description | +|-----------------|----------|-------|------------------------------------------------------| +| computedGroupId | `string` | - | The computed ID of the supplied atomic transactions. | + +[Back to top ^][top] + +#### 4300 `FailedToPostSomeTransactionsError` + +This error is thrown when some transactions failed to be posted to the network. + +The code **MUST** be 4300. + +**Additional Data** + +| Name | Type | Value | Description | +|---------------|--------------------------------------|-------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| successTxnIDs | (string | null)[] | - | This will correspond to the `stxns` list sent in `post_transactions` & `sign_and_post_transactions` and will contain the ID of those transactions that were successfully committed to the blockchain, or null if they failed. | + +[Back to top ^][top] + +## Rationale + +An original vision for Algorand was that multiple AVM chains could co-exist. Extending the base of each message schema with a targeted network (referenced by its genesis hash) ensures the schema can remain AVM chain-agnostic and adapted to work with any AVM-compatible chain. + +The schema adds a few more methods that are not mentioned in previous ARCs and the inception of these methods are born out of the need that has been seen by providers, and clients alike. + +The latest JSON schema (as of writing is the 2020-12 draft) was chosen as the format due to the widely supported use across multiple platforms & languages, and due to its popularity. + +[Back to top ^][top] + +## Reference Implementation + +### Disable Example + +**Request** + +```json +{ + "id": "e44f5bde-37f4-44b0-94d5-1daff41bc984d", + "params": { + "genesisHash": "SGO1GKSzyE7IEPItTxCByw9x8FmnrCDexi9/cOUJOiI=", + "providerId": "85533948-4d0b-4727-904e-dd35305d49aa", + "sessionIds": ["ab476381-c1f4-4665-b89c-9f386fb6f15d", "7b02d412-6a27-4d97-b091-d5c26387e644"] + }, + "reference": "arc0027:disable:request" +} +``` + +**Response** + +```json +{ + "id": "e6696507-6a6c-4df8-98c4-356d5351207c", + "reference": "arc0027:disable:response", + "requestId": "e44f5bde-37f4-44b0-94d5-1daff41bc984d", + "result": { + "genesisHash": "SGO1GKSzyE7IEPItTxCByw9x8FmnrCDexi9/cOUJOiI=", + "genesisId": "testnet-v1.0", + "providerId": "85533948-4d0b-4727-904e-dd35305d49aa", + "sessionIds": ["ab476381-c1f4-4665-b89c-9f386fb6f15d", "7b02d412-6a27-4d97-b091-d5c26387e644"] + } +} +``` + +[Back to top ^][top] + +### Discover Example + +**Request** + +```json +{ + "id": "5d5186fc-2091-4e88-8ef9-05a5d4da24ed", + "params": { + "providerId": "85533948-4d0b-4727-904e-dd35305d49aa" + }, + "reference": "arc0027:discover:request" +} +``` + +**Response** + +```json +{ + "id": "6695f990-e3d7-41c4-bb26-64ab8da0653b", + "reference": "arc0027:discover:response", + "requestId": "5d5186fc-2091-4e88-8ef9-05a5d4da24ed", + "result": { + "host": "https://awesome-wallet.com", + "icon": "data:image/png;base64,iVBORw0KGgoAAAANSUh...", + "name": "Awesome Wallet", + "networks": [ + { + "genesisHash": "wGHE2Pwdvd7S12BL5FaOP20EGYesN73ktiC1qzkkit8=", + "genesisId": "mainnet-v1.0", + "methods": [ + "disable", + "enable", + "post_transactions", + "sign_and_post_transactions", + "sign_message", + "sign_transactions" + ] + }, + { + "genesisHash": "SGO1GKSzyE7IEPItTxCByw9x8FmnrCDexi9/cOUJOiI=", + "genesisId": "testnet-v1.0", + "methods": [ + "disable", + "enable", + "post_transactions", + "sign_message", + "sign_transactions" + ] + } + ], + "providerId": "85533948-4d0b-4727-904e-dd35305d49aa" + } +} +``` + +[Back to top ^][top] + +### Enable Example + +**Request** + +```json +{ + "id": "4dd4ccdf-a918-4e33-a675-073330db4c99", + "params": { + "genesisHash": "SGO1GKSzyE7IEPItTxCByw9x8FmnrCDexi9/cOUJOiI=", + "providerId": "85533948-4d0b-4727-904e-dd35305d49aa" + }, + "reference": "arc0027:enable:request" +} +``` + +**Response** + +```json +{ + "id": "cdf43d9e-1158-400b-b2fb-ba45e39548ff", + "reference": "arc0027:enable:response", + "requestId": "4dd4ccdf-a918-4e33-a675-073330db4c99", + "result": { + "accounts": [{ + "address": "ARC27GVTJO27GGSWHZR2S3E7UY46KXFLBC6CLEMF7GY3UYF7YWGWC6NPTA", + "name": "Main Account" + }], + "genesisHash": "SGO1GKSzyE7IEPItTxCByw9x8FmnrCDexi9/cOUJOiI=", + "genesisId": "testnet-v1.0", + "providerId": "85533948-4d0b-4727-904e-dd35305d49aa", + "sessionId": "6eb74cf1-93e8-400c-94b5-4928807a3ab1" + } +} +``` + +[Back to top ^][top] + +### Post Transactions Example + +**Request** + +```json +{ + "id": "e555ccb3-4730-474c-92e3-1e42868e0c0d", + "params": { + "providerId": "85533948-4d0b-4727-904e-dd35305d49aa", + "stxns": [ + "iaNhbXT..." + ] + }, + "reference": "arc0027:post_transactions:request" +} +``` + +**Response** + +```json +{ + "id": "13b115fb-2966-4a21-b6f7-8aca118ac008", + "reference": "arc0027:post_transactions:response", + "requestId": "e555ccb3-4730-474c-92e3-1e42868e0c0d", + "result": { + "providerId": "85533948-4d0b-4727-904e-dd35305d49aa", + "txnIDs": [ + "H2KKVI..." + ] + } +} +``` + +[Back to top ^][top] + +### Sign And Post Transactions Example + +**Request** + +```json +{ + "id": "43adafeb-d455-4264-a1c0-d86d9e1d75d9", + "params": { + "providerId": "85533948-4d0b-4727-904e-dd35305d49aa", + "txns": [ + { + "txn": "iaNhbXT..." + }, + { + "txn": "iaNhbXT...", + "signers": [] + } + ] + }, + "reference": "arc0027:sign_and_post_transactions:request" +} +``` + +**Response** + +```json +{ + "id": "973df300-f149-4004-9718-b04b5f3991bd", + "reference": "arc0027:sign_and_post_transactions:response", + "requestId": "43adafeb-d455-4264-a1c0-d86d9e1d75d9", + "result": { + "providerId": "85533948-4d0b-4727-904e-dd35305d49aa", + "stxns": [ + "iaNhbXT...", + null + ] + } +} +``` + +[Back to top ^][top] + +### Sign Message Example + +**Request** + +```json +{ + "id": "8f4aa9e5-d039-4272-95ac-6e972967e0cb", + "params": { + "message": "Hello humie!", + "providerId": "85533948-4d0b-4727-904e-dd35305d49aa", + "signer": "ARC27GVTJO27GGSWHZR2S3E7UY46KXFLBC6CLEMF7GY3UYF7YWGWC6NPTA" + }, + "reference": "arc0027:sign_message:request" +} +``` + +**Response** + +```json +{ + "id": "9bdf72bf-218e-462a-8f64-3a40ef4a4963", + "reference": "arc0027:sign_message:response", + "requestId": "8f4aa9e5-d039-4272-95ac-6e972967e0cb", + "result": { + "providerId": "85533948-4d0b-4727-904e-dd35305d49aa", + "signature": "iaNhbXT...", + "signer": "ARC27GVTJO27GGSWHZR2S3E7UY46KXFLBC6CLEMF7GY3UYF7YWGWC6NPTA" + } +} +``` + +[Back to top ^][top] + +### Sign Transactions Example + +**Request** + +```json +{ + "id": "464e6b88-8860-403c-891d-7de6d0425686", + "params": { + "providerId": "85533948-4d0b-4727-904e-dd35305d49aa", + "txns": [ + { + "txn": "iaNhbXT..." + }, + { + "txn": "iaNhbXT...", + "signers": [] + } + ] + }, + "reference": "arc0027:sign_transactions:request" +} +``` + +**Response** + +```json +{ + "id": "f5a56135-5cd2-4f3f-8757-7b89d32d67e0", + "reference": "arc0027:sign_transactions:response", + "requestId": "464e6b88-8860-403c-891d-7de6d0425686", + "result": { + "providerId": "85533948-4d0b-4727-904e-dd35305d49aa", + "stxns": [ + "iaNhbXT...", + null + ] + } +} +``` + +[Back to top ^][top] + +## Security Considerations + +As this ARC only serves as the formalization of the message schema, the end-to-end security of the actual messages is beyond the scope of this ARC. It is **RECOMMENDED** that another ARC be proposed to advise in this topic, with reference to this ARC. + +[Back to top ^][top] + +## Copyright +Copyright and related rights waived via CCO. + +[Back to top ^][top] + + +[arc-0005]: ./arc-0005.md#specification +[arc-0006]: ./arc-0006.md#specification +[arc-0007]: ./arc-0007.md#specification +[arc-0008]: ./arc-0008.md#specification +[top]: #provider-message-schema