Blockchain API

From BlockChainTeleCom wiki
Revision as of 14:35, 28 March 2018 by Smaltsev (talk | contribs) (Default node configuration)
Jump to: navigation, search

Default node configuration

Blockchain nodes are assumed to run continuously in 24/7 mode


default P2P port for witness_node : 27800 (must be globally accessible)

default RPC port for witness_node : 7212 (local only by default)

default RPC port for cli_wallet : 1227 (local only by default)


Commands must be sent to cli_wallet RPC port if not specified otherwise.

Wallet access

is_locked
no params

unlock (string password)

params:

password local password to unlock wallet and get access to the encrypted private keys needed for signing transaction

lock
no params

Examples

curl --data '{"jsonrpc": "2.0", "method": "is_locked", "params": [], "id": 1}' http://127.0.0.1:1227/rpc

curl --data '{"jsonrpc": "2.0", "method": "unlock", "params": ["MySuperSecretPassword"], "id": 1}' http://127.0.0.1:1227/rpc

curl --data '{"jsonrpc": "2.0", "method": "lock", "params": [], "id": 1}' http://127.0.0.1:1227/rpc

Account creation and initial configuration

To create a new account, one need to ask an owner of another account (registrar) with appropriate permissions (account must be upgraded) to register new account in the blockchain.

The following steps must be performed:

  1. Upgrade account of registrar if necessary (done by registrar account owner)
  2. Generate new public and private keys. Backup generated keys and keep them securely. There are no ways to restore access to your accounts and your funds if your private key is lost or leaked.
  3. Send public key (never send private key!) and desired account name to registrar
  4. Register new account and notify owner of new account that registration was successfully completed (done by registrar account owner)
  5. Import private key into your wallet. After that you will get a full control over your newly created account.

Account upgrading

Upgrading must be done once per account. After upgrading the following additional functions are available:

  • Register other accounts
  • Create witness – other participants will be able to vote for your account; after successful voting account will be able to validate blockchain blocks
  • Create committee member - - other participants will be able to vote for your account; after successful voting you will be able to propose changes to blockchain parameters and vote for proposals of other committee members.

upgrade_account (string name, bool broadcast)

params:

name the name or id of the account to upgrade
broadcast true to broadcast the transaction on the network

Example

curl --data '{"jsonrpc": "2.0", "method": "upgrade_account", "params": ["super-telecom", "true"], "id": 1}' http://127.0.0.1:1227/rpc

Generating new private and public keys

New operator must generate private and public keys for its account and safely store them. There are no ways to restore access to your accounts and your funds if your private key is lost or leaked.

Keys can be generated using cli_wallet:

suggest_brain_key ()
no params

Example

curl --data '{"jsonrpc": "2.0", "method": "suggest_brain_key", "params": [], "id": 1}' http://127.0.0.1:1227/rpc
return
{"id":1,"jsonrpc":"2.0","result":{"brain_priv_key":"DANDIFY DIBASE HUMANLY UNPERCH SANDBUR OUTBUZZ STAGE TRIPPLE INVITE WARDMAN PEDUM TSUNAMI TARRAS OXIDIZE OASEAN TYPHIC","wif_priv_key":"5KJYJ9u4TTDXpCjDEjxGbAkvybCQJgeE5Yq3hN5Q4UtUrdmBF79","pub_key":"BTS5CaAg1Eb9NoBAhizY68NZFvadrTWQE8cb9bfVNZUrM9SBowdZi"}}


Registering new account

New operator should send public key to registrar while keeping private keys securely. Never send private key!

Owner of registrar account registers new account, specifying account name and public keys:

register_account (string name, public_key_type owner, public_key_type active, string registrar_account, string referrer_account, uint32_t referrer_percent, bool broadcast = false)

params:

name the name of the account, must be unique on the blockchain. Shorter names are more expensive to register; the rules are still in flux, but in general names of more than 8 characters with at least one digit will be cheap.
owner the owner key for the new account
active the active key for the new account
registrar_account the account which will pay the fee to register the user
referrer_account the account who is acting as a referrer, and may receive a portion of the user’s transaction fees. Normally this should be the same as the registrar_account if there is no referrer.
referrer_percent the percentage (0 - 100) of the new user’s transaction fees not claimed by the blockchain that will be distributed to the referrer; the rest will be sent to the registrar. Currently transaction fees are zero cost, set this parameter to 0.
broadcast true to broadcast the transaction on the network

Example

curl --data '{"jsonrpc": "2.0", "method": "register_account", "params": ["super-telecom", "BTS5CaAg1Eb9NoBAhizY68NZFvadrTWQE8cb9bfVNZUrM9SBowdZi", "BTS5CaAg1Eb9NoBAhizY68NZFvadrTWQE8cb9bfVNZUrM9SBowdZi", "authorized-registrar", "authorized-registrar", 0, "true"], "id": 1}' http://127.0.0.1:1227/rpc

Importing private key to wallet

After successful registration of the new account user imports its private key to his wallet.

import_key (string account_name_or_id, string wif_key)

params:

account_name_or_id the account owning the key
wif_key the private key in WIF format

The private key must match either an owner key or an active key for the named account.

Example

curl --data '{"jsonrpc": "2.0", "method": "import_key", "params": ["super-telecom", "5KJYJ9u4TTDXpCjDEjxGbAkvybCQJgeE5Yq3hN5Q4UtUrdmBF79"], "id": 1}' http://127.0.0.1:1227/rpc

General account functions

list_accounts (const string &lowerbound, uint32_t limit)

Lists all accounts registered in the blockchain. This returns a list of all account names and their account ids, sorted by account name.

params:

lowerbound the name of the first account to return. If the named account does not exist, the list will start at the account that comes after lowerbound
limit the maximum number of accounts to return (max: 1000)

Use the lowerbound and limit parameters to page through the list. To retrieve all accounts, start by setting lowerbound to the empty string "", and then each iteration, pass the last account name returned as the lowerbound for the next list_accounts() call.

Example

curl --data '{"jsonrpc": "2.0", "method": "list_accounts", "params": ["", 100], "id": 1}' http://127.0.0.1:1227/rpc



list_my_accounts ()

Lists all accounts controlled by this wallet. This returns a list of the full account objects for all accounts whose private keys we possess.

no params

Example

curl --data '{"jsonrpc": "2.0", "method": "list_my_accounts", "params": [], "id": 1}' http://127.0.0.1:1227/rpc



get_account (string account_name_or_id)

Get public information about the given account.

params:

account_name_or_id the name or id of the account to provide information about

Example

curl --data '{"jsonrpc": "2.0", "method": "get_account", "params": ["super-telecom"], "id": 1}' http://127.0.0.1:1227/rpc



list_account_balances (string account_name_or_id)

List the balances of an account. Each account can have multiple balances, one for each type of asset owned by that account. Assets may be SDR funds or offers for mobile operators.

The returned list will only contain assets for which the account has a nonzero balance.

params:

account_name_or_id the name or id of the account whose balances you want

Example

curl --data '{"jsonrpc": "2.0", "method": "list_account_balances", "params": ["super-telecom"], "id": 1}' http://127.0.0.1:1227/rpc