4.1. Database API¶

The database API is available from the full node via websockets.

If you have not set up your websockets connection, please read this article.

Table of Contents

Objects
- get_objects
Subscriptions
Blocks and transactions
Globals
Keys
- get_key_references
Accounts
Balances
Assets
Markets / feeds
Witnesses
Committee members
Workers
- get_workers_by_account
Votes
- lookup_vote_ids
Authority / Validation
Proposed Transactions
- get_proposed_transactions
Blinded balances
- get_blinded_balances

4.1.1. Objects ¶

4.1.1.1. get_objects ¶

fc::variants graphene::app::database_api::get_objects(const vector<object_id_type> &ids) const¶

Get the objects corresponding to the provided IDs.

If any of the provided IDs does not map to an object, a null variant is returned in its position.

Return

The objects retrieved, in the order they are mentioned in ids

Parameters

ids: IDs of the objects to retrieve

4.1.2. Subscriptions ¶

4.1.2.2. set_pending_transaction_callback ¶

void graphene::app::database_api::set_pending_transaction_callback(std::function<void(const variant &signed_transaction_object)> cb)¶

Register a callback handle which will get notified when a transaction is pushed to database.

Note: a transaction can be pushed to database and be popped from database several times while processing, before and after included in a block. Everytime when a push is done, the client will be notified.

Parameters

cb: The callback handle to register

4.1.2.3. set_block_applied_callback ¶

void graphene::app::database_api::set_block_applied_callback(std::function<void(const variant &block_id)> cb)¶

Register a callback handle which will get notified when a block is pushed to database.

Parameters

cb: The callback handle to register

4.1.2.4. cancel_all_subscriptions ¶

void graphene::app::database_api::cancel_all_subscriptions()¶

Stop receiving any notifications.

This unsubscribes from all subscribed markets and objects.

4.1.3. Blocks and transactions ¶

4.1.3.1. get_block_header ¶

optional<block_header> graphene::app::database_api::get_block_header(uint32_t block_num) const¶

Retrieve a block header.

Return

header of the referenced block, or null if no matching block was found

Parameters

block_num: Height of the block whose header should be returned

4.1.3.2. get_block ¶

optional<signed_block> graphene::app::database_api::get_block(uint32_t block_num) const¶

Retrieve a full, signed block.

Return

the referenced block, or null if no matching block was found

Parameters

block_num: Height of the block to be returned

4.1.3.3. get_transaction ¶

processed_transaction graphene::app::database_api::get_transaction(uint32_t block_num, uint32_t trx_in_block) const¶: used to fetch an individual transaction.

4.1.3.4. get_recent_transaction_by_id ¶

optional<signed_transaction> graphene::app::database_api::get_recent_transaction_by_id(const transaction_id_type &id) const¶: If the transaction has not expired, this method will return the transaction for the given ID or it will return NULL if it is not known. Just because it is not known does not mean it wasn’t included in the blockchain.

4.1.4. Globals ¶

4.1.4.1. get_chain_properties ¶

chain_property_object graphene::app::database_api::get_chain_properties() const¶: Retrieve the chain_property_object associated with the chain.

4.1.4.2. get_global_properties ¶

global_property_object graphene::app::database_api::get_global_properties() const¶: Retrieve the current global_property_object.

4.1.4.3. get_config ¶

fc::variant_object graphene::app::database_api::get_config() const¶: Retrieve compile-time constants.

4.1.4.4. get_chain_id ¶

chain_id_type graphene::app::database_api::get_chain_id() const¶: Get the chain ID.

4.1.4.5. get_dynamic_global_properties ¶

dynamic_global_property_object graphene::app::database_api::get_dynamic_global_properties() const¶: Retrieve the current dynamic_global_property_object.

4.1.5. Keys ¶

4.1.5.1. get_key_references ¶

vector<vector<account_id_type>> graphene::app::database_api::get_key_references(vector<public_key_type> key) const¶

4.1.6. Accounts ¶

4.1.6.1. get_accounts ¶

vector<optional<account_object>> graphene::app::database_api::get_accounts(const vector<std::string> &account_names_or_ids) const¶

Get a list of accounts by ID.

This function has semantics identical to

get_objects

Return

The accounts corresponding to the provided IDs

Parameters

account_names_or_ids: IDs or names of the accounts to retrieve

4.1.6.2. get_full_accounts ¶

