JS API 레퍼런스

@solana/surfpool 패키지는 하나의 클래스인 Surfnet와 해당 메서드를 타입 안전하게 호출하는 데 필요한 보조 타입들을 제공합니다. 이 페이지에는 내보내진 모든 심볼이 나열되어 있으며, 사용 방법에 대한 설명은 개요부터 시작하는 가이드를 참고하세요.

패키지 내보내기

심볼	종류	설명
`Surfnet`	클래스	치트코드 메서드가 포함된 실행 중인 Surfnet 인스턴스
`SurfnetConfig`	타입	`Surfnet.startWithConfig`의 인수
`DeployOptions`	타입	`Surfnet.deploy`의 인수
`SetTokenAccountUpdate`	타입	`Surfnet.setTokenAccount`의 인수
`ResetAccountOptions`	타입	`Surfnet.resetAccount`의 인수
`StreamAccountOptions`	타입	`Surfnet.streamAccount`의 인수
`SolAccountFunding`	타입	`Surfnet.fundSolMany`에 전달되는 배열의 요소
`SimnetEventValue`	타입	`Surfnet.drainEvents`가 반환하는 요소
`KeypairInfo`	타입	`Surfnet.newKeypair`가 반환하는 값
`ClockValue`	타입	`SimnetEventValue`의 필드
`EpochInfoValue`	타입	시간 여행 헬퍼가 반환하는 값
`ByteArrayLike`	타입	`Uint8Array \| number[]` — 유연한 바이트 입력

Surfnet 클래스

정적 메서드

class Surfnet {
  static start(): Surfnet;
  static startWithConfig(config: SurfnetConfig): Surfnet;
  static newKeypair(): KeypairInfo;
}

인스턴스 속성

class Surfnet {
  readonly rpcUrl: string; // http://127.0.0.1:<port>
  readonly wsUrl: string; // ws://127.0.0.1:<port>
  readonly payer: string; // base58 public key
  readonly payerSecretKey: Uint8Array; // 64-byte private key
  readonly instanceId: string;
}

라이프사이클

class Surfnet {
  stop(): void; // idempotent; safe to call from `finally` / test teardown
}

SOL 치트코드

class Surfnet {
  fundSol(address: string, lamports: number): void;
  fundSolMany(accounts: SolAccountFunding[]): void;
  setAccount(
    address: string,
    lamports: number,
    data: Uint8Array,
    owner: string
  ): void;
  resetAccount(address: string, options?: ResetAccountOptions): void;
}

토큰 치트코드

class Surfnet {
  fundToken(
    owner: string,
    mint: string,
    amount: number,
    tokenProgram?: string
  ): void;
  fundTokenMany(
    owners: string[],
    mint: string,
    amount: number,
    tokenProgram?: string
  ): void;
  setTokenBalance(
    owner: string,
    mint: string,
    amount: number,
    tokenProgram?: string
  ): void;
  setTokenAccount(
    owner: string,
    mint: string,
    update: SetTokenAccountUpdate,
    tokenProgram?: string
  ): void;
  getAta(owner: string, mint: string, tokenProgram?: string): string;
}

시간 여행

class Surfnet {
  timeTravelToSlot(slot: number): EpochInfoValue;
  timeTravelToEpoch(epoch: number): EpochInfoValue;
  timeTravelToTimestamp(timestampMs: number): EpochInfoValue;
}

프로그램 배포

class Surfnet {
  deployProgram(programName: string): string; // returns program id
  deploy(options: DeployOptions): string; // returns program id
}

스트리밍 및 이벤트

class Surfnet {
  streamAccount(address: string, options?: StreamAccountOptions): void;
  drainEvents(): SimnetEventValue[];
}

설정 타입

SurfnetConfig

