[#771] Update documentation for SDK 1.10.0

CHANGELOG.md

@@ -20,6 +20,8 @@ Change Log
 - `cash.z.ecc.android.sdk.tool`:
   - `DerivationTool.deriveUnifiedSpendingKey`
   - `DerivationTool.deriveUnifiedFullViewingKey`
+  - `DerivationTool.deriveTransparentAccountPrivateKey`
+  - `DerivationTool.deriveTransparentAddressFromAccountPrivateKey`
   - `DerivationTool.deriveUnifiedAddress`
   - `DerivationTool.deriveUnifiedFullViewingKeys`
   - `DerivationTool.validateUnifiedFullViewingKey`
@@ -58,15 +60,15 @@ Change Log
     public key, and not the extended public key as intended. This made it incompatible
     with ZIP 316.
 - `cash.z.ecc.android.sdk.tool`:
-  - `DerivationTool.deriveSpendingKeys` (use `DerivationTool.deriveUnifiedSpendingKey` instead).
-  - `DerivationTool.deriveViewingKey` (use `DerivationTool.deriveUnifiedFullViewingKey` instead).
+  - `DerivationTool.deriveSpendingKeys` (use `DerivationTool.deriveUnifiedSpendingKey` instead)
+  - `DerivationTool.deriveViewingKey` (use `DerivationTool.deriveUnifiedFullViewingKey` instead)
   - `DerivationTool.deriveTransparentAddress` (use `Synchronizer.getLegacyTransparentAddress` instead).
   - `DerivationTool.deriveTransparentAddressFromPrivateKey` (use `Synchronizer.getLegacyTransparentAddress` instead).
   - `DerivationTool.deriveTransparentAddressFromPublicKey` (use `Synchronizer.getLegacyTransparentAddress` instead).
   - `DerivationTool.deriveTransparentSecretKey` (use `DerivationTool.deriveUnifiedSpendingKey` instead).
   - `DerivationTool.deriveShieldedAddress`
-  - `DerivationTool.deriveUnifiedViewingKeys`
-  - `DerivationTool.validateUnifiedViewingKey`
+  - `DerivationTool.deriveUnifiedViewingKeys` (use `DerivationTool.deriveUnifiedFullViewingKey` instead)
+  - `DerivationTool.validateUnifiedViewingKey` 
 
 Version 1.9.0-beta05
 ------------------------------------

MIGRATIONS.md

@@ -3,6 +3,12 @@ Troubleshooting Migrations
 
 Migration to Version 1.10
 ---------------------------------
+The way the SDK is initialized has changed.  The `Initializer` object has been removed and `Synchronizer.new` now takes a longer parameter list which includes the parameters previously passed to `Initializer`.
+
+SDK initialization also now requires access to the seed bytes at two times: 1. during new wallet creation and 2. during upgrade of an existing wallet to SDK 1.10 due to internal data migrations.  To handle case #2, client should wrap `Synchronizer.new()` with a try-catch for `InitializerException.SeedRequired`.  Clients can pass `null` to try to initialize the SDK without the seed, then try again if the exception is thrown to indicate the seed is needed.  This pattern future-proofs initialization, as the seed may be required by future SDK updates.
+
+To improve type safety of the public API, Zcash account indexes are now represented by an `Account` object.  The SDK currently only supports the default account, `Account.DEFAULT`.  Migration will effectively require replacing APIs with an account `0` with `Account.DEFAULT`.
+
 To support Network Upgrade 5, the way keys are generated has changed.
 
 For SDK clients that regenerate the keys from a mnemonic, migration might look like:
@@ -16,6 +22,8 @@ For SDK clients that store the key separately from the mnemonic, the migration m
    provided that they can be rederived from the mnemonic.
  * Re-generate the key from the mnemonic using `DerivationTool.deriveUnifiedFullViewingKeys`
 
+To support Unified Addresses (UAs), some APIs have been modified.  In particular, `Synchronizer.getCurrentAddress()` returns the unified address while `Synchronizer.getLegacySaplingAddress()` and `Synchronizer.getLegacyTransparentAddress()` return the sapling or transparent components of the unified address.  Due to this change and the derivation of different addresses from UAs, clients may notice that the transparent address returned by this API is different from the transparent address returned by older versions of the SDK.  Note that UA support does not yet encompass orchard addresses.
+
 Due to internal changes in the SDK, the way transactions are queried and represented works differently.  The previous ConfirmedTransaction object has been replaced with `TransactionOverview` which contains less information.  Missing fields, such as memos and recipients, can be queried with `Synchronizer.getMemos(TransactionOverview)` and `Synchronizer.getReceipients(TransactionOverview)`.
 
 Migration to Version 1.9

gradle.properties

@@ -22,7 +22,7 @@ ZCASH_ASCII_GPG_KEY=
 # Configures whether release is an unstable snapshot, therefore published to the snapshot repository.
 IS_SNAPSHOT=true
 
-LIBRARY_VERSION=1.9.0-beta04
+LIBRARY_VERSION=1.10.0-beta01
 
 # Kotlin compiler warnings can be considered errors, failing the build.
 ZCASH_IS_TREAT_WARNINGS_AS_ERRORS=true

sdk-lib/src/main/java/cash/z/ecc/android/sdk/Synchronizer.kt

@@ -480,13 +480,21 @@ interface Synchronizer {
         /**
          * Primary method that SDK clients will use to construct a synchronizer.
          *
-         * @param initializer the helper that is leveraged for creating all the components that the
-         * Synchronizer requires. It contains all information necessary to build a synchronizer and it is
-         * mainly responsible for initializing the databases associated with this synchronizer and loading
-         * the rust backend.
+         * @param zcashNetwork the network to use.
+         * @param alias A string used to segregate multiple wallets in the filesystem.  This implies the string
+         * should not contain characters unsuitable for the platform's filesystem.  The default value is
+         * generally used unless an SDK client needs to support multiple wallets.
+         * @param lightWalletEndpoint Server endpoint.  See [cash.z.ecc.android.sdk.model.defaultForNetwork]. If a
+         * client wishes to change the server endpoint, the active synchronizer will need to be stopped and a new
+         * instance created with a new value.
          * @param seed the wallet's seed phrase. This is required the first time a new wallet is set up. For
          * subsequent calls, seed is only needed if [InitializerException.SeedRequired] is thrown.
-         * @throws InitializerException.SeedRequired
+         * @param birthday Block height representing the "birthday" of the wallet.  When creating a new wallet, see
+         * [BlockHeight.ofLatestCheckpoint].  When restoring an existing wallet, use block height that was first used
+         * to create the wallet.  If that value is unknown, null is acceptable but will result in longer
+         * sync times.  After sync completes, the birthday can be determined from [Synchronizer.latestBirthdayHeight].
+         * @throws InitializerException.SeedRequired Indicates clients need to call this method again, providing the
+         * seed bytes.
          */
         /*
          * If customized initialization is required (e.g. for dependency injection or testing), see

sdk-lib/src/main/java/cash/z/ecc/android/sdk/model/TransactionOverview.kt

@@ -3,7 +3,8 @@ package cash.z.ecc.android.sdk.model
 /**
  * High level transaction information, suitable for mapping to a display of transaction history.
  *
- * Note that both sent and received transactions will have a positive net value.  Consumers of this class must
+ * Note that both sent and received transactions will have a positive net value.  Consumers of this class must check
+ * [isSentTransaction] if displaying negative values is desired.
  */
 data class TransactionOverview internal constructor(
     val id: Long,