Cosmos SDK 기반 체인 configuration

※ 원글 작성 : 22년 6월 29일

Cosmos SDK 기반 체인을 구성시에는 /config/ 디렉토리 내에 config 파일이 생성이 된다. 그 중 app.toml, config.toml에 대해 확인해본다.

app.toml

1. Base config

minimum-gas-price

• validator가 transaction을 처리할 때 수용하는 최소 gas price

pruning

• default : default
• option
  • default : 추가로 500번째 state 마다 100개의 state만 남기고 삭제, 10 block 간격으로 pruning
  • nothing : state를 삭제하지 않음 (archiving node 시)
  • everything : 모든 state 삭제
  • custom : 파라미터를 설정하여 pruning costumizing

pruning-keep-recent, pruning-keep-every, pruning-interval

• default : 0, 0, 0
• custom parameters

halt-height

• default : 0
• 루틴한 유지관리를 수행하거나 soft fork 등 예정된 업그레이드를 계획할 때 validator를 정상적으로 종료하기 위한 블록 height 설정 (non-zero block 기준)

halt-time

• default : 0
• halt-height처럼 종료하기 위한 target block time을 지정(unix time)

min-retain-blocks

• default : 0
• 커밋되고 있는 현재 블록으로부터 최소 block height offset을 설정하고, 이 offset을 지나는 모든 블록이 tendermint에서 제거
• ABCI 커밋 동안 RetainHeight를 결정하는 프로세스에 사용
• 0이면 제거 블록 없음
• block pruning만 정하며 위의 state pruning과는 관련 없음
• Retain block 참고

inter-block-cache

• default : true
• 자주 read 되거나, n 블록의 마지막에 write 되고 n+1 블록에 read되는 거버넌스 proposal queue와 같이 read 시 디스크 crash를 방지하고 자주 접근하는 변수에 대한 read 반복 속도를 높이기 위함
• write-through cache
• 참고

index-events

• default : []
• {eventType}.{attributeKey} 형식으로 tendermint에 index를 생성할 대상의 event set을 정의 (e.g. ["message.sender", "message.recipient"] )
• empty의 경우 모든 event를 index

iavl-cache-size

• default : 781250
• iavl tree(ethereum의 MPT 역할)의 내부 노드 크기 (내부에 지정된 default 크기 50mb, 참고)

2. Telemetry

