bitcoin-cli 기초

bitcoin-cli 프로그램은 Bitcoin의 Command Line 클라이언트 프로그램으로서, 커맨드 아규먼트로부터 명령어(메서드)를 입력 받아 이를 JSON-RPC로 변환하여 Bitcoin 노드 (bitcoind)에게 전달/호출한 후 그 결과를 콘솔에 출력하는 기능을 제공한다.

bitcoin-cli 는 JSON-RPC request를 호출하기 위해 다음과 같은 포트를 사용한다. 예를 들어, 로컬에 있는 bitcoind 에게 JSON-RPC를 호출하기 위해 testnet 의 경우 "127.0.0.1:18332" 를 사용한다.

    mainnet: 8332
    testnet: 18332
    regtest: 18443

bitcoin-cli 도움말

bitcoin-cli 는 커맨드 라인 프로그램으로, bitcoin-cli 뒤에 일반적으로 명령어^{(혹은 호출 메서드)} 를 적고, 그 뒤에 해당 명령에 필요한 파라미터를 넣게 된다.

bitcoin-cli 프로그램은 매우 많은 명령들과 파라미터들을 갖고 있는데, 어떤 명령과 파라미터가 있는지를 알기 위해 help 명령을 사용할 수 있다.

    $ bitcoin-cli help                  (전체 명령에 대한 도움말)
    $ bitcoin-cli help getnewaddress    (특정 명령 getnewaddress 에 대한 도움말)

bitcoin-cli 사용법

bitcoin-cli 프로그램은 기본적으로 다음과 같은 구문으로 사용한다.
(1) bitcoin-cli 바로 뒤에 옵션(options)을 줄 수 있는데, 예를 들어 -datadir, -chain, -testnet, -rpcconnect, -rpcwallet 등과 같은 여러가지 옵션들을 줄 수 있다. 선택적인 옵션(options) 뒤에는 명령(command)를 주게 되는데, 예를 들어 getbalance, getnewaddress 등과 같은 명령을 주게 되고, 명령(command) 뒤에는 해당 명령에 필요한 파라미터들(params)를 순서대로 넣게 된다(positional arguments).
(2) 만약 명령의 파라미터들을 이름별로 넣는 경우(named arguments) 두번째 구문을 사용한다. 즉, -named 를 명령 앞에 쓰고 name=value 형식으로 파라미터를 적게 된다. (아래 bitcoin-cli 아규먼트 전달 섹션 참고)
(3) 마지막으로 도움말을 표시하는 help는 help 뒤에 원하는 명령어를 적으면 된다.

    (1) bitcoin-cli [options] (command) [params]  
    (2) bitcoin-cli [options] -named (command) [name=value]... 
    (3) bitcoin-cli [options] help (command)  

bitcoin-cli 간단한 조회

bitcoin-cli 에서 간단한 명령을 수행하기 위해 블럭체인이나 월렛 정보를 간단하게 조회해 볼 수 있다.

예를 들어, 아래 명령은 블렉체인의 기본 정보를 조회하는 명령이다. 이 명령의 결과를 살펴 보면, 현재 연결된 블럭체인(chain)은 testnet 이고, 현재 블럭 수(blocks) 는 2161821 이고, 전체 블럭체인 사이즈(size_on_disk)는 약 30 GB (30625171070) 임을 알 수 있다.

$ bitcoin-cli getblockchaininfo
{
    "chain": "test",
    "blocks": 2161821,
    "headers": 2161821,
    "bestblockhash": "0000000000000c38ab41faa3ed46cc56d91284b37ce5abc5b8fc7f108b19ce8f",
    "difficulty": 1323722.924123052,
    "mediantime": 1645207147,
    "verificationprogress": 0.9999997205124377,
    "initialblockdownload": false,
    "chainwork": "00000000000000000000000000000000000000000000064792284fc79541ab9a",
    "size_on_disk": 30625171070,
    "pruned": false,
    "softforks": {
        "bip34": {
            "type": "buried",
            "active": true,
            "height": 21111
        },
        "bip66": {
            "type": "buried",
            "active": true,
            "height": 330776
        },
        "bip65": {
            "type": "buried",
            "active": true,
            "height": 581885
        },
        "csv": {
            "type": "buried",
            "active": true,
            "height": 770112
        },
        "segwit": {
            "type": "buried",
            "active": true,
            "height": 834624
        }
    },
    "warnings": "Warning: unknown new rules activated (versionbit 28)"
}

bitcoin-cli 에는 위와 같은 조회 명령이 많이 제공되는데, 이 중 자주 사용되는 몇가지를 들어 보면 다음과 같다.

    $ bitcoin-cli getblockchaininfo
    $ bitcoin-cli getwalletinfo
    $ bitcoin-cli getbalance
    $ bitcoin-cli getblockcount
    $ bitcoin-cli getblockinfo {blkheight}
    $ bitcoin-cli getblock {blkhash}
    $ bitcoin-cli getrawtransaction {txid}
    $ bitcoin-cli decoderawtransaction {rawtx}

bitcoin-cli 아규먼트 전달

bitcoin-cli 프로그램에서 아규먼트를 전달하는 방법은 크게 2가지가 있는데, (1) 아규먼트들의 위치에 맞춰 순서대로 전달하는 positional argument 방법과 (2) 순서와 상관없이 아규먼트들의 이름을 적고 그 뒤에 값을 적는 named argument 방법이 있다.

예를 들어, 현재 자신의 월렛이 가지고 있는 코인 잔액을 알아내기 위해 getbalance 를 사용할 수 있는데, 이 명령은 4개의 아규먼트를 가지고 있다. getbalance가 어떤 아규먼트들을 가지고 있는지를 체크하기 위해서는 아래와 같이 help 명령을 사용하면 된다.

$ bitcoin-cli help getbalance
getbalance ( "dummy" minconf include_watchonly avoid_reuse )

Returns the total available balance.

Arguments:
1. dummy (string, optional) Remains for backward compatibility. Must be excluded or set to "*".
2. minconf (numeric, optional, default=0) Only include transactions confirmed at least this many times.
3. include_watchonly (boolean, optional, default=true)
4. avoid_reuse (boolean, optional, default=true)

위 도움말에서 알 수 있듯이, getbalance 는 dummy, minconf, include_watchonly, avoid_reuse 등 4개의 아규먼트를 가지고 있고, optional 아규먼트의 경우 그 디폴트 값을 가지고 있다. getbalance 의 경우 4개 모두 optional 아규먼트이므로 특별히 아규먼트를 지정할 필요는 없다.

Positional argument

하지만, 옵션을 지정하고 싶은 경우, positional argument 방식의 경우 아규먼트의 순서를 지켜야 한다. 예를 들어, minconf 파라미터를 지정하고 싶으면, 첫번째 파라미터를 지정한 후, 두번째에서 그 값(6)을 넣어 주어야 한다. 이는 최소 6 confirmation 이 확인된 밸런스만을 표시하게 된다.

    $ bitcoin-cli getbalance "*" 6

Named argument

아규먼트가 많은 경우나 아규먼트의 의미를 쉽게 알 수 있게 하기 위해서 named argument 방식을 종종 사용한다. named argument 방식을 사용하기 위해서는 bitcoin-cli 뒤에 -named 를 붙여 사용한다. 위의 명령은 아래와 같이 named argument 방식으로 바꿔 쓸 수 있다.

    $ bitcoin-cli -named getbalance minconf=6