시작하기 | Solana

solana-test-validator를 구동하는 Solana 테스트 스위트는 테스트당 수 초가 걸립니다 — 프로세스 시작, RPC 연결, 네트워크 왕복 대기 시간이 발생하기 때문입니다. LiteSVM은 동일한 테스트를 밀리초 단위로 실행합니다. 외부 프로세스도 없고, 네트워크도 없으며, 모든 것이 테스트 러너 내부의 메모리 안에서 처리됩니다.

테스트 대상 버전: @solana/kit@6.8.0, @solana/kit-plugin-litesvm@0.10.0, @solana/kit-plugin-signer@0.10.0, @solana-program/system@0.12.0, @solana-program/token@0.13.0. 이 플러그인 패키지들은 새롭게 출시되어 빠르게 발전하고 있습니다 — 버전 불일치가 발생하면 testing/package.json에서 문서 및 테스트 스위트가 사용하는 정확한 버전을 확인하세요.

@solana/kit의 Kit 클라이언트는 .use()로 플러그인을 설치하여 구성합니다: 사이너 플러그인 (@solana/kit-plugin-signer), LiteSVM 플러그인 (@solana/kit-plugin-litesvm), 그리고 필요한 프로그램 플러그인을 추가하면 됩니다. 결과물은 client.sendTransaction(), client.rpc, 그리고 계정 상태, 클락, sysvars에 대한 직접 접근을 제공합니다 — 모두 프로세스를 벗어나지 않고 처리됩니다.

빠른 시작

의존성 설치

pnpm add @solana/kit @solana/kit-plugin-litesvm @solana/kit-plugin-signer @solana-program/system

클라이언트 생성

import { createClient, generateKeyPairSigner, lamports } from "@solana/kit";
import { litesvm } from "@solana/kit-plugin-litesvm";
import { signer } from "@solana/kit-plugin-signer";

// Payer first, then the LiteSVM transport.
const mySigner = await generateKeyPairSigner();
const client = createClient().use(signer(mySigner)).use(litesvm());

// Fund the payer
client.svm.airdrop(client.payer.address, lamports(5_000_000_000n));

// Check the balance
const balance = client.svm.getBalance(client.payer.address);
console.log("Balance:", balance, "lamports");

createClient()는 빈 껍데기를 반환하며, 각 .use(plugin) 호출이 기능을 추가합니다. signer() 플러그인은 반드시 litesvm() 이전에 와야 합니다. 트랜스포트 플러그인이 연결할 payer가 필요하기 때문입니다. signer(mySigner)는 동일한 keypair를 payer와 identity 양쪽에 설치하는 단축 표현입니다 — 두 역할을 분리하려면 동일 패키지의 payer() 또는 identity()를 사용하세요. 실제 네트워크에서 solanaRpc()를 사용할 때도 이 순서는 동일합니다.

빠른 실험을 위해 한 줄로 설정하고 싶으신가요? litesvm() 번들에는 에어드롭이 포함되어 있으므로, @solana/kit-plugin-signer의 .use(generatedPayerWithSol(lamports(10_000_000_000n)))을 체이닝하여 payer를 자동 생성하고 자금을 충전할 수 있습니다.

클라이언트 이해하기

.use(signer(...)).use(litesvm()) 이후 클라이언트가 노출하는 항목:

속성	설명
`client.payer`	`signer()` 플러그인으로 설치한 `TransactionSigner` (`client.identity`로도 설정됨)
`client.identity`	계정, 토큰, 권한을 소유하는 지갑 사이너
`client.svm`	계정 관리, 트랜잭션, 설정을 위한 직접 `LiteSVM` 인스턴스
`client.rpc`	Kit 호환 RPC 인터페이스 (지원 기능: `getAccountInfo`, `getBalance`, `getEpochSchedule`, `getLatestBlockhash`, `getMinimumBalanceForRentExemption`, `getMultipleAccounts`, `getSlot`, `requestAirdrop`)
`client.sendTransaction(s)`	명령을 계획하고, 서명하고, 트랜잭션으로 전송
`client.airdrop`	LiteSVM 파우셋에서 SOL 요청
`client.getMinimumBalance`	rent 면제를 위한 최소 lamport 계산

