-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Interface with Bitcoin RPC
--   
--   This can be used to send Bitcoins, query balances, etc. It requires
--   the Bitcoin daemon to be running and accessible via HTTP.
--   
--   <pre>
--   import Network.Bitcoin
--   
--   main = do
--      balance &lt;- getBalance auth
--      putStrLn $ show balance ++ " BTC"
--    where
--      auth = Auth "http://127.0.0.1:8332" "user" "password"
--   </pre>
--   
--   To learn more about Bitcoin, see <a>http://www.bitcoin.org</a>.
--   
--   Changes in v0.1.5
--   
--   <ul>
--   <li>Correct aeson dependency</li>
--   </ul>
--   
--   Changes in v0.1.4
--   
--   <ul>
--   <li>More accurate conversion of Bitcoin amounts from floating
--   point</li>
--   </ul>
@package network-bitcoin
@version 0.1.5

module Network.Bitcoin.Address

-- | Represents a Bitcoin receiving address. Construct one with
--   <a>mkAddress</a>.
data Address

-- | Construct an <a>Address</a> from a <a>String</a>. Returns
--   <a>Nothing</a> if the string is not a valid Bitcoin address.
--   
--   Only validates approximate address format. <i>Does not</i> validate
--   address checksum. Until full validation is done, use
--   <tt>isValidAddress</tt> RPC call instead
mkAddress :: String -> Maybe Address
instance Show Address


-- | Communicate with a Bitcoin daemon over JSON RPC
module Network.Bitcoin

-- | <a>Auth</a> describes authentication credentials for making API
--   requests to the Bitcoin daemon
data Auth
Auth :: String -> String -> String -> Auth

-- | URL, with port, where bitcoind listens
rpcUrl :: Auth -> String

-- | same as bitcoind's <tt>rpcuser</tt> config
rpcUser :: Auth -> String

-- | same as bitcoind's <tt>rpcpassword</tt> config
rpcPassword :: Auth -> String

-- | Represents a Bitcoin receiving address. Construct one with
--   <a>mkAddress</a>.
data Address

-- | Construct an <a>Address</a> from a <a>String</a>. Returns
--   <a>Nothing</a> if the string is not a valid Bitcoin address.
--   
--   Only validates approximate address format. <i>Does not</i> validate
--   address checksum. Until full validation is done, use
--   <tt>isValidAddress</tt> RPC call instead
mkAddress :: String -> Maybe Address

-- | Fixed precision Bitcoin amount (to avoid floating point errors)
type Amount = Fixed Satoshi

-- | Name of a Bitcoin wallet account
type Account = String

-- | Minimum number of confirmations for a payment
type MinConf = Integer

-- | Encapsulates address validation results from <a>validateAddress</a>
data AddressValidation

-- | Is the address valid?
isValid :: AddressValidation -> Bool

-- | Does the address belong to my wallet?
isMine :: AddressValidation -> Bool

-- | To which account does this address belong?
account :: AddressValidation -> Account

-- | A <a>BitcoinException</a> is thrown when <a>callApi</a> encounters an
--   error. The API error code is represented as an <tt>Int</tt>, the
--   message as a <tt>String</tt>.
data BitcoinException
BitcoinApiError :: Int -> String -> BitcoinException
data Satoshi
Satoshi :: Satoshi

-- | Returns the balance of a specific Bitcoin account
getBalance :: Auth -> Account -> MinConf -> IO Amount

-- | Returns the number of blocks in the longest block chain
getBlockCount :: Auth -> IO Integer

-- | Returns the number of connections to other nodes
getConnectionCount :: Auth -> IO Integer

-- | Returns the proof-of-work difficulty as a multiple of the minimum
--   difficulty
getDifficulty :: Auth -> IO Double

-- | Indicates whether the node is generating or not
getGenerate :: Auth -> IO Bool

-- | Returns a recent hashes per second performance measurement while
--   generating
getHashesPerSec :: Auth -> IO Integer

-- | Returns the total amount received by addresses with <tt>account</tt>
--   in transactions with at least <tt>minconf</tt> confirmations
getReceivedByAccount :: Auth -> Account -> MinConf -> IO Amount

-- | Returns the total amount received by an address in transactions with
--   at least <tt>minconf</tt> confirmations.
getReceivedByAddress :: Auth -> Address -> MinConf -> IO Amount

-- | Return information about an address. If the address is invalid or
--   doesn't belong to us, the account name is the empty string.
validateAddress :: Auth -> Address -> IO AddressValidation

-- | Returns true if the RPC says the address is valid. Use this function
--   until <a>mkAddress</a> verifies address checksums
isValidAddress :: Auth -> Address -> IO Bool

-- | <a>callApi</a> is a low-level interface for making authenticated API
--   calls to a Bitcoin daemon. The first argument specifies authentication
--   details (URL, username, password) and is often curried for
--   convenience:
--   
--   <pre>
--   callBtc = callApi $ Auth "http://127.0.0.1:8332" "user" "password"
--   </pre>
--   
--   The second argument is the command name. The third argument provides
--   parameters for the API call.
--   
--   <pre>
--   let result = callBtc "getbalance" ["account-name", Number 6]
--   </pre>
--   
--   On error, throws a <a>BitcoinException</a>
callApi :: Auth -> String -> [Value] -> IO Value

-- | Convert JSON numeric values to more specific numeric types
class FromNumber a
fromNumber :: FromNumber a => Number -> a
instance Typeable BitcoinException
instance Show Auth
instance Show BitcoinRpcResponse
instance Show BitcoinException
instance Show AddressValidation
instance ToValue Account
instance ToValue MinConf
instance ToValue Address
instance FromNumber Double
instance FromNumber Integer
instance FromNumber Amount
instance Exception BitcoinException
instance FromJSON BitcoinRpcResponse
instance HasResolution Satoshi