chore: v8 migration guide

README.md

@@ -10,13 +10,23 @@ Note: If you prefer Python there's an equivalent [Python utility library](https:
 
 ## Install
 
-This library can be installed from NPM using your favourite npm client, e.g.:
+Before installing, you'll need to decide on the version you want to target. Version 7 and 8 have the same feature set, however v7 leverages algosdk@>=2.9.0<3.0, whereas v8 leverages algosdk@>=3.0.0. Your project and it's dependencies will help you decide which version to target.
+
+Once you've decided on the target version, this library can be installed from NPM using your favourite npm client, e.g.:
+
+To target algosdk@2 and use version 7 of AlgoKit Utils, run the below:
+
+```
+npm install algosdk@^2.9.0 @algorandfoundation/algokit-utils@^7.0.0
+```
+
+To target algosdk@3 and use the latest version of AlgoKit Utils, run the below:
 
 ```
-npm install algosdk@2 @algorandfoundation/algokit-utils
+npm install algosdk@^3.0.0 @algorandfoundation/algokit-utils
 ```
 
-Then to import it:
+Now you can import the library:
 
 ```typescript
 import { AlgorandClient, Config } from '@algorandfoundation/algokit-utils'
@@ -30,6 +40,7 @@ Whilst we aim to minimise breaking changes, there are situations where they are
 JSDoc deprecations should guide you through most migration paths inside your IDE, however the migration guides will provide more detailed information should you need it.
 
 If you're targetting v7, please refer to the [v7 migration guide](./docs/v7-migration.md).
+If you're targetting v8, please refer to the [v8 migration guide](./docs/v8-migration.md).
 
 ## Guiding principles
 

docs/README.md

@@ -18,15 +18,25 @@ This library is designed with the following principles:
 
 # Installation
 
-This library can be installed from NPM using your favourite npm client, e.g.:
+Before installing, you'll need to decide on the version you want to target. Version 7 and 8 have the same feature set, however v7 leverages algosdk@>=2.9.0<3.0, whereas v8 leverages algosdk@>=3.0.0. Your project and it's dependencies will help you decide which version to target.
+
+Once you've decided on the target version, this library can be installed from NPM using your favourite npm client, e.g.:
+
+To target algosdk@2 and use version 7 of AlgoKit Utils, run the below:
+
+```
+npm install algosdk@^2.9.0 @algorandfoundation/algokit-utils@^7.0.0
+```
+
+To target algosdk@3 and use the latest version of AlgoKit Utils, run the below:
 
 ```
