class Character(domain: str, eth_provider_uri: str = None, known_node_class: object = None, is_me: bool = True, checksum_address: str = None, network_middleware: = None, keystore: nucypher.crypto.keystore.Keystore = None, crypto_power: nucypher.crypto.powers.CryptoPower = None, crypto_power_ups: List[nucypher.crypto.powers.CryptoPowerUp] = None, signer: nucypher.blockchain.eth.signers.base.Signer = None, registry: nucypher.blockchain.eth.registry.BaseContractRegistry = None, include_self_in_the_state: bool = False, *args, **kwargs)


A base-class for any character in our cryptography protocol narrative.

property name
property stamp
property canonical_address
classmethod from_config(config, **overrides)nucypher.characters.base.Character
classmethod from_public_keys(powers_and_material: Dict = None, verifying_key: Optional[umbral.PublicKey] = None, encrypting_key: Optional[umbral.PublicKey] = None, *args, **kwargs)nucypher.characters.base.Character

Sometimes we discover a Character and, at the same moment, learn the public parts of more of their powers. Here, we take a Dict (powers_and_material) in the format {CryptoPowerUp class: material}, where material can be bytes or umbral.PublicKey.

Each item in the collection will have the CryptoPowerUp instantiated with the given material, and the resulting CryptoPowerUp instance consumed by the Character.

Alternatively, you can pass directly a verifying public key (for SigningPower) and/or an encrypting public key (for DecryptionPower).

store_metadata(filepath: pathlib.Path)pathlib.Path

Save this node to the disk. :param filepath: Output filepath to save node metadata. :return: Output filepath

public_keys(power_up_class: ClassVar)

Pass a power_up_class, get the public material for this Character which corresponds to that class - whatever type of object that may be.

If the Character doesn’t have the power corresponding to that class, raises the appropriate PowerUpError (ie, NoSigningPower or NoDecryptingPower).

class Alice(is_me: bool = True, eth_provider_uri: str = None, signer=None, checksum_address: Optional[NewType.<locals>.new_type] = None, threshold: Optional[int] = None, shares: Optional[int] = None, rate: int = None, duration: int = None, payment_method: nucypher.policy.payment.PaymentMethod = None, store_policy_credentials: bool = None, timeout: int = 10, network_middleware: = None, *args, **kwargs)

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

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

Adds a Policy object that is active on the NuCypher network to Alice’s active_policies dictionary by the policy ID.

