App2App을 통한 Klip 연동하기

App2App API의 진행단계

App2App API를 사용하는 단계는 총 3가지 단계로 구성된다.

1. Prepare

BApp에서 어떤 작업을 실행하고 정의하는 단계

인증(auth)을 제외한 나머지는 Klaytn 네트워크(정확히는 Klip Server)에 Transaction을 전송하는 방식으로 진행된다. 각 작업의 종류로는 아래와 같이 5가지가 있다.

1. 인증(auth)
   • 사용자의 Klip 지갑의 EOA를 획득할 때 사용한다.
2. KLAY전송(send_klay)
   • 다른 EOA로 KLAY를 전송할 때 사용한다.
3. 토큰전송(send_token)
   • 다른 EOA로 FT를 전송할 때 사용한다.
4. Card전송(send_card)
   • 다른 EOA로 Card(NFT)를 전송할 때 사용한다.
5. 스마트컨트랙트 실행(executeContract)
   • 지정된 SCA의 메소드를 실행시킬 때 사용한다.

2. Request

Prepare 단계에서 정의한 작업을 수행하는 단계

인증(auth)는 Klip 지갑의 EOA를 가져오는 방식으로 구성되며, 나머지 작업들은 정의한 Transaction에 서명처리를 하는 방식으로 구성된다.

• 앞서 설명했듯이, Prepare 단계에서는 정확히 Klip서버에 처리할 Transaction 정보를 넘겨주는 것이고, Request 단계가 진행되어야 Klip Server에서 Klaytn 네트워크에 트랜잭션을 전송한다.
• 각 지갑의 개인키(계정키)는 klip서버에 암호화되어 저장되어 있기 때문에, Klip서버에 서명 요청을 하는 방식으로만 트랜잭션을 발생시킬 수 있다.
• Prepare 단계에서 응답값으로 받은 인증키(Request Key)를 가지고 요청을 특정하고, 이를 통해 생성한 DeepLink를 통해 모바일 환경에서 서명을 진행하는 방식으로 이루어진다.

3. Result

Requset에서 실시한 작업에 대한 결과를 얻는 단계

GET 요청에 Prepare 단계에서 획득한 인증키(Request Key)를 가지고 결과 데이터를 받아오는 방식으로 구성된다.

• 공통적으로 request_key, expiration_time, status, result를 키값으로 가지고 있다. 이는 각 각 인증키값, 인증키 만료시간, 처리상태(prepared, requested, completed, canceled, error)를 의미한다.
• 인증(auth) 작업의 경우, result에 EOA 값을 받아오고, 나머지 작업의 경우, 발생시킨 트랜잭션(Transaction)의 해시값을 가지고 온다.

+. Get Card Information

Klip EOA의 특정 SCA에 해당하는 Card(NFT)리스트를 사용할 때 사용

Get Card Information 요청의 경우 기존 방식들과 다르게, 지갑을 거치지 않고 바로 Klip Server에 요청하여 정보를 받는다.

API Flow Diagram

위 내용들을 도식화 하면 위와 같은 구성을 가진다.

단계를 크게 두가지로 분류하면, REST API 요청을 하는 prepare, result 단계와 DeepLink를 생성하는 Request를 단계로 구분할 수 있다. 각 단계가 왜 이렇게 작동하는지는 개념에서 설명하였지만, 아래 코드를 보면서 좀 더 확실하게 이해해보자.

코드를 통해 분석 개념 적용해보기

KlipSDK.js 코드를 가지고 위에서 학습한 개념을 적용시켜보자.

1. Prepare

Prepare 객체 내에는 각 작업이 객체 내 메소드로 정의되어있다.

위 캡처를 보면 알 수 있듯이, Prepare 내에는 특정 작업들에 대한 메소드들이 미리 정의되어있다. 각 메소드는 Prepare.<method>의 형식으로 접근하여 실행이 가능하다.
각 메소드를 정상적으로 실행하기 위한 인자들은 klip-sdk npm 문서에서 정확히 확인하면 좋을 것 같다.

