From 6c47fbc21a40ffc16dbec786e48ae90145f10d5f Mon Sep 17 00:00:00 2001 From: Daira Hopwood Date: Fri, 10 May 2019 20:21:09 +0100 Subject: [PATCH 1/9] ZIP 308: ovk SHOULD be generated as if for a transfer from a t-addr. Signed-off-by: Daira Hopwood --- zip-0308.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/zip-0308.rst b/zip-0308.rst index 2b469999..abb16d3e 100644 --- a/zip-0308.rst +++ b/zip-0308.rst @@ -259,6 +259,9 @@ migration transaction. The ``lock_time`` field MUST be set to 0 (unused). +When creating Sapling shielded Outputs, the outgoing viewing key ``ovk`` +SHOULD be chosen in the same way as for a transfer sent from a t-address. + A node SHOULD treat migration transactions in the same way as transactions submitted over the RPC interface. From 0a202f8c35de722793d683ae806d36c46bda146e Mon Sep 17 00:00:00 2001 From: Daira Hopwood Date: Fri, 10 May 2019 20:22:31 +0100 Subject: [PATCH 2/9] ZIP 308: Update RPC names to begin with `z_`. Signed-off-by: Daira Hopwood --- zip-0308.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/zip-0308.rst b/zip-0308.rst index abb16d3e..55e4211a 100644 --- a/zip-0308.rst +++ b/zip-0308.rst @@ -317,7 +317,7 @@ the address for Sapling account 0, with the default diversifier [#zip-0032]_. The state variable can also be set for a running node using the following RPC method:: - setmigration true/false + z_setmigration true/false It is intentional that the only option associated with the migration is the destination z-address. Other options could potentially distinguish users. @@ -326,7 +326,7 @@ destination z-address. Other options could potentially distinguish users. Nodes MUST also support the following RPC call to return the current status of the migration:: - getmigrationstatus + z_getmigrationstatus Returns:: From 5f50fe0fca3e40d903137939c1ee808901e4206f Mon Sep 17 00:00:00 2001 From: Daira Hopwood Date: Fri, 10 May 2019 20:24:38 +0100 Subject: [PATCH 3/9] ZIP 308: In `z_getmigrationstatus` change occurrences of the word 'confirmed' to 'finalized'. Also add "at least" to the definition of finalized. Signed-off-by: Daira Hopwood --- zip-0308.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/zip-0308.rst b/zip-0308.rst index 55e4211a..759f1329 100644 --- a/zip-0308.rst +++ b/zip-0308.rst @@ -334,9 +334,9 @@ Returns:: "enabled": true|false, "destination_address": "zaddr", "unmigrated_amount": nnn.n, - "unconfirmed_migrated_amount": nnn.n, - "confirmed_migrated_amount": nnn.n, - "confirmed_migration_transactions": nnn, + "unfinalized_migrated_amount": nnn.n, + "finalized_migrated_amount": nnn.n, + "finalized_migration_transactions": nnn, "time_started": ttt, // Unix timestamp "migration_txids": [txids] } @@ -365,7 +365,7 @@ The value of ``time_started`` is the earliest Unix timestamp of any known migration transaction involving this wallet; if there is no such transaction, then the field is absent. -A transaction is ``confirmed`` iff it has 10 confirmations. +A transaction is ``finalized`` iff it has at least 10 confirmations. TODO: subject to change, if the recommended number of confirmations changes. From cee6562813449d705640c3bedf1efc01d8eb38e8 Mon Sep 17 00:00:00 2001 From: Daira Hopwood Date: Fri, 10 May 2019 20:25:44 +0100 Subject: [PATCH 4/9] ZIP 308: Specify that `[un]finalized_migrated_amount` does not include fees. Signed-off-by: Daira Hopwood --- zip-0308.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/zip-0308.rst b/zip-0308.rst index 759f1329..32faed45 100644 --- a/zip-0308.rst +++ b/zip-0308.rst @@ -348,6 +348,10 @@ The values of ``unmigrated_amount`` and ``migrated_amount`` MUST take into account failed transactions, that were not mined within their expiration height. +The values of ``unfinalized_migrated_amount`` and ``finalized_migrated_amount`` +are the total amounts sent to the Sapling destination address in migration +transactions, excluding fees. + ``migration_txids`` is a list of strings representing transaction IDs of all known migration transactions involving this wallet, as lowercase hexadecimal in RPC byte order. A given transaction is defined as a migration transaction From d7bed44d73e2a67822618855fec13953deca6196 Mon Sep 17 00:00:00 2001 From: Daira Hopwood Date: Fri, 10 May 2019 20:26:45 +0100 Subject: [PATCH 5/9] ZIP 308: Migration txns SHOULD only be sent if the timestamp of the block used to trigger sending a batch is more recent than 3 hours ago according to the node's adjusted clock. Signed-off-by: Daira Hopwood --- zip-0308.rst | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/zip-0308.rst b/zip-0308.rst index 32faed45..6ac73ad3 100644 --- a/zip-0308.rst +++ b/zip-0308.rst @@ -136,6 +136,10 @@ after seeing a block with height 499, modulo 500). Up to the limit of 5, as many transactions are sent as are needed to migrate the remaining funds (possibly with a remainder less than 0.01 ZEC left unmigrated). +Nodes SHOULD NOT send migration transactions during initial block download, or +if the timestamp of the triggering block (with height 499, modulo 500) is more +than three hours in the past according to the node's adjusted local clock. + TODO: if we change the target block interval, 500 might need to be changed. The migration transactions to be sent in a particular batch can take @@ -143,7 +147,8 @@ significant time to generate, and this time depends on the speed of the user's computer. If they were generated only after a block is seen at the target height minus 1, then this could leak information. Therefore, for target height N, implementations SHOULD start generating the transactions at around -height N-5. Each migration transaction SHOULD specify an anchor at height N-10 +height N-5 (provided that block's timestamp is not more than three hours in +the past). Each migration transaction SHOULD specify an anchor at height N-10 for each Sprout JoinSplit description. Open questions: From 4861f5583036b4163299a2e10c6efb74f4065621 Mon Sep 17 00:00:00 2001 From: Daira Hopwood Date: Fri, 10 May 2019 20:27:45 +0100 Subject: [PATCH 6/9] ZIP 308: Migration transactions MUST have an expiry delta of 450 blocks. Signed-off-by: Daira Hopwood --- zip-0308.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/zip-0308.rst b/zip-0308.rst index 6ac73ad3..5546df42 100644 --- a/zip-0308.rst +++ b/zip-0308.rst @@ -246,7 +246,9 @@ the same as for a normal transaction sending the same amount with the same wallet state. Only the ``vpub_out`` of the last JoinSplit will be nonzero. There will always be exactly one Sapling Output. -The expiry height MUST be chosen as for other transactions. +The expiry delta for migration transactions MUST be 450 blocks. Since these +transactions are sent when the block height is 499 modulo 500, their expiry +height will be 451 blocks later, i.e. ``nExpiryHeight`` will be 450 modulo 500. The fee for each migration transaction MUST be 0.0001 ZEC. This fee is taken from the funds to be migrated. From 482f4c046898a7e7d103ae722ca577d12f127a7a Mon Sep 17 00:00:00 2001 From: Daira Hopwood Date: Fri, 10 May 2019 20:28:19 +0100 Subject: [PATCH 7/9] ZIP 308: Mark Status as Final. Signed-off-by: Daira Hopwood --- zip-0308.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/zip-0308.rst b/zip-0308.rst index 5546df42..6768b661 100644 --- a/zip-0308.rst +++ b/zip-0308.rst @@ -4,7 +4,7 @@ Title: Sprout to Sapling Migration Author: Daira Hopwood Eirik Ogilvie-Wigley - Status: Draft + Status: Final Category: RPC/Wallet Created: 2018-11-27 License: MIT From f7eec5124d65eb3f6200b4c08c31aa4d0f5481cd Mon Sep 17 00:00:00 2001 From: Daira Hopwood Date: Fri, 10 May 2019 20:28:42 +0100 Subject: [PATCH 8/9] ZIP 308: Add list of implementing zcashd PRs. Signed-off-by: Daira Hopwood --- zip-0308.rst | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/zip-0308.rst b/zip-0308.rst index 6768b661..0a893bb8 100644 --- a/zip-0308.rst +++ b/zip-0308.rst @@ -383,7 +383,19 @@ TODO: subject to change, if the recommended number of confirmations changes. Support in zcashd ================= -TODO (point to the PR). +The following PRs implement this specification: + +* https://github.com/zcash/zcash/pull/3848 (TransactionBuilder support) +* https://github.com/zcash/zcash/pull/3888 (main RPC) +* https://github.com/zcash/zcash/pull/3967 (config options) +* https://github.com/zcash/zcash/pull/3973 (getmigrationstatus RPC) +* https://github.com/zcash/zcash/pull/3977 (bugfix) +* https://github.com/zcash/zcash/pull/3987 (bugfix) +* https://github.com/zcash/zcash/pull/3990 (bugfix) +* https://github.com/zcash/zcash/pull/3995 (don't migrate in initial block download/after wakeup) +* https://github.com/zcash/zcash/pull/3997 (bugfix) +* https://github.com/zcash/zcash/pull/4002 (minor RPC improvements) +* https://github.com/zcash/zcash/pull/4005 (change expiry for migration transactions) References From a7683fbca60ab40b448b98f177c48f768029abe4 Mon Sep 17 00:00:00 2001 From: Daira Hopwood Date: Fri, 10 May 2019 20:32:49 +0100 Subject: [PATCH 9/9] ZIP 308: Correct `vpub_out` to `vpub_new`. Signed-off-by: Daira Hopwood --- zip-0308.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/zip-0308.rst b/zip-0308.rst index 0a893bb8..2f6d725e 100644 --- a/zip-0308.rst +++ b/zip-0308.rst @@ -243,7 +243,7 @@ We assume use of the normal wallet note selection algorithm and change handling. Change is sent back to the default address, which is the z-address of the first selected Sprout note. The number of JoinSplits will therefore be the same as for a normal transaction sending the same amount with the same -wallet state. Only the ``vpub_out`` of the last JoinSplit will be nonzero. +wallet state. Only the ``vpub_new`` of the last JoinSplit will be nonzero. There will always be exactly one Sapling Output. The expiry delta for migration transactions MUST be 450 blocks. Since these @@ -364,7 +364,7 @@ known migration transactions involving this wallet, as lowercase hexadecimal in RPC byte order. A given transaction is defined as a migration transaction iff it has: -* one or more Sprout JoinSplits with nonzero vpub_new field; and +* one or more Sprout JoinSplits with nonzero ``vpub_new`` field; and * no Sapling Spends, and; * one or more Sapling Outputs.