1 of 100

Peerplays Developer Docs

Developer Documentation

Your gateway to comprehensive APIs, guides for common services, use case examples, resources, tools, and more. Developer documentation is all about empowering you to build on the Peerplays blockchain.

API Reference

This section explains about the different types of API calls involved in exchanges and gateways. The sample output for several API calls are also listed. The following APIs are explained in this section:

Peerplays Core API
Wallet API
Bookie API

API Libraries

API Libraries plays an important role in communicating with Peerplays blockchain. This section explains about:

Steps to install
How to create an account?
How to create a Peerplays wallet?
NFT, Marketplace, and Role based Permission API

Click the below link to learn about the API Libraries in detail.

Development Guides

The guides in this section will describe about the User Issued Assets, types of permissions, a detailed explanation about NFTs, and finally about cost calculation. Click the link below to learn in detail.

The Cookbook

Peerplays community need some specialized work to accomplish the vision of the community. The work includes file encoding, file storage, content verifiers, and Content Delivery Network (CDN) gateways which are not covered directly by Peerplays but a system is created to complete these works in a decentralized way. Click the below link to learn in detail about the plan and process.

Tools & Integration

This section explains about important Authentication techniques and random numbers:

Peer ID - Explain about Authentication and Requirement to create a Peer ID
Random Number Generator (RNG) - Explain about RNG Generation process and API involved in getting a random number.

Reference Docs

This section contains needful documents which helps to provide details about any questions that arise during learning and experimenting with Peerplays applications.

The topics under Supporting & Reference Documents are listed below:

Workflow

The workflow section provides a step by step approach followed in the Peerplays development process. Click below to learn in details about the nature of workflow involved in developing any application.

API Reference

Peerplays Core API

Popular API Calls

Overview

Some of the most interesting API calls for exchanges and gateways are listed in this document.

We will now take a look at some sample outputs for some of the API calls.

API Calls

list_account_balances

List the balances of an account. Each account can have multiple balances, one for each type of asset owned by that account. The returned list will only contain assets for which the account has a nonzero balance.

vector<asset> graphene::wallet::wallet_api::list_account_balances(
    const string &id)

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

A list of the given account’s balances.

import json
from grapheneapi import GrapheneAPI
client = GrapheneAPI("localhost", 8092, "", "")
res = client.list_account_balances("dan")
print(json.dumps(res,indent=4))

[
    {
        "asset_id": "1.3.0",
        "amount": "331104701530"
    },
    {
        "asset_id": "1.3.511",
        "amount": 3844848635
    },
    {
        "asset_id": "1.3.427",
        "amount": 8638
    },
    {
        "asset_id": "1.3.536",
        "amount": 31957981
    }
]

transfer

Transfer an amount from one account to another.

signed_transaction graphene::wallet::wallet_api::transfer(
    string from, 
    string to, 
    string amount, 
    string asset_symbol, 
    string memo, 
    bool broadcast = false)

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 BTS, specify 0.5)
asset_symbol: the symbol or id of the asset to send
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

The final parameter True states that the signed transaction will be broadcast. If this parameter is False the transaction will be signed but not broadcast, hence not executed.

The signed transaction transferring funds.

import json
from grapheneapi import GrapheneAPI
client = GrapheneAPI("localhost", 8092, "", "")
res = client.transfer("fromaccount","toaccount","10", "USD", "$10 gift", True);
print(json.dumps(res,indent=4))

{
  "ref_block_num": 18,
  "ref_block_prefix": 2320098938,
  "expiration": "2015-10-13T13:56:15",
  "operations": [[
      0,{
        "fee": {
          "amount": 2089843,
          "asset_id": "1.3.0"
        },
        "from": "1.2.17",
        "to": "1.2.7",
        "amount": {
          "amount": 10000000,
          "asset_id": "1.3.0"
        },
        "memo": {
          "from": "GPH6MRyAjQq8ud7hVNYcfnVPJqcVpscN5So8BhtHuGYqET5GDW5CV",
          "to": "GPH6MRyAjQq8ud7hVNYcfnVPJqcVpscN5So8BhtHuGYqET5GDW5CV",
          "nonce": "16430576185191232340",
          "message": "74d0e455e2e5587b7dc85380102c3291"
        },
        "extensions": []
      }
    ]
  ],
  "extensions": [],
  "signatures": [
    "1f147aed197a2925038e4821da54bd7818472ebe25257ac9a7ea66429494e7242d0dc13c55c6840614e6da6a5bf65ae609a436d13a3174fd12f073550f51c8e565"
  ]
}

transfer2

This method works just like transfer, except it always broadcasts and returns the transaction ID (hash) along with the signed transaction.

pair<transaction_id_type, signed_transaction> graphene::wallet::wallet_api::transfer2(
    string from, 
    string to, 
    string amount, 
    string asset_symbol, 
    string memo)

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
asset_symbol: the symbol or id of the asset to send
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

The transaction ID (hash) along with the signed transaction transferring funds

import json
from grapheneapi import GrapheneAPI
client = GrapheneAPI("localhost", 8092, "", "")
res = client.transfer2("fromaccount","toaccount","10", "USD", "$10 gift");
print(json.dumps(res,indent=4))

 [b546a75a891b5c51de6d1aafd40d10e91a717bb3,{
   "ref_block_num": 18,
   "ref_block_prefix": 2320098938,
   "expiration": "2015-10-13T13:56:15",
   "operations": [[
       0,{
         "fee": {
           "amount": 2089843,
           "asset_id": "1.3.0"
         },
         "from": "1.2.17",
         "to": "1.2.7",
         "amount": {
           "amount": 10000000,
           "asset_id": "1.3.0"
         },
         "memo": {
           "from": "GPH6MRyAjQq8ud7hVNYcfnVPJqcVpscN5So8BhtHuGYqET5GDW5CV",
           "to": "GPH6MRyAjQq8ud7hVNYcfnVPJqcVpscN5So8BhtHuGYqET5GDW5CV",
           "nonce": "16430576185191232340",
           "message": "74d0e455e2e5587b7dc85380102c3291"
         },
         "extensions": []
       }
     ]
   ],
   "extensions": [],
   "signatures": [
     "1f147aed197a2925038e4821da54bd7818472ebe25257ac9a7ea66429494e7242d0dc13c55c6840614e6da6a5bf65ae609a436d13a3174fd12f073550f51c8e565"
   ]
 }
]

get_account_history

Returns the most recent operations on the named account.

This returns a list of operation history objects, which describe activity on the account.

vector<operation_detail> graphene::wallet::wallet_api::get_account_history(
    string name, 
    int limit)const

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

A list of operation_history_objects.

import json
from grapheneapi import GrapheneAPI
client = GrapheneAPI("localhost", 8092, "", "")
res = client.get_account_history("dan", 1)
print(json.dumps(res,indent=4))

[
     {
         "description": "fill_order_operation dan fee: 0 CORE",
         "op": {
             "block_num": 28672,
             "op": [
                 4,
                 {
                     "pays": {
                         "asset_id": "1.3.536",
                         "amount": 20000
                     },
                     "fee": {
                         "asset_id": "1.3.0",
                         "amount": 0
                     },
                     "order_id": "1.7.1459",
                     "account_id": "1.2.21532",
                     "receives": {
                         "asset_id": "1.3.0",
                         "amount": 50000000
                     }
                 }
             ],
             "id": "1.11.213277",
             "trx_in_block": 0,
             "virtual_op": 47888,
             "op_in_trx": 0,
             "result": [
                 0,
                 {}
             ]
         },
         "memo": ""
     }
 ]

get_object

Returns the blockchain object corresponding to the given id.

This generic function can be used to retrieve any object from the blockchain that is assigned an ID. Certain types of objects have specialized convenience functions to return their objects e.g., assets have get_asset(), accounts have get_account(), but this function will work for any object.

variant graphene::wallet::wallet_api::get_object(
    object_id_type id)const

id: the id of the object to return

The requested object.

import json
from grapheneapi import GrapheneAPI
client = GrapheneAPI("localhost", 8092, "", "")
res = client.get_object("1.11.213277")
print(json.dumps(res,indent=4))

{
    "trx_in_block": 0,
    "id": "1.11.213277",
    "block_num": 28672,
    "op": [
        4,
        {
            "fee": {
                "asset_id": "1.3.0",
                "amount": 0
            },
            "receives": {
                "asset_id": "1.3.0",
                "amount": 50000000
            },
            "pays": {
                "asset_id": "1.3.536",
                "amount": 20000
            },
            "account_id": "1.2.21532",
            "order_id": "1.7.1459"
        }
    ],
    "result": [
        0,
        {}
    ],
    "op_in_trx": 0,
    "virtual_op": 47888
}

get_asset

Returns information about the given asset.

extended_asset_object graphene::wallet::wallet_api::get_asset(
    string asset_name_or_id)const

asset_name_or_id: the symbol or id of the asset in question

The information about the asset stored in the block chain.

import json
from grapheneapi import GrapheneAPI
client = GrapheneAPI("localhost", 8092, "", "")
res = client.get_asset("USD")
print(json.dumps(res,indent=4))

{
    "symbol": "USD",
    "issuer": "1.2.1",
    "options": {
        "description": "1 United States dollar",
        "whitelist_authorities": [],
        "flags": 0,
        "extensions": [],
        "core_exchange_rate": {
            "quote": {
                "asset_id": "1.3.536",
                "amount": 11
            },
            "base": {
                "asset_id": "1.3.0",
                "amount": 22428
            }
        },
        "whitelist_markets": [],
        "max_supply": "1000000000000000",
        "blacklist_markets": [],
        "issuer_permissions": 79,
        "market_fee_percent": 0,
        "max_market_fee": "1000000000000000",
        "blacklist_authorities": []
    },
    "dynamic_asset_data_id": "2.3.536",
    "bitasset_data_id": "2.4.32",
    "id": "1.3.536",
    "precision": 4
}

Account History

The history API is available from the full node via websockets.

Account History

get_account_history

Get operations relevant to the specified account.

vector<operation_history_object> graphene::app::history_api::get_account_history(
    const std::string account_id_or_name, 
    operation_history_id_type stop = operation_history_id_type(), 
    unsigned limit = 100, 
    operation_history_id_type start = operation_history_id_type())const

account_id_or_name: The account ID or name whose history should be queried
stop: ID of the earliest operation to retrieve
limit: Maximum number of operations to retrieve (must not exceed 100)
start: ID of the most recent operation to retrieve

A list of operations performed by account, ordered from most recent to oldest.

get_account_history_operations

Get only asked operations relevant to the specified account.

vector<operation_history_object> graphene::app::history_api::get_account_history_operations(
    const std::string account_id_or_name, 
    int operation_type, 
    operation_history_id_type start = operation_history_id_type(), 
    operation_history_id_type stop = operation_history_id_type(), 
    unsigned limit = 100)const

account_id_or_name: The account ID or name whose history should be queried
operation_type: The type of the operation we want to get operations in the account ( 0 = transfer , 1 = limit order create, …)
stop: ID of the earliest operation to retrieve
limit: Maximum number of operations to retrieve (must not exceed 100)
start: ID of the most recent operation to retrieve

A list of operations performed by account, ordered from most recent to oldest.

get_relative_account_history

Get operations relevant to the specified account referenced by an event numbering specific to the account. The current number of operations for the account can be found in the account statistics (or use 0 for start).

vector<operation_history_object> graphene::app::history_api::get_relative_account_history(
    const std::string account_id_or_name, 
    uint64_t stop = 0, 
    unsigned limit = 100, 
    uint64_t start = 0)const

account_id_or_name: The account ID or name whose history should be queried
stop: Sequence number of earliest operation. 0 is default and will query ‘limit’ number of operations.
limit: Maximum number of operations to retrieve (must not exceed 100)
start: Sequence number of the most recent operation to retrieve. 0 is default, which will start querying from the most recent operation.

A list of operations performed by account, ordered from most recent to oldest.

Market History

get_fill_order_history

Get details of order executions occurred most recently in a trading pair.

vector<order_history_object> graphene::app::history_api::get_fill_order_history(
    std::string a, 
    std::string b, 
    uint32_t limit)const

a: Asset symbol or ID in a trading pair
b: The other asset symbol or ID in the trading pair
limit: Maximum records to return

a list of order_history objects, in most recent first order

get_market_history

Get OHLCV data of a trading pair in a time range.

vector<bucket_object> graphene::app::history_api::get_market_history(
    std::string a, 
    std::string b, 
    uint32_t bucket_seconds, 
    fc::time_point_sec start, 
    fc::time_point_sec end)const

a: Asset symbol or ID in a trading pair
b: The other asset symbol or ID in the trading pair
bucket_seconds: Length of each time bucket in seconds.

Note: It needs to be within result of get_market_history_buckets(), otherwise no data will be returned

start: The start of a time range, E.G. “2018-01-01T00:00:00”
end: The end of the time range

A list of OHLCV data, in least recent first order.

If there are more than 200 records in the specified time range, the first 200 records will be returned.

get_market_history_buckets

Get OHLCV time bucket lengths supported (configured) by this API server.

flat_set<uint32_t> graphene::app::history_api::get_market_history_buckets()const

A list of time bucket lengths in seconds.

For example, if the result contains a number “300” it means this API server supports OHLCV data aggregated in 5-minute buckets.

Asset API

get_asset_holders

Get asset holders for a specific asset.

vector<account_asset_balance> graphene::app::asset_api::get_asset_holders(
    std::string asset, 
    uint32_t start, 
    uint32_t limit)const

