Module type Bitcoin.ENGINE

module type ENGINE = sig .. end

Actual engine offering the Bitcoin API.

type 'a monad_t

val addnode : ?conn:Bitcoin.conn_t ->
       Bitcoin.node_t -> Bitcoin.addnodeop_t -> unit monad_t

Allows manually adding/removing a node.

val backupwallet : ?conn:Bitcoin.conn_t -> string -> unit monad_t

Safely backs up wallet file to the given destination, which can be either a directory or a path with filename.

val createmultisig : ?conn:Bitcoin.conn_t ->
       int ->
       Bitcoin.pub_t list ->
       (Bitcoin.address_t * Bitcoin.hexspk_t) monad_t

Creates a m-of-n multi-signature address. An invocation of createmultisig num pubs where List.length pubs >= num returns an address that requires the private keys of at least num members of pubs for spending.

val createrawtransaction : ?conn:Bitcoin.conn_t ->
       Bitcoin.txoutput_t list ->
       (Bitcoin.address_t * Bitcoin.amount_t) list ->
       Bitcoin.hextx_t monad_t

createrawtransaction inputs outputs creates a raw transaction that transfers the given inputs (a list of transaction outputs) to the given outputs (a list of addresses and amounts). This function returns the hex-encoded transaction, but neither does it transmit the transaction to the network nor does it store the transaction in the wallet. In addition, the transaction inputs are not signed, and therefore the returned raw transaction cannot be directly transmitted to the network with Bitcoin.ENGINE.sendrawtransaction without it being previosuly signed with Bitcoin.ENGINE.signrawtransaction.

A transaction fee is specified implicitly by making the total output amounts be smaller than the total input amounts (ie, fee = total inputs - total outputs).

Beware that no checks are performed concerning the validity of the transaction. If care is not taken, it is possible to create a transaction that will not be accepted by the network, either because it uses invalid inputs, has a greater total amount in the outputs than in the outputs, or does not offer a sufficient transaction fee.

val decoderawtransaction : ?conn:Bitcoin.conn_t ->
       Bitcoin.hextx_t -> Bitcoin.assoc_t monad_t

Returns an object containing information concerning the given raw transaction.

val dumpprivkey : ?conn:Bitcoin.conn_t ->
       Bitcoin.address_t -> Bitcoin.priv_t monad_t

Returns the private key corresponding to the given address. This private key can then be imported into another wallet with Bitcoin.ENGINE.importprivkey. (Requires unlocked wallet).

val encryptwallet : ?conn:Bitcoin.conn_t -> string -> unit monad_t

Encrypts the wallet with the given passphrase. Note that once encrypted, a wallet cannot be unencrypted (though the passphrase may be changed with Bitcoin.ENGINE.walletpassphrasechange), and operations requiring an unlocked wallet must be preceded by a call to Bitcoin.ENGINE.walletpassphrase.

val getaccount : ?conn:Bitcoin.conn_t ->
       Bitcoin.address_t -> Bitcoin.account_t monad_t

Returns the account associated with the given address.

val getaccountaddress : ?conn:Bitcoin.conn_t ->
       Bitcoin.account_t -> Bitcoin.address_t monad_t

Returns the receiving address currently associated with the given account. Note that a new address will automatically be generated upon funds being received on this address.

val getaddednodeinfo : ?conn:Bitcoin.conn_t ->
       ?node:Bitcoin.node_t -> unit -> Bitcoin.assoc_t monad_t

Returns the list of nodes manually added with Bitcoin.ENGINE.addnode.

val getaddednodeinfo_verbose : ?conn:Bitcoin.conn_t ->
       ?node:Bitcoin.node_t -> unit -> Bitcoin.assoc_t list monad_t

Returns the list of nodes manually added with Bitcoin.ENGINE.addnode.

val getaddressesbyaccount : ?conn:Bitcoin.conn_t ->
       Bitcoin.account_t -> Bitcoin.address_t list monad_t

Return all addresses associated with the given account.

val getbalance : ?conn:Bitcoin.conn_t ->
       ?account:Bitcoin.account_t ->
       ?minconf:int -> unit -> Bitcoin.amount_t monad_t

If account is provided, returns the balance available in that account. If not, returns the total balance of all accounts.

val getblock : ?conn:Bitcoin.conn_t ->
       Bitcoin.blkhash_t -> Bitcoin.assoc_t monad_t

Returns the available data for the block with the given block hash.

val getblockcount : ?conn:Bitcoin.conn_t -> unit -> int monad_t

Returns the number of blocks in the longest block chain.

val getblockhash : ?conn:Bitcoin.conn_t -> int -> Bitcoin.blkhash_t monad_t

Returns the block hash for the block located at the given index in the longest block chain.

