feat(docs): introduce Upshift vaults documentation with deposit, redeem, and claim guides

docs/fxrp/overview.mdx

@@ -6,6 +6,7 @@ keywords: [fassets, fxrp, xrp, flare-network, firelight, vault, defi]
 
 import DocCardList from "@theme/DocCardList";
 import Firelight from "./firelight/_firelight.mdx";
+import Upshift from "./upshift/_upshift.mdx";
 
 FXRP is the [FAsset](/fassets/overview) representation of XRP on the Flare network.
 It is an [ERC-20](https://eips.ethereum.org/EIPS/eip-20) token that represents XRP bridged from the XRP Ledger (XRPL) to Flare.
@@ -123,11 +124,4 @@ FXRP is deployed as an [Omnichain Fungible Token (OFT)](/fxrp/oft) using LayerZe
 
 ## Upshift Vaults
 
-[Upshift vault](https://app.upshift.finance/pools/14/0x373D7d201C8134D4a2f7b5c63560da217e3dEA28) is part of the XRP finance stack on Flare Network.
-It inherits the transparency model of the [FAssets](/fassets/overview) system: minting and redemption are proof-backed, and vault interactions are recorded on-chain.
-
-- **Funds are on-chain:** User deposits, vault balances, withdrawal requests, and claims are executed as smart contract state changes on Flare.
-  You can verify all vault holdings on [DeBank](https://debank.com/profile/0xEDb7B1e92B8D3621b46843AD024949F10438374B) portfolio tracker.
-- **User ownership is verifiable:** A user's position is represented directly on-chain and can be queried from smart contracts.
-- **Instruction flow is auditable:** XRPL-triggered actions are executed on Flare via [Smart Accounts](/smart-accounts/overview) with [Flare Data Connector](/fdc/overview) backed verification and onchain execution.
-  You can verify all smart account activity on the [Flare Systems Explorer](https://flare-systems-explorer.flare.network/smart-accounts).
+<Upshift />

docs/fxrp/upshift/01-status.mdx

@@ -0,0 +1,108 @@
+---
+title: Get Upshift Vault Status
+tags: [intermediate, upshift, fassets]
+slug: status
+description: Learn how to get Upshift vault status
+keywords: [fassets, flare-network, fxrp, upshift, vault]
+sidebar_position: 1
+---
+
+import CodeBlock from "@theme/CodeBlock";
+import UpshiftStatus from "!!raw-loader!/examples/developer-hub-javascript/upshift-status.ts";
+
+This guide demonstrates how to retrieve information about an Upshift vault, including vault configuration, LP token info, user balances, and withdrawal epoch information.
+
+The Upshift vault is an [ERC-4626](https://eips.ethereum.org/EIPS/eip-4626) style tokenized vault compatible with [FAssets](/fassets/overview).
+
+## Prerequisites
+
+- [Flare Hardhat Starter Kit](/network/guides/hardhat-foundry-starter-kit)
+- [Flare Network Periphery Contracts](https://www.npmjs.com/package/@flarenetwork/flare-periphery-contracts)
+- Understanding of [FAssets](/fassets/overview)
+
+## Upshift Vault Status Script
+
+The following script retrieves and displays information about the Upshift vault:
+
+<CodeBlock language="typescript" title="scripts/upshift/status.ts">
+  {UpshiftStatus}
+</CodeBlock>
+
+## Script Breakdown
+
+The `main()` function executes the following steps:
+
+1. **Initialize:** Gets the user account and logs the vault and user addresses.
+2. **Connect to vault:** Creates an instance of the Upshift vault contract.
+3. **Get reference asset info:** Retrieves the vault's reference asset (FXRP) address, symbol, and decimals.
+4. **Get LP token info:** Retrieves the vault's LP token address, which represents user shares.
+5. **Get vault configuration:** Fetches key vault parameters.
+6. **Get withdrawal epoch info:** Retrieves the current withdrawal epoch (year, month, day) and claimable epoch.
+7. **Get user balances:** Shows the user's reference asset balance and LP token balance.
+8. **Check allowances:** Displays the user's token allowances to the vault for both the reference asset and LP token.
+
+## Running the Script
+
+To run the Upshift vault status script:
+
+1. Ensure you have the [Flare Hardhat Starter Kit](/network/guides/hardhat-foundry-starter-kit) set up.
+2. Update the `VAULT_ADDRESS` constant with the correct vault address for your network.
+3. Run the script using Hardhat:
+
+```bash
+npx hardhat run scripts/upshift/status.ts --network coston2
+```
+
+## Output
+
+The script outputs the following information about the Upshift vault:
+
+```bash
+VAULT STATUS
+
+Vault Address: 0x24c1a47cD5e8473b64EAB2a94515a196E10C7C81
+User Address: 0x0d09ff7630588E05E2449aBD3dDD1D8d146bc5c2
+
+Reference Asset
+Address: 0x0b6A3645c240605887a5532109323A3E12273dc7
+Symbol: FTestXRP
+Decimals: 6
+
+LP Token
+Address: 0x1234567890abcdef1234567890abcdef12345678
+
+Vault Configuration
+Withdrawals Paused: false
+Lag Duration: 86400 seconds
+Withdrawal Fee: 0.5%
+Instant Redemption Fee: 1.0%
+Max Withdrawal Amount: 1000000.0 FTestXRP
+
+Withdrawal Epoch
+Year: 2025, Month: 1, Day: 15
+Claimable Epoch: 14
+
+User Balances
+FTestXRP Balance: 100.0
+LP Token Balance: 95.5
+
+Allowances
+FTestXRP Allowance to Vault: 0.0
+LP Token Allowance to Vault: 0.0
+```
+
+## Summary
+
+In this guide, you learned how to retrieve status information from an Upshift vault, including vault configuration, LP token details, user balances, and withdrawal epoch information.
+
+:::tip[What's next]
+
+To continue your Upshift development journey, you can:
+
+- Learn more about [FAssets](/fassets/overview) and how the system works.
+- Learn how to [deposit assets into an Upshift vault](/fxrp/upshift/deposit).
+- Learn how to [instantly redeem from an Upshift vault](/fxrp/upshift/instant-redeem) for immediate liquidity.
+- Learn how to [request a redemption from an Upshift vault](/fxrp/upshift/request-redeem) for delayed liquidity.
+- Learn how to [claim assets from an Upshift vault](/fxrp/upshift/claim) after your requested redemption is claimable.
+
+:::

docs/fxrp/upshift/02-deposit.mdx

@@ -0,0 +1,106 @@
+---
+title: Deposit Assets into Upshift Vault
+tags: [intermediate, upshift, fassets]
+slug: deposit
+description: Learn how to deposit assets into an Upshift vault
+keywords: [fassets, flare-network, fxrp, upshift, vault]
+sidebar_position: 2
+---
+
+import CodeBlock from "@theme/CodeBlock";
+import UpshiftDeposit from "!!raw-loader!/examples/developer-hub-javascript/upshift-deposit.ts";
+
+This guide demonstrates how to deposit assets into an Upshift vault.
+The Upshift vault implements an [ERC-4626](https://eips.ethereum.org/EIPS/eip-4626) style tokenized vault, allowing users to deposit assets (e.g., FXRP) and receive LP tokens (vault shares) in return.
+
+Depositing assets is the process of transferring them to the vault and receiving LP tokens that represent your proportional ownership of the vault's assets.
+
+## Prerequisites
+
+- [Flare Hardhat Starter Kit](/network/guides/hardhat-foundry-starter-kit)
+- [Flare Network Periphery Contracts](https://www.npmjs.com/package/@flarenetwork/flare-periphery-contracts)
+- Understanding of [FAssets](/fassets/overview)
+- Sufficient asset balance (e.g., FXRP) to deposit into the vault.
+
+## Upshift Vault Deposit Script
+
+The following script demonstrates how to deposit assets into the Upshift vault:
+
+<CodeBlock language="typescript" title="scripts/upshift/deposit.ts">
+  {UpshiftDeposit}
+</CodeBlock>
+
+## Script Breakdown
+
+The `main()` function executes the following steps:
+
+1. **Initialize:** Gets the user account and logs the vault and user addresses.
+2. **Connect to vault:** Creates an instance of the Upshift vault contract.
+3. **Get reference asset info:** Retrieves the vault's reference asset (FXRP) address, symbol, and decimals.
+4. **Calculate deposit amount:** Converts the desired amount into the correct units based on decimals.
+5. **Check balance:** Verifies the user has sufficient balance to cover the deposit.
+6. **Approve allowance:** Approves the vault to spend the deposit amount if needed.
+7. **Preview deposit:** Calls [`previewDeposit()`](https://docs.upshift.finance/developer-docs/vault-contract-interface#id-7.-previewdeposit-uint256-assets) to see the expected shares and amount in reference tokens.
+8. **Get LP token info:** Records the LP token balance before the deposit.
+9. **Execute deposit:** Calls [`deposit()`](https://docs.upshift.finance/developer-docs/vault-contract-interface#id-1.-deposit-uint256-assets-address-receiver) to transfer assets and mint LP tokens.
+10. **Verify deposit:** Confirms the deposit by checking the new LP token balance and shares received.
+
+## Running the Script
+
+To run the Upshift vault deposit script:
+
+1. Ensure you have the [Flare Hardhat Starter Kit](/network/guides/hardhat-foundry-starter-kit) set up.
+2. Update the `VAULT_ADDRESS` constant with the correct vault address for your network.
+3. Adjust the `DEPOSIT_AMOUNT` constant to the desired number of tokens.
+4. Ensure your account has sufficient asset balance (e.g., FXRP) to cover the deposit.
+5. Run the script using Hardhat:
+
+```bash
+npx hardhat run scripts/upshift/deposit.ts --network coston2
+```
+
+## Output
+
+The script outputs the following information about the deposit:
+
+```bash
+DEPOSIT TO VAULT
+
+Vault Address: 0x24c1a47cD5e8473b64EAB2a94515a196E10C7C81
+User Address: 0x0d09ff7630588E05E2449aBD3dDD1D8d146bc5c2
+
+Reference Asset (asset depositing): 0x0b6A3645c240605887a5532109323A3E12273dc7
+
+Deposit Amount: 1 FTestXRP (1000000)
+Balance: 100.0 FTestXRP
+Current Allowance: 0.0 FTestXRP
+
+Approving vault to spend 1 FTestXRP tokens
+Approval Tx: 0x87a36c1009575719fd3adb9a1bb2e3062a601bf910fc7fac3248da71891c39a4
+
+Expected Shares: 0.99
+Amount in Reference Tokens: 1.0
+LP Balance Before: 0.0
+
+Deposit: (tx: 0x446b7a171859d676677fc870cff81c7e8c0d618fc3588e60665792da86b94c50 , block: 12345678 )
+
+Verifying deposit...
+LP Balance After: 0.99
+Shares Received: 0.99
+```
+
+## Summary
+
+In this guide, you learned how to deposit assets into an Upshift vault by specifying the amount of assets to deposit and receiving LP tokens in return.
+
+:::tip[What's next]
+
+To continue your Upshift development journey, you can:
+
+- Learn more about [FAssets](/fassets/overview) and how the system works.
+- Learn how to [get Upshift vault status](/fxrp/upshift/status) to monitor your position.
+- Learn how to [instantly redeem from an Upshift vault](/fxrp/upshift/instant-redeem) for immediate liquidity.
+- Learn how to [request a redemption from an Upshift vault](/fxrp/upshift/request-redeem) for delayed liquidity.
+- Learn how to [claim assets from an Upshift vault](/fxrp/upshift/claim) after your requested redemption is claimable.
+
+:::

docs/fxrp/upshift/03-instant-redeem.mdx

@@ -0,0 +1,113 @@
+---
+title: Instant Redeem from Upshift Vault
+tags: [intermediate, upshift, fassets]
+slug: instant-redeem
+description: Learn how to instantly redeem LP tokens from an Upshift vault
+keywords: [fassets, flare-network, fxrp, upshift, vault, redeem]
+sidebar_position: 3
+---
+
+import CodeBlock from "@theme/CodeBlock";
+import UpshiftInstantRedeem from "!!raw-loader!/examples/developer-hub-javascript/upshift-instant-redeem.ts";
+
+This guide demonstrates how to perform an instant redemption from an Upshift vault.
+The Upshift vault implements an [ERC-4626](https://eips.ethereum.org/EIPS/eip-4626) style tokenized vault that supports instant redemptions for immediate liquidity when available.
+
+Instant redemption burns your LP tokens (vault shares) and immediately returns the underlying assets to your wallet, subject to an instant redemption fee.
+
+## Prerequisites
+
+- [Flare Hardhat Starter Kit](/network/guides/hardhat-foundry-starter-kit)
+- [Flare Network Periphery Contracts](https://www.npmjs.com/package/@flarenetwork/flare-periphery-contracts)
+- Understanding of [FAssets](/fassets/overview)
+- LP tokens (vault shares) in the Upshift vault to redeem.
+
+## Upshift Vault Instant Redeem Script
+
+The following script demonstrates how to perform an instant redemption from the Upshift vault:
+
+<CodeBlock language="typescript" title="scripts/upshift/instantRedeem.ts">
+  {UpshiftInstantRedeem}
+</CodeBlock>
+
+## Script Breakdown
+
+The `main()` function executes the following steps:
+
+1. **Initialize:** Gets the user account and logs the vault and user addresses.
+2. **Connect to vault:** Creates an instance of the Upshift vault contract.
+3. **Get reference asset info:** Retrieves the vault's reference asset (FXRP) address, symbol, and decimals.
+4. **Get LP token info:** Retrieves the LP token address and the user's current LP balance.
+5. **Validate balance:** Converts the shares amount and checks if the user has sufficient LP tokens.
+6. **Preview redemption:** Calls [`previewRedemption()`](https://docs.upshift.finance/developer-docs/vault-contract-interface#id-8.-previewredeem-uint256-shares) to see the expected assets before and after the instant redemption fee.
+7. **Get asset balance:** Records the user's asset balance before redemption.
+8. **Execute instant redemption:** Calls [`instantRedeem()`](https://docs.upshift.finance/developer-docs/vault-contract-interface#id-4.-instantredeem-uint256-shares-address-receiveraddr-address-holderaddr) to burn LP tokens and receive assets immediately.
+9. **Verify redemption:** Confirms the redemption by checking the updated LP and asset balances.
+
+## Understanding Instant Redemption
+
+The Upshift vault supports two types of redemptions:
+
+- **Instant Redemption**: Immediately burns LP tokens and returns assets, but incurs an instant redemption fee.
+- **Requested Redemption**: Creates a withdrawal request that is processed after a lag period, with a lower fee.
+
+The instant redemption fee compensates the vault for providing immediate liquidity.
+The [`previewRedemption()`](https://docs.upshift.finance/developer-docs/vault-contract-interface#id-8.-previewredeem-uint256-shares) function shows both the gross and net amounts you'll receive.
+
+## Running the Script
+
+To run the Upshift vault instant redeem script:
+
+1. Ensure you have the [Flare Hardhat Starter Kit](/network/guides/hardhat-foundry-starter-kit) set up.
+2. Update the `VAULT_ADDRESS` constant with the correct vault address for your network.
+3. Adjust the `SHARES_TO_REDEEM` constant to the desired number of shares.
+4. Ensure your account has sufficient LP tokens (vault shares) to cover the redemption.
+5. Run the script using Hardhat:
+
+```bash
+npx hardhat run scripts/upshift/instantRedeem.ts --network coston2
+```
+
+## Output
+
+The script outputs the following information about the instant redemption:
+
+```bash
+INSTANT REDEEM FROM VAULT
+
+Vault Address: 0x24c1a47cD5e8473b64EAB2a94515a196E10C7C81
+User Address: 0x0d09ff7630588E05E2449aBD3dDD1D8d146bc5c2
+Reference Asset (asset receiving): 0x0b6A3645c240605887a5532109323A3E12273dc7
+
+LP Balance: 10.0
+Shares to Redeem: 1 (1000000)
+
+Instant Redemption Fee: 1.0%
+Expected Assets (before fee): 1.0 FTestXRP
+Expected Assets (after fee): 0.99 FTestXRP
+
+Asset Balance Before: 50.0 FTestXRP
+
+Instant Redeem: (tx: 0x3f1bd8c766852d3b835bcde79f6d8e20afeeb227d737e0ed28d057dc0e6b2ba9 , block: 12345678 )
+
+Verifying redemption...
+LP Balance After: 9.0
+Shares Redeemed: 1.0
+Assets Received: 0.99 FTestXRP
+```
+
+## Summary
+
+In this guide, you learned how to perform an instant redemption from an Upshift vault by specifying the number of LP tokens (shares) to redeem.
+The instant redemption provides immediate liquidity but incurs a fee.
+
+:::tip[What's next]
+
+To continue your Upshift development journey, you can:
+
+- Learn more about [FAssets](/fassets/overview) and how the system works.
+- Learn how to [deposit assets into an Upshift vault](/fxrp/upshift/deposit).
+- Learn how to [request a redemption from an Upshift vault](/fxrp/upshift/request-redeem) for delayed liquidity.
+- Learn how to [claim assets from an Upshift vault](/fxrp/upshift/claim) after your requested redemption is claimable.
+
+:::