プログラムのデプロイ

SDKは、ローカルのビルド成果物から1回の呼び出しでプログラムをデプロイできます。2つの方式があります：標準的なパス構造を持つ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 は相互排他です — どちらか一方のみを指定してください。

登録される内容

デプロイが成功すると、ランタイムは次の3つの処理を行います：

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 がアップストリームに既に存在する	デプロイは成功するが、ローカルのコピーがアップストリームのバージョンを上書きする

目次