Skip to content
This repository has been archived by the owner on Feb 29, 2024. It is now read-only.

Latest commit

 

History

History
818 lines (789 loc) · 25.8 KB

migration-guide-1.5.0-1.6.0.md

File metadata and controls

818 lines (789 loc) · 25.8 KB
Raw

Libindy 1.5 to 1.6 migration Guide

This document is written for developers using Libindy to provide necessary information and to simplify their transition to Libindy 1.6 from Libindy 1.5. If you are using older Libindy version you can check migration guides history:

Table of contents

Notes

Migration information is organized in tables, there are mappings for each Libindy API part of how older version functionality maps to a newer one. Functions from older version are listed in the left column, and the equivalent newer version function is placed in the right column:

  • If some function had been added, the word 'NEW' would be placed in the left column.
  • If some function had been deleted, the word 'DELETED' would be placed in the right column.
  • If some function had been deprecated, the word 'DEPRECATED' would be placed in the right column.
  • If some function had been changed, the current format would be placed in the right column.
  • If some function had not been changed, the symbol '=' would be placed in the right column.
  • To get more details about current format of a function click on the description above it.
  • Bellow are signatures of functions in Libindy C API. The params of cb (except command_handle and err) will be result values of the similar function in any Libindy wrapper.

Wallet API

The main idea of changes performed in Wallet API is to avoid maintaining created wallet list on Libindy side. It allows to access wallets from a cluster and solves some problems on mobile platforms.

The following changes have been performed:

  • Changed Wallet export serialization:
    • Use MsgPack instead of custom entities serialization to be more reliable and allow extend-ability in backward compatible way.
    • Changed header format to be more reliable and allow extend-ability in backward compatible way.
    • Use STOP message to make sure that there was no truncation of export file.
    • Removed EXPERIMENTAL notice for import/export API endpoints.
  • Removed association between Wallet and Pool.
  • Removed persistence of Wallet configuration by Libindy.
  • A significant part of Wallet APIs has been updated to accept wallet configuration as a single json which provides whole wallet configuration. This wallet configuration json has the following format:
 {
   "id": string, Identifier of the wallet.
         Configured storage uses this identifier to lookup exact wallet data placement.
   "storage_type": optional<string>, Type of the wallet storage. Defaults to 'default'.
                  'Default' storage type allows to store wallet data in the local file.
                  Custom storage types can be registered with indy_register_wallet_storage call.
   "storage_config": optional<object>, Storage configuration json. Storage type defines set of supported keys.
                     Can be optional if storage supports default configuration.
                     For 'default' storage type configuration is:
   {
     "path": optional<string>, Path to the directory with wallet files.
             Defaults to $HOME/.indy_client/wallets.
             Wallet will be stored in the file {path}/{id}/sqlite.db
   }
 }

WARNING Wallet format of libindy v1.6 isn't compatible with a wallet format of libindy v1.5.

v1.5.0 - Wallet API v1.6.0 - Wallet API
Create a new secure wallet 
indy_create_wallet(command_handle: i32,
                   pool_name: *const c_char,
                   name: *const c_char,
                   xtype: *const c_char,
                   config: *const c_char,
                   credentials: *const c_char,
                   cb: Option)
      
indy_create_wallet(command_handle: i32,
                   config: *const c_char,
                   credentials: *const c_char,
                   cb: Option)
Note: Format of config parameter was changed. Current format is described above.
Open the wallet 
indy_open_wallet(command_handle: i32,
                 name: *const c_char,
                 runtime_config: *const c_char,
                 credentials_json: *const c_char,
                 cb: Option)
      
indy_open_wallet(command_handle: i32,
                 config: *const c_char,
                 credentials: *const c_char,
                 cb: Option)
Note: Format of config parameter was changed. Current format is described above.
Deletes created wallet 
indy_delete_wallet(command_handle: i32,
                   name: *const c_char,
                   credentials: *const c_char,
                   cb: Option)
      
indy_delete_wallet(command_handle: i32,
                   config: *const c_char,
                   credentials: *const c_char,
                   cb: Option)
