Blockchain API

From BlockChainTeleCom wiki
Jump to: navigation, search

Default node configuration

Blockchain nodes are assumed to run continuously at 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

is_locked ( )
no params

Example

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

unlock

unlock (string password)

params:

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

Example

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

lock

lock ( )
no params


Example

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

Commonly used objects

ID Object Type
1.1.x base object
1.2.x account object
1.3.x asset object
1.4.x force settlement object
1.5.x committee member object
1.6.x witness object
1.7.x limit order object
1.8.x call order object
1.9.x custom object
1.10.x proposal object
1.11.x operation history object
1.12.x withdraw permission object
1.13.x vesting balance object
1.14.x worker object
1.15.x balance object

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.

upgrade_account

upgrade_account (string name, bool broadcast)

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.

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

suggest_brain_key

Generates 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"}}

register_account

Registers new account on the blockchain

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 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

import_key

import_key (string account_name_or_id, string wif_key)

Imports private key to wallet

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

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

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

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

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

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

transfer

transfer (string from, string to, string amount, string asset_symbol, string memo, bool broadcast = false)

Transfer an amount of asset from one account to another Participants can use this function for direct transfers of SDRT between them. Don't use this function to transfer offer-like assets.

params:

from the name or id of the account sending the funds
to the name or id of the account receiving the funds
amount the amount to send (in nominal units to send half of a SDRT, specify 0.5)
asset_symbol the symbol or id of the asset to send. Typically should be "SDRT"
memo a memo to attach to the transaction. The memo will be encrypted in the transaction and readable for the receiver. There is no length limit other than the limit imposed by maximum transaction size, but transaction increase with transaction size
broadcast true to broadcast the transaction on the network

Example

curl --data '{"jsonrpc": "2.0", "method": "transfer", "params": ["bank", "super-telecom", 1000, "SDRT", "here is some cash", "true"], "id": 1}' http://127.0.0.1:1227/rpc


add_account_key

add_account_key ( string name, optional<public_key_type> owner, optional<public_key_type> active, bool broadcast = false)

Adds another public keys to control specified account. Holder of private key corresponded to any added public key gets all appropriate credentials over account.

params:

name the name or id of the account to update
owner the public key for ownership authority to add to the account, null to not change owner key
active the public key for active authority to add to the account, null to not change active key
broadcast true to broadcast the transaction on the network

Remarks

Use this function in combination with remove_account_key to safely transfer ownership of account to another participant.

  1. New account holder generates new pair of pubic and private keys and sends pubic keys to previous account holder.
  2. Previous account holder adds public keys of new holder to account using add_account_key.
  3. New account holder imports private key for account into his wallet. Now he gets a full control over account.
  4. New account holder removes public key of previous holder using remove_account_key. Previous account holder losses control over account, new holder gets exclusive control over account and all its balances.

Use get_account function to check all public keys which can control the account.

Example

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


remove_account_key

remove_account_key ( string name, optional<public_key_type> owner, optional<public_key_type> active, bool broadcast = false)

Removes public key from the account. Holder of private key corresponded to removed public key loses all appropriate credentials over account.

params:

name the name or id of the account to update
owner the public key with ownership authority to remove from the account, null to not change owner key
active the public key with active authority to remove from the account, null to not change active key
broadcast true to broadcast the transaction on the network

Remarks

Use get_account function to check all public keys which can control the account.

Example

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

Creating and viewing assets (offers)

create_asset

create_asset (string issuer, string symbol, uint8 precision, asset_details common, optional<bitasset_options> bitasset_opts, bool broadcast = false) Creates a new user-issued asset.

params:

issuer the name or id of the account who will become the issuer of the new asset.
symbol the ticker symbol of the new asset. symbol of the asset must be unique blockchain-wide
precision the number of digits of precision to the right of the decimal point, must be less than or equal to 12. For typical usages as offers should be set to 0.
common asset_details required for all new assets. See below.
bitasset_opts reserved. set to null
broadcast true to broadcast the transaction on the network