std::map<string, full_account> graphene::app::database_api::get_full_accounts(const vector<string> &names_or_ids, bool subscribe)¶

Fetch all objects relevant to the specified accounts and subscribe to updates.

This function fetches all relevant objects for the given accounts, and subscribes to updates to the given accounts. If any of the strings in names_or_ids cannot be tied to an account, that input will be ignored. All other accounts will be retrieved and subscribed.

Return

Map of string from names_or_ids to the corresponding account

Parameters

callback: Function to call with updates
names_or_ids: Each item must be the name or ID of an account to retrieve

4.1.6.3. get_account_by_name ¶

optional<account_object> graphene::app::database_api::get_account_by_name(string name) const¶

4.1.6.4. get_account_references ¶

vector<account_id_type> graphene::app::database_api::get_account_references(const std::string account_id_or_name) const¶

Return: all accounts that referr to the key or account id in their owner or active authorities.

4.1.6.5. lookup_account_names ¶

vector<optional<account_object>> graphene::app::database_api::lookup_account_names(const vector<string> &account_names) const¶

Get a list of accounts by name.

This function has semantics identical to

get_objects

Return

The accounts holding the provided names

Parameters

account_names: Names of the accounts to retrieve

4.1.6.6. lookup_accounts ¶

map<string, account_id_type> graphene::app::database_api::lookup_accounts(const string &lower_bound_name, uint32_t limit) const¶

Get names and IDs for registered accounts.

Return

Map of account names to corresponding IDs

Parameters

lower_bound_name: Lower bound of the first name to return
limit: Maximum number of results to return must not exceed 1000

4.1.6.7. get_account_count ¶

uint64_t graphene::app::database_api::get_account_count() const¶: Get the total number of accounts registered with the blockchain.

4.1.7. Balances ¶

4.1.7.1. get_account_balances ¶

vector<asset> graphene::app::database_api::get_account_balances(const std::string &account_name_or_id, const flat_set<asset_id_type> &assets) const¶

Get an account’s balances in various assets.

Return

Balances of the account

Parameters

account_name_or_id: ID or name of the account to get balances for
assets: IDs of the assets to get balances of; if empty, get all assets account has a balance in

4.1.7.2. get_named_account_balances ¶

vector<asset> graphene::app::database_api::get_named_account_balances(const std::string &name, const flat_set<asset_id_type> &assets) const¶: Semantically equivalent to get_account_balances, but takes a name instead of an ID.

4.1.7.3. get_balance_objects ¶

vector<balance_object> graphene::app::database_api::get_balance_objects(const vector<address> &addrs) const¶

Return: all unclaimed balance objects for a set of addresses

4.1.7.4. get_vested_balances ¶

vector<asset> graphene::app::database_api::get_vested_balances(const vector<balance_id_type> &objs) const¶

4.1.7.5. get_vesting_balances ¶

vector<vesting_balance_object> graphene::app::database_api::get_vesting_balances(const std::string account_id_or_name) const¶

4.1.8. Assets ¶

4.1.8.1. get_assets ¶

vector<optional<asset_object>> graphene::app::database_api::get_assets(const vector<asset_id_type> &asset_ids) const¶

Get a list of assets by ID.

This function has semantics identical to

get_objects

Return

The assets corresponding to the provided IDs

Parameters

asset_ids: IDs of the assets to retrieve

4.1.8.2. list_assets ¶

vector<asset_object> graphene::app::database_api::list_assets(const string &lower_bound_symbol, uint32_t limit) const¶

Get assets alphabetically by symbol name.

Return

The assets found

Parameters

lower_bound_symbol: Lower bound of symbol names to retrieve
limit: Maximum number of assets to fetch (must not exceed 101)

4.1.8.3. lookup_asset_symbols ¶

vector<optional<asset_object>> graphene::app::database_api::lookup_asset_symbols(const vector<string> &symbols_or_ids) const¶

Get a list of assets by symbol.

This function has semantics identical to

get_objects

Return

The assets corresponding to the provided symbols or IDs

Parameters

asset_symbols: Symbols or stringified IDs of the assets to retrieve

4.1.9. Markets / feeds ¶

4.1.9.1. get_order_book ¶

order_book graphene::app::database_api::get_order_book(const string &base, const string &quote, unsigned limit = 50) const¶

Returns the order book for the market base:quote.

Return

Order book of the market

Parameters

