> 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/ru/prilozheniya-v-rome/bloom/building.md).

# Построение на Bloom

Это руководство отвечает на один вопрос: **как разработчик делает это самостоятельно?** Возьмите контракт реального актива на Solidity, разверните его в цепочке Rome как разрешённый токен, откройте его для кошельков Solana, а также для EVM-кошельков без второго токена и подключите собственное решение KYC/комплаенса.

Аудитория — разработчик, который оценивает или внедряет этот подход. На протяжении всего материала Bloom служит практическим примером — его живой актив **ARCV ("Mineral Vault I")** на Hadrian (`200010`) — это реальный пример каждого шага ниже, а его receipt развертывания (`deployments/200010.tokens/ARCV.json`) фиксирует ровно три контракта и восемь транзакций, которые создаёт этот метод.

Здесь ничего не изменяет контракты актива. Bloom использует фреймворк Arc от Plume **без изменений** (вендоризованное дерево в `contracts/`, побайтно идентичное `plumenetwork/contracts` по закреплению в `NOTICE`); единственный контракт на стороне Rome — это `ArcTokenFactoryV2`, который добавляет одну функцию. Работа заключается в том, *как* как вы развёртываете *как* и управляете контрактами — а не в их изменении.

> **Метод в общих чертах.** Разрешённый токен — это **три** развёрнутых контракта. Он развёртывается **поэтапно** — по одному контракту на транзакцию — потому что вызов фабрики одной транзакцией превышает лимит аккаунтов Rome на транзакцию. Его прокси должны создаваться из **артефактов с закреплённым происхождением** или регистрация в блокчейне завершится с ошибкой по умолчанию. Комплаенс — это одно **булево значение на адрес**, записываемое тем, кого авторизует ваш KYC-процесс. И одно и то же развёртывание доступно из кошелька Solana через **синтетического отправителя** , выводимого в блокчейне — без второго токена и без второго allowlist.

## Предварительные требования

> **Перед началом.** Инструменты эмитента, которые использует это руководство, пока не опубликованы. Речь идёт о скриптах (`deploy-infra.ts`, `create-token.ts` и остальных), деревьях `contracts/` и `rome-contracts/` и receipts развертывания, которые они создают. Эмитенты получают эти инструменты при онбординге в Rome. До этого воспринимайте руководство как описание метода и того, что делает каждый скрипт.

Эталонные инструменты находятся в каталоге `scripts/` (выдаётся при онбординге; установите зависимости с помощью `npm install`). Каждая команда получает сведения о цепочке из registry, а не жёстко задаёт их, поэтому перенос на другую цепочку Rome — это изменение окружения, а не кода:

```bash
export PRIVATE_KEY=…       # ключ финансируемого деплойера/эмитента в целевой цепочке
export CHAIN_ID=200010     # выбирает цепочку
export REGISTRY_ROOT=…     # checkout реестра цепочек Rome
# Потоки Solana-lane также требуют:
export SOLANA_KEYPAIR=…    # путь к JSON-файлу финансируемой пары ключей Solana (payer комиссии)
```

Газ в цепочках 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 — это не один контракт. Это **три развёрнутых контракта**, плюс четыре общих контракта, которые ops развёртывает один раз на цепочку, а каждый эмитент использует повторно.

**Три контракта на один токен** — один актив владеет именно этими:

| Контракт                     | Исходный код                                                | Что это                                                                                                                  |
| ---------------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `ArcTokenProxy`              | `contracts/src/proxy/ArcTokenProxy.sol`                     | Сам токен — UUPS-прокси, указывающий на общий `ArcToken` implementation. Балансы, держатели и роли находятся здесь.      |
| `WhitelistRestrictions`      | `contracts/src/restrictions/WhitelistRestrictions.sol`      | Модуль allowlist. Одно булево значение на адрес; применяется при каждой передаче, пока актив находится под ограничением. |
| `YieldBlacklistRestrictions` | `contracts/src/restrictions/YieldBlacklistRestrictions.sol` | Модуль доходности. Исключает адреса из распределений дохода, не затрагивая их владение.                                  |

**Четыре общих контракта, по одному на цепочку** (развёрнутые `deploy-infra.ts`):

