> 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/nachalo-raboty-1/ecosystem.md).

# Экосистема и репозитории

Каждый публичный репозиторий Rome, что он представляет собой и как они сочетаются — карта для навигации по системе.

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

Два соседних раздела отвечают на разные вопросы, и эта страница ссылается на оба, а не повторяет их:

* [Архитектура](https://docs.rome.builders/ru/nachalo-raboty-1/architecture.md) объясняет **протокол** — как EVM работает внутри программы Solana.
* Каждый репозиторий поставляется с **`AGENTS.md`** (например, [rome-sdk-ts/AGENTS.md](https://github.com/rome-protocol/rome-sdk-ts/blob/main/AGENTS.md)) который направляет вас по **тому, с чего вы начинаете** (контракт Solidity, программа Solana, с нуля, из домашней сети) к тому примеру, который ближе всего к вашему случаю.

Эта страница — промежуточный уровень между: **всей поверхностью** и тем, как части соединяются.

## Поверхность в одном взгляде

### Основа — опирайтесь на это

| Репозиторий                                                     | Что это                                                                                                                                                                                           | Обращайтесь к этому, когда                                   |
| --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
| [rome-registry](https://github.com/rome-protocol/rome-registry) | `@rome-protocol/registry` — только для чтения, сгенерированная проекция актуальных сведений о цепочке (идентификаторы, RPC, адреса, mint токенов, идентификаторы программ, оракульные фиды, ALT). | Вам нужен реальный факт цепочки — никогда не хардкодьте его. |
| [rome-sdk-ts](https://github.com/rome-protocol/rome-sdk-ts)     | `@rome-protocol/sdk` — путь записи на TypeScript: `submitRomeTx` + размер комиссии, обе дорожки, кодировщики PDA/ATA + CPI, привязки precompile, клиент `/bridge` .                               | Вы пишете код приложения или фронтенда.                      |
| [rome-solidity](https://github.com/rome-protocol/rome-solidity) | Интерфейсы precompile для Solidity, обёртки SPL/ERC-20 и адаптеры оракулов — набор инструментов на стороне контрактов.                                                                            | Вы пишете контракты.                                         |

Названия `@rome-protocol/…` выше — это имена пакетов, но сами пакеты не опубликованы в npm. Устанавливайте их из GitHub (команды приведены в каждом разделе под [Основа, крупным планом](#the-foundation-layer-up-close)); пути импорта в вашем коде остаются теми же.

### Роллапы Rome ZK EVM

| Репозиторий                                                     | Что это                                                                      | Обращайтесь к этому, когда                                |
| --------------------------------------------------------------- | ---------------------------------------------------------------------------- | --------------------------------------------------------- |
| [solana-zk-evm](https://github.com/rome-protocol/solana-zk-evm) | Документация по программам ZK-роллапа, узлу, доказывающему узлу и оператору. | Вы запускаете EVM-цепочку, которая завершается на Solana. |
| [rome-zk-guest](https://github.com/rome-protocol/rome-zk-guest) | Исходный код guest для батча, собранный для генезиса каждой цепочки.         | Вы собираете guest и запрашиваете его verification key.   |

### Ostia (ZK EVM на Canton)

| Репозиторий                                                                           | Что это                                                                                                                | Обращайтесь к этому, когда                                                                                                                                                                           |
| ------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [canton-zk-evm](https://github.com/rome-protocol/canton-zk-evm/blob/v0.1.0/README.md) | Ostia, ZK EVM на Canton: каждый доказанный блок EVM вместе со своими действиями Canton фиксируется в одной транзакции. | Вы строите на Ostia DevNet ([explorer](https://ostia.devnet.romeprotocol.xyz/)) или запускаете собственную Ostia. См. [Canton ZK EVM](https://docs.rome.builders/ru/canton-zk-evm/canton-zk-evm.md). |

### Референсные приложения — учитесь на примерах

| Репозиторий                                                             | Что это                                                                                                                              | Обращайтесь к этому, когда                             |
| ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------ |
| [rome-dex](https://github.com/rome-protocol/rome-dex)                   | AMM с двумя дорожками — нативный пул Solana с тонким EVM-роутером.                                                                   | Открытие второй дорожки; пример **native-core** .      |
| [aerarium](https://github.com/rome-protocol/aerarium)                   | Кредитование с двумя дорожками — ядро Comet на Solidity, к которому пользователи Solana обращаются через синтетического отправителя. | Открытие второй дорожки; пример **ядро на Solidity** . |
| [cardo](https://github.com/rome-protocol/cardo)                         | Пользователи EVM, управляющие Solana dApp (swap/stake/lend/perps) через CPI.                                                         | Готовое приложение CPI-to-Solana для изучения.         |
| [appia](https://github.com/rome-protocol/appia)                         | DeFi между VM с приоритетом позиций; пользователи получают к нему доступ из своей домашней сети.                                     | Приложение **из домашней сети** .                      |
| [rome-aave-v3-demo](https://github.com/rome-protocol/rome-aave-v3-demo) | Поставка/заём/погашение Aave v3, развернуто без изменений.                                                                           | Полноценное EVM-приложение, работающее как есть.       |

### Форки контрактов — известные протоколы, развернутые на Rome

| Репозиторий                                                                       | Что это                              | Обращайтесь к этому, когда     |
| --------------------------------------------------------------------------------- | ------------------------------------ | ------------------------------ |
| [compound-on-rome-comet](https://github.com/rome-protocol/compound-on-rome-comet) | Денежный рынок Compound III (Comet). | Форк известного EVM-протокола. |
| [rome-aave-v3](https://github.com/rome-protocol/rome-aave-v3)                     | Форк контрактов Aave v3.             | Форк известного EVM-протокола. |

### Сервисы — ваше приложение обращается к этим

| Репозиторий                                                                 | Что это                                                                                           | Обращайтесь к этому, когда                      |
| --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | ----------------------------------------------- |
| [rome-bridge-api](https://github.com/rome-protocol/rome-bridge-api)         | Внецепочечный оркестратор и спонсор комиссий для on-chain моста. Не хранит ключей.                | Пополнение кошелька или поток из домашней сети. |
| [rome-oracle-gateway](https://github.com/rome-protocol/rome-oracle-gateway) | Ценовые фиды Solana (Pyth, Switchboard), доступные в EVM через Chainlink `AggregatorV3Interface`. | Вам нужен ценовой фид.                          |

### Каркас — начните здесь

| Репозиторий                                                         | Что это                                                                                                                                                             | Обращайтесь к этому, когда  |
| ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- |
| [create-rome-app](https://github.com/rome-protocol/create-rome-app) | `npx github:rome-protocol/create-rome-app` — генерирует приложение с двумя дорожками, заранее подключённое к registry и SDK, с пополненной проверкой обеих дорожек. | Начинаете новое приложение. |

## Как они сочетаются

```mermaid
flowchart TD
    REG["rome-registry — актуальные данные цепочки"]
    SDK["rome-sdk-ts — запись, CPI, клиент моста"]
    SOL["rome-solidity — интерфейсы precompile, обёртки SPL, адаптеры оракулов"]
    CRA["create-rome-app — генератор каркаса"]
    APP["ваше приложение — фронтенд + контракты"]
    BAPI["rome-bridge-api — внецепочечный оркестратор, не хранит ключей"]
    OG["rome-oracle-gateway — ценовые фиды Solana"]

    CRA -->|генерирует, заранее подключено| APP
    REG -->|данные, никогда не хардкодятся| APP
    SDK -->|путь записи и CPI| APP
    SOL -->|импортируется вашими контрактами| APP
    APP -->|SDK /bridge client| BAPI
    APP -->|читает через AggregatorV3Interface| OG
    OG -.->|адаптеры находятся в| SOL
    CRA -.->|подключает| REG
    CRA -.->|подключает| SDK
```

Основа состоит из трёх базовых репозиториев и генератора каркаса:

* [**rome-registry**](https://github.com/rome-protocol/rome-registry) является единственным источником актуальных данных. [**rome-sdk-ts**](https://github.com/rome-protocol/rome-sdk-ts) является путём записи — и его `/bridge` подпуть — это клиент, через который ваше приложение обращается к `rome-bridge-api`. [**rome-solidity**](https://github.com/rome-protocol/rome-solidity) — это то, что импортируют ваши контракты (и форки); адаптеры оракулов, которые `rome-oracle-gateway` разворачиваются там же. Эти три компонента независимы друг от друга — выбирайте те, которые нужны вашему приложению.
* [**create-rome-app**](https://github.com/rome-protocol/create-rome-app) связывает первые два компонента для нового приложения, чтобы свежий проект сразу начинал читать registry и писать через SDK.

Референсные приложения — исключение, которое стоит знать: **они появились раньше выделенных пакетов.** cardo использует пакет registry; appia проецирует registry в статический JSON на этапе сборки; и оба вендорят свой путь записи вместо импорта SDK. Изучайте их, чтобы понять паттерны — но новое **новое** приложение должно начинать с `create-rome-app` + пакеты, а не с клонирования приложения.

## Ориентируйтесь по тому, что вам нужно

* **Актуальный факт цепочки** (id, адрес, mint, program id) → [rome-registry](https://github.com/rome-protocol/rome-registry). Никогда не хардкодьте.
* **Написание кода приложения** (запись, вызов CPI, мост) → [rome-sdk-ts](https://github.com/rome-protocol/rome-sdk-ts); справка в [Rome SDK](https://docs.rome.builders/ru/produkty/rome-sdk.md).
* **Написание контрактов** → [rome-solidity](https://github.com/rome-protocol/rome-solidity); см. [Развертывание Solidity-контрактов](https://docs.rome.builders/ru/rukovodstva-dlya-razrabotchikov/deploy-solidity.md).
* **Вызов программы Solana из Solidity-контракта** → precompile CPI в [rome-solidity](https://github.com/rome-protocol/rome-solidity) (`interface.sol`); [cardo](https://github.com/rome-protocol/cardo) — готовый пример.
* **Рабочий пример** AMM, кредитования, CPI или приложения из домашней сети → референсные приложения выше; у каждого репозитория `AGENTS.md` есть маршрутизация по точке старта.
* **Генерация каркаса нового приложения** → [create-rome-app](https://github.com/rome-protocol/create-rome-app).
* **Ценовой фид** → [rome-oracle-gateway](https://github.com/rome-protocol/rome-oracle-gateway) (см. [портал Oracle Gateway](https://docs.rome.builders/ru/prilozheniya-v-rome/oracle-gateway.md)).
* **Пользователи в другой сети** → [Из домашней сети](https://docs.rome.builders/ru/rukovodstva-dlya-razrabotchikov/from-home.md) + [rome-bridge-api](https://github.com/rome-protocol/rome-bridge-api).
* **Определение, на какой стороне находится ваша логика** → [Выберите ваше ядро](https://docs.rome.builders/ru/klyuchevye-ponyatiya/choose-your-core.md).

## Основа, крупным планом

### rome-registry — актуальные данные, публичные по конструкции

Registry **генерируется** из внутреннего источника Rome: allowlist публикует только то, что должно быть доступно публично, **подставляет** внутренние конечные точки их публичными эквивалентами, и **по умолчанию запрещает** всё остальное — поэтому по конструкции он безопасен для публикации. Он публикует для каждой цепочки `chain.json` / `tokens.json` / `contracts.json` / `oracle.json` / `bridge.json` / `alts.json`, а также Solana `программы` и развертывания приложений по каждому протоколу.

Устанавливайте из GitHub, закрепив версию за тегом релиза: `npm install github:rome-protocol/rome-registry#v0.2.0`. Чтение выполняется через геттеры — `getChain`, `getTokens`, `getContracts`, `getOracle`, `getBridge`, `getAlts`, и `getPrograms(network)` (идентификаторы программ индексируются по network, а не по chain id). Пакет — обычный ESM (сегодня без встроенных TypeScript-типов).

Два момента, которые нужно знать перед подключением:

* **`getTokens()` не возвращает `assetRef`.** Чтобы найти обёртку токена, сопоставьте его по **mint** (`mintId`) — например, обёртка gas-токена — это запись, у которой совпадает mint.
* **Он читает JSON с диска (`node:fs`) — для браузера не подходит.** В веб-приложении сведите нужные значения в статический JSON-файл на этапе сборки и импортируйте его в клиент. (Именно это делает `create-rome-app` и appia.)

Адреса контрактов возвращаются как список версий для каждого контракта; выбирайте ту, у которой `статус` равен `live`. [Чтение списка контрактов](https://docs.rome.builders/ru/spravochnik/contract-addresses.md#reading-the-contracts-list) показывает, как это работает. Факты, которые ваше приложение не читает в реальном времени, также доступны в [справочнике Contract Addresses](https://docs.rome.builders/ru/spravochnik/contract-addresses.md) .

### rome-sdk-ts — путь записи, обе дорожки

Устанавливайте из GitHub: `npm install github:rome-protocol/rome-sdk-ts#v0.4.0`.

`@rome-protocol/sdk` (v0.4.0) объединяет всё, что нужно для записи в Rome, чтобы вам не приходилось вручную собирать calldata или комиссии:

* **`submitRomeTx`** — путь записи для EVM-дорожки: рассчитывает gas на основе `eth_estimateGas` (с запасом, с верхним пределом на случай, если оценка завершится ошибкой), и предоставляет комиссии EIP-1559.
* **`submitRomeTxV1`** — то же самое для **кошелька Solana** управляющего вашим EVM-приложением: одна транзакция Solana v1 на вызов, два запроса к кошельку. Синтетический отправитель ничего не хранит в состоянии покоя; `buildFundLeg`/`buildSweepLeg` перемещают value внутрь и наружу как ERC-20 (`wUSDC`), **а не** нативный `msg.value`; обычные инструкции Solana вокруг вызова (fund leg, создание token-account кошелька перед sweep) также проходят через `submitSolanaInstructionsV1` как транзакции v1. `submitRomeTxSolanaLane` — более ранний путь, который собирает legacy-транзакцию Solana в клиенте и автоматически создаёт новый синтетический (`create_pda`) при первом использовании.
* **Генерация PDA/ATA, CPI `invoke`/`invoke_signed` кодировщики, привязки precompile**, и **`/bridge`** подпуть (`@rome-protocol/sdk/bridge`) — клиент моста, ориентированный прежде всего на котировку.

Полный API + примеры: [Rome SDK](https://docs.rome.builders/ru/produkty/rome-sdk.md), и руководства [Вызов Solana из EVM](https://docs.rome.builders/ru/rukovodstva-dlya-razrabotchikov/call-solana-from-evm.md), [Вызов EVM из Solana](https://docs.rome.builders/ru/rukovodstva-dlya-razrabotchikov/call-evm-from-solana.md), и [Сборка приложения с двумя дорожками](https://docs.rome.builders/ru/rukovodstva-dlya-razrabotchikov/dual-lane-app.md).

### rome-solidity — набор инструментов на стороне контрактов

Устанавливайте из GitHub, а не из npm. С npm или Hardhat: `npm install github:rome-protocol/rome-solidity`. С Foundry: `forge install rome-protocol/rome-solidity`, затем добавьте remapping `@rome-protocol/rome-solidity/=lib/rome-solidity/` в `foundry.toml` (под `[profile.default]`, как `remappings = [...]`), чтобы `@rome-protocol/rome-solidity/contracts/interface.sol` разрешался. Имя пакета в `package.json` равен `@rome-protocol/rome-solidity`, поэтому один и тот же путь импорта работает в обоих случаях.

Что импортируют ваши контракты:

* **`contracts/interface.sol`** — интерфейсы precompile, привязанные к своим адресам: **CPI** `ICrossProgramInvocation` (`0xFF…08`), **Вспомогательный** `IHelperProgram` (`0xFF…09`, создание ATA/PDA, переводы SPL, gas↔lamports), **Вывод** `IWithdraw` (`0x42…16`), и **Система** (`0xFF…07`). Здесь же находится и оптимизированное по gas **кешированное** семейство; контракт последовательно использует одну дорожку. Полная таблица адресов: [справочнике Contract Addresses](https://docs.rome.builders/ru/spravochnik/contract-addresses.md).
* **Обёртки SPL/ERC-20** — `SPL_ERC20` (на основе CPI) и `SPL_ERC20_cached` (кешированный вариант, используемый в devnet); любой mint SPL уже является ERC-20 через них.
* **Адаптеры оракулов** (`contracts/oracle/`) — адаптеры Pyth/Switchboard `rome-oracle-gateway` развёртывания, читаются через `IAggregatorV3Interface`.
* Готовые примеры в `contracts/examples/`.

В разделе Solidity SDK [Rome SDK](https://docs.rome.builders/ru/produkty/rome-sdk.md) показываются шаблоны импорта и привязки precompile в коде.

## Что дальше

* [Выберите ваше ядро](https://docs.rome.builders/ru/klyuchevye-ponyatiya/choose-your-core.md) — на какой стороне находится ваша логика.
* [Быстрый старт](https://docs.rome.builders/ru/nachalo-raboty-1/quickstart.md) — разверните свой первый контракт.
* [create-rome-app](https://github.com/rome-protocol/create-rome-app) — сгенерируйте приложение с двумя дорожками.
* Каждого репозитория `AGENTS.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/ru/nachalo-raboty-1/ecosystem.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.
