flywithu/Learning-Bitcoin-from-the-Command-Line
1
1
Fork 0
mirror of https://github.com/ChristopherA/Learning-Bitcoin-from-the-Command-Line.git synced 2025-06-08 00:16:26 +00:00
Code Issues Releases Wiki Activity

Create 12_1_Accessing_Bitcoind_with_Curl.md

Browse Source
This commit is contained in:
Shannon Appelcline 2017-06-14 11:29:03 -07:00 committed by GitHub
parent 7621acef9f
commit b31410a63c
1 changed files with 27 additions and 28 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

55
12_1_Accessing_Bitcoind_with_Curl.md
View File

@ -14,36 +14,28 @@ In order to use `curl` with `bitcoind`, you must know three things: the standard
The `bitcoin-cli` commands are all linked to the RPC commands in `bitcoind`. That makes the transition from using `bitcoin-cli` to using `curl` very simply. In fact, if you look at any of the help pages for `bitcoin-cli`, you'll see that they list not only the `bitcoin-cli` command, but also a parallel `curl` command. For example, here is `bitcoin-cli getinfo help`: The `bitcoin-cli` commands are all linked to the RPC commands in `bitcoind`. That makes the transition from using `bitcoin-cli` to using `curl` very simply. In fact, if you look at any of the help pages for `bitcoin-cli`, you'll see that they list not only the `bitcoin-cli` command, but also a parallel `curl` command. For example, here is `bitcoin-cli getinfo help`:
``` ```
$ bitcoin-cli help getinfo $ bitcoin-cli help getmininginfo
getinfo getmininginfo
DEPRECATED. Returns an object containing various state info.
Returns a json object containing mining-related information.
Result: Result:
{ {
"version": xxxxx, (numeric) the server version "blocks": nnn, (numeric) The current block
"protocolversion": xxxxx, (numeric) the protocol version "currentblocksize": nnn, (numeric) The last block size
"walletversion": xxxxx, (numeric) the wallet version "currentblockweight": nnn, (numeric) The last block weight
"balance": xxxxxxx, (numeric) the total bitcoin balance of the wallet "currentblocktx": nnn, (numeric) The last block transaction
"blocks": xxxxxx, (numeric) the current number of blocks processed in the server "difficulty": xxx.xxxxx (numeric) The current difficulty
"timeoffset": xxxxx, (numeric) the time offset "errors": "..." (string) Current errors
"connections": xxxxx, (numeric) the number of connections "networkhashps": nnn, (numeric) The network hashes per second
"proxy": "host:port", (string, optional) the proxy used by the server "pooledtx": n (numeric) The size of the mempool
"difficulty": xxxxxx, (numeric) the current difficulty "chain": "xxxx", (string) current network name as defined in BIP70 (main, test, regtest)
"testnet": true|false, (boolean) if the server is using testnet or not
"keypoololdest": xxxxxx, (numeric) the timestamp (seconds since Unix epoch) of the oldest pre-generated key in the key pool
"keypoolsize": xxxx, (numeric) how many new keys are pre-generated
"unlocked_until": ttt, (numeric) the timestamp in seconds since epoch (midnight Jan 1 1970 GMT) that the wallet is unlocked for transfers, or 0 if the wallet is locked
"paytxfee": x.xxxx, (numeric) the transaction fee set in BTC/kB
"relayfee": x.xxxx, (numeric) minimum relay fee for non-free transactions in BTC/kB
"errors": "..." (string) any error messages
} }
Examples: Examples:
> bitcoin-cli getinfo > bitcoin-cli getmininginfo
> curl --user myusername --data-binary '{"jsonrpc": "1.0", "id":"curltest", "method": "getinfo", "params": [] }' -H 'content-type: text/plain;' http://127.0.0.1:8332/ > curl --user myusername --data-binary '{"jsonrpc": "1.0", "id":"curltest", "method": "getmininginfo", "params": [] }' -H 'content-type: text/plain;' http://127.0.0.1:8332/
``` ```
This somewhat lengthy command has four major parts: (1) a listing of your user name; (2) a ``--data-binary` flag; (3) a JSON object that tells `bitcoind` what to do; and (4) an HTTP header that includes the URL to talk to. When you are working with `curl`, most of this will stay the same from command to command, other than the `method` and `params` entries in the JSON array. However, you need to know how to fill in your username and your URL address in order to make it work in the first place! And there's the `curl` command, at the end of the help screen! This somewhat lengthy command has four major parts: (1) a listing of your user name; (2) a `--data-binary` flag; (3) a JSON object that tells `bitcoind` what to do; and (4) an HTTP header that includes the URL to talk to. When you are working with `curl`, most of this will stay the same from command to command, other than the `method` and `params` entries in the JSON array. However, you need to know how to fill in your username and your URL address in order to make it work in the first place!
### Know Your User Name ### Know Your User Name
@ -67,14 +59,14 @@ Clearly, our user is `bitcoinrpc` and our password is `d8340efbcd34e312044c8431c
The secure way to access your user name is as follows: The secure way to access your user name is as follows:
``` ```
$ curl --user bitcoinrpc --data-binary '{"jsonrpc": "1.0", "id":"curltest", "method": "getinfo", "params": [] }' -H 'content-type: text/plain;' http://127.0.0.1:8332/ $ curl --user bitcoinrpc --data-binary '{"jsonrpc": "1.0", "id":"curltest", "method": "getmininginfo", "params": [] }' -H 'content-type: text/plain;' http://127.0.0.1:8332/
Enter host password for user 'bitcoinrpc': Enter host password for user 'bitcoinrpc':
``` ```
As noted, you will be prompted for your password. As noted, you will be prompted for your password.
The insecure way to do so is as follows: The insecure way to do so is as follows:
``` ```
$ curl --user bitcoinrpc:d8340efbcd34e312044c8431c59c792c --data-binary '{"jsonrpc": "1.0", "id":"curltest", "method": "getinfo", "params": [] }' -H 'content-type: text/plain;' http://127.0.0.1:8332/ $ curl --user bitcoinrpc:d8340efbcd34e312044c8431c59c792c --data-binary '{"jsonrpc": "1.0", "id":"curltest", "method": "getmininginfo", "params": [] }' -H 'content-type: text/plain;' http://127.0.0.1:8332/
``` ```
> **WARNING:** Entering your password on the command line may put your password into the process table and/or save it into a history. It's not recommended, except for testing on testnet. If you want to do it anywhere else, make sure you know what you're doing! > **WARNING:** Entering your password on the command line may put your password into the process table and/or save it into a history. It's not recommended, except for testing on testnet. If you want to do it anywhere else, make sure you know what you're doing!
@ -86,16 +78,23 @@ The port should be easy, it's the `http://127.0.0.1:8332/` shown in the tutorial
However, with the right port number in hand, you should now be able to `curl` out to the `bitcoind`: However, with the right port number in hand, you should now be able to `curl` out to the `bitcoind`:
``` ```
$ curl --user bitcoinrpc:d8340efbcd34e312044c8431c59c792c --data-binary '{"jsonrpc": "1.0", "id":"curltest", "method": "getinfo", "params": [] }' -H 'content-type: text/plain;' http://127.0.0.1:18332/ $ curl --user bitcoinrpc:d8340efbcd34e312044c8431c59c792c --data-binary '{"jsonrpc": "1.0", "id":"curltest", "method": "getmininginfo", "params": [] }' -H 'content-type: text/plain;' http://127.0.0.1:18332/
{"result":{"version":140100,"protocolversion":70015,"walletversion":130000,"balance":2.41850000,"blocks":1128598,"timeoffset":0,"connections":11,"proxy":"","difficulty":1,"testnet":true,"keypoololdest":1494285051,"keypoolsize":100,"paytxfee":0.00000000,"relayfee":0.00001000,"errors":""},"error":null,"id":"curltest"} {"result":{"blocks":1128599,"currentblocksize":0,"currentblockweight":0,"currentblocktx":0,"difficulty":1,"errors":"Warning: unknown new rules activated (versionbit 28)","networkhashps":8658807967387.751,"pooledtx":0,"chain":"test"},"error":null,"id":"curltest"}
``` ```
You'll note that the result is another JSON array, which is kind of ugly to read if you're using `curl` by hand. That's why `bitcoin-cli` and `curl` libraries exist. But, for the moment, we'll struggle through the JSON inputs and outputs, to understand this as the low-level. You'll note that the result is another JSON array, which is kind of ugly to read if you're using `curl` by hand. That's why `bitcoin-cli` and `curl` libraries exist. But, for the moment, we'll struggle through the JSON inputs and outputs, to understand this as the low-level.
> **WARNING:** If you get a result like "Failed to connect to 127.0.0.1 port 8332: Connection refused", be sure that a line like `rpcallowip=127.0.0.1` is in your ~/.bitcoin/bitcoin.conf. If things still don't work, be sure that you're allowing access to port 18332 (or 8332) from localhost. Our standard setup from [Chapter Two: Creating a Bitcoin-Core VPS](02_0_Setting_Up_a_Bitcoin-Core_VPS.md) should do all of this. > **WARNING:** If you get a result like "Failed to connect to 127.0.0.1 port 8332: Connection refused", be sure that a line like `rpcallowip=127.0.0.1` is in your ~/.bitcoin/bitcoin.conf. If things still don't work, be sure that you're allowing access to port 18332 (or 8332) from localhost. Our standard setup from [Chapter Two: Creating a Bitcoin-Core VPS](02_0_Setting_Up_a_Bitcoin-Core_VPS.md) should do all of this.
## Understand the Limits of RPC
In each of these three chapters about accessing `bitcoind` via RPC, we're going to quickly run through lessons already learned, about wallet access and about sending raw transactions, as a guide to getting you started if you choose to use this message of access. Expect all of these access methods to be _harder_ than when you were working directly with `bitcoin-cli`.
There's a reason for this: `bitcoin-cli` actually provides two sorts of functionality. First, it gives you access to the RPC commands of `bitcoind`; and second, it proides you with basic wallet functionality while accessing those RPC commands. Now that you're accessing RPC commands directly, those wallet shortcuts are going to go away, leaving you on your own to deal with the wilds of Bitcoin. Mind you, this isn't necessarily a bad thing. When a programmer starts working with Bitcoin, often one of the first things he does is write a new set wallet functionality. Because he _needs_ it when working with Bitcoin more directly.
So, welcome to the club.
## Manipulate Your Wallet ## Manipulate Your Wallet
### Understand the Dangers of Curl
## Create a Transaction ## Create a Transaction