bbc1.core.bbc_app module¶
Copyright (c) 2017 beyond-blockchain.org.
Licensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-
class
bbc1.core.bbc_app.
BBcAppClient
(host='127.0.0.1', port=9000, multiq=True, logname='-', loglevel='none')[source]¶ Bases:
object
Basic functions for a client of bbc_core
-
cancel_insert_completion_notification
(asset_group_id)[source]¶ Cancel notification when a transaction has been inserted (as a copy of transaction)
- Parameters
asset_group_id (bytes) – asset_group_id for requesting notification about insertion
- Returns
query_id
- Return type
bytes
-
count_transactions
(asset_group_id=None, asset_id=None, user_id=None, start_from=None, until=None)[source]¶ Count transactions that matches the given conditions
If multiple conditions are specified, they are considered as AND condition.
- Parameters
asset_group_id (bytes) – asset_group_id in BBcEvent and BBcRelations
asset_id (bytes) – asset_id in BBcAsset
user_id (bytes) – user_id in BBcAsset that means the owner of the asset
start_from (int) – the starting timestamp to search
until (int) – the end timestamp to search
- Returns
the number of transactions
- Return type
int
-
domain_close
(domain_id=None)[source]¶ Close domain leading to remove_domain in the core
- Parameters
domain_id (bytes) – domain_id to delete
- Returns
query_id
- Return type
bytes
-
domain_setup
(domain_id, config=None)[source]¶ Set up domain with the specified network module and storage
This method should be used by a system administrator.
- Parameters
domain_id (bytes) – domain_id to create
config (str) – system config in json format
- Returns
query_id
- Return type
bytes
-
gather_signatures
(txobj, reference_obj=None, asset_files=None, destinations=None, anycast=False)[source]¶ Request to gather signatures from the specified user_ids
- Parameters
txobj (BBcTransaction) –
reference_obj (BBcReference) – BBcReference object that includes the information about destinations
asset_files (dict) – mapping from asset_id to its file content
destinations (list) – list of destination user_ids
anycast (bool) – True if this message is for anycasting
- Returns
query_id
- Return type
bytes
-
get_bbc_config
()[source]¶ Get config file of bbc_core
This method should be used by a system administrator.
- Returns
query_id
- Return type
bytes
-
get_domain_neighborlist
(domain_id)[source]¶ Get peer list of the domain from the core node
This method should be used by a system administrator.
- Parameters
domain_id (bytes) – domain_id of the neighbor list
- Returns
query_id
- Return type
bytes
-
get_forwarding_list
()[source]¶ Get forwarding_list of the domain in the core node
- Returns
query_id
- Return type
bytes
-
get_notification_list
()[source]¶ Get notification_list of the core node
- Returns
query_id
- Return type
bytes
-
get_user_list
()[source]¶ Get user_ids in the domain that are connecting to the core node
- Returns
query_id
- Return type
bytes
-
include_cross_ref
(txobj)[source]¶ Include BBcCrossRef from other domains in the transaction
If the client object has one or more cross_ref objects, one of them is included in the given transaction. This method should be voluntarily called for inter-domain weak collaboration.
- Parameters
txobj (BBcTransaction) – Transaction object to include cross_ref
-
insert_transaction
(txobj)[source]¶ Request to insert a legitimate transaction
- Parameters
txobj (BBcTransaction) – Transaction object to insert
- Returns
query_id
- Return type
bytes
-
manipulate_ledger_subsystem
(enable=False, domain_id=None)[source]¶ Start/stop ledger_subsystem on the bbc_core
This method should be used by a system administrator.
- Parameters
enable (bool) – True->start, False->stop
domain_id (bytes) – target domain_id to enable/disable ledger_subsystem
- Returns
query_id
- Return type
bytes
-
notify_domain_key_update
()[source]¶ Notify update of bbc_core
This method should be used by a system administrator.
- Returns
query_id
- Return type
bytes
-
register_in_ledger_subsystem
(asset_group_id, transaction_id)[source]¶ Register transaction_id in the ledger_subsystem
- Parameters
asset_group_id (bytes) –
transaction_id (bytes) – the target transaction_id
- Returns
query_id
- Return type
bytes
-
register_to_core
(on_multiple_nodes=False)[source]¶ Register the client (user_id) to the core node
After that, the client can communicate with the core node.
- Parameters
on_multiple_nodes (bool) – True if this user_id is for multicast address
- Returns
True
- Return type
bool
-
request_cross_ref_holders_list
()[source]¶ Request the list of transaction_ids that are registered as cross_ref in outer domains
- Returns
query_id
- Return type
bytes
-
request_insert_completion_notification
(asset_group_id)[source]¶ Request notification when a transaction has been inserted (as a copy of transaction)
- Parameters
asset_group_id (bytes) – asset_group_id for requesting notification about insertion
- Returns
query_id
- Return type
bytes
-
request_to_repair_asset
(asset_group_id, asset_id)[source]¶ Request to repair compromised asset file
- Parameters
asset_group_id (bytes) – the asset_group_id of the target asset
asset_id (bytes) – the target asset_id
- Returns
query_id
- Return type
bytes
-
request_to_repair_transaction
(transaction_id)[source]¶ Request to repair compromised transaction data
- Parameters
transaction_id (bytes) – the target transaction to repair
- Returns
query_id
- Return type
bytes
-
request_verify_by_cross_ref
(transaction_id)[source]¶ Request to verify the transaction by Cross_ref in transaction of outer domain
- Parameters
transaction_id (bytes) – the target transaction_id
- Returns
query_id
- Return type
bytes
-
search_transaction
(transaction_id)[source]¶ Search request for a transaction
- Parameters
transaction_id (bytes) – the target transaction to retrieve
- Returns
query_id
- Return type
bytes
-
search_transaction_with_condition
(asset_group_id=None, asset_id=None, user_id=None, start_from=None, until=None, direction=0, count=0)[source]¶ Search transaction data by asset_group_id/asset_id/user_id
If multiple conditions are specified, they are considered as AND condition.
- Parameters
asset_group_id (bytes) – asset_group_id in BBcEvent and BBcRelations
asset_id (bytes) – asset_id in BBcAsset
user_id (bytes) – user_id in BBcAsset that means the owner of the asset
start_from (int) – the starting timestamp to search
until (int) – the end timestamp to search
direction (int) – 0: descend, 1: ascend
count (int) – the number of transactions to retrieve
- Returns
query_id
- Return type
bytes
-
send_domain_ping
(domain_id, ipv4=None, ipv6=None, port=6641)[source]¶ Send domain ping to notify the existence of the node
This method should be used by a system administrator.
- Parameters
domain_id (bytes) – target domain_id to send ping
ipv4 (str) – IPv4 address of the node
ipv6 (str) – IPv6 address of the node
port (int) – Port number to wait messages UDP
- Returns
query_id
- Return type
bytes
-
send_message
(msg, dst_user_id, is_anycast=False)[source]¶ Send a message to the specified user_id
- Parameters
msg (dict) – message to send
dst_user_id (bytes) – destination user_id
is_anycast (bool) – If true, the message is treated as an anycast message.
- Returns
query_id
- Return type
bytes
-
sendback_denial_of_sign
(dest_user_id=None, transaction_id=None, reason_text=None, query_id=None)[source]¶ Send back the denial of sign the transaction
This method is called if the receiver (signer) denies the transaction.
- Parameters
dest_user_id (bytes) – destination user_id to send back
transaction_id (bytes) –
reason_text (str) – message to the requester about why the node denies the transaction
query_id – The query_id that was in the received SIGN_REQUEST message
- Returns
query_id
- Return type
bytes
-
sendback_signature
(dest_user_id=None, transaction_id=None, ref_index=-1, signature=None, query_id=None)[source]¶ Send back the signed transaction to the source
This method is called if the receiver (signer) approves the transaction.
- Parameters
dest_user_id (bytes) – destination user_id to send back
transaction_id (bytes) –
ref_index (int) – (optional) which reference in transaction the signature is for
signature (BBcSignature) – Signature that expresses approval of the transaction with transaction_id
query_id – The query_id that was in the received SIGN_REQUEST message
- Returns
query_id
- Return type
bytes
-
set_callback
(callback_obj)[source]¶ Set callback object that implements message processing functions
- Parameters
callback_obj (obj) – callback method object
-
set_domain_id
(domain_id)[source]¶ Set domain_id to this client to include it in all messages
- Parameters
domain_id (bytes) – domain_id to join in
-
set_domain_static_node
(domain_id, node_id, ipv4, ipv6, port)[source]¶ Set static node to the core node
IPv6 is used for socket communication if both IPv4 and IPv6 is specified. This method should be used by a system administrator.
- Parameters
domain_id (bytes) – target domain_id to set static neighbor entry
node_id (bytes) – node_id to register
ipv4 (str) – IPv4 address of the node
ipv6 (str) – IPv6 address of the node
port (int) – Port number to wait messages (UDP/TCP)
- Returns
query_id
- Return type
bytes
-
set_keypair
(keypair)[source]¶ Set keypair for the user
- Parameters
keypair (KeyPair) – KeyPair object for signing
-
set_node_key
(pem_file=None)[source]¶ Set node_key to this client
- Parameters
pem_file (str) – path string for the pem file
-
set_user_id
(identifier)[source]¶ Set user_id of the object
- Parameters
identifier (bytes) – user_id of this clients
-
traverse_transactions
(transaction_id, asset_group_id=None, user_id=None, start_from=None, until=None, direction=1, hop_count=3)[source]¶ Search request for transactions
The method traverses the transaction graph in the ledger. The response from the bbc_core includes the list of transactions.
- Parameters
transaction_id (bytes) – the target transaction to retrieve
asset_group_id (bytes) – asset_group_id that target transactions should have
user_id (bytes) – user_id that target transactions should have
start_from (int) – the starting timestamp to search
until (int) – the end timestamp to search
direction (int) – 1:backforward, non-1:forward
hop_count (int) – hop count to traverse from the specified origin point
- Returns
query_id
- Return type
bytes
-
-
class
bbc1.core.bbc_app.
Callback
(log=None)[source]¶ Bases:
object
Set of callback functions for processing received message
If you want to implement your own way to process messages, inherit this class.
-
proc_cmd_sign_request
(dat)[source]¶ Callback for message REQUEST_SIGNATURE
This method should be overridden if you want to process the message asynchronously.
- Parameters
dat (dict) – received message
-
proc_notify_cross_ref
(dat)[source]¶ Callback for message NOTIFY_CROSS_REF
This method must not be overridden.
- Parameters
dat (dict) – received message
-
proc_notify_inserted
(dat)[source]¶ Callback for message NOTIFY_INSERTED
This method should be overridden if you want to process the message asynchronously.
- Parameters
dat (dict) – received message
-
proc_resp_count_transactions
(dat)[source]¶ Callback for message RESPONSE_COUNT_TRANSACTIONS
This method should be overridden if you want to process the message asynchronously.
- Parameters
dat (dict) – received message
-
proc_resp_cross_ref_list
(dat)[source]¶ Callback for message RESPONSE_CROSS_REF_LIST
This method should be overridden if you want to process the message asynchronously.
- Parameters
dat (dict) – received message
-
proc_resp_domain_close
(dat)[source]¶ Callback for message RESPONSE_CLOSE_DOMAIN
This method should be overridden if you want to process the message asynchronously.
- Parameters
dat (dict) – received message
-
proc_resp_domain_setup
(dat)[source]¶ Callback for message RESPONSE_SETUP_DOMAIN
This method should be overridden if you want to process the message asynchronously.
- Parameters
dat (dict) – received message
-
proc_resp_ecdh_key_exchange
(dat)[source]¶ Callback for message RESPONSE_ECDH_KEY_EXCHANGE
This method must not be overridden.
- Parameters
dat (dict) – received message
-
proc_resp_gather_signature
(dat)[source]¶ Callback for message RESPONSE_GATHER_SIGNATURE
This method should be overridden if you want to process the message asynchronously.
- Parameters
dat (dict) – received message
-
proc_resp_get_config
(dat)[source]¶ Callback for message RESPONSE_GET_CONFIG
This method should be overridden if you want to process the message asynchronously.
- Parameters
dat (dict) – received message
-
proc_resp_get_domainlist
(dat)[source]¶ Callback for message RESPONSE_GET_DOMAINLIST
List of domain_ids is queued rather than message itself. This method should be overridden if you want to process the message asynchronously.
- Parameters
dat (dict) – received message
-
proc_resp_get_forwardinglist
(dat)[source]¶ Callback for message RESPONSE_GET_FORWARDING_LIST
List of user_ids in other core nodes is queued rather than message itself. This method should be overridden if you want to process the message asynchronously.
- Parameters
dat (dict) – received message
-
proc_resp_get_neighborlist
(dat)[source]¶ Callback for message RESPONSE_GET_NEIGHBORLIST
List of neighbor node info (the first one is that of the connecting core) is queued rather than message itself. This method must not be overridden.
- Parameters
dat (dict) – received message
-
proc_resp_get_node_id
(dat)[source]¶ Callback for message RESPONSE_GET_NODEID
Node_id is queued rather than message itself. This method should be overridden if you want to process the message asynchronously.
- Parameters
dat (dict) – received message
-
proc_resp_get_notificationlist
(dat)[source]¶ Callback for message RESPONSE_GET_NOTIFICATION_LIST
List of user_ids in other core nodes is queued rather than message itself. This method should be overridden if you want to process the message asynchronously.
- Parameters
dat (dict) – received message
-
proc_resp_get_stats
(dat)[source]¶ Callback for message RESPONSE_GET_STATS
This method should be overridden if you want to process the message asynchronously.
- Parameters
dat (dict) – received message
-
proc_resp_get_userlist
(dat)[source]¶ Callback for message RESPONSE_GET_USERS
List of user_ids is queued rather than message itself. This method should be overridden if you want to process the message asynchronously.
- Parameters
dat (dict) – received message
-
proc_resp_insert
(dat)[source]¶ Callback for message RESPONSE_INSERT
This method should be overridden if you want to process the message asynchronously.
- Parameters
dat (dict) – received message
-
proc_resp_ledger_subsystem
(dat)[source]¶ Callback for message RESPONSE_MANIP_LEDGER_SUBSYS
This method should be overridden if you want to process the message asynchronously.
- Parameters
dat (dict) – received message
-
proc_resp_register_hash
(dat)[source]¶ Callback for message RESPONSE_REGISTER_HASH_IN_SUBSYS
This method should be overridden if you want to process the message asynchronously.
- Parameters
dat (dict) – received message
-
proc_resp_search_transaction
(dat)[source]¶ Callback for message RESPONSE_SEARCH_TRANSACTION
This method should be overridden if you want to process the message asynchronously.
- Parameters
dat (dict) – received message
-
proc_resp_search_with_condition
(dat)[source]¶ Callback for message RESPONSE_SEARCH_WITH_CONDITIONS
This method should be overridden if you want to process the message asynchronously.
- Parameters
dat (dict) – received message
-
proc_resp_set_neighbor
(dat)[source]¶ Callback for message RESPONSE_SET_STATIC_NODE
This method should be overridden if you want to process the message asynchronously.
- Parameters
dat (dict) – received message
-
proc_resp_sign_request
(dat)[source]¶ Callback for message RESPONSE_SIGNATURE
This method should be overridden if you want to process the message asynchronously.
- Parameters
dat (dict) – received message
-
proc_resp_traverse_transactions
(dat)[source]¶ Callback for message RESPONSE_TRAVERSE_TRANSACTIONS
This method should be overridden if you want to process the message asynchronously.
- Parameters
dat (dict) – received message
-
proc_resp_verify_cross_ref
(dat)[source]¶ Callback for message RESPONSE_CROSS_REF_VERIFY
This method should be overridden if you want to process the message asynchronously.
- Parameters
dat (dict) – received message
-
proc_resp_verify_hash
(dat)[source]¶ Callback for message RESPONSE_VERIFY_HASH_IN_SUBSYS
This method should be overridden if you want to process the message asynchronously.
- Parameters
dat (dict) – received message
-
proc_user_message
(dat)[source]¶ Callback for message MESSAGE
This method should be overridden if you want to process the message asynchronously.
- Parameters
dat (dict) – received message
-
sync_by_queryid
(query_id, timeout=None, no_delete_q=False)[source]¶ Wait for the message with specified query_id
This method creates a queue for the query_id and waits for the response
- Parameters
query_id (byte) – timeout for waiting a message in seconds
timeout (int) – timeout for waiting a message in seconds
no_delete_q (bool) – If True, the queue for the query_id remains after popping a message
- Returns
a received message
- Return type
dict
-