Algorand Wallet Reach Minimum Requirements

Abstract

An amalgamation of APIs which comprise the minimum requirements for Reach to be able to function correctly with a given wallet.

Specification

A group of related functions:

enable (REQUIRED)
enableNetwork (OPTIONAL)
enableAccounts (OPTIONAL)
signAndPostTxns (REQUIRED)
getAlgodv2Client (REQUIRED)
getIndexerClient (REQUIRED)
signTxns (OPTIONAL)
postTxns (OPTIONAL)
enable: as specified in ARC-0006.
signAndPostTxns: as specified in ARC-0008.
getAlgodv2Client and getIndexerClient: as specified in ARC-0009.
signTxns: as specified in ARC-0005 / ARC-0001.
postTxns: as specified in ARC-0007.

There are additional semantics for using these functions together.

Semantic Requirements

enable SHOULD be called before calling the other functions and upon refresh of the dApp.
Calling enableNetwork and then enableAccounts MUST be equivalent to calling enable.
If used instead of enable: enableNetwork SHOULD be called before enableAccounts and getIndexerClient. Both enableNetwork and enableAccounts SHOULD be called before the other functions.
If signAndPostTxns, getAlgodv2Client, getIndexerClient, signTxns, or postTxns are called before enable (or enableAccounts), they SHOULD throw an error object with property code=4202. (See Error Standards in ARC-0001).
getAlgodv2Client and getIndexerClient MUST return connections to the network indicated by the network result of enable.
signAndPostTxns MUST post transactions to the network indicated by the network result of enable
The result of getAlgodv2Client SHOULD only be used to query the network. postTxns (if available) and signAndPostTxns SHOULD be used to send transactions to the network. The Algodv2Client object MAY be modified to throw exceptions if the caller tries to use it to post transactions.
signTxns and postTxns MAY or MAY NOT be provided. When one is provided, they both MUST be provided. In addition, signTxns MAY display a warning that the transactions are returned to the dApp rather than posted directly to the blockchain.

Additional requirements regarding LogicSigs

signAndPostTxns must also be able to handle logic sigs, and more generally transactions signed by the DApp itself. In case of logic sigs, callers are expected to sign the logic sig by themselves, rather than expecting the wallet to do so on their behalf. To handle these cases, we adopt and extend the ARC-0001 format for WalletTransactions that do not need to be signed:

1
{
2
  "txn": "...",
3
  "signers": [],
4
  "stxn": "..."
5
}

stxn is a SignedTxnStr, as specified in ARC-0007.
For production wallets, stxn MUST be checked to match txn, as specified in ARC-0001.

signAndPostTxns MAY reject when none of the transactions need to be signed by the user.

Rationale

In order for a wallet to be useable by a DApp, it must support features for account discovery, signing and posting transactions, and querying the network.

To whatever extent possible, the end users of a DApp should be empowered to select their own wallet, accounts, and network to be used with the DApp. Furthermore, said users should be able to use their preferred network node connection, without exposing their connection details and secrets (such as endpoint URLs and API tokens) to the DApp.

The APIs presented in this document and related documents are sufficient to cover the needed functionality, while protecting user choice and remaining compatible with best security practices. Most DApps indeed always need to post transactions immediately after signing. signAndPostTxns allows this goal without revealing the signed transactions to the DApp, which prevents surprises to the user: there is no risk the DApp keeps in memory the transactions and post it later without the user knowing it (either to achieve a malicious goal such as forcing double spending, or just because the DApp has a bug). However, there are cases where signTxns and postTxns need to be used: for example when multiple users need to coordinate to sign an atomic transfer.

Reference Implementation

1
async function main(wallet) {
2

3
  // Account discovery
4
  const enabled = await wallet.enable({genesisID: 'testnet-v1.0'});
5
  const from = enabled.accounts[0];
6

7
  // Querying
8
  const algodv2 = new algosdk.Algodv2(await wallet.getAlgodv2Client());
9
  const suggestedParams = await algodv2.getTransactionParams().do();
10
  const txns = makeTxns(from, suggestedParams);
11

12
  // Sign and post
13
  const res = await wallet.signAndPost(txns);
14
  console.log(res);
15

16
};

Where makeTxns is comparable to what is seen in ARC-0001’s sample code.

Security Considerations

None.