| Контракт                    | Роль                                                                             |
| --------------------------- | -------------------------------------------------------------------------------- |
| `RestrictionsRouter`        | Реестр типов модулей — привязка цепочки, задаётся один раз ops.                  |
| `ArcTokenFactoryV2`         | Регистрация + канонический codehash прокси (шаги 2–3).                           |
| `ArcToken` (implementation) | Общая, повторно используемая логика актива, к которой проксируется каждый токен. |
| `ArcTokenPurchase`          | Один storefront, общий для каждого токена и каждого эмитента (шаг 4).            |
| wUSDC                       | Денежная сторона — валюта доходности и валюта покупки-продажи.                   |

Ограничение переводов и ограничение доходности — это **намеренно отдельные модули**: держателю может быть запрещён доход при сохранении актива, и именно так на практике работают санкции и судебные решения.

Этот факт о «трёх контрактах» критически важен для верификации. `verify-deployments.ts` и `register-asset.ts` оба ожидают, что токен разрешится в три развёрнутых контракта — ручная проверка одного токена однажды упустила семь из них в одной цепочке (все модули доходности и три модуля whitelist).

Жизненный цикл состоит из трёх фаз и одних ворот в одну сторону:

```
draft     прокси активен, модуль не подключён — ничто не блокирует перевод
  ↓
ungated   модуль подключён, transfersAllowed = true   (WhitelistRestrictions.initialize устанавливает это)
  ↓  выпуск эмиссии, построение allowlist               [обратимо]
gated     setTransfersAllowed(false)                [ВОРOТА В ОДНУ СТОРОНУ — эмиссия становится окончательной]
```

Блокировка в одну сторону действует для эмиссии, потому что mint и burn проходят `address(0)` в качестве второй стороны, а `address(0)` никогда не может быть добавлен в allowlist — поэтому после включения блокировки новую эмиссию уже невозможно создать. Это и есть гарантия, которую разрешённый актив даёт своим держателям.

***

## Шаг 2 — Развёртывание поэтапно, никогда не одной транзакцией

Arc поставляется с одноразовым `createToken` который разворачивает прокси и оба модуля и связывает их одним вызовом. **На Rome использовать его нельзя.** Эта транзакция требует **77 блокировок аккаунтов Solana**, а лимит Rome на одну транзакцию составляет **62 блокировки**. Она никогда не поместится — ни при какой настройке, ни после оптимизации.

Поэтому развертывание **поэтапно**: каждый контракт в своей транзакции, а токен получает статус, эквивалентный фабричному, через `ArcTokenFactoryV2.registerToken` вместо монолитного `createToken`. Это wizard создания, и именно так консоль эмитента выполняет шаги один за другим:

![wizard создания](https://1351373662-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
# один раз на цепочку (ops, не на каждый токен) — разворачивает четыре общих контракта
npx tsx deploy-infra.ts

# на каждый токен — wizard, воспроизведённый как скрипт
NAME="Mineral Vault I" SYMBOL=ARCV SUPPLY=1000000 DECIMALS=6 npx tsx create-token.ts
```

Эмитент (`PRIVATE_KEY`) подписывает каждую транзакцию и в итоге владеет ролями токена (`ArcToken.initialize` grant to `msg.sender` — см. шаг 7). Регистрация (tx 8) — это то, что открывает у storefront `enableToken` и любое обновление через фабрику.

> **Не пытайтесь «оптимизировать» это обратно в монолит.** Объединение этих вызовов в одну транзакцию ради экономии round-trips снова приведёт к ровно тому переполнению по 62 блокировкам, которого поэтапный путь и призван избежать. Тот же лимит объясняет, почему распределение дохода проходит по одному держателю на транзакцию (шаг 8). Если вызов завершается ошибкой `Too many accounts: N > 62`, значит одна транзакция затрагивает слишком много аккаунтов — разбейте её, а не настраивайте.

***

## Шаг 3 — Разворачивайте прокси только из артефактов с закреплённым происхождением

`registerToken` — это граница безопасности, которая делает поэтапные развёртывания безопасными. Он принимает только токен, чей **runtime codehash совпадает с каноническим `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();
    // …implementation должна быть в allowlist фабрики, msg.sender должен владеть
    //    ADMIN_ROLE токена, и токен ещё не должен быть зарегистрирован.
}
```

Поскольку этот codehash **неизменяемый**, прокси, созданный из любого другого артефакта, завершится с ошибкой по умолчанию `ProxyCodehashUnknown`. Из этого следуют два правила, и оба обеспечиваются CI и жёсткими правилами в `CLAUDE.md`:

1. **Прокси токенов ДОЛЖНЫ развёртываться из `rome-contracts/out`** — никогда из `contracts/out`, никогда из другой сборки. Именно эту компиляцию закрепляет канонический codehash фабрики.
2. **`bytecode_hash = "none"` и `cbor_metadata = false`** в `rome-contracts/foundry.toml` имеют критическое значение. При включённых метаданных `ArcTokenProxy` runtime *встроенный* в фабрику (`type().runtimeCode`) содержит другой хвост CBOR/IPFS, чем отдельный артефакт `out/` из которого wizard выполняет развёртывание — поэтому on-chain `registerToken` завершается с revert, тогда как **все встроенные в исходники тесты Foundry проходят** (Foundry встраивает обе копии, поэтому не видит расхождение). `rome-contracts/test/ArtifactProvenance.t.sol` фиксирует это свойство; именно прогон с финансированием изначально выявил проблему.

> **Зелёный suite внутри исходников не доказывает происхождение.** Перед выпуском образа и после ЛЮБОГО изменения настроек компилятора докажите это свойство относительно *развёрнутой* фабрики (только чтение, без ключей):
>
> ```bash
> cd scripts && CHAIN_ID=<id> npx tsx verify-artifact-provenance.ts
> ```
>
> Он хэширует ваш локальный `ArcTokenProxy` артефакт и проверяет, что этот хэш в точности присутствует внутри байткода развёрнутой фабрики.

Если настройки компилятора нужно изменить, **ротация фабрики** — разверните новую, чья неизменяемая переменная закрепляет новый codehash, и переподключите всё — вместо того чтобы вручную править проверку:

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

Ротация сохраняет старый адрес в receipt; токены, зарегистрированные через старую фабрику, должны быть зарегистрированы заново через новую.

***

## Шаг 4 — Откройте продажу через общий storefront

Продажа — это отдельное действие от создания, и оно выполняется через единственный общий `ArcTokenPurchase` storefront. Перед открытием продажи должны быть выполнены три условия, и `ArcTokenPurchase.enableToken` проверяет каждое из них в блокчейне:

```solidity
// contracts/src/ArcTokenPurchase.sol
function enableToken(address _tokenContract, uint256 _numberOfTokens, uint256 _tokenPrice)
    external onlyTokenAdmin(_tokenContract)                       // (a) вы владеете ADMIN_ROLE токена
{
    // (b) токен должен быть известен фабрике — именно это и покупает registerToken (шаг 2):
    if (ArcTokenFactory(ps.tokenFactory).getTokenImplementation(_tokenContract) == address(0))
        revert TokenNotCreatedByFactory();
    // (c) storefront уже должен хранить запас для продажи:
    if (ArcToken(_tokenContract).balanceOf(address(this)) < _numberOfTokens)
        revert ContractMissingRequiredTokens();
    // …цена и количество должны быть положительными.
}
```

Есть и четвёртое, неявное требование, которое навязывает gated-актив: поскольку **каждая передача проходит через gate allowlist**, перемещение запаса в storefront возможно только если адрес storefront сам whitelisted в вашем токене. Итак, полный порядок открытия продажи таков:

1. **Добавьте storefront в whitelist** в модуле whitelist вашего токена (`batchAddToWhitelist([storefront])` — см. шаг 5). Без этого перевод запаса в пункте (2) завершится ошибкой `TransferRestricted()` после включения блокировки.
2. **Переведите запас** на адрес storefront (из receipt инфраструктуры `arcTokenPurchase`).
3. **`enableToken(token, amount, price)`** — покупатели теперь платят wUSDC и получают RWA.

Разделение вывода средств важно понимать на *общем* storefront, и оно несимметрично (`arc/roles.ts` является источником полномочий):

| Действие                                                   | Полномочие                             | Кем удерживается              |
| ---------------------------------------------------------- | -------------------------------------- | ----------------------------- |
| `enableToken` / `disableToken` / `withdrawUnsoldArcTokens` | токена `ADMIN_ROLE` (`onlyTokenAdmin`) | вы, эмитент                   |
| `withdrawPurchaseTokens` (выручка в wUSDC)                 | storefront `DEFAULT_ADMIN_ROLE`        | тем, кто развернул storefront |

В собственной цепочке вы являетесь и тем и другим. В общем storefront пул выручки — это доходы каждого эмитента, поэтому вывод средств осуществляется на уровне платформы — проектируйте расчёты с учётом этого, а не исходя из предположения о единоличном контроле.

***

## Шаг 5 — Подключите собственный KYC / комплаенс

Это раздел, который клиент читает перед тем, как согласиться, поэтому это код, а не проза. **Комплаенс обеспечивается самим контрактом токена** — а не внешней проверкой, фильтром секвенсора или политикой площадки. Правила следуют за токеном в любой путь исполнения, на обоих кошельковых каналах. В блокчейне записывается **результат** результат вашего KYC-решения в виде одного булева значения:

```solidity
// contracts/src/restrictions/WhitelistRestrictions.sol — состояние в блокчейне, полностью
struct WhitelistStorage {
    mapping(address => bool) isWhitelisted;   // ← одно булево значение на адрес. Никаких PII, никогда.
    bool transfersAllowed;                    // false = gated; переводить могут только whitelisted-адреса
    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)`, и эта роль находится на `WhitelistRestrictions` экземпляре. Аутентификация `ADMIN_ROLE` на токене с последующей записью в модуль — это реальный дефект, за который эта кодовая база уже заплатила. Не предлагайте `WHITELIST_ADMIN_ROLE` как исправление отказа — она выдаётся при инициализации и **нигде не проверяется в suite** (`arc/roles.ts` (suite подтверждает, что это единственная роль, которая ничего не блокирует).

`WhitelistRestrictions.initialize(issuer)` (tx 3 wizard) выдаёт эмитенту `DEFAULT_ADMIN_ROLE`, `ADMIN_ROLE`, `MANAGER_ROLE`, `WHITELIST_ADMIN_ROLE`, и `UPGRADER_ROLE` на этом модуле. Таким образом, эмитент по умолчанию владеет `MANAGER_ROLE` и может делегировать её: поскольку эмитент владеет `DEFAULT_ADMIN_ROLE`, `grantRole(MANAGER_ROLE, serviceAccount)` передаёт право записи backend-подписанту.

### Решение, превращающееся в запись в блокчейне

Направьте webhook вашего провайдера на подписанта, который удерживает `MANAGER_ROLE`, и при одобрении выполните пакетную запись адресов:

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

// `signer` должен владеть MANAGER_ROLE в модуле whitelist ЭТОГО токена.
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)`), никогда не из кэшированной проекции — попытка записи в неверный модуль и стала причиной того, что "approve on any asset" однажды записал разрешение в белый список одного токена.

