nectar package

Submodules

Module contents

nectar.

class nectar.Hive(node: str | list[str] | None = None, rpcuser: str | None = None, rpcpassword: str | None = None, debug: bool = False, data_refresh_time_seconds: int = 900, **kwargs)

Bases: BlockChainInstance

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 300)

  • 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)

  • custom_chains (dict) – custom chain which should be added to the known chains

Three wallet operation modes are possible:

  • Wallet Database: Here, the nectarlibs load the keys from the locally stored wallet SQLite database (see storage.py). To use this mode, simply call Hive() without the keys parameter

  • Providing 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 to Hive().

  • 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 the active, owner, posting or memo keys for any account. This mode is only used for foreign signatures!

If no node is provided, it will connect to default nodes from nectar.NodeList. Default settings can be changed with:

hive = Hive(<host>)

where <host> starts with https://, ws:// or wss://.

The purpose of this class it to simplify interaction with Hive.

The idea is to have a class that allows to do this:

>>> from nectar 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 nectar 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'}
    }
)
property chain_params: Dict[str, Any] | None
get_hbd_per_rshares(not_broadcasted_vote_rshares: int | float = 0, use_stored_data: bool = True) → float

Returns the current rshares to HBD ratio

get_hive_per_mvest(time_stamp: datetime | int | None = None, use_stored_data: bool = True) → float

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_network(use_stored_data: bool = True, config: Dict[str, Any] | None = None) → Dict[str, Any] | None

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_token_per_mvest(time_stamp: datetime | int | None = None, use_stored_data: bool = True) → float

Returns the MVEST to TOKEN ratio

Parameters:

time_stamp (int) – (optional) if set, return an estimated TOKEN per MVEST ratio for the given time stamp. If unset the current ratio is returned (default). (can also be a datetime object)

property hardfork: str
property hbd_symbol: str
hbd_to_rshares(hbd: str | int | Amount, not_broadcasted_vote: bool = False, use_stored_data: bool = True) → float

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: str | int | Amount, post_rshares: int = 0, hive_power: Amount | float | None = None, vests: Amount | float | None = None, voting_power: int = 10000, not_broadcasted_vote: bool = True, use_stored_data: bool = True) → float

Calculate the voting percentage required to achieve a target HBD payout for a given voting power and stake.

Given a desired HBD amount, this returns the vote percentage (100% == 10000) that, when applied from the provided Hive Power or vesting shares, would produce approximately that payout. Exactly one of hive_power or vests must be provided.

Parameters:

hbd (str|int|Amount): Desired HBD payout. Accepts an Amount, numeric value, or asset string; will be converted to an Amount in the chain’s HBD symbol. hive_power (number, optional): Voter’s Hive Power. Mutually exclusive with vests. vests (number, optional): Voter’s vesting shares. Mutually exclusive with hive_power. voting_power (int, optional): Current voting power normalization constant (default HIVE_100_PERCENT). not_broadcasted_vote (bool, optional): If True, treat the vote as not yet broadcast; this slightly changes calculations for very large HBD amounts because an unbroadcasted vote reduces the available reward pool. post_rshares (int, optional): rshares already present on the post (used when calculating required vote to reach a target). use_stored_data (bool, optional): Use cached chain properties when available.

Returns:

int: Required vote percentage where 100% == 10000. Values >10000 or < -10000 indicate the requested HBD is too large for a single vote.

Raises:

AssertionError: If the provided hbd cannot be interpreted as the chain’s HBD asset.

property hive_symbol: str
hp_to_hbd(hp: Amount | float, post_rshares: int = 0, voting_power: int = 10000, vote_pct: int = 10000, not_broadcasted_vote: bool = True, use_stored_data: bool = True) → float

Convert Hive Power (HP) to the estimated HBD payout this vote would produce.

Parameters:

hp (number): Amount of Hive Power to convert. post_rshares (int): Current post rshares to include when computing marginal effect of this vote. voting_power (int): Voter’s current voting power (100% = 10000). vote_pct (int): Vote percentage to apply (100% = 10000). not_broadcasted_vote (bool): If True, treat the vote as not yet broadcast — the function will account for the vote reducing the available reward pool when applicable. use_stored_data (bool): If True, use cached chain/state data when available.

Returns:

HBD value corresponding to the provided HP under the current reward pool and price conditions (same type/format as the library’s Amount/HBD results).

hp_to_rshares(hive_power: Amount | float, post_rshares: int = 0, voting_power: int = 10000, vote_pct: int = 10000, use_stored_data: bool = True) → float

Convert Hive Power (HP) to r-shares used for voting.

Given a Hive Power amount, computes the equivalent vesting shares and then the r-shares that a vote with the specified voting_power and vote_pct would produce against a post that currently has post_rshares. voting_power and vote_pct use the chain-normalized scale (100% == HIVE_100_PERCENT).

Parameters:

hive_power (number): Hive Power (HP) value to convert. post_rshares (int, optional): Current r-shares of the post being voted on; used to adjust the resulting r-shares. Defaults to 0. voting_power (int, optional): Voter’s current voting power on the HIVE_100_PERCENT scale. Defaults to HIVE_100_PERCENT. vote_pct (int, optional): Vote percentage to apply on the HIVE_100_PERCENT scale. Defaults to HIVE_100_PERCENT. use_stored_data (bool, optional): Whether to use cached chain data when performing conversions. Defaults to True.

