> 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/core-concepts/token-interop.md).

# 토큰 상호운용성

Rome에서는 ERC-20과 SPL 토큰이 같은 기본 계정입니다.

Rome은 ERC-20 토큰과 그 기반이 되는 SPL 토큰을 하나의 공유 계정으로 나타냅니다. 이 페이지에서는 EVM과 Solana에서 토큰이 작동하는 방식을 설명합니다.

## 공유 상태 모델

일반 지갑의 경우 Rome의 ERC-20 토큰은 Solana의 SPL 토큰 계정을 감싸는 **투명한 래퍼** 입니다. 지갑의 ERC-20 잔액은 SPL 잔액과 같습니다. EVM 주소의 프로그램 파생 주소가 토큰 계정을 소유합니다. 이를 **외부 권한 PDA**.

<figure><img src="https://1350471780-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>

* 동기화 지연 없음: 지갑의 ERC-20 잔액은 SPL 잔액과 같습니다.
* MetaMask 지갑과 합성 주소를 포함한 일반 지갑에는 유동성 분할이 없습니다. 하나의 민트를 감싸는 모든 래퍼에 동일한 지갑 잔액이 표시됩니다.  `balanceOf` 메서드는 지갑의 토큰 계정에서 해당 잔액을 읽습니다. EVM 컨트랙트 내부에 보유된 토큰은 래퍼별로 보관됩니다(참조:  [래퍼 컨트랙트](#the-wrapper-contract)).
* 지갑 토큰의 경우 한쪽에서 잠그고 다른 쪽에서 발행하는 일이 없습니다. 컨트랙트가 보유한 토큰은 Solana에 있는 래퍼 자체의 에스크로 토큰 계정에 보관됩니다. 각 래퍼는 해당 토큰을 별도로 추적합니다.

**두 번째 래퍼가 잔액을 분할하지 않는 이유**

동일한 민트를 감싸는 두 래퍼에는 같은 지갑 잔액이 표시됩니다. 래퍼는 Solana 민트에서 `totalSupply` 를 읽습니다. Hadrian(테스트넷)에서는 wUSDC 래퍼 세 개가 동일한 지갑 잔액을 반환했습니다. 세 wUSDC 래퍼(9.0.0, 8.0.0, 2026년 5월)는 모두 Solana 민트의 공급량을 반환했습니다.

각 팩토리는 민트당 하나의 래퍼만 허용합니다. 새 팩토리 버전은 해당 민트용 래퍼를 추가로 배포할 수 있습니다. 레지스트리에는 체인별 정식 래퍼가 명시되어 있습니다.

USDC를 직접 보유한 Solana 지갑과 EVM 주소는 동일한 민트의 토큰을 보유합니다. Solana 풀은 두 경우 모두 같은 볼트와 준비금을 사용합니다.

의 보유자 표는  [Via 탐색기](https://docs.rome.builders/ko/rome-1/via.md) 각 래퍼의  `Transfer` 이벤트를 바탕으로 생성됩니다. 직접 SPL 전송,  `ActivateAta`, 다른 래퍼를 통한 전송은 해당 래퍼의 이벤트에 나타나지 않으므로 이 표의 내용이 토큰 계정 잔액과 다를 수 있습니다.

> 아래 가져오기 경로는  `@rome-protocol/rome-solidity`를 사용합니다. 이 패키지는 npm에 없으므로 공개  [`rome-solidity`](https://github.com/rome-protocol/rome-solidity) 저장소에서 다음 명령으로 설치하세요:  `npm install github:rome-protocol/rome-solidity`또는 `forge install rome-protocol/rome-solidity` 와 remapping을 사용하세요. Foundry에서 래퍼 및 팩토리 컨트랙트를 사용하려면 OpenZeppelin도 필요합니다(참조:  [Solidity 컨트랙트 배포](https://docs.rome.builders/ko/developer-guides/deploy-solidity.md#using-the-rome-solidity-sdk)). 프리컴파일 인터페이스는  [`contracts/interface.sol`](https://github.com/rome-protocol/rome-solidity/blob/master/contracts/interface.sol).

## 래퍼 컨트랙트

`SPL_ERC20` (및 캐시 트랙 변형인  `SPL_ERC20_cached`은 전송 훅이 활성화된 하나의 민트를 제외한 모든 민트에 대해 팩토리가 배포합니다. 참조:  [Token-2022 민트](#token-2022-mints))은 SPL 민트에 대해 완전한 ERC-20 인터페이스를 제공합니다:

* `balanceOf()` — Solana에서 사용자의 ATA 잔액을 읽습니다(컨트랙트 주소인 경우 래퍼 자체 원장을 읽습니다. 아래 참조).
* `transfer()` / `transferFrom()` — Solana에서 토큰을 이동합니다.
* `approve()` / `allowance()` — EVM 스토리지에 저장되는 스펜더별 ERC-20 허용량입니다(SPL 토큰 계정에는 EVM 방식의 허용량이 없습니다). 아래의 일회성 권한 부여와는 별개입니다. 사용자의 토큰을 이동하려면 래퍼가 해당 사용자의 SPL 대리자 역할을 해야 하며, 사용자는 지갑마다 한 번씩 래퍼에 그 권한을 부여합니다.
* `totalSupply()` — SPL 민트의 공급량을 읽습니다.

컨트랙트는 일회성 권한을 부여할 수 없으므로, 컨트랙트의 토큰은 래퍼 자체 토큰 계정에 보관되고 래퍼의 원장에 기록됩니다. `balanceOf(contract)` 는 해당 원장을 읽습니다.

## 팩토리

`ERC20SPLFactory` 는 모든 SPL 민트에 대한 래퍼를 배포합니다.

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

// 민트의 Token-2022 메타데이터 또는 Metaplex에서 이름/심벌을 가져와 래퍼 배포
address wrapper = factory.add_spl_token_with_metadata(splMint);

// 또는 이름/심벌을 직접 지정
address wrapper = factory.add_spl_token_no_metadata(splMint, "USD Coin", "USDC");
```

레지스트리의 `live` 항목에 등록된 현재 팩토리 주소(v0.2.0): Hadrian `0x37c13e4ff21fb914eb24014dcbd0f8dbeaa31078`입니다. 이전 팩토리도 여전히 온체인에 있지만 `deprecated` 또는 `retired` 로 [레지스트리](https://github.com/rome-protocol/rome-registry/tree/main/chains)에 표시되어 있습니다. 사용하지 마세요. 레지스트리가 기준 정보이므로, 주소를 코드에 복사하는 대신 레지스트리에서 현재 주소를 확인하세요(자세한 내용은 [컨트랙트 목록 읽기](https://docs.rome.builders/ko/reference/contract-addresses.md#reading-the-contracts-list)참조).

## 정식 민트

온체인 토큰 레지스트리 컨트랙트는 없습니다. 정식 래퍼와 가스/브리지 토큰은 오프체인 [`rome-protocol/registry`](https://github.com/rome-protocol/rome-registry)에서 관리합니다. 반면 `add_spl_token_no_metadata` 를 통해 권한 없이 생성된 래퍼는 온체인의 `TokenCreated` 이벤트에서 확인할 수 있습니다. 레지스트리에는 각 체인에서 각 민트에 해당하는 정식 래퍼가 명시되어 있습니다. 지갑 잔액은 모든 래퍼에서 공유됩니다. 각 래퍼는 EVM 컨트랙트가 보유한 잔액을 별도로 추적합니다.

## Solidity에서 SPL 작업 수행

사용자 PDA 서명이 필요한 SPL 기본 작업에는 **HelperProgram** 프리컴파일을 사용하세요(`0xFF…09`). ATA 생성, SPL 전송, 가스↔램포트 변환을 지원합니다.

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

IHelperProgram helper = IHelperProgram(0xFF00000000000000000000000000000000000009);

helper.create_ata(user, mint);              // 민트에 대한 사용자의 ATA 생성
helper.transfer_spl(to, tokens, mint);      // 호출자의 PDA에서 SPL 전송
```

`transfer_spl` 에는 여러 오버로드가 있습니다( `transferFrom` 흐름을 위한 대리자 변형 포함). 자세한 내용은 `interface.sol` 정확한 시그니처를 확인하세요. 캐시 트랙에서는 이에 해당하는 작업이 `ISplCached` (`0xFF…05`) 및 `IAssociatedSplCached` (`0xFF…06`)에 있습니다. 컨트랙트는 한 트랙을 일관되게 사용합니다.

## 지갑별 1회 부여

래퍼는 사용자의 토큰을 다음과 같이 이동합니다. **SPL 위임자** 해당 사용자의 토큰 계정에 대한 권한입니다. 따라서 래퍼가 사용자를 대신해 토큰을 이동하려면, 지갑은 각 래퍼에 대해 먼저 한 번 이 권한을 부여해야 합니다. 권한 부여는 Helper 프리컴파일을 한 번 호출하면 됩니다(`0xff00000000000000000000000000000000000009`):

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

`approve_spl` 은 사용자의 계정 자체가 서명하므로, 래퍼나 사용자의 컨트랙트가 아니라 사용자가 직접 전송합니다. 민트는 `mint_id()` 이며, 래퍼에서 가져옵니다.

* **필요한 대상.** 토큰을 이동하려는 각 래퍼마다 모든 EVM 지갑과 모든 Solana 사용자의 합성 주소에 필요합니다. 토큰을 가져오는 컨트랙트는 `transferFrom` 래퍼에 권한을 부여한 사용자에게만 작동합니다.
* **확인 방법** 래퍼에서 `isEnabled(user)` 을 호출합니다. 권한이 부여되면 `true` 를 반환합니다.
* **권한이 없는 경우의 동작** 전송이 SPL 오류와 함께 되돌려집니다. `0x4` (소유자가 일치하지 않음).
* **토큰 계정당 위임자는 하나입니다.** SPL 토큰 계정에는 위임자가 하나만 지정됩니다. 브리지나 라우터처럼 같은 토큰 계정에 다른 프로그램을 추가로 승인하면 래퍼에 부여된 승인이 대체되며, 사용자가 다시 승인할 때까지 해당 사용자는 래퍼를 사용할 수 없습니다. 전송 전에 `isEnabled` 를 확인하여 이전에 부여한 승인이 여전히 유효하다고 가정하지 마세요.

새 팩토리 버전이 래퍼를 대체하면 각 지갑은 `approve_spl`을 사용해 새 래퍼에 권한을 부여합니다. 기존 래퍼는 해당 지갑의 토큰을 이동할 수 있지만, 이는 토큰 계정의 위임자로 남아 있는 동안에만 가능합니다. 새 래퍼를 승인하면 해당 위임자가 대체됩니다.

The [듀얼 레인 앱 가이드](https://docs.rome.builders/ko/developer-guides/dual-lane-app.md#one-time-grant-the-wrapper) 두 레인의 전체 코드가 포함되어 있습니다.

## 입금 및 출금

* **EVM으로** — SPL 측에서 사용자의 PDA가 소유한 ATA에 금액을 적립하며, ERC-20 래퍼에 잔액이 즉시 반영됩니다. 다른 체인에서 들어오는 전송은 브리지에서 사용자가 서명한 승인을 통해 온체인으로 정산됩니다.
* **가스를 가스 토큰으로 래핑** — 다음을 호출합니다. `Withdraw` 프리컴파일(`0x42…16`). `withdraw_to_ata(wei)` 네이티브 가스를 소각하고, 이에 해당하는 양을 가스 토큰의 소수 자릿수 기준으로 호출자의 토큰 계정에 적립합니다. 그러면 가스 토큰 래퍼(예: wUSDC)에 잔액으로 표시됩니다. `withdraw_to_pda(wei)` 호출자의 PDA에 라멜트를 지급하며, 가스가 SOL인 체인에서만 사용할 수 있습니다. 가스로 USDC를 사용하는 Hadrian 및 Rubicon에서는 실행이 되돌려지므로 대신 다음을 사용하세요. `withdraw_to_ata` 여기서 금액은 소수점 18자리 기준의 가스 단위이며, 가스 토큰 단위의 정수여야 합니다. USDC 가스 체인에서는 10^12의 배수(소수점 6자리 기준 1단위)여야 합니다. 그렇지 않으면 호출이 되돌려집니다. `HelperProgram.deposit_from_ata(wei)` 는 반대 방향으로 작동하여 호출자의 토큰 계정에 있는 가스 토큰을 다시 네이티브 가스로 변환하며, 동일하게 배수 조건이 적용됩니다. 이는 가스 토큰 변환이며, 다른 토큰을 출금하는 방법은 아닙니다.
* **Solana로 다른 토큰 보내기** — 래퍼 자체의 잔액이 이미 SPL 잔액이므로, 이를 밖으로 보내는 작업은 SPL 전송입니다.
  * `HelperProgram.transfer_spl_to_signer(amount, mint)` 호출자의 토큰을 트랜잭션에 서명한 Solana 지갑의 토큰 계정으로 보냅니다. 이 반환 경로가 사용자의 개인 지갑에 도달하는 것은 사용자가 지갑으로 서명하는 Solana 경로뿐입니다. MetaMask에서 호출하거나 릴레이를 통해 호출하면 서명자는 Rome의 프록시 페이어이므로, 호출이 실패하거나 토큰이 Rome으로 전송됩니다. 대신 다음을 사용하세요. `transfer_spl` 또는 `RomeBridgeWithdraw.bridgeOutToSolana` 를 사용하세요.
  * `RomeBridgeWithdraw.bridgeOutToSolana(solanaRecipient, amount, mint)` 토큰을 임의의 Solana 지갑으로 보냅니다. 브리지 컨트랙트에 대한 사용자의 권한 부여가 필요하며(`approve_spl(bridge, …)`, 위의 단일 위임자 참고 사항 참조), 수신자의 토큰 계정이 존재해야 합니다. `ensureRecipientAta(solanaRecipient, mint)` 를 사용하면 계정을 생성할 수 있습니다.
  * `RomeBridgeWithdraw` 는 CCTP를 통해 USDC를 다른 체인으로 소각하고(`burnUSDC`), 다른 자산은 Wormhole을 통해 전송합니다(`burnETH`, `burnToWormhole`).

레지스트리에서 최신 `RomeBridgeWithdraw` 주소를 가져오세요.

Solana와 Ethereum 또는 AggLayer 체인 간에 다른 토큰을 전송하려면 다음을 참조하세요. [Solgate](https://docs.rome.builders/ko/rome-1/solgate.md) 및 [13. Solgate 기반으로 빌드하기](https://docs.rome.builders/ko/rome/13-build-on-solgate.md).

## 가스 토큰

각 체인에는 SOL 또는 SPL 토큰이라는 자체 가스 토큰이 있습니다. Rome Proxy의 가격 소스는 Hermes API 피드, Meteora DAMM v1 풀, Meteora DAMM v2 풀 또는 고정 가격일 수 있습니다. Hadrian(테스트넷)과 Rubicon(메인넷)은 USDC를 사용합니다. Hadrian은 테스트용 USDC를 사용하고 Rubicon은 실제 USDC를 사용합니다. 모든 체인에 공통으로 적용되는 기본 가스 토큰은 없습니다.

## Token-2022 민트

팩토리는 Token-2022 민트도 래핑합니다. Helper 프리컴파일에 다음을 사용해 민트 정보를 요청하고, `mint_info(mint)` (선택자 `0xe24bf5d4`) 응답에 따라 래퍼를 선택합니다. `mint_info` 는 다음 다섯 가지 값을 반환합니다.

| 값              | 의미                                                   |
| -------------- | ---------------------------------------------------- |
| `tokenProgram` | 민트를 소유한 토큰 프로그램(기본 SPL Token 프로그램 또는 Token-2022)     |
| `decimals`     | 민트의 소수 자릿수                                           |
| `hookProgram`  | 전송 훅 프로그램. 훅이 없거나 훅이 있지만 활성화되지 않은 경우에는 0             |
| `feeBps`       | 베이시스 포인트 단위의 전송 수수료. 수수료가 없거나 0으로 설정된 경우에는 0         |
| `extensions`   | 민트가 보유한 Token-2022 확장 기능의 비트맵. 확장 유형 N은 비트 N으로 표시됩니다 |

민트에 할당되는 항목:

| 민트                                               | 래퍼                                                                       | `wrapper_kind_by_mint` |
| ------------------------------------------------ | ------------------------------------------------------------------------ | ---------------------- |
| 일반 민트, 훅이 없는 Token-2022 민트 또는 훅이 있지만 활성화되지 않은 민트 | 캐시된 래퍼(`SPL_ERC20_cached`)                                               | `1`                    |
| 활성화된 전송 훅이 있는 Token-2022 민트                      | 훅이 적용된 래퍼(`SPL_ERC20_Token2022Hooked`). 팩토리의 `hooked_wrapper_deployer()` | `2`                    |

전송 수수료가 있는 민트에는 캐시된 래퍼가 할당되며, 해당 래퍼의 `Transfer` 이벤트에는 전송한 금액이 아니라 수수료를 제외하고 실제로 도착한 금액이 보고됩니다. 팩토리에서 민트에 할당된 래퍼 종류를 다음으로 확인할 수 있습니다. `wrapper_kind_by_mint(mint)`; 라이브 Hadrian 팩토리에서 USDC, ETH, SOL 래퍼는 모두 다음을 반환합니다. `1`.

거부되는 경우:

* 활성화된 전송 훅이 있는 민트에는 일반 래퍼를 할당할 수 없습니다. 여기에 `SPL_ERC20` 또는 `SPL_ERC20_cached` 를 직접 배포하면 다음 오류와 함께 트랜잭션이 되돌려집니다. `ArmedTransferHookUnsupported(mint, hookProgram)`. 팩토리를 통하면 이 경우 훅이 적용된 래퍼가 할당됩니다.
* SPL 민트가 아닌 주소를 사용하면 `mint_info` 가 다음 오류와 함께 되돌려집니다. `Invalid SPL mint account: <address>`.
* 이미 래퍼가 있는 민트를 사용하면 `Token exists`오류가 발생하고, 이미 사용 중인 심볼을 사용하면 `Token with symbol exists`.
* `add_spl_token_with_metadata` 는 먼저 민트 자체의 Token-2022 메타데이터에서 이름과 심볼을 읽고, 다음으로 Metaplex에서 읽습니다. 민트에 둘 다 없으면 다음 오류와 함께 되돌려집니다. `Mint asserts no name: use add_spl_token_no_metadata`.

훅이 적용된 래퍼의 동작:

* Token-2022는 전송할 때마다 훅을 실행하며, 훅에는 전송 내용에 따라 달라지는 계정이 필요합니다. 래퍼는 이러한 계정을 알아낼 수 없으므로 호출자가 민트의 extra-account-metas 목록에서 전체 계정 목록을 확인해 전달해야 합니다. 래퍼는 해당 목록의 고정 부분(훅 프로그램과 검증 계정)을 확인한 다음, 목록을 변경하지 않고 전달합니다.
* 일반 `transfer`, `transferFrom` 및 `bridgeOutToSolana` 다음 오류로 되돌립니다. `HookAccountPlanRequired`을 사용하세요. `transferWithHookAccounts`, `transferFromWithHookAccounts` 및 `bridgeOutToSolanaWithHookAccounts`이 함수들은 계정 목록을 추가 인수로 받습니다.
* 래퍼 배포 후 민트의 훅 프로그램이 변경되면 전송은 `HookConfigurationChanged`.
* 이 방식은 프로그램 간 직접 호출을 통해 토큰을 이동하는 레거시 경로이며, 캐시된 경로를 사용하지 않습니다. 컨트랙트는 한 가지 경로를 일관되게 사용하며, 레거시 경로의 호출은 원자적 실행에서만 수행되므로 훅이 적용된 래퍼를 사용하는 호출은 하나의 원자적 트랜잭션 안에서 완료되어야 합니다.
* 컨트랙트 잔액 원장을 유지하지 않습니다. 컨트랙트로 전송된 토큰은 컨트랙트 자체의 토큰 계정에 들어가며, 컨트랙트는 먼저 래퍼 자체에 `approve_spl` 승인을 부여한 후에만 토큰을 다시 전송할 수 있습니다.
* 다른 래퍼와 마찬가지로 [일회성 승인](#one-time-grant-per-wallet) 이 필요합니다.

## 제약 사항

* SPL 토큰 수량은 `uint64` (최댓값 18,446,744,073,709,551,615)입니다.
* ERC-20 허용량(`approve` / `allowance`)은 EVM 저장소에 저장됩니다. 래퍼는 사용자가 래퍼마다 한 번씩 승인한 사용자의 SPL 위임자로서 토큰을 이동합니다(자세한 내용은 [지갑별 일회성 승인](#one-time-grant-per-wallet))
* ERC-20 래퍼 심볼은 팩토리별로 고유해야 합니다.

## 다음 단계

* [컨트랙트 주소](https://docs.rome.builders/ko/reference/contract-addresses.md) — 프리컴파일 및 체인별 주소
* [EVM에서 Solana 호출하기](https://docs.rome.builders/ko/developer-guides/call-solana-from-evm.md) — Solidity에서 CPI 및 SPL 작업 수행
* [Rome에서 Solana와 EVM이 만나는 방식](https://docs.rome.builders/ko/core-concepts/how-solana-and-evm-meet.md)
* [Solana 프로그램 통합하기](https://docs.rome.builders/ko/developer-guides/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/ko/core-concepts/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.
