nucypher.network¶

Submodules¶

class NucypherMiddlewareClient(registry=None, *args, **kwargs)¶

Bases: object

library = <module 'requests' from '/home/docs/checkouts/readthedocs.org/user_builds/nucypher/envs/latest/lib/python3.7/site-packages/requests/__init__.py'>¶

timeout = 1.2¶

static response_cleaner(response)¶

verify_and_parse_node_or_host_and_port(node_or_sprout, host, port)¶: Does two things: 1) Verifies the node (unless it is EXEMPT_FROM_VERIFICATION, like when we initially get its certificate) 2) Parses the node into a host and port, or returns the provided host and port. :return: A 3-tuple: host string, certificate, and the library to be used for the connection.

parse_node_or_host_and_port(node, host, port)¶

invoke_method(method, url, *args, **kwargs)¶

clean_params(request_kwargs)¶: No cleaning needed.

node_information(host, port, certificate_filepath=None)¶

node_selector(node)¶

class RestMiddleware(registry=None)¶

Bases: object

log¶

Drop-in replacement of Twisted’s Logger, patching the emit() method to tolerate inputs with curly braces, i.e., not compliant with PEP 3101.

See Issue #724 and, particularly, https://github.com/nucypher/nucypher/issues/724#issuecomment-600190455

TEACHER_NODES = {'ibex': ('https://ibex.nucypher.network:9151',), 'mainnet': ('https://mainnet.nucypher.network:9151',)}¶

exception UnexpectedResponse(message, status, *args, **kwargs)¶: Bases: Exception

exception NotFound(*args, **kwargs)¶: Bases: nucypher.network.middleware.RestMiddleware.UnexpectedResponse

exception BadRequest(reason, *args, **kwargs)¶: Bases: nucypher.network.middleware.RestMiddleware.UnexpectedResponse

get_certificate(host, port, timeout=3, retry_attempts: int = 3, retry_rate: int = 2, current_attempt: int = 0)¶

propose_arrangement(arrangement)¶

enact_policy(ursula, kfrag_id, payload)¶

reencrypt(work_order)¶

revoke_arrangement(ursula, revocation)¶

get_competitive_rate()¶

get_treasure_map_from_node(node, map_identifier)¶

put_treasure_map_on_node(node, map_payload)¶

send_work_order_payload_to_ursula(work_order)¶

check_rest_availability(initiator, responder)¶

get_nodes_via_rest(node, announce_nodes=None, nodes_i_need=None, fleet_checksum=None)¶

class NodeSprout(node_metadata)¶

Bases: bytestring_splitter.PartiallyKwargifiedBytes

An abridged node class designed for optimization of instantiation of > 100 nodes simultaneously.

verified_node = False¶

property stamp¶

property domain¶

property checksum_address¶

property nickname¶

mature()¶

class DiscoveryCanceller¶: Bases: object

class Learner(domain: str, node_class: object = None, network_middleware: nucypher.network.middleware.RestMiddleware = None, start_learning_now: bool = False, learn_on_same_thread: bool = False, known_nodes: tuple = None, seed_nodes: Tuple[tuple] = None, node_storage=None, save_metadata: bool = False, abort_on_learning_error: bool = False, lonely: bool = False, verify_node_bonding: bool = True)¶

Bases: object

Any participant in the “learning loop” - a class inheriting from this one has the ability, synchronously or asynchronously, to learn about nodes in the network, verify some essential details about them, and store information about them for later use.

LEARNING_TIMEOUT = 10¶

LEARNER_VERSION = 2¶

LOWEST_COMPATIBLE_VERSION = 2¶

node_splitter = <bytestring_splitter.BytestringSplitter object>¶

version_splitter = <bytestring_splitter.BytestringSplitter object>¶

tracker_class¶: alias of nucypher.acumen.perception.FleetSensor

invalid_metadata_message = "{} has invalid metadata. The node's stake may have ended, or it is transitioning to a new interface. Ignoring."¶

fleet_state_population = None¶

exception NotEnoughNodes¶: Bases: RuntimeError

exception NotEnoughTeachers¶

Bases: nucypher.network.nodes.Learner.NotEnoughNodes

crash_right_now = True¶

exception UnresponsiveTeacher¶: Bases: ConnectionError

exception NotATeacher¶

Bases: ValueError

Raised when a character cannot be properly utilized because it does not have the proper attributes for learning or verification.

exception InvalidSignature¶: Bases: Exception

property known_nodes¶

load_seednodes(read_storage: bool = True, record_fleet_state=False)¶

Engage known nodes from storages and pre-fetch hardcoded seednode certificates for node learning.

