> 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/almfahym-alasasyh/token-interop.md).

# التشغيل البيني للرموز

كيف يكون ERC-20 وSPL token هما نفس الحساب الأساسي على Rome.

تمثل Rome رمز ERC-20 ورمز SPL الأساسي المقابل له كحساب مشترك واحد. تشرح هذه الصفحة آلية عمل الرموز عبر EVM وSolana.

## نموذج الحالة المشتركة

بالنسبة إلى المحفظة العادية، يكون رمز ERC-20 على Rome عبارة عن **غلاف شفاف** للحساب الذي يحتوي على رمز SPL على Solana. رصيد ERC-20 في المحفظة هو رصيد SPL الخاص بها. ويملك حساب الرمز عنوان مشتق من برنامج (PDA) لعنوان EVM. وهذا هو **عنوان PDA ذي السلطة الخارجية**.

<figure><img src="https://1717205515-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F671PKS8ZQSNqtoC8PGvz%2Fuploads%2Fgit-blob-552c639322c2d0e90b312def5db39d06c1871d18%2Ftoken-interop.svg?alt=media" alt="An EVM address and its Solana token account, owned by its external-authority PDA. Multiple wrappers read the same token account. The wrapper escrow account and Solana pool vaults hold tokens of the same Solana mint."><figcaption></figcaption></figure>

