Algorand WalletConnect v1 API | Algorand Developer Portal

Algorand WalletConnect v1 API

This document specifies a standard API for communication between Algorand decentralized applications and wallets using the WalletConnect v1 protocol.

Abstract

WalletConnect is an open protocol to communicate securely between mobile wallets and decentralized applications (dApps) using QR code scanning (desktop) or deep linking (mobile). Its main use case allows users to sign transactions on web apps using a mobile wallet.

This document aims to establish a standard API for using the WalletConnect v1 protocol on Algorand, leveraging the existing transaction signing APIs defined in ARC-1.

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.

It is strongly recommended to read and understand the entirety of ARC-1 before reading this ARC.

Overview

This overview section is non-normative. It offers a brief overview of the WalletConnect v1 lifecycle. A more in-depth description can be found in the WalletConnect v1 documentation here.

In order for a dApp and wallet to communicate using WalletConnect, a WalletConnect session must be established between them. The dApp is responsible for initiating this session and producing a session URI, which it will communicate to the wallet, typically in the form of a QR code or a deep link. This process is described in the Session Creation section.

Once a session is established between a dApp and a wallet, the dApp is able to send requests to the wallet. The wallet is responsible for listening for requests, performing the appropriate actions to fulfill requests, and sending responses back to the dApp with the results of requests. This process is described in the Message Schema section.

Session Creation

The dApp is responsible for initializing a WalletConnect session and producing a WalletConnect URI that communicates the necessary session information to the wallet. This process is described in the WalletConnect documentation here, with one addition. In order for wallets to easily recognize an Algorand WalletConnect session, dApps SHOULD add an additional URI query parameter to the WalletConnect URI named algorand with a value of true.

It is RECOMMENDED that dApps include this query parameter, but it is not REQUIRED. Wallets MAY reject sessions if the session URI does not contain this query parameter.

Chain IDs

WalletConnect v1 sessions are associated with a numeric chain ID. The document defines the following chain IDs for the Algorand ecosystem:

MainNet (genesis hash wGHE2Pwdvd7S12BL5FaOP20EGYesN73ktiC1qzkkit8=): 416001
TestNet (genesis hash SGO1GKSzyE7IEPItTxCByw9x8FmnrCDexi9/cOUJOiI=): 416002
BetaNet (genesis hash mFgazF+2uRS1tMiL9dsj01hJGySEmPN28B/TjjvpVW0=): 416003

At the time of writing, these chain IDs do not conflict with any known chain that also uses WalletConnect. In the unfortunate event that this were to happen, the algorand query parameter discussed above would be used to differentiate Algorand chains from others.

Message Schema

The WalletConnect message schema is a set of JSON-RPC 2.0 requests and responses. Decentralized applications will send requests to the wallets and will receive responses as JSON-RPC messages. All requests MUST adhere to the following structure:

interface JsonRpcRequest {
  id: number;
  jsonrpc: "2.0";
  method: string;
  params: any[];
}

The Algorand WalletConnect schema consists of a single RPC method, algo_signTxn, as described in the following section.

All responses, whether successful or unsuccessful, MUST adhere to the following structure:

interface JsonRpcResponse {
  id: number;
  jsonrpc: "2.0";
  result?: any;
  error?: JsonRpcError;
}

`algo_signTxn`

This request is used to ask a wallet to sign one or more transactions in one or more atomic groups.

Request

This request MUST adhere to the following structure:

interface AlgoSignTxnRequest {
  id: number;
  jsonrpc: "2.0";
  method: "algo_signTxn";
  params: SignTxnParams;
}

type SignTxnParams = [WalletTransaction[], SignTxnOpts?];

Response

To respond to a request, the wallet MUST send back the following response object:

interface AlgoSignTxnResponse {
  id: number;
  jsonrpc: "2.0";
  result?: Array<SignedTxnStr | null>;
  error?: JsonRpcError;
}

Rationale

Security Considerations

None.