ARC-7: Algorand Wallet Post Transactions API

API function to Post Signed Transactions to the network.

Algorand Wallet Post Transactions API

Abstract

A function, postTxns, which accepts an array of SignedTransactions, and posts them to the network.

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.

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

Interface PostTxnsFunction

export type TxnID = string;
export type SignedTxnStr = string;

export type PostTxnsFunction = (
  stxns: SignedTxnStr[],
) => Promise<PostTxnsResult>;

export interface PostTxnsResult {
  txnIDs: TxnID[];
}

export interface PostTxnsError extends Error {
  code: number;
  data?: any;
  successTxnIDs: (TxnID | null)[];
}

A PostTxnsFunction with input argument stxns:string[] and promised return value ret:PostTxnsResult:

• expects stxns to be in the correct string format as specified by SignedTxnStr (defined below).
• MUST, if successful, return an object ret such that ret.txID is in the correct string format as specified by TxID.

The use of txID instead of txnID is to follow the standard name for the transaction ID.

String specification: SignedTxnStr

Defined as in ARC-0001:

[SignedTxnStr is] the base64 encoding of the canonical msgpack encoding of the SignedTxn corresponding object, as defined in the Algorand specs.

String specification: TxnID

A TxnID is a 52-character base32 string (without padding) corresponding to a 32-byte string. For example: H2KKVITXKWL2VBZBWNHSYNU3DBLYBXQAVPFPXBCJ6ZZDVXQPSRTQ.

Error standard

PostTxnsError follows the same rules as SignTxnsError from ARC-0001 and uses the same status codes as well as the following status codes:

Semantic requirements

Regarding a call to postTxns(stxns) with promised return value ret:

• postTxns MAY assume that stxns is an array of valid SignedTxnStr strings that represent correctly signed transactions such that:
  • Either all transaction belong to the same group of transactions and are in the correct order. In other words, either stxns is an array of a single transaction with a zero group ID (txn.Group), or stxns is an array of one or more transactions with the same non-zero group ID. The function MUST reject if the transactions do not match their group ID. (The caller must provide the transactions in the order defined by the group ID.)

    An early draft of this ARC required that the size of a group of transactions must be greater than 1 but, since the Algorand protocol supports groups of size 1, this requirement had been changed so dApps don’t have to have special cases for single transactions and can always send a group to the wallet.

  • Or stxns is a concatenation of arrays satisfying the above.
• postTxns MUST attempt to post all transactions together. With the algod v2 API, this implies splitting the transactions into groups and making an API call per transaction group. postTxns SHOULD NOT wait after each transaction group but post all of them without pause in-between.
• postTxns MAY ask the user whether they approve posting those transactions.

  A dApp can always post transactions itself without the help of postTxns when a public network is used. However, when a private network is used, a dApp may need postTxns, and in this case, asking the user’s approval can make sense. Another such use case is when the user uses a specific trusted node that has some legal restrictions.

• postTxns MUST wait for confirmation that the transactions are finalized.

  TODO: Decide whether to add an optional flag to not wait for that.

• If successful, postTxns MUST resolve the returned promise with the list of transaction IDs txnIDs of the posted transactions stxn.
• If unsuccessful, postTxns MUST reject the promise with an error err of type PostTxnsError such that:
  • err.code=4400 if there was a failure sending the transactions or a code as specified in ARC-0001 if the user or function disallowed posting the transactions.
  • err.message SHOULD describe what went wrong in as much detail as possible.
  • err.successTxnIDs MUST be an array such that err.successTxnID[i] is the transaction ID of stxns[i] if stxns[i] was successfully committed to the blockchain, and null otherwise.

Security considerations

In case the wallet uses an API service that is secret or provided by the user, the wallet MUST ensure that the URL of the service and the potential tokens/headers are not leaked to the dApp.

Leakage may happen by accidentally including too much information in responses or errors returned by the various methods. For example, if the Node.JS superagent library is used without filtering errors and responses, errors and responses may include the request object, which includes the potentially secret API service URL / secret token headers.

Rationale

This API allows DApps to use a user’s preferred connection in order to submit transactions to the network.

The user may wish to use a specific trusted node, or a particular paid service with their own secret token. This API protects the user’s secrets by not exposing connection details to the DApp.

Security Considerations

None.

Copyright

Copyright and related rights waived via CCO.

Citation

Please cite this document as:

DanBurton, "ARC-7: Algorand Wallet Post Transactions API," Algorand Requests for Comments, no. 7, August 2021. [Online serial]. Available: https://github.com/algorandfoundation/ARCs/blob/main/ARCs/arc-0007.md.