A
Aura Core Research SMART CONTRACT TUTORIALS
Home / Smart Contract Tutorials / aura-core-48-aiken-first-project-structure
Cardano Smart Contract Development Series · Part 01 · AURA #48

Aiken 첫 프로젝트 만들기: 프로젝트 구조와 aiken.toml 이해하기

Cardano의 eUTxO 모델을 기반으로 스마트 컨트랙트를 작성하기 위한 Aiken 프로젝트 생성 방법과 기본 디렉터리 구조 및 aiken.toml 설정 가이드

PK
Paul Ko (Cardano Ambassador & DRep)
Published: 2026-11-01 · Series: Developer Tutorial
#Aiken #Cardano #SmartContract #aiken_toml #CIP57
이 글의 검증 범위 이 글은 공식 Aiken 문서를 바탕으로 작성한 개발 입문 안내입니다. 예제 명령은 설명을 위한 것이며, 이 글 자체에서 실제 설치·컴파일·테스트넷 실행을 수행했다는 의미는 아닙니다.

1 Cardano 스마트 컨트랙트 개발, 어디서 시작해야 할까?

Cardano에서 스마트 컨트랙트를 개발하려면 먼저 개발 환경과 프로젝트 구조를 이해해야 합니다.

Cardano는 UTXO 모델을 기반으로 하는 블록체인입니다. 따라서 스마트 컨트랙트 개발에서도 트랜잭션, 입력(Input), 출력(Output), Datum, Redeemer 등의 개념을 이해하는 것이 중요합니다.

이러한 환경에서 Aiken은 Cardano 스마트 컨트랙트를 작성하고 검증하기 위한 프로그래밍 언어이자 개발 도구입니다.

Aiken을 처음 접하는 개발자라면 복잡한 계약부터 작성하기보다 다음 세 가지를 먼저 익히는 것이 좋습니다.

  1. Aiken 프로젝트 생성 방법
  2. 프로젝트 디렉터리 구조
  3. aiken.toml 설정 파일의 역할

이번 글에서는 실제 스마트 컨트랙트를 작성하기 위한 첫 번째 단계로 Aiken 프로젝트를 생성하고 그 구조를 살펴봅니다.

2 Aiken이란 무엇인가?

Aiken은 Cardano 블록체인의 스마트 컨트랙트를 개발하기 위해 만들어진 프로그래밍 언어입니다.

Aiken은 Cardano의 UTXO 기반 스마트 컨트랙트 모델에 맞춰 설계되었으며, 개발자가 계약 로직을 작성하고 테스트하고 컴파일할 수 있는 도구를 제공합니다.

일반적인 개발 흐름은 다음과 같습니다.

Aiken 프로젝트 생성
       |
       v
스마트 컨트랙트 코드 작성
       |
       v
타입 검사 및 테스트
       |
       v
Plutus Blueprint 생성
       |
       v
Off-chain 애플리케이션과 연동
       |
       v
테스트넷 검증

이 과정에서 Aiken CLI는 프로젝트 관리, 검사, 테스트 및 컴파일을 담당합니다.

3 첫 번째 Aiken 프로젝트 만들기

Aiken 공식 Getting Started 문서에서는 aiken new 명령을 이용해 새 프로젝트를 생성하는 방법을 안내합니다.

예를 들어 다음과 같이 실행할 수 있습니다.

aiken new sarangbang/first-validator

프로젝트를 생성한 후 실제 생성된 디렉터리 이름을 확인하고 해당 디렉터리로 이동합니다.

cd first-validator

설치된 Aiken CLI가 정상적으로 실행되는지도 확인할 수 있습니다.

aiken --version

여기서 중요한 점은 프로젝트 생성과 컴파일은 서로 다른 작업이라는 것입니다.

aiken new는 프로젝트의 기본 구조를 생성합니다. 실제 계약 코드의 타입 검사와 테스트, 컴파일은 별도의 명령으로 수행합니다.

4 Aiken 프로젝트의 기본 디렉터리 구조

새 프로젝트에는 일반적으로 다음과 같은 기본 구성 요소가 생성됩니다.

first-validator/
│
├── aiken.toml
├── README.md
│
├── lib/
│   └── 프로젝트 라이브러리 코드
│
└── validators/
    └── 스마트 컨트랙트 코드

각 구성 요소의 역할을 살펴보겠습니다.

4.1 aiken.toml

프로젝트의 이름, 버전, 라이선스, 설명 및 의존성 등을 관리하는 설정 파일입니다. Aiken 프로젝트의 기본적인 정보를 확인하고 관리하는 출발점입니다.

4.2 README.md

프로젝트에 대한 설명을 기록하는 문서입니다. 프로젝트의 목적, 설치 및 실행 방법, 주요 Validator 설명, 테스트 실행 방법, 개발 및 사용 관련 안내 등을 기록하면 좋습니다.

4.3 lib/

프로젝트에서 재사용할 수 있는 라이브러리 코드와 모듈을 배치하는 디렉터리입니다. 여러 Validator에서 공통으로 사용할 데이터 타입이나 보조 함수를 분리하면 코드의 재사용성과 유지보수성을 높일 수 있습니다.

4.4 validators/

스마트 컨트랙트의 Validator 코드를 배치하는 디렉터리입니다. 예를 들어 토큰 발행, 자산 잠금, 소유자 권한 확인 등의 계약 로직을 이곳에 구성할 수 있습니다.

* 프로젝트의 실제 파일 구성은 생성된 프로젝트와 사용 중인 Aiken 버전에 따라 확인해야 합니다.

5 aiken.toml 이해하기

