Document bitcoind RPC authentication options (ordinals#2056)

README.md

@@ -107,6 +107,43 @@ If `bitcoind` is not on mainnet, is not run by the same user, has a non-default
 datadir, or a non-default port, you'll need to pass additional flags to `ord`.
 See `ord --help` for details.
 
+`bitcoind` RPC Authentication
+-----------------------------
+
+`ord` makes RPC calls to `bitcoind`, which usually require a username and
+password.
+
+By default, `ord` looks a username and password in the cookie file created by
+`bitcoind`.
+
+The cookie file path can be configured using `--cookie-file`:
+
+```
+ord --cookie-file /path/to/cookie/file server
+```
+
+Alternatively, `ord` can be supplied with a username and password on the
+command line:
+
+```
+ord --bitcoin-rpc-user foo --bitcoin-rpc-pass bar server
+```
+
+Using environment variables:
+
+```
+export ORD_BITCOIN_RPC_USER=foo
+export ORD_BITCOIN_RPC_PASS=bar
+ord server
+```
+
+Or in the config file:
+
+```yaml
+bitcoin_rpc_user: foo
+bitcoin_rpc_pass: bar
+```
+
 Logging
 --------
 

ord.yaml

@@ -1,5 +1,9 @@
 # Example Config
 
+# use username `bar` and password `foo` for bitcoind RPC calls
+bitcoin_rpc_user: bar
+bitcoin_rpc_pass: foo
+
 # prevent `ord server` from serving the content of the inscriptions below
 hidden:
 - 6fb976ab49dcec017f1e201e84395983204ae1a7c2abf7ced0a85d692e442799i0

src/config.rs

@@ -1,10 +1,11 @@
 use super::*;
 
 #[derive(Deserialize, Default, PartialEq, Debug)]
+#[serde(deny_unknown_fields)]
 pub(crate) struct Config {
  pub(crate) hidden: HashSet<InscriptionId>,
- pub(crate) rpc_pass: Option<String>,
- pub(crate) rpc_user: Option<String>,
+ pub(crate) bitcoin_rpc_pass: Option<String>,
+ pub(crate) bitcoin_rpc_user: Option<String>,
 }
 
 impl Config {
@@ -35,4 +36,9 @@ mod tests {
  assert!(config.is_hidden(a));
  assert!(!config.is_hidden(b));
  }
+
+ #[test]
+ fn example_config_file_is_valid() {
+ let _: Config = serde_yaml::from_reader(File::open("ord.yaml").unwrap()).unwrap();
+ }
 }

src/options.rs

@@ -170,14 +170,14 @@ impl Options {
  let rpc_user = Options::derive_var(
  self.bitcoin_rpc_user.as_deref(),
  Some("BITCOIN_RPC_USER"),
- config.rpc_user.as_deref(),
+ config.bitcoin_rpc_user.as_deref(),
  None,
  )?;
 
  let rpc_pass = Options::derive_var(
  self.bitcoin_rpc_pass.as_deref(),
  Some("BITCOIN_RPC_PASS"),
- config.rpc_pass.as_deref(),
+ config.bitcoin_rpc_pass.as_deref(),
  None,
  )?;
 
@@ -620,7 +620,11 @@ mod tests {
  fn config_with_rpc_user_pass() {
  let tempdir = TempDir::new().unwrap();
  let path = tempdir.path().join("ord.yaml");
- fs::write(&path, "hidden:\nrpc_user: foo\nrpc_pass: bar").unwrap();
+ fs::write(
+ &path,
+ "hidden:\nbitcoin_rpc_user: foo\nbitcoin_rpc_pass: bar",
+ )
+ .unwrap();
 
  assert_eq!(
  Arguments::try_parse_from(["ord", "--config", path.to_str().unwrap(), "index",])
@@ -629,8 +633,8 @@ mod tests {
  .load_config()
  .unwrap(),
  Config {
- rpc_user: Some("foo".into()),
- rpc_pass: Some("bar".into()),
+ bitcoin_rpc_user: Some("foo".into()),
+ bitcoin_rpc_pass: Some("bar".into()),
  ..Default::default()
  }
  );