asset_options : JSON struct
{

max_supply: integer - The maximum supply of this asset which may exist at any given time; Set to some big value , 1000000000000 is a good choice
whitelist_authorities: list - A set of whitelisted accounts. If whitelist_authorities is non-empty, then only whitelisted accounts are allowed to hold, use, or transfer the asset.
blacklist_authorities: list - A set of blacklisted accounts. An account may only send, receive, trade, etc. this asset if it is not blacklisted. If the account is blacklisted, it may not transact in this asset even if it is also whitelisted.
memo: string - description of the asset; specify all details of your offer in standardized XML format. If whitelist_authorities is non-empty, then memo is encrypted so that only whitelisted accounts can decrepit and read memo from the blockchain.

}

Remarks

Creating asset is a first step to offer services to other participants. You specify various aspects of the service, such as country of service, type of service, restrictions and price in SDR in description of the asset.


Example

curl --data '{"jsonrpc": "2.0", "method": "create_asset", "params": ["super-telecom", "NOPROBLEMS", 0, { "max_supply": "1000000000000", "whitelist_authorities": [], "blacklist_authorities": [], "memo": "<params>...XML descryption PUBLIC ...</params>" }, null, true], "id": 1}' http://127.0.0.1:1227/rpc

curl --data '{"jsonrpc": "2.0", "method": "create_asset", "params": ["super-telecom", "PRIVATE", 0, { "max_supply": "1000000000000", "whitelist_authorities": ["super-telecom", "partner-a", "partner-b"], "blacklist_authorities": [], "memo": "<params>...XML descryption PRIVATE ...</params>" }, null, true], "id": 1}' http://127.0.0.1:1227/rpc

issue_asset

issue_asset (string to_account, string amount, string symbol, string memo, bool broadcast = false)

Issue new shares of an asset.

params:

to_account the name or id of the account to receive the new shares. Always use name or id of your own account.
amount the amount to issue, in nominal units. Issue large enough amount just after creating new asset, 10000000000 is a good choice.
symbol the ticker symbol of the asset to issue
memo a memo to include in the transaction, readable by the recipient
broadcast true to broadcast the transaction on the network

Remarks

Service provider must issue some amount of asset to his own account to enable selling offers to other participants. It is convenient to issue fairly large amount of assets just after creating asset.


Example

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

update_asset

update_asset (string symbol, optional<string> new_issuer, asset_options new_options, bool broadcast = false)

This command is used to update the core options for an existing asset.

params:

symbol the name or id of the asset to update
new_issuer reserved. set to null
new_options asset options required for all new assets. See asset_options.
broadcast true to broadcast the transaction on the network

Remarks

Issuer may need update asset to change price of the offer, correct description, or set “expired” state. Use this function for those tasks.


Example

curl --data '{"jsonrpc": "2.0", "method": "update_asset", "params": ["NOPROBLEMS ", null, { "max_supply": "1000000000000", "whitelist_authorities": [], "blacklist_authorities": [], "memo": "<params>...XML descryption PUBLIC ...</params>" }, true], "id": 1}' http://127.0.0.1:1227/rpc

list_assets

list_assets list_assets(string lowerbound, uint32 last_seconds, uint32 limit)

Lists assets registered on the blockchain. To list all assets, pass the empty string "" for the lowerbound to start at the beginning of the list, and iterate as necessary.

params:

lowerbound the symbol of the first asset to include in the list.
last_seconds limit output by assets which were created or modified recently during specified time period in seconds. Set to 0 to list all assets.
limit the maximum number of assets to return (max: 1000)

Returns a list of asset_object

asset_object: : JSON struct
{

id: object_id_type - asset ID;
symbol: string - ticker symbol for this asset, i.e. "SDRT"
precision: integer - maximum number of digits after the decimal point (must be <= 12, should be 0 for offers )
issuer : account_id_type - ID of the account which issued this asset.
options : asset_options - asset options of the asset. See asset_options struct. Read options.description to get all details about corresponded offer
dynamic_asset_data_id: asset_dynamic_data_id_type - ID of asset_dynamic_data_object. Current supply, fee pool, and collected fees are stored in a separate : object as they change frequently
modification_timestamp : time - time when asset was created or time of last modification

}

Remarks

Use this function to navigate through offers created by service providers


Example

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

Example of response

{

"jsonrpc" : "2.0",
"id" : 1,
"result" : [
{
"symbol" : "BTE",
"modification_timestamp" : "1970-01-01T00:00:00",
"dynamic_asset_data_id" : "2.3.0",
"issuer" : "1.2.3",
"precision" : 5,
"id" : "1.3.0",
"options" : {
"max_market_fee" : "1000000000000000",
"market_fee_percent" : 0,
"flags" : 0,
"whitelist_markets" : [],
"issuer_permissions" : 0,
"description" : "",
"core_exchange_rate" : {
"quote" : {
"asset_id" : "1.3.0",
"amount" : 1
},
"base" : {
"amount" : 1,
"asset_id" : "1.3.0"
}
},
"max_supply" : "1000000000000000",
"extensions" : [],
"blacklist_markets" : [],
"whitelist_authorities" : [],
"blacklist_authorities" : []
}
},
{
"precision" : 4,
"id" : "1.3.1",
"issuer" : "1.2.19",
"modification_timestamp" : "1970-01-01T00:00:00",
"dynamic_asset_data_id" : "2.3.1",
"symbol" : "SDRT",
"options" : {
"whitelist_authorities" : [],
"blacklist_authorities" : [],
"description" : "Universal SDR pegged token",
"issuer_permissions" : 0,
"core_exchange_rate" : {
"base" : {
"amount" : 0,
"asset_id" : "1.3.0"
},
"quote" : {
"amount" : 0,
"asset_id" : "1.3.0"
}
},
"max_supply" : "1000000000000000",
"extensions" : [],
"blacklist_markets" : [],
"market_fee_percent" : 0,
"flags" : 64,
"whitelist_markets" : [],
"max_market_fee" : "1000000000000000"
}
},{
"symbol" : "PUBLICA"
"memo" : "<params>...XML descryption...</params>",
"issuer" : "1.2.21",
"options" : {
"core_exchange_rate" : {
"quote" : {
"asset_id" : "1.3.2",
"amount" : 1
},
"base" : {
"amount" : 1,
"asset_id" : "1.3.0"
}
},
"whitelist_markets" : [],
"whitelist_authorities" : [],
"extensions" : [],
"p_memo" : {
"message" : "000000003c706172616d733e2e2e2e584d4c206465736372797074696f6e2e2e2e3c2f706172616d733e",
"from" : "BTE1111111111111111111111111111111114T1Anm",
"gto" : [],
"nonce" : 0
},
"issuer_permissions" : 2,
"flags" : 64,
"blacklist_authorities" : [],
"market_fee_percent" : 0,
"blacklist_markets" : [],
"max_supply" : "1000000000000",
"max_market_fee" : "1000000000000000"
},
"modification_timestamp" : "2018-05-18T12:37:10",
"id" : "1.3.2",
"precision" : 0,
"dynamic_asset_data_id" : "2.3.2",
},
{
"symbol" : "PARTNERA",
"memo" : "<params>...XML private descryption...</params>"
"dynamic_asset_data_id" : "2.3.4",
"precision" : 0,
"id" : "1.3.4",
"modification_timestamp" : "2018-05-18T12:37:10",
"options" : {
"max_market_fee" : "1000000000000000",
"blacklist_markets" : [],
"max_supply" : "1000000000000",
"flags" : 66,
"market_fee_percent" : 0,
"blacklist_authorities" : [],
"p_memo" : {
"gto" : [
{
"ekey" : "eb9583020fc337fc2f01984f53a4a6c92fdc844838164fd8563a7f4eba3c06b41553be2fc8a989d5be82987457b640547844121a835f16665e9547b35d5952e505abed67b5daa77feb07956a5126d916",
"to" : "BTE8JsK7hGpPSyaNgHhKQLQGwwFACyvksUUgyKZfKP1kCySEL6oLt"
}
],
"message" : "0e183f0951efc58a38cbdf7e500c2dcd91103c7ac6d899ca3263099c18149813b53e822d63891e65801bca5216dcc01b01a47ceed19921434d16cc4bbb1b46d4",
"from" : "BTE6jdewg5KQ24T8tBCRnCtgbapEkJ2hBwXE1nXQR23VxLYbMo2cL",
"nonce" : "3316175981091154811"
},
"extensions" : [],
"issuer_permissions" : 2,
"whitelist_markets" : [],
"core_exchange_rate" : {
"base" : {
"amount" : 1,
"asset_id" : "1.3.0"
},
"quote" : {
"asset_id" : "1.3.4",
"amount" : 1
}
},
"whitelist_authorities" : [
"1.2.22"
]
},
"issuer" : "1.2.21",
},
{
"symbol" : "PARTNERB",
"memo_err" : " — Could not decrypt memo. No decryption key.",
"precision" : 0,
"dynamic_asset_data_id" : "2.3.3",
"options" : {
"max_market_fee" : "1000000000000000",
"blacklist_markets" : [],
"max_supply" : "1000000000000",
"flags" : 66,
"market_fee_percent" : 0,
"blacklist_authorities" : [],
"extensions" : [],
"issuer_permissions" : 2,
"p_memo" : {
"nonce" : "17151234028090960674",
"gto" : [
{
"to" : "BTE8JsK7hGpPSyaNgHhKQLQGwwFACyvksUUgyKZfKP1kCySEL6oLt",
"ekey" : "a9bdcdd20fd1cd497825d9d0c3b2f8cd"
}
],
"from" : "BTE6jdewg5KQ24T8tBCRnCtgbapEkJ2hBwXE1nXQR23VxLYbMo2cL",
"message" : "454009f30c0135ed55dd84fe5c9bc003fe1e0970a289ba4d86663cbb0b23887d31cf9b0744608136af4c7ec4854e4ef64dd51818f286af6f1face56c1a879612"
},
"whitelist_markets" : [],
"core_exchange_rate" : {
"base" : {
"amount" : 1,
"asset_id" : "1.3.0"
},
"quote" : {
"amount" : 1,
"asset_id" : "1.3.3"
}
},
"whitelist_authorities" : [
"1.2.22"
]
},
"issuer" : "1.2.21",
"id" : "1.3.3",
"modification_timestamp" : "2018-05-18T12:37:10"
}
]

}

