ARC-5: Wallet Transaction Signing API (Functional)

An API for a function used to sign a list of transactions.

Algorand Wallet Transaction Signing API (Functionality Only)

This ARC is intended to be completely compatible with ARC-1.

Abstract

ARC-1 defines a standard for signing transactions with security in mind. This proposal is a strict subset of ARC-1 that outlines only the minimum functionality required in order to be useable.

Wallets that conform to ARC-1 already conform to this API.

Wallets conforming to ARC-5 but not ARC-1 MUST only be used for testing purposes and MUST NOT used on MainNet. This is because this ARC-5 does not provide the same security guarantees as ARC-1 to protect properly wallet users.

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.

Interface SignTxnsFunction

Signatures are requested by calling a function signTxns(txns) on a list txns of transactions. The dApp may also provide an optional parameter opts.

A wallet transaction signing function signTxns is defined by the following interface:

export type SignTxnsFunction = (
   txns: WalletTransaction[],
   opts?: SignTxnsOpts,
)
   => Promise<(SignedTxnStr | null)[]>;

• SignTxnsOpts is as specified by ARC-1.
• SignedTxnStr is as specified by ARC-1.

A SignTxnsFunction:

• expects txns to be in the correct format as specified by WalletTransaction.

Interface WalletTransaction

export interface WalletTransaction {
   /**
    * Base64 encoding of the canonical msgpack encoding of a Transaction.
    */
   txn: string;
}

Semantic requirements

• The call signTxns(txns, opts) MUST either throw an error or return an array ret of the same length as the txns array.
• Each element of ret MUST be a valid SignedTxnStr with the underlying transaction exactly matching txns[i].txn.

This ARC uses interchangeably the terms “throw an error” and “reject a promise with an error”.

signTxns SHOULD follow the error standard specified in ARC-0001.

UI requirements

Wallets satisfying this ARC but not ARC-0001 MUST clearly display a warning to the user that they MUST not be used with real funds on MainNet.

Rationale

This simplified version of ARC-0001 exists for two main reasons:

1. To outline the minimum amount of functionality needed in order to be useful.
2. To serve as a stepping stone towards full ARC-0001 compatibility.

While this ARC MUST not be used by users with real funds on MainNet for security reasons, this simplified API sets a lower bar and acts as a signpost for which wallets can even be used at all.

Security Considerations

None.

Copyright

Copyright and related rights waived via CCO.

Citation

Please cite this document as:

DanBurton, "ARC-5: Wallet Transaction Signing API (Functional)," Algorand Requests for Comments, no. 5, August 2021. [Online serial]. Available: https://github.com/algorandfoundation/ARCs/blob/main/ARCs/arc-0005.md.