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

Based for all HTTP status codes

exception NotFound(*args, **kwargs)

Bases: nucypher.network.middleware.RestMiddleware.UnexpectedResponse

Raised for HTTP 404

exception BadRequest(reason, *args, **kwargs)

Bases: nucypher.network.middleware.RestMiddleware.UnexpectedResponse

Raised for HTTP 400

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

classmethod set_cert_storage_function(node_storage_function: Callable)
mature(*args, **kwargs)

This is the most mature form, so we do nothing.

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

  • 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, delimiter: str = '@') → Tuple[str, int, NewType.<locals>.new_type]
class InterfaceInfo(host, port)

Bases: object

property uri
property formal_uri
get_static_resources()
class RetrievalError(errors: Dict[NewType.<locals>.new_type, str])

Bases: object

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.

update_errors(work_order: nucypher.network.retrieval.RetrievalWorkOrder, ursula_address: NewType.<locals>.new_type, error_message: str)
is_complete()bool
results() → Tuple[List[nucypher.policy.kits.RetrievalResult], List[nucypher.network.retrieval.RetrievalError]]
class RetrievalWorkOrder(ursula_address: nucypher_core.Address, retrieval_kits: List[nucypher_core.RetrievalKit])

Bases: object

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

property capsules
property lingos
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, **context) → Tuple[List[nucypher.policy.kits.RetrievalResult], List[nucypher.network.retrieval.RetrievalError]]
class ProxyRESTServer(rest_host: str, rest_port: int, hosting_power=None, rest_app=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(this_node, log: nucypher.utilities.logging.Logger = <Logger 'http-application-layer'>) → flask.app.Flask

Creates a REST application.

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.