프로그램 배포

SDK는 로컬 빌드 아티팩트에서 한 번의 호출로 프로그램을 배포할 수 있습니다. 두 가지 방식이 있습니다: 관습적인 경로를 사용하는 Anchor/Agave 워크스페이스를 위한 자동 검색 방식과, 바이트의 출처를 직접 제어하고 싶을 때 사용하는 명시적 배포 방식입니다.

두 방식 모두 IDL에 선언된 주소(또는 keypair 파일의 공개 키)에 프로그램을 등록하고, IDL이 있는 경우 surfnet_registerIdl를 통해 런타임에 등록하여 RPC 클라이언트가 계정 데이터를 디코딩할 수 있도록 합니다.

Anchor 워크스페이스 자동 검색

deployProgram / deploy_program는 프로그램 이름을 받아 현재 작업 디렉토리를 기준으로 다음 파일들을 검색합니다:

파일	용도
`target/deploy/{name}.so`	컴파일된 프로그램 바이트코드 (필수)
`target/deploy/{name}-keypair.json`	프로그램 keypair — 공개 키가 프로그램 ID가 됩니다 (필수)
`target/idl/{name}.json`	Anchor IDL JSON (선택 사항; 존재할 경우 등록됨)

use surfpool_sdk::Surfnet;

let surfnet = Surfnet::start().await?;
let cheats = surfnet.cheatcodes();

let program_id = cheats.deploy_program("my_program")?;
println!("deployed at {program_id}");

배포 전에 빌드를 먼저 실행하세요

deployProgram를 호출하기 전에 anchor build (또는 cargo build-sbf)를 실행하여 .so 및 keypair 아티팩트가 실제로 디스크에 존재하도록 하세요. SDK는 빌드를 자동으로 실행하지 않습니다.

명시적 배포

아티팩트가 비표준 위치에 있는 경우 — CI 빌드 아티팩트, 미리 준비된 테스트 픽스처, 내장된 바이트 슬라이스 등 — 명시적인 배포 설정을 전달하세요.

use surfpool_sdk::cheatcodes::builders::DeployProgram;
use surfpool_sdk::Surfnet;

let cheats = Surfnet::start().await?.cheatcodes();

// Derive the program ID from a keypair file.
let program_id = cheats.deploy(
    DeployProgram::from_keypair_path("fixtures/my_program-keypair.json")?
        .so_path("fixtures/my_program.so")
        .idl_path("fixtures/my_program.idl.json"),
)?;

원시 바이트에서 배포

바이트코드가 이미 메모리에 있는 경우 — 빌드 단계에서 생성되었거나, 아티팩트 저장소에서 다운로드되었거나, include_bytes!를 통해 내장된 경우 — 파일 시스템을 완전히 건너뛸 수 있습니다.

use surfpool_sdk::cheatcodes::builders::DeployProgram;
use surfpool_sdk::{Pubkey, Surfnet};

const PROGRAM_BYTES: &[u8] = include_bytes!("../fixtures/my_program.so");

let cheats = Surfnet::start().await?.cheatcodes();
let program_id: Pubkey = "DemoProgram111111111111111111111111111111111".parse()?;

cheats.deploy(
    DeployProgram::new(program_id).so_bytes(PROGRAM_BYTES.to_vec()),
)?;

DeployProgram 빌더 참조 (Rust)

생성자 / 설정자	시그니처	목적
`DeployProgram::new`	`(program_id: Pubkey) -> Self`	알려진 프로그램 ID로 배포를 빌드합니다.
`DeployProgram::from_keypair_path`	`(path: impl AsRef<Path>) -> SurfnetResult<Self>`	Solana keypair 파일을 읽고, 공개 키가 프로그램 ID가 됩니다.
`.so_path`	`(path: impl Into<PathBuf>)`	디스크에 있는 컴파일된 `.so` 아티팩트의 경로입니다.
`.so_bytes`	`(bytes: Vec<u8>)`	원시 프로그램 바이트 (`so_path`와 상호 배타적).
`.idl_path`	`(path: impl Into<PathBuf>)`	배포 후 등록할 선택적 Anchor IDL JSON.

DeployOptions 타입 참조 (JS)

type ByteArrayLike = Uint8Array | number[];

interface DeployOptions {
  programId: string; // base58 address to deploy at
  soPath?: string; // path to .so on disk
  soBytes?: ByteArrayLike; // or raw bytes in memory
  idlPath?: string; // optional Anchor IDL JSON
}

soPath와 soBytes는 상호 배타적입니다 — 정확히 하나만 제공하세요.

등록되는 항목

배포가 성공하면 런타임은 세 가지 작업을 수행합니다:

program account를 기록합니다 programId에 .so 바이트를 surfnet_writeProgram를 통해 씁니다.
계정을 실행 가능으로 표시합니다 그러면 일반 RPC 호출을 통해 호출할 수 있습니다.
IDL을 등록합니다 (제공된 경우) surfnet_registerIdl를 통해, RPC 클라이언트가 프로그램의 IDL 스키마를 사용하여 계정 데이터를 디코딩할 수 있게 합니다.

드문 경우: 실행 불가능한 program account

프로그램 바이트를 계정에 쓰되 실행 불가능하게 유지하려면, deploy 대신 SetAccount를 직접 사용하세요. deploy 경로는 항상 계정을 실행 가능으로 표시합니다.

오류

원인	증상
`.so` 파일이 없거나 읽을 수 없음	`SurfnetError::Cheatcode("...failed to read...")` 또는 JS 오류 발생
프로그램 ID가 keypair 파일과 일치하지 않음	`SurfnetError::Cheatcode("...mismatched program id...")`
IDL JSON 형식이 잘못됨	`SurfnetError::Cheatcode("...invalid IDL...")`
Surfnet이 오프라인 상태이고 program account가 이미 업스트림에 존재함	배포는 여전히 성공하며, 로컬 복사본이 업스트림 버전을 재정의합니다

목차