> 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/almntjat/rome-sdk.md). # Rome SDK واجهات Solidity مُنظَّمة النوع لاستدعاء برامج Solana من عقود EVM، بالإضافة إلى Rust SDK الذي يشغّل خدمات Rome خارج السلسلة. توفر حزمة تطوير Rome SDK واجهات Solidity مُنَمطَة للتفاعل مع برامج Solana من عقود EVM الذكية. إنها مجموعة أدوات المطورين لبناء تطبيقات عبر بيئات التشغيل على Rome. ## حِزم SDK لدى Rome حِزم SDK لثلاث فئات — منشئو التطبيقات (TypeScript)، ومطورو العقود (Solidity)، والفرق التي تشغّل خدماتها الخاصة على Rome (Rust). ### حزمة تطوير TypeScript (`@rome-protocol/sdk`) **لمطوري dapp والواجهة الأمامية** — الحزمة التي يبدأ بها معظم منشئي التطبيقات. [`@rome-protocol/sdk`](https://github.com/rome-protocol/rome-sdk-ts) تغلف مسار الكتابة في Rome بحيث يرسل تطبيق الويب معاملات Rome بشكل صحيح: `submitRomeTx` (مسار الكتابة الصحيح مع التعامل مع الغاز/الرسوم)، واستخراج PDA / ATA، و CPI `invoke` / `invoke_signed` ، ومشفّرات encoder، وروابط precompile، و `/bridge` مسار فرعي. التثبيت من المستودع أولاً (نشر npm قيد الانتظار): ```bash npm install github:rome-protocol/rome-sdk-ts#v0.4.0 ``` ```typescript import { submitRomeTx } from '@rome-protocol/sdk'; // أرسل أي عملية كتابة إلى Rome EVM عبر مسار الكتابة الصحيح (يتعامل مع ترميز الغاز/الرسوم). ``` التطبيق [rome-dex](https://github.com/rome-protocol/rome-dex) العام يستخدم فقط عدداً قليلاً من مساعدات الحزمة (استخراج PDA وحساب الرمز المميز، ومشفّر CPI `invoke` ومخزن الغاز 1.3x)، و [cardo](https://github.com/rome-protocol/cardo) لا يعتمد عليها. كما أنه لا يستدعي `submitRomeTx` أو `submitRomeTxV1`، لذا اقرأهما لمعرفة كيفية استدعاء التطبيق لـ precompile الخاص بـ CPI، وليس لمسار الكتابة في الحزمة. **مساران، وحزمة SDK واحدة.** `submitRomeTx` هو مسار EVM (MetaMask). أما في **مسار Solana** — محفظة Solana تقود تطبيق EVM الخاص بك — `submitRomeTxV1` فهو يعكس ذلك: حيث يقوم الوكيل بتركيب معاملة Solana v1 واحدة للاستدعاء، وتوقّع المحفظة مرتين بالمفتاح نفسه (رسالة تفويض مقروءة، ثم المعاملة)، ويُشغّل Rome الاستدعاء كمعاملة EVM من الهوية المشتقة للمستخدم، من دون مفتاح EVM. ويتم تمرير الاستدعاء الذي لا يناسب معاملة واحدة عبر الوكيل مع توقيع التفويض نفسه، و `fundSyntheticGas` تضيف إلى الغاز الأصلي الذي يستهلكه الاستدعاء المُرحَّل. وإذا فشل استدعاء مُرحَّل، فإن النتيجة تكون `receipt.status === "0x0"` بدلاً من رمي خطأ، لذا تحقّق منه؛ [قسم الاستدعاءات المُرحَّلة والاستدعاءات الطويلة](/ar/adlh-almtw-ryn/call-evm-from-solana.md#relayed-calls-and-long-calls) يحتوي على قاعدة الغاز والحدود. تنتقل القيمة إلى الداخل والخارج عبر `buildFundLeg` / `buildSweepLeg` على أنه غلاف ERC-20 (مثلاً `wUSDC`)، وليس أصلياً `msg.value` — إذ لا يحمل المرسل الاصطناعي شيئاً في حالة السكون — ويُزوَّد المرسل الاصطناعي لأول مرة مرةً واحدة، وبشكل صريح، باستخدام `buildCreatePdaCall`. أما `submitRomeTxSolanaLane`السابقة، التي تبني معاملة Solana قديمة في العميل، فما تزال موجودة في الحزمة. انظر [ابنِ تطبيقًا ثنائي المسار](/ar/adlh-almtw-ryn/dual-lane-app.md) و [استدعِ EVM من Solana](/ar/adlh-almtw-ryn/call-evm-from-solana.md). ### حزمة Solidity SDK (`@rome-protocol/rome-solidity`) **لمطوري Solidity.** توفر واجهات precompile، ولفائف ERC-20/SPL، واستخراج PDA، وأدوات CPI. نشر npm قيد الانتظار؛ ويمكنك اليوم استهلاكها من [`rome-solidity`](https://github.com/rome-protocol/rome-solidity) المستودع العام (اعتماد git أو ملفات منسوخة). ```solidity import {ISystemProgram, ICrossProgramInvocation, IHelperProgram, IWithdraw} from "@rome-protocol/rome-solidity/contracts/interface.sol"; import {SPL_ERC20} from "@rome-protocol/rome-solidity/contracts/erc20spl/erc20spl.sol"; import {RomeEVMAccount} from "@rome-protocol/rome-solidity/contracts/rome_evm_account.sol"; ``` ### حزمة Rust SDK (`rome-sdk`) **للفرق التي تشغّل خدماتها الخاصة على Rome.** مساحة عمل Rust تتعامل مع تركيب المعاملات، والتفاعل مع Solana، وتسعير الغاز، وفهرسة الكتل. ويُبنى عليها Proxy وHercules. المصدر موجود في [`rome-protocol/rome-sdk`](https://github.com/rome-protocol/rome-sdk). وهي ترسل معاملات Solana v1 (4 كيلوبايت، حتى 64 حساباً). **بناءها.** تتوقع مساحة العمل أن تكون المستودعات [`rome-sdk`](https://github.com/rome-protocol/rome-sdk), [`rome-evm`](https://github.com/rome-protocol/rome-evm) و [`mollusk`](https://github.com/rome-protocol/mollusk) مستنسخة جنباً إلى جنب، لأنها تعتمد على الاثنين الآخرين عبر مسار نسبي. ولهذا أيضاً فإن الطريقة المدعومة لاستخدامها من مشروع آخر هي كاعتماد مسار، وليس كاعتماد git عادي. تحتاج إلى Rust 1.85 أو أحدث وإلى وصول إلى الشبكة في أول بناء. `rome-evm` لا يملك ميزة شبكة افتراضية، لذا فإن أي بناء يترجمه يحتاج بالضبط إلى واحدة من `ci`, `testnet` أو `mainnet`؛ استخدم `ci` للعمل المحلي، على سبيل المثال `cargo test -p rome-sdk --features ci`. يحتوي README الخاص بالمستودع على الخطوات الكاملة وجدول الميزات. **الترخيص.** حزمة Rust SDK متاحة كمصدر، وليست مفتوحة المصدر: جميع الحقوق محفوظة، ويجوز استخدامها لأغراض شخصية وغير تجارية. ويتطلب الاستخدام التجاري إذناً خطياً من Rome Protocol؛ ويقول ملف `LICENSE` في المستودع كيفية الطلب. ## Solidity SDK: ما الذي يتضمنه ### واجهات Precompile اربط واجهة بعنوان precompile الخاص بها: ```solidity ISystemProgram constant System = ISystemProgram(0xFF00000000000000000000000000000000000007); ICrossProgramInvocation constant Cpi = ICrossProgramInvocation(0xFF00000000000000000000000000000000000008); IHelperProgram constant Helper = IHelperProgram(0xFF00000000000000000000000000000000000009); IWithdraw constant Withdraw = IWithdraw(0x4200000000000000000000000000000000000016); // المسار المخزن مؤقتاً: ISplCached 0xff…05، IAssociatedSplCached 0xff…06، ISystemCached 0xff…04، IWithdrawCached 0xff…0b ``` ### عمليات SPL Token استخدم `IHelperProgram` (`0xff…09`للعناصر الأساسية في SPL الموقَّعة بواسطة PDA الخاصة بالمستخدم: ```solidity // أنشئ ATA الخاص بالمتصل لعملة mint Helper.create_ata(user, mint); // انقل SPL من PDA الخاصة بالمتصل Helper.transfer_spl(to, tokens, mint); ``` في المسار المخزن مؤقتاً، توجد العمليات المكافئة على `ISplCached` (`0xff…05`، و `IAssociatedSplCached` (`0xff…06`). انظر `interface.sol` لجميع الأشكال الزائدة؛ يستخدم العقد مساراً واحداً باستمرار. ### استخراج PDA ```solidity // استخرج PDA الخاصة بمستخدم Solana bytes32 userPda = RomeEVMAccount.pda(msg.sender); // استخرج PDA مع salt (لإنشاء عدة PDA لكل مستخدم) bytes32 pda = RomeEVMAccount.pda_with_salt(msg.sender, salt); // اعثر على PDA عشوائية (bytes32 pda, uint8 bump) = SystemProgram.find_program_address(programId, seeds); ``` ### الاستدعاء بين البرامج ```solidity // استدعِ أي برنامج Solana ICrossProgramInvocation.AccountMeta[] memory accounts = new ICrossProgramInvocation.AccountMeta[](2); accounts[0] = ICrossProgramInvocation.AccountMeta(signerPda, true, true); accounts[1] = ICrossProgramInvocation.AccountMeta(targetAccount, false, true); CpiProgram.invoke(programId, accounts, instructionData); // استدعِ مع توقيع PDA CpiProgram.invoke_signed(programId, accounts, data, seeds); // اقرأ بيانات الحساب (uint64 lamports, bytes32 owner, bool isSigner, bool isWritable, bool executable, bytes memory data) = CpiProgram.account_info(pubkey); ``` ### ERC-20 فوق رموز SPL ```solidity // انشر غلافاً لأي mint من SPL ERC20SPLFactory factory = ERC20SPLFactory(FACTORY_ADDRESS); address wrapper = factory.add_spl_token_with_metadata(splMint); // استخدم الغلاف كأنه ERC-20 قياسي SPL_ERC20 token = SPL_ERC20(wrapper); token.transfer(recipient, amount); uint256 balance = token.balanceOf(user); ``` ### إلغاء التسلسل باستخدام Borsh ```solidity import {Convert} from "@rome-protocol/rome-solidity/contracts/convert.sol"; // حلّل بيانات حساب Solana (صيغة Borsh بنظام little-endian) (uint64 value, uint256 newOffset) = Convert.read_u64le(data, offset); (bytes32 pubkey, uint256 newOffset2) = Convert.read_bytes32(data, offset); ``` ### بيانات Metaplex الوصفية ```solidity import {MplTokenMetadataLib} from "@rome-protocol/rome-solidity/contracts/mpl_token_metadata/lib.sol"; // حمّل بيانات الرمز المميز الوصفية من Metaplex MplTokenMetadataLib.Metadata memory meta = MplTokenMetadataLib.load_metadata( mintPubkey, mplProgramId, cpiAddress ); string memory name = meta.name; string memory symbol = meta.symbol; ``` ## حزمة Rust SDK: البنية حزمة Rust SDK هي مساحة عمل Cargo. أهم الحزم الأساسية فيها: | الحزمة | الغرض | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------- | | `rome-sdk` | واجهة API الأساسية: `Rome` struct، والإعدادات، وأنواع المعاملات (RheaTx, RemusTx, RomulusTx) | | `rome-evm-client` | عميل تجميع EVM، TxBuilder، ResourceFactory، وتكامل المحاكي | | `rome-solana` | برج Solana، وعميل RPC، وتجميع المعاملات وتتبعها | | `rome-utils` | أدوات RLP، وhex، وJSON-RPC، والمصادقة | | `rome-obs` | قابلية الملاحظة عبر OpenTelemetry (التتبعات، المقاييس، السجلات) | | `rome-meteora` | قارئات مجمعات Meteora DAMM v1 وv2 لتسعير الغاز | | `rome-meta-hook` | عميل لبرنامج Meta-Hook Router: إعداد transfer-hook في Token-2022، وحلّ الحسابات الإضافية، والتحويلات مع تقديرات ميزانية الحوسبة | | `rome-jito-bundler` | منشئ حزم Jito لإرسال معاملات متعددة ذرّياً | ### أنواع المعاملات ```rust // معاملة تجميع واحدة let rhea = RheaTx::new(signed_eth_tx); let mut tx = rome.compose_rollup_tx(rhea).await?; let sig = rome.send_and_confirm(&mut *tx).await?; // معاملة ذرّية عبر عدة تجميعات let remus = RemusTx::new(vec![tx1, tx2]); let mut tx = rome.compose_cross_rollup_tx(remus).await?; // معاملة ذرّية عبر السلاسل (EVM + Solana) let romulus = RomulusTx::new(eth_txs, sol_ixs); let mut tx = rome.compose_cross_chain_tx(romulus, signers).await?; ``` ### تجميع الموارد تجمع الحزمة أزواج مفاتيح Solana (الدافعون) وفهارس حسابات الحافظ لإرسال المعاملات بالتوازي: ```rust let resource = resource_factory.get().await?; let payer = resource.payer(); // زوج مفاتيح Solana let holder = resource.holder(); // فهرس حساب الحافظ // تُعاد الموارد تلقائياً إلى التجمع عند Drop ``` ## خارطة طريق الحزمة ### مبني ويعمل * لفائف SPL Token وواجهات precompile * مقايضات Meteora DAMM v1 عبر CPI * Oracle Gateway V1 + V2 (Pyth Pull, Switchboard V3) * مساعدات System Program، وإلغاء التسلسل باستخدام Borsh * Factory لـ ERC20SPL وعقود الجسر ## ما التالي * [انشر Solidity](/ar/adlh-almtw-ryn/deploy-solidity.md) — انشر عقدك الأول باستخدام الحزمة * [استدعِ Solana من EVM](/ar/adlh-almtw-ryn/call-solana-from-evm.md) — استخدم CPI للتفاعل مع برامج Solana * [عناوين العقود](/ar/almrja/contract-addresses.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/almntjat/rome-sdk.md?ask=&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.