feat(docs): add new guide how to mint directly FAssets

fassko · fassko · commit 8d7266161acb · 2026-04-29T23:12:20.000+03:00
diff --git a/docs/fassets/developer-guides.mdx b/docs/fassets/developer-guides.mdx
@@ -42,6 +42,12 @@ Guides for [minting FAssets](/fassets/minting) from underlying assets.
 
 <DocCardList
   items={[
+    {
+      type: "link",
+      label: "Direct Mint FXRP",
+      href: "/fassets/developer-guides/fassets-direct-minting",
+      docId: "fassets/developer-guides/fassets-direct-minting",
+    },
     {
       type: "link",
       label: "Mint FAssets",
diff --git a/docs/fassets/developer-guides/10-fassets-agent-details.mdx b/docs/fassets/developer-guides/10-fassets-agent-details.mdx
@@ -4,7 +4,7 @@ tags: [intermediate, fassets]
 slug: fassets-agent-details
 description: Learn how to read FAssets agent details
 keywords: [fassets, flare-network]
-sidebar_position: 9
+sidebar_position: 10
 ---
 
 import CodeBlock from "@theme/CodeBlock";
diff --git a/docs/fassets/developer-guides/11-fassets-redemption-default.mdx b/docs/fassets/developer-guides/11-fassets-redemption-default.mdx
@@ -4,7 +4,7 @@ tags: [intermediate, fassets]
 slug: fassets-redemption-default
 description: Monitor and handle redemption scenarios
 keywords: [fassets, flare-network]
-sidebar_position: 10
+sidebar_position: 11
 ---
 
 import YouTubeEmbed from "@site/src/components/YouTubeEmbed";
diff --git a/docs/fassets/developer-guides/12-fassets-redemption-queue.mdx b/docs/fassets/developer-guides/12-fassets-redemption-queue.mdx
@@ -4,7 +4,7 @@ tags: [intermediate, fassets]
 slug: fassets-redemption-queue
 description: Learn how to get the redemption queue
 keywords: [fassets, flare-network]
-sidebar_position: 11
+sidebar_position: 12
 ---
 
 import CodeBlock from "@theme/CodeBlock";
diff --git a/docs/fassets/developer-guides/5-fassets-direct-minting.mdx b/docs/fassets/developer-guides/5-fassets-direct-minting.mdx
@@ -0,0 +1,88 @@
+---
+title: Direct Mint FXRP
+tags: [intermediate, fassets]
+slug: fassets-direct-minting
+description: Mint FXRP in a single XRPL payment using direct minting.
+keywords: [fassets, fxrp, direct-minting, flare-network, xrpl]
+sidebar_position: 5
+---
+
+import CodeBlock from "@theme/CodeBlock";
+import FAssetsDirectMinting from "!!raw-loader!/examples/developer-hub-javascript/fassetsDirectMinting.ts";
+
+## Overview
+
+This guide walks you through minting FAssets FXRP using [direct minting](/fassets/direct-minting): a single XRPL payment to the FXRP [Core Vault](/fassets/core-vault) with a memo that encodes the Flare-side recipient.
+An executor then finalizes the mint on Flare, and the recipient receives FXRP.
+
+The complete runnable example is available in the [flare-viem-starter](https://github.com/flare-foundation/flare-viem-starter/blob/main/src/fassets/direct-mint.ts) repository.
+
+## How it differs from standard minting
+
+Compared to the standard [collateral reservation flow](/fassets/developer-guides/fassets-mint), direct minting is a single-step XRPL payment:
+
+- No collateral reservation — the minter does not call [`reserveCollateral`](/fassets/developer-guides/fassets-mint#reserve-collateral) and there is no agent selection.
+- A single XRPL payment to the Core Vault address replaces the agent payment.
+- The recipient (and optionally the executor) is encoded in the XRPL memo or destination tag.
+- An executor calls `executeDirectMinting` on Flare to finalize and receives a flat fee.
+
+This guide demonstrates the **32-byte memo format**, where the recipient is a Flare address and any executor can finalize.
+
+## Prerequisites
+
+- [Flare smart account](/smart-accounts/overview) controlled by your XRPL wallet.
+- Testnet XRP on the XRP Ledger Testnet usage.
+  Get testnet XRP from the [XRP Testnet Faucet](https://xrpl.org/resources/dev-tools/xrp-faucets).
+
+## Direct Minting Memo
+
+The memo is a packed 32-byte [`PaymentReference`](/fassets/direct-minting#memo-field):
+
+| Bytes | Value              | Meaning                                                       |
+| :---- | :----------------- | :------------------------------------------------------------ |
+| 0-7   | `4642505266410018` | Direct minting prefix.                                        |
+| 8-11  | `00000000`         | Zero padding to fill the 32-byte memo.                        |
+| 12-31 | 20-byte recipient  | EVM address of the Flare smart account receiving FXRP tokens. |
+
+Because no executor is encoded, anyone can finalize this minting on Flare.
+For executor-restricted minting, use the 48-byte memo format described in [Memo Field](/fassets/direct-minting#memo-field).
+
+## Direct Minting Script
+
+<CodeBlock language="typescript" title="src/fassets/direct-mint.ts">
+  {FAssetsDirectMinting}
+</CodeBlock>
+
+## Code Breakdown
+
+1. Define the direct minting prefix constant `DIRECT_MINTING_PREFIX`.
+2. `buildDirectMintingMemo` concatenates the prefix, four zero bytes, and the recipient address (without the `0x` prefix, lowercased) into a 32-byte hex string ready to be passed as [`MemoData`](https://xrpl.org/docs/references/protocol/transactions/common-fields#memos-field) on the XRPL payment.
+3. `sendDirectMintPayment` builds the memo for the recipient and submits an XRPL `Payment` transaction to the [Core Vault](/fassets/core-vault) address with `memos: [{ Memo: { MemoData } }]`, returning the resulting transaction.
+4. Set the net FXRP amount to mint in XRP. Minting and executor fees are added to the net amount to form the XRPL payment amount.
+5. Connect to the XRPL Testnet using `XRPL_TESTNET_RPC_URL` and load the sender wallet from `XRPL_SEED`.
+6. Resolve the recipient — the Flare [`PersonalAccount`](/smart-accounts/reference/IPersonalAccount) for the XRPL wallet — via [`getPersonalAccountAddress`](/smart-accounts/reference/IPersonalAccount), and look up `AssetManagerFXRP` through the [Flare Contract Registry](/network/guides/flare-contracts-registry) using [`getContractAddressByName`](/network/guides/flare-contracts-registry).
+7. Read three values in parallel:
+   - `getDirectMintingPaymentAddress` — the Core Vault XRPL address that receives the payment.
+   - `getFxrpBalance` — the recipient's FXRP balance before minting.
+   - `computeDirectMintingPaymentAmountXrp` — the gross XRP amount equal to the net mint amount plus the minting fee and the executor fee, as quoted by the `AssetManagerFXRP` contract.
+8. Send the XRPL payment to the Core Vault with the recipient memo via the `sendDirectMintPayment` function.
+9. Wait for the [`DirectMintingExecuted`](/fassets/reference/IAssetManagerEvents#directmintingexecuted) event on `AssetManagerFXRP` using `waitForDirectMintingExecuted` function.
+   The event's `mintedAmountUBA`, `mintingFeeUBA`, and `executorFeeUBA` describe how the underlying payment was split.
+10. Read the final FXRP balance and log the delta.
+
+## Important Notes
+
+- **Fees are deducted from the underlying payment.** The XRP sent to the [Core Vault](/fassets/core-vault) must cover the net mint amount plus the minting fee and the executor fee.
+- **If the payment is below the minimum minting fee**, no FXRP is minted, and the entire payment is forfeited to the fee receiver.
+- **Rate limits may delay execution.** When hourly, daily, or large-minting thresholds are hit, the minting emits [`DirectMintingDelayed`](/fassets/reference/IAssetManagerEvents#directmintingdelayed) instead of [`DirectMintingExecuted`](/fassets/reference/IAssetManagerEvents#directmintingexecuted), with an `executionAllowedAt` timestamp.
+- **For repeat minters**, prefer the destination-tag flow via `IMintingTagManager` — it avoids constructing a memo per payment and lets you set a preferred executor.
+
+:::tip[What's next]
+
+To continue your FAssets development journey, you can:
+
+- Read the protocol details in [Direct Minting](/fassets/direct-minting).
+- Check current limits and fees in [Operational Parameters](/fassets/operational-parameters).
+- Continue with [Redeem FAssets](/fassets/developer-guides/fassets-redeem).
+
+:::
diff --git a/docs/fassets/developer-guides/6-fassets-mint.mdx b/docs/fassets/developer-guides/6-fassets-mint.mdx
@@ -4,7 +4,7 @@ tags: [intermediate, fassets]
 slug: fassets-mint
 description: Learn how to mint FAssets
 keywords: [fassets, flare-network]
-sidebar_position: 5
+sidebar_position: 6
 ---
 
 import CodeBlock from "@theme/CodeBlock";
diff --git a/docs/fassets/developer-guides/7-fassets-mint-executor.mdx b/docs/fassets/developer-guides/7-fassets-mint-executor.mdx
@@ -4,7 +4,7 @@ tags: [intermediate, fassets]
 slug: fassets-mint-executor
 description: Learn how to mint FAssets using the executor
 keywords: [fassets, flare-network]
-sidebar_position: 6
+sidebar_position: 7
 ---
 
 import CodeBlock from "@theme/CodeBlock";
diff --git a/docs/fassets/developer-guides/8-fassets-redeem.mdx b/docs/fassets/developer-guides/8-fassets-redeem.mdx
@@ -4,7 +4,7 @@ tags: [intermediate, fassets]
 slug: fassets-redeem
 description: Learn how to redeem FAssets
 keywords: [fassets, flare-network]
-sidebar_position: 7
+sidebar_position: 8
 ---
 
 import CodeBlock from "@theme/CodeBlock";
diff --git a/docs/fassets/developer-guides/9-fassets-swap-redeem.mdx b/docs/fassets/developer-guides/9-fassets-swap-redeem.mdx
@@ -4,7 +4,7 @@ tags: [intermediate, fassets]
 slug: fassets-swap-redeem
 description: Learn how to swap and redeem FAssets
 keywords: [fassets, flare-network]
-sidebar_position: 8
+sidebar_position: 9
 ---
 
 import CodeBlock from "@theme/CodeBlock";
diff --git a/docs/fassets/reference/IAssetManagerEvents.mdx b/docs/fassets/reference/IAssetManagerEvents.mdx
@@ -142,6 +142,24 @@ event DirectMintingExecuted(
 );
 ```
 
+### `DirectMintingDelayed`
+
+Emitted when a direct minting is throttled by rate limits and its execution is postponed.
+
+Parameters:
+
+- `transactionId`: Identifier of the direct minting transaction
+- `amount`: Amount being minted in the underlying base amount
+- `executionAllowedAt`: Earliest timestamp at which the minting can be executed
+
+```solidity
+event DirectMintingDelayed(
+    bytes32 transactionId,
+    uint256 amount,
+    uint256 executionAllowedAt
+);
+```
+
 ### `MintingPaymentDefault`
 
 Emitted when a minter fails to pay the underlying funds in time.
diff --git a/examples/developer-hub-javascript/fassetsDirectMinting.ts b/examples/developer-hub-javascript/fassetsDirectMinting.ts
@@ -0,0 +1,119 @@
+import { Client, Wallet } from "xrpl";
+import type { Address } from "viem";
+import { sendXrplPayment } from "./utils/xrpl";
+import { getPersonalAccountAddress } from "./utils/smart-accounts";
+import {
+  getContractAddressByName,
+  getDirectMintingPaymentAddress,
+} from "./utils/flare-contract-registry";
+import {
+  computeDirectMintingPaymentAmountXrp,
+  getFxrpBalance,
+  waitForDirectMintingExecuted,
+} from "./utils/fassets";
+
+// 1. Direct minting prefix
+const DIRECT_MINTING_PREFIX = "4642505266410018";
+
+// 2. Build the 32-byte direct-minting PaymentReference memo:
+//    [8-byte prefix][4-byte zero padding][20-byte recipient address]
+function buildDirectMintingMemo(recipientAddress: Address): string {
+  return (
+    DIRECT_MINTING_PREFIX + "00000000" + recipientAddress.slice(2).toLowerCase()
+  );
+}
+
+// 3. Send the XRPL payment to the Core Vault with the direct-minting memo
+async function sendDirectMintPayment({
+  coreVaultXrplAddress,
+  recipientAddress,
+  amountXrp,
+  xrplClient,
+  xrplWallet,
+}: {
+  coreVaultXrplAddress: string;
+  recipientAddress: Address;
+  amountXrp: number;
+  xrplClient: Client;
+  xrplWallet: Wallet;
+}) {
+  const memoData = buildDirectMintingMemo(recipientAddress);
+  console.log("Direct minting memo (32 bytes):", memoData, "\n");
+
+  const transaction = await sendXrplPayment({
+    destination: coreVaultXrplAddress,
+    amount: amountXrp,
+    memos: [{ Memo: { MemoData: memoData } }],
+    wallet: xrplWallet,
+    client: xrplClient,
+  });
+  console.log(
+    "Direct mint XRPL transaction hash:",
+    transaction.result.hash,
+    "\n",
+  );
+
+  return transaction;
+}
+
+async function main() {
+  // 4. Net FXRP amount to mint in XRP. Minting + executor fees are added on top
+  //    by computeDirectMintingPaymentAmountXrp to form the XRPL payment amount.
+  const fxrpMintAmount = 10;
+
+  // 5. Connect to the XRPL Testnet and load the sender wallet from XRPL_SEED.
+  const xrplClient = new Client(process.env.XRPL_TESTNET_RPC_URL!);
+  const xrplWallet = Wallet.fromSeed(process.env.XRPL_SEED!);
+
+  // 6. Resolve the Flare smart-account recipient and the AssetManagerFXRP address.
+  const [personalAccountAddress, assetManagerAddress] = await Promise.all([
+    getPersonalAccountAddress(xrplWallet.address),
+    getContractAddressByName("AssetManagerFXRP"),
+  ]);
+  console.log("Personal account address:", personalAccountAddress, "\n");
+
+  // 7. Read the Core Vault XRPL payment address, the recipient's initial FXRP
+  //    balance, and the gross XRP amount (net mint + minting fee + executor fee).
+  const [coreVaultXrplAddress, initialBalance, paymentAmountXrp] =
+    await Promise.all([
+      getDirectMintingPaymentAddress(assetManagerAddress),
+      getFxrpBalance(personalAccountAddress),
+      computeDirectMintingPaymentAmountXrp({ netMintAmountXrp: fxrpMintAmount }),
+    ]);
+  console.log("Core Vault XRPL address:", coreVaultXrplAddress, "\n");
+  console.log("AssetManagerFXRP address:", assetManagerAddress, "\n");
+  console.log("Initial FXRP balance:", initialBalance, "\n");
+  console.log("Payment amount (XRP, net mint + fees):", paymentAmountXrp, "\n");
+
+  // 8. Send the XRPL payment that triggers direct minting on Flare.
+  await sendDirectMintPayment({
+    coreVaultXrplAddress,
+    recipientAddress: personalAccountAddress,
+    amountXrp: paymentAmountXrp,
+    xrplClient,
+    xrplWallet,
+  });
+
+  // 9. Wait for the DirectMintingExecuted event from AssetManagerFXRP.
+  const mintEvent = await waitForDirectMintingExecuted({
+    assetManagerAddress,
+    targetAddress: personalAccountAddress,
+  });
+
+  console.log("DirectMintingExecuted event:", mintEvent, "\n");
+  console.log("Minted amount (UBA):", mintEvent.args.mintedAmountUBA, "\n");
+  console.log("Minting fee (UBA):", mintEvent.args.mintingFeeUBA, "\n");
+  console.log("Executor fee (UBA):", mintEvent.args.executorFeeUBA, "\n");
+
+  // 10. Read the final FXRP balance and log the delta.
+  const finalBalance = await getFxrpBalance(personalAccountAddress);
+  console.log("Final FXRP balance:", finalBalance, "\n");
+  console.log("FXRP minted:", finalBalance - initialBalance, "\n");
+}
+
+void main()
+  .then(() => process.exit(0))
+  .catch((error) => {
+    console.error(error);
+    process.exit(1);
+  });