asset: The specific asset id or symbol
start: The start index
limit: Maximum limit must not exceed 100

A list of asset holders for the specified asset.

get_all_asset_holders

Get all asset holders.

vector<asset_holders> graphene::app::asset_api::get_all_asset_holders()const

A list of all asset holders.

Block API

get_blocks

Get signed blocks.

vector<optional<signed_block>> graphene::app::block_api::get_blocks(
    uint32_t block_num_from, 
    uint32_t block_num_to)const

block_num_from: The lowest block number
block_num_to: The highest block number

A list of signed blocks from block_num_from to block_num_to

Crypto API

The crypto API is available from the full node via websockets.

Blinding and Un-Blinding

blind

Get signed blocks.

Generates a Pedersen Commitment: *commit = blind * G + value * G2. The commitment is 33 bytes, the blinding factor is 32 bytes.

blind: Sha-256 blind factor type
value: Positive 64-bit integer value

A 33-byte Pedersen Commitment: commit = blind G + value * G2

blind_sum

Get SHA-256 blind factor type.

blinds_in: List of SHA-256 blind factor types
non_neg: 32-bit integer value

A blind factor type.

Range Proofs

range_get_info

Gets “range proof” information.

The cli_wallet includes functionality for sending blind transfers in which the values of the input and output amounts are “blinded.”

Note: In the case where a transaction produces two or more outputs, (e.g. an amount to the intended recipient plus “charge” back to the sender), a “range proof” must be supplied to prove that none of the outputs commit to a negative value.

proof: List of proof’s characters

A range proof info structure with exponent, mantissa, min and max values.

range_proof_sign

Proves with respect to min_value the range for Pedersen Commitment which has the provided blinding factor and value.

min_value: Positive 64-bit integer value
commit: 33-byte pedersen commitment
commit_blind: Sha-256 blind factor type for the correct digits
nonce: Sha-256 blind factor type for our non-forged signatures
base10_exp: Exponents base 10 in range [-1 ; 18] inclusively
min_bits: 8-bit positive integer, must be in range [0 ; 64] inclusively
actual_value: 64-bit positive integer, must be greater or equal min_value

A list of characters as proof in proof.

Verification

verify_sum

Verifies that commits + neg_commits + excess == 0.

commits_in: List of 33-byte Pedersen Commitments
neg_commits_in: List of 33-byte Pedersen Commitments
excess: Sum of two list of 33-byte Pedersen Commitments where sums the first set and subtracts the second

(Boolean) True in event of commits + neg_commits + excess == 0, otherwise false

verify_range

Verifies range proof for 33-byte Pedersen Commitment.

commit: 33-byte pedersen commitment
proof: List of characters

A structure with success, min and max values

verify_range_proof_rewind

Verifies range proof rewind for 33-byte Pedersen Commitment.

nonce: Sha-256 blind refactor type
commit: 33-byte pedersen commitment
proof: List of characters

A structure with success, min, max, value_out, blind_out and message_out values.

Database API

The database API is available from the full node via web-sockets.

Objects

get_objects

Get the objects corresponding to the provided IDs.

If any of the provided IDs does not map to an object, a null variant is returned in its position.

Subscriptions

set_subscribe_callback

cb: The callback handle to register
notify_remove_create: Whether subscribe to universal object creation and removal events. If this is set to true, the API server will notify all newly created objects and ID of all newly removed objects to the client, no matter whether client subscribed to the objects. By default, API servers don’t allow subscribing to universal events, which can be changed on server startup.

set_pending_transaction_callback

Note: A transaction can be pushed to the database and be popped from the database several times while processing, before and after,, included in a block. Every time a push is done, the client will be notified.

cb: The callback handle to register

set_block_applied_callback

cb: The callback handle to register

cancel_all_subscriptions

Stop receiving any notifications.

This unsubscribes from all subscribed markets and objects.

Blocks and transactions

get_block_header

Retrieve a block header.

block_num: Height of the block whose header should be returned

The header of the referenced block, or null if no matching block was foun

get_block

Retrieve a full, signed block.

block_num: Height of the block to be returned

The referenced block, or null if no matching block was found.

get_transaction

Fetch an individual transaction.

block_num: height of the block to fetch
trx_in_block: the index (sequence number) of the transaction in the block, starts from 0

The transaction at the given position.

get_recent_transaction_by_id

txid: hash of the transaction

The corresponding transaction if found, or null if not found.

If the transaction has not expired, this method will return the transaction for the given ID or it will return NULL if it is not known. Just because it is not known does not mean it wasn’t included in the blockchain.

Globals

get_chain_properties

get_global_properties

get_config

Retrieve compile-time constants.

get_chain_id

Get the chain ID.

get_dynamic_global_properties

Keys

get_key_references

Get all accounts that refer to the specified public keys in their owner authority, active authorities or memo key.

keys: a list of public keys to query

ID of all accounts that refer to the specified keys.

Accounts

get_accounts

Get a list of accounts by names or IDs.

account_names_or_ids: names or IDs of the accounts to retrieve

The accounts corresponding to the provided names or IDs.

get_full_accounts

Fetch all objects relevant to the specified accounts and optionally 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 innames_or_ids cannot be tied to an account, that input will be ignored. All other accounts will be retrieved and subscribed.

names_or_ids: Each item must be the name or ID of an account to retrieve

Map of string from names_or_ids to the corresponding account.

get_account_by_name

Get info of an account by name.

name: Name of the account to retrieve

The account holding the provided name.

get_account_references

Get all accounts that refer to the specified account in their owner or active authorities.

account_name_or_id: Account name or ID to query

All accounts that refer to the specified account in their owner or active authorities

lookup_account_names

Get a list of accounts by name.

account_names: Names of the accounts to retrieve

The accounts holding the provided names.

lookup_accounts

Get names and IDs for registered accounts.

Note: In addition to the common auto-subscription rules, this API will subscribe to the returned account only if limit is 1.

lower_bound_name: Lower bound of the first name to return
limit: Maximum number of results to return must not exceed 1000

Map of account names to corresponding IDs.

get_account_count

Get the total number of accounts registered with the blockchain.

Balances

get_account_balances

Get an account’s balances in various assets.

account_name_or_id: name or ID of the account to get balances for.
assets: IDs of the assets to get balances of; if empty, get all assets account has a balance in.

Balances of the account.

get_named_account_balances

account_name_or_id: name or ID of the account to get balances for.
assets: IDs of the assets to get balances of; if empty, get all assets account has a balance in.

Balances of the account.

get_balance_objects

addrs: a list of addresses

All unclaimed balance objects for the addresses.

get_vested_balances

Calculate how much assets in the given balance objects are able to be claimed at current head block time.

objs: a list of balance object IDs

A list indicating how much asset in each balance object is available to be claimed.

get_vesting_balances

Return all vesting balance objects owned by an account.

account_name_or_id: name or ID of an account

All vesting balance objects owned by the account.

Assets

get_assets

Get a list of assets by symbol names or IDs.

asset_symbols_or_ids: symbol names or IDs of the assets to retrieve

The assets corresponding to the provided symbol names or IDs.

list_assets

Get assets alphabetically by symbol name.

lower_bound_symbol: Lower bound of symbol names to retrieve
limit: Maximum number of assets to fetch (must not exceed 101)

The assets found.

lookup_asset_symbols

Get a list of assets by symbol names or IDs.

symbols_or_ids: symbol names or IDs of the assets to retrieve

The assets corresponding to the provided symbols or IDs

Markets / Feeds

get_order_book

Returns the order book for the market base

base: symbol name or ID of the base asset
quote: symbol name or ID of the quote asset
limit: depth of the order book to retrieve, for bids and asks each, capped at 50

Order book of the market.

get_limit_orders

Get limit orders in a given market.

a: symbol or ID of asset being sold
b: symbol or ID of asset being purchased
limit: Maximum number of orders to retrieve

The limit orders, ordered from least price to greatest.

get_call_orders

Get call orders (aka margin positions) for a given asset.

a: symbol name or ID of the debt asset
limit: Maximum number of orders to retrieve

The call orders, ordered from earliest to be called to latest

get_settle_orders

Get forced settlement orders in a given asset.

a: Symbol or ID of asset being settled
limit: Maximum number of orders to retrieve

The settle orders, ordered from earliest settlement date to latest.

get_margin_positions

Get all open margin positions of a given account.

account_name_or_id: name or ID of an account

All open margin positions of the account.

subscribe_to_market

Request notification when the active orders in the market between two assets changes.

Callback will be passed a variant containing a vector<pair<operation, operation_result>>.

The vector will contain, in order, the operations which changed the market, and their results

callback: Callback method which is called when the market changes
a: symbol name or ID of the first asset
b: symbol name or ID of the second asset

unsubscribe_from_market

Unsubscribe from updates to a given market.

a: symbol name or ID of the first asset
b: symbol name or ID of the second asset

get_ticker

Returns the ticker for the market assetA:assetB.

base: symbol name or ID of the base asset
quote: symbol name or ID of the quote asset

The market ticker for the past 24 hours.

get_24_volume

Returns the 24 hour volume for the market assetA:assetB.

base: symbol name or ID of the base asset
quote: symbol name or ID of the quote asset

The market volume over the past 24 hours.

get_trade_history

Returns recent trades for the market base:quote, ordered by time, most recent first.

Note: Currently, timezone offsets are not supported. The time must be UTC.

base: symbol or ID of the base asset
quote: symbol or ID of the quote asset
start: Start time as a UNIX timestamp, the latest trade to retrieve
stop: Stop time as a UNIX timestamp, the earliest trade to retrieve
limit: Number of transactions to retrieve, capped at 100.

Recent transactions in the market

Witnesses

get_witnesses

Get a list of witnesses by ID.

witness_ids: IDs of the witnesses to retrieve

The witnesses corresponding to the provided IDs.

get_witness_by_account

Get the witness owned by a given account.

account_name_or_id: The name or ID of the account whose witness should be retrieved

The witness object, or null if the account does not have a witness.

lookup_witness_accounts

Get names and IDs for registered witnesses.

lower_bound_name: Lower bound of the first name to return
limit: Maximum number of results to return must not exceed 1000

Map of witness names to corresponding IDs.

get_witness_count

Get the total number of witnesses registered with the blockchain.

Committee members

get_committee_members

Get a list of committee_members by ID.

committee_member_ids: IDs of the committee_members to retrieve

The committee_members corresponding to the provided IDs.

get_committee_member_by_account

Get the committee_member owned by a given account.

account_name_or_id: The name or ID of the account whose committee_member should be retrieved

The committee_member object, or null if the account does not have a committee_member.

lookup_committee_member_accounts

Get names and IDs for registered committee_members.

lower_bound_name: Lower bound of the first name to return
limit: Maximum number of results to return must not exceed 1000

Map of committee_member names to corresponding IDs

Workers

get_workers_by_account

Get the workers owned by a given account.

account_name_or_id: The name or ID of the account whose worker should be retrieved

A list of worker objects owned by the account.

Votes

lookup_vote_ids

Given a set of votes, returns the objects they are voting for.

This will be a mixture of committee_member_objects, witness_objects, and worker_objects

votes: a list of vote IDs

The referenced objects

The results will be in the same order as the votes. Null will be returned for any vote IDs that are not found.

Authority / Validation

get_transaction_hex

Get a hexdump of the serialized binary form of a transaction.

trx: a transaction to get hexdump from

The hexdump of the transaction.

get_required_signatures

This API will take a partially signed transaction and a set of public keys that the owner has the ability to sign for and return the minimal subset of public keys that should add signatures to the transaction.

trx: the transaction to be signed
available_keys: a set of public keys

A subset of available_keys that could sign for the given transaction.

get_potential_signatures

trx: the transaction to be signed

A set of public keys that could possibly sign for the given transaction.

get_potential_address_signatures

This method will return the set of all addresses that could possibly sign for a given transaction.

trx: the transaction to be signed

A set of addresses that could possibly sign for the given transaction.

verify_authority

Check whether a transaction has all of the required signatures

trx: a transaction to be verified

true if the trx has all of the required signatures, otherwise throws an exception.

verify_account_authority

Verify that the public keys have enough authority to approve an operation for this account.

account_name_or_id: name or ID of an account to check
signers: the public keys

true if the passed in keys have enough authority to approve an operation for this account.

validate_transaction

Validates a transaction against the current state without broadcasting it on the network.

trx: a transaction to be validated

A processed_transaction object if the transaction passes the validation, otherwise an exception will be thrown.

get_required_fees

For each operation calculate the required fee in the specified asset type.

ops: a list of operations to be query for required fees
asset_symbol_or_id: symbol name or ID of an asset that to be used to pay the fees

A **list of objects which indicates required fees of each operation

Proposed Transactions

get_proposed_transactions

Gets a set of proposed transactions (proposals) that the specified account can add approval to or remove approval from.

account_name_or_id: The name or ID of an account

A set of proposed transactions that the specified account can act on.

Blinded balances

get_blinded_balances

Gets the set of blinded balance objects by commitment ID.

commitments: a set of commitments to query for

The set of blinded balance objects by commitment ID.

Network Broadcast API

The network broadcast API is available from the full node via web-sockets.

Transactions

broadcast_transaction

Broadcast a transaction to the network.

The transaction will be checked for validity in the local database prior to broadcasting. If it fails to apply locally, an error will be thrown and the transaction will not be broadcast

trx: The transaction to broadcast

broadcast_transaction_with_callback

This version of broadcast transaction registers a callback method that will be called when the transaction is included into a block. The callback method includes the transaction id, block number, and transaction number in the block.

