Merge pull request hyperledger-indy#900 from vimmerru/feature/deprecation

Added experimental and deprecation notes for the 1.5 release

Author: jovfer

CHANGELOG.md

@@ -8,11 +8,15 @@
     All encryption is performed in libindy. It simplifies plugged wallets and provides warranty of a good security level
     for 3d party wallets implementations.
   * The format of wallet data was changed for better security and support of efficient search
-* Added [Wallet Export/Import API](https://github.com/hyperledger/indy-sdk/tree/master/doc/design/009-wallet-export-import) and
+* Added EXPERIMENTAL [Wallet Export/Import API](https://github.com/hyperledger/indy-sdk/tree/master/doc/design/009-wallet-export-import) and
   corresponded commands to Indy CLI
+* ```indy_list_wallets``` endpoint is DEPRECATED and will be removed in the next release. The main idea is avoid
+  maintaining created wallet list on libindy side. It will allow to access wallets from a cluster and solve
+  some problems on mobile platforms. ```indy_create_wallet``` and ```indy_open_wallet``` endpoints will
+  also get related changes in the next release.
 * Added [Non-Secrets API](https://github.com/hyperledger/indy-sdk/tree/master/doc/design/003-wallet-storage#non-secrets-api) that allows store and read  
   application specific data in the wallet
-* Added [Generic Payments API](https://github.com/hyperledger/indy-sdk/tree/master/doc/design/004-payment-interface#payment-method-api) that provides
+* Added EXPERIMENTAL [Generic Payments API](https://github.com/hyperledger/indy-sdk/tree/master/doc/design/004-payment-interface#payment-method-api) that provides
   ability to register custom payment method
   and then create payment addresses, build payment-related transactions, assign fees to transactions
 * Added ability to [load custom plugins using Indy CLI](https://github.com/hyperledger/indy-sdk/tree/master/doc/design/006-cli-plugins)

doc/migration-guide-1.4.0-1.5.0.md

@@ -39,7 +39,12 @@ Functions from older version are listed in the left column, and the equivalent n
   for 3d party wallets implementations.
 * Libindy v1.5 changes wallet format to allow efficient and flexible search for entities with pagination support.
   *WARNING* wallet format of libindy v1.5 isn't compatible with a wallet format of libindy v1.4.
-* There have been added functions that allow performing Export/Import of Wallet.
+* There have been added functions that allow performing Export/Import of Wallet. Note these endpoints are EXPERIMENTAL.
+  Function signature and behavior may change in the future releases.
+* ```indy_list_wallets``` endpoint is DEPRECATED and will be removed in the next release. The main idea is avoid
+  maintaining created wallet list on libindy side. It will allow to access wallets from a cluster and solve
+  some problems on mobile platforms. ```indy_create_wallet``` and ```indy_open_wallet``` endpoints will
+  also get related changes in the next release.
 
 References:
 
@@ -480,6 +485,9 @@ This API is intended to provide the ability to register custom payment method an
 * Adding fees to transactions
 * Getting transactions fees amount
 
+Note all endpoints in this group are EXPERIMENTAL. Function signatures and behavior may change
+in the future releases.
+
 References:
 
 * [Payment Interface Design](https://github.com/hyperledger/indy-sdk/tree/master/doc/design/004-payment-interface)

libindy/debian/changelog

@@ -8,11 +8,15 @@ libindy (1.5.0) unstable; urgency=medium
     All encryption is performed in libindy. It simplifies plugged wallets and provides warranty of a good security level
     for 3d party wallets implementations.
   * The format of wallet data was changed for better security and support of efficient search
-* Added [Wallet Export/Import API](https://github.com/hyperledger/indy-sdk/tree/master/doc/design/009-wallet-export-import) and
+* Added EXPERIMENTAL [Wallet Export/Import API](https://github.com/hyperledger/indy-sdk/tree/master/doc/design/009-wallet-export-import) and
   corresponded commands to Indy CLI
+* ```indy_list_wallets``` endpoint is DEPRECATED and will be removed in the next release. The main idea is avoid
+  maintaining created wallet list on libindy side. It will allow to access wallets from a cluster and solve
+  some problems on mobile platforms. ```indy_create_wallet``` and ```indy_open_wallet``` endpoints will
+  also get related changes in the next release.
 * Added [Non-Secrets API](https://github.com/hyperledger/indy-sdk/tree/master/doc/design/003-wallet-storage#non-secrets-api) that allows store and read  
   application specific data in the wallet
-* Added [Generic Payments API](https://github.com/hyperledger/indy-sdk/tree/master/doc/design/004-payment-interface#payment-method-api) that provides
+* Added EXPERIMENTAL [Generic Payments API](https://github.com/hyperledger/indy-sdk/tree/master/doc/design/004-payment-interface#payment-method-api) that provides
   ability to register custom payment method
   and then create payment addresses, build payment-related transactions, assign fees to transactions
 * Added ability to [load custom plugins using Indy CLI](https://github.com/hyperledger/indy-sdk/tree/master/doc/design/006-cli-plugins)

libindy/src/api/payments.rs

@@ -265,6 +265,9 @@ pub type ParseGetTxnFeesResponseCB = extern fn(command_handle: i32,
 ///
 /// It allows library user to provide custom payment method implementation as set of handlers.
 ///
+/// Note this endpoint is EXPERIMENTAL. Function signature and behaviour may change
+/// in the future releases.
+///
 /// #Params
 /// command_handle: Command handle to map callback to caller context.
 /// payment_method: The type of payment method also used as sub-prefix for fully resolvable payment address format ("sov" - for example)
@@ -352,6 +355,9 @@ pub extern fn indy_register_payment_method(command_handle: i32,
 /// Note that payment method should be able to resolve this
 /// secret by fully resolvable payment address format.
 ///
+/// Note this endpoint is EXPERIMENTAL. Function signature and behaviour may change
+/// in the future releases.
+///
 /// #Params
 /// command_handle: command handle to map callback to context
 /// wallet_handle: wallet handle where to save new address
@@ -403,6 +409,9 @@ pub extern fn indy_create_payment_address(command_handle: i32,
 
 /// Lists all payment addresses that are stored in the wallet
 ///
+/// Note this endpoint is EXPERIMENTAL. Function signature and behaviour may change
+/// in the future releases.
+///
 /// #Params
 /// command_handle: command handle to map callback to context
 /// wallet_handle: wallet to search for payment_addresses in
@@ -454,6 +463,9 @@ pub extern fn indy_list_payment_addresses(command_handle: i32,
 /// Format of inputs is specific for payment method. Usually it should reference payment transaction
 /// with at least one output that corresponds to payment address that user owns.
 ///
+/// Note this endpoint is EXPERIMENTAL. Function signature and behaviour may change
+/// in the future releases.
+///
 /// #Params
 /// wallet_handle: wallet handle
 /// submitter_did : DID of request sender
@@ -520,6 +532,9 @@ pub extern fn indy_add_request_fees(command_handle: i32,
 
 /// Parses response for Indy request with fees.
 ///
+/// Note this endpoint is EXPERIMENTAL. Function signature and behaviour may change
+/// in the future releases.
+///
 /// #Params
 /// command_handle
 /// payment_method
@@ -568,6 +583,9 @@ pub extern fn indy_parse_response_with_fees(command_handle: i32,
 /// Builds Indy request for getting UTXO list for payment address
 /// according to this payment method.
 ///
+/// Note this endpoint is EXPERIMENTAL. Function signature and behaviour may change
+/// in the future releases.
+///
 /// #Params
 /// wallet_handle: wallet handle
 /// submitter_did : DID of request sender
@@ -617,6 +635,9 @@ pub extern fn indy_build_get_utxo_request(command_handle: i32,
 
 /// Parses response for Indy request for getting UTXO list.
 ///
+/// Note this endpoint is EXPERIMENTAL. Function signature and behaviour may change
+/// in the future releases.
+///
 /// #Params
 /// resp_json: response for Indy request for getting UTXO list
 ///   Note: this param will be used to determine payment_method
@@ -671,6 +692,9 @@ pub extern fn indy_parse_get_utxo_response(command_handle: i32,
 /// Format of inputs is specific for payment method. Usually it should reference payment transaction
 /// with at least one output that corresponds to payment address that user owns.
 ///
+/// Note this endpoint is EXPERIMENTAL. Function signature and behaviour may change
+/// in the future releases.
+///
 /// #Params
 /// wallet_handle: wallet handle
 /// submitter_did : DID of request sender
@@ -731,6 +755,9 @@ pub extern fn indy_build_payment_req(command_handle: i32,
 
 /// Parses response for Indy request for payment txn.
 ///
+/// Note this endpoint is EXPERIMENTAL. Function signature and behaviour may change
+/// in the future releases.
+///
 /// #Params
 /// command_handle
 /// payment_method
@@ -782,6 +809,9 @@ pub extern fn indy_parse_payment_response(command_handle: i32,
 /// Builds Indy request for doing tokens minting
 /// according to this payment method.
 ///
+/// Note this endpoint is EXPERIMENTAL. Function signature and behaviour may change
+/// in the future releases.
+///
 /// #Params
 /// wallet_handle: wallet handle
 /// submitter_did : DID of request sender
@@ -836,6 +866,9 @@ pub extern fn indy_build_mint_req(command_handle: i32,
 
 /// Builds Indy request for setting fees for transactions in the ledger
 ///
+/// Note this endpoint is EXPERIMENTAL. Function signature and behaviour may change
+/// in the future releases.
+///
 /// # Params
 /// command_handle
 /// wallet_handle: wallet handle
@@ -891,6 +924,9 @@ pub extern fn indy_build_set_txn_fees_req(command_handle: i32,
 
 /// Builds Indy get request for getting fees for transactions in the ledger
 ///
+/// Note this endpoint is EXPERIMENTAL. Function signature and behaviour may change
+/// in the future releases.
+///
 /// # Params
 /// command_handle
 /// wallet_handle: wallet handle
@@ -938,6 +974,9 @@ pub extern fn indy_build_get_txn_fees_req(command_handle: i32,
 
 /// Parses response for Indy request for getting fees
 ///
+/// Note this endpoint is EXPERIMENTAL. Function signature and behaviour may change
+/// in the future releases.
+///
 /// # Params
 /// command_handle
 /// payment_method

libindy/src/api/wallet.rs

@@ -270,6 +270,8 @@ pub extern fn indy_open_wallet(command_handle: i32,
 
 /// Lists created wallets as JSON array with each wallet metadata: name, type, name of associated pool
 ///
+/// Note this function is DEPRECATED and will be removed in the next release.
+///
 /// #Returns
 /// wallets list json: [{
 ///    "name": <string>
@@ -310,6 +312,9 @@ pub extern fn indy_list_wallets(command_handle: i32,
 
 /// Exports opened wallet
 ///
+/// Note this endpoint is EXPERIMENTAL. Function signature and behaviour may change
+/// in the future releases.
+///
 /// #Params:
 /// wallet_handle: wallet handle returned by indy_open_wallet
 /// export_config_json: JSON containing settings for input operation.
@@ -356,15 +361,18 @@ pub extern fn indy_export_wallet(command_handle: i32,
 }
 
 
-// Creates a new secure wallet with the given unique name and then imports its content
-// according to fields provided in import_config
-// This can be seen as an indy_create_wallet call with additional content import
-//
-// #Params
-// pool_name: Name of the pool that corresponds to this wallet
-// name: Name of the wallet
-// storage_type(optional): Type of the wallet storage. Defaults to 'default'.
-//                  Custom storage types can be registered with indy_register_wallet_storage_call
+/// Creates a new secure wallet with the given unique name and then imports its content
+/// according to fields provided in import_config
+/// This can be seen as an indy_create_wallet call with additional content import
+///
+/// Note this endpoint is EXPERIMENTAL. Function signature and behaviour may change
+/// in the future releases.
+///
+/// #Params
+/// pool_name: Name of the pool that corresponds to this wallet
+/// name: Name of the wallet
+/// storage_type(optional): Type of the wallet storage. Defaults to 'default'.
+///                  Custom storage types can be registered with indy_register_wallet_storage_call
 /// config(optional): Wallet configuration json.
 ///   {
 ///       "storage": <object>  List of supported keys are defined by wallet type.

wrappers/ios/libindy-pod/Indy/Wrapper/IndyWallet.h

@@ -115,6 +115,9 @@
 /**
  Exports opened wallet.
 
+ Note this endpoint is EXPERIMENTAL. Function signature and behavior may change
+ in the future releases.
+
  @param walletHandle  wallet handle returned by IndyWallet::openWalletWithName.
  @param exportConfigJson  JSON containing settings for input operation.
    {
@@ -132,6 +135,9 @@
  according to fields provided in import_config
  This can be seen as an indy_create_wallet call with additional content import
 
+ Note this endpoint is EXPERIMENTAL. Function signature and behavior may change
+ in the future releases.
+
  @param poolName   Name of the pool that corresponds to this wallet.
  @param name Name of the wallet.
  @param type Type of the wallet. Defaults to 'default'.

wrappers/java/src/main/java/org/hyperledger/indy/sdk/payments/Payments.java

@@ -107,6 +107,9 @@ public void callback(int xcommandHandle, int err, String mintReqJson, String pay
      *
      * Note that payment method should be able to resolve this
      * secret by fully resolvable payment address format.
+     *
+     * Note this endpoint is EXPERIMENTAL. Function signature and behaviour may change
+     * in the future releases.
      * @param wallet The wallet.
      * @param paymentMethod Payment method to use (for example, 'sov')
      * @param config payment address config as json:
@@ -145,6 +148,8 @@ public static CompletableFuture<String> createPaymentAddress(
     /**
      * Lists all payment addresses that are stored in the wallet
      *
+     * Note this endpoint is EXPERIMENTAL. Function signature and behaviour may change
+     * in the future releases.
      * @param wallet The wallet.
      * @return json array of string with json addresses
      * @throws IndyException
@@ -181,6 +186,9 @@ public static CompletableFuture<String> listPaymentAddresses(
      *
      * Format of inputs is specific for payment method. Usually it should reference payment transaction
      * with at least one output that corresponds to payment address that user owns.
+     *
+     * Note this endpoint is EXPERIMENTAL. Function signature and behaviour may change
+     * in the future releases.
      * @param wallet The wallet.
      * @param submitterDid DID of request sender
      * @param reqJson initial transaction request as json
@@ -231,6 +239,9 @@ public static CompletableFuture<AddRequestFeesResult> addRequestFees(
 
     /**
      * Parses response for Indy request with fees.
+     *
+     * Note this endpoint is EXPERIMENTAL. Function signature and behaviour may change
+     * in the future releases.
      * @param paymentMethod
      * @param respJson response for Indy request with fees
      * @return parsed (payment method and node version agnostic) utxo info as json:
@@ -251,6 +262,9 @@ public static CompletableFuture<String> parseResponseWithFees(
     /**
      * Builds Indy request for getting UTXO list for payment address
      * according to this payment method.
+     *
+     * Note this endpoint is EXPERIMENTAL. Function signature and behaviour may change
+     * in the future releases.
      * @param wallet The wallet.
      * @param submitterDid DID of request sender
      * @param paymentAddress target payment address
@@ -285,6 +299,8 @@ public static CompletableFuture<BuildGetUtxoRequestResult> buildGetUtxoRequest(
     /**
      * Parses response for Indy request for getting UTXO list.
      *
+     * Note this endpoint is EXPERIMENTAL. Function signature and behaviour may change
+     * in the future releases.
      * @param paymentMethod
      * @param respJson response for Indy request for getting UTXO list
      * @return parsed (payment method and node version agnostic) utxo info as json:
@@ -311,6 +327,8 @@ public static CompletableFuture<String> parseGetUtxoResponse(
      * Format of inputs is specific for payment method. Usually it should reference payment transaction
      * with at least one output that corresponds to payment address that user owns.
      *
+     * Note this endpoint is EXPERIMENTAL. Function signature and behaviour may change
+     * in the future releases.
      * @param wallet The wallet.
      * @param submitterDid DID of request sender
      * @param inputsJson The list of UTXO inputs as json array:
@@ -358,6 +376,8 @@ public static CompletableFuture<BuildPaymentReqResult> buildPaymentRequest(
     /**
      * Parses response for Indy request for payment txn.
      *
+     * Note this endpoint is EXPERIMENTAL. Function signature and behaviour may change
+     * in the future releases.
      * @param paymentMethod
      * @param respJson response for Indy request for payment txn
      * @return parsed (payment method and node version agnostic) utxo info as json:
@@ -379,6 +399,9 @@ public static CompletableFuture<String> parsePaymentResponse (
      * Builds Indy request for doing tokens minting
      * according to this payment method.
      *
+     * Note this endpoint is EXPERIMENTAL. Function signature and behaviour may change
+     * in the future releases.
+     *
      * @param wallet The wallet.
      * @param submitterDid DID of request sender
      * @param outputsJson The list of UTXO outputs as json array:
@@ -417,6 +440,9 @@ public static CompletableFuture<BuildMintReqResult> buildMintRequest(
 
     /**
      * Builds Indy request for setting fees for transactions in the ledger
+     *
+     * Note this endpoint is EXPERIMENTAL. Function signature and behaviour may change
+     * in the future releases.
      * @param wallet The wallet.
      * @param submitterDid DID of request sender
      * @param paymentMethod
@@ -460,6 +486,8 @@ public static CompletableFuture<String> buildSetTxnFeesRequest(
     /**
      * Builds Indy get request for getting fees for transactions in the ledger
      *
+     * Note this endpoint is EXPERIMENTAL. Function signature and behaviour may change
+     * in the future releases.
      * @param wallet The wallet.
      * @param submitterDid DID of request sender
      * @param paymentMethod
@@ -493,6 +521,9 @@ public static CompletableFuture<String> buildGetTxnFeesRequest(
 
     /**
      * Parses response for Indy request for getting fees
+     *
+     * Note this endpoint is EXPERIMENTAL. Function signature and behaviour may change
+     * in the future releases.
      * @param paymentMethod
      * @param respJson response for Indy request for getting fees
      * @return fees_json {

wrappers/java/src/main/java/org/hyperledger/indy/sdk/wallet/Wallet.java

@@ -267,6 +267,8 @@ public static CompletableFuture<Void> deleteWallet(
 	/**
 	 * Exports opened wallet to the file.
 	 *
+	 * Note this endpoint is EXPERIMENTAL. Function signature and behaviour may change
+     * the future releases.
 	 * @param wallet The wallet to export.
 	 * @param exportConfigJson: JSON containing settings for input operation.
 	 *   {
@@ -304,6 +306,8 @@ public static CompletableFuture<Void> exportWallet(
 	 * according to fields provided in import_config
 	 * This can be seen as an indy_create_wallet call with additional content import
 	 *
+	 * Note this endpoint is EXPERIMENTAL. Function signature and behaviour may change
+     * the future releases.
 	 * @param poolName Name of the pool that corresponds to this wallet.
 	 * @param name Name of the wallet.
 	 * @param xtype Type of the wallet. Defaults to 'default'.