nucypher.network¶

Submodules¶

class NucypherMiddlewareClient(registry: Optional[BaseContractRegistry] = None, eth_provider_uri: Optional[str] = None, storage: Optional[NodeStorage] = 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¶

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

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

node_selector(node)¶

class RestMiddleware(registry=None, eth_provider_uri: str = 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

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

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

exception PaymentRequired(*args, **kwargs)¶

Bases: nucypher.network.middleware.RestMiddleware.UnexpectedResponse

Raised for HTTP 402

exception Unauthorized(*args, **kwargs)¶

Bases: nucypher.network.middleware.RestMiddleware.UnexpectedResponse

Raised for HTTP 403

request_revocation(ursula, revocation)¶

reencrypt(ursula: Ursula, reencryption_request_bytes: bytes)¶

check_availability(initiator, responder)¶

ping(node)¶

get_nodes_via_rest(node, fleet_state_checksum: nucypher_core.FleetStateChecksum, announce_nodes: Sequence[nucypher_core.NodeMetadata])¶

class NodeSprout(metadata: nucypher_core.NodeMetadata)¶

Bases: object

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

verified_node = False¶

property checksum_address¶

property canonical_address¶

property nickname¶

property rest_interface¶

rest_url()¶

metadata()¶

property verifying_key¶

property encrypting_key¶

property operator_signature_from_metadata¶

property timestamp¶

property stamp¶

property domain¶

finish()¶

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, include_self_in_the_state: bool = False)¶

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¶

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."¶

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.

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.

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

network_bootstrap(node_list: list) → None ¶

get_nodes_by_ids(node_ids)¶

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

verify_from(stranger: Character, message: bytes, signature: umbral.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: pathlib.Path)¶

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

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

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

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.

classmethod set_cert_storage_function(node_storage_function: Callable)¶

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

classmethod set_federated_mode(federated_only: bool)¶

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

bytestring_of_known_nodes()¶

validate_operator(registry: nucypher.blockchain.eth.registry.BaseContractRegistry = None, eth_provider_uri: Optional[str] = None) → None ¶

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

validate_metadata(registry: nucypher.blockchain.eth.registry.BaseContractRegistry = None, eth_provider_uri: Optional[str] = None)¶

verify_node(network_middleware_client, registry: nucypher.blockchain.eth.registry.BaseContractRegistry = None, eth_provider_uri: Optional[str] = None, certificate_filepath: Optional[pathlib.Path] = 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).

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

property uri¶

property formal_uri¶

get_static_resources()¶

class RetrievalPlan(treasure_map: nucypher_core.TreasureMap, retrieval_kits: Sequence[nucypher_core.RetrievalKit])¶

Bases: object

An emphemeral object providing a service of selecting Ursulas for reencryption requests during retrieval.

get_work_order() → nucypher.network.retrieval.RetrievalWorkOrder ¶: Returns a new retrieval work order based on the current plan state.

update(work_order: nucypher.network.retrieval.RetrievalWorkOrder, cfrags: Dict[umbral.Capsule, umbral.VerifiedCapsuleFrag])¶: Updates the plan state, recording the cfrags obtained for capsules during a query.

is_complete() → bool ¶

results() → List[nucypher.policy.kits.RetrievalResult]¶

class RetrievalWorkOrder(ursula_address: NewType.<locals>.new_type, capsules: List[umbral.Capsule])¶

Bases: object

A work order issued by a retrieval plan to request reencryption from an Ursula

class RetrievalClient(learner: nucypher.network.nodes.Learner)¶

Bases: object

Capsule frag retrieval machinery shared between Bob and Porter.

retrieve_cfrags(treasure_map: nucypher_core.TreasureMap, retrieval_kits: Sequence[nucypher_core.RetrievalKit], alice_verifying_key: umbral.PublicKey, bob_encrypting_key: umbral.PublicKey, bob_verifying_key: umbral.PublicKey) → List[nucypher.policy.kits.RetrievalResult]¶

class ProxyRESTServer(rest_host: str, rest_port: int, hosting_power=None, rest_app=None, datastore=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

rest_url()¶

make_rest_app(db_filepath: pathlib.Path, this_node, 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 OperatorBondedTracker(ursula)¶

Bases: nucypher.utilities.task.SimpleTask

INTERVAL = 3600¶

exception OperatorNoLongerBonded¶

Bases: RuntimeError

Raised when a running node is no longer associated with a staking provider.

run() → None ¶: Task method that should be periodically run.

handle_errors(failure: twisted.python.failure.Failure) → None ¶: Error callback for error handling during execution.

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.