Merge pull request #232 from daira/zip-0308-updates

ZIP 308 updates

zip-0308.rst

@@ -4,7 +4,7 @@
   Title: Sprout to Sapling Migration
   Author: Daira Hopwood <daira@z.cash>
           Eirik Ogilvie-Wigley <eirik@z.cash>
-  Status: Draft
+  Status: Final
   Category: RPC/Wallet
   Created: 2018-11-27
   License: MIT
@@ -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:
@@ -238,10 +243,12 @@ 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 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.
@@ -259,6 +266,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.
 
@@ -314,7 +324,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.
@@ -323,7 +333,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::
 
@@ -331,9 +341,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]
   }
@@ -345,12 +355,16 @@ 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
 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.
 
@@ -362,14 +376,26 @@ 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.
 
 
 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