nectar.blockchaininstance module

class nectar.blockchaininstance.BlockChainInstance(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: object

Connect to a Graphene 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 nectar libraries 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 the default Hive nodes. Default settings can be changed with:

hive = Hive(<host>)

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

The purpose of this class is 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 backed_token_symbol: str

Return the symbol for the chain’s backed asset (HBD-like).

Attempts to read the asset symbol at asset id 0 (typical HBD). If that key is missing, falls back to asset id 1 (main token) and returns that symbol. Returns a string (e.g., “HBD”, “TBD”, or the chain’s main token symbol). May propagate KeyError if neither asset id is available.

broadcast(tx: dict[str, Any] | None = None, trx_id: bool = True) → dict[str, Any]

Broadcast a transaction to the Hive network

Parameters:

  • tx (tx) – Signed transaction to broadcast

  • trx_id (bool) – when True, the trx_id will be included into the return dict.

property chain_params: dict[str, Any]
claim_account(creator: str | Account | None = None, fee: str | None = None, **kwargs) → dict[str, Any]

Claim a subsidized account slot or pay the account-creation fee.

When fee is “0 <TOKEN>” (default), the claim consumes an account slot paid from RC (resource credits) allowing a later call to create_claimed_account to create the account. Supplying a nonzero fee will pay the registration fee in the chain token (e.g., HIVE).

Parameters:

creator (str): Account that will pay or consume the claim (defaults to configured default_account). fee (str, optional): Fee as a string with asset symbol (e.g., “0 HIVE” or “3.000 HIVE”). If omitted, defaults to “0 <token_symbol>”.

Returns:

The result of finalizeOp for the submitted Claim_account operation (signed/broadcast transaction or unsigned/buffered result, depending on instance configuration).

Raises:

ValueError: If no creator is provided and no default_account is configured.

clear() → None
clear_data() → None

Reset the internal cache of blockchain-derived data.

This clears stored values used to cache node-dependent blockchain parameters (dynamic global properties, feed history, hardfork properties, network info, witness schedule, config, reward funds) and their per-key refresh timestamps. It does not affect network connection, wallet state, transaction buffers, or other non-cache attributes.

comment_options(options: dict[str, Any], identifier: str, beneficiaries: list[dict[str, Any]] = [], account: str | Account | None = None, **kwargs: Any) → dict[str, Any]

Set comment/post options for a post (Comment_options operation) and submit the operation.

Parameters:
options (dict): Comment options to set. Common keys include:

  • max_accepted_payout (str): e.g. “1000000.000 HBD”

  • percent_hbd (int): e.g. 10000 for 100%

  • allow_votes (bool)

  • allow_curation_rewards (bool)

Other valid keys accepted by the chain’s Comment_options operation are supported.

identifier (str): Post identifier in the form “author/permlink” or a permlink for the default author. beneficiaries (list): Optional list of beneficiaries (each entry typically a dict with account and weight). account (str): Account that authorizes this operation; defaults to the instance’s default_account if not provided. **kwargs: Additional keyword arguments forwarded to finalizeOp (e.g., broadcast/signing options).

Returns:

The result of finalizeOp for the created Comment_options operation (signed/broadcasted transaction or unsigned buffer), depending on instance configuration.

Raises:

ValueError: If no account is provided and no default account is configured.

connect(node: str | list[str] = '', rpcuser: str = '', rpcpassword: str = '', **kwargs) → None

Connect to a Hive node and initialize the internal RPC client.

If node is empty, the method will attempt to use the configured default nodes; if none are available a ValueError is raised. If rpcuser or rpcpassword are not provided, values are read from self.config when present. The config key “use_tor” (if set) will be used to enable Tor for the connection. Any additional keyword arguments are forwarded to the NodeRPC constructor.

Parameters:

node (str | list): Node URL or list of node URLs to connect to. If omitted, default nodes are used. rpcuser (str): Optional RPC username; falls back to self.config[“rpcuser”] when not supplied. rpcpassword (str): Optional RPC password; falls back to self.config[“rpcpassword”] when not supplied.

Raises:

ValueError: If no node is provided and no default nodes are configured.

create_account(account_name: str, creator: str | Account | None = 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 nectargraphenebase.account for more details.

By default, this call will use default_account to register a new name account_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: str, creator: str | Account | None = None, owner_key: str | None = None, active_key: str | None = None, memo_key: str | None = None, posting_key: str | None = None, password: str | None = None, additional_owner_keys: list[str] | None = None, additional_active_keys: list[str] | None = None, additional_posting_keys: list[str] | None = None, additional_owner_accounts: list[str] | None = None, additional_active_accounts: list[str] | None = None, additional_posting_accounts: list[str] | None = None, storekeys: bool = True, store_owner_key: bool = False, json_meta: dict[str, Any] | None = None, combine_with_claim_account: bool = False, fee: str | None = None, **kwargs) → dict[str, Any]

Create new claimed account on Hive

The brainkey/password can be used to recover all generated keys (see nectargraphenebase.account for more details.

By default, this call will use default_account to register a new name account_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: str, json_data: Any, required_auths: list[str] = [], required_posting_auths: list[str] = [], **kwargs) → dict[str, Any]

Create and submit a Custom_json operation.

Parameters:

id (str): Identifier for the custom JSON (max 32 bytes). json_data: JSON-serializable payload to include in the operation. required_auths (list): Accounts that must authorize with active permission. If non-empty, the operation will be finalized using active permission. required_posting_auths (list): Accounts that must authorize with posting permission. Used when required_auths is empty.

Returns:

The result returned by finalizeOp (signed and/or broadcast transaction), which may vary based on the instance configuration (e.g., unsigned, nobroadcast, bundle).

Raises:

Exception: If neither required_auths nor required_posting_auths contains an account.

finalizeOp(ops: Any, account: Account | str, permission: str, **kwargs) → dict[str, Any]

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 BlockChainInstance.new_tx()) to specify where to put a specific operation.

