프로그램 배포하기

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

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 account를 확장해야 할 수도 있습니다:

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 호출에 제공하여 실패한 배포를 재개할 수 있습니다.

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

==================================================================================
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`.
==================================================================================

keypair를 복구하려면:

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

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

그런 다음 새로운 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 account, 버퍼 계정 및 해당 계정에 잠긴 자금만 회수할 수 있습니다. 프로그램 계정과 프로그램 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는 동일하게 유지됩니다. 또한, 하나의 권한으로 여러 program account를 제어할 수 있습니다.

초기 배포 시 명시적으로 지정하지 않으면 기본 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단계 재배포

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

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

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

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

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

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

고급: 오프라인 서명

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

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

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

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

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

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

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

목차