feat(docs): update FAssets guides for v1.3 (#1312)

Author: nikerzetic-aflabs

docs/fassets/01-overview.mdx

@@ -37,7 +37,9 @@ Agents and a community-provided collateral pool ensure trustlessness through ove
   }}
 />
 
-Anyone on the Flare blockchain can mint FAssets, which are wrapped versions of original tokens from other blockchains, known as underlying networks. The original tokens from these chains, such as Ripple (XRPL), Dogecoin (DOGE), Bitcoin (BTC), and Litecoin (LTC), are referred to as underlying assets. For example, the FAsset version of Bitcoin is known as FBTC.
+Anyone on the Flare blockchain can mint FAssets, which are wrapped versions of original tokens from other blockchains, known as underlying networks.
+The original tokens from these chains, such as Ripple (XRPL), Dogecoin (DOGE), Bitcoin (BTC), and Litecoin (LTC), are referred to as underlying assets.
+For example, the FAsset version of Bitcoin is known as FBTC.
 
 ### Minting
 
@@ -99,7 +101,8 @@ Eligibility:
 
 ### Challengers
 
-Challengers monitor agents for illegal transactions that reduce collateral below the backing factor. They:
+Challengers monitor agents for illegal transactions that reduce collateral below the backing factor.
+They:
 
 - Submit proof of illegal actions to the system.
 - Earn rewards from the agent's vault upon successful challenges.

docs/fassets/02-minting.mdx