generate_kfrags(bob: nucypher.characters.lawful.Bob, label: bytes, threshold: int = None, shares: 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.

  • 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

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.

generate_policy_parameters(threshold: Optional[int] = None, shares: Optional[int] = None, duration: Optional[int] = None, commencement: Optional[maya.core.MayaDT] = None, expiration: Optional[maya.core.MayaDT] = None, value: Optional[int] = None, rate: Optional[int] = None, payment_method: Optional[nucypher.policy.payment.PaymentMethod] = None)dict

Construct policy creation from default parameters or overrides.

grant(bob: nucypher.characters.lawful.Bob, label: bytes, ursulas: set = None, timeout: int = None, **policy_params)
get_policy_encrypting_key_from_label(label: bytes)umbral.PublicKey
revoke(policy: nucypher.policy.policies.Policy, onchain: bool = True, offchain: bool = True) → Tuple[web3.types.TxReceipt, Dict[NewType.<locals>.new_type, Tuple[Revocation, Exception]]]
decrypt_message_kit(label: bytes, message_kit: nucypher_core.MessageKit) → List[bytes]

Decrypt this Alice’s own encrypted data.

I/O signatures match Bob’s retrieve interface.

class Bob(is_me: bool = True, verify_node_bonding: bool = False, eth_provider_uri: str = None, *args, **kwargs)

Bases: nucypher.characters.base.Character

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'
exception IncorrectCFragsReceived(evidence: List)

Bases: Exception

Raised when Bob detects incorrect CFrags returned by some Ursulas

retrieve(message_kits: Sequence[Union[nucypher_core.MessageKit, nucypher.policy.kits.PolicyMessageKit]], alice_verifying_key: umbral.PublicKey, encrypted_treasure_map: nucypher_core.EncryptedTreasureMap, publisher_verifying_key: Optional[umbral.PublicKey] = None, **context) → List[nucypher.policy.kits.PolicyMessageKit]

Attempts to retrieve reencrypted capsule fragments corresponding to given message kits from Ursulas.

Accepts both “clean” message kits (obtained from a side channel) and “loaded” ones (with earlier retrieved capsule frags attached, along with the addresses of Ursulas they were obtained from).

Returns a list of loaded message kits corresponding to the input list, with the kits containing the capsule fragments obtained during the retrieval. These kits can be used as an external cache to preserve the cfrags between several retrieval attempts.

retrieve_and_decrypt(*args, **kwds) → List[bytes]

Attempts to retrieve reencrypted capsule fragments from Ursulas and decrypt the ciphertexts in the given message kits.

See retrieve() for the parameter list.

class Ursula(rest_host: str, rest_port: int, domain: str, is_me: bool = True, certificate: Optional[cryptography.x509.base.Certificate] = None, certificate_filepath: Optional[pathlib.Path] = None, availability_check: bool = False, metadata: Optional[nucypher_core.NodeMetadata] = None, checksum_address: Optional[NewType.<locals>.new_type] = None, operator_address: Optional[NewType.<locals>.new_type] = None, client_password: Optional[str] = None, operator_signature_from_metadata=NOT_SIGNED, eth_provider_uri: Optional[str] = None, payment_method: Union[nucypher.policy.payment.PaymentMethod, nucypher.policy.payment.ContractPayment, None] = None, abort_on_learning_error: bool = False, crypto_power=None, known_nodes: Iterable[] = None, **character_kwargs)

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

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

Bases: Exception

property operator_signature
property operator_address
run(emitter: nucypher.utilities.emitters.StdoutEmitter = None, discovery: bool = True, availability: bool = False, worker: bool = True, hendrix: bool = True, start_reactor: bool = True, prometheus_config: PrometheusMetricsConfig = None, preflight: bool = True, block_until_ready: bool = True, eager: bool = False)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 #

property rest_interface
property operator_signature_from_metadata
property timestamp
classmethod from_metadata_bytes(metadata_bytes)
classmethod from_rest_url(network_middleware:, host: str, port: int)
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.

classmethod seednode_for_network(network: str)nucypher.characters.lawful.Ursula

Returns a default seednode ursula for a given network.

classmethod from_teacher_uri(teacher_uri: str, min_stake: int, network_middleware: = None, registry: nucypher.blockchain.eth.registry.BaseContractRegistry = None, retry_attempts: int = 2, retry_interval: int = 2)nucypher.characters.lawful.Ursula
classmethod from_seed_and_stake_info(seed_uri: str, minimum_stake: int = 0, registry: nucypher.blockchain.eth.registry.BaseContractRegistry = None, network_middleware: = None) → Union[nucypher.characters.lawful.Ursula,]
classmethod from_storage(node_storage: nucypher.config.storages.NodeStorage, checksum_adress: str)nucypher.characters.lawful.Ursula
property rest_url
property rest_app
status_info(omit_known_nodes: bool = False)nucypher.characters.lawful.LocalUrsulaStatus
class LocalUrsulaStatus(nickname, staker_address, operator_address, rest_url, timestamp, domain, version, fleet_state, previous_fleet_states, known_nodes, balance_eth)

Bases: tuple

property nickname

Alias for field number 0

property staker_address

Alias for field number 1

property operator_address

Alias for field number 2

property rest_url

Alias for field number 3

property timestamp

Alias for field number 4

property domain

Alias for field number 5

property version

Alias for field number 6

property fleet_state

Alias for field number 7

property previous_fleet_states

Alias for field number 8

property known_nodes

Alias for field number 9

property balance_eth

Alias for field number 10

to_json() → Dict[str, Any]
class Enrico(policy_encrypting_key: umbral.PublicKey)

Bases: object

A data source that encrypts data for some policy’s public key

banner = '\n ___ \n )_ _ _ o _ _ \n(__ ) ) ) ( (_ (_) \n\nthe Encryptor.\n{}\n'
encrypt_message(plaintext: bytes, conditions: Optional[List[Union[nucypher.policy.conditions.types.OperatorDict, nucypher.policy.conditions.types.TimeConditionDict, nucypher.policy.conditions.types.RPCConditionDict, nucypher.policy.conditions.types.ContractConditionDict]]] = None) → nucypher_core.MessageKit
classmethod from_alice(alice: nucypher.characters.lawful.Alice, label: bytes)
  • alice – Not a stranger. This is your Alice who will derive the policy keypair, leaving Enrico with the public part.

  • label – The label with which to derive the key.


property policy_pubkey
class Vladimir(*args, **kwargs)

Bases: nucypher.characters.lawful.Ursula

The power of Ursula, but with a heart forged deep in the mountains of Microsoft or a State Actor or whatever.

fraud_address = '0xbad022A87Df21E4c787C7B1effD5077014b8CC45'
fraud_key = 'a75d701cc4199f7646909d15f22e2e0ef6094b3e2aa47a188f35f47e8932a7b9'
classmethod from_target_ursula(target_ursula: nucypher.characters.lawful.Ursula, substitute_verifying_key: bool = False, sign_metadata: bool = False)nucypher.characters.unlawful.Vladimir

Sometimes Vladimir seeks to attack or imitate a specific target Ursula.

TODO: This is probably a more instructive method if it takes a bytes representation instead of the entire Ursula.

classmethod attach_transacting_key(blockchain)

Upload Vladimir’s ETH keys to the keychain via web3.

class Amonia(is_me: bool = True, eth_provider_uri: str = None, signer=None, checksum_address: Optional[NewType.<locals>.new_type] = None, threshold: Optional[int] = None, shares: Optional[int] = None, rate: int = None, duration: int = None, payment_method: nucypher.policy.payment.PaymentMethod = None, store_policy_credentials: bool = None, timeout: int = 10, network_middleware: = None, *args, **kwargs)

Bases: nucypher.characters.lawful.Alice

Separated at birth, Alice’s sister is lighter than air and has a pungent smell.

classmethod from_lawful_alice(alice)
grant_without_paying(*args, **kwargs)

I take what I want for free.

circumvent_safegaurds_and_grant_without_paying(*args, **kwargs)

I am not Alice, and I needn’t abide by her sensibilities or raise her Exceptions.

Can I grant for free if I change the client code to my liking?