bbc1.core.bbc_app module — BBc1 1.2 documentation

# 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

> http://www.apache.org/licenses/LICENSE-2.0

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

  Bases: `object`

  Basic functions for a client of bbc_core

  `cancel_insert_completion_notification`(asset_group_id)

    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)

    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
    Returns: | the number of transactions
    Return type: | int

  `domain_close`(domain_id=None)

    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)

    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

  `exchange_key`()

    Perform ECDH (key exchange algorithm)

    Returns: | query_id
    Return type: | bytes

  `gather_signatures`(txobj, reference_obj=None, asset_files=None, destinations=None, anycast=False)

    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`()

    Get config file of bbc_core

    This method should be used by a system administrator.

    Returns: | query_id
    Return type: | bytes

  `get_domain_list`()

    Get domain_id list in bbc_core

    Returns: | query_id
    Return type: | bytes

  `get_domain_neighborlist`(domain_id)

    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`()

    Get forwarding_list of the domain in the core node

    Returns: | query_id
    Return type: | bytes

  `get_node_id`()

    Get node_id of the connecting core node

    Returns: | query_id
    Return type: | bytes

  `get_notification_list`()

    Get notification_list of the core node

    Returns: | query_id
    Return type: | bytes

  `get_stats`()

    Get statistics of bbc_core

    Returns: | query_id
    Return type: | bytes

  `get_user_list`()

    Get user_ids in the domain that are connecting to the core node

    Returns: | query_id
    Return type: | bytes

  `include_admin_info`(dat, admin_info, keypair)
  `include_cross_ref`(txobj)

    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)

    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)

    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`()

    Notify update of bbc_core

    This method should be used by a system administrator.

    Returns: | query_id
    Return type: | bytes

  `receiver_loop`()
  `register_in_ledger_subsystem`(asset_group_id, transaction_id)

    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)

    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`()

    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)

    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)

    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)

    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)

    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)

    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, direction=0, count=1)

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

    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)

    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)

    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)

    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)

    Set callback object that implements message processing functions

    Parameters: | callback_obj (obj) – callback method object

  `set_domain_id`(domain_id)

    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)

    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)

    Set keypair for the user

    Parameters: | keypair (KeyPair) – KeyPair object for signing

  `set_node_key`(pem_file=None)

    Set node_key to this client

    Parameters: | pem_file (str) – path string for the pem file

  `set_user_id`(identifier)

    Set user_id of the object

    Parameters: | identifier (bytes) – user_id of this clients

  `start_receiver_loop`()
  `traverse_transactions`(transaction_id, asset_group_id=None, user_id=None, direction=1, hop_count=3)

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

  `unregister_from_core`()

    Unregister and disconnect from the core node

    Returns: | True
    Return type: | bool

  `verify_in_ledger_subsystem`(asset_group_id, transaction_id)

    Verify transaction_id in the ledger_subsystem

    Parameters: | asset_group_id (bytes) – transaction_id (bytes) – the target transaction_id
    Returns: | query_id
    Return type: | bytes

class `bbc1.core.bbc_app.` `Callback`(log=None)

  Bases: `object`

  Set of callback functions for processing received message

  If you want to implement your own way to process messages, inherit this class.

  `create_queue`(query_id)
  `dispatch`(dat, payload_type)
  `get_from_queue`(query_id, timeout=None, no_delete=False)
  `proc_cmd_sign_request`(dat)

    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)

    Callback for message NOTIFY_CROSS_REF

    This method must not be overridden.

    Parameters: | dat (dict) – received message

  `proc_notify_inserted`(dat)

    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)

    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)

    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)

    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)

    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)

    Callback for message RESPONSE_ECDH_KEY_EXCHANGE

    This method must not be overridden.

    Parameters: | dat (dict) – received message

  `proc_resp_gather_signature`(dat)

    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)

    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)

    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)

    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)

    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)

    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)

    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)

    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)

    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)

    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)

    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)

    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)

    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)

    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)

    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)

    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)

    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)

    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)

    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)

    Callback for message MESSAGE

    This method should be overridden if you want to process the message asynchronously.

    Parameters: | dat (dict) – received message

  `set_client`(client)
  `set_logger`(log)
  `sync_by_queryid`(query_id, timeout=None, no_delete_q=False)

    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

  `synchronize`(timeout=None)

    Wait for receiving message with a common queue

    Parameters: | timeout (int) – timeout for waiting a message in seconds
    Returns: | a received message
    Return type: | dict