> 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/alttbyqat-ala-rome/bloom/building.md).

# البناء على Bloom

يجيب هذا الدليل عن سؤال واحد: **كيف يفعل المنشئ ذلك بنفسه؟** خذ عقد أصول حقيقية مكتوبًا بلغة Solidity، وشغّله على سلسلة Rome كرمز مقيّد الصلاحيات، وافتحه لمحافظ Solana وكذلك محافظ EVM من دون رمز ثانٍ، ووصل قرارك الخاص بـ KYC/الامتثال.

الجمهور هو مطوّر يقيّم هذا النهج أو يتبنّاه. Bloom هو المثال العملي طوال الدليل — وأصلُه الحي **ARCV («Mineral Vault I»)** على Hadrian (`200010`) هو تطبيق حقيقي لكل خطوة أدناه، وسند نشره (`deployments/200010.tokens/ARCV.json`) يسجّل العقود الثلاثة الدقيقة وثماني المعاملات التي تنتجها هذه الطريقة.

لا شيء هنا يغيّر عقود الأصل. يشغّل Bloom إطار Arc الخاص بـ Plume **من دون تعديل** (الشجرة المضمَّنة في `contracts/`، ومطابقة بايتًا لـ `plumenetwork/contracts` عند التثبيت في `NOTICE`)؛ العقد الوحيد على جانب Rome هو `ArcTokenFactoryV2`، الذي يضيف دالة واحدة. العمل يكمن في *كيف* أنت تنشر و *كيف* أنت تتحكم بالعقود — لا في تغييرها.

> **الطريقة في لمحة.** الرمز المقيّد الصلاحيات هو **ثلاثة** عقود منشورة. ويُنشَر **على مراحل** — عقد واحد لكل معاملة — لأن استدعاء المصنع في معاملة واحدة يتجاوز حد الحسابات لكل معاملة في Rome. ويجب أن تأتي وكلاؤه من **بُنى مقفلة المصدر** وإلا يفشل التسجيل على السلسلة بشكلٍ آمن. والامتثال هو **قيمة منطقية واحدة لكل عنوان**، يكتبها من يصرّح له إجراء KYC الخاص بك. كما يمكن الوصول إلى النشر نفسه من محفظة Solana عبر **مرسل اصطناعي** مشتق على السلسلة — لا رمز ثانٍ، ولا قائمة سماح ثانية.

## المتطلبات الأساسية

> **قبل أن تبدأ.** أدوات المُصدِر التي يستخدمها هذا الدليل لم تُنشر بعد. ويشمل ذلك النصوص البرمجية (`deploy-infra.ts`, `create-token.ts` والبقية)، و `contracts/` و `rome-contracts/` الأشجار، وإيصالات النشر التي يسميها. يحصل المُصدِرون على هذه الأدوات عبر الانضمام إلى Rome. وحتى ذلك الحين، اقرأ الدليل بوصفه وصفًا للطريقة وما يفعله كل سكربت.

توجد الأدوات المرجعية في `scripts/` مجلد (يُقدَّم عند الانضمام؛ ثبّت اعتماداته باستخدام `npm install`). كل أمر يستخرج حقائق السلسلة من السجل بدلاً من ترميزها صراحةً، لذا فإن توجيهه إلى سلسلة Rome أخرى هو تغيير في البيئة، لا في الشيفرة:

```bash
export PRIVATE_KEY=…       # مفتاح الموزِّع/المُصدِر المموَّل على السلسلة المستهدفة
export CHAIN_ID=200010     # يختار السلسلة
export REGISTRY_ROOT=…     # نسخة مُستخرجة من سجل سلاسل Rome
# تحتاج تدفقات مسار Solana أيضًا إلى:
export SOLANA_KEYPAIR=…    # مسار إلى ملف JSON لمفتاح Solana ممول (دافع الرسوم)
```

غاز سلاسل Rome مُسعَّر بعملة USDC؛ وتكلفة تسلسل النشر الكامل في حدود 10–15 وحدة أصلية على devnet. تأتي المفاتيح من البيئة فقط — وليس من المستودع أبدًا. ابنِ العقود مرة واحدة قبل النشر، لأن البنى **يجب أن** تأتي من `rome-contracts/out` (انظر الخطوة 3):

```bash
cd contracts       && forge build --via-ir     # مجموعة Arc المضمَّنة
cd rome-contracts  && forge build --via-ir     # ArcTokenFactoryV2 + الوكيل القياسي
```

***

## الخطوة 1 — اعرف ما هو الرمز المقيّد الصلاحيات *هو* هنا

رمز Bloom المقيّد الصلاحيات ليس عقدًا واحدًا. بل هو **ثلاثة عقود منشورة**، بالإضافة إلى أربعة عقود مشتركة ينشرها فريق العمليات مرة واحدة لكل سلسلة ويعيد كل مُصدِر استخدامها.

**العقود الثلاثة الخاصة بكل رمز** — كل أصل يملك بالضبط هذه:

| العقد                         | المصدر                                                      | ما هو                                                                                              |
| ----------------------------- | ----------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| `ArcTokenProxy`               | `contracts/src/proxy/ArcTokenProxy.sol`                     | الرمز نفسه — وكيل UUPS يشير إلى `ArcToken` التنفيذ المشترك. الأرصدة، والحائزون، والأدوار توجد هنا. |
| `قيود القائمة البيضاء`        | `contracts/src/restrictions/WhitelistRestrictions.sol`      | وحدة قائمة السماح. قيمة منطقية واحدة لكل عنوان؛ وتُفرض عند كل تحويل بينما يكون الأصل مقيّدًا.      |
| `قيود القائمة السوداء للعائد` | `contracts/src/restrictions/YieldBlacklistRestrictions.sol` | وحدة العائد. تستبعد العناوين من توزيعات العائد من دون المساس بحيازتها.                             |

**العقود الأربعة المشتركة، واحد لكل سلسلة** (تُنشر بواسطة `deploy-infra.ts`):

