Wallet Provider

1. 시작하기

최신 버전

• npm: https://www.npmjs.com/package/@linenext/dapp-portal-sdk/v/1.6.0
• cdn: https://static.kaiawallet.io/js/dapp-portal-sdk-1.6.0.js

SDK 접근 권한(clientId & clientSecret) 발급 방법

Unifi Apps SDK를 연동하려면 Unifi 팀으로부터 clientId와 clientSecret을 발급받아야 합니다.

단계:

1. Unifi Apps 신청서 제출
2. 안내에 따라 Unifi Apps SDK 이용약관을 검토하고 제출하세요.
3. 제출한 이메일을 통해 clientId와 clientSecret을 발급받습니다.

경고

clientSecret을 절대 공개적으로 노출하지 마세요.
노출된 경우, Tech Support를 통해 재발급을 요청하세요.

프로젝트 설정 & 도메인 등록

• clientId는 도메인이 등록되어야만 활성화됩니다.
  
  • 테스트 목적으로는 http://localhost:3000을 사용할 수 있습니다.
  • 외부 테스트 도메인의 경우, Tech Support 또는 이메일을 통해 화이트리스트 등록을 요청하세요.
• paymentProvider를 통한 결제에는 유효한 clientSecret이 필요합니다.

SDK 설치

npm, yarn, 또는 pnpm으로 SDK를 설치하세요.

npm install @linenext/dapp-portal-sdk
# or
yarn add @linenext/dapp-portal-sdk
# or
pnpm add @linenext/dapp-portal-sdk

2. SDK 초기화

SDK 초기화하기

Unifi Apps가 로드될 때마다 반드시 SDK를 초기화해야 합니다.

import DappPortalSDK from '@linenext/dapp-portal-sdk'
 
const sdk = await DappPortalSDK.init({
  clientId: '<CLIENT_ID>',
  chainId: '1001', // or '8217' for mainnet
});

파라미터

Name	Type	Description
clientId*required	string	SDK 신청 시 발급된 clientId
chainId	string	기본값은 1001(테스트넷)입니다. 개발 후 메인넷을 사용하려면 값을 8217(메인넷)로 설정하세요.

응답

DappPortalSDK 객체를 반환하며, 이를 통해 다음 메서드들을 호출할 수 있습니다.

경고

LINE MINI App 및 LINE Login LIFF 버전 참고 사항

• DappPortalSDK.init()을 호출하기 전에 liff.init()을 호출하세요.
• LINE MINI App 또는 LINE Login LIFF 진입 시 지갑 연결(connectWallet)을 트리거하지 마세요. 필요할 때(예: 아이템 구매, 온체인 리워드)에만 연결하세요.
• 이렇게 하면 LINE을 통한 활성 사용자 추적과 기여도 측정을 정확하게 할 수 있습니다.

팁

모범 사례

• SDK는 한 번만 초기화하고 DappPortalSDK 인스턴스를 싱글턴으로 관리하세요.
• DappPortalSDK.init()을 여러 번 호출하지 마세요—예기치 않은 동작이나 오작동을 일으킬 수 있습니다.

기본적으로 싱글턴 사용을 강제하지 않습니다. 이는 다중 구성 설정(예: 하나의 앱에서 테스트넷과 메인넷을 함께 사용)을 지원하기 위함입니다. 그러한 경우에는 구성마다 하나의 싱글턴 인스턴스(예: 테스트넷용 하나, 메인넷용 하나)를 관리하세요.

WalletProvider는 EIP-1193 표준을 따르며, 해당 표준에 정의된 EventEmitter 인터페이스를 지원합니다.

sdk.getWalletProvider()

walletProvider를 초기화하여 개발자가 다양한 지갑 기능을 사용할 수 있도록 합니다.

const walletProvider = sdk.getWalletProvider();

파라미터

• N/A

응답

WalletProvider

walletProvider.getWalletType()

현재 연결된 지갑의 타입을 반환합니다.

const walletType = walletProvider.getWalletType();

파라미터

• N/A
  

응답

enum WalletType {
    Web = "Web",
    Liff = "Liff",
    Extension = "Extension",
    Mobile = "Mobile",
    OKX = "OKX",
    BITGET = "BITGET"
}

walletProvider.request()

이 함수는 요청 시 JSON-RPC API 형식을 제공합니다. 체인의 정상 상태를 조회하거나 지갑으로 트랜잭션에 서명하는 요청을 보낼 수 있습니다. 지갑 연결 전에 요청을 보내면, 사용자에게 연결할 지갑 타입을 선택하는 화면이 표시됩니다.