Returns:

int: The computed r-shares produced by the specified vote.

hp_to_vests(hp: Amount | float, timestamp: datetime | int | None = None, use_stored_data: bool = True) → float

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

property is_hive: bool

Return True if the connected chain appears to be Hive.

Checks the cached chain configuration and returns True when the key “HIVE_CHAIN_ID” is present; returns False if configuration is unavailable or the key is absent.

rshares_to_hbd(rshares: int | float, not_broadcasted_vote: bool = False, use_stored_data: bool = True) → float

Calculates the current HBD value of a vote

rshares_to_token_backed_dollar(rshares: int | float, not_broadcasted_vote: bool = False, use_stored_data: bool = True) → float

Calculates the current HBD value of a vote

rshares_to_vote_pct(rshares: int | float, post_rshares: int = 0, hive_power: Amount | float | None = None, vests: Amount | float | None = None, voting_power: int = 10000, use_stored_data: bool = True) → float

Compute the voting percentage required to achieve a target r-shares value.

Given a desired r-shares (positive for upvotes, negative for downvotes) and either hive_power or vests (exactly one must be provided), return the voting percentage where 100% = 10000. The calculation accounts for post-vote r-shares adjustments, current dust-threshold behavior (post-hardfork), and the configured voting power.

Parameters:

rshares (int | float): Target r-shares value (signed). post_rshares (int, optional): R-shares already present on the post (positive

for existing upvotes, negative for downvotes). Defaults to 0.

hive_power (float, optional): Hive Power to use for the calculation. Provide

this or vests, not both. If given, it is converted to vesting shares.

vests (int, optional): Vesting shares (in micro-vests, i.e., vest*1e6). Provide

this or hive_power, not both.

voting_power (int, optional): Voter’s current voting power where 100% = 10000.

Defaults to HIVE_100_PERCENT.

use_stored_data (bool, optional): Whether to use cached chain properties when

available. Defaults to True.

Returns:

int: Signed voting percentage required (100% = 10000). The sign matches the sign of rshares.

Raises:

ValueError: If neither or both of hive_power and vests are provided.

token_power_to_token_backed_dollar(token_power: Amount | float, post_rshares: int = 0, voting_power: int = 10000, vote_pct: int = 10000, not_broadcasted_vote: bool = True, use_stored_data: bool = True) → float

Convert token power (Hive Power) to its token-backed dollar equivalent (HBD).

Parameters:

token_power: Hive Power amount (numeric or Amount-like) to convert. post_rshares (int): Optional existing rshares on the post to include when estimating payout. voting_power (int): Voter’s current voting power (use HIVE_100_PERCENT for full power). vote_pct (int): Vote weight to apply (use HIVE_100_PERCENT for 100%). not_broadcasted_vote (bool): If True, include the vote as not-yet-broadcasted when computing reward pool effects. use_stored_data (bool): If True, prefer cached chain data when available.

Returns:

The estimated HBD value (token-backed dollar) corresponding to the provided token power.

token_power_to_vests(token_power: Amount | float, timestamp: datetime | int | None = None, use_stored_data: bool = True) → float

Converts TokenPower to vests

Parameters:

  • token_power (float) – Token power to convert

  • timestamp (datetime) – (Optional) Can be used to calculate the conversion rate from the past

property vests_symbol: str

get the current chains symbol for VESTS

vests_to_hbd(vests: Amount | float, post_rshares: int = 0, voting_power: int = 10000, vote_pct: int = 10000, not_broadcasted_vote: bool = True, use_stored_data: bool = True) → float

Convert vesting shares to their equivalent HBD payout for a single vote.

Given vesting shares, computes the vote’s r-shares (taking into account post r-shares, voter power and percentage) and converts that r-shares value to an HBD payout.

Parameters:

vests: Vesting shares to use for the vote (number or Amount-like). post_rshares (int): Existing r-shares of the post being voted on; affects the r-shares calculation. voting_power (int): Voter’s current voting power (units where 100% == HIVE_100_PERCENT). vote_pct (int): Vote percentage to apply (units where 100% == HIVE_100_PERCENT). not_broadcasted_vote (bool): If True, treat this as a not-yet-broadcast vote (it reduces the effective reward pool);

if False, treat as already-applied (affects conversion math for very large votes).

use_stored_data (bool): Whether to use cached chain parameters/reward state or query fresh data.

Returns:

The estimated HBD value (same type returned by rshares_to_hbd) for the vote.

vests_to_hp(vests: Amount | float, timestamp: datetime | int | None = None, use_stored_data: bool = True) → float

Converts vests to HP

Parameters:

  • vests (amount.Amount vests/float) – Vests to convert

  • timestamp (int) – (Optional) Can be used to calculate the conversion rate from the past

vests_to_token_power(vests: Amount | float, timestamp: datetime | int | None = None, use_stored_data: bool = True) → float

Converts vests to TokenPower

Parameters:

  • vests (amount.Amount vests/float) – Vests to convert

  • timestamp (int) – (Optional) Can be used to calculate the conversion rate from the past