Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: spellling and reference to order of migration #111

Merged
merged 1 commit into from
Apr 5, 2023
Merged

docs: spellling and reference to order of migration #111

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
82 changes: 22 additions & 60 deletions guides/updating/update-indy-sdk-to-askar.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,14 +1,10 @@
# Migrating from an Indy SDK Wallet to Aries Askar

This documentation explains the process of migrating your Indy-sdk wallet to
[Aries Askar](https://github.com/hyperledger/aries-askar).
This documentation explains the process of migrating your Indy-sdk wallet to [Aries Askar](https://github.com/hyperledger/aries-askar).

:::danger

While the migration script techinically works on node.js, it is strongly
advised not to use it, yet. The mean reason for this is that the Credential
Definition migration is not done yet. When a credential definition is detected
it will revert the migration process and no harm is done.
While the migration script techinically works on node.js, it is strongly advised not to use it, yet. The mean reason for this is that the Credential Definition migration is not done yet. When a credential definition is detected it will revert the migration process and no harm is done.

:::

Expand All @@ -20,115 +16,85 @@ Postgres is not supported, yet.

:::caution

The migration script is supported for 0.4.x (or moving from 0.3.x to 0.4.x).
Please refer to [Migrating from AFJ 0.3.x to 0.4.x](./versions/0.3-to-0.4.md)
to get to 0.4.x.
The migration script is supported to run on 0.3.x before migrating from 0.3.x to 0.4.x. Please refer to [Migrating from AFJ 0.3.x to 0.4.x](./versions/0.3-to-0.4.md) to get to 0.4.x afterwards.

It is important to note that this script must be ran before you update from 0.3.x to 0.4.x.

:::

## What does the migration do internally?

The migration script does the following to make sure everything is migrated
properly, and if anything goes wrong, it will revert back to a working state.
The migration script does the following to make sure everything is migrated properly, and if anything goes wrong, it will revert back to a working state.

### Create a backup

Because undefined behaviour might occur, we create a backup in the new `tmp`
directory from Aries Framework JavaScript. if some error occurs, it will be
reverted back to the backed-up state and if no error occurs, it will delete the
backup from the temporary directory.
Because undefined behaviour might occur, we create a backup in the new `tmp` directory from Aries Framework JavaScript. if some error occurs, it will be reverted back to the backed-up state and if no error occurs, it will delete the backup from the temporary directory.

### Migrate the database to an Aries Askar structure

The Indy-sdk and Aries Askar have different database structures. So first of
all we need to change some table names, decrypt all the items with the old Indy
keys, encrypt the items with the new Aries Askar keys and store them inside the
new structure.
The Indy-sdk and Aries Askar have different database structures. So first of all we need to change some table names, decrypt all the items with the old Indy keys, encrypt the items with the new Aries Askar keys and store them inside the new structure.

### Try to open the wallet in the new Aries Askar structure

When the wallet is correctly transformed, the wallet will be attempted to be
openend.
When the wallet is correctly transformed, the wallet will be attempted to be openend.

### Update the keys

Aries Askar has a specific way to store keys and every key, defined by the
category of `Indy::Key` will be migrated.
Aries Askar has a specific way to store keys and every key, defined by the category of `Indy::Key` will be migrated.

### Update the Dids

:::caution

This update script does not transform did records. This is fine for something
like `did:peer`, but will cause issues with `indy` and `sov` dids. For more
information, please check out the [Migrating from AFJ 0.3.x to
0.4.x](./versions/0.3-to-0.4.md#removal-of-publicdidseed-and-publicdid)
This update script does not transform did records. This is fine for something like `did:peer`, but will cause issues with `indy` and `sov` dids. For more information, please check out the [Migrating from AFJ 0.3.x to 0.4.x](./versions/0.3-to-0.4.md#removal-of-publicdidseed-and-publicdid)

:::

### Update the credential definitions

:::danger

Updating of credential definitions is not yet supported. This is why it is
strongly advised not to run this script in a node.js environment.
Updating of credential definitions is not yet supported. This is why it is strongly advised not to run this script in a node.js environment.

:::

### Update the link secret(s) (master secret)

The link sercets, identified by the category `Indy::MasterSecret`, are updated
next. They are stored inside a new `AnonCredsLinkSecretRecord`.
The link sercets, identified by the category `Indy::MasterSecret`, are updated next. They are stored inside a new `AnonCredsLinkSecretRecord`.

:::caution

Since we have to set a default link secret, some additional logic is added to
detect this. You can either supply a `defaultLinkSercetId` as a constructor
parameter or it will be based on your `walletId`.
Since we have to set a default link secret, some additional logic is added to detect this. You can either supply a `defaultLinkSercetId` as a constructor parameter or it will be based on your `walletId`.

If there is no Indy record with the `defaultLinkSecretId` or the `walletId`, an
error will be thrown and the migration will be restored.
If there is no Indy record with the `defaultLinkSecretId` or the `walletId`, an error will be thrown and the migration will be restored.

:::

### Update the credentials

The credentials, identified by the category `Indy::Credential` are updated
last. They are stored in the new `AnonCredsCredentialRecord` as a one-to-one
copy. This means that they now support more tags and will make querying a lot
easier.
The credentials, identified by the category `Indy::Credential` are updated last. They are stored in the new `AnonCredsCredentialRecord` as a one-to-one copy. This means that they now support more tags and will make querying a lot easier.

### All the other records

All the other records will be transferred without any updates as they are not
Indy specific.
All the other records will be transferred without any updates as they are not Indy specific.

## How to update

Updating does not require a lot of code, but must be done with caution.

It is very important to note that the migration script only has to be run once.
If it runs for a second time, it will error saying that the database is already
migrated. Also, when the migration is finished, it is common practise to store
this state in your persistent app storage. This script does not provide a way
to detect if an update has happened, so storing this value will prevent the
script from running every time. For more information regarding this topic,
please check out [Update
Assistant](./update-assistant.md#storing-the-agent-storage-version-outside-of-the-agent-storage).
It is very important to note that the migration script only has to be run once. If it runs for a second time, it will error saying that the database is already migrated. Also, when the migration is finished, it is common practise to store this state in your persistent app storage. This script does not provide a way to detect if an update has happened, so storing this value will prevent the script from running every time. For more information regarding this topic, please check out [Update Assistant](./update-assistant.md#storing-the-agent-storage-version-outside-of-the-agent-storage).

### add the required dependencies:

```sh
yarn add @hyperledger/aries-askar-react-native @aries-framework/indy-sdk-to-askar-migration react-native-fs
```

Below is the minimal code required for the migration to work. It is recommended
to turn the logger on as it gives a lot of information regarding the migration.
Below is the minimal code required for the migration to work. It is recommended to turn the logger on as it gives a lot of information regarding the migration.

:::caution

The agent is not allowed to be initialized to run this script. This makes sure
nothing else happens during the migration.
The agent is not allowed to be initialized to run this script. This makes sure nothing else happens during the migration.

:::

Expand Down Expand Up @@ -159,9 +125,7 @@ await updater.update()

On android, the database is commonly located under the `ExternalDirectoryPath`.

If you did not follow the default indy-sdk for React Native setup, your path
might differ. Check out [step 5 of the Android setup for Indy SDK React Native](https://github.com/hyperledger/indy-sdk-react-native#5-load-indy-library)
for the default behaviour.
If you did not follow the default indy-sdk for React Native setup, your path might differ. Check out [step 5 of the Android setup for Indy SDK React Native](https://github.com/hyperledger/indy-sdk-react-native#5-load-indy-library) for the default behaviour.

```typescript
import fs from 'react-native-fs'
Expand All @@ -179,9 +143,7 @@ const dbPath = `${base}/${indyClient}/${wallet}/${walletId}/${file}`

On iOS, the database is commonly located under the `DocumentDirectoryPath`.

For iOS this can only change if your phone does not have the `HOME` environment
variable set. This is not usual behaviour, and if `HOME` is not set, the `base`
in the code section below will be `/home/indy/Documents`.
For iOS this can only change if your phone does not have the `HOME` environment variable set. This is not usual behaviour, and if `HOME` is not set, the `base` in the code section below will be `/home/indy/Documents`.

```typescript
import fs from 'react-native-fs'
Expand Down
Loading