Cosmos SDK 기반 체인 configuration (v0.50.X)

2023.06.14 - [Blockchain/Cosmos] - Cosmos SDK 기반 체인 configuration (v0.45.X)

2025.04.04 - [Blockchain/Cosmos] - Cosmos SDK 기반 체인 configuration (v0.50.X)

이전 글에서 Cosmos SDK의 configuration을 정리를 했었는데, 새로 생겼거나 사라진 값들이 존재하여서 업데이트를 한다.

app.toml

1. Base config

Base configuration은 Cosmos SDK 기반 app chain을 운영할 시 validator node 설정을 위한 파라미터를 정의한다.

minimum-gas-prices

• Validator node가 인입된 트랜잭션을 처리할 때 수용할 최소 gas price
• Empty string 값은 설정할 수 없으며, 필요하다면 gas price를 0으로 설정이 필요 (e.g. 0uatom)

query-gas-limit

• default: 0
• 일반적으로 default 값이 설정되어 있으면 제한 없이 state 쿼리를 수행할 수 있으나 DDoS 공격 방지 등의 이유로 설정
• 설정한 gas limit 이하로 consume되는 쿼리만 수행하고, 가스 초과 시 out of gas 에러 발생

pruning

• default: "default"
• 무한정 늘어나는 노드의 state 용량 관리를 위한 파라미터
• option
  • "default": 마지막 362,880 state들만 남기고 삭제, 10 blocks 간격으로 pruning
  • "nothing": 모든 state를 삭제하지 않음 (archiving node 운영 시)
  • "everything": 마지막 2 state들만 남기고 삭제, 10 blocks 간격으로 pruning
  • "custom": 파라미터를 설정하여 pruning customizing, 아래의 pruning-keep-recent와 pruning-interval을 이용하여 설정

pruning-keep-recent

• default: 0
• Pruning option이 "custom" 일 시 남기는 state 수

pruning-interval

• default: 0
• Pruning option이 "custom"일 시 pruning 간격 block 수

halt-height

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

halt-time

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

min-retain-blocks

• default: 0
• 커밋되고 있는 현재 블록으로부터 최소 block height offset을 설정하고, 이 offset을 지나는 모든 블록이 CometBFT에서 제거
• 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: []
• {eventyType}.{attributeKey} 형식으로 CometBFT에 index를 생성할 대상의 event set을 정의 (e.g. ["message.sender", "message.recipient"])
• default인 empty의 경우 모든 event를 index

iavl-cache-size

• default: 781250
• IAVL tree(Ethereum의 MPT 역할)의 내부 노드 크기
• 내부에 지정된 default 크기는 50MB(참고)

iavl-disable-fastnode

• default: false
• FastNode 모드는 노드의 state 동기화 및 state 접근 속도/디스크 사용량 감소를 개선하기 위한 기능. Merkle proof용 데이터를 유지하지 않고 빠른 상태 조회에 최적화 됨
• FastNode 모드가 실행되지 않을 때(true)는 전체 merkle proof 데이터를 저장 (full node나 light client 증명을 사용할 시 사용)
• FastNode 모드가 실행될 때(false = default 값)는 merkle proof 생성을 제한하거나 생략 (빠른 상태 동기화가 중요하거나 개발/테스트 환경에서 리소스 절약 시 사용)

app-db-backend

• default: ""
• Application이나 snapshots DB 사용을 위한 데이터베이스 backend 타입 설정
• 빈 값일 시 fallback이 사용됨을 나타내며, fallback은 CometBFT의 config.toml에 db_backend 값으로 설정됨

2. Telemetry config

Telemetry configuration은 원격 분석으로 모듈 및 애플리케이션에 대한 insight 수집을 위한 telemetry 사용 시의 설정값을 정의한다. Config 내에서 telemetry가 enable 된 경우 글로벌 메트릭 수집기(go-metrics)로 수집한다.

service-name

• default: ""
• 서비스 분류를 위하여 service name key값을 통한 prefix 설정

enabled

• default: false
• Telemetry 활성화

enable-hostname

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

enable-hostname-label, enable-service-label

