이 가이드에서는 Universal Ledger 클라이언트 구현이 네트워크와 안전하고 안정적으로 상호작용하도록 보장하기 위한 권장사항을 제공합니다. 학습 내용:
- 고가용성을 위해 네트워크 토폴로지를 활용합니다.
- 트랜잭션을 제출하고 실행 결과를 이해합니다.
- 폴링, 제한 시간, 재시도 전략을 구현합니다.
네트워크 토폴로지 및 고가용성
Universal Ledger 네트워크는 여러 영역과 리전에 분산된 여러 검증자로 구성되므로 전체 네트워크의 고가용성을 보장합니다.
영역 장애: 클라우드 영역 내에서 단일 검증자가 실패하면 동일한 리전 내의 다른 검증자가 요청 처리를 원활하게 계속합니다.
리전 서비스 중단: 전체 리전을 사용할 수 없게 되더라도 다른 리전의 검증자는 계속 작동합니다. 트랜잭션을 계속 제출하려면 클라이언트가 대체하고 다른 엔드포인트를 통해 트랜잭션을 다시 제출하는 것이 안전합니다.
트랜잭션 실행 특성
원자적 실행: 트랜잭션이 완전히 성공하거나 완전히 실패합니다. 잔액 부족으로 인해 요청된 금액의 일부만 이체하는 것과 같은 부분 트랜잭션 실행은 발생하지 않습니다. 여기에는 트랜잭션 체인이 포함되어, 여러 임의 트랜잭션을 단일 원자적 시퀀스로 결합할 수 있습니다.
자동 재시도 없음: 네트워크는 제출된 트랜잭션을 정확히 한 번 실행하려고 시도합니다. 실행에 실패하면 원장이 트랜잭션을 자동으로 대기열에 추가하거나 재시도하지 않습니다.
멱등성 재제출: 제출된 모든 트랜잭션은 시퀀스 번호와 발신자를 포함한 정확한 직렬화된 페이로드를 기반으로 고유한 트랜잭션 ID를 생성합니다. 정확히 동일한 페이로드를 여러 번 제출하면 동일한 트랜잭션 ID가 생성됩니다. 원장은 트랜잭션이 최대 한 번 실행되도록 보장하므로 엔드포인트 중 하나를 사용할 수 없는 경우 동일한 트랜잭션 페이로드를 다른 엔드포인트에 다시 제출해도 안전합니다.
자세한 내용은
SubmitTransactionRequest참조 페이지를 확인하세요.
지연 시간, 폴링, 재시도 전략
트랜잭션을 제출하면 검증자가 먼저 서명과 시퀀스 번호가 유효한지 확인하는 빠른 검사를 실행합니다. 성공하면
Universal Ledger API가 할당된 트랜잭션 ID를 포함한
SubmitTransactionResponse
로 즉시 응답합니다.
대부분의 트랜잭션은 3초 이내에 완료됩니다. 트랜잭션
상태를 확인하려면 제공된 트랜잭션 ID를 사용하여
QueryTransactionState
메서드를 폴링합니다.
트랜잭션 상태가 여전히
PENDING이면 지수 백오프 전략을 사용하여 상태를 다시 가져옵니다. 예를 들어 3초, 9초, 27초, 60초 간격으로 쿼리합니다.QueryTransactionState가NOT_FOUND를 반환하면 트랜잭션을 다시 제출합니다.
트랜잭션 시도가 FINALIZED되면 응답에 다음과 같은 다양한
세부정보가 포함된
TransactionCertificate도 포함됩니다.
- 트랜잭션이 완료된 라운드 ID입니다.
- 실행 상태 (OK 또는 실패)입니다.
- 트랜잭션 출력을 포함한 트랜잭션 이벤트입니다.
제한 시간 프로토콜
트랜잭션이 60초 후에도 PENDING 또는 NOT_FOUND 상태로 유지되는 드문 경우 요청을 처리하는 검증자가 네트워크의 다른 검증자를 따라잡지 못하는 것으로 가정합니다. 다음 단계를 완료하세요.
- 다른 네트워크 리전에서 다른 엔드포인트를 선택합니다.
- 정확히 동일한 서명된 트랜잭션 페이로드를 다시 제출합니다.
- Universal Ledger팀에서 조사할 수 있도록 gcul-help@google.com으로 이메일을 보내 문제를 보고합니다.
트랜잭션 상태를 확인할 때 동일한 페이로드를 여러 번 제출한 경우 응답에 여러
TransactionAttempt 메시지가 포함될 수 있습니다. 최대 하나의 시도가 OK 트랜잭션 상태로 완료되는 반면
TransactionEffects 다른 시도는 보류 중이거나 실패 상태입니다. 이는 예상되는 동작입니다. 원장이 트랜잭션 제출 중 하나를 성공적으로 실행하고 중복된 재제출을 올바르게 거부했거나 결국 거부합니다.
네트워크 일관성
완료된 트랜잭션: 한 검증자가 트랜잭션이 완료되었다고 보고하면 동일한 네트워크의 다른 모든 검증자가 결국 트랜잭션을 처리하고 정확히 동일한 결과를 재현할 것으로 예상됩니다. 트랜잭션이 완료된 라운드 ID를 사용하여
QueryAccountRequest제출하면TransactionCertificate에서 찾을 수 있으므로 모든 동기화된 검증자에서 동일한 결과가 생성됩니다.완료되지 않은 트랜잭션: 트랜잭션은 네트워크 전체에 비동기식으로 전파되므로 트랜잭션이 완료된 것으로 보고되는지 여부는 검증자마다 다를 수 있습니다.
서비스 중단에서 복구 중이거나 동기화 지연이 발생하는 검증자는 완료된 트랜잭션을
PENDING또는NOT_FOUND로 일시적으로 보고할 수 있습니다. 검증자가 따라잡으면 트랜잭션 상태가 해결됩니다.
클라이언트 책임 및 오류 처리
트랜잭션 추적: 클라이언트 애플리케이션은 제출된 모든 트랜잭션이 완료될 때까지 상태를 추적해야 합니다.
오류 처리: 트랜잭션이 실패하면 실패 세부정보를 가져와 검사하여
TransactionCertificate적절한 비즈니스 수준 수정을 트리거합니다.
다음 단계
- Universal Ledger API에 RPC 요청을 보내는 방법을 알아봅니다.
- Universal Ledger API 참조를 확인합니다.