val getblocktemplate : ?conn:Bitcoin.conn_t ->
       ?obj:Bitcoin.assoc_t -> unit -> Bitcoin.assoc_t monad_t

Returns data needed to construct a block to work on.

val getconnectioncount : ?conn:Bitcoin.conn_t -> unit -> int monad_t

Returns the number of connections to peer nodes.

val getdifficulty : ?conn:Bitcoin.conn_t -> unit -> float monad_t

Returns the current difficulty (as a multiple of the minimum difficulty).

val getgenerate : ?conn:Bitcoin.conn_t -> unit -> bool monad_t

Are we currently trying to generate new blocks?

val gethashespersec : ?conn:Bitcoin.conn_t -> unit -> int monad_t

Returns number of hashes per second we currently attain when attempting block generation. Note that it returns 0 if block generation is switched off.

val getinfo : ?conn:Bitcoin.conn_t -> unit -> Bitcoin.assoc_t monad_t

Returns an object containing various state information.

val getmininginfo : ?conn:Bitcoin.conn_t -> unit -> Bitcoin.assoc_t monad_t

Returns an object containing mining related information.

val getnewaddress : ?conn:Bitcoin.conn_t ->
       ?account:Bitcoin.account_t ->
       unit -> Bitcoin.address_t monad_t

Returns a newly generated address. If account is specified, the returned address is associated with that account. If not, the address is associated with the default account.

val getpeerinfo : ?conn:Bitcoin.conn_t -> unit -> Bitcoin.assoc_t list monad_t

Returns information about each connected peer.

val getrawmempool : ?conn:Bitcoin.conn_t -> unit -> Bitcoin.txid_t list monad_t

Returns all transaction IDs currently in the memory pool.

val getrawtransaction : ?conn:Bitcoin.conn_t ->
       Bitcoin.txid_t -> Bitcoin.hextx_t monad_t

Returns the raw transaction corresponding to the given transaction ID.

val getrawtransaction_verbose : ?conn:Bitcoin.conn_t ->
       Bitcoin.txid_t -> Bitcoin.assoc_t monad_t

Returns all the raw information concerning the transaction with the given ID. This function returns even more information than that available with Bitcoin.ENGINE.gettransaction.

val getreceivedbyaccount : ?conn:Bitcoin.conn_t ->
       ?minconf:int -> Bitcoin.account_t -> Bitcoin.amount_t monad_t

Returns the total amount received on the given account. Note that only receiving transactions are considered and therefore this function does not compute the account's current balance; see Bitcoin.ENGINE.getbalance for that purpose.

val getreceivedbyaddress : ?conn:Bitcoin.conn_t ->
       ?minconf:int -> Bitcoin.address_t -> Bitcoin.amount_t monad_t

Returns the total amount received on this address. Note that only receiving transactions are considered and therefore this function does not compute the balance currently associated with the address.

val gettransaction : ?conn:Bitcoin.conn_t ->
       Bitcoin.txid_t -> Bitcoin.assoc_t monad_t

Returns an object containing various information about the given transaction.

val gettxout : ?conn:Bitcoin.conn_t ->
       ?includemempool:bool ->
       Bitcoin.txoutput_t -> Bitcoin.assoc_t monad_t

Returns detailed information concerning a given unspent transaction output.

val gettxoutsetinfo : ?conn:Bitcoin.conn_t -> unit -> Bitcoin.assoc_t monad_t

Returns some statistics about the current set of unspent transaction outputs.

val getwork_with_data : ?conn:Bitcoin.conn_t -> Bitcoin.hexwork_t -> bool monad_t

Tries to solve the given block, returning a boolean indicating success status.

val getwork_without_data : ?conn:Bitcoin.conn_t -> unit -> Bitcoin.assoc_t monad_t

Returns formatted hash data to work on.

val importprivkey : ?conn:Bitcoin.conn_t ->
       ?account:Bitcoin.account_t ->
       ?rescan:bool -> Bitcoin.priv_t -> unit monad_t

Adds a private key to the wallet. This can be an externally generated key or one previously obtained with Bitcoin.ENGINE.dumpprivkey. If account is provided, the key is associated with that account. If not, the key is associated with the default account. The rescan parameter indicates whether the blockchain should be rescanned for transactions involving the imported key. It is true be default. (Requires unlocked wallet).

val keypoolrefill : ?conn:Bitcoin.conn_t -> unit -> unit monad_t

Refills the keypool. (Requires unlocked wallet).

val listaccounts : ?conn:Bitcoin.conn_t ->
       ?minconf:int ->
       unit -> (Bitcoin.account_t * Bitcoin.amount_t) list monad_t

Returns a list of all accounts and associated balance.

val listaddressgroupings : ?conn:Bitcoin.conn_t ->
       unit ->
       (Bitcoin.address_t * Bitcoin.amount_t * Bitcoin.account_t) list list
       monad_t

