Live Scanner 운영자 메뉴얼

---

ABC

운영자 매뉴얼(Live Scanner)

목 차

1. Live Scanner 개요

1-1) 시스템 구성도

1-2) Live Scanner 흐름도

1-3)Live Scanner 설치

2. End-point 상태 모니터링

2-1) 스캐너 프로세스 Log 확인

3. Live Scanner 프로세스 관리

3-1) 프로세스 목록 확인

3-2) 프로세스 시작

3-3) 프로세스 중지

4. Live Scanner 구동 권장 H/W 사양

4-1) 하드웨어 요구사항

4-2) 기타

---

1. Live Scanner 개요

Live Scanner는 Node.JS로 제작되었으며 Ethereum, Klaytn, Polygon, BnB 메인넷 End-Point Node에 연계하여 실시간으로 생성되는 블록 및 Transaction을 분석하여 블록 관련 정보를 추출하는 프로그램입니다.

추출된 NFT와 토큰 정보는 RDS 서버에 실시간으로 저장되며, 현재 처리하고 있는 블록 번호 또한 RDS 서버에 실시간으로 저장됩니다.

1-1) 시스템 구성도

1-2) Live Scanner 흐름도

시작 : 엔드포인트 노드 연결
state 1(정상)   function: updateDB, Started... “network(Ethereum)”
state 0(오류)   function: updateDB, Ready... “network(Ethereum)”

1. 블록 정보 가져오기
연결된 노드에서 블록의 정보를 가져옵니다.

2. Deploy, Transfer 분류
    1) Deploy (ERC-20, 721, 1155) : contract address와 from 이 존재하며 to가 null 경우
        -> Deploy, 내용 insert
    2) Transfer (ERC-20, 721, 1155) : contract address, from, to, topic[0]이 존재
        -> Transfer, 내용 insert 또는 update

3. Sales 분류
    1) Sales : ERC-721, ERC-1155 이면서 contract address, from, to, topic[0]이 존재
        ->Sale, 내용 insert

완료 : Network: ethereum, function: parseBlocks, block_number: 17963060, successfully parsed block 로그 출력

1-3) Live Scanner 설치

Live Scanner 는 Node.JS로 제작되었으며, 프로세스 관리에서는 pm2를 사용합니다. 따라서 Live Scanner를 설치하기 위해서는 Server에 Node.JS 및 pm2 등이 설치되어 있어야 합니다.

전제 조건

• Ubuntu 20.04 이상

• Node v18.17.1 또는 그 이상

• Npm v9.6.7 또는 그 이상

• Pm2 v5.3.0 또는 그 이상

설치

Live Scanner는 작동 시에 NFT DB의 crawler_table을 읽어서 수집할 블록 번호에 따라서 동작하므로 crawler_table이 없다면 설치 전에 아래의 명령에 따라 crawler_table을 정의하거나, 수집할 블록 번호를 NFT DB에 업데이트합니다. crawler_table의 상세 설명은 ‘블록체인 DB 테이블명세서.docx’ 및 docs의 블록체인 스캐너 로직 설명을 참고하시기 바랍니다.

• Crawler_table 생성

