feat: upgrade algosdk to v3

README.md

@@ -2,10 +2,32 @@
 
 This library a simple, but flexible / configurable Algorand transaction subscription / indexing mechanism. It allows you to quickly create Node.js or JavaScript services that follow or subscribe to the Algorand Blockchain.
 
-> npm install @algorandfoundation/algokit-subscriber
-
 [Documentation](./docs/README.md)
 
+## Install
+
+Before installing, you'll need to decide on the version you want to target. Version 2 and 3 have largerly the same feature set, however v2 leverages algosdk@>=2.9.0<3.0, whereas v3 leverages algosdk@>=3.0.0. It is recommended that you aim to target the latest version, however in some circumstances that might not be possible.
+
+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 2 of AlgoKit Subscriber, run the below:
+
+```
+npm install algosdk@^2.10.0 @algorandfoundation/algokit-utils@^7.1.0 @algorandfoundation/algokit-subscriber@^2.2.0
+```
+
+To target algosdk@3 and use the latest version of AlgoKit Subscriber, run the below:
+
+```
+npm install algosdk@^3.1.0 @algorandfoundation/algokit-utils @algorandfoundation/algokit-subscriber
+```
+
+## Migration
+
+Whilst we aim to minimise breaking changes, there are situations where they are required.
+
+If you're migrating from an older version to v3, please refer to the [v3 migration guide](./docs/v3-migration.md).
+
 ## Quick start
 
 ```typescript
@@ -70,8 +92,8 @@ The balance change for an asset create transaction will be as below:
 ```json
 {
   "address": "VIDHG4SYANCP2GUQXXSFSNBPJWS4TAQSI3GH4GYO54FSYPDIBYPMSF7HBY", // The asset creator
-  "assetId": 2391, // The created asset id
-  "amount": 100000, // Full asset supply of the created asset
+  "assetId": 2391n, // The created asset id
+  "amount": 100000n, // Full asset supply of the created asset
   "roles": ["AssetCreator"]
 }
 ```
@@ -82,11 +104,11 @@ If you need to account for the asset supply being destroyed from the creators ac
 
 The balance change for an asset destroy transaction will be as below:
 
-```json
+```typescript
 {
   "address": "PIDHG4SYANCP2GUQXXSFSNBPJWS4TAQSI3GH4GYO54FSYPDIBYPMSF7HBY", // The asset destroyer, which will always be the asset manager
-  "assetId": 2391, // The destroyed asset id
-  "amount": 0, // This value will always be 0
+  "assetId": 2391n, // The destroyed asset id
+  "amount": 0n, // This value will always be 0
   "roles": ["AssetDestroyer"]
 }
 ```
@@ -101,7 +123,7 @@ The watermark is stored in-memory so this particular example is not resilient to
 
 ```typescript
 const algorand = AlgorandClient.fromEnvironment()
-let watermark = 0
+let watermark = 0n
 const subscriber = new AlgorandSubscriber(
   {
     events: [
@@ -146,7 +168,7 @@ The following code, when algod is pointed to MainNet, will find all transfers of
 
 ```typescript
 const algorand = AlgorandClient.fromEnvironment()
