161 symmetric key pr2

[dan-da]

closes #161. obsoletes #169

This PR addresses review requests in #169 and goes further to simplify and improve the implementation.

Heres a list of changes since #169

code:
 * simplified `UtxoNotifyMethod` to `OnChain`, `OffChain`
 * simplified `UtxoNotifcation` to `OnChain(_)`, `OffChain(_)`
 * removed `UtxoNotifyMethodSpecifier`
 * change logic in `TxOutput::auto()`
 * add `KeyType` enum to improve abstraction
 * refactor common key logic into address::common
 * simplify WalletState::scan_for_announced_utxos()
 * simplify WalletState::find_spending_key_for_utxo()
 * add WalletState::get_all_known_spending_keys()
 * new param `owned_utxo_output_method` for `generate_tx_outputs()`
 * new param `change_key` for `create_transaction()
 * new param `key_type` for `next_receiving_address()` rpc
 * neptune-cli generate-wallet: remove display of first wallet addr
   as it should not be considered special/only.

docs:
 * document keys and addresses in mdbook
 * document utxo notifications in mdbook
 * add/update type/method doc-comments
 * add some missing module doc-comments

tests:
 * consolidate all key/addr tests into address_type::test
 * same test logic applies to both symmetric and generation keys
 * make all key tests into proptests (symmetric and generation)
 * make transaction_output tests more comprehensive

Here's how requests were addressed:

Please add a page to the documentation covering symmetric keys for change UTXOs.

Added a page about "Keys and Addresses" and another about "Utxo Notifications". Please review and feel free to edit, or send me your edits.

Avoid importing tools from generation_address in symmetric_key. Instead, factor them out to a helper module.

done. added address::common module.

UtxoNotifierMethodSpecifier and UtxoNotifierMethod seem similar and I wonder if they cannot be merged.

I got rid of UtxoNotifierMethodSpecifier. UtxoNotifyMethod and UtxoNotification are now simpler with just Onchain and OffChain variants.

Consider renaming SpendingKeyType to SpendingKey and generation_address::SpendingKey to generation_address::GenerationSpendingKey.

I forgot about this one. There is also ReceivingAddressType/ReceivingAddress. anyway, I can do that in a follow-up commit. either to this PR, or after merging.

edit: done.

Please convert the randomized tests in symmetric_key.rs into proptests. Have a look in primitive_witness.rs if you need something to pattern match on. (I realize there are plenty of tests out there that are randomized with thread_rng but I should like to convert those to proptests at some point. Let's not add to that conversion workload.)

done. all the tests for generation_address and symmetric have been moved into address_type and the same tests apply to both implementations. all tests that were in generation_address are now proptests.

Please add an integration test (not sure that's the right word) whereby you spawn two global states, one of which is a premine recipient whose sends some money to the other node and gets some change, and verify that the change is being observed and recovered correctly, even if the node in question reboots and loses everything but the seed phrase.

ok, I missed this one too. I will work on it tmw.

edit: done. please review. see module global_state_tests::restore_wallet

I'm making this a draft PR until the above two items are completed.

edit: ready for review.

[dan-da]

i think the build is failing in CI because of new rust 1.80. the time crate is generating an error. I will update to 1.80 and see if I can duplicate/fix.

[aszepieniec]

Excellent stuff. Very little to remark on. Green light for merging.

I added a commit for the requested description of generation addresses on asz/161_symmetric_key_pr2.