HF·18: cli_wallet interface changes - GolosChain/golos GitHub Wiki

This page contains information about API changes implemented in the client application cli_wallet to manually construct transactions.

cli_wallet is a client application that comes together with a daemon. This application provides a lot of functionality. It is the main tool for delegates which is also well used by everyone on the exchange. It manages client balances by doing operations, such as sending money, creating posts, voting and so on.

A purpose of the cli_wallet changes is to create a convenient tool for delegates to operate with the daemon through minimal manipulations.

In previous blockchain versions a transaction was formed automatically with including JS-, Python- and GO-libraries. On the one hand, it was convenient for а user in terms of quick proposal creation. On the other hand, there was a fixed command set in cli_wallet, that not allowed to manipulate with parameters while a transaction was building. In HF·18 due to implemented changes in cli_wallet this deficiency has been eliminated. In cli_wallet has been created a constructor which allows to manually build a transaction of any form. It allows the user to add, change and edit operations in the transaction.

All of cli_wallet changes have been done in accordance with proposals of the task №542.

• create_account_delegated
• create_account_with_keys_delegated
• delegate_vesting_shares
• begin_builder_transaction
• get_prototype_operation
• add_operation_to_builder_transaction
• add_operation_copy_to_builder_transaction
• replace_operation_in_builder_transaction
• preview_builder_transaction
• sign_builder_transaction
• propose_builder_transaction
• remove_builder_transaction
• approve_proposal
• get_proposed_transactions

• create_account
• create_account_with_keys

Following methods implement a new mechanism in cli_wallet application to construct transactions. This mechanism, unlike that one from previous blockchain versions, allows the delegates to form transactions with any operation set, and transfer the operations between transactions. Besides of this, it allows also to construct several transactions in parallel and identify them individually. The implementation mainly consisted in adding new methods to cli_wallet application. Only two methods (create_account and create_account_with_keys) from entire previous list were slightly modified.

This method generates public keys named as owner, active, posting and memo for a new account. Сreated account is controlled by its wallet. For creating the new account is always charged commission fee that is paid by an account creator. Сommission fee, as well as other blockchain information, can be found in output of the info wallet command, that looks like “account_creation_fee”:”X.000 GOLOS”.

Commission fee can not be less than the value of account_creation_fee which is determined by delegates voting. That fee is debited from creator’s wallet and added to wallet of the new account. This payment is made in Golos and credited to VESTS balance of new account. It is to create a necessary basic balance for existing the new account in system. The fee parameter is implemented in order to have got an initial basic balance.

To create a post the user have to also withdraw commission from her/his wallet. A number of creating posts per a certain time is limited by bandwidth which depends on the user's balance. Therefore, the user can not create comments or take part in voting too often because of the bandwidth does not allow this to happen.

The creator can delegate a piece of VESTS to the new account. In this case the piece of VESTS is also debited from creator's wallet and credited to VESTS balance of the new account. However, unlike the commission fee, delegated VESTS can be returned back to creator's wallet after a time set by delegates voting.

Procedure is called with the following arguments:

annotated_signed_transaction create_account_delegated(
	string creator,
	asset steem_fee, 
	asset delegated_vests, 
	string new_account_name,
	string json_meta,
	bool broadcast
);

where:
creator — an account which creates the new account;
steem_fee — commissions charged for creating the new account, which is debited from Golos balance of the creator and credited to VESTS balance of the new account. Commission amount is never returned back to the creator's wallet;
delegated_vests — commissions charged for creating the new account, which is debited from VESTS balance of the creator and credited to VESTS balance of the new account. Unlike commission fee, delegated amount can be returned back to creator's wallet after a time set by delegates voting;
new_account_name — a name of the new account;
json_meta — JSON metadata related to the new account;
broadcast — 'true' means, a transaction is passed to the demon; 'false' means doing a basic checking with passing a signed transaction to console.

This method is used by faucets to create new accounts for other users which have to provide their appropriate keys. Resulting account can not be checked by this wallet. For creating a new account is charged commission fee that is paid by an account creator. Commission fee can be found in output of calling the info wallet command. These accounts are created through combination of GOLOS and delegated GP. The method takes the following form:

annotated_signed_transaction create_account_with_keys_delegated(
	string creator,
	asset steem_fee,
	asset delegated_vests,
	string newname,
	string json_meta,
	public_key_type owner,
	public_key_type active,
	public_key_type posting,
	public_key_type memo,
	bool broadcast
) const;