사용 가능한 Kaia 관련 메서드와 그 파라미터, 대응하는 응답은 아래 표에서 확인할 수 있습니다. 표에 포함되지 않은 RPC 메서드는 체인 노드로 직접 요청되며, Kaia 문서의 RPC API Reference를 참고하세요.

const getAccount = async() => {
   const accounts = await walletProvider.request({ method: 'kaia_accounts' }) as string[]; 
   return accounts[0]; 
} 
 
const requestAccount = async () => {
   const addresses = await walletProvider.request({ method: 'kaia_requestAccounts' }) as string[];
   return addresses[0];
}
 
const connectAndSign = async (msg:string) => {
   const [account, signature] = await walletProvider.request({ method: 'kaia_connectAndSign', params: [msg]}) as string[];
   return [account, signature];
}
 
const getBalance = async(params: [account:string,blockNumberOrHash:'latest' | 'earliest'])=>{
   return await walletProvider.request({ method: 'kaia_getBalance', params: params });
}
 
const transaction = {
  from: '0xYourWalletAddress', //The currently connected wallet account can be retrieved using the kaia_accounts method.
  to: '0xRecipientAddress', //Please replace it with a valid wallet address.
  value: '0x10',
  gas: '0x5208', //general gas usage for Kaia transaction
};
 
const sendTransaction = async(transaction) => {
    const transactionHash = await walletProvider.request({ method: 'kaia_sendTransaction', params: [transaction]});
    return transactionHash;
};

파라미터

• RequestArguments *required · object
  • method *required · string
  • params unknown[]

응답

Promise<unknown>

method	params	Responses
kaia_accounts 현재 지갑에 연결된 주소 목록을 반환합니다. 연결된 지갑이 없으면 빈 배열을 반환합니다.	null	['Account1']
kaia_requestAccounts 지갑 연결을 시작합니다. 이 과정에서 사용자가 지갑 provider를 선택할 수 있는 창이 표시됩니다. 선택한 지갑에 연결된 주소 목록을 반환합니다.	null	['Account1']
personal_sign (EIP-191) 서명 절차를 시작합니다. OKX Wallet을 포함한 다양한 지갑과의 호환성을 위해 personal_sign 사용을 권장합니다.	[message: string, account: string]	"0xa3f20717a250c2b0b729b7e5becbff67fdaef7e0699da4de7ca5895b02a170a12d887fd3b17bfdce3481f10bea41f45ba9f709d39ce8325427b57afcfc994cee1b" signature
kaia_connectAndSign (EIP-191)recommended 지갑 연결과 서명을 시작합니다. 사용자에게 지갑 provider를 선택하도록 안내한 뒤, 제공된 메시지에 서명합니다. [account, signature]를 배열로 반환합니다.	[message: string]	["account","0xa3f20717a250c2b0b729b7e5becbff67fdaef7e0699da4de7ca5895b02a170a12d887fd3b17bfdce3481f10bea41f45ba9f709d39ce8325427b57afcfc994cee1b"] account와 signature를 배열로 반환
kaia_getBalance KAIA 잔액을 반환합니다.	[account: string, blockNumberOrHash: string] blockNumberOrHash는 latest 또는 earliest로 설정할 수 있습니다. latest: 가장 최근 블록 earliest: 제네시스 블록(블록 0)	"0x00000000000000000" Kaia 블록체인의 최소 단위인 kei로 표현된 잔액 값입니다. 1 KAIA = 10^18 kei
kaia_sendTransaction 주어진 파라미터로 트랜잭션을 구성합니다.	[{ from: string, to: string, value: string, gas: string }] from 필드는 'kaia_accounts','kaia_requestAccounts' 또는 'kaia_connectAndSign'에서 얻은 account여야 합니다.	"0xe670ec64341771606e55d6b4ca35a1a6b75ee3d5145a99d059210" transactionHash

에러

{code: -32001, message: 'User canceled'}

Code	Description
-32001	{ "code": -32001, "message": "User canceled" } //When the user dismissed the wallet connection popup. {code: -32001, message: 'User closed popup', data: null} //When the user clicks the dismiss button on the signature popup { "code": -32001, "message": "User denied message signature" } //When the user clicks the dismiss button on the transaction popup { "code": -32001, "message": "User denied transaction send." }
-32004	잘못된 from 주소입니다 (walletProvider.disconnectWallet()을 실행한 후 메서드를 다시 시도하세요)
-32005	비밀번호를 잘못 입력하여 로그아웃되었습니다 (walletProvider.disconnectWallet()을 실행한 후 메서드를 다시 시도하세요)
-32006	지갑이 아직 연결되지 않았습니다 (지갑이 연결된 상태에서 에러가 발생한 경우, walletProvider.disconnectWallet()을 실행한 후 메서드를 다시 시도하세요. 지갑이 연결되지 않은 상태에서 에러가 발생한 경우, 먼저 지갑을 연결하세요)