CREATE TABLE `crawler_table` (
 `network` varchar(20) NOT NULL,
 `crawled_block_number` int(11) NOT NULL,
 `block_endnumber` int(11) NOT NULL,
 `network_state` int(11) NOT NULL,
 PRIMARY KEY (`network`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

테이블명	설명
crawler_table	실시간 블록체인 데이터 수집을 위한 정보 수집
nft_collection_table	NFT 컬렉션 정보 수집
nft_owner_table	소유자별 NFT 잔고 정보 수집
nft_token_table	NFT 토큰 정보 수집
nft_transaction_table	NFT 전송, 거래 이력 정보 수집
nft_hide_table	숨겨진 NFT에 대한 정보 수집
token_table	토큰 정보 수집
token_owner_table	소유자별 token 잔고 정보 수집
token_transfer_table	토큰 전송 이력 정보 수집
nodes_table	노드 활성화 상태 수집
statistics_table	통계 정보 수집
users_table	사용자 유형 정보 수집

• 블록체인 DB 테이블 설명

블록체인 스캐너(Crawler)KTHULU DOCS

테이블의 이해를 돕기 위한 설명이므로 데이터베이스 정의서와 상이할 수 있으므로 데이터베이스 정의서를 참고하시기 바랍니다.

• crawler 프로세스별 테이터 입력

컬럼명	설명
network	각 체인의 이름(ethereum, cypress, polygon, bnb)을 입력합니다.
crawled_block_number	기존에 최종적으로 수집한 블록 번호를 입력합니다. 0을 입력하는 경우 1번 블록부터 데이터를 수집합니다.
block_endnumber	수집할 최종 번호를 입력합니다. -1을 입력하는경우 실시간 최신블록으로 동작합니다.
network_state	각 프로세스의 작동 여부를 지정합니다. crawler가 동작을 시작하면 1로 update 됩니다.

• 프로세스 별 데이터 입력 예

INSERT INTO `databaseName`.`crawler_table` 
(`network`, `crawled_block_number`, `block_endnumber`, `network_state`) 
VALUES
 ('ethereum', 45000, -1, 1), ('cypress', 90000, -1, 1), 
('polygon', 100, -1, 1), ('bnb', 25000, -1, 1);

1.3.1) 메인넷(Ethereum) NFT 데이터 수집 프로그램 설치

제공받은 block-crawler-live 파일을 압축해제 및 폴더를 아래의 명령어를 통해 block-crawler-live-eth 폴더로 복사합니다.

cp -r ./block-crawler-live ./block-crawler-live-eth

• crawler에 config/config.json을 수정합니다.

{
    "port":3000,
    "network":"ethereum", // network ex) "ehtereum", "cypress", "polygon", "bnb"
    "endpoints":{
        "ethereum":[
            "ethereumNode"
        ],
        "cypress":[
            "klaytnNode"
        ],
        "polygon":[
            "polygonNode"
        ],
        "bnb":[
            "binanceNode"
        ],
        "ipfs":[
            "ipfsNode"
        ]
    },
    "db_connection": {
        "host": "127.0.0.1", // database host 
        "port": 3306, // database port
        "user": "userName",  // database user name
        "password": "userPassword", // database user password
        "charset" : "utf8mb4", // database charset
        "database": "databaseName" // database name
    }
}

• 다음 명령을 통해 블록체인 데이터 수집 프로그램을 시작합니다.

pm2 start ./tools/crawler.js -i 10 --name "block-crawler"

2. End-point 상태 모니터링

Live Scanner에서는 End-Point Node와의 Connection 상태를 실시간으로 체크하고 이를 DB에 저장합니다. 이러한 End-Point 상태 값을 확인하기 위해서는 아래 Query 문을 실행합니다.

SELECT * FROM nodes_table;

Query 실행 결과

2-1) 스캐너 프로세스 Log 확인

pm2 명령어를 통해 스캐너 프로세스의 로그를 확인할 수 있으며 아래와 같이 명령어를 콘솔창에 입력합니다.

pm2 logs all

실행 결과 예시

3. Live Scanner 프로세스 관리

Live Scanner는 Node.JS 프로세스 관리 도구인 pm2를 통해 관리됩니다. Pm2 사용법에 관해서는 https://pm2.keymetrics.io/ 를 참고 바랍니다.

3-1) 프로세스 목록 확인

프로세스 목록 확인을 위해서는 Live Scanner가 설치된 서버의 콘솔에서 아래의 명령을 실행합니다.

pm2 list

실행 결과

3-2) 프로세스 시작

• 프로세스 목록 확인 과정에서 프로세스가 없는 경우에는 아래와 같이 프로세스를 시작할 수 있습니다.

pm2 start ./tools/crawler.js -i 10 --name "block-crawler"

