bhive.hive module¶
-
class
bhive.hive.
Hive
(node='', rpcuser=None, rpcpassword=None, debug=False, data_refresh_time_seconds=900, **kwargs)¶ Bases:
object
Connect to the Hive network.
- Parameters
node (str) – Node to connect to (optional)
rpcuser (str) – RPC user (optional)
rpcpassword (str) – RPC password (optional)
nobroadcast (bool) – Do not broadcast a transaction! (optional)
unsigned (bool) – Do not sign a transaction! (optional)
debug (bool) – Enable Debugging (optional)
keys (array, dict, string) – Predefine the wif keys to shortcut the wallet database (optional)
wif (array, dict, string) – Predefine the wif keys to shortcut the wallet database (optional)
offline (bool) – Boolean to prevent connecting to network (defaults to
False
) (optional)expiration (int) – Delay in seconds until transactions are supposed to expire (optional) (default is 30)
blocking (str) – Wait for broadcasted transactions to be included in a block and return full transaction (can be “head” or “irreversible”)
bundle (bool) – Do not broadcast transactions right away, but allow to bundle operations. It is not possible to send out more than one vote operation and more than one comment operation in a single broadcast (optional)
appbase (bool) – Use the new appbase rpc protocol on nodes with version 0.19.4 or higher. The settings has no effect on nodes with version of 0.19.3 or lower.
num_retries (int) – Set the maximum number of reconnects to the nodes before NumRetriesReached is raised. Disabled for -1. (default is -1)
num_retries_call (int) – Repeat num_retries_call times a rpc call on node error (default is 5)
timeout (int) – Timeout setting for https nodes (default is 60)
use_sc2 (bool) – When True, a hiveconnect object is created. Can be used for broadcast posting op or creating hot_links (default is False)
hiveconnect (HiveConnect) – A HiveConnect object can be set manually, set use_sc2 to True
custom_chains (dict) – custom chain which should be added to the known chains
Three wallet operation modes are possible:
Wallet Database: Here, the hivelibs load the keys from the locally stored wallet SQLite database (see
storage.py
). To use this mode, simply callHive()
without thekeys
parameterProviding Keys: Here, you can provide the keys for your accounts manually. All you need to do is add the wif keys for the accounts you want to use as a simple array using the
keys
parameter toHive()
.Force keys: This more is for advanced users and requires that you know what you are doing. Here, the
keys
parameter is a dictionary that overwrite theactive
,owner
,posting
ormemo
keys for any account. This mode is only used for foreign signatures!
If no node is provided, it will connect to default nodes of http://geo.hive.pl. Default settings can be changed with:
hive = Hive(<host>)
where
<host>
starts withhttps://
,ws://
orwss://
.The purpose of this class it to simplify interaction with Hive.
The idea is to have a class that allows to do this:
>>> from bhive import Hive >>> hive = Hive() >>> print(hive.get_blockchain_version())
This class also deals with edits, votes and reading content.
Example for adding a custom chain:
from bhive import Hive hv = Hive(node=["https://mytstnet.com"], custom_chains={"MYTESTNET": {'chain_assets': [{'asset': 'HBD', 'id': 0, 'precision': 3, 'symbol': 'HBD'}, {'asset': 'HIVE', 'id': 1, 'precision': 3, 'symbol': 'HIVE'}, {'asset': 'VESTS', 'id': 2, 'precision': 6, 'symbol': 'VESTS'}], 'chain_id': '79276aea5d4877d9a25892eaa01b0adf019d3e5cb12a97478df3298ccdd01674', 'min_version': '0.0.0', 'prefix': 'MTN'} } )
-
broadcast
(tx=None)¶ Broadcast a transaction to the Hive network
- Parameters
tx (tx) – Signed transaction to broadcast
-
property
chain_params
¶
-
claim_account
(creator, fee=None, **kwargs)¶ Claim account for claimed account creation.
When fee is 0 HIVE a subsidized account is claimed and can be created later with create_claimed_account. The number of subsidized account is limited.
- Parameters
creator (str) – which account should pay the registration fee (RC or HIVE) (defaults to
default_account
)fee (str) – when set to 0 HIVE (default), claim account is paid by RC
-
clear
()¶
-
comment_options
(options, identifier, beneficiaries=[], account=None, **kwargs)¶ Set the comment options
- Parameters
options (dict) – The options to define.
identifier (str) – Post identifier
beneficiaries (list) – (optional) list of beneficiaries
account (str) – (optional) the account to allow access to (defaults to
default_account
)
For the options, you have these defaults::
{ "author": "", "permlink": "", "max_accepted_payout": "1000000.000 HBD", "percent_hive_dollars": 10000, "allow_votes": True, "allow_curation_rewards": True, }
-
connect
(node='', rpcuser='', rpcpassword='', **kwargs)¶ Connect to Hive network (internal use only)
-
create_account
(account_name, creator=None, owner_key=None, active_key=None, memo_key=None, posting_key=None, password=None, additional_owner_keys=[], additional_active_keys=[], additional_posting_keys=[], additional_owner_accounts=[], additional_active_accounts=[], additional_posting_accounts=[], storekeys=True, store_owner_key=False, json_meta=None, **kwargs)¶ Create new account on Hive
The brainkey/password can be used to recover all generated keys (see
bhivegraphenebase.account
for more details.By default, this call will use
default_account
to register a new nameaccount_name
with all keys being derived from a new brain key that will be returned. The corresponding keys will automatically be installed in the wallet.Warning
Don’t call this method unless you know what you are doing! Be sure to understand what this method does and where to find the private keys for your account.
Note
Please note that this imports private keys (if password is present) into the wallet by default when nobroadcast is set to False. However, it does not import the owner key for security reasons by default. If you set store_owner_key to True, the owner key is stored. Do NOT expect to be able to recover it from the wallet if you lose your password!
Note
Account creations cost a fee that is defined by the network. If you create an account, you will need to pay for that fee!
- Parameters
account_name (str) – (required) new account name
json_meta (str) – Optional meta data for the account
owner_key (str) – Main owner key
active_key (str) – Main active key
posting_key (str) – Main posting key
memo_key (str) – Main memo_key
password (str) – Alternatively to providing keys, one can provide a password from which the keys will be derived
additional_owner_keys (array) – Additional owner public keys
additional_active_keys (array) – Additional active public keys
additional_posting_keys (array) – Additional posting public keys
additional_owner_accounts (array) – Additional owner account names
additional_active_accounts (array) – Additional acctive account names
storekeys (bool) – Store new keys in the wallet (default:
True
)creator (str) – which account should pay the registration fee (defaults to
default_account
)
- Raises
AccountExistsException – if the account already exists on the blockchain
-
create_claimed_account
(account_name, creator=None, owner_key=None, active_key=None, memo_key=None, posting_key=None, password=None, additional_owner_keys=[], additional_active_keys=[], additional_posting_keys=[], additional_owner_accounts=[], additional_active_accounts=[], additional_posting_accounts=[], storekeys=True, store_owner_key=False, json_meta=None, combine_with_claim_account=False, fee=None, **kwargs)¶ Create new claimed account on Hive
The brainkey/password can be used to recover all generated keys (see
bhivegraphenebase.account
for more details.By default, this call will use
default_account
to register a new nameaccount_name
with all keys being derived from a new brain key that will be returned. The corresponding keys will automatically be installed in the wallet.Warning
Don’t call this method unless you know what you are doing! Be sure to understand what this method does and where to find the private keys for your account.
Note
Please note that this imports private keys (if password is present) into the wallet by default when nobroadcast is set to False. However, it does not import the owner key for security reasons by default. If you set store_owner_key to True, the owner key is stored. Do NOT expect to be able to recover it from the wallet if you lose your password!
Note
Account creations cost a fee that is defined by the network. If you create an account, you will need to pay for that fee!
- Parameters
account_name (str) – (required) new account name
json_meta (str) – Optional meta data for the account
owner_key (str) – Main owner key
active_key (str) – Main active key
posting_key (str) – Main posting key
memo_key (str) – Main memo_key
password (str) – Alternatively to providing keys, one can provide a password from which the keys will be derived
additional_owner_keys (array) – Additional owner public keys
additional_active_keys (array) – Additional active public keys
additional_posting_keys (array) – Additional posting public keys
additional_owner_accounts (array) – Additional owner account names
additional_active_accounts (array) – Additional acctive account names
storekeys (bool) – Store new keys in the wallet (default:
True
)combine_with_claim_account (bool) – When set to True, a claim_account operation is additionally broadcasted
fee (str) – When combine_with_claim_account is set to True, this parameter is used for the claim_account operation
creator (str) – which account should pay the registration fee (defaults to
default_account
)
- Raises
AccountExistsException – if the account already exists on the blockchain
-
custom_json
(id, json_data, required_auths=[], required_posting_auths=[], **kwargs)¶ Create a custom json operation
- Parameters
id (str) – identifier for the custom json (max length 32 bytes)
json_data (json) – the json data to put into the custom_json operation
required_auths (list) – (optional) required auths
required_posting_auths (list) – (optional) posting auths
Note
While reqired auths and required_posting_auths are both optional, one of the two are needed in order to send the custom json.
hive.custom_json("id", "json_data", required_posting_auths=['account'])
-
finalizeOp
(ops, account, permission, **kwargs)¶ This method obtains the required private keys if present in the wallet, finalizes the transaction, signs it and broadacasts it
- Parameters
ops (list, GrapheneObject) – The operation (or list of operations) to broadcast
account (Account) – The account that authorizes the operation
permission (string) – The required permission for signing (active, owner, posting)
append_to (TransactionBuilder) – This allows to provide an instance of TransactionBuilder (see
Hive.new_tx()
) to specify where to put a specific operation.
Note
append_to
is exposed to every method used in the Hive classNote
If
ops
is a list of operation, they all need to be signable by the same key! Thus, you cannot combine ops that require active permission with ops that require posting permission. Neither can you use different accounts for different operations!Note
This uses
Hive.txbuffer()
as instance ofbhive.transactionbuilder.TransactionBuilder
. You may want to use your own txbuffer
-
get_api_methods
()¶ Returns all supported api methods
-
get_apis
()¶ Returns all enabled apis
-
get_block_interval
(use_stored_data=True)¶ Returns the block interval in seconds
-
get_blockchain_version
(use_stored_data=True)¶ Returns the blockchain version
-
get_chain_properties
(use_stored_data=True)¶ Return witness elected chain properties
Properties::
{ 'account_creation_fee': '30.000 HIVE', 'maximum_block_size': 65536, 'hbd_interest_rate': 250 }
-
get_config
(use_stored_data=True)¶ Returns internal chain configuration.
- Parameters
use_stored_data (bool) – If True, the cached value is returned
-
get_current_median_history
(use_stored_data=True)¶ Returns the current median price
- Parameters
use_stored_data (bool) – if True, stored data will be returned. If stored data are empty or old, refresh_data() is used.
-
get_default_nodes
()¶ Returns the default nodes
-
get_dust_threshold
(use_stored_data=True)¶ Returns the vote dust threshold
-
get_dynamic_global_properties
(use_stored_data=True)¶ This call returns the dynamic global properties
- Parameters
use_stored_data (bool) – if True, stored data will be returned. If stored data are empty or old, refresh_data() is used.
-
get_feed_history
(use_stored_data=True)¶ Returns the feed_history
- Parameters
use_stored_data (bool) – if True, stored data will be returned. If stored data are empty or old, refresh_data() is used.
-
get_hardfork_properties
(use_stored_data=True)¶ Returns Hardfork and live_time of the hardfork
- Parameters
use_stored_data (bool) – if True, stored data will be returned. If stored data are empty or old, refresh_data() is used.
Returns the current rshares to HBD ratio
-
get_hive_per_mvest
(time_stamp=None, use_stored_data=True)¶ Returns the MVEST to HIVE ratio
- Parameters
time_stamp (int) – (optional) if set, return an estimated HIVE per MVEST ratio for the given time stamp. If unset the current ratio is returned (default). (can also be a datetime object)
-
get_median_price
(use_stored_data=True)¶ Returns the current median history price as Price
-
get_network
(use_stored_data=True)¶ Identify the network
- Parameters
use_stored_data (bool) – if True, stored data will be returned. If stored data are empty or old, refresh_data() is used.
- Returns
Network parameters
- Return type
dictionary
-
get_rc_cost
(resource_count)¶ Returns the RC costs based on the resource_count
-
get_reserve_ratio
()¶ This call returns the reserve ratio
-
get_resource_params
()¶ Returns the resource parameter
-
get_resource_pool
()¶ Returns the resource pool
-
get_reward_funds
(use_stored_data=True)¶ Get details for a reward fund.
- Parameters
use_stored_data (bool) – if True, stored data will be returned. If stored data are empty or old, refresh_data() is used.
-
get_witness_schedule
(use_stored_data=True)¶ Return witness elected chain properties
-
property
hardfork
¶
-
property
hbd_symbol
¶ get the current chains symbol for HBD (e.g. “TBD” on testnet)
Obtain the r-shares from HBD
- Parameters
hbd (str, int, amount.Amount) – HBD
not_broadcasted_vote (bool) – not_broadcasted or already broadcasted vote (True = not_broadcasted vote). Only impactful for very high amounts of HBD. Slight modification to the value calculation, as the not_broadcasted vote rshares decreases the reward pool.
-
hbd_to_vote_pct
(hbd, hive_power=None, vests=None, voting_power=10000, not_broadcasted_vote=True, use_stored_data=True)¶ Obtain the voting percentage for a desired HBD value for a given Hive Power or vesting shares and voting power Give either Hive Power or vests, not both. When the output is greater than 10000 or smaller than -10000, the HBD value is too high.
Returns the required voting percentage (100% = 10000)
- Parameters
hbd (str, int, amount.Amount) – desired HBD value
hive_power (number) – Hive Power
vests (number) – vesting shares
not_broadcasted_vote (bool) – not_broadcasted or already broadcasted vote (True = not_broadcasted vote). Only impactful for very high amounts of HBD. Slight modification to the value calculation, as the not_broadcasted vote rshares decreases the reward pool.
-
property
hive_symbol
¶ get the current chains symbol for HIVE (e.g. “TESTS” on testnet)
-
hp_to_hbd
(hp, voting_power=10000, vote_pct=10000, not_broadcasted_vote=True, use_stored_data=True)¶ Obtain the resulting HBD vote value from Hive power
- Parameters
hive_power (number) – Hive Power
voting_power (int) – voting power (100% = 10000)
vote_pct (int) – voting percentage (100% = 10000)
not_broadcasted_vote (bool) – not_broadcasted or already broadcasted vote (True = not_broadcasted vote).
Only impactful for very big votes. Slight modification to the value calculation, as the not_broadcasted vote rshares decreases the reward pool.
Obtain the r-shares from Hive power
- Parameters
hive_power (number) – Hive Power
voting_power (int) – voting power (100% = 10000)
vote_pct (int) – voting percentage (100% = 10000)
-
hp_to_vests
(hp, timestamp=None, use_stored_data=True)¶ Converts HP to vests
- Parameters
hp (float) – Hive power to convert
timestamp (datetime) – (Optional) Can be used to calculate the conversion rate from the past
-
info
(use_stored_data=True)¶ Returns the global properties
-
is_connected
()¶ Returns if rpc is connected
-
move_current_node_to_front
()¶ Returns the default node list, until the first entry is equal to the current working node url
-
newWallet
(pwd)¶ Create a new wallet. This method is basically only calls
bhive.wallet.Wallet.create()
.- Parameters
pwd (str) – Password to use for the new wallet
- Raises
WalletExists – if there is already a wallet created
-
new_tx
(*args, **kwargs)¶ Let’s obtain a new txbuffer
- Returns
id of the new txbuffer
- Return type
int
-
post
(title, body, author=None, permlink=None, reply_identifier=None, json_metadata=None, comment_options=None, community=None, app=None, tags=None, beneficiaries=None, self_vote=False, parse_body=False, **kwargs)¶ Create a new post. If this post is intended as a reply/comment, reply_identifier needs to be set with the identifier of the parent post/comment (eg. @author/permlink). Optionally you can also set json_metadata, comment_options and upvote the newly created post as an author. Setting category, tags or community will override the values provided in json_metadata and/or comment_options where appropriate.
- Parameters
title (str) – Title of the post
body (str) – Body of the post/comment
author (str) – Account are you posting from
permlink (str) – Manually set the permlink (defaults to None). If left empty, it will be derived from title automatically.
reply_identifier (str) – Identifier of the parent post/comment (only if this post is a reply/comment).
json_metadata (str, dict) – JSON meta object that can be attached to the post.
comment_options (dict) – JSON options object that can be attached to the post.
Example:
comment_options = { 'max_accepted_payout': '1000000.000 HBD', 'percent_hive_dollars': 10000, 'allow_votes': True, 'allow_curation_rewards': True, 'extensions': [[0, { 'beneficiaries': [ {'account': 'account1', 'weight': 5000}, {'account': 'account2', 'weight': 5000}, ]} ]] }
- Parameters
community (str) – (Optional) Name of the community we are posting into. This will also override the community specified in json_metadata.
app (str) – (Optional) Name of the app which are used for posting when not set, bhive/<version> is used
tags (str, list) – (Optional) A list of tags to go with the post. This will also override the tags specified in json_metadata. The first tag will be used as a ‘category’. If provided as a string, it should be space separated.
beneficiaries (list) – (Optional) A list of beneficiaries for posting reward distribution. This argument overrides beneficiaries as specified in comment_options.
For example, if we would like to split rewards between account1 and account2:
beneficiaries = [ {'account': 'account1', 'weight': 5000}, {'account': 'account2', 'weight': 5000} ]
- Parameters
self_vote (bool) – (Optional) Upvote the post as author, right after posting.
parse_body (bool) – (Optional) When set to True, all mentioned users, used links and images are put into users, links and images array inside json_metadata. This will override provided links, images and users inside json_metadata. Hashtags will added to tags until its length is below five entries.
-
property
prefix
¶
-
refresh_data
(force_refresh=False, data_refresh_time_seconds=None)¶ Read and stores hive blockchain parameters If the last data refresh is older than data_refresh_time_seconds, data will be refreshed
- Parameters
force_refresh (bool) – if True, a refresh of the data is enforced
data_refresh_time_seconds (float) – set a new minimal refresh time in seconds
Calculates the current HBD value of a vote
Obtain the voting percentage for a desired rshares value for a given Hive Power or vesting shares and voting_power Give either hive_power or vests, not both. When the output is greater than 10000 or less than -10000, the given absolute rshares are too high
Returns the required voting percentage (100% = 10000)
- Parameters
rshares (number) – desired rshares value
hive_power (number) – Hive Power
vests (number) – vesting shares
voting_power (int) – voting power (100% = 10000)
-
set_default_account
(account)¶ Set the default account to be used
-
set_default_nodes
(nodes)¶ Set the default nodes to be used
-
set_default_vote_weight
(vote_weight)¶ Set the default vote weight to be used
-
set_password_storage
(password_storage)¶ Set the password storage mode.
When set to “no”, the password has to be provided each time. When set to “environment” the password is taken from the UNLOCK variable
When set to “keyring” the password is taken from the python keyring module. A wallet password can be stored with python -m keyring set bhive wallet password
- Parameters
password_storage (str) – can be “no”, “keyring” or “environment”
-
sign
(tx=None, wifs=[], reconstruct_tx=True)¶ Sign a provided transaction with the provided key(s)
- Parameters
tx (dict) – The transaction to be signed and returned
wifs (string) – One or many wif keys to use for signing a transaction. If not present, the keys will be loaded from the wallet as defined in “missing_signatures” key of the transactions.
reconstruct_tx (bool) – when set to False and tx is already contructed, it will not reconstructed and already added signatures remain
-
tx
()¶ Returns the default transaction buffer
-
property
txbuffer
¶ Returns the currently active tx buffer
-
unlock
(*args, **kwargs)¶ Unlock the internal wallet
-
update_proposal_votes
(proposal_ids, approve, account=None, **kwargs)¶ Update proposal votes
- Parameters
proposal_ids (list) – list of proposal ids
approve (bool) – True/False
account (str) – (optional) witness account name
-
property
vests_symbol
¶ get the current chains symbol for VESTS
-
vests_to_hbd
(vests, voting_power=10000, vote_pct=10000, not_broadcasted_vote=True, use_stored_data=True)¶ Obtain the resulting HBD vote value from vests
- Parameters
vests (number) – vesting shares
voting_power (int) – voting power (100% = 10000)
vote_pct (int) – voting percentage (100% = 10000)
not_broadcasted_vote (bool) – not_broadcasted or already broadcasted vote (True = not_broadcasted vote).
Only impactful for very big votes. Slight modification to the value calculation, as the not_broadcasted vote rshares decreases the reward pool.
-
vests_to_hp
(vests, timestamp=None, use_stored_data=True)¶ Converts vests to HP
- Parameters
vests/float vests (amount.Amount) – Vests to convert
timestamp (int) – (Optional) Can be used to calculate the conversion rate from the past
Obtain the r-shares from vests
- Parameters
vests (number) – vesting shares
voting_power (int) – voting power (100% = 10000)
vote_pct (int) – voting percentage (100% = 10000)
-
vote
(weight, identifier, account=None, **kwargs)¶ Vote for a post
- Parameters
weight (float) – Voting weight. Range: -100.0 - +100.0.
identifier (str) – Identifier for the post to vote. Takes the form
@author/permlink
.account (str) – (optional) Account to use for voting. If
account
is not defined, thedefault_account
will be used or a ValueError will be raised
-
witness_set_properties
(wif, owner, props, use_condenser_api=True)¶ Set witness properties
- Parameters
wif (str) – Private signing key
props (dict) – Properties
owner (str) – witness account name
Properties::
{ "account_creation_fee": x, "account_subsidy_budget": x, "account_subsidy_decay": x, "maximum_block_size": x, "url": x, "hbd_exchange_rate": x, "hbd_interest_rate": x, "new_signing_key": x }
-
witness_update
(signing_key, url, props, account=None, **kwargs)¶ Creates/updates a witness
- Parameters
signing_key (str) – Public signing key
url (str) – URL
props (dict) – Properties
account (str) – (optional) witness account name
Properties::
{ "account_creation_fee": "3.000 HIVE", "maximum_block_size": 65536, "hbd_interest_rate": 0, }