solana-program-upgrade
라이브 Solana 프로그램을 업그레이드하고 온체인 계정 데이터를 안전하게 마이그레이션합니다 -
버전 관리, 지연 realloc 마이그레이션, 포크 시뮬레이션, 업그레이드 권한 위생 처리,
및 롤백. Solana 개발에서 가장 치명적인 라이프사이클 단계를 생존 가능하게 만듭니다.
solana-dev-skill의 애드온 해당 스킬이 그린필드 Anchor/Pinocchio/테스트 기본을 담당합니다. 이 스킬은 오직 업그레이드 + 마이그레이션 라이프사이클만 담당합니다 - 프로그램이 이미 배포되어 있고 변경이 필요할 때 사용하세요.
황금 규칙 (안전 중추)
- 버전 태그 + 마이그레이션 경로 없이 라이브 계정 레이아웃을 절대 변경하지 마십시오.
이전 계정은 원시 바이트이며, 변경된 구조체로 읽는 새 코드는
AccountDidNotDeserialize또는 조용한 데이터 손상을 초래합니다. 8바이트 판별자는 유형을 제한하며, 버전이 아닙니다. - 메인넷 전에 실제 클론된 메인넷 상태에 대해 시뮬레이션하십시오. 항상 정확한 업그레이드 + 마이그레이션을 포크에서 먼저 실행하고 계정 바이트를 비교하세요. 예외는 없습니다.
- 업그레이드 권한을 멀티시그로 설정하십시오. 모든 프로그램 로직을 교체할 수 있는 단일 핫 키는 러그/침해 벡터입니다. Squads v4로 이동하세요.
- 온체인 데이터 마이그레이션은 일반적으로 순방향 전용입니다. 추가 가능하고 재개 가능하게 설계하십시오. 데이터를 되돌릴 수 있다고 가정하지 마십시오.
- 이전
.so를 보관하십시오. 데이터를 되돌릴 수 없는 경우에도 코드를 빠르게 롤백할 수 있습니다. - 기본값은 devnet/localnet/포크입니다. 어떤 예제에서도 메인넷 자동 타겟팅을 피하십시오.
업그레이드 워크플로
순서대로 따르세요. 각 단계는 심층 내용을 위한 특정 파일로 연결됩니다.
- 스키마 차이점 확인 - 이전
#[account]구조체와 새 구조체 비교. 추가적 변경과 파괴적 변경(순서 변경/제거/타입 변경 = 파괴적)을 식별합니다. - 전략 선택 - 즉시 크랭크 대 지연 터치 시 마이그레이션 대 새 계정 복사 ->
migration-strategies.md. - 버전 관리 구조체 작성 - 버전 태그 추가, 저장된 버전 분기 처리 ->
account-versioning.md. - 마이그레이션 구현 - 수동
realloc(이식 가능한 기준선) ->realloc-migration.md; 또는 AnchorMigration유형 (해당 버전에 있다면) ->anchor-migration-type.md. - 포크에서 시뮬레이션 - 실제 계정 클론, 업그레이드 실행, 바이트 비교, 멱등성 확인 ->
fork-simulation.md. - 권한 보안 - 메인넷 건드리기 전에 Squads 멀티시그로 확인/이동 ->
upgrade-authority.md. - 바이너리 배포 - 버퍼 흐름, 더 큰 경우
extend, IDL,--final->program-deploy-upgrade.md. - 검증 및 롤백 계획 유지 - 계정 역직렬화 확인, 이전
.so및 반쪽 마이그레이션 복구 경로 유지 ->rollback-recovery.md.
라우팅 테이블
상황에 맞는 행을 찾아 해당 파일을 읽으세요.
| 증상 / 작업 | 읽을 파일 |
|---|---|
AccountDidNotDeserialize / 크기 불일치 / 업그레이드 후 잘못된 값 | account-versioning.md, 그다음 realloc-migration.md |
#[account] 구조체의 필드 추가/제거/순서 변경/타입 변경 | account-versioning.md |
| "나중에 변경할 수 있도록 계정에 버전을 어떻게 추가하나요?" | account-versioning.md |
| 기존 계정을 제자리에서 확장/축소해야 함 | realloc-migration.md |
| 지연 "터치 시 마이그레이션" 대 즉시 일회성 마이그레이션 | realloc-migration.md, migration-strategies.md |
realloc::zero 오래된 바이트 문제 / 렌트 충전 방향 | realloc-migration.md |
| 명령어당 10KB 재할당 증가 한도, 큰 증가 | realloc-migration.md |
새 Anchor Migration<'info, From, To> 유형 사용 | anchor-migration-type.md |
AccountAlreadyMigrated / AccountNotMigrated 오류 | anchor-migration-type.md |
| 즉시 vs 지연 vs 새 계정 복사 선택 | migration-strategies.md |
| 대규모 계정 집합(예: 수만 개)을 저렴하게 마이그레이션 | migration-strategies.md |
| 배치/크랭크/키퍼 마이그레이션, 페이지네이션, 진행 추적 | migration-strategies.md |
| 제자리 재할당 불가능(과거 데이터 축소, 유형 변경) | migration-strategies.md |
| 프로그램 바이너리 재배포/업그레이드 | program-deploy-upgrade.md |
solana program write-buffer / deploy --buffer 흐름 | program-deploy-upgrade.md |
새 .so가 배포된 것보다 큼 (solana program extend) | program-deploy-upgrade.md |
IDL 업그레이드 (anchor idl upgrade) | program-deploy-upgrade.md |
| 제자리 배포 vs 새 프로그램 ID (PDA/계정에 미치는 영향) | program-deploy-upgrade.md |
| 프로그램을 누가 제어하는가? 단일 키 vs 멀티시그 | upgrade-authority.md |
| 업그레이드 권한을 Squads v4 멀티시그로 이동 | upgrade-authority.md |
set-upgrade-authority, 타임락, 키 관리 | upgrade-authority.md |
프로그램을 불변으로 만들기 (--final) 및 비용 | upgrade-authority.md |
| 메인넷 전 업그레이드 테스트 / 실제 상태 클론 | fork-simulation.md |
| Surfpool 메인넷 포크; 사전/사후 계정 바이트 비교 | fork-simulation.md |
| LiteSVM / Mollusk 단위 테스트로 마이그레이션 명령어 테스트 | fork-simulation.md |
| 마이그레이션의 멱등성 증명 (두 번 실행 = no-op) | fork-simulation.md |
| 업그레이드 실패 - 빠르게 이전 코드 복원 | rollback-recovery.md |
| 반쪽 마이그레이션된 계정 집합, 안전하게 재개 | rollback-recovery.md |
| 일시 중지 / 마이그레이션 가드 / 비상 기능 플래그 | rollback-recovery.md |
| 네이티브 / Pinocchio 프로그램 (Anchor 없음) | realloc-migration.md, account-versioning.md |
| 권위 있는 링크 및 문서 (현재 확인) | resources.md |
동반 도구
- 명령어:
/plan-upgrade(스키마 비교 -> 마이그레이션 계획 + 위험 보고서),/simulate-upgrade(포크, 클론, 실행, 비교),/check-upgrade-authority(단일 키 vs 멀티시그 감사). - 에이전트:
program-migration-architect(스키마 차이로 마이그레이션 설계),migration-qa-engineer(포크/LiteSVM 테스트 작성, 손상 여부 확인). - 규칙:
account-layout-guard는#[account]구조체 /state.rs편집 시 자동 실행되며 버전 범프 및 마이그레이션 경로를 요구합니다.
정확성 계약
라우팅된 파일의 모든 CLI 플래그, Anchor 제약 조건, 크레이트, 계정 유형은 실제이고 검증 가능해야 합니다.
확실하지 않은 경우 설치된 버전(anchor --version, solana --version, Anchor 변경 로그)에 대해 확인하세요 -
절대 발명하지 마십시오. Migration 유형을 아직 출시되지 않았을 수 있는 것으로 취급하십시오. 수동 realloc
패턴이 이식 가능한 기본값입니다.