A
Aura Core Research SMART CONTRACT TUTORIALS
Home / Smart Contract Tutorials / aura-core-53-validator-module-handler-blueprint-title
Cardano Smart Contract Development Series · Part 06 · AURA #53

Validator, 모듈, 핸들러 이름과 Blueprint Title 매핑 규칙

Aiken 소스코드의 구성 계층(모듈, Validator, 핸들러), 6대 목적 핸들러와 else의 구분, CIP-0057 Plutus Blueprint Title의 본질 및 오프체인 dApp 연동 시 Title 조회 원리와 위험 예방 수칙

PK
Paul Ko (Cardano Ambassador & DRep)
Published: 2026-11-11 · Series: Developer Tutorial
#Aiken #Cardano #CIP57 #BlueprintTitle #eUTxO
기술적 범위 안내 본 글은 Aiken 컴파일러의 소스코드 구조와 CIP-0057 명세의 매핑 관례를 설명하는 교육용 기술 자료입니다. 본 문서의 작성 과정에서 실제 로컬 컴파일러 실행이나 테스트넷 배포가 완료되었다는 의미는 아닙니다. 코드 및 JSON 예시는 이해를 돕기 위한 교육용 플레이스홀더입니다.

1 이번 글에서 배울 것

AURA #52에서는 aiken build 명령이 UPLC 컴파일을 수행하고, CIP-0057 Plutus Blueprint(plutus.json)라는 표준화된 인터페이스 명세서를 생성하는 과정을 살펴봤습니다.

오프체인 애플리케이션은 plutus.json의 Validator 항목을 읽어 필요한 스크립트를 선택하고, 컴파일된 코드와 파라미터를 이용해 스크립트 해시 및 주소를 계산할 수 있습니다. 이때 title은 사람이 Validator 항목을 식별하고 선택하는 데 활용할 수 있는 설명적 이름입니다. 다만 CIP-0057에서 title은 상호운용성을 결정하는 필수 식별자가 아니므로, 실제 스크립트의 코드·해시·파라미터와 구분해서 이해해야 합니다.

Aiken 소스코드에서 선언한 모듈, 검증기, 핸들러는 어떤 관계를 가지며, Blueprint의 Title은 실무에서 어떻게 해석하고 다루어야 할까요?

이번 글에서는 다음 핵심 주제를 다룹니다.

  1. Aiken 소스코드의 구성 계층: 파일과 모듈, Validator 선언, 핸들러
  2. Aiken Validator가 지원하는 6대 목적 핸들러와 사용자 정의 else의 구분
  3. CIP-0057에서 정의하는 Blueprint Title의 본질과 도구별 명명 관례
  4. 단일 목적 검증기와 다목적 검증기(Multi-purpose: spend, mint 등)의 구조
  5. 오프체인 애플리케이션에서 Blueprint Title을 안전하게 조회하고 활용하는 방법
  6. 실무에서 발생할 수 있는 명명 불일치 위험 상황과 예방 수칙

2 소스코드의 구성 계층

Aiken 프로젝트의 소스코드는 파일과 모듈, Validator 선언, 핸들러라는 개념으로 이해할 수 있습니다.

Aiken project
└── validators/
    └── owner_lock.ak
        └── module
            └── validator owner_lock
                └── spend(...)

각 계층의 역할과 문법적 의미는 다음과 같습니다.

  • 모듈(Module): Aiken 소스 파일에서 정의와 Validator를 구성하는 단위입니다. 파일 경로와 모듈 이름은 프로젝트의 소스 구조를 이해하는 데 중요합니다.
  • 검증기(Validator): validator 키워드로 선언하는 온체인 검증 로직의 단위입니다.
  • 핸들러(Handler): Validator 내부에서 Cardano 원장의 스크립트 목적(Script Purpose)에 대응하는 실행 인터페이스입니다.

하나의 Validator는 여러 핸들러를 포함할 수 있습니다. 따라서 소스 파일 하나와 온체인 스크립트 하나가 반드시 일대일로 대응한다고 생각해서는 안 됩니다.

3 Aiken Validator Handler의 종류

Aiken이 지원하는 명명된 Validator 핸들러는 다음과 같습니다.