• default: 각각 false
• 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

해당 노드의 HTTP write/read 기능 수행에 대한 설정값

enable

• default: false
• HTTP API server 사용 설정

swagger

• default: false
• Swagger 사용

address

• default: tcp://localhost:1317
• HTTP API server로 listening을 수행할 노출 address 정의

max-open-connections

• default: 1000
• API server에 연결될 최대 connection 수 설정

rpc-read-timeout

• default: 10
• CometBFT RPC read timeout 시간 설정 (second 단위)

rpc-write-timeout

• default: 0
• CometBFT RPC write timeout 시간 설정 (second 단위)

rpc-max-body-bytes

• default: 1000000
• CometBFT RPC의 최대 request body 사이즈 설정 (bytes 단위)

enabled-unsafe-cors

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

4. gRPC config

해당 노드의 gRPC write/read 기능 수행에 대한 설정값

enable

• default: true
• gRPC server 사용 설정

address

• default: localhost:9090
• gRPC server로 listening을 수행할 노출 address 정의

max-recv-msg-size

• default: 10485760 (1024 * 1024 * 10)
• gRPC server가 수용할 최대 메시지 사이즈

max-send-msg-size

• default: 2147483647 (Int32)
• gRPC server가 전송할 수 있는 최대 메시지 사이즈

5. gRPC Web config

해당 노드의 HTTP 기능을 수행할 수 있는 gRPC Web server의 설정값

enable

• default: true
• gRPC webserver 활성화

6. State Sync config

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

snapshot-interval

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

snapshot-keep-recent

• default: 2
• Snaptshot 제공을 위해 유지할 최신 snapshot 수 설정 (0은 모두 저장)

7. State Streaming

State를 외부 시스템에 real time 또는 near-real time으로 스트리밍 하는 기능 설정

keys

• default: []
• gRPC를 통하여 스트리밍으로 내보낼 KV store의 key들. Module들의 StoreKey 명칭과 동일해야 함
• e.g. ["acc", "back", "gov", "staking","mint"[,...]] / ["*"]의 경우 모든 key값들이 노출됨

plugin

• default: ""
• gRPC를 통하여 스트리밍 할 플러그인 명칭. Streaming은 이 값이 세팅되어야 실행됨
• 지원 plugins: abci

stop-node-on-err

• default: true
• Message 전달 에러가 발생 시 node를 멈추게 하는 설정

8. Mempool

Transaction들을 블록에 포함하기 전에 보관하는 각 노드별 memory pool의 설정

max-txs

• default: 5000
• 해당값이 0일 시 mempool내의 트랜잭션을 무제한으로 허용
• 해당값이 -1일 시 트랜잭션이 mempool에 삽입되지 않음 (no-op mempool)
• 해당값이 0보다 클 시 (>0) 지정된 양만큼만 mempool에 들어올 수 있는 트랜잭션으로 제한

---

config.toml

version

• CometBFT의 버전

1. Main Base Config Options

CometBFT의 기본적인 설정

proxy_app

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

moniker

• 해당 노드의 별명 (human readable name)

db_backend

• default: goleveldb
• DB backend의 설정. app.toml의 app-db-backend와 연계되어 설정
• options
  • goleveldb (github.com/syndtr/goleveldb): 가장 자주 사용, pure go, stable
  • cleveldb (uses levigo wrapper): 빠름, gcc 필요, cleveldb build tag 사용(go build -tags cleveldb)
  • doltdb (github.com/etcd-io/bbolt - etcd fork 사용): EXPERIMENTAL, 특정 use-cases에 더 빠름, boltdb build tag 사용(go build -tags boltdb)
  • rocksdb (github.com/tecbot/gorocksdb): EXPERIMENTAL, gcc 필요, rocksdb build tag 사용(go build -tags rocksdb)
  • badgerdb (github.com/dgraph-io/badger): EXPERIMENTAL, badgerdb build tag 사용(go build -tags badgerdb)

db_dir

• default: data
• DB 데이터 디렉토리 설정

log_level

• default: info
• 로그 레벨 설정

log_format