TODO: Dehydrate this with nucypher.utilities.seednodes.load_seednodes

read_nodes_from_storage() → List¶

remember_node(node, force_verification_recheck=False, record_fleet_state=True, eager: bool = False)¶

start_learning_loop(now=False)¶

stop_learning_loop(reason=None)¶: Only for tests at this point. Maybe some day for graceful shutdowns.

handle_learning_errors(failure, *args, **kwargs)¶

select_teacher_nodes()¶

cycle_teacher_node()¶

current_teacher_node(cycle=False)¶

learn_about_nodes_now(force=False)¶

keep_learning_about_nodes()¶: Continually learn about new nodes.

learn_about_specific_nodes(addresses: Iterable)¶

block_until_number_of_known_nodes_is(number_of_nodes_to_know: int, timeout: int = 10, learn_on_this_thread: bool = False, eager: bool = False)¶

block_until_specific_nodes_are_known(addresses: Set, timeout=10, allow_missing=0, learn_on_this_thread=False, verify_now=False)¶

network_bootstrap(node_list: list) → None ¶

get_nodes_by_ids(node_ids)¶

write_node_metadata(node, serializer=<class 'bytes'>) → str ¶

verify_from(stranger: nucypher.network.nodes.Teacher, message_kit: Union[nucypher.crypto.kits.PolicyMessageKit, bytes], signature: umbral.signing.Signature)¶

learn_from_teacher_node(eager=False, canceller=None)¶

Sends a request to node_url to find out about known nodes.

TODO: Does this (and related methods) belong on FleetSensor for portability?

TODO: A lot of other code can be simplified if this is converted to async def. That’s a project, though.

class Teacher(domain: str, certificate: cryptography.x509.base.Certificate, certificate_filepath: str, interface_signature=NOT_SIGNED, timestamp=NOT_SIGNED, decentralized_identity_evidence=NOT_SIGNED)¶

Bases: object

TEACHER_VERSION = 2¶

log¶

Drop-in replacement of Twisted’s Logger, patching the emit() method to tolerate inputs with curly braces, i.e., not compliant with PEP 3101.

See Issue #724 and, particularly, https://github.com/nucypher/nucypher/issues/724#issuecomment-600190455

synchronous_query_timeout = 20¶

exception InvalidNode¶

Bases: nucypher.network.protocols.SuspiciousActivity

Raised when a node has an invalid characteristic - stamp, interface, or address.

exception InvalidStamp¶

Bases: nucypher.network.nodes.Teacher.InvalidNode

Base exception class for invalid character stamps

exception StampNotSigned¶

Bases: nucypher.network.nodes.Teacher.InvalidStamp

Raised when a node does not have a stamp signature when one is required for verification

exception InvalidWorkerSignature¶

Bases: nucypher.network.nodes.Teacher.InvalidStamp

Raised when a stamp fails signature verification or recovers an unexpected worker address

exception NotStaking¶

Bases: nucypher.network.nodes.Teacher.InvalidStamp

Raised when a node fails verification because it is not currently staking

exception UnbondedWorker¶

Bases: nucypher.network.nodes.Teacher.InvalidNode

Raised when a node fails verification because it is not bonded to a Staker

exception WrongMode¶

Bases: TypeError

Raised when a Character tries to use another Character as decentralized when the latter is federated_only.

exception UnexpectedVersion¶

Bases: TypeError

Raised when deserializing a Character from a unexpected and incompatible version.

exception IsFromTheFuture¶

Bases: nucypher.network.nodes.Teacher.UnexpectedVersion

Raised when deserializing a Character from a future version.

exception AreYouFromThePast¶

Bases: nucypher.network.nodes.Teacher.UnexpectedVersion

Raised when deserializing a Character from a previous, now unsupported version.

unknown_version_message = "{} purported to be of version {}, but we're version {}."¶

really_unknown_version_message = "Unable to glean address from node that purported to be version {}. We're version {}."¶

classmethod set_cert_storage_function(node_storage_function)¶

mature(*args, **kwargs)¶: This is the most mature form, so we do nothing.

classmethod set_federated_mode(federated_only: bool)¶

classmethod from_tls_hosting_power(tls_hosting_power: nucypher.network.server.TLSHostingPower, *args, **kwargs) → nucypher.network.nodes.Teacher ¶

seed_node_metadata(as_teacher_uri=False) → nucypher.config.constants.seednode¶

sorted_nodes()¶

bytestring_of_known_nodes()¶

update_snapshot(checksum, updated, number_of_known_nodes)¶

TODO: We update the simple snapshot here, but of course if we’re dealing: with an instance that is also a Learner, it has its own notion of its FleetState, so we probably need a reckoning of sorts here to manage that. In time. NRN

