> 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/cac-khai-niem-cot-loi/token-interop.md).

# Tương tác token

Cách token ERC-20 và SPL thực chất là cùng một account nền tảng trên Rome.

Rome biểu diễn một token ERC-20 và token SPL cơ sở của nó dưới dạng một tài khoản dùng chung. Trang này giải thích cách token hoạt động trên EVM và Solana.

## Mô hình trạng thái dùng chung

Đối với ví thông thường, token ERC-20 trên Rome là một **lớp bọc trong suốt** cho tài khoản token SPL trên Solana. Số dư ERC-20 của ví chính là số dư SPL. Một địa chỉ được tạo dẫn xuất từ chương trình (PDA) cho địa chỉ EVM sở hữu tài khoản token. Đây là **PDA có quyền kiểm soát bên ngoài**.

<figure><img src="https://4233397286-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F671PKS8ZQSNqtoC8PGvz%2Fuploads%2Fgit-blob-552c639322c2d0e90b312def5db39d06c1871d18%2Ftoken-interop.svg?alt=media" alt="An EVM address and its Solana token account, owned by its external-authority PDA. Multiple wrappers read the same token account. The wrapper escrow account and Solana pool vaults hold tokens of the same Solana mint."><figcaption></figcaption></figure>

* Không có độ trễ đồng bộ: số dư ERC-20 của ví chính là số dư SPL.
* Các ví thông thường, bao gồm ví MetaMask và địa chỉ tổng hợp, không bị phân mảnh thanh khoản. Mọi lớp bọc trên cùng một mint đều hiển thị số dư giống nhau của ví. Phương thức `balanceOf` đọc số dư đó từ tài khoản token của ví. Token được giữ bên trong các hợp đồng EVM được lưu theo từng lớp bọc (xem [Hợp đồng lớp bọc](#the-wrapper-contract)).
* Đối với token của ví, không có gì bị khóa ở một bên rồi được đúc ở bên kia. Token do hợp đồng nắm giữ nằm trong tài khoản token ký quỹ riêng của lớp bọc trên Solana. Mỗi lớp bọc theo dõi riêng các token đó.

**Vì sao lớp bọc thứ hai không chia tách số dư**

Hai lớp bọc trên cùng một mint hiển thị số dư giống nhau của ví. Các lớp bọc đọc `totalSupply` từ mint Solana. Trên Hadrian (testnet), ba lớp bọc wUSDC trả về số dư ví trùng khớp. Cả ba lớp bọc wUSDC (9.0.0, 8.0.0 và May 2026) đều trả về tổng cung của mint Solana.

Mỗi factory chỉ cho phép một lớp bọc trên mỗi mint. Phiên bản factory mới có thể triển khai một lớp bọc khác cho mint đó. Sổ đăng ký chỉ định lớp bọc chính tắc cho từng chain.

Ví Solana nắm giữ USDC trực tiếp và một địa chỉ EVM cùng nắm giữ token của cùng một mint. Các pool Solana sử dụng cùng vault và cùng lượng dự trữ cho cả hai.

Bảng chủ sở hữu trong [Via explorer](https://docs.rome.builders/vi/ung-dung-tren-rome/via.md) được tạo từ các sự kiện `Transfer` của từng lớp bọc. Bảng này có thể khác với số dư tài khoản token vì các giao dịch chuyển SPL trực tiếp, `ActivateAta`và giao dịch chuyển qua lớp bọc khác không xuất hiện trong các sự kiện của lớp bọc đó.

> Các đường dẫn import bên dưới sử dụng `@rome-protocol/rome-solidity`. Gói này không có trên npm; hãy cài đặt từ kho lưu trữ công khai [`rome-solidity`](https://github.com/rome-protocol/rome-solidity) bằng lệnh `npm install github:rome-protocol/rome-solidity`hoặc `forge install rome-protocol/rome-solidity` kèm cấu hình remapping; các hợp đồng lớp bọc và factory cũng cần OpenZeppelin trong Foundry (xem [Triển khai hợp đồng Solidity](https://docs.rome.builders/vi/huong-dan-cho-nha-phat-trien/deploy-solidity.md#using-the-rome-solidity-sdk)). Các giao diện precompile nằm trong [`contracts/interface.sol`](https://github.com/rome-protocol/rome-solidity/blob/master/contracts/interface.sol).

## Hợp đồng lớp bọc

`SPL_ERC20` (và biến thể cached-track `SPL_ERC20_cached`, được factory triển khai cho mọi mint, trừ mint có transfer hook đang hoạt động; xem [Các mint Token-2022](#token-2022-mints)) cung cấp giao diện ERC-20 đầy đủ cho một mint SPL:

* `balanceOf()` — đọc số dư ATA của người dùng từ Solana (với địa chỉ hợp đồng, phương thức này đọc sổ cái riêng của lớp bọc; xem bên dưới)
* `transfer()` / `transferFrom()` — chuyển token trên Solana
* `approve()` / `allowance()` — các khoản cấp quyền ERC-20 cho từng người chi tiêu được lưu trong bộ nhớ EVM (tài khoản token SPL không có cơ chế cấp quyền kiểu EVM). Chúng tách biệt với quyền cấp một lần bên dưới: để có thể chuyển token của người dùng, wrapper hoạt động với tư cách delegate SPL của người dùng đó, và người dùng cấp quyền này một lần cho mỗi ví
* `totalSupply()` — đọc tổng cung của mint SPL

Hợp đồng không thể cấp quyền một lần này, vì vậy token của hợp đồng được giữ trong tài khoản token riêng của wrapper và theo dõi trong sổ cái của wrapper. `balanceOf(contract)` đọc sổ cái đó.

## Factory

`ERC20SPLFactory` triển khai wrapper cho bất kỳ mint SPL nào:

```solidity
import {ERC20SPLFactory} from "@rome-protocol/rome-solidity/contracts/erc20spl/erc20spl_factory.sol";

// Deploy a wrapper, loading name/symbol from the mint's Token-2022 metadata or Metaplex
address wrapper = factory.add_spl_token_with_metadata(splMint);

// Or specify name/symbol manually
address wrapper = factory.add_spl_token_no_metadata(splMint, "USD Coin", "USDC");
```

Địa chỉ factory đang hoạt động, lấy từ các mục `live` trong registry (v0.2.0): Hadrian `0x37c13e4ff21fb914eb24014dcbd0f8dbeaa31078`. Các factory cũ vẫn còn trên chuỗi nhưng được đánh dấu là `deprecated` hoặc `retired` trong [registry](https://github.com/rome-protocol/rome-registry/tree/main/chains); không sử dụng chúng. Registry là nguồn thông tin chuẩn, vì vậy hãy đọc địa chỉ đang hoạt động từ đó (xem [Đọc danh sách hợp đồng](https://docs.rome.builders/vi/tai-lieu-tham-khao/contract-addresses.md#reading-the-contracts-list)) thay vì sao chép địa chỉ vào mã của bạn.

## Các mint chuẩn

Không có hợp đồng registry token trên chuỗi. Các wrapper chuẩn và token gas/cầu nối được tuyển chọn trong [`rome-protocol/registry`](https://github.com/rome-protocol/rome-registry)ngoại tuyến; các wrapper không cần cấp phép được tạo bằng `add_spl_token_no_metadata` được phát hiện thông qua sự kiện trên chuỗi `TokenCreated`  . Registry chỉ định wrapper chuẩn cho từng mint trên mỗi chuỗi. Số dư ví được dùng chung giữa các wrapper. Mỗi wrapper theo dõi riêng số dư do các hợp đồng EVM nắm giữ.

## Thao tác SPL từ Solidity

Đối với các thao tác SPL nguyên thủy được ký bằng PDA của người dùng, hãy dùng precompile **HelperProgram** (`0xFF…09`) — tạo ATA, chuyển SPL và chuyển đổi gas↔lamports:

```solidity
import {IHelperProgram} from "@rome-protocol/rome-solidity/contracts/interface.sol";

IHelperProgram helper = IHelperProgram(0xFF00000000000000000000000000000000000009);

helper.create_ata(user, mint);              // create the user's ATA for a mint
helper.transfer_spl(to, tokens, mint);      // transfer SPL from the caller's PDA
```

`transfer_spl` có một số phiên bản nạp chồng (bao gồm phiên bản delegate cho các luồng `transferFrom` ); xem `interface.sol` cho chữ ký chính xác. Trên luồng cached, các thao tác tương đương nằm trên `ISplCached` (`0xFF…05`) và `IAssociatedSplCached` (`0xFF…06`). Một hợp đồng sử dụng nhất quán một luồng.

## Cấp quyền một lần cho mỗi ví

Wrapper di chuyển token của người dùng với tư cách là **SPL delegate** của tài khoản token của người dùng đó. Vì vậy, ví cần cấp quyền này một lần cho mỗi wrapper trước khi wrapper có thể di chuyển token thay mặt ví. Việc cấp quyền chỉ cần một lần gọi đến precompile Helper (`0xff00000000000000000000000000000000000009`):

```solidity
helper.approve_spl(wrapper, type(uint64).max, mint);   // approve_spl(wrapper, 2^64-1, mint)
```

`approve_spl` được ký bằng chính tài khoản của người dùng, vì vậy người dùng gửi giao dịch này, không phải wrapper hay hợp đồng của bạn. Mint là `mint_id()` trên wrapper.

* **Ai cần cấp quyền.** Mọi ví EVM và mọi địa chỉ tổng hợp của người dùng Solana đều cần cấp quyền cho từng wrapper có token mà họ muốn di chuyển. Hợp đồng dùng `transferFrom` chỉ hoạt động với những người dùng đã cấp quyền cho wrapper.
* **Cách kiểm tra.** Gọi `isEnabled(user)` trên wrapper. Hàm trả về `true` khi quyền đã được cấp.
* **Biểu hiện khi chưa được cấp quyền.** Giao dịch chuyển token bị revert với lỗi SPL `0x4` (không khớp chủ sở hữu).
* **Mỗi tài khoản token chỉ có một delegate.** Tài khoản token SPL chỉ có một delegate. Cấp quyền cho chương trình khác trên cùng tài khoản token, chẳng hạn như cầu nối hoặc router, sẽ thay thế quyền của wrapper; wrapper sẽ ngừng hoạt động với người dùng đó cho đến khi họ cấp quyền lại. Hãy kiểm tra `isEnabled` trước khi chuyển token thay vì cho rằng quyền đã cấp trước đó vẫn còn hiệu lực.

Khi phiên bản factory mới thay thế một wrapper, mỗi ví cấp quyền cho wrapper mới bằng `approve_spl`. Wrapper cũ chỉ có thể di chuyển token của ví đó khi nó vẫn là delegate của tài khoản token. Cấp quyền cho wrapper mới sẽ thay thế delegate đó.

Hướng dẫn ứng dụng [dual-lane](https://docs.rome.builders/vi/huong-dan-cho-nha-phat-trien/dual-lane-app.md#one-time-grant-the-wrapper) có mã đầy đủ cho cả hai luồng.

## Nạp và rút

* **Vào EVM** — phía SPL ghi có vào ATA do PDA của người dùng sở hữu; wrapper ERC-20 lập tức phản ánh số dư. Các giao dịch chuyển vào từ chuỗi khác được quyết toán trên chuỗi thông qua ủy quyền do người dùng ký trên cầu nối.
* **Gói gas thành gas token** — gọi `Withdraw` precompile (`0x42…16`). `withdraw_to_ata(wei)` đốt gas gốc và ghi có số tiền tương đương, tính theo số chữ số thập phân của chính token gas, vào tài khoản token của bên gọi; sau đó, wrapper của token gas (ví dụ wUSDC) sẽ hiển thị số dư này. `withdraw_to_pda(wei)` chuyển lamport đến PDA của bên gọi và chỉ áp dụng trên chuỗi sử dụng SOL làm gas; lệnh sẽ revert trên Hadrian và Rubicon, vốn dùng USDC làm gas, vì vậy hãy dùng `withdraw_to_ata` ở đó. Số tiền được tính theo đơn vị gas có 18 chữ số thập phân và phải là số nguyên đơn vị token gas: trên chuỗi dùng USDC làm gas, số tiền phải là bội số của 10^12 (một đơn vị có 6 chữ số thập phân); nếu không, lệnh sẽ revert. `HelperProgram.deposit_from_ata(wei)` thực hiện theo chiều ngược lại, đổi token gas trong tài khoản token của bên gọi trở lại thành gas gốc, với cùng quy tắc về bội số. Đây là các thao tác chuyển đổi token gas, không phải lối rút các token khác.
* **Chuyển ra Solana các token khác** — số dư riêng của wrapper vốn đã là số dư SPL, nên việc chuyển ra chỉ là một giao dịch chuyển SPL:
  * `HelperProgram.transfer_spl_to_signer(amount, mint)` chuyển token của bên gọi đến tài khoản token của ví Solana đã ký giao dịch. Chặng chuyển về này chỉ đến được ví của chính người dùng khi giao dịch được ký bằng ví trên Solana. Nếu được gọi từ MetaMask hoặc qua relay, bên ký là bên trả phí proxy của Rome, nên lệnh sẽ thất bại hoặc token sẽ được gửi đến Rome. Thay vào đó, hãy dùng `transfer_spl` hoặc `RomeBridgeWithdraw.bridgeOutToSolana` trong trường hợp đó.
  * `RomeBridgeWithdraw.bridgeOutToSolana(solanaRecipient, amount, mint)` gửi token đến bất kỳ ví Solana nào. Lệnh này cần quyền cấp của người dùng cho hợp đồng bridge (`approve_spl(bridge, …)`, xem ghi chú về một delegate ở trên), đồng thời tài khoản token của người nhận phải tồn tại; `ensureRecipientAta(solanaRecipient, mint)` sẽ tạo tài khoản đó.
  * `RomeBridgeWithdraw` cũng đốt USDC để chuyển sang một chuỗi khác qua CCTP (`burnUSDC`) và gửi các tài sản khác qua Wormhole (`burnETH`, `burnToWormhole`).

Lấy địa chỉ `RomeBridgeWithdraw` đang hoạt động từ registry.

Để chuyển các token khác giữa Solana và Ethereum hoặc các chuỗi AggLayer, hãy xem [Solgate](https://docs.rome.builders/vi/ung-dung-tren-rome/solgate.md) và [13. Xây dựng trên Solgate](https://docs.rome.builders/vi/rome-academy/13-build-on-solgate.md).

## Token gas

Mỗi chuỗi có token gas riêng: SOL hoặc một token SPL. Nguồn giá của Rome Proxy có thể là nguồn dữ liệu API Hermes, pool Meteora DAMM v1, pool Meteora DAMM v2 hoặc một mức giá cố định. Hadrian (testnet) và Rubicon (mainnet) sử dụng USDC. Hadrian sử dụng USDC thử nghiệm. Rubicon sử dụng USDC thật. Không có token gas mặc định dùng chung cho mọi chuỗi.

## Mint Token-2022

Factory cũng bọc các mint Token-2022. Factory truy vấn precompile Helper để xác định loại mint bằng `mint_info(mint)` (selector `0xe24bf5d4`), rồi chọn wrapper dựa trên kết quả. `mint_info` trả về năm giá trị:

| Giá trị        | Ý nghĩa                                                                                                  |
| -------------- | -------------------------------------------------------------------------------------------------------- |
| `tokenProgram` | chương trình token sở hữu mint (chương trình SPL Token cổ điển hoặc Token-2022)                          |
| `decimals`     | số chữ số thập phân của mint                                                                             |
| `hookProgram`  | chương trình transfer-hook, hoặc giá trị 0 khi không có hook hoặc hook tồn tại nhưng chưa được kích hoạt |
| `feeBps`       | phí chuyển tiền tính theo điểm cơ bản, hoặc giá trị 0 khi không có phí hoặc phí được đặt thành 0         |
| `extensions`   | bitmap của các phần mở rộng Token-2022 mà mint có, bit N tương ứng với loại phần mở rộng N               |

Mint nhận được gì:

| Mint                                                                                               | Wrapper                                                                                              | `wrapper_kind_by_mint` |
| -------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | ---------------------- |
| Mint thông thường, mint Token-2022 không có hook, hoặc mint có hook nhưng hook chưa được kích hoạt | wrapper được lưu đệm (`SPL_ERC20_cached`)                                                            | `1`                    |
| Mint Token-2022 có transfer hook đã được kích hoạt                                                 | wrapper có hook (`SPL_ERC20_Token2022Hooked`), được triển khai thông qua `hooked_wrapper_deployer()` | `2`                    |

Mint có phí chuyển tiền sẽ nhận wrapper được lưu đệm, và sự kiện `Transfer` báo cáo số tiền thực nhận sau khi trừ phí, không phải số tiền đã gửi. Bạn có thể xem loại wrapper mà mint nhận được từ factory bằng `wrapper_kind_by_mint(mint)`; trên factory Hadrian đang hoạt động, các wrapper USDC, ETH và SOL đều trả về `1`.

Những trường hợp bị từ chối:

* Mint có transfer hook đã được kích hoạt không thể nhận một trong các wrapper thông thường. Triển khai `SPL_ERC20` hoặc `SPL_ERC20_cached` trực tiếp cho mint đó sẽ revert với `ArmedTransferHookUnsupported(mint, hookProgram)`. Với factory, trường hợp này sẽ được chuyển sang wrapper có hook.
* Địa chỉ không phải là mint SPL khiến `mint_info` revert với `Invalid SPL mint account: <address>`.
* Mint đã có wrapper sẽ revert với `Token exists`, còn symbol đã được sử dụng sẽ revert với `Token with symbol exists`.
* `add_spl_token_with_metadata` trước tiên đọc tên và symbol từ metadata Token-2022 của chính mint, sau đó mới đọc từ Metaplex. Nếu mint không có cả hai, hàm sẽ revert với `Mint asserts no name: use add_spl_token_no_metadata`.

Cách wrapper có hook hoạt động:

* Token-2022 chạy hook trên mỗi lần chuyển, và hook cần các tài khoản phụ thuộc vào giao dịch chuyển đó. Wrapper không thể tự xác định các tài khoản này, vì vậy bên gọi phải phân giải danh sách tài khoản đầy đủ từ danh sách extra-account-metas của mint rồi truyền vào. Wrapper kiểm tra phần cố định của danh sách đó (chương trình hook và tài khoản xác thực của nó), sau đó chuyển tiếp danh sách nguyên trạng.
* Lệnh `transfer`, `transferFrom` và `bridgeOutToSolana` hoàn tác bằng `HookAccountPlanRequired`. Sử dụng `transferWithHookAccounts`, `transferFromWithHookAccounts` và `bridgeOutToSolanaWithHookAccounts`, các hàm này nhận danh sách tài khoản làm đối số bổ sung.
* Nếu chương trình hook của mint thay đổi sau khi wrapper được triển khai, các giao dịch chuyển sẽ bị hoàn tác với lỗi `HookConfigurationChanged`.
* Cơ chế này chuyển token bằng cách gọi trực tiếp giữa các chương trình (luồng cũ) và không sử dụng luồng lưu đệm. Một hợp đồng sử dụng nhất quán một luồng; các lời gọi theo luồng cũ chỉ chạy trong quá trình thực thi nguyên tử, vì vậy lời gọi sử dụng wrapper hỗ trợ hook phải nằm gọn trong một giao dịch nguyên tử.
* Cơ chế này không duy trì sổ cái số dư của hợp đồng. Token gửi đến hợp đồng sẽ được chuyển vào tài khoản token riêng của hợp đồng, và hợp đồng chỉ có thể chuyển tiếp chúng sau khi đã cấp `approve_spl` quyền cho chính wrapper.
* Cơ chế này cần cùng một [lần cấp quyền duy nhất](#one-time-grant-per-wallet) như mọi wrapper khác.

## Các giới hạn

* Số lượng token SPL có kiểu `uint64` (tối đa 18.446.744.073.709.551.615)
* Hạn mức ERC-20 (`approve` / `allowance`) được lưu trong bộ nhớ EVM. Wrapper chuyển token với tư cách là người ủy quyền SPL của người dùng; người dùng cấp quyền này một lần cho mỗi wrapper (xem [Cấp quyền một lần cho mỗi ví](#one-time-grant-per-wallet))
* Ký hiệu wrapper ERC-20 phải là duy nhất trong mỗi factory

## Tiếp theo là gì

* [Địa chỉ hợp đồng](https://docs.rome.builders/vi/tai-lieu-tham-khao/contract-addresses.md) — precompile và địa chỉ theo từng chuỗi
* [Gọi Solana từ EVM](https://docs.rome.builders/vi/huong-dan-cho-nha-phat-trien/call-solana-from-evm.md) — CPI và các thao tác SPL từ Solidity
* [Cách Solana và EVM kết nối trên Rome](https://docs.rome.builders/vi/cac-khai-niem-cot-loi/how-solana-and-evm-meet.md)
* [Tích hợp chương trình Solana](https://docs.rome.builders/vi/huong-dan-cho-nha-phat-trien/integrate-solana-program.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/vi/cac-khai-niem-cot-loi/token-interop.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.
