extra/bitcoin/client/client-docs.factor

   1 ! Copyright (C) 2010 Chris Double.
   2 ! See https://factorcode.org/license.txt for BSD license.
   3 USING: assocs help.markup help.syntax kernel math sequences strings ;
   4 IN: bitcoin.client
   5
   6 HELP: bitcoin-server
   7 { $values
   8   { "string" string }
   9 }
  10 { $description
  11     "Returns the hostname of the json-rpc server for the bitcoin client. "
  12     "This defaults to 'localhost' or the value of the 'bitcoin-server' "
  13     "variable."
  14 }
  15 { $see-also bitcoin-port bitcoin-user bitcoin-password } ;
  16
  17 HELP: bitcoin-port
  18 { $values
  19   { "n" number }
  20 }
  21 { $description
  22     "Returns the port of the json-rpc server for the bitcoin client. "
  23     "This defaults to '8332' or the value of the 'bitcoin-port' "
  24     "variable."
  25 }
  26 { $see-also bitcoin-server bitcoin-user bitcoin-password } ;
  27
  28 HELP: bitcoin-user
  29 { $values
  30   { "string" string }
  31 }
  32 { $description
  33     "Returns the username required to authenticate with the json-rpc "
  34     "server for the bitcoin client. This defaults to empty or the "
  35     "value of the 'bitcoin-user' variable."
  36 }
  37 { $see-also bitcoin-port bitcoin-server bitcoin-password } ;
  38
  39 HELP: bitcoin-password
  40 { $values
  41   { "string" string }
  42 }
  43 { $description
  44     "Returns the password required to authenticate with the json-rpc "
  45     "server for the bitcoin client. This returns the "
  46     "value of the 'bitcoin-password' variable."
  47 }
  48 { $see-also bitcoin-port bitcoin-server bitcoin-user } ;
  49
  50 HELP: get-addresses-by-label
  51 { $values
  52   { "label" string }
  53   { "seq" sequence }
  54 }
  55 { $description
  56     "Returns the list of addresses with the given label."
  57 } ;
  58
  59 HELP: get-balance
  60 { $values
  61   { "n" number }
  62 }
  63 { $description
  64     "Returns the server's available balance."
  65 } ;
  66
  67 HELP: get-block-count
  68 { $values
  69   { "n" number }
  70 }
  71 { $description
  72     "Returns the number of blocks in the longest block chain."
  73 } ;
  74
  75 HELP: get-block-number
  76 { $values
  77   { "n" number }
  78 }
  79 { $description
  80     "Returns the block number of the latest block in the longest block chain."
  81 } ;
  82
  83 HELP: get-connection-count
  84 { $values
  85   { "n" number }
  86 }
  87 { $description
  88     "Returns the number of connections to other nodes."
  89 } ;
  90
  91 HELP: get-difficulty
  92 { $values
  93   { "n" number }
  94 }
  95 { $description
  96     "Returns the proof-of-work difficulty as a multiple of the minimum "
  97     "difficulty."
  98 } ;
  99
 100 HELP: get-generate
 101 { $values
 102   { "?" boolean }
 103 }
 104 { $description
 105     "Returns true if the server is trying to generate bitcoins, false "
 106     "otherwise."
 107 } ;
 108
 109 HELP: set-generate
 110 { $values
 111   { "gen" boolean }
 112   { "n" number }
 113 }
 114 { $description
 115     "If 'gen' is true, the server starts generating bitcoins. If 'gen' is "
 116     "'false' then the server stops generating bitcoins. 'n' is the number "
 117     "of CPU's to use while generating. A value of '-1' means use all the "
 118     "CPU's available."
 119 } ;
 120
 121 HELP: get-info
 122 { $values
 123   { "result" assoc }
 124 }
 125 { $description
 126     "Returns an assoc containing server information."
 127 } ;
 128
 129 HELP: get-label
 130 { $values
 131   { "address" string }
 132   { "label" string }
 133 }
 134 { $description
 135     "Returns the label associated with the given address."
 136 } ;
 137
 138 HELP: set-label
 139 { $values
 140   { "address" string }
 141   { "label" string }
 142 }
 143 { $description
 144     "Sets the label associateed with the given address."
 145 } ;
 146
 147 HELP: remove-label
 148 { $values
 149   { "address" string }
 150 }
 151 { $description
 152     "Removes the label associated with the given address."
 153 } ;
 154
 155 HELP: get-new-address
 156 { $values
 157   { "address" string }
 158 }
 159 { $description
 160     "Returns a new bitcoin address for receiving payments."
 161 } ;
 162
 163 HELP: get-new-labelled-address
 164 { $values
 165   { "label" string }
 166   { "address" string }
 167 }
 168 { $description
 169     "Returns a new bitcoin address for receiving payments. The given "
 170     "label is associated with the new address."
 171 } ;
 172
 173 HELP: get-received-by-address
 174 { $values
 175   { "address" string }
 176   { "amount" number }
 177 }
 178 { $description
 179     "Returns the total amount received by the address in transactions "
 180     "with at least one confirmation."
 181 } ;
 182
 183 HELP: get-confirmed-received-by-address
 184 { $values
 185   { "address" string }
 186   { "minconf" number }
 187   { "amount" number }
 188 }
 189 { $description
 190     "Returns the total amount received by the address in transactions "
 191     "with at least 'minconf' confirmations."
 192 } ;
 193
 194 HELP: get-received-by-label
 195 { $values
 196   { "label" string }
 197   { "amount" number }
 198 }
 199 { $description
 200     "Returns the total amount received by addresses with 'label' in transactions "
 201     "with at least one confirmation."
 202 } ;
 203
 204 HELP: get-confirmed-received-by-label
 205 { $values
 206   { "label" string }
 207   { "minconf" number }
 208   { "amount" number }
 209 }
 210 { $description
 211     "Returns the total amount received by the addresses with 'label' in transactions "
 212     "with at least 'minconf' confirmations."
 213 } ;
 214
 215 HELP: list-received-by-address
 216 { $values
 217   { "minconf" number }
 218   { "include-empty" boolean }
 219   { "seq" sequence }
 220 }
 221 { $description
 222     "Return a sequence containing an assoc of data about the payments an "
 223     "address has received. 'include-empty' indicates whether addresses that "
 224     "haven't received any payments should be included. 'minconf' is the "
 225     "minimum number of confirmations before payments are included."
 226 } ;
 227
 228 HELP: list-received-by-label
 229 { $values
 230   { "minconf" number }
 231   { "include-empty" boolean }
 232   { "seq" sequence }
 233 }
 234 { $description
 235     "Return a sequence containing an assoc of data about the payments that "
 236     "addresses with the given label have received. 'include-empty' "
 237     " indicates whether addresses that "
 238     "haven't received any payments should be included. 'minconf' is the "
 239     "minimum number of confirmations before payments are included."
 240 } ;
 241
 242 HELP: send-to-address
 243 { $values
 244   { "address" string }
 245   { "amount" number }
 246   { "?" boolean }
 247 }
 248 { $description
 249     "Sends 'amount' from the server's available balance to 'address'. "
 250     "'amount' is rounded to the nearest 0.01. Returns a boolean indicating "
 251     "if the call succeeded."
 252 } ;
 253
 254 HELP: stop
 255 { $description
 256     "Stops the bitcoin server."
 257 } ;
 258
 259 HELP: list-transactions
 260 { $values
 261   { "count" number }
 262   { "include-generated" boolean }
 263   { "seq" sequence }
 264 }
 265 { $description
 266     "Return's a sequence containing up to 'count' most recent transactions."
 267     "This requires a patched bitcoin server so may not work with old or unpatched "
 268     "servers."
 269 } ;