get_asset

get_asset (string asset_name_or_id)

Returns information about the given asset.

params:

asset_name_or_id the symbol or id of the asset in question

Returns corresponded asset_object, see list_assets

Example

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

Creating requests and serving requests

Participants make requests for offers of service providers and serve requests of other operators by selling and buying corresponding asset. Selling and buying asset means that sides enter into contract.

sell_asset

sell_asset (string seller_account, string amount_to_sell, string symbol_to_sell, string min_to_receive, string symbol_to_receive, optional<offer_request_detail> offer_request, uint32 timeout_sec = 0, bool fill_or_kill = false, bool broadcast = false)

Place a limit order attempting to sell one asset for another. Market orders are matched in the order they are included in the block chain.

params:

seller_account the account providing the asset being sold, and which will receive the proceeds of the sale.
amount_to_sell the amount of the asset being sold to sell (in nominal units)
symbol_to_sell the name or id of the asset to sell
min_to_receive the minimum amount you are willing to receive in return for selling the entire amount_to_sell
symbol_to_receive the name or id of the asset you wish to receive
offer_request offer_request_detail object, optional, may be null. Applies additional restrictions on order matching specific to offer-request workflow. See below.
timeout_sec if the order does not fill immediately, this is the length of time the order will remain on the order books before it is cancelled and the un-spent funds are returned to the seller’s account
fill_or_kill if true, the order will only be included in the blockchain if it is filled immediately; if false, an open order will be left on the books to fill any amount that cannot be filled immediately.
broadcast true to broadcast the transaction on the network

offer_request_detail: JSON struct
{

request_id: uint64 - operator generated unique request ID. Counter order must specify the same value to match orders.
user_id: uint64 - operator generated identifier of his customer (actual user of mobile service). Counter order must specify the same value to match orders.
counterparty_id string - name or id of the counterparty account. If specified order matching is possible only for counter orders created by this account.
memo: string - supplies auxiliary data, i.e. requester supplies request details, service provider supplies service data, including encoded user profile for customer's SIM card. Memo is encrypted so that only two participants (order creator and specified counterparty) can decrypt and read it from the blockchain.

}

Remarks

Selling and buying asset is implemented by the same function call, actual operation is defined by asset to sell and asset to receive.

Request starts when one side (presumably home operator) makes an order to sell specified amount of SDR for some asset (typically of amount 1) issued by other service provider.

Service providers checks orders related to assets issued by him and makes a counter order by selling asset for SDR and suppling necessary IMSI profile data (encrypted by requester’s public key).

When both orders match each other services provider immediately receives corresponded amount of SDRT tokens to his balance, requester receives user profile data which he can decrypt by his private key and upload to customer’s SIM card

After matching and filling orders (request - serve request) results can be seen from account history. See get_account_history, get_account_history_operations.

Examples

curl --data '{"jsonrpc": "2.0", "method": "sell_asset", "params": ["home-operator", "9.99", "SDRT", "1" "NOPROBLEMS", { "request_id": 12345, "user_id": 1234, "counterparty_id": "foreign-operator", "memo": "<params>...Request details in XML...</params>"}, 86400, "false", "true"], "id": 1}' http://127.0.0.1:1227/rpc

curl --data '{"jsonrpc": "2.0", "method": "sell_asset", "params": ["foreign-operator", "1" "NOPROBLEMS", "9.99", "SDRT", { "request_id": 12345, "user_id": 1234, "counterparty_id": "home-operator", "memo": "<params>...Service details and user profile in XML...</params>"}, 86400, "false", "true"], "id": 1}' http://127.0.0.1:1227/rpc

get_limit_orders

get_limit_orders (string a, string b, uint32 limit)

returns a list of limit_order_objviewer corresponded to a given asset pair. Normally one of the asset should be “SDRT” and another is asset symbol corresponded to the offer.

params:

a the symbol or id of the first asset
b the symbol or id of the second asset
limit restrict output by specified number of orders

limit_order_objviewer: JSON struct
{

id: object_id_type - unique limit order ID
expiration: time_point - order expiration time
seller: account_id_type - ID of the order creator account
for_sale: big integer - amount of the asset for sale
sell_price: price - price object specifying sail price and asset to receive
deferred_fee: big integer - reserved, ignore this value
umt_fee: asset - SDR amount reserved to pay blockchain fee
request_id: optional<uint64> - corresponds to offer_request_detail.request_id if offer_request has been specified in sell_asset
user_id: optional<uint64> - corresponds to offer_request_detail.user_id if offer_request has been specified in sell_asset
counterparty_id: optional<account_id_type> - corresponds to offer_request_detail.counterparty_id if offer_request has been specified in sell_asset
p_memo: optional< memo_data > - encrypted memo data
p_accepted_memo: optional< memo_data > - encrypted memo data
memo: optional<string> - corresponds to offer_request_detail.memo if offer_request has been specified in sell_asset. Contains request details and requester's public key to encrypt user data. Visible only to order creator and specified counterparty (offer_request_detail.counterparty_id)
accepted_memo: optional<string> - corresponds to offer_request_detail.memo after counterparty's call of accept_limit_order. Contain service details and customer's IMSI profile data. Visible only to order creator and specified counterparty (offer_request_detail.counterparty_id)
memo_err: optional<string> - if description of p_memo failed contains description of the failure.
accepted_memo_err: optional<string> - if description of p_accepted_memo failed contains description of the failure.

};

