fix(docs): fixes problems in guides (#872)

Author: nikerzetic-aflabs

docs/fassets/1-overview.mdx

@@ -60,7 +60,7 @@ Agents manage the infrastructure and operations of the FAssets system, including
 - Providing collateral for minting and redemption.
 - Redeeming underlying assets for users.
 
-Each agent is verified through governance and uses the following addresses:
+Each agent is verified through governance and uses the following addresses on the native chain:
 
 - **Work Address:** A hot wallet for executing operations.
 - **Management Address:** A cold wallet for secure administrative actions.

docs/fassets/2-minting.mdx

@@ -30,7 +30,7 @@ The choice is based on the minting fee or the amount of free collateral, which m
 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 whole number of [lots](/fassets/minting#lots).
+    - The amount to mint, which must be a positive integer of [lots](/fassets/minting#lots).
     - The [collateral reservation fee (CRF)](#fees) to compensate for the locked collateral.
     - The executor's address, if the minter is not the executor.
     - The executor's fee, if the minter is not the executor.
@@ -51,7 +51,8 @@ The collateral reservation response is an event issued by the contract, which in
 
 ### 2. Underlying Payment
 
-After this event is emitted, the minter must pay the full underlying amount plus the fee to the agent on the underlying chain in a certain amount of time.
+After this event is emitted, the minter must pay the full underlying amount plus the fee to the agent on the underlying chain.
+This payment must be completed within a specified time limit.
 
 ### 3. Payment Proof
 
@@ -148,11 +149,11 @@ The [agent's registration process](/fassets/overview#agents) verifies that the a
 The following example shows proof of nonpayment.
 
 <details>
-<summary>Proof of nonpayment example.</summary>
+<summary>Referenced payment nonexistence attestation type example.</summary>
 
 The following example shows how the nonpayment proof works.
 
-The Data Connector's [payment nonexistence attestation type](https://gitlab.com/flarenetwork/state-connector-protocol/-/blob/main/specs/attestations/active-types/ReferencedPaymentNonexistence.md?ref_type=heads) proves nonpayment.
+The Flare Data Connector's [referenced payment nonexistence attestation type](/fdc/attestation-types/referenced-payment-nonexistence) proves nonpayment.
 
 1. The minter sends a request to mint FBTC.
    At the time the request is received, the last mined block on the Bitcoin chain is number 92, with timestamp 09:00 AM.
@@ -172,7 +173,7 @@ The Data Connector's [payment nonexistence attestation type](https://gitlab.com/
 5. The agent sends a nonpayment attestation request, which includes the payment reference, the underlying amount that was expected, the last block (100), and the last timestamp (11:00).
 6. Attestation providers attest to the following facts:
    - Block 102 is finalized and has both the number and timestamp larger than required.
-   - Until this block, the required payment either was not made or was not sufficient.
+   - Before this block, the required payment either was not made or was not sufficient.
 
 Now, the mint-payment failure and the nonpayment proof can be submitted to the FAssets system.
 
@@ -188,14 +189,14 @@ FAssets are still transferred to the minter's account, and the agent's collatera
 
 ### Expired proof
 
-Proofs provided by the Data Connector are available for only 24 hours, approximately.
+Proofs provided by the Flare Data Connector are available for only 24 hours, approximately.
 If neither the minter nor the agent presents the proof of payment or nonpayment within 24 hours, 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:
 
     1. Request the proof from the time when the deposit should have happened.
-     The Data Connector's answer will indicate that payments proofs are no longer available for that time.
+     The Flare Data Connector's answer will indicate that payments proofs are no longer available for that time.
     2. Provide the amount of FLR collateral equivalent to the price of the underlying assets that should have been deposited.
     3. Present the proof.
 
@@ -214,7 +215,7 @@ The maximum duration of the process is the sum of:
 - A system-defined maximum time for deposit.
   It is either a few blocks on the underlying chain or a few minutes, whichever is longer.
 - The underlying chain's finalization time.
-- The Data Connector proof time, which is approximately 3 - 5 minutes, independent of the underlying chain.
+- The Flare Data Connector proof time, which is approximately 3 - 5 minutes, independent of the underlying chain.
 
 On fast chains like XRPL, the maximum total time is less than 10 minutes, while on Bitcoin it is approximately 1.5 hours.
 For payment failures, the agent needs to wait the maximum time, as defined above, before the nonpayment proof can be retrieved.
@@ -243,11 +244,11 @@ The following example shows how the redemption queue works.
 <details>
 <summary>Redemption queue example.</summary>
 
-1.  Bob mints 10 FXRP with Agent 1.
-2.  Alice mints 20 FXRP with Agent 2.
+1.  Alice mints 10 FXRP with Agent 1.
+2.  Bob mints 20 FXRP with Agent 2.
 3.  Charlie mints 5 FXRP with Agent 1.
 
-    After Bob, Alice, and Charlie have minted their FAssets, the redemption queue according to the FIFO method is:
+    After Alice, Bob, and Charlie have minted their FAssets, the redemption queue according to the FIFO method is:
     1. Agent 1 with 10 FXRP.
     2. Agent 2 with 20 FXRP.
     3. Agent 1 with 5 FXRP.
@@ -265,7 +266,7 @@ The following example shows how the redemption queue works.
 
 ## Lots
 
-Every minting and redemption must be made in a whole number of lots.
+Every minting and redemption must be made in a positive integer of lots.
 Lots serve the following purposes:
 
 - They prevent underlying transaction fees from exceeding minting or redemption fees.
@@ -284,9 +285,9 @@ Some processes generate a fractional number of lots:
 
 - On minting, part of the minting fee is minted as the FAsset fee to the collateral pool.
   This value is usually less than 1 lot.
-- When the lot size is changed, redemptions close only a whole number of lots of each redemption ticket, which leaves the remainder unredeemed.
+- When the lot size is changed, redemptions close only a positive integer of lots of each redemption ticket, which leaves the remainder unredeemed.
 
-These amounts, known as dust, cannot be redeemed directly because redemption requires a whole number of lots.
+These amounts, known as dust, cannot be redeemed directly because redemption requires a positive integer of lots.
 
 In such cases, the generated dust is not included in any redemption ticket.
 Instead, each agent's dust is accumulated until the dust amounts to a whole lot.

docs/fassets/3-redemption.mdx

@@ -11,7 +11,7 @@ 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 whole number of lots by issuing a request to the Asset Manager smart contract.
+1. The redeemer starts the redemption for a positive integer of lots by issuing a request to the Asset Manager smart contract.
 
    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.
@@ -24,7 +24,7 @@ This is the summary of the redemption process:
    For every agent participating in the redemption, the system issues an event with the following redemption payment information:
    - Redeemer's underlying address.
 
-     Agents can use the Data Connector to ensure the validity of this address.
+     Agents can use the Flare Data Connector to ensure the validity of this address.
      Otherwise, malicious redeemers could provide an address that systematically blocks payments and exploit the redeeming process to their advantage.
 
    - Amount to pay minus the fee that was already subtracted.
@@ -67,7 +67,7 @@ If the agent does not report the failed payment in time, anyone (including the e
 
 :::info
 
-    When payment fails because of the redeemer, the agent can obtain a proof of the failed payment from the Data Connector and present it to the FAssets system.
+    When payment fails because of the redeemer, the agent can obtain a proof of the failed payment from the Flare Data Connector and present it to the FAssets system.
     The agent's obligation is then fulfilled, and he can keep both the collateral and the underlying.
 
     Two different proofs can be used:
@@ -76,13 +76,13 @@ If the agent does not report the failed payment in time, anyone (including the e
     * Proof of blocked payment: Even if the address is valid, it might contain a contract that blocks the payment.
         This can only happen on underlying networks supporting smart contracts.
 
-        The agent must still try to pay and, if the payment is blocked, the agent can request this proof from the Data Connector and present it to the FAssets system.
+        The agent must still try to pay and, if the payment is blocked, the agent can request this proof from the Flare Data Connector and present it to the FAssets system.
 
 :::
 
 During step 4 above, if any agent does not pay on the underlying chain, the redeemer completes the following procedure separately for each nonpaying agent:
 
-1. The redeemer obtains a proof of nonpayment from the Data Connector.
+1. The redeemer obtains a proof of nonpayment from the Flare Data Connector.
 2. The redeemer presents the nonpayment proofs to the FAssets system, which triggers a redemption failure.
 3. The redeemer is paid with collateral, according to the current price plus a premium.
 4. FAssets are overcollateralized, so, even after paying the redeemer with a premium, a remainder is released.
@@ -107,7 +107,7 @@ After enough time for the agent to present the proof has elapsed, anyone, includ
 
 ### Expired proof
 
-Proofs provided by the Data Connector are available for only 24 hours, approximately.
+Proofs provided by the Flare Data Connector are available for only 24 hours, approximately.
 If neither the redeemer, the agent, nor the executor presents the proof of payment or nonpayment within 24 hours, the regular redeeming process cannot continue, and the agent's collateral could be locked indefinitely.
 
 The procedure to recover this collateral is the same as the procedure in the minting case.
@@ -135,4 +135,4 @@ As shown in the following process, agents can self-redeem for any reason, includ
 3. The collateral that was backing those assets is released.
 4. The underlying collateral is released and can be withdrawn from the underlying address later.
 
-The self-redeemed amount is not limited to a whole number of lots and can be less than 1 lot, which makes self-closing ideal for redeeming an agent's dust.
+The self-redeemed amount is not limited to a positive integer of lots and can be less than 1 lot, which makes self-closing ideal for redeeming an agent's dust.

docs/fassets/4-collateral.mdx

@@ -35,7 +35,7 @@ If governance deprecates a type, agents must switch to a supported type.
 Each vault is associated with a single, unique address on the underlying chain called the agent's underlying address.
 It receives underlying assets when they are minted into FAssets and sends underlying assets to the redeemer's address when they are redeemed.
 
-When an agent creates a vault, the underlying address is checked for validity using the Data Connector.
+When an agent creates a vault, the underlying address is checked for validity using the Flare Data Connector.
 Otherwise, malicious agents could provide an address that systematically blocks payments and exploit the [minting process](/fassets/minting) to their advantage.
 
 ### Pool Collateral

docs/fassets/5-core-vault.mdx

@@ -22,35 +22,44 @@ import useBaseUrl from "@docusaurus/useBaseUrl";
 />
 
 The **Core Vault (CV)** is a specialized FAsset system vault that operates on the underlying network.
-It allows FAsset agents to deposit and withdraw underlying assets while optimizing capital efficiency through reduced collateral requirements.
-The CV was introduced in **FAssets v1.1** to solve key limitations of v1, such as limited minting capacity, high collateral burdens, and poor agent exit flexibility.
+It addresses a critical challenge in cross-chain systems: **protecting user funds from malicious agents while maintaining system scalability.**
 
-Only whitelisted users can withdraw from the Core Vault.
+### Why the Core Vault?
 
-The Core Vault is:
+- In **FAssets v1**, every agent had to keep the underlying asset (e.g., XRP) in their own wallet.
+- To prevent theft, agents needed to be heavily overcollateralized - they had to lock up more value than they could ever profit from stealing.
+- This worked, but it limited minting capacity and made the system capital-inefficient.
 
-- A **multisig-controlled reserve** that enhances **agent liquidity and profitability**
-- Integrated into the **FAssets smart contract system** on Flare
-- Designed to operate with **manual, auditable, and time-bounded signing routines**
-- Supported by **escrow-based fund throttling** to mitigate security risk
+The **Core Vault** changes this model:
 
-FAsset users don't need to take any action to benefit from CV — it automatically integrates with FXRP and other v1 tokens.
+- Instead of holding XRP in their own wallets, **agents can transfer underlying assets into a shared, insured vault**.
+- The vault is **multisig-controlled** and governed by Flare, so agents cannot unilaterally take the funds.
+- Because theft is structurally prevented, agents no longer need extreme levels of overcollateralization.
+
+The Core Vault prevents agents from running away with XRP while simultaneously lowering collateral requirements and improving system scalability.
+
+### Key Properties
+
+- **Secure by design**: Agents cannot withdraw underlying assets directly.
+- **Capital efficient**: Agents can mint more FAssets with less collateral.
+- **System-wide liquidity**: Assets in the CV form a shared pool available to all agents.
+- **Governance oversight**: Multisig with pause controls and time-bounded fund release.
+
+Introduced in **FAssets v1.1**, the Core Vault enables the system to expand its minting capacity while maintaining the same strong guarantees of safety for users.
 
 ## Key Features
 
 ### Transfer Capacity
 
-A system parameter defines the minimum percentage of minting capacity (based on collateral) that must remain on an agent's address after transferring assets to the CV.  
-This ensures redemption liquidity and protects the system from agent insolvency.
+To ensure redemption liquidity, a parameter enforces that after transferring assets to the Core Vault, **an agent must still maintain a minimum portion of minting capacity outside the CV**.
+This prevents agents from moving everything into the vault and leaving the system unbalanced.
 
 ### Security Design
 
-Each asset type has a dedicated Core Vault, which is managed by a multisig account on the underlying network under a formal agreement with Flare.
-The assets stored in the CV do not belong to any specific agent and can be requested to return to the agent's collateralized security.
-To ensure security, governance has the authority to pause deposits and withdrawals if necessary, such as in the event of a system compromise.
-
-The Core Vault operates through a predefined address on the underlying chain and is managed via a multisig setup with smart contract oversight under formal Flare contracts.
-Governance has the authority to pause operations in the event of a security issue.
+- Each supported asset (XRP, BTC, DOGE, etc.) has its **own dedicated Core Vault**.
+- Each CV is a **multisig account on the underlying chain**, operated under a formal governance agreement with Flare.
+- Funds in the CV **no longer belong to a single agent** - they are pooled, with withdrawals only allowed under system rules.
+- Governance can pause deposits or withdrawals if suspicious activity is detected.
 
 ## Core Vault Implementation
 
@@ -61,21 +70,21 @@ The Core Vault operates differently depending on the underlying network:
 **For XRP Ledger (XRP CV):**
 
 - The CV is implemented as a **multisig account** on the XRP Ledger.
-- Only the designated **multisig signers** can move XRP from the vault.
+- Only the authorized **multisig signers** can move XRP from the vault.
 - These signers are authorized by Flare governance and operate under formal agreements.
 - All outgoing transactions require multiple signatures from the authorized signers.
 
-### Agent Ownership Clarification
+### Agent Ownership vs. Core Vault Ownership
 
 There's an important distinction between agent ownership and CV ownership:
 
-### Agent Ownership (Standard FAssets)
+#### Agent Ownership (Standard FAssets)
 
 - Agents hold underlying assets in their own wallets.
 - These assets belong to the specific agent and are part of their collateral.
 - Agents have direct control over these assets.
 
-### Core Vault Ownership
+#### Core Vault Ownership
 
 - Assets transferred to the CV become part of a shared pool.
 - These assets **do not belong to any specific agent** once in the CV.
@@ -90,7 +99,7 @@ Agents are required to provide collateral in the form of:
 - **USDC/USDT (stablecoins)**
 
 When agents transfer underlying assets to the CV, they can reduce their collateral requirements while maintaining their minting capacity.
-The CV acts as a shared reserve that backs the system, allowing agents to operate more efficiently.
+The CV effectively acts as an **insurance-backed reserve** that boosts efficiency without weakening security.
 
 ## Operational Workflow
 
@@ -102,7 +111,7 @@ The CV acts as a shared reserve that backs the system, allowing agents to operat
 
 2. **Proof of Payment Submitted**
 
-   Anyone (including the agent) submits a proof of the transfer to the FAsset system.
+   Anyone (including the agent) submits the proof of the transfer to the FAsset system.
 
 3. **Verification and Redemption**
 
@@ -127,7 +136,7 @@ There is no time limit for the CV to honor the request, but governance ensures t
 #### Direct Redemption (Users)
 
 Approved users can burn FXRP and receive underlying XRP from the CV.
-This Requires KYC approval and a minimum redemption threshold.
+This requires KYC approval and a minimum redemption threshold.
 It is typically processed once per day and has a lower priority than agent return requests.
 It is helpful for large, less time-sensitive redemptions.
 
@@ -157,7 +166,7 @@ Multisig signers validate all outgoing transactions against a pre-approved rule
 
 2. **Withdrawals & Payouts**
 
-   Users request withdrawals; multisig operators validate Flare's offchain instructions and process payouts.
+   Users request withdrawals; multisig operators validate Flare's off-chain instructions and process payouts.
 
 3. **Re-escrow Excess & Maintain Reserve**
 
@@ -170,3 +179,14 @@ Three escrows are created if `remaining_funds = M + 3L`, and M stays in the wall
 The XRP Core Vault features enhanced security measures for managing daily liquidity, including escrow time-locking and a minimum reserve in multisig setups. It has an emergency pause function and "Red Alert Mode" for urgent threats.
 
 In case of a security issue, all signing is halted pending governance review. Escrow accounts may be unlocked to prevent asset loss, with governance overseeing the restoration of operations. Only one escrow can be unlocked per day, minimizing potential damage.
+
+## Summary
+
+The **Core Vault** fundamentally strengthens FAssets:
+
+- **Prevents loss of underlying assets** by removing agent control over pooled funds.
+- **Lowers collateral burdens**, improving capital efficiency.
+- **Expands minting capacity**, making the system more scalable.
+- **Adds layered security**, combining multisig, escrow, and governance controls.
+
+It is the key to making cross-chain assets on Flare both **secure** and **efficient**.