Database API
The database API is available from the full node via web-sockets.
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.
fc::variants graphene::app::database_api::get_objects(
const vector<object_id_type> &ids,
optional<bool> subscribe = optional<bool>())const
Parameters
Return
ids
: IDs of the objects to retrievesubscribe
: true to subscribe to the queried objects; false to not subscribe; null to subscribe or not subscribe according to current auto-subscription setting (see set_auto_subscription)
The objects retrieved, in the order they are mentioned in ids.
Register a callback handle which then can be used to subscribe to object database changes.
void graphene::app::database_api::set_subscribe_callback(
std::function<void(const variant&)> cb,
bool notify_remove_create, )
Parameters
cb
: The callback handle to registernotify_remove_create
: Whether subscribe to universal object creation and removal events. If this is set to true, the API server will notify all newly created objects and ID of all newly removed objects to the client, no matter whether client subscribed to the objects. By default, API servers don’t allow subscribing to universal events, which can be changed on server startup.
Register a callback handle which will get notified when a transaction is pushed to database.
Note: A transaction can be pushed to the database and be popped from the database several times while processing, before and after,, included in a block. Every time a push is done, the client will be notified.
void graphene::app::database_api::set_pending_transaction_callback(
std::function<void(const variant &signed_transaction_object)> cb)
Parameters
cb
: The callback handle to register
Register a callback handle which will get notified when a block is pushed to database.
void graphene::app::database_api::set_block_applied_callback(
std::function<void(const variant &block_id)> cb)
Parameters
cb
: The callback handle to register
Stop receiving any notifications.
This unsubscribes from all subscribed markets and objects.
void graphene::app::database_api::cancel_all_subscriptions()
Retrieve a block header.
optional<block_header> graphene::app::database_api::get_block_header(
uint32_t block_num)const
Parameters
Return
block_num
: Height of the block whose header should be returned
- The header of the referenced block, or null if no matching block was foun
Retrieve a full, signed block.
optional<signed_block> graphene::app::database_api::get_block(
uint32_t block_num)const
Parameters
Return
block_num
: Height of the block to be returned
The referenced block, or null if no matching block was found.
Fetch an individual transaction.
processed_transaction graphene::app::database_api::get_transaction(
uint32_t block_num, uint32_t trx_in_block)const
Parameters
Return
block_num
: height of the block to fetchtrx_in_block
: the index (sequence number) of the transaction in the block, starts from 0
The transaction at the given position.
optional<signed_transaction> graphene::app::database_api::get_recent_transaction_by_id(
const transaction_id_type &txid)const
Parameters
Return
txid
: hash of the transaction
The corresponding transaction if found, or null if not found.
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.
chain_property_object graphene::app::database_api::get_chain_properties()const
global_property_object graphene::app::database_api::get_global_properties()const
Retrieve compile-time constants.
fc::variant_object graphene::app::database_api::get_config()const
Get the chain ID.
chain_id_type graphene::app::database_api::get_chain_id()cons
dynamic_global_property_object graphene::app::database_api::get_dynamic_global_properties()const
Get all accounts that refer to the specified public keys in their owner authority, active authorities or memo key.
vector<flat_set<account_id_type>> graphene::app::database_api::get_key_references(
vector<public_key_type> keys)const
Parameters
Return
keys
: a list of public keys to query
ID of all accounts that refer to the specified keys.
Get a list of accounts by names or IDs.
vector<optional<account_object>> graphene::app::database_api::get_accounts(
const vector<std::string> &account_names_or_ids,
optional<bool> subscribe = optional<bool>())const
Parameters
Return
account_names_or_ids
: names or IDs of the accounts to retrievesubscribe
: true to subscribe to the queried account objects; false to not subscribe; null to subscribe or not subscribe according to current auto-subscription setting (see set_auto_subscription)
The accounts corresponding to the provided names or IDs.
Fetch all objects relevant to the specified accounts and optionally 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.std::map<string, full_account> graphene::app::database_api::get_full_accounts(
const vector<string> &names_or_ids,
optional<bool> subscribe = optional<bool>())
Parameters
Return
names_or_ids
: Each item must be the name or ID of an account to retrievesubscribe
: true to subscribe to the queried full account objects; false to not subscribe; null to subscribe or not subscribe according to current auto-subscription setting (see set_auto_subscription)
Map of string from
names_or_ids
to the corresponding account.Get info of an account by name.
optional<account_object> graphene::app::database_api::get_account_by_name(
string name)const
Parameters
Return
name
: Name of the account to retrieve
The account holding the provided name.
Get all accounts that refer to the specified account in their owner or active authorities.
vector<account_id_type> graphene::app::database_api::get_account_references(
const std::string account_name_or_id)const
Parameters
Return
account_name_or_id
: Account name or ID to query
All accounts that refer to the specified account in their owner or active authorities
Get a list of accounts by name.
vector<optional<account_object>> graphene::app::database_api::lookup_account_names(
const vector<string> &account_names)const
Parameters
Return
account_names
: Names of the accounts to retrieve
The accounts holding the provided names.
Get names and IDs for registered accounts.
Note: In addition to the common auto-subscription rules, this API will subscribe to the returned account only if
limit
is 1.map<string, account_id_type> graphene::app::database_api::lookup_accounts(
const string &lower_bound_name,
uint32_t limit,
optional<bool> subscribe = optional<bool>())const
Parameters
Return
lower_bound_name
: Lower bound of the first name to returnlimit
: Maximum number of results to return must not exceed 1000subscribe
: true to subscribe to the queried account objects; false to not subscribe; null to subscribe or not subscribe according to current auto-subscription setting (see set_auto_subscription).
Map of account names to corresponding IDs.
Get the total number of accounts registered with the blockchain.
uint64_t graphene::app::database_api::get_account_count()const
Get an account’s balances in various assets.
vector<asset> graphene::app::database_api::get_account_balances(
const std::string &account_name_or_id,
const flat_set<asset_id_type> &assets)const
Parameters
Return
account_name_or_id
: name or ID 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.
Balances of the account.
vector<asset> graphene::app::database_api::get_named_account_balances(
const std::string &name,
const flat_set<asset_id_type> &assets)const
Parameters
Return
account_name_or_id
: name or ID 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.
Balances of the account.
vector<balance_object> graphene::app::database_api::get_balance_objects(
const vector<address> &addrs)const
Parameters
Return
addrs
: a list of addresses
All unclaimed balance objects for the addresses.
Calculate how much assets in the given balance objects are able to be claimed at current head block time.
vector<asset> graphene::app::database_api::get_vested_balances(
const vector<balance_id_type> &objs)const
Parameters
Return
objs
: a list of balance object IDs
A list indicating how much asset in each balance object is available to be claimed.
Return all vesting balance objects owned by an account.
vector<vesting_balance_object> graphene::app::database_api::get_vesting_balances(
const std::string account_name_or_id)const
Parameters
Return
account_name_or_id
: name or ID of an account
All vesting balance objects owned by the account.
Get a list of assets by symbol names or IDs.
vector<optional<extended_asset_object>> graphene::app::database_api::get_assets(
const vector<std::string> &asset_symbols_or_ids,
optional<bool> subscribe = optional<bool>())const
Parameters
Return
asset_symbols_or_ids
: symbol names or IDs of the assets to retrievesubscribe
: true to subscribe to the queried asset objects; false to not subscribe; null to subscribe or not subscribe according to current auto-subscription setting (see set_auto_subscription)
The assets corresponding to the provided symbol names or IDs.
Get assets alphabetically by symbol name.
vector<extended_asset_object> graphene::app::database_api::list_assets(
const string &lower_bound_symbol,
uint32_t limit)const
Parameters
Return
lower_bound_symbol
: Lower bound of symbol names to retrievelimit
: Maximum number of assets to fetch (must not exceed 101)
The assets found.
Get a list of assets by symbol names or IDs.
vector<optional<extended_asset_object>> graphene::app::database_api::lookup_asset_symbols(
const vector<string> &symbols_or_ids)const
Parameters
Return
symbols_or_ids
: symbol names or IDs of the assets to retrieve
The assets corresponding to the provided symbols or IDs
Returns the order book for the market base
order_book graphene::app::database_api::get_order_book(
const string &base,
const string "e,
unsigned limit = 50)const
Parameters
Return
base
: symbol name or ID of the base assetquote
: symbol name or ID of the quote assetlimit
: depth of the order book to retrieve, for bids and asks each, capped at 50
Order book of the market.
Get limit orders in a given market.
vector<limit_order_object> graphene::app::database_api::get_limit_orders(
std::string a,
std::string b,
uint32_t limit)const
Parameters
Return
a
: symbol or ID of asset being soldb
: symbol or ID of asset being purchasedlimit
: Maximum number of orders to retrieve
The limit orders, ordered from least price to greatest.
Get call orders (aka margin positions) for a given asset.
vector<call_order_object> graphene::app::database_api::get_call_orders(
const std::string &a,
uint32_t limit)const
Parameters
Return
a
: symbol name or ID of the debt assetlimit
: Maximum number of orders to retrieve
The call orders, ordered from earliest to be called to latest
Get forced settlement orders in a given asset.
vector<force_settlement_object> graphene::app::database_api::get_settle_orders(
const std::string &a,
uint32_t limit)const
Parameters
Return
a
: Symbol or ID of asset being settledlimit
: Maximum number of orders to retrieve
The settle orders, ordered from earliest settlement date to latest.
Get all open margin positions of a given account.
vector<call_order_object> graphene::app::database_api::get_margin_positions(
const std::string account_name_or_id)const
Parameters
Return
account_name_or_id
: name or ID of an account
All open margin positions of the account.
Request notification when the active orders in the market between two assets changes.
Callback will be passed a variant containing a vector<pair<operation, operation_result>>.
The vector will contain, in order, the operations which changed the market, and their results
void graphene::app::database_api::subscribe_to_market(std::function<void(
const variant&)> callback,
const std::string &a,
const std::string &b, )
Parameters
callback
: Callback method which is called when the market changesa
: symbol name or ID of the first assetb
: symbol name or ID of the second asset
Unsubscribe from updates to a given market.
void graphene::app::database_api::unsubscribe_from_market(
const std::string &a,
const std::string &b)
Parameters
a
: symbol name or ID of the first assetb
: symbol name or ID of the second asset
Returns the ticker for the market assetA:assetB.
market_ticker graphene::app::database_api::get_ticker(
const string &base,
const string "e)const
Parameters
Return
base
: symbol name or ID of the base assetquote
: symbol name or ID of the quote asset
The market ticker for the past 24 hours.
Returns the 24 hour volume for the market assetA:assetB.
market_volume graphene::app::database_api::get_24_volume(
const string &base,
const string "e)const
Parameters
Return
base
: symbol name or ID of the base assetquote
: symbol name or ID of the quote asset
The market volume over the past 24 hours.
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 there are more than 100 trades occurring in the same second, this API only returns the first 100 records; use get_trade_history_by_sequence to query for the rest.
vector<market_trade> graphene::app::database_api::get_trade_history(
const string &base,
const string "e,
fc::time_point_sec start,
fc::time_point_sec stop,
unsigned limit = 100)const
Parameters
Return
base
: symbol or ID of the base assetquote
: symbol or ID of the quote assetstart
: Start time as a UNIX timestamp, the latest trade to retrievestop
: Stop time as a UNIX timestamp, the earliest trade to retrievelimit
: Number of transactions to retrieve, capped at 100.
Recent transactions in the market
Get a list of witnesses by ID.
vector<optional<witness_object>> graphene::app::database_api::get_witnesses(
const vector<witness_id_type> &witness_ids)const
Parameters
Return
witness_ids
: IDs of the witnesses to retrieve
The witnesses corresponding to the provided IDs.
Get the witness owned by a given account.
fc::optional<witness_object> graphene::app::database_api::get_witness_by_account(
const std::string account_name_or_id)const
Parameters
Return
account_name_or_id
: The name or ID of the account whose witness should be retrieved
The witness object, or null if the account does not have a witness.
Get names and IDs for registered witnesses.
map<string, witness_id_type> graphene::app::database_api::lookup_witness_accounts(
const string &lower_bound_name, uint32_t limit)const
Parameters
Return
lower_bound_name
: Lower bound of the first name to returnlimit
: Maximum number of results to return must not exceed 1000
Map of witness names to corresponding IDs.
Get the total number of witnesses registered with the blockchain.
uint64_t graphene::app::database_api::get_witness_count()const
Get a list of committee_members by ID.
vector<optional<committee_member_object>> graphene::app::database_api::get_committee_members(
const vector<committee_member_id_type> &committee_member_ids)const
Parameters
Return
committee_member_ids
: IDs of the committee_members to retrieve
The committee_members corresponding to the provided IDs.
Get the committee_member owned by a given account.
fc::optional<committee_member_object> graphene::app::database_api::get_committee_member_by_account(
const string account_name_or_id)const
Parameters
Return
account_name_or_id
: The name or ID of the account whose committee_member should be retrieved
The committee_member object, or null if the account does not have a committee_member.
Get names and IDs for registered committee_members.
map<string, committee_member_id_type> graphene::app::database_api::lookup_committee_member_accounts(
const string &lower_bound_name,
uint32_t limit)const
Parameters
Return
lower_bound_name
: Lower bound of the first name to returnlimit
: Maximum number of results to return must not exceed 1000
Map of committee_member names to corresponding IDs
Get the workers owned by a given account.
vector<optional<worker_object>> graphene::app::database_api::get_workers_by_account(
const std::string account_name_or_id)const
Parameters
Return
account_name_or_id
: The name or ID of the account whose worker should be retrieved
A list of worker objects owned by the account.
Given a set of votes, returns the objects they are voting for.
This will be a mixture of
committee_member_objects
, witness_objects
, and worker_objects
vector<variant> graphene::app::database_api::lookup_vote_ids(
const vector<vote_id_type> &votes)const
Parameters
Return
votes
: a list of vote IDs
The referenced objects
The results will be in the same order as the votes. Null will be returned for any vote IDs that are not found.
Get a hexdump of the serialized binary form of a transaction.
std::string graphene::app::database_api::get_transaction_hex(
const signed_transaction &trx)const
Parameters
Return
trx
: a transaction to get hexdump from
The hexdump of the transaction.
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.
set<public_key_type> graphene::app::database_api::get_required_signatures(
const signed_transaction &trx,
const flat_set<public_key_type> &available_keys)const
Parameters
Return
trx
: the transaction to be signedavailable_keys
: a set of public keys
A subset of
available_keys
that could sign for the given transaction.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.
set<public_key_type> graphene::app::database_api::get_potential_signatures(
const signed_transaction &trx)const
Parameters
Return
trx
: the transaction to be signed
A set of public keys that could possibly sign for the given transaction.
This method will return the set of all addresses that could possibly sign for a given transaction.
set<address> graphene::app::database_api::get_potential_address_signatures(
const signed_transaction &trx)const