Frequently Asked Questions (FAQ)¶
General¶
What is the standard Bitshares address structure and format?
What is the maximum bitshares block size? - Configurable by chain parameters
How is time addressed in the blockchain? Is NTP used or some other protocol?
How is accounting addressed in Bitshares? Is it a Nxt style accounting model or like Bitcoin’s UTXO
What is the average size in Bytes of a Bitshares transaction?
What parameters in a configuration file in a data directory? - (rel:config.ini)
Are there any support information for python and javascript developers?
Protocol
Does the protocol provide mechanisms for overlay protocols to interact such as OR_RETURN?
Is this done via a gossip protocol or through a federate relay?
Data Structures
Public Key System
Scripting Language
System Components¶
What types of Objects and elements are available in BitShares-Core?
configuration examples and support files
config.ini (Node Configuration File )
apiConfig.js (BitShares Public Node information)
api-access.json (API Access restriction)
saltpass.py (obtain hash and salt values from a password)
Accounts¶
Where can I read about the BitShares Account information?
Include: Membership, Fees, Permissions, Public Key and Private key, Muiti-Signature, Voting, Referral Program, and Vesting Balances
Install options¶
Which development environment would be possible to install BitShares-Core?
Use Ubuntu Linux
Use OS X
Use Windows
APIs¶
What’s API Restrictions? How to use? - (rel:api-access.json)
How do I get the network_add_nodes command to work? Why is it so complicated?
Is there a way to access methods which require login over HTTP?
Is there a way to allow external program to drive cli_wallet via websocket, JSONRPC, or HTTP?
Is there a way to generate help with parameter names and method descriptions?
The answer to the previous question was really confusing. Can you make it clearer?
Where can I find a simple Python script saltpass.py to obtain hash and salt values from a password? - (rel: saltpass.py)
Where Can I find BitShares Public Full Node information? (apiconfig)
Transfer / Transactions¶
CLI Wallet Questions¶
Witness Questions¶
Assets - FAQ¶
Can I change x after creation of the asset¶
The following parameters can be changed after creation:
Issuer
- UIA-Options:
Max Supply
Market Fee
Permissions (disable only/nor re-enable)
Flags (if permissions allow it)
Core exchange rate
White/Black Listing
Description
- MPG-Options:
Feed Life Time
Minimum Feeds
Force Settlement Offset/Delay/Volume
Things that cannot be changes:
Symbol
Precision
A guide can be found here.
Can I change the issuer?¶
The current issue of an asset may transfer ownership of the asset to someone else by changing the issuer in the asset’s settings.
What about Parent and Child assets?¶
A parent/child relation ship for assets can be represented by the name of the symbol, e.g.:
PARENT.child
can only be created by the issuer of PARENT
and no one else.
What happens to the asset creation fee?¶
50% of the asset creation fee are used to pre-fill the assets fee pool. From the other 50%, 20% go to the network and 80% go to the referral program. This means, that if you are a life-time member, you get back 40% of the asset creation fee after the vesting period (currently 90 days).
Fee Pool¶
What is Fee Pool Draining?¶
If an order is created and paid in a non-BTS asset, the fee is implicitly exchange into BTS to pay the network fee. However, if the order is canceled, 90% of the fee will be returned as BTS. The result is, that if the core exchange rate is lower than the highest bid, people can simply buy your token from the market, and exchange them implicitly with the fee pool by creating and canceling an order. This will deplete the fee pool and leave the issuer with his tokens at a slight loss (depending on the offset of the core exchange rate). For this reason, we recommend to use a core exchange that is slightly higher than the market price of your asset. As a consequence, paying fees in BTS should always be cheaper.
What is the fee pool all about?¶
The fee pool allows participants in the network to deal with assets and pay for the transaction fees without the need to hold BTS. Any transaction fee can be paid by paying any asset that has a core exchange rate (i.e. a price) at which the asset can be exchange implicitly into BTS to cover the network fee. If the asset’s fee pool is funded, the fees can be payed in the native UIA instead of BTS.
Note
The core exchange rate at which a fee can be exchanged into BTS may differ from the actual market valuation of the asset. A user, thus, may pay a premium or spare funds by paying in BTS.
Warning
Make sure your core exchange rate is higher than the lowest ask, otherwise, people will buy your token from the market and drain your fee pool via implicit abitrage.
It is the task of the issuer to keep the fee pool funded and the core exchange rate updated unless he wants the owner of his asset to be required to hold BTS for the fee.
What to do if the fee pool is empty?¶
Open up the issuer’s account, click the assets tab and open up the dialog to change the asset. There will be a fee pool tab that allows you to fund the fee pool and claim the accumulated fees!
Market Fees¶
What are Asset Flags and Permissions?¶
When an asset is creatd, the issuer can set any combination of flags/permissions. Flags are set in stone unless there is permission to edit. Once a permission to edit is revoked, flags are permanent, and can never be modified again.
What are the Flags?¶
charge_market_fee
: an issuer-specified percentage of all market trades in this asset is paid to the issuerwhite_list
: accounts must be white-listed in order to hold this assetoverride_authority
: issuer may transfer asset back to himselftransfer_restricted
: require the issuer to be one party to every transferdisable_force_settle
: disable force settlingglobal_settle
: (only for bitassets) allows bitasset issuer to force a global settling - this may be set in permissions, but should not be set as flag unless, for instance, a prediction market has to be resolved. If this flag has been enabled, no further shares can be borrowed!disable_confidential
: allow the asset to be used with confidential transactionswitness_fed_asset
: allow the asset to be fed by witnessescommittee_fed_asset
: allow the asset to be fed by the committee
What are the Permissions?¶
Enable market fee
Require holders to be white-listed
Issuer may transfer asset back to himself
Issuer must approve all transfers
Disable confidential transactions
What happens if I enable Market fees?¶
If Market Fees of a UIA are turned on, fees have to be payed for each market transaction. This means, that market fees only apply to filled orders!
The percentage of market fees that are applied can be defined and changed by the issuer and any fee generated that way will be accumulated for each asset only to be claimed by the issuer.
If the Market Fee is set to 1%, the issuer will earn 1% of market volume as profit. These profits are accumulated for each UIA and can be withdrawn by the issuer.
What if two different market fees are involved in a trade?¶
Suppose, I set the market fee for MyUIA market at 0.1%. and the market fee for YourUIA market at 0.3%.
In BitShares, You pay the fee upon receiving an asset. Hence, one side will pay 0.3% the other will pay 0.1%.
Market Pegged Assets¶
Can I use the same flags/permissions as for UIAs?¶
Yes!
What are market-pegged-asset-specific parameters?¶
feed_lifetime_sec
: The lifetime of a feed. After this time (in seconds) a feed is no longer considered valid.minimum_feeds
: The number of feeds required for a market to become (and stay) active.force_settlement_delay_sec
: The delay between requesting a settlement and actual execution of settlement (in seconds)force_settlement_offset_percent
: A percentage offset from the price feed for settlement (100% = 10000)maximum_force_settlement_volume
: Maximum percentage of the supply that can be settled per day (100% = 10000)short_backing_asset
: The asset that has to be used to back this asset (when borrowing)
CLI Wallet - FAQ¶
How can I close the CLI client in a clean way?¶
In Windows closing the whole window produces a nasty exception. In Windows you can try ctrl-d which stops the process but stil produces a nasty exception.
Why does the CLI client crash immediately when I try to run it for the first time?¶
The CLI client is unable to run on its own, i.e. without being connected to the witness node (via a web socket connection). So to successfully run the CLI client you need to do this:
make sure you have this entry uncommented in the witness_node_data_dir/config.ini file rpc-endpoint = 127.0.0.1:8090
before you start the CLI client, you need to start the witness node (and wait a while till it’s up and running)
Note
Find more “How to” guide in a Tutorials section.
Witness - FAQ¶
How can I close the witness node in a clean way?¶
In windows use ctrl-c
.
How do I check whether the witness node is already synceed?¶
Run the info
command in the CLI client and check the head_block_age
value.
If it seems to be unable to sync beyond a certain date¶
You should always make sure you use the newest build available here as earlier releases will get stuck due to hard-forks.
Is it safe to delete logs stored in witness_node_data_dirlogsp2p?¶
Yes, but
they’re rotated automatically after 24 hours anyway
if you don’t use them you should probably modify
config.ini
so they aren’t written to disk in the first place.
What is the best way to interact with the witness node?¶
The only way you can interact with the witness node is through the CLI client by using its API.
You can also use the GUI (i.e. the light client). Read more about : How to connect to your own Full Node (GUI)
What is the difference between public and private testnet?¶
Not much. The biggest difference is that public testnet are intended for wider audience and has fixed (not easy to change parameters), while private testnets can be setup with arbitrary settings.
What is the meaning of all those different text colors in the witness node console?¶
green - debug
white - info/default
yellow/brown - warning
red - error
blue - some kind of info, I don’t know
Related source files are in libraries/fc/include/fc/log/
and libraries/fc/src/log/
.
Whose private key is [“BTS6MRyAjQ..”,”5KQwrPbwdL..”]? Why is it predefined in the config.ini?¶
It’s a shared key for some special purpose. (But I don’t remember what it is. If I remember BM or someone else has ever explained it in the forum, but I can’t find the post right now. Just let it be there. I think if you comment it out, it will appear again automatically, it’s generated by the code of witness_node.)
Developers - Questions
Developers - FAQ¶
Are there any sharding mechanics currently deployed?¶
No
Are there any special affordances made for privacy?¶
…such as using CoinJoin or a ZK-SNARK based privacy scheme like Zerocash? If mixing is integrated at the protocl level are you using the standards set forth by the BNMCKF Mixcoin proposal
Confidential values (same as blockstream elements using the same secp256k1-zkp lib) + stealth addresses. https://github.com/ElementsProject/elementsproject.github.io/blob/master/confidential_values.md No mixing, No CoinJoin.
Does the protocol provide mechanisms for overlay protocols to interact such as OR_RETURN?¶
Yes, using a custom_operation.
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;
};
How are SPV clients handled?¶
No SPV clients at the moment, each full node can expose a public websocket/http api.
How are transactions validated?¶
Each operation has a defined evaluator that checks for preconditions (do_evaluate) and modify the state (do_apply). (After signature verification)
class transfer_evaluator : public evaluator<transfer_evaluator>
{
public:
typedef transfer_operation operation_type;
void_result do_evaluate( const transfer_operation& o );
void_result do_apply( const transfer_operation& o );
}
Note
See a list of System Components - Evaluators information.
How do new clients bootstrap into the network?¶
Trusted seed nodes. Knowledge of initial witness keys.
How is time addressed in the blockchain? Is NTP used or some other protocol?¶
NTP
Is the scripting language turing complete?¶
No scripting
Is this done via a gossip protocol or through a federate relay?¶
Each node immediately broadcast the data it receives to its peers after validating it https://github.com/cryptonomex/graphene/blob/master/libraries/p2p/design.md
What data structures are used in the blockchain?¶
Blocks => transactions => operations => objects.
The blockchain state is contained in an object database that is affected by the operations. Example objects::
account_object
asset_object
account_balance_object
...
class account_balance_object : public abstract_object<account_balance_object>
{
public:
static const uint8_t space_id = implementation_ids;
static const uint8_t type_id = impl_account_balance_object_type;
account_id_type owner;
asset_id_type asset_type;
share_type balance;
asset get_balance()const { return asset(balance, asset_type); }
void adjust_balance(const asset& delta);
};
What is the average block time?¶
Current 3 seconds, configurable by chain parameters.
What public key system is used? If elliptic curve, then what is the curve?¶
Same as Bitcoin, secp256k1.
What transaction types are natively supported?¶
Transaction are composed of operations (about ~40 different types). Example of operations are:
transfer_operation
limit_order_create_operation
asset_issue_operation
Full list : System component - Operations