walletProvider.disconnectWallet()

지갑 연결을 해제합니다. 이 함수를 호출하면 연결 해제를 확인하는 확인 창이 표시됩니다.

 const disconnectWallet = async ()=>{
    await walletProvider.disconnectWallet();
    window.location.reload();
}

파라미터

• N/A

응답

• N/A

walletProvider.getErc20TokenBalanceWithDepositedBalance()

경고

왜 getErc20TokenBalance() 대신 이 메서드를 사용해야 하나요?
Unifi는 Unifi Wallet이 보유한 USDT·JPYC를 내부 풀에 자동으로 예치합니다. 이 때문에 getErc20TokenBalance()는 해당 토큰의 예치분을 포함하지 않으며, Unifi Wallet로 연결된 사용자의 경우 실제로 잔액이 있어도 0을 반환할 수 있어 앱의 잔액 확인이 잘못 실패하고 결제가 막힐 수 있습니다.

트랜잭션 전에 USDT 또는 JPYC 잔액을 확인하는 dapp이라면 getErc20TokenBalanceWithDepositedBalance()를 사용하세요. 이 메서드는 조건 없이 호출해도 안전합니다. 예치 풀이 없는 Unifi Wallet 외 지갑의 경우 예치분 0으로 온체인 잔액을 그대로 반환합니다.

이 메서드는 지원 토큰(USDT, JPYC)에 대해 온체인 잔액과 Unifi에 예치된 잔액의 합계인 총액을 반환합니다.

const getErc20TokenBalanceWithDepositedBalance = async(contractAddress:string,account:string)=> {
    return await walletProvider.getErc20TokenBalanceWithDepositedBalance(contractAddress,account);
}
 
const USDTContractAddress = '0xd077a400968890eacc75cdc901f0356c943e4fdb';
const account = 'my_account_address';
getErc20TokenBalanceWithDepositedBalance(USDTContractAddress, account).then(balance => {
    const formattedUSDTBalance = Number(microUSDTHexToUSDTDecimal(balance as string)).toFixed(2);
    //microUSDTHexToUSDTDecimal is format function to transform hexadecimal string to decimal string
    //https://github.com/techreadiness/unifi-apps-starter/blob/main/src/utils/format.ts
    console.log(formattedUSDTBalance);
    //0.00
})

토큰	컨트랙트 주소 (Kaia)
USDT	0xd077a400968890eacc75cdc901f0356c943e4fdb
JPYC	0xE7C3D8C9a439feDe00D2600032D5dB0Be71C3c29

파라미터

• contractAddress *required · string
• account *required · string

응답

64바이트 16진수 문자열입니다. 반환되는 값은 토큰의 decimals 명세에 따른 소수점 스케일링이 적용되어 있습니다.

예를 들어 USDT는 10⁶의 소수점 스케일을, JPYC는 10¹⁸의 소수점 스케일을 사용합니다.

string

walletProvider.getErc20TokenBalance()

ERC20 기반 토큰의 온체인 잔액을 반환합니다.

const getErc20TokenBalance = async(contractAddress:string,account:string)=> {
    return await walletProvider.getErc20TokenBalance(contractAddress,account);
}
 
const USDTContractAddress = '0xd077a400968890eacc75cdc901f0356c943e4fdb';
const account = 'my_account_address';
getErc20TokenBalance(USDTContractAddress, account).then(balance => {
    const formattedUSDTBalance = Number(microUSDTHexToUSDTDecimal(balance as string)).toFixed(2);
    //microUSDTHexToUSDTDecimal is format function to transform hexadecimal string to decimal string
    //https://github.com/techreadiness/unifi-apps-starter/blob/main/src/utils/format.ts
    console.log(formattedUSDTBalance);
    //0.00
})

파라미터

• contractAddress *required · string
• account *required · string

응답

64바이트 16진수 문자열입니다. 반환되는 값은 토큰의 decimals 명세에 따른 소수점 스케일링이 적용되어 있습니다.

예를 들어 USDT는 10⁶의 소수점 스케일을, JPYC는 10¹⁸의 소수점 스케일을 사용합니다.

string

호환 라이브러리

• https://docs.kaia.io/ko/references/sdk/ethers-ext/getting-started/
• https://docs.kaia.io/ko/references/sdk/web3js-ext/getting-started/
• https://docs.kaia.io/ko/references/sdk/caver-js/