Note: Format of config parameter was changed. Current format is described above.
Import wallet 
indy_import_wallet(
            command_handle: i32,
            pool_name: *const c_char,
            name: *const c_char,
            storage_type: *const c_char,
            config: *const c_char,
            credentials: *const c_char,
            import_config_json: *const c_char,
            cb: fn(xcommand_handle: i32, 
                   err: ErrorCode))
        
indy_import_wallet(
            command_handle: i32,
            config: *const c_char,
            credentials: *const c_char,
            import_config_json: *const c_char,
            cb: fn(xcommand_handle: i32, 
                   err: ErrorCode))
Note: Format of config parameter was changed. Current format is described above.
Lists created wallets 
indy_list_wallets(command_handle: i32,
                  cb: fn(xcommand_handle: i32,
                         err: ErrorCode,
                         wallets: *const c_char))
DELETED

Anoncreds API

The main idea of changes performed in Anoncreds API is integration tags based search to Anoncreds workflow as it has done in Non-Secrets API.

  • Create tags for a stored object.
  • Provide efficient and flexible search for entities using WQL.
  • Avoid immediately returning all matched records.
  • Provide ability to fetch records by small batches.

The following changes have been performed:

  • Updated behavior of indy_prover_store_credential API function to create tags for a stored credential object. Here is the list of tags will be created:
{
    "schema_id": <credential schema id>,
    "schema_issuer_did": <credential schema issuer did>,
    "schema_name": <credential schema name>,
    "schema_version": <credential schema version>,
    "issuer_did": <credential issuer did>,
    "cred_def_id": <credential definition id>,
    // for every attribute in <credential values>
    "attr::<attribute name>::marker": "1", // to check existence of attribute
    "attr::<attribute name>::value": <attribute raw value>, // to check value of attribute
}
  • indy_prover_get_credential was added to Libindy Anoncreds API to allow getting human readable credential by the given id.
  • Updated indy_prover_get_credentials and indy_prover_get_credentials_for_proof_req API functions to support tags based search.
  • indy_prover_get_credentials endpoint marked as DEPRECATED and will be removed in the next release because immediately returns all fetched credentials.
  • indy_prover_get_credentials_for_proof_req endpoint marked as DEPRECATED and will be removed in the next release because immediately returns all fetched credentials.
  • Added two chains of APIs related to credentials search that allows fetching records by batches:
    • Simple credentials search - indy_prover_search_credentials -> indy_prover_fetch_credentials -> indy_prover_close_credentials_search
    • Search credentials for proof request - indy_prover_search_credentials_for_proof_req -> indy_prover_fetch_credentials_for_proof_req -> indy_prover_close_credentials_search_for_proof_req

Note:

  • Functions indy_prover_get_credentials and indy_prover_get_credentials_for_proof_req support both formats of queries: old strict filter and WQL.
  • Functions indy_prover_search_credentials and indy_prover_search_credentials_for_proof_req support only WQL format of queries.

References:

v1.5.0 - Anoncreds API v1.6.0 - Anoncreds API
Gets human readable credential by the given id
NEW 
indy_prover_get_credential(
            command_handle: i32,
            wallet_handle: i32,
            cred_id: *const c_char,
            cb: fn(xcommand_handle: i32, 
                   err: ErrorCode,
                   credential_json: *const c_char))
Gets human readable credentials according to the filter 
indy_prover_get_credentials(
        command_handle: i32,
        wallet_handle: i32,
        filter_json: *const c_char,
        cb: fn(xcommand_handle: i32, 
               err: ErrorCode,
               credentials_json: *const c_char))
DEPRECATED
Search for credentials stored in wallet
NEW 
indy_prover_search_credentials(
            command_handle: i32,
            wallet_handle: i32,
            query_json: *const c_char,
            cb: fn(xcommand_handle: i32, 
                   err: ErrorCode,
                   search_handle: i32,
                   total_count: usize))
Fetch next credentials for search
NEW 
indy_prover_fetch_credentials(
            command_handle: i32,
            search_handle: i32,
            count: usize,
            cb: fn(command_handle_: i32, 
                   err: ErrorCode,
                   credentials_json: *const c_char))