• default: plain
• options
  • plain: colored text
  • json: json 형식

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로 부터 CometBFT가 listen하여 connection이 되는 TCP 또는 UNIX socket 주소

abci

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

fileter_peers

• default: false
• true일 시 새로운 피어여 연결한다면 ABCI 애플리케이션에 쿼리하여 애플리케이션이 연결되는 유지 여부 설정

2. RPC Server Configuration Options

CometBFT가 외부로 통신하는 RPC server의 설정

laddr

• default: tcp://127.0.0.1:26657
• CometBFT RPC 서버 주소

cors_allowed_origins

• default: []
• CORS를 인정할 origin list
• ["*"]일 시 any로 설정됨

cors_allowed_methods

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

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은 무제한
• Should be < {ulimit -Sn} - {MaxNumInboundPeers} - {MaxNumOutboundPeers} - {N of wal, db and other open files}
• 1024 - 40 - 10 - 50 = 924 = ~900

unsafe

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

max_open_connections

• default: 900
• gRPC를 제외한 HTTP와 websocket에 연결 가능한 최대 숫자 설정
• 0은 무제한
• Should be < {ulimit -Sn} - {MaxNumInboundPeers} - {MaxNumOutboundPeers} - {N of wal, db and other open files}
• 1024 - 40 - 10 - 50 = 924 = ~900

max_subscription_clients

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

max_subscription_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 수를 지정
• 실험적인 파라미터
• 최소한 100은 설정하여 하며, 큰 값을 설정하는 경우 더 많은 memory를 사용하지만 높은 event 쓰루풋 rate를 가짐

experimental_websocket_write_buffer_size

• default: 200
• 각 websocket 클라이언트 당 RPC response의 최대 버퍼 수
• 실험적인 파라미터
• 클라이언트가 데이터를 websocket endpoint에서 빨리 read 못하면 disconnect되어 버퍼 사이즈를 늘리면 memory를 더 사용하지만 disconnect될 가능성이 줄어듬
• 적어도 experimental_subscription_buffer_size와 같아야 함

experimental_close_on_slow_client

• default: false
• Websocket client가 읽을 정도로 빠르지 못하면 error 생성이나 disconnect 대신 drop event를 제공

timeout_broadcast_tx_commit

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

max_body_bytes

• default: 1000000
• Request body의 최대 사이즈 (bytes 단위)

max_header_bytes

• default: 1048576
• Request header 최대 사이즈 (bytes 단위)

tls_cert_file, tls_key_file

• default: 각 ""
• HTTP server를 생성 시 사용되는 certificate 파일 path
• HTTP server를 생성 시에 tls_cert_file 및 tls_key_file은 반드시 CometBFT에 알려야 함

pprof_laddr

