> 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/developer-guides/integrate-solana-program.md).

# Solana 프로그램 통합

Solana 프로그램을 Rome EVM과 통합하세요 — Solana 서명자가 누구인지, 가치가 어떻게 프로그램에 도달하고 다시 돌아오는지, 단일 경로 규칙, 원자적 vs 반복적, 그리고 계정 프로비저닝.

이 가이드는 Rome EVM 사용자가 여러분의 프로그램을 사용하게 하려는 Solana 프로그램 팀을 위한 것입니다. 즉, EVM 계정의 가치를 보관해야 하는 프라이버시, 대출 또는 볼트 프로그램을 위한 것입니다. 이 가이드는 [EVM에서 Solana 호출](https://docs.rome.builders/ko/developer-guides/call-solana-from-evm.md) (프리컴파일 메커니즘)을 바탕으로 하며, 실제 프로그램이 반대편에 있을 때 생기는 질문들에 답합니다: *누가* 서명하고, *어떻게* 토큰이 들어오고 나가는지, 그리고 *어떤* 제약이 설계를 좌우하는지입니다.

여기서 전체적으로 사용하는 흐름은 다음과 같습니다: EVM 계정이 USDC를 여러분의 프로그램으로 이동시켜("shield" 또는 "deposit"), 여러분의 프로그램이 그 사용자를 위해 이를 보관하고, 나중에 다시 돌려줍니다("unshield" 또는 "withdraw"). 동사는 여러분의 용어로 바꾸면 됩니다.

## 1. 모든 EVM 주소는 하나의 Solana 신원을 가진다

Rome은 모든 EVM 주소—사용자와 계약 모두—에 대해 하나의 Solana 계정을 파생시키며, 이를 **외부 권한**:

```
external_auth(addr) = find_program_address(["EXTERNAL_AUTHORITY", addr_h160], rome_evm_program_id)
```

라고 부릅니다. 이 계정은 해당 주소의 연관 토큰 계정들을 소유하고(즉 `wUSDC.balanceOf(addr)` 가 읽는 곳이며), 그 주소를 대신해 수행되는 CPI에 서명하는 키입니다. 여러분의 프로그램은 32바이트 Solana pubkey만 보며, H160은 절대 보지 못합니다.

**누가 서명하는지는 누가 프리컴파일을 호출하는지에 따라 결정됩니다:**

| 프리컴파일은 다음에 의해 호출됩니다                                   | Solana 서명자                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| ----------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 하나의 **계약**은 일반적인 `CALL`                               | 위의 **계약 자신의** 외부 권한(`external_auth(contract)`), 그리고 요청한 계약의 솔트가 붙은 하위 PDA들                                                                                                                                                                                                                                                                                                                                                                               |
| 하나의 **사용자**를 포함합니다. 이는 프리컴파일 주소로 직접 전송된 트랜잭션에서 이루어집니다 | 위의 **사용자 자신의** 외부 권한                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| 계약은 다음을 통해 `DELEGATECALL`                             | 기본 권한은 거부됩니다(`DelegatecallOwnerAuthority`). `invoke` 서명자 없이 실행되며, `invoke_signed` 솔트가 붙은 하위 PDA는 여전히 동작합니다. 하지만 그 하위 PDA들은 실행 중인 계약의 주소(`["EXTERNAL_AUTHORITY", caller, running_contract, salt]`)로 이름공간이 분리되므로 `pda_with_salt` 는 그것들을 파생하지 않습니다. HelperProgram에서는 생성 및 자금 조달 선택자만 통과합니다(`create_ata*`, `create_pda*`, `swap_gas_to_lamports`, `init_spl_mint`, `create_and_init_mint`); 이들은 아무것도 서명하지 않기 때문이 아니라, 대상이 호출자에 묶여 있거나 운영자에 의해 자금이 조달되기 때문입니다 |

그 결과는 여러분이 이미 알고 있는 ERC-20 규칙입니다: **계약은 스스로 사용자의 자산을 이동시킬 수 없습니다.** 계약은 자기 자신의 신원으로 동작하며, 사용자가 먼저 권한을 부여합니다. Solana 쪽에서 이동해야 하는 토큰의 경우, 그 권한 부여는 사용자의 토큰 계정에 대한 SPL 위임이고, 래퍼의 ERC-20 `approve` 은 래퍼 자체 전송이 따르는 EVM 쪽 allowance일 뿐입니다. 이것이 Rome의 자체 토큰 래퍼가 동작하는 방식이며, 여러분의 어댑터도 이렇게 동작합니다(3절).

솔트가 붙은 하위 PDA: `invoke_signed` 다음의 목록을 받습니다 `bytes32` 솔트들을, 그리고 Rome은 다음으로 서명합니다 `["EXTERNAL_AUTHORITY", caller_h160, salt]` 각각에 대해(버ンプ가 뒤에 붙음; 직접 호출에서는 호출자가 계약입니다). `HelperProgram.pda_with_salt(addr, salt)` 는 Solidity에서 주소를 반환합니다. 여러분의 프로그램이 포지션마다 별도의 소유자 계정을 원할 때는 사용자당 하나의 솔트(예: 사용자의 주소)를 사용하세요.

자금 조달: ATA를 소유하기 위해 외부 권한 PDA가 존재할 필요는 없습니다(`create_ata` 는 멱등적이며 트랜잭션의 Solana 수수료 지불자가 임대료를 부담합니다). 여러분의 instruction이 만드는 계정에 자금을 댈 때만 존재해야 하며 lamports를 보유해야 합니다. `HelperProgram.create_pda(addr)` 는 이를 일반적인 System `CreateAccount`으로 생성하므로 한 번만 호출하세요. 멱등적이지 않습니다. `swap_gas_to_lamports(n)` 는 트랜잭션의 Solana 수수료 지불자로부터 해당 주소의 PDA에 `n` lamports를 크레딧하고, 호출자는 Rome 가스로 그 비용을 지불합니다: 모든 레거시 경로 CPI가 수수료 지불자의 잔액에 미치는 효과는 트랜잭션 수수료에 더해져 가스 가격으로 사용자에게 청구되며, CPI가 생성한 계정의 임대료가 청구되는 방식과 같습니다. Solana 경로의 프로비저닝 단계는 [Solana에서 EVM 호출](https://docs.rome.builders/ko/developer-guides/call-evm-from-solana.md)에서 설명합니다. 계약은 자신의 PDA를 생성자 또는 첫 호출에서 프로비저닝합니다.

## 2. 사용자의 포지션을 보유하는 세 가지 방법

**A. 어댑터 계약(재사용 가능한 어댑터에 권장).** 하나의 Solidity 계약이 여러분의 프로그램의 전면에 섭니다. 사용자는 어댑터의 권한에 자신의 토큰 계정에 대한 SPL 위임을 부여합니다. 어댑터는 토큰을 자신이 소유한 토큰 계정으로 끌어오고, 자기 자신으로서 여러분의 프로그램을 호출하며, 사용자 포지션은 사용자별 하위 PDA 또는 instruction data에 전달하는 식별자로 여러분의 프로그램 안에서 식별합니다. 반환 시에는 여러분의 프로그램에 사용자 자신의 토큰 계정으로 풀어주도록 지시합니다. 어댑터는 여러분의 프로그램이 알아야 하는 유일한 Solana 신원입니다. 이 권한 부여는 SPL 위임이며, ERC-20 `approve`이 아닙니다. 3절에서 그 이유와 그것이 사용자에게 드는 비용을 설명합니다.

**B. 사용자가 Solana 서명자인 경우.** 프런트엔드는 사용자의 EVM 계정에서 트랜잭션을 보냅니다 **직접 CpiProgram 프리컴파일로** (`to = 0xff…08`로, calldata = ABI로 인코딩된 `invoke` 또는 `invoke_signed`이므로 사용자의 자체 외부 권한이 서명하고, 여러분의 프로그램은 그 계정을 기준으로 포지션을 식별합니다. 어댑터 계약도 없고 위임도 없지만, 각 동작은 지갑에서 보이는 불투명한 calldata 트랜잭션이며, CPI 외에 흐름에 필요한 것(ATA, 사전 전송)은 별도 트랜잭션입니다. 이는 일회성 권한 부여(사용자의 `approve_spl` 를 래퍼에 대한 권한 부여)에 적합하며, 다단계 흐름에는 적합하지 않습니다. [Cardo](https://github.com/rome-protocol/cardo) 는 이 형태를 사용합니다: 프런트엔드가 사용자 지갑에서 `invoke` 을 직접 프리컴파일로 보냅니다.

**C. 보관하지 않는 라우터.** 사용자의 토큰을 절대 보유하지 않는 계약입니다. 사용자는 라우터의 권한에 자신의 토큰 계정에 대한 SPL 위임을 부여하고, 라우터는 그 권한을 전송 권한자로 삼아 여러분의 프로그램으로 CPI를 호출합니다. 그래서 토큰은 사용자의 토큰 계정에서 여러분의 프로그램 계정으로(또는 다시 사용자에게) 이동하며, 라우터는 호출 사이에 아무것도 보유하지 않습니다. 라우터는 모든 사용자 측 계정을 `msg.sender`에서 파생하므로 한 사용자의 권한 부여가 다른 사용자의 계정을 향할 수 없고, 일반적인 `invoke` 패스스루처럼 동작하는 대신 고정된 instruction 형식으로 고정된 프로그램 하나를 호출합니다. The `RomeDexRouter` 을 [rome-dex](https://github.com/rome-protocol/rome-dex) 는 이런 방식으로 작성되어 있으며, rome-dex의 EVM 경로도 형태 B의 원시 직접 `invoke` 를 제공합니다. 여기에는 A와 같은 권한 부여가 필요하며, 같은 한 번의 위임 비용이 듭니다(3절), 그리고 pull 단계는 없습니다.

이 가이드의 나머지는 A를 따릅니다. C도 같은 권한 부여와 같은 서명 규칙을 사용합니다.

## 3. 토큰의 유입과 유출

Rome의 USDC는 두 측면에서 본 하나의 SPL 민트입니다: `wUSDC` EVM 쪽의 ERC-20 래퍼와 Solana 쪽의 외부 권한의 ATA입니다. 사용자의 자체 주소에 대해서는 둘이 같은 잔액입니다: `wUSDC.balanceOf(user)` 는 사용자의 ATA를 읽습니다. 두 뷰 사이에서 아무것도 이동하거나 동기화되지 않습니다.

**계약의 래퍼 잔액은 계약이 제어하는 토큰 계정이 아닙니다.** 팩토리는 `SPL_ERC20_cached` 일반적인 mint에 대해 배포하며, Hadrian의 `wUSDC` 는 그 중 하나입니다. 그 래퍼는 계약을 위해 서명할 수 없으므로 `wUSDC.transferFrom(user, adapter, amount)` 또는 `transfer` 가 계약으로 토큰을 보낼 때, SPL 토큰은 **래퍼 자신의 에스크로 토큰 계정** (`escrow_ata()`에 들어가고, 래퍼는 저장소에 계약별 금액을 기록합니다. `wUSDC.balanceOf(adapter)` 는 해당 기록, 즉 에스크로 원장을 반환하며, `external_auth(adapter)`가 소유한 토큰 계정의 잔액은 아닙니다. 어댑터는 그 토큰들을 CPI로 여러분의 프로그램에 넘길 수 없고, 다시 래퍼를 통해서만 빠져나갈 수 있습니다. 따라서 `transferFrom` 로 자금을 조달하는 어댑터는 Solana 쪽에서 사용할 수 있는 것이 아무것도 없습니다.

작동하는 경로는 SPL 위임입니다:

* **권한 부여.** 사용자가 `approve_spl(adapter, amount, mint)` 을 트랜잭션으로 보냅니다 **직접 HelperProgram으로** (`to = 0xff…09`), 여기서 `mint` 는 래퍼의 `mint_id()`. 사용자의 자체 권한이 서명하고, 사용자의 토큰 계정에 설정되는 delegate는 어댑터의 외부 권한입니다.
* **유입.** 어댑터의 `deposit(amount)` 는 delegate 오버로드로 끌어옵니다 `HelperProgram.transfer_spl(srcAta, dstAta, amount, mint)`를 사용하며, 사용자의 ATA를 source로, 어댑터 자신의 ATA를`HelperProgram.ata(address(this), mint)`(한 번 생성됨, `create_ata`사용) destination으로 둡니다. 어댑터의 권한이 delegate로서 서명합니다. 이제 토큰은 `external_auth(adapter)`가 소유한 토큰 계정에 들어가며, 이것이 여러분의 CPI가 이름으로 지정하는 계정입니다. 서명자와 source는 어댑터의 자체 것이므로 추가 권한이 필요하지 않습니다. 이는 `wUSDC.balanceOf(adapter)`.
* **유출.** 여러분의 프로그램의 withdraw instruction은 **사용자의** ATA로 전송합니다, `HelperProgram.ata(user, mint)`. 받는 데 사용자의 서명은 필요 없으며, 잔액은 즉시 `wUSDC.balanceOf(user)`로 보입니다. ATA가 아직 없을 수 있다면 먼저 `HelperProgram.create_ata(user, mint)` (멱등적)으로 생성하세요.

**토큰 계정에는 하나의 delegate만 있습니다.** 위의 권한 부여는 해당 계정에서 래퍼 자신의 권한 부여를 대체합니다. 사용자가 래퍼에 다시 권한을 부여하기 전까지, 해당 주소에서 나가는 모든 `wUSDC` `transfer` 또는 `transferFrom` 전송은 SPL 오류 `0x4`로 되돌아갑니다. 이 권한 부여를 사용하는 흐름이 끝난 뒤에는 `wUSDC.isEnabled(user)`를 확인하세요; `false`를 반환하면 사용자에게 `approve_spl(wrapper, 2^64-1, mint)` 를 다시 HelperProgram으로 보내 달라고 요청하세요. 이는 래퍼가 기반으로 삼는 최대 권한 부여와 같습니다(참조 [일회성: 래퍼에 권한을 부여](https://docs.rome.builders/ko/developer-guides/dual-lane-app.md#one-time-grant-the-wrapper)). 한도 있는 권한 부여는 사용자의 일반적인 `wUSDC` 전송이 다시 잔액이 부족해지면 망가지고, `isEnabled` 는 `true` 로 유지되면서 그중 일부라도 남아 있으면 앱은 언제 다시 요청해야 할지 알 수 없습니다.

어떤 mint가 어떤 래퍼를 가지는지 확인하려면 팩토리의 `wrapper_kind_by_mint(mint)` 를 읽으세요(체인의 `contracts.json` 에 있는 [registry](https://github.com/rome-protocol/rome-registry)). `1` 에는 이 절에서 설명하는 캐시된 래퍼가 저장되어 있습니다. `2` 는 armed transfer hook이 있는 Token-2022 mint를 위해 팩토리가 배포하는 직접-CPI 래퍼입니다. 이 가이드는 이를 다루지 않습니다. registry의 `tokens.json` 에는 래퍼 주소와 mint는 있지만 종류는 적혀 있지 않습니다.

## 4. 계약당, 그리고 트랜잭션당 하나의 트랙

Rome에는 Solana 상태를 변경하는 두 계열의 프리컴파일이 있으며, **하나의 트랜잭션은 그중 정확히 하나만 사용합니다** — 런타임은 두 계열의 변경 호출을 섞은 트랜잭션을, 계약이 다르더라도, 거부합니다.

| 트랙      | 프리컴파일                                                                                                     | 효과가 도달하는 시점                                                | 반복 실행에서 동작 여부                                                         |
| ------- | --------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- | --------------------------------------------------------------------- |
| **레거시** | `` `CpiProgram` `` `0xff…08` (`invoke`, `invoke_signed`), `` `HelperProgram` `` `0xff…09`, `출금` `0x42…16` | 즉시, EVM 단계 내부의 실제 CPI로                                     | **아니요** — 반복 트랜잭션에서의 레거시 CPI는 다음으로 실패합니다 `CpiProhibitedInIterativeTx` |
| **캐시됨** | `SplCached` `0xff…05`, `ASplCached` `0xff…06`, `SystemCached` `0xff…04`, `WithdrawCached` `0xff…0b`       | 오버레이에 스테이징된 뒤 트랜잭션 종료 시 CPI로 커밋됩니다. EVM revert가 발생하면 버려집니다 | 예                                                                     |

프로그램 통합에서 이것이 의미하는 바는 다음과 같습니다:

* **자신의 프로그램 instruction을 호출하는 것은 레거시 경로에서만 가능합니다.** 캐시된 경로에는 일반적인 `invoke`가 없으며, SPL 전송, ATA 생성, 시스템 프로그램 작업, 가스 인출만 다룹니다.
* 따라서 어댑터에 자금을 대는 단계도 CPI와 같은 트랜잭션에서 실행된다면 레거시 경로여야 합니다. 캐시된 래퍼의 `transferFrom` 는 캐시된 경로 호출이므로 여러분의 CPI와 트랜잭션을 공유할 수 없으며(그리고 3절에서 보듯, 에스크로 원장에만 적립될 뿐입니다). 대신 `HelperProgram.transfer_spl(userAta, adapterAta, amount, mint)` 를 사용해 끌어오세요. 단, 사용자가 어댑터를 SPL delegate로 만든 뒤에만 가능합니다(`approve_spl`은 사용자가 HelperProgram으로 직접 보냅니다). pull과 CPI는 모두 레거시 경로이므로 한 트랜잭션에서 실행됩니다.
* **그 트랜잭션에서 래퍼를 제외하세요.** 래퍼의 변경 함수(`wUSDC.transfer`, `transferFrom`)를 어댑터에서 레거시 CPI와 같은 트랜잭션 안에서 호출하지 마세요. `isEnabled(user)` 와 잔액은 프런트엔드에서 확인하세요 `eth_call`.
* **그리고 CPI 트랜잭션은 원자적이어야 합니다.** 그것이 이 설계가 놓여 있는 한계입니다.

읽기는 이 규칙의 밖에 있습니다: `account_info`, `account_data_at`, `account_u64_at`, `account_lamports`, `pdas_batch_derive` 그리고 `HelperProgram.user_balance` / `allowance_of` 는 미리 로드된 계정의 읽기입니다(CPI 없음). 어느 트랙에서나, 그리고 두 실행 모드 모두에서 허용됩니다. 사전 점검은 여기에 두세요. 하나의 순서 규칙이 있습니다: 트랜잭션에서 캐시된 변경이 한 번이라도 발생하면, 그 이후에는 레거시 경로 읽기가 차단됩니다 — 먼저 읽고, 그다음 변경하세요.

## 5. 원자성이 예산이다

원자적 Rome 트랜잭션은 하나의 Solana 트랜잭션입니다: 대략 **140만 compute unit**과 **64개 주소** 의 계정 목록, 그리고 **4 KB** 의 와이어 크기(Solana v1 트랜잭션)입니다. Rome 프로그램과 여러분의 CPI가 이 예산을 공유합니다. 래퍼 전송은 Hadrian에서 약 17만 CU를 사용하며, 여러분의 instruction은 자체 비용을 더합니다. EVM `computeUnitsConsumed`이 아니라 Solana 영수증의 `gasUsed`.

로 측정하세요. 에뮬레이션이 트랜잭션이 맞지 않는다고 판단하면, Rome은 이를 **반복적으로** 여러 Solana 트랜잭션에 걸쳐 실행하고, 그 안의 레거시 CPI는 실패합니다. deposit과 withdraw 각각은 하나의 토큰 이동과 여러분의 프로그램으로의 하나의 CPI만 포함하도록 하고, 그 주위의 Solidity는 작게 유지하세요. 더 큰 것은 두 개의 사용자 트랜잭션으로 나누세요.

CPI 깊이: Solana는 4단계를 허용하고 Rome은 그중 하나를 사용하므로, 여러분의 instruction은 두 단계 아래에 두 단계가 남은 상태로 2단계에서 실행됩니다(여러분의 프로그램 → SPL Token이면 한 단계가 남습니다).

## 6. 계정 프로비저닝

여러분의 프로그램은 런타임에 Solidity로부터 계정을 전달받지 않습니다. 프록시는 **에뮬레이션하고** 모든 트랜잭션을 전송하기 전에, CPI가 접촉한 모든 Solana 계정을 기록하고, 이를 Solana 트랜잭션에 넣습니다. 어댑터는 `invoke_signed` 계정 목록

* 에 계정을 이름으로 지정하며; 에뮬레이션이 그것들이 해석된다는 것을 증명합니다. 다음 세 가지가 따라옵니다: `SystemProgram.find_program_address` 그리고 `CpiProgram.pdas_batch_derive` 가 Solidity에서 파생을 수행합니다.
* 아직 존재하지 않는 계정(새 포지션, 새 ATA)도 여전히 계정 목록에 이름이 올라가야 합니다. 그 주소가 Solana 트랜잭션으로 전달됩니다.
* 트랜잭션이 접촉하는 모든 것—사용자, 어댑터, 래퍼를 위한 Rome 자신의 계정까지 포함—은 64개 주소 이하로 유지되어야 합니다. 한 호출에서 열 개 시장을 건드리는 설계는 맞지 않습니다.

Solana 지갑 경로에서는 `rome_emulateCallAccounts` 가 같은 탐색을 클라이언트에 노출하며, SDK가 이를 사용합니다.

CPI가 절대 이름을 붙일 수 없는 두 계정이 있습니다: 트랜잭션을 제출하는 Solana 수수료 지불자(단, 일반 System transfer instruction 내부는 제외)와 Rome 프로그램 자체입니다. Rome 프로그램으로 되돌아가는 CPI는 거부됩니다.

## 7. Solidity에서 보는 deposit과 withdraw

레거시 경로의 어댑터에 대한 최소 스케치입니다. 사용자는 이미 `approve_spl(adapter, amount, mint)` 를 HelperProgram으로 보냈습니다(3절). `PRIVACY_PROGRAM` 는 여러분의 프로그램 ID입니다; `encodeDeposit` / `encodeWithdraw` 는 여러분의 instruction 데이터를 구성합니다(Borsh, 리틀엔디언). account meta는 여러분 instruction의 레이아웃을 따릅니다.

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

contract PrivacyAdapter {
    ICrossProgramInvocation constant Cpi    = ICrossProgramInvocation(0xFF00000000000000000000000000000000000008);
    IHelperProgram          constant Helper = IHelperProgram(0xFF00000000000000000000000000000000000009);
    bytes32 constant SPL_TOKEN = 0x06ddf6e1d765a193d9cbe146ceeb79ac1cb485ed5f5b37913a8cf5857eff00a9; // TokenkegQ...

    bytes32 immutable PRIVACY_PROGRAM;
    bytes32 immutable USDC_MINT;

    constructor(bytes32 program, bytes32 mint) {
        PRIVACY_PROGRAM = program; USDC_MINT = mint;
        Helper.create_pda(address(this));                 // 어댑터의 자체 Solana 신원
        Helper.create_ata(address(this), USDC_MINT);      // 그리고 어댑터가 소유한 USDC 계정
    }

    function _salt(address user) internal pure returns (bytes32) { return bytes32(uint256(uint160(user))); }

    function deposit(uint64 amount) external {
        bytes32 self       = Helper.pda(address(this));                   // 서명자: 어댑터의 권한
        bytes32 adapterAta = Helper.ata(address(this), USDC_MINT);
        bytes32 position   = Helper.pda_with_salt(address(this), _salt(msg.sender)); // 사용자별 하위 PDA, 역시 서명

        // 사용자의 토큰 계정에서 끌어옵니다. 어댑터의 권한이 SPL
        // delegate로 서명하며, 아래 CPI처럼 이것도 레거시 경로 호출입니다.
        Helper.transfer_spl(Helper.ata(msg.sender, USDC_MINT), adapterAta, amount, USDC_MINT);

        ICrossProgramInvocation.AccountMeta[] memory accs = new ICrossProgramInvocation.AccountMeta[](5);
        accs[0] = ICrossProgramInvocation.AccountMeta(self,       true,  true);
        accs[1] = ICrossProgramInvocation.AccountMeta(position,   true,  true);
        accs[2] = ICrossProgramInvocation.AccountMeta(adapterAta, false, true);                          // source: 어댑터의 권한이 소유
        accs[3] = ICrossProgramInvocation.AccountMeta(_vaultFor(position), false, true);                 // 여러분 프로그램의 볼트
        accs[4] = ICrossProgramInvocation.AccountMeta(SPL_TOKEN, false, false);

        bytes32[] memory salts = new bytes32[](1);
        salts[0] = _salt(msg.sender);
        Cpi.invoke_signed(PRIVACY_PROGRAM, accs, encodeDeposit(amount), salts);
    }

    function withdraw(uint64 amount) external {
        bytes32 position = Helper.pda_with_salt(address(this), _salt(msg.sender));
        bytes32 userAta  = Helper.ata(msg.sender, USDC_MINT);            // destination: 사용자의 자체 계정
        // ... 같은 형태: 여러분의 프로그램이 볼트에서 userAta로 `amount`를 이동시키며, `position`이 서명
        Cpi.invoke_signed(PRIVACY_PROGRAM, accs, encodeWithdraw(amount), salts);
    }
}
```

어댑터는 `wUSDC` 계약을 절대 호출하지 않습니다. pull은 사용자의 위임을 소모하는 HelperProgram 호출이며, 토큰은 `external_auth(adapter)` 가 소유하는 토큰 계정에 놓여 있으므로 CPI가 그것들을 사용할 수 있습니다.

서명자에 대한 노트. Rome은 정확히 두 종류의 계정에 대해 서명합니다: 호출하는 계약의 기본 권한(`Helper.pda(address(this))`), 이는 `salts`에 나열되지 않은 채로 서명하며, `salts`의 각 항목당 하나의 솔트가 붙은 하위 PDA입니다. 나열한 모든 솔트는 account list에서 서명자로 나타나야 하며, 그렇지 않으면 호출은 `제공된 seed로 계산된 signer 계정을 찾을 수 없습니다`오류로 실패합니다. 사용자의 자체 권한을 포함해 서명자로 표시된 다른 어떤 계정도 Rome으로부터 seed를 받지 못하며, Solana 런타임은 CPI를 거부합니다. 사용자가 자신의 토큰에 대해 가지는 권리는 위임에서 나오며, 어댑터가 사용자를 대신해 서명해서 나오는 것이 아닙니다.

pull 없는 위임: 여러분의 프로그램이 사용자의 토큰 계정에서 바로 지출해야 한다면, 사용자는 `HelperProgram.approve_spl_raw_delegate(userAta, yourProgramPda, amount, mint, decimals)` 를 직접 HelperProgram으로 보내며, 여러분 프로그램의 PDA를 SPL delegate로 지정합니다. Rome 브리지는 이를 Wormhole에 사용합니다. 3절의 one-delegate 규칙도 여기에도 적용됩니다: 이 권한 부여는 래퍼의 권한을 대체합니다.

## 8. 테스트

* 다음에 배포하세요 **Hadrian** (testnet, chain 200010) 먼저; 주소와 RPC는 [Contract Addresses](https://docs.rome.builders/ko/reference/contract-addresses.md) 그리고 [registry](https://github.com/rome-protocol/rome-registry).
* `eth_call` 그리고 `eth_estimateGas` 프록시가 전송에 사용하는 것과 동일한 에뮬레이션을 실행하므로, 그곳에서 실패하는 CPI는 같은 이유로 체인에서도 실패하며, revert data에는 하위 Solana 오류가 포함됩니다(`non-evm call error: …` Solana 프로그램 로그에 있음).
* 랜딩된 EVM 트랜잭션의 Solana 쪽은 `rome_solanaTxForEvmTx(hash)`로 읽으세요. Solana 영수증에는 CU와 여러분 프로그램의 로그가 있습니다.
* 에서 작동하는 CPI가 `eth_call` 로 보냈을 때 거부된다면, 대개 에뮬레이션이 보고한 한계에 걸린 것입니다: 64개 주소 한도, 원자적 CU 예산(트랜잭션이 반복 실행으로 넘어감), 또는 트랙 규칙입니다.

## 9. 레퍼런스

* [사전 컴파일 참조](https://docs.rome.builders/ko/reference/precompiles.md) — 모든 프리컴파일의 모든 selector와 그 디스패치 클래스 및 delegatecall 규칙.
* [제약 사항](https://docs.rome.builders/ko/core-concepts/constraints.md) — 위의 한계를 하나의 표로 정리.
* [토큰 상호운용성](https://docs.rome.builders/ko/core-concepts/token-interop.md) — 래퍼, 정식 mint, deposit과 withdraw.
* 공개 저장소의 레퍼런스 앱: [cardo](https://github.com/rome-protocol/cardo) (사용자가 CPI 프리컴파일을 직접 호출하는 형태 B), [rome-dex](https://github.com/rome-protocol/rome-dex) (직접 `invoke` 및 보관하지 않는 라우터, 형태 C), 그리고 [aerarium](https://github.com/rome-protocol/aerarium) (하나의 공유 시장 위에 구축된 Compound III 대출 앱; Solidity에서 Solana 프로그램을 호출하지 않으므로(CPI 없음), 어댑터의 예는 아닙니다).


---

# 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/developer-guides/integrate-solana-program.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.