### Вариант с подписью кошельком (самообслуживаемая демонстрация)

Для тестового развёртывания без разрешений, где посетители регистрируются сами, предоставьте `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-native нет нигде EVM-ключа; вместо этого его EVM-идентичность — это *синтетическая*, полученная в блокчейне из фактического подписанта Solana в транзакции:

```
синтетический EVM-адрес = keccak256(solana_pubkey)[12..32]
```

Программа Rome EVM выводит его из самого подписанта (`do_tx_unsigned::derive_sender`), поэтому подделать его невозможно, и секp256k1-частный ключ для него не существует — **подпись 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/ru/rukovodstva-dlya-razrabotchikov/dual-lane-app.md#one-time-activate-provision-the-synthetic).
3. **Отправляйте через библиотеку канала, а не вручную.** `submitDoTxUnsigned` (`arc/materialise/solana/submit.ts`) просит прокси сети собрать транзакцию и решает те проблемы, с которыми вручную собранная транзакция не справляется. Каждый вызов контракта в канале — это **Solana v1-транзакция, собранная прокси** (`rome_composeUnsignedAtomicV1`), без таблицы поиска адресов, а библиотека канала завершает работу с ошибкой вместо отката к старому формату. Операция cash-in на шаге 5 — это отдельная транзакция Solana, которую приложение собирает самостоятельно, а не собранный вызов контракта.
   * **Определение аккаунтов и бюджет вычислений — задача прокси.** Он эмулирует вызов, определяет writable-статус каждого аккаунта ( `value` является частью того, что он эмулирует, так что передавайте его), и задаёт бюджет вычислений и heap для возвращаемой транзакции. Ваш код не формирует инструкции budget вычислений и не добавляет аккаунт fee-pool.
   * **Две подписи на каждый вызов, обе с ключа Solana.** Сначала кошелёк подписывает читаемое сообщение авторизации (*Авторизация Rome* плюс хэш unsigned EIP-1559 payload; Wallet Standard `solana:signMessage`), которое прокси проверяет, прежде чем собирать вызов. Затем он подписывает v1-транзакцию, которую возвращает прокси (`solana:signTransaction` в необработанном wire-формате). Библиотека канала воспринимает их как `signAuthHash` и `signV1Wire`, а не как единый упрощённый метод. Проверьте, что ваш кошелёк подписывает v1-транзакции, прежде чем строить на нём решение: Solflare уже делает это в devnet, а Phantom пока нет.
   * **Приложение само отправляет подписанную транзакцию в Solana RPC.** Прокси собирает; он не вещает атомарный вызов.
   * **Проверьте до запроса подписи.** Библиотека канала разбирает собранное сообщение и отклоняет некорректное ещё до запроса на подпись транзакции.
4. **Разместите разовый grant на wrapper до первого расходования wUSDC.** wUSDC перемещает токены пользователя как SPL-делегат этого пользователя, поэтому синтетический адрес, которому ещё не выдавался grant, получит SPL-ошибку `0x4` при первой передаче wUSDC. Проверьте `isEnabled(user)` на wrapper и, если значение false, предварительно выполните `approve_spl(wrapper, 2^64-1, mint)` на precompile Helper как первый этап выполнения. Это обычный вызов в любом канале, по одному разу на кошелёк. См. [Одноразовое предоставление разрешения для каждого кошелька](https://docs.rome.builders/ru/klyuchevye-ponyatiya/token-interop.md#one-time-grant-per-wallet).
5. **Сначала заведите средства перед вызовом, который их тратит.** Синтетический адрес в состоянии покоя ничего не хранит. Если на нём меньше wUSDC, чем тратит вызов, сначала переведите недостачу с собственного USDC-токена кошелька (идемпотентное создание токен-аккаунта синтетического адреса, затем инструкция activate-token-account программы Rome, которая перемещает токены без запуска EVM). Это одна транзакция Solana, подписываемая одним подтверждением, и она пропускается, если на синтетическом адресе уже достаточно средств.
6. **Ретранслируйте только то, что атомарный компоновщик отклоняет.** Вызов, который не помещается в одну транзакцию Solana (около 1,4 млн вычислительных единиц, 64 аккаунта, 4 КБ), отклоняется компоновщиком с сообщением *external atomic plan requires iterative composition*. Только при таком отказе, и никогда раньше, вызывайте `rome_relayUnsignedV1` с той же подписью авторизации: прокси соберёт и отправит её, оплатит комиссии Solana и вернёт хэш EVM-транзакции (а не подпись Solana). Синтетический адрес платит нативный газ цепочки в wei, поэтому, если его баланс меньше `gasLimit x maxFeePerGas`, сначала пополните его с помощью `rome_composeExternalDepositV1` (v1-транзакция, подписанная кошельком; сумма должна быть кратна 10^12 wei), на практике — по одному разу на каждый кошелёк. Любая другая ошибка, например revert, сбой сети или отклонённая подпись, пробрасывается дальше, а не ретранслируется. Подробности см. в [Ретранслируемые вызовы и длинные вызовы](https://docs.rome.builders/ru/rukovodstva-dlya-razrabotchikov/call-evm-from-solana.md#relayed-calls-and-long-calls).

Пользователь является **плательщиком комиссии** и оплачивает лампорты (SOL) из своего кошелька Solana для прямого вызова; синтетический адрес, которым он управляет, хранит активы и никогда не хранит SOL. После каждой отправки по каналу перед следующим вызовом опрашивайте nonce EVM — индексатор немного отстаёт от подтверждения в Solana, и иначе следующий вызов будет собран на основе nonce, который сеть уже израсходовала.

> **Сначала атомарно, ретрансляция только при отказе.** По умолчанию каждый вызов — это одна EVM-транзакция, выполняемая внутри одной транзакции Solana и подписываемая кошельком пользователя. Ретрансляция — исключение для вызова, который не помещается, а не второй маршрут на выбор по предпочтению: прямой вызов — это два запроса на подпись, ретранслируемый — один, и при ретрансляции оплачивается gas Rome вместо лампортов. Многошаговый сценарий (одобрить, затем купить) — это несколько отдельных вызовов, каждый со своей транзакцией, а не одно выполнение, разбитое на несколько транзакций.

**Почему RWA не может выйти за пределы периметра.** Актив существует в состоянии EVM — его балансы хранятся внутри аккаунтов программы Rome EVM. У него **нет SPL mint** и нет ничего нативного для Solana, что можно было бы переместить; базовые примитивы переноса активов в канале работают с SPL token accounts, которых у баланса в хранилище EVM нет. Любое перемещение, которое может выразить подпись Solana, — это вызов в токен-контракт, а он проходит через гейт белого списка — тестовый набор подтверждает, что перевод на адрес вне белого списка отклоняется одинаково, независимо от того, подписан ли он EVM-ключом или ключом Solana. Денежная часть (wUSDC) — осознанное исключение: она обеспечена SPL и *не* сворачивается обратно на собственный токен-аккаунт пользователя.

***

## Шаг 7 — Узнайте, кто обладает полномочиями после развёртывания

`ArcToken.initialize` запускается из конструктора proxy (tx 1) и назначает роли `msg.sender` — мастеру wizard, то есть эмитенту. Он явно назначает **пять** ролей:

```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.** Первичное предложение отчеканивается внутри `инициализация` (внутренняя `_mint`, роль не нужна), но *позднее* `mint` или `сжигание` требует, чтобы эмитент сначала выдал эту роль самому себе. Он может это сделать, потому что у него есть `DEFAULT_ADMIN_ROLE` (администратор каждой роли — ничего не вызывает `_setRoleAdmin`, поэтому `DEFAULT_ADMIN_ROLE` он администрирует их все). Но это намеренный дополнительный шаг, а не постоянное право.
* **`UPGRADER_ROLE` никогда не назначается factory.** Обновления через factory (`ArcTokenFactoryV2.upgradeToken`) требуют, чтобы **сама factory** имела `UPGRADER_ROLE` на токене — выдача этого права себе ничего не даёт. Это право — односторонняя дверь, которую factory не может отозвать, поэтому оно выдаётся по желанию: если вам нужны обновления через factory, `grantRole(UPGRADER_ROLE, factory)` явно; в противном случае эмитент обновляет токен напрямую.