* لا تأخير في المزامنة: رصيد ERC-20 في المحفظة هو رصيد SPL الخاص بها.
* لا تعاني المحافظ العادية، بما فيها محافظ MetaMask والعناوين الاصطناعية، من تجزؤ السيولة. يعرض كل غلاف للسكّة نفسها رصيد المحفظة ذاته. وتقرأ الطريقة `balanceOf` ذلك الرصيد من حساب الرموز في المحفظة. أما الرموز الموجودة داخل عقود EVM فتُحتفظ بها لكل غلاف على حدة (انظر [عقد الغلاف](#the-wrapper-contract)).
* لا تُقفل رموز المحفظة في أحد الجانبين وتُسكّ في الجانب الآخر. تُحفظ الرموز الموجودة في العقود في حساب الضمان الخاص بالغلاف على Solana. ويتتبع كل غلاف هذه الرموز على حدة.

**لماذا لا يقسّم غلاف ثانٍ الرصيد**

يعرض غلافان للسكّة نفسها رصيد المحفظة ذاته. وتقرأ الأغلفة `totalSupply` من سكّة Solana. على Hadrian (شبكة الاختبار)، أعادت ثلاثة أغلفة wUSDC أرصدة متطابقة للمحافظ. وأعادت أغلفة wUSDC الثلاثة (9.0.0 و8.0.0 وإصدار مايو 2026) إجمالي المعروض في سكّة Solana.

يتيح كل مصنع غلافًا واحدًا لكل سكّة. ويمكن لإصدار جديد من المصنع نشر غلاف آخر لتلك السكّة. ويسمّي السجل الغلاف القياسي لكل سلسلة.

تمتلك محفظة Solana تحتوي على USDC مباشرةً وعنوان EVM رموزًا من السكّة نفسها. وتستخدم مجمعات Solana خزائن الاحتياطي نفسها لكليهما.

جدول الحائزين في [عبر المستكشف](https://docs.rome.builders/ar/alttbyqat-ala-rome/via.md) يُنشأ من أحداث `Transfer` الخاصة بكل غلاف. وقد يختلف عن رصيد حساب الرموز، لأن التحويلات المباشرة لـSPL و `ActivateAta`والتحويلات عبر غلاف آخر لا تظهر ضمن أحداث ذلك الغلاف.

> تستخدم مسارات الاستيراد أدناه `@rome-protocol/rome-solidity`. الحزمة غير متاحة على npm؛ ثبّتها من المستودع العام [`rome-solidity`](https://github.com/rome-protocol/rome-solidity) باستخدام `npm install github:rome-protocol/rome-solidity`أو `forge install rome-protocol/rome-solidity` مع إعداد إعادة تعيين المسارات (remapping). وتحتاج عقود الغلاف والمصنع أيضًا إلى OpenZeppelin ضمن Foundry (انظر [نشر عقود Solidity](https://docs.rome.builders/ar/adlh-almtw-ryn/deploy-solidity.md#using-the-rome-solidity-sdk)). توجد واجهات البرامج المسبقة التجميع في [`contracts/interface.sol`](https://github.com/rome-protocol/rome-solidity/blob/master/contracts/interface.sol).

## عقد الغلاف

`SPL_ERC20` (ومتغير المسار المخزّن مؤقتًا `SPL_ERC20_cached`، الذي ينشره المصنع لكل سكّة باستثناء سكّة واحدة لها خطاف تحويل مُفعّل؛ انظر [سكك Token-2022](#token-2022-mints)) واجهة ERC-20 كاملة فوق سكّة SPL:

* `balanceOf()` — يقرأ رصيد ATA للمستخدم من Solana (أما عنوان العقد فيقرأ سجل الغلاف نفسه، كما هو موضح أدناه)
* `transfer()` / `transferFrom()` — ينقل الرموز على Solana
* `approve()` / `allowance()` — أرصدة ERC-20 المصرّح بها لكل جهة إنفاق، والمحفوظة في تخزين EVM (لا يملك حساب رمز SPL أرصدةً مصرّحًا بها على نمط EVM). وهي منفصلة عن التفويض لمرة واحدة أدناه: لكي يتمكن الغلاف من نقل رموز المستخدم، يعمل بصفته المفوّض في SPL عن ذلك المستخدم، ويمنحه المستخدم هذا الحق مرة واحدة لكل محفظة
* `totalSupply()` — تقرأ إجمالي المعروض من سكّ SPL

لا يمكن للعقد منح التفويض لمرة واحدة، لذا تُحفظ رموز العقد في حساب الرموز الخاص بالغلاف وتُتابَع في سجل الغلاف. `balanceOf(contract)` تقرأ ذلك السجل.

## المصنع

`ERC20SPLFactory` ينشر غلافًا لأي سكّ SPL:

```solidity
import {ERC20SPLFactory} from "@rome-protocol/rome-solidity/contracts/erc20spl/erc20spl_factory.sol";

// نشر غلاف، مع جلب الاسم والرمز من بيانات Token-2022 الوصفية للسكّ أو من Metaplex
address wrapper = factory.add_spl_token_with_metadata(splMint);

// أو تحديد الاسم والرمز يدويًا
address wrapper = factory.add_spl_token_no_metadata(splMint, "USD Coin", "USDC");
```

عنوان المصنع النشط، من `live` مدخلات السجل (v0.2.0): Hadrian `0x37c13e4ff21fb914eb24014dcbd0f8dbeaa31078`. لا تزال المصانع الأقدم موجودة على السلسلة، لكنها موسومة بأنها `deprecated` أو `retired` في [السجل](https://github.com/rome-protocol/rome-registry/tree/main/chains)؛ لا تستخدمها. السجل هو المرجع المعتمد، لذا اقرأ العنوان النشط منه (راجع [قراءة قائمة العقود](https://docs.rome.builders/ar/almrja/contract-addresses.md#reading-the-contracts-list)) بدلًا من نسخه إلى الشيفرة.

## السكوك المعتمدة

لا يوجد عقد تسجيل للرموز على السلسلة. تُدرج الأغلفة المعتمدة ورموز الغاز والجسور في المستودع المنسّق خارج السلسلة [`rome-protocol/registry`](https://github.com/rome-protocol/rome-registry)؛ أما الأغلفة غير المقيّدة التي تُنشأ عبر `add_spl_token_no_metadata` فيُكتشف وجودها من خلال حدث `TokenCreated` . يحدد السجل الغلاف المعتمد لكل سكّ على كل سلسلة. وتتشارك المحافظ أرصدتها بين الأغلفة. ويتتبّع كل غلاف على حدة الأرصدة التي تحتفظ بها عقود EVM.

## عمليات SPL من Solidity

لعمليات SPL الأولية الموقّعة بواسطة PDA المستخدم، استخدم **برنامج المساعدة** المسبق التجميع (`0xFF…09`) — لإنشاء ATA، وتحويلات SPL، والتحويل بين الغاز واللامبورت:

```solidity
import {IHelperProgram} from "@rome-protocol/rome-solidity/contracts/interface.sol";

IHelperProgram helper = IHelperProgram(0xFF00000000000000000000000000000000000009);

helper.create_ata(user, mint);              // إنشاء ATA للمستخدم لسكٍّ معين
helper.transfer_spl(to, tokens, mint);      // تحويل رموز SPL من PDA الخاص بالمتصل
```

`transfer_spl` له عدة صيغ محمّلة (بما فيها صيغة للمفوّض ضمن تدفقات `transferFrom` )؛ راجع `interface.sol` للتواقيع الدقيقة. في المسار المخزّن مؤقتًا، توجد العمليات المكافئة على `ISplCached` (`0xFF…05`) و `IAssociatedSplCached` (`0xFF…06`). يستخدم العقد مسارًا واحدًا باستمرار.

## منح لمرة واحدة لكل محفظة

ينقل الغلاف رموز المستخدم بصفته **المفوّض في SPL** لحساب الرموز الخاص بذلك المستخدم. لذلك، يتعين على المحفظة منحه هذا الحق مرة واحدة لكل غلاف، قبل أن يتمكن الغلاف من نقل أي شيء نيابةً عنها. يتم المنح باستدعاء واحد إلى التمهيد المسبق Helper (`0xff00000000000000000000000000000000000009`):

```solidity
helper.approve_spl(wrapper, type(uint64).max, mint);   // approve_spl(wrapper, 2^64-1, mint)
```

`approve_spl` يوقّعه حساب المستخدم نفسه، لذا يرسله المستخدم، وليس الغلاف أو عقدك. والرمز المُصدِر هو `mint_id()` على الغلاف.

* **من يحتاج إليه.** كل محفظة EVM، وكل عنوان اصطناعي لمستخدم Solana، لكل غلاف تريد نقل رموزه. لا يعمل العقد الذي يسحب الرموز باستخدام `transferFrom` إلا مع المستخدمين الذين منحوا الغلاف الإذن.
* **كيفية التحقق.** استدعِ `isEnabled(user)` على الغلاف. ويُرجع `true` بعد إتمام المنح.
* **ما يحدث عند غياب المنح.** يفشل النقل ويُرجع خطأ SPL `0x4` (عدم تطابق المالك).
* **مفوّض واحد لكل حساب رموز.** لحساب رموز SPL مفوّض واحد فقط. إن منح برنامجًا آخر إذنًا على حساب الرموز نفسه، مثل جسر أو موجّه، يستبدل منح الغلاف، ويتوقف الغلاف عن العمل لهذا المستخدم إلى أن يمنحه الإذن مجددًا. تحقّق من `isEnabled` قبل النقل بدلًا من افتراض أن منحًا سابقًا لا يزال ساريًا.

عندما يحل إصدار جديد من المصنع محل غلاف، تمنح كل محفظة الغلاف الجديد الإذن باستخدام `approve_spl`. لا يستطيع الغلاف القديم نقل رموز تلك المحفظة إلا ما دام مفوّضًا لحساب الرموز. ويؤدي منح الإذن للغلاف الجديد إلى استبدال ذلك المفوّض.

يحتوي [دليل التطبيق ذي المسارين](https://docs.rome.builders/ar/adlh-almtw-ryn/dual-lane-app.md#one-time-grant-the-wrapper) على الشيفرة الكاملة لكلا المسارين.

## الإيداع والسحب

* **إلى EVM** — يضيف جانب SPL الرصيد إلى حساب ATA المملوك لـPDA الخاص بالمستخدم، ويعكس غلاف ERC-20 الرصيد فورًا. وتُسوّى التحويلات الواردة من سلاسل أخرى على السلسلة عبر تفويض يوقّعه المستخدم على الجسر.
* **تحويل الغاز إلى رمز الغاز** — استدعِ التمهيد المسبق `Withdraw` (`0x42…16`). `withdraw_to_ata(wei)` يحرق غازًا أصليًا ويضيف المبلغ المكافئ، بوحدات المنازل العشرية الخاصة برمز الغاز، إلى حساب الرموز الخاص بالمتصل، حيث يعرض غلاف رمز الغاز (مثل wUSDC) ذلك على هيئة رصيد. `withdraw_to_pda(wei)` يدفع لامبورت إلى PDA الخاص بالمتصل، ولا ينطبق إلا على سلسلة يكون رمز الغاز فيها SOL؛ وتفشل المعاملة على Hadrian وRubicon، اللتين تستخدمان USDC للغاز، لذا استخدم `withdraw_to_ata` هناك. يُعبّر عن المبلغ بوحدات الغاز ذات 18 منزلة عشرية، ويجب أن يكون عددًا صحيحًا من وحدات رمز الغاز: في السلاسل التي تستخدم USDC للغاز، يجب أن يكون من مضاعفات 10^12 (أي وحدة واحدة ذات 6 منازل عشرية)، وإلا فستفشل المعاملة. `HelperProgram.deposit_from_ata(wei)` يعمل في الاتجاه المعاكس، إذ يحوّل رمز الغاز الموجود في حساب الرموز الخاص بالمتصل إلى غاز أصلي، مع تطبيق قاعدة المضاعفات نفسها. هذه تحويلات لرمز الغاز، وليست وسيلة لسحب الرموز الأخرى.
* **الإرسال إلى Solana لرمز آخر** — فرصيد الغلاف نفسه هو بالفعل رصيد SPL، لذا فإن نقله إلى الخارج يتم عبر تحويل SPL:
  * `HelperProgram.transfer_spl_to_signer(amount, mint)` يرسل رموز المتصل إلى حساب الرموز الخاص بمحفظة Solana التي وقّعت المعاملة. لا تصل هذه الخطوة إلى محفظة المستخدم نفسه إلا عبر مسار Solana الذي وقّعته المحفظة. إذا استُدعيت من MetaMask أو عبر المُرحِّل، فالموقّع هو دافع Rome الوكيل، لذا يفشل الاستدعاء أو تُرسل الرموز إلى Rome. استخدم `transfer_spl` أو `RomeBridgeWithdraw.bridgeOutToSolana` بدلًا من ذلك.
  * `RomeBridgeWithdraw.bridgeOutToSolana(solanaRecipient, amount, mint)` يرسلها إلى أي محفظة Solana. ويتطلب منح المستخدم عقد الجسر صلاحية الإنفاق (`approve_spl(bridge, …)`، راجع الملاحظة أعلاه بشأن المفوَّض الواحد)، كما يجب أن يكون حساب الرموز الخاص بالمستلم موجودًا؛ `ensureRecipientAta(solanaRecipient, mint)` ينشئه.
  * `RomeBridgeWithdraw` يحرق أيضًا USDC لإرساله إلى سلسلة أخرى عبر CCTP (`burnUSDC`) ويرسل الأصول الأخرى عبر Wormhole (`burnETH`, `burnToWormhole`).

استخرج العنوان الفعلي لـ `RomeBridgeWithdraw` من السجل.

لنقل الرموز الأخرى بين Solana وEthereum أو سلاسل AggLayer، راجع [Solgate](https://docs.rome.builders/ar/alttbyqat-ala-rome/solgate.md) و [13. البناء على Solgate](https://docs.rome.builders/ar/akadymyh-rwma/13-build-on-solgate.md).

## رمز الغاز

لكل سلسلة رمز غاز خاص بها: SOL أو أحد رموز SPL. ويمكن أن يكون مصدر الأسعار في Rome Proxy موجزًا من واجهة Hermes API، أو مجمع Meteora DAMM v1، أو مجمع Meteora DAMM v2، أو سعرًا ثابتًا. تستخدم Hadrian (شبكة الاختبار) وRubicon (الشبكة الرئيسية) USDC. وتستخدم Hadrian عملة USDC تجريبية، بينما تستخدم Rubicon عملة USDC حقيقية. لا يوجد رمز غاز افتراضي موحّد.

## عمليات سك Token-2022

يدعم المصنع أيضًا أغلفة عمليات سك Token-2022. ويستعلم من الـ precompile المساعد عن نوع عملية السك باستخدام `mint_info(mint)` (المحدِّد `0xe24bf5d4`)، ثم يختار الغلاف بناءً على الإجابة. `mint_info` يُرجع خمس قيم:

| القيمة         | المعنى                                                                        |
| -------------- | ----------------------------------------------------------------------------- |
| `tokenProgram` | برنامج الرموز الذي يملك عملية السك (برنامج SPL Token التقليدي أو Token-2022)  |
| `decimals`     | عدد الخانات العشرية للـ mint                                                  |
| `hookProgram`  | برنامج خطاف التحويل، أو صفر عند عدم وجود خطاف أو عند وجوده دون تفعيله         |
| `feeBps`       | رسوم التحويل بنقاط الأساس، أو صفر عند عدم وجود رسوم أو عند ضبطها على صفر      |
| `extensions`   | خريطة بتّية لامتدادات Token-2022 التي يحملها الـ mint؛ البت N لنوع الامتداد N |

ما الذي يحصل عليه الـ mint:

| الـ mint                                                                      | الغلاف                                                                                     | `wrapper_kind_by_mint` |
| ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | ---------------------- |
| mint عادي، أو mint من Token-2022 بلا خطاف، أو mint موجود خطافه لكنه غير مفعّل | الغلاف المخزّن مؤقتًا (`SPL_ERC20_cached`)                                                 | `1`                    |
| mint من Token-2022 يتضمن خطاف تحويل مفعّلًا                                   | الغلاف ذو الخطاف (`SPL_ERC20_Token2022Hooked`)، الذي يُنشر عبر `hooked_wrapper_deployer()` | `2`                    |

يحصل الـ mint الذي يفرض رسوم تحويل على الغلاف المخزّن مؤقتًا، ويُبلغ حدث `Transfer` عن المبلغ الذي وصل بعد خصم الرسوم، لا عن المبلغ المُرسَل. يمكنك قراءة نوع الغلاف الذي حصل عليه mint من المصنع باستخدام `wrapper_kind_by_mint(mint)`؛ وفي مصنع Hadrian المباشر، تُرجع أغلفة USDC وETH وSOL جميعها `1`.

ما الذي يُرفض:

* لا يمكن لـ mint يتضمن خطاف تحويل مفعّل أن يحصل على أحد الأغلفة العادية. نشر `SPL_ERC20` أو `SPL_ERC20_cached` عليه مباشرةً يؤدي إلى التراجع مع `ArmedTransferHookUnsupported(mint, hookProgram)`. أما عبر المصنع، فتُوجَّه هذه الحالة إلى الغلاف ذي الخطاف.
* يتسبب العنوان الذي لا يمثل mint من SPL في أن تتراجع `mint_info` مع `Invalid SPL mint account: <address>`.
* يتسبب mint الذي لديه غلاف بالفعل في التراجع مع `Token exists`كما يتسبب الرمز المستخدم بالفعل في التراجع مع `Token with symbol exists`.
* `add_spl_token_with_metadata` يقرأ الاسم والرمز من بيانات Token-2022 الوصفية الخاصة بالـ mint أولًا، ثم من Metaplex. إذا لم تتوفر للـ mint بيانات من أيٍّ منهما، فإنه يتراجع مع `Mint asserts no name: use add_spl_token_no_metadata`.

آلية عمل الغلاف ذي الخطاف:

* يشغّل Token-2022 الخطاف عند كل عملية تحويل، ويحتاج الخطاف إلى حسابات تعتمد على التحويل. لا يستطيع الغلاف تحديد هذه الحسابات، لذا يستخرج المستدعي القائمة الكاملة للحسابات من قائمة extra-account-metas الخاصة بالـ mint ويمررها إليه. يتحقق الغلاف من الجزء الثابت من تلك القائمة (برنامج الخطاف وحساب التحقق الخاص به) ويمررها دون تغيير.
* الدالة العادية `transfer`, `transferFrom` و `bridgeOutToSolana` ترجع بخطأ باستخدام `HookAccountPlanRequired`. استخدم `transferWithHookAccounts`, `transferFromWithHookAccounts` و `bridgeOutToSolanaWithHookAccounts`، إذ تأخذ قائمة الحسابات كوسيط إضافي.
* إذا تغيّر برنامج الخطاف الخاص بـ mint بعد نشر الغلاف، فسترجع عمليات التحويل بخطأ باستخدام `HookConfigurationChanged`.
* ينقل الرموز عبر استدعاء مباشر بين البرامج، أي عبر المسار القديم، ولا يستخدم المسار المخزّن مؤقتًا. يلتزم العقد بمسار واحد باستمرار، ولا تُنفّذ الاستدعاءات عبر المسار القديم إلا ضمن تنفيذ ذري؛ لذا يجب أن يتسع الاستدعاء الذي يستخدم الغلاف ذي الخطاف لمعاملة ذرية واحدة.
* لا يحتفظ بسجل لأرصدة العقد. تصل الرموز المرسلة إلى عقدٍ ما إلى حساب الرموز الخاص بالعقد نفسه، ولا يمكن للعقد إرسالها إلا بعد أن يمنح `approve_spl` للغلاف نفسه.
* يحتاج إلى المنحة نفسها [لمرة واحدة](#one-time-grant-per-wallet) مثل أي غلاف آخر.

## القيود

* مبالغ رموز SPL هي من النوع `uint64` (الحد الأقصى 18,446,744,073,709,551,615)
* موافقات ERC-20 (`approve` / `allowance`) هي بيانات تخزين في EVM. ينقل الغلاف الرموز بصفته مفوّض SPL للمستخدم، الذي يمنحه التفويض مرة واحدة لكل غلاف (راجع [منحة لمرة واحدة لكل محفظة](#one-time-grant-per-wallet))
* يجب أن تكون رموز أغلفة ERC-20 فريدة لكل مصنع

## ما التالي

* [عناوين العقود](https://docs.rome.builders/ar/almrja/contract-addresses.md) — البرامج المسبقة التجميع والعناوين لكل سلسلة
* [استدعاء Solana من EVM](https://docs.rome.builders/ar/adlh-almtw-ryn/call-solana-from-evm.md) — عمليات CPI وSPL من Solidity
* [كيف تلتقي Solana وEVM على Rome](https://docs.rome.builders/ar/almfahym-alasasyh/how-solana-and-evm-meet.md)
* [دمج برنامج Solana](https://docs.rome.builders/ar/adlh-almtw-ryn/integrate-solana-program.md)


---

# 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/almfahym-alasasyh/token-interop.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.
