From 39f229ce3cda6c10536a62194095ae97e000ccd9 Mon Sep 17 00:00:00 2001 From: Jordan Ribbink Date: Mon, 31 Mar 2025 12:06:18 -0700 Subject: [PATCH 01/16] First pass of docs --- docs/tools/clients/fcl-js/api.md | 251 +++++++++++++++++++++++++++++-- 1 file changed, 241 insertions(+), 10 deletions(-) diff --git a/docs/tools/clients/fcl-js/api.md b/docs/tools/clients/fcl-js/api.md index 40f8e5b7e1..02a47dfcb0 100644 --- a/docs/tools/clients/fcl-js/api.md +++ b/docs/tools/clients/fcl-js/api.md @@ -1513,12 +1513,123 @@ const latestBlock = await fcl.latestBlock(); --- -## Transaction Status Utility +## Real-time Data + +Streaming data is available through the WebSocket Streaming API provided by the HTTP Access API. It allows developers to subscribe to specific topics and receive real-time updates as they occur on the Flow blockchain. + +The following topics are available for subscription: + +- `events` +- `blocks` +- `block_headers` +- `block_digests` +- `transaction_statuses` +- `account_statuses` + +### `subscribe` + +A utility function used for subscribing to real-time data from the WebSocket Streaming API. Data returned will be automatically decoded via `fcl.decode`. + +#### Arguments + +| Name | Type | Description | +| -------------------- | ------------------ | -------------------------------------------------------------------------------------------------- | +| [`SubscriptionParams`] | SubscriptionParams | An object containing the subscription topic, arguments, and callbacks. See below for more details. | +| `opts` | object | _(Optional)_ Additional options for the subscription. See below for more details. | + +SubscriptionParams (first parameter): + +| Name | Type | Description | +| --------- | ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | +| `topic` | SubscriptionTopic | The subscription topic. Valid values include: `events`, `blocks`, `transactions`, and `collections`. | +| `args` | SubscriptionArgs | An array or object of parameters specific to the topic. For example, when subscribing to events, these might be event identifiers. | +| `onData` | (data: SubscriptionData) | A callback function that is called with the decoded data whenever a new message is received. | +| `onError` | (error: Error) => void | A callback function that is called if an error occurs during the subscription. | + +Additional Options (second parameter): + +| Name | Type | Description | +| ----------- | ------ | ------------------------------------------------------------------------- | +| `node` | string | _(Optional)_ Custom node endpoint to be used for the subscription. | +| `transport` | object | _(Optional)_ Custom transport implementation for handling the connection. | + +#### Returns + +| Type | Description | +| ------------------------------------------------------ | ---------------------------------------------------------------------------------------------- | +| [SdkTransport.Subscription](#sdktransportsubscription) | A subscription object that allows you to manage the subscription (e.g., to unsubscribe later). | + +#### Usage + +```javascript +import * as fcl from '@onflow/fcl'; +import { SubscriptionTopic } from '@onflow/sdk'; + +const subscription = fcl.subscribe({ + topic: SubscriptionTopic.EVENTS, + args: { + type: 'A.7e60df042a9c0868.FlowToken.TokensWithdrawn', + }, + onData: (data) => console.log('Received event data:', data), + onError: (error) => console.error('Subscription error:', error), +}); + +// Later, to unsubscribe: +subscription.unsubscribe(); +``` + +--- + +### `subscribeRaw` + +A utility function used for subscribing to raw data from the WebSocket Streaming API. Data returned will not be decoded via `fcl.decode` and developers are responsible for handling the raw data returned. + +#### Arguments + +| Name | Type | Description | +| --------- | -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | +| `topic` | SubscriptionTopic | The subscription topic. Valid values include: `events`, `blocks`, `transactions`, and `collections`. | +| `args` | RawSubscriptionArgs | An array or object of parameters specific to the topic. For example, when subscribing to events, these might be event identifiers. | +| `onData` | (data: RawSubscriptionData) | A callback function that is called with the decoded data whenever a new message is received. | +| `onError` | (error: Error) => void | A callback function that is called if an error occurs during the subscription. | + +Additional Options (second parameter): + +| Name | Type | Description | +| ----------- | ------ | ------------------------------------------------------------------------- | +| `node` | string | _(Optional)_ Custom node endpoint to be used for the subscription. | +| `transport` | object | _(Optional)_ Custom transport implementation for handling the connection. | + +#### Returns + +| Type | Description | +| ------------------------------------------------------ | ---------------------------------------------------------------------------------------------- | +| [SdkTransport.Subscription](#sdktransportsubscription) | A subscription object that allows you to manage the subscription (e.g., to unsubscribe later). | + +#### Usage + +```javascript +import * as fcl from '@onflow/fcl'; +import { SubscriptionTopic } from '@onflow/sdk'; + +const subscription = fcl.subscribeRaw({ + topic: SubscriptionTopic.EVENTS, + args: { + type: 'A.7e60df042a9c0868.FlowToken.TokensWithdrawn', + }, + onData: (data) => console.log('Received event data:', data), + onError: (error) => console.error('Subscription error:', error), +}); + +// Later, to unsubscribe: +subscription.unsubscribe(); +``` + +--- ### `tx` -A utility function that lets you set the transaction to get subsequent status updates (via polling) and the finalized result once available. -⚠️The poll rate is set at `2500ms` and will update at that interval until transaction is sealed. +A utility function that lets you set the transaction to get subsequent status updates and the finalized result once available. #### Arguments @@ -1547,15 +1658,9 @@ useEffect(() => fcl.tx(txId).subscribe(setTxStatus)); --- -## Event Polling Utility - ### `events` -A utility function that lets you set the transaction to get subsequent status updates (via polling) and the finalized result once available. -⚠️The poll rate is set at `10000ms` and will update at that interval for getting new events. - -Note: -⚠️`fcl.eventPollRate` value **could** be set to change the polling rate of all events subcribers, check [FCL Configuration](#configuration) for guide. +A utility function that lets you set the transaction to get subsequent status updates and the finalized result once available. #### Arguments @@ -2126,3 +2231,129 @@ Signature objects are used to represent a signature for a particular message as | `addr` | [Address](#address) | the address of the account which this signature has been generated for | | `keyId` | number | The index of the key to use during authorization. (Multiple keys on an account is possible). | | `signature` | string | a hexidecimal-encoded string representation of the generated signature | + + +### SubscriptionParams + +```ts +import { SubscriptionParams } from "@onflow/typedefs" +``` + +An object containing the subscription topic, arguments, and callbacks. + +```ts +interface SubscriptionParams { + topic: T; + args: SubscriptionArgs; + onData: (data: SubscriptionData) => void; + onError: (error: Error) => void; +} +``` + +### SubscriptionTopic + +```ts +import { SubscriptionTopic } from "@onflow/typedefs" +``` + +The subscription topic. Valid values include: `events`, `blocks`, `block_headers`, `block_digests`, `transaction_statuses`, `account_statuses`. + +```ts +enum SubscriptionTopic { + BLOCKS = "blocks", + BLOCK_HEADERS = "block_headers", + BLOCK_DIGESTS = "block_digests", + ACCOUNT_STATUSES = "account_statuses", + TRANSACTION_STATUSES = "transaction_statuses", + EVENTS = "events", +} +``` + +### SubscriptionArgs + +```ts +import { type SubscriptionArgs } from "@onflow/typedefs" +``` + +An array or object of parameters specific to the topic. For example, when subscribing to events, these might be event identifiers. + +```ts +type SubscriptionArgs = T extends "blocks" | "block_headers" | "block_digests" + ? BlockArgs + : T extends "account_statuses" + ? AccountStatusesArgs + : T extends "transaction_statuses" + ? { transactionId: string } + : T extends "events" + ? EventFilter + : never; +``` + +#### Blocks, BlockHeaders, BlockDigests + +```ts +type BlockArgs = { + startBlockId?: string; + startHeight?: number; +} +``` + +#### AccountStatuses + +```ts +type AccountStatusesArgs = { + address: string; +} +``` + +#### TransactionStatuses + +```ts +type TransactionStatusesArgs = { + transactionId: string; +} +``` + +#### Events + +See [EventFilter](#eventfilter). + +### SubscriptionData + +```ts +import { type SubscriptionData } from "@onflow/typedefs" +``` + +The data returned by the subscription. This will vary depending on the topic. + +#### Blocks + +See [BlockObject](#blockobject). + +#### BlockHeaders + +See [BlockHeaderObject](#blockheaderobject). + +#### BlockDigests + +See [BlockDigestObject](#blockdigestobject). + +#### AccountStatuses + +See [AccountStatusObject](#accountstatusobject). + +#### TransactionStatuses + +See [TransactionStatusObject](#transactionstatusobject). + +#### Events + +See [EventObject](#event-object). + +### RawSubscriptionData + +```ts +import { type RawSubscriptionData } from "@onflow/typedefs" +``` + +The raw data returned by the subscription. This will vary depending on the topic. \ No newline at end of file From 56220273f9c98c19e2039e30eab7a91162ee5bba Mon Sep 17 00:00:00 2001 From: Jordan Ribbink Date: Mon, 31 Mar 2025 12:16:08 -0700 Subject: [PATCH 02/16] add raw data --- docs/tools/clients/fcl-js/api.md | 154 +++++++++++++++++++++++++++---- 1 file changed, 137 insertions(+), 17 deletions(-) diff --git a/docs/tools/clients/fcl-js/api.md b/docs/tools/clients/fcl-js/api.md index 02a47dfcb0..4643a3c59b 100644 --- a/docs/tools/clients/fcl-js/api.md +++ b/docs/tools/clients/fcl-js/api.md @@ -2277,32 +2277,30 @@ import { type SubscriptionArgs } from "@onflow/typedefs" An array or object of parameters specific to the topic. For example, when subscribing to events, these might be event identifiers. -```ts -type SubscriptionArgs = T extends "blocks" | "block_headers" | "block_digests" - ? BlockArgs - : T extends "account_statuses" - ? AccountStatusesArgs - : T extends "transaction_statuses" - ? { transactionId: string } - : T extends "events" - ? EventFilter - : never; -``` #### Blocks, BlockHeaders, BlockDigests ```ts -type BlockArgs = { - startBlockId?: string; - startHeight?: number; -} +type BlockArgs = + | { + blockStatus: "finalized" | "sealed"; + startBlockId?: string; + } + | { + blockStatus: "finalized" | "sealed"; + startBlockHeight?: number; + } ``` #### AccountStatuses ```ts type AccountStatusesArgs = { - address: string; + startBlockId?: string; + startBlockHeight?: number; + eventTypes?: string[]; + addresses?: string[]; + accountAddresses?: string[]; } ``` @@ -2356,4 +2354,126 @@ See [EventObject](#event-object). import { type RawSubscriptionData } from "@onflow/typedefs" ``` -The raw data returned by the subscription. This will vary depending on the topic. \ No newline at end of file +The raw data returned by the subscription. This will vary depending on the topic. + +#### Blocks + +```ts +type RawBlockData = { + block: { + id: string; + parentId: string; + height: number; + timestamp: string; + collectionGuarantees: { + collectionId: string; + signatures: { + addr: string; + keyId: number; + signature: string; + }[]; + }[]; + blockSeals: { + addr: string; + keyId: number; + signature: string; + }[]; + signatures: { + addr: string; + keyId: number; + signature: string; + }[]; + } +} +``` + +#### BlockHeaders + +```ts +type RawBlockHeaderData = { + blockHeader: { + id: string; + parentId: string; + height: number; + timestamp: string; + } +} +``` + +#### BlockDigests + +```ts +type RawBlockDigestData = { + blockDigest: { + id: string; + parentId: string; + height: number; + timestamp: string; + } +} +``` + +#### AccountStatuses + +```ts +type RawAccountStatusData = { + accountStatus: { + address: string; + balance: number; + code: string; + contracts: { + [contractName: string]: string; + }; + keys: { + index: number; + publicKey: string; + revoked: boolean; + sequenceNumber: number; + signAlgo: number; + hashAlgo: number; + weight: number; + }[]; + } +} +``` + +#### TransactionStatuses + +```ts +type RawTransactionStatusData = { + transactionStatus: { + blockId: string; + events: { + blockId: string; + blockHeight: number; + blockTimestamp: string; + type: string; + transactionId: string; + transactionIndex: number; + eventIndex: number; + data: any; + }[]; + status: number; + statusString: string; + errorMessage: string; + statusCode: number; + } +} +``` + +#### Events + +```ts +type RawEventData = { + event: { + blockId: string; + blockHeight: number; + blockTimestamp: string; + type: string; + transactionId: string; + transactionIndex: number; + eventIndex: number; + data: any; + } +} +``` \ No newline at end of file From 22ccdaf61faece0156b6b29bbc7a640163554e12 Mon Sep 17 00:00:00 2001 From: Jordan Ribbink Date: Mon, 31 Mar 2025 12:17:13 -0700 Subject: [PATCH 03/16] fix imports --- docs/tools/clients/fcl-js/api.md | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/docs/tools/clients/fcl-js/api.md b/docs/tools/clients/fcl-js/api.md index 4643a3c59b..0b2346c66d 100644 --- a/docs/tools/clients/fcl-js/api.md +++ b/docs/tools/clients/fcl-js/api.md @@ -2326,26 +2326,50 @@ The data returned by the subscription. This will vary depending on the topic. #### Blocks +```ts +import { type Block } from "@onflow/typedefs" +``` + See [BlockObject](#blockobject). #### BlockHeaders +```ts +import { type BlockHeader } from "@onflow/typedefs" +``` + See [BlockHeaderObject](#blockheaderobject). #### BlockDigests +```ts +import { type BlockDigest } from "@onflow/typedefs" +``` + See [BlockDigestObject](#blockdigestobject). #### AccountStatuses +```ts +import { type AccountStatus } from "@onflow/typedefs" +``` + See [AccountStatusObject](#accountstatusobject). #### TransactionStatuses +```ts +import { type TransactionStatus } from "@onflow/typedefs" +``` + See [TransactionStatusObject](#transactionstatusobject). #### Events +```ts +import { type Event } from "@onflow/typedefs" +``` + See [EventObject](#event-object). ### RawSubscriptionData From 9abe31a37c59f9d9ca5a1dde130eb9e745787f9a Mon Sep 17 00:00:00 2001 From: Jordan Ribbink Date: Mon, 31 Mar 2025 20:58:57 -0700 Subject: [PATCH 04/16] cleanup --- docs/tools/clients/fcl-js/api.md | 165 ++++++++++++++++++++++++++----- 1 file changed, 139 insertions(+), 26 deletions(-) diff --git a/docs/tools/clients/fcl-js/api.md b/docs/tools/clients/fcl-js/api.md index 0b2346c66d..9962a975b1 100644 --- a/docs/tools/clients/fcl-js/api.md +++ b/docs/tools/clients/fcl-js/api.md @@ -2241,6 +2241,7 @@ import { SubscriptionParams } from "@onflow/typedefs" An object containing the subscription topic, arguments, and callbacks. + ```ts interface SubscriptionParams { topic: T; @@ -2252,21 +2253,37 @@ interface SubscriptionParams { ### SubscriptionTopic +Import: + ```ts import { SubscriptionTopic } from "@onflow/typedefs" ``` -The subscription topic. Valid values include: `events`, `blocks`, `block_headers`, `block_digests`, `transaction_statuses`, `account_statuses`. +The `SubscriptionTopic` type is used to specify the topic of a subscription. + +The type is defined as: + +```ts +type SubscriptionTopic = + | "blocks" + | "block_headers" + | "block_digests" + | "account_statuses" + | "transaction_statuses" + | "events" +``` + +Constants for each topic are also provided: ```ts -enum SubscriptionTopic { +const SubscriptionTopic = { BLOCKS = "blocks", BLOCK_HEADERS = "block_headers", BLOCK_DIGESTS = "block_digests", ACCOUNT_STATUSES = "account_statuses", TRANSACTION_STATUSES = "transaction_statuses", EVENTS = "events", -} +} as const ``` ### SubscriptionArgs @@ -2277,25 +2294,67 @@ import { type SubscriptionArgs } from "@onflow/typedefs" An array or object of parameters specific to the topic. For example, when subscribing to events, these might be event identifiers. +Usage: + +```ts +const args: SubscriptionArgs<"events"> = { + eventTypes: ["A.7e60df042a9c0868.FlowToken.TokensWithdrawn"], + addresses: ["0x7e60df042a9c0868"], +} +``` + #### Blocks, BlockHeaders, BlockDigests +Import: + ```ts -type BlockArgs = - | { - blockStatus: "finalized" | "sealed"; - startBlockId?: string; - } - | { - blockStatus: "finalized" | "sealed"; - startBlockHeight?: number; - } +import { type BlockSubscriptionArgs } from "@onflow/typedefs" +``` + +Any of the following formats are valid for the `args` field. + +Start at the latest block: + +```ts +// Internal type, not exported +type BlockSubscriptionAtLatestArgs = { + blockStatus: "finalized" | "sealed"; +} +``` + +Start at a specific block ID: + +```ts +// Internal type, not exported +type BlockSubscriptionAtIdArgs = { + blockStatus: "finalized" | "sealed"; + startBlockId: string; +} +``` + +Start at a specific block height: + +```ts +// Internal type, not exported +type BlockSubscriptionAtHeightArgs = { + blockStatus: "finalized" | "sealed"; + startBlockHeight: number; +} ``` #### AccountStatuses +Import: + +```ts +import { type AccountStatusSubscriptionArgs } from "@onflow/typedefs" +``` + +Type definition: + ```ts -type AccountStatusesArgs = { +type AccountStatusSubscriptionArgs = { startBlockId?: string; startBlockHeight?: number; eventTypes?: string[]; @@ -2304,10 +2363,18 @@ type AccountStatusesArgs = { } ``` -#### TransactionStatuses +#### Transaction Statuses + +Import: + +```ts +import { type TransactionStatusSubscriptionArgs } from "@onflow/typedefs" +``` + +Type definition: ```ts -type TransactionStatusesArgs = { +type TransactionStatusSubscriptionArgs = { transactionId: string; } ``` @@ -2356,7 +2423,7 @@ import { type AccountStatus } from "@onflow/typedefs" See [AccountStatusObject](#accountstatusobject). -#### TransactionStatuses +#### Transaction Statuses ```ts import { type TransactionStatus } from "@onflow/typedefs" @@ -2382,8 +2449,16 @@ The raw data returned by the subscription. This will vary depending on the topic #### Blocks +Import: + +```ts +import { type RawBlock } from "@onflow/typedefs" +``` + +Type definition: + ```ts -type RawBlockData = { +type RawBlock = { block: { id: string; parentId: string; @@ -2411,10 +2486,18 @@ type RawBlockData = { } ``` -#### BlockHeaders +#### Block Headers + +Import: ```ts -type RawBlockHeaderData = { +import { type RawBlockHeader } from "@onflow/typedefs" +``` + +Type definition: + +```ts +type RawBlockHeader = { blockHeader: { id: string; parentId: string; @@ -2424,10 +2507,18 @@ type RawBlockHeaderData = { } ``` -#### BlockDigests +#### Block Digests + +Import: ```ts -type RawBlockDigestData = { +import { type RawBlockDigest } from "@onflow/typedefs" +``` + +Type definition: + +```ts +type RawBlockDigest = { blockDigest: { id: string; parentId: string; @@ -2437,10 +2528,16 @@ type RawBlockDigestData = { } ``` -#### AccountStatuses +#### Account Statuses + +Import: ```ts -type RawAccountStatusData = { +import { type RawAccountStatus } from "@onflow/typedefs" +``` + +```ts +type RawAccountStatus = { accountStatus: { address: string; balance: number; @@ -2461,10 +2558,18 @@ type RawAccountStatusData = { } ``` -#### TransactionStatuses +#### Transaction Statuses + +Import: + +```ts +import { type RawTransactionStatus } from "@onflow/typedefs" +``` + +Type definition: ```ts -type RawTransactionStatusData = { +type RawTransactionStatus = { transactionStatus: { blockId: string; events: { @@ -2487,8 +2592,16 @@ type RawTransactionStatusData = { #### Events +Import: + +```ts +import { type RawEvent } from "@onflow/typedefs" +``` + +Type definition: + ```ts -type RawEventData = { +type RawEvent = { event: { blockId: string; blockHeight: number; From 4e83b2b03c42661b594833181b18d32f0571dd74 Mon Sep 17 00:00:00 2001 From: Jordan Ribbink Date: Mon, 31 Mar 2025 21:01:42 -0700 Subject: [PATCH 05/16] fix --- docs/tools/clients/fcl-js/api.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/tools/clients/fcl-js/api.md b/docs/tools/clients/fcl-js/api.md index 9962a975b1..29b6aa62fa 100644 --- a/docs/tools/clients/fcl-js/api.md +++ b/docs/tools/clients/fcl-js/api.md @@ -2413,7 +2413,7 @@ See [BlockHeaderObject](#blockheaderobject). import { type BlockDigest } from "@onflow/typedefs" ``` -See [BlockDigestObject](#blockdigestobject). +See BlockDigestObject. #### AccountStatuses @@ -2421,7 +2421,7 @@ See [BlockDigestObject](#blockdigestobject). import { type AccountStatus } from "@onflow/typedefs" ``` -See [AccountStatusObject](#accountstatusobject). +See AccountStatusObject. #### Transaction Statuses From 27644cb3bf8d24b7f7b23c72b1a793cacbea66c5 Mon Sep 17 00:00:00 2001 From: Jordan Ribbink Date: Thu, 3 Apr 2025 06:34:20 -0700 Subject: [PATCH 06/16] cleanup --- docs/tools/clients/fcl-js/api.md | 138 ++++++++++++++++++------------- 1 file changed, 81 insertions(+), 57 deletions(-) diff --git a/docs/tools/clients/fcl-js/api.md b/docs/tools/clients/fcl-js/api.md index 29b6aa62fa..6939c53ba3 100644 --- a/docs/tools/clients/fcl-js/api.md +++ b/docs/tools/clients/fcl-js/api.md @@ -1528,23 +1528,23 @@ The following topics are available for subscription: ### `subscribe` -A utility function used for subscribing to real-time data from the WebSocket Streaming API. Data returned will be automatically decoded via `fcl.decode`. +A utility function used for subscribing to real-time data from the WebSocket Streaming API. Data returned will be automatically decoded via the [`decode`](#decode) function. #### Arguments | Name | Type | Description | | -------------------- | ------------------ | -------------------------------------------------------------------------------------------------- | -| [`SubscriptionParams`] | SubscriptionParams | An object containing the subscription topic, arguments, and callbacks. See below for more details. | +| `params` | `SubscribeParams` | An object containing the subscription topic, arguments, and callbacks. See below for more details. | | `opts` | object | _(Optional)_ Additional options for the subscription. See below for more details. | -SubscriptionParams (first parameter): +`SubscribeParams` (first parameter): | Name | Type | Description | | --------- | ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | -| `topic` | SubscriptionTopic | The subscription topic. Valid values include: `events`, `blocks`, `transactions`, and `collections`. | -| `args` | SubscriptionArgs | An array or object of parameters specific to the topic. For example, when subscribing to events, these might be event identifiers. | -| `onData` | (data: SubscriptionData) | A callback function that is called with the decoded data whenever a new message is received. | -| `onError` | (error: Error) => void | A callback function that is called if an error occurs during the subscription. | +| `topic` | [`SubscriptionTopic`](#subscriptiontopic) | The subscription topic. Valid values include: `events`, `blocks`, `transactions`, and `collections`. | +| `args` | [`SubscriptionArgs`](#subscriptionargs) | An array or object of parameters specific to the topic. For example, when subscribing to events, these might be event identifiers. | +| `onData` | [`(data: SubscriptionData)`](#subscriptiontopic) | A callback function that is called with the decoded data whenever a new message is received. | +| `onError` | `(error: Error) => void` | A callback function that is called if an error occurs during the subscription. | Additional Options (second parameter): @@ -1602,9 +1602,6 @@ Additional Options (second parameter): #### Returns -| Type | Description | -| ------------------------------------------------------ | ---------------------------------------------------------------------------------------------- | -| [SdkTransport.Subscription](#sdktransportsubscription) | A subscription object that allows you to manage the subscription (e.g., to unsubscribe later). | #### Usage @@ -2233,7 +2230,7 @@ Signature objects are used to represent a signature for a particular message as | `signature` | string | a hexidecimal-encoded string representation of the generated signature | -### SubscriptionParams +### SubscriptionParams ```ts import { SubscriptionParams } from "@onflow/typedefs" @@ -2251,6 +2248,15 @@ interface SubscriptionParams { } ``` +| Subscription Topic | Argument Type | Data Returned | +|-------------------------|----------------------------------------|-----------------------| +| `"blocks"` | `SubscriptionArgs<"blocks">` | `Block` | +| `"block_headers"` | `SubscriptionArgs<"block_headers">` | `BlockHeader` | +| `"block_digests"` | `SubscriptionArgs<"block_digests">` | `BlockDigest` | +| `"account_statuses"` | `SubscriptionArgs<"account_statuses">` | `AccountStatus` | +| `"transaction_statuses"`| `SubscriptionArgs<"transaction_statuses">` | `TransactionStatus` | +| `"events"` | `SubscriptionArgs<"events">` | `Event` | + ### SubscriptionTopic Import: @@ -2261,8 +2267,6 @@ import { SubscriptionTopic } from "@onflow/typedefs" The `SubscriptionTopic` type is used to specify the topic of a subscription. -The type is defined as: - ```ts type SubscriptionTopic = | "blocks" @@ -2273,7 +2277,7 @@ type SubscriptionTopic = | "events" ``` -Constants for each topic are also provided: +The `SubscriptionTopic` type is also exported as a constant object for easier usage in TypeScript. ```ts const SubscriptionTopic = { @@ -2286,12 +2290,28 @@ const SubscriptionTopic = { } as const ``` -### SubscriptionArgs +### SubscriptionArgs ```ts import { type SubscriptionArgs } from "@onflow/typedefs" ``` +Type definition: + +```ts +type SubscriptionArgs = { + [K in T]: K extends "blocks" | "block_headers" | "block_digests" + ? BlockSubscriptionAtLatestArgs | BlockSubscriptionAtIdArgs | BlockSubscriptionAtHeightArgs + : K extends "account_statuses" + ? AccountStatusSubscriptionArgs + : K extends "transaction_statuses" + ? TransactionStatusSubscriptionArgs + : K extends "events" + ? EventSubscriptionArgs + : never; +}[T]; +``` + An array or object of parameters specific to the topic. For example, when subscribing to events, these might be event identifiers. Usage: @@ -2303,16 +2323,9 @@ const args: SubscriptionArgs<"events"> = { } ``` - #### Blocks, BlockHeaders, BlockDigests -Import: - -```ts -import { type BlockSubscriptionArgs } from "@onflow/typedefs" -``` - -Any of the following formats are valid for the `args` field. +_Applies to topics: `blocks`, `block_headers`, `block_digests`_ Start at the latest block: @@ -2345,15 +2358,10 @@ type BlockSubscriptionAtHeightArgs = { #### AccountStatuses -Import: - -```ts -import { type AccountStatusSubscriptionArgs } from "@onflow/typedefs" -``` - -Type definition: +_Applies to topic: `account_statuses`_ ```ts +// Internal type, not exported type AccountStatusSubscriptionArgs = { startBlockId?: string; startBlockHeight?: number; @@ -2365,25 +2373,35 @@ type AccountStatusSubscriptionArgs = { #### Transaction Statuses -Import: +_Applies to topic: `transaction_statuses`_ ```ts -import { type TransactionStatusSubscriptionArgs } from "@onflow/typedefs" +// Internal type, not exported +type TransactionStatusSubscriptionArgs = { + transactionId: string; +} ``` +#### Events + +_Applies to topic: `events`_ + Type definition: ```ts -type TransactionStatusSubscriptionArgs = { - transactionId: string; +// Internal type, not exported +type EventSubscriptionArgs = { + startBlockId?: string; + startBlockHeight?: number; + eventTypes?: string[]; + addresses?: string[]; + contracts?: string[]; } ``` -#### Events +### SubscriptionData -See [EventFilter](#eventfilter). - -### SubscriptionData +**Import:** ```ts import { type SubscriptionData } from "@onflow/typedefs" @@ -2391,55 +2409,61 @@ import { type SubscriptionData } from "@onflow/typedefs" The data returned by the subscription. This will vary depending on the topic. -#### Blocks - ```ts -import { type Block } from "@onflow/typedefs" +type SubscriptionData = { + [K in T]: K extends "blocks" + ? Block + : K extends "block_headers" + ? Blockheader + : K extends "block_digests" + ? BlockDigestObject + : K extends "account_statuses" + ? AccountStatusObject + : K extends "transaction_statuses" + ? TransactionStatusObject + : K extends "events" + ? EventObject + : never; +}[T]; ``` +#### Blocks + +___Applies to topic: `blocks`_ + See [BlockObject](#blockobject). #### BlockHeaders -```ts -import { type BlockHeader } from "@onflow/typedefs" -``` +__Applies to topic: `block_headers`_ See [BlockHeaderObject](#blockheaderobject). #### BlockDigests -```ts -import { type BlockDigest } from "@onflow/typedefs" -``` +__Applies to topic: `block_digests`_ See BlockDigestObject. #### AccountStatuses -```ts -import { type AccountStatus } from "@onflow/typedefs" -``` +__Applies to topic: `account_statuses`_ See AccountStatusObject. #### Transaction Statuses -```ts -import { type TransactionStatus } from "@onflow/typedefs" -``` +__Applies to topic: `transaction_statuses`_ See [TransactionStatusObject](#transactionstatusobject). #### Events -```ts -import { type Event } from "@onflow/typedefs" -``` +__Applies to topic: `events`_ See [EventObject](#event-object). -### RawSubscriptionData +### RawSubscriptionData ```ts import { type RawSubscriptionData } from "@onflow/typedefs" From 1d37ca7c6dcc42279a2f0d00fbc4c2325a0651f2 Mon Sep 17 00:00:00 2001 From: Jordan Ribbink Date: Thu, 3 Apr 2025 06:49:30 -0700 Subject: [PATCH 07/16] fix build --- docs/tools/clients/fcl-js/api.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/tools/clients/fcl-js/api.md b/docs/tools/clients/fcl-js/api.md index 6939c53ba3..6ce20e57a6 100644 --- a/docs/tools/clients/fcl-js/api.md +++ b/docs/tools/clients/fcl-js/api.md @@ -1557,7 +1557,7 @@ Additional Options (second parameter): | Type | Description | | ------------------------------------------------------ | ---------------------------------------------------------------------------------------------- | -| [SdkTransport.Subscription](#sdktransportsubscription) | A subscription object that allows you to manage the subscription (e.g., to unsubscribe later). | +| SdkTransport.Subscription | A subscription object that allows you to manage the subscription (e.g., to unsubscribe later). | #### Usage @@ -1588,9 +1588,9 @@ A utility function used for subscribing to raw data from the WebSocket Streaming | Name | Type | Description | | --------- | -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | -| `topic` | SubscriptionTopic | The subscription topic. Valid values include: `events`, `blocks`, `transactions`, and `collections`. | -| `args` | RawSubscriptionArgs | An array or object of parameters specific to the topic. For example, when subscribing to events, these might be event identifiers. | -| `onData` | (data: RawSubscriptionData) | A callback function that is called with the decoded data whenever a new message is received. | +| `topic` | `SubscriptionTopic` | The subscription topic. Valid values include: `events`, `blocks`, `transactions`, and `collections`. | +| `args` | `RawSubscriptionArgs` | An array or object of parameters specific to the topic. For example, when subscribing to events, these might be event identifiers. | +| `onData` | `(data: RawSubscriptionData) => void` | A callback function that is called with the decoded data whenever a new message is received. | | `onError` | (error: Error) => void | A callback function that is called if an error occurs during the subscription. | Additional Options (second parameter): @@ -2463,7 +2463,7 @@ __Applies to topic: `events`_ See [EventObject](#event-object). -### RawSubscriptionData +### RawSubscriptionData ```ts import { type RawSubscriptionData } from "@onflow/typedefs" From cd17cf826d70881ed25e6dd8760d9185a0ddeb0f Mon Sep 17 00:00:00 2001 From: Jordan Ribbink Date: Thu, 3 Apr 2025 07:35:07 -0700 Subject: [PATCH 08/16] fix up params --- docs/tools/clients/fcl-js/api.md | 20 ++++---------------- 1 file changed, 4 insertions(+), 16 deletions(-) diff --git a/docs/tools/clients/fcl-js/api.md b/docs/tools/clients/fcl-js/api.md index 6ce20e57a6..23cf025106 100644 --- a/docs/tools/clients/fcl-js/api.md +++ b/docs/tools/clients/fcl-js/api.md @@ -1534,17 +1534,12 @@ A utility function used for subscribing to real-time data from the WebSocket Str | Name | Type | Description | | -------------------- | ------------------ | -------------------------------------------------------------------------------------------------- | -| `params` | `SubscribeParams` | An object containing the subscription topic, arguments, and callbacks. See below for more details. | +| `params` | [`SubscriptionParams`](#subscriptionparams) | An object containing the subscription topic, arguments, and callbacks. See below for more details. | | `opts` | object | _(Optional)_ Additional options for the subscription. See below for more details. | -`SubscribeParams` (first parameter): +`params` (first parameter): -| Name | Type | Description | -| --------- | ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | -| `topic` | [`SubscriptionTopic`](#subscriptiontopic) | The subscription topic. Valid values include: `events`, `blocks`, `transactions`, and `collections`. | -| `args` | [`SubscriptionArgs`](#subscriptionargs) | An array or object of parameters specific to the topic. For example, when subscribing to events, these might be event identifiers. | -| `onData` | [`(data: SubscriptionData)`](#subscriptiontopic) | A callback function that is called with the decoded data whenever a new message is received. | -| `onError` | `(error: Error) => void` | A callback function that is called if an error occurs during the subscription. | +See [`SubscriptionParams`](#subscriptionparams) for more details. Additional Options (second parameter): @@ -2248,14 +2243,7 @@ interface SubscriptionParams { } ``` -| Subscription Topic | Argument Type | Data Returned | -|-------------------------|----------------------------------------|-----------------------| -| `"blocks"` | `SubscriptionArgs<"blocks">` | `Block` | -| `"block_headers"` | `SubscriptionArgs<"block_headers">` | `BlockHeader` | -| `"block_digests"` | `SubscriptionArgs<"block_digests">` | `BlockDigest` | -| `"account_statuses"` | `SubscriptionArgs<"account_statuses">` | `AccountStatus` | -| `"transaction_statuses"`| `SubscriptionArgs<"transaction_statuses">` | `TransactionStatus` | -| `"events"` | `SubscriptionArgs<"events">` | `Event` | + ### SubscriptionTopic From f3bb9cc7f5d4a7e4b083f24932334b26dd2fbef6 Mon Sep 17 00:00:00 2001 From: Jordan Ribbink Date: Thu, 3 Apr 2025 07:37:29 -0700 Subject: [PATCH 09/16] update --- docs/tools/clients/fcl-js/api.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/docs/tools/clients/fcl-js/api.md b/docs/tools/clients/fcl-js/api.md index 23cf025106..99f08480f7 100644 --- a/docs/tools/clients/fcl-js/api.md +++ b/docs/tools/clients/fcl-js/api.md @@ -2243,7 +2243,14 @@ interface SubscriptionParams { } ``` - +| Subscription Topic | Argument Type | Data Returned | +|-------------------------|----------------------------------------|-----------------------| +| `"blocks"` | [`SubscriptionArgs<"blocks">`](#blocks-blockheaders-blockdigests) | `Block` | +| `"block_headers"` | [`SubscriptionArgs<"block_headers">`](#blocks-blockheaders-blockdigests) | `BlockHeader` | +| `"block_digests"` | [`SubscriptionArgs<"block_digests">`](#blocks-blockheaders-blockdigests) | `BlockDigest` | +| `"account_statuses"` | [`SubscriptionArgs<"account_statuses">`](#accountstatuses-1) | `AccountStatus` | +| `"transaction_statuses"`| [`SubscriptionArgs<"transaction_statuses">`](#transaction-statuses-3) | `TransactionStatus` | +| `"events"` | [`SubscriptionArgs<"events">`](#events-3) | `Event` | ### SubscriptionTopic From 9c487cc7ad28017bdadedd4ac3be7985f42b57b9 Mon Sep 17 00:00:00 2001 From: Jordan Ribbink Date: Thu, 3 Apr 2025 07:39:31 -0700 Subject: [PATCH 10/16] update --- docs/tools/clients/fcl-js/api.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/tools/clients/fcl-js/api.md b/docs/tools/clients/fcl-js/api.md index 99f08480f7..da6111484f 100644 --- a/docs/tools/clients/fcl-js/api.md +++ b/docs/tools/clients/fcl-js/api.md @@ -2214,7 +2214,7 @@ import { BlockHeartbeat } from "@onflow/typedefs" const heartbeat: BlockHeartbeat = ... ``` -### SignatureObject +### `SignatureObject` Signature objects are used to represent a signature for a particular message as well as the account and keyId which signed for this message. @@ -2225,7 +2225,7 @@ Signature objects are used to represent a signature for a particular message as | `signature` | string | a hexidecimal-encoded string representation of the generated signature | -### SubscriptionParams +### `SubscriptionParams` ```ts import { SubscriptionParams } from "@onflow/typedefs" @@ -2252,7 +2252,7 @@ interface SubscriptionParams { | `"transaction_statuses"`| [`SubscriptionArgs<"transaction_statuses">`](#transaction-statuses-3) | `TransactionStatus` | | `"events"` | [`SubscriptionArgs<"events">`](#events-3) | `Event` | -### SubscriptionTopic +### `SubscriptionTopic` Import: @@ -2285,7 +2285,7 @@ const SubscriptionTopic = { } as const ``` -### SubscriptionArgs +### `SubscriptionArgs` ```ts import { type SubscriptionArgs } from "@onflow/typedefs" @@ -2394,7 +2394,7 @@ type EventSubscriptionArgs = { } ``` -### SubscriptionData +### `SubscriptionData` **Import:** @@ -2458,7 +2458,7 @@ __Applies to topic: `events`_ See [EventObject](#event-object). -### RawSubscriptionData +### `RawSubscriptionData` ```ts import { type RawSubscriptionData } from "@onflow/typedefs" From 78324b268380a6a7b6521a92e7c9f68ef8e48177 Mon Sep 17 00:00:00 2001 From: Jordan Ribbink Date: Thu, 3 Apr 2025 07:48:08 -0700 Subject: [PATCH 11/16] add links --- docs/tools/clients/fcl-js/api.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/tools/clients/fcl-js/api.md b/docs/tools/clients/fcl-js/api.md index da6111484f..8c7f90041f 100644 --- a/docs/tools/clients/fcl-js/api.md +++ b/docs/tools/clients/fcl-js/api.md @@ -2245,12 +2245,12 @@ interface SubscriptionParams { | Subscription Topic | Argument Type | Data Returned | |-------------------------|----------------------------------------|-----------------------| -| `"blocks"` | [`SubscriptionArgs<"blocks">`](#blocks-blockheaders-blockdigests) | `Block` | -| `"block_headers"` | [`SubscriptionArgs<"block_headers">`](#blocks-blockheaders-blockdigests) | `BlockHeader` | +| `"blocks"` | [`SubscriptionArgs<"blocks">`](#blocks-blockheaders-blockdigests) | [`Block`](#blockobject) | +| `"block_headers"` | [`SubscriptionArgs<"block_headers">`](#blocks-blockheaders-blockdigests) | [`BlockHeader`](#blockheaderobject) | | `"block_digests"` | [`SubscriptionArgs<"block_digests">`](#blocks-blockheaders-blockdigests) | `BlockDigest` | -| `"account_statuses"` | [`SubscriptionArgs<"account_statuses">`](#accountstatuses-1) | `AccountStatus` | -| `"transaction_statuses"`| [`SubscriptionArgs<"transaction_statuses">`](#transaction-statuses-3) | `TransactionStatus` | -| `"events"` | [`SubscriptionArgs<"events">`](#events-3) | `Event` | +| `"account_statuses"` | [`SubscriptionArgs<"account_statuses">`](#accountstatuses) | [`AccountStatus`] | +| `"transaction_statuses"`| [`SubscriptionArgs<"transaction_statuses">`](#transaction-statuses-2) | [`TransactionStatus`](#transactionstatusobject) | +| `"events"` | [`SubscriptionArgs<"events">`](#events-2) | [`Event`] | ### `SubscriptionTopic` From d6d0edabd1acee1b616d0e5438fbb01eaf97fdb4 Mon Sep 17 00:00:00 2001 From: Jordan Ribbink Date: Thu, 3 Apr 2025 07:54:33 -0700 Subject: [PATCH 12/16] fixup italics --- docs/tools/clients/fcl-js/api.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/tools/clients/fcl-js/api.md b/docs/tools/clients/fcl-js/api.md index 8c7f90041f..6250d1007d 100644 --- a/docs/tools/clients/fcl-js/api.md +++ b/docs/tools/clients/fcl-js/api.md @@ -2424,37 +2424,37 @@ type SubscriptionData = { #### Blocks -___Applies to topic: `blocks`_ +_Applies to topic: `blocks`_ See [BlockObject](#blockobject). #### BlockHeaders -__Applies to topic: `block_headers`_ +_Applies to topic: `block_headers`_ See [BlockHeaderObject](#blockheaderobject). #### BlockDigests -__Applies to topic: `block_digests`_ +_Applies to topic: `block_digests`_ See BlockDigestObject. #### AccountStatuses -__Applies to topic: `account_statuses`_ +_Applies to topic: `account_statuses`_ See AccountStatusObject. #### Transaction Statuses -__Applies to topic: `transaction_statuses`_ +_Applies to topic: `transaction_statuses`_ See [TransactionStatusObject](#transactionstatusobject). #### Events -__Applies to topic: `events`_ +_Applies to topic: `events`_ See [EventObject](#event-object). From 5a66167230786dd752f76127fc3356fce7bc18d1 Mon Sep 17 00:00:00 2001 From: Jordan Ribbink Date: Thu, 3 Apr 2025 07:55:50 -0700 Subject: [PATCH 13/16] add spaces --- docs/tools/clients/fcl-js/api.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/tools/clients/fcl-js/api.md b/docs/tools/clients/fcl-js/api.md index 6250d1007d..1932a2ede1 100644 --- a/docs/tools/clients/fcl-js/api.md +++ b/docs/tools/clients/fcl-js/api.md @@ -2318,7 +2318,7 @@ const args: SubscriptionArgs<"events"> = { } ``` -#### Blocks, BlockHeaders, BlockDigests +#### Blocks, Block Headers, Block Digests _Applies to topics: `blocks`, `block_headers`, `block_digests`_ @@ -2351,7 +2351,7 @@ type BlockSubscriptionAtHeightArgs = { } ``` -#### AccountStatuses +#### Account Statuses _Applies to topic: `account_statuses`_ @@ -2428,19 +2428,19 @@ _Applies to topic: `blocks`_ See [BlockObject](#blockobject). -#### BlockHeaders +#### Block Headers _Applies to topic: `block_headers`_ See [BlockHeaderObject](#blockheaderobject). -#### BlockDigests +#### Block Digests _Applies to topic: `block_digests`_ See BlockDigestObject. -#### AccountStatuses +#### Account Statuses _Applies to topic: `account_statuses`_ From 82b6764a1e60e8325d47849af1373f263bb713f0 Mon Sep 17 00:00:00 2001 From: Jordan Ribbink Date: Thu, 3 Apr 2025 07:58:47 -0700 Subject: [PATCH 14/16] reorg --- docs/tools/clients/fcl-js/api.md | 130 ++++++++++++++++--------------- 1 file changed, 66 insertions(+), 64 deletions(-) diff --git a/docs/tools/clients/fcl-js/api.md b/docs/tools/clients/fcl-js/api.md index 1932a2ede1..ad8d801ab6 100644 --- a/docs/tools/clients/fcl-js/api.md +++ b/docs/tools/clients/fcl-js/api.md @@ -1517,14 +1517,73 @@ const latestBlock = await fcl.latestBlock(); Streaming data is available through the WebSocket Streaming API provided by the HTTP Access API. It allows developers to subscribe to specific topics and receive real-time updates as they occur on the Flow blockchain. -The following topics are available for subscription: +The following topics can be subscribed to: -- `events` -- `blocks` -- `block_headers` -- `block_digests` -- `transaction_statuses` -- `account_statuses` +- `events`: Subscribe to events emitted by contracts. +- `blocks`: Subscribe to new blocks added to the chain. +- `block_headers`: Subscribe to new block headers added to the chain. +- `block_digests`: Subscribe to block digests added to the chain. +- `transaction_statuses`: Subscribe to transaction statuses. +- `account_statuses`: Subscribe to account statuses. + +### `tx` + +A utility function that lets you set the transaction to get subsequent status updates and the finalized result once available. + +#### Arguments + +| Name | Type | Description | +| --------------- | ------ | ----------------------- | +| `transactionId` | string | A valid transaction id. | + +#### Returns + +| Name | Type | Description | +| ----------------- | -------- | --------------------------------------------------------------------------------------------------------- | +| `snapshot()` | function | Returns the current state of the transaction. | +| `subscribe(cb)` | function | Calls the `cb` passed in with the new transaction on a status change. | +| `onceFinalized()` | function | Provides the transaction once status `2` is returned. See [Tranasaction Statuses](#transaction-statuses). | +| `onceExecuted()` | function | Provides the transaction once status `3` is returned. See [Tranasaction Statuses](#transaction-statuses). | +| `onceSealed()` | function | Provides the transaction once status `4` is returned. See [Tranasaction Statuses](#transaction-statuses). | + +#### Usage + +```javascript +import * as fcl from '@onflow/fcl'; + +const [txStatus, setTxStatus] = useState(null); +useEffect(() => fcl.tx(txId).subscribe(setTxStatus)); +``` + +--- + +### `events` + +A utility function that lets you set the transaction to get subsequent status updates and the finalized result once available. + +#### Arguments + +| Name | Type | Description | +| ------------------- | ----------------------------------------- | ------------------------------------------------ | +| `eventNameOrFilter` | string | [EventFilter](#eventfilter) | The name of the event or an event filter object. | + +#### Returns + +| Name | Type | Description | +| --------------- | -------- | -------------------------------------------- | +| `subscribe(cb)` | function | Calls the `cb` passed in with the new event. | + +#### Usage + +```javascript +import * as fcl from '@onflow/fcl'; +// in some react component +fcl.events(eventName).subscribe((event) => { + console.log(event); +}); +``` + +--- ### `subscribe` @@ -1619,63 +1678,6 @@ subscription.unsubscribe(); --- -### `tx` - -A utility function that lets you set the transaction to get subsequent status updates and the finalized result once available. - -#### Arguments - -| Name | Type | Description | -| --------------- | ------ | ----------------------- | -| `transactionId` | string | A valid transaction id. | - -#### Returns - -| Name | Type | Description | -| ----------------- | -------- | --------------------------------------------------------------------------------------------------------- | -| `snapshot()` | function | Returns the current state of the transaction. | -| `subscribe(cb)` | function | Calls the `cb` passed in with the new transaction on a status change. | -| `onceFinalized()` | function | Provides the transaction once status `2` is returned. See [Tranasaction Statuses](#transaction-statuses). | -| `onceExecuted()` | function | Provides the transaction once status `3` is returned. See [Tranasaction Statuses](#transaction-statuses). | -| `onceSealed()` | function | Provides the transaction once status `4` is returned. See [Tranasaction Statuses](#transaction-statuses). | - -#### Usage - -```javascript -import * as fcl from '@onflow/fcl'; - -const [txStatus, setTxStatus] = useState(null); -useEffect(() => fcl.tx(txId).subscribe(setTxStatus)); -``` - ---- - -### `events` - -A utility function that lets you set the transaction to get subsequent status updates and the finalized result once available. - -#### Arguments - -| Name | Type | Description | -| ------------------- | ----------------------------------------- | ------------------------------------------------ | -| `eventNameOrFilter` | string | [EventFilter](#eventfilter) | The name of the event or an event filter object. | - -#### Returns - -| Name | Type | Description | -| --------------- | -------- | -------------------------------------------- | -| `subscribe(cb)` | function | Calls the `cb` passed in with the new event. | - -#### Usage - -```javascript -import * as fcl from '@onflow/fcl'; -// in some react component -fcl.events(eventName).subscribe((event) => { - console.log(event); -}); -``` - #### Examples - [Flow-view-source example](https://github.com/orodio/flow-view-source/blob/master/src/pages/event.comp.js) From c41cdb9633d85307c3c1a4691d6462abdff08a49 Mon Sep 17 00:00:00 2001 From: Jordan Ribbink Date: Thu, 3 Apr 2025 08:58:42 -0700 Subject: [PATCH 15/16] block digest object --- docs/tools/clients/fcl-js/api.md | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/docs/tools/clients/fcl-js/api.md b/docs/tools/clients/fcl-js/api.md index ad8d801ab6..cb34df2403 100644 --- a/docs/tools/clients/fcl-js/api.md +++ b/docs/tools/clients/fcl-js/api.md @@ -2007,6 +2007,17 @@ The subset of the [BlockObject](#blockobject) containing only the header values | `height` | number | The height of the block. | | `timestamp` | object | Contains time related fields. | +### `BlockDigestObject` + +A lightweight subset of the [BlockObject](#blockobject) containing only the id, height, and timestamp of a block. + +| Key | Value Type | Description | +| ----------- | ---------- | ----------------------------- | +| `id` | string | The id of the block. | +| `height` | number | The height of the block. | +| `timestamp` | string | The timestamp of the block. | + + ### `CollectionGuaranteeObject` A collection that has been included in a block. @@ -2249,7 +2260,7 @@ interface SubscriptionParams { |-------------------------|----------------------------------------|-----------------------| | `"blocks"` | [`SubscriptionArgs<"blocks">`](#blocks-blockheaders-blockdigests) | [`Block`](#blockobject) | | `"block_headers"` | [`SubscriptionArgs<"block_headers">`](#blocks-blockheaders-blockdigests) | [`BlockHeader`](#blockheaderobject) | -| `"block_digests"` | [`SubscriptionArgs<"block_digests">`](#blocks-blockheaders-blockdigests) | `BlockDigest` | +| `"block_digests"` | [`SubscriptionArgs<"block_digests">`](#blocks-blockheaders-blockdigests) | [`BlockDigest`](#blockdigestobject) | | `"account_statuses"` | [`SubscriptionArgs<"account_statuses">`](#accountstatuses) | [`AccountStatus`] | | `"transaction_statuses"`| [`SubscriptionArgs<"transaction_statuses">`](#transaction-statuses-2) | [`TransactionStatus`](#transactionstatusobject) | | `"events"` | [`SubscriptionArgs<"events">`](#events-2) | [`Event`] | From f1267888969655b56dd4ef84bccb1f1f44de3469 Mon Sep 17 00:00:00 2001 From: Jordan Ribbink Date: Thu, 3 Apr 2025 09:03:56 -0700 Subject: [PATCH 16/16] add account status --- docs/tools/clients/fcl-js/api.md | 18 ++++++++++++++++-- 1 file changed, 16 insertions(+), 2 deletions(-) diff --git a/docs/tools/clients/fcl-js/api.md b/docs/tools/clients/fcl-js/api.md index cb34df2403..53e08262fb 100644 --- a/docs/tools/clients/fcl-js/api.md +++ b/docs/tools/clients/fcl-js/api.md @@ -2067,6 +2067,20 @@ The format of all responses in FCL returned from `fcl.send(...)`. For full detai | `eventIndex` | number | Used to prevent replay attacks. | | `data` | any | The data emitted from the event. | +### `Account Status Event Object` + +| Key | Value Type | Description | +| ------------------ | ----------------------- | ----------------------------------------------------------------------------------------------------- | +| `blockId` | string | ID of the block that contains the event. | +| `blockHeight` | number | Height of the block that contains the event. | +| `blockTimestamp` | string | The timestamp of when the block was sealed in a `DateString` format. eg. `'2021-06-25T13:42:04.227Z'` | +| `type` | [EventName](#eventname) | A string containing the event name. | +| `transactionId` | string | Can be used to query transaction information, eg. via a Flow block explorer. | +| `transactionIndex` | number | Used to prevent replay attacks. | +| `eventIndex` | number | Used to prevent replay attacks. | +| `data` | any | The data emitted from the event. | +| `accountAddress` | [Address](#address) | The address of the account where the status change occurred. | + ### `Transaction Statuses` The status of a transaction will depend on the Flow blockchain network and which phase it is in as it completes and is finalized. @@ -2261,9 +2275,9 @@ interface SubscriptionParams { | `"blocks"` | [`SubscriptionArgs<"blocks">`](#blocks-blockheaders-blockdigests) | [`Block`](#blockobject) | | `"block_headers"` | [`SubscriptionArgs<"block_headers">`](#blocks-blockheaders-blockdigests) | [`BlockHeader`](#blockheaderobject) | | `"block_digests"` | [`SubscriptionArgs<"block_digests">`](#blocks-blockheaders-blockdigests) | [`BlockDigest`](#blockdigestobject) | -| `"account_statuses"` | [`SubscriptionArgs<"account_statuses">`](#accountstatuses) | [`AccountStatus`] | +| `"account_statuses"` | [`SubscriptionArgs<"account_statuses">`](#accountstatuses) | [`AccountStatusEvent`](#account-status-event-object) | | `"transaction_statuses"`| [`SubscriptionArgs<"transaction_statuses">`](#transaction-statuses-2) | [`TransactionStatus`](#transactionstatusobject) | -| `"events"` | [`SubscriptionArgs<"events">`](#events-2) | [`Event`] | +| [`"events"`](#event-object) | [`SubscriptionArgs<"events">`](#events-2) | [`Event`] | ### `SubscriptionTopic`