A
Aura Core Research SMART CONTRACT TUTORIALS
Home / Smart Contract Tutorials / aura-core-50-datum-redeemer-transaction-context
Cardano Smart Contract Development Series · Part 03 · AURA #50

Datum, Redeemer와 Transaction Context: Aiken Validator는 무엇을 읽는가?

Cardano eUTxO 모델에서 스마트 컨트랙트가 참조하는 세 가지 핵심 요소인 Datum(상태 데이터), Redeemer(동작 데이터), Transaction Context(트랜잭션 구조 정보)의 상호작용과 검증 설계 원리

PK
Paul Ko (Cardano Ambassador & DRep)
Published: 2026-11-05 · Series: Developer Tutorial
#Aiken #Cardano #Datum #Redeemer #eUTxO
기술적 범위 및 검증 상태 안내 본 글은 Aiken과 Cardano eUTxO의 데이터 흐름 및 상호작용 원리를 설명하는 교육 자료입니다. 본 문서의 작성 과정에서 별도의 로컬 컴파일, 자동화 테스트 및 테스트넷 배포가 완료된 상태를 의미하는 것은 아닙니다.

1 이번 글에서 배울 것

AURA #49에서는 소유자의 공개키 해시를 Datum에 저장하고, Spending Validator가 트랜잭션의 서명자 목록을 확인하는 방법을 살펴봤습니다.

이번에는 그 검증이 어떤 데이터를 기반으로 이루어지는지 자세히 살펴봅니다.

Cardano의 eUTxO 모델에서 스마트 컨트랙트는 세 가지 핵심 요소를 조합하여 검증을 수행합니다.

  • Datum: 스크립트 주소에 UTxO를 생성할 때 함께 설정하는 데이터
  • Redeemer: 해당 UTxO를 소비하려는 트랜잭션에서 전달하는 데이터
  • Transaction Context: 현재 검증 대상 트랜잭션의 구조적 정보

이 세 가지를 이해하면 단순한 서명 확인을 넘어 상태 관리, 조건부 인출, 토큰 발행과 같은 다양한 스마트 컨트랙트 구조를 이해할 수 있습니다.

2 Datum: UTxO에 저장되는 상태 데이터

Datum은 UTxO 생성 시 출력에 연결됩니다. Datum 자체를 출력에 포함하는 Inline Datum 방식과 Datum Hash를 기록하고 실제 Datum 데이터를 별도로 제공하는 방식이 있습니다. Spending Validator는 소비 시점에 해당 Datum을 Option<T> 형태로 전달받습니다.

예를 들어 특정 소유자만 자산을 인출할 수 있도록 만들려면 소유자의 공개키 해시를 Datum에 저장할 수 있습니다.

pub type OwnerDatum {
  owner: VerificationKeyHash,
}

이 구조에서 owner는 소유자의 공개키 해시입니다.

Datum은 개인키나 실제 서명 데이터를 저장하는 공간이 아닙니다. Validator가 나중에 검증할 조건이나 상태를 기록하는 데이터입니다.

Datum은 UTxO가 생성되는 시점에 설정되며, 이후 해당 UTxO를 소비하는 Spending Validator에서 전달받아 사용할 수 있습니다.

Datum이 항상 존재하는 것은 아니다

Aiken의 Spending Validator는 Datum을 다음과 같이 전달받습니다.

datum: Option<OwnerDatum>

이는 Datum이 존재할 수도 있고 존재하지 않을 수도 있다는 뜻입니다.

따라서 반드시 Datum이 필요한 컨트랙트라면 다음과 같이 확인해야 합니다.

expect Some(OwnerDatum { owner }) = datum

Datum이 없거나 예상한 데이터 구조와 일치하지 않으면 expect 문에 의해 스크립트 평가 자체가 실패(Evaluation Failure)하게 되며, 단순히 False를 반환하는 것과 구별됩니다.

3 Redeemer: 소비자가 전달하는 실행 데이터

Redeemer는 UTxO를 소비하려는 트랜잭션이 Validator에 전달하는 데이터입니다.

Datum이 UTxO 생성 시점에 설정되는 데이터라면, Redeemer는 소비 시점에 전달되는 데이터라는 차이가 있습니다.

