3.0.0 Changes

[yeastplume]

Outlining changes for 3.0.0, keeping this updated as I go for now

Inter-Wallet Compatibility

• For now, v3.0.0 wallets can exchange transactions with v2.x.x wallets, with the following caveats:

  • The v3.0.0 will not send to a v2.x.x wallet over http (including TOR) if a payment proof is requested.
  • If the v3.0.0 wallet attempts to specify a TTL while sending over http to a v2.x.x wallet, the transaction will work but the user will get a warning.
  • If outputting to a file and either a payment proof or a TTL is specified, the file will be v3.0.0 compatible only, and the user will be warned that this file can only be sent to other > v3.0.0 wallets.
  • If outputting to a file and neither a payment proof nor a TTL is specified, a v2.x.x. compatible transaction file will be created.

• v2.x.x compatibility will be removed in a later release, so it's highly recommended to upgrade ASAP

Node Compatibility

• The v3.0.0 Wallet is only compatible with Grin nodes running v3.0.0 or greater.

Command-line Changes

• Wallets created before v3.0.0 will automatically perform a scan process the first time they are run with v3.0.0
• Wallets recovered with a seed phrase will perform a scan on first init. Wallets created with a new seed will not.
• Default selection strategy is changed to smallest from all
• Options added to allow for separation of the finalize and post operations, to allow for offline transaction finalization.
• no_tor added to the listen command, to prevent listeners from listening via TOR (see TOR Support below)
• If the provided destination address during a send command is confirmed to be an onion V3 address, the wallet will attempt to send the transaction via TOR, and fail if TOR isn't configured on the system.
• grin-wallet check is now grin-wallet scan
• The restore function has been removed in favor of the scan function, (which provides the same functionality).
• scan now accepts a start_height parameter, which denotes which block height to start the scan from.
• The recover function now only displays the wallet's recovery phrase. To perform a recovery from seed phrase on a new wallet instance, use grin-wallet init -r
• The data_dir global switch has been renamed to top_level_dir, and is intended to specify the location of the directory containing a wallet's grin-wallet.toml file.
• A ttl_blocks options is added to both the send and pay commands, specifying the number of blocks into the future after which all wallets should refuse to process a transaction further and cancel them. Note that specifying this option will produce a v3.0.0 compatible-only transaction file when being output to a file, or will be dropped if sent directly to a v2.x.x HTTP listener.
• A request_payment_proof flag is added to the send command, which denotes that the recipient must fill out a payment proof. Note that specifying this option will produce a v3.0.0 compatible-only transaction file when being output to a file, or will refuse to send the transaction to a v2.x.x HTTP listener.

TOR Support

Support for sending and listening via TOR is added according to Online Transacting via TOR RFC.

Upstream consumers of the API will need to manage the installation and running of the TOR executable separately. The command-line wallet will attempt to use TOR before falling back to the HTTP listener.

To Listen (via the command-line wallet)

• Install tor on a target machine, and ensure the tor executable is on the PATH (to test this, just type tor at the prompt and check if it starts up). Note: you do not need to run tor manually when sending via the wallet, this is just to ensure the executable can be found
• Run grin-wallet listen

If tor is installed and on the path, your hidden service address should be printed to stdout. If not, listening will fall back to standard HTTP only.

To Send (Via the wallet Client)

• Install tor on the target machine as above

• The usual send command will check whether the provided destination is a tor address, and send via tor if so. For instance: grin-wallet send -d "http://tuyadexmtd5houbmysg5qqctor43npeqmeibwmrml55spidwudi4egid.onion" 60

• This will also work with just the onion address:
  grin-wallet send -d "tuyadexmtd5houbmysg5qqctor43npeqmeibwmrml55spidwudi4egid" 60

• The following is the default tor configuration section forgrin-wallet.toml (this will be output for new wallets, note send_config_dir is full path). For backwards compatibility reasons, if this section doesn't exist in grin-wallet.toml these are the defaults that will be assumed, with send_config_dir configured to the top-level wallet directory)

