Config

class nucypher.config.node.NodeConfiguration(config_root: str = None, config_file_location: str = None, dev_mode: bool = False, federated_only: bool = False, is_me: bool = True, checksum_address: str = None, crypto_power: nucypher.crypto.powers.CryptoPower = None, keyring: nucypher.config.keyring.NucypherKeyring = None, keyring_dir: str = None, learn_on_same_thread: bool = False, abort_on_learning_error: bool = False, start_learning_now: bool = True, rest_host: str = None, rest_port: int = None, controller_port: int = None, tls_curve: cryptography.hazmat.primitives.asymmetric.ec.EllipticCurve = None, certificate: cryptography.x509.base.Certificate = None, domains: Set[str] = None, interface_signature: umbral.signing.Signature = None, network_middleware: nucypher.network.middleware.RestMiddleware = None, known_nodes: set = None, node_storage: nucypher.config.storages.NodeStorage = None, reload_metadata: bool = True, save_metadata: bool = True, poa: bool = False, provider_uri: str = None, provider_process=None, registry_source: str = None, registry_filepath: str = None, download_registry: bool = True)[source]

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

exception ConfigurationError[source]
exception InvalidConfiguration[source]
NODE_DESERIALIZER()

Binary data of hexadecimal representation.

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

NODE_SERIALIZER()

Hexadecimal representation of binary data.

The return value is a bytes object.

exception NoConfigurationRoot[source]
connect_to_blockchain(enode: str = None, recompile_contracts: bool = False, full_sync: bool = False) → None[source]
Parameters
  • enode – ETH seednode or bootnode enode address to start learning from, i.e. ‘enode://e54eebad24dc…e1f6d246bea455@52.71.255.237:30303’

  • recompile_contracts – Recompile all contracts on connection.

Returns

None

connect_to_contracts() → None[source]

Initialize contract agency and set them on config

destroy() → None[source]

Parse a node configuration and remove all associated files from the filesystem

property dynamic_payload

Exported dynamic configuration values for initializing Ursula

classmethod from_configuration_file(filepath: str = None, provider_process=None, **overrides) → nucypher.config.node.NodeConfiguration[source]

Initialize a NodeConfiguration from a JSON file.

classmethod generate(password: str, *args, **kwargs)[source]

Shortcut: Hook-up a new initial installation and write configuration file to the disk

classmethod generate_runtime_filepaths(config_root: str) → dict[source]

Dynamically generate paths based on configuration root directory

initialize(password: str, download_registry: bool = True) → str[source]

Initialize a new configuration and write installation files to disk.

produce(**overrides)[source]

Initialize a new character instance and return it.

property static_payload

Exported static configuration values for initializing Ursula

to_configuration_file(filepath: str = None) → str[source]

Write the static_payload to a JSON file.

class nucypher.config.characters.AliceConfiguration(m: int = None, n: int = None, rate: int = None, first_period_rate: float = None, duration: int = None, *args, **kwargs)[source]
class Alice(checksum_address: str = None, m: int = None, n: int = None, rate: int = None, duration: int = None, first_period_rate: float = None, timeout: int = 10, is_me: bool = True, federated_only: bool = False, network_middleware=None, controller=True, policy_agent=None, *args, **kwargs)
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

create_policy(bob: nucypher.characters.lawful.Bob, label: bytes, handpicked_ursulas: set = None, **policy_params)

Create a Policy to share uri with bob. Generates KFrags and attaches them.

decrypt_message_kit(message_kit: nucypher.crypto.kits.UmbralMessageKit, 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: int = None, expiration: maya.core.MayaDT = None, value: int = None, rate: int = None, first_period_value: int = None, first_period_rate: float = None) → dict

Construct policy creation from parameters or overrides.

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.

property static_payload

Exported static configuration values for initializing Ursula

class nucypher.config.characters.BobConfiguration(config_root: str = None, config_file_location: str = None, dev_mode: bool = False, federated_only: bool = False, is_me: bool = True, checksum_address: str = None, crypto_power: nucypher.crypto.powers.CryptoPower = None, keyring: nucypher.config.keyring.NucypherKeyring = None, keyring_dir: str = None, learn_on_same_thread: bool = False, abort_on_learning_error: bool = False, start_learning_now: bool = True, rest_host: str = None, rest_port: int = None, controller_port: int = None, tls_curve: cryptography.hazmat.primitives.asymmetric.ec.EllipticCurve = None, certificate: cryptography.x509.base.Certificate = None, domains: Set[str] = None, interface_signature: umbral.signing.Signature = None, network_middleware: nucypher.network.middleware.RestMiddleware = None, known_nodes: set = None, node_storage: nucypher.config.storages.NodeStorage = None, reload_metadata: bool = True, save_metadata: bool = True, poa: bool = False, provider_uri: str = None, provider_process=None, registry_source: str = None, registry_filepath: str = None, download_registry: bool = True)[source]
class Bob(controller=True, *args, **kwargs)
exception IncorrectCFragsReceived(evidence: List)

Raised when Bob detects incorrect CFrags returned by some Ursulas

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.

get_treasure_map_from_known_ursulas(network_middleware, map_id)

Iterate through the nodes we know, asking for the TreasureMap. Return the first one who has it.

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.

class nucypher.config.characters.FelixConfiguration(db_filepath: str = None, *args, **kwargs)[source]
class Felix(db_filepath: str, rest_host: str, rest_port: int, crash_on_error: bool = False, economics: nucypher.blockchain.economics.TokenEconomics = None, distribute_ether: bool = True, *args, **kwargs)

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.

exception NoDatabase
airdrop_tokens()

Calculate airdrop eligibility via faucet registration and transfer tokens to selected recipients.

start_distribution(now: bool = True) → bool

Start token distribution

stop_distribution() → bool

Start token distribution

property static_payload

Exported static configuration values for initializing Ursula

class nucypher.config.characters.UrsulaConfiguration(dev_mode: bool = False, db_filepath: str = None, *args, **kwargs)[source]
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, decentralized_identity_evidence: bytes = NOT_SIGNED, checksum_address: str = None, 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)
exception NotEnoughUrsulas

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
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.

work_orders(bob=None)

TODO: This is better written as a model method for Ursula’s datastore.

destroy() → None[source]

Parse a node configuration and remove all associated files from the filesystem

property dynamic_payload

Exported dynamic configuration values for initializing Ursula

generate_runtime_filepaths(config_root: str) → dict[source]

Dynamically generate paths based on configuration root directory

produce(**overrides)[source]

Produce a new Ursula from configuration

property static_payload

Exported static configuration values for initializing Ursula

class nucypher.config.storages.ForgetfulNodeStorage(*args, **kwargs)[source]
all(federated_only: bool, certificates_only: bool = False) → set[source]

Return s set of all stored nodes

clear(metadata: bool = True, certificates: bool = True) → None[source]

Forget all stored nodes and certificates

classmethod from_payload(payload: dict, *args, **kwargs) → nucypher.config.storages.ForgetfulNodeStorage[source]

Alternate constructor to create a storage instance from JSON-like configuration

get(federated_only: bool, host: str = None, checksum_address: str = None, certificate_only: bool = False)[source]

Retrieve a single stored node

initialize() → bool[source]

Returns True if initialization was successful

remove(checksum_address: str, metadata: bool = True, certificate: bool = True) → Tuple[bool, str][source]

Remove a single stored node

store_node_metadata(node, filepath: str = None)[source]

Save a single node’s metadata and tls certificate

class nucypher.config.storages.LocalFileBasedNodeStorage(config_root: str = None, storage_root: str = None, metadata_dir: str = None, certificates_dir: str = None, *args, **kwargs)[source]
exception NoNodeMetadataFileFound[source]
all(federated_only: bool, certificates_only: bool = False) → Set[Union[Any, cryptography.x509.base.Certificate]][source]

Return s set of all stored nodes

clear(metadata: bool = True, certificates: bool = True) → None[source]

Forget all stored nodes and certificates

classmethod from_payload(payload: dict, *args, **kwargs) → nucypher.config.storages.LocalFileBasedNodeStorage[source]

Instantiate a storage object from a dictionary

get(checksum_address: str, federated_only: bool, certificate_only: bool = False)[source]

Retrieve a single stored node

initialize() → bool[source]

One-time initialization steps to establish a node storage backend

remove(checksum_address: str, metadata: bool = True, certificate: bool = True) → None[source]

Remove a single stored node

store_node_metadata(node, filepath: str = None) → str[source]

Save a single node’s metadata and tls certificate

class nucypher.config.storages.NodeStorage(federated_only: bool, character_class=None, serializer: Callable = <built-in function hexlify>, deserializer: Callable = <built-in function unhexlify>)[source]
NODE_DESERIALIZER()

Binary data of hexadecimal representation.

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

NODE_SERIALIZER()

Hexadecimal representation of binary data.

The return value is a bytes object.

exception NodeStorageError[source]
exception UnknownNode[source]
abstract all(federated_only: bool, certificates_only: bool = False) → set[source]

Return s set of all stored nodes

abstract clear() → bool[source]

Remove all stored nodes

abstract classmethod from_payload(data: dict, *args, **kwargs) → nucypher.config.storages.NodeStorage[source]

Instantiate a storage object from a dictionary

abstract get(checksum_address: str, federated_only: bool)[source]

Retrieve a single stored node

abstract initialize()[source]

One-time initialization steps to establish a node storage backend

abstract remove(checksum_address: str) → bool[source]

Remove a single stored node

abstract store_node_metadata(node, filepath: str = None) → str[source]

Save a single node’s metadata and tls certificate

class nucypher.config.storages.TemporaryFileBasedNodeStorage(*args, **kwargs)[source]
initialize() → bool[source]

One-time initialization steps to establish a node storage backend