price: JSON struct
{

base: asset - base asset, that is the asset being sold in sell operation
quote: asset - quote asset, that is the asset being purchased in sell operation

}

asset: JSON struct
{ amount: big integer - amount of the asset asset_id: asset_id_type - ID of the asset }

Remarks

Service provider periodically reads orders from the blockchain to monitor requests of other operators to his services.

Example

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

Example of response

{

"id" : 1,
"jsonrpc" : "2.0",
"result" : [
{
"id" : "1.7.3",
"counterparty_id" : "1.2.21",
"request_id" : 12345,
"seller" : "1.2.23",
"deferred_fee" : 0,
"for_sale" : 59900,
"sell_price" : {
"quote" : {
"amount" : 1,
"asset_id" : "1.3.3"
},
"base" : {
"amount" : 59900,
"asset_id" : "1.3.1"
}
},
"expiration" : "2018-05-26T10:44:27",
"umt_fee" : {
"asset_id" : "1.3.1",
"amount" : 1198
},
"p_memo" : {
"message" : "2e55d326f6c3eac48efee0bfbaac289ed554e3d6629552eee582c79e79d7961ffa25ef2fcc18fb6992912ca9eef44f432103ef1e660411a4d0faa207e870fd5b",
"to" : "BTE6jdewg5KQ24T8tBCRnCtgbapEkJ2hBwXE1nXQR23VxLYbMo2cL",
"from" : "BTE7EJpNzzCJts1EJWfrzkzrWwB65TL7WA51BirngPiKEyqkkPj5q",
"nonce" : "2307370254281396803"
},
"user_id" : 1234,
"memo" : "<params>...Request details PRIVATE in XML...</params>"
}
]

}

get_account_limit_orders

get_account_limit_orders (string aname, uint32_t limit)

returns a list of limit_order_objviewer placed by owner of specified account.

params:

aname the name or id of the order creator account.
limit restrict output by specified number of orders.

Remarks

Use this function to monitor the sate of your orders and changes applied by accept_limit_order call

Example

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

accept_limit_order

accept_limit_order ( string seller_account, string symbol_to_sell, string symbol_to_receive, offer_request_detail offer_request, bool broadcast = false)

Supplies user profile IMSI data and other service details without making counter order to request of another operator.

params:

seller_account the name or id of the service provider account accepting an request
symbol_to_sell the symbol or id of the asset to sell, normally corresponds to offer of service provider
symbol_to_receive the symbol or id of the asset to receive, normally should be "SDRT"
offer_request offer_request_detail object, containing order matching details and encoded data to transfer.
broadcast true to broadcast the transaction on the network

Remarks

Service providers use this function to implement more flexible charging of potential customers. Service provider may supply customer all data necessary to start service, but servicing doesn't start immediately. In this case customer has an option to start usage of service at any time (may be withing specified period of service) or not use it at all. Home operator doesn't pay for service at this point but necessary funds are reserved from his account balance.

In a case user decides to start actual using the service the service provider charges home operator by calling sell_asset function in a regular way.

Home operator may cancel his order before customer start using it. Service provider should periodically check accepted orders and don't start servicing if order has been canceled.

Example

curl --data '{"jsonrpc": "2.0", "method": "accept_limit_order", "params": ["foreign-operator", "NOPROBLEMS", "SDRT", { "request_id": 12345, "user_id": 1234, "counterparty_id": "home-operator", "memo": "<params>...Service details and user profile in XML...</params>"}, "true"], "id": 1}' http://127.0.0.1:1227/rpc

cancel_order

cancel_order (object_id_type order_id, bool broadcast = false)

Cancel an existing order

params:

order_id the id of order to be cancelled
broadcast true to broadcast the transaction on the network

Examples

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

get_account_history

get_account_history (string name, int limit)

Returns the most recent operations on the named account. This returns a list of operation history objects, which describe activity on the account.

