Operations¶
graphene::chain::base_operation
This document purpose: to describe Graphene available operations details and the object structures. Learning Graphene-Core Available Operations!
You can find Operations and OperationIDs pairs here.
Table of Contents
Operations have been carefully designed to include all of the information necessary to interpret them outside the context of the blockchain. This means that information about current chain state is included in the operation even though it could be inferred from a subset of the data. This makes the expected outcome of each operation well defined and easily understood without access to chain state.
Detailed Descriptions
Account¶
account_create_operation¶
struct account_create_operation : public base_operation
{
struct ext
{
optional< void_t > null_ext;
optional< special_authority > owner_special_authority;
optional< special_authority > active_special_authority;
optional< buyback_account_options > buyback_options;
};
struct fee_parameters_type
{
uint64_t basic_fee = 5*GRAPHENE_BLOCKCHAIN_PRECISION; ///< the cost to register the cheapest non-free account
uint64_t premium_fee = 2000*GRAPHENE_BLOCKCHAIN_PRECISION; ///< the cost to register the cheapest non-free account
uint32_t price_per_kbyte = GRAPHENE_BLOCKCHAIN_PRECISION;
};
asset fee;
/// This account pays the fee. Must be a lifetime member.
account_id_type registrar;
/// This account receives a portion of the fee split between registrar and referrer. Must be a member.
account_id_type referrer;
/// Of the fee split between registrar and referrer, this percentage goes to the referrer. The rest goes to the
/// registrar.
uint16_t referrer_percent = 0;
string name;
authority owner;
authority active;
account_options options;
extension< ext > extensions;
account_id_type fee_payer()const { return registrar; }
void validate()const;
share_type calculate_fee(const fee_parameters_type& )const;
void get_required_active_authorities( flat_set<account_id_type>& a )const
{
// registrar should be required anyway as it is the fee_payer(), but we insert it here just to be sure
a.insert( registrar );
if( extensions.value.buyback_options.valid() )
a.insert( extensions.value.buyback_options->asset_to_buy_issuer );
}
};
account_transfer_operation¶
Transfers the account to another account while clearing the white list.
In theory an account can be transferred by simply updating the authorities, but that kind of transfer lacks semantic meaning and is more often done to rotate keys without transferring ownership.
This operation is used to indicate the legal transfer of title to this account and a break in the operation history.
The account_id’s owner/active/voting/memo authority should be set to new_owner
This operation will clear the account’s whitelist statuses, but not the blacklist statuses.
struct account_transfer_operation : public base_operation
{
struct fee_parameters_type { uint64_t fee = 500 * GRAPHENE_BLOCKCHAIN_PRECISION; };
asset fee;
account_id_type account_id;
account_id_type new_owner;
extensions_type extensions;
account_id_type fee_payer()const { return account_id; }
void validate()const;
};
account_update_operation¶
Update an existing account.
This operation is used to update an existing account. It can be used to update the authorities, or adjust the options on the account.
See
account_object::options_type
for the options which may be updated.
struct account_update_operation : public base_operation
{
struct ext
{
optional< void_t > null_ext;
optional< special_authority > owner_special_authority;
optional< special_authority > active_special_authority;
};
struct fee_parameters_type
{
share_type fee = 20 * GRAPHENE_BLOCKCHAIN_PRECISION;
uint32_t price_per_kbyte = GRAPHENE_BLOCKCHAIN_PRECISION;
};
asset fee;
/// The account to update
account_id_type account;
/// New owner authority. If set, this operation requires owner authority to execute.
optional<authority> owner;
/// New active authority. This can be updated by the current active authority.
optional<authority> active;
/// New account options
optional<account_options> new_options;
extension< ext > extensions;
account_id_type fee_payer()const { return account; }
void validate()const;
share_type calculate_fee( const fee_parameters_type& k )const;
bool is_owner_update()const
{ return owner || extensions.value.owner_special_authority.valid(); }
void get_required_owner_authorities( flat_set<account_id_type>& a )const
{ if( is_owner_update() ) a.insert( account ); }
void get_required_active_authorities( flat_set<account_id_type>& a )const
{ if( !is_owner_update() ) a.insert( account ); }
};
account_upgrade_operation¶
Manage an account’s membership status
This operation is used to upgrade an account to a member, or renew its subscription.
If an account which is an unexpired annual subscription member publishes this operation with
upgrade_to_lifetime_member
set tofalse
, the account’s membership expiration date will be pushed backward one year.If a basic account publishes it with
upgrade_to_lifetime_member
set to false, the account will be upgraded to a subscription member with an expiration date one year after the processing time of this operation.Any account may use this operation to become a lifetime member by setting
upgrade_to_lifetime_member
to true. Once an account has become a lifetime member, it may not use this operation anymore.
Note
Due to some discrepancies, the annual membership has been disabled in most web wallets and will be re-enabled after a proper update eventually.
In Q1/2016, the annual membership has been removed from the code base and no longer exists. References to this kind of memberships can be safely ignored.
struct account_upgrade_operation : public base_operation
{
struct fee_parameters_type {
uint64_t membership_annual_fee = 2000 * GRAPHENE_BLOCKCHAIN_PRECISION;
uint64_t membership_lifetime_fee = 10000 * GRAPHENE_BLOCKCHAIN_PRECISION; ///< the cost to upgrade to a lifetime member
};
asset fee;
/// The account to upgrade; must not already be a lifetime member
account_id_type account_to_upgrade;
/// If true, the account will be upgraded to a lifetime member; otherwise, it will add a year to the subscription
bool upgrade_to_lifetime_member = false;
extensions_type extensions;
account_id_type fee_payer()const { return account_to_upgrade; }
void validate()const;
share_type calculate_fee( const fee_parameters_type& k )const;
};
account_whitelist_operation¶
This operation is used to whitelist and blacklist accounts, primarily for transacting in whitelisted assets.
Accounts can freely specify opinions about other accounts, in the form of either whitelisting or blacklisting them. This information is used in chain validation only to determine whether an account is authorized to transact in an asset type which enforces a whitelist, but third parties can use this information for other uses as well, as long as it does not conflict with the use of whitelisted assets.
An asset which enforces a whitelist specifies a list of accounts to maintain its whitelist, and a list of accounts to maintain its blacklist. In order for a given account A to hold and transact in a whitelisted asset S, A must be whitelisted by at least one of S’s whitelist_authorities and blacklisted by none of S’s blacklist_authorities. If A receives a balance of S, and is later removed from the whitelist(s) which allowed it to hold S, or added to any blacklist S specifies as authoritative, A’s balance of S will be frozen until A’s authorization is reinstated.
This operation requires authorizing_account’s signature, but not account_to_list’s. The fee is paid by
authorizing_account
struct account_whitelist_operation : public base_operation
{
struct fee_parameters_type { share_type fee = 300000; };
enum account_listing {
no_listing = 0x0, ///< No opinion is specified about this account
white_listed = 0x1, ///< This account is whitelisted, but not blacklisted
black_listed = 0x2, ///< This account is blacklisted, but not whitelisted
white_and_black_listed = white_listed | black_listed ///< This account is both whitelisted and blacklisted
};
/// Paid by authorizing_account
asset fee;
/// The account which is specifying an opinion of another account
account_id_type authorizing_account;
/// The account being opined about
account_id_type account_to_list;
/// The new white and blacklist status of account_to_list, as determined by authorizing_account
/// This is a bitfield using values defined in the account_listing enum
uint8_t new_listing = no_listing;
extensions_type extensions;
account_id_type fee_payer()const { return authorizing_account; }
void validate()const { FC_ASSERT( fee.amount >= 0 ); FC_ASSERT(new_listing < 0x4); }
};
Assert¶
assert_operation¶
assert that some conditions are true.
This operation performs no changes to the database state, but can used to verify pre or post conditions for other operations.
struct assert_operation : public base_operation
{
struct fee_parameters_type { uint64_t fee = GRAPHENE_BLOCKCHAIN_PRECISION; };
asset fee;
account_id_type fee_paying_account;
vector<predicate> predicates;
flat_set<account_id_type> required_auths;
extensions_type extensions;
account_id_type fee_payer()const { return fee_paying_account; }
void validate()const;
share_type calculate_fee(const fee_parameters_type& k)const;
};
Asset¶
asset_claim_fees_operation¶
used to transfer accumulated fees back to the issuer’s balance.
struct asset_claim_fees_operation : public base_operation
{
struct fee_parameters_type {
uint64_t fee = 20 * GRAPHENE_BLOCKCHAIN_PRECISION;
};
asset fee;
account_id_type issuer;
asset amount_to_claim;
extensions_type extensions;
account_id_type fee_payer()const { return issuer; }
void validate()const;
};
asset_claim_pool_operation¶
Transfers GPH from the fee pool of a specified asset back to the issue’s balance.
Parameters
fee Payment for the operation execution
issuer Account which will be used for transfering GPH
asset_id Id of the asset whose fee pool is going to be drained
amount_to_claim Amount of GPH to claim from the fee pool
extensions Field for future expansion
Precondition
fee must be paid in the asset other than the one whose pool is being drained
amount_to_claim should be specified in the core asset
amount_to_claim should be nonnegative
struct asset_claim_pool_operation : public base_operation
{
struct fee_parameters_type {
uint64_t fee = 20 * GRAPHENE_BLOCKCHAIN_PRECISION;
};
asset fee;
account_id_type issuer;
asset_id_type asset_id;
asset amount_to_claim;
extensions_type extensions;
account_id_type fee_payer()const { return issuer; }
void validate()const;
};
asset_create_operation¶
struct asset_create_operation : public base_operation
{
struct fee_parameters_type {
uint64_t symbol3 = 500000 * GRAPHENE_BLOCKCHAIN_PRECISION;
uint64_t symbol4 = 300000 * GRAPHENE_BLOCKCHAIN_PRECISION;
uint64_t long_symbol = 5000 * GRAPHENE_BLOCKCHAIN_PRECISION;
uint32_t price_per_kbyte = 10;
}
};
asset_fund_fee_pool_operation¶
struct asset_fund_fee_pool_operation : public base_operation
{
struct fee_parameters_type { uint64_t fee = GRAPHENE_BLOCKCHAIN_PRECISION; };
asset fee;
account_id_type from_account;
asset_id_type asset_id;
share_type amount;
extensions_type extensions;
account_id_type fee_payer()const { return from_account; }
void validate()const;
};
asset_global_settle_operation¶
Allows global settling of bitassets (black swan or prediction markets)
In order to use this operation,
asset_to_settle
must have theglobal_settle
flag setWhen this operation is executed all balances are converted into the backing asset at the
settle_price
and all open margin positions are called at the settle price. If this asset is used as backing for other bitassets, those bitassets will be force settled at their current feed price.
struct asset_global_settle_operation : public base_operation
{
struct fee_parameters_type { uint64_t fee = 500 * GRAPHENE_BLOCKCHAIN_PRECISION; };
asset fee;
account_id_type issuer;
asset_id_type asset_to_settle;
price settle_price;
extensions_type extensions;
account_id_type fee_payer()const { return issuer; }
void validate()const;
};
asset_issue_operation¶
struct asset_issue_operation : public base_operation
{
struct fee_parameters_type {
uint64_t fee = 20 * GRAPHENE_BLOCKCHAIN_PRECISION;
uint32_t price_per_kbyte = GRAPHENE_BLOCKCHAIN_PRECISION;
};
asset_publish_feed_operation¶
Publish price feeds for market-issued assets
Price feed providers use this operation to publish their price feeds for market-issued assets. A price feed is used to tune the market for a particular market-issued asset. For each value in the feed, the median across all committee_member feeds for that asset is calculated and the market for the asset is configured with the median of that value.
The feed in the operation contains three prices: a call price limit, a short price limit, and a settlement price.
The call limit price is structured as
(collateral asset) / (debt asset)
and the short limit price is structured as(asset for sale) / (collateral asset)
.
Note
The asset IDs
are opposite to each other, so if we’re publishing a feed for USD, the call limit price will be CORE/USD
and the short limit price will be USD/CORE
. The settlement price may be flipped either direction, as long as it is a ratio between the market-issued asset and its collateral.
struct asset_publish_feed_operation : public base_operation
{
struct fee_parameters_type { uint64_t fee = GRAPHENE_BLOCKCHAIN_PRECISION; };
asset fee;
account_id_type publisher;
asset_id_type asset_id;
price_feed feed;
extensions_type extensions;
account_id_type fee_payer()const { return publisher; }
void validate()const;
};
asset_reserve_operation¶
used to take an asset out of circulation, returning to the issuer
Note
You cannot use this operation on market-issued assets.
struct asset_reserve_operation : public base_operation
{
struct fee_parameters_type { uint64_t fee = 20 * GRAPHENE_BLOCKCHAIN_PRECISION; };
asset fee;
account_id_type payer;
asset amount_to_reserve;
extensions_type extensions;
account_id_type fee_payer()const { return payer; }
void validate()const;
};
asset_settle_cancel_operation¶
Virtual op generated when force settlement is canceled.
struct asset_settle_cancel_operation : public base_operation
{
struct fee_parameters_type { };
asset fee;
force_settlement_id_type settlement;
account_id_type account;
asset amount;
extensions_type extensions;
account_id_type fee_payer()const { return account; }
void validate()const {
FC_ASSERT( amount.amount > 0, "Must settle at least 1 unit" );
}
share_type calculate_fee(const fee_parameters_type& params)const
{ return 0; }
};
asset_settle_operation¶
Schedules a market-issued asset for automatic settlement
Holders of market-issued assets may request a forced settlement for some amount of their asset. This means that the specified sum will be locked by the chain and held for the settlement period, after which time the chain will choose a margin position holder and buy the settled asset using the margin’s collateral. The price of this sale will be based on the feed price for the market-issued asset being settled. The exact settlement price will be the feed price at the time of settlement with an offset in favor of the margin position, where the offset is a blockchain parameter set in the
global_property_object
.The fee is paid by account, and account must authorize this operation
struct asset_settle_operation : public base_operation
{
struct fee_parameters_type {
uint64_t fee = 100 * GRAPHENE_BLOCKCHAIN_PRECISION;
};
asset fee;
account_id_type account;
asset amount;
extensions_type extensions;
account_id_type fee_payer()const { return account; }
void validate()const;
};
asset_update_bitasset_operation¶
Update options specific to BitAssets
BitAssets have some options which are not relevant to other asset types. This operation is used to update those options an an existing BitAsset.
Precondition
issuer
MUST be an existing account and MUST matchasset_object::issuer
onasset_to_update
asset_to_update MUST be a BitAsset, i.e.
asset_object::is_market_issued()
returns truefee MUST be nonnegative, and issuer MUST have a sufficient balance to pay it
new_options SHALL be internally consistent, as verified by
validate()
Postcondition
asset_to_update
will have BitAsset-specific options matching those of new_options
struct asset_update_bitasset_operation : public base_operation
{
struct fee_parameters_type { uint64_t fee = 500 * GRAPHENE_BLOCKCHAIN_PRECISION; };
asset fee;
account_id_type issuer;
asset_id_type asset_to_update;
bitasset_options new_options;
extensions_type extensions;
account_id_type fee_payer()const { return issuer; }
void validate()const;
};
asset_update_feed_producers_operation¶
Update the set of feed-producing accounts for a BitAsset
BitAssets have price feeds selected by taking the median values of recommendations from a set of feed producers. This operation is used to specify which accounts may produce feeds for a given BitAsset.
Precondition
issuer
MUST be an existing account, and MUST matchasset_object::issuer
on asset_to_updateissuer
MUST NOT be the committee accountasset_to_update
MUST be a BitAsset, i.e.asset_object::is_market_issued()
returns truefee
MUST be nonnegative, andissuer
MUST have a sufficient balance to pay itCardinality of
new_feed_producers
MUST NOT exceedchain_parameters::maximum_asset_feed_publishers
Postcondition
asset_to_update
will have a set of feed producers matchingnew_feed_producers
All valid feeds supplied by feed producers in
new_feed_producers
, which were already feed producers prior to execution of this operation, will be preserved
struct asset_update_feed_producers_operation : public base_operation
{
struct fee_parameters_type { uint64_t fee = 500 * GRAPHENE_BLOCKCHAIN_PRECISION; };
asset fee;
account_id_type issuer;
asset_id_type asset_to_update;
flat_set<account_id_type> new_feed_producers;
extensions_type extensions;
account_id_type fee_payer()const { return issuer; }
void validate()const;
};
asset_update_issuer_operation¶
Update issuer of an asset
An issuer has general administrative power of an asset and in some cases also its shares issued to individuals. Thus, changing the issuer today requires the use of a separate operation that needs to be signed by the owner authority.
struct asset_update_issuer_operation : public base_operation
{
struct fee_parameters_type {
uint64_t fee = 20 * GRAPHENE_BLOCKCHAIN_PRECISION;
};
asset fee;
account_id_type issuer;
asset_id_type asset_to_update;
account_id_type new_issuer;
extensions_type extensions;
account_id_type fee_payer()const { return issuer; }
void validate()const;
void get_required_owner_authorities( flat_set<account_id_type>& a )const
{ a.insert( issuer ); }
void get_required_active_authorities( flat_set<account_id_type>& a )const
{ }
};
asset_update_operation¶
Update options common to all assets
There are a number of options which all assets in the network use. These options are enumerated in the
asset_options
struct. This operation is used to update these options for an existing asset.
Note
This operation cannot be used to update BitAsset-specific options. For these options, use asset_update_bitasset_operation
instead
Precondition
issuer
SHALL be an existing account and MUST matchasset_object::issuer
on asset_to_updatefee
SHALL be nonnegative, andissuer
MUST have a sufficient balance to pay itnew_options
SHALL be internally consistent, as verified byvalidate()
Postcondition -
asset_to_update
will have options matching those of new_options
struct asset_update_issuer_operation : public base_operation
{
struct fee_parameters_type {
uint64_t fee = 20 * GRAPHENE_BLOCKCHAIN_PRECISION;
};
asset fee;
account_id_type issuer;
asset_id_type asset_to_update;
account_id_type new_issuer;
extensions_type extensions;
account_id_type fee_payer()const { return issuer; }
void validate()const;
void get_required_owner_authorities( flat_set<account_id_type>& a )const
{ a.insert( issuer ); }
void get_required_active_authorities( flat_set<account_id_type>& a )const
{ }
};
Balance Claim¶
balance_claim_operation¶
Claim a balance in a balanc_object.
This operation is used to claim the balance in a given
balance_object
. If the balance object contains a vesting balance,total_claimed
must not exceedbalance_object::available
at the time of evaluation. If the object contains a non-vesting balance,total_claimed
must be the full balance of the object.
Bit collateral (market)¶
bit_collateral_operation¶
This operation can be used after a black swan to bid collateral for taking over part of the debt and the settlement_fund (see BSIP-0018).
struct bid_collateral_operation : public base_operation
{
struct fee_parameters_type { uint64_t fee = 20 * GRAPHENE_BLOCKCHAIN_PRECISION; };
asset fee;
account_id_type bidder;
asset additional_collateral;
asset debt_covered;
extensions_type extensions;
account_id_type fee_payer()const { return bidder; }
void validate()const;
};
Committee¶
committee_member_create_operation¶
Create a committee_member object, as a bid to hold a committee_member seat on the network.
Accounts which wish to become committee_members may use this operation to create a committee_member object which stakeholders may vote on to approve its position as a committee_member.
struct committee_member_create_operation : public base_operation
{
struct fee_parameters_type { uint64_t fee = 5000 * GRAPHENE_BLOCKCHAIN_PRECISION; };
asset fee;
/// The account which owns the committee_member. This account pays the fee for this operation.
account_id_type committee_member_account;
string url;
account_id_type fee_payer()const { return committee_member_account; }
void validate()const;
};
committee_member_update_global_parameters_operation¶
Used by committee_members to update the global parameters of the blockchain.
This operation allows the committee_members to update the global parameters on the blockchain. These control various tunable aspects of the chain, including block and maintenance intervals, maximum data sizes, the fees charged by the network, etc.
This operation may only be used in a proposed transaction, and a proposed transaction which contains this operation must have a review period specified in the current global parameters before it may be accepted.
struct committee_member_update_global_parameters_operation : public base_operation
{
struct fee_parameters_type { uint64_t fee = GRAPHENE_BLOCKCHAIN_PRECISION; };
asset fee;
chain_parameters new_parameters;
account_id_type fee_payer()const { return account_id_type(); }
void validate()const;
};
committee_member_update_operation¶
Update a committee_member object.
Currently the only field which can be updated is the url field.
struct committee_member_update_operation : public base_operation
{
struct fee_parameters_type { uint64_t fee = 20 * GRAPHENE_BLOCKCHAIN_PRECISION; };
asset fee;
/// The committee member to update.
committee_member_id_type committee_member;
/// The account which owns the committee_member. This account pays the fee for this operation.
account_id_type committee_member_account;
optional< string > new_url;
account_id_type fee_payer()const { return committee_member_account; }
void validate()const;
};
Custom (market)¶
custom_operation¶
provides a generic way to add higher level protocols on top of witness consensus
There is no validation for this operation other than that required auths are valid and a fee is paid that is appropriate for the data contained.
struct custom_operation : public base_operation
{
struct fee_parameters_type {
uint64_t fee = GRAPHENE_BLOCKCHAIN_PRECISION;
uint32_t price_per_kbyte = 10;
};
asset fee;
account_id_type payer;
flat_set<account_id_type> required_auths;
uint16_t id = 0;
vector<char> data;
account_id_type fee_payer()const { return payer; }
void validate()const;
share_type calculate_fee(const fee_parameters_type& k)const;
};
execute_bit_operation¶
Note
This is a virtual operation that is created while reviving a bitasset from collateral bids.
struct execute_bid_operation : public base_operation
{
struct fee_parameters_type {};
execute_bid_operation(){}
execute_bid_operation( account_id_type a, asset d, asset c )
: bidder(a), debt(d), collateral(c) {}
account_id_type bidder;
asset debt;
asset collateral;
asset fee;
account_id_type fee_payer()const { return bidder; }
void validate()const { FC_ASSERT( !"virtual operation" ); }
share_type calculate_fee(const fee_parameters_type& k)const { return 0; }
};
FBA¶
fba_distribute_operation¶
struct fba_distribute_operation : public base_operation
{
struct fee_parameters_type {};
asset fee; // always zero
account_id_type account_id;
fba_accumulator_id_type fba_id;
share_type amount;
account_id_type fee_payer()const { return account_id; }
void validate()const { FC_ASSERT( false ); }
share_type calculate_fee(const fee_parameters_type& k)const { return 0; }
};
Order (market)¶
call_order_update_operation¶
This operation can be used to add collateral, cover, and adjust the margin call price for a particular user.
For prediction markets the collateral and debt must always be equal.
This operation will fail if it would trigger a margin call that couldn’t be filled. If the margin call hits the call price limit then it will fail if the call price is above the settlement price.
Note
this operation can be used to force a market order using the collateral without requiring outside funds.
struct call_order_update_operation : public base_operation
{
struct options_type
{
optional<uint16_t> target_collateral_ratio;
};
struct fee_parameters_type { uint64_t fee = 20 * GRAPHENE_BLOCKCHAIN_PRECISION; };
asset fee;
account_id_type funding_account;
asset delta_collateral;
asset delta_debt;
typedef extension<options_type> extensions_type; // note: this will be jsonified to {...} but no longer [...]
extensions_type extensions;
account_id_type fee_payer()const { return funding_account; }
void validate()const;
};
fill_order_operation¶
Note
This is a virtual operation that is created while matching orders and emitted for the purpose of accurately tracking account history, accelerating a re-index
struct fill_order_operation : public base_operation
{
struct fee_parameters_type {};
fill_order_operation(){}
fill_order_operation( object_id_type o, account_id_type a, asset p, asset r, asset f, price fp, bool m )
:order_id(o),account_id(a),pays(p),receives(r),fee(f),fill_price(fp),is_maker(m) {}
object_id_type order_id;
account_id_type account_id;
asset pays;
asset receives;
asset fee; // paid by receiving account
price fill_price;
bool is_maker;
pair<asset_id_type,asset_id_type> get_market()const
{
return pays.asset_id < receives.asset_id ?
std::make_pair( pays.asset_id, receives.asset_id ) :
std::make_pair( receives.asset_id, pays.asset_id );
}
account_id_type fee_payer()const { return account_id; }
void validate()const { FC_ASSERT( !"virtual operation" ); }
share_type calculate_fee(const fee_parameters_type& k)const { return 0; }
};
limit_order_cancel_operation¶
Used to cancel an existing limit order. Both fee_pay_account and the account to receive the proceeds must be the same as order->seller.
Returns the amount actually refunded
struct limit_order_cancel_operation : public base_operation
{
struct fee_parameters_type { uint64_t fee = 0; };
asset fee;
limit_order_id_type order;
account_id_type fee_paying_account;
extensions_type extensions;
account_id_type fee_payer()const { return fee_paying_account; }
void validate()const;
};
limit_orders_create_operation¶
instructs the blockchain to attempt to sell one asset for another
The blockchain will attempt to sell
amount_to_sell.asset_id
for as muchmin_to_receive.asset_id
as possible. The fee will be paid by the seller’s account. Market fees will apply as specified by the issuer of both the selling asset and the receiving asset as a percentage of the amount exchanged.If either the selling asset or the receiving asset is white list restricted, the order will only be created if the seller is on the white list of the restricted asset type.
Market orders are matched in the order they are included in the block chain.
struct limit_order_create_operation : public base_operation
{
struct fee_parameters_type { uint64_t fee = 5 * GRAPHENE_BLOCKCHAIN_PRECISION; };
asset fee;
account_id_type seller;
asset amount_to_sell;
asset min_to_receive;
time_point_sec expiration = time_point_sec::maximum();
bool fill_or_kill = false;
extensions_type extensions;
pair<asset_id_type,asset_id_type> get_market()const
{
return amount_to_sell.asset_id < min_to_receive.asset_id ?
std::make_pair(amount_to_sell.asset_id, min_to_receive.asset_id) :
std::make_pair(min_to_receive.asset_id, amount_to_sell.asset_id);
}
account_id_type fee_payer()const { return seller; }
void validate()const;
price get_price()const { return amount_to_sell / min_to_receive; }
};
Transfer¶
blind_transfer_operation¶
Transfers from blind to blind.
There are two ways to transfer value while maintaining privacy:
account to account with amount kept secret
stealth transfers with amount sender/receiver kept secret
When doing account to account transfers, everyone with access to the memo key can see the amounts, but they will not have access to the funds.
When using stealth transfers the same key is used for control and reading the memo.
This operation is more expensive than a normal transfer and has a fee proportional to the size of the operation.
All assets in a blind transfer must be of the same type: fee.asset_id The fee_payer is the temp account and can be funded from the blinded values.
Using this operation you can transfer from an account and/or blinded balances to an account and/or blinded balances.
Stealth Transfers:
Assuming Receiver has key pair R,r and has shared public key R with Sender
Assuming Sender has key pair S,s
Generate one time key pair O,o as s.child(nonce) where nonce can be inferred from transaction
Calculate secret V = o*R
blinding_factor = sha256(V)
memo is encrypted via aes of `V `
owner = R.child(sha256(blinding_factor))
Sender gives Receiver output ID to complete the payment.
This process can also be used to send money to a cold wallet without having to pre-register any accounts.
Outputs are assigned the same IDs as the inputs until no more input IDs are available, in which case a the return value will be the first ID allocated for an output. Additional output IDs are allocated sequentially thereafter. If there are fewer outputs than inputs then the input IDs are freed and never used again.
struct blind_transfer_operation : public base_operation
{
struct fee_parameters_type {
uint64_t fee = 5*GRAPHENE_BLOCKCHAIN_PRECISION;
uint32_t price_per_output = 5*GRAPHENE_BLOCKCHAIN_PRECISION;
};
asset fee;
vector<blind_input> inputs;
vector<blind_output> outputs;
account_id_type fee_payer()const;
void validate()const;
share_type calculate_fee( const fee_parameters_type& k )const;
void get_required_authorities( vector<authority>& a )const
{
for( const auto& in : inputs )
a.push_back( in.owner );
}
};
override_transfer_operation¶
Allows the issuer of an asset to transfer an asset from any account to any account if they have override_authority.
Precondition
amount.asset_id->issuer == issuer
issuer != from because this is pointless, use a normal transfer operation
struct override_transfer_operation : public base_operation
{
struct fee_parameters_type {
uint64_t fee = 20 * GRAPHENE_BLOCKCHAIN_PRECISION;
uint32_t price_per_kbyte = 10; /// only required for large memos.
};
asset fee;
account_id_type issuer;
/// Account to transfer asset from
account_id_type from;
/// Account to transfer asset to
account_id_type to;
/// The amount of asset to transfer from @ref from to @ref to
asset amount;
/// User provided data encrypted to the memo key of the "to" account
optional<memo_data> memo;
extensions_type extensions;
account_id_type fee_payer()const { return issuer; }
void validate()const;
share_type calculate_fee(const fee_parameters_type& k)const;
};
transfer_from_blind_operation¶
Converts blinded/stealth balance to a public account balance.
struct transfer_from_blind_operation : public base_operation
{
struct fee_parameters_type {
uint64_t fee = 5*GRAPHENE_BLOCKCHAIN_PRECISION; ///< the cost to register the cheapest non-free account
};
asset fee;
asset amount;
account_id_type to;
blind_factor_type blinding_factor;
vector<blind_input> inputs;
account_id_type fee_payer()const { return GRAPHENE_TEMP_ACCOUNT; }
void validate()const;
void get_required_authorities( vector<authority>& a )const
{
for( const auto& in : inputs )
a.push_back( in.owner );
}
};
transfer_operation¶
Transfers an amount of one asset from one account to another.
Fees are paid by the “from” account
Precondition
amount.amount > 0
fee.amount >= 0
from != to
Postcondition
from account’s balance will be reduced by fee and amount
to account’s balance will be increased by amount
Returns
n/a
struct transfer_operation : public base_operation
{
struct fee_parameters_type {
uint64_t fee = 20 * GRAPHENE_BLOCKCHAIN_PRECISION;
uint32_t price_per_kbyte = 10 * GRAPHENE_BLOCKCHAIN_PRECISION; /// only required for large memos.
};
asset fee;
/// Account to transfer asset from
account_id_type from;
/// Account to transfer asset to
account_id_type to;
/// The amount of asset to transfer from @ref from to @ref to
asset amount;
/// User provided data encrypted to the memo key of the "to" account
optional<memo_data> memo;
extensions_type extensions;
account_id_type fee_payer()const { return from; }
void validate()const;
share_type calculate_fee(const fee_parameters_type& k)const;
};
transfer_to_blind_operation¶
Converts public account balance to a blinded or stealth balance.
struct transfer_to_blind_operation : public base_operation
{
struct fee_parameters_type {
uint64_t fee = 5*GRAPHENE_BLOCKCHAIN_PRECISION;
uint32_t price_per_output = 5*GRAPHENE_BLOCKCHAIN_PRECISION;
};
asset fee;
asset amount;
account_id_type from;
blind_factor_type blinding_factor;
vector<blind_output> outputs;
account_id_type fee_payer()const { return from; }
void validate()const;
share_type calculate_fee(const fee_parameters_type& )const;
};
Proposal¶
proposal_create_operation¶
The
proposal_create_operation
creates a transaction proposal, for use in multi-sig scenariosCreates a transaction proposal. The operations which compose the transaction are listed in order in
proposed_ops
, andexpiration_time
specifies the time by which the proposal must be accepted or it will fail permanently. The expiration_time cannot be farther in the future than the maximum expiration time set in the global properties object.Constructs a
proposal_create_operation
suitable for committee proposals, with expiration time and review period set
appropriately. No
proposed_ops
are added. When used to create a proposal to change chain parameters, this method expects to receive the currently effective parameters, not the proposed parameters. (The proposed parameters will go inproposed_ops
, andproposed_ops
is untouched by this function.)
struct proposal_create_operation : public base_operation
{
struct fee_parameters_type {
uint64_t fee = 20 * GRAPHENE_BLOCKCHAIN_PRECISION;
uint32_t price_per_kbyte = 10;
};
asset fee;
account_id_type fee_paying_account;
vector<op_wrapper> proposed_ops;
time_point_sec expiration_time;
optional<uint32_t> review_period_seconds;
extensions_type extensions;
/**
* Constructs a proposal_create_operation suitable for committee
* proposals, with expiration time and review period set
* appropriately. No proposed_ops are added. When used to
* create a proposal to change chain parameters, this method
* expects to receive the currently effective parameters, not
* the proposed parameters. (The proposed parameters will go
* in proposed_ops, and proposed_ops is untouched by this
* function.)
*/
static proposal_create_operation committee_proposal(const chain_parameters& param, fc::time_point_sec head_block_time );
account_id_type fee_payer()const { return fee_paying_account; }
void validate()const;
share_type calculate_fee(const fee_parameters_type& k)const;
};
proposal_delete_operation¶
The
proposal_delete_operation
deletes an existing transaction proposalThis operation allows the early veto of a proposed transaction. It may be used by any account which is a required authority on the proposed transaction, when that account’s holder feels the proposal is ill-advised and he decides he will never approve of it and wishes to put an end to all discussion of the issue. Because he is a required authority, he could simply refuse to add his approval, but this would leave the topic open for debate until the proposal expires. Using this operation, he can prevent any further breath from being wasted on such an absurd proposal.
struct proposal_delete_operation : public base_operation
{
struct fee_parameters_type { uint64_t fee = GRAPHENE_BLOCKCHAIN_PRECISION; };
account_id_type fee_paying_account;
bool using_owner_authority = false;
asset fee;
proposal_id_type proposal;
extensions_type extensions;
account_id_type fee_payer()const { return fee_paying_account; }
void validate()const;
};
proposal_update_operation¶
The
proposal_update_operation
updates an existing transaction proposalThis operation allows accounts to add or revoke approval of a proposed transaction. Signatures sufficient to satisfy the authority of each account in approvals are required on the transaction containing this operation.
If an account with a multi-signature authority is listed in
approvals_to_add
orapprovals_to_remove
, either all required signatures to satisfy that account’s authority must be provided in the transaction containing this operation, or a secondary proposal must be created which contains this operation.
Note
If the proposal requires only an account’s active authority, the account must not update adding its owner authority’s approval. This is considered an error. An owner approval may only be added if the proposal requires the owner’s authority.
If an account’s owner and active authority are both required, only the owner authority may approve. An attempt to add or remove active authority approval to such a proposal will fail.
struct proposal_update_operation : public base_operation
{
struct fee_parameters_type {
uint64_t fee = 20 * GRAPHENE_BLOCKCHAIN_PRECISION;
uint32_t price_per_kbyte = 10;
};
account_id_type fee_paying_account;
asset fee;
proposal_id_type proposal;
flat_set<account_id_type> active_approvals_to_add;
flat_set<account_id_type> active_approvals_to_remove;
flat_set<account_id_type> owner_approvals_to_add;
flat_set<account_id_type> owner_approvals_to_remove;
flat_set<public_key_type> key_approvals_to_add;
flat_set<public_key_type> key_approvals_to_remove;
extensions_type extensions;
account_id_type fee_payer()const { return fee_paying_account; }
void validate()const;
share_type calculate_fee(const fee_parameters_type& k)const;
void get_required_authorities( vector<authority>& )const;
void get_required_active_authorities( flat_set<account_id_type>& )const;
void get_required_owner_authorities( flat_set<account_id_type>& )const;
};
Vesting Balance¶
vesting_balance_create_operation¶
Create a vesting balance.
The chain allows a user to create a vesting balance. Normally, vesting balances are created automatically as part of cashback and worker operations. This operation allows vesting balances to be created manually as well.
Manual creation of vesting balances can be used by a stakeholder to publicly demonstrate that they are committed to the chain. It can also be used as a building block to create transactions that function like public debt. Finally, it is useful for testing vesting balance functionality.
Returns
ID of newly created vesting_balance_object
struct vesting_balance_create_operation : public base_operation
{
struct fee_parameters_type { uint64_t fee = GRAPHENE_BLOCKCHAIN_PRECISION; };
asset fee;
account_id_type creator; ///< Who provides funds initially
account_id_type owner; ///< Who is able to withdraw the balance
asset amount;
vesting_policy_initializer policy;
account_id_type fee_payer()const { return creator; }
void validate()const
{
FC_ASSERT( fee.amount >= 0 );
FC_ASSERT( amount.amount > 0 );
}
};
vesting_balance_withdraw_operation¶
Withdraw from a vesting balance.
Withdrawal from a not-completely-mature vesting balance will result in paying fees.
Returns
nothing
struct vesting_balance_withdraw_operation : public base_operation
{
struct fee_parameters_type { uint64_t fee = 20*GRAPHENE_BLOCKCHAIN_PRECISION; };
asset fee;
vesting_balance_id_type vesting_balance;
account_id_type owner; ///< Must be vesting_balance.owner
asset amount;
account_id_type fee_payer()const { return owner; }
void validate()const
{
FC_ASSERT( fee.amount >= 0 );
FC_ASSERT( amount.amount > 0 );
}
};
Withdraw¶
withdraw_permission_claim_operation¶
Withdraw from an account which has published a withdrawal permission
This operation is used to withdraw from an account which has authorized such a withdrawal. It may be executed at most once per withdrawal period for the given permission. On execution,
amount_to_withdraw
is transferred fromwithdraw_from_account
towithdraw_to_account
, assumingamount_to_withdraw
is within the withdrawal limit. The withdrawal permission will be updated to note that the withdrawal for the current period has occurred, and further withdrawals will not be permitted until the next withdrawal period, assuming the permission has not expired. This operation may be executed at any time within the current withdrawal period.Fee is paid by withdraw_to_accoun`t, which is required to authorize this operation
struct withdraw_permission_claim_operation : public base_operation
{
struct fee_parameters_type {
uint64_t fee = 20*GRAPHENE_BLOCKCHAIN_PRECISION;
uint32_t price_per_kbyte = 10;
};
/// Paid by withdraw_to_account
asset fee;
/// ID of the permission authorizing this withdrawal
withdraw_permission_id_type withdraw_permission;
/// Must match withdraw_permission->withdraw_from_account
account_id_type withdraw_from_account;
/// Must match withdraw_permision->authorized_account
account_id_type withdraw_to_account;
/// Amount to withdraw. Must not exceed withdraw_permission->withdrawal_limit
asset amount_to_withdraw;
/// Memo for withdraw_from_account. Should generally be encrypted with withdraw_from_account->memo_key
optional<memo_data> memo;
account_id_type fee_payer()const { return withdraw_to_account; }
void validate()const;
share_type calculate_fee(const fee_parameters_type& k)const;
};
withdraw_permission_create_operation¶
Create a new withdrawal permission
This operation creates a withdrawal permission, which allows some authorized account to withdraw from an authorizing account. This operation is primarily useful for scheduling recurring payments.
Withdrawal permissions define withdrawal periods, which is a span of time during which the authorized account may make a withdrawal. Any number of withdrawals may be made so long as the total amount withdrawn per period does not exceed the limit for any given period.
Withdrawal permissions authorize only a specific pairing, i.e. a permission only authorizes one specified authorized account to withdraw from one specified authorizing account. Withdrawals are limited and may not exceed the withdrawal limit. The withdrawal must be made in the same asset as the limit; attempts with withdraw any other asset type will be rejected.
The fee for this operation is paid by
withdraw_from_account
, and this account is required to authorize this operation.
struct withdraw_permission_create_operation : public base_operation
{
struct fee_parameters_type { uint64_t fee = GRAPHENE_BLOCKCHAIN_PRECISION; };
asset fee;
/// The account authorizing withdrawals from its balances
account_id_type withdraw_from_account;
/// The account authorized to make withdrawals from withdraw_from_account
account_id_type authorized_account;
/// The maximum amount authorized_account is allowed to withdraw in a given withdrawal period
asset withdrawal_limit;
/// Length of the withdrawal period in seconds
uint32_t withdrawal_period_sec = 0;
/// The number of withdrawal periods this permission is valid for
uint32_t periods_until_expiration = 0;
/// Time at which the first withdrawal period begins; must be in the future
time_point_sec period_start_time;
account_id_type fee_payer()const { return withdraw_from_account; }
void validate()const;
};
withdraw_permission_delete_operation¶
Delete an existing withdrawal permission
This operation cancels a withdrawal permission, thus preventing any future withdrawals using that permission.
Fee is paid by
withdraw_from_account
, which is required to authorize this operation
struct withdraw_permission_delete_operation : public base_operation
{
struct fee_parameters_type { uint64_t fee = 0; };
asset fee;
/// Must match withdrawal_permission->withdraw_from_account. This account pays the fee.
account_id_type withdraw_from_account;
/// The account previously authorized to make withdrawals. Must match withdrawal_permission->authorized_account
account_id_type authorized_account;
/// ID of the permission to be revoked.
withdraw_permission_id_type withdrawal_permission;
account_id_type fee_payer()const { return withdraw_from_account; }
void validate()const;
};
withdraw_permission_update_operation¶
Update an existing withdraw permission
This operation is used to update the settings for an existing withdrawal permission. The accounts to withdraw to and from may never be updated. The fields which may be updated are the withdrawal limit (both amount and asset type may be updated), the withdrawal period length, the remaining number of periods until expiration, and the starting time of the new period.
Fee is paid by
withdraw_from_account
, which is required to authorize this operation
struct withdraw_permission_update_operation : public base_operation
{
struct fee_parameters_type { uint64_t fee = GRAPHENE_BLOCKCHAIN_PRECISION; };
asset fee;
/// This account pays the fee. Must match permission_to_update->withdraw_from_account
account_id_type withdraw_from_account;
/// The account authorized to make withdrawals. Must match permission_to_update->authorized_account
account_id_type authorized_account;
/// ID of the permission which is being updated
withdraw_permission_id_type permission_to_update;
/// New maximum amount the withdrawer is allowed to charge per withdrawal period
asset withdrawal_limit;
/// New length of the period between withdrawals
uint32_t withdrawal_period_sec = 0;
/// New beginning of the next withdrawal period; must be in the future
time_point_sec period_start_time;
/// The new number of withdrawal periods for which this permission will be valid
uint32_t periods_until_expiration = 0;
account_id_type fee_payer()const { return withdraw_from_account; }
void validate()const;
};
Witness¶
witness_create_operation¶
Create a witness object, as a bid to hold a witness position on the network.
Accounts which wish to become witnesses may use this operation to create a witness object which stakeholders may vote on to approve its position as a witness.
struct witness_create_operation : public base_operation
{
struct fee_parameters_type { uint64_t fee = 5000 * GRAPHENE_BLOCKCHAIN_PRECISION; };
asset fee;
/// The account which owns the witness. This account pays the fee for this operation.
account_id_type witness_account;
string url;
public_key_type block_signing_key;
account_id_type fee_payer()const { return witness_account; }
void validate()const;
};
witness_update_operation¶
Update a witness object’s URL and block signing key.
struct witness_update_operation : public base_operation
{
struct fee_parameters_type
{
share_type fee = 20 * GRAPHENE_BLOCKCHAIN_PRECISION;
};
asset fee;
/// The witness object to update.
witness_id_type witness;
/// The account which owns the witness. This account pays the fee for this operation.
account_id_type witness_account;
/// The new URL.
optional< string > new_url;
/// The new block signing key.
optional< public_key_type > new_signing_key;
account_id_type fee_payer()const { return witness_account; }
void validate()const;
};
Worker¶
worker_create_operation¶
Create a new worker object.
struct worker_create_operation : public base_operation
{
struct fee_parameters_type { uint64_t fee = 5000*GRAPHENE_BLOCKCHAIN_PRECISION; };
asset fee;
account_id_type owner;
time_point_sec work_begin_date;
time_point_sec work_end_date;
share_type daily_pay;
string name;
string url;
/// This should be set to the initializer appropriate for the type of worker to be created.
worker_initializer initializer;
account_id_type fee_payer()const { return owner; }
void
};