| العقد                | الدور                                                             |
| -------------------- | ----------------------------------------------------------------- |
| `RestrictionsRouter` | سجل أنواع الوحدات — توصيل السلسلة، يضبطه فريق العمليات مرة واحدة. |
| `ArcTokenFactoryV2`  | التسجيل + بصمة الشيفرة القياسية للوكيل (الخطوتان 2–3).            |
| `ArcToken` (التنفيذ) | منطق الأصل المشترك القابل لإعادة الاستخدام الذي يشير إليه كل رمز. |
| `ArcTokenPurchase`   | واجهة بيع واحدة، مشتركة بين كل رمز وكل مُصدِر (الخطوة 4).         |
| wUSDC                | جانب النقد — عملة العائد وعملة الشراء والبيع.                     |

تقييد التحويل وتقييد العائد هما **وحدتين منفصلتين عمدًا**: يمكن منع الحائز من الدخل مع الاحتفاظ بالأصل، وهذه هي الطريقة التي تعمل بها العقوبات والأوامر القضائية في الواقع.

حقيقة «العقود الثلاثة» أساسية للتحقق. `verify-deployments.ts` و `register-asset.ts` يتوقع كلاهما أن يحل الرمز إلى ثلاثة عقود منشورة — والتحقق اليدوي من رمز واحد فاته سبعة منها عبر سلسلة كاملة (كل وحدة عائد وثلاث وحدات قائمة سماح).

لدورة الحياة ثلاث مراحل وباب أحادي الاتجاه:

```
مسودة     الوكيل نشط، ولا توجد وحدة مرتبطة — لا شيء يقيّد أي تحويل
  ↓
غير مقيّد   الوحدة مرتبطة، transfersAllowed = true   (WhitelistRestrictions.initialize تضبط هذا)
  ↓  صُكّ المعروض، وابنِ قائمة السماح               [قابل للعكس]
مقيّد     setTransfersAllowed(false)                [باب أحادي الاتجاه — يصبح المعروض نهائيًا]
```

التقييد أحادي الاتجاه بالنسبة للمعروض لأن الصكّ والحرق يمران عبر `address(0)` كطرف مقابل، و `address(0)` لا يمكن إدراجه أبدًا في قائمة السماح — لذا بمجرد تقييده، لا يمكن صك أي معروض جديد مطلقًا. هذا هو الضمان الذي يقدمه الأصل المقيّد لحامليه.

***

## الخطوة 2 — انشره على مراحل، لا كمعاملة واحدة أبدًا

تُصدر Arc أداة أحادية الضربة `createToken` تقوم بنشر الوكيل والوحدتين معًا وتوصيلهما في استدعاء واحد. **في Rome لا يمكنك استخدامها.** تلك المعاملة تحتاج إلى **77 قفلًا لحسابات Solana**، وحد Rome لكل معاملة هو **62 قفلًا**. لا يمكن أن يتسع أبدًا — لا مع الضبط، ولا مع تمرير تحسين.

لذلك يكون النشر **على مراحل**: كل عقد في معاملة خاصة به، ويكتسب الرمز حالة مكافئة للمصنع عبر `ArcTokenFactoryV2.registerToken` بدلاً من `createToken`. هذا هو معالج الإنشاء، وهو ما تفعله واجهة المُصدِر خطوة بخطوة:

