Merge pull request #22 from algorandfoundation/arc-28

feat: ARC-28 support

.vscode/settings.json

@@ -6,10 +6,10 @@
     "source.organizeImports": true
   },
   "jest.jestCommandLine": "npm run test --",
-  "jest.autoRun": {
-    "watch": false,
-    "onSave": "test-file",
-    "onStartup": false
+  "jest.runMode": {
+    "runAllTestsOnStartup": false,
+    "showInlineError": true,
+    "type": "on-demand"
   },
   "jest.outputConfig": { "revealWithFocus": "none" },
   "testing.openTesting": "neverOpen",

README.md

@@ -35,8 +35,8 @@ subscriber.pollOnce()
 
 - **Notification _and_ indexing** - You have fine-grained control over the syncing behaviour and can control the number of rounds to sync at a time, the pattern of syncing i.e. start from the beginning of the chain, or start from the tip; drop stale records if your service can't keep up or keep syncing from where you are up to; etc.
 - **Low latency processing** - When your service has caught up to the tip of the chain it can optionally wait for new rounds so you have a low latency reaction to a new round occurring
-- **Extensive subscription filtering** - You can filter by transaction type, sender, receiver, note prefix, apps (ID, creation, on complete, ARC-4 method signature, call arguments, ARC-28 events), assets (ID, creation, amount transferred range), transfers (amount transferred range)
 - **Watermarking and resilience** - You can create reliable syncing / indexing services through a simple round watermarking capability that allows you to create resilient syncing services that can recover from an outage
+- **Extensive subscription filtering** - You can filter by transaction type, sender, receiver, note prefix, apps (ID, creation, on complete, ARC-4 method signature, call arguments, ARC-28 events), assets (ID, creation, amount transferred range), transfers (amount transferred range)
 - **ARC-28 event subscription support** - You can subscribe to ARC-28 events for a smart contract, similar to how you can [subscribe to events in Ethereum](https://docs.web3js.org/guides/events_subscriptions/)
 - **First-class inner transaction support** - Your filter will find arbitrarily nested inner transactions and return that transaction (indexer can't do this!)
 - **State-proof support** - You can subscribe to state proof transactions

docs/code/classes/index.AlgorandSubscriber.md

@@ -155,7 +155,7 @@ The subscriber so `on`/`onBatch` calls can be chained
 
 #### Defined in
 
-[subscriber.ts:149](https://github.com/algorandfoundation/algokit-subscriber-ts/blob/main/src/subscriber.ts#L149)
+[subscriber.ts:150](https://github.com/algorandfoundation/algokit-subscriber-ts/blob/main/src/subscriber.ts#L150)
 
 ___
 
@@ -192,7 +192,7 @@ The subscriber so `on`/`onBatch` calls can be chained
 
 #### Defined in
 
-[subscriber.ts:166](https://github.com/algorandfoundation/algokit-subscriber-ts/blob/main/src/subscriber.ts#L166)
+[subscriber.ts:167](https://github.com/algorandfoundation/algokit-subscriber-ts/blob/main/src/subscriber.ts#L167)
 
 ___
 
@@ -240,7 +240,7 @@ An object that contains a promise you can wait for after calling stop
 
 #### Defined in
 
-[subscriber.ts:92](https://github.com/algorandfoundation/algokit-subscriber-ts/blob/main/src/subscriber.ts#L92)
+[subscriber.ts:93](https://github.com/algorandfoundation/algokit-subscriber-ts/blob/main/src/subscriber.ts#L93)
 
 ___
 
@@ -264,4 +264,4 @@ A promise that can be awaited to ensure the subscriber has finished stopping
 
 #### Defined in
 
-[subscriber.ts:135](https://github.com/algorandfoundation/algokit-subscriber-ts/blob/main/src/subscriber.ts#L135)
+[subscriber.ts:136](https://github.com/algorandfoundation/algokit-subscriber-ts/blob/main/src/subscriber.ts#L136)

docs/code/interfaces/types_subscription.Arc28Event.md

@@ -0,0 +1,51 @@
+[@algorandfoundation/algokit-subscriber](../README.md) / [types/subscription](../modules/types_subscription.md) / Arc28Event
+
+# Interface: Arc28Event
+
+[types/subscription](../modules/types_subscription.md).Arc28Event
+
+The definition of metadata for an ARC-28 event per https://github.com/algorandfoundation/ARCs/blob/main/ARCs/arc-0028.md#event.
+
+## Table of contents
+
+### Properties
+
+- [args](types_subscription.Arc28Event.md#args)
+- [desc](types_subscription.Arc28Event.md#desc)
+- [name](types_subscription.Arc28Event.md#name)
+
+## Properties
+
+### args
+
+• **args**: \{ `desc?`: `string` ; `name?`: `string` ; `type`: `string`  }[]
+
+The arguments of the event, in order
+
+#### Defined in
+
+[types/subscription.ts:13](https://github.com/algorandfoundation/algokit-subscriber-ts/blob/main/src/types/subscription.ts#L13)
+
+___
+
+### desc
+
+• `Optional` **desc**: `string`
+
+Optional, user-friendly description for the event
+
+#### Defined in
+
+[types/subscription.ts:11](https://github.com/algorandfoundation/algokit-subscriber-ts/blob/main/src/types/subscription.ts#L11)
+
+___
+
+### name
+
+• **name**: `string`
+
+The name of the event
+
+#### Defined in
+
+[types/subscription.ts:9](https://github.com/algorandfoundation/algokit-subscriber-ts/blob/main/src/types/subscription.ts#L9)

docs/code/interfaces/types_subscription.Arc28EventGroup.md

@@ -0,0 +1,91 @@
+[@algorandfoundation/algokit-subscriber](../README.md) / [types/subscription](../modules/types_subscription.md) / Arc28EventGroup
+
+# Interface: Arc28EventGroup
+
+[types/subscription](../modules/types_subscription.md).Arc28EventGroup
+
+Specifies a group of ARC-28 event definitions along with instructions for when to attempt to process the events.
+
+## Table of contents
+
+### Properties
+
+- [continueOnError](types_subscription.Arc28EventGroup.md#continueonerror)
+- [events](types_subscription.Arc28EventGroup.md#events)
+- [groupName](types_subscription.Arc28EventGroup.md#groupname)
+- [processForAppIds](types_subscription.Arc28EventGroup.md#processforappids)
+- [processTransaction](types_subscription.Arc28EventGroup.md#processtransaction)
+
+## Properties
+
+### continueOnError
+
+• `Optional` **continueOnError**: `boolean`
+
+Whether or not to silently (with warning log) continue if an error is encountered processing the ARC-28 event data; default = false
+
+#### Defined in
+
+[types/subscription.ts:54](https://github.com/algorandfoundation/algokit-subscriber-ts/blob/main/src/types/subscription.ts#L54)
+
+___
+
+### events
+
+• **events**: [`Arc28Event`](types_subscription.Arc28Event.md)[]
+
+The list of ARC-28 event definitions
+
+#### Defined in
+
+[types/subscription.ts:56](https://github.com/algorandfoundation/algokit-subscriber-ts/blob/main/src/types/subscription.ts#L56)
+
+___
+
+### groupName
+
+• **groupName**: `string`
+
+The name to designate for this group of events.
+
+#### Defined in
+
+[types/subscription.ts:48](https://github.com/algorandfoundation/algokit-subscriber-ts/blob/main/src/types/subscription.ts#L48)
+
+___
+
+### processForAppIds
+
+• `Optional` **processForAppIds**: `number`[]
+
+Optional list of app IDs that this event should apply to
+
+#### Defined in
+
+[types/subscription.ts:50](https://github.com/algorandfoundation/algokit-subscriber-ts/blob/main/src/types/subscription.ts#L50)
+
+___
+
+### processTransaction
+
+• `Optional` **processTransaction**: (`transaction`: `TransactionResult`) => `boolean`
+
+#### Type declaration
+
+▸ (`transaction`): `boolean`
+
+Optional predicate to indicate if these ARC-28 events should be processed for the given transaction
+
+##### Parameters
+
+| Name | Type |
+| :------ | :------ |
+| `transaction` | `TransactionResult` |
+
+##### Returns
+
+`boolean`
+
+#### Defined in
+
+[types/subscription.ts:52](https://github.com/algorandfoundation/algokit-subscriber-ts/blob/main/src/types/subscription.ts#L52)

docs/code/interfaces/types_subscription.Arc28EventToProcess.md

@@ -0,0 +1,83 @@
+[@algorandfoundation/algokit-subscriber](../README.md) / [types/subscription](../modules/types_subscription.md) / Arc28EventToProcess
+
+# Interface: Arc28EventToProcess
+
+[types/subscription](../modules/types_subscription.md).Arc28EventToProcess
+
+An ARC-28 event to be processed
+
+## Hierarchy
+
+- **`Arc28EventToProcess`**
+
+  ↳ [`EmittedArc28Event`](types_subscription.EmittedArc28Event.md)
+
+## Table of contents
+
+### Properties
+
+- [eventDefinition](types_subscription.Arc28EventToProcess.md#eventdefinition)
+- [eventName](types_subscription.Arc28EventToProcess.md#eventname)
+- [eventPrefix](types_subscription.Arc28EventToProcess.md#eventprefix)
+- [eventSignature](types_subscription.Arc28EventToProcess.md#eventsignature)
+- [groupName](types_subscription.Arc28EventToProcess.md#groupname)
+
+## Properties
+
+### eventDefinition
+
+• **eventDefinition**: [`Arc28Event`](types_subscription.Arc28Event.md)
+
+The ARC-28 definition of the event
+
+#### Defined in
+
+[types/subscription.ts:34](https://github.com/algorandfoundation/algokit-subscriber-ts/blob/main/src/types/subscription.ts#L34)
+
+___
+
+### eventName
+
+• **eventName**: `string`
+
+The name of the ARC-28 event that was triggered
+
+#### Defined in
+
+[types/subscription.ts:28](https://github.com/algorandfoundation/algokit-subscriber-ts/blob/main/src/types/subscription.ts#L28)
+
+___
+
+### eventPrefix
+
+• **eventPrefix**: `string`
+
+The 4-byte hex prefix for the event
+
+#### Defined in
+
+[types/subscription.ts:32](https://github.com/algorandfoundation/algokit-subscriber-ts/blob/main/src/types/subscription.ts#L32)
+
+___
+
+### eventSignature
+
+• **eventSignature**: `string`
+
+The signature of the event e.g. `EventName(type1,type2)`
+
+#### Defined in
+
+[types/subscription.ts:30](https://github.com/algorandfoundation/algokit-subscriber-ts/blob/main/src/types/subscription.ts#L30)
+
+___
+
+### groupName
+
+• **groupName**: `string`
+
+The name of the ARC-28 event group the event belongs to
+
+#### Defined in
+
+[types/subscription.ts:26](https://github.com/algorandfoundation/algokit-subscriber-ts/blob/main/src/types/subscription.ts#L26)