feat: rfc-1104 confirming transactions

src/RFC-1104_ConfirmingTx.md

@@ -0,0 +1,158 @@
+# RFC-1104/ConfirmingTx
+
+## Tari Universe: rules of confirming transactions
+
+![status: draft](theme/images/status-draft.svg)
+
+**Maintainer(s)**: [karczuRF](https://github.com/karczuRF)
+
+# Licence
+
+[ The 3-Clause BSD Licence](https://opensource.org/licenses/BSD-3-Clause).
+
+Copyright 2024 The Tari Development Community
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the
+following conditions are met:
+
+1. Redistributions of this document must retain the above copyright notice, this list of conditions and the following
+   disclaimer.
+2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following
+   disclaimer in the documentation and/or other materials provided with the distribution.
+3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products
+   derived from this software without specific prior written permission.
+
+THIS DOCUMENT IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS", AND ANY EXPRESS OR IMPLIED WARRANTIES,
+INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
+WHETHER IN CONTRACT, STRICT LIABILITY OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+## Language
+
+The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED",
+"NOT RECOMMENDED", "MAY" and "OPTIONAL" in this document are to be interpreted as described in
+[BCP 14](https://tools.ietf.org/html/bcp14) (covering RFC2119 and RFC8174) when, and only when, they appear in all capitals, as
+shown here.
+
+## Disclaimer
+
+This document and its content are intended for information purposes only and may be subject to change or update
+without notice.
+
+This document may include preliminary concepts that may or may not be in the process of being developed by the Tari
+community. The release of this document is intended solely for review and discussion by the community regarding the
+technological merits of the potential system outlined herein.
+
+## Goals
+
+The aim of this Request for Comment (RFC) is to describe the rules for confirming transactions by the user.
+
+## Related Requests for Comment
+
+- [RFC-1100: Tari Universe Overview](https://github.com/tari-project/rfcs/pull/134)
+- [RFC-1101: Tapplet](https://github.com/tari-project/rfcs/pull/137)
+- [RFC-0150: Base Layer Wallet Module](RFC-0150_Wallets.md)
+- [RFC-0153: Staged Wallet Security](RFC-0153_StagedWalletSecurity.md)
+
+## Description
+
+For the moment the vast majority of dapps uses external wallets, like MetaMask, to allow users to interact with the dapp, confirm and sign transactions. The flow roughly looks like this:
+
+- Init transaction with the data to be signed (e.g. by pressing a button)
+- Metamask sign-in request window appears
+- User press “sign” button to proceed a transaction
+- If a transaction is done (succeeded or failed) another notification appears to inform an user about the tx result.
+
+At Tari Universe simplicity and security should go hand in hand, so below a few concepts of confirming transactions are presented to find the best one.
+
+1. “Metamask-like” flow
+
+   It is just a copy-paste solution widely used in web3. Tari Univers needs something more user-friendly and integrated with the application.
+
+2. No modal window for signing transactions at all
+
+   This concept is rejected due to lack of security.
+
+3. “Mixed model”
+
+   This concept assumes that some tx can be done without explicit user confirmation. In this scenario _x_ (as USD value of transaction) should be defined:
+
+   - no-prompt if the tx value is less than _x_
+   - modal window if the tx value is greater than _x_
+
+   Rejected due to lack of clarity about what price level would be the limit and non-intuitiveness
+
+4. Build-in signing window which is part of Tari Univers/tapplet design
+
+   Transaction with presented data can be confirmed by clicking a button on a tapplet window, which appears or on top of a tapplet or is placed aside.
+
+5. Desirable from the point of view of readability and UX.
+
+   Simulate the transaction and summarize the difference of user holdings in case the transaction is executed. It can be done with transaction dry-run before submitting it to a validator node. For more details see [RFC-0350/TariVM](https://rfc.tari.com/RFC-0350_TariVM)
+
+#### Suggested solution
+
+As it was discussed, the security comes first, so definitely all transactions need to be confirmed before sending to the Tari Network. At the same time users shouldn’t be overwhelmed by the amount of information, especially not given just the “list of hashes” to sign, which are definitely not understandable for typical users. Therefore the idea is to show the transaction summary and quite a nice example of that is presented by [Radix Wallet](https://www.radixdlt.com/wallet).
+
+Transactions should be shown in a clear, simple and user-friendly way. They should give users complete visibility and control before signing, with a summary of a transaction and meaningful instructions of each step. It should be easy to see what inputs and outputs are, what’s the transaction cost and so on.
+
+Confirming transaction steps should be an inseparable part of the transaction flow, thus its summary should be presented not as a modal window (like MetaMask), but rather within the Tari Universe (on top of a tapplet or to a side of it) - designs need to be discussed and created accordingly.
+
+### Sample transaction in Tari Network
+
+Tari Network [accounts transfer](https://github.com/tari-project/tari-dan/blob/86dd4f910e040cb98b118abaf66a5719b59c987f/applications/tari_dan_wallet_web_ui/src/api/hooks/useAccounts.tsx#L89) is the simplest transaction that can be used to analyze and extract transaction data. This is needed to know what data is available and should be shown to the user when interacting with the tapplet.
+At the time of writing this RFC, a transfer transaction has the following parameters:
+
+```
+export interface ConfidentialTransferRequest {
+  account: ComponentAddressOrName;
+  amount: Amount;
+  input_selection: ConfidentialTransferInputSelection;
+  resource_address: ResourceAddress;
+  destination_public_key: string;
+  max_fee: Amount;
+  output_to_revealed: boolean;
+  proof_from_badge_resource: string;
+  dry_run: boolean;
+}
+```
+
+And transaction response.
+
+```
+export interface ConfidentialTransferResponse {
+  transaction_id: string;
+  fee: Amount;
+  result: {
+      transaction_hash: Uint8Array;
+      events: Array<Event>;
+      logs: Array<LogEntry>;
+      execution_results: Array<InstructionResult>;
+      result: TransactionResult;
+      fee_receipt: FeeReceipt;
+  }
+}
+```
+
+The last parameter from the `ConfidentialTransferRequest` - `dry_run` - is used for gas calculation and at the same time is crucial for transaction simulation. Therefore it can be used to show transaction result before confirming it. From this the key values can be extracted and shown to the user in a simple and transparent way:
+
+```
+withdrawing from: <sender_account_name_or_hash>
+depositing to: <destination_account_name_or_hash>
+amount: <amount_parsed_to_decimal>
+fee: <fee_amount_parsed_to_decimal>
+status: <success/failed/pending/etc>
+```
+
+Appropriate designs must be created. The simplest example may look like below.
+
+![Confirming Tx](./assets/confirm-tx.png)
+
+# Change Log
+
+| Date        | Change      | Author |
+| :---------- | :---------- | :----- |
+| 25 Mar 2024 | First draft | karczu |