Add initial architecture documentation

Author: matthewwalsh0

packages/transaction-pay-controller/ARCHITECTURE.md

@@ -0,0 +1,56 @@
+# Architecture
+
+The ultimate purpose of the `TransactionPayController` is to automatically transfer ERC-20 tokens to the appropriate chains and accounts, in order to enable and simplify EVM transactions.
+
+This functionality is referred to as `MetaMask Pay` in the MetaMask clients.
+
+## Required Tokens
+
+The ERC-20 tokens required by a transaction are automatically identified from various sources, this includes:
+
+- ERC-20 Token Transfers
+  - Identified from the call data using the `0xa9059cbb` four-byte prefix.
+  - Supports EIP-7702 transactions where the token transfer is a nested call.
+- Gas Fees
+  - A required native token is generated from the gas limit and gas fee parameters, including estimates from the `GasFeeController`.
+
+## Pay Strategies
+
+The mechanism by which the tokens are moved is abstracted into a `PayStrategy`.
+
+Each `PayStrategy` dictates how the `quotes` are retrieved, which detail the associated fees and strategy specific data, and how those quotes are actioned or "submitted".
+
+### Bridge
+
+The `BridgeStrategy` retrieves quotes from the MetaMask Bridge API via the `BridgeController`, and submits quotes via the `BridgeStatusController`.
+
+The `BridgeStatusController` generates suitable transactions via the `TransactionController` that target the MetaMask Bridge contract which in turn communicates with a specific Bridge provider.
+
+### Relay
+
+The `RelayStrategy` retrieves quotes from the [Relay API](https://docs.relay.link/what-is-relay), then submits the necessary transactions directly to the `TransactionController`.
+
+The resulting transaction deposits the necessary funds (on the source network), then a Relayer on the target chain immediately transfers the necessary funds and optionally executes any requested call data.
+
+## Client Lifecycle
+
+The high level interaction with the `TransactionPayController` is as follows:
+
+1. Controller subscribes to `TranasctionController` state changes during initialisation.
+2. An unapproved transaction is created in a MetaMask client, either internally or via a dApp.
+3. Controller identifies any required tokens and adds them to its state.
+4. If a client confirmation is using `MetaMask Pay`, the user selects a payment token (or it is done automatically) which invokes the `updatePaymentToken` action.
+5. Controllers selects an appropriate `PayStrategy` using the `getStrategy` action.
+6. Controller requests quotes from the `PayStrategy` and persists them in state, including associated totals.
+7. Resulting fees and totals are presented in the client transaction confirmation.
+8. If approved by the user, the target transaction is signed and published.
+9. The `TransactionPayPublishHook` is invoked as this is specified by the client during `TransactionController` initialisation.
+10. Publish hook submits the quotes via the same `PayStrategy`.
+11. Depending on the pay strategy and required tokens, the original target transaction is also published as the required funds are now in place on the user's account on the target chain.
+12. Target transaction is finalized and relevant controller state is removed.
+
+## State
+
+State is grouped according to the associated transaction ID in the `transactionData` property.
+
+This transaction specific data includes any required tokens, selected payment token, retrieved quotes, and calculated totals.