2. auth vs 나머지

auth는 단순히 EOA 정보를 받아오기 위한 요청이기 때문에, 요청의 BODY에 transaction 키가 존재하지 않는다.

Prepare 내 메소드들은 모두 POST 메세지를 발송하지만, auth는 트랜잭션(Transaction)을 발생시키지 않기 때문에 transaction 속성을 가지지 않는다.(그래서 인자도 없음)

3. Request

Request 함수는 API요청을 하는 것이 아니라, 인증키(Request Key)를 기반으로 DeepLink를 연동하는 과정이다.

기본적으로 Request는 모바일 환경에서 인증 절차가 이루어지기 때문에 userAgent()를 통하여 os정보를 가져오고 사용자의 모바일 OS환경(Android || IOS)에 맞는 DeepLink를 생성한다.
이후 web2app 함수를 통하여 DeepLink과 자동 연동시킨다. 만약 모바일 환경이 아닐 경우를 대비하여, onUnsupportedEnvironment라는 인자로 실행할 콜백 함수를 전달할 수 있다.

4. getResult, getCardList

getResult 함수는 처리된 트랜잭션(Transaction)의 결과를 받아오는 데 사용되고, getCardList 함수는 특정 EOA의 특정 SCA의 Card(NFT) 리스트를 불러오는 데 사용된다.

각 함수의 인자를 보면 알 수 있듯이 getResult는 App2App 요청에 대한 결과를 인증키(Request Key)를 통하여 확인하고, getCardList의 경우 조회하고자 하는 특정 스마트컨트랙트의 특정 EOA가 보유한 Card(NFT)리스트를 가져온다. 이떄 보통 EOA 인자값의 경우 auth를 통해 받아온 EOA 값을 사용한다.
조회량이 많은 경우, Paging 처리를 하기 위하여 cursor 라는 인자값을 활용할 수 있도록 되어있다.

실제 적용 예제

위를 통해 각 단계의 개념과 동작방식에 대한 이해가 어느정도 될 수 있었다. 그렇다면 실제 코드에서는 어떻게 동작하는 걸까?
지갑을 연동하여 로그인(auth)을 하는 코드를 가지고 이해해보자.

• 예제코드 : Github Link(cic-develop/klaymint_front)

1. prepare

1. prepare.auth() 메소드를 이용하여 res.json()에 저장되어있는 인증키(Request Key)를 가져온다.
2. 이때, expiration_time 키 값을 가지고 만료시간을 State에 저장하는데, 이를 통해 사용자가 제한시간(만료시간) 이내에 Request 절차를 진행할 수 있도록 사용자경험에 활용할 수 있다.

2. Request & getResult

먼저 Request를 발생시키기 전, 브라우저 공급자, 버전 등의 정보를 포함하고 있는 navigator 객체에 접근하여 userAgent(혹은 platform)정보를 통해 OS를 판단한다.
1. 만약 모바일 환경이라면, Request 메소드를 직접 실행하여 DeepLink를 통해 Klip으로 연동되도록 할 수 있다.
2. 이때, mobilePolling 이라는 인터벌을 발생시켜 지속적으로 getResult 함수를 실행해 Request 처리결과를 확인한다.
3. Result값이 completed가 되면, 처리가 정상적으로 완료되었다는 의미이므로 수신받은 EOA, 잔액(balance) 등의 데이터를 저장하여 로그인 처리하고 인터벌을 종료한다.

1. 만약 PC 환경이라면, Request 메소드에서 지원하는 DeepLink를 통해 바로 Klip으로 연동하는 것이 불가능하다.(Klip은 모바일 환경에서만 지원되니깐)
2. 이럴 경우에는 QR스캔을 통하여 DeepLink로 모바일 환경과 연동이 가능하도록 구현할 수 있다.
3. 인증키(Request Key)를 가지고 QRcode를 생성하고, 이후 polling 인터벌을 통해 로그인을 구현하는 방식은 동일하다.