-let watermark = 0
+let watermark = 0n
 
 const subscriber = new AlgorandSubscriber(
   {
@@ -155,8 +177,8 @@ const subscriber = new AlgorandSubscriber(
         eventName: 'usdc',
         filter: {
           type: TransactionType.axfer,
-          assetId: 31566704, // MainNet: USDC
-          minAmount: 1_000_000, // $1
+          assetId: 31566704n, // MainNet: USDC
+          minAmount: 1_000_000n, // $1
         },
       },
     ],
@@ -174,8 +196,8 @@ const subscriber = new AlgorandSubscriber(
 subscriber.on('usdc', (transfer) => {
   // eslint-disable-next-line no-console
   console.log(
-    `${transfer.sender} sent ${transfer['asset-transfer-transaction']?.receiver} USDC$${(
-      (transfer['asset-transfer-transaction']?.amount ?? 0) / 1_000_000
+    `${transfer.sender} sent ${transfer.assetTransferTransaction?.receiver} USDC$${Number(
+      (transfer.assetTransferTransaction?.amount ?? 0n) / 1_000_000n,
     ).toFixed(2)} in transaction ${transfer.id}`,
   )
 })

docs/README.md

@@ -113,11 +113,11 @@ You can create reliable syncing / indexing services through a simple round water
 This works through the use of the `watermarkPersistence` parameter in [`AlgorandSubscriber`](./subscriber.md) and `watermark` parameter in [`getSubscribedTransactions`](./subscriptions.md):
 
 ```typescript
-async function getSavedWatermark(): Promise<number> {
+async function getSavedWatermark(): Promise<bigint> {
   // Return the watermark from a persistence store e.g. database, redis, file system, etc.
 }
 
-async function saveWatermark(newWatermark: number): Promise<void> {
+async function saveWatermark(newWatermark: bigint): Promise<void> {
   // Save the watermark to a persistence store e.g. database, redis, file system, etc.
 }
 
@@ -143,7 +143,7 @@ If you are doing a quick test or creating an ephemeral subscriber that just need
 ```typescript
 let watermark = 0
 const subscriber = new AlgorandSubscriber({watermarkPersistence: {
-  get: () => watermark, set: (newWatermark: number) => watermark = newWatermark
+  get: () => watermark, set: (newWatermark: bigint) => watermark = newWatermark
 }, ...}, ...)
 
 // or:
@@ -194,10 +194,10 @@ Currently this allows you filter based on any combination (AND logic) of:
     Note: For this to work you need to [specify ARC-28 events in the subscription config](#arc-28-event-subscription-and-reads).
 
 - Assets
-  - ID e.g. `filter: { assetId: 123456 }` or `filter: { assetId: [123456, 456789] }`
+  - ID e.g. `filter: { assetId: 123456n }` or `filter: { assetId: [123456n, 456789n] }`
   - Creation e.g. `filter: { assetCreate: true }`
   - Amount transferred (min and/or max) e.g. `filter: { type: TransactionType.axfer, minAmount: 1, maxAmount: 100 }`
-  - Balance changes (asset ID, sender, receiver, close to, min and/or max change) e.g. `filter: { balanceChanges: [{assetId: [15345, 36234], roles: [BalanceChangeRole.sender], address: "ABC...", minAmount: 1, maxAmount: 2}]}`
+  - Balance changes (asset ID, sender, receiver, close to, min and/or max change) e.g. `filter: { balanceChanges: [{assetId: [15345n, 36234n], roles: [BalanceChangeRole.sender], address: "ABC...", minAmount: 1, maxAmount: 2}]}`
 - Algo transfers (pay transactions)
   - Amount transferred (min and/or max) e.g. `filter: { type: TransactionType.pay, minAmount: 1, maxAmount: 100 }`
   - Balance changes (sender, receiver, close to, min and/or max change) e.g. `filter: { balanceChanges: [{roles: [BalanceChangeRole.sender], address: "ABC...", minAmount: 1, maxAmount: 2}]}`
@@ -243,7 +243,7 @@ export interface Arc28EventGroup {
   /** The name to designate for this group of events. */
   groupName: string
   /** Optional list of app IDs that this event should apply to */
-  processForAppIds?: number[]
+  processForAppIds?: bigint[]
   /** Optional predicate to indicate if these ARC-28 events should be processed for the given transaction */
   processTransaction?: (transaction: TransactionResult) => boolean
   /** Whether or not to silently (with warning log) continue if an error is encountered processing the ARC-28 event data; default = false */

docs/code/classes/index.AlgorandSubscriber.md

@@ -49,16 +49,16 @@ Create a new `AlgorandSubscriber`.
 | Name | Type | Description |
 | :------ | :------ | :------ |
 | `config` | [`AlgorandSubscriberConfig`](../interfaces/types_subscription.AlgorandSubscriberConfig.md) | The subscriber configuration |
-| `algod` | `default` | An algod client |
-| `indexer?` | `default` | An (optional) indexer client; only needed if `subscription.syncBehaviour` is `catchup-with-indexer` |
+| `algod` | `AlgodClient` | An algod client |
+| `indexer?` | `IndexerClient` | An (optional) indexer client; only needed if `subscription.syncBehaviour` is `catchup-with-indexer` |
 
 #### Returns
 
 [`AlgorandSubscriber`](index.AlgorandSubscriber.md)
 
 #### Defined in
 
-[subscriber.ts:41](https://github.com/algorandfoundation/algokit-subscriber-ts/blob/main/src/subscriber.ts#L41)
+[src/subscriber.ts:41](https://github.com/algorandfoundation/algokit-subscriber-ts/blob/main/src/subscriber.ts#L41)
 
 ## Properties
 
@@ -68,17 +68,17 @@ Create a new `AlgorandSubscriber`.
 
 #### Defined in
 
-[subscriber.ts:24](https://github.com/algorandfoundation/algokit-subscriber-ts/blob/main/src/subscriber.ts#L24)
+[src/subscriber.ts:24](https://github.com/algorandfoundation/algokit-subscriber-ts/blob/main/src/subscriber.ts#L24)
 
 ___
 
 ### algod
 
-• `Private` **algod**: `default`
+• `Private` **algod**: `AlgodClient`
 
 #### Defined in
 
-[subscriber.ts:21](https://github.com/algorandfoundation/algokit-subscriber-ts/blob/main/src/subscriber.ts#L21)
+[src/subscriber.ts:21](https://github.com/algorandfoundation/algokit-subscriber-ts/blob/main/src/subscriber.ts#L21)
 
 ___
 
@@ -88,7 +88,7 @@ ___
 
 #### Defined in
 
-[subscriber.ts:23](https://github.com/algorandfoundation/algokit-subscriber-ts/blob/main/src/subscriber.ts#L23)
+[src/subscriber.ts:23](https://github.com/algorandfoundation/algokit-subscriber-ts/blob/main/src/subscriber.ts#L23)
 
 ___
 
@@ -98,7 +98,7 @@ ___
 
 #### Defined in
 
-[subscriber.ts:30](https://github.com/algorandfoundation/algokit-subscriber-ts/blob/main/src/subscriber.ts#L30)
+[src/subscriber.ts:30](https://github.com/algorandfoundation/algokit-subscriber-ts/blob/main/src/subscriber.ts#L30)
 
 ___
 
@@ -108,7 +108,7 @@ ___
 
 #### Defined in
 
-[subscriber.ts:25](https://github.com/algorandfoundation/algokit-subscriber-ts/blob/main/src/subscriber.ts#L25)
+[src/subscriber.ts:25](https://github.com/algorandfoundation/algokit-subscriber-ts/blob/main/src/subscriber.ts#L25)
 
 ___
 
@@ -118,17 +118,17 @@ ___
 
 #### Defined in
 
-[subscriber.ts:28](https://github.com/algorandfoundation/algokit-subscriber-ts/blob/main/src/subscriber.ts#L28)
+[src/subscriber.ts:28](https://github.com/algorandfoundation/algokit-subscriber-ts/blob/main/src/subscriber.ts#L28)
 
 ___
 
 ### indexer
 
-• `Private` **indexer**: `undefined` \| `default`
+• `Private` **indexer**: `undefined` \| `IndexerClient`
 
 #### Defined in
 
-[subscriber.ts:22](https://github.com/algorandfoundation/algokit-subscriber-ts/blob/main/src/subscriber.ts#L22)
+[src/subscriber.ts:22](https://github.com/algorandfoundation/algokit-subscriber-ts/blob/main/src/subscriber.ts#L22)
 
 ___
 
@@ -138,7 +138,7 @@ ___
 
 #### Defined in
 
-[subscriber.ts:27](https://github.com/algorandfoundation/algokit-subscriber-ts/blob/main/src/subscriber.ts#L27)
+[src/subscriber.ts:27](https://github.com/algorandfoundation/algokit-subscriber-ts/blob/main/src/subscriber.ts#L27)
 
 ___
 
@@ -148,7 +148,7 @@ ___
 
 #### Defined in
 
-[subscriber.ts:26](https://github.com/algorandfoundation/algokit-subscriber-ts/blob/main/src/subscriber.ts#L26)
+[src/subscriber.ts:26](https://github.com/algorandfoundation/algokit-subscriber-ts/blob/main/src/subscriber.ts#L26)
 
 ## Methods
 
@@ -168,7 +168,7 @@ ___
 
 #### Defined in
 
-[subscriber.ts:31](https://github.com/algorandfoundation/algokit-subscriber-ts/blob/main/src/subscriber.ts#L31)
+[src/subscriber.ts:31](https://github.com/algorandfoundation/algokit-subscriber-ts/blob/main/src/subscriber.ts#L31)
 
 ___
 
@@ -184,7 +184,7 @@ The listener can be async and it will be awaited if so.
 
 | Name | Type |
 | :------ | :------ |
-| `T` | [`SubscribedTransaction`](../modules/types_subscription.md#subscribedtransaction) |
+| `T` | [`SubscribedTransaction`](types_subscription.SubscribedTransaction.md) |
 
 #### Parameters
 
@@ -214,7 +214,7 @@ new AlgorandSubscriber({filters: [{name: 'my-filter', filter: {...}, mapper: (t)
 
 #### Defined in
 
-[subscriber.ts:191](https://github.com/algorandfoundation/algokit-subscriber-ts/blob/main/src/subscriber.ts#L191)
+[src/subscriber.ts:191](https://github.com/algorandfoundation/algokit-subscriber-ts/blob/main/src/subscriber.ts#L191)
 
 ___
 
@@ -234,7 +234,7 @@ The listener can be async and it will be awaited if so.
 
 | Name | Type |
 | :------ | :------ |
-| `T` | [`SubscribedTransaction`](../modules/types_subscription.md#subscribedtransaction) |
+| `T` | [`SubscribedTransaction`](types_subscription.SubscribedTransaction.md) |
 
 #### Parameters
 
@@ -264,7 +264,7 @@ new AlgorandSubscriber({filters: [{name: 'my-filter', filter: {...}, mapper: (t)
 
 #### Defined in
 
-[subscriber.ts:220](https://github.com/algorandfoundation/algokit-subscriber-ts/blob/main/src/subscriber.ts#L220)
+[src/subscriber.ts:220](https://github.com/algorandfoundation/algokit-subscriber-ts/blob/main/src/subscriber.ts#L220)
 
 ___
 
@@ -298,7 +298,7 @@ subscriber.onBeforePoll(async (metadata) => { console.log(metadata.watermark) })
 
 #### Defined in
 
-[subscriber.ts:238](https://github.com/algorandfoundation/algokit-subscriber-ts/blob/main/src/subscriber.ts#L238)
+[src/subscriber.ts:238](https://github.com/algorandfoundation/algokit-subscriber-ts/blob/main/src/subscriber.ts#L238)
 
 ___
 
@@ -349,7 +349,7 @@ subscriber.onError(async (error) => {
 
 #### Defined in
 
-[subscriber.ts:292](https://github.com/algorandfoundation/algokit-subscriber-ts/blob/main/src/subscriber.ts#L292)
+[src/subscriber.ts:292](https://github.com/algorandfoundation/algokit-subscriber-ts/blob/main/src/subscriber.ts#L292)
 
 ___
 
@@ -386,7 +386,7 @@ subscriber.onPoll(async (pollResult) => { console.log(pollResult.subscribedTrans
 
 #### Defined in
 
-[subscriber.ts:259](https://github.com/algorandfoundation/algokit-subscriber-ts/blob/main/src/subscriber.ts#L259)
+[src/subscriber.ts:259](https://github.com/algorandfoundation/algokit-subscriber-ts/blob/main/src/subscriber.ts#L259)
 
 ___
 
@@ -407,7 +407,7 @@ The poll result
 
 #### Defined in
 
-[subscriber.ts:67](https://github.com/algorandfoundation/algokit-subscriber-ts/blob/main/src/subscriber.ts#L67)
+[src/subscriber.ts:67](https://github.com/algorandfoundation/algokit-subscriber-ts/blob/main/src/subscriber.ts#L67)
 
 ___
 
@@ -434,7 +434,7 @@ An object that contains a promise you can wait for after calling stop
 
 #### Defined in
 
-[subscriber.ts:113](https://github.com/algorandfoundation/algokit-subscriber-ts/blob/main/src/subscriber.ts#L113)
+[src/subscriber.ts:113](https://github.com/algorandfoundation/algokit-subscriber-ts/blob/main/src/subscriber.ts#L113)
 
 ___
 
@@ -458,4 +458,4 @@ A promise that can be awaited to ensure the subscriber has finished stopping
 
 #### Defined in
 
-[subscriber.ts:164](https://github.com/algorandfoundation/algokit-subscriber-ts/blob/main/src/subscriber.ts#L164)
+[src/subscriber.ts:164](https://github.com/algorandfoundation/algokit-subscriber-ts/blob/main/src/subscriber.ts#L164)