docs(Main+Send): document hub + four-step Send flow

- Main hub (View/VM): documents the three balance-fetch triggers, the
  cached-balance-prepend trick (no zero flash on launch), and the
  pre-warming of the gas-price cache for Send.
- SendCoordinator: linear four-step flow with the QR/deeplink intent
  merge into a single transactionIntent stream, plus topmost-scene gating
  to avoid stale prefills.
- Step 1 PrepareTransaction (View/VM): documents the four parallel
  concerns (balance fetch, per-field validation, sufficient-funds check,
  prefill). Switches the type_body_length disable to a same-line :this
  directive so it doesn't conflict with the docstring.
- Step 1.1 ScanQRCode (View/VM): zilliqa:// prefix stripping + Combine
  bridge from the third-party reader.
- Step 2 ReviewTransactionBeforeSigning (View/VM): read-only summary +
  formatted amount/fee/total + accept-checkbox gating.
- Step 3 SignTransaction (View/VM): wallet-keystore signing pipeline,
  errorTracker for wrong-password, flatMapLatest cancellation.
- Step 4 PollTransactionStatus (View/VM): polling with linear backoff,
  haptic + sound on receipt, four exit paths (skip/dismiss/view/timeout).

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Sources/Scenes/1_Main/2_Main/0_Main/Main.swift

@@ -25,12 +25,15 @@
 import Foundation
 import UIKit
 
+/// `SceneController` glue for the wallet hub screen.
 final class Main: Scene<MainView> {}
 
+/// Right-bar settings cog icon — taps fire `goToSettings` on the view-model.
 extension Main: RightBarButtonContentMaking {
     static let makeRightContent = BarButtonContent(image: UIImage(resource: .settings))
 }
 