params:

name the name or id of the account .
limit the number of entries to return (starting from the most recent).

returns a list of operation_detail objects

operation_detail
{

memo: string - operation-specific memo; see description of operation of interest
description: string - human readable description of the operation
op: operation_history_object - operation as it was registered on the blockchain

}

operation_history_object: JSON struct
{

op: operation - operation details, can be mapped to various blockchain operations
result: operation_result - operation results
block_num: uint32 - the block that caused this operation
trx_in_block: uint16 - the transaction in the block
op_in_trx: uint16 - the operation within the transaction
virtual_op: uint16 - any virtual operations implied by operation in block

};

Essential operations

operation is produced after creating new order

operation code is 1

limit_order_create_operation: JSON struct {

seller: account_id_type
amount_to_sell: asset
min_to_receive: asset
expiration: time_point - The order will be removed from the books if not filled by expiration. Upon expiration, all unsold asset will be returned to seller
fill_or_kill: bool - If this flag is set the entire order must be filled or the operation is rejected
request_id: optional< uint64 > - match information from offer_request_detail object
user_id: optional< uint64 > - match information from offer_request_detail object
counterparty_id: optional< account_id_type > - match information from offer_request_detail object
p_memo: optional< memo_data > - encrypted memo data from offer_request_detail object as was specified at order creation. If user is an owner of appropriate private key ( user must be limit order creator or specified counterparty) then operation_detail.memo contains decrypted memo.

}


virtual operation is produced after your order has been filled by counter order

operation code is 4

struct fill_order_operation: JSON struct {

order_id: object_id_type
account_id: account_id_type
pays: asset
receives: asset
fill_price: price
is_maker: bool
request_id: optional<uint64> - match information from offer_request_detail object
user_id: optional<uint64> - match information from offer_request_detail object
p_memo: optional<memo_data> - encrypted memo data from counterparty's order. If user is an owner of appropriate private key (user must be limit order creator or specified counterparty) then operation_detail.memo contains decrypted memo.

}


operation is produced when service provider calls accept_limit_order function. Blockchain stores history record for service provider's account.

operation code is 46

limit_order_accept_operation: JSON struct {

seller: account_id_type - account id of the caller of accept_limit_order
asset_id_to_sell: as set_id_type
asset_id_to_receive: asset_id_type
request_id: uint64 - match information from offer_request_detail object
user_id: uint64 - match information from offer_request_detail object
counterparty_id: account_id_type - requester's account id
memo: memo_data - encrypted memo data from offer_request_detail object as was specified at accept_limit_order call. If user is an owner of appropriate private key (user must be limit order creator or specified counterparty) then operation_detail.memo contains decrypted memo.

}


operation is produced when service provider calls accept_limit_order function. Blockchain stores history record for requester's account.

operation code is 47

limit_order_accepted_operation: JSON struct {

order_id: object_id_type
order_creator_account_id: account_id_type - account id of the requester who created request order
asset_id_to_sell: asset_id_type
asset_id_to_receive: asset_id_type
request_id: uint64 - match information from offer_request_detail object
user_id: uint64 - match information from offer_request_detail object
accepted_by_account_id: account_id_type - account id of the service provider who called accept_limit_order
accepted_memo : memo_data - encrypted memo data from offer_request_detail object as was specified at accept_limit_order call by service provider. If user is an owner of appropriate private key (user must be limit order creator or specified counterparty) then operation_detail.memo contains decrypted memo.

}

Examples

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

get_account_history_operations

get_account_history_operations ( string name, int operation_code, int limit)

Returns the most recent operations of specified operation code on the named account. This returns a list of operation history objects, which describe activity on the account. See also get_account_history

params:

name the name or id of the account .
operation_code the code of the operation of interest.
limit the number of entries to return (starting from the most recent).

Examples

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

Network management : Witnesses and Committee Members

Creating Witness

create_witness

create_witness (string owner_account, string url, bool broadcast = false)

