v5.1.0 (2021-04-15)


  • Improve UX for character CLI when there are multiple configuration files:
    • If there are multiple possible character configuration files prompt the user to choose

    • If there is only one character configuration file, even if not the default filename, use lone configuration without prompting and print to CLI. (#2617)


  • Ensure that correct configuration filepath is displayed when initializing characters, and add hint about using --config-file <FILE> for subsequent CLI commands if non-default filepath used. (#2617)

v5.0.2 (2021-04-14)


  • Fixed incorrect use of genesis value for seconds_per_period when estimating block number based on period number - applies to prometheus metrics collection and nucypher status events. (#2646)

v5.0.1 (2021-04-14)

No significant changes.

v5.0.0 (2021-04-14)


  • Increase period duration in contracts and handle migration of current stakes to new format. (#2549)

  • DAO proposal #1: Improve staker P/L by increasing period duration. (#2594)

  • Refinements for pool staking contract (#2596)

  • New standalone geth fullnode ansible playbook. (#2624)


  • Accommodate migrated period duration in CLI UX. (#2614)

  • cloudworkers more throughoughly cleans up diskspace before updates. (#2618)

  • Bob now accepts provider_uri as an optional parameter (#2626)

  • Add a default gas limit multiplier of 1.15 for all outgoing ETH transactions (#2637)

Improved Documentation

  • Document staking smart contract API and the base staking pool implementation (PoolingStakingContractV2). (#2597)


  • Change filepath delimiter to dot (“.”) in Card Storage API (#2628)

  • Use constant for loopback address across the codebase. (#2629)

v4.8.2 (2021-03-25)


  • Fixes ethereum account selection with ambiguous source in CLI. (#2615)

v4.8.1 (2021-03-24)


  • Add balance_eth, balance_nu, missing_commitments and last_committed_period to the /status REST endpoint. (#2611)

v4.8.0 (2021-03-23)


  • Expanded features for staker and status CLI:
    • Support substake inspection via nucypher status stakers –substakes.

    • Automated transaction series for inactive substake removal.

    • Display unlocked NU amount from stakers status.

    • Handle replacement of stuck withdraw transactions with –replace. (#2528)

  • Support extended period migration by nodes via work tracker. (#2607)


  • Improved import error feedback and default ssh key path in cloudworkers. (#2598)

  • Support geth 1.10.x - Remove chainID from transaction payloads. (#2603)

Improved Documentation

  • Document minimum approval and support requirements for NuCypher DAO. (#2599)

Deprecations and Removals

  • Deprecate worker IP address as environment variable (NUCYPHER_WORKER_IP_ADDRESS). (#2583)


  • Adjust Ursula.status_info() API to make it easier for nucypher-monitor to collect data. (#2574)

v4.7.1 (2021-03-02)


  • Fixed missing domain parameter causing Ursulas to fail on startup when prometheus is enabled. (#2589)

v4.7.0 (2021-03-02)


  • New preferable base pooling contract (#2544)

  • The output of nucypher stake events can be written to a csv file for simpler staker accounting. (#2548)

  • Simplifies CLI usage with optional interactive collection of all CLI parameters used during grant, encrypt, and retrieve. (#2551)

  • Improved status codes and error messages for various PRE http endpoints (#2562)

  • nucypher status events can now use event filters and be output to a csv file for simpler accounting. (#2573)


  • Properly handles public TLS certificate restoration; Simplify Ursula construction. (#2536)

  • Update the call to estimateGas() according to the new web3 API (#2543)

  • Ensure remote ethereum provider connection is automatically established with characters. Fixes default keyring filepath generation. (#2550)

  • Cache Alice’s transacting power for later activation. (#2555)

  • Prevent process hanging in the cases when the main thread finishes before the treasure map publisher (#2557)

Improved Documentation

  • Documentation overhaul with focus on staking node operation (#2463)

  • Expands Alice grant example using the python API. (#2554)

Deprecations and Removals

  • Deprecated StakingEscrow features to reduce code size: batch deposits, testContract flag, locking reStake. Deployment of StakingEscrow is split in two steps: initial step with stub and final step after all contracts. (#2518)


  • Refactor FleetSensor; add “/status/?omit_known_nodes=true” argument; prevent internal constants from leaking into the status page. (#2352)

  • WorkLock prometheus metrics are only collected on mainnet. (#2546)

  • Sister demo for Finnegan’s wake for use on lynx/goerli testnet. Alice and Bob API cleanup compelled by EthDenver 2021. (#2560)

  • Rework internal transaction signing API for improved thread saftey. (#2572)

  • new seed URL for mainnet cloudworkers CLI updates (#2576)

  • Extends probationary period for policy creation in the network to 2021-04-30 23:59:59 UTC. (#2585)

v4.6.0 (2021-01-26)


  • Introduces the Lynx testnet, a more stable environment to learn how to use NuCypher and integrate it into other apps. (#2537)

v4.5.4 (2021-01-22)


  • Fix wrong usage of net_version to identify the EthereumClient client chain. (#2484)

  • Use eth_chainId instead of net_version to maintain compatibility with geth. (#2533)

  • Fixed infinite loop during learning when timing out but known nodes exceeds target. (#2534)

v4.5.3 (2021-01-18)


  • Ensure minimum number of available peers for fleet-sourced IP determination and better handling of default teacher unavailability scenarios on startup (#2527)

v4.5.2 (2021-01-15)

No significant changes.

v4.5.1 (2021-01-15)

No significant changes.

v4.5.0 (2021-01-14)


  • Compare Ursula IP address with configuration values on startup to help ensure node availability. (#2462)

  • Arrangement proposals and policy enactment are performed in parallel, with more nodes being considered as some of the requests fail. This improves granting reliability. (#2482)


  • More logging added for arrangement proposal failures, and more suitable exceptions thrown. (#2479)

  • Ignore pending Ethereum transactions for purposes of gas estimation. (#2486)

  • Fix rtd build after #2477 (#2489)

  • (#2491, #2498)

  • Fix rtd build after #2477 and #2489 (#2492)

  • cloudworkers bugfixes, cli args refactor and new “cloudworkers stop” feature. (#2494)

  • Gentler handling of unsigned stamps from stranger Ursulas on status endpoint (#2515)

  • Restore the re-raising behavior in BlockchainInterface._handle_failed_transaction() (#2521)

Improved Documentation

  • Auto docs generation for smart contracts (#2477)

  • Add pricing protocol & economics paper to main repo readme and docs homepage. (#2520)

Deprecations and Removals

  • (#2470)

  • Deprecated manual worker commitments using the CLI. (#2507)


  • Relock dependencies and update relock script. (#2440)

  • Fixed failing readthedocs build due to dependency mismatches in docs requirements. (#2496)

  • (#2499)

  • Ensure that documentation dependencies are updated when standard/development dependencies are updated. (#2510)

v4.4.0 (2020-12-24)


  • Introduces “Character Cards” a serializable identity abstraction and ‘nucypher contacts’ CLI to support. (#2115)

    • nucypher cloudworkers now contains a complete and comprehensive set of features for easily managing, backing up and restoring one to many workers (#2365)

  • New composite gas strategy that uses the median from three different gas price oracles (currently, Etherchain, Upvest and, which behaves more robustly against sporadic errors in the oracles (e.g., spikes, stuck feeds). (#2420)

  • Improve gas strategy selection: Infura users now can choose between slow, medium and fast, and a maximum gas price can be configured with –max-gas-price. (#2445)


  • Slowly try more and more nodes if some of the initial draft for a policy were inaccessible. (#2416)

  • Fix bad cli handling in several cloudworkers commands, improved envvar handling. (#2475)


  • (#2244, #2483)

  • Solidity compilation refinements (#2461)

  • Deprecates internally managed geth process management (#2466)

  • Include checksum and IP addresses in exception messages for Rejected. (#2467)

  • Deprecates managed ethereum client syncing and stale interface methods (#2468)

  • Improves console messages for stakeholder CLI initialization and worker startup. (#2474)

  • Introduce a template to describe Pull Requests. (#2476)

v4.3.0 (2020-12-08)


  • Introduces shorthand options for –bob-verifying-key (-bvk), –bob-encrypting-key (-bek) and alice verifying key (-avk) for CLI commands. (#2459)

  • Complete interactive collection of policy parameters via alice grant CLI. (#2460)


  • Corrected minimum stake value for –min-stake CLI option (#2371)


  • Introduces a probationary period for policy creation in the network, until 2021-02-28 23:59:59 UTC. (#2431)

  • Supplies AccessDenied exception class for better incorrect password handling. (#2451)

  • Maintain compatibility with python 3.6 (removes re.Pattern annotations) (#2458)

v4.2.1 (2020-12-04)


  • Removes tests import from constants module causing pip installed versions to crash. (#2452)

v4.2.0 (2020-12-03)


  • Improve user experience when removing unused substakes (CLI and docs). (#2450)


  • Fix bug in deployer logic while transferring ownership of StakingInterfaceRouter (#2369)

  • Allow arbitrary decimal precision when entering NU amounts to nucypher CLI. (#2441)

Improved Documentation

  • Document usage of hardware wallets for signing. (#2346)

  • Improvements to the staking guide: extending description of winddown command, other minor corrections. (#2434)


  • Rework internal solidity compiler usage to implement “Standard JSON Compile”. (#2439)

  • Introduces –config-path and –logging-path CLI flags displaying default nucypher directories (#2446)

v4.1.2 (2020-11-09)


  • Added support for a user-provided gas price to the nucypher stake command, using --gas-price GWEI. (#2425)


  • Correct CLI problems when setting the min fee rate. Also, simplifies usage by expressing rates in GWEI. (#2390)

  • Tone-down learning logging messages even more (see issue #1712). Fixes some CLI and exception messages. (#2395)

  • Fixes logical bug in WorkTracker to ensure commitment transactions can only be issued once per period. (#2406)

  • Removes leftover imports of Twisted Logger, using instead our shim (Closes #2404). Also, changes NuCypher Logger behavior to always escape curly braces. (#2412)

  • Now BlockchainInterface.gas_strategy always has a value; previously it was possible to pass None via the constructor (e.g. if the config file had an explicit "null" value). (#2421)

  • Take advantage of the changes in PR#2410 by retrying worker commitments on failure (#2422)

  • Domain “leakage”, or nodes saving metadata about nodes from other domains (but never being able to verify them) was still possible because domain-checking only occurred in the high-level APIs (and not, for example, when checking metadata POSTed to the node_metadata_exchange endpoint). This fixes that (fixes #2417).

    Additionally, domains are no longer separated into “serving” or “learning”. Each Learner instance now has exactly one domain, and it is called domain. (#2423)


  • Updates contract registry after upgrade of StakingEscrow to v5.5.1, at behest of the DAO (proposal #0). (#2402)

  • Improved newsfragments README file to clarify release note entry naming convention. (#2415)

v4.1.1 (2020-10-29)


  • Add CLI functionality for the removal of unused (inactive) sub-stakes. Depending on the staker’s sub-stake configuration, this command can reduce the associated worker’s gas costs when making commitments. (#2384)


  • Automatically restart Ursula worker task on failure. (#2410)

Improved Documentation

  • Update global fee range documentation, including genesis values. (#2363)


  • Update Ursula network grant availability script for mainnet usage. (#2383)

  • GitHub Action to ensure that each pull request into main makes an associated release note entry. (#2396)

v4.1.0 (2020-10-19)


  • Temporary workaround for lack of single attribute for the value of “domain” in sprouts and mature nodes. (#2356)

  • Show the correct fleet state on Ursula status page. (#2368)

  • Don’t crash when handling failed transaction; reduce network learning messages. (#2375)

  • Reduce the greediness of prometheus metrics collection. (#2376)

  • Ensure minimum NU stake is allowed instead of stake creation failing for not enough tokens. (#2377)

  • Fixes to status page based on reworked design done in PR #2351. (#2378)

  • Track pending Ursula commitment transactions due to slower gas strategies. (#2389)

v4.0.1 (2020-10-14)


  • Set default teacher uri for mainnet. (#2367)

v4.0.0 (2020-10-14)

🚀 Mainnet Launch 🚀