Aiken 핸들러 원장 실행 목적 (Script Purpose) 주요 역할
spend Spending 스크립트 주소의 UTxO 소비 검증
mint Minting 네이티브 토큰 발행·소각 검증
withdraw Rewarding 스테이킹 보상 인출 검증
publish Certifying 인증서 관련 작업(위임, 등록 등) 검증
vote Voting CIP-1694 거버넌스 투표 검증
propose Proposing CIP-1694 거버넌스 제안 검증

이 이름들은 Aiken Validator에서 사용하는 명명된 핸들러 이름입니다. 특히 publish는 Aiken의 고유한 명명 방식이며, 원장 차원의 Certifying 목적과 연결됩니다.

⚠️ else 핸들러에 대한 올바른 구분

else는 위 여섯 가지와 동등한 독립적인 원장 목적이 아닙니다. 명시적으로 선언한 목적 핸들러 외의 스크립트 컨텍스트를 처리하는 사용자 정의 핸들러입니다. 일반적인 Validator 개발에서는 목적에 맞는 명명된 핸들러를 우선 사용하는 것이 좋습니다.

4 Blueprint Title의 의미와 Aiken 명명 관례

CIP-0057에서 Validator의 title은 해당 Validator를 설명하는 짧은 문자열입니다.

실무 개발에서는 다음 사항을 명확히 구분해야 합니다.

  1. CIP-0057 표준: title을 해당 검증기를 설명하는 임의의 식별 문자열로 정의합니다. 특정 구분자 형식을 강제하지 않습니다.
  2. Aiken 컴파일러: 소스코드의 Validator를 Blueprint의 Validator 항목으로 생성합니다.
  3. 프로젝트별 식별 관례: 생성 도구에 따라 모듈명, Validator 이름, 목적을 조합한 문자열(예: <모듈>.<검증기>.<핸들러>)을 사용할 수 있습니다.
  4. 실제 확인 기준: 특정 프로젝트에서 사용해야 할 정확한 문자열은 실제 생성된 plutus.json의 validators[].title 값입니다.

예를 들어 다음은 형식을 설명하기 위한 가상의 플레이스홀더 구조입니다.

{
  "validators": [
    {
      "title": "<실제_컴파일러가_생성한_Title>",
      "compiledCode": "<실제_컴파일_산출물>",
      "hash": "<실제_스크립트_해시>"
    }
  ]
}

owner_lock.owner_lock.spend와 같은 문자열은 이해를 돕기 위한 예시로 사용할 수 있지만, 실제 컴파일 결과를 확인하지 않은 상태에서 Aiken의 모든 버전에 적용되는 고정 규칙이라고 설명해서는 안 됩니다. CIP-0057은 이러한 점 구분 형식을 의무화하지 않습니다.

5 단일 목적과 다목적 Validator

하나의 Validator 블록 안에 여러 핸들러를 함께 정의할 수 있습니다.

validator vault {
  spend(
    datum: Option<Datum>,
    redeemer: Redeemer,
    own_ref: OutputReference,
    self: Transaction,
  ) {
    // UTxO 소비 조건 검증
    True
  }

  mint(
    redeemer: Redeemer,
    policy_id: PolicyId,
    self: Transaction,
  ) {
    // 토큰 발행 및 소각 조건 검증
    True
  }
}

이 예시는 개념을 설명하기 위한 구조입니다. 실제 프로젝트에서는 사용 중인 Aiken 버전과 타입 정의에 맞춰 작성해야 합니다.

spend와 mint는 서로 다른 스크립트 목적을 담당합니다. 컴파일 산출물에서 각 목적에 대응하는 Validator 엔트리를 확인하고, 실제 생성된 코드와 해시를 기준으로 오프체인 연동을 구성해야 합니다.

따라서 두 핸들러가 소스에 있다는 사실만으로 특정 Title이나 해시가 어떻게 생성될지 미리 단정하지 않는 것이 중요합니다.

6 오프체인에서 Blueprint Title 사용하기

오프체인 애플리케이션(JavaScript/TypeScript SDK 등)은 Blueprint의 validators 항목을 읽고 필요한 스크립트를 선택할 수 있습니다.

import blueprint from "./plutus.json";