Returns a list of the groups of addresses whose common ownership has been made public by common use as inputs or as the resulting change in past transactions.

val listlockunspent : ?conn:Bitcoin.conn_t ->
       unit -> Bitcoin.txoutput_t list monad_t

Returns a list of temporarily unspendable transaction outputs. These are outputs previously locked by a call of Bitcoin.ENGINE.lockunspent, and will not be spent by the system unless explicitly used in a raw transaction.

val listreceivedbyaccount : ?conn:Bitcoin.conn_t ->
       ?minconf:int ->
       ?includeempty:bool ->
       unit ->
       (Bitcoin.account_t * Bitcoin.amount_t * int) list monad_t

Returns a list of the total amount received by each account. Each returned list element is a tuple consisting of an account, the total amount received for that account, and the number of confirmations. Optional parameter includeempty indicates whether accounts with nothing received will be included in the returned list (defaults to false).

val listreceivedbyaddress : ?conn:Bitcoin.conn_t ->
       ?minconf:int ->
       ?includeempty:bool ->
       unit ->
       (Bitcoin.address_t * Bitcoin.account_t * Bitcoin.amount_t * int) list
       monad_t

Returns a list of the total amount received by each address. Each returned list element is a tuple consisting of the address, the associated account, the total amount received for that address, and the number of confirmations. Optional parameter includeempty indicates whether accounts with nothing received will be included in the returned list (defaults to false).

val listsinceblock : ?conn:Bitcoin.conn_t ->
       ?blockhash:Bitcoin.blkhash_t ->
       ?minconf:int ->
       unit -> (Bitcoin.assoc_t list * Bitcoin.blkhash_t) monad_t

Returns a pair consisting of a list of all transactions and the block hash of the latest block. If provided, the blockhash parameter limits the list of transactions to those occurring after (and not including) that block. Note that if you want to provide a value for parameter minconf, then you must also provide blockhash.

val listtransactions : ?conn:Bitcoin.conn_t ->
       ?account:Bitcoin.account_t ->
       ?count:int ->
       ?from:int -> unit -> Bitcoin.assoc_t list monad_t

Returns up to count most recent transactions skipping the first from transactions for account. If account is not provided, then all recent transactions from all accounts will be returned. Note that count and from default to 10 and 0, respectively.

val listunspent : ?conn:Bitcoin.conn_t ->
       ?minconf:int ->
       ?maxconf:int ->
       ?addresses:Bitcoin.address_t list ->
       unit -> Bitcoin.assoc_t list monad_t

Returns a list of the unspent transaction outputs that have between minconf and maxconf confirmations (these default to 1 and 999_999, respectively). If addresses is provided, the returned list is filtered to only include transaction outputs paid to the specified addresses.

val lockunspent : ?conn:Bitcoin.conn_t ->
       ?outputs:Bitcoin.txoutput_t list ->
       Bitcoin.lockop_t -> bool monad_t

