프로그램 배포하기

이 가이드는 다음 주제에 대한 지식을 전제로 합니다:

Loader-v3 및 Loader-v4

현재 loader-v3(program 서브커맨드)에서 loader-v4(program -v4 서브커맨드)로의 전환이 진행 중이며, loader-v3는 더 이상 사용되지 않을 예정입니다.

새로운 배포에는 solana program deploy 대신 solana program-v4 deploy를 사용하세요.

기존 프로그램을 마이그레이션하려면(본질적으로 재배포):

solana program migrate ./target/deploy/your_program-keypair.json

준비

먼저, 프로그램을 빌드해야 합니다(컴파일, 링크, 스트립).

cargo +solana build --target sbpf-solana-solana --release

이 단계는 모든 재배포/배포 전에 수행해야 합니다.

실행 파일의 크기에 비례하여 기본 지불 계정에 충분한 자금이 있는지 확인하세요:

du -h ./target/deploy/your_program.so
solana balance

또한, 각 프로그램에는 프로그램 계정과 프로그램 ID가 있으며, 이는 해당 프로그램 계정의 주소입니다. 다음은 프로그램 계정을 위한 keypair를 생성합니다:

solana-keygen new -o ./target/deploy/your_program-keypair.json

이 작업은 프로그램당 한 번만 수행해야 하며, 나중에 동일한 프로그램을 재배포할 때 재사용됩니다.

툴체인에는 단축 방법이 포함되어 있었지만, 이는 단계적으로 폐지/사용 중단되고 있습니다:

cargo-build-sbf

초기 배포

이제 실행 파일을 프로그램 계정에 업로드할 수 있습니다:

Loader-v3

매개변수는 keypair의 파일 경로를 예상하지만 program-id라고 불립니다:

solana program deploy ./target/deploy/your_program.so --program-id ./target/deploy/your_program-keypair.json

Loader-v4

solana program-v4 deploy ./target/deploy/your_program.so --program-keypair ./target/deploy/your_program-keypair.json

재배포

동일한 프로그램 계정에 다른 실행 파일을 다시 업로드하면 기존 파일을 덮어쓰거나 교체합니다. 그러나 재배포의 경우, 서명자가 업그레이드 권한 keypair이기 때문에 전체 keypair가 아닌 프로그램 ID(프로그램 keypair의 pubkey)만 필요합니다.

Loader-v3

이것은 초기 배포와 정확히 동일합니다:

solana program deploy ./target/deploy/your_program.so --program-id ./target/deploy/your_program-keypair.json

이전 실행 파일이 새 파일보다 짧은 경우 먼저 programdata 계정을 확장해야 할 수도 있습니다:

solana program extend ./target/deploy/your_program.so <ADDITIONAL_BYTES>

Loader-v4

초기 배포에서는 program-keypair를 사용했지만, 재배포에서는 program-id를 대신 사용합니다:

solana program-v4 deploy ./target/deploy/your_program.so --program-id ./target/deploy/your_program-keypair.json

업로드 우선순위 지정

네트워크 혼잡 시간 동안 프로그램 배포를 돕기 위해 사용할 수 있는 몇 가지 추가 플래그가 있습니다:

--with-compute-unit-price: 트랜잭션의 컴퓨팅 유닛 가격을 설정합니다. 컴퓨팅 유닛당 0.000001 lamport(마이크로 lamport) 단위로 증가합니다. 설정할 우선순위 수수료를 추정하려면 Helius의 우선순위 수수료 API를 사용하세요.
--use-rpc: 쓰기 트랜잭션을 validator TPU 대신 구성된 RPC로 보냅니다. 이 플래그는 Helius 또는 Triton과 같은 스테이크 가중치 RPC 연결이 필요합니다. 이 플래그는 다음을 사용하여 기본값으로 구성할 수도 있습니다: solana config set --url <RPC_URL>.
--max-sign-attempts: blockhash 만료 후 트랜잭션에 서명하거나 재서명하는 최대 시도 횟수입니다. 프로그램 배포 중에 보낸 트랜잭션이 처음 선택한 최근 blockhash가 만료된 후에도 확인되지 않은 경우, 해당 트랜잭션은 새로운 최근 blockhash로 재서명되어 다시 전송됩니다. 이 설정을 사용하여 트랜잭션 서명 반복의 최대 횟수를 조정하세요. 각 blockhash는 약 60초 동안 유효하므로, 기본값 5를 사용하면 모든 트랜잭션이 확인될 때까지 또는 최소 5분 동안 트랜잭션을 보내게 됩니다.

