List of Changes in 4.0.0

[yeastplume]

These release notes constitute the list of changes from 3.1.2

Inter-Wallet Compatibility

• v4.0.0 wallets will be able to exchange transactions with v3.x.x wallets until the Hardfork block. When performing file-based transactions, the wallet will output older V3 transaction files before the hardfork block, and Slatepack afterwards. To force output of Slatepack files before the hardfork, use the send command's --v4 flag. See the Slatepack section for details.
• v3.x.x compatibility will be removed in a later release, so it's highly recommended to upgrade ASAP

Node Compatibility

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

Slatepack

The major new feature of the v4.0.0 wallet is the introduction of the Slatepack Format and Workflow. Slatepack is the culmination of much thinking about how to reduce, simplify and standardize how transactions are exchanged between parties, and it is hoped that it will provide a solid foundation to improve the overall user experience over time.

In a nutshell:

• All wallets have a Slatepack address (which will be cyclable in future versions).
• When a wallet listener is run and TOR is present on the system, the wallet will create a TOR hidden service.
• A wallet's Slatepack address can be provided to other users .
• If a Slatepack address is provided during a send, sending wallets will attempt to send a transaction to the TOR hidden service.
• If sending via TOR fails, the wallet outputs a compact, easily-cut-and-pasted string that can be sent to the other party for manual processing. The contents of the Slatepack are encrypted for the recipient only.

A Full description of Slatepack can be found in the Slatepack RFC (URL to be updated after merge)

Command-line Changes