Close credentials search
NEW 
indy_prover_close_credentials_search(
            command_handle: i32,
            search_handle: i32,
            cb: fn(command_handle_: i32, 
                   err: ErrorCode))
Gets human readable credentials matching the given proof request 
indy_prover_get_credentials_for_proof_req(
        command_handle: i32,
        wallet_handle: i32,
        proof_request_json: *const c_char,
        cb: fn(xcommand_handle: i32, 
               err: ErrorCode,
               credentials_json: *const c_char))
DEPRECATED
Search for credentials matching the given proof request.
NEW 
indy_prover_search_credentials_for_proof_req(
            command_handle: i32,
            wallet_handle: i32,
            proof_request_json: *const c_char,
            extra_query_json: *const c_char,
            cb: fn(xcommand_handle: i32, 
                   err: ErrorCode,
                   search_handle: i32))
      NOTE: Added parameter extra_query_json.
      Using this parameter you can pass an additional 
      query to any attribute/predicate in a proof request.
Fetch next credentials for the requested item using proof request search handle
NEW 
indy_prover_fetch_credentials_for_proof_req(
            command_handle: i32,
            search_handle: i32,
            item_referent: *const c_char,
            count: usize,
            cb: fn(command_handle_: i32, 
                   err: ErrorCode,
                   credentials_json: *const c_char))
Close credentials search for proof request
NEW 
indy_prover_close_credentials_search_for_proof_req(
            command_handle: i32,
            search_handle: i32,
            cb: fn(command_handle_: i32, 
                   err: ErrorCode))

Payments API

The main idea of changes performed in Payment API is avoiding UTXO based payments approach. Payment API has been updated to support non-UTXO based crypto payments and traditional payments like VISA.

Note: Removed EXPERIMENTAL notice for API endpoints.

The following changes have been performed:

  • Changed format of input and output parameters.
  • Changed format of result values of indy_parse_response_with_fees and indy_parse_payment_response API functions.
  • Renamed indy_build_get_utxo_request and indy_parse_get_utxo_response API functions.
  • Added indy_build_verify_payment_req and indy_parse_verify_payment_response API functions.
v1.5.0 - Payment API v1.6.0 - Payment API
Modifies Indy request by adding information how to pay fees for this transaction according to selected payment method 
indy_add_request_fees(
        command_handle: i32,
        wallet_handle: i32,
        submitter_did: *const c_char,
        req_json: *const c_char,
        inputs_json: *const c_char,
        outputs_json: *const c_char,
        cb: fn(command_handle_: i32,
               err: ErrorCode,
               req_with_fees_json: *const c_char,
               payment_method: *const c_char))
      
Left the same but the format of outputs has been 
changed to:
[{
  recipient: , // payment address of recipient
  amount: , // amount
  extra: , // optional data
}]
Parses response for Indy request with fees 
indy_parse_response_with_fees(
        command_handle: i32,
        payment_method: *const c_char,
        resp_json: *const c_char,
        cb: fn(command_handle_: i32,
               err: ErrorCode,
               utxo_json: *const c_char))
      
indy_parse_response_with_fees(
        command_handle: i32,
        payment_method: *const c_char,
        resp_json: *const c_char,
        cb: fn(command_handle_: i32,
               err: ErrorCode,
               receipts_json: *const c_char))
NOTE: Format of result value has been changed to:
[{
   receipt: , // receipt that can be used for 
             payment referencing and verification
   recipient: , //payment address of recipient
   amount: , // amount
   extra: , // optional data from payment transaction
}]
Builds Indy request for getting sources list for payment address according to this payment method 
indy_build_get_utxo_request(
        command_handle: i32,
        wallet_handle: i32,
        submitter_did: *const c_char,
        payment_address: *const c_char,
        cb: fn(command_handle_: i32,
               err: ErrorCode,
               get_utxo_txn_json: *const c_char,
               payment_method: *const c_char))
      
indy_build_get_sources_request(
        command_handle: i32,
        wallet_handle: i32,
        submitter_did: *const c_char,
        payment_address: *const c_char,
        cb: fn(command_handle_: i32,
               err: ErrorCode,
               get_sources_txn_json: *const c_char,
               payment_method: *const c_char))
