Flow Client Library (FCL) API Reference

Configuration

FCL has a mechanism that lets you configure various aspects of FCL. When you move from one instance of the Flow Blockchain to another (Local Emulator to Testnet to Mainnet) the only thing you should need to change for your FCL implementation is your configuration.

Setting Configuration Values

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.

Alternatively, you can set the config by passing a JSON object directly.

import * as fcl from "@onflow/fcl";

fcl
  .config() // returns the config instance
  .put("foo", "bar") // configures "foo" to be "bar"
  .put("baz", "buz"); // configures "baz" to be "buz"

// OR

fcl.config({
  foo: "bar",
  baz: "buz",
});

Getting Configuration Values

The config instance has an asynchronous get method. You can also pass it a fallback value.

import * as fcl from "@onflow/fcl";

fcl.config().put("foo", "bar").put("woot", 5).put("rawr", 7);

const FALLBACK = 1;

async function addStuff() {
  var woot = await fcl.config().get("woot", FALLBACK); // will be 5 -- set in the config before
  var rawr = await fcl.config().get("rawr", FALLBACK); // will be 7 -- set in the config before
  var hmmm = await fcl.config().get("hmmm", FALLBACK); // will be 1 -- uses fallback because this isnt in the config

  return woot + rawr + hmmm;
}

addStuff().then((d) => console.log(d)); // 13 (5 + 7 + 1)

Common Configuration Keys

Address replacement in scripts and transactions

Configuration keys that start with 0x will be used to find-and-replace their values in Cadence scripts and transactions input to FCL. Typically this is used to represent account addresses. Account addresses for the same contract will be different depending on the Flow network you're interacting with (eg. Testnet, Mainnet). This allows you to write your script or transaction once and not have to update code when you point your application at a different Flow network.

import * as fcl from "@onflow/fcl";

fcl
  .config()
  .put("accessNode.api", "https://rest-testnet.onflow.org")
  .put("0xFlowToken", "0x7e60df042a9c0868");

async function myScript() {
  return fcl.query({
    cadence: `
        import FlowToken from 0xFlowToken // will be replaced with 0xf233dcee88fe0abe because of the configuration

        pub fun main(): UFix64 { 
          return FlowToken.totalSupply  // arbitrary script that can access FlowToken interface
        }
      `,
  });
}

Example

import * as fcl from "@onflow/fcl";

fcl
  .config()
  .put("flow.network", "testnet")
  .put("accessNode.api", "https://rest-testnet.onflow.org")
  .put("discovery.wallet", "https://fcl-discovery.onflow.org/testnet/authn")
  .put("app.detail.title", "Test Harness")
  .put("app.detail.icon", "https://i.imgur.com/r23Zhvu.png")
  .put("0xFlowToken", "0x7e60df042a9c0868");

Wallet Interactions

These methods allows dapps to interact with FCL compatible wallets in order to authenticate the user and authorize transactions on their behalf.

⚠️These methods are async.

Methods

authenticate

⚠️This method can only be used in web browsers.

Calling this method will authenticate the current user via any wallet that supports FCL. Once called, FCL will initiate communication with the configured discovery.wallet endpoint which lets the user select a wallet to authenticate with. Once the wallet provider has authenticated the user, FCL will set the values on the current user object for future use and authorization.

Note

⚠️discovery.wallet value must be set in the configuration before calling this method. See FCL Configuration.

📣 The default discovery endpoint will open an iframe overlay to let the user choose a supported wallet.

Usage

import * as fcl from "@onflow/fcl";
fcl
  .config()
  .put("accessNode.api", "https://rest-testnet.onflow.org")
  .put("discovery.wallet", "https://fcl-discovery.onflow.org/testnet/authn");
// anywhere on the page
fcl.authenticate();

Note

⚠️ authenticate can also take a service returned from discovery with fcl.authenticate({ service }).

Examples

• Press Login: Live Kitty Items

unauthenticate

⚠️This method can only be used in web browsers.

Logs out the current user and sets the values on the current user object to null.

Note

⚠️The current user must be authenticated first.

Usage

import * as fcl from "@onflow/fcl";
fcl.config().put("accessNode.api", "https://rest-testnet.onflow.org");
// first authenticate to set current user
fcl.authenticate();
// ... somewhere else & sometime later
fcl.unauthenticate();
// fcl.currentUser.loggedIn === null

