기술적 범위 안내 본 글은 Aiken의 빌드 시스템과 CIP-0057 Plutus Blueprint의 구조를 설명하는 교육용 기술 자료입니다. 실제 로컬 Aiken 컴파일, 자동화 테스트 실행 또는 테스트넷 트랜잭션 제출이 완료되었다는 의미는 아닙니다. JSON과 해시 관련 예시는 구조를 설명하기 위한 것이며, 실제 프로젝트에서 생성된 컴파일 결과값이 아닙니다.
1 이번 글에서 배울 것
AURA #49~#51에서는 소유자 서명을 검증하는 Spending Validator(owner_lock.ak)를 작성하고, 타입 검사 및 단위 테스트(aiken check)를 통해 로컬 환경에서 로직을 검증하는 방법을 살펴봤습니다.
하지만 단위 테스트가 통과했다고 해서 스마트 컨트랙트가 온체인에서 즉시 동작할 수 있는 것은 아닙니다.
작성된 Aiken 소스코드는 UPLC(Untyped Plutus Core) 프로그램으로 컴파일되어야 합니다. 컴파일된 프로그램은 Flat 직렬화와 CBOR 인코딩을 거쳐 스크립트 아티팩트로 만들어집니다. 또한 오프체인 애플리케이션이 스크립트와 Datum, Redeemer의 구조를 이해할 수 있도록 표준화된 인터페이스 명세도 필요합니다.
Aiken에서 프로젝트 컴파일을 수행하는 명령이 바로 aiken build입니다.
여기서 aiken check와 aiken build의 역할을 구분해야 합니다.
aiken check: 프로젝트의 타입 검사와 내장 테스트를 수행합니다.aiken build: 온체인 스크립트를 컴파일하고 Plutus Blueprint 등의 빌드 산출물을 생성합니다.
이번 글에서는 다음 내용을 다룹니다.
aiken build의 역할과 프로젝트 산출물- Cardano 스마트 컨트랙트 인터페이스 표준인 CIP-0057의 목적
- 핵심 산출물인
plutus.json의 내부 구조 - Plutus Language Tag와 Script Hash 계산 원리
- Script Hash와 실제 온체인 주소의 관계
- Blueprint 빌드와 온체인 상호작용의 차이
- 빌드 성공이 테스트넷 제출 성공을 보장하지 않는 이유
2 aiken build의 역할과 산출물
Aiken 프로젝트 루트에서 다음 명령을 실행합니다.
aiken build
컴파일러는 프로젝트 소스코드를 분석하고 UPLC 프로그램으로 컴파일한 뒤, 직렬화된 스크립트와 인터페이스 정보를 포함하는 Blueprint를 생성합니다.
프로젝트의 기본적인 디렉터리 구조는 다음과 같이 이해할 수 있습니다.
owner_lock/
├── aiken.toml
├── plutus.json
├── build/
└── validators/
└── owner_lock.ak
각 항목의 역할은 다음과 같습니다.
aiken.toml: 프로젝트 이름, 버전, 의존성 및 컴파일 관련 설정을 관리하는 프로젝트 설정 파일입니다.validators/: 온체인 검증기 소스코드를 보관하는 디렉터리입니다.plutus.json: 컴파일된 Validator 정보와 데이터 스키마를 담는 CIP-0057 Plutus Blueprint 산출물입니다.build/: 컴파일 과정에서 생성되는 빌드 관련 산출물과 가져온 의존성 자료가 위치하는 디렉터리입니다. 세부 구조는 Aiken 버전과 빌드 환경에 따라 달라질 수 있습니다.
이 가운데 오프체인 애플리케이션과 개발 도구가 활용하는 핵심 명세 파일이 plutus.json입니다.
중요한 점은 plutus.json이 단순한 프로젝트 설명 파일이 아니라는 것입니다. 컴파일된 스크립트, 해시, Datum 및 Redeemer의 데이터 구조와 같은 정보를 기계가 읽을 수 있는 형태로 담고 있습니다.
3 CIP-0057 Plutus Blueprint의 목적
스마트 컨트랙트를 실제 dApp으로 구축할 때 개발자가 마주치는 문제 중 하나는 온체인 코드와 오프체인 코드 사이의 인터페이스 규격을 일치시키는 작업입니다.
온체인 Validator는 Datum과 Redeemer를 특정 데이터 구조로 해석합니다. 반면 지갑, 프론트엔드, 트랜잭션 빌더와 같은 오프체인 애플리케이션은 해당 데이터를 별도로 구성하고 직렬화해야 합니다.
양쪽의 데이터 구조가 일치하지 않으면 스크립트 실행 과정에서 오류가 발생할 수 있습니다.
이러한 문제를 줄이기 위해 제안된 표준이 CIP-0057 (Plutus Contract Blueprint)입니다.
CIP-0057은 웹 개발의 OpenAPI와 유사하게 스마트 컨트랙트의 인터페이스와 관련 정보를 기계가 읽을 수 있는 JSON 형식으로 표현합니다.
CIP-0057의 주요 목적
① 기계 판독 가능한 인터페이스 명세
Validator가 사용하는 Datum, Redeemer, 파라미터 등의 데이터 구조를 명시합니다. 오프체인 개발자는 이 정보를 활용하여 입력 데이터의 형태를 확인하고 적절한 직렬화 코드를 구성할 수 있습니다.
② 도구 간 상호운용성 지원
CIP-0057을 지원하거나 구현한 오프체인 개발 도구(예: Lucid, Mesh SDK, PyCardano 등)가 공통된 명세 형식으로 스크립트와 데이터 스키마를 해석할 수 있도록 돕습니다. 다만 모든 도구가 Blueprint를 동일한 방식으로 자동 처리하는 것은 아니므로, 실제 사용 전에는 각 도구의 Blueprint 지원 범위와 버전을 확인해야 합니다.
③ 자동화와 통합 지원
Blueprint는 데이터 직렬화·역직렬화 코드 생성, 문서화, 개발 도구 통합 및 dApp 프론트엔드 연동 자동화에 활용될 수 있습니다.
다만 Blueprint를 프로젝트의 모든 정보를 대체하는 절대적인 단일 진실 공급원으로 이해해서는 안 됩니다.
Blueprint는 컴파일 산출물과 컨트랙트 인터페이스를 표준화된 방식으로 표현하는 명세서입니다. 실제 동작을 이해하려면 원본 소스코드, 컴파일러 버전, 네트워크의 Ledger 규칙 및 오프체인 구현도 함께 확인해야 합니다.
4 plutus.json의 구조 분석
CIP-0057 Blueprint는 다음과 같은 최상위 구조를 가집니다.
{
"preamble": {},
"validators": [],
"definitions": {}
}
각 항목의 역할을 살펴보겠습니다.
중요: 아래 JSON은 구조를 설명하기 위한 교육용 플레이스홀더입니다. 특정 Aiken 프로젝트에서 실제 컴파일을 수행하여 생성한 결과가 아닙니다.
① preamble: 프로젝트 전역 메타데이터
preamble에는 Blueprint를 생성한 프로젝트와 컴파일 환경에 대한 정보가 기록됩니다.
{
"title": "my_project/owner_lock",
"description": "Aiken contracts for owner lock",
"version": "1.0.0",
"plutusVersion": "v3",
"compiler": {
"name": "Aiken",
"version": "<컴파일러_버전>"
},
"license": "Apache-2.0"
}
주요 필드는 다음과 같습니다.
title: Blueprint 문서 또는 프로젝트를 식별하는 제목입니다.description: 프로젝트에 대한 설명입니다.version: 프로젝트의 버전 정보입니다.plutusVersion: 해당 Blueprint의 Plutus 언어 버전을 표시합니다.compiler: 컴파일러 이름과 버전 정보를 기록합니다.license: 프로젝트 라이선스 정보를 표시합니다.
plutusVersion은 스크립트가 어떤 Plutus 언어 환경을 대상으로 하는지 이해하는 데 중요합니다.
본 시리즈에서 사용하는 owner_lock 예제는 Plutus V3를 대상으로 설명합니다. Plutus V4가 Ledger에 정의되어 있다는 사실과 특정 Aiken 컴파일러가 V4를 지원한다는 사실은 구분해야 합니다. 실제 컴파일 시에는 사용하는 Aiken 버전과 대상 네트워크의 지원 여부를 확인해야 합니다.
② validators: 검증기 명세 목록
validators 배열에는 프로젝트에서 정의한 Validator에 관한 정보가 기록됩니다.
{
"validators": [
{
"title": "<검증기_제목>",
"datum": {
"title": "datum",
"schema": {
"$ref": "#/definitions/<Datum_스키마>"
}
},
"redeemer": {
"title": "redeemer",
"schema": {
"$ref": "#/definitions/<Redeemer_스키마>"
}
},
"compiledCode": "<CBOR_인코딩된_Flat_스크립트>",
"hash": "<스크립트_해시>"
}
]
}
주요 필드는 다음과 같습니다.
title: Validator를 식별하는 설명적인 이름입니다. 생성 도구에 따라 모듈명, Validator 이름, 목적을 조합하는 명명 관례가 사용될 수 있습니다.datum: Validator가 사용하는 Datum의 데이터 스키마를 가리킵니다.redeemer: Validator가 사용하는 Redeemer의 데이터 스키마를 가리킵니다.compiledCode: UPLC 프로그램을 Flat 형식으로 직렬화한 후 CBOR 인코딩한 스크립트 바이트열을 16진수 문자열로 표현한 것입니다.hash: 해당 스크립트에 대응하는 28바이트 Script Hash를 16진수로 표현한 값입니다.
여기서 compiledCode를 일반적인 소스코드나 단순한 텍스트로 이해해서는 안 됩니다. 실제 온체인 스크립트 실행에 사용되는 직렬화된 스크립트 아티팩트입니다.
③ definitions: 데이터 스키마 레지스트리
definitions는 Datum, Redeemer 및 기타 사용자 정의 데이터 타입의 스키마를 모아 재사용할 수 있도록 하는 영역입니다.
예를 들어 Aiken에서 다음과 같은 데이터 타입을 정의했다고 가정해 보겠습니다.
pub type Datum {
owner: VerificationKeyHash,
}
pub type Redeemer {
Unlock
}
Blueprint는 이러한 데이터 구조를 기계가 읽을 수 있는 스키마로 표현하고, Validator의 datum 및 redeemer 필드에서 참조할 수 있도록 합니다.
오프체인 도구는 이 스키마를 활용하여 애플리케이션의 데이터를 올바른 Plutus Data 형식으로 구성할 수 있습니다.
definitions의 구체적인 내용은 프로젝트에서 사용하는 데이터 타입과 생성되는 스키마에 따라 달라집니다. 모든 프로젝트가 동일한 항목을 가지는 것은 아닙니다.
5 Script Hash 계산 원리와 스크립트 주소
Cardano 스마트 컨트랙트를 이해할 때 중요한 질문 중 하나는 다음과 같습니다.
컴파일된 스크립트는 어떻게 Script Hash가 되고, 이 해시가 어떻게 스크립트 주소에 사용될까요?
① Plutus Language Tag
Cardano Ledger는 서로 다른 Plutus 스크립트 언어 버전을 구분해야 합니다. 이를 위해 스크립트 해시 계산 시 언어 식별 태그(Language Tag)를 사용합니다.
| 언어 버전 | Language Tag |
|---|---|
| Plutus V1 | 0x01 |
| Plutus V2 | 0x02 |
| Plutus V3 | 0x03 |
| Plutus V4 | 0x04 |
이 값은 스크립트의 언어 버전을 구분하기 위한 식별 정보입니다.
Plutus V4의 Ledger 지원과 특정 개발 도구 또는 컴파일러의 V4 지원 여부는 별도로 확인해야 합니다.
② Script Hash 계산
Plutus 스크립트의 해시는 단순히 UPLC 소스 표현을 해싱하는 것이 아닙니다.
Flat 직렬화와 CBOR 인코딩을 거친 스크립트 바이트열 앞에 해당 언어의 식별 태그를 결합한 다음 Blake2b-224 해시를 계산합니다.
Plutus V3의 개념적인 계산식은 다음과 같습니다.
여기서 serialized_script는 Flat 직렬화된 UPLC 프로그램을 CBOR로 인코딩한 스크립트 바이트열입니다. Blueprint의 compiledCode에 기록된 16진수 문자열을 바이트로 해석한 값에 해당합니다.
계산 과정은 다음과 같습니다.
[Aiken 소스코드]
|
v
[UPLC 프로그램으로 컴파일]
|
v
[Flat 직렬화]
|
v
[CBOR 인코딩]
|
v
[Language Tag 결합]
|
v
[Blake2b-224 해싱]
|
v
[28바이트 Script Hash]
따라서 소스코드 변경으로 최종 컴파일된 직렬화 스크립트가 달라지면 Script Hash도 달라집니다.
또한 Plutus 언어 버전이 달라지면 Language Tag가 달라지므로 동일한 스크립트 바이트열이라도 해시 결과가 달라질 수 있습니다.
③ Script Hash에서 Script Address로
Script Hash가 생성되었다고 해서 그것이 곧바로 완성된 Cardano 주소가 되는 것은 아닙니다.
스크립트 주소를 구성하는 과정에는 다음 요소가 관여합니다.
- Payment Credential: 28바이트 Script Hash가 스크립트 결제 자격 증명으로 사용됩니다.
- 주소 유형 및 네트워크 식별 정보: 주소 헤더에는 결제 자격 증명 유형과 네트워크 식별 정보가 반영됩니다.
- 선택적인 Stake Credential: 주소 유형에 따라 스테이킹 자격 증명이 추가될 수 있습니다.
- Bech32 인코딩: 완성된 주소 바이트열을 사람이 읽을 수 있는 문자열로 인코딩합니다.
개념적인 구조는 다음과 같습니다.
[Script Hash]
|
v
[Payment Credential]
|
+---- [주소 유형]
|
+---- [Network ID]
|
+---- [선택적인 Stake Credential]
|
v
[주소 바이트열]
|
v
[Bech32 인코딩]
|
v
[Script Address]
테스트넷 주소는 addr_test1... 형태로, 메인넷 주소는 일반적으로 addr1... 형태로 표현됩니다.
다만 주소는 Script Hash만으로 구성되는 것이 아닙니다. 주소 유형과 네트워크 식별 정보, 선택적인 Stake Credential에 따라 최종 주소가 달라집니다.
6 Blueprint 빌드와 실제 온체인 상호작용의 차이
aiken build를 실행하여 plutus.json이 정상적으로 생성되었다고 해서 스마트 컨트랙트가 블록체인에 등록되거나 배포된 것은 아닙니다.
Cardano의 eUTxO 모델은 계정 기반 블록체인과 다른 방식으로 스마트 컨트랙트를 사용합니다.
Cardano에서는 스크립트 해시를 기반으로 스크립트 주소를 도출할 수 있습니다. 해당 주소로 자산을 보내면 스크립트가 소비 조건을 결정하는 UTxO를 만들 수 있습니다.
이 과정에서 스크립트 바이너리를 별도의 전역 컨트랙트 저장소에 사전 등록해야만 하는 것은 아닙니다.
| 단계 | 수행 환경 | 주요 작업 | 결과 |
|---|---|---|---|
| Blueprint 빌드 | 로컬 개발 환경 | aiken build 실행 |
plutus.json 생성 |
| 자산 잠금(Locking) | Cardano 네트워크 | 스크립트 주소로 자산 전송 및 Datum 설정 | 스크립트 UTxO 생성 |
| 자산 인출(Spending) | Cardano 네트워크 | Redeemer와 필요한 스크립트 및 증거 제출 | Validator 실행 및 원장 검증 |
| Reference Script 활용 | Cardano 네트워크 | 스크립트를 포함한 UTxO를 Reference Input으로 참조 | 반복적인 스크립트 본문 제출 부담 감소 |
① Datum Hash와 Inline Datum의 차이
스크립트 주소에 자산을 보낼 때 Datum을 설정하는 방법에는 중요한 차이가 있습니다.
Datum Hash 방식
출력에는 Datum 데이터 자체가 아니라 Datum Hash가 기록됩니다. 실제 Datum 데이터는 소비 트랜잭션에서 제공되어야 합니다. 출력에 기록된 해시와 제공된 Datum 데이터가 일치해야 합니다.
Inline Datum 방식
Datum 데이터 자체가 출력에 포함됩니다. 소비 트랜잭션에서 해당 출력의 Datum을 직접 참조할 수 있습니다. 데이터가 출력에 포함되므로 UTxO 크기와 최소 UTxO 요구량에도 영향을 줄 수 있습니다.
두 방식은 데이터가 원장 출력에 기록되는 형태가 다릅니다. 실제 dApp 설계에서는 데이터 크기, 비용, 조회 방식 및 소비 트랜잭션의 구조를 함께 고려해야 합니다.
② CIP-0033 Reference Script의 올바른 이해
CIP-0033은 Reference Script 기능을 정의합니다.
일반적인 스크립트 사용 방식에서는 소비 트랜잭션에 스크립트 본문을 직접 포함해야 할 수 있습니다. Reference Script를 사용하면 특정 UTxO에 포함된 스크립트를 다른 트랜잭션이 Reference Input으로 참조할 수 있습니다.
이를 통해 반복적인 스크립트 본문 제출에 따른 트랜잭션 크기 부담을 줄일 수 있습니다.
그러나 Reference Script는 영구적인 게시물이 아닙니다.
스크립트를 담고 있는 UTxO가 다른 트랜잭션에 의해 소비되면 해당 Reference Script도 그 UTxO와 함께 원장에서 사라집니다.
따라서 Reference Script는 영구 저장소가 아니라 UTxO의 생명주기에 종속되는 온체인 참조 기능으로 이해해야 합니다.
또한 Reference Script는 모든 스마트 컨트랙트에 반드시 필요한 배포 절차가 아니라, 사용 목적과 비용 구조에 따라 선택하는 기능입니다.
7 빌드 성공이 테스트넷 제출 성공을 보장하지 않는 이유
aiken build가 오류 없이 완료되었다는 것은 소스코드가 컴파일되고 Blueprint 산출물이 생성되었다는 의미입니다.
그러나 이것이 실제 네트워크에서 트랜잭션이 성공한다는 보장은 아닙니다.
실제 Cardano 네트워크에서는 컴파일 단계와 별개로 원장 검증 규칙과 프로토콜 파라미터가 적용됩니다.
① 실행 예산(ExUnits) 초과
Plutus 스크립트 실행에는 CPU와 메모리 사용량을 나타내는 Execution Units(ExUnits)이 적용됩니다.
트랜잭션에 설정된 실행 예산이 프로토콜에서 허용하는 한도를 초과하면 원장 검증 규칙에 따라 트랜잭션이 거부될 수 있습니다.
이는 스크립트의 논리적 조건이 False를 반환하는 문제와 구분해야 합니다.
② 스크립트 평가 실패와 담보(Collateral)
실행 예산 범위 안에서 스크립트가 실행되더라도 Validator의 조건을 만족하지 못하면 Phase-2 검증이 실패할 수 있습니다.
이 경우 트랜잭션은 무효 처리되며, 원장의 담보 규칙에 따라 제출자가 제공한 Collateral이 소비될 수 있습니다.
실제 담보 소비량은 담보 설정과 Collateral Return 등 관련 원장 규칙에 따라 결정됩니다. 따라서 모든 경우에 담보 입력 전체가 동일한 방식으로 몰수된다고 단정해서는 안 됩니다.
③ 트랜잭션 크기 제한
프로토콜 파라미터에는 트랜잭션 전체 크기에 대한 제한이 있습니다.
스크립트, Datum, Redeemer, 입력 및 출력 등이 커지면 트랜잭션이 허용된 크기를 초과할 수 있습니다.
Reference Script는 이러한 부담을 줄이는 방법 중 하나이지만, 모든 크기 문제를 자동으로 해결하는 것은 아닙니다.
④ 최소 UTxO 요구량
Cardano 원장은 UTxO를 생성할 때 최소 ADA 요구량을 적용합니다.
스크립트 주소에 자산을 전송하는 경우에도 해당 출력이 최소 UTxO 규칙을 충족해야 합니다.
필요한 최소량은 프로토콜 파라미터와 출력의 크기 및 구성에 따라 달라집니다.
⑤ 오프체인 데이터 직렬화 불일치
Blueprint의 스키마와 오프체인 애플리케이션이 실제로 생성하는 Datum 또는 Redeemer의 직렬화 구조가 일치하지 않을 수 있습니다.
이 경우 온체인 Validator가 데이터를 기대한 형태로 해석하지 못해 평가에 실패할 수 있습니다.
따라서 Blueprint를 참고하는 것만으로 직렬화 정확성이 자동 보장되는 것은 아닙니다. 실제 오프체인 구현과 테스트를 통해 데이터 구조가 일치하는지 확인해야 합니다.
다음 개발 단계
빌드 이후에는 다음 단계가 이어집니다.
- AURA #53: Validator, 모듈 및 핸들러 이름과 Blueprint Title 매핑
- AURA #54: CPU 및 메모리 실행 예산(ExUnits) 분석
- AURA #55: 오프체인 트랜잭션 구성과 CBOR 직렬화
- AURA #56: Preprod 테스트넷에서 실제 트랜잭션 상호작용 및 검증
이 과정은 서로 다른 검증 목적을 갖습니다. 컴파일 성공, 단위 테스트 통과, 오프체인 트랜잭션 구성, 원장 검증 및 테스트넷 제출은 각각 구분해서 확인해야 합니다.
8 핵심 요약
| 개념 | 핵심 내용 |
|---|---|
aiken check |
타입 검사 및 내장 단위 테스트 수행 |
aiken build |
소스코드를 컴파일하고 Blueprint 산출물 생성 |
plutus.json |
컴파일된 스크립트와 인터페이스 스키마를 표현하는 CIP-0057 명세 파일 |
compiledCode |
Flat 직렬화 및 CBOR 인코딩된 UPLC 스크립트 바이트열의 16진수 표현 |
Script Hash |
Plutus Language Tag와 직렬화 스크립트를 결합해 계산하는 Blake2b-224 해시 |
Script Address |
Script Hash를 Payment Credential로 사용하고 주소 유형과 네트워크 정보를 반영한 주소 |
Reference Script |
UTxO에 포함되어 Reference Input으로 참조되는 선택적 스크립트 기능 |
빌드와 배포 |
빌드는 로컬 컴파일 산출물 생성이며, 온체인 상호작용은 실제 트랜잭션을 통해 발생 |
이번 글에서는 Aiken 소스코드가 어떻게 컴파일되고, CIP-0057 Blueprint가 온체인과 오프체인 개발 사이의 인터페이스를 연결하는지 살펴봤습니다.
다음 AURA #53에서는 plutus.json의 validators 배열에 기록되는 Validator Title과 모듈·핸들러 명명 규칙을 분석하고, 이러한 정보가 실제 dApp 통합에 어떤 영향을 주는지 알아보겠습니다.
본 글은 Aiken 빌드 시스템과 CIP-0057 Plutus Blueprint 표준의 구조를 설명하는 교육용 기술 자료입니다. 본 문서의 작성 과정에서 실제 Aiken 컴파일, 자동화 테스트 실행 또는 테스트넷 배포가 완료되었다는 의미는 아닙니다.