Provider Message Schema | Algorand Developer Portal
Provider Message Schema
Abstract
Building off of the work of the previous ARCs relating to; provider transaction signing ( ARC-0005), provider address discovery ( ARC-0006), provider transaction network posting ( ARC-0007) and provider transaction signing & posting ( 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.
Motivation
The previous ARCs relating to client/provider communication ( ARC-0005, ARC-0006, ARC-0007 and ARC-0008 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.
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.
Definitions
- 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.
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
- MUST be
method:- MUST be in snake case
- MUST be one of
disable,discover,enable,post_transactions,sign_and_post_transactions,sign_messageorsign_transactions
type:- MUST be one of
requestorresponse
- MUST be one of
This convention ensures that each message can be identified and handled.
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 |
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 |
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 |
post_transactions |
Sends a list of signed transactions to be posted to the network by the provider. | here |
sign_and_post_transactions |
Sends a list of signed transactions to be posted to the network by the provider. | here |
sign_message |
Sends a UTF-8 encoded message to be signed by the provider. | here |
sign_transactions |
Sends a list of transactions to be signed by the provider. | here |
Request Message Schema
{
"$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"
}
}
}
}
]
}
``
### Param Definitions
##### Disable Params
{
"$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"]
}
##### Discover Params
{
"$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"
}
}
}
##### Enable Params
{
"$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"]
}
##### Post Transactions Params
{
"$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"]
}
##### Sign And Post Transactions Params
{
"$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"]
}
##### Sign Message Params
{
"$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"]
}
##### Sign Transactions Params
{
"$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"]
}
### Response Message Schema
{
"$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"
}
}
}
]
}
}
]
} ``
Licensing
Copyright and related rights waived via CCO.