From 8a95d391ae9ab7a8880fec3a1f479deec46d2aec Mon Sep 17 00:00:00 2001 From: Lucas Tortora <85233773+lucas-tortora@users.noreply.github.com> Date: Fri, 1 Sep 2023 15:31:51 -0300 Subject: [PATCH] Re-add listen to events how-to to SDK --- .../_warning-unlock-conditions.md | 3 +- .../list-transactions.mdx | 2 +- .../listen-to-events.mdx | 189 ++++++++++++++++++ docs/build/iota-sdk/1.0.0/sidebars.js | 1 + 4 files changed, 192 insertions(+), 3 deletions(-) create mode 100644 docs/build/iota-sdk/1.0.0/docs/how-tos/accounts-and-addresses/listen-to-events.mdx diff --git a/docs/build/iota-sdk/1.0.0/docs/_admonitions/_warning-unlock-conditions.md b/docs/build/iota-sdk/1.0.0/docs/_admonitions/_warning-unlock-conditions.md index e6dc4436869..98b6c8acde7 100644 --- a/docs/build/iota-sdk/1.0.0/docs/_admonitions/_warning-unlock-conditions.md +++ b/docs/build/iota-sdk/1.0.0/docs/_admonitions/_warning-unlock-conditions.md @@ -1,7 +1,6 @@ :::warning Unlock Conditions -Outputs may have multiple [UnlockConditions](https://wiki.iota.org/shimmer/tips/tips/TIP-0018/#unlock-conditions), which may require [returning some or all of the transferred amount](https://wiki.iota.org/shimmer/tips/tips/TIP-0018/#storage-deposit-return-unlock-condition). The outputs could also [expire if not claimed in time](https://wiki.iota.org/shimmer/tips/tips/TIP-0018/#expiration-unlock-condition), or may not be [unlockable for a predefined period](https://wiki.iota.org/shimmer/tips/tips/TIP-0018/#timelock-unlock-condition). - +Outputs may have multiple [UnlockConditions](https://wiki.iota.org/shimmer/tips/tips/TIP-0018/#unlock-conditions), which may require [returning some or all of the transferred amount](https://wiki.iota.org/shimmer/tips/tips/TIP-0018/#storage-deposit-return-unlock-condition). The outputs could also [expire if not claimed in time](https://wiki.iota.org/shimmer/tips/tips/TIP-0018/#expiration-unlock-condition) or may not be [unlockable for a predefined period](https://wiki.iota.org/shimmer/tips/tips/TIP-0018/#timelock-unlock-condition). To get outputs with only the [`AddressUnlockCondition`](https://wiki.iota.org/shimmer/tips/tips/TIP-0018/#address-unlock-condition), you should synchronize with the option `syncOnlyMostBasicOutputs: true`. If you are synchronizing outputs with other unlock conditions, you should check the unlock conditions carefully before crediting users any balance. diff --git a/docs/build/iota-sdk/1.0.0/docs/how-tos/accounts-and-addresses/list-transactions.mdx b/docs/build/iota-sdk/1.0.0/docs/how-tos/accounts-and-addresses/list-transactions.mdx index 34cd154983f..e46d6459a26 100644 --- a/docs/build/iota-sdk/1.0.0/docs/how-tos/accounts-and-addresses/list-transactions.mdx +++ b/docs/build/iota-sdk/1.0.0/docs/how-tos/accounts-and-addresses/list-transactions.mdx @@ -22,7 +22,7 @@ This guide will show you how to list all the transactions of all the addresses o :::tip Sync Options -If you want to list incoming transactions you need to specify that in your `sync` call. +If you want to list incoming transactions, you need to specify that in your `sync` call. Transactions for outputs that you synced before with other sync options, will not be requested later. Also, only transactions that weren't pruned on the point of syncing will be listed. diff --git a/docs/build/iota-sdk/1.0.0/docs/how-tos/accounts-and-addresses/listen-to-events.mdx b/docs/build/iota-sdk/1.0.0/docs/how-tos/accounts-and-addresses/listen-to-events.mdx new file mode 100644 index 00000000000..2c001971b0e --- /dev/null +++ b/docs/build/iota-sdk/1.0.0/docs/how-tos/accounts-and-addresses/listen-to-events.mdx @@ -0,0 +1,189 @@ +--- +title: Listen To Events +description: 'How to listen to events using the IOTA SDK.' +image: /img/logo/iota_mark_light.png +keywords: + - how to + - listen + - events + - listen to events + - get outputs + - get transactions + - nodejs + - python + - rust +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import WarningUnlockConditions from '../../_admonitions/_warning-unlock-conditions.md'; + +Listening to events in an application is essential for real-time data updates and a seamless user experience. By +subscribing to events, such as transfers, deposits, or withdrawals, you can trigger a callback as soon as the event occurs. + + + +## Example Code + + + + +1. Instantiate a [`Wallet`](https://docs.rs/iota-sdk/latest/iota_sdk/wallet/core/struct.Wallet.html). + +
+ +```rust reference +https://github.com/iotaledger/iota-sdk/blob/develop/sdk/examples/wallet/events.rs#L38-L44 +``` + +
+ +2. Use the `Wallet` instance to listen to events with the + [`Wallet.listen()`](https://docs.rs/iota-sdk/latest/iota_sdk/wallet/core/struct.WalletInner.html#method.listen) function. + You can listen for a specific + [`WalletEventType`](https://docs.rs/iota-sdk/latest/iota_sdk/wallet/events/types/enum.WalletEventType.html). + +
+ +```rust reference +https://github.com/iotaledger/iota-sdk/blob/develop/sdk/examples/wallet/events.rs#L46-L50 +``` + +
+ +
+ + +1. Instantiate a [`Wallet`](../../references/nodejs/classes/Wallet.md). + +
+ +```typescript reference +https://github.com/iotaledger/iota-sdk/blob/develop/bindings/nodejs/examples/exchange/4-listen-events.ts#L21-L23 +``` + +
+ +2. Define a callback. + +
+ +```typescript reference +https://github.com/iotaledger/iota-sdk/blob/develop/bindings/nodejs/examples/exchange/4-listen-events.ts#L25-L31 +``` + +
+ +3. Use the `Wallet` instance to listen to events with the + [`Wallet.listen()`](../../references/nodejs/classes/Wallet.md#listen) function. You can listen for a specific + [`WalletEventType`](../../references/nodejs/enums/WalletEventType.md), in this case, + [`WalletEventType.NewOutput`](../../references/nodejs/enums/WalletEventType.md#newoutput). + +
+ +```typescript reference +https://github.com/iotaledger/iota-sdk/blob/develop/bindings/nodejs/examples/exchange/4-listen-events.ts#L34 +``` + +
+ +
+ + +1. Instantiate a [`wallet`](../../references/python/iota_sdk/wallet/wallet.md). + +
+ +```python reference +https://github.com/iotaledger/iota-sdk/blob/develop/bindings/python/examples/exchange/4_listen_events.py#L19 +``` + +
+ +2. Define a callback. + +
+ +```python reference +https://github.com/iotaledger/iota-sdk/blob/develop/bindings/python/examples/exchange/4_listen_events.py#L26-L33 +``` + +
+ +3. Use the `wallet` instance to listen to events with the + [`wallet.listen()`](../../references/python/iota_sdk/wallet/wallet.md#listen) function. You can listen for a specific + [`WalletEventType`](../../references/python/iota_sdk/types/event.md), in this case, `WalletEventType.NewOutput`. + +
+ +```python reference +https://github.com/iotaledger/iota-sdk/blob/develop/bindings/python/examples/exchange/4_listen_events.py#L37 +``` + +
+ +
+ +
+ +### Full Example Code + + + + +```rust reference +https://github.com/iotaledger/iota-sdk/blob/develop/sdk/examples/wallet/events.rs +``` + + + + +```typescript reference +https://github.com/iotaledger/iota-sdk/blob/develop/bindings/nodejs/examples/exchange/4-listen-events.ts +``` + + + + +```python reference +https://github.com/iotaledger/iota-sdk/blob/develop/bindings/python/examples/exchange/4_listen_events.py +``` + + + + + +### Expected Output + +```js +AccountIndex: 0 +Event: { + type: 2, + output: { + outputId: '0x581f43218322d742c0ba1f0d738d6afbc9beaaf4c47f439ab048766b25843f920100', + metadata: { + blockId: '0x7fdf4079802bd00d022cc382a422491724af6564d31522b7f34133d119b7979d', + transactionId: '0x581f43218322d742c0ba1f0d738d6afbc9beaaf4c47f439ab048766b25843f92', + outputIndex: 1, + isSpent: false, + milestoneIndexBooked: 6316391, + milestoneTimestampBooked: 1690125643, + ledgerIndex: 6450179 + }, + output: { + type: 3, + amount: '3043981300', + nativeTokens: [Array], + unlockConditions: [Array] + }, + isSpent: false, + address: { + type: 0, + pubKeyHash: '0x194eb32b9b6c61207192c7073562a0b3adf50a7c1f268182b552ec8999380acb' + }, + networkId: '1856588631910923207', + remainder: false, + chain: { coinType: 4218, account: 0, change: 0, addressIndex: 0 } + } +} +``` diff --git a/docs/build/iota-sdk/1.0.0/sidebars.js b/docs/build/iota-sdk/1.0.0/sidebars.js index 8353125353d..a5a11822263 100644 --- a/docs/build/iota-sdk/1.0.0/sidebars.js +++ b/docs/build/iota-sdk/1.0.0/sidebars.js @@ -142,6 +142,7 @@ module.exports = { 'how-tos/accounts-and-addresses/list-transactions', 'how-tos/accounts-and-addresses/list-outputs', 'how-tos/accounts-and-addresses/consolidate-outputs', + 'how-tos/accounts-and-addresses/listen-to-events', ], }, {