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
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
Bases:
nucypher.network.middleware.RestMiddleware.UnexpectedResponse
Raised for HTTP 403
-
request_revocation
(ursula, revocation)¶
-
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
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
¶
-
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)¶
-
get_nodes_by_ids
(node_ids)¶
-
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.
-
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.
-
update_errors
(work_order: nucypher.network.retrieval.RetrievalWorkOrder, ursula_address: NewType.<locals>.new_type, error_message: str)¶
-
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
¶
-
property
-
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.
-
-
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
¶
-
shutdown_everything
(reason=None, halt_reactor=False)¶
-
property
running
¶
-
property
score
¶
-
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.
-