Parameters

checksum –
updated –
number_of_known_nodes –

Returns

validate_worker(registry: nucypher.blockchain.eth.registry.BaseContractRegistry = None) → None ¶

validate_metadata(registry: nucypher.blockchain.eth.registry.BaseContractRegistry = None)¶

verify_node(network_middleware_client, registry: nucypher.blockchain.eth.registry.BaseContractRegistry = None, certificate_filepath: str = None, force: bool = False) → bool ¶

Three things happening here:

Verify that the stamp matches the address (raises InvalidNode is it’s not valid, or WrongMode if it’s a federated mode and being verified as a decentralized node)
Verify the interface signature (raises InvalidNode if not valid)
Connect to the node, make sure that it’s up, and that the signature and address we checked are the same ones this node is using now. (raises InvalidNode if not valid; also emits a specific warning depending on which check failed).

property decentralized_identity_evidence¶

property worker_address¶

substantiate_stamp()¶

validate_interface() → bool ¶: Checks that the interface info is valid for this node’s canonical address.

property timestamp¶

timestamp_bytes()¶

property nickname_icon¶

nickname_icon_details()¶

known_nodes_details() → dict ¶

static node_details(node)¶: Stranger-Safe Details

abridged_node_details() → dict ¶: Self-Reporting

exception SuspiciousActivity¶

Bases: RuntimeError

raised when an action appears to amount to malicious conduct.

parse_node_uri(uri: str)¶

class InterfaceInfo(host, port)¶

Bases: object

expected_bytes_length()¶

classmethod from_bytes(url_string)¶

property uri¶

property formal_uri¶

get_static_resources()¶

class ProxyRESTServer(rest_host: str, rest_port: int, hosting_power=None, rest_app=None, datastore=None)¶

Bases: object

SERVER_VERSION = 2¶

log¶

Drop-in replacement of Twisted’s Logger, patching the emit() method to tolerate inputs with curly braces, i.e., not compliant with PEP 3101.

See Issue #724 and, particularly, https://github.com/nucypher/nucypher/issues/724#issuecomment-600190455

rest_url()¶

make_rest_app(db_filepath: str, this_node, domain, log: nucypher.utilities.logging.Logger = <Logger 'http-application-layer'>) → Tuple[flask.app.Flask, nucypher.datastore.datastore.Datastore]¶: Creates a REST application and an associated Datastore object. Note that the REST app does not hold a reference to the datastore; it is your responsibility to ensure it lives for as long as the app does.

class TLSHostingPower(host: str, public_certificate=None, public_certificate_filepath=None, *args, **kwargs)¶

Bases: nucypher.crypto.powers.KeyPairBasedPower

provides = ('get_deployer',)¶

exception NoHostingPower¶: Bases: nucypher.crypto.powers.PowerUpError

not_found_error¶: alias of TLSHostingPower.NoHostingPower

class AvailabilityTracker(ursula, enforce_loneliness: bool = True)¶

Bases: object

FAST_INTERVAL = 15¶

SLOW_INTERVAL = 120¶

SEEDING_DURATION = 60¶

MAXIMUM_ALONE_TIME = 120¶

MAXIMUM_SCORE = 10.0¶

SAMPLE_SIZE = 1¶

SENSITIVITY = 0.5¶

CHARGE_RATE = 0.9¶

exception Unreachable¶: Bases: RuntimeError

exception Solitary¶

Bases: nucypher.network.trackers.AvailabilityTracker.Unreachable

message = 'Cannot connect to any teacher nodes.'¶

exception Lonely¶

Bases: nucypher.network.trackers.AvailabilityTracker.Unreachable

message = 'Cannot connect to enough teacher nodes.'¶

property excuses¶

mild_warning() → None ¶

medium_warning() → None ¶

severe_warning() → None ¶

shutdown_everything(reason=None, halt_reactor=False)¶

handle_measurement_errors(crash_on_error: bool = False, *args, **kwargs) → None ¶

status() → bool ¶: Returns current indication of availability

property running¶

start(now: bool = False)¶

stop() → None ¶

maintain() → None ¶

issue_warnings(cascade: bool = True) → None ¶

sample(quantity: int) → list ¶

property score¶

record(result: bool = None, reason: dict = None) → None ¶: Score the result and cache it.

measure_sample(ursulas: list = None) → None ¶: Measure self-availability from a sample of Ursulas or automatically from known nodes. Handle the possibility of unreachable or invalid remote nodes in the sample.

measure(ursula_or_sprout: Union[Ursula, nucypher.network.nodes.NodeSprout]) → None ¶: Measure self-availability from a single remote node that participates uptime checks.