docs: [ADP-3270] Support key deposit refund lookup in `Write.balanceT…

…x` & new tx workflow (#4690) - [x] Add new `PartialTx` field `keyDeposits` for looking up stake key UnReg refunds - This allows us to stop assuming the deposited amount equals the `ppKeyDeposit` value of the current protocol parameters. - [x] Test that `Write.balanceTx` takes it into account - [x] Query deposit amounts with LSQ for the new tx workflow (construct, construct-shared, balance) ### For later - Query deposit amounts for the old tx workflow - Improve the internals of `Write.balanceTx`. This PR muddies the point of `TxWithUTxO` and the distinction between `balanceTx` and `balanceTxInner`. We could imagine a new type ```haskell -- | Tx with enough additional context to evaluate it's balance etc (may or may not include PParams) data TxWithContext evaluateBalanceAfterSettingMinFee :: TxWithContext -> (Value, Coin, KeyWitnessCounts) balance :: TxWithContext -> Value -- | Will also modify the UTxO applySelection :: TxWithContext -> SelectAssetsResult -> TxWithContext ``` where we'd let `balanceTxInner` take `TxWithContext` instead of `Tx` + related args. However, we'd either need to include the entire `referenceUTxO` (`extraUTxO <> walletUTxO`) in the `utxo` of the `TxWithContext` and later trust that the inputs from the `SelectAssetsResult` can be resolved, or we'd need to do something else... The relationship of `PartialTx` with a new `TxWithContext` may also be awkward, as they would be almost — but not quite — the same. E.g. `PartialTx` contains a `redeemers` field. ### Comments <!-- Additional comments, links, or screenshots to attach, if any. --> ### Issue Number ADP-3270 Source commit: 17cc50f

api/edge/swagger.yaml

@@ -5609,6 +5609,19 @@ x-errUnresolvedInputs: &errUnresolvedInputs
       type: string
       enum: ['unknown_inputs']
 
+x-errUnresolvedRefunds: &errUnresolvedRefunds
+  <<: *responsesErr
+  title: unresolved_refunds
+  properties:
+    message:
+      type: string
+      description: |
+        There are stake key deregistration certificates in the transaction for which corresponding
+        deposit amounts could not be found.
+    code:
+      type: string
+      enum: ['unresolved_refunds']
+
 x-errRedeemerInvalidData: &errRedeemerInvalidData
   <<: *responsesErr
   title: redeemer_invalid_data