• 프로세스 목록 확인 과정에서 프로세스가 없는 경우에는 아래와 같이 프로세스를 시작할 수 있습니다.

cd block-crawler-live-eth
pm2 –i 3 –name=’block-crawler-eth’ start bin/www

• 프로세스 목록 확인 과정에서 프로세스가 있고 status 가 online이 아닌 경우에는 아래와 같이 프로세스를 시작할 수 있습니다.

pm2 start all

• 프로세스를 개별 id나 name으로도 시작할 수 있으며 아래와 같이 명령을 실행합니다.

pm2 start block-crawler-eth

• 프로세스 목록 확인 과정에서 프로세스가 있고 status 가 online이 아닌 경우에는 아래와 같이 프로세스를 재시작할 수 있습니다.

pm2 restart all

3-3) 프로세스 중지

• 모든 프로세스를 중지하고자 할 때는 아래의 명령으로 중지할 수 있습니다.

pm2 stop all

• 개별 프로세스를 중지하고자 할 때는 아래의 명령으로 중지할 수 있습니다.

pm2 stop block-crawler-eth

Live Scanner 오류코드

발생 코드	원인	해결
runQuery : Error: Can't add new command when connection is in closed state	DB 커넥션이 너무 많을 때 발생.	Pm2 프로세스의 수를 줄여서 다시 실행합니다.
getToken : TypeError: (intermediate value) is not iterable
contract.methods.totalSupply() : Error: Returned error: execution reverted	totalSupply가 없는 블럭정보에서 totalSupply를 실행하는 메서드를 실행하려고 할 때 발생.
getBlock : Error: Returned error: the block does not exist	해당 블럭이 존재하지 않거나 정보가 잘못 되었을 때 발생.	스타트 블럭의 번호를 확인하고 이전 번호로 다시 실행합니다.
You have triggered an unhandledRejection, you may have forgotten to catch a Promise rejection: 11|crawler | TypeError: undefined is not iterable
isERC1155Contract : Error: Returned error: execution reverted	1155컨트랙트 함수 호출 중 1155컨트랙트가 없는 정보에서 메서드를 실행하려고 할 때 발생.
isERC1155Contract : Error: Returned values aren't valid, did it run Out of Gas? You might also see this error if you are not using the correct ABI for the contract you are retrieving data from, requesting data from a block number that does not exist, or querying a node which is not fully synced.	데이터를 검색하는 컨트랙트가 올바른 ABI를 사용하지 않는 경우에 이 오류가 표시. 혹은 컨트랙트 주소가 잘못되었을 때 발생.
getBlock : Error: Returned error: invalid argument 0: hex string without 0x prefix	컨트랙트어드레스가 16진수임을 제대로 나타내지 못해서 발생

위 오류코드 이외에 또다른 오류코드가 발생하여 해결이 어려울 때는 직접 문의하여 주시기 바랍니다.

문의 : [e-mail]

4. Live Scanner 구동 권장 H/W 사양

4-1) 하드웨어 요구 사항

• 최신 버전의 Mac OS X, Linux 를 실행하는 VPS.

• 12코어 CPU 및 64GB 메모리(RAM) 또는 그 이상

• HDD : 8TB 또는 그 이상 / SSD : 8TB 또는 그 이상

4-2) 기타

※ 참고

Node.JS

• https://nodejs.org/en/

pm2

• https://pm2.keymetrics.io/

4-3) Endpoint Node

Live Schanner에서는 2개 이상의 Endpoint Node를 config.json 파일에 등록하여 데이터 수집시에 하나의 Endpoint Node와의 통신이 원활하지 않을 경우 다른 Endpoint Node를 사용하도록 하고 있습니다.

따라서 Infura(https://www.infura.io/), Alchemy(https://www.alchemy.com/), Allthatnode(https://allthatnode.com) 등의 Endpoint Node 서비스를 활용하여 Ethereum, Klaytn, IPFS 등의 Endpoint Node를 추가할 수 있습니다.