> 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/products/rome-sdk.md).

# Rome SDK

EVM 계약에서 Solana 프로그램을 호출하기 위한 타입 지정 Solidity 인터페이스와 Rome의 오프체인 서비스를 뒷받침하는 Rust SDK.

Rome SDK는 EVM 스마트 계약에서 Solana 프로그램과 상호작용하기 위한 타입이 지정된 Solidity 인터페이스를 제공합니다. Rome에서 크로스 런타임 애플리케이션을 구축하기 위한 개발자 툴킷입니다.

## SDK

Rome은 세 대상용 SDK를 제공합니다 — 앱 빌더(TypeScript), 계약 개발자(Solidity), 그리고 Rome에서 자체 서비스를 운영하는 팀(Rust).

### TypeScript SDK (`@rome-protocol/sdk`)

**dapp 및 프런트엔드 개발자용** — 대부분의 앱 빌더가 가장 먼저 사용하는 SDK입니다. [`@rome-protocol/sdk`](https://github.com/rome-protocol/rome-sdk-ts) 웹 앱이 Rome 트랜잭션을 올바르게 제출하도록 Rome 쓰기 경로를 감쌉니다: `submitRomeTx` (올바른 쓰기 경로와 gas/fee 처리), PDA / ATA 파생, CPI `invoke` / `invoke_signed` 인코더, 프리컴파일 바인딩, 그리고 `/bridge` 하위 경로. 저장소 우선 설치(npm publish 예정):

```bash
npm install github:rome-protocol/rome-sdk-ts#v0.4.0
```

```typescript
import { submitRomeTx } from '@rome-protocol/sdk';
// 올바른 쓰기 경로를 통해 모든 Rome EVM 쓰기를 제출합니다(gas/fee 인코딩 처리).
```

공개 [rome-dex](https://github.com/rome-protocol/rome-dex) 앱은 SDK의 몇 가지 헬퍼만 사용합니다(PDA 및 토큰 계정 파생, CPI `invoke` 인코더와 1.3배 gas 패드), 그리고 [cardo](https://github.com/rome-protocol/cardo) 그것에 의존하지 않습니다. 또한 호출하지도 않습니다 `submitRomeTx` 또는 `submitRomeTxV1`, 따라서 앱이 CPI 프리컴파일을 호출하는 방법을 보려면 그것들을 읽고, SDK의 쓰기 경로를 보려는 것은 아닙니다.

**두 경로, 하나의 SDK.** `submitRomeTx` 는 EVM 경로(MetaMask)입니다. For the **Solana 경로** — Solana 지갑이 여러분의 EVM 앱을 구동하는 경우 — `submitRomeTxV1` 이를 그대로 따릅니다: 프록시는 호출을 위해 하나의 Solana v1 트랜잭션을 구성하고, 지갑은 같은 키로 두 번 서명하며(읽을 수 있는 권한 부여 메시지, 그다음 트랜잭션), Rome은 사용자의 파생된 ID에서 나온 EVM 트랜잭션으로 해당 호출을 실행하며 EVM 키는 사용하지 않습니다. 하나의 트랜잭션에 들어가지 않는 호출은 같은 권한 부여 서명으로 프록시가 중계하며, 그리고 `fundSyntheticGas` 중계된 호출이 소비한 네이티브 gas를 보충합니다. 되돌려지는 중계 호출은 다음으로 반환됩니다 `receipt.status === "0x0"` 예외를 던지는 대신, 이를 확인하세요; the [중계된 호출 및 장시간 호출](https://docs.rome.builders/ko/developer-guides/call-evm-from-solana.md#relayed-calls-and-long-calls) 섹션에 gas 규칙과 제한이 있습니다. 값의 이동은 다음을 통해 들어오고 나갑니다 `buildFundLeg` / `buildSweepLeg` ERC-20 래퍼로서(예: `wUSDC`), 네이티브가 아니라 `msg.value` — 합성 송신자는 대기 상태에서 아무것도 보유하지 않습니다 — 그리고 최초의 합성 계정은 한 번, 명시적으로 다음과 함께 프로비저닝됩니다 `buildCreatePdaCall`. 이전의 `submitRomeTxSolanaLane`, 클라이언트에서 레거시 Solana 트랜잭션을 생성하는 것은 여전히 SDK에 있습니다. See [듀얼 레인 앱 빌드](https://docs.rome.builders/ko/developer-guides/dual-lane-app.md) 그리고 [Solana에서 EVM 호출](https://docs.rome.builders/ko/developer-guides/call-evm-from-solana.md).

### Solidity SDK (`@rome-protocol/rome-solidity`)

**Solidity 개발자용.** 프리컴파일 인터페이스, ERC-20/SPL 래퍼, PDA 파생, 그리고 CPI 유틸리티를 제공합니다. npm publish는 예정되어 있으며; 현재는 공개 [`rome-solidity`](https://github.com/rome-protocol/rome-solidity) 저장소(git 의존성 또는 복사된 파일)에서 이것들을 사용합니다.

```solidity
import {ISystemProgram, ICrossProgramInvocation, IHelperProgram, IWithdraw}
    from "@rome-protocol/rome-solidity/contracts/interface.sol";
import {SPL_ERC20} from "@rome-protocol/rome-solidity/contracts/erc20spl/erc20spl.sol";
import {RomeEVMAccount} from "@rome-protocol/rome-solidity/contracts/rome_evm_account.sol";
```

### Rust SDK (`rome-sdk`)

**Rome에서 자체 서비스를 운영하는 팀용.** 트랜잭션 구성, Solana 상호작용, gas 가격 책정, 블록 인덱싱을 처리하는 Rust 워크스페이스입니다. Proxy와 Hercules는 이를 기반으로 구축됩니다. 소스는 다음에 있습니다 [`rome-protocol/rome-sdk`](https://github.com/rome-protocol/rome-sdk). Solana v1 트랜잭션(4 KB, 최대 64개 계정)을 보냅니다.

**빌드하기.** 워크스페이스는 저장소들이 [`rome-sdk`](https://github.com/rome-protocol/rome-sdk), [`rome-evm`](https://github.com/rome-protocol/rome-evm) 그리고 [`mollusk`](https://github.com/rome-protocol/mollusk) 나란히 클론되어 있기를 기대합니다. 이는 상대 경로로 나머지 두 저장소에 의존하기 때문입니다. 이것이 다른 프로젝트에서 이를 사용하는 지원되는 방식이 일반 git 의존성이 아니라 path dependency인 이유이기도 합니다. 첫 빌드에는 Rust 1.85 이상과 네트워크 접근이 필요합니다. `rome-evm` 기본 네트워크 기능이 없으므로, 이를 컴파일하는 모든 빌드는 다음 중 정확히 하나가 필요합니다 `ci`, `테스트넷` 또는 `메인넷`; use `ci` 로컬 작업에 사용하세요, 예를 들면 `cargo test -p rome-sdk --features ci`. 저장소 README에는 전체 단계와 기능 표가 있습니다.

**라이선스.** Rust SDK는 오픈 소스가 아니라 source-available입니다: all rights reserved이며 개인적, 비상업적 용도로 사용할 수 있습니다. 상업적 사용에는 Rome Protocol의 서면 허가가 필요합니다; 저장소의 `LICENSE` 에 요청 방법이 적혀 있습니다.

## Solidity SDK: 포함 내용

### 프리컴파일 인터페이스

인터페이스를 해당 프리컴파일 주소에 바인딩합니다:

```solidity
ISystemProgram          constant System   = ISystemProgram(0xFF00000000000000000000000000000000000007);
ICrossProgramInvocation constant Cpi      = ICrossProgramInvocation(0xFF00000000000000000000000000000000000008);
IHelperProgram          constant Helper   = IHelperProgram(0xFF00000000000000000000000000000000000009);
IWithdraw               constant Withdraw = IWithdraw(0x4200000000000000000000000000000000000016);
// 캐시된 경로: ISplCached 0xff…05, IAssociatedSplCached 0xff…06, ISystemCached 0xff…04, IWithdrawCached 0xff…0b
```

### SPL 토큰 작업

사용 `IHelperProgram` (`0xff…09`) 사용자 PDA 서명 SPL 프리미티브용:

```solidity
// 민트에 대한 호출자의 ATA를 생성합니다
Helper.create_ata(user, mint);

// 호출자의 PDA에서 SPL을 전송합니다
Helper.transfer_spl(to, tokens, mint);
```

캐시된 경로에서는 해당 작업이 다음에 있습니다 `ISplCached` (`0xff…05`) 그리고 `IAssociatedSplCached` (`0xff…06`). See `의 CPI 프리컴파일` 모든 오버로드에 대해; 계약은 하나의 경로를 일관되게 사용합니다.

### PDA 파생

```solidity
// 사용자의 Solana PDA를 파생합니다
bytes32 userPda = RomeEVMAccount.pda(msg.sender);

// salt로 PDA를 파생합니다(사용자당 여러 PDA를 생성하기 위해)
bytes32 pda = RomeEVMAccount.pda_with_salt(msg.sender, salt);

// 임의의 PDA를 찾습니다
(bytes32 pda, uint8 bump) = SystemProgram.find_program_address(programId, seeds);
```

### 크로스 프로그램 호출

```solidity
// 모든 Solana 프로그램을 호출합니다
ICrossProgramInvocation.AccountMeta[] memory accounts = new ICrossProgramInvocation.AccountMeta[](2);
accounts[0] = ICrossProgramInvocation.AccountMeta(signerPda, true, true);
accounts[1] = ICrossProgramInvocation.AccountMeta(targetAccount, false, true);

CpiProgram.invoke(programId, accounts, instructionData);

// PDA 서명으로 호출
CpiProgram.invoke_signed(programId, accounts, data, seeds);

// 계정 데이터를 읽습니다
(uint64 lamports, bytes32 owner, bool isSigner, bool isWritable, bool executable, bytes memory data)
    = CpiProgram.account_info(pubkey);
```

### SPL 토큰 위의 ERC-20

```solidity
// 모든 SPL 민트에 대한 래퍼를 배포합니다
ERC20SPLFactory factory = ERC20SPLFactory(FACTORY_ADDRESS);
address wrapper = factory.add_spl_token_with_metadata(splMint);

// 래퍼를 표준 ERC-20으로 사용합니다
SPL_ERC20 token = SPL_ERC20(wrapper);
token.transfer(recipient, amount);
uint256 balance = token.balanceOf(user);
```

### Borsh 역직렬화

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

// Solana 계정 데이터를 파싱합니다(리틀 엔디안 Borsh 형식)
(uint64 value, uint256 newOffset) = Convert.read_u64le(data, offset);
(bytes32 pubkey, uint256 newOffset2) = Convert.read_bytes32(data, offset);
```

### Metaplex 메타데이터

```solidity
import {MplTokenMetadataLib} from "@rome-protocol/rome-solidity/contracts/mpl_token_metadata/lib.sol";

// Metaplex에서 토큰 메타데이터를 불러옵니다
MplTokenMetadataLib.Metadata memory meta = MplTokenMetadataLib.load_metadata(
    mintPubkey, mplProgramId, cpiAddress
);
string memory name = meta.name;
string memory symbol = meta.symbol;
```

## Rust SDK: 아키텍처

Rust SDK는 Cargo 워크스페이스입니다. 핵심 크레이트는 다음과 같습니다:

| 크레이트                | 목적                                                                                             |
| ------------------- | ---------------------------------------------------------------------------------------------- |
| `rome-sdk`          | 핵심 API: `Rome` struct, 구성, 세 가지 트랜잭션 유형(`RheaTx`, `RemusTx`, `RomulusTx`)                      |
| `rome-evm-client`   | Rome 체인을 위한 EVM 클라이언트, TxBuilder, ResourceFactory, 에뮬레이터 통합                                    |
| `rome-solana`       | Solana 타워, RPC 클라이언트, 트랜잭션 배칭 및 추적                                                             |
| `rome-utils`        | RLP, hex, JSON-RPC, 인증 유틸리티                                                                    |
| `rome-obs`          | OpenTelemetry 관측성(트레이스, 메트릭, 로그)                                                               |
| `rome-meteora`      | gas 가격 책정을 위한 Meteora DAMM v1 및 v2 풀 리더                                                        |
| `rome-meta-hook`    | Meta-Hook Router 프로그램용 클라이언트: Token-2022 transfer-hook 구성, 추가 계정 해석, compute-budget 추정이 포함된 전송 |
| `rome-jito-bundler` | 원자적 다중 트랜잭션 제출을 위한 Jito 번들 빌더                                                                  |

### 트랜잭션 유형

```rust
// 하나의 Rome 체인에서 하나의 EVM 트랜잭션
let rhea = RheaTx::new(signed_eth_tx);
let mut tx = rome.compose_rollup_tx(rhea).await?;
let sig = rome.send_and_confirm(&mut *tx).await?;

// 서로 다른 Rome 체인에 걸친 여러 EVM 트랜잭션, 하나의 Solana 트랜잭션에서 원자적
let remus = RemusTx::new(vec![tx1, tx2]);
let mut tx = rome.compose_cross_rollup_tx(remus).await?;

// EVM 트랜잭션과 네이티브 Solana 명령, 하나의 Solana 트랜잭션에서 원자적
let romulus = RomulusTx::new(eth_txs, sol_ixs);
let mut tx = rome.compose_cross_chain_tx(romulus, signers).await?;
```

### 리소스 풀링

SDK는 병렬 트랜잭션 제출을 위해 Solana 키페어(지불자)와 홀더 계정 인덱스를 풀링합니다:

```rust
let resource = resource_factory.get().await?;
let payer = resource.payer();       // Solana 키페어
let holder = resource.holder();     // 홀더 계정 인덱스
// 리소스는 Drop 시 자동으로 풀에 반환됩니다
```

## SDK 로드맵

### 구현 완료 및 작동 중

* SPL 토큰 래퍼 및 프리컴파일 인터페이스
* CPI를 통한 Meteora DAMM v1 스왑
* Oracle Gateway V1 + V2(Pyth Pull, Switchboard V3)
* System Program 헬퍼, Borsh 역직렬화
* ERC20SPL Factory + 브리지 계약

## 다음은 무엇인가

* [Solidity 배포](https://docs.rome.builders/ko/developer-guides/deploy-solidity.md) — SDK를 사용해 첫 계약을 배포하세요
* [EVM에서 Solana 호출](https://docs.rome.builders/ko/developer-guides/call-solana-from-evm.md) — CPI를 사용해 Solana 프로그램과 상호작용하세요
* [Contract Addresses](https://docs.rome.builders/ko/reference/contract-addresses.md) — 배포된 SDK 계약 주소


---

# 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/products/rome-sdk.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.