Aiken 프로젝트에서 중요한 파일 중 하나는 aiken.toml입니다. 다음은 프로젝트 설정의 개념을 설명하기 위한 예시입니다.

name = "sarangbang/first-validator"
version = "0.1.0"
licence = "Apache-2.0"
description = "Aiken smart contract learning project"

각 항목의 의미는 다음과 같습니다.

항목 설명
name 프로젝트 식별 이름
version 프로젝트 버전
licence 프로젝트 라이선스 정보
description 프로젝트 설명

위 예시는 설정 파일의 기본 개념을 설명하기 위한 것입니다. 실제 프로젝트에서 사용하는 설정 항목과 형식은 해당 Aiken 버전의 공식 문서를 기준으로 확인해야 합니다.

특히 licence와 license의 표기 차이를 임의로 혼용하지 않는 것이 좋습니다. 프로젝트에 의존성이 필요한 경우에는 Aiken CLI의 패키지 관리 기능을 사용해 추가할 수 있습니다.

6 Standard Library 추가하기

스마트 컨트랙트를 개발하다 보면 자주 사용하는 데이터 타입이나 함수를 직접 구현하는 대신 표준 라이브러리를 활용할 수 있습니다. Aiken Standard Library는 이러한 공통 기능을 제공하는 라이브러리입니다.

공식 문서에서 안내하는 v4 계열 추가 명령의 예시는 다음과 같습니다.

aiken add aiken-lang/stdlib --version v4

여기서 v4는 라이브러리 버전 계열을 지정하는 예시입니다. 실제 설치 가능 여부와 호환성은 사용하는 Aiken 컴파일러 버전에 따라 확인해야 합니다.

의존성을 추가한 후에는 프로젝트 설정 파일과 실제 생성된 파일을 확인하여 어떤 버전이 적용되었는지 점검하는 것이 좋습니다.

7 aiken check와 aiken build의 차이

Aiken 개발에서 자주 사용하는 명령은 aiken check와 aiken build입니다. 두 명령은 목적이 다릅니다.

7.1 aiken check

aiken check

이 명령은 프로젝트의 타입을 검사하고 테스트를 실행합니다. 개발 중 코드의 오류를 발견하고 테스트 결과를 확인할 때 사용합니다. Aiken의 테스트는 계약 로직이 예상한 조건에서 올바르게 동작하는지 확인하는 데 도움이 됩니다.

7.2 aiken build

aiken build

이 명령은 프로젝트를 컴파일하고 Plutus Blueprint 산출물을 생성합니다. 일반적으로 생성되는 주요 산출물은 다음과 같습니다.

plutus.json

이 파일에는 컴파일된 계약과 관련된 Blueprint 정보가 포함됩니다.

명령 주요 목적
aiken check 타입 검사 및 테스트
aiken build 컴파일 및 Blueprint 생성

* 개발 과정에서는 코드 작성과 테스트를 반복한 후 빌드 결과를 확인하는 것이 일반적입니다.

8 Plutus Blueprint란 무엇인가?

Plutus Blueprint는 Cardano 스마트 컨트랙트의 정보를 표준화된 형태로 표현하기 위한 구조입니다.

CIP-0057은 Plutus Contract Blueprint에 대한 표준을 정의합니다. Blueprint는 스마트 컨트랙트의 인터페이스와 관련 정보를 도구 및 애플리케이션이 이해할 수 있도록 표현하는 데 도움을 줍니다.

Aiken의 aiken build 명령으로 생성되는 plutus.json이 이와 관련된 중요한 산출물입니다.

다만 Blueprint 파일이 생성되었다고 해서 스마트 컨트랙트가 자동으로 테스트넷에 배포되거나 실제 트랜잭션이 실행되는 것은 아닙니다. 실제 블록체인에서 계약을 사용하려면 별도의 Off-chain 트랜잭션 구성, 서명, 제출 및 검증 과정이 필요합니다.

9 첫 프로젝트 완성 점검표

Aiken 프로젝트를 처음 생성했다면 다음 항목을 확인해 보세요.

Aiken CLI 설치 및 버전 확인
aiken new 명령으로 프로젝트 생성
실제 프로젝트 디렉터리 확인
aiken.toml 내용 확인
lib/ 디렉터리 확인
validators/ 디렉터리 확인
Standard Library 버전 및 호환성 확인
aiken check 실행
aiken build 실행
생성된 plutus.json 확인

* 아직 실행하지 않은 항목은 완료로 표시하지 마세요.

10 다음 단계: 첫 번째 Spending Validator

이번 글에서는 Aiken 프로젝트의 기본 구조와 설정 파일을 살펴보았습니다. 다음 단계에서는 실제 스마트 컨트랙트 코드를 작성해 보겠습니다.

다음 편에서는 Spending Validator를 이용해 특정 조건에서만 UTXO를 소비할 수 있도록 하는 기본적인 계약 구조를 살펴볼 예정입니다.

특히 소유자의 공개키 해시가 트랜잭션의 extra_signatories에 포함되어 있는지를 확인하는 예제를 통해 Cardano의 검증 모델을 이해해 보겠습니다.

여기서 extra_signatories는 트랜잭션에 포함된 검증 키 해시 목록을 다루는 것이며, Validator가 원시 암호학적 서명 데이터를 직접 검증한다는 뜻은 아닙니다.

공식 참고 자료

이전 아티클 (AURA #47) AuraGrandSynthesis.hs: 47대 코어 아키텍처 대통합과 AI 자율 문명을 위한 5세대 블록체인 완성 선언
다음 아티클 (AURA #49) 다음 편 준비 중 (첫 Spending Validator와 소유자 서명 조건)