> 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/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** gói để bạn xây dựng trên đó, một bộ scaffold, các ứng dụng tham chiếu để học hỏi, 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 repo lân cận trả lời những 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](/vi/bat-dau/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 kèm theo một **`AGENTS.md`** (ví dụ [rome-sdk-ts/AGENTS.md](https://github.com/rome-protocol/rome-sdk-ts/blob/main/AGENTS.md)) định tuyến theo **điểm bạn đang bắt đầu từ** (một hợp đồng Solidity, một chương trình Solana, greenfield, từ nhà) đến ví dụ gần nhất với trường hợp của bạn. Trang này là tầng ở giữa: **toàn bộ bề mặt** và cách các phần kết nối. ## Bề mặt nhìn qua ### Nền tảng — xây dựng trên những thứ này | Repo | Nó là gì | Hãy dùng nó khi | | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------- | | [rome-registry](https://github.com/rome-protocol/rome-registry) | `@rome-protocol/registry` — phần chiếu chỉ đọc, được tạo sinh từ các sự thật chuỗi thực (id, RPC, địa chỉ, mint token, program id, nguồn oracle, ALT). | Bạn cần một sự thật chuỗi thực — không bao giờ hardcode. | | [rome-sdk-ts](https://github.com/rome-protocol/rome-sdk-ts) | `@rome-protocol/sdk` — đường ghi TypeScript: `submitRomeTx` + tính kích thướ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) | giao diện precompile Solidity, các wrapper SPL/ERC-20, và các bộ điều hợp 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 (các lệnh nằm trong mỗi mục bên dưới [Lớp nền tảng, nhìn cận cảnh](#the-foundation-layer-up-close)); các đường import trong mã của bạn vẫn giữ nguyên. ### Rome ZK EVM rollups | Repo | Nó là gì | Hãy dùng nó khi | | --------------------------------------------------------------- | ------------------------------------------------------------------- | --------------------------------------------------------------- | | [solana-zk-evm](https://github.com/rome-protocol/solana-zk-evm) | Tài liệu về các chương trình ZK rollup, node, prover và operator. | Bạn đang chạy 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 verification key của nó. | ### Canton ZK EVM | Repo | Nó là gì | Hãy dùng nó khi | | ----------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | [canton-zk-evm](https://github.com/rome-protocol/canton-zk-evm/blob/a84e84e439a5cc669c0ae61facf7c8c995d9d564/README.md) | Ostia, một bản phát hành sớm của Canton zkEVM, thanh toán các block EVM đã được chứng minh và các hành động Canton trong một giao dịch. | Bạn đang chạy bản demo cục bộ hoặc nghiên cứu cổng và các kiểm tra bằng chứng của nó. Xem [Canton ZK EVM](/vi/canton-zk-evm/canton-zk-evm.md). | ### Ứng dụng tham chiếu — học bằng ví dụ | Repo | Nó là gì | Hãy dùng 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 ví dụ **native-core** . | | [aerarium](https://github.com/rome-protocol/aerarium) | Cho vay hai làn — một lõi Comet Solidity mà người dùng Solana truy cập qua một synthetic sender. | Mở làn còn lại; một ví dụ **Lõi Solidity** . | | [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 đã được làm mẫu để nghiên cứu. | | [appia](https://github.com/rome-protocol/appia) | DeFi xuyên VM ưu tiên positions; người dùng truy cập nó từ chuỗi gốc của họ. | Một ứng dụng **từ nhà** . | | [rome-aave-v3-demo](https://github.com/rome-protocol/rome-aave-v3-demo) | Nạp/vay/trả Aave v3, triển khai nguyên trạng. | Một ứng dụng EVM hoàn chỉnh chạy nguyên xi. | ### Fork hợp đồng — các giao thức quen thuộc, triển khai trên Rome | Repo | Nó là gì | Hãy dùng 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 quen thuộc. | | [rome-aave-v3](https://github.com/rome-protocol/rome-aave-v3) | Fork hợp đồng Aave v3. | Fork một giao thức EVM quen thuộc. | ### Dịch vụ — ứng dụng của bạn gọi những thứ này | Repo | Nó là gì | Hãy dùng nó khi | | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | --------------------------------------- | | [rome-bridge-api](https://github.com/rome-protocol/rome-bridge-api) | Bộ điều phối ngoài chuỗi + bên tài trợ phí cho cầu nối on-chain. Không giữ khóa nào. | Nạp tiền cho ví, hoặc một luồng từ nhà. | | [rome-oracle-gateway](https://github.com/rome-protocol/rome-oracle-gateway) | Nguồn giá Solana (Pyth, Switchboard) được đưa ra EVM qua Chainlink `AggregatorV3Interface`. | Bạn cần một nguồn giá. | ### Scaffold — bắt đầu tại đây | Repo | Nó là gì | Hãy dùng nó khi | | ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- | | [create-rome-app](https://github.com/rome-protocol/create-rome-app) | `npx github:rome-protocol/create-rome-app` — scaffold 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 cấp vốn. | Bắt đầu một ứng dụng mới. | ## Cách chúng kết hợp ```mermaid flowchart TD REG["rome-registry — sự thật chuỗi thực"] SDK["rome-sdk-ts — ghi, CPI, bridge client"] SOL["rome-solidity — giao diện precompile, wrapper SPL, bộ điều hợp oracle"] CRA["create-rome-app — scaffolder"] 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 -->|scaffold, nối sẵn| APP REG -->|sự thật, không hardcode| APP SDK -->|đường ghi & CPI| APP SOL -->|được import bởi hợp đồng của bạn| APP APP -->|SDK /bridge client| BAPI APP -->|đọc qua AggregatorV3Interface| OG OG -.->|các bộ điều hợp nằm trong| SOL CRA -.->|nối| REG CRA -.->|nối| SDK ``` Xương sống là ba nền tảng và một scaffolder: * [**rome-registry**](https://github.com/rome-protocol/rome-registry) là nguồn duy nhất của các sự thật 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à hợp đồng của bạn (và các fork) import; các bộ điều hợp oracle mà `rome-oracle-gateway` triển khai cũng nằm ở đó. Ba phần này độc lập với nhau — hãy chọn những phần ứ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 tiên lại với nhau 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 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 họ thay vì import SDK. Đọc chúng để học các mẫu — nhưng một **ứng dụng** mới nên bắt đầu từ `create-rome-app` + các gói, không phải bằng cách clone một ứng dụng. ## Điều hướng theo thứ bạn cần * **Một sự thật chuỗi thực** (id, address, mint, program id) → [rome-registry](https://github.com/rome-protocol/rome-registry). Không bao giờ hardcode. * **Viết mã ứng dụng** (một lệnh ghi, một lệnh gọi CPI, một bridge) → [rome-sdk-ts](https://github.com/rome-protocol/rome-sdk-ts); tham khảo tại [Rome SDK](/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](/vi/huong-dan-cho-nha-phat-trien/deploy-solidity.md). * **Gọi một chương trình Solana từ mộ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ụ đã làm mẫu. * **Một ví dụ hoạt động** của một AMM, lending, CPI, hoặc ứng dụng từ nhà → các ứng dụng tham chiếu ở trên; mỗi repo's `AGENTS.md` định tuyến theo điểm bắt đầu. * **Scaffolding một ứ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](/vi/ung-dung-tren-rome/oracle-gateway.md)). * **Người dùng trên chuỗi khác** → [Từ nhà](/vi/huong-dan-cho-nha-phat-trien/from-home.md) + [rome-bridge-api](https://github.com/rome-protocol/rome-bridge-api). * **Quyết định bên nào giữ logic của bạn** → [Chọn lõi của bạn](/vi/cac-khai-niem-cot-loi/choose-your-core.md). ## Lớp nền tảng, nhìn cận cảnh ### rome-registry — sự thật trực tiếp, công khai theo thiết kế Registry được **tạo sinh** 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 endpoint công khai tương ứng, và **mặc định từ chối** mọi thứ khác — nên nó an toàn để công khai theo thiết kế. Nó xuất bản, theo từng chain, `chain.json` / `tokens.json` / `contracts.json` / `oracle.json` / `bridge.json` / `alts.json`, cộng thêm Solana `programs` và các triển khai ứng dụng theo từng giao thức. Cài từ GitHub, ghim vào một thẻ phát hành: `npm install github:rome-protocol/rome-registry#v0.2.0`. Bạn đọc nó qua các getter — `getChain`, `getTokens`, `getContracts`, `getOracle`, `getBridge`, `getAlts`, và `getPrograms(network)` (program id được key theo network, không phải chain id). Gói là ESM thuần túy (hiện không có type TypeScript đi kèm). 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 khớp 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ó ở client. (Đây chính là điều `create-rome-app` và appia làm.) Địa chỉ hợp đồng được 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 bản có `trạng thái` là `live`. [Đọc danh sách hợp đồng](/vi/tai-lieu-tham-khao/contract-addresses.md#reading-the-contracts-list) cho thấy cách làm. Các sự thật mà ứng dụng của bạn không đọc trực tiếp cũng xuất hiện trong tham chiếu [Địa chỉ Hợp đồng](/vi/tai-lieu-tham-khao/contract-addresses.md) . ### 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) gói gọn mọi thứ một lệnh ghi Rome cần để bạn không phải tự viết calldata hay phí: * **`submitRomeTx`** — đường ghi làn EVM: tính kích thước gas từ `eth_estimateGas` (đã đệm, với trần dự phòng khi ướ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ột giao dịch Solana v1 cho mỗi lần gọi, hai lời nhắc ví. Synthetic sender không giữ gì ở trạng thái nghỉ; `buildFundLeg`/`buildSweepLeg` chuyển giá trị vào và ra như một ERC-20 (`wUSDC`), **không phải** native `msg.value`; các lệnh Solana thuần xung quanh một lần gọi (fund leg, việc tạo tài khoản token của ví trước một sweep) đi qua `submitSolanaInstructionsV1` cũng dưới dạng giao dịch v1. `submitRomeTxSolanaLane` là đường đi trước đó, tạo một giao dịch Solana legacy ở client và tự 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 precompile**, và một **`/bridge`** đường con (`@rome-protocol/sdk/bridge`) — bridge client ưu tiên báo giá trước. API đầy đủ + ví dụ: [Rome SDK](/vi/san-pham/rome-sdk.md), và các hướng dẫn [Gọi Solana từ EVM](/vi/huong-dan-cho-nha-phat-trien/call-solana-from-evm.md), [Gọi EVM từ Solana](/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](/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 phép remapping `@rome-protocol/rome-solidity/=lib/rome-solidity/` vào `foundry.toml` (trong `[profile.default]`, như `remappings = [...]`) để `@rome-protocol/rome-solidity/contracts/interface.sol` được resolve. Tên gói trong `package.json` là `@rome-protocol/rome-solidity`, nên cùng đường import hoạt động với cả hai. Các hợp đồng của bạn import gì: * **`contracts/interface.sol`** — các giao diện precompile được gắn với địa chỉ của chúng: **CPI** `ICrossProgramInvocation` (`0xFF…08`), **Helper** `IHelperProgram` (`0xFF…09`, ATA/PDA creation, SPL transfers, gas↔lamports), **Rút** `IWithdraw` (`0x42…16`), và **System** (`0xFF…07`). Một họ **cached** được tối ưu gas cũng nằm ở đây; một hợp đồng dùng một đường nhất quán. Bảng địa chỉ đầy đủ: [Địa chỉ Hợp đồng](/vi/tai-lieu-tham-khao/contract-addresses.md). * **Các wrapper SPL/ERC-20** — `SPL_ERC20` (dựa trên CPI) và `SPL_ERC20_cached` (đường cached, dùng trên devnet); mọi mint SPL đã là ERC-20 thông qua các thứ này. * **Các bộ điều hợp Oracle** (`contracts/oracle/`) — các bộ điều hợp Pyth/Switchboard `rome-oracle-gateway` triển khai, đọc qua `IAggregatorV3Interface`. * Các ví dụ làm mẫu trong `contracts/examples/`. Phần Solidity SDK của [Rome SDK](/vi/san-pham/rome-sdk.md) cho thấy các mẫu import và liên kết precompile trong mã. ## Tiếp theo là gì * [Chọn lõi của bạn](/vi/cac-khai-niem-cot-loi/choose-your-core.md) — bên nào giữ logic của bạn. * [Bắt đầu nhanh](/vi/bat-dau/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) — scaffold một ứng dụng hai làn. * Mỗi repo `AGENTS.md` — đường 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/ecosystem.md?ask=&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.