Kit 클라이언트

@solana/kit은 플러그인으로 확장하는 경량 호스트인 createClient를 제공합니다. 각 플러그인은 RPC 연결, 서명자, 트랜잭션 계획 등의 기능을 추가하며, 구성된 클라이언트는 스크립트, 서버 라우트, UI 모두에서 활용할 수 있습니다.

설치

$ 
npm install @solana/kit @solana/kit-plugin-rpc @solana/kit-plugin-signerCopy

패키지 매니저는 무엇이든 사용할 수 있습니다. Kit는 v7 이상이며, @solana/kit-plugin-* 패키지는 0.13 이상입니다.

클라이언트 생성

.use(...)로 플러그인을 구성합니다. 서명자를 먼저 설정한 후 RPC 연결을 설정하세요. solanaDevnetRpc()는 client.rpc, 구독, 트랜잭션 플래너/실행기, 그리고 client.sendTransaction 헬퍼를 추가하므로, 앱에서 이 요소들을 직접 연결할 필요가 거의 없습니다.

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

const payer = await generateKeyPairSigner();

const client = createClient().use(signer(payer)).use(solanaDevnetRpc());

const slot = await client.rpc.getSlot().send();
console.log("current slot", slot);

signer 플러그인은 수수료 지불자와 앱 신원을 모두 설정합니다. RPC 번들은 지불자가 먼저 설정되어 있어야 하므로, 순서가 중요합니다.

서명자 변형

@solana/kit-plugin-signer는 클라이언트에 필요한 권한만 부여할 수 있도록 세 가지 역할을 제공합니다:

• signer(x) — client.payer와 client.identity 모두 설정합니다.
• payer(x) — 수수료 지불자 전용입니다.
• identity(x) — 앱 권한 전용입니다.

각각 테스트와 스크립트를 위한 *FromFile(path) (Node), generated*(), generated*WithSol(amount), airdrop*() 변형이 있습니다.

트랜잭션 전송

생성된 프로그램 클라이언트로 명령어를 구성한 후 client.sendTransaction에 전달합니다. 플래너는 블록해시를 확인하고, 컴퓨팅 비용을 추정하고, 클라이언트의 지불자로 서명한 뒤 제출합니다.

import { getTransferSolInstruction } from "@solana-program/system";
import { address, lamports } from "@solana/kit";

const transfer = getTransferSolInstruction({
  source: client.payer,
  destination: address("Fke...address"),
  amount: lamports(10_000_000n) // 0.01 SOL
});

const { context } = await client.sendTransaction([transfer]);
console.log("submitted", context.signature);

sendTransaction은 결과 객체로 resolve되며, 트랜잭션 서명은 result.context.signature에서 확인할 수 있습니다. 플랜이 단일 트랜잭션에 맞지 않으면 오류를 발생시키므로, 배치가 여러 트랜잭션에 걸칠 경우 sendTransactions를 사용하세요.

RPC 번들 선택

@solana/kit-plugin-rpc는 클러스터 프리셋을 제공합니다:

• solanaDevnetRpc() — devnet 기본값, 에어드롭 활성화 (client.airdrop).
• solanaMainnetRpc() — mainnet; 에어드롭은 컴파일 타임 오류입니다.
• solanaLocalRpc() — 로컬 validator용 http://127.0.0.1:8899.
• solanaRpc({ rpcUrl }) — 임의의 엔드포인트.

import { solanaRpc } from "@solana/kit-plugin-rpc";

const client = createClient()
  .use(signer(payer))
  .use(solanaRpc({ rpcUrl: "https://your-rpc-provider.example" }));

세밀하게 구성하기

프리셋은 RPC 연결, 플래너, 실행기, 전송 헬퍼를 번들로 제공하므로 대부분의 앱은 개별 요소가 필요하지 않습니다. 개별 플러그인으로 내려가는 것은 하나를 커스터마이즈할 때만 사용하세요 — 예를 들어 커스텀 플래너나 다른 구독 채널이 필요한 경우입니다. 이 경로에는 프리셋이 기본으로 포함하는 @solana/kit-plugin-instruction-plan도 별도로 필요합니다:

import {
  solanaRpcConnection,
  rpcAirdrop,
  rpcTransactionPlanner,
  rpcTransactionPlanExecutor
} from "@solana/kit-plugin-rpc";
import { planAndSendTransactions } from "@solana/kit-plugin-instruction-plan";

const client = createClient()
  .use(signer(payer))
  .use(solanaRpcConnection({ rpcUrl: "https://api.devnet.solana.com" }))
  .use(rpcAirdrop())
  .use(rpcTransactionPlanner())
  .use(rpcTransactionPlanExecutor())
  .use(planAndSendTransactions());

프로그램 클라이언트 추가

생성된 @solana-program/* 패키지는 클라이언트 플러그인을 제공하여 프로그램 호출을 클라이언트에 연결할 수 있습니다. 필요한 프로그램을 설치하고 .use()로 플러그인을 추가하세요:

import { tokenProgram } from "@solana-program/token";

const client = createClient()
  .use(signer(payer))
  .use(solanaDevnetRpc())
  .use(tokenProgram()); // adds client.token

브라우저 지갑 없이 서명하기

API 라우트, 워커, 또는 스크립트에서 헤드리스로 실행 중인가요? 원시 keypair 대신 백엔드 키 관리 서비스로 서명하세요. Keychain과 프로덕션에서 서명하기를 참고하세요.

Solana 개발자를 위한 일반적인 패턴

• 공유 설정: 핵심 모듈에서 클라이언트를 한 번 빌드하고 스크립트, 서버 라우트, UI에서 가져다 사용하세요.
• 서버 사이드 읽기: signer + solanaRpc만으로 구성된 클라이언트(지갑 플러그인 없음)는 서버에서 계정을 읽고 트랜잭션을 시뮬레이션합니다.
• 로컬 테스트: @solana/kit-plugin-litesvm의 .use(litesvm())으로 RPC 번들을 교체하여 인메모리 validator에서 실행합니다 (Node 전용).
• 테스트 용이성: 구성된 클라이언트는 모킹이 쉬워 — 브라우저 지갑 없이도 RPC 응답이나 서명자를 스텁으로 대체할 수 있습니다.