Updates the list of temporarily unspendable transaction outputs. If the operation is `Lock, this function will lock the specified outputs, preventing them from being spent outside of a raw transaction. If the operation is `Unlock, this function will unlock the specified previously locked outputs. To unlock all currently locked outputs, set the operation to `Unlock and do not provide any list of outputs. Returns a boolean indicating whether the operation was successfull.

val move : ?conn:Bitcoin.conn_t ->
       ?minconf:int ->
       ?comment:string ->
       Bitcoin.account_t ->
       Bitcoin.account_t -> Bitcoin.amount_t -> bool monad_t

move ?minconf ?comment from_account to_account amount transfers the given amount from one account to another. If provided, comment allows you to record a comment associated with the move. Note that this is operation only rearranges the internal balances on your wallet, and is not communicated to the Bitcoin network.

val sendfrom : ?conn:Bitcoin.conn_t ->
       ?minconf:int ->
       ?comment:string ->
       ?recipient:string ->
       Bitcoin.account_t ->
       Bitcoin.address_t ->
       Bitcoin.amount_t -> Bitcoin.txid_t monad_t

Transfers a given amount to the specified address, deducting the balance of the given account. If successful, the function returns the ID of the transaction recording the transfer. The optional parameter comment allows you to record an arbitrary comment about this transaction, whereas the also optional recipient assigns a string identifier to the recipient address. Note that sendfrom is only performed if the account balance is sufficient to fund the transfer. (Requires unlocked wallet).

val sendmany : ?conn:Bitcoin.conn_t ->
       ?minconf:int ->
       ?comment:string ->
       Bitcoin.account_t ->
       (Bitcoin.address_t * Bitcoin.amount_t) list ->
       Bitcoin.txid_t monad_t

Makes multiple transfers from a given account. Besides the source account, this function accepts as parameter a list whole elements are pairs consisting of each target address and the amount to be sent. If successful, the function returns the ID of the transaction recording the transfer. The optional parameter comment allows you to record an arbitrary comment about this transaction. Note that sendmany is only performed if the account balance is sufficient to fund the transfer. (Requires unlocked wallet).

val sendrawtransaction : ?conn:Bitcoin.conn_t ->
       Bitcoin.hextx_t -> Bitcoin.txid_t monad_t

Transmits the given raw transaction to the network. Note that no attempt is made to verify the validity of the transaction. Other peers may choose to drop it if invalid.

val sendtoaddress : ?conn:Bitcoin.conn_t ->
       ?comment:string ->
       ?recipient:string ->
       Bitcoin.address_t ->
       Bitcoin.amount_t -> Bitcoin.txid_t monad_t

Transfers a given amount to the specified address, deducting the balance of the defaul account. If successful, the function returns the ID of the transaction recording the transfer. The optional parameter comment allows you to record an arbitrary comment about this transaction, whereas the also optional recipient assigns a string identifier to the recipient address. Note that sendtoaddress is only performed if the total balance (not the balance of the default account!) is sufficient to fund the transfer. (Requires unlocked wallet).

val setaccount : ?conn:Bitcoin.conn_t ->
       Bitcoin.address_t -> Bitcoin.account_t -> unit monad_t

Associates the given address with the given account.

val setgenerate : ?conn:Bitcoin.conn_t ->
       ?genproclimit:int -> bool -> unit monad_t

Turns on/off the generation of new blocks (a.k.a. "mining"). If provided, genproclimit limits the number of CPUs to be used for generating.

val settxfee : ?conn:Bitcoin.conn_t -> Bitcoin.amount_t -> bool monad_t

Sets the transaction fee to be used in subsequent transactions.

val signmessage : ?conn:Bitcoin.conn_t ->
       Bitcoin.address_t -> string -> Bitcoin.sig_t monad_t

Signs the given message with the private key of the given address. The resulting signed message can be validated with Bitcoin.ENGINE.validateaddress. (Requires unlocked wallet).

val signrawtransaction : ?conn:Bitcoin.conn_t ->
       ?parents:(Bitcoin.txoutput_t * Bitcoin.hexspk_t) list ->
       ?keys:Bitcoin.priv_t list ->
       ?sighash:Bitcoin.sigcomp_t * bool ->
       Bitcoin.hextx_t -> (Bitcoin.hextx_t * bool) monad_t

Signs a raw transaction, returning a pair with the signed transaction in hex format and a boolean indicating whether all private keys required for a successful signing have been found. A raw transaction created with Bitcoin.ENGINE.createrawtransaction must be signed before broadcasting to the network with Bitcoin.ENGINE.sendrawtransaction. The optional parameters parents, keys, and sighash are only required if you wish to chain transactions or if the private keys required for signing do not reside in the wallet. Note that these optional parameters have the particularity that providing a value for parameter n requires also providing a value for n-1.

val submitblock : ?conn:Bitcoin.conn_t -> Bitcoin.hexblk_t -> unit monad_t

Attempts to submit new block to network.

val validateaddress : ?conn:Bitcoin.conn_t ->
       Bitcoin.address_t -> Bitcoin.assoc_t option monad_t

Is the given address a valid Bitcoin address? If so, this function returns an object containing miscelaneous information about that address. Returns None otherwise.

val verifymessage : ?conn:Bitcoin.conn_t ->
       Bitcoin.address_t -> Bitcoin.sig_t -> string -> bool monad_t

Returns a boolean indicating whether a supposedly signed message does indeed correspond to a source message signed with the given address. Use Bitcoin.ENGINE.signmessage for signing messages.

val walletlock : ?conn:Bitcoin.conn_t -> unit -> unit monad_t

Removes the wallet decryption key from memory, thus effectively locking the wallet. After this function is invoked, you may not perform any API calls that require an unlocked wallet unless you beforehand unlock the wallet again with Bitcoin.ENGINE.walletpassphrase. Note that this function may not be called on an already locked wallet or in one which is altogether unencrypted.

val walletpassphrase : ?conn:Bitcoin.conn_t -> string -> int -> unit monad_t

walletpassphrase passphrase timeout unlocks an encrypted wallet, storing the decryption key in memory. If your wallet is encrypted (see Bitcoin.ENGINE.encryptwallet) then you must invoke this function prior to calling any of the functions which require an unlocked wallet. Note that the unlocking expires after timeout seconds. Regardless of the timeout, you may at any moment lock again the wallet with Bitcoin.ENGINE.walletlock.

val walletpassphrasechange : ?conn:Bitcoin.conn_t -> string -> string -> unit monad_t

walletpassphrasechange old_passphrase new_passphrase changes the wallet passphrase from old_passphrase to new_passphrase. Must only be called for an encrypted wallet.