Creates a witness object owned by the given account. An account can have at most one witness object.

params:

owner_account the name or id of the account which is creating the witness.
url a URL to include in the witness record in the blockchain. Clients may display this when showing a list of witnesses. May be blank.
broadcast true to broadcast the transaction on the network

update_witness

update_witness (string witness_name, string url, string block_signing_key, bool broadcast = false)

Update a witness object owned by the given account.

params:

witness The name of the witness’s owner account. Also accepts the ID of the owner account or the ID of the witness.
url Same as for create_witness. The empty string makes it remain the same.
block_signing_key The new block signing public key. The empty string makes it remain the same.
broadcast true to broadcast the transaction on the network

get_witness

Returns information about the given witness.

params:

owner_account the name or id of the witness account owner, or the id of the witness

Creating committee members

create_committee_member

create_committee_member (string owner_account, string url, bool broadcast = false)

Creates a committee_member object owned by the given account. An account can have at most one committee_member object.

params:

owner_account the name or id of the account which is creating the committee_member
url a URL to include in the committee_member record in the blockchain. Clients may display this when showing a list of committee_members. May be blank.
broadcast true to broadcast the transaction on the network

get_committee_member

get_committee_member (string owner_account)

Returns information about the given committee_member.

params:

owner_account the name or id of the committee_member account owner, or the id of the committee_member

Voting for witnesses and committee members

vote_for_witness

vote_for_witness (string voting_account, string witness, bool approve, bool broadcast = false)

Vote for a given witness.

An account can publish a list of all witnesses they approve of. This command allows you to add or remove witnesses from this list. Each account’s vote is weighted according to the number of shares of the core asset owned by that account at the time the votes are tallied.

Note you cannot vote against a witness, you can only vote for the witness or not vote for the witness.

params:

voting_account the name or id of the account who is voting with their shares
witness the name or id of the witness’ owner account
approve true if you wish to vote in favor of that witness, false to remove your vote in favor of that witness
broadcast true if you wish to broadcast the transaction

vote_for_committee_member

vote_for_committee_member (string voting_account, string committee_member, bool approve, bool broadcast = false)

Vote for a given committee_member.

An account can publish a list of all committee_memberes they approve of. This command allows you to add or remove committee_memberes from this list. Each account’s vote is weighted according to the number of shares of the core asset owned by that account at the time the votes are tallied.

Note you cannot vote against a committee_member, you can only vote for the committee_member or not vote for the committee_member.

params:

voting_account the name or id of the account who is voting with their shares
committee_member the name or id of the committee_member’ owner account
approve true if you wish to vote in favor of that committee_member, false to remove your vote in favor of that committee_member
broadcast true if you wish to broadcast the transaction

get_full_accounts

get_full_accounts ( vector<string> &names_or_ids, bool subscribe) Send this command to witness_node RPC port, not cli_wallet port

Fetch all objects relevant to the specified accounts and 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.

get_full_accounts also return a list of witnesses and committee_members which have been voted for by the specified accounts.

params:

names_or_ids Each item must be the name or ID of an account to retrieve
subscribe reserved, set to false

Changing number of witnesses and committee members

set_desired_witness_and_committee_member_count

set_desired_witness_and_committee_member_count (string account_to_modify, uint16_t desired_number_of_witnesses, uint16_t desired_number_of_committee_members, bool broadcast = false)

Set your vote for the number of witnesses and committee_members in the system.

Each account can voice their opinion on how many committee_members and how many witnesses there should be in the active committee_member/active witness list. These are independent of each other. You must vote your approval of at least as many committee_members or witnesses as you claim there should be (you can’t say that there should be 20 committee_members but only vote for 10).

There are maximum values for each set in the blockchain parameters (currently defaulting to 1001).

This setting can be changed at any time. If your account has a voting proxy set, your preferences will be ignored.

params:

account_to_modify the name or id of the account to update
desired_number_of_witnesses, number_of_committee_members the number
broadcast true if you wish to broadcast the transaction