Полная модель из 21 полномочия (11 имён ролей в шести контрактах — одно и то же имя является разным полномочием в каждом контракте) зафиксирована в `arc/roles.ts`. Выполняйте `rolesRequiredFor(contract, functionName)` а не чтением собственного контракта роли, потому что четыре storefront-функции и обе factory-функции ограничены полномочием, которое находится в *другом* контракт.

***

## Шаг 8 — Распределите доходность

Токен выплачивает доходность в wUSDC (фиксировано на `инициализация`изменяется через `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 тыс. gas на держателя). Каждый whitelisted-держатель, будь то EVM или Solana-native, получает долю пропорционально; эталонный скрипт — `measure-yield-batch.ts` а шаг доходности в funded smoke проверяет это end-to-end.

```bash
# USAGE.md reference form: обрабатывайте по одному держателю за транзакцию, пока nextIndex не вернётся к 0
distributeYieldWithLimit(total, offset, 1)
```

***

## Шаг 9 — Проверьте то, что вы развернули

В Rome источники никуда не отправляются автоматически, поэтому верификация — это отдельный шаг, который вы запускаете сами. После любого развёртывания — инфраструктуры или нового токена — запустите только для чтения, без ключей и идемпотентный верификатор (уже проверенные контракты пропускаются, поэтому повторный запуск после выпуска токена проверит только новые):

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

Он ожидает **три** контракты на каждый токен (proxy + оба модуля) плюс инфраструктуру и сообщает, что именно не удалось верифицировать, вместо того чтобы проваливать развёртывание. Ручной запуск этого процесса однажды пропустил семь контрактов.

Регистрация актива в реестре Rome рассматривает верификацию как **гейт**, а не как украшение (`register-asset.ts`): токен получает запись `apps/arc/<chain>.json` — содержащую `standard: arc-permissioned-erc20` и `transferRestriction` с именем его гейта белого списка — только когда все три его контракта верифицированы в Sourcify. Эта запись получает факты из сети (у токена, развёрнутого wizard, нет зафиксированного receipt) и записывает только локальную копию реестра; отправка PR — задача человека.

```bash
CHAIN_ID=200010 npx tsx register-asset.ts <tokenAddress>        # верифицировать + подготовить запись реестра
CHAIN_ID=200010 DRY=1 npx tsx register-asset.ts <tokenAddress>  # только чтение, предварительный просмотр
```

Для end-to-end подтверждения всего цикла — создать, добавить в белый список, включить гейт, продать по обоим каналам, распределить доходность — запустите funded smoke на любой цепочке:

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

***

## Шаг 10 — Поймите, что остаётся вне блокчейна

Модель доверия намеренно прозрачна, и разработчик должен представлять её своим пользователям точно так же:

* **Флаг белого списка — это ваше решение вне блокчейна.** KYC/AML выполняются в вашем процессе — ваши провайдеры, ваши правила. В блокчейне записывается и исполняется только *результат*, `isWhitelisted(addr)`.
* **В ончейне хранится только один булев флаг на адрес.** Никаких PII, никаких документов, никаких заявлений об идентичности, никаких ончейн-аттестаций, никакого криптографического доказательства того, кому принадлежит адрес. Это модель Arc, используемая в Plume; она обменивает более тяжёлые переносы стандарта ончейн-идентичности (например, ERC-3643) на более лёгкую механику и доверие, удерживаемое эмитентом.
* **Восстановление — это полномочие эмитента, а не аварийный обход.** Утерянный кошелёк — EVM или Solana — восстанавливается путём добавления в белый список замещающего адреса и, при необходимости, использования mint/burn/upgrade в рамках вашей правовой процедуры (у Arc нет встроенного примитива принудительного перевода). Поэтому хранение ключей эмитента является частью compliance-позиции.
* **Ни собственного relayer Bloom, ни поверхности кастодиального риска.** Пользователи хранят свой gas на обоих каналах. Сервис fee-payer, запускаемый приложением, означал бы хранение ключей — поверхность риска, которую RWA-продукт не должен добавлять. Единственный relay в канале Solana — это relay прокси цепочки, для вызова, который слишком велик для одной транзакции, и пользователь всё равно авторизует его своей подписью и оплачивает своим Rome gas.

***

## Справка: инструментарий

Каждый скрипт запускается из каталога `scripts/` инструментария, при этом `PRIVATE_KEY`, `CHAIN_ID`, и `REGISTRY_ROOT` экспортируются.

| Скрипт                          | Что делает                                                                               |
| ------------------------------- | ---------------------------------------------------------------------------------------- |
| `deploy-infra.ts`               | Один раз на цепочку: четыре общих контракта, настроенные для wUSDC.                      |
| `create-token.ts`               | Поэтапный wizard — восемь транзакций, один токен.                                        |
| `rotate-factory.ts`             | Развернуть свежую factory после изменения компилятора/артефакта; перенастроить.          |
| `verify-artifact-provenance.ts` | Доказать, что артефакт proxy принимается развернутой factory (только чтение).            |
| `verify-deployments.ts`         | Проверить все три контракта на каждый токен + инфраструктуру в Sourcify (только чтение). |
| `register-asset.ts`             | Проверить гейт, затем подготовить compliance-запись в реестре.                           |
| `measure-yield-batch.ts`        | Повторно измерить потолок доходности на транзакцию для цепочки.                          |
| `smoke.ts`                      | Снабжённый end-to-end набор для обеих веток.                                             |
| `sweep-synthetic-native.ts`     | Вернуть нативный gas с синтетического аккаунта (гигиена тестов).                         |

Более подробные материалы находятся рядом с этим руководством: `docs/ARCHITECTURE.md` (многоуровневая модель приложения), `docs/LANES.md` (два канала и кастодиальность), `docs/COMPLIANCE.md` (модель доверия) и `docs/USAGE.md` (операторский runbook).


---

# 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/ru/prilozheniya-v-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.
