From 9ce78b4b16cc18c20bced8d86ea16a2814a0866c Mon Sep 17 00:00:00 2001 From: cshannon1218 Date: Tue, 9 Dec 2025 16:01:09 -0600 Subject: [PATCH 1/3] fcl-js doc edits --- .../tools/clients/fcl-js/authentication.md | 33 +++-- .../tools/clients/fcl-js/configure-fcl.md | 55 ++++--- docs/build/tools/clients/fcl-js/discovery.md | 93 ++++++++---- docs/build/tools/clients/fcl-js/index.md | 139 +++++++++++------- .../tools/clients/fcl-js/installation.mdx | 8 +- .../clients/fcl-js/interaction-templates.mdx | 40 ++--- .../clients/fcl-js/proving-authentication.mdx | 38 ++--- docs/build/tools/clients/fcl-js/scripts.md | 31 ++-- .../tools/clients/fcl-js/transactions.md | 59 ++++---- .../tools/clients/fcl-js/user-signatures.md | 33 +++-- 10 files changed, 321 insertions(+), 208 deletions(-) diff --git a/docs/build/tools/clients/fcl-js/authentication.md b/docs/build/tools/clients/fcl-js/authentication.md index 4932ddd3cf..34f79213d7 100644 --- a/docs/build/tools/clients/fcl-js/authentication.md +++ b/docs/build/tools/clients/fcl-js/authentication.md @@ -1,23 +1,23 @@ # Authentication -Authentication in FCL is closely tied to the concept of `currentUser`. In fact, `fcl.authenticate` and `fcl.unauthenticate` are simply aliases for `fcl.currentUser.authenticate()` and `fcl.currentUser.unauthenticate()`, respectively. So, let’s take a closer look at `currentUser`. +Authentication in Flow Client Library (FCL) is closely tied to the concept of `currentUser`. In fact, `fcl.authenticate` and `fcl.unauthenticate` are simply aliases for `fcl.currentUser.authenticate()` and `fcl.currentUser.unauthenticate()`, respectively. So, let’s take a closer look at `currentUser`. -As an onchain app developer using FCL, the primary authentication functionalities revolve around: +As an onchain app developer who uses FCL, the primary authentication functionalities revolve around how to: -- Determining the `currentUser` and whether they are logged in. -- Logging a user in. -- Logging a user out. +- Determine the `currentUser` and whether they are logged in. +- Log a user in. +- Log a user out. -Due to the way FCL works, logging in and signing up are essentially the same process. +Due to the way FCL works, to log in and sign up are essentially the same process. -# Retrieving Information About the Current User +# Retriev information about the current user FCL provides two ways to get information about the current user: 1. **A promise-based method** that returns a snapshot of the user’s data. 2. **A subscription-based method** that triggers a callback function with the latest user information whenever it changes. -### Snapshot of the Current User +### Snapshot of the current user ```javascript import * as fcl from '@onflow/fcl'; @@ -37,14 +37,21 @@ const unsubscribe = fcl.currentUser.subscribe((currentUser) => { }); ``` -# Authenticating and Unauthenticating +# Authenticate and unauthenticate The TL;DR: Call `fcl.authenticate()` to log in and `fcl.unauthenticate()` to log out. -On Flow mainnet, no additional configuration is needed—your app’s users will go through the authentication process and be able to use any FCL-compatible wallet provider. +On Flow mainnet, no additional configuration is needed, because your app’s users will go through the authentication process and can use any FCL-compatible wallet provider. -During development, you’ll likely want to configure your app to use [`@onflow/dev-wallet`](https://github.com/onflow/fcl-dev-wallet). The [Quick Start](../../../../blockchain-development-tutorials/cadence/getting-started/index.md) guide will walk you through setting it up. +During development, you’ll likely want to configure your app to use [`@onflow/dev-wallet`]. The [Quick Start] guide will walk you through how to set it up. -We also recommend using the [FCL Discovery Service](discovery.md) to help users discover and connect to FCL-compatible wallets. +We also recommend that you use the [FCL Discovery Service] to help users discover and connect to FCL-compatible wallets. -Whether you're new to building onchain, or an established veteran, we’re here to help. If you run into any issues, reach out to us on [Discord](https://discord.gg/flow) — we’re happy to assist! +Whether you're new to building onchain, or an established veteran, we’re here to help. If you run into any issues, reach out to us on [Discord] — we’re happy to assist! + + + +[`@onflow/dev-wallet`]: https://github.com/onflow/fcl-dev-wallet +[Quick Start]: ../../../../blockchain-development-tutorials/cadence/getting-started/index.md +[FCL Discovery Service]: discovery.md +[Discord]: https://discord.gg/flow \ No newline at end of file diff --git a/docs/build/tools/clients/fcl-js/configure-fcl.md b/docs/build/tools/clients/fcl-js/configure-fcl.md index 271121277a..2c426d2b43 100644 --- a/docs/build/tools/clients/fcl-js/configure-fcl.md +++ b/docs/build/tools/clients/fcl-js/configure-fcl.md @@ -4,11 +4,12 @@ title: How to Configure FCL ## Configuration -FCL provides a mechanism to configure various aspects of its behavior. The key principle is that when switching between different Flow Blockchain environments (e.g., Local Emulator → Testnet → Mainnet), the only required change should be your FCL configuration. +Flow Client Library (FCL) provides a mechanism to configure various aspects of its behavior. The key principle is that when you switch between different Flow Blockchain environments (for example, Local Emulator → Testnet → Mainnet), the only required change should be your FCL configuration. -## Setting Configuration Values +## Set configuration values + +Values only need to be set once. We recommend that you do this once and as early in the life cycle as possible. -Values only need to be set once. We recommend doing this once and as early in the life cycle as possible. To set a configuration value, the `put` method on the `config` instance needs to be called, the `put` method returns the `config` instance so they can be chained. ```javascript @@ -20,11 +21,15 @@ fcl .put('baz', 'buz'); // configures "baz" to be "buz" ``` -> **Note**: For advanced use cases requiring scoped configuration, isolated client instances, or multi-tenancy support, see the [`createFlowClient` reference documentation](./packages-docs/fcl/createFlowClient.md). +:::info + +For advanced use cases that require scoped configuration, isolated client instances, or multi-tenancy support, see the [`createFlowClient` reference documentation]. -## Getting Configuration Values +::: -The `config` instance has an asynchronous `get` method. You can also pass it a fallback value incase the configuration state does not include what you are wanting. +## Get configuration values + +The `config` instance has an asynchronous `get` method. You can also pass it a fallback value in case the configuration state does not include what you want. ```javascript import * as fcl from '@onflow/fcl'; @@ -44,13 +49,13 @@ async function addStuff() { addStuff().then((d) => console.log(d)); // 13 (5 + 7 + 1) ``` -## Common Configuration Keys +## Common configuration keys -- `accessNode.api` -- Api URL for the Flow Blockchain Access Node you want to be communicating with. -- `app.detail.title` - **(INTRODUCED `@onflow/fcl@0.0.68`)** Your applications title, can be requested by wallets and other services. Used by WalletConnect plugin & Wallet Discovery service. -- `app.detail.icon` - **(INTRODUCED `@onflow/fcl@0.0.68`)** Url for your applications icon, can be requested by wallets and other services. Used by WalletConnect plugin & Wallet Discovery service. -- `app.detail.description` - **(INTRODUCED `@onflow/fcl@1.11.0`)** Your applications description, can be requested by wallets and other services. Used by WalletConnect plugin & Wallet Discovery service. -- `app.detail.url` - **(INTRODUCED `@onflow/fcl@1.11.0`)** Your applications url, can be requested by wallets and other services. Used by WalletConnect plugin & Wallet Discovery service. +- `accessNode.api` -- API URL for the Flow Blockchain Access Node you want to communicate with. +- `app.detail.title` - **(INTRODUCED `@onflow/fcl@0.0.68`)** Your applications title, can be requested by wallets and other services. Used by WalletConnect plugin and Wallet Discovery service. +- `app.detail.icon` - **(INTRODUCED `@onflow/fcl@0.0.68`)** URL for your applications icon, can be requested by wallets and other services. Used by WalletConnect plugin and Wallet Discovery service. +- `app.detail.description` - **(INTRODUCED `@onflow/fcl@1.11.0`)** Your applications description, can be requested by wallets and other services. Used by WalletConnect plugin and Wallet Discovery service. +- `app.detail.url` - **(INTRODUCED `@onflow/fcl@1.11.0`)** Your applications URL, can be requested by wallets and other services. Used by WalletConnect plugin and Wallet Discovery service. - `challenge.handshake` -- **(DEPRECATED `@onflow/fcl@0.0.68`)** Points FCL at the Wallet or Wallet Discovery mechanism. - `discovery.wallet` -- **(INTRODUCED `@onflow/fcl@0.0.68`)** Points FCL at the Wallet or Wallet Discovery mechanism. - `discovery.wallet.method` -- Describes which service strategy a wallet should use: `IFRAME/RPC`, `POP/RPC`, `TAB/RPC`, `HTTP/POST`, `EXT/RPC` @@ -58,14 +63,14 @@ addStuff().then((d) => console.log(d)); // 13 (5 + 7 + 1) - `fcl.limit` -- Specifies fallback compute limit if not provided in transaction. Provided as integer. - `flow.network` (recommended) -- **(INTRODUCED `@onflow/fcl@1.0.0`)** Used in conjunction with stored interactions and provides FCLCryptoContract address for `testnet` and `mainnet`. Possible values: `local`, `testnet`, `mainnet`. - `service.OpenID.scopes` - **(INTRODUCED `@onflow/fcl@0.0.68`)** Open ID Connect claims for Wallets and OpenID services. -- `walletconnect.projectId` -- **(INTRODUCED `@onflow/fcl@1.11.0`)** Your app's WalletConnect project ID. See [WalletConnect Cloud](https://cloud.walletconnect.com/sign-in) to obtain a project ID for your application. +- `walletconnect.projectId` -- **(INTRODUCED `@onflow/fcl@1.11.0`)** Your app's WalletConnect project ID. See [WalletConnect Cloud] to obtain a project ID for your application. - `walletconnect.disableNotifications` -- **(INTRODUCED `@onflow/fcl@1.13.0`)** Flag to disable pending WalletConnect request notifications within the application's UI. Default is `false`. -## Using Contracts in Scripts and Transactions +## Use contracts in scripts and transactions -### Address Replacement +### Address replacement -Configuration keys that start with `0x` will be replaced in FCL scripts and transactions, this allows you to write your script or transaction Cadence code once and not have to change it when you point your application at a difference instance of the Flow Blockchain. +Configuration keys that start with `0x` will be replaced in FCL scripts and transactions. This allows you to write your script or transaction Cadence code once and not have to change it when you point your application at a difference instance of the Flow Blockchain. ```javascript import * as fcl from '@onflow/fcl'; @@ -115,9 +120,9 @@ fcl .put('0xFlowToken', '0x7e60df042a9c0868'); ``` -### Using `flow.json` +### Use `flow.json` -A simpler way to import contracts in scripts and transactions is to use the `config.load` method to ingest your contracts from your `flow.json` file. This keeps the import syntax unified across tools and lets FCL figure out which address to use for what network based on the network provided in config. To use `config.load` you must first import your `flow.json` file and then pass it to `config.load` as a parameter. +A simpler way to import contracts in scripts and transactions is to use the `config.load` method to ingest your contracts from your `flow.json` file. This keeps the import syntax unified across tools and lets FCL figure out which address to use for what network based on the network provided in the config. To use `config.load` you must first import your `flow.json` file and then pass it to `config.load` as a parameter. ```javascript import { config } from '@onflow/fcl'; @@ -146,6 +151,16 @@ Then in your scripts and transactions, all you have to do is: import "HelloWorld" ``` -FCL will automatically replace the contract name with the address for the network you are using. +FCL will automatically replace the contract name with the address for the network you use. + +:::info + +Never put private keys in your `flow.json`. Instead, use the [key/location syntax] to separate your keys into a separate git ignored file. + +::: + + -> Note: never put private keys in your `flow.json`. You should use the [key/location syntax](../../flow-cli/flow.json/security.md) to separate your keys into a separate git ignored file. +[`createFlowClient` reference documentation]: ./packages-docs/fcl/createFlowClient.md +[WalletConnect Cloud]: https://cloud.walletconnect.com/sign-in +[key/location syntax]: ../../flow-cli/flow.json/security.md \ No newline at end of file diff --git a/docs/build/tools/clients/fcl-js/discovery.md b/docs/build/tools/clients/fcl-js/discovery.md index 8ba7966eef..c590364930 100644 --- a/docs/build/tools/clients/fcl-js/discovery.md +++ b/docs/build/tools/clients/fcl-js/discovery.md @@ -4,24 +4,28 @@ title: Wallet Discovery ## Wallet Discovery -Knowing all the wallets available to users on a blockchain can be challenging. FCL's Discovery mechanism relieves much of the burden of integrating with Flow compatible wallets and let's developers focus on building their dapp and providing as many options as possible to their users. +It's a challenge to know all the wallets available to users on a blockchain. Flow Client Library's (FCL) Discovery mechanism relieves much of the burden of Flow compatible wallet integration and lets developers focus on building their dApp and providing as many options as possible to their users. There are two ways an app can use Discovery: 1. The **UI version** which can be configured for display via iFrame, Popup, or Tab. 2. The **API version** which allows you to access authentication services directly in your code via `fcl.discovery.authn` method which we'll describe below. -## UI Version +## UI version -When authenticating via FCL using Discovery UI, a user is shown a list of services they can use to login. +When a user authenticates via FCL with Discovery UI, they receive a list of services they can use to login. ![FCL Default Discovery UI](./images/discovery.png) This method is the simplest way to integrate Discovery and its wallets and services into your app. All you have to do is configure `discovery.wallet` with the host endpoint for testnet or mainnet. -> **Note**: Opt-in wallets, like Ledger and Dapper Wallet, require you to explicitly state you'd like to use them. For more information on including opt-in wallets, [see these docs](./packages-docs/fcl/index.md#configuration). -> -> A [Dapper Wallet](https://meetdapper.com/developers) developer account is required. To enable Dapper Wallet inside FCL, you need to [follow this guide](https://docs.meetdapper.com/quickstart). +:::info + +Opt-in wallets, like Ledger and Dapper Wallet, require you to explicitly state you'd like to use them. For more information on how to include opt-in wallets, [see these docs]. + +A [Dapper Wallet] developer account is required. To turn on Dapper Wallet inside FCL, you need to [follow this guide]. + +::: ```javascript import { config } from '@onflow/fcl'; @@ -34,11 +38,11 @@ config({ Any time you call `fcl.authenticate` the user will be presented with that screen. -To change the default view from iFrame to popup or tab set `discovery.wallet.method` to `POP/RPC` (opens as a popup) or `TAB/RPC` (opens in a new tab). More info about service methods can be [found here](https://github.com/onflow/fcl-js/blob/9bce741d3b32fde18b07084b62ea15f9bbdb85bc/packages/fcl/src/wallet-provider-spec/draft-v3.md). +To change the default view from iFrame to popup or tab set `discovery.wallet.method` to `POP/RPC` (opens as a popup) or `TAB/RPC` (opens in a new tab). For more info about service methods, see [here]. ### Branding Discovery UI -Starting in version 0.0.79-alpha.4, dapps now have the ability to display app a title and app icon in the Discovery UI by setting a few values in their FCL app config. This branding provides users with messaging that has clear intent before authenticating to add a layer of trust. +As of version 0.0.79-alpha.4, dApps can now display an app title and app icon in the Discovery UI when you a few values in their FCL app config. This branding provides users with messaging that has clear intent before they authenticate to add a layer of trust. All you have to do is set `app.detail.icon` and `app.detail.title` like this: @@ -51,13 +55,15 @@ config({ }); ``` -**Note:** If these configuration options aren't set, Dapps using the Discovery API will still display a default icon and "Unknown App" as the title when attempting to authorize a user who is not logged in. It is highly recommended to set these values accurately before going live. +:::info + +If these configuration options aren't set, dApps that use the Discovery API will still display a default icon and "Unknown App" as the title when they attempt to authorize a user who is not logged in. We highly recommended that you set these values accurately before you go live. -## API Version +## API version If you want more control over your authentication UI, the Discovery API is also simple to use as it exposes Discovery directly in your code via `fcl`. -Setup still requires configuration of the Discovery endpoint, but when using the API it is set via `discovery.authn.endpoint` as shown below. +Setup still requires configuration of the Discovery endpoint, but when you use the API, it is set via `discovery.authn.endpoint` as shown below. ```javascript import { config } from '@onflow/fcl'; @@ -81,7 +87,7 @@ fcl.discovery.authn.subscribe(callback); fcl.discovery.authn.snapshot(); ``` -In order to authenticate with a service (for example, when a user click's "login"), pass the selected service to the `fcl.authenticate` method described here [in the API reference](./packages-docs/fcl/authenticate.md): +To authenticate with a service (for example, when a user click's "login"), pass the selected service to the `fcl.authenticate` method described in [the API reference]: ```jsx fcl.authenticate({ service }); @@ -134,7 +140,7 @@ Helpful fields for your UI can be found in the `provider` object inside of the s } ``` -## Network Configuration +## Network configuration ### Discovery UI URLs @@ -144,7 +150,7 @@ Helpful fields for your UI can be found in the `provider` object inside of the s | Testnet | `https://fcl-discovery.onflow.org/testnet/authn` | | Local | `https://fcl-discovery.onflow.org/local/authn` | -### Discovery API Endpoints +### Discovery API endpoints | Environment | Example | | ----------- | ---------------------------------------------------- | @@ -152,21 +158,29 @@ Helpful fields for your UI can be found in the `provider` object inside of the s | Testnet | `https://fcl-discovery.onflow.org/api/testnet/authn` | | Local | `https://fcl-discovery.onflow.org/api/local/authn` | -> Note: Local will return [Dev Wallet](https://github.com/onflow/fcl-dev-wallet) on emulator for developing locally with the default port of 8701. If you'd like to override the default port add ?port=0000 with the port being whatever you'd like to override it to. +:::info + +Local will return [Dev Wallet] on emulator for local development with the default port of 8701. If you'd like to override the default port, add `?port=0000` and set the port to whatever you'd like to override it to. + +::: + +## Other configuration -## Other Configuration +:::info -> Note: Configuration works across both UI and API versions of Discovery. +Configuration works across both UI and API versions of Discovery. -### Include Opt-In Wallets +::: -**Starting in FCL v0.0.78-alpha.10** +### Include opt-in wallets + +**Start in FCL v0.0.78-alpha.10** Opt-in wallets are those that don't have support for authentication, authorization, and user signature services. Or, support only a limited set of transactions. -You can include opt-in wallets using either **wallet UIDs** (recommended) or service account addresses: +You can include opt-in wallets with either **wallet UIDs** (recommended) or service account addresses: -**Using Wallet UIDs (Recommended):** +**Use wallet UIDs (recommended):** ```javascript import * as fcl from '@onflow/fcl'; @@ -179,7 +193,7 @@ fcl.config({ }); ``` -**Using Service Account Addresses:** +**Use service Aacount addresses:** ```javascript import * as fcl from '@onflow/fcl'; @@ -199,13 +213,13 @@ fcl.config({ | Dapper Wallet | `dapper-wallet` | 0xead892083b3e2c6c | 0x82ec283f88a62e65 | | Ledger | `ledger` | 0xe5cd26afebe62781 | 0x9d2e44203cb13051 | -To learn more about other possible configurations, check out the [Discovery Github Repo](https://github.com/onflow/fcl-discovery). +To learn more about other possible configurations, check out the [Discovery Github Repo]. -### Exclude Wallets +### Exclude wallets -To exclude wallets from FCL Discovery, you can use the `discovery.authn.exclude` configuration option. You can specify wallets using either **wallet UIDs** (recommended) or service account addresses: +To exclude wallets from FCL Discovery, you can use the `discovery.authn.exclude` configuration option. You can specify wallets with either **wallet UIDs** (recommended) or service account addresses: -**Using Wallet UIDs (Recommended):** +**Use wallet UIDs (recommended):** ```javascript import * as fcl from '@onflow/fcl'; @@ -218,7 +232,7 @@ fcl.config({ }); ``` -**Using Service Account Addresses:** +**Use service account addresses:** ```javascript import * as fcl from '@onflow/fcl'; @@ -231,7 +245,7 @@ fcl.config({ }); ``` -**Available Wallet UIDs** +**Available wallet UIDs** You can use any of the following wallet identifiers with `discovery.authn.include` or `discovery.authn.exclude`: @@ -243,11 +257,15 @@ You can use any of the following wallet identifiers with `discovery.authn.includ | Dapper Wallet | `dapper-wallet` | 0xead892083b3e2c6c | 0x82ec283f88a62e65 | Opt-in | | Ledger | `ledger` | 0xe5cd26afebe62781 | 0x9d2e44203cb13051 | Opt-in | -> **Note**: Default wallets appear in Discovery by default. Opt-in wallets must be explicitly included using `discovery.authn.include`. You can use either the wallet UID or the service account address for filtering. -> -> For the most up-to-date list of available wallets, see the [fcl-discovery wallet data](https://github.com/onflow/fcl-discovery/tree/master/data/wallets) in the official repository. +:::info + +Default wallets appear in Discovery by default. Opt-in wallets must be explicitly included with `discovery.authn.include`. You can use either the wallet UID or the service account address to filter. + +For the most up-to-date list of available wallets, see the [fcl-discovery wallet data] in the official repository. -### WalletConnect Configuration +::: + +### WalletConnect configuration To configure WalletConnect, add a WalletConnect project ID to the FCL config: @@ -258,3 +276,14 @@ fcl.config({ 'walletconnect.projectId': 'YOUR_WALLETCONNECT_PROJECT_ID', }); ``` + + + +[see these docs]: ./packages-docs/fcl/index.md#configuration +[Dapper Wallet]: https://meetdapper.com/developers +[follow this guide]: https://docs.meetdapper.com/quickstart +[here]: https://github.com/onflow/fcl-js/blob/9bce741d3b32fde18b07084b62ea15f9bbdb85bc/packages/fcl/src/wallet-provider-spec/draft-v3.md +[the API reference]: ./packages-docs/fcl/authenticate.md +[Dev Wallet]: https://github.com/onflow/fcl-dev-wallet +[Discovery Github Repo]: https://github.com/onflow/fcl-discovery +[fcl-discovery wallet data]: https://github.com/onflow/fcl-discovery/tree/master/data/wallets \ No newline at end of file diff --git a/docs/build/tools/clients/fcl-js/index.md b/docs/build/tools/clients/fcl-js/index.md index f2567b4779..ddaef601f0 100644 --- a/docs/build/tools/clients/fcl-js/index.md +++ b/docs/build/tools/clients/fcl-js/index.md @@ -6,29 +6,29 @@ sidebar_position: 3 :::info -If you're building a frontend, use the [React SDK](../../react-sdk/index.mdx). If you're familiar with Solidity and the EVM world, the [React SDK] is to wagmi as FCL is to viem. +If you want to build a frontend, use the [React SDK]. If you're familiar with Solidity and the EVM world, the [React SDK] is to wagmi as FCL is to viem. ::: ## What is FCL? -The **Flow Client Library (FCL) JS** is a package designed to facilitate interactions between dapps, wallets, and the Flow blockchain. It provides a standardized way for applications to connect with users and their wallets, **eliminating the need for custom integrations**. +The **Flow Client Library (FCL) JS** is a package designed to facilitate interactions between dApps, wallets, and the Flow blockchain. It provides a standardized way for applications to connect with users and their wallets, **eliminating the need for custom integrations**. ### Key Features: -- **Universal Wallet Support** Works seamlessly with all FCL-compatible wallets, making authentication simple. +- **Universal Wallet Support** Works seamlessly with all FCL-compatible wallets, which makes authentication simple. - **Secure Authentication** Standardized authentication flow ensures a smooth user experience. -- **Blockchain Interactions** Enables querying, mutating, and interacting with smart contracts on Flow. +- **Blockchain Interactions** Allows querying, mutating, and interacting with smart contracts on Flow. - **Full-Featured Utilities** Offers built-in functions to streamline blockchain development. - **Flexible Environment** Can run in both browser and server environments, though wallet interactions are browser-only. FCL was created to make building Flow-connected applications **easy, secure, and scalable** by defining **standardized communication patterns** between wallets, applications, and users. -For iOS, we also offer [FCL Swift](https://github.com/Outblock/fcl-swift). +For iOS, we also offer [FCL Swift]. --- -## Getting Started +## Get started ### Requirements @@ -36,7 +36,7 @@ For iOS, we also offer [FCL Swift](https://github.com/Outblock/fcl-swift). ### Installation -To use the FCL JS in your application, install using **yarn** or **npm** +To use the FCL JS in your application, install with **yarn** or **npm** ```shell npm i -S @onflow/fcl @@ -46,8 +46,7 @@ npm i -S @onflow/fcl yarn add @onflow/fcl ``` -#### Importing - +#### Import **ES6** ```js @@ -62,12 +61,12 @@ const fcl = require('@onflow/fcl'); --- -## FCL for Dapps +## FCL for dApps -#### Wallet Interactions +#### Wallet interactions -- _Wallet Discovery_ and _Sign-up/Login_: Onboard users with ease. Never worry about supporting multiple wallets. - Authenticate users with any [FCL compatible wallet](#current-wallet-providers). +- _Wallet Discovery_ and _Sign-up/Login_: Onboard users with ease. Never worry about how to support multiple wallets. + Authenticate users with any [FCL compatible wallet]. ```js // in the browser @@ -80,16 +79,20 @@ fcl.config({ fcl.authenticate(); ``` -> **Note**: For advanced configuration patterns including scoped clients and multi-tenancy, see the [`createFlowClient` reference documentation](./packages-docs/fcl/createFlowClient.md). +:::info + +For advanced configuration patterns including scoped clients and multi-tenancy, see the [`createFlowClient` reference documentation]. ![FCL Default Discovery UI](images/discovery.png) -> **Note**: A [Dapper Wallet](https://meetdapper.com/developers) developer account is required. +A [Dapper Wallet] developer account is required. -- _Interact with smart contracts_: Authorize transactions via the user's chosen wallet -- _Prove ownership of a wallet address_: Signing and verifying user signed data +- _Interact with smart contracts_: Authorize transactions via the user's chosen wallet. +- _Prove ownership of a wallet address_: Sign and verify user signed data. + +::: -#### Blockchain Interactions +#### Blockchain interactions - _Query the chain_: Send arbitrary Cadence scripts to the chain and receive back decoded values @@ -140,9 +143,9 @@ const txId = await fcl.mutate({ - Event polling - Custom authorization functions -## Typescript Support +## Typescript support -FCL JS supports TypeScript. If you need to import specific types, you can do so via the [@onflow/typedefs](https://github.com/onflow/fcl-js/tree/master/packages/typedefs) package. +FCL JS supports TypeScript. If you need to import specific types, you can do so via the [@onflow/typedefs] package. ```typescript import { CurrentUser } from '@onflow/typedefs'; @@ -158,63 +161,97 @@ const newUser: CurrentUser = { }; ``` -For all type definitions available, see [this file](https://github.com/onflow/fcl-js/blob/master/packages/typedefs/src/index.ts) +For all type definitions available, see [this file] ## Next Steps -- See the [Flow App Quick Start](../../../../blockchain-development-tutorials/cadence/getting-started/index.md). -- See the full [API Reference](./packages-docs/fcl/index.md) for all FCL functionality. -- Learn Flow's smart contract language to build any script or transactions: [Cadence](https://cadence-lang.org). -- Explore all of Flow [docs and tools](https://developers.flow.com). +- See the [Flow App Quick Start]. +- See the full [API Reference] for all FCL functionality. +- Learn Flow's smart contract language to build any script or transactions: [Cadence]. +- Explore all of Flow [docs and tools]. --- -## FCL for Wallet Providers +## FCL for wallet providers Wallet providers on Flow have the flexibility to build their user interactions and UI through a variety of ways: -- Front channel communication via Iframe, pop-up, tab, or extension -- Back channel communication via HTTP +- Front channel communication via Iframe, pop-up, tab, or extension. +- Back channel communication via HTTP. -FCL is agnostic to the communication channel and be configured to create both custodial and non-custodial wallets. This enables users to interact with wallet providers without needing to download an app or extension. +FCL is agnostic to the communication channel and be configured to create both custodial and non-custodial wallets. This allows users to interact with wallet providers without the need to download an app or extension. -The communication channels involve responding to a set of pre-defined FCL messages to deliver the requested information to the dapp. Implementing a FCL compatible wallet on Flow is as simple as filling in the responses with the appropriate data when FCL requests them. If using any of the front-channel communication methods, FCL also provides a set of [wallet utilities](https://github.com/onflow/fcl-js/blob/master/packages/fcl-core/src/wallet-utils/index.js) to simplify this process. +The communication channels involve responding to a set of pre-defined FCL messages to deliver the requested information to the dApp. To implement a FCL compatible wallet on Flow is as simple as filling in the responses with the appropriate data when FCL requests them. If you use any of the front-channel communication methods, FCL also provides a set of [wallet utilities] to simplify this process. -### Current Wallet Providers +### Current wallet providers -- [Flow Wallet](https://wallet.flow.com/) -- [NuFi Wallet](https://nu.fi/) -- [Blocto](https://blocto.portto.io/en/) -- [Ledger](https://ledger.com) (limited transaction support) -- [Dapper Wallet](https://www.meetdapper.com/) +- [Flow Wallet] +- [NuFi Wallet] +- [Blocto] +- [Ledger] (limited transaction support) +- [Dapper Wallet] -### Wallet Discovery +### Wallet discovery -It can be difficult to get users to discover new wallets on a chain. To solve this, we created a [wallet discovery service](https://github.com/onflow/fcl-discovery) that can be configured and accessed through FCL to display all available Flow wallet providers to the user. This means: +It can be difficult to get users to discover new wallets on a chain. To solve this, we created a [wallet discovery service] that can be configured and accessed through FCL to display all available Flow wallet providers to the user. This means: -- Dapps can display and support all FCL compatible wallets that launch on Flow without needing to change any code -- Users don't need to sign up for new wallets - they can carry over their existing one to any dapp that uses FCL for authentication and authorization. +- dApps can display and support all FCL compatible wallets that launch on Flow without the need to change any code. +- Users don't need to sign up for new wallets - they can carry over their current one to any dApp that uses FCL for authentication and authorization. The discovery feature can be used via API allowing you to customize your own UI or you can use the default UI without any additional configuration. -> Note: To get your wallet added to the discovery service, make a PR in [fcl-discovery](https://github.com/onflow/fcl-discovery). +:::info + +To get your wallet added to the discovery service, make a PR in [fcl-discovery]. + +::: -### Building a FCL compatible wallet +### Build a FCL compatible wallet -- Read the [wallet guide](https://github.com/onflow/fcl-js/blob/master/packages/fcl-core/src/wallet-provider-spec/draft-v4.md) to understand the implementation details. -- Review the architecture of the [FCL dev wallet](https://github.com/onflow/fcl-dev-wallet) for an overview. -- If building a non-custodial wallet, see the [Account API](https://github.com/onflow/flow-account-api) and the [FLIP](https://github.com/onflow/flow/pull/727) on derivation paths and key generation. +- Read the [wallet guide] to understand the implementation details. +- Review the architecture of the [FCL dev wallet] for an overview. +- If you want to build a non-custodial wallet, see the [Account API] and the [FLIP] on derivation paths and key generation. --- -## 🛠 Want to Use the Flow SDK Directly? +## 🛠 Want to use the Flow SDK directly? -If you prefer to interact with Flow at a **lower level** without using FCL, you can use the [Flow JavaScript SDK](./packages-docs/sdk/index.md) directly. The SDK provides raw access to Flow's API for sending transactions, executing scripts, and managing accounts. +If you prefer to interact with Flow at a **lower level** without FCL, you can use the [Flow JavaScript SDK] directly. The SDK provides raw access to Flow's API to send transactions, execute scripts, and manage accounts. -FCL is built **on top of the Flow SDK**, making it easier to handle authentication, wallet interactions, and dapp connectivity. Choose the approach that best fits your use case. +FCL is built **on top of the Flow SDK**, which makes it easier to handle authentication, wallet interactions, and dApp connectivity. Choose the approach that best fits your use case. ## Support -- Notice a problem or want to request a feature? [Add an issue](https://github.com/onflow/fcl-js/issues). -- Join the Flow community on [Discord](https://discord.gg/flow) to keep up to date and to talk to the team. -- Read the [Contributing Guide](https://github.com/onflow/fcl-js/blob/master/CONTRIBUTING.md) to learn how to contribute to the project. +- Notice a problem or want to request a feature? [Add an issue]. +- Join the Flow community on [Discord] to keep up to date and to talk to the team. +- Read the [Contributing Guide] to learn how to contribute to the project. + + + +[React SDK]: ../../react-sdk/index.mdx +[FCL Swift]: https://github.com/Outblock/fcl-swift +[FCL compatible wallet]: #current-wallet-providers +[`createFlowClient` reference documentation]: ./packages-docs/fcl/createFlowClient.md +[Dapper Wallet]: https://meetdapper.com/developers +[@onflow/typedefs]: https://github.com/onflow/fcl-js/tree/master/packages/typedefs +[this file]: https://github.com/onflow/fcl-js/blob/master/packages/typedefs/src/index.ts +[Flow App Quick Start]: ../../../../blockchain-development-tutorials/cadence/getting-started/index.md +[API Reference]: ./packages-docs/fcl/index.md +[Cadence]: https://cadence-lang.org +[docs and tools]: https://developers.flow.com +[wallet utilities]: https://github.com/onflow/fcl-js/blob/master/packages/fcl-core/src/wallet-utils/index.js +[Flow Wallet]: https://wallet.flow.com/ +[NuFi Wallet]: https://nu.fi/ +[Blocto]: https://blocto.portto.io/en/ +[Ledger]: https://ledger.com +[Dapper Wallet]: https://www.meetdapper.com/ +[wallet discovery service]: https://github.com/onflow/fcl-discovery +[fcl-discovery]: https://github.com/onflow/fcl-discovery +[wallet guide]: https://github.com/onflow/fcl-js/blob/master/packages/fcl-core/src/wallet-provider-spec/draft-v4.md +[FCL dev wallet]: https://github.com/onflow/fcl-dev-wallet +[Account API]: https://github.com/onflow/flow-account-api +[FLIP]: https://github.com/onflow/flow/pull/727 +[Flow JavaScript SDK]: ./packages-docs/sdk/index.md +[Add an issue]: https://github.com/onflow/fcl-js/issues +[Discord]: https://discord.gg/flow +[Contributing Guide]: https://github.com/onflow/fcl-js/blob/master/CONTRIBUTING.md \ No newline at end of file diff --git a/docs/build/tools/clients/fcl-js/installation.mdx b/docs/build/tools/clients/fcl-js/installation.mdx index f0c2f2bfe1..657241d9a1 100644 --- a/docs/build/tools/clients/fcl-js/installation.mdx +++ b/docs/build/tools/clients/fcl-js/installation.mdx @@ -1,20 +1,20 @@ # Installation -This chapter explains the installation of the FCL JS library in your system. However, before moving to the installation, let us verify the prerequisite first. +This chapter explains the installation of the Flow CLient Library (FCL) JS library in your system. However, before we move to the installation, let's verify the prerequisite first. ## Prerequisite - Node.js version v12.0.0 or higher. -FCL JS depends on Node.js version v12.0.0 or higher. You can check your currently installed version using the below command: +FCL JS depends on Node.js version v12.0.0 or higher. You can check your currently-installed version with the below command: ```javascript node --version ``` -If Node.js is not installed on your system, you can download and install it by visiting [Node.js Download](https://nodejs.org/en/download/). +If Node.js is not installed on your system, you can visit [Node.js Download](https://nodejs.org/en/download/) to download and install it. -Install FCL JS using **npm** or **yarn** +Install FCL JS with **npm** or **yarn** ```shell npm i -S @onflow/fcl diff --git a/docs/build/tools/clients/fcl-js/interaction-templates.mdx b/docs/build/tools/clients/fcl-js/interaction-templates.mdx index c628a3fcb6..d3c2437ce0 100644 --- a/docs/build/tools/clients/fcl-js/interaction-templates.mdx +++ b/docs/build/tools/clients/fcl-js/interaction-templates.mdx @@ -12,23 +12,23 @@ title: Interaction Templates Interaction Templates establish a format for metadata that exists about an interaction. Interaction Templates can include: -- Human readable, internationalized messages about the interaction -- The Cadence code to carry out the interaction -- Information about arguments such as internationalized human readable messages and what the arguments act upon -- Contract dependencies the Interaction engages with, pinned to a version of them and their dependency tree +- Human readable, internationalized messages about the interaction. +- The Cadence code to carry out the interaction. +- Information about arguments such as internationalized human readable messages and what the arguments act upon. +- Contract dependencies the Interaction engages with, pinned to a version of them and their dependency tree. -Applications and Wallets can use Interaction Templates and it's interaction metadata. +Applications and Wallets can use Interaction Templates and its interaction metadata. -For example Applications and Wallets can extract the internationalized human readable messaging from an Interaction Template to display to their users prior to execution of the interaction. +For example, Applications and Wallets can extract the internationalized human readable messaging from an Interaction Template to display to their users prior to execution of the interaction. ## For Applications -FCL `mutate` and `query` can accept an Interaction Template. FCL `mutate` and `query` will use the Interaction Template to: +Flow Client Library (FCL) `mutate` and `query` can accept an Interaction Template. FCL `mutate` and `query` will use the Interaction Template to: -- Extract the Cadence code to carry out the interaction -- Extract dependency configuration for the interaction (eg: Information about contract import addresses) +- Extract the Cadence code to carry out the interaction. +- Extract dependency configuration for the interaction (for example, Information about contract import addresses) -Here is an example of using `mutate` with an Interaction Template: +Here is an example of how to use `mutate` with an Interaction Template: ```javascript import * as fcl from "@onflow/fcl" import myTransactionTemplate from "./my-transaction-template.template.json" @@ -63,11 +63,11 @@ const nftInfo = await fcl.query({ }) ``` -FCL will resolve the template from the remote location before using it to execute its underlying transaction or script. +FCL will resolve the template from the remote location before it uses it to execute its underlying transaction or script. -> 💡 By requesting an Interaction Template from an external location, applications have a mechanism to always retrieve the most up to date way of accomplishing an interaction. +> 💡 When apps use an Interaction Template from an external location, they have a mechanism to always retrieve the most up to date way of accomplishing an interaction. -By default FCL supports resolving Interaction Templates over http/https, but FCL can also be configured with various other ways to resolve Interaction Templates: +By default, FCL supports resolving Interaction Templates over http or https, but FCL can also be configured with various other ways to resolve Interaction Templates: ```javascript import * as fcl from "@onflow/fcl" @@ -85,11 +85,11 @@ const txId = await fcl.mutate({ ## For Wallets Wallets can use Interaction Templates to: -- Display internationalized human readable information about a transaction to their users during signing -- Verify the dependencies of an Interaction Template have not changed since when the Interaction Template was created -- Using Interaction Template Audits, gain confidence in the correctness and safety of an Interaction Template and it's underlying transaction +- Display internationalized human readable information about a transaction to their users during signing. +- Verify the dependencies of an Interaction Template have not changed since when the Interaction Template was created. +- With Interaction Template Audits, gain confidence in the correctness and safety of an Interaction Template and it's underlying transaction. -When recieving a transaction to sign, wallets can query for an Interaction Template that corresponds to it. +When wallets receive a transaction to sign, they can query for an Interaction Template that corresponds to it. Flow operates an "Interaction Template Discovery Service" which wallets can use to query for Interaction Templates. Anyone can run an "Interaction Template Discovery Service" and wallets can choose to query from any of them. @@ -118,9 +118,9 @@ const interactionTemplate = await fetch( > ❗️ Not all transactions will have a corresponding Interaction Template. Wallets are encouraged to always support signing transactions that do not have a corresponding Interaction Template, or if they fail to discover one. -Once a wallet has a corresponding Interaction Template for a given transaction, they may also may wish to verify that the transaction it represents is safe to sign, and that the Interaction Template is accurate for that transaction. +When a wallet has a corresponding Interaction Template for a given transaction, they may also may wish to verify that the transaction it represents is safe to sign, and that the Interaction Template is accurate for that transaction. -To do so, wallets can rely on themselves, along with external Interaction Template Auditors to gain confidence in the Interaction Template and it's underlying transaction. Interaction Template Auditors are entities that audit Interaction Templates for correctness and safety. +To do so, wallets can rely on themselves, along with external Interaction Template Auditors to gain confidence in the Interaction Template and its underlying transaction. Interaction Template Auditors are entities that audit Interaction Templates for correctness and safety. > 💡 Anyone can be an Interaction Template Auditor. Wallets can choose auditors they trust, if any. @@ -184,7 +184,7 @@ const hasDependencyTreeChanged = await fcl.InteractionTemplateUtils If the dependency tree has changed, wallets may choose to disregard the Interaction Template (and it's audits). -Once the Interaction Template has been sufficiently audited by auditors the wallet trusts, and it's dependency tree determined unchanged since the interaction was created and audited against, then the wallet can use the Interaction Template with greater confidence in it's correctness and safety. +After auditors that the wallet trusts sufficiently audits the Interaction Template, and it's dependency tree determined unchanged since the interaction was created and audited against, then the wallet can use the Interaction Template with greater confidence in its correctness and safety. The wallet may then decide to render human readable information about the transaction such as: - Internationalized 'title' and 'description' of the transaction diff --git a/docs/build/tools/clients/fcl-js/proving-authentication.mdx b/docs/build/tools/clients/fcl-js/proving-authentication.mdx index beb0e5c94f..3562f4b6cb 100644 --- a/docs/build/tools/clients/fcl-js/proving-authentication.mdx +++ b/docs/build/tools/clients/fcl-js/proving-authentication.mdx @@ -7,7 +7,7 @@ title: Proving Ownership of a Flow Account A common desire that application developers have is to be able to prove that a user controls an onchain account. Proving ownership of an onchain account is a way to authenticate a user with an application backend. Fortunately, -FCL provides a way to achieve this. +Flow Client Library (FCL) provides a way to achieve this. During user authentication, some FCL compatible wallets will choose to support the FCL `account-proof` service. If a wallet chooses to support this service, and @@ -20,7 +20,7 @@ authenticate a user. > Are you an FCL Wallet Developer? Check out the wallet provider specific docs > [here](https://github.com/onflow/fcl-js/blob/master/packages/fcl-core/src/wallet-provider-spec/provable-authn.md) -### Authenticating a user using `account-proof` +### Authenticate a user with `account-proof` In order to authenticate your users via a wallet provider's account-proof service, your application needs to configure FCL by setting `fcl.accountProof.resolver` and providing two pieces of information. @@ -59,11 +59,11 @@ config({ Here is the suggested order of operations of how your application might use the `account-proof` service: -- A user would like to authenticate via your application client using FCL. The process is triggered +- A user would like to authenticate via your application client with FCL. The process is triggered by a call to `fcl.authenticate()`. If `fcl.accountProof.resolver` is configured, FCL will attempt to retrieve the account proof data (`nonce`) and trigger your server to start a new account proof authentication process. -- Your application server generates a **minimum 32-byte random nonce** using a local source of entropy and +- Your application server generates a **minimum 32-byte random nonce** with a local source of entropy and sends it to the client. The server saves the challenge for future look-ups. - If FCL successfully retrieves the `account-proof` data, it continues the authentication process over a secure channel with the wallet. FCL includes the `appIdentifier` and `nonce` as part of the `FCL:VIEW:READY:RESPONSE` or HTTP POST request body. The `appIdentifier` @@ -119,7 +119,7 @@ The data within the `account-proof` service will look like this: **Verification** Your application can verify the signature against the data from `account-proof` -data using FCL's provided utility: +data with FCL's provided utility: ```js @@ -139,28 +139,28 @@ import { AppUtils } from "@onflow/fcl" ## Implementation considerations: -- The authentication assumes the Flow address is the identifier of the user's application account. - If an existing user doesn't have a Flow address in their profile, or if they decide to authenticate using - a Flow address different than the one saved in their profile, the user's account won't be found and the - process would consider a new user creating an account. It is useful for your application to consider - other authentication methods that allow an existing user to update the Flow address in their profile so +- The authentication assumes the Flow address is user's application account identifier. + If a current user doesn't have a Flow address in their profile, or if they decide to authenticate with + a Flow address different than the one saved in their profile, the system won't find the user's account and the + process considers a new user creating an account. It is useful for your application to consider + other authentication methods that allow a current user to update the Flow address in their profile so they are able to use FCL authentication. -- In the `account-proof` flow as described in this document, - the backend doesn't know the user's account address at the moment of generating a nonce. +- In the `account-proof` flow as this document describes, + the backend doesn't know the user's account address at the moment it generates a nonce. This results in the nonces not being tied to particular Flow addresses. The backend should enforce an expiry window for each nonce to avoid the pool of valid nonces from growing indefinitely. - Your application is encouraged to implement further mitigations against malicious attempts and + We encourage your application to implement further mitigations against malicious attempts and maintain a scalable authentication process. - FCL `account-proof` provides functionality to prove a user is in control of a Flow address. All other aspects of authentication, authorization and session management - are up to the application. There are many resources available for setting up secure user + are up to the application. There are many resources available to set up secure user authentication systems. Application developers should carefully consider what's best for their use case and follow industry best practices. -- It is important to use a secure source of entropy to generate the random nonces. The source should insure - nonces are not predictable by looking at previously generated nonces. Moreover, backend should use its own - local source and not rely on a publicly available source. Using a nonce of at least 32-bytes insures - it is extremely unlikely to have a nonce collision. -- The origin / `appIdentifier` is a tuple ⟨scheme, host, port⟩ computed per RFC 6454 (i.e. the value returned +- It is important to use a secure source of entropy to generate the random nonces. The source should look at + previously generated nonces to make sure that future nonces aren't predictible. Moreover, backend should use its own + local source and not rely on a publicly available source. Use a nonce of at least 32-bytes to try and prevent a + nonce collision. +- The origin / `appIdentifier` is a tuple ⟨scheme, host, port⟩ computed per RFC 6454 (that is, the value returned by window.location.origin in conforming user agents). Wallets will embed this origin into the RLP-encoded payload which is cryptographically signed. The resulting signature serves as an attestation that the authentication request originated from the specified application origin (which is known through verification with supporting Browser APIs) diff --git a/docs/build/tools/clients/fcl-js/scripts.md b/docs/build/tools/clients/fcl-js/scripts.md index dbfbccc393..d5c4a2992f 100644 --- a/docs/build/tools/clients/fcl-js/scripts.md +++ b/docs/build/tools/clients/fcl-js/scripts.md @@ -6,9 +6,9 @@ They always need to contain a `access(all) fun main()` function as an entry poin `fcl.query` is a function that sends Cadence scripts to the chain and receives back decoded responses. -The `cadence` key inside the object sent to the `query` function is a [JavaScript Tagged Template Literal](https://styled-components.com/docs/advanced#tagged-template-literals) that we can pass Cadence code into. +The `cadence` key inside the object sent to the `query` function is a [JavaScript Tagged Template Literal] that we can pass Cadence code into. -### Sending Your First Script +### Send your first script The following example demonstrates how to send a script to the Flow blockchain. This script adds two numbers and returns the result. @@ -26,13 +26,13 @@ const response = await fcl.query({ console.log(response) // 3 ``` -### A More Complex Script +### A more complex script -[Resources](https://cadence-lang.org/docs/language/resources) and [Structs](https://cadence-lang.org/docs/language/composite-types#structures) are complex data types that are fairly common place in Cadence. +[Resources] and [Structs] are complex data types that are fairly common place in Cadence. In the following code snippet, our script defines a struct called `Point`, it then returns a list of them. -The closest thing to a Structure in JavaScript is an object. In this case when we decode this response, we would be expecting to get back an array of objects, where the objects have an `x` and `y` value. +The closest thing to a Structure in JavaScript is an object. In this case when we decode this response, we would expect to get back an array of objects, where the objects have an `x` and `y` value. ```javascript import * as fcl from "@onflow/fcl" @@ -58,16 +58,15 @@ const response = await fcl.query({ console.log(response) // [{x:1, y:1}, {x:2, y:2}] ``` -### Transforming Data with Custom Decoders +### Transform data with custom decoders -In our app, we probably have a way of representing these Cadence values internally. In the above example it might be a `Point` class. +In our app, we probably have a way to represent these Cadence values internally. In the above example it might be a `Point` class. -FCL enables us to provide custom decoders that we can use to transform the data we receive from the Flow blockchain at the edge, before anything else in our dapp gets a chance to look at it. +FCL allows us to provide custom decoders that we can use to transform the data we receive from the Flow blockchain at the edge, before anything else in our dApp gets a chance to look at it. -We add these custom decoders by [Configuring FCL](./configure-fcl.md). -This lets us set it once when our dapp starts up and use our normalized data through out the rest of our dapp. +To add these custom decoders, we [configure FCL]. This lets us set it once when our dApp starts up and use our normalized data through out the rest of our dapp. -In the below example we will use the concept of a `Point` again, but this time, we will add a custom decoder, that enables `fcl.decode` to transform it into a custom JavaScript `Point` class. +In the below example, we will use the concept of a `Point` again, but this time, we will add a custom decoder, that allows `fcl.decode` to transform it into a custom JavaScript `Point` class. ```javascript import * as fcl from "@onflow/fcl" @@ -103,4 +102,12 @@ const response = await fcl.query({ console.log(response) // [Point{x:1, y:1}, Point{x:2, y:2}] ``` -To learn more about `query`, check out the [API documentation](./packages-docs/fcl/query.md). +To learn more about `query`, check out the [API documentation]. + + + +[JavaScript Tagged Template Literal]: https://styled-components.com/docs/advanced#tagged-template-literals +[Resources]: https://cadence-lang.org/docs/language/resources +[Structs]: https://cadence-lang.org/docs/language/composite-types#structures +[configure FCL]: ./configure-fcl.md +[API documentation]: ./packages-docs/fcl/query.md \ No newline at end of file diff --git a/docs/build/tools/clients/fcl-js/transactions.md b/docs/build/tools/clients/fcl-js/transactions.md index 47361312b9..7d454fae09 100644 --- a/docs/build/tools/clients/fcl-js/transactions.md +++ b/docs/build/tools/clients/fcl-js/transactions.md @@ -2,21 +2,20 @@ Transactions let you send Cadence code to the Flow blockchain that permanently alters its state. -We are assuming you have read the [Scripts Documentation](./scripts.md) before this, as transactions are sort of scripts with more required things. +We assume you have read the [Scripts Documentation]: ./scripts.md before this, as transactions are sort of scripts with more required things. -While `query` is used for sending scripts to the chain, `mutate` is used for building and sending transactions. Just like [scripts](./scripts.md), `fcl.mutate` is a [JavaScript Tagged Template Literal](https://styled-components.com/docs/advanced#tagged-template-literals) that we can pass Cadence code into. +While `query` is used to send scripts to the chain, `mutate` is used to build and send transactions. Just like [scripts], `fcl.mutate` is a [JavaScript Tagged Template Literal] that we can pass Cadence code into. Unlike scripts, they require a little more information, things like a proposer, authorizations and a payer, which may be a little confusing and overwhelming. -## Sending Your First Transaction +## Send your first transaction -There is a lot to unpack in the following code snippet. -It sends a transaction to the Flow blockchain. For the transaction, the current user is authorizing it as both the `proposer` and the `payer`. -Something that is unique to Flow is the one paying for the transaction doesn't always need to be the one performing the transaction. -Proposers and Payers are special kinds of authorizations that are always required for a transaction. -The `proposer` acts similar to the `nonce` in Ethereum transactions, and helps prevent repeat attacks. -The `payer` is who will be paying for the transaction. -If these are not set, FCL defaults to using the current user for all roles. +There is a lot to unpack in the following code snippet. It sends a transaction to the Flow blockchain. For the transaction, the current user authorizes it as both the `proposer` and the `payer`. + +Something that is unique to Flow is the one who pays for the transaction doesn't always need to be the one who performs the transaction. Proposers and Payers are special kinds of authorizations that are always required for a transaction. +- The `proposer` acts similar to the `nonce` in Ethereum transactions, and helps prevent repeat attacks. +- The `payer` is who will be paying for the transaction. +If these are not set, Flow Client Library (FCL) defaults to the current user for all roles. `fcl.mutate` will return a `transactionId`. We can pass the response directly to `fcl.tx` and then use the `onceExecuted` method which resolves a promise when a transaction result is available. @@ -40,15 +39,13 @@ const transaction = await fcl.tx(transactionId).onceExecuted(); console.log(transaction); // The transactions status and events after being executed ``` -## Authorizing a Transaction +## Authorize a transaction -The below code snippet is the same as the above one, except for one extremely important difference. -Our Cadence code this time has a prepare statement, and we are using the `fcl.currentUser` when constructing our transaction. +The below code snippet is the same as the above one, except for one extremely important difference. Our Cadence code this time has a prepare statement, and we use the `fcl.currentUser` when constructing our transaction. -The `prepare` statement's arguments directly map to the order of the authorizations in the `authorizations` array. -Four authorizations means four `&Account`s as arguments passed to `prepare`. In this case though there is only one, and it is the `currentUser`. +The `prepare` statement's arguments directly map to the order of the authorizations in the `authorizations` array. Four authorizations means four `&Account`s as arguments passed to `prepare`. In this case though there is only one, and it is the `currentUser`. -These authorizations are important as you can only access/modify an accounts storage if you have the said accounts authorization. +These authorizations are important as you can only access or modify an account's storage if you have that account's authorization. ```javascript import * as fcl from '@onflow/fcl'; @@ -74,21 +71,21 @@ const transaction = await fcl.tx(transactionId).onceExecuted(); console.log(transaction); // The transactions status and events after being executed ``` -To learn more about `mutate`, check out the [API documentation](./packages-docs/fcl/mutate.md). +To learn more about `mutate`, check out the [API documentation]. -## Querying Transaction Results +## Query transaction results -When querying transaction results (e.g., via HTTP/REST endpoints like `GET /v1/transaction_results/{id}`), you can provide either: -- A **transaction ID** (256-bit hash as hex string) -- A **scheduled transaction ID** (UInt64 as decimal string) +When you query transaction results (for example, via HTTP/REST endpoints like `GET /v1/transaction_results/{id}`), you can provide either: +- A **transaction ID** (256-bit hash as hex string). +- A **scheduled transaction ID** (UInt64 as decimal string). The returned result always includes `transaction_id` as the underlying native transaction ID. For scheduled transactions, this will be the system transaction ID that executed the scheduled callback. -Learn more about [Scheduled Transactions](/docs/build/cadence/advanced-concepts/scheduled-transactions.md). +Learn more about [Scheduled Transactions]. -## Transaction Finality +## Transaction finality -As of **FCL v1.15.0**, it is now recommended to use use `onceExecuted` in most cases, leading to a 2.5x reduction in latency when waiting for a transaction result. For example, the following code snippet should be updated from: +As of **FCL v1.15.0**, it is now recommended to use use `onceExecuted` in most cases, which leads to a 2.5x reduction in latency when you wait for a transaction result. For example, the following code snippet should be updated from: ```ts import * as fcl from '@onflow/fcl'; @@ -102,7 +99,7 @@ import * as fcl from '@onflow/fcl'; const result = await fcl.tx(txId).onceExecuted(); ``` -Developers manually subscribing to transaction statuses should update their listeners to treat "executed" as the final status (see the release notes [here](https://github.com/onflow/fcl-js/releases/tag/%40onflow%2Ffcl%401.15.0)). For example, the following code snippet should be updated from: +Developers who manually subscribe to transaction statuses should update their listeners to treat "executed" as the final status (see the [release notes]). For example, the following code snippet should be updated from: ```ts import * as fcl from '@onflow/fcl'; @@ -129,7 +126,7 @@ fcl.tx(txId).subscribe((txStatus) => { }); ``` -The "executed" status corresponds to soft finality, indicating that the transaction has been included in a block and a transaction status is available, backed by a cryptographic proof. Only in rare cases should a developer need to wait for "sealed" status in their applications and you can learn more about the different transaction statuses on Flow [here](../../../cadence/basics/transactions.md#transaction-status). +The "executed" status corresponds to soft finality, which indicates that the transaction has been included in a block and a transaction status is available, backed by a cryptographic proof. Only in rare cases should a developer need to wait for "sealed" status in their applications and you can learn more about the different transaction statuses on Flow [here]. See the following video for demonstration of how to update your code to wait for "executed" status: @@ -142,3 +139,13 @@ See the following video for demonstration of how to update your code to wait for allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen > + + + +[Scripts Documentation]: ./scripts.md +[scripts]: ./scripts.md +[JavaScript Tagged Template Literal]: https://styled-components.com/docs/advanced#tagged-template-literals +[API documentation]: ./packages-docs/fcl/mutate.md +[Scheduled Transactions]: /docs/build/cadence/advanced-concepts/scheduled-transactions.md +[release notes]: https://github.com/onflow/fcl-js/releases/tag/%40onflow%2Ffcl%401.15.0 +[here]: ../../../cadence/basics/transactions.md#transaction-status \ No newline at end of file diff --git a/docs/build/tools/clients/fcl-js/user-signatures.md b/docs/build/tools/clients/fcl-js/user-signatures.md index dfb4c28608..cca3746e56 100644 --- a/docs/build/tools/clients/fcl-js/user-signatures.md +++ b/docs/build/tools/clients/fcl-js/user-signatures.md @@ -2,29 +2,33 @@ title: Signing and Verifying Arbitrary Data --- -## Signing Arbitrary Data +## Signing and Verifying Arbitrary Data -Cryptographic signatures are a key part of the blockchain. They are used to prove ownership of an address without exposing its private key. While primarily used for signing transactions, cryptographic signatures can also be used to sign arbitrary messages. +Cryptographic signatures are a key part of the blockchain. They prove ownership of an address without exposing its private key. While primarily used to sign transactions, you can also use cryptographic signatures to sign arbitrary messages. -FCL has a feature that lets you send arbitrary data to a configured wallet/service where the user may approve signing it with their private key/s. +FCL has a feature that lets you send arbitrary data to a configured wallet or service. The user may approve signing it with their private keys. -## Verifying User Signatures +## Verify user signatures What makes message signatures more interesting is that we can use Flow blockchain to verify the signatures. Cadence has a built-in function `publicKey.verify` that will verify a signature against a Flow account given the account address. -FCL includes a utility function, `AppUtils.verifyUserSignatures`, for verifying one or more signatures against an account's public key on the Flow blockchain. +FCL includes a utility function, `AppUtils.verifyUserSignatures`, that verifies one or more signatures against an account's public key on the Flow blockchain. You can use both in tandem to prove a user is in control of a private key or keys. -This enables cryptographically-secure login flow using a message-signing-based authentication mechanism with a user’s public address as their identifier. +This allows cryptographically-secure login flow with a message-signing-based authentication mechanism with a user’s public address as their identifier. --- ## `currentUser.signUserMessage()` -A method to use allowing the user to personally sign data via FCL Compatible Wallets/Services. +A method that allows the user to personally sign data via FCL Compatible Wallets or Services. -> :Note: **Requires authentication/configuration with an authorized signing service.** +:::info + +> **Requires authentication/configuration with an authorized signing service.** + +::: ### Arguments @@ -36,7 +40,7 @@ A method to use allowing the user to personally sign data via FCL Compatible Wal | Type | Description | | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `Array` | An Array of [CompositeSignatures](https://github.com/onflow/fcl-js/blob/master/packages/fcl-core/src/wallet-provider-spec/draft-v2.md#compositesignature): {`addr`, `keyId`, `signature`} | +| `Array` | An Array of [CompositeSignatures]: {`addr`, `keyId`, `signature`} | #### Usage @@ -57,11 +61,13 @@ const signMessage = async () => { ## `AppUtils.verifyUserSignatures` -#### Note +:::info ⚠️ `fcl.config.flow.network` or options override is required to use this API. See [FCL Configuration](./configure-fcl.md). -A method allowing applications to cryptographically verify the ownership of a Flow account by verifying a message was signed by a user's private key/s. This is typically used with the response from `currentUser.signUserMessage`. +A method to verify that a user's private keys signed a message, which allows applications to cryptographically verify Flow account ownership. This is typically used with the response from `currentUser.signUserMessage`. + +::: ### Arguments @@ -107,3 +113,8 @@ A method allowing applications to cryptographically verify the ownership of a Fl Use cases include cryptographic login, message validation, verifiable credentials, and others. --- + + + +[FCL Configuration]: ./configure-fcl.md +[CompositeSignatures]: https://github.com/onflow/fcl-js/blob/master/packages/fcl-core/src/wallet-provider-spec/draft-v2.md#compositesignature \ No newline at end of file From b982196f59e86da0c377057299aaa85b5d2a8202 Mon Sep 17 00:00:00 2001 From: Brian Doyle Date: Thu, 11 Dec 2025 12:49:25 -0500 Subject: [PATCH 2/3] Apply suggestion from @briandoyle81 --- docs/build/tools/clients/fcl-js/authentication.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/build/tools/clients/fcl-js/authentication.md b/docs/build/tools/clients/fcl-js/authentication.md index 34f79213d7..4dc53f3811 100644 --- a/docs/build/tools/clients/fcl-js/authentication.md +++ b/docs/build/tools/clients/fcl-js/authentication.md @@ -10,7 +10,7 @@ As an onchain app developer who uses FCL, the primary authentication functionali Due to the way FCL works, to log in and sign up are essentially the same process. -# Retriev information about the current user +# Retrieve information about the current user FCL provides two ways to get information about the current user: From 1c1c2441041cd9f57c4ce324a573696ef1dd9f96 Mon Sep 17 00:00:00 2001 From: Brian Doyle Date: Thu, 11 Dec 2025 12:51:42 -0500 Subject: [PATCH 3/3] Apply suggestion from @briandoyle81 --- docs/build/tools/clients/fcl-js/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/build/tools/clients/fcl-js/index.md b/docs/build/tools/clients/fcl-js/index.md index ddaef601f0..acd1ebcb1b 100644 --- a/docs/build/tools/clients/fcl-js/index.md +++ b/docs/build/tools/clients/fcl-js/index.md @@ -12,7 +12,7 @@ If you want to build a frontend, use the [React SDK]. If you're familiar with So ## What is FCL? -The **Flow Client Library (FCL) JS** is a package designed to facilitate interactions between dApps, wallets, and the Flow blockchain. It provides a standardized way for applications to connect with users and their wallets, **eliminating the need for custom integrations**. +The **Flow Client Library (FCL) JS** is a package designed to facilitate interactions between apps, wallets, and the Flow blockchain. It provides a standardized way for applications to connect with users and their wallets, **eliminating the need for custom integrations**. ### Key Features: