nucypher.config¶

Submodules¶

class BaseConfiguration(config_root: str = None, filepath: str = None, *args, **kwargs)¶

Bases: abc.ABC

Abstract base class for saving a JSON serializable version of the subclass’s attributes to the disk exported by static_payload, generating an optionally unique filename, and restoring a subclass instance from the written JSON file by passing the deserialized values to the subclass’s constructor.

Implementation:

NAME and def static_payload are required for subclasses, for example:

class MyItem(BaseConfiguration):
    _NAME = 'my-item'

AND

def static_payload(self) -> dict:
    payload = dict(**super().static_payload(), key=value)
    return payload

OR

def static_payload(self) -> dict:
    subclass_payload = {'key': 'value'}
    payload = {**super().static_payload(), **subclass_payload}
    return payload

Filepath Generation

Default behavior avoids overwriting an existing configuration file:

The name of the JSON file to write/read from is determined by NAME. When calling to_configuration_file.
If the default path (i.e. my-item.json) already exists and, optionally, override is set to False, then a modifer is appended to the name (i.e. my-item-<MODIFIER>.json).
If modifier is None and override is False, FileExistsError will be raised.

If the subclass implementation has a global unique identifier, an additional method override to to_configuration_file will automate the renaming process.

def to_configuration_file(*args, **kwargs) -> str:
    filepath = super().to_configuration_file(modifier=<MODIFIER>, *args, **kwargs)
    return filepath

NAME = NotImplemented¶

INDENTATION = 2¶

DEFAULT_CONFIG_ROOT = '/home/docs/.local/share/nucypher'¶

VERSION = NotImplemented¶

exception ConfigurationError¶: Bases: RuntimeError

exception InvalidConfiguration¶: Bases: nucypher.config.base.BaseConfiguration.ConfigurationError

exception NoConfigurationRoot¶: Bases: nucypher.config.base.BaseConfiguration.InvalidConfiguration

exception OldVersion¶: Bases: nucypher.config.base.BaseConfiguration.InvalidConfiguration

abstract static_payload() → dict ¶

Return a dictionary of JSON serializable configuration key/value pairs matching the input specification of this classes __init__.

Recommended subclass implementations:

` payload = dict(**super().static_payload(), key=value) return payload `

OR

` subclass_payload = {'key': 'value'} payload = {**super().static_payload(), **subclass_payload} return payload `

classmethod generate_filename(modifier: str = None) → str ¶

Generates the configuration filename with an optional modification string.

Parameters: modifier – String to modify default filename with.
Returns: The generated filepath string.

classmethod default_filepath(config_root: str = None) → str ¶

Generates the default configuration filepath for the class.

Returns: The generated filepath string

generate_filepath(filepath: str = None, modifier: str = None, override: bool = False) → str ¶

Generates a filepath for saving to writing to a configuration file.

Default behavior avoids overwriting an existing configuration file:

The filepath exists and a filename modifier is not provided, then FileExistsError will be raised.
The modified filepath exists, then FileExistsError will be raised.

To allow re-generation of an existing filepath, set override to True.

Parameters

filepath – A custom filepath to use for configuration.
modifier – A unique string to modify the filename if the file already exists.
override – Allow generation of an existing filepath.

Returns

The generated filepath.

classmethod peek(filepath: str, field: str) → Optional[str]¶

to_configuration_file(filepath: str = None, modifier: str = None, override: bool = False) → str ¶

classmethod from_configuration_file(filepath: str = None, **overrides) → nucypher.config.base.BaseConfiguration ¶

serialize(serializer=<function dumps>) → str ¶: Returns the JSON serialized output of static_payload

classmethod deserialize(payload: str, deserializer=<function loads>) → dict ¶: Returns the JSON deserialized content of payload

update(filepath: str = None, modifier: str = None, **updates) → None ¶

class UrsulaConfiguration(worker_address: str = None, dev_mode: bool = False, db_filepath: str = None, rest_host: str = None, rest_port: int = None, tls_curve: cryptography.hazmat.primitives.asymmetric.ec.EllipticCurve = None, certificate: cryptography.x509.base.Certificate = None, availability_check: bool = None, *args, **kwargs)¶

Bases: nucypher.config.node.CharacterConfiguration

class Ursula(rest_host: str, rest_port: int, domains: Set = None, certificate: cryptography.x509.base.Certificate = None, certificate_filepath: str = None, db_filepath: str = None, is_me: bool = True, interface_signature=None, timestamp=None, availability_check: bool = False, prune_datastore: bool = True, decentralized_identity_evidence: bytes = NOT_SIGNED, checksum_address: str = None, worker_address: str = None, block_until_ready: bool = True, work_tracker: nucypher.blockchain.eth.token.WorkTracker = None, start_working_now: bool = True, client_password: str = None, abort_on_learning_error: bool = False, federated_only: bool = False, start_learning_now: bool = None, crypto_power=None, tls_curve: cryptography.hazmat.primitives.asymmetric.ec.EllipticCurve = None, known_nodes: Iterable = None, **character_kwargs)¶

Bases: nucypher.network.nodes.Teacher, nucypher.characters.base.Character, nucypher.blockchain.eth.actors.Worker

exception NotEnoughUrsulas¶

Bases: nucypher.network.nodes.Learner.NotEnoughTeachers, nucypher.blockchain.eth.agents.StakingEscrowAgent.NotEnoughStakers

All Characters depend on knowing about enough Ursulas to perform their role. This exception is raised when a piece of logic can’t proceed without more Ursulas.

exception NotFound¶: Bases: Exception

banner = '\n\n\n ,ggg, gg \ndP""Y8a 88 ,dPYb, \nYb, `88 88 IP\'`Yb \n `" 88 88 I8 8I \n 88 88 I8 8\' \n 88 88 ,gggggg, ,g, gg gg I8 dP ,gggg,gg \n 88 88 dP""""8I ,8\'8, I8 8I I8dP dP" "Y8I \n 88 88 ,8\' 8I ,8\' Yb I8, ,8I I8P i8\' ,8I \n Y8b,____,d88,,dP Y8,,8\'_ 8) ,d8b, ,d8b,,d8b,_ ,d8, ,d8b,\n "Y888888P"Y88P `Y8P\' "YY8P8P8P\'"Y88P"`Y88P\'"Y88P"Y8888P"`Y8\n\n\nthe Untrusted Re-Encryption Proxy.\n{}\n'¶

classmethod batch_from_bytes(ursulas_as_bytes: Iterable[bytes], fail_fast: bool = False) → List[nucypher.characters.lawful.Ursula]¶

property datastore¶

classmethod from_bytes(ursula_as_bytes: bytes, version: int = INCLUDED_IN_BYTESTRING, fail_fast=False) → nucypher.characters.lawful.Ursula ¶

classmethod from_processed_bytes(**processed_objects)¶: A convenience method for completing the maturation of a NodeSprout. TODO: Either deprecate or consolidate this logic; it’s mostly just workarounds. NRN

classmethod from_rest_url(network_middleware: nucypher.network.middleware.RestMiddleware, host: str, port: int, certificate_filepath, *args, **kwargs)¶

classmethod from_seed_and_stake_info(seed_uri: str, federated_only: bool = False, minimum_stake: int = 0, registry: nucypher.blockchain.eth.registry.BaseContractRegistry = None, network_middleware: nucypher.network.middleware.RestMiddleware = None, *args, **kwargs) → nucypher.characters.lawful.Ursula ¶

classmethod from_seednode_metadata(seednode_metadata, *args, **kwargs)¶

Essentially another deserialization method, but this one doesn’t reconstruct a complete node from bytes; instead it’s just enough to connect to and verify a node.

NOTE: This is a federated only method.

classmethod from_storage(node_storage: nucypher.config.storages.NodeStorage, checksum_adress: str, federated_only: bool = False) → nucypher.characters.lawful.Ursula ¶

classmethod from_teacher_uri(federated_only: bool, teacher_uri: str, min_stake: int, network_middleware: nucypher.network.middleware.RestMiddleware = None, registry: nucypher.blockchain.eth.registry.BaseContractRegistry = None, retry_attempts: int = 2, retry_interval: int = 2) → nucypher.characters.lawful.Ursula ¶

get_deployer()¶

interface_info_with_metadata()¶

classmethod internal_splitter(splittable, partial=False)¶

property rest_app¶

rest_information()¶

property rest_interface¶

rest_server_certificate()¶

property rest_url¶

run(emitter: nucypher.characters.control.emitters.StdoutEmitter = None, hendrix: bool = True, learning: bool = True, availability: bool = True, worker: bool = True, pruning: bool = True, interactive: bool = False, start_reactor: bool = True, prometheus_config: PrometheusMetricsConfig = None) → None ¶: Schedule and start select ursula services, then optionally start the reactor.

stop(halt_reactor: bool = False) → None ¶: Stop services for partially or fully initialized characters. # CAUTION #

CHARACTER_CLASS¶: alias of nucypher.characters.lawful.Ursula

NAME = 'ursula'¶

DEFAULT_REST_HOST = '127.0.0.1'¶

DEFAULT_REST_PORT = 9151¶

DEFAULT_DEVELOPMENT_REST_PORT = 10151¶

DEFAULT_DB_NAME = 'ursula.db'¶

DEFAULT_AVAILABILITY_CHECKS = False¶

LOCAL_SIGNERS_ALLOWED = True¶

generate_runtime_filepaths(config_root: str) → dict ¶: Dynamically generate paths based on configuration root directory

generate_filepath(modifier: str = None, *args, **kwargs) → str ¶

Generates a filepath for saving to writing to a configuration file.

Default behavior avoids overwriting an existing configuration file:

The filepath exists and a filename modifier is not provided, then FileExistsError will be raised.
The modified filepath exists, then FileExistsError will be raised.

To allow re-generation of an existing filepath, set override to True.

Parameters

filepath – A custom filepath to use for configuration.
modifier – A unique string to modify the filename if the file already exists.
override – Allow generation of an existing filepath.

Returns

The generated filepath.

static_payload() → dict ¶: Exported static configuration values for initializing Ursula

property dynamic_payload¶: Exported dynamic configuration values for initializing Ursula

produce(**overrides)¶: Produce a new Ursula from configuration

attach_keyring(checksum_address: str = None, *args, **kwargs) → None ¶

write_keyring(password: str, **generation_kwargs) → nucypher.config.keyring.NucypherKeyring ¶

destroy() → None ¶: Parse a node configuration and remove all associated files from the filesystem

class AliceConfiguration(m: int = None, n: int = None, rate: int = None, duration_periods: int = None, *args, **kwargs)¶

Bases: nucypher.config.node.CharacterConfiguration

class Alice(is_me: bool = True, federated_only: bool = False, signer=None, checksum_address: str = None, client_password: str = None, cache_password: bool = False, m: int = None, n: int = None, rate: int = None, duration_periods: int = None, timeout: int = 10, network_middleware: nucypher.network.middleware.RestMiddleware = None, controller: bool = True, *args, **kwargs)¶

Bases: nucypher.characters.base.Character, nucypher.blockchain.eth.actors.BlockchainPolicyAuthor

add_active_policy(active_policy)¶: Adds a Policy object that is active on the NuCypher network to Alice’s active_policies dictionary by the policy ID. The policy ID is a Keccak hash of the policy label and Bob’s stamp bytes

banner = '\n\n / \\ | (_) ___ ___\n / _ \\ | | |/ __/ _ \\\n / ___ \\| | | (_| __/\n /_/ \\_|_|_|\\___\\___|\n\n the Authority.\n'¶

create_policy(bob: nucypher.characters.lawful.Bob, label: bytes, **policy_params)¶: Create a Policy so that Bob has access to all resources under label. Generates KFrags and attaches them.

decrypt_message_kit(message_kit: nucypher.crypto.kits.PolicyMessageKit, data_source: nucypher.characters.base.Character, label: bytes) → List[bytes]¶

Decrypt this Alice’s own encrypted data.

I/O signatures match Bob’s retrieve interface.

generate_kfrags(bob: nucypher.characters.lawful.Bob, label: bytes, m: int = None, n: int = None) → List¶

Generates re-encryption key frags (“KFrags”) and returns them.

These KFrags can be used by Ursula to re-encrypt a Capsule for Bob so that he can activate the Capsule.

Parameters

bob – Bob instance which will be able to decrypt messages re-encrypted with these kfrags.
m – Minimum number of kfrags needed to activate a Capsule.
n – Total number of kfrags to generate

generate_policy_parameters(m: int = None, n: int = None, duration_periods: int = None, expiration: maya.core.MayaDT = None, *args, **kwargs) → dict ¶: Construct policy creation from parameters or overrides.

get_policy_encrypting_key_from_label(label: bytes) → umbral.keys.UmbralPublicKey¶

grant(bob: nucypher.characters.lawful.Bob, label: bytes, handpicked_ursulas: set = None, discover_on_this_thread: bool = True, timeout: int = None, publish_treasure_map: bool = True, block_until_success_is_reasonably_likely: bool = True, **policy_params)¶

make_web_controller(crash_on_error: bool = False)¶

revoke(policy) → Dict¶: Parses the treasure map and revokes arrangements in it. If any arrangements can’t be revoked, then the node_id is added to a dict as a key, and the revocation and Ursula’s response is added as a value.

CHARACTER_CLASS¶: alias of nucypher.characters.lawful.Alice

NAME = 'alice'¶

DEFAULT_CONTROLLER_PORT = 8151¶

DEFAULT_M = 2¶

DEFAULT_N = 3¶

static_payload() → dict ¶: Exported static configuration values for initializing Ursula

write_keyring(password: str, **generation_kwargs) → nucypher.config.keyring.NucypherKeyring ¶

class BobConfiguration(emitter=None, config_root: str = None, filepath: str = None, dev_mode: bool = False, federated_only: bool = False, checksum_address: str = None, crypto_power: nucypher.crypto.powers.CryptoPower = None, keyring: nucypher.config.keyring.NucypherKeyring = None, keyring_root: str = None, learn_on_same_thread: bool = False, abort_on_learning_error: bool = False, start_learning_now: bool = True, controller_port: int = None, domains: Set[str] = None, interface_signature: umbral.signing.Signature = None, network_middleware: nucypher.network.middleware.RestMiddleware = None, lonely: bool = False, known_nodes: set = None, node_storage: nucypher.config.storages.NodeStorage = None, reload_metadata: bool = True, save_metadata: bool = True, poa: bool = None, light: bool = False, sync: bool = False, provider_uri: str = None, provider_process=None, gas_strategy: Union[Callable, str] = 'fast', signer_uri: str = None, registry: nucypher.blockchain.eth.registry.BaseContractRegistry = None, registry_filepath: str = None)¶

Bases: nucypher.config.node.CharacterConfiguration

class Bob(controller: bool = True, *args, **kwargs)¶

Bases: nucypher.characters.base.Character

exception IncorrectCFragsReceived(evidence: List)¶

Bases: Exception

Raised when Bob detects incorrect CFrags returned by some Ursulas

banner = '\n\noooooooooo oooo \n 888 888 ooooooo 888ooooo \n 888oooo88 888 888 888 888\n 888 888 888 888 888 888\no888ooo888 88ooo88 o888ooo88 \n\nthe BUIDLer.\n'¶

construct_hrac_and_map_id(verifying_key, label)¶

construct_policy_hrac(verifying_key: Union[bytes, umbral.keys.UmbralPublicKey], label: bytes) → bytes ¶

follow_treasure_map(treasure_map=None, map_id=None, block=False, new_thread=False, timeout=10, allow_missing=0)¶

Follows a known TreasureMap, looking it up by map_id.

Determines which Ursulas are known and which are unknown.

If block, will block until either unknown nodes are discovered or until timeout seconds have elapsed. After timeout seconds, if more than allow_missing nodes are still unknown, raises NotEnoughUrsulas.

If block and new_thread, does the same thing but on a different thread, returning a Deferred which fires after the blocking has concluded.

Otherwise, returns (unknown_nodes, known_nodes).

# TODO: Check if nodes are up, declare them phantom if not. 567

get_reencrypted_cfrags(work_order, retain_cfrags=False)¶

get_treasure_map(alice_verifying_key, label)¶

get_treasure_map_from_known_ursulas(network_middleware, map_id, timeout=3)¶: Iterate through the nodes we know, asking for the TreasureMap. Return the first one who has it.

join_policy(label, alice_verifying_key, node_list=None, block=False)¶

make_compass_for_alice(alice)¶

make_web_controller(crash_on_error: bool = False)¶

matching_nodes_among(nodes: nucypher.acumen.perception.FleetSensor, no_less_than=7)¶

peek_at_treasure_map(treasure_map=None, map_id=None)¶

Take a quick gander at the TreasureMap matching map_id to see which nodes are already known to us.

Don’t do any learning, pinging, or anything other than just seeing whether we know or don’t know the nodes.

Return two sets: nodes that are unknown to us, nodes that are known to us.

retrieve(*message_kits: nucypher.crypto.kits.PolicyMessageKit, alice_verifying_key: umbral.keys.UmbralPublicKey = None, label: bytes = None, enrico: Enrico = None, retain_cfrags: bool = False, use_attached_cfrags: bool = False, use_precedent_work_orders: bool = False, policy_encrypting_key: umbral.keys.UmbralPublicKey = None, treasure_map: Union[TreasureMap, bytes] = None)¶

work_orders_for_capsules(*capsules, alice_verifying_key: umbral.keys.UmbralPublicKey = None, map_id: str = None, treasure_map: TreasureMap = None, num_ursulas: int = None)¶

CHARACTER_CLASS¶: alias of nucypher.characters.lawful.Bob

NAME = 'bob'¶

DEFAULT_CONTROLLER_PORT = 7151¶

write_keyring(password: str, **generation_kwargs) → nucypher.config.keyring.NucypherKeyring ¶

class FelixConfiguration(db_filepath: str = None, rest_host: str = None, rest_port: int = None, tls_curve: cryptography.hazmat.primitives.asymmetric.ec.EllipticCurve = None, certificate: cryptography.x509.base.Certificate = None, *args, **kwargs)¶

Bases: nucypher.config.node.CharacterConfiguration

class Felix(db_filepath: str, rest_host: str, rest_port: int, client_password: str = None, crash_on_error: bool = False, distribute_ether: bool = True, registry: nucypher.blockchain.eth.registry.BaseContractRegistry = None, *args, **kwargs)¶

Bases: nucypher.characters.base.Character, nucypher.blockchain.eth.actors.NucypherTokenActor

A NuCypher ERC20 faucet / Airdrop scheduler.

Felix is a web application that gives NuCypher testnet tokens to registered addresses with a scheduled reduction of disbursement amounts, and an HTTP endpoint for handling new address registration.

The main goal of Felix is to provide a source of testnet tokens for research and the development of production-ready nucypher dApps.

BATCH_SIZE = 10¶

DISBURSEMENT_INTERVAL = 8760¶

DISTRIBUTION_INTERVAL = 60¶

ETHER_AIRDROP_AMOUNT = 100000000000000000¶

LEARNING_TIMEOUT = 30¶

MAX_INDIVIDUAL_REGISTRATIONS = 3¶

MINIMUM_DISBURSEMENT = 1000000000000000000¶

MULTIPLIER = Decimal('0.9')¶

exception NoDatabase¶: Bases: RuntimeError

STAGING_DELAY = 10¶

airdrop_tokens()¶: Calculate airdrop eligibility via faucet registration and transfer tokens to selected recipients.

create_tables() → None ¶

make_web_app()¶

start(host: str, port: int, web_services: bool = True, distribution: bool = True, crash_on_error: bool = False)¶

start_distribution(now: bool = True) → bool ¶: Start token distribution

start_learning_loop(now=False)¶: Felix needs to not even be a Learner, but since it is at the moment, it certainly needs not to learn.

stop_distribution() → bool ¶: Start token distribution

CHARACTER_CLASS¶: alias of nucypher.characters.chaotic.Felix

NAME = 'felix'¶

DEFAULT_DB_NAME = 'felix.db'¶

DEFAULT_DB_FILEPATH = '/home/docs/.local/share/nucypher/felix.db'¶

DEFAULT_REST_PORT = 6151¶

DEFAULT_LEARNER_PORT = 9151¶

DEFAULT_REST_HOST = '127.0.0.1'¶

static_payload() → dict ¶: Exported static configuration values for initializing Ursula

write_keyring(password: str, **generation_kwargs) → nucypher.config.keyring.NucypherKeyring ¶

class StakeHolderConfiguration(checksum_addresses: set = None, *args, **kwargs)¶

Bases: nucypher.config.node.CharacterConfiguration

NAME = 'stakeholder'¶

CHARACTER_CLASS¶: alias of nucypher.blockchain.eth.actors.StakeHolder

static_payload() → dict ¶: Values to read/write from stakeholder JSON configuration files

property dynamic_payload¶: Exported dynamic configuration values for initializing Ursula

classmethod assemble(filepath: str = None, **overrides) → dict ¶: Warning: This method allows mutation and may result in an inconsistent configuration.

classmethod generate_runtime_filepaths(config_root: str) → dict ¶: Dynamically generate paths based on configuration root directory

initialize(password: str = None) → str ¶: Initialize a new configuration and write installation files to disk.

classmethod generate(*args, **kwargs)¶: Shortcut: Hook-up a new initial installation and write configuration file to the disk

to_configuration_file(override: bool = True, *args, **kwargs) → str ¶

SeednodeMetadata¶: alias of nucypher.config.constants.seednode

exception PrivateKeyExistsError¶: Bases: RuntimeError

exception ExistingKeyringError¶: Bases: RuntimeError

unlock_required(func)¶: Method decorator

class NucypherKeyring(account: str, keyring_root: str = None, root_key_path: str = None, pub_root_key_path: str = None, signing_key_path: str = None, pub_signing_key_path: str = None, delegating_key_path: str = None, tls_key_path: str = None, tls_certificate_path: str = None)¶

Bases: object

Handles keys for a single identity, recognized by account. Warning: This class handles private keys!

keyring
- .private
  
  key.priv
  
  key.priv.pem
- public
  
  key.pub
  
  cert.pem

MINIMUM_PASSWORD_LENGTH = 16¶

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 KeyringError¶: Bases: Exception

exception KeyringLocked¶: Bases: nucypher.config.keyring.NucypherKeyring.KeyringError

exception AuthenticationFailed¶: Bases: nucypher.config.keyring.NucypherKeyring.KeyringError

property checksum_address¶

property signing_public_key¶

property encrypting_public_key¶

property certificate_filepath¶

property keyring_root¶

property account¶

property is_unlocked¶

lock() → bool ¶: Make efforts to remove references to the cached key data

unlock(password: str) → bool ¶

derive_crypto_power(*args, **kwargs)¶

classmethod generate(checksum_address: str, password: str, encrypting: bool = True, rest: bool = False, host: str = None, curve: cryptography.hazmat.primitives.asymmetric.ec.EllipticCurve = None, keyring_root: str = None) → nucypher.config.keyring.NucypherKeyring ¶: Generates new encrypting, signing, and wallet keys encrypted with the password, respectively saving keyfiles on the local filesystem from default paths, returning the corresponding Keyring instance.

classmethod validate_password(password: str) → List¶

Validate a password and return True or raise an error with a failure reason.

NOTICE: Do not raise inside this function.

destroy()¶

class CharacterConfiguration(emitter=None, config_root: str = None, filepath: str = None, dev_mode: bool = False, federated_only: bool = False, checksum_address: str = None, crypto_power: nucypher.crypto.powers.CryptoPower = None, keyring: nucypher.config.keyring.NucypherKeyring = None, keyring_root: str = None, learn_on_same_thread: bool = False, abort_on_learning_error: bool = False, start_learning_now: bool = True, controller_port: int = None, domains: Set[str] = None, interface_signature: umbral.signing.Signature = None, network_middleware: nucypher.network.middleware.RestMiddleware = None, lonely: bool = False, known_nodes: set = None, node_storage: nucypher.config.storages.NodeStorage = None, reload_metadata: bool = True, save_metadata: bool = True, poa: bool = None, light: bool = False, sync: bool = False, provider_uri: str = None, provider_process=None, gas_strategy: Union[Callable, str] = 'fast', signer_uri: str = None, registry: nucypher.blockchain.eth.registry.BaseContractRegistry = None, registry_filepath: str = None)¶

Bases: nucypher.config.base.BaseConfiguration

‘Sideways Engagement’ of Character classes; a reflection of input parameters.

VERSION = 1¶

CHARACTER_CLASS = NotImplemented¶

DEFAULT_CONTROLLER_PORT = NotImplemented¶

DEFAULT_DOMAIN = 'mainnet'¶

DEFAULT_NETWORK_MIDDLEWARE¶: alias of nucypher.network.middleware.RestMiddleware

TEMP_CONFIGURATION_DIR_PREFIX = 'tmp-nucypher'¶

known_node_class¶: alias of nucypher.characters.lawful.Ursula

DEFAULT_GAS_STRATEGY = 'fast'¶

classmethod checksum_address_from_filepath(filepath: str) → str ¶

update(**kwargs) → None ¶

A facility for updating existing attributes on existing configuration instances.

Warning: This method allows mutation and may result in an inconsistent configuration.

classmethod generate(password: str, *args, **kwargs)¶: Shortcut: Hook-up a new initial installation and write configuration file to the disk

cleanup() → None ¶

property dev_mode¶

forget_nodes() → None ¶

destroy() → None ¶: Parse a node configuration and remove all associated files from the filesystem

generate_parameters(**overrides) → dict ¶: Warning: This method allows mutation and may result in an inconsistent configuration.

produce(**overrides) → NotImplemented¶: Initialize a new character instance and return it.

classmethod assemble(filepath: str = None, **overrides) → dict ¶: Warning: This method allows mutation and may result in an inconsistent configuration.

classmethod from_configuration_file(filepath: str = None, provider_process=None, **overrides) → nucypher.config.node.CharacterConfiguration ¶: Initialize a CharacterConfiguration from a JSON file.

validate() → bool ¶

static_payload() → dict ¶: Exported static configuration values for initializing Ursula

property dynamic_payload¶: Exported dynamic configuration values for initializing Ursula

generate_filepath(filepath: str = None, modifier: str = None, override: bool = False) → str ¶

Generates a filepath for saving to writing to a configuration file.

Default behavior avoids overwriting an existing configuration file:

The filepath exists and a filename modifier is not provided, then FileExistsError will be raised.
The modified filepath exists, then FileExistsError will be raised.

To allow re-generation of an existing filepath, set override to True.

Parameters

filepath – A custom filepath to use for configuration.
modifier – A unique string to modify the filename if the file already exists.
override – Allow generation of an existing filepath.

Returns

The generated filepath.

property runtime_filepaths¶

classmethod generate_runtime_filepaths(config_root: str) → dict ¶: Dynamically generate paths based on configuration root directory

attach_keyring(checksum_address: str = None, *args, **kwargs) → None ¶

derive_node_power_ups() → List[nucypher.crypto.powers.CryptoPowerUp]¶

initialize(password: str) → str ¶: Initialize a new configuration and write installation files to disk.

write_keyring(password: str, checksum_address: str = None, **generation_kwargs) → nucypher.config.keyring.NucypherKeyring ¶

classmethod load_node_storage(storage_payload: dict, federated_only: bool)¶

class NodeStorage(federated_only: bool, character_class=None, serializer: Callable = <built-in function hexlify>, deserializer: Callable = <built-in function unhexlify>, registry: nucypher.blockchain.eth.registry.BaseContractRegistry = None)¶

Bases: abc.ABC

NODE_SERIALIZER()¶

Hexadecimal representation of binary data.

The return value is a bytes object.

NODE_DESERIALIZER()¶

Binary data of hexadecimal representation.

hexstr must contain an even number of hex digits (upper or lower case).

TLS_CERTIFICATE_ENCODING = 'PEM'¶

TLS_CERTIFICATE_EXTENSION = '.pem'¶

exception NodeStorageError¶: Bases: Exception

exception UnknownNode¶: Bases: nucypher.config.storages.NodeStorage.NodeStorageError

exception InvalidNodeCertificate¶

Bases: RuntimeError

Raised when a TLS certificate is not a valid Teacher certificate.

abstract property source¶: Human readable source string

abstract store_node_certificate(certificate: cryptography.x509.base.Certificate) → str ¶

abstract store_node_metadata(node, filepath: str = None) → str ¶: Save a single node’s metadata and tls certificate

abstract generate_certificate_filepath(checksum_address: str) → str ¶

abstract payload() → dict ¶

abstract classmethod from_payload(data: dict, *args, **kwargs) → nucypher.config.storages.NodeStorage ¶: Instantiate a storage object from a dictionary

abstract initialize()¶: One-time initialization steps to establish a node storage backend

abstract all(federated_only: bool, certificates_only: bool = False) → set ¶: Return s set of all stored nodes

abstract get(checksum_address: str, federated_only: bool)¶: Retrieve a single stored node

abstract remove(checksum_address: str) → bool ¶: Remove a single stored node

abstract clear() → bool ¶: Remove all stored nodes

class ForgetfulNodeStorage(parent_dir: str = None, *args, **kwargs)¶

Bases: nucypher.config.storages.NodeStorage

property source¶: Human readable source string

all(federated_only: bool, certificates_only: bool = False) → set ¶: Return s set of all stored nodes

get(federated_only: bool, host: str = None, checksum_address: str = None, certificate_only: bool = False)¶: Retrieve a single stored node

forget() → bool ¶

store_node_certificate(certificate: cryptography.x509.base.Certificate)¶

store_node_metadata(node, filepath: str = None)¶: Save a single node’s metadata and tls certificate

generate_certificate_filepath(checksum_address: str) → str ¶

remove(checksum_address: str, metadata: bool = True, certificate: bool = True) → Tuple[bool, str]¶: Remove a single stored node

clear(metadata: bool = True, certificates: bool = True) → None ¶: Forget all stored nodes and certificates

payload() → dict ¶

classmethod from_payload(payload: dict, *args, **kwargs) → nucypher.config.storages.ForgetfulNodeStorage ¶: Alternate constructor to create a storage instance from JSON-like configuration

initialize() → bool ¶: Returns True if initialization was successful

class LocalFileBasedNodeStorage(config_root: str = None, storage_root: str = None, metadata_dir: str = None, certificates_dir: str = None, *args, **kwargs)¶

Bases: nucypher.config.storages.NodeStorage

exception NoNodeMetadataFileFound¶: Bases: FileNotFoundError, nucypher.config.storages.NodeStorage.UnknownNode

property source¶: Human readable source string

generate_certificate_filepath(checksum_address: str) → str ¶

all(federated_only: bool, certificates_only: bool = False) → Set[Union[Any, cryptography.x509.base.Certificate]]¶: Return s set of all stored nodes

get(checksum_address: str, federated_only: bool, certificate_only: bool = False)¶: Retrieve a single stored node

store_node_certificate(certificate: cryptography.x509.base.Certificate, force: bool = True)¶

store_node_metadata(node, filepath: str = None) → str ¶: Save a single node’s metadata and tls certificate

save_node(node, force) → Tuple[str, str]¶

remove(checksum_address: str, metadata: bool = True, certificate: bool = True) → None ¶: Remove a single stored node

clear(metadata: bool = True, certificates: bool = True) → None ¶: Forget all stored nodes and certificates

payload() → dict ¶

classmethod from_payload(payload: dict, *args, **kwargs) → nucypher.config.storages.LocalFileBasedNodeStorage ¶: Instantiate a storage object from a dictionary

initialize() → bool ¶: One-time initialization steps to establish a node storage backend

class TemporaryFileBasedNodeStorage(*args, **kwargs)¶

Bases: nucypher.config.storages.LocalFileBasedNodeStorage

initialize() → bool ¶: One-time initialization steps to establish a node storage backend