프로덕션 모범 사례

Keychain은 서명 백엔드를 추상화하지만, 프로덕션 환경에서 서명자를 운영하는 것은 여전히 사용자의 책임입니다. 이 모범 사례는 모든 백엔드에 적용됩니다. 백엔드 선택에 대해서는 백엔드 선택하기를 참조하세요.

핫 서명자와 콜드 서명자 분리

잔액이 낮은 운영용("핫") 서명자는 빈번한 자동화 트랜잭션에 사용하고, 별도의 고가치("콜드") 서명자는 자산 이동에 사용하세요. 콜드 서명자는 MPC 커스터디 또는 클라우드 HSM으로 뒷받침하고, 서명 전에 승인 정책을 요구하도록 설정하세요. 인터페이스가 동일하기 때문에 각 역할은 호출 지점을 변경하지 않고도 서로 다른 백엔드를 사용할 수 있습니다.

계획적인 키 순환

Solana에서 서명 키는 곧 계정 주소이므로, 키를 순환하면 새로운 주소가 생성됩니다. 순환은 마이그레이션으로 계획하세요: 새 키를 프로비저닝하고, 관련 권한을 재할당하거나 자금을 새 주소로 이전한 후 기존 키를 폐기하세요. 환경별로 구별된 키를 사용하여 devnet 키가 mainnet에서 재사용되지 않도록 하세요.

각 백엔드의 자격 증명 범위는 서명에 필요한 최소한으로 제한하세요. AWS KMS의 경우 특정 키에 대한 kms:Sign, kms:DescribeKey, kms:GetPublicKey 권한이 이에 해당하며 (가용성 확인에는 마지막 두 가지가 사용됩니다), 정적 자격 증명보다는 IAM 역할을 사용하는 것이 좋습니다. Vault 정책과 관리형 지갑 API 키에도 동일한 원칙을 적용하세요.

가용성 계획

원격 백엔드는 네트워크 서비스에 의존합니다. 서명자를 사용하기 전에 가용성을 확인하고 (TypeScript에서는 isAvailable(), Rust와 Python에서는 is_available(), Go에서는 IsAvailable(ctx)), 서명만 수행하는 요청이 실패하면 백오프를 적용해 재시도하며, 장애 발생 시 사용할 대체 경로를 정의하세요. 브로드캐스트를 수행하는 백엔드 (Crossmint, Fordefi 네이티브 자동 모드)는 무작정 재시도하지 마세요. 자세한 내용은 확인되지 않은 브로드캐스트 처리를 참고하세요. Keychain은 구성된 기본 URL에 HTTPS를 강제하고, 리디렉션을 거부하며, 기본 요청 타임아웃을 적용합니다.

확인되지 않은 브로드캐스트 처리

Crossmint와 Fordefi 네이티브 자동 모드는 서버 측에서 서명과 브로드캐스트를 모두 수행하므로, 호출이 실패했다고 해서 아무것도 반영되지 않았다는 뜻은 아닙니다. 공급자가 트랜잭션을 수락했을 수 있는 경우 Keychain은 BROADCAST_UNCONFIRMED(Rust에서는 SignerError::BroadcastUnconfirmed)를 반환합니다. 이 오류에는 생성 요청이 수락된 경우 공급자의 트랜잭션 ID가 포함되며, 메시지에서 파생되어 생성 요청에 사용된 멱등성 키(idempotency key)는 항상 포함됩니다.

다른 작업을 하기 전에 먼저 트랜잭션 ID로 공급자와 상태를 대조하세요.
바이트 단위로 동일한 트랜잭션을 다시 전송하는 것은 안전합니다. 멱등성 키가 중복 처리를 방지합니다.
트랜잭션을 다시 구성하면(예: 새 블록해시 사용) 새로운 키가 생성되므로 새로운 전송이 발생합니다.

시크릿 및 전송 보호

원격 백엔드는 구성된 기본 URL에 HTTPS를 강제하고 리디렉션을 거부합니다. 유일한 예외는 Vault로, 로컬의 vault server -dev가 동작하도록 루프백에서는 일반 HTTP를 허용합니다.
API 키, 토큰, 자격 증명은 시크릿 매니저 또는 환경 변수를 통해 제공하세요. 하드코딩하거나 소스 컨트롤에 커밋해서는 안 됩니다.
Keychain은 오류 응답을 정제하여 시크릿이 로그에 노출되는 것을 방지합니다. 자체 로깅에서도 원시 자격 증명과 키 자료가 포함되지 않도록 하세요.

서명 모니터링 및 감사

서명 성공률, 지연 시간, 실패 횟수를 추적하고 급격한 변화 시 알림을 설정하세요 — 프로덕션 준비 상태의 메트릭을 참조하세요. 공급자 측 감사 로그(KMS, Vault 또는 커스터디언)를 활성화하고, 애플리케이션이 제출하는 트랜잭션과 대조하여 검증하세요.

Keychain이 검사하는 항목 알아보기

Keychain은 사용자의 트랜잭션이 아니라 서명 구간(signing hop)을 검증합니다. 시뮬레이션, 트랜잭션 내용 검사, 정책 엔진은 제공되지 않습니다. 이러한 기능은 애플리케이션이나 공급자의 정책 제어에서 적용하세요.
Fordefi 네이티브 수동 모드는 서명하기 전에 트랜잭션(블록해시, Compute Budget 수수료 명령)을 다시 작성합니다. 제출한 트랜잭션이 아니라 반환된 트랜잭션을 기준으로 이어서 진행하고, 다른 어떤 서명자보다 먼저 실행하세요.
Rust는 중간 키 버퍼를 제로화(zeroize)하지만, Python과 Go는 그렇지 않습니다. 이러한 언어에서 Memory 백엔드를 사용할 때는 프로세스 전체 메모리를 민감한 정보로 취급하세요.
Ledger에서는 기기 화면만이 서명 대상에 대한 신뢰할 수 있는 유일한 설명입니다. 프로덕션 환경에서는 unsafe-debug 기능을 활성화하거나 solana_remote_wallet에 대해 TRACE 로깅을 사용하지 마세요. 두 가지 모두 기기 및 트랜잭션 세부 정보를 로그에 기록합니다.

전체적인 내용은 보안 모델을 참고하세요.