예를 들어 사용자가 자산을 인출하거나 취소할 수 있는 컨트랙트를 생각해 봅시다.

pub type Action {
  Withdraw
  Cancel
}

이렇게 정의하면 소비자는 다음 두 가지 동작 중 하나를 요청할 수 있습니다.

  • Withdraw: 자산 인출 요청
  • Cancel: 취소 요청

Validator는 Redeemer에 따라 서로 다른 조건을 검사할 수 있습니다.

예를 들어 인출 요청에는 소유자 서명이 필요하고, 취소 요청에는 별도의 시간 조건이 필요하도록 설계할 수 있습니다.

중요한 것은 Redeemer 자체가 권한을 부여하지 않는다는 점입니다.

사용자가 Withdraw를 전달했다고 해서 자동으로 자산을 인출할 수 있는 것은 아닙니다. 실제 허용 여부는 Validator가 Datum과 Transaction Context를 함께 검사한 결과에 달려 있습니다.

4 Transaction Context: 검증 대상 트랜잭션 정보

세 번째 요소는 Transaction Context입니다.

Aiken의 Spending Validator는 마지막 인자로 Transaction을 전달받습니다.

use cardano/transaction.{OutputReference, Transaction}

예를 들어 다음과 같은 구조로 핸들러를 정의할 수 있습니다.

validator example {
  spend(
    datum: Option<OwnerDatum>,
    redeemer: Action,
    _own_ref: OutputReference,
    self: Transaction,
  ) {
    // Validation logic
    True
  }
}

self는 현재 검증 대상 트랜잭션의 구조적 정보를 나타냅니다. (교육적 비유로 흔히 "실행 증거"로 불리기도 합니다.)

이를 통해 Validator는 트랜잭션의 입력, 출력, 수수료, 자산 이동, 서명자 정보 등 검증에 필요한 여러 요소를 확인할 수 있습니다.

예를 들어 다음과 같은 정보를 활용할 수 있습니다. (※ 아래 각 필드의 구체적인 내부 타입은 사용하는 Aiken 컴파일러 및 표준 라이브러리 버전에 따라 달라질 수 있으므로, 실제 프로젝트의 라이브러리 정의를 확인해야 합니다.)

필드 활용 목적
inputs 소비하려는 입력 UTxO 목록 확인
outputs 자산이 전달되는 목적지 출력 확인
fee 트랜잭션 수수료 확인
mint 토큰 발행 및 소각 정보 확인
extra_signatories 요구된 서명자 공개키 해시 목록 확인
validity_range 트랜잭션 유효 시간 범위 확인

5 세 가지 데이터가 함께 작동하는 과정

이제 세 가지 요소를 하나의 흐름으로 연결해 보겠습니다.

  1. 사용자가 스크립트 주소에 자산을 보냅니다.
  2. 출력에 Datum이 연결되어 소유자의 공개키 해시 등이 기록됩니다.
  3. UTxO에 자산과 Datum이 연결된 상태로 온체인에 존재합니다.
  4. 시간이 지나 사용자가 해당 UTxO를 소비하려고 합니다.
  5. 소비 트랜잭션에 Redeemer가 포함됩니다.
  6. Spending Validator가 Datum, Redeemer, Transaction Context를 전달받습니다.
  7. Validator가 소유자 서명, 인출 조건, 출력 조건 등을 검사합니다.
  8. 모든 조건이 충족되면 해당 스크립트의 검증이 통과합니다.

이 구조를 간단히 표현하면 다음과 같습니다.

UTxO 생성
   │
   └── 출력에 Datum 연결 (Inline Datum 또는 Datum Hash)
          │
          ▼
     UTxO 잠금 상태 (자산과 Datum이 연결되어 존재)
          │
          ▼
     소비 트랜잭션 생성
          │
          ├── Redeemer 전달
          │
          └── Transaction Context 제공
                  │
                  ▼
           Spending Validator
                  │
                  ▼
             조건 검증
                  │
             ┌────┴────┐
             ▼         ▼
           통과       실패

6 Datum과 Redeemer는 신뢰할 수 있는가?

