(5mins) On-chain History Trace in Luniverse

📘
루니버스 Trace란?
블록체인은 오직 데이터 추가만 가능한 구조이기 때문에, 한 번 블록체인에 저장된 데이터는 수정하거나 삭제를 할 수 없습니다. 이런 특징 덕분에 온체인 데이터에 대한 무결성과 신뢰성을 보장할 수 있어요. 하지만 높은 Gas 수수료와 낮은 처리속도 등, 실제 어플리케이션에 적용하기에 이러한 구조는 진입장벽이 매우 크다는 것이 가장 큰 문제인데요, 이런 문제를 해결하기 위해 루니버스는 Trace를 포함한 여러 API들을 제공하고 있습니다.
Trace 서비스는 사이드체인을 공유 원장으로 활용하여 데이터를 읽고 쓰며, 검증하는 기능을 GUI및 API로 제공합니다. Trace 서비스를 통해 데이터 저장 목적으로 설계된 스마트 컨트랙트를 사용할 수 있으며, 무결성이 필요한 데이터를 타임스탬프와 함께 기록한 후 기록된 데이터를 검증할 수 있습니다.
Trace에 대한 더 자세한 내용을 원하시면 Luniverse Trace 페이지를 방문해보세요!

이번 튜토리얼에서는 Frontend인 Demo Web 코드를 제공합니다. 가장 먼저 루니버스 사이드 체인에 Trace 기능을 연동한 뒤, 예제로 제공된 Demo Web을 구동하고, Trace API를 호출하여 스마트 컨트랙트 기능을 실행합니다.

튜토리얼은 다음 순서에 따라 진행됩니다.

개발 환경 셋팅
루니버스 Trace 관련 설정 진행하기
새로운 데이터 기록하기
추가 데이터 기록하여 최종 상태 변경하기

개발 환경 셋팅

Luniverse Console 가입 및 Testnet 연결

Luniverse Console로 이동하여 회원 가입을 진행합니다.

회원가입이 완료되었다면 아래 링크를 참조하여 Luniverse Testnet에 연결합니다.
Luniverse Testnet 연결 가이드

NodeJS & NPM 설치

NodeJS는 자바스크립트 런타임 환경이며, 아래 공식 홈페이지 링크를 클릭하여 자신의 운영체제에 맞는 파일로 다운로드 및 설치합니다.

(NodeJS 최신 버전 다운로드 받기)

❗️꼭 LTS의 최신 버전으로 받아주세요! 일반 최신 버전은 튜토리얼 진행시 에러가 발생할 수 있습니다.

NodeJS 설치가 완료 되었다면, 버전이 18버전 이상인지 확인합니다. 설치에 포함되어 있는 NPM 버전을 함께 확인할 수 있습니다.

node -v
# v18.16.1
npm -v
# 9.8.1

Visual Studio Code 설치

이 튜토리얼에서는 Visual Studio Code (VS Code)를 사용합니다. 기존에 사용하던 IDE가 없다면 아래 링크를 클릭하여 VS Code 설치를 권장드립니다.

Visual Studio 최신 버전 다운로드 받기

Demo Web 코드 다운로드 받기

아래 Github 링크를 클릭하여 NFT Demo Web 구동을 위한 샘플 코드를 다운로드 받으세요.

[Github]Trace Demo Project

VS Code로 trace-car 폴더를 열면 아래와 같은 파일 구조를 확인하실 수 있습니다.

