From ef7d171a6427649036f6da417a295f5949fc3a6e Mon Sep 17 00:00:00 2001
From: Simon Warta <simon@warta.it>
Date: Thu, 23 Jul 2020 16:15:28 +0200
Subject: [PATCH] Improve documentation of
 Secp256k1Wallet.serialize/deserialize

---
 packages/sdk38/src/index.ts               |  4 ++--
 packages/sdk38/src/secp256k1wallet.ts     | 15 +++++++++++++++
 packages/sdk38/types/index.d.ts           |  4 ++--
 packages/sdk38/types/secp256k1wallet.d.ts | 15 +++++++++++++++
 4 files changed, 34 insertions(+), 4 deletions(-)

diff --git a/packages/sdk38/src/index.ts b/packages/sdk38/src/index.ts
index 78cbf494..44f477b7 100644
--- a/packages/sdk38/src/index.ts
+++ b/packages/sdk38/src/index.ts
@@ -85,5 +85,5 @@ export { findSequenceForSignedTx } from "./sequence";
 export { encodeSecp256k1Signature, decodeSignature } from "./signature";
 export { FeeTable, SigningCosmosClient } from "./signingcosmosclient";
 export { isStdTx, pubkeyType, CosmosSdkTx, PubKey, StdFee, StdSignature, StdTx } from "./types";
-export { OfflineSigner, makeCosmoshubPath } from "./wallet";
-export { Secp256k1Wallet } from "./secp256k1wallet";
+export { OfflineSigner, makeCosmoshubPath, executeKdf, KdfConfiguration } from "./wallet";
+export { extractKdfConfiguration, Secp256k1Wallet } from "./secp256k1wallet";
diff --git a/packages/sdk38/src/secp256k1wallet.ts b/packages/sdk38/src/secp256k1wallet.ts
index 65f09745..6c393cfa 100644
--- a/packages/sdk38/src/secp256k1wallet.ts
+++ b/packages/sdk38/src/secp256k1wallet.ts
@@ -152,6 +152,12 @@ export class Secp256k1Wallet implements OfflineSigner {
     return Secp256k1Wallet.fromMnemonic(mnemonic.toString(), hdPath, prefix);
   }
 
+  /**
+   * Restores a wallet from an encrypted serialization.
+   *
+   * @param password The user provided password used to generate an encryption key via a KDF.
+   *                 This is not normalized internally (see "Unicode normalization" to learn more).
+   */
   public static async deserialize(serialization: string, password: string): Promise<Secp256k1Wallet> {
     const root = JSON.parse(serialization);
     if (!isNonNullObject(root)) throw new Error("Root document is not an object.");
@@ -163,6 +169,15 @@ export class Secp256k1Wallet implements OfflineSigner {
     }
   }
 
+  /**
+   * Restores a wallet from an encrypted serialization.
+   *
+   * This is an advanced alternative to calling `deserialize(serialization, password)` directly, which allows
+   * you to offload the KDF execution to a non-UI thread (e.g. in a WebWorker).
+   *
+   * The caller is responsible for ensuring the key was derived with the given KDF configuration. This can be
+   * done using `extractKdfConfiguration(serialization)` and `executeKdf(password, kdfConfiguration)` from this package.
+   */
   public static async deserializeWithEncryptionKey(
     serialization: string,
     encryptionKey: Uint8Array,
diff --git a/packages/sdk38/types/index.d.ts b/packages/sdk38/types/index.d.ts
index 5e37414e..af666c9a 100644
--- a/packages/sdk38/types/index.d.ts
+++ b/packages/sdk38/types/index.d.ts
@@ -83,5 +83,5 @@ export { findSequenceForSignedTx } from "./sequence";
 export { encodeSecp256k1Signature, decodeSignature } from "./signature";
 export { FeeTable, SigningCosmosClient } from "./signingcosmosclient";
 export { isStdTx, pubkeyType, CosmosSdkTx, PubKey, StdFee, StdSignature, StdTx } from "./types";
-export { OfflineSigner, makeCosmoshubPath } from "./wallet";
-export { Secp256k1Wallet } from "./secp256k1wallet";
+export { OfflineSigner, makeCosmoshubPath, executeKdf, KdfConfiguration } from "./wallet";
+export { extractKdfConfiguration, Secp256k1Wallet } from "./secp256k1wallet";
diff --git a/packages/sdk38/types/secp256k1wallet.d.ts b/packages/sdk38/types/secp256k1wallet.d.ts
index af84a682..06e9510c 100644
--- a/packages/sdk38/types/secp256k1wallet.d.ts
+++ b/packages/sdk38/types/secp256k1wallet.d.ts
@@ -57,7 +57,22 @@ export declare class Secp256k1Wallet implements OfflineSigner {
     hdPath?: readonly Slip10RawIndex[],
     prefix?: string,
   ): Promise<Secp256k1Wallet>;
+  /**
+   * Restores a wallet from an encrypted serialization.
+   *
+   * @param password The user provided password used to generate an encryption key via a KDF.
+   *                 This is not normalized internally (see "Unicode normalization" to learn more).
+   */
   static deserialize(serialization: string, password: string): Promise<Secp256k1Wallet>;
+  /**
+   * Restores a wallet from an encrypted serialization.
+   *
+   * This is an advanced alternative to calling `deserialize(serialization, password)` directly, which allows
+   * you to offload the KDF execution to a non-UI thread (e.g. in a WebWorker).
+   *
+   * The caller is responsible for ensuring the key was derived with the given KDF configuration. This can be
+   * done using `extractKdfConfiguration(serialization)` and `executeKdf(password, kdfConfiguration)` from this package.
+   */
   static deserializeWithEncryptionKey(
     serialization: string,
     encryptionKey: Uint8Array,