NOTE: Function and result value have been renamed.
Parses response for Indy request for getting sources list 
indy_parse_get_utxo_response(
        command_handle: i32,
        payment_method: *const c_char,
        resp_json: *const c_char,
        cb: fn(command_handle_: i32,
               err: ErrorCode,
               utxo_json: *const c_char))
      
indy_parse_get_sources_response(
        command_handle: i32,
        payment_method: *const c_char,
        resp_json: *const c_char,
        cb: fn(command_handle_: i32,
               err: ErrorCode,
               sources_json: *const c_char))
NOTE: Function and result value have been renamed.
NOTE: sources have the following format:
[{
   source: , // source input
   paymentAddress: , //payment address for this source
   amount: , // amount
   extra: , // optional data from payment transaction
}]
Builds Indy request for doing payment according to this payment method 
indy_build_payment_req(
        command_handle: i32,
        wallet_handle: i32,
        submitter_did: *const c_char,
        inputs_json: *const c_char,
        outputs_json: *const c_char,
        cb: fn(command_handle_: i32,
               err: ErrorCode,
               payment_req_json: *const c_char,
               payment_method: *const c_char))
      
Left the same but the format of outputs has been 
changed to:
[{
  recipient: , // payment address of recipient
  amount: , // amount
  extra: , // optional data
}]
Builds Indy request for doing payment according to this payment method 
indy_parse_payment_response(
            command_handle: i32,
            payment_method: *const c_char,
            resp_json: *const c_char,
            cb: fn(command_handle_: i32,
                   err: ErrorCode,
                   utxo_json: *const c_char))
      
indy_parse_payment_response(
            command_handle: i32,
            payment_method: *const c_char,
            resp_json: *const c_char,
            cb: fn(command_handle_: i32,
                   err: ErrorCode,
                   receipts_json: *const c_char))
NOTE: Format of result value has been changed to:
[{
   receipt: , // receipt that can be used for 
             payment referencing and verification
   recipient: , //payment address of recipient
   amount: , // amount
   extra: , // optional data from payment transaction
}]
Builds Indy request for doing tokens minting according to this payment method 
indy_build_mint_req(
        command_handle: i32,
        wallet_handle: i32,
        submitter_did: *const c_char,
        outputs_json: *const c_char,
        cb: fn(command_handle_: i32,
               err: ErrorCode,
               mint_req_json: *const c_char,
               payment_method: *const c_char))
      
Left the same but the format of outputs has been 
changed to:
[{
  recipient: , // payment address of recipient
  amount: , // amount
  extra: , // optional data
}]
Builds Indy request for information to verify the payment receipt
NEW 
indy_build_verify_payment_req(
        command_handle: i32,
        wallet_handle: i32,
        submitter_did: *const c_char,
        receipt: *const c_char,
        cb: fn(command_handle_: i32,
               err: ErrorCode,
               verify_txn_json: *const c_char,
               payment_method: *const c_char))
Parses Indy response with information to verify receipt
NEW 
indy_parse_verify_payment_response(
        command_handle: i32,
        payment_method: *const c_char,
        resp_json: *const c_char,
        cb: fn(command_handle_: i32,
               err: ErrorCode,
               txn_json: *const c_char))

Pool API

v1.5.0 - Pool API v1.6.0 - Pool API
Opens pool ledger and performs connecting to pool nodes 
indy_open_pool_ledger(command_handle: i32,
                      config_name: *const c_char,
                      config: *const c_char,
                      cb: fn(xcommand_handle: i32,
                           err: ErrorCode,
                           pool_handle: i32))
      
Left the same but the format of config has been changed to:
{
   "timeout": int (optional), timeout for network request (in sec).
   "extended_timeout": int (optional), extended timeout for network request (in sec).
   "preordered_nodes": array - (optional), names of nodes which will 
       have a priority during request sending:
       ["name_of_1st_prior_node",  "name_of_2nd_prior_node", .... ]
       Note: Not specified nodes will be placed in a random way.
}