> For the complete documentation index, see [llms.txt](https://docs.rome.builders/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.rome.builders/ar/adlh-almtw-ryn/dual-lane-app.md).

# بناء تطبيق ثنائي المسار

شرح خطوة بخطوة لتطبيق ثنائي المسار — عقد Solidity واحد يستخدمه كلٌّ من مستخدم MetaMask ومستخدم محفظة Solana، مع توضيح ما يحدث بالضبط في كل خطوة.

تطبيق **تطبيق ثنائي المسار** هو عقد Solidity واحد يستخدمه كلٌّ من **MetaMask (EVM)** مستخدم و **Solana** يستخدمه المستخدم مباشرة — نفس العقد، نفس الحالة، وكلٌّ منهما بالمحفظة التي يملكها بالفعل. تشرح هذه الصفحة *بالضبط* ما يحدث في كل خطوة، على كل جانب.

المثال عبارة عن **خزنة**: أنت `إيداع` USDC ثم لاحقًا `withdraw` تودِعه. «stake / unstake»، و«supply / redeem»، و«tip / claim» كلها بنفس البنية.

## ما تكتبه — خزنة ERC-20 قياسية

على Rome، يظهر USDC الخاص بمستخدم Solana على جانب EVM على أنه **رمز ERC-20** — غلاف SPL لذلك الـ mint (مثلًا `wUSDC`). لذا فالعقد لديك خزنة رموز عادية: تسحب الرموز باستخدام `transferFrom` وتعيدها باستخدام `transfer`. لا شيء خاص بـ Rome:

```solidity
interface IERC20 {
    function transfer(address to, uint256 amount) external returns (bool);
    function transferFrom(address from, address to, uint256 amount) external returns (bool);
}

contract Vault {
    IERC20 public immutable token;                 // غلاف wUSDC
    mapping(address => uint256) public balanceOf;
    constructor(IERC20 _token) { token = _token; }

    function deposit(uint256 amount) external {
        require(token.transferFrom(msg.sender, address(this), amount));
        balanceOf[msg.sender] += amount;
    }
    function withdraw(uint256 amount) external {
        balanceOf[msg.sender] -= amount;
        require(token.transfer(msg.sender, amount));
    }
}
```

> **لماذا ERC-20 وليس `قابل للدفع` / `msg.value`?** الرصيد القابل للإنفاق لمستخدم Solana هو **حساب SPL للرمز في محفظته**، ويظهر 1:1 على هيئة غلاف ERC-20 هذا — *ليس* رصيد EVM الأصلي. لذا يستطيع مستخدم Solana دائمًا تمويل `transferFrom`، `الدالة deposit() القابلة للدفع` ستحتاج إلى قيمة أصلية لا يحتفظون بها خاملة. ابنِ حول الرمز، وسيعمل المساران بالطريقة نفسها.

انشره باستخدام Foundry أو Hardhat، ووجّه الباني إلى عنوان الغلاف الخاص برمزك (من [السجل](https://github.com/rome-protocol/rome-registry)). على Rome، رمز الغاز هو USDC، لذا تحتاج إلى رصيد USDC صغير للغاز كي تنشر.

## المساران

| المسار     | المحفظة                                  | كيف يستدعيه التطبيق                                                           |
| ---------- | ---------------------------------------- | ----------------------------------------------------------------------------- |
| **EVM**    | MetaMask (مفتاح EVM)                     | `submitRomeTx` — كتابة Rome القياسية                                          |
| **Solana** | محفظة Solana مثل Solflare (مفتاح Solana) | `submitRomeTxV1` — معاملة Solana v1 واحدة لكل استدعاء، ولا حاجة إلى مفتاح EVM |

مسار EVM عادي. أما بقية هذه الصفحة فهي **مسار Solana** — النصف المثير للاهتمام.

## الفكرة الأساسية: الـ synthetic مجرد ممرّ تمريري

هوية EVM لمستخدم Solana هي **العنوان الاصطناعي** — `keccak256(solana_pubkey)[12:]`. إنه `msg.sender` في العقد، لكنه **لا يحتفظ بأي شيء وهو خامد.** أموال المستخدم موجودة في **Solana** (بوصفها SPL USDC)، وعلى جانب EVM فإن الرصيد نفسه هو ما `wUSDC.balanceOf(synthetic)` تقرأه. تتدفق القيمة *عبر* عبر الـ synthetic:

* **للداخل** (الإيداع): حساب الرمز في المحفظة → حساب الرمز الخاص بـ synthetic → العقد (عبر `transferFrom`).
* **للخارج** (السحب): العقد → حساب الرمز الخاص بـ synthetic → حساب الرمز في المحفظة.

يعود رصيد الـ synthetic إلى الصفر بعد كل ذهاب وإياب.

## مرة واحدة: التفعيل (تجهيز الـ synthetic)

لا يوجد حساب on-chain لـ synthetic جديد حتى تنشئه. في المرة الأولى التي يتصرف فيها مستخدم Solana، يكون الـ synthetic الخاص به **مُجهَّزًا** مع `create_pda` استدعاء — وبعد ذلك يمكن توقيع استدعاءات نقل القيمة (استدعاء ERC-20 `transferFrom`، والـ sweep) من قبله.

`submitRomeTxV1` لا يقوم بذلك نيابةً عنك، لذا جهّزه صراحةً، مرة واحدة، قبل أول استدعاء ينقل قيمة. مكان جيد لذلك هو خطوة «Activate»، أو مباشرة قبل أول approve:

```javascript
import { submitRomeTxV1, isSyntheticProvisioned, buildCreatePdaCall, syntheticAddress } from "@rome-protocol/sdk";

const synthetic = syntheticAddress(wallet.publicKey);
const deps = { connection, proxyUrl, chainId, programId, signer }; // signer: زوج مفاتيح في السكربتات، أو LaneSigner في تطبيق محفظة
if (!(await isSyntheticProvisioned(connection, programId, synthetic))) {
  await submitRomeTxV1(deps, buildCreatePdaCall(synthetic)); // إنشاء create_pda واحد
}
```

## مرة واحدة: امنح الغلاف

يحرّك غلاف wUSDC رموز المستخدم بوصفه **مفوَّض SPL** مفوَّضًا على حساب الرمز الخاص به، لذا يجب على كل مستخدم أن يمنحه هذا الحق مرة واحدة لكل غلاف، قبل أول إيداع. ينطبق هذا على مستخدم MetaMask وعلى عنوان synthetic لمستخدم Solana على حد سواء. من دون هذا التفويض، فإن كل `transferFrom` عملية خروج من المحفظة تفشل ويُلغى الإيداع بخطأ SPL `0x4` (عدم تطابق المالك).

تحقق عبر دالة العرض في الغلاف `isEnabled(user)`. إذا أعادت `false`، فأرسل `approve_spl(wrapper, 2^64-1, mint)` مباشرةً إلى Helper precompile عند `0xff00000000000000000000000000000000000009`; الـ mint هو `mint_id()` على الغلاف. على مسار EVM ذلك يكون `submitRomeTx` استدعاءً، وعلى مسار Solana يكون `submitRomeTxV1` استدعاء:

```javascript
import { submitRomeTx, submitRomeTxV1, syntheticAddress } from "@rome-protocol/sdk";
import { createPublicClient, encodeFunctionData, http, parseAbi } from "viem";

const HELPER = "0xff00000000000000000000000000000000000009";
const wrapperAbi = parseAbi(["function isEnabled(address user) view returns (bool)", "function mint_id() view returns (bytes32)"]);
const grantAbi = parseAbi(["function approve_spl(address spender, uint64 amount, bytes32 mint)"]);

// عميل viem على RPC الخاص بالسلسلة

// من: عنوان MetaMask، أو syntheticAddress(wallet.publicKey) لمستخدم Solana
// يبقى null عندما تكون isEnabled true
if (!(await publicClient.readContract({ address: wUSDC, abi: wrapperAbi, functionName: "isEnabled", args: [who] }))) {
  const mint = await publicClient.readContract({ address: wUSDC, abi: wrapperAbi, functionName: "mint_id" });
  grant = { to: HELPER, data: encodeFunctionData({ abi: grantAbi, functionName: "approve_spl", args: [wUSDC, 2n ** 64n - 1n, mint] }) };
}
// مسار EVM: إذا وُجد grant فاستدعِ submitRomeTx(provider, { from: who, ...grant });
// مسار Solana: إذا وُجد grant فاستدعِ submitRomeTxV1(deps, grant);
```

## ما يحتاجه كل جانب

|                           | يحتاج                                                              | لماذا                                                                                                  |
| ------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------ |
| **مستخدم Solana**         | **SOL** (قليلًا)                                                   | يدفع رسوم معاملة Solana في كل معاملة على أيٍّ من المسارين                                              |
|                           | **USDC كرمز SPL** في محفظته                                        | القيمة التي يودعها (وتظهر على جانب EVM على أنها `wUSDC`)                                               |
| **مستخدم EVM (MetaMask)** | **USDC** كرصيدهم من غاز Rome                                       | غاز، والقيمة التي يودعونها بعد تغليفها؛ ويزيدونها عبر **جسر USDC** إلى Rome (لا يوجد faucet)           |
|                           | عملية **تغليف** جزء من ذلك الغاز إلى **wUSDC** (`withdraw_to_ata`) | تأخذ الخزنة wUSDC، وهو غلاف ERC-20، وليس الغاز الأصلي. رصيد MetaMask من USDC الغاز ليس wUSDC حتى يُغلف |
|                           | التفويض **الخاص بالغلاف لمرة واحدة** (`approve_spl`)               | يسمح لغلاف wUSDC بتحريك رموزهم؛ انظر [مرة واحدة: امنح الغلاف](#one-time-grant-the-wrapper)             |
| **أنت (المطوّر)**         | محفظة تحتوي على **USDC** غاز على Rome                              | لنشر العقد                                                                                             |

## القيمة الداخلة — الإيداع (خطوة بخطوة)

لدى مستخدم Solana كلٌّ من SOL وUSDC في محفظة Solana الخاصة به. كل خطوة هي معاملة Solana v1، **موقَّعة من تلك المحفظة**، ويرسلها التطبيق إلى Solana RPC. يُبنى مسار التمويل في التطبيق وتوقّعه المحفظة بمطالبة واحدة؛ بينما يكوّن الوكيل كل استدعاء للعقد، وتوقّعه المحفظة بعد رسالة تفويض قابلة للقراءة:

1. **مسار التمويل** — `buildFundLeg(...)` → `submitSolanaInstructionsV1(...)`. ينشئ حساب USDC الرمزي الخاص بـ synthetic (إذا لزم) ويشغّل **`ActivateAta`**، ناقلًا `المبلغ` من USDC من حساب الرمز في المحفظة **إلى**. الآن `wUSDC.balanceOf(synthetic)` ويعرض ذلك الرصيد.
2. **امنح الغلاف** (عندما `isEnabled` تكون false) — `submitRomeTxV1(deps, { to: HELPER, data: approve_spl(wUSDC, 2^64-1, mint) })`. انظر [مرة واحدة: امنح الغلاف](#one-time-grant-the-wrapper). *(جهّز الـ synthetic قبل هذا إذا كان هذا أول استدعاء للمسار لدى المستخدم.)*
3. **اعتمد** — `submitRomeTxV1(deps, { to: wUSDC, data: approve(vault, amount) })`. يتيح للخزنة سحب الرموز.
4. **إيداع** — `submitRomeTxV1(deps, { to: vault, data: deposit(amount) })`. تشغّل الخزنة `transferFrom(synthetic, vault, amount)` — ينتقل USDC من الـ synthetic إلى الخزنة، ويُسجَّل في رصيد عنوان الـ synthetic.

**الأثر الصافي:** انتقل USDC من **محفظة Solana → (synthetic) → الخزنة.**

```javascript
import { syntheticAddress, buildFundLeg, submitSolanaInstructionsV1, submitRomeTxV1 } from "@rome-protocol/sdk";
import { encodeFunctionData, erc20Abi } from "viem";

const synthetic = syntheticAddress(wallet.publicKey);
const deps = { connection, proxyUrl, chainId, programId, signer }; // signer: LaneSigner (payer, signAuthHash, signV1Wire) أو Keypair

// 1) مسار التمويل — USDC من المحفظة → حساب الرمز الخاص بـ synthetic (توقّع المحفظة)
await submitSolanaInstructionsV1(
  buildFundLeg({ programId, chainId, mint: usdcMint, amount: depositAmount, wallet: wallet.publicKey, synthetic }),
  { connection, signer },
);

// 2) امنح الغلاف، مرة واحدة (الـ synthetic مُجهَّز بالفعل)؛ `grant` هو الاستدعاء المُنشأ تحت «مرة واحدة: امنح الغلاف»، أو null عندما تكون isEnabled true
if (grant) await submitRomeTxV1(deps, grant);

// 3) اعتمد الخزنة
await submitRomeTxV1(deps, { to: wUSDC, data: encodeFunctionData({ abi: erc20Abi, functionName: "approve", args: [vault, depositAmount] }) });

// 4) الإيداع — تسحب الخزنة عبر transferFrom
await submitRomeTxV1(deps, { to: vault, data: encodeFunctionData({ abi, functionName: "deposit", args: [depositAmount] }) });
```

## القيمة الخارجة — السحب (خطوة بخطوة)

الآن يسحب المستخدم. أيضًا بتوقيع المحفظة، ومطالبتان لكل استدعاء:

1. **السحب** — `submitRomeTxV1(deps, { to: vault, data: withdraw(amount) })`. `vault.withdraw` تشغّل `transfer(synthetic, amount)` — ينتقل USDC من الخزنة عائدًا إلى **الخاص بـ synthetic** حساب الرمز.
2. **مسار التحويل النهائي** — `buildSweepLeg(...)` يمنحك `HelperProgram.transfer_spl` الاستدعاء + الحسابات؛ شغّله (أنشئ حساب الرمز في المحفظة إذا لزم باستخدام `submitSolanaInstructionsV1`، ثم أرسل استدعاء Helper عبر `submitRomeTxV1`؛ يعثر الوكيل على حسابات الرموز) لنقل USDC من الـ synthetic **إلى محفظة Solana الخاصة بالمستخدم**. يعود رصيد الـ synthetic إلى الصفر.

**الأثر الصافي:** انتقل USDC من **الخزنة → (synthetic) → محفظة Solana الخاصة بالمستخدم.** لا شيء يعلق.

```javascript
import { buildSweepLeg } from "@rome-protocol/sdk";

// 1) السحب — تعيد الخزنة USDC إلى حساب الرمز الخاص بـ synthetic
await submitRomeTxV1(deps, { to: vault, data: encodeFunctionData({ abi, functionName: "withdraw", args: [amount] }) });

// 2) مسار التحويل النهائي — حساب رمز synthetic → حساب الرمز في محفظة المستخدم الخاصة
const sweep = buildSweepLeg({ programId, mint: usdcMint, amount, wallet: wallet.publicKey, synthetic });
await submitSolanaInstructionsV1([sweep.ensureWalletAtaIx], { connection, signer });
await submitRomeTxV1(deps, { to: sweep.helperTo, data: sweep.calldata });
```

## مقاس على Hadrian

كل خطوة على مسار Solana أدناه نُفِّذت كمعاملة version-1 واحدة على Hadrian:

| الخطوة                           | وحدات الحوسبة | بايت  | الحسابات |
| -------------------------------- | ------------- | ----- | -------- |
| التجهيز (`create_pda`)           | 39,008        | 703   | 9        |
| منح الغلاف (`approve_spl`)       | 50,687        | 899   | 13       |
| اعتمد                            | 79,335        | 769   | 10       |
| إيداع الخزنة                     | 242,880       | 1,070 | 20       |
| سحب الخزنة                       | 280,903       | 1,037 | 19       |
| التحويل النهائي (`transfer_spl`) | 46,810        | 899   | 13       |

## الأخطاء الشائعة

هذه هي الأشياء التي تخطئ فيها معاملة Solana على المسار المصنوعة يدويًا. يتولى SDK ومركّب الوكيل معظمها:

* **التجهيز.** يجب إنشاء حساب synthetic جديد (`create_pda`) `submitRomeTxV1` لا يقوم بذلك نيابةً عنك: تحقّق من `isSyntheticProvisioned` وأرسِل `buildCreatePdaCall(synthetic)` مرة واحدة.
* **امنح الغلاف مرة واحدة.** يحرّك الغلاف الرموز بوصفه المفوَّض SPL للمستخدم. تحقّق من `isEnabled` وأرسل `approve_spl` إلى Helper precompile قبل أول إيداع، وإلا فسيُلغى الإيداع بخطأ SPL `0x4`.
* **أنفق الغلاف، لا `msg.value`.** رصيد مستخدم Solana هو حساب الرمز SPL الخاص به، ويُعرض على هيئة غلاف ERC-20 — حرّكه باستخدام `transfer` / `transferFrom`، وليس القيمة الأصلية أبدًا.
* **مُركَّب من أجلك.** يتولى مركّب الوكيل ComputeBudget، ومحفظة الكنز، واكتشاف الحسابات، لذا لا يظهر أيٌّ منها في كودك. قبل أن توقّع المحفظة، يتحقق SDK من المعاملة المركبة ويرفض أي شيء غير الاستدعاء الذي فوّضه المستخدم.
* **إلى أين يُرسل.** توقّع المحفظة معاملة v1 و **يرسله التطبيق إلى Solana RPC** — وليس إلى الوكيل، الذي يركّبها (الاستدعاء المرحَّل هو الاستثناء الوحيد، أدناه؛ انظر [الاستدعاءات المُرحَّلة والاستدعاءات الطويلة](https://docs.rome.builders/ar/adlh-almtw-ryn/call-evm-from-solana.md#relayed-calls-and-long-calls)). على السلسلة، يستخرج البرنامج `msg.sender` من موقِّع Solana.
* **مطالبتان لكل استدعاء.** توقّع المحفظة رسالة تفويض قابلة للقراءة (`تفويض Rome` وهاش معاملة EVM)، ثم المعاملة نفسها، وكلتاهما بالمفتاح نفسه.
* **تحقّق من أن محفظتك توقّع v1.** `signV1Wire` يجب أن تعيد التوقيع المكوّن من 64 بايت على رسالة v1؛ وعبر Wallet Standard يكون ذلك `solana:signTransaction` على السلك الخام و `signedTransaction.slice(-64)`. ليست كل المحافظ تفك ترميز معاملات v1 بعد، لذا اختبر محفظتك قبل أن تبني عليها. على devnet اليوم، يوقّع Solflare عليها؛ أما Phantom فلا يفعل ذلك بعد.
* **الاستدعاءات الكبيرة تُرحَّل.** الاستدعاء الذي لا يتسع في معاملة واحدة يرحّله الوكيل بالتوقيع التفويضي نفسه، وتكون النتيجة `route: "relay"`. يُدفع الاستدعاء المرحَّل بعملة الغاز الأصلية للسلسلة، لذا زد الـ synthetic بـ `fundSyntheticGas(deps, amountWei)`. انظر [الاستدعاءات المُرحَّلة والاستدعاءات الطويلة](https://docs.rome.builders/ar/adlh-almtw-ryn/call-evm-from-solana.md#relayed-calls-and-long-calls).
* **الغاز هو USDC.** لا يوجد faucet — جسّر USDC إلى الداخل (انظر [الحصول على تمويل](https://docs.rome.builders/ar/almward/faucets.md)).

السابق `submitRomeTxSolanaLane` لا يزال موجودًا في SDK: فهو يبني معاملة Solana قديمة في العميل (مطالبة محفظة واحدة، مع معالجة ComputeBudget ومحفظة الكنز بواسطة SDK).

## التطبيق نفسه من MetaMask

يستدعي مستخدم EVM العقد نفسه باستخدام `submitRomeTx` — أدوات EVM قياسية، والغاز بـ USDC. فرق واحد عن مستخدم Solana: يحتفظ مستخدم MetaMask بـ **USDC الغاز الأصلي**، وليس wUSDC. تأخذ الخزنة غلاف wUSDC، لذا يغلّف المستخدم جزءًا من غازه أولًا، ثم يمنح الغلاف مرة واحدة، ثم ينفذ خطوات ERC-20 كالمعتاد. لا توجد مسارات تمويل أو تحويل نهائي، لأن الرموز المغلَّفة موجودة أصلًا على عنوان EVM الخاص به.

1. **غلّف الغاز إلى wUSDC** — أرسل `withdraw_to_ata(wei)` إلى Withdraw precompile عند `0x4200000000000000000000000000000000000016`. فهو يحرق تلك الكمية من الغاز الأصلي ويقيد المبلغ المكافئ في حساب الرمز الخاص بالمستخدم في رمز الغاز، والذي `يقرأ ATA الخاص بالمستخدم. لا شيء يتحرك أو يتزامن بين العرضين.` ثم يظهر. `wei` بوحدة الغاز ذات 18 منزلة عشرية ويجب أن يكون مضاعفًا لـ 10^12 (وحدة واحدة من wUSDC ذات 6 منازل عشرية)، وإلا يُلغى الاستدعاء. تخطَّ هذه الخطوة إذا كان المستخدم يملك wUSDC بالفعل.
2. **امنح الغلاف** (عندما `isEnabled` تكون false) — الاستدعاء نفسه `approve_spl` كما سبق، يُرسل مع `submitRomeTx`. انظر [مرة واحدة: امنح الغلاف](#one-time-grant-the-wrapper).
3. **اعتمد** — `approve(vault, amount)` على wUSDC.
4. **إيداع** — `deposit(amount)` على الخزنة. السحب هو `withdraw(amount)`.

```javascript
import { submitRomeTx } from "@rome-protocol/sdk";
import { encodeFunctionData, erc20Abi, parseAbi } from "viem";

const WITHDRAW = "0x4200000000000000000000000000000000000016";
const withdrawAbi = parseAbi(["function withdraw_to_ata(uint256 wei_)"]);

// 1) غلّف بعض USDC الغاز إلى wUSDC (weiAmount بوحدات الغاز ذات 18 منزلة عشرية)
await submitRomeTx(provider, { from: who, to: WITHDRAW, data: encodeFunctionData({ abi: withdrawAbi, functionName: "withdraw_to_ata", args: [weiAmount] }) });

// 2) امنح الغلاف، مرة واحدة: `grant` هو الاستدعاء المُنشأ تحت «مرة واحدة: امنح الغلاف»، أو null
if (grant) await submitRomeTx(provider, { from: who, ...grant });

// 3) اعتمد و4) أودِع، كما في أي ERC-20
await submitRomeTx(provider, { from: who, to: wUSDC, data: encodeFunctionData({ abi: erc20Abi, functionName: "approve", args: [vault, depositAmount] }) });
await submitRomeTx(provider, { from: who, to: vault, data: encodeFunctionData({ abi, functionName: "deposit", args: [depositAmount] }) });
```

كلا المستخدمين يشتركان في نفس `balanceOf` الحالة داخل الخزنة.

## ما التالي

* [استدعِ EVM من Solana](https://docs.rome.builders/ar/adlh-almtw-ryn/call-evm-from-solana.md) — آليات مسار Solana بالتفصيل
* [استدعِ Solana من EVM](https://docs.rome.builders/ar/adlh-almtw-ryn/call-solana-from-evm.md) — الاتجاه الآخر (CPI)
* [الحصول على تمويل](https://docs.rome.builders/ar/almward/faucets.md) — USDC بوصفه رمز الغاز؛ جسّره إلى الداخل


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.rome.builders/ar/adlh-almtw-ryn/dual-lane-app.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