![معالج الإنشاء](https://1717205515-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F671PKS8ZQSNqtoC8PGvz%2Fuploads%2Fgit-blob-94683a3a49ac2418aed8cc66dbf47fad940814f7%2Fcreate-wizard.png?alt=media\&token=38b47568-d343-483d-8ce1-f437164bdeae)

التنفيذ المرجعي هو `arc/plan/create.ts` (`createSequence()`، والتي تعرضها التطبيق على هيئة ست بطاقات (`bloom/lib/createCards.ts`) على مدى **ثماني معاملات**، وبالترتيب الدقيق الذي تفرضه العقود:

| # | المعاملة                     | استدعاء العقد                                                                 |
| - | ---------------------------- | ----------------------------------------------------------------------------- |
| 1 | نشر الأصل                    | `new ArcTokenProxy(impl, initData)` حيث `initData = ArcToken.initialize(...)` |
| 2 | نشر وحدة القائمة المسموح بها | `new WhitelistRestrictions()`                                                 |
| 3 | اجعل نفسك مديرًا له          | `whitelist.initialize(issuer)`                                                |
| 4 | فرضه على التحويلات           | `token.setRestrictionModule(TRANSFER, whitelist)`                             |
| 5 | نشر وحدة العائد              | `new YieldBlacklistRestrictions()`                                            |
| 6 | اجعل نفسك مديرًا له          | `yieldBlacklist.initialize(issuer)`                                           |
| 7 | فرضه على العائد              | `token.setRestrictionModule(YIELD, yieldBlacklist)`                           |
| 8 | التسجيل لدى المصنع           | `factoryV2.registerToken(token, impl)`                                        |

صيغة السكربت هي أمر واحد:

```bash
# مرة واحدة لكل سلسلة (العمليات، لا لكل رمز) — ينشر العقود الأربعة المشتركة
npx tsx deploy-infra.ts

# لكل رمز — المعالج، يُعاد تشغيله كسكربت
NAME="Mineral Vault I" SYMBOL=ARCV SUPPLY=1000000 DECIMALS=6 npx tsx create-token.ts
```

المُصدِر (`PRIVATE_KEY`) يوقّع كل معاملة وينتهي به الأمر حاملًا لأدوار الرمز (`ArcToken.initialize` التفويضات إلى `msg.sender` — انظر الخطوة 7). والتسجيل (المعاملة 8) هو ما يفعّل `enableToken` وأي ترقية تُدار عبر المصنع.

> **لا «تحسّن» هذا لتعيده إلى كتلة واحدة.** تجميع هذه الاستدعاءات في معاملة واحدة لتوفير الذهاب والإياب يعيد بالضبط تجاوز حد 62 قفلًا الذي وُجد المسار المرحلي لتجنبه. والحد نفسه هو سبب أن توزيع العائد يسير حاملًا واحدًا لكل معاملة (الخطوة 8). إذا فشل استدعاء برسالة `عدد الحسابات كبير جدًا: N > 62`، فهناك معاملة واحدة تلمس عددًا كبيرًا جدًا من الحسابات — قسّمها، لا تضبطها.

***

## الخطوة 3 — انشر الوكلاء فقط من البُنى المقفلة المصدر

`registerToken` هو الحدّ الأمني الذي يجعل النشر المرحلي آمنًا. ولن يقبل إلا رمزًا تكون **بصمة الشيفرة وقت التشغيل له مطابقة للبصمة القياسية `ArcTokenProxy`** المثبتة في المصنع وقت النشر:

```solidity
// rome-contracts/src/ArcTokenFactoryV2.sol
bytes32 private immutable CANONICAL_PROXY_CODEHASH =
    keccak256(type(ArcTokenProxy).runtimeCode);

function registerToken(address token, address implementation) external {
    if (token.codehash != CANONICAL_PROXY_CODEHASH) revert ProxyCodehashUnknown();
    // …يجب أن يكون التنفيذ مُدرجًا في قائمة سماح المصنع، ويجب أن يحمل msg.sender
    //    دور ADMIN_ROLE الخاص بالرمز، ويجب ألا يكون الرمز مسجلاً بالفعل.
}
```

لأن بصمة الشيفرة هذه **ثابتة**، فإن أي وكيل يُبنى من أي بُنية أخرى يفشل بشكل آمن مع `ProxyCodehashUnknown`. وينتج عن ذلك قاعدتان، وكلتاهما مفروضتان عبر CI والقواعد الصارمة في `CLAUDE.md`:

1. **يجب نشر وكلاء الرموز من `rome-contracts/out`** — لا من `contracts/out`، ولا من بناء مختلف. هذا هو التجميع الذي تثبته بصمة الشيفرة القياسية للمصنع.
2. **`bytecode_hash = "none"` و `cbor_metadata = false`** في `rome-contracts/foundry.toml` هما عنصران حامِلان للحمولة. ومع تفعيل البيانات الوصفية، فإن `ArcTokenProxy` الرمز وقت التشغيل *المضمَّن* في المصنع (`type().runtimeCode`) يحمل لاحقة CBOR/IPFS مختلفة عن `out/` البنية التي ينشر منها المعالج — لذا على السلسلة `registerToken` يحدث revert بينما **تمر جميع اختبارات Foundry داخل المصدر** (يضمّن Foundry النسختين معًا، لذا لا يمكنه رؤية عدم التطابق). `rome-contracts/test/ArtifactProvenance.t.sol` يثبّت هذه الخاصية؛ وكان التشغيل المموَّل هو ما اكتشفها أصلًا.

> **نجاح مجموعة الاختبارات داخل المصدر لا يثبت المصدرية.** قبل شحن صورة، وبعد أي تغيير في إعدادات المترجم، أثبت الخاصية مقابل *المُنشر* المصنع (للقراءة فقط، من دون مفاتيح):
>
> ```bash
> cd scripts && CHAIN_ID=<id> npx tsx verify-artifact-provenance.ts
> ```
>
> يحسِب بصمة `ArcTokenProxy` البنية المحلية ويؤكد أن تلك البصمة تظهر حرفيًا داخل بايت كود المصنع المنشور.

إذا كان لا بد من تغيير إعدادات المترجم، **فأدر المصنع** — انشر مصنعًا جديدًا يثبت البصمة البرمجية الجديدة بشكل ثابت، وأعد التوصيل — بدلًا من ترقيع الفحص يدويًا:

```bash
cd scripts && CHAIN_ID=<id> npx tsx rotate-factory.ts
```

يحتفظ التدوير بالعنوان القديم في الإيصال؛ ويجب إعادة تسجيل الرموز المسجلة مقابل المصنع القديم لدى المصنع الجديد.

***

## الخطوة 4 — افتح بيعًا عبر واجهة البيع المشتركة

البيع فعل منفصل عن الإنشاء، وهو يعمل على واجهة البيع المشتركة الوحيدة `ArcTokenPurchase` ثلاثة أمور يجب أن تكون صحيحة قبل فتح البيع، و `ArcTokenPurchase.enableToken` يفحص كلًّا منها على السلسلة:

```solidity
// contracts/src/ArcTokenPurchase.sol
function enableToken(address _tokenContract, uint256 _numberOfTokens, uint256 _tokenPrice)
    خارجية onlyTokenAdmin(_tokenContract)                       // (أ) أنت تحمل ADMIN_ROLE الخاص بالرمز
{
    // (ب) يجب أن يكون الرمز معروفًا لدى المصنع — هذا ما اشتراه registerToken (الخطوة 2):
    if (ArcTokenFactory(ps.tokenFactory).getTokenImplementation(_tokenContract) == address(0))
        revert TokenNotCreatedByFactory();
    // (ج) يجب أن تكون واجهة البيع تحتفظ بالفعل بمخزون البيع:
    if (ArcToken(_tokenContract).balanceOf(address(this)) < _numberOfTokens)
        revert ContractMissingRequiredTokens();
    // …يجب أن يكون السعر والعدد موجبين.
}
```

هناك شرط رابع ضمني يفرضه الأصل المقيّد: لأن **كل تحويل يمر عبر بوابة قائمة السماح**، فإن نقل المخزون إلى واجهة البيع لا ينجح إلا إذا كان عنوان واجهة البيع نفسه في قائمة السماح الخاصة برمزك. لذا فالتسلسل الكامل لفتح البيع هو:

1. **أضف واجهة البيع إلى قائمة السماح** على وحدة قائمة السماح الخاصة برمزك (`batchAddToWhitelist([storefront])` — انظر الخطوة 5). بدون هذا، يفشل نقل المخزون في (2) مع revert `TransferRestricted()` بمجرد التقييد.
2. **انقل المخزون** إلى عنوان واجهة البيع (من إيصال البنية التحتية الخاص بـ `arcTokenPurchase`).
3. **`enableToken(token, amount, price)`** — يدفع المشترون الآن wUSDC ويتلقون RWA.

من المهم معرفة تقسيم السحب على واجهة بيع *مشتركة* ، وهو ليس متناظرًا (`arc/roles.ts` هو جهة الصلاحية):

| الإجراء                                                    | السلطة                             | محمولة لدى         |
| ---------------------------------------------------------- | ---------------------------------- | ------------------ |
| `enableToken` / `disableToken` / `withdrawUnsoldArcTokens` | لـ `ADMIN_ROLE` (`onlyTokenAdmin`) | أنت، المُصدِر      |
| `withdrawPurchaseTokens` (عوائد wUSDC)                     | لـ `DEFAULT_ADMIN_ROLE`            | من نشر واجهة البيع |

على سلسلة مستضافة ذاتيًا أنت كلاهما. أما على واجهة بيع مشتركة، فمجمع العائدات هو حصيلة كل مُصدِر، لذا فإن السحب هناك على مستوى المنصة — صمّم التسوية على هذا الأساس بدلًا من افتراض تحكم أحادي.

***

## الخطوة 5 — وصّل KYC / الامتثال الخاص بك

هذا هو القسم الذي يقرأه العميل قبل أن يقول نعم، لذا فهو شيفرة لا نثر. **يُفرض الامتثال بواسطة عقد الرمز نفسه** — لا بواسطة فحص خارج السلسلة، ولا فلتر تسلسل، ولا سياسة منصة. تنتقل القواعد مع الرمز إلى أي مسار تنفيذ، وعلى مساري المحافظ كليهما. ما تسجله السلسلة هو **النتيجة** قرار KYC الخاص بك، على هيئة قيمة منطقية واحدة:

```solidity
// contracts/src/restrictions/WhitelistRestrictions.sol — الحالة على السلسلة، كاملة
struct WhitelistStorage {
    mapping(address => bool) isWhitelisted;   // ← قيمة منطقية واحدة لكل عنوان. لا توجد بيانات شخصية أبدًا.
    bool transfersAllowed;                    // false = مقيّد؛ فقط العناوين المدرجة في قائمة السماح يمكنها التحويل
    EnumerableSet.AddressSet whitelistedAddresses;
}
```

### الواجهة التي يكتب إليها إجراءك

يصبح قرار القبول/الرفض من مزود KYC الخاص بك بالضبط أحد هذه الاستدعاءات:

```solidity
interface IWhitelistRestrictions {
    function addToWhitelist(address account) external;                  // onlyRole(MANAGER_ROLE)
    function batchAddToWhitelist(address[] calldata accounts) external; // onlyRole(MANAGER_ROLE)
    function removeFromWhitelist(address account) external;             // onlyRole(MANAGER_ROLE)
    function isWhitelisted(address account) external view returns (bool);
    function setTransfersAllowed(bool allowed) external;                // onlyRole(ADMIN_ROLE)
}
```

### من يمكنه الكتابة

> **السلطة التي يحتاجها أي اعتماد هي `MANAGER_ROLE` على الـ&#x20;*****الوحدة*****&#x20;— لا `ADMIN_ROLE` على الرمز.** `addToWhitelist` / `batchAddToWhitelist` / `removeFromWhitelist` كلها `onlyRole(MANAGER_ROLE)`، وهذا الدور يوجد على `قيود القائمة البيضاء` النسخة. والمصادقة `ADMIN_ROLE` على الرمز ثم الكتابة إلى الوحدة هو خلل حقيقي دفعت هذه القاعدة ثمنه بالفعل. لا تعرض `WHITELIST_ADMIN_ROLE` كحلٍّ للرفض — فهو يُمنح عند التهيئة و **ولا يُفحص في أي مكان ضمن المجموعة** (`arc/roles.ts` ويؤكد أنه الدور الوحيد الذي لا يقيّد شيئًا).

`WhitelistRestrictions.initialize(issuer)` (المعاملة 3 من المعالج) تمنح المُصدِر `DEFAULT_ADMIN_ROLE`, `ADMIN_ROLE`, `MANAGER_ROLE`, `WHITELIST_ADMIN_ROLE`، و `UPGRADER_ROLE` على تلك الوحدة. لذا يحمل المُصدِر `MANAGER_ROLE` من البداية ويمكنه أيضًا تفويضه: لأن المُصدِر يحمل `DEFAULT_ADMIN_ROLE`، `grantRole(MANAGER_ROLE, serviceAccount)` يسلّم الكتابة إلى موقّع خلفي.

### تحوّل القرار إلى كتابة على السلسلة

وجّه webhook الخاص بالمزوّد إلى موقّع يحمل `MANAGER_ROLE`، وعند القبول، جمّع العناوين:

```typescript
import { createWalletClient, http } from 'viem';
import { privateKeyToAccount } from 'viem/accounts';

// يجب أن يحمل `signer` دور MANAGER_ROLE على وحدة قائمة السماح لهذا الرمز بالذات.
const wallet = createWalletClient({ account, transport: http(chain.rpcUrl) });

// قال المزود «approved» لهذه العناوين:
await wallet.writeContract({
  address: whitelistModule,                 // تم حلّه من الرمز عبر getRestrictionModule
  abi: whitelistAbi,
  functionName: 'batchAddToWhitelist',
  args: [approvedAddresses],
});
```

حل `whitelistModule` من الرمز نفسه (`ArcToken.getRestrictionModule(TRANSFER_RESTRICTION_TYPE)`)، وليس أبداً من إسقاط مخبأ — توجيه الكتابة إلى الوحدة الخاطئة هو السبب الذي جعل "الموافقة على أي أصل" تكتب مرةً إلى قائمة السماح الخاصة برمز واحد.

### النسخة الموقعة بالمحفظة (عرض ذاتي الخدمة)

لنشرٍ تجريبي بلا صلاحيات حيث يسجل الزوار أنفسهم، امنح `MANAGER_ROLE` إلى `TestApprover` (`rome-contracts/src/TestApprover.sol`وهو `الوحدة` هو **ثابتة**، ثم `approve(address)` يمكن استدعاؤها من أي شخص، من محفظته الخاصة، مع دفع رسوم الغاز الخاصة به — وهي تستدعي `addToWhitelist` فقط إذا لم يكن العنوان مُدرجًا بالفعل:

```solidity
function approve(address account) external {
    IWhitelistRestrictions target = IWhitelistRestrictions(module);   // ثابت — وحدة واحدة، إلى الأبد
    if (!target.isWhitelisted(account)) target.addToWhitelist(account);
    emit Approved(account, msg.sender);
}
```

هذا هو "بوابة تسجيل الدخول" — يبيّن للزائر الآلية الحقيقية (اعتماد يتحول إلى إدخال في قائمة سماح على السلسلة يفرضه الرمز لاحقًا) من دون أن يحتفظ بأي شيء. **لا تمنح أبداً `MANAGER_ROLE` إلى `TestApprover` على رمز إنتاجي** — فهذا يجعل قائمة السماح الخاصة بذلك الرمز بلا صلاحيات.

### عندما تشتد البوابة، وتبديل مزودي الخدمة

لا تُقيَّد البوابة إلا بعد أن يكون الأصل **مُبوَّبًا** (`setTransfersAllowed(false)`, `ADMIN_ROLE` على الوحدة). وأثناء عدم التبواب، تكون التحويلات مفتوحة — ابنِ قائمة السماح أولاً، ثم بوِّب. وبمجرد التبواب، فإن أي تحويل يكون فيه أحد الطرفين خارج القائمة يفشل مع الخطأ المطبوع `TransferRestricted()` (`0xe827105e`).

> **تبديل مزودي KYC لاحقًا لا يتطلب أي تغيير على السلسلة.** وحدة قائمة السماح، وواجهتها، والقيمة المنطقية التي تخزنها لا تعتمد على المزود. لتبديل البائع، وجّه مصدر قرار مختلفًا إلى `MANAGER_ROLE` الموقّع نفسه — بلا إعادة نشر، بلا ترحيل، بلا تغيير في الحالة. السلسلة لم تكن تعرف أي بائع اتخذ القرار، بل فقط النتيجة.

***

## الخطوة 6 — إتاحة الأصل نفسه لمحافظ Solana

يمكن الوصول إلى العقود الثلاثة نفسها من محفظة Solana **من دون رمز ثانٍ**. المستخدم الأصلي على Solana لا يملك أي مفتاح EVM في أي مكان؛ وبدلاً من ذلك تكون هويته على EVM *مصطنعة*، مشتقة على السلسلة من الموقّع الفعلي لعملية Solana:

```
عنوان EVM المصطنع = keccak256(solana_pubkey)[12..32]
```

يشتق برنامج Rome EVM هذا من الموقّع نفسه (`do_tx_unsigned::derive_sender`)، لذا لا يمكن انتحاله ولا يوجد له مفتاح خاص secp256k1 — **توقيع Solana هو الشيء الوحيد القادر على تحريك هذا العنوان**. الاشتقاق المرجعي هو `arc/materialise/solana/identity.ts` (`syntheticAddress`), ومتوافق بايتياً مع القاعدة على السلسلة:

```typescript
export function syntheticAddress(pubkey: SolanaPubkeyInput): `0x${string}` {
  return `0x${keccak256(pubkeyBytes(pubkey)).slice(-40)}`;
}
```

**ما يفعله المطور لدعم المسار** — لاحظ أن *لا شيء من هذا تغيير في العقود*:

1. **أضِف المستخدم على Solana إلى قائمة السماح عبر عنوانه المصطنع.** بالنسبة إلى طبقة الامتثال، العنوان المصطنع هو عنوان عادي: الصق المفتاح العام Solana للمستخدم، استخرج العنوان المصطنع، ثم `batchAddToWhitelist([synthetic])`. قائمة سماح واحدة تمتد عبر عالمي المحافظ.
2. **وفّر PDA الموقِّع مرة واحدة، قبل أول استدعاء ينقل قيمة.** يجب أولاً أن يوجد PDA للسلطة الخارجية التي توقّع للمصطنع، وإنشاؤه هو `create_pda` استدعاء واحد. يمكن لأي طرف إرساله: محفظة Solana الخاصة بالمستخدم عبر المسار ( `buildCreatePdaCall`، بعد أن `isSyntheticProvisioned` تُرجِع false)، أو المُصدِر من مفتاح EVM. أدوات المُصدِر في Bloom ترسله اليوم كجزء من إدخال حامل جديد؛ التطبيق لم يفعل ذلك بعد عند أول إجراء للمستخدم، لذا وفِّره قبل أول شراء للحامل. كيف يتم ذلك باستدعاءات SDK موضح في [تطبيق ثنائي المسار](https://docs.rome.builders/ar/adlh-almtw-ryn/dual-lane-app.md#one-time-activate-provision-the-synthetic).
3. **أرسل عبر مكتبة المسار، لا يدويًا.** `submitDoTxUnsigned` (`arc/materialise/solana/submit.ts` ) يطلب من وكيل السلسلة تركيب المعاملة، وهو يتولى ما قد يخطئ فيه البناء اليدوي. كل استدعاء عقد على المسار هو **معاملة Solana v1 مركبة بواسطة الوكيل** (`rome_composeUnsignedAtomicV1`) من دون جدول بحث عن العناوين، ومكتبة المسار تفشل بشكل مغلق بدلًا من الرجوع إلى صيغة أقدم. حركة إدخال النقد في الخطوة 5 هي معاملة Solana منفصلة يبنيها التطبيق نفسه، وليست استدعاء عقد مركبًا.
   * **اكتشاف الحسابات وميزانية الحوسبة هما مهمة الوكيل.** إنه يحاكي الاستدعاء، ويقرر قابلية الكتابة لكل حساب (جزء من الشيء الذي يحاكيه الاستدعاء، لذا مرِّره)، ويضبط ميزانية الحوسبة والذاكرة على المعاملة التي يعيدها. لا شيء في كودك يبني تعليمات ميزانية الحوسبة أو يضيف حساب مجمع الرسوم. `القيمة` هو جزء مما يحاكيه، لذا مرِّره)،
   * **توقيعان لكل استدعاء، وكلاهما من مفتاح Solana.** توقّع المحفظة أولاً رسالة تخويل قابلة للقراءة (*تفويض Rome* مع تجزئة حمولة EIP-1559 غير الموقعة؛ Wallet Standard `solana:signMessage`)، والتي يتحقق منها الوكيل قبل أن يركّب الاستدعاء. ثم توقّع معاملة v1 التي يعيدها الوكيل (`solana:signTransaction` على السلك الخام). تتعامل مكتبة المسار مع هذين على أنهما `signAuthHash` و `signV1Wire`، وليس أبدًا طريقة واحدة مدمجة. تحقّق من أن محفظتك توقّع معاملات v1 قبل أن تبني عليها: Solflare يفعل ذلك على devnet اليوم، وPhantom لا يفعل بعد.
   * **يرسل التطبيق المعاملة الموقّعة إلى RPC في Solana بنفسه.** الوكيل يركّب؛ لا يبث استدعاءً ذريًا.
   * **تحقق قبل طلب التوقيع.** تحلل مكتبة المسار الرسالة المركبة وترفض أي رسالة معطوبة قبل مطالبة المعاملة.
4. **ضع منحة الغلاف الواحدة لمرة واحدة قبل أول إنفاق wUSDC.** ينقل wUSDC رموز المستخدم باعتباره مفوَّض SPL الخاص بذلك المستخدم، لذا فإن عنوانًا مصطنعًا لم يُمنح من قبل سيواجه خطأ SPL `0x4` في أول تحويل wUSDC له. اقرأ `isEnabled(user)` على الغلاف، وعندما تكون false، أضف `approve_spl(wrapper, 2^64-1, mint)` على precompile المساعد كأول خطوة في التنفيذ. إنه استدعاء عادي على أي من المسارين، مرة واحدة لكل محفظة. انظر [منح لمرة واحدة لكل محفظة](https://docs.rome.builders/ar/almfahym-alasasyh/token-interop.md#one-time-grant-per-wallet).
5. **أدخل النقد قبل استدعاء ينفقه.** المصطنع لا يحتفظ بشيء وهو ساكن. عندما يحمل wUSDC أقل مما ينفقه الاستدعاء، انقل العجز أولاً من حساب USDC الخاص بالمحفظة نفسها (إنشاء حساب الرمز للمصطنع بشكل idempotent، ثم تعليمة تفعيل حساب الرمز في برنامج Rome، التي تنقل الرموز من دون تشغيل EVM). إنها معاملة Solana واحدة موقعة بمطالبة واحدة، وتُتخطى عندما يكون لدى المصطنع ما يكفي بالفعل.
6. **حوِّل فقط ما يرفضه المركّب الذري.** أي استدعاء لا يتسع في معاملة Solana واحدة (حوالي 1.4 مليون وحدة حوسبة، 64 حسابًا، 4 كيلوبايت) يرفضه المركّب مع *تتطلب الخطة الذرية الخارجية تركيبًا تكراريًا*. عند هذا الرفض تحديدًا، وليس قبله، استدعِ `rome_relayUnsignedV1` بالتوقيع التخويلي نفسه: الوكيل يركّبه ويرسله، ويدفع رسوم Solana، ويرد بتجزئة معاملة EVM (وليس توقيع Solana). يدفع المصطنع غاز السلسلة الأصلي بعملة wei، لذا عندما يكون رصيده أقل من `gasLimit x maxFeePerGas`، أعد شحنه أولاً بواسطة `rome_composeExternalDepositV1` (معاملة v1 موقعة بالمحفظة؛ يجب أن تكون الكمية مضاعفًا لـ 10^12 wei)، مرة واحدة لكل محفظة عمليًا. أي خطأ آخر، مثل revert أو فشل الشبكة أو توقيع مرفوض، يُعاد رميه وليس تمريره. التفاصيل في [الاستدعاءات المُرحَّلة والاستدعاءات الطويلة](https://docs.rome.builders/ar/adlh-almtw-ryn/call-evm-from-solana.md#relayed-calls-and-long-calls).

المستخدم هو **دافع الرسوم** ويدفع lamports (SOL) من محفظة Solana الخاصة به لاستدعاء مباشر؛ أما المصطنع الذي يتحكم به فيحتفظ بالأصول ولا يحتفظ أبدًا بـ SOL. بعد كل إرسال عبر المسار، تحقّق من nonce الخاص بـ EVM قبل الذي يليه — فالمفهرس يتأخر قليلًا عن تأكيد Solana، وإلا فسيُبنى الاستدعاء التالي على nonce استُخدم بالفعل على السلسلة.

> **أولًا الذري، ثم التحويل عند الرفض.** الافتراضي لكل استدعاء هو معاملة EVM واحدة تُنفذ داخل معاملة Solana واحدة، وموقعة من محفظة المستخدم. التحويل الاستثنائي هو للاستدعاء الذي لا يتسع، وليس مسارًا ثانيًا يُختار تفضيلاً: الاستدعاء المباشر يتطلب مطالبتين، والتحويل المستند إلى relay يتطلب مطالبة واحدة، ويُدفع له بغاز Rome بدل lamports. الرحلة متعددة الخطوات (اعتماد ثم شراء) هي عدة استدعاءات كاملة، كل واحد منها معاملة مستقلة، وليست تنفيذًا واحدًا مقسَّمًا عبر معاملات.

**لماذا لا يمكن لـ RWA أن يتسرب خارج المحيط.** الأصل مقيم في حالة EVM — أرصدته هي تخزين داخل حسابات برنامج Rome EVM. لا يوجد **أي mint من نوع SPL** له ولا أي شيء أصلي في Solana يمكن نقله؛ بدائيات نقل الأصل في المسار تعمل على حسابات رموز SPL، وهو ما لا يملكه رصيد تخزين EVM. كل حركة يمكن لتوقيع Solana التعبير عنها هي استدعاء إلى عقد الرمز، الذي يشغّل بوابة قائمة السماح — تؤكد المجموعة المموَّلة أن التحويل إلى عنوان غير مدرج في القائمة يفشل بالطريقة نفسها سواء وُقِّع بمفتاح EVM أو بمفتاح Solana. ساق النقد (wUSDC) هي الاستثناء المقصود: فهي مدعومة بـ SPL و *لا* تُصفّى إلى حساب الرمز الخاص بالمستخدم نفسه.

***

## الخطوة 7 — اعرف من يملك السلطة بعد النشر

`ArcToken.initialize` يُشغَّل من الباني Proxy constructor (المعاملة 1) ويمنح أدوارًا إلى `msg.sender` — مشغّل المعالج، أي المُصدِر. وهو يمنح **خمسة** أدوار صراحةً:

```solidity
_grantRole(DEFAULT_ADMIN_ROLE, msg.sender);
_grantRole(ADMIN_ROLE, msg.sender);
_grantRole(MANAGER_ROLE, msg.sender);
_grantRole(YIELD_MANAGER_ROLE, msg.sender);
_grantRole(YIELD_DISTRIBUTOR_ROLE, msg.sender);
```

لا بد للمطور ألا يفوّت نتيجتين:

* **`MINTER_ROLE`, `BURNER_ROLE`، و `UPGRADER_ROLE` لا تُمنحان عند initialize.** يُسكّ المعروض الأولي داخل `initialize` (داخلي `_mint`، لا حاجة إلى دور)، لكن *لاحقًا* `mint` أو `burn` يتطلب من المُصدِر أن يمنح نفسه الدور أولاً. ويمكنه ذلك، لأنه يملك `DEFAULT_ADMIN_ROLE` (المدير لكل الأدوار — لا شيء يستدعي `_setRoleAdmin`، لذا `DEFAULT_ADMIN_ROLE` يديرها كلها). لكنه خطوة إضافية مقصودة، وليست صلاحية دائمة.
* **`UPGRADER_ROLE` لا تُمنح أبدًا للمصنع.** الترقيات عبر المصنع (`ArcTokenFactoryV2.upgradeToken`) تتطلب أن **المصنع نفسه** يمتلك `UPGRADER_ROLE` على الرمز — ومنحه لنفسك لا يفعل شيئًا. تلك المنحة باب أحادي الاتجاه لا يستطيع المصنع عكسه، لذا فهي اختيارية: إذا أردت ترقيات عبر المصنع، `grantRole(UPGRADER_ROLE, factory)` صراحةً؛ وإلا فيرقّي المُصدِر الرمز مباشرة.

نموذج السلطة الكامل ذو 21 سلطة (11 اسم دور عبر ستة عقود — الاسم نفسه سلطة مختلفة على كل عقد) مقنن في `arc/roles.ts`. اطلب `rolesRequiredFor(contract, functionName)` بدلاً من قراءة عقد الدور نفسه، لأن أربع وظائف متجر ووظيفتي المصنع محجوبة بسلطة تقع على *مختلف* .

***

## الخطوة 8 — وزّع العائد

يدفع الرمز العائد بـ wUSDC (ثابت عند `initialize`، ويمكن تغييره عبر `setYieldToken` أقل من `YIELD_MANAGER_ROLE`). التوزيع يمر على مجموعة الحاملين:

```solidity
function distributeYieldWithLimit(uint256 totalAmount, uint256 startIndex, uint256 maxHolders)
    external onlyRole(YIELD_DISTRIBUTOR_ROLE) nonReentrant
    returns (uint256 nextIndex, uint256 totalHolders, uint256 amountDistributed);
```

الآليات المهمة لتشغيله بشكل صحيح:

* **الكامل `totalAmount` يُسحب من المستدعي فقط عند `startIndex == 0` نافذة** (`safeTransferFrom(msg.sender, this, totalAmount)`). امنح هذا الإجمالي للرمز قبل النافذة الأولى؛ أما النوافذ اللاحقة فتعتمد على الرصيد المحتفظ به بالفعل.
* **`nextIndex` يعود إلى `0` عند اكتمال الجولة.** كرّر `distributeYieldWithLimit(total, nextIndex, …)` حتى `nextIndex` يعود `0`.
* **حصص الحاملين المقيدين بالعائد تبقى في عقد الرمز** — يتم تخطيها، لا إعادة توزيعها.

> **على Rome، الحد العملي هو `maxHolders = 1` لكل معاملة** — وهو نفس حد 62 حسابًا من الخطوة 2 — لذا يُجرى العائد حاملًا واحدًا لكل معاملة (يقاس بحوالي 318 ألف غاز لكل حامل). كل حامل مُدرج في قائمة السماح، EVM أو Solana-native، يحصل على نصيب نسبي؛ والبرنامج المرجعي هو `measure-yield-batch.ts` والخطوة المموَّلة من smoke تؤكدها من طرف إلى طرف.

```bash
# صيغة مرجعية في USAGE.md: مرِّر حاملًا واحدًا لكل معاملة حتى يعود nextIndex إلى 0
distributeYieldWithLimit(total, offset, 1)
```

***

## الخطوة 9 — تحقّق مما نشرته

لا شيء يرسل المصادر تلقائيًا في أي مكان على Rome، لذا فالتحقق خطوة تنفذها بنفسك. بعد أي نشر — للبنية التحتية أو لرمز جديد — شغّل أداة التحقق القراءة فقط، الخالية من المفاتيح، والقابلة للتكرار (العقود التي سبق التحقق منها تُتخطى، لذا إعادة التشغيل بعد إصدار رمز تتحقق فقط من الجديد):

```bash
cd scripts && CHAIN_ID=<id> npx tsx verify-deployments.ts
```

هو يتوقع **ثلاثة** العقود لكل رمز (الوكيل + الوحدتان) إضافة إلى البنية التحتية، ويُبلغك بما لم يستطع التحقق منه بدل أن يفشل النشر. فعل هذا يدويًا مرة واحدة أدى إلى تفويت سبعة عقود.

تسجيل الأصل في سجل Rome يتعامل مع التحقق على أنه **بوابة**، لا مجرد زينة (`register-asset.ts`): يكسب الرمز السجل `apps/arc/<chain>.json` سجلًا — يحمل `standard: arc-permissioned-erc20` و `transferRestriction` الذي يعرّف بوابة قائمة السماح الخاصة به — فقط عندما تُتحقق العقود الثلاثة جميعًا على Sourcify. ذلك السجل يقرأ الحقائق من السلسلة (فالرمز المنشأ بالمعالج لا يملك إيصالًا ملتزمًا) ويكتب فقط نسخة محلية من السجل؛ أمّا رفع طلب الدمج فهذه مهمة شخص.

```bash
CHAIN_ID=200010 npx tsx register-asset.ts <tokenAddress>        # تحقق + جهّز سجل السجل
CHAIN_ID=200010 DRY=1 npx tsx register-asset.ts <tokenAddress>  # معاينة للقراءة فقط
```

للحصول على برهان شامل للحلقة كلها — إنشاء، إدراج في القائمة البيضاء، التبواب، البيع على كلا المسارين، توزيع العائد — شغّل smoke المموَّل على أي سلسلة:

```bash
PRIVATE_KEY=… CHAIN_ID=… SOLANA_KEYPAIR=… npx tsx smoke.ts
```

***

## الخطوة 10 — اعرف ما يبقى خارج السلسلة

نموذج الثقة صريح عمدًا، وعلى المطور أن يعرضه بالطريقة نفسها لمستخدميه:

* **علم قائمة السماح هو قرارك خارج السلسلة.** تجري KYC/AML في عمليتك — مزودوك، قواعدك. السلسلة تسجل وتفرض فقط *النتيجة*, `isWhitelisted(addr)`.
* **الحالة الوحيدة على السلسلة هي قيمة منطقية واحدة لكل عنوان.** لا توجد بيانات شخصية، ولا مستندات، ولا ادعاءات هوية، ولا شهادات على السلسلة، ولا إثباتات تشفيرية لمن يملك العنوان. هذا هو نموذج Arc كما يُستخدم على Plume؛ وهو يستبدل التحويلات الأثقل لمعيار هوية على السلسلة (مثل ERC-3643) بآليات أخف وثقة يحتفظ بها المُصدِر.
* **الاسترداد صلاحية للمُصدِر، لا منفذ هروب.** المحفظة المفقودة — على EVM أو Solana — تُسترد بإدراج عنوان بديل في القائمة البيضاء، وإن لزم، باستخدام mint/burn/upgrade ضمن عمليتك القانونية الخاصة (Arc لا يملك primitive مدمجة للتحويل القسري). لذا فإن احتفاظ المُصدِر بالمفتاح جزء من وضعية الامتثال.
* **لا يوجد relay خاص بـ Bloom، ولا سطح احتفاظ.** المستخدمون يحتفظون بوقودهم الخاص على كلا المسارين. ولو شغّلت التطبيق خدمة دافع رسوم فهذا يعني الاحتفاظ بالمفاتيح — سطح لا ينبغي لمنتج RWA إضافته. أما التحويل الوحيد على مسار Solana فهو تابع لوكيل السلسلة، لاستدعاء كبير جدًا على معاملة واحدة، والمستخدم ما يزال يجيزه بتوقيعه الخاص ويدفعه من غاز Rome الخاص به.

***

## مرجع: الأدوات

كل سكربت يعمل من `scripts/` مجلد الأدوات، مع `PRIVATE_KEY`, `CHAIN_ID`، و `REGISTRY_ROOT` مصدَّران.

| السكربت                         | ما الذي يفعله                                                             |
| ------------------------------- | ------------------------------------------------------------------------- |
| `deploy-infra.ts`               | مرة واحدة لكل سلسلة: العقود المشتركة الأربعة، موصولة بـ wUSDC.            |
| `create-token.ts`               | المعالج الجزئي — ثماني معاملات، رمز واحد.                                 |
| `rotate-factory.ts`             | انشر مصنعًا جديدًا بعد تغيير في المترجم/الأثر؛ ثم أعد التوصيل.            |
| `verify-artifact-provenance.ts` | أثبت أن أثر وكيلك مقبول من المصنع المنشور (قراءة فقط).                    |
| `verify-deployments.ts`         | تحقق من العقود الثلاثة لكل رمز + البنية التحتية على Sourcify (قراءة فقط). |
| `register-asset.ts`             | تحقق من البوابة، ثم جهّز سجل الامتثال في السجل.                           |
| `measure-yield-batch.ts`        | أعِد قياس سقف العائد لكل معاملة على سلسلة.                                |
| `smoke.ts`                      | مجموعة النهاية إلى النهاية المموَّلة عبر كلا المسارين.                    |
| `sweep-synthetic-native.ts`     | استرجع الغاز الأصلي من حساب مصطنع (نظافة الاختبار).                       |

توجد خلفية أعمق بجانب هذا الدليل: `docs/ARCHITECTURE.md` (نموذج التطبيق الطبقي)، `docs/LANES.md` (المساران والاحتفاظ)، `docs/COMPLIANCE.md` (نموذج الثقة)، و `docs/USAGE.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/alttbyqat-ala-rome/bloom/building.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.