-npm install @algorandfoundation/algokit-utils
+npm install algosdk@^3.0.0 @algorandfoundation/algokit-utils
 ```
 
 ## Peer Dependencies
 
-This library requires `algosdk@2.9.0` as a peer dependency. Ensure you have it installed in your project.
+This library uses `algosdk` as a peer dependency. Please see above to ensure you have the correct version installed in your project.
 
 # Usage
 

docs/v7-migration.md

@@ -8,9 +8,9 @@ The old version will still work until at least v9 (we have been careful to keep
 
 An early version of the AlgorandClient was released in v6.1.0. The intention was to evolve the stateful class-based interface without any breaking changes, however unfortunately that wasn't possible.
 
-As a result we have 2 supported migration paths: [Pre 6.1.0](#pre-610-migration-guide) and [Post 6.1.0](#post-610-migration-guide).
+As a result we have 2 supported migration paths: [<6.1.0](#610-migration-guide) and [>=6.1.0](#610-migration-guide-1).
 
-## Pre 6.1.0 Migration Guide
+## <6.1.0 Migration Guide
 
 We have been diligently adding JSDoc deprecations to the code. We recommend that after reading this guide you leverage the deprecation messages inside your IDE to guide you through the migration process.
 
@@ -36,7 +36,7 @@ const payment = await algokit.transferAlgos({
 /**** After ****/
 import { AlgorandClient } from '@algorandfoundation/algokit-utils'
 const algorand = await AlgorandClient.fromEnvironment()
-const account = algorand.account.fromEnvironment('MY_ACCOUNT', (2).algo())
+const account = await algorand.account.fromEnvironment('MY_ACCOUNT', (2).algo())
 const payment = await algorand.send.payment({
   sender: account.addr,
   receiver: 'RECEIVER',
@@ -144,9 +144,9 @@ If you are converting from an older typed client to a new one you will need to m
 - `client.compose()` is now `client.newGroup()`
 - `client.compose()....execute()` is now `client.compose()....send()`
 
-## Post 6.1.0 Migration Guide
+## >=6.1.0 Migration Guide
 
-Assuming you have actioned the deprecation notices as part of moving to a post `6.1.0` version and have started using the early version of the AlgorandClient, then you need to be aware of some breaking changes that we have made to accommodate the featureset of v7. Any migration information related to the stateless function based interface is available in the [Pre 6.1.0 Migration Guide](#pre-610-migration-guide).
+Assuming you have actioned the deprecation notices as part of moving to the `>=6.1.0` version and have started using the early version of the `AlgorandClient`, then you need to be aware of some breaking changes that we have made to accommodate the feature set of v7. Any migration information related to the stateless function based interface is available in the [<6.1.0 Migration Guide](#610-migration-guide).
 
 ### Migrating
 

docs/v8-migration.md

@@ -0,0 +1,105 @@
+# v8 migration
+
+Version 8 of AlgoKit Utils adds support for algosdk@3. This algosdk version has a number of major breaking changes and as a result we have also needed to make some breaking changes to support it. All changes between version 7 and 8 have been made to support algosdk@3.
+
+Depending on the complexity of your project, you may find that first migrating to version 7, then migrating to version 8 is easier and offers a more gradual experience. Either way this migration will heavily reference the [v7 migration guide](./v7-migration.md) as it documents the majority of changes you will likely need to make.
+
+## <6.1.0 Migration Guide
+
+### Migrating
+
+#### Step 1 - Learn about the changes between version 7 and 8
+
+First read the [>=7.0.0 migration guide](#700-migration-guide) below to familiarise yourself with the version 7 to 8 changes. This will give you the context needed to successfully execute the next step.
+
+#### Step 2 - Migrate using the version 7 migration guide
+
+Using the context gathered from Step 1, you should have all the information you need to migrate using the [version 7 migration guide](./v7-migration.md#610-migration-guide).
+
+A simple example of the before and after follows:
+
+```typescript
+/**** Before ****/
+import * as algokit from '@algorandfoundation/algokit-utils'
+const algod = algokit.getAlgoClient()
+const account = await algokit.mnemonicAccountFromEnvironment(
+  {
+    name: 'MY_ACCOUNT',
+    fundWith: algokit.algos(2),
+  },
+  algod,
+)
+const payment = await algokit.transferAlgos({
+  from: account,
+  to: 'RECEIVER',
+  amount: algokit.algos(1),
+})
+
+/**** After ****/
+import { AlgorandClient } from '@algorandfoundation/algokit-utils'
+const algorand = await AlgorandClient.fromEnvironment()
+const account = await algorand.account.fromEnvironment('MY_ACCOUNT', (2).algo())
+const payment = await algorand.send.payment({
+  sender: account, // NOTE: .addr has been removed from the v7 version of this same code
+  receiver: 'RECEIVER',
+  amount: (1).algo(),
+})
+```
+
+## >=6.1.0<7.0.0 Migration Guide
+
+### Migrating
+
+#### Step 1 - Learn about the changes between version 7 and 8
+
+First read the [>=7.0.0 migration guide](#700-migration-guide) below to familiarise yourself with the version 7 to 8 changes. This will give you the context needed to successfully execute the next step.
+
+#### Step 2 - Migrate using the version 7 migration guide
+
+Using the context gathered from Step 1, you should have all the information you need to migrate using the [version 7 migration guide](./v7-migration.md#610-migration-guide-1).
+
+## >=7.0.0 Migration Guide
+
+This migration path assumes you have actioned all the deprecation notices as part of moving to the `>=7.0.0` version and you are using the `AlgorandClient` and it's related abstractions. Given this, all changes you'll need to make are directly related to upgrading from algosdk@2 to algosdk@3.
+
+While AlgoKit utils now wraps most of the algosdk functionality, it's likely you may have functionality that uses algosdk directly. As as result you may need to refer to the [algosdk v3 migration guide](https://github.com/algorand/js-algorand-sdk/blob/develop/v2_TO_v3_MIGRATION_GUIDE.md.
+
+### Migrating
+
+#### Step 1 - Accommodate usages of addresses
+
+The biggest change in this release is that addresses are consistently typed using `Address` from algosdk@3. All of the AlgoKit Utils methods that previously took a `string` for an account address now take `string | Address` so the impact of this change should be minimal.
+
+The majority of changes should simply be either adding or removing `.addr` from the account like type that you are using, like below:
+
+```typescript
+/**** Before ****/
+const payment = await algorand.send.payment({
+  sender: account.addr,
+  receiver: 'RECEIVER',
+  amount: (1).algo(),
+})
+
+/**** After ****/
+const payment = await algorand.send.payment({
+  sender: account, // NOTE: .addr has been removed here
+  receiver: 'RECEIVER',
+  amount: (1).algo(),
+})
+```
+
+Whilst the above is cleaner, it's generally not required as `string` is also supported.
+
+#### Step 2 - Remove usages of performAtomicTransactionComposerDryrun
+
+The dryrun feature has long been deprecated and it isn't compatible with algosdk@3, as a result we had to remove support for it. It's likely you can instead use the simulate feature like below:
+
+```typescript
+const payment = await algorand.createTransaction.payment({
+  sender: 'SENDER',
+  receiver: 'RECEIVER',
+  amount: (1).algo(),
+})
+
+const result = await algorand.newGroup().addTransaction(payment).simulate()
+```