• Transactions will be output as V3 Slates before the hardfork block, and Slatepack afterwards. To force Slatepack output, use the --v4 flag during the send command.
• The method flag is removed from all command-line arguments in favor of Slatepack workflows
• dest is no longer mandatory for all functions that produce a slate. If dest is provided and is a Slatepack address, the slatepack sync-send workflow is invoked, which attempts to send to the TOR address represented by the Slatepack address, followed by Slatepack output to the prompt and a file if that fails. If dest is not provided the Slatepack is automatically output.
• If dest is provided as a Slatepack address, the Slatepack is encrypted for the recipient only.
• The sender field in the encrypted portion of the Slatepack is included by default.
• If the dest field is a valid Slatepack address, a payment proof will be requested by default. If this is not desired, the --no_payment_proof -n flag can be provided.
• All command-line functions that produce a slate for sending to the other party (send, receive, pay) attempt to continue the transaction via the Slatepack's sender field if available, otherwise they revert to Slatepack output.
• All command-line functions that produce a slate output the Slatepack to the terminal, as well as save the Slatepack in a file [slatepack/[slate-id].[slate.state].slatepack.
• The location of the output Slatepack file above can be overridden with the --outfile, -u flag
• The input argument for all command-line functions that accept a slate is no longer mandatory. If included, the command will attempt to read from the given file. If not, the command will prompt the user to paste Slatepack data into the terminal directly.
• A --manual flag is added to all commands that can send a Slatepack. If this flag is present, the wallet will not attempt to send the resulting Slatepack via TOR.
• An unpack command is added, which will decode and decrypt (if possible), a Slatepack Message.
• The address command will now output this wallet's Slatepack address
• sends via http will be deprecated in 5.0.0. If the user may provide an http address in the dest field for now, however the user will need to respond to a nag prompt.
• The message flag has been removed from all commands that previously accepted an optional message

Owner API Changes

• The message argument is removed from init_send_tx, receive_tx
• init_send_tx and process_invoice_tx will optionally invoke the Slatepack sync workflow if the appropriate InitSendTx arguments are provided.
• A new field skip_send_attempt is added to the TorConfig struct. To prevent these calls from attempting to send via TOR, call the set_tor_config API function with this field set to Some(true)
• verify_slate_messages is removed
• The post_tx function now accepts a Slate rather than a raw Transaction
• get_stored_tx can now accept either a Transaction Log ID or a Slate UUID
• get_public_proof_address is replaced with get_slatepack_address, which returns a SlatepackAddress
• proof_address_from_onion_v3 is removed
• get_slatepack_secret_key is added, which returns the SecretKey of the wallet that can be used for Slatepack decryption
• create_slatepack_message is added, which creates a SlatepackMessage string from the given slate and recipients
• slate_from_slatepack_message is added, which extracts a Slate from a SlatepackMessage
• decode_slatepack_message is added, which decodes a SlatepackMessage

Foreign API Changes

• receive_tx will attempt to send the processed transaction back to the sender if a return address is provided. This functionality is provided for convenience for upstream wallet developers. If this functionality is used, the caller should check the slate's sta field to determine whether the sync send attempt succeeded, and invoke the slatepack workflow otherwise.
• The message field in the receive_tx has been changed to r_addr. It is now interpreted as a Slatepack address and if included, the funciton will attempt to send the resulting Slatepack back to the specified address.
• As with the OwnerAPI, call set_tor_config with skip_send_attempt set to Some(true) to prevent recieve_tx from attempting to send the result via TOR.
• finalize_invoice_tx is removed, replaced with simply finalize_tx
• The finalize_tx function now has a post_automatically flag. The function will post to the node only if this is set to true.

Slate Changes

• The format of the V4 Slate has changed significantly from V3 to allow for a more compact slate format that suits the Slatepack workflow. Please refer to Grin RFC 0012 for description of the Slate, a detailed list of changes, and the new binary Slate representation.
• Note the message field removed from the Slate along with all related API and command-line functions.

Config File Changes

• An optional skip_send_attempt field is added to the TorConfig struct. This can be set to true to stop the wallet from ever attempting to send via TOR. This field is not required to be present in the configuraiton file.

[slavikus]

I am sorry to be a little late to the party with my comments about the Slatepack changes, but could one of the developers please quickly elaborate on how do you envision the cryptocurrency exchanges would work with this mode? Would users need to copy-paste a serialized SlateMessage every time they need to deposit funds to the exchange?

Ideally, some method like the exchange providing multiple-use receive-only SlateMessage to the user so they can use it to deposit funds multiple times would work, but as I understand it (correct me if I am wrong), the receive Slatepacks are one-shot.

This whole will ruin the model of the miners who mine directly to the exchange (this also brings the question of how the mining pool would be paying its users -- again, emailing them a serialized SlateMessage for every payout is totally not an option for many pools as they don't know the email address of the users and/or have no "secure account management page" where this info could be accumulated).

Am I missing something here? Thanks.

[yeastplume]

I am sorry to be a little late to the party with my comments about the Slatepack changes, but could one of the developers please quickly elaborate on how do you envision the cryptocurrency exchanges would work with this mode? Would users need to copy-paste a serialized SlateMessage every time they need to deposit funds to the exchange?

Ideally, some method like the exchange providing multiple-use receive-only SlateMessage to the user so they can use it to deposit funds multiple times would work, but as I understand it (correct me if I am wrong), the receive Slatepacks are one-shot.

This whole will ruin the model of the miners who mine directly to the exchange (this also brings the question of how the mining pool would be paying its users -- again, emailing them a serialized SlateMessage for every payout is totally not an option for many pools as they don't know the email address of the users and/or have no "secure account management page" where this info could be accumulated).

Am I missing something here? Thanks.

Will get back to you on this soon, we intend to introduce exchange integration guidelines for slatepack that should hopefully answer these questions

[slavikus]

@yeastplume any updates on this one? Thanks!

[DavidBurkett]

Hi @slavikus!

I am sorry to be a little late to the party with my comments about the Slatepack changes, but could one of the developers please quickly elaborate on how do you envision the cryptocurrency exchanges would work with this mode? Would users need to copy-paste a serialized SlateMessage every time they need to deposit funds to the exchange?

It depends. If you are willing to support tor, most transactions will not require copy-pasting a serialized SlateMessage at all. That would only be necessary when the other party is inaccessible via tor.

Ideally, some method like the exchange providing multiple-use receive-only SlateMessage to the user so they can use it to deposit funds multiple times would work, but as I understand it (correct me if I am wrong), the receive Slatepacks are one-shot.

Multiple-use receive-only SlateMessage's are not possible. They are one-time use. The Slatepack addresses are reusable though.

This whole will ruin the model of the miners who mine directly to the exchange (this also brings the question of how the mining pool would be paying its users -- again, emailing them a serialized SlateMessage for every payout is totally not an option for many pools as they don't know the email address of the users and/or have no "secure account management page" where this info could be accumulated).

Am I missing something here? Thanks.

Yes, if you support tor, miners can still mine directly to the exchange, as long as you support the ability to reuse slatepack addresses.

Here's an exchange integration guide that our doc wizard @Paouky wrote for us: https://docs.grin.mw/wiki/services/slatepack-integration/

Let me know if you still have any outstanding questions.

[slavikus]

@DavidBurkett thanks for a detailed response!

Please correct me if I am wrong, but the thing that worries me about the exchanges is that it means that for every wallet for each exchange customer who has a GRIN incoming wallet set up (or for a miner to be able to mine directly to it), it has to allocate a new Tor hostname so the Slatepack-based transactions pass through. Creating thousands of Tor addresses is pretty resource and infrastructure intensive (as you have to restart the tor daemon at the very least after adding each additional address and that renders other addresses inoperable for 2-3 minutes while the daemon spins off).

Copy-pasing the Slatepack message could work, but then it kills the whole automation part of mining to an exchange. Also, it complicates things as for example, our pool (2Miners.com) is fully anonymous not having any sort of a client area or secure page where the miner could potentially grab these Slatepack Messages for a direct manual deposit. Before we could get away by allowing miners use the HTTPS urls as their "mining address". Now we still could do that and try to deposit via Tor automagically, but due to the concerns raised above, I am not sure this will be possible for most miners.

What approach could we, as a pool, use to continue keeping the miners anonymity and to be able to pay out their mining rewards?

Thank you!

[DavidBurkett]

Creating thousands of Tor addresses is pretty resource and infrastructure intensive (as you have to restart the tor daemon at the very least after adding each additional address and that renders other addresses inoperable for 2-3 minutes while the daemon spins off).

Why do you have to restart the tor daemon after adding each address? The addresses should not be added to the config file. Instead, the control port should be used (https://gitweb.torproject.org/torspec.git/tree/control-spec.txt#n1659)

[slavikus]

Thank you for the clarification. Then my main point about difficulties for the exchanges is no longer moot, and hopefully we will be able to use Tor as a transport to pay out our miners. If that fails, well...

[tromp]

our pool (2Miners.com) is fully anonymous not having any sort of a client area or secure page where the miner could potentially grab these Slatepack Messages for a direct manual deposit

You're already maintaining some miner credentials, like an address to send mining proceeds to. By maintaining a grin wallet address for each grin miner, you can let them exchange encrypted slatepacks for payout to their claimed grin wallet in an anonymous client area. Only the true owner of the grin wallet address is able to complete the payout transaction, so no further authentication is required?!