Note

append_to is exposed to every method used in the BlockChainInstance class

Note

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 BlockChainInstance.txbuffer() as instance of nectar.transactionbuilder.TransactionBuilder. You may want to use your own txbuffer

Note

when doing sign + broadcast, the trx_id is added to the returned dict

get_api_methods() → list[str]

Return the list of all JSON-RPC API methods supported by the connected node.

Returns:

list: Method names (strings) provided by the node’s JSON-RPC API.

get_apis() → list[str]

Returns all enabled apis

get_block_interval(use_stored_data: bool = True) → int

Returns the block interval in seconds

get_blockchain_name(use_stored_data: bool = True) → str

Returns the blockchain version

get_blockchain_version(use_stored_data: bool = True) → str | dict[str, Any]

Returns the blockchain version

get_chain_properties(use_stored_data: bool = True) → dict[str, Any]

Return the witness-elected chain properties (median_props) used by the network.

When cached data is allowed (use_stored_data=True) this reads from the instance cache (populated by refresh_data). Otherwise it fetches the latest witness schedule and returns its median_props object.

Parameters:
use_stored_data (bool): If True, return cached properties when available; if False,

force fetching the current witness schedule.

Returns:
dict: The median_props mapping, e.g.:
{

‘account_creation_fee’: ‘30.000 HIVE’, ‘maximum_block_size’: 65536, ‘hbd_interest_rate’: 250

}

get_config(use_stored_data: bool = True) → dict[str, Any] | None

Returns internal chain configuration.

Parameters:

use_stored_data (bool) – If True, the cached value is returned

get_current_median_history(use_stored_data: bool = True) → dict[str, Any] | None

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() → list[str]

Returns the default nodes

get_dust_threshold(use_stored_data: bool = True) → float

Returns the vote dust threshold

get_dynamic_global_properties(use_stored_data: bool = True) → dict[str, Any] | None

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: bool = True) → dict[str, Any] | None

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: bool = True) → dict[str, Any] | None

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.

get_median_price(use_stored_data: bool = True) → dict[str, Any] | None

Returns the current median history price as Price

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_rc_cost(resource_count: dict[str, int]) → int

Compute the total Resource Credits (RC) cost for a set of resource usages.

This queries the current resource pool, price curve parameters, and dynamic global properties to compute the RC cost for each resource type in resource_count and returns their sum. If the RC regeneration rate is zero, returns 0.

Parameters:

resource_count (dict): Mapping of resource type keys to requested usage counts. Counts are interpreted in resource-specific units and will be scaled by the resource’s resource_unit parameter.

Returns:

int: Total RC cost (rounded as produced by internal cost calculation).

get_reserve_ratio() → dict[str, Any] | None

This call returns the reserve ratio

get_resource_params() → dict[str, Any]

Returns the resource parameter

get_resource_pool() → dict[str, Any]

Returns the resource pool

get_reward_funds(use_stored_data: bool = True) → dict[str, Any] | None

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_token_per_mvest(time_stamp: int | datetime | 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)

get_witness_schedule(use_stored_data: bool = True) → dict[str, Any] | None

Return witness elected chain properties

property hardfork: int
info(use_stored_data: bool = True) → dict[str, Any] | None

Returns the global properties

is_connected() → bool

Returns if rpc is connected

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.

property is_steem: bool

Deprecated compatibility flag; always False in Hive-only nectar.

move_current_node_to_front() → None

Returns the default node list, until the first entry is equal to the current working node url

newWallet(pwd: str) → None

Create a new wallet. This method is basically only calls nectar.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) → TransactionBuilder

Let’s obtain a new txbuffer

Returns:

id of the new txbuffer