base: String name of the first asset
quote: String name of the second asset
depth: of the order book. Up to depth of each asks and bids, capped at 50. Prioritizes most moderate of each

4.1.9.2. get_limit_orders ¶

vector<limit_order_object> graphene::app::database_api::get_limit_orders(asset_id_type a, asset_id_type b, uint32_t limit) const¶

Get limit orders in a given market.

Return

The limit orders, ordered from least price to greatest

Parameters

a: ID of asset being sold
b: ID of asset being purchased
limit: Maximum number of orders to retrieve

4.1.9.3. get_call_orders ¶

vector<call_order_object> graphene::app::database_api::get_call_orders(asset_id_type a, uint32_t limit) const¶

Get call orders in a given asset.

Return

The call orders, ordered from earliest to be called to latest

Parameters

a: ID of asset being called
limit: Maximum number of orders to retrieve

4.1.9.4. get_settle_orders ¶

vector<force_settlement_object> graphene::app::database_api::get_settle_orders(asset_id_type a, uint32_t limit) const¶

Get forced settlement orders in a given asset.

Return

The settle orders, ordered from earliest settlement date to latest

Parameters

a: ID of asset being settled
limit: Maximum number of orders to retrieve

4.1.9.5. get_margin_positions ¶

vector<call_order_object> graphene::app::database_api::get_margin_positions(const std::string account_id_or_name) const¶

Return: all open margin positions for a given account id or name.

4.1.9.7. unsubscribe_from_market ¶

void graphene::app::database_api::unsubscribe_from_market(asset_id_type a, asset_id_type b)¶

Unsubscribe from updates to a given market.

Parameters

a: First asset ID
b: Second asset ID

4.1.9.8. get_ticker ¶

market_ticker graphene::app::database_api::get_ticker(const string &base, const string &quote) const¶

Returns the ticker for the market assetA:assetB.

Return

The market ticker for the past 24 hours.

Parameters

a: String name of the first asset
b: String name of the second asset

4.1.9.9. get_24_volume ¶

market_volume graphene::app::database_api::get_24_volume(const string &base, const string &quote) const¶

Returns the 24 hour volume for the market assetA:assetB.

Return

The market volume over the past 24 hours

Parameters

a: String name of the first asset
b: String name of the second asset

4.1.9.10. get_trade_history ¶

vector<market_trade> graphene::app::database_api::get_trade_history(const string &base, const string &quote, fc::time_point_sec start, fc::time_point_sec stop, unsigned limit = 100) const¶

Returns recent trades for the market base:quote, ordered by time, most recent first. Note: Currently, timezone offsets are not supported. The time must be UTC. The range is [stop, start). In case when there are more than 100 trades occurred in the same second, this API only returns the first 100 records, can use another API get_trade_history_by_sequence to query for the rest.

Return

Recent transactions in the market

Parameters

base: symbol or ID of the base asset
quote: symbol or ID of the quote asset
start: Start time as a UNIX timestamp, the latest trade to retrieve
stop: Stop time as a UNIX timestamp, the earliest trade to retrieve
limit: Number of trasactions to retrieve, capped at 100.

4.1.10. Witnesses ¶

4.1.10.1. get_witnesses ¶

vector<optional<witness_object>> graphene::app::database_api::get_witnesses(const vector<witness_id_type> &witness_ids) const¶

Get a list of witnesses by ID.

This function has semantics identical to

get_objects

Return

The witnesses corresponding to the provided IDs

Parameters

witness_ids: IDs of the witnesses to retrieve

4.1.10.2. get_witness_by_account ¶

fc::optional<witness_object> graphene::app::database_api::get_witness_by_account(const std::string account_id_or_name) const¶

Get the witness owned by a given account.

Return

The witness object, or null if the account does not have a witness

Parameters

account_id_or_name: The ID of the account whose witness should be retrieved

4.1.10.3. lookup_witness_accounts ¶

map<string, witness_id_type> graphene::app::database_api::lookup_witness_accounts(const string &lower_bound_name, uint32_t limit) const¶

Get names and IDs for registered witnesses.

Return

Map of witness names to corresponding IDs

Parameters

lower_bound_name: Lower bound of the first name to return
limit: Maximum number of results to return must not exceed 1000

4.1.10.4. get_witness_count ¶

uint64_t graphene::app::database_api::get_witness_count() const¶: Get the total number of witnesses registered with the blockchain.

4.1.11. Committee members ¶

