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

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

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

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

• Архитектура объясняет протокол — как EVM работает внутри программы Solana.

• Каждый репозиторий поставляется с AGENTS.md (например, rome-sdk-ts/AGENTS.md) который направляет по тому, с чего вы начинаете (контракту Solidity, программе Solana, проекту с нуля, from-home) к тому примеру, который ближе всего к вашему случаю.

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

Поверхность в общих чертах

Основа — стройте на этом

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

Справочные приложения — учитесь на примерах

Репозиторий	Что это	Обращайтесь к нему, когда
rome-dex	AMM с двумя каналами — нативный пул Solana с тонким EVM-маршрутизатором.	Открытие другого канала; native-core пример.
aerarium	Кредитование с двумя каналами — ядро Comet на Solidity, к которому пользователи Solana обращаются через синтетического отправителя.	Открытие другого канала; ядро на Solidity пример.
cardo	Пользователи EVM управляют dApp'ами Solana (swap/stake/lend/perps) через CPI.	Подробно разобранное приложение CPI-to-Solana для изучения.
appia	Cross-VM DeFi, ориентированное на позиции; пользователи получают доступ к нему со своей исходной сети.	Это from-home приложение.
rome-aave-v3-demo	Supply/borrow/repay для Aave v3, развернутые без изменений.	Полноценное EVM-приложение, работающее без изменений.

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

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

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

Репозиторий	Что это	Обращайтесь к нему, когда
rome-bridge-api	Внецепочечный оркестратор и спонсор комиссий для ончейн-моста. Не хранит ключи.	Пополнение кошелька или поток from-home.
rome-oracle-gateway	Ценовые потоки Solana (Pyth, Switchboard), доступные для EVM через Chainlink AggregatorV3Interface.	Вам нужен ценовой поток.

Scaffold — начните здесь

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

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

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

• rome-registry является единственным источником актуальных данных сети. rome-sdk-ts является путём записи — и его /bridge подпуть — это клиент, который ваше приложение использует для взаимодействия с rome-bridge-api. rome-solidity то, что импортируют ваши контракты (и форки); oracle-адаптеры, которые rome-oracle-gateway развёртывания также находятся там. Эти три компонента независимы друг от друга — выбирайте те, которые нужны вашему приложению.

• create-rome-app связывает первые два компонента для нового приложения, так что новый проект начинает работу уже с чтением registry и записью через SDK.

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

Переходите к нужному по тому, что вам требуется

• Актуальный факт сети (идентификатор, адрес, mint, program id) → rome-registry. Никогда не хардкодьте.

• Пишете код приложения (запись, вызов CPI, мост) → rome-sdk-ts; см. в Rome SDK.

• Пишете контракты → rome-solidity; см. Развертывание контрактов Solidity.

• Вызов программы Solana из контракта Solidity → CPI precompile в rome-solidity (interface.sol); cardo — это подробно разобранный пример.

• Рабочий пример AMM, кредитования, CPI или from-home-приложения → смотрите справочные приложения выше; в каждом репозитории AGENTS.md маршрутизация идёт по исходной точке.

• Генерация нового приложения → create-rome-app.

• Ценовой поток → rome-oracle-gateway (см. портал Oracle Gateway).

• Пользователи в другой сети → Из исходной сети + rome-bridge-api.

• Определение, на какой стороне находится ваша логика → Выберите своё ядро.

Слой основы в деталях

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

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

Вы читаете это через геттеры — getChain, getTokens, getContracts, getOracle, getBridge, getAlts, а также getPrograms(network) (идентификаторы программ привязаны к сети, а не к chain id). Пакет — обычный ESM (на сегодня без встроенных TypeScript-типов).

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

• getTokens() не возвращает assetRef. Чтобы найти обёртку токена, сопоставляйте по его mint (mintId) — например, обёртка gas token — это запись, у которой совпадает mint.

• Он читает JSON с диска (node:fs) — в браузере использовать нельзя. В веб-приложении заранее преобразуйте нужные значения в статический JSON-файл на этапе сборки и импортируйте его в клиент. (Именно так делают create-rome-app и appia.)

Факты, которые ваше приложение не читает в реальном времени, также доступны в справочнике Contract Addresses. .

rome-sdk-ts — путь записи для обоих каналов

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

• submitRomeTx — путь записи для EVM-канала: рассчитывает gas на основе eth_estimateGas (с запасом, с резервным верхним пределом, если оценка завершается ошибкой) и подставляет комиссии EIP-1559.

• submitRomeTxSolanaLane — то же самое для кошелька Phantom/Solana кошелька, который управляет вашим EVM-приложением. Синтетический отправитель не хранит ничего в состоянии покоя; buildFundLeg/buildSweepLeg перемещает стоимость внутрь и наружу как ERC-20 (wUSDC), а не нативный msg.value, а новый синтетический адрес автоматически создаётся (create_pda) при первом использовании.

• Вывод PDA/ATA, CPI invoke/invoke_signed кодировщики, привязки precompile, а также /bridge подпуть (@rome-protocol/sdk/bridge) — клиент моста с предварительным получением котировки.

Полный API и примеры: Rome SDK, а также руководства Вызов Solana из EVM, Вызов EVM из Solana, а также Создание приложения с двумя каналами.

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

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

• contracts/interface.sol — интерфейсы precompile, привязанные к своим адресам: CPI ICrossProgramInvocation (0xFF…08), Helper IHelperProgram (0xFF…09, создание ATA/PDA, переводы SPL, газ↔lamports), Withdraw IWithdraw (0x42…16), а также System (0xFF…07). Также здесь находится оптимизированное по газу cached семейство; контракт последовательно использует один из вариантов. Полная таблица адресов: справочнике Contract Addresses..

• Обёртки SPL/ERC-20 — SPL_ERC20 (на основе CPI) и SPL_ERC20_cached (кэшированный вариант, используемый в devnet); любой SPL mint уже является ERC-20 через них.

• Адаптеры oracle (contracts/oracle/) — адаптеры Pyth/Switchboard rome-oracle-gateway развёртывания, читаются через IAggregatorV3Interface.

• Разобранные примеры в contracts/examples/.

Раздел Solidity SDK в Rome SDK показывает шаблоны импортов и привязки precompile в коде.

Что дальше

• Выберите своё ядро — на какой стороне находится ваша логика.

• Быстрый старт — разверните свой первый контракт.

• create-rome-app — сгенерируйте приложение с двумя каналами.

• В каждом репозитории AGENTS.md — маршрут по исходной точке к ближайшему примеру.