@@ -31,7 +31,8 @@ This is the summary of the minting process:
 The minter chooses an agent from the publicly available [agent list](/fassets/overview#agents).
 The choice is based on the minting fee or the amount of free collateral, which must be enough to back the amount to be minted.
 
-The minter sends to the Asset Manager contract a collateral reservation transaction (CRT). The CRT includes:
+The minter sends to the Asset Manager contract a collateral reservation transaction (CRT).
+The CRT includes:
 
     - The address of the chosen agent.
     - The amount to mint, which must be a positive integer of [lots](/fassets/minting#lots).
@@ -120,11 +121,13 @@ The minting fee is further divided in two shares:
 
 #### Agent share
 
-This share remains in the agent's underlying account but is not marked as being in use. The agent can use this balance freely.
+This share remains in the agent's underlying account but is not marked as being in use.
+The agent can use this balance freely.
 
 #### Pool share
 
-This share is minted as FAssets and sent to the [collateral pool](/fassets/collateral#pool-collateral). The percentage of this share is defined by the agent and can be changed by the agent after a delay that provides time for minters to notice the change.
+This share is minted as FAssets and sent to the [collateral pool](/fassets/collateral#pool-collateral).
+The percentage of this share is defined by the agent and can be changed by the agent after a delay that provides time for minters to notice the change.
 
 ### Executor Fee
 
@@ -140,13 +143,21 @@ This design ensures timely and reliable minting finalization without relying on
 
 ### Minting
 
-The FAssets agent verifies the minter after the user completes the collateral reservation and pays the collateral reservation fee. The agent is responsible for confirming or rejecting the minter's status. If the agent does not respond within a certain timeframe, the minter has the option to cancel the reservation and receive a full refund of the collateral reservation fee.
+The FAssets agent verifies the minter after the user completes the collateral reservation and pays the collateral reservation fee.
+The agent is responsible for confirming or rejecting the minter's status.
+If the agent does not respond within a certain timeframe, the minter has the option to cancel the reservation and receive a full refund of the collateral reservation fee.
 
-To enable the agent to verify the minter, the collateral reservation must include the address (or multiple addresses, in the case of UTXO chains) from which the payment will be made. If multiple addresses are provided, all of them must be used for the payment.
+To enable the agent to verify the minter, the collateral reservation must include the address (or multiple addresses, in the case of UTXO chains) from which the payment will be made.
+If multiple addresses are provided, all of them must be used for the payment.
 
-Users must wait up to 60 seconds before they can cancel their request. If the agent accepts within this time, the user can proceed to mint by depositing the underlying assets. Therefore, it is important for the agent to respond quickly. If the agent does not respond in time, it will depend on whether the user is willing to wait; otherwise, the agent will simply miss the opportunity to mint, but there will be no loss of tokens.
+Users must wait up to 60 seconds before they can cancel their request.
+If the agent accepts within this time, the user can proceed to mint by depositing the underlying assets.
+Therefore, it is important for the agent to respond quickly.
+If the agent does not respond in time, it will depend on whether the user is willing to wait; otherwise, the agent will simply miss the opportunity to mint, but there will be no loss of tokens.
 
-When the agent rejects the minter's request or the minter decides to cancel, the minter will receive a refund of the collateral reservation fee, minus a small percentage (e.g., 5%) that is burned. This burned amount is designed to prevent abuse of the agent by stopping someone from repeatedly reserving collateral from a sanctioned address. If the burned percentage were zero, an attacker could exploit the system without any cost.
+When the agent rejects the minter's request or the minter decides to cancel, the minter will receive a refund of the collateral reservation fee, minus a small percentage (e.g., 5%) that is burned.
+This burned amount is designed to prevent abuse of the agent by stopping someone from repeatedly reserving collateral from a sanctioned address.
+If the burned percentage were zero, an attacker could exploit the system without any cost.
 
 ## Payment Failure
 
@@ -200,7 +211,8 @@ FAssets are still transferred to the minter's account, and the agent's collatera
 ### Expired proof
 
 Proofs provided by the [Flare Data Connector](/fdc/overview) can be created for 14 days and remain valid indefinitely once created.
-Suppose neither the minter nor the agent presents the proof of payment or nonpayment within the 14-day window. In that case, the regular minting process cannot continue, and the agent's collateral could be locked indefinitely.
+Suppose neither the minter nor the agent presents the proof of payment or nonpayment within the 14-day window.
+In that case, the regular minting process cannot continue, and the agent's collateral could be locked indefinitely.
 
 In this case, the agent can still recover the collateral by buying it back with native tokens.
 The recovery is accomplished with the following procedure:

docs/fassets/03-direct-minting.mdx

@@ -0,0 +1,112 @@
+---
+title: Direct Minting
+description: Understand how direct minting works in FAssets.
+keywords: [fassets, xrp, flare-network, direct-minting]
+---
+
+Direct minting allows users to mint FAssets by creating a single transaction on the underlying chain, bypassing the multi-step [collateral reservation process](/fassets/minting#minting-process) of standard minting.
+This feature is currently available only for XRP.
+
+## How It Works
+
+The minter creates a payment transaction on the underlying chain (XRPL) to the [Core Vault](/fassets/core-vault) address, not to an individual agent's address.
+The transaction identifies the minting parameters (recipient and executor) through either a **destination tag** or a **memo field**.
+
+An **executor** then calls `executeDirectMinting` on the Flare side to finalize the mint.
+The executor is paid a fee upon successful completion.
+
+## Fees
+
+Direct minting charges two fees, both deducted from the underlying payment amount:
+
+- **Minting fee**: A percentage of the received amount (in BIPS), with a minimum floor.
+  This fee is paid to a governance-configured fee receiver.
+  If the payment is smaller than the minimum minting fee, no FAssets are minted and the entire payment goes to the fee receiver.
+- **Executor fee**: A flat fee in the underlying asset, paid to the executor who finalizes the minting.
+  The minting fee takes priority: if the payment only covers the minting fee, the executor receives nothing.
+
+## Identifying Minting Parameters
+
+There are two ways to specify the minting recipient and executor in a direct minting payment.
+
+### Destination Tag
+
+XRPL transactions natively support a **destination tag**, a 32-bit integer.
+The `MintingTagManager` contract on Flare acts as a registry that maps these destination tags to Flare-side parameters: the minting recipient and the preferred executor.
+
+The tag on the XRPL side and the tag registered in `MintingTagManager` on Flare are the same tag.
+The Flare contract gives the XRPL tag its meaning in the FAsset system.
+This path is convenient for repeated use, such as an exchange or service that regularly mints.
+
+### Memo Field
+
+Instead of a tag, the minter can encode the minting parameters directly in the memo field on the XRPL payment.
+There are two supported formats:
+
+**32-byte memo** (recipient only):
+
+A standard direct minting payment reference that encodes only the 20-byte recipient address.
+Anyone can execute, as no executor is specified.
+
+**48-byte memo** (recipient and executor):
+
+1. **8-byte prefix**: `0x4642505266410021` (`DIRECT_MINTING_EX`)
+2. **20-byte recipient address**
+3. **20-byte executor address**
+
+If the executor address is the zero address, anyone can execute.
+
+No reservation is needed for either format, but the memo must be constructed for each payment.
+
+## Minting Tag Manager
+
+The `MintingTagManager` contract on Flare manages the reservation and ownership of XRPL destination tags for direct minting.
+
+- Users reserve destination tags by paying a reservation fee in native currency (FLR/SGB).
+  The fee exists because the XRPL destination tag space is limited to 32-bit integers, and without a cost, someone could squat on all available tags.
+- Tags are assigned sequentially.
+  The user always receives the next available tag.
+- The contract implements the **ERC-721** (NFT) interface, so reserved tags can be transferred or resold.
+- Tag owners can set a minting recipient with `setMintingRecipient` and a preferred executor with `setAllowedExecutor`.
+  Executor changes are not immediate: the new executor becomes active after a 10-minute cooldown to protect in-flight FDC proofs.
+- On initial reservation and tag transfer, the recipient resets to the new owner and the executor resets to the zero address.
+
+## Executor Restrictions
+
+Executors can be restricted in three ways depending on the minting method:
+
+1. **Tag-based:** The tag manager's `setAllowedExecutor` method defines the allowed executor.
+   If set to the zero address, anyone can execute.
+2. **Memo-based:** The 48-byte memo format encodes the executor address directly.
+   The 32-byte memo format does not specify an executor, so anyone can execute.
+   If the executor address in the 48-byte format is the zero address, anyone can also execute.
+3. **Smart account:** The smart account manager may restrict the executor.
+   The asset manager passes every request through.
+
+If the preferred executor does not act within `othersCanExecuteAfterSeconds`, anyone can execute the minting.
+
+## Rate Limits
+
+Direct minting has multiple rate-limiting safeguards to protect against compromises, such as FDC exploits.
+
+| Limit                                   | Description                                           |
+| :-------------------------------------- | :---------------------------------------------------- |
+| `directMintingHourlyLimitUBA`           | Hourly minting cap                                    |
+| `directMintingDailyLimitUBA`            | Daily minting cap                                     |
+| `directMintingLargeMintingThresholdUBA` | Threshold above which a minting is considered "large" |
+| `directMintingLargeMintingDelaySeconds` | Automatic delay for large mintings                    |
+
+Rate limits **throttle** rather than reject.
+When limits are hit, further mintings are delayed proportionally to the accumulated backlog.
+Large mintings above the threshold are delayed independently by a fixed duration.
+
+Delayed mintings emit the `DirectMintingDelayed` event instead of `DirectMintingExecuted`, with an `executionAllowedAt` timestamp.
+Governance can unblock delayed mintings via `unblockDirectMintingsUntil`, but only for past timestamps and after manual review.
+
+If a preferred executor's minting is delayed, their exclusive execution window restarts from `executionAllowedAt`.
+
+:::tip[What's next]
+
+Learn more about the different components and processes involved in FAssets - [standard minting](/fassets/minting), [redemptions](/fassets/redemption), [collateral](/fassets/collateral), [liquidations](/fassets/liquidation), and [Core Vault](/fassets/core-vault).
+
+:::

docs/fassets/03-redemption.mdx docs/fassets/04-redemption.mdxdocs/fassets/03-redemption.mdx renamed to docs/fassets/04-redemption.mdx

@@ -11,7 +11,8 @@ To do so, these holders, known as redeemers, send FAssets to the Asset Manager s
 
 This is the summary of the redemption process:
 
-1. The redeemer starts the redemption for a positive integer of lots by issuing a request to the Asset Manager smart contract.
+1. The redeemer starts the redemption by issuing a request to the Asset Manager smart contract.
+   The standard `redeem` method requires a whole number of lots, while `redeemAmount` and `redeemWithTag` allow redeeming any amount.
 
    The FAssets system chooses one or more redemption tickets from the front of the [FIFO redemption queue](/fassets/minting#redemption-tickets-and-the-redemption-queue).
    The number of chosen redemption tickets is capped to avoid high gas consumption.
@@ -51,6 +52,25 @@ This is the summary of the redemption process:
 
    After the collateral is released, it can either back the minting of more FAssets or be withdrawn.
 
+## Redeem Any Amount
+
+The standard `redeem` method requires whole lots.
+The `redeemAmount` method allows redeeming **any amount** of FAssets, which is useful for redeeming yields or partial amounts that don not align with lot boundaries.
+
+No redemption through `redeemAmount` or `redeemWithTag` can be smaller than `minimumRedeemAmountUBA` to prevent uneconomical micro-redemptions.
+If the requested amount requires too many redemption tickets, only a partial redemption is performed and the remaining amount is returned in a `RedemptionAmountIncomplete` event.
+
+## Redeem with Tag
+
+The `redeemWithTag` method allows the redeemer to request an **XRP destination tag** on the redemption payment.
+This is useful when redeeming directly to an exchange address that requires a destination tag.
+Like `redeemAmount`, it also supports redeeming any amount, not just whole lots.
+
+The destination tag must fit in a 32-bit integer.
+This is an XRP-only feature, gated by the `redeemWithTagSupported` flag.
+Confirming a redemption with a tag requires the `confirmXRPRedemptionPayment` method, which uses a dedicated FDC proof type that supports destination tags.
+If the agent fails to pay, the redeemer calls `xrpRedemptionPaymentDefault` to trigger the default process.
+
 ## Fees
 
 These fees are charged when a user redeems FAssets for the underlying asset:
@@ -116,6 +136,12 @@ During step 4 above, if any agent does not pay on the underlying chain, the rede
    This remainder is derived from the [system-wide collateral ratio settings](/fassets/collateral#system-wide-thresholds) specified by governance.
 5. The underlying assets backing the redeemed FAssets are marked as free and can be withdrawn by the agent later.
 
+## Redemption Time Extension
+
+When many redemption requests target the same agent in rapid succession, the system automatically extends the agent's payment deadline.
+Each new redemption request adds time to the deadline, which then gradually decays back to the baseline as the volume of requests decreases.
+This mechanism prevents agents from being overwhelmed by a burst of redemptions and failing to pay in time through no fault of their own.
+
 ## Edge Cases
 
 ### Unresponsive redeemer