feat(docs): add redeemAmount and redeemWithTag functions, and new events for redemption process (#1341)

Author: fassko

docs/fassets/reference/IAssetManager.mdx

@@ -404,6 +404,76 @@ function redeem(
     returns (uint256 _redeemedAmountUBA);
 ```
 
+### `redeemAmount`
+
+Redeem up to `_amountUBA` FAssets, like [`redeem`](/fassets/reference/IAssetManager#redeem), but accepts an arbitrary amount in UBA instead of whole lots and does not require a destination tag.
+
+The `redeemAmount` function enforces a minimum redemption size `minimumRedeemAmount`.
+
+In some cases, not all sent FAssets can be redeemed (for example, if there are insufficient tickets or the maximum ticket limit has been reached).
+In that case, only part of the approved assets are burned and redeemed, and the redeemer can call this method again for the remaining amount.
+The [`RedemptionAmountIncomplete`](/fassets/reference/IAssetManagerEvents#redemptionamountincomplete) event is emitted with the remaining amount.
+
+Parameters:
+
+- `_amountUBA`: Amount of redeemer's FAssets that will be burned (this is not the received amount; redemption fee is subtracted).
+- `_redeemerUnderlyingAddressString`: Address to which the agent must transfer the underlying amount.
+- `_executor`: Account that can execute redemption default (besides redeemer and agent).
+
+Returns:
+
+- `_redeemedAmountUBA`: Actual redeemed amount; may be less than requested when ticket availability or ticket limits apply.
+
+```solidity
+function redeemAmount(
+    uint256 _amountUBA,
+    string memory _redeemerUnderlyingAddressString,
+    address payable _executor
+) external payable
+    returns (uint256 _redeemedAmountUBA);
+```
+
+### `redeemWithTag`
+
+Redeem up to `_amountUBA` FAssets and require a destination tag in the redemption XRPL payment.
+
+In some cases, not all sent FAssets can be redeemed (for example, if there are insufficient tickets or the maximum ticket limit has been reached).
+In that case, only part of the approved assets are burned and redeemed, and the redeemer can call this method again for the remaining amount.
+The [`RedemptionAmountIncomplete`](/fassets/reference/IAssetManagerEvents#redemptionamountincomplete) event is emitted with the remaining amount.
+
+Parameters:
+
+- `_amountUBA`: Amount of redeemer's FAssets that will be burned (this is not the received amount; redemption fee is subtracted).
+- `_redeemerUnderlyingAddressString`: Address to which the agent must transfer the underlying amount.
+- `_executor`: Account that can execute redemption default (besides redeemer and agent).
+- `_destinationTag`: Destination tag required in redemption payment (XRP only; must fit in 32 bits for now).
+
+Returns:
+
+- `_redeemedAmountUBA`: Actual redeemed amount; may be less than requested when ticket availability or ticket limits apply.
+
+```solidity
+function redeemWithTag(
+    uint256 _amountUBA,
+    string memory _redeemerUnderlyingAddressString,
+    address payable _executor,
+    uint256 _destinationTag
+) external payable
+    returns (uint256 _redeemedAmountUBA);
+```
+
+### `minimumRedeemAmountUBA`
+
+Minimum amount in UBA for redemption with tag.
+Redemption requests with smaller amounts are rejected.
+This governance-configured minimum applies to both [`redeemAmount`](/fassets/reference/IAssetManager#redeemamount) and [`redeemWithTag`](/fassets/reference/IAssetManager#redeemwithtag) functions.
+
+```solidity
+function minimumRedeemAmountUBA()
+    external view
+    returns (uint256);
+```
+
 ### `redemptionPaymentDefault`
 
 If the agent fails to transfer the redeemed underlying assets in a timely manner, the redeemer or appointed executor can invoke this method and receive payment in collateral.

docs/fassets/reference/IAssetManagerEvents.mdx

@@ -222,6 +222,48 @@ event RedemptionRequested(
     uint256 executorFeeNatWei);
 ```
 
+### `RedemptionWithTagRequested`
+
+Emitted when the redeemer starts redemption with the tag and provides FAssets.
+The amount corresponding to `valueUBA` FAssets is burned.
+
+Several `RedemptionWithTagRequested` events can be emitted in a single redemption call (one per redeemed agent, with multiple tickets for the same agent combined).
+The agent's collateral remains locked at this stage.
+
+Parameters:
+
+- `agentVault`: Address of the agent vault.
+- `redeemer`: Address of the redeemer.
+- `requestId`: Unique identifier for the redemption request.
+- `paymentAddress`: Address on the underlying chain to which the agent must transfer the payment.
+- `valueUBA`: Amount redeemed in underlying base units.
+- `feeUBA`: Redemption fee in underlying base units.
+- `firstUnderlyingBlock`: First underlying block in the valid payment window.
+- `lastUnderlyingBlock`: Last underlying block in the valid payment window.
+- `lastUnderlyingTimestamp`: Last underlying timestamp in the valid payment window.
+- `paymentReference`: Payment reference that must be used in the underlying payment.
+- `executor`: Address allowed to execute redemption default (besides redeemer and agent).
+- `executorFeeNatWei`: Fee paid to the executor in NAT wei.
+- `destinationTag`: Destination tag required for the XRP payment.
+
+```solidity
+event RedemptionWithTagRequested(
+    address indexed agentVault,
+    address indexed redeemer,
+    uint256 indexed requestId,
+    string paymentAddress,
+    uint256 valueUBA,
+    uint256 feeUBA,
+    uint256 firstUnderlyingBlock,
+    uint256 lastUnderlyingBlock,
+    uint256 lastUnderlyingTimestamp,
+    bytes32 paymentReference,
+    address executor,
+    uint256 executorFeeNatWei,
+    uint256 destinationTag
+);
+```
+
 ### `RedemptionTicketCreated`
 
 This event is emitted when a redemption ticket is created, when a minting transaction is executed.
@@ -302,6 +344,22 @@ event RedemptionRequestIncomplete(
 );
 ```
 
+### `RedemptionAmountIncomplete`
+
+Emitted when only a partial redemption can occur, for instance, if there are insufficient redemption tickets or if fulfilling the entire request would exceed the allowed ticket limit.
+
+Parameters:
+
+- `redeemer`: Address of the user who requested redemption.
+- `remainingAmountUBA`: Amount (UBA) that could not be redeemed and is returned.
+
+```solidity
+event RedemptionAmountIncomplete(
+    address indexed redeemer,
+    uint256 remainingAmountUBA
+);
+```
+
 ### `RedemptionDefault`
 
 Emitted when a redemption payment times out and the redeemer is compensated with collateral instead.

src/features/FAssets/OperationalParameters/operational-parameters.ts

@@ -155,6 +155,29 @@ export const operationalParameters = [
           },
         },
       },
+      {
+        name: "Minimum Redeem Amount",
+        settingName: "minimumRedeemAmountUBA",
+        link: "/fassets/reference/IAssetManager#minimumredeemamountuba",
+        description:
+          "Minimum amount that can be redeemed, in base unit of the underlying asset (UBA).",
+        values: {
+          flare: {
+            xrp: "-",
+          },
+          coston2: {
+            xrp: "5 TestXRP",
+          },
+          songbird: {
+            xrp: "-",
+          },
+          coston: {
+            xrp: "-",
+            btc: "-",
+            doge: "-",
+          },
+        },
+      },
     ],
   },
   {