• default: localhost:6060
• pprof listen address (https://golang.org/pkg/net/http/pprof)

3. P2P Configuration Options

다른 노드들과 연결되는 P2P 설정

laddr

• default: ""
• Incoming connection 시의 listening 주소

external_address

• default: ""
• Dial 시 다른 피어들에게 알리는 주소, Empty 시 위의 laddr과 같음

seeds

• default: ""
• 연결 대상 seed node의 리스트
• 각 시드노드들은 comma로 구분되어야 함

persistent_peers

• default: ""
• 지속적으로 운영되고 있다고 믿을 수 있는 persistent peer들의 리스트
• 각 persistent피어들은 comma로 구분되어야 함

addr_book_file

• default: config/addrbook.json
• Address book 파일의 위치 설정

addr_book_strict

• default: true
• 엄격한 주소 라우팅 규칙에 대해서는 true로 설정하고, private 또는 local network에서는 false로 설정

max_num_inbound_peers

• default: 40
• Inbound peer로 연결할 최대 수

max_num_outbound_peers

• default: 10
• Outbound peer로 연결할 최대 수

unconditional_peer_ids

• default: ""
• Connection 설정 가능한 node ID 리스트
• 해당 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 사이즈 (bytes 단위)

send_rate

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

recv_rate

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

pex

• default: true
• Peer-exchange reactor의 실행 설정

seed_mode

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

private_peers_ids

• default: ""
• Private로 유지하기 위한 peer ID 리스트
• Private peer는 다른 peer들에 gossip 되지 않음

allow_duplicate_ip

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

handshake_timeout, dial_timeout

• default: 각 20s, 3s
• 피어 연결 타임아웃 설정

4. Mempool Configuration Options

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

type

• default: flood
• Mempool 타입 설정
• options
  • floods: flooding 가십 프로토콜을 사용한 동시 연결 리스트 mempool
  • nop: nop-mempool(no operation의 약자. ABCI 앱은 tx를 저장하고, 배포하고, 제안하는 역할을 수행). create_empty_blocks=false는 되지 않음

recheck

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

recheck_timeout

• default: 1s
• recheck를 수행 시 대기하는 timeout 시간

broadcast

• default: true
• 트랜잭션 다른 peer들 에게 broadcast를 할지 말지 설정

wal_dir

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

size

• default: 5000
• Mempool 내에 포함 가능한 트랜잭션 최대 숫자

max_txs_bytes

• default: 1073741824
• Mempool의 트랜잭션 수용 가능한 total size

cache-size

• default: 10000
• 일찍 발견된 트랜잭션들의 filtering을 위해 사용되는 캐시의 사이즈 설정

keep-invalid-txs-in-cache

• default: false
• Cache에서 invalid 트랜잭션들을 제거하지 않을 것을 설정 (default false로 제거하지 않음)
• true 시 invalid transaction들이 valid로 변경되는 것이 불가

max_tx_bytes

• default: 1048576
• Mempool에 입력 가능한 하나의 트랜잭션 최대 크기

max_batch_bytes

• default: 0
• Reactor는 연결된 피어에게 batch로 트랜잭션을 보내는데, 이 배치의 최대 크기 설정
• 현재 사용되지 않음 (https://github.com/tendermint/tendermint/issues/5796)

experimental_max_gossip_connections_to_persistent_peers, experimental_max_gossip_connections_to_non_persistent_peers

• default: 각 0, 0
• Gossip tx를 지정된 피어수 까지 제한하는 설정값
• Unconditional peer는 해당 설정값에 영향받지 않음
• Persistent peer 중 하나가 연결이 끊어지면 다른 persistent 피어를 활성화하고 non-persistent peer도 동일한 동작
• 0으로 설정하면 해당 피어 그룹에 대하여 기능이 비활성화 (해당 피어 그룹에 대한 활성 연결 수가 제한되지 않음)
• 성능 결과 상 10이 권장

5. State Sync Configuration Options

블록 데이터 동기화를 위한 설정

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
• 복원을 시작하기 전에 스냅샷을 검색 시 걸리는 시간

temp_dir

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

chunk_request_timeout

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

chunk_fetchers

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

6. Block Sync Configuration Options

Block sync 프로토콜 설정

version

• default: v0
• Block sync version
• v0.37에서 블록 sync 프로토콜인 v1과 v2가 deprecated

7. Consensus Configuration Options

Block 생성을 위한 validator 간의 합의 설정

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
• #mpty block 간 지속 생성 시 interval

peer_gossip_sleep_duration, peer_query_maj23_sleep_duration

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

8. Storage Configuration Options

State 스토리지 절약 기능 설정

discard_abci_responses

• default: false
• true로 설정하면 state store에서 ABCI 응답을 삭제하여 다량의 디스크 공간을 절약 가능
• false로 설정하면 ABCI 응답이 지속되도록 설정 가능
• ABCI 응답은 /block_results RPC 쿼리와 command line에서 이벤트를 다시 인덱싱하는 데 필요

9. Transaction Indexer Configuration Options

블록에 포함되는 트랜잭션들의 indexing을 지원

indexer

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

10. Instrumentation Configuration Options

prometheus

• default: false
• true일 시 prometheus metrics가 서비스 실행됨

prometheus_listen_addr

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

max_open_connections

• default: 3
• 동시 connection 최대 수
• 0일 시 제한 없음
• 기본값보다 더 큰수를 사용 시 os limit까지 증가 가능

namespace

• default: cometbft
• Instrumentation namespace