• telemetry : 원격 분석으로 모듈 및 애플리케이션에 대한 insight 수집
• config 내에서 telemetry가 enable 된 경우 글로벌 메트릭 수집기로 ([go-metrics] (https://github.com/armon/go-metrics)) 수집
• 측정항목

service-name

• default : ""
• 서비스 분류를 위해 key를 통한 prifix

enabled

• default : false
• telemetry 활성화

enable-hostname

• default : false
• host name을 이용한 gauge value prefixing 활성화

enable-hostname-label, enable-service-lavel

• default : 0
• label에 hostname or service를 추가 여부

prometheus-retention-time

• default : 0
• time이 양수인 경우 prometheus metrics sink 활성화
• expose된 API 엔드포인트에서 /metrics?format={text|prometheus} 통해 메트릭을 쿼리/스크랩

global-labels

• default : []
• telemetry 패키지를 사용하여 내보낸 모든 메트릭에 적용될 global label를 정의
• e.g. [["chain_id", "cosmoshub-1"]]

3. API config

enable

• default : false
• API server 사용

swagger

• default : false
• swagger 사용

address

• default : tcp://0.0.0.0:1317
• 노출될 address 정의

max-open-connections

• default : 1000
• 최대 connection 수 설정

rpc-read-timeout

• default : 10
• tendermint RPC read timeout 시간 설정 (sec 단위)

rpc-write-timeout

• default : 0
• tendermint RPC write timeout 시간 설정 (sec 단위)

enabled-unsafe-cors

• default : false
• 다른 origin request를 위한 CORS 활성화

4. Rosetta

• Rosetta API server : 체인 노드에 연결하여 지원하는 api를 통해 블록체인 integration
• Cosmos SDK(v0.45.4) 상에 개발된 rosetta는 "WARNING: The Rosetta server is still a beta feature. Please do not use it in production." 로 상용에 사용을 지양
• rosetta api spec

enable

• default : false
• rosetta api server 사용

address

• default : 8080
• API server listen

blockchain

• default : app
• rosetta에 return 되는 블록체인 이름 정의

network

• default : network
• rosetta에 return 되는 network 이름 정의

retries

• default : 3
• failing 전에 node connection retry 수

offline

• default : false
• offline mode 설정

5. gRPC

enable

• default : true
• grpc 서버 활성화

address

• default : 0.0.0.0:9090
• grpc 서버 주소

6. gRPC web

enable

• default : true
• grpc web server 활성화

address

• default : 0.0.0.0:9091
• grpc web 주소

7. State sync

• state sync snapshot을 통해 과거 블록의 history replay 없이 네트워크에 참여할 수 있도록 하고, 지정된 height에서 애플리케이션 state의 스냅샷을 다운로드 하여 적용

snapshot-interval

• default : 1000
• snapshot을 위한 block interval 설정 (0은 disable)

snapshot-keep-recent

• default : 10
• 유지하고 제공할 최신의 snapshot 수 설정 (0은 모두 저장)

8. Custom

bypass-min-fee-msg-types

• default : ["/ibc.core.channel.v1.MsgRecvPacket", "/ibc.core.channel.v1.MsgAcknowledgement", "/ibc.core.client.v1.MsgUpdateClient", ])
• ChectTx 동안 최소 fee 확인을 bypass 하도록 설정하는 메시지 유형

config.toml

1. Base config

proxy_app

• default : tcp://127.0.0.1:26658
• Tendermint와 애플리케이션 간 통신을 위한 인터페이스 ABCI proxy 주소 설정

moniker

• 노드 별명(human readable)

fast_sync

• default : true
• 체인에 블록이 많이 있을 경우, 블록을 다운로드 하면서 커밋들을 병행하여 검증하는 모드 설정

db_backend

• default : goleveldb
• DB backend 설정 (기본 goleveldb, 옵션 cleveldb, boltdb, rockdb, badgerdb)

db_dir

• default : data
• DB directory

log_level, log_format

• default : info, plain
• log type 설정

genesis_file

• default : config/genesis.json
• 제네시스 파일 위치

priv_validator_key_file

• default : config/priv_validator_key.json
• validator private key 위치

priv_validator_state_file

• default : data/priv_validator_state.json
• validator의 최신 sign state 파일 위치

priv_validator_laddr

• default : ""
• 외부 PrivValidator로 부터 tendermint가 listen 하여 connection되는 tcp, unix socket 주소

node_key_file

• default : config/node_key.json
• p2p 프로토콜 인증을 위한 node의 private key 위치

abci

• default : false
• ABCI 어플리케이션에 연결하기 위한 메커니즘 (socket | grpc)

filter_peers

• default : false
• true 새로운 피어에 연결할 시 ABCI 애플리케이션에 query하여 애플리케이션이 연결, 연결을 유지할지 여부 설정

2. RPC

laddr

• default : tcp://127.0.0.1:26657
• RPC server 주소

cors_allowed_origins

• default : []
• CORS를 인정할 origin list (["*"]일시 any)

cors_allowed_method

• default : ["HEAD", "GET","POST"]
• cross domain request 시 사용 가능한 method

cors_allowed_headers

• default : ["Origin", "Accept", "Content-Type", "X-Requested-With", "X-Server-Time", ]
• cross domain request 시 non simple header 리스트

grpc_laddr

• default : ""
• /broadcast_tx_commit 만을 지원할 grpc 서버 주소

grpc_max_open_connections

• default : 900
• HTTP 및 websocket이 아닌 grpc에 동시에 connection 가능한 최대 숫자
• 0은 무제한

unsafe

• default : false
• /dial_seed나 /unsafe_flush_mempool 같은 안전하지 않은 RPC command의 활성화 여부

max_open_connections

• default : 900
• grpc를 제외한 http와 websocket에 연결 가능한 최대 숫자
• 0은 무제한

max_subscription_clients

• default : 100
• /subscribe 명령어를 사용 가능한 유니크한 clientID의 수 설정
• /broadcast_tx_commit을 사용한다면 각 블록마다 해당 명령을 호출할 수 있는 최대 수로 설정해야 한다.

max_subscriptions_per_client

• default : 5
• /subscribe 가능한 client의 유니크한 query의 최대 수
• grpc, local rpc client를 사용하거나 /broadcast_tx_commit을 사용한다면 각 블록마다 해당 명령을 호출할 수 있는 최대 수로 설정해야 한다.

experimental_subscription_buffer_size

• default : 200
• subscription을 error 리턴 하거나 closing 전에 각 subscription 당 노드가 버퍼링 가능한 최대 event 수를 지정 (experimental parameter)
• 최소한 100은 설정해야 하며, 큰 값을 설정하는 경우 더 많은 memory를 사용하지만 높은 event 쓰루풋 rate를 가진다.

experimental_websocket_write_buffer_size

• default : 200
• 각 websocket 클라이언트 당 RPC response의 최대 버퍼 수
• 클라이언트가 데이터를 websocket endpoint에서 빨리 read 못하면 disconnect 되어 buffer size를 늘리면 메모리를 더 사용하짐나 disconnect될 가능성이 준다.
• 적어도 experimental_subscription_buffer_size와 같아야 한다.

experimental_close_on_slow_client

• default : false
• websocket client가 read할 정도로 빠르지 못하면 error 생성이나 disconnect 대신 drop event를 제공한다.

timeout_broadcast_tx_commit

• default : 10s
• /broadcast_tx_commit 시에 tx가 커밋될 때 까지 기다리는 시간 설정

max_body_bytes

• default : 1000000
• request body 최대 바이트 사이즈 (byte 단위)

max_header_bytes

• default : 1048576
• request header 최대 바이트 사이즈 (byte 단위)

tls_cert_file, tls_key_file

• default : "", ""
• HTTP server를 생성 시 사용되는 certificate 파일 path
• HTTP server를 생성 시에 tls_cert_file 및 tls_key_file은 반드시 tendermint에 알려야 한다.

pprof_laddr

• default : localhost:6060
• pprof listen addr

3. P2P

laddr

• default : tcp://0.0.0.0:26656
• incoming connection 시 listen 주소

external_address

• default : ""
• dial 시 다른 피어들에게 알리는 주소
• empty 시 laddr과 같다

seeds

• default : ""
• 연결 대상 seed node의 comma로 분리되는 리스트

persistent_peers

• default : ""
• persistent node의 리스트

upnp

• default : false
• upnp port forwarding 사용 설정

addr_book_file

• default : config/addrbook.json
• address book 위치

max_num_inbound_peers

• default : 40
• inbound peer의 최대 수

max_num_outbound_peers

• default : 10
• persistent peer를 제외한 outbound peer의 최대 수

unconditional_peer_ids

• default : ""
• 커넥션 설정 가능한 node ID 리스트 (어떤 제한도 무시)

persistent_peers_max_dial_period

• default : 0s
• persistent peer에 redialing 시 정지하는 시간
• 0일 시 exponential backoff를 설정하여 retry

flush_throttle_timeout

• default : 100ms
• connection 시 메시지를 flush하기 전에 대기하는 시간

max_packet_msg_payload_size

• default : 1024
• 최대 메시지 패킷 payload 사이즈 (byte 단위)

send_rate

• default : 5120000
• packet이 전송되는 rate (bytes/second)

recv_rate

• default : 5120000
• packet을 receive 가능한 rate (bytes/second)

seed_mode

• default : false
• 노드가 지속적으로 네트워크를 크롤링하고 피어를 찾는 시드 모드 설정
• 다른 노드가 주소를 요청하면 response 후 disconnect
• peer-exchange reactor가 비활성화 된 경우 동작 불가

private_peer_ids

• default : ""
• private로 유지하기 위한 peer id 리스트
• private peer는 다른 peer들에 gossip 되지 않는다.

allow_duplicat_ip

• default : false
• 같은 IP로부터 피어 커넥팅 비활성화 설정

handshake_timeout, dial_timeout

• default : 20s, 3s
• 피어 연결 설정

4. Mempool

• 다른 노드들로 broadcast 되고, 블록 포함 시 consensus reactor로 제공 될 트랜잭션의 memory pool config 설정
• 참고

recheck

• default : true
• 서명 확인 같은 특정 check를 건너 뛸 수 있기 때문에 CheckTx를 통과한 transaction에 대해 mempool에서 다시한번 check를 하는 recheck 호출 설정

broadcast

• default : true
• 트랜잭션을 broadcast 설정

wal_dir

• default : ""
• write-ahead log인 wal 파일을 저장하기 위한 directory
• wal file은 노드가 crash되는 경우 broadcast 되지 않은 트랜잭션을 다시 로드하는데 사용

size

• default : ""
• mempool 내의 transaction 최대 수

max_txs_bytes

• default : 1073741824
• mempool의 트랜잭션 total size

cache_size

• default : 10000
• 일찍 발견된 transaction들의 filtering을 위해 사용되는 cache size

keep-invalid-txs-in-cache

• default : false
• cache에서 invalid transaction들을 제거하지 말것(그래서 default로 false)
• true 시 invalid transaction들이 valid로 변경되는 것이 불가능하다

max_tx_bytes

• default : 1048576
• 하나의 트랜잭션의 최대 크기

max_batch_bytes

• default : 0
• reactor는 연결된 피어에게 batch로 트랜잭션을 보내고, 한 배치의 최대 크기 설정
• 현재는 사용하지 않는다. 참고

5. State sync

enable

• default : false
• state sync 사용

rpc_server

• default : ""
• synced state machine 및 node bootstrap을 위한 state data 검색의 light client 검증을 위한 RPC 서버 설정

trust_height, trust_hash, trust_period

• default : 0, "", 168h0m0s
• 위 RPC 서버는 신뢰 가능한 height, 신뢰 할 수 있는 source에서 얻은 header hash, validator를 신뢰할 수 있는 period가 필요
• cosmos sdk 기반 체인에서는 slash(financially punish)가 가능하도록 trust_period는 unbonding time의 2/3로 보통 설정한다.

discovery_time

• default : 15s
• initiating a restore 전에 snapshot을 찾을 시간

temp_dir

• default : ""
• state sync snapshot chunk를 보관하기 위한 임시 디렉토리
• 보통 OS tempdir을 사용 (/tmp)

chunk_request_timeout

• default : 10s
• 다른 피어로 부터 chunk를 재요청하기 전에 timeout 시간

chunk_fetchers

• default : 4
• 동작하기 위한 chunk fetcher 수

6. Fast sync

version

• default : v0
• fast sync version
  • v0 : legacy fast sync
  • v1 : 더 나은 테스트를 위한 v0의 리팩터링
  • v2 : 테스트와 readability에 최적화 된, v0의 완전히 새로운 설계 버전

7. Consensus

wal_file

• default : data/cs.wal/wal
• wal 파일 저장 디렉토리
• consensus 모듈은 모든 메시지를 wal에 write

timeout_propose

• default : 3s
• prevoting nil 전 proposal block을 기다리는 시간

timeout_propose_delta

• default : 500ms
• 컨센서스 각 라운드에 timeout_propose가 증가하는 시간

timeout_prevote

• default : 1s
• prevote의 2/3 이상 받아들이는 것을 대기하는 시간

timeout_prevote_delta

• default : 500ms
• 각 라운드에 timeout_prevote가 늘어나는 시간

timeout_precommit

• default : 1s
• precommit의 2/3 이상이 validator에게 수신되기를 대기하는 시간

timeout_precommit_delta

• default : 500ms
• 각 라운드에 timeout_precommit이 늘어나는 시간

timeout_commit

• default : 5s
• 새로운 height로 시작하기 전에 committing된 블록을 기다리는 시간

double_sign_check_height

• default : 0
• consensus에 참여하기 전에 노드의 합의 vote 존재를 확인하기 위해 확인할 블록의 수
• non-zero일 경우 동일한 consensus key가 double_sign_check_height 마지막 블록에 sign 하는데 사용되는 경우, 해당 노드는 재시작 시 panic
• 따라서 validator는 state machine을 중지하고 일부 블록을 기다린 다음 panic을 피하기 위해 state machine을 재시작 해야 한다.

skip_timeout_commit

• default : false
• 모든 precommit이 있는 즉시 진행(TimeoutCommit = 0인 것처럼)

create_empty_blocks

• default : true
• empty block 생성 여부

create_empty_blocks_interval

• default : 0s
• empty block 간 지속 생성 시 interval

peer_gossip_sleep_duration, peer_query_maj23_sleep_duration

• default : 100ms, 2s
• reactor sleep duration

8. Transaction indexer

• transaction 들의 indexing을 지원

indexer

• default : kv
• 인덱서를 백업할 데이터 베이스
• null이면 인덱싱 서비스를 사용하지 않음
• kv이면 key-value storage가 지원하는 가장 간단한 인덱서(default levelDB)
• kv가 선택되면 tx.height 및 tx.hash가 항상 인덱싱 됨

9. Instrumentation

prometheus

• default : false
• true일 시 prometheus metrics가 서비스 됨 (상기 telemetry)

prometheus_listen_addr

• default : 26660
• 프로메테우스 listen 포트

max_open_connections

• default : 3
• 동시 connection 최대 수
• 0 : unlimit
• 디폴트보다 더 큰 수를 사용 시 os limit 까지 증가 가능

namespace

• default : tendermint
• instrumentation namespace