nucypher.network

Subpackages

• nucypher.network.nicknames

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.