const targetTitle = "<실제_plutus.json에서_확인한_Title>";

const validatorEntry = blueprint.validators.find(
  (validator) => validator.title === targetTitle
);

if (!validatorEntry) {
  throw new Error(`Validator not found: ${targetTitle}`);
}

if (!validatorEntry.compiledCode) {
  throw new Error("Validator compiledCode is missing");
}

if (!validatorEntry.hash) {
  throw new Error("Validator hash is missing");
}

const compiledCode = validatorEntry.compiledCode;
const scriptHash = validatorEntry.hash;

이 예시는 개념적인 JavaScript 코드입니다. 실제 사용 시에는 사용 중인 SDK의 Blueprint 로딩 방식, CBOR 처리 방식 및 파라미터 적용 절차를 확인해야 합니다.

CIP-0057에서 compiledCode와 hash는 선택 필드이지만, compiledCode가 포함된 항목에는 hash도 포함되어야 합니다. 실제 SDK에서는 이 값을 그대로 주소에 사용하는 것이 아니라, 스크립트 버전과 파라미터 적용 여부에 맞는 처리 절차를 거쳐야 합니다.

중요한 실무 원칙은 Title을 추측하지 않는 것입니다. 소스코드의 파일명이나 Validator 선언만 보고 오프체인 문자열을 직접 임의로 작성하기보다, 실제 빌드 산출물에서 확인한 값을 사용해야 합니다.

7 실무에서 발생할 수 있는 위험 상황과 예방 방법

오프체인 연동 과정에서 발생할 수 있는 위험 상황과 이를 방지하기 위한 실무적인 점검 수칙은 다음과 같습니다.

위험 상황 발생 가능한 문제 예방 및 점검 방법
파일명 또는 모듈 구조 변경 생성된 Blueprint 항목 식별자(title)가 달라질 가능성 빌드 후 plutus.json의 validators[].title 재확인
Validator 선언 또는 핸들러 변경 Blueprint 항목의 구성과 데이터 인터페이스 변경 새 Blueprint와 오프체인 연동 코드를 함께 검토
오프체인 코드의 Title 오타 원하는 Validator 항목을 찾지 못해 런타임 오류 발생 실제 Blueprint 값으로 조회하고 누락 예외 처리 추가
오래된 Blueprint 사용 최신 소스코드와 실제 로딩된 스크립트 바이트코드 불일치 빌드 산출물 갱신 확인 및 스크립트 해시 대조

8 핵심 요약

개념 주요 내용
소스코드 계층 모듈(파일) → Validator 선언 → 핸들러 함수(스크립트 목적)
6대 목적 핸들러 spend, mint, withdraw, publish, vote, propose
else 핸들러 명시되지 않은 컨텍스트를 처리하는 사용자 정의 핸들러 (독립 목적 아님)
Blueprint Title CIP-0057상 설명적 식별 문자열 (실제 값은 plutus.json에서 반드시 확인)
오프체인 연동 원칙 Title을 추측하여 하드코딩하지 말고, 실제 빌드 산출물의 값을 조회해 사용

스마트 컨트랙트 개발에서는 온체인 로직 작성뿐 아니라, 이 로직이 컴파일 산출물에서 어떤 식별자로 표현되는지 정확히 이해하고 실제 산출물을 기준으로 오프체인과 연동해야 합니다.

다음 AURA #54에서는 온체인 스크립트의 실행 성능과 네트워크 수수료를 결정하는 핵심 지표인 CPU 및 메모리 실행 예산(Execution Units, ExUnits)의 개념과 예산 관리 방법을 살펴봅니다.


기술적 범위 안내

본 글은 Aiken 컴파일러의 소스코드 구조와 CIP-0057 명세의 매핑 관례를 설명하는 교육용 기술 자료입니다. 본 문서의 작성 과정에서 실제 로컬 컴파일러 실행이나 테스트넷 배포가 완료되었다는 의미는 아닙니다.

이전 아티클 (AURA #52) AURA #52: aiken build와 CIP-0057 Plutus Blueprint의 구조 이해
다음 아티클 (AURA #54) 다음 편 준비 중 (CPU 및 메모리 Execution Units 분석)