4.1.11.1. get_committee_members ¶

vector<optional<committee_member_object>> graphene::app::database_api::get_committee_members(const vector<committee_member_id_type> &committee_member_ids) const¶

Get a list of committee_members by ID.

This function has semantics identical to

get_objects

Return

The committee_members corresponding to the provided IDs

Parameters

committee_member_ids: IDs of the committee_members to retrieve

4.1.11.2. get_committee_member_by_account ¶

fc::optional<committee_member_object> graphene::app::database_api::get_committee_member_by_account(const std::string account_id_or_name) const¶

Get the committee_member owned by a given account.

Return

The committee_member object, or null if the account does not have a committee_member

Parameters

account: The ID or name of the account whose committee_member should be retrieved

4.1.11.3. lookup_committee_member_accounts ¶

map<string, committee_member_id_type> graphene::app::database_api::lookup_committee_member_accounts(const string &lower_bound_name, uint32_t limit) const¶

Get names and IDs for registered committee_members.

Return

Map of committee_member names to corresponding IDs

Parameters

lower_bound_name: Lower bound of the first name to return
limit: Maximum number of results to return must not exceed 1000

4.1.12. Workers ¶

4.1.12.1. get_workers_by_account ¶

vector<optional<worker_object>> graphene::app::database_api::get_workers_by_account(const std::string account_id_or_name) const¶

Get the workers owned by a given account.

Return

The worker object, or null if the account does not have a worker

Parameters

account_id_or_name: The ID or name of the account whose worker should be retrieved

4.1.13. Votes ¶

4.1.13.1. lookup_vote_ids ¶

vector<variant> graphene::app::database_api::lookup_vote_ids(const vector<vote_id_type> &votes) const¶

Given a set of votes, return the objects they are voting for.

This will be a mixture of committee_member_object, witness_objects, and worker_objects

The results will be in the same order as the votes. Null will be returned for any vote ids that are not found.

4.1.14. Authority / Validation ¶

4.1.14.1. get_transaction_hex ¶

std::string graphene::app::database_api::get_transaction_hex(const signed_transaction &trx) const¶: Get a hexdump of the serialized binary form of a transaction.

4.1.14.2. get_required_signatures ¶

set<public_key_type> graphene::app::database_api::get_required_signatures(const signed_transaction &trx, const flat_set<public_key_type> &available_keys) const¶: This API will take a partially signed transaction and a set of public keys that the owner has the ability to sign for and return the minimal subset of public keys that should add signatures to the transaction.

4.1.14.3. get_potential_signatures ¶

set<public_key_type> graphene::app::database_api::get_potential_signatures(const signed_transaction &trx) const¶: This method will return the set of all public keys that could possibly sign for a given transaction. This call can be used by wallets to filter their set of public keys to just the relevant subset prior to calling get_required_signatures to get the minimum subset.

4.1.14.4. get_potential_address_signatures ¶

set<address> graphene::app::database_api::get_potential_address_signatures(const signed_transaction &trx) const¶

4.1.14.5. verify_authority ¶

bool graphene::app::database_api::verify_authority(const signed_transaction &trx) const¶

Return: true of the trx has all of the required signatures, otherwise throws an exception

4.1.14.6. verify_account_authority ¶

bool graphene::app::database_api::verify_account_authority(const string &account_name_or_id, const flat_set<public_key_type> &signers) const¶

Return: true if the signers have enough authority to authorize an account

4.1.14.7. validate_transaction ¶

processed_transaction graphene::app::database_api::validate_transaction(const signed_transaction &trx) const¶: Validates a transaction against the current state without broadcasting it on the network.

4.1.14.8. get_required_fees ¶

vector<fc::variant> graphene::app::database_api::get_required_fees(const vector<operation> &ops, asset_id_type id) const¶: For each operation calculate the required fee in the specified asset type. If the asset type does not have a valid core_exchange_rate

4.1.15. Proposed Transactions ¶

4.1.15.1. get_proposed_transactions ¶

vector<proposal_object> graphene::app::database_api::get_proposed_transactions(const std::string account_id_or_name) const¶

Return: the set of proposed transactions relevant to the specified account id.

4.1.16. Blinded balances ¶

4.1.16.1. get_blinded_balances ¶

vector<blinded_balance_object> graphene::app::database_api::get_blinded_balances(const flat_set<commitment_type> &commitments) const¶

Return: the set of blinded balance objects by commitment ID