Lab4. View Transaction History

Lab Overview

Lab4에서는 다음과 같은 작업을 수행합니다:

1. API 이해도 향상: Account API의 기능과 사용법을 자세히 학습하며, 특히 트랜잭션 조회와 관련된 파라미터 및 필터링 옵션에 대해 이해합니다.
2. 트랜잭션 조회 기능 추가: Lab3에서 작성한 코드를 수정하여 특정 계정과 연관된 트랜잭션 목록을 조회하는 기능을 추가합니다. API 호출 및 응답 처리 방법을 활용하여 트랜잭션 정보를 가져오고 화면에 표시합니다.
3. 프로젝트에 반영 확인: 작성한 코드가 실제 프로젝트에 반영되어 동작하는지 확인합니다. 특정 계정의 트랜잭션 목록이 정확하게 출력되는지 테스트하여 프로젝트에 API를 효과적으로 통합한 결과를 확인합니다.

Prerequisite

이번 랩을 진행하기 전에 아래의 작업을 완료해야 합니다:

1. [Lab3. Query NFTs]를 완료하셨어야 합니다. Lab4에서는 Lab3의 코드와 설정을 그대로 활용합니다.
2. Luniverse Multichain API의 AUTH_TOKEN을 발급받았어야 합니다. 발급받은 인증 토큰은 Lab4 코드에서 API 호출 시 사용됩니다.
3. instances.ts 파일에 기입된 프로토콜과 네트워크가 발급받은 인증 토큰과 대응되는지 확인해주세요. 다른 환경에서 생성된 인증토큰은 API 호출 시 에러가 발생합니다.
4. 발급 받은 인증 토큰의 유효기간이 유효한지 확인해주세요. 모든 인증토큰은 발급 시점으로 부터 7일 동안만 유효합니다.

위의 사항들이 준비되었다면 이제 Lab4에서 사용할 API에 대해서 알아보겠습니다.

사용할 API

특정 계정의 자산 혹은 트랜잭션을 조회하려면 Account API를 사용하면 됩니다. 그 중 이번 랩에서 사용할 API는 계정 주소와 연관된 트랜잭션 목록을 조회하는 listAccountTransactions API입니다.

listAccountTransactions

이 API를 사용하면 특정 계정과 관련된 트랜잭션 목록을 조회할 수 있습니다. 단순 조회뿐만 아니라 트랜잭션과의 관계나 트랜잭션 상태에 따라 필요한 트랜잭션 목록만 필터링하여 조회할 수 있습니다.

트랜잭션 관계 (relation)

이더리움 트랜잭션에는 보내는 계정의 주소(from)와 받는 계정의 주소(to)에 대한 필드가 포함됩니다. listAccountTransactions에서는 이 두 필드 간의 연관성에 따라 필터링이 가능합니다. 필터링할 수 있는 조건은 총 세 가지입니다.

1. from: 조회 대상 계정 주소가 from에 포함된 트랜잭션들만 반환합니다.
2. to: 조회 대상 계정 주소가 to에 포함된 트랜잭션들만 반환합니다.
3. 빈 값: 조회 대상 계정 주소가 from이나 to 중 하나라도 포함된 트랜잭션들만 반환합니다.

트랜잭션 상태 (status)

이더리움에서 트랜잭션의 상태는 해당 트랜잭션이 실행되었는지 또는 실행 결과에 대한 정보를 나타냅니다. 여기에서 필터링할 수 있는 조건은 총 네 가지입니다.

1. success: 조회 대상 계정 주소의 트랜잭션 목록 중 성공한 트랜잭션들만 반환합니다.
2. failed: 조회 대상 계정 주소의 트랜잭션 목록 중 실패한 트랜잭션들만 반환합니다.
3. pending: 조회 대상 계정 주소의 트랜잭션 목록 중 아직 실행되지 않은 트랜잭션들을 반환합니다.
4. 빈 값: 조회 대상 계정 주소의 트랜잭션 목록 중 모든 상태 트랜잭션을 반환합니다.

API에 대한 더 자세한 정보를 얻고 싶다면 listAccountTransactions API Docs를 참고해주세요!

적용해보기

Luniverse Instance

• 파일 경로: [ server > src > apis > instances.ts ]

server 폴더 안의 instances.ts 파일을 열어주세요. 이 파일에는 루니버스 Multichain API에 호출할 때 필요한 인스턴스인 luniverseInstance가 정의되어 있습니다. luniverseInstance 에는 우리가 호출하고자 하는 API의 base URL과 인증 토큰(AUTH_TOKEN)에 대한 정보를 담고 있습니다.

📘

조회하려는 네트워크를 바꾸고 싶다면 어떻게 하나요?

instance.ts 파일의 PROTOCOL과 NETWORK에 원하는 프로토콜과 네트워크로 변경하면 됩니다. 단, 이때 변경한 프로토콜과 네트워크과 대응하는 노드가 필요합니다. (해당 노드가 없다면 가이드 문서를 참조해 노드를 생성해 주시기 바랍니다.) 추가적으로, 변경한 노드에서 발급받은 인증토큰을 .env 파일의 AUTH_TOKEN에 입력해야 합니다.

listAccountTransactions

• 파일 경로: [ server > src > apis > lab4.ts ]

이 파일에는 listAccountTransactions API를 호출하는 함수가 정의되어 있습니다. listAccountTransactions API 가이드를 참고하여 함수 내 미완성된 부분을 수정해주세요.

미완성 코드

// server/src/apis/lab4.ts

import { luniverseInstance } from "./instances";

export async function listAccountTransactions(
	address: string,
	relation?: string,
	status?: string,
	page?: number,
	rpp?: number
) {
	return luniverseInstance.request({
		method: "",
		url: ``,
		params: {},
	});
}

• method: HTTP 요청의 메서드(method)를 입력하는 필드 입니다. 이 API는 “GET” 요청을 받습니다.
• url: 이 필드는 API의 엔드포인트를 입력하는 곳입니다. luniverseInstance에서 baseURL이 설정되어 있기 때문에, 나머지 엔드포인트 부분을 입력해야 합니다. 따라서 url에 /accounts/${address}/transactions를 입력합니다.
• data: 이 필드는 바디 파라미터를 입력하는 필드입니다. 이 API는 총 네 개의 바디 파라미터(relation, status, page, rpp)를 받습니다.

완성 코드

비어있는 HTTP 요청의 메서드(method), API의 엔드포인트, 그리고 쿼리 파라미터(query parameter) 부분을 가이드 문서에 따라 작성하면 아래와 같이 코드를 완성할 수 있습니다.

// server/src/apis/lab4.ts

import { luniverseInstance } from "./instances";

export async function listAccountTransactions(
    address: string,
    relation?: string,
    status?: string,
    page?: number,
    rpp?: number
) {
    return luniverseInstance.request({
        method: "get",
        url: `/accounts/${address}/transactions`,
        params: {
            relation,
            status,
            page,
            rpp,
        },
    });
}

코드를 완성하면, 브라우저로 돌아가서 새로고침을 누르세요. 아래 그림처럼 트랜잭션 목록이 표시된다면 성공입니다!

튜토리얼을 마치며

축하합니다! 드디어 이번 튜토리얼의 모든 과정을 완료했습니다.🎉 이제 사용된 API의 필터링 옵션을 변경하거나 다른 API를 추가해보세요. 이를 통해 루니버스에 대한 경험이 더욱 풍부해질 것입니다.