For the complete documentation index, see llms.txt. This page is also available as Markdown.

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 nền tảng của nó như 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 chia sẻ

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

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.
  • Không có độ trễ đồng bộ: số dư ERC-20 của ví chính là số dư SPL của nó.

  • 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ị cùng số dư ví. Hàm 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 giữ theo từng lớp bọc (xem Hợp đồng wrapper).

  • Đối với token của một ví, không có gì bị khóa ở một phía và được mint ở phía kia. Token do hợp đồng giữ nằm trong tài khoản ký quỹ token riêng của wrapper trên Solana. Mỗi wrapper theo dõi các token đó riêng biệt.

Vì sao một wrapper thứ hai không chia tách số dư

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

Mỗi factory cho phép một wrapper cho mỗi mint. Một phiên bản factory mới có thể triển khai một wrapper khác cho mint đó. Registry đặt tên wrapper chuẩn cho từng chain.

Một 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 dùng cùng vault và dự trữ cho cả hai.

Bảng người nắm giữ trong Qua trình khám phá được xây dựng từ Transfer các sự kiện. Nó có thể khác với số dư tài khoản token vì các chuyển khoản SPL trực tiếp, ActivateAta, và các chuyển khoản qua một wrapper khác không xuất hiện trong sự kiện của wrapper đó.

Các đường dẫn import dưới đây sử dụng @rome-protocol/rome-solidity. Gói này không có trên npm; hãy cài nó từ rome-solidity repo công khai bằng npm install github:rome-protocol/rome-solidity, hoặc forge install rome-protocol/rome-solidity với remapping; các hợp đồng wrapper và factory cũng cần OpenZeppelin dưới Foundry (xem Triển khai Hợp đồng Solidity). Các giao diện precompile nằm trong contracts/interface.sol.

Hợp đồng wrapper

SPL_ERC20 (và biến thể theo track cached của nó SPL_ERC20_cached, mà factory triển khai cho mọi mint ngoại trừ mint có transfer hook đã được kích hoạt; xem Các mint Token-2022) cung cấp một giao diện ERC-20 đầy đủ trên một mint SPL:

  • balanceOf() — đọc số dư ATA của người dùng từ Solana (đối với địa chỉ hợp đồng, nó đọc sổ cái riêng của wrapper, xem bên dưới)

  • transfer() / transferFrom() — di chuyển token trên Solana

  • approve() / allowance() — hạn mức ERC-20 theo từng bên nhận chi tiêu được lưu trong bộ nhớ EVM (một tài khoản token SPL không có cơ chế hạn mức kiểu EVM). Chúng tách biệt với quyền cấp một lần bên dưới: để di chuyển token của người dùng, wrapper sẽ đóng vai trò delegate SPL của người dùng đó, và người dùng cấp cho nó quyền đó một lần cho mỗi ví

  • totalSupply() — đọc tổng cung của mint SPL

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

Factory

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

Địa chỉ factory đang hoạt động, từ đang hoạt động các mục của registry (v0.2.0): Hadrian 0x37c13e4ff21fb914eb24014dcbd0f8dbeaa31078. Các factory trước đó vẫn còn trên chuỗi nhưng được đánh dấu là lỗi thời hoặc ngừng dùng trong registry; đừng sử dụng chúng. Registry là nguồn sự thật, vì vậy hãy đọc địa chỉ đang hoạt động từ đó (xem Đọc danh sách hợp đồng) thay vì sao chép một địa chỉ vào mã của bạn.

Các mint chuẩn

Không có hợp đồng token-registry on-chain. Các wrapper chuẩn và token gas/bridge được tuyển chọn trong rome-protocol/registry; các wrapper không cần cấp phép được tạo qua add_spl_token_no_metadata được phát hiện từ TokenCreated sự kiện on-chain. Registry đặt tên wrapper chuẩn cho mỗi mint trên mỗi chain. Số dư ví được chia sẻ giữa các wrapper. Mỗi wrapper riêng biệt theo dõi số dư do các hợp đồng EVM nắm giữ.

Các thao tác SPL từ Solidity

Đối với các primitive SPL được ký bởi user-PDA, hãy dùng HelperProgram precompile (0xFF…09) — tạo ATA, chuyển SPL, và chuyển đổi gas↔lamports:

