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

A L{Logger} emits log messages to an observer. You should instantiate it as a class or module attribute, as documented in L{this module’s documentation <twisted.logger>}.

@type namespace: L{str} @ivar namespace: the namespace for this logger

@type source: L{object} @ivar source: The object which is emitting events via this logger

@type: L{ILogObserver} @ivar observer: The observer that this logger will send events to.

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)
consider_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_id)
put_treasure_map_on_node(node, map_id, 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)
icon_from_checksum(checksum, nickname_metadata, number_of_nodes='Unknown number of ')
class FleetStateTracker

Bases: object

A representation of a fleet of NuCypher nodes.

most_recent_node_change = NO_KNOWN_NODES (b'2V@\xd6\x16\x113\x84')
snapshot_splitter = <bytestring_splitter.BytestringSplitter object>
log

A L{Logger} emits log messages to an observer. You should instantiate it as a class or module attribute, as documented in L{this module’s documentation <twisted.logger>}.

@type namespace: L{str} @ivar namespace: the namespace for this logger

@type source: L{object} @ivar source: The object which is emitting events via this logger

@type: L{ILogObserver} @ivar observer: The observer that this logger will send events to.

class FleetState(nickname, metadata, icon, nodes, updated)

Bases: tuple

property icon

Alias for field number 2

property metadata

Alias for field number 1

property nickname

Alias for field number 0

property nodes

Alias for field number 3

property updated

Alias for field number 4

property checksum
property nickname
property nickname_metadata
property icon
addresses()
icon_html()
snapshot()
record_fleet_state(additional_nodes_to_track=None)
start_tracking_state(additional_nodes_to_track=None)
sorted()
shuffled()
abridged_states_dict()
static abridged_state_details(state)
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
mature()
class Learner(domains: set, 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)

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 = 1
node_splitter = <bytestring_splitter.BytestringSplitter object>
version_splitter = <bytestring_splitter.BytestringSplitter object>
tracker_class

alias of FleetStateTracker

invalid_metadata_message = "{} has invalid metadata. The node's stake may have ended, or it is transitioning to a new interface. Ignoring."
unknown_version_message = "{} purported to be of version {}, but we're only version {}. Is there a new version of NuCypher?"
really_unknown_version_message = "Unable to glean address from node that perhaps purported to be version {}. We're only version {}."
fleet_state_icon = ''
exception NotEnoughNodes

Bases: RuntimeError

exception NotEnoughTeachers

Bases: nucypher.network.nodes.Learner.NotEnoughNodes

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, retry_attempts: int = 3)

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

read_nodes_from_storage()None
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(*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: Set)
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: nucypher.network.nodes.Teacher, message_kit: Union[nucypher.crypto.kits.PolicyMessageKit, bytes], signature: umbral.signing.Signature)
learn_from_teacher_node(eager=False)

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

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

Bases: object

TEACHER_VERSION = 1
log

A L{Logger} emits log messages to an observer. You should instantiate it as a class or module attribute, as documented in L{this module’s documentation <twisted.logger>}.

@type namespace: L{str} @ivar namespace: the namespace for this logger

@type source: L{object} @ivar source: The object which is emitting events via this logger

@type: L{ILogObserver} @ivar observer: The observer that this logger will send events to.

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 IsFromTheFuture

Bases: TypeError

Raised when deserializing a Character from a future 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_html()
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
class ProxyRESTServer(rest_host: str, rest_port: int, hosting_power=None, rest_app=None, datastore=None)

Bases: object

SERVER_VERSION = 1
log

A L{Logger} emits log messages to an observer. You should instantiate it as a class or module attribute, as documented in L{this module’s documentation <twisted.logger>}.

@type namespace: L{str} @ivar namespace: the namespace for this logger

@type source: L{object} @ivar source: The object which is emitting events via this logger

@type: L{ILogObserver} @ivar observer: The observer that this logger will send events to.

rest_url()
make_rest_app(db_filepath: str, this_node, serving_domains, log=<Logger 'http-application-layer'>) → Tuple
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.