where:
creator — an account which creates the new account;
steem_fee — commissions charged for creating the new account, which is debited from Golos balance of the creator and credited to VESTS balance of the new account. Commission amount can not be less than the value of account_creation_fee which is determined by delegates voting. Commission fee is never returned back to the creator's wallet;
delegated_vests — commissions charged for creating the new account, which is debited from VESTS balance of the creator and credited to VESTS balance of the new account. Unlike commission fee, delegated amount can be returned back to creator's wallet after a time set by delegates voting;
newname — a name of the new account;
json_meta — JSON metadata related to the new account;
owner — public owner key of the new account;
active — public active key of the new account;
posting — public posting key of the new account;
memo — public memo key of the new account;
broadcast — ‘true’, if the transaction to be broadcasted.

This method delegates VESTS from one account to another. It takes the following form:

annotated_signed_transaction delegate_vesting_shares(
	string delegator,
	string delegatee,
	asset vesting_shares,
	bool broadcast
);

where:
delegator — a name of account which delegates VESTS;
delegatee — a name of account which receives VESTS;
vesting_shares — amount of VESTS to delegate;
broadcast — ‘true’ in case the transaction to be broadcasted. .

This method returns an unique number of created transaction builder. It returns unique number ‘handle’ which initially takes ‘zero’ value and then increments by ‘one’ per every calling the method. Form of this method is:

transaction_handle_type begin_builder_transaction();

No any parameters are required.

The method is used to get and fill a template for an operation to be created through the another method add_operation_to_builder_transaction. It returns an uninitialized object representing a given sequence of operations.

Any operation can be added to the object by calling add_operation_to_builder_transaction(). Before calling the method it needs to know what the JSON form of the operation looks like. And only after getting appropriate template it can be filled. The method takes the following form:

operation get_prototype_operation(
	string operation_type
);

where:
operation_type — a type of operation to be returned. The operation should be defined in steem/chain/operations.hpp.

This method is used to add an operation to transaction builder. It takes the following form:

void add_operation_to_builder_transaction(
	transaction_handle_type handle,
	const operation& op
);

where:
handle — unique constructor’s number;
op — operation to be added.

This method is used to copy an operation from one transaction builder to another. The transaction builder is identified by a handler returned by the method begin_builder_transaction(). The method takes the form:

void add_operation_copy_to_builder_transaction(
	transaction_handle_type src_handle,
	transaction_handle_type dst_handle,
	uint32_t op_index
);

where:
src_handle — unique constructor’s number, from where copied;
dst_handle — unique constructor’s number, where copied;
op_index — а number of operation to be copied.

This method is used to replace the operation under index op_index in transaction builder to the op operation.

void replace_operation_in_builder_transaction(
	transaction_handle_type handle,
	unsigned op_index,
	const operation& op
);

where:
handle — unique constructor’s number;
op_index — number of operation in transaction builder which is replaced;
op — operation to be replaced.

This method is used to obtain a transaction builder from the whole list of transaction builders by using its identificator. It takes the following form:

transaction preview_builder_transaction(
	transaction_handle_type handle
);

where:
handle — unique constructor’s number to be obtained.

This method is used to sign all transactions in builder_transaction.

signed_transaction sign_builder_transaction(
	transaction_handle_type handle,
	bool broadcast
);

where:
handle — unique constructor’s number;
broadcast — ‘true’, if the signed transactions to be passed to the demon.

This method is used to create a builder for proposed transaction. The method takes the following form:

signed_transaction propose_builder_transaction(
	transaction_handle_type handle,
	std::string author,
	std::string title,
	std::string memo,
	time_point_sec expiration = time_point::now() + fc::minutes(1),
	time_point_sec review_period_time = time_point::min(),
	bool broadcast
);

where:
handle — unique number of transaction builder;
author — author of the proposal;
title — transaction name;
memo — memo data;
expiration — time, after which the transaction may not be approved;
review_period_time — time taken to receive signatures;
broadcast — ‘true’, if the transaction to be passed to the demon.

This method identifies builder_transaction and removes it. The method takes the following form:

void remove_builder_transaction(
	transaction_handle_type handle
);

where:
handle — unique number of transaction builder. It's value decrements by 'one' per every method call.

This method validates and signs a proposed transaction. It returns a signed version of the transaction.

Since to put a signature for a proposal there are four types of keys (owner, active, posting and memo) are used, it is necessary to count votes for each type separately. In approve_proposal has been implemented special struct parameter — delta, where locate actual voting data for each type of keys. The struct looks like as follows:

struct approval_delta {
	vector<string> active_approvals_to_add; // list of accounts which have to put the «active»  
						// signatures  to approve the proposal
	vector<string> active_approvals_to_remove; // list of accounts whose the «active» signatures had  
						// to be removed to approve the proposal
	vector<string> owner_approvals_to_add; // list of accounts which have to put the «owner»   
						// signatures to approve the proposal
	vector<string> owner_approvals_to_remove; // list of accounts whose the «owner» signatures had  
						// to be removed to approve the proposal
	vector<string> posting_approvals_to_add; // list of accounts which have to put the «posting»  
						// signature  to approve the proposal
	vector<string> posting_approvals_to_remove; // list of accounts whose the «posting» signatures had 
						// to be removed to approve the proposal
	vector<string> key_approvals_to_add; // list of «public» signatures which have to be put  
						// to approve the proposal
	vector<string> key_approvals_to_remove; // list of «public» signatures which had to be removed  
						// to approve the proposal
}

The method takes the following form:

signed_transaction approve_proposal(
	const std::string& author,
	const std::string& title,
	const approval_delta& delta,
	bool broadcast
);

where:
author — author of the proposed transaction;
title — title of th transaction which needs to be signed;
delta — lists of signatures which have to be put to approve the proposal. In JSON the lists can be empty;
broadcast — ‘true’, if the transaction to be passed to the demon; ‘false’, if the signed transaction to be passed to console.

This method is used to obtain information about all proposed transactions related to the same account. Specifying initial transaction number and transaction limit, it allows to obtain information about one or several transactions. The method takes the following form:

std::vector<database_api::proposal_api_object> get_proposed_transactions(
	std::string account,
	uint32_t from,
	uint32_t limit
);

where:
account — account whose transaction information is obtained;
from — initial transaction number;
limit — transaction list restriction.

Тhe following methods are not new in cli_wallet and have been applied already in previous blockchain versions. They are just slightly modified.

New parameter fee was added to the following procedure. The method returns created account. Currently, its parameters and signature look like as follows:

annotated_signed_transaction create_account(
	string creator,
	string new_account_name,
	string json_meta,
	asset fee,
	bool broadcast
);

where:
creator — an account which creates the new account;
new_account_name — a name of the new account;
json_meta — JSON metadata related to the new account;
fee — commissions charged for creating the new account, which is debited from Golos balance of the creator and credited to VESTS balance of the new account. Commission amount can not be less than the value of account_creation_fee which is determined by delegates voting;
broadcast — ‘true’, if the transaction to be passed to the demon; ‘false’, if the signed transaction to be passed to console.

New parameter fee was added to the following procedure. Currently, its parameters and signature look like as follows:

annotated_signed_transaction create_account_with_keys(
	string creator,
	string newname,
	string json_meta,
	asset fee,
	public_key_type owner,
	public_key_type active,
	public_key_type posting,
	public_key_type memo,
	bool broadcast 
) const;

where:
creator — an account which creates the new account;
newname — a name of a new account;
json_meta — JSON metadata of the new account;
fee — commissions charged for creating the new account, which is debited from Golos balance of the creator and credited to VESTS balance of the new account. Commission amount can not be less than the value of account_creation_fee which is determined by delegates voting;
owner — public owner key of the new account;
active — public active key of the new account;
posting — public posting key of the new account;
memo — public memo key of the new account;
broadcast — ‘true’, if the transaction to be broadcasted.

Procedure for generating, singing and broadcasting a transaction in free form includes the following general actions:

1. Creating an instance of the transaction builder. It is done through API call begin_builder_transaction. The method will return HANDLE — unique number of the created constructor. The constructor will be available via the HANDLE value. It allows to create several constructors.

2. Adding arbitrary operation types. This action is performed by the API call add_operation_to_builder_transaction $HANDLE [opID, {operation}]. The constructor is used to create transaction and manipulate with its operations in manual mode. The operations are selected by their opID identifiers. It allows to construct several transactions in parallel — one transaction per one constructor. The opID of the operation can be obtained with the method get_prototype_operation <operation-type>.

3. Adding the required amount of fees. Each operation needs to be payed. At this step the creator has a choice between either defining each fee for created operations individually, or setting the fee for each operation automatically to the chosen asset by calling the method set_fees_on_builder_transaction. This method has not been modified and is used as usual.

4. Signing and broadcasting the proposed transaction. At the end step it needs just to call the method sign_builder_transaction $HANDLE true. It will automatically sign and broadcast the proposed transaction.

Because of the changes in cli_wallet the output of get_ops_in_block has been changed too. Its previous output value looked like:

vector<operation_api_object> get_ops_in_block(
	uint32_t <blockquote></blockquote>_num,
	bool only_virtual = true
);

At now it looks like as follows:

vector<golos::plugins::operation_history::applied_operation> get_ops_in_block(
	uint32_t block_num,
	bool only_virtual = true
);