업로드 재개하기

업로드가 중단되거나 취소될 수 있습니다.

Loader-v3

프로그램 배포가 실패하면, 0이 아닌 잔액을 포함하는 중간 버퍼 계정이 남게 됩니다. 이 잔액을 회수하기 위해 동일한 중간 버퍼를 새로운 deploy 호출에 제공하여 실패한 배포를 재개할 수 있습니다.

배포 실패 시 생성된 중간 버퍼의 키페어를 복구하는 데 필요한 시드 구문을 지정하는 오류 메시지가 출력됩니다:

==================================================================================
Recover the intermediate account's ephemeral keypair file with
`solana-keygen recover` and the following 12-word seed phrase:
==================================================================================
valley flat great hockey share token excess clever benefit traffic avocado athlete
==================================================================================
To resume a deploy, pass the recovered keypair as
the [BUFFER_SIGNER] to `solana program deploy` or `solana program write-buffer'.
Or to recover the account's lamports, pass it as the
[BUFFER_ACCOUNT_ADDRESS] argument to `solana program drain`.
==================================================================================

키페어를 복구하려면:

solana-keygen recover -o ./target/deploy/buffer-keypair.json

요청 시 12단어 시드 구문을 입력하세요.

그런 다음 새로운 deploy 명령을 실행하고 버퍼를 지정하세요:

solana program deploy ./target/deploy/your_program.so --program-id ./target/deploy/your_program-keypair.json --buffer ./target/deploy/buffer-keypair.json

Loader-v4

지정된 바이트 오프셋에서 업로드를 재개할 수 있습니다:

solana program deploy ./target/deploy/your_program.so --program-id ./target/deploy/your_program-keypair.json --start-offset <BYTES_UPLOADED_SO_FAR>

완료

이것은 되돌릴 수 없는 작업입니다.

프로그램의 업그레이드 권한을 제거하여 변경 불가능하게 만들 수 있습니다.

Loader-v3

solana program set-upgrade-authority ./target/deploy/your_program-keypair.json --final

Loader-v4

solana program finalize --program-id ./target/deploy/your_program-keypair.json

프로그램을 덮어쓰는 대신, 완료된 프로그램의 연결 리스트를 구성하여 사용자에게 사용하고 싶은 프로그램 버전을 선택할 수 있는 옵션을 제공할 수도 있습니다:

solana program finalize --program-id ./target/deploy/your_program-keypair.json --next-version ../your_newer_program/target/deploy/your_newer_program-keypair.json

종료

loader-v3로 배포된 프로그램의 경우 programdata 계정, 버퍼 계정 및 해당 계정에 잠긴 자금만 회수할 수 있습니다. 프로그램 계정과 프로그램 ID, 그리고 특히 프로그램 계정에 잠긴 자금은 회수할 수 없습니다.

loader-v4로 배포된 프로그램은 프로그램 계정과 함께 종료될 수 있으며, 프로그램 ID와 잠긴 자금이 모두 다시 다른 용도로 사용 가능하게 됩니다.

Loader-v3

loader-v3를 사용하여 배포된 프로그램의 경우 이는 되돌릴 수 없는 작업입니다.

프로그램이 종료되면 해당 프로그램 ID를 재사용할 수 없습니다. 이전에 종료된 프로그램 ID로 프로그램을 배포하려고 하면 오류가 발생합니다. 프로그램을 종료한 후 다시 배포해야 하는 경우, 새로운 프로그램 keypair 파일을 생성해야 합니다.

단일 programdata 계정을 종료하려면:

solana program close ./target/deploy/your_program-keypair.json

현재 권한과 연결된 모든 버퍼 계정을 종료하려면:

solana program close --buffers

Loader-v4

solana program-v4 close --program-id ./target/deploy/your_program-keypair.json

메타데이터 검사

show 하위 명령은 프로그램의 메타데이터를 나열합니다.

출력 예시는 다음과 같습니다:

Program Id: 3KS2k14CmtnuVv2fvYcvdrNgC94Y11WETBpMUGgXyWZL
Owner: BPFLoaderUpgradeab1e11111111111111111111111
ProgramData Address: EHsACWBhgmw8iq5dmUZzTA1esRqcTognhKNHUkPi4q4g
Authority: FwoGJNUaJN2zfVEex9BB11Dqb3NJKy3e9oY3KTh9XzCU
Last Deployed In Slot: 63890568
Data Length: 5216 (0x1460) bytes

Program Id는 프로그램을 호출할 때 명령어의 program_id 필드에서 참조할 수 있는 주소입니다.
Owner: 이 프로그램이 배포된 로더입니다.
ProgramData Address는 프로그램의 실행 파일을 보유하는 프로그램 계정과 연결된 programdata 계정입니다(loader-v3만 해당).
Status: retracted, deployed 또는 finalized(loader-v4만 해당).
Authority는 프로그램의 업그레이드 권한입니다.
Last Deployed In Slot는 프로그램이 마지막으로 배포된 slot입니다.
Data Length는 배포를 위해 예약된 공간의 크기입니다. 현재 배포된 프로그램이 실제로 사용하는 공간은 이보다 적을 수 있습니다.

Loader-v3

특정 프로그램을 보려면:

solana program show ./target/deploy/your_program-keypair.json

기본 권한으로 배포된 프로그램 목록을 보려면:

solana program show --programs

권한에 관계없이 모든 버퍼 계정을 표시하려면:

solana program show --buffers --all

다른 권한을 지정하려면:

solana program show --programs --buffer-authority ~/.config/solana/authority-keypair.json
solana program show --buffers --buffer-authority ~/.config/solana/authority-keypair.json

Loader-v4

특정 프로그램을 보려면:

solana program-v4 show --program-id ./target/deploy/your_program-keypair.json

기본 권한으로 배포된 프로그램 목록을 보려면:

solana program-v4 show --all

특정 권한으로 배포된 프로그램 목록을 보려면:

solana program-v4 show --authority ~/.config/solana/authority-keypair.json

실행 파일 다운로드

때로는 프로그램을 다운로드하여 비교함으로써 알려진 실행 파일이 포함되어 있는지 확인하는 것이 유용합니다. 다운로드한 파일은 잘라내고, 해시하여 원본 프로그램 파일의 해시와 비교할 수 있습니다.

Loader-v3

solana program dump ./target/deploy/your_program-keypair.json ./target/deploy/your_program.so

Loader-v4

solana program download ./target/deploy/your_program.so --program-id ./target/deploy/your_program-keypair.json

고급: 권한 이전

특정 프로그램을 변경할 수 있는 권리는 해당 프로그램의 권한을 가진 주체에게 있습니다. 이 권한은 프로그램 keypair를 변경하지 않고 다른 keypair로 이전할 수 있어, 프로그램 ID는 동일하게 유지됩니다. 또한, 하나의 권한으로 여러 프로그램 계정을 제어할 수 있습니다.

초기 배포 시 명시적으로 지정하지 않으면 기본 keypair가 권한으로 사용됩니다. 이것이 위의 단계에서 프로그램을 재배포할 때 권한을 명시적으로 지정할 필요가 없었던 이유입니다.

명시적 권한은 오프라인 서명 및 다중 엔티티가 관리하는 프로그램에 유용합니다.

먼저, 권한을 위한 keypair를 생성해야 합니다:

solana-keygen new -o ~/.config/solana/authority-keypair.json

Loader-v3

배포 중에 권한을 지정할 수 있습니다:

solana program deploy ./target/deploy/your_program.so --upgrade-authority ~/.config/solana/authority-keypair.json

또는 배포 후 기본 keypair를 현재 권한으로 사용할 수 있습니다:

solana program set-upgrade-authority ./target/deploy/your_program-keypair.json --new-upgrade-authority ~/.config/solana/authority-keypair.json

또는 배포 후 현재 권한을 지정하는 방법:

solana program set-upgrade-authority ./target/deploy/your_program-keypair.json --upgrade-authority ~/.config/solana/authority-keypair.json --new-upgrade-authority ~/.config/solana/new_authority-keypair.json

Loader-v4

배포 중에 권한을 지정할 수 있습니다:

solana program-v4 deploy ./target/deploy/your_program.so --program-keypair ./target/deploy/your_program-keypair.json --authority ~/.config/solana/authority-keypair.json

또는 배포 후 기본 keypair를 현재 권한으로 사용하는 방법:

solana program-v4 transfer-authority --program-id ./target/deploy/your_program-keypair.json --new-authority ~/.config/solana/authority-keypair.json

또는 배포 후 현재 권한을 지정하는 방법:

solana program-v4 transfer-authority --program-id ./target/deploy/your_program-keypair.json --authority ~/.config/solana/authority-keypair.json --new-authority ~/.config/solana/new_authority-keypair.json

고급: 버퍼를 사용한 2단계 재배포

실행 파일을 프로그램 계정에 직접 업로드하는 대신, 먼저 스테이징 버퍼 계정에 업로드한 다음 두 번째 단계(실제 재배포/배포)에서 프로그램 계정으로 전송할 수 있습니다. 이는 오프라인 서명 및 DAO 투표와 같이 실제 재배포 전에 업로드된 실행 파일을 선택하거나 거부할 수 있는 다중 엔티티 관리 프로그램에 유용합니다.

버퍼 계정을 사용하면 두 계정이 동시에 각각 하나의 실행 파일을 보유하기 때문에 업로드 과정에서 필요한 자금이 대략 두 배가 된다는 점을 염두에 두세요.

먼저, 버퍼 계정을 위한 keypair를 생성해야 합니다:

solana-keygen new -o ~/.config/solana/buffer-keypair.json

버퍼 계정은 다양한 업로드에 재사용할 수 있으며 특정 프로그램 계정에 종속되지 않습니다.

Loader-v3

solana program write-buffer ./target/deploy/your_program.so --buffer ~/.config/solana/buffer-keypair.json
solana program deploy --program-id ./target/deploy/your_program-keypair.json --buffer ~/.config/solana/buffer-keypair.json

Loader-v4

solana program-v4 deploy ./target/deploy/your_program.so --buffer ~/.config/solana/buffer-keypair.json
solana program-v4 deploy --program-id ./target/deploy/your_program-keypair.json --buffer ~/.config/solana/buffer-keypair.json

고급: 오프라인 서명

일부 보안 모델에서는 서명 키가 네트워크에서 완전히 분리될 수 있도록 서명 프로세스와 트랜잭션 브로드캐스트를 분리해야 합니다. 이를 오프라인 서명이라고도 합니다.

재배포만 오프라인 모드에서 수행할 수 있다는 점에 유의하세요. 초기 프로그램 배포는 반드시 온라인 기기에서 수행해야 하며, 이후 프로그램 재배포만 오프라인 서명을 활용할 수 있습니다.

일반적인 설정은 두 가지 다른 서명자로 구성됩니다:

온라인 서명자(수수료 지불자 및 버퍼 계정의 권한자)
오프라인 서명자(프로그램 계정의 권한자)

일반적인 프로세스는 몇 가지 추가 단계가 있는 2단계 재배포입니다:

(온라인) 새 프로그램 생성
(온라인) 오프라인 서명자에게 권한 이전
(온라인) 버퍼를 생성하고 실행 파일 업로드
(선택 사항) 버퍼의 온체인 내용 확인
(오프라인) 버퍼를 사용하여 프로그램을 재배포하는 트랜잭션에 서명 --blockhash <VALUE> --sign-only
(온라인) 이 서명을 사용하여 재배포 트랜잭션 브로드캐스트 --blockhash <VALUE> --signer <OFFLINE_SIGNER_PUBKEY>:<OFFLINE_SIGNER_SIGNATURE>

최근 blockhash를 찾아 붙여넣어 오프라인 트랜잭션 서명을 생성하세요. blockhash는 약 60초 후에 만료됩니다. 시간 내에 완료하지 못했다면 - 새로운 해시를 얻어 성공할 때까지 반복하거나, 지속 가능한 트랜잭션 nonce 사용을 고려하세요.

목차