transfer_spl có nhiều overload (bao gồm một biến thể delegate cho transferFrom các luồng); xem interface.sol để biết chữ ký chính xác. Trên track cached, các thao tác tương đương nằm trên ISplCached (0xFF…05và IAssociatedSplCached (0xFF…06). Một hợp đồng sử dụng nhất quán một track.

cần mỗi người dùng đã thực hiện việc này. Xem

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

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

  • Ai cần nó. Mọi ví EVM, và địa chỉ tổng hợp của mỗi người dùng Solana, cho mỗi wrapper có token mà nó muốn di chuyển. Một hợp đồng kéo token bằ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. Nó trả về true khi quyền cấp đã được thiết lập.

  • Khi thiếu nó sẽ trông như thế nào. Giao dịch chuyển hoàn nguyên 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. Một tài khoản token SPL chỉ có một delegate duy nhất. Cấp quyền cho một chương trình khác trên cùng tài khoản token, chẳng hạn bridge hoặc router, sẽ thay thế quyền cấp của wrapper, và wrapper ngừng hoạt động đối với người dùng đó cho đến khi họ cấp lại. Hãy kiểm tra isEnabled trước khi chuyển thay vì giả định rằng quyền cấp trước đó vẫn còn.

Khi một 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 đó.

Các hướng dẫn ứng dụng dual-lane có mã đầy đủ cho cả hai lane.

Nạp và rút

  • Vào EVM — phía SPL ghi có vào ATA thuộc sở hữu PDA của người dùng; wrapper ERC-20 phản ánh ngay số dư. Chuyển vào từ các chain khác được thanh toán on-chain thông qua một ủy quyền do người dùng ký trên bridge.

  • Bọc gas thành token gas — gọi Withdraw precompile (0x42…16). withdraw_to_ata(wei) đốt gas gốc và ghi có số lượng tương đương, theo số thập phân riêng của token gas, vào tài khoản token của bên gọi, rồi wrapper của token gas (ví dụ wUSDC) hiển thị thành số dư. withdraw_to_pda(wei) trả lamports cho PDA của bên gọi và chỉ áp dụng cho chain có gas là SOL; nó hoàn nguyên trên Hadrian và Rubicon, vốn dùng USDC làm gas, vì vậy hãy dùng withdraw_to_ata ở đó. Số lượng được tính theo đơn vị gas có 18 chữ số thập phân và phải là một số nguyên đơn vị token gas: trên chain dùng USDC làm gas thì phải là bội số của 10^12 (một đơn vị 6 chữ số thập phân), nếu không lời gọi sẽ hoàn nguyên. HelperProgram.deposit_from_ata(wei) đi theo chiều ngược lại và chuyển token gas trong tài khoản token của bên gọi trở lại gas gốc, với cùng quy tắc bội số. Đây là chuyển đổi token gas, không phải lối thoát cho các token khác.

  • Ra Solana, bất kỳ token nào khác — số dư riêng của wrapper vốn đã là số dư SPL, nên đưa nó ra ngoài là một chuyển SPL:

    • HelperProgram.transfer_spl_to_signer(amount, mint) gửi token của bên gọi đến tài khoản token của ví Solana đã ký giao dịch. Chặng quay về này chỉ đến được ví của chính người dùng trên lane Solana do ví ký. Khi được gọi từ MetaMask hoặc thông qua relay, bên ký là proxy payer của Rome, nên lời gọi sẽ thất bại hoặc token sẽ đi tới Rome. Hãy dùng transfer_spl hoặc RomeBridgeWithdraw.bridgeOutToSolana thay vào đó ở đó.

    • RomeBridgeWithdraw.bridgeOutToSolana(solanaRecipient, amount, mint) gửi chúng đến bất kỳ ví Solana nào. Nó 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), và tài khoản token của người nhận phải tồn tại; ensureRecipientAta(solanaRecipient, mint) tạo nó.

    • RomeBridgeWithdraw cũng đốt USDC sang chain khác qua CCTP (burnUSDC) và gửi các tài sản khác qua Wormhole (burnETH, burnToWormhole).

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

Token gas