+/// Translucent navigation bar so the parallax aurora background bleeds under it.
 extension Main: NavigationBarLayoutOwner {
     var navigationBarLayout: NavigationBarLayout {
         .translucent

Sources/Scenes/1_Main/2_Main/0_Main/MainView.swift

@@ -25,10 +25,16 @@
 import Combine
 import UIKit
 
+/// Wallet hub screen — shows balance with pull-to-refresh + send/receive CTAs.
+/// `PullToRefreshCapable` brings in the refresh control + its publishers.
 final class MainView: ScrollableStackViewOwner, PullToRefreshCapable {
+    /// Container hosting the parallax aurora background.
     private lazy var motionEffectAuroraImageView = UIView()
+    /// "Balance" label above the value.
     private lazy var balanceTitleLabel = UILabel()
+    /// The big balance number — uses the impression font.
     private lazy var balanceValueLabel = UILabel()
+    /// Zilliqa logo aligned bottom-left of the balance number.
     private lazy var zilliqaBalanceImageView = UIImageView()
     private lazy var zilliqaImageVerticalPositioner = UIStackView(arrangedSubviews: [
         .spacer,
@@ -59,6 +65,7 @@ final class MainView: ScrollableStackViewOwner, PullToRefreshCapable {
 extension MainView: ViewModelled {
     typealias ViewModel = MainViewModel
 
+    /// Surfaces pull-to-refresh + the two CTA taps.
     var inputFromView: InputFromView {
         InputFromView(
             pullToRefreshTrigger: pullToRefreshTriggerPublisher,
@@ -67,6 +74,8 @@ extension MainView: ViewModelled {
         )
     }
 
+    /// Binds fetching state → refresh-spinner, balance string → big number,
+    /// and last-updated copy → the refresh control's title.
     func populate(with viewModel: MainViewModel.Output) -> [AnyCancellable] {
         [
             viewModel.isFetchingBalance --> isRefreshingBinder,
@@ -77,6 +86,9 @@ extension MainView: ViewModelled {
 }
 
 private extension MainView {
+    /// Styling pass — labels, logo image, two image-above-label buttons,
+    /// and the parallax aurora background inserted *behind* the scrollView
+    /// so it stays put while content scrolls.
     func setupSubviews() {
         balanceTitleLabel.withStyle(.init(
             text: String(localized: .Main.balanceTitle),
@@ -117,6 +129,8 @@ private extension MainView {
     }
 }
 
+/// Shared helper that wires the three-layer aurora parallax into `effectView`.
+/// Used by both `MainView` and `LockAppScene` so the visual effect is identical.
 func addAuroraImagesWithMotionEffect(to effectView: UIView) {
     effectView.backgroundColor = .clear
     effectView.translatesAutoresizingMaskIntoConstraints = false

Sources/Scenes/1_Main/2_Main/0_Main/MainViewModel.swift

@@ -28,30 +28,44 @@ import Zesame
 
 // MARK: - MainUserAction
 
+/// Outcomes of the wallet hub.
 enum MainUserAction {
+    /// User tapped the Send CTA.
     case send
+    /// User tapped the Receive CTA.
     case receive
+    /// User tapped the right-bar settings cog.
     case goToSettings
 }
 
 // MARK: - MainViewModel
 
+/// View model for the wallet hub. Manages three independent triggers that
+/// fire a balance refetch (initial load, pull-to-refresh, post-send refresh)
+/// and surfaces formatted balance + freshness label to the view.
 final class MainViewModel: BaseViewModel<
     MainUserAction,
     MainViewModel.InputFromView,
     MainViewModel.Output
 > {
+    /// Network + cache façade for balance/gas-price calls.
     @Injected(\.transactionsUseCase) private var transactionUseCase: TransactionsUseCase
+    /// Wallet source — resolves to the persisted wallet.
     @Injected(\.walletStorageUseCase) private var walletStorageUseCase: WalletStorageUseCase
 
+    /// External pulse that asks for a refetch — e.g. the post-send hook from
+    /// `MainCoordinator.triggerFetchingOfBalance()`.
     private let updateBalanceTrigger: AnyPublisher<Void, Never>
 
     // MARK: - Initialization
 
+    /// Captures the external balance-refresh trigger.
     init(updateBalanceTrigger: AnyPublisher<Void, Never>) {
         self.updateBalanceTrigger = updateBalanceTrigger
     }
 
+    /// Composes the three refetch triggers, runs the balance use case,
+    /// caches the result, and surfaces formatted balance + freshness.
     override func transform(input: Input) -> Output {
         func userIntends(to intention: NavigationStep) {
             navigator.next(intention)
@@ -61,8 +75,15 @@ final class MainViewModel: BaseViewModel<
 
         let activityIndicator = ActivityIndicator()
 
+        // Three triggers fan into a single fetch stream:
+        //   - external (post-send) → updateBalanceTrigger
+        //   - user-initiated → pullToRefreshTrigger
+        //   - initial load → wallet emission
         let fetchTrigger = Publishers.Merge3(updateBalanceTrigger, input.fromView.pullToRefreshTrigger, wallet.mapToVoid()).eraseToAnyPublisher()
 
+        // Run the balance call. flatMapLatest cancels in-flight requests when
+        // a new trigger fires (e.g. user pulls again before the first fetch returns).
+        // handleEvents caches the balance for the next launch's pre-fetch UI.
         let latestBalanceAndNonce: AnyPublisher<BalanceResponse, Never> = fetchTrigger.withLatestFrom(wallet)
             .flatMapLatest { [unowned self] in
                 self.transactionUseCase
@@ -73,11 +94,14 @@ final class MainViewModel: BaseViewModel<
             }
             .eraseToAnyPublisher()
 
+        // Sample balanceUpdatedAt at fetch time for the "Updated N min ago" label.
         let balanceWasUpdatedAt = fetchTrigger.map { [unowned self] in
             self.transactionUseCase.balanceUpdatedAt
         }
 
         // Format output
+        // Show the cached balance immediately on first launch so the user
+        // doesn't see a "0 ZIL" flash before the network call resolves.
         let _cachedBalance: Amount = transactionUseCase.cachedBalance ?? 0
         let latestBalanceOrZero = latestBalanceAndNonce.map(\.balance).prepend(_cachedBalance)
 
@@ -91,6 +115,7 @@ final class MainViewModel: BaseViewModel<
             input.fromView.receiveTrigger
                 .sink { userIntends(to: .receive) },
 
+            // Pre-warm the gas-price cache so the Send screen has a value ready.
             transactionUseCase.getMinimumGasPrice().sink(receiveCompletion: { _ in }, receiveValue: { _ in }),
         ].forEach { $0.store(in: &cancellables) }
 
@@ -109,15 +134,23 @@ final class MainViewModel: BaseViewModel<
 }
 
 extension MainViewModel {
+    /// User-event publishers the view-model consumes.
     struct InputFromView {
+        /// Fires when the user pulls to refresh.
         let pullToRefreshTrigger: AnyPublisher<Void, Never>
+        /// Fires when the user taps Send.
         let sendTrigger: AnyPublisher<Void, Never>
+        /// Fires when the user taps Receive.
         let receiveTrigger: AnyPublisher<Void, Never>
     }
 
+    /// Reactive bindings the view installs.
     struct Output {
+        /// Drives the pull-to-refresh spinner.
         let isFetchingBalance: AnyPublisher<Bool, Never>
+        /// Pre-formatted balance string (ZIL, with thousands separator).
         let balance: AnyPublisher<String, Never>
+        /// Localized "Updated N min ago" string for the refresh control.
         let refreshControlLastUpdatedTitle: AnyPublisher<String, Never>
     }
 }

Sources/Scenes/1_Main/2_Main/A_Send/1_PrepareTransaction/0_PrepareTransaction/PrepareTransaction.swift

@@ -24,12 +24,15 @@
 
 import UIKit
 
+/// `SceneController` glue for the prepare-transaction screen (step 1 of Send).
 final class PrepareTransaction: Scene<PrepareTransactionView> {}
 
+/// Localized title; back arrow hidden because cancel is the only "back" path.
 extension PrepareTransaction: BackButtonHiding {
     static let title = String(localized: .PrepareTransaction.title)
 }
 
+/// Right "Cancel" button — aborts the entire Send flow.
 extension PrepareTransaction: RightBarButtonMaking {
     static let makeRight: BarButton = .cancel
 }

Sources/Scenes/1_Main/2_Main/A_Send/1_PrepareTransaction/0_PrepareTransaction/PrepareTransactionView.swift

@@ -27,6 +27,9 @@ import Factory
 import UIKit
 import Zesame
 
+/// Step 1 of Send — recipient/amount/gas entry with QR-scan + max-amount conveniences,
+/// plus pull-to-refresh on balance. The view-model handles validation, max-amount
+/// calculation (balance - gas), and QR-scan pre-fill routing.
 final class PrepareTransactionView: ScrollableStackViewOwner, PullToRefreshCapable {
     private lazy var balanceTitleLabel = UILabel()
     private lazy var balanceValueLabel = UILabel()

Sources/Scenes/1_Main/2_Main/A_Send/1_PrepareTransaction/0_PrepareTransaction/PrepareTransactionViewModel.swift

@@ -29,25 +29,37 @@ import Zesame
 
 // MARK: - PrepareTransactionUserAction
 
+/// Outcomes of step 1 of Send.
 enum PrepareTransactionUserAction {
+    /// User tapped the right-bar Cancel.
     case cancel
+    /// User submitted a fully-validated payment for review (advances to step 2).
     case reviewPayment(Payment)
+    /// User tapped the QR-scan icon — coordinator presents the scanner modal.
     case scanQRCode
 }
 
 // MARK: - PrepareTransactionViewModel
 
-// swiftlint:disable:next type_body_length
-final class PrepareTransactionViewModel: BaseViewModel<
+/// View model for step 1 of Send. Handles four parallel concerns:
+/// - balance fetch (with pull-to-refresh + cached-balance fallback);
+/// - real-time per-field validation (recipient, amount, gas limit, gas price);
+/// - cross-field "sufficient funds" check;
+/// - pre-fill from inbound `TransactionIntent` (deep-link or QR scan).
+final class PrepareTransactionViewModel: BaseViewModel< // swiftlint:disable:this type_body_length
     PrepareTransactionUserAction,
     PrepareTransactionViewModel.InputFromView,
     PrepareTransactionViewModel.Output
 > {
+    /// Network façade for balance + gas-price fetches.
     @Injected(\.transactionsUseCase) private var transactionUseCase: TransactionsUseCase
+    /// Wallet source for the recipient/amount/balance pipeline.
     @Injected(\.walletStorageUseCase) private var walletStorageUseCase: WalletStorageUseCase
 
+    /// Pre-fill source — merged stream of QR-scanned and deep-linked intents from the coordinator.
     private let scannedOrDeeplinkedTransaction: AnyPublisher<TransactionIntent, Never>
 
+    /// Captures the pre-fill source.
     init(scannedOrDeeplinkedTransaction: AnyPublisher<TransactionIntent, Never>) {
         self.scannedOrDeeplinkedTransaction = scannedOrDeeplinkedTransaction
     }

Sources/Scenes/1_Main/2_Main/A_Send/1_PrepareTransaction/1_ScanQR/ScanQRCodeController.swift

@@ -24,12 +24,15 @@
 
 import UIKit
 
+/// `SceneController` glue for the QR-code scanner side-trip from PrepareTransaction.
 final class ScanQRCode: Scene<ScanQRCodeView> {}
 
+/// Localized navigation title.
 extension ScanQRCode {
     static let title = String(localized: .ScanQRCode.title)
 }
 
+/// Left "Cancel" bar-button — closes the scanner without picking a transaction.
 extension ScanQRCode: LeftBarButtonMaking {
     static let makeLeft: BarButton = .cancel
 }

Sources/Scenes/1_Main/2_Main/A_Send/1_PrepareTransaction/1_ScanQR/ScanQRCodeView.swift

@@ -27,9 +27,14 @@ import Combine
 import QRCodeReader
 import UIKit
 
+/// QR-code scanner view backed by the third-party `QRCodeReader` library.
+/// Captures from the back camera and emits scanned strings through the view-model.
 final class ScanQRCodeView: UIView {
+    /// Bridges the third-party reader's `didFindCode` callback into a Combine publisher.
     private let scannedQrCodeSubject = PassthroughSubject<String?, Never>()
+    /// Library-provided viewfinder view.
     private lazy var readerView = QRCodeReaderView()
+    /// Underlying QR-code reader (back camera, QR metadata only).
     private lazy var reader = QRCodeReader(metadataObjectTypes: [.qr], captureDevicePosition: .back)
 
     init() {

Sources/Scenes/1_Main/2_Main/A_Send/1_PrepareTransaction/1_ScanQR/ScanQRCodeViewModel.swift

@@ -27,21 +27,35 @@ import Foundation
 
 // MARK: - User action and navigation steps
 
+/// Outcomes of the QR-scan modal.
 enum ScanQRCodeUserAction {
-    case /* user did */ cancel, scanQRContainingTransaction(TransactionIntent)
+    /// User tapped Cancel.
+    case cancel
+    /// QR code scanned and successfully decoded into a `TransactionIntent`.
+    case scanQRContainingTransaction(TransactionIntent)
 }
 
 // MARK: - ScanQRCodeViewModel
 
+/// View model for the QR scanner. Decodes scanned strings into a
+/// `TransactionIntent` and routes them upstream.
+///
+/// Accepts both raw JSON-payload QRs and ones prefixed with `zilliqa://`
+/// (the QR scheme other Zilliqa wallets emit).
 final class ScanQRCodeViewModel: BaseViewModel<
     ScanQRCodeUserAction,
     ScanQRCodeViewModel.InputFromView,
     ScanQRCodeViewModel.Output
 > {
+    /// Result type for the scan→decode pipeline.
     typealias ScannedQRResult = Result<TransactionIntent, Swift.Error>
 
+    /// Currently unused side-channel for "start scanning" pulses (kept for
+    /// future use if the reader needs an explicit start trigger).
     private let startScanningSubject = CurrentValueSubject<Void, Never>(())
 
+    /// Decodes scanned strings, strips an optional `zilliqa://` prefix, and
+    /// surfaces the resulting `TransactionIntent` (or cancel on bar-button tap).
     override func transform(input: Input) -> Output {
         func userDid(_ userAction: NavigationStep) {
             navigator.next(userAction)

Sources/Scenes/1_Main/2_Main/A_Send/2_ReviewTransaction/ReviewTransactionBeforeSigning.swift

@@ -24,8 +24,11 @@
 
 import Foundation
 
+/// `SceneController` glue for the review-transaction screen (step 2 of Send).
+/// Shows the prepared payment for the user to confirm before signing.
 final class ReviewTransactionBeforeSigning: Scene<ReviewTransactionBeforeSigningView> {}
 
+/// Localized navigation title.
 extension ReviewTransactionBeforeSigning {
     static let title = String(localized: .ReviewTransaction.title)
 }

Sources/Scenes/1_Main/2_Main/A_Send/2_ReviewTransaction/ReviewTransactionBeforeSigningView.swift

@@ -25,6 +25,8 @@
 import Combine
 import UIKit
 
+/// Step 2 of Send — read-only summary of the prepared payment (recipient,
+/// amount, gas, total) plus an "I have reviewed" checkbox + accept CTA.
 final class ReviewTransactionBeforeSigningView: ScrollableStackViewOwner {
     private lazy var recipientAddressesLabel = UILabel()
     private lazy var recipientLegacyAddressView = TitledValueView()

Sources/Scenes/1_Main/2_Main/A_Send/2_ReviewTransaction/ReviewTransactionBeforeSigningViewModel.swift

@@ -26,21 +26,30 @@ import Combine
 import Foundation
 import Zesame
 
+/// Outcome of step 2 of Send.
 enum ReviewTransactionBeforeSigningUserAction {
+    /// User checked "I have reviewed" and tapped accept; payment forwarded to signing.
     case acceptPaymentProceedWithSigning(Payment)
 }
 
+/// View model for step 2 of Send. Displays the prepared payment in human-readable
+/// form (formatted amounts, both legacy hex + bech32 recipient addresses) and
+/// gates the accept CTA on the "I have reviewed" checkbox.
 final class ReviewTransactionBeforeSigningViewModel: BaseViewModel<
     ReviewTransactionBeforeSigningUserAction,
     ReviewTransactionBeforeSigningViewModel.InputFromView,
     ReviewTransactionBeforeSigningViewModel.Output
 > {
+    /// The payment to display + forward.
     private let paymentToReview: Payment
 
+    /// Captures the payment to display.
     init(paymentToReview: Payment) {
         self.paymentToReview = paymentToReview
     }
 
+    /// Wires the accept-tap (carries `paymentToReview` upstream) and formats
+    /// the four displayed values (recipient hex/bech32, amount, fee, total).
     override func transform(input: Input) -> Output {
         func userDid(_ userAction: NavigationStep) {
             navigator.next(userAction)

Sources/Scenes/1_Main/2_Main/A_Send/3_SignTransaction/SignTransaction.swift

@@ -24,4 +24,6 @@
 
 import Foundation
 
+/// `SceneController` glue for the sign-transaction screen (step 3 of Send).
+/// Re-prompts for the wallet password and runs the actual signing + broadcast.
 final class SignTransaction: Scene<SignTransactionView> {}

Sources/Scenes/1_Main/2_Main/A_Send/3_SignTransaction/SignTransactionView.swift

@@ -25,6 +25,7 @@
 import Combine
 import UIKit
 
+/// Step 3 of Send — re-prompt for the keystore password and sign+broadcast on tap.
 final class SignTransactionView: ScrollableStackViewOwner {
     private lazy var confirmTransactionLabel = UILabel()
     private lazy var encryptionPasswordField = FloatingLabelTextField()