> 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/vi/bat-dau-1/ecosystem.md).

# Hệ sinh thái & các repo

Mọi repo công khai của Rome, chúng là gì, và cách chúng kết hợp với nhau — bản đồ để điều hướng bề mặt.

Bề mặt công khai của Rome là một tập hợp các kho lưu trữ: vài **nền tảng** các gói bạn xây dựng trên đó, một bộ khung, các ứng dụng tham chiếu để học từ, và hai dịch vụ mà ứng dụng của bạn gọi. Trang này là bản đồ — mỗi repo là gì và chúng khớp với nhau như thế nào.

Hai mục lân cận trả lời các câu hỏi khác nhau, và trang này liên kết đến cả hai thay vì lặp lại chúng:

* [Kiến trúc](https://docs.rome.builders/vi/bat-dau-1/architecture.md) giải thích **giao thức** — cách EVM chạy bên trong một chương trình Solana.
* Mỗi repo đều đi kèm một **`AGENTS.md`** (ví dụ: [rome-sdk-ts/AGENTS.md](https://github.com/rome-protocol/rome-sdk-ts/blob/main/AGENTS.md)) dùng để điều hướng theo **điểm xuất phát của bạn** (một hợp đồng Solidity, một chương trình Solana, greenfield, từ home) tới ví dụ gần nhất với trường hợp của bạn.

Trang này là tầng trung gian: toàn bộ **bề mặt tổng thể** và cách các mảnh ghép kết nối với nhau.

## Bề mặt nhìn lướt qua

### Nền tảng — xây dựng trên các mục này

| Repo                                                            | Nó là gì                                                                                                                                                        | Tìm đến nó khi                                               |
| --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
| [rome-registry](https://github.com/rome-protocol/rome-registry) | `@rome-protocol/registry` — bản chiếu chỉ đọc, được tạo ra của các thông tin chuỗi trực tiếp (id, RPC, địa chỉ, mint token, program id, nguồn oracle, ALT).     | Bạn cần một thông tin chuỗi thực tế — đừng bao giờ hardcode. |
| [rome-sdk-ts](https://github.com/rome-protocol/rome-sdk-ts)     | `@rome-protocol/sdk` — đường ghi bằng TypeScript: `submitRomeTx` + tính cỡ phí, cả hai làn, bộ mã hóa PDA/ATA + CPI, liên kết precompile, một `/bridge` client. | Bạn đang viết mã ứng dụng hoặc frontend.                     |
| [rome-solidity](https://github.com/rome-protocol/rome-solidity) | Các giao diện precompile Solidity, các bộ bao bọc SPL/ERC-20, và các bộ chuyển đổi oracle — bộ công cụ phía hợp đồng.                                           | Bạn đang viết hợp đồng.                                      |

Các `@rome-protocol/…` tên ở trên là tên gói, nhưng các gói không được phát hành lên npm. Cài chúng từ GitHub (lệnh nằm trong mỗi phần dưới đây [Lớp nền tảng, nhìn cận cảnh](#the-foundation-layer-up-close)); đường dẫn import trong mã của bạn vẫn giữ nguyên.

### Các rollup ZK EVM của Rome

| Repo                                                            | Nó là gì                                                            | Tìm đến nó khi                                               |
| --------------------------------------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------ |
| [solana-zk-evm](https://github.com/rome-protocol/solana-zk-evm) | Các chương trình ZK rollup, node, prover và tài liệu operator.      | Bạn đang vận hành một chuỗi EVM thanh toán trên Solana.      |
| [rome-zk-guest](https://github.com/rome-protocol/rome-zk-guest) | Mã nguồn guest theo batch được xây dựng cho genesis của từng chuỗi. | Bạn đang xây dựng một guest và yêu cầu khóa xác minh của nó. |

### Ostia (ZK EVM trên Canton)

| Repo                                                                                  | Nó là gì                                                                                                                                | Tìm đến nó khi                                                                                                                                                                                                 |
| ------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [canton-zk-evm](https://github.com/rome-protocol/canton-zk-evm/blob/v0.1.0/README.md) | Ostia, một ZK EVM trên Canton: mỗi block EVM đã được chứng minh được ghi nhận cùng với các hành động Canton của nó trong một giao dịch. | Bạn đang xây dựng trên Ostia DevNet ([explorer](https://ostia.devnet.romeprotocol.xyz/)) hoặc vận hành Ostia của riêng bạn. Xem [Canton ZK EVM](https://docs.rome.builders/vi/canton-zk-evm/canton-zk-evm.md). |

### Ứng dụng tham chiếu — học qua ví dụ

| Repo                                                                    | Nó là gì                                                                                              | Tìm đến nó khi                                          |
| ----------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------- |
| [rome-dex](https://github.com/rome-protocol/rome-dex)                   | AMM hai làn — một pool Solana gốc với một bộ định tuyến EVM mỏng.                                     | Mở làn còn lại; một **native-core** ví dụ.              |
| [aerarium](https://github.com/rome-protocol/aerarium)                   | Cho vay hai làn — một lõi Comet bằng Solidity mà người dùng Solana truy cập qua một synthetic sender. | Mở làn còn lại; một **Solidity-core** ví dụ.            |
| [cardo](https://github.com/rome-protocol/cardo)                         | Người dùng EVM điều khiển các dApp Solana (swap/stake/lend/perps) qua CPI.                            | Một ứng dụng CPI-to-Solana đã hoàn thiện để nghiên cứu. |
| [appia](https://github.com/rome-protocol/appia)                         | DeFi xuyên VM lấy vị thế làm đầu; người dùng truy cập nó từ chuỗi nhà của họ.                         | Một **từ home** ứng dụng.                               |
| [rome-aave-v3-demo](https://github.com/rome-protocol/rome-aave-v3-demo) | Cung cấp/vay/trả nợ Aave v3, được triển khai nguyên trạng.                                            | Một ứng dụng EVM hoàn chỉnh chạy nguyên trạng.          |

### Các nhánh fork hợp đồng — các giao thức quen thuộc, được triển khai trên Rome

| Repo                                                                              | Nó là gì                                 | Tìm đến nó khi                  |
| --------------------------------------------------------------------------------- | ---------------------------------------- | ------------------------------- |
| [compound-on-rome-comet](https://github.com/rome-protocol/compound-on-rome-comet) | Thị trường tiền tệ Compound III (Comet). | Fork một giao thức EVM đã biết. |
| [rome-aave-v3](https://github.com/rome-protocol/rome-aave-v3)                     | Bản fork hợp đồng Aave v3.               | Fork một giao thức EVM đã biết. |

### Dịch vụ — ứng dụng của bạn gọi các dịch vụ này

| Repo                                                                        | Nó là gì                                                                                        | Tìm đến nó khi                           |
| --------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | ---------------------------------------- |
| [rome-bridge-api](https://github.com/rome-protocol/rome-bridge-api)         | Bộ điều phối ngoài chuỗi + nhà tài trợ phí cho cầu nối on-chain. Không giữ khóa.                | Nạp tiền vào ví, hoặc một luồng từ home. |
| [rome-oracle-gateway](https://github.com/rome-protocol/rome-oracle-gateway) | Các nguồn giá Solana (Pyth, Switchboard) được đưa ra EVM qua Chainlink `AggregatorV3Interface`. | Bạn cần một nguồn giá.                   |

### Khung sườn — bắt đầu ở đây

| Repo                                                                | Nó là gì                                                                                                                                    | Tìm đến nó khi            |
| ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- |
| [create-rome-app](https://github.com/rome-protocol/create-rome-app) | `npx github:rome-protocol/create-rome-app` — dựng sẵn một ứng dụng hai làn được nối sẵn với registry + SDK, kèm kiểm tra cả hai làn có vốn. | Bắt đầu một ứng dụng mới. |

## Chúng kết hợp như thế nào

```mermaid
sơ đồ luồng TD
    REG["rome-registry — thông tin chuỗi trực tiếp"]
    SDK["rome-sdk-ts — ghi, CPI, client cầu nối"]
    SOL["rome-solidity — giao diện precompile, bộ bao bọc SPL, bộ chuyển đổi oracle"]
    CRA["create-rome-app — công cụ dựng khung"]
    APP["ứng dụng của bạn — frontend + hợp đồng"]
    BAPI["rome-bridge-api — bộ điều phối ngoài chuỗi, không giữ khóa"]
    OG["rome-oracle-gateway — nguồn giá Solana"]

    CRA -->|dựng khung, nối sẵn| APP
    REG -->|thông tin, không bao giờ hardcode| APP
    SDK -->|đường ghi & CPI| APP
    SOL -->|được hợp đồng của bạn import| APP
    APP -->|SDK /bridge client| BAPI
    APP -->|đọc qua AggregatorV3Interface| OG
    OG -.->|bộ chuyển đổi nằm trong| SOL
    CRA -.->|nối| REG
    CRA -.->|nối| SDK
```

Trục chính gồm ba nền tảng và một công cụ dựng khung:

* [**rome-registry**](https://github.com/rome-protocol/rome-registry) là nguồn duy nhất của các thông tin trực tiếp. [**rome-sdk-ts**](https://github.com/rome-protocol/rome-sdk-ts) là đường ghi — và `/bridge` đường con của nó là client mà ứng dụng của bạn dùng để nói chuyện với `rome-bridge-api`. [**rome-solidity**](https://github.com/rome-protocol/rome-solidity) là thứ mà các hợp đồng của bạn (và các fork) import; các bộ chuyển đổi oracle mà `rome-oracle-gateway` cũng được triển khai ở đó. Cả ba độc lập với nhau — hãy chọn những gì ứng dụng của bạn cần.
* [**create-rome-app**](https://github.com/rome-protocol/create-rome-app) kết nối hai phần đầu cho một ứng dụng mới, để một dự án mới bắt đầu đã đọc registry và ghi qua SDK.

Các ứng dụng tham chiếu là ngoại lệ đáng biết: **chúng có trước các gói đã được tách ra.** cardo sử dụng gói registry; appia chiếu registry sang JSON tĩnh khi build; và cả hai tự đóng gói đường ghi của mình thay vì import SDK. Hãy đọc chúng để học các mẫu — nhưng một **mới** ứng dụng nên bắt đầu từ `create-rome-app` + các gói, chứ không phải bằng cách sao chép một ứng dụng.

## Điều hướng theo thứ bạn cần

* **Một thông tin chuỗi trực tiếp** (id, địa chỉ, mint, program id) → [rome-registry](https://github.com/rome-protocol/rome-registry). Đừng bao giờ hardcode.
* **Viết mã ứng dụng** (một thao tác ghi, một lời gọi CPI, một cầu nối) → [rome-sdk-ts](https://github.com/rome-protocol/rome-sdk-ts); tham khảo tại [Rome SDK](https://docs.rome.builders/vi/san-pham/rome-sdk.md).
* **Viết hợp đồng** → [rome-solidity](https://github.com/rome-protocol/rome-solidity); xem [Triển khai Hợp đồng Solidity](https://docs.rome.builders/vi/huong-dan-cho-nha-phat-trien/deploy-solidity.md).
* **Gọi một chương trình Solana từ hợp đồng Solidity** → precompile CPI trong [rome-solidity](https://github.com/rome-protocol/rome-solidity) (`interface.sol`); [cardo](https://github.com/rome-protocol/cardo) là một ví dụ đã hoàn thiện.
* **Một ví dụ hoạt động** của một ứng dụng AMM, lending, CPI, hoặc from-home → các ứng dụng tham chiếu ở trên; mỗi repo `AGENTS.md` điều hướng theo điểm bắt đầu.
* **Dựng khung cho ứng dụng mới** → [create-rome-app](https://github.com/rome-protocol/create-rome-app).
* **Một nguồn giá** → [rome-oracle-gateway](https://github.com/rome-protocol/rome-oracle-gateway) (xem [cổng Oracle Gateway](https://docs.rome.builders/vi/ung-dung-tren-rome/oracle-gateway.md)).
* **Người dùng trên chuỗi khác** → [Từ home](https://docs.rome.builders/vi/huong-dan-cho-nha-phat-trien/from-home.md) + [rome-bridge-api](https://github.com/rome-protocol/rome-bridge-api).
* **Quyết định phía nào giữ logic của bạn** → [Chọn lõi của bạn](https://docs.rome.builders/vi/cac-khai-niem-cot-loi/choose-your-core.md).

## Lớp nền tảng, nhìn cận cảnh

### rome-registry — thông tin trực tiếp, công khai theo thiết kế

Registry được **tạo ra** từ nguồn nội bộ của Rome: một allowlist chỉ phát ra những gì được phép công khai, **thay thế** các endpoint nội bộ bằng các tương đương công khai của chúng, và **mặc định từ chối** mọi thứ khác — nên nó an toàn để công khai ngay từ thiết kế. Nó công bố, theo từng chuỗi, `chain.json` / `tokens.json` / `contracts.json` / `oracle.json` / `bridge.json` / `alts.json`, cùng với Solana `các chương trình` và các triển khai ứng dụng theo từng giao thức.

Cài nó từ GitHub, cố định theo một thẻ phát hành: `npm install github:rome-protocol/rome-registry#v0.2.0`. Bạn đọc nó thông qua các getter — `getChain`, `getTokens`, `getContracts`, `getOracle`, `getBridge`, `getAlts`, và `getPrograms(network)` (program id được khóa theo network, không phải chain id). Gói này là ESM thuần (hiện không có type TypeScript đi kèm).

Có hai điều cần biết trước khi tích hợp nó:

* **`getTokens()` không trả về `assetRef`.** Để tìm wrapper của một token, hãy đối chiếu theo **mint** (`mintId`) — ví dụ, wrapper của token gas là mục có cùng mint với nó.
* **Nó đọc JSON từ đĩa (`node:fs`) — nó không an toàn cho trình duyệt.** Trong một ứng dụng web, hãy chiếu các giá trị bạn cần sang một tệp JSON tĩnh khi build và import nó trong client. (Đó chính xác là điều mà `create-rome-app` và appia làm.)

Địa chỉ hợp đồng trả về dưới dạng danh sách các phiên bản cho mỗi hợp đồng; hãy chọn phiên bản có `trạng thái` là `đang hoạt động`. [Đọc danh sách hợp đồng](https://docs.rome.builders/vi/tai-lieu-tham-khao/contract-addresses.md#reading-the-contracts-list) cho thấy cách làm. Các thông tin mà ứng dụng của bạn không đọc trực tiếp cũng xuất hiện trong phần [Địa chỉ hợp đồng](https://docs.rome.builders/vi/tai-lieu-tham-khao/contract-addresses.md) tham chiếu.

### rome-sdk-ts — đường ghi, cả hai làn

Cài từ GitHub: `npm install github:rome-protocol/rome-sdk-ts#v0.4.0`.

`@rome-protocol/sdk` (v0.4.0) bao bọc mọi thứ mà một lần ghi của Rome cần, để bạn không phải tự viết calldata hay phí:

* **`submitRomeTx`** — đường ghi của làn EVM: tính gas dựa trên `eth_estimateGas` (được đệm, với một mức trần dự phòng khi việc ước lượng bị revert) và cung cấp phí EIP-1559.
* **`submitRomeTxV1`** — tương tự, cho một **ví Solana** điều khiển ứng dụng EVM của bạn: mỗi lần gọi là một giao dịch Solana v1, hai lần nhắc ví. Synthetic sender không giữ gì khi nghỉ; `buildFundLeg`/`buildSweepLeg` di chuyển giá trị ra vào dưới dạng ERC-20 (`wUSDC`), **không phải** native `msg.value`; các lệnh Solana thuần xung quanh một cuộc gọi (fund leg, việc tạo token-account của ví trước khi sweep) đi qua `submitSolanaInstructionsV1` cũng dưới dạng giao dịch v1. `submitRomeTxSolanaLane` là đường cũ hơn, xây dựng một giao dịch Solana kiểu cũ trong client và tự động cấp phát một synthetic mới (`create_pda`) khi dùng lần đầu.
* **Suy diễn PDA/ATA, CPI `invoke`/`invoke_signed` bộ mã hóa, liên kết precompile**, và một **`/bridge`** đường con (`@rome-protocol/sdk/bridge`) — client cầu nối ưu tiên báo giá.

API đầy đủ + ví dụ: [Rome SDK](https://docs.rome.builders/vi/san-pham/rome-sdk.md), và các hướng dẫn [Gọi Solana từ EVM](https://docs.rome.builders/vi/huong-dan-cho-nha-phat-trien/call-solana-from-evm.md), [Gọi EVM từ Solana](https://docs.rome.builders/vi/huong-dan-cho-nha-phat-trien/call-evm-from-solana.md), và [Xây dựng một ứng dụng hai làn](https://docs.rome.builders/vi/huong-dan-cho-nha-phat-trien/dual-lane-app.md).

### rome-solidity — bộ công cụ phía hợp đồng

Cài từ GitHub, không phải npm. Với npm hoặc Hardhat: `npm install github:rome-protocol/rome-solidity`. Với Foundry: `forge install rome-protocol/rome-solidity`, rồi thêm remapping `@rome-protocol/rome-solidity/=lib/rome-solidity/` vào `foundry.toml` (trong `[profile.default]`, dưới dạng `remappings = [...]`) để `@rome-protocol/rome-solidity/contracts/interface.sol` được phân giải. Tên gói trong `package.json` là `@rome-protocol/rome-solidity`, nên cùng một đường dẫn import dùng được cho cả hai.

Những gì hợp đồng của bạn import:

* **`contracts/interface.sol`** — các giao diện precompile gắn với địa chỉ của chúng: **CPI** `ICrossProgramInvocation` (`0xFF…08`), **Helper** `IHelperProgram` (`0xFF…09`, tạo ATA/PDA, chuyển SPL, gas↔lamports), **Withdraw** `IWithdraw` (`0x42…16`), và **System** (`0xFF…07`). Một **cached** họ hàng tối ưu gas cũng nằm ở đây; một hợp đồng dùng một track nhất quán. Bảng địa chỉ đầy đủ: [Địa chỉ hợp đồng](https://docs.rome.builders/vi/tai-lieu-tham-khao/contract-addresses.md).
* **Bộ bao bọc SPL/ERC-20** — `SPL_ERC20` (dựa trên CPI) và `SPL_ERC20_cached` (track cached, dùng trên devnet); bất kỳ mint SPL nào cũng đã là một ERC-20 thông qua chúng.
* **Bộ chuyển đổi oracle** (`contracts/oracle/`) — các bộ chuyển đổi Pyth/Switchboard `rome-oracle-gateway` được triển khai, đọc qua `IAggregatorV3Interface`.
* Các ví dụ hoàn chỉnh trong `contracts/examples/`.

Phần Solidity SDK của [Rome SDK](https://docs.rome.builders/vi/san-pham/rome-sdk.md) cho thấy các mẫu import và các liên kết precompile trong mã.

## Tiếp theo là gì

* [Chọn lõi của bạn](https://docs.rome.builders/vi/cac-khai-niem-cot-loi/choose-your-core.md) — phía nào giữ logic của bạn.
* [Bắt đầu nhanh](https://docs.rome.builders/vi/bat-dau-1/quickstart.md) — triển khai hợp đồng đầu tiên của bạn.
* [create-rome-app](https://github.com/rome-protocol/create-rome-app) — dựng khung một ứng dụng hai làn.
* Của mỗi repo `AGENTS.md` — lộ trình theo điểm bắt đầu đến ví dụ gần nhất.


---

# 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/vi/bat-dau-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.