Mỗi chain có token gas riêng: SOL hoặc một token SPL. Nguồn giá của Rome Proxy có thể là nguồn cấp Hermes API, pool Meteora DAMM v1, pool Meteora DAMM v2, hoặc giá cố định. Hadrian (testnet) và Rubicon (mainnet) dùng USDC. Hadrian dùng USDC test. Rubicon dùng USDC thật. Không có token gas mặc định dùng chung cho tất cả.

Các mint Token-2022

Factory cũng bọc các mint Token-2022. Nó hỏi precompile Helper mint đó là gì, bằng mint_info(mint) (selector 0xe24bf5d4), và chọn wrapper dựa trên câu trả lời. 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ố thập phân của mint

hookProgram

chương trình transfer-hook, hoặc bằng zero khi không có hook hoặc hook có mặt nhưng chưa được kích hoạt

feeBps

phí chuyển theo basis points, hoặc bằng zero khi không có phí hoặc phí được đặt bằng zero

extensions

bitmap các extension Token-2022 mà mint mang, bit N cho loại extension N

Mint nhận được:

Mint

Wrapper

wrapper_kind_by_mint

Một mint thông thường, một mint Token-2022 không có hook, hoặc một mint có hook hiện diện nhưng chưa được kích hoạt

wrapper cached (SPL_ERC20_cached)

1

Một 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

Một mint có phí chuyển sẽ nhận wrapper cached, và Transfer sự kiện của nó báo cáo số lượng nhận được sau phí, không phải số lượng đã gửi. Bạn có thể đọc loại wrapper mà mint nhận 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 gì bị từ chối:

  • Một 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 trên nó sẽ hoàn nguyên với ArmedTransferHookUnsupported(mint, hookProgram). Thông qua factory, trường hợp này sẽ được chuyển đến wrapper có hook thay thế.

  • Một địa chỉ không phải là mint SPL khiến mint_info hoàn nguyên với Invalid SPL mint account: <address>.

  • Một mint đã có wrapper sẽ hoàn nguyên với Token tồn tại, và một symbol đã được sử dụng sẽ hoàn nguyên với Token với symbol đã tồn tại.

  • add_spl_token_with_metadata đọc name và symbol từ metadata Token-2022 của chính mint trước tiên và từ Metaplex thứ hai. Nếu mint không có cả hai thì nó hoàn nguyên với Mint không khai báo tên: hãy dùng add_spl_token_no_metadata.

Wrapper có hook hoạt động như thế nào:

  • 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ự suy ra chúng, vì vậy bên gọi sẽ lấy danh sách tài khoản đầy đủ từ danh sách extra-account-metas của mint và 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ó) rồi chuyển tiếp nguyên trạng.

  • Phiên bản thuần transfer, transferFrom và bridgeOutToSolana hoàn nguyên với HookAccountPlanRequired. Hãy dùng transferWithHookAccounts, transferFromWithHookAccounts và bridgeOutToSolanaWithHookAccounts, vốn nhận danh sách tài khoản như một đố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 lần chuyển sẽ hoàn nguyên với HookConfigurationChanged.

  • Nó di chuyển token bằng lời gọi cross-program trực tiếp, track legacy, và không dùng track cached. Một hợp đồng sử dụng nhất quán một track, và các lời gọi trên track legacy chỉ chạy trong thực thi nguyên tử, vì vậy một lời gọi dùng wrapper có hook phải vừa trong một giao dịch nguyên tử.

  • Nó không giữ sổ cái cho số dư hợp đồng. Token gửi đến một hợp đồng sẽ vào tài khoản token riêng của hợp đồng, và hợp đồng chỉ có thể gửi chúng tiếp sau khi đã thực hiện approve_spl quyền cấp cho chính wrapper.

  • Nó cần cùng một quyền cấp một lần như bất kỳ wrapper nào khác.

Ràng buộc

  • Số lượng token SPL là uint64 (tối đa 18,446,744,073,709,551,615)

  • Hạn mức ERC-20 (approve / allowance) là dữ liệu lưu trữ EVM. Wrapper di chuyển token với tư cách là delegate SPL của người dùng, quyền này người dùng cấp một lần cho mỗi wrapper (xem cần mỗi người dùng đã thực hiện việc này. Xem)

  • Symbol của wrapper ERC-20 phải là duy nhất trong mỗi factory

Tiếp theo là gì

Cập nhật lần cuối

Nội dung này có hữu ích không?