Examples

• React Hook to manage FCL authentication: Kitty-items

reauthenticate

⚠️This method can only be used in web browsers.

A convenience method that calls fcl.unauthenticate() and then fcl.authenticate() for the current user.

Note

⚠️The current user must be authenticated first.

Usage

import * as fcl from "@onflow/fcl";
// first authenticate to set current user
fcl.authenticate();
// ... somewhere else & sometime later
fcl.reauthenticate();
// logs out user and opens up login/sign-up flow

Examples

• React Hook to manage FCL authentication: Kitty-items

signUp

⚠️This method can only be used in web browsers.

A convenience method that calls and is equivalent to fcl.authenticate().

logIn

⚠️This method can only be used in web browsers.

A convenience method that calls and is equivalent to fcl.authenticate().

authz

A convenience method that produces the needed authorization details for the current user to submit transactions to Flow. It defines a signing function that connects to a user's wallet provider to produce signatures to submit transactions.

📣 You can replace this function with your own authorization function if needed.

Returns

Usage

Note: The default values for proposer, payer, and authorizations are already fcl.authz so there is no need to include these parameters, it is shown only for example purposes. See more on signing roles.

import * as fcl from "@onflow/fcl";
// login somewhere before
fcl.authenticate();
// once logged in authz will produce values
console.log(fcl.authz);
// prints {addr, signingFunction, keyId, sequenceNum} from the current authenticated user.

const txId = await fcl.mutate({
  cadence: `
    import Profile from 0xba1132bc08f82fe2
    
    transaction(name: String) {
      prepare(account: AuthAccount) {
        account.borrow<&{Profile.Owner}>(from: Profile.privatePath)!.setName(name)
      }
    }
  `,
  args: (arg, t) => [arg("myName", t.String)],
  proposer: fcl.authz, // optional - default is fcl.authz
  payer: fcl.authz, // optional - default is fcl.authz
  authorizations: [fcl.authz], // optional - default is [fcl.authz]
});

Current User

Holds the current user, if set, and offers a set of functions to manage the authentication and authorization of the user.

⚠️The following methods can only be used in web browsers.

Methods

currentUser.subscribe

The callback passed to subscribe will be called when the user authenticates and un-authenticates, making it easy to update the UI accordingly.

Arguments

Usage

import React, { useState, useEffect } from "react";
import * as fcl from "@onflow/fcl";

export function AuthCluster() {
  const [user, setUser] = useState({ loggedIn: null });
  useEffect(() => fcl.currentUser.subscribe(setUser), []); // sets the callback for FCL to use

  if (user.loggedIn) {
    return (
      <div>
        <span>{user?.addr ?? "No Address"}</span>
        <button onClick={fcl.unauthenticate}>Log Out</button> {/* once logged out in setUser(user) will be called */}
      </div>
    );
  } else {
    return (
      <div>
        <button onClick={fcl.logIn}>Log In</button>{" "}
        {/* once logged in setUser(user) will be called */}
        <button onClick={fcl.signUp}>Sign Up</button> {/* once signed up, setUser(user) will be called */}
      </div>
    );
  }
}

currentUser.snapshot

Returns the current user object. This is the same object that is set and available on fcl.currentUser.subscribe(callback).

Usage

// returns the current user object
const user = fcl.currentUser.snapshot();

// subscribes to the current user object and logs to console on changes
fcl.currentUser.subscribe(console.log);

currentUser.authenticate

Equivalent to fcl.authenticate.

currentUser.unauthenticate

Equivalent to fcl.unauthenticate.

currentUser.authorization

Equivalent to fcl.authz

currentUser.signUserMessage

A method to use allowing the user to personally sign data via FCL Compatible Wallets/Services.

⚠️ This method requires the current user's wallet to support a signing service endpoint. Currently, only Blocto is compatible with this feature by default.

Arguments

Returns

Usage

import * as fcl from "@onflow/fcl"

export const signMessage = async () => {
  const MSG = Buffer.from("FOO").toString("hex")
  try {
    return await currentUser.signUserMessage(MSG)
  } catch (error) {
    console.log(error)
  }
}

Discovery

discovery

Discovery abstracts away code so that developers don't have to deal with the discovery of Flow compatible wallets, integration, or authentication. Using discovery from FCL allows dapps to list and authenticate with wallets while having full control over the UI. Common use cases for this are login or registration pages.

