📢 This ARC is in the last call for review stage. The authors wish to finalize the ARC and appreciate feedback.

ARC-27: Provider Message Schema Source

A comprehensive message schema for communication between clients and providers.

AuthorKieran O'Neill
StatusLast Call
Last Call Deadline2025-02-15
TypeStandards Track
CategoryInterface
Created2023-12-24

Table of Contents

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.

Back to top ^

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.

Back to 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 ^

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 ^

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

Back to top ^

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"
          }
        }
      }
    }
  ]
}

where:

Back to top ^

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"]
}

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 ^

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"
    }
  }
}

where:

  • providerId:
    • OPTIONAL if omitted, all providers MAY respond
    • MUST be a UUIDv4 compliant string

Back to top ^

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"]
}

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 ^

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"
  ]
}

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
    • MAY be empty

Back to top ^

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"
  ]
}

where:

  • providerId:
    • MUST be a UUIDv4 compliant string
  • txns:
    • MUST have each item conform to the semantic of a transaction in ARC-1
    • MAY be empty

Back to top ^

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"
  ]
}

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 ^

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"
  ]
}

where:

  • providerId:
    • MUST be a UUIDv4 compliant string
  • txns:
    • MUST have each item conform to the semantic of a transaction in ARC-1
    • MAY be empty

Back to top ^

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"
              }
            }
          }
        ]
      }
    }
  ]
}
  • id:
    • MUST be a UUIDv4 compliant string
  • reference:
  • requestId:
    • MUST be the ID of the origin request message

Back to top ^

Result Definitions

Disable Result 
{
  "$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 ^

Discover Result 
{
  "$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 ^

Enable Result 
{
  "$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 ^

Post Transactions Result 
{
  "$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 ^

Sign And Post Transactions Result 
{
  "$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 ^

Sign Message Result 
{
  "$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 ^

Sign Transactions Result 
{
  "$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
    • MAY be empty

Back to top ^

Error Definition 

{
  "$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
  • 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 ^

Errors

Summary

Code Name Summary
4000 UnknownError The default error response, usually indicates something is not quite right.
4001 MethodCanceledError When a user has rejected the method.
4002 MethodTimedOutError The requested method has timed out.
4003 MethodNotSupportedError The provider does not support this method.
4004 NetworkNotSupportedError Network is not supported.
4100 UnauthorizedSignerError The provider has not given permission to use a specified signer.
4200 InvalidInputError The input for signing transactions is malformed.
4201 InvalidGroupIdError The computed group ID of the atomic transactions is different from the assigned group ID.
4300 FailedToPostSomeTransactionsError When some transactions were not sent properly.

Back to 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 ^

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 ^

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 ^

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 ^

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 ^

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 ^

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 ^

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 ^

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 ^

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 ^

Reference Implementation

Disable Example

Request

{
  "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

{
  "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 ^

Discover Example

Request

{
  "id": "5d5186fc-2091-4e88-8ef9-05a5d4da24ed",
  "params": {
    "providerId": "85533948-4d0b-4727-904e-dd35305d49aa"
  },
  "reference": "arc0027:discover:request"
}

Response

{
  "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 ^

Enable Example

Request

{
  "id": "4dd4ccdf-a918-4e33-a675-073330db4c99",
  "params": {
    "genesisHash": "SGO1GKSzyE7IEPItTxCByw9x8FmnrCDexi9/cOUJOiI=",
    "providerId": "85533948-4d0b-4727-904e-dd35305d49aa"
  },
  "reference": "arc0027:enable:request"
}

Response

{
  "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 ^

Post Transactions Example

Request

{
  "id": "e555ccb3-4730-474c-92e3-1e42868e0c0d",
  "params": {
    "providerId": "85533948-4d0b-4727-904e-dd35305d49aa",
    "stxns": [
      "iaNhbXT..."
    ]
  },
  "reference": "arc0027:post_transactions:request"
}

Response

{
  "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 ^

Sign And Post Transactions Example

Request

{
  "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

{
  "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 ^

Sign Message Example

Request

{
  "id": "8f4aa9e5-d039-4272-95ac-6e972967e0cb",
  "params": {
    "message": "Hello humie!",
    "providerId": "85533948-4d0b-4727-904e-dd35305d49aa",
    "signer": "ARC27GVTJO27GGSWHZR2S3E7UY46KXFLBC6CLEMF7GY3UYF7YWGWC6NPTA"
  },
  "reference": "arc0027:sign_message:request"
}

Response

{
  "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 ^

Sign Transactions Example

Request

{
  "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

{
  "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 ^

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 ^

Copyright and related rights waived via CCO.

Back to top ^

Citation

Please cite this document as:

Kieran O'Neill, "ARC-27: Provider Message Schema [DRAFT]," Algorand Requests for Comments, no. 27, December 2023. [Online serial]. Available: https://github.com/algorandfoundation/ARCs/blob/main/ARCs/arc-0027.md.