Datum과 Redeemer는 컨트랙트의 검증 입력이지, 그 자체로 신뢰할 수 있는 권한 증명은 아닙니다.

예를 들어 다음과 같은 Datum이 있다고 가정하겠습니다.

pub type AccountDatum {
  balance: Int,
  owner: VerificationKeyHash,
}

여기서 balance: 1000은 개발자가 정의한 데이터 필드의 정수값일 뿐이며, 실제 UTxO에 1,000 ADA(참고: 1 ADA = 1,000,000 Lovelace) 또는 1,000 Lovelace의 잔액이 존재한다는 사실을 증명하지 않습니다.

Cardano 원장은 트랜잭션의 기본적인 자산 보존 규칙을 검증합니다. 그러나 이것만으로 계약의 비즈니스 조건까지 자동으로 보장되지는 않습니다. Validator는 self.inputs와 self.outputs의 실제 Value를 확인하여 계약에서 요구하는 지급 대상, 지급량, 잔액 반환 및 상태 전이 조건을 별도로 검증해야 합니다.

마찬가지로 Redeemer에 Withdraw가 들어 있다고 해서 인출 권한이 생기는 것도 아닙니다.

Validator는 사용자가 전달한 데이터를 그대로 믿는 대신, 컨트랙트가 정의한 조건에 맞는지 확인해야 합니다.

7 실무에서 자주 발생하는 설계 실수

① Datum을 실제 자산 잔액으로 오해하는 경우

Datum에 기록된 숫자는 컨트랙트가 관리하는 상태 데이터일 뿐입니다. 실제 UTxO의 자산 수량과 반드시 일치하는 것은 아닙니다. 이를 혼동하면 잘못된 지급이나 계약 규칙 우회로 이어질 수 있으므로, 자산 보존 및 이동 조건을 검증하려면 입력과 출력의 실제 Value를 직접 대조해야 합니다.

② Redeemer를 권한 증명으로 사용하는 경우

Redeemer는 소비자의 동작 요청을 표현합니다. 권한 확인은 서명자 목록, Datum, 트랜잭션 조건 등을 조합하여 별도로 수행해야 합니다.

③ Transaction Context를 충분히 검사하지 않는 경우

스크립트가 특정 출력으로 자산을 보내도록 설계되었다면, 단순히 소비 요청이 유효한지만 검사해서는 안 됩니다. 출력 주소와 자산 수량까지 확인해야 합니다.

④ Datum의 존재를 가정하는 경우

Spending Validator의 Datum은 Option<T>입니다. Datum이 반드시 필요하다면 expect Some(...) 등의 패턴으로 명시적으로 검사해야 하며, 없을 경우 스크립트 평가가 실패하도록 설계해야 합니다.

8 핵심 요약

구성 요소 설정 시점 역할
Datum UTxO 생성 시 (Inline Datum 또는 Datum Hash) 컨트랙트 상태 및 설정 데이터
Redeemer UTxO 소비 시 소비자의 요청 또는 동작 데이터
Transaction Context 검증 실행 시 검증 대상 트랜잭션의 구조적 정보

세 가지 요소를 함께 이해해야 eUTxO 기반 스마트 컨트랙트의 검증 구조를 제대로 설계할 수 있습니다.

Datum은 무엇을 기억하는지, Redeemer는 어떤 동작을 요청하는지, Transaction Context는 실제 트랜잭션이 어떤 상태인지 보여줍니다.

다음 AURA #51에서는 Aiken의 단위 테스트를 통해 정상적인 검증과 실패하는 검증을 구분하고, 테스트 케이스를 설계하는 방법을 살펴봅니다.


기술적 범위 및 검증 상태 고지

본 글은 Aiken과 Cardano eUTxO의 데이터 흐름을 설명하는 교육 자료입니다. 실제 Aiken 컴파일, 자동화 테스트 또는 테스트넷 실행을 완료했다는 의미는 아닙니다.

이전 아티클 (AURA #49) 첫 Spending Validator와 소유자 서명 조건: owner_lock.ak
다음 아티클 (AURA #51) 다음 편 준비 중 (Aiken 단위 테스트와 fail 테스트)