QDL

Q. Klip은 어떤 방식으로 활용할 수 있을까?

A. 기본적으로 Klip Partners에 등록하여 자사의 IP를 활용한 디지털자산을 Klip에 Card(NFT)를 민팅 및 리스팅할 수 있고, Klip에서 지원하는 NFT(Klip drops, Klip Partners)를 거래하는 마켓을 구현할 수 있다.

Klip은 KIP-17(NFT)와 호환되는 어떤 토큰이든 담을 수 있지만, 리스팅(Listing)을 정책적으로 제한(실제로는 있지만, 보여주지 않는다)하고 있기 때문에 Klip Partners에 가입하여 리스팅을 할 수 있는 권한을 얻어야한다.(=SCA 등록)

하지만, Klip지갑이 Klip Partners에 제휴된 거래만 허용한다는 것을 의미하는 것은 아니다. executeContract() 을 이용하여 cypress에 사전 배포된 스마트컨트랙트를 실행하는 것은 가능하기 때문에, 우회적으로 전송처리는 가능하다.

즉, 사용자가 해당 Klip 지갑에 보유한 모든 NFT를 확인할 수 없는 이슈를 제외한다면 일반 klaytn 지갑으로서의 기능도 수행 가능하다.

Q. Klip에서 보유중인 Card(NFT)를 가져오려면 어떻게 해야할까?

A. klipSDK에서 지원하는 getCardList 함수를 이용하면 된다. 단, 특정 SCA에 해당하는 card를 가져올 수 있도록 되어있기 때문에 만약에 EOA계정이 보유한 모든 NFT를 불러오기 위해서는 KAS API를 활용해야한다.)

Q. Klip 연동절차를 간단히 설명하자면?

A. ① Prepare → ② Request → ③ Result 의 절차로 이루어지며, Prepare 단계에서 획득한 인증키(Request Key)를 가지고 Request 단계에서 DeepLink를 통해 모바일 환경에서 구동되는 Klip 인증을 진행한다. 이때 개인키를 통한 서명이 이루어져 실제 메인넷에 트랜잭션이 발생한다. 이후 정상적으로 처리된 결과를 Result 단계에서 받아 Klip 연동 작업이 완료된다.

Q. Klip Card Minting과 KIP-17 기반 Minting은 무엇이 다를까?

A. 기본적으로 Klip Card 또한 KIP-17 표준으로 구현되어있기 때문에 기술적으로는 동일하다고 볼 수 있다.

하지만, Klip Card Minting의 경우 Klip 정책에 의해 Private하게 운영되기 때문에 Klip Partners의 컨트랙트로 발행한 NFT만 Klip지갑 상에 리스팅된다. ① 손쉬운 스마트컨트랙트 배포∙관리 ② Klip 지갑 리스팅 혜택 의 장점이 있다. 단, 현재까지는 테스트넷을 제공하고 있지 않아 메인넷만 사용이 가능하다.

KIP-17 기반 Minting의 경우에는 Klaytn IDE를 통해서 직접 스마트컨트랙트를 구현하고 배포, 관리해야하며 KAS를 통해 API요청을 진행한다. (실제로 사용되는 라이브러리도 다르다)

반면에 Klip Card Minting에서 제공하는 API는 관련 컨텐츠를 업로드만 하면 해당 데이터 저장 및 민팅, 전송, 삭제 등 다양한 기능들을 쉽게 구현할 수 있다. 즉, Klip 사용자들을 대상으로 KAS 기능들의 일부를 편리하게 사용하도록 제공한다고 보면 된다.(지갑을 통한 인증 및 서명에 초점)

좀 더 복잡한 서비스(전송 이력 등)를 만들고자 한다면 KAS를 활용하는 것이 좀 더 자유도가 높다.