기술적 범위 및 주의사항 본문은 Babbage 및 Conway 계열의 트랜잭션 구조를 중심으로 설명합니다. 실제 구현 시에는 사용하는 Ledger Era, SDK 버전, Provider API 및 Protocol Parameters를 확인해야 합니다. 본문에 제시한 코드는 Mesh SDK의 기본 트랜잭션 구성 흐름을 설명하는 예제이며, Plutus 스마트 컨트랙트의 실제 Mainnet 실행이나 네트워크 검증을 수행한 결과가 아닙니다.
0 들어가며: 스마트 컨트랙트는 어떻게 블록체인에 도달하는가?
Cardano에서 Plutus 스마트 컨트랙트를 실행하려면 스크립트만 작성해서는 충분하지 않습니다. 스크립트를 호출할 Datum과 Redeemer를 준비하고, 필요한 UTxO를 선택하며, 실행 예산(Execution Units)을 반영하고, 수수료와 Collateral을 계산한 뒤, 트랜잭션을 서명하고 네트워크에 제출해야 합니다.
이 과정을 담당하는 것이 오프체인(Off-chain) 트랜잭션 구성 코드입니다.
오프체인 코드는 트랜잭션을 구성하고 검증에 필요한 자료를 준비합니다. 반면 온체인(On-chain)의 Ledger와 Plutus 스크립트는 제출된 트랜잭션이 합의 규칙과 스크립트 조건을 충족하는지 판단합니다.
이 글에서는 다음 흐름을 중심으로 살펴봅니다.
단, 이 순서는 이해를 위한 개념적 흐름입니다. 실제 SDK에서는 Evaluation과 Balance, Fee 계산이 여러 차례 반복되거나 Builder 내부에 통합될 수 있습니다.
1 Off-chain과 On-chain의 역할 구분
Cardano의 eUTxO 모델에서는 트랜잭션이 기존 UTxO를 소비하고 새로운 UTxO를 생성합니다.
스마트 컨트랙트와 상호작용할 때 각 계층의 역할은 다음과 같습니다.
| 구분 | 주요 역할 |
|---|---|
| Off-chain | UTxO 조회, 트랜잭션 구성, Datum·Redeemer 준비, 서명 요청, 제출 |
| Transaction Builder | 입력·출력 구성, 수수료 및 잔액 조정, 직렬화 |
| Provider / Node API | 체인 데이터 조회, 스크립트 평가 지원, 트랜잭션 제출 |
| On-chain Ledger | 트랜잭션 구조, 입력, 서명, 수수료, 유효성 및 스크립트 검증 |
| Plutus Script | 전달된 실행 문맥과 Redeemer 등을 바탕으로 조건 평가 |
여기서 주의할 점이 있습니다.
Off-chain 코드가 스크립트를 미리 평가할 수 있다고 해서 온체인 검증을 대신하는 것은 아닙니다. SDK나 Provider가 제공하는 Script Evaluation은 제출 전 실행 예산과 스크립트 결과를 확인하는 데 도움을 주는 절차입니다. 최종적인 유효성 판단은 Ledger 규칙에 따릅니다.
2 Cardano Transaction의 기본 구성
일반적인 Cardano 트랜잭션에는 다음 요소들이 포함됩니다.
- Inputs: 소비할 기존 UTxO의 참조
- Outputs: 새롭게 생성할 UTxO
- Fee: 트랜잭션 처리에 필요한 수수료
- Validity Interval: 트랜잭션이 유효한 시간 범위
- Mint: Native Asset의 발행 또는 소각 정보
- Certificates / Withdrawals: 스테이킹 및 관련 등록·출금 정보
- Collateral: Plutus 스크립트 검증 실패에 대비한 담보 입력
- Reference Inputs: 소비하지 않고 참조하는 UTxO
- Script Data Hash: 스크립트 평가에 영향을 주는 데이터의 무결성 해시
모든 트랜잭션이 위 필드를 전부 사용하는 것은 아닙니다. 사용 여부와 직렬화 형태는 트랜잭션 유형과 Ledger Era에 따라 달라집니다.
2.1 Transaction Body의 정수 키
Conway Era CDDL에서 Transaction Body는 정수 키를 사용하는 CBOR Map으로 정의됩니다.
대표적인 필드는 다음과 같습니다.
| CBOR 키 | 필드 | 의미 |
|---|---|---|
| 0 | inputs | 소비할 UTxO 집합 |
| 1 | outputs | 생성할 출력 목록 |
| 2 | fee | 수수료 |
| 3 | ttl | 유효 종료 슬롯 |
| 4 | certificates | 인증서 |
| 5 | withdrawals | 보상 출금 |
| 7 | auxiliary_data_hash | 보조 데이터 해시 |
| 8 | validity_interval_start | 유효 시작 슬롯 |
| 9 | mint | Native Asset 발행·소각 |
| 11 | script_data_hash | 스크립트 데이터 무결성 해시 |
| 13 | collateral | 담보 입력 |
| 14 | required_signers | 요구 서명자 |
| 15 | network_id | 네트워크 식별자 |
| 16 | collateral_return | Collateral 반환 출력 |
| 17 | total_collateral | 총 Collateral 금액 |
| 18 | reference_inputs | 참조 입력 |
| 19 | voting_procedures | 거버넌스 투표 |
| 20 | proposal_procedures | 거버넌스 제안 |
| 21 | current_treasury_value | 현재 Treasury 값 |
| 22 | donation | Treasury 기부 |
위 표는 Conway CDDL의 필드 번호를 기준으로 정리한 것입니다. 모든 필드가 필수는 아니며, 일부 필드는 특정 기능이나 Era에서만 사용됩니다.
또한 CBOR Map은 사람이 읽기 쉬운 JSON 객체와 다릅니다. 숫자 키와 값이 CBOR 규칙에 따라 직렬화되며, 실제 바이트 표현은 인코딩 방식과 자료 구조에 영향을 받습니다.
3 Babbage·Conway Era의 최상위 Transaction 구조
Conway CDDL에서 일반적인 Transaction은 다음 네 요소로 표현됩니다.
transaction = [
transaction_body,
transaction_witness_set,
bool,
auxiliary_data / null
]
각 요소의 의미는 다음과 같습니다.
| 위치 | 요소 | 설명 |
|---|---|---|
| 0 | Transaction Body | 입력, 출력, 수수료, 유효 기간 등의 핵심 정보 |
| 1 | Transaction Witness Set | 서명, 스크립트, Datum, Redeemer 등의 증거 자료 |
| 2 | bool | is_valid: Phase-2 스크립트 유효성 표시 |
| 3 | auxiliary_data / null | 메타데이터 등 보조 데이터 |
여기서 세 번째 요소인 bool은 단순히 사용자가 트랜잭션을 승인했는지 여부를 나타내는 값이 아닙니다. Alonzo 이후의 Plutus 트랜잭션에서 스크립트 유효성 상태를 표현하는 Ledger 필드입니다.
네 요소 구조는 Babbage 및 Conway 계열 트랜잭션을 이해하는 데 유용하지만, 모든 Cardano Era의 모든 직렬화 형식을 하나의 구조로 일반화해서는 안 됩니다. 실제 구현에서는 해당 Era의 CDDL과 Ledger 규칙을 확인해야 합니다.
4 Transaction ID와 VKey Witness의 관계
Transaction ID(TxId)는 트랜잭션 전체 CBOR 바이트를 단순히 해싱한 값이 아닙니다.
핵심은 Transaction Body의 CBOR 직렬화 바이트입니다.
개념적으로 다음과 같이 표현할 수 있습니다.
즉, Transaction Body가 동일하다면 Witness Set에 서명이 추가되거나 다른 Witness가 결합되더라도 TxId는 바뀌지 않습니다.
4.1 서명은 무엇을 대상으로 하는가?
일반적인 VKey Witness는 다음 요소로 구성됩니다.
- 공개키(VKey)
- 서명(Signature)
서명자는 Transaction Body의 해시를 기준으로 서명합니다. 따라서 서명 검증은 해당 공개키가 Transaction Body 해시에 대한 유효한 서명을 생성했는지 확인하는 과정입니다.
Transaction Body
│
▼
CBOR Serialization
│
▼
Blake2b-256
│
▼
Transaction ID
│
▼
Private Key Signature
│
▼
VKey Witness
4.2 서명 후 Transaction Body를 변경하면?
서명이 끝난 후 Transaction Body의 필드가 바뀌면 새로운 Body 해시가 만들어집니다.
예를 들어 다음 항목을 변경하면 기존 서명은 새로운 Body에 대한 유효한 서명이 아닙니다.
- Inputs
- Outputs
- Fee
- Validity Interval
- Required Signers
- Script Data Hash
이 경우 변경된 Body에 맞춰 다시 서명해야 합니다.
반면 Witness Set에 유효한 서명을 추가하는 것 자체는 Transaction Body를 변경하지 않으므로 TxId를 바꾸지 않습니다.
5 Datum과 Redeemer: 스크립트 실행에 전달되는 데이터
Plutus 스크립트는 트랜잭션에 포함된 실행 문맥과 입력 데이터에 따라 결과를 결정합니다. 대표적인 입력 요소가 Datum과 Redeemer입니다.
5.1 Datum
Datum은 스크립트 주소에 잠긴 UTxO와 연결되는 데이터입니다.
예를 들어 다음과 같은 정보를 표현할 수 있습니다.
- 자산 소유자
- 잠금 해제 조건
- 상태 정보
- 계약에 필요한 식별자
Babbage 이후의 Transaction Output에서는 Datum을 표현하는 방식으로 Datum Hash와 Inline Datum을 사용할 수 있습니다.
| 구분 | Datum Hash | Inline Datum |
|---|---|---|
| 출력에 기록되는 정보 | Datum의 해시 | Datum 데이터 자체 |
| 실제 데이터 | 별도로 제공될 수 있음 | 출력 안에 포함 |
| 참조 방식 | 해시를 통해 연결 | 출력에서 직접 확인 |
| 주요 고려사항 | Datum 원본을 별도로 확보해야 할 수 있음 | 출력 크기 및 데이터 직렬화 고려 |
Datum Hash 방식에서는 트랜잭션의 Witness Set에 Datum 데이터가 제공될 수 있습니다. 그러나 모든 Datum Hash가 반드시 동일 트랜잭션의 Witness Set에 존재한다고 가정해서는 안 됩니다. 소비하려는 UTxO와 스크립트가 요구하는 데이터 확보 방식을 확인해야 합니다.
Inline Datum과 CIP-0032
Inline Datum은 CIP-0032를 통해 도입된 기능으로, Datum 데이터를 Transaction Output 내부에 직접 저장하는 방식입니다. 소비 트랜잭션은 해당 UTxO를 참조하여 Inline Datum을 확인할 수 있으므로, Datum 원본을 별도로 Witness Set에 다시 포함할 필요가 없습니다.
이 방식은 Datum 데이터의 별도 전달 과정을 줄이고, Reference Input과 결합하여 다른 트랜잭션에서 온체인 상태를 읽는 설계를 가능하게 합니다.
다만 Inline Datum이 모든 상황에서 최선의 선택은 아닙니다. 출력 크기와 데이터 공개 범위, 트랜잭션 비용, 프로토콜 설계에 따라 Datum Hash 방식이 더 적합할 수도 있습니다.
5.2 Redeemer
Redeemer는 스크립트가 실행될 때 전달되는 입력 데이터입니다.
예를 들어 다음과 같은 작업 의도를 표현할 수 있습니다.
- 자산 인출
- 토큰 발행
- 계약 상태 변경
- 조건에 따른 자산 이전
Redeemer는 단순한 사용자 입력 문자열이 아닙니다. Plutus Data 형식으로 직렬화되어야 하며, 스크립트가 기대하는 데이터 구조와 정확히 일치해야 합니다. 잘못된 필드 순서, 데이터 타입 또는 Constructor 인덱스는 스크립트 실패의 원인이 될 수 있습니다.
5.3 Redeemer Index는 무엇을 의미하는가?
Conway CDDL에서는 Redeemer가 Script Purpose Tag와 Index를 사용하여 식별됩니다.
대표적인 Tag는 다음과 같습니다.
| Tag | Script Purpose |
|---|---|
| 0 | Spend |
| 1 | Mint |
| 2 | Cert |
| 3 | Reward |
| 4 | Voting |
| 5 | Proposing |
Index는 해당 목적에 속하는 Ledger 대상의 순서와 연결됩니다.
따라서 Redeemer Index를 단순히 “트랜잭션 입력 배열의 번호”라고 설명하면 부정확합니다. Spend, Mint, Cert, Reward, Voting, Proposing 등 목적별 Ledger 규칙에 따라 인덱싱 대상과 순서를 해석해야 합니다.
Conway Era의 Voting과 Proposing
Babbage Era에서 사용되던 Spend, Mint, Cert, Reward 목적에 더해 Conway Era에서는 온체인 거버넌스를 위한 Voting과 Proposing 목적이 추가되었습니다.
이는 CIP-1694에 따른 거버넌스 기능과 연결됩니다. Voting은 거버넌스 투표를 검증하는 스크립트 목적이며, Proposing은 거버넌스 제안(Proposal Procedure)을 검증하는 스크립트 목적입니다.
따라서 Conway Era에서 Redeemer Index를 해석할 때는 기존 네 가지 목적뿐 아니라 Voting과 Proposing까지 포함하여 목적별 Ledger 인덱싱 규칙을 확인해야 합니다.
6 Script Data Hash와 Plutus V3
Script Data Hash는 Transaction Body의 필드 11에 해당하며, Script Integrity Hash라고도 불립니다.
이 해시는 스크립트 실행 결과에 영향을 미치는 데이터와 언어별 실행 비용 정보를 Ledger가 검증할 수 있도록 연결합니다.
Conway CDDL의 설명에 따르면 해시 계산에 사용되는 핵심 자료는 다음과 같습니다.
- Transaction Witness Set의 Redeemers
- Transaction Witness Set의 Datums
- 해당 스크립트 언어에 대응하는 Language Views
개념적으로 다음과 같이 표현할 수 있습니다.
Script Data Hash
= Hash(
Redeemers
|| Datums
|| Language Views
)
이 표현은 구성 요소를 이해하기 위한 개념도입니다. 실제 해시를 계산할 때는 Ledger가 정한 CBOR 직렬화, 데이터의 존재 여부, Language Views의 정규 인코딩 규칙을 따라야 합니다.
6.1 Cost Model은 어디에 포함되는가?
Cost Model은 Plutus 스크립트의 실행 비용을 계산하는 데 사용되는 언어별 파라미터입니다.
Script Data Hash를 설명할 때 Cost Model을 단순히 별도의 원시 바이트 덩어리로 Redeemer와 이어 붙인다고 이해해서는 안 됩니다.
Ledger는 해당 스크립트 언어에 대응하는 Language Views를 구성하고, 이를 Redeemers 및 Datums와 함께 규정된 방식으로 해싱합니다.
따라서 Script Data Hash는 다음과 같은 역할을 합니다.
- Redeemer와 Datum의 무결성 연결
- 스크립트 언어별 비용 파라미터와의 연결
- 트랜잭션이 스크립트 실행에 필요한 정보를 일관되게 제공하는지 검증
Plutus V3 역시 Conway Era에서 지원되는 Plutus 언어 중 하나입니다. 그러나 V3라는 이유만으로 Script Data Hash의 원리를 별도로 임의 정의해서는 안 됩니다. 해당 Era의 Ledger CDDL과 Script Integrity Hash 규칙을 따라야 합니다.
7 Collateral: 스크립트 실패에 대비하는 담보
Plutus 스크립트가 포함된 트랜잭션은 Collateral을 요구할 수 있습니다.
Collateral은 일반적인 트랜잭션 입력과 구별됩니다.
| 구분 | 일반 Input | Collateral |
|---|---|---|
| 목적 | 트랜잭션의 정상적인 자산 소비 | Phase-2 실패에 대비 |
| 정상 실행 | 소비되어 Output 구성에 반영 | 일반적으로 소비되지 않음 |
| Phase-2 실패 | Ledger 규칙에 따라 정상 입력 처리 여부가 달라짐 | 정해진 규칙에 따라 담보 처리 |
| 관련 필드 | Transaction Body: inputs | Transaction Body: collateral |
Babbage 및 Conway 계열에서는 다음 필드가 Collateral 처리와 관련됩니다.
- collateral
- collateral_return
- total_collateral
Collateral Return은 실패 시 담보로 제공된 금액 중 반환될 부분을 표현할 수 있습니다. 다만 실제 적용 여부와 계산은 Era별 Ledger 규칙 및 프로토콜 파라미터에 따릅니다.
Collateral을 일반 수수료와 동일하게 이해해서는 안 됩니다. 정상적인 스크립트 실행과 실패한 스크립트 실행의 처리 방식이 다르기 때문입니다.
8 Execution Units와 Fee 계산
Plutus 스크립트 실행에는 실행 예산이 필요합니다. Cardano는 이를 Execution Units(ExUnits)로 표현합니다.
| 항목 | 의미 |
|---|---|
| Memory | 스크립트 실행에 사용되는 메모리 예산 |
| Steps | 스크립트 실행 연산량 예산 |
ExUnits는 각 Redeemer와 연결됩니다. 따라서 여러 스크립트가 실행되는 트랜잭션에서는 Redeemer별 실행 예산을 관리해야 합니다.
8.1 Evaluation은 왜 필요한가?
스크립트가 실행되기 전에 예상 실행 비용을 정확히 알기 어려울 수 있습니다.
Provider 또는 Node의 Evaluation 기능은 구성된 트랜잭션을 대상으로 스크립트 실행 결과와 실행 예산을 산출하는 데 도움을 줍니다.
일반적인 개념 흐름은 다음과 같습니다.
Transaction 초안 구성
│
▼
Script Evaluation
│
▼
Redeemer별 ExUnits 확인
│
▼
Redeemer 예산 반영
│
▼
Transaction 재구성 및 Fee 조정
이 과정은 한 번으로 끝나지 않을 수 있습니다. Redeemer 예산, 트랜잭션 크기, Fee, Change Output이 서로 영향을 주기 때문입니다.
8.2 Fee는 무엇으로 결정되는가?
Cardano 트랜잭션 수수료는 단순히 트랜잭션 크기만으로 결정되지 않습니다.
일반적으로 다음 요소를 고려합니다.
- 직렬화된 트랜잭션 크기
- 프로토콜 파라미터
- Plutus 스크립트 실행 비용
- 적용되는 경우 Reference Script 관련 비용
- 기타 Ledger 규칙에 따른 비용 요소
따라서 고정된 ADA 금액을 모든 트랜잭션에 적용해서는 안 됩니다. 실제 Fee는 네트워크의 현재 프로토콜 파라미터와 트랜잭션 구성에 따라 계산해야 합니다.
9 UTxO Selection과 Balance
트랜잭션을 구성할 때는 출력에 필요한 자산과 수수료를 충족할 수 있도록 입력 UTxO를 선택해야 합니다.
예를 들어 다음과 같은 트랜잭션을 구성한다고 가정하겠습니다.
사용자 Input:
20 ADA
목표 Output:
12 ADA
예상 Fee:
0.2 ADA
예상 Change:
7.8 ADA
이는 ADA만 사용하는 단순 예시입니다. 실제 Multi-Asset 트랜잭션에서는 토큰 수량과 최소 ADA 요구사항도 고려해야 합니다.
UTxO Selection은 단순히 가장 큰 UTxO 하나를 선택하는 작업이 아닙니다. 다음 사항을 함께 고려해야 합니다.
- 필요한 ADA와 Native Asset 수량
- 입력 UTxO의 실제 소비 가능 여부
- 출력별 최소 ADA 조건
- Change Output 구성
- 최대 Value 크기 등 Ledger 제한
- 트랜잭션 크기와 Fee
- Collateral로 사용할 수 있는 UTxO의 조건
Fee가 증가하면 필요한 Input과 Change Output이 바뀔 수 있습니다. 따라서 Balance와 Fee 계산은 서로 영향을 주는 반복 작업이 될 수 있습니다.
10 CBOR 직렬화와 Transaction의 실제 표현
CBOR(Canonical Binary Representation)은 Cardano 트랜잭션을 바이너리로 표현하는 데 사용되는 직렬화 형식입니다. 개발자가 작성하는 JavaScript 객체나 JSON 형태의 데이터가 그대로 블록체인에 저장되는 것은 아닙니다.
일반적인 과정은 다음과 같습니다.
Application Data
│
▼
Transaction Builder
│
▼
Ledger Transaction Structure
│
▼
CBOR Serialization
│
▼
Transaction CBOR Hex
│
▼
Wallet Signing
│
▼
Signed Transaction CBOR
CBOR는 사람이 읽기 쉬운 형식이 아니므로 디버깅할 때는 CBOR Decoder나 Transaction Parser를 사용합니다.
다만 CBOR를 디코딩한 뒤 다시 인코딩하는 과정에서 원래의 바이트 표현이 달라질 수 있다는 점에 주의해야 합니다.
특히 Transaction Body의 해시를 계산할 때는 Ledger가 검증하는 실제 직렬화 바이트가 중요합니다. 임의로 재인코딩하거나 Map의 정렬 및 길이 표현을 바꾸면 기존 바이트와 다른 결과가 나올 수 있습니다.
11 Build → Evaluate → Balance → Sign → Submit
이제 전체 과정을 하나의 개발 흐름으로 정리해 보겠습니다.
Step 1. UTxO 및 체인 데이터 조회
먼저 소비할 UTxO, 참조할 UTxO, 스크립트 주소의 데이터 등을 조회합니다. 필요한 경우 Protocol Parameters, Script 및 Script Hash, Datum, Redeemer 데이터 구조, Collateral 후보 UTxO, Wallet Address 및 Signer 정보도 확보합니다.
Step 2. Transaction 초안 구성
Transaction Builder를 이용하여 Inputs, Outputs, Datum / Redeemer, Mint / Burn, Validity Interval, Reference Inputs, Collateral, Required Signers를 설정합니다.
Step 3. Script Evaluation
Plutus 스크립트가 포함되어 있다면 Provider 또는 지원되는 평가 도구로 실행 결과와 ExUnits를 확인합니다. 평가 결과는 Redeemer별로 반영되어야 합니다.
Step 4. Fee 및 Balance 조정
입력 UTxO, 출력, Fee, Change, ExUnits를 반영해 트랜잭션을 균형 상태로 만듭니다. 필요한 경우 Evaluation과 Balance를 반복합니다.
Step 5. CBOR 직렬화 및 서명
완성된 Transaction Body를 기준으로 서명을 요청합니다. 지갑은 Transaction Body의 해시를 기준으로 서명하고, 그 결과를 Witness Set에 추가합니다. 서명 이후 Transaction Body를 변경하면 기존 서명은 더 이상 변경된 Body를 보증하지 않습니다.
Step 6. Submit
서명된 트랜잭션을 Node 또는 Provider를 통해 네트워크에 제출합니다. 제출 결과로 TxId를 반환받을 수 있지만, 제출 성공 응답만으로 블록 포함이나 최종 확정을 의미하지는 않습니다.
Step 7. Confirmation 확인
TxId를 이용해 체인에서 트랜잭션의 상태를 조회합니다. 제출 요청 성공, 노드 또는 Provider의 수락, 블록 포함, 후속 블록 생성 및 확인 수준 증가 등의 단계들은 서로 명확히 구분해야 합니다.
12 Mesh SDK를 이용한 기본 Build·Sign·Submit 예제
SDK마다 API와 내부 구현은 다릅니다. 여기서는 Mesh SDK 공식 문서에 소개된 MeshTxBuilder 흐름을 단순 ADA 전송 예제로 살펴봅니다.
다음 코드는 Plutus 스크립트 실행 예제가 아니라, 기본적인 트랜잭션 구성과 서명 및 제출의 구조를 보여주는 예제입니다.
import {
MeshTxBuilder,
BlockfrostProvider,
} from "@meshsdk/core";
// Provider
const provider = new BlockfrostProvider(
"<YOUR_API_KEY>"
);
// Transaction Builder
const txBuilder = new MeshTxBuilder({
fetcher: provider,
submitter: provider,
});
// Wallet에서 필요한 정보 조회
const utxos = await wallet.getUtxos();
const changeAddress = await wallet.getChangeAddress();
// Build
const unsignedTx = await txBuilder
.txOut(
"addr_test1...",
[
{
unit: "lovelace",
quantity: "5000000",
},
]
)
.changeAddress(changeAddress)
.selectUtxosFrom(utxos)
.complete();
// Sign
const signedTx = await wallet.signTx(unsignedTx);
// Submit
const txHash = await wallet.submitTx(signedTx);
console.log("Submitted TxId:", txHash);
이 예제에서 확인할 수 있는 것은 세 단계의 역할이 분리되어 있다는 점입니다.
| 단계 | 코드 | 역할 |
|---|---|---|
| Build | txBuilder.complete() | 트랜잭션 구성 및 완성 |
| Sign | wallet.signTx() | 지갑 서명 |
| Submit | wallet.submitTx() | 서명된 트랜잭션 제출 |
Mesh SDK의 Builder는 설정된 Fetcher, Evaluator, Serializer, Protocol Parameters 등에 따라 더 복잡한 작업을 지원할 수 있습니다.
다만 위의 단순 전송 예제만으로 Plutus Evaluation, Collateral 선택, Script Data Hash 생성의 내부 동작까지 설명할 수는 없습니다. 스마트 컨트랙트 트랜잭션에서는 별도의 스크립트 구성과 평가 절차가 필요합니다.
13 SDK API를 사용할 때 주의할 점
Lucid-Evolution과 Mesh SDK는 모두 Cardano 오프체인 트랜잭션 개발에 사용할 수 있지만, API 이름과 내부 처리 방식이 동일하다고 가정해서는 안 됩니다.
특히 다음 사항을 구분해야 합니다.
- Builder가 Fee를 자동 계산하는지, 별도 계산이 필요한지
- Script Evaluation을 자동으로 수행하는지, Provider를 직접 연결해야 하는지
- Redeemer별 ExUnits를 어떻게 설정하는지
- Collateral을 자동 선택하는지, 명시적으로 지정해야 하는지
- 서명 결과가 CBOR 문자열인지, 다른 직렬화 객체인지
- Submit 기능이 Wallet과 Provider 중 어디에 구현되어 있는지
이 글에서는 확인되지 않은 Lucid-Evolution 메서드 이름이나 버전별 API를 임의로 만들어 제시하지 않습니다.
실제 프로젝트에 적용할 때는 설치된 SDK 버전과 공식 API 문서의 인터페이스를 기준으로 코드를 작성해야 합니다.
14 Phase-1과 Phase-2 검증: Submit 이후의 Ledger 처리
Cardano의 스마트 컨트랙트 트랜잭션 검증은 크게 두 단계로 이해할 수 있습니다.
14.1 Phase-1: 기본 Ledger 검증
Phase-1에서는 트랜잭션이 Ledger의 기본 규칙을 충족하는지 검사합니다.
대표적으로 다음 항목이 포함됩니다.
- Transaction 구조와 필드의 유효성
- 입력 UTxO의 존재 및 소비 가능 여부
- 서명 및 요구 서명자의 유효성
- 수수료 및 잔액 조건
- 유효 기간
- 출력 및 최소 ADA 조건
- 기타 해당 Era의 Ledger 규칙
Phase-1에서 실패한 트랜잭션은 정상적인 블록 포함 대상으로 진행할 수 없습니다.
14.2 Phase-2: Plutus 스크립트 검증
Phase-1 검증을 통과한 Plutus 트랜잭션은 Phase-2 스크립트 검증을 받습니다.
이 단계에서는 각 스크립트가 주어진 실행 문맥과 Redeemer 등의 입력에 따라 유효한 결과를 내는지 평가합니다.
여기서 중요한 점은 Phase-2 실패의 처리 방식입니다.
Plutus 스크립트가 실패했다고 해서 항상 Phase-1과 동일하게 트랜잭션 전체가 단순 거부되는 것은 아닙니다. Ledger 규칙에 따라 is_valid가 false인 트랜잭션이 블록에 포함될 수 있으며, 이 경우 Collateral 처리 규칙이 적용됩니다.
따라서 다음 두 상황은 구분해야 합니다.
| 상황 | 결과 |
|---|---|
| Phase-1 실패 | 트랜잭션이 기본 Ledger 검증을 통과하지 못함 (블록 미포함) |
| Phase-1 통과, Phase-2 실패 | 스크립트 실패 상태로 처리될 수 있으며 Collateral 규칙 적용 |
| Phase-1 통과, Phase-2 성공 | 정상적인 스크립트 실행 결과로 처리 (정상 입력 소비 및 출력 생성) |
15 실무 디버깅 체크리스트
트랜잭션이 제출되지 않거나 스크립트 실행에 실패할 때 다음 항목을 순서대로 확인할 수 있습니다.
| 점검 항목 | 확인 내용 |
|---|---|
| UTxO | 입력 UTxO가 존재하며 이미 소비되지 않았는가? |
| Network | Mainnet, Preprod 등 네트워크 설정이 일치하는가? |
| Datum | 스크립트가 기대하는 데이터 구조와 일치하는가? |
| Redeemer | 데이터 타입, Constructor, 필드 순서가 올바른가? |
| Redeemer Index | Script Purpose별 Index가 정확한가? |
| Script Data Hash | Redeemer, Datum, Language Views에 맞게 갱신되었는가? |
| ExUnits | Redeemer별 Memory와 Steps 예산이 적절한가? |
| Collateral | 해당 트랜잭션과 Era의 조건을 충족하는가? |
| Fee | 최신 Protocol Parameters에 따라 계산되었는가? |
| Change | ADA 및 Native Asset 잔액이 올바른가? |
| CBOR | 직렬화 결과가 해당 Era의 규칙에 맞는가? |
| Signature | 서명 후 Transaction Body가 변경되지 않았는가? |
| Submit | 제출 응답과 실제 블록 포함 상태를 구분했는가? |
자주 발생하는 문제
조회한 UTxO가 다른 트랜잭션에 의해 이미 소비되었을 수 있습니다. 제출 직전 입력 상태를 다시 확인해야 합니다.
트랜잭션 입력이나 목적별 대상의 구성이 바뀌었는데 Redeemer Index를 갱신하지 않으면 스크립트가 의도하지 않은 데이터를 받을 수 있습니다.
Fee가 증가하면 Change Output과 Input 선택도 달라질 수 있습니다. 최종 Balance 이후 Body가 변경되었다면 재평가와 재서명이 필요할 수 있습니다.
Redeemer, Datum 또는 Language Views가 변경되었는데 Script Data Hash를 갱신하지 않으면 Ledger 검증에 실패할 수 있습니다.
Provider가 TxId를 반환했다고 해서 블록 포함이 완료된 것은 아닙니다. 별도의 체인 조회와 Confirmation 확인이 필요합니다.
16 마무리: Transaction은 단순한 데이터가 아니라 검증 가능한 Ledger 객체다
Cardano에서 오프체인 트랜잭션을 구성하는 작업은 단순히 API를 호출해 자산을 보내는 과정이 아닙니다.
개발자는 다음 요소가 서로 일치하도록 관리해야 합니다.
- UTxO 입력과 출력
- Datum과 Redeemer
- Script Data Hash
- ExUnits와 Fee
- Collateral
- Transaction Body의 CBOR 직렬화
- VKey Witness
- Ledger의 Phase-1 및 Phase-2 검증
이 가운데 가장 중요한 원칙은 Transaction Body가 서명의 기준이 되는 핵심 데이터라는 점입니다.
Body를 변경하면 TxId와 서명의 관계가 달라집니다. 스크립트 관련 데이터가 변경되면 Script Data Hash와 ExUnits도 다시 확인해야 합니다. 그리고 Submit 응답과 블록 포함 상태는 별개의 단계입니다.
이러한 구조를 이해하면 Cardano 스마트 컨트랙트 개발에서 발생하는 CBOR 오류, 서명 불일치, Script Evaluation 실패, Fee 부족, Collateral 문제를 더 체계적으로 분석할 수 있습니다.
기술 참고 자료
-
Cardano Ledger — Conway CDDL 및 Era별 Ledger 명세:
https://github.com/IntersectMBO/cardano-ledger -
Cardano Developer Portal — Transactions:
https://developers.cardano.org/docs/learn/core-concepts/transactions/ -
Cardano Developer Portal — Debugging CBOR:
https://developers.cardano.org/docs/build/smart-contracts/advanced/debug-cbor/ -
Cardano Developer Portal — Smart Contracts:
https://developers.cardano.org/docs/smart-contracts/ -
Mesh SDK — Transaction Builder Basics:
https://meshjs.dev/apis/txbuilder/basics -
Mesh SDK — API Reference:
https://meshjs.dev/apis