#########################################
### TOR CONFIGURATION (Experimental)  ###
#########################################
[tor]

#Whether to start tor listener on listener startup (default true)
use_tor_listener = true

# TOR (SOCKS) proxy server address
socks_proxy_addr = "127.0.0.1:59050"

#Directory to output TOR configuration to when sending
send_config_dir = "/FULL/PATH/TO/TOPLEVEL/WALLET/DIR/tor/sender"

TOR Troubleshooting

If you're having trouble sending or receiving via TOR, please check the following:

• The TOR executable may exist but fail to start due to an underlying library error, this can be easily checked by running tor manually and checking whether it starts
• Some Linux distributions (e.g. Ubuntu 18) contain outdated TOR packages that may not support V2 addresses. Always ensure your TOR binaries are up to date and obtained directly from the TOR project.

Wallet State Updating

• The process via which the wallet updates itself has been modified to incorporate UTXO scanning as part of normal operation. The entire process is detailed in the associated RFC (update this link on RFC merge).
• Clients now have the option to run the wallet update periodically on a background thread. See Owner API Changes for details.

Payment Proofs

Payment proofs are added as described in mimblewimble/grin-rfcs#31 to the wallet APIs. Note that payment proofs are meant to match up with TOR Onion V3 addresses, but are usable even if the exchange is not happening via TOR.

A listening recipient will fill out and return a payment proof if the payment_proof structure is included in the slate. The sender will reject a returned transaction if a payment proof has been requested but not filled out by the recipient. Details on the changes to the slate, owner API and transaction logs to support slates are outlined below.

Note that proofs are only supported during a sender->recipient exchange. Invoice transactions do not currently support Payment Proofs.

Owner API Changes

• The V2 Owner API is deprecated, and will be removed in grin-wallet 4.0.0. Please update your code to use the V3 API (contained in api/src/owner_rpc_s.rs). Please note that all new functions are available in the V3 API only.
• The previous check_repair function has been renamed to scan.
• scan now accepts a start_height parameter, which denotes which block height to start the scan from.
• The restore function has been removed in favor of the scan function, (which provides the same functionality).
• New functions related to background state updates have been added. These are:
  • start_updater - Starts the updater thread at a specified frequency
  • stop_updater - Stops the updater thread
  • get_updater_messages - Returns messages created by the updater thread in historical order.
• A set_tor_config function is added to configure the API for sending via a TOR socks listener.
• The init_tx_args parameter block is updated with the following fields:
  • ttl_blocks - The number of blocks from the current to set the slate's TTL field to
  • payment_proof_recipient_address - The payment proof address of the recipient. If this is filled out, it is expected that the recipient will fill out the full payment proof. (See Payment Proofs)
• A get_public_proof_address function is added, which will return the payment proof address of the active wallet account.
• A proof_address_from_onion_v3 convenience function is added, which extracts the public proof address from an onion V3 address.

Slate Changes

• The default slate version is updated to 3, however the wallet will generally output V2 slates if neither the payment_proof or ttl_cutoff_height fields are being used.
• An optional payment_proof struct is added to the Slate. This contains:
  • sender_address - an ed25519 Public Key corresponding to the sender's derived wallet payment proof address.
  • receiver_address - an ed25519 Public Key corresponding to the recipients's derived wallet payment proof address.
  • receiver_signature - an ed25519 signature representing the recipient's payment proof.
• ttl_cutoff_height is added to the slate, meant to represent the height at which wallets should refuse to further process the transaction

Transaction Log Entry Changes

• A payment_proof has been added to the transaction log entry struct. This contains:
  • sender_address - an ed25519 Public Key corresponding to the sender's derived wallet payment proof address.
  • sender_signature - an ed25519 signature representing the sender's payment proof, which can optionally be provided to the recipient
  • sender_address_path - The derivation path in the wallet's current account used to derive the sender address
  • receiver_address - an ed25519 Public Key corresponding to the recipients's derived wallet payment proof address.
  • receiver_signature - an ed25519 signature representing the recipient's payment proof.

[yeastplume]

Closing, but this should still be linked via the relevant release notes.