(Alternatively, if you don't need control over your UI you can continue to use the discovery.wallet config value documented in the Quickstart for the simplest configuration.)

⚠️The following methods can only be used in web browsers.

Note

⚠️discovery.authn.endpoint value must be set in the configuration before calling this method. See FCL Configuration.

Suggested Configuration

If the Discovery endpoint is set in config, then you can iterate through authn services and pass the chosen service to authenticate to authenticate a user.

Usage

import "./config"
import { useState, useEffect } from "react"
import * as fcl from "@onflow/fcl"

function Component() {
  const [wallets, setWallets] = useState([])
  useEffect(() => fcl.discovery.authn.subscribe(res => setWallets(res.results)), [])

  return (
    <div>
      {wallets.map((wallet) => (
        <button
          key={wallet.provider.address}
          onClick={() => fcl.authenticate({ service: wallet })}
        >
          Login with {wallet.provider.name}
        </button>
      ))}
    </div>
  )
}

authn

More Configuration

By default, limited functionality services, like Ledger, require apps to opt-in in order to display to users. This is so users don't authenticate only to later find out certain services cannot complete certain actions. To enable specific limited functionality services in an application, use the discovery.authn.include property in your configuration with a value of an array of services you'd like your app to opt-in to displaying for users.

import { config } from "@onflow/fcl"

config({
  "discovery.authn.endpoint": "https://fcl-discovery.onflow.org/api/testnet/authn", // Endpoint set to Testnet
  "discovery.authn.include": ["0x9d2e44203cb13051"] // Ledger wallet address on Testnet set to be included
})

Wallet Addresses on Testnet and Mainnet

For more details on wallets, view the service list here.

discovery.authn.snapshot()

Return a list of authn services.

discovery.authn.subscribe(callback)

The callback sent to subscribe will be called with a list of authn services.

On-chain Interactions

📣 These methods can be used in browsers and NodeJS.

These methods allows dapps to interact directly with the Flow blockchain via a set of functions that currently use the Access Node API.

Methods

Query and Mutate Flow with Cadence

If you want to run arbitrary Cadence scripts on the blockchain, these methods offer a convenient way to do so without having to build, send, and decode interactions.

query

Allows you to submit scripts to query the blockchain.

Options

Pass in the following as a single object with the following keys.All keys are optional unless otherwise stated.

Returns

Usage

import * as fcl from "@onflow/fcl";

const result = await fcl.query({
  cadence: `
    pub fun main(a: Int, b: Int, addr: Address): Int {
      log(addr)
      return a + b
    }
  `,
  args: (arg, t) => [
    arg(7, t.Int), // a: Int
    arg(6, t.Int), // b: Int
    arg("0xba1132bc08f82fe2", t.Address), // addr: Address
  ],
});
console.log(result); // 13

Examples

• Additional Explanation

mutate

Allows you to submit transactions to the blockchain to potentially mutate the state.

⚠️When being used in the browser, fcl.mutate uses the built-in fcl.authz function to produce the authorization (signatures) for the current user. When calling this method from Node.js, you will need to supply your own custom authorization function.

Options

Pass in the following as a single object with the following keys. All keys are optional unless otherwise stated.

Returns

Usage

import * as fcl from "@onflow/fcl";
// login somewhere before
fcl.authenticate();

const txId = await fcl.mutate({
  cadence: `
    import Profile from 0xba1132bc08f82fe2
    
    transaction(name: String) {
      prepare(account: AuthAccount) {
        account.borrow<&{Profile.Owner}>(from: Profile.privatePath)!.setName(name)
      }
    }
  `,
  args: (arg, t) => [arg("myName", t.String)],
});

Examples

• Additional explanation
• Custom authorization function

verifyUserSignatures (Deprecated)

Use fcl.AppUtils.verifyUserSignatures

AppUtils

AppUtils.verifyUserSignatures

A method allowing applications to cryptographically verify a message was signed by a user's private key/s. This is typically used with the response from currentUser.signUserMessage.

Note

⚠️ fcl.config.flow.network or options override is required to use this api. See FCL Configuration.

Arguments

Returns

Usage

import * as fcl from "@onflow/fcl"

const verifySignatures = async (message, compositeSignatures) => {
  try {
    return await fcl.AppUtils.verifyUserSignatures(message, compositeSignatures)
  } catch (error) {
    console.log(error)
  }
}

Examples

• fcl-next-harness

AppUtils.verifyAccountProof

A method allowing applications to cryptographically prove that a user controls an on-chain account. 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 the user approves the signing of message data, they will return account-proof data and a signature(s) that can be used to prove a user controls an on-chain account. See proving-authentication documentaion for more details.

⚠️ fcl.config.flow.network or options override is required to use this api. See FCL Configuration.

Arguments

Returns

Usage

import * as fcl from "@onflow/fcl"

const accountProofData = {
  address: "0x123",
  nonce: "F0123"
  signatures: [{f_type: "CompositeSignature", f_vsn: "1.0.0", addr: "0x123", keyId: 0, signature: "abc123"}],
}

const isValid = await fcl.AppUtils.verifyAccountProof(
  "AwesomeAppId",
  accountProofData,
  {fclCryptoContract}
)

Examples

• fcl-next-harness

Query and mutate the blockchain with Builders

In some cases, you may want to utilize pre-built interactions or build more complex interactions than what the fcl.query and fcl.mutate interface offer. To do this, FCL uses a pattern of building up an interaction with a combination of builders, resolving them, and sending them to the chain.

⚠️Recommendation: Unless you have a specific use case that require usage of these builders, you should be able to achieve most cases with fcl.query({...options} or fcl.mutate({...options})

send

Sends arbitrary scripts, transactions, and requests to Flow.

This method consumes an array of builders that are to be resolved and sent. The builders required to be included in the array depend on the interaction that is being built.

Note

⚠️Must be used in conjuction with fcl.decode(response) to get back correct keys and all values in JSON.

Arguments

Returns

Usage

import * as fcl from "@onflow/fcl";

// a script only needs to resolve the arguments to the script
const response = await fcl.send([fcl.script`${script}`, fcl.args(args)]);
// note: response values are encoded, call await fcl.decode(response) to get JSON

// a transaction requires multiple 'builders' that need to be resolved prior to being sent to the chain - such as setting the authorizations.
const response = await fcl.send([
  fcl.transaction`
    ${transaction}
    `,
  fcl.args(args),
  fcl.proposer(proposer),
  fcl.authorizations(authorizations),
  fcl.payer(payer),
  fcl.limit(9999),
]);
// note: response contains several values (Cad)

Examples

• Getting a user account
• Getting the latest block
• Sending a transaction

decode

Decodes the response from fcl.send() into the appropriate JSON representation of any values returned from Cadence code.

Note

📣 To define your own decoder, see tutorial.

Arguments

Returns

Usage

import * as fcl from "@onflow/fcl";

// simple script to add 2 numbers
const response = await fcl.send([
  fcl.script`
        pub fun main(int1: Int, int2: Int): Int {
            return int1 + int2
        }
    `,
  fcl.args([
    fcl.arg(1, fcl.t.Int),
    fcl.arg(2, fcl.t.Int)
  ]),
]);

const decoded = await fcl.decode(response);

assert(3 === decoded);
assert(typeof decoded === "number");

Examples

• Getting a user account
• Getting the latest block
• Sending a transaction

Builders

These methods fill out various portions of a transaction or script template in order to build, resolve, and send it to the blockchain. A valid populated template is referred to as an Interaction.

⚠️These methods must be used with fcl.send([...builders]).then(fcl.decode)

Query Builders

getAccount

A builder function that returns the interaction to get an account by address.

⚠️Consider using the pre-built interaction fcl.account(address) if you do not need to pair with any other builders.

Arguments

Returns after decoding

Usage

import * as fcl from "@onflow/fcl";

// somewhere in an async function
// fcl.account is the same as this function
const getAccount = async (address) => {
  const account = await fcl.send([fcl.getAccount(address)]).then(fcl.decode);
  return account;
};

getBlock

A builder function that returns the interaction to get the latest block.

📣 Use with fcl.atBlockId() and fcl.atBlockHeight() when building the interaction to get information for older blocks.

⚠️Consider using the pre-built interaction fcl.latestBlock(isSealed) if you do not need to pair with any other builders.

Arguments

Returns after decoding

Usage

import * as fcl from "@onflow/fcl";

const latestSealedBlock = await fcl
  .send([
    fcl.getBlock(true), // isSealed = true
  ])
  .then(fcl.decode);

atBlockHeight

A builder function that returns a partial interaction to a block at a specific height.

⚠️Use with other interactions like fcl.getBlock() to get a full interaction at the specified block height.

Arguments

Returns

Usage

import * as fcl from "@onflow/fcl";

await fcl.send([fcl.getBlock(), fcl.atBlockHeight(123)]).then(fcl.decode);

atBlockId

A builder function that returns a partial interaction to a block at a specific block ID.

⚠️Use with other interactions like fcl.getBlock() to get a full interaction at the specified block ID.

Arguments

Returns

Usage

import * as fcl from "@onflow/fcl";

await fcl.send([fcl.getBlock(), fcl.atBlockId("23232323232")]).then(fcl.decode);

getBlockHeader

A builder function that returns the interaction to get a block header.

📣 Use with fcl.atBlockId() and fcl.atBlockHeight() when building the interaction to get information for older blocks.

Returns after decoding

Usage

import * as fcl from "@onflow/fcl";

const latestBlockHeader = await fcl
  .send([fcl.getBlockHeader()])
  .then(fcl.decode);

getEventsAtBlockHeightRange

A builder function that returns all instances of a particular event (by name) within a height range.

⚠️The block range provided must be from the current spork.

⚠️The block range provided must be 250 blocks or lower per request.

Arguments

Returns after decoding

Usage

import * as fcl from "@onflow/fcl";

const events = await fcl
  .send([
    fcl.getEventsAtBlockHeightRange(
      "A.7e60df042a9c0868.FlowToken.TokensWithdrawn",
      35580624,
      35580624
    ),
  ])
  .then(fcl.decode);

getEventsAtBlockIds

A builder function that returns all instances of a particular event (by name) within a set of blocks, specified by block ids.

⚠️The block range provided must be from the current spork.

Arguments

Returns after decoding

Usage

import * as fcl from "@onflow/fcl";

const events = await fcl
  .send([
    fcl.getEventsAtBlockIds("A.7e60df042a9c0868.FlowToken.TokensWithdrawn", [
      "c4f239d49e96d1e5fbcf1f31027a6e582e8c03fcd9954177b7723fdb03d938c7",
      "5dbaa85922eb194a3dc463c946cc01c866f2ff2b88f3e59e21c0d8d00113273f",
    ]),
  ])
  .then(fcl.decode);

getCollection

A builder function that returns all a collection containing a list of transaction ids by its collection id.

⚠️The block range provided must be from the current spork. All events emitted during past sporks is current unavailable.

Arguments

Returns after decoding

Usage

import * as fcl from "@onflow/fcl";

const collection = await fcl
  .send([
    fcl.getCollection(
      "cccdb0c67d015dc7f6444e8f62a3244ed650215ed66b90603006c70c5ef1f6e5"
    ),
  ])
  .then(fcl.decode);

getTransactionStatus

A builder function that returns the status of transaction in the form of a TransactionStatusObject.

⚠️The transactionID provided must be from the current spork.

📣 Considering subscribing to the transaction from fcl.tx(id) instead of calling this method directly.

Arguments

Returns after decoding

Returns

Usage

import * as fcl from "@onflow/fcl";

const status = await fcl
  .send([
    fcl.getTransactionStatus(
      "9dda5f281897389b99f103a1c6b180eec9dac870de846449a302103ce38453f3"
    ),
  ])
  .then(fcl.decode);

getTransaction

A builder function that returns a transaction object once decoded.

⚠️The transactionID provided must be from the current spork.

📣 Considering using fcl.tx(id).onceSealed() instead of calling this method directly.

Arguments

Returns after decoding

Returns

Usage

import * as fcl from "@onflow/fcl";

const tx = await fcl
  .send([
    fcl.getTransaction(
      "9dda5f281897389b99f103a1c6b180eec9dac870de846449a302103ce38453f3"
    ),
  ])
  .then(fcl.decode);

getEvents (Deprecated)

Use fcl.getEventsAtBlockHeightRange or fcl.getEventsAtBlockIds.

getLatestBlock (Deprecated)

Use fcl.getBlock.

getBlockById (Deprecated)

Use fcl.getBlock and fcl.atBlockId.

getBlockByHeight (Deprecated)

Use fcl.getBlock and fcl.atBlockHeight.

Utility Builders

These builders are used to compose interactions with other builders such as scripts and transactions.

⚠️Recommendation: Unless you have a specific use case that require usage of these builders, you should be able to achieve most cases with fcl.query({...options} or fcl.mutate({...options})

arg

A utility builder to be used with fcl.args[...] to create FCL supported arguments for interactions.

Arguments

Returns

Usage

import * as fcl from "@onflow/fcl";

await fcl
  .send([
    fcl.script`
      pub fun main(a: Int, b: Int): Int {
        return a + b
      }
    `,
    fcl.args([
      fcl.arg(5, fcl.t.Int), // a
      fcl.arg(4, fcl.t.Int), // b
    ]),
  ])
  .then(fcl.decode);

args

A utility builder to be used with other builders to pass in arguments with a value and supported type.

Arguments

Returns

Usage

import * as fcl from "@onflow/fcl";

await fcl
  .send([
    fcl.script`
      pub fun main(a: Int, b: Int): Int {
        return a + b
      }
    `,
    fcl.args([
      fcl.arg(5, fcl.t.Int), // a
      fcl.arg(4, fcl.t.Int), // b
    ]),
  ])
  .then(fcl.decode); // 9

Template Builders

⚠️**Recommended:** The following functionality is simplified by fcl.query({...options} or fcl.mutate({...options}) and is reccomended to use over the functions below.

script

A template builder to use a Cadence script for an interaction.

📣 Use with fcl.args(...) to pass in arguments dynamically.

Arguments

Returns

Usage

import * as fcl from "@onflow/fcl";

const code = `
  pub fun main(): Int {
    return 5 + 4
  }
`;
const answer = await fcl.send([fcl.script(code)]).then(fcl.decode);
console.log(answer); // 9

transaction

A template builder to use a Cadence transaction for an interaction.

⚠️Must be used with fcl.payer, fcl.proposer, fcl.authorizations to produce a valid interaction before sending to the chain.

📣 Use with fcl.args[...] to pass in arguments dynamically.

Arguments

Returns

Usage

import * as fcl from "@onflow/fcl";

const code = `
  pub fun main(): Int {
    return 5 + 4
  }
`;
const answer = await fcl.send([fcl.script(code)]).then(fcl.decode);
console.log(answer); // 9

Pre-built Interactions

These functions are abstracted short hand ways to skip the send and decode steps of sending an interaction to the chain. More pre-built interactions are coming soon.

account

A pre-built interaction that returns the details of an account from their public address.

Arguments

Returns

Usage

import * as fcl from "@onflow/fcl";
const account = await fcl.account("0x1d007d755706c469");

block

A pre-built interaction that returns the latest block (optionally sealed or not), by id, or by height.

Arguments

Returns

Usage

import * as fcl from "@onflow/fcl";
await fcl.block() // get latest finalized block
await fcl.block({sealed: true}) // get latest sealed block
await fcl.block({id: '0b1bdfa9ddaaf31d53c584f208313557d622d1fedee1586ffc38fb5400979faa'}) // get block by id
await fcl.block({height: 56481953}) // get block by height

latestBlock (Deprecated)

A pre-built interaction that returns the latest block (optionally sealed or not).

Arguments

Returns

Usage

import * as fcl from "@onflow/fcl";
const latestBlock = await fcl.latestBlock();

Transaction Status Utility

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.

Arguments

Returns

Usage

import * as fcl from "@onflow/fcl";

const [txStatus, setTxStatus] = useState(null);
useEffect(() => fcl.tx(txId).subscribe(setTxStatus));

Examples

• React Effect to get the transaction status on submit
• Example usage in Kitty Items app

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 for guide.

Arguments

Returns

Usage

import * as fcl from "@onflow/fcl";
// in some react component
fcl.events(eventName).subscribe((event) => {
  console.log(event)
})

Examples

• Flow-view-source example

Types, Interfaces, and Definitions

Builders

Builders are modular functions that can be coupled together with fcl.send([...builders]) to create an Interaction. The builders needed to create an interaction depend on the script or transaction that is being sent.

Interaction

An interaction is an object containing the information to perform an action on chain.This object is populated through builders and converted into the approriate access node API call. See the interaction object here. A 'partial' interaction is an interaction object that does not have sufficient information to the intended on-chain action. Multiple partial interactions (through builders) can be coupled to create a complete interaction.

CurrentUserObject

AuthorizationObject

This type conforms to the interface required for FCL to authorize transaction on behalf o the current user.

SignableObject

An object that contains all the information needed for FCL to sign a message with the user's signature.

AccountObject

The JSON representation of an account on the Flow blockchain.

Address

ArgumentObject

An argument object created by fcl.arg(value,type)

ArgumentFunction

An function that takes the fcl.arg function and fcl types t and returns an array of fcl.arg(value,type).

(arg, t) => Array<Arg>

Returns

Authorization Function

An authorization function must produce the information of the user that is going to sign and a signing function to use the information to produce a signature.

⚠️This function is always async.

📣 By default FCL exposes fcl.authz that produces the authorization object for the current user (given they are signed in and only on the browser). Replace this with your own function that conforms to this interface to use it wherever an authorization object is needed.

Returns

Usage

const authorizationFunction = async (account) => {
    // authorization function need to return an account
    const { address, keys } = account
    const tempId = `${address}-${keys[process.env.minterAccountIndex]}`;
    const keyId = Number(KEY_ID);
    let signingFunction = async signable => {
      return {
        keyId,
        addr: fcl.withPrefix(address),
        signature: sign(process.env.FLOW_MINTER_PRIVATE_KEY, signable.message), // signing function, read below
      }
    }
    return {
    ...account,
    address,
    keyId,
    tempId,
    signingFunction,
  }

Examples:

• Node.js Service using the service account to authorize a minter
• Detailed explanation

Signing Function

Consumes a payload and produces a signature for a transaction.

⚠️This function is always async.

📣 Only write your own signing function if you are writing your own custom authorization function.

Payload

Note: These values are destructed from the payload object in the first argument.

Returns

Usage

import * as fcl from "@onflow/fcl";
import { ec as EC } from "elliptic";
import { SHA3 } from "sha3";
const ec: EC = new EC("p256");

const produceSignature = (privateKey, msg) => {
  const key = ec.keyFromPrivate(Buffer.from(privateKey, "hex"));
  const sig = key.sign(this.hashMsg(msg));
  const n = 32;
  const r = sig.r.toArrayLike(Buffer, "be", n);
  const s = sig.s.toArrayLike(Buffer, "be", n);
  return Buffer.concat([r, s]).toString("hex");
};

const signingFunction = ({
  message, // The encoded string which needs to be used to produce the signature.
  addr, // The address of the Flow Account this signature is to be produced for.
  keyId, // The keyId of the key which is to be used to produce the signature.
  roles: {
    proposer, // A Boolean representing if this signature to be produced for a proposer.
    authorizer, // A Boolean representing if this signature to be produced for a authorizer.
    payer, // A Boolean representing if this signature to be produced for a payer.
  },
  voucher, // The raw transactions information, can be used to create the message for additional safety and lack of trust in the supplied message.
}) => {
  return {
    addr, // The address of the Flow Account this signature was produced for.
    keyId, // The keyId for which key was used to produce the signature.
    signature: produceSignature(message), // The hex encoded string representing the signature of the message.
  };
};

Examples:

• Node.js Service using the service account to authorize a minter
• Detailed explanation

TransactionObject

TransactionRolesObject

For more on what each transaction role means, see singing roles.

TransactionStatusObject

EventName

Contract

KeyObject

This is the JSON representation of a key on the Flow blockchain.

ProposalKeyObject

ProposalKey is the account key used to propose this transaction.

A proposal key references a specific key on an account, along with an up-to-date sequence number for that key. This sequence number is used to prevent replay attacks.

You can find more information about sequence numbers here: https://docs.onflow.org/concepts/transaction-signing/#sequence-numbers

BlockObject

The JSON representation of a key on the Flow blockchain.

BlockHeaderObject

The subset of the BlockObject containing only the header values of a block.

CollectionGuaranteeObject

A collection that has been included in a block.

CollectionObject

A collection is a list of transactions that are contained in the same block.

ResponseObject

The format of all responses in FCL returned from fcl.send(...). For full details on the values and descriptions of the keys, view here.

Event Object

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.

GRPC Statuses

The access node GRPC implementation follows the standard GRPC Core status code spec. View here.

FType

FCL arguments must specify one of the following support types for each value passed in.