interface SurfnetConfig {
  offline?: boolean; // default: true
  remoteRpcUrl?: string; // setting this implies offline=false
  blockProductionMode?: "manual" | "clock" | "transaction"; // default: "transaction"
  slotTimeMs?: number; // default: 1
  airdropSol?: number; // lamports; default: 10_000_000_000
  airdropAddresses?: string[];
  payerSecretKey?: ByteArrayLike;
  enableFeatures?: string[]; // feature IDs (base58 or kebab name)
  disableFeatures?: string[];
  allFeatures?: boolean;
}

DeployOptions

interface DeployOptions {
  programId: string; // base58 address
  soPath?: string; // mutually exclusive with soBytes
  soBytes?: ByteArrayLike;
  idlPath?: string; // optional Anchor IDL JSON
}

SetTokenAccountUpdate

interface SetTokenAccountUpdate {
  amount?: number;
  delegate?: string; // base58 pubkey
  clearDelegate?: boolean;
  state?: string; // e.g. "initialized", "frozen"
  delegatedAmount?: number;
  closeAuthority?: string;
  clearCloseAuthority?: boolean;
}

ResetAccountOptions

interface ResetAccountOptions {
  includeOwnedAccounts?: boolean;
}

StreamAccountOptions

interface StreamAccountOptions {
  includeOwnedAccounts?: boolean;
}

SolAccountFunding

interface SolAccountFunding {
  address: string;
  lamports: number;
}

KeypairInfo

interface KeypairInfo {
  publicKey: string; // base58
  secretKey: number[]; // 64 bytes
}

ByteArrayLike

type ByteArrayLike = Uint8Array | number[];

메서드가 ByteArrayLike를 허용하는 경우, Uint8Array 또는 일반 숫자 배열을 전달할 수 있습니다. 래퍼는 두 형식을 네이티브 바인딩이 기대하는 형식으로 정규화합니다.

이벤트 타입

SimnetEventValue

kind 판별자와 선택적 필드를 포함하는 플랫 객체입니다. 변형 카탈로그는 이벤트를 참조하세요.

interface SimnetEventValue {
  kind: string;
  message?: string;
  timestamp?: string;
  initialTransactionCount?: number;
  clock?: ClockValue;
  epochInfo?: EpochInfoValue;
  accountPubkey?: string;
  clockCommand?: string;
  slotIntervalMs?: number;
  transactionSignature?: string;
  logs?: string[];
  computeUnitsConsumed?: number;
  fee?: number;
  errorMessage?: string;
  tag?: string;
  profileKey?: string;
  profileSlot?: number;
  runbookId?: string;
  runbookErrors?: string[];
}

ClockValue

interface ClockValue {
  slot: number;
  epoch: number;
  leaderScheduleEpoch: number;
  unixTimestamp: number;
  epochStartTimestamp: number;
}

EpochInfoValue

interface EpochInfoValue {
  absoluteSlot: number;
  slotIndex: number;
  slotsInEpoch: number;
  epoch: number;
  blockHeight: number;
  transactionCount?: number;
}

오류

모든 메서드는 표준 Error를 발생시키며, 메시지에는 기본 Rust SurfnetError가 포함됩니다. 케이스를 구분하려면 error.message를 검사하세요.

try {
  surfnet.deploy({ programId, soPath: "missing.so" });
} catch (err) {
  // err.message starts with "Cheatcode:" / "Startup:" / etc.
  console.error(err);
}

네이티브 모듈 풋프린트

이 패키지는 optionalDependencies(으)로 배포된 플랫폼별 네이티브 바이너리에 의존합니다:

트리플	패키지
`aarch64-apple-darwin`	`@solana/surfpool-darwin-arm64`
`x86_64-apple-darwin`	`@solana/surfpool-darwin-x64`
`x86_64-unknown-linux-gnu`	`@solana/surfpool-linux-x64-gnu`

플랫폼 패키지 중 어느 것도 사용 중인 머신에 설치되지 않으면, Surfnet.start()가 첫 번째 호출 시 "네이티브 모듈을 찾을 수 없음" 오류와 함께 예외를 발생시킵니다. 지원 매트릭스 및 문제 해결 방법은 설치를 참조하세요.

목차