El programa principal en una instalación de Bitcoin es “bitcoind”, que mina, valida transacciones e intercambia bloques.
bitcoin-cli es un programa que viene con el nodo de Bitcoin y que nos sirve de consola para consultar su estado, hacer operaciones criptográficas y obtener información de los bloques, entre otros. Se trata de un programa totalmente separado de bitcoind, pero que se compila a la misma vez y tiene partes de código fuente en común.
Configuración de RPC
bitcoin-cli se conecta con el nodo usando una conexión RPC. Este canal no siempre está habilitado en bitcoind. Cuando bitcoind arranca lo hace con opciones por defecto y si queremos modificar ese comportamiento tenemos 2 vías: introducir opciones en linea de comando cuando se lanza bitcoind (ej: -debug -rpcport=8332, …) o introducir esos mismos valores en el fichero bitcoin.conf que encontramos habitualmente en el directorio $HOME/.bitcoin del usuario que ejecuta el nodo.
Todas las opciones disponibles en linea de comando las obtenemos ejecutando "bitcoin-cli -help".
Nos decantamos por mantener los parámetros en el fichero bitcoin.conf porque es más ordenado y sencillo de mantener y documentar.
Un ejemplo típico de configuración RPC en bitcoin.conf podría ser:
[...]
rcpallowip=0.0.0.0/0
rpcbind=127.0.0.1
rpcpassword=password
rpcuser=bitcoin
#rpcport=8332
[...]
En mi experiencia, si no ponemos rpcuser y rpcpassword no vamos a poder conectarnos con el nodo. El rpcport por defecto es 8332 en la cadena de bloques principal o mainnet, 18832 para testnet y 9332 para la stn. Por seguridad, escuchamos solo en la ip localhost para evitar que nuestro nodo pueda ser usado desde internet.
Cualquier cambio en bitcoin.conf requiere un reinicio del nodo. Por más veces que he parado y arrancado un nodo siempre vuelve consistente al punto donde lo dejó sin perder datos y continúa su tarea, así que, es tu decisión, pero yo no tengo miedo de reiniciar mi nodo.
Ejecución básica
Una vez configurado RPC ya podemos usar el comando bitcoin-cli. Es interesante saber que si tenemos varios nodos accesibles entre sí, desde el mismo bitcoin-cli podemos hacer consultas en todos ellos.
Un ejemplo básico sería:
bitcoin-cli -conf=/home/bitcoin/.bitcoin/bitcoin.conf getblockchaininfo
El subcomando “getblockchaininfo” obtiene el estado del nodo y lo muestra en formato JSON. Observa que solo indicamos el fichero de configuración del nodo como única opción. bitcoin-cli tiene en ese fichero todo lo que necesita como el usuario, la password, el puerto y la IP en la que escucha bitcoind.
Otra posibilidad a medio camino es indicar algunos parámetros y que asuma que otros (puerto, host, etc…) son los default:
bitcoin-cli -rpcuser=bitcoin -rpcpassword=password getblockchaininfo
Subcomandos bitcoin-cli
Hay muchos subcomandos de bitcoin-cli. Eso nos indica que el nodo bitcoind hace demasiadas cosas y que se avecina una división/especialización …
Para descubrir los subcomandos ejecuta el siguiente comando conectando con tu nodo (no lleva “-”):
bitcoin-cli help
Lista completa de comandos bitcoin-cli
La siguiente es la lista en un nodo BitcoinSV 1.0.3:
== Blockchain ==
getbestblockhash
getblock "blockhash" ( verbosity )
getblockchaininfo
getblockcount
getblockhash height
getblockheader "hash" ( verbose )
getchaintips
getchaintxstats ( nblocks blockhash )
getdifficulty
getmempoolancestors txid (verbose)
getmempooldescendants txid (verbose)
getmempoolentry txid
getmempoolinfo
getrawmempool ( verbose )
gettxout "txid" n ( include_mempool )
gettxoutproof ["txid",...] ( blockhash )
gettxoutsetinfo
preciousblock "blockhash"
pruneblockchain
verifychain ( checklevel nblocks )
verifytxoutproof "proof"
== Control ==
getinfo
getmemoryinfo
help ( "command" )
stop
uptime
== Generating ==
generate nblocks ( maxtries )
generatetoaddress nblocks address (maxtries)
== Mining ==
getblocktemplate ( TemplateRequest )
getminingcandidate coinbase (optional, default false)
getmininginfo
getnetworkhashps ( nblocks height )
prioritisetransaction <txid> <priority delta> <fee delta>
submitblock "hexdata" ( "jsonparametersobject" )
submitminingsolution "<json string>"
== Network ==
addnode "node" "add|remove|onetry"
clearbanned
disconnectnode "[address]" [nodeid]
getaddednodeinfo ( "node" )
getconnectioncount
getexcessiveblock
getnettotals
getnetworkinfo
getpeerinfo
listbanned
ping
setban "subnet" "add|remove" (bantime) (absolute)
setexcessiveblock blockSize
setnetworkactive true|false
settxnpropagationfreq freq
== Rawtransactions ==
createrawtransaction [{"txid":"id","vout":n},...] {"address":amount,"data":"hex",...} ( locktime )
decoderawtransaction "hexstring"
decodescript "hexstring"
fundrawtransaction "hexstring" ( options )
getrawtransaction "txid" ( verbose )
sendrawtransaction "hexstring" ( allowhighfees )
signrawtransaction "hexstring" ( [{"txid":"id","vout":n,"scriptPubKey":"hex","redeemScript":"hex"},...] ["privatekey1",...] sighashtype )
== Util ==
createmultisig nrequired ["key",...]
estimatefee nblocks
signmessagewithprivkey "privkey" "message"
validateaddress "address"
verifymessage "address" "signature" "message"
== Wallet ==
abandontransaction "txid"
addmultisigaddress nrequired ["key",...] ( "account" )
backupwallet "destination"
dumpprivkey "address"
dumpwallet "filename"
encryptwallet "passphrase"
getaccount "address"
getaccountaddress "account"
getaddressesbyaccount "account"
getbalance ( "account" minconf include_watchonly )
getnewaddress ( "account" )
getrawchangeaddress
getreceivedbyaccount "account" ( minconf )
getreceivedbyaddress "address" ( minconf )
gettransaction "txid" ( include_watchonly )
getunconfirmedbalance
getwalletinfo
importaddress "address" ( "label" rescan p2sh )
importmulti "requests" "options"
importprivkey "bitcoinprivkey" ( "label" ) ( rescan )
importprunedfunds
importpubkey "pubkey" ( "label" rescan )
importwallet "filename"
keypoolrefill ( newsize )
listaccounts ( minconf include_watchonly)
listaddressgroupings
listlockunspent
listreceivedbyaccount ( minconf include_empty include_watchonly)
listreceivedbyaddress ( minconf include_empty include_watchonly)
listsinceblock ( "blockhash" target_confirmations include_watchonly)
listtransactions ( "account" count skip include_watchonly)
listunspent ( minconf maxconf ["addresses",...] [include_unsafe] )
listwallets
lockunspent unlock ([{"txid":"txid","vout":n},...])
move "fromaccount" "toaccount" amount ( minconf "comment" )
removeprunedfunds "txid"
sendfrom "fromaccount" "toaddress" amount ( minconf "comment" "comment_to" )
sendmany "fromaccount" {"address":amount,...} ( minconf "comment" ["address",...] )
sendtoaddress "address" amount ( "comment" "comment_to" subtractfeefromamount )
setaccount "address" "account"
settxfee amount
signmessage "address" "message"