cb: the callback method
trx: the transaction

Block

broadcast_block

Broadcast a signed block to the network.

block: The signed block to broadcast.

Network Nodes API

The network node API is available from the full node via web-sockets.

Obtain Network Information

get_info

Return general network information, such as p2p port.

fc::variant_object graphene::app::network_node_api:get_info()const

get_connected_peers

Get status of all current connections to peers.

std::vector<net::peer_status> graphene::app::network_node_api::get_connected_peers()const

get_potential_peers

Return list of potential peers.

std::vector<net::potential_peer_record> graphene::app::network_node_api::get_potential_peers()const

get_advanced_node_parameters

Get advanced node parameters, such as desired and max number of connections.

fc::variant_object graphene::app::network_node_api::get_advanced_node_parameters()const

Change Network Settings

add_node

Connect to a new peer

void graphene::app::network_node_api::add_node(
    const fc::ip::endpoint &ep)

ep: The IP/Port of the peer to connect to

set_advanced_node_parameters

Set advanced node parameters, such as desired and max number of connections.

void graphene::app::network_node_api::set_advanced_node_parameters(
    const fc::variant_object &params)

params: a JSON object containing the name/value pairs for the parameters to set

Orders API

get_grouped_limit_orders

Get grouped limit orders in given market.

base_asset: ID or symbol of asset being sold
quote_asset: ID or symbol of asset being purchased
group: Maximum price diff within each order group, have to be one of configured values
start: Optional price to indicate the first order group to retrieve
limit: Maximum number of order groups to retrieve (must not exceed 101)

The grouped limit orders, ordered from best offered price to the worst.

Wallet API

The wallet (cli_wallet) requires a running full node to connect to because it does not offer P2P or blockchain capabilities directly.

Account Calls

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.

A list of account objects

list_accounts

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

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.

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)

A list of accounts mapping account names to account ids.

list_account_balances

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

A list of the given account’s balances

register_account

Registers a third party’s account on the blockchain.

This function is used to register an account for which you do not own the private keys. When acting as a registrar, an end user will generate their own private keys and send you the public keys. The registrar will use this function to register the account on behalf of the end user.

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. This can 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. Will be multiplied by GRAPHENE_1_PERCENT when constructing the transaction.
broadcast: true to broadcast the transaction on the network

The signed transaction registering the account

upgrade_account

Upgrades an account to prime status. This makes the account holder a ‘lifetime member’.

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

The signed transaction upgrading the account

create_account_with_brain_key

Creates a new account and registers it on the blockchain.

brain_key: the brain key used for generating the account’s private keys
account_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.
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. This can be the same as the registrar_account if there is no referrer.
broadcast: true to broadcast the transaction on the network

The signed transaction registering the account

transfer

Transfer an amount from one account to another.

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, for example to send half of a PPY specify 0.5)
asset_symbol: the symbol or id of the asset to send
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

The signed transaction transferring funds

transfer2

This method works just like transfer, except it always broadcasts and returns the transaction ID (hash) along with the signed transaction.

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, for example to send half of a PPY specify 0.5)
asset_symbol: the symbol or id of the asset to send
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

The transaction ID (hash) along with the signed transaction transferring funds

whitelist_account

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.

authorizing_account: the account who is doing the whitelisting
account_to_list: the account being whitelisted
new_listing_status: the new whitelisting status
broadcast: true to broadcast the transaction on the network

The signed transaction changing the whitelisting status

get_vesting_balances

Get information about a vesting balance object or vesting balance objects owned by an account.

account_name: An account name, account ID, or vesting balance object ID.

A list of vesting balance objects with additional info

withdraw_vesting

Withdraw a vesting balance.

witness_name: The account name of the witness, also accepts account ID or vesting balance ID type.
amount: The amount to withdraw.
asset_symbol: The symbol of the asset to withdraw.
broadcast: true if you wish to broadcast the transaction

The signed transaction

get_account

Returns information about the given account.

account_name_or_id: the name or ID of the account to provide information about

The public account data stored in the blockchain

get_account_id

Lookup the id of a named account.

account_name_or_id: the name or ID of the account to look up

The id of the named account

get_account_history

Returns the most recent operations on the named account.

This returns a list of operation history objects, which describe activity on the account.

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

A list of operation_history_objects

approve_proposal

Approve or disapprove a proposal.

fee_paying_account: The account paying the fee for the op.
proposal_id: The proposal to modify.
delta: Members contain approvals to create or remove. In JSON you can leave empty members undefined.
broadcast: true if you wish to broadcast the transaction

The signed version of the transaction

Asset Calls

list_assets

Lists all 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.

lowerbound: the symbol of the first asset to include in the list.
limit: the maximum number of assets to return (max: 100)

The list of asset objects, ordered by symbol.

create_asset

Creates a new user-issued or market-issued asset.

Note: Right now this function is difficult to use because you must provide raw JSON data structures for the options objects, and those include prices and asset ids.

issuer: the name or id of the account who will pay the fee and become the issuer of the new asset. This can be updated later
symbol: the ticker symbol of the new asset
precision: the number of digits of precision to the right of the decimal point, must be less than or equal to 12
common: asset options required for all new assets. Note that core_exchange_rate technically needs to store the asset ID of this new asset. Since this ID is not known at the time this operation is created, create this price as though the new asset has instance ID 1, and the chain will overwrite it with the new asset’s ID.
bitasset_opts: options specific to BitAssets. This may be null unless the market_issued flag is set in common.flags
broadcast: true to broadcast the transaction on the network

The signed transaction creating a new asset.

update_asset

Update the core options on an asset. There are a number of options which all assets in the network use. These options are enumerated in the asset_object::asset_options struct.

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

symbol: the name or id of the asset to update
new_issuer: if changing the asset’s issuer, the name or id of the new issuer. null if you wish to remain the issuer of the asset
new_options: the new asset_options object, which will entirely replace the existing options.
broadcast: true to broadcast the transaction on the network

The signed transaction updating the asset

update_bitasset

Update the options specific to a BitAsset.

BitAssets have some options which are not relevant to other asset types. This operation is used to update those options as an existing BitAsset.

symbol: the name or id of the asset to update, which must be a market-issued asset
new_options: the new bitasset_options object, which will entirely replace the existing options.
broadcast: true to broadcast the transaction on the network

The signed transaction updating the Bitasset

update_asset_feed_producers

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 command is used to specify which accounts may produce feeds for a given BitAsset.

symbol: the name or id of the asset to update
new_feed_producers: a list of account names or ids which are authorized to produce feeds for the asset. this list will completely replace the existing list
broadcast: true to broadcast the transaction on the network

The signed transaction updating the BitAsset’s feed producers

publish_asset_feed

Publishes a price feed for the named asset.

Price feed providers use this command 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 object in this command contains three prices:

A call price limit
A short price limit,
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 BTC, the call limit price will be PPY/BTC and the short limit price will be BTC/PPY.

The settlement price may be flipped either direction, as long as it is a ratio between the market-issued asset and its collateral.

publishing_account: the account publishing the price feed
symbol: the name or id of the asset whose feed we’re publishing
feed: the price_feed object containing the three prices making up the feed
broadcast: true to broadcast the transaction on the network

The signed transaction updating the price feed for the given asset.

issue_asset

Issue new shares of an asset.

to_account: the name or id of the account to receive the new shares
amount: the amount to issue, in nominal units
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

The signed transaction issuing the new shares

get_asset

Returns information about the given asset.

asset_name_or_id: the symbol or id of the asset in question

The information about the asset stored in the block chain.

get_bitasset_data

asset_name_or_id: the symbol or id of the BitAsset in question

The BitAsset-specific data for this asset

fund_asset_fee_pool

Pay into the fee pool for the given asset.

User-issued assets can optionally have a pool of the core asset which is automatically used to pay transaction fees for any transaction using that asset (using the asset’s core exchange rate).

This command allows anyone to deposit the core asset into this fee pool.

from: the name or id of the account sending the core asset
symbol: the name or id of the asset whose fee pool you wish to fund
amount: the amount of the core asset to deposit
broadcast: true to broadcast the transaction on the network

The signed transaction funding the fee pool.

reserve_asset

Burns an amount of given asset.

This command burns an amount of given asset to reduce the amount in circulation.

Note: You can't burn market-issued assets.

from: the account containing the asset you wish to burn
amount: the amount to burn, in nominal units
symbol: the name or id of the asset to burn
broadcast: true to broadcast the transaction on the network

The signed transaction burning the asset

global_settle_asset

Forces a global settling of the given asset (black swan or prediction markets).

In order to use this operation, asset_to_settle must have the global_settle flag set

If this asset is used as backing for other BitAssets, those BitAssets will not be affected.

Note: This operation is used only by the asset issuer.

symbol: the name or id of the asset to globally settle
settle_price: the price at which to settle
broadcast: true to broadcast the transaction on the network

The signed transaction settling the named asset

Blockchain Inspection

get_block

Returns info about a specified block.

optional<signed_block_with_info> graphene::wallet::wallet_api::get_block(
    uint32_t num)

num: height of the block to retrieve

Info about the block, or null if not found.

get_account_count

Returns the number of accounts registered on the blockchain.

uint64_t graphene::wallet::wallet_api::get_account_count()const

The number of registered accounts

get_global_properties

Returns the block chain’s slowly-changing settings.

This object contains all of the properties of the blockchain that are fixed or that change only once per maintenance interval (daily) such as the current list of witnesses, committee_members, block interval, etc.

See get_dynamic_global_properties() for frequently changing properties.

global_property_object graphene::wallet::wallet_api::get_global_properties()const

The global properties.

get_dynamic_global_properties

Returns the block chain’s rapidly-changing properties. The returned object contains information that changes every block interval such as the head block number, the next witness, etc. See get_global_properties() for less-frequently changing properties.

dynamic_global_property_object graphene::wallet::wallet_api::get_dynamic_global_properties()const

The dynamic global properties.

get_object

Returns the blockchain object corresponding to the given id.

variant graphene::wallet::wallet_api::get_object(
    object_id_type id)const

id: the id of the object to return.

The requested object.

General Calls

help

Returns a list of all commands supported by the wallet API.

A multi-line string suitable for displaying on a terminal.

gethelp

Returns detailed help on a single API command.

method: the name of the API command you want help with

A multi-line string suitable for displaying on a terminal.

info

Returns info about head block, chain_id, maintenance, participation, current active witnesses and committee members.

Runtime info about the blockchain

about

Returns info such as client version, git version of graphene/fc, version of boost, openssl etc.

Compile time info and client and dependencies versions.

network_add_nodes

nodes: Nodes to be added.

network_get_connected_peers

List of connected peers.

Governance

create_committee_member

Creates a committee_member object owned by the given account.

An account can have at most one committee_member object.

signed_transaction graphene::wallet::wallet_api::create_committee_member(
    string owner_account, 
    string url, 
    bool broadcast = false)

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

The signed transaction registering a committee_member

get_witness

Returns information about the given witness.

witness_object graphene::wallet::wallet_api::get_witness(
    string owner_account)

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

The information about the witness stored in the block chain.

get_committee_member

Returns information about the given committee_member.

committee_member_object graphene::wallet::wallet_api::get_committee_member(
    string owner_account)

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

The information about the committee_member stored in the block chain

list_witnesses

Lists all Witnesses registered in the blockchain. This returns a list of all account names that own Witnesses, and the associated witness id, sorted by name. This lists Witnesses whether they are currently voted in or not.

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

map<string, witness_id_type> graphene::wallet::wallet_api::list_witnesses(
    const string &lowerbound, 
    uint32_t limit)

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

A list of Witness's mapping witness names to witness ids

list_committee_members

Lists all committee_members registered in the blockchain. This returns a list of all account names that own committee_members, and the associated committee_member id, sorted by name. This lists committee_members whether they are currently voted in or not.

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

map<string, committee_member_id_type> graphene::wallet::wallet_api::list_committee_members(
    const string &lowerbound, 
    uint32_t limit)

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

A list of committee_members mapping committee_member names to committee_member ids

create_witness

Creates a witness object owned by the given account.

An account can have at most one witness object.

signed_transaction graphene::wallet::wallet_api::create_witness(
    string owner_account, 
    string url, 
    bool broadcast = false)

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

The signed transaction registering a witness

update_witness

Update a witness object owned by the given account.

signed_transaction graphene::wallet::wallet_api::update_witness(
    string witness_name, 
    string url, 
    string block_signing_key, 
    bool broadcast = false)

witness_name: 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 if you wish to broadcast the transaction.

The signed transaction

create_worker

Create a worker object.

signed_transaction graphene::wallet::wallet_api::create_worker(
    string owner_account, 
    time_point_sec work_begin_date, 
    time_point_sec work_end_date, 
    share_type daily_pay, 
    string name, string url, 
    variant worker_settings, 
    bool broadcast = false)

owner_account: The account which owns the worker and will be paid
work_begin_date: When the work begins
work_end_date: When the work ends
daily_pay: Amount of pay per day (NOT per maint interval)
name: Any text
url: Any text
worker_settings: {“type” : “burn”|”refund”|”vesting”, “pay_vesting_period_days” : x}
broadcast: true if you wish to broadcast the transaction.

The signed transaction

update_worker_votes

Update your votes for workers.

signed_transaction graphene::wallet::wallet_api::update_worker_votes(
    string account, 
    worker_vote_delta delta,
    bool broadcast = false)

account: The account which will pay the fee and update votes.
delta: {“vote_for” : […], “vote_against” : […], “vote_abstain” : […]}
broadcast: true if you wish to broadcast the transaction.

