# 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](https://walletconnect.com/) 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](https://dev.algorand.co/arc-standards/arc-0001).

## 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](https://www.ietf.org/rfc/rfc2119.txt).

> Comments like this are non-normative.

It is strongly recommended to read and understand the entirety of [ARC-1](https://dev.algorand.co/arc-standards/arc-0001) 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](https://docs.walletconnect.com/tech-spec).

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](https://dev.algorand.co/arc-standards/arc-0025/#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](https://dev.algorand.co/arc-standards/arc-0025/#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](https://docs.walletconnect.com/tech-spec#requesting-connection), 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](https://www.jsonrpc.org/specification). 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.

## Copyright

Copyright and related rights waived via [CCO](https://creativecommons.org/publicdomain/zero/1.0/).