터미널을 열고 npm 모듈을 설치합니다.(터미널 여는 단축키: ctrl + `)

npm install

VS Code 터미널 창에 아래 명령어를 입력하여 로컬 서버를 실행하세요.

npm run dev

서버가 실행되면 표기된 URL(http://localhost:[port])을 클릭하거나, 웹 브라우저에 해당 주소를 입력하여 접근합니다. 위의 과정이 잘 완료되었다면 아래와 같은 메인 화면이 나타납니다.

2. 루니버스 Trace 관련 설정 진행하기

API 호출을 위한 API Key 설정하기

루니버스 콘솔(https://console.luniverse.io/)에 접속 합니다. Luniverse API Key페이지를 참조하여 API Key를 생성합니다.

💡API key 생성 시 반드시 Trace API 권한을 선택해 주세요.

DEMO 웹의 우측 상단 메뉴에서 AuthToken 메뉴를 클릭하여 발급받은 API Key를 입력한 뒤, [Submit]버튼을 클릭하여 API 인증 토큰을 발급받을 수 있습니다.

💡 관련 코드를 확인해보면 알 수 있듯이, [Submit]버튼을 누르면 Auth API를 호출합니다.

Expiry Value는 생성할 토큰의 유효 기간(초 단위)를 의미합니다. 기본값은 3600초로 되어있으며, 원하는 기간으로 설정할 수 있습니다. (최대 31536000초)

인증 토큰이 발급되면, 이를 설정 파일에 추가해야 합니다.

.env_template 파일 이름을 .env로 변경한 후, 파일을 열어 VITE_AUTH_TOKEN 에 해당하는 값 부분에 위에서 발급 받은 인증 토큰 값을 입력합니다.

Trace Program 생성 및 Program ID 입력하기

Trace Program 생성하기

루니버스 콘솔로 이동하여 Trace > Dashboard > Create Trace 버튼을 클릭하여 새로운 Trace Program을 생성합니다.

Environment는 Testnet Side Chain을 선택합니다. 그리고 원하는 Trace Name을 입력 후 Create 버튼을 클릭합니다.

Trace Program 생성에 대한 상세한 과정은 Trace Service페이지를 참고하시기 바랍니다.

Trace Program ID 확인하기

방금 생성한 TraceDemo에 대한 상세 정보를 Trace Dashboard에서 확인할 수 있습니다.

Luniverse 콘솔에서 Trace > Dashboard > TraceDemo > Information 으로 이동한 후, 방금 생성한 TraceDemo 프로그램의 ID 항목을 복사합니다. 이 값이 Trace Program ID입니다.

Program ID를 복사하여 .env의 VITE_PROGRAM_ID에 입력해주세요.

사용자 이름(User Name) 입력

사용자 이름은 Trace DEMO에서 데이터를 입력할 때 입력한 사람을 구분하는 용도로 사용합니다. 값을 자유롭게 설정할 수 있지만, DEMO환경에서 다른 사용자와 중복을 방지하기 위해 이름 뒤에 4자리 이상의 숫자를 추가해주세요. 설정할 사용자 이름을 .env의 VITE_USER_NAME에 입력해주세요.

// 아래 값은 예시입니다. 실제 입력 값은 아래 값과 입력값이 다를 수 있습니다.
VITE_AUTH_TOKEN = "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJ2ZXIiOiJ2MSIsInRrbiI6ImNmMWM3YjlkODE3YjEwYzYiLCJ0cGUiOiJJQU0iLCJzbHQiOiI1NjgxYmQxNjJlYTgxYzdjIiwiaWF0IjoxNjU4Mzg5NDUzLCJleHAiOjE2NTgzOTMwNTMsImlzcyI6Imx1bnZzOmJhYXM6YXV0aDpzZXJ2aWNlIn0._ChE_3L23dv0_YHlrnWE9JyQ89sqaG1fmERS9Q3tJk6TiGhwee-VbJNpTVKQdVZqcy47yNfJYG2oeidPZazWOg"
VITE_PROGRAM_ID = "5560136422332062785"
VITE_USER_NAME = "Damon3726"

API Key에 IP 등록하기

이제 데모 페이지를 다시 열고 상단 메뉴의 MyPage를 클릭 하면, 에러 메세지가 나타난 것 확인할 수 있습니다. 이 에러는 현재 IP주소의 접근이 허용되지 않았기 때문에 발생한 에러입니다. 이를 해결하기 위해 현재 IP주소를 whitelist에 등록하겠습니다. 먼저, 에러 메세지에 나온 IP 주소를 복사해주세요.

다시 콘솔로 돌아와 이전에 생성한 API Key의 IP Whitelists 탭으로 이동합니다. 그리고 Register IP Whitelist 버튼을 클릭해주세요.

이전에 복사한 IP 주소를 입력하고 Create 버튼을 눌러 등록해주세요.

위 과정이 성공적으로 진행 됐다면 아래와 같이 아이템 페이지가 나타납니다. (새로 생성한 Trace Program 이라면 아이템 카드는 보이지 않을 수 있습니다.)

3. 새로운 데이터 기록하기

이제 모든 세팅이 완료되었습니다! 이제 Trace로 어떤 기능을 만들 수 있는지 본격적으로 체험 해볼까요?

데이터를 블록체인에 기록하기에 앞서, Trace DEMO가 어떻게 동작하게 될 지 시퀀스 다이어그램으로 먼저 살펴보겠습니다.

유저는 Create Page에서 필요한 데이터를 입력하고 전송 버튼을 클릭한다.
입력한 데이터를 JSON 형식으로 변환한다.
Trace API를 이용하여 Create 이벤트 생성 요청을 보낸다.
요청에 대한 응답이 도착하면 성공 여부를 확인한다.
만약 이벤트 생성이 성공 했다면, 유저에게 성공 메세지를 표시한다.
메세지를 닫으면 MyPage로 이동한다.
만약 이벤트 생성이 실패 했다면, 유저에게 실패 메세지를 표시한다.
메세지를 닫으면 다시 Items Page로 이동한다.

위 과정을 실제로 실행해보겠습니다. DEMO 웹 페이지를 열고, 상단 메뉴바에서 Items를 클릭하여 페이지를 이동합니다. 첫 번째에 위치한 플러스(⨁) 카드를 클릭하고 필요한 데이터를 모두 입력합니다.

Owner 필드는 Configurations에서 설정한 사용자 이름으로 자동 입력됩니다.

새로운 아이템이 성공적으로 생성되면 MyPage로 이동하여 새로 생성된 아이템 카드를 확인할 수 있습니다.
아이템 카드를 클릭하면 상세 정보 페이지로 이동하며 생성 정보를 확인할 수 있습니다.

API가 호출되면 실제 체인에 배포된 스마트 컨트랙트를 실행하여 데이터 기록을 위한 트랜잭션이 발생하게 됩니다. 루니버스 스캔에서 온체인 데이터를 확인해볼 수 있습니다. 아이템 상세 정보 페이지에서 사이드 스캔 링크를 클릭해보세요!

4. 추가 데이터 기록하여 최종 상태 변경하기

차량 이력에 대한 최초 데이터가 등록 되었다면, 해당 차량에 추가 데이터를 기록하여 최종 상태를 변경해보도록 하겠습니다. 아이템 정보 업데이트 과정은 블록체인에 이미 기록된 데이터를 변경하는 것이 아니라, 데이터의 변경 히스토리를 추가하여 최종 상태를 변경하는 과정입니다. 따라서 구현 과정은 이전 과정과 거의 동일하며, 주요 차이점은 생성하는 이벤트 이름이 다르다는 것입니다.

유저는 Update Page에서 필요한 데이터를 입력하고 전송 버튼을 클릭한다.
입력한 데이터를 JSON 형식으로 변환한다.
Trace API를 이용하여 Update 이벤트 생성 요청을 보낸다.
요청에 대한 응답이 도착하면 성공 여부를 확인한다.
만약 이벤트 생성이 성공 했다면, 유저에게 성공 메세지를 표시한다.
메세지를 닫으면 Item Info Page로 이동한다.
만약 이벤트 생성이 실패 했다면, 유저에게 실패 메세지를 표시한다.
메세지를 닫으면 다시 Items Page로 이동한다.

위 과정을 실제로 실행해보겠습니다. 아이템 상세 정보 페이지(Item Info Page)에서 Update 버튼을 클릭하여 Update Page로 이동합니다. 원하는 데이터를 자유롭게 작성하고 전송 버튼을 누릅니다. 정보 업데이트가 성공적으로 완료되었다면, 히스토리 박스가 추가된 것을 확인할 수 있습니다.

추가된 이력은 사이드 스캔에서도 확인할 수 있습니다. 히스토리 박스 안에 사이드 스캔 링크를 클릭하여 업데이트한 데이터가 정상적으로 저장 되었는지 확인해보세요.

아이템 정보가 업데이트 된 후에도 이전에 기록한 기록은 블록체인에 정상적으로 남아있습니다. 아이템 상세 페이지의 Created 히스토리 박스에서 사이드 스캔 링크를 클릭해서 확인해보세요!

축하합니다, Trace car 튜토리얼을 성공적으로 마쳤어요! 🎉 도움이 많이 되셨다면 다른 튜토리얼도 준비되어 있으니 꼭 확인해보세요!

📘루니버스 Trace란?