> 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/ko/getting-started-1/ecosystem.md).

# 생태계 및 저장소

모든 공개 Rome 저장소, 각 저장소의 내용, 그리고 어떻게 함께 구성되는지 — 표면을 탐색하기 위한 지도.

Rome의 공개 표면은 여러 저장소들의 집합입니다: 몇 개의 **기반** 그 위에 구축하는 패키지, 스캐폴더, 배울 수 있는 참고용 앱, 그리고 앱이 호출하는 두 서비스입니다. 이 페이지는 지도입니다 — 각 저장소가 무엇인지, 그리고 어떻게 서로 맞물리는지 보여줍니다.

두 인접한 저장소가 서로 다른 질문에 답하며, 이 페이지는 둘 중 어느 하나를 반복하지 않고 둘 다를 연결합니다:

* [아키텍처](https://docs.rome.builders/ko/getting-started-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` — 읽기 전용, 실시간 체인 사실을 생성해 투영한 결과(ids, RPC, addresses, token mints, program ids, oracle feeds, ALTs). | 실제 체인 사실이 필요할 때 — 절대 하드코딩하지 마세요. |
| [rome-sdk-ts](https://github.com/rome-protocol/rome-sdk-ts)     | `@rome-protocol/sdk` — TypeScript 쓰기 경로: `submitRomeTx` + 수수료 산정, 양쪽 레인, PDA/ATA + CPI 인코더, 프리컴파일 바인딩,  `/bridge`  클라이언트.    | 앱 또는 프런트엔드 코드를 작성 중입니다.          |
| [rome-solidity](https://github.com/rome-protocol/rome-solidity) | Solidity 프리컴파일 인터페이스, SPL/ERC-20 래퍼, 그리고 오라클 어댑터 — 계약 측 툴킷.                                                                  | 계약을 작성 중입니다.                     |

위의 `@rome-protocol/…` 라는 이름은 패키지 이름이지만, 해당 패키지들은 npm에 배포되지 않습니다. GitHub에서 설치하세요(명령어는 각 섹션의 [기반 계층을 가까이서](#the-foundation-layer-up-close)); 코드의 import 경로는 그대로 유지됩니다.

### Rome ZK EVM 롤업

| 저장소                                                             | 무엇인지                          | 이럴 때 사용                         |
| --------------------------------------------------------------- | ----------------------------- | ------------------------------- |
| [solana-zk-evm](https://github.com/rome-protocol/solana-zk-evm) | ZK 롤업 프로그램, 노드, 프로버 및 운영자 문서. | Solana에 정산되는 EVM 체인을 운영하고 있습니다. |
| [rome-zk-guest](https://github.com/rome-protocol/rome-zk-guest) | 각 체인의 제네시스를 위해 빌드된 배치 게스트 소스. | 게스트를 빌드하고 해당 검증 키를 요청하고 있습니다.   |

### Ostia (Canton의 ZK EVM)

| 저장소                                                                                   | 무엇인지                                                                    | 이럴 때 사용                                                                                                                                                                      |
| ------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [canton-zk-evm](https://github.com/rome-protocol/canton-zk-evm/blob/v0.1.0/README.md) | Canton 위의 ZK EVM인 Ostia: 증명된 각 EVM 블록은 한 번의 트랜잭션으로 Canton 액션과 함께 커밋됩니다. | Ostia DevNet([탐색기](https://ostia.devnet.romeprotocol.xyz/))에서 구축하거나 자신만의 Ostia를 운영하고 있습니다. 참조 [Canton ZK EVM](https://docs.rome.builders/ko/canton-zk-evm/canton-zk-evm.md). |

### 참고용 앱 — 예제로 배우기

| 저장소                                                                     | 무엇인지                                                      | 이럴 때 사용                           |
| ----------------------------------------------------------------------- | --------------------------------------------------------- | --------------------------------- |
| [rome-dex](https://github.com/rome-protocol/rome-dex)                   | 듀얼 레인 AMM — 얇은 EVM 라우터가 달린 네이티브 Solana 풀.                 | 다른 레인을 여는;  **native-core** 예제.   |
| [aerarium](https://github.com/rome-protocol/aerarium)                   | 듀얼 레인 대출 — Solana 사용자가 합성 송신자를 통해 접근하는 Solidity Comet 코어. | 다른 레인을 여는;  **Solidity 코어** 예제.   |
| [cardo](https://github.com/rome-protocol/cardo)                         | CPI를 통해 Solana dApp(스왑/스테이킹/대출/무기한 계약)을 구동하는 EVM 사용자.     | 공부해볼 수 있는 CPI-to-Solana 앱의 실전 예제. |
| [appia](https://github.com/rome-protocol/appia)                         | 포지션 우선의 크로스-VM DeFi; 사용자는 자신의 홈 체인에서 접근합니다.               | 하나의 **홈 체인에서** 앱.                 |
| [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)         | 온체인 브리지용 오프체인 오케스트레이터 + 수수료 스폰서. 키를 보유하지 않습니다.                      | 지갑에 자금을 넣거나, 홈 체인에서 시작하는 흐름. |
| [rome-oracle-gateway](https://github.com/rome-protocol/rome-oracle-gateway) | Solana 가격 피드(Pyth, Switchboard)를 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 — 프리컴파일 인터페이스, SPL 래퍼, 오라클 어댑터"]
    CRA["create-rome-app — 스캐폴더"]
    APP["your app — 프런트엔드 + 계약"]
    BAPI["rome-bridge-api — 오프체인 오케스트레이터, 키를 보유하지 않음"]
    OG["rome-oracle-gateway — Solana 가격 피드"]

    CRA -->|스캐폴드, 사전 연결됨| APP
    REG -->|사실, 절대 하드코딩되지 않음| APP
    SDK -->|쓰기 경로 및 CPI| APP
    SOL -->|계약에서 import| APP
    APP -->|SDK /bridge 클라이언트| 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) 계약(및 포크)이 import하는 것이며; 오라클 어댑터는 `rome-oracle-gateway` 거기에 배포됩니다. 이 셋은 서로 독립적입니다 — 앱에 필요한 것만 선택하세요.
* [**create-rome-app**](https://github.com/rome-protocol/create-rome-app) 첫 두 가지를 새 앱을 위해 하나로 묶어 주므로, 새 프로젝트는 이미 registry를 읽고 SDK를 통해 쓰는 상태로 시작합니다.

알아둘 만한 예외는 참고용 앱입니다: **이는 추출된 패키지보다 앞서 만들어졌습니다.** cardo는 registry 패키지를 소비하고; appia는 빌드 시 registry를 정적 JSON으로 투영하며; 둘 다 SDK를 import하는 대신 쓰기 경로를 자체 포함합니다. 패턴을 배우려면 읽어보세요 — 하지만  **새** 앱은 `create-rome-app` + 패키지들에서 시작해야 하며, 앱을 복제해서 시작하면 안 됩니다.

## 필요한 것에 따라 이동

* **실시간 체인 사실** (id, address, 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/ko/products/rome-sdk.md).
* **계약 작성** → [rome-solidity](https://github.com/rome-protocol/rome-solidity); 참조: [Solidity 계약 배포](https://docs.rome.builders/ko/developer-guides/deploy-solidity.md).
* **Solidity 계약에서 Solana 프로그램 호출** → [rome-solidity](https://github.com/rome-protocol/rome-solidity) (`의 CPI 프리컴파일`); [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/ko/rome-1/oracle-gateway.md)).
* **다른 체인의 사용자** → [홈 체인에서](https://docs.rome.builders/ko/developer-guides/from-home.md) + [rome-bridge-api](https://github.com/rome-protocol/rome-bridge-api).
* **로직을 어느 쪽이 보유할지 결정하기** → [핵심을 선택하세요](https://docs.rome.builders/ko/core-concepts/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`. getter를 통해 읽습니다 — `getChain`, `getTokens`, `getContracts`, `getOracle`, `getBridge`, `getAlts`, 그리고 `getPrograms(network)` (프로그램 id는 chain id가 아니라 네트워크별로 키가 지정됩니다). 이 패키지는 순수 ESM입니다(현재 번들된 TypeScript 타입 없음).

연결하기 전에 알아둘 두 가지:

* **`getTokens()` 는 반환하지 않습니다 `assetRef`.** 토큰의 래퍼를 찾으려면 그 **mint** (`mintId`)와 일치시키세요 — 예를 들어 가스 토큰의 래퍼는 자신의 mint를 공유하는 항목입니다.
* **디스크에서 JSON을 읽습니다(`node:fs`) — 브라우저 안전이 아닙니다.** 웹 앱에서는 빌드 시 필요한 값을 정적 JSON 파일로 투영하여 클라이언트에서 import하세요. (이것이 바로 `create-rome-app` 와 appia가 하는 일입니다.)

계약 주소는 계약별로 버전 목록으로 반환됩니다; 그중 `status` 가 `live`. [계약 목록 읽기](https://docs.rome.builders/ko/reference/contract-addresses.md#reading-the-contracts-list) 는 방법을 보여줍니다. 앱이 실시간으로 읽지 않는 사실들도 [Contract Addresses](https://docs.rome.builders/ko/reference/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 레인 쓰기 경로: 가스 산정은 `eth_estimateGas` 에서 하고(패딩 적용, 추정이 실패하면 대체 상한 사용), EIP-1559 수수료를 제공합니다.
* **`submitRomeTxV1`** — 동일한 기능을 **Solana 지갑** 으로 EVM 앱을 구동할 때 사용: 호출당 Solana v1 트랜잭션 하나, 지갑 프롬프트 두 번. 합성 송신자는 정지 상태에서 아무 것도 보유하지 않으며; `buildFundLeg`/`buildSweepLeg` 가치를 안팎으로 이동시키는 ERC-20(`wUSDC`), **가 아니라** 네이티브 `msg.value`; 호출 주변의 일반 Solana 지침(펀드 레그, 스윕 전에 지갑 토큰 계정 생성)은 `submitSolanaInstructionsV1` 을 통해서도 v1 트랜잭션으로 전달됩니다. `submitRomeTxSolanaLane` 는 이전 경로로, 클라이언트에서 레거시 Solana 트랜잭션을 만들고 처음 사용할 때 새 합성(`create_pda`)를 자동으로 프로비저닝합니다.
* **PDA/ATA 파생, CPI `invoke`/`invoke_signed` 인코더, 프리컴파일 바인딩**, 그리고 **`/bridge`** 하위 경로(`@rome-protocol/sdk/bridge`) — 견적 우선 브리지 클라이언트.

전체 API + 예제: [Rome SDK](https://docs.rome.builders/ko/products/rome-sdk.md), 그리고 가이드 [EVM에서 Solana 호출](https://docs.rome.builders/ko/developer-guides/call-solana-from-evm.md), [Solana에서 EVM 호출](https://docs.rome.builders/ko/developer-guides/call-evm-from-solana.md), 그리고 [듀얼 레인 앱 빌드](https://docs.rome.builders/ko/developer-guides/dual-lane-app.md).

### rome-solidity — 계약 측 툴킷

npm이 아니라 GitHub에서 설치하세요. 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`, 그래서 동일한 import 경로가 둘 다에서 작동합니다.

계약에서 import하는 것:

* **`contracts/interface.sol`** — 주소에 바인딩된 프리컴파일 인터페이스: **CPI** `ICrossProgramInvocation` (`0xFF…08`), **Helper** `IHelperProgram` (`0xFF…09`, ATA/PDA 생성, SPL 전송, gas↔lamports), **출금** `IWithdraw` (`0x42…16`), 그리고 **System** (`0xFF…07`). 가스 최적화된 **캐시된** 계열도 여기에 있습니다; 계약은 한 경로를 일관되게 사용합니다. 전체 주소표: [Contract Addresses](https://docs.rome.builders/ko/reference/contract-addresses.md).
* **SPL/ERC-20 래퍼** — `SPL_ERC20` (CPI 기반) 및 `SPL_ERC20_cached` (캐시된 경로, devnet에서 사용); 모든 SPL mint는 이들을 통해 이미 ERC-20입니다.
* **오라클 어댑터** (`contracts/oracle/`) — Pyth/Switchboard 어댑터 `rome-oracle-gateway` 배포, 다음을 통해 읽음 `IAggregatorV3Interface`.
* 실전 예제는 `contracts/examples/`.

에 있습니다. [Rome SDK](https://docs.rome.builders/ko/products/rome-sdk.md) 의 Solidity SDK 섹션은 import 패턴과 프리컴파일 바인딩을 코드로 보여줍니다.

## 다음 단계

* [핵심을 선택하세요](https://docs.rome.builders/ko/core-concepts/choose-your-core.md) — 로직을 어느 쪽이 보유할지.
* [빠른 시작](https://docs.rome.builders/ko/getting-started-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/ko/getting-started-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.