client.svm 사용하기

다음을 위한 LiteSVM 직접 접근:

계정 관리 (setAccount, getAccount, airdrop)
트랜잭션 실행 (sendTransaction, simulateTransaction)
설정 (withSigverify, withBlockhashCheck 등)
시간 조작 (warpToSlot, getClock)

import { address, lamports } from "@solana/kit";

// Fund an account
client.svm.airdrop(address, lamports(1_000_000_000n));

// Set account state directly
client.svm.setAccount({
  address: myAddress,
  data: new Uint8Array([1, 2, 3]),
  executable: false,
  lamports: lamports(1_000_000n),
  programAddress: address("11111111111111111111111111111111"),
  space: 3n
});

// Get the latest blockhash
const blockhash = client.svm.latestBlockhash();

client.rpc 사용하기

표준 작업을 위한 Kit 호환 RPC 인터페이스:

// Get account info (returns base64-encoded data)
const { value: account } = await client.rpc.getAccountInfo(address).send();

// Get multiple accounts in one call
const { value: accounts } = await client.rpc
  .getMultipleAccounts([addr1, addr2, addr3])
  .send();

// Get latest blockhash
const { value: blockhash } = await client.rpc.getLatestBlockhash().send();

RPC 레이어는 base64 인코딩만 지원합니다. 다른 인코딩을 요청하면 오류가 발생합니다.

설정

client.svm의 빌더 메서드를 사용하여 LiteSVM을 설정합니다:

const client = createClient().use(signer(mySigner)).use(litesvm());

// Configure for testing
client.svm
  .withSigverify(false) // Skip signature verification
  .withBlockhashCheck(false) // Skip blockhash validation
  .withSysvars() // Enable Clock, Rent, etc.
  .withBuiltins() // Enable ed25519, secp256k1
  .withTransactionHistory(100n); // Store transaction history

트랜잭션 전송

트랜스포트 이후에 프로그램 플러그인을 레이어링하세요 — 클라이언트에 명령 빌더를 연결해주므로 원시 TransactionMessage를 직접 다룰 필요가 없습니다:

import { createClient, generateKeyPairSigner, lamports } from "@solana/kit";
import { litesvm } from "@solana/kit-plugin-litesvm";
import { signer } from "@solana/kit-plugin-signer";
import { systemProgram } from "@solana-program/system";

const mySigner = await generateKeyPairSigner();
const client = createClient()
  .use(signer(mySigner))
  .use(litesvm())
  .use(systemProgram());

client.svm.airdrop(client.payer.address, lamports(10_000_000_000n));

const recipient = await generateKeyPairSigner();

// Build and send in one call
await client.system.instructions
  .transferSol({
    source: client.payer,
    destination: recipient.address,
    amount: lamports(1_000_000_000n)
  })
  .sendTransaction();

SVM → RPC 흐름

SVM으로 상태를 설정하고 RPC로 읽을 수 있습니다:

import { address, lamports } from "@solana/kit";

// Set account directly via SVM
client.svm.setAccount({
  address: myAddress,
  data: new Uint8Array([0xde, 0xad, 0xbe, 0xef]),
  executable: false,
  lamports: lamports(1_000_000n),
  programAddress: address("11111111111111111111111111111111"),
  space: 4n
});

// Read via RPC (returns base64-encoded data)
const { value } = await client.rpc.getAccountInfo(myAddress).send();
console.log("Data:", value?.data); // ['3q2+7w==', 'base64']

다음 단계

여기서는 핵심 클라이언트인 계정 생성, 명령 전송, 상태 읽기를 다뤘습니다. 테스트에 SPL 토큰(민트, ATA, 전송)이 포함된다면, 토큰 테스트 가이드에서 tokenProgram() 플러그인으로 약 40줄의 설정을 3번의 호출로 줄이는 방법을 확인하세요. 전체 API 레퍼런스는 API 문서를 참조하세요.

목차