> 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).

### SDK TypeScript (`@rome-protocol/sdk`)

**للمطورين في التطبيقات اللامركزية والواجهة الأمامية** — حزمة SDK التي يبدأ بها معظم بنّائي التطبيقات. [`@rome-protocol/sdk`](https://github.com/rome-protocol/rome-sdk-ts) يغلّف مسار الكتابة في Rome بحيث يرسل تطبيق الويب معاملات Rome بشكل صحيح: `submitRomeTx` (مسار الكتابة الصحيح مع معالجة الغاز/الرسوم)، اشتقاق PDA / ATA، وCPI `invoke` / `invoke_signed` المشفّرات، وروابط الـ precompile، و `/bridge` مسار فرعي. التثبيت من المستودع أولًا (النشر على npm قيد الانتظار):

```bash
npm install github:rome-protocol/rome-sdk-ts#v0.4.0
```

```typescript
import { submitRomeTx } from '@rome-protocol/sdk';
// أرسل أي كتابة EVM على Rome عبر مسار الكتابة الصحيح (يتولى ترميز الغاز/الرسوم).
```

التطبيق العام [rome-dex](https://github.com/rome-protocol/rome-dex) يستخدم التطبيق فقط عددًا قليلًا من مساعدات SDK (اشتقاق PDA وحساب الرمز المميز، وCPI `invoke` المشفّر وهامش الغاز 1.3x)، و [cardo](https://github.com/rome-protocol/cardo) لا يعتمد عليه. كما أن أياً من النداءات `submitRomeTx` أو `submitRomeTxV1`، لذا اقرأهما لمعرفة كيف يستدعي التطبيق الـ precompile الخاص بـ CPI، لا لمسار الكتابة في SDK.

**مساران، وSDK واحد.** `submitRomeTx` هو مسار EVM (MetaMask). أما بالنسبة إلى **مسار Solana** — محفظة Solana تدير تطبيق EVM الخاص بك — `submitRomeTxV1` يعكسه: يقوم الوكيل بتركيب معاملة Solana v1 واحدة للاستدعاء، وتوقّع المحفظة مرتين بالمفتاح نفسه (رسالة تفويض قابلة للقراءة، ثم المعاملة)، ويشغّل Rome الاستدعاء كمعاملة EVM من الهوية المشتقة للمستخدم، دون مفتاح EVM. أما الاستدعاء الذي لا يتسع ضمن معاملة واحدة فيُرحَّل بواسطة الوكيل باستخدام توقيع التفويض نفسه، و `fundSyntheticGas` يُكمل الغاز الأصلي الذي يستهلكه الاستدعاء المُرحَّل. والاستدعاء المُرحَّل الذي يتراجع يُحلّ بـ `receipt.status === "0x0"` بدلًا من رمي استثناء، لذا تحقّق منه؛ [الاستدعاءات المُرحَّلة والاستدعاءات الطويلة](https://docs.rome.builders/ar/adlh-almtw-ryn/call-evm-from-solana.md#relayed-calls-and-long-calls) يحتوي القسم على قاعدة الغاز والحدود. وتتحرك القيمة إلى الداخل والخارج عبر `buildFundLeg` / `buildSweepLeg` بوصفه غلاف ERC-20 (مثل `wUSDC`)، وليس أصليًا `msg.value` — المرسِل الاصطناعي لا يحتفظ بأي شيء وهو ساكن — `buildCreatePdaCall`. أما `submitRomeTxSolanaLane`، الذي يبني معاملة Solana قديمة في العميل، فلا يزال موجودًا في SDK. انظر [أنشئ تطبيقًا ثنائي المسار](https://docs.rome.builders/ar/adlh-almtw-ryn/dual-lane-app.md) و [استدعِ EVM من Solana](https://docs.rome.builders/ar/adlh-almtw-ryn/call-evm-from-solana.md).

### SDK Solidity (`@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";
```

### SDK Rust (`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`, `شبكة الاختبار` أو `الشبكة الرئيسية`; استخدم `ci` للعمل المحلي، على سبيل المثال `cargo test -p rome-sdk --features ci`. يحتوي README الخاص بالمستودع على الخطوات الكاملة وجدول الميزات.

**الترخيص.** إن Rust SDK متاح المصدر، وليس مفتوح المصدر: جميع الحقوق محفوظة، ويمكن استخدامه لأغراض شخصية غير تجارية. الاستخدام التجاري يحتاج إلى إذن كتابي من Rome Protocol؛ ويشير `LICENSE` ملف إلى كيفية الطلب.

## SDK Solidity: ما المتضمن

### واجهات 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

استخدم `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 مع ملح (لإنشاء عدة PDAs لكل مستخدم)
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 بنهاية صغيرة)
(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;
```

## SDK Rust: البنية

SDK Rust هو مساحة عمل Cargo. حِزمه الأساسية:

| الحزمة              | الغرض                                                                                                                           |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `rome-sdk`          | واجهة برمجة التطبيقات الأساسية: `Rome` البنية، والإعداد، وأنواع المعاملات الثلاثة (`RheaTx`, `RemusTx`, `RomulusTx`)            |
| `rome-evm-client`   | عميل EVM لسلاسل Rome، TxBuilder، ResourceFactory، ودمج المحاكي                                                                  |
| `rome-solana`       | Tower الخاص بـ 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
// معاملة EVM واحدة على سلسلة Rome واحدة
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?;

// عدة معاملات EVM على سلاسل Rome مختلفة، ذرّية ضمن معاملة Solana واحدة
let remus = RemusTx::new(vec![tx1, tx2]);
let mut tx = rome.compose_cross_rollup_tx(remus).await?;

// معاملات EVM بالإضافة إلى تعليمات Solana الأصلية، ذرّية ضمن معاملة 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
```

## خارطة طريق SDK

### مبني ويعمل

* غلافات رموز SPL وواجهات precompile
* مبادلات Meteora DAMM v1 عبر CPI
* Oracle Gateway V1 + V2 (Pyth Pull، Switchboard V3)
* مساعدات System Program، وإلغاء تسلسل Borsh
* ERC20SPL Factory وعقود الجسر

## ما التالي

* [انشر Solidity](https://docs.rome.builders/ar/adlh-almtw-ryn/deploy-solidity.md) — انشر أول عقد لك باستخدام SDK
* [استدعِ Solana من EVM](https://docs.rome.builders/ar/adlh-almtw-ryn/call-solana-from-evm.md) — استخدم CPI للتفاعل مع برامج Solana
* [عناوين العقود](https://docs.rome.builders/ar/almrja/contract-addresses.md) — عناوين عقود SDK المنشورة


---

# 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=<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.