The signed transaction

vote_for_committee_member

Vote for a given committee_member.

An account can publish a list of all committee_members they approve of. This command allows you to add or remove committee_members 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 can't vote against a committee_member, you can only vote for the committee_member or not vote for the committee_member.

signed_transaction graphene::wallet::wallet_api::vote_for_committee_member(
    string voting_account, 
    string committee_member, 
    bool approve, 
    bool broadcast = false)

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 favour of that committee_member, false to remove your vote in favour of that committee_member
broadcast: true if you wish to broadcast the transaction

The signed transaction changing your vote for the given committee_member.

vote_for_witness

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 can't vote against a witness, you can only vote for the witness or not vote for the witness.

signed_transaction graphene::wallet::wallet_api::vote_for_witness(
    string voting_account, 
    string witness, 
    bool approve, 
    bool broadcast = false)

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 favour of that witness, false to remove your vote in favour of that witness
broadcast: true if you wish to broadcast the transaction

The signed transaction changing your vote for the given witness

set_voting_proxy

Set the voting proxy for an account.

If a user does not wish to take an active part in voting, they can choose to allow another account to vote their stake.

Setting a vote proxy does not remove your previous votes from the blockchain, they remain there but are ignored. If you later null out your vote proxy, your previous votes will take effect again.

This setting can be changed at any time.

signed_transaction graphene::wallet::wallet_api::set_voting_proxy(
    string account_to_modify, 
    optional<string> voting_account, 
    bool broadcast = false)

account_to_modify: the name or id of the account to update
voting_account: the name or id of an account authorized to vote account_to_modify’s shares, or null to vote your own shares
broadcast: true if you wish to broadcast the transaction

The signed transaction changing your vote proxy settings

set_desired_witness_and_committee_member_count

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.

signed_transaction graphene::wallet::wallet_api::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)

account_to_modify: the name or id of the account to update
desired_number_of_witnesses: desired number of active witnesses
desired_number_of_committee_members: desired number of active committee members
broadcast: true if you wish to broadcast the transaction

The signed transaction changing your vote proxy settings

propose_parameter_change

Creates a transaction to propose a parameter change.

Multiple parameters can be specified if an atomic change is desired.

signed_transaction graphene::wallet::wallet_api::propose_parameter_change(
    const string &proposing_account, 
    fc::time_point_sec expiration_time, 
    const variant_object &changed_values, 
    bool broadcast = false)

proposing_account: The account paying the fee to propose the tx
expiration_time: Timestamp specifying when the proposal will either take effect or expire.
changed_values: The values to change; all other chain parameters are filled in with default values
broadcast: true if you wish to broadcast the transaction

The signed version of the transaction

propose_fee_change

Propose a fee change.

signed_transaction graphene::wallet::wallet_api::propose_fee_change(
    const string &proposing_account, 
    fc::time_point_sec expiration_time, 
    const variant_object &changed_values, 
    bool broadcast = false)

proposing_account: The account paying the fee to propose the tx
expiration_time: Timestamp specifying when the proposal will either take effect or expire.
changed_values: Map of operation type to new fee. Operations may be specified by name or ID. The “scale” key changes the scale. All other operations will maintain current values.
broadcast: true if you wish to broadcast the transaction

The signed version of the transaction

Privacy Mode

set_key_label

These methods are used for stealth transfers This method can be used to set a label for a public key

Note: No two keys can have the same label.

key: a public key
label: a user-defined string as label

True if the label was set, otherwise false

get_key_label

Get label of a public key.

get_public_key

Get the public key associated with a given label

label: a label

The public key associated with the given label.

get_blind_accounts

Get all blind accounts.

All blind accounts

get_my_blind_accounts

Get all blind accounts for which this wallet has the private key.

All blind accounts for which this wallet has the private key.

get_blind_balances

Return the total balances of all blinded commitments that can be claimed by the given account key or label.

key_or_label: a public key in Base58 format or a label

The total balances of all blinded commitments that can be claimed by the given account key or label

create_blind_account

Generates a new blind account for the given brain key and assigns it the given label

label: a label
brain_key: the brain key to be used to generate a new blind account

The public key of the new account

transfer_to_blind

Transfers a public balance from from_account_id_or_name to one or more blinded balances using a stealth transfer.

from_account_id_or_name: ID or name of an account to transfer from
asset_symbol: symbol or ID of the asset to be transferred
to_amounts: map from key or label to amount
broadcast: true to broadcast the transaction on the network

A blind confirmation

transfer_from_blind

Transfers funds from a set of blinded balances to a public account balance.

from_blind_account_key_or_label: a public key in Base58 format or a label to transfer from
to_account_id_or_name: ID or name of an account to transfer to
amount: the amount to be transferred
asset_symbol: symbol or ID of the asset to be transferred
broadcast: true to broadcast the transaction on the network

A blind confirmation.

blind_transfer

Transfer from one set of blinded balances to another.

from_key_or_label: a public key in Base58 format or a label to transfer from
to_key_or_label: a public key in Base58 format or a label to transfer to
amount: the amount to be transferred
symbol: symbol or ID of the asset to be transferred
broadcast: true to broadcast the transaction on the network

A blind confirmation

blind_history

Get all blind receipts to/form a particular account.

key_or_account: a public key in Base58 format or an account

All blind receipts to/form the account.

receive_blind_transfer

Given a confirmation receipt, this method will parse it for a blinded balance and confirm that it exists in the blockchain. If it exists then it will report the amount received and who sent it.

confirmation_receipt: a base58 encoded stealth confirmation
opt_from: if not empty and the sender is a unknown public key, then the unknown public key will be given the label opt_from
opt_memo: a self-defined label for this transfer to be saved in local wallet file

A blind receipt.

Trading Calls

sell_asset

Place a limit order attempting to sell one asset for another.

Buying and selling are the same operation on Peerplays; if you want to buy PPY with BTC, you should sell BTC for PPY.

The blockchain will attempt to sell the symbol_to_sell for as much symbol_to_receive as possible, as long as the price is at least min_to_receive / amount_to_sell.

In addition to the transaction fees, 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 whitelist restricted, the order will only be created if the seller is on the whitelist of the restricted asset type.

Market orders are matched in the order they are included in the block chain.

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, for example 0.5 for half of a PPY)
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
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

The signed transaction selling the funds.

borrow_asset

Borrow an asset or update the debt/collateral ratio for the loan.

This is the first step in shorting an asset.

borrower_name: the name or id of the account associated with the transaction.
amount_to_borrow: the amount of the asset being borrowed. Make this value negative to pay back debt.
asset_symbol: the symbol or id of the asset being borrowed.
amount_of_collateral: the amount of the backing asset to add to your collateral position. Make this negative to claim back some of your collateral. The backing asset is defined in the bitasset_options for the asset being borrowed.
broadcast: true to broadcast the transaction on the network

The signed transaction borrowing the asset

cancel_order

Cancel an existing order.

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

The signed transaction canceling the order

settle_asset

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.

account_to_settle: the name or id of the account owning the asset
amount_to_settle: the amount of the named asset to schedule for settlement
symbol: the name or id of the asset to settle
broadcast: true to broadcast the transaction on the network

The signed transaction settling the named asset.

get_market_history

Get OHLCV (Open, High, Low, Close, & Volume) data of a trading pair in a time range.

symbol: name or ID of the base asset
symbol2: name or ID of the quote asset
bucket: length of each time bucket in seconds.
start: the start of a time range, E.G. “2018-01-01T00:00:00”
end: the end of the time range

A list of OHLCV data, in “least recent first” order.

get_limit_orders

Get limit orders in a given market.

a: symbol or ID of asset being sold
b: symbol or ID of asset being purchased
limit: Maximum number of orders to retrieve

The limit orders, ordered from least price to greatest.

get_call_orders

Get call orders (aka margin positions) for a given asset.

a: symbol name or ID of the debt asset
limit: Maximum number of orders to retrieve

The call orders, ordered from earliest to be called to latest

get_settle_orders

Get forced settlement orders in a given asset.

a: Symbol or ID of asset being settled
limit: Maximum number of orders to retrieve

The settle orders, ordered from earliest settlement date to latest

Transaction Builder

begin_builder_transaction

Create a new transaction builder.

Handle of the new transaction builder.

add_operation_to_builder_transaction

Append a new operation to a transaction builder.

transaction_handle: handle of the transaction builder
op: the operation in JSON format

replace_operation_in_builder_transaction

Replace an operation in a transaction builder with a new operation.

handle: handle of the transaction builder
operation_index: the index of the old operation in the builder to be replaced
new_op: the new operation in JSON format

set_fees_on_builder_transaction

Calculate and update fees for the operations in a transaction builder.

handle: handle of the transaction builder
fee_asset: name or ID of an asset that to be used to pay fees

Total fees.

preview_builder_transaction

Show content of a transaction builder.

handle: handle of the transaction builder

A transaction.

sign_builder_transaction

Sign the transaction in a transaction builder and optionally broadcast to the network.

transaction_handle: handle of the transaction builder
broadcast: whether to broadcast the signed transaction to the network

A signed transaction.

propose_builder_transaction

Create a proposal containing the operations in a transaction builder (create a new proposal_create operation, then replace the transaction builder with the new operation), then sign the transaction and optionally broadcast to the network.

handle: handle of the transaction builder
expiration: when the proposal will expire
review_period_seconds: review period of the proposal in seconds
broadcast: whether to broadcast the signed transaction to the network

A signed transaction.

propose_builder_transaction2

handle: handle of the transaction builder
account_name_or_id: name or ID of the account who would pay fees for creating the proposal
expiration: when the proposal will expire
review_period_seconds: review period of the proposal in seconds
broadcast: whether to broadcast the signed transaction to the network

A signed transaction.

remove_builder_transaction

Destroy a transaction builder.

handle: handle of the transaction builder

serialize_transaction

Converts a signed_transaction in JSON form to its binary representation.

tx: the transaction to serialize

The binary form of the transaction. It will not be hex encoded, this returns a raw string that may have null characters embedded in it

sign_transaction

Signs a transaction.

Given a fully-formed transaction that is only lacking signatures, this signs the transaction with the necessary keys and optionally broadcasts the transaction.

tx: the unsigned transaction
broadcast: true if you wish to broadcast the transaction

The signed version of the transaction

get_prototype_operation

Returns an uninitialized object representing a given blockchain operation.

This returns a default-initialized object of the given type; it can be used during early development of the wallet when we don’t yet have custom commands for creating all of the operations the blockchain supports.

operation_type: the type of operation to return, must be one of the operations defined in graphene/protocol/operations.hpp (e.g., “global_parameters_update_operation”)

A default-constructed operation of the given type.

Wallet Calls

is_new

Checks whether the wallet has just been created and has not yet had a password set.

Calling set_password will transition the wallet to the locked state.

True if the wallet is new.

is_locked

Checks whether the wallet is locked (is unable to use its private keys).

True if the wallet is locked

lock

Locks the wallet immediately.

unlock

Unlocks the wallet.

The wallet remain unlocked until the lock is called or the program exits.

When used in command line, if typed “unlock” without a password followed, the user will be prompted to input a password without echo.

set_password

Sets a new password on the wallet.

The wallet must be either ‘new’ or ‘unlocked’ to execute this command.

When used in command line, if typed “set_password” without a password followed, the user will be prompted to input a password without echo.

password: a new password

dump_private_keys

Dumps all private keys owned by the wallet.

A _**_map containing the private keys, indexed by their public key

import_key

Imports the private key for an existing account.

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

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

true if the key was imported

import_accounts

Imports accounts from a BitShares 0.x wallet file. Current wallet file must be unlocked to perform the import.

filename: the BitShares 0.x wallet file to import
password: the password to encrypt the BitShares 0.x wallet file

A map containing the accounts found and whether imported.

import_account_keys

Imports from a BitShares 0.x wallet file, find keys that were bound to a given account name on the BitShares 0.x chain, rebind them to an account name on the 2.0 chain. Current wallet file must be unlocked to perform the import.

filename: the BitShares 0.x wallet file to import
password: the password to encrypt the BitShares 0.x wallet file
src_account_name: name of the account on BitShares 0.x chain
dest_account_name: name of the account on BitShares 2.0 chain, can be same or different to src_account_name

Whether the import has succeeded

import_balance

This call will construct transaction(s) that will claim all balances controlled by wif_keys and deposit them into the given account.

account_name_or_id: name or ID of an account that to claim balances to
wif_keys: private WIF keys of balance objects to claim balances from
broadcast: true to broadcast the transaction on the network

suggest_brain_key

This function will suggest a suitably random string that should be easy to write down (and, with effort, memorize).

A suggested brain_key

get_transaction_id

This method is used to convert a JSON transaction to its transacting ID.

trx: a JSON transaction

The ID (hash) of the transaction.

get_private_key

Get the WIF private key corresponding to a public key. The private key must already be in the wallet.

pubkey: a public key in Base58 format

The WIF private key

load_wallet_file

Loads a specified Graphene wallet.

The current wallet is closed before the new wallet is loaded.

Important: This does not change the filename that will be used for future wallet writes, so this may cause you to overwrite your original wallet unless you also call set_wallet_filename()

wallet_filename: the filename of the wallet JSON file to load. If wallet_filename is empty, it reloads the existing wallet file.

True if the specified wallet is loaded.

normalize_brain_key

Transforms a brain key to reduce the chance of errors when re-entering the key from memory.

This takes a user-supplied brain key and normalizes it into the form used for generating private keys. In particular, this upper-cases all ASCII characters and collapses multiple spaces into one.

s: the brain key as supplied by the user

The brain key in its normalized form.

save_wallet_file

Saves the current wallet to the given filename.

Important: This does not change the wallet filename that will be used for future writes, so think of this function as ‘Save a Copy As…’ instead of ‘Save As…’. Use set_wallet_filename() to make the filename persist.

wallet_filename: the filename of the new wallet JSON file to create or overwrite. If wallet_filename is empty, save to the current filename.

Bookie API

Listeners

subscribe_to_market

Subscribe a listener to a betting market.

updateListener: An object of type updateListener.
1.3.0: Start version.
1.3.19: End version.

unsubscribe_from_market

Unsubscribe a listener from a betting market.

updateListener: An object of type updateListener.
1.3.0: Start version.
1.3.19: End version.

Peerplays API Libraries

Python Peerplays

Introduction

Its the Python library for communicating with the Peerplays blockchain.

Ids

1.2.x : accounts

1.3.x : assets

Notes

p.rpc.get_account_balances("jemshid", [])

p.rpc.get_global_properties

private-key = ["TEST6MRyAjQq8ud7hVNYcfnVPJqcVpscN5So8BhtHuGYqET5GDW5CV","5KQwrPbwdL6PhXujxW37FSSQZ1JiwsST4cqQzDeyXtP79zkvFD3"]

Development Guides

The Cookbook

Tools and Integrations

PeerID

Random Number Generator

Supporting & Reference Docs

Sidechain Operator Node (SON) Development

Generic Sidechain Docs

Low Level Designs

This section contains pages that describe low level design

Database API

The database API is available from the full node via web-sockets.

Objects

get_objects

Get the objects corresponding to the provided IDs.

If any of the provided IDs does not map to an object, a null variant is returned in its position.

fc::variants graphene::app::database_api::get_objects(
    const vector<object_id_type> &ids, 
    optional<bool> subscribe = optional<bool>())const

ids: IDs of the objects to retrieve
subscribe: true to subscribe to the queried objects; false to not subscribe; null to subscribe or not subscribe according to current auto-subscription setting (see )

The objects retrieved, in the order they are mentioned in ids.

Subscriptions

set_subscribe_callback

Note: auto-subscription is enabled by default and can be disabled with

void graphene::app::database_api::set_subscribe_callback(
    std::function<void(const variant&)> cb, 
    bool notify_remove_create, )

cb: The callback handle to register
notify_remove_create: Whether subscribe to universal object creation and removal events. If this is set to true, the API server will notify all newly created objects and ID of all newly removed objects to the client, no matter whether client subscribed to the objects. By default, API servers don’t allow subscribing to universal events, which can be changed on server startup.

set_pending_transaction_callback

void graphene::app::database_api::set_pending_transaction_callback(
    std::function<void(const variant &signed_transaction_object)> cb)

cb: The callback handle to register

set_block_applied_callback

void graphene::app::database_api::set_block_applied_callback(
    std::function<void(const variant &block_id)> cb)

cb: The callback handle to register

cancel_all_subscriptions

Stop receiving any notifications.

This unsubscribes from all subscribed markets and objects.

void graphene::app::database_api::cancel_all_subscriptions()

Blocks and transactions

get_block_header

Retrieve a block header.

optional<block_header> graphene::app::database_api::get_block_header(
    uint32_t block_num)const

block_num: Height of the block whose header should be returned

The header of the referenced block, or null if no matching block was foun

get_block

Retrieve a full, signed block.

optional<signed_block> graphene::app::database_api::get_block(
    uint32_t block_num)const

block_num: Height of the block to be returned

The referenced block, or null if no matching block was found.

get_transaction

Fetch an individual transaction.

processed_transaction graphene::app::database_api::get_transaction(
    uint32_t block_num, uint32_t trx_in_block)const

block_num: height of the block to fetch
trx_in_block: the index (sequence number) of the transaction in the block, starts from 0

The transaction at the given position.

get_recent_transaction_by_id

optional<signed_transaction> graphene::app::database_api::get_recent_transaction_by_id(
    const transaction_id_type &txid)const

txid: hash of the transaction

The corresponding transaction if found, or null if not found.

Globals

get_chain_properties

Retrieve the associated with the chain.

chain_property_object graphene::app::database_api::get_chain_properties()const

get_global_properties

Retrieve the current .

global_property_object graphene::app::database_api::get_global_properties()const

get_config

Retrieve compile-time constants.

fc::variant_object graphene::app::database_api::get_config()const

get_chain_id

Get the chain ID.

chain_id_type graphene::app::database_api::get_chain_id()cons

get_dynamic_global_properties

Retrieve the current .

dynamic_global_property_object graphene::app::database_api::get_dynamic_global_properties()const

Keys

get_key_references

Get all accounts that refer to the specified public keys in their owner authority, active authorities or memo key.

vector<flat_set<account_id_type>> graphene::app::database_api::get_key_references(
    vector<public_key_type> keys)const

keys: a list of public keys to query

ID of all accounts that refer to the specified keys.

Accounts

get_accounts

Get a list of accounts by names or IDs.

This function has semantics identical to ****

vector<optional<account_object>> graphene::app::database_api::get_accounts(
    const vector<std::string> &account_names_or_ids, 
    optional<bool> subscribe = optional<bool>())const

account_names_or_ids: names or IDs of the accounts to retrieve
subscribe: true to subscribe to the queried account objects; false to not subscribe; null to subscribe or not subscribe according to current auto-subscription setting (see )

The accounts corresponding to the provided names or IDs.

get_full_accounts

Fetch all objects relevant to the specified accounts and optionally subscribe to updates.

std::map<string, full_account> graphene::app::database_api::get_full_accounts(
    const vector<string> &names_or_ids, 
    optional<bool> subscribe = optional<bool>())

names_or_ids: Each item must be the name or ID of an account to retrieve
subscribe: true to subscribe to the queried full account objects; false to not subscribe; null to subscribe or not subscribe according to current auto-subscription setting (see )

Map of string from names_or_ids to the corresponding account.

get_account_by_name

Get info of an account by name.

optional<account_object> graphene::app::database_api::get_account_by_name(
    string name)const

name: Name of the account to retrieve

The account holding the provided name.

get_account_references

Get all accounts that refer to the specified account in their owner or active authorities.

vector<account_id_type> graphene::app::database_api::get_account_references(
    const std::string account_name_or_id)const

account_name_or_id: Account name or ID to query

All accounts that refer to the specified account in their owner or active authorities

lookup_account_names

Get a list of accounts by name.

This function has semantics identical to, but doesn’t subscribe

vector<optional<account_object>> graphene::app::database_api::lookup_account_names(
    const vector<string> &account_names)const

account_names: Names of the accounts to retrieve

The accounts holding the provided names.

lookup_accounts

Get names and IDs for registered accounts.

Note: In addition to the common auto-subscription rules, this API will subscribe to the returned account only if limit is 1.

map<string, account_id_type> graphene::app::database_api::lookup_accounts(
    const string &lower_bound_name, 
    uint32_t limit, 
    optional<bool> subscribe = optional<bool>())const

lower_bound_name: Lower bound of the first name to return
limit: Maximum number of results to return must not exceed 1000
subscribe: true to subscribe to the queried account objects; false to not subscribe; null to subscribe or not subscribe according to current auto-subscription setting (see ).

Map of account names to corresponding IDs.

get_account_count

Get the total number of accounts registered with the blockchain.

uint64_t graphene::app::database_api::get_account_count()const

Balances

get_account_balances

Get an account’s balances in various assets.

vector<asset> graphene::app::database_api::get_account_balances(
    const std::string &account_name_or_id, 
    const flat_set<asset_id_type> &assets)const

account_name_or_id: name or ID of the account to get balances for.
assets: IDs of the assets to get balances of; if empty, get all assets account has a balance in.

Balances of the account.

get_named_account_balances

Semantically equivalent to .

vector<asset> graphene::app::database_api::get_named_account_balances(
    const std::string &name, 
    const flat_set<asset_id_type> &assets)const

account_name_or_id: name or ID of the account to get balances for.
assets: IDs of the assets to get balances of; if empty, get all assets account has a balance in.

Balances of the account.

get_balance_objects

vector<balance_object> graphene::app::database_api::get_balance_objects(
    const vector<address> &addrs)const

addrs: a list of addresses

All unclaimed balance objects for the addresses.

get_vested_balances

Calculate how much assets in the given balance objects are able to be claimed at current head block time.

vector<asset> graphene::app::database_api::get_vested_balances(
    const vector<balance_id_type> &objs)const

objs: a list of balance object IDs

A list indicating how much asset in each balance object is available to be claimed.

get_vesting_balances

Return all vesting balance objects owned by an account.

vector<vesting_balance_object> graphene::app::database_api::get_vesting_balances(
    const std::string account_name_or_id)const

account_name_or_id: name or ID of an account

All vesting balance objects owned by the account.

Assets

get_assets

Get a list of assets by symbol names or IDs.

Semantically equivalent to .

vector<optional<extended_asset_object>> graphene::app::database_api::get_assets(
    const vector<std::string> &asset_symbols_or_ids, 
    optional<bool> subscribe = optional<bool>())const

asset_symbols_or_ids: symbol names or IDs of the assets to retrieve
subscribe: true to subscribe to the queried asset objects; false to not subscribe; null to subscribe or not subscribe according to current auto-subscription setting (see )

The assets corresponding to the provided symbol names or IDs.

list_assets

Get assets alphabetically by symbol name.

vector<extended_asset_object> graphene::app::database_api::list_assets(
    const string &lower_bound_symbol, 
    uint32_t limit)const

lower_bound_symbol: Lower bound of symbol names to retrieve
limit: Maximum number of assets to fetch (must not exceed 101)

The assets found.

lookup_asset_symbols

Get a list of assets by symbol names or IDs.

Semantically equivalent to , but doesn’t subscribe.

vector<optional<extended_asset_object>> graphene::app::database_api::lookup_asset_symbols(
    const vector<string> &symbols_or_ids)const

symbols_or_ids: symbol names or IDs of the assets to retrieve

The assets corresponding to the provided symbols or IDs

Markets / Feeds

get_order_book

Returns the order book for the market base

order_book graphene::app::database_api::get_order_book(
    const string &base, 
    const string &quote, 
    unsigned limit = 50)const

base: symbol name or ID of the base asset
quote: symbol name or ID of the quote asset
limit: depth of the order book to retrieve, for bids and asks each, capped at 50

Order book of the market.

get_limit_orders

Get limit orders in a given market.

vector<limit_order_object> graphene::app::database_api::get_limit_orders(
    std::string a, 
    std::string b, 
    uint32_t limit)const

a: symbol or ID of asset being sold
b: symbol or ID of asset being purchased
limit: Maximum number of orders to retrieve

The limit orders, ordered from least price to greatest.

get_call_orders

Get call orders (aka margin positions) for a given asset.

vector<call_order_object> graphene::app::database_api::get_call_orders(
    const std::string &a, 
    uint32_t limit)const

a: symbol name or ID of the debt asset
limit: Maximum number of orders to retrieve

The call orders, ordered from earliest to be called to latest

get_settle_orders

Get forced settlement orders in a given asset.

vector<force_settlement_object> graphene::app::database_api::get_settle_orders(
    const std::string &a, 
    uint32_t limit)const

a: Symbol or ID of asset being settled
limit: Maximum number of orders to retrieve

The settle orders, ordered from earliest settlement date to latest.

get_margin_positions

Get all open margin positions of a given account.

Similar to , but without pagination.

vector<call_order_object> graphene::app::database_api::get_margin_positions(
    const std::string account_name_or_id)const

account_name_or_id: name or ID of an account

All open margin positions of the account.

subscribe_to_market

Request notification when the active orders in the market between two assets changes.

Callback will be passed a variant containing a vector<pair<operation, operation_result>>.

The vector will contain, in order, the operations which changed the market, and their results

void graphene::app::database_api::subscribe_to_market(std::function<void(
    const variant&)> callback, 
    const std::string &a, 
    const std::string &b, )

callback: Callback method which is called when the market changes
a: symbol name or ID of the first asset
b: symbol name or ID of the second asset

unsubscribe_from_market

Unsubscribe from updates to a given market.

void graphene::app::database_api::unsubscribe_from_market(
    const std::string &a, 
    const std::string &b)

a: symbol name or ID of the first asset
b: symbol name or ID of the second asset

get_ticker

Returns the ticker for the market assetA:assetB.

market_ticker graphene::app::database_api::get_ticker(
    const string &base, 
    const string &quote)const

base: symbol name or ID of the base asset
quote: symbol name or ID of the quote asset

The market ticker for the past 24 hours.

get_24_volume

Returns the 24 hour volume for the market assetA:assetB.

market_volume graphene::app::database_api::get_24_volume(
    const string &base, 
    const string &quote)const

base: symbol name or ID of the base asset
quote: symbol name or ID of the quote asset

The market volume over the past 24 hours.

get_trade_history

Returns recent trades for the market base:quote, ordered by time, most recent first.

Note: Currently, timezone offsets are not supported. The time must be UTC.

The range is [stop, start). In case there are more than 100 trades occurring in the same second, this API only returns the first 100 records; use to query for the rest.

vector<market_trade> graphene::app::database_api::get_trade_history(
    const string &base, 
    const string &quote, 
    fc::time_point_sec start, 
    fc::time_point_sec stop, 
    unsigned limit = 100)const

base: symbol or ID of the base asset
quote: symbol or ID of the quote asset
start: Start time as a UNIX timestamp, the latest trade to retrieve
stop: Stop time as a UNIX timestamp, the earliest trade to retrieve
limit: Number of transactions to retrieve, capped at 100.

Recent transactions in the market

Witnesses

get_witnesses

Get a list of witnesses by ID.

Semantically equivalent to , but doesn’t subscribe.

vector<optional<witness_object>> graphene::app::database_api::get_witnesses(
    const vector<witness_id_type> &witness_ids)const

witness_ids: IDs of the witnesses to retrieve

The witnesses corresponding to the provided IDs.

get_witness_by_account

Get the witness owned by a given account.

fc::optional<witness_object> graphene::app::database_api::get_witness_by_account(
    const std::string account_name_or_id)const

account_name_or_id: The name or ID of the account whose witness should be retrieved

The witness object, or null if the account does not have a witness.

lookup_witness_accounts

Get names and IDs for registered witnesses.

map<string, witness_id_type> graphene::app::database_api::lookup_witness_accounts(
    const string &lower_bound_name, uint32_t limit)const

lower_bound_name: Lower bound of the first name to return
limit: Maximum number of results to return must not exceed 1000

Map of witness names to corresponding IDs.

get_witness_count

Get the total number of witnesses registered with the blockchain.

uint64_t graphene::app::database_api::get_witness_count()const

Committee members

get_committee_members

Get a list of committee_members by ID.

Semantically equivalent to , but doesn’t subscribe.

vector<optional<committee_member_object>> graphene::app::database_api::get_committee_members(
    const vector<committee_member_id_type> &committee_member_ids)const

committee_member_ids: IDs of the committee_members to retrieve

The committee_members corresponding to the provided IDs.

get_committee_member_by_account

Get the committee_member owned by a given account.

fc::optional<committee_member_object> graphene::app::database_api::get_committee_member_by_account(
    const string account_name_or_id)const

account_name_or_id: The name or ID of the account whose committee_member should be retrieved

The committee_member object, or null if the account does not have a committee_member.

lookup_committee_member_accounts

Get names and IDs for registered committee_members.

map<string, committee_member_id_type> graphene::app::database_api::lookup_committee_member_accounts(
    const string &lower_bound_name, 
    uint32_t limit)const

lower_bound_name: Lower bound of the first name to return
limit: Maximum number of results to return must not exceed 1000

Map of committee_member names to corresponding IDs

Workers

get_workers_by_account

Get the workers owned by a given account.

vector<optional<worker_object>> graphene::app::database_api::get_workers_by_account(
    const std::string account_name_or_id)const

account_name_or_id: The name or ID of the account whose worker should be retrieved

A list of worker objects owned by the account.

Votes

lookup_vote_ids

Given a set of votes, returns the objects they are voting for.

This will be a mixture of committee_member_objects, witness_objects, and worker_objects

vector<variant> graphene::app::database_api::lookup_vote_ids(
    const vector<vote_id_type> &votes)const

votes: a list of vote IDs

The referenced objects

The results will be in the same order as the votes. Null will be returned for any vote IDs that are not found.

Authority / Validation

get_transaction_hex

Get a hexdump of the serialized binary form of a transaction.

std::string graphene::app::database_api::get_transaction_hex(
    const signed_transaction &trx)const

trx: a transaction to get hexdump from

The hexdump of the transaction.

get_required_signatures

set<public_key_type> graphene::app::database_api::get_required_signatures(
    const signed_transaction &trx, 
    const flat_set<public_key_type> &available_keys)const

trx: the transaction to be signed
available_keys: a set of public keys

A subset of available_keys that could sign for the given transaction.

get_potential_signatures

This method will return the set of all public keys that could possibly sign for a given transaction. This call can be used by wallets to filter their set of public keys to just the relevant subset prior to calling to get the minimum subset.

set<public_key_type> graphene::app::database_api::get_potential_signatures(
    const signed_transaction &trx)const

trx: the transaction to be signed

A set of public keys that could possibly sign for the given transaction.

get_potential_address_signatures

This method will return the set of all addresses that could possibly sign for a given transaction.

set<address> graphene::app::database_api::get_potential_address_signatures(
    const signed_transaction &trx)const

trx: the transaction to be signed

A set of addresses that could possibly sign for the given transaction.

verify_authority

Check whether a transaction has all of the required signatures

bool graphene::app::database_api::verify_authority(
    const signed_transaction &trx)const

trx: a transaction to be verified

true if the trx has all of the required signatures, otherwise throws an exception.

verify_account_authority

Verify that the public keys have enough authority to approve an operation for this account.

bool graphene::app::database_api::verify_account_authority(
    const string &account_name_or_id, 
    const flat_set<public_key_type> &signers)const

account_name_or_id: name or ID of an account to check
signers: the public keys

true if the passed in keys have enough authority to approve an operation for this account.

validate_transaction

Validates a transaction against the current state without broadcasting it on the network.

processed_transaction graphene::app::database_api::validate_transaction(
const signed_transaction &trx)const

trx: a transaction to be validated

A processed_transaction object if the transaction passes the validation, otherwise an exception will be thrown.

get_required_fees

For each operation calculate the required fee in the specified asset type.

vector<fc::variant> graphene::app::database_api::get_required_fees(
    const vector<operation> &ops, 
    const std::string &asset_symbol_or_id)const

ops: a list of operations to be query for required fees
asset_symbol_or_id: symbol name or ID of an asset that to be used to pay the fees

A **list of objects which indicates required fees of each operation

Proposed Transactions

get_proposed_transactions

Gets a set of proposed transactions (proposals) that the specified account can add approval to or remove approval from.

vector<proposal_object> graphene::app::database_api::get_proposed_transactions(
    const std::string account_name_or_id)const

account_name_or_id: The name or ID of an account

A set of proposed transactions that the specified account can act on.

Blinded balances

get_blinded_balances

Gets the set of blinded balance objects by commitment ID.

vector<blinded_balance_object> graphene::app::database_api::get_blinded_balances(
    const flat_set<commitment_type> &commitments)const

commitments: a set of commitments to query for

The set of blinded balance objects by commitment ID.

Introduction to Permissions

A brief explanation of role-based & resource permissions for Peerplays objects.

1. Types of Permissions in Peerplays

There are three functions available in the CLI Wallet to produce permission settings:

create_custom_permission
create_custom_account_authority
create_account_role

The first two functions deal with creating Hierarchical Role-based Permissions (HRP). The third is used to provide resource permissions with account roles.

HRP is a feature of the Peerplays blockchain which helps to increase the security of user accounts. Users don’t have to use their active and owner keys for everything they do on the chain. Instead, they can create role based custom permissions and map them to different keys other than active and owner keys. They can then use these custom keys to sign transactions.

As opposed to HRP mentioned above, resource permissions are controlled by the owner of a resource (such as NFT metadata). These are similar to IAM permissions in an AWS Cloud environment.

2. Hierarchical Role-based Permissions (HRP)

To create a custom HRP, the first step is to create the custom permission. Then the custom permission will be mapped to the actual operations present on the blockchain by creating a related custom account authority.

Some of the following functions need Operation IDs. You can find a list of Operation IDs here.

2.1. create_custom_permission

This function creates a new custom permission.

return type, namespace, & method

signed_transaction graphene::wallet::wallet_api::create_custom_permission(
    string owner, 
    string permission_name, 
    authority auth, 
    bool broadcast)

The basic structure of the create_custom_permission function looks like this:

When using the cli_wallet...

create_custom_permission <owner> <permission_name> <auth> true

Parameters

name

data type

description

details

owner

string

The name or id of the account who is creating the permission.

n/a

permission_name

string

The name of the permission.

n/a

auth

authority

This is a JSON object which describes an account authority. See below for details.

a JSON object

broadcast

bool

true or false, whether or not you want to broadcast the transaction.

n/a

The auth parameter is a JSON object which looks like this:

{
  "weight_threshold": 1,
  "account_auths": [["1.2.52",1]],
  "key_auths": [["TEST71ADtL4fzjGKErk9nQJrABmCPUR8QCjkCUNfdmgY5yDzQGhwto",1]],
  "address_auths": []
}

This represents an authority structure, account_auths represents the amount of weight each account has on our account, in this example 1.2.52 has a weight of 1.

key_auths represents the amount of weight each public key has on this account, in this example TEST71ADtL4fzjGKErk9nQJrABmCPUR8QCjkCUNfdmgY5yDzQGhwto has a weight of 1.

weight_threshold represents the required weight for a transaction to be signed successfully.

In this example, either 1.2.52 can sign with their active key or TEST71ADtL4fzjGKErk9nQJrABmCPUR8QCjkCUNfdmgY5yDzQGhwto can be used to sign a transaction successfully because they each have a weight of 1, and only 1 is required by the threshold.

Example Call

create_custom_permission account01 perm1 { "weight_threshold": 1,  "account_auths": [["1.2.52",1]], "key_auths": [["TEST71ADtL4fzjGKErk9nQJrABmCPUR8QCjkCUNfdmgY5yDzQGhwto",1]], "address_auths": [] } true

2.2. get_custom_permissions

This function returns the custom permissions that have been created by the given account.

return type, namespace, & method

signed_transaction graphene::wallet::wallet_api::get_custom_permissions(
    string owner)

The basic structure of the get_custom_permission function looks like this:

When using the cli_wallet...

get_custom_permissions <owner>

Parameters

name

data type

description

details

owner

string

The name or id of the account for which we'd like to see the list of created custom permissions.

n/a

Example Call

get_custom_permissions account01

2.3. update_custom_permission

This function updates an existing permission with the new authority object that you supply.

return type, namespace, & method

signed_transaction graphene::wallet::wallet_api::update_custom_permission(
    string owner,
    custom_permission_id_type permission_id,
    fc::optional<authority> new_auth,
    bool broadcast)

The basic structure of the update_custom_permission function looks like this:

When using the cli_wallet...

update_custom_permissions <owner> <permission_id> <new_auth> true

Parameters

name

data type

description

details

owner

string

The name or id of the account who is updating the permission.

n/a

permission_id

custom_permission_id_type

The ID of the custom permission we're intending to edit.

n/a

new_auth

authority

n/a

broadcast

bool

true or false, whether or not you want to broadcast the transaction.

n/a

Example Call

update_custom_permission account01 1.27.0 { "weight_threshold": 1,  "account_auths": [["1.2.53",1]], "key_auths": [], "address_auths": [] } true

Here we removed the key_auths and added 1.2.53 with weight 1, which is equal to weight_threshold , so 1.2.53 can alone sign the transaction successfully.

The new authority object will replace the old authority object using this function call. Make sure that the authority object that you supply here is set exactly as you'd like.

2.4. create_custom_account_authority

Creating a custom authority maps the created custom permissions with the actual operations present on the blockchain. It also has expiry time by when this custom permission is no longer valid on any given account and operation combination.

return type, namespace, & method

signed_transaction graphene::wallet::wallet_api::create_custom_account_authority(
    string owner,
    custom_permission_id_type permission_id,
    int operation_type,
    fc::time_point_sec valid_from,
    fc::time_point_sec valid_to,
    bool broadcast)

The basic structure of the create_custom_account_authority function looks like this:

When using the cli_wallet...

create_custom_account_authority <owner> <permission_id> <operation_type> <valid_from> <valid_to> true

Parameters

name

data type

description

details

owner

string

The name or id of the account who is creating the account authority.

n/a

permission_id

custom_permission_id_type

The ID of the custom permission we're intending to edit.

n/a

operation_type

int

n/a

valid_from

time_point_sec

The timestamp when the permission begins to be valid. See below for what a valid timestamp looks like.

n/a

valid_to

time_point_sec

The timestamp when the permission stops being valid. See below for what a valid timestamp looks like.

n/a

broadcast

bool

true or false, whether or not you want to broadcast the transaction.

n/a

A valid timestamp looks like this: "2019-11-22T18:30:00"

Example Call

create_custom_account_authority account01 1.27.0 0 "2019-11-22T18:30:00" "2020-12-03T17:53:25" true

Basically this represents a full HRP where the transfer operation on account01 can be done by authorities present in 1.27.0 instead of account owner account01.

2.5. update_custom_account_authority

This function can be used to update existing valid_from and valid_to times.

return type, namespace, & method

signed_transaction graphene::wallet::wallet_api::update_custom_account_authority(
    string owner,
    custom_account_authority_id_type auth_id,
    fc::optional<fc::time_point_sec> new_valid_from,
    fc::optional<fc::time_point_sec> new_valid_to,
    bool broadcast)

The basic structure of the update_custom_account_authority function looks like this:

When using the cli_wallet...

update_custom_account_authority <owner> <auth_id> <new_valid_from> <new_valid_to> true

Parameters

name

data type

description

details

owner

string

The name or id of the account who is updating the account authority.

n/a

auth_id

custom_account_authority_id_type

The ID of the custom account authority we're intending to edit.

n/a

new_valid_from

time_point_sec

The timestamp when the permission begins to be valid. See below for what a valid timestamp looks like.

n/a

new_valid_to

time_point_sec

The timestamp when the permission stops being valid. See below for what a valid timestamp looks like.

n/a

broadcast

bool

true or false, whether or not you want to broadcast the transaction.

n/a

A valid timestamp looks like this: "2019-11-22T18:30:00"

Example Call

update_custom_account_authority account01 1.28.0 "2020-06-02T17:52:25" "2020-06-03T17:52:25" true

2.6. delete_custom_permission

This function is used to delete an existing custom permission.

This will delete all the custom account authorities linked to this permission as well.

A cascading delete!

return type, namespace, & method

signed_transaction graphene::wallet::wallet_api::delete_custom_permission(
    string owner,
    custom_permission_id_type permission_id,
    bool broadcast)

The basic structure of the delete_custom_permission function looks like this:

When using the cli_wallet...

delete_custom_permission <owner> <permission_id> true

Parameters

name

data type

description

details

owner

string

The name or id of the account who is deleting the permission.

n/a

permission_id

custom_permission_id_type

The ID of the custom permission we're intending to delete.

n/a

broadcast

bool

true or false, whether or not you want to broadcast the transaction.

n/a

Example Call

delete_custom_permission account01 1.27.0 true

2.7. delete_custom_account_authority

This function is used to delete an account authority attached to a permission.

return type, namespace, & method

signed_transaction graphene::wallet::wallet_api::delete_custom_account_authority(
    string owner,
    custom_account_authority_id_type auth_id,
    bool broadcast)

The basic structure of the delete_custom_account_authority function looks like this:

When using the cli_wallet...

delete_custom_account_authority <owner> <auth_id> true

Parameters

name

data type

description

details

owner

string

The name or id of the account who is deleting the account authority.

n/a

auth_id

custom_account_authority_id_type

The ID of the custom account authority we're intending to delete.

n/a

broadcast

bool

true or false, whether or not you want to broadcast the transaction.

n/a

Example Call

delete_custom_account_authority account01 1.28.0 true

3. Resource Permissions with Account Roles

Resource permissions can be granted by applying account roles to those resources. The allowed permissions are attached to the role. Then accounts can be added to the role to grant them the permissions the role provides.

Some of the following functions need Operation IDs. You can find a list of Operation IDs here.

3.1. create_account_role

This function creates an account role.

return type, namespace, & method

signed_transaction graphene::wallet::wallet_api::create_account_role(
    string owner_account_id_or_name,
    string name,
    string metadata,
    flat_set<int> allowed_operations,
    flat_set<account_id_type> whitelisted_accounts,
    time_point_sec valid_to,
    bool broadcast)

The basic structure of the create_account_role function looks like this:

When using the cli_wallet...

create_account_role <owner_account_id_or_name> <name> <metadata> <allowed_operations> <whitelisted_accounts> <valid_to> true

Parameters

name

data type

description

details

owner_account_id_or_name

string

The name or id of the account who is creating the account role.

n/a

name

string

The name of the account role. For example, "Movie Interstellar Permissions"

n/a

metadata

string

Metadata for additional info. For example, this could be a JSON object or and external URL with info.

n/a

allowed_operations

flat_set<int>

n/a

whitelisted_accounts

flat_set<account_id_type>

An array of account IDs for the accounts that belong to this role and are therefore granted the allowed_operations for the resource.

n/a

valid_to

time_point_sec

The time at which the role no longer provides the allowed_operations to its whitelisted_accounts.

Note: valid_from is automatically set to the time the account role was created.

n/a

broadcast

bool

true or false, whether or not you want to broadcast the transaction.

n/a

A valid timestamp looks like this: "2020-09-04T13:43:39"

Example Call

create_account_role account01 ar1 ar1 [89,95] [1.2.40, 1.2.41, 1.2.43] "2020-09-04T13:43:39" true

This command effectively limits any NFT to be sold or transferred between only three accounts, 1.2.40, 1.2.41, and 1.2.43.

3.2. get_account_roles_by_owner

You can use this to find all the account roles by their owner.

return type, namespace, & method

signed_transaction graphene::wallet::wallet_api::get_account_roles_by_owner(
    string owner_account_id_or_name)

The basic structure of the get_account_roles_by_owner function looks like this:

When using the cli_wallet...

get_account_roles_by_owner <owner_account_id_or_name>

Parameters

name

data type

description

details

owner_account_id_or_name

string

The name or id of the account for which we'd like to see the list of created account roles.

n/a

Example Call

get_account_roles_by_owner account01

3.3. update_account_role

As a resource owner, you can update the operations and whitelisted accounts present in an account role. This helps in blacklisting any users from selling or transferring NFTs or any resources.

return type, namespace, & method

signed_transaction graphene::wallet::wallet_api::update_account_role(
    string owner_account_id_or_name,
    account_role_id_type role_id,
    optional<string> name,
    optional<string> metadata,
    flat_set<int> operations_to_add,
    flat_set<int> operations_to_remove,
    flat_set<account_id_type> accounts_to_add,
    flat_set<account_id_type> accounts_to_remove,
    optional<time_point_sec> valid_to,
    bool broadcast)

The basic structure of the update_account_role function looks like this:

When using the cli_wallet...

update_account_role <owner_account_id_or_name> <role_id> <name> <metadata> <operations_to_add> <operations_to_remove> <accounts_to_add> <accounts_to_remove> <valid_to> true

Parameters

name

data type

description

details

owner_account_id_or_name

string

The name or id of the account who is updating the account role.

n/a

role_id

account_role_id_type

The ID of the account role we're intending to update.

n/a

name

string

The name of the account role. For example, "Movie Interstellar Permissions"

n/a

metadata

string

Metadata for additional info. For example, this could be a JSON object or and external URL with info.

n/a

operations_to_add

flat_set<int>

n/a

operations_to_remove

flat_set<int>

n/a

accounts_to_add

flat_set<account_id_type>

An array of account IDs for the accounts that should be added to the role.

n/a

accounts_to_remove

flat_set<account_id_type>

An array of account IDs for the accounts that should be removed from the role.

n/a

valid_to

time_point_sec

The time at which the role no longer provides the allowed_operations to its whitelisted_accounts.

Note: valid_from is automatically set to the time the account role was created.

n/a

broadcast

bool

true or false, whether or not you want to broadcast the transaction.

n/a

A valid timestamp looks like this: "2020-09-04T13:43:39"

Example Call

update_account_role account01 1.32.0 null null [88] [95] [1.2.42] [1.2.40] "2020-09-04T13:52:38" true

88 offer_operation is added.

95 nft_safe_transfer_from_operation is removed.

1.2.42 account is added to the whitelist.

1.2.40 account is removed from the whitelist.

3.4. delete_account_role

This function deletes an account role.

Once an account role is deleted, restrictions on resource access no longer work!

return type, namespace, & method

signed_transaction graphene::wallet::wallet_api::delete_account_role(
    string owner_account_id_or_name,
    account_role_id_type role_id,
    bool broadcast)

The basic structure of the delete_account_role function looks like this:

When using the cli_wallet...

delete_account_role <owner_account_id_or_name> <role_id> true

Parameters

name

data type

description

details

owner_account_id_or_name

string

The name or id of the account who is deleting the account role.

n/a

role_id

account_role_id_type

The ID of the account role we're intending to delete.

n/a

broadcast

bool

true or false, whether or not you want to broadcast the transaction.

n/a

Example Call

delete_account_role account01 1.32.0 true

The functions listed in this guide will cost transaction fees. To calculate how much PPY you'll need to make these transactions and meet your development goals, please see the Calculating Costs guide.

son-consensus-communication-and-transaction-signing-on-chain-lld

1.Purpose

The purpose of this document is to provide low-level design for the communication mechanism between SONs and transaction signing.

2. Scope

The design requirement listed in this document will be limited to the communication, consensus and transaction signing of SONs on-chain.

The document also proposes a design to create a way to know the health of an active SON.

The document takes only the Bitcoin sidechain into consideration as of this writing but can be extended to others in the future.

The document doesn’t deal with sidechain deposit handling or withdrawal.

The assumption is that we use a single PW design without creating deposit addresses.

Note1: For the simplicity of the examples, let's assume we have 3 SONs.

Note2: Code snippets provided in the document are pseudo-codes, they just illustrate basic logic and may not be syntactically correct.

2.1 Glossary

Consensus-SON: Top 2/3rd active SONs who signs transactions on behalf of the 15 active SONs takes part in the consensus and the operations. They are termed as Consensus-SONs

SON-Quorum: The availability of SONs with 2/3rd accumulated stakes via votes is a SON-Quorum.

3. Background

The Bitcoin Sidechain functionality has been implemented in the Peerplays blockchain but it doesn't take into account, the change of witnesses.

As per the current implementation of Sidechain, a multi-sig bitcoin address will be created on the bitcoin blockchain to hold the bitcoins that have been deposited into the pBTC accounts of the Peerplays users.

Every Peerplays witnesses will have a bitcoin transaction signing key for this multi-sig bitcoin address and will be required to sign any withdrawal transaction.

When a witness changes, the transaction signing key of the outgoing witness needs to be removed from the multi-sig bitcoin address and the key of the incoming witness needs to be added.

The suggested proposal is to make the Sidechain code available as a plugin and assign the responsibility for running the sidechain code to separate nodes called the Sidechain Operating Nodes (SONs).

The SON functionality will be independent of the witness functionality and SONs don't need to be changed much often.

4. Basic Idea

One of the biggest challenges of the SON project is to achieve consensus among the SONs on the blockchain.

The consensus is required among SONs to perform the following tasks,

Transferring BTC to User address after withdrawal.
Transferring BTC from old PW to new PW.
To issue pBTC.
To report on another active SON for being inactive.

Also, the challenge is that SONs have to make sure they do all the work with respect to the sidechain and relieve the witnesses of the extra load of listening to the sidechain and handling deposits and withdrawals.

But the records/statistics of the sidechain transactions, issuance of pBTC, SON health status, etc have to be kept on-chain.

The Statics of the sidechain transactions, issuance of pBTC, SON health, availability of SONs etc have to be kept on the Peerplays blockchain.

This provides a robust mechanism for anyone to get the historical performance of the SONs, near real time view of the chain fund movements.

The basic idea of how to achieve consensus is as follows,

Create a peerplays account for a sidechain SON-195 - Getting issue details... STATUS , let's name it ‘son-btc-account’.
Owners for the account are SONs.
Weights of their signatures are proportional to the votes they receive.
The weight threshold of the account is 2/3 of the total weight.
Any operation related to the SON tasks has the paying account as the son account that's created.
All such operations are encapsulated in proposals.
So for any SON proposal to be successfully executed it needs to have 2/3 of the total authority of SONs.

Eg. SON1 weight = 7 SON2 weight = 5 SON3 weight = 3 Total weight = 15 Weight Threshold = 2/3 * 15 = 10

So signatures of one of the SON combinations (1,2), (1,3), (1,2,3) are required to execute a successful transaction/proposal.

Psuedo-code is as follows,

const auto& son_btc_account = create<account_object>( [&]( account_object& obj ) {

obj.name = "son-btc-account";

obj.statistics = create<account_statistics_object>([&]( account_statistics_object& acc_stat ){ acc_stat.owner = obj.id; }).id;

obj.owner.weight_threshold = 10;

obj.active.weight_threshold = 10;

obj.membership_expiration_date = time_point_sec::maximum();

obj.network_fee_percentage = GRAPHENE_DEFAULT_NETWORK_PERCENT_OF_FEE;

obj.lifetime_referrer_fee_percentage = GRAPHENE_100_PERCENT - GRAPHENE_DEFAULT_NETWORK_PERCENT_OF_FEE;

// Add Authority Weights

obj.owner.add_authority( son1, 7 );

obj.active.add_authority( son1, 7 );

obj.owner.add_authority( son2, 5 );

obj.active.add_authority( son2, 5 );

obj.owner.add_authority( son3, 3 );

obj.active.add_authority( son3, 3 );

});

5. How to get SON Public Keys for Multi-Sig PW creation

We need SON public keys to create a multi-sig Bitcoin address for PW.

We get this from son_object::signing_key stored in the database.

The key is assigned during the registration of SON through CLI (refer to create_son).

We can also extend the create_son API to include a sidechain public key that is different from peerplays public key. SON-190 - Getting issue details... STATUS

6. Creation and Signing of BTC Transaction

As discussed above, we need to egress BTC transactions in case of transferring BTC to a user after withdrawal and transferring BTC from old PW to new PW.

Following steps will accomplish this,

A Proposal is created with the fee-paying account as the individual SON account who is proposing.
Create the BTC raw transaction.
Create a BTC Transaction Send Operation with fee payer as the peerplays bitcoin sidechain account son-btc-account(weight threshold as 2/3 of SONs total weight).
Encapsulate the send operation in the proposal created.
Ensure the proposal lifetime is sufficient ( N*(number of SONs)*(block_creation_interval) where N is configurable i.e. 1,2,3,4 etc).
Publish the proposal on to the peerplays blockchain.
Each SON after receiving the proposal validated the data against the sidechain BTC database stored in the plugin locally.
If appropriate, each SON signs the BTC transaction.
Create a BTC Transaction Sign Operation with fee payer as the individual SON account who is signing (i.e. SON1 account, SON2 account, etc).
Sign the BTC transaction and store the signature in the sign operation.
Encapsulate the operation in a peerplays transaction, sign it and send it to peerplays blockchain.
The sign operation is evaluated by checking the SON signature on BTC Transaction with the SON public key registered on peerplays blockchain.
If evaluation succeeds, during the do_apply of sign operation the verified signatures are stored in the send operation encapsulated in the proposal created initially.
After the required signatures are available or lifetime of the proposal is expired and if enough signatures to reach the weight threshold of the son-btc-account are present, the proposal is executed, signatures are sorted and BTC transaction is sent out.

As the weights in the bitcoin script and weights of the son-btc-account are the same, if proposal is executed successfully the bitcoin transaction will also be successful.

Creating send-BTC transaction proposal pseudo-code,

// Create BTC Transaction with the vins and vouts stored in SON Database

btc_tx = create_btc_transaction();

// Create BTC Transaction Send Operation

bitcoin_transaction_send_operation btc_send_op;

btc_send_op.payer = son-btc-account;

// Get the BTC vector of inputs

btc_send_op.vins = btc_tx.get_valid_vins();

// Fill the BTC vector of outputs

btc_send_op.vout = fill_vouts();

// Store BTC Transaction data i.e. hash, amount, fee etc.

btc_send_op.transaction = btc_tx;

// Create the proposal and encapsulate the send operation in it.

proposal_create_operation proposal_op;

proposal_op.fee_paying_account = son_account;

proposal_op.proposed_ops.push_back( op_wrapper( btc_send_op ) );

uint32_t lifetime = ( get_global_properties().parameters.block_interval * get_global_properties().active_sons.size() ) * 4;

proposal_op.expiration_time = time_point_sec( head_block_time().sec_since_epoch() + lifetime );

Each SON signing the send-BTC transaction proposal pseudo-code,

bitcoin_transaction_sign_operation sign_operation;

sign_operation.payer = current_son.son_account;

// Proposal ID of the send-BTC Transaction Operation

sign_operation.proposal_id = proposal_id;

// Assign SON ID

sign_operation.son_id = my_son_id;

// Get the vins from the proposal

auto vins = btc_send_op.vins;

// Sign the transaction

sign_operation.signatures = sign_transaction(btc_send_op.transaction, vins);

BTC Sign Operation Evaluator pseudo-code,

void_result bitcoin_transaction_sign_evaluator::do_evaluate( const bitcoin_transaction_sign_operation& op ) {

const auto& proposal_itr = proposal_idx.find(op.proposal_id);

FC_ASSERT(proposal_idx.end() != proposal_itr, "proposal not found");

FC_ASSERT(is_signed_by_active_son(op.son_id), "Not signed by active SON.");

const auto& son_object = get_son_object(op.son_id);

bytes public_key( public_key_data_to_bytes( son_object.signing_key.key_data ) );

auto btc_send_op = proposal_itr->proposed_transaction.operations[0].get<bitcoin_transaction_send_operation>();

// Get the vector of input txs from send-operation from proposal and verify sigs with SON Public key

auto vins = btc_send_op.vins;

FC_ASSERT( check_sigs( public_key, op.signatures, vins, btc_send_op.transaction ) );

}

void_result bitcoin_transaction_sign_evaluator::do_apply( const bitcoin_transaction_sign_operation& op ) {

database& d = db();

// Get the send-BTC Transaction Operation Proposal created

const auto& proposal = op.proposal_id( d );

// Modify the operation by adding the validated signature

d.modify( proposal, [&]( proposal_object& po ) {

auto bitcoin_transaction_send_op = po.proposed_transaction.operations[0].get<bitcoin_transaction_send_operation>();

for( size_t i = 0; i < op.signatures.size(); i++ ) {

bitcoin_transaction_send_op.transaction.vin[i].scriptWitness.push_back( op.signatures[i] );

}

po.proposed_transaction.operations[0] = bitcoin_transaction_send_op;

});

// Create proposal_update_operation and add the SON's approval to the proposal.

proposal_update_operation update_op;

update_op.fee_paying_account = op.payer;

update_op.proposal = op.proposal_id;

update_op.active_approvals_to_add = { op.payer };

d.apply_operation(*trx_state, update_op);

return void_result();

}

BTC Send Transaction Operation Evaluator Pseudo-code,

void_result bitcoin_transaction_send_evaluator::do_evaluate( const bitcoin_transaction_send_operation& op ) {

// Check if the payer of the operation is the multi signatory SON BTC peerplays account.

FC_ASSERT( son-btc-account == op.payer );

return void_result();

}

object_id_type bitcoin_transaction_send_evaluator::do_apply( const bitcoin_transaction_send_operation& op ) {

bitcoin_transaction_send_operation& mutable_op = const_cast<bitcoin_transaction_send_operation&>( op );

database& d = db();

// Make the transaction ready by sorting sigs etc

finalize_btc_tx(mutable_op);

auto new_vins = create_transaction_vins( mutable_op );

// Create the bitcoin_transaction_object to be stored on the chain.

const bitcoin_transaction_object& btc_tx = d.create< bitcoin_transaction_object >( [&]( bitcoin_transaction_object& obj )

{

obj.pw_vin = mutable_op.pw_vin.identifier;

obj.vins = new_vins;

obj.vouts = mutable_op.vouts;

obj.transaction = mutable_op.transaction;

obj.transaction_id = mutable_op.transaction.get_txid();

obj.fee_for_size = mutable_op.fee_for_size;

});

// Send out the transaction.

send_bitcoin_transaction( btc_tx );

return btc_tx.id;

}

7. SON Heart Beats

Heartbeat transactions are sent by active SONs to notify the blockchain that they are active.

The frequency of the heartbeat can be configured through chain parameter extensions.

We need these in order to mark active SONs as in_maintenance if heartbeats are missed.

Evaluation and application of the heartbeat operation pseudo-code,

void_result son_evaluator::do_evaluate(const son_heartbeat_operation& op) {

// Get SON Object from son id through son_index

son_object son = get_son_by_id(op.son_id);

// Payer for hearbeat operations are individual SON accounts

FC_ASSERT(op.payer == son.son_account);

return void_result();

}

void_result son_evaluator::do_apply(const son_heartbeat_operation& op) {

// Get SON Object from son id through son_index

son_object son = get_son_by_id(op.son_id);

// Get SON Statistics Object from son_stats_index

son_statistics_object son_stats = get_son_stats(son.statistics);

// Update the last active timestamp

db.modify( son_stats, [&]( son_statistics_object& _s)

{

_s.last_active_ts = op.ts;

});

}

8. Reporting SON Down

If any SON misses N number of heartbeats then one of the other active SONs can notify the peerplays blockchain about it.

N can be configurable with chain parameter extensions.

One of the rest of the active SON can raise a son_deactivate_operation to report on the SON which is down.

The fee-paying account for this operation should be the peerplays bitcoin sidechain account son-btc-account.

A proposal is created and the deactivate operation is encapsulated inside the proposal. (Fee-paying account for the proposal is individual SON account)

The lifetime of the proposal can be N*(number of SONs)*(block_creation_interval) where N is configurable i.e. 1,2,3,4 etc.

The rest of the SONs on receiving the proposal can validate and add their approvals to the proposal.

After the required signatures are available or once the proposal is expired, if it succeeds it is executed and the down SON status is set to in_maintenance on the blockchain.

If the down SON becomes active and sends a heartbeat while the deactivate proposal is active, we can leave the SON status as active but add up the downtime in statistics object.

Evaluation and application of the son deactivate operation pseudo-code,

void_result son_evaluator::do_evaluate(const son_deactivate_operation& op) {

// Get SON Object from son id through son_index

son_object son = get_son_by_id(op.son_id);

// Payer for hearbeat operations are individual SON accounts

FC_ASSERT(op.payer == son.son_account);

return void_result();

}

void_result son_evaluator::do_apply(const son_deactivate_operation& op) {

// Get SON Object from son id through son_index

son_object son = get_son_by_id(op.son_id);

// Get SON Statistics Object from son_stats_index

son_statistics_object son_stats = get_son_stats(son.statistics);

// Update the last active timestamp

db.modify( son, [&]( son_object& _son_obj)

{

_son_obj.status = son_status::in_maintenance;

});

db.modify( son_stats, [&]( son_statistics_object& _s)

{

_s.last_down_ts = op.ts;

});

}

Adding approvals by rest of the active SONs pseudo-code,

// Create proposal_update_operation and add the SON's approval to the proposal.

proposal_update_operation update_op;

update_op.fee_paying_account = op.payer;

update_op.proposal = op.proposal_id;

update_op.active_approvals_to_add = { op.payer };

d.apply_operation(*trx_state, update_op);

9. SON Issue pBTC

Once a required number of confirmations are reached for a transaction sending BTC from user bitcoin address to PW address, SON pBTC issue operation has to be raised to user’s peerplays account.

As discussed above similar proposal process is followed.

A proposal is created by one active SON and the fee-paying account is set to the individual account of the SON. (lifetime same as discussed above)
A bitcoin_issue_operation is created for which the fee-paying account is set to son-btc-account.
The issue operation is encapsulated in the proposal and sent to the peerplays blockchain.
Rest of the active SONs validate their plugin BTC databases and add approvals upon receiving the proposal.
Once the required number of approvals (2/3 of SONs total weight) are added, proposal is executed and the pBTC is issued.

SON Issue pBTC pseudo-code,

void_result son_evaluator::do_evaluate(const bitcoin_issue_operation& op) {

// Check if the payer of the operation is the multi signatory SON BTC peerplays account.

FC_ASSERT( son-btc-account == op.payer );

// Check if the vin tx input address is user registered address on peerplays blockchain.

FC_ASSERT( is_address_registered(op.vin_addres))

return void_result();

}

void_result son_evaluator::do_apply(const bitcoin_issue_operation& op) {

// Get the peerplays account to issue pBTC

const auto& account_to_issue = get_account_to_issue(op.vin_address);

// Get the amount to issue i.e. equal to BTC amount transferred

const auto& amount_to_issue = get_amount_to_issue(op.amount);

// Follow the normal UIA issue procedure.

add_issue(account_to_issue, amount_to_issue);

}

Adding approvals by rest of the active SONs pseudo-code,

// Create proposal_update_operation and add the SON's approval to the proposal.

proposal_update_operation update_op;

update_op.fee_paying_account = op.payer;

update_op.proposal = op.proposal_id;

update_op.active_approvals_to_add = { op.payer };

d.apply_operation(*trx_state, update_op);

10. Choosing the SON who creates the next proposal

In all the above operations, any one of the SON has to raise the initial proposal.

If multiple proposals are raised for the same BTC transaction, only one of them is valid and the rest of them should be rejected.

To achieve this we can use one of the existing witnesses shuffled or scheduled algorithms.

With these algorithms in place, all the SONs know when is their slot to publish a proposal for the next event.

The detailed design for this is out of the scope of this document and should be part of SON plugin handling.

For the existing witness scheduling algorithm please refer to this link.

11. Data Structures

11.1 bitcoin_transaction_send_operation

We can retain most of the implementation from the sidechain branch.

It can be found here.

11.2 bitcoin_transaction_sign_operation

We can retain most of the implementation from the sidechain branch.

It can be found here.

11.3 son_heartbeat_operation

11.4 son_deactivate_operation

12. SON changes during Maintenance

One of the many things we have to do during maintenance is updating the PW and the multi signatory SON account (son-btc-account).

As discussed above the weights of signatures is the same for both PW and the multi signatory SON account, we have to change both accordingly after the SON weight changes or SON changes.

The change of PW is discussed here.

Eg. Weights of the SONs have changed from the previous example above and a new SON is active. SON1 weight = 10 SON2 weight = 5 SON4 weight = 6 Total weight = 21 Weight Threshold = 2/3 * 21 = 14

So signatures of one of the SON combinations (1,2), (1,4), (1,2,4) are required to execute a successful transaction/proposal.

For changing the weights of peerplays SON account following is the pseudo-code,

modify( sidechain_account, [&]( account_object& obj ) {

// Add new weight threshold

obj.owner.weight_threshold = 14;

obj.active.weight_threshold = 14;

// Add new authority for SON1

obj.owner.add_authority( son1, 10 );

obj.active.add_authority( son1, 10 );

// Add new authority for SON2

obj.owner.add_authority( son2, 5 );

obj.active.add_authority( son2, 5 );

// Remove the SON3 Authority

obj.owner.add_authority( son3, 0 );

obj.active.add_authority( son3, 0 );

// Add new authority for SON4

obj.owner.add_authority( son4, 6 );

obj.active.add_authority( son4, 6 );

});

13. Conclusion

This approach can greatly relieve the peerplays blockchain of any type of sidechain listening, deposit, and withdrawal operations.

Only the transactions which are needed to be logged are processed by the nodes other than SONs.

All the operations which need multiple signatures can directly be accepted by everyone on the blockchain as the proposals ensure all signatures present before execution.

The most important aspect of this design is we can re-use most of the existing bitcoin-related sidechain code which can reduce our development effort.

Peerplays Developer Docs

Developer Documentation

API Reference

API Libraries

Development Guides

The Cookbook

Tools & Integration

Reference Docs

Workflow

Other Documentation

API Reference

Peerplays Core API

Popular API Calls

Overview

API Calls

list_account_balances

transfer

transfer2

get_account_history

get_object

get_asset

Account History

Account History

get_account_history

get_account_history_operations

get_relative_account_history

Market History

get_fill_order_history

get_market_history

get_market_history_buckets

Asset API

Asset API

get_asset_holders

get_all_asset_holders

Block API

Block API

get_blocks

Crypto API

Blinding and Un-Blinding

blind

blind_sum

Range Proofs

range_get_info

range_proof_sign

Verification

verify_sum

verify_range

verify_range_proof_rewind

Database API

Objects

get_objects

Subscriptions

set_subscribe_callback

set_pending_transaction_callback

set_block_applied_callback

cancel_all_subscriptions

Blocks and transactions

get_block_header

get_block

get_transaction

get_recent_transaction_by_id

Globals

get_chain_properties

get_global_properties

get_config

get_chain_id

get_dynamic_global_properties

Keys

get_key_references

Accounts

get_accounts

get_full_accounts

get_account_by_name

get_account_references

lookup_account_names

lookup_accounts

get_account_count

Balances

get_account_balances

get_named_account_balances