Return type:

int

post(title: str, body: str, author: str | None = None, permlink: str | None = None, reply_identifier: str | None = None, json_metadata: dict[str, Any] | None = None, comment_options: dict[str, Any] | None = None, community: str | None = None, app: str | None = None, tags: list[str] | None = None, beneficiaries: list[dict[str, Any]] | None = None, self_vote: bool = False, parse_body: bool = False, **kwargs) → dict[str, Any]

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_hbd': 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 and the category

  • app (str) – (Optional) Name of the app which are used for posting when not set, nectar/<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’ when community is not specified. 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: str
refresh_data(chain_property: str, force_refresh: bool = False, data_refresh_time_seconds: int | None = None) → None

Refresh and cache a specific blockchain data category in self.data.

This updates the cached value for the given chain_property (one of: “dynamic_global_properties”, “feed_history”, “hardfork_properties”, “witness_schedule”, “config”, “reward_funds”). If the cached value was refreshed recently (within self.data_refresh_time_seconds) and force_refresh is False, the method will skip the RPC call. When online, timestamps (last_refresh_*) and last_node are updated to reflect the refresh.

Parameters:

chain_property (str): The cache key to refresh; must be one of the supported properties. force_refresh (bool): If True, bypass the time-based refresh guard and force an update. data_refresh_time_seconds (float | None): If provided, set a new minimal refresh interval

(in seconds) before evaluating whether to skip refreshing.

Raises:

ValueError: If chain_property is not one of the supported keys.

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

Calculates the current HBD value of a vote

set_default_account(account: str) → None

Set the instance default account.

If given an account name or an Account object, validate/resolve it (an Account is constructed with this blockchain instance) and store the account identifier in the instance configuration under “default_account”. This makes the account the implicit default for subsequent operations that omit an explicit account.

Parameters:

account (str | Account): Account name or Account object to set as default.

Notes:

The Account constructor is invoked for validation; errors from account resolution/lookup may propagate.

set_default_nodes(nodes: list[str] | str) → None

Set the default nodes to be used

set_default_vote_weight(vote_weight: int) → None

Set the default vote weight to be used

set_password_storage(password_storage: str) → None

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 nectar wallet password

Parameters:

password_storage (str) – can be “no”, “keyring” or “environment”

sign(tx: dict[str, Any] | None = None, wifs: list[str] | str | None = None, reconstruct_tx: bool = True) → dict[str, Any]

Sign a transaction using provided WIFs or the wallet’s missing signatures and return the signed transaction.

If tx is provided, it is wrapped in a TransactionBuilder; otherwise the instance’s current txbuffer is used. Provided wifs (single string or list) are appended before missing required signatures are added. If reconstruct_tx is False and the transaction already contains signatures, it will not be reconstructed.

Parameters:

tx (dict, optional): A transaction object to sign. If omitted, the active txbuffer is used. wifs (str | list[str], optional): One or more WIF private keys to use for signing. If not provided, keys from the wallet for any missing signatures are used. reconstruct_tx (bool, optional): If False, do not reconstruct an already-built transaction; existing signatures are preserved. Defaults to True.

Returns:

dict: The signed transaction JSON with an added “trx_id” field containing the transaction id.

switch_blockchain(blockchain: str, update_nodes: bool = False) → None

Switch the instance to the specified blockchain (Hive only).

If the requested blockchain is already the configured default and update_nodes is False, this is a no-op. When update_nodes is True, the node list is refreshed via NodeList.update_nodes() and the default nodes are replaced with the Hive node list. The instance’s config[“default_chain”] is updated and, if the instance is not offline, a reconnect is attempted.

Parameters:

blockchain (str): Target blockchain; must be “hive”. update_nodes (bool): If True, refresh and replace the known node list before switching.

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

Estimate the token-backed-dollar (HBD-like) value that a vote from the given token power would yield.

Calculates the expected payout (in the blockchain’s backed token units) that a vote of vote_pct from an account with voting_power and token_power would contribute to a post with post_rshares. The estimate accounts for the vote rshares mechanics and the reduction of the reward pool when a not-yet-broadcast vote is included.

Parameters:

token_power (float): Voter’s token power (in vest/token-equivalent units used by the chain). post_rshares (int, optional): Current rshares of the post being voted on. Defaults to 0. voting_power (int, optional): Voter’s current voting power where 100% == HIVE_100_PERCENT (default full power). vote_pct (int, optional): Vote percentage where 100% == HIVE_100_PERCENT (default full vote). not_broadcasted_vote (bool, optional): If True, treat the vote as not yet broadcast (reduces available reward pool accordingly). use_stored_data (bool, optional): If True, prefer cached chain parameters; otherwise fetch fresh values.

Returns:

float: Estimated payout denominated in the backed token (e.g., HBD).

Raises:

Exception: Not implemented (function is a placeholder).

token_power_to_vests(token_power: float, timestamp: datetime | 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 token_symbol: str

get the current chains symbol for HIVE (e.g. “TESTS” on testnet)

tx() → TransactionBuilder

Returns the default transaction buffer

property txbuffer: TransactionBuilder

Returns the currently active tx buffer

unlock(*args, **kwargs) → bool | None

Unlock the internal wallet

update_account(account: str | Account | None = None, owner_key=None, active_key=None, memo_key=None, posting_key=None, password=None, additional_owner_keys: list[str] | None = None, additional_active_keys: list[str] | None = None, additional_posting_keys: list[str] | None = None, additional_owner_accounts: list[str] | None = None, additional_active_accounts: list[str] | None = None, additional_posting_accounts: list[str] | None = None, storekeys: bool = True, store_owner_key: bool = False, json_meta=None, **kwargs)

Update account

The brainkey/password can be used to recover all generated keys (see nectargraphenebase.account for more details.

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!

Parameters:

  • account_name (str) – (required) account name

  • json_meta (str) – Optional updated meta data for the account

  • owner_key (str) – Main owner (public) key

  • active_key (str) – Main active (public) key

  • posting_key (str) – Main posting (public) key

  • memo_key (str) – Main memo (public) 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)

Raises:

AccountExistsException – if the account already exists on the blockchain

update_proposal_votes(proposal_ids: list[int], approve: bool, account: str | Account | None = None, **kwargs: Any) → dict[str, Any]

Update proposal votes

Parameters:

  • proposal_ids (list) – list of proposal ids

  • approve (bool) – True/False

  • account (str) – (optional) witness account name

property vest_token_symbol: str

get the current chains symbol for VESTS

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

Convert vesting shares to reward r-shares used for voting.

Calculates the signed r-shares produced by a vote from a given amount of vesting shares, taking into account current voting power and vote percentage. Optionally subtracts the chain’s dust threshold so small votes become zero.

Parameters:

vests (float|int): Vesting shares (in VESTS units) to convert. voting_power (int, optional): Voter’s current voting power, where 100% == 10000. Defaults to HIVE_100_PERCENT. vote_pct (int, optional): Intended vote strength, where 100% == 10000. Can be negative for downvotes. Defaults to HIVE_100_PERCENT. subtract_dust_threshold (bool, optional): If True, subtract the chain’s dust threshold from the absolute r-shares and return 0 when the result is at-or-below the threshold. Defaults to True. use_stored_data (bool, optional): If True, prefer cached chain parameters when computing vote cost; otherwise fetch fresh values from the node. Defaults to True.

Returns:

int: Signed r-shares corresponding to the provided vesting shares and vote parameters. Returns 0 if the computed r-shares are at-or-below the dust threshold when subtraction is enabled.

vests_to_token_power(vests: float | Amount, timestamp: 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

vote(weight: float, identifier: str, account: str | Account | None = None, **kwargs) → dict[str, Any]

Cast a vote on a post.

Parameters:
weight (float): Vote weight in percent, range -100.0 to 100.0. This is

converted to the chain’s internal weight units (multiplied by HIVE_1_PERCENT) and clamped to the allowed range.

identifier (str): Post identifier in the form “@author/permlink”. account (str, optional): Name of the account to use for voting. If not

provided, the instance’s default_account from config is used. A ValueError is raised if no account can be determined.

Returns:

The result from finalizeOp (operation signing/broadcast buffer or broadcast response) after creating a Vote operation using posting permission.

witness_set_properties(wif: str, owner: str | Account, props: dict[str, Any]) → dict[str, Any]

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,
    "sbd_exchange_rate": x,
    "sbd_interest_rate": x,
    "new_signing_key": x
}
witness_update(signing_key: str, url: str, props: dict[str, Any], account: str | Account | None = None, **kwargs: Any) → dict[str, Any]

Create or update a witness (register or modify a block producer).

Creates a Witness_update operation for the given account with the provided signing key, node URL, and witness properties, then finalizes (signs/broadcasts or returns) the operation via the transaction pipeline.

Parameters:

signing_key (str): Witness block signing public key (must be valid for the chain prefix). url (str): URL for the witness (website or endpoint). props (dict): Witness properties, e.g.:

{

“account_creation_fee”: “3.000 HIVE”, “maximum_block_size”: 65536, “hbd_interest_rate”: 0,

} The “account_creation_fee” value will be converted to an Amount if present.

account (str, optional): Witness account name. If omitted, the instance default_account config is used.

Returns:

The value returned by finalizeOp (typically a transaction/broadcast result or a transaction builder when unsigned/bundled).

Raises:

ValueError: If no account is provided or resolvable. Exception